Cameras
The cameras block configures a list of cameras the card should support. This block is optional. When present, 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 |
|---|---|---|
always_error_if_entity_unavailable |
false |
When true and when camera_entity is specified, attempting to live stream this camera will always error out if the entity state is unavailable, even if the live_provider does not actually need the camera_entity. |
camera_entity |
The Home Assistant camera entity. Used by most live providers for live stream data, and to auto-detect other camera metadata (e.g. Frigate camera name, camera title/icon). | |
capabilities |
Allows selective disabling of camera capabilities. See capabilities. |
|
cast |
Configuration that controls how this camera is "casted" / sent to media players. See cast. |
|
dependencies |
Other cameras that this camera should depend upon. See dependencies. |
|
dimensions |
Controls the dimensions and layout for media from this camera. See dimensions. |
|
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). If none of these are set, the camera has no id and cannot be referenced by name in conditions or actions. |
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. |
media |
Controls the default media configuration (e.g. thumbnails) for this camera. See media. |
|
proxy |
Controls whether/how content is proxied via hass-web-proxy-integration (must be installed separately). See proxy. |
|
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 triggers. |
|
webrtc_card |
The WebRTC entity/URL to use for this camera with the webrtc-card live provider. See Live Provider. |
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. | |
force |
A list of capabilities to force-enable instead of auto-detecting them. Currently only supports 2-way-audio. disable / disable_except take precedence over force. |
Capabilities
| Capability | Purpose |
|---|---|
clips |
Clips can be fetched from the camera. |
remote-control-entity |
The camera can be selected by a Camera Remote Control Entity. |
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. |
reviews |
Review items (alerts/detections) 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. |
trigger |
The camera can be triggered. |
2-way-audio |
The camera can be used for 2-way audio. |
Note
If using a camera only as a
substream, don't forget to keep both thesubstreamandptzcapabilities enabled if you wish to use PTZ controls for the substream.
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 Dashboard Configuration. | |
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. |
|
grid |
Grid layout configuration for this camera when displayed in grid mode. See Grid Configuration. | |
layout |
How the media should be laid out within the camera dimensions. See Layout Configuration. | |
rotation |
0 |
Rotates the camera clockwise by 0, 90, 180 or 270 degrees. |
Note
Use of
rotationcauses the browser to rotate the video player, unavoidably including rotating the builtin video controls on the player, which may be distracting or confusing (e.g. upside down controls). Builtin controls can be disabled using thelive.controls.builtinparameter. Rotation is not available in iOS fullscreen, due to the limited fullscreen support offered by that OS.
Tip
When rotation is configured, directional PTZ actions (
left,right,up,down) are automatically rotated to match the camera's orientation.
Warning
Rotating the camera incurs a rendering performance penalty. Always rotate "upstream" if possible (e.g. in your camera settings).
Grid Configuration
The grid block configures how this camera appears in grid display mode.
cameras:
- camera_entity: camera.office
dimensions:
grid:
width_factor: 2
| Option | Default | Description |
|---|---|---|
width_factor |
1 |
Width multiplier for this camera in grid mode (minimum: 0.1). When selected, width becomes width_factor * grid_selected_width_factor, capped at 100%. |
media
The media block configures the default media options for this camera which
defines which media is shown as thumbnails and on the timeline.
cameras:
- camera_entity: camera.office
media:
# [...]
| Option | Default | Description |
|---|---|---|
type |
auto |
The default media type to show for this camera. One of auto, events, recordings, reviews or folder. See Media Types for description of each. |
events_type |
all |
If type is events, what subtype of events to show. One of clips, snapshots or all (default). |
reviewed |
unreviewed |
Whether to filter the media based on review status. One of unreviewed (default, shows only unreviewed media), reviewed (shorts only reviewed media) or all (show regardless of whether reviewed or unreviewed). Only relevant when type is reviews or auto. |
folders |
An optional list of folder IDs to use when type is folder. If not specified, and type is folder, will default to showing the default (first) configured folder. See Folder Configuration and the worked example. |
Media Types
Not all camera engines support all media types. See Camera Engines for details.
| Type | Description |
|---|---|
events |
Typically represents an interesting event recorded from the camera, in either a video clip or image snapshot (see events_type parameter). |
recordings |
Typically represents continuous video recordings from the camera. |
reviews |
Typically represents an alert / detection of some kind that the user can review. |
folder |
Arbitrary media from a folder, e.g. a Home Assistant media folder. |
auto |
Automatically prioritize available media based on camera capabilities. Order of precedence: reviews > clips > snapshots > recordings. |
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 camera container/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. Note that if aspect_ratio is also set, this is controlling the behavior "within" that aspect-ratio, otherwise it's within the container for the camera (which is effectively the whole card for single card configurations). |
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). |
Note
Layout operations are effectively applied in this order:
fit,position,view_box,zoomthenpan.
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
Order of Operations
Camera dimensions settings are applied in this order:
aspect_ratiodefines the aspect ratio of the video player ...- ... then
fit,positionandview_boxdefines how the media is laid out within that ratio ... - ... then
rotationdefines whether the video is rotated ... - ... then
zoomandpandefine the zoom and pan settings respectively.
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.
When PTZ actions are manually set in the config, they will replace the
auto-detected actions. For example if actions_left is set for a Frigate
camera, it will be used for all left PTZ actions even though Frigate cameras
natively support continuous actions (actions_left_start, actions_left_stop).
Note
Frigate auto-detected PTZ actions will always be
continuousas 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 |
Set by camera engine of the selected camera | The perform-action 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 perform-action 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]. data_home is automatically converted into a home preset. If both actions_X and data_X are specified, actions_X takes priority. This is compatible with AlexxIT's WebRTC Card PTZ configuration. |
|
data_start_left, data_end_left, data_start_right, data_end_right, data_start_up, data_end_up, data_start_down, data_end_down, data_start_zoom_in, data_end_zoom_in, data_start_zoom_out, data_end_zoom_out |
Shorthand for continuous actions that call the service defined by the service parameter, with the data provided in this argument. Internally, data_start_* and data_end_* are translated into actions_*_start and actions_*_stop. If an equivalent actions_ key already exists, it takes priority. This uses AlexxIT's WebRTC Card key ordering. Both a data_start_ and data_end_ variety must be provided for an action to be usable. |
|
presets |
PTZ preset actions. See presets. |
|
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 presets are provided in the configuration, they will take precedence over auto-detected presets from the camera.
cameras:
- camera_entity: camera.office
ptz:
presets:
[preset_name]:
? [action]
[action] is any perform-action action.
Note
The 'Home' PTZ button (🏠) activates the first preset.
Warning
WebRTC Card's
data_long_*parameters are not supported.
proxy
Configures whether and how the content is proxied via hass-web-proxy-integration (this must be installed separately). This allows fetching media or live streams through the Home Assistant process itself, allowing the card to access resources it otherwise would not be able to directly access.
cameras:
- camera_entity: camera.office
proxy:
# [...]
For live streams, only the go2rtc live provider currently supports live stream proxying.
For media, not all engines benefit from proxying:
| Engine | Purpose of proxying |
|---|---|
frigate |
The Frigate integration already comes with a built-in proxy, so this functionality does not serve any purpose for frigate. |
reolink, motioneye |
May be used to fetch videos in cases where the browser may not be able to access the camera/NVR, or the camera/NVR may use a self-signed SSL certificate that your browser would otherwise reject due to mixed content. |
generic |
generic cameras do not have media, so proxying currently would serve no purpose. |
Proxying parameters:
| Option | Default | Description |
|---|---|---|
live |
auto |
Whether or not to proxy live streams. true to proxy (will show an error if the proxy integration is unavailable), false to not proxy, or auto to allow the camera engine to decide whether to proxy or not. If auto resolves to proxying, the card will still fall back to the original URL if the proxy integration is unavailable. Not all live providers support proxying live streams. |
media |
auto |
Whether or not to proxy media items. true to proxy (will show an error if the proxy integration is unavailable), false to not proxy, or auto to allow the camera engine to decide whether to proxy or not. If auto resolves to proxying, the card will still fall back to the original URL if the proxy integration is unavailable. |
dynamic |
true |
Whether to dynamically (at the time) request proxying of the required media item, or rely on statically user-configured pre-existing proxying. See the hass-web-proxy-integration documentation. |
ssl_verification |
auto |
Whether to verify the validity of SSL certificates. If true always verifies, if false never verifies and if auto the engine decides the best setting for that camera ecosystem. |
ssl_ciphers |
auto |
Whether to use default, intermediate, insecure or modern SSL ciphers. See the Home Assistant code for the precise list of SSL ciphers each implies. If auto the engine decides the best setting for that camera ecosystem. |
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.
Tip
A camera's
triggersare not the same as an automation'striggers. Camera triggers take action on per-camera events such as motion; automation triggers initiate automations. They share only the word "trigger".
cameras:
- camera_entity: camera.office
triggers:
# [...]
| Option | Default | Description |
|---|---|---|
doorbell |
false |
Whether to trigger the camera by automatically detecting an HA event.* entity with device_class: doorbell on the same HA device as the camera entity. Requires camera_entity to be set. |
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). |
|
events |
[] |
A list of Home Assistant bus events to trigger on, with optional payload filtering. Each entry subscribes to one HA event type and fires the camera trigger every time that event is dispatched (and the optional event_data filter matches). See events. |
media_events |
[] |
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. |
reviews |
Configuration for triggering on review items. Currently only supported by Frigate. See reviews. |
events
The events list subscribes the card to Home Assistant bus events. Each entry maps to a single event_type (e.g. zha_event, deconz_event, or any custom event your automations fire). Because events are momentary (HA fires them once, with no on/off), the card treats each fire as an instantaneous trigger; the visible "active" window is then controlled by view.triggers.event_hold_seconds.
cameras:
- camera_entity: camera.front_door
triggers:
events:
# Trigger only on a specific ZHA device firing its 'press' command.
- event_type: zha_event
event_data:
device_ieee: '00:11:22:33:44:55:66:77'
command: press
# No `event_data` filter -- triggers every time this event is fired.
- event_type: home_doorbell_pressed
| Option | Default | Description |
|---|---|---|
event_type |
The Home Assistant event type to subscribe to (e.g. zha_event, deconz_event, or a custom event name fired by one of your automations). Same field name and meaning as in HA automation YAML. May be a single string or a list of strings to match any of them. |
|
event_data |
Optional dictionary of key/value pairs the event's payload must contain for this entry to trigger. Mirrors Home Assistant's event_data matching exactly: the top-level keys you list must be present in the payload (extra payload keys are ignored), and nested objects are matched the same way -- list only the keys you care about and extra nested keys are ignored. Omit entirely to trigger on every fire of this event_type. |
|
context |
Optional filter on the event's context object. Recognised fields: id, user_id, parent_id. Each field may be a single value (equality) or a list (membership). All listed fields must match. |
[!TIP] Shared
event_typevalues likezha_eventanddeconz_eventfire for every device on that integration. Without anevent_datafilter the camera would trigger on any Zigbee/deCONZ device press in your home. Useevent_datato narrow down to the specific device you care about; you can copy values straight out of Developer tools → Events in Home Assistant.
reviews
The reviews block configures triggering based on review items (e.g., alerts and detections from Frigate).
cameras:
- camera_entity: camera.office
triggers:
reviews:
severities:
- high
description: true
| Option | Default | Description |
|---|---|---|
severities |
[high] |
An array of severity levels to trigger on. Possible values: high (equivalent to Frigate alerts), medium (equivalent to Frigate detections), low. At least one severity must be configured for review triggers to be active. |
description |
true |
Whether to trigger on review description updates (e.g. Frigate GenAI descriptions). Severity must also match. |
Fully expanded reference
See Engines and Live Providers for other options nested under cameras.
cameras:
- camera_entity: camera.front_Door
# 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
events:
- event_type: zha_event
event_data:
device_ieee: '00:11:22:33:44:55:66:77'
command: press
media_events:
- events
- clips
- snapshots
reviews:
severities:
- high
description: true
cast:
method: standard
dimensions:
aspect_ratio: 16:9
layout:
fit: contain
position:
x: 50
y: 50
always_error_if_entity_unavailable: false
- camera_entity: camera.entrance
icon: 'mdi:car'
title: 'Front entrance'
# Custom identifier for the camera to refer to it above.
id: 'camera-2'
triggers:
motion: false
occupancy: true
entities:
- binary_sensor.entrance_sensor
dependencies:
all_cameras: false
- 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: perform-action
perform_action: service.of_your_choice
data:
device: '048123'
cmd: left
# Continuous action (only `right` shown)
actions_right_start:
action: perform-action
perform_action: service.of_your_choice
data:
device: '048123'
cmd: right
phase: start
actions_right_stop:
action: perform-action
perform_action: 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: perform-action
perform_action: 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
- camera_entity: camera.needs_proxy
proxy:
live: auto
media: auto
dynamic: true
ssl_verification: auto
ssl_ciphers: auto
- camera_entity: camera.capabilities_reference
capabilities:
disable_except:
- clips
- favorite-events
- favorite-recordings
- live
- menu
- ptz
- recordings
- seek
- snapshots
- substream
- trigger
- 2-way-audio
disable:
# Capabilities to selectively disable.
- camera_entity: camera.rotated
dimensions:
rotation: 90
cameras_global:
triggers:
motion: false








