livekit-client 2.22.4 → 2.23.0

package/src/e2ee/worker/FrameCryptor.ts

@@ -25,7 +25,7 @@ import type {
 import { deriveKeys, isVideoFrame, needsRbspUnescaping, parseRbsp, writeRbsp } from '../utils';
 import { ErrorRateLimiter } from './ErrorRateLimiter';
 import type { ParticipantKeyHandler } from './ParticipantKeyHandler';
-import { processNALUsForEncryption } from './naluUtils';
+import { normalizeAnnexBStartCodes, processNALUsForEncryption } from './naluUtils';
 import { identifySifPayload } from './sifPayload';
 
 export const encryptionEnabledMap: Map<string, boolean> = new Map();
@@ -490,7 +490,16 @@ export class FrameCryptor extends BaseFrameCryptor {
       let frameInfo = this.getUnencryptedBytes(encodedFrame);
 
       // Thіs is not encrypted and contains the VP8 payload descriptor or the Opus TOC byte.
-      const frameHeader = new Uint8Array(encodedFrame.data, 0, frameInfo.unencryptedBytes);
+      let frameHeader: NonSharedUint8Array = new Uint8Array(
+        encodedFrame.data,
+        0,
+        frameInfo.unencryptedBytes,
+      );
+      if (frameInfo.requiresNALUProcessing) {
+        // The receiver's depacketizer rebuilds NALUs with 4-byte start codes, so authenticate (and
+        // send) the header in that form or decryption fails for encoders emitting 3-byte ones.
+        frameHeader = normalizeAnnexBStartCodes(frameHeader);
+      }
 
       // Frame trailer contains the R|IV_LENGTH and key index
       const frameTrailer = new Uint8Array(2);
@@ -510,7 +519,7 @@ export class FrameCryptor extends BaseFrameCryptor {
           {
             name: ENCRYPTION_ALGORITHM,
             iv,
-            additionalData: new Uint8Array(encodedFrame.data, 0, frameHeader.byteLength),
+            additionalData: frameHeader,
           },
           encryptionKey,
           new Uint8Array(encodedFrame.data, frameInfo.unencryptedBytes),
@@ -906,7 +915,7 @@ export class FrameCryptor extends BaseFrameCryptor {
         };
       }
     } catch (e) {
-      this.logNALUFallbackOnce(fallbackKey, payloadType, e);
+      this.logNALUFallbackOnce(fallbackKey, frame, payloadType, detectedCodec, e);
     }
 
     // Fallback to VP8 handling
@@ -919,7 +928,9 @@ export class FrameCryptor extends BaseFrameCryptor {
    */
   private logNALUFallbackOnce(
     fallbackKey: string,
+    frame: RTCEncodedVideoFrame,
     payloadType: number | undefined,
+    detectedCodec: VideoCodec | undefined,
     error: unknown,
   ) {
     if (this.loggedNALUFallbacks.has(fallbackKey)) {
@@ -929,6 +940,12 @@ export class FrameCryptor extends BaseFrameCryptor {
     workerLogger.warn('NALU processing failed, falling back to VP8 handling', {
       error,
       payloadType,
+      detectedCodec,
+      frameType: frame.type,
+      byteLength: frame.data.byteLength,
+      firstBytes: Array.from(new Uint8Array(frame.data, 0, Math.min(16, frame.data.byteLength)))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join(' '),
       ...this.logContext,
     });
   }

package/src/e2ee/worker/naluUtils.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeAnnexBStartCodes, processNALUsForEncryption } from './naluUtils';
+
+/** Annex-B frame: a 4-byte start code before every NALU. */
+function annexB(...nalus: number[][]) {
+  return Uint8Array.from(nalus.flatMap((nalu) => [0x00, 0x00, 0x00, 0x01, ...nalu]));
+}
+
+// h264: 0x06 SEI, 0x65 IDR slice, 0x67 SPS. h265: 0x26 IDR_W_RADL slice.
+// An h264 SEI byte (0x06) reads as h265 TSA_R, which is why the SEI leads here.
+// findNALUIndices stops at stream.length - 3. A trailing NALU with fewer than 4 payload
+// bytes is never indexed, so its fixture tests nothing. Interior NALUs are fine at any
+// length, because the next start code ends them.
+const h264KeyFrame = annexB([0x06, 0x11, 0x22], [0x65, 0x33, 0x44, 0x55, 0x66]);
+const h265KeyFrame = annexB([0x26, 0x11, 0x22], [0x02, 0x33, 0x44, 0x55, 0x66]);
+const noSliceFrame = annexB([0x67, 0x11, 0x22, 0x33, 0x44, 0x55]);
+// 0x25 is a slice under both: h264 &0x1f = 5 IDR, h265 (b >> 1) & 0x3f = 18 BLA_W_RADL.
+const ambiguousFrame = annexB([0x25, 0x11, 0x22, 0x33, 0x44, 0x55]);
+
+describe('normalizeAnnexBStartCodes', () => {
+  it('rewrites 3-byte start codes to 4-byte start codes', () => {
+    // prettier-ignore
+    const input = new Uint8Array([
+      0x00, 0x00, 0x01, 0x67, 0x64, // SPS
+      0x00, 0x00, 0x01, 0x68, 0xee, // PPS
+      0x00, 0x00, 0x01, 0x65, 0x88, // IDR slice
+    ]);
+    // prettier-ignore
+    const expected = new Uint8Array([
+      0x00, 0x00, 0x00, 0x01, 0x67, 0x64,
+      0x00, 0x00, 0x00, 0x01, 0x68, 0xee,
+      0x00, 0x00, 0x00, 0x01, 0x65, 0x88,
+    ]);
+
+    expect(normalizeAnnexBStartCodes(input)).toEqual(expected);
+  });
+
+  it('rewrites only the 3-byte start codes when mixed with 4-byte ones', () => {
+    // prettier-ignore
+    const input = new Uint8Array([
+      0x00, 0x00, 0x00, 0x01, 0x67, 0x64,
+      0x00, 0x00, 0x01, 0x68, 0xee,
+      0x00, 0x00, 0x00, 0x01, 0x06, 0x05,
+      0x00, 0x00, 0x01, 0x65, 0x88,
+    ]);
+    // prettier-ignore
+    const expected = new Uint8Array([
+      0x00, 0x00, 0x00, 0x01, 0x67, 0x64,
+      0x00, 0x00, 0x00, 0x01, 0x68, 0xee,
+      0x00, 0x00, 0x00, 0x01, 0x06, 0x05,
+      0x00, 0x00, 0x00, 0x01, 0x65, 0x88,
+    ]);
+
+    expect(normalizeAnnexBStartCodes(input)).toEqual(expected);
+  });
+
+  it('returns the same instance when all start codes are already 4-byte', () => {
+    // prettier-ignore
+    const input = new Uint8Array([
+      0x00, 0x00, 0x00, 0x01, 0x67, 0x64,
+      0x00, 0x00, 0x00, 0x01, 0x65, 0x88,
+    ]);
+
+    expect(normalizeAnnexBStartCodes(input)).toBe(input);
+  });
+
+  it('does not add a zero when a start code already has extra leading zeros', () => {
+    const input = new Uint8Array([0x00, 0x00, 0x00, 0x00, 0x01, 0x65, 0x88]);
+
+    expect(normalizeAnnexBStartCodes(input)).toBe(input);
+  });
+});
+
+describe('processNALUsForEncryption', () => {
+  it('slices at the h264 slice NALU even when seeded with h265', () => {
+    // The whole point: the h265 seed must not win, or the offset lands at 6 (inside the
+    // SEI) and the slice header gets encrypted with no error raised.
+    expect(processNALUsForEncryption(h264KeyFrame, 'h265')).toEqual({
+      unencryptedBytes: 13,
+      detectedCodec: 'h264',
+      requiresNALUProcessing: true,
+    });
+  });
+
+  it('reads an h264 frame whose SEI precedes the slice as h264', () => {
+    expect(processNALUsForEncryption(h264KeyFrame)).toEqual({
+      unencryptedBytes: 13,
+      detectedCodec: 'h264',
+      requiresNALUProcessing: true,
+    });
+  });
+
+  it('still reads an h265 frame as h265', () => {
+    expect(processNALUsForEncryption(h265KeyFrame)).toEqual({
+      unencryptedBytes: 6,
+      detectedCodec: 'h265',
+      requiresNALUProcessing: true,
+    });
+    expect(processNALUsForEncryption(h265KeyFrame, 'h264')).toEqual({
+      unencryptedBytes: 6,
+      detectedCodec: 'h265',
+      requiresNALUProcessing: true,
+    });
+  });
+
+  it('resolves a byte that is a slice under both codecs as h264', () => {
+    // Only the h264-first ordering decides this one. Swap the two loops back and it reads h265.
+    expect(processNALUsForEncryption(ambiguousFrame)).toEqual({
+      unencryptedBytes: 6,
+      detectedCodec: 'h264',
+      requiresNALUProcessing: true,
+    });
+  });
+
+  it('throws with a seed, and returns quietly without one, when no slice NALU is present', () => {
+    expect(() => processNALUsForEncryption(noSliceFrame, 'h264')).toThrow('Could not find NALU');
+    expect(processNALUsForEncryption(noSliceFrame)).toEqual({
+      unencryptedBytes: 0,
+      detectedCodec: 'unknown',
+      requiresNALUProcessing: false,
+    });
+  });
+});

package/src/e2ee/worker/naluUtils.ts

@@ -202,8 +202,14 @@ export interface NALUProcessingResult {
  * @returns Detected codec type
  */
 function detectCodecFromNALUs(data: NonSharedUint8Array, naluIndices: number[]): DetectedCodec {
+  // h264 runs to completion first. Several non-slice h264 NALUs read as h265 slice types
+  // (AUD 0x09 -> STSA_N, SEI 0x06 -> TSA_R), so interleaving the two checks lets one of
+  // those outrank the real h264 slice that follows it. The reverse cannot happen: h265
+  // header bytes are even at nuh_layer_id 0, so they never mask to an h264 slice type.
   for (const naluIndex of naluIndices) {
     if (isH264SliceNALU(parseH264NALUType(data[naluIndex]))) return 'h264';
+  }
+  for (const naluIndex of naluIndices) {
     if (isH265SliceNALU(parseH265NALUType(data[naluIndex]))) return 'h265';
   }
   return 'unknown';
@@ -306,7 +312,7 @@ function findNALUIndices(stream: NonSharedUint8Array): number[] {
 /**
  * Process NALU data for frame encryption, detecting codec and finding unencrypted bytes
  * @param data Frame data
- * @param knownCodec Known codec from other sources (optional)
+ * @param knownCodec Codec from other sources, used only when the bytes are inconclusive (optional)
  * @returns NALU processing result
  */
 export function processNALUsForEncryption(
@@ -314,7 +320,16 @@ export function processNALUsForEncryption(
   knownCodec?: 'h264' | 'h265',
 ): NALUProcessingResult {
   const naluIndices = findNALUIndices(data);
-  const detectedCodec = knownCodec ?? detectCodecFromNALUs(data, naluIndices);
+  // The bytes outrank knownCodec, which can be the codec the client asked for rather than the
+  // one that was negotiated. Parsing the wrong one mis-slices without raising anything: the
+  // offset lands before the real slice header, so the header itself gets encrypted.
+  // That holds in one direction only. An h264 access unit carrying no slice NALU but carrying
+  // an AUD or SEI that reads as an h265 slice now slices there instead of throwing. No real
+  // WebRTC access unit can reach it, because every one of them carries a type 1 or 5 slice.
+  let detectedCodec = detectCodecFromNALUs(data, naluIndices);
+  if (detectedCodec === 'unknown') {
+    detectedCodec = knownCodec ?? 'unknown';
+  }
 
   if (detectedCodec === 'unknown') {
     return { unencryptedBytes: 0, detectedCodec, requiresNALUProcessing: false };
@@ -327,3 +342,43 @@ export function processNALUsForEncryption(
 
   return { unencryptedBytes, detectedCodec, requiresNALUProcessing: true };
 }
+
+/**
+ * Rewrite every 3-byte Annex B start code (00 00 01) in `data` to the 4-byte form (00 00 00 01).
+ *
+ * WebRTC's H.264/H.265 depacketizer always reconstructs NALUs with 4-byte start codes, regardless
+ * of what the encoder emitted. Some encoders (e.g. Intel Quick Sync) emit 3-byte start codes, so
+ * the unencrypted header a receiver sees would differ from what the sender authenticated as
+ * AES-GCM additionalData. Normalizing on the sender makes both sides agree.
+ *
+ * Returns `data` unchanged (same instance) when it contains no 3-byte start codes.
+ */
+export function normalizeAnnexBStartCodes(data: NonSharedUint8Array): NonSharedUint8Array {
+  const shortStartCodes: number[] = [];
+  for (let i = 0; i + 2 < data.length;) {
+    if (data[i + 2] === 0) {
+      i += 1;
+      continue;
+    }
+    if (data[i + 2] === 1 && data[i] === 0 && data[i + 1] === 0 && (i === 0 || data[i - 1] !== 0)) {
+      shortStartCodes.push(i);
+    }
+    // data[i + 2] is non-zero, so no start code can begin at i + 1 or i + 2 either.
+    i += 3;
+  }
+  if (shortStartCodes.length === 0) {
+    return data;
+  }
+
+  // The new array is zero-filled, so the one-byte gap left before each short start code becomes
+  // the inserted leading 00.
+  const result = new Uint8Array(data.length + shortStartCodes.length);
+  let from = 0;
+  for (let inserted = 0; inserted < shortStartCodes.length; inserted++) {
+    const to = shortStartCodes[inserted];
+    result.set(data.subarray(from, to), from + inserted);
+    from = to;
+  }
+  result.set(data.subarray(from), from + shortStartCodes.length);
+  return result;
+}

package/src/index.ts

@@ -56,6 +56,7 @@ import {
   isSVCCodec,
   isVideoCodec,
   isVideoTrack,
+  releaseEmptyAudioStreamTrack,
   supportsAV1,
   supportsAdaptiveStream,
   supportsAudioOutputSelection,
@@ -145,6 +146,7 @@ export {
   getEmptyVideoStreamTrack,
   getLogger,
   isBrowserSupported,
+  releaseEmptyAudioStreamTrack,
   setLogExtension,
   setLogLevel,
   supportsAV1,

package/src/room/DefaultReconnectPolicy.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import DefaultReconnectPolicy from './DefaultReconnectPolicy';
+
+const delayFor = (policy: DefaultReconnectPolicy, retryCount: number, random: number) => {
+  vi.spyOn(Math, 'random').mockReturnValue(random);
+  return policy.nextRetryDelayInMs({ retryCount, elapsedMs: 0 });
+};
+
+describe('DefaultReconnectPolicy', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('spreads the first retry over a window instead of retrying immediately', () => {
+    const policy = new DefaultReconnectPolicy();
+    expect(delayFor(policy, 0, 0)).toBe(0);
+    expect(delayFor(policy, 0, 0.5)).toBe(250);
+    expect(delayFor(policy, 0, 0.999)).toBeGreaterThan(450);
+    expect(delayFor(policy, 0, 0.999)).toBeLessThan(500);
+  });
+
+  it('scales the jitter of later retries with the delay', () => {
+    const policy = new DefaultReconnectPolicy();
+    expect(delayFor(policy, 1, 0)).toBe(150);
+    expect(delayFor(policy, 1, 0.5)).toBe(300);
+    expect(delayFor(policy, 2, 0)).toBe(600);
+    expect(delayFor(policy, 2, 0.5)).toBe(1200);
+    expect(delayFor(policy, 9, 0)).toBe(3500);
+    expect(delayFor(policy, 9, 0.999)).toBeLessThan(10500);
+  });
+
+  it('returns a different delay for each client on every retry', () => {
+    const policy = new DefaultReconnectPolicy();
+    for (let retryCount = 0; retryCount < 10; retryCount++) {
+      expect(delayFor(policy, retryCount, 0.1)).not.toBe(delayFor(policy, retryCount, 0.9));
+    }
+  });
+
+  it('returns null once the retries are exhausted', () => {
+    const policy = new DefaultReconnectPolicy([0, 100]);
+    expect(policy.nextRetryDelayInMs({ retryCount: 2, elapsedMs: 0 })).toBeNull();
+    expect(
+      new DefaultReconnectPolicy().nextRetryDelayInMs({ retryCount: 10, elapsedMs: 0 }),
+    ).toBeNull();
+  });
+
+  it('applies jitter to custom delays', () => {
+    const policy = new DefaultReconnectPolicy([1000]);
+    expect(delayFor(policy, 0, 0.5)).toBe(1000);
+    expect(delayFor(policy, 0, 0)).toBe(500);
+  });
+
+  it('keeps a zero delay at a later index immediate', () => {
+    const policy = new DefaultReconnectPolicy([100, 0]);
+    expect(delayFor(policy, 1, 0.5)).toBe(0);
+    expect(delayFor(policy, 1, 0.999)).toBe(0);
+  });
+});

package/src/room/DefaultReconnectPolicy.ts

@@ -2,6 +2,12 @@ import type { ReconnectContext, ReconnectPolicy } from './ReconnectPolicy';
 
 const maxRetryDelay = 7000;
 
+/**
+ * Upper bound of the random delay added to the first retry, whose base delay is 0. It keeps a
+ * brief network blip recovering quickly while spreading out clients that disconnect together.
+ */
+const maxFirstRetryJitterInMs = 500;
+
 const DEFAULT_RETRY_DELAYS_IN_MS = [
   0,
   300,
@@ -26,9 +32,15 @@ class DefaultReconnectPolicy implements ReconnectPolicy {
     if (context.retryCount >= this._retryDelays.length) return null;
 
     const retryDelay = this._retryDelays[context.retryCount];
-    if (context.retryCount <= 1) return retryDelay;
 
-    return retryDelay + Math.random() * 1_000;
+    // The first retry has no base delay to scale, so it gets a fixed window instead. A zero at a
+    // later index is an explicit request for an immediate retry and passes through the formula as zero.
+    if (context.retryCount === 0 && retryDelay === 0) {
+      return Math.random() * maxFirstRetryJitterInMs;
+    }
+
+    // Jitter scales with the delay (+/-50%) so clients spread out further on later retries.
+    return Math.round(retryDelay * (0.5 + Math.random()));
   }
 }
 

package/src/room/PCTransport.test.ts

@@ -1,6 +1,6 @@
 import { type MediaDescription, parse } from 'sdp-transform';
-import { describe, expect, it } from 'vitest';
-import {
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import PCTransport, {
   applyVideoStartBitrate,
   computeConnectionStartBitrate,
   computeTrackStartBitrate,
@@ -156,6 +156,148 @@ describe('video start bitrate', () => {
     expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 300 })).toBe(270);
   });
 
+  it('ramps the cap down with connection setup time', () => {
+    // A 3 Mbps camera target, so only the cap moves.
+    const camera = (ms: number) =>
+      computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 3_000 }, ms);
+
+    expect(camera(0)).toBe(1_000);
+    expect(camera(471)).toBe(1_000); // unshaped baseline
+    expect(camera(1_273)).toBe(1_000); // 1 Mbps link median
+    expect(camera(1_500)).toBe(1_000); // the fast anchor
+    expect(camera(1_724)).toBe(922); // 1 Mbps link slow attempt
+    expect(camera(2_334)).toBe(708); // 500 kbps link median
+    expect(camera(2_500)).toBe(650); // midpoint of the ramp
+    expect(camera(3_093)).toBe(442); // 300 kbps link fastest attempt
+    expect(camera(3_500)).toBe(300); // the slow anchor
+    expect(camera(18_131)).toBe(300); // anything slower stays at the floor
+  });
+
+  it('keeps the 1 Mbps ceiling without a setup time', () => {
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 3_000 }, undefined)).toBe(
+      1_000,
+    );
+  });
+
+  it('still applies 90% of the target under the ramp, and hints at the floor', () => {
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 500 }, 2_500)).toBe(450);
+    expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 300 }, 3_500)).toBe(270);
+  });
+
+  it('leaves screen share uncapped however slow the setup', () => {
+    const screenShare = (ms: number) =>
+      computeTrackStartBitrate({ cid: 's', codec: 'VP8', maxbr: 3_000, isScreenShare: true }, ms);
+
+    expect(screenShare(1_273)).toBe(2_700);
+    expect(screenShare(2_500)).toBe(2_700);
+    expect(screenShare(4_061)).toBe(2_700);
+  });
+
+  it('applies the setup time to the connection-level value', () => {
+    const { media } = parse(TWO_VIDEO_SECTIONS);
+    const camera = { cid: 'camera-cid', codec: 'VP8', maxbr: 3_000 };
+    const screenShare = { cid: 'other-track', codec: 'VP8', maxbr: 3_000, isScreenShare: true };
+
+    expect(computeConnectionStartBitrate(media, [camera], 1_000)).toBe(1_000);
+    expect(computeConnectionStartBitrate(media, [camera], 2_500)).toBe(650);
+    // The uncapped screen share still wins the connection-level max on a slow setup.
+    expect(computeConnectionStartBitrate(media, [camera, screenShare], 2_500)).toBe(2_700);
+  });
+
+  describe('browser effective connection type', () => {
+    const withEffectiveType = (effectiveType: string | undefined) =>
+      vi.stubGlobal('navigator', { connection: effectiveType ? { effectiveType } : undefined });
+
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    // A 3 Mbps camera target, so only the cap moves.
+    const camera = (setupTimeMs?: number) =>
+      computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 3_000 }, setupTimeMs);
+
+    it('caps 2g and slow-2g at 300 kbps and 3g at 500 kbps', () => {
+      withEffectiveType('slow-2g');
+      expect(camera(500)).toBe(300);
+      withEffectiveType('2g');
+      expect(camera(500)).toBe(300);
+      withEffectiveType('3g');
+      expect(camera(500)).toBe(500);
+    });
+
+    it('gives no cap for 4g or without the API', () => {
+      withEffectiveType('4g');
+      expect(camera(500)).toBe(1_000);
+      withEffectiveType(undefined);
+      expect(camera(500)).toBe(1_000);
+      vi.stubGlobal('navigator', undefined);
+      expect(camera(500)).toBe(1_000);
+    });
+
+    it('takes the lower of the setup time cap and the effective type cap', () => {
+      withEffectiveType('3g');
+      expect(camera(2_500)).toBe(500); // setup time alone allows 650
+      expect(camera(3_093)).toBe(442); // setup time is lower
+      expect(camera()).toBe(500);
+    });
+
+    it('still applies 90% of a target below the cap', () => {
+      withEffectiveType('3g');
+      expect(computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 450 }, 500)).toBe(405);
+    });
+
+    it('leaves screen share uncapped', () => {
+      withEffectiveType('slow-2g');
+      expect(
+        computeTrackStartBitrate(
+          { cid: 's', codec: 'VP8', maxbr: 3_000, isScreenShare: true },
+          500,
+        ),
+      ).toBe(2_700);
+    });
+  });
+
+  describe('connection setup time while still connecting', () => {
+    beforeEach(() => {
+      // The constructor creates its peer connection eagerly; only its event handlers are set.
+      vi.stubGlobal('RTCPeerConnection', class {});
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+      vi.unstubAllGlobals();
+    });
+
+    const estimate = (transport: PCTransport) =>
+      (
+        transport as unknown as { connectionSetupTimeEstimateMs(): number | undefined }
+      ).connectionSetupTimeEstimateMs();
+
+    it('uses the time elapsed since the join started before the setup time is measured', () => {
+      const transport = new PCTransport();
+      vi.spyOn(performance, 'now').mockReturnValue(10_000);
+      transport.setConnectionStartedAt(7_500);
+
+      expect(estimate(transport)).toBe(2_500);
+      expect(
+        computeTrackStartBitrate({ cid: 'c', codec: 'VP8', maxbr: 3_000 }, estimate(transport)),
+      ).toBe(650);
+    });
+
+    it('prefers the measured setup time once known', () => {
+      const transport = new PCTransport();
+      vi.spyOn(performance, 'now').mockReturnValue(10_000);
+      transport.setConnectionStartedAt(7_500);
+      transport.setConnectionSetupTime(3_600);
+
+      expect(estimate(transport)).toBe(3_600);
+    });
+
+    it('has no estimate without any timing', () => {
+      expect(estimate(new PCTransport())).toBeUndefined();
+    });
+  });
+
   it('uses one connection-level value: the largest hint across video sections', () => {
     const { media } = parse(TWO_VIDEO_SECTIONS);