@axonkit/client-sdk-js 0.1.0

package/dist/track/options.d.ts

@@ -0,0 +1,525 @@
+import type { TrackSource } from '../protocol/types';
+/**
+ * Options for capturing video from a camera device.
+ */
+export interface VideoCaptureOptions {
+    /**
+     * A ConstrainDOMString specifying a device ID or an array of device IDs
+     * which are acceptable and/or required.
+     */
+    deviceId?: ConstrainDOMString;
+    /**
+     * A ConstrainDouble specifying the frame rate or range of frame rates
+     * which are acceptable and/or required.
+     */
+    frameRate?: ConstrainDouble;
+    /**
+     * A facing or an array of facings which are acceptable and/or required.
+     */
+    facingMode?: 'user' | 'environment' | 'left' | 'right';
+    /**
+     * Target capture resolution.
+     */
+    resolution?: VideoResolution;
+}
+/**
+ * Video resolution descriptor.
+ */
+export interface VideoResolution {
+    width: number;
+    height: number;
+    frameRate?: number;
+    aspectRatio?: number;
+}
+/**
+ * Options for capturing audio from a microphone device.
+ */
+export interface AudioCaptureOptions {
+    /**
+     * Specifies whether automatic gain control is preferred and/or required.
+     */
+    autoGainControl?: ConstrainBoolean;
+    /**
+     * The channel count or range of channel counts which are acceptable
+     * and/or required.
+     */
+    channelCount?: ConstrainULong;
+    /**
+     * A ConstrainDOMString specifying a device ID or an array of device IDs
+     * which are acceptable and/or required.
+     */
+    deviceId?: ConstrainDOMString;
+    /**
+     * Whether or not echo cancellation is preferred and/or required.
+     */
+    echoCancellation?: ConstrainBoolean;
+    /**
+     * The latency or range of latencies which are acceptable and/or required.
+     */
+    latency?: ConstrainDouble;
+    /**
+     * Whether noise suppression is preferred and/or required.
+     */
+    noiseSuppression?: ConstrainBoolean;
+    /**
+     * @experimental
+     * A stronger version of `noiseSuppression`; browser support is not
+     * widespread yet. When set (and supported) the value for
+     * `noiseSuppression` will be ignored.
+     *
+     * @see https://w3c.github.io/mediacapture-extensions/#voiceisolation-constraint
+     */
+    voiceIsolation?: ConstrainBoolean;
+    /**
+     * The sample rate or range of sample rates which are acceptable
+     * and/or required.
+     */
+    sampleRate?: ConstrainULong;
+    /**
+     * The sample size or range of sample sizes which are acceptable
+     * and/or required.
+     */
+    sampleSize?: ConstrainULong;
+}
+/**
+ * Options for audio output device selection.
+ *
+ * Only supported on browsers where `setSinkId` is available.
+ */
+export interface AudioOutputOptions {
+    /**
+     * Device ID to route audio output to.
+     */
+    deviceId?: string;
+}
+/**
+ * Options for capturing a screen share.
+ */
+export interface ScreenShareCaptureOptions {
+    /**
+     * `true` to capture audio shared alongside the screen. Browser support for
+     * audio capturing in screen share is limited.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia#browser_compatibility
+     */
+    audio?: boolean | AudioCaptureOptions;
+    /**
+     * `true` to capture video. Chrome allows additional options.
+     *
+     * @see https://developer.chrome.com/docs/web-platform/screen-sharing-controls/#displaySurface
+     */
+    video?: true | {
+        displaySurface?: 'window' | 'browser' | 'monitor';
+    };
+    /**
+     * Capture resolution. Defaults to 1080 for most browsers.
+     */
+    resolution?: VideoResolution;
+    /**
+     * Target frame rate for the screen share capture.
+     */
+    frameRate?: number;
+    /**
+     * Specifies whether the browser should allow the user to select the
+     * current tab for capture.
+     */
+    selfBrowserSurface?: 'include' | 'exclude';
+    /**
+     * Specifies whether the browser should display a control to allow the user
+     * to dynamically switch the shared tab during screen-sharing.
+     */
+    surfaceSwitching?: 'include' | 'exclude';
+    /**
+     * Specifies whether the browser should include the system audio among the
+     * possible audio sources offered to the user.
+     */
+    systemAudio?: 'include' | 'exclude';
+    /**
+     * Specify the type of content.
+     *
+     * @see https://www.w3.org/TR/mst-content-hint/#video-content-hints
+     */
+    contentHint?: 'detail' | 'text' | 'motion';
+    /**
+     * @experimental
+     * Controls whether the audio playing in a tab will continue to be played
+     * out of a user's local speakers when the tab is captured.
+     */
+    suppressLocalAudioPlayback?: boolean;
+    /**
+     * @experimental
+     * Instructs the browser to offer the current tab as the most prominent
+     * capture source.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia#prefercurrenttab
+     */
+    preferCurrentTab?: boolean;
+    /**
+     * A CaptureController instance for further manipulation of the capture
+     * session if included.
+     */
+    controller?: unknown;
+}
+/**
+ * Video encoding parameters.
+ */
+export interface VideoEncoding {
+    maxBitrate: number;
+    maxFramerate?: number;
+    priority?: RTCPriorityType;
+}
+/**
+ * Audio preset defining the maximum bitrate and optional priority.
+ */
+export interface AudioPreset {
+    maxBitrate: number;
+    priority?: RTCPriorityType;
+}
+/**
+ * Options accepted by the {@link VideoPreset} constructor.
+ */
+export interface VideoPresetOptions {
+    width: number;
+    height: number;
+    aspectRatio?: number;
+    maxBitrate: number;
+    maxFramerate?: number;
+    priority?: RTCPriorityType;
+}
+/**
+ * Encapsulates a video resolution together with its target encoding
+ * parameters. Used for simulcast layers and default presets.
+ */
+export declare class VideoPreset {
+    encoding: VideoEncoding;
+    width: number;
+    height: number;
+    aspectRatio?: number;
+    constructor(options: VideoPresetOptions);
+    constructor(width: number, height: number, maxBitrate: number, maxFramerate?: number, priority?: RTCPriorityType);
+    /** Convenience getter that returns a {@link VideoResolution} from this preset. */
+    get resolution(): VideoResolution;
+}
+/** `red` is not technically a codec but treated as one in signalling. */
+export declare const audioCodecs: readonly ["opus", "red"];
+/** Audio codec identifier. */
+export type AudioCodec = (typeof audioCodecs)[number];
+declare const backupVideoCodecs: readonly ["vp8", "h264"];
+/** All supported video codecs. */
+export declare const videoCodecs: readonly ["vp8", "h264", "vp9", "av1", "h265"];
+/** Video codec identifier. */
+export type VideoCodec = (typeof videoCodecs)[number];
+/** Subset of video codecs that can serve as a backup codec. */
+export type BackupVideoCodec = (typeof backupVideoCodecs)[number];
+/**
+ * Returns `true` if the given codec string is a valid backup video codec.
+ */
+export declare function isBackupVideoCodec(codec: string): codec is BackupVideoCodec;
+/**
+ * Policy for handling backup codec behaviour when the primary codec is an
+ * advanced codec (VP9 / AV1 / H265).
+ */
+export declare enum BackupCodecPolicy {
+    /**
+     * Codec regression is preferred — the SFU will try to regress codec if
+     * possible but it is not guaranteed.
+     */
+    PREFER_REGRESSION = 0,
+    /** Multi-codec simulcast: publish both primary and backup codec simultaneously. */
+    SIMULCAST = 1,
+    /** Always use backup codec only. */
+    REGRESSION = 2
+}
+/**
+ * Scalability modes for SVC (Scalable Video Coding).
+ *
+ * @see https://www.w3.org/TR/webrtc-svc/#scalabilitymodes
+ */
+export type ScalabilityMode = 'L1T1' | 'L1T2' | 'L1T3' | 'L2T1' | 'L2T1h' | 'L2T1_KEY' | 'L2T2' | 'L2T2h' | 'L2T2_KEY' | 'L2T3' | 'L2T3h' | 'L2T3_KEY' | 'L3T1' | 'L3T1h' | 'L3T1_KEY' | 'L3T2' | 'L3T2h' | 'L3T2_KEY' | 'L3T3' | 'L3T3h' | 'L3T3_KEY';
+/**
+ * Codec-specific options that map to SDP `fmtp` parameters for the
+ * selected codec.
+ */
+export interface PublishCodecOptions {
+    opusStereo?: boolean;
+    opusFec?: boolean;
+    opusDtx?: boolean;
+    opusMaxPlaybackRate?: number;
+    opusMaxAverageBitrate?: number;
+    opusPtime?: number;
+    opusNack?: boolean;
+    videoGoogleStartBitrate?: number;
+    videoGoogleMaxBitrate?: number;
+    videoGoogleMinBitrate?: number;
+}
+/**
+ * Default parameters applied when publishing a track. These can be set once
+ * on {@link RoomOptions.publishDefaults} and will be used for every subsequent
+ * publish call unless overridden per-track.
+ */
+export interface TrackPublishDefaults {
+    /**
+     * Encoding parameters for camera track.
+     */
+    videoEncoding?: VideoEncoding;
+    /**
+     * Advanced codecs (VP9 / AV1 / H265) are not supported by all browser
+     * clients. When `backupCodec` is set and an incompatible client attempts
+     * to subscribe, the server will automatically publish a secondary track
+     * encoded with the backup codec.
+     *
+     * You can customize the encoding parameters of the backup track by
+     * explicitly setting codec and encoding fields.
+     *
+     * @defaultValue `true`
+     */
+    backupCodec?: true | false | {
+        codec: BackupVideoCodec;
+        encoding?: VideoEncoding;
+    };
+    /**
+     * Policy for deciding whether to send the primary codec at the same time
+     * as the backup codec.
+     *
+     * @see {@link BackupCodecPolicy}
+     */
+    backupCodecPolicy?: BackupCodecPolicy;
+    /**
+     * Encoding parameters for screen share tracks.
+     */
+    screenShareEncoding?: VideoEncoding;
+    /**
+     * Video codec, defaults to `'vp8'`. For SVC codecs, auto-enable `'vp8'`
+     * as backup.
+     */
+    videoCodec?: VideoCodec;
+    /**
+     * Which audio preset should be used for publishing audio tracks.
+     *
+     * @defaultValue {@link AudioPresets.music}
+     */
+    audioPreset?: AudioPreset;
+    /**
+     * DTX (Discontinuous Transmission of audio). Enabled by default for mono
+     * tracks.
+     */
+    dtx?: boolean;
+    /**
+     * RED (Redundant Encoding for audio). Enabled by default for mono tracks.
+     * When using stereo, RED is automatically disabled unless explicitly set.
+     */
+    red?: boolean;
+    /**
+     * Publish track in stereo mode (or set to `false` to disable). Default is
+     * determined by the capture channel count.
+     */
+    forceStereo?: boolean;
+    /**
+     * Use simulcast. Defaults to `true`.
+     *
+     * When using simulcast, the SDK will publish up to three versions of the
+     * stream at various resolutions.
+     */
+    simulcast?: boolean;
+    /**
+     * Scalability mode for SVC codecs, defaults to `'L3T3_KEY'`.
+     * When an SVC codec is used, simulcast is disabled.
+     */
+    scalabilityMode?: ScalabilityMode;
+    /**
+     * Degradation preference hint for the browser encoder.
+     */
+    degradationPreference?: RTCDegradationPreference;
+    /**
+     * Up to two additional simulcast layers to publish in addition to the
+     * original track.
+     *
+     * When left blank, it defaults to `[VideoPresets.h180, VideoPresets.h360]`.
+     * If an SVC codec is used (VP9 or AV1), this field has no effect.
+     *
+     * @example
+     * ```ts
+     * {
+     *   videoEncoding: { maxBitrate: 1_700_000, maxFramerate: 30 },
+     *   videoSimulcastLayers: [VideoPresets.h540, VideoPresets.h216],
+     * }
+     * ```
+     */
+    videoSimulcastLayers?: VideoPreset[];
+    /**
+     * Custom simulcast layers for screen share tracks.
+     *
+     * Note: layers should be ordered from lowest to highest quality.
+     */
+    screenShareSimulcastLayers?: VideoPreset[];
+    /**
+     * For local tracks, stop the underlying `MediaStreamTrack` when the track
+     * is muted (or paused). On some platforms this is necessary to disable the
+     * microphone recording indicator.
+     *
+     * Note: when enabled with Bluetooth devices connected, they will
+     * transition between profiles (e.g. HFP to A2DP) causing an audible
+     * difference in playback.
+     *
+     * @defaultValue `false`
+     */
+    stopMicTrackOnMute?: boolean;
+    /**
+     * Codec-specific options (SDP `fmtp` parameters) forwarded to the
+     * underlying transport layer.
+     *
+     * @see {@link PublishCodecOptions}
+     */
+    codecOptions?: PublishCodecOptions;
+    /**
+     * should local track be stopped when they are unpublished. defaults to false
+     * set this to true if you would prefer to clean up unpublished local track automatically.
+     */
+    stopTrackOnUnpublish?: boolean;
+}
+/**
+ * Options when publishing tracks. Extends {@link TrackPublishDefaults} with
+ * per-track metadata.
+ */
+export interface TrackPublishOptions extends TrackPublishDefaults {
+    /**
+     * A human-readable name for the track.
+     */
+    name?: string;
+    /**
+     * Source of track — camera, microphone, or screen.
+     */
+    source?: TrackSource;
+    /**
+     * Set a stream name for the track. Audio and video tracks with the same
+     * stream name will be placed in the same `MediaStream` and offer better
+     * synchronisation.
+     *
+     * By default, camera and microphone are placed in one stream; screen share
+     * video and audio in another.
+     */
+    stream?: string;
+    /**
+     * Target audio bitrate in bits per second.
+     */
+    audioBitrate?: number;
+}
+/**
+ * Options for publishing data via a DataChannel.
+ */
+export interface DataPublishOptions {
+    /** A human-readable name for the data track. */
+    name?: string;
+    /** DataChannel label. */
+    label?: string;
+    /** Whether messages should be delivered in order. */
+    ordered?: boolean;
+    /** Maximum number of retransmissions. */
+    maxRetransmits?: number;
+    /** Maximum packet lifetime in milliseconds. */
+    maxPacketLifeTime?: number;
+}
+/**
+ * Options accepted by {@link createLocalTracks}.
+ */
+export interface CreateLocalTracksOptions {
+    /**
+     * Audio track options. `true` to create with defaults, `false` to skip.
+     *
+     * @defaultValue `true`
+     */
+    audio?: boolean | AudioCaptureOptions;
+    /**
+     * Video track options. `true` to create with defaults, `false` to skip.
+     *
+     * @defaultValue `true`
+     */
+    video?: boolean | VideoCaptureOptions;
+}
+/**
+ * Default camera capture options: 720p @ 30 fps.
+ */
+export declare const defaultVideoCaptureOptions: VideoCaptureOptions;
+/**
+ * Default microphone capture options with echo cancellation, noise
+ * suppression and automatic gain control enabled.
+ */
+export declare const defaultAudioCaptureOptions: AudioCaptureOptions;
+/**
+ * Default video encoding: 720p @ 30 fps, 1.7 Mbps.
+ */
+export declare const defaultVideoEncoding: VideoEncoding;
+/**
+ * Default screen share encoding: 1080p @ 30 fps, 3 Mbps.
+ */
+export declare const defaultScreenShareEncoding: VideoEncoding;
+/**
+ * Pre-defined audio encoding presets.
+ */
+export declare const AudioPresets: {
+    /** 12 kbps — suitable for telephone-quality speech. */
+    readonly telephone: AudioPreset;
+    /** 24 kbps — good quality speech. */
+    readonly speech: AudioPreset;
+    /** 48 kbps — music quality (mono). */
+    readonly music: AudioPreset;
+    /** 64 kbps — music quality (stereo). */
+    readonly musicStereo: AudioPreset;
+    /** 96 kbps — high quality music (mono). */
+    readonly musicHighQuality: AudioPreset;
+    /** 128 kbps — high quality music (stereo). */
+    readonly musicHighQualityStereo: AudioPreset;
+};
+/**
+ * Pre-defined 16 : 9 video resolution / encoding presets.
+ */
+export declare const VideoPresets: {
+    readonly h90: VideoPreset;
+    readonly h180: VideoPreset;
+    readonly h216: VideoPreset;
+    readonly h360: VideoPreset;
+    readonly h540: VideoPreset;
+    readonly h720: VideoPreset;
+    readonly h1080: VideoPreset;
+    readonly h1440: VideoPreset;
+    readonly h2160: VideoPreset;
+};
+/**
+ * Pre-defined 4 : 3 video resolution / encoding presets.
+ */
+export declare const VideoPresets43: {
+    readonly h120: VideoPreset;
+    readonly h180: VideoPreset;
+    readonly h240: VideoPreset;
+    readonly h360: VideoPreset;
+    readonly h480: VideoPreset;
+    readonly h540: VideoPreset;
+    readonly h720: VideoPreset;
+    readonly h1080: VideoPreset;
+    readonly h1440: VideoPreset;
+};
+/**
+ * Pre-defined screen share resolution / encoding presets.
+ */
+export declare const ScreenSharePresets: {
+    readonly h360fps3: VideoPreset;
+    readonly h360fps15: VideoPreset;
+    readonly h720fps5: VideoPreset;
+    readonly h720fps15: VideoPreset;
+    readonly h720fps30: VideoPreset;
+    readonly h1080fps15: VideoPreset;
+    readonly h1080fps30: VideoPreset;
+    /** Original resolution, no resizing applied. */
+    readonly original: VideoPreset;
+};
+/**
+ * Simulcast encoding presets used internally for building default
+ * simulcast layers.
+ */
+export declare const videoSimulcastPresets: {
+    h180: VideoEncoding;
+    h360: VideoEncoding;
+    h720: VideoEncoding;
+    h1080: VideoEncoding;
+};
+export {};

