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/config/management.ts

@@ -791,6 +791,42 @@ const frigateCardToAdvancedCameraCardTransform = (
   return modified;
 };
 
+/**
+ * Migrate a `condition: microphone` condition with the (removed) `connected`
+ * field into a `condition: call` node. Operates on a single condition object in
+ * place. When both `connected` and `muted` are present, splits into a
+ * two-condition `and` (the only way to preserve both semantics now that
+ * `connected` no longer lives on `microphone`).
+ *
+ * @returns `true` if the node was modified.
+ */
+const microphoneConnectedToCallTransform = (data: unknown): boolean => {
+  if (typeof data !== 'object' || !data || data['condition'] !== 'microphone') {
+    return false;
+  }
+  const connected = data['connected'];
+  if (typeof connected !== 'boolean') {
+    return false;
+  }
+  const muted = data['muted'];
+
+  for (const key of Object.keys(data)) {
+    delete data[key];
+  }
+
+  if (typeof muted === 'boolean') {
+    data['condition'] = 'and';
+    data['conditions'] = [
+      { condition: 'call', call: connected },
+      { condition: 'microphone', muted: muted },
+    ];
+  } else {
+    data['condition'] = 'call';
+    data['call'] = connected;
+  }
+  return true;
+};
+
 const frigateCardToAdvancedCameraCardStyleTransform = (data: unknown): unknown => {
   if (typeof data !== 'object' || !data || Array.isArray(data)) {
     return data;
@@ -999,4 +1035,20 @@ const UPGRADES = [
     CONF_CAMERAS,
     upgradeWithOverrides('ptz', ptzIncorrectDataToWebRTCDataTransform),
   ),
+
+  // microphone.connected → call condition migration. Conditions live under
+  // overrides, elements, and automations.
+  upgradeArrayOfObjects(CONF_OVERRIDES, (override) =>
+    upgradeObjectRecursively(microphoneConnectedToCallTransform)(override),
+  ),
+  (data: unknown): boolean => {
+    return upgradeObjectRecursively(microphoneConnectedToCallTransform)(
+      typeof data === 'object' && data ? data[CONF_ELEMENTS] : {},
+    );
+  },
+  (data: unknown): boolean => {
+    return upgradeObjectRecursively(microphoneConnectedToCallTransform)(
+      typeof data === 'object' && data ? data[CONF_AUTOMATIONS] : {},
+    );
+  },
 ];

src/config/profiles/casting.ts

@@ -10,18 +10,16 @@ import {
   CONF_MENU_BUTTONS_MEDIA_PLAYER,
   CONF_MENU_BUTTONS_MUTE,
   CONF_MENU_BUTTONS_PLAY,
-  CONF_MENU_STYLE,
 } from '../../const.js';
 
 export const CASTING_PROFILE = {
   [CONF_LIVE_CONTROLS_BUILTIN]: false,
   [CONF_MEDIA_VIEWER_CONTROLS_BUILTIN]: false,
 
-  // TVs are generally not touch-enabled, so we don't want to show the menu
-  [CONF_MENU_STYLE]: 'none',
-
-  // But in case the user enables the menu, let's make sure to enable the
-  // buttons that make sense and disable the ones that don't
+  // TVs are generally not touch-enabled, so the menu auto-hides while casting
+  // (the `casting` default in `menu.auto_hide`). Should it nonetheless be
+  // shown, make sure the buttons that make sense are enabled and the ones that
+  // don't are disabled.
   [`${CONF_MENU_BUTTONS_PLAY}.enabled`]: true,
   [`${CONF_MENU_BUTTONS_MUTE}.enabled`]: true,
   [`${CONF_MENU_BUTTONS_FULLSCREEN}.enabled`]: false,

src/config/schema/actions/custom/call-end.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { advancedCameraCardCustomActionsBaseSchema } from './base';
+
+export const callEndActionConfigSchema =
+  advancedCameraCardCustomActionsBaseSchema.extend({
+    advanced_camera_card_action: z.literal('call_end'),
+  });
+export type CallEndActionConfig = z.infer<typeof callEndActionConfigSchema>;

src/config/schema/actions/custom/call-start.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { advancedCameraCardCustomActionsBaseSchema } from './base';
+
+export const callStartActionConfigSchema =
+  advancedCameraCardCustomActionsBaseSchema.extend({
+    advanced_camera_card_action: z.literal('call_start'),
+
+    // The camera to start the call on. Defaults to the selected camera.
+    camera: z.string().optional(),
+
+    // The 2-way-audio stream to carry the call: Could be `camera` itself, or
+    // one of its 2-way-audio dependencies. Defaults to the first eligible.
+    stream: z.string().optional(),
+  });
+export type CallStartActionConfig = z.infer<typeof callStartActionConfigSchema>;

src/config/schema/actions/types.ts

@@ -3,6 +3,8 @@ import { linkSchema } from '../common/link';
 import { severitySchema } from '../common/severity';
 import { statusBarItemBaseSchema } from '../common/status-bar';
 import { advancedCameraCardCustomActionsBaseSchema } from './custom/base';
+import { callEndActionConfigSchema } from './custom/call-end';
+import { callStartActionConfigSchema } from './custom/call-start';
 import { cameraSelectActionConfigSchema } from './custom/camera-select';
 import { viewDisplayModeActionConfigSchema } from './custom/display-mode';
 import { effectActionConfigSchema } from './custom/effect';
@@ -58,6 +60,8 @@ export const statusBarActionConfigSchema: z.ZodSchema<StatusBarActionConfig> =
   });
 
 const advancedCameraCardCustomActionSchema = z.union([
+  callEndActionConfigSchema,
+  callStartActionConfigSchema,
   cameraSelectActionConfigSchema,
   effectActionConfigSchema,
   generalActionConfigSchema,

src/config/schema/common/auto-hide.ts

@@ -0,0 +1,4 @@
+// Conditions under which the menu or status bar auto-hides.
+export const AUTO_HIDE_CONDITIONS = ['call', 'casting'] as const;
+
+export type AutoHideCondition = (typeof AUTO_HIDE_CONDITIONS)[number];

src/config/schema/common/controls/next-previous.ts

@@ -1,7 +1,9 @@
 import { z } from 'zod';
+import { AUTO_HIDE_CONDITIONS } from '../auto-hide';
 import { BUTTON_SIZE_MIN } from '../const';
 
 export const nextPreviousControlConfigSchema = z.object({
+  auto_hide: z.enum(AUTO_HIDE_CONDITIONS).array(),
   style: z.enum(['none', 'chevrons', 'icons', 'thumbnails']),
   size: z.number().min(BUTTON_SIZE_MIN),
 });

src/config/schema/common/media-actions.ts

@@ -4,15 +4,24 @@ export const MEDIA_ACTION_NEGATIVE_CONDITIONS = ['unselected', 'hidden'] as cons
 export const MEDIA_MUTE_CONDITIONS = [
   ...MEDIA_ACTION_NEGATIVE_CONDITIONS,
   'microphone',
+  'call',
 ] as const;
 
 export const MEDIA_UNMUTE_CONDITIONS = [
   ...MEDIA_ACTION_POSITIVE_CONDITIONS,
   'microphone',
+  'call',
 ] as const;
 
-export const MICROPHONE_MUTE_CONDITIONS = MEDIA_ACTION_NEGATIVE_CONDITIONS;
-export const MICROPHONE_UNMUTE_CONDITIONS = MEDIA_ACTION_POSITIVE_CONDITIONS;
+export const MICROPHONE_MUTE_CONDITIONS = [
+  ...MEDIA_ACTION_NEGATIVE_CONDITIONS,
+  'call',
+] as const;
+
+export const MICROPHONE_UNMUTE_CONDITIONS = [
+  ...MEDIA_ACTION_POSITIVE_CONDITIONS,
+  'call',
+] as const;
 
 export type AutoPlayCondition = (typeof MEDIA_ACTION_POSITIVE_CONDITIONS)[number];
 export type AutoPauseCondition = (typeof MEDIA_ACTION_NEGATIVE_CONDITIONS)[number];

src/config/schema/conditions/custom/call.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+
+export const callConditionSchema = z.object({
+  condition: z.literal('call'),
+  call: z.boolean().optional(),
+});

src/config/schema/conditions/custom/microphone.ts

@@ -2,6 +2,5 @@ import { z } from 'zod';
 
 export const microphoneConditionSchema = z.object({
   condition: z.literal('microphone'),
-  connected: z.boolean().optional(),
-  muted: z.boolean().optional(),
+  muted: z.boolean(),
 });

src/config/schema/conditions/types.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { callConditionSchema } from './custom/call';
 import { cameraConditionSchema } from './custom/camera';
 import { configConditionSchema } from './custom/config';
 import { displayModeConditionSchema } from './custom/display-mode';
@@ -69,6 +70,7 @@ export const advancedCameraCardConditionSchema = z.union([
   templateConditionSchema,
 
   // Custom conditions:
+  callConditionSchema,
   cameraConditionSchema,
   configConditionSchema,
   displayModeConditionSchema,

src/config/schema/live.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { actionsSchema } from './actions/types';
+import { BUTTON_SIZE_MIN } from './common/const';
 import { nextPreviousControlConfigSchema } from './common/controls/next-previous';
 import { ptzControlsConfigSchema, ptzControlsDefaults } from './common/controls/ptz';
 import {
@@ -23,23 +24,37 @@ import { transitionEffectConfigSchema } from './common/transition-effect';
 
 const microphoneConfigDefault = {
   always_connected: false,
-  auto_mute: [],
+  auto_mute: ['call' as const],
   auto_unmute: [],
   disconnect_seconds: 90,
-  lock: true,
   mute_after_microphone_mute_seconds: 60,
 };
 
+const callConfigDefault = {
+  button_size: 40,
+  lock: true,
+};
+
+const callConfigSchema = z.object({
+  button_size: z.number().min(BUTTON_SIZE_MIN).default(callConfigDefault.button_size),
+  lock: z.boolean().default(callConfigDefault.lock),
+});
+
 const microphoneConfigSchema = z
   .object({
     always_connected: z.boolean().default(microphoneConfigDefault.always_connected),
-    auto_mute: z.enum(MICROPHONE_MUTE_CONDITIONS).array().default([]),
-    auto_unmute: z.enum(MICROPHONE_UNMUTE_CONDITIONS).array().default([]),
+    auto_mute: z
+      .enum(MICROPHONE_MUTE_CONDITIONS)
+      .array()
+      .default(microphoneConfigDefault.auto_mute),
+    auto_unmute: z
+      .enum(MICROPHONE_UNMUTE_CONDITIONS)
+      .array()
+      .default(microphoneConfigDefault.auto_unmute),
     disconnect_seconds: z
       .number()
       .min(0)
       .default(microphoneConfigDefault.disconnect_seconds),
-    lock: z.boolean().default(microphoneConfigDefault.lock),
     mute_after_microphone_mute_seconds: z
       .number()
       .min(0)
@@ -52,7 +67,7 @@ export const liveConfigDefault = {
   auto_play: [...MEDIA_ACTION_POSITIVE_CONDITIONS],
   auto_pause: [],
   auto_mute: [...MEDIA_MUTE_CONDITIONS],
-  auto_unmute: ['microphone' as const],
+  auto_unmute: ['microphone' as const, 'call' as const],
   preload: false,
   lazy_load: true,
   lazy_unload: [],
@@ -62,7 +77,9 @@ export const liveConfigDefault = {
   show_image_during_load: true,
   controls: {
     builtin: true,
+    call: { ...callConfigDefault },
     next_previous: {
+      auto_hide: ['call' as const, 'casting' as const],
       size: 48,
       style: 'chevrons' as const,
     },
@@ -97,8 +114,12 @@ export const liveConfigSchema = z
     controls: z
       .object({
         builtin: z.boolean().default(liveConfigDefault.controls.builtin),
+        call: callConfigSchema.default(liveConfigDefault.controls.call),
         next_previous: nextPreviousControlConfigSchema
           .extend({
+            auto_hide: nextPreviousControlConfigSchema.shape.auto_hide.default(
+              liveConfigDefault.controls.next_previous.auto_hide,
+            ),
             // Live cannot show thumbnails, remove that option.
             style: z
               .enum(['none', 'chevrons', 'icons'])

src/config/schema/menu.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { AUTO_HIDE_CONDITIONS } from './common/auto-hide';
 import { BUTTON_SIZE_MIN, MENU_PRIORITY_DEFAULT } from './common/const';
 import { menuBaseSchema } from './elements/custom/menu/base';
 
@@ -32,10 +33,12 @@ const hiddenButtonDefault = {
 
 export const menuConfigDefault = {
   alignment: 'left' as const,
+  auto_hide: ['call' as const, 'casting' as const],
   button_size: 40,
   buttons: {
     // Clone per key so each button has its own default object. This avoids
     // shared nested default references between keys.
+    call: { ...visibleButtonDefault },
     camera_ui: { ...visibleButtonDefault },
     cameras: { ...visibleButtonDefault },
     clips: { ...hiddenButtonDefault },
@@ -86,8 +89,10 @@ export const menuConfigSchema = z
     style: z.enum(MENU_STYLES).default(menuConfigDefault.style),
     position: z.enum(MENU_POSITIONS).default(menuConfigDefault.position),
     alignment: z.enum(MENU_ALIGNMENTS).default(menuConfigDefault.alignment),
+    auto_hide: z.enum(AUTO_HIDE_CONDITIONS).array().default(menuConfigDefault.auto_hide),
     buttons: z
       .object({
+        call: visibleButtonSchema.default(menuConfigDefault.buttons.call),
         camera_ui: visibleButtonSchema.default(menuConfigDefault.buttons.camera_ui),
         cameras: visibleButtonSchema.default(menuConfigDefault.buttons.cameras),
         clips: hiddenButtonSchema.default(menuConfigDefault.buttons.clips),

src/config/schema/status-bar.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { AUTO_HIDE_CONDITIONS } from './common/auto-hide';
 import { BUTTON_SIZE_MIN, STATUS_BAR_PRIORITY_DEFAULT } from './common/const';
 import { statusBarItemBaseSchema } from './common/status-bar';
 
@@ -36,6 +37,7 @@ const statusBarIssuesItemSchema = statusBarItemBaseSchema.extend({
 });
 
 export const statusBarConfigDefault = {
+  auto_hide: ['call' as const, 'casting' as const],
   height: 40,
   items: {
     engine: statusBarItemDefault,
@@ -52,6 +54,10 @@ export const statusBarConfigDefault = {
 
 export const statusBarConfigSchema = z
   .object({
+    auto_hide: z
+      .enum(AUTO_HIDE_CONDITIONS)
+      .array()
+      .default(statusBarConfigDefault.auto_hide),
     position: z.enum(STATUS_BAR_POSITIONS).default(statusBarConfigDefault.position),
     style: z.enum(STATUS_BAR_STYLES).default(statusBarConfigDefault.style),
     popup_seconds: z

src/config/schema/viewer.ts

@@ -30,6 +30,7 @@ export const viewerConfigDefault = {
   controls: {
     builtin: true,
     next_previous: {
+      auto_hide: ['casting' as const],
       size: 48,
       style: 'thumbnails' as const,
     },
@@ -44,6 +45,12 @@ export const viewerConfigDefault = {
 };
 
 const viewerNextPreviousControlConfigSchema = nextPreviousControlConfigSchema.extend({
+  // Calls only occur in the live view, so `call` is dropped from the common
+  // enum.
+  auto_hide: z
+    .enum(['casting'])
+    .array()
+    .default(viewerConfigDefault.controls.next_previous.auto_hide),
   style: z
     .enum(['none', 'thumbnails', 'chevrons'])
     .default(viewerConfigDefault.controls.next_previous.style),