livekit-client 2.15.7 → 2.15.8

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

@@ -0,0 +1,285 @@
+import { Mutex } from '@livekit/mutex';
+import {
+  RoomAgentDispatch,
+  RoomConfiguration,
+  TokenSourceRequest,
+  TokenSourceResponse,
+} from '@livekit/protocol';
+import {
+  TokenSourceConfigurable,
+  type TokenSourceFetchOptions,
+  TokenSourceFixed,
+  type TokenSourceResponseObject,
+} from './types';
+import { decodeTokenPayload, isResponseExpired } from './utils';
+
+/** A TokenSourceCached is a TokenSource which caches the last {@link TokenSourceResponseObject} value and returns it
+ * until a) it expires or b) the {@link TokenSourceFetchOptions} provided to .fetch(...) change. */
+abstract class TokenSourceCached extends TokenSourceConfigurable {
+  private cachedFetchOptions: TokenSourceFetchOptions | null = null;
+
+  private cachedResponse: TokenSourceResponse | null = null;
+
+  private fetchMutex = new Mutex();
+
+  private isSameAsCachedFetchOptions(options: TokenSourceFetchOptions) {
+    if (!this.cachedFetchOptions) {
+      return false;
+    }
+
+    for (const key of Object.keys(this.cachedFetchOptions) as Array<
+      keyof TokenSourceFetchOptions
+    >) {
+      switch (key) {
+        case 'roomName':
+        case 'participantName':
+        case 'participantIdentity':
+        case 'participantMetadata':
+        case 'participantAttributes':
+        case 'agentName':
+        case 'agentMetadata':
+          if (this.cachedFetchOptions[key] !== options[key]) {
+            return false;
+          }
+          break;
+        default:
+          // ref: https://stackoverflow.com/a/58009992
+          const exhaustiveCheckedKey: never = key;
+          throw new Error(`Options key ${exhaustiveCheckedKey} not being checked for equality!`);
+      }
+    }
+
+    return true;
+  }
+
+  private shouldReturnCachedValueFromFetch(fetchOptions: TokenSourceFetchOptions) {
+    if (!this.cachedResponse) {
+      return false;
+    }
+    if (isResponseExpired(this.cachedResponse)) {
+      return false;
+    }
+    if (this.isSameAsCachedFetchOptions(fetchOptions)) {
+      return false;
+    }
+    return true;
+  }
+
+  getCachedResponseJwtPayload() {
+    if (!this.cachedResponse) {
+      return null;
+    }
+    return decodeTokenPayload(this.cachedResponse.participantToken);
+  }
+
+  async fetch(options: TokenSourceFetchOptions): Promise<TokenSourceResponseObject> {
+    const unlock = await this.fetchMutex.lock();
+    try {
+      if (this.shouldReturnCachedValueFromFetch(options)) {
+        return this.cachedResponse!.toJson() as TokenSourceResponseObject;
+      }
+      this.cachedFetchOptions = options;
+
+      const tokenResponse = await this.update(options);
+      this.cachedResponse = tokenResponse;
+      return tokenResponse.toJson() as TokenSourceResponseObject;
+    } finally {
+      unlock();
+    }
+  }
+
+  protected abstract update(options: TokenSourceFetchOptions): Promise<TokenSourceResponse>;
+}
+
+type LiteralOrFn =
+  | TokenSourceResponseObject
+  | (() => TokenSourceResponseObject | Promise<TokenSourceResponseObject>);
+export class TokenSourceLiteral extends TokenSourceFixed {
+  private literalOrFn: LiteralOrFn;
+
+  constructor(literalOrFn: LiteralOrFn) {
+    super();
+    this.literalOrFn = literalOrFn;
+  }
+
+  async fetch(): Promise<TokenSourceResponseObject> {
+    if (typeof this.literalOrFn === 'function') {
+      return this.literalOrFn();
+    } else {
+      return this.literalOrFn;
+    }
+  }
+}
+
+type CustomFn = (
+  options: TokenSourceFetchOptions,
+) => TokenSourceResponseObject | Promise<TokenSourceResponseObject>;
+export class TokenSourceCustom extends TokenSourceCached {
+  private customFn: CustomFn;
+
+  constructor(customFn: CustomFn) {
+    super();
+    this.customFn = customFn;
+  }
+
+  protected async update(options: TokenSourceFetchOptions) {
+    const resultMaybePromise = this.customFn(options);
+
+    let result;
+    if (resultMaybePromise instanceof Promise) {
+      result = await resultMaybePromise;
+    } else {
+      result = resultMaybePromise;
+    }
+
+    return TokenSourceResponse.fromJson(result, {
+      // NOTE: it could be possible that the response body could contain more fields than just
+      // what's in TokenSourceResponse depending on the implementation
+      ignoreUnknownFields: true,
+    });
+  }
+}
+
+export type EndpointOptions = Omit<RequestInit, 'body'>;
+
+export class TokenSourceEndpoint extends TokenSourceCached {
+  private url: string;
+
+  private endpointOptions: EndpointOptions;
+
+  constructor(url: string, options: EndpointOptions = {}) {
+    super();
+    this.url = url;
+    this.endpointOptions = options;
+  }
+
+  private createRequestFromOptions(options: TokenSourceFetchOptions) {
+    const request = new TokenSourceRequest();
+
+    for (const key of Object.keys(options) as Array<keyof TokenSourceFetchOptions>) {
+      switch (key) {
+        case 'roomName':
+        case 'participantName':
+        case 'participantIdentity':
+        case 'participantMetadata':
+          request[key] = options[key];
+          break;
+
+        case 'participantAttributes':
+          request.participantAttributes = options.participantAttributes ?? {};
+          break;
+
+        case 'agentName':
+          request.roomConfig = request.roomConfig ?? new RoomConfiguration();
+          if (request.roomConfig.agents.length === 0) {
+            request.roomConfig.agents.push(new RoomAgentDispatch());
+          }
+          request.roomConfig.agents[0].agentName = options.agentName!;
+          break;
+
+        case 'agentMetadata':
+          request.roomConfig = request.roomConfig ?? new RoomConfiguration();
+          if (request.roomConfig.agents.length === 0) {
+            request.roomConfig.agents.push(new RoomAgentDispatch());
+          }
+          request.roomConfig.agents[0].metadata = options.agentMetadata!;
+          break;
+
+        default:
+          // ref: https://stackoverflow.com/a/58009992
+          const exhaustiveCheckedKey: never = key;
+          throw new Error(
+            `Options key ${exhaustiveCheckedKey} not being included in forming request!`,
+          );
+      }
+    }
+
+    return request;
+  }
+
+  protected async update(options: TokenSourceFetchOptions) {
+    const request = this.createRequestFromOptions(options);
+
+    const response = await fetch(this.url, {
+      ...this.endpointOptions,
+      method: this.endpointOptions.method ?? 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...this.endpointOptions.headers,
+      },
+      body: request.toJsonString({
+        useProtoFieldName: true,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Error generating token from endpoint ${this.url}: received ${response.status} / ${await response.text()}`,
+      );
+    }
+
+    const body = await response.json();
+    return TokenSourceResponse.fromJson(body, {
+      // NOTE: it could be possible that the response body could contain more fields than just
+      // what's in TokenSourceResponse depending on the implementation (ie, SandboxTokenServer)
+      ignoreUnknownFields: true,
+    });
+  }
+}
+
+export type SandboxTokenServerOptions = {
+  baseUrl?: string;
+};
+
+export class TokenSourceSandboxTokenServer extends TokenSourceEndpoint {
+  constructor(sandboxId: string, options: SandboxTokenServerOptions) {
+    const { baseUrl = 'https://cloud-api.livekit.io', ...rest } = options;
+
+    super(`${baseUrl}/api/v2/sandbox/connection-details`, {
+      ...rest,
+      headers: {
+        'X-Sandbox-ID': sandboxId,
+      },
+    });
+  }
+}
+
+export const TokenSource = {
+  /** TokenSource.literal contains a single, literal set of {@link TokenSourceResponseObject}
+   * credentials, either provided directly or returned from a provided function. */
+  literal(literalOrFn: LiteralOrFn) {
+    return new TokenSourceLiteral(literalOrFn);
+  },
+
+  /**
+   * TokenSource.custom allows a user to define a manual function which generates new
+   * {@link TokenSourceResponseObject} values on demand.
+   *
+   * Use this to get credentials from custom backends / etc.
+   */
+  custom(customFn: CustomFn) {
+    return new TokenSourceCustom(customFn);
+  },
+
+  /**
+   * TokenSource.endpoint creates a token source that fetches credentials from a given URL using
+   * the standard endpoint format:
+   * FIXME: add docs link here in the future!
+   */
+  endpoint(url: string, options: EndpointOptions = {}) {
+    return new TokenSourceEndpoint(url, options);
+  },
+
+  /**
+   * TokenSource.sandboxTokenServer queries a sandbox token server for credentials,
+   * which supports quick prototyping / getting started types of use cases.
+   *
+   * This token provider is INSECURE and should NOT be used in production.
+   *
+   * For more info:
+   * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+   */
+  sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) {
+    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  },
+};

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

@@ -0,0 +1,84 @@
+import { RoomConfiguration, TokenSourceRequest, TokenSourceResponse } from '@livekit/protocol';
+import type { JWTPayload } from 'jose';
+import type { ValueToSnakeCase } from '../../utils/camelToSnakeCase';
+// The below imports are being linked in tsdoc comments, so they have to be imported even if they
+// aren't being used.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { TokenSourceCustom, TokenSourceEndpoint, TokenSourceLiteral } from './TokenSource';
+
+export type TokenSourceRequestObject = Required<
+  NonNullable<ConstructorParameters<typeof TokenSourceRequest>[0]>
+>;
+export type TokenSourceResponseObject = Required<
+  NonNullable<ConstructorParameters<typeof TokenSourceResponse>[0]>
+>;
+
+/** The `TokenSource` request object sent to the server as part of fetching a configurable
+ * `TokenSource` like {@link TokenSourceEndpoint}.
+ *
+ * Use this as a type for your request body if implementing a server endpoint in node.js.
+ */
+export type TokenSourceRequestPayload = ValueToSnakeCase<TokenSourceRequestObject>;
+
+/** The `TokenSource` response object sent from the server as part of fetching a configurable
+ * `TokenSource` like {@link TokenSourceEndpoint}.
+ *
+ * Use this as a type for your response body if implementing a server endpoint in node.js.
+ */
+export type TokenSourceResponsePayload = ValueToSnakeCase<TokenSourceResponseObject>;
+
+/** The payload of a LiveKit JWT token. */
+export type TokenPayload = JWTPayload & {
+  name?: string;
+  metadata?: string;
+  attributes?: Record<string, string>;
+  video?: {
+    room?: string;
+    roomJoin?: boolean;
+    canPublish?: boolean;
+    canPublishData?: boolean;
+    canSubscribe?: boolean;
+  };
+  roomConfig?: RoomConfigurationObject;
+};
+export type RoomConfigurationObject = NonNullable<
+  ConstructorParameters<typeof RoomConfiguration>[0]
+>;
+
+/** A Fixed TokenSource is a token source that takes no parameters and returns a completely
+ * independently derived value on each fetch() call.
+ *
+ * The most common downstream implementer is {@link TokenSourceLiteral}.
+ */
+export abstract class TokenSourceFixed {
+  abstract fetch(): Promise<TokenSourceResponseObject>;
+}
+
+export type TokenSourceFetchOptions = {
+  roomName?: string;
+  participantName?: string;
+  participantIdentity?: string;
+  participantMetadata?: string;
+  participantAttributes?: { [key: string]: string };
+
+  agentName?: string;
+  agentMetadata?: string;
+};
+
+/** A Configurable TokenSource is a token source that takes a
+ * {@link TokenSourceFetchOptions} object as input and returns a deterministic
+ * {@link TokenSourceResponseObject} output based on the options specified.
+ *
+ * For example, if options.participantName is set, it should be expected that
+ * all tokens that are generated will have participant name field set to the
+ * provided value.
+ *
+ * A few common downstream implementers are {@link TokenSourceEndpoint}
+ * and {@link TokenSourceCustom}.
+ */
+export abstract class TokenSourceConfigurable {
+  abstract fetch(options: TokenSourceFetchOptions): Promise<TokenSourceResponseObject>;
+}
+
+/** A TokenSource is a mechanism for fetching credentials required to connect to a LiveKit Room. */
+export type TokenSourceBase = TokenSourceFixed | TokenSourceConfigurable;

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

@@ -0,0 +1,35 @@
+import { RoomConfiguration, type TokenSourceResponse } from '@livekit/protocol';
+import { decodeJwt } from 'jose';
+import type { RoomConfigurationObject, TokenPayload } from './types';
+
+const ONE_SECOND_IN_MILLISECONDS = 1000;
+const ONE_MINUTE_IN_MILLISECONDS = 60 * ONE_SECOND_IN_MILLISECONDS;
+
+export function isResponseExpired(response: TokenSourceResponse) {
+  const jwtPayload = decodeTokenPayload(response.participantToken);
+  if (!jwtPayload?.exp) {
+    return true;
+  }
+  const expInMilliseconds = jwtPayload.exp * ONE_SECOND_IN_MILLISECONDS;
+  const expiresAt = new Date(expInMilliseconds - ONE_MINUTE_IN_MILLISECONDS);
+
+  const now = new Date();
+  return expiresAt >= now;
+}
+
+export function decodeTokenPayload(token: string) {
+  const payload = decodeJwt<Omit<TokenPayload, 'roomConfig'>>(token);
+
+  const { roomConfig, ...rest } = payload;
+
+  const mappedPayload: TokenPayload = {
+    ...rest,
+    roomConfig: payload.roomConfig
+      ? (RoomConfiguration.fromJson(
+          payload.roomConfig as Record<string, any>,
+        ) as RoomConfigurationObject)
+      : undefined,
+  };
+
+  return mappedPayload;
+}

package/src/room/track/LocalAudioTrack.ts

@@ -244,7 +244,7 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
     const trackIsSilent = await detectSilence(this);
     if (trackIsSilent) {
       if (!this.isMuted) {
-        this.log.warn('silence detected on local audio track', this.logContext);
+        this.log.debug('silence detected on local audio track', this.logContext);
       }
       this.emit(TrackEvent.AudioSilenceDetected);
     }

package/src/room/track/LocalTrack.ts

@@ -670,7 +670,7 @@ export default abstract class LocalTrack<
   }
 
   /** @internal */
-  getPreConnectBuffer() {
+  getPreConnectBuffer(): ReadableStream<Uint8Array> | undefined {
     return this.localTrackRecorder?.byteStream;
   }
 

package/src/room/track/options.ts

@@ -390,18 +390,26 @@ export interface AudioPreset {
   priority?: RTCPriorityType;
 }
 
-const backupCodecs = ['vp8', 'h264'] as const;
+// `red` is not technically a codec, but treated as one in signalling protocol
+export const audioCodecs = ['opus', 'red'] as const;
+
+export type AudioCodec = (typeof audioCodecs)[number];
+
+const backupVideoCodecs = ['vp8', 'h264'] as const;
 
 export const videoCodecs = ['vp8', 'h264', 'vp9', 'av1', 'h265'] as const;
 
 export type VideoCodec = (typeof videoCodecs)[number];
 
-export type BackupVideoCodec = (typeof backupCodecs)[number];
+export type BackupVideoCodec = (typeof backupVideoCodecs)[number];
 
-export function isBackupCodec(codec: string): codec is BackupVideoCodec {
-  return !!backupCodecs.find((backup) => backup === codec);
+export function isBackupVideoCodec(codec: string): codec is BackupVideoCodec {
+  return !!backupVideoCodecs.find((backup) => backup === codec);
 }
 
+/** @deprecated Use {@link isBackupVideoCodec} instead */
+export const isBackupCodec = isBackupVideoCodec;
+
 export enum BackupCodecPolicy {
   // codec regression is preferred, the sfu will try to regress codec if possible but not guaranteed
   PREFER_REGRESSION = 0,

package/src/room/track/utils.ts

@@ -147,10 +147,18 @@ export function getNewAudioContext(): AudioContext | void {
           }
         } catch (e) {
           console.warn('Error trying to auto-resume audio context', e);
+        } finally {
+          window.document.body?.removeEventListener('click', handleResume);
         }
-
-        window.document.body?.removeEventListener('click', handleResume);
       };
+
+      // https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/statechange_event
+      audioContext.addEventListener('statechange', () => {
+        if (audioContext.state === 'closed') {
+          window.document.body?.removeEventListener('click', handleResume);
+        }
+      });
+
       window.document.body.addEventListener('click', handleResume);
     }
     return audioContext;

package/src/room/types.ts

@@ -136,6 +136,7 @@ export interface BaseStreamInfo {
   /** total size in bytes for finite streams and undefined for streams of unknown size */
   size?: number;
   attributes?: Record<string, string>;
+  encryptionType: Encryption_Type;
 }
 export interface ByteStreamInfo extends BaseStreamInfo {
   name: string;

package/src/room/utils.ts

@@ -22,7 +22,7 @@ import type RemoteTrackPublication from './track/RemoteTrackPublication';
 import type RemoteVideoTrack from './track/RemoteVideoTrack';
 import { Track } from './track/Track';
 import type { TrackPublication } from './track/TrackPublication';
-import { type VideoCodec, videoCodecs } from './track/options';
+import { type AudioCodec, type VideoCodec, audioCodecs, videoCodecs } from './track/options';
 import { getNewAudioContext } from './track/utils';
 import type { ChatMessage, LiveKitReactNativeInfo, TranscriptionSegment } from './types';
 
@@ -73,7 +73,7 @@ export function supportsAV1(): boolean {
   let hasAV1 = false;
   if (capabilities) {
     for (const codec of capabilities.codecs) {
-      if (codec.mimeType === 'video/AV1') {
+      if (codec.mimeType.toLowerCase() === 'video/av1') {
         hasAV1 = true;
         break;
       }
@@ -110,7 +110,7 @@ export function supportsVP9(): boolean {
   let hasVP9 = false;
   if (capabilities) {
     for (const codec of capabilities.codecs) {
-      if (codec.mimeType === 'video/VP9') {
+      if (codec.mimeType.toLowerCase() === 'video/vp9') {
         hasVP9 = true;
         break;
       }
@@ -128,7 +128,7 @@ export function supportsH265(): boolean {
   let hasH265 = false;
   if (capabilities) {
     for (const codec of capabilities.codecs) {
-      if (codec.mimeType === 'video/H265') {
+      if (codec.mimeType.toLowerCase() === 'video/h265') {
         hasH265 = true;
         break;
       }
@@ -533,6 +533,10 @@ export function createAudioAnalyser(
   return { calculateVolume, analyser, cleanup };
 }
 
+export function isAudioCodec(maybeCodec: string): maybeCodec is AudioCodec {
+  return audioCodecs.includes(maybeCodec as AudioCodec);
+}
+
 export function isVideoCodec(maybeCodec: string): maybeCodec is VideoCodec {
   return videoCodecs.includes(maybeCodec as VideoCodec);
 }

package/src/utils/camelToSnakeCase.ts

@@ -0,0 +1,16 @@
+export type CamelToSnakeCase<Str extends string> = Str extends `${infer First}${infer Rest}`
+  ? `${First extends Capitalize<First> ? '_' : ''}${Lowercase<First>}${CamelToSnakeCase<Rest>}`
+  : Str;
+
+type ArrayValuesToSnakeCase<Item> = Array<ValueToSnakeCase<Item>>;
+
+type ObjectKeysToSnakeCase<Obj> = {
+  [Key in keyof Obj as CamelToSnakeCase<string & Key>]: NonNullable<ValueToSnakeCase<Obj[Key]>>;
+};
+
+export type ValueToSnakeCase<Value> =
+  Value extends Array<infer Item>
+    ? ArrayValuesToSnakeCase<Item>
+    : Value extends object
+      ? ObjectKeysToSnakeCase<Value>
+      : Value;