livekit-client 2.22.4 → 2.23.0

package/src/room/track/LocalTrack.ts

@@ -5,7 +5,14 @@ import { debounce } from '../debounce';
 import { DeviceUnsupportedError, TrackInvalidError } from '../errors';
 import { TrackEvent } from '../events';
 import type { LoggerOptions } from '../types';
-import { compareVersions, isAppleMobile, isMobile, sleep, unwrapConstraint } from '../utils';
+import {
+  compareVersions,
+  isAppleMobile,
+  isMobile,
+  markDeviceAcquisitionFailure,
+  sleep,
+  unwrapConstraint,
+} from '../utils';
 import { Track, attachToElement, detachTrack } from './Track';
 import type { VideoCodec } from './options';
 import type { TrackProcessor } from './processor/types';
@@ -132,6 +139,10 @@ export default abstract class LocalTrack<
     return this.providedByUser;
   }
 
+  get isStopped() {
+    return this.manuallyStopped;
+  }
+
   get mediaStreamTrack() {
     return this.processor?.processedTrack ?? this._mediaStreamTrack;
   }
@@ -195,6 +206,9 @@ export default abstract class LocalTrack<
         track: newTrack,
         kind: this.kind,
         element: this.processorElement,
+        // audio processors need the context they were initialised with in order to rebuild
+        // their graph, omitting it here would leave them without one
+        audioContext: this.audioContext,
         localTrack: this,
       });
       processedTrack = this.processor.processedTrack;
@@ -218,6 +232,17 @@ export default abstract class LocalTrack<
         attachToElement(processedTrack ?? newTrack, el);
       });
     }
+    await this.onMediaStreamTrackChanged();
+  }
+
+  /**
+   * Hook invoked after the underlying MediaStreamTrack has been swapped and the processor has
+   * been restarted around it, so `processor.processedTrack` already holds the new track.
+   * Unlike `onSenderTrackSwapped` this also fires on the restart and unmute paths.
+   */
+  protected async onMediaStreamTrackChanged(): Promise<void> {
+    // base implementation is a no-op; LocalAudioTrack overrides this to move the krisp
+    // feature listeners onto the new processed track.
   }
 
   async waitForDimensions(timeout = DEFAULT_DIMENSIONS_TIMEOUT): Promise<Track.Dimensions> {
@@ -255,7 +280,8 @@ export default abstract class LocalTrack<
   async setDeviceId(deviceId: ConstrainDOMString): Promise<boolean> {
     if (
       this._constraints.deviceId === deviceId &&
-      this._mediaStreamTrack.getSettings().deviceId === unwrapConstraint(deviceId)
+      this._mediaStreamTrack.getSettings().deviceId === unwrapConstraint(deviceId) &&
+      this._mediaStreamTrack.readyState === 'live'
     ) {
       return true;
     }
@@ -386,19 +412,37 @@ export default abstract class LocalTrack<
       this._mediaStreamTrack.stop();
 
       // create new track and attach
-      const mediaStream = await navigator.mediaDevices.getUserMedia(streamConstraints);
+      let mediaStream: MediaStream;
+      try {
+        mediaStream = await navigator.mediaDevices.getUserMedia(streamConstraints);
+      } catch (e) {
+        markDeviceAcquisitionFailure(e);
+        throw e;
+      }
       const newTrack = mediaStream.getTracks()[0];
-      if (this.kind === Track.Kind.Video) {
-        // we already captured the audio track with the constraints, so we only need to apply the video constraints
-        await newTrack.applyConstraints(otherConstraints);
+      try {
+        if (this.kind === Track.Kind.Video) {
+          // we already captured the audio track with the constraints, so we only need to apply the video constraints
+          await newTrack.applyConstraints(otherConstraints);
+        }
+        newTrack.addEventListener('ended', this.handleEnded);
+        this.log.debug('re-acquired MediaStreamTrack', this.logContext);
+
+        await this.setMediaStreamTrack(newTrack, false, isUnmuting);
+      } catch (e) {
+        // setMediaStreamTrack can throw after acquisition but before it adopts the new track,
+        // which would leave the capture device live with nothing referencing it
+        if (this._mediaStreamTrack !== newTrack) {
+          newTrack.stop();
+        }
+        throw e;
       }
-      newTrack.addEventListener('ended', this.handleEnded);
-      this.log.debug('re-acquired MediaStreamTrack', this.logContext);
-
-      await this.setMediaStreamTrack(newTrack, false, isUnmuting);
       this._constraints = constraints;
       this.pendingDeviceChange = false;
       this.emit(TrackEvent.Restarted, this);
+      return this;
+    } finally {
+      // in the finally because a throw can also leave the new track adopted, and so still live
       if (this.manuallyStopped) {
         this.log.warn(
           'track was stopped during a restart, stopping restarted track',
@@ -406,8 +450,6 @@ export default abstract class LocalTrack<
         );
         this.stop();
       }
-      return this;
-    } finally {
       unlock();
     }
   }
@@ -475,7 +517,11 @@ export default abstract class LocalTrack<
     this._mediaStreamTrack.removeEventListener('ended', this.handleEnded);
     this._mediaStreamTrack.removeEventListener('mute', this.handleTrackMuteEvent);
     this._mediaStreamTrack.removeEventListener('unmute', this.handleTrackUnmuteEvent);
-    this.processor?.destroy();
+    // `stop` is synchronous, so we can't await the teardown of the processor here.
+    // make sure a failing teardown doesn't surface as an unhandled rejection.
+    this.processor?.destroy().catch((error) => {
+      this.log.error('failed to destroy processor', { ...this.logContext, error });
+    });
     this.processor = undefined;
   }
 
