docs: Various small documentation improvements (#2386)
This commit is contained in:
Dermot Duffy
@@ -17,7 +17,7 @@ action functionality. In general, the Advanced Camera Card functionality is a su
|
||||
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
|
||||
elements](https://www.home-assistant.io/dashboards/picture-elements/). Extended
|
||||
Advanced Camera Card behavior covers all other interactions on the Advanced Camera Card (e.g.
|
||||
menu icon elements, submenus and actions on the card or views).
|
||||
|
||||
|
||||
@@ -211,13 +211,13 @@ cameras:
|
||||
# [...]
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
| ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `fit` | `contain` | If `contain`, the media is contained within the camera container/card and letterboxed if necessary. If `cover`, the media is expanded proportionally (i.e. maintaining the media aspect ratio) until the camera/card dimensions are fully covered. If `fill`, the media is stretched to fill the camera/card dimensions (i.e. ignoring the media aspect ratio). See [CSS object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) for technical details and a visualization. Note that if `aspect_ratio` is also set, this is controlling the behavior "within" that aspect-ratio, otherwise it's within the container for the camera (which is effectively the whole card for single card configurations). |
|
||||
| `pan` | | A dictionary that may contain an `x` and `y` percentage (`0` - `100`) to control the position of the media when "digitally zoomed in" (see `zoom` parameter). This can be effectively used to "pan"/cut the media shown. A value of `0` means maximally to the left or top of the media, a value of `100` means maximally to the right or bottom of the media. See visualizations below. |
|
||||
| `position` | | A dictionary that may contain an `x` and `y` percentage (`0` - `100`) to control the position of the media when the fit is `cover` (for other values of `fit` this option has no effect). This can be effectively used to "pan"/cut the media shown. At any given time, only one of `x` and `y` will have an effect, depending on whether media width is larger than the camera/card dimensions (in which case `x` controls the position) or the media height is larger than the camera/card dimensions (in which case `y` controls the position). A value of `0` means maximally to the left or top of the media, a value of `100` means maximally to the right or bottom of the media. See [CSS object-position](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):    |
|
||||
| `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). |
|
||||
| Option | Default | Description |
|
||||
| ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `fit` | `contain` | If `contain`, the media is contained within the camera container/card and letterboxed if necessary. If `cover`, the media is expanded proportionally (i.e. maintaining the media aspect ratio) until the camera/card dimensions are fully covered. If `fill`, the media is stretched to fill the camera/card dimensions (i.e. ignoring the media aspect ratio). See [CSS object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-fit) for technical details and a visualization. Note that if `aspect_ratio` is also set, this is controlling the behavior "within" that aspect-ratio, otherwise it's within the container for the camera (which is effectively the whole card for single card configurations). |
|
||||
| `pan` | | A dictionary that may contain an `x` and `y` percentage (`0` - `100`) to control the position of the media when "digitally zoomed in" (see `zoom` parameter). This can be effectively used to "pan"/cut the media shown. A value of `0` means maximally to the left or top of the media, a value of `100` means maximally to the right or bottom of the media. See visualizations below. |
|
||||
| `position` | | A dictionary that may contain an `x` and `y` percentage (`0` - `100`) to control the position of the media when the fit is `cover` (for other values of `fit` this option has no effect). This can be effectively used to "pan"/cut the media shown. At any given time, only one of `x` and `y` will have an effect, depending on whether media width is larger than the camera/card dimensions (in which case `x` controls the position) or the media height is larger than the camera/card dimensions (in which case `y` controls the position). A value of `0` means maximally to the left or top of the media, a value of `100` means maximally to the right or bottom of the media. See [CSS object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/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):    |
|
||||
| `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). |
|
||||
|
||||
> [!NOTE]
|
||||
> Layout operations are effectively applied in this order: `fit`, `position`, `view_box`, `zoom` then `pan`.
|
||||
@@ -351,11 +351,11 @@ For live streams, only the `go2rtc` [live provider](./live-provider.md) currentl
|
||||
|
||||
For media, not all [engines](./engine.md) benefit from proxying:
|
||||
|
||||
| Engine | Purpose of proxying |
|
||||
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `frigate` | The Frigate integration already comes with a built-in proxy, so this functionality does not serve any purpose for `frigate`. |
|
||||
| `reolink`, `motioneye` | May be used to fetch videos in cases where the browser may not be able to access the camera/NVR, or the camera/NVR may use a self-signed SSL certificate that your browser would otherwise reject due to [mixed content](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content). |
|
||||
| `generic` | `generic` cameras do not have media, so proxying currently would serve no purpose. |
|
||||
| Engine | Purpose of proxying |
|
||||
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `frigate` | The Frigate integration already comes with a built-in proxy, so this functionality does not serve any purpose for `frigate`. |
|
||||
| `reolink`, `motioneye` | May be used to fetch videos in cases where the browser may not be able to access the camera/NVR, or the camera/NVR may use a self-signed SSL certificate that your browser would otherwise reject due to [mixed content](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Mixed_content). |
|
||||
| `generic` | `generic` cameras do not have media, so proxying currently would serve no purpose. |
|
||||
|
||||
Regardless of the parameters, the integration will never attempt to proxy
|
||||
content if the
|
||||
|
||||
@@ -35,13 +35,13 @@ cameras:
|
||||
# [...]
|
||||
```
|
||||
|
||||
| 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 in the default media filter for 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 in the default media filter for events (clips & snapshots), e.g. [`front_door`, `front_steps`]. |
|
||||
| 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 in the default media filter for 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 in the default media filter for events (clips & snapshots), e.g. [`front_door`, `front_steps`]. |
|
||||
|
||||
## `motioneye`
|
||||
|
||||
|
||||
@@ -13,11 +13,11 @@ 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. |
|
||||
| `height` | `auto` | The 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. |
|
||||
| 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. |
|
||||
| `height` | `auto` | The height for the card. Specified in [CSS units](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units). Generally users should not need to change this. |
|
||||
|
||||
### `aspect_ratio_mode`
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
## Introduction to elements <!-- {docsify-ignore} -->
|
||||
|
||||
This card supports the [Picture Elements configuration
|
||||
syntax](https://www.home-assistant.io/lovelace/picture-elements/) to seamlessly
|
||||
syntax](https://www.home-assistant.io/dashboards/picture-elements/) to seamlessly
|
||||
allow the user to add custom elements to the card.
|
||||
|
||||
```yaml
|
||||
|
||||
@@ -30,7 +30,7 @@ elements:
|
||||
# [...]
|
||||
```
|
||||
|
||||
Configuration is similar to a stock [Picture Elements Icon](https://www.home-assistant.io/lovelace/picture-elements/#icon-element).
|
||||
Configuration is similar to a stock [Picture Elements Icon](https://www.home-assistant.io/dashboards/picture-elements/#icon-element).
|
||||
|
||||
| Parameter | Default | Description |
|
||||
| ------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@@ -119,7 +119,7 @@ elements:
|
||||
# [...]
|
||||
```
|
||||
|
||||
Configuration is similar to a stock [Picture Elements State Icon](https://www.home-assistant.io/lovelace/picture-elements/#state-icon).
|
||||
Configuration is similar to a stock [Picture Elements State Icon](https://www.home-assistant.io/dashboards/picture-elements/#state-icon).
|
||||
|
||||
| Parameter | Default | Description |
|
||||
| ------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
|
||||
@@ -94,7 +94,7 @@ Allows overriding of any CSS value, can be used to tweak theming parameters.
|
||||
|
||||
| Option | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| Any CSS key. Overriding the [Advanced Camera Card](https://github.com/dermotduffy/advanced-camera-card/tree/main/src/scss/themes/base.scss) CSS variables allows changing individual theming parameters, e.g. `--advanced-camera-card-menu-override-background` | Any CSS value, e.g. `red` or `rgba(10, 11, 12, 0.64)`. |
|
||||
| Any CSS key. Overriding the [Advanced Camera Card](https://github.com/dermotduffy/advanced-camera-card/blob/main/src/scss/themes/base.scss) CSS variables allows changing individual theming parameters, e.g. `--advanced-camera-card-menu-override-background` | Any CSS value, e.g. `red` or `rgba(10, 11, 12, 0.64)`. |
|
||||
|
||||
## `triggers`
|
||||
|
||||
|
||||
+11
-2
@@ -54,8 +54,7 @@ To add translations, you can manually edit the JSON translation files in
|
||||
|
||||
[](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/dermotduffy/advanced-camera-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:
|
||||
You can use the [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) extension to speed up the development environment creation. Simply:
|
||||
|
||||
1. Clone the repository to your machine
|
||||
2. Open VS Code on it
|
||||
@@ -84,3 +83,13 @@ Some environment variables are supported in a `.env` file:
|
||||
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.
|
||||
|
||||
### Documentation
|
||||
|
||||
Docs are served with [Docsify](https://docsify.js.org/) from the `docs/` directory and validated with:
|
||||
|
||||
```sh
|
||||
$ yarn run docs-check-links
|
||||
```
|
||||
|
||||
Run this before submitting a documentation PR.
|
||||
|
||||
+2
-2
@@ -203,7 +203,7 @@ cameras:
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> Browsers will reject [mixed content](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content): if you access Home Assistant over `https`, you must also put `go2rtc` behind `https` and use that in the `url` parameter. Check [go2rtc proxying](#go2rtc) as an alternative.
|
||||
> Browsers will reject [mixed content](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Mixed_content): if you access Home Assistant over `https`, you must also put `go2rtc` behind `https` and use that in the `url` parameter. Check [go2rtc proxying](#go2rtc) as an alternative.
|
||||
|
||||
## Card Mod
|
||||
|
||||
@@ -216,7 +216,7 @@ card contents.
|
||||
|
||||
This example changes the color and removes the padding around a [Picture
|
||||
Elements state
|
||||
label](https://www.home-assistant.io/lovelace/picture-elements/#state-label).
|
||||
label](https://www.home-assistant.io/dashboards/picture-elements/#state-label).
|
||||
|
||||
```yaml
|
||||
type: custom:advanced-camera-card
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 973 KiB |
@@ -131,7 +131,7 @@ your Home Assistant log as there may be more information in there.
|
||||
> Frigate must be modified, i.e. Frigate does not encode clips in a Chromecast
|
||||
> compatible format out of the box (specifically: audio must be enabled in the AAC
|
||||
> codec, whether your camera supports audio or not). See the [Frigate Home
|
||||
> Assistant documentation](https://docs.frigate.video/integrations/home-assistant)
|
||||
> Assistant documentation](https://docs.frigate.video/integrations/home-assistant/)
|
||||
> or [this issue](https://github.com/blakeblackshear/frigate/issues/3175) for
|
||||
> more.
|
||||
|
||||
|
||||
@@ -66,7 +66,7 @@ Which in turn will cast the specified Home Assistant dashboard (and view) to the
|
||||
|
||||
For the example above to work, a dashboard with `dashboard-cast` URL must exist:
|
||||
|
||||
|
||||
|
||||
|
||||
Within that dashboard, create an `office` view and finally within that view you can place the Advanced Camera Card configured for that camera for a proper full-screen casting experience:
|
||||
|
||||
@@ -87,7 +87,7 @@ views:
|
||||
|
||||
The `casting` profile pre-configures the card to be casted to a 16:9 screen (such as a TV), including hiding all interactive elements and the menu. The `low-performance` profile is also recommended, as normally casting devices have limited hardware capabilities.
|
||||
|
||||
|
||||
|
||||
|
||||
When casting to a Google Nest Hub, the following configuration can be used:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user