livekit-client 0.18.4-RC7 → 0.18.5

package/src/room/errors.ts

@@ -0,0 +1,65 @@
+export class LivekitError extends Error {
+  code: number;
+
+  constructor(code: number, message?: string) {
+    super(message || 'an error has occured');
+    this.code = code;
+  }
+}
+
+export class ConnectionError extends LivekitError {
+  constructor(message?: string) {
+    super(1, message);
+  }
+}
+
+export class TrackInvalidError extends LivekitError {
+  constructor(message?: string) {
+    super(20, message || 'Track is invalid');
+  }
+}
+
+export class UnsupportedServer extends LivekitError {
+  constructor(message?: string) {
+    super(10, message || 'Unsupported server');
+  }
+}
+
+export class UnexpectedConnectionState extends LivekitError {
+  constructor(message?: string) {
+    super(12, message || 'Unexpected connection state');
+  }
+}
+
+export class PublishDataError extends LivekitError {
+  constructor(message?: string) {
+    super(13, message || 'Unable to publish data');
+  }
+}
+
+export enum MediaDeviceFailure {
+  // user rejected permissions
+  PermissionDenied = 'PermissionDenied',
+  // device is not available
+  NotFound = 'NotFound',
+  // device is in use. On Windows, only a single tab may get access to a device at a time.
+  DeviceInUse = 'DeviceInUse',
+  Other = 'Other',
+}
+
+export namespace MediaDeviceFailure {
+  export function getFailure(error: any): MediaDeviceFailure | undefined {
+    if (error && 'name' in error) {
+      if (error.name === 'NotFoundError' || error.name === 'DevicesNotFoundError') {
+        return MediaDeviceFailure.NotFound;
+      }
+      if (error.name === 'NotAllowedError' || error.name === 'PermissionDeniedError') {
+        return MediaDeviceFailure.PermissionDenied;
+      }
+      if (error.name === 'NotReadableError' || error.name === 'TrackStartError') {
+        return MediaDeviceFailure.DeviceInUse;
+      }
+      return MediaDeviceFailure.Other;
+    }
+  }
+}

package/src/room/events.ts

