livekit-client 0.18.4-RC8 → 0.18.6

package/src/room/track/options.ts

@@ -0,0 +1,292 @@
+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;
+
+  /**
+   * scalability mode for svc codecs, defaults to 'L3T3'.
+   * for svc codecs, simulcast is disabled.
+   */
+  scalabilityMode?: ScalabilityMode;
+
+  /**
+   * custom video simulcast layers for camera tracks, defaults to h180, h360, h540
+   * 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
+   */
+  videoSimulcastLayers?: Array<VideoPreset>;
+
+  /**
+   * custom video simulcast layers for screen tracks
+   * Note: the layers need to be ordered from lowest to highest quality
+   */
+  screenShareSimulcastLayers?: Array<VideoPreset>;
+
+  /**
+   * 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' | 'av1' | 'vp9';
+
+/**
+ * scalability modes for svc, only supprot l3t3 now.
+ */
+export type ScalabilityMode = 'L3T3';
+
+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 = {
+  h90: new VideoPreset(160, 90, 60_000, 15),
+  h180: new VideoPreset(320, 180, 120_000, 15),
+  h216: new VideoPreset(384, 216, 180_000, 15),
+  h360: new VideoPreset(640, 360, 300_000, 20),
+  h540: new VideoPreset(960, 540, 600_000, 25),
+  h720: new VideoPreset(1280, 720, 1_700_000, 30),
+  h1080: new VideoPreset(1920, 1080, 3_000_000, 30),
+  h1440: new VideoPreset(2560, 1440, 5_000_000, 30),
+  h2160: new VideoPreset(3840, 2160, 8_000_000, 30),
+  /** @deprecated */
+  qvga: new VideoPreset(320, 180, 120_000, 10),
+  /** @deprecated */
+  vga: new VideoPreset(640, 360, 300_000, 20),
+  /** @deprecated */
+  qhd: new VideoPreset(960, 540, 600_000, 25),
+  /** @deprecated */
+  hd: new VideoPreset(1280, 720, 1_700_000, 30),
+  /** @deprecated */
+  fhd: new VideoPreset(1920, 1080, 3_000_000, 30),
+} as const;
+
+/**
+ * Four by three presets
+ */
+export const VideoPresets43 = {
+  h120: new VideoPreset(160, 120, 80_000, 15),
+  h180: new VideoPreset(240, 180, 100_000, 15),
+  h240: new VideoPreset(320, 240, 150_000, 15),
+  h360: new VideoPreset(480, 360, 225_000, 20),
+  h480: new VideoPreset(640, 480, 300_000, 20),
+  h540: new VideoPreset(720, 540, 450_000, 25),
+  h720: new VideoPreset(960, 720, 1_500_000, 30),
+  h1080: new VideoPreset(1440, 1080, 2_500_000, 30),
+  h1440: new VideoPreset(1920, 1440, 3_500_000, 30),
+  /** @deprecated */
+  qvga: new VideoPreset(240, 180, 90_000, 10),
+  /** @deprecated */
+  vga: new VideoPreset(480, 360, 225_000, 20),
+  /** @deprecated */
+  qhd: new VideoPreset(720, 540, 450_000, 25),
+  /** @deprecated */
+  hd: new VideoPreset(960, 720, 1_500_000, 30),
+  /** @deprecated */
+  fhd: new VideoPreset(1440, 1080, 2_800_000, 30),
+} as const;
+
+export const ScreenSharePresets = {
+  h360fps3: new VideoPreset(640, 360, 200_000, 3),
+  h720fps5: new VideoPreset(1280, 720, 400_000, 5),
+  h720fps15: new VideoPreset(1280, 720, 1_000_000, 15),
+  h1080fps15: new VideoPreset(1920, 1080, 1_500_000, 15),
+  h1080fps30: new VideoPreset(1920, 1080, 3_000_000, 30),
+  /** @deprecated */
+  vga: new VideoPreset(640, 360, 200_000, 3),
+  /** @deprecated */
+  hd_8: new VideoPreset(1280, 720, 400_000, 5),
+  /** @deprecated */
+  hd_15: new VideoPreset(1280, 720, 1_000_000, 15),
+  /** @deprecated */
+  fhd_15: new VideoPreset(1920, 1080, 1_500_000, 15),
+  /** @deprecated */
+  fhd_30: new VideoPreset(1920, 1080, 3_000_000, 30),
+} as const;

