livekit-client 2.20.2 → 2.22.0

package/src/room/data-stream/outgoing/header-utils.ts

@@ -0,0 +1,87 @@
+import {
+  DataPacket,
+  DataStream_ByteHeader,
+  DataStream_CompressionType,
+  DataStream_Header,
+  DataStream_OperationType,
+  DataStream_TextHeader,
+} from '@livekit/protocol';
+import type { ByteStreamInfo, StreamTextOptions, TextStreamInfo } from '../../types';
+import { numberToBigInt } from '../../utils';
+
+/** The data-streams-v2 wire signals carried directly on the header: the compression flag and the
+ * inline single-packet payload. Both used to live in reserved header attributes; they are now
+ * first-class protobuf fields on `DataStream.Header`. */
+export interface StreamHeaderV2Fields {
+  /** Compression applied to the inline/chunked payload. Defaults to `NONE` when omitted. */
+  compression?: DataStream_CompressionType;
+  /** The full payload smuggled into the header for single-packet (inline) sends. */
+  inlineContent?: Uint8Array;
+}
+
+/** Builds the `DataStream_Header` for a text stream from its info and stream options. */
+export function buildTextStreamHeader(
+  info: TextStreamInfo,
+  options?: Pick<StreamTextOptions, 'version' | 'replyToStreamId' | 'type'>,
+  v2?: StreamHeaderV2Fields,
+): DataStream_Header {
+  return new DataStream_Header({
+    streamId: info.id,
+    mimeType: info.mimeType,
+    topic: info.topic,
+    timestamp: numberToBigInt(info.timestamp),
+    totalLength: numberToBigInt(info.size),
+    attributes: info.attributes,
+    compression: v2?.compression ?? DataStream_CompressionType.NONE,
+    inlineContent: v2?.inlineContent,
+    contentHeader: {
+      case: 'textHeader',
+      value: new DataStream_TextHeader({
+        version: options?.version,
+        attachedStreamIds: info.attachedStreamIds,
+        replyToStreamId: options?.replyToStreamId,
+        operationType:
+          options?.type === 'update'
+            ? DataStream_OperationType.UPDATE
+            : DataStream_OperationType.CREATE,
+      }),
+    },
+  });
+}
+
+/** Builds the `DataStream_Header` for a byte stream from its info. */
+export function buildByteStreamHeader(
+  info: ByteStreamInfo,
+  v2?: StreamHeaderV2Fields,
+): DataStream_Header {
+  return new DataStream_Header({
+    streamId: info.id,
+    mimeType: info.mimeType,
+    topic: info.topic,
+    timestamp: numberToBigInt(info.timestamp),
+    totalLength: numberToBigInt(info.size),
+    attributes: info.attributes,
+    compression: v2?.compression ?? DataStream_CompressionType.NONE,
+    inlineContent: v2?.inlineContent,
+    contentHeader: {
+      case: 'byteHeader',
+      value: new DataStream_ByteHeader({
+        name: info.name,
+      }),
+    },
+  });
+}
+
+/** Wraps a `DataStream_Header` in a `DataPacket` ready to be sent over a data channel. */
+export function createStreamHeaderPacket(
+  header: DataStream_Header,
+  destinationIdentities?: Array<string>,
+): DataPacket {
+  return new DataPacket({
+    destinationIdentities,
+    value: {
+      case: 'streamHeader',
+      value: header,
+    },
+  });
+}

package/src/room/errors.ts

@@ -248,8 +248,7 @@ export class PublishTrackError extends LivekitError {
 }
 
 export type RequestErrorReason =