@@ -551,6 +597,11 @@ export default abstract class LocalTrack<
    * Sets a processor on this track.
    * See https://github.com/livekit/track-processors-js for example usage
    *
+   * The processor lives on the track, so stopping the track destroys it. Unpublishing and
+   * disconnecting both stop the track by default, which means a processor has to be set again on
+   * the track published after a reconnect. See {@link TrackProcessor} for the full lifecycle,
+   * including what `stopLocalTrackOnUnpublish: false` changes.
+   *
    * @param processor
    * @param showProcessedStreamLocally
    * @returns
@@ -617,6 +668,10 @@ export default abstract class LocalTrack<
     await this.onSenderTrackSwapped();
   }
 
+  /**
+   * Returns the processor currently set on this track, or `undefined` if there is none. A track
+   * that was stopped by an unpublish or a disconnect has none. See {@link TrackProcessor}.
+   */
   getProcessor() {
     return this.processor;
   }
@@ -625,6 +680,8 @@ export default abstract class LocalTrack<
    * Stops the track processor
    * See https://github.com/livekit/track-processors-js for example usage
    *
+   * Only needed to remove a processor from a track that stays published. Unpublishing or
+   * disconnecting already destroys it. See {@link TrackProcessor}.
    */
   async stopProcessor(keepElement = true) {
     const unlock = await this.trackChangeLock.lock();

package/src/room/track/LocalVideoTrack.ts

@@ -401,6 +401,13 @@ export default class LocalVideoTrack extends LocalTrack<Track.Kind.Video> {
     await sender.setParameters(params);
   }
 
+  /**
+   * Sets a processor on this track, and wires its processed track into the simulcast codecs.
+   *
+   * The processor is destroyed when the track is stopped, which unpublishing and disconnecting
+   * both do by default, so it has to be set again after reconnecting. See {@link TrackProcessor}
+   * for the full lifecycle.
+   */
   async setProcessor(
     processor: TrackProcessor<Track.Kind.Video>,
     showProcessedStreamLocally = true,

package/src/room/track/RemoteAudioTrack.ts

@@ -20,6 +20,13 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
 
   private webAudioPluginNodes: AudioNode[];
 
+  /**
+   * the nodes of the graph currently wired up, in order, so teardown can undo exactly the edges
+   * `connectWebAudio` created. Reading `webAudioPluginNodes` instead would miss the old plugins
+   * once `setWebAudioPlugins` has replaced them.
+   */
+  private connectedNodes: AudioNode[] = [];
+
   private sinkId?: string;
 
   constructor(
@@ -42,10 +49,11 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
    * sets the volume for all attached audio elements
    */
   setVolume(volume: number) {
-    for (const el of this.attachedElements) {
-      if (this.audioContext) {
-        this.gainNode?.gain.setTargetAtTime(volume, 0, 0.1);
-      } else {
+    if (this.audioContext) {
+      // playback goes through the web audio graph, the attached elements themselves stay silent
+      this.gainNode?.gain.setTargetAtTime(volume, 0, 0.1);
+    } else {
+      for (const el of this.attachedElements) {
         el.volume = volume;
       }
     }
@@ -96,7 +104,9 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
   attach(): HTMLMediaElement;
   attach(element: HTMLMediaElement): HTMLMediaElement;
   attach(element?: HTMLMediaElement): HTMLMediaElement {
-    const needsNewWebAudioConnection = this.attachedElements.length === 0;
+    // the graph is fed by the track rather than by a specific element, so one connection covers
+    // all attached elements
+    const needsNewWebAudioConnection = !this.sourceNode;
     if (!element) {
       element = super.attach();
     } else {
@@ -108,11 +118,15 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
         this.log.error('Failed to set sink id on remote audio track', e, this.logContext);
       });
     }
-    if (this.audioContext && needsNewWebAudioConnection) {
-      this.log.debug('using audio context mapping', this.logContext);
-      this.connectWebAudio(this.audioContext, element);
+    if (this.audioContext) {
+      // audio is routed through the web audio graph, so every attached element has to stay
+      // silent, no matter whether it is the one the graph was built from
       element.volume = 0;
       element.muted = true;
+      if (needsNewWebAudioConnection) {
+        this.log.debug('using audio context mapping', this.logContext);
+        this.connectWebAudio(this.audioContext, element);
+      }
     }
 
     if (this.elementVolume !== undefined) {
@@ -158,11 +172,26 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
    * @experimental
    */
   setAudioContext(audioContext: AudioContext | undefined) {
+    if (this.audioContext === audioContext) {
+      return;
+    }
     this.audioContext = audioContext;
-    if (audioContext && this.attachedElements.length > 0) {
-      this.connectWebAudio(audioContext, this.attachedElements[0]);
-    } else if (!audioContext) {
+    if (audioContext) {
+      // playback moves into the web audio graph, mute the elements to avoid double playback
+      for (const element of this.attachedElements) {
+        element.volume = 0;
+        element.muted = true;
+      }
+      if (this.attachedElements.length > 0) {
+        this.connectWebAudio(audioContext, this.attachedElements[0]);
+      }
+    } else {
       this.disconnectWebAudio();
+      // playback moves back into the elements, which `attach` had muted in favour of the graph
+      for (const element of this.attachedElements) {
+        element.muted = false;
+        element.volume = this.elementVolume ?? 1;
+      }
     }
   }
 
@@ -183,12 +212,15 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
     // @ts-ignore attached elements always have a srcObject set
     this.sourceNode = context.createMediaStreamSource(element.srcObject);
     let lastNode: AudioNode = this.sourceNode;
+    this.connectedNodes = [this.sourceNode];
     this.webAudioPluginNodes.forEach((node) => {
       lastNode.connect(node);
       lastNode = node;
+      this.connectedNodes.push(node);
     });
     this.gainNode = context.createGain();
     lastNode.connect(this.gainNode);
+    this.connectedNodes.push(this.gainNode);
     this.gainNode.connect(context.destination);
 
     if (this.elementVolume !== undefined) {
@@ -214,6 +246,19 @@ export default class RemoteAudioTrack extends RemoteTrack<Track.Kind.Audio> {
   }
 
   private disconnectWebAudio() {
+    // the plugin nodes belong to whoever passed them in and may feed graphs of their own, so only
+    // the edges this track created come down. A bare `node.disconnect()` would drop the
+    // application's own routing with them
+    for (let i = 0; i < this.connectedNodes.length - 1; i += 1) {
+      try {
+        this.connectedNodes[i].disconnect(this.connectedNodes[i + 1]);
+      } catch {
+        // a plugin node the application already disconnected itself, the rest of the chain still
+        // has to come apart
+      }
+    }
+    this.connectedNodes = [];
+    // the source and gain nodes are ours alone, so every remaining edge of theirs is ours to drop
     this.gainNode?.disconnect();
     this.sourceNode?.disconnect();
     this.gainNode = undefined;

package/src/room/track/processor/types.ts

@@ -22,6 +22,17 @@ export interface AudioProcessorOptions extends ProcessorOptions<Track.Kind.Audio
  */
 export interface VideoProcessorOptions extends ProcessorOptions<Track.Kind.Video> {}
 
+/**
+ * A processor is bound to the track it was set on, not to the room, and it does not survive the
+ * track being stopped: unpublishing a track or disconnecting from a room destroys its processor.
+ * Both paths stop the track by default, so after reconnecting or republishing, call
+ * `setProcessor` again on the new track to put the processor back.
+ *
+ * The exception is `stopLocalTrackOnUnpublish: false`, which keeps the track alive across an
+ * unpublish or disconnect. A video processor then survives with it. An audio processor only
+ * survives if the audio context came from the application, because a context the SDK created is
+ * closed on disconnect and the processor goes with it.
+ */
 export interface TrackProcessor<
   T extends Track.Kind,
   U extends ProcessorOptions<T> = ProcessorOptions<T>,

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

@@ -105,6 +105,11 @@ describe('constraintsForOptions', () => {
     expect(videoOpts.frameRate).toEqual(VideoPresets.h720.resolution.frameRate);
     expect(videoOpts.aspectRatio).toEqual(VideoPresets.h720.resolution.aspectRatio);
   });
+
+  it('leaves an explicitly set exact deviceId untouched', () => {
+    const constraints = constraintsForOptions({ audio: { deviceId: { exact: 'default' } } });
+    expect((constraints.audio as MediaTrackConstraints).deviceId).toEqual({ exact: 'default' });
+  });
 });
 
 describe('diffAttributes', () => {

package/src/room/track/utils.ts

@@ -108,22 +108,46 @@ export function constraintsForOptions(options: CreateLocalTracksOptions): MediaS
  */
 export async function detectSilence(track: AudioTrack, timeOffset = 200): Promise<boolean> {
   const ctx = getNewAudioContext();
-  if (ctx) {
-    const analyser = ctx.createAnalyser();
+  if (!ctx) {
+    return false;
+  }
+  let source: MediaStreamAudioSourceNode | undefined;
+  let analyser: AnalyserNode | undefined;
+  try {
+    analyser = ctx.createAnalyser();
     analyser.fftSize = 2048;
 
     const bufferLength = analyser.frequencyBinCount;
     const dataArray = new Uint8Array(bufferLength);
-    const source = ctx.createMediaStreamSource(new MediaStream([track.mediaStreamTrack]));
+    source = ctx.createMediaStreamSource(new MediaStream([track.mediaStreamTrack]));
 
     source.connect(analyser);
+    // read through a function so that `state` isn't narrowed to its value from before `resume`
+    const isRunning = () => ctx.state === 'running';
+    if (!isRunning()) {
+      try {
+        // `resume` can stay pending indefinitely on a blocked page rather than rejecting, which
+        // would keep the context and its nodes alive past the `finally` below
+        await Promise.race([ctx.resume(), sleep(200)]);
+      } catch {
+        // autoplay policies can keep us from resuming the context
+      }
+      if (!isRunning()) {
+        // a context that isn't running doesn't process any audio, so the analyser would only ever
+        // read silence. Report the track as not silent rather than raising a false positive.
+        return false;
+      }
+    }
     await sleep(timeOffset);
     analyser.getByteTimeDomainData(dataArray);
     const someNoise = dataArray.some((sample) => sample !== 128 && sample !== 0);
-    ctx.close();
     return !someNoise;
+  } finally {
+    source?.disconnect();
+    analyser?.disconnect();
+    // don't let a failing teardown mask the detection result
+    await ctx.close().catch(() => {});
   }
-  return false;
 }
 
 /**

package/src/room/utils.test.ts

@@ -13,6 +13,7 @@ import {
   isCompressionStreamSupported,
   isDeflateRawCompressionSupported,
   isIPadOS,
+  isPermissionDeniedError,
   isSVCSimulcast,
   isSVCSimulcastSupportedByServer,
   negotiateDependencyDescriptor,
@@ -491,3 +492,128 @@ describe('isDeflateRawCompressionSupported', () => {
     }
   });
 });
+
+describe('isPermissionDeniedError', () => {
+  function errorNamed(name: string) {
+    const e = new Error(name);
+    e.name = name;
+    return e;
+  }
+
+  it('matches the permission denial names and their legacy aliases', () => {
+    expect(isPermissionDeniedError(errorNamed('NotAllowedError'))).toBe(true);
+    expect(isPermissionDeniedError(errorNamed('SecurityError'))).toBe(true);
+    expect(isPermissionDeniedError(errorNamed('PermissionDeniedError'))).toBe(true);
+    expect(isPermissionDeniedError(errorNamed('PermissionDismissedError'))).toBe(true);
+  });
+
+  it('does not match failures that a softer constraint could still satisfy', () => {
+    expect(isPermissionDeniedError(errorNamed('OverconstrainedError'))).toBe(false);
+    expect(isPermissionDeniedError(errorNamed('ConstraintNotSatisfiedError'))).toBe(false);
+    expect(isPermissionDeniedError(errorNamed('NotFoundError'))).toBe(false);
+    expect(isPermissionDeniedError(errorNamed('SomeNameNobodyHasShippedYet'))).toBe(false);
+  });
+
+  it('does not match a plain error, undefined or null', () => {
+    expect(isPermissionDeniedError(new Error('boom'))).toBe(false);
+    expect(isPermissionDeniedError(undefined)).toBe(false);
+    expect(isPermissionDeniedError(null)).toBe(false);
+  });
+});
+
+// `freshUtils` below calls `vi.resetModules()`, so a dynamic import of `./utils` from a later
+// block would get a different module instance than the static import at the top of this file.
+// Keep this block last.
+describe('empty audio stream track refcounting', () => {
+  let closedContexts: number;
+
+  function makeTrack(): MediaStreamTrack {
+    const track = {
+      enabled: true,
+      stopped: false,
+      stop() {
+        track.stopped = true;
+      },
+      clone: () => makeTrack(),
+    };
+    return track as unknown as MediaStreamTrack;
+  }
+
+  /** reloads `./utils` so its module level context and refcount start empty */
+  async function freshUtils() {
+    closedContexts = 0;
+    vi.resetModules();
+    vi.stubGlobal(
+      'AudioContext',
+      class {
+        createOscillator() {
+          return { connect: () => {}, start: () => {} };
+        }
+
+        createGain() {
+          return { gain: { setValueAtTime: () => {} }, connect: () => {} };
+        }
+
+        createMediaStreamDestination() {
+          return { stream: { getAudioTracks: () => [makeTrack()] } };
+        }
+
+        async close() {
+          closedContexts += 1;
+        }
+      },
+    );
+    return import('./utils');
+  }
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('closes the shared context once every track handed out is released', async () => {
+    const { getEmptyAudioStreamTrack, releaseEmptyAudioStreamTrack } = await freshUtils();
+    const first = getEmptyAudioStreamTrack();
+    const second = getEmptyAudioStreamTrack();
+
+    await releaseEmptyAudioStreamTrack(first);
+    expect(closedContexts).toBe(0);
+
+    await releaseEmptyAudioStreamTrack(second);
+    expect(closedContexts).toBe(1);
+  });
+
+  it('ignores a second release of the same track', async () => {
+    const { getEmptyAudioStreamTrack, releaseEmptyAudioStreamTrack } = await freshUtils();
+    const first = getEmptyAudioStreamTrack();
+    const second = getEmptyAudioStreamTrack();
+
+    await releaseEmptyAudioStreamTrack(first);
+    await releaseEmptyAudioStreamTrack(first);
+    expect(closedContexts).toBe(0);
+
+    await releaseEmptyAudioStreamTrack(second);
+    expect(closedContexts).toBe(1);
+  });
+
+  it('leaves a track it never handed out alone', async () => {
+    const { getEmptyAudioStreamTrack, releaseEmptyAudioStreamTrack } = await freshUtils();
+    const owned = getEmptyAudioStreamTrack();
+    const foreign = makeTrack();
+
+    await releaseEmptyAudioStreamTrack(foreign);
+    expect(closedContexts).toBe(0);
+    expect((foreign as unknown as { stopped: boolean }).stopped).toBe(false);
+
+    await releaseEmptyAudioStreamTrack(owned);
+    expect(closedContexts).toBe(1);
+  });
+
+  it('builds a fresh context for an acquire that arrives after the last release', async () => {
+    const { getEmptyAudioStreamTrack, releaseEmptyAudioStreamTrack } = await freshUtils();
+    await releaseEmptyAudioStreamTrack(getEmptyAudioStreamTrack());
+    expect(closedContexts).toBe(1);
+
+    await releaseEmptyAudioStreamTrack(getEmptyAudioStreamTrack());
+    expect(closedContexts).toBe(2);
+  });
+});

package/src/room/utils.ts

@@ -559,6 +559,17 @@ export function createDummyVideoStreamTrack(
 
 let emptyAudioStreamTrack: MediaStreamTrack | undefined;
 
+let emptyAudioStreamContext: AudioContext | undefined;
+
+/** tracks handed out by `getEmptyAudioStreamTrack` that haven't been released yet */
+const outstandingEmptyAudioStreamTracks = new Set<MediaStreamTrack>();
+
+/**
+ * Returns a silent audio track, cloned off a shared `AudioContext` created on first use. Hand the
+ * clone back to `releaseEmptyAudioStreamTrack` rather than stopping it, so the context can close.
+ * A clone that is only stopped stays counted as outstanding, which holds the shared context open
+ * for the lifetime of the page.
+ */
 export function getEmptyAudioStreamTrack() {
   if (!emptyAudioStreamTrack) {
     // implementation adapted from https://blog.mozilla.org/webrtc/warm-up-with-replacetrack/
@@ -572,31 +583,37 @@ export function getEmptyAudioStreamTrack() {
     oscillator.start();
     [emptyAudioStreamTrack] = dst.stream.getAudioTracks();
     if (!emptyAudioStreamTrack) {
+      // don't hold on to a context we can't get a track out of
+      ctx.close().catch(() => {});
       throw Error('Could not get empty media stream audio track');
     }
     emptyAudioStreamTrack.enabled = false;
+    emptyAudioStreamContext = ctx;
+  }
+  const track = emptyAudioStreamTrack.clone();
+  outstandingEmptyAudioStreamTracks.add(track);
+  return track;
+}
+
+/**
+ * Stops a track obtained from `getEmptyAudioStreamTrack` and closes the shared `AudioContext`
+ * backing it once every track it handed out has been released. Does nothing for a track this
+ * module never handed out, or one that has been released already.
+ */
+export async function releaseEmptyAudioStreamTrack(track: MediaStreamTrack) {
+  if (!outstandingEmptyAudioStreamTracks.delete(track)) {
+    // the track wasn't obtained from `getEmptyAudioStreamTrack`, or has been released before
+    return;
   }
-  return emptyAudioStreamTrack.clone();
-}
-
-export function getStereoAudioStreamTrack() {
-  const ctx = new AudioContext();
-  const oscLeft = ctx.createOscillator();
-  const oscRight = ctx.createOscillator();
-  oscLeft.frequency.value = 440;
-  oscRight.frequency.value = 220;
-  const merger = ctx.createChannelMerger(2);
-  oscLeft.connect(merger, 0, 0); // left channel
-  oscRight.connect(merger, 0, 1); // right channel
-  const dst = ctx.createMediaStreamDestination();
-  merger.connect(dst);
-  oscLeft.start();
-  oscRight.start();
-  const [stereoTrack] = dst.stream.getAudioTracks();
-  if (!stereoTrack) {
-    throw Error('Could not get stereo media stream audio track');
+  track.stop();
+  if (outstandingEmptyAudioStreamTracks.size > 0) {
+    return;
   }
-  return stereoTrack;
+  const context = emptyAudioStreamContext;
+  emptyAudioStreamTrack?.stop();
+  emptyAudioStreamTrack = undefined;
+  emptyAudioStreamContext = undefined;
+  await context?.close();
 }
 
 /** An object that represents a serialized version of a `new Promise((resolve, reject) => {})`
@@ -708,11 +725,20 @@ export function createAudioAnalyser(
     return volume;
   };
 
+  let isCleanedUp = false;
+
   const cleanup = async () => {
-    await audioContext.close();
+    if (isCleanedUp) {
+      // closing an already closed context would reject, make repeated cleanups a no-op instead
+      return;
+    }
+    isCleanedUp = true;
+    mediaStreamSource.disconnect();
+    analyser.disconnect();
     if (opts.cloneTrack) {
       streamTrack.stop();
     }
+    await audioContext.close();
   };
 
   return { calculateVolume, analyser, cleanup };
@@ -751,6 +777,43 @@ export function unwrapConstraint(constraint: ConstrainDOMString | ConstrainULong
   throw Error('could not unwrap constraint');
 }
 
+/**
+ * The getUserMedia rejections that no softer constraint can recover from, because the user or the
+ * document refused capture outright. Retrying one of these would put a second prompt in front of
+ * someone who already said no. The last two names are legacy spellings still reported by older
+ * engines. Matched by `name` rather than with `instanceof`, because these are not reliably distinct
+ * constructors across environments. happy-dom, which the tests run under, aliases them to `Event`.
+ */
+export function isPermissionDeniedError(e: unknown): boolean {
+  return (
+    typeof e === 'object' &&
+    e !== null &&
+    'name' in e &&
+    (e.name === 'NotAllowedError' ||
+      e.name === 'SecurityError' ||
+      e.name === 'PermissionDeniedError' ||
+      e.name === 'PermissionDismissedError')
+  );
+}
+
+const deviceAcquisitionFailures = new WeakSet();
+
+/** Records that `e` is the rejection getUserMedia itself produced. */
+export function markDeviceAcquisitionFailure(e: unknown) {
+  if (typeof e === 'object' && e !== null) {
+    deviceAcquisitionFailures.add(e);
+  }
+}
+
+/**
+ * Whether a track restart failed at getUserMedia rather than in the work that adopts the new track.
+ * Recorded on the side rather than by wrapping, because callers of `restartTrack` match on the
+ * rejection's own name.
+ */
+export function isDeviceAcquisitionFailure(e: unknown): boolean {
+  return typeof e === 'object' && e !== null && deviceAcquisitionFailures.has(e);
+}
+
 export function toWebsocketUrl(url: string): string {
   if (url.startsWith('http')) {
     return url.replace(/^(http)/, 'ws');