livekit-client 2.22.2 → 2.22.4

package/src/room/utils.test.ts

@@ -1,13 +1,26 @@
 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,
+  isSVCSimulcast,
+  isSVCSimulcastSupportedByServer,
   negotiateDependencyDescriptor,
+  resetDeflateRawCompressionSupportCache,
   splitUtf8,
   supportsAdaptiveStream,
   toWebsocketUrl,
+  usesLegacySVCEncodings,
 } from './utils';
 
 describe('toWebsocketUrl', () => {
@@ -280,3 +293,201 @@ describe('supportsAdaptiveStream', () => {
     expect(supportsAdaptiveStream()).toBe(false);
   });
 });
+
+describe('isSVCSimulcast', () => {
+  it('requires an svc capable codec, simulcast and a single spatial layer mode', () => {
+    expect(isSVCSimulcast('vp9', { simulcast: true, scalabilityMode: 'L1T2' })).toBe(true);
+    expect(isSVCSimulcast('av1', { simulcast: true, scalabilityMode: 'L1T3' })).toBe(true);
+  });
+
+  it('stays on svc without the opt in', () => {
+    expect(isSVCSimulcast('vp9', { simulcast: false, scalabilityMode: 'L1T2' })).toBe(false);
+    expect(isSVCSimulcast('vp9', { simulcast: true })).toBe(false);
+    // a multi spatial layer mode is svc by definition
+    expect(isSVCSimulcast('vp9', { simulcast: true, scalabilityMode: 'L3T3_KEY' })).toBe(false);
+    expect(isSVCSimulcast('vp9', undefined)).toBe(false);
+  });
+
+  it('does not apply to non svc codecs', () => {
+    expect(isSVCSimulcast('vp8', { simulcast: true, scalabilityMode: 'L1T2' })).toBe(false);
+    expect(isSVCSimulcast('h264', { simulcast: true, scalabilityMode: 'L1T2' })).toBe(false);
+    expect(isSVCSimulcast(undefined, { simulcast: true, scalabilityMode: 'L1T2' })).toBe(false);
+  });
+});
+
+describe('isSVCSimulcastSupportedByServer', () => {
+  it('requires a server newer than 1.13.6', () => {
+    expect(isSVCSimulcastSupportedByServer('1.13.7')).toBe(true);
+    expect(isSVCSimulcastSupportedByServer('1.14.0')).toBe(true);
+    expect(isSVCSimulcastSupportedByServer('2.0.0')).toBe(true);
+  });
+
+  it('rejects 1.13.6 and older', () => {
+    expect(isSVCSimulcastSupportedByServer('1.13.6')).toBe(false);
+    expect(isSVCSimulcastSupportedByServer('1.13.5')).toBe(false);
+    expect(isSVCSimulcastSupportedByServer('1.9.0')).toBe(false);
+    expect(isSVCSimulcastSupportedByServer('0.15.1')).toBe(false);
+  });
+
+  it('treats an unknown version as unsupported', () => {
+    expect(isSVCSimulcastSupportedByServer(undefined)).toBe(false);
+    expect(isSVCSimulcastSupportedByServer('')).toBe(false);
+  });
+});
+
+describe('usesLegacySVCEncodings', () => {
+  const stubUserAgent = (userAgent: string) =>
+    vi.stubGlobal('navigator', { userAgent, product: 'Gecko' });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  const chrome = (v: string) =>
+    `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${v} Safari/537.36`;
+
+  it('is legacy on chrome before M113', () => {
+    stubUserAgent(chrome('112.0.0.0'));
+    expect(usesLegacySVCEncodings()).toBe(true);
+  });
+
+  it('is not legacy from chrome M113 onwards', () => {
+    stubUserAgent(chrome('113.0.0.0'));
+    expect(usesLegacySVCEncodings()).toBe(false);
+    stubUserAgent(chrome('120.0.0.0'));
+    expect(usesLegacySVCEncodings()).toBe(false);
+  });
+
+  it('is legacy on safari, which has no rid based svc simulcast', () => {
+    stubUserAgent(
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15',
+    );
+    expect(usesLegacySVCEncodings()).toBe(true);
+  });
+
+  it('is legacy on iOS, where every browser is webkit', () => {
+    stubUserAgent(
+      'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/120.0.0.0 Mobile/15E148 Safari/604.1',
+    );
+    expect(usesLegacySVCEncodings()).toBe(true);
+  });
+
+  it('is legacy on react native regardless of chrome version', () => {
+    vi.stubGlobal('navigator', { userAgent: chrome('120.0.0.0'), product: 'ReactNative' });
+    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;
+    }
+  });
+});

