flan/advanced-camera-card
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fccb4c9afd6ea5d86d330094f9efba90096c4eb3
advanced-camera-card/docs/configuration/cameras/README.md
T

41 KiB
Raw Blame History

Cameras

The cameras block configures a list of cameras the card should support. The first listed camera is the default.

cameras:
  - [...camera 0 (default camera)...]
  - [...camera 1...]
  - [...camera 2...]

The cameras_global block can be used to set defaults across multiple cameras.

cameras_global: [...]
Option Default Description
camera_entity The Home Assistant camera entity to use with the frigate live provider view. Also used to automatically detect the name of the underlying Frigate camera, and the title/icon of the camera.
capabilities Allows selective disabling of camera capabilities. See below.
cast Configuration that controls how this camera is "casted" / sent to media players. See below.
dependencies Other cameras that this camera should depend upon. See below.
dimensions Controls the dimensions and layout for media from this camera. See below.
engine auto The camera engine to use. If auto the card will attempt to choose the correct engine from the specified options. See Engine.
frigate Options for Frigate cameras. See Frigate camera engine configuration.
icon Autodetected from camera_entity if that is specified. The icon to use for this camera in the camera menu and in the next & previous controls when using the icon style.
id camera_entity, webrtc_card.entity or frigate.camera_name if set (in that preference order). An optional identifier to use throughout the card configuration to refer unambiguously to this camera. This id may be used in conditions, dependencies or custom actions to refer to a given camera unambiguously.
live_provider auto The choice of live stream provider. See Live Provider.
title Autodetected from camera_entity if that is specified. A friendly name for this camera to use in the card.
triggers Define what should cause this camera to update/trigger. See below.
webrtc_card The WebRTC entity/URL to use for this camera with the webrtc-card live provider. See below.

capabilities

The capabilities block allows selected disabling of auto-detected camera capabilities. This is rarely used, with substreams being a notable exception.

cameras:
  - camera_entity: camera.office
    capabilities: [...]
Option Default Description
disable A list of camera capabilities to disable. By default all capabilities supported by the camera are enabled.
disable_except A list of camera capabilities to leave enabled if supported. Everything else will be disabled.

Capabilities

Capability Purpose
clips Clips can be fetched from the camera.
favorite-events Events can be favorited.
favorite-recordings Recordings can be favorited.
live Live video can be received from the camera.
menu The camera should show up in the card camera menu.
ptz The camera can be PTZ controlled.
recordings Recordings can be fetched from the camera.
seek Clips can be seeked / scrubbed by the timeline.
snapshots Snapshots can be fetched from the camera.
substream The camera can be used as a substream on another camera.

cast

The cast block configures how a camera is cast / sent to media players.

cameras:
  - camera_entity: camera.office
    cast: [...]
Option Default Description
dashboard Configuration for the dashboard to cast. See below.
method standard Whether to use standard media casting to send the live view to your media player, or to instead cast a dashboard you have manually setup. Casting a dashboard supports a much wider variety of video media, including low latency video providers (e.g. go2rtc). This setting has no effect on casting non-live media.

See the dashboard method cast example.

Dashboard Configuration

cameras:
  - camera_entity: camera.office
    cast:
      dashboard: [...]
Option Default Description
dashboard_path A required field that specifies the name of the dashboard to cast. You can see this name in your HA URL when you visit the dashboard.
view_path A required field that specifies view/"tab" on that dashboard to cast. This is the value you have specified in the url field of the view configuration on the dashboard.

dependencies

The dependencies block configures other cameras as dependents of this camera. Dependent cameras have their media fetched and merged with this camera by default, and offer their respective live views as 'substreams' of the main (depended upon) camera. Configuration is under:

cameras:
  - camera_entity: camera.office
    dependencies: [...]
Option Default Description
all_cameras false Shortcut to specify all other cameras as dependent cameras.
cameras An optional list of other camera identifiers (see id parameter). If specified the card will fetch media for this camera and also recursively for the named cameras by default. Live views for the involved cameras will be available as 'substreams' of the main (depended upon) camera. All dependent cameras must themselves be a configured camera in the card. This can be useful to group events for cameras that are close together, to show multiple related live views, to always have clips/snapshots show fully merged events across all cameras or to show events for the birdseye camera that otherwise would not have events itself.

