livekit-client 2.22.3 → 2.23.0

package/src/room/participant/LocalParticipant.ts

@@ -32,6 +32,7 @@ import {
 import type { InternalRoomOptions } from '../../options';
 import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import TypedPromise from '../../utils/TypedPromise';
+import DeviceManager from '../DeviceManager';
 import { PCTransportState } from '../PCTransportManager';
 import type RTCEngine from '../RTCEngine';
 import { DataChannelKind } from '../RTCEngine';
@@ -96,11 +97,14 @@ import {
 import {
   Future,
   isAudioTrack,
+  isChromiumBased,
+  isDeviceAcquisitionFailure,
   isE2EESimulcastSupported,
   isFireFox,
   isLocalAudioTrack,
   isLocalTrack,
   isLocalVideoTrack,
+  isPermissionDeniedError,
   isSVCCodec,
   isSVCSimulcast,
   isSVCSimulcastSupportedByServer,
@@ -691,19 +695,21 @@ export default class LocalParticipant extends Participant {
         loggerName: this.roomOptions.loggerName,
         loggerContextCb: () => this.logContext,
       });
-      const localTracks = tracks.map((track) => {
-        if (isAudioTrack(track)) {
-          this.microphoneError = undefined;
-          track.setAudioContext(this.audioContext);
-          track.source = Track.Source.Microphone;
-          this.emit(ParticipantEvent.AudioStreamAcquired);
-        }
-        if (isVideoTrack(track)) {
-          this.cameraError = undefined;
-          track.source = Track.Source.Camera;
-        }
-        return track;
-      });
+      const localTracks = await Promise.all(
+        tracks.map(async (track) => {
+          if (isAudioTrack(track)) {
+            this.microphoneError = undefined;
+            await track.setAudioContext(this.audioContext);
+            track.source = Track.Source.Microphone;
+            this.emit(ParticipantEvent.AudioStreamAcquired);
+          }
+          if (isVideoTrack(track)) {
+            this.cameraError = undefined;
+            track.source = Track.Source.Camera;
+          }
+          return track;
+        }),
+      );
       return localTracks;
     } catch (err) {
       if (err instanceof Error) {
@@ -819,7 +825,7 @@ export default class LocalParticipant extends Participant {
     hasRetriedAfterNegotiationError = false,
   ): Promise<LocalTrackPublication> {
     if (isLocalAudioTrack(track)) {
-      track.setAudioContext(this.audioContext);
+      await track.setAudioContext(this.audioContext);
     }
 
     await this.reconnectFuture?.promise;
@@ -1532,21 +1538,37 @@ export default class LocalParticipant extends Participant {
     }
     const packetTrailerFeatures = this.normalizeRequestedFrameMetadataOptions(track, opts);
 
+    // the backup sender encodes the processed track, not the raw capture track.dimensions reports
+    const { width, height } = track.mediaStreamTrack.getSettings();
+    const dims = width && height ? { width, height } : undefined;
+    if (!dims) {
+      this.log.warn(
+        'could not determine track dimensions, publishing backup codec without layers',
+        getLogContextFromTrack(track),
+      );
+    }
+    // the server reads the layers off the codec entry for a request that carries a sid, and
+    // falls back to the top level ones when it predates per codec layers
+    const layers = dims ? videoLayersFromEncodings(dims.width, dims.height, encodings) : [];
+
     const req = new AddTrackRequest({
       cid: simulcastTrack.mediaStreamTrack.id,
       type: Track.kindToProto(track.kind),
       muted: track.isMuted,
       source: Track.sourceToProto(track.source),
       sid: track.sid,
+      width: dims?.width,
+      height: dims?.height,
       packetTrailerFeatures,
+      layers,
       simulcastCodecs: [
         {
           codec: opts.videoCodec,
           cid: simulcastTrack.mediaStreamTrack.id,
+          layers,
         },
       ],
     });
-    req.layers = videoLayersFromEncodings(req.width, req.height, encodings);
 
     if (!this.engine || this.engine.isClosed) {
       throw new UnexpectedConnectionState('cannot publish track when not connected');
@@ -2140,8 +2162,7 @@ export default class LocalParticipant extends Participant {
             getLogContextFromTrack(track),
           );
           if (isLocalAudioTrack(track)) {
-            // fall back to default device if available
-            await track.restartTrack({ deviceId: 'default' });
+            await this.restartOnDefaultAudioDevice(track);
           } else {
             await track.restartTrack();
           }
@@ -2153,6 +2174,34 @@ export default class LocalParticipant extends Participant {
     }
   };
 
+  /**
+   * @internal
+   */
+  private async restartOnDefaultAudioDevice(track: LocalAudioTrack) {
+    try {
+      if (isChromiumBased()) {
+        // only chrome has the notion of a literal `default` device
+        await track.setDeviceId({ exact: 'default' });
+      } else {
+        // just try to restart for other browsers and try to change the device id as a fallback in the catch clause
+        await track.restartTrack();
+      }
+    } catch (e) {
+      // restart() clears the manually-stopped flag on entry, so retrying a track the user stopped
+      // while the first attempt was in flight would re-open the capture device behind their back
+      if (!isDeviceAcquisitionFailure(e) || isPermissionDeniedError(e) || track.isStopped) {
+        throw e;
+      }
+      this.log.debug(
+        'could not reacquire the audio device, retrying with an enumerated device',
+        getLogContextFromTrack(track),
+      );
+      // permission is already granted at this point, so skip the probe that would re-acquire media
+      const allDevices = await DeviceManager.getInstance().getDevices('audioinput', false);
+      await track.setDeviceId(allDevices?.[0]?.deviceId ?? 'default');
+    }
+  }
+
   private getPublicationForTrack(
     track: LocalTrack | MediaStreamTrack,
   ): LocalTrackPublication | undefined {

package/src/room/participant/Participant.ts

@@ -363,10 +363,13 @@ export default class Participant extends (EventEmitter as new () => TypedEmitter
   /**
    * @internal
    */
-  setAudioContext(ctx: AudioContext | undefined) {
+  async setAudioContext(ctx: AudioContext | undefined) {
     this.audioContext = ctx;
-    this.audioTrackPublications.forEach(
-      (track) => isAudioTrack(track.track) && track.track.setAudioContext(ctx),
+    await Promise.all(
+      Array.from(this.audioTrackPublications.values())
+        .map((publication) => publication.track)
+        .filter(isAudioTrack)
+        .map((track) => track.setAudioContext(ctx)),
     );
   }
 

package/src/room/participant/publishUtils.ts

@@ -74,25 +74,6 @@ export const computeDefaultScreenShareSimulcastPresets = (fromPreset: VideoPrese
   );
 };
 
-// /**
-//  *
-//  * @internal
-//  * @experimental
-//  */
-// const computeDefaultMultiCodecSimulcastEncodings = (width: number, height: number) => {
-//   // use vp8 as a default
-//   const vp8 = determineAppropriateEncoding(false, width, height);
-//   const vp9 = { ...vp8, maxBitrate: vp8.maxBitrate * 0.9 };
-//   const h264 = { ...vp8, maxBitrate: vp8.maxBitrate * 1.1 };
-//   const av1 = { ...vp8, maxBitrate: vp8.maxBitrate * 0.7 };
-//   return {
-//     vp8,
-//     vp9,
-//     h264,
-//     av1,
-//   };
-// };
-
 const videoRids = ['q', 'h', 'f'];
 
 /* @internal */

package/src/room/participant/restartOnDefaultAudioDevice.test.ts

@@ -0,0 +1,177 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import DeviceManager from '../DeviceManager';
+import type LocalAudioTrack from '../track/LocalAudioTrack';
+import { Track } from '../track/Track';
+import { isChromiumBased, markDeviceAcquisitionFailure } from '../utils';
+import LocalParticipant from './LocalParticipant';
+
+vi.mock('../utils', async () => {
+  const actual = await vi.importActual('../utils');
+  return {
+    ...actual,
+    isChromiumBased: vi.fn(() => true),
+  };
+});
+
+type DefaultDeviceTestParticipant = {
+  restartOnDefaultAudioDevice: (track: LocalAudioTrack) => Promise<void>;
+  log: { debug: ReturnType<typeof vi.fn> };
+};
+
+function makeDefaultDeviceParticipant() {
+  const participant = Object.create(
+    LocalParticipant.prototype,
+  ) as unknown as DefaultDeviceTestParticipant;
+  participant.log = { debug: vi.fn() };
+  return participant;
+}
+
+function errorNamed(name: string) {
+  const e = new Error(name);
+  e.name = name;
+  markDeviceAcquisitionFailure(e);
+  return e;
+}
+
+function makeAudioTrack(
+  setDeviceId: ReturnType<typeof vi.fn>,
+  restartTrack: ReturnType<typeof vi.fn> = vi.fn(),
+  isStopped = false,
+) {
+  return {
+    sid: 'track-sid',
+    source: Track.Source.Microphone,
+    setDeviceId,
+    restartTrack,
+    isStopped,
+  } as unknown as LocalAudioTrack;
+}
+
+function stubAudioDevices(...deviceIds: string[]) {
+  const getDevices = vi.fn().mockResolvedValue(deviceIds.map((deviceId) => ({ deviceId })));
+  vi.spyOn(DeviceManager, 'getInstance').mockReturnValue({
+    getDevices,
+  } as unknown as DeviceManager);
+  return getDevices;
+}
+
+describe('LocalParticipant restartOnDefaultAudioDevice', () => {
+  beforeEach(() => {
+    vi.mocked(isChromiumBased).mockReturnValue(true);
+    stubAudioDevices('mic-1', 'mic-2');
+  });
+
+  it('falls back to an available device when the exact default is rejected', async () => {
+    const getDevices = stubAudioDevices('mic-1', 'mic-2');
+    const setDeviceId = vi.fn().mockRejectedValueOnce(errorNamed('OverconstrainedError'));
+    const participant = makeDefaultDeviceParticipant();
+
+    await participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId));
+
+    expect(getDevices).toHaveBeenCalledWith('audioinput', false);
+    expect(setDeviceId).toHaveBeenCalledTimes(2);
+    expect(setDeviceId).toHaveBeenNthCalledWith(1, { exact: 'default' });
+    expect(setDeviceId).toHaveBeenNthCalledWith(2, 'mic-1');
+  });
+
+  it('falls back to the default id when no device is enumerated', async () => {
+    stubAudioDevices();
+    const setDeviceId = vi.fn().mockRejectedValueOnce(errorNamed('OverconstrainedError'));
+    const participant = makeDefaultDeviceParticipant();
+
+    await participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId));
+
+    expect(setDeviceId).toHaveBeenNthCalledWith(2, 'default');
+  });
+
+  it('falls back for a rejection name the spec does not prescribe', async () => {
+    const setDeviceId = vi.fn().mockRejectedValueOnce(errorNamed('ConstraintNotSatisfiedError'));
+    const participant = makeDefaultDeviceParticipant();
+
+    await participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId));
+
+    expect(setDeviceId).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not retry a denied permission, so one prompt never becomes two', async () => {
+    const setDeviceId = vi.fn().mockRejectedValue(errorNamed('NotAllowedError'));
+    const participant = makeDefaultDeviceParticipant();
+
+    await expect(
+      participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId)),
+    ).rejects.toThrow();
+
+    expect(setDeviceId).toHaveBeenCalledOnce();
+  });
+
+  it('asks for the exact default only, when that succeeds', async () => {
+    const setDeviceId = vi.fn().mockResolvedValue(undefined);
+    const participant = makeDefaultDeviceParticipant();
+
+    await participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId));
+
+    expect(setDeviceId).toHaveBeenCalledOnce();
+    expect(setDeviceId).toHaveBeenCalledWith({ exact: 'default' });
+  });
+
+  it('propagates the second rejection, not the first', async () => {
+    const setDeviceId = vi
+      .fn()
+      .mockRejectedValueOnce(errorNamed('OverconstrainedError'))
+      .mockRejectedValueOnce(errorNamed('NotReadableError'));
+    const participant = makeDefaultDeviceParticipant();
+
+    await expect(
+      participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId)),
+    ).rejects.toThrow('NotReadableError');
+
+    expect(setDeviceId).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not retry a failure that happened after the device was acquired', async () => {
+    const postAcquisition = new Error('processor restart failed');
+    const setDeviceId = vi.fn().mockRejectedValue(postAcquisition);
+    const participant = makeDefaultDeviceParticipant();
+
+    await expect(
+      participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId)),
+    ).rejects.toThrow('processor restart failed');
+
+    expect(setDeviceId).toHaveBeenCalledOnce();
+  });
+
+  it('does not retry a track the user stopped while the first attempt was in flight', async () => {
+    const setDeviceId = vi.fn().mockRejectedValue(errorNamed('OverconstrainedError'));
+    const participant = makeDefaultDeviceParticipant();
+
+    await expect(
+      participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId, vi.fn(), true)),
+    ).rejects.toThrow();
+
+    expect(setDeviceId).toHaveBeenCalledOnce();
+  });
+
+  it('keeps the existing device id on a browser without a literal default', async () => {
+    vi.mocked(isChromiumBased).mockReturnValue(false);
+    const setDeviceId = vi.fn();
+    const restartTrack = vi.fn().mockResolvedValue(undefined);
+    const participant = makeDefaultDeviceParticipant();
+
+    await participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId, restartTrack));
+
+    expect(restartTrack).toHaveBeenCalledOnce();
+    expect(setDeviceId).not.toHaveBeenCalled();
+  });
+
+  it('switches device when a browser without a literal default cannot reacquire', async () => {
+    vi.mocked(isChromiumBased).mockReturnValue(false);
+    const setDeviceId = vi.fn();
+    const restartTrack = vi.fn().mockRejectedValue(errorNamed('OverconstrainedError'));
+    const participant = makeDefaultDeviceParticipant();
+
+    await participant.restartOnDefaultAudioDevice(makeAudioTrack(setDeviceId, restartTrack));
+
+    expect(restartTrack).toHaveBeenCalledOnce();
+    expect(setDeviceId).toHaveBeenCalledExactlyOnceWith('mic-1');
+  });
+});

