feat: support iOS 26 Speaker Selection API via shared WebAudio relay element

fkwp · fkwp · commit 2b09b51d1a1c · 2026-05-15T11:19:06.000+02:00
diff --git a/src/room/Room.ts b/src/room/Room.ts
@@ -103,17 +103,20 @@ import {
 import {
   Future,
   createDummyVideoStreamTrack,
+  disposeSharedRelay,
   extractChatMessage,
   extractTranscriptionSegments,
   getDisconnectReasonFromConnectionError,
   getEmptyAudioStreamTrack,
+  getOrCreateSharedRelay,
   isBrowserSupported,
   isCloud,
   isLocalAudioTrack,
   isLocalParticipant,
   isReactNative,
   isRemotePub,
   isSafariBased,
+  isSafariSpeakerSelectionSupported,
   isWeb,
   numberToBigInt,
   sleep,
@@ -1446,14 +1449,28 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       if (success && isMuted) shouldTriggerImmediateDeviceChange = true;
     } else if (kind === 'audiooutput') {
       shouldTriggerImmediateDeviceChange = true;
-      if (
-        (!supportsSetSinkId() && !this.options.webAudioMix) ||
-        (this.options.webAudioMix && this.audioContext && !('setSinkId' in this.audioContext))
-      ) {
+      // True when we can route output via AudioContext.setSinkId directly, e.g., 
+      //   Chrome / Edge / Firefox + webAudioMix : true  (use AudioContext.setSinkId)
+      //   Safari macOS (any version)            : false (AudioContext.setSinkId not implemented)
+      //   Safari iOS  (any version)             : false (AudioContext.setSinkId not implemented)
+      //   any browser without webAudioMix       : false
+      const audioContextHasSinkId =
+        this.options.webAudioMix && !!this.audioContext && 'setSinkId' in this.audioContext;
+      // True when we route output via the shared relay <audio> element (iOS 26 path).
+      //   iOS 26+ Safari + webAudioMix          : true
+      //   macOS Safari 26+ + webAudioMix        : true (also benefits from the relay approach)
+      //   anything else                         : false
+      const useSharedRelay = isSafariSpeakerSelectionSupported() && !!this.audioContext;
+      // Throw only when neither HTMLMediaElement.setSinkId nor AudioContext.setSinkId is usable.
+      // When webAudioMix=true but AudioContext.setSinkId is unavailable (e.g. iOS 26 Safari),
+      // we fall through and rely on the shared relay-element setSinkId path.
+      if (!supportsSetSinkId() && !audioContextHasSinkId) {
         throw new Error('cannot switch audio output, the current browser does not support it');
       }
-      if (this.options.webAudioMix) {
-        // setting `default` for web audio output doesn't work, so we need to normalize the id before
+      if (audioContextHasSinkId) {
+        // AudioContext.setSinkId (Chrome) doesn't accept 'default', so resolve to a real device id.
+        // On iOS 26 we use HTMLMediaElement.setSinkId on a relay element instead, which does
+        // accept 'default', so skip normalization there.
         deviceId =
           (await DeviceManager.getInstance().normalizeDeviceId('audiooutput', deviceId)) ?? '';
       }
@@ -1462,16 +1479,28 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       this.options.audioOutput.deviceId = deviceId;
 
       try {
-        if (this.options.webAudioMix) {
+        if (audioContextHasSinkId) {
           // @ts-expect-error setSinkId is not yet in the typescript type of AudioContext
           this.audioContext?.setSinkId(deviceId);
         }
 
-        // also set audio output on all audio elements, even if webAudioMix is enabled in order to workaround echo cancellation not working on chrome with non-default output devices
-        // see https://issues.chromium.org/issues/40252911#comment7
-        await Promise.all(
-          Array.from(this.remoteParticipants.values()).map((p) => p.setAudioOutput({ deviceId })),
-        );
+        if (useSharedRelay) {
+          // iOS 26 path: route via a single shared relay <audio> element on the AudioContext.
+          // Calling setSinkId here (within the user gesture) grants iOS permission for this
+          // element, which persists for the call — so new remote tracks joining later route
+          // through the already-permitted element without needing their own user gesture.
+          await (getOrCreateSharedRelay(this.audioContext!).relayElement.setSinkId(
+            deviceId,
+          ) as Promise<void>);
+        } else {
+          // Standard path for browsers with HTMLMediaElement.setSinkId (Chrome, Firefox, etc.):
+          // apply setSinkId on each participant's attached <audio> element directly.
+          // Note: Chrome with webAudioMix=true also needs this for echo cancellation with
+          // non-default output devices — see https://issues.chromium.org/issues/40252911#comment7
+          await Promise.all(
+            Array.from(this.remoteParticipants.values()).map((p) => p.setAudioOutput({ deviceId })),
+          );
+        }
       } catch (e) {
         this.options.audioOutput.deviceId = prevDeviceId;
         throw e;
@@ -1806,9 +1835,12 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       this.remoteParticipants.clear();
       this.sidToIdentity.clear();
       this.activeSpeakers = [];
-      if (this.audioContext && typeof this.options.webAudioMix === 'boolean') {
-        this.audioContext.close();
-        this.audioContext = undefined;
+      if (this.audioContext) {
+        disposeSharedRelay(this.audioContext);
+        if (typeof this.options.webAudioMix === 'boolean') {
+          this.audioContext.close();
+          this.audioContext = undefined;
+        }
       }
       if (isWeb()) {
         window.removeEventListener('beforeunload', this.onPageLeave);
@@ -2229,7 +2261,15 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         continue;
       }
       const devicesOfKind = availableDevices.filter((d) => d.kind === kind);
-      const activeDevice = this.getActiveDevice(kind);
+      // For audiooutput, also check options.audioOutput.deviceId as a fallback: switchActiveDevice
+      // sets that field before awaiting setSinkId, but only updates activeDeviceMap after the
+      // await resolves. If a devicechange handler fires inside that window before any audiooutput
+      // switch has been recorded, activeDeviceMap is empty and the fallback yields the in-flight
+      // selection rather than nothing.
+      const activeDevice =
+        kind === 'audiooutput'
+          ? (this.getActiveDevice(kind) ?? this.options.audioOutput?.deviceId)
+          : this.getActiveDevice(kind);
 
       if (activeDevice === previousDevices.filter((info) => info.kind === kind)[0]?.deviceId) {
         // in  Safari the first device is always the default, so we assume a user on the default device would like to switch to the default once it changes
@@ -2247,18 +2287,19 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       // switch to first available device if previously active device is not available any more
       if (
         devicesOfKind.length > 0 &&
-        !devicesOfKind.find((deviceInfo) => deviceInfo.deviceId === this.getActiveDevice(kind)) &&
+        !devicesOfKind.find((deviceInfo) => deviceInfo.deviceId === activeDevice) &&
         // avoid switching audio output on safari without explicit user action as it leads to slowed down audio playback
-        (kind !== 'audiooutput' || !isSafariBased())
+        // exception: iOS/Safari 26+ supports the Speaker Selection API
+        (kind !== 'audiooutput' || !isSafariBased() || isSafariSpeakerSelectionSupported())
       ) {
         await this.switchActiveDevice(kind, devicesOfKind[0].deviceId);
       }
     }
   }
 
   private handleDeviceChange = async () => {
-    if (getBrowser()?.os !== 'iOS') {
-      // default devices are non deterministic on iOS, so we don't attempt to select them here
+    if (getBrowser()?.os !== 'iOS' || isSafariSpeakerSelectionSupported()) {
+      // default devices are non deterministic on iOS (pre-26), so we don't attempt to select them here
       await this.selectDefaultDevices();
     }
     this.emit(RoomEvent.MediaDevicesChanged);
diff --git a/src/room/track/RemoteAudioTrack.ts b/src/room/track/RemoteAudioTrack.ts
@@ -2,7 +2,12 @@ import { TrackEvent } from '../events';
 import type { AudioReceiverStats } from '../stats';
 import { computeBitrate } from '../stats';
 import type { LoggerOptions } from '../types';
-import { isReactNative, supportsSetSinkId } from '../utils';
+import {
+  getOrCreateSharedRelay,
+  isReactNative,
+  isSafariSpeakerSelectionSupported,
+  supportsSetSinkId,
+} from '../utils';
 import RemoteTrack from './RemoteTrack';
 import { Track } from './Track';
 import type { AudioOutputOptions } from './options';
@@ -82,6 +87,13 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
    */
   async setSinkId(deviceId: string) {
     this.sinkId = deviceId;
+    // On iOS 26, audio routing is handled by the shared relay element at the AudioContext
+    // level — see Room.switchActiveDevice. The attached elements here are muted/vol=0, and
+    // calling setSinkId on them would throw NotAllowedError without a concurrent user gesture
+    // (e.g. when a participant joins after a device switch).
+    if (isSafariSpeakerSelectionSupported()) {
+      return;
+    }
     await Promise.all(
       this.attachedElements.map((elm) => {
         if (!supportsSetSinkId(elm)) {
@@ -103,8 +115,11 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
       super.attach(element);
     }
 
-    if (this.sinkId && supportsSetSinkId(element)) {
-      element.setSinkId(this.sinkId).catch((e) => {
+    // Skip setSinkId on the primary element on iOS 26: the element is muted/vol=0 below and
+    // audio routing happens via the shared relay, so calling setSinkId here would only throw
+    // NotAllowedError when no user gesture is active.
+    if (this.sinkId && supportsSetSinkId(element) && !isSafariSpeakerSelectionSupported()) {
+      (element.setSinkId(this.sinkId) as Promise<void>).catch((e) => {
         this.log.error('Failed to set sink id on remote audio track', e, this.logContext);
       });
     }
@@ -189,7 +204,20 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
     });
     this.gainNode = context.createGain();
     lastNode.connect(this.gainNode);
-    this.gainNode.connect(context.destination);
+
+    // When AudioContext.setSinkId is unavailable (notably iOS 26 Safari), audio is routed via
+    // a shared MediaStreamDestinationNode + relay <audio> element. setSinkId() is called once
+    // on that relay element during the user gesture in Room.switchActiveDevice and applies to
+    // all remote audio. This sidesteps the iOS quirk where HTMLMediaElement.setSinkId() has no
+    // effect on elements backed by WebRTC remote tracks (those go through the WebRTC engine's
+    // internal pipeline → AVAudioSession, bypassing AVPlayer).
+    const useSharedRelay = !('setSinkId' in context);
+    if (useSharedRelay) {
+      this.gainNode.connect(getOrCreateSharedRelay(context).destinationNode);
+    } else {
+      // AudioContext.setSinkId() is available (Chrome, Firefox etc.) — use it directly.
+      this.gainNode.connect(context.destination);
+    }
 
     if (this.elementVolume) {
       this.gainNode.gain.setTargetAtTime(this.elementVolume, 0, 0.1);
diff --git a/src/room/utils.test.ts b/src/room/utils.test.ts
@@ -1,6 +1,15 @@
 import { ClientInfo_Capability } from '@livekit/protocol';
-import { describe, expect, it } from 'vitest';
-import { extractMaxAgeFromRequestHeaders, getClientInfo, splitUtf8, toWebsocketUrl } from './utils';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  disposeSharedRelay,
+  extractMaxAgeFromRequestHeaders,
+  getClientInfo,
+  getOrCreateSharedRelay,
+  isSafariSpeakerSelectionSupported,
+  splitUtf8,
+  supportsSetSinkId,
+  toWebsocketUrl,
+} from './utils';
 
 describe('toWebsocketUrl', () => {
   it('leaves wss urls alone', () => {
@@ -326,3 +335,76 @@ describe('supportsSetSinkId', () => {
     expect(supportsSetSinkId(fakeAudio)).toBe(false);
   });
 });
+
+describe('getOrCreateSharedRelay / disposeSharedRelay', () => {
+  function createMockContext() {
+    const stream = new MediaStream();
+    const destNode = {
+      stream,
+      disconnect: vi.fn(),
+    } as unknown as MediaStreamAudioDestinationNode;
+    const ctx = {
+      createMediaStreamDestination: vi.fn(() => destNode),
+    } as unknown as AudioContext;
+    return { ctx, destNode, stream };
+  }
+
+  it('creates a hidden DOM-attached <audio> element on first call', () => {
+    const { ctx, destNode, stream } = createMockContext();
+    const relay = getOrCreateSharedRelay(ctx);
+    expect(relay.destinationNode).toBe(destNode);
+    expect(relay.relayElement.srcObject).toBe(stream);
+    expect(relay.relayElement.parentElement).toBe(document.body);
+    expect(relay.relayElement.hidden).toBe(true);
+    expect(relay.relayElement.autoplay).toBe(true);
+    disposeSharedRelay(ctx);
+  });
+
+  it('returns the same relay on subsequent calls for the same context (singleton)', () => {
+    const { ctx } = createMockContext();
+    const a = getOrCreateSharedRelay(ctx);
+    const b = getOrCreateSharedRelay(ctx);
+    expect(a).toBe(b);
+    expect(ctx.createMediaStreamDestination).toHaveBeenCalledTimes(1);
+    disposeSharedRelay(ctx);
+  });
+
+  it('creates independent relays for different contexts', () => {
+    const a = createMockContext();
+    const b = createMockContext();
+    const relayA = getOrCreateSharedRelay(a.ctx);
+    const relayB = getOrCreateSharedRelay(b.ctx);
+    expect(relayA).not.toBe(relayB);
+    expect(relayA.destinationNode).toBe(a.destNode);
+    expect(relayB.destinationNode).toBe(b.destNode);
+    disposeSharedRelay(a.ctx);
+    disposeSharedRelay(b.ctx);
+  });
+
+  it('removes the element from the DOM and disconnects the destination on dispose', () => {
+    const { ctx, destNode } = createMockContext();
+    const relay = getOrCreateSharedRelay(ctx);
+    expect(relay.relayElement.parentElement).toBe(document.body);
+
+    disposeSharedRelay(ctx);
+
+    expect(relay.relayElement.parentElement).toBeNull();
+    expect(destNode.disconnect).toHaveBeenCalled();
+  });
+
+  it('creates a fresh relay after dispose', () => {
+    const { ctx } = createMockContext();
+    const first = getOrCreateSharedRelay(ctx);
+    disposeSharedRelay(ctx);
+    const second = getOrCreateSharedRelay(ctx);
+    expect(second).not.toBe(first);
+    expect(ctx.createMediaStreamDestination).toHaveBeenCalledTimes(2);
+    disposeSharedRelay(ctx);
+  });
+
+  it('is a no-op when no relay exists for the context', () => {
+    const { ctx, destNode } = createMockContext();
+    expect(() => disposeSharedRelay(ctx)).not.toThrow();
+    expect(destNode.disconnect).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/room/utils.ts b/src/room/utils.ts
@@ -145,6 +145,50 @@ export function isSVCCodec(codec?: string): boolean {
   return codec === 'av1' || codec === 'vp9';
 }
 
+/** A shared relay element + destination node attached to an AudioContext on iOS 26.
+ *  iOS 26 grants setSinkId permission per-element (not per-origin), so a new <audio> element
+ *  created when a remote participant joins would fail setSinkId without a user gesture.
+ *  Routing all remote tracks through a single shared relay element (created once, setSinkId'd
+ *  once during the user gesture in Room.switchActiveDevice) sidesteps this. */
+const SHARED_RELAY_KEY = '_livekitSharedRelay';
+
+type AudioContextWithSharedRelay = AudioContext & {
+  [SHARED_RELAY_KEY]?: {
+    destinationNode: MediaStreamAudioDestinationNode;
+    relayElement: HTMLAudioElement;
+  };
+};
+
+export function getOrCreateSharedRelay(context: AudioContext): {
+  destinationNode: MediaStreamAudioDestinationNode;
+  relayElement: HTMLAudioElement;
+} {
+  const ctx = context as AudioContextWithSharedRelay;
+  if (!ctx[SHARED_RELAY_KEY]) {
+    const destinationNode = context.createMediaStreamDestination();
+    const relayElement = document.createElement('audio');
+    relayElement.hidden = true;
+    relayElement.autoplay = true;
+    relayElement.srcObject = destinationNode.stream;
+    document.body?.appendChild(relayElement);
+    relayElement.play().catch(() => {});
+    ctx[SHARED_RELAY_KEY] = { destinationNode, relayElement };
+  }
+  return ctx[SHARED_RELAY_KEY]!;
+}
+
+export function disposeSharedRelay(context: AudioContext) {
+  const ctx = context as AudioContextWithSharedRelay;
+  const relay = ctx[SHARED_RELAY_KEY];
+  if (relay) {
+    relay.relayElement.pause();
+    relay.relayElement.srcObject = null;
+    relay.relayElement.parentElement?.removeChild(relay.relayElement);
+    relay.destinationNode.disconnect();
+    delete ctx[SHARED_RELAY_KEY];
+  }
+}
+
 export function supportsSetSinkId(elm?: HTMLMediaElement): boolean {
   if (!document) return false;
   // iOS/Safari 26+ has Speaker Selection API — trust the version check rather than
