livekit-client 2.22.0 → 2.22.2

package/src/room/statsSummary.ts

@@ -0,0 +1,187 @@
+/** one summarised stats entry; keys without a value are dropped */
+type Summary = Record<string, unknown>;
+
+function compact<T extends Summary>(summary: T): Summary {
+  const compacted: Summary = {};
+  for (const [key, value] of Object.entries(summary)) {
+    if (value !== undefined) {
+      compacted[key] = value;
+    }
+  }
+  return compacted;
+}
+
+function resolution(width?: number, height?: number): string | undefined {
+  return width && height ? `${width}x${height}` : undefined;
+}
+
+/** keeps the derived durations readable; reported values are logged as they are */
+function round(seconds: number): number {
+  return Math.round(seconds * 10_000) / 10_000;
+}
+
+/**
+ * Average time media spent in the jitter buffer, in s. Both counters are
+ * cumulative, so this is the average over the lifetime of the stream.
+ */
+function jitterBuffer(stat: Summary): number | undefined {
+  const delay = stat.jitterBufferDelay as number | undefined;
+  const emitted = stat.jitterBufferEmittedCount as number | undefined;
+  return delay !== undefined && emitted ? round(delay / emitted) : undefined;
+}
+
+/**
+ * Playout delay in s. Video receive reports it directly, the audio path keeps it
+ * in the linked `media-playout` stats summed over the samples played out. Pairs
+ * with `RemoteTrack.setPlayoutDelay`.
+ */
+function playoutDelay(stat: Summary, playout?: Summary): number | undefined {
+  if (stat.playoutDelay !== undefined) {
+    return round(stat.playoutDelay as number);
+  }
+  const total = playout?.totalPlayoutDelay as number | undefined;
+  const samples = playout?.totalSamplesCount as number | undefined;
+  return total !== undefined && samples ? round(total / samples) : undefined;
+}
+
+/**
+ * Picks the interesting fields out of a `getStats()` report and groups them by
+ * RTP stream, so a stats dump can be read without unfolding the raw report.
+ */
+export function summarizeStatsReport(report: RTCStatsReport) {
+  const byId = new Map<string, Summary>();
+  const candidatePairs: Summary[] = [];
+  const inbound: Summary[] = [];
+  const outbound: Summary[] = [];
+  let transport: Summary | undefined;
+
+  report.forEach((stat) => byId.set(stat.id, stat));
+
+  const codecOf = (stat: Summary) =>
+    stat.codecId ? byId.get(stat.codecId as string)?.mimeType : undefined;
+  const relatedOf = (stat: Summary, key: 'remoteId' | 'mediaSourceId' | 'playoutId') =>
+    stat[key] ? byId.get(stat[key] as string) : undefined;
+
+  report.forEach((stat) => {
+    switch (stat.type) {
+      case 'inbound-rtp': {
+        const playout = relatedOf(stat, 'playoutId');
+        inbound.push(
+          compact({
+            kind: stat.kind,
+            ssrc: stat.ssrc,
+            mid: stat.mid,
+            // matches `streamTrackID` in the track's own log context
+            trackId: stat.trackIdentifier,
+            codec: codecOf(stat),
+            decoder: stat.decoderImplementation,
+            resolution: resolution(stat.frameWidth, stat.frameHeight),
+            fps: stat.framesPerSecond,
+            bytesReceived: stat.bytesReceived,
+            packetsReceived: stat.packetsReceived,
+            packetsLost: stat.packetsLost,
+            packetsDiscarded: stat.packetsDiscarded,
+            // frames received without frames decoded is a decode failure
+            framesReceived: stat.framesReceived,
+            framesDecoded: stat.framesDecoded,
+            framesDropped: stat.framesDropped,
+            keyFramesDecoded: stat.keyFramesDecoded,
+            freezeCount: stat.freezeCount,
+            totalFreezesDuration: stat.totalFreezesDuration,
+            pauseCount: stat.pauseCount,
+            nackCount: stat.nackCount,
+            pliCount: stat.pliCount,
+            firCount: stat.firCount,
+            jitter: stat.jitter,
+            jitterBuffer: jitterBuffer(stat),
+            playoutDelay: playoutDelay(stat, playout),
+            audioLevel: stat.audioLevel,
+            totalSamplesReceived: stat.totalSamplesReceived,
+            concealedSamples: stat.concealedSamples,
+          }),
+        );
+        break;
+      }
+      case 'outbound-rtp': {
+        const remote = relatedOf(stat, 'remoteId');
+        const source = relatedOf(stat, 'mediaSourceId');
+        outbound.push(
+          compact({
+            kind: stat.kind,
+            ssrc: stat.ssrc,
+            mid: stat.mid,
+            rid: stat.rid,
+            trackId: source?.trackIdentifier,
+            active: stat.active,
+            codec: codecOf(stat),
+            encoder: stat.encoderImplementation,
+            resolution: resolution(stat.frameWidth, stat.frameHeight),
+            fps: stat.framesPerSecond,
+            // what the source produces, to tell a stalled capture from a stalled encoder
+            captureResolution: resolution(
+              source?.width as number | undefined,
+              source?.height as number | undefined,
+            ),
+            captureFps: source?.framesPerSecond,
+            audioLevel: source?.audioLevel,
+            targetBitrate: stat.targetBitrate,
+            bytesSent: stat.bytesSent,
+            packetsSent: stat.packetsSent,
+            retransmittedPacketsSent: stat.retransmittedPacketsSent,
+            framesEncoded: stat.framesEncoded,
+            keyFramesEncoded: stat.keyFramesEncoded,
+            limitedBy:
+              stat.qualityLimitationReason === 'none' ? undefined : stat.qualityLimitationReason,
+            nackCount: stat.nackCount,
+            pliCount: stat.pliCount,
+            firCount: stat.firCount,
+            // loss, jitter and RTT are only known from what the remote reports
+            remotePacketsLost: remote?.packetsLost,
+            remoteFractionLost: remote?.fractionLost,
+            remoteJitter: remote?.jitter,
+            remoteRoundTripTime: remote?.roundTripTime,
+          }),
+        );
+        break;
+      }
+      case 'transport':
+        transport = stat;
+        break;
+      case 'candidate-pair':
+        candidatePairs.push(stat);
+        break;
+      default:
+    }
+  });
+
+  const selectedPairId = transport?.selectedCandidatePairId as string | undefined;
+  const pair =
+    (selectedPairId ? byId.get(selectedPairId) : undefined) ??
+    candidatePairs.find((candidate) => candidate.selected) ??
+    candidatePairs.find((candidate) => candidate.nominated);
+  const local = pair?.localCandidateId ? byId.get(pair.localCandidateId as string) : undefined;
+  const remote = pair?.remoteCandidateId ? byId.get(pair.remoteCandidateId as string) : undefined;
+
+  const connection = compact({
+    ice: transport?.iceState,
+    dtls: transport?.dtlsState,
+    route:
+      local && remote
+        ? `${local.candidateType}/${local.protocol} -> ${remote.candidateType}`
+        : undefined,
+    network: local?.networkType,
+    currentRoundTripTime: pair?.currentRoundTripTime,
+    // the send bandwidth estimate; no RTP stream reports it
+    availableOutgoingBitrate: pair?.availableOutgoingBitrate,
+    availableIncomingBitrate: pair?.availableIncomingBitrate,
+    bytesSent: pair?.bytesSent,
+    bytesReceived: pair?.bytesReceived,
+    candidatePairChanges: transport?.selectedCandidatePairChanges,
+  });
+
+  return {
+    connection: Object.keys(connection).length > 0 ? connection : undefined,
+    outbound: outbound.length > 0 ? outbound : undefined,
+    inbound: inbound.length > 0 ? inbound : undefined,
+  };
+}