package/src/room/track/types.ts

@@ -0,0 +1,20 @@
+import type LocalAudioTrack from './LocalAudioTrack';
+import type LocalVideoTrack from './LocalVideoTrack';
+import type RemoteAudioTrack from './RemoteAudioTrack';
+import type RemoteVideoTrack from './RemoteVideoTrack';
+
+export type RemoteTrack = RemoteAudioTrack | RemoteVideoTrack;
+export type AudioTrack = RemoteAudioTrack | LocalAudioTrack;
+export type VideoTrack = RemoteVideoTrack | LocalVideoTrack;
+
+export type AdaptiveStreamSettings = {
+  /**
+   * Set a custom pixel density, defaults to 1
+   * 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
+   * Note: this might significantly increase the bandwidth consumed by people
+   * streaming on high definition screens.
+   */
+  pixelDensity?: number | 'screen';
+};

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

@@ -0,0 +1,110 @@
+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,113 @@
+import { sleep } from '../utils';
+import { AudioCaptureOptions, CreateLocalTracksOptions, VideoCaptureOptions } from './options';
+import { AudioTrack } from './types';
+
+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;
+}
+/**
+ * This function detects silence on a given [[Track]] instance.
+ * Returns true if the track seems to be entirely silent.
+ */
+export async function detectSilence(track: AudioTrack, timeOffset = 200): Promise<boolean> {
+  const ctx = getNewAudioContext();
+  if (ctx) {
+    const analyser = ctx.createAnalyser();
+    analyser.fftSize = 2048;
+
+    const bufferLength = analyser.frequencyBinCount;
+    const dataArray = new Uint8Array(bufferLength);
+    const source = ctx.createMediaStreamSource(new MediaStream([track.mediaStreamTrack]));
+
+    source.connect(analyser);
+    await sleep(timeOffset);
+    analyser.getByteTimeDomainData(dataArray);
+    const someNoise = dataArray.some((sample) => sample !== 128 && sample !== 0);
+    ctx.close();
+    return !someNoise;
+  }
+  return false;
+}
+
+/**
+ * @internal
+ */
+export function getNewAudioContext(): AudioContext | void {
+  // @ts-ignore
+  const AudioContext = window.AudioContext || window.webkitAudioContext;
+  if (AudioContext) {
+    return new AudioContext();
+  }
+}

package/src/room/utils.ts

