@ceralive/cerastream 2026.7.5 → 2026.7.6

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>;
@@ -289,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;
@@ -466,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;
@@ -647,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">;

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

package/dist/messages.d.ts

@@ -95,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<{
@@ -116,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";
@@ -357,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<{
@@ -404,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>>;
@@ -572,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<{
@@ -592,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";

package/dist/messages.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { AUDIO_DELAY_MAX_MS } from "./constants.js";
 import { helloParamsSchema, helloResultSchema, } from "./envelope.js";
-import { balancerAlgorithmSchema, bitrateControlSchema, captureDeviceKindSchema, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, 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,

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";

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.

package/package.json

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