livekit-client 2.18.3 → 2.18.5

package/dist/ts4.2/room/participant/RemoteParticipant.d.ts

@@ -1,7 +1,8 @@
 import type { ParticipantInfo } from '@livekit/protocol';
 import type { SignalClient } from '../../api/SignalClient';
 import { DeferrableMap } from '../../utils/deferrable-map';
-import type RemoteDataTrack from '../data-track/RemoteDataTrack';
+import RemoteDataTrack from '../data-track/RemoteDataTrack';
+import type IncomingDataTrackManager from '../data-track/incoming/IncomingDataTrackManager';
 import RemoteTrackPublication from '../track/RemoteTrackPublication';
 import { Track } from '../track/Track';
 import type { AudioOutputOptions } from '../track/options';
@@ -24,13 +25,13 @@ export default class RemoteParticipant extends Participant {
     private volumeMap;
     private audioOutput?;
     /** @internal */
-    static fromParticipantInfo(signalClient: SignalClient, pi: ParticipantInfo, loggerOptions: LoggerOptions): RemoteParticipant;
+    static fromParticipantInfo(signalClient: SignalClient, pi: ParticipantInfo, loggerOptions: LoggerOptions, manager: IncomingDataTrackManager): RemoteParticipant;
     protected get logContext(): {
         remoteParticipantID: string;
         remoteParticipant: string;
     };
     /** @internal */
-    constructor(signalClient: SignalClient, sid: string, identity?: string, name?: string, metadata?: string, attributes?: Record<string, string>, loggerOptions?: LoggerOptions, kind?: ParticipantKind);
+    constructor(signalClient: SignalClient, sid: string, identity?: string, name?: string, metadata?: string, attributes?: Record<string, string>, loggerOptions?: LoggerOptions, kind?: ParticipantKind, remoteDataTracks?: Array<RemoteDataTrack>);
     protected addTrackPublication(publication: RemoteTrackPublication): void;
     getTrackPublication(source: Track.Source): RemoteTrackPublication | undefined;
     getTrackPublicationByName(name: string): RemoteTrackPublication | undefined;

package/dist/ts4.2/room/track/LocalTrack.d.ts

@@ -60,6 +60,13 @@ export default abstract class LocalTrack<TrackKind extends Track.Kind = Track.Ki
     unmute(): Promise<this>;
     replaceTrack(track: MediaStreamTrack, options?: ReplaceTrackOptions): Promise<typeof this>;
     replaceTrack(track: MediaStreamTrack, userProvidedTrack?: boolean): Promise<typeof this>;
+    /**
+     * Hook invoked after the MediaStreamTrack on the sender has been swapped
+     * (via replaceTrack, setProcessor, or stopProcessor). Fires outside the
+     * trackChangeLock so subclasses can do asynchronous work such as polling
+     * for new dimensions without blocking other track operations.
+     */
+    protected onSenderTrackSwapped(): Promise<void>;
     protected restart(constraints?: MediaTrackConstraints, isUnmuting?: boolean): Promise<this>;
     protected setTrackMuted(muted: boolean): void;
     protected get needsReAcquisition(): boolean;

package/dist/ts4.2/room/track/LocalVideoTrack.d.ts

@@ -4,7 +4,7 @@ import type { VideoSenderStats } from '../stats';
 import type { LoggerOptions } from '../types';
 import LocalTrack from './LocalTrack';
 import { Track, VideoQuality } from './Track';
-import type { VideoCaptureOptions, VideoCodec } from './options';
+import type { TrackPublishOptions, VideoCaptureOptions, VideoCodec } from './options';
 import type { TrackProcessor } from './processor/types';
 export declare class SimulcastTrackInfo {
     codec: VideoCodec;
@@ -23,6 +23,8 @@ export default class LocalVideoTrack extends LocalTrack<Track.Kind.Video> {
     private degradationPreference;
     private isCpuConstrained;
     private optimizeForPerformance;
+    publishOptions?: TrackPublishOptions;
+    lastEncodedDimensions?: Track.Dimensions;
     get sender(): RTCRtpSender | undefined;
     set sender(sender: RTCRtpSender | undefined);
     /**
@@ -43,6 +45,15 @@ export default class LocalVideoTrack extends LocalTrack<Track.Kind.Video> {
     getSenderStats(): Promise<VideoSenderStats[]>;
     setPublishingQuality(maxQuality: VideoQuality): void;
     restartTrack(options?: VideoCaptureOptions): Promise<void>;
+    protected onSenderTrackSwapped(): Promise<void>;
+    /**
+     * Recomputes encoding parameters for this track's senders based on the current
+     * MediaStreamTrack dimensions and reapplies them via setParameters. This is a no-op
+     * if the track hasn't been published yet or if the track is in performance-optimized
+     * mode (which manages its own encodings).
+     */
+    private refreshSenderEncodings;
+    private applyEncodingsToSender;
     setProcessor(processor: TrackProcessor<Track.Kind.Video>, showProcessedStreamLocally?: boolean): Promise<void>;
     setDegradationPreference(preference: RTCDegradationPreference): Promise<void>;
     addSimulcastTrack(codec: VideoCodec, encodings?: RTCRtpEncodingParameters[]): SimulcastTrackInfo | undefined;

package/dist/ts4.2/room/types.d.ts

@@ -62,7 +62,7 @@ export type LiveKitReactNativeInfo = {
     platform: 'ios' | 'android' | 'windows' | 'macos' | 'web' | 'native';
     devicePixelRatio: number;
 };
-export type SimulationScenario = 'signal-reconnect' | 'speaker' | 'node-failure' | 'server-leave' | 'migration' | 'resume-reconnect' | 'force-tcp' | 'force-tls' | 'full-reconnect' | 'subscriber-bandwidth' | 'disconnect-signal-on-resume' | 'disconnect-signal-on-resume-no-messages' | 'leave-full-reconnect';
+export type SimulationScenario = 'signal-reconnect' | 'speaker' | 'node-failure' | 'server-leave' | 'migration' | 'resume-reconnect' | 'force-tcp' | 'force-tls' | 'full-reconnect' | 'subscriber-bandwidth' | 'disconnect-signal-on-resume' | 'disconnect-signal-on-resume-no-messages' | 'leave-full-reconnect' | 'fail-on-v1-path';
 export type LoggerOptions = {
     loggerName?: string;
     loggerContextCb?: () => Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.18.3",
+  "version": "2.18.5",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",
@@ -44,7 +44,7 @@
     "sdp-transform": "^2.15.0",
     "tslib": "2.8.1",
     "typed-emitter": "^2.1.0",
-    "webrtc-adapter": "^9.0.1"
+    "webrtc-adapter": "9.0.5"
   },
   "peerDependencies": {
     "@types/dom-mediacapture-record": "^1"
@@ -57,7 +57,7 @@
     "@eslint/js": "9.39.2",
     "@livekit/changesets-changelog-github": "^0.0.4",
     "@livekit/throws-transformer": "^0.1.3",
-    "@rollup/plugin-babel": "6.1.0",
+    "@rollup/plugin-babel": "7.0.0",
     "@rollup/plugin-commonjs": "28.0.9",
     "@rollup/plugin-json": "6.1.0",
     "@rollup/plugin-node-resolve": "16.0.3",

package/src/api/SignalClient.ts

@@ -1081,6 +1081,10 @@ export class SignalClient {
 
       switch (resp.status) {
         case 404:
+          const errorMsg = await resp.text();
+          if (errorMsg.includes('requested room does not exist')) {
+            return ConnectionError.notAllowed(errorMsg, resp.status);
+          }
           return ConnectionError.serviceNotFound(
             'v1 RTC path not found. Consider upgrading your LiveKit server version',
             'v0-rtc',

package/src/room/PCTransport.ts

@@ -165,7 +165,7 @@ export default class PCTransport extends EventEmitter {
       this.remoteStereoMids = stereoMids;
       this.remoteNackMids = nackMids;
     } else if (sd.type === 'answer') {
-      if (this.pendingInitialOffer) {
+      if (this.pendingInitialOffer && this._pc) {
         const initialOffer = this.pendingInitialOffer;
         this.pendingInitialOffer = undefined;
         const sdpParsed = parse(initialOffer.sdp ?? '');
@@ -523,6 +523,7 @@ export default class PCTransport extends EventEmitter {
     if (!this._pc) {
       return;
     }
+    this.pendingInitialOffer = undefined;
     this._pc.close();
     this._pc.onconnectionstatechange = null;
     this._pc.oniceconnectionstatechange = null;
@@ -539,8 +540,8 @@ export default class PCTransport extends EventEmitter {
   };
 
   private async setMungedSDP(sd: RTCSessionDescriptionInit, munged?: string, remote?: boolean) {
+    const originalSdp = sd.sdp;
     if (munged) {
-      const originalSdp = sd.sdp;
       sd.sdp = munged;
       try {
         this.log.debug(
@@ -557,7 +558,8 @@ export default class PCTransport extends EventEmitter {
         this.log.warn(`not able to set ${sd.type}, falling back to unmodified sdp`, {
           ...this.logContext,
           error: e,
-          sdp: munged,
+          mungedSdp: munged,
+          originalSdp,
         });
         sd.sdp = originalSdp;
       }
@@ -565,9 +567,9 @@ export default class PCTransport extends EventEmitter {
 
     try {
       if (remote) {
-        await this.pc.setRemoteDescription(sd);
+        await this._pc?.setRemoteDescription(sd);
       } else {
-        await this.pc.setLocalDescription(sd);
+        await this._pc?.setLocalDescription(sd);
       }
     } catch (e) {
       let msg = 'unknown error';
@@ -581,6 +583,9 @@ export default class PCTransport extends EventEmitter {
         error: msg,
         sdp: sd.sdp,
       };
+      if (munged && munged !== originalSdp) {
+        fields.mungedSdp = munged;
+      }
       if (!remote && this.pc.remoteDescription) {
         fields.remoteSdp = this.pc.remoteDescription;
       }
@@ -609,9 +614,6 @@ export default class PCTransport extends EventEmitter {
       if (this.ddExtID === 0) {
         let maxID = 0;
         sdp.media.forEach((m) => {
-          if (m.type !== 'video') {
-            return;
-          }
           m.ext?.forEach((ext) => {
             if (ext.value > maxID) {
               maxID = ext.value;

package/src/room/RTCEngine.ts

@@ -21,6 +21,7 @@ import {
   PublishDataTrackResponse,
   ReconnectReason,
   type ReconnectResponse,
+  type RegionSettings,
   RequestResponse,
   Room as RoomModel,
   RoomMovedResponse,
@@ -62,7 +63,6 @@ import { TTLMap } from '../utils/ttlmap';
 import PCTransport, { PCEvents } from './PCTransport';
 import { PCTransportManager, PCTransportState } from './PCTransportManager';
 import type { ReconnectContext, ReconnectPolicy } from './ReconnectPolicy';
-import { DEFAULT_MAX_AGE_MS, type RegionUrlProvider } from './RegionUrlProvider';
 import { DataTrackInfo } from './data-track/types';
 import { roomConnectOptionDefaults } from './defaults';
 import {
@@ -86,6 +86,7 @@ import type { TrackPublishOptions, VideoCodec } from './track/options';
 import { getTrackPublicationInfo } from './track/utils';
 import type { LoggerOptions } from './types';
 import {
+  Future,
   isCompressionStreamSupported,
   isVideoCodec,
   isVideoTrack,
@@ -220,7 +221,9 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
   private shouldFailNext: boolean = false;
 
-  private regionUrlProvider?: RegionUrlProvider;
+  private shouldFailOnV1Path: boolean = false;
+
+  private regionStrategy?: RegionStrategy;
 
   private log = log;
 
@@ -247,6 +250,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   /** used to indicate whether the browser is currently waiting to reconnect */
   private isWaitingForNetworkReconnect: boolean = false;
 
+  private bufferStatusLowClosingFuture = new Future<never, UnexpectedConnectionState>();
+
   constructor(private options: InternalRoomOptions) {
     super();
     this.log = getLogger(options.loggerName ?? LoggerNames.Engine);
@@ -280,6 +285,13 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.client.onParticipantUpdate = (updates) =>
       this.emit(EngineEvent.ParticipantUpdate, updates);
     this.client.onJoined = (joinResponse) => this.emit(EngineEvent.Joined, joinResponse);
+
+    this.on(EngineEvent.Closing, () => {
+      this.bufferStatusLowClosingFuture.reject?.(new UnexpectedConnectionState('engine closed'));
+    });
+    // Swallow the rejection at the source so it doesn't surface as an unhandled promise rejection
+    // when no waitForBufferStatusLow callers are attached.
+    this.bufferStatusLowClosingFuture.promise.catch(() => {});
   }
 
   /** @internal */
@@ -321,9 +333,15 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
           offerProto = toProtoSessionDescription(offer.offer, offer.offerId);
         }
       }
+
       if (abortSignal?.aborted) {
         throw ConnectionError.cancelled('Connection aborted');
       }
+
+      if (!useV0Path && this.shouldFailOnV1Path) {
+        this.shouldFailOnV1Path = false;
+        throw ConnectionError.serviceNotFound('Simulated v1 path failure', 'v0-rtc');
+      }
       const joinResponse = await this.client.join(
         url,
         token,
@@ -383,6 +401,10 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
           }
         } else if (e.reason === ConnectionErrorReason.ServiceNotFound) {
           this.log.warn(`Initial connection failed: ${e.message} – Retrying`);
+          if (this.pcManager) {
+            this.pcManager.onStateChange = undefined;
+            await this.cleanupPeerConnections();
+          }
           return this.join(url, token, opts, abortSignal, true);
         }
       }
@@ -456,6 +478,14 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   async cleanupClient() {
     await this.client.close();
     this.client.resetCallbacks();
+    // Any in-flight addTrack requests are orphaned by the signal reconnect — the new session
+    // won't deliver `trackPublishedResponse` for them, so reject the pending resolvers and
+    // clear the map. Otherwise a subsequent `addTrack` call with the same client id (e.g. a
+    // publish retry after a `NegotiationError`) throws `TrackInvalidError`.
+    for (const cid of Object.keys(this.pendingTrackResolvers)) {
+      this.pendingTrackResolvers[cid].reject();
+    }
+    this.pendingTrackResolvers = {};
   }
 
   addTrack(req: AddTrackRequest): Promise<TrackInfo> {
@@ -519,8 +549,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   }
 
   /* @internal */
-  setRegionUrlProvider(provider: RegionUrlProvider) {
-    this.regionUrlProvider = provider;
+  setRegionStrategy(strategy: RegionStrategy | undefined) {
+    this.regionStrategy = strategy;
   }
 
   private async configure(joinResponse?: JoinResponse, useSinglePeerConnection?: boolean) {
@@ -671,7 +701,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     this.client.onTokenRefresh = (token: string) => {
       this.token = token;
-      this.regionUrlProvider?.updateToken(token);
+      this.emit(EngineEvent.TokenRefreshed, token);
     };
 
     this.client.onRemoteMuteChanged = (trackSid: string, muted: boolean) => {
@@ -713,13 +743,9 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     this.client.onLeave = (leave: LeaveRequest) => {
       this.log.debug('client leave request', { ...this.logContext, reason: leave?.reason });
-      if (leave.regions && this.regionUrlProvider) {
+      if (leave.regions) {
         this.log.debug('updating regions', this.logContext);
-        this.regionUrlProvider.setServerReportedRegions({
-          updatedAtInMs: Date.now(),
-          maxAgeInMs: DEFAULT_MAX_AGE_MS,
-          regionSettings: leave.regions,
-        });
+        this.emit(EngineEvent.ServerRegionsReported, leave.regions);
       }
       switch (leave.action) {
         case LeaveRequest_Action.DISCONNECT:
@@ -1124,10 +1150,10 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.log.debug(`reconnecting in ${delay}ms`, this.logContext);
 
     this.clearReconnectTimeout();
-    if (this.token && this.regionUrlProvider) {
+    if (this.token) {
       // token may have been refreshed, we do not want to recreate the regionUrlProvider
       // since the current engine may have inherited a regional url
-      this.regionUrlProvider.updateToken(this.token);
+      this.emit(EngineEvent.TokenRefreshed, this.token);
     }
     this.reconnectTimeout = CriticalTimers.setTimeout(
       () =>
@@ -1260,17 +1286,17 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
         throw new SignalReconnectError('Signal connection got severed during reconnect');
       }
 
-      this.regionUrlProvider?.resetAttempts();
+      this.regionStrategy?.resetAttempts();
       // reconnect success
       this.emit(EngineEvent.Restarted);
     } catch (error) {
-      const nextRegionUrl = await this.regionUrlProvider?.getNextBestRegionUrl();
+      const nextRegionUrl = await this.regionStrategy?.getNextUrl();
       if (nextRegionUrl) {
         await this.restartConnection(nextRegionUrl);
         return;
       } else {
         // no more regions to try (or we're not on cloud)
-        this.regionUrlProvider?.resetAttempts();
+        this.regionStrategy?.resetAttempts();
         throw error;
       }
     }
@@ -1565,23 +1591,15 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       if (this.isBufferStatusLow(kind)) {
         resolve();
       } else {
-        const onClosing = () => reject(new UnexpectedConnectionState('engine closed'));
-        this.once(EngineEvent.Closing, onClosing);
         const dc = this.dataChannelForKind(kind);
         if (!dc) {
           reject(new UnexpectedConnectionState(`DataChannel not found, kind: ${kind}`));
           return;
         }
-        dc.addEventListener(
-          'bufferedamountlow',
-          () => {
-            this.off(EngineEvent.Closing, onClosing);
-            resolve();
-          },
-          {
-            once: true,
-          },
-        );
+        this.bufferStatusLowClosingFuture.promise.catch((e) => reject(e));
+        dc.addEventListener('bufferedamountlow', () => resolve(), {
+          once: true,
+        });
       }
     });
   }
@@ -1860,6 +1878,12 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.shouldFailNext = true;
   }
 
+  /* @internal */
+  failNextV1Path() {
+    // debugging method to fail the next connection attempt for /rtc/v1 to trigger the fallback version
+    this.shouldFailOnV1Path = true;
+  }
+
   private dataChannelsInfo(): DataChannelInfo[] {
     const infos: DataChannelInfo[] = [];
     const getInfo = (dc: RTCDataChannel | undefined, target: SignalTarget) => {
@@ -2004,8 +2028,15 @@ export type EngineEventCallbacks = {
   dataTrackSubscriberHandles: (event: DataTrackSubscriberHandles) => void;
   dataTrackPacketReceived: (packet: Uint8Array) => void;
   joined: (joinResponse: JoinResponse) => void;
+  tokenRefreshed: (token: string) => void;
+  serverRegionsReported: (regions: RegionSettings) => void;
 };
 
+export interface RegionStrategy {
+  getNextUrl(abortSignal?: AbortSignal): Promise<string | null>;
+  resetAttempts(): void;
+}
+
 function applyUserDataCompat(newObj: DataPacket, oldObj: UserPacket) {
   const participantIdentity = newObj.participantIdentity
     ? newObj.participantIdentity

package/src/room/RegionUrlProvider.ts

@@ -189,6 +189,13 @@ export class RegionUrlProvider {
 
   updateToken(token: string) {
     this.token = token;
+    const url = this.getServerUrl();
+    const settings = RegionUrlProvider.cache.get(url.hostname);
+    RegionUrlProvider.scheduleRefetch(
+      this.serverUrl,
+      this.token,
+      settings?.maxAgeInMs ?? DEFAULT_MAX_AGE_MS,
+    );
   }
 
   isCloud() {

package/src/room/Room.ts

@@ -47,8 +47,8 @@ import TypedPromise from '../utils/TypedPromise';
 import { getBrowser } from '../utils/browserParser';
 import { BackOffStrategy } from './BackOffStrategy';
 import DeviceManager from './DeviceManager';
-import RTCEngine, { DataChannelKind } from './RTCEngine';
-import { RegionUrlProvider } from './RegionUrlProvider';
+import RTCEngine, { DataChannelKind, type RegionStrategy } from './RTCEngine';
+import { DEFAULT_MAX_AGE_MS, RegionUrlProvider } from './RegionUrlProvider';
 import IncomingDataStreamManager from './data-stream/incoming/IncomingDataStreamManager';
 import {
   type ByteStreamHandler,
@@ -588,22 +588,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         this.emit(RoomEvent.DCBufferStatusChanged, status, kind);
       })
       .on(EngineEvent.LocalTrackSubscribed, (subscribedSid) => {
-        const trackPublication = this.localParticipant
-          .getTrackPublications()
-          .find(({ trackSid }) => trackSid === subscribedSid) as LocalTrackPublication | undefined;
-        if (!trackPublication) {
-          this.log.warn(
-            'could not find local track subscription for subscribed event',
-            this.logContext,
-          );
-          return;
-        }
-        this.localParticipant.emit(ParticipantEvent.LocalTrackSubscribed, trackPublication);
-        this.emitWhenConnected(
-          RoomEvent.LocalTrackSubscribed,
-          trackPublication,
-          this.localParticipant,
-        );
+        this.handleLocalTrackSubscribed(subscribedSid);
       })
       .on(EngineEvent.RoomMoved, (roomMoved) => {
         this.log.debug('room moved', roomMoved);
@@ -683,6 +668,16 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
           }),
         );
         this.incomingDataTrackManager.receiveSfuPublicationUpdates(mapped);
+      })
+      .on(EngineEvent.TokenRefreshed, (token) => {
+        this.regionUrlProvider?.updateToken(token);
+      })
+      .on(EngineEvent.ServerRegionsReported, (regions) => {
+        this.regionUrlProvider?.setServerReportedRegions({
+          regionSettings: regions,
+          updatedAtInMs: Date.now(),
+          maxAgeInMs: DEFAULT_MAX_AGE_MS,
+        });
       });
 
     if (this.localParticipant) {
@@ -696,6 +691,14 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
   }
 
+  private createRegionStrategy(): RegionStrategy {
+    return {
+      getNextUrl: async (signal?: AbortSignal) =>
+        this.regionUrlProvider ? this.regionUrlProvider.getNextBestRegionUrl(signal) : null,
+      resetAttempts: () => this.regionUrlProvider?.resetAttempts(),
+    };
+  }
+
   /**
    * getLocalDevices abstracts navigator.mediaDevices.enumerateDevices.
    * In particular, it requests device permissions by default if needed
@@ -980,7 +983,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       this.maybeCreateEngine();
     }
     if (this.regionUrlProvider?.isCloud()) {
-      this.engine.setRegionUrlProvider(this.regionUrlProvider);
+      this.engine.setRegionStrategy(this.createRegionStrategy());
     }
 
     this.acquireAudioContext();
@@ -1137,6 +1140,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         // @ts-expect-error function is private
         await this.engine.client.handleOnClose('simulate disconnect');
         break;
+      case 'fail-on-v1-path':
+        this.engine.failNextV1Path();
+        break;
       case 'speaker':
         req = new SimulateScenario({
           scenario: {
@@ -1623,6 +1629,65 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
   }
 
+  private handleLocalTrackSubscribed(subscribedSid: string) {
+    const findPublication = () =>
+      this.localParticipant
+        .getTrackPublications()
+        .find(({ trackSid }) => trackSid === subscribedSid) as LocalTrackPublication | undefined;
+
+    const trackPublication = findPublication();
+    if (trackPublication) {
+      this.emitLocalTrackSubscribed(trackPublication);
+      return;
+    }
+
+    // the track publication may not be registered yet if the server signals
+    // the subscription before publishTrack has finished adding the publication.
+    // defer with a timeout until LocalTrackPublished fires for the matching trackSid
+    this.log.debug('deferring LocalTrackSubscribed, publication not yet available', {
+      ...this.logContext,
+      subscribedSid,
+    });
+
+    const TIMEOUT_MS = 10_000;
+    let timer: ReturnType<typeof setTimeout>;
+
+    const onPublished = (pub: LocalTrackPublication) => {
+      if (pub.trackSid === subscribedSid) {
+        cleanup();
+        this.emitLocalTrackSubscribed(pub);
+      }
+    };
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      this.localParticipant.off(ParticipantEvent.LocalTrackPublished, onPublished);
+      this.off(RoomEvent.Disconnected, cleanup);
+    };
+
+    this.localParticipant.on(ParticipantEvent.LocalTrackPublished, onPublished);
+    this.once(RoomEvent.Disconnected, cleanup);
+
+    timer = setTimeout(() => {
+      cleanup();
+      // final attempt in case the publication was added without emitting the event
+      const pub = findPublication();
+      if (pub) {
+        this.emitLocalTrackSubscribed(pub);
+      } else {
+        this.log.warn(
+          'could not find local track publication for LocalTrackSubscribed event after timeout',
+          { ...this.logContext, subscribedSid },
+        );
+      }
+    }, TIMEOUT_MS);
+  }
+
+  private emitLocalTrackSubscribed(trackPublication: LocalTrackPublication) {
+    this.localParticipant.emit(ParticipantEvent.LocalTrackSubscribed, trackPublication);
+    this.emitWhenConnected(RoomEvent.LocalTrackSubscribed, trackPublication, this.localParticipant);
+  }
+
   private handleRestarting = () => {
     this.clearConnectionReconcile();
     // in case we went from resuming to full-reconnect, make sure to reflect it on the isResuming flag
@@ -2253,10 +2318,15 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
   private createParticipant(identity: string, info?: ParticipantInfo): RemoteParticipant {
     let participant: RemoteParticipant;
     if (info) {
-      participant = RemoteParticipant.fromParticipantInfo(this.engine.client, info, {
-        loggerContextCb: () => this.logContext,
-        loggerName: this.options.loggerName,
-      });
+      participant = RemoteParticipant.fromParticipantInfo(
+        this.engine.client,
+        info,
+        {
+          loggerContextCb: () => this.logContext,
+          loggerName: this.options.loggerName,
+        },
+        this.incomingDataTrackManager,
+      );
     } else {
       participant = new RemoteParticipant(
         this.engine.client,