@qencode/calls 0.2.0

package/dist/call.d.ts

@@ -0,0 +1,255 @@
+import { CallError } from './errors';
+import { type CallCredential } from './credential';
+import { type VideoProfileName, type VideoProfile } from './profiles';
+import { type LatencyMode } from './latency';
+import { type CallStats, type Quality, type Direction } from './stats';
+import { type TelemetryFields } from './telemetry';
+import { Devices, type DeviceList } from './devices';
+import { type VideoHandle } from './render';
+export type CallState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'ended';
+export type EndReason = 'left' | 'peerLeft' | 'roomClosed' | 'network' | 'credential' | 'error' | 'roomFull';
+export type LogLevelName = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export interface Peer {
+    identity: string;
+    name: string | null;
+    audioMuted: boolean;
+    videoMuted: boolean;
+}
+/** A data message from the peer. Strings and JSON objects arrive as sent; bytes arrive as Uint8Array. */
+export type MessagePayload = string | Uint8Array | Record<string, unknown> | unknown[];
+export interface ModerationEvent {
+    level: 'warn' | 'mute' | 'end';
+    classes: string[];
+    at: number;
+}
+/** Video codecs an app may ask for. H.264 is the default; the engine negotiates VP8 when a peer cannot decode the choice. */
+export type VideoCodec = 'h264' | 'vp8' | 'vp9' | 'av1';
+export declare const VIDEO_CODECS: readonly VideoCodec[];
+/**
+ * Builds the video track to publish for a profile: size a canvas, open a screen, wrap a processed
+ * camera. Called on every publish and republish, so a profile switch reaches it with the new size.
+ */
+export type VideoSourceFactory = (profile: VideoProfile) => MediaStreamTrack | Promise<MediaStreamTrack>;
+export type VideoSource = MediaStreamTrack | VideoSourceFactory;
+/** Which receiver property took the jitter buffer target; null before the first remote video track. */
+export type JitterBufferSupport = 'jitterBufferTarget' | 'playoutDelayHint' | 'unsupported' | null;
+/**
+ * App fields for every telemetry row, called once per row with its direction. `g2g_p50`, `g2g_p95`
+ * and `g2g_samples` (the app's own measured glass-to-glass latency, ms) are stored as columns;
+ * every other key lands in the row's `extra` object.
+ */
+export type TelemetryExtra = (direction: Direction) => TelemetryFields | null | undefined;
+export interface CallOptions {
+    /** Publish the microphone on connect. Default true. */
+    audio?: boolean;
+    /** Publish the camera on connect. Default true. */
+    video?: boolean;
+    /** Named media tier. Default p540_60. */
+    videoProfile?: VideoProfileName;
+    /** `lowest` (default) or `smooth`. */
+    latencyMode?: LatencyMode;
+    /** Pin a region name from the credential; default picks the fastest by probe. */
+    region?: string | null;
+    /** Post quality stats to Qencode every 5 s. Default true. */
+    telemetry?: boolean;
+    /** Resume after network changes for up to 60 s. Default true. */
+    autoReconnect?: boolean;
+    /** Default 'warn'. Never logs media or credentials. */
+    logLevel?: LogLevelName;
+    /** API base used only by telemetry. Default https://api.qencode.com, or the credential's api_base. */
+    apiBase?: string;
+    /** Initial camera and microphone device ids. */
+    cameraId?: string;
+    microphoneId?: string;
+    /** End the call when the peer leaves. Default true: a 1:1 call is over when one side is gone. */
+    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.
+     */
+    adaptiveStream?: 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
+     * factory returned when it is replaced or the call ends; a track passed directly stays yours to
+     * stop. `devices.setCamera` does not apply while a custom source is published.
+     */
+    videoSource?: VideoSource;
+    /** Video codec to publish. Default `h264`. */
+    codec?: VideoCodec;
+    /** Override the profile's simulcast setting. Default follows the profile. */
+    simulcast?: boolean;
+    /** Jitter buffer target in ms, overriding the latency mode's. `setLatencyMode` clears it. */
+    jitterBufferTargetMs?: number;
+    /** Fields appended to every telemetry row. */
+    telemetryExtra?: TelemetryExtra;
+    /** Forces TURN relay, for measuring the relay path. */
+    forceRelay?: boolean;
+}
+type OptionalKey = 'cameraId' | 'microphoneId' | 'region' | 'forceRelay' | 'videoSource' | 'simulcast' | 'jitterBufferTargetMs' | 'telemetryExtra';
+export type CallEvents = {
+    stateChanged: [CallState, EndReason | null];
+    peerJoined: [Peer];
+    peerLeft: [Peer];
+    remoteVideo: [VideoHandle | null];
+    remoteAudio: [VideoHandle | null];
+    peerMuted: ['audio' | 'video', boolean];
+    stats: [CallStats];
+    qualityChanged: [Quality, Direction];
+    message: [MessagePayload, boolean];
+    credentialExpiring: [number];
+    devicesChanged: [DeviceList];
+    moderation: [ModerationEvent];
+    error: [CallError];
+};
+/**
+ * One 1:1 call. Create it from a credential minted by your backend, attach the video handles to
+ * your views, and call `connect()`. The engine underneath is not part of this API.
+ */
+export declare class Call {
+    static create(credential: CallCredential, options?: CallOptions): Call;
+    readonly devices: Devices;
+    readonly options: Readonly<Required<Omit<CallOptions, OptionalKey>> & Pick<CallOptions, OptionalKey>>;
+    private readonly emitter;
+    private cred;
+    private _state;
+    private _endReason;
+    private room;
+    private profile;
+    private latency;
+    private _codec;
+    private simulcastOverride;
+    private jbOverride;
+    private jbSupport;
+    private videoSource;
+    /** The MediaStreamTrack currently published from `videoSource`, and whether a factory made it (then the SDK stops it). */
+    private sourceTrack;
+    private sourceOwned;
+    private regionChoice;
+    private _peer;
+    private agentPresent;
+    private remoteVideoTrack;
+    private remoteAudioTrack;
+    private _localVideo;
+    private _remoteVideo;
+    private _remoteAudio;
+    private audioEl;
+    private statsTimer;
+    private expiryTimer;
+    private reconnectTimer;
+    private telemetry;
+    private readonly recvTracker;
+    private readonly sendTracker;
+    private readonly recvQuality;
+    private readonly sendQuality;
+    private peerRttMs;
+    private joinMs;
+    private _stats;
+    private msgTimes;
+    private leaving;
+    private pendingEnd;
+    private constructor();
+    get state(): CallState;
+    get endReason(): EndReason | null;
+    get peer(): Peer | null;
+    get localVideo(): VideoHandle | null;
+    get remoteVideo(): VideoHandle | null;
+    get remoteAudio(): VideoHandle | null;
+    get stats(): CallStats | null;
+    get videoProfile(): VideoProfileName;
+    get latencyMode(): LatencyMode;
+    get videoCodec(): VideoCodec;
+    /** Whether video is published with simulcast layers: the override when set, else the profile's setting. */
+    get simulcast(): boolean;
+    /** The jitter buffer target in force: the override when set, else the latency mode's. */
+    get jitterBufferTargetMs(): number;
+    get jitterBufferSupport(): JitterBufferSupport;
+    /** Region probe results in ms by name, or null when no probe ran (one region, or a pinned one). */
+    get regionProbe(): Record<string, number> | null;
+    get identity(): string;
+    get callId(): string | null;
+    get region(): string | null;
+    get credentialExpiresAt(): number | null;
+    get agentJoined(): boolean;
+    on<K extends keyof CallEvents>(event: K, handler: (...args: CallEvents[K]) => void): () => void;
+    once<K extends keyof CallEvents>(event: K, handler: (...args: CallEvents[K]) => void): () => void;
+    off<K extends keyof CallEvents>(event: K, handler: (...args: CallEvents[K]) => void): void;
+    connect(): Promise<void>;
+    leave(): Promise<void>;
+    /** Replace the credential (same call, same identity) so the next reconnect uses a fresh token. */
+    updateCredential(credential: CallCredential): void;
+    /**
+     * A media server refuses a join with a bare websocket close, and a browser never sees the
+     * reason. When the server's validate endpoint still accepts the very same credential, the
+     * refusal was not the token, the room or the network; on a two-person room it is capacity.
+     * One short request on the failure path only.
+     */
+    private joinRefusedByServer;
+    setMicrophoneEnabled(enabled: boolean): Promise<void>;
+    setCameraEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Switch resolution, frame rate and bitrate cap mid-call. A simulcast change or a factory video
+     * source republishes the track; a camera restarts capture in place; a fixed custom track only
+     * gets the new encoding parameters.
+     */
+    setVideoProfile(name: VideoProfileName): Promise<void>;
+    setLatencyMode(mode: LatencyMode): Promise<void>;
+    /**
+     * Pin the receiver's jitter buffer target in ms regardless of the latency mode (0 asks the
+     * browser for its floor). Returns which receiver property took it; `unsupported` on Firefox.
+     * `setLatencyMode` clears the pin.
+     */
+    setJitterBufferTarget(ms: number): JitterBufferSupport;
+    /** Change the codec or the simulcast setting mid-call; the video track is republished. */
+    setVideoEncoding(opts: {
+        codec?: VideoCodec;
+        simulcast?: boolean | null;
+    }): Promise<void>;
+    /** Replace the video source mid-call; `null` returns to the camera. Republishes when video is published. */
+    setVideoSource(source: VideoSource | null): Promise<void>;
+    /** Send up to 15 KB to the peer. Strings and JSON-able objects arrive as sent; Uint8Array arrives as bytes. */
+    sendMessage(payload: MessagePayload, reliable?: boolean): Promise<void>;
+    private buildRoom;
+    private publishOptions;
+    private captureOptions;
+    private audioCaptureOptions;
+    private publishAudio;
+    private publishVideo;
+    /** Takes the track from `videoSource`; a factory's result is owned by the SDK, a passed track is not. */
+    private resolveSource;
+    private releaseSource;
+    private unpublishVideo;
+    /** Unpublish and publish again with the current source, codec, simulcast and profile. A muted camera stays off. */
+    private republishVideo;
+    private applyEncoding;
+    private applyJitterTarget;
+    private adoptExistingParticipants;
+    private countHumans;
+    private onParticipantConnected;
+    private onParticipantDisconnected;
+    private onTrackSubscribed;
+    private onTrackUnsubscribed;
+    private onMuteChange;
+    private onData;
+    private onReconnecting;
+    private onReconnected;
+    private onDisconnected;
+    private startStats;
+    private pollStats;
+    private extraFields;
+    private audioRoute;
+    private sendHello;
+    private scheduleExpiryWarning;
+    private ensureAudioElement;
+    private requireRoom;
+    private setState;
+    private endWith;
+    private finish;
+    private teardown;
+}
+/** Envelope: 1 tag byte (1 string, 2 json, 3 bytes) followed by the payload. */
+export declare function encodeMessage(payload: MessagePayload): Uint8Array;
+export declare function decodeMessage(bytes: Uint8Array): MessagePayload;
+export {};

