livekit-client 2.19.2 → 2.20.0

package/src/{packetTrailer/PacketTrailerManager.ts → frameMetadata/FrameMetadataManager.ts}

@@ -2,13 +2,13 @@ import type { TrackInfo } from '@livekit/protocol';
 import log from '../logger';
 import type Room from '../room/Room';
 import { RoomEvent } from '../room/events';
-import { PacketTrailerExtractor } from '../room/track/PacketTrailerExtractor';
+import { FrameMetadataExtractor } from '../room/track/FrameMetadataExtractor';
 import type RemoteTrack from '../room/track/RemoteTrack';
 import RemoteVideoTrack from '../room/track/RemoteVideoTrack';
 import type { PTDecodeMessage, PTUpdateTrackIdMessage, PTWorkerMessage } from './types';
-import { isPacketTrailerSupported, shouldUsePacketTrailerScriptTransform } from './utils';
+import { isFrameMetadataSupported, shouldUseFrameMetadataScriptTransform } from './utils';
 
-export interface PacketTrailerOptions {
+export interface FrameMetadataOptions {
   /**
    * Dedicated worker for extracting packet trailers off the main thread.
    *
@@ -34,12 +34,12 @@ export interface PacketTrailerOptions {
  *
  * @experimental
  */
-export class PacketTrailerManager {
+export class FrameMetadataManager {
   private worker?: Worker;
 
   private room?: Room;
 
-  private extractors = new Map<string, PacketTrailerExtractor>();
+  private extractors = new Map<string, FrameMetadataExtractor>();
 
   /**
    * Tracks the trackId associated with each receiver that has had its
@@ -49,7 +49,7 @@ export class PacketTrailerManager {
    */
   private workerPipelines = new Map<RTCRtpReceiver, string>();
 
-  constructor(options?: PacketTrailerOptions) {
+  constructor(options?: FrameMetadataOptions) {
     this.worker = options?.worker;
   }
 
@@ -100,18 +100,18 @@ export class PacketTrailerManager {
     }
 
     if (
-      !isPacketTrailerSupported(this.worker ? { worker: this.worker } : undefined) &&
+      !isFrameMetadataSupported(this.worker ? { worker: this.worker } : undefined) &&
       !this.room?.hasE2EESetup
     ) {
-      log.warn('packet trailer transform not supported; skipping extraction');
+      log.warn('frame metadata transform not supported; skipping extraction');
       return;
     }
 
-    const extractor = new PacketTrailerExtractor();
+    const extractor = new FrameMetadataExtractor();
     const trackId = track.mediaStreamID;
 
     this.extractors.set(trackId, extractor);
-    track.packetTrailerExtractor = extractor;
+    track.frameMetadataExtractor = extractor;
 
     if (this.room?.hasE2EESetup) {
       // E2EE worker strips the trailer and injects metadata directly into
@@ -123,7 +123,7 @@ export class PacketTrailerManager {
   }
 
   private setupPassthroughReceiver(receiver: RTCRtpReceiver, trackId: string) {
-    if (shouldUsePacketTrailerScriptTransform()) {
+    if (shouldUseFrameMetadataScriptTransform()) {
       if ('transform' in receiver) {
         // @ts-ignore
         receiver.transform = null;
@@ -133,7 +133,7 @@ export class PacketTrailerManager {
 
     if (
       this.worker &&
-      isPacketTrailerSupported({ worker: this.worker }) &&
+      isFrameMetadataSupported({ worker: this.worker }) &&
       !this.workerPipelines.has(receiver)
     ) {
       this.setupWorkerReceiver(receiver, trackId, false);
@@ -155,7 +155,7 @@ export class PacketTrailerManager {
       return;
     }
 
-    if (shouldUsePacketTrailerScriptTransform()) {
+    if (shouldUseFrameMetadataScriptTransform()) {
       // @ts-ignore
       receiver.transform = new RTCRtpScriptTransform(worker, {
         kind: 'decode',
@@ -215,7 +215,7 @@ export class PacketTrailerManager {
     }
 
     if (track instanceof RemoteVideoTrack) {
-      track.packetTrailerExtractor = undefined;
+      track.frameMetadataExtractor = undefined;
     }
 
     // The receiver pipeline is intentionally left running. If the receiver is
@@ -245,6 +245,12 @@ export class PacketTrailerManager {
   };
 
   private onWorkerError = (ev: ErrorEvent) => {
-    log.error('packet trailer worker encountered an error:', { error: ev.error });
+    log.error('frame metadata worker encountered an error:', { error: ev.error });
   };
 }
+
+/** @deprecated Use {@link FrameMetadataManager} instead. */
+export const PacketTrailerManager = FrameMetadataManager;
+
+/** @deprecated Use {@link FrameMetadataOptions} instead. */
+export type PacketTrailerOptions = FrameMetadataOptions;

package/src/{packetTrailer/packetTrailer.test.ts → frameMetadata/frameMetadata.test.ts}

@@ -4,7 +4,7 @@ import {
   appendPacketTrailerToEncodedFrame,
   extractPacketTrailer,
   processPacketTrailer,
-} from './packetTrailer';
+} from './frameMetadata';
 
 describe('packetTrailer', () => {
   afterEach(() => {

package/src/{packetTrailer/packetTrailer.ts → frameMetadata/frameMetadata.ts}

@@ -1,5 +1,5 @@
-import type { PacketTrailerMetadata, PacketTrailerPublishOptions } from './types';
-import { hasPacketTrailerPublishOptions } from './utils';
+import type { FrameMetadata, FrameMetadataPublishOptions } from './types';
+import { hasFrameMetadataPublishOptions } from './utils';
 
 export const PACKET_TRAILER_MAGIC = Uint8Array.from([
   'L'.charCodeAt(0),
@@ -17,7 +17,7 @@ const FRAME_ID_TLV_SIZE = 6;
 
 export interface ExtractPacketTrailerResult {
   data: Uint8Array;
-  metadata?: PacketTrailerMetadata;
+  metadata?: FrameMetadata;
 }
 
 export function appendPacketTrailer(
@@ -64,10 +64,10 @@ export function appendPacketTrailer(
 
 export function appendPacketTrailerToEncodedFrame(
   frame: RTCEncodedVideoFrame,
-  options: PacketTrailerPublishOptions | undefined,
+  options: FrameMetadataPublishOptions | undefined,
   frameId: number,
 ): boolean {
-  if (!hasPacketTrailerPublishOptions(options) || frame.data.byteLength === 0) {
+  if (!hasFrameMetadataPublishOptions(options) || frame.data.byteLength === 0) {
     return false;
   }
 
@@ -108,7 +108,7 @@ export function extractPacketTrailer(data: ArrayBuffer | Uint8Array): ExtractPac
   const strippedData = bytes.subarray(0, trailerStart);
   let offset = trailerStart;
   let foundAny = false;
-  const metadata: PacketTrailerMetadata = {
+  const metadata: FrameMetadata = {
     userTimestamp: BigInt(0),
     frameId: 0,
   };
@@ -223,16 +223,16 @@ export function getFrameSsrc(frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame)
   return 0;
 }
 
-export interface PacketTrailerFramePayload {
+export interface FrameMetadataPayload {
   trackId: string;
   rtpTimestamp: number;
   ssrc: number;
-  metadata: PacketTrailerMetadata;
+  metadata: FrameMetadata;
 }
 
 export interface ProcessPacketTrailerResult {
   data?: ArrayBuffer;
-  payload?: PacketTrailerFramePayload;
+  payload?: FrameMetadataPayload;
 }
 
 /**

package/src/{packetTrailer → frameMetadata}/types.ts

@@ -1,15 +1,21 @@
-import type { PacketTrailerFramePayload } from './packetTrailer';
+import type { FrameMetadataPayload } from './frameMetadata';
 
-export interface PacketTrailerMetadata {
+export interface FrameMetadata {
   userTimestamp: bigint;
   frameId: number;
 }
 
-export interface PacketTrailerPublishOptions {
+/** @deprecated Use {@link FrameMetadata} instead. */
+export type PacketTrailerMetadata = FrameMetadata;
+
+export interface FrameMetadataPublishOptions {
   timestamp?: boolean;
   frameId?: boolean;
 }
 
+/** @deprecated Use {@link FrameMetadataPublishOptions} instead. */
+export type PacketTrailerPublishOptions = FrameMetadataPublishOptions;
+
 export interface PTBaseMessage {
   kind: string;
   data?: unknown;
@@ -38,7 +44,7 @@ export interface PTEncodeMessage extends PTBaseMessage {
   data: {
     readableStream: ReadableStream;
     writableStream: WritableStream;
-    packetTrailer?: PacketTrailerPublishOptions;
+    packetTrailer?: FrameMetadataPublishOptions;
   };
 }
 
@@ -49,12 +55,12 @@ export type PTScriptTransformOptions =
     }
   | {
       kind: 'encode';
-      packetTrailer?: PacketTrailerPublishOptions;
+      packetTrailer?: FrameMetadataPublishOptions;
     };
 
 export interface PTMetadataMessage extends PTBaseMessage {
   kind: 'metadata';
-  data: PacketTrailerFramePayload;
+  data: FrameMetadataPayload;
 }
 
 export interface PTUpdateTrackIdMessage extends PTBaseMessage {

package/src/{packetTrailer → frameMetadata}/utils.test.ts

@@ -1,12 +1,12 @@
 import { PacketTrailerFeature } from '@livekit/protocol';
 import { afterEach, describe, expect, it } from 'vitest';
 import {
-  getPacketTrailerFeatures,
-  getPacketTrailerPublishOptions,
-  isPacketTrailerSupported,
+  getFrameMetadataFeatures,
+  getFrameMetadataPublishOptions,
+  isFrameMetadataSupported,
 } from './utils';
 
-describe('packet trailer support', () => {
+describe('frame metadata support', () => {
   const originalRTCRtpSender = window.RTCRtpSender;
   const originalRTCRtpScriptTransform = (window as unknown as { RTCRtpScriptTransform?: unknown })
     .RTCRtpScriptTransform;
@@ -46,20 +46,20 @@ describe('packet trailer support', () => {
     });
   }
 
-  it('supports packet trailers with RTCRtpScriptTransform on Safari', () => {
+  it('supports frame metadata with RTCRtpScriptTransform on Safari', () => {
     stubScriptTransformSupport(
       'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15',
     );
 
-    expect(isPacketTrailerSupported({ worker: {} as Worker })).toBe(true);
+    expect(isFrameMetadataSupported({ worker: {} as Worker })).toBe(true);
   });
 
-  it('supports packet trailers with RTCRtpScriptTransform on Firefox', () => {
+  it('supports frame metadata with RTCRtpScriptTransform on Firefox', () => {
     stubScriptTransformSupport(
       'Mozilla/5.0 (Macintosh; Intel Mac OS X 14.0; rv:144.0) Gecko/20100101 Firefox/144.0',
     );
 
-    expect(isPacketTrailerSupported({ worker: {} as Worker })).toBe(true);
+    expect(isFrameMetadataSupported({ worker: {} as Worker })).toBe(true);
   });
 
   it('does not use RTCRtpScriptTransform support on Chromium-based browsers', () => {
@@ -67,39 +67,39 @@ describe('packet trailer support', () => {
       'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36',
     );
 
-    expect(isPacketTrailerSupported({ worker: {} as Worker })).toBe(false);
+    expect(isFrameMetadataSupported({ worker: {} as Worker })).toBe(false);
   });
 });
 
-describe('packet trailer publish features', () => {
+describe('frame metadata publish features', () => {
   it('maps publish options to protocol features', () => {
-    expect(getPacketTrailerFeatures({ timestamp: true, frameId: true })).toEqual([
+    expect(getFrameMetadataFeatures({ timestamp: true, frameId: true })).toEqual([
       PacketTrailerFeature.PTF_USER_TIMESTAMP,
       PacketTrailerFeature.PTF_FRAME_ID,
     ]);
-    expect(getPacketTrailerFeatures({ timestamp: true })).toEqual([
+    expect(getFrameMetadataFeatures({ timestamp: true })).toEqual([
       PacketTrailerFeature.PTF_USER_TIMESTAMP,
     ]);
-    expect(getPacketTrailerFeatures({ frameId: true })).toEqual([
+    expect(getFrameMetadataFeatures({ frameId: true })).toEqual([
       PacketTrailerFeature.PTF_FRAME_ID,
     ]);
-    expect(getPacketTrailerFeatures()).toEqual([]);
+    expect(getFrameMetadataFeatures()).toEqual([]);
   });
 
   it('maps protocol features to publish options', () => {
     expect(
-      getPacketTrailerPublishOptions([
+      getFrameMetadataPublishOptions([
         PacketTrailerFeature.PTF_USER_TIMESTAMP,
         PacketTrailerFeature.PTF_FRAME_ID,
       ]),
     ).toEqual({ timestamp: true, frameId: true });
-    expect(getPacketTrailerPublishOptions([PacketTrailerFeature.PTF_USER_TIMESTAMP])).toEqual({
+    expect(getFrameMetadataPublishOptions([PacketTrailerFeature.PTF_USER_TIMESTAMP])).toEqual({
       timestamp: true,
     });
-    expect(getPacketTrailerPublishOptions([PacketTrailerFeature.PTF_FRAME_ID])).toEqual({
+    expect(getFrameMetadataPublishOptions([PacketTrailerFeature.PTF_FRAME_ID])).toEqual({
       frameId: true,
     });
-    expect(getPacketTrailerPublishOptions()).toBeUndefined();
-    expect(getPacketTrailerPublishOptions([])).toBeUndefined();
+    expect(getFrameMetadataPublishOptions()).toBeUndefined();
+    expect(getFrameMetadataPublishOptions([])).toBeUndefined();
   });
 });

package/src/{packetTrailer → frameMetadata}/utils.ts

@@ -1,25 +1,25 @@
 import { PacketTrailerFeature } from '@livekit/protocol';
 import { isInsertableStreamSupported } from '../e2ee/utils';
 import { isScriptTransformSupportedForWorker } from '../room/utils';
-import type { PacketTrailerOptions } from './PacketTrailerManager';
-import type { PacketTrailerPublishOptions } from './types';
+import type { FrameMetadataOptions } from './FrameMetadataManager';
+import type { FrameMetadataPublishOptions } from './types';
 
-export function shouldUsePacketTrailerScriptTransform() {
+export function shouldUseFrameMetadataScriptTransform() {
   return isScriptTransformSupportedForWorker();
 }
 
-export function isPacketTrailerSupported(options?: PacketTrailerOptions) {
+export function isFrameMetadataSupported(options?: FrameMetadataOptions) {
   return (
-    !!options?.worker && (isInsertableStreamSupported() || shouldUsePacketTrailerScriptTransform())
+    !!options?.worker && (isInsertableStreamSupported() || shouldUseFrameMetadataScriptTransform())
   );
 }
 
-export function hasPacketTrailerPublishOptions(options?: PacketTrailerPublishOptions): boolean {
+export function hasFrameMetadataPublishOptions(options?: FrameMetadataPublishOptions): boolean {
   return !!(options?.timestamp || options?.frameId);
 }
 
-export function getPacketTrailerFeatures(
-  options?: PacketTrailerPublishOptions,
+export function getFrameMetadataFeatures(
+  options?: FrameMetadataPublishOptions,
 ): PacketTrailerFeature[] {
   const features: PacketTrailerFeature[] = [];
   if (options?.timestamp) {
@@ -31,14 +31,14 @@ export function getPacketTrailerFeatures(
   return features;
 }
 
-export function getPacketTrailerPublishOptions(
+export function getFrameMetadataPublishOptions(
   features?: PacketTrailerFeature[],
-): PacketTrailerPublishOptions | undefined {
+): FrameMetadataPublishOptions | undefined {
   if (!features || features.length === 0) {
     return undefined;
   }
 
-  const options: PacketTrailerPublishOptions = {};
+  const options: FrameMetadataPublishOptions = {};
   if (features.includes(PacketTrailerFeature.PTF_USER_TIMESTAMP)) {
     options.timestamp = true;
   }

package/src/{packetTrailer/worker/packetTrailer.worker.ts → frameMetadata/worker/frameMetadata.worker.ts}

@@ -1,11 +1,11 @@
-import { appendPacketTrailerToEncodedFrame, processPacketTrailer } from '../packetTrailer';
+import { appendPacketTrailerToEncodedFrame, processPacketTrailer } from '../frameMetadata';
 import type {
+  FrameMetadataPublishOptions,
   PTMetadataMessage,
   PTScriptTransformOptions,
   PTWorkerMessage,
-  PacketTrailerPublishOptions,
 } from '../types';
-import { hasPacketTrailerPublishOptions } from '../utils';
+import { hasFrameMetadataPublishOptions } from '../utils';
 
 /**
  * Holds the trackId currently associated with a pipeline. A mutable
@@ -97,9 +97,9 @@ function setupDecodeTransform(
 function setupEncodeTransform(
   readable: ReadableStream,
   writable: WritableStream,
-  packetTrailer?: PacketTrailerPublishOptions,
+  packetTrailer?: FrameMetadataPublishOptions,
 ) {
-  if (!hasPacketTrailerPublishOptions(packetTrailer)) {
+  if (!hasFrameMetadataPublishOptions(packetTrailer)) {
     readable.pipeTo(writable).catch(() => {});
     return;
   }

package/src/{packetTrailer → frameMetadata}/worker/tsconfig.json

@@ -8,7 +8,10 @@
       "ES2018.Promise",
       "WebWorker",
       "ES2021.WeakRef",
-      "DOM.AsyncIterable"
+      "DOM.AsyncIterable",
+      "ES2020.BigInt",
+      "ES2018.AsyncIterable",
+      "ES2018.AsyncGenerator"
     ]
   }
 }

package/src/index.ts

@@ -64,11 +64,22 @@ import {
 import { getBrowser } from './utils/browserParser';
 
 export { RpcError, type RpcInvocationData, type PerformRpcParams } from './room/rpc';
-export type { PacketTrailerMetadata, PacketTrailerPublishOptions } from './packetTrailer/types';
+export type {
+  FrameMetadata,
+  FrameMetadataPublishOptions,
+  /** @deprecated Use {@link FrameMetadata} instead. */
+  PacketTrailerMetadata,
+  /** @deprecated Use {@link FrameMetadataPublishOptions} instead. */
+  PacketTrailerPublishOptions,
+} from './frameMetadata/types';
 export {
+  FrameMetadataManager,
+  /** @deprecated Use {@link FrameMetadataManager} instead. */
   PacketTrailerManager,
+  type FrameMetadataOptions,
+  /** @deprecated Use {@link FrameMetadataOptions} instead. */
   type PacketTrailerOptions,
-} from './packetTrailer/PacketTrailerManager';
+} from './frameMetadata/FrameMetadataManager';
 
 export * from './connectionHelper/ConnectionCheck';
 export * from './connectionHelper/checks/Checker';

package/src/options.ts

@@ -1,5 +1,5 @@
 import type { E2EEOptions } from './e2ee/types';
-import type { PacketTrailerOptions } from './packetTrailer/PacketTrailerManager';
+import type { FrameMetadataOptions } from './frameMetadata/FrameMetadataManager';
 import type { ReconnectPolicy } from './room/ReconnectPolicy';
 import type {
   AudioCaptureOptions,
@@ -103,10 +103,15 @@ export interface InternalRoomOptions {
 
   /**
    * @experimental
-   * Options for enabling packet trailers on video tracks.
-   * Packet trailers carry frame-level metadata such as user timestamps and frame IDs.
+   * Options for enabling frame metadata on video tracks.
+   * Frame metadata carries frame-level information such as user timestamps and frame IDs.
    */
-  packetTrailer?: PacketTrailerOptions;
+  frameMetadata?: FrameMetadataOptions;
+
+  /**
+   * @deprecated Use {@link InternalRoomOptions.frameMetadata} instead.
+   */
+  packetTrailer?: FrameMetadataOptions;
 
   /**
    * will attempt to connect via single peer connection mode.

package/src/room/PCTransport.ts

@@ -498,6 +498,10 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
     return this.pc.getStats();
   }
 
+  getMaxMessageSize() {
+    return this._pc?.sctp?.maxMessageSize;
+  }
+
   async getConnectedAddress(): Promise<string | undefined> {
     if (!this._pc) {
       return;

package/src/room/PCTransportManager.ts

@@ -310,6 +310,10 @@ export class PCTransportManager {
     return matchingTransceiver?.mid;
   }
 
+  getMaxPublisherMessageSize() {
+    return this.publisher.getMaxMessageSize();
+  }
+
   addPublisherTrack(track: MediaStreamTrack) {
     return this.publisher.addTrack(track);
   }