livekit-client 2.9.9 → 2.11.0

package/src/room/track/create.ts

@@ -31,70 +31,110 @@ export async function createLocalTracks(
   options?: CreateLocalTracksOptions,
 ): Promise<Array<LocalTrack>> {
   // set default options to true
-  options ??= {};
-  options.audio ??= { deviceId: 'default' };
-  options.video ??= { deviceId: 'default' };
+  const internalOptions = { ...(options ?? {}) };
+  let attemptExactMatch = false;
+  let retryAudioOptions: AudioCaptureOptions | undefined | boolean = options?.audio;
+  let retryVideoOptions: VideoCaptureOptions | undefined | boolean = options?.video;
+  // if the user passes a device id as a string, we default to exact match
+  if (
+    internalOptions.audio &&
+    typeof internalOptions.audio === 'object' &&
+    typeof internalOptions.audio.deviceId === 'string'
+  ) {
+    const deviceId: string = internalOptions.audio.deviceId;
+    internalOptions.audio.deviceId = { exact: deviceId };
+    attemptExactMatch = true;
+    retryAudioOptions = {
+      ...internalOptions.audio,
+      deviceId: { ideal: deviceId },
+    };
+  }
+  if (
+    internalOptions.video &&
+    typeof internalOptions.video === 'object' &&
+    typeof internalOptions.video.deviceId === 'string'
+  ) {
+    const deviceId: string = internalOptions.video.deviceId;
+    internalOptions.video.deviceId = { exact: deviceId };
+    attemptExactMatch = true;
+    retryVideoOptions = {
+      ...internalOptions.video,
+      deviceId: { ideal: deviceId },
+    };
+  }
+  internalOptions.audio ??= { deviceId: 'default' };
+  internalOptions.video ??= { deviceId: 'default' };
 
-  const { audioProcessor, videoProcessor } = extractProcessorsFromOptions(options);
-  const opts = mergeDefaultOptions(options, audioDefaults, videoDefaults);
+  const { audioProcessor, videoProcessor } = extractProcessorsFromOptions(internalOptions);
+  const opts = mergeDefaultOptions(internalOptions, audioDefaults, videoDefaults);
   const constraints = constraintsForOptions(opts);
 
   // Keep a reference to the promise on DeviceManager and await it in getLocalDevices()
   // works around iOS Safari Bug https://bugs.webkit.org/show_bug.cgi?id=179363
   const mediaPromise = navigator.mediaDevices.getUserMedia(constraints);
 
-  if (options.audio) {
+  if (internalOptions.audio) {
     DeviceManager.userMediaPromiseMap.set('audioinput', mediaPromise);
     mediaPromise.catch(() => DeviceManager.userMediaPromiseMap.delete('audioinput'));
   }
-  if (options.video) {
+  if (internalOptions.video) {
     DeviceManager.userMediaPromiseMap.set('videoinput', mediaPromise);
     mediaPromise.catch(() => DeviceManager.userMediaPromiseMap.delete('videoinput'));
   }
+  try {
+    const stream = await mediaPromise;
+    return await Promise.all(
+      stream.getTracks().map(async (mediaStreamTrack) => {
+        const isAudio = mediaStreamTrack.kind === 'audio';
+        let trackOptions = isAudio ? opts!.audio : opts!.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 stream = await mediaPromise;
-  return Promise.all(
-    stream.getTracks().map(async (mediaStreamTrack) => {
-      const isAudio = mediaStreamTrack.kind === 'audio';
-      let trackOptions = isAudio ? opts!.audio : opts!.video;
-      if (typeof trackOptions === 'boolean' || !trackOptions) {
-        trackOptions = {};
-      }
-      let trackConstraints: MediaTrackConstraints | undefined;
-      const conOrBool = isAudio ? constraints.audio : constraints.video;
-      if (typeof conOrBool !== 'boolean') {
-        trackConstraints = conOrBool;
-      }
+        // update the constraints with the device id the user gave permissions to in the permission prompt
+        // otherwise each track restart (e.g. mute - unmute) will try to initialize the device again -> causing additional permission prompts
+        const newDeviceId = mediaStreamTrack.getSettings().deviceId;
+        if (
+          trackConstraints?.deviceId &&
+          unwrapConstraint(trackConstraints.deviceId) !== newDeviceId
+        ) {
+          trackConstraints.deviceId = newDeviceId;
+        } else if (!trackConstraints) {
+          trackConstraints = { deviceId: newDeviceId };
+        }
 
-      // update the constraints with the device id the user gave permissions to in the permission prompt
-      // otherwise each track restart (e.g. mute - unmute) will try to initialize the device again -> causing additional permission prompts
-      const newDeviceId = mediaStreamTrack.getSettings().deviceId;
-      if (
-        trackConstraints?.deviceId &&
-        unwrapConstraint(trackConstraints.deviceId) !== newDeviceId
-      ) {
-        trackConstraints.deviceId = newDeviceId;
-      } else if (!trackConstraints) {
-        trackConstraints = { deviceId: newDeviceId };
-      }
+        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;
+        }
+        track.mediaStream = stream;
 
-      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;
-      }
-      track.mediaStream = stream;
+        if (isAudioTrack(track) && audioProcessor) {
+          await track.setProcessor(audioProcessor);
+        } else if (isVideoTrack(track) && videoProcessor) {
+          await track.setProcessor(videoProcessor);
+        }
 
-      if (isAudioTrack(track) && audioProcessor) {
-        await track.setProcessor(audioProcessor);
-      } else if (isVideoTrack(track) && videoProcessor) {
-        await track.setProcessor(videoProcessor);
-      }
-
-      return track;
-    }),
-  );
+        return track;
+      }),
+    );
+  } catch (e) {
+    if (!attemptExactMatch) {
+      throw e;
+    }
+    return createLocalTracks({
+      ...options,
+      audio: retryAudioOptions,
+      video: retryVideoOptions,
+    });
+  }
 }
 
 /**

package/src/room/track/options.ts

@@ -389,8 +389,12 @@ export function isBackupCodec(codec: string): codec is BackupVideoCodec {
 }
 
 export enum BackupCodecPolicy {
-  REGRESSION = 0,
+  // codec regression is preferred, the sfu will try to regress codec if possible but not guaranteed
+  PREFER_REGRESSION = 0,
+  // multi-codec simulcast, publish both primary and backup codec at the same time
   SIMULCAST = 1,
+  // always use backup codec only
+  REGRESSION = 2,
 }
 
 /**

package/src/room/track/utils.ts

@@ -33,7 +33,7 @@ export function mergeDefaultOptions(
       clonedOptions.audio as Record<string, unknown>,
       audioDefaults as Record<string, unknown>,
     );
-    clonedOptions.audio.deviceId ??= 'default';
+    clonedOptions.audio.deviceId ??= { ideal: 'default' };
     if (audioProcessor || defaultAudioProcessor) {
       clonedOptions.audio.processor = audioProcessor ?? defaultAudioProcessor;
     }
@@ -43,7 +43,7 @@ export function mergeDefaultOptions(
       clonedOptions.video as Record<string, unknown>,
       videoDefaults as Record<string, unknown>,
     );
-    clonedOptions.video.deviceId ??= 'default';
+    clonedOptions.video.deviceId ??= { ideal: 'default' };
     if (videoProcessor || defaultVideoProcessor) {
       clonedOptions.video.processor = videoProcessor ?? defaultVideoProcessor;
     }
@@ -81,9 +81,9 @@ export function constraintsForOptions(options: CreateLocalTracksOptions): MediaS
         }
       });
       constraints.video = videoOptions;
-      constraints.video.deviceId ??= 'default';
+      constraints.video.deviceId ??= { ideal: 'default' };
     } else {
-      constraints.video = options.video ? { deviceId: 'default' } : false;
+      constraints.video = options.video ? { deviceId: { ideal: 'default' } } : false;
     }
   } else {
     constraints.video = false;
@@ -92,9 +92,9 @@ export function constraintsForOptions(options: CreateLocalTracksOptions): MediaS
   if (options.audio) {
     if (typeof options.audio === 'object') {
       constraints.audio = options.audio;
-      constraints.audio.deviceId ??= 'default';
+      constraints.audio.deviceId ??= { ideal: 'default' };
     } else {
-      constraints.audio = { deviceId: 'default' };
+      constraints.audio = { deviceId: { ideal: 'default' } };
     }
   } else {
     constraints.audio = false;