package/dist/credential.d.ts

@@ -0,0 +1,42 @@
+/** One region a credential may connect through. */
+export interface Region {
+    name: string;
+    url: string;
+}
+/**
+ * The token response from `POST /v1/calls/{id}/tokens`, passed to the app unchanged by the
+ * customer's backend. Only `token` and `url` are required; the rest is read from the JWT
+ * payload when missing.
+ */
+export interface CallCredential {
+    token: string;
+    url: string;
+    regions?: Region[];
+    identity?: string;
+    room_name?: string;
+    /** ISO 8601 string, epoch seconds, or epoch milliseconds. */
+    expires_at?: string | number;
+    call_id?: string;
+    /** Optional API base for telemetry; overrides the SDK default. */
+    api_base?: string;
+}
+export interface ParsedCredential {
+    token: string;
+    url: string;
+    regions: Region[];
+    identity: string;
+    roomName: string;
+    /** Epoch milliseconds, or null when unknown. */
+    expiresAt: number | null;
+    callId: string | null;
+    apiBase: string | null;
+}
+/** Fires `credentialExpiring` this long before `expiresAt`. */
+export declare const EXPIRY_WARNING_MS: number;
+export declare function parseCredential(input: CallCredential): ParsedCredential;
+export declare function isExpired(c: ParsedCredential, now?: number): boolean;
+/** Milliseconds until the expiry warning should fire; 0 when already due; null when unknown. */
+export declare function msUntilExpiryWarning(c: ParsedCredential, now?: number): number | null;
+export declare function parseExpiry(v: string | number | undefined): number | null;
+/** Decodes the JWT payload without verifying the signature; the media server verifies it. */
+export declare function decodeJwtPayload(token: string): Record<string, unknown>;