package/src/room/utils.ts

@@ -185,6 +185,65 @@ export function negotiateDependencyDescriptor(transceiver: RTCRtpTransceiver): b
   }
 }
 
+/**
+ * VP9 and AV1 are published as SVC (a single RTP stream carrying every spatial layer)
+ * by default. They can instead be published as real, rid based simulcast — one
+ * independent stream per rid, each carrying a single spatial layer — when the caller
+ * opts in with `simulcast: true` and a single spatial layer scalability mode (`L1Tx`).
+ *
+ * The SFU has to be told about this: without an explicit
+ * `SimulcastCodec.videoLayerMode` it assumes `MULTIPLE_SPATIAL_LAYERS_PER_STREAM` for
+ * any SVC capable codec.
+ */
+export function isSVCSimulcast(
+  codec?: string,
+  options?: { simulcast?: boolean; scalabilityMode?: string },
+): boolean {
+  return isSVCCodec(codec) && !!options?.simulcast && !!options.scalabilityMode?.startsWith('L1T');
+}
+
+/**
+ * Whether the browser reads multiple encodings on an SVC capable codec as *legacy SVC*
+ * rather than as real simulcast.
+ *
+ * Before Chrome M113, supplying more than one encoding for VP9/AV1 selected SVC mode;
+ * only from M113 does libwebrtc treat such encodings as simulcast, and only when each
+ * one carries its own scalabilityMode. Safari (and anything WebKit based, i. e. every
+ * browser on iOS) still uses the old interpretation, as does React Native's libwebrtc.
+ * Announced at https://groups.google.com/g/discuss-webrtc/c/-QQ3pxrl-fw
+ *
+ * Where this is true the rids would not exist on the wire, so VP9/AV1 must be published
+ * as SVC no matter what the caller asked for.
+ */
+export function usesLegacySVCEncodings(): boolean {
+  const browser = getBrowser();
+  return (
+    isSafariBased() ||
+    // Even tho RN runs M114, it does not produce SVC layers when a single encoding
+    // is provided. So we'll use the legacy SVC specification for now.
+    // TODO: when we upstream libwebrtc, this will need additional verification
+    isReactNative() ||
+    (browser?.name === 'Chrome' && compareVersions(browser.version, '113') < 0)
+  );
+}
+
+/**
+ * Last server version that doesn't support vp9/av1 simulcast.
+ */
+const svcSimulcastMinServerVersion = '1.13.6';
+
+/**
+ * Whether the connected server honours `SimulcastCodec.videoLayerMode`, i. e. whether
+ * VP9/AV1 can be published as rid based simulcast. An unknown version is treated as
+ * unsupported so the publish falls back to SVC.
+ */
+export function isSVCSimulcastSupportedByServer(serverVersion?: string): boolean {
+  if (!serverVersion) {
+    return false;
+  }
+  return compareVersions(serverVersion, svcSimulcastMinServerVersion) > 0;
+}
+
 export function supportsSetSinkId(elm?: HTMLMediaElement): boolean {
   if (!document || isSafariBased()) {
     return false;
@@ -241,6 +300,33 @@ export function isSafariBased(): boolean {
   return b?.name === 'Safari' || b?.os === 'iOS';
 }
 
+/**
+ * iPadOS has sent the desktop Macintosh user agent by default since iPadOS 13, so `getBrowser()`
+ * reports `os: 'macOS'` there and every `os === 'iOS'` check misses it. macOS Safari implements no
+ * touch events at all (`TouchEvent` undefined, `maxTouchPoints` 0) regardless of any touchscreen
+ * attached, so touch capability separates the two. Measured on an iPad 6 / iPadOS 17
+ * (`maxTouchPoints` 5) against macOS Safari 26.4 (`maxTouchPoints` 0).
+ *
+ * Deliberately a separate helper rather than a fix in `browserParser`: iPadOS spoofs the Mac
+ * version too, so reporting `os: 'iOS'` there would leave `osVersion` at `10.15.7` and silently
+ * break {@link isSafari17Based} and {@link isSafariSvcApi}, which compare it.
+ */
+export function isIPadOS(): boolean {
+  if (!isWeb()) {
+    return false;
+  }
+  const b = getBrowser();
+  return b?.name === 'Safari' && b?.os === 'macOS' && navigator.maxTouchPoints > 1;
+}
+
+/**
+ * iPhone, iPad and iOS-hosted browsers — everything running the Apple camera capture pipeline,
+ * including iPads that present themselves as a Mac.
+ */
+export function isAppleMobile(): boolean {
+  return getBrowser()?.os === 'iOS' || isIPadOS();
+}
+
 export function isSafari17Based(): boolean {
   const b = getBrowser();
   return (
@@ -902,6 +988,49 @@ export function isCompressionStreamSupported() {
   return typeof CompressionStream !== 'undefined';
 }
 
+let deflateRawCompressionSupported: boolean | null = null;
+
+/**
+ * Whether this runtime can compress AND decompress the `deflate-raw` format, which is a stricter
+ * requirement than {@link isCompressionStreamSupported}: Chromium 80-102 included
+ * `CompressionStream` supporting only `gzip` / `deflate`, and `deflate-raw` was added in Chromium
+ * 103 (Firefox 113, Safari 16.4).
+ */
+export function isDeflateRawCompressionSupported(): boolean {
+  if (typeof deflateRawCompressionSupported !== 'boolean') {
+    deflateRawCompressionSupported = probeDeflateRawCompressionSupport();
+  }
+  return deflateRawCompressionSupported;
+}
+
+function probeDeflateRawCompressionSupport(): boolean {
+  if (typeof CompressionStream === 'undefined' || typeof DecompressionStream === 'undefined') {
+    return false;
+  }
+  try {
+    // There is no api to query format support, and constructing with an unsupported format throws
+    // synchronously, so constructing one of each is the probe. Both are checked because the
+    // deflate-raw capability advertised to peers is as much about decompressing what they send us
+    // as it is about compressing what we send them.
+    new CompressionStream('deflate-raw');
+    new DecompressionStream('deflate-raw');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clears the memoized {@link isDeflateRawCompressionSupported} probe result. A runtime doesn't
+ * gain or lose compression formats while it is running, so this only exists for tests that swap
+ * the global `CompressionStream` / `DecompressionStream`.
+ *
+ * @internal
+ */
+export function resetDeflateRawCompressionSupportCache() {
+  deflateRawCompressionSupported = null;
+}
+
 export function isPublisherOfferWithJoinSupported() {
   // we have connectivity issue about publisher offer with join on firefox #1919
   return isCompressionStreamSupported() && !isFireFox();

package/src/test/compressionStreamStubs.ts

@@ -0,0 +1,53 @@
+import { resetDeflateRawCompressionSupportCache } from '../room/utils';
+
+/**
+ * Swaps the global `CompressionStream` / `DecompressionStream` away entirely, emulating a runtime
+ * that predates the compression streams api. Returns a function that restores them.
+ */
+export function stubMissingCompressionStreams(): () => void {
+  return stubCompressionStreams(undefined, undefined);
+}
+
+/**
+ * Swaps in global `CompressionStream` / `DecompressionStream` constructors that reject the
+ * `deflate-raw` format the way Chromium 80-102 does (the api exists, but only `gzip` / `deflate`
+ * are supported). Returns a function that restores the real ones.
+ */
+export function stubMissingDeflateRawSupport(): () => void {
+  return stubCompressionStreams(
+    legacyFormatsOnly('CompressionStream', CompressionStream),
+    legacyFormatsOnly('DecompressionStream', DecompressionStream),
+  );
+}
+
+type CompressionStreamCtor<T> = new (format: CompressionFormat) => T;
+
+function legacyFormatsOnly<T>(
+  name: string,
+  Real: CompressionStreamCtor<T>,
+): CompressionStreamCtor<T> {
+  return function LegacyCompressionStream(format: CompressionFormat) {
+    if (format === 'deflate-raw') {
+      throw new TypeError(
+        `Failed to construct '${name}': Unsupported compression format: 'deflate-raw'`,
+      );
+    }
+    return new Real(format);
+  } as unknown as CompressionStreamCtor<T>;
+}
+
+function stubCompressionStreams(compression: unknown, decompression: unknown): () => void {
+  const originalCompressionStream = globalThis.CompressionStream;
+  const originalDecompressionStream = globalThis.DecompressionStream;
+  (globalThis as any).CompressionStream = compression;
+  (globalThis as any).DecompressionStream = decompression;
+  // The support probe memoizes, which is only safe because a real runtime never changes formats
+  // mid-session; swapping the globals has to invalidate it.
+  resetDeflateRawCompressionSupportCache();
+
+  return () => {
+    (globalThis as any).CompressionStream = originalCompressionStream;
+    (globalThis as any).DecompressionStream = originalDecompressionStream;
+    resetDeflateRawCompressionSupportCache();
+  };
+}