Merge pull request #1524 from dermotduffy/dev

Merge `dev` back to `main` in advance of release

.devcontainer/Dockerfile

@@ -7,3 +7,5 @@ ARG HOME="/home/vscode"
 ENV VOLTA_HOME="${HOME}/.volta"
 ENV PATH="${VOLTA_HOME}/bin:${PATH}"
 RUN bash -c "$(curl -fsSL https://get.volta.sh)" -- --skip-setup
+
+CMD ["sleep", "infinity"]

.devcontainer/devcontainer.json

@@ -1,15 +1,16 @@
 // See https://aka.ms/vscode-remote/devcontainer.json for format details.
 {
   "dockerComposeFile": "../docker-compose.yml",
-  "service": "dev",
+  "service": "devcontainer",
   "features": {
     "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
-      "moby": false,
+      "moby": false
-      "dockerDashComposeVersion": "v2"
     }
   },
+  "updateRemoteUserUID": true,
   "workspaceFolder": "${localWorkspaceFolder}",
-  "shutdownAction": "stopCompose",
+  "initializeCommand": [".devcontainer/initialize.sh"],
+  "postCreateCommand": ["yarn", "install"],
   "forwardPorts": [10001, "hass:8123", "frigate:5000"],
   "portsAttributes": {
     "10001": {
@@ -25,8 +26,6 @@
       "onAutoForward": "silent"
     }
   },
