livekit-client 2.18.8 → 2.18.10

package/src/e2ee/E2eeManager.ts

@@ -2,16 +2,24 @@ import { Encryption_Type, TrackInfo } from '@livekit/protocol';
 import { EventEmitter } from 'events';
 import type TypedEventEmitter from 'typed-emitter';
 import log, { LogLevel, workerLogger } from '../logger';
+import { hasPacketTrailerPublishOptions } from '../packetTrailer/utils';
 import type RTCEngine from '../room/RTCEngine';
 import type Room from '../room/Room';
 import { ConnectionState } from '../room/Room';
 import { DeviceUnsupportedError } from '../room/errors';
 import { EngineEvent, ParticipantEvent, RoomEvent } from '../room/events';
 import type RemoteTrack from '../room/track/RemoteTrack';
+import RemoteVideoTrack from '../room/track/RemoteVideoTrack';
 import type { Track } from '../room/track/Track';
-import type { VideoCodec } from '../room/track/options';
+import type { TrackPublishOptions, VideoCodec } from '../room/track/options';
 import { mimeTypeToVideoCodecString } from '../room/track/utils';
-import { Future, isChromiumBased, isLocalTrack, isSafariBased, isVideoTrack } from '../room/utils';
+import {
+  Future,
+  isLocalTrack,
+  isSafariBased,
+  isScriptTransformSupportedForWorker,
+  isVideoTrack,
+} from '../room/utils';
 import type { BaseKeyProvider } from './KeyProvider';
 import { E2EE_FLAG } from './constants';
 import { type E2EEManagerCallbacks, EncryptionEvent, KeyProviderEvent } from './events';
@@ -34,7 +42,7 @@ import type {
   SifTrailerMessage,
   UpdateCodecMessage,
 } from './types';
