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

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
```

src/components-lib/auto-hide.ts

@@ -0,0 +1,21 @@
+import { AutoHideCondition } from '../config/schema/common/auto-hide';
+import { isBeingCasted } from '../utils/casting';
+
+// Whether each auto-hide condition is currently active.
+export interface AutoHideState {
+  call: boolean;
+  casting: boolean;
+}
+
+// Single constructor for the auto-hide state. `casting` is read from the
+// environment; `call` is the only context-specific input, supplied by the
+// caller (absent when no call notion applies, e.g. the media viewer).
+export const resolveAutoHideState = (callActive = false): AutoHideState => ({
+  call: callActive,
+  casting: isBeingCasted(),
+});
+
+export const isAutoHidden = (
+  autoHide: readonly AutoHideCondition[],
+  state: AutoHideState,
+): boolean => autoHide.some((condition) => state[condition]);

src/components-lib/live/microphone-actions-controller.ts

@@ -26,6 +26,7 @@ interface MicrophoneActionsControllerOptions {
 export class MicrophoneActionsController {
   private _options: MicrophoneActionsControllerOptions | null = null;
   private _selectedCamera: string | null = null;
+  private _callActive = false;
   private _visibilityObserver: VisibilityObserver;
 
   constructor() {
@@ -38,6 +39,27 @@ export class MicrophoneActionsController {
     this._options = options;
   }
 
+  /**
+   * Notifies the controller of the call-active state, acting only on a genuine
+   * transition. The initial state is treated as inactive, so a first-ever
+   * `true` counts -- the call rules apply even when the live view first
+   * appears during an active call.
+   *
+   * Call start unmutes the microphone only if the user opted into
+   * `microphone.auto_unmute: ['call']`.
+   */
+  public setCallActive(active: boolean): void {
+    if (active === this._callActive) {
+      return;
+    }
+    this._callActive = active;
+    if (active) {
+      this._unmuteIfConfigured('call');
+    } else {
+      this._muteIfConfigured('call');
+    }
+  }
+
   public setRoot(root: HTMLElement): void {
     this._visibilityObserver.setRoot(root);
   }

src/components-lib/media-actions-controller.ts

@@ -17,7 +17,6 @@ export interface MediaActionsControllerOptions {
   autoPauseConditions?: readonly AutoPauseCondition[];
   autoMuteConditions?: readonly AutoMuteCondition[];
 
-  microphoneState?: MicrophoneState;
   microphoneMuteSeconds?: number;
 }
 
@@ -40,6 +39,16 @@ export class MediaActionsController {
   private _microphoneMuteTimer = new Timer();
   private _root: RenderRoot | null = null;
 
+  // Audio-related state fed in via dedicated setters (not `setOptions`, which
+  // is pure configuration).
+  private _microphoneState?: MicrophoneState;
+  private _callActive = false;
+
+  // Deferred because the media player is not always ready when a call starts:
+  // the call may start from another view, or engage a substream that is still
+  // loading. Applied by `_applyPendingCallStartAction`.
+  private _pendingCallStartAction = false;
+
   private _eventListeners = new Map<HTMLElement, () => void>();
   private _children: MediaPlayerElement[] = [];
   private _target: MediaActionsTarget | null = null;
@@ -53,16 +62,34 @@ export class MediaActionsController {
   }
 
   public setOptions(options: MediaActionsControllerOptions): void {
-    if (this._options?.microphoneState !== options.microphoneState) {
-      this._microphoneStateChangeHandler(
-        this._options?.microphoneState,
-        options.microphoneState,
-      );
-    }
-
     this._options = options;
   }
 
+  public setMicrophoneState(state: MicrophoneState): void {
+    const previous = this._microphoneState;
+    this._microphoneState = state;
+    this._microphoneStateChangeHandler(previous, state);
+  }
+
+  // Audio-out auto-mute/unmute driven by the call lifecycle: unmute on call
+  // start (hear the caller), mute on call end. Acts only on a genuine
+  // transition. The first-ever `true` counts as a transition: a carousel that
+  // loads while a call is already active (e.g. `call_start` dispatched from a
+  // non-live view) must still unmute.
+  public setCallActive(active: boolean): void {
+    if (active === this._callActive) {
+      return;
+    }
+    this._callActive = active;
+    if (active) {
+      this._pendingCallStartAction = true;
+      this._applyPendingCallStartAction();
+    } else {
+      this._pendingCallStartAction = false;
+      this._muteTargetIfConfigured('call');
+    }
+  }
+
   public hasRoot(): boolean {
     return !!this._root;
   }
@@ -94,6 +121,9 @@ export class MediaActionsController {
       index,
     };
 
+    // A call may have started before this target existed; honor it now.
+    await this._applyPendingCallStartAction();
+
     if (selected) {
       await this._unmuteTargetIfConfigured('selected');
       await this._playTargetIfConfigured('selected');
@@ -132,6 +162,30 @@ export class MediaActionsController {
     await (await this._children[index]?.getMediaPlayerController())?.unmute();
   }
 
+  // The call-start action is currently a single unmute (hear the caller),
+  // applied once the media player is ready. The call-end mute is not deferred
+  // here: a mute that misses a not-yet-ready element is harmless, since
+  // elements start muted.
+  private async _applyPendingCallStartAction(): Promise<void> {
+    if (
+      !this._pendingCallStartAction ||
+      this._target === null ||
+      !this._options?.autoUnmuteConditions?.includes('call')
+    ) {
+      return;
+    }
+
+    const controller =
+      await this._children[this._target.index]?.getMediaPlayerController();
+    if (!controller) {
+      // Media not ready yet -- retried from `setTarget` / `_mediaLoadedHandler`.
+      return;
+    }
+
+    this._pendingCallStartAction = false;
+    await controller.unmute();
+  }
+
   private async _pauseAllIfConfigured(condition: AutoPauseCondition): Promise<void> {
     if (this._options?.autoPauseConditions?.includes(condition)) {
       for (const index of this._children.keys()) {
@@ -190,6 +244,10 @@ export class MediaActionsController {
     // media load.
     const condition = this._target.selected ? 'selected' : 'visible';
     await this._unmuteTargetIfConfigured(condition);
+
+    // The media element is ready now; apply any call-start action that was
+    // deferred because it was not.
+    await this._applyPendingCallStartAction();
     await this._playTargetIfConfigured(condition);
   };
 

src/components-lib/menu-button-controller.ts

@@ -1,5 +1,6 @@
 import { StyleInfo } from 'lit/directives/style-map';
 import { CameraManager } from '../camera-manager/manager';
+import { CallManager } from '../card-controller/call/manager';
 import { FoldersManager } from '../card-controller/folders/manager';
 import { FullscreenManager } from '../card-controller/fullscreen/fullscreen-manager';
 import { MediaPlayerManager } from '../card-controller/media-player-manager';
@@ -17,6 +18,8 @@ import { HomeAssistant } from '../ha/types';
 import { localize } from '../localize/localize.js';
 import { MediaLoadedInfo } from '../types';
 import {
+  createCallEndAction,
+  createCallStartAction,
   createCameraAction,
   createDisplayModeAction,
   createGeneralAction,
@@ -30,8 +33,8 @@ import {
 import { arrayify, isTruthy } from '../utils/basic';
 import { isBeingCasted } from '../utils/casting';
 import { getPTZTarget } from '../utils/ptz';
-import { getStreamCameraID, hasSubstream } from '../utils/substream';
 import { ViewItemClassifier } from '../view/item-classifier';
+import { getStreamCameraID, hasSubstream } from '../view/substream';
 import { resolveViewName } from '../view/utils/resolve-default';
 import { View } from '../view/view';
 import {
@@ -40,6 +43,7 @@ import {
 } from '../view/view-support';
 
 export interface MenuButtonControllerOptions {
+  callManager?: CallManager | null;
   currentMediaLoadedInfo?: MediaLoadedInfo | null;
   showCameraUIButton?: boolean;
   fullscreenManager?: FullscreenManager | null;
@@ -94,11 +98,13 @@ export class MenuButtonController {
       this._getInfoButton(config, cameraManager, options?.view),
       this._getSetReviewButton(config, options?.view),
       this._getCameraUIButton(config, options?.showCameraUIButton),
+      this._getCallButton(config, cameraManager, options?.callManager, options?.view),
       this._getMicrophoneButton(
         config,
         cameraManager,
         options?.view,
         options?.microphoneManager,
+        options?.callManager,
       ),
       this._getExpandButton(config, options?.inExpandedMode),
       this._getFullscreenButton(config, options?.fullscreenManager),
@@ -480,17 +486,91 @@ export class MenuButtonController {
       : null;
   }
 
+  private _getCallButton(
+    config: AdvancedCameraCardConfig,
+    cameraManager: CameraManager,
+    callManager?: CallManager | null,
+    view?: View | null,
+  ): MenuItem | null {
+    if (!view?.camera || !view.is('live')) {
+      return null;
+    }
+    const cameraID = view.camera;
+
+    // The call targets: the selected camera and/or any 2-way-audio-capable
+    // dependency.
+    const targets = [
+      ...cameraManager.getStore().getAllDependentCameras(cameraID, '2-way-audio'),
+    ];
+    if (!targets.length) {
+      return null;
+    }
+
+    // In a call: a single hang-up button, regardless of target count.
+    if (callManager?.isActive()) {
+      return {
+        icon: 'mdi:phone-hangup',
+        title: localize('config.live.controls.call.end'),
+        style: this._getEmphasizedStyle(true),
+        ...config.menu.buttons.call,
+        type: 'custom:advanced-camera-card-menu-icon',
+        tap_action: createCallEndAction(),
+      };
+    }
+
+    // Idle, single target: a plain button (`call_start` resolves the default).
+    if (targets.length === 1) {
+      return {
+        icon: 'mdi:phone',
+        title: localize('config.live.controls.call.start'),
+        ...config.menu.buttons.call,
+        type: 'custom:advanced-camera-card-menu-icon',
+        tap_action: createCallStartAction(),
+      };
+    }
+
+    // Idle, multiple targets: a submenu, one entry per stream.
+    const menuItems = targets.map((streamID) => {
+      const metadata = cameraManager.getCameraMetadata(streamID) ?? undefined;
+      return {
+        enabled: true,
+        icon: metadata?.icon.icon,
+        entity: metadata?.icon.entity,
+        state_color: true,
+        title: metadata?.title,
+        tap_action: createCallStartAction(
+          cameraID,
+          streamID === cameraID ? undefined : streamID,
+        ),
+      };
+    });
+
+    return {
+      icon: 'mdi:phone',
+      title: localize('config.live.controls.call.start'),
+      ...config.menu.buttons.call,
+      type: 'custom:advanced-camera-card-menu-submenu',
+      items: menuItems,
+    };
+  }
+
   private _getMicrophoneButton(
     config: AdvancedCameraCardConfig,
     cameraManager: CameraManager,
     view?: View | null,
     microphoneManager?: MicrophoneManager | null,
+    callManager?: CallManager | null,
   ): MenuItem | null {
     const streamCameraID = view ? getStreamCameraID(view) : null;
     if (!streamCameraID) {
       return null;
     }
 
+    // The microphone only transmits during an active call.
+    if (!callManager?.isActive()) {
+      return null;
+    }
+
     const capabilities = cameraManager.getCameraCapabilities(streamCameraID);
 
     if (microphoneManager && capabilities?.has('2-way-audio')) {

src/components-lib/menu-controller.ts

@@ -10,6 +10,7 @@ import type { MenuConfig } from '../config/schema/menu.js';
 import type { Interaction } from '../types.js';
 import { getActionConfigGivenAction } from '../utils/action';
 import { arrayify, isTruthy, setOrRemoveAttribute } from '../utils/basic.js';
+import { AutoHideState, isAutoHidden as evaluateAutoHidden } from './auto-hide.js';
 
 export class MenuController {
   private _host: LitElement;
@@ -17,6 +18,7 @@ export class MenuController {
   private _buttons: MenuItem[] = [];
   private _expanded = false;
   private _lockManagerEpoch?: LockManagerEpoch;
+  private _autoHideState: AutoHideState | null = null;
 
   constructor(host: LitElement) {
     this._host = host;
@@ -74,6 +76,21 @@ export class MenuController {
     return this._config;
   }
 
+  public setAutoHideState(state: AutoHideState): void {
+    this._autoHideState = state;
+    this._host.requestUpdate();
+  }
+
+  public shouldRender(): boolean {
+    if (!this._config || this._config.style === 'none') {
+      return false;
+    }
+    return !(
+      this._autoHideState &&
+      evaluateAutoHidden(this._config.auto_hide, this._autoHideState)
+    );
+  }
+
   public isExpanded(): boolean {
     return this._expanded;
   }

src/components-lib/status-bar-controller.ts

@@ -7,6 +7,7 @@ import { StatusBarConfig } from '../config/schema/status-bar';
 import { getActionConfigGivenAction } from '../utils/action';
 import { arrayify, setOrRemoveAttribute } from '../utils/basic';
 import { Timer } from '../utils/timer';
+import { AutoHideState, isAutoHidden as evaluateAutoHidden } from './auto-hide';
 
 export class StatusBarController {
   private _host: LitElement;
@@ -14,6 +15,7 @@ export class StatusBarController {
 
   private _popupTimer = new Timer();
   private _items: StatusBarItem[] = [];
+  private _autoHideState: AutoHideState | null = null;
 
   constructor(host: LitElement) {
     this._host = host;
@@ -80,7 +82,19 @@ export class StatusBarController {
     return this._config;
   }
 
+  public setAutoHideState(state: AutoHideState): void {
+    this._autoHideState = state;
+    this._host.requestUpdate();
+  }
+
   public shouldRender(): boolean {
+    if (
+      this._config &&
+      this._autoHideState &&
+      evaluateAutoHidden(this._config.auto_hide, this._autoHideState)
+    ) {
+      return false;
+    }
     return this._items.some(
       (item) => item.enabled !== false && (item.sufficient || item.permanent),
     );