livekit-client 2.19.2 → 2.20.1

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

@@ -1,8 +1,8 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import type { TrackInfo } from '@livekit/protocol';
-import { PacketTrailerManager } from './PacketTrailerManager';
+import { FrameMetadataManager } from './FrameMetadataManager';
 
-describe('PacketTrailerManager', () => {
+describe('FrameMetadataManager', () => {
   const originalRTCRtpSender = window.RTCRtpSender;
   const originalUserAgent = navigator.userAgent;
   const originalRTCRtpScriptTransform = (window as unknown as { RTCRtpScriptTransform?: unknown })
@@ -63,7 +63,7 @@ describe('PacketTrailerManager', () => {
     });
   }
 
-  function setupWorkerReceiver(manager: PacketTrailerManager, receiver: RTCRtpReceiver) {
+  function setupWorkerReceiver(manager: FrameMetadataManager, receiver: RTCRtpReceiver) {
     (
       manager as unknown as {
         setupWorkerReceiver: (receiver: RTCRtpReceiver, newTrackId: string) => void;
@@ -72,7 +72,7 @@ describe('PacketTrailerManager', () => {
   }
 
   function setupReceiver(
-    manager: PacketTrailerManager,
+    manager: FrameMetadataManager,
     receiver: RTCRtpReceiver,
     trackId: string,
     trackInfo?: TrackInfo,
@@ -103,11 +103,13 @@ describe('PacketTrailerManager', () => {
   it('uses RTCRtpScriptTransform for packet trailer extraction when supported', () => {
     useSafariUserAgent();
     const transform = {};
-    const RTCRtpScriptTransform = vi.fn(() => transform);
+    const RTCRtpScriptTransform = vi.fn(function () {
+      return transform;
+    });
     setScriptTransform(RTCRtpScriptTransform);
 
     const worker = {} as Worker;
-    const manager = new PacketTrailerManager({ worker });
+    const manager = new FrameMetadataManager({ worker });
     const receiver = {
       createEncodedStreams: vi.fn(),
     } as unknown as RTCRtpReceiver;
@@ -129,7 +131,7 @@ describe('PacketTrailerManager', () => {
     stubInsertableStreamsSupport();
 
     const worker = { postMessage: vi.fn() } as unknown as Worker;
-    const manager = new PacketTrailerManager({ worker });
+    const manager = new FrameMetadataManager({ worker });
     const { receiver, readable, writable, createEncodedStreams } = makeReceiver();
 
     setupReceiver(manager, receiver, 'track-without-trailer');
@@ -153,7 +155,7 @@ describe('PacketTrailerManager', () => {
     stubInsertableStreamsSupport();
 
     const worker = { postMessage: vi.fn() } as unknown as Worker;
-    const manager = new PacketTrailerManager({ worker });
+    const manager = new FrameMetadataManager({ worker });
     const { receiver } = makeReceiver();
     const trackInfo = { packetTrailerFeatures: [1] } as unknown as TrackInfo;
 

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}

@@ -1,10 +1,56 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
+  PACKET_TRAILER_ENVELOPE_SIZE,
+  PACKET_TRAILER_FRAME_ID_TAG,
+  PACKET_TRAILER_MAGIC,
+  PACKET_TRAILER_TIMESTAMP_TAG,
+  PACKET_TRAILER_USER_DATA_TAG,
   appendPacketTrailer,
   appendPacketTrailerToEncodedFrame,
   extractPacketTrailer,
   processPacketTrailer,
-} from './packetTrailer';
+} from './frameMetadata';
+
+/**
+ * Builds a packet trailer (XORed TLVs + envelope) for the given fields. The
+ * SDK only writes timestamp/frameId, so this mirrors the native sender's TLV
+ * encoding to exercise user_data extraction.
+ */
+function buildTrailer(
+  payload: Uint8Array,
+  fields: { userTimestamp?: bigint; frameId?: number; userData?: Uint8Array },
+): Uint8Array {
+  const tlvs: number[] = [];
+
+  if (fields.userTimestamp !== undefined) {
+    tlvs.push(PACKET_TRAILER_TIMESTAMP_TAG ^ 0xff, 8 ^ 0xff);
+    for (let i = 7; i >= 0; i -= 1) {
+      tlvs.push(Number((fields.userTimestamp >> BigInt(i * 8)) & BigInt(0xff)) ^ 0xff);
+    }
+  }
+
+  if (fields.frameId !== undefined) {
+    tlvs.push(PACKET_TRAILER_FRAME_ID_TAG ^ 0xff, 4 ^ 0xff);
+    for (let i = 3; i >= 0; i -= 1) {
+      tlvs.push(((fields.frameId >> (i * 8)) & 0xff) ^ 0xff);
+    }
+  }
+
+  if (fields.userData !== undefined) {
+    tlvs.push(PACKET_TRAILER_USER_DATA_TAG ^ 0xff, fields.userData.length ^ 0xff);
+    for (const byte of fields.userData) {
+      tlvs.push(byte ^ 0xff);
+    }
+  }
+
+  const trailerLength = tlvs.length + PACKET_TRAILER_ENVELOPE_SIZE;
+  const result = new Uint8Array(payload.length + trailerLength);
+  result.set(payload, 0);
+  result.set(tlvs, payload.length);
+  result[payload.length + tlvs.length] = trailerLength ^ 0xff;
+  result.set(PACKET_TRAILER_MAGIC, payload.length + tlvs.length + 1);
+  return result;
+}
 
 describe('packetTrailer', () => {
   afterEach(() => {
@@ -47,6 +93,43 @@ describe('packetTrailer', () => {
     });
   });
 
+  it('extracts user_data from a trailer carrying only user_data', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const userData = Uint8Array.from([0x00, 0x01, 0xfe, 0xff, 0x42]);
+    const trailer = buildTrailer(payload, { userData });
+    const extracted = extractPacketTrailer(trailer);
+
+    expect(Array.from(extracted.data)).toEqual(Array.from(payload));
+    expect(extracted.metadata?.userTimestamp).toBe(0n);
+    expect(extracted.metadata?.frameId).toBe(0);
+    expect(extracted.metadata?.userData).toBeInstanceOf(Uint8Array);
+    expect(Array.from(extracted.metadata!.userData!)).toEqual(Array.from(userData));
+  });
+
+  it('extracts user_data alongside timestamp and frameId', () => {
+    const payload = Uint8Array.from([9, 8, 7, 6, 5]);
+    const userData = Uint8Array.from([10, 20, 30, 40]);
+    const trailer = buildTrailer(payload, {
+      userTimestamp: 1_744_249_600_123_456n,
+      frameId: 42,
+      userData,
+    });
+    const extracted = extractPacketTrailer(trailer);
+
+    expect(Array.from(extracted.data)).toEqual(Array.from(payload));
+    expect(extracted.metadata?.userTimestamp).toBe(1_744_249_600_123_456n);
+    expect(extracted.metadata?.frameId).toBe(42);
+    expect(Array.from(extracted.metadata!.userData!)).toEqual(Array.from(userData));
+  });
+
+  it('leaves userData undefined when no user_data tag is present', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const trailer = appendPacketTrailer(payload, 1_744_249_600_123_456n, 42);
+    const extracted = extractPacketTrailer(trailer);
+
+    expect(extracted.metadata?.userData).toBeUndefined();
+  });
+
   it('returns data unchanged when both timestamp and frameId are 0', () => {
     const payload = Uint8Array.from([1, 2, 3, 4]);
     const result = appendPacketTrailer(payload, 0n, 0);

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),
@@ -10,6 +10,7 @@ export const PACKET_TRAILER_MAGIC = Uint8Array.from([
 
 export const PACKET_TRAILER_TIMESTAMP_TAG = 0x01;
 export const PACKET_TRAILER_FRAME_ID_TAG = 0x02;
+export const PACKET_TRAILER_USER_DATA_TAG = 0x03;
 export const PACKET_TRAILER_ENVELOPE_SIZE = 5;
 
 const TIMESTAMP_TLV_SIZE = 10;
@@ -17,7 +18,7 @@ const FRAME_ID_TLV_SIZE = 6;
 
 export interface ExtractPacketTrailerResult {
   data: Uint8Array;
-  metadata?: PacketTrailerMetadata;
+  metadata?: FrameMetadata;
 }
 
 export function appendPacketTrailer(
@@ -64,10 +65,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 +109,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,
   };
@@ -127,6 +128,13 @@ export function extractPacketTrailer(data: ArrayBuffer | Uint8Array): ExtractPac
     } else if (tag === PACKET_TRAILER_FRAME_ID_TAG && length === 4) {
       metadata.frameId = readUint32Xor(bytes, offset, length);
       foundAny = true;
+    } else if (tag === PACKET_TRAILER_USER_DATA_TAG) {
+      const userData = new Uint8Array(length);
+      for (let index = 0; index < length; index += 1) {
+        userData[index] = bytes[offset + index] ^ 0xff;
+      }
+      metadata.userData = userData;
+      foundAny = true;
     }
 
     offset += length;
@@ -223,16 +231,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,22 @@
-import type { PacketTrailerFramePayload } from './packetTrailer';
+import type { FrameMetadataPayload } from './frameMetadata';
 
-export interface PacketTrailerMetadata {
+export interface FrameMetadata {
   userTimestamp: bigint;
   frameId: number;
+  userData?: Uint8Array;
 }
 
-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 +45,7 @@ export interface PTEncodeMessage extends PTBaseMessage {
   data: {
     readableStream: ReadableStream;
     writableStream: WritableStream;
-    packetTrailer?: PacketTrailerPublishOptions;
+    packetTrailer?: FrameMetadataPublishOptions;
   };
 }
 
@@ -49,12 +56,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.