dimensions

The dimensions block configures the dimensions and layout of media of a given camera (see Card Dimensions to set the dimensions of the whole card and not just a single camera).

cameras:
  - camera_entity: camera.office
    dimensions: [...]
Option Default Description
aspect_ratio An optional aspect ratio for media from this camera which will be used in live or media viewer related views (e.g. clip, snapshot and recording). Format is the same as the parameter of the same name under the dimensions block (which controls dimensions for the whole card), e.g. 16 / 9.
layout How the media should be laid out within the camera dimensions. See below.

Layout Configuration

The layout block configures the fit and position of the media within the camera dimensions (in order to control the dimensions for the whole card see the card dimensions configuration ).

cameras:
  - camera_entity: camera.office
    dimensions:
      layout: [...]
Option Default Description
fit contain If contain, the media is contained within the card and letterboxed if necessary. If cover, the media is expanded proportionally (i.e. maintaining the media aspect ratio) until the camera/card dimensions are fully covered. If fill, the media is stretched to fill the camera/card dimensions (i.e. ignoring the media aspect ratio). See CSS object-fit for technical details and a visualization.
pan A dictionary that may contain an x and y percentage (0 - 100) to control the position of the media when "digitally zoomed in" (see zoom parameter). This can be effectively used to "pan"/cut the media shown. A value of 0 means maximally to the left or top of the media, a value of 100 means maximally to the right or bottom of the media. See visualizations below.
position A dictionary that may contain an x and y percentage (0 - 100) to control the position of the media when the fit is cover (for other values of fit this option has no effect). This can be effectively used to "pan"/cut the media shown. At any given time, only one of x and y will have an effect, depending on whether media width is larger than the camera/card dimensions (in which case x controls the position) or the media height is larger than the camera/card dimensions (in which case y controls the position). A value of 0 means maximally to the left or top of the media, a value of 100 means maximally to the right or bottom of the media. See CSS object-position for technicals. See visualizations below.
view_box A dictionary that may contain a top, bottom, left and right percentage (0 - 100) to precisely crop what part of the media to show by specifying a % inset value from each side. Browsers apply this cropping after position and fit have been applied. Unlike zoom, the user cannot dynamically zoom back out -- however the builtin media controls will work as normal. See visualizations below. Limited browser support:
zoom 1.0 A value between 1.0 and 10.0 inclusive that defines how much additional "digital zoom" to apply to this camera by default. Unlike with view_box the user can easily "zoom back out". Often used in conjuction with pan. When zoomed in the builtin browser media controls will automatically be disabled (as otherwise they would be enlarged also).

?> Layout operations are effectively applied in this order: fit, position, view_box, zoom then pan.

See media layout examples.

Layout Visualizations

fit

position: When media is shorter than dimensions height

position: When media is thinner than dimensions width

view_box: Precise media cropping

pan and zoom: Predefined panning and zooming

ptz

Configure the PTZ actions taken for a camera (not to be confused with configuration of the PTZ controls, see Live PTZ Controls or Media Viewer PTZ Controls). Manually configured actions override any auto-detected actions.

cameras:
  - camera_entity: camera.office
    ptz: [...]

Movement types

Generally PTZ cameras/integrations may support two kinds of PTZ actions:

  • relative: Single relative steps, e.g. "Pan to the left one step".
  • continuous: Separate start and stop, e.g. "Start panning to the left", following by a later command "Stop panning".

The card supports both, and with the help of the r2c_delay_between_calls_seconds and c2r_delay_between_calls_seconds can translate between them where necessary. See the ONVIF specification for more details on the distinction between relative and continuous.

The card UI (e.g. PTZ controls) will always try to call the continuous variety to allow for precise/smooth controls, and if unavailable will translate multiple relative steps with optional delays between each step. Manually configured actions may be configured to call either variety.

?> Frigate auto-detected PTZ actions will always be continuous as this is what the integration currently offers.

Parameters