@@ -0,0 +1,438 @@
+/**
+ * Events are the primary way LiveKit notifies your application of changes.
+ *
+ * The following are events emitted by [[Room]], listen to room events like
+ *
+ * ```typescript
+ * room.on(RoomEvent.TrackPublished, (track, publication, participant) => {})
+ * ```
+ */
+
+export enum RoomEvent {
+  /**
+   * When the connection to the server has been interrupted and it's attempting
+   * to reconnect.
+   */
+  Reconnecting = 'reconnecting',
+
+  /**
+   * Fires when a reconnection has been successful.
+   */
+  Reconnected = 'reconnected',
+
+  /**
+   * When disconnected from room. This fires when room.disconnect() is called or
+   * when an unrecoverable connection issue had occured
+   */
+  Disconnected = 'disconnected',
+
+  /**
+   * Whenever the connection state of the room changes
+   *
+   * args: ([[RoomState]])
+   */
+  StateChanged = 'stateChanged',
+
+  /**
+   * When input or output devices on the machine have changed.
+   */
+  MediaDevicesChanged = 'mediaDevicesChanged',
+
+  /**
+   * When a [[RemoteParticipant]] joins *after* the local
+   * participant. It will not emit events for participants that are already
+   * in the room
+   *
+   * args: ([[RemoteParticipant]])
+   */
+  ParticipantConnected = 'participantConnected',
+
+  /**
+   * When a [[RemoteParticipant]] leaves *after* the local
+   * participant has joined.
+   *
+   * args: ([[RemoteParticipant]])
+   */
+  ParticipantDisconnected = 'participantDisconnected',
+
+  /**
+   * When a new track is published to room *after* the local
+   * participant has joined. It will not fire for tracks that are already published.
+   *
+   * A track published doesn't mean the participant has subscribed to it. It's
+   * simply reflecting the state of the room.
+   *
+   * args: ([[RemoteTrackPublication]], [[RemoteParticipant]])
+   */
+  TrackPublished = 'trackPublished',
+
+  /**
+   * The [[LocalParticipant]] has subscribed to a new track. This event will **always**
+   * fire as long as new tracks are ready for use.
+   *
+   * args: ([[RemoteTrack]], [[RemoteTrackPublication]], [[RemoteParticipant]])
+   */
+  TrackSubscribed = 'trackSubscribed',
+
+  /**
+   * Could not subscribe to a track
+   *
+   * args: (track sid, [[RemoteParticipant]])
+   */
+  TrackSubscriptionFailed = 'trackSubscriptionFailed',
+
+  /**
+   * A [[RemoteParticipant]] has unpublished a track
+   *
+   * args: ([[RemoteTrackPublication]], [[RemoteParticipant]])
+   */
+  TrackUnpublished = 'trackUnpublished',
+
+  /**
+   * A subscribed track is no longer available. Clients should listen to this
+   * event and ensure they detach tracks.
+   *
+   * args: ([[Track]], [[RemoteTrackPublication]], [[RemoteParticipant]])
+   */
+  TrackUnsubscribed = 'trackUnsubscribed',
+
+  /**
+   * A track that was muted, fires on both [[RemoteParticipant]]s and [[LocalParticipant]]
+   *
+   * args: ([[TrackPublication]], [[Participant]])
+   */
+  TrackMuted = 'trackMuted',
+
+  /**
+   * A track that was unmuted, fires on both [[RemoteParticipant]]s and [[LocalParticipant]]
+   *
+   * args: ([[TrackPublication]], [[Participant]])
+   */
+  TrackUnmuted = 'trackUnmuted',
+
+  /**
+   * A local track was published successfully. This event is helpful to know
+   * when to update your local UI with the newly published track.
+   *
+   * args: ([[LocalTrackPublication]], [[LocalParticipant]])
+   */
+  LocalTrackPublished = 'localTrackPublished',
+
+  /**
+   * A local track was unpublished. This event is helpful to know when to remove
+   * the local track from your UI.
+   *
+   * When a user stops sharing their screen by pressing "End" on the browser UI,
+   * this event will also fire.
+   *
+   * args: ([[LocalTrackPublication]], [[LocalParticipant]])
+   */
+  LocalTrackUnpublished = 'localTrackUnpublished',
+
+  /**
+   * Active speakers changed. List of speakers are ordered by their audio level.
+   * loudest speakers first. This will include the LocalParticipant too.
+   *
+   * Speaker updates are sent only to the publishing participant and their subscribers.
+   *
+   * args: (Array<[[Participant]]>)
+   */
+  ActiveSpeakersChanged = 'activeSpeakersChanged',
+
+  /**
+   * @deprecated Use ParticipantMetadataChanged instead
+   * @internal
+   */
+  MetadataChanged = 'metadataChanged',
+
+  /**
+   * Participant metadata is a simple way for app-specific state to be pushed to
+   * all users.
+   * When RoomService.UpdateParticipantMetadata is called to change a participant's
+   * state, *all*  participants in the room will fire this event.
+   *
+   * args: (prevMetadata: string, [[Participant]])
+   *
+   */
+  ParticipantMetadataChanged = 'participantMetadataChanged',
+
+  /**
+   * Room metadata is a simple way for app-specific state to be pushed to
+   * all users.
+   * When RoomService.UpdateRoomMetadata is called to change a room's state,
+   * *all*  participants in the room will fire this event.
+   *
+   * args: (string)
+   */
+  RoomMetadataChanged = 'roomMetadataChanged',
+
+  /**
+   * Data received from another participant.
+   * Data packets provides the ability to use LiveKit to send/receive arbitrary payloads.
+   * All participants in the room will receive the messages sent to the room.
+   *
+   * args: (payload: Uint8Array, participant: [[Participant]], kind: [[DataPacket_Kind]])
+   */
+  DataReceived = 'dataReceived',
+
+  /**
+   * Connection quality was changed for a Participant. It'll receive updates
+   * from the local participant, as well as any [[RemoteParticipant]]s that we are
+   * subscribed to.
+   *
+   * args: (connectionQuality: [[ConnectionQuality]], participant: [[Participant]])
+   */
+  ConnectionQualityChanged = 'connectionQualityChanged',
+
+  /**
+   * StreamState indicates if a subscribed (remote) track has been paused by the SFU
+   * (typically this happens because of subscriber's bandwidth constraints)
+   *
+   * When bandwidth conditions allow, the track will be resumed automatically.
+   * TrackStreamStateChanged will also be emitted when that happens.
+   *
+   * args: (pub: [[RemoteTrackPublication]], streamState: [[Track.StreamState]],
+   *        participant: [[RemoteParticipant]])
+   */
+  TrackStreamStateChanged = 'trackStreamStateChanged',
+
+  /**
+   * One of subscribed tracks have changed its permissions for the current
+   * participant. If permission was revoked, then the track will no longer
+   * be subscribed. If permission was granted, a TrackSubscribed event will
+   * be emitted.
+   *
+   * args: (pub: [[RemoteTrackPublication]],
+   *        status: [[TrackPublication.SubscriptionStatus]],
+   *        participant: [[RemoteParticipant]])
+   */
+  TrackSubscriptionPermissionChanged = 'trackSubscriptionPermissionChanged',
+
+  /**
+   * LiveKit will attempt to autoplay all audio tracks when you attach them to
+   * audio elements. However, if that fails, we'll notify you via AudioPlaybackStatusChanged.
+   * `Room.canPlayAudio` will indicate if audio playback is permitted.
+   */
+  AudioPlaybackStatusChanged = 'audioPlaybackChanged',
+
+  /**
+   * When we have encountered an error while attempting to create a track.
+   * The errors take place in getUserMedia().
+   * Use MediaDeviceFailure.getFailure(error) to get the reason of failure.
+   * [[getAudioCreateError]] and [[getVideoCreateError]] will indicate if it had
+   * an error while creating the audio or video track respectively.
+   *
+   * args: (error: Error)
+   */
+  MediaDevicesError = 'mediaDevicesError',
+
+  /**
+   * A participant's permission has changed. Currently only fired on LocalParticipant.
+   * args: (prevPermissions: [[ParticipantPermission]], participant: [[Participant]])
+   */
+  ParticipantPermissionsChanged = 'participantPermissionsChanged',
+}
+
+export enum ParticipantEvent {
+  /**
+   * When a new track is published to room *after* the local
+   * participant has joined. It will not fire for tracks that are already published.
+   *
+   * A track published doesn't mean the participant has subscribed to it. It's
+   * simply reflecting the state of the room.
+   *
+   * args: ([[RemoteTrackPublication]])
+   */
+  TrackPublished = 'trackPublished',
+
+  /**
+   * Successfully subscribed to the [[RemoteParticipant]]'s track.
+   * This event will **always** fire as long as new tracks are ready for use.
+   *
+   * args: ([[RemoteTrack]], [[RemoteTrackPublication]])
+   */
+  TrackSubscribed = 'trackSubscribed',
+
+  /**
+   * Could not subscribe to a track
+   *
+   * args: (track sid)
+   */
+  TrackSubscriptionFailed = 'trackSubscriptionFailed',
+
+  /**
+   * A [[RemoteParticipant]] has unpublished a track
+   *
+   * args: ([[RemoteTrackPublication]])
+   */
+  TrackUnpublished = 'trackUnpublished',
+
+  /**
+   * A subscribed track is no longer available. Clients should listen to this
+   * event and ensure they detach tracks.
+   *
+   * args: ([[RemoteTrack]], [[RemoteTrackPublication]])
+   */
+  TrackUnsubscribed = 'trackUnsubscribed',
+
+  /**
+   * A track that was muted, fires on both [[RemoteParticipant]]s and [[LocalParticipant]]
+   *
+   * args: ([[TrackPublication]])
+   */
+  TrackMuted = 'trackMuted',
+
+  /**
+   * A track that was unmuted, fires on both [[RemoteParticipant]]s and [[LocalParticipant]]
+   *
+   * args: ([[TrackPublication]])
+   */
+  TrackUnmuted = 'trackUnmuted',
+
+  /**
+   * A local track was published successfully. This event is helpful to know
+   * when to update your local UI with the newly published track.
+   *
+   * args: ([[LocalTrackPublication]])
+   */
+  LocalTrackPublished = 'localTrackPublished',
+
+  /**
+   * A local track was unpublished. This event is helpful to know when to remove
+   * the local track from your UI.
+   *
+   * When a user stops sharing their screen by pressing "End" on the browser UI,
+   * this event will also fire.
+   *
+   * args: ([[LocalTrackPublication]])
+   */
+  LocalTrackUnpublished = 'localTrackUnpublished',
+
+  /**
+   * @deprecated Use ParticipantMetadataChanged instead
+   * @internal
+   */
+  MetadataChanged = 'metadataChanged',
+
+  /**
+   * Participant metadata is a simple way for app-specific state to be pushed to
+   * all users.
+   * When RoomService.UpdateParticipantMetadata is called to change a participant's
+   * state, *all*  participants in the room will fire this event.
+   * To access the current metadata, see [[Participant.metadata]].
+   *
+   * args: (prevMetadata: string)
+   *
+   */
+  ParticipantMetadataChanged = 'participantMetadataChanged',
+
+  /**
+   * Data received from this participant as sender.
+   * Data packets provides the ability to use LiveKit to send/receive arbitrary payloads.
+   * All participants in the room will receive the messages sent to the room.
+   *
+   * args: (payload: Uint8Array, kind: [[DataPacket_Kind]])
+   */
+  DataReceived = 'dataReceived',
+
+  /**
+   * Has speaking status changed for the current participant
+   *
+   * args: (speaking: boolean)
+   */
+  IsSpeakingChanged = 'isSpeakingChanged',
+
+  /**
+   * Connection quality was changed for a Participant. It'll receive updates
+   * from the local participant, as well as any [[RemoteParticipant]]s that we are
+   * subscribed to.
+   *
+   * args: (connectionQuality: [[ConnectionQuality]])
+   */
+  ConnectionQualityChanged = 'connectionQualityChanged',
+
+  /**
+   * StreamState indicates if a subscribed track has been paused by the SFU
+   * (typically this happens because of subscriber's bandwidth constraints)
+   *
+   * When bandwidth conditions allow, the track will be resumed automatically.
+   * TrackStreamStateChanged will also be emitted when that happens.
+   *
+   * args: (pub: [[RemoteTrackPublication]], streamState: [[Track.StreamState]])
+   */
+  TrackStreamStateChanged = 'trackStreamStateChanged',
+
+  /**
+   * One of subscribed tracks have changed its permissions for the current
+   * participant. If permission was revoked, then the track will no longer
+   * be subscribed. If permission was granted, a TrackSubscribed event will
+   * be emitted.
+   *
+   * args: (pub: [[RemoteTrackPublication]],
+   *        status: [[TrackPublication.SubscriptionStatus]])
+   */
+  TrackSubscriptionPermissionChanged = 'trackSubscriptionPermissionChanged',
+
+  // fired only on LocalParticipant
+  /** @internal */
+  MediaDevicesError = 'mediaDevicesError',
+
+  /**
+   * A participant's permission has changed. Currently only fired on LocalParticipant.
+   * args: (prevPermissions: [[ParticipantPermission]])
+   */
+  ParticipantPermissionsChanged = 'participantPermissionsChanged',
+}
+
+/** @internal */
+export enum EngineEvent {
+  TransportsCreated = 'transportsCreated',
+  Connected = 'connected',
+  Disconnected = 'disconnected',
+  Resuming = 'resuming',
+  Resumed = 'resumed',
+  Restarting = 'restarting',
+  Restarted = 'restarted',
+  SignalResumed = 'signalResumed',
+  MediaTrackAdded = 'mediaTrackAdded',
+  ActiveSpeakersUpdate = 'activeSpeakersUpdate',
+  DataPacketReceived = 'dataPacketReceived',
+}
+
+export enum TrackEvent {
+  Message = 'message',
+  Muted = 'muted',
+  Unmuted = 'unmuted',
+  Ended = 'ended',
+  /** @internal */
+  UpdateSettings = 'updateSettings',
+  /** @internal */
+  UpdateSubscription = 'updateSubscription',
+  /** @internal */
+  AudioPlaybackStarted = 'audioPlaybackStarted',
+  /** @internal */
+  AudioPlaybackFailed = 'audioPlaybackFailed',
+  /**
+   * @internal
+   * Only fires on LocalAudioTrack instances
+   */
+  AudioSilenceDetected = 'audioSilenceDetected',
+  /** @internal */
+  VisibilityChanged = 'visibilityChanged',
+  /** @internal */
+  VideoDimensionsChanged = 'videoDimensionsChanged',
+  /** @internal */
+  ElementAttached = 'elementAttached',
+  /** @internal */
+  ElementDetached = 'elementDetached',
+  /**
+   * @internal
+   * Only fires on LocalTracks
+   */
+  UpstreamPaused = 'upstreamPaused',
+  /**
+   * @internal
+   * Only fires on LocalTracks
+   */
+  UpstreamResumed = 'upstreamResumed',
+}