livekit-client 0.15.1 → 0.16.0

package/src/room/track/TrackPublication.ts

@@ -0,0 +1,120 @@
+import { EventEmitter } from 'events';
+import { TrackInfo } from '../../proto/livekit_models';
+import { TrackEvent } from '../events';
+import LocalAudioTrack from './LocalAudioTrack';
+import LocalVideoTrack from './LocalVideoTrack';
+import RemoteAudioTrack from './RemoteAudioTrack';
+import RemoteVideoTrack from './RemoteVideoTrack';
+import { Track } from './Track';
+
+export class TrackPublication extends EventEmitter {
+  kind: Track.Kind;
+
+  trackName: string;
+
+  trackSid: Track.SID;
+
+  track?: Track;
+
+  source: Track.Source;
+
+  /** MimeType of the published track */
+  mimeType?: string;
+
+  /** dimension of the original published stream, video-only */
+  dimensions?: Track.Dimensions;
+
+  /** true if track was simulcasted to server, video-only */
+  simulcasted?: boolean;
+
+  /** @internal */
+  trackInfo?: TrackInfo;
+
+  protected metadataMuted: boolean = false;
+
+  constructor(kind: Track.Kind, id: string, name: string) {
+    super();
+    this.kind = kind;
+    this.trackSid = id;
+    this.trackName = name;
+    this.source = Track.Source.Unknown;
+  }
+
+  /** @internal */
+  setTrack(track?: Track) {
+    if (this.track) {
+      this.track.off(TrackEvent.Muted, this.handleMuted);
+      this.track.off(TrackEvent.Unmuted, this.handleUnmuted);
+    }
+
+    this.track = track;
+
+    if (track) {
+      // forward events
+      track.on(TrackEvent.Muted, this.handleMuted);
+      track.on(TrackEvent.Unmuted, this.handleUnmuted);
+    }
+  }
+
+  get isMuted(): boolean {
+    return this.metadataMuted;
+  }
+
+  get isEnabled(): boolean {
+    return true;
+  }
+
+  get isSubscribed(): boolean {
+    return this.track !== undefined;
+  }
+
+  /**
+   * an [AudioTrack] if this publication holds an audio track
+   */
+  get audioTrack(): LocalAudioTrack | RemoteAudioTrack | undefined {
+    if (this.track instanceof LocalAudioTrack || this.track instanceof RemoteAudioTrack) {
+      return this.track;
+    }
+  }
+
+  /**
+   * an [VideoTrack] if this publication holds a video track
+   */
+  get videoTrack(): LocalVideoTrack | RemoteVideoTrack | undefined {
+    if (this.track instanceof LocalVideoTrack || this.track instanceof RemoteVideoTrack) {
+      return this.track;
+    }
+  }
+
+  handleMuted = () => {
+    this.emit(TrackEvent.Muted);
+  };
+
+  handleUnmuted = () => {
+    this.emit(TrackEvent.Unmuted);
+  };
+
+  /** @internal */
+  updateInfo(info: TrackInfo) {
+    this.trackSid = info.sid;
+    this.trackName = info.name;
+    this.source = Track.sourceFromProto(info.source);
+    this.mimeType = info.mimeType;
+    if (this.kind === Track.Kind.Video && info.width > 0) {
+      this.dimensions = {
+        width: info.width,
+        height: info.height,
+      };
+      this.simulcasted = info.simulcast;
+    }
+    this.trackInfo = info;
+  }
+}
+
+export namespace TrackPublication {
+  export enum SubscriptionStatus {
+    Subscribed = 'subscribed',
+    NotAllowed = 'not_allowed',
+    Unsubscribed = 'unsubscribed',
+  }
+}

package/src/room/track/create.ts

