livekit-client 2.18.9 → 2.18.10

package/src/e2ee/worker/e2ee.worker.ts

@@ -29,7 +29,7 @@ let isEncryptionEnabled: boolean = false;
 
 let useSharedKey: boolean = false;
 
-let sifTrailer: Uint8Array | undefined;
+let sifTrailer: NonSharedUint8Array | undefined;
 
 let keyProviderOptions: KeyProviderOptions = KEY_PROVIDER_DEFAULTS;
 
@@ -64,6 +64,7 @@ onmessage = (ev) => {
         break;
       case 'decode':
         let cryptor = getTrackCryptor(data.participantIdentity, data.trackId);
+        cryptor.setHasPacketTrailer(data.hasPacketTrailer);
         cryptor.setupTransform(
           kind,
           data.readableStream,
@@ -75,6 +76,7 @@ onmessage = (ev) => {
         break;
       case 'encode':
         let pubCryptor = getTrackCryptor(data.participantIdentity, data.trackId);
+        pubCryptor.setHasPacketTrailer(data.hasPacketTrailer);
         pubCryptor.setupTransform(
           kind,
           data.readableStream,
@@ -82,6 +84,7 @@ onmessage = (ev) => {
           data.trackId,
           data.isReuse,
           data.codec,
+          data.packetTrailer,
         );
         break;
 
@@ -159,11 +162,14 @@ onmessage = (ev) => {
         unsetCryptorParticipant(data.trackId, data.participantIdentity);
         break;
       case 'updateCodec':
-        getTrackCryptor(data.participantIdentity, data.trackId).setVideoCodec(data.codec);
+        const trackCryptor = getTrackCryptor(data.participantIdentity, data.trackId);
+        trackCryptor.setVideoCodec(data.codec);
+        trackCryptor.setHasPacketTrailer(data.hasPacketTrailer);
         workerLogger.info('updated codec', {
           participantIdentity: data.participantIdentity,
           trackId: data.trackId,
           codec: data.codec,
+          hasPacketTrailer: data.hasPacketTrailer,
         });
         break;
       case 'setRTPMap':
@@ -319,7 +325,7 @@ function emitRatchetedKeys(
   postMessage(msg);
 }
 
-function handleSifTrailer(trailer: Uint8Array) {
+function handleSifTrailer(trailer: NonSharedUint8Array) {
   sifTrailer = trailer;
   participantCryptors.forEach((c) => {
     c.setSifTrailer(trailer);
@@ -333,10 +339,11 @@ if (self.RTCTransformEvent) {
   self.onrtctransform = (event: RTCTransformEvent) => {
     // @ts-ignore
     const transformer = event.transformer;
-    const { kind, participantIdentity, trackId, codec } =
-      transformer.options as ScriptTransformOptions;
+    const options = transformer.options as ScriptTransformOptions;
+    const { kind, participantIdentity, trackId, codec, hasPacketTrailer } = options;
     messageQueue.run(async () => {
       const cryptor = getTrackCryptor(participantIdentity, trackId);
+      cryptor.setHasPacketTrailer(hasPacketTrailer);
       workerLogger.debug('onrtctransform setup', { participantIdentity, trackId, codec });
       cryptor.setupTransform(
         kind,
@@ -345,6 +352,7 @@ if (self.RTCTransformEvent) {
         trackId,
         false,
         codec,
+        kind === 'encode' ? options.packetTrailer : undefined,
       );
     });
   };

package/src/e2ee/worker/naluUtils.ts

@@ -200,7 +200,7 @@ export interface NALUProcessingResult {
  * @param naluIndices Indices where NALUs start
  * @returns Detected codec type
  */
-function detectCodecFromNALUs(data: Uint8Array, naluIndices: number[]): DetectedCodec {
+function detectCodecFromNALUs(data: NonSharedUint8Array, naluIndices: number[]): DetectedCodec {
   for (const naluIndex of naluIndices) {
     if (isH264SliceNALU(parseH264NALUType(data[naluIndex]))) return 'h264';
     if (isH265SliceNALU(parseH265NALUType(data[naluIndex]))) return 'h265';
@@ -216,7 +216,7 @@ function detectCodecFromNALUs(data: Uint8Array, naluIndices: number[]): Detected
  * @returns Number of unencrypted bytes (index + 2) or null if no slice found
  */
 function findSliceNALUUnencryptedBytes(
-  data: Uint8Array,
+  data: NonSharedUint8Array,
   naluIndices: number[],
   codec: 'h264' | 'h265',
 ): number | null {
@@ -246,7 +246,7 @@ function findSliceNALUUnencryptedBytes(
  * @param stream Byte stream containing NALUs
  * @returns Array of indices where NALUs start (after the start code)
  */
-function findNALUIndices(stream: Uint8Array): number[] {
+function findNALUIndices(stream: NonSharedUint8Array): number[] {
   const result: number[] = [];
   let start = 0,
     pos = 0,
@@ -309,7 +309,7 @@ function findNALUIndices(stream: Uint8Array): number[] {
  * @returns NALU processing result
  */
 export function processNALUsForEncryption(
-  data: Uint8Array,
+  data: NonSharedUint8Array,
   knownCodec?: 'h264' | 'h265',
 ): NALUProcessingResult {
   const naluIndices = findNALUIndices(data);

package/src/e2ee/worker/sifPayload.ts

@@ -2,29 +2,31 @@ import type { VideoCodec } from '../..';
 
 //  Payload definitions taken from https://github.com/livekit/livekit/blob/master/pkg/sfu/downtrack.go#L104
 
-export const VP8KeyFrame8x8: Uint8Array = new Uint8Array([
+export const VP8KeyFrame8x8: NonSharedUint8Array = new Uint8Array([
   0x10, 0x02, 0x00, 0x9d, 0x01, 0x2a, 0x08, 0x00, 0x08, 0x00, 0x00, 0x47, 0x08, 0x85, 0x85, 0x88,
   0x85, 0x84, 0x88, 0x02, 0x02, 0x00, 0x0c, 0x0d, 0x60, 0x00, 0xfe, 0xff, 0xab, 0x50, 0x80,
 ]);
 
-export const H264KeyFrame2x2SPS: Uint8Array = new Uint8Array([
+export const H264KeyFrame2x2SPS: NonSharedUint8Array = new Uint8Array([
   0x67, 0x42, 0xc0, 0x1f, 0x0f, 0xd9, 0x1f, 0x88, 0x88, 0x84, 0x00, 0x00, 0x03, 0x00, 0x04, 0x00,
   0x00, 0x03, 0x00, 0xc8, 0x3c, 0x60, 0xc9, 0x20,
 ]);
 
-export const H264KeyFrame2x2PPS: Uint8Array = new Uint8Array([0x68, 0x87, 0xcb, 0x83, 0xcb, 0x20]);
+export const H264KeyFrame2x2PPS: NonSharedUint8Array = new Uint8Array([
+  0x68, 0x87, 0xcb, 0x83, 0xcb, 0x20,
+]);
 
-export const H264KeyFrame2x2IDR: Uint8Array = new Uint8Array([
+export const H264KeyFrame2x2IDR: NonSharedUint8Array = new Uint8Array([
   0x65, 0x88, 0x84, 0x0a, 0xf2, 0x62, 0x80, 0x00, 0xa7, 0xbe,
 ]);
 
-export const H264KeyFrame2x2: Uint8Array[] = [
+export const H264KeyFrame2x2: NonSharedUint8Array[] = [
   H264KeyFrame2x2SPS,
   H264KeyFrame2x2PPS,
   H264KeyFrame2x2IDR,
 ];
 
-export const OpusSilenceFrame: Uint8Array = new Uint8Array([
+export const OpusSilenceFrame: NonSharedUint8Array = new Uint8Array([
   0xf8, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
@@ -35,7 +37,7 @@ export const OpusSilenceFrame: Uint8Array = new Uint8Array([
 /**
  * Create a crypto hash using Web Crypto API for secure comparison operations
  */
-async function cryptoHash(data: Uint8Array | ArrayBuffer): Promise<string> {
+async function cryptoHash(data: NonSharedUint8Array | ArrayBuffer): Promise<string> {
   const hashBuffer = await crypto.subtle.digest('SHA-256', data);
   const hashArray = new Uint8Array(hashBuffer);
   return Array.from(hashArray)
@@ -58,7 +60,7 @@ export const CryptoHashes = {
  * Check if a byte array matches any of the known SIF payload frame types using secure crypto hashes
  */
 export async function identifySifPayload(
-  data: Uint8Array | ArrayBuffer,
+  data: NonSharedUint8Array | ArrayBuffer,
 ): Promise<VideoCodec | 'opus' | null> {
   const hash = await cryptoHash(data);
 

package/src/index.ts

@@ -13,6 +13,7 @@ import Room, { ConnectionState, type RoomEventCallbacks } from './room/Room';
 import * as attributes from './room/attribute-typings';
 import LocalDataTrack from './room/data-track/LocalDataTrack';
 import RemoteDataTrack, { type DataTrackSubscribeOptions } from './room/data-track/RemoteDataTrack';
+import { type RemoteDataTrackPipelineOptions } from './room/data-track/types';
 import LocalParticipant from './room/participant/LocalParticipant';
 import Participant, {
   ConnectionQuality,
@@ -63,6 +64,11 @@ import {
 import { getBrowser } from './utils/browserParser';
 
 export { RpcError, type RpcInvocationData, type PerformRpcParams } from './room/rpc';
+export type { PacketTrailerMetadata, PacketTrailerPublishOptions } from './packetTrailer/types';
+export {
+  PacketTrailerManager,
+  type PacketTrailerOptions,
+} from './packetTrailer/PacketTrailerManager';
 
 export * from './connectionHelper/ConnectionCheck';
 export * from './connectionHelper/checks/Checker';
@@ -159,6 +165,7 @@ export type {
   ParticipantEventCallbacks,
   PublicationEventCallbacks,
   DataTrackSubscribeOptions,
+  RemoteDataTrackPipelineOptions,
 };
 export { DataTrackPacket, type DataTrackPacketHeader } from './room/data-track/packet';
 export {

package/src/options.ts

@@ -1,4 +1,5 @@
 import type { E2EEOptions } from './e2ee/types';
+import type { PacketTrailerOptions } from './packetTrailer/PacketTrailerManager';
 import type { ReconnectPolicy } from './room/ReconnectPolicy';
 import type {
   AudioCaptureOptions,
@@ -100,6 +101,13 @@ export interface InternalRoomOptions {
 
   loggerName?: string;
 
+  /**
+   * @experimental
+   * Options for enabling packet trailers on video tracks.
+   * Packet trailers carry frame-level metadata such as user timestamps and frame IDs.
+   */
+  packetTrailer?: PacketTrailerOptions;
+
   /**
    * will attempt to connect via single peer connection mode.
    * falls back to dual peer connection mode if not available.

package/src/packetTrailer/PacketTrailerManager.test.ts

@@ -0,0 +1,172 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { TrackInfo } from '@livekit/protocol';
+import { PacketTrailerManager } from './PacketTrailerManager';
+
+describe('PacketTrailerManager', () => {
+  const originalRTCRtpSender = window.RTCRtpSender;
+  const originalUserAgent = navigator.userAgent;
+  const originalRTCRtpScriptTransform = (window as unknown as { RTCRtpScriptTransform?: unknown })
+    .RTCRtpScriptTransform;
+
+  afterEach(() => {
+    Object.defineProperty(window, 'RTCRtpSender', {
+      configurable: true,
+      value: originalRTCRtpSender,
+      writable: true,
+    });
+    Object.defineProperty(window.navigator, 'userAgent', {
+      configurable: true,
+      value: originalUserAgent,
+    });
+    Object.defineProperty(window, 'RTCRtpScriptTransform', {
+      configurable: true,
+      value: originalRTCRtpScriptTransform,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, 'RTCRtpScriptTransform', {
+      configurable: true,
+      value: originalRTCRtpScriptTransform,
+      writable: true,
+    });
+  });
+
+  function stubInsertableStreamsSupport() {
+    class MockRTCRtpSender {
+      createEncodedStreams() {}
+    }
+
+    Object.defineProperty(window, 'RTCRtpSender', {
+      configurable: true,
+      value: MockRTCRtpSender,
+      writable: true,
+    });
+  }
+
+  function useSafariUserAgent() {
+    Object.defineProperty(window.navigator, 'userAgent', {
+      configurable: true,
+      value:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15',
+    });
+  }
+
+  function setScriptTransform(mock: unknown) {
+    Object.defineProperty(window, 'RTCRtpScriptTransform', {
+      configurable: true,
+      value: mock,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, 'RTCRtpScriptTransform', {
+      configurable: true,
+      value: mock,
+      writable: true,
+    });
+  }
+
+  function setupWorkerReceiver(manager: PacketTrailerManager, receiver: RTCRtpReceiver) {
+    (
+      manager as unknown as {
+        setupWorkerReceiver: (receiver: RTCRtpReceiver, newTrackId: string) => void;
+      }
+    ).setupWorkerReceiver(receiver, 'track-id');
+  }
+
+  function setupReceiver(
+    manager: PacketTrailerManager,
+    receiver: RTCRtpReceiver,
+    trackId: string,
+    trackInfo?: TrackInfo,
+  ) {
+    (
+      manager as unknown as {
+        setupReceiver: (
+          track: { receiver: RTCRtpReceiver; mediaStreamID: string },
+          trackInfo?: TrackInfo,
+        ) => void;
+      }
+    ).setupReceiver({ receiver, mediaStreamID: trackId }, trackInfo);
+  }
+
+  function makeReceiver() {
+    const readable = {} as ReadableStream;
+    const writable = {} as WritableStream;
+    const createEncodedStreams = vi.fn(() => ({ readable, writable }));
+
+    return {
+      receiver: { createEncodedStreams } as unknown as RTCRtpReceiver,
+      readable,
+      writable,
+      createEncodedStreams,
+    };
+  }
+
+  it('uses RTCRtpScriptTransform for packet trailer extraction when supported', () => {
+    useSafariUserAgent();
+    const transform = {};
+    const RTCRtpScriptTransform = vi.fn(() => transform);
+    setScriptTransform(RTCRtpScriptTransform);
+
+    const worker = {} as Worker;
+    const manager = new PacketTrailerManager({ worker });
+    const receiver = {
+      createEncodedStreams: vi.fn(),
+    } as unknown as RTCRtpReceiver;
+
+    setupWorkerReceiver(manager, receiver);
+
+    expect(RTCRtpScriptTransform).toHaveBeenCalledWith(worker, {
+      kind: 'decode',
+      trackId: 'track-id',
+    });
+    expect((receiver as unknown as { transform: unknown }).transform).toBe(transform);
+    expect(
+      (receiver as unknown as { createEncodedStreams: ReturnType<typeof vi.fn> })
+        .createEncodedStreams,
+    ).not.toHaveBeenCalled();
+  });
+
+  it('sets up a passthrough receiver pipeline when a subscribed track has no packet trailer features', () => {
+    stubInsertableStreamsSupport();
+
+    const worker = { postMessage: vi.fn() } as unknown as Worker;
+    const manager = new PacketTrailerManager({ worker });
+    const { receiver, readable, writable, createEncodedStreams } = makeReceiver();
+
+    setupReceiver(manager, receiver, 'track-without-trailer');
+
+    expect(createEncodedStreams).toHaveBeenCalledTimes(1);
+    expect(worker.postMessage).toHaveBeenCalledWith(
+      {
+        kind: 'decode',
+        data: {
+          readableStream: readable,
+          writableStream: writable,
+          trackId: 'track-without-trailer',
+          hasPacketTrailer: false,
+        },
+      },
+      [readable, writable],
+    );
+  });
+
+  it('updates a reused receiver from trailer extraction to passthrough for tracks without packet trailer features', () => {
+    stubInsertableStreamsSupport();
+
+    const worker = { postMessage: vi.fn() } as unknown as Worker;
+    const manager = new PacketTrailerManager({ worker });
+    const { receiver } = makeReceiver();
+    const trackInfo = { packetTrailerFeatures: [1] } as unknown as TrackInfo;
+
+    setupReceiver(manager, receiver, 'track-with-trailer', trackInfo);
+    setupReceiver(manager, receiver, 'track-without-trailer');
+
+    expect(worker.postMessage).toHaveBeenLastCalledWith({
+      kind: 'updateTrackId',
+      data: {
+        oldTrackId: 'track-with-trailer',
+        newTrackId: 'track-without-trailer',
+        hasPacketTrailer: false,
+      },
+    });
+  });
+});

package/src/packetTrailer/PacketTrailerManager.ts

@@ -0,0 +1,250 @@
+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 type RemoteTrack from '../room/track/RemoteTrack';
+import RemoteVideoTrack from '../room/track/RemoteVideoTrack';
+import type { PTDecodeMessage, PTUpdateTrackIdMessage, PTWorkerMessage } from './types';
+import { isPacketTrailerSupported, shouldUsePacketTrailerScriptTransform } from './utils';
+
+export interface PacketTrailerOptions {
+  /**
+   * Dedicated worker for extracting packet trailers off the main thread.
+   *
+   * Encoded video streams are transferred to the worker for processing, which
+   * avoids per-frame work on the main thread.
+   */
+  worker: Worker;
+}
+
+/**
+ * Manages packet trailer extraction for received video tracks.
+ *
+ * When a track's TrackInfo indicates packet trailer features, the manager
+ * wires up an encoded frame transform to strip the trailer from encoded frames
+ * and cache the metadata for lookup.
+ *
+ * Packet trailer extraction is worker-only. If no worker is configured, the
+ * SDK does not advertise packet trailer support and skips extraction.
+ *
+ * When E2EE is active, the E2EE FrameCryptor worker handles trailer
+ * extraction directly (before decryption), so this manager only creates
+ * the extractor/metadata cache — no separate pipeline is installed.
+ *
+ * @experimental
+ */
+export class PacketTrailerManager {
+  private worker?: Worker;
+
+  private room?: Room;
+
+  private extractors = new Map<string, PacketTrailerExtractor>();
+
+  /**
+   * Tracks the trackId associated with each receiver that has had its
+   * encoded streams handed off to the worker. Used to detect receiver
+   * reuse (transceiver recycling) so we can remap trackIds instead of
+   * re-transferring already-consumed streams.
+   */
+  private workerPipelines = new Map<RTCRtpReceiver, string>();
+
+  constructor(options?: PacketTrailerOptions) {
+    this.worker = options?.worker;
+  }
+
+  /** @internal */
+  setup(room: Room) {
+    if (room === this.room) {
+      return;
+    }
+    this.room = room;
+
+    if (this.worker) {
+      this.worker.onmessage = this.onWorkerMessage;
+      this.worker.onerror = this.onWorkerError;
+      this.worker.postMessage({ kind: 'init' });
+    }
+
+    room
+      .on(RoomEvent.TrackSubscribed, (track, pub, _participant) => {
+        if (track.kind !== 'video') {
+          return;
+        }
+        this.setupReceiver(track as unknown as RemoteVideoTrack, pub.trackInfo);
+      })
+      .on(RoomEvent.TrackUnsubscribed, (track) => {
+        this.teardownTrack(track);
+      })
+      .on(RoomEvent.Disconnected, () => {
+        this.cleanup();
+      });
+  }
+
+  private setupReceiver(track: RemoteVideoTrack, trackInfo?: TrackInfo) {
+    const receiver = track.receiver;
+    if (!receiver) {
+      return;
+    }
+
+    // Only install a pipeline for tracks that actually advertise packet
+    // trailer features. This keeps us out of the way for tracks published by
+    // clients on older protocols or that don't opt into the feature.
+    const hasFeatures =
+      !!trackInfo?.packetTrailerFeatures && trackInfo.packetTrailerFeatures.length > 0;
+    if (!hasFeatures) {
+      if (!this.room?.hasE2EESetup) {
+        this.setupPassthroughReceiver(receiver, track.mediaStreamID);
+      }
+      return;
+    }
+
+    if (
+      !isPacketTrailerSupported(this.worker ? { worker: this.worker } : undefined) &&
+      !this.room?.hasE2EESetup
+    ) {
+      log.warn('packet trailer transform not supported; skipping extraction');
+      return;
+    }
+
+    const extractor = new PacketTrailerExtractor();
+    const trackId = track.mediaStreamID;
+
+    this.extractors.set(trackId, extractor);
+    track.packetTrailerExtractor = extractor;
+
+    if (this.room?.hasE2EESetup) {
+      // E2EE worker strips the trailer and injects metadata directly into
+      // the extractor via E2eeManager; no pipeline is needed here.
+      return;
+    }
+
+    this.setupWorkerReceiver(receiver, trackId, true);
+  }
+
+  private setupPassthroughReceiver(receiver: RTCRtpReceiver, trackId: string) {
+    if (shouldUsePacketTrailerScriptTransform()) {
+      if ('transform' in receiver) {
+        // @ts-ignore
+        receiver.transform = null;
+      }
+      return;
+    }
+
+    if (
+      this.worker &&
+      isPacketTrailerSupported({ worker: this.worker }) &&
+      !this.workerPipelines.has(receiver)
+    ) {
+      this.setupWorkerReceiver(receiver, trackId, false);
+      return;
+    }
+
+    if (this.worker && this.workerPipelines.has(receiver)) {
+      this.setupWorkerReceiver(receiver, trackId, false);
+    }
+  }
+
+  private setupWorkerReceiver(
+    receiver: RTCRtpReceiver,
+    newTrackId: string,
+    hasPacketTrailer = true,
+  ) {
+    const worker = this.worker;
+    if (!worker) {
+      return;
+    }
+
+    if (shouldUsePacketTrailerScriptTransform()) {
+      // @ts-ignore
+      receiver.transform = new RTCRtpScriptTransform(worker, {
+        kind: 'decode',
+        trackId: newTrackId,
+      });
+      return;
+    }
+
+    const existingTrackId = this.workerPipelines.get(receiver);
+
+    if (existingTrackId) {
+      // Receiver is reused (transceiver recycled). The worker already owns
+      // the encoded streams — just remap the trackId so metadata is keyed
+      // correctly and re-activate processing.
+      const msg: PTUpdateTrackIdMessage = {
+        kind: 'updateTrackId',
+        data: { oldTrackId: existingTrackId, newTrackId, hasPacketTrailer },
+      };
+      worker.postMessage(msg);
+      this.workerPipelines.set(receiver, newTrackId);
+      return;
+    }
+
+    if (!('createEncodedStreams' in receiver)) {
+      log.warn('createEncodedStreams not supported');
+      return;
+    }
+
+    let streams: { readable: ReadableStream; writable: WritableStream };
+    try {
+      // @ts-ignore — createEncodedStreams is not in standard typings
+      streams = receiver.createEncodedStreams();
+    } catch (err) {
+      log.warn('failed to create encoded streams', { error: err });
+      return;
+    }
+
+    const msg: PTDecodeMessage = {
+      kind: 'decode',
+      data: {
+        readableStream: streams.readable,
+        writableStream: streams.writable,
+        trackId: newTrackId,
+        hasPacketTrailer,
+      },
+    };
+    worker.postMessage(msg, [streams.readable, streams.writable]);
+    this.workerPipelines.set(receiver, newTrackId);
+  }
+
+  private teardownTrack(track: RemoteTrack) {
+    const trackId = track.mediaStreamID;
+    const extractor = this.extractors.get(trackId);
+    if (extractor) {
+      extractor.dispose();
+      this.extractors.delete(trackId);
+    }
+
+    if (track instanceof RemoteVideoTrack) {
+      track.packetTrailerExtractor = undefined;
+    }
+
+    // The receiver pipeline is intentionally left running. If the receiver is
+    // reused for a new track, `setupReceiver` will remap it. If the room
+    // disconnects, `cleanup` drops all state. Any metadata produced in the
+    // meantime is harmless — the extractor above has already been disposed and
+    // is no longer reachable from any track.
+  }
+
+  private cleanup() {
+    for (const extractor of this.extractors.values()) {
+      extractor.dispose();
+    }
+    this.extractors.clear();
+    this.workerPipelines.clear();
+    this.worker?.terminate();
+  }
+
+  private onWorkerMessage = (ev: MessageEvent<PTWorkerMessage>) => {
+    const msg = ev.data;
+    if (msg.kind === 'metadata') {
+      const extractor = this.extractors.get(msg.data.trackId);
+      if (extractor) {
+        extractor.storeMetadata(msg.data.rtpTimestamp, msg.data.ssrc, msg.data.metadata);
+      }
+    }
+  };
+
+  private onWorkerError = (ev: ErrorEvent) => {
+    log.error('packet trailer worker encountered an error:', { error: ev.error });
+  };
+}