livekit-client 1.9.6 → 1.10.0

package/src/room/Room.ts

@@ -18,6 +18,7 @@ import {
   Room as RoomModel,
   ServerInfo,
   SpeakerInfo,
+  SubscriptionError,
   TrackInfo,
   TrackSource,
   TrackType,
@@ -29,6 +30,7 @@ import {
   SimulateScenario,
   StreamStateUpdate,
   SubscriptionPermissionUpdate,
+  SubscriptionResponse,
 } from '../proto/livekit_rtc';
 import DeviceManager from './DeviceManager';
 import RTCEngine from './RTCEngine';
@@ -207,6 +209,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.engine.client.onStreamStateUpdate = this.handleStreamStateUpdate;
     this.engine.client.onSubscriptionPermissionUpdate = this.handleSubscriptionPermissionUpdate;
     this.engine.client.onConnectionQuality = this.handleConnectionQualityUpdate;
+    this.engine.client.onSubscriptionError = this.handleSubscriptionError;
 
     this.engine
       .on(
@@ -1114,6 +1117,21 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     pub.setAllowed(update.allowed);
   };
 
+  private handleSubscriptionError = (update: SubscriptionResponse) => {
+    const participant = Array.from(this.participants.values()).find((p) =>
+      p.tracks.has(update.trackSid),
+    );
+    if (!participant) {
+      return;
+    }
+    const pub = participant.getTrackPublication(update.trackSid);
+    if (!pub) {
+      return;
+    }
+
+    pub.setSubscriptionError(update.err);
+  };
+
   private handleDataPacket = (userPacket: UserPacket, kind: DataPacket_Kind) => {
     // find the participant
     const participant = this.participants.get(userPacket.participantSid);
@@ -1280,6 +1298,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       .on(ParticipantEvent.TrackSubscriptionStatusChanged, (pub, status) => {
         this.emitWhenConnected(RoomEvent.TrackSubscriptionStatusChanged, pub, status, participant);
       })
+      .on(ParticipantEvent.TrackSubscriptionFailed, (trackSid, error) => {
+        this.emit(RoomEvent.TrackSubscriptionFailed, trackSid, participant, error);
+      })
       .on(ParticipantEvent.TrackSubscriptionPermissionChanged, (pub, status) => {
         this.emitWhenConnected(
           RoomEvent.TrackSubscriptionPermissionChanged,
@@ -1609,7 +1630,11 @@ export type RoomEventCallbacks = {
     publication: RemoteTrackPublication,
     participant: RemoteParticipant,
   ) => void;
-  trackSubscriptionFailed: (trackSid: string, participant: RemoteParticipant) => void;
+  trackSubscriptionFailed: (
+    trackSid: string,
+    participant: RemoteParticipant,
+    reason?: SubscriptionError,
+  ) => void;
   trackUnpublished: (publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
   trackUnsubscribed: (
     track: RemoteTrack,

package/src/room/events.ts

@@ -508,4 +508,8 @@ export enum TrackEvent {
    * Fires on RemoteTrackPublication
    */
   SubscriptionStatusChanged = 'subscriptionStatusChanged',
+  /**
+   * Fires on RemoteTrackPublication
+   */
+  SubscriptionFailed = 'subscriptionFailed',
 }

package/src/room/participant/LocalParticipant.ts

@@ -625,8 +625,8 @@ export default class LocalParticipant extends Participant {
       // for svc codecs, disable simulcast and use vp8 for backup codec
       if (track instanceof LocalVideoTrack) {
         if (isSVCCodec(opts.videoCodec)) {
-          // set scalabilityMode to 'L3T3' by default
-          opts.scalabilityMode = opts.scalabilityMode ?? 'L3T3';
+          // set scalabilityMode to 'L3T3_KEY' by default
+          opts.scalabilityMode = opts.scalabilityMode ?? 'L3T3_KEY';
         }
 
         // set up backup
@@ -647,6 +647,16 @@ export default class LocalParticipant extends Participant {
               enableSimulcastLayers: true,
             },
           ];
+        } else if (opts.videoCodec) {
+          // pass codec info to sfu so it can prefer codec for the client which don't support
+          // setCodecPreferences
+          req.simulcastCodecs = [
+            {
+              codec: opts.videoCodec,
+              cid: track.mediaStreamTrack.id,
+              enableSimulcastLayers: opts.simulcast ?? false,
+            },
+          ];
         }
       }
 
@@ -656,7 +666,7 @@ export default class LocalParticipant extends Participant {
         dims.height,
         opts,
       );
-      req.layers = videoLayersFromEncodings(req.width, req.height, simEncodings ?? encodings);
+      req.layers = videoLayersFromEncodings(req.width, req.height, encodings);
     } else if (track.kind === Track.Kind.Audio) {
       encodings = [
         {
@@ -850,6 +860,16 @@ export default class LocalParticipant extends Participant {
       trackSender
     ) {
       try {
+        for (const transceiver of this.engine.publisher.pc.getTransceivers()) {
+          // if sender is not currently sending (after replaceTrack(null))
+          // removeTrack would have no effect.
+          // to ensure we end up successfully removing the track, manually set
+          // the transceiver to inactive
+          if (transceiver.sender === trackSender) {
+            transceiver.direction = 'inactive';
+            negotiationNeeded = true;
+          }
+        }
         if (this.engine.removeTrack(trackSender)) {
           negotiationNeeded = true;
         }

package/src/room/participant/Participant.ts

@@ -6,6 +6,7 @@ import {
   ParticipantInfo,
   ParticipantPermission,
   ConnectionQuality as ProtoQuality,
+  SubscriptionError,
 } from '../../proto/livekit_models';
 import { ParticipantEvent, TrackEvent } from '../events';
 import type LocalTrackPublication from '../track/LocalTrackPublication';
@@ -265,7 +266,7 @@ export default class Participant extends (EventEmitter as new () => TypedEmitter
 export type ParticipantEventCallbacks = {
   trackPublished: (publication: RemoteTrackPublication) => void;
   trackSubscribed: (track: RemoteTrack, publication: RemoteTrackPublication) => void;
-  trackSubscriptionFailed: (trackSid: string) => void;
+  trackSubscriptionFailed: (trackSid: string, reason?: SubscriptionError) => void;
   trackUnpublished: (publication: RemoteTrackPublication) => void;
   trackUnsubscribed: (track: RemoteTrack, publication: RemoteTrackPublication) => void;
   trackMuted: (publication: TrackPublication) => void;

package/src/room/participant/RemoteParticipant.ts

@@ -1,6 +1,6 @@
 import type { SignalClient } from '../../api/SignalClient';
 import log from '../../logger';
-import type { ParticipantInfo } from '../../proto/livekit_models';
+import type { ParticipantInfo, SubscriptionError } from '../../proto/livekit_models';
 import type { UpdateSubscription, UpdateTrackSettings } from '../../proto/livekit_rtc';
 import { ParticipantEvent, TrackEvent } from '../events';
 import RemoteAudioTrack from '../track/RemoteAudioTrack';
@@ -81,6 +81,9 @@ export default class RemoteParticipant extends Participant {
     publication.on(TrackEvent.Unsubscribed, (previousTrack: RemoteTrack) => {
       this.emit(ParticipantEvent.TrackUnsubscribed, previousTrack, publication);
     });
+    publication.on(TrackEvent.SubscriptionFailed, (error: SubscriptionError) => {
+      this.emit(ParticipantEvent.TrackSubscriptionFailed, publication.trackSid, error);
+    });
   }
 
   getTrack(source: Track.Source): RemoteTrackPublication | undefined {

package/src/room/participant/publishUtils.ts

@@ -10,7 +10,7 @@ import type {
   VideoCodec,
   VideoEncoding,
 } from '../track/options';
-import { isSVCCodec } from '../utils';
+import { getReactNativeOs, isReactNative, isSVCCodec } from '../utils';
 
 /** @internal */
 export function mediaTrackToLocalTrack(
@@ -128,17 +128,15 @@ export function computeVideoEncodings(
     // svc use first encoding as the original, so we sort encoding from high to low
     switch (scalabilityMode) {
       case 'L3T3':
-        for (let i = 0; i < 3; i += 1) {
-          encodings.push({
-            rid: videoRids[2 - i],
-            scaleResolutionDownBy: 2 ** i,
-            maxBitrate: videoEncoding.maxBitrate / 3 ** i,
-            /* @ts-ignore */
-            maxFramerate: original.encoding.maxFramerate,
-            /* @ts-ignore */
-            scalabilityMode: '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;
 
@@ -321,6 +319,33 @@ function encodingsFromPresets(
     }
     encodings.push(encoding);
   });
+
+  // RN ios simulcast requires all same framerates.
+  if (isReactNative() && getReactNativeOs() === 'ios') {
+    let topFramerate: number | undefined = undefined;
+    encodings.forEach((encoding) => {
+      if (!topFramerate) {
+        topFramerate = encoding.maxFramerate;
+      } else if (encoding.maxFramerate && encoding.maxFramerate > topFramerate) {
+        topFramerate = encoding.maxFramerate;
+      }
+    });
+
+    let notifyOnce = true;
+    encodings.forEach((encoding) => {
+      if (encoding.maxFramerate != topFramerate) {
+        if (notifyOnce) {
+          notifyOnce = false;
+          log.info(
+            `Simulcast on iOS React-Native requires all encodings to share the same framerate.`,
+          );
+        }
+        log.info(`Setting framerate of encoding \"${encoding.rid ?? ''}\" to ${topFramerate}`);
+        encoding.maxFramerate = topFramerate;
+      }
+    });
+  }
+
   return encodings;
 }
 
@@ -341,3 +366,34 @@ export function sortPresets(presets: Array<VideoPreset> | undefined) {
     return 0;
   });
 }
+
+/** @internal */
+export class ScalabilityMode {
+  spatial: number;
+
+  temporal: number;
+
+  suffix: undefined | 'h' | '_KEY' | '_KEY_SHIFT';
+
+  constructor(scalabilityMode: string) {
+    const results = scalabilityMode.match(/^L(\d)T(\d)(h|_KEY|_KEY_SHIFT){0,1}$/);
+    if (!results) {
+      throw new Error('invalid scalability mode');
+    }
+
+    this.spatial = parseInt(results[1]);
+    this.temporal = parseInt(results[2]);
+    if (results.length > 3) {
+      switch (results[3]) {
+        case 'h':
+        case '_KEY':
+        case '_KEY_SHIFT':
+          this.suffix = results[3];
+      }
+    }
+  }
+
+  toString(): string {
+    return `L${this.spatial}T${this.temporal}${this.suffix ?? ''}`;
+  }
+}

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
@@ -82,6 +84,10 @@ export default abstract class LocalTrack extends Track {
     return this.providedByUser;
   }
 
+  get mediaStreamTrack() {
+    return this.processor?.processedTrack ?? this._mediaStreamTrack;
+  }
+
   async waitForDimensions(timeout = defaultDimensionsTimeout): Promise<Track.Dimensions> {
     if (this.kind === Track.Kind.Audio) {
       throw new Error('cannot get dimensions for audio tracks');
@@ -158,6 +164,9 @@ export default abstract class LocalTrack extends Track {
 
     this.mediaStream = new MediaStream([track]);
     this.providedByUser = userProvidedTrack;
+    if (this.processor) {
+      await this.stopProcessor();
+    }
     return this;
   }
 
@@ -180,7 +189,7 @@ export default abstract class LocalTrack extends Track {
 
     // detach
     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
@@ -203,12 +212,16 @@ export default abstract class LocalTrack extends Track {
 
     await this.resumeUpstream();
 
-    this.attachedElements.forEach((el) => {
-      attachToElement(newTrack, el);
-    });
-
     this.mediaStream = mediaStream;
     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 +266,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 +291,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();
     }
@@ -293,5 +321,81 @@ export default abstract class LocalTrack extends Track {
     }
   }
 
+  /**
+   * 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,88 @@ 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) {
+
+    /* @ts-ignore */
+    if (encodings.length === 1 && 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;
+        /* 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
+        @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 {
@@ -425,6 +469,25 @@ export function videoLayersFromEncodings(
       },
     ];
   }
+
+  /* @ts-ignore */
+  if (encodings.length === 1 && encodings[0].scalabilityMode) {
+    // 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/Track.ts

@@ -118,7 +118,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 +167,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 +179,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);