package/dist/devices.d.ts

@@ -0,0 +1,40 @@
+import type { Room } from 'livekit-client';
+export interface DeviceInfo {
+    id: string;
+    label: string;
+}
+export interface DeviceList {
+    cameras: DeviceInfo[];
+    microphones: DeviceInfo[];
+    speakers: DeviceInfo[];
+}
+/**
+ * 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.
+ */
+export declare class Devices {
+    private readonly emitter;
+    private room;
+    private readonly audioElements;
+    private speakerId;
+    private customVideo;
+    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 */
+    _registerAudioElement(el: HTMLMediaElement): void;
+    /** @internal */
+    _start(): void;
+    /** @internal */
+    _stop(): void;
+    list(): Promise<DeviceList>;
+    get canSelectSpeaker(): boolean;
+    setCamera(deviceId: string): Promise<void>;
+    setMicrophone(deviceId: string): Promise<void>;
+    setSpeaker(deviceId: string): Promise<void>;
+    onChange(handler: (list: DeviceList) => void): () => void;
+    private switch;
+    private applySink;
+}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/** Stable error codes, identical on every platform (web, iOS, Android). */
+export type CallErrorCode = 'credentialInvalid' | 'credentialExpired' | 'roomFull' | 'roomClosed' | 'permissionDenied' | 'deviceUnavailable' | 'network' | 'unsupported' | 'internal';
+export declare class CallError extends Error {
+    readonly code: CallErrorCode;
+    /** Whether trying again, possibly after user action, can succeed. */
+    readonly retryable: boolean;
+    readonly cause?: unknown;
+    constructor(code: CallErrorCode, message: string, opts?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+export declare function isCallError(e: unknown): e is CallError;
+/**
+ * Map an engine or browser error to a CallError. Engine mapping (livekit-client 2.22):
+ *
+ * - message matches "room is full" / "max participants"        -> roomFull
+ * - ConnectionError NotAllowed (HTTP 401/403 on join)            -> credentialInvalid
+ * - ConnectionError ServerUnreachable / WebSocket / Timeout      -> network
+ *   (Call.connect() turns a WebSocket refusal into roomFull when the server's validate
+ *   endpoint still accepts the credential; the server sends no reason a browser can read)
+ * - ConnectionError ServiceNotFound (wrong URL path)             -> credentialInvalid (the url in the credential is wrong)
+ * - ConnectionError Cancelled / LeaveRequest                     -> internal, not retryable (connect() was abandoned by leave())
+ * - ConnectionError InternalError                                -> internal
+ * - DOMException NotAllowedError / PermissionDeniedError         -> permissionDenied
+ * - DOMException NotFoundError / NotReadableError / OverconstrainedError / AbortError -> deviceUnavailable
+ * - anything else                                                -> internal, with the original message attached
+ */
+export declare function mapEngineError(e: unknown): CallError;

package/dist/events.d.ts

@@ -0,0 +1,11 @@
+/** Minimal typed event emitter. Handlers run synchronously on the calling thread; a throwing
+ *  handler is reported through console.error and never breaks the emitter or the SDK. */
+export type Listener<T extends unknown[]> = (...args: T) => void;
+export declare class Emitter<M extends Record<string, unknown[]>> {
+    private readonly handlers;
+    on<K extends keyof M>(event: K, handler: Listener<M[K]>): () => void;
+    once<K extends keyof M>(event: K, handler: Listener<M[K]>): () => void;
+    off<K extends keyof M>(event: K, handler: Listener<M[K]>): void;
+    emit<K extends keyof M>(event: K, ...args: M[K]): void;
+    removeAll(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { Call, encodeMessage, decodeMessage } from './call';
+export type { CallOptions, CallEvents, CallState, EndReason, Peer, MessagePayload, ModerationEvent, LogLevelName, VideoCodec, VideoSource, VideoSourceFactory, JitterBufferSupport, TelemetryExtra } from './call';
+export { VIDEO_CODECS } from './call';
+export type { TelemetryFields } from './telemetry';
+export { CallError, isCallError } from './errors';
+export type { CallErrorCode } from './errors';
+export type { CallCredential, Region } from './credential';
+export { PROFILES, DEFAULT_PROFILE } from './profiles';
+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 { VideoHandle } from './render';
+export { QencodeVideoElement, registerVideoElement } from './render';
+export { SDK_VERSION } from './version';

package/dist/latency.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Latency modes move several engine knobs together.
+ *
+ * - `lowest`: jitter buffer target at the platform minimum (0 ms asks the browser for its floor),
+ *   degradation drops resolution before frame rate, 10 ms Opus frames where the platform lets us.
+ * - `smooth`: jitter buffer target 150 ms, degradation drops frame rate before resolution,
+ *   20 ms Opus frames.
+ */
+export type LatencyMode = 'lowest' | 'smooth';
+export interface LatencySettings {
+    jitterBufferTargetMs: number;
+    degradationPreference: RTCDegradationPreference;
+    audioFrameMs: 10 | 20;
+}
+export declare const LATENCY_SETTINGS: Readonly<Record<LatencyMode, LatencySettings>>;
+export declare const DEFAULT_LATENCY_MODE: LatencyMode;
+export declare function latencySettings(mode: LatencyMode | undefined): LatencySettings;
+/**
+ * Applies a jitter buffer target to a receiver. Returns which property took it:
+ * `jitterBufferTarget` (Chromium 108+, Safari 17.4+), `playoutDelayHint` (older Chromium), or
+ * `null` when the browser exposes neither (Firefox). Never throws.
+ */
+export declare function applyJitterBufferTarget(receiver: RTCRtpReceiver | undefined | null, ms: number): 'jitterBufferTarget' | 'playoutDelayHint' | null;
+/** Applies a degradation preference to a live sender without republishing. Returns false when unsupported. */
+export declare function applyDegradationPreference(sender: RTCRtpSender | undefined | null, pref: RTCDegradationPreference): Promise<boolean>;

package/dist/profiles.d.ts

@@ -0,0 +1,18 @@
+/** Named media tiers. Quality, cost and the pricing tier line up on these; apps pick a name, never raw constraints. */
+export type VideoProfileName = 'audioOnly' | 'p360_30' | 'p540_30' | 'p540_60' | 'p720_30' | 'p720_60' | 'p1080_30';
+export interface VideoProfile {
+    name: VideoProfileName;
+    width: number;
+    height: number;
+    fps: number;
+    /** Encoder bitrate cap in bits per second. */
+    maxBitrate: number;
+    /** Simulcast layers are published at 720p and above; below, the single layer is cheaper to encode. */
+    simulcast: boolean;
+    video: boolean;
+}
+export declare const PROFILES: Readonly<Record<VideoProfileName, VideoProfile>>;
+export declare const DEFAULT_PROFILE: VideoProfileName;
+/** Opus bitrate for the microphone track, bits per second. */
+export declare const AUDIO_BITRATE = 48000;
+export declare function resolveProfile(name: VideoProfileName | undefined): VideoProfile;