@ceralive/cerastream 2026.8.1 → 2026.9.1

package/README.md

@@ -8,6 +8,7 @@ engine's JSON-RPC 2.0 / NDJSON control plane over a Unix domain socket.
 - The eight v1 control methods (Zod params + result schemas + inferred types)
 - The nine server-push event payloads (discriminated union)
 - Two-tier error codes (RPC + runtime)
+- Typed capture-probe causes retained on runtime events and rejected-start exceptions
 - A unified engine config schema (= `start` params)
 - A `CerastreamClient` interface + `connect()` factory (UDS transport)
 - Additive `client.getCapabilities()` discovery for platform, source, encoder, and

package/dist/client.js

@@ -183,7 +183,7 @@ class ClientImpl {
         if (!parsed.success)
             return;
         const { id, error } = parsed.data;
-        const rpcErr = new CerastreamRpcError(error.code, error.message, error.data?.code, id);
+        const rpcErr = new CerastreamRpcError(error.code, error.message, error.data?.code, id, error.data);
         if (id == null)
             return; // parse error with null id — no request to settle.
         const pending = this.pending.get(id);

package/dist/constants.d.ts

@@ -8,7 +8,7 @@ export declare const PROTOCOL_VERSION: 'cerastream-ipc/1';
  * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
  * only moves when the wire schema itself does, in lockstep across both languages.
  */
-export declare const SCHEMA_VERSION: '0.11.0';
+export declare const SCHEMA_VERSION: '0.13.0';
 /** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
 export declare const DEFAULT_IPC_DIR: '/run/cerastream';
 /** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */

package/dist/constants.js

@@ -11,7 +11,7 @@ export const PROTOCOL_VERSION = 'cerastream-ipc/1';
  * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
  * only moves when the wire schema itself does, in lockstep across both languages.
  */
-export const SCHEMA_VERSION = '0.11.0';
+export const SCHEMA_VERSION = '0.13.0';
 /** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
 export const DEFAULT_IPC_DIR = '/run/cerastream';
 /** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */

package/dist/errors.d.ts

@@ -20,7 +20,11 @@ export declare class CerastreamRpcError extends Error {
     readonly dataCode: string | undefined;
     /** The request id this error answered, when present. */
     readonly requestId: number | string | null;
-    constructor(code: number, message: string, dataCode: string | undefined, requestId: number | string | null);
+    /** Full JSON-RPC `error.data` object, retained for additive typed detail. */
+    readonly data?: unknown;
+    constructor(code: number, message: string, dataCode: string | undefined, requestId: number | string | null, data?: unknown);
+    /** Typed capture-probe failures carried by a rejected stream start. */
+    captureCauses(): readonly CaptureCauseEntry[];
 }
 /**
  * Machine-readable classification of a {@link CerastreamConnectionError}, stable
@@ -91,6 +95,21 @@ export declare const processErrorCodeSchema: z.ZodEnum<{
     srtla_no_connections: "srtla_no_connections";
 }>;
 export type ProcessErrorCode = z.infer<typeof processErrorCodeSchema>;
+export declare const captureCauseSchema: z.ZodEnum<{
+    device_busy: "device_busy";
+    negotiation_failed: "negotiation_failed";
+    no_signal: "no_signal";
+}>;
+export type CaptureCause = z.infer<typeof captureCauseSchema>;
+export declare const captureCauseEntrySchema: z.ZodObject<{
+    device: z.ZodString;
+    cause: z.ZodEnum<{
+        device_busy: "device_busy";
+        negotiation_failed: "negotiation_failed";
+        no_signal: "no_signal";
+    }>;
+}, z.core.$strip>;
+export type CaptureCauseEntry = z.infer<typeof captureCauseEntrySchema>;
 /**
  * Why a capture device became `capture_unrecoverable` — the `reason` field of the
  * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.

package/dist/errors.js

@@ -23,12 +23,21 @@ export class CerastreamRpcError extends Error {
     dataCode;
     /** The request id this error answered, when present. */
     requestId;
-    constructor(code, message, dataCode, requestId) {
+    /** Full JSON-RPC `error.data` object, retained for additive typed detail. */
+    data;
+    constructor(code, message, dataCode, requestId, data) {
         super(message);
         this.name = 'CerastreamRpcError';
         this.code = code;
         this.dataCode = dataCode;
         this.requestId = requestId;
+        if (data !== undefined)
+            this.data = data;
+    }
+    /** Typed capture-probe failures carried by a rejected stream start. */
+    captureCauses() {
+        const parsed = rpcCaptureDataSchema.safeParse(this.data);
+        return parsed.success ? parsed.data.capture_causes : [];
     }
 }
 /**
@@ -129,6 +138,16 @@ export const processErrorCodeSchema = z.enum([
     // would be lying. Always carries a captureUnrecoverableReasonSchema `reason`.
     'capture_unrecoverable',
 ]);
+export const captureCauseSchema = z.enum(['negotiation_failed', 'no_signal', 'device_busy']);
+export const captureCauseEntrySchema = z.object({
+    device: z.string(),
+    cause: captureCauseSchema,
+});
+const rpcCaptureDataSchema = z
+    .object({
+    capture_causes: z.array(captureCauseEntrySchema),
+})
+    .passthrough();
 /**
  * Why a capture device became `capture_unrecoverable` — the `reason` field of the
  * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.

package/dist/events.d.ts

@@ -239,6 +239,11 @@ export declare const runtimeErrorEventSchema: z.ZodObject<{
     }>;
     reason: z.ZodOptional<z.ZodString>;
     selected: z.ZodOptional<z.ZodBoolean>;
+    capture_cause: z.ZodOptional<z.ZodEnum<{
+        device_busy: "device_busy";
+        negotiation_failed: "negotiation_failed";
+        no_signal: "no_signal";
+    }>>;
 }, z.core.$strip>;
 /** Payload of a {@link runtimeErrorEventSchema} event. */
 export type RuntimeErrorEvent = z.infer<typeof runtimeErrorEventSchema>;
@@ -457,6 +462,11 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>;
     reason: z.ZodOptional<z.ZodString>;
     selected: z.ZodOptional<z.ZodBoolean>;
+    capture_cause: z.ZodOptional<z.ZodEnum<{
+        device_busy: "device_busy";
+        negotiation_failed: "negotiation_failed";
+        no_signal: "no_signal";
+    }>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"preview">;
     seq: z.ZodNumber;
@@ -649,6 +659,11 @@ export declare const cerastreamEventSchema: z.ZodObject<{
         }>;
         reason: z.ZodOptional<z.ZodString>;
         selected: z.ZodOptional<z.ZodBoolean>;
+        capture_cause: z.ZodOptional<z.ZodEnum<{
+            device_busy: "device_busy";
+            negotiation_failed: "negotiation_failed";
+            no_signal: "no_signal";
+        }>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"preview">;
         seq: z.ZodNumber;
@@ -850,6 +865,11 @@ export declare const eventSchemas: {
         }>;
         reason: z.ZodOptional<z.ZodString>;
         selected: z.ZodOptional<z.ZodBoolean>;
+        capture_cause: z.ZodOptional<z.ZodEnum<{
+            device_busy: "device_busy";
+            negotiation_failed: "negotiation_failed";
+            no_signal: "no_signal";
+        }>>;
     }, z.core.$strip>;
     readonly preview: z.ZodObject<{
         type: z.ZodLiteral<"preview">;

package/dist/events.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { processErrorCodeSchema, processErrorSourceSchema } from './errors.js';
+import { captureCauseSchema, processErrorCodeSchema, processErrorSourceSchema } from './errors.js';
 import { captureDeviceSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewEncodeFallbackSchema, previewEncodeModeSchema, streamStateSchema, } from './types.js';
 // Server → client `event` notifications, delivered after `subscribe-events`
 // (schema.md "Events"). Each event is the inner `params` of an rpcEventSchema:
@@ -119,6 +119,8 @@ export const runtimeErrorEventSchema = z.object({
     source: processErrorSourceSchema,
     reason: z.string().optional(), // structured replacement for the stderr <reason>
     selected: z.boolean().optional(), // additive (0.11.0): the degraded input is the operator's OWN selection, so the stream will not move itself and only they can pick another — a materially different operator response than a degraded non-selected input, and one to branch on rather than string-match. Absent ⇒ false
+    // The code stays capture_video_error because older consumers reject unknown code values.
+    capture_cause: captureCauseSchema.optional(),
 });
 /** `preview` event — a preview-session lifecycle/phase change. */
 export const previewEventSchema = z.object({

package/dist/messages.d.ts

@@ -28,6 +28,10 @@ export declare const startParamsSchema: z.ZodObject<{
     resolution: z.ZodOptional<z.ZodString>;
     framerate: z.ZodOptional<z.ZodNumber>;
     audio: z.ZodOptional<z.ZodObject<{
+        backend: z.ZodOptional<z.ZodEnum<{
+            alsa: "alsa";
+            pipewire: "pipewire";
+        }>>;
         mode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             device: "device";
@@ -91,6 +95,10 @@ export declare const reloadConfigParamsSchema: z.ZodObject<{
         latency_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     audio: z.ZodOptional<z.ZodObject<{
+        backend: z.ZodOptional<z.ZodEnum<{
+            alsa: "alsa";
+            pipewire: "pipewire";
+        }>>;
         delay_ms: z.ZodOptional<z.ZodNumber>;
         delay_ms_signed: z.ZodOptional<z.ZodNumber>;
         meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -116,6 +124,10 @@ export declare const reloadConfigResultSchema: z.ZodObject<{
             latency_ms: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         audio: z.ZodOptional<z.ZodObject<{
+            backend: z.ZodOptional<z.ZodEnum<{
+                alsa: "alsa";
+                pipewire: "pipewire";
+            }>>;
             delay_ms: z.ZodOptional<z.ZodNumber>;
             delay_ms_signed: z.ZodOptional<z.ZodNumber>;
             meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -130,6 +142,7 @@ export declare const reloadConfigResultSchema: z.ZodObject<{
         "source-fixed": "source-fixed";
     }>>;
     reason: z.ZodOptional<z.ZodString>;
+    applies: z.ZodOptional<z.ZodLiteral<"next-session">>;
 }, z.core.$strip>;
 export type ReloadConfigResult = z.infer<typeof reloadConfigResultSchema>;
 export declare const setBitrateParamsSchema: z.ZodObject<{
@@ -402,6 +415,16 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
         default_framerate: z.ZodNumber;
     }, z.core.$strip>>;
     audio_live_switch: z.ZodOptional<z.ZodBoolean>;
+    audio_backends: z.ZodOptional<z.ZodObject<{
+        supported: z.ZodArray<z.ZodEnum<{
+            alsa: "alsa";
+            pipewire: "pipewire";
+        }>>;
+        active: z.ZodEnum<{
+            alsa: "alsa";
+            pipewire: "pipewire";
+        }>;
+    }, z.core.$strip>>;
     latency_range: z.ZodOptional<z.ZodObject<{
         min: z.ZodNumber;
         default: z.ZodNumber;
@@ -516,6 +539,10 @@ export declare const requestSchemas: {
             resolution: z.ZodOptional<z.ZodString>;
             framerate: z.ZodOptional<z.ZodNumber>;
             audio: z.ZodOptional<z.ZodObject<{
+                backend: z.ZodOptional<z.ZodEnum<{
+                    alsa: "alsa";
+                    pipewire: "pipewire";
+                }>>;
                 mode: z.ZodOptional<z.ZodEnum<{
                     default: "default";
                     device: "device";
@@ -579,6 +606,10 @@ export declare const requestSchemas: {
                 latency_ms: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             audio: z.ZodOptional<z.ZodObject<{
+                backend: z.ZodOptional<z.ZodEnum<{
+                    alsa: "alsa";
+                    pipewire: "pipewire";
+                }>>;
                 delay_ms: z.ZodOptional<z.ZodNumber>;
                 delay_ms_signed: z.ZodOptional<z.ZodNumber>;
                 meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -603,6 +634,10 @@ export declare const requestSchemas: {
                     latency_ms: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>>;
                 audio: z.ZodOptional<z.ZodObject<{
+                    backend: z.ZodOptional<z.ZodEnum<{
+                        alsa: "alsa";
+                        pipewire: "pipewire";
+                    }>>;
                     delay_ms: z.ZodOptional<z.ZodNumber>;
                     delay_ms_signed: z.ZodOptional<z.ZodNumber>;
                     meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -617,6 +652,7 @@ export declare const requestSchemas: {
                 "source-fixed": "source-fixed";
             }>>;
             reason: z.ZodOptional<z.ZodString>;
+            applies: z.ZodOptional<z.ZodLiteral<"next-session">>;
         }, z.core.$strip>;
     };
     readonly 'set-bitrate': {

package/dist/messages.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { AUDIO_DELAY_MAX_MS } from './constants.js';
 import { helloParamsSchema, helloResultSchema } from './envelope.js';
-import { balancerAlgorithmSchema, bitrateControlSchema, captureDeviceKindSchema, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewEncodeModeSchema, previewTierSchema, streamStateSchema, videoCodecSchema, } from './types.js';
+import { audioBackendSchema, balancerAlgorithmSchema, bitrateControlSchema, captureDeviceKindSchema, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewEncodeModeSchema, previewTierSchema, streamStateSchema, videoCodecSchema, } from './types.js';
 // The eight v1 control methods (schema.md "v1 messages"). Each is matched
 // byte-for-byte to schema.md: the JSON shape on the wire is the contract.
 // ---- 1. start ----
@@ -37,6 +37,7 @@ export const reloadConfigParamsSchema = z.object({
         .optional(),
     audio: z
         .object({
+        backend: audioBackendSchema.optional(),
         delay_ms: z.number().int().min(0).max(AUDIO_DELAY_MAX_MS).optional(), // legacy unsigned; kept for 0.3.0 callers
         delay_ms_signed: z.number().int().optional(), // signed sibling; clamped at apply, so unbounded
         // additive (0.9.0): idle-meter card preference — absent leaves it unchanged,
@@ -58,6 +59,7 @@ export const reloadConfigResultSchema = z.object({
     // "source-fixed" + reason "passthrough" report that. Absent on a transcode reload.
     bitrate_control: bitrateControlSchema.optional(),
     reason: z.string().optional(),
+    applies: z.literal('next-session').optional(),
 });
 // ---- 4. set-bitrate ----
 export const setBitrateParamsSchema = z.object({
@@ -200,6 +202,12 @@ export const getCapabilitiesResultSchema = z.object({
     encoder: encoderCapsSchema,
     sources: z.array(videoSourceCapSchema),
     audio_live_switch: z.boolean().optional(),
+    audio_backends: z
+        .object({
+        supported: z.array(audioBackendSchema),
+        active: audioBackendSchema,
+    })
+        .optional(),
     latency_range: latencyRangeCapsSchema.optional(),
     fec_capable: z.boolean().optional(), // engine can encode FEC on egress (SRTO_PACKETFILTER)
     supported_profiles: z.array(z.string()).optional(), // SRT receive presets the device offers

package/dist/types.d.ts

@@ -116,7 +116,16 @@ export declare const audioModeSchema: z.ZodEnum<{
     none: "none";
 }>;
 export type AudioMode = z.infer<typeof audioModeSchema>;
+export declare const audioBackendSchema: z.ZodEnum<{
+    alsa: "alsa";
+    pipewire: "pipewire";
+}>;
+export type AudioBackend = z.infer<typeof audioBackendSchema>;
 export declare const audioConfigSchema: z.ZodObject<{
+    backend: z.ZodOptional<z.ZodEnum<{
+        alsa: "alsa";
+        pipewire: "pipewire";
+    }>>;
     mode: z.ZodOptional<z.ZodEnum<{
         default: "default";
         device: "device";
@@ -162,6 +171,10 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
     resolution: z.ZodOptional<z.ZodString>;
     framerate: z.ZodOptional<z.ZodNumber>;
     audio: z.ZodOptional<z.ZodObject<{
+        backend: z.ZodOptional<z.ZodEnum<{
+            alsa: "alsa";
+            pipewire: "pipewire";
+        }>>;
         mode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             device: "device";

package/dist/types.js

@@ -113,7 +113,9 @@ export const bitrateConfigSchema = z
 // so a pre-0.6.0 caller keeps working. Replaces leaking pseudo-source strings
 // (e.g. "No audio") into `device`.
 export const audioModeSchema = z.enum(['none', 'default', 'device']);
+export const audioBackendSchema = z.enum(['alsa', 'pipewire']);
 export const audioConfigSchema = z.object({
+    backend: audioBackendSchema.optional(),
     mode: audioModeSchema.optional(),
     device: z.string().optional(), // ALSA capture device id; absent ⇒ test-tone fallback
     codec: z.string().optional(), // audio encoder codec id (e.g. "aac", "opus")

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ceralive/cerastream",
-	"version": "2026.8.1",
+	"version": "2026.9.1",
 	"description": "Type-safe TypeScript schema + IPC client for the cerastream streaming engine (JSON-RPC 2.0 / NDJSON over a Unix domain socket).",
 	"type": "module",
 	"main": "dist/index.js",