-  "initializeCommand": ".devcontainer/initialize.sh",
-  "postCreateCommand": "yarn install",
   "customizations": {
     "vscode": {
       "extensions": [
@@ -39,9 +38,12 @@
         "davidanson.vscode-markdownlint",
         "redhat.vscode-yaml",
         "lokalise.i18n-ally",
+        "vitest.explorer",
+        "inlang.vs-code-extension",
         "ms-azuretools.vscode-docker"
       ],
       "settings": {
+        "task.allowAutomaticTasks": "on",
         "files.eol": "\n",
         "editor.tabSize": 2,
         "editor.formatOnPaste": false,

.eslintrc.cjs

@@ -1,14 +1,15 @@
 module.exports = {
-    parser: "@typescript-eslint/parser", // Specifies the ESLint parser
+  parser: '@typescript-eslint/parser', // Specifies the ESLint parser
   parserOptions: {
     ecmaVersion: 2020, // Allows for the parsing of modern ECMAScript features
-        sourceType: "module" // Allows for the use of imports
+    sourceType: 'module', // Allows for the use of imports
   },
   extends: [
-        "plugin:@typescript-eslint/recommended" // Uses the recommended rules from the @typescript-eslint/eslint-plugin
+    'plugin:@typescript-eslint/recommended', // Uses the recommended rules from the @typescript-eslint/eslint-plugin
+    'prettier', // Uses eslint-config-prettier to disable ESLint rules from @typescript-eslint/eslint-plugin that would conflict with prettier
   ],
   rules: {
     // Place to specify ESLint rules. Can be used to overwrite rules specified from the extended configs
     // e.g. "@typescript-eslint/explicit-function-return-type": "off",
-    }
+  },
 };

.github/dependabot.yml

@@ -5,4 +5,4 @@ updates:
     directory: /
     schedule:
       interval: daily
-    target-branch: "dev"
+    target-branch: 'dev'

.github/release-drafter.yml

@@ -1,29 +1,29 @@
 ---
 categories:
-  - title: ":boom: Breaking Changes"
+  - title: ':boom: Breaking Changes'
-    label: "breaking"
+    label: 'breaking'
-  - title: ":rocket: Features"
+  - title: ':rocket: Features'
-    label: "enhancement"
+    label: 'enhancement'
-  - title: ":fire: Removals and Deprecations"
+  - title: ':fire: Removals and Deprecations'
-    label: "removal"
+    label: 'removal'
-  - title: ":bug: Fixes"
+  - title: ':bug: Fixes'
-    label: "bug"
+    label: 'bug'
-  - title: ":racehorse: Performance"
+  - title: ':racehorse: Performance'
-    label: "performance"
+    label: 'performance'
-  - title: ":rotating_light: Testing"
+  - title: ':rotating_light: Testing'
-    label: "testing"
+    label: 'testing'
-  - title: ":construction_worker: Continuous Integration"
+  - title: ':construction_worker: Continuous Integration'
-    label: "ci"
+    label: 'ci'
-  - title: ":books: Documentation"
+  - title: ':books: Documentation'
-    label: "documentation"
+    label: 'documentation'
-  - title: ":hammer: Refactoring"
+  - title: ':hammer: Refactoring'
-    label: "refactoring"
+    label: 'refactoring'
-  - title: ":lipstick: Style"
+  - title: ':lipstick: Style'
-    label: "style"
+    label: 'style'
-  - title: ":package: Dependencies"
+  - title: ':package: Dependencies'
     labels:
-      - "dependencies"
+      - 'dependencies'
-      - "build"
+      - 'build'
 template: |
   ## Changes
 

.github/workflows/build.yml

@@ -8,7 +8,7 @@ on:
       - dev
   pull_request:
   schedule:
-    - cron: "17 6 * * *"
+    - cron: '17 6 * * *'
   workflow_dispatch:
 
 jobs:
@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Node and Yarn
         uses: volta-cli/action@v4
@@ -25,23 +25,40 @@ jobs:
       - name: Install dependencies
         run: yarn install --immutable
 
+      - name: Lint
+        run: yarn run lint
+
+      - name: Check formatting
+        run: yarn run format-check
+
+      - name: Test & Coverage
+        run: yarn run coverage
+
       - name: Build
         run: yarn run build
 
-      - name: Test
-        run: yarn run test
-
       - name: HACS build validation
-        uses: "hacs/action@21.12.1"
+        uses: 'hacs/action@21.12.1'
         with:
-          category: "plugin"
+          category: 'plugin'
 
           # Don't attempt to load into HACS (as it loads the release, not the
           # build).
-          ignore: "hacs"
+          ignore: 'hacs'
 
-      - name: Upload artifact
+      - name: Verify docs links
-        uses: actions/upload-artifact@v3
+        run: yarn run docs-check-links
+
+      - name: Upload javascript
+        uses: actions/upload-artifact@v4
         with:
           name: frigate-hass-card
           path: dist/*.js
+
+      # When this issue is fixed, it would be useful to upload visualizations:
+      # https://github.com/actions/upload-artifact/issues/14
+      # - name: Upload visualizations
+      #   uses: actions/upload-artifact@v4
+      #   with:
+      #     name: frigate-hass-card
+      #     path: visualizations/*.html

.github/workflows/labeler.yml

@@ -13,9 +13,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Run Labeler
-        uses: crazy-max/ghaction-github-labeler@v4.1.0
+        uses: crazy-max/ghaction-github-labeler@v5.0.0
         with:
           skip-delete: true

.github/workflows/release-drafter.yml

@@ -11,6 +11,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Run release-drafter
-        uses: release-drafter/release-drafter@v5.23.0
+        uses: release-drafter/release-drafter@v6.0.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Node and Yarn
         uses: volta-cli/action@v4
@@ -24,14 +24,14 @@ jobs:
         run: yarn run build
 
       - name: Zip the files
-        uses: thedoctor0/zip-release@0.7.1
+        uses: thedoctor0/zip-release@0.7.6
         with:
           type: zip
           path: dist
           filename: frigate-hass-card.zip
 
       - name: Upload JS files to release
-        uses: svenstaro/upload-release-action@2.6.1
+        uses: svenstaro/upload-release-action@2.9.0
 
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
@@ -41,7 +41,7 @@ jobs:
           overwrite: true
 
       - name: Upload Zip file to release
-        uses: svenstaro/upload-release-action@2.6.1
+        uses: svenstaro/upload-release-action@2.9.0
 
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -6,7 +6,7 @@ package-lock.json
 .env
 .envrc
 
-stats.html
+/visualizations/
 /coverage/
 
 # https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored

.prettierignore

@@ -0,0 +1,2 @@
+docs/js/
+.devcontainer/

.prettierrc.cjs

@@ -1,8 +0,0 @@
-module.exports = {
-    semi: true,
-    trailingComma: 'all',
-    singleQuote: true,
-    printWidth: 89,
-    tabWidth: 2,
-    embeddedLanguageFormatting: 'auto',
-};

.vscode/extensions.json

@@ -8,8 +8,8 @@
     "runem.lit-plugin",
     "davidanson.vscode-markdownlint",
     "redhat.vscode-yaml",
-    // "lokalise.i18n-ally",
+    "lokalise.i18n-ally",
-    "zixuanchen.vitest-explorer",
+    "vitest.explorer",
-    "inlang.vs-code-extension" // improved i18n DX
+    "inlang.vs-code-extension"
   ]
 }

.vscode/i18n-ally-custom-framework.yml

@@ -12,7 +12,6 @@ usageMatchRegex:
   # you can ignore it and use your own matching rules as well
   - "[^\\w\\d]localize\\(['\"`]({key})['\"`]"
 
-
 # An array of strings containing refactor templates.
 # The "$1" will be replaced by the keypath specified.
 # Optional: uncomment the following two lines to use
@@ -20,6 +19,5 @@ usageMatchRegex:
 # refactorTemplates:
 #  - i18n.get("$1")
 
-
 # If set to true, only enables this custom framework (will disable all built-in frameworks)
 monopoly: true

.vscode/settings.json

@@ -4,6 +4,5 @@
   "i18n-ally.sortKeys": true,
   "i18n-ally.keepFulfilled": true,
   "i18n-ally.editor.preferEditor": true,
-  "i18n-ally.translate.saveAsCandidates": true,
+  "i18n-ally.translate.saveAsCandidates": true
-  "vitest.commandLine": "npx vitest --root ."
 }

.vscode/tasks.json

@@ -20,7 +20,10 @@
           "endsPattern": "^created"
         }
       },
-      "isBackground": true
+      "isBackground": true,
+      "runOptions": {
+        "runOn": "folderOpen"
+      }
     }
   ]
 }

.yarn/patches/README.md

@@ -0,0 +1,7 @@
+# Patches
+
+## `sass`
+
+`sass` is patched to avoid printing out a noisy deprecation notice on every
+build. `sass` is imported by `rollup-plugin-styler`, in a way that triggers this
+message. The patch simply prevents this console spam.

.yarn/patches/sass-npm-1.77.4-13b6910aea.patch

@@ -0,0 +1,13 @@
+diff --git a/sass.node.mjs b/sass.node.mjs
+index f59a3d8987162a3cbc9787c34f67186fb0f09186..b154f46118ccc03989b9a1c11309954c85515539 100644
+--- a/sass.node.mjs
++++ b/sass.node.mjs
+@@ -40,7 +40,7 @@ export const NodePackageImporter = cjs.NodePackageImporter;
+ export const deprecations = cjs.deprecations;
+ export const Version = cjs.Version;
+ 
+-let printedDefaultExportDeprecation = false;
++let printedDefaultExportDeprecation = true;
+ function defaultExportDeprecation() {
+   if (printedDefaultExportDeprecation) return;
+   printedDefaultExportDeprecation = true;

docker-compose.yml

@@ -1,10 +1,8 @@
 ---
 services:
-  dev:
+  devcontainer:
-    init: true
     build: .devcontainer
-    entrypoint: /usr/local/share/docker-init.sh
+    init: true
-    command: sleep infinity
     env_file:
       - .env
     volumes:

docs/CNAME

@@ -0,0 +1 @@
+card.camera

docs/README.md

@@ -0,0 +1,60 @@
+# Getting Started
+
+## Installation
+
+- [HACS](https://hacs.xyz/) is **highly** recommended to install the card -- it works for all Home Assistant variants. If you don't have [HACS](https://hacs.xyz/) installed, start there -- then come back to these instructions.
+
+- Find the card in HACS:
+
+```
+Home Assistant > HACS > Frontend > "Explore & Add Integrations" > Frigate Card
+```
+
+- Click `Download this repository with HACS`.
+
+See [Advanced Installation](advanced-installation.md) for other installation resources.
+
+## Adding your card
+
+- On a Home Assistant dashboard, choose:
+
+```
+[Three dots menu] > Edit dashboard
+```
+
+- Click `+ Add Card` shown on the bottom of the screen
+- Choose `Custom: Frigate card` from the list
+
+## Initial configuration
+
+### Minimal configuration
+
+```yaml
+type: custom:frigate-card
+cameras:
+  - camera_entity: camera.office
+```
+
+### Video scrubbing configuration
+
+```yaml
+type: custom:frigate-card
+cameras:
+  - camera_entity: camera.office
+profiles:
+  - scrubbing
+```
+
+### Multi-camera grid configuration
+
+```yaml
+type: custom:frigate-card
+cameras:
+  - camera_entity: camera.office
+  - camera_entity: camera.kitchen
+live:
+  display:
+    mode: grid
+```
+
+See [Configuration](configuration/README.md) for full details on supported configuration options.

docs/_coverpage.md

@@ -0,0 +1,8 @@
+![logo](images/frigate-logo.svg)
+
+# Frigate Card <small>6.0.0</small>
+
+> A comprehensive camera card for Home Assistant.
+
+[GitHub](https://github.com/dermotduffy/frigate-hass-card/)
+[Documentation](README.md)

docs/_sidebar.md

@@ -0,0 +1,10 @@
+- [Getting Started](README.md)
+- [Configuration](configuration/README.md)
+- [Examples](examples.md)
+- [Screenshots](screenshots.md)
+- [Troubleshooting](troubleshooting.md)
+- [Usage](usage/README.md)
+
+---
+
+- [Developing](developing.md)

docs/advanced-installation.md

@@ -0,0 +1,51 @@
+# Advanced Installation
+
+For most users, the installation instructions in the [Getting Started](README.md) section will install the card successfully. In some rarer situations, additional steps may need to be taken.
+
+### Manual resource management
+
+For most users, HACS should automatically add the necessary resources. Should this auto-registration not work you will need to complete one additional step.
+
+#### Lovelace in "Storage Mode" (default)
+
+- Navigate:
+
+```
+Three dots menu -> "Edit Dashboard" -> Three dots menu -> "Manage resources" -> "Add Resource"
+```
+
+- URL: `/hacsfiles/frigate-hass-card/frigate-hass-card.js`
+- Resource type: `JavaScript Module`
+
+#### Lovelace in "YAML mode" (rare)
+
+You would see`mode: yaml` under `lovelace:` in your `configuration.yaml` if this applies to you.
+
+- Add the following to `configuration.yaml`:
+
+```yaml
+lovelace:
+  resources:
+    - url: /hacsfiles/frigate-hass-card/frigate-hass-card.js
+      type: module
+```
+
+- Restart Home Assistant.
+
+### Manual installation
+
+- Download the `frigate-hass-card.zip` attachment of the desired [release](https://github.com/dermotduffy/frigate-hass-card/releases) to a location accessible by Home Assistant. Note that the release will have a series of `.js` files (for HACS users) **and** a `frigate-hass-card.zip` for the convenience of manual installers.
+- Unzip the file and move the contents of the `dist/` folder to any subfolder name you'd like, e.g. `frigate-card` is used in the below example.
+- Add the location as a Lovelace resource via the UI, or via [YAML configuration](https://www.home-assistant.io/lovelace/dashboards/#resources) such as:
+
+```yaml
+lovelace:
+  mode: yaml
+  resources:
+    - url: /local/frigate-card/frigate-hass-card.js
+      type: module
+```
+
+### Unreleased versions
+
+You can install any unreleased version of the card by leveraging the GitHub Actions artifacts that are generated on every revision. See a [video walkthrough](https://user-images.githubusercontent.com/29582865/228320074-6a2607f5-c637-48d5-b833-a553f8df8f4f.mp4) installing the latest revision of the `release-4.1.0` branch.

docs/configuration/README.md

@@ -0,0 +1,43 @@
+# Configuration
+
+The card supports a myriad of configuration options for simple or complex setups.
+
+### Minimal configuration
+
+```yaml
+type: custom:frigate-card
+cameras:
+  - camera_entity: camera.office
+```
+
+### Configuration blocks
+
+#### Top-level configuration blocks
+
+Only the `cameras` option is required, all other parameters are optional.
+
+| Option                                | Description                                                                                                                                                                                             |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`automations`](automations.md)       | Take action when conditions are met.                                                                                                                                                                    |
+| [`cameras`](cameras/README.md)        | Configures the cameras to be used in the card. At least one camera must be specified.                                                                                                                   |
+| [`cameras_global`](cameras/README.md) | Global defaults that apply to all cameras from the `cameras` section.                                                                                                                                   |
+| `card_id`                             | An optional ID to uniquely identify this card. For use when actions are being sent to card(s) via [URL actions](../usage/url-actions.md). Must exclusively consist of these characters: `[a-zA-Z0-9_]`. |
+| [`dimensions`](dimensions.md)         | Configures the overall card dimensions.                                                                                                                                                                 |
+| [`elements`](elements/README.md)      | Add custom elements to the card.                                                                                                                                                                        |
+| [`image`](image.md)                   | Configures the `image` view.                                                                                                                                                                            |
+| [`live`](live.md)                     | Configures the `live` view.                                                                                                                                                                             |
+| [`media_gallery`](media-gallery.md)   | Configures the media gallery.                                                                                                                                                                           |
+| [`media_viewer`](media-viewer.md)     | Configures the media viewer.                                                                                                                                                                            |
+| [`menu`](menu.md)                     | Configures the card menu.                                                                                                                                                                               |
+| [`overrides`](overrides.md)           | Override card configuration when conditions are met.                                                                                                                                                    |
+| [`performance`](performance.md)       | Configures the card performance.                                                                                                                                                                        |
+| [`profiles`](profiles.md)             | Apply pre-configured sets of defaults to ease card configuration.                                                                                                                                       |
+| [`timeline`](timeline.md)             | Configures the `timeline` view.                                                                                                                                                                         |
+| [`view`](view.md)                     | Configures the default view and behavior of the card.                                                                                                                                                   |
+
+#### Common configuration blocks
+
+| Option                         | Description           |
+| ------------------------------ | --------------------- |
+| [`actions`](actions/README.md) | Configure actions.    |
+| [`conditions`](conditions.md)  | Configure conditions. |

docs/configuration/_sidebar.md

@@ -0,0 +1,27 @@
+- [Getting Started](../README.md)
+- [Configuration](README.md)
+  - [`actions`](actions/README.md)
+  - [`automations`](automations.md)
+  - [`cameras`](cameras/README.md)
+  - [`conditions`](conditions.md)
+  - [`dimensions`](dimensions.md)
+  - [`elements`](elements/README.md)
+  - [`image`](image.md)
+  - [`live`](live.md)
+  - [`media_gallery`](media-gallery.md)
+  - [`media_viewer`](media-viewer.md)
+  - [`menu`](menu.md)
+  - [`overrides`](overrides.md)
+  - [`performance`](performance.md)
+  - [`profiles`](profiles.md)
+  - [`status_bar`](status-bar.md)
+  - [`timeline`](timeline.md)
+  - [`view`](view.md)
+- [Examples](../examples.md)
+- [Screenshots](../screenshots.md)
+- [Troubleshooting](../troubleshooting.md)
+- [Usage](../usage/README.md)
+
+---
+
+- [Developing](../developing.md)

docs/configuration/actions/README.md

@@ -0,0 +1,73 @@
+# `actions`
+
+## Introduction to actions <!-- {docsify-ignore} -->
+
+`actions` is not a top-level configuration block, but can be used as part of
+multiple other blocks.
+
+Actions are pre-configured activities that can be triggered in response to a
+variety of circumstances (e.g. tapping on a menu icon, double tapping on an
+[element](../elements/README.md) or holding the mouse/tap down on a particular
+[view](../view.md?id=supported-views)).
+
+### Differences in actions between Frigate Card and Home Assistant
+
+Both the Home Assistant frontend and the Frigate card cooperate to provide
+action functionality. In general, the Frigate Card functionality is a superset
+of that offered by stock Home Assistant.
+
+Stock action functionality is used for Stock [Home Assistant picture
+elements](https://www.home-assistant.io/lovelace/picture-elements/). Extended
+Frigate card behavior covers all other interactions on the Frigate card (e.g.
+menu icon elements, submenus and actions on the card or views).
+
+#### Custom action types: `start_tap` and `end_tap`
+
+The card has partial support for two special action types `start_tap` and
+`end_tap` which occur when a tap is started (e.g. mouse is pressed down /
+touch begins), and ended (e.g. mouse released / touch ends) respectively. This
+might be useful for PTZ cameras cameras to start/stop movement on touch. Network
+latency may introduce unavoidable imprecision between `end_tap` and action
+actually occurring.
+
+#### Multiple actions
+
+Extended Frigate card behavior supports a list of actions instead of a single
+action, all of which will be handled. See [an example of multiple
+actions](../../examples.md?id=multiple-actions).
+
+## Card and view actions <!-- {docsify-ignore} -->
+
+Actions may be attached to the card itself, to trigger action when the card
+experiences a `tap`, `double_tap`, `hold`, `start_tap` or `end_tap` event.
+Alternatively they can be configured on a per group-of-views basis, e.g. only
+when `live` view is tapped.
+
+| Configuration path      | Views to which it refers               |
+| ----------------------- | -------------------------------------- |
+| `image.actions`         | `image`                                |
+| `live.actions`          | `live`                                 |
+| `media_gallery.actions` | `clips`, `snapshots`, `recordings`     |
+| `media_viewer.actions`  | `clip`, `snapshot`, `recording`        |
+| `view.actions`          | All except `timeline` and `diagnostic` |
+
+If an action is configured for both the whole card (`view.actions`) and a more
+specific view (e.g. `live.actions`) then the actions are merged, with the more
+specific overriding the less specific.
+
+!> The card itself relies on user interactions to function (e.g. `tap` on
+the menu should activate that button). Card or View actions are prevented from
+being activated through standard interaction with menu buttons, next/previous
+controls, thumbnails, etc, but in some cases this prevention is not possible
+(e.g. embedded WebRTC card controls) -- in these cases duplicate actions may
+occur with certain configurations (e.g. `tap`).
+
+!> Card-wide actions are not supported on the `timeline` view, `diagnostics`
+view nor when a info/error message is being displayed.
+
+## Actions <!-- {docsify-ignore} -->
+
+| Option                               | Description                         |
+| ------------------------------------ | ----------------------------------- |
+| [Custom Actions](./custom/README.md) | Custom actions to control the card. |
+| [Stock Actions](./stock/README.md)   | Standard Home Assistant actions.    |

docs/configuration/actions/_sidebar.md

@@ -0,0 +1,29 @@
+- [Getting Started](../../README.md)
+- [Configuration](../README.md)
+  - [`actions`](README.md)
+    - [Custom Actions](./custom/README.md)
+    - [Stock Actions](./stock/README.md)
+  - [`automations`](../automations.md)
+  - [`cameras`](../cameras/README.md)
+  - [`conditions`](../conditions.md)
+  - [`dimensions`](../dimensions.md)
+  - [`elements`](../elements/README.md)
+  - [`image`](../image.md)
+  - [`live`](../live.md)
+  - [`media_gallery`](../media-gallery.md)
+  - [`media_viewer`](../media-viewer.md)
+  - [`menu`](../menu.md)
+  - [`overrides`](../overrides.md)
+  - [`performance`](../performance.md)
+  - [`profiles`](../profiles.md)
+  - [`status_bar`](../status-bar.md)
+  - [`timeline`](../timeline.md)
+  - [`view`](../view.md)
+- [Examples](../../examples.md)
+- [Screenshots](../../screenshots.md)
+- [Troubleshooting](../../troubleshooting.md)
+- [Usage](../../usage/README.md)
+
+---
+
+- [Developing](../../developing.md)

docs/configuration/actions/custom/README.md

@@ -0,0 +1,810 @@
+# `custom:frigate-card-action`
+
+Execute a Frigate Card action.
+
+```yaml
+action: custom:frigate-card-action
+# [...]
+```
+
+| Parameter             | Description                                 |
+| --------------------- | ------------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`.       |
+| `frigate_card_action` | A supported Frigate Card action. See below. |
+
+## `camera_select`
+
+Select a given camera.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: camera_select
+# [...]
+```
+
+| Parameter             | Description                                                                                         |
+| --------------------- | --------------------------------------------------------------------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`.                                                               |
+| `frigate_card_action` | Must be `camera_select`.                                                                            |
+| `camera`              | The [camera ID](../../cameras/README.md?id=cameras) of the camera to select.                        |
+| `triggered`           | If `true` instead of `camera` being specified then a triggered camera (if any) is selected instead. |
+
+This action will respect the value of the `view.camera_select` to choose the appropriate view on the new camera. See [`view` configuration](../../view.md).
+
+## `camera_ui`
+
+Download the displayed media.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: camera_ui
+```
+
+Open the UI for the selected camera engine (e.g. the Frigate UI).
+
+## `change_zoom`
+
+Zoom in and/or pan for a given camera.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: change_zoom
+# [...]
+```
+
+| Parameter             | Description                                                                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`.                                                                                                   |
+| `frigate_card_action` | Must be `change_zoom`.                                                                                                                  |
+| `target_id`           | The [camera ID](../../cameras/README.md?id=cameras) or a media ID (e.g. `frigate` event ID) to change zoom/pam settings for.            |
+| `zoom`                | Optional parameter that controls how much to zoom-in. See the [camera zoom parameter](../../cameras/README.md?id=layout-configuration). |
+| `pan`                 | Optional parameter that controls how much to pan-x/y. See the [camera pan parameter](../../cameras/README.md?id=layout-configuration).  |
+
+?> If neither `zoom` nor `pan` are specified the camera will return to its default zoom and pan settings.
+
+See [example of automatically zoom/panning based on state](../../../examples.md?id=automatically-zoom-based-on-state).
+
+## `clip`
+
+Change to the `clip` view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: clip
+```
+
+## `clips`
+
+Change to the `clips` view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: clips
+```
+
+## `default`
+
+Change to the default view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: default
+```
+
+## `diagnostics`
+
+Show the card diagnostics.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: diagnostics
+```
+
+## `display_mode_select`
+
+Select a display mode (e.g. view a `single` camera or a `grid` of cameras).
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: display_mode_select
+# [...]
+```
+
+| Parameter             | Description                                                                                    |
+| --------------------- | ---------------------------------------------------------------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`.                                                          |
+| `frigate_card_action` | Must be `display_mode_select`.                                                                 |
+| `display_mode`        | `single` to show a single camera at a time in a carousel, or `grid` to show a grid of cameras. |
+
+## `download`
+
+Download the displayed media.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: download
+```
+
+## `expand`
+
+Expand the card into a dialog/popup.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: expand
+```
+
+## `fullscreen`
+
+Toggle fullscreen.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: fullscreen
+```
+
+## `image`
+
+Change to the `image` view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: image
+```
+
+## `live`
+
+Change to the `live` view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: live
+```
+
+## `live_substream_off`
+
+Turn off the substream (if on).
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: live_substream_on
+```
+
+| Parameter             | Description                           |
+| --------------------- | ------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`. |
+| `frigate_card_action` | Must be `live_substream_on`.          |
+
+## `live_substream_on`
+
+Turn on the first available substream. Use [Camera dependency configuration](../../cameras/README.md?id=dependencies) to configure substreams.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: live_substream_on
+```
+
+| Parameter             | Description                           |
+| --------------------- | ------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`. |
+| `frigate_card_action` | Must be `live_substream_on`.          |
+
+## `live_substream_select`
+
+Select a substream. Use [Camera dependency configuration](../../cameras/README.md?id=dependencies) to configure substreams.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: live_substream_select
+# [...]
+```
+
+| Parameter             | Description                                                                     |
+| --------------------- | ------------------------------------------------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`.                                           |
+| `frigate_card_action` | Must be `live_substream_select`.                                                |
+| `camera`              | The [camera ID](../../cameras/README.md?id=cameras) of the substream to select. |
+
+## `log`
+
+Log a message to the Javascript console.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: log
+# [...]
+```
+
+| Parameter             | Default | Description                                                                    |
+| --------------------- | ------- | ------------------------------------------------------------------------------ |
+| `action`              |         | Must be `custom:frigate-card-action`.                                          |
+| `frigate_card_action` |         | Must be `log`.                                                                 |
+| `message`             |         | The message to log.                                                            |
+| `level`               | `info`  | The console logging level to use. One of `['debug', 'info', 'warn', 'error']`. |
+
+## `media_player`
+
+Perform a media player action.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: media_player
+# [...]
+```
+
+| Parameter             | Description                                                       |
+| --------------------- | ----------------------------------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`.                             |
+| `frigate_card_action` | Must be `media_player`.                                           |
+| `media_player`        | The entity ID of the media_player on which to perform the action. |
+| `media_player_action` | Either `play` or `stop` to play or stop the media in question.    |
+
+## `menu_toggle`
+
+Show/hide the menu (for the `hidden` mode style).
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: menu_toggle
+```
+
+## `microphone_mute`
+
+Mute the microphone during [2-way audio](../../../usage/2-way-audio.md).
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: microphone_mute
+```
+
+## `microphone_unmute`
+
+Unmute the microphone during [2-way audio](../../../usage/2-way-audio.md).
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: microphone_unmute
+```
+
+## `mute`
+
+Mute the selected media.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: mute
+```
+
+## `pause`
+
+Pause the selected media.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: pause
+```
+
+## `play`
+
+Play the selected media.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: play
+```
+
+## `ptz`
+
+Execute a real PTZ action, whether configured manually (see [Camera PTZ configuration](../../cameras/README.md?id=ptz)) or auto-detected.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: ptz
+# [...]
+```
+
+| Parameter             |                           | Description                                                                                   |
+| --------------------- | ------------------------- | --------------------------------------------------------------------------------------------- |
+| `action`              |                           | Must be `custom:frigate-card-action`.                                                         |
+| `frigate_card_action` |                           | Must be `ptz`.                                                                                |
+| `camera`              | Currently selected camera | An optional camera ID to execute the action on.                                               |
+| `ptz_action`          |                           | Optional action that is of `left`, `right`, `up`, `down`, `zoom_in`, `zoom_out` or `preset`.  |
+| `ptz_phase`           |                           | Optional parameter that is one of `start` or `stop` to start or stop the movement separately. |
+| `ptz_preset`          |                           | Optional preset to execute when the `ptz_action` is `preset`.                                 |
+
+?> If no `ptz_action` is specified, the camera returns to its "home" position. For a real PTZ camera, the "home" position is the first available preset. If there are no presets, there is no home position.
+
+## `ptz_controls`
+
+Show or hide the PTZ controls.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: ptz_controls
+# [...]
+```
+
+| Parameter             | Description                                              |
+| --------------------- | -------------------------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`.                    |
+| `frigate_card_action` | Must be `ptz_controls`.                                  |
+| `show`                | If `true` shows the PTZ controls, if `false` hides them. |
+
+## `ptz_digital`
+
+Execute a digital PTZ action.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: ptz-digital
+# [...]
+```
+
+| Parameter             | Default                                                                                       | Description                                                                                                                                                |
+| --------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`              |                                                                                               | Must be `custom:frigate-card-action`.                                                                                                                      |
+| `frigate_card_action` |                                                                                               | Must be `ptz-digital`.                                                                                                                                     |
+| `target_id`           | The currently selected camera or media                                                        | The target (camera or media) to execute a digital PTZ action on. Can be a camera ID, or another media ID (e.g. for Frigate, can specify a media/event ID). |
+| `ptz_action`          | Optional action that is one of `left`, `right`, `up`, `down`, `zoom_in` or `zoom_out`.        |
+| `ptz_phase`           | Optional parameter that is one of `start` or `stop` to start or stop the movement separately. |
+| `absolute`            | Optional parameter to specify exact absolute pan and zoom settings. See below.                |
+
+?> If no `ptz_action` is specified and no `absolute` value is specified, the camera returns to its "home" position. See [Camera layout configuration](../../cameras/README.md?id=layout-configuration) to configure the default "home" position for digital PTZ.
+
+### `absolute`
+
+Set exact digital PTZ pan and zoom parameters.
+
+| Parameter | Description                                                                                                                              |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `pan`     | Control camera digital pan. See the `pan` parameter in [Camera layout configuration](../../cameras/README.md?id=layout-configuration).   |
+| `zoom`    | Control camera digital zoom. See the `zoom` parameter in [Camera layout configuration](../../cameras/README.md?id=layout-configuration). |
+
+## `ptz_multi`
+
+Execute a PTZ action that intelligently chooses between a real and digital PTZ
+action. If the media in question is a live camera with real PTZ support, a real
+PTZ action will execute (equivalent to using the [`ptz`](README.md?id=ptz)
+action), otherwise a digital PTZ action will be run (equivalent to using the
+[`ptz_digital`](README.md?id=ptz_digital) action).
+
+?> If the camera supports _any_ real PTZ action, _all_ actions will attempt to make real PTZ calls.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: ptz-multi
+# [...]
+```
+
+| Parameter             | Description                                                                                   |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`.                                                         |
+| `frigate_card_action` | Must be `ptz-digital`.                                                                        |
+| `ptz_action`          | Optional action that is one of `left`, `right`, `up`, `down`, `zoom_in` or `zoom_out`.        |
+| `ptz_phase`           | Optional parameter that is one of `start` or `stop` to start or stop the movement separately. |
+| `ptz_preset`          | Optional preset to execute when the `ptz_action` is `preset`.                                 |
+
+?> If no `ptz_action` is specified, the camera returns to its "home" position.
+
+## `recording`
+
+Change to the `recording` view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: recording
+```
+
+## `recordings`
+
+Change to the `recordings` view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: recordings
+```
+
+## `screenshot`
+
+Take a screenshot of the selected media (e.g. a still from a video).
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: screenshot
+```
+
+## `sleep`
+
+Take no action for a given duration. Useful to pause between multiple other actions.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: sleep
+```
+
+| Parameter             | Description                           |
+| --------------------- | ------------------------------------- |
+| `action`              | Must be `custom:frigate-card-action`. |
+| `frigate_card_action` | Must be `sleep`.                      |
+| `duration`            | A duration object. See below.         |
+
+### `duration`
+
+The `duration` block configures how long the `sleep` should last.
+
+| Parameter | Description                |
+| --------- | -------------------------- |
+| `h`       | Hours to sleep for.        |
+| `m`       | Minutes to sleep for.      |
+| `s`       | Seconds to sleep for.      |
+| `ms`      | Milliseconds to sleep for. |
+
+?> Multiple values can be combined, e.g. `{ m: 2, s: 30}` will sleep for `2.5` minutes.
+
+## `snapshot`
+
+Change to the `snapshot` view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: snapshot
+```
+
+## `status_bar`
+
+Add or remove items from the status bar.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: status_bar
+# [...]
+```
+
+| Parameter           | Default | Description                                                                                                                                             |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status_bar_action` |         | If `add` adds `items` to the status bar, if `remove` removes items and if `reset` resets the status bar entirely (removes all dynamically added items). |
+| `items`             |         | The items to `add` or `remove`. See below.                                                                                                              |
+
+### `items`
+
+The items parameter is a list of items to `add` or `remove`. See [`custom:frigate-card-status-bar-icon`](../../elements/custom/README.md?id=status-bar-icon), [`custom:frigate-card-status-bar-image`](../../elements/custom/README.md?id=status-bar-image), [`custom:frigate-card-status-bar-string`](../../elements/custom/README.md?id=status-bar-string) for the allowable items and their parameters. See the [fully expanded reference](./README.md?fully-expanded-reference) below for a complete example.
+
+## `timeline`
+
+Change to the `timeline` view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: timeline
+```
+
+## `unmute`
+
+Unmute the selected media.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: unmute
+```
+
+## Fully expanded reference
+
+[](../../common/expanded-warning.md ':include')
+
+```yaml
+elements:
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-a-circle
+    title: Select Front Door
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: camera_select
+      camera: camera.front_door
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-b-circle
+    title: Open Camera UI
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: camera_ui
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-c-circle
+    title: Change Zoom
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: change_zoom
+      pan:
+        x: 50
+        y: 50
+      zoom: 1
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-d-circle
+    title: Show most recent clip
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: clip
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-e-circle
+    title: Show clips
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: clips
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-f-circle
+    title: Show default view
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: default
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-g-circle
+    title: Show diagnostics
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: diagnostics
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-h-circle
+    title: Show  grid
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: display_mode_select
+      display_mode: grid
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-i-circle
+    title: Download media
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: download
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-j-circle
+    title: Expand
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: expand
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-k-circle
+    title: Fullscreen
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: fullscreen
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-l-circle
+    title: Show image view
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: image
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-m-circle
+    title: Show live view
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: live
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-n-circle
+    title: Turn off substream
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: live_substream_off
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-o-circle
+    title: Turn on substream
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: live_substream_on
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-n-circle
+    title: Select HD substream
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: live_substream_select
+      camera: camera.front_door_hd
+  - type: custom:frigate-card-menu-icon
+      icon: mdi:alpha-o-circle
+      title: Log to console
+      tap_action:
+        action: custom:frigate-card-action
+        frigate_card_action: log
+        message: "Hello, world!"
+        level: debug
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-m-circle
+    title: Media player play
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: media_player
+      media_player: media_player.nesthub50be
+      media_player_action: play
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-n-circle
+    title: Media player stop
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: media_player
+      media_player: media_player.nesthub
+      media_player_action: stop
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-o-circle
+    title: Toggle hidden menu
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: menu_toggle
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-p-circle
+    title: Microphone mute
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: microphone_mute
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-q-circle
+    title: Microphone unmute
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: microphone_unmute
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-r-circle
+    title: Mute
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: mute
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-s-circle
+    title: Pause
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: pause
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-t-circle
+    title: Play
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: play
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-u-circle
+    title: Real PTZ Preset
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: ptz
+      ptz_action: preset
+      ptz_preset: doorway
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-v-circle
+    title: Show PTZ Controls
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: ptz_controls
+      enabled: true
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-w-circle
+    title: Go to precise digital location
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: ptz_digital
+      absolute:
+        zoom: 5
+        pan:
+          x: 58
+          y: 14
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-x-circle
+    title: Smart select between real and digital PTZ
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: ptz_multi
+      ptz_action: left
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-y-circle
+    title: Show most recent recording
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: recording
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-a-circle-outline
+    title: Show recordings
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: recordings
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-b-circle-outline
+    title: Screenshot
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: screenshot
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-c-circle-outline
+    title: Sleep
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: sleep
+      duration:
+        h: 1
+        m: 20
+        s: 56
+        ms: 422
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-d-circle-outline
+    title: Show most recent snapshot
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: snapshot
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-e-circle-outline
+    title: Show snapshots
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: snapshots
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-f-circle-outline
+    title: Show timeline
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: timeline
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-g-circle-outline
+    title: Unmute
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: unmute
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-h-circle-outline
+    title: Add status bar contents
+    tap_action:
+      - action: custom:frigate-card-action
+        frigate_card_action: status_bar
+        status_bar_action: add
+        items:
+          - type: custom:frigate-card-status-bar-string
+            enabled: true
+            exclusive: false
+            expand: false
+            string: 'Intruder alert!'
+            priority: 50
+            sufficient: false
+          - type: custom:frigate-card-status-bar-icon
+            enabled: true
+            exclusive: false
+            expand: false
+            icon: 'mdi:cow'
+            priority: 50
+            sufficient: false
+          - type: custom:frigate-card-status-bar-image
+            enabled: true
+            exclusive: false
+            expand: false
+            image: https://my.site.com/status.png
+            priority: 50
+            sufficient: false
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-i-circle-outline
+    title: Remove status bar contents
+    tap_action:
+      - action: custom:frigate-card-action
+        frigate_card_action: status_bar
+        status_bar_action: remove
+        items:
+          - type: custom:frigate-card-status-bar-string
+            enabled: true
+            exclusive: false
+            expand: false
+            string: 'Intruder alert!'
+            priority: 50
+            sufficient: false
+          - type: custom:frigate-card-status-bar-icon
+            enabled: true
+            exclusive: false
+            expand: false
+            icon: 'mdi:cow'
+            priority: 50
+            sufficient: false
+          - type: custom:frigate-card-status-bar-image
+            enabled: true
+            exclusive: false
+            expand: false
+            image: https://my.site.com/status.png
+            priority: 50
+            sufficient: false
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-i-circle-outline
+    title: Reset status bar contents
+    tap_action:
+      - action: custom:frigate-card-action
+        frigate_card_action: status_bar
+        status_bar_action: reset
+```

docs/configuration/actions/custom/_sidebar.md

@@ -0,0 +1,29 @@
+- [Getting Started](../../../README.md)
+- [Configuration](../../README.md)
+  - [`actions`](../README.md)
+    - [Custom Actions](README.md)
+    - [Stock Actions](../stock/README.md)
+  - [`automations`](../../automations.md)
+  - [`cameras`](../../cameras/README.md)
+  - [`conditions`](../../conditions.md)
+  - [`dimensions`](../../dimensions.md)
+  - [`elements`](../../elements/README.md)
+  - [`image`](../../image.md)
+  - [`live`](../../live.md)
+  - [`media_gallery`](../../media-gallery.md)
+  - [`media_viewer`](../../media-viewer.md)
+  - [`menu`](../../menu.md)
+  - [`overrides`](../../overrides.md)
+  - [`performance`](../../performance.md)
+  - [`profiles`](../../profiles.md)
+  - [`status_bar`](../../status-bar.md)
+  - [`timeline`](../../timeline.md)
+  - [`view`](../../view.md)
+- [Examples](../../../examples.md)
+- [Screenshots](../../../screenshots.md)
+- [Troubleshooting](../../../troubleshooting.md)
+- [Usage](../../../usage/README.md)
+
+---
+
+- [Developing](../../../developing.md)

docs/configuration/actions/stock/README.md

@@ -0,0 +1,142 @@
+# Stock Actions
+
+## `call-service`
+
+Call a service. See [Home Assistant actions documentation](https://www.home-assistant.io/dashboards/actions/).
+
+!> Home Assistant has deprecated the `call-service` action, please use [`perform-action`](#perform-action) instead.
+
+```yaml
+action: call-service
+# [...]
+```
+
+## `more-info`
+
+Open the "more-info" dialog for an entity. See [Home Assistant actions documentation](https://www.home-assistant.io/dashboards/actions/).
+
+```yaml
+action: more-info
+# [...]
+```
+
+## `navigate`
+
+Navigate to a particular dashboard path. See [Home Assistant actions documentation](https://www.home-assistant.io/dashboards/actions/).
+
+```yaml
+action: navigate
+# [...]
+```
+
+## `perform-action`
+
+Perform a Home Assistant action. See [Home Assistant actions documentation](https://www.home-assistant.io/dashboards/actions/).
+
+```yaml
+action: perform-action
+# [...]
+```
+
+## `toggle`
+
+Toggle an entity. See [Home Assistant actions documentation](https://www.home-assistant.io/dashboards/actions/).
+
+```yaml
+action: toggle
+# [...]
+```
+
+## `url`
+
+Navigate to an arbitrary URL. See [Home Assistant actions documentation](https://www.home-assistant.io/dashboards/actions/).
+
+```yaml
+action: url
+# [...]
+```
+
+## Fully expanded reference
+
+[](../../common/expanded-warning.md ':include')
+
+Reference: [Home Assistant Actions](https://www.home-assistant.io/dashboards/actions/).
+
+```yaml
+elements:
+  - type: icon
+    icon: mdi:numeric-1-box
+    title: More info action
+    style:
+      left: 200px
+      top: 50px
+    entity: light.office_main_lights
+    tap_action:
+      action: more-info
+  - type: icon
+    icon: mdi:numeric-2-box
+    title: Toggle action
+    style:
+      left: 200px
+      top: 100px
+    entity: light.office_main_lights
+    tap_action:
+      action: toggle
+  - type: icon
+    icon: mdi:numeric-3-box
+    title: Call Service action
+    style:
+      left: 200px
+      top: 150px
+    tap_action:
+      action: call-service
+      service: homeassistant.toggle
+      data:
+        entity_id: light.office_main_lights
+  - type: icon
+    icon: mdi:numeric-4-box
+    title: Navigate action
+    style:
+      left: 200px
+      top: 200px
+    tap_action:
+      action: navigate
+      navigation_path: /lovelace/2
+  - type: icon
+    icon: mdi:numeric-5-box
+    title: URL action
+    style:
+      left: 200px
+      top: 250px
+    tap_action:
+      action: url
+      url_path: https://www.home-assistant.io/
+  - type: icon
+    icon: mdi:numeric-6-box
+    title: None action
+    style:
+      left: 200px
+      top: 300px
+    tap_action:
+      action: none
+  - type: icon
+    icon: mdi:numeric-7-box
+    title: Custom action
+    style:
+      left: 200px
+      top: 350px
+    tap_action:
+      action: fire-dom-event
+      key: value
+  - type: icon
+    icon: mdi:numeric-8-box
+    title: Perform action
+    style:
+      left: 200px
+      top: 400px
+    tap_action:
+      action: perform-action
+      perform_action: homeassistant.toggle
+      target:
+        entity_id: light.office_main_lights
+```

docs/configuration/actions/stock/_sidebar.md

@@ -0,0 +1,29 @@
+- [Getting Started](../../../README.md)
+- [Configuration](../../README.md)
+  - [`actions`](../README.md)
+    - [Custom Actions](../custom/README.md)
+    - [Stock Actions](README.md)
+  - [`automations`](../../automations.md)
+  - [`cameras`](../../cameras/README.md)
+  - [`conditions`](../../conditions.md)
+  - [`dimensions`](../../dimensions.md)
+  - [`elements`](../../elements/README.md)
+  - [`image`](../../image.md)
+  - [`live`](../../live.md)
+  - [`media_gallery`](../../media-gallery.md)
+  - [`media_viewer`](../../media-viewer.md)
+  - [`menu`](../../menu.md)
+  - [`overrides`](../../overrides.md)
+  - [`performance`](../../performance.md)
+  - [`profiles`](../../profiles.md)
+  - [`status_bar`](../../status-bar.md)
+  - [`timeline`](../../timeline.md)
+  - [`view`](../../view.md)
+- [Examples](../../../examples.md)
+- [Screenshots](../../../screenshots.md)
+- [Troubleshooting](../../../troubleshooting.md)
+- [Usage](../../../usage/README.md)
+
+---
+
+- [Developing](../../../developing.md)

docs/configuration/automations.md

@@ -0,0 +1,38 @@
+# `automations`
+
+Automatically take [actions](actions/README.md) based on [conditions](conditions.md) being met.
+
+?> To change configuration conditionally use [overrides](overrides.md).
+
+```yaml
+automations:
+  - conditions:
+      - [condition]
+    actions:
+      - [action]
+    actions_not:
+      - [action]
+```
+
+| Option        | Default | Description                                                                                                              |
+| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `conditions`  |         | A list of [conditions](conditions.md) that must evaluate to `true` in order to trigger the automation.                   |
+| `actions`     |         | An optional list of [actions](actions/README.md) that will be run when the [conditions](conditions.md) evaluate `true`.  |
+| `actions_not` |         | An optional list of [actions](actions/README.md) that will be run when the [conditions](conditions.md) evaluate `false`. |
+
+# Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+automations:
+  - conditions:
+      - condition: fullscreen
+        fullscreen: true
+    actions:
+      - action: custom:frigate-card-action
+        frigate_card_action: live_substream_on
+    actions_not:
+      - action: custom:frigate-card-action
+        frigate_card_action: live_substream_off
+```

docs/configuration/cameras/README.md

@@ -0,0 +1,436 @@
+# Cameras
+
+The `cameras` block configures a list of cameras the card should support. The first listed camera is the default.
+
+```yaml
+cameras:
+  - [...camera 0 (default camera)...]
+  - [...camera 1...]
+  - [...camera 2...]
+```
+
+The `cameras_global` block can be used to set defaults across multiple cameras.
+
+```yaml
+cameras_global:
+  # [...]
+```
+
+| Option          | Default                                                                                           | Description                                                                                                                                                                                                                                                      |
+| --------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `camera_entity` |                                                                                                   | The Home Assistant camera entity to use with the `frigate` live provider view. Also used to automatically detect the name of the underlying Frigate camera, and the title/icon of the camera.                                                                    |
+| `capabilities`  |                                                                                                   | Allows selective disabling of camera capabilities. See below.                                                                                                                                                                                                    |
+| `cast`          |                                                                                                   | Configuration that controls how this camera is "casted" / sent to media players. See below.                                                                                                                                                                      |
+| `dependencies`  |                                                                                                   | Other cameras that this camera should depend upon. See below.                                                                                                                                                                                                    |
+| `dimensions`    |                                                                                                   | Controls the dimensions and layout for media from this camera. See below.                                                                                                                                                                                        |
+| `engine`        | `auto`                                                                                            | The camera engine to use. If `auto` the card will attempt to choose the correct engine from the specified options. See [Engine](engine.md).                                                                                                                      |
+| `frigate`       |                                                                                                   | Options for Frigate cameras. See [Frigate camera engine configuration](engine.md?id=frigate).                                                                                                                                                                    |
+| `icon`          | Autodetected from `camera_entity` if that is specified.                                           | The icon to use for this camera in the camera menu and in the next & previous controls when using the `icon` style.                                                                                                                                              |
+| `id`            | `camera_entity`, `webrtc_card.entity` or `frigate.camera_name` if set (in that preference order). | An optional identifier to use throughout the card configuration to refer unambiguously to this camera. This `id` may be used in [conditions](../conditions.md), dependencies or custom [actions](../actions/README.md) to refer to a given camera unambiguously. |
+| `live_provider` | `auto`                                                                                            | The choice of live stream provider. See [Live Provider](live-provider.md).                                                                                                                                                                                       |
+| `title`         | Autodetected from `camera_entity` if that is specified.                                           | A friendly name for this camera to use in the card.                                                                                                                                                                                                              |
+| `triggers`      |                                                                                                   | Define what should cause this camera to update/trigger. See below.                                                                                                                                                                                               |
+| `webrtc_card`   |                                                                                                   | The WebRTC entity/URL to use for this camera with the `webrtc-card` live provider. See below.                                                                                                                                                                    |
+
+## `capabilities`
+
+The `capabilities` block allows selected disabling of auto-detected camera capabilities. This is rarely used, with substreams being a notable exception.
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    capabilities:
+      # [...]
+```
+
+| Option           | Default | Description                                                                                                |
+| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
+| `disable`        |         | A list of camera capabilities to disable. By default all capabilities supported by the camera are enabled. |
+| `disable_except` |         | A list of camera capabilities to leave enabled if supported. Everything else will be disabled.             |
+
+### Capabilities
+
+| Capability            | Purpose                                                  |
+| --------------------- | -------------------------------------------------------- |
+| `clips`               | Clips can be fetched from the camera.                    |
+| `favorite-events`     | Events can be favorited.                                 |
+| `favorite-recordings` | Recordings can be favorited.                             |
+| `live`                | Live video can be received from the camera.              |
+| `menu`                | The camera should show up in the card camera menu.       |
+| `ptz`                 | The camera can be PTZ controlled.                        |
+| `recordings`          | Recordings can be fetched from the camera.               |
+| `seek`                | Clips can be seeked / scrubbed by the timeline.          |
+| `snapshots`           | Snapshots can be fetched from the camera.                |
+| `substream`           | The camera can be used as a substream on another camera. |
+
+## `cast`
+
+The `cast` block configures how a camera is cast / sent to media players.
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    cast:
+      # [...]
+```
+
+| Option      | Default    | Description                                                                                                                                                                                                                                                                                                                  |
+| ----------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dashboard` |            | Configuration for the dashboard to cast. See below.                                                                                                                                                                                                                                                                          |
+| `method`    | `standard` | Whether to use `standard` media casting to send the live view to your media player, or to instead cast a `dashboard` you have manually setup. Casting a dashboard supports a much wider variety of video media, including low latency video providers (e.g. `go2rtc`). This setting has no effect on casting non-live media. |
+
+See the [dashboard method cast example](../../examples.md?id=cast-a-dashboard).
+
+### Dashboard Configuration
+
+```yaml
+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:
+
+```yaml
+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](../dimensions.md) to set the dimensions of the whole card and not just a single camera).
+
+```yaml
+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](../dimensions.md) (which controls dimensions for the whole card), e.g. `16 / 9`. |
+| `layout`       |         | How the media should be laid out _within_ the camera dimensions. See below.                                                                                                                                                                                                                                                  |
+
+### Layout Configuration
+
+The `layout` block configures the fit and position of the media _within_ the camera dimensions (in order to control the dimensions for the whole card see [the card dimensions configuration](../dimensions.md) ).
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    dimensions:
+      layout:
+        # [...]
+```
+
+| Option     | Default   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `fit`      | `contain` | If `contain`, the media is contained within the card and letterboxed if necessary. If `cover`, the media is expanded proportionally (i.e. maintaining the media aspect ratio) until the camera/card dimensions are fully covered. If `fill`, the media is stretched to fill the camera/card dimensions (i.e. ignoring the media aspect ratio). See [CSS object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) for technical details and a visualization.                                                                                                                                                                                                                                                                                                                                                    |
+| `pan`      |           | A dictionary that may contain an `x` and `y` percentage (`0` - `100`) to control the position of the media when "digitally zoomed in" (see `zoom` parameter). This can be effectively used to "pan"/cut the media shown. A value of `0` means maximally to the left or top of the media, a value of `100` means maximally to the right or bottom of the media. See visualizations below.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `position` |           | A dictionary that may contain an `x` and `y` percentage (`0` - `100`) to control the position of the media when the fit is `cover` (for other values of `fit` this option has no effect). This can be effectively used to "pan"/cut the media shown. At any given time, only one of `x` and `y` will have an effect, depending on whether media width is larger than the camera/card dimensions (in which case `x` controls the position) or the media height is larger than the camera/card dimensions (in which case `y` controls the position). A value of `0` means maximally to the left or top of the media, a value of `100` means maximally to the right or bottom of the media. See [CSS object-position](https://developer.mozilla.org/en-US/docs/Web/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](https://caniuse.com/mdn-css_properties_object-view-box): ![](../../images/browsers/chrome_16x16.png 'Google Chrome :no-zoom') ![](../../images/browsers/chromium_16x16.png 'Chromium :no-zoom') ![](../../images/browsers/edge_16x16.png 'Microsoft Edge :no-zoom')                                                                                                             |
+| `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](../live.md?id=controls) will automatically be disabled (as otherwise they would be enlarged also).                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
+?> Layout operations are effectively applied in this order: `fit`, `position`, `view_box`, `zoom` then `pan`.
+
+See [media layout examples](../../examples.md?id=media-layout).
+
+#### Layout **Visualizations**
+
+##### `fit`
+
+![](../../images/media_layout/fit.png 'Media Layout Fit :size=400')
+
+##### `position`: When media is shorter than dimensions height
+
+![](../../images/media_layout/position-shorter-than-height.png 'Media Layout Position: Wider than taller :size=400')
+
+##### `position`: When media is thinner than dimensions width
+
+![](../../images/media_layout/position-thinner-than-width.png 'Media Layout Position: Taller than wider :size=400')
+
+#### `view_box`: Precise media cropping
+
+![](../../images/media_layout/view-box.png 'Media Layout Position: Taller than wider :size=400')
+
+#### `pan` and `zoom`: Predefined panning and zooming
+
+![](../../images/media_layout/pan-zoom.png 'Panning and zooming :size=400')
+
+## `ptz`
+
+Configure the PTZ actions taken for a camera (not to be confused with configuration of the PTZ _controls_, see [Live PTZ Controls](../live.md?id=ptz) or [Media Viewer PTZ Controls](../media-viewer.md?id=ptz)). Manually configured actions override any auto-detected actions.
+
+```yaml
+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](https://www.onvif.org/specs/srv/ptz/ONVIF-PTZ-Service-Spec.pdf)
+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](../actions/README.md) may be configured to call either variety.
+
+?> Frigate auto-detected PTZ actions will always be `continuous` as this is what
+the integration currently offers.
+
+### Parameters
+
+| Option                                                                                                                                                                                                                                                                   | Default                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actions_left`, `actions_right`, `actions_up`, `actions_down`, `actions_zoom_in`, `actions_zoom_out`, `actions_home`                                                                                                                                                     | Set by camera [engine](./engine.md) of the selected camera | The [perform-action](../actions/stock/README.md?id=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](./engine.md) of the selected camera | The [perform-action](../actions/stock/README.md?id=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](../actions/README.md)), then `start` will be called, followed by a delay of this number of seconds and finally `stop` will be called. Cameras / integrations that are slower to respond to continuous steps may need to increase this value to avoid the continuous motion being too small. Cameras / integrations that are rapid to respond may need to decrease this value to avoid the "relative step" being too large. |
+| `data_left`, `data_right`, `data_up`, `data_down`, `data_zoom_in`, `data_zoom_out`, `data_home`                                                                                                                                                                          |                                                            | Shorthand for relative actions that call the service defined by the `service` parameter, with the data provided in this argument. Internally, this is just translated into the longer-form `actions_[action]`. If both `actions_X` and `data_X` are specified, `actions_X` takes priority. This is compatible with [AlexxIT's WebRTC Card PTZ configuration](https://github.com/AlexxIT/WebRTC/wiki/PTZ-Config-Examples).                                                                                                                                                                                               |
+| `data_left_start`, `data_left_stop`, `data_right_start`, `data_right_stop`, `data_up_start`, `data_up_stop`, `data_down_start`, `data_down_stop`, `data_zoom_in_start`, `data_zoom_in_stop`, `data_zoom_out_start`, `data_zoom_out_stop`                                 |                                                            | Shorthand for continuous actions that call the service defined by the `service` parameter, with the data provided in this argument. Internally, this is just translated into the longer-form `actions_[action]_start` and `actions_[action]_stop`. If both `actions_X_*` and `data_X_*` are specified, `actions_X_*` takes priority. This is compatible with [AlexxIT's WebRTC Card PTZ configuration](https://github.com/AlexxIT/WebRTC/wiki/PTZ-Config-Examples). Both a `_start` and `_stop` variety must be provided for an action to be usable.                                                                    |
+| `presets`                                                                                                                                                                                                                                                                |                                                            | PTZ preset actions. See below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `r2c_delay_between_calls_seconds`                                                                                                                                                                                                                                        | `0.5`                                                      | When the camera is configured with relative actions only (e.g. `left` but not `left_start` and `left_stop`), if something requests a continuous action (e.g. the card PTZ controls have a button held down), then a delay of this number of seconds will be inserted between each call of the relative action. Cameras / integrations that are slower to respond to relative steps may need to increase this value to avoid multiple simultaneous actions being sent. Cameras / integrations that are rapid to respond may need to decrease this value to increase the appearance of one single continuous motion.      |
+| `service`                                                                                                                                                                                                                                                                |                                                            | An optional Home Assistant service to call when the `data_` parameters are used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+
+### `presets`
+
+Configures named PTZ presets. If a preset of this name is auto-detected, these configured actions will take precedence.
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    ptz:
+      presets:
+        [preset_name]:
+          ? [action]
+```
+
+`[action]` is any [perform-action](../actions/stock/README.md?id=perform-action) action.
+
+## `triggers`
+
+The `triggers` block configures what triggers a camera. Triggering can be used
+to activate an action (e.g. view a camera in live, reset the card to the default
+view). See [`view.triggers`](../view.md?id=triggers) to control what happens when a
+camera is triggered.
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    triggers:
+      # [...]
+```
+
+| Option      | Default                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ----------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entities`  |                              | Whether to not to trigger the camera when the state of any Home Assistant entity becomes active (i.e. state becomes `on` or `open`). This works for Frigate or non-Frigate cameras.                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `events`    | `[events, clips, snapshots]` | Whether to trigger the camera when `events` occur (whether or not media is available) or whenever updated `clips` or `snapshots` are detected. Detection support varies by camera [engine](engine.md).                                                                                                                                                                                                                                                                                                                                                                                    |
+| `motion`    | `false`                      | Whether to not to trigger the camera by automatically detecting and using the motion `binary_sensor` for this camera. This autodetection only works for Frigate cameras, and only when the motion `binary_sensor` entity has been enabled in Home Assistant.                                                                                                                                                                                                                                                                                                                              |
+| `occupancy` | `false`                      | Whether to not to trigger the camera by automatically detecting and using the occupancy `binary_sensor` for this camera and its configured zones and labels. This autodetection only works for Frigate cameras, and only when the occupancy `binary_sensor` entity has been enabled in Home Assistant. If this camera has configured zones, only occupancy sensors for those zones are used -- if the overall _camera_ occupancy sensor is also required, it can be manually added to `entities`. If this camera has configured labels, only occupancy sensors for those labels are used. |
+
+## Fully expanded reference
+
+[](../common/expanded-warning.md ':include')
+
+```yaml
+cameras:
+  - camera_entity: camera.front_Door
+    live_provider: ha
+    engine: auto
+    frigate:
+      url: http://my.frigate.local
+      client_id: frigate
+      camera_name: front_door
+      labels:
+       - person
+      zones:
+       - steps
+    # Show events for camera-2 when this camera is viewed.
+    dependencies:
+      all_cameras: false
+      cameras:
+        - camera-2
+    triggers:
+      motion: false
+      occupancy: true
+      entities:
+        - binary_sensor.front_door_sensor
+    cast:
+      method: standard
+    dimensions:
+      aspect_ratio: 16:9
+      layout:
+        fit: contain
+        position:
+          x: 50
+          y: 50
+  - camera_entity: camera.entrance
+    live_provider: webrtc-card
+    engine: auto
+    frigate:
+      url: http://my-other.frigate.local
+      client_id: frigate-other
+      camera_name: entrance
+      labels:
+       - car
+      zones:
+       - driveway
+    icon: 'mdi:car'
+    title: 'Front entrance'
+    # Custom identifier for the camera to refer to it above.
+    id: 'camera-2'
+    webrtc_card:
+      entity: camera.entrance_rtsp
+      url: 'rtsp://username:password@camera:554/av_stream/ch0'
+    triggers:
+      motion: false
+      occupancy: true
+      entities:
+        - binary_sensor.entrance_sensor
+    dependencies:
+      all_cameras: false
+  - camera_entity: camera.sitting_room
+    live_provider: go2rtc
+    go2rtc:
+      modes:
+        - webrtc
+        - mse
+        - mp4
+        - mjpeg
+      stream: sitting_room
+      url: 'https://my.custom.go2rtc.backend'
+      cast:
+        method: dashboard
+        dashboard:
+          dashboard_path: cast
+          view_path: front-door
+  - camera_entity: camera.sitting_room_webrtc_card
+    live_provider: webrtc_card
+    webrtc_card:
+      # Arbitrary WebRTC Card options, see https://github.com/AlexxIT/WebRTC#configuration .
+      entity: camera.sitting_room_rtsp
+      ui: true
+  - camera_entity: camera.kitchen
+    live_provider: jsmpeg
+    jsmpeg:
+      options:
+        audio: false
+        video: true
+        pauseWhenHidden: false
+        disableGl: false
+        disableWebAssembly: false
+        preserveDrawingBuffer: false
+        progressive: true
+        throttled: true
+        chunkSize: 1048576
+        maxAudioLag: 10
+        videoBufferSize: 524288
+        audioBufferSize: 131072
+  - camera_entity: camera.back_yard
+    live_provider: image
+    image:
+      mode: auto
+      refresh_seconds: 1
+      url: 'https://path/to/image.png'
+      entity: image.office_person
+      entity_parameters: 'width=400&height=200'
+  - camera_entity: camera.office_motioneye
+    motioneye:
+      images:
+        directory_pattern: '%Y-%m-%d'
+        file_pattern: '%H-%M-%S'
+      movies:
+        directory_pattern: '%Y-%m-%d'
+        file_pattern: '%H-%M-%S'
+  - camera_entity: camera.zoomed
+    dimensions:
+      layout:
+        zoom: 2.0
+        pan:
+          x: 50
+          y: 50
+  - camera_entity: camera.manual-ptz
+    ptz:
+      c2r_delay_between_calls_seconds: 0.2
+      r2c_delay_between_calls_seconds: 0.5
+      # Relative action (only `left` shown)
+      actions_left:
+        action: 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
+cameras_global:
+  live_provider: ha
+```

docs/configuration/cameras/_sidebar.md

@@ -0,0 +1,29 @@
+- [Getting Started](../../README.md)
+- [Configuration](../README.md)
+  - [`actions`](../actions/README.md)
+  - [`automations`](../automations.md)
+  - [`cameras`](README.md)
+    - [`live_provider`](live-provider.md)
+    - [`engine`](engine.md)
+  - [`conditions`](../conditions.md)
+  - [`dimensions`](../dimensions.md)
+  - [`elements`](../elements/README.md)
+  - [`image`](../image.md)
+  - [`live`](../live.md)
+  - [`media_gallery`](../media-gallery.md)
+  - [`media_viewer`](../media-viewer.md)
+  - [`menu`](../menu.md)
+  - [`overrides`](../overrides.md)
+  - [`performance`](../performance.md)
+  - [`profiles`](../profiles.md)
+  - [`status_bar`](../status-bar.md)
+  - [`timeline`](../timeline.md)
+  - [`view`](../view.md)
+- [Examples](../../examples.md)
+- [Screenshots](../../screenshots.md)
+- [Troubleshooting](../../troubleshooting.md)
+- [Usage](../../usage/README.md)
+
+---
+
+- [Developing](../../developing.md)

docs/configuration/cameras/engine.md

@@ -0,0 +1,82 @@
+# `engine`
+
+## Overview
+
+A "Camera Engine" defines what "type" of camera is being configured (e.g. `frigate`), each engine offers different capabilities:
+
+| Engine      | Live               | Supports clips           | Supports Snapshots       | Supports Recordings      | Supports Timeline        | Supports PTZ out of the box | Supports manually configured PTZ | Favorite events          | Favorite recordings      | Detect new events        | Detect new snapshots     | Detect new clips         |
+| ----------- | ------------------ | ------------------------ | ------------------------ | ------------------------ | ------------------------ | --------------------------- | -------------------------------- | ------------------------ | ------------------------ | ------------------------ | ------------------------ | ------------------------ |
+| `frigate`   | :white_check_mark: | :white_check_mark:       | :white_check_mark:       | :white_check_mark:       | :white_check_mark:       | :white_check_mark:          | :white_check_mark:               | :white_check_mark:       | :heavy_multiplication_x: | :white_check_mark:       | :white_check_mark:       | :white_check_mark:       |
+| `generic`   | :white_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x:    | :white_check_mark:               | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: |
+| `motioneye` | :white_check_mark: | :white_check_mark:       | :white_check_mark:       | :heavy_multiplication_x: | :white_check_mark:       | :heavy_multiplication_x:    | :white_check_mark:               | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: |
+
+#### Live providers supported per Engine
+
+| Engine / Live Provider | `ha`               | `image`            | `jsmpeg`                 | `go2rtc`           | `webrtc-card`            |
+| ---------------------- | ------------------ | ------------------ | ------------------------ | ------------------ | ------------------------ |
+| `frigate`              | :white_check_mark: | :white_check_mark: | :white_check_mark:       | :white_check_mark: | :white_check_mark:       |
+| `generic`              | :white_check_mark: | :white_check_mark: | :heavy_multiplication_x: | :white_check_mark: | :white_check_mark:       |
+| `motioneye`            | :white_check_mark: | :white_check_mark: | :heavy_multiplication_x: | :white_check_mark: | :heavy_multiplication_x: |
+
+See [Live Provider Configuration](live-provider.md) for more details on live providers.
+
+## `frigate`
+
+The `frigate` block configures options for a Frigate camera.
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    frigate:
+      # [...]
+```
+
+| Option        | Default                                                 | Description                                                                                                                                                                                                                                                                                                                                                       |
+| ------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                                                                                                                                                                              |
+| `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). |
+| `labels`      |                                                         | A list of Frigate labels used to filter events (clips & snapshots), e.g. [`person`, `car`].                                                                                                                                                                                                                                                                       |
+| `url`         |                                                         | The URL of the frigate server. If set, this value will be (exclusively) used for a `Camera UI` menu button. All other communication with Frigate goes via Home Assistant.                                                                                                                                                                                         |
+| `zones`       |                                                         | A list of Frigates zones used to filter events (clips & snapshots), e.g. [`front_door`, `front_steps`].                                                                                                                                                                                                                                                           |
+
+## `motioneye`
+
+The `motioneye` block configures options for a MotionEye camera.
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    motioneye:
+      # [...]
+```
+
+| Option   | Default | Description                                                                                                   |
+| -------- | ------- | ------------------------------------------------------------------------------------------------------------- |
+| `images` |         | Configure how MotionEye images are consumed. See below.                                                       |
+| `movies` |         | Configure how MotionEye movies are consumed. See below.                                                       |
+| `url`    |         | The URL of the MotionEye server. If set, this value will be (exclusively) used for a `Camera UI` menu button. |
+
+### `images` / `movies`
+
+The `images` and `movies` block configures how images and movies respectively are fetched from motionEye. The options for both blocks are the same.
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    motioneye:
+      images:
+        # [...]
+```
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    motioneye:
+      movies:
+        # [...]
+```
+
+| Option              | Default    | Description                                                                                                                                                                                                                                                                                                                               |
+| ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `directory_pattern` | `%Y-%m-%d` | The directory that motionEye is configured to store media into. May contain multiple sub-directories separated by `/`. Path must encode the date of the media using MotionEye patterns such as `%Y`, `%m`, `%d`, `%H`, `%M`, `%S` (at least one pattern is required). Consult MotionEye help text for information on these substitutions. |
+| `file_pattern`      | `%H-%M-%S` | Within a directory (as matched by `directory_pattern`) the media items must exist and match this pattern. `file_pattern` must encode the time of the media using MotionEye patterns such as `%Y`, `%m`, `%d`, `%H`, `%M`, `%S` (at least one pattern is required). Consult MotionEye help text for information on these substitutions.    |

docs/configuration/cameras/live-provider.md

@@ -0,0 +1,89 @@
+# `live_provider`
+
+## Overview
+
+The `live_provider` parameter determines what provides the live stream for a camera. Each provider offers different capabilities:
+
+| Live Provider                      | Latency | Frame Rate | Loading Time | Installation                   | Description                                                                                                                                                                                                     |
+| ---------------------------------- | ------- | ---------- | ------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `go2rtc`                           | Best    | High       | Better       | Builtin                        | Uses [go2rtc](https://github.com/AlexxIT/go2rtc) to stream live feeds. This is supported by Frigate >= `0.12`.                                                                                               |
+| `ha` (default HA configuration)    | Poor    | High       | Better       | Builtin                        | Use the built-in Home Assistant camera stream. The camera doesn't even need to be a Frigate camera!                                                                                                             |
+| `ha` (Native WebRTC)               | Best    | High       | Better       | Builtin                        | Use the built-in Home Assistant camera streams -- can be configured to use [native WebRTC](https://www.home-assistant.io/integrations/rtsp_to_webrtc/) offering a very low-latency feed direct to your browser. |
+| `ha` (when configured with LL-HLS) | Better  | High       | Better       | Builtin                        | Use the built-in Home Assistant camera streams -- can be configured to use an [LL-HLS](https://www.home-assistant.io/integrations/stream/#ll-hls) feed for lower latency.                                       |
+| `image`                            | Poor    | Poor       | Best         | Builtin                        | Use refreshing snapshots of the built-in Home Assistant camera streams.                                                                                                                                         |
+| `jsmpeg`                           | Better  | Low        | Poor         | Builtin                        | Use a the JSMPEG stream.                                                                                                                                                                                        |
+| `webrtc-card`                      | Best    | High       | Better       | Separate installation required | Embed's [AlexxIT's WebRTC Card](https://github.com/AlexxIT/WebRTC) to stream live feed, requires manual extra setup. See below. Not to be confused with native Home Assistant WebRTC (use the `ha` provider).   |
+
+## `go2rtc`
+
+The `go2rtc` block configures use of the `go2rtc` live provider. This configuration is included as part of a camera entry in the `cameras` list.
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    live_provider: go2rtc
+    go2rtc:
+      # [...]
+```
+
+| Option   | Default                                                                                                                                              | Description                                                                                                                                                                      |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modes`  | `[webrtc, mse, mp4, mjpeg]`                                                                                                                          | An ordered list of `go2rtc` modes to use. Valid values are `webrtc`, `mse`, `mp4` or `mjpeg` values.                                                                             |
+| `stream` | Determined by camera engine (e.g. `frigate` camera name).                                                                                            | A valid `go2rtc` stream name.                                                                                                                                                    |
+| `url`    | Determined by camera engine (e.g. the `frigate` engine will automatically generate a URL for the go2rtc backend that runs in the Frigate container). | The root `go2rtc` URL the card should stream the video from. This is only needed for non-Frigate usecases, or advanced Frigate usecases. Example: `http://my-custom-go2rtc:1984` |
+
+## `image`
+
+All configuration is under:
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    live_provider: image
+    image:
+      # [...]
+```
+
+| Option              | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entity`            |         | The entity to use when `mode` is set to `entity`. This entity is expected to have an `entity_picture` attribute that specifies the image URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `entity_parameters` |         | Optional URL parameters to add to the URL generated for entity-based modes (i.e. when `mode` is `camera` or `entity`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `mode`              | `auto`  | Value must be one of `url` (to fetch an arbitrary image URL), `camera` (to show a still of the currently selected camera entity using either `camera_entity` or `webrtc_card.entity` in that order of precedence), `entity` to show an image associated with a named entity (see the `entity` parameter below), or `screensaver` (to show an [embedded stock Frigate card logo](https://github.com/dermotduffy/frigate-hass-card/blob/main/src/images/frigate-bird-in-sky.jpg)). If `auto`, the mode is chosen automatically based on whether `url` or `entity` parameters have been specified. |
+| `refresh_seconds`   | 1       | The image will be refreshed at least every `refresh_seconds` (it may refresh more frequently, e.g. whenever Home Assistant updates its camera security token). `0` implies no refreshing.                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `url`               |         | A static image URL to be used when the `mode` is set to `url` or when a temporary image is required (e.g. may appear momentarily prior to load of a camera snapshot in the `camera` mode). Note that a `_t=[timestsamp]` query parameter will be automatically added to all URLs such that the image will not be cached by the browser.                                                                                                                                                                                                                                                         |
+
+## `jsmpeg`
+
+All configuration is under:
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    live_provider: jsmpeg
+    jsmpeg:
+      # [...]
+```
+
+| Option    | Default | 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. |
+
+## `webrtc_card`
+
+WebRTC Card support blends the use of the ultra-realtime [WebRTC card live
+view](https://github.com/AlexxIT/WebRTC) with convenient access to Frigate
+events/snapshots/UI. AlexxIT's WebRTC Integration/Card must be installed and configured separately (see [details](https://github.com/AlexxIT/WebRTC)) before it can be used with this card.
+
+```yaml
+cameras:
+  - camera_entity: camera.office
+    live_provider: webrtc-card
+    webrtc_card:
+      # [...]
+```
+
+| Option   | Default                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                     |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entity` |                                                                                                                                                                                                                     | The RTSP camera entity to pass to the WebRTC Card for this camera.                                                                                                                                                                                                                              |
+| `url`    | Depends on the camera engine (e.g. Frigate cameras will automatically use the camera name since this is the [recommended setup](https://deploy-preview-4055--frigate-docs.netlify.app/guides/configuring_go2rtc/)). | The RTSP url to pass to the WebRTC Card, e.g. `rtsp://USERNAME:PASSWORD@CAMERA:554/RTSP_PATH`                                                                                                                                                                                                   |
+| `*`      |                                                                                                                                                                                                                     | Any options specified in the `webrtc_card:` YAML dictionary are silently passed through to the AlexxIT's WebRTC Card. See [WebRTC Configuration](https://github.com/AlexxIT/WebRTC#configuration) for full details this external card provides, e.g. `ui: true` will enable the WebRTC Card UI. |

docs/configuration/common/expanded-warning.md

@@ -0,0 +1 @@
+!> Just copying this full reference into your configuration will cause you a significant maintenance burden. Don't do it! Only specify what you need, everything shown here are either default or illustrative values.

docs/configuration/common/timeline-seek-info.md

@@ -0,0 +1,4 @@
+?> For optimal UX, keep the settings for the mini-timeline in the `live` and
+`media_viewer` identical. Dragging the timeline may cause the card to change
+between the `live` view and `media_viewer` based views as the user pans between
+the past and present -- if the settings are different the timeline must "reset".

docs/configuration/conditions.md

@@ -0,0 +1,236 @@
+# `conditions`
+
+`conditions` is not a top-level configuration block, but can be used as part of
+multiple other blocks.
+
+Conditions are used to conditionally take action (in `automations`), to apply
+certain configurations (in `overrides`) or to display "picture elements" (in
+`elements`) depending on runtime evaluation.
+
+```yaml
+[used as part of other configuration]
+  conditions:
+    - [condition_1]
+    - [condition_2]
+```
+
+## `camera`
+
+```yaml
+conditions:
+  - condition: camera
+    # [...]
+```
+
+| Parameter   | Description                                                                                                  |
+| ----------- | ------------------------------------------------------------------------------------------------------------ |
+| `condition` | Must be `camera`.                                                                                            |
+| `cameras`   | A list of camera IDs in which this condition is satisfied. See the camera [id](cameras/README.md) parameter. |
+
+## `expand`
+
+```yaml
+conditions:
+  - condition: expand
+    # [...]
+```
+
+| Parameter   | Description                                                                                                                                                                                  |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `condition` | Must be `expand`.                                                                                                                                                                            |
+| `expand`    | If `true` the condition is satisfied if the card is in expanded mode (in a dialog/popup). If `false` the condition is satisfied if the card is **NOT** in expanded mode (in a dialog/popup). |
+
+## `fullscreen`
+
+```yaml
+conditions:
+  - condition: fullscreen
+    # [...]
+```
+
+| Parameter    | Description                                                                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `condition`  | Must be `fullscreen`.                                                                                                                                    |
+| `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. |
+
+## `interaction`
+
+```yaml
+conditions:
+  - condition: interaction
+    # [...]
+```
+
+| Parameter     | Description                                                                                                                                                                                                                     |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `condition`   | Must be `interaction`.                                                                                                                                                                                                          |
+| `interaction` | If `true` the condition is satisfied if the card has had human interaction within `view.interaction_seconds` elapsed seconds. If `false` the condition is satisfied if the card has **NOT** had human interaction in that time. |
+
+## `key`
+
+```yaml
+conditions:
+  - condition: key
+    # [...]
+```
+
+| Parameter   | Default | Description                                                                                                                       |
+| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `condition` | -       | Must be `key`.                                                                                                                    |
+| `alt`       | `false` | An optional value to match whether the `alt` key is being held.                                                                   |
+| `ctrl`      | `false` | An optional value to match whether the `ctrl` key is being held.                                                                  |
+| `key`       |         | Any [keyboard key value](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values), e.g. `ArrowLeft`. |
+| `meta`      | `false` | An optional value to match whether the `meta` key is being held.                                                                  |
+| `shift`     | `false` | An optional value to match whether the `shift` key is being held.                                                                 |
+| `state`     | `down`  | An optional value to match the state of the. Must be one of `down` or `up`.                                                       |
+
+## `media_loaded`
+
+```yaml
+conditions:
+  - condition: media_loaded
+    # [...]
+```
+
+| Parameter      | Description                                                                                                                                                                                                                                    |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `condition`    | Must be `media_loaded`.                                                                                                                                                                                                                        |
+| `media_loaded` | If `true` the condition is satisfied if there is media load**ED** (not load**ING**) in the card (e.g. a clip, snapshot or live view). This may be used to hide controls during media loading or when a message (not media) is being displayed. |
+
+## `microphone`
+
+```yaml
+conditions:
+  - condition: microphone
+    # [...]
+```
+
+| Parameter   | Description                                                                                                            |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `condition` | Must be `microphone`.                                                                                                  |
+| `connected` | Optional: If `true` or `false` the condition is satisfied if the microphone is connected or disconnected respectively. |
+| `muted`     | Optional: If `true` or `false` the condition is satisfied if the microphone is muted or unmuted respectively.          |
+
+## `numeric_state`
+
+```yaml
+conditions:
+  - condition: numeric_state
+    # [...]
+```
+
+This stock Home Assistant condition works out of the box. See [Home Assistant conditions documentation](https://www.home-assistant.io/dashboards/conditional/#numeric-state).
+
+## `screen`
+
+```yaml
+conditions:
+  - condition: screen
+    # [...]
+```
+
+| Parameter     | Description                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `condition`   | Must be `screen`.                                                                                                                                                                                                                                                                                                                                                              |
+| `media_query` | Any valid [media query](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries) string. Media queries must start and end with parentheses. This may be used to alter card configuration based on device/media properties (e.g. viewport width, orientation). Please note that `width` and `height` refer to the entire viewport not just the card. |
+
+See the [screen conditions examples](../examples.md?id=screen-conditions).
+
+## `state`
+
+```yaml
+conditions:
+  - condition: state
+    # [...]
+```
+
+This stock Home Assistant condition works out of the box. See [Home Assistant conditions documentation](https://www.home-assistant.io/dashboards/conditional/#state).
+
+## `triggered`
+
+```yaml
+conditions:
+  - condition: triggered
+    # [...]
+```
+
+| Parameter   | Description                                                                                       |
+| ----------- | ------------------------------------------------------------------------------------------------- |
+| `condition` | Must be `triggered`.                                                                              |
+| `triggered` | A list of camera IDs which, if [triggered](cameras/README.md?id=triggers), satisfy the condition. |
+
+## `user`
+
+```yaml
+conditions:
+  - condition: user
+    # [...]
+```
+
+This stock Home Assistant condition works out of the box. See [Home Assistant conditions documentation](https://www.home-assistant.io/dashboards/conditional/#user).
+
+## `view`
+
+```yaml
+conditions:
+  - condition: view
+    # [...]
+```
+
+| Parameter   | Description                                                                                       |
+| ----------- | ------------------------------------------------------------------------------------------------- |
+| `condition` | Must be `view`.                                                                                   |
+| `views`     | A list of [views](view.md?id=supported-views) in which this condition is satified (e.g. `clips`). |
+
+?> Internally, views associated with the media viewer (e.g. `clip`, `snapshot`,
+`recording`) are translated to a special view called `media` after the relevant
+media is fetched. When including views as part of a [condition](conditions.md),
+you may need to refer to this special `media` view.
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+conditions:
+ - condition: camera
+   cameras:
+     - camera.office
+  - condition: expand
+    expand: true
+  - condition: fullscreen
+    fullscreen: true
+  - condition: interaction
+    interaction: true
+  - condition: key
+    alt: false
+    ctrl: false
+    key: F
+    meta: false
+    shift: false
+    state: down
+  - condition: media_loaded
+    media_loaded: true
+  - condition: microphone
+    connected: true
+    muted: true
+  - condition: numeric_state
+    entity: sensor.office_temperature
+    above: 10
+    below: 20
+  - condition: screen
+    media_query: '(orientation: landscape)'
+  - condition: state
+    entity: climate.office
+    state: heat
+    state_not: off
+  - condition: triggered
+    triggered:
+      - camera.office
+  - condition: user
+    users:
+      - 581fca7fdc014b8b894519cc531f9a04
+  - condition: view
+    views:
+      - live
+```

docs/configuration/dimensions.md

@@ -0,0 +1,47 @@
+# `dimensions`
+
+These options control the dimensions and aspect-ratio of the card (See [Camera
+Dimensions](./cameras/README.md?id=dimensions) to set the dimensions of a camera
+and not the whole card). These options configuration applies once to the entire
+card (including the menu, thumbnails, etc), not just to displayed media. This
+only applies to the card in normal render mode -- when in fullscreen, or when in
+expanded (popup/dialog mode) the aspect ratio is chosen dynamically to maximize
+the amount of content shown.
+
+```yaml
+dimensions:
+  # [...]
+```
+
+| Option              | Default   | Description                                                                                                                                                                                                                                                            |
+| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `aspect_ratio_mode` | `dynamic` | The aspect ratio mode to use. Acceptable values: `dynamic`, `static`, `unconstrained`. See below.                                                                                                                                                                      |
+| `aspect_ratio`      | `16:9`    | The aspect ratio to use. Acceptable values: `[W]:[H]` or `[W]/[H]`. See below.                                                                                                                                                                                         |
+| `max_height`        | `100vh`   | The maximum allowable height for the card. Specified in [CSS units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units). Generally users should not need to change this setting unless they have set an `unconstrained` aspect ratio. |
+| `min_height`        | `100px`   | The minimum allowable height for the card. Specified in [CSS units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units). Generally users should not need to change this setting.                                                      |
+
+### `aspect_ratio_mode`
+
+| Option          | Description                                                                                                                                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dynamic`       | The aspect-ratio of the entire card will match the aspect-ratio of the last selected media item.                                                                                                                    |
+| `static`        | A fixed aspect-ratio (as defined by `aspect_ratio`) will be applied to the card.                                                                                                                                    |
+| `unconstrained` | No aspect ratio is enforced in any view, the card will expand with the content. This may be especially useful for a panel-mode dashboard, or in views that have no intrinsic aspect-ratio (e.g. the media gallery). |
+
+### `aspect_ratio`
+
+- `16 / 9` or `16:9`: Default widescreen ratio.
+- `4 / 3` or `4:3`: Default fullscreen ratio.
+- `[W]/[H]` or `[W]:[H]`: Any arbitrary aspect-ratio.
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+dimensions:
+  aspect_ratio_mode: dynamic
+  aspect_ratio: 16:9
+  max_height: 100vh
+  min_height: 100px
+```

docs/configuration/elements/README.md

@@ -0,0 +1,24 @@
+# `elements`
+
+## Introduction to elements <!-- {docsify-ignore} -->
+
+This card supports the [Picture Elements configuration
+syntax](https://www.home-assistant.io/lovelace/picture-elements/) to seamlessly
+allow the user to add custom elements to the card.
+
+```yaml
+elements:
+  - [element_1]
+  - [element_2]
+```
+
+?> The Frigate Card allows either a single [action](../actions/README.md) (as in stock Home
+Assistant) or list of [actions](../actions/README.md) to be defined for each class of user interaction
+(e.g. `tap`, `double_tap`, `hold`, etc). See [an example of multiple actions](../../examples.md?id=multiple-actions).
+
+## Elements <!-- {docsify-ignore} -->
+
+| Option                                | Description                       |
+| ------------------------------------- | --------------------------------- |
+| [Custom Elements](./custom/README.md) | Custom elements.                  |
+| [Stock Elements](./stock/README.md)   | Standard Home Assistant elements. |

docs/configuration/elements/_sidebar.md

@@ -0,0 +1,29 @@
+- [Getting Started](../../README.md)
+- [Configuration](../README.md)
+  - [`actions`](../actions/README.md)
+  - [`automations`](../automations.md)
+  - [`cameras`](../cameras/README.md)
+  - [`conditions`](../conditions.md)
+  - [`dimensions`](../dimensions.md)
+  - [`elements`](README.md)
+    - [Custom Elements](./custom/README.md)
+    - [Stock Elements](./stock/README.md)
+  - [`image`](../image.md)
+  - [`live`](../live.md)
+  - [`media_gallery`](../media-gallery.md)
+  - [`media_viewer`](../media-viewer.md)
+  - [`menu`](../menu.md)
+  - [`overrides`](../overrides.md)
+  - [`performance`](../performance.md)
+  - [`profiles`](../profiles.md)
+  - [`status_bar`](../status-bar.md)
+  - [`timeline`](../timeline.md)
+  - [`view`](../view.md)
+- [Examples](../../examples.md)
+- [Screenshots](../../screenshots.md)
+- [Troubleshooting](../../troubleshooting.md)
+- [Usage](../../usage/README.md)
+
+---
+
+- [Developing](../../developing.md)

docs/configuration/elements/custom/README.md

@@ -0,0 +1,258 @@
+# Custom Elements
+
+## `conditional`
+
+Restrict a set of elements to only render when the card is matches a set of [conditions](../../conditions.md). This is analogous to the stock [`conditional`](../stock/README.md?id=conditional) element except supporting a rich set of Frigate Card [conditions](../../conditions.md).
+
+```yaml
+elements:
+  - type: custom:frigate-card-conditional
+    # [...]
+```
+
+Parameters for the `custom:frigate-card-conditional` element:
+
+| Parameter    | Description                                                                                                      |
+| ------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `type`       | Must be `custom:frigate-card-conditional`.                                                                       |
+| `conditions` | A list of [conditions](../../conditions.md) that must evaluate to true in order for the elements to be rendered. |
+| `elements`   | The elements to render. Can be any supported element.                                                            |
+
+See the [conditional elements example](../../../examples.md?id=conditional-elements).
+
+## `menu-icon`
+
+Add an arbitrary icon to the Frigate Card menu. Configuration is ~identical to that of the [Picture Elements Icon](https://www.home-assistant.io/lovelace/picture-elements/#icon-element) except with a type name of `custom:frigate-card-menu-icon`.
+
+```yaml
+elements:
+  - type: custom:frigate-card-menu-icon
+    # [...]
+```
+
+## `menu-submenu`
+
+Add a configurable submenu dropdown.
+
+```yaml
+elements:
+  - type: custom:frigate-card-menu-submenu
+    # [...]
+```
+
+Parameters for this element are identical to the parameters of the [stock Home Assistant Icon Element](https://www.home-assistant.io/lovelace/picture-elements/#icon-element) with the exception of these parameters which differ:
+
+| Parameter | Description                                 |
+| --------- | ------------------------------------------- |
+| `type`    | Must be `custom:frigate-card-menu-submenu`. |
+| `items`   | A list of menu items, as described below.   |
+
+### Submenu items
+
+| Parameter                                                                | Default | Description                                                                                       |
+| ------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
+| `enabled`                                                                | `true`  | Whether or not to show this item as enabled / selectable.                                         |
+| `entity`                                                                 |         | An optional Home Assistant entity from which title, icon and style can be automatically computed. |
+| `icon`                                                                   |         | An optional item icon to display, e.g. `mdi:car`                                                  |
+| `selected`                                                               | `false` | Whether or not to show this item as selected.                                                     |
+| `state_color`                                                            | `true`  | Whether or not the title and icon should be stylized based on state.                              |
+| `style`                                                                  |         | Position and style the element using CSS.                                                         |
+| `tap_action`, `double_tap_action`, `hold_action`, `start_tap`, `end_tap` |         | The [actions](../../actions/README.md) to take when this item is interacted with.                 |
+| `title`                                                                  |         | An optional title to display.                                                                     |
+
+## `menu-submenu-select`
+
+Add a submenu based on a `select` or `input_select`. This element allows you to convert a [Home Assistant Select Entity](https://www.home-assistant.io/integrations/select/) or [Home Assistant Input Select Entity](https://www.home-assistant.io/integrations/input_select/) (an entity either starting with `select` or `input_select`) into an overridable submenu. This _could_ be done by hand using a regular submenu (above) -- this element is a convenience.
+
+```yaml
+elements:
+  - type: custom:frigate-card-menu-submenu-select
+    # [...]
+```
+
+Parameters for the `custom:frigate-card-menu-submenu-select` element are identical to the parameters of the [stock Home Assistant State Icon Element](https://www.home-assistant.io/dashboards/picture-elements/#state-icon) with the exception of these parameters which differ:
+
+| Parameter | Description                                                                                                                                                                                                                                                                        |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`    | Must be `custom:frigate-card-menu-submenu-select`.                                                                                                                                                                                                                                 |
+| `options` | An optional dictionary of overrides keyed by the option name that the given select entity supports. These options can be used to set or override submenu item parameters on a per-option basis. The format is as described in [Submenu Items](./README.md?id=submenu-items) above. |
+
+See the `select` [submenu example](../../../examples.md?id=select-submenu).
+
+## `state-icon`
+
+Add a state icon to the Frigate Card menu that represents the state of a Home Assistant entity. Configuration is ~identical to that of the [Picture Elements State Icon](https://www.home-assistant.io/lovelace/picture-elements/#state-icon) except with a type name of `custom:frigate-card-menu-state-icon`.
+
+```yaml
+elements:
+  - type: custom:frigate-card-menu-icon
+    # [...]
+```
+
+## `status-bar-icon`
+
+Add an arbitrary icon to the status bar.
+
+```yaml
+elements:
+  - type: custom:frigate-card-status-bar-icon
+    # [...]
+```
+
+| Parameter    | Default | Description                                                                                                                                                                                                              |
+| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`       |         | Must be `custom:frigate-card-status-bar-icon`.                                                                                                                                                                           |
+| `actions`    |         | Actions to performs when the status bar item is interacted with. See [actions](../../actions/README.md).                                                                                                                 |
+| `enabled`    | `true`  | `true` to enable this status bar item, `false` to disable.                                                                                                                                                               |
+| `exclusive`  | `false` | Whether or not this item should evict non-exclusive items from the status bar.                                                                                                                                           |
+| `expand`     | `false` | If `false` this status bar item will consume the minimum possible space, if `true` will expand to the available space.                                                                                                   |
+| `icon`       |         | The icon to show in the status bar, e.g. `mdi:camera-front`.                                                                                                                                                             |
+| `priority`   | `50`    | The item priority. Higher priority items are ordered closer to the start of the status bar (i.e. an item with priority `70` will order further to the left than an item with priority `60`). Minimum `0`, maximum `100`. |
+| `sufficient` | `false` | Whether or not this item is sufficient to display the status bar if it's otherwise hidden (e.g. with the `popup` [status bar style](../../status-bar.md)).                                                               |
+
+## `status-bar-image`
+
+Add an arbitrary image to the status bar.
+
+```yaml
+elements:
+  - type: custom:frigate-card-status-bar-image
+    # [...]
+```
+
+| Parameter    | Default | Description                                                                                                                                                                                                              |
+| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`       |         | Must be `custom:frigate-card-status-bar-image`.                                                                                                                                                                          |
+| `actions`    |         | Actions to performs when the status bar item is interacted with. See [actions](../../actions/README.md).                                                                                                                 |
+| `enabled`    | `true`  | `true` to enable this status bar item, `false` to disable.                                                                                                                                                               |
+| `exclusive`  | `false` | Whether or not this item should evict non-exclusive items from the status bar.                                                                                                                                           |
+| `expand`     | `false` | If `false` this status bar item will consume the minimum possible space, if `true` will expand to the available space.                                                                                                   |
+| `image`      |         | The image to show in the status bar, e.g. `https://my.site.com/status.png`.                                                                                                                                              |
+| `priority`   | `50`    | The item priority. Higher priority items are ordered closer to the start of the status bar (i.e. an item with priority `70` will order further to the left than an item with priority `60`). Minimum `0`, maximum `100`. |
+| `sufficient` | `false` | Whether or not this item is sufficient to display the status bar if it's otherwise hidden (e.g. with the `popup` [status bar style](../../status-bar.md)).                                                               |
+
+## `status-bar-string`
+
+Add an arbitrary string to the status bar.
+
+```yaml
+elements:
+  - type: custom:frigate-card-status-bar-string
+    # [...]
+```
+
+| Parameter    | Default | Description                                                                                                                                                                                                              |
+| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`       |         | Must be `custom:frigate-card-status-bar-string`.                                                                                                                                                                         |
+| `actions`    |         | Actions to performs when the status bar item is interacted with. See [actions](../../actions/README.md).                                                                                                                 |
+| `enabled`    | `true`  | `true` to enable this status bar item, `false` to disable.                                                                                                                                                               |
+| `exclusive`  | `false` | Whether or not this item should evict non-exclusive items from the status bar.                                                                                                                                           |
+| `expand`     | `false` | If `false` this status bar item will consume the minimum possible space, if `true` will expand to the available space.                                                                                                   |
+| `string`     |         | The string to show in the status bar, e.g. `Intruder detected!`                                                                                                                                                          |
+| `priority`   | `50`    | The item priority. Higher priority items are ordered closer to the start of the status bar (i.e. an item with priority `70` will order further to the left than an item with priority `60`). Minimum `0`, maximum `100`. |
+| `sufficient` | `false` | Whether or not this item is sufficient to display the status bar if it's otherwise hidden (e.g. with the `popup` [status bar style](../../status-bar.md)).                                                               |
+
+## Fully expanded reference
+
+> [Actions](../../actions/README.md) are omitted for simplicity.
+
+[](../../common/expanded-warning.md ':include')
+
+```yaml
+elements:
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:car
+    title: Vroom
+  - type: custom:frigate-card-menu-state-icon
+    entity: light.office_main_lights
+    title: Office lights
+    icon: mdi:chair-rolling
+    state_color: true
+  - type: custom:frigate-card-menu-submenu
+    icon: mdi:menu
+    items:
+      - title: Lights
+        icon: mdi:lightbulb
+        entity: light.office_main_lights
+        tap_action:
+          action: toggle
+      - title: Google
+        icon: mdi:google
+        enabled: false
+        tap_action:
+          action: url
+          url_path: https://www.google.com
+  - type: custom:frigate-card-menu-submenu-select
+    icon: mdi:lamps
+    entity: input_select.kitchen_scene
+    options:
+      scene.kitchen_cooking_scene:
+        icon: mdi:chef-hat
+        title: Cooking time!
+      scene.kitchen_tv_scene:
+        icon: mdi:television
+        title: TV!
+    # Show a pig icon if a variety of conditions are met.
+  - type: custom:frigate-card-conditional
+    elements:
+      - type: icon
+        icon: mdi:pig
+        title: Oink
+        style:
+          left: 300px
+          top: 100px
+    conditions:
+      - condition: view
+        views:
+          - live
+      - condition: fullscreen
+        fullscreen: true
+      - condition: expand
+        expand: true
+      - condition: camera
+        cameras: camera.front_door
+      - condition: media_loaded
+        media_loaded: true
+      - condition: display_mode
+        display_mode: single
+      - condition: triggered
+        triggered:
+          - camera.front_door
+      - condition: interaction
+        interaction: true
+      - condition: microphone
+        muted: true
+        connected: true
+      - condition: state
+        entity: light.office_main_lights
+        state: on
+        state_not: off
+      - condition: numeric_state
+        entity: sensor.light_level
+        above: 20
+        below: 100
+      - condition: user
+        users:
+          - 581fca7fdc014b8b894519cc531f9a04
+  - type: custom:frigate-card-status-bar-string
+    enabled: true
+    exclusive: false
+    expand: false
+    string: 'Intruder alert!'
+    priority: 50
+    sufficient: false
+  - type: custom:frigate-card-status-bar-icon
+    enabled: true
+    exclusive: false
+    expand: false
+    icon: 'mdi:cow'
+    priority: 50
+    sufficient: false
+  - type: custom:frigate-card-status-bar-image
+    enabled: true
+    exclusive: false
+    expand: false
+    image: https://my.site.com/status.png
+    priority: 50
+    sufficient: false
+```

docs/configuration/elements/custom/_sidebar.md

@@ -0,0 +1,29 @@
+- [Getting Started](../../../README.md)
+- [Configuration](../../README.md)
+  - [`actions`](../README.md)
+  - [`automations`](../../automations.md)
+  - [`cameras`](../../cameras/README.md)
+  - [`conditions`](../../conditions.md)
+  - [`dimensions`](../../dimensions.md)
+  - [`elements`](../../elements/README.md)
+    - [Custom Actions](README.md)
+    - [Stock Actions](../stock/README.md)
+  - [`image`](../../image.md)
+  - [`live`](../../live.md)
+  - [`media_gallery`](../../media-gallery.md)
+  - [`media_viewer`](../../media-viewer.md)
+  - [`menu`](../../menu.md)
+  - [`overrides`](../../overrides.md)
+  - [`performance`](../../performance.md)
+  - [`profiles`](../../profiles.md)
+  - [`status_bar`](../../status-bar.md)
+  - [`timeline`](../../timeline.md)
+  - [`view`](../../view.md)
+- [Examples](../../../examples.md)
+- [Screenshots](../../../screenshots.md)
+- [Troubleshooting](../../../troubleshooting.md)
+- [Usage](../../../usage/README.md)
+
+---
+
+- [Developing](../../../developing.md)

docs/configuration/elements/stock/README.md

@@ -0,0 +1,173 @@
+# Stock Elements
+
+## `conditional`
+
+This element will let you show its sub-elements based on entity states. See [Home Assistant elements documentation](https://www.home-assistant.io/dashboards/picture-elements/#conditional-element).
+
+```yaml
+elements:
+  - type: conditional
+    # [...]
+```
+
+## `custom`
+
+Custom elements provided by a card. See [Home Assistant elements documentation](https://www.home-assistant.io/dashboards/picture-elements/#custom-elements).
+
+```yaml
+elements:
+  - type: custom
+    # [...]
+```
+
+?> See [Frigate Card custom elements](../custom//README.md) for the custom elements offered by _this_ card.
+
+## `icon`
+
+This element creates a static icon that is not linked to the state of an entity. See [Home Assistant elements documentation](https://www.home-assistant.io/dashboards/picture-elements/#icon-element).
+
+```yaml
+elements:
+  - type: icon
+    # [...]
+```
+
+## `image`
+
+This creates an image element that overlays the background image. See [Home Assistant elements documentation](https://www.home-assistant.io/dashboards/picture-elements/#image-element).
+
+```yaml
+elements:
+  - type: image
+    # [...]
+```
+
+## `service-button`
+
+This entity creates a button (with arbitrary text) that can be used to call a service. See [Home Assistant elements documentation](https://www.home-assistant.io/dashboards/picture-elements/#service-call-button).
+
+```yaml
+elements:
+  - type: service-button
+    # [...]
+```
+
+## `state-badge`
+
+This element creates a badge representing the state of an entity. See [Home Assistant elements documentation](https://www.home-assistant.io/dashboards/picture-elements/#state-badge).
+
+```yaml
+elements:
+  - type: state-badge
+    # [...]
+```
+
+## `state-icon`
+
+This element represents an entity state using an icon. See [Home Assistant elements documentation](https://www.home-assistant.io/dashboards/picture-elements/#state-icon).
+
+```yaml
+elements:
+  - type: state-icon
+    # [...]
+```
+
+## `state-label`
+
+This element represents an entity’s state via text. See [Home Assistant elements documentation](https://www.home-assistant.io/dashboards/picture-elements/#state-label).
+
+```yaml
+elements:
+  - type: state-label
+    # [...]
+```
+
+## Fully expanded reference
+
+> [Actions](../../actions/README.md) are omitted for simplicity.
+
+[](../../common/expanded-warning.md ':include')
+
+Reference: [Home Assistant Picture Elements](https://www.home-assistant.io/dashboards/picture-elements/)
+
+```yaml
+elements:
+  - type: state-badge
+    entity: sensor.kitchen_dining_multisensor_air_temperature
+    style:
+      left: 100px
+      top: 50px
+    title: 'Temperature'
+  - type: state-icon
+    entity: light.office_main_lights
+    icon: mdi:lamp
+    state_color: true
+    style:
+      left: 100px
+      top: 100px
+  - type: state-label
+    entity: sensor.kitchen_motion_sensor_battery
+    attribute: battery_voltage
+    prefix: Volts
+    title: Battery Voltage
+    style:
+      left: 100px
+      top: 150px
+  - type: state-label
+    entity: sensor.kitchen_motion_sensor_battery
+    attribute: battery_voltage
+    prefix: 'Volts: '
+    title: Battery Voltage
+    style:
+      background-color: black
+      left: 100px
+      top: 200px
+  - type: service-button
+    title: Light on
+    service: homeassistant.turn_on
+    service_data:
+      entity: light.office_main_lights
+    style:
+      left: 100px
+      top: 250px
+  - type: icon
+    icon: mdi:cow
+    title: Moo
+    style:
+      left: 100px
+      top: 300px
+  - type: image
+    entity: light.office_main_lights
+    title: Image
+    state_image:
+      on: 'https://picsum.photos/id/1003/1181/1772'
+      off: 'https://picsum.photos/id/102/4320/3240'
+    state_filter:
+      'on': brightness(110%) saturate(1.2)
+      'off': brightness(50%) hue-rotate(45deg)
+    style:
+      left: 100px
+      top: 350px
+      height: 50px
+      width: 100px
+  - type: conditional
+    conditions:
+      - condition: state
+        entity: light.office_main_lights
+        state: on
+        state_not: off
+      - condition: numeric_state
+        entity: sensor.light_level
+        above: 20
+        below: 100
+      - condition: user
+        users:
+          - 581fca7fdc014b8b894519cc531f9a04
+    elements:
+      - type: icon
+        icon: mdi:dog
+        title: Woof
+        style:
+          left: 100px
+          top: 400px
+```

docs/configuration/elements/stock/_sidebar.md

@@ -0,0 +1,29 @@
+- [Getting Started](../../../README.md)
+- [Configuration](../../README.md)
+  - [`actions`](../README.md)
+  - [`automations`](../../automations.md)
+  - [`cameras`](../../cameras/README.md)
+  - [`conditions`](../../conditions.md)
+  - [`dimensions`](../../dimensions.md)
+  - [`elements`](../../elements/README.md)
+    - [Custom Actions](../custom/README.md)
+    - [Stock Actions](README.md)
+  - [`image`](../../image.md)
+  - [`live`](../../live.md)
+  - [`media_gallery`](../../media-gallery.md)
+  - [`media_viewer`](../../media-viewer.md)
+  - [`menu`](../../menu.md)
+  - [`overrides`](../../overrides.md)
+  - [`performance`](../../performance.md)
+  - [`profiles`](../../profiles.md)
+  - [`status_bar`](../../status-bar.md)
+  - [`timeline`](../../timeline.md)
+  - [`view`](../../view.md)
+- [Examples](../../../examples.md)
+- [Screenshots](../../../screenshots.md)
+- [Troubleshooting](../../../troubleshooting.md)
+- [Usage](../../../usage/README.md)
+
+---
+
+- [Developing](../../../developing.md)

docs/configuration/grid-layout-algorithm.md

@@ -0,0 +1,10 @@
+# Grid Layout Algorithm
+
+When display mode (in `live` or `media_viewer` views) is set to `grid`, it will lay out cameras roughly in the order they are specified in the config (items may be moved to optimize grid 'density').
+
+The following algorithm is used to calculate the number of columns. This attempts to offers a balance between configurability, reasonable display in a typical Lovelace card width and reasonable display in a typical fullscreen display.
+
+- Use `grid_columns` if specified.
+- Otherwise, use the largest number of columns in the range `[2 - grid_max_columns]` that will fit at least a `600px` column width.
+- Otherwise, use the largest number of columns in the range `[2 - grid_max_columns]` that will fit at least a `190px` column width.
+- Otherwise, there will be `1` column only.

docs/configuration/image.md

@@ -0,0 +1,44 @@
+# `image`
+
+Configure the `image` view.
+
+```yaml
+image:
+  # [...]
+```
+
+| Option              | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actions`           |         | [Actions](actions/README.md) to use for the `image` view.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `entity`            |         | The entity to use when `mode` is set to `entity`. This entity is expected to have an `entity_picture` attribute that specifies the image URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `entity_parameters` |         | Optional URL parameters to add to the URL generated for entity-based modes (i.e. when `mode` is `camera` or `entity`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `mode`              | `auto`  | Value must be one of `url` (to fetch an arbitrary image URL), `camera` (to show a still of the currently selected camera entity using either `camera_entity` or `webrtc_card.entity` in that order of precedence), `entity` to show an image associated with a named entity (see the `entity` parameter below), or `screensaver` (to show an [embedded stock Frigate card logo](https://github.com/dermotduffy/frigate-hass-card/blob/main/src/images/frigate-bird-in-sky.jpg)). If `auto`, the mode is chosen automatically based on whether `url` or `entity` parameters have been specified. |
+| `refresh_seconds`   | 1       | The image will be refreshed at least every `refresh_seconds` (it may refresh more frequently, e.g. whenever Home Assistant updates its camera security token). `0` implies no refreshing.                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `url`               |         | A static image URL to be used when the `mode` is set to `url` or when a temporary image is required (e.g. may appear momentarily prior to load of a camera snapshot in the `camera` mode). Note that a `_t=[timestsamp]` query parameter will be automatically added to all URLs such that the image will not be cached by the browser.                                                                                                                                                                                                                                                         |
+
+?> When `mode` is set to `camera` this is effectively providing the same image as the `image` [live provider](cameras/live-provider.md) would show in the live camera carousel.
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+image:
+  mode: auto
+  refresh_seconds: 1
+  url: 'https://path/to/image.png'
+  entity: image.office_person
+  entity_parameters: 'width=400&height=200'
+  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
+```

docs/configuration/live.md

@@ -0,0 +1,236 @@
+# `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]` | A list of conditions in which live camera feeds are muted. `unselected` will automatically mute when a camera is unselected in the carousel, `hidden` will automatically mute when the browser/tab becomes hidden or `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). 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 and `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 the carousel and `visible` will automatically play when the browser/tab becomes visible. 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 flag on play-after-pause.                                                                                                                                                                                                                                                                                                 |
+| `auto_unmute`            | `[microphone]`                     | A list of conditions in which live camera feeds are unmuted. `selected` will automatically unmute when a camera is unselected in the carousel, `visible` will automatically unmute when the browser/tab becomes visible or `microphone` will automatically unmute after the microphone is unmuted. Use an empty list (`[]`) to never automatically unmute.                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `controls`               |                                    | Configuration for the `live` view controls. See below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `display`                |                                    | Controls whether to show a single or grid `live` view. See below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `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 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.                                                                                                                                                                                                                                                                                                                                                                               |
+| `lazy_unload`            | `[]`                               | A list of conditions in which live camera feeds are unloaded. `unselected` will lazy-unload a camera when it is unselected in the carousel and `hidden` will lazy-unload all cameras when the browser/tab becomes hidden. Use an empty list (`[]`) to never automatically unload. This will cause a reloading delay on revisiting that camera in the carousel but will save the streaming network resources that are otherwise consumed. This option has no effect if `lazy_load` is false. 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 below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `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. 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.                   |
+| `next_previous` |         | Configures how the "Next & Previous" controls are shown on the `live` view. See below. |
+| `thumbnails`    |         | Configures how thumbnails are shown on the `live` view. See below.                     |
+| `timeline`      |         | Configures how the mini-timeline is shown on the `live` view. See below.               |
+
+### `next_previous`
+
+Configures how the "Next & Previous" controls are shown on the live view.
+
+```yaml
+live:
+  controls:
+    next_previous:
+      # [...]
+```
+
+| Option  | Default    | Description                                                                                                                                    |
+| ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 button of the control is hidden                                                                                                                                                                            |
+| `hide_pan_tilt` | `false`        | When `true` the Pan & Tilt buttons of the control is hidden                                                                                                                                                                     |
+| `hide_zoom`     | `false`        | When `true` the Zoom button of the control is hidden                                                                                                                                                                            |
+| `mode`          | `auto`         | If `on` or `off` will always or never show PTZ controls respectively, if `auto` will show PTZ controls only if the camera supports real PTZ.                                                                                    |
+| `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%` |
+
+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                                                                                                                                                                   |
+| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `events_media_type`     | `all`    | Whether to show `clips`, `snapshots` or `all` in the thumbnail carousel in the `live` view. This setting is only relevant when the `media_type` parameter is set to `events`. |
+| `media_type`            | `events` | Whether to load `events` or `recordings` media.                                                                                                                               |
+| `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` | `true`   | Whether to show the download control on each thumbnail.                                                                                                                       |
+| `show_favorite_control` | `true`   | Whether to show the favorite ('star') control on each thumbnail.                                                                                                              |
+| `show_timeline_control` | `true`   | 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 <= `175`.                                                                           |
+
+### `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. |
+| `events_media_type`    | `all`    | Whether to show only events with `clips`, events with `snapshots` or `all` events. When `all` is used, `clips` are favored for events that have both a clip and a snapshot.                                                                                                                                                                                                                                                     |
+| `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')
+
+## `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. The precise number will be calculated based on the [grid layout algorithm](grid-layout-algorithm.md). |
+| `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.                                                                                                                  |
+
+## `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 stream continually connected while the card is running, or only when microphone is used (default). In the latter case there'll be a connection reset when the microphone is first used -- using this option can avoid that reset. |
+| `disconnect_seconds`                 | `90`    | The number of seconds after microphone usage to disconnect the microphone from the stream. `0` implies never. Not relevant if `always_connected` is `true`.                                                                                                             |
+| `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
+  auto_unmute:
+    - microphone
+  preload: false
+  lazy_load: true
+  lazy_unload: []
+  draggable: true
+  zoomable: true
+  transition_effect: slide
+  controls:
+    builtin: true
+    next_previous:
+      style: chevrons
+      size: 48
+    ptz:
+      mode: auto
+      position: bottom-right
+      orientation: horizontal
+      hide_pan_tilt: false
+      hide_zoom: false
+      hide_home: false
+      style:
+        # Optionally override the default style.
+        right: 5%
+    thumbnails:
+      media_type: events
+      events_media_type: all
+      size: 100
+      show_details: false
+      show_download_control: true
+      show_favorite_control: true
+      show_timeline_control: true
+      mode: none
+    timeline:
+      style: ribbon
+      mode: none
+      pan_mode: pan
+      clustering_threshold: 3
+      events_media_type: all
+      show_recordings: true
+      window_seconds: 3600
+  microphone:
+    always_connected: false
+    disconnect_seconds: 90
+    mute_after_microphone_mute_seconds: 60
+  display:
+    mode: single
+    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
+```

docs/configuration/media-gallery.md

@@ -0,0 +1,78 @@
+# `media_gallery`
+
+The `media_gallery` is used for providing an overview of all `clips`, `snapshots` and `recordings` in a thumbnail gallery.
+
+```yaml
+media_gallery:
+  # [...]
+```
+
+| Option     | Default | Description                                                                                                               |
+| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `actions`  |         | [Actions](actions/README.md) to use for all views that use the `media_gallery` (e.g. `clips`, `snapshots`, `recordings`). |
+| `controls` |         | Configuration for the Media viewer controls. See below.                                                                   |
+
+## `controls`
+
+### `filter`
+
+Configure the media gallery filter.
+
+```yaml
+media_gallery:
+  controls:
+    filter:
+      # [...]
+```
+
+| Option | Default | Description                                                                                           |
+| ------ | ------- | ----------------------------------------------------------------------------------------------------- |
+| `mode` | `right` | Whether to show the gallery media filter to the `left`, to the `right` or `none` for no media filter. |
+
+### `thumbnails`
+
+Configure the media gallery thumbnails.
+
+```yaml
+media_gallery:
+  controls:
+    thumbnails:
+      # [...]
+```
+
+| Option                  | Default | Description                                                                                              |
+| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `show_details`          | `false` | Whether to show media details (e.g. duration, start time, object detected, etc) alongside the thumbnail. |
+| `show_download_control` | `true`  | Whether to show the download control on each thumbnail.                                                  |
+| `show_favorite_control` | `true`  | Whether to show the favorite ('star') control on each thumbnail.                                         |
+| `show_timeline_control` | `true`  | Whether to show the timeline ('target') control on each thumbnail.                                       |
+| `size`                  | `100`   | The size of the thumbnails in the gallery. Must be >= `75` and <= `175`.                           |
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+media_gallery:
+  controls:
+    filter:
+      mode: 'right'
+    thumbnails:
+      size: 100
+      show_details: false
+      show_download_control: true
+      show_favorite_control: true
+      show_timeline_control: true
+  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
+```

docs/configuration/media-viewer.md

@@ -0,0 +1,207 @@
+# `media_viewer`
+
+The `media_player` section configures viewing all `clip`, `snapshot` or `recording` media, in either a media carousel or grid.
+
+```yaml
+media_viewer:
+  # [...]
+```
+
+| Option                      | Default                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actions`                   |                        | [Actions](actions/README.md) to use for all views that use the `media_viewer` (e.g. `clip`, `snapshot`).                                                                                                                                                                                                                                                                                                                                                               |
+| `auto_mute`                 | `[unselected, hidden]` | A list of conditions in which media items are muted. `unselected` will automatically mute when a media item is unselected in the carousel and `hidden` will automatically mute when the browser/tab becomes hidden. Use an empty list (`[]`) to never automatically mute.                                                                                                                                                                                              |
+| `auto_pause`                | `[unselected, hidden]` | A list of conditions in which media items are automatically paused. `unselected` will automatically pause when a media item is unselected in the carousel and `hidden` will automatically pause when the browser/tab becomes hidden. Use an empty list (`[]`) to never automatically pause.                                                                                                                                                                            |
+| `auto_play`                 | `[selected, visible]`  | A list of conditions in which media items are automatically played.`selected` will automatically play when a media item is selected in the carousel and `visible` will automatically play when the browser/tab becomes visible. Use an empty list (`[]`) to never automatically play.                                                                                                                                                                                  |
+| `auto_unmute`               | `[]`                   | A list of conditions in which media items are unmuted. `selected` will automatically unmute when a media item is unselected in the carousel and `visible` will automatically unmute when the browser/tab becomes visible. Use an empty list (`[]`) to never automatically unmute. Note that 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 Media viewer controls. See below.                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `draggable`                 | `true`                 | Whether or not the Media viewer carousel can be dragged left or right, via touch/swipe and mouse dragging.                                                                                                                                                                                                                                                                                                                                                             |
+| `lazy_load`                 | `true`                 | Whether or not to lazily load media in the Media 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.                                                                                                                                                                                                      |
+| `snapshot_click_plays_clip` | `true`                 | Whether clicking on a snapshot in the media viewer should play a related clip.                                                                                                                                                                                                                                                                                                                                                                                         |
+| `transition_effect`         | `slide`                | Effect to apply as a transition between event media. Accepted values: `slide` or `none`.                                                                                                                                                                                                                                                                                                                                                                               |
+| `zoomable`                  | `true`                 | Whether or not the Media Viewer can be zoomed and panned, via touch/pinch and mouse scroll wheel with `ctrl` held.                                                                                                                                                                                                                                                                                                                                                     |
+
+## `controls`
+
+Configure the controls for the media player views.
+
+```yaml
+media_viewer:
+  controls:
+    # [...]
+```
+
+| Option          | Default | Description                                                                             |
+| --------------- | ------- | --------------------------------------------------------------------------------------- |
+| `builtin`       | `true`  | Whether to show the built in (browser) video controls on media viewer videos.           |
+| `next_previous` |         | Configures how the "Next & Previous" controls are shown on the media viewer. See below. |
+| `thumbnails`    |         | Configures how thumbnails are shown on the media viewer. See below.                     |
+| `timeline`      |         | Configures how the mini-timeline is shown on the media viewer. See below.               |
+
+### `next_previous`
+
+Configures how the "Next & Previous" controls are shown on the media viewer.
+
+```yaml
+media_viewer:
+  controls:
+    next_previous:
+      # [...]
+```
+
+| Option  | Default      | Description                                                                                                                                      |
+| ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `size`  | `48`         | The size of the next/previous controls in pixels. Must be >= `20`.                                                                            |
+| `style` | `thumbnails` | When viewing media, what kind of controls to show to move to the previous/next media item. Acceptable values: `thumbnails`, `chevrons`, `none` . |
+
+### `ptz`
+
+Configures the PTZ (Pan Tilt Zoom) controls. As the media viewer is never
+viewing live view, the PTZ controls in this context always refer to digital (vs
+real) panning and zooming.
+
+```yaml
+media_viewer:
+  controls:
+    ptz:
+      # [...]
+```
+
+| Option          | Default        | Description                                                                                                                                                                                                                     |
+| --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hide_home`     | `false`        | When `true` the Home button of the control is hidden                                                                                                                                                                            |
+| `hide_pan_tilt` | `false`        | When `true` the Pan & Tilt buttons of the control is hidden                                                                                                                                                                     |
+| `hide_zoom`     | `false`        | When `true` the Zoom button of the control is hidden                                                                                                                                                                            |
+| `mode`          | `off`          | If `on` or `off` will always or never show PTZ controls respectively.                                                                                                                                                           |
+| `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%` |
+
+### `thumbnails`
+
+Configures how thumbnails are shown on the media viewer.
+
+```yaml
+media_viewer:
+  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` | `true`  | Whether to show the download control on each thumbnail.                                                                                                         |
+| `show_favorite_control` | `true`  | Whether to show the favorite ('star') control on each thumbnail.                                                                                                |
+| `show_timeline_control` | `true`  | Whether to show the timeline ('target') control on each thumbnail.                                                                                              |
+| `size`                  | `100`   | The size of the thumbnails in the thumbnail carousel pixels. Must be >= `75` and <= `175`.                                                                |
+
+### `timeline`
+
+Configures how the mini-timeline is shown on the media viewer.
+
+```yaml
+media_viewer:
+  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. |
+| `events_media_type`    | `all`    | Whether to show only events with `clips`, events with `snapshots` or `all` events. When `all` is used, `clips` are favored for events that have both a clip and a snapshot.                                                                                                                                                                                                                                                     |
+| `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')
+
+## `display`
+
+Controls whether to show a single media item or grid in the media viewer.
+
+```yaml
+media_viewer:
+  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. The precise number will be calculated based on the [grid layout algorithm](grid-layout-algorithm.md). |
+| `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` media item at a time, or a media item for all cameras in a `grid` configuration.                                                                                                      |
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+media_viewer:
+  auto_play:
+    - selected
+    - visible
+  auto_pause:
+    - unselected
+    - hidden
+  auto_mute:
+    - unselected
+    - hidden
+  auto_unmute: []
+  lazy_load: true
+  draggable: true
+  zoomable: true
+  snapshot_click_plays_clip: true
+  transition_effect: slide
+  controls:
+    builtin: true
+    next_previous:
+      size: 48
+      style: thumbnails
+    ptz:
+      mode: off
+      position: bottom-right
+      orientation: horizontal
+      hide_pan_tilt: false
+      hide_zoom: false
+      hide_home: false
+      style:
+        # Optionally override the default style.
+        right: 5%
+    thumbnails:
+      size: 100
+      mode: none
+      show_details: false
+      show_download_control: true
+      show_favorite_control: true
+      show_timeline_control: true
+    timeline:
+      style: ribbon
+      mode: none
+      pan_mode: pan
+      clustering_threshold: 3
+      events_media_type: all
+      show_recordings: true
+      window_seconds: 3600
+  display:
+    mode: single
+    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
+```

docs/configuration/menu.md

@@ -0,0 +1,178 @@
+# `menu`
+
+Configures how the card menu behaves.
+
+```yaml
+menu:
+  # [...]
+```
+
+| Option        | Default  | Description                                                                                                                                                                                                                                                  |
+| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `alignment`   | `left`   | Whether to align the menu buttons to the `left`, `right`, `top` or `bottom` of the menu. Some selections may have no effect depending on the value of `position` (e.g. it doesn't make sense to `left` align icons on a menu with `position` to the `left`). |
+| `button_size` | `40`     | The size of the menu buttons in pixels. Must be >= `20`.                                                                                                                                                                                                  |
+| `buttons`     |          | Whether to show or hide built-in buttons. See below.                                                                                                                                                                                                         |
+| `position`    | `top`    | Whether to show the menu on the `left`, `right`, `top` or `bottom` side of the card. Note that for the `outside` style only the `top` and `bottom` positions have an effect.                                                                                 |
+| `style`       | `hidden` | The menu style to show by default, one of `none`, `hidden`, `hover`, `hover-card`, `overlay`, or `outside`. See below.                                                                                                                                       |
+
+## `buttons`
+
+All configuration is under:
+
+```yaml
+menu:
+  buttons:
+    [button]:
+      # [...]
+```
+
+### Available Buttons
+
+| Button name    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `camera_ui`    | The `camera_ui` menu button: brings the user to a context-appropriate page on the UI of their camera engine (e.g. the Frigate camera homepage). Will only appear if the camera engine supports a camera UI (e.g. if `frigate.url` option is set for `frigate` engine users).                                                                                                                                                                                                                          |
+| `cameras`      | The camera selection submenu. Will only appear if multiple cameras are configured.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `clips`        | The `clips` view menu button: brings the user to the `clips` view on tap and the most-recent `clip` view on hold.                                                                                                                                                                                                                                                                                                                                                                                     |
+| `display_mode` | The `display_mode` button allows changing between single and grid views.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `download`     | The `download` menu button: allow direct download of the media being displayed.                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `expand`       | The `expand` menu button: expand the card into a popup/dialog.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `frigate`      | The `Frigate` menu button: brings the user to the default configured view (`view.default`), or collapses/expands the menu if the `menu.style` is `hidden` .                                                                                                                                                                                                                                                                                                                                           |
+| `fullscreen`   | The `fullscreen` menu button: expand the card to consume the fullscreen.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `image`        | The `image` view menu button: brings the user to the static `image` view.                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `live`         | The `live` view menu button: brings the user to the `live` view.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `media_player` | The `media_player` menu button: sends the visible media to a remote media player. Supports Frigate clips, snapshots and live camera (only for cameras that specify a `camera_entity` and only using the default HA stream (equivalent to the `ha` live provider)). `jsmpeg` or `webrtc-card` are not supported, although live can still be played as long as `camera_entity` is specified. In the player list, a `tap` will send the media to the player, a `hold` will stop the media on the player. |
+| `microphone`   | The `microphone` button allows usage of 2-way audio in certain configurations. See [Using 2-way audio](../usage/2-way-audio.md).                                                                                                                                                                                                                                                                                                                                                                      |
+| `ptz_controls` | The `ptz_controls` button shows or hides the PTZ controls.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `ptz_home`     | The `ptz_home` button allows easily returning the camera to default home position.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `recordings`   | The `recordings` view menu button: brings the user to the `recordings` view on tap and the most-recent `recording` view on hold.                                                                                                                                                                                                                                                                                                                                                                      |
+| `screenshot`   | The `screenshot` menu button: take a screenshot of the loaded media (e.g. a still from a video).                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `snapshots`    | The `snapshots` view menu button: brings the user to the `clips` view on tap and the most-recent `snapshot` view on hold.                                                                                                                                                                                                                                                                                                                                                                             |
+| `timeline`     | The `timeline` menu button: show the event timeline.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+
+### Options for each button
+
+| Option      | Default                                                                                                                                                                                                                                                                                | Description                                                                                                                                                                                                                                                           |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `alignment` | `matching`                                                                                                                                                                                                                                                                             | Whether this button should have an alignment that is `matching` the menu alignment or `opposing` the menu. Can be used to create two separate groups of buttons on the menu. `priority` orders buttons within a given `alignment`.                                    |
+| `enabled`   | `true` for `frigate`, `cameras`, `substreams`, `live`, `clips`, `snapshots`, `timeline`, `download`, `camera_ui`, `fullscreen`, `media_player`, `display_mode` and `ptz_home`. `false` for `image`, `expand`, `microphone`, `mute`, `play`, `recordings`, `screenshot`, `ptz_controls` | Whether or not to show the button.                                                                                                                                                                                                                                    |
+| `icon`      |                                                                                                                                                                                                                                                                                        | An icon to overriding the default for that button, e.g. `mdi:camera-front`.                                                                                                                                                                                           |
+| `priority`  | `50`                                                                                                                                                                                                                                                                                   | The button priority. Higher priority buttons are ordered closer to the start of the menu alignment (i.e. a button with priority `70` will order further to the left than a button with priority `60`, when the menu alignment is `left`). Minimum `0`, maximum `100`. |
+
+## `style`
+
+This card supports several menu styles.
+
+| Key          | Description                                                                                                                                                | Screenshot                                                       |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `hidden`     | Hide the menu by default, expandable upon clicking the Frigate button.                                                                                     | ![](../images/menu-mode-hidden.png 'Menu hidden :size=400')      |
+| `hover-card` | Overlay the menu over the card contents when the mouse is over the **card**, otherwise it is not shown. The Frigate button shows the default view.         | ![](../images/menu-mode-overlay.png 'Menu hover-card :size=400') |
+| `hover`      | Overlay the menu over the card contents when the mouse is over the **menu**, otherwise it is not shown. The Frigate button shows the default view.         | ![](../images/menu-mode-overlay.png 'Menu hover :size=400')      |
+| `none`       | No menu is shown.                                                                                                                                          | ![](../images/menu-mode-none.png 'No menu :size=400')            |
+| `outside`    | Render the menu outside the card (i.e. above it if `position` is `top`, or below it if `position` is `bottom`). The Frigate button shows the default view. | ![](../images/menu-mode-above.png 'Menu outside :size=400')      |
+| `overlay`    | Overlay the menu over the card contents. The Frigate button shows the default view.                                                                        | ![](../images/menu-mode-overlay.png 'Menu hidden :size=400')     |
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+menu:
+  alignment: left
+  buttons:
+    frigate:
+      priority: 50
+      enabled: true
+      alignment: matching
+      # Default icon is an internal coded Frigate icon. Note
+      # absence of 'mdi' here (mdi has no Frigate icon).
+      icon: frigate
+    cameras:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:video-switch
+    substreams:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:video-input-component
+    live:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:cctv
+    clips:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:filmstrip
+    snapshots:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:camera
+    image:
+      priority: 50
+      enabled: false
+      alignment: matching
+      icon: mdi:image
+    timeline:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:chart-gantt
+    download:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:download
+    camera_ui:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:web
+    fullscreen:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:fullscreen
+    expand:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:arrow-expand-all
+    media_player:
+      priority: 50
+      enabled: false
+      alignment: matching
+      icon: mdi:cast
+    microphone:
+      priority: 50
+      enabled: false
+      alignment: matching
+      icon: mdi:microphone
+      type: momentary
+    mute:
+      priority: 50
+      enabled: false
+      alignment: matching
+      icon: mdi:volume-off
+    play:
+      priority: 50
+      enabled: false
+      alignment: matching
+      icon: mdi:play
+    ptz_controls:
+      priority: 50
+      enabled: false
+      alignment: matching
+      icon: mdi:pan
+    ptz_home:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:home
+  button_size: 40
+  position: top
+  style: hidden
+```

docs/configuration/overrides.md

@@ -0,0 +1,152 @@
+# `overrides`
+
+The card configuration may [conditionally](conditions.md) be overridden (e.g. to
+hide the menu in fullscreen mode).
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    # [...]
+```
+
+!> Whilst all configuration parameters are theoretically overridable, in some instances a configuration variable may only be consulted on startup or changing its value may negatively impact behavior -- override results may vary!
+
+The top-level `overrides` configuration block expects a list, with each list
+item containing `conditions` and at least one of `merge`, `delete` or `set` specified.
+
+| Option       | Default | Description                                                                                                  |
+| ------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
+| `conditions` |         | A list of [conditions](conditions.md) that must evaluate to `true` in order for the overrides to be applied. |
+| `delete`     |         | An array of configuration paths to delete. See below.                                                        |
+| `merge`      |         | A dictionary of configuration paths to merge. See below.                                                     |
+| `set`        |         | A dictionary of configuration paths to set. See below.                                                       |
+
+## Configuration Paths
+
+The `delete`, `merge` and `set` parameters take configuration paths. Paths are dot-separated references to particular configuration parameters. To refer to list elements use `[n]` notation.
+
+For example the path `cameras[1].dimensions.aspect_ratio` refers to the `aspect_ratio` parameter below:
+
+```yaml
+cameras:
+  - camera_entity: camera.other
+  - camera_entity: camera.relevant
+    dimensions:
+      aspect_ratio: '16:9'
+```
+
+## `delete`
+
+An array of configuration paths to delete.
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    delete:
+      - [path_1]
+      - [path_2]
+```
+
+### Examples
+
+Delete the 2nd camera:
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    delete:
+      - 'cameras[2]'
+```
+
+Delete the menu style parameter, thus falling back to the default:
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    delete:
+      - 'menu.style'
+```
+
+## `merge`
+
+Specifies an object to recursively merge into existing configuration.
+
+| Option               | Default | Description                                                                            |
+| -------------------- | ------- | -------------------------------------------------------------------------------------- |
+| [configuration path] |         | Arbitrary configuration object to merge. Must be an object (i.e. not a literal value). |
+
+### Examples
+
+Hide the menu when a given condition is met:
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    merge:
+      menu: { style: 'hidden' }
+```
+
+Enable thumbnails below the `live` feed:
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    merge:
+      'live.controls.thumbnails': { mode: 'below' }
+```
+
+Also enables thumbnails below the `live` feed, but without using the dot-separated notation:
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    merge:
+      live: { controls: { thumbnails: { mode: 'below' } } }
+```
+
+## `set`
+
+Specifies a value to set in the configuration. This differs from `merge` in that the existing value is entirely replaced.
+
+| Option               | Default | Description                                           |
+| -------------------- | ------- | ----------------------------------------------------- |
+| [configuration path] |         | Arbitrary configuration value / object / list to set. |
+
+### Examples
+
+Set the entire menu configuration to defaults with the exception of the `style` which is set to `overlay`.
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    set:
+      menu: { style: 'overlay' }
+```
+
+Set the menu style but without touching the other `menu` parameters:
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    set:
+      'menu.style': 'overlay'
+```
+
+That is equivalent to merging the following:
+
+```yaml
+overrides:
+  - conditions:
+      - [condition]
+    merge:
+      menu: { style: 'overlay' }
+```

docs/configuration/performance.md

@@ -0,0 +1,67 @@
+# `performance`
+
+Configure the card performance settings to enable the card to run (more) smoothly on lower end devices.
+
+```yaml
+performance:
+  # [...]
+```
+
+| Option     | Default | Description                                         |
+| ---------- | ------- | --------------------------------------------------- |
+| `features` |         | Configure feature settings that impact performance. |
+| `style`    |         | Configure style settings that impact performance.   |
+
+### `features`
+
+Controls card-wide functionality that may impact performance.
+
+```yaml
+performance:
+  features:
+    # [...]
+```
+
+| Option                             | Default    | Description                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `animated_progress_indicator`      | `true`     | Will show the animated progress indicator 'spinner' when `true` or a simple loading icon when `false`.                                                                                                                                                                                                                                                                                                              |
+| `media_chunk_size`                 | `50`       | How many media items to fetch and render at a time (e.g. thumbnails under a live view, or number of snapshots to load in the media viewer). This may only make partial sense in some contexts (e.g. the 'infinite gallery' is still infinite, it just loads thumbnails this many items at a time) or not at all (e.g. the timeline will show the number of events dictated by the time span the user navigates to). |
+| `max_simultaneous_engine_requests` | _Infinity_ | How many camera engine requests to allow occur in parallel. Setting lower values will slow the card down since more requests will run in sequence, but it will increase the chances of positive cache hit rates and reduce the chances of overwhelming the backend.                                                                                                                                                 |
+
+### `style`
+
+Style performance options request the card minimize certain expensive CSS
+stylings. This does not necessarily disable these stylings _entirely_ since that
+may break the basic expected visuals of the card (e.g. menu icons need curves),
+but rather avoids use of them in high item-count situations (e.g. avoiding
+shadows on timeline items, or curves in the media gallery items).
+
+```yaml
+performance:
+  style:
+    # [...]
+```
+
+| Option          | Default | Description                                        |
+| --------------- | ------- | -------------------------------------------------- |
+| `border_radius` | `true`  | If `false` minimizes the usage of rounded corners. |
+| `box_shadow`    | `true`  | If `false` minimizes the usage of shadows.         |
+
+### The `low-performance` profile
+
+For low end devices, the `low-performance` profile will adjust card defaults to attempt to improve performance. See the [profiles](profiles.md) configuration option for details on how to select profiles.
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+performance:
+  features:
+    animated_progress_indicator: true
+    media_chunk_size: 50
+    max_simultaneous_engine_requests: 100
+  style:
+    border_radius: true
+    box_shadow: true
+```

docs/configuration/profiles.md

@@ -0,0 +1,47 @@
+# `profiles`
+
+Apply pre-configured sets of defaults to ease card configuration.
+
+```yaml
+profiles:
+  - [profile_1]
+  - [profile_2]
+```
+
+?> Since the profiles change the _default_ value of options, setting a profile
+on a pre-existing card could have limited effect if there are options already set by
+the user.
+
+?> Profiles are applied top to bottom. If multiple profiles change a configuration default, then the last one "wins"
+
+| Profile name      | Purpose                    |
+| ----------------- | -------------------------- |
+| `low-performance` | Increase card performance. |
+| `scrubbing`       | Allow media "scrubbing".   |
+
+## `low-performance`
+
+For low end devices, the `low-performance` profile will adjust card defaults to attempt to increase performance.
+
+Principles used in the selection of options set by `low-profile` profile mode:
+
+- Get 'out of the box' performance similar to the basic "Home Assistant Picture Glance" card.
+- Do not break the visual aesthetic of the card.
+
+See the [source code](https://github.com/dermotduffy/frigate-hass-card/blob/dev/src/config/profiles/low-performance.ts) for an exhaustive list of defaults set by this profile.
+
+## `scrubbing`
+
+Configures the `live` view and media viewer to allow media "scrubbing" as the timeline is dragged back and forth.
+
+See the [source code](https://github.com/dermotduffy/frigate-hass-card/blob/dev/src/config/profiles/scrubbing.ts) for an exhaustive list of options set by this profile.
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+profiles:
+  - low-performance
+  - scrubbing
+```

docs/configuration/status-bar.md

@@ -0,0 +1,82 @@
+# `status_bar`
+
+Configures the card status bar.
+
+```yaml
+status_bar:
+  # [...]
+```
+
+| Option          | Default  | Description                                                                                                                |
+| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `position`      | `bottom` | Whether to place the status bar at the `top` or `bottom` of the card.                                                      |
+| `popup_seconds` | `3`      | The number of seconds to display the status bar when using the `popup` style.                                              |
+| `height`        | `46`     | The height of the status bar in pixels.                                                                                    |
+| `items`         |          | Whether to show or hide built-in status bar items. See below.                                                              |
+| `style`         | `popup`  | The status bar style to show by default, one of `none`, `hover`, `hover-card`, `overlay`, `outside` or `popup`. See below. |
+
+## `items`
+
+All configuration is under:
+
+```yaml
+status_bar:
+  items:
+    [item]:
+      # [...]
+```
+
+### Available Items
+
+| Button name  | Description                                            |
+| ------------ | ------------------------------------------------------ |
+| `engine`     | The icon of the camera engine for the relevant camera. |
+| `resolution` | The detected media resolution (if any).                |
+| `technology` | The detected media technology (if any).                |
+| `title`      | The media title.                                       |
+
+### Options for each item
+
+| Option     | Default | Description                                                                                                                                                                                                              |
+| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `enabled`  | `true`  | Whether or not to show the item.                                                                                                                                                                                         |
+| `priority` | `50`    | The item priority. Higher priority items are ordered closer to the start of the status bar (i.e. an item with priority `70` will order further to the left than an item with priority `60`). Minimum `0`, maximum `100`. |
+
+## `style`
+
+This card supports several menu styles.
+
+| Key          | Description                                                                                                           |
+| ------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `hover-card` | Overlay the status bar over the card contents when the mouse is over the **card**, otherwise it is not shown.         |
+| `hover`      | Overlay the status bar over the card contents when the mouse is over the **status bar**, otherwise it is not shown.   |
+| `none`       | No status bar is shown.                                                                                               |
+| `outside`    | Render the status bar outside the card (i.e. above it if `position` is `top`, or below it if `position` is `bottom`). |
+| `overlay`    | Overlay the status bar over the card contents.                                                                        |
+
+## Fully expanded reference
+
+?> To add custom status bar contents, see [status bar custom elements](elements/custom/README.md?id=status-bar-icon).
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+status_bar:
+  position: bottom
+  popup_seconds: 3
+  height: 46
+  style: popup
+  items:
+    engine:
+      enabled: true
+      priority: 50
+    resolution:
+      enabled: true
+      priority: 50
+    technology:
+      enabled: true
+      priority: 50
+    title:
+      enabled: true
+      priority: 50
+```

docs/configuration/timeline-pan-mode.md

@@ -0,0 +1,10 @@
+# Timeline Pan Mode
+
+The behavior of the timeline during seeking/dragging can be controlled by means of the icon on the bottom-right of the timeline, or by using the `pan_mode` configuration variable for the relevant timeline controls (e.g. `live.controls.timeline.pan_mode`).
+
+| Configuration name | UI Icon                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Behavior                                                                                                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `pan`              | <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><title>pan-horizontal</title><path d="M7,8L2.5,12L7,16V8M17,8V16L21.5,12L17,8M12,10A2,2 0 0,0 10,12A2,2 0 0,0 12,14A2,2 0 0,0 14,12A2,2 0 0,0 12,10Z" /></svg>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Dragging the timeline will pan only without selected or seeking any media.                                                                                                                                   |
+| `seek-in-camera`   | <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><title>camera-lock</title><path d="M4 4H7L9 2H15L17 4H20C21.11 4 22 4.89 22 6V12C21.16 11.37 20.13 11 19 11C18.21 11 17.46 11.18 16.79 11.5C16.18 9.22 14.27 7 12 7C9.24 7 7 9.24 7 12C7 14.76 9.24 17 12 17C12.42 17 12.84 16.95 13.23 16.85C13.08 17.2 13 17.59 13 18V20H4C2.9 20 2 19.11 2 18V6C2 4.89 2.9 4 4 4M12 9C13.66 9 15 10.34 15 12C15 13.66 13.66 15 12 15C10.34 15 9 13.66 9 12C9 10.34 10.34 9 12 9M23 18.3V21.8C23 22.4 22.4 23 21.7 23H16.2C15.6 23 15 22.4 15 21.7V18.2C15 17.6 15.6 17 16.2 17V15.5C16.2 14.1 17.6 13 19 13C20.4 13 21.8 14.1 21.8 15.5V17C22.4 17 23 17.6 23 18.3M20.5 15.5C20.5 14.7 19.8 14.2 19 14.2C18.2 14.2 17.5 14.7 17.5 15.5V17H20.5V15.5Z" /></svg> | Dragging the timeline will seek / select across all available media from the selected camera only, selecting the media item with the longest duration.                                                       |
+| `seek-in-media`    | <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><title>play-box-lock</title><path d="M23 17.3V20.8C23 21.4 22.4 22 21.7 22H16.2C15.6 22 15 21.4 15 20.7V17.2C15 16.6 15.6 16 16.2 16V14.5C16.2 13.1 17.6 12 19 12C20.4 12 21.8 13.1 21.8 14.5V16C22.4 16 23 16.6 23 17.3M13 19V21H4C2.89 21 2 20.1 2 19V5C2 3.89 2.89 3 4 3H18C19.1 3 20 3.89 20 5V10.1L19 10L18 10.1C15.79 10.55 14.12 12.45 14 14.76C13.39 15.31 13 16.11 13 17V19M20.5 14.5C20.5 13.7 19.8 13.2 19 13.2C18.2 13.2 17.5 13.7 17.5 14.5V16H20.5V14.5M9 8V16L14 12L9 8Z" /></svg>                                                                                                                                                                                                 | Dragging the timeline will seek within the selected media item only.                                                                                                                                         |
+| `seek`             | <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><title>filmstrip-box-multiple</title><path d="M4,6H2V20A2,2 0 0,0 4,22H18V20H4V6M20,2H8A2,2 0 0,0 6,4V16A2,2 0 0,0 8,18H20A2,2 0 0,0 22,16V4A2,2 0 0,0 20,2M10,15H8V13H10V15M10,11H8V9H10V11M10,7H8V5H10V7M20,15H18V13H20V15M20,11H18V9H20V11M20,7H18V5H20V7Z" /></svg>                                                                                                                                                                                                                                                                                                                                                                                                                           | Dragging the timeline will seek / select across all available media from all cameras, selecting the media item with the longest duration whilst favoring (but not limited to) the currently selected camera. |

docs/configuration/timeline.md

@@ -0,0 +1,79 @@
+# `timeline`
+
+Configures a `timeline` view used to show the timing sequence of events and
+recordings across multiple cameras.
+
+```yaml
+timeline:
+  # [...]
+```
+
+You can interact with the timeline in a number of ways:
+
+- Clicking on an event will take you to the media viewer for that event.
+- Clicking on the "background", or a camera title, will take you to the recordings for that camera (seeking to the clicked time).
+- Clicking on the time axis will take you to recordings for all cameras (seeking to the clicked time).
+
+| 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. |
+| `controls`             |         | Configuration for the timeline controls. See below.                                                                                                                                                                                                                                                                                                                                                                             |
+| `events_media_type`    | `all`   | Whether to show only events with `clips`, events with `snapshots` or `all` events. When `all` is used, `clips` are favored for events that have both a clip and a snapshot.                                                                                                                                                                                                                                                     |
+| `show_recordings`      | `true`  | Whether to show recordings on the timeline (specifically: which hours have any recorded content).                                                                                                                                                                                                                                                                                                                               |
+| `style`                | `stack` | 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.                                                                                                                                                                                                                                                                                                                    |
+
+## `controls`
+
+Configure the controls for the `timeline` view.
+
+```yaml
+timeline:
+  controls:
+    # [...]
+```
+
+| Option       | Default | Description                                                            |
+| ------------ | ------- | ---------------------------------------------------------------------- |
+| `thumbnails` |         | Configures how thumbnails are shown on the `timeline` view. See below. |
+
+### `thumbnails`
+
+Configures how thumbnails are shown on the timeline.
+
+```yaml
+timeline:
+  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` | `true`  | Whether to show the download control on each thumbnail.                                                                                                         |
+| `show_favorite_control` | `true`  | Whether to show the favorite ('star') control on each thumbnail.                                                                                                |
+| `show_timeline_control` | `true`  | 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 <= `175`.                                                             |
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+timeline:
+  style: stack
+  clustering_threshold: 3
+  events_media_type: all
+  show_recordings: true
+  window_seconds: 3600
+  controls:
+    thumbnails:
+      mode: left
+      size: 100
+      show_details: true
+      show_download_control: true
+      show_favorite_control: true
+      show_timeline_control: true
+```

docs/configuration/view.md

@@ -0,0 +1,176 @@
+# `view`
+
+The `view` configuration options control how the default view of the card behaves.
+
+```yaml
+view:
+  # [...]
+```
+
+| Option                    | Default                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actions`                 |                                                           | [Actions](actions/README.md) to use for all views, individual actions may be overriden by view-specific actions.                                                                                                                                                                                                                                                                             |
+| `camera_select`           | `current`                                                 | The [view](view.md?id=supported-views) to show when a new camera is selected (e.g. in the camera menu). If `current` the view is unchanged when a new camera is selected.                                                                                                                                                                                                                    |
+| `dark_mode`               | `off`                                                     | Whether or not to turn dark mode `on`, `off` or `auto` to automatically turn on if the card `interaction_seconds` has expired (i.e. card has been left unattended for that period of time) or if dark mode is enabled in the HA profile theme setting. Dark mode dims the brightness by `25%`.                                                                                               |
+| `default`                 | `live`                                                    | The view to show in the card by default. The default camera is the first one listed. See [Supported Views](view.md?id=supported-views) below.                                                                                                                                                                                                                                                |
+| `default_reset`           |                                                           | The circumstances and behavior that cause the card to reset to the default view. See below.                                                                                                                                                                                                                                                                                                  |
+| `interaction_seconds`     | `300`                                                     | After a mouse/touch interaction with the card, it will be considered "interacted with" until this number of seconds elapses without further interaction. May be used as part of an [interaction condition](conditions.md?id=interaction) or with `reset_after_interaction` to reset the view after the interaction is complete. `0` means no interactions are reported / acted upon.         |
+| `keyboard_shortcuts`      | See [usage](../usage/keyboard-shortcuts.md) for defaults. | Configure keyboard shortcuts. See below.                                                                                                                                                                                                                                                                                                                                                     |
+| `render_entities`         |                                                           | **YAML only**: A list of entity ids that should cause the card to re-render 'in-place'. The view/camera is not changed. This should **very** rarely be needed, but could be useful if the card is both setting and changing HA state of the same object as could be the case for some complex `card_mod` scenarios ([example](https://github.com/dermotduffy/frigate-hass-card/issues/343)). |
+| `reset_after_interaction` | `true`                                                    | If `true` the card will reset to the default configured view (i.e. 'screensaver' functionality) after `interaction_seconds` has elapsed after user interaction.                                                                                                                                                                                                                              |
+| `triggers`                |                                                           | How to react when a camera is [triggered](cameras/README.md?id=triggers).                                                                                                                                                                                                                                                                                                                    |
+| `default_cycle_camera`    | `false`                                                   | When set to `true` the selected camera is cycled on each default view change.                                                                                                                                                                                                                                                                                                                |
+
+## `default_reset`
+
+Configure the circumstances and behavior that cause the card to reset to the default view. All configuration is under:
+
+```yaml
+view:
+  default_reset: [...]
+```
+
+| Option              | Default    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `after_interaction` | `true`     | If `true` the card will reset to the default configured view (i.e. 'screensaver' functionality) after `interaction_seconds` has elapsed after user interaction.                                                                                                                                                                                                                                                                                                                                                       |
+| `entities`          |            | A list of entities that should cause the view to reset to the default (if the entity only pertains to a particular camera use [`triggers`](cameras/README.md?id=triggers) for the selected camera instead).                                                                                                                                                                                                                                                                                                           |
+| `interaction_mode`  | `inactive` | Whether the default reset should happen when the card is being interacted with. If `all`, the reset will always happen regardless. If `inactive` the reset will only be taken if the card has _not_ had human interaction recently (as defined by `view.interaction_seconds`). If `active` the reset will only be happen if the card _has_ had human interaction recently. This controls resets triggered by `entities` and `every_seconds`, but not `after_interaction` which by definition requires no interaction. |
+| `every_seconds`     | `0`        | A number of seconds after which to automatically reset to the default view. `0` disables this functionality.                                                                                                                                                                                                                                                                                                                                                                                                          |
+
+## `keyboard_shortcuts`
+
+All configuration is under:
+
+```yaml
+view:
+  keyboard_shortcuts: [...]
+```
+
+Configure the key-bindings for the builtin keyboard shortcuts. See [usage](../usage/keyboard-shortcuts.md) information for defaults on keyboard shortcuts.
+
+| Option                                                                                   | Default                                                   | Description                                                                             |
+| ---------------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `enabled`                                                                                | `true`                                                    | If `true`, keyboard shortcuts are enabled. If `false`, they are disabled.               |
+| `ptz_left`, `ptz_right`, `ptz_up`, `ptz_down`, `ptz_zoom_in`, `ptz_zoom_out`, `ptz_home` | See [usage](../usage/keyboard-shortcuts.md) for defaults. | An object that configures the key binding for a given pre-configured action. See below. |
+
+### Keyboard Shortcut Configuration
+
+| Option | Default | Description                                                                                                                      |
+| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| key    |         | Any [keyboard key value](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values), e.g. `ArrowLeft` |
+| ctrl   | `false` | If `true` requires the `ctrl` key to be held.                                                                                    |
+| shift  | `false` | If `true` requires the `shift` key to be held.                                                                                   |
+| alt    | `false` | If `true` requires the `alt` key to be held.                                                                                     |
+| meta   | `false` | If `true` requires the `meta` key to be held.                                                                                    |
+
+## `triggers`
+
+The `triggers` block controls how the card reacts when a camera is triggered (note that _what_ triggers the camera is controlled by the [`triggers`](cameras/README.md?id=triggers) block within the config for a given camera). This can be used for a variety of purposes, such as allowing the card to automatically change to `live` for a camera that triggers.
+
+All configuration is under:
+
+```yaml
+view:
+  triggers:
+    # [...]
+```
+
+When a camera untriggers (e.g. an entity state returning to something other than
+`on` or `open`), an action can also be taken with an optional number of seconds
+to wait prior to the acting (see `untrigger_seconds`). By default, triggering is
+only allowed when there is no ongoing human interaction with the card. This
+behavior can be controlled by the `interaction_mode` parameter.
+
+Triggers based on Home Assistant entities require state _changes_ -- when the
+card is first started, it takes an active change in state to trigger (i.e. an
+already occupied room will not trigger, but a newly occupied room will).
+
+| Option                   | Default | Description                                                                                                                        |
+| ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `actions`                |         | The actions to take when a camera is triggered. See below.                                                                         |
+| `filter_selected_camera` | `false` | If set to `true` will only trigger on the currently selected camera.                                                               |
+| `show_trigger_status`    | `false` | Whether or not the `live` view should show a visual indication that it is triggered (a pulsing border around the camera edge).     |
+| `untrigger_seconds`      | `0`     | The number of seconds to wait after a camera untriggers before considering the card untriggered and taking the `untrigger` action. |
+
+### Trigger action configuration
+
+| Option             | Default    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `interaction_mode` | `inactive` | Whether actions should be taken when the card is being interacted with. If `all`, actions will always left be taken regardless. If `inactive` actions will only be taken if the card has _not_ had human interaction recently (as defined by `view.interaction_seconds`). If `active` actions will only be taken if the card _has_ had human interaction recently. This does not stop triggering itself (i.e. border will still pulse if `show_trigger_status` is true) but rather just prevents the actions being performed. |
+| `trigger`          | `update`   | If set to `update` the current view is updated in place. If set to `default` the default view of the card will be reloaded. If set to `live` the triggered camera will be selected in `live` view. If set to `media` the appropriate media view (e.g. `clip` or `snapshot`) will be chosen to match a newly available media item (please note that only some [camera engines](cameras/engine.md) support new media detection, e.g. `frigate`). If set to `none` no action is taken.                                           |
+| `untrigger`        | `none`     | If set to `default` the the default view of the card will be reloaded. If set to `none` no action will be taken.                                                                                                                                                                                                                                                                                                                                                                                                              |
+
+## Supported views
+
+This card supports several different views.
+
+| Key          | Description                                                                                                                                        |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clip`       | Shows a viewer for the most recent clip for this camera. Can also be accessed by holding down the `clips` menu icon.                               |
+| `clips`      | Shows a gallery of clips for this camera.                                                                                                          |
+| `image`      | Shows a static image specified by the `image` parameter, can be used as a discrete default view or a screensaver (via `view.interaction_seconds`). |
+| `live`       | Shows the live camera view with the configured [live provider]().                                                                                  |
+| `recording`  | Shows a viewer for the most recent recording for this camera. Can also be accessed by holding down the `recordings` menu icon.                     |
+| `recordings` | Shows a gallery of recent (last day) recordings for this camera and its dependents.                                                                |
+| `snapshot`   | Shows a viewer for the most recent snapshot for this camera. Can also be accessed by holding down the `snapshots` menu icon.                       |
+| `snapshots`  | Shows a gallery of snapshots for this camera.                                                                                                      |
+| `timeline`   | Shows an event timeline.                                                                                                                           |
+
+The default view is `live`, but can be configured by the `view.default` parameter.
+
+## Fully expanded reference
+
+[](common/expanded-warning.md ':include')
+
+```yaml
+view:
+  default: live
+  camera_select: current
+  interaction_seconds: 300
+  default_cycle_camera: false
+  default_reset:
+    after_interaction: false
+    entities:
+      - binary_sensor.my_motion_sensor
+    every_seconds: 0
+    interaction_mode: inactive
+  render_entities:
+    - switch.render_card
+  dark_mode: 'off'
+  triggers:
+    show_trigger_status: false
+    filter_selected_camera: true
+    untrigger_seconds: 0
+    actions:
+      interaction_mode: inactive
+      trigger: update
+      untrigger: none
+  keyboard_shortcuts:
+    enabled: true
+    ptz_left:
+      key: 'ArrowLeft'
+    ptz_right:
+      key: 'ArrowRight'
+    ptz_up:
+      key: 'ArrowUp'
+    ptz_down:
+      key: 'ArrowDown'
+    ptz_zoom_in:
+      key: '+'
+    ptz_zoom_out:
+      key: '-'
+    ptz_home:
+      key: 'h'
+  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
+```

docs/developing.md

@@ -0,0 +1,74 @@
+# Developing
+
+?> Want to contribute? Development help [**welcome**](https://github.com/dermotduffy/frigate-hass-card/issues/1248)!
+
+## Building
+
+This project uses [Volta](https://github.com/volta-cli/volta) to ensure a
+consistent version of Node and Yarn are used during development. If you install
+Volta in your environment, you should not need to worry about which version of
+both to choose. **Note:** the dev container already comes with Volta installed.
+
+However, if you are not using Volta, you can check the `volta` key in the
+`package.json` to see which version of Node and Yarn should be used.
+
+```sh
+$ git clone https://github.com/dermotduffy/frigate-hass-card
+$ cd frigate-hass-card
+$ yarn install
+$ yarn run build
+```
+
+Resultant build entry file will be in `dist/frigate-hass-card.js`. This could be
+installed via the [manual installation
+instructions](advanced-installation.md?id=manual-installation).
+
+## Releasing
+
+1. Merge a PR that contains only a `package.json` and `const.ts` version number bump (see [this example](https://github.com/dermotduffy/frigate-hass-card/commit/a854187d4a354f8841ad284d75b0afbed7b634c4)).
+1. Go to the [releases page](https://github.com/dermotduffy/frigate-hass-card/releases).
+1. A release draft will automatically have been created, click 'Edit'.
+1. Use the same version number for the release title and tag.
+1. Choose 'This is a pre-release' for a beta version.
+1. Hit 'Publish release'.
+
+## Translations
+
+[![translation badge](https://badge.inlang.com/?url=github.com/dermotduffy/frigate-hass-card)](https://fink.inlang.com/github.com/dermotduffy/frigate-hass-card?ref=badge)
+
+To add translations, you can manually edit the JSON translation files in
+`src/localize/languages` or use the [inlang](https://inlang.com/) online editor.
+
+## Using a dev container
+
+[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/dermotduffy/frigate-hass-card)
+
+You can use the [VS Code Dev Containers](https://code.visualstudio.com/docs/remote/containers) extension to
+speed up the development environment creation. Simply:
+
+1. Clone the repository to your machine
+2. Open VS Code on it
+3. Reopen the folder in the Dev Container
+4. Once done, press `F5` to start debugging
+
+Everything should just work without any additional configuration. Under the
+hood, the dev container setup takes care of bringing up:
+
+- Home Assistant (port `8123` or the next available one)
+- Frigate (ports `5000` or the next available one)
+- MQTT (port `1883` or the next available one)
+
+As docker-compose containers.
+
+- The Frigate Home Assistant Integration is registered as a `git submodule` at `.devcontainer/frigate-hass-integration`, and VS Code will initialize/clone it for you before opening the dev container.
+
+Some environment variables are supported in a `.env` file:
+
+- `FRIGATE_VERSION`: The version of Frigate to use. Defaults to the latest stable version.
+- `HA_VERSION`: The version of Home Assistant to use. Defaults to the latest stable version.
+
+?> When not specifying any version, it's recommended that you `docker-compose pull` the stack from time to time to ensure you have the latest versions of the images.
+
+The Home Assistant container will get preconfigured during first initialization,
+therefore, if you changed the Home Assistant configuration, you will need to
+remove the HA container and start another.

docs/images/README.md

@@ -0,0 +1,4 @@
+## favicon.ico
+
+- https://pictogrammers.com/library/mdi/icon/camera-iris/
+- $ convert camera-iris.png -define icon:auto-resize="256,128,96,64,48,32,16" favicon.ico