# `live` Configures the behavior of the `live` view. ```yaml live: # [...] ``` | Option | Default | Description | | ------------------------ | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `actions` | | [Actions](actions/README.md) to use for the `live` view. | | `auto_mute` | `[unselected, hidden, microphone, call]` | A list of conditions in which live camera feeds are muted. `unselected` will automatically mute when a camera is unselected in the carousel or grid. `hidden` will automatically mute when the camera becomes hidden (e.g. browser tab change). `microphone` will automatically mute after the microphone is muted as long as the camera stays selected (see the `live.microphone.mute_after_microphone_mute_seconds` to control how long after). `call` will automatically mute the inbound audio when an answered [two-way audio](../usage/2-way-audio.md) call ends. Use an empty list (`[]`) to never automatically mute. Note that if `auto_play` is enabled, the stream may mute itself automatically in order to honor the `auto_play` setting, as some browsers will not auto play media that is unmuted -- that is to say, where necessary, the `auto_play` parameter will take priority over the `auto_mute` parameter. | | `auto_pause` | `[]` | A list of conditions in which live camera feeds are automatically paused. `unselected` will automatically pause when a camera is unselected in the carousel or grid. `hidden` will automatically pause when the browser/tab becomes hidden. Use an empty list (`[]`) to never automatically pause. **Caution**: Some live providers (e.g. `jsmpeg`) may not offer human-accessible means to resume play if it is paused, unless the `auto_play` option is used. | | `auto_play` | `[selected, visible]` | A list of conditions in which live camera feeds are automatically played. `selected` will automatically play when a camera is selected in a carousel or grid. `visible` will automatically play when a camera becomes visible (e.g. browser tab change, or visible in a grid but not selected). Use an empty list (`[]`) to never automatically play. Some live providers (e.g. `webrtc-card`, `jsmpeg`) do not support the prevention of automatic play on initial load, but should still respect the value of this parameter on play-after-pause. | | `auto_unmute` | `[microphone, call]` | A list of conditions in which live camera feeds are unmuted. `selected` will automatically unmute when a camera is selected in a carousel or grid. `visible` will automatically unmute when a camera becomes visible (e.g. a browser/tab change, or visible in a grid but not selected). `microphone` will automatically unmute after the microphone is unmuted. `call` will automatically unmute the inbound audio when a [two-way audio](../usage/2-way-audio.md) call is answered (outbound calls are answered at start; inbound calls when the user accepts), so the caller can be heard. Use an empty list (`[]`) to never automatically unmute. Some browsers will not allow automated unmute until the user has interacted with the page in some way -- if the user has not then the browser may pause the media instead. | | `controls` | | Configuration for the `live` view controls. See [`controls`](#controls). | | `display` | | Controls whether to show a single or grid `live` view. See [`display`](#display). | | `draggable` | `true` | Whether or not the live carousel can be dragged left or right, via touch/swipe and mouse dragging. | | `lazy_load` | `true` | Whether or not to lazily load cameras in the camera carousel. Setting this to `false` will cause all cameras to load simultaneously when the `live` carousel is opened (or cause all cameras to load continually if `preload` is also `true`). This will result in a smoother carousel experience at a cost of (potentially) a substantial amount of continually streamed data. | | `lazy_unload` | `[]` | A list of conditions in which live camera feeds are unloaded. `unselected` will unload a camera when it is not visible in the carousel/grid and `hidden` will unload a camera when the browser itself is minimized or the browser tab changes. An empty list (`[]`, the default) will never automatically unload a stream once loaded unless the user navigates away entirely, so that it's always instantly visible on carousel scroll. Once unloaded, subsequently revisiting the camera will cause a reloading delay. Some live providers (e.g. `webrtc-card`) implement their own lazy unloading independently which may occur regardless of the value of this setting. | | `microphone` | | See [`microphone`](#microphone). | | `preload` | `false` | Whether or not to preload the live view. Preloading causes the live view to render in the background regardless of what view is actually shown, so it's instantly available when requested. The currently-selected camera's media is loaded in the background; other cameras follow the `lazy_load` setting (set `lazy_load: false` to preload them all). This consumes additional network/CPU resources continually. | | `show_image_during_load` | `true` | If `true`, during the initial stream load, the `image` live provider will be shown instead of the loading video stream. This still image will auto-refresh and is replaced with the live stream once loaded. | | `transition_effect` | `slide` | Effect to apply as a transition between live cameras. Accepted values: `slide` or `none`. | | `zoomable` | `true` | Whether or not the live carousel can be zoomed and panned, via touch/pinch and mouse scroll wheel with `ctrl` held. | ## `controls` Configure the controls for the `live` view. ```yaml live: controls: # [...] ``` | Option | Default | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | `builtin` | `true` | Whether to show the built in (browser) video controls on live video. | | `call` | | Configures the on-screen [two-way audio](../usage/2-way-audio.md) call controls. See [`call`](#call). | | `next_previous` | | Configures how the "Next & Previous" controls are shown on the `live` view. See [`next_previous`](#next_previous). | | `thumbnails` | | Configures how thumbnails are shown on the `live` view. See [`thumbnails`](#thumbnails). | | `timeline` | | Configures how the mini-timeline is shown on the `live` view. See [`timeline`](#timeline). | | `wheel` | `true` | Whether to allow mouse wheel to scroll through the carousel. | ### `call` Configures the on-screen controls shown during a [two-way audio](../usage/2-way-audio.md) call. The overlay appears whenever a call is in progress and offers buttons to answer calls (for inbound), end calls, mute/unmute the microphone and mute/unmute the inbound audio. ```yaml live: controls: call: # [...] ``` | Option | Default | Description | | ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `button_size` | `40` | The size of the call control buttons in pixels. Must be >= `20`. | | `enabled` | `true` | Whether the on-screen call controls are shown during a call. Set to `false` to hide them and drive calls from the [`menu`](./menu.md) instead. When hiding the controls, be sure to also remove `call` from `menu.auto_hide` so the menu stays visible allowing the call to be controlled. See [Driving calls from the menu](../examples.md?id=driving-calls-from-the-menu) for a complete example. | | `lock` | `true` | Whether to lock the rest of the card controls/actions while a call is in progress. Prevents an accidental tap, swipe or action mid-call. Set to `false` to allow interactions regardless of call state. | | `ringtone` | | The audible chime played while an inbound call (e.g. one started by [`view.triggers.actions.trigger: call`](./view.md?id=trigger-action-configuration)) is ringing. Stops as soon as the call is answered or ended. Manual calls never ring. See [`ringtone`](#ringtone). | | `unanswered_timeout_seconds` | `60` | The number of seconds an inbound call may ring unanswered before it is automatically ended. The timer is cancelled the moment the call is answered. Set to `0` to disable the timeout. | > [!NOTE] Browser autoplay restrictions may prevent the ringtone from playing > until the page has received a user gesture (e.g. a tap or click). When that > happens no sound is produced and no error is shown. The underlying behavior is > documented in [MDN's Autoplay > guide](https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Autoplay). #### `ringtone` Configures the chime played while an inbound call is ringing. ```yaml live: controls: call: ringtone: # [...] ``` | Option | Default | Description | | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `chime` | Which ringtone to play. `chime` is the default two-note doorbell. `westminster` plays the four-note Westminster Quarters phrase. `arpeggio` plays three quick descending plucks. `melody` plays a I-V-I chord cadence. `custom` plays an audio file at `url` (e.g. an `.mp3` or any browser-supported URL). `none` disables the ringtone entirely (equivalent to leaving the call silent until answered). | | `url` | | Path to an audio file to use as the ringtone. Only honored when `type` is `custom`; ignored otherwise. If `type` is `custom` but no `url` is provided, no ringtone plays. | | `repeat` | `0` | Number of times the ringtone is played per inbound call. `0` loops indefinitely until the call is answered or ended. | ### `next_previous` Configures how the "Next & Previous" controls are shown on the live view. ```yaml live: controls: next_previous: # [...] ``` | Option | Default | Description | | ----------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto_hide` | `[call, casting]` | The conditions under which the next/previous controls auto-hide: a list of zero or more of `call` (a [two-way audio](../usage/2-way-audio.md) call is active) and `casting` (the card is being cast). Set to `[]` to disable. | | `size` | `48` | The size of the next/previous controls in pixels. Must be >= `20`. | | `style` | `chevrons` | When viewing live cameras, what kind of controls to show to move to the previous/next camera. Acceptable values: `chevrons`, `icons`, `none` . | ### `ptz` Configures the PTZ (Pan Tilt Zoom) controls. ```yaml live: controls: ptz: # [...] ``` | Option | Default | Description | | --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hide_home` | `false` | When `true` the Home and Presets buttons of the control are hidden | | `hide_pan_tilt` | `false` | When `true` the Pan & Tilt buttons of the control is hidden | | `hide_type` | `false` | When `true` the button that switches between `buttons` and `gestures` PTZ control types is hidden. This button is automatically hidden on cameras without physical PTZ support. | | `hide_zoom` | `false` | When `true` the Zoom button of the control is hidden | | `mode` | `auto` | If `on`, PTZ controls are always shown. If `off`, PTZ controls are never shown. If `auto`, PTZ controls are shown only for cameras with physical PTZ support. | | `orientation` | `horizontal` | Whether to show a `vertical` or `horizontal` PTZ control. | | `position` | `bottom-right` | Whether to position the control on the `top-left`, `top-right`, `bottom-left` or `bottom-right`. This may be overridden by using the `style` parameter to precisely control placement. | | `style` | | Optionally position and style the element using CSS. Similar to [Picture Element styling](https://www.home-assistant.io/dashboards/picture-elements/#how-to-use-the-style-object), except without any default, e.g. `left: 42%` | | `type` | `buttons` | The PTZ control type: `buttons` shows directional button controls, `gestures` enables drag, pinch, and scroll wheel to pan, tilt, and zoom. Gesture controls only function on cameras with physical PTZ support. | > [!WARNING] > PTZ control precision is affected by latency at multiple points: the command round-trip to the camera, the camera's own response time, and the delay before movement is visible in the live stream. Additionally, cameras that only support relative movement may move in non-smooth discrete steps, while continuous movement cameras may overshoot the intended position before a stop command arrives. To configure the PTZ _actions_ taken for a particular camera, see [Camera PTZ Settings](./cameras/README.md?id=ptz). ### `thumbnails` Configures how thumbnails are shown on the live view. ```yaml live: controls: thumbnails: # [...] ``` | Option | Default | Description | | ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | `none` | Whether to show the thumbnail carousel `below` the media, `above` the media, in a drawer to the `left` or `right` of the media or to hide it entirely (`none`). | | `show_details` | `false` | Whether to show event details (e.g. duration, start time, object detected, etc) alongside the thumbnail. | | `show_download_control` | `false` | Whether to show the download control on each thumbnail. | | `show_favorite_control` | `true` | Whether to show the favorite ('star') control on each thumbnail. | | `show_info_control` | `true` | Whether to show the info ('i') control on each thumbnail. | | `show_review_control` | `true` | Whether to show the review ('check') control on each thumbnail. | | `show_timeline_control` | `false` | Whether to show the timeline ('target') control on each thumbnail. | | `size` | `100` | The size of the thumbnails in the thumbnail carousel in pixels. Must be >= `75` and <= `300`. | ### `timeline` Configures how the mini-timeline is shown on the live view. ```yaml live: controls: timeline: # [...] ``` | Option | Default | Description | | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clustering_threshold` | `3` | The minimum number of overlapping events to allow prior to clustering/grouping them. Higher numbers cause clustering to happen less frequently. Depending on the timescale/zoom of the timeline, the underlying timeline library may still allow overlaps for low values of this parameter -- for a fully "flat" timeline use the `ribbon` style. `0` disables clustering entirely. Only used in the `stack` style of timeline. | | `format` | | Configuration for the timeline time & date format. See [`format`](#format). | | `mode` | `none` | Whether to show the thumbnail carousel `below` the media, `above` the media, in a drawer to the `left` or `right` of the media or to hide it entirely (`none`). | | `pan_mode` | `pan` | See [timeline pan mode](timeline-pan-mode.md). | | `show_recordings` | `true` | Whether to show recordings on the timeline (specifically: which hours have any recorded content). | | `style` | `ribbon` | Whether the timeline should show events as a single flat `ribbon` or a `stack` of events that are clustered using the `clustering_threshold`. | | `window_seconds` | `3600` | The length of the default timeline in seconds. By default, 1 hour (`3600` seconds) is shown in the timeline. | [](common/timeline-seek-info.md ':include') #### `format` Configure the date and time format for the `timeline` view. ```yaml live: controls: timeline: format: # [...] ``` | Option | Default | Description | | ------ | ------- | ------------------------------------------------------------------------------- | | `24h` | `true` | If `true` shows time in 24-hour clock. If `false` otherwise uses 12-hour clock. | ## `display` Controls whether to show a single or grid `live` view. ```yaml live: display: # [...] ``` | Option | Default | Description | | ---------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `grid_columns` | | If specified the grid will always have exactly this number of columns. | | `grid_max_columns` | `4` | If specified, and `grid_columns` is not specified, the grid will not render more than this number of columns. | | `grid_selected_position` | `default` | Controls where the selected item should be laid out in the grid. If `default`, the cameras are laid out in the order they are specified in the configuration and selecting a camera does not change this order. If `first`, the selected camera is moved to the start of the grid, if `last` it is moved to the end of the grid. | | `grid_selected_width_factor` | `2` | How much to scale up the selected media item in a grid. A value of `1` will not scale the selected item at all, the default value of `2` will scale the media item width to twice what it would otherwise be, etc. | | `mode` | `single` | Whether to display a `single` live camera in a carousel, or all cameras in a `grid` configuration. | See the [grid layout algorithm](grid-layout-algorithm.md) for more details on how the grid lays elements out. ## `microphone` Controls the behavior of the microphone in the `live` view. ```yaml live: microphone: ``` | Option | Default | Description | | ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `always_connected` | `false` | Whether or not to keep the microphone connected while the card is running. By default the microphone is connected when a [two-way audio](../usage/2-way-audio.md) call needs it and disconnected when that call ends. Setting this to `true` connects it at card load and never disconnects it, which avoids the connection setup on the first call at the cost of the browser reporting the microphone as in use for as long as the card is running. | | `auto_mute` | `[]` | A list of conditions in which the microphone is muted. `hidden` will automatically mute the microphone when the card becomes hidden (e.g. browser/tab change, or the card scrolling out of view). Use an empty list (`[]`, the default) to never automatically mute the microphone this way. The microphone is always muted when a call ends. | | `auto_unmute` | `[]` | A list of conditions in which the microphone is unmuted. `call` will automatically unmute the microphone when a [two-way audio](../usage/2-way-audio.md) call is started (or answered for inbound calls). `visible` will automatically unmute the microphone when the card becomes visible again. By default this list is empty, so the microphone stays muted even after answering (push-to-talk) -- tap the microphone button in the call overlay to talk. Unmuting only has an effect during a call: at any other time nothing can carry the audio, so the request is ignored. | | `mute_after_microphone_mute_seconds` | `60` | The number of seconds after the microphone mutes to automatically mute the inbound audio when `live.auto_mute` includes `microphone`. | See [Using 2-way audio](../usage/2-way-audio.md) for more information about the very particular requirements that must be followed for 2-way audio to work. ## Fully expanded reference [](common/expanded-warning.md ':include') ```yaml live: auto_play: - selected - visible auto_pause: [] auto_mute: - unselected - hidden - microphone - call auto_unmute: - microphone - call preload: false lazy_load: true lazy_unload: [] draggable: true zoomable: true transition_effect: slide controls: builtin: true call: button_size: 40 lock: true ringtone: type: chime repeat: 0 unanswered_timeout_seconds: 60 next_previous: auto_hide: - call - casting style: chevrons size: 48 wheel: true ptz: mode: auto position: bottom-right orientation: horizontal hide_pan_tilt: false hide_zoom: false hide_home: false hide_type: false type: buttons style: # Optionally override the default style. right: 5% thumbnails: size: 100 show_details: false show_download_control: false show_favorite_control: true show_info_control: true show_review_control: true show_timeline_control: false mode: none timeline: style: ribbon mode: none pan_mode: pan clustering_threshold: 3 show_recordings: true window_seconds: 3600 format: 24h: true microphone: always_connected: false auto_mute: [] auto_unmute: [] mute_after_microphone_mute_seconds: 60 display: mode: single grid_selected_position: default grid_selected_width_factor: 2 grid_max_columns: 4 actions: entity: light.office_main_lights tap_action: action: none hold_action: action: none double_tap_action: action: none start_tap_action: action: none end_tap_action: action: none ```