Option Default Description
actions_left, actions_right, actions_up, actions_down, actions_zoom_in, actions_zoom_out, actions_home Set by camera engine of the selected camera The call-service action that will be called for each PTZ action for relative movements.
actions_left_start, actions_left_stop, actions_right_start, actions_right_stop,actions_up_start, actions_up_stop,actions_down_start, actions_down_stop,actions_zoom_in_start, actions_zoom_in_stop,actions_zoom_out_start, actions_zoom_out_stop Set by camera engine of the selected camera The call-service action that will be called for each PTZ action for continous movements. Both a _start and _stop variety must be provided for an action to be usable.
c2r_delay_between_calls_seconds 0.2 When the camera is configured with continuous actions only (e.g. left_start and left_stop, but not left), if something requests a relative action (e.g. a manually configured action), then start will be called, followed by a delay of this number of seconds and finally stop will be called. Cameras / integrations that are slower to respond to continuous steps may need to increase this value to avoid the continuous motion being too small. Cameras / integrations that are rapid to respond may need to decrease this value to avoid the "relative step" being too large.
data_left, data_right, data_up, data_down, data_zoom_in, data_zoom_out, data_home Shorthand for relative actions that call the service defined by the service parameter, with the data provided in this argument. Internally, this is just translated into the longer-form actions_[action]. If both actions_X and data_X are specified, actions_X takes priority. This is compatible with AlexxIT's WebRTC Card PTZ configuration.
data_left_start, data_left_stop, data_right_start, data_right_stop, data_up_start, data_up_stop, data_down_start, data_down_stop, data_zoom_in_start, data_zoom_in_stop, data_zoom_out_start, data_zoom_out_stop Shorthand for continuous actions that call the service defined by the service parameter, with the data provided in this argument. Internally, this is just translated into the longer-form actions_[action]_start and actions_[action]_stop. If both actions_X_* and data_X_* are specified, actions_X_* takes priority. This is compatible with AlexxIT's WebRTC Card PTZ configuration. Both a _start and _stop variety must be provided for an action to be usable.
presets PTZ preset actions. See below.
r2c_delay_between_calls_seconds 0.5 When the camera is configured with relative actions only (e.g. left but not left_start and left_stop), if something requests a continuous action (e.g. the card PTZ controls have a button held down), then a delay of this number of seconds will be inserted between each call of the relative action. Cameras / integrations that are slower to respond to relative steps may need to increase this value to avoid multiple simultaneous actions being sent. Cameras / integrations that are rapid to respond may need to decrease this value to increase the appearance of one single continuous motion.
service An optional Home Assistant service to call when the data_ parameters are used.

presets

Configures named PTZ presets. If a preset of this name is auto-detected, these configured actions will take precedence.

cameras:
  - camera_entity: camera.office
    ptz:
      presets:
        [preset_name]:
          ? [action]

[action] is any call-service action.

triggers

The triggers block configures what triggers a camera. Triggering can be used to activate an action (e.g. view a camera in live, reset the card to the default view). See view.triggers to control what happens when a camera is triggered.

cameras:
  - camera_entity: camera.office
    triggers: [...]
Option Default Description
entities Whether to not to trigger the camera when the state of any Home Assistant entity becomes active (i.e. state becomes on or open). This works for Frigate or non-Frigate cameras.
events [events, clips, snapshots] Whether to trigger the camera when events occur (whether or not media is available) or whenever updated clips or snapshots are detected. Detection support varies by camera engine.
motion false Whether to not to trigger the camera by automatically detecting and using the motion binary_sensor for this camera. This autodetection only works for Frigate cameras, and only when the motion binary_sensor entity has been enabled in Home Assistant.
occupancy false Whether to not to trigger the camera by automatically detecting and using the occupancy binary_sensor for this camera and its configured zones and labels. This autodetection only works for Frigate cameras, and only when the occupancy binary_sensor entity has been enabled in Home Assistant. If this camera has configured zones, only occupancy sensors for those zones are used -- if the overall camera occupancy sensor is also required, it can be manually added to entities. If this camera has configured labels, only occupancy sensors for those labels are used.

Fully expanded reference

