livekit-client 2.18.9 → 2.19.0

package/src/packetTrailer/packetTrailer.test.ts

@@ -0,0 +1,174 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  appendPacketTrailer,
+  appendPacketTrailerToEncodedFrame,
+  extractPacketTrailer,
+  processPacketTrailer,
+} from './packetTrailer';
+
+describe('packetTrailer', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('extracts user timestamp and frame id from packet trailer', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const trailer = appendPacketTrailer(payload, 1_744_249_600_123_456n, 42);
+    const extracted = extractPacketTrailer(trailer);
+
+    expect(Array.from(extracted.data)).toEqual(Array.from(payload));
+    expect(extracted.metadata).toEqual({
+      userTimestamp: 1_744_249_600_123_456n,
+      frameId: 42,
+    });
+  });
+
+  it('extracts timestamp-only trailer when frameId is 0', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const trailer = appendPacketTrailer(payload, 1_744_249_600_123_456n, 0);
+    const extracted = extractPacketTrailer(trailer);
+
+    expect(Array.from(extracted.data)).toEqual(Array.from(payload));
+    expect(extracted.metadata).toEqual({
+      userTimestamp: 1_744_249_600_123_456n,
+      frameId: 0,
+    });
+  });
+
+  it('extracts frameId-only trailer when timestamp is 0', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const trailer = appendPacketTrailer(payload, 0n, 42);
+    const extracted = extractPacketTrailer(trailer);
+
+    expect(Array.from(extracted.data)).toEqual(Array.from(payload));
+    expect(extracted.metadata).toEqual({
+      userTimestamp: 0n,
+      frameId: 42,
+    });
+  });
+
+  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);
+
+    expect(Array.from(result)).toEqual(Array.from(payload));
+  });
+
+  it('passes frames through when there is no valid trailer', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4, 5]);
+    const extracted = extractPacketTrailer(payload);
+
+    expect(Array.from(extracted.data)).toEqual(Array.from(payload));
+    expect(extracted.metadata).toBeUndefined();
+  });
+
+  it('uses the encoded frame timestamp when metadata does not include an RTP timestamp', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const trailer = appendPacketTrailer(payload, 1_744_249_600_123_456n, 42);
+    const frame = {
+      data: trailer.buffer,
+      timestamp: 1234,
+      getMetadata() {
+        return {};
+      },
+    } as unknown as RTCEncodedVideoFrame;
+
+    const result = processPacketTrailer(frame, 'track-id');
+
+    expect(result.payload).toEqual({
+      trackId: 'track-id',
+      rtpTimestamp: 1234,
+      ssrc: 0,
+      metadata: {
+        userTimestamp: 1_744_249_600_123_456n,
+        frameId: 42,
+      },
+    });
+  });
+
+  it('appends timestamp-only packet trailer to encoded frames', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2025-04-10T12:00:00.123Z'));
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const frame = { data: payload.buffer } as RTCEncodedVideoFrame;
+
+    appendPacketTrailerToEncodedFrame(frame, { timestamp: true }, 0);
+    const extracted = extractPacketTrailer(frame.data);
+
+    expect(Array.from(extracted.data)).toEqual(Array.from(payload));
+    expect(frame.data.byteLength).toBe(payload.byteLength + 15);
+    expect(extracted.metadata).toEqual({
+      userTimestamp: BigInt(Date.now()) * BigInt(1000),
+      frameId: 0,
+    });
+  });
+
+  it('appends frame-id-only packet trailer to encoded frames', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const firstFrame = { data: payload.buffer.slice(0) } as RTCEncodedVideoFrame;
+    const secondFrame = { data: payload.buffer.slice(0) } as RTCEncodedVideoFrame;
+
+    appendPacketTrailerToEncodedFrame(firstFrame, { frameId: true }, 1);
+    appendPacketTrailerToEncodedFrame(secondFrame, { frameId: true }, 2);
+
+    expect(firstFrame.data.byteLength).toBe(payload.byteLength + 11);
+    expect(secondFrame.data.byteLength).toBe(payload.byteLength + 11);
+    expect(extractPacketTrailer(firstFrame.data).metadata).toEqual({
+      userTimestamp: 0n,
+      frameId: 1,
+    });
+    expect(extractPacketTrailer(secondFrame.data).metadata).toEqual({
+      userTimestamp: 0n,
+      frameId: 2,
+    });
+  });
+
+  it('appends both timestamp and frame id to encoded frames', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2025-04-10T12:00:00.123Z'));
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const frame = { data: payload.buffer } as RTCEncodedVideoFrame;
+
+    appendPacketTrailerToEncodedFrame(frame, { timestamp: true, frameId: true }, 7);
+
+    expect(extractPacketTrailer(frame.data).metadata).toEqual({
+      userTimestamp: BigInt(Date.now()) * BigInt(1000),
+      frameId: 7,
+    });
+  });
+
+  it.each([{}, { timestamp: false, frameId: false }])(
+    'passes encoded frames through when no write features are enabled: %o',
+    (packetTrailer) => {
+      const payload = Uint8Array.from([1, 2, 3, 4]);
+      const frame = { data: payload.buffer } as RTCEncodedVideoFrame;
+
+      const changed = appendPacketTrailerToEncodedFrame(frame, packetTrailer, 1);
+
+      expect(changed).toBe(false);
+      expect(frame.data).toBe(payload.buffer);
+      expect(extractPacketTrailer(frame.data).metadata).toBeUndefined();
+    },
+  );
+
+  it('passes encoded frames through when publish options omit enabled features', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const frame = { data: payload.buffer } as RTCEncodedVideoFrame;
+
+    const changed = appendPacketTrailerToEncodedFrame(frame, { timestamp: false }, 1);
+
+    expect(changed).toBe(false);
+    expect(frame.data).toBe(payload.buffer);
+    expect(extractPacketTrailer(frame.data).metadata).toBeUndefined();
+  });
+
+  it('passes encoded frames through when publish options are undefined', () => {
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const frame = { data: payload.buffer } as RTCEncodedVideoFrame;
+
+    const changed = appendPacketTrailerToEncodedFrame(frame, undefined, 1);
+
+    expect(changed).toBe(false);
+    expect(frame.data).toBe(payload.buffer);
+  });
+});