package/dist/track/processor/types.d.ts

@@ -0,0 +1,49 @@
+import type { TrackKind } from '../../protocol/types';
+/**
+ * Options provided to a track processor during initialization.
+ *
+ * @experimental
+ */
+export interface ProcessorOptions<T extends TrackKind = TrackKind> {
+    kind: T;
+    track: MediaStreamTrack;
+    element?: HTMLMediaElement;
+    audioContext?: AudioContext;
+}
+/**
+ * A track processor transforms a `MediaStreamTrack` before publishing.
+ *
+ * Implementors must provide at least `init`, `restart`, and `destroy`.
+ * The SDK calls these methods at the appropriate lifecycle moments.
+ *
+ * After `init` (and `restart`), the processor MUST set `processedTrack`
+ * to the transformed output track. The SDK will publish this track instead
+ * of the original.
+ *
+ * @experimental
+ */
+export interface TrackProcessor<T extends TrackKind = TrackKind> {
+    /** Human-readable processor name (for logging/debugging). */
+    name: string;
+    /**
+     * Initialize the processor with the given options. After this call,
+     * `processedTrack` must be set.
+     */
+    init: (opts: ProcessorOptions<T>) => Promise<void>;
+    /**
+     * Restart the processor (e.g. when the source track changes). The
+     * implementation should release old resources and re-initialize with the
+     * new options.
+     */
+    restart: (opts: ProcessorOptions<T>) => Promise<void>;
+    /**
+     * Destroy the processor and release all resources. After calling this,
+     * `processedTrack` should be `undefined`.
+     */
+    destroy: () => Promise<void>;
+    /**
+     * The transformed output track. Must be set after `init` / `restart`.
+     * The SDK publishes this track instead of the original source.
+     */
+    processedTrack?: MediaStreamTrack;
+}

