@ceralive/cerastream 2026.7.4 → 2026.7.6

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.10.0";
+export declare const SCHEMA_VERSION: "0.11.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}. */
@@ -63,7 +63,7 @@ export declare const PROFILE_CATALOG_VERSION: "1.0.0";
  * ignores the field) never applies a semantic the caller assumed. Mirrors the
  * Rust `ENGINE_FEATURES`.
  */
-export declare const ENGINE_FEATURES: readonly ["video-passthrough"];
+export declare const ENGINE_FEATURES: readonly ["video-passthrough", "input-mode"];
 /** 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.10.0";
+export const SCHEMA_VERSION = "0.11.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}. */
@@ -72,7 +72,7 @@ export const PROFILE_CATALOG_VERSION = "1.0.0";
  * ignores the field) never applies a semantic the caller assumed. Mirrors the
  * Rust `ENGINE_FEATURES`.
  */
-export const ENGINE_FEATURES = ["video-passthrough"];
+export const ENGINE_FEATURES = ["video-passthrough", "input-mode"];
 /** 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

@@ -88,8 +88,21 @@ export declare const processErrorCodeSchema: z.ZodEnum<{
     pipeline_stall: "pipeline_stall";
     srt_connect_failed: "srt_connect_failed";
     srt_connection_lost: "srt_connection_lost";
+    capture_unrecoverable: "capture_unrecoverable";
 }>;
 export type ProcessErrorCode = z.infer<typeof processErrorCodeSchema>;
+/**
+ * Why a capture device became `capture_unrecoverable` — the `reason` field of the
+ * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.
+ */
+export declare const captureUnrecoverableReasonSchema: z.ZodEnum<{
+    node_absent_reprobe_disabled: "node_absent_reprobe_disabled";
+    reprobe_no_reenumeration: "reprobe_no_reenumeration";
+    reprobe_identity_changed: "reprobe_identity_changed";
+    reprobe_node_still_absent: "reprobe_node_still_absent";
+    reprobe_unavailable: "reprobe_unavailable";
+}>;
+export type CaptureUnrecoverableReason = z.infer<typeof captureUnrecoverableReasonSchema>;
 /** Origin of a Tier 2 runtime error (the notification channel CeraUI routes on). */
 export declare const processErrorSourceSchema: z.ZodEnum<{
     srtla: "srtla";

package/dist/errors.js

@@ -124,6 +124,21 @@ export const processErrorCodeSchema = z.enum([
     "pipeline_stall",
     "srt_connect_failed",
     "srt_connection_lost",
+    // TERMINAL, unlike capture_video_error: the device is still on the bus but the
+    // engine has exhausted recovery, so a UI that keeps showing "reconnecting"
+    // would be lying. Always carries a captureUnrecoverableReasonSchema `reason`.
+    "capture_unrecoverable",
+]);
+/**
+ * Why a capture device became `capture_unrecoverable` — the `reason` field of the
+ * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.
+ */
+export const captureUnrecoverableReasonSchema = z.enum([
+    "node_absent_reprobe_disabled",
+    "reprobe_no_reenumeration",
+    "reprobe_identity_changed",
+    "reprobe_node_still_absent",
+    "reprobe_unavailable",
 ]);
 /** Origin of a Tier 2 runtime error (the notification channel CeraUI routes on). */
 export const processErrorSourceSchema = z.enum(["srtla", "engine"]);

package/dist/events.d.ts

@@ -20,6 +20,37 @@ export declare const activeEncodeSchema: z.ZodObject<{
     pipeline_playing: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ActiveEncode = z.infer<typeof activeEncodeSchema>;
+/**
+ * What this session's PREVIEW branch is actually encoding with (additive),
+ * reported on the `status` event as `preview_encoder_realized`. A separate
+ * realized fact from {@link activeEncodeSchema}, which describes the EGRESS
+ * encode — the two are different graph branches and are independently absent.
+ *
+ * Present only while a session has a preview branch spliced into its graph (the
+ * branch exists for the life of the session even while its valve is closed).
+ * ABSENT means "no preview branch, or a legacy emitter" — which is NOT
+ * `mode: "software"` (a branch exists and encodes in software) and NOT
+ * `preview.preview_hw_capability === false` (the board publishes no preview
+ * encoder at all). Those three states must never be defaulted into each other.
+ *
+ * `mode` is the ACTIVE mode. The REQUESTED mode is deliberately not an engine
+ * fact: it lives in CeraUI's persisted config.
+ */
+export declare const previewEncoderRealizedSchema: z.ZodObject<{
+    selected_element: z.ZodOptional<z.ZodString>;
+    realized_element: z.ZodString;
+    mode: z.ZodEnum<{
+        software: "software";
+        hardware: "hardware";
+    }>;
+    fallback_reason: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        code: z.ZodLiteral<"factory-missing">;
+    }, z.core.$strip>, z.ZodObject<{
+        code: z.ZodLiteral<"property-failure">;
+        property: z.ZodString;
+    }, z.core.$strip>], "code">>;
+}, z.core.$strip>;
+export type PreviewEncoderRealized = z.infer<typeof previewEncoderRealizedSchema>;
 /**
  * `status` event — stream state change + heartbeat. The trailing fields are
  * additive: the `buffering*` / `spooled_bytes` / `data_headroom_bytes` /
@@ -28,7 +59,9 @@ export type ActiveEncode = z.infer<typeof activeEncodeSchema>;
  * `active_profile` (srt-receive-profiles) reports the profile/config the stream is
  * running under and is absent on a legacy emitter or a bare state-only heartbeat;
  * `active_encode` (0.4.0) reports the resolved runtime encode and is absent on a
- * legacy emitter or a bare state-only heartbeat.
+ * legacy emitter or a bare state-only heartbeat; `preview_encoder_realized`
+ * reports the PREVIEW branch's own encoder and is absent when the session has no
+ * preview branch.
  */
 export declare const statusEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"status">;
