@ceralive/cerastream 2026.9.0 → 2026.9.2

package/README.md

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

package/dist/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.12.0';
+export declare const SCHEMA_VERSION: '0.13.0';
 /** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
 export declare const DEFAULT_IPC_DIR: '/run/cerastream';
 /** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */

package/dist/constants.js

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

package/dist/errors.d.ts

@@ -99,6 +99,7 @@ export declare const captureCauseSchema: z.ZodEnum<{
     device_busy: "device_busy";
     negotiation_failed: "negotiation_failed";
     no_signal: "no_signal";
+    no_silicon_converter: "no_silicon_converter";
 }>;
 export type CaptureCause = z.infer<typeof captureCauseSchema>;
 export declare const captureCauseEntrySchema: z.ZodObject<{
@@ -107,6 +108,7 @@ export declare const captureCauseEntrySchema: z.ZodObject<{
         device_busy: "device_busy";
         negotiation_failed: "negotiation_failed";
         no_signal: "no_signal";
+        no_silicon_converter: "no_silicon_converter";
     }>;
 }, z.core.$strip>;
 export type CaptureCauseEntry = z.infer<typeof captureCauseEntrySchema>;

package/dist/errors.js

@@ -138,7 +138,12 @@ export const processErrorCodeSchema = z.enum([
     // would be lying. Always carries a captureUnrecoverableReasonSchema `reason`.
     'capture_unrecoverable',
 ]);
-export const captureCauseSchema = z.enum(['negotiation_failed', 'no_signal', 'device_busy']);
+export const captureCauseSchema = z.enum([
+    'negotiation_failed',
+    'no_signal',
+    'device_busy',
+    'no_silicon_converter',
+]);
 export const captureCauseEntrySchema = z.object({
     device: z.string(),
     cause: captureCauseSchema,

package/dist/events.d.ts

@@ -243,6 +243,7 @@ export declare const runtimeErrorEventSchema: z.ZodObject<{
         device_busy: "device_busy";
         negotiation_failed: "negotiation_failed";
         no_signal: "no_signal";
+        no_silicon_converter: "no_silicon_converter";
     }>>;
 }, z.core.$strip>;
 /** Payload of a {@link runtimeErrorEventSchema} event. */
@@ -466,6 +467,7 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         device_busy: "device_busy";
         negotiation_failed: "negotiation_failed";
         no_signal: "no_signal";
+        no_silicon_converter: "no_silicon_converter";
     }>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"preview">;
@@ -663,6 +665,7 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             device_busy: "device_busy";
             negotiation_failed: "negotiation_failed";
             no_signal: "no_signal";
+            no_silicon_converter: "no_silicon_converter";
         }>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"preview">;