-  | Exclude<RequestResponse_Reason, RequestResponse_Reason.OK>
-  | 'TimeoutError';
+  Exclude<RequestResponse_Reason, RequestResponse_Reason.OK> | 'TimeoutError';
 
 export class SignalRequestError extends LivekitReasonedError<RequestErrorReason> {
   readonly name = 'SignalRequestError';
@@ -287,6 +286,12 @@ export enum DataStreamErrorReason {
 
   // Encryption type mismatch.
   EncryptionTypeMismatch = 8,
+
+  // The serialized stream header packet (driven mainly by attributes) exceeds the MTU budget.
+  HeaderTooLarge = 9,
+
+  // The stream's (decompressed) payload exceeds the maximum allowed size.
+  PayloadTooLarge = 10,
 }
 
 export class DataStreamError extends LivekitReasonedError<DataStreamErrorReason> {

package/src/room/participant/LocalParticipant.ts

@@ -82,8 +82,10 @@ import {
   sourceToKind,
 } from '../track/utils';
 import {
+  type ByteStreamInfo,
   type ChatMessage,
   type DataPublishOptions,
+  type SendBytesOptions,
   type SendFileOptions,
   type SendTextOptions,
   type StreamBytesOptions,
@@ -1851,6 +1853,17 @@ export default class LocalParticipant extends Participant {
     return this.roomOutgoingDataStreamManager.sendFile(file, options);
   }
 
+  /**
+   * Sends the given bytes to participants in the room via the data channel.
+   * For files, consider using {@link sendFile}; for longer/incremental payloads, {@link streamBytes}.
+   *
+   * @param bytes The byte payload
+   * @param options.topic Topic identifier used to route the stream to appropriate handlers.
+   */
+  async sendBytes(bytes: Uint8Array, options?: SendBytesOptions): Promise<ByteStreamInfo> {
+    return this.roomOutgoingDataStreamManager.sendBytes(bytes, options);
+  }
+
   /**
    * Stream bytes incrementally to participants in the room via the data channel.
    * For sending files, consider using {@link sendFile} instead.

package/src/room/participant/RemoteParticipant.ts

@@ -1,8 +1,9 @@
-import type {
-  ParticipantInfo,
-  SubscriptionError,
-  UpdateSubscription,
-  UpdateTrackSettings,
+import {
+  ClientInfo_Capability,
+  type ParticipantInfo,
+  type SubscriptionError,
+  type UpdateSubscription,
+  type UpdateTrackSettings,
 } from '@livekit/protocol';
 import type { SignalClient } from '../../api/SignalClient';
 import { DeferrableMap } from '../../utils/deferrable-map';
@@ -47,6 +48,16 @@ export default class RemoteParticipant extends Participant {
    **/
   clientProtocol: number;
 
+  /** The client capabilities the remote participant advertises (e.g. deflate-raw compression
+   * support). Used to decide which peer-to-peer features can be used when sending to them.
+   *
+   * Differs from clientProtocol in that these are truely optional "additions" which can be used
+   * or not depending on client specific attributes rather than protocol level invariants.
+   *
+   * @internal
+   **/
+  capabilities: Array<ClientInfo_Capability>;
+
   private volumeMap: Map<Track.Source, number>;
 
   private audioOutput?: AudioOutputOptions;
@@ -72,6 +83,7 @@ export default class RemoteParticipant extends Participant {
         return new RemoteDataTrack(info, manager, { publisherIdentity: pi.identity });
       }),
       pi.clientProtocol,
+      pi.capabilities,
     );
   }
 