package/src/room/token-source/test-tokens.ts

@@ -1,3 +1,11 @@
+// Builds an unsigned (`alg: none`) JWT. These aren't signed at all, so they can only be used in
+// tests which don't care about the signature.
+function unsignedToken(payload: Record<string, unknown>) {
+  const encode = (value: Record<string, unknown>) =>
+    btoa(JSON.stringify(value)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+  return `${encode({ alg: 'none', typ: 'JWT' })}.${encode(payload)}.`;
+}
+
 // Test JWTs created for test purposes only.
 // None of these actually auth against anything.
 export const TOKENS = {
@@ -25,4 +33,16 @@ export const TOKENS = {
   // A dummy roomConfig value is also set, with room_config.name = "test room name", room_config.extraField = "extra field value", and room_config.agents = [{"agentName": "test agent name","metadata":"test agent metadata","extraField":"extra field value"}]
   EXTRA_FIELDS:
     'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZXhwIjo5ODc2NTQzMjEwLCJuYmYiOjEyMzQ1Njc4OTAsImlhdCI6MTIzNDU2Nzg5MCwicm9vbUNvbmZpZyI6eyJuYW1lIjoidGVzdCByb29tIG5hbWUiLCJlbXB0eVRpbWVvdXQiOjAsImRlcGFydHVyZVRpbWVvdXQiOjAsIm1heFBhcnRpY2lwYW50cyI6MCwibWluUGxheW91dERlbGF5IjowLCJtYXhQbGF5b3V0RGVsYXkiOjAsInN5bmNTdHJlYW1zIjpmYWxzZSwiYWdlbnRzIjpbeyJhZ2VudE5hbWUiOiJ0ZXN0IGFnZW50IG5hbWUiLCJtZXRhZGF0YSI6InRlc3QgYWdlbnQgbWV0YWRhdGEiLCJleHRyYUZpZWxkIjoiZXh0cmEgZmllbGQgdmFsdWUifV0sIm1ldGFkYXRhIjoiIiwiZXh0cmFGaWVsZCI6ImV4dHJhIGZpZWxkIHZhbHVlIn19Cg.EDetpHG8cSubaApzgWJaQrpCiSy9KDBlfCfVdIydbQ-_CHiNnXOK_f_mCJbTf9A-duT1jmvPOkLrkkWFT60XPQ',
+
+  // Nbf date set at 1234567890 seconds (Fri Feb 13 2009 23:31:30 GMT+0000)
+  // No exp date set at all
+  NO_EXP: unsignedToken({ sub: '1234567890', nbf: 1234567890, iat: 1234567890 }),
+
+  // No nbf date set at all
+  // Exp date set at 1234567891 seconds (Fri Feb 13 2009 23:31:31 GMT+0000)
+  EXP_IN_PAST_NO_NBF: unsignedToken({ sub: '1234567890', exp: 1234567891, iat: 1234567890 }),
+
+  // No nbf date set at all
+  // Exp date set at 9876543210 seconds (Fri Dec 22 2282 20:13:30 GMT+0000)
+  VALID_NO_NBF: unsignedToken({ sub: '1234567890', exp: 9876543210, iat: 1234567890 }),
 };

package/src/room/token-source/utils.test.ts

@@ -31,6 +31,33 @@ describe('isResponseTokenValid', () => {
     );
     expect(isValid).toBe(false);
   });
+  it('should treat a jwt without exp as expired', () => {
+    const isValid = isResponseTokenValid(
+      TokenSourceResponse.fromJson({
+        serverUrl: 'ws://localhost:7800',
+        participantToken: TOKENS.NO_EXP,
+      }),
+    );
+    expect(isValid).toBe(false);
+  });
+  it('should honor exp when nbf is absent', () => {
+    const isValid = isResponseTokenValid(
+      TokenSourceResponse.fromJson({
+        serverUrl: 'ws://localhost:7800',
+        participantToken: TOKENS.EXP_IN_PAST_NO_NBF,
+      }),
+    );
+    expect(isValid).toBe(false);
+  });
+  it('should accept a non-expired jwt that omits nbf', () => {
+    const isValid = isResponseTokenValid(
+      TokenSourceResponse.fromJson({
+        serverUrl: 'ws://localhost:7800',
+        participantToken: TOKENS.VALID_NO_NBF,
+      }),
+    );
+    expect(isValid).toBe(true);
+  });
 });
 
 describe('decodeTokenPayload', () => {

package/src/room/token-source/utils.ts

@@ -7,19 +7,26 @@ const ONE_MINUTE_IN_MILLISECONDS = 60 * ONE_SECOND_IN_MILLISECONDS;
 
 export function isResponseTokenValid(response: TokenSourceResponse) {
   const jwtPayload = decodeTokenPayload(response.participantToken);
-  if (!jwtPayload?.nbf || !jwtPayload?.exp) {
-    return true;
+  // Missing exp: TokenSourceCached would otherwise return this response forever.
+  // nbf is optional (RFC 7519); do not skip the exp check when it is absent.
+  if (!jwtPayload?.exp) {
+    return false;
   }
 
   const now = new Date();
 
-  const nbfInMilliseconds = jwtPayload.nbf * ONE_SECOND_IN_MILLISECONDS;
-  const nbfDate = new Date(nbfInMilliseconds);
+  if (jwtPayload.nbf) {
+    const nbfInMilliseconds = jwtPayload.nbf * ONE_SECOND_IN_MILLISECONDS;
+    const nbfDate = new Date(nbfInMilliseconds);
+    if (nbfDate > now) {
+      return false;
+    }
+  }
 
   const expInMilliseconds = jwtPayload.exp * ONE_SECOND_IN_MILLISECONDS;
   const expDate = new Date(expInMilliseconds - ONE_MINUTE_IN_MILLISECONDS);
 
-  return nbfDate <= now && expDate > now;
+  return expDate > now;
 }
 
 /** Given a LiveKit generated participant token, decodes and returns the associated {@link TokenPayload} data. */

package/src/room/track/LocalAudioTrack.ts

@@ -245,12 +245,18 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
           type: 'audio',
           streamId: v.id,
           packetsSent: v.packetsSent,
-          packetsLost: v.packetsLost,
           bytesSent: v.bytesSent,
           timestamp: v.timestamp,
-          roundTripTime: v.roundTripTime,
-          jitter: v.jitter,
         };
+
+        // loss, jitter and RTT are only known from what the remote reports back,
+        // the same way the video sender picks them up
+        const remote = stats.get(v.remoteId);
+        if (remote) {
+          audioStats.packetsLost = remote.packetsLost;
+          audioStats.jitter = remote.jitter;
+          audioStats.roundTripTime = remote.roundTripTime;
+        }
       }
     });
 