@@ -0,0 +1,120 @@
+import { TrackInvalidError } from '../errors';
+import { mediaTrackToLocalTrack } from '../participant/publishUtils';
+import { audioDefaults, videoDefaults } from './defaults';
+import LocalAudioTrack from './LocalAudioTrack';
+import LocalTrack from './LocalTrack';
+import LocalVideoTrack from './LocalVideoTrack';
+import {
+  AudioCaptureOptions, CreateLocalTracksOptions, ScreenShareCaptureOptions,
+  VideoCaptureOptions, VideoPresets,
+} from './options';
+import { Track } from './Track';
+import { constraintsForOptions, mergeDefaultOptions } from './utils';
+
+/**
+ * Creates a local video and audio track at the same time. When acquiring both
+ * audio and video tracks together, it'll display a single permission prompt to
+ * the user instead of two separate ones.
+ * @param options
+ */
+export async function createLocalTracks(
+  options?: CreateLocalTracksOptions,
+): Promise<Array<LocalTrack>> {
+  // set default options to true
+  options ??= {};
+  options.audio ??= true;
+  options.video ??= true;
+
+  const opts = mergeDefaultOptions(options, audioDefaults, videoDefaults);
+  const constraints = constraintsForOptions(opts);
+  const stream = await navigator.mediaDevices.getUserMedia(
+    constraints,
+  );
+  return stream.getTracks().map((mediaStreamTrack) => {
+    const isAudio = mediaStreamTrack.kind === 'audio';
+    let trackOptions = isAudio ? options!.audio : options!.video;
+    if (typeof trackOptions === 'boolean' || !trackOptions) {
+      trackOptions = {};
+    }
+    let trackConstraints: MediaTrackConstraints | undefined;
+    const conOrBool = isAudio ? constraints.audio : constraints.video;
+    if (typeof conOrBool !== 'boolean') {
+      trackConstraints = conOrBool;
+    }
+    const track = mediaTrackToLocalTrack(mediaStreamTrack, trackConstraints);
+    if (track.kind === Track.Kind.Video) {
+      track.source = Track.Source.Camera;
+    } else if (track.kind === Track.Kind.Audio) {
+      track.source = Track.Source.Microphone;
+    }
+    return track;
+  });
+}
+
+/**
+ * Creates a [[LocalVideoTrack]] with getUserMedia()
+ * @param options
+ */
+export async function createLocalVideoTrack(
+  options?: VideoCaptureOptions,
+): Promise<LocalVideoTrack> {
+  const tracks = await createLocalTracks({
+    audio: false,
+    video: options,
+  });
+  return <LocalVideoTrack>tracks[0];
+}
+
+export async function createLocalAudioTrack(
+  options?: AudioCaptureOptions,
+): Promise<LocalAudioTrack> {
+  const tracks = await createLocalTracks({
+    audio: options,
+    video: false,
+  });
+  return <LocalAudioTrack>tracks[0];
+}
+
+/**
+ * Creates a screen capture tracks with getDisplayMedia().
+ * A LocalVideoTrack is always created and returned.
+ * If { audio: true }, and the browser supports audio capture, a LocalAudioTrack is also created.
+ */
+export async function createLocalScreenTracks(
+  options?: ScreenShareCaptureOptions,
+): Promise<Array<LocalTrack>> {
+  if (options === undefined) {
+    options = {};
+  }
+  if (options.resolution === undefined) {
+    options.resolution = VideoPresets.fhd.resolution;
+  }
+
+  let videoConstraints: MediaTrackConstraints | boolean = true;
+  if (options.resolution) {
+    videoConstraints = {
+      width: options.resolution.width,
+      height: options.resolution.height,
+    };
+  }
+  // typescript definition is missing getDisplayMedia: https://github.com/microsoft/TypeScript/issues/33232
+  // @ts-ignore
+  const stream: MediaStream = await navigator.mediaDevices.getDisplayMedia({
+    audio: options.audio ?? false,
+    video: videoConstraints,
+  });
+
+  const tracks = stream.getVideoTracks();
+  if (tracks.length === 0) {
+    throw new TrackInvalidError('no video track found');
+  }
+  const screenVideo = new LocalVideoTrack(tracks[0]);
+  screenVideo.source = Track.Source.ScreenShare;
+  const localTracks: Array<LocalTrack> = [screenVideo];
+  if (stream.getAudioTracks().length > 0) {
+    const screenAudio = new LocalAudioTrack(stream.getAudioTracks()[0]);
+    screenAudio.source = Track.Source.ScreenShareAudio;
+    localTracks.push(screenAudio);
+  }
+  return localTracks;
+}

package/src/room/track/defaults.ts

@@ -0,0 +1,23 @@
+import {
+  AudioCaptureOptions, AudioPresets, ScreenSharePresets,
+  TrackPublishDefaults, VideoCaptureOptions, VideoPresets,
+} from './options';
+
+export const publishDefaults: TrackPublishDefaults = {
+  audioBitrate: AudioPresets.speech.maxBitrate,
+  dtx: true,
+  simulcast: true,
+  screenShareEncoding: ScreenSharePresets.hd_15.encoding,
+  stopMicTrackOnMute: false,
+};
+
+export const audioDefaults: AudioCaptureOptions = {
+  autoGainControl: true,
+  channelCount: 1,
+  echoCancellation: true,
+  noiseSuppression: true,
+};
+
+export const videoDefaults: VideoCaptureOptions = {
+  resolution: VideoPresets.qhd.resolution,
+};