package/src/room/rpc/client/RpcClientManager.test.ts

@@ -255,6 +255,57 @@ describe('RpcClientManager', () => {
       }
     });
 
+    it('cleans up a failed v2 publish without a later ack timeout', async () => {
+      vi.useFakeTimers();
+
+      try {
+        sendTextMock.mockRejectedValue(new Error('engine closed'));
+        await expect(
+          rpcClientManager.performRpc({
+            destinationIdentity: 'remote-identity',
+            method: 'test-method',
+            payload: 'test-payload',
+          }),
+        ).rejects.toThrow('engine closed');
+
+        expect(vi.getTimerCount()).toBe(0);
+        expect((rpcClientManager as any).pendingAcks.size).toBe(0);
+        expect((rpcClientManager as any).pendingResponses.size).toBe(0);
+        await vi.advanceTimersByTimeAsync(7001);
+        // An unhandled rejection from completionFuture would also fail Vitest.
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('handles an ack timeout while a v2 publish is still pending', async () => {
+      vi.useFakeTimers();
+
+      try {
+        let resolveSend!: () => void;
+        sendTextMock.mockReturnValue(
+          new Promise<void>((resolve) => {
+            resolveSend = resolve;
+          }),
+        );
+        const performRpcPromise = rpcClientManager.performRpc({
+          destinationIdentity: 'remote-identity',
+          method: 'test-method',
+          payload: 'test-payload',
+        });
+
+        await vi.advanceTimersByTimeAsync(7001);
+        resolveSend();
+        const [, completionPromise] = await performRpcPromise;
+        await expect(completionPromise).rejects.toThrow(/Connection timeout/i);
+        expect(vi.getTimerCount()).toBe(0);
+        expect((rpcClientManager as any).pendingAcks.size).toBe(0);
+        expect((rpcClientManager as any).pendingResponses.size).toBe(0);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
     it('should handle a v2 RPC error response', async () => {
       const errorCode = 101;
       const errorMessage = 'Test error message';

package/src/room/rpc/client/RpcClientManager.ts

@@ -108,22 +108,13 @@ export default class RpcClientManager extends (EventEmitter as new () => TypedEm
       participantIdentity: destinationIdentity,
     });
 
-    await this.publishRpcRequest(
-      destinationIdentity,
-      id,
-      method,
-      payload,
-      effectiveTimeoutMs,
-      remoteClientProtocol,
-    );
-
-    responseTimeoutId = setTimeout(() => {
-      this.pendingResponses.delete(id);
-      completionFuture.reject?.(RpcError.builtIn('RESPONSE_TIMEOUT'));
-    }, responseTimeoutMs);
-
+    // Observe the future before publishing: a slow send can outlast the ack timer.
+    // Keep the returned promise rejected for callers, while marking its rejection
+    // handled until performRpc has finished publishing and can return it.
     const completionPromise = completionFuture.promise.finally(() => {
-      clearTimeout(responseTimeoutId);
+      if (responseTimeoutId !== null) {
+        clearTimeout(responseTimeoutId);
+      }
 
       if (this.pendingAcks.has(id)) {
         this.log.warn('RPC response received before ack', id);
@@ -131,6 +122,32 @@ export default class RpcClientManager extends (EventEmitter as new () => TypedEm
         clearTimeout(ackTimeoutId);
       }
     });
+    completionPromise.catch(() => {});
+
+    try {
+      await this.publishRpcRequest(
+        destinationIdentity,
+        id,
+        method,
+        payload,
+        effectiveTimeoutMs,
+        remoteClientProtocol,
+      );
+    } catch (e) {
+      // The caller receives the publish error. Do not leave an ack timer that
+      // later rejects a future the caller never received.
+      clearTimeout(ackTimeoutId);
+      this.pendingAcks.delete(id);
+      this.pendingResponses.delete(id);
+      throw e;
+    }
+
+    if (this.pendingResponses.has(id)) {
+      responseTimeoutId = setTimeout(() => {
+        this.pendingResponses.delete(id);
+        completionFuture.reject?.(RpcError.builtIn('RESPONSE_TIMEOUT'));
+      }, responseTimeoutMs);
+    }
 
     return [id, completionPromise];
   }

package/src/room/rpc/utils.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { RpcError, byteLength, truncateBytes } from './utils';
+
+describe('truncateBytes', () => {
+  it('returns the string unchanged when it fits', () => {
+    expect(truncateBytes('hello', 5)).toBe('hello');
+  });
+
+  it('truncates ASCII on the byte limit', () => {
+    expect(truncateBytes('hello world', 5)).toBe('hello');
+  });
+
+  it('does not split a multibyte character', () => {
+    expect(truncateBytes('aéé', 4)).toBe('aé');
+  });
+
+  it('does not leave half of a surrogate pair when truncating emoji', () => {
+    // 'a' (1 byte) + 63 emoji (4 bytes each) = 253 bytes, so the limit falls inside the next emoji.
+    const str = `a${'😀'.repeat(64)}`;
+    const truncated = truncateBytes(str, 256);
+
+    expect(truncated).toBe(`a${'😀'.repeat(63)}`);
+    expect(new TextDecoder().decode(new TextEncoder().encode(truncated))).toBe(truncated);
+  });
+
+  it('keeps an RpcError message valid when it is cut inside an emoji', () => {
+    const error = new RpcError(1500, `a${'😀'.repeat(100)}`);
+
+    expect(byteLength(error.message)).toBeLessThanOrEqual(RpcError.MAX_MESSAGE_BYTES);
+    expect(error.message).not.toMatch(/[\ud800-\udbff](?![\udc00-\udfff])/);
+  });
+});

package/src/room/rpc/utils.ts

@@ -214,5 +214,12 @@ export function truncateBytes(str: string, maxBytes: number): string {
     }
   }
 
+  // Never end on the first half of a surrogate pair: it would be encoded as a replacement
+  // character, and the truncated string would no longer round trip.
+  const lastCode = low > 0 ? str.charCodeAt(low - 1) : 0;
+  if (lastCode >= 0xd800 && lastCode <= 0xdbff) {
+    low -= 1;
+  }
+
   return str.slice(0, low);
 }

package/src/room/track/LocalAudioTrack.ts

@@ -18,6 +18,12 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
 
   private isKrispNoiseFilterEnabled = false;
 
+  /**
+   * the processed track we currently have krisp feature listeners registered on. Tracked
+   * separately, as `processor.processedTrack` can be swapped out while we hold the listeners.
+   */
+  private observedProcessedTrack?: MediaStreamTrack;
+
   protected processor?: TrackProcessor<Track.Kind.Audio, AudioProcessorOptions> | undefined;
 
   /**
@@ -184,6 +190,51 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
     );
   };
 
+  /**
+   * registers the krisp feature listeners on the given processed track, moving them over from
+   * a previously observed one. Passing `undefined` just removes the existing listeners.
+   */
+  private observeProcessedTrack(processedTrack: MediaStreamTrack | undefined) {
+    if (this.observedProcessedTrack === processedTrack) {
+      return;
+    }
+    if (this.observedProcessedTrack) {
+      this.observedProcessedTrack.removeEventListener(
+        'enable-lk-krisp-noise-filter',
+        this.handleKrispNoiseFilterEnable,
+      );
+      this.observedProcessedTrack.removeEventListener(
+        'disable-lk-krisp-noise-filter',
+        this.handleKrispNoiseFilterDisable,
+      );
+      this.observedProcessedTrack = undefined;
+      if (this.isKrispNoiseFilterEnabled) {
+        // we're no longer observing the track that had the filter enabled, so the feature
+        // can't be active anymore. Make sure the state doesn't get stuck on `true`.
+        this.handleKrispNoiseFilterDisable();
+      }
+    }
+    if (!processedTrack) {
+      return;
+    }
+    processedTrack.addEventListener(
+      'enable-lk-krisp-noise-filter',
+      this.handleKrispNoiseFilterEnable,
+    );
+    processedTrack.addEventListener(
+      'disable-lk-krisp-noise-filter',
+      this.handleKrispNoiseFilterDisable,
+    );
+    this.observedProcessedTrack = processedTrack;
+  }
+
+  /**
+   * Sets a processor on this track.
+   *
+   * The processor is destroyed when the track is stopped, and also when the audio context goes
+   * away, so a disconnect ends it on both counts and it has to be set again after reconnecting.
+   * See {@link TrackProcessor} for the full lifecycle.
+   */
   async setProcessor(processor: TrackProcessor<Track.Kind.Audio, AudioProcessorOptions>) {
     const unlock = await this.trackChangeLock.lock();
     try {
@@ -209,14 +260,7 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
       this.processor = processor;
       if (this.processor.processedTrack) {
         await this.sender?.replaceTrack(this.processor.processedTrack);
-        this.processor.processedTrack.addEventListener(
-          'enable-lk-krisp-noise-filter',
-          this.handleKrispNoiseFilterEnable,
-        );
-        this.processor.processedTrack.addEventListener(
-          'disable-lk-krisp-noise-filter',
-          this.handleKrispNoiseFilterDisable,
-        );
+        this.observeProcessedTrack(this.processor.processedTrack);
       }
       this.emit(TrackEvent.TrackProcessorUpdate, this.processor);
     } finally {
@@ -224,12 +268,59 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
     }
   }
 
+  protected override async onMediaStreamTrackChanged(): Promise<void> {
+    // the processor rebuilds its graph around the new track, so the krisp listeners have to
+    // follow it onto whatever it hands back
+    this.observeProcessedTrack(this.processor?.processedTrack);
+  }
+
+  protected async internalStopProcessor(keepElement = true) {
+    this.observeProcessedTrack(undefined);
+    await super.internalStopProcessor(keepElement);
+  }
+
+  stop() {
+    this.observeProcessedTrack(undefined);
+    super.stop();
+  }
+
   /**
    * @internal
    * @experimental
+   *
+   * A processor's nodes (`AudioWorkletNode`, ...) can't move between contexts, so the processor
+   * is rebuilt whenever the context changes and torn down when there is none left to run in.
    */
-  setAudioContext(audioContext: AudioContext | undefined) {
-    this.audioContext = audioContext;
+  async setAudioContext(audioContext: AudioContext | undefined) {
+    if (this.audioContext === audioContext) {
+      return;
+    }
+    const unlock = await this.trackChangeLock.lock();
+    try {
+      this.audioContext = audioContext;
+      if (!this.processor || isReactNative()) {
+        return;
+      }
+      if (!audioContext) {
+        this.log.debug('stopping audio processor, audio context has been removed', this.logContext);
+        await this.internalStopProcessor();
+        return;
+      }
+      this.log.debug('restarting audio processor on new audio context', this.logContext);
+      await this.processor.restart({
+        kind: this.kind,
+        track: this._mediaStreamTrack,
+        audioContext,
+        localTrack: this,
+      });
+      if (this.processor.processedTrack) {
+        await this.sender?.replaceTrack(this.processor.processedTrack);
+        this.observeProcessedTrack(this.processor.processedTrack);
+      }
+      this.emit(TrackEvent.TrackProcessorUpdate, this.processor);
+    } finally {
+      unlock();
+    }
   }
 
   async getSenderStats(): Promise<AudioSenderStats | undefined> {