package/src/room/track/Track.ts

@@ -11,6 +11,7 @@ import type { SignalClient } from '../../api/SignalClient';
 import log, { LoggerNames, type StructuredLogger, getLogger } from '../../logger';
 import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import { TrackEvent } from '../events';
+import { summarizeStatsReport } from '../statsSummary';
 import type { LoggerOptions } from '../types';
 import { isFireFox, isSafari, isWeb } from '../utils';
 import type { TrackProcessor } from './processor/types';
@@ -85,6 +86,8 @@ export abstract class Track<
 
   protected monitorInterval?: ReturnType<typeof setInterval>;
 
+  private finalStatsLogged = false;
+
   protected log: StructuredLogger = log;
 
   protected constructor(
@@ -271,6 +274,11 @@ export abstract class Track<
   /* @internal */
   abstract startMonitor(signalClient?: SignalClient): void;
 
+  /**
+   * Raw stats of the sender or receiver this track is attached to.
+   */
+  abstract getRTCStatsReport(): Promise<RTCStatsReport | undefined>;
+
   /* @internal */
   stopMonitor() {
     if (this.monitorInterval) {
@@ -280,6 +288,25 @@ export abstract class Track<
       cancelAnimationFrame(this.timeSyncHandle);
       this.timeSyncHandle = undefined;
     }
+    this.logFinalStats();
+  }
+
+  /**
+   * Dumps the raw stats of the track as it ends, once: a track that stops
+   * between two of the room's stats dumps is gone by the time the next one runs.
+   */
+  private logFinalStats() {
+    if (this.finalStatsLogged) {
+      return;
+    }
+    this.finalStatsLogged = true;
+    this.getRTCStatsReport()
+      .then((report) => {
+        if (report) {
+          this.log.info('final track stats', summarizeStatsReport(report));
+        }
+      })
+      .catch((error) => this.log.debug('could not collect final track stats', { error }));
   }
 
   /** @internal */

package/src/room/utils.test.ts

@@ -1,11 +1,12 @@
 import { ClientInfo_Capability } from '@livekit/protocol';
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
   ddExtensionURI,
   extractMaxAgeFromRequestHeaders,
   getClientInfo,
   negotiateDependencyDescriptor,
   splitUtf8,
+  supportsAdaptiveStream,
   toWebsocketUrl,
 } from './utils';
 