package/src/room/track/options.ts

@@ -0,0 +1,229 @@
+import { Track } from './Track';
+
+export interface TrackPublishDefaults {
+  /**
+   * encoding parameters for camera track
+   */
+  videoEncoding?: VideoEncoding;
+
+  /**
+   * encoding parameters for screen share track
+   */
+  screenShareEncoding?: VideoEncoding;
+
+  /**
+   * codec, defaults to vp8
+   */
+  videoCodec?: VideoCodec;
+
+  /**
+   * max audio bitrate, defaults to [[AudioPresets.speech]]
+   */
+  audioBitrate?: number;
+
+  /**
+   * dtx (Discontinuous Transmission of audio), defaults to true
+   */
+  dtx?: boolean;
+
+  /**
+   * use simulcast, defaults to true.
+   * When using simulcast, LiveKit will publish up to three versions of the stream
+   * at various resolutions.
+   */
+  simulcast?: boolean;
+
+  /**
+   * For local tracks, stop the underlying MediaStreamTrack when the track is muted (or paused)
+   * on some platforms, this option is necessary to disable the microphone recording indicator.
+   * Note: when this is enabled, and BT devices are connected, they will transition between
+   * profiles (e.g. HFP to A2DP) and there will be an audible difference in playback.
+   *
+   * defaults to false
+   */
+  stopMicTrackOnMute?: boolean;
+}
+
+/**
+ * Options when publishing tracks
+ */
+export interface TrackPublishOptions extends TrackPublishDefaults {
+  /**
+   * set a track name
+   */
+  name?: string;
+
+  /**
+   * Source of track, camera, microphone, or screen
+   */
+  source?: Track.Source;
+}
+
+export interface CreateLocalTracksOptions {
+  /**
+   * audio track options, true to create with defaults. false if audio shouldn't be created
+   * default true
+   */
+  audio?: boolean | AudioCaptureOptions;
+
+  /**
+   * video track options, true to create with defaults. false if video shouldn't be created
+   * default true
+   */
+  video?: boolean | VideoCaptureOptions;
+}
+
+export interface VideoCaptureOptions {
+  /**
+   * A ConstrainDOMString object specifying a device ID or an array of device
+   * IDs which are acceptable and/or required.
+   */
+  deviceId?: ConstrainDOMString;
+
+  /**
+   * a facing or an array of facings which are acceptable and/or required.
+   */
+  facingMode?: 'user' | 'environment' | 'left' | 'right';
+
+  resolution?: VideoResolution;
+}
+
+export interface ScreenShareCaptureOptions {
+  /**
+   * true to capture audio shared. browser support for audio capturing in
+   * screenshare is limited: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia#browser_compatibility
+   */
+  audio?: boolean;
+
+  /** capture resolution, defaults to full HD */
+  resolution?: VideoResolution;
+}
+
+export interface AudioCaptureOptions {
+  /**
+   * specifies whether automatic gain control is preferred and/or required
+   */
+  autoGainControl?: ConstrainBoolean;
+
+  /**
+   * the channel count or range of channel counts which are acceptable and/or required
+   */
+  channelCount?: ConstrainULong;
+
+  /**
+   * A ConstrainDOMString object specifying a device ID or an array of device
+   * IDs which are acceptable and/or required.
+   */
+  deviceId?: ConstrainDOMString;
+
+  /**
+   * whether or not echo cancellation is preferred and/or required
+   */
+  echoCancellation?: ConstrainBoolean;
+
+  /**
+   * the latency or range of latencies which are acceptable and/or required.
+   */
+  latency?: ConstrainDouble;
+
+  /**
+   * whether noise suppression is preferred and/or required.
+   */
+  noiseSuppression?: ConstrainBoolean;
+
+  /**
+   * the sample rate or range of sample rates which are acceptable and/or required.
+   */
+  sampleRate?: ConstrainULong;
+
+  /**
+   * sample size or range of sample sizes which are acceptable and/or required.
+   */
+  sampleSize?: ConstrainULong;
+}
+
+export interface VideoResolution {
+  width: number;
+  height: number;
+  frameRate?: number;
+  aspectRatio?: number;
+}
+
+export interface VideoEncoding {
+  maxBitrate: number;
+  maxFramerate?: number;
+}
+
+export class VideoPreset {
+  encoding: VideoEncoding;
+
+  width: number;
+
+  height: number;
+
+  constructor(width: number, height: number, maxBitrate: number, maxFramerate?: number) {
+    this.width = width;
+    this.height = height;
+    this.encoding = {
+      maxBitrate,
+      maxFramerate,
+    };
+  }
+
+  get resolution(): VideoResolution {
+    return {
+      width: this.width,
+      height: this.height,
+      frameRate: this.encoding.maxFramerate,
+      aspectRatio: this.width / this.height,
+    };
+  }
+}
+
+export interface AudioPreset {
+  maxBitrate: number;
+}
+
+export type VideoCodec = 'vp8' | 'h264';
+
+export namespace AudioPresets {
+  export const telephone: AudioPreset = {
+    maxBitrate: 12_000,
+  };
+  export const speech: AudioPreset = {
+    maxBitrate: 20_000,
+  };
+  export const music: AudioPreset = {
+    maxBitrate: 32_000,
+  };
+}
+
+/**
+ * Sane presets for video resolution/encoding
+ */
+export const VideoPresets = {
+  qvga: new VideoPreset(320, 180, 120_000, 10),
+  vga: new VideoPreset(640, 360, 300_000, 20),
+  qhd: new VideoPreset(960, 540, 600_000, 25),
+  hd: new VideoPreset(1280, 720, 2_000_000, 30),
+  fhd: new VideoPreset(1920, 1080, 3_000_000, 30),
+};
+
+/**
+ * Four by three presets
+ */
+export const VideoPresets43 = {
+  qvga: new VideoPreset(240, 180, 90_000, 10),
+  vga: new VideoPreset(480, 360, 225_000, 20),
+  qhd: new VideoPreset(720, 540, 450_000, 25),
+  hd: new VideoPreset(960, 720, 1_500_000, 30),
+  fhd: new VideoPreset(1440, 1080, 2_800_000, 30),
+};
+
+export const ScreenSharePresets = {
+  vga: new VideoPreset(640, 360, 200_000, 3),
+  hd_8: new VideoPreset(1280, 720, 400_000, 5),
+  hd_15: new VideoPreset(1280, 720, 1_000_000, 15),
+  fhd_15: new VideoPreset(1920, 1080, 1_500_000, 15),
+  fhd_30: new VideoPreset(1920, 1080, 3_000_000, 30),
+};

