livekit-client 2.19.2 → 2.20.1

package/src/room/RTCEngine.ts

@@ -54,13 +54,14 @@ import {
 } from '../api/SignalClient';
 import type { BaseE2EEManager } from '../e2ee/E2eeManager';
 import { asEncryptablePacket, isInsertableStreamSupported } from '../e2ee/utils';
+import {
+  hasFrameMetadataPublishOptions,
+  isFrameMetadataSupported,
+  shouldUseFrameMetadataScriptTransform,
+} from '../frameMetadata/utils';
 import log, { LoggerNames, getLogger } from '../logger';
 import type { InternalRoomOptions } from '../options';
-import {
-  hasPacketTrailerPublishOptions,
-  isPacketTrailerSupported,
-  shouldUsePacketTrailerScriptTransform,
-} from '../packetTrailer/utils';
+import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import TypedPromise from '../utils/TypedPromise';
 import { DataPacketBuffer } from '../utils/dataPacketBuffer';
 import { TTLMap } from '../utils/ttlmap';
@@ -73,6 +74,7 @@ import {
   ConnectionError,
   ConnectionErrorReason,
   NegotiationError,
+  PublishDataError,
   SignalReconnectError,
   TrackInvalidError,
   UnexpectedConnectionState,
@@ -91,6 +93,7 @@ import type { LoggerOptions } from './types';
 import {
   Future,
   isPublisherOfferWithJoinSupported,
+  isReactNative,
   isVideoCodec,
   isVideoTrack,
   isWeb,
@@ -108,6 +111,7 @@ const leaveReconnect = 'leave-reconnect';
 const reliabeReceiveStateTTL = 30_000;
 const lossyDataChannelBufferThresholdMin = 8 * 1024;
 const lossyDataChannelBufferThresholdMax = 256 * 1024;
+
 const initialMediaSectionsAudio = 3;
 const initialMediaSectionsVideo = 3;
 
@@ -125,6 +129,11 @@ export enum DataChannelKind {
   DATA_TRACK_LOSSY = 2,
 }
 
+// Default data-channel max message size (bytes), used when the remote SDP
+// answer does not advertise an `a=max-message-size` attribute (RFC 8841).
+// `0` means "no limit".
+const DEFAULT_MAX_MESSAGE_SIZE = 64_000;
+
 /** @internal */
 export default class RTCEngine extends (EventEmitter as new () => TypedEventEmitter<EngineEventCallbacks>) {
   client: SignalClient;
@@ -449,18 +458,25 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   }
 
   async cleanupPeerConnections() {
-    await this.pcManager?.close();
-    this.pcManager = undefined;
-
     const dcCleanup = (dc: RTCDataChannel | undefined) => {
-      if (!dc) return;
-      dc.close();
+      if (!dc) {
+        return;
+      }
+
+      // Detach the data channel handlers before closing anything. Closing a peer connection tears
+      // down the SCTP transport, which can dispatch `error`/`close` events on the still-open data
+      // channels; if our handlers are still attached at that point, handleDataError logs a spurious
+      // "Unknown DataChannel error" during an otherwise graceful disconnect. Removing the handlers
+      // before dc.close()/pcManager.close() makes this deterministic regardless of how/when the
+      // browser dispatches those teardown events. See livekit/client-sdk-js#1953.
       dc.onbufferedamountlow = null;
       dc.onclose = null;
       dc.onclosing = null;
       dc.onerror = null;
       dc.onmessage = null;
       dc.onopen = null;
+
+      dc.close();
     };
     dcCleanup(this.lossyDC);
     dcCleanup(this.lossyDCSub);
@@ -469,6 +485,9 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     dcCleanup(this.dataTrackDC);
     dcCleanup(this.dataTrackDCSub);
 
+    await this.pcManager?.close();
+    this.pcManager = undefined;
+
     this.lossyDC = undefined;
     this.lossyDCSub = undefined;
     this.reliableDC = undefined;
@@ -788,7 +807,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     // used; RTCRtpScriptTransform does not need the PeerConnection flag.
     const needsInsertableStreams =
       this.signalOpts?.e2eeEnabled ||
-      (this.options.packetTrailer?.worker && !shouldUsePacketTrailerScriptTransform());
+      (this.frameMetadataWorker && !shouldUseFrameMetadataScriptTransform());
 
     if (needsInsertableStreams && isInsertableStreamSupported()) {
       this.log.debug('E2EE - setting up transports with insertable streams');
@@ -840,7 +859,15 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
    */
   private applyInitialPublisherLayout() {
     this.createDataChannels();
-    this.addMediaSections(initialMediaSectionsAudio, initialMediaSectionsVideo);
+    /**
+     * Native libwebrtc does not support pre-populating the media sections,
+     * so we skip it for React Native.
+     *
+     * Related: https://github.com/livekit/rust-sdks/pull/1151
+     */
+    if (!isReactNative()) {
+      this.addMediaSections(initialMediaSectionsAudio, initialMediaSectionsVideo);
+    }
   }
 
   private addMediaSections(numAudios: number, numVideos: number) {
@@ -862,14 +889,17 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     if (this.lossyDC) {
       this.lossyDC.onmessage = null;
       this.lossyDC.onerror = null;
+      this.lossyDC.onclose = null;
     }
     if (this.reliableDC) {
       this.reliableDC.onmessage = null;
       this.reliableDC.onerror = null;
+      this.reliableDC.onclose = null;
     }
     if (this.dataTrackDC) {
       this.dataTrackDC.onmessage = null;
       this.dataTrackDC.onerror = null;
+      this.dataTrackDC.onclose = null;
     }
 
     // create data channels
@@ -895,6 +925,11 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.reliableDC.onerror = this.handleDataError;
     this.dataTrackDC.onerror = this.handleDataError;
 
+    // detect unexpected publisher data channel closes
+    this.lossyDC.onclose = this.handleDataChannelClose(DataChannelKind.LOSSY);
+    this.reliableDC.onclose = this.handleDataChannelClose(DataChannelKind.RELIABLE);
+    this.dataTrackDC.onclose = this.handleDataChannelClose(DataChannelKind.DATA_TRACK_LOSSY);
+
     // set up dc buffer threshold, set to 64kB (otherwise 0 by default)
     this.lossyDC.bufferedAmountLowThreshold = 65535;
     this.reliableDC.bufferedAmountLowThreshold = 65535;
@@ -1023,17 +1058,41 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   };
 
   private handleDataError = (event: Event) => {
+    // Errors fired while we're tearing the connection down (e.g. the SCTP transport aborting as
+    // the peer connection closes) carry no actionable information — the channel is going away
+    // regardless. Suppress them so a graceful disconnect doesn't surface spurious errors.
+    // See livekit/client-sdk-js#1953.
+    if (this._isClosed) {
+      return;
+    }
+
     const channel = event.currentTarget as RTCDataChannel;
     const channelKind = channel.maxRetransmits === 0 ? 'lossy' : 'reliable';
 
-    if (event instanceof ErrorEvent && event.error) {
-      const { error } = event.error;
-      this.log.error(`DataChannel error on ${channelKind}: ${event.message}`, { error });
+    if (typeof RTCErrorEvent !== 'undefined' && event instanceof RTCErrorEvent && event.error) {
+      const { error } = event;
+      this.log.error(`DataChannel error on ${channelKind}: ${error.message}`, {
+        error,
+        errorDetail: error.errorDetail,
+        sctpCauseCode: error.sctpCauseCode,
+      });
     } else {
       this.log.error(`Unknown DataChannel error on ${channelKind}`, { event });
     }
   };
 
+  private handleDataChannelClose = (kind: DataChannelKind) => () => {
+    // A publisher DC closing while the session is up and the publisher PC is still
+    // connected is the signature of an oversized message having aborted the channel
+    // (see livekit/rust-sdks#1137). Surface it; do not attempt renegotiation.
+    if (!this._isClosed && this.pcManager?.publisher.getConnectionState() === 'connected') {
+      this.log.error(
+        `publisher data channel '${DataChannelKind[kind]}' closed unexpectedly`,
+        this.logContext,
+      );
+    }
+  };
+
   private handleBufferedAmountLow = (channelKind: DataChannelKind) => {
     this.updateAndEmitDCBufferStatus(channelKind);
   };
@@ -1052,7 +1111,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     } else {
       throw new UnexpectedConnectionState('Required webRTC APIs not supported on this device');
     }
-    this.setupPacketTrailerSender(sender, opts);
+    this.setupFrameMetadataSender(sender, opts);
     return sender;
   }
 
@@ -1072,50 +1131,55 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       throw new UnexpectedConnectionState('Cannot stream on this device');
     }
     if (sender) {
-      this.setupPacketTrailerSender(sender, opts);
+      this.setupFrameMetadataSender(sender, opts);
     }
     return sender;
   }
 
-  private setupPacketTrailerSender(sender: RTCRtpSender, opts: TrackPublishOptions = {}) {
-    if (!this.options.packetTrailer?.worker || this.signalOpts?.e2eeEnabled) {
+  private get frameMetadataWorker(): Worker | undefined {
+    return (this.options.frameMetadata ?? this.options.packetTrailer)?.worker;
+  }
+
+  private setupFrameMetadataSender(sender: RTCRtpSender, opts: TrackPublishOptions = {}) {
+    const worker = this.frameMetadataWorker;
+    if (!worker || this.signalOpts?.e2eeEnabled) {
       return;
     }
 
-    const packetTrailer = opts.packetTrailer;
-    const hasPacketTrailer = hasPacketTrailerPublishOptions(packetTrailer);
+    const frameMetadata = opts.frameMetadata ?? opts.packetTrailer;
+    const hasMetadata = hasFrameMetadataPublishOptions(frameMetadata);
 
-    if (shouldUsePacketTrailerScriptTransform()) {
-      if (hasPacketTrailer) {
+    if (shouldUseFrameMetadataScriptTransform()) {
+      if (hasMetadata) {
         // @ts-ignore
-        sender.transform = new RTCRtpScriptTransform(this.options.packetTrailer.worker, {
+        sender.transform = new RTCRtpScriptTransform(worker, {
           kind: 'encode',
-          packetTrailer,
+          packetTrailer: frameMetadata,
         });
       }
       return;
     }
 
     if (
-      !isPacketTrailerSupported(this.options.packetTrailer) ||
+      !isFrameMetadataSupported(this.options.frameMetadata ?? this.options.packetTrailer) ||
       !('createEncodedStreams' in sender)
     ) {
-      if (hasPacketTrailer) {
-        this.log.warn('packet trailer transform not supported; skipping write', this.logContext);
+      if (hasMetadata) {
+        this.log.warn('frame metadata transform not supported; skipping write', this.logContext);
       }
       return;
     }
 
     // @ts-ignore
     const { readable, writable } = sender.createEncodedStreams();
-    if (hasPacketTrailer) {
-      this.options.packetTrailer.worker.postMessage(
+    if (hasMetadata) {
+      worker.postMessage(
         {
           kind: 'encode',
           data: {
             readableStream: readable,
             writableStream: writable,
-            packetTrailer,
+            packetTrailer: frameMetadata,
           },
         },
         [readable, writable],
@@ -1535,6 +1599,23 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     const msg = packet.toBinary() as Uint8Array<ArrayBuffer>;
 
+    // Clamp to the SDK default - libwebrtc advertises larger (~256 KiB)
+    // than LiveKit/pion can deliver end-to-end (~64 KiB), so we trust
+    // the answer up untilthe built in ceiling.
+    const maxPublisherMessageSizeBytes = Math.min(
+      this.pcManager?.getMaxPublisherMessageSize() ?? DEFAULT_MAX_MESSAGE_SIZE,
+      DEFAULT_MAX_MESSAGE_SIZE,
+    );
+    if (
+      typeof maxPublisherMessageSizeBytes !== 'undefined' &&
+      maxPublisherMessageSizeBytes !== 0 /* 0 means "no limit" */ &&
+      msg.byteLength > maxPublisherMessageSizeBytes
+    ) {
+      throw new PublishDataError(
+        `cannot publish data packet larger than ${maxPublisherMessageSizeBytes} bytes (got ${msg.byteLength})`,
+      );
+    }
+
     switch (kind) {
       case DataChannelKind.LOSSY:
       case DataChannelKind.DATA_TRACK_LOSSY:

package/src/room/Room.ts

@@ -37,6 +37,8 @@ import type TypedEmitter from 'typed-emitter';
 import { ensureTrailingSlash } from '../api/utils';
 import { EncryptionEvent } from '../e2ee';
 import { type BaseE2EEManager, E2EEManager } from '../e2ee/E2eeManager';
+import { FrameMetadataManager } from '../frameMetadata/FrameMetadataManager';
+import { isFrameMetadataSupported } from '../frameMetadata/utils';
 import log, { LoggerNames, getLogger } from '../logger';
 import type {
   InternalRoomConnectOptions,
@@ -44,8 +46,7 @@ import type {
   RoomConnectOptions,
   RoomOptions,
 } from '../options';
-import { PacketTrailerManager } from '../packetTrailer/PacketTrailerManager';
-import { isPacketTrailerSupported } from '../packetTrailer/utils';
+import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import TypedPromise from '../utils/TypedPromise';
 import { getBrowser } from '../utils/browserParser';
 import { CLIENT_PROTOCOL_DEFAULT } from '../version';
@@ -198,7 +199,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
   private e2eeManager: BaseE2EEManager | undefined;
 
-  private packetTrailerManager: PacketTrailerManager | undefined;
+  private frameMetadataManager: FrameMetadataManager | undefined;
 
   private e2eeStateMutex: Mutex = new Mutex();
 
@@ -343,7 +344,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       this.rpcServerManager,
     );
 
-    this.setupPacketTrailer();
+    this.setupFrameMetadata();
 
     if (this.options.e2ee || this.options.encryption) {
       this.setupE2EE();
@@ -514,11 +515,10 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
   }
 
-  private setupPacketTrailer() {
-    // The manager is always created so tracks that advertise packet trailer
-    // features can be wired up when the app passes a packet trailer worker.
-    this.packetTrailerManager = new PacketTrailerManager(this.options.packetTrailer);
-    this.packetTrailerManager.setup(this);
+  private setupFrameMetadata() {
+    const opts = this.options.frameMetadata ?? this.options.packetTrailer;
+    this.frameMetadataManager = new FrameMetadataManager(opts);
+    this.frameMetadataManager.setup(this);
   }
 
   private get logContext() {
@@ -972,7 +972,8 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         adaptiveStream:
           typeof roomOptions.adaptiveStream === 'object' ? true : roomOptions.adaptiveStream,
         clientInfoCapabilities:
-          isPacketTrailerSupported(roomOptions.packetTrailer) || !!this.e2eeManager
+          isFrameMetadataSupported(roomOptions.frameMetadata ?? roomOptions.packetTrailer) ||
+          !!this.e2eeManager
             ? [ClientInfo_Capability.CAP_PACKET_TRAILER]
             : undefined,
         maxRetries: connectOptions.maxRetries,

package/src/room/data-track/depacketizer.ts

@@ -1,5 +1,6 @@
 import { type Throws } from '@livekit/throws-transformer/throws';
 import { LoggerNames, getLogger } from '../../logger';
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import { LivekitReasonedError } from '../errors';
 import { type DataTrackFrameInternal } from './frame';
 import { DataTrackPacket, FrameMarker } from './packet';

package/src/room/data-track/frame.ts

@@ -1,3 +1,4 @@
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import { DataTrackExtensions, DataTrackUserTimestampExtension } from './packet/extensions';
 
 /** A pair of payload bytes and packet extensions which can be fed into a {@link DataTrackPacketizer}. */

package/src/room/data-track/outgoing/types.ts

@@ -1,3 +1,4 @@
+import type { NonSharedUint8Array } from '../../../type-polyfills/non-shared-typed-arrays';
 import type LocalDataTrack from '../LocalDataTrack';
 import { type DataTrackHandle } from '../handle';
 import { type DataTrackInfo, type DataTrackSid } from '../types';

package/src/room/data-track/packet/extensions.ts

@@ -1,4 +1,5 @@
 import { type Throws } from '@livekit/throws-transformer/throws';
+import type { NonSharedUint8Array } from '../../../type-polyfills/non-shared-typed-arrays';
 import { coerceToDataView } from '../utils';
 import { EXT_TAG_PADDING, U8_LENGTH_BYTES, U64_LENGTH_BYTES } from './constants';
 import { DataTrackDeserializeError, DataTrackDeserializeErrorReason } from './errors';

package/src/room/data-track/packet/index.ts

@@ -1,4 +1,5 @@
 import { type Throws } from '@livekit/throws-transformer/throws';
+import type { NonSharedUint8Array } from '../../../type-polyfills/non-shared-typed-arrays';
 import { DataTrackHandle, DataTrackHandleError, DataTrackHandleErrorReason } from '../handle';
 import {
   DataTrackTimestamp,

package/src/room/data-track/packet/serializable.ts

@@ -1,4 +1,5 @@
 import { type Throws } from '@livekit/throws-transformer/throws';
+import type { NonSharedUint8Array } from '../../../type-polyfills/non-shared-typed-arrays';
 import { DataTrackSerializeError } from './errors';
 
 /** An abstract class implementing common behavior related to data track binary serialization. */

package/src/room/participant/LocalParticipant.test.ts

@@ -5,18 +5,18 @@ import { Track } from '../track/Track';
 import type { TrackPublishOptions } from '../track/options';
 import LocalParticipant from './LocalParticipant';
 
-type PacketTrailerTestParticipant = {
-  canPublishPacketTrailer: () => boolean;
+type FrameMetadataTestParticipant = {
+  canPublishFrameMetadata: () => boolean;
   log: { warn: ReturnType<typeof vi.fn> };
-  normalizeRequestedPacketTrailerOptions: (
+  normalizeRequestedFrameMetadataOptions: (
     track: LocalTrack,
     opts: TrackPublishOptions,
   ) => PacketTrailerFeature[];
 };
 
-function makeParticipant(canPublishPacketTrailer: boolean) {
-  const participant = Object.create(LocalParticipant.prototype) as PacketTrailerTestParticipant;
-  participant.canPublishPacketTrailer = () => canPublishPacketTrailer;
+function makeParticipant(canPublishFrameMetadata: boolean) {
+  const participant = Object.create(LocalParticipant.prototype) as FrameMetadataTestParticipant;
+  participant.canPublishFrameMetadata = () => canPublishFrameMetadata;
   participant.log = { warn: vi.fn() };
   return participant;
 }
@@ -35,12 +35,12 @@ function makeTrack(kind: Track.Kind) {
   } as unknown as LocalTrack;
 }
 
-describe('LocalParticipant packet trailer publish options', () => {
-  it('normalizes requested video packet trailer options to advertised features', () => {
+describe('LocalParticipant frame metadata publish options', () => {
+  it('normalizes requested video frame metadata options to advertised features', () => {
     const participant = makeParticipant(true);
-    const opts: TrackPublishOptions = { packetTrailer: { timestamp: true, frameId: true } };
+    const opts: TrackPublishOptions = { frameMetadata: { timestamp: true, frameId: true } };
 
-    const features = participant.normalizeRequestedPacketTrailerOptions(
+    const features = participant.normalizeRequestedFrameMetadataOptions(
       makeTrack(Track.Kind.Video),
       opts,
     );
@@ -49,33 +49,33 @@ describe('LocalParticipant packet trailer publish options', () => {
       PacketTrailerFeature.PTF_USER_TIMESTAMP,
       PacketTrailerFeature.PTF_FRAME_ID,
     ]);
-    expect(opts.packetTrailer).toEqual({ timestamp: true, frameId: true });
+    expect(opts.frameMetadata).toEqual({ timestamp: true, frameId: true });
   });
 
-  it('clears packet trailer options for non-video tracks', () => {
+  it('clears frame metadata options for non-video tracks', () => {
     const participant = makeParticipant(true);
-    const opts: TrackPublishOptions = { packetTrailer: { timestamp: true } };
+    const opts: TrackPublishOptions = { frameMetadata: { timestamp: true } };
 
-    const features = participant.normalizeRequestedPacketTrailerOptions(
+    const features = participant.normalizeRequestedFrameMetadataOptions(
       makeTrack(Track.Kind.Audio),
       opts,
     );
 
     expect(features).toEqual([]);
-    expect(opts.packetTrailer).toBeUndefined();
+    expect(opts.frameMetadata).toBeUndefined();
   });
 
-  it('clears packet trailer options when publishing packet trailers is unsupported', () => {
+  it('clears frame metadata options when publishing frame metadata is unsupported', () => {
     const participant = makeParticipant(false);
-    const opts: TrackPublishOptions = { packetTrailer: { frameId: true } };
+    const opts: TrackPublishOptions = { frameMetadata: { frameId: true } };
 
-    const features = participant.normalizeRequestedPacketTrailerOptions(
+    const features = participant.normalizeRequestedFrameMetadataOptions(
       makeTrack(Track.Kind.Video),
       opts,
     );
 
     expect(features).toEqual([]);
-    expect(opts.packetTrailer).toBeUndefined();
+    expect(opts.frameMetadata).toBeUndefined();
     expect(participant.log.warn).toHaveBeenCalledOnce();
   });
 });

package/src/room/participant/LocalParticipant.ts

@@ -22,13 +22,14 @@ import {
   protoInt64,
 } from '@livekit/protocol';
 import { SignalConnectionState } from '../../api/SignalClient';
-import type { InternalRoomOptions } from '../../options';
 import {
-  getPacketTrailerFeatures,
-  getPacketTrailerPublishOptions,
-  hasPacketTrailerPublishOptions,
-  isPacketTrailerSupported,
-} from '../../packetTrailer/utils';
+  getFrameMetadataFeatures,
+  getFrameMetadataPublishOptions,
+  hasFrameMetadataPublishOptions,
+  isFrameMetadataSupported,
+} from '../../frameMetadata/utils';
+import type { InternalRoomOptions } from '../../options';
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import TypedPromise from '../../utils/TypedPromise';
 import { PCTransportState } from '../PCTransportManager';
 import type RTCEngine from '../RTCEngine';
@@ -1085,7 +1086,7 @@ export default class LocalParticipant extends Participant {
       audioFeatures.push(AudioTrackFeature.TF_PRECONNECT_BUFFER);
     }
     const packetTrailerFeatures: PacketTrailerFeature[] =
-      this.normalizeRequestedPacketTrailerOptions(track, opts);
+      this.normalizeRequestedFrameMetadataOptions(track, opts);
 
     // create track publication from track
     const req = new AddTrackRequest({
@@ -1416,31 +1417,36 @@ export default class LocalParticipant extends Participant {
     return publication;
   }
 
-  private canPublishPacketTrailer() {
+  private canPublishFrameMetadata() {
     return !!(
       this.roomOptions.e2ee ||
       this.roomOptions.encryption ||
-      isPacketTrailerSupported(this.roomOptions.packetTrailer)
+      isFrameMetadataSupported(this.roomOptions.frameMetadata ?? this.roomOptions.packetTrailer)
     );
   }
 
-  private normalizeRequestedPacketTrailerOptions(track: LocalTrack, opts: TrackPublishOptions) {
-    if (track.kind !== Track.Kind.Video || !hasPacketTrailerPublishOptions(opts.packetTrailer)) {
+  private normalizeRequestedFrameMetadataOptions(track: LocalTrack, opts: TrackPublishOptions) {
+    const fmOpts = opts.frameMetadata ?? opts.packetTrailer;
+    if (track.kind !== Track.Kind.Video || !hasFrameMetadataPublishOptions(fmOpts)) {
+      opts.frameMetadata = undefined;
       opts.packetTrailer = undefined;
       return [];
     }
 
-    if (!this.canPublishPacketTrailer()) {
-      this.log.warn('packet trailer transform not supported; not advertising features', {
+    if (!this.canPublishFrameMetadata()) {
+      this.log.warn('frame metadata transform not supported; not advertising features', {
         ...this.logContext,
         ...getLogContextFromTrack(track),
       });
+      opts.frameMetadata = undefined;
       opts.packetTrailer = undefined;
       return [];
     }
 
-    const features = getPacketTrailerFeatures(opts.packetTrailer);
-    opts.packetTrailer = getPacketTrailerPublishOptions(features);
+    const features = getFrameMetadataFeatures(fmOpts);
+    const normalized = getFrameMetadataPublishOptions(features);
+    opts.frameMetadata = normalized;
+    opts.packetTrailer = normalized;
     return features;
   }
 
@@ -1496,7 +1502,7 @@ export default class LocalParticipant extends Participant {
     if (!simulcastTrack) {
       return;
     }
-    const packetTrailerFeatures = this.normalizeRequestedPacketTrailerOptions(track, opts);
+    const packetTrailerFeatures = this.normalizeRequestedFrameMetadataOptions(track, opts);
 
     const req = new AddTrackRequest({
       cid: simulcastTrack.mediaStreamTrack.id,

package/src/room/participant/Participant.ts

@@ -12,6 +12,7 @@ import {
 import { EventEmitter } from 'events';
 import type TypedEmitter from 'typed-emitter';
 import log, { LoggerNames, type StructuredLogger, getLogger } from '../../logger';
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import { ParticipantEvent, TrackEvent } from '../events';
 import type LocalTrackPublication from '../track/LocalTrackPublication';
 import type LocalVideoTrack from '../track/LocalVideoTrack';

package/src/room/participant/publishUtils.test.ts

@@ -174,6 +174,12 @@ describe('customSimulcastLayers', () => {
     expect(sortedPresets[1].encoding.maxFramerate).toBe(15);
     expect(sortedPresets[2].encoding.maxFramerate).toBe(20);
   });
+  it('does not mutate the passed-in array', () => {
+    const presets = [VideoPresets.h1440, VideoPresets.h360, VideoPresets.h1080, VideoPresets.h90];
+    const original = [...presets];
+    sortPresets(presets);
+    expect(presets).toEqual(original);
+  });
 });
 
 describe('screenShareSimulcastDefaults', () => {

package/src/room/participant/publishUtils.ts

@@ -419,7 +419,10 @@ function encodingsFromPresets(
 /** @internal */
 export function sortPresets(presets: Array<VideoPreset> | undefined) {
   if (!presets) return;
-  return presets.sort((a, b) => {
+  // Sort a copy so we don't mutate the caller's array in place. Mutating the
+  // passed-in simulcast layers can cause consumers that compare options by value
+  // (e.g. components-react's useLiveKitRoom) to detect a spurious change.
+  return presets.slice().sort((a, b) => {
     const { encoding: aEnc } = a;
     const { encoding: bEnc } = b;
 

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

@@ -1,5 +1,5 @@
 import { DataPacket, DataPacket_Kind, RpcRequest } from '@livekit/protocol';
-import EventEmitter from 'events';
+import { EventEmitter } from 'events';
 import type TypedEmitter from 'typed-emitter';
 import { type StructuredLogger } from '../../../logger';
 import { CLIENT_PROTOCOL_DATA_STREAM_RPC } from '../../../version';

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

@@ -1,5 +1,5 @@
 import { DataPacket, DataPacket_Kind, RpcAck, RpcRequest, RpcResponse } from '@livekit/protocol';
-import EventEmitter from 'events';
+import { EventEmitter } from 'events';
 import type TypedEmitter from 'typed-emitter';
 import { type StructuredLogger } from '../../../logger';
 import { CLIENT_PROTOCOL_DATA_STREAM_RPC } from '../../../version';