livekit-client 1.9.7 → 1.11.0

package/src/room/track/LocalTrack.ts

@@ -1,16 +1,12 @@
 import log from '../../logger';
+import { getBrowser } from '../../utils/browserParser';
 import DeviceManager from '../DeviceManager';
-import { TrackInvalidError } from '../errors';
+import { DeviceUnsupportedError, TrackInvalidError } from '../errors';
 import { TrackEvent } from '../events';
-import {
-  Mutex,
-  getEmptyAudioStreamTrack,
-  getEmptyVideoStreamTrack,
-  isMobile,
-  sleep,
-} from '../utils';
+import { Mutex, compareVersions, isMobile, sleep } from '../utils';
 import { Track, attachToElement, detachTrack } from './Track';
 import type { VideoCodec } from './options';
+import type { TrackProcessor } from './processor/types';
 
 const defaultDimensionsTimeout = 1000;
 
@@ -31,6 +27,12 @@ export default abstract class LocalTrack extends Track {
 
   protected pauseUpstreamLock: Mutex;
 
+  protected processorElement?: HTMLMediaElement;
+
+  protected processor?: TrackProcessor<typeof this.kind>;
+
+  protected isSettingUpProcessor: boolean = false;
+
   /**
    *
    * @param mediaTrack
@@ -45,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 {
@@ -82,6 +88,57 @@ export default abstract class LocalTrack extends Track {
     return this.providedByUser;
   }
 
+  get mediaStreamTrack() {
+    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');
@@ -127,37 +184,15 @@ 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');
+    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.sender) {
-      await this.sender.replaceTrack(track);
+    if (this.processor) {
+      await this.stopProcessor();
     }
-    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.providedByUser = userProvidedTrack;
     return this;
   }
 
@@ -178,9 +213,10 @@ 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);
+      detachTrack(this.mediaStreamTrack, el);
     });
     this._mediaStreamTrack.removeEventListener('ended', this.handleEnded);
     // on Safari, the old audio track must be stopped before attempting to acquire
@@ -194,21 +230,16 @@ 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.attachedElements.forEach((el) => {
-      attachToElement(newTrack, el);
-    });
-
-    this.mediaStream = mediaStream;
+    this.setMediaStreamTrack(newTrack);
     this.constraints = constraints;
+    if (this.processor) {
+      const processor = this.processor;
+      await this.setProcessor(processor);
+    } else {
+      this.attachedElements.forEach((el) => {
+        attachToElement(this._mediaStreamTrack, el);
+      });
+    }
     this.emit(TrackEvent.Restarted, this);
     return this;
   }
@@ -253,6 +284,18 @@ export default abstract class LocalTrack extends Track {
     this.emit(TrackEvent.Ended, this);
   };
 
+  stop() {
+    super.stop();
+    this.processor?.destroy();
+    this.processor = undefined;
+  }
+
+  /**
+   * pauses publishing to the server without disabling the local MediaStreamTrack
+   * this is used to display a user's own video locally while pausing publishing to
+   * the server.
+   * this API is unsupported on Safari < 12 due to a bug
+   **/
   async pauseUpstream() {
     const unlock = await this.pauseUpstreamLock.lock();
     try {
@@ -266,9 +309,12 @@ export default abstract class LocalTrack extends Track {
 
       this._isUpstreamPaused = true;
       this.emit(TrackEvent.UpstreamPaused, this);
-      const emptyTrack =
-        this.kind === Track.Kind.Audio ? getEmptyAudioStreamTrack() : getEmptyVideoStreamTrack();
-      await this.sender.replaceTrack(emptyTrack);
+      const browser = getBrowser();
+      if (browser?.name === 'Safari' && compareVersions(browser.version, '12.0') < 0) {
+        // https://bugs.webkit.org/show_bug.cgi?id=184911
+        throw new DeviceUnsupportedError('pauseUpstream is not supported on Safari < 12.');
+      }
+      await this.sender.replaceTrack(null);
     } finally {
       unlock();
     }
@@ -287,11 +333,88 @@ 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();
     }
   }
 
+  /**
+   * Sets a processor on this track.
+   * See https://github.com/livekit/track-processors-js for example usage
+   *
+   * @experimental
+   *
+   * @param processor
+   * @param showProcessedStreamLocally
+   * @returns
+   */
+  async setProcessor(
+    processor: TrackProcessor<typeof this.kind>,
+    showProcessedStreamLocally = true,
+  ) {
+    if (this.isSettingUpProcessor) {
+      log.warn('already trying to set up a processor');
+      return;
+    }
+    log.debug('setting up processor');
+    this.isSettingUpProcessor = true;
+    if (this.processor) {
+      await this.stopProcessor();
+    }
+    if (this.kind === 'unknown') {
+      throw TypeError('cannot set processor on track of unknown kind');
+    }
+    this.processorElement = this.processorElement ?? document.createElement(this.kind);
+    this.processorElement.muted = true;
+
+    attachToElement(this._mediaStreamTrack, this.processorElement);
+    this.processorElement.play().catch((e) => log.error(e));
+
+    const processorOptions = {
+      kind: this.kind,
+      track: this._mediaStreamTrack,
+      element: this.processorElement,
+    };
+
+    await processor.init(processorOptions);
+    this.processor = processor;
+    if (this.processor.processedTrack) {
+      for (const el of this.attachedElements) {
+        if (el !== this.processorElement && showProcessedStreamLocally) {
+          detachTrack(this._mediaStreamTrack, el);
+          attachToElement(this.processor.processedTrack, el);
+        }
+      }
+      await this.sender?.replaceTrack(this.processor.processedTrack);
+    }
+    this.isSettingUpProcessor = false;
+  }
+
+  getProcessor() {
+    return this.processor;
+  }
+
+  /**
+   * Stops the track processor
+   * See https://github.com/livekit/track-processors-js for example usage
+   *
+   * @experimental
+   * @returns
+   */
+  async stopProcessor() {
+    if (!this.processor) return;
+
+    log.debug('stopping processor');
+    this.processor.processedTrack?.stop();
+    await this.processor.destroy();
+    this.processor = undefined;
+    this.processorElement?.remove();
+    this.processorElement = undefined;
+
+    await this.restart();
+  }
+
   protected abstract monitorSender(): void;
 }