package/src/packetTrailer/packetTrailer.ts

@@ -0,0 +1,276 @@
+import type { PacketTrailerMetadata, PacketTrailerPublishOptions } from './types';
+import { hasPacketTrailerPublishOptions } from './utils';
+
+export const PACKET_TRAILER_MAGIC = Uint8Array.from([
+  'L'.charCodeAt(0),
+  'K'.charCodeAt(0),
+  'T'.charCodeAt(0),
+  'S'.charCodeAt(0),
+]);
+
+export const PACKET_TRAILER_TIMESTAMP_TAG = 0x01;
+export const PACKET_TRAILER_FRAME_ID_TAG = 0x02;
+export const PACKET_TRAILER_ENVELOPE_SIZE = 5;
+
+const TIMESTAMP_TLV_SIZE = 10;
+const FRAME_ID_TLV_SIZE = 6;
+
+export interface ExtractPacketTrailerResult {
+  data: Uint8Array;
+  metadata?: PacketTrailerMetadata;
+}
+
+export function appendPacketTrailer(
+  data: Uint8Array,
+  userTimestamp: bigint,
+  frameId: number,
+): Uint8Array {
+  const hasTimestamp = userTimestamp !== BigInt(0);
+  const hasFrameId = frameId !== 0;
+
+  if (!hasTimestamp && !hasFrameId) {
+    return data;
+  }
+
+  const trailerLength =
+    (hasTimestamp ? TIMESTAMP_TLV_SIZE : 0) +
+    (hasFrameId ? FRAME_ID_TLV_SIZE : 0) +
+    PACKET_TRAILER_ENVELOPE_SIZE;
+  const result = new Uint8Array(data.length + trailerLength);
+  let offset = 0;
+
+  result.set(data, offset);
+  offset += data.length;
+
+  if (hasTimestamp) {
+    result[offset++] = PACKET_TRAILER_TIMESTAMP_TAG ^ 0xff;
+    result[offset++] = 8 ^ 0xff;
+    writeUint64Xor(result, offset, userTimestamp);
+    offset += 8;
+  }
+
+  if (hasFrameId) {
+    result[offset++] = PACKET_TRAILER_FRAME_ID_TAG ^ 0xff;
+    result[offset++] = 4 ^ 0xff;
+    writeUint32Xor(result, offset, frameId);
+    offset += 4;
+  }
+
+  result[offset++] = trailerLength ^ 0xff;
+  result.set(PACKET_TRAILER_MAGIC, offset);
+
+  return result;
+}
+
+export function appendPacketTrailerToEncodedFrame(
+  frame: RTCEncodedVideoFrame,
+  options: PacketTrailerPublishOptions | undefined,
+  frameId: number,
+): boolean {
+  if (!hasPacketTrailerPublishOptions(options) || frame.data.byteLength === 0) {
+    return false;
+  }
+
+  const userTimestamp = options?.timestamp ? BigInt(Date.now()) * BigInt(1000) : BigInt(0);
+  const packetTrailerFrameId = options?.frameId ? frameId : 0;
+  const data = new Uint8Array(frame.data);
+  const result = appendPacketTrailer(data, userTimestamp, packetTrailerFrameId);
+
+  if (result.byteLength === data.byteLength) {
+    return false;
+  }
+
+  frame.data = result.buffer.slice(
+    result.byteOffset,
+    result.byteOffset + result.byteLength,
+  ) as ArrayBuffer;
+  return true;
+}
+
+export function extractPacketTrailer(data: ArrayBuffer | Uint8Array): ExtractPacketTrailerResult {
+  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  if (bytes.length < PACKET_TRAILER_ENVELOPE_SIZE) {
+    return { data: bytes };
+  }
+
+  const magicOffset = bytes.length - PACKET_TRAILER_MAGIC.length;
+  if (!matchesMagic(bytes, magicOffset)) {
+    return { data: bytes };
+  }
+
+  const trailerLength = bytes[bytes.length - PACKET_TRAILER_ENVELOPE_SIZE] ^ 0xff;
+  if (trailerLength < PACKET_TRAILER_ENVELOPE_SIZE || trailerLength > bytes.length) {
+    return { data: bytes };
+  }
+
+  const trailerStart = bytes.length - trailerLength;
+  const trailerEnd = bytes.length - PACKET_TRAILER_ENVELOPE_SIZE;
+  const strippedData = bytes.subarray(0, trailerStart);
+  let offset = trailerStart;
+  let foundAny = false;
+  const metadata: PacketTrailerMetadata = {
+    userTimestamp: BigInt(0),
+    frameId: 0,
+  };
+
+  while (offset + 2 <= trailerEnd) {
+    const tag = bytes[offset++] ^ 0xff;
+    const length = bytes[offset++] ^ 0xff;
+
+    if (offset + length > trailerEnd) {
+      break;
+    }
+
+    if (tag === PACKET_TRAILER_TIMESTAMP_TAG && length === 8) {
+      metadata.userTimestamp = readUint64Xor(bytes, offset);
+      foundAny = true;
+    } else if (tag === PACKET_TRAILER_FRAME_ID_TAG && length === 4) {
+      metadata.frameId = readUint32Xor(bytes, offset, length);
+      foundAny = true;
+    }
+
+    offset += length;
+  }
+
+  if (!foundAny) {
+    return { data: bytes };
+  }
+
+  return { data: strippedData, metadata };
+}
+
+function matchesMagic(data: Uint8Array, offset: number) {
+  for (let index = 0; index < PACKET_TRAILER_MAGIC.length; index += 1) {
+    if (data[offset + index] !== PACKET_TRAILER_MAGIC[index]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function readUint64Xor(data: Uint8Array, offset: number): bigint {
+  const hi = BigInt(
+    (((data[offset] ^ 0xff) << 24) |
+      ((data[offset + 1] ^ 0xff) << 16) |
+      ((data[offset + 2] ^ 0xff) << 8) |
+      (data[offset + 3] ^ 0xff)) >>>
+      0,
+  );
+  const lo = BigInt(
+    (((data[offset + 4] ^ 0xff) << 24) |
+      ((data[offset + 5] ^ 0xff) << 16) |
+      ((data[offset + 6] ^ 0xff) << 8) |
+      (data[offset + 7] ^ 0xff)) >>>
+      0,
+  );
+  return (hi << BigInt(32)) | lo;
+}
+
+function readUint32Xor(data: Uint8Array, offset: number, length: number) {
+  let value = 0;
+  for (let index = 0; index < length; index += 1) {
+    value = (value << 8) | (data[offset + index] ^ 0xff);
+  }
+  return value >>> 0;
+}
+
+function writeUint64Xor(target: Uint8Array, offset: number, value: bigint) {
+  const hi = Number((value >> BigInt(32)) & BigInt(0xffffffff));
+  const lo = Number(value & BigInt(0xffffffff));
+  target[offset] = (hi >>> 24) ^ 0xff;
+  target[offset + 1] = ((hi >>> 16) & 0xff) ^ 0xff;
+  target[offset + 2] = ((hi >>> 8) & 0xff) ^ 0xff;
+  target[offset + 3] = (hi & 0xff) ^ 0xff;
+  target[offset + 4] = (lo >>> 24) ^ 0xff;
+  target[offset + 5] = ((lo >>> 16) & 0xff) ^ 0xff;
+  target[offset + 6] = ((lo >>> 8) & 0xff) ^ 0xff;
+  target[offset + 7] = (lo & 0xff) ^ 0xff;
+}
+
+function writeUint32Xor(target: Uint8Array, offset: number, value: number) {
+  for (let index = 3; index >= 0; index -= 1) {
+    target[offset + (3 - index)] = ((value >> (index * 8)) & 0xff) ^ 0xff;
+  }
+}
+
+export function getFrameRtpTimestamp(
+  frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
+): number | undefined {
+  try {
+    const metadata = frame.getMetadata() as Record<string, unknown>;
+    if (typeof metadata.rtpTimestamp === 'number') {
+      return metadata.rtpTimestamp;
+    }
+    if (typeof metadata.timestamp === 'number') {
+      return metadata.timestamp;
+    }
+  } catch {
+    // getMetadata() might not be available
+  }
+  if (typeof frame.timestamp === 'number') {
+    return frame.timestamp;
+  }
+  return undefined;
+}
+
+export function getFrameSsrc(frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame): number {
+  try {
+    const metadata = frame.getMetadata() as Record<string, unknown>;
+    if (typeof metadata.synchronizationSource === 'number') {
+      return metadata.synchronizationSource;
+    }
+  } catch {}
+  return 0;
+}
+
+export interface PacketTrailerFramePayload {
+  trackId: string;
+  rtpTimestamp: number;
+  ssrc: number;
+  metadata: PacketTrailerMetadata;
+}
+
+export interface ProcessPacketTrailerResult {
+  data?: ArrayBuffer;
+  payload?: PacketTrailerFramePayload;
+}
+
+/**
+ * Extracts a packet trailer from an encoded frame and returns the stripped
+ * frame data (if any) along with a ready-to-post metadata payload. Returns an
+ * empty object when no trailer is present, an RTP timestamp can't be read, or
+ * a trackId isn't available.
+ */
+export function processPacketTrailer(
+  frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
+  trackId: string | undefined,
+): ProcessPacketTrailerResult {
+  if (frame.data.byteLength === 0) {
+    return {};
+  }
+
+  const result = extractPacketTrailer(frame.data);
+  if (!result.metadata) {
+    return {};
+  }
+
+  const strippedData = (result.data.buffer as ArrayBuffer).slice(
+    result.data.byteOffset,
+    result.data.byteOffset + result.data.byteLength,
+  );
+
+  const rtpTimestamp = getFrameRtpTimestamp(frame);
+  if (rtpTimestamp === undefined || !trackId) {
+    return { data: strippedData };
+  }
+
+  return {
+    data: strippedData,
+    payload: {
+      trackId,
+      rtpTimestamp,
+      ssrc: getFrameSsrc(frame),
+      metadata: result.metadata,
+    },
+  };
+}

package/src/packetTrailer/types.ts

@@ -0,0 +1,75 @@
+import type { PacketTrailerFramePayload } from './packetTrailer';
+
+export interface PacketTrailerMetadata {
+  userTimestamp: bigint;
+  frameId: number;
+}
+
+export interface PacketTrailerPublishOptions {
+  timestamp?: boolean;
+  frameId?: boolean;
+}
+
+export interface PTBaseMessage {
+  kind: string;
+  data?: unknown;
+}
+
+export interface PTInitMessage extends PTBaseMessage {
+  kind: 'init';
+}
+
+export interface PTInitAck extends PTBaseMessage {
+  kind: 'initAck';
+}
+
+export interface PTDecodeMessage extends PTBaseMessage {
+  kind: 'decode';
+  data: {
+    readableStream: ReadableStream;
+    writableStream: WritableStream;
+    trackId: string;
+    hasPacketTrailer: boolean;
+  };
+}
+
+export interface PTEncodeMessage extends PTBaseMessage {
+  kind: 'encode';
+  data: {
+    readableStream: ReadableStream;
+    writableStream: WritableStream;
+    packetTrailer?: PacketTrailerPublishOptions;
+  };
+}
+
+export type PTScriptTransformOptions =
+  | {
+      kind: 'decode';
+      trackId: string;
+    }
+  | {
+      kind: 'encode';
+      packetTrailer?: PacketTrailerPublishOptions;
+    };
+
+export interface PTMetadataMessage extends PTBaseMessage {
+  kind: 'metadata';
+  data: PacketTrailerFramePayload;
+}
+
+export interface PTUpdateTrackIdMessage extends PTBaseMessage {
+  kind: 'updateTrackId';
+  data: {
+    oldTrackId: string;
+    newTrackId: string;
+    hasPacketTrailer: boolean;
+  };
+}
+
+export type PTWorkerMessage =
+  | PTInitMessage
+  | PTInitAck
+  | PTDecodeMessage
+  | PTEncodeMessage
+  | PTUpdateTrackIdMessage
+  | PTMetadataMessage;

package/src/packetTrailer/utils.test.ts

@@ -0,0 +1,105 @@
+import { PacketTrailerFeature } from '@livekit/protocol';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  getPacketTrailerFeatures,
+  getPacketTrailerPublishOptions,
+  isPacketTrailerSupported,
+} from './utils';
+
+describe('packet trailer support', () => {
+  const originalRTCRtpSender = window.RTCRtpSender;
+  const originalRTCRtpScriptTransform = (window as unknown as { RTCRtpScriptTransform?: unknown })
+    .RTCRtpScriptTransform;
+  const originalUserAgent = navigator.userAgent;
+
+  afterEach(() => {
+    Object.defineProperty(window, 'RTCRtpSender', {
+      configurable: true,
+      value: originalRTCRtpSender,
+      writable: true,
+    });
+    Object.defineProperty(window, 'RTCRtpScriptTransform', {
+      configurable: true,
+      value: originalRTCRtpScriptTransform,
+      writable: true,
+    });
+    Object.defineProperty(window.navigator, 'userAgent', {
+      configurable: true,
+      value: originalUserAgent,
+    });
+  });
+
+  function stubScriptTransformSupport(userAgent: string) {
+    Object.defineProperty(window, 'RTCRtpSender', {
+      configurable: true,
+      value: undefined,
+      writable: true,
+    });
+    Object.defineProperty(window, 'RTCRtpScriptTransform', {
+      configurable: true,
+      value: class MockRTCRtpScriptTransform {},
+      writable: true,
+    });
+    Object.defineProperty(window.navigator, 'userAgent', {
+      configurable: true,
+      value: userAgent,
+    });
+  }
+
+  it('supports packet trailers 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);
+  });
+
+  it('supports packet trailers 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);
+  });
+
+  it('does not use RTCRtpScriptTransform support on Chromium-based browsers', () => {
+    stubScriptTransformSupport(
+      '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);
+  });
+});
+
+describe('packet trailer publish features', () => {
+  it('maps publish options to protocol features', () => {
+    expect(getPacketTrailerFeatures({ timestamp: true, frameId: true })).toEqual([
+      PacketTrailerFeature.PTF_USER_TIMESTAMP,
+      PacketTrailerFeature.PTF_FRAME_ID,
+    ]);
+    expect(getPacketTrailerFeatures({ timestamp: true })).toEqual([
+      PacketTrailerFeature.PTF_USER_TIMESTAMP,
+    ]);
+    expect(getPacketTrailerFeatures({ frameId: true })).toEqual([
+      PacketTrailerFeature.PTF_FRAME_ID,
+    ]);
+    expect(getPacketTrailerFeatures()).toEqual([]);
+  });
+
+  it('maps protocol features to publish options', () => {
+    expect(
+      getPacketTrailerPublishOptions([
+        PacketTrailerFeature.PTF_USER_TIMESTAMP,
+        PacketTrailerFeature.PTF_FRAME_ID,
+      ]),
+    ).toEqual({ timestamp: true, frameId: true });
+    expect(getPacketTrailerPublishOptions([PacketTrailerFeature.PTF_USER_TIMESTAMP])).toEqual({
+      timestamp: true,
+    });
+    expect(getPacketTrailerPublishOptions([PacketTrailerFeature.PTF_FRAME_ID])).toEqual({
+      frameId: true,
+    });
+    expect(getPacketTrailerPublishOptions()).toBeUndefined();
+    expect(getPacketTrailerPublishOptions([])).toBeUndefined();
+  });
+});

package/src/packetTrailer/utils.ts

@@ -0,0 +1,50 @@
+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';
+
+export function shouldUsePacketTrailerScriptTransform() {
+  return isScriptTransformSupportedForWorker();
+}
+
+export function isPacketTrailerSupported(options?: PacketTrailerOptions) {
+  return (
+    !!options?.worker && (isInsertableStreamSupported() || shouldUsePacketTrailerScriptTransform())
+  );
+}
+
+export function hasPacketTrailerPublishOptions(options?: PacketTrailerPublishOptions): boolean {
+  return !!(options?.timestamp || options?.frameId);
+}
+
+export function getPacketTrailerFeatures(
+  options?: PacketTrailerPublishOptions,
+): PacketTrailerFeature[] {
+  const features: PacketTrailerFeature[] = [];
+  if (options?.timestamp) {
+    features.push(PacketTrailerFeature.PTF_USER_TIMESTAMP);
+  }
+  if (options?.frameId) {
+    features.push(PacketTrailerFeature.PTF_FRAME_ID);
+  }
+  return features;
+}
+
+export function getPacketTrailerPublishOptions(
+  features?: PacketTrailerFeature[],
+): PacketTrailerPublishOptions | undefined {
+  if (!features || features.length === 0) {
+    return undefined;
+  }
+
+  const options: PacketTrailerPublishOptions = {};
+  if (features.includes(PacketTrailerFeature.PTF_USER_TIMESTAMP)) {
+    options.timestamp = true;
+  }
+  if (features.includes(PacketTrailerFeature.PTF_FRAME_ID)) {
+    options.frameId = true;
+  }
+
+  return options.timestamp || options.frameId ? options : undefined;
+}