package/dist/track/publishUtils.d.ts

@@ -0,0 +1,14 @@
+import type { TrackPublishOptions, VideoCodec, VideoEncoding } from './options';
+import { TrackSource } from '../protocol/types';
+export declare function isSVCCodec(codec?: string): boolean;
+export declare function determineAppropriateEncoding(isScreenShare: boolean, width: number, height: number, codec?: VideoCodec): VideoEncoding;
+/**
+ * Compute video encodings for publishing based on the current track source,
+ * dimensions, and publish options. Handles simulcast layers and SVC modes.
+ */
+export declare function computeVideoEncodings(isScreenShare: boolean, width?: number, height?: number, options?: TrackPublishOptions): RTCRtpEncodingParameters[];
+/**
+ * Returns the default degradation preference for a video track based on its
+ * source and resolution constraints.
+ */
+export declare function getDefaultDegradationPreference(source: TrackSource, constraints?: MediaTrackConstraints): RTCDegradationPreference;

package/dist/transport/TransportManager.d.ts

@@ -0,0 +1,62 @@
+import * as mediasoupClient from 'mediasoup-client';
+import { types as mediasoupTypes } from 'mediasoup-client';
+import { TypedEmitter } from '../utils/typedEmitter';
+import { SignalClient } from '../signal/SignalClient';
+import type { JoinResponse, DtlsFingerprint, IceParameters } from '../protocol/types';
+export type ProduceCallback = (params: {
+    kind: mediasoupTypes.MediaKind;
+    rtpParameters: mediasoupTypes.RtpParameters;
+    appData: Record<string, unknown>;
+}, callback: (response: {
+    id: string;
+}) => void, errback: (error: Error) => void) => void;
+export type ProduceDataCallback = (params: {
+    sctpStreamParameters: mediasoupTypes.SctpStreamParameters;
+    label?: string;
+    protocol?: string;
+    appData: Record<string, unknown>;
+}, callback: (response: {
+    id: string;
+}) => void, errback: (error: Error) => void) => void;
+export type TransportEvents = {
+    signalReady: (sendDC: mediasoupTypes.DataProducer, recvDC: mediasoupTypes.DataConsumer) => void;
+    connectionFailed: (direction: 'send' | 'recv') => void;
+    closed: () => void;
+};
+export declare class TransportManager extends TypedEmitter<TransportEvents> {
+    device: mediasoupClient.Device;
+    sendTransport: mediasoupTypes.Transport | null;
+    recvTransport: mediasoupTypes.Transport | null;
+    signalDataProducer: mediasoupTypes.DataProducer | null;
+    signalDataConsumer: mediasoupTypes.DataConsumer | null;
+    private url;
+    private signalClient;
+    private hasDtlsFingerprints;
+    private joinResponse;
+    private certificate;
+    private pendingProduceCallbacks;
+    private pendingProduceDataCallbacks;
+    constructor(signalClient: SignalClient);
+    registerProduceCallback(clientTrackId: string, cb: ProduceCallback): void;
+    registerProduceDataCallback(clientTrackId: string, cb: ProduceDataCallback): void;
+    generateCertificate(): Promise<DtlsFingerprint[]>;
+    getCertificate(): RTCCertificate | null;
+    /** Used when replacing TransportManager (full reconnect) so DTLS matches join fingerprints. */
+    setCertificate(cert: RTCCertificate | null): void;
+    getDtlsFingerprints(): DtlsFingerprint[];
+    setup(url: string, joinResponse: JoinResponse, hasDtlsFingerprints: boolean, rtcConfig?: RTCConfiguration): Promise<void>;
+    restartIce(iceParamsMap: Record<string, IceParameters>): Promise<void>;
+    /**
+     * Returns WebRTC stats for the send and/or receive transports.
+     */
+    getStats(): Promise<{
+        send?: RTCStatsReport;
+        recv?: RTCStatsReport;
+    }>;
+    close(): void;
+    private setupTransportEvents;
+    private connectTransports;
+    private setupSignalChannels;
+    private static readonly DC_OPEN_TIMEOUT;
+    private waitForDataChannelOpen;
+}