@remavideo/sdk 0.9.0

package/dist/index.d.ts

@@ -0,0 +1,1020 @@
+import { HealthStatus, NodeState, ActivationGate, TrackInfo, NodeEventMsg, MonitorEventMsg, WorkflowInfo } from '@remavideo/server';
+export { AppRouter, HealthStatus, MonitorDescriptorMsg, MonitorEventMsg, NodeEventKind, NodeNotificationKind, NodeState, PipelineSnapshot, TrackInfo, VisEdge, VisNode, WorkflowInfo, WorkflowResourceUsageMsg } from '@remavideo/server';
+import { createTRPCClient } from '@trpc/client';
+
+interface RemaClientOptions {
+    host?: string;
+    port?: number;
+    onLogEvent?: (log: {
+        level: string;
+        message: string;
+    }) => void;
+    onReady?: () => void;
+    onFailedToConnect?: () => void;
+}
+declare class RemaClient {
+    readonly trpc: ReturnType<typeof createTRPCClient<AppRouter>>;
+    readonly options: Required<Pick<RemaClientOptions, "host" | "port">>;
+    private constructor();
+    static connect(opts?: RemaClientOptions): Promise<RemaClient>;
+    /** No-op kept for API compatibility — SSE has no persistent connection to close. */
+    close(): void;
+    /** Fetches the server's health status from the plain HTTP `/api/health` endpoint. */
+    health(): Promise<HealthStatus>;
+}
+
+/** Lifecycle callbacks available on every node's settings object. */
+interface NodeCallbacks {
+    /** Called when the node transitions into the `ERROR` state. */
+    onError?: (err: Error) => void;
+    /** Called on every lifecycle state transition (`READY`, `ACTIVE`, `ENDED`, `ERROR`, `CLOSED`). */
+    onStatusChange?: (state: NodeState, message?: string) => void;
+    /** Called when the node closes — locally via `.close()`, or remotely (workflow close, crash). */
+    onClose?: () => void;
+}
+/**
+ * FFmpeg codec specification for one stream of a subscription.
+ *
+ * The receiving output node applies it where appropriate (e.g. per-rendition
+ * `-c:v:N`/`-c:a:N` for HLS, `-c:v`/`-c:a` for RTMP/File outputs). Omitted =
+ * stream copy.
+ */
+interface CodecSpec {
+    /** FFmpeg encoder name: `"copy"`, `"aac"`, `"libx264"`, … */
+    name: string;
+    /**
+     * Extra encoder options keyed by bare FFmpeg option name (no stream
+     * specifier), e.g. `{ preset: "veryfast", b: "3M" }`.
+     */
+    options?: Record<string, string | number>;
+}
+/**
+ * Audio rendition metadata for HLS output nodes. Sets the language tag and
+ * label that appear in the player's track menu. Ignored by non-HLS nodes.
+ */
+interface AudioRenditionOptions {
+    /** BCP-47 language tag, e.g. `"en"`, `"fr"`. Default: `"und"`. */
+    language?: string;
+    /** Label shown in player track menus. Default: `"Audio"`. */
+    label?: string;
+    /** Pre-select this track on first play. Default: `false`. */
+    defaultTrack?: boolean;
+}
+/**
+ * Video rendition metadata for HLS output nodes. Ignored by non-HLS nodes.
+ */
+interface VideoRenditionOptions {
+    /**
+     * Label used to name the HLS variant playlist/segments (sanitized to a
+     * URL-safe variant name).
+     */
+    label?: string;
+}
+/** Fields shared by every subscription variant. */
+interface SubscriptionSpecBase {
+    source: BaseNode;
+    /**
+     * Delay this stream by N milliseconds before it reaches the subscribing
+     * node (applied server-side). Typical use: delay the A/V subscriptions so
+     * a slower caption source has lead time.
+     */
+    delayMs?: number;
+    /**
+     * Read from a keyed output port of a multi-output source node (Gate).
+     * Ports are named by the `name` field of the specs the gate itself was
+     * subscribed with. Mutually exclusive with `track`.
+     */
+    port?: string;
+    /**
+     * When the *subscribing* node is a multi-output node (Gate), names the
+     * pass-through port it creates for this source (default: the source's
+     * index as a string). Ignored by other node types.
+     */
+    name?: string;
+}
+/** Subscribe to a video-only stream of a source node. */
+interface VideoSubscriptionSpec extends SubscriptionSpecBase {
+    sourceSelector: "VIDEO";
+    /**
+     * Per-type video track index within the source container (0 = first video
+     * track). Discover available indices with `await source.tracks()`.
+     * Default: 0.
+     */
+    track?: number;
+    /** Codec applied to the video stream by the receiving output node. */
+    codec?: CodecSpec;
+    /** Video rendition metadata (HLS). */
+    video?: VideoRenditionOptions;
+}
+/** Subscribe to an audio-only stream of a source node. */
+interface AudioSubscriptionSpec extends SubscriptionSpecBase {
+    sourceSelector: "AUDIO";
+    /**
+     * Per-type audio track index within the source container (0 = first audio
+     * track). Discover available indices with `await source.tracks()`.
+     * Default: 0.
+     */
+    track?: number;
+    /** Codec applied to the audio stream by the receiving output node. */
+    codec?: CodecSpec;
+    /** Audio rendition metadata (HLS). */
+    audio?: AudioRenditionOptions;
+}
+/** Subscribe to the combined A/V stream of a source node. */
+interface AllSubscriptionSpec extends SubscriptionSpecBase {
+    sourceSelector: "ALL";
+    /** Codec applied to the video track by the receiving output node. */
+    videoCodec?: CodecSpec;
+    /** Codec applied to the audio track by the receiving output node. */
+    audioCodec?: CodecSpec;
+    /** Video rendition metadata (HLS). */
+    video?: VideoRenditionOptions;
+    /** Audio rendition metadata (HLS). */
+    audio?: AudioRenditionOptions;
+}
+/** Subscribe to the caption stream of a source node. */
+interface CaptionsSubscriptionSpec extends SubscriptionSpecBase {
+    sourceSelector: "CAPTIONS";
+}
+/**
+ * One source wired into a subscribing node, discriminated by
+ * `sourceSelector` so per-stream options (codec, rendition metadata) are
+ * only available where they apply.
+ */
+type SubscriptionSpec = VideoSubscriptionSpec | AudioSubscriptionSpec | AllSubscriptionSpec | CaptionsSubscriptionSpec;
+/**
+ * Minimal interface passed to factory functions. Defined here (not in workflow.ts)
+ * to avoid a circular import: workflow.ts imports factory files, factory files
+ * import this interface.
+ */
+interface WorkflowHandle {
+    readonly workflowId: string;
+    readonly client: RemaClient;
+    _onNodeEvent(nodeId: string, handler: (evt: NodeEventMsg) => void): () => void;
+}
+/**
+ * Base class for all rema nodes.
+ * Provides the .subscribe() method that wires nodes together on the server.
+ */
+declare abstract class BaseNode {
+    readonly nodeId: string;
+    readonly workflowId: string;
+    protected readonly client: RemaClient;
+    private _eventCleanup;
+    private _callbacks;
+    constructor(nodeId: string, client: RemaClient, workflowId: string);
+    /** Called by create functions to register the workflow event handler cleanup. */
+    _setEventCleanup(fn: () => void): void;
+    /**
+     * Called by create functions to register the node's lifecycle callbacks
+     * (`onError`/`onStatusChange`/`onClose`), so `.close()` can invoke `onClose`
+     * directly on a locally-initiated close.
+     */
+    _bindCallbacks(callbacks: NodeCallbacks): void;
+    /**
+     * Subscribe this node to one or more source nodes.
+     * This tells the server to route streams from the sources into this node.
+     */
+    subscribe(specs: SubscriptionSpec[], options?: {
+        gate?: ActivationGate;
+    }): Promise<void>;
+    /** Map one `SubscriptionSpec` to the wire shape expected by the server. */
+    private static _toSourceInput;
+    /**
+     * Probe this node's media stream (ffprobe, server-side) and return its
+     * track list. Each entry's `track` is the per-type index to pass back as
+     * `track` in a VIDEO/AUDIO subscription:
+     *
+     * ```ts
+     * const tracks = await input.tracks();
+     * const ita = tracks.find((t) => t.type === "audio" && t.language === "ita");
+     * await output.subscribe([
+     *   { source: input, sourceSelector: "VIDEO" },
+     *   { source: input, sourceSelector: "AUDIO", track: ita!.track },
+     * ]);
+     * ```
+     *
+     * Probing consumes real-time-paced stream data, so it can take several
+     * seconds; `probeSizeBytes` (default 1 MB) trades discovery depth for
+     * latency. The server errors after ~15 s if the source produces no data
+     * (e.g. no publisher connected yet, or a disabled file input).
+     */
+    tracks(options?: {
+        probeSizeBytes?: number;
+    }): Promise<TrackInfo[]>;
+    /** Tear down this node on the server. */
+    close(): Promise<void>;
+}
+
+interface CaptionSourceSettings extends NodeCallbacks {
+    /**
+     * How many past caption entries to replay to an encoder that subscribes
+     * after some captions have already been sent.
+     *
+     * - `0` (default) — no replay; each encoder only receives captions sent
+     *   after it connects.  Correct for live captioning where old text is stale.
+     * - `Infinity` — replay the full history.  Use this when pre-scheduling
+     *   all captions upfront (e.g. from an SRT file) before the pipeline starts,
+     *   so encoders that activate later still see every entry.
+     * - `N` — replay the last N entries only.
+     */
+    replayCount?: number;
+    /**
+     * BCP-47 language tag written into the HLS master playlist when this caption
+     * source is wired as a subtitle track. Default: "und".
+     */
+    language?: string;
+    /** Human-readable track label shown in player subtitle menus. Default: "Subtitles". */
+    label?: string;
+    /** Whether this track is pre-selected when the player first loads. Default: true. */
+    defaultTrack?: boolean;
+    /**
+     * Maximum character length per caption line.  When set, captions whose text
+     * exceeds this length are automatically split into sequential chunks on the
+     * server.  Each chunk's display duration is proportional to its character
+     * count relative to the original caption's total duration.
+     */
+    maxLineLength?: number;
+}
+declare class CaptionSourceNode extends BaseNode {
+    readonly settings: CaptionSourceSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: CaptionSourceSettings);
+    /**
+     * Queue caption text for injection into the video stream.
+     *
+     * @param options.startAt   Stream-elapsed milliseconds (relative to the
+     *                          first video frame received by the server) at which
+     *                          to show the caption.  The server holds the text and
+     *                          injects it at the matching PTS, so you can schedule
+     *                          captions before that point in the stream is reached.
+     *                          Omit (or 0) to inject immediately at the next frame.
+     * @param options.duration  How long (ms) the caption stays visible before
+     *                          being automatically erased. Required.
+     */
+    send(text: string, options: {
+        duration: number;
+        startAt?: number;
+    }): Promise<void>;
+    /**
+     * Parse raw SRT or WebVTT content and schedule all entries on the server.
+     *
+     * Use `replayCount: Infinity` when creating this node if the pipeline may
+     * connect encoders after the captions are loaded.
+     *
+     * @returns The number of caption entries loaded.
+     */
+    sendFile(content: string): Promise<{
+        count: number;
+    }>;
+    /**
+     * Read a local SRT or WebVTT file and schedule all its entries on the server.
+     * The file is read client-side; only the content string is sent over the wire.
+     *
+     * @param filePath Absolute or relative path to the subtitle file.
+     * @returns The number of caption entries loaded.
+     */
+    sendFileByPath(filePath: string): Promise<{
+        count: number;
+    }>;
+}
+
+interface FileInputSettings extends NodeCallbacks {
+    /** Absolute path to the media file (MP4, TS, MKV, …) */
+    fileName: string;
+    /** Loop the file indefinitely. Default: false */
+    loop?: boolean;
+    /** Source name used to identify streams from this node */
+    sourceName?: string;
+    /**
+     * Start in a disabled state — the file is not read until `.enable()` is called
+     * (or the node is enabled from the web UI). Default: false.
+     */
+    disabled?: boolean;
+    /** Called when the node transitions to the enabled / ready state */
+    onReady?: () => void;
+    /**
+     * Called once when the first data packet from this input arrives at the server.
+     * Use this to convert absolute timestamps to the stream-relative `startAt`
+     * expected by `CaptionSourceNode.send()`:
+     *
+     * ```ts
+     * onStreamStart(wallClockMs) {
+     *   const startAt = myAbsoluteCaptionMs - wallClockMs;
+     *   await captions.send(text, { startAt });
+     * }
+     * ```
+     *
+     * @param wallClockMs  `Date.now()` on the server at the moment the first
+     *                     MPEG-TS data packet arrived from this input.
+     */
+    onStreamStart?: (wallClockMs: number) => void;
+    /** Called once the file has finished playing (reaches EOF). Never fires when `loop` is true. */
+    onEnded?: () => void;
+}
+declare class FileInputNode extends BaseNode {
+    readonly settings: FileInputSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: FileInputSettings);
+    /** Enable this node — starts reading the file and streaming to downstream nodes. */
+    enable(): Promise<void>;
+}
+
+interface NodeStreamInputSettings extends NodeCallbacks {
+    /**
+     * FFmpeg format identifier for the incoming audio data.
+     *
+     * Raw PCM examples: `"s16le"` (16-bit signed LE), `"f32le"` (32-bit float LE).
+     * Encoded examples: `"wav"`, `"mp3"`, `"aac"`, `"flac"`.
+     */
+    format: string;
+    /** Sample rate in Hz. Required when `format` is a raw PCM format. */
+    sampleRate?: number;
+    /** Number of audio channels. Required when `format` is a raw PCM format. */
+    channels?: number;
+    /**
+     * FFmpeg codec for the MPEG-TS output. Defaults to `"aac"`, which is safe
+     * for any input format. Use `"copy"` only when the input is already
+     * MPEG-TS-compatible AAC.
+     */
+    audioCodec?: string;
+    /** Human-readable label shown in the dashboard. */
+    label?: string;
+    /** Called when the node transitions to the ready state on the server. */
+    onReady?: () => void;
+    /**
+     * Called once when the first audio packet is written to the server.
+     * The argument is `Date.now()` on the server at that moment.
+     */
+    onStreamStart?: (wallClockMs: number) => void;
+    /** Called once the underlying FFmpeg process exits cleanly after `end()`. */
+    onEnded?: () => void;
+}
+declare class NodeStreamInputNode extends BaseNode {
+    readonly settings: NodeStreamInputSettings;
+    private readonly _apiBase;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: NodeStreamInputSettings);
+    /**
+     * Push an audio stream to the server.
+     *
+     * Accepts any `AsyncIterable<Buffer | Uint8Array>`, which includes Node.js
+     * `Readable` streams (async-iterable since Node 10) and async generators.
+     * The call resolves when the source iterable is exhausted or the server
+     * closes the connection.
+     *
+     * @example
+     * ```ts
+     * import { createReadStream } from "node:fs";
+     * await audioInput.stream(createReadStream("audio.mp3"));
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Raw PCM from a microphone via node-record-lpcm16
+     * const mic = recorder.start({ sampleRate: 16000, channels: 1 });
+     * await audioInput.stream(mic);
+     * ```
+     */
+    stream(source: AsyncIterable<Buffer | Uint8Array>): Promise<void>;
+}
+declare function createNodeStreamInputNode(workflow: WorkflowHandle, settings: NodeStreamInputSettings, nodeId?: string): Promise<NodeStreamInputNode>;
+
+/** Connection info passed to `onConnect` and `onDisconnect`. */
+interface RtmpConnectionInfo {
+    app: string;
+    sourceName: string;
+    /**
+     * MediaMTX connection id for this publisher, if it could be resolved at
+     * connect time. Pass directly to `operations.disconnectSource`.
+     */
+    connectionId?: string;
+}
+/** Operations available on a live RTMP publisher connection. */
+interface RtmpAnnouncerOperations {
+    /**
+     * Forcibly disconnect the connection identified by `connectionId`. Safe to
+     * call even if it already disconnected (resolves as a no-op).
+     */
+    disconnectSource(connectionId: string): Promise<void>;
+}
+interface RtmpAnnouncerSettings extends NodeCallbacks {
+    /** RTMP app name to watch (default: "live"). */
+    app?: string;
+    /**
+     * Called when a publisher connects. Create nodes in any workflow from
+     * here, or call `operations.disconnectSource(info.connectionId)` to kick
+     * the publisher synchronously (e.g. to reject an invalid `sourceName`).
+     */
+    onConnect: (info: RtmpConnectionInfo, operations: RtmpAnnouncerOperations) => void;
+    /** Called when a publisher disconnects. */
+    onDisconnect?: (info: RtmpConnectionInfo) => void;
+}
+/** SDK handle for an RTMP announcer node. */
+declare class RtmpAnnouncerNode extends BaseNode {
+    /**
+     * Forcibly disconnect the connection identified by `connectionId`. Can be
+     * called at any time after the node is created — e.g. from an async
+     * moderation decision made after `onConnect` already returned.
+     */
+    disconnectSource(connectionId: string): Promise<void>;
+}
+
+/**
+ * Represents a single active RTMP stream created by an `RtmpMultiplexerNode`.
+ *
+ * The server creates this node automatically when a publisher connects. The SDK
+ * wraps the server-side node ID so it can be passed as a source to downstream
+ * nodes (encoders, outputs) via `subscribe()`.
+ */
+declare class RtmpStreamNode extends BaseNode {
+    readonly app: string;
+    readonly sourceName: string;
+    constructor(nodeId: string, client: RemaClient, app: string, sourceName: string, workflowId: string);
+}
+/**
+ * SDK handle for an RTMP multiplexer node.
+ *
+ * Calling `close()` deactivates the multiplexer and all of its active stream
+ * nodes on the server.
+ */
+declare class RtmpMultiplexerNode extends BaseNode {
+}
+interface RtmpMultiplexerSettings extends NodeCallbacks {
+    /** RTMP app name to listen on (default: "live"). */
+    app?: string;
+    /**
+     * Called when a publisher connects. Return `{ accept: false }` to kick the
+     * connection immediately; return `{ accept: true }` or omit the return value
+     * to accept and trigger `onStream`.
+     */
+    onConnect?: (info: {
+        app: string;
+        sourceName: string;
+    }) => Promise<{
+        accept: boolean;
+    } | undefined> | {
+        accept: boolean;
+    } | undefined;
+    /**
+     * Called with the per-publisher `RtmpStreamNode` when a new RTMP stream is
+     * accepted. Create your downstream pipeline (encoders, outputs) from this node.
+     */
+    onStream: (node: RtmpStreamNode) => Promise<void> | void;
+    /**
+     * Called when a publisher disconnects or is rejected. Use this to close any
+     * downstream nodes you created in `onStream`.
+     */
+    onStreamEnd?: (node: RtmpStreamNode) => Promise<void> | void;
+}
+
+interface RtmpReaderSettings extends NodeCallbacks {
+    /** RTMP app name. */
+    app: string;
+    /** Source name (stream key). */
+    sourceName: string;
+    /** Called when an RTMP publisher connects. */
+    onPublish?: (info: {
+        app: string;
+        internalUrl: string;
+    }) => void;
+    /**
+     * Called once when the first data packet from this input arrives at the server.
+     * @param wallClockMs `Date.now()` on the server at the moment the first MPEG-TS packet arrived.
+     */
+    onStreamStart?: (wallClockMs: number) => void;
+    /** Called when the publisher disconnects (the underlying FFmpeg pull exits). */
+    onStreamEnded?: () => void;
+}
+declare class RtmpReaderNode extends BaseNode {
+    readonly settings: RtmpReaderSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: RtmpReaderSettings);
+}
+
+/** Connection info passed to `onConnect` and `onDisconnect`. */
+interface SrtConnectionInfo {
+    app: string;
+    sourceName: string;
+    /** Passphrase configured on the announcer, if any. */
+    passphrase?: string;
+    /** Negotiated SRT latency in milliseconds, if configured. */
+    latencyMs?: number;
+    /**
+     * MediaMTX connection id for this publisher, if it could be resolved at
+     * connect time. Pass directly to `operations.disconnectSource`.
+     */
+    connectionId?: string;
+}
+/** Operations available on a live SRT publisher connection. */
+interface SrtAnnouncerOperations {
+    /**
+     * Forcibly disconnect the connection identified by `connectionId`. Safe to
+     * call even if it already disconnected (resolves as a no-op).
+     */
+    disconnectSource(connectionId: string): Promise<void>;
+}
+interface SrtAnnouncerSettings extends NodeCallbacks {
+    /** SRT app name to watch (default: "live"). */
+    app?: string;
+    /** Passphrase to include in connection events (mirrors MediaMTX path config). */
+    passphrase?: string;
+    /** SRT latency in milliseconds to include in connection events. */
+    latencyMs?: number;
+    /**
+     * Called when a publisher connects. Create nodes in any workflow from
+     * here, or call `operations.disconnectSource(info.connectionId)` to kick
+     * the publisher synchronously (e.g. to reject an invalid `sourceName`).
+     */
+    onConnect: (info: SrtConnectionInfo, operations: SrtAnnouncerOperations) => void;
+    /** Called when a publisher disconnects. */
+    onDisconnect?: (info: Pick<SrtConnectionInfo, "app" | "sourceName">) => void;
+}
+/** SDK handle for an SRT announcer node. */
+declare class SrtAnnouncerNode extends BaseNode {
+    /**
+     * Forcibly disconnect the connection identified by `connectionId`. Can be
+     * called at any time after the node is created — e.g. from an async
+     * moderation decision made after `onConnect` already returned.
+     */
+    disconnectSource(connectionId: string): Promise<void>;
+}
+
+interface SrtReaderSettings extends NodeCallbacks {
+    /** SRT app name. */
+    app: string;
+    /** Source name (stream key / stream ID suffix). */
+    sourceName: string;
+    /** Called when an SRT publisher connects and the stream is ready to read. */
+    onPublish?: (info: {
+        app: string;
+        internalUrl: string;
+    }) => void;
+    /**
+     * Called once when the first data packet from this input arrives at the server.
+     * @param wallClockMs `Date.now()` on the server at the moment the first MPEG-TS packet arrived.
+     */
+    onStreamStart?: (wallClockMs: number) => void;
+    /** Called when the publisher disconnects (the underlying FFmpeg pull exits). */
+    onStreamEnded?: () => void;
+}
+/** SDK handle for an SRT reader node. */
+declare class SrtReaderNode extends BaseNode {
+    readonly settings: SrtReaderSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: SrtReaderSettings);
+}
+
+interface FileOutputSettings extends NodeCallbacks {
+    /** Absolute path for the output file */
+    fileName: string;
+    /** Container format: "mp4" | "ts" | "mkv". Default: inferred from extension */
+    format?: string;
+    /** Overwrite `fileName` if it already exists. Default: `true`. */
+    overwrite?: boolean;
+}
+declare class FileOutputNode extends BaseNode {
+    readonly settings: FileOutputSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: FileOutputSettings);
+}
+
+type HlsDestination = {
+    type: "file";
+    path: string;
+} | {
+    type: "s3";
+    bucket: string;
+    region: string;
+    /** S3-compatible endpoint URL (e.g. Tigris, MinIO, Cloudflare R2). */
+    endpoint?: string;
+    /** Key prefix prepended to all uploaded paths. */
+    keyPrefix?: string;
+    /**
+     * When true (default), a per-session timestamp suffix is appended to
+     * `keyPrefix` so that browser-cached segments from a previous session are
+     * never served for a new one.  Set to false when the caller already
+     * generates a unique prefix or when sub-paths are not supported.
+     */
+    makePrefixUnique?: boolean;
+    accessKeyId: string;
+    secretAccessKey: string;
+} | {
+    type: "http";
+    /** Base URL that receives PUT/DELETE requests for each segment and playlist. */
+    baseUrl: string;
+    /** Extra headers sent with every PUT/DELETE request. */
+    headers?: Record<string, string>;
+};
+interface HlsOutputSettings extends NodeCallbacks {
+    /** One or more destinations to fan HLS output to. */
+    destinations: HlsDestination[];
+    /** Target segment duration in seconds. Default: 6 */
+    segmentTime?: number;
+    /**
+     * Number of segments kept in the live playlist window.
+     * 0 = keep all (VOD). Default: 5.
+     */
+    listSize?: number;
+    /**
+     * Node-level fallback audio codec, applied to audio streams whose
+     * subscription does not specify its own `codec`. Omitted (or `copy`)
+     * preserves the input audio codec — except when more than one audio source
+     * is connected, where the default becomes `aac` so all alternate-audio
+     * renditions share one codec (required by hls.js).
+     *
+     * For a caption-readiness buffer (the old `avDelayMs`), put `delayMs` on
+     * each media subscription instead and leave caption subscriptions
+     * undelayed.
+     */
+    audioCodec?: "copy" | string | null;
+    /**
+     * Node-level fallback video codec, applied to video streams whose
+     * subscription does not specify its own `codec`. Omitted (or `copy`)
+     * preserves the input video codec.
+     */
+    videoCodec?: "copy" | string | null;
+}
+declare class HlsOutputNode extends BaseNode {
+    readonly settings: HlsOutputSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: HlsOutputSettings);
+    /**
+     * Return the effective base path or URL for each configured destination in
+     * the current session.  Must be called after `subscribe()` so that the server
+     * has wired the destinations.  For S3 destinations this includes the
+     * per-session subfolder appended by `makePrefixUnique`.
+     */
+    effectivePaths(): Promise<string[]>;
+}
+
+interface RtmpOutputSettings extends NodeCallbacks {
+    /** Full RTMP URL to push to, e.g. "rtmp://live.twitch.tv/app/stream-key" */
+    url: string;
+    /**
+     * Called when the output FFmpeg process exits with an error after the node
+     * has been created — e.g. the destination server refused the connection,
+     * dropped mid-stream, or returned an unexpected error code.
+     *
+     * Errors that occur during node creation still reject the
+     * `workflow.output.rtmp()` promise as usual.
+     */
+    onError?: (err: Error) => void;
+}
+declare class RtmpOutputNode extends BaseNode {
+    readonly settings: RtmpOutputSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: RtmpOutputSettings);
+}
+
+interface SrtOutputSettings extends NodeCallbacks {
+    /**
+     * Full SRT URL to push to, e.g. `"srt://host:port"`.
+     * Transport parameters (latency, passphrase, etc.) are passed as query
+     * params: `"srt://host:port?latency=200&passphrase=secret"`.
+     */
+    url: string;
+    /**
+     * Called when the output FFmpeg process exits with an error after the node
+     * has been created — e.g. the destination refused the connection or dropped
+     * mid-stream.
+     *
+     * Errors that occur during node creation still reject the
+     * `workflow.output.srt()` promise as usual.
+     */
+    onError?: (err: Error) => void;
+}
+declare class SrtOutputNode extends BaseNode {
+    readonly settings: SrtOutputSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: SrtOutputSettings);
+}
+
+interface BufferSettings extends NodeCallbacks {
+    /** Time (ms) to hold back the input stream before forwarding it to subscribers. */
+    bufferMs: number;
+}
+/**
+ * Time-shift node. Subscribe it to exactly one source (any selector); it
+ * re-emits that source delayed by `bufferMs`, shared so every downstream
+ * subscriber sees the same delayed feed.
+ */
+declare class BufferNode extends BaseNode {
+    readonly settings: BufferSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: BufferSettings);
+}
+
+interface CambAiTranslateSettings extends NodeCallbacks {
+    /** Camb.ai API key. */
+    apiKey: string;
+    /** BCP-47 source language code for the input audio (e.g. `"en-US"`). */
+    sourceLanguageCode: string;
+    /** BCP-47 target language code for the translation output (e.g. `"de-DE"`). */
+    targetLanguageCode: string;
+    /** Realtime translation model. Defaults to Camb's server-side default. */
+    model?: "lilac" | "violet" | "iris" | "orchid";
+    /** Cloned voice ID to synthesize the translation with. Defaults to a built-in voice for the target language. */
+    voiceId?: number;
+    /** Human-readable label shown in the dashboard. */
+    label?: string;
+}
+/** Processor node that translates audio via the Camb.ai realtime speech-to-speech API. */
+declare class CambAiTranslateNode extends BaseNode {
+    readonly settings: CambAiTranslateSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: CambAiTranslateSettings);
+}
+
+type CaptionMode = "rollUp" | "popOn" | "paintOn";
+interface Cea608EncoderSettings extends NodeCallbacks {
+    /** Caption display mode. Default: "rollUp" */
+    mode?: CaptionMode;
+    /**
+     * Maximum number of visible rows (2, 3, or 4). Default: 2.
+     *
+     * - **rollUp**: sets the scroll-window height (RU2/RU3/RU4 command).
+     * - **popOn**: captions sent with `\n`-separated lines are displayed
+     *   bottom-anchored; this value caps how many lines are shown at once.
+     *   E.g. `rows: 2` with `"line one\nline two"` fills rows 14 and 15.
+     */
+    rows?: 2 | 3 | 4;
+    /**
+     * When `mode` is `"popOn"`, automatically word-wrap caption text to
+     * CEA-608's 32-column display width before laying it out as a
+     * bottom-anchored multi-line caption card (capped at `rows` lines) —
+     * instead of requiring you to insert `\n` yourself. Has no effect in
+     * `"rollUp"`/`"paintOn"` modes, where each `send()` is naturally a single
+     * line.
+     *
+     * Default: false.
+     */
+    autoWrap?: boolean;
+}
+declare class Cea608EncoderNode extends BaseNode {
+    readonly settings: Cea608EncoderSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: Cea608EncoderSettings);
+}
+
+interface FfprobeMonitorSettings extends NodeCallbacks {
+    /**
+     * How often (ms) to re-run ffprobe on the attached stream.
+     * Each cycle spawns a fresh ffprobe process, probes `probeSizeBytes` of data,
+     * and publishes the result to the **stream-info** monitor.
+     * Default: 30 000 ms.
+     */
+    intervalMs?: number;
+    /**
+     * Bytes of stream data to feed into each ffprobe invocation.
+     * Larger values give ffprobe more context (e.g. long-GOP streams) at the
+     * cost of a slightly longer first-result latency. Default: 1 048 576 (1 MB).
+     */
+    probeSizeBytes?: number;
+}
+declare class FfprobeMonitorNode extends BaseNode {
+    readonly settings: FfprobeMonitorSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: FfprobeMonitorSettings);
+    /**
+     * Subscribe to a monitor stream on this node.
+     *
+     * - `"stream-info"` — emits a `status` event (key/value map) every time a
+     *   probe cycle completes, containing codec names, resolution, frame rate,
+     *   bit rates, and format.
+     * - `"ffprobe-log"` — emits `log` events with raw ffprobe stderr output.
+     *
+     * Returns an object with an `unsubscribe()` method; call it to stop receiving
+     * events and release the tRPC subscription.
+     */
+    observe(monitorName: "stream-info" | "ffprobe-log", onData: (event: MonitorEventMsg) => void, onError?: (err: unknown) => void): {
+        unsubscribe(): void;
+    };
+}
+
+interface GateSettings extends NodeCallbacks {
+    /**
+     * Number of distinct sources that must have emitted at least one item
+     * before the gate opens. Default: wait for every subscribed source.
+     */
+    minReady?: number;
+    /**
+     * Force the gate open after this many ms even if `minReady` hasn't been
+     * reached, using whatever sources are ready by then. Omit to wait
+     * indefinitely — a source that never produces data would otherwise stall
+     * the gate forever.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Synchronization barrier for fan-in from multiple, independently-timed
+ * sources (e.g. two different transcription/translation services). Not to
+ * be confused with the `gate` option on `.subscribe()` (`ActivationGate`),
+ * which defers wiring based on upstream node *lifecycle*, not data.
+ *
+ * `GateNode` subscribes to every source immediately and queues everything
+ * each one emits, then starts forwarding — for every source at once — only
+ * once enough of them have produced their first item. It is a one-time
+ * rendezvous, not a per-item join.
+ *
+ * Every source becomes its own keyed pass-through port on the gate — streams
+ * are never merged. Name a port with `name` on the gate's subscription spec
+ * (default: the source's index as a string) and read it downstream with
+ * `port`:
+ *
+ * ```ts
+ * await gate.subscribe([
+ *   { source: a, sourceSelector: "ALL", name: "main" },
+ *   { source: b, sourceSelector: "ALL", name: "backup" },
+ * ]);
+ * await out1.subscribe([{ source: gate, sourceSelector: "ALL", port: "main" }]);
+ * await out2.subscribe([{ source: gate, sourceSelector: "ALL", port: "backup" }]);
+ * ```
+ *
+ * With exactly one source of a kind, plain selector subscriptions (no
+ * `port`) still resolve to it; with several same-kind sources the server
+ * errors and asks for an explicit `port`.
+ */
+declare class GateNode extends BaseNode {
+    readonly settings: GateSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: GateSettings);
+}
+
+interface GeminiTranslateSettings extends NodeCallbacks {
+    /** Gemini API key. */
+    apiKey: string;
+    /**
+     * BCP-47 target language code for the translation output
+     * (e.g. `"it"`, `"es"`, `"fr"`).
+     */
+    targetLanguageCode: string;
+    /** Human-readable label shown in the dashboard. */
+    label?: string;
+}
+/** Processor node that translates audio via the Gemini Live Translate API. */
+declare class GeminiTranslateNode extends BaseNode {
+    readonly settings: GeminiTranslateSettings;
+    constructor(nodeId: string, workflow: WorkflowHandle, settings: GeminiTranslateSettings);
+}
+
+/** Lifecycle callbacks available on a workflow. */
+interface WorkflowCallbacks {
+    /**
+     * Called if this workflow's worker process crashes. Workflow errors
+     * otherwise only appear in server logs — this is the client-side signal.
+     */
+    onError?: (err: Error) => void;
+    /** Called when the workflow closes, whether via `.close()` or a crash. */
+    onClose?: () => void;
+}
+/**
+ * A workflow is an isolated sub-registry on the server.
+ * All nodes created through a workflow handle are scoped to that workflow;
+ * they cannot subscribe to nodes in other workflows.
+ *
+ * Obtain a workflow via `rema.workflow.create()`.
+ */
+declare class Workflow {
+    readonly workflowId: string;
+    /** Non-private: accessible to factory functions via WorkflowHandle. */
+    readonly client: RemaClient;
+    private readonly _callbacks;
+    private readonly _eventHandlers;
+    private _eventSub;
+    private _stateSub;
+    private _seenInList;
+    private _erroredFired;
+    private _closedFired;
+    /** @internal — use `rema.workflow.create()` instead */
+    constructor(workflowId: string, client: RemaClient, callbacks?: WorkflowCallbacks);
+    /**
+     * Register a handler for events emitted by a specific node in this workflow.
+     * Returns an unsubscribe function — call it when the node is closed.
+     * @internal used by node factory functions
+     */
+    _onNodeEvent(nodeId: string, handler: (evt: NodeEventMsg) => void): () => void;
+    private _startEventSubscription;
+    /**
+     * Watches the server's list of all workflows for this workflow's entry, so
+     * `onError`/`onClose` can be derived without a dedicated per-workflow
+     * subscription: a transition to `status: "crashed"` fires `onError`, and
+     * the entry disappearing (graceful close) fires `onClose`.
+     */
+    private _startStateSubscription;
+    private _fireClose;
+    readonly input: {
+        file: (settings: FileInputSettings, nodeId?: string) => Promise<FileInputNode>;
+        rtmpReader: (settings: RtmpReaderSettings, nodeId?: string) => Promise<RtmpReaderNode>;
+        /** Announces RTMP publisher connections on an `app` without creating nodes. */
+        rtmpAnnouncer: (settings: RtmpAnnouncerSettings, nodeId?: string) => Promise<RtmpAnnouncerNode>;
+        /** Announces SRT publisher connections on an `app` without creating nodes. */
+        srtAnnouncer: (settings: SrtAnnouncerSettings, nodeId?: string) => Promise<SrtAnnouncerNode>;
+        /** Reads an SRT stream ingested by MediaMTX, pulling it back via RTSP internally. */
+        srtReader: (settings: SrtReaderSettings, nodeId?: string) => Promise<SrtReaderNode>;
+        /**
+         * An RTMP multiplexer: accepts any number of simultaneous publishers under
+         * the given `app`. For each connection `onStream` is called with a fresh
+         * `RtmpStreamNode` that can be wired into its own encoder/output pipeline.
+         */
+        rtmpMultiplexer: (settings: RtmpMultiplexerSettings, nodeId?: string) => Promise<RtmpMultiplexerNode>;
+        /** Format-agnostic caption schedule node. Send captions to it; wire it to a cea608() encoder. */
+        captions: (settings?: CaptionSourceSettings, nodeId?: string) => Promise<CaptionSourceNode>;
+        /**
+         * Audio stream input node.  Push a Node.js `Readable` (or any
+         * `AsyncIterable<Buffer>`) directly into the pipeline by calling
+         * `.stream(source)` on the returned node.
+         */
+        streamInput: (settings: NodeStreamInputSettings, nodeId?: string) => Promise<NodeStreamInputNode>;
+    };
+    readonly output: {
+        rtmp: (settings: RtmpOutputSettings, nodeId?: string) => Promise<RtmpOutputNode>;
+        file: (settings: FileOutputSettings, nodeId?: string) => Promise<FileOutputNode>;
+        /** HLS output node. Subscribe it to one or more media/subtitle sources. */
+        hls: (settings: HlsOutputSettings, nodeId?: string) => Promise<HlsOutputNode>;
+        /** SRT output node. Pushes MPEG-TS over SRT to the given URL. */
+        srt: (settings: SrtOutputSettings, nodeId?: string) => Promise<SrtOutputNode>;
+    };
+    readonly processor: {
+        /** CEA-608/708 encoder node. Subscribe it to video + a captions() node. */
+        cea608: (settings?: Cea608EncoderSettings, nodeId?: string) => Promise<Cea608EncoderNode>;
+        /**
+         * ffprobe monitor node.
+         * Subscribe it to any media source; it periodically probes the live stream
+         * and exposes codec/resolution/bitrate info via the `stream-info` monitor.
+         */
+        ffprobeMonitor: (settings?: FfprobeMonitorSettings, nodeId?: string) => Promise<FfprobeMonitorNode>;
+        /**
+         * Gemini Live Translate node.
+         * Subscribe it to an audio/media source; it outputs translated audio-only
+         * MPEG-TS using the Gemini Live Translate API.
+         */
+        geminiTranslate: (settings: GeminiTranslateSettings, nodeId?: string) => Promise<GeminiTranslateNode>;
+        /**
+         * Camb.ai realtime speech-to-speech translation node.
+         * Subscribe it to an audio/media source; it outputs translated audio-only
+         * MPEG-TS using the Camb.ai realtime translation API.
+         */
+        cambAiTranslate: (settings: CambAiTranslateSettings, nodeId?: string) => Promise<CambAiTranslateNode>;
+        /**
+         * Time-shift node. Subscribe it to exactly one source; it re-emits that
+         * source delayed by `bufferMs`, shared across every downstream
+         * subscriber.
+         */
+        buffer: (settings: BufferSettings, nodeId?: string) => Promise<BufferNode>;
+        /**
+         * Synchronization barrier for fan-in from multiple, independently-timed
+         * sources. Subscribe it to two or more sources; it withholds all of them
+         * until enough (`minReady`, default: all) have produced their first
+         * item, then forwards everything live.
+         */
+        gate: (settings?: GateSettings, nodeId?: string) => Promise<GateNode>;
+    };
+    /**
+     * Close this workflow and deactivate all its nodes on the server.
+     * After calling this the workflow handle is no longer usable.
+     */
+    close(): Promise<void>;
+}
+
+declare class Rema {
+    private readonly client;
+    private readonly _autoCloseWorkflows;
+    private constructor();
+    static connect(opts?: RemaClientOptions): Promise<Rema>;
+    readonly workflow: {
+        /**
+         * Create a new isolated workflow on the server.
+         *
+         * All nodes created through the returned `Workflow` handle are scoped to
+         * this workflow; they cannot subscribe to nodes in other workflows.
+         *
+         * @param opts.name               Human-readable label shown in the web UI.
+         * @param opts.workflowId         Optional stable ID. Server generates one if omitted.
+         * @param opts.closeOnDisconnect  When true, this workflow is closed automatically
+         *                                when `rema.close()`/`wf.close()` is called, or
+         *                                when the connection to the server is lost (e.g.
+         *                                the process crashes) for more than a few seconds.
+         * @param opts.parentId           ID of an existing workflow to attach this one to as
+         *                                a child (shown nested in the web UI).
+         * @param opts.closeWithParent    When true, this workflow is closed automatically
+         *                                when its parent workflow is closed.
+         * @param opts.onError            Called if this workflow's worker process crashes.
+         * @param opts.onClose            Called when the workflow closes, whether via
+         *                                `.close()` or a crash.
+         */
+        create: (opts?: {
+            name?: string;
+            workflowId?: string;
+            closeOnDisconnect?: boolean;
+            parentId?: string;
+            closeWithParent?: boolean;
+        } & WorkflowCallbacks) => Promise<Workflow>;
+        /** List all active workflows on the server. */
+        list: () => Promise<WorkflowInfo[]>;
+    };
+    /** Fetches the server's current health status (uptime, workflow counts, MediaMTX reachability). */
+    health(): Promise<HealthStatus>;
+    /**
+     * Close all `closeOnDisconnect` workflows, then disconnect from the server.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Stream selectors — used when calling node.subscribe() to pick which
+ * streams flow from source to subscriber.
+ */
+type StreamSelector = "VIDEO" | "AUDIO" | "CAPTIONS" | "ALL";
+declare const selectVideo: "VIDEO";
+declare const selectAudio: "AUDIO";
+declare const selectCaptions: "CAPTIONS";
+declare const selectAll: "ALL";
+
+export { type AllSubscriptionSpec, type AudioRenditionOptions, type AudioSubscriptionSpec, BaseNode, BufferNode, type BufferSettings, CambAiTranslateNode, type CambAiTranslateSettings, type CaptionMode, CaptionSourceNode, type CaptionSourceSettings, type CaptionsSubscriptionSpec, Cea608EncoderNode, type Cea608EncoderSettings, type CodecSpec, FfprobeMonitorNode, type FfprobeMonitorSettings, FileInputNode, type FileInputSettings, FileOutputNode, type FileOutputSettings, GateNode, type GateSettings, GeminiTranslateNode, type GeminiTranslateSettings, type HlsDestination, HlsOutputNode, type HlsOutputSettings, type NodeCallbacks, NodeStreamInputNode, type NodeStreamInputSettings, Rema, type RemaClientOptions, RtmpAnnouncerNode, type RtmpAnnouncerSettings, type RtmpConnectionInfo, RtmpMultiplexerNode, type RtmpMultiplexerSettings, RtmpOutputNode, type RtmpOutputSettings, RtmpReaderNode, type RtmpReaderSettings, RtmpStreamNode, SrtAnnouncerNode, type SrtAnnouncerSettings, type SrtConnectionInfo, SrtOutputNode, type SrtOutputSettings, SrtReaderNode, type SrtReaderSettings, type StreamSelector, type SubscriptionSpec, type VideoRenditionOptions, type VideoSubscriptionSpec, Workflow, type WorkflowCallbacks, createNodeStreamInputNode, selectAll, selectAudio, selectCaptions, selectVideo };