@ceralive/cerastream 2026.7.1 → 2026.7.3

package/README.md

@@ -6,10 +6,12 @@ engine's JSON-RPC 2.0 / NDJSON control plane over a Unix domain socket.
 
 - JSON-RPC 2.0 envelope + `hello` handshake schemas
 - The eight v1 control methods (Zod params + result schemas + inferred types)
-- The seven server-push event payloads (discriminated union)
+- The eight server-push event payloads (discriminated union)
 - Two-tier error codes (RPC + runtime)
 - A unified engine config schema (= `start` params)
 - A `CerastreamClient` interface + `connect()` factory (UDS transport)
+- Additive `client.getCapabilities()` discovery for platform, source, encoder, and
+  local preview availability
 
 The Zod schemas, types, and constants are the frozen wire contract; `connect()`
 drives that contract over an NDJSON/UDS transport with no native dependencies.
@@ -45,6 +47,8 @@ import { connect } from "@ceralive/cerastream";
 
 const client = await connect({ autoReconnect: true }); // hello handshake runs here
 console.log(client.hello.engine_version);
+const capabilities = await client.getCapabilities();
+console.log(capabilities.preview?.bound);
 
 const sub = await client.subscribeEvents({ topics: ["status", "bitrate"] }, (ev) => {
   if (ev.type === "bitrate") console.log("bitrate", ev.current_bitrate);

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { type HelloResult } from "./envelope.js";
 import { type EventParams } from "./events.js";
-import { type ListDevicesParams, type ListDevicesResult, type PreviewSessionParams, type PreviewSessionResult, type ReloadConfigParams, type ReloadConfigResult, type SetBitrateParams, type SetBitrateResult, type StartParams, type StartResult, type StopParams, type StopResult, type SubscribeEventsParams, type SubscribeEventsResult, type SwitchInputParams, type SwitchInputResult } from "./messages.js";
+import { type GetCapabilitiesResult, type ListDevicesParams, type ListDevicesResult, type PreviewSessionParams, type PreviewSessionResult, type ReloadConfigParams, type ReloadConfigResult, type SetBitrateParams, type SetBitrateResult, type StartParams, type StartResult, type StopParams, type StopResult, type SubscribeEventsParams, type SubscribeEventsResult, type SwitchInputParams, type SwitchInputResult } from "./messages.js";
 /** Options for {@link connect}. All optional — `connect({})` is valid. */
 export interface ConnectOptions {
     /** Control socket path override. Defaults to the resolved /run/cerastream/control.sock. */
@@ -77,6 +77,11 @@ export interface CerastreamClient {
      * @returns The discovered capture devices.
      */
     listDevices(params?: ListDevicesParams): Promise<ListDevicesResult>;
+    /**
+     * Read the engine's additive capability contract, including local preview
+     * availability. This request intentionally sits outside the frozen v1 map.
+     */
+    getCapabilities(): Promise<GetCapabilitiesResult>;
     /**
      * Subscribe to the live event stream; `handler` fires for each pushed event.
      * @param params The topics to subscribe to (absent ⇒ all topics).

package/dist/client.js

@@ -1,9 +1,10 @@
 import { CONTROL_SOCKET_PATH, PROTOCOL_VERSION } from "./constants.js";
 import { helloResultSchema, rpcErrorSchema, rpcResponseSchema, } from "./envelope.js";
+import { existsSync } from "node:fs";
 import { CerastreamConnectionError, CerastreamRpcError, CerastreamTimeoutError, } from "./errors.js";
 import { eventParamsSchema } from "./events.js";
 import { controlSocketPath } from "./paths.js";
-import { requestSchemas, } from "./messages.js";
+import { getCapabilitiesResultSchema, requestSchemas, } from "./messages.js";
 import { LineSocket } from "./transport.js";
 const DEFAULTS = {
     requestTimeoutMs: 10_000,
@@ -49,7 +50,7 @@ class ClientImpl {
             });
         }
         catch (err) {
-            throw new CerastreamConnectionError(`failed to connect to cerastream control socket at ${this.socketPath}`, err);
+            throw new CerastreamConnectionError(`failed to connect to cerastream control socket at ${this.socketPath}`, err, classifyConnectError(err, this.socketPath));
         }
         this.socket = socket;
     }
@@ -78,6 +79,9 @@ class ClientImpl {
     listDevices(params) {
         return this.call("list-devices", params);
     }
+    async getCapabilities() {
+        return getCapabilitiesResultSchema.parse(await this.rawRequest("get-capabilities", undefined));
+    }
     previewSession(params) {
         return this.call("preview-session", params);
     }
@@ -98,7 +102,7 @@ class ClientImpl {
         this.intentionalClose = true;
         for (const sub of this.subscriptions)
             sub.close();
-        const conn = new CerastreamConnectionError("client closed");
+        const conn = new CerastreamConnectionError("client closed", undefined, "closed");
         this.rejectAllPending(conn);
         this.socket?.close();
         this.socket = undefined;
@@ -114,7 +118,7 @@ class ClientImpl {
     rawRequest(method, params) {
         const socket = this.socket;
         if (!socket) {
-            return Promise.reject(new CerastreamConnectionError("control connection is not open"));
+            return Promise.reject(new CerastreamConnectionError("control connection is not open", undefined, "closed"));
         }
         const id = this.nextId++;
         const envelope = {
@@ -136,7 +140,7 @@ class ClientImpl {
             catch (err) {
                 clearTimeout(timer);
                 this.pending.delete(id);
-                reject(new CerastreamConnectionError("failed to write request", err));
+                reject(new CerastreamConnectionError("failed to write request", err, "lost"));
             }
         });
     }
@@ -203,7 +207,7 @@ class ClientImpl {
         this.socket = undefined;
         if (this.intentionalClose)
             return;
-        const conn = new CerastreamConnectionError("control connection lost", err);
+        const conn = new CerastreamConnectionError("control connection lost", err, "lost");
         this.rejectAllPending(conn);
         if (this.autoReconnect)
             void this.reconnectLoop();
@@ -260,6 +264,20 @@ function safeControlSocketPath() {
 function isObject(value) {
     return typeof value === "object" && value !== null;
 }
+// Classify a connect-time transport failure into a stable machine code. Bun's
+// `connect` collapses several distinct errors onto ENOENT and does not reliably
+// surface ECONNREFUSED for a stale AF_UNIX socket, so an explicit errno is
+// honored when present, then the socket file's presence disambiguates: a path
+// that is gone is `absent` (engine not up yet), a path that still exists but
+// won't accept is `refused` (a crashed/stale listener).
+function classifyConnectError(err, socketPath) {
+    const raw = isObject(err) ? err.code : undefined;
+    if (raw === "ECONNREFUSED")
+        return "refused";
+    if (raw === "EACCES" || raw === "EPERM")
+        return "unreachable";
+    return existsSync(socketPath) ? "refused" : "absent";
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

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.4.0";
+export declare const SCHEMA_VERSION: "0.8.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,6 +56,14 @@ 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";
+/**
+ * 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`.
+ */
+export declare const ENGINE_FEATURES: readonly ["video-passthrough"];
 /** 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.4.0";
+export const SCHEMA_VERSION = "0.8.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,6 +65,14 @@ 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";
+/**
+ * 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`.
+ */
+export const ENGINE_FEATURES = ["video-passthrough"];
 /** 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

@@ -22,15 +22,41 @@ export declare class CerastreamRpcError extends Error {
     readonly requestId: number | string | null;
     constructor(code: number, message: string, dataCode: string | undefined, requestId: number | string | null);
 }
+/**
+ * Machine-readable classification of a {@link CerastreamConnectionError}, stable
+ * across releases so CeraUI's start-failure taxonomy can branch on it without
+ * parsing messages. Distinguishes the three connect-phase failure shapes the
+ * engine's systemd lifecycle produces (an absent socket during boot, a stale
+ * socket left by a crashed instance, an otherwise-unreachable socket) from a
+ * mid-session drop or an intentional client close:
+ *
+ * - `absent`      — the control socket path does not exist (ENOENT): the engine
+ *                   is not running yet, or systemd has torn the old socket down
+ *                   during a restart. Maps to `engine_unavailable`/`engine_restarting`.
+ * - `refused`     — the socket path exists but the connection was refused
+ *                   (ECONNREFUSED): a stale socket a crashed/`SIGKILL`ed engine
+ *                   left behind, or one mid-`bind` on restart. Maps to
+ *                   `engine_restarting`/`engine_unavailable`.
+ * - `unreachable` — any other connect-time transport failure (e.g. EACCES).
+ * - `lost`        — an established connection dropped (socket closed/errored) or
+ *                   a write failed while a request was in flight.
+ * - `closed`      — the client was closed, or a request was issued on a
+ *                   not-open connection.
+ */
+export declare const CERASTREAM_CONNECT_ERROR_CODES: readonly ["absent", "refused", "unreachable", "lost", "closed"];
+export type CerastreamConnectErrorCode = (typeof CERASTREAM_CONNECT_ERROR_CODES)[number];
 /**
  * Thrown when the control connection is lost (socket closed/errored) while a
  * request was in flight, or when {@link connect} cannot reach the engine and
- * auto-reconnect is disabled.
+ * auto-reconnect is disabled. The {@link code} field classifies the failure —
+ * absent vs refused vs unreachable vs lost vs closed — for machine routing.
  */
 export declare class CerastreamConnectionError extends Error {
+    /** Stable machine-readable classification of the connection failure. */
+    readonly code: CerastreamConnectErrorCode;
     /** The underlying transport error, when there was one. */
     readonly cause: unknown;
-    constructor(message: string, cause?: unknown);
+    constructor(message: string, cause?: unknown, code?: CerastreamConnectErrorCode);
 }
 /** Thrown when a request exceeds the configured per-request timeout. */
 export declare class CerastreamTimeoutError extends Error {

package/dist/errors.js

@@ -31,17 +31,49 @@ export class CerastreamRpcError extends Error {
         this.requestId = requestId;
     }
 }
+/**
+ * Machine-readable classification of a {@link CerastreamConnectionError}, stable
+ * across releases so CeraUI's start-failure taxonomy can branch on it without
+ * parsing messages. Distinguishes the three connect-phase failure shapes the
+ * engine's systemd lifecycle produces (an absent socket during boot, a stale
+ * socket left by a crashed instance, an otherwise-unreachable socket) from a
+ * mid-session drop or an intentional client close:
+ *
+ * - `absent`      — the control socket path does not exist (ENOENT): the engine
+ *                   is not running yet, or systemd has torn the old socket down
+ *                   during a restart. Maps to `engine_unavailable`/`engine_restarting`.
+ * - `refused`     — the socket path exists but the connection was refused
+ *                   (ECONNREFUSED): a stale socket a crashed/`SIGKILL`ed engine
+ *                   left behind, or one mid-`bind` on restart. Maps to
+ *                   `engine_restarting`/`engine_unavailable`.
+ * - `unreachable` — any other connect-time transport failure (e.g. EACCES).
+ * - `lost`        — an established connection dropped (socket closed/errored) or
+ *                   a write failed while a request was in flight.
+ * - `closed`      — the client was closed, or a request was issued on a
+ *                   not-open connection.
+ */
+export const CERASTREAM_CONNECT_ERROR_CODES = [
+    "absent",
+    "refused",
+    "unreachable",
+    "lost",
+    "closed",
+];
 /**
  * Thrown when the control connection is lost (socket closed/errored) while a
  * request was in flight, or when {@link connect} cannot reach the engine and
- * auto-reconnect is disabled.
+ * auto-reconnect is disabled. The {@link code} field classifies the failure —
+ * absent vs refused vs unreachable vs lost vs closed — for machine routing.
  */
 export class CerastreamConnectionError extends Error {
+    /** Stable machine-readable classification of the connection failure. */
+    code;
     /** The underlying transport error, when there was one. */
     cause;
-    constructor(message, cause) {
+    constructor(message, cause, code = "unreachable") {
         super(message);
         this.name = "CerastreamConnectionError";
+        this.code = code;
         this.cause = cause;
     }
 }

package/dist/events.d.ts

@@ -13,6 +13,11 @@ export declare const activeEncodeSchema: z.ZodObject<{
     active_input: z.ZodOptional<z.ZodString>;
     decoder: z.ZodOptional<z.ZodString>;
     input_codec: z.ZodOptional<z.ZodString>;
+    passthrough: z.ZodOptional<z.ZodBoolean>;
+    gop_probe_outcome: z.ZodOptional<z.ZodString>;
+    gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+    frames_emitted: z.ZodOptional<z.ZodNumber>;
+    pipeline_playing: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ActiveEncode = z.infer<typeof activeEncodeSchema>;
 /**
@@ -48,6 +53,11 @@ export declare const statusEventSchema: z.ZodObject<{
         active_input: z.ZodOptional<z.ZodString>;
         decoder: z.ZodOptional<z.ZodString>;
         input_codec: z.ZodOptional<z.ZodString>;
+        passthrough: z.ZodOptional<z.ZodBoolean>;
+        gop_probe_outcome: z.ZodOptional<z.ZodString>;
+        gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+        frames_emitted: z.ZodOptional<z.ZodNumber>;
+        pipeline_playing: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Payload of a {@link statusEventSchema} event. */
@@ -106,6 +116,14 @@ export declare const deviceEventSchema: z.ZodObject<{
             network: "network";
         }>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
+        product_name: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<{
+            hdmi: "hdmi";
+            usb: "usb";
+            bluetooth: "bluetooth";
+            onboard: "onboard";
+        }>>;
+        stable_id: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 /** Payload of a {@link deviceEventSchema} event. */
@@ -162,6 +180,40 @@ export declare const previewEventSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Payload of a {@link previewEventSchema} event. */
 export type PreviewEvent = z.infer<typeof previewEventSchema>;
+/**
+ * `audio-level` event — the always-on audio level meter (ADR-0007, additive Todo
+ * 21). Either a real per-channel level from the current owner (the idle
+ * `sidecar` or the `streaming` audio leg), or `unavailable: true` + `reason` for
+ * a handoff gap or a degenerate `audio.mode` — never a fabricated level. A level
+ * carries `source`/`channels`/`rms_db`/`peak_db`/`floor_db`; an unavailable event
+ * carries `unavailable`/`reason` and omits the level fields. `floor_db` (`-1e6`)
+ * is the sentinel a consumer maps back to "silence" (JSON has no `-Infinity`).
+ * Independent of the preview-scoped `audio-level` WebSocket frame.
+ */
+export declare const audioLevelEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"audio-level">;
+    seq: z.ZodNumber;
+    source: z.ZodOptional<z.ZodObject<{
+        identity: z.ZodOptional<z.ZodString>;
+        owner: z.ZodEnum<{
+            streaming: "streaming";
+            sidecar: "sidecar";
+        }>;
+    }, z.core.$strip>>;
+    channels: z.ZodOptional<z.ZodNumber>;
+    rms_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    peak_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    floor_db: z.ZodOptional<z.ZodNumber>;
+    unavailable: z.ZodOptional<z.ZodLiteral<true>>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        device_busy: "device_busy";
+        no_device: "no_device";
+        mode_none: "mode_none";
+        handoff: "handoff";
+    }>>;
+}, z.core.$strip>;
+/** Payload of a {@link audioLevelEventSchema} event. */
+export type AudioLevelEvent = z.infer<typeof audioLevelEventSchema>;
 /** Discriminated union of every v1 event payload (the inner `params`). */
 export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"status">;
@@ -186,6 +238,11 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         active_input: z.ZodOptional<z.ZodString>;
         decoder: z.ZodOptional<z.ZodString>;
         input_codec: z.ZodOptional<z.ZodString>;
+        passthrough: z.ZodOptional<z.ZodBoolean>;
+        gop_probe_outcome: z.ZodOptional<z.ZodString>;
+        gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+        frames_emitted: z.ZodOptional<z.ZodNumber>;
+        pipeline_playing: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"switch">;
@@ -232,6 +289,14 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             network: "network";
         }>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
+        product_name: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<{
+            hdmi: "hdmi";
+            usb: "usb";
+            bluetooth: "bluetooth";
+            onboard: "onboard";
+        }>>;
+        stable_id: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"bitrate">;
@@ -266,6 +331,27 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     seq: z.ZodNumber;
     session_id: z.ZodString;
     phase: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"audio-level">;
+    seq: z.ZodNumber;
+    source: z.ZodOptional<z.ZodObject<{
+        identity: z.ZodOptional<z.ZodString>;
+        owner: z.ZodEnum<{
+            streaming: "streaming";
+            sidecar: "sidecar";
+        }>;
+    }, z.core.$strip>>;
+    channels: z.ZodOptional<z.ZodNumber>;
+    rms_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    peak_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    floor_db: z.ZodOptional<z.ZodNumber>;
+    unavailable: z.ZodOptional<z.ZodLiteral<true>>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        device_busy: "device_busy";
+        no_device: "no_device";
+        mode_none: "mode_none";
+        handoff: "handoff";
+    }>>;
 }, z.core.$strip>], "type">;
 export type EventParams = z.infer<typeof eventParamsSchema>;
 /** Full event envelope: { jsonrpc, method:"event", params } with typed params. */