@@ -257,3 +258,25 @@ describe('negotiateDependencyDescriptor', () => {
     expect(negotiateDependencyDescriptor(transceiver)).toBe(false);
   });
 });
+
+describe('supportsAdaptiveStream', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('reports support where both observers exist', () => {
+    expect(supportsAdaptiveStream()).toBe(true);
+  });
+
+  it('reports no support where ResizeObserver is missing', () => {
+    vi.stubGlobal('ResizeObserver', undefined);
+
+    expect(supportsAdaptiveStream()).toBe(false);
+  });
+
+  it('reports no support where IntersectionObserver is missing', () => {
+    vi.stubGlobal('IntersectionObserver', undefined);
+
+    expect(supportsAdaptiveStream()).toBe(false);
+  });
+});

package/src/room/utils.ts

@@ -58,7 +58,7 @@ export function supportsAddTrack() {
 }
 
 export function supportsAdaptiveStream() {
-  return typeof ResizeObserver !== undefined && typeof IntersectionObserver !== undefined;
+  return typeof ResizeObserver !== 'undefined' && typeof IntersectionObserver !== 'undefined';
 }
 
 export function supportsDynacast() {

package/src/utils/machineInspector.ts

@@ -0,0 +1,90 @@
+/**
+ * Opt-in registry that lets a development tool observe the state machines driving the connection
+ * layer.
+ *
+ * The machines are private to the objects that own them and, more importantly, do not outlive them:
+ * a full reconnect replaces the whole engine along with its `SignalClient`, so anything watching a
+ * single machine reference goes blind exactly when the interesting part starts. Machines therefore
+ * announce themselves here as they are constructed, and a subscriber sees the whole succession.
+ *
+ * Nothing is recorded until {@link enableMachineInspector} is called, which no shipping code does —
+ * with the registry off, announcing is a comparison and a return.
+ */
+
+/**
+ * The slice of machina's `Fsm` surface an inspector needs. Structural rather than machina's own
+ * type so that any machine satisfies it regardless of its state and input unions.
+ */
+export interface InspectableMachine {
+  readonly id: string;
+  readonly initialState: string;
+  readonly states: Record<string, Record<string, unknown>>;
+  readonly context?: unknown;
+  currentState(): string;
+  canHandle(input: string): boolean;
+  on(eventName: string, callback: (data: any) => void): { off(): void };
+}
+
+export interface MachineAnnouncement {
+  /** What the machine drives, e.g. `signal`. Not unique: each new `SignalClient` announces one. */
+  label: string;
+  /** How many machines have been announced before this one, so successive instances are tellable apart. */
+  seq: number;
+  /**
+   * When the machine was constructed. Carried on the announcement because subscribers receive the
+   * recorded ones on subscribe, and stamping those at replay time would date them all to whenever
+   * the tool happened to open.
+   */
+  at: number;
+  machine: InspectableMachine;
+}
+
+/** Kept small: enough for a panel opened mid-session to see how the connection got where it is. */
+const HISTORY_LIMIT = 16;
+
+let enabled = false;
+let announced: MachineAnnouncement[] = [];
+let subscribers: Array<(announcement: MachineAnnouncement) => void> = [];
+
+/**
+ * Starts recording machine announcements. Call before the machines of interest are constructed —
+ * for the signal machine that means before the `Room` is created.
+ */
+export function enableMachineInspector() {
+  enabled = true;
+}
+
+export function isMachineInspectorEnabled() {
+  return enabled;
+}
+
+/** Announces a machine to whatever is watching. A no-op unless the inspector was enabled. */
+export function announceMachine(label: string, machine: InspectableMachine) {
+  if (!enabled) {
+    return;
+  }
+  const announcement: MachineAnnouncement = {
+    label,
+    seq: announced.length,
+    at: Date.now(),
+    machine,
+  };
+  announced = [...announced.slice(-(HISTORY_LIMIT - 1)), announcement];
+  for (const subscriber of subscribers) {
+    subscriber(announcement);
+  }
+}
+
+/**
+ * Subscribes to machine announcements, replaying the ones already recorded so that a panel opened
+ * after connecting still sees the machine currently in charge. Returns an unsubscribe function.
+ */
+export function onMachineAnnounced(callback: (announcement: MachineAnnouncement) => void) {
+  subscribers = [...subscribers, callback];
+  for (const announcement of announced) {
+    callback(announcement);
+  }
+  return () => {
+    subscribers = subscribers.filter((subscriber) => subscriber !== callback);
+  };
+}