package/src/room/track/LocalVideoTrack.ts

@@ -2,6 +2,7 @@ import type { SignalClient } from '../../api/SignalClient';
 import log from '../../logger';
 import { VideoLayer, VideoQuality } from '../../proto/livekit_models';
 import type { SubscribedCodec, SubscribedQuality } from '../../proto/livekit_rtc';
+import { ScalabilityMode } from '../participant/publishUtils';
 import { computeBitrate, monitorFrequency } from '../stats';
 import type { VideoSenderStats } from '../stats';
 import { Mutex, isFireFox, isMobile, isWeb } from '../utils';
@@ -349,45 +350,90 @@ async function setPublishingLayersForSender(
     }
 
     let hasChanged = false;
-    encodings.forEach((encoding, idx) => {
-      let rid = encoding.rid ?? '';
-      if (rid === '') {
-        rid = 'q';
-      }
-      const quality = videoQualityForRid(rid);
-      const subscribedQuality = qualities.find((q) => q.quality === quality);
-      if (!subscribedQuality) {
-        return;
-      }
-      if (encoding.active !== subscribedQuality.enabled) {
+
+    /* disable closable spatial layer as it has video blur / frozen issue with current server / client
+    1. chrome 113: when switching to up layer with scalability Mode change, it will generate a 
+          low resolution frame and recover very quickly, but noticable
+    2. livekit sfu: additional pli request cause video frozen for a few frames, also noticable */
+    const closableSpatial = false;
+    /* @ts-ignore */
+    if (closableSpatial && encodings[0].scalabilityMode) {
+      // svc dynacast encodings
+      const encoding = encodings[0];
+      /* @ts-ignore */
+      // const mode = new ScalabilityMode(encoding.scalabilityMode);
+      let maxQuality = VideoQuality.OFF;
+      qualities.forEach((q) => {
+        if (q.enabled && (maxQuality === VideoQuality.OFF || q.quality > maxQuality)) {
+          maxQuality = q.quality;
+        }
+      });
+
+      if (maxQuality === VideoQuality.OFF) {
+        if (encoding.active) {
+          encoding.active = false;
+          hasChanged = true;
+        }
+      } else if (!encoding.active /* || mode.spatial !== maxQuality + 1*/) {
         hasChanged = true;
-        encoding.active = subscribedQuality.enabled;
-        log.debug(
-          `setting layer ${subscribedQuality.quality} to ${
-            encoding.active ? 'enabled' : 'disabled'
-          }`,
-        );
-
-        // FireFox does not support setting encoding.active to false, so we
-        // have a workaround of lowering its bitrate and resolution to the min.
-        if (isFireFox()) {
-          if (subscribedQuality.enabled) {
-            encoding.scaleResolutionDownBy = senderEncodings[idx].scaleResolutionDownBy;
-            encoding.maxBitrate = senderEncodings[idx].maxBitrate;
-            /* @ts-ignore */
-            encoding.maxFrameRate = senderEncodings[idx].maxFrameRate;
-          } else {
-            encoding.scaleResolutionDownBy = 4;
-            encoding.maxBitrate = 10;
-            /* @ts-ignore */
-            encoding.maxFrameRate = 2;
-          }
+        encoding.active = true;
+        /*
+        @ts-ignore
+        const originalMode = new ScalabilityMode(senderEncodings[0].scalabilityMode)
+        mode.spatial = maxQuality + 1;
+        mode.suffix = originalMode.suffix;
+        if (mode.spatial === 1) {
+          // no suffix for L1Tx
+          mode.suffix = undefined;
         }
+        @ts-ignore
+        encoding.scalabilityMode = mode.toString();
+        encoding.scaleResolutionDownBy = 2 ** (2 - maxQuality);
+      */
       }
-    });
+    } else {
+      // simulcast dynacast encodings
+      encodings.forEach((encoding, idx) => {
+        let rid = encoding.rid ?? '';
+        if (rid === '') {
+          rid = 'q';
+        }
+        const quality = videoQualityForRid(rid);
+        const subscribedQuality = qualities.find((q) => q.quality === quality);
+        if (!subscribedQuality) {
+          return;
+        }
+        if (encoding.active !== subscribedQuality.enabled) {
+          hasChanged = true;
+          encoding.active = subscribedQuality.enabled;
+          log.debug(
+            `setting layer ${subscribedQuality.quality} to ${
+              encoding.active ? 'enabled' : 'disabled'
+            }`,
+          );
+
+          // FireFox does not support setting encoding.active to false, so we
+          // have a workaround of lowering its bitrate and resolution to the min.
+          if (isFireFox()) {
+            if (subscribedQuality.enabled) {
+              encoding.scaleResolutionDownBy = senderEncodings[idx].scaleResolutionDownBy;
+              encoding.maxBitrate = senderEncodings[idx].maxBitrate;
+              /* @ts-ignore */
+              encoding.maxFrameRate = senderEncodings[idx].maxFrameRate;
+            } else {
+              encoding.scaleResolutionDownBy = 4;
+              encoding.maxBitrate = 10;
+              /* @ts-ignore */
+              encoding.maxFrameRate = 2;
+            }
+          }
+        }
+      });
+    }
 
     if (hasChanged) {
       params.encodings = encodings;
+      log.debug(`setting encodings`, params.encodings);
       await sender.setParameters(params);
     }
   } finally {
@@ -412,6 +458,7 @@ export function videoLayersFromEncodings(
   width: number,
   height: number,
   encodings?: RTCRtpEncodingParameters[],
+  svc?: boolean,
 ): VideoLayer[] {
   // default to a single layer, HQ
   if (!encodings) {
@@ -425,6 +472,24 @@ export function videoLayersFromEncodings(
       },
     ];
   }
+
+  if (svc) {
+    // svc layers
+    /* @ts-ignore */
+    const sm = new ScalabilityMode(encodings[0].scalabilityMode);
+    const layers = [];
+    for (let i = 0; i < sm.spatial; i += 1) {
+      layers.push({
+        quality: VideoQuality.HIGH - i,
+        width: width / 2 ** i,
+        height: height / 2 ** i,
+        bitrate: encodings[0].maxBitrate ? encodings[0].maxBitrate / 3 ** i : 0,
+        ssrc: 0,
+      });
+    }
+    return layers;
+  }
+
   return encodings.map((encoding) => {
     const scale = encoding.scaleResolutionDownBy ?? 1;
     let quality = videoQualityForRid(encoding.rid ?? '');

package/src/room/track/RemoteTrackPublication.ts

@@ -1,5 +1,5 @@
 import log from '../../logger';
-import { TrackInfo, VideoQuality } from '../../proto/livekit_models';
+import { SubscriptionError, TrackInfo, VideoQuality } from '../../proto/livekit_models';
 import { UpdateSubscription, UpdateTrackSettings } from '../../proto/livekit_rtc';
 import { TrackEvent } from '../events';
 import type RemoteTrack from './RemoteTrack';
@@ -24,6 +24,8 @@ export default class RemoteTrackPublication extends TrackPublication {
 
   protected fps?: number;
 
+  protected subscriptionError?: SubscriptionError;
+
   constructor(kind: Track.Kind, ti: TrackInfo, autoSubscribe: boolean | undefined) {
     super(kind, ti.sid, ti.name);
     this.subscribed = autoSubscribe;
@@ -205,6 +207,11 @@ export default class RemoteTrackPublication extends TrackPublication {
     this.emitSubscriptionUpdateIfChanged(prevStatus);
   }
 
+  /** @internal */
+  setSubscriptionError(error: SubscriptionError) {
+    this.emit(TrackEvent.SubscriptionFailed, error);
+  }
+
   /** @internal */
   updateInfo(info: TrackInfo) {
     super.updateInfo(info);

package/src/room/track/RemoteVideoTrack.ts

@@ -1,11 +1,11 @@
 import { debounce } from 'ts-debounce';
 import log from '../../logger';
 import { TrackEvent } from '../events';
-import { computeBitrate } from '../stats';
 import type { VideoReceiverStats } from '../stats';
+import { computeBitrate } from '../stats';
 import CriticalTimers from '../timers';
-import { getDevicePixelRatio, getIntersectionObserver, getResizeObserver, isWeb } from '../utils';
 import type { ObservableMediaElement } from '../utils';
+import { getDevicePixelRatio, getIntersectionObserver, getResizeObserver, isWeb } from '../utils';
 import RemoteTrack from './RemoteTrack';
 import { Track, attachToElement, detachTrack } from './Track';
 import type { AdaptiveStreamSettings } from './types';
@@ -248,11 +248,10 @@ export default class RemoteVideoTrack extends RemoteTrack {
   private updateDimensions() {
     let maxWidth = 0;
     let maxHeight = 0;
+    const pixelDensity = this.getPixelDensity();
     for (const info of this.elementInfos) {
-      const pixelDensity = this.adaptiveStreamSettings?.pixelDensity ?? 1;
-      const pixelDensityValue = pixelDensity === 'screen' ? getDevicePixelRatio() : pixelDensity;
-      const currentElementWidth = info.width() * pixelDensityValue;
-      const currentElementHeight = info.height() * pixelDensityValue;
+      const currentElementWidth = info.width() * pixelDensity;
+      const currentElementHeight = info.height() * pixelDensity;
       if (currentElementWidth + currentElementHeight > maxWidth + maxHeight) {
         maxWidth = currentElementWidth;
         maxHeight = currentElementHeight;
@@ -270,6 +269,24 @@ export default class RemoteVideoTrack extends RemoteTrack {
 
     this.emit(TrackEvent.VideoDimensionsChanged, this.lastDimensions, this);
   }
+
+  private getPixelDensity(): number {
+    const pixelDensity = this.adaptiveStreamSettings?.pixelDensity;
+    if (pixelDensity === 'screen') {
+      return getDevicePixelRatio();
+    } else if (!pixelDensity) {
+      // when unset, we'll pick a sane default here.
+      // for higher pixel density devices (mobile phones, etc), we'll use 2
+      // otherwise it defaults to 1
+      const devicePixelRatio = getDevicePixelRatio();
+      if (devicePixelRatio > 2) {
+        return 2;
+      } else {
+        return 1;
+      }
+    }
+    return pixelDensity;
+  }
 }
 
 export interface ElementInfo {

package/src/room/track/Track.ts

@@ -1,5 +1,4 @@
-import { EventEmitter } from 'events';
-import type TypedEventEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import type { SignalClient } from '../../api/SignalClient';
 import log from '../../logger';
 import { TrackSource, TrackType } from '../../proto/livekit_models';
@@ -13,7 +12,7 @@ const BACKGROUND_REACTION_DELAY = 5000;
 // Safari tracks which audio elements have been "blessed" by the user.
 const recycledElements: Array<HTMLAudioElement> = [];
 
-export abstract class Track extends (EventEmitter as new () => TypedEventEmitter<TrackEventCallbacks>) {
+export abstract class Track extends EventEmitter<TrackEventCallbacks> {
   kind: Track.Kind;
 
   attachedElements: HTMLMediaElement[] = [];
@@ -52,7 +51,6 @@ export abstract class Track extends (EventEmitter as new () => TypedEventEmitter
 
   protected constructor(mediaTrack: MediaStreamTrack, kind: Track.Kind) {
     super();
-    this.setMaxListeners(100);
     this.kind = kind;
     this._mediaStreamTrack = mediaTrack;
     this._mediaStreamID = mediaTrack.id;
@@ -118,7 +116,7 @@ export abstract class Track extends (EventEmitter as new () => TypedEventEmitter
     // even if we believe it's already attached to the element, it's possible
     // the element's srcObject was set to something else out of band.
     // we'll want to re-attach it in that case
-    attachToElement(this._mediaStreamTrack, element);
+    attachToElement(this.mediaStreamTrack, element);
 
     // handle auto playback failures
     const allMediaStreamTracks = (element.srcObject as MediaStream).getTracks();
@@ -167,7 +165,7 @@ export abstract class Track extends (EventEmitter as new () => TypedEventEmitter
     try {
       // detach from a single element
       if (element) {
-        detachTrack(this._mediaStreamTrack, element);
+        detachTrack(this.mediaStreamTrack, element);
         const idx = this.attachedElements.indexOf(element);
         if (idx >= 0) {
           this.attachedElements.splice(idx, 1);
@@ -179,7 +177,7 @@ export abstract class Track extends (EventEmitter as new () => TypedEventEmitter
 
       const detached: HTMLMediaElement[] = [];
       this.attachedElements.forEach((elm) => {
-        detachTrack(this._mediaStreamTrack, elm);
+        detachTrack(this.mediaStreamTrack, elm);
         detached.push(elm);
         this.recycleElement(elm);
         this.emit(TrackEvent.ElementDetached, elm);

package/src/room/track/TrackPublication.ts

@@ -1,7 +1,6 @@
-import { EventEmitter } from 'events';
-import type TypedEventEmitter from 'typed-emitter';
+import EventEmitter from 'eventemitter3';
 import log from '../../logger';
-import type { TrackInfo } from '../../proto/livekit_models';
+import type { SubscriptionError, TrackInfo } from '../../proto/livekit_models';
 import type { UpdateSubscription, UpdateTrackSettings } from '../../proto/livekit_rtc';
 import { TrackEvent } from '../events';
 import LocalAudioTrack from './LocalAudioTrack';
@@ -11,7 +10,7 @@ import type RemoteTrack from './RemoteTrack';
 import RemoteVideoTrack from './RemoteVideoTrack';
 import { Track } from './Track';
 
-export class TrackPublication extends (EventEmitter as new () => TypedEventEmitter<PublicationEventCallbacks>) {
+export class TrackPublication extends EventEmitter<PublicationEventCallbacks> {
   kind: Track.Kind;
 
   trackName: string;
@@ -38,7 +37,6 @@ export class TrackPublication extends (EventEmitter as new () => TypedEventEmitt
 
   constructor(kind: Track.Kind, id: string, name: string) {
     super();
-    this.setMaxListeners(100);
     this.kind = kind;
     this.trackSid = id;
     this.trackName = name;
@@ -146,4 +144,5 @@ export type PublicationEventCallbacks = {
     status: TrackPublication.SubscriptionStatus,
     prevStatus: TrackPublication.SubscriptionStatus,
   ) => void;
+  subscriptionFailed: (error: SubscriptionError) => void;
 };

package/src/room/track/options.ts

@@ -63,10 +63,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>;
 
@@ -284,7 +293,7 @@ export function isCodecEqual(c1: string | undefined, c2: string | undefined): bo
 /**
  * scalability modes for svc, only supprot l3t3 now.
  */
-export type ScalabilityMode = 'L3T3';
+export type ScalabilityMode = 'L3T3' | 'L3T3_KEY';
 
 export namespace AudioPresets {
   export const telephone: AudioPreset = {