Advanced Camera Card

repository·main·Indexed 22 days ago

https://github.com/dermotduffy/advanced-camera-card

A feature-rich Home Assistant Lovelace card for advanced camera management, live viewing, and event/media browsing, specifically optimized for Frigate users. It supports a wide range of custom actions via `custom:advanced-camera-card-action`, including camera selection, display mode switching, visual effects, media folder navigation, substream control, and both real and digital PTZ (Pan-Tilt-Zoom) movements.

Tokens
78.5K
Snippets
263
Records
333
Agent score
77%

What's inside advanced-camera-card

  1. Overview of Advanced Camera Card

    main

    Advanced Camera Card (formerly known as Frigate Card) is a comprehensive camera card designed for Home Assistant. It provides advanced viewing capabilities for multiple cameras, including live streams, event browsing, and media management.

    Key features include:

    • Live Viewing: Support for multiple camera streams.
    • Media Browsing: A mini-gallery for browsing clips and snapshots, with automatic updates to show the latest media.
    • Event Filtering: Filter events by specific zones and labels.
    • Entity Integration: Access arbitrary entities (such as motion sensors) via a menu.
    • Display Modes: Fullscreen mode, grid layouts, and carousel/swipeable media or camera views.
    • Media Interaction: Direct media downloads and thumbnail support.
    • Lovelace Integration: Supports visual editing and full Picture Elements support.
    • Theming: Fully theme-friendly for Home Assistant environments.
  2. Use the go2rtc Player in Advanced Camera Card

    main

    The go2rtc player is a modified version of the original go2rtc video player code, specifically adapted for integration within the Advanced Camera Card. It allows for high-performance video streaming by leveraging the go2rtc ecosystem.

    Note that this implementation is a derivative of the original code by Alexey Khit and is used to provide specialized video playback capabilities within the card's live view features.

  3. Use stock elements in Advanced Camera Card

    main

    The Advanced Camera Card supports several stock elements that follow the Home Assistant Picture Elements model. These elements can be overlaid on the camera background to display entity states, icons, images, or buttons.

    Available stock element types include:

    • conditional: Shows sub-elements based on specific entity states or conditions.
    • custom: Uses custom elements provided by the card (see Advanced Camera Card custom elements for details).
    • icon: Displays a static icon not linked to an entity state.
    • image: Overlays an image that can change based on entity state.
    • service-button: A button with text used to call a Home Assistant service.
    • state-badge: A badge representing an entity's state.
    • state-icon: Represents an entity state using an icon.
    • state-label: Represents an entity's state via text.

    Note: For detailed configuration of individual elements, refer to the Home Assistant Picture Elements documentation.

  4. Use `input_select` entities for camera remote control

    main

    To synchronize the camera selection between the card and an external entity, provide an input_select entity to the remote_control.entities.camera option.

    Behavior

    • Bidirectional Control: When you change the camera on the card, the input_select entity state is updated. Conversely, when the entity state changes, the card updates to show the corresponding camera.
    • Initialization: When the card starts, it automatically resets the input_select options to only include valid camera IDs available on the card. The card's initial camera selection will match the current state of the entity.
    • Requirement: The entity must be an input_select (e.g., input_select.your_entity_name).

    How to create a compatible entity

    If you don't have an entity ready, you can create one via the visual card editor:

    1. Go to Remote Control -> Remote Control Entities.
    2. Choose Create a new Dropdown helper.
    3. Provide an entity name (e.g., my_selected_camera) and an optional icon.
    4. Add at least one placeholder option (e.g., camera) and click Add (the card will overwrite these options with valid camera IDs upon startup).
    5. Click Create.
  5. Configure keyboard shortcuts and automations

    main

    There are two ways to handle keyboard input in the card:

    1. Modify Built-in Shortcuts: Use the keyboard_shortcuts configuration to change the default key bindings for the pre-defined shortcuts listed above.
    2. Create Custom Keyboard Automations: For any arbitrary action, you can configure it to run in response to keyboard input by setting up an automation. This allows you to trigger actions that do not have a pre-defined shortcut.
  6. Navigate folder hierarchies with `path` matchers and parsers

    main

    The path key allows you to navigate through a media hierarchy by defining a list of steps. Each step in the list represents a level in the folder structure.

    Matchers

    Use matchers to select specific sub-folders at a given level:

    • type: title: Matches a folder based on its display title. You can use a literal title string or a regexp with a named capture group (?<value>...) to extract data.
    • type: template: Uses a Jinja2-style template to match folders (e.g., matching today's date).
    • type: date: Matches folders based on date criteria using the since option.

    Parsers

    Use parsers to extract metadata (like dates and times) from folder names or filenames at a specific level:

    • type: startdate: Automatically detects and parses a start date/time from the name.
    • type: date: Extracts a date using a regexp and an optional format (e.g., yyyyMMdd-HHmmss).

    Example: Navigating a resolution -> date -> time hierarchy

    folders:
      - type: ha
        ha:
          url: /media-browser/browser/app%2Cmedia-source%3A%2F%2Freolink/playlist%2Cmedia-source%3A%2F%2Freolink%2FCAM%7C01J8XAATNH77WE5D654K07KY1F%7C0
          path:
            - matchers:
                - type: title
                  title: High resolution
            - parsers:
                - type: startdate
            - parsers:
                - type: startdate
  7. Understand the order of camera dimension applications

    main

    When configuring a camera, the dimensions settings are applied in a specific sequence to ensure predictable rendering:

    1. aspect_ratio: Defines the aspect ratio of the video player.
    2. fit, position, and view_box: Defines how the media is laid out within that aspect ratio.
    3. rotation: Determines if the video is rotated.
    4. zoom and pan: Defines the final zoom and pan settings applied to the view.
  8. Understand how actions work in Advanced Camera Card

    main

    Actions are pre-configured activities triggered by user interactions, such as tapping a menu icon, double-tapping an element, or holding down on a view.

    Unlike standard Home Assistant picture-elements actions, the Advanced Camera Card provides a superset of functionality. Key differences include:

    • Multiple Actions: You can define a list of actions for a single trigger, and all will be executed.
    • Special Tap Types: The card supports start_tap (when a touch/press begins) and end_tap (when a touch/release ends). This is particularly useful for PTZ cameras to start or stop movement based on touch duration.

    Note that network latency may cause slight imprecision between an end_tap event and the actual execution of the action.

  9. Use profiles to apply pre-configured defaults

    main

    Profiles allow you to apply sets of pre-configured default values to the Advanced Camera Card to simplify configuration.

    Key behaviors to note:

    • Precedence: Profiles are applied from top to bottom. If multiple profiles modify the same configuration option, the last profile in the list takes precedence (the last one "wins").
    • User Overrides: Profiles only change the default values. If a user has already manually set a specific option on a card, applying a profile may have no effect on that specific option.
    profiles:
      - [profile_1]
      - [profile_2]