Add support for packet trailer features

.size-limit.cjs

@@ -2,7 +2,7 @@ module.exports = [
   {
     path: 'dist/livekit-client.esm.mjs',
     import: '{ Room }',
-    limit: '100 kB',
+    limit: '101 kB',
   },
   {
     path: 'dist/livekit-client.umd.js',

examples/demo/demo.ts

@@ -23,6 +23,7 @@ import {
   ParticipantEvent,
   RemoteParticipant,
   RemoteTrackPublication,
+  RemoteVideoTrack,
   Room,
   RoomEvent,
   ScreenSharePresets,
@@ -40,7 +41,10 @@ import {
   supportsAV1,
   supportsVP9,
 } from '../../src/index';
+//@ts-ignore
+import PTWorker from '../../src/packetTrailer/worker/packetTrailer.worker?worker';
 import type { DataTrackFrame } from '../../src/room/data-track/frame';
+import { TrackEvent } from '../../src/room/events';
 import { isSVCCodec, sleep, supportsH265 } from '../../src/room/utils';
 
 setLogLevel(LogLevel.debug);
@@ -106,6 +110,7 @@ const appActions = {
     const cryptoKey = (<HTMLSelectElement>$('crypto-key')).value;
     const autoSubscribe = (<HTMLInputElement>$('auto-subscribe')).checked;
     const e2eeEnabled = (<HTMLInputElement>$('e2ee')).checked;
+    const packetTrailerEnabled = (<HTMLInputElement>$('packet-trailer')).checked;
     const audioOutputId = (<HTMLSelectElement>$('audio-output')).value;
     let backupCodecPolicy: BackupCodecPolicy | undefined;
     if ((<HTMLInputElement>$('multicodec-simulcast')).checked) {
@@ -137,6 +142,7 @@ const appActions = {
       encryption: e2eeEnabled
         ? { keyProvider: state.e2eeKeyProvider, worker: new E2EEWorker() }
         : undefined,
+      packetTrailer: packetTrailerEnabled ? { worker: new PTWorker() } : undefined,
     };
     if (
       roomOpts.publishDefaults?.videoCodec === 'av1' ||
@@ -243,6 +249,35 @@ const appActions = {
         appendLog('subscribed to track', pub.trackSid, participant.identity);
         renderParticipant(participant);
         renderScreenShare(room);
+        if (track instanceof RemoteVideoTrack) {
+          let lastLatencyUpdate = 0;
+          let latencyDisplay = '';
+          track.on(TrackEvent.TimeSyncUpdate, ({ rtpTimestamp }) => {
+            const meta = track.lookupFrameMetadata({ rtpTimestamp });
+            const overlayElm = document.getElementById(`pt-overlay-${participant.identity}`);
+            if (overlayElm && meta) {
+              let text = meta.frameId ? `Frame ID: ${meta.frameId}` : '';
+              if (meta.userTimestamp) {
+                const now = Date.now();
+                const receiveTime = new Date(now);
+                const publishTime = new Date(Number(meta.userTimestamp / 1000n));
+                if (now - lastLatencyUpdate >= 500) {
+                  lastLatencyUpdate = now;
+                  latencyDisplay = `${(receiveTime.getTime() - publishTime.getTime()).toFixed(1)}ms`;
+                }
+                const fmt = (d: Date) => {
+                  const pad = (n: number, w = 2) => String(n).padStart(w, '0');
+                  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}:${pad(d.getMilliseconds(), 3)}`;
+                };
+                text +=
+                  `\nPublish:  ${fmt(publishTime)}` +
+                  `\nReceive:  ${fmt(receiveTime)}` +
+                  `\nLatency:  ${latencyDisplay}`;
+              }
+              overlayElm.textContent = text;
+            }
+          });
+        }
       })
       .on(RoomEvent.TrackUnsubscribed, (_, pub, participant) => {
         appendLog('unsubscribed from track', pub.trackSid);
@@ -850,6 +885,7 @@ function renderParticipant(participant: Participant, remove: boolean = false) {
     div.innerHTML = `
       <video id="video-${identity}"></video>
       <audio id="audio-${identity}"></audio>
+      <div id="pt-overlay-${identity}" class="pt-overlay"></div>
       <div class="info-bar">
         <div id="name-${identity}" class="name">
         </div>

examples/demo/index.html

@@ -70,6 +70,10 @@ <h2>Livekit Sample App</h2>
               <input type="checkbox" class="form-check-input" id="e2ee" />
               <label for="e2ee" class="form-check-label"> E2E Encryption </label>
             </div>
+            <div>
+              <input type="checkbox" class="form-check-input" id="packet-trailer" />
+              <label for="packet-trailer" class="form-check-label"> Packet Trailer </label>
+            </div>
             <div>
               <select id="preferred-codec" class="custom-select" style="width: auto"></select>
             </div>

examples/demo/styles.css

@@ -164,3 +164,19 @@
   position: absolute;
   z-index: 4;
 }
+
+.participant .pt-overlay {
+  position: absolute;
+  top: 4px;
+  left: 4px;
+  padding: 2px 6px;
+  background-color: rgba(0, 0, 0, 0.6);
+  color: #fff;
+  font-family: monospace;
+  font-size: 11px;
+  line-height: 1.4;
+  border-radius: 3px;
+  z-index: 6;
+  pointer-events: none;
+  white-space: pre;
+}

package.json

@@ -15,6 +15,11 @@
       "types": "./dist/src/e2ee/worker/e2ee.worker.d.ts",
       "import": "./dist/livekit-client.e2ee.worker.mjs",
       "require": "./dist/livekit-client.e2ee.worker.js"
+    },
+    "./packet-trailer-worker": {
+      "types": "./dist/src/packetTrailer/worker/packetTrailer.worker.d.ts",
+      "import": "./dist/livekit-client.pt.worker.mjs",
+      "require": "./dist/livekit-client.pt.worker.js"
     }
   },
   "files": [
@@ -29,14 +34,17 @@
       ],
       "./dist/src/e2ee/worker/e2ee.worker.d.ts": [
         "./dist/ts4.2/e2ee/worker/e2ee.worker.d.ts"
+      ],
+      "./dist/src/packetTrailer/worker/packetTrailer.worker.d.ts": [
+        "./dist/ts4.2/packetTrailer/worker/packetTrailer.worker.d.ts"
       ]
     }
   },
   "repository": "git@github.com:livekit/client-sdk-js.git",
   "author": "LiveKit <hello@livekit.io>",
   "license": "Apache-2.0",
   "scripts": {
-    "build": "rollup --config --bundleConfigAsCjs && rollup --config rollup.config.worker.js --bundleConfigAsCjs && pnpm downlevel-dts",
+    "build": "rollup --config --bundleConfigAsCjs && rollup --config rollup.config.worker.js --bundleConfigAsCjs && rollup --config rollup.config.pt-worker.js --bundleConfigAsCjs && pnpm downlevel-dts",
     "build:clean": "rm -rf ./dist && pnpm build",
     "build:watch": "rollup --watch --config --bundleConfigAsCjs",
     "build:worker:watch": "rollup --watch --config rollup.config.worker.js --bundleConfigAsCjs",
@@ -57,7 +65,7 @@
   },
   "dependencies": {
     "@livekit/mutex": "1.1.1",
-    "@livekit/protocol": "1.45.3",
+    "@livekit/protocol": "1.45.6",
     "events": "^3.3.0",
     "jose": "^6.1.0",
     "loglevel": "^1.9.2",

rollup.config.pt-worker.js

@@ -0,0 +1,25 @@
+import terser from '@rollup/plugin-terser';
+import typescript from 'rollup-plugin-typescript2';
+import packageJson from './package.json';
+import { commonPlugins, kebabCaseToPascalCase } from './rollup.config';
+
+export default {
+  input: 'src/packetTrailer/worker/packetTrailer.worker.ts',
+  output: [
+    {
+      file: `dist/${packageJson.name}.pt.worker.mjs`,
+      format: 'es',
+      strict: true,
+      sourcemap: true,
+    },
+    {
+      file: `dist/${packageJson.name}.pt.worker.js`,
+      format: 'umd',
+      strict: true,
+      sourcemap: true,
+      name: kebabCaseToPascalCase(packageJson.name) + '.pt.worker',
+      plugins: [terser()],
+    },
+  ],
+  plugins: [typescript({ tsconfig: './src/packetTrailer/worker/tsconfig.json' }), ...commonPlugins],
+};

src/api/SignalClient.test.ts

@@ -1,10 +1,14 @@
 import {
+  ClientInfo_Capability,
   DisconnectReason,
+  JoinRequest,
   JoinResponse,
   LeaveRequest,
   ReconnectResponse,
   SignalRequest,
   SignalResponse,
+  WrappedJoinRequest,
+  WrappedJoinRequest_Compression,
 } from '@livekit/protocol';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { ConnectionError, ConnectionErrorReason } from '../room/errors';
@@ -60,6 +64,7 @@ interface MockWebSocketStreamOptions {
   connection?: WebSocketConnection;
   opened?: Promise<WebSocketConnection>;
   closed?: Promise<WebSocketCloseInfo>;
+  onUrl?: (url: string) => void;
   readyState?: number;
 }
 
@@ -69,18 +74,19 @@ function mockWebSocketStream(options: MockWebSocketStreamOptions = {}) {
     opened = connection ? Promise.resolve(connection) : new Promise(() => {}),
     closed = new Promise(() => {}),
     readyState = 1,
+    onUrl,
   } = options;
 
-  return vi.mocked(WebSocketStream).mockImplementationOnce(
-    () =>
-      ({
-        url: 'wss://test.livekit.io',
-        opened,
-        closed,
-        close: vi.fn(),
-        readyState,
-      }) as any,
-  );
+  return vi.mocked(WebSocketStream).mockImplementationOnce((url) => {
+    onUrl?.(url);
+    return {
+      url: 'wss://test.livekit.io',
+      opened,
+      closed,
+      close: vi.fn(),
+      readyState,
+    } as any;
+  });
 }
 
 describe('SignalClient.connect', () => {
@@ -99,6 +105,47 @@ describe('SignalClient.connect', () => {
     signalClient = new SignalClient(false);
   });
 
+  async function decodeJoinRequestFromUrl(url: string): Promise<JoinRequest> {
+    const joinRequestParam = new URL(url).searchParams.get('join_request');
+    expect(joinRequestParam).toBeTruthy();
+
+    const paddedBase64Url = joinRequestParam!.padEnd(
+      joinRequestParam!.length + ((4 - (joinRequestParam!.length % 4)) % 4),
+      '=',
+    );
+    const binaryString = atob(paddedBase64Url.replace(/-/g, '+').replace(/_/g, '/'));
+    const wrappedBytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i += 1) {
+      wrappedBytes[i] = binaryString.charCodeAt(i);
+    }
+
+    const wrappedJoinRequest = WrappedJoinRequest.fromBinary(wrappedBytes);
+    if (wrappedJoinRequest.compression === WrappedJoinRequest_Compression.NONE) {
+      return JoinRequest.fromBinary(wrappedJoinRequest.joinRequest);
+    }
+
+    const stream = new DecompressionStream('gzip');
+    const writer = stream.writable.getWriter();
+    writer.write(wrappedJoinRequest.joinRequest);
+    writer.close();
+
+    const chunks: Uint8Array[] = [];
+    const reader = stream.readable.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+    const bytes = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return JoinRequest.fromBinary(bytes);
+  }
+
   describe('Happy Path - Initial Join', () => {
     it('should successfully connect and receive join response', async () => {
       const joinResponse = createJoinResponse();
@@ -113,6 +160,51 @@ describe('SignalClient.connect', () => {
       expect(result).toEqual(joinResponse);
       expect(signalClient.currentState).toBe(SignalConnectionState.CONNECTED);
     });
+
+    it('does not advertise packet trailer capability by default', async () => {
+      const joinResponse = createJoinResponse();
+      const signalResponse = createSignalResponse('join', joinResponse);
+      const mockReadable = createMockReadableStream([signalResponse]);
+      const mockConnection = createMockConnection(mockReadable);
+      let capturedUrl = '';
+
+      mockWebSocketStream({
+        connection: mockConnection,
+        onUrl: (url) => {
+          capturedUrl = url;
+        },
+      });
+
+      await signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions);
+
+      const joinRequest = await decodeJoinRequestFromUrl(capturedUrl);
+      expect(joinRequest.clientInfo?.capabilities).toEqual([]);
+    });
+
+    it('advertises packet trailer capability when provided', async () => {
+      const joinResponse = createJoinResponse();
+      const signalResponse = createSignalResponse('join', joinResponse);
+      const mockReadable = createMockReadableStream([signalResponse]);
+      const mockConnection = createMockConnection(mockReadable);
+      let capturedUrl = '';
+
+      mockWebSocketStream({
+        connection: mockConnection,
+        onUrl: (url) => {
+          capturedUrl = url;
+        },
+      });
+
+      await signalClient.join('wss://test.livekit.io', 'test-token', {
+        ...defaultOptions,
+        clientInfoCapabilities: [ClientInfo_Capability.CAP_PACKET_TRAILER],
+      });
+
+      const joinRequest = await decodeJoinRequestFromUrl(capturedUrl);
+      expect(joinRequest.clientInfo?.capabilities).toEqual([
+        ClientInfo_Capability.CAP_PACKET_TRAILER,
+      ]);
+    });
   });
 
   describe('Happy Path - Reconnect', () => {