@@ -0,0 +1,115 @@
+import { ClientInfo, ClientInfo_SDK } from '../proto/livekit_models';
+import { protocolVersion, version } from '../version';
+
+const separator = '|';
+
+export function unpackStreamId(packed: string): string[] {
+  const parts = packed.split(separator);
+  if (parts.length > 1) {
+    return [parts[0], packed.substr(parts[0].length + 1)];
+  }
+  return [packed, ''];
+}
+
+export async function sleep(duration: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, duration));
+}
+
+export function isFireFox(): boolean {
+  if (!isWeb()) return false;
+  return navigator.userAgent.indexOf('Firefox') !== -1;
+}
+
+export function isSafari(): boolean {
+  if (!isWeb()) return false;
+  return /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
+}
+
+export function isMobile(): boolean {
+  if (!isWeb()) return false;
+  return /Tablet|iPad|Mobile|Android|BlackBerry/.test(navigator.userAgent);
+}
+
+export function isWeb(): boolean {
+  return typeof document !== 'undefined';
+}
+
+function roDispatchCallback(entries: ResizeObserverEntry[]) {
+  for (const entry of entries) {
+    (entry.target as ObservableMediaElement).handleResize(entry);
+  }
+}
+
+function ioDispatchCallback(entries: IntersectionObserverEntry[]) {
+  for (const entry of entries) {
+    (entry.target as ObservableMediaElement).handleVisibilityChanged(entry);
+  }
+}
+
+let resizeObserver: ResizeObserver | null = null;
+export const getResizeObserver = () => {
+  if (!resizeObserver) resizeObserver = new ResizeObserver(roDispatchCallback);
+  return resizeObserver;
+};
+
+let intersectionObserver: IntersectionObserver | null = null;
+export const getIntersectionObserver = () => {
+  if (!intersectionObserver)
+    intersectionObserver = new IntersectionObserver(ioDispatchCallback, {
+      root: document,
+      rootMargin: '0px',
+    });
+  return intersectionObserver;
+};
+
+export interface ObservableMediaElement extends HTMLMediaElement {
+  handleResize: (entry: ResizeObserverEntry) => void;
+  handleVisibilityChanged: (entry: IntersectionObserverEntry) => void;
+}
+
+export function getClientInfo(): ClientInfo {
+  const info = ClientInfo.fromPartial({
+    sdk: ClientInfo_SDK.JS,
+    protocol: protocolVersion,
+    version,
+  });
+  return info;
+}
+
+let emptyVideoStreamTrack: MediaStreamTrack | undefined;
+
+export function getEmptyVideoStreamTrack() {
+  if (!emptyVideoStreamTrack) {
+    const canvas = document.createElement('canvas');
+    canvas.width = 2;
+    canvas.height = 2;
+    canvas.getContext('2d')?.fillRect(0, 0, canvas.width, canvas.height);
+    // @ts-ignore
+    const emptyStream = canvas.captureStream();
+    [emptyVideoStreamTrack] = emptyStream.getTracks();
+    if (!emptyVideoStreamTrack) {
+      throw Error('Could not get empty media stream video track');
+    }
+    emptyVideoStreamTrack.enabled = false;
+  }
+  return emptyVideoStreamTrack;
+}
+
+let emptyAudioStreamTrack: MediaStreamTrack | undefined;
+
+export function getEmptyAudioStreamTrack() {
+  if (!emptyAudioStreamTrack) {
+    // implementation adapted from https://blog.mozilla.org/webrtc/warm-up-with-replacetrack/
+    const ctx = new AudioContext();
+    const oscillator = ctx.createOscillator();
+    const dst = ctx.createMediaStreamDestination();
+    oscillator.connect(dst);
+    oscillator.start();
+    [emptyAudioStreamTrack] = dst.stream.getAudioTracks();
+    if (!emptyAudioStreamTrack) {
+      throw Error('Could not get empty media stream audio track');
+    }
+    emptyAudioStreamTrack.enabled = false;
+  }
+  return emptyAudioStreamTrack;
+}

package/src/test/mocks.ts

@@ -0,0 +1,17 @@
+import { SignalClient } from '../api/SignalClient';
+import RTCEngine from '../room/RTCEngine';
+
+jest.mock('../api/SignalClient');
+jest.mock('../room/RTCEngine');
+
+// mock helpers for testing
+
+const mocks = {
+  SignalClient: SignalClient as jest.MockedClass<typeof SignalClient>,
+  RTCEngine: RTCEngine as jest.MockedClass<typeof RTCEngine>,
+  MockLocalVideoTrack: {
+    stop: jest.fn(),
+  },
+};
+
+export default mocks;

package/src/version.ts

@@ -0,0 +1,2 @@
+export const version = '0.18.6';
+export const protocolVersion = 7;

package/CHANGELOG.md

@@ -1,5 +0,0 @@
-# Change Log
-
-## 0.12.0
-
-- Updated API to create screen share tracks.