@@ -59,6 +92,20 @@ export declare const statusEventSchema: z.ZodObject<{
         frames_emitted: z.ZodOptional<z.ZodNumber>;
         pipeline_playing: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
+    preview_encoder_realized: z.ZodOptional<z.ZodObject<{
+        selected_element: z.ZodOptional<z.ZodString>;
+        realized_element: z.ZodString;
+        mode: z.ZodEnum<{
+            software: "software";
+            hardware: "hardware";
+        }>;
+        fallback_reason: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            code: z.ZodLiteral<"factory-missing">;
+        }, z.core.$strip>, z.ZodObject<{
+            code: z.ZodLiteral<"property-failure">;
+            property: z.ZodString;
+        }, z.core.$strip>], "code">>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Payload of a {@link statusEventSchema} event. */
 export type StatusEvent = z.infer<typeof statusEventSchema>;
@@ -115,6 +162,25 @@ export declare const deviceEventSchema: z.ZodObject<{
             test: "test";
             network: "network";
         }>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            pipeline_kind: z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>;
+            caps: z.ZodArray<z.ZodObject<{
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
         product_name: z.ZodOptional<z.ZodString>;
         transport: z.ZodOptional<z.ZodEnum<{
@@ -164,12 +230,14 @@ export declare const runtimeErrorEventSchema: z.ZodObject<{
         pipeline_stall: "pipeline_stall";
         srt_connect_failed: "srt_connect_failed";
         srt_connection_lost: "srt_connection_lost";
+        capture_unrecoverable: "capture_unrecoverable";
     }>;
     source: z.ZodEnum<{
         srtla: "srtla";
         engine: "engine";
     }>;
     reason: z.ZodOptional<z.ZodString>;
+    selected: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Payload of a {@link runtimeErrorEventSchema} event. */
 export type RuntimeErrorEvent = z.infer<typeof runtimeErrorEventSchema>;
@@ -268,6 +336,20 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         frames_emitted: z.ZodOptional<z.ZodNumber>;
         pipeline_playing: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
+    preview_encoder_realized: z.ZodOptional<z.ZodObject<{
+        selected_element: z.ZodOptional<z.ZodString>;
+        realized_element: z.ZodString;
+        mode: z.ZodEnum<{
+            software: "software";
+            hardware: "hardware";
+        }>;
+        fallback_reason: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            code: z.ZodLiteral<"factory-missing">;
+        }, z.core.$strip>, z.ZodObject<{
+            code: z.ZodLiteral<"property-failure">;
+            property: z.ZodString;
+        }, z.core.$strip>], "code">>;
+    }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"switch">;
     seq: z.ZodNumber;