-import { isE2EESupported, isScriptTransformSupported } from './utils';
+import { isE2EESupported } from './utils';
 
 export interface BaseE2EEManager {
   setup(room: Room): void;
@@ -42,11 +50,11 @@ export interface BaseE2EEManager {
   isEnabled: boolean;
   isDataChannelEncryptionEnabled: boolean;
   setParticipantCryptorEnabled(enabled: boolean, participantIdentity: string): void;
-  setSifTrailer(trailer: Uint8Array): void;
-  encryptData(data: Uint8Array): Promise<EncryptDataResponseMessage['data']>;
+  setSifTrailer(trailer: NonSharedUint8Array): void;
+  encryptData(data: NonSharedUint8Array): Promise<EncryptDataResponseMessage['data']>;
   handleEncryptedData(
-    payload: Uint8Array,
-    iv: Uint8Array,
+    payload: NonSharedUint8Array,
+    iv: NonSharedUint8Array,
     participantIdentity: string,
     keyIndex: number,
   ): Promise<DecryptDataResponseMessage['data']>;
@@ -133,7 +141,7 @@ export class E2EEManager
   /**
    * @internal
    */
-  setSifTrailer(trailer: Uint8Array) {
+  setSifTrailer(trailer: NonSharedUint8Array) {
     if (!trailer || trailer.length === 0) {
       log.warn("ignoring server sent trailer as it's empty");
     } else {
@@ -221,6 +229,9 @@ export class E2EEManager
           encryptFuture.resolve(data as EncryptDataResponseMessage['data']);
         }
         break;
+      case 'packetTrailerMetadata':
+        this.handlePacketTrailerMetadata(data.trackId, data.rtpTimestamp, data.ssrc, data.metadata);
+        break;
       default:
         break;
     }
@@ -231,6 +242,33 @@ export class E2EEManager
     this.emit(EncryptionEvent.EncryptionError, ev.error, undefined);
   };
 
+  private handlePacketTrailerMetadata(
+    trackId: string,
+    rtpTimestamp: number,
+    ssrc: number,
+    metadata: { userTimestamp: bigint; frameId: number },
+  ) {
+    if (!this.room) {
+      return;
+    }
+    for (const participant of [
+      this.room.localParticipant,
+      ...this.room.remoteParticipants.values(),
+    ]) {
+      for (const pub of participant.trackPublications.values()) {
+        if (
+          pub.track &&
+          pub.track.mediaStreamID === trackId &&
+          pub.track instanceof RemoteVideoTrack &&
+          pub.track.packetTrailerExtractor
+        ) {
+          pub.track.packetTrailerExtractor.storeMetadata(rtpTimestamp, ssrc, metadata);
+          return;
+        }
+      }
+    }
+  }
+
   public setupEngine(engine: RTCEngine) {
     engine.on(EngineEvent.RTPVideoMapUpdate, (rtpMap) => {
       this.postRTPMap(rtpMap);
@@ -299,6 +337,7 @@ export class E2EEManager
           trackId: publication.track!.mediaStreamID,
           codec: mimeTypeToVideoCodecString(publication.trackInfo!.codecs[0].mimeType),
           participantIdentity: this.room!.localParticipant.identity,
+          hasPacketTrailer: false,
         },
       };
 
@@ -314,7 +353,7 @@ export class E2EEManager
       );
   }
 
-  async encryptData(data: Uint8Array): Promise<EncryptDataResponseMessage['data']> {
+  async encryptData(data: NonSharedUint8Array): Promise<EncryptDataResponseMessage['data']> {
     if (!this.worker) {
       throw Error('could not encrypt data, worker is missing');
     }
@@ -337,8 +376,8 @@ export class E2EEManager
   }
 
   handleEncryptedData(
-    payload: Uint8Array,
-    iv: Uint8Array,
+    payload: NonSharedUint8Array,
+    iv: NonSharedUint8Array,
     participantIdentity: string,
     keyIndex: number,
   ) {
@@ -428,7 +467,7 @@ export class E2EEManager
     this.worker.postMessage(msg);
   }
 
-  private postSifTrailer(trailer: Uint8Array) {
+  private postSifTrailer(trailer: NonSharedUint8Array) {
     if (!this.worker) {
       throw Error('could not post SIF trailer, worker is missing');
     }
@@ -448,11 +487,16 @@ export class E2EEManager
     if (!trackInfo?.mimeType || trackInfo.mimeType === '') {
       throw new TypeError('MimeType missing from trackInfo, cannot set up E2EE cryptor');
     }
+    const hasPacketTrailer =
+      track.kind === 'video' &&
+      !!trackInfo.packetTrailerFeatures &&
+      trackInfo.packetTrailerFeatures.length > 0;
     this.handleReceiver(
       track.receiver,
       track.mediaStreamID,
       remoteId,
       track.kind === 'video' ? mimeTypeToVideoCodecString(trackInfo.mimeType) : undefined,
+      hasPacketTrailer,
     );
   }
 
@@ -461,7 +505,12 @@ export class E2EEManager
       if (!sender) log.warn('early return because sender is not ready');
       return;
     }
-    this.handleSender(sender, track.mediaStreamID, undefined);
+    this.handleSender(
+      sender,
+      track.mediaStreamID,
+      undefined,
+      isVideoTrack(track) ? track.publishOptions?.packetTrailer : undefined,
+    );
   }
 
   /**
@@ -473,35 +522,33 @@ export class E2EEManager
     receiver: RTCRtpReceiver,
     trackId: string,
     participantIdentity: string,
-    codec?: VideoCodec,
+    codec: VideoCodec | undefined,
+    hasPacketTrailer: boolean,
   ) {
     if (!this.worker) {
       return;
     }
 
-    if (
-      isScriptTransformSupported() &&
-      // Chrome occasionally throws an `InvalidState` error when using script transforms directly after introducing this API in 141.
-      // Disabling it for Chrome based browsers until the API has stabilized
-      !isChromiumBased()
-    ) {
+    if (isScriptTransformSupportedForWorker()) {
       const options: ScriptTransformOptions = {
         kind: 'decode',
         participantIdentity,
         trackId,
         codec,
+        hasPacketTrailer,
       };
       // @ts-ignore
       receiver.transform = new RTCRtpScriptTransform(this.worker, options);
     } else {
       if (E2EE_FLAG in receiver && codec) {
-        // only update codec
+        // update track-specific state when the transceiver is reused
         const msg: UpdateCodecMessage = {
           kind: 'updateCodec',
           data: {
             trackId,
             codec,
-            participantIdentity: participantIdentity,
+            participantIdentity,
+            hasPacketTrailer,
           },
         };
         this.worker.postMessage(msg);
@@ -532,6 +579,7 @@ export class E2EEManager
           codec,
           participantIdentity: participantIdentity,
           isReuse: E2EE_FLAG in receiver,
+          hasPacketTrailer,
         },
       };
       this.worker.postMessage(msg, [readable, writable]);
@@ -546,7 +594,12 @@ export class E2EEManager
    * a frame encoder.
    *
    */
-  private handleSender(sender: RTCRtpSender, trackId: string, codec?: VideoCodec) {
+  private handleSender(
+    sender: RTCRtpSender,
+    trackId: string,
+    codec?: VideoCodec,
+    packetTrailer?: TrackPublishOptions['packetTrailer'],
+  ) {
     if (E2EE_FLAG in sender || !this.worker) {
       return;
     }
@@ -555,18 +608,15 @@ export class E2EEManager
       throw TypeError('local identity needs to be known in order to set up encrypted sender');
     }
 
-    if (
-      isScriptTransformSupported() &&
-      // Chrome occasionally throws an `InvalidState` error when using script transforms directly after introducing this API in 141.
-      // Disabling it for Chrome based browsers until the API has stabilized
-      !isChromiumBased()
-    ) {
+    if (isScriptTransformSupportedForWorker()) {
       log.info('initialize script transform');
-      const options = {
+      const options: ScriptTransformOptions = {
         kind: 'encode',
         participantIdentity: this.room.localParticipant.identity,
         trackId,
         codec,
+        hasPacketTrailer: hasPacketTrailerPublishOptions(packetTrailer),
+        packetTrailer,
       };
       // @ts-ignore
       sender.transform = new RTCRtpScriptTransform(this.worker, options);
@@ -583,6 +633,8 @@ export class E2EEManager
           trackId,
           participantIdentity: this.room.localParticipant.identity,
           isReuse: false,
+          hasPacketTrailer: hasPacketTrailerPublishOptions(packetTrailer),
+          packetTrailer,
         },
       };
       this.worker.postMessage(msg, [senderStreams.readable, senderStreams.writable]);

package/src/e2ee/types.ts

@@ -1,4 +1,6 @@
 import type { LogLevel } from '../logger';
+import type { PacketTrailerFramePayload } from '../packetTrailer/packetTrailer';
+import type { PacketTrailerPublishOptions } from '../packetTrailer/types';
 import type { VideoCodec } from '../room/track/options';
 import type { BaseE2EEManager } from './E2eeManager';
 import type { BaseKeyProvider } from './KeyProvider';
@@ -38,7 +40,7 @@ export interface RTPVideoMapMessage extends BaseMessage {
 export interface SifTrailerMessage extends BaseMessage {
   kind: 'setSifTrailer';
   data: {
-    trailer: Uint8Array;
+    trailer: NonSharedUint8Array;
   };
 }
 
@@ -51,6 +53,16 @@ export interface EncodeMessage extends BaseMessage {
     trackId: string;
     codec?: VideoCodec;
     isReuse: boolean;
+    /**
+     * Whether the published track advertises packet trailer features.
+     * When false, the cryptor skips the per-frame trailer extraction path
+     * entirely on decode.
+     */
+    hasPacketTrailer: boolean;
+    /**
+     * Packet trailer metadata to append on published video frames.
+     */
+    packetTrailer?: PacketTrailerPublishOptions;
   };
 }
 
@@ -68,6 +80,7 @@ export interface UpdateCodecMessage extends BaseMessage {
     participantIdentity: string;
     trackId: string;
     codec: VideoCodec;
+    hasPacketTrailer: boolean;
   };
 }
 
@@ -116,8 +129,8 @@ export interface DecryptDataRequestMessage extends BaseMessage {
   kind: 'decryptDataRequest';
   data: {
     uuid: string;
-    payload: Uint8Array;
-    iv: Uint8Array;
+    payload: NonSharedUint8Array;
+    iv: NonSharedUint8Array;
     participantIdentity: string;
     keyIndex: number;
   };
@@ -127,7 +140,7 @@ export interface DecryptDataResponseMessage extends BaseMessage {
   kind: 'decryptDataResponse';
   data: {
     uuid: string;
-    payload: Uint8Array;
+    payload: NonSharedUint8Array;
   };
 }
 
@@ -135,7 +148,7 @@ export interface EncryptDataRequestMessage extends BaseMessage {
   kind: 'encryptDataRequest';
   data: {
     uuid: string;
-    payload: Uint8Array;
+    payload: NonSharedUint8Array;
     participantIdentity: string;
   };
 }
@@ -144,12 +157,17 @@ export interface EncryptDataResponseMessage extends BaseMessage {
   kind: 'encryptDataResponse';
   data: {
     uuid: string;
-    payload: Uint8Array;
-    iv: Uint8Array;
+    payload: NonSharedUint8Array;
+    iv: NonSharedUint8Array;
     keyIndex: number;
   };
 }
 
+export interface PTMetadataFromE2EEMessage extends BaseMessage {
+  kind: 'packetTrailerMetadata';
+  data: PacketTrailerFramePayload;
+}
+
 export type E2EEWorkerMessage =
   | InitMessage
   | SetKeyMessage
@@ -166,7 +184,8 @@ export type E2EEWorkerMessage =
   | DecryptDataRequestMessage
   | DecryptDataResponseMessage
   | EncryptDataRequestMessage
-  | EncryptDataResponseMessage;
+  | EncryptDataResponseMessage
+  | PTMetadataFromE2EEMessage;
 
 export type KeySet = { material: CryptoKey; encryptionKey: CryptoKey };
 
@@ -221,4 +240,14 @@ export type ScriptTransformOptions = {
   participantIdentity: string;
   trackId: string;
   codec?: VideoCodec;
+  /**
+   * Whether the published track advertises packet trailer features.
+   * When false, the cryptor skips the per-frame trailer extraction path
+   * entirely on decode.
+   */
+  hasPacketTrailer: boolean;
+  /**
+   * Packet trailer metadata to append on published video frames.
+   */
+  packetTrailer?: PacketTrailerPublishOptions;
 };

package/src/e2ee/utils.ts

@@ -8,11 +8,12 @@ export function isE2EESupported() {
 
 export function isScriptTransformSupported() {
   // @ts-ignore
-  return typeof window.RTCRtpScriptTransform !== 'undefined';
+  return typeof window !== 'undefined' && typeof window.RTCRtpScriptTransform !== 'undefined';
 }
 
 export function isInsertableStreamSupported() {
   return (
+    typeof window !== 'undefined' &&
     typeof window.RTCRtpSender !== 'undefined' &&
     // @ts-ignore
     typeof window.RTCRtpSender.prototype.createEncodedStreams !== 'undefined'
@@ -26,7 +27,7 @@ export function isVideoFrame(
 }
 
 export async function importKey(
-  keyBytes: Uint8Array | ArrayBuffer,
+  keyBytes: NonSharedUint8Array | ArrayBuffer,
   algorithm: string | { name: string } = { name: ENCRYPTION_ALGORITHM },
   usage: 'derive' | 'encrypt' = 'encrypt',
 ) {
@@ -112,7 +113,7 @@ export async function deriveKeys(material: CryptoKey, options: KeyProviderOption
   return { material, encryptionKey };
 }
 
-export function createE2EEKey(): Uint8Array {
+export function createE2EEKey(): NonSharedUint8Array {
   return window.crypto.getRandomValues(new Uint8Array(32));
 }
 
@@ -127,14 +128,14 @@ export async function ratchet(material: CryptoKey, salt: string): Promise<ArrayB
   return crypto.subtle.deriveBits(algorithmOptions, material, 256);
 }
 
-export function needsRbspUnescaping(frameData: Uint8Array) {
+export function needsRbspUnescaping(frameData: NonSharedUint8Array) {
   for (var i = 0; i < frameData.length - 3; i++) {
     if (frameData[i] == 0 && frameData[i + 1] == 0 && frameData[i + 2] == 3) return true;
   }
   return false;
 }
 
-export function parseRbsp(stream: Uint8Array): Uint8Array {
+export function parseRbsp(stream: NonSharedUint8Array): NonSharedUint8Array {
   const dataOut: number[] = [];
   var length = stream.length;
   for (var i = 0; i < stream.length; ) {
@@ -159,7 +160,7 @@ export function parseRbsp(stream: Uint8Array): Uint8Array {
 const kZerosInStartSequence = 2;
 const kEmulationByte = 3;
 
-export function writeRbsp(data_in: Uint8Array): Uint8Array {
+export function writeRbsp(data_in: NonSharedUint8Array): NonSharedUint8Array {
   const dataOut: number[] = [];
   var numConsecutiveZeros = 0;
   for (var i = 0; i < data_in.length; ++i) {

package/src/e2ee/worker/DataCryptor.ts

@@ -21,11 +21,11 @@ export class DataCryptor {
   }
 
   static async encrypt(
-    data: Uint8Array,
+    data: NonSharedUint8Array,
     keys: ParticipantKeyHandler,
   ): Promise<{
-    payload: Uint8Array;
-    iv: Uint8Array;
+    payload: NonSharedUint8Array;
+    iv: NonSharedUint8Array;
     keyIndex: number;
   }> {
     const iv = DataCryptor.makeIV(performance.now());
@@ -51,14 +51,14 @@ export class DataCryptor {
   }
 
   static async decrypt(
-    data: Uint8Array,
-    iv: Uint8Array,
+    data: NonSharedUint8Array,
+    iv: NonSharedUint8Array,
     keys: ParticipantKeyHandler,
     keyIndex: number = 0,
     initialMaterial?: KeySet,
     ratchetOpts: DecodeRatchetOptions = { ratchetCount: 0 },
   ): Promise<{
-    payload: Uint8Array;
+    payload: NonSharedUint8Array;
   }> {
     const keySet = await keys.getKeySet(keyIndex);
     if (!keySet) {

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

@@ -1,4 +1,6 @@
 import { afterEach, describe, expect, it, vitest } from 'vitest';
+import { appendPacketTrailer, extractPacketTrailer } from '../../packetTrailer/packetTrailer';
+import type { PacketTrailerPublishOptions } from '../../packetTrailer/types';
 import { IV_LENGTH, KEY_PROVIDER_DEFAULTS } from '../constants';
 import { CryptorEvent } from '../events';
 import type { KeyProviderOptions } from '../types';
@@ -13,7 +15,7 @@ function mockEncryptedRTCEncodedVideoFrame(keyIndex: number): RTCEncodedVideoFra
   return mockRTCEncodedVideoFrame(data);
 }
 
-function mockRTCEncodedVideoFrame(data: Uint8Array): RTCEncodedVideoFrame {
+function mockRTCEncodedVideoFrame(data: NonSharedUint8Array): RTCEncodedVideoFrame {
   return {
     data: data.buffer,
     timestamp: vitest.getMockedSystemTime()?.getTime() ?? 0,
@@ -24,7 +26,7 @@ function mockRTCEncodedVideoFrame(data: Uint8Array): RTCEncodedVideoFrame {
   };
 }
 
-function mockFrameTrailer(keyIndex: number): Uint8Array {
+function mockFrameTrailer(keyIndex: number): NonSharedUint8Array {
   const frameTrailer = new Uint8Array(2);
 
   frameTrailer[0] = IV_LENGTH;
@@ -67,14 +69,21 @@ function prepareParticipantTestDecoder(
 function prepareParticipantTestEncoder(
   participantIdentity: string,
   partialKeyProviderOptions: Partial<KeyProviderOptions>,
+  packetTrailer?: PacketTrailerPublishOptions,
 ) {
-  return prepareParticipantTest('encode', participantIdentity, partialKeyProviderOptions);
+  return prepareParticipantTest(
+    'encode',
+    participantIdentity,
+    partialKeyProviderOptions,
+    packetTrailer,
+  );
 }
 
 function prepareParticipantTest(
   mode: 'encode' | 'decode',
   participantIdentity: string,
   partialKeyProviderOptions: Partial<KeyProviderOptions>,
+  packetTrailer?: PacketTrailerPublishOptions,
 ): {
   keys: ParticipantKeyHandler;
   cryptor: FrameCryptor;
@@ -95,7 +104,15 @@ function prepareParticipantTest(
 
   const input = new TestUnderlyingSource<RTCEncodedVideoFrame>();
   const output = new TestUnderlyingSink<RTCEncodedVideoFrame>();
-  cryptor.setupTransform(mode, new ReadableStream(input), new WritableStream(output), 'testTrack');
+  cryptor.setupTransform(
+    mode,
+    new ReadableStream(input),
+    new WritableStream(output),
+    'testTrack',
+    false,
+    undefined,
+    packetTrailer,
+  );
 
   return { keys, cryptor, input, output };
 }
@@ -215,6 +232,127 @@ describe('FrameCryptor', () => {
         vitest.useRealTimers();
       }
     });
+
+    it('appends packet trailer after encryption', async () => {
+      vitest.useFakeTimers();
+      const now = new Date('2025-04-10T12:00:00.123Z');
+      vitest.setSystemTime(now);
+      try {
+        const { keys, input, output } = prepareParticipantTestEncoder(
+          participantIdentity,
+          {},
+          { timestamp: true, frameId: true },
+        );
+
+        await keys.setKey(await createKeyMaterialFromString('key1'), 1);
+
+        const frame = mockRTCEncodedVideoFrame(
+          new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]),
+        );
+
+        input.write(frame);
+        await vitest.waitFor(() => expect(output.chunks).toHaveLength(1));
+
+        const extracted = extractPacketTrailer(frame.data);
+        expect(extracted.metadata?.userTimestamp).toBeGreaterThanOrEqual(
+          BigInt(now.getTime()) * BigInt(1000),
+        );
+        expect(extracted.metadata?.frameId).toBe(1);
+
+        const frameTrailer = new Uint8Array(
+          extracted.data.buffer.slice(extracted.data.byteLength - 2),
+        );
+        expect(frameTrailer[0]).toEqual(IV_LENGTH);
+        expect(frameTrailer[1]).toEqual(1);
+      } finally {
+        vitest.useRealTimers();
+      }
+    });
+
+    it('does not append packet trailer after encryption when no trailer features are enabled', async () => {
+      vitest.useFakeTimers();
+      try {
+        const { keys, input, output } = prepareParticipantTestEncoder(
+          participantIdentity,
+          {},
+          { timestamp: false, frameId: false },
+        );
+
+        await keys.setKey(await createKeyMaterialFromString('key1'), 1);
+
+        const frame = mockRTCEncodedVideoFrame(
+          new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]),
+        );
+
+        input.write(frame);
+        await vitest.waitFor(() => expect(output.chunks).toHaveLength(1));
+
+        const extracted = extractPacketTrailer(frame.data);
+        expect(extracted.metadata).toBeUndefined();
+        expect(extracted.data.byteLength).toBe(frame.data.byteLength);
+
+        const frameTrailer = new Uint8Array(frame.data.slice(frame.data.byteLength - 2));
+        expect(frameTrailer[0]).toEqual(IV_LENGTH);
+        expect(frameTrailer[1]).toEqual(1);
+      } finally {
+        vitest.useRealTimers();
+      }
+    });
+
+    it('appends only timestamp packet trailer metadata after encryption', async () => {
+      vitest.useFakeTimers();
+      const now = new Date('2025-04-10T12:00:00.123Z');
+      vitest.setSystemTime(now);
+      try {
+        const { keys, input, output } = prepareParticipantTestEncoder(
+          participantIdentity,
+          {},
+          { timestamp: true },
+        );
+
+        await keys.setKey(await createKeyMaterialFromString('key1'), 1);
+
+        const frame = mockRTCEncodedVideoFrame(
+          new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]),
+        );
+
+        input.write(frame);
+        await vitest.waitFor(() => expect(output.chunks).toHaveLength(1));
+
+        const extracted = extractPacketTrailer(frame.data);
+        expect(frame.data.byteLength - extracted.data.byteLength).toBe(15);
+        expect(extracted.metadata?.userTimestamp).toBeGreaterThanOrEqual(
+          BigInt(now.getTime()) * BigInt(1000),
+        );
+        expect(extracted.metadata?.frameId).toBe(0);
+      } finally {
+        vitest.useRealTimers();
+      }
+    });
+
+    it('appends only frame id packet trailer metadata after encryption', async () => {
+      const { keys, input, output } = prepareParticipantTestEncoder(
+        participantIdentity,
+        {},
+        { frameId: true },
+      );
+
+      await keys.setKey(await createKeyMaterialFromString('key1'), 1);
+
+      const frame = mockRTCEncodedVideoFrame(
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]),
+      );
+
+      input.write(frame);
+      await vitest.waitFor(() => expect(output.chunks).toHaveLength(1));
+
+      const extracted = extractPacketTrailer(frame.data);
+      expect(frame.data.byteLength - extracted.data.byteLength).toBe(11);
+      expect(extracted.metadata).toEqual({
+        userTimestamp: BigInt(0),
+        frameId: 1,
+      });
+    });
   });
 
   describe('decode', () => {
@@ -391,6 +529,41 @@ describe('FrameCryptor', () => {
       }
     });
 
+    it('posts packet trailer metadata when the advertised trailer path is active', async () => {
+      vitest.useFakeTimers();
+      try {
+        const { cryptor, input, output } = prepareParticipantTestDecoder(participantIdentity, {});
+        const postMessage = vitest.fn();
+        vitest.stubGlobal('postMessage', postMessage);
+        encryptionEnabledMap.set(participantIdentity, false);
+        cryptor.setHasPacketTrailer(true);
+
+        const payload = Uint8Array.from([1, 2, 3, 4]);
+        const trailer = appendPacketTrailer(payload, 1_744_249_600_123_456n, 0);
+        const frame = mockRTCEncodedVideoFrame(trailer);
+
+        input.write(frame);
+        await vitest.advanceTimersToNextTimerAsync();
+
+        expect(new Uint8Array(output.chunks[0].data)).toEqual(payload);
+        expect(postMessage).toHaveBeenCalledWith({
+          kind: 'packetTrailerMetadata',
+          data: {
+            trackId: 'testTrack',
+            rtpTimestamp: frame.timestamp,
+            ssrc: 0,
+            metadata: {
+              userTimestamp: 1_744_249_600_123_456n,
+              frameId: 0,
+            },
+          },
+        });
+      } finally {
+        vitest.unstubAllGlobals();
+        vitest.useRealTimers();
+      }
+    });
+
     it('recovers from delayed use of rotated key', async () => {
       vitest.useFakeTimers();
       try {