@furious.luke/argus-js 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,224 @@
+/**
+ * Message types exchanged over the WebSocket signaling channel.
+ */
+type SignalMessage = {
+    type: "offer";
+    sdp: string;
+    sdp_type: "offer";
+} | {
+    type: "answer";
+    sdp: string;
+    sdp_type: "answer";
+} | {
+    type: "ice_candidate";
+    candidate: string;
+    sdp_mid?: string;
+    sdp_mline_index?: number;
+    username_fragment?: string;
+} | {
+    type: "connection_state";
+    state: string;
+} | {
+    type: "error";
+    error: string;
+} | {
+    type: "accepted";
+} | {
+    type: "proceed";
+} | {
+    type: "ready";
+    turn_url?: string;
+    turn_username?: string;
+    turn_credential?: string;
+    read_token?: string;
+};
+/**
+ * Callbacks emitted by the Publisher during its lifecycle.
+ */
+interface PublisherCallbacks {
+    /** Called when the WebRTC peer connection state changes. */
+    onConnectionStateChange?: (state: RTCPeerConnectionState) => void;
+    /** Called when a fatal error occurs (e.g. signaling error, WebSocket close). */
+    onError?: (error: Error) => void;
+    /** Called when the browser has successfully connected to the media server. */
+    onConnected?: () => void;
+}
+/**
+ * TURN and read-token info delivered in the gateway `ready` message.
+ */
+interface GatewayReadyInfo {
+    turn_url?: string;
+    turn_username?: string;
+    turn_credential?: string;
+    read_token?: string;
+}
+/**
+ * Options for publishing a media stream.
+ */
+interface PublisherOptions {
+    /** Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are raced simultaneously. */
+    gatewayURLs: string[];
+    /** The short-lived join token from POST /api/streams. */
+    token: string;
+    /** Optional extra ICE servers (e.g. STUN). TURN is supplied by the winning gateway. */
+    iceServers?: RTCIceServer[];
+    /** Callbacks for lifecycle events. */
+    callbacks?: PublisherCallbacks;
+}
+
+/**
+ * Publisher streams a browser {@link MediaStream} to an Argus media server over
+ * WebRTC. Given the `gateway_urls` and `token` from a join-token response, it
+ * races the candidate gateways to the fastest one, completes the two-phase
+ * signaling handshake, and manages the peer connection — offer/answer exchange,
+ * ICE candidate trickling, and track (re)negotiation.
+ *
+ * After {@link Publisher.start} resolves, {@link Publisher.frameReadToken} holds
+ * the token your application server needs to fetch frames for this stream.
+ *
+ * @example Publish the default camera:
+ * ```ts
+ * const pub = new Publisher({
+ *   gatewayURLs: joinResp.gateway_urls,
+ *   token: joinResp.token,
+ *   callbacks: { onConnected: () => console.log("live!") },
+ * });
+ *
+ * const stream = await navigator.mediaDevices.getUserMedia({ video: true });
+ * await pub.start(stream);
+ * ```
+ */
+declare class Publisher {
+    private opts;
+    private sig;
+    private pc;
+    private hasAnswer;
+    private pendingRemoteCandidates;
+    private localStream;
+    private readToken;
+    constructor(opts: PublisherOptions);
+    /** The read token received from the gateway after connecting, for fetching frames. */
+    get frameReadToken(): string | null;
+    /**
+     * Starts the publisher: races all gateways to find the fastest, completes
+     * the two-phase handshake, creates the peer connection, and sends the SDP
+     * offer. Resolves when the offer has been sent (not when ICE completes —
+     * use onConnected for that).
+     */
+    start(stream: MediaStream): Promise<void>;
+    /** Replaces the currently published stream with a new one. */
+    replaceStream(stream: MediaStream): Promise<void>;
+    /** Stops publishing and tears down the peer connection. */
+    stop(): void;
+    /** Returns the current RTCPeerConnection, or null if not started. */
+    get peerConnection(): RTCPeerConnection | null;
+    /** Returns true if the peer connection is in the "connected" state. */
+    get isConnected(): boolean;
+    private raceGateways;
+    private handleSignal;
+    /** Waits for ICE gathering to reach the "complete" state. */
+    private gatherComplete;
+}
+
+/**
+ * Options for {@link captureCamera}.
+ *
+ * These are merged shallowly over the library defaults: any field you provide
+ * replaces the default for that field entirely (e.g. passing `video` overrides
+ * the default video constraints rather than merging into them). Omit a field to
+ * keep its default.
+ */
+interface CaptureCameraOptions {
+    /**
+     * Video constraints, or `true`/`false`. Defaults to a modest resolution and
+     * frame rate (see {@link captureCamera}). Set `false` to disable video.
+     */
+    video?: MediaTrackConstraints | boolean;
+    /**
+     * Audio constraints, or `true`/`false`. Defaults to `false` — Argus is a
+     * video-frame streaming system, so audio is off unless you ask for it.
+     */
+    audio?: MediaTrackConstraints | boolean;
+}
+/**
+ * Options for {@link captureScreen}.
+ *
+ * These are merged shallowly over the library defaults: any field you provide
+ * replaces the default for that field entirely. Omit a field to keep its
+ * default.
+ */
+interface CaptureScreenOptions {
+    /**
+     * Video constraints, or `true`. Defaults to a capped width and a low frame
+     * rate (see {@link captureScreen}).
+     */
+    video?: MediaTrackConstraints | boolean;
+    /**
+     * Audio constraints, or `true`/`false`. Defaults to `false` — screen shares
+     * rarely need audio for a video-frame streaming system.
+     */
+    audio?: MediaTrackConstraints | boolean;
+}
+/**
+ * Captures the user's camera via `navigator.mediaDevices.getUserMedia`,
+ * applying sensible defaults for a video-frame streaming system.
+ *
+ * Defaults:
+ * - `video`: `{ width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30 } }`
+ *   — a modest resolution that keeps upload bandwidth reasonable. Cameras are
+ *   rarely the 4k bandwidth problem that screen capture is, so this is an
+ *   `ideal` (a hint) rather than a hard cap.
+ * - `audio`: `false` — this is a video-frame streaming system.
+ *
+ * Any option you pass replaces the corresponding default outright (shallow
+ * merge), so pass a full `video` constraints object if you want to tweak it.
+ *
+ * @example
+ * ```ts
+ * const stream = await captureCamera();
+ * await publisher.start(stream);
+ * ```
+ *
+ * @example Front camera with audio:
+ * ```ts
+ * const stream = await captureCamera({
+ *   video: { facingMode: "user" },
+ *   audio: true,
+ * });
+ * ```
+ */
+declare function captureCamera(opts?: CaptureCameraOptions): Promise<MediaStream>;
+/**
+ * Captures a screen / window / tab via
+ * `navigator.mediaDevices.getDisplayMedia`, applying sensible defaults tuned to
+ * avoid the HiDPI/Retina bandwidth trap.
+ *
+ * Defaults:
+ * - `video`: `{ width: { max: 1920 }, frameRate: { ideal: 5, max: 10 } }`.
+ *   The `width` is a **`max`, not an `ideal`**: on a 2x-Retina display the
+ *   browser would otherwise capture at native resolution (often 3456px+ /
+ *   effectively 4k), wasting upload bandwidth and downstream decode cost for no
+ *   visible benefit. Capping the max roughly halves a 2x-Retina share while
+ *   leaving smaller displays untouched. Screen content is mostly static, so the
+ *   low frame rate saves further bandwidth.
+ * - `audio`: `false`.
+ *
+ * IMPORTANT — do NOT add `resizeMode: "none"` here. That value forbids the
+ * browser from downscaling the source, which turns the `width: { max: 1920 }`
+ * cap into a no-op on exactly the Retina displays it targets. By omitting
+ * `resizeMode` we let the user agent scale to satisfy the constraint (its
+ * default behaviour), which is the entire point of this helper. It is tempting
+ * to add `resizeMode: "none"` back for "sharpness" — don't.
+ *
+ * Any option you pass replaces the corresponding default outright (shallow
+ * merge), so pass a full `video` constraints object if you want to tweak it.
+ *
+ * @example
+ * ```ts
+ * const stream = await captureScreen();
+ * await publisher.start(stream);
+ * ```
+ */
+declare function captureScreen(opts?: CaptureScreenOptions): Promise<MediaStream>;
+
+export { type CaptureCameraOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type SignalMessage, captureCamera, captureScreen };

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Message types exchanged over the WebSocket signaling channel.
+ */
+type SignalMessage = {
+    type: "offer";
+    sdp: string;
+    sdp_type: "offer";
+} | {
+    type: "answer";
+    sdp: string;
+    sdp_type: "answer";
+} | {
+    type: "ice_candidate";
+    candidate: string;
+    sdp_mid?: string;
+    sdp_mline_index?: number;
+    username_fragment?: string;
+} | {
+    type: "connection_state";
+    state: string;
+} | {
+    type: "error";
+    error: string;
+} | {
+    type: "accepted";
+} | {
+    type: "proceed";
+} | {
+    type: "ready";
+    turn_url?: string;
+    turn_username?: string;
+    turn_credential?: string;
+    read_token?: string;
+};
+/**
+ * Callbacks emitted by the Publisher during its lifecycle.
+ */
+interface PublisherCallbacks {
+    /** Called when the WebRTC peer connection state changes. */
+    onConnectionStateChange?: (state: RTCPeerConnectionState) => void;
+    /** Called when a fatal error occurs (e.g. signaling error, WebSocket close). */
+    onError?: (error: Error) => void;
+    /** Called when the browser has successfully connected to the media server. */
+    onConnected?: () => void;
+}
+/**
+ * TURN and read-token info delivered in the gateway `ready` message.
+ */
+interface GatewayReadyInfo {
+    turn_url?: string;
+    turn_username?: string;
+    turn_credential?: string;
+    read_token?: string;
+}
+/**
+ * Options for publishing a media stream.
+ */
+interface PublisherOptions {
+    /** Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are raced simultaneously. */
+    gatewayURLs: string[];
+    /** The short-lived join token from POST /api/streams. */
+    token: string;
+    /** Optional extra ICE servers (e.g. STUN). TURN is supplied by the winning gateway. */
+    iceServers?: RTCIceServer[];
+    /** Callbacks for lifecycle events. */
+    callbacks?: PublisherCallbacks;
+}
+
+/**
+ * Publisher streams a browser {@link MediaStream} to an Argus media server over
+ * WebRTC. Given the `gateway_urls` and `token` from a join-token response, it
+ * races the candidate gateways to the fastest one, completes the two-phase
+ * signaling handshake, and manages the peer connection — offer/answer exchange,
+ * ICE candidate trickling, and track (re)negotiation.
+ *
+ * After {@link Publisher.start} resolves, {@link Publisher.frameReadToken} holds
+ * the token your application server needs to fetch frames for this stream.
+ *
+ * @example Publish the default camera:
+ * ```ts
+ * const pub = new Publisher({
+ *   gatewayURLs: joinResp.gateway_urls,
+ *   token: joinResp.token,
+ *   callbacks: { onConnected: () => console.log("live!") },
+ * });
+ *
+ * const stream = await navigator.mediaDevices.getUserMedia({ video: true });
+ * await pub.start(stream);
+ * ```
+ */
+declare class Publisher {
+    private opts;
+    private sig;
+    private pc;
+    private hasAnswer;
+    private pendingRemoteCandidates;
+    private localStream;
+    private readToken;
+    constructor(opts: PublisherOptions);
+    /** The read token received from the gateway after connecting, for fetching frames. */
+    get frameReadToken(): string | null;
+    /**
+     * Starts the publisher: races all gateways to find the fastest, completes
+     * the two-phase handshake, creates the peer connection, and sends the SDP
+     * offer. Resolves when the offer has been sent (not when ICE completes —
+     * use onConnected for that).
+     */
+    start(stream: MediaStream): Promise<void>;
+    /** Replaces the currently published stream with a new one. */
+    replaceStream(stream: MediaStream): Promise<void>;
+    /** Stops publishing and tears down the peer connection. */
+    stop(): void;
+    /** Returns the current RTCPeerConnection, or null if not started. */
+    get peerConnection(): RTCPeerConnection | null;
+    /** Returns true if the peer connection is in the "connected" state. */
+    get isConnected(): boolean;
+    private raceGateways;
+    private handleSignal;
+    /** Waits for ICE gathering to reach the "complete" state. */
+    private gatherComplete;
+}
+
+/**
+ * Options for {@link captureCamera}.
+ *
+ * These are merged shallowly over the library defaults: any field you provide
+ * replaces the default for that field entirely (e.g. passing `video` overrides
+ * the default video constraints rather than merging into them). Omit a field to
+ * keep its default.
+ */
+interface CaptureCameraOptions {
+    /**
+     * Video constraints, or `true`/`false`. Defaults to a modest resolution and
+     * frame rate (see {@link captureCamera}). Set `false` to disable video.
+     */
+    video?: MediaTrackConstraints | boolean;
+    /**
+     * Audio constraints, or `true`/`false`. Defaults to `false` — Argus is a
+     * video-frame streaming system, so audio is off unless you ask for it.
+     */
+    audio?: MediaTrackConstraints | boolean;
+}
+/**
+ * Options for {@link captureScreen}.
+ *
+ * These are merged shallowly over the library defaults: any field you provide
+ * replaces the default for that field entirely. Omit a field to keep its
+ * default.
+ */
+interface CaptureScreenOptions {
+    /**
+     * Video constraints, or `true`. Defaults to a capped width and a low frame
+     * rate (see {@link captureScreen}).
+     */
+    video?: MediaTrackConstraints | boolean;
+    /**
+     * Audio constraints, or `true`/`false`. Defaults to `false` — screen shares
+     * rarely need audio for a video-frame streaming system.
+     */
+    audio?: MediaTrackConstraints | boolean;
+}
+/**
+ * Captures the user's camera via `navigator.mediaDevices.getUserMedia`,
+ * applying sensible defaults for a video-frame streaming system.
+ *
+ * Defaults:
+ * - `video`: `{ width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30 } }`
+ *   — a modest resolution that keeps upload bandwidth reasonable. Cameras are
+ *   rarely the 4k bandwidth problem that screen capture is, so this is an
+ *   `ideal` (a hint) rather than a hard cap.
+ * - `audio`: `false` — this is a video-frame streaming system.
+ *
+ * Any option you pass replaces the corresponding default outright (shallow
+ * merge), so pass a full `video` constraints object if you want to tweak it.
+ *
+ * @example
+ * ```ts
+ * const stream = await captureCamera();
+ * await publisher.start(stream);
+ * ```
+ *
+ * @example Front camera with audio:
+ * ```ts
+ * const stream = await captureCamera({
+ *   video: { facingMode: "user" },
+ *   audio: true,
+ * });
+ * ```
+ */
+declare function captureCamera(opts?: CaptureCameraOptions): Promise<MediaStream>;
+/**
+ * Captures a screen / window / tab via
+ * `navigator.mediaDevices.getDisplayMedia`, applying sensible defaults tuned to
+ * avoid the HiDPI/Retina bandwidth trap.
+ *
+ * Defaults:
+ * - `video`: `{ width: { max: 1920 }, frameRate: { ideal: 5, max: 10 } }`.
+ *   The `width` is a **`max`, not an `ideal`**: on a 2x-Retina display the
+ *   browser would otherwise capture at native resolution (often 3456px+ /
+ *   effectively 4k), wasting upload bandwidth and downstream decode cost for no
+ *   visible benefit. Capping the max roughly halves a 2x-Retina share while
+ *   leaving smaller displays untouched. Screen content is mostly static, so the
+ *   low frame rate saves further bandwidth.
+ * - `audio`: `false`.
+ *
+ * IMPORTANT — do NOT add `resizeMode: "none"` here. That value forbids the
+ * browser from downscaling the source, which turns the `width: { max: 1920 }`
+ * cap into a no-op on exactly the Retina displays it targets. By omitting
+ * `resizeMode` we let the user agent scale to satisfy the constraint (its
+ * default behaviour), which is the entire point of this helper. It is tempting
+ * to add `resizeMode: "none"` back for "sharpness" — don't.
+ *
+ * Any option you pass replaces the corresponding default outright (shallow
+ * merge), so pass a full `video` constraints object if you want to tweak it.
+ *
+ * @example
+ * ```ts
+ * const stream = await captureScreen();
+ * await publisher.start(stream);
+ * ```
+ */
+declare function captureScreen(opts?: CaptureScreenOptions): Promise<MediaStream>;
+
+export { type CaptureCameraOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type SignalMessage, captureCamera, captureScreen };