@@ -295,6 +381,11 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             active_input: z.ZodOptional<z.ZodString>;
             decoder: z.ZodOptional<z.ZodString>;
             input_codec: z.ZodOptional<z.ZodString>;
+            passthrough: z.ZodOptional<z.ZodBoolean>;
+            gop_probe_outcome: z.ZodOptional<z.ZodString>;
+            gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+            frames_emitted: z.ZodOptional<z.ZodNumber>;
+            pipeline_playing: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"switch">;
@@ -341,6 +432,14 @@ export declare const cerastreamEventSchema: z.ZodObject<{
                 network: "network";
             }>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
+            product_name: z.ZodOptional<z.ZodString>;
+            transport: z.ZodOptional<z.ZodEnum<{
+                hdmi: "hdmi";
+                usb: "usb";
+                bluetooth: "bluetooth";
+                onboard: "onboard";
+            }>>;
+            stable_id: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"bitrate">;
@@ -375,11 +474,33 @@ export declare const cerastreamEventSchema: z.ZodObject<{
         seq: z.ZodNumber;
         session_id: z.ZodString;
         phase: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"audio-level">;
+        seq: z.ZodNumber;
+        source: z.ZodOptional<z.ZodObject<{
+            identity: z.ZodOptional<z.ZodString>;
+            owner: z.ZodEnum<{
+                streaming: "streaming";
+                sidecar: "sidecar";
+            }>;
+        }, z.core.$strip>>;
+        channels: z.ZodOptional<z.ZodNumber>;
+        rms_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        peak_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        floor_db: z.ZodOptional<z.ZodNumber>;
+        unavailable: z.ZodOptional<z.ZodLiteral<true>>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            device_busy: "device_busy";
+            no_device: "no_device";
+            mode_none: "mode_none";
+            handoff: "handoff";
+        }>>;
     }, z.core.$strip>], "type">;
 }, z.core.$strip>;
 export type CerastreamEvent = z.infer<typeof cerastreamEventSchema>;