cameras:
  - camera_entity: camera.front_Door
    live_provider: ha
    engine: auto
    frigate:
      url: http://my.frigate.local
      client_id: frigate
      camera_name: front_door
      labels:
       - person
      zones:
       - steps
    # Show events for camera-2 when this camera is viewed.
    dependencies:
      all_cameras: false
      cameras:
        - camera-2
    triggers:
      motion: false
      occupancy: true
      entities:
        - binary_sensor.front_door_sensor
    cast:
      method: standard
    dimensions:
      aspect_ratio: 16:9
      layout:
        fit: contain
        position:
          x: 50
          y: 50
  - camera_entity: camera.entrance
    live_provider: webrtc-card
    engine: auto
    frigate:
      url: http://my-other.frigate.local
      client_id: frigate-other
      camera_name: entrance
      labels:
       - car
      zones:
       - driveway
    icon: 'mdi:car'
    title: 'Front entrance'
    # Custom identifier for the camera to refer to it above.
    id: 'camera-2'
    webrtc_card:
      entity: camera.entrance_rtsp
      url: 'rtsp://username:password@camera:554/av_stream/ch0'
    triggers:
      motion: false
      occupancy: true
      entities:
        - binary_sensor.entrance_sensor
    dependencies:
      all_cameras: false
  - camera_entity: camera.sitting_room
    live_provider: go2rtc
    go2rtc:
      modes:
        - webrtc
        - mse
        - mp4
        - mjpeg
      stream: sitting_room
      url: 'https://my.custom.go2rtc.backend'
      cast:
        method: dashboard
        dashboard:
          dashboard_path: cast
          view_path: front-door
  - camera_entity: camera.sitting_room_webrtc_card
    live_provider: webrtc_card
    webrtc_card:
      # Arbitrary WebRTC Card options, see https://github.com/AlexxIT/WebRTC#configuration .
      entity: camera.sitting_room_rtsp
      ui: true
  - camera_entity: camera.kitchen
    live_provider: jsmpeg
    jsmpeg:
      options:
        audio: false
        video: true
        pauseWhenHidden: false
        disableGl: false
        disableWebAssembly: false
        preserveDrawingBuffer: false
        progressive: true
        throttled: true
        chunkSize: 1048576
        maxAudioLag: 10
        videoBufferSize: 524288
        audioBufferSize: 131072
  - camera_entity: camera.back_yard
    live_provider: image
    image:
      refresh_seconds: 1
  - camera_entity: camera.office_motioneye
    motioneye:
      images:
        directory_pattern: '%Y-%m-%d'
        file_pattern: '%H-%M-%S'
      movies:
        directory_pattern: '%Y-%m-%d'
        file_pattern: '%H-%M-%S'
  - camera_entity: camera.zoomed
    dimensions:
      layout:
        zoom: 2.0
        pan:
          x: 50
          y: 50
  - camera_entity: camera.manual-ptz
    ptz:
      c2r_delay_between_calls_seconds: 0.2
      r2c_delay_between_calls_seconds: 0.5
      # Relative action (only `left` shown)
      actions_left:
        action: call-service
        service: service.of_your_choice
        data:
          device: '048123'
          cmd: left
      # Continuous action (only `right` shown)
      actions_right_start:
        action: call-service
        service: service.of_your_choice
        data:
          device: '048123'
          cmd: right
          phase: start
      actions_right_stop:
        action: call-service
        service: service.of_your_choice
        data:
          device: '048123'
          phase: stop
      # Equivalent relative short form (only `up` shown)
      service: service.send_command
      data_up:
        device: '048123'
        cmd: up
      # Equivalent continuous short form (only `down` shown)
      service: service.send_command
      data_up_start:
        device: '048123'
        cmd: down
        phase: start
      data_up_stop:
        device: '048123'
        cmd: down
        phase: stop
      presets:
        # Preset using long form.
        armchair:
          action: call-service
          service: service.of_your_choice
          data:
            device: '048123'
            cmd: preset
            preset: armchair
        # Preset using short form.
        service: service.of_your_choice
        window:
          device: '048123'
          cmd: preset
          preset: window
cameras_global:
  live_provider: ha
Reference in New Issue View Git Blame Copy Permalink