@@ -312,6 +394,25 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             test: "test";
             network: "network";
         }>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            pipeline_kind: z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>;
+            caps: z.ZodArray<z.ZodObject<{
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
         product_name: z.ZodOptional<z.ZodString>;
         transport: z.ZodOptional<z.ZodEnum<{
@@ -346,12 +447,14 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         pipeline_stall: "pipeline_stall";
         srt_connect_failed: "srt_connect_failed";
         srt_connection_lost: "srt_connection_lost";
+        capture_unrecoverable: "capture_unrecoverable";
     }>;
     source: z.ZodEnum<{
         srtla: "srtla";
         engine: "engine";
     }>;
     reason: z.ZodOptional<z.ZodString>;
+    selected: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"preview">;
     seq: z.ZodNumber;
@@ -424,6 +527,20 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             frames_emitted: z.ZodOptional<z.ZodNumber>;
             pipeline_playing: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
+        preview_encoder_realized: z.ZodOptional<z.ZodObject<{
+            selected_element: z.ZodOptional<z.ZodString>;
+            realized_element: z.ZodString;
+            mode: z.ZodEnum<{
+                software: "software";
+                hardware: "hardware";
+            }>;
+            fallback_reason: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                code: z.ZodLiteral<"factory-missing">;
+            }, z.core.$strip>, z.ZodObject<{
+                code: z.ZodLiteral<"property-failure">;
+                property: z.ZodString;
+            }, z.core.$strip>], "code">>;
+        }, z.core.$strip>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"switch">;
         seq: z.ZodNumber;
@@ -468,6 +585,25 @@ export declare const cerastreamEventSchema: z.ZodObject<{
                 test: "test";
                 network: "network";
             }>>;
