@ceralive/cerastream 2026.8.0 → 2026.9.0

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.12.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}. */
@@ -56,14 +56,27 @@ export declare const SUPPORTED_PROFILES: readonly ['balanced', 'low-latency', 'r
  * set or any preset's meaning changes. Mirrors the Rust `PROFILE_CATALOG_VERSION`.
  */
 export declare const PROFILE_CATALOG_VERSION: '1.0.0';
+/**
+ * PipeWire-backed audio capture: the engine addresses capture nodes by
+ * `node.name`/`object.serial`, so a source with no ALSA card — a Bluetooth
+ * microphone is the first one — is selectable as an ordinary node. Unlike the
+ * other tokens this one describes the engine's RUNNING configuration, so an
+ * engine configured for ALSA omits it even though this catalog lists it. Mirrors
+ * the Rust `PIPEWIRE_CAPTURE_FEATURE`.
+ */
+export declare const PIPEWIRE_CAPTURE_FEATURE: 'pipewire-capture';
 /**
  * Named engine features `get-capabilities` advertises in `features`. This is the
  * fail-closed negotiation contract: CeraUI sends a new out-of-schema field ONLY
  * when its feature is listed, so an engine that predates a feature (and silently
  * ignores the field) never applies a semantic the caller assumed. Mirrors the
  * Rust `ENGINE_FEATURES`.
+ *
+ * This is the full CATALOG. Gate on the token in the engine's own `features`
+ * array, never on membership here — a configuration-dependent token is filtered
+ * out of the response the engine actually sends.
  */
-export declare const ENGINE_FEATURES: readonly ['video-passthrough', 'input-mode', 'audio-pcm-spec'];
+export declare const ENGINE_FEATURES: readonly ['video-passthrough', 'input-mode', 'audio-pcm-spec', "pipewire-capture"];
 /** Engine binary name (systemd-owned; CeraUI never spawns it — ADR-0005). */
 export declare const CERASTREAM_BIN: 'cerastream';
 export declare const DEFAULT_MIN_BITRATE = 300;

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.12.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}. */
@@ -65,14 +65,32 @@ export const SUPPORTED_PROFILES = [
  * set or any preset's meaning changes. Mirrors the Rust `PROFILE_CATALOG_VERSION`.
  */
 export const PROFILE_CATALOG_VERSION = '1.0.0';
+/**
+ * PipeWire-backed audio capture: the engine addresses capture nodes by
+ * `node.name`/`object.serial`, so a source with no ALSA card — a Bluetooth
+ * microphone is the first one — is selectable as an ordinary node. Unlike the
+ * other tokens this one describes the engine's RUNNING configuration, so an
+ * engine configured for ALSA omits it even though this catalog lists it. Mirrors
+ * the Rust `PIPEWIRE_CAPTURE_FEATURE`.
+ */
+export const PIPEWIRE_CAPTURE_FEATURE = 'pipewire-capture';
 /**
  * Named engine features `get-capabilities` advertises in `features`. This is the
  * fail-closed negotiation contract: CeraUI sends a new out-of-schema field ONLY
  * when its feature is listed, so an engine that predates a feature (and silently
  * ignores the field) never applies a semantic the caller assumed. Mirrors the
  * Rust `ENGINE_FEATURES`.
+ *
+ * This is the full CATALOG. Gate on the token in the engine's own `features`
+ * array, never on membership here — a configuration-dependent token is filtered
+ * out of the response the engine actually sends.
  */
-export const ENGINE_FEATURES = ['video-passthrough', 'input-mode', 'audio-pcm-spec'];
+export const ENGINE_FEATURES = [
+    'video-passthrough',
+    'input-mode',
+    'audio-pcm-spec',
+    PIPEWIRE_CAPTURE_FEATURE,
+];
 /** Engine binary name (systemd-owned; CeraUI never spawns it — ADR-0005). */
 export const CERASTREAM_BIN = 'cerastream';
 // ---- config defaults (mirror ceracoder, the engine being replaced) ----

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

@@ -192,6 +192,7 @@ export declare const deviceEventSchema: z.ZodObject<{
         stable_id: z.ZodOptional<z.ZodString>;
         physical_group_id: z.ZodOptional<z.ZodString>;
         hardware_serial: z.ZodOptional<z.ZodString>;
+        device_address: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 /** Payload of a {@link deviceEventSchema} event. */
@@ -238,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>;
@@ -424,6 +430,7 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         stable_id: z.ZodOptional<z.ZodString>;
         physical_group_id: z.ZodOptional<z.ZodString>;
         hardware_serial: z.ZodOptional<z.ZodString>;
+        device_address: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"bitrate">;
@@ -455,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;
@@ -615,6 +627,7 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             stable_id: z.ZodOptional<z.ZodString>;
             physical_group_id: z.ZodOptional<z.ZodString>;
             hardware_serial: z.ZodOptional<z.ZodString>;
+            device_address: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"bitrate">;
@@ -646,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;
@@ -812,6 +830,7 @@ export declare const eventSchemas: {
             stable_id: z.ZodOptional<z.ZodString>;
             physical_group_id: z.ZodOptional<z.ZodString>;
             hardware_serial: z.ZodOptional<z.ZodString>;
+            device_address: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>;
     readonly bitrate: z.ZodObject<{
@@ -846,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

@@ -241,6 +241,7 @@ export declare const listDevicesResultSchema: z.ZodObject<{
         stable_id: z.ZodOptional<z.ZodString>;
         physical_group_id: z.ZodOptional<z.ZodString>;
         hardware_serial: z.ZodOptional<z.ZodString>;
+        device_address: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ListDevicesResult = z.infer<typeof listDevicesResultSchema>;
@@ -711,6 +712,7 @@ export declare const requestSchemas: {
                 stable_id: z.ZodOptional<z.ZodString>;
                 physical_group_id: z.ZodOptional<z.ZodString>;
                 hardware_serial: z.ZodOptional<z.ZodString>;
+                device_address: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
     };

package/dist/types.d.ts

@@ -276,6 +276,7 @@ export declare const captureDeviceSchema: z.ZodObject<{
     stable_id: z.ZodOptional<z.ZodString>;
     physical_group_id: z.ZodOptional<z.ZodString>;
     hardware_serial: z.ZodOptional<z.ZodString>;
+    device_address: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CaptureDevice = z.infer<typeof captureDeviceSchema>;
 export declare const srtStatsSchema: z.ZodObject<{

package/dist/types.js

@@ -184,6 +184,7 @@ export const captureDeviceSchema = z.object({
     stable_id: z.string().optional(), // additive (Todo 20): reboot-stable hardware identity, distinct from input_id/device_path
     physical_group_id: z.string().optional(), // additive (0.10.0, ADR-0008): `usb:<topology-token>` shared by one physical device's rows; absent on non-USB + legacy producers, and an absent group NEVER matches
     hardware_serial: z.string().optional(), // additive (0.10.0, ADR-0008): USB serial, DIAGNOSTIC ONLY — vendors ship placeholder serials, so never match/group/select on it
+    device_address: z.string().optional(), // additive: the address the node's provider advertises, carried verbatim; the engine attaches no meaning to it, so the consumer owning the address space is the one that matches on it. Absent unless a provider published one
 });
 // ---- transport telemetry (srt-stats event payload) ----
 export const srtStatsSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ceralive/cerastream",
-	"version": "2026.8.0",
+	"version": "2026.9.0",
 	"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",