# 2-way Audio

This card supports 2-way audio (e.g. transmitting audio from a microphone to a
suitably equipped camera). In general, due to the myriad of different cameras,
security requirements and browser limitations getting 2-way to work may be
challenging.

## Requirements

### Environmental requirements

- Must have a camera that supports audio out (otherwise what's the point!)
- Camera must be supported by `go2rtc` for 2-way audio (see [supported cameras](https://github.com/AlexxIT/go2rtc#two-way-audio)).
- Must be accessing your Home Assistant instance over `https`. The browser will enforce this.

### Card requirements

- Only Frigate cameras are supported.
- Only the `go2rtc` and `go2rtc-experimental` live providers are supported.
- Only the `webrtc` mode supports 2-way audio.

If your setup supports 2-way audio but detection is intermittent on load:

- Increase `cameras[].go2rtc.metadata_fetch_timeout_seconds`.
- Or force the capability with `cameras[].capabilities.force: ['2-way-audio']`.

## Example configuration

```yaml
type: custom:advanced-camera-card
cameras:
  - camera_entity: camera.office
    live_provider: go2rtc
    go2rtc:
      modes:
        - webrtc
      # Optional: For slower cameras increase timeout (default: 2)
      metadata_fetch_timeout_seconds: 10
```

## 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 an **outbound** 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.
- **Inbound** calls (started by a
  [`view.triggers.actions.trigger: call`](../configuration/view.md?id=trigger-action-configuration)
  trigger -- e.g. a doorbell) open the overlay in a ringing state with only
  two buttons: a red **Reject** and a green **Answer**.
- When a call is answered (outbound calls are answered by definition) the
  inbound audio is unmuted automatically, so the caller can be heard. The
  microphone stays muted by default (push-to-talk) -- tap the microphone button
  in the overlay to speak. Both behaviors are 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`. 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 controlled programmatically with the
[`call_start`](../configuration/actions/custom/README.md?id=call_start),
[`call_answer`](../configuration/actions/custom/README.md?id=call_answer), 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-triggers.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: start (or answer) the call so you can
hear, then unmute the microphone via the in-call overlay 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 is answered:

```yaml
live:
  microphone:
    auto_unmute: ['call']
```

For outbound calls the microphone opens the moment the call starts; for inbound
calls it opens the moment you press the green answer button. Leave
[`auto_unmute`](../configuration/live.md?id=microphone) empty (the default) to
always start muted regardless.