package/src/room/track/types.ts

@@ -0,0 +1,8 @@
+import LocalAudioTrack from './LocalAudioTrack';
+import LocalVideoTrack from './LocalVideoTrack';
+import RemoteAudioTrack from './RemoteAudioTrack';
+import RemoteVideoTrack from './RemoteVideoTrack';
+
+export type RemoteTrack = RemoteAudioTrack | RemoteVideoTrack;
+export type AudioTrack = RemoteAudioTrack | LocalAudioTrack;
+export type VideoTrack = RemoteVideoTrack | LocalVideoTrack;

package/src/room/track/utils.test.ts

@@ -0,0 +1,93 @@
+import {
+  AudioCaptureOptions, VideoCaptureOptions, VideoPresets,
+} from './options';
+import { constraintsForOptions, mergeDefaultOptions } from './utils';
+
+describe('mergeDefaultOptions', () => {
+  const audioDefaults: AudioCaptureOptions = {
+    autoGainControl: true,
+    channelCount: 2,
+  };
+  const videoDefaults: VideoCaptureOptions = {
+    deviceId: 'video123',
+    resolution: VideoPresets.fhd.resolution,
+  };
+
+  it('does not enable undefined options', () => {
+    const opts = mergeDefaultOptions(undefined, audioDefaults, videoDefaults);
+    expect(opts.audio).toEqual(undefined);
+    expect(opts.video).toEqual(undefined);
+  });
+
+  it('does not enable explicitly disabled', () => {
+    const opts = mergeDefaultOptions({
+      video: false,
+    });
+    expect(opts.audio).toEqual(undefined);
+    expect(opts.video).toEqual(false);
+  });
+
+  it('accepts true for options', () => {
+    const opts = mergeDefaultOptions({
+      audio: true,
+    }, audioDefaults, videoDefaults);
+    expect(opts.audio).toEqual(audioDefaults);
+    expect(opts.video).toEqual(undefined);
+  });
+
+  it('enables overriding specific fields', () => {
+    const opts = mergeDefaultOptions({
+      audio: { channelCount: 1 },
+    }, audioDefaults, videoDefaults);
+    const audioOpts = opts.audio as AudioCaptureOptions;
+    expect(audioOpts.channelCount).toEqual(1);
+    expect(audioOpts.autoGainControl).toEqual(true);
+  });
+
+  it('does not override explicit false', () => {
+    const opts = mergeDefaultOptions({
+      audio: { autoGainControl: false },
+    }, audioDefaults, videoDefaults);
+    const audioOpts = opts.audio as AudioCaptureOptions;
+    expect(audioOpts.autoGainControl).toEqual(false);
+  });
+});
+
+describe('constraintsForOptions', () => {
+  it('correctly enables audio bool', () => {
+    const constraints = constraintsForOptions({
+      audio: true,
+    });
+    expect(constraints.audio).toEqual(true);
+    expect(constraints.video).toEqual(false);
+  });
+
+  it('converts audio options correctly', () => {
+    const constraints = constraintsForOptions({
+      audio: {
+        noiseSuppression: true,
+        echoCancellation: false,
+      },
+    });
+    const audioOpts = constraints.audio as MediaTrackConstraints;
+    expect(Object.keys(audioOpts)).toEqual(['noiseSuppression', 'echoCancellation']);
+    expect(audioOpts.noiseSuppression).toEqual(true);
+    expect(audioOpts.echoCancellation).toEqual(false);
+  });
+
+  it('converts video options correctly', () => {
+    const constraints = constraintsForOptions({
+      video: {
+        resolution: VideoPresets.hd.resolution,
+        facingMode: 'user',
+        deviceId: 'video123',
+      },
+    });
+    const videoOpts = constraints.video as MediaTrackConstraints;
+    expect(Object.keys(videoOpts)).toEqual(['width', 'height', 'frameRate', 'aspectRatio', 'facingMode', 'deviceId']);
+    expect(videoOpts.width).toEqual(VideoPresets.hd.resolution.width);
+    expect(videoOpts.height).toEqual(VideoPresets.hd.resolution.height);
+    expect(videoOpts.frameRate).toEqual(VideoPresets.hd.resolution.frameRate);
+    expect(videoOpts.aspectRatio).toEqual(VideoPresets.hd.resolution.aspectRatio);
+  });
+});

