livekit-client 2.22.3 → 2.23.0

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

@@ -1,7 +1,12 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { audioDefaults, videoDefaults } from '../defaults';
 import { type AudioCaptureOptions, VideoPresets } from './options';
-import { constraintsForOptions, diffAttributes, mergeDefaultOptions } from './utils';
+import {
+  constraintsForOptions,
+  diffAttributes,
+  mergeDefaultOptions,
+  waitForFirstVideoFrame,
+} from './utils';
 
 describe('mergeDefaultOptions', () => {
   it('does not enable undefined options', () => {
@@ -100,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', () => {
@@ -135,3 +145,197 @@ describe('diffAttributes', () => {
     expect(diff.a).toBe('value');
   });
 });
+
+class FakeVideoTrack extends EventTarget {
+  kind = 'video';
+
+  id = 'fake-video-track';
+
+  label = 'fake';
+
+  enabled = true;
+
+  muted = false;
+
+  readyState: MediaStreamTrackState = 'live';
+
+  settings: MediaTrackSettings;
+
+  constructor(settings: MediaTrackSettings = { width: 1280, height: 720 }) {
+    super();
+    this.settings = settings;
+  }
+
+  getSettings() {
+    return this.settings;
+  }
+
+  getConstraints() {
+    return {};
+  }
+}
+
+const asMediaStreamTrack = (track: FakeVideoTrack) => track as unknown as MediaStreamTrack;
+
+describe('waitForFirstVideoFrame', () => {
+  let frameCallbacks: Map<number, VideoFrameRequestCallback>;
+  let cancelledHandles: number[];
+  let createdVideoElements: HTMLVideoElement[];
+
+  /** happy-dom has no requestVideoFrameCallback, install a controllable one */
+  function enableFrameCallbacks() {
+    let nextHandle = 1;
+    HTMLVideoElement.prototype.requestVideoFrameCallback = function requestVideoFrameCallback(
+      callback: VideoFrameRequestCallback,
+    ) {
+      const handle = nextHandle;
+      nextHandle += 1;
+      frameCallbacks.set(handle, callback);
+      return handle;
+    };
+    HTMLVideoElement.prototype.cancelVideoFrameCallback = function cancelVideoFrameCallback(
+      handle: number,
+    ) {
+      cancelledHandles.push(handle);
+      frameCallbacks.delete(handle);
+    };
+  }
+
+  function deliverFrame() {
+    Array.from(frameCallbacks.values()).forEach((callback) =>
+      callback(0, {} as VideoFrameCallbackMetadata),
+    );
+  }
+
+  beforeEach(() => {
+    frameCallbacks = new Map();
+    cancelledHandles = [];
+    createdVideoElements = [];
+    const createElement = document.createElement.bind(document);
+    vi.spyOn(document, 'createElement').mockImplementation(((
+      tagName: string,
+      options?: ElementCreationOptions,
+    ) => {
+      const element = createElement(tagName, options);
+      if (tagName === 'video') {
+        createdVideoElements.push(element as HTMLVideoElement);
+      }
+      return element;
+    }) as typeof document.createElement);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    // @ts-expect-error removing the stand-in we installed above
+    delete HTMLVideoElement.prototype.requestVideoFrameCallback;
+    // @ts-expect-error removing the stand-in we installed above
+    delete HTMLVideoElement.prototype.cancelVideoFrameCallback;
+  });
+
+  it('resolves once a frame has been delivered', async () => {
+    enableFrameCallbacks();
+    const pending = waitForFirstVideoFrame(asMediaStreamTrack(new FakeVideoTrack()), 1000);
+    expect(createdVideoElements).toHaveLength(1);
+
+    deliverFrame();
+
+    await expect(pending).resolves.toBe(true);
+  });
+
+  it('gives up once the timeout elapses', async () => {
+    enableFrameCallbacks();
+
+    await expect(
+      waitForFirstVideoFrame(asMediaStreamTrack(new FakeVideoTrack()), 20),
+    ).resolves.toBe(false);
+  });
+
+  it.each([
+    ['ended', { readyState: 'ended' as MediaStreamTrackState }],
+    ['muted', { muted: true }],
+    ['disabled', { enabled: false }],
+  ])('does not wait on a track that is %s', async (_label, overrides) => {
+    enableFrameCallbacks();
+    const track = Object.assign(new FakeVideoTrack(), overrides);
+
+    await expect(waitForFirstVideoFrame(asMediaStreamTrack(track), 10_000)).resolves.toBe(false);
+    expect(createdVideoElements).toHaveLength(0);
+  });
+
+  it('falls back to loadeddata when requestVideoFrameCallback is unavailable', async () => {
+    const pending = waitForFirstVideoFrame(asMediaStreamTrack(new FakeVideoTrack()), 1000);
+
+    createdVideoElements[0].dispatchEvent(new Event('loadeddata'));
+
+    await expect(pending).resolves.toBe(true);
+  });
+
+  it('keeps waiting when play() is rejected', async () => {
+    enableFrameCallbacks();
+    vi.spyOn(HTMLMediaElement.prototype, 'play').mockRejectedValue(new Error('NotAllowedError'));
+    const pending = waitForFirstVideoFrame(asMediaStreamTrack(new FakeVideoTrack()), 1000);
+
+    deliverFrame();
+
+    await expect(pending).resolves.toBe(true);
+  });
+
+  it('reuses an element that already renders the track', async () => {
+    enableFrameCallbacks();
+    const track = new FakeVideoTrack();
+    const attached = document.createElement('video');
+    attached.srcObject = new MediaStream([asMediaStreamTrack(track)]);
+    createdVideoElements.length = 0;
+
+    const pending = waitForFirstVideoFrame(asMediaStreamTrack(track), 1000, [attached]);
+    expect(createdVideoElements).toHaveLength(0);
+    deliverFrame();
+
+    await expect(pending).resolves.toBe(true);
+    // the caller owns that element, it must be left rendering
+    expect(attached.srcObject).not.toBeNull();
+  });
+
+  it('reuses an element that has not decoded a frame yet without requestVideoFrameCallback', async () => {
+    const track = new FakeVideoTrack();
+    const attached = document.createElement('video');
+    attached.srcObject = new MediaStream([asMediaStreamTrack(track)]);
+    Object.defineProperty(attached, 'readyState', { value: 1, configurable: true });
+    createdVideoElements.length = 0;
+
+    const pending = waitForFirstVideoFrame(asMediaStreamTrack(track), 1000, [attached]);
+    expect(createdVideoElements).toHaveLength(0);
+    // `loadeddata` has not fired on that element yet, so listening for it still works
+    attached.dispatchEvent(new Event('loadeddata'));
+
+    await expect(pending).resolves.toBe(true);
+  });
+
+  it('declines an already loaded element without requestVideoFrameCallback', async () => {
+    const track = new FakeVideoTrack();
+    const attached = document.createElement('video');
+    attached.srcObject = new MediaStream([asMediaStreamTrack(track)]);
+    Object.defineProperty(attached, 'readyState', { value: 2, configurable: true });
+    createdVideoElements.length = 0;
+
+    const pending = waitForFirstVideoFrame(asMediaStreamTrack(track), 1000, [attached]);
+    // `loadeddata` already fired on that element and is never replayed, so we need our own
+    expect(createdVideoElements).toHaveLength(1);
+    createdVideoElements[0].dispatchEvent(new Event('loadeddata'));
+
+    await expect(pending).resolves.toBe(true);
+  });
+
+  it('tears down the element it created', async () => {
+    enableFrameCallbacks();
+    const pause = vi.spyOn(HTMLMediaElement.prototype, 'pause');
+    const pending = waitForFirstVideoFrame(asMediaStreamTrack(new FakeVideoTrack()), 1000);
+
+    deliverFrame();
+    await pending;
+
+    expect(createdVideoElements[0].srcObject).toBeNull();
+    expect(pause).toHaveBeenCalled();
+    expect(cancelledHandles).toHaveLength(1);
+  });
+});

package/src/room/track/utils.ts

@@ -1,5 +1,6 @@
 import { TrackInfo, TrackPublishedResponse, TrackSource, VideoQuality } from '@livekit/protocol';
 import type { AudioProcessorOptions, TrackProcessor, VideoProcessorOptions } from '../..';
+import log from '../../logger';
 import { cloneDeep } from '../../utils/cloneDeep';
 import { isSafari, sleep } from '../utils';
 import { Track } from './Track';
@@ -107,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;
 }
 
 /**
@@ -351,3 +376,90 @@ export function layerDimensionsFor(
 ): Track.Dimensions | undefined {
   return trackInfo.layers?.find((l) => l.quality === quality);
 }
+
+/**
+ * Waits until `track` has actually produced a video frame.
+ *
+ * iOS keeps reporting the camera's sensor frame from `getSettings()` until the camera has
+ * delivered its first picture, so a portrait capture initially reads as landscape. The arrival
+ * of that first frame is the only reliable signal that the reported settings describe reality.
+ *
+ * Best effort, never throws. Resolves `true` when a frame was observed, `false` when no frame
+ * can be observed (the track is already ended, muted or disabled) or `timeoutMs` elapsed first.
+ *
+ * @internal
+ */
+export async function waitForFirstVideoFrame(
+  track: MediaStreamTrack,
+  timeoutMs: number,
+  candidateElements: HTMLMediaElement[] = [],
+): Promise<boolean> {
+  if (typeof document === 'undefined') {
+    return false;
+  }
+  if (track.readyState === 'ended' || track.muted || !track.enabled) {
+    // no frame is ever going to arrive, don't hold the caller up for the full timeout
+    return false;
+  }
+
+  // requestVideoFrameCallback (Safari 15.4 and up) is a platform capability, so the answer is the
+  // same for every element
+  const supportsFrameCallback =
+    typeof HTMLVideoElement.prototype.requestVideoFrameCallback === 'function';
+
+  // prefer an element that is already rendering this track (a local preview, typically) over
+  // spinning up a second decode just to observe a frame
+  const existingElement = candidateElements.find(
+    (el): el is HTMLVideoElement =>
+      el instanceof HTMLVideoElement &&
+      el.srcObject instanceof MediaStream &&
+      el.srcObject.getVideoTracks().includes(track) &&
+      // without requestVideoFrameCallback we depend on `loadeddata`, which is one-shot: an element
+      // that already decoded a frame (readyState >= HAVE_CURRENT_DATA) never fires it again.
+      // Leave those alone and set up our own element, which starts out empty.
+      (supportsFrameCallback || el.readyState < 2),
+  );
+
+  const element = existingElement ?? document.createElement('video');
+  if (!existingElement) {
+    element.playsInline = true;
+    element.muted = true;
+    element.srcObject = new MediaStream([track]);
+    // the element is deliberately never added to the DOM, it only exists to pull frames.
+    // WebKit delivers frames to a paused element too, so a rejected play() (Safari's low power
+    // mode, for instance) is not a reason to stop waiting
+    element.play().catch((error) => {
+      log.debug('could not play element while waiting for the first video frame', { error });
+    });
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let frameHandle: number | undefined;
+  let onLoadedData: (() => void) | undefined;
+
+  try {
+    return await new Promise<boolean>((resolve) => {
+      timer = setTimeout(() => resolve(false), timeoutMs);
+      if (supportsFrameCallback) {
+        frameHandle = element.requestVideoFrameCallback(() => resolve(true));
+      } else {
+        // Safari below 15.4 has no requestVideoFrameCallback. `loadeddata` fires once the first
+        // frame has been decoded, which is the same signal a few milliseconds earlier.
+        onLoadedData = () => resolve(true);
+        element.addEventListener('loadeddata', onLoadedData);
+      }
+    });
+  } finally {
+    clearTimeout(timer);
+    if (frameHandle !== undefined) {
+      element.cancelVideoFrameCallback?.(frameHandle);
+    }
+    if (onLoadedData) {
+      element.removeEventListener('loadeddata', onLoadedData);
+    }
+    if (!existingElement) {
+      element.pause();
+      element.srcObject = null;
+    }
+  }
+}

package/src/room/utils.test.ts

@@ -1,12 +1,23 @@
 import { ClientInfo_Capability } from '@livekit/protocol';
 import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  stubMissingCompressionStreams,
+  stubMissingDeflateRawSupport,
+} from '../test/compressionStreamStubs';
+import { getBrowser } from '../utils/browserParser';
 import {
   ddExtensionURI,
   extractMaxAgeFromRequestHeaders,
   getClientInfo,
+  isAppleMobile,
+  isCompressionStreamSupported,
+  isDeflateRawCompressionSupported,
+  isIPadOS,
+  isPermissionDeniedError,
   isSVCSimulcast,
   isSVCSimulcastSupportedByServer,
   negotiateDependencyDescriptor,
+  resetDeflateRawCompressionSupportCache,
   splitUtf8,
   supportsAdaptiveStream,
   toWebsocketUrl,
@@ -367,3 +378,242 @@ describe('usesLegacySVCEncodings', () => {
     expect(usesLegacySVCEncodings()).toBe(true);
   });
 });
+
+describe('isIPadOS / isAppleMobile', () => {
+  const stub = (userAgent: string, maxTouchPoints: number) =>
+    vi.stubGlobal('navigator', { userAgent, maxTouchPoints, product: 'Gecko' });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // measured on an iPad 6 running iPadOS 17: the default (desktop) user agent, maxTouchPoints 5
+  const IPAD_DESKTOP_UA =
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.14 Safari/605.1.15';
+  // measured on macOS Safari 26.4: the same shape of user agent, maxTouchPoints 0
+  const MAC_SAFARI_UA =
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.4 Safari/605.1.15';
+  const IPHONE_UA =
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1';
+  const IPAD_MOBILE_UA =
+    'Mozilla/5.0 (iPad; CPU OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1';
+  const MAC_CHROME_UA =
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36';
+  const ANDROID_CHROME_UA =
+    'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Mobile Safari/537.36';
+
+  it('detects an iPad sending the desktop user agent', () => {
+    stub(IPAD_DESKTOP_UA, 5);
+    expect(isIPadOS()).toBe(true);
+    expect(isAppleMobile()).toBe(true);
+  });
+
+  it('is the case getBrowser() alone gets wrong', () => {
+    // the gap this exists to close: iPadOS parses as macOS, so `os === 'iOS'` misses it
+    stub(IPAD_DESKTOP_UA, 5);
+    expect(getBrowser()?.os).toBe('macOS');
+  });
+
+  it('leaves macOS Safari alone, where the camera reports correctly and frames are slow', () => {
+    stub(MAC_SAFARI_UA, 0);
+    expect(isIPadOS()).toBe(false);
+    expect(isAppleMobile()).toBe(false);
+  });
+
+  it('covers iPhones through the existing iOS check', () => {
+    stub(IPHONE_UA, 5);
+    expect(isIPadOS()).toBe(false);
+    expect(isAppleMobile()).toBe(true);
+  });
+
+  it('covers an iPad set to request the mobile site', () => {
+    stub(IPAD_MOBILE_UA, 5);
+    expect(isIPadOS()).toBe(false);
+    expect(isAppleMobile()).toBe(true);
+  });
+
+  it('does not fire for a Mac with a touchscreen attached, which is not Safari', () => {
+    stub(MAC_CHROME_UA, 5);
+    expect(isIPadOS()).toBe(false);
+    expect(isAppleMobile()).toBe(false);
+  });
+
+  it('does not fire on android', () => {
+    stub(ANDROID_CHROME_UA, 5);
+    expect(isIPadOS()).toBe(false);
+    expect(isAppleMobile()).toBe(false);
+  });
+
+  it('does not fire on a desktop safari reporting no touch support', () => {
+    stub(MAC_SAFARI_UA, 1);
+    expect(isIPadOS()).toBe(false);
+  });
+});
+
+describe('isDeflateRawCompressionSupported', () => {
+  afterEach(() => {
+    resetDeflateRawCompressionSupportCache();
+  });
+
+  it('is true in a runtime that supports the deflate-raw format', () => {
+    expect(isDeflateRawCompressionSupported()).toBe(true);
+  });
+
+  it('is false without the compression streams api at all', () => {
+    const restoreCompressionStreams = stubMissingCompressionStreams();
+    try {
+      expect(isDeflateRawCompressionSupported()).toBe(false);
+      expect(isCompressionStreamSupported()).toBe(false);
+    } finally {
+      restoreCompressionStreams();
+    }
+  });
+
+  it('is false when the api exists but deflate-raw is not a supported format', () => {
+    const restoreCompressionStreams = stubMissingDeflateRawSupport();
+    try {
+      expect(isDeflateRawCompressionSupported()).toBe(false);
+      // Chromium 80-102 still compresses gzip, which is all the wrapped join request needs.
+      expect(isCompressionStreamSupported()).toBe(true);
+    } finally {
+      restoreCompressionStreams();
+    }
+  });
+
+  it('probes the runtime only once', () => {
+    expect(isDeflateRawCompressionSupported()).toBe(true);
+
+    const originalCompressionStream = globalThis.CompressionStream;
+    try {
+      (globalThis as any).CompressionStream = undefined;
+      expect(isDeflateRawCompressionSupported()).toBe(true);
+    } finally {
+      (globalThis as any).CompressionStream = originalCompressionStream;
+    }
+  });
+});
+
+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);
+  });
+});