livekit-client 2.19.1 → 2.20.0

package/src/room/RTCEngine.ts

@@ -54,13 +54,13 @@ 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 TypedPromise from '../utils/TypedPromise';
 import { DataPacketBuffer } from '../utils/dataPacketBuffer';
 import { TTLMap } from '../utils/ttlmap';
@@ -73,6 +73,7 @@ import {
   ConnectionError,
   ConnectionErrorReason,
   NegotiationError,
+  PublishDataError,
   SignalReconnectError,
   TrackInvalidError,
   UnexpectedConnectionState,
@@ -91,6 +92,7 @@ import type { LoggerOptions } from './types';
 import {
   Future,
   isPublisherOfferWithJoinSupported,
+  isReactNative,
   isVideoCodec,
   isVideoTrack,
   isWeb,
@@ -108,6 +110,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 +128,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;
@@ -324,12 +332,21 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       this.joinAttempts += 1;
 
       this.setupSignalClientCallbacks();
+      // Whether the initial publisher offer is bundled with the join request. Computed once and
+      // reused after the join below. Only the (non-Firefox) offer-with-join path does this.
+      const sendOfferWithJoin = !useV0Path && isPublisherOfferWithJoinSupported();
+
       let offerProto: SessionDescription | undefined;
-      if (!useV0Path && isPublisherOfferWithJoinSupported()) {
+      if (sendOfferWithJoin) {
         if (!this.pcManager) {
+          // Firefox is excluded from offer-with-join (see isPublisherOfferWithJoinSupported):
+          // customers reported ICE connectivity problems for FF on this path (#1919) that we were
+          // never able to reproduce, so out of caution FF stays on the deferred path below. The
+          // exact cause is unknown — note that ICE gathering does not actually start here, since
+          // createInitialOffer() defers setLocalDescription (via pendingInitialOffer) until the
+          // answer is applied, after updateConfiguration() has set the server's TURN servers.
           await this.configure();
-          this.createDataChannels();
-          this.addMediaSections(initialMediaSectionsAudio, initialMediaSectionsVideo);
+          this.applyInitialPublisherLayout();
         }
         const offer = await this.pcManager?.publisher.createInitialOffer();
         if (offer) {
@@ -358,11 +375,20 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       this.participantSid = joinResponse.participant?.sid;
 
       this.subscriberPrimary = joinResponse.subscriberPrimary;
-      if (!useV0Path && isPublisherOfferWithJoinSupported()) {
+      if (sendOfferWithJoin) {
         this.pcManager?.updateConfiguration(this.makeRTCConfiguration(joinResponse));
       } else {
         if (!this.pcManager) {
+          // Deferred path (Firefox, and V0): configure with the join response so the PC picks up
+          // the server's ICE servers and topology, then negotiate separately rather than bundling
+          // the offer with the join.
           await this.configure(joinResponse, !useV0Path);
+          if (!useV0Path) {
+            // The V1 first offer must carry the media layout so Firefox binds receive decoders for
+            // subscribed tracks — without it, subscribed audio/video arrive as RTP but
+            // never decode. V0 (legacy dual-PC) keeps its original lazy behavior.
+            this.applyInitialPublisherLayout();
+          }
         }
         // create offer
         if (!this.subscriberPrimary || joinResponse.fastPublish) {
@@ -431,18 +457,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);
@@ -451,6 +484,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;
@@ -770,7 +806,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');
@@ -814,6 +850,25 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     return rtcConfig;
   }
 
+  /**
+   * Populate the publisher PC so its first offer carries the data channels + recvonly media
+   * sections. Required for every V1 connection: Firefox only binds receive decoders for media
+   * present in that first offer, and the offer-with-join path needs the sections to
+   * build a meaningful initial offer. Must be called on a configured pcManager.
+   */
+  private applyInitialPublisherLayout() {
+    this.createDataChannels();
+    /**
+     * 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) {
     const transceiverInit: RTCRtpTransceiverInit = { direction: 'recvonly' };
     for (let i: number = 0; i < numAudios; i++) {
@@ -833,14 +888,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
@@ -866,6 +924,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;
@@ -994,17 +1057,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);
   };
@@ -1023,7 +1110,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;
   }
 
@@ -1043,50 +1130,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],
@@ -1506,6 +1598,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:
@@ -1746,20 +1855,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       }
       this.on(EngineEvent.Closing, handleClosed);
       this.on(EngineEvent.Restarting, handleClosed);
-
-      this.pcManager.publisher.once(
-        PCEvents.RTPVideoPayloadTypes,
-        (rtpTypes: MediaAttributes['rtp']) => {
-          const rtpMap = new Map<number, VideoCodec>();
-          rtpTypes.forEach((rtp) => {
-            const codec = rtp.codec.toLowerCase();
-            if (isVideoCodec(codec)) {
-              rtpMap.set(rtp.payload, codec);
-            }
-          });
-          this.emit(EngineEvent.RTPVideoMapUpdate, rtpMap);
-        },
-      );
+      this.pcManager.publisher.off(PCEvents.RTPVideoPayloadTypes, this.onRtpMapAvailable);
+      this.pcManager.publisher.once(PCEvents.RTPVideoPayloadTypes, this.onRtpMapAvailable);
 
       try {
         await this.pcManager.negotiate(abortController);
@@ -1906,6 +2003,17 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.shouldFailOnV1Path = true;
   }
 
+  private onRtpMapAvailable = (rtpTypes: MediaAttributes['rtp']) => {
+    const rtpMap = new Map<number, VideoCodec>();
+    rtpTypes.forEach((rtp) => {
+      const codec = rtp.codec.toLowerCase();
+      if (isVideoCodec(codec)) {
+        rtpMap.set(rtp.payload, codec);
+      }
+    });
+    this.emit(EngineEvent.RTPVideoMapUpdate, rtpMap);
+  };
+
   private dataChannelsInfo(): DataChannelInfo[] {
     const infos: DataChannelInfo[] = [];
     const getInfo = (dc: RTCDataChannel | undefined, target: SignalTarget) => {

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,6 @@ import type {
   RoomConnectOptions,
   RoomOptions,
 } from '../options';
-import { PacketTrailerManager } from '../packetTrailer/PacketTrailerManager';
-import { isPacketTrailerSupported } from '../packetTrailer/utils';
 import TypedPromise from '../utils/TypedPromise';
 import { getBrowser } from '../utils/browserParser';
 import { CLIENT_PROTOCOL_DEFAULT } from '../version';
@@ -198,7 +198,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 +343,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 +514,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 +971,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/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,13 @@ 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 TypedPromise from '../../utils/TypedPromise';
 import { PCTransportState } from '../PCTransportManager';
 import type RTCEngine from '../RTCEngine';
@@ -1085,7 +1085,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 +1416,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 +1501,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/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;