livekit-client 0.15.3 → 0.16.2

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;
+}

package/src/room/utils.ts

@@ -0,0 +1,62 @@
+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 {
+  return navigator.userAgent.indexOf('Firefox') !== -1;
+}
+
+export function isSafari(): boolean {
+  return /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
+}
+
+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);
+  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;
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+export const version = '0.16.2';
+export const protocolVersion = 6;

package/.github/workflows/publish.yaml

@@ -1,55 +0,0 @@
-name: Publish
-
-# Controls when the action will run.
-on:
-  push:
-    # only publish on version tags
-    tags:
-      - v*
-
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
-jobs:
-  docs:
-    # The type of runner that the job will run on
-    runs-on: ubuntu-latest
-
-    # Steps represent a sequence of tasks that will be executed as part of the job
-    steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
-        with:
-          node-version: '16.x'
-      - uses: actions/cache@v2
-        with:
-          path: |
-            ~/.npm
-            ~/.config/yarn/global
-          key: ${{ runner.os }}-node-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-node-
-
-      - name: Install Yarn
-        run: |
-          npm install -g yarn
-          yarn install
-
-      - name: Build
-        run: yarn build
-
-      - name: Build Docs
-        run: yarn build-docs
-
-      - name: Publish to npm
-        run: |
-          npm config set '//registry.npmjs.org/:_authToken' $NPM_TOKEN
-          npm publish
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: S3 Upload
-        run: aws s3 cp docs/ s3://livekit-docs/client-sdk-js --recursive
-        env:
-          AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }}
-          AWS_DEFAULT_REGION: "us-east-1"

package/.github/workflows/test.yaml

@@ -1,36 +0,0 @@
-name: Test
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v2
-
-    - uses: actions/setup-node@v2
-      with:
-        node-version: '16.x'
-
-    - uses: actions/cache@v2
-      with:
-        path: |
-          ~/.npm
-          ~/.config/yarn/global
-        key: ${{ runner.os }}-node-${{ hashFiles('**/yarn.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-node-
-
-    - name: Install Yarn
-      run: |
-        npm install -g yarn
-        yarn install
-
-    - name: ESLint
-      run: yarn lint
-
-    - name: Run Tests
-      run: yarn test