flan/advanced-camera-card
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.

Browse Source
This commit is contained in:
Dermot Duffy
2022-01-14 21:31:16 -08:00
parent 48bf3af1b1
commit 64af74ae26
1 changed files with 278 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+275 -153
View File
@@ -19,13 +19,13 @@
A full-featured Frigate Lovelace card: A full-featured Frigate Lovelace card:
* Live viewing. * Live viewing of multiple cameras.
* Clips and snapshot browsing via mini-gallery. * Clips and snapshot browsing via mini-gallery.
* Automatic updating to continually show latest clip / snapshot. * Automatic updating to continually show latest clip / snapshot.
* Support for filtering events by zone and label. * Support for filtering events by zone and label.
* Arbitrary entity access via menu (e.g. motion sensor access). * Arbitrary entity access via menu (e.g. motion sensor access).
* Fullscreen mode. * Fullscreen mode.
* Carousel/Swipeable media & thumbnails. * Carousel/Swipeable media, thumbnails and cameras.
* Direct media downloads. * Direct media downloads.
* Lovelace visual editing support. * Lovelace visual editing support.
* Full [Picture Elements](https://www.home-assistant.io/lovelace/picture-elements/) support. * Full [Picture Elements](https://www.home-assistant.io/lovelace/picture-elements/) support.
@@ -73,28 +73,56 @@ lovelace:
## Options ## Options
### Basic Options At least 1 camera must be configured in the `cameras` options, but otherwise all configuration parameters are optional.
| Option | Default | Description | ### Camera Options
| - | - | - |
| `camera_entity` | | The optional Frigate camera entity to use in the `frigate` live provider view. Also used to automatically detect the value of `frigate.camera_name`.|
### Frigate Server Options The `cameras` block configures a list of cameras the card should support, under:
All configuration is under:
```yaml ```yaml
frigate: cameras:
- [...camera 1...]
- [...camera 2...]
``` ```
| Option | Default | Overridable | Description |
| - | - | - | - |
| `camera_entity` | | :heavy_multiplication_x: | 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. |
| `camera_name` | Autodetected from `camera_entity` if that is specified. | :heavy_multiplication_x: | The Frigate camera name to use when communicating with the Frigate server, e.g. for viewing clips/snapshots or the JSMPEG live view. To view the birdseye view set this to `birdseye` and use the `frigate-jsmpeg` live provider.|
| `frigate_url` | | :heavy_multiplication_x: | The URL of the frigate server. If set, this value will be (exclusively) used for a `Frigate UI` menu button. |
| `label` | | :heavy_multiplication_x: | A Frigate label / object filter used to filter events (clips & snapshots), e.g. 'person'.|
| `zone` | | :heavy_multiplication_x: | A Frigate zone used to filter events (clips & snapshots), e.g. 'front_door'.|
| `client_id` | `frigate` | :heavy_multiplication_x: | The Frigate client id to use. If this Home Assistant server has multiple Frigate server backends configured, this selects which server should be used. It should be set to the MQTT client id configured for this server, see [Frigate Integration Multiple Instance Support](https://docs.frigate.video/integrations/home-assistant/#multiple-instance-support).|
| `title` | Autodetected from `camera_entity` if that is specified. | :heavy_multiplication_x: | A friendly name for this camera to use in the card. |
| `icon` | Autodetected from `camera_entity` if that is specified. | :heavy_multiplication_x: | The icon to use for this camera in the camera menu and in the next & previous controls when using the `icon` style. |
| `webrtc` | | :heavy_multiplication_x: | The WebRTC entity/URL to use for this camera. See below. |
| `id` | `camera_entity`, or `camera_name` if set (in that preference order). | :heavy_multiplication_x: | An optional identifier to use throughout the card configuration to refer unambiguously to this camera. See [camera IDs](#camera-ids). |
| Option | Default | Description | #### Camera WebRTC configuration
| - | - | - |
| `camera_name` | Autodetected from `camera_entity` if that is specified. | The Frigate camera name to use when communicating with the Frigate server, e.g. for viewing clips/snapshots or the JSMPEG live view. To view the birdseye view set this to `birdseye` and use the `frigate-jsmpeg` live provider.| The `webrtc` block configures only the entity/URL for this camera to be used with the WebRTC live provider. This configuration is included as part of a camera entry in the `cameras` array.
| `url` | | The URL of the frigate server. If set, this value will be (exclusively) used for a `Frigate UI` menu button. |
| `label` | | A Frigate label / object filter used to filter events (clips & snapshots), e.g. 'person'.| ```yaml
| `zone` | | A Frigate zone used to filter events (clips & snapshots), e.g. 'front_door'.| cameras:
| `client_id` | `frigate` | The Frigate client id to use. If this Home Assistant server has multiple Frigate server backends configured, this selects which server should be used. It should be set to the MQTT client id configured for this server, see [Frigate Integration Multiple Instance Support](https://docs.frigate.video/integrations/home-assistant/#multiple-instance-support).| - webrtc:
```
| Option | Default | Overridable | Description |
| - | - | - | - |
| `entity` | | :heavy_multiplication_x: | The RTSP entity to pass WebRTC for this camera. Specify this OR `url` (below). |
| `url` | | :heavy_multiplication_x: | The RTSP url to pass to WebRTC. Specify this OR `entity` (above). |
See [Using WebRTC](#webrtc) below for more details on how to use WebRTC with this card.
<a name="camera-ids"></a>
#### Camera IDs: Refering to cameras in card configuration
Each camera configured in the card has a single identifier (`id`). For a given camera, this will be one of the camera {`id`, `camera_entity` or `camera_name`} parameters for that camera -- in that order of precedence. These ids may be used in conditions or custom actions to refer to a given camera unambiguously. |
#### Example
See [the basic cameras configuration example](#basic-cameras-configuration) below.
### View Options ### View Options
@@ -104,13 +132,13 @@ All configuration is under:
view: view:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `default` | `live` | The view to show in the card by default. See [views](#views) below.| | `default` | `live` | :heavy_multiplication_x: | The view to show in the card by default. See [views](#views) below.|
| `timeout` | | A numbers of seconds of inactivity after which the card will reset to the default configured view. Inactivity is defined as lack of interaction with the Frigate menu.| | `timeout` | | :heavy_multiplication_x: | A numbers of seconds of inactivity after which the card will reset to the default configured view. Inactivity is defined as lack of interaction with the Frigate menu.|
| `actions` | | Actions to use for all views, individual actions may be overriden by view-specific actions. See [actions](#actions) below.| | `actions` | | :heavy_multiplication_x: | Actions to use for all views, individual actions may be overriden by view-specific actions. See [actions](#actions) below.|
| `update_force` | `false` | Whether card updates/refreshes should ignore playing media and human interaction. See [card updates](#card-updates) below for behavior and usecases.| | `update_force` | `false` | :heavy_multiplication_x: | Whether card updates/refreshes should ignore playing media and human interaction. See [card updates](#card-updates) below for behavior and usecases.|
| `update_entities` | | **YAML only**: A list of entity ids that should cause the whole card to re-render. Entities used in picture elements / included in the menu do not need to be explicitly included here to be kept updated. See [card updates](#card-updates) below for behavior and usecases.| | `update_entities` | | :heavy_multiplication_x: | **YAML only**: A list of entity ids that should cause the view to reset to the default. See [card updates](#card-updates) below for behavior and usecases.|
### Menu Options ### Menu Options
@@ -120,12 +148,11 @@ All configuration is under:
menu: menu:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `mode` | `hidden-top` | The menu mode to show by default. See [menu modes](#menu-modes) below.| | `mode` | `hidden-top` | :white_check_mark: | The menu mode to show by default. See [menu modes](#menu-modes) below.|
| `button_size` | `40px` | The size of the menu buttons [in CSS Units](https://www.w3schools.com/cssref/css_units.asp).| | `button_size` | `40px` | :white_check_mark: | The size of the menu buttons [in CSS Units](https://www.w3schools.com/cssref/css_units.asp).|
| `buttons` | | Whether to show or hide built-in buttons. See below. | | `buttons` | | :white_check_mark: | Whether to show or hide built-in buttons. See below. |
| `conditions` | | Condition(s) that must be met in order for the menu to be displayed. These conditions use the same format as the `custom:frigate-card-conditional` card (see [Possible conditions](#frigate-card-conditions) below). If conditions are specified but not met, then the menu is not rendered.|
#### Menu Options: Buttons #### Menu Options: Buttons
@@ -136,17 +163,17 @@ menu:
buttons: buttons:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `frigate` | `true` | Whether to show the `Frigate` menu button: brings the user to the default configured view (`view.default`), or collapses/expands the menu if the `menu.mode` is `hidden-*` . | | `frigate` | `true` | :white_check_mark: | Whether to show the `Frigate` menu button: brings the user to the default configured view (`view.default`), or collapses/expands the menu if the `menu.mode` is `hidden-*` . |
| `cameras` | `true` | Whether to show the camera selection submenu. Will only appear if multiple cameras are configured. | | `cameras` | `true` | :white_check_mark: | Whether to show the camera selection submenu. Will only appear if multiple cameras are configured. |
| `live` | `true` | Whether to show the `live` view menu button: brings the user to the `live` view. See [views](#views) below.| | `live` | `true` | :white_check_mark: | Whether to show the `live` view menu button: brings the user to the `live` view. See [views](#views) below.|
| `clips` | `true` | Whether to show the `clips` view menu button: brings the user to the `clips` view on tap and the most-recent `clip` view on hold. See [views](#views) below.| | `clips` | `true` | :white_check_mark: | Whether to show the `clips` view menu button: brings the user to the `clips` view on tap and the most-recent `clip` view on hold. See [views](#views) below.|
| `snapshots` | `true` | Whether to show the `snapshots` view menu button: brings the user to the `clips` view on tap and the most-recent `snapshot` view on hold. See [views](#views) below.| | `snapshots` | `true` | :white_check_mark: | Whether to show the `snapshots` view menu button: brings the user to the `clips` view on tap and the most-recent `snapshot` view on hold. See [views](#views) below.|
| `image` | `false` | Whether to show the `image` view menu button: brings the user to the static `image` view. See [views](#views) below.| | `image` | `false` | :white_check_mark: | Whether to show the `image` view menu button: brings the user to the static `image` view. See [views](#views) below.|
| `download` | `true` | Whether to show the `download` menu button: allow direct download of the media being displayed.| | `download` | `true` | :white_check_mark: | Whether to show the `download` menu button: allow direct download of the media being displayed.|
| `frigate_ui` | `true` | Whether to show the `frigate_ui` menu button: brings the user to a context-appropriate page on the Frigate UI (e.g. the camera homepage). Will only appear if the `frigate.url` option is set.| | `frigate_ui` | `true` | :white_check_mark: | Whether to show the `frigate_ui` menu button: brings the user to a context-appropriate page on the Frigate UI (e.g. the camera homepage). Will only appear if the `frigate.url` option is set.|
| `fullscreen` | `true` | Whether to show the `fullscreen` menu button: expand the card to consume the fullscreen. | | `fullscreen` | `true` | :white_check_mark: | Whether to show the `fullscreen` menu button: expand the card to consume the fullscreen. |
### Live Options ### Live Options
@@ -156,14 +183,16 @@ All configuration is under:
live: live:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `preload` | `false` | Whether or not to preload the live view. Preloading causes the live view to render in the background so it's instantly available when requested. This consumes additional network/CPU resources continually.| | `preload` | `false` | :heavy_multiplication_x: | 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. This consumes additional network/CPU resources continually. |
| `provider` | `frigate` | The means through which the live camera view is displayed. See [Live Provider](#live-provider) below.| | `lazy_load` | `true` | :heavy_multiplication_x: | Whether or not to lazily load camera views in the camera carousel. Setting this will `false` will cause all cameras to load simultaneously when the `live` carousel is opened (or cause all cameras to load continually if both `lazy_load` and `preload` are `true`). This will result in a smoother carousel experience at a cost of (potentially) a substantial amount of continually streamed data. |
| `actions` | | Actions to use for the `live` view. See [actions](#actions) below.| | `draggable` | `true` | :heavy_multiplication_x: | Whether or not the live carousel can be dragged left or right, via touch/swipe and mouse dragging. |
| `controls` | | Configuration for the `live` view controls. See below. | | `provider` | `frigate` | :white_check_mark: | The means through which the live camera view is displayed. See [Live Provider](#live-provider) below.|
| `jsmpeg` | | Configuration for the `frigate-jsmpeg` live provider. See below.| | `actions` | | :white_check_mark: | Actions to use for the `live` view. See [actions](#actions) below.|
| `webrtc` | | Configuration for the `webrtc` live provider. See below.| | `controls` | | :white_check_mark: | Configuration for the `live` view controls. See below. |
| `jsmpeg` | | :white_check_mark: | Configuration for the `frigate-jsmpeg` live provider. See below.|
| `webrtc` | | :white_check_mark: | Configuration for the `webrtc` live provider. See below.|
#### Available Live Providers #### Available Live Providers
@@ -173,7 +202,6 @@ live:
|`frigate-jsmpeg`|Lower|Low|Builtin|Stream the JSMPEG stream from Frigate (proxied via the Frigate integration). See [note below on the required integration version](#jsmpeg-troubleshooting) for this live provider to function. This is the only live provider that can view the Frigate `birdseye` view.| |`frigate-jsmpeg`|Lower|Low|Builtin|Stream the JSMPEG stream from Frigate (proxied via the Frigate integration). See [note below on the required integration version](#jsmpeg-troubleshooting) for this live provider to function. This is the only live provider that can view the Frigate `birdseye` view.|
|`webrtc`|Lowest|High|Separate installation required|Uses [WebRTC](https://github.com/AlexxIT/WebRTC) to stream live feed, requires manual extra setup, see [below](#webrtc).| |`webrtc`|Lowest|High|Separate installation required|Uses [WebRTC](https://github.com/AlexxIT/WebRTC) to stream live feed, requires manual extra setup, see [below](#webrtc).|
#### Live Provider: JSMPEG Configuration #### Live Provider: JSMPEG Configuration
All configuration is under: All configuration is under:
@@ -183,9 +211,11 @@ live:
jsmpeg: jsmpeg:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `options` | | **Advanced users only**: Control the underlying [JSMPEG library options](https://github.com/phoboslab/jsmpeg#usage). Supports setting these JSMPEG options `{audio, video, pauseWhenHidden, disableGl, disableWebAssembly, preserveDrawingBuffer, progressive, throttled, chunkSize, maxAudioLag, videoBufferSize, audioBufferSize}`. This is not necessary for the vast majority of users: only set these flags if you know what you're doing, as you may entirely break video rendering in the card.| | `options` | | :white_check_mark: | **Advanced users only**: Control the underlying [JSMPEG library options](https://github.com/phoboslab/jsmpeg#usage). Supports setting these JSMPEG options `{audio, video, pauseWhenHidden, disableGl, disableWebAssembly, preserveDrawingBuffer, progressive, throttled, chunkSize, maxAudioLag, videoBufferSize, audioBufferSize}`. This is not necessary for the vast majority of users: only set these flags if you know what you're doing, as you may entirely break video rendering in the card.|
<a name="webrtc-live-configuration"></a>
#### Live Provider: WebRTC Configuration #### Live Provider: WebRTC Configuration
@@ -196,11 +226,11 @@ live:
webrtc: webrtc:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `entity` | | The RTSP entity to pass WebRTC. Specify this OR `webrtc.url` (above). | | `*`| | :white_check_mark: | Any options specified in the `webrtc:` YAML dictionary are silently passed through to WebRTC. See [WebRTC Configuration](https://github.com/AlexxIT/WebRTC#configuration) for full details this external card provides. This implies that if `entity` or `url` are specified here they will override the matching named parameters under the per camera configuration. |
| `url` | | The RTSP url to pass to WebRTC. Specify this OR `webrtc.entity` (below).|
| `*`| | Any other options in the `webrtc:` YAML dictionary are silently passed through to WebRTC. See [WebRTC Configuration](https://github.com/AlexxIT/WebRTC#configuration) for full details this external card provides.| See [Using WebRTC](#webrtc) below for more details on how to use WebRTC with this card.
#### Live Controls: Thumbnails #### Live Controls: Thumbnails
@@ -212,11 +242,27 @@ live:
thumbnails: thumbnails:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `mode` | `none` | Whether to show the thumbnail carousel `below` the media, `above` the media or to hide it entirely (`none`).| | `mode` | `none` | :white_check_mark: | Whether to show the thumbnail carousel `below` the media, `above` the media or to hide it entirely (`none`).|
| `size` | `100px` | The size of the thumbnails in the thumbnail carousel [in CSS Units](https://www.w3schools.com/cssref/css_units.asp).| | `size` | `100px` | :white_check_mark: | The size of the thumbnails in the thumbnail carousel [in CSS Units](https://www.w3schools.com/cssref/css_units.asp).|
| `media` | `clips` | Whether to show `clips` or `snapshots` in the thumbnail carousel in the `live` view.| | `media` | `clips` | :white_check_mark: | Whether to show `clips` or `snapshots` in the thumbnail carousel in the `live` view.|
#### Live Controls: Next / Previous
All configuration is under:
```yaml
live:
controls:
next_previous:
```
| Option | Default | Overridable | Description |
| - | - | - | - |
| `style` | `chevrons` | :white_check_mark: | When viewing live cameras, what kind of controls to show to move to the previous/next camera. Acceptable values: `chevrons`, `icons`, `none` . |
| `size` | `48px` | :white_check_mark: | The size of the next/previous controls [in CSS Units](https://www.w3schools.com/cssref/css_units.asp).|
### Event Viewer Options ### Event Viewer Options
@@ -228,14 +274,13 @@ All configuration is under:
event_viewer: event_viewer:
``` ```
| Option | Default | Overridable | Description |
| Option | Default | Description | | - | - | - | - |
| - | - | - | | `autoplay_clip` | `false` | :heavy_multiplication_x: | Whether or not to autoplay clips in the 'clip' [view](#views). Clips manually chosen in the clips gallery will still autoplay.|
| `autoplay_clip` | `false` | Whether or not to autoplay clips in the 'clip' [view](#views). Clips manually chosen in the clips gallery will still autoplay.| | `lazy_load` | `true` | :heavy_multiplication_x: | Whether or not to lazily load media in the event viewer carousel. Setting this will false will fetch all media immediately which may make the carousel experience smoother at a cost of (potentially) a substantial number of simultaneous media fetches on load. |
| `lazy_load` | `true` | Whether or not to lazily load media in the event viewer carousel. Setting this will false will fetch all media immediately which may make the carousel experience smoother at a cost of (potentially) a substantial number of simultaneous media fetches on load. | | `draggable` | `true` | :heavy_multiplication_x: | Whether or not the event viewer carousel can be dragged left or right, via touch/swipe and mouse dragging. |
| `draggable` | `true` | Whether or not the event viewer carousel can be dragged left or right, via touch/swipe and mouse dragging. | | `controls` | | :heavy_multiplication_x: | Configuration for the event viewer. See below. |
| `controls` | | Configuration for the event viewer. See below. | | `actions` | | :heavy_multiplication_x: | Actions to use for all views that use the `event_viewer` (e.g. `clip`, `snapshot`). See [actions](#actions) below.|
| `actions` | | Actions to use for all views that use the `event_viewer` (e.g. `clip`, `snapshot`). See [actions](#actions) below.|
#### Event Viewer Controls: Next / Previous #### Event Viewer Controls: Next / Previous
@@ -247,10 +292,10 @@ event_viewer:
next_previous: next_previous:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `style` | `thumbnails` | When viewing media, what kind of controls to show to move to the previous/next media item. Acceptable values: `thumbnails`, `chevrons`, `none` . | | `style` | `thumbnails` | :heavy_multiplication_x: | When viewing media, what kind of controls to show to move to the previous/next media item. Acceptable values: `thumbnails`, `chevrons`, `none` . |
| `size` | `48px` | The size of the next/previous controls [in CSS Units](https://www.w3schools.com/cssref/css_units.asp).| | `size` | `48px` | :heavy_multiplication_x: | The size of the next/previous controls [in CSS Units](https://www.w3schools.com/cssref/css_units.asp).|
#### Event Viewer Controls: Thumbnails #### Event Viewer Controls: Thumbnails
@@ -262,10 +307,10 @@ event_viewer:
thumbnails: thumbnails:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `mode` | `none` | Whether to show the thumbnail carousel `below` the media, `above` the media or to hide it entirely (`none`).| | `mode` | `none` | :heavy_multiplication_x: | Whether to show the thumbnail carousel `below` the media, `above` the media or to hide it entirely (`none`).|
| `size` | `100px` | The size of the thumbnails in the thumbnail carousel [in CSS Units](https://www.w3schools.com/cssref/css_units.asp).| | `size` | `100px` | :heavy_multiplication_x: | The size of the thumbnails in the thumbnail carousel [in CSS Units](https://www.w3schools.com/cssref/css_units.asp).|
### Event Gallery Options ### Event Gallery Options
@@ -277,9 +322,9 @@ All configuration is under:
event_gallery: event_gallery:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `actions` | | Actions to use for all views that use the `event_gallery` (e.g. `clips`, `snapshots`). See [actions](#actions) below.| | `actions` | | :heavy_multiplication_x: | Actions to use for all views that use the `event_gallery` (e.g. `clips`, `snapshots`). See [actions](#actions) below.|
### Image Options ### Image Options
@@ -289,10 +334,10 @@ All configuration is under:
image: image:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `src` | [embedded image](https://www.flickr.com/photos/dianasch/47543120431) | A static image URL for use with the `image` [view](#views).| | `src` | | :heavy_multiplication_x: | [embedded image](https://www.flickr.com/photos/dianasch/47543120431) | A static image URL for use with the `image` [view](#views).|
| `actions` | | Actions to use for the `image` view. See [actions](#actions) below.| | `actions` | | :heavy_multiplication_x: | Actions to use for the `image` view. See [actions](#actions) below.|
### Dimension Options ### Dimension Options
@@ -302,10 +347,10 @@ All configuration is under:
dimensions: dimensions:
``` ```
| Option | Default | Description | | Option | Default | Overridable | Description |
| - | - | - | | - | - | - | - |
| `aspect_ratio_mode` | `dynamic` | The aspect ratio mode to use. Acceptable values: `dynamic`, `static`, `unconstrained`. See [aspect ratios](#aspect-ratios) below.| | `aspect_ratio_mode` | `dynamic` | :heavy_multiplication_x: | The aspect ratio mode to use. Acceptable values: `dynamic`, `static`, `unconstrained`. See [aspect ratios](#aspect-ratios) below.|
| `aspect_ratio` | `16:9` | The aspect ratio to use. Acceptable values: `<W>:<H>` or `<W>/<H>`. See [aspect ratios](#aspect-ratios) below.| | `aspect_ratio` | `16:9` | :heavy_multiplication_x: | The aspect ratio to use. Acceptable values: `<W>:<H>` or `<W>/<H>`. See [aspect ratios](#aspect-ratios) below.|
#### `dimensions.aspect_ratio_mode`: #### `dimensions.aspect_ratio_mode`:
@@ -338,6 +383,34 @@ be used by default.
<a name="webrtc"></a> <a name="webrtc"></a>
### Override Options
All configuration is a list under:
```yaml
overrides:
```
Various parts of this configuration may conditionally (see [Frigate Card
Conditions](#frigate-card-conditions)) be overridden, for example to use custom
WebRTC paramters for a particular camera or to hide the menu in fullscreen mode.
Not all configuration parameters are overriddable (only those with check marks
in this documentation) -- some because it doesn't make sense for that parameter
to vary, and many because of the extra complexity of supporting overriding given
the lack of compelling usecases ([please request new overridable parameters
here!](https://github.com/dermotduffy/frigate-hass-card/issues/new/choose)).
Each entry under the top-level `overrides` configuration block should be a list
item, that has both of the following parameters set:
| Option | Default | Overridable | Description |
| - | - | - | - |
| `conditions` | | :heavy_multiplication_x: | A set of conditions that must evaluate to `true` in order for the overrides to be applied. See [Frigate Card Conditions](#frigate-card-conditions). |
| `overrides` | | :heavy_multiplication_x: |Configuration overrides to be applied. Any configuration parameter described in this documentation as 'Overridable' is supported. |
### Using WebRTC ### Using WebRTC
WebRTC support blends the use of the ultra-realtime [WebRTC live WebRTC support blends the use of the ultra-realtime [WebRTC live
@@ -346,40 +419,64 @@ events/snapshots/UI. A perfect combination!
<img src="https://raw.githubusercontent.com/dermotduffy/frigate-hass-card/main/images/webrtc.png" alt="Live viewing" width="400px"> <img src="https://raw.githubusercontent.com/dermotduffy/frigate-hass-card/main/images/webrtc.png" alt="Live viewing" width="400px">
**Note**: WebRTC must be installed and configured separately (see [details](https://github.com/AlexxIT/WebRTC)) before it can be used with this card. **Note**: WebRTC must be installed and configured separately (see [details](https://github.com/AlexxIT/WebRTC)) before it can be used with this card.
#### Specifying The WebRTC Camera #### Specifying The WebRTC Camera
WebRTC does **not** support use of Frigate-provided camera entities, as it WebRTC does **not** support use of Frigate-provided camera entities, as it
requires an RTSP stream which Frigate does not provide. There are two ways to requires an RTSP stream which Frigate does not currently provide. There are two
specify the WebRTC source camera: ways to specify the WebRTC source camera:
* Manual setup of separate RTSP camera entities in Home Assistant ([see * Manual setup of separate RTSP camera entities in Home Assistant ([see
example](https://www.home-assistant.io/integrations/generic/#live-stream)). example](https://www.home-assistant.io/integrations/generic/#live-stream)).
These entities will then be available for selection in the GUI card editor for These entities will then be available for selection in the GUI card editor for
the Frigate card under the WebRTC options, or can be manually specified with a the camera, or can be manually specified with a `webrtc.entity` option under
`webrtc.entity` option in the YAML configuration for this card: that particular cameras configuration:
```yaml ```yaml
[rest of Frigate card configuration] cameras:
live: - webrtc:
webrtc:
entity: 'camera.front_door_rstp` entity: 'camera.front_door_rstp`
``` ```
* OR manually entering the WebRTC camera URL parameter in the GUI card editor, * OR manually entering the WebRTC camera URL parameter in the GUI card editor,
or configuring the `url` parameter as part of a manual Frigate card or configuring the `url` parameter as part of a manual Frigate card
configuration, like the following example: configuration, as illustrated in the following example:
```yaml ```yaml
[rest of Frigate card configuration] cameras:
live: - webrtc:
webrtc:
url: 'rtsp://USERNAME:PASSWORD@CAMERA:554/RTSP_PATH' url: 'rtsp://USERNAME:PASSWORD@CAMERA:554/RTSP_PATH'
``` ```
See [WebRTC configuration](https://github.com/AlexxIT/WebRTC#configuration) for full configuration options. Other WebRTC options may be specified under the `live` section, like so:
```yaml
live:
webrtc:
ui: true
```
See [the WebRTC live configuration](#webrtc-live-configuration) above, and the
[external WebRTC configuration
documentation](https://github.com/AlexxIT/WebRTC#configuration) for full
configuration options that can be used here.
<a name="frigate-card-conditions"></a>
## Frigate Card Conditions
Conditions are used to apply certain configuration depending on runtime evaluations. Conditions may be used in `elements` configuration (as part of a `custom:frigate-card-conditional` element) or the `overrides` configuration (see below for both).
All variables listed are under a `conditions:` section.
| Condition | Description |
| ------------- | --------------------------------------------- |
| `view` | A list of [views](#views) in which this condition is satified (e.g. `clips`) |
| `camera` | A list of camera ids in which this condition is satisfied. See [camera IDs](#camera-ids).|
| `fullscreen` | If `true` the condition is satisfied if the card is in fullscreen mode. If `false` the condition is satisfied if the card is **NOT** in fullscreen mode.|
See the [PTZ example below](#frigate-card-conditional-example) for a real-world example of how these conditions can be used.
## Picture Elements / Menu Customizations ## Picture Elements / Menu Customizations
@@ -422,9 +519,10 @@ Parameters for the `custom:frigate-card-menu-submenu` element are identical to t
| Parameter | Default | Description | | Parameter | Default | Description |
| - | - | - | | - | - | - |
| `title` | | An optional title to display. | | `title` | | An optional title to display. |
| `icon` | | An optional item icon to display. | | `icon` | | An optional item icon to display, e.g. `mdi:car` |
| `entity` | | An optional Home Assistant entity from which title, icon and style can be automatically computed. | | `entity` | | An optional Home Assistant entity from which title, icon and style can be automatically computed. |
| `state_color` | `true` | Whether or not the title and icon should be stylized based on state. | | `state_color` | `true` | Whether or not the title and icon should be stylized based on state. |
| `selected` | `false` | Whether or not to show this item as selected. |
| `style` | | Position and style the element using CSS. | | `style` | | Position and style the element using CSS. |
| `tap_action`, `double_tap_action` or `hold_action` | | Standard [Home Assistant action configuration](https://www.home-assistant.io/lovelace/actions). | | `tap_action`, `double_tap_action` or `hold_action` | | Standard [Home Assistant action configuration](https://www.home-assistant.io/lovelace/actions). |
@@ -439,21 +537,8 @@ Parameters for the `custom:frigate-card-conditional` element:
| Parameter | Description | | Parameter | Description |
| ------------- | --------------------------------------------- | | ------------- | --------------------------------------------- |
| `type` | Must be `custom:frigate-card-conditional`. | | `type` | Must be `custom:frigate-card-conditional`. |
| `conditions` | A set of conditions that must evaluate to true in order for the elements to be rendered. See below. |
`elements` | The elements to render. Can be any supported element, include additional condition or custom elements. | `elements` | The elements to render. Can be any supported element, include additional condition or custom elements. |
| `conditions` | A set of conditions that must evaluate to true in order for the elements to be rendered. See [Frigate Card Conditions](#frigate-card-conditions). |
<a name="frigate-card-conditions"></a>
##### Frigate Card Conditions
All variables listed are under a `conditions:` section.
| Condition | Description |
| ------------- | --------------------------------------------- |
| `view` | A list of [views](#views) in which these elements should be rendered. |
| `fullscreen` | If `true` the elements are only rendered if the card is in fullscreen mode. If `false` the elements are only rendered if the card is **NOT** in fullscreen mode.|
See the [PTZ example below](#frigate-card-conditional-example) for a real-world example.
### Special Actions ### Special Actions
@@ -470,7 +555,7 @@ See the [PTZ example below](#frigate-card-conditional-example) for a real-world
|`download`|Download the displayed media.| |`download`|Download the displayed media.|
|`frigate_ui`|Open the Frigate UI at the configured URL.| |`frigate_ui`|Open the Frigate UI at the configured URL.|
|`fullscreen`|Toggle fullscreen.| |`fullscreen`|Toggle fullscreen.|
|`camera_select`|Select a given camera. Takes a single additional `camera` parameter with the [camera ID](#camera-ids) of the camera to select.|
<a name="views"></a> <a name="views"></a>
@@ -572,6 +657,19 @@ This card supports fully configurable submenus.
## Examples ## Examples
### Basic cameras configuration
<details>
<summary>Expand: Basic cameras configuration</summary>
```yaml
type: custom:frigate-card
cameras:
- camera_entity: camera.sitting_room
- camera_entity: camera.front_door
```
</details>
### WebRTC ### WebRTC
<details> <details>
@@ -819,29 +917,6 @@ live:
``` ```
</details> </details>
### Hiding The Menu In Certain Circumstances
You can add conditions to the menu, which will hide the menu unless met.
<details>
<summary>Expand: Hiding the menu</summary>
This example hides the menu unless the card is in fullscreen mode, and uses a card-wide action to enable fullscreen mode on `double_tap`:
```yaml
[...]
view:
actions:
double_tap_action:
action: custom:frigate-card-action
frigate_card_action: fullscreen
menu:
conditions:
fullscreen: true
```
</details>
<a name="configuring-a-submenu-example"></a> <a name="configuring-a-submenu-example"></a>
### Configuring a submenu ### Configuring a submenu
@@ -878,13 +953,60 @@ elements:
</details> </details>
### Overriding card behavior
You can override card configuration when certain [conditions](#frigate-card-conditions) are met.
<details>
<summary>Expand: Hiding the menu in fullscreen mode</summary>
This example disables the menu unless the card is in fullscreen mode, and uses a
card-wide action to enable fullscreen mode on `double_tap`:
```yaml
view:
actions:
double_tap_action:
action: custom:frigate-card-action
frigate_card_action: fullscreen
overrides:
- conditions:
fullscreen: true
overrides:
menu:
mode: none
```
</details>
<details>
<summary>Expand: Enable WebRTC UI for a particular camera</summary>
This example enables WebRTC UI mode for a particular camera.
```yaml
cameras:
- camera_entity: camera.office
[...]
overrides:
- conditions:
camera:
- camera.office
overrides:
live:
provider: webrtc
webrtc:
ui: true
```
</details>
<a name="card-updates"></a> <a name="card-updates"></a>
## Card Refreshes / Updates ## Card Refreshes
Automated card refreshes / updates are minimized to avoid disruption to the Three sets of flags govern when the card will automatically re-render in the
user, in particular when media is playing. Three sets of flags govern when the absence of human interaction.
card will automatically re-render in the absence of human interaction.
The following table describes the behavior these 3 flags have. The following table describes the behavior these 3 flags have.
@@ -892,13 +1014,13 @@ The following table describes the behavior these 3 flags have.
| `view.timeout` | `view.update_force` | `view.update_entities` | Behavior | | `view.timeout` | `view.update_force` | `view.update_entities` | Behavior |
| :-: | :-: | :-: | - | | :-: | :-: | :-: | - |
| Unset or `0` | *(Any value)* | Unset | Card will not automatically re-render. | | Unset or `0` | *(Any value)* | Unset | Card will not automatically refresh. |
| Unset or `0` | `false` | *(Any entity)* | Card will reload **current** view when entity state changes, unless media is playing. | | Unset or `0` | `false` | *(Any entity)* | Card will reload default view when entity state changes, unless media is playing. |
| Unset or `0` | `true` | *(Any entity)* | Card will reload **current** view when entity state changes. | | Unset or `0` | `true` | *(Any entity)* | Card will reload default view when entity state changes. |
| `X` seconds | `false` | Unset | Card will reload **default** view `X` seconds after human interaction stops, unless media is playing. | | `X` seconds | `false` | Unset | Card will reload default view `X` seconds after human interaction stops, unless media is playing. |
| `X` seconds | `false` | *(Any entity)* | Card will reload **default** view `X` seconds after human interaction stops and reload the **current** view when entity state changes -- in both cases unless media is playing. | | `X` seconds | `false` | *(Any entity)* | Card will reload default view `X` seconds after human interaction stops or when entity state changes -- in both cases unless media is playing. |
| `X` seconds | `true` | Unset | Card will reload **default** view every `X` seconds. | | `X` seconds | `true` | Unset | Card will reload default view every `X` seconds. |
| `X` seconds | `true` | *(Any entity)* | Card will reload **default** view every `X` seconds and reload the **current** view when entity state changes. | | `X` seconds | `true` | *(Any entity)* | Card will reload default view every `X` seconds or when entity state changes. |
### Usecases For Automated Refreshes ### Usecases For Automated Refreshes