package/src/room/track/utils.ts

@@ -0,0 +1,76 @@
+import {
+  AudioCaptureOptions, CreateLocalTracksOptions,
+  VideoCaptureOptions,
+} from './options';
+
+export function mergeDefaultOptions(
+  options?: CreateLocalTracksOptions,
+  audioDefaults?: AudioCaptureOptions,
+  videoDefaults?: VideoCaptureOptions,
+): CreateLocalTracksOptions {
+  const opts: CreateLocalTracksOptions = {
+    ...options,
+  };
+  if (opts.audio === true) opts.audio = {};
+  if (opts.video === true) opts.video = {};
+
+  // use defaults
+  if (opts.audio) {
+    mergeObjectWithoutOverwriting(opts.audio as Record<string, unknown>,
+      audioDefaults as Record<string, unknown>);
+  }
+  if (opts.video) {
+    mergeObjectWithoutOverwriting(opts.video as Record<string, unknown>,
+      videoDefaults as Record<string, unknown>);
+  }
+  return opts;
+}
+
+function mergeObjectWithoutOverwriting(
+  mainObject: Record<string, unknown>,
+  objectToMerge: Record<string, unknown>,
+): Record<string, unknown> {
+  Object.keys(objectToMerge).forEach((key) => {
+    if (mainObject[key] === undefined) mainObject[key] = objectToMerge[key];
+  });
+  return mainObject;
+}
+
+export function constraintsForOptions(options: CreateLocalTracksOptions): MediaStreamConstraints {
+  const constraints: MediaStreamConstraints = {};
+
+  if (options.video) {
+    // default video options
+    if (typeof options.video === 'object') {
+      const videoOptions: MediaTrackConstraints = {};
+      const target = videoOptions as Record<string, unknown>;
+      const source = options.video as Record<string, unknown>;
+      Object.keys(source).forEach((key) => {
+        switch (key) {
+          case 'resolution':
+            // flatten VideoResolution fields
+            mergeObjectWithoutOverwriting(target, source.resolution as Record<string, unknown>);
+            break;
+          default:
+            target[key] = source[key];
+        }
+      });
+      constraints.video = videoOptions;
+    } else {
+      constraints.video = options.video;
+    }
+  } else {
+    constraints.video = false;
+  }
+
+  if (options.audio) {
+    if (typeof options.audio === 'object') {
+      constraints.audio = options.audio;
+    } else {
+      constraints.audio = true;
+    }
+  } else {
+    constraints.audio = false;
+  }
+  return constraints;
+}