@qencode/calls 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,8 @@
 
 Low-latency 1:1 audio and video calls inside your own UI. The SDK takes a short-lived
 participant credential minted by **your backend**, connects, renders media into views you
-place, and reports call quality. It ships no screens and no theme. Version 0.2.0, pre-release.
+place, and reports call quality. It ships no screens and no theme. Version 0.3.0, pre-release,
+on npm as [`@qencode/calls`](https://www.npmjs.com/package/@qencode/calls).
 
 ## Quickstart
 
@@ -72,7 +73,7 @@ which is about 145 KB gzipped on its own.
 | `setJitterBufferTarget(ms)` | Pins the receiver's jitter buffer target regardless of the mode. Returns which property took it: `jitterBufferTarget`, `playoutDelayHint`, or `unsupported` (Firefox). |
 | `setVideoEncoding({ codec, simulcast })` | Switches codec or simulcast mid-call; the video track is republished. |
 | `setVideoSource(source \| null)` | Replaces the published video with a custom track or factory, or returns to the camera. See below. |
-| `devices` | `list()`, `setCamera(id)`, `setMicrophone(id)`, `setSpeaker(id)`, `onChange(handler)`, `canSelectSpeaker`. |
+| `devices` | `list()`, `setCamera(id)`, `setCameraFacing('user' \| 'environment')`, `setMicrophone(id)`, `setSpeaker(id)`, `cameraId`, `cameraFacing`, `microphoneId`, `onChange(handler)`, `canSelectSpeaker`. A choice made before `connect()` or while the camera is off is applied when the camera is next published. |
 | `sendMessage(payload, reliable = true)` | Up to 15 KB, 30 per second, to the peer. Strings and JSON objects arrive as sent, `Uint8Array` as bytes. |
 | `stats` | Latest quality snapshot, refreshed every second. |
 | `peer` | Identity, display name and mute state of the other human, or `null`. |
@@ -108,6 +109,22 @@ bench wants and what a customer UI rarely does.
 | `telemetryExtra` | none | `(direction) => fields` appended to every telemetry row; see telemetry. |
 | `forceRelay` | `false` | Connect through TURN only, to measure the relay path. |
 
+### Switching cameras
+
+On a phone, flip between the front and the rear camera by direction rather than by id:
+
+```ts
+const facing = call.devices.cameraFacing;                       // 'user', 'environment', or null when unknown
+await call.devices.setCameraFacing(facing === 'user' ? 'environment' : 'user');
+self.toggleAttribute('mirror', call.devices.cameraFacing !== 'environment');   // mirror only a user-facing camera
+```
+
+Phone browsers honour the direction directly. Elsewhere the SDK falls back to a camera whose
+label says which way it points (`DeviceInfo.facing`, from labels such as "Back Camera" or
+"camera2 0, facing back") and throws `deviceUnavailable` when there is none; a desktop app
+then offers `devices.list().cameras` and calls `setCamera(id)`. Either way the profile's
+resolution is kept, and a later profile switch stays on the chosen camera.
+
 ### Custom video source
 
 Pass `videoSource` to publish something other than the raw camera: a canvas with an overlay or a

package/dist/call.d.ts

@@ -65,11 +65,18 @@ export interface CallOptions {
     endOnPeerLeft?: boolean;
     /**
      * Let the engine adapt what it sends and receives to how the video is displayed (default true).
-     * The receiver asks for the layer matching the rendered size, and a video element that is
-     * hidden or in a background tab pauses that track on the server. Set false to always
-     * receive and send the full profile regardless of visibility, as a measurement bench does.
+     * The receiver asks for the layer matching the rendered size in device pixels, and the sender
+     * encodes only the layers someone is subscribed to. Set false to always receive and send the
+     * full profile regardless of how the video is shown, as a measurement bench does.
      */
     adaptiveStream?: boolean;
+    /**
+     * With `adaptiveStream`, pause the remote video on the server while the page is hidden (a
+     * background tab, a minimized window) and resume it when the page is shown again. Default
+     * false: a call keeps its picture flowing so it is there the moment the user comes back, and
+     * the peer's encoder never has to restart. Set true to save bandwidth while hidden.
+     */
+    pauseVideoInBackground?: boolean;
     /**
      * Publish this track instead of opening the camera: a canvas, a screen, a processed camera. A
      * factory is called with the profile on every publish and republish. The SDK stops a track a
@@ -213,6 +220,7 @@ export declare class Call {
     sendMessage(payload: MessagePayload, reliable?: boolean): Promise<void>;
     private buildRoom;
     private publishOptions;
+    /** Profile resolution plus the camera the devices object currently selects (an id, a facing, or the default). */
     private captureOptions;
     private audioCaptureOptions;
     private publishAudio;

package/dist/devices.d.ts

@@ -1,7 +1,11 @@
-import type { Room } from 'livekit-client';
+import { type Room, type VideoCaptureOptions } from 'livekit-client';
+/** Which way a camera points: `user` faces the person, `environment` faces away (the rear camera on a phone). */
+export type CameraFacing = 'user' | 'environment';
 export interface DeviceInfo {
     id: string;
     label: string;
+    /** For cameras: which way it points when the label says so (phones do); null when unknown. */
+    facing?: CameraFacing | null;
 }
 export interface DeviceList {
     cameras: DeviceInfo[];
@@ -10,7 +14,10 @@ export interface DeviceList {
 }
 /**
  * Device selection. Labels are empty until the first getUserMedia permission is granted; after
- * `connect()` the list is complete. Speaker selection needs `setSinkId`, which Safari lacks.
+ * `connect()` the list is complete. A camera or microphone chosen before `connect()` is used
+ * when the track is first published; chosen mid-call it is switched in place; chosen while the
+ * camera is off it takes effect when the camera is turned back on. Speaker selection needs
+ * `setSinkId`, which Safari lacks.
  */
 export declare class Devices {
     private readonly emitter;
@@ -18,11 +25,35 @@ export declare class Devices {
     private readonly audioElements;
     private speakerId;
     private customVideo;
+    private cameraIdValue;
+    private microphoneIdValue;
+    /** A facing request not yet turned into a concrete device id. */
+    private facingWish;
+    /** True when a camera choice is waiting for the camera to be published or unmuted. */
+    private pending;
+    private captureOptions;
     private readonly onDeviceChange;
     /** @internal */
     _attachRoom(room: Room | null): void;
     /** @internal The call publishes a custom video source, so the engine must not replace it with a camera. */
     _setCustomVideo(on: boolean): void;
+    /** @internal Initial ids from CallOptions. */
+    _setInitial(cameraId?: string, microphoneId?: string): void;
+    /** @internal The call's capture options (profile resolution plus the selection below), used to restart the camera. */
+    _setCaptureOptions(fn: () => VideoCaptureOptions): void;
+    /**
+     * @internal The camera selection part of the capture constraints. A chosen id is exact: a
+     * preference lets the browser keep the camera it already has (Chrome does when the other one
+     * takes a moment to wake, as a phone used as a webcam does). A facing stays a preference so
+     * desktops, which cannot honour it, do not fail.
+     */
+    _videoSelection(): Pick<VideoCaptureOptions, 'deviceId' | 'facingMode'>;
+    /** @internal The chosen camera could not be opened at publish time; fall back to the default one. */
+    _clearCamera(): void;
+    /** @internal */
+    _microphoneSelection(): string | undefined;
+    /** @internal Called by the call when the camera is (re)published or unmuted: applies a deferred choice and records what is in use. */
+    _cameraPublished(): Promise<void>;
     /** @internal */
     _registerAudioElement(el: HTMLMediaElement): void;
     /** @internal */
@@ -31,10 +62,35 @@ export declare class Devices {
     _stop(): void;
     list(): Promise<DeviceList>;
     get canSelectSpeaker(): boolean;
+    /** The camera in use, or the one chosen for when the camera is next published; null for the system default. */
+    get cameraId(): string | null;
+    get microphoneId(): string | null;
+    /** Which way the camera in use points, when the browser says (phones do); otherwise the last facing asked for, or null. */
+    get cameraFacing(): CameraFacing | null;
+    /** Use this camera: now when it is published and on, otherwise as soon as it is. */
     setCamera(deviceId: string): Promise<void>;
+    /**
+     * Use the camera that faces the given way: the front (`user`) or the rear (`environment`)
+     * camera on a phone. Browsers on phones honour the request directly; elsewhere a camera whose
+     * label says which way it points is used, and `deviceUnavailable` is thrown when there is none.
+     */
+    setCameraFacing(mode: CameraFacing): Promise<void>;
     setMicrophone(deviceId: string): Promise<void>;
     setSpeaker(deviceId: string): Promise<void>;
     onChange(handler: (list: DeviceList) => void): () => void;
+    /**
+     * Records a selection and restarts the published, unmuted camera with it. Returns false when
+     * that has to wait. The engine stops the old capture before it opens the new one, so when the
+     * new camera cannot be opened the previous selection is put back and reopened, and the call
+     * keeps its picture; the failure is still thrown.
+     */
+    private select;
+    private syncFromTrack;
+    private cameraTrack;
+    private trackSettings;
+    private refuseIfCustomVideo;
     private switch;
     private applySink;
 }
+/** Phones label their cameras by direction ("Back Camera", "camera2 0, facing back"); desktops rarely do. */
+export declare function facingFromLabel(label: string): CameraFacing | null;

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { VideoProfileName, VideoProfile } from './profiles';
 export { LATENCY_SETTINGS, DEFAULT_LATENCY_MODE } from './latency';
 export type { LatencyMode, LatencySettings } from './latency';
 export type { CallStats, RecvStats, SendStats, Quality, Direction, Transport, CandidateType, AudioRoute } from './stats';
-export type { DeviceInfo, DeviceList } from './devices';
+export type { DeviceInfo, DeviceList, CameraFacing } from './devices';
 export type { VideoHandle } from './render';
 export { QencodeVideoElement, registerVideoElement } from './render';
 export { SDK_VERSION } from './version';