@@ -869,6 +872,7 @@ export declare const eventSchemas: {
             device_busy: "device_busy";
             negotiation_failed: "negotiation_failed";
             no_signal: "no_signal";
+            no_silicon_converter: "no_silicon_converter";
         }>>;
     }, z.core.$strip>;
     readonly preview: z.ZodObject<{

package/dist/messages.d.ts

@@ -28,6 +28,10 @@ export declare const startParamsSchema: z.ZodObject<{
     resolution: z.ZodOptional<z.ZodString>;
     framerate: z.ZodOptional<z.ZodNumber>;
     audio: z.ZodOptional<z.ZodObject<{
+        backend: z.ZodOptional<z.ZodEnum<{
+            alsa: "alsa";
+            pipewire: "pipewire";
+        }>>;
         mode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             device: "device";
@@ -91,6 +95,10 @@ export declare const reloadConfigParamsSchema: z.ZodObject<{
         latency_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     audio: z.ZodOptional<z.ZodObject<{
+        backend: z.ZodOptional<z.ZodEnum<{
+            alsa: "alsa";
+            pipewire: "pipewire";
+        }>>;
         delay_ms: z.ZodOptional<z.ZodNumber>;
         delay_ms_signed: z.ZodOptional<z.ZodNumber>;
         meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -116,6 +124,10 @@ export declare const reloadConfigResultSchema: z.ZodObject<{
             latency_ms: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         audio: z.ZodOptional<z.ZodObject<{
+            backend: z.ZodOptional<z.ZodEnum<{
+                alsa: "alsa";
+                pipewire: "pipewire";
+            }>>;
             delay_ms: z.ZodOptional<z.ZodNumber>;
             delay_ms_signed: z.ZodOptional<z.ZodNumber>;
             meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -130,6 +142,7 @@ export declare const reloadConfigResultSchema: z.ZodObject<{
         "source-fixed": "source-fixed";
     }>>;
     reason: z.ZodOptional<z.ZodString>;
+    applies: z.ZodOptional<z.ZodLiteral<"next-session">>;
 }, z.core.$strip>;
 export type ReloadConfigResult = z.infer<typeof reloadConfigResultSchema>;
 export declare const setBitrateParamsSchema: z.ZodObject<{
@@ -346,6 +359,12 @@ export declare const encoderCapsSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type EncoderCaps = z.infer<typeof encoderCapsSchema>;
+export declare const platformConverterSchema: z.ZodEnum<{
+    librga: "librga";
+    none: "none";
+    "v4l2-rga2": "v4l2-rga2";
+}>;
+export type PlatformConverter = z.infer<typeof platformConverterSchema>;
 export declare const platformCapsSchema: z.ZodObject<{
     supports_h265: z.ZodBoolean;
     hardware_accelerated: z.ZodBoolean;
@@ -360,6 +379,11 @@ export declare const platformCapsSchema: z.ZodObject<{
         detected: "detected";
         override: "override";
     }>>;
+    converter: z.ZodOptional<z.ZodEnum<{
+        librga: "librga";
+        none: "none";
+        "v4l2-rga2": "v4l2-rga2";
+    }>>;
 }, z.core.$strip>;
 export type PlatformCaps = z.infer<typeof platformCapsSchema>;
 export declare const previewAvailabilitySchema: z.ZodObject<{
@@ -384,6 +408,11 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
             detected: "detected";
             override: "override";
         }>>;
+        converter: z.ZodOptional<z.ZodEnum<{
+            librga: "librga";
+            none: "none";
+            "v4l2-rga2": "v4l2-rga2";
+        }>>;
     }, z.core.$strip>;
     encoder: z.ZodObject<{
         codecs: z.ZodArray<z.ZodString>;
@@ -402,6 +431,16 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
         default_framerate: z.ZodNumber;
     }, z.core.$strip>>;
     audio_live_switch: z.ZodOptional<z.ZodBoolean>;
+    audio_backends: z.ZodOptional<z.ZodObject<{
+        supported: z.ZodArray<z.ZodEnum<{
+            alsa: "alsa";
+            pipewire: "pipewire";
+        }>>;
+        active: z.ZodEnum<{
+            alsa: "alsa";
+            pipewire: "pipewire";
+        }>;
+    }, z.core.$strip>>;
     latency_range: z.ZodOptional<z.ZodObject<{
         min: z.ZodNumber;
         default: z.ZodNumber;
@@ -516,6 +555,10 @@ export declare const requestSchemas: {
             resolution: z.ZodOptional<z.ZodString>;
             framerate: z.ZodOptional<z.ZodNumber>;
             audio: z.ZodOptional<z.ZodObject<{
+                backend: z.ZodOptional<z.ZodEnum<{
+                    alsa: "alsa";
+                    pipewire: "pipewire";
+                }>>;
                 mode: z.ZodOptional<z.ZodEnum<{
                     default: "default";
                     device: "device";
@@ -579,6 +622,10 @@ export declare const requestSchemas: {
                 latency_ms: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             audio: z.ZodOptional<z.ZodObject<{
+                backend: z.ZodOptional<z.ZodEnum<{
+                    alsa: "alsa";
+                    pipewire: "pipewire";
+                }>>;
                 delay_ms: z.ZodOptional<z.ZodNumber>;
                 delay_ms_signed: z.ZodOptional<z.ZodNumber>;
                 meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -603,6 +650,10 @@ export declare const requestSchemas: {
                     latency_ms: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>>;
                 audio: z.ZodOptional<z.ZodObject<{
+                    backend: z.ZodOptional<z.ZodEnum<{
+                        alsa: "alsa";
+                        pipewire: "pipewire";
+                    }>>;
                     delay_ms: z.ZodOptional<z.ZodNumber>;
                     delay_ms_signed: z.ZodOptional<z.ZodNumber>;
                     meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -617,6 +668,7 @@ export declare const requestSchemas: {
                 "source-fixed": "source-fixed";
             }>>;
             reason: z.ZodOptional<z.ZodString>;
+            applies: z.ZodOptional<z.ZodLiteral<"next-session">>;
         }, z.core.$strip>;
     };
     readonly 'set-bitrate': {

package/dist/messages.js

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

package/dist/types.d.ts

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

package/dist/types.js

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

package/package.json

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