livekit-client 1.10.0 → 1.11.0

package/dist/ts4.2/src/room/participant/Participant.d.ts

@@ -1,4 +1,4 @@
-import type TypedEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import { DataPacket_Kind, ParticipantInfo, ParticipantPermission, ConnectionQuality as ProtoQuality, SubscriptionError } from '../../proto/livekit_models';
 import type LocalTrackPublication from '../track/LocalTrackPublication';
 import type RemoteTrack from '../track/RemoteTrack';
@@ -11,8 +11,7 @@ export declare enum ConnectionQuality {
     Poor = "poor",
     Unknown = "unknown"
 }
-declare const Participant_base: new () => TypedEmitter<ParticipantEventCallbacks>;
-export default class Participant extends Participant_base {
+export default class Participant extends EventEmitter<ParticipantEventCallbacks> {
     protected participantInfo?: ParticipantInfo;
     audioTracks: Map<string, TrackPublication>;
     videoTracks: Map<string, TrackPublication>;
@@ -90,5 +89,4 @@ export type ParticipantEventCallbacks = {
     participantPermissionsChanged: (prevPermissions?: ParticipantPermission) => void;
     trackSubscriptionStatusChanged: (publication: RemoteTrackPublication, status: TrackPublication.SubscriptionStatus) => void;
 };
-export {};
 //# sourceMappingURL=Participant.d.ts.map

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

@@ -1,3 +1,4 @@
+import type EventEmitter from 'eventemitter3';
 import type { SignalClient } from '../../api/SignalClient';
 import type { ParticipantInfo } from '../../proto/livekit_models';
 import RemoteTrackPublication from '../track/RemoteTrackPublication';
@@ -48,6 +49,6 @@ export default class RemoteParticipant extends Participant {
      */
     setAudioOutput(output: AudioOutputOptions): Promise<void>;
     /** @internal */
-    emit<E extends keyof ParticipantEventCallbacks>(event: E, ...args: Parameters<ParticipantEventCallbacks[E]>): boolean;
+    emit<T extends EventEmitter.EventNames<ParticipantEventCallbacks>>(event: T, ...args: EventEmitter.EventArgs<ParticipantEventCallbacks, T>): boolean;
 }
 //# sourceMappingURL=RemoteParticipant.d.ts.map

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

@@ -29,6 +29,7 @@ export default abstract class LocalTrack extends Track {
     get isUpstreamPaused(): boolean;
     get isUserProvided(): boolean;
     get mediaStreamTrack(): MediaStreamTrack;
+    private setMediaStreamTrack;
     waitForDimensions(timeout?: number): Promise<Track.Dimensions>;
     /**
      * @returns DeviceID of the device that is currently being used for this track

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

@@ -50,5 +50,5 @@ export default class LocalVideoTrack extends LocalTrack {
     protected handleAppVisibilityChanged(): Promise<void>;
 }
 export declare function videoQualityForRid(rid: string): VideoQuality;
-export declare function videoLayersFromEncodings(width: number, height: number, encodings?: RTCRtpEncodingParameters[]): VideoLayer[];
+export declare function videoLayersFromEncodings(width: number, height: number, encodings?: RTCRtpEncodingParameters[], svc?: boolean): VideoLayer[];
 //# sourceMappingURL=LocalVideoTrack.d.ts.map

package/dist/ts4.2/src/room/track/RemoteVideoTrack.d.ts

@@ -37,6 +37,7 @@ export default class RemoteVideoTrack extends RemoteTrack {
     private readonly debouncedHandleResize;
     private updateVisibility;
     private updateDimensions;
+    private getPixelDensity;
 }
 export interface ElementInfo {
     element: object;

package/dist/ts4.2/src/room/track/Track.d.ts

@@ -1,9 +1,8 @@
-import type TypedEventEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import type { SignalClient } from '../../api/SignalClient';
 import { TrackSource, TrackType } from '../../proto/livekit_models';
 import { StreamState as ProtoStreamState } from '../../proto/livekit_rtc';
-declare const Track_base: new () => TypedEventEmitter<TrackEventCallbacks>;
-export declare abstract class Track extends Track_base {
+export declare abstract class Track extends EventEmitter<TrackEventCallbacks> {
     kind: Track.Kind;
     attachedElements: HTMLMediaElement[];
     isMuted: boolean;
@@ -121,5 +120,4 @@ export type TrackEventCallbacks = {
     upstreamPaused: (track: any) => void;
     upstreamResumed: (track: any) => void;
 };
-export {};
 //# sourceMappingURL=Track.d.ts.map

package/dist/ts4.2/src/room/track/TrackPublication.d.ts

@@ -1,4 +1,4 @@
-import type TypedEventEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import type { SubscriptionError, TrackInfo } from '../../proto/livekit_models';
 import type { UpdateSubscription, UpdateTrackSettings } from '../../proto/livekit_rtc';
 import LocalAudioTrack from './LocalAudioTrack';
@@ -7,8 +7,7 @@ import RemoteAudioTrack from './RemoteAudioTrack';
 import type RemoteTrack from './RemoteTrack';
 import RemoteVideoTrack from './RemoteVideoTrack';
 import { Track } from './Track';
-declare const TrackPublication_base: new () => TypedEventEmitter<PublicationEventCallbacks>;
-export declare class TrackPublication extends TrackPublication_base {
+export declare class TrackPublication extends EventEmitter<PublicationEventCallbacks> {
     kind: Track.Kind;
     trackName: string;
     trackSid: Track.SID;
@@ -65,5 +64,4 @@ export type PublicationEventCallbacks = {
     subscriptionStatusChanged: (status: TrackPublication.SubscriptionStatus, prevStatus: TrackPublication.SubscriptionStatus) => void;
     subscriptionFailed: (error: SubscriptionError) => void;
 };
-export {};
 //# sourceMappingURL=TrackPublication.d.ts.map

package/dist/ts4.2/src/room/track/options.d.ts

@@ -54,10 +54,19 @@ export interface TrackPublishDefaults {
      */
     scalabilityMode?: ScalabilityMode;
     /**
-     * custom video simulcast layers for camera tracks, defaults to h180, h360
-     * You can specify up to two custom layers that will be used instead of
-     * the LiveKit default layers.
-     * Note: the layers need to be ordered from lowest to highest quality
+     * Up to two additional simulcast layers to publish in addition to the original
+     * Track.
+     * When left blank, it defaults to h180, h360.
+     * If a SVC codec is used (VP9 or AV1), this field has no effect.
+     *
+     * To publish three total layers, you would specify:
+     * {
+     *   videoEncoding: {...}, // encoding of the primary layer
+     *   videoSimulcastLayers: [
+     *     VideoPresets.h540,
+     *     VideoPresets.h216,
+     *   ],
+     * }
      */
     videoSimulcastLayers?: Array<VideoPreset>;
     /**

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

@@ -6,7 +6,8 @@ export type AudioTrack = RemoteAudioTrack | LocalAudioTrack;
 export type VideoTrack = RemoteVideoTrack | LocalVideoTrack;
 export type AdaptiveStreamSettings = {
     /**
-     * Set a custom pixel density, defaults to 1
+     * Set a custom pixel density. Defaults to 2 for high density screens (3+) or
+     * 1 otherwise.
      * When streaming videos on a ultra high definition screen this setting
      * let's you account for the devicePixelRatio of those screens.
      * Set it to `screen` to use the actual pixel density of the screen

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",
@@ -42,12 +42,11 @@
     "size-limit": "size-limit"
   },
   "dependencies": {
-    "events": "^3.3.0",
+    "eventemitter3": "^5.0.1",
     "loglevel": "^1.8.0",
     "protobufjs": "^7.0.0",
     "sdp-transform": "^2.14.1",
     "ts-debounce": "^4.0.0",
-    "typed-emitter": "^2.1.0",
     "webrtc-adapter": "^8.1.1"
   },
   "devDependencies": {

package/src/connectionHelper/ConnectionCheck.ts

@@ -1,5 +1,4 @@
-import { EventEmitter } from 'events';
-import type TypedEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import { CheckStatus, Checker } from './checks/Checker';
 import type { CheckInfo, InstantiableCheck } from './checks/Checker';
 import { PublishAudioCheck } from './checks/publishAudio';
@@ -11,7 +10,7 @@ import { WebSocketCheck } from './checks/websocket';
 
 export type { CheckInfo, CheckStatus };
 
-export class ConnectionCheck extends (EventEmitter as new () => TypedEmitter<ConnectionCheckCallbacks>) {
+export class ConnectionCheck extends EventEmitter<ConnectionCheckCallbacks> {
   token: string;
 
   url: string;

package/src/connectionHelper/checks/Checker.ts

@@ -1,5 +1,4 @@
-import { EventEmitter } from 'events';
-import type TypedEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import type { RoomConnectOptions, RoomOptions } from '../../options';
 import type RTCEngine from '../../room/RTCEngine';
 import Room, { ConnectionState } from '../../room/Room';
@@ -30,7 +29,7 @@ export interface CheckerOptions {
   connectOptions?: RoomConnectOptions;
 }
 
-export abstract class Checker extends (EventEmitter as new () => TypedEmitter<CheckerCallbacks>) {
+export abstract class Checker extends EventEmitter<CheckerCallbacks> {
   protected url: string;
 
   protected token: string;

package/src/logger.ts

@@ -21,7 +21,7 @@ type StructuredLogger = {
 
 const livekitLogger = log.getLogger('livekit');
 
-livekitLogger.setLevel(LogLevel.info);
+livekitLogger.setDefaultLevel(LogLevel.info);
 
 export default livekitLogger as StructuredLogger;
 
@@ -38,10 +38,10 @@ export type LogExtension = (level: LogLevel, msg: string, context?: object) => v
 export function setLogExtension(extension: LogExtension) {
   const originalFactory = livekitLogger.methodFactory;
 
-  livekitLogger.methodFactory = (methodName, logLevel, loggerName) => {
-    const rawMethod = originalFactory(methodName, logLevel, loggerName);
+  livekitLogger.methodFactory = (methodName, configLevel, loggerName) => {
+    const rawMethod = originalFactory(methodName, configLevel, loggerName);
 
-    const configLevel = livekitLogger.getLevel();
+    const logLevel = LogLevel[methodName as LogLevelString];
     const needLog = logLevel >= configLevel && logLevel < LogLevel.silent;
 
     return (msg, context?: [msg: string, context: object]) => {

package/src/room/PCTransport.ts

@@ -1,4 +1,4 @@
-import { EventEmitter } from 'events';
+import EventEmitter from 'eventemitter3';
 import { parse, write } from 'sdp-transform';
 import type { MediaDescription } from 'sdp-transform';
 import { debounce } from 'ts-debounce';

package/src/room/RTCEngine.ts

@@ -1,5 +1,4 @@
-import { EventEmitter } from 'events';
-import type TypedEventEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import { SignalClient } from '../api/SignalClient';
 import type { SignalOptions } from '../api/SignalClient';
 import log from '../logger';
@@ -65,7 +64,7 @@ enum PCState {
 }
 
 /** @internal */
-export default class RTCEngine extends (EventEmitter as new () => TypedEventEmitter<EngineEventCallbacks>) {
+export default class RTCEngine extends EventEmitter<EngineEventCallbacks> {
   publisher?: PCTransport;
 
   subscriber?: PCTransport;
@@ -1046,6 +1045,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       };
       this.once(EngineEvent.Restarted, onRestarted);
       this.once(EngineEvent.Disconnected, onDisconnected);
+      this.once(EngineEvent.Closing, onDisconnected);
     });
   };
 
@@ -1172,7 +1172,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       this.hasPublished = true;
 
       const handleClosed = () => {
-        log.debug('engine disconnected while negotiation was ongoing');
+        log.warn('engine disconnected while negotiation was ongoing');
         cleanup();
         resolve();
         return;

package/src/room/Room.ts

@@ -1,5 +1,4 @@
-import { EventEmitter } from 'events';
-import type TypedEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import 'webrtc-adapter';
 import { toProtoSessionDescription } from '../api/SignalClient';
 import log from '../logger';
@@ -65,6 +64,7 @@ import {
   createDummyVideoStreamTrack,
   getEmptyAudioStreamTrack,
   isCloud,
+  isSafari,
   isWeb,
   supportsSetSinkId,
   unpackStreamId,
@@ -90,7 +90,7 @@ export const RoomState = ConnectionState;
  *
  * @noInheritDoc
  */
-class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>) {
+class Room extends EventEmitter<RoomEventCallbacks> {
   state: ConnectionState = ConnectionState.Disconnected;
 
   /** map of sid: [[RemoteParticipant]] */
@@ -140,7 +140,6 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
    */
   constructor(options?: RoomOptions) {
     super();
-    this.setMaxListeners(100);
     this.participants = new Map();
     this.cachedParticipantSids = [];
     this.identityToSid = new Map();
@@ -495,6 +494,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       // capturing both 'pagehide' and 'beforeunload' to capture broadest set of browser behaviors
       window.addEventListener('pagehide', this.onPageLeave);
       window.addEventListener('beforeunload', this.onPageLeave);
+    }
+    if (isWeb()) {
+      document.addEventListener('freeze', this.onPageLeave);
       navigator.mediaDevices?.addEventListener('devicechange', this.handleDeviceChange);
     }
     this.setAndEmitConnectionState(ConnectionState.Connected);
@@ -657,8 +659,31 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
    */
   async startAudio() {
     await this.acquireAudioContext();
-
     const elements: Array<HTMLMediaElement> = [];
+
+    if (isSafari()) {
+      /**
+       * iOS Safari blocks audio element playback if
+       * - user is not publishing audio themselves and
+       * - no other audio source is playing
+       *
+       * as a workaround, we create an audio element with an empty track, so that
+       * silent audio is always playing
+       */
+      const audioId = 'livekit-dummy-audio-el';
+      let dummyAudioEl = document.getElementById(audioId) as HTMLAudioElement | null;
+      if (!dummyAudioEl) {
+        dummyAudioEl = document.createElement('audio');
+        dummyAudioEl.autoplay = true;
+        dummyAudioEl.hidden = true;
+        const track = getEmptyAudioStreamTrack();
+        track.enabled = true;
+        dummyAudioEl.srcObject = new MediaStream([track]);
+        document.body.append(dummyAudioEl);
+      }
+      elements.push(dummyAudioEl);
+    }
+
     this.participants.forEach((p) => {
       p.audioTracks.forEach((t) => {
         if (t.track) {
@@ -965,6 +990,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       if (isWeb()) {
         window.removeEventListener('beforeunload', this.onPageLeave);
         window.removeEventListener('pagehide', this.onPageLeave);
+        window.removeEventListener('freeze', this.onPageLeave);
         navigator.mediaDevices?.removeEventListener('devicechange', this.handleDeviceChange);
       }
     } finally {
@@ -1420,9 +1446,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     return true;
   }
 
-  private emitWhenConnected<E extends keyof RoomEventCallbacks>(
-    event: E,
-    ...args: Parameters<RoomEventCallbacks[E]>
+  private emitWhenConnected<T extends EventEmitter.EventNames<RoomEventCallbacks>>(
+    event: T,
+    ...args: EventEmitter.EventArgs<RoomEventCallbacks, T>
   ): boolean {
     if (this.state === ConnectionState.Connected) {
       return this.emit(event, ...args);
@@ -1599,10 +1625,14 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
   }
 
   // /** @internal */
-  emit<E extends keyof RoomEventCallbacks>(
-    event: E,
-    ...args: Parameters<RoomEventCallbacks[E]>
+  emit<T extends EventEmitter.EventNames<RoomEventCallbacks>>(
+    event: T,
+    ...args: EventEmitter.EventArgs<RoomEventCallbacks, T>
   ): boolean {
+    // emit<E extends keyof RoomEventCallbacks>(
+    //   event: E,
+    //   ...args: Parameters<RoomEventCallbacks[E]>
+    // ): boolean {
     // active speaker updates are too spammy
     if (event !== RoomEvent.ActiveSpeakersChanged) {
       log.debug(`room event ${event}`, { event, args });

package/src/room/participant/LocalParticipant.ts

@@ -143,8 +143,11 @@ export default class LocalParticipant extends Participant {
   };
 
   private handleDisconnected = () => {
-    this.reconnectFuture?.reject?.('Got disconnected during publishing attempt');
-    this.reconnectFuture = undefined;
+    if (this.reconnectFuture) {
+      this.reconnectFuture.promise.catch((e) => log.warn(e));
+      this.reconnectFuture?.reject?.('Got disconnected during reconnection attempt');
+      this.reconnectFuture = undefined;
+    }
   };
 
   /**
@@ -666,7 +669,12 @@ export default class LocalParticipant extends Participant {
         dims.height,
         opts,
       );
-      req.layers = videoLayersFromEncodings(req.width, req.height, encodings);
+      req.layers = videoLayersFromEncodings(
+        req.width,
+        req.height,
+        encodings,
+        isSVCCodec(opts.videoCodec),
+      );
     } else if (track.kind === Track.Kind.Audio) {
       encodings = [
         {

package/src/room/participant/Participant.ts

@@ -1,5 +1,4 @@
-import { EventEmitter } from 'events';
-import type TypedEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import log from '../../logger';
 import {
   DataPacket_Kind,
@@ -35,7 +34,7 @@ function qualityFromProto(q: ProtoQuality): ConnectionQuality {
   }
 }
 
-export default class Participant extends (EventEmitter as new () => TypedEmitter<ParticipantEventCallbacks>) {
+export default class Participant extends EventEmitter<ParticipantEventCallbacks> {
   protected participantInfo?: ParticipantInfo;
 
   audioTracks: Map<string, TrackPublication>;
@@ -72,7 +71,6 @@ export default class Participant extends (EventEmitter as new () => TypedEmitter
   /** @internal */
   constructor(sid: string, identity: string, name?: string, metadata?: string) {
     super();
-    this.setMaxListeners(100);
     this.sid = sid;
     this.identity = identity;
     this.name = name;

package/src/room/participant/RemoteParticipant.ts

@@ -1,3 +1,4 @@
+import type EventEmitter from 'eventemitter3';
 import type { SignalClient } from '../../api/SignalClient';
 import log from '../../logger';
 import type { ParticipantInfo, SubscriptionError } from '../../proto/livekit_models';
@@ -345,9 +346,9 @@ export default class RemoteParticipant extends Participant {
   }
 
   /** @internal */
-  emit<E extends keyof ParticipantEventCallbacks>(
-    event: E,
-    ...args: Parameters<ParticipantEventCallbacks[E]>
+  emit<T extends EventEmitter.EventNames<ParticipantEventCallbacks>>(
+    event: T,
+    ...args: EventEmitter.EventArgs<ParticipantEventCallbacks, T>
   ): boolean {
     log.trace('participant event', { participant: this.sid, event, args });
     return super.emit(event, ...args);

package/src/room/participant/publishUtils.ts

@@ -123,27 +123,25 @@ export function computeVideoEncodings(
   if (scalabilityMode && isSVCCodec(videoCodec)) {
     log.debug(`using svc with scalabilityMode ${scalabilityMode}`);
 
-    const encodings: RTCRtpEncodingParameters[] = [];
+    const sm = new ScalabilityMode(scalabilityMode);
 
-    // svc use first encoding as the original, so we sort encoding from high to low
-    switch (scalabilityMode) {
-      case 'L3T3':
-      case 'L3T3_KEY':
-        encodings.push({
-          rid: videoRids[2],
-          maxBitrate: videoEncoding.maxBitrate,
-          /* @ts-ignore */
-          maxFramerate: original.encoding.maxFramerate,
-          /* @ts-ignore */
-          scalabilityMode: scalabilityMode,
-        });
-        log.debug('encodings', encodings);
-        return encodings;
+    const encodings: RTCRtpEncodingParameters[] = [];
 
-      default:
-        // TODO : support other scalability modes
-        throw new Error(`unsupported scalabilityMode: ${scalabilityMode}`);
+    if (sm.spatial > 3) {
+      throw new Error(`unsupported scalabilityMode: ${scalabilityMode}`);
+    }
+    for (let i = 0; i < sm.spatial; i += 1) {
+      encodings.push({
+        rid: videoRids[2 - i],
+        maxBitrate: videoEncoding.maxBitrate / 3 ** i,
+        /* @ts-ignore */
+        maxFramerate: original.encoding.maxFramerate,
+      });
     }
+    /* @ts-ignore */
+    encodings[0].scalabilityMode = scalabilityMode;
+    log.debug('encodings', encodings);
+    return encodings;
   }
 
   if (!useSimulcast) {

package/src/room/track/LocalTrack.ts

@@ -47,12 +47,16 @@ export default abstract class LocalTrack extends Track {
     userProvidedTrack = false,
   ) {
     super(mediaTrack, kind);
-    this._mediaStreamTrack.addEventListener('ended', this.handleEnded);
-    this.constraints = constraints ?? mediaTrack.getConstraints();
     this.reacquireTrack = false;
     this.providedByUser = userProvidedTrack;
     this.muteLock = new Mutex();
     this.pauseUpstreamLock = new Mutex();
+    // added to satisfy TS compiler, constraints are synced with MediaStreamTrack
+    this.constraints = mediaTrack.getConstraints();
+    this.setMediaStreamTrack(mediaTrack);
+    if (constraints) {
+      this.constraints = constraints;
+    }
   }
 
   get id(): string {
@@ -88,6 +92,53 @@ export default abstract class LocalTrack extends Track {
     return this.processor?.processedTrack ?? this._mediaStreamTrack;
   }
 
+  private async setMediaStreamTrack(newTrack: MediaStreamTrack) {
+    if (newTrack === this._mediaStreamTrack) {
+      return;
+    }
+    if (this._mediaStreamTrack) {
+      // detach
+      this.attachedElements.forEach((el) => {
+        detachTrack(this._mediaStreamTrack, el);
+      });
+      this._mediaStreamTrack.removeEventListener('ended', this.handleEnded);
+      this._mediaStreamTrack.removeEventListener('mute', this.pauseUpstream);
+      this._mediaStreamTrack.removeEventListener('unmute', this.resumeUpstream);
+      if (!this.providedByUser) {
+        this._mediaStreamTrack.stop();
+      }
+    }
+
+    this.mediaStream = new MediaStream([newTrack]);
+    if (newTrack) {
+      newTrack.addEventListener('ended', this.handleEnded);
+      // when underlying track emits mute, it indicates that the device is unable
+      // to produce media. In this case we'll need to signal with remote that
+      // the track is "muted"
+      // note this is different from LocalTrack.mute because we do not want to
+      // touch MediaStreamTrack.enabled
+      newTrack.addEventListener('mute', () => {
+        log.info('pausing upstream due to device mute');
+        this.pauseUpstream();
+      });
+      newTrack.addEventListener('unmute', this.resumeUpstream);
+      this.constraints = newTrack.getConstraints();
+    }
+    if (this.sender) {
+      await this.sender.replaceTrack(newTrack);
+    }
+    this._mediaStreamTrack = newTrack;
+    if (newTrack) {
+      // sync muted state with the enabled state of the newly provided track
+      this._mediaStreamTrack.enabled = !this.isMuted;
+      // when a valid track is replace, we'd want to start producing
+      await this.resumeUpstream();
+      this.attachedElements.forEach((el) => {
+        attachToElement(newTrack, el);
+      });
+    }
+  }
+
   async waitForDimensions(timeout = defaultDimensionsTimeout): Promise<Track.Dimensions> {
     if (this.kind === Track.Kind.Audio) {
       throw new Error('cannot get dimensions for audio tracks');
@@ -133,37 +184,12 @@ export default abstract class LocalTrack extends Track {
       throw new TrackInvalidError('unable to replace an unpublished track');
     }
 
-    // detach
-    this.attachedElements.forEach((el) => {
-      detachTrack(this._mediaStreamTrack, el);
-    });
-    this._mediaStreamTrack.removeEventListener('ended', this.handleEnded);
-    // on Safari, the old audio track must be stopped before attempting to acquire
-    // the new track, otherwise the new track will stop with
-    // 'A MediaStreamTrack ended due to a capture failure`
-    if (!this.providedByUser) {
-      this._mediaStreamTrack.stop();
-    }
-
-    track.addEventListener('ended', this.handleEnded);
     log.debug('replace MediaStreamTrack');
-
-    if (this.sender) {
-      await this.sender.replaceTrack(track);
-    }
-    this._mediaStreamTrack = track;
-
-    // sync muted state with the enabled state of the newly provided track
-    this._mediaStreamTrack.enabled = !this.isMuted;
-
-    await this.resumeUpstream();
-
-    this.attachedElements.forEach((el) => {
-      attachToElement(track, el);
-    });
-
-    this.mediaStream = new MediaStream([track]);
+    this.setMediaStreamTrack(track);
+    // this must be synced *after* setting mediaStreamTrack above, since it relies
+    // on the previous state in order to cleanup
     this.providedByUser = userProvidedTrack;
+
     if (this.processor) {
       await this.stopProcessor();
     }
@@ -187,7 +213,8 @@ export default abstract class LocalTrack extends Track {
       streamConstraints.audio = constraints;
     }
 
-    // detach
+    // these steps are duplicated from setMediaStreamTrack because we must stop
+    // the previous tracks before new tracks can be acquired
     this.attachedElements.forEach((el) => {
       detachTrack(this.mediaStreamTrack, el);
     });
@@ -203,16 +230,7 @@ export default abstract class LocalTrack extends Track {
     newTrack.addEventListener('ended', this.handleEnded);
     log.debug('re-acquired MediaStreamTrack');
 
-    if (this.sender) {
-      // Track can be restarted after it's unpublished
-      await this.sender.replaceTrack(newTrack);
-    }
-
-    this._mediaStreamTrack = newTrack;
-
-    await this.resumeUpstream();
-
-    this.mediaStream = mediaStream;
+    this.setMediaStreamTrack(newTrack);
     this.constraints = constraints;
     if (this.processor) {
       const processor = this.processor;
@@ -315,6 +333,7 @@ export default abstract class LocalTrack extends Track {
       this._isUpstreamPaused = false;
       this.emit(TrackEvent.UpstreamResumed, this);
 
+      // this operation is noop if mediastreamtrack is already being sent
       await this.sender.replaceTrack(this._mediaStreamTrack);
     } finally {
       unlock();