Add BackupCodecPolicy to TrackPublishDefaults (livekit#1399)

Co-authored-by: lukasIO <mail@lukasseiler.de>

Author: 2 people

.changeset/honest-hornets-fail.md

@@ -0,0 +1,9 @@
+---
+'livekit-client': minor
+---
+
+Add backupCodecPolicy to TrackPublishDefaults
+
+The default policy of backup codec is `codec regression` for maxium compatibility, which means the publisher stops sending primary codec and all subscribers will receive backup codec even primary codec is supported. 
+It changes the default behavior `multi-codec simulcast` in the previous version, will not break the functionality of the previous version but only cause potential extra bandwidth usage. The user can set the policy to `multi-codec simulcast` to keep the previous behavior.
+ 

examples/demo/demo.ts

@@ -10,6 +10,7 @@ import type {
   VideoCodec,
 } from '../../src/index';
 import {
+  BackupCodecPolicy,
   ConnectionQuality,
   ConnectionState,
   DisconnectReason,
@@ -98,6 +99,10 @@ const appActions = {
     const autoSubscribe = (<HTMLInputElement>$('auto-subscribe')).checked;
     const e2eeEnabled = (<HTMLInputElement>$('e2ee')).checked;
     const audioOutputId = (<HTMLSelectElement>$('audio-output')).value;
+    let backupCodecPolicy: BackupCodecPolicy | undefined;
+    if ((<HTMLInputElement>$('multicodec-simulcast')).checked) {
+      backupCodecPolicy = BackupCodecPolicy.SIMULCAST;
+    }
 
     updateSearchParams(url, token, cryptoKey);
 
@@ -116,6 +121,7 @@ const appActions = {
         forceStereo: false,
         screenShareEncoding: ScreenSharePresets.h1080fps30.encoding,
         scalabilityMode: 'L3T3_KEY',
+        backupCodecPolicy: backupCodecPolicy,
       },
       videoCaptureDefaults: {
         resolution: VideoPresets.h720.resolution,

examples/demo/index.html

@@ -81,6 +81,10 @@ <h2>Livekit Sample App</h2>
                 disabled="true"
               ></select>
             </div>
+            <div>
+              <input type="checkbox" class="form-check-input" id="multicodec-simulcast" />
+              <label for="multicodec-simulcast" class="form-check-label">MultiCodec-Simulcast </label>
+            </div>
           </div>
 
           <!-- actions -->

package.json

@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@livekit/mutex": "1.1.1",
-    "@livekit/protocol": "1.32.0",
+    "@livekit/protocol": "1.33.0",
     "events": "^3.3.0",
     "loglevel": "^1.8.0",
     "sdp-transform": "^2.14.1",

pnpm-lock.yaml

@@ -937,6 +937,7 @@ export default class LocalParticipant extends Participant {
       stereo: isStereo,
       disableRed: this.isE2EEEnabled || !(opts.red ?? true),
       stream: opts?.stream,
+      backupCodecPolicy: opts?.backupCodecPolicy,
     });
 
     // compute encodings and layers for video

src/room/participant/LocalParticipant.ts

@@ -12,8 +12,7 @@ export interface TrackPublishDefaults {
   videoEncoding?: VideoEncoding;
 
   /**
-   * Multi-codec Simulcast
-   * VP9 and AV1 are not supported by all browser clients. When backupCodec is
+   * Advanced codecs (VP9/AV1/H265) are not supported by all browser clients. When backupCodec is
    * set, when an incompatible client attempts to subscribe to the track, LiveKit
    * will automatically publish a secondary track encoded with the backup codec.
    *
@@ -24,6 +23,20 @@ export interface TrackPublishDefaults {
    */
   backupCodec?: true | false | { codec: BackupVideoCodec; encoding?: VideoEncoding };
 
+  /**
+   * When backup codec is enabled, there are two options to decide whether to
+   * send the primary codec at the same time:
+   *   * codec regression: publisher stops sending primary codec and all subscribers
+   *       will receive backup codec even if the primary codec is supported on their browser. It is the default
+   *       behavior and provides maximum compatibility. It also reduces CPU
+   *       and bandwidth consumption for publisher.
+   *   * multi-codec simulcast: publisher encodes and sends both codecs at same time,
+   *       subscribers will get most efficient codec. It will provide most bandwidth
+   *       efficiency, especially in the large 1:N room but requires more device performance
+   *       and bandwidth consumption for publisher.
+   */
+  backupCodecPolicy?: BackupCodecPolicy;
+
   /**
    * encoding parameters for screen share track
    */
@@ -375,6 +388,11 @@ export function isBackupCodec(codec: string): codec is BackupVideoCodec {
   return !!backupCodecs.find((backup) => backup === codec);
 }
 
+export enum BackupCodecPolicy {
+  REGRESSION = 0,
+  SIMULCAST = 1,
+}
+
 /**
  * scalability modes for svc.
  */