+            modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                media_type: z.ZodString;
+                pipeline_kind: z.ZodEnum<{
+                    audio: "audio";
+                    hdmi: "hdmi";
+                    uvc_h264: "uvc_h264";
+                    uvc_h265: "uvc_h265";
+                    mjpeg: "mjpeg";
+                    camlink: "camlink";
+                    test: "test";
+                    network: "network";
+                }>;
+                caps: z.ZodArray<z.ZodObject<{
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    framerate: z.ZodOptional<z.ZodString>;
+                    media_type: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
             product_name: z.ZodOptional<z.ZodString>;
             transport: z.ZodOptional<z.ZodEnum<{
@@ -502,12 +638,14 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             pipeline_stall: "pipeline_stall";
             srt_connect_failed: "srt_connect_failed";
             srt_connection_lost: "srt_connection_lost";
+            capture_unrecoverable: "capture_unrecoverable";
         }>;
         source: z.ZodEnum<{
             srtla: "srtla";
             engine: "engine";
         }>;
         reason: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"preview">;
         seq: z.ZodNumber;
@@ -584,6 +722,20 @@ export declare const eventSchemas: {
             frames_emitted: z.ZodOptional<z.ZodNumber>;
             pipeline_playing: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
+        preview_encoder_realized: z.ZodOptional<z.ZodObject<{
+            selected_element: z.ZodOptional<z.ZodString>;
+            realized_element: z.ZodString;
+            mode: z.ZodEnum<{
+                software: "software";
+                hardware: "hardware";
+            }>;
+            fallback_reason: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                code: z.ZodLiteral<"factory-missing">;
+            }, z.core.$strip>, z.ZodObject<{
+                code: z.ZodLiteral<"property-failure">;
+                property: z.ZodString;
+            }, z.core.$strip>], "code">>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     readonly switch: z.ZodObject<{
         type: z.ZodLiteral<"switch">;
@@ -630,6 +782,25 @@ export declare const eventSchemas: {
                 test: "test";
                 network: "network";
             }>>;
+            modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                media_type: z.ZodString;
+                pipeline_kind: z.ZodEnum<{
+                    audio: "audio";
+                    hdmi: "hdmi";
+                    uvc_h264: "uvc_h264";
+                    uvc_h265: "uvc_h265";
+                    mjpeg: "mjpeg";
+                    camlink: "camlink";
+                    test: "test";
+                    network: "network";
+                }>;
+                caps: z.ZodArray<z.ZodObject<{
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    framerate: z.ZodOptional<z.ZodString>;
+                    media_type: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
             product_name: z.ZodOptional<z.ZodString>;
             transport: z.ZodOptional<z.ZodEnum<{
@@ -667,12 +838,14 @@ export declare const eventSchemas: {
             pipeline_stall: "pipeline_stall";
             srt_connect_failed: "srt_connect_failed";
             srt_connection_lost: "srt_connection_lost";
+            capture_unrecoverable: "capture_unrecoverable";
         }>;
         source: z.ZodEnum<{
             srtla: "srtla";
             engine: "engine";
         }>;
         reason: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     readonly preview: z.ZodObject<{
         type: z.ZodLiteral<"preview">;

package/dist/events.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { processErrorCodeSchema, processErrorSourceSchema, } from "./errors.js";
-import { captureDeviceSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, streamStateSchema, } from "./types.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:
 // { type, seq, … }. `type` discriminates; `seq` is a per-type monotonic counter.
@@ -25,6 +25,28 @@ export const activeEncodeSchema = z.object({
     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)
 });
+/**
+ * What this session's PREVIEW branch is actually encoding with (additive),
+ * reported on the `status` event as `preview_encoder_realized`. A separate
+ * realized fact from {@link activeEncodeSchema}, which describes the EGRESS
+ * encode — the two are different graph branches and are independently absent.
+ *
+ * Present only while a session has a preview branch spliced into its graph (the
+ * branch exists for the life of the session even while its valve is closed).
+ * ABSENT means "no preview branch, or a legacy emitter" — which is NOT
+ * `mode: "software"` (a branch exists and encodes in software) and NOT
+ * `preview.preview_hw_capability === false` (the board publishes no preview
+ * encoder at all). Those three states must never be defaulted into each other.
+ *
+ * `mode` is the ACTIVE mode. The REQUESTED mode is deliberately not an engine
+ * fact: it lives in CeraUI's persisted config.
+ */
+export const previewEncoderRealizedSchema = z.object({
+    selected_element: z.string().optional(), // the element the platform's HAL descriptor publishes; absent ⇒ this board publishes none
+    realized_element: z.string(), // the element actually built into the preview branch, e.g. "x264enc"/"mpph264enc"
+    mode: previewEncodeModeSchema, // the encoder family actually realized — never the request
+    fallback_reason: previewEncodeFallbackSchema.optional(), // why a hardware request is in software; absent is the normal case
+});
 /**
  * `status` event — stream state change + heartbeat. The trailing fields are
  * additive: the `buffering*` / `spooled_bytes` / `data_headroom_bytes` /
@@ -33,7 +55,9 @@ export const activeEncodeSchema = z.object({
  * `active_profile` (srt-receive-profiles) reports the profile/config the stream is
  * running under and is absent on a legacy emitter or a bare state-only heartbeat;
  * `active_encode` (0.4.0) reports the resolved runtime encode and is absent on a
- * legacy emitter or a bare state-only heartbeat.
+ * legacy emitter or a bare state-only heartbeat; `preview_encoder_realized`
+ * reports the PREVIEW branch's own encoder and is absent when the session has no
+ * preview branch.
  */
 export const statusEventSchema = z.object({
     type: z.literal("status"),
@@ -47,6 +71,7 @@ export const statusEventSchema = z.object({
     data_headroom_bytes: z.number().int().nonnegative().optional(),
     disk_warning: z.boolean().optional(),
     active_encode: activeEncodeSchema.optional(),
+    preview_encoder_realized: previewEncoderRealizedSchema.optional(),
 });
 /**
  * `switch` event — active input changed (manual or failover). `media_class` is
@@ -93,6 +118,7 @@ export const runtimeErrorEventSchema = z.object({
     code: processErrorCodeSchema, // Tier 2 (errors.ts)
     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
 });
 /** `preview` event — a preview-session lifecycle/phase change. */
 export const previewEventSchema = z.object({

package/dist/messages.d.ts

@@ -42,6 +42,16 @@ export declare const startParamsSchema: z.ZodObject<{
         force: "force";
         off: "off";
     }>>;
+    input_mode: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>>;
 }, z.core.$strip>;
 export type StartParams = z.infer<typeof startParamsSchema>;
 export declare const startResultSchema: z.ZodObject<{
@@ -85,6 +95,10 @@ export declare const reloadConfigParamsSchema: z.ZodObject<{
         delay_ms_signed: z.ZodOptional<z.ZodNumber>;
         meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
+    preview_encode: z.ZodOptional<z.ZodEnum<{
+        software: "software";
+        hardware: "hardware";
+    }>>;
 }, z.core.$strip>;
 export type ReloadConfigParams = z.infer<typeof reloadConfigParamsSchema>;
 export declare const reloadConfigResultSchema: z.ZodObject<{
@@ -106,6 +120,10 @@ export declare const reloadConfigResultSchema: z.ZodObject<{
             delay_ms_signed: z.ZodOptional<z.ZodNumber>;
             meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>;
+        preview_encode: z.ZodOptional<z.ZodEnum<{
+            software: "software";
+            hardware: "hardware";
+        }>>;
     }, z.core.$strip>;
     bitrate_control: z.ZodOptional<z.ZodEnum<{
         encoder: "encoder";
@@ -193,6 +211,25 @@ export declare const listDevicesResultSchema: z.ZodObject<{
             test: "test";
             network: "network";
         }>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            pipeline_kind: z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>;
+            caps: z.ZodArray<z.ZodObject<{
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
         product_name: z.ZodOptional<z.ZodString>;
         transport: z.ZodOptional<z.ZodEnum<{
@@ -328,6 +365,7 @@ export declare const previewAvailabilitySchema: z.ZodObject<{
     enabled: z.ZodBoolean;
     port: z.ZodOptional<z.ZodNumber>;
     bound: z.ZodBoolean;
+    preview_hw_capability: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type PreviewAvailability = z.infer<typeof previewAvailabilitySchema>;
 export declare const getCapabilitiesResultSchema: z.ZodObject<{
@@ -375,6 +413,7 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
         enabled: z.ZodBoolean;
         port: z.ZodOptional<z.ZodNumber>;
         bound: z.ZodBoolean;
+        preview_hw_capability: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     network_embedded_audio: z.ZodOptional<z.ZodBoolean>;
     features: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -389,6 +428,16 @@ export declare const changeConfigParamsSchema: z.ZodObject<{
         h265: "h265";
     }>>;
     input_id: z.ZodOptional<z.ZodString>;
+    input_mode: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>>;
 }, z.core.$strip>;
 export type ChangeConfigParams = z.infer<typeof changeConfigParamsSchema>;
 export declare const changeConfigResultSchema: z.ZodObject<{
@@ -480,6 +529,16 @@ export declare const requestSchemas: {
                 force: "force";
                 off: "off";
             }>>;
+            input_mode: z.ZodOptional<z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
             session_id: z.ZodString;
@@ -523,6 +582,10 @@ export declare const requestSchemas: {
                 delay_ms_signed: z.ZodOptional<z.ZodNumber>;
                 meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             }, z.core.$strip>>;
+            preview_encode: z.ZodOptional<z.ZodEnum<{
+                software: "software";
+                hardware: "hardware";
+            }>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
             applied: z.ZodObject<{
@@ -543,6 +606,10 @@ export declare const requestSchemas: {
                     delay_ms_signed: z.ZodOptional<z.ZodNumber>;
                     meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 }, z.core.$strip>>;
+                preview_encode: z.ZodOptional<z.ZodEnum<{
+                    software: "software";
+                    hardware: "hardware";
+                }>>;
             }, z.core.$strip>;
             bitrate_control: z.ZodOptional<z.ZodEnum<{
                 encoder: "encoder";
@@ -614,6 +681,25 @@ export declare const requestSchemas: {
                     test: "test";
                     network: "network";
                 }>>;
+                modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    media_type: z.ZodString;
+                    pipeline_kind: z.ZodEnum<{
+                        audio: "audio";
+                        hdmi: "hdmi";
+                        uvc_h264: "uvc_h264";
+                        uvc_h265: "uvc_h265";
+                        mjpeg: "mjpeg";
+                        camlink: "camlink";
+                        test: "test";
+                        network: "network";
+                    }>;
+                    caps: z.ZodArray<z.ZodObject<{
+                        width: z.ZodOptional<z.ZodNumber>;
+                        height: z.ZodOptional<z.ZodNumber>;
+                        framerate: z.ZodOptional<z.ZodString>;
+                        media_type: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>>;
                 alsa_card_id: z.ZodOptional<z.ZodString>;
                 product_name: z.ZodOptional<z.ZodString>;
                 transport: z.ZodOptional<z.ZodEnum<{

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, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, videoCodecSchema, } from "./types.js";
+import { 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 ----
@@ -45,6 +45,12 @@ export const reloadConfigParamsSchema = z.object({
         meter_device: z.string().nullable().optional(),
     })
         .optional(),
+    // Absent leaves the engine's current preview-encoder selection unchanged. This
+    // belongs on `reload-config` rather than `change-config`: the preview encoder is
+    // fixed when a session graph is built, so it takes effect on the NEXT stream
+    // session, and routing it through the transactional method would restart a live
+    // stream to change a preview setting.
+    preview_encode: previewEncodeModeSchema.optional(),
 });
 export const reloadConfigResultSchema = z.object({
     applied: reloadConfigParamsSchema, // post-clamp values actually applied
@@ -179,6 +185,15 @@ export const previewAvailabilitySchema = z.object({
     enabled: z.boolean(),
     port: z.number().int().min(1).max(65535).optional(), // present when a listener is (or would be) bound
     bound: z.boolean(),
+    // Whether this PLATFORM publishes a hardware preview encoder at all — the fact
+    // that decides whether a hardware-preview toggle may be offered. It rides the
+    // capability fetch rather than stream status because a consumer reads
+    // capabilities while IDLE, which is exactly when the operator picks the setting.
+    // Three readings, none interchangeable: absent ⇒ legacy engine, capability
+    // UNKNOWN (never assume false); false ⇒ this board publishes none, hide the
+    // toggle; true ⇒ it does. Independent of whether any session is realizing it
+    // (`status.preview_encoder_realized`).
+    preview_hw_capability: z.boolean().optional(),
 });
 export const getCapabilitiesResultSchema = z.object({
     platform: platformCapsSchema,
@@ -207,6 +222,13 @@ export const changeConfigParamsSchema = z
     framerate: z.number().optional(),
     codec: videoCodecSchema.optional(),
     input_id: z.string().optional(),
+    // Switching a LIVE device between a libuvc family (uvc_h264/uvc_h265) and
+    // the v4l2 mjpeg family is NOT a plain rebuild: libuvc detaches uvcvideo, so
+    // the /dev/videoN node the mjpeg leg needs does not exist until the hold is
+    // released — and it then returns asynchronously, possibly renumbered. The
+    // engine runs a release → re-enumeration-barrier → open transaction and
+    // rolls back honestly (reason: mode_barrier_timeout) if the barrier expires.
+    input_mode: captureDeviceKindSchema.optional(),
 })
     .refine((delta) => Object.keys(delta).length > 0, {
     message: "change-config delta must carry at least one field",

package/dist/types.d.ts

@@ -27,6 +27,18 @@ export declare const previewTierSchema: z.ZodEnum<{
     webrtc: "webrtc";
 }>;
 export type PreviewTier = z.infer<typeof previewTierSchema>;
+export declare const previewEncodeModeSchema: z.ZodEnum<{
+    software: "software";
+    hardware: "hardware";
+}>;
+export type PreviewEncodeMode = z.infer<typeof previewEncodeModeSchema>;
+export declare const previewEncodeFallbackSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    code: z.ZodLiteral<"factory-missing">;
+}, z.core.$strip>, z.ZodObject<{
+    code: z.ZodLiteral<"property-failure">;
+    property: z.ZodString;
+}, z.core.$strip>], "code">;
+export type PreviewEncodeFallback = z.infer<typeof previewEncodeFallbackSchema>;
 export declare const videoCodecSchema: z.ZodEnum<{
     h264: "h264";
     h265: "h265";
@@ -164,6 +176,16 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
         force: "force";
         off: "off";
     }>>;
+    input_mode: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>>;
 }, z.core.$strip>;
 export type CerastreamConfig = z.infer<typeof cerastreamConfigSchema>;
 export type PartialCerastreamConfig = z.input<typeof cerastreamConfigSchema>;
@@ -180,6 +202,26 @@ export declare const captureCapSchema: z.ZodObject<{
     media_type: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CaptureCap = z.infer<typeof captureCapSchema>;
+export declare const captureModeSchema: z.ZodObject<{
+    media_type: z.ZodString;
+    pipeline_kind: z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>;
+    caps: z.ZodArray<z.ZodObject<{
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        framerate: z.ZodOptional<z.ZodString>;
+        media_type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CaptureMode = z.infer<typeof captureModeSchema>;
 export declare const captureDeviceSchema: z.ZodObject<{
     input_id: z.ZodString;
     device_path: z.ZodString;
@@ -204,6 +246,25 @@ export declare const captureDeviceSchema: z.ZodObject<{
         test: "test";
         network: "network";
     }>>;
+    modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        media_type: z.ZodString;
+        pipeline_kind: z.ZodEnum<{
+            audio: "audio";
+            hdmi: "hdmi";
+            uvc_h264: "uvc_h264";
+            uvc_h265: "uvc_h265";
+            mjpeg: "mjpeg";
+            camlink: "camlink";
+            test: "test";
+            network: "network";
+        }>;
+        caps: z.ZodArray<z.ZodObject<{
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            framerate: z.ZodOptional<z.ZodString>;
+            media_type: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     alsa_card_id: z.ZodOptional<z.ZodString>;
     product_name: z.ZodOptional<z.ZodString>;
     transport: z.ZodOptional<z.ZodEnum<{

package/dist/types.js

@@ -14,6 +14,22 @@ export const inputModeSchema = z.enum(["manual", "auto"]);
 export const balancerAlgorithmSchema = z.enum(["adaptive", "fixed", "aimd"]);
 export const mediaClassSchema = z.enum(["video", "audio"]);
 export const previewTierSchema = z.enum(["webcodecs", "webrtc"]);
+// Which encoder the LIVE preview branch uses. Set through `reload-config`
+// (additive) and reported back as the ACTIVE mode on stream status. Applies to
+// the NEXT stream session: the preview encoder is fixed when a session graph is
+// built, so this never swaps an encoder mid-stream.
+export const previewEncodeModeSchema = z.enum(["software", "hardware"]);
+// Why a `hardware` preview request is encoding in software anyway — a tagged
+// union so a consumer branches on `code` and still receives the detail a code
+// carries. `property-failure` names the property the element refused, which is
+// the difference between "hardware preview is broken" and "this image's encoder
+// plugin does not take `rc-mode`". ABSENT is the normal case (software was
+// chosen, hardware was delivered, or the board never offered the toggle) — there
+// is deliberately no `{code:"none"}` sentinel.
+export const previewEncodeFallbackSchema = z.discriminatedUnion("code", [
+    z.object({ code: z.literal("factory-missing") }),
+    z.object({ code: z.literal("property-failure"), property: z.string() }),
+]);
 // Requested egress video codec (0.4.0, additive). Absent ⇒ the engine picks its
 // platform default. Wire values are the codec id strings the encoder caps also
 // advertise ("h264"/"h265") — never an encoder element name.
@@ -129,6 +145,7 @@ export const cerastreamConfigSchema = z.object({
     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
+    input_mode: captureDeviceKindSchema.optional(), // additive (0.11.0): which MODE family of the selected device to capture in, naming a list-devices modes[].pipeline_kind. Absent ⇒ the engine's precedence pick (h265 → h264 → mjpeg → raw). The ONLY way to reach the non-precedence family of a dual-format camera; a family the device does not expose is a typed cerastream.params.invalid, never a silent fallback
 });
 // convenience defaults for building a config client-side
 export const DEFAULT_BITRATE_CONFIG = {
@@ -144,13 +161,33 @@ export const captureCapSchema = z.object({
     framerate: z.string().optional(), // e.g. "30/1"
     media_type: z.string().optional(), // e.g. "video/x-h265"; additive, absent on legacy producers
 });
+// One startable capture MODE family of a device (0.11.0, additive).
+//
+// A capture device is not necessarily one format family: the DJI Osmo Pocket 3
+// exposes H.264 AND MJPEG on the SAME /dev/video1 node (selection is a
+// VIDIOC_S_FMT pixelformat choice, not a different node). The scalar
+// captureDevice.kind can only name ONE family, so before this contract a
+// dual-format camera was classified uvc_h264 by precedence and its MJPEG ladder
+// was unreachable — visible, but impossible to start.
+//
+// pipeline_kind is exactly what a caller echoes back as start.input_mode to drive
+// the device in this family. caps is the ladder for THIS family ALONE, never the
+// device-wide union: on the Osmo, H.264 offers 4K at 60/50/48 fps while MJPEG
+// tops out at 30, so a merged list would advertise 4K60 MJPEG — a mode the device
+// cannot deliver.
+export const captureModeSchema = z.object({
+    media_type: z.string(), // e.g. "image/jpeg"
+    pipeline_kind: captureDeviceKindSchema, // the value start.input_mode takes to select this mode
+    caps: z.array(captureCapSchema), // the {w × h × framerate} ladder for THIS media type only
+});
 export const captureDeviceSchema = z.object({
     input_id: z.string(), // stable id used by switch-input
     device_path: z.string(), // e.g. /dev/video0 (dedup key)
     display_name: z.string(),
     media_class: mediaClassSchema,
     caps: z.array(captureCapSchema).optional(),
-    kind: captureDeviceKindSchema.optional(), // additive (0.4.0): engine-typed device family; absent on legacy producers
+    kind: captureDeviceKindSchema.optional(), // additive (0.4.0): engine-typed device family; absent on legacy producers. A dual-format device reports its HIGHEST-PRECEDENCE family here; the full set is `modes`
+    modes: z.array(captureModeSchema).optional(), // additive (0.11.0): every startable mode family, each with its OWN caps ladder; absent on legacy producers, on audio rows, and on a device with no probed caps. When present it ALWAYS contains the family named by `kind`, first
     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

package/package.json

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