Implement Dynacast and AdaptiveStream (#102)

* Update protocol, switch to using it as submodule

* Implements Dynacast. Renamed autoManageVideo -> adaptiveStream

Author: davidzhao

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "protocol"]
+	path = protocol
+	url = https://github.com/livekit/protocol

README.md

@@ -47,8 +47,11 @@ import {
 
 // creates a new room with options
 const room = new Room({
-  // automatically manage video quality
-  autoManageVideo: true,
+  // automatically manage subscribed video quality
+  adaptiveStream: true,
+
+  // optimize publishing bandwidth and CPU for simulcasted tracks
+  dynacast: true,
 
   // default capture settings
   videoCaptureDefaults: {
@@ -152,7 +155,21 @@ if (p) {
 }
 ```
 
-### Advanced track manipulation
+### Creating a track prior to creating a room
+
+In some cases, it may be useful to create a track before creating a room. For
+example, when building a staging area so the user may check their own camera.
+
+You can use our global track creation functions for this:
+
+```typescript
+const tracks = await createLocalTracks({
+  audio: true,
+  video: true,
+});
+```
+
+### Publish tracks from any source
 
 LiveKit lets you publish any track as long as it can be represented by a MediaStreamTrack. You can specify a name on the track in order to identify it later.
 

example/index.html

@@ -72,11 +72,22 @@ <h2>Livekit Sample App</h2>
               <input
                 type="checkbox"
                 class="form-check-input"
-                id="adaptive-video"
+                id="dynacast"
                 checked
               />
-              <label for="adaptive-video" class="form-check-label">
-                Adaptive video
+              <label for="dynacast" class="form-check-label">
+                Dynacast
+              </label>
+            </div>
+            <div>
+              <input
+                type="checkbox"
+                class="form-check-input"
+                id="adaptive-stream"
+                checked
+              />
+              <label for="adaptive-stream" class="form-check-label">
+                AdaptiveStream
               </label>
             </div>
             <div>

example/sample.ts

@@ -26,14 +26,16 @@ const appActions = {
     const url = (<HTMLInputElement>$('url')).value;
     const token = (<HTMLInputElement>$('token')).value;
     const simulcast = (<HTMLInputElement>$('simulcast')).checked;
+    const dynacast = (<HTMLInputElement>$('dynacast')).checked;
     const forceTURN = (<HTMLInputElement>$('force-turn')).checked;
-    const adaptiveVideo = (<HTMLInputElement>$('adaptive-video')).checked;
+    const adaptiveStream = (<HTMLInputElement>$('adaptive-stream')).checked;
     const shouldPublish = (<HTMLInputElement>$('publish-option')).checked;
 
     setLogLevel('debug');
 
     const roomOpts: RoomOptions = {
-      autoManageVideo: adaptiveVideo,
+      adaptiveStream,
+      dynacast,
       publishDefaults: {
         simulcast,
       },

package.json

@@ -11,7 +11,7 @@
   "scripts": {
     "build": "yarn exec tsc",
     "build-docs": "yarn exec typedoc",
-    "proto": "protoc --plugin=node_modules/ts-proto/protoc-gen-ts_proto --ts_proto_opt=esModuleInterop=true --ts_proto_out=./src/proto --ts_proto_opt=outputClientImpl=false,useOptionals=true -I../protocol ../protocol/livekit_rtc.proto ../protocol/livekit_models.proto",
+    "proto": "protoc --plugin=node_modules/ts-proto/protoc-gen-ts_proto --ts_proto_opt=esModuleInterop=true --ts_proto_out=./src/proto --ts_proto_opt=outputClientImpl=false,useOptionals=true -I./protocol ./protocol/livekit_rtc.proto ./protocol/livekit_models.proto",
     "sample": "cd example && webpack serve",
     "build-sample": "cd example && webpack && cp styles.css index.html dist/",
     "lint": "yarn exec eslint src",

protocol

@@ -11,6 +11,8 @@ import {
   SignalRequest,
   SignalResponse,
   SignalTarget,
+  StreamStateUpdate,
+  SubscribedQualityUpdate,
   TrackPublishedResponse,
   UpdateSubscription,
   UpdateTrackSettings,
@@ -59,6 +61,10 @@ export class SignalClient {
 
   onConnectionQuality?: (update: ConnectionQualityUpdate) => void;
 
+  onStreamStateUpdate?: (update: StreamStateUpdate) => void;
+
+  onSubscribedQualityUpdate?: (update: SubscribedQualityUpdate) => void;
+
   onLeave?: () => void;
 
   ws?: WebSocket;
@@ -310,6 +316,14 @@ export class SignalClient {
       if (this.onConnectionQuality) {
         this.onConnectionQuality(msg.connectionQuality);
       }
+    } else if (msg.streamStateUpdate) {
+      if (this.onStreamStateUpdate) {
+        this.onStreamStateUpdate(msg.streamStateUpdate);
+      }
+    } else if (msg.subscribedQualityUpdate) {
+      if (this.onSubscribedQualityUpdate) {
+        this.onSubscribedQualityUpdate(msg.subscribedQualityUpdate);
+      }
     } else {
       log.debug('unsupported message', msg);
     }

src/api/SignalClient.ts

@@ -31,6 +31,9 @@ export async function connect(
   options?: ConnectOptions,
 ): Promise<Room> {
   options ??= {};
+  if (options.adaptiveStream === undefined) {
+    options.adaptiveStream = options.autoManageVideo;
+  }
   setLogLevel(options.logLevel ?? LogLevel.warn);
 
   const config: RTCConfiguration = options.rtcConfig ?? {};

src/connect.ts

@@ -8,15 +8,22 @@ import {
  */
 export interface RoomOptions {
   /**
-   * automatically manage quality of subscribed video tracks, subscribe to the
-   * an appropriate resolution based on the size of the video elements that
-   * tracks are attached to.
+   * AdaptiveStream lets LiveKit automatically manage quality of subscribed
+   * video tracks to optimize for bandwidth and CPU.
+   * When attached video elements are visible, it'll choose an appropriate
+   * resolution based on the size of largest video element it's attached to.
    *
-   * also observes the visibility of attached tracks and pauses receiving data
-   * if they are not visible. when an attached element becomes visible again,
-   * the track resumes receiving data.
+   * When none of the video elements are visible, it'll temporarily pause
+   * the data flow until they are visible again.
    */
-  autoManageVideo?: boolean;
+  adaptiveStream?: boolean;
+
+  /**
+   * enable Dynacast, off by default. With Dynacast dynamically pauses
+   * video layers that are not being consumed by any subscribers, significantly
+   * reducing publishing CPU and bandwidth usage.
+   */
+  dynacast?: boolean;
 
   /**
    * default options to use when capturing user's audio
@@ -68,16 +75,21 @@ export interface ConnectOptions extends CreateLocalTracksOptions {
   autoSubscribe?: boolean;
 
   /**
-   * automatically manage quality of subscribed video tracks, subscribe to the
-   * an appropriate resolution based on the size of the video elements that tracks
-   * are attached to.
-   *
-   * also observes the visibility of attached tracks and pauses receiving data
-   * if they are not visible.
-   *
+   * see [[RoomOptions.adaptiveStream]]
+   */
+  adaptiveStream?: boolean;
+
+  /**
+   * alias for adaptiveStream
+   * @deprecated
    */
   autoManageVideo?: boolean;
 
+  /**
+   * see [[RoomOptions.dynacast]]
+   */
+  dynacast?: boolean;
+
   /** configures LiveKit internal log level */
   logLevel?: LogLevel | LogLevelDesc;