livekit-client 2.18.8 → 2.18.10

package/src/e2ee/worker/FrameCryptor.ts

@@ -1,13 +1,24 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
 // TODO code inspired by https://github.com/webrtc/samples/blob/gh-pages/src/content/insertable-streams/endtoend-encryption/js/worker.js
 import { EventEmitter } from 'events';
 import type TypedEventEmitter from 'typed-emitter';
 import { workerLogger } from '../../logger';
+import {
+  appendPacketTrailerToEncodedFrame,
+  processPacketTrailer,
+} from '../../packetTrailer/packetTrailer';
+import type { PacketTrailerPublishOptions } from '../../packetTrailer/types';
+import { hasPacketTrailerPublishOptions } from '../../packetTrailer/utils';
 import type { VideoCodec } from '../../room/track/options';
 import { ENCRYPTION_ALGORITHM, IV_LENGTH, UNENCRYPTED_BYTES } from '../constants';
 import { CryptorError, CryptorErrorReason } from '../errors';
 import { type CryptorCallbacks, CryptorEvent } from '../events';
-import type { DecodeRatchetOptions, KeyProviderOptions, KeySet, RatchetResult } from '../types';
+import type {
+  DecodeRatchetOptions,
+  KeyProviderOptions,
+  KeySet,
+  PTMetadataFromE2EEMessage,
+  RatchetResult,
+} from '../types';
 import { deriveKeys, isVideoFrame, needsRbspUnescaping, parseRbsp, writeRbsp } from '../utils';
 import type { ParticipantKeyHandler } from './ParticipantKeyHandler';
 import { processNALUsForEncryption } from './naluUtils';
