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

feat: Add 'call' support to improve 2-way audio experience (#2486)

Browse Source 
Draws significant inspiration (and direct styling) from
https://github.com/dermotduffy/advanced-camera-card/pull/2447 . Thank
you @Maudfer !

BREAKING CHANGE:

The microphone condition previously bundled two unrelated signals —
whether a two-way-audio session was connected and whether the microphone
was muted. Connection state is now its own dedicated call condition, and
microphone is reserved purely for mute state. Configs are upgraded
automatically (the card rewrites affected conditions under overrides,
elements, and automations). If you maintain config by hand, convert as
follows:

If you only used connected:

# Before
```yaml
condition: microphone
connected: true
```

# After
```yaml
condition: call
call: true
```
If you used both connected and muted — they must be split into two
conditions, since they no longer live together:

# Before
```yaml
condition: microphone
connected: true
muted: false
```

# After
```yaml
condition: and
conditions:
  - condition: call
    call: true
  - condition: microphone
    muted: false
```
This commit is contained in:
Dermot Duffy
2026-06-30 17:45:13 -07:00
committed by dermotduffy
parent bb061a1a55
commit abcba884e5
116 changed files with 3871 additions and 845 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/configuration/actions/custom/README.md
+41
View File
@@ -12,6 +12,34 @@ action: custom:advanced-camera-card-action
| `action` | Must be `custom:advanced-camera-card-action`. |
| `advanced_camera_card_action` | A supported Advanced Camera Card action. One of the below actions. |
## `call_end`
End the [two-way audio](../../../usage/2-way-audio.md) call in progress. Has no effect if no call is active.
```yaml
action: custom:advanced-camera-card-action
advanced_camera_card_action: call_end
```
## `call_start`
Start a [two-way audio](../../../usage/2-way-audio.md) call.
```yaml
action: custom:advanced-camera-card-action
advanced_camera_card_action: call_start
# [...]
```
| Parameter | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | Must be `custom:advanced-camera-card-action`. |
| `advanced_camera_card_action` | Must be `call_start`. |
| `camera` | An optional [camera ID](../../cameras/README.md?id=cameras) to make the call from. If omitted, the selected camera is used. |
| `stream` | An optional [camera ID](../../cameras/README.md?id=cameras) of a 2-way-audio [dependency](../../cameras/README.md?id=dependencies) of `camera`. If omitted, the first eligible stream is used. |
The call starts only if a 2-way-audio-capable stream can be resolved and the browser grants microphone access; otherwise a notification explains why. While the call is in progress an on-screen overlay is shown and (by default) disruptive actions are locked -- see [`live.controls.call`](../../live.md?id=call).
## `camera_select`
Select a given camera.
@@ -683,6 +711,19 @@ advanced_camera_card_action: unmute
```yaml
elements:
- type: custom:advanced-camera-card-menu-icon
icon: mdi:phone
title: Start a two-way audio call
tap_action:
action: custom:advanced-camera-card-action
advanced_camera_card_action: call_start
camera: camera.front_door
- type: custom:advanced-camera-card-menu-icon
icon: mdi:phone-hangup
title: End a two-way audio call
tap_action:
action: custom:advanced-camera-card-action
advanced_camera_card_action: call_end
- type: custom:advanced-camera-card-menu-icon
icon: mdi:alpha-a-circle
title: Select Front Door
docs/configuration/conditions.md
+27 -15
View File
@@ -29,6 +29,21 @@ conditions:
| `condition` | Must be `and`. |
| `conditions` | A list of other conditions _all_ of which must evaluate `true` in order for this condition to evaluate `true`. |
## `call`
Matches based on whether a [two-way audio](../usage/2-way-audio.md) call is in progress.
```yaml
conditions:
- condition: call
# [...]
```
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `condition` | Must be `call`. |
| `call` | If `true` (the default) or `false`, the condition is satisfied when a two-way audio call is or is not in progress respectively. |
## `camera`
Matches based on the selected camera. Does not match other cameras (whether
@@ -197,14 +212,10 @@ conditions:
# [...]
```
| 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. |
When multiple parameters are specified they must all match for the condition to
match.
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `condition` | Must be `microphone`. |
| `muted` | If `true` or `false`, the condition is satisfied when the microphone is muted or unmuted respectively. |
## `not`
@@ -391,12 +402,14 @@ conditions:
```yaml
conditions:
- condition: camera
cameras:
- camera.office
- condition: call
call: true
- condition: camera
cameras:
- camera.office
- condition: config
paths:
- "menu.style"
- 'menu.style'
- condition: display_mode
display_mode: single
- condition: expand
@@ -416,7 +429,6 @@ conditions:
- condition: media_loaded
media_loaded: true
- condition: microphone
connected: true
muted: true
- condition: numeric_state
entity: sensor.office_temperature
@@ -435,8 +447,8 @@ conditions:
users:
- 581fca7fdc014b8b894519cc531f9a04
- condition: user_agent
user_agent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
user_agent_re: "Chrome/"
user_agent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36'
user_agent_re: 'Chrome/'
casting: true
companion: true
- condition: view
docs/configuration/live.md
+57 -31
View File
@@ -7,23 +7,23 @@ 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 or grid. `hidden` will automatically mute when the camera becomes hidden (e.g. browser tab change) 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 or grid. `hidden` will automatically pause when the browser/tab becomes hidden. Use an empty list (`[]`) to never automatically pause. **Caution**: Some live providers (e.g. `jsmpeg`) may not offer human-accessible means to resume play if it is paused, unless the `auto_play` option is used. |
| `auto_play` | `[selected, visible]` | A list of conditions in which live camera feeds are automatically played. `selected` will automatically play when a camera is selected in a carousel or grid. `visible` will automatically play when a camera becomes visible (e.g. browser tab change, or visible in a grid but not selected). Use an empty list (`[]`) to never automatically play. Some live providers (e.g. `webrtc-card`, `jsmpeg`) do not support the prevention of automatic play on initial load, but should still respect the value of this parameter on play-after-pause. |
| `auto_unmute` | `[microphone]` | A list of conditions in which live camera feeds are unmuted. `selected` will automatically unmute when a camera is selected in a carousel or grid. `visible` will automatically unmute when a camera becomes visible (e.g. a browser/tab change, or visible in a grid but not selected). `microphone` will automatically unmute after the microphone is unmuted. Use an empty list (`[]`) to never automatically unmute. Some browsers will not allow automated unmute until the user has interacted with the page in some way -- if the user has not then the browser may pause the media instead. |
| `controls` | | Configuration for the `live` view controls. See [`controls`](#controls). |
| `display` | | Controls whether to show a single or grid `live` view. See [`display`](#display). |
| `draggable` | `true` | Whether or not the live carousel can be dragged left or right, via touch/swipe and mouse dragging. |
| `lazy_load` | `true` | Whether or not to lazily load cameras in the camera carousel. Setting this to `false` will cause all cameras to load simultaneously when the `live` carousel is opened (or cause all cameras to load continually if `preload` is also `true`). This will result in a smoother carousel experience at a cost of (potentially) a substantial amount of continually streamed data. |
| `lazy_unload` | `[]` | A list of conditions in which live camera feeds are unloaded. `unselected` will unload a camera when it is not visible in the carousel/grid and `hidden` will unload a camera when the browser itself is minimized or the browser tab changes. An empty list (`[]`, the default) will never automatically unload a stream once loaded unless the user navigates away entirely, so that it's always instantly visible on carousel scroll. Once unloaded, subsequently revisiting the camera will cause a reloading delay. Some live providers (e.g. `webrtc-card`) implement their own lazy unloading independently which may occur regardless of the value of this setting. |
| `microphone` | | See [`microphone`](#microphone). |
| `preload` | `false` | Whether or not to preload the live view. Preloading causes the live view to render in the background regardless of what view is actually shown, so it's instantly available when requested. The currently-selected camera's media is loaded in the background; other cameras follow the `lazy_load` setting (set `lazy_load: false` to preload them all). This consumes additional network/CPU resources continually. |
| `show_image_during_load` | `true` | If `true`, during the initial stream load, the `image` live provider will be shown instead of the loading video stream. This still image will auto-refresh and is replaced with the live stream once loaded. |
| `transition_effect` | `slide` | Effect to apply as a transition between live cameras. Accepted values: `slide` or `none`. |
| `zoomable` | `true` | Whether or not the live carousel can be zoomed and panned, via touch/pinch and mouse scroll wheel with `ctrl` held. |
| Option | Default | Description |
| ------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actions` | | [Actions](actions/README.md) to use for the `live` view. |
| `auto_mute` | `[unselected, hidden, microphone, call]` | A list of conditions in which live camera feeds are muted. `unselected` will automatically mute when a camera is unselected in the carousel or grid. `hidden` will automatically mute when the camera becomes hidden (e.g. browser tab change). `microphone` will automatically mute after the microphone is muted as long as the camera stays selected (see the `live.microphone.mute_after_microphone_mute_seconds` to control how long after). `call` will automatically mute the inbound audio when a [two-way audio](../usage/2-way-audio.md) call ends. Use an empty list (`[]`) to never automatically mute. Note that if `auto_play` is enabled, the stream may mute itself automatically in order to honor the `auto_play` setting, as some browsers will not auto play media that is unmuted -- that is to say, where necessary, the `auto_play` parameter will take priority over the `auto_mute` parameter. |
| `auto_pause` | `[]` | A list of conditions in which live camera feeds are automatically paused. `unselected` will automatically pause when a camera is unselected in the carousel or grid. `hidden` will automatically pause when the browser/tab becomes hidden. Use an empty list (`[]`) to never automatically pause. **Caution**: Some live providers (e.g. `jsmpeg`) may not offer human-accessible means to resume play if it is paused, unless the `auto_play` option is used. |
| `auto_play` | `[selected, visible]` | A list of conditions in which live camera feeds are automatically played. `selected` will automatically play when a camera is selected in a carousel or grid. `visible` will automatically play when a camera becomes visible (e.g. browser tab change, or visible in a grid but not selected). Use an empty list (`[]`) to never automatically play. Some live providers (e.g. `webrtc-card`, `jsmpeg`) do not support the prevention of automatic play on initial load, but should still respect the value of this parameter on play-after-pause. |
| `auto_unmute` | `[microphone, call]` | A list of conditions in which live camera feeds are unmuted. `selected` will automatically unmute when a camera is selected in a carousel or grid. `visible` will automatically unmute when a camera becomes visible (e.g. a browser/tab change, or visible in a grid but not selected). `microphone` will automatically unmute after the microphone is unmuted. `call` will automatically unmute the inbound audio when a [two-way audio](../usage/2-way-audio.md) call starts, so the caller can be heard immediately. Use an empty list (`[]`) to never automatically unmute. Some browsers will not allow automated unmute until the user has interacted with the page in some way -- if the user has not then the browser may pause the media instead. |
| `controls` | | Configuration for the `live` view controls. See [`controls`](#controls). |
| `display` | | Controls whether to show a single or grid `live` view. See [`display`](#display). |
| `draggable` | `true` | Whether or not the live carousel can be dragged left or right, via touch/swipe and mouse dragging. |
| `lazy_load` | `true` | Whether or not to lazily load cameras in the camera carousel. Setting this to `false` will cause all cameras to load simultaneously when the `live` carousel is opened (or cause all cameras to load continually if `preload` is also `true`). This will result in a smoother carousel experience at a cost of (potentially) a substantial amount of continually streamed data. |
| `lazy_unload` | `[]` | A list of conditions in which live camera feeds are unloaded. `unselected` will unload a camera when it is not visible in the carousel/grid and `hidden` will unload a camera when the browser itself is minimized or the browser tab changes. An empty list (`[]`, the default) will never automatically unload a stream once loaded unless the user navigates away entirely, so that it's always instantly visible on carousel scroll. Once unloaded, subsequently revisiting the camera will cause a reloading delay. Some live providers (e.g. `webrtc-card`) implement their own lazy unloading independently which may occur regardless of the value of this setting. |
| `microphone` | | See [`microphone`](#microphone). |
| `preload` | `false` | Whether or not to preload the live view. Preloading causes the live view to render in the background regardless of what view is actually shown, so it's instantly available when requested. The currently-selected camera's media is loaded in the background; other cameras follow the `lazy_load` setting (set `lazy_load: false` to preload them all). This consumes additional network/CPU resources continually. |
| `show_image_during_load` | `true` | If `true`, during the initial stream load, the `image` live provider will be shown instead of the loading video stream. This still image will auto-refresh and is replaced with the live stream once loaded. |
| `transition_effect` | `slide` | Effect to apply as a transition between live cameras. Accepted values: `slide` or `none`. |
| `zoomable` | `true` | Whether or not the live carousel can be zoomed and panned, via touch/pinch and mouse scroll wheel with `ctrl` held. |
## `controls`
@@ -38,11 +38,28 @@ live:
| Option | Default | Description |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `builtin` | `true` | Whether to show the built in (browser) video controls on live video. |
| `call` | | Configures the on-screen [two-way audio](../usage/2-way-audio.md) call controls. See [`call`](#call). |
| `next_previous` | | Configures how the "Next & Previous" controls are shown on the `live` view. See [`next_previous`](#next_previous). |
| `thumbnails` | | Configures how thumbnails are shown on the `live` view. See [`thumbnails`](#thumbnails). |
| `timeline` | | Configures how the mini-timeline is shown on the `live` view. See [`timeline`](#timeline). |
| `wheel` | `true` | Whether to allow mouse wheel to scroll through the carousel. |
### `call`
Configures the on-screen controls shown during a [two-way audio](../usage/2-way-audio.md) call. The overlay appears whenever a call is in progress and offers buttons to mute/unmute the microphone, mute/unmute the inbound audio, and end the call.
```yaml
live:
controls:
call:
# [...]
```
| Option | Default | Description |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `button_size` | `40` | The size of the call control buttons in pixels. Must be >= `20`. |
| `lock` | `true` | Whether to lock the rest of the card controls/actions while a call is in progress. Prevents an accidental tap, swipe or action mid-call. Set to `false` to allow interactions regardless of call state. |
### `next_previous`
Configures how the "Next & Previous" controls are shown on the live view.
@@ -54,10 +71,11 @@ live:
# [...]
```
| 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` . |
| Option | Default | Description |
| ----------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_hide` | `[call, casting]` | The conditions under which the next/previous controls auto-hide: a list of zero or more of `call` (a [two-way audio](../usage/2-way-audio.md) call is active) and `casting` (the card is being cast). Set to `[]` to disable. |
| `size` | `48` | The size of the next/previous controls in pixels. Must be >= `20`. |
| `style` | `chevrons` | When viewing live cameras, what kind of controls to show to move to the previous/next camera. Acceptable values: `chevrons`, `icons`, `none` . |
### `ptz`
@@ -177,14 +195,13 @@ 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. |
| `auto_mute` | `[]` | A list of conditions in which the microphone is muted. `unselected` will automatically mute the microphone when a camera is unselected in the carousel or grid. `hidden` will automatically mute the microphone when the card becomes hidden (e.g. browser/tab change). Use an empty list (`[]`, the default) to never automatically mute the microphone via these conditions. |
| `auto_unmute` | `[]` | A list of conditions in which the microphone is unmuted. `selected` will automatically unmute the microphone when a camera is selected in the carousel or grid (useful for an always-hot mic on the currently selected camera). `visible` will automatically unmute when the card becomes visible. Use an empty list (`[]`, the default) to never automatically unmute the microphone via these conditions. The browser will still prompt for microphone permission on first unmute. |
| `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`. |
| `lock` | `true` | Whether to lock disruptive actions (view/camera/substream changes, pause, reload, casting) while the microphone is unmuted. Prevents an accidental tap, swipe, or button press from cutting off the session mid-sentence during 2-way audio. Set to `false` to allow all actions regardless of microphone state. |
| `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`. |
| Option | Default | Description |
| ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `always_connected` | `false` | Whether or not to keep the microphone stream continually connected while the card is running, or only connect it when first needed (default) -- typically when a [two-way audio](../usage/2-way-audio.md) call is started. In the latter case there'll be a connection reset the first time the microphone connects -- using this option can avoid that reset. |
| `auto_mute` | `[call]` | A list of conditions in which the microphone is muted. `unselected` will automatically mute the microphone when a camera is unselected in the carousel or grid. `hidden` will automatically mute the microphone when the card becomes hidden (e.g. browser/tab change). `call` will automatically mute the microphone when a [two-way audio](../usage/2-way-audio.md) call ends. Use an empty list (`[]`) to never automatically mute the microphone via these conditions. |
| `auto_unmute` | `[]` | A list of conditions in which the microphone is unmuted. `selected` will automatically unmute the microphone when a camera is selected in the carousel or grid. `visible` will automatically unmute when the card becomes visible. `call` will automatically unmute the microphone when a [two-way audio](../usage/2-way-audio.md) call starts. By default this list is empty, so the microphone stays muted when a call starts (push-to-talk) -- tap the microphone button in the call overlay to talk. The microphone is still connected when the call starts (just left muted), so the browser may prompt for microphone permission at that point. |
| `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.
@@ -201,8 +218,11 @@ live:
auto_mute:
- unselected
- hidden
- microphone
- call
auto_unmute:
- microphone
- call
preload: false
lazy_load: true
lazy_unload: []
@@ -211,7 +231,13 @@ live:
transition_effect: slide
controls:
builtin: true
call:
button_size: 40
lock: true
next_previous:
auto_hide:
- call
- casting
style: chevrons
size: 48
wheel: true
@@ -247,10 +273,10 @@ live:
24h: true
microphone:
always_connected: false
auto_mute: []
auto_mute:
- call
auto_unmute: []
disconnect_seconds: 90
lock: true
mute_after_microphone_mute_seconds: 60
display:
mode: single
docs/configuration/media-viewer.md
+7 -4
View File
@@ -50,10 +50,11 @@ media_viewer:
# [...]
```
| 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` . |
| Option | Default | Description |
| ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_hide` | `[casting]` | The conditions under which the next/previous controls auto-hide. The only condition is `casting` (the card is being cast). Set to `[]` to disable. |
| `size` | `48` | The size of the next/previous controls in pixels. Must be >= `20`. |
| `style` | `thumbnails` | When viewing media, what kind of controls to show to move to the previous/next media item. Acceptable values: `thumbnails`, `chevrons`, `none` . |
### `ptz`
@@ -183,6 +184,8 @@ media_viewer:
controls:
builtin: true
next_previous:
auto_hide:
- casting
size: 48
style: thumbnails
wheel: true
docs/configuration/menu.md
+28 -17
View File
@@ -7,13 +7,14 @@ 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 [`buttons`](#buttons). |
| `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 [`style`](#style). |
| 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`). |
| `auto_hide` | `[call, casting]` | The conditions under which the menu auto-hides. A list of zero or more of `call` (a [two-way audio](../usage/2-way-audio.md) call is active) and `casting` (the card is being cast, e.g. to a Chromecast). Set to `[]` to disable. |
| `button_size` | `40` | The size of the menu buttons in pixels. Must be >= `20`. |
| `buttons` | | Whether to show or hide built-in buttons. See [`buttons`](#buttons). |
| `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 [`style`](#style). |
## `buttons`
@@ -28,6 +29,7 @@ menu:
| Button name | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `call` | The `call` menu button: starts or ends a [two-way audio](../usage/2-way-audio.md) call. |
| `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. |
@@ -42,7 +44,7 @@ menu:
| `iris` | The main Advanced Camera Card `iris` menu button: brings the user to the default configured view (`view.default`), or collapses/expands the menu if the `menu.style` is `hidden` . |
| `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). |
| `microphone` | The `microphone` button mutes/unmutes the microphone. It is only shown during an active call, since the microphone only transmits while a call is in progress. See [Using 2-way audio](../usage/2-way-audio.md). |
| `mute` | The `mute` button: toggles the mute state of the selected media. |
| `pip` | The `pip` menu button: enter Picture-in-Picture mode. Floats the video element as a native browser overlay. |
| `play` | The `play` button: toggles the play/pause state of the selected media. |
@@ -57,15 +59,15 @@ menu:
### Options for each button
| Option | Default | Description |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alignment` | `matching` | Whether this menu item should have an alignment that is `matching` the menu alignment or `opposing` the menu alignment. Can be used to create two separate groups of buttons on the menu. The `priority` option orders buttons within a given `alignment`. |
| `enabled` | `true` for `camera_ui`, `cameras`, `display_mode`, `download`, `folders`, `fullscreen`, `gallery`, `info`, `iris`, `live`, `media_player`, `set_review`, `substreams` and `timeline`. `false` for `clips`, `expand`, `image`, `microphone`, `mute`, `pip`, `play`, `ptz_controls`, `ptz_home`, `recordings`, `reviews`, `screenshot` and `snapshots`. | Whether or not to show the button. |
| `icon` | | An icon to overriding the default for that button, e.g. `mdi:camera-front`. See also [custom icons](../usage/custom-icons.md). |
| `inert` | `false` | If `true` the button is shown but rendered as inert (greyed out, non-interactive). Differs from `enabled: false`, which removes the button entirely. |
| `permanent` | `false` | If `false` the menu item is hidden when the menu has the `hidden` style and the menu is closed, otherwise it is shown (and sorted to the front). |
| `priority` | `50` | The menu item priority. Higher priority items 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`). Priority applies separately to `matching` and `opposing` groups (see `alignment` above). Minimum `0`, maximum `100`. |
| `state_color` | `true` | Whether to colorize the button based on the state of a related entity (where applicable). |
| Option | Default | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alignment` | `matching` | Whether this menu item should have an alignment that is `matching` the menu alignment or `opposing` the menu alignment. Can be used to create two separate groups of buttons on the menu. The `priority` option orders buttons within a given `alignment`. |
| `enabled` | `true` for `call`, `camera_ui`, `cameras`, `display_mode`, `download`, `folders`, `fullscreen`, `gallery`, `info`, `iris`, `live`, `media_player`, `set_review`, `substreams` and `timeline`. `false` for `clips`, `expand`, `image`, `microphone`, `mute`, `pip`, `play`, `ptz_controls`, `ptz_home`, `recordings`, `reviews`, `screenshot` and `snapshots`. | Whether or not to show the button. |
| `icon` | | An icon to overriding the default for that button, e.g. `mdi:camera-front`. See also [custom icons](../usage/custom-icons.md). |
| `inert` | `false` | If `true` the button is shown but rendered as inert (greyed out, non-interactive). Differs from `enabled: false`, which removes the button entirely. |
| `permanent` | `false` | If `false` the menu item is hidden when the menu has the `hidden` style and the menu is closed, otherwise it is shown (and sorted to the front). |
| `priority` | `50` | The menu item priority. Higher priority items 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`). Priority applies separately to `matching` and `opposing` groups (see `alignment` above). Minimum `0`, maximum `100`. |
| `state_color` | `true` | Whether to colorize the button based on the state of a related entity (where applicable). |
### Additional options: `microphone`
@@ -100,7 +102,16 @@ This card supports several menu styles.
```yaml
menu:
alignment: left
auto_hide:
- call
- casting
buttons:
call:
priority: 50
enabled: true
inert: false
alignment: matching
icon: mdi:phone
camera_ui:
priority: 50
enabled: true
docs/configuration/status-bar.md
+11 -7
View File
@@ -7,13 +7,14 @@ 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` | `40` | The height of the status bar in pixels. |
| `items` | | Whether to show or hide built-in status bar items. See [`items`](#items). |
| `style` | `popup` | The status bar style to show by default, one of `none`, `hover`, `hover-card`, `overlay`, `outside` or `popup`. See [`style`](#style). |
| Option | Default | Description |
| --------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_hide` | `[call, casting]` | The conditions under which the status bar auto-hides. A list of zero or more of `call` (a [two-way audio](../usage/2-way-audio.md) call is active) and `casting` (the card is being cast, e.g. to a Chromecast). Set to `[]` to disable. |
| `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` | `40` | The height of the status bar in pixels. |
| `items` | | Whether to show or hide built-in status bar items. See [`items`](#items). |
| `style` | `popup` | The status bar style to show by default, one of `none`, `hover`, `hover-card`, `overlay`, `outside` or `popup`. See [`style`](#style). |
## `items`
@@ -73,6 +74,9 @@ This card supports several menu styles.
```yaml
status_bar:
auto_hide:
- call
- casting
position: bottom
popup_seconds: 3
height: 40
docs/images/call-sequence.svg
+1
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

docs/uml/call-sequence.puml
+59
View File
@@ -0,0 +1,59 @@
@startuml
skinparam backgroundColor white
actor User
participant "Call" as Card
participant Microphone as Mic
actor Guest
opt <color:#43a047>**""live.microphone.always_connected""**</color> is enabled
Card -> Mic : Microphone connection attempted (muted)
note over Mic : Connected at card load, before (and independent of) any call
Mic --> User : Microphone access granted
end
User -> Card : Start a call
note over User, Card
Via Call menu button or <color:#43a047>**""call_start""**</color> action.
Needs a camera that supports 2-way audio
end note
opt <color:#43a047>**""live.microphone.always_connected""**</color> not enabled
Card -> Mic : Microphone connection attempted (muted)
note over Mic : Stays muted by default (<color:#43a047>**""live.microphone.auto_unmute""**</color>)
Mic --> User : Microphone access granted
end
note over User, Mic
The microphone must connect for the call to proceed —
if access is denied or unsupported, the call does not start
end note
Card --> User : You hear the caller
note over Card
Inbound audio unmutes if configured (<color:#43a047>**""live.auto_unmute""**</color>)
Menu, status bar & next/previous hide (<color:#43a047>**""auto_hide""**</color>)
Camera navigation is locked (<color:#43a047>**""live.controls.call.lock""**</color>)
end note
User -> Mic : Unmute to talk
note over Mic : List 'call' in <color:#43a047>**""live.microphone.auto_unmute""**</color> to unmute automatically
loop Until the call ends
User -[#red]> Guest : Talking
Guest -[#red]-> User : Responding
end
User -> Card : End the call
note over User, Card
Via Hang-up button, <color:#43a047>**""call_end""**</color> action, or — when
<color:#43a047>**""live.controls.call.lock""**</color> is disabled — navigating away
end note
Card --> User : Inbound audio mutes (<color:#43a047>**""live.auto_mute""**</color>)
Card -> Mic : Microphone mutes (<color:#43a047>**""live.microphone.auto_mute""**</color>)
note over Mic
Disconnects after <color:#43a047>**""live.microphone.disconnect_seconds""**</color>
unless <color:#43a047>**""live.microphone.always_connected""**</color>
end note
@enduml
docs/usage/2-way-audio.md
+64 -18
View File
@@ -17,8 +17,7 @@ challenging.
- Only Frigate cameras are supported.
- Only the `go2rtc` live provider is supported.
- Only the `webrtc` mode supports 2-way audio:
- Must have microphone menu button enabled:
- Only the `webrtc` mode supports 2-way audio.
If your setup supports 2-way audio but detection is intermittent on load:
@@ -37,24 +36,71 @@ cameras:
- webrtc
# Optional: For slower cameras increase timeout (default: 2)
metadata_fetch_timeout_seconds: 10
menu:
buttons:
microphone:
enabled: true
```
## Usage
Two-way audio is driven by the **call** menu button (a phone icon). It is
enabled by default and appears in the `live` view whenever the selected camera
-- or one of its [dependencies](../configuration/cameras/README.md?id=dependencies)
-- supports 2-way audio.
- Tap the call button to start a call. An on-screen overlay appears with
controls to mute/unmute the microphone, mute/unmute the inbound audio, and end
the call. When more than one 2-way-audio camera is available the button
becomes a submenu with one entry per camera.
- When a call starts the inbound audio is unmuted automatically, so the caller
can be heard immediately. The microphone stays muted by default
(push-to-talk) -- tap the microphone button in the overlay to speak. This is
configurable via [`live.microphone.auto_unmute`](../configuration/live.md?id=microphone)
and [`live.auto_unmute`](../configuration/live.md).
- The camera will always load _without_ the microphone connected, unless the
[`always_connected`](../configuration/live.md?id=microphone) microphone option is
set to `true`.
- To speak, hold-down the microphone menu button.
- On first press, this will reset the `webrtc` connection to include 2-way
audio unless [`always_connected`](../configuration/live.md?id=microphone) has
been used.
- Thereafter hold the microphone button down to unmute/speak, let go to
mute.
- The video will automatically reset to remove the microphone after the number
of seconds specified by
[`disconnect_seconds`](../configuration/live.md?id=microphone) configuration have
elapsed since the last mute/unmute press.
[`always_connected`](../configuration/live.md?id=microphone) microphone option
is set to `true`. On the first call there may be a brief `webrtc` connection
reset to include 2-way audio.
- While a call is in progress the card locks disruptive actions (camera and
substream changes, casting, reload, etc.) so an accidental tap, swipe, or
button press doesn't cut the call off. Set
[`live.controls.call.lock`](../configuration/live.md?id=call) to `false` to
disable this.
- End the call with the overlay's end-call button. When the call ends the
microphone and inbound audio are muted again.
- The video automatically resets to remove the microphone after the number of
seconds specified by [`disconnect_seconds`](../configuration/live.md?id=microphone)
have elapsed since the call ended.
Calls can also be started and ended programmatically with the
[`call_start`](../configuration/actions/custom/README.md?id=call_start) and
[`call_end`](../configuration/actions/custom/README.md?id=call_end) actions --
for example, from an [automation](../configuration/automations.md) that fires
when a doorbell sensor triggers. The [`call` condition](../configuration/conditions.md?id=call)
can be used to show or hide elements while a call is in progress.
### Call lifecycle
The diagram below traces a call from start to finish:
![Call lifecycle sequence diagram](../images/call-sequence.svg ':size=600')
## Talking with a single tap
By default, two taps are needed to speak: the call button starts the call (so
you can hear), then the microphone button in the call overlay unmutes your
microphone (so you can be heard). This push-to-talk default keeps the microphone
muted until you explicitly choose to speak.
To collapse that to a single tap, unmute the microphone automatically when a
call starts:
```yaml
live:
microphone:
auto_unmute: ['call']
```
The call button then behaves as a toggle -- one tap starts the call and opens
the microphone, a second tap ends the call and closes it again. Note this also
opens the microphone for calls started by an
[automation](../configuration/automations.md); leave
[`auto_unmute`](../configuration/live.md?id=microphone) empty (the default) to
always start muted.