@@ -95,6 +107,7 @@ export default class RemoteParticipant extends Participant {
     kind: ParticipantKind = ParticipantKind.STANDARD,
     remoteDataTracks: Array<RemoteDataTrack> = [],
     clientProtocol: number = CLIENT_PROTOCOL_DEFAULT,
+    capabilities: Array<ClientInfo_Capability> = [],
   ) {
     super(sid, identity || '', name, metadata, attributes, loggerOptions, kind);
     this.signalClient = signalClient;
@@ -108,6 +121,7 @@ export default class RemoteParticipant extends Participant {
     );
     this.volumeMap = new Map();
     this.clientProtocol = clientProtocol;
+    this.capabilities = capabilities;
   }
 
   protected addTrackPublication(publication: RemoteTrackPublication) {

package/src/room/rpc/client/RpcClientManager.test.ts

@@ -16,6 +16,8 @@ describe('RpcClientManager', () => {
       const outgoingDataStreamManager = new OutgoingDataStreamManager(
         {} as unknown as RTCEngine,
         log,
+        (_identity) => CLIENT_PROTOCOL_DEFAULT,
+        () => [],
       );
 
       rpcClientManager = new RpcClientManager(
@@ -132,19 +134,13 @@ describe('RpcClientManager', () => {
 
   describe('v2 -> v2', () => {
     let rpcClientManager: RpcClientManager;
-    let mockStreamTextWriter: {
-      write: ReturnType<typeof vi.fn>;
-      close: ReturnType<typeof vi.fn>;
-    };
+    let sendTextMock: ReturnType<typeof vi.fn>;
     let mockOutgoingDataStreamManager: OutgoingDataStreamManager;
 
     beforeEach(() => {
-      mockStreamTextWriter = {
-        write: vi.fn().mockResolvedValue(undefined),
-        close: vi.fn().mockResolvedValue(undefined),
-      };
+      sendTextMock = vi.fn().mockResolvedValue(undefined);
       mockOutgoingDataStreamManager = {
-        streamText: vi.fn().mockResolvedValue(mockStreamTextWriter),
+        sendText: sendTextMock,
       } as unknown as OutgoingDataStreamManager;
 
       rpcClientManager = new RpcClientManager(
@@ -171,7 +167,8 @@ describe('RpcClientManager', () => {
       });
 
       // Verify the data stream was used with correct attributes
-      expect(mockOutgoingDataStreamManager.streamText).toHaveBeenCalledWith(
+      expect(mockOutgoingDataStreamManager.sendText).toHaveBeenCalledWith(
+        'request-payload',
         expect.objectContaining({
           topic: RPC_REQUEST_DATA_STREAM_TOPIC,
           destinationIdentities: ['destination-identity'],
@@ -182,8 +179,6 @@ describe('RpcClientManager', () => {
           }),
         }),
       );
-      expect(mockStreamTextWriter.write).toHaveBeenCalledWith('request-payload');
-      expect(mockStreamTextWriter.close).toHaveBeenCalled();
 
       // No packet should have been emitted
       expect(managerEvents.areThereBufferedEvents('sendDataPacket')).toBe(false);
@@ -213,7 +208,8 @@ describe('RpcClientManager', () => {
       });
 
       // Verify the data stream was used with correct attributes
-      expect(mockOutgoingDataStreamManager.streamText).toHaveBeenCalledWith(
+      expect(mockOutgoingDataStreamManager.sendText).toHaveBeenCalledWith(
+        longPayload,
         expect.objectContaining({
           topic: RPC_REQUEST_DATA_STREAM_TOPIC,
           destinationIdentities: ['destination-identity'],
@@ -224,8 +220,6 @@ describe('RpcClientManager', () => {
           }),
         }),
       );
-      expect(mockStreamTextWriter.write).toHaveBeenCalledWith(longPayload);
-      expect(mockStreamTextWriter.close).toHaveBeenCalled();
 
       // No packet should have been emitted
       expect(managerEvents.areThereBufferedEvents('sendDataPacket')).toBe(false);
@@ -337,14 +331,14 @@ describe('RpcClientManager', () => {
     });
 
     it('should not drop ack and response that arrive before publish completes', async () => {
-      // Hold the publish path open by blocking writer.close() until we explicitly resolve it.
-      let resolveClose!: () => void;
-      const closeBlocked = new Promise<void>((resolve) => {
-        resolveClose = resolve;
+      // Hold the publish path open by blocking sendText() until we explicitly resolve it.
+      let resolveSend!: () => void;
+      const sendBlocked = new Promise<void>((resolve) => {
+        resolveSend = resolve;
       });
-      mockStreamTextWriter.close = vi.fn().mockReturnValue(closeBlocked);
+      sendTextMock.mockReturnValue(sendBlocked);
 
-      // Start performRpc but don't await its return yet. The synchronous prefix runs streamText.
+      // Start performRpc but don't await its return yet. The synchronous prefix runs sendText.
       const performRpcPromise = rpcClientManager.performRpc({
         destinationIdentity: 'destination-identity',
         method: 'test-method',
@@ -352,11 +346,10 @@ describe('RpcClientManager', () => {
         responseTimeout: 200,
       });
 
-      // streamText was called synchronously; pull the request id out of the attributes.
-      const streamTextCalls = (mockOutgoingDataStreamManager.streamText as ReturnType<typeof vi.fn>)
-        .mock.calls;
-      expect(streamTextCalls.length).toBe(1);
-      const requestId = streamTextCalls[0][0].attributes[RpcRequestAttrs.RPC_REQUEST_ID];
+      // sendText was called synchronously; pull the request id out of the attributes.
+      const sendTextCalls = sendTextMock.mock.calls;
+      expect(sendTextCalls.length).toBe(1);
+      const requestId = sendTextCalls[0][1].attributes[RpcRequestAttrs.RPC_REQUEST_ID];
 
       // Deliver ack and response BEFORE close() unblocks - the publish has not yet returned.
       rpcClientManager.handleIncomingRpcAck(requestId);
@@ -367,7 +360,7 @@ describe('RpcClientManager', () => {
       );
 
       // Now allow the publish path to complete.
-      resolveClose();
+      resolveSend();
 
       const [, completionPromise] = await performRpcPromise;
       await expect(completionPromise).resolves.toStrictEqual('response-payload');

package/src/room/rpc/client/RpcClientManager.ts

@@ -145,7 +145,7 @@ export default class RpcClientManager extends (EventEmitter as new () => TypedEm
   ) {
     if (remoteClientProtocol >= CLIENT_PROTOCOL_DATA_STREAM_RPC) {
       // Send payload as a data stream - a "version 2" rpc request.
-      const writer = await this.outgoingDataStreamManager.streamText({
+      await this.outgoingDataStreamManager.sendText(payload, {
         topic: RPC_REQUEST_DATA_STREAM_TOPIC,
         destinationIdentities: [destinationIdentity],
         attributes: {
@@ -155,9 +155,6 @@ export default class RpcClientManager extends (EventEmitter as new () => TypedEm
           [RpcRequestAttrs.RPC_REQUEST_VERSION]: `${RPC_VERSION_V2}`,
         },
       });
-
-      await writer.write(payload);
-      await writer.close();
       return;
     }
 

package/src/room/rpc/server/RpcServerManager.test.ts

@@ -2,7 +2,11 @@ import { RpcRequest } from '@livekit/protocol';
 import { assert, beforeEach, describe, expect, it, vi } from 'vitest';
 import log from '../../../logger';
 import { subscribeToEvents } from '../../../utils/subscribeToEvents';
-import { CLIENT_PROTOCOL_DATA_STREAM_RPC, CLIENT_PROTOCOL_DEFAULT } from '../../../version';
+import {
+  CLIENT_PROTOCOL_DATA_STREAM_RPC,
+  CLIENT_PROTOCOL_DATA_STREAM_V2,
+  CLIENT_PROTOCOL_DEFAULT,
+} from '../../../version';
 import type RTCEngine from '../../RTCEngine';
 import OutgoingDataStreamManager from '../../data-stream/outgoing/OutgoingDataStreamManager';
 import { RPC_RESPONSE_DATA_STREAM_TOPIC, RpcError, RpcRequestAttrs } from '../utils';
@@ -17,6 +21,8 @@ describe('RpcServerManager', () => {
       const outgoingDataStreamManager = new OutgoingDataStreamManager(
         {} as unknown as RTCEngine,
         log,
+        (_identity) => CLIENT_PROTOCOL_DEFAULT,
+        () => [],
       );
 
       rpcServerManager = new RpcServerManager(
@@ -184,22 +190,17 @@ describe('RpcServerManager', () => {
   describe('v2 -> v2', () => {
     let rpcServerManager: RpcServerManager;
     let outgoingDataStreamManager: OutgoingDataStreamManager;
-    let mockStreamTextWriter: {
-      write: ReturnType<typeof vi.fn>;
-      close: ReturnType<typeof vi.fn>;
-    };
 
     beforeEach(() => {
-      outgoingDataStreamManager = new OutgoingDataStreamManager({} as unknown as RTCEngine, log);
-
-      mockStreamTextWriter = {
-        write: vi.fn().mockResolvedValue(undefined),
-        close: vi.fn().mockResolvedValue(undefined),
-      };
-      vi.spyOn(outgoingDataStreamManager, 'streamText').mockResolvedValue(
-        mockStreamTextWriter as any,
+      outgoingDataStreamManager = new OutgoingDataStreamManager(
+        {} as unknown as RTCEngine,
+        log,
+        (_identity) => CLIENT_PROTOCOL_DATA_STREAM_V2,
+        () => [],
       );
 
+      vi.spyOn(outgoingDataStreamManager, 'sendText').mockResolvedValue(undefined as any);
+
       rpcServerManager = new RpcServerManager(
         log,
         outgoingDataStreamManager,
@@ -243,15 +244,14 @@ describe('RpcServerManager', () => {
 
       // The response should have been sent via data stream, not packet
       expect(managerEvents.areThereBufferedEvents('sendDataPacket')).toBe(false);
-      expect(outgoingDataStreamManager.streamText).toHaveBeenCalledWith(
+      expect(outgoingDataStreamManager.sendText).toHaveBeenCalledWith(
+        'response payload',
         expect.objectContaining({
           topic: RPC_RESPONSE_DATA_STREAM_TOPIC,
           destinationIdentities: ['caller-identity'],
           attributes: { [RpcRequestAttrs.RPC_REQUEST_ID]: requestId },
         }),
       );
-      expect(mockStreamTextWriter.write).toHaveBeenCalledWith('response payload');
-      expect(mockStreamTextWriter.close).toHaveBeenCalled();
     });
 
     it('should receive a large rpc request (> 15kb) and send a large response via data stream from a participant', async () => {
@@ -277,15 +277,14 @@ describe('RpcServerManager', () => {
 
       // The response should have been sent via data stream, not packet
       expect(managerEvents.areThereBufferedEvents('sendDataPacket')).toBe(false);
-      expect(outgoingDataStreamManager.streamText).toHaveBeenCalledWith(
+      expect(outgoingDataStreamManager.sendText).toHaveBeenCalledWith(
+        new Array(20_000).fill('B').join(''),
         expect.objectContaining({
           topic: RPC_RESPONSE_DATA_STREAM_TOPIC,
           destinationIdentities: ['caller-identity'],
           attributes: { [RpcRequestAttrs.RPC_REQUEST_ID]: requestId },
         }),
       );
-      expect(mockStreamTextWriter.write).toHaveBeenCalledWith(new Array(20_000).fill('B').join(''));
-      expect(mockStreamTextWriter.close).toHaveBeenCalled();
     });
 
     it('should register an RPC method handler', async () => {
@@ -317,7 +316,7 @@ describe('RpcServerManager', () => {
 
       // Response goes via data stream, not packet
       expect(managerEvents.areThereBufferedEvents('sendDataPacket')).toBe(false);
-      expect(outgoingDataStreamManager.streamText).toHaveBeenCalled();
+      expect(outgoingDataStreamManager.sendText).toHaveBeenCalled();
     });
 
     it('should catch and transform unhandled errors in the RPC method handler', async () => {
@@ -414,7 +413,7 @@ describe('RpcServerManager', () => {
       const errorResponse = errorEvent.packet.value.value.value.value;
       expect(errorResponse.code).toStrictEqual(RpcError.ErrorCode.UNSUPPORTED_METHOD);
 
-      expect(outgoingDataStreamManager.streamText).not.toHaveBeenCalled();
+      expect(outgoingDataStreamManager.sendText).not.toHaveBeenCalled();
       expect(managerEvents.areThereBufferedEvents('sendDataPacket')).toBe(false);
     });
   });
@@ -424,8 +423,10 @@ describe('RpcServerManager', () => {
       const outgoingDataStreamManager = new OutgoingDataStreamManager(
         {} as unknown as RTCEngine,
         log,
+        (_identity) => CLIENT_PROTOCOL_DEFAULT,
+        () => [],
       );
-      const streamTextSpy = vi.spyOn(outgoingDataStreamManager, 'streamText');
+      const sendTextSpy = vi.spyOn(outgoingDataStreamManager, 'sendText');
 
       const rpcServerManager = new RpcServerManager(
         log,
@@ -457,7 +458,7 @@ describe('RpcServerManager', () => {
       assert(ackEvent.packet.value.case === 'rpcAck');
 
       // Response should be a v1 RpcResponse packet, not a data stream
-      expect(streamTextSpy).not.toHaveBeenCalled();
+      expect(sendTextSpy).not.toHaveBeenCalled();
       const responseEvent = await managerEvents.waitFor('sendDataPacket');
       assert(responseEvent.packet.value.case === 'rpcResponse');
       const rpcResponse = responseEvent.packet.value.value;

package/src/room/rpc/server/RpcServerManager.ts

@@ -263,13 +263,11 @@ export default class RpcServerManager extends (EventEmitter as new () => TypedEm
 
     if (callerClientProtocol >= CLIENT_PROTOCOL_DATA_STREAM_RPC) {
       // Send response as a data stream
-      const writer = await this.outgoingDataStreamManager.streamText({
+      await this.outgoingDataStreamManager.sendText(payload, {
         topic: RPC_RESPONSE_DATA_STREAM_TOPIC,
         destinationIdentities: [destinationIdentity],
         attributes: { [RpcRequestAttrs.RPC_REQUEST_ID]: requestId },
       });
-      await writer.write(payload);
-      await writer.close();
       return;
     }
 

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

@@ -213,29 +213,34 @@ class TokenSourceEndpoint extends TokenSourceCached {
     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)
+      // what's in TokenSourceResponse depending on the implementation (ie, DevelopmentTokenServer)
       ignoreUnknownFields: true,
     });
   }
 }
 
-export type SandboxTokenServerOptions = {
+export type DevelopmentTokenServerOptions = {
   baseUrl?: string;
 };
-
-class TokenSourceSandboxTokenServer extends TokenSourceEndpoint {
-  constructor(sandboxId: string, options: SandboxTokenServerOptions) {
+class TokenSourceDevelopmentTokenServer extends TokenSourceEndpoint {
+  constructor(tokenServerId: string, options: DevelopmentTokenServerOptions) {
     const { baseUrl = 'https://cloud-api.livekit.io', ...rest } = options;
 
     super(`${baseUrl}/api/v2/sandbox/connection-details`, {
       ...rest,
       headers: {
-        'X-Sandbox-ID': sandboxId,
+        'X-Sandbox-ID': tokenServerId,
       },
     });
   }
 }
 
+/** @deprecated use {@link DevelopmentTokenServerOptions} instead */
+export type SandboxTokenServerOptions = DevelopmentTokenServerOptions;
+
+/** @deprecated Use {@link TokenSourceDevelopmentTokenServer} instead */
+class TokenSourceSandboxTokenServer extends TokenSourceDevelopmentTokenServer {}
+
 export {
   /** The return type of {@link TokenSource.literal} */
   type TokenSourceLiteral,
@@ -243,8 +248,9 @@ export {
   type TokenSourceCustom,
   /** The return type of {@link TokenSource.endpoint} */
   type TokenSourceEndpoint,
-  /** The return type of {@link TokenSource.sandboxTokenServer} */
   type TokenSourceSandboxTokenServer,
+  /** The return type of {@link TokenSource.developmentTokenServer} */
+  type TokenSourceDevelopmentTokenServer,
   decodeTokenPayload,
   areTokenSourceFetchOptionsEqual,
 };
@@ -269,22 +275,29 @@ export const TokenSource = {
   /**
    * TokenSource.endpoint creates a token source that fetches credentials from a given URL using
    * the standard endpoint format:
-   * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
+   * @see https://docs.livekit.io/frontends/build/authentication/endpoint/
    */
   endpoint(url: string, options: EndpointOptions = {}) {
     return new TokenSourceEndpoint(url, options);
   },
 
   /**
-   * TokenSource.sandboxTokenServer queries a sandbox token server for credentials,
+   * @deprecated Use {@link TokenSource.developmentTokenServer} instead
+   */
+  sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) {
+    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  },
+
+  /**
+   * TokenSource.developmentTokenServer queries a development 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
+   * @see https://docs.livekit.io/frontends/build/authentication/sandbox-token-server/
    */
-  sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) {
-    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  developmentTokenServer(tokenServerId: string, options: DevelopmentTokenServerOptions = {}) {
+    return new TokenSourceDevelopmentTokenServer(tokenServerId, options);
   },
 };

package/src/room/track/LocalVideoTrack.test.ts

@@ -1,6 +1,8 @@
-import { describe, expect, it } from 'vitest';
-import { videoLayersFromEncodings } from './LocalVideoTrack';
+import { describe, expect, it, vi } from 'vitest';
+import LocalVideoTrack, { videoLayersFromEncodings } from './LocalVideoTrack';
+import type { SimulcastTrackInfo } from './LocalVideoTrack';
 import { VideoQuality } from './Track';
+import type { VideoCodec } from './options';
 
 describe('videoLayersFromEncodings', () => {
   it('returns single layer for no encoding', () => {
@@ -131,3 +133,104 @@ describe('videoLayersFromEncodings', () => {
     expect(layers[2].width).toBe(720);
   });
 });
+
+function makeSender(label = 'sender', events: string[] = []) {
+  let params: RTCRtpSendParameters = {
+    encodings: [],
+    transactionId: '',
+    codecs: [],
+    headerExtensions: [],
+    rtcp: {},
+  };
+  return {
+    getParameters: () => params,
+    // resolves on a later task, like the real setParameters, so that a caller
+    // which fails to await it never observes the update
+    setParameters: vi.fn(async (next: RTCRtpSendParameters) => {
+      events.push(`${label}:start`);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      params = next;
+      events.push(`${label}:done`);
+    }),
+    get degradationPreference() {
+      return params.degradationPreference;
+    },
+  };
+}
+
+function makeTrack() {
+  const track = Object.create(LocalVideoTrack.prototype) as LocalVideoTrack;
+  Object.assign(track, {
+    log: { debug: vi.fn(), warn: vi.fn() },
+    simulcastCodecs: new Map<VideoCodec, SimulcastTrackInfo>(),
+    subscribedCodecs: undefined,
+  });
+  // logContext and mediaStreamTrack are getters we don't set up state for here
+  Object.defineProperty(track, 'logContext', { get: () => ({}) });
+  Object.defineProperty(track, 'mediaStreamTrack', { get: () => ({ clone: () => ({}) }) });
+  return track;
+}
+
+describe('setDegradationPreference', () => {
+  it('applies the preference to the primary sender', async () => {
+    const track = makeTrack();
+    const sender = makeSender();
+    Object.assign(track, { _sender: sender });
+
+    await track.setDegradationPreference('maintain-resolution');
+
+    expect(sender.degradationPreference).toBe('maintain-resolution');
+  });
+
+  it('applies the resolved preference to a backup codec sender', async () => {
+    const track = makeTrack();
+    const primary = makeSender();
+    Object.assign(track, { _sender: primary });
+
+    await track.setDegradationPreference('maintain-resolution');
+
+    // the backup codec transceiver is created later, when the server asks for it
+    const backupInfo = track.addSimulcastTrack('vp8', [])!;
+    const backup = makeSender();
+    await track.setSimulcastTrackSender('vp8', backup as unknown as RTCRtpSender);
+
+    expect(backupInfo.sender).toBe(backup);
+    expect(backup.degradationPreference).toBe('maintain-resolution');
+    expect(primary.degradationPreference).toBe('maintain-resolution');
+  });
+
+  it('updates every sender when the preference changes after the backup is published', async () => {
+    const track = makeTrack();
+    const primary = makeSender();
+    Object.assign(track, { _sender: primary });
+    await track.setDegradationPreference('maintain-framerate');
+
+    track.addSimulcastTrack('vp8', []);
+    const backup = makeSender();
+    await track.setSimulcastTrackSender('vp8', backup as unknown as RTCRtpSender);
+
+    await track.setDegradationPreference('balanced');
+
+    expect(primary.degradationPreference).toBe('balanced');
+    expect(backup.degradationPreference).toBe('balanced');
+  });
+
+  it('applies to senders one at a time', async () => {
+    const events: string[] = [];
+    const track = makeTrack();
+    const primary = makeSender('primary', events);
+    Object.assign(track, { _sender: primary });
+    track.addSimulcastTrack('vp8', []);
+    await track.setSimulcastTrackSender(
+      'vp8',
+      makeSender('backup', events) as unknown as RTCRtpSender,
+    );
+    events.length = 0;
+
+    await track.setDegradationPreference('balanced');
+
+    // setParameters is only valid against the most recent getParameters, so the
+    // writes must not overlap
+    expect(events).toEqual(['primary:start', 'primary:done', 'backup:start', 'backup:done']);
+  });
+});