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

Author: fkwp

src/index.ts

@@ -53,9 +53,9 @@ import {
   isLocalTrack,
   isRemoteParticipant,
   isRemoteTrack,
+  isSafariSpeakerSelectionSupported,
   isVideoCodec,
   isVideoTrack,
-  isSafariSpeakerSelectionSupported,
   supportsAV1,
   supportsAdaptiveStream,
   supportsAudioOutputSelection,

src/room/Room.ts

@@ -103,10 +103,12 @@ import {
 import {
   Future,
   createDummyVideoStreamTrack,
+  disposeSharedRelay,
   extractChatMessage,
   extractTranscriptionSegments,
   getDisconnectReasonFromConnectionError,
   getEmptyAudioStreamTrack,
+  getOrCreateSharedRelay,
   isBrowserSupported,
   isCloud,
   isLocalAudioTrack,
@@ -1473,22 +1475,26 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
           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 })),
-        );
-
-        // On platforms where AudioContext.setSinkId is unavailable (e.g. iOS 26 Safari), audio
-        // is routed through a relay <audio> element whose setSinkId is called without a user
-        // gesture when a remote track is first received. iOS requires that setSinkId has been
-        // called at least once with a user gesture for a given deviceId before it will honour
-        // the call from a non-gesture context. When there are no remote participants yet (the
-        // user is switching the device while alone), we call setSinkId on a temporary element
-        // right now — within the current user gesture — to pre-grant that permission.
-        if (this.remoteParticipants.size === 0 && canSwitch && !audioContextHasSinkId) {
-          const permissionEl = document.createElement('audio');
-          await (permissionEl.setSinkId(deviceId) as Promise<void>).catch(() => {});
+        if (isSafariSpeakerSelectionSupported() && this.audioContext) {
+          // 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>
+          ).catch((e) => {
+            this.log.warn('Failed to set sink id on shared relay element', e, this.logContext);
+          });
+        } else {
+          // Chrome / fallback: set on individual participant elements.
+          // Also needed for Chrome echo cancellation workaround with non-default output devices
+          // even when webAudioMix is enabled.
+          // 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;
@@ -1824,9 +1830,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);

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';
@@ -18,15 +23,6 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
 
   private sourceNode?: MediaStreamAudioSourceNode;
 
-  /** Used on iOS >=26 Safari where AudioContext.setSinkId is unavailable.
-   *  On iOS26, WebRTC remote tracks bypass the HTMLMediaElement/AVPlayer pipeline — they go
-   *  through the WebRTC engine's own internal audio pipeline connected directly to
-   *  AVAudioSession — so HTMLMediaElement.setSinkId() has no effect on them.
-   *  Audio is therefore routed WebRTC→AudioContext→MediaStreamDestinationNode→this element.
-   *  This relay element's srcObject is AudioContext-generated, which goes through the normal
-   *  AVPlayer pipeline where setSinkId() is honoured. */
-  private webAudioRelayElement?: HTMLAudioElement;
-
   private webAudioPluginNodes: AudioNode[];
 
   private sinkId?: string;
@@ -91,12 +87,15 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
    */
   async setSinkId(deviceId: string) {
     this.sinkId = deviceId;
-    const targets: HTMLAudioElement[] = [
-      ...(this.attachedElements as HTMLAudioElement[]),
-      ...(this.webAudioRelayElement ? [this.webAudioRelayElement] : []),
-    ];
+    // 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(
-      targets.map((elm) => {
+      this.attachedElements.map((elm) => {
         if (!supportsSetSinkId(elm)) {
           return;
         }
@@ -118,7 +117,10 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
       super.attach(element);
     }
 
-    if (this.sinkId && supportsSetSinkId(element)) {
+    // 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);
       });
@@ -209,26 +211,13 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
       // AudioContext.setSinkId() is available (Chrome, Firefox etc.) — use it directly.
       this.gainNode.connect(context.destination);
     } else {
-      // AudioContext.setSinkId() is not available (iOS 26 Safari).
-      // On iOS, WebRTC remote tracks go through the WebRTC engine's own audio pipeline
-      // (connected directly to AVAudioSession), bypassing the AVPlayer pipeline that
-      // setSinkId() controls. Route through a MediaStreamDestinationNode so that the
-      // relay element's srcObject is AudioContext-generated; that stream goes through
-      // AVPlayer and setSinkId() is honoured.
-      const destinationNode = context.createMediaStreamDestination();
-      this.gainNode.connect(destinationNode);
-      const relayEl = document.createElement('audio');
-      relayEl.hidden = true;
-      relayEl.autoplay = true;
-      relayEl.srcObject = destinationNode.stream;
-      document.body?.appendChild(relayEl);
-      relayEl.play().catch(() => {});
-      if (this.sinkId && supportsSetSinkId(relayEl)) {
-        (relayEl.setSinkId(this.sinkId) as Promise<void>).catch((e) => {
-          this.log.error('Failed to set sink id on web audio relay element', e, this.logContext);
-        });
-      }
-      this.webAudioRelayElement = relayEl;
+      // iOS 26 Safari: AudioContext.setSinkId() is unavailable AND HTMLMediaElement.setSinkId()
+      // has no effect on elements backed by WebRTC remote tracks (those go through the WebRTC
+      // engine's internal pipeline → AVAudioSession, bypassing AVPlayer). Route via a shared
+      // MediaStreamDestinationNode + relay element so that setSinkId() — called once on the
+      // shared relay element during the user gesture in Room.switchActiveDevice — applies to
+      // all remote audio.
+      this.gainNode.connect(getOrCreateSharedRelay(context).destinationNode);
     }
 
     if (this.elementVolume) {
@@ -258,12 +247,6 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
     this.sourceNode?.disconnect();
     this.gainNode = undefined;
     this.sourceNode = undefined;
-    if (this.webAudioRelayElement) {
-      this.webAudioRelayElement.pause();
-      this.webAudioRelayElement.srcObject = null;
-      this.webAudioRelayElement.parentElement?.removeChild(this.webAudioRelayElement);
-      this.webAudioRelayElement = undefined;
-    }
   }
 
   protected monitorReceiver = async () => {

src/room/utils.test.ts

@@ -3,7 +3,6 @@ import { describe, expect, it } from 'vitest';
 import { extractMaxAgeFromRequestHeaders, getClientInfo, splitUtf8, toWebsocketUrl } from './utils';
 import { isSafariSpeakerSelectionSupported, supportsSetSinkId } from './utils';
 
-
 describe('toWebsocketUrl', () => {
   it('leaves wss urls alone', () => {
     expect(toWebsocketUrl('ws://mywebsite.com')).toEqual('ws://mywebsite.com');
@@ -193,45 +192,55 @@ describe('extractMaxAgeFromRequestHeaders', () => {
 
 describe('isSafariSpeakerSelectionSupported', () => {
   it('returns true for Safari >= 26', () => {
-    expect(isSafariSpeakerSelectionSupported({
-      name: 'Safari',
-      version: '26.0',
-      os: 'macOS',
-      osVersion: '26.0',
-    })).toBe(true);
-    expect(isSafariSpeakerSelectionSupported({
-      name: 'Safari',
-      version: '27.1',
-      os: 'macOS',
-      osVersion: '27.1',
-    })).toBe(true);
+    expect(
+      isSafariSpeakerSelectionSupported({
+        name: 'Safari',
+        version: '26.0',
+        os: 'macOS',
+        osVersion: '26.0',
+      }),
+    ).toBe(true);
+    expect(
+      isSafariSpeakerSelectionSupported({
+        name: 'Safari',
+        version: '27.1',
+        os: 'macOS',
+        osVersion: '27.1',
+      }),
+    ).toBe(true);
   });
 
   it('returns true for iOS Safari >= 26', () => {
-    expect(isSafariSpeakerSelectionSupported({
-      name: 'Safari',
-      version: '26.0',
-      os: 'iOS',
-      osVersion: '26.0',
-    })).toBe(true);
+    expect(
+      isSafariSpeakerSelectionSupported({
+        name: 'Safari',
+        version: '26.0',
+        os: 'iOS',
+        osVersion: '26.0',
+      }),
+    ).toBe(true);
   });
 
   it('returns false for Safari < 26', () => {
-    expect(isSafariSpeakerSelectionSupported({
-      name: 'Safari',
-      version: '25.9',
-      os: 'macOS',
-      osVersion: '25.9',
-    })).toBe(false);
+    expect(
+      isSafariSpeakerSelectionSupported({
+        name: 'Safari',
+        version: '25.9',
+        os: 'macOS',
+        osVersion: '25.9',
+      }),
+    ).toBe(false);
   });
 
   it('returns false for non-Safari browsers', () => {
-    expect(isSafariSpeakerSelectionSupported({
-      name: 'Chrome',
-      version: '120.0',
-      os: 'macOS',
-      osVersion: '14.0',
-    })).toBe(false);
+    expect(
+      isSafariSpeakerSelectionSupported({
+        name: 'Chrome',
+        version: '120.0',
+        os: 'macOS',
+        osVersion: '14.0',
+      }),
+    ).toBe(false);
   });
 });
 
@@ -246,18 +255,20 @@ describe('supportsSetSinkId', () => {
   });
   it('returns true if setSinkId is present', () => {
     Object.defineProperty(navigator, 'userAgent', {
-      value: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15',
+      value:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15',
       configurable: true,
     });
     const fakeAudio = { setSinkId: () => {} } as any as HTMLMediaElement;
     expect(supportsSetSinkId(fakeAudio)).toBe(true);
   });
   it('returns false if setSinkId not supported', () => {
     Object.defineProperty(navigator, 'userAgent', {
-      value: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.6 Safari/605.1.15',
+      value:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.6 Safari/605.1.15',
       configurable: true,
     });
     const fakeAudio = { setSinkId: () => {} } as any as HTMLMediaElement;
     expect(supportsSetSinkId(fakeAudio)).toBe(false);
   });
-});
+});