@@ -65,12 +76,23 @@ export class FrameCryptor extends BaseFrameCryptor {
   /**
    * used for detecting server injected unencrypted frames
    */
-  private sifTrailer: Uint8Array;
+  private sifTrailer: NonSharedUint8Array;
 
   private detectedCodec?: VideoCodec;
 
   private currentTransform?: TransformerInfo;
 
+  /**
+   * Whether the subscribed track advertises packet trailer features.
+   * When false, we skip the per-frame trailer extraction path entirely
+   * on decode to avoid unnecessary work on tracks that don't use it.
+   */
+  private hasPacketTrailer: boolean = false;
+
+  private packetTrailer?: PacketTrailerPublishOptions;
+
+  private packetTrailerFrameId = 0;
+
   /**
    * Throttling mechanism for decryption errors to prevent memory leaks
    */
@@ -88,7 +110,7 @@ export class FrameCryptor extends BaseFrameCryptor {
     keys: ParticipantKeyHandler;
     participantIdentity: string;
     keyProviderOptions: KeyProviderOptions;
-    sifTrailer?: Uint8Array;
+    sifTrailer?: NonSharedUint8Array;
   }) {
     super();
     this.sendCounts = new Map();
@@ -178,6 +200,20 @@ export class FrameCryptor extends BaseFrameCryptor {
     this.rtpMap = map;
   }
 
+  /**
+   * Sets whether the track associated with this cryptor carries packet
+   * trailer data. When false, {@link decodeFunction} skips the per-frame
+   * trailer extraction branch entirely.
+   */
+  setHasPacketTrailer(hasPacketTrailer: boolean) {
+    this.hasPacketTrailer = hasPacketTrailer;
+  }
+
+  setPacketTrailer(packetTrailer?: PacketTrailerPublishOptions) {
+    this.packetTrailer = packetTrailer;
+    this.packetTrailerFrameId = 0;
+  }
+
   setupTransform(
     operation: 'encode' | 'decode',
     readable: ReadableStream<RTCEncodedVideoFrame | RTCEncodedAudioFrame>,
@@ -185,11 +221,15 @@ export class FrameCryptor extends BaseFrameCryptor {
     trackId: string,
     isReuse: boolean,
     codec?: VideoCodec,
+    packetTrailer?: PacketTrailerPublishOptions,
   ) {
     if (codec) {
       workerLogger.info('setting codec on cryptor to', { codec });
       this.videoCodec = codec;
     }
+    if (operation === 'encode') {
+      this.setPacketTrailer(packetTrailer);
+    }
 
     workerLogger.debug('Setting up frame cryptor transform', {
       operation,
@@ -262,7 +302,7 @@ export class FrameCryptor extends BaseFrameCryptor {
       });
   }
 
-  setSifTrailer(trailer: Uint8Array) {
+  setSifTrailer(trailer: NonSharedUint8Array) {
     workerLogger.debug('setting SIF trailer', { ...this.logContext, trailer });
     this.sifTrailer = trailer;
   }
@@ -353,11 +393,13 @@ export class FrameCryptor extends BaseFrameCryptor {
     encodedFrame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
     controller: TransformStreamDefaultController,
   ) {
-    if (
-      !this.isEnabled() ||
-      // skip for encryption for empty dtx frames
-      encodedFrame.data.byteLength === 0
-    ) {
+    // skip for encryption and packet trailer writes for empty dtx frames
+    if (encodedFrame.data.byteLength === 0) {
+      return controller.enqueue(encodedFrame);
+    }
+
+    if (!this.isEnabled()) {
+      this.appendPacketTrailer(encodedFrame);
       return controller.enqueue(encodedFrame);
     }
     const keySet = this.keys.getKeySet();
@@ -410,7 +452,7 @@ export class FrameCryptor extends BaseFrameCryptor {
           new Uint8Array(encodedFrame.data, frameInfo.unencryptedBytes),
         );
 
-        let newDataWithoutHeader = new Uint8Array(
+        let newDataWithoutHeader: NonSharedUint8Array = new Uint8Array(
           cipherText.byteLength + iv.byteLength + frameTrailer.byteLength,
         );
         newDataWithoutHeader.set(new Uint8Array(cipherText)); // add ciphertext.
@@ -426,6 +468,7 @@ export class FrameCryptor extends BaseFrameCryptor {
         newData.set(newDataWithoutHeader, frameHeader.byteLength);
 
         encodedFrame.data = newData.buffer;
+        this.appendPacketTrailer(encodedFrame);
 
         return controller.enqueue(encodedFrame);
       } catch (e: any) {
@@ -444,6 +487,18 @@ export class FrameCryptor extends BaseFrameCryptor {
     }
   }
 
+  private appendPacketTrailer(encodedFrame: RTCEncodedVideoFrame | RTCEncodedAudioFrame) {
+    if (!hasPacketTrailerPublishOptions(this.packetTrailer) || !isVideoFrame(encodedFrame)) {
+      return;
+    }
+
+    if (this.packetTrailer?.frameId) {
+      this.packetTrailerFrameId =
+        this.packetTrailerFrameId === 0xffffffff ? 1 : this.packetTrailerFrameId + 1;
+    }
+    appendPacketTrailerToEncodedFrame(encodedFrame, this.packetTrailer, this.packetTrailerFrameId);
+  }
+
   /**
    * Function that will be injected in a stream and will decrypt the given encoded frames.
    *
@@ -454,6 +509,24 @@ export class FrameCryptor extends BaseFrameCryptor {
     encodedFrame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
     controller: TransformStreamDefaultController,
   ) {
+    if (this.hasPacketTrailer && isVideoFrame(encodedFrame)) {
+      try {
+        const ptResult = processPacketTrailer(encodedFrame, this.trackId);
+        if (ptResult.data) {
+          encodedFrame.data = ptResult.data;
+        }
+        if (ptResult.payload && this.participantIdentity) {
+          const msg: PTMetadataFromE2EEMessage = {
+            kind: 'packetTrailerMetadata',
+            data: ptResult.payload,
+          };
+          postMessage(msg);
+        }
+      } catch {
+        // best-effort: never break the media pipeline if trailer parsing fails
+      }
+    }
+
     if (
       !this.isEnabled() ||
       // skip for decryption for empty dtx frames
@@ -540,8 +613,12 @@ export class FrameCryptor extends BaseFrameCryptor {
     // ---------+-------------------------+-+---------+----
 
     try {
-      const frameHeader = new Uint8Array(encodedFrame.data, 0, frameInfo.unencryptedBytes);
-      var encryptedData = new Uint8Array(
+      const frameHeader: NonSharedUint8Array = new Uint8Array(
+        encodedFrame.data,
+        0,
+        frameInfo.unencryptedBytes,
+      );
+      var encryptedData: NonSharedUint8Array = new Uint8Array(
         encodedFrame.data,
         frameHeader.length,
         encodedFrame.data.byteLength - frameHeader.length,
@@ -758,7 +835,10 @@ export class FrameCryptor extends BaseFrameCryptor {
  * by the livekit server and thus to be treated as unencrypted
  * @internal
  */
-export function isFrameServerInjected(frameData: ArrayBuffer, trailerBytes: Uint8Array): boolean {
+export function isFrameServerInjected(
+  frameData: ArrayBuffer,
+  trailerBytes: NonSharedUint8Array,
+): boolean {
   if (trailerBytes.byteLength === 0) {
     return false;
   }

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

@@ -261,7 +261,7 @@ describe('ParticipantKeyHandler', () => {
 
       await keyHandler.setKey(originalMaterial);
 
-      const ciphertexts: Uint8Array[] = [];
+      const ciphertexts: NonSharedUint8Array[] = [];
 
       const plaintext = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]);
 
@@ -354,8 +354,8 @@ describe('ParticipantKeyHandler', () => {
     async function encrypt(
       participantKeyHandler: ParticipantKeyHandler,
       keyIndex: number,
-      iv: Uint8Array,
-      data: Uint8Array,
+      iv: NonSharedUint8Array,
+      data: NonSharedUint8Array,
     ): Promise<ArrayBuffer> {
       return crypto.subtle.encrypt(
         {
@@ -370,7 +370,7 @@ describe('ParticipantKeyHandler', () => {
     async function decrypt(
       participantKeyHandler: ParticipantKeyHandler,
       keyIndex: number,
-      iv: Uint8Array,
+      iv: NonSharedUint8Array,
       cipherText: ArrayBuffer,
     ): Promise<ArrayBuffer> {
       return crypto.subtle.decrypt(

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,
+      },
+    });
+  });
+});