-/** The seven event topics (schema.md "Events" table) — count-assertion source. */
-export declare const EVENT_TOPICS: readonly ["status", "switch", "device", "bitrate", "srt-stats", "error", "preview"];
+/** The eight event topics (schema.md "Events" table) — count-assertion source.
+ * `audio-level` is additive (Todo 21) and appended last, preserving order. */
+export declare const EVENT_TOPICS: readonly ["status", "switch", "device", "bitrate", "srt-stats", "error", "preview", "audio-level"];
 export type EventTopicName = (typeof EVENT_TOPICS)[number];
 /** topic → payload Zod schema. Tests assert every topic is represented here. */
 export declare const eventSchemas: {
@@ -406,6 +527,11 @@ export declare const eventSchemas: {
             active_input: z.ZodOptional<z.ZodString>;
             decoder: z.ZodOptional<z.ZodString>;
             input_codec: z.ZodOptional<z.ZodString>;
+            passthrough: z.ZodOptional<z.ZodBoolean>;
+            gop_probe_outcome: z.ZodOptional<z.ZodString>;
+            gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+            frames_emitted: z.ZodOptional<z.ZodNumber>;
+            pipeline_playing: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
     readonly switch: z.ZodObject<{
@@ -454,6 +580,14 @@ export declare const eventSchemas: {
                 network: "network";
             }>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
+            product_name: z.ZodOptional<z.ZodString>;
+            transport: z.ZodOptional<z.ZodEnum<{
+                hdmi: "hdmi";
+                usb: "usb";
+                bluetooth: "bluetooth";
+                onboard: "onboard";
+            }>>;
+            stable_id: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>;
     readonly bitrate: z.ZodObject<{
@@ -493,4 +627,26 @@ export declare const eventSchemas: {
         session_id: z.ZodString;
         phase: z.ZodString;
     }, z.core.$strip>;
+    readonly "audio-level": z.ZodObject<{
+        type: z.ZodLiteral<"audio-level">;
+        seq: z.ZodNumber;
+        source: z.ZodOptional<z.ZodObject<{
+            identity: z.ZodOptional<z.ZodString>;
+            owner: z.ZodEnum<{
+                streaming: "streaming";
+                sidecar: "sidecar";
+            }>;
+        }, z.core.$strip>>;
+        channels: z.ZodOptional<z.ZodNumber>;
+        rms_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        peak_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        floor_db: z.ZodOptional<z.ZodNumber>;
+        unavailable: z.ZodOptional<z.ZodLiteral<true>>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            device_busy: "device_busy";
+            no_device: "no_device";
+            mode_none: "mode_none";
+            handoff: "handoff";
+        }>>;
+    }, z.core.$strip>;
 };

package/dist/events.js

@@ -19,6 +19,11 @@ export const activeEncodeSchema = z.object({
     active_input: z.string().optional(), // active input id feeding the encode
     decoder: z.string().optional(), // runtime-selected decode element when transcoding
     input_codec: z.string().optional(), // incoming pre-decode codec token: "h264"/"h265"/"mjpeg"
+    passthrough: z.boolean().optional(), // 0.5.0: true when a same-codec passthrough graph is live (no decode/re-encode)
+    gop_probe_outcome: z.string().optional(), // 0.5.0: GOP preflight outcome: "eligible"|"ineligible"|"unknown"|"skipped"
+    gop_probe_ms: z.number().int().nonnegative().optional(), // 0.5.0: GOP preflight duration in ms when a probe ran
+    frames_emitted: z.number().int().nonnegative().optional(), // 0.7.0: monotonic egress-buffer counter; advances across status heartbeats while frames flow
+    pipeline_playing: z.boolean().optional(), // 0.7.0: pipeline is in GStreamer PLAYING (false during an in-process reconnect)
 });
 /**
  * `status` event — stream state change + heartbeat. The trailing fields are
@@ -96,6 +101,32 @@ export const previewEventSchema = z.object({
     session_id: z.string(),
     phase: z.string(),
 });
+/**
+ * `audio-level` event — the always-on audio level meter (ADR-0007, additive Todo
+ * 21). Either a real per-channel level from the current owner (the idle
+ * `sidecar` or the `streaming` audio leg), or `unavailable: true` + `reason` for
+ * a handoff gap or a degenerate `audio.mode` — never a fabricated level. A level
+ * carries `source`/`channels`/`rms_db`/`peak_db`/`floor_db`; an unavailable event
+ * carries `unavailable`/`reason` and omits the level fields. `floor_db` (`-1e6`)
+ * is the sentinel a consumer maps back to "silence" (JSON has no `-Infinity`).
+ * Independent of the preview-scoped `audio-level` WebSocket frame.
+ */
+export const audioLevelEventSchema = z.object({
+    type: z.literal("audio-level"),
+    seq,
+    source: z
+        .object({
+        identity: z.string().optional(), // reboot-stable device id (Todo 20 stable_id)
+        owner: z.enum(["sidecar", "streaming"]),
+    })
+        .optional(),
+    channels: z.number().int().nonnegative().optional(),
+    rms_db: z.array(z.number()).optional(),
+    peak_db: z.array(z.number()).optional(),
+    floor_db: z.number().optional(),
+    unavailable: z.literal(true).optional(),
+    reason: z.enum(["device_busy", "no_device", "mode_none", "handoff"]).optional(),
+});
 /** Discriminated union of every v1 event payload (the inner `params`). */
 export const eventParamsSchema = z.discriminatedUnion("type", [
     statusEventSchema,
@@ -105,6 +136,7 @@ export const eventParamsSchema = z.discriminatedUnion("type", [
     srtStatsEventSchema,
     runtimeErrorEventSchema,
     previewEventSchema,
+    audioLevelEventSchema,
 ]);
 /** Full event envelope: { jsonrpc, method:"event", params } with typed params. */
 export const cerastreamEventSchema = z.object({
@@ -112,7 +144,8 @@ export const cerastreamEventSchema = z.object({
     method: z.literal("event"),
     params: eventParamsSchema,
 });
-/** The seven event topics (schema.md "Events" table) — count-assertion source. */
+/** The eight event topics (schema.md "Events" table) — count-assertion source.
+ * `audio-level` is additive (Todo 21) and appended last, preserving order. */
 export const EVENT_TOPICS = [
     "status",
     "switch",
@@ -121,6 +154,7 @@ export const EVENT_TOPICS = [
     "srt-stats",
     "error",
     "preview",
+    "audio-level",
 ];
 /** topic → payload Zod schema. Tests assert every topic is represented here. */
 export const eventSchemas = {
@@ -131,4 +165,5 @@ export const eventSchemas = {
     "srt-stats": srtStatsEventSchema,
     error: runtimeErrorEventSchema,
     preview: previewEventSchema,
+    "audio-level": audioLevelEventSchema,
 };

package/dist/messages.d.ts

@@ -28,10 +28,20 @@ export declare const startParamsSchema: z.ZodObject<{
     resolution: z.ZodOptional<z.ZodString>;
     framerate: z.ZodOptional<z.ZodNumber>;
     audio: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            none: "none";
+            device: "device";
+        }>>;
         device: z.ZodOptional<z.ZodString>;
         codec: z.ZodOptional<z.ZodString>;
         delay_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    video_passthrough: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        force: "force";
+        off: "off";
+    }>>;
 }, z.core.$strip>;
 export type StartParams = z.infer<typeof startParamsSchema>;
 export declare const startResultSchema: z.ZodObject<{
@@ -95,6 +105,11 @@ export declare const reloadConfigResultSchema: z.ZodObject<{
             delay_ms_signed: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
+    bitrate_control: z.ZodOptional<z.ZodEnum<{
+        encoder: "encoder";
+        "source-fixed": "source-fixed";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ReloadConfigResult = z.infer<typeof reloadConfigResultSchema>;
 export declare const setBitrateParamsSchema: z.ZodObject<{
@@ -105,6 +120,11 @@ export declare const setBitrateResultSchema: z.ZodObject<{
     applied: z.ZodObject<{
         max_bitrate: z.ZodNumber;
     }, z.core.$strip>;
+    bitrate_control: z.ZodOptional<z.ZodEnum<{
+        encoder: "encoder";
+        "source-fixed": "source-fixed";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SetBitrateResult = z.infer<typeof setBitrateResultSchema>;
 export declare const switchInputParamsSchema: z.ZodObject<{
@@ -172,6 +192,14 @@ export declare const listDevicesResultSchema: z.ZodObject<{
             network: "network";
         }>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
+        product_name: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<{
+            hdmi: "hdmi";
+            usb: "usb";
+            bluetooth: "bluetooth";
+            onboard: "onboard";
+        }>>;
+        stable_id: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ListDevicesResult = z.infer<typeof listDevicesResultSchema>;
@@ -183,6 +211,7 @@ export declare const eventTopicSchema: z.ZodEnum<{
     switch: "switch";
     "srt-stats": "srt-stats";
     preview: "preview";
+    "audio-level": "audio-level";
 }>;
 export type EventTopic = z.infer<typeof eventTopicSchema>;
 export declare const subscribeEventsParamsSchema: z.ZodObject<{
@@ -194,6 +223,7 @@ export declare const subscribeEventsParamsSchema: z.ZodObject<{
         switch: "switch";
         "srt-stats": "srt-stats";
         preview: "preview";
+        "audio-level": "audio-level";
     }>>>;
 }, z.core.$strip>;
 export type SubscribeEventsParams = z.infer<typeof subscribeEventsParamsSchema>;
@@ -206,6 +236,7 @@ export declare const subscribeEventsResultSchema: z.ZodObject<{
         switch: "switch";
         "srt-stats": "srt-stats";
         preview: "preview";
+        "audio-level": "audio-level";
     }>>;
 }, z.core.$strip>;
 export type SubscribeEventsResult = z.infer<typeof subscribeEventsResultSchema>;
@@ -274,6 +305,16 @@ export declare const platformCapsSchema: z.ZodObject<{
     supports_h265: z.ZodBoolean;
     hardware_accelerated: z.ZodBoolean;
     max_resolution: z.ZodString;
+    hardware_kind: z.ZodOptional<z.ZodEnum<{
+        rk3588: "rk3588";
+        jetson: "jetson";
+        n100: "n100";
+        generic: "generic";
+    }>>;
+    source: z.ZodOptional<z.ZodEnum<{
+        detected: "detected";
+        override: "override";
+    }>>;
 }, z.core.$strip>;
 export type PlatformCaps = z.infer<typeof platformCapsSchema>;
 export declare const previewAvailabilitySchema: z.ZodObject<{
@@ -287,6 +328,16 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
         supports_h265: z.ZodBoolean;
         hardware_accelerated: z.ZodBoolean;
         max_resolution: z.ZodString;
+        hardware_kind: z.ZodOptional<z.ZodEnum<{
+            rk3588: "rk3588";
+            jetson: "jetson";
+            n100: "n100";
+            generic: "generic";
+        }>>;
+        source: z.ZodOptional<z.ZodEnum<{
+            detected: "detected";
+            override: "override";
+        }>>;
     }, z.core.$strip>;
     encoder: z.ZodObject<{
         codecs: z.ZodArray<z.ZodString>;
@@ -319,6 +370,7 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
         bound: z.ZodBoolean;
     }, z.core.$strip>>;
     network_embedded_audio: z.ZodOptional<z.ZodBoolean>;
+    features: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type GetCapabilitiesResult = z.infer<typeof getCapabilitiesResultSchema>;
 /** The eight v1 control methods (the literal JSON-RPC `method` strings). */
@@ -371,10 +423,20 @@ export declare const requestSchemas: {
             resolution: z.ZodOptional<z.ZodString>;
             framerate: z.ZodOptional<z.ZodNumber>;
             audio: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodOptional<z.ZodEnum<{
+                    default: "default";
+                    none: "none";
+                    device: "device";
+                }>>;
                 device: z.ZodOptional<z.ZodString>;
                 codec: z.ZodOptional<z.ZodString>;
                 delay_ms: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
+            video_passthrough: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                force: "force";
+                off: "off";
+            }>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
             session_id: z.ZodString;
@@ -437,6 +499,11 @@ export declare const requestSchemas: {
                     delay_ms_signed: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>>;
             }, z.core.$strip>;
+            bitrate_control: z.ZodOptional<z.ZodEnum<{
+                encoder: "encoder";
+                "source-fixed": "source-fixed";
+            }>>;
+            reason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     };
     readonly "set-bitrate": {
@@ -447,6 +514,11 @@ export declare const requestSchemas: {
             applied: z.ZodObject<{
                 max_bitrate: z.ZodNumber;
             }, z.core.$strip>;
+            bitrate_control: z.ZodOptional<z.ZodEnum<{
+                encoder: "encoder";
+                "source-fixed": "source-fixed";
+            }>>;
+            reason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     };
     readonly "switch-input": {
@@ -498,6 +570,14 @@ export declare const requestSchemas: {
                     network: "network";
                 }>>;
                 alsa_card_id: z.ZodOptional<z.ZodString>;
+                product_name: z.ZodOptional<z.ZodString>;
+                transport: z.ZodOptional<z.ZodEnum<{
+                    hdmi: "hdmi";
+                    usb: "usb";
+                    bluetooth: "bluetooth";
+                    onboard: "onboard";
+                }>>;
+                stable_id: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
     };
@@ -511,6 +591,7 @@ export declare const requestSchemas: {
                 switch: "switch";
                 "srt-stats": "srt-stats";
                 preview: "preview";
+                "audio-level": "audio-level";
             }>>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
@@ -522,6 +603,7 @@ export declare const requestSchemas: {
                 switch: "switch";
                 "srt-stats": "srt-stats";
                 preview: "preview";
+                "audio-level": "audio-level";
             }>>;
         }, z.core.$strip>;
     };

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, captureDeviceSchema, cerastreamConfigSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, } from "./types.js";
+import { balancerAlgorithmSchema, bitrateControlSchema, captureDeviceSchema, cerastreamConfigSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, } 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 ----
@@ -44,6 +44,10 @@ export const reloadConfigParamsSchema = z.object({
 });
 export const reloadConfigResultSchema = z.object({
     applied: reloadConfigParamsSchema, // post-clamp values actually applied
+    // additive (0.5.0): a bitrate-bearing reload during passthrough is NOT applied —
+    // "source-fixed" + reason "passthrough" report that. Absent on a transcode reload.
+    bitrate_control: bitrateControlSchema.optional(),
+    reason: z.string().optional(),
 });
 // ---- 4. set-bitrate ----
 export const setBitrateParamsSchema = z.object({
@@ -51,6 +55,10 @@ export const setBitrateParamsSchema = z.object({
 });
 export const setBitrateResultSchema = z.object({
     applied: z.object({ max_bitrate: z.number().int() }),
+    // additive (0.5.0). On passthrough there is no encoder to drive, so a request is
+    // NOT applied: "source-fixed" with reason "passthrough". Absent/"encoder" ⇒ applied.
+    bitrate_control: bitrateControlSchema.optional(),
+    reason: z.string().optional(),
 });
 // ---- 5. switch-input ----
 export const switchInputParamsSchema = z.object({
@@ -91,6 +99,7 @@ export const eventTopicSchema = z.enum([
     "srt-stats",
     "error",
     "preview",
+    "audio-level",
 ]);
 export const subscribeEventsParamsSchema = z.object({
     topics: z.array(eventTopicSchema).optional(), // default: all topics
@@ -154,6 +163,10 @@ export const platformCapsSchema = z.object({
     supports_h265: z.boolean(),
     hardware_accelerated: z.boolean(),
     max_resolution: z.string(),
+    // additive: the engine's resolved hardware kind and how it was resolved.
+    // Optional so a pre-field engine (which omits both) still parses.
+    hardware_kind: z.enum(["rk3588", "jetson", "n100", "generic"]).optional(),
+    source: z.enum(["detected", "override"]).optional(),
 });
 // Preview-server availability (0.4.0, additive). Lets the UI tell an unbound /
 // port-conflicted preview (enabled:true, bound:false) from a down engine.
@@ -173,6 +186,7 @@ export const getCapabilitiesResultSchema = z.object({
     profile_catalog_version: z.string().optional(), // semver of the supported_profiles catalog
     preview: previewAvailabilitySchema.optional(), // preview-server availability (unbound vs down)
     network_embedded_audio: z.boolean().optional(), // engine routes network-ingest embedded audio to the mux
+    features: z.array(z.string()).optional(), // named engine features (e.g. "video-passthrough") for fail-closed negotiation
 });
 // ---- method registry (count-assertion source of truth) ----
 /** The eight v1 control methods (the literal JSON-RPC `method` strings). */

package/dist/types.d.ts

@@ -32,6 +32,17 @@ export declare const videoCodecSchema: z.ZodEnum<{
     h265: "h265";
 }>;
 export type VideoCodec = z.infer<typeof videoCodecSchema>;
+export declare const videoPassthroughSchema: z.ZodEnum<{
+    auto: "auto";
+    force: "force";
+    off: "off";
+}>;
+export type VideoPassthrough = z.infer<typeof videoPassthroughSchema>;
+export declare const bitrateControlSchema: z.ZodEnum<{
+    encoder: "encoder";
+    "source-fixed": "source-fixed";
+}>;
+export type BitrateControl = z.infer<typeof bitrateControlSchema>;
 export declare const captureDeviceKindSchema: z.ZodEnum<{
     audio: "audio";
     hdmi: "hdmi";
@@ -43,6 +54,13 @@ export declare const captureDeviceKindSchema: z.ZodEnum<{
     network: "network";
 }>;
 export type CaptureDeviceKind = z.infer<typeof captureDeviceKindSchema>;
+export declare const deviceTransportSchema: z.ZodEnum<{
+    hdmi: "hdmi";
+    usb: "usb";
+    bluetooth: "bluetooth";
+    onboard: "onboard";
+}>;
+export type DeviceTransport = z.infer<typeof deviceTransportSchema>;
 /** SRT transport config. Mirrors schema.md `start.srt` exactly. */
 export declare const srtConfigSchema: z.ZodObject<{
     host: z.ZodString;
@@ -73,7 +91,18 @@ export type BitrateConfig = z.infer<typeof bitrateConfigSchema>;
  * later, negative = earlier); it is clamped to ±AUDIO_DELAY_MAX_MS when applied,
  * never rejected — so the schema does NOT bound it.
  */
+export declare const audioModeSchema: z.ZodEnum<{
+    default: "default";
+    none: "none";
+    device: "device";
+}>;
+export type AudioMode = z.infer<typeof audioModeSchema>;
 export declare const audioConfigSchema: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        none: "none";
+        device: "device";
+    }>>;
     device: z.ZodOptional<z.ZodString>;
     codec: z.ZodOptional<z.ZodString>;
     delay_ms: z.ZodOptional<z.ZodNumber>;
@@ -114,10 +143,20 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
     resolution: z.ZodOptional<z.ZodString>;
     framerate: z.ZodOptional<z.ZodNumber>;
     audio: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            none: "none";
+            device: "device";
+        }>>;
         device: z.ZodOptional<z.ZodString>;
         codec: z.ZodOptional<z.ZodString>;
         delay_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    video_passthrough: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        force: "force";
+        off: "off";
+    }>>;
 }, z.core.$strip>;
 export type CerastreamConfig = z.infer<typeof cerastreamConfigSchema>;
 export type PartialCerastreamConfig = z.input<typeof cerastreamConfigSchema>;
@@ -159,6 +198,14 @@ export declare const captureDeviceSchema: z.ZodObject<{
         network: "network";
     }>>;
     alsa_card_id: z.ZodOptional<z.ZodString>;
+    product_name: z.ZodOptional<z.ZodString>;
+    transport: z.ZodOptional<z.ZodEnum<{
+        hdmi: "hdmi";
+        usb: "usb";
+        bluetooth: "bluetooth";
+        onboard: "onboard";
+    }>>;
+    stable_id: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CaptureDevice = z.infer<typeof captureDeviceSchema>;
 export declare const srtStatsSchema: z.ZodObject<{

package/dist/types.js

@@ -18,6 +18,16 @@ export const previewTierSchema = z.enum(["webcodecs", "webrtc"]);
 // platform default. Wire values are the codec id strings the encoder caps also
 // advertise ("h264"/"h265") — never an encoder element name.
 export const videoCodecSchema = z.enum(["h264", "h265"]);
+// Same-codec passthrough policy (0.5.0, additive). Absent ⇒ "auto". "auto" =
+// passthrough only when adaptive bitrate is inactive and eligibility holds;
+// "force" = passthrough whenever eligible (typed start failure otherwise);
+// "off" = always transcode. See schema.md and the engine's layer-C matrix.
+export const videoPassthroughSchema = z.enum(["auto", "force", "off"]);
+// Which surface owns the running bitrate, reported additively on a set-bitrate /
+// reload-config response (0.5.0). "encoder" = applied; "source-fixed" = a
+// passthrough graph fixes the bitrate at the source, so the request was NOT
+// applied (paired with reason "passthrough").
+export const bitrateControlSchema = z.enum(["encoder", "source-fixed"]);
 // Engine-typed capture-device family (0.4.0, additive). CeraUI groups a device
 // by the engine's resolved kind (a UVC/USB dongle is uvc_h264/mjpeg, never
 // mislabeled HDMI). Absent ⇒ CeraUI falls back to a bus/name heuristic.
@@ -31,6 +41,17 @@ export const captureDeviceKindSchema = z.enum([
     "test",
     "network",
 ]);
+// How a capture device is physically attached (Todo 20, additive). The transport
+// tag CeraUI renders beside the product name (e.g. "RØDE NT-USB · USB"). Distinct
+// from captureDeviceKind: an HDMI-to-USB dongle is kind:uvc_h264 but transport:usb,
+// while the SoC's dedicated HDMI-RX port is transport:hdmi. Absent on a legacy
+// producer or when no hint identifies a transport.
+export const deviceTransportSchema = z.enum([
+    "usb",
+    "hdmi",
+    "bluetooth",
+    "onboard",
+]);
 // ---- config sub-schemas (canonical; reused by `start` + the unified config) ----
 /** SRT transport config. Mirrors schema.md `start.srt` exactly. */
 export const srtConfigSchema = z.object({
@@ -67,7 +88,15 @@ export const bitrateConfigSchema = z
  * later, negative = earlier); it is clamped to ±AUDIO_DELAY_MAX_MS when applied,
  * never rejected — so the schema does NOT bound it.
  */
+// How the program audio is sourced (0.6.0, additive). "none" = no audio branch
+// (video-only TS); "default" = embedded audio for a network source, the selected
+// device or a silent track for a capture source; "device" = the selected ALSA
+// leg (requires `device`). Absent ⇒ legacy inference from `device`/source kind,
+// 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 audioConfigSchema = z.object({
+    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")
     delay_ms: z.number().int().optional(), // signed A/V-sync delay (clamped at apply)
@@ -87,6 +116,7 @@ export const cerastreamConfigSchema = z.object({
     resolution: z.string().optional(), // additive (0.4.0): "WxH" pixel form (never a UI token)
     framerate: z.number().optional(), // additive (0.4.0): fps as a number, e.g. 29.97
     audio: audioConfigSchema.optional(), // additive (0.4.0): audio device/codec/signed delay
+    video_passthrough: videoPassthroughSchema.optional(), // additive (0.5.0): auto|force|off; absent ⇒ auto
 });
 // convenience defaults for building a config client-side
 export const DEFAULT_BITRATE_CONFIG = {
@@ -110,6 +140,9 @@ export const captureDeviceSchema = z.object({
     caps: z.array(captureCapSchema).optional(),
     kind: captureDeviceKindSchema.optional(), // additive (0.4.0): engine-typed device family; absent on legacy producers
     alsa_card_id: z.string().optional(), // additive: ALSA card id for media_class:audio devices only; absent on video + legacy producers
+    product_name: z.string().optional(), // additive (Todo 20): real product name, deduped with a #N suffix when shared; absent ⇒ use display_name
+    transport: deviceTransportSchema.optional(), // additive (Todo 20): how the device is attached; absent on legacy producers
+    stable_id: z.string().optional(), // additive (Todo 20): reboot-stable hardware identity, distinct from input_id/device_path
 });
 // ---- transport telemetry (srt-stats event payload) ----
 export const srtStatsSchema = z.object({

package/package.json

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