livekit-client 2.21.0 → 2.22.0

package/src/room/token-source/TokenSource.ts

@@ -213,29 +213,34 @@ class TokenSourceEndpoint extends TokenSourceCached {
     const body = await response.json();
     return TokenSourceResponse.fromJson(body, {
       // NOTE: it could be possible that the response body could contain more fields than just
-      // what's in TokenSourceResponse depending on the implementation (ie, SandboxTokenServer)
+      // what's in TokenSourceResponse depending on the implementation (ie, DevelopmentTokenServer)
       ignoreUnknownFields: true,
     });
   }
 }
 
-export type SandboxTokenServerOptions = {
+export type DevelopmentTokenServerOptions = {
   baseUrl?: string;
 };
-
-class TokenSourceSandboxTokenServer extends TokenSourceEndpoint {
-  constructor(sandboxId: string, options: SandboxTokenServerOptions) {
+class TokenSourceDevelopmentTokenServer extends TokenSourceEndpoint {
+  constructor(tokenServerId: string, options: DevelopmentTokenServerOptions) {
     const { baseUrl = 'https://cloud-api.livekit.io', ...rest } = options;
 
     super(`${baseUrl}/api/v2/sandbox/connection-details`, {
       ...rest,
       headers: {
-        'X-Sandbox-ID': sandboxId,
+        'X-Sandbox-ID': tokenServerId,
       },
     });
   }
 }
 
+/** @deprecated use {@link DevelopmentTokenServerOptions} instead */
+export type SandboxTokenServerOptions = DevelopmentTokenServerOptions;
+
+/** @deprecated Use {@link TokenSourceDevelopmentTokenServer} instead */
+class TokenSourceSandboxTokenServer extends TokenSourceDevelopmentTokenServer {}
+
 export {
   /** The return type of {@link TokenSource.literal} */
   type TokenSourceLiteral,
@@ -243,8 +248,9 @@ export {
   type TokenSourceCustom,
   /** The return type of {@link TokenSource.endpoint} */
   type TokenSourceEndpoint,
-  /** The return type of {@link TokenSource.sandboxTokenServer} */
   type TokenSourceSandboxTokenServer,
+  /** The return type of {@link TokenSource.developmentTokenServer} */
+  type TokenSourceDevelopmentTokenServer,
   decodeTokenPayload,
   areTokenSourceFetchOptionsEqual,
 };
@@ -269,22 +275,29 @@ export const TokenSource = {
   /**
    * TokenSource.endpoint creates a token source that fetches credentials from a given URL using
    * the standard endpoint format:
-   * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+   * @see https://docs.livekit.io/frontends/build/authentication/endpoint/
    */
   endpoint(url: string, options: EndpointOptions = {}) {
     return new TokenSourceEndpoint(url, options);
   },
 
   /**
-   * TokenSource.sandboxTokenServer queries a sandbox token server for credentials,
+   * @deprecated Use {@link TokenSource.developmentTokenServer} instead
+   */
+  sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) {
+    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  },
+
+  /**
+   * TokenSource.developmentTokenServer queries a development token server for credentials,
    * which supports quick prototyping / getting started types of use cases.
    *
    * This token provider is INSECURE and should NOT be used in production.
    *
    * For more info:
-   * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+   * @see https://docs.livekit.io/frontends/build/authentication/sandbox-token-server/
    */
-  sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) {
-    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  developmentTokenServer(tokenServerId: string, options: DevelopmentTokenServerOptions = {}) {
+    return new TokenSourceDevelopmentTokenServer(tokenServerId, options);
   },
 };

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

@@ -1,6 +1,8 @@
-import { describe, expect, it } from 'vitest';
-import { videoLayersFromEncodings } from './LocalVideoTrack';
+import { describe, expect, it, vi } from 'vitest';
+import LocalVideoTrack, { videoLayersFromEncodings } from './LocalVideoTrack';
+import type { SimulcastTrackInfo } from './LocalVideoTrack';
 import { VideoQuality } from './Track';
+import type { VideoCodec } from './options';
 
 describe('videoLayersFromEncodings', () => {
   it('returns single layer for no encoding', () => {
@@ -131,3 +133,104 @@ describe('videoLayersFromEncodings', () => {
     expect(layers[2].width).toBe(720);
   });
 });
+
+function makeSender(label = 'sender', events: string[] = []) {
+  let params: RTCRtpSendParameters = {
+    encodings: [],
+    transactionId: '',
+    codecs: [],
+    headerExtensions: [],
+    rtcp: {},
+  };
+  return {
+    getParameters: () => params,
+    // resolves on a later task, like the real setParameters, so that a caller
+    // which fails to await it never observes the update
+    setParameters: vi.fn(async (next: RTCRtpSendParameters) => {
+      events.push(`${label}:start`);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      params = next;
+      events.push(`${label}:done`);
+    }),
+    get degradationPreference() {
+      return params.degradationPreference;
+    },
+  };
+}
+
+function makeTrack() {
+  const track = Object.create(LocalVideoTrack.prototype) as LocalVideoTrack;
+  Object.assign(track, {
+    log: { debug: vi.fn(), warn: vi.fn() },
+    simulcastCodecs: new Map<VideoCodec, SimulcastTrackInfo>(),
+    subscribedCodecs: undefined,
+  });
+  // logContext and mediaStreamTrack are getters we don't set up state for here
+  Object.defineProperty(track, 'logContext', { get: () => ({}) });
+  Object.defineProperty(track, 'mediaStreamTrack', { get: () => ({ clone: () => ({}) }) });
+  return track;
+}
+
+describe('setDegradationPreference', () => {
+  it('applies the preference to the primary sender', async () => {
+    const track = makeTrack();
+    const sender = makeSender();
+    Object.assign(track, { _sender: sender });
+
+    await track.setDegradationPreference('maintain-resolution');
+
+    expect(sender.degradationPreference).toBe('maintain-resolution');
+  });
+
+  it('applies the resolved preference to a backup codec sender', async () => {
+    const track = makeTrack();
+    const primary = makeSender();
+    Object.assign(track, { _sender: primary });
+
+    await track.setDegradationPreference('maintain-resolution');
+
+    // the backup codec transceiver is created later, when the server asks for it
+    const backupInfo = track.addSimulcastTrack('vp8', [])!;
+    const backup = makeSender();
+    await track.setSimulcastTrackSender('vp8', backup as unknown as RTCRtpSender);
+
+    expect(backupInfo.sender).toBe(backup);
+    expect(backup.degradationPreference).toBe('maintain-resolution');
+    expect(primary.degradationPreference).toBe('maintain-resolution');
+  });
+
+  it('updates every sender when the preference changes after the backup is published', async () => {
+    const track = makeTrack();
+    const primary = makeSender();
+    Object.assign(track, { _sender: primary });
+    await track.setDegradationPreference('maintain-framerate');
+
+    track.addSimulcastTrack('vp8', []);
+    const backup = makeSender();
+    await track.setSimulcastTrackSender('vp8', backup as unknown as RTCRtpSender);
+
+    await track.setDegradationPreference('balanced');
+
+    expect(primary.degradationPreference).toBe('balanced');
+    expect(backup.degradationPreference).toBe('balanced');
+  });
+
+  it('applies to senders one at a time', async () => {
+    const events: string[] = [];
+    const track = makeTrack();
+    const primary = makeSender('primary', events);
+    Object.assign(track, { _sender: primary });
+    track.addSimulcastTrack('vp8', []);
+    await track.setSimulcastTrackSender(
+      'vp8',
+      makeSender('backup', events) as unknown as RTCRtpSender,
+    );
+    events.length = 0;
+
+    await track.setDegradationPreference('balanced');
+
+    // setParameters is only valid against the most recent getParameters, so the
+    // writes must not overlap
+    expect(events).toEqual(['primary:start', 'primary:done', 'backup:start', 'backup:done']);
+  });
+});

package/src/room/track/LocalVideoTrack.ts

@@ -406,15 +406,37 @@ export default class LocalVideoTrack extends LocalTrack<Track.Kind.Video> {
 
   async setDegradationPreference(preference: RTCDegradationPreference) {
     this.degradationPreference = preference;
-    if (this.sender) {
-      try {
-        this.log.debug(`setting degradationPreference to ${preference}`, this.logContext);
-        const params = this.sender.getParameters();
-        params.degradationPreference = preference;
-        this.sender.setParameters(params);
-      } catch (e: any) {
-        this.log.warn(`failed to set degradationPreference`, { error: e, ...this.logContext });
-      }
+    // applied one sender at a time on purpose, see applyDegradationPreference
+    await this.applyDegradationPreference(this.sender);
+    for (const sc of this.simulcastCodecs.values()) {
+      await this.applyDegradationPreference(sc.sender);
+    }
+  }
+
+  /**
+   * Degradation preference is a property of the sender, not of the track, so every sender
+   * publishing this track needs it applied separately. A backup codec publishes over its
+   * own sender, which would otherwise let the browser resolve a preference implicitly and
+   * diverge from the primary encoder.
+   *
+   * Callers apply this sequentially rather than concurrently: `setParameters` is only valid
+   * against the parameters most recently returned by `getParameters`, which is why this file
+   * serializes other sender parameter updates through `senderLock`.
+   */
+  private async applyDegradationPreference(sender?: RTCRtpSender) {
+    if (!sender) {
+      return;
+    }
+    try {
+      this.log.debug(
+        `setting degradationPreference to ${this.degradationPreference}`,
+        this.logContext,
+      );
+      const params = sender.getParameters();
+      params.degradationPreference = this.degradationPreference;
+      await sender.setParameters(params);
+    } catch (e: any) {
+      this.log.warn(`failed to set degradationPreference`, { error: e, ...this.logContext });
     }
   }
 
@@ -436,13 +458,17 @@ export default class LocalVideoTrack extends LocalTrack<Track.Kind.Video> {
     return simulcastCodecInfo;
   }
 
-  setSimulcastTrackSender(codec: VideoCodec, sender: RTCRtpSender) {
+  async setSimulcastTrackSender(codec: VideoCodec, sender: RTCRtpSender) {
     const simulcastCodecInfo = this.simulcastCodecs.get(codec);
     if (!simulcastCodecInfo) {
       return;
     }
     simulcastCodecInfo.sender = sender;
 
+    // the backup codec publishes over its own sender, so it needs the same degradation
+    // preference the primary sender resolved to.
+    await this.applyDegradationPreference(sender);
+
     // browser will reenable disabled codec/layers after new codec has been published,
     // so refresh subscribedCodecs after publish a new codec
     setTimeout(() => {

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

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import MockMediaStreamTrack from '../../test/MockMediaStreamTrack';
+import { TrackEvent } from '../events';
+import RemoteVideoTrack from './RemoteVideoTrack';
+
+describe('RemoteTrack time sync loop', () => {
+  let track: RemoteVideoTrack;
+  let getSynchronizationSources: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    // fake timers back `requestAnimationFrame`, so cancellation behaves like it does in a browser
+    vi.useFakeTimers();
+    // `supportsSynchronizationSources()` gates the loop on this being implemented
+    vi.stubGlobal(
+      'RTCRtpReceiver',
+      class {
+        getSynchronizationSources() {}
+      },
+    );
+
+    let rtpTimestamp = 0;
+    getSynchronizationSources = vi.fn(() => [{ timestamp: 1, rtpTimestamp: ++rtpTimestamp }]);
+    const receiver = { getSynchronizationSources } as unknown as RTCRtpReceiver;
+    track = new RemoteVideoTrack(new MockMediaStreamTrack(), 'sid', receiver, {});
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it('does not sample the receiver when nobody listens', () => {
+    track.startMonitor();
+    vi.advanceTimersToNextFrame();
+
+    expect(getSynchronizationSources).not.toHaveBeenCalled();
+  });
+
+  it('starts the loop when a listener subscribes', () => {
+    track.startMonitor();
+    const listener = vi.fn();
+    track.on(TrackEvent.TimeSyncUpdate, listener);
+    vi.advanceTimersToNextFrame();
+
+    expect(listener).toHaveBeenCalledWith({ timestamp: 1, rtpTimestamp: 1 });
+  });
+
+  it('starts the loop for listeners that subscribed before the monitor started', () => {
+    const listener = vi.fn();
+    track.on(TrackEvent.TimeSyncUpdate, listener);
+    track.startMonitor();
+    vi.advanceTimersToNextFrame();
+
+    expect(listener).toHaveBeenCalled();
+  });
+
+  it('does not start a second loop when a second listener subscribes', () => {
+    track.startMonitor();
+    track.on(TrackEvent.TimeSyncUpdate, vi.fn());
+    track.on(TrackEvent.TimeSyncUpdate, vi.fn());
+
+    vi.advanceTimersToNextFrame();
+
+    // a second chain would sample twice per frame
+    expect(getSynchronizationSources).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not start a second loop when the monitor is started again', () => {
+    track.on(TrackEvent.TimeSyncUpdate, vi.fn());
+    track.startMonitor();
+    track.startMonitor();
+    getSynchronizationSources.mockClear();
+
+    vi.advanceTimersToNextFrame();
+
+    expect(getSynchronizationSources).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops the loop once the last listener unsubscribes', () => {
+    const listener = vi.fn();
+    track.startMonitor();
+    track.on(TrackEvent.TimeSyncUpdate, listener);
+    vi.advanceTimersToNextFrame();
+
+    track.off(TrackEvent.TimeSyncUpdate, listener);
+    vi.advanceTimersToNextFrame();
+    getSynchronizationSources.mockClear();
+    vi.advanceTimersToNextFrame();
+
+    expect(getSynchronizationSources).not.toHaveBeenCalled();
+  });
+
+  it('restarts the loop when a listener subscribes again', () => {
+    const listener = vi.fn();
+    track.startMonitor();
+    track.on(TrackEvent.TimeSyncUpdate, listener);
+    track.off(TrackEvent.TimeSyncUpdate, listener);
+    vi.advanceTimersToNextFrame();
+    listener.mockClear();
+
+    track.on(TrackEvent.TimeSyncUpdate, listener);
+    vi.advanceTimersToNextFrame();
+
+    expect(listener).toHaveBeenCalled();
+  });
+
+  it('cancels a running loop when the monitor is stopped', () => {
+    track.startMonitor();
+    // the listener stays subscribed, so only the cancellation can stop the loop
+    track.on(TrackEvent.TimeSyncUpdate, vi.fn());
+    vi.advanceTimersToNextFrame();
+    expect(getSynchronizationSources).toHaveBeenCalled();
+
+    track.stopMonitor();
+    getSynchronizationSources.mockClear();
+    vi.advanceTimersToNextFrame();
+    vi.advanceTimersToNextFrame();
+
+    expect(getSynchronizationSources).not.toHaveBeenCalled();
+  });
+
+  it('resumes the loop when the monitor is started again after a stop', () => {
+    track.startMonitor();
+    track.on(TrackEvent.TimeSyncUpdate, vi.fn());
+    vi.advanceTimersToNextFrame();
+    track.stopMonitor();
+    getSynchronizationSources.mockClear();
+
+    track.startMonitor();
+    vi.advanceTimersToNextFrame();
+
+    expect(getSynchronizationSources).toHaveBeenCalled();
+  });
+
+  it('does not restart the loop after the monitor has been stopped', () => {
+    track.startMonitor();
+    track.stopMonitor();
+
+    track.on(TrackEvent.TimeSyncUpdate, vi.fn());
+    vi.advanceTimersToNextFrame();
+
+    expect(getSynchronizationSources).not.toHaveBeenCalled();
+  });
+});

package/src/room/track/RemoteTrack.ts

@@ -1,3 +1,4 @@
+import type { EventEmitter } from 'events';
 import { TrackEvent } from '../events';
 import { monitorFrequency } from '../stats';
 import type { LoggerOptions } from '../types';
@@ -123,20 +124,46 @@ export default abstract class RemoteTrack<
     }
   }
 
+  /* @internal */
+  stopMonitor() {
+    super.stopMonitor();
+    (this as unknown as EventEmitter).off('newListener', this.onTimeSyncListenerAdded);
+  }
+
   protected abstract monitorReceiver(): void;
 
-  registerTimeSyncUpdate() {
-    const loop = () => {
-      this.timeSyncHandle = requestAnimationFrame(() => loop());
-      const sources = this.receiver?.getSynchronizationSources()[0];
-      if (sources) {
-        const { timestamp, rtpTimestamp } = sources;
-        if (rtpTimestamp && this.rtpTimestamp !== rtpTimestamp) {
-          this.emit(TrackEvent.TimeSyncUpdate, { timestamp, rtpTimestamp });
-          this.rtpTimestamp = rtpTimestamp;
-        }
+  private timeSyncLoop = () => {
+    if (this.listenerCount(TrackEvent.TimeSyncUpdate) === 0) {
+      // nobody is listening anymore, pause the loop until a new listener subscribes
+      this.timeSyncHandle = undefined;
+      return;
+    }
+    this.timeSyncHandle = requestAnimationFrame(this.timeSyncLoop);
+    const sources = this.receiver?.getSynchronizationSources()[0];
+    if (sources) {
+      const { timestamp, rtpTimestamp } = sources;
+      if (rtpTimestamp && this.rtpTimestamp !== rtpTimestamp) {
+        this.emit(TrackEvent.TimeSyncUpdate, { timestamp, rtpTimestamp });
+        this.rtpTimestamp = rtpTimestamp;
       }
-    };
-    loop();
+    }
+  };
+
+  private onTimeSyncListenerAdded = (event: string) => {
+    if (event === TrackEvent.TimeSyncUpdate && this.timeSyncHandle === undefined) {
+      // `newListener` fires before the listener is registered, so schedule the
+      // next frame instead of entering the loop (which would see a count of 0)
+      this.timeSyncHandle = requestAnimationFrame(this.timeSyncLoop);
+    }
+  };
+
+  registerTimeSyncUpdate() {
+    // `newListener` isn't part of the typed event map, hence the cast
+    const emitter = this as unknown as EventEmitter;
+    emitter.off('newListener', this.onTimeSyncListenerAdded);
+    emitter.on('newListener', this.onTimeSyncListenerAdded);
+    if (this.timeSyncHandle === undefined) {
+      this.timeSyncLoop();
+    }
   }
 }

package/src/room/track/Track.ts

@@ -276,8 +276,9 @@ export abstract class Track<
     if (this.monitorInterval) {
       clearInterval(this.monitorInterval);
     }
-    if (this.timeSyncHandle) {
+    if (this.timeSyncHandle !== undefined) {
       cancelAnimationFrame(this.timeSyncHandle);
+      this.timeSyncHandle = undefined;
     }
   }
 

package/src/room/utils.test.ts

@@ -1,6 +1,13 @@
 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 {
+  ddExtensionURI,
+  extractMaxAgeFromRequestHeaders,
+  getClientInfo,
+  negotiateDependencyDescriptor,
+  splitUtf8,
+  toWebsocketUrl,
+} from './utils';
 
 describe('toWebsocketUrl', () => {
   it('leaves wss urls alone', () => {
@@ -188,3 +195,65 @@ describe('extractMaxAgeFromRequestHeaders', () => {
     expect(extractMaxAgeFromRequestHeaders(headers)).toBe(3600);
   });
 });
+
+describe('negotiateDependencyDescriptor', () => {
+  /** A transceiver whose header extension control offers `extensions`, or none at all. */
+  const transceiverWith = (extensions?: RTCRtpHeaderExtensionCapability[], throws = false) => {
+    const set = vi.fn((updated: RTCRtpHeaderExtensionCapability[]) => {
+      if (throws) {
+        throw new Error('InvalidModificationError');
+      }
+      extensions = updated;
+    });
+    return {
+      transceiver: (extensions
+        ? {
+            getHeaderExtensionsToNegotiate: () => extensions!,
+            setHeaderExtensionsToNegotiate: set,
+          }
+        : {}) as unknown as RTCRtpTransceiver,
+      set,
+      current: () => extensions,
+    };
+  };
+
+  it('turns the extension on for a transceiver that has it stopped', () => {
+    const { transceiver, set, current } = transceiverWith([
+      { uri: 'urn:ietf:params:rtp-hdrext:sdes:mid', direction: 'sendrecv' },
+      { uri: ddExtensionURI, direction: 'stopped' },
+    ]);
+
+    expect(negotiateDependencyDescriptor(transceiver)).toBe(true);
+    expect(set).toHaveBeenCalledOnce();
+    // sendrecv keeps it a plain a=extmap line, with no direction suffix for the server to parse
+    expect(current()?.find((ext) => ext.uri === ddExtensionURI)?.direction).toBe('sendrecv');
+  });
+
+  it('leaves an extension the browser already negotiates alone', () => {
+    const { transceiver, set } = transceiverWith([{ uri: ddExtensionURI, direction: 'recvonly' }]);
+
+    expect(negotiateDependencyDescriptor(transceiver)).toBe(true);
+    expect(set).not.toHaveBeenCalled();
+  });
+
+  it('reports no negotiation where the browser does not know the extension', () => {
+    const { transceiver, set } = transceiverWith([
+      { uri: 'urn:ietf:params:rtp-hdrext:sdes:mid', direction: 'sendrecv' },
+    ]);
+
+    expect(negotiateDependencyDescriptor(transceiver)).toBe(false);
+    expect(set).not.toHaveBeenCalled();
+  });
+
+  it('reports no negotiation where the browser has no such control', () => {
+    const { transceiver } = transceiverWith();
+
+    expect(negotiateDependencyDescriptor(transceiver)).toBe(false);
+  });
+
+  it('swallows a rejected direction rather than failing the connection', () => {
+    const { transceiver } = transceiverWith([{ uri: ddExtensionURI, direction: 'stopped' }], true);
+
+    expect(negotiateDependencyDescriptor(transceiver)).toBe(false);
+  });
+});

package/src/room/utils.ts

@@ -146,6 +146,45 @@ export function isSVCCodec(codec?: string): boolean {
   return codec === 'av1' || codec === 'vp9';
 }
 
+/**
+ * Opts `transceiver` into negotiating the AV1 dependency descriptor, reporting whether it will be.
+ *
+ * Chrome only offers the extension on transceivers that can send, so one we create to receive on
+ * never negotiates it — and Chrome 152 stopped decoding AV1 that arrives without it: frames get
+ * assembled, none ever decode, and the receiver asks for a keyframe forever. Asking through the
+ * transceiver rather than munging the extension into the SDP leaves the browser owning the
+ * extension id, which is what keeps that id consistent across the bundle and across
+ * renegotiations.
+ *
+ * A no-op where the browser offers no such control, or does not know the extension at all.
+ * @internal
+ */
+export function negotiateDependencyDescriptor(transceiver: RTCRtpTransceiver): boolean {
+  const extensions = transceiver.getHeaderExtensionsToNegotiate?.();
+  if (!extensions || !transceiver.setHeaderExtensionsToNegotiate) {
+    return false;
+  }
+  const dd = extensions.find((ext) => ext.uri === ddExtensionURI);
+  if (!dd) {
+    return false;
+  }
+  if (dd.direction !== 'stopped') {
+    return true;
+  }
+  // sendrecv rather than recvonly, so that the extension is written as a plain `a=extmap` line —
+  // the form the server already emits where it is the one offering — rather than one carrying a
+  // `/recvonly` suffix that its parser may not expect
+  dd.direction = 'sendrecv';
+  try {
+    transceiver.setHeaderExtensionsToNegotiate(extensions);
+    return true;
+  } catch (e) {
+    // a rejected direction throws. Negotiating without the extension is what happened before this
+    // existed, so it is not worth failing the connection over
+    return false;
+  }
+}
+
 export function supportsSetSinkId(elm?: HTMLMediaElement): boolean {
   if (!document || isSafariBased()) {
     return false;
@@ -867,3 +906,16 @@ export function isPublisherOfferWithJoinSupported() {
   // we have connectivity issue about publisher offer with join on firefox #1919
   return isCompressionStreamSupported() && !isFireFox();
 }
+
+export function extractTrackSid(
+  mediaTrack: MediaStreamTrack,
+  stream: MediaStream,
+): Track.SID | undefined {
+  const [, streamId] = unpackStreamId(stream.id);
+  if (streamId?.startsWith('TR')) {
+    return streamId;
+  }
+  if (mediaTrack.id.startsWith('TR')) {
+    return mediaTrack.id;
+  }
+}

package/src/test/promiseState.ts

@@ -0,0 +1,23 @@
+/**
+ * Test helper: resolves `true` if `promise` is still pending after `ms`
+ * (default: one macrotask), `false` if it has already settled — regardless of
+ * whether it resolved or rejected.
+ *
+ * Use to assert that something has *not* happened yet (e.g. an onClose callback
+ * that must stay silent), optionally within a timeout window. Preferable to
+ * `Promise.race([p, Promise.resolve(sentinel)])` when the "not yet" needs to
+ * hold for a duration rather than just the current microtask.
+ */
+export async function isPending(promise: Promise<unknown>, ms = 0): Promise<boolean> {
+  const pending = Symbol('pending');
+  // Swallow settlement (incl. rejection) so racing it can't raise unhandled
+  // rejections when the timer wins.
+  const settled = promise.then(
+    () => 'settled' as const,
+    () => 'settled' as const,
+  );
+  const timer = new Promise<typeof pending>((resolve) => {
+    setTimeout(() => resolve(pending), ms);
+  });
+  return (await Promise.race([settled, timer])) === pending;
+}

package/src/test/signalServerSetup.ts

@@ -2,6 +2,7 @@ import { type ChildProcess, execFileSync, spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { Socket, createServer } from 'node:net';
 import { join } from 'node:path';
+import { sleep } from '../room/utils';
 import { createToken } from './signalToken';
 
 /**
@@ -47,7 +48,7 @@ async function waitReady(serverUrl: string): Promise<boolean> {
     } catch {
       // not up yet
     }
-    await new Promise((r) => setTimeout(r, 200));
+    await sleep(200);
   }
   return false;
 }