@oshara/voice-sdk 0.1.0

package/src/core/appearance.ts

@@ -0,0 +1,464 @@
+import {
+  DEFAULT_FORM_DEFINITIONS,
+  FormDefinition,
+  normalizeFormDefinitions,
+} from "./forms";
+
+/**
+ * Per-agent widget appearance configuration.
+ *
+ * The widget fetches this from `GET {apiUrl}/api/agents/{slug}/appearance/`
+ * (override with `data-appearance-url`) on init, falling back to the defaults
+ * below if the request fails or any field is missing.
+ *
+ * Every field is optional on the wire — partial responses are merged on top of
+ * the defaults so the widget never breaks if the backend hasn't been updated.
+ */
+
+export type WidgetPosition =
+  | "bottom-right"
+  | "bottom-left"
+  | "top-right"
+  | "top-left";
+
+export interface AppearanceTheme {
+  primary_color: string;
+  accent_color: string;
+  background_color: string;
+  text_color: string;
+  user_bubble_color: string;
+  user_bubble_text_color: string;
+  agent_bubble_color: string;
+  agent_bubble_text_color: string;
+}
+
+export interface AppearanceDimensions {
+  fab_size: number;
+  panel_width: number;
+  panel_height: number;
+  border_radius: number;
+}
+
+export interface AppearanceLayout {
+  position: WidgetPosition;
+  font_family: string;
+}
+
+export interface AppearanceLabels {
+  idle: string;
+  connecting: string;
+  listening: string;
+  speaking: string;
+  /** Shown while the agent is processing (running STT→LLM→tool→TTS). The
+   *  backend may override this with a per-tool contextual label
+   *  ("Searching the knowledge base…") via voice.agent_status events. */
+  thinking: string;
+  muted: string;
+  call_ended: string;
+  transcript_placeholder: string;
+  language_label: string;
+}
+
+export interface AppearanceLanguage {
+  /** BCP-47-ish short code sent to the backend (e.g. "en", "ne"). */
+  code: string;
+  /** English label, e.g. "English", "Nepali". */
+  label: string;
+  /** Native script label, e.g. "English", "नेपाली". Falls back to label. */
+  native_label: string;
+}
+
+export interface AppearanceConfig {
+  name: string;
+  subtitle: string;
+  logo_url: string;
+  fab_label: string;
+  fab_sublabel: string;
+  start_button_text: string;
+  powered_by_text: string;
+  powered_by_url: string;
+  theme: AppearanceTheme;
+  dimensions: AppearanceDimensions;
+  layout: AppearanceLayout;
+  labels: AppearanceLabels;
+  languages: AppearanceLanguage[];
+  default_language: string;
+  /** Hard cap on a single voice call, in seconds. 0 = no limit. */
+  max_call_seconds: number;
+  /** URL to the terms & conditions / privacy policy page. When set, a
+   *  consent line is shown beneath the Start button stating that starting
+   *  the call accepts these terms. Empty disables the consent UI. */
+  terms_url: string;
+  /** Visible label for the terms link (default "Terms & Conditions"). */
+  terms_label: string;
+  /** Prefix shown before the terms link (default
+   *  "By starting the call, you agree to our"). */
+  consent_text: string;
+  /**
+   * Extra form definitions (book-a-demo, reservation, lead capture, …) the
+   * agent can open mid-call by publishing a LiveKit data message. Built-in
+   * defaults are always available; entries here override defaults by id.
+   * See `forms.ts` for the wire protocol.
+   */
+  forms: FormDefinition[];
+  /**
+   * Whether to expose the in-widget audio settings drawer (mic/speaker
+   * selection, NC/AEC/AGC toggles, headphone mode, mic-level meter,
+   * diagnostics row). Defaults to true. Set false to hide the gear icon
+   * entirely for a kiosk-style minimal UI.
+   */
+  show_audio_settings: boolean;
+}
+
+export const DEFAULT_APPEARANCE: AppearanceConfig = {
+  name: "Voice Assistant",
+  subtitle: "Tap below to start a voice conversation.",
+  logo_url: "",
+  // Empty by default — only show FAB text when the backend explicitly
+  // configures fab_label/fab_sublabel. Otherwise the FAB is icon-only.
+  fab_label: "",
+  fab_sublabel: "",
+  start_button_text: "Start Call",
+  powered_by_text: "Powered by Oshara.ai",
+  powered_by_url: "",
+  theme: {
+    primary_color: "#6366F1",
+    accent_color: "#22D3EE",
+    background_color: "#FFFFFF",
+    text_color: "#0F172A",
+    user_bubble_color: "#6366F1",
+    user_bubble_text_color: "#FFFFFF",
+    agent_bubble_color: "#F1F5F9",
+    agent_bubble_text_color: "#0F172A",
+  },
+  dimensions: {
+    fab_size: 64,
+    panel_width: 380,
+    panel_height: 620,
+    border_radius: 24,
+  },
+  layout: {
+    position: "bottom-right",
+    font_family:
+      "Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+  },
+  labels: {
+    idle: "Idle",
+    connecting: "Connecting…",
+    listening: "Listening",
+    speaking: "Speaking…",
+    thinking: "Thinking…",
+    muted: "Microphone muted",
+    call_ended: "Call ended",
+    transcript_placeholder: "Your live transcript will appear here",
+    language_label: "Language",
+  },
+  languages: [
+    { code: "en", label: "English", native_label: "English" },
+    { code: "ne", label: "Nepali", native_label: "नेपाली" },
+  ],
+  default_language: "en",
+  max_call_seconds: 0,
+  terms_url: "",
+  terms_label: "Terms & Conditions",
+  consent_text: "By starting the call, you agree to our",
+  forms: DEFAULT_FORM_DEFINITIONS,
+  show_audio_settings: true,
+};
+
+const POSITIONS: WidgetPosition[] = [
+  "bottom-right",
+  "bottom-left",
+  "top-right",
+  "top-left",
+];
+
+/**
+ * Deep-merge a partial server response on top of DEFAULT_APPEARANCE.
+ * Only known keys are accepted; unknown keys are ignored.
+ */
+export function mergeAppearance(
+  partial: Partial<AppearanceConfig> | null | undefined,
+): AppearanceConfig {
+  if (!partial || typeof partial !== "object") return DEFAULT_APPEARANCE;
+  const safe = asRecord(partial);
+  const theme = asRecord(safe.theme);
+  const dimensions = asRecord(safe.dimensions);
+  const layout = asRecord(safe.layout);
+  const labels = asRecord(safe.labels);
+
+  return {
+    name: nonEmptyString(safe.name) ?? DEFAULT_APPEARANCE.name,
+    subtitle: stringOrDefault(safe.subtitle, DEFAULT_APPEARANCE.subtitle),
+    logo_url: stringOrDefault(safe.logo_url, DEFAULT_APPEARANCE.logo_url),
+    fab_label: stringOrDefault(safe.fab_label, DEFAULT_APPEARANCE.fab_label),
+    fab_sublabel: stringOrDefault(
+      safe.fab_sublabel,
+      DEFAULT_APPEARANCE.fab_sublabel,
+    ),
+    start_button_text:
+      nonEmptyString(safe.start_button_text) ??
+      DEFAULT_APPEARANCE.start_button_text,
+    powered_by_text: stringOrDefault(
+      safe.powered_by_text,
+      DEFAULT_APPEARANCE.powered_by_text,
+    ),
+    powered_by_url: stringOrDefault(
+      safe.powered_by_url,
+      DEFAULT_APPEARANCE.powered_by_url,
+    ),
+    theme: {
+      primary_color:
+        nonEmptyString(theme.primary_color) ??
+        DEFAULT_APPEARANCE.theme.primary_color,
+      accent_color:
+        nonEmptyString(theme.accent_color) ??
+        DEFAULT_APPEARANCE.theme.accent_color,
+      background_color:
+        nonEmptyString(theme.background_color) ??
+        DEFAULT_APPEARANCE.theme.background_color,
+      text_color:
+        nonEmptyString(theme.text_color) ?? DEFAULT_APPEARANCE.theme.text_color,
+      user_bubble_color:
+        nonEmptyString(theme.user_bubble_color) ??
+        DEFAULT_APPEARANCE.theme.user_bubble_color,
+      user_bubble_text_color:
+        nonEmptyString(theme.user_bubble_text_color) ??
+        DEFAULT_APPEARANCE.theme.user_bubble_text_color,
+      agent_bubble_color:
+        nonEmptyString(theme.agent_bubble_color) ??
+        DEFAULT_APPEARANCE.theme.agent_bubble_color,
+      agent_bubble_text_color:
+        nonEmptyString(theme.agent_bubble_text_color) ??
+        DEFAULT_APPEARANCE.theme.agent_bubble_text_color,
+    },
+    dimensions: {
+      fab_size:
+        pixelOrNumber(dimensions.fab_size) ??
+        DEFAULT_APPEARANCE.dimensions.fab_size,
+      panel_width:
+        pixelOrNumber(dimensions.panel_width) ??
+        DEFAULT_APPEARANCE.dimensions.panel_width,
+      panel_height:
+        pixelOrNumber(dimensions.panel_height) ??
+        DEFAULT_APPEARANCE.dimensions.panel_height,
+      border_radius:
+        pixelOrNumber(dimensions.border_radius) ??
+        DEFAULT_APPEARANCE.dimensions.border_radius,
+    },
+    layout: {
+      position:
+        enumOrUndefined(POSITIONS, layout.position) ??
+        DEFAULT_APPEARANCE.layout.position,
+      font_family: stringOrDefault(
+        layout.font_family,
+        DEFAULT_APPEARANCE.layout.font_family,
+      ),
+    },
+    labels: {
+      idle: nonEmptyString(labels.idle) ?? DEFAULT_APPEARANCE.labels.idle,
+      connecting:
+        nonEmptyString(labels.connecting) ??
+        DEFAULT_APPEARANCE.labels.connecting,
+      listening:
+        nonEmptyString(labels.listening) ?? DEFAULT_APPEARANCE.labels.listening,
+      speaking:
+        nonEmptyString(labels.speaking) ?? DEFAULT_APPEARANCE.labels.speaking,
+      thinking:
+        nonEmptyString(labels.thinking) ?? DEFAULT_APPEARANCE.labels.thinking,
+      muted: nonEmptyString(labels.muted) ?? DEFAULT_APPEARANCE.labels.muted,
+      call_ended:
+        nonEmptyString(labels.call_ended) ??
+        DEFAULT_APPEARANCE.labels.call_ended,
+      transcript_placeholder: stringOrDefault(
+        labels.transcript_placeholder,
+        DEFAULT_APPEARANCE.labels.transcript_placeholder,
+      ),
+      language_label:
+        nonEmptyString(labels.language_label) ??
+        DEFAULT_APPEARANCE.labels.language_label,
+    },
+    languages: normalizeLanguages(safe.languages),
+    default_language:
+      nonEmptyString(safe.default_language) ??
+      DEFAULT_APPEARANCE.default_language,
+    max_call_seconds:
+      nonNegativeNumber(safe.max_call_seconds) ??
+      DEFAULT_APPEARANCE.max_call_seconds,
+    terms_url: stringOrDefault(safe.terms_url, DEFAULT_APPEARANCE.terms_url),
+    terms_label:
+      nonEmptyString(safe.terms_label) ?? DEFAULT_APPEARANCE.terms_label,
+    consent_text: stringOrDefault(
+      safe.consent_text,
+      DEFAULT_APPEARANCE.consent_text,
+    ),
+    forms: mergeForms(safe.forms),
+    show_audio_settings:
+      typeof safe.show_audio_settings === "boolean"
+        ? safe.show_audio_settings
+        : DEFAULT_APPEARANCE.show_audio_settings,
+  };
+}
+
+function mergeForms(value: unknown): FormDefinition[] {
+  const custom = normalizeFormDefinitions(value);
+  const map = new Map<string, FormDefinition>();
+  for (const f of DEFAULT_FORM_DEFINITIONS) map.set(f.id, f);
+  for (const f of custom) map.set(f.id, f);
+  return Array.from(map.values());
+}
+
+function normalizeLanguages(value: unknown): AppearanceLanguage[] {
+  if (!Array.isArray(value)) return DEFAULT_APPEARANCE.languages;
+  const seen = new Set<string>();
+  const out: AppearanceLanguage[] = [];
+  for (const raw of value) {
+    if (!isPlainObject(raw)) continue;
+    const code = nonEmptyString(raw.code);
+    if (!code || seen.has(code)) continue;
+    const label = nonEmptyString(raw.label) ?? code.toUpperCase();
+    const native = nonEmptyString(raw.native_label) ?? label;
+    seen.add(code);
+    out.push({ code, label, native_label: native });
+  }
+  return out.length ? out : DEFAULT_APPEARANCE.languages;
+}
+
+export interface FetchAppearanceArgs {
+  /** Resolved URL (already substituted) — takes precedence when present. */
+  appearanceUrl: string;
+  /** Falls back to `${apiUrl}/api/agents/${slug}/appearance/`. */
+  apiUrl: string;
+  slug: string;
+  /** Secret key sent as `x-api-key` (server/trusted mode). */
+  apiKey?: string;
+  /** Custom fetch (Node <18 / testing). Defaults to globalThis.fetch. */
+  fetch?: typeof fetch;
+}
+
+export async function fetchAppearance(
+  args: FetchAppearanceArgs,
+): Promise<AppearanceConfig> {
+  const url =
+    args.appearanceUrl ||
+    `${args.apiUrl.replace(/\/$/, "")}/api/agents/${encodeURIComponent(
+      args.slug,
+    )}/appearance/`;
+
+  const headers: Record<string, string> = { Accept: "application/json" };
+  if (args.apiKey?.trim()) headers["x-api-key"] = args.apiKey.trim();
+  const doFetch =
+    args.fetch ??
+    (typeof globalThis.fetch === "function"
+      ? globalThis.fetch.bind(globalThis)
+      : null);
+  if (!doFetch) {
+    // eslint-disable-next-line no-console
+    console.warn("[voice-agent] no fetch available; using default appearance");
+    return DEFAULT_APPEARANCE;
+  }
+
+  // eslint-disable-next-line no-console
+  console.info("[voice-agent] fetching appearance from", url);
+
+  try {
+    const r = await doFetch(url, { method: "GET", headers });
+    if (!r.ok) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[voice-agent] appearance fetch returned ${r.status}; using defaults`,
+      );
+      return DEFAULT_APPEARANCE;
+    }
+    const body: any = await r.json();
+    // eslint-disable-next-line no-console
+    console.info("[voice-agent] appearance response", body);
+    const payload = unwrapAppearanceResponse(body);
+    const merged = mergeAppearance(payload);
+    // eslint-disable-next-line no-console
+    console.info("[voice-agent] applied appearance", merged);
+    return merged;
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn("[voice-agent] appearance fetch failed; using defaults:", err);
+    return DEFAULT_APPEARANCE;
+  }
+}
+
+function unwrapAppearanceResponse(
+  body: unknown,
+): Partial<AppearanceConfig> | null {
+  if (!isPlainObject(body)) return null;
+  const safe = body as Record<string, unknown>;
+
+  const candidates: unknown[] = [
+    safe.data,
+    safe.appearance,
+    safe.widget_appearance,
+    safe,
+  ];
+  for (const candidate of candidates) {
+    if (isPlainObject(candidate)) {
+      return candidate as Partial<AppearanceConfig>;
+    }
+  }
+  return null;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return isPlainObject(value) ? value : {};
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function stringOrDefault(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function finitePositiveNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? value
+    : undefined;
+}
+
+function nonNegativeNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) return undefined;
+    const parsed = Number(trimmed);
+    if (Number.isFinite(parsed) && parsed >= 0) return parsed;
+  }
+  return undefined;
+}
+
+function pixelOrNumber(value: unknown): number | undefined {
+  const direct = finitePositiveNumber(value);
+  if (direct !== undefined) return direct;
+  if (typeof value !== "string") return undefined;
+
+  const match = value.trim().match(/^(\d+(?:\.\d+)?)px$/i);
+  if (!match) return undefined;
+
+  const parsed = Number(match[1]);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function enumOrUndefined<T extends string>(
+  allowed: readonly T[],
+  value: unknown,
+): T | undefined {
+  return typeof value === "string" && allowed.includes(value as T)
+    ? (value as T)
+    : undefined;
+}

package/src/core/audioSettings.ts

@@ -0,0 +1,180 @@
+/**
+ * Per-agent audio preferences for the voice widget.
+ *
+ * Persists the user's chosen mic/speaker devices, processor toggles, and
+ * speaker volume so subsequent calls open with the same setup. Reads &
+ * writes are namespaced by agent slug so different agents can hold
+ * different preferences in the same browser.
+ */
+
+/**
+ * Choice of deep-learning noise-suppression engine layered on top of the
+ * browser's native NS. Picked per-user via the audio settings drawer.
+ *
+ * - `off`        — rely on browser NS + voiceIsolation only.
+ * - `krisp`      — @livekit/krisp-noise-filter (closed-source, free for LK).
+ * - `deepfilter` — deepfilternet3-noise-filter (mezonai/mezon-noise-suppression),
+ *                  open-source DeepFilterNet3 with a 0-100 strength knob.
+ */
+export type NoiseFilterEngine = "off" | "krisp" | "deepfilter";
+
+export interface AudioPrefs {
+  /** Browser-native AEC. Standard MediaTrackSettings.echoCancellation. */
+  echoCancellation: boolean;
+  /** Browser-native noise suppression. Standard MediaTrackSettings. */
+  noiseSuppression: boolean;
+  /** Browser-native automatic gain control. */
+  autoGainControl: boolean;
+  /** Microsoft / Chrome non-standard hardware voice isolation. */
+  voiceIsolation: boolean;
+  /** Which deep-learning noise-suppression processor to attach. */
+  noiseFilter: NoiseFilterEngine;
+  /** DeepFilterNet3 strength 0-100 (ignored unless noiseFilter === "deepfilter"). */
+  deepFilterStrength: number;
+  /** Selected mic deviceId (empty string = system default). */
+  micDeviceId: string;
+  /** Selected speaker deviceId for setSinkId (empty = default). */
+  speakerDeviceId: string;
+  /** Speaker volume 0-100, applied to HTMLAudioElement.volume / 100. */
+  outputVolume: number;
+  /**
+   * When true, disables half-duplex ducking. The user wears headphones so
+   * the mic can't physically pick up the speaker — no need to mute them
+   * while the agent talks.
+   */
+  headphonesMode: boolean;
+  /** Whether to show live transcription in the UI. */
+  transcriptionEnabled: boolean;
+  /** Whether to show the text input box during a call. */
+  textInputEnabled: boolean;
+}
+
+export const DEFAULT_AUDIO_PREFS: AudioPrefs = {
+  echoCancellation: true,
+  noiseSuppression: true,
+  // Off by default: AGC boosts the trailing tail of an utterance, which
+  // confuses the agent's contextual turn detector ("user is still
+  // talking softly") and delays preemptive LLM generation. Users can
+  // toggle this on per-call from the audio settings drawer if they're
+  // soft-spoken and the agent isn't hearing them.
+  autoGainControl: false,
+  voiceIsolation: true,
+  noiseFilter: "deepfilter",
+  deepFilterStrength: 40,
+  micDeviceId: "",
+  speakerDeviceId: "",
+  outputVolume: 85,
+  headphonesMode: true,
+  transcriptionEnabled: false,
+  textInputEnabled: false,
+};
+
+const STORAGE_PREFIX = "voice-agent:audio-prefs:";
+
+function storageKey(agentSlug: string): string {
+  return `${STORAGE_PREFIX}${agentSlug || "default"}`;
+}
+
+export function loadAudioPrefs(agentSlug: string): AudioPrefs {
+  try {
+    const raw = window.localStorage.getItem(storageKey(agentSlug));
+    if (!raw) return { ...DEFAULT_AUDIO_PREFS };
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return { ...DEFAULT_AUDIO_PREFS };
+    }
+    return { ...DEFAULT_AUDIO_PREFS, ...normalize(parsed) };
+  } catch {
+    return { ...DEFAULT_AUDIO_PREFS };
+  }
+}
+
+export function saveAudioPrefs(agentSlug: string, prefs: AudioPrefs): void {
+  try {
+    window.localStorage.setItem(
+      storageKey(agentSlug),
+      JSON.stringify(normalize(prefs as unknown as Record<string, unknown>)),
+    );
+  } catch {
+    // Storage may be disabled (private mode, quota); preferences just
+    // won't survive a reload. Not worth surfacing to the user.
+  }
+}
+
+function normalize(input: Record<string, unknown>): Partial<AudioPrefs> {
+  const out: Partial<AudioPrefs> = {};
+  if (typeof input.echoCancellation === "boolean") out.echoCancellation = input.echoCancellation;
+  if (typeof input.noiseSuppression === "boolean") out.noiseSuppression = input.noiseSuppression;
+  if (typeof input.autoGainControl === "boolean") out.autoGainControl = input.autoGainControl;
+  if (typeof input.voiceIsolation === "boolean") out.voiceIsolation = input.voiceIsolation;
+  if (input.noiseFilter === "off" || input.noiseFilter === "krisp" || input.noiseFilter === "deepfilter") {
+    out.noiseFilter = input.noiseFilter;
+  } else if (typeof input.krispEnabled === "boolean") {
+    // Migration path from the pre-engine-picker AudioPrefs shape.
+    out.noiseFilter = input.krispEnabled ? "krisp" : "off";
+  }
+  if (typeof input.deepFilterStrength === "number" && Number.isFinite(input.deepFilterStrength)) {
+    out.deepFilterStrength = Math.max(0, Math.min(100, input.deepFilterStrength));
+  }
+  if (typeof input.micDeviceId === "string") out.micDeviceId = input.micDeviceId;
+  if (typeof input.speakerDeviceId === "string") out.speakerDeviceId = input.speakerDeviceId;
+  if (typeof input.outputVolume === "number" && Number.isFinite(input.outputVolume)) {
+    out.outputVolume = Math.max(0, Math.min(100, input.outputVolume));
+  }
+  if (typeof input.headphonesMode === "boolean") out.headphonesMode = input.headphonesMode;
+  if (typeof input.transcriptionEnabled === "boolean") out.transcriptionEnabled = input.transcriptionEnabled;
+  if (typeof input.textInputEnabled === "boolean") out.textInputEnabled = input.textInputEnabled;
+  return out;
+}
+
+export interface AudioDevices {
+  inputs: MediaDeviceInfo[];
+  outputs: MediaDeviceInfo[];
+}
+
+/**
+ * Enumerate audio I/O devices. Device labels are only populated after the
+ * user has granted mic permission for the page; before that the labels
+ * come back empty and the caller should show a placeholder.
+ */
+export async function enumerateAudioDevices(): Promise<AudioDevices> {
+  if (!navigator.mediaDevices?.enumerateDevices) {
+    return { inputs: [], outputs: [] };
+  }
+  const devices = await navigator.mediaDevices.enumerateDevices();
+  const inputs = devices.filter((d) => d.kind === "audioinput");
+  const outputs = devices.filter((d) => d.kind === "audiooutput");
+  return { inputs, outputs };
+}
+
+/** Browser-feature probes used to decide which UI controls make sense. */
+export interface AudioCapabilities {
+  /** setSinkId is unsupported on Safari and Firefox at the time of writing. */
+  setSinkIdSupported: boolean;
+  /** voiceIsolation is honored on Chromium/Edge with system support only. */
+  voiceIsolationSupported: boolean;
+}
+
+export function probeAudioCapabilities(): AudioCapabilities {
+  const audioEl = typeof HTMLAudioElement !== "undefined"
+    ? HTMLAudioElement.prototype
+    : null;
+  const setSinkIdSupported = Boolean(
+    audioEl && typeof (audioEl as unknown as { setSinkId?: unknown }).setSinkId === "function",
+  );
+
+  // No reliable feature flag for voiceIsolation; the actual support comes
+  // out in MediaTrackSettings.getSettings() once the track is published.
+  // Best we can do up-front is gate on getSupportedConstraints().
+  let voiceIsolationSupported = false;
+  try {
+    const supported = navigator.mediaDevices?.getSupportedConstraints?.() as
+      | (MediaTrackSupportedConstraints & { voiceIsolation?: boolean })
+      | undefined;
+    voiceIsolationSupported = Boolean(supported?.voiceIsolation);
+  } catch {
+    voiceIsolationSupported = false;
+  }
+
+  return { setSinkIdSupported, voiceIsolationSupported };
+}