@ceralive/cerastream 2026.9.1 → 2026.9.3

package/README.md

@@ -9,12 +9,16 @@ 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`)
+- Typed RK3588 composition config (secondary input, six PiP/PbP layouts, alpha),
+  gated by the READY-trialled `composition` capability token
 - 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
 - Additive `client.changeConfig()` — reconfigure the live session (resolution,
-  framerate, codec, pipeline, source) as one transaction with typed rollback
+  framerate, codec, pipeline, source) as one transaction with typed rollback;
+  composition-only changes use live layout/alpha writes and secondary rebind
 
 The Zod schemas, types, and constants are the frozen wire contract; `connect()`
 drives that contract over an NDJSON/UDS transport with no native dependencies.

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.13.0';
+export declare const SCHEMA_VERSION: '0.14.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}. */
@@ -65,6 +65,8 @@ export declare const PROFILE_CATALOG_VERSION: '1.0.0';
  * the Rust `PIPEWIRE_CAPTURE_FEATURE`.
  */
 export declare const PIPEWIRE_CAPTURE_FEATURE: 'pipewire-capture';
+/** Two-leg RK3588 composition, emitted only after `rgacompositor` passes READY. */
+export declare const COMPOSITION_FEATURE: 'composition';
 /**
  * Named engine features `get-capabilities` advertises in `features`. This is the
  * fail-closed negotiation contract: CeraUI sends a new out-of-schema field ONLY
@@ -76,7 +78,7 @@ export declare const PIPEWIRE_CAPTURE_FEATURE: 'pipewire-capture';
  * array, never on membership here — a configuration-dependent token is filtered
  * out of the response the engine actually sends.
  */
-export declare const ENGINE_FEATURES: readonly ['video-passthrough', 'input-mode', 'audio-pcm-spec', "pipewire-capture"];
+export declare const ENGINE_FEATURES: readonly ['video-passthrough', 'input-mode', 'audio-pcm-spec', "pipewire-capture", "composition"];
 /** 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.13.0';
+export const SCHEMA_VERSION = '0.14.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}. */
@@ -74,6 +74,8 @@ export const PROFILE_CATALOG_VERSION = '1.0.0';
  * the Rust `PIPEWIRE_CAPTURE_FEATURE`.
  */
 export const PIPEWIRE_CAPTURE_FEATURE = 'pipewire-capture';
+/** Two-leg RK3588 composition, emitted only after `rgacompositor` passes READY. */
+export const COMPOSITION_FEATURE = 'composition';
 /**
  * Named engine features `get-capabilities` advertises in `features`. This is the
  * fail-closed negotiation contract: CeraUI sends a new out-of-schema field ONLY
@@ -90,6 +92,7 @@ export const ENGINE_FEATURES = [
     'input-mode',
     'audio-pcm-spec',
     PIPEWIRE_CAPTURE_FEATURE,
+    COMPOSITION_FEATURE,
 ];
 /** Engine binary name (systemd-owned; CeraUI never spawns it — ADR-0005). */
 export const CERASTREAM_BIN = 'cerastream';

package/dist/errors.d.ts

@@ -96,17 +96,23 @@ export declare const processErrorCodeSchema: z.ZodEnum<{
 }>;
 export type ProcessErrorCode = z.infer<typeof processErrorCodeSchema>;
 export declare const captureCauseSchema: z.ZodEnum<{
+    "composition-unsupported": "composition-unsupported";
     device_busy: "device_busy";
     negotiation_failed: "negotiation_failed";
     no_signal: "no_signal";
+    no_silicon_converter: "no_silicon_converter";
+    "secondary-unavailable": "secondary-unavailable";
 }>;
 export type CaptureCause = z.infer<typeof captureCauseSchema>;
 export declare const captureCauseEntrySchema: z.ZodObject<{
     device: z.ZodString;
     cause: z.ZodEnum<{
+        "composition-unsupported": "composition-unsupported";
         device_busy: "device_busy";
         negotiation_failed: "negotiation_failed";
         no_signal: "no_signal";
+        no_silicon_converter: "no_silicon_converter";
+        "secondary-unavailable": "secondary-unavailable";
     }>;
 }, z.core.$strip>;
 export type CaptureCauseEntry = z.infer<typeof captureCauseEntrySchema>;

package/dist/errors.js

@@ -138,7 +138,14 @@ 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',
+    'composition-unsupported',
+    'secondary-unavailable',
+]);
 export const captureCauseEntrySchema = z.object({
     device: z.string(),
     cause: captureCauseSchema,

package/dist/events.d.ts

@@ -240,9 +240,12 @@ export declare const runtimeErrorEventSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
     selected: z.ZodOptional<z.ZodBoolean>;
     capture_cause: z.ZodOptional<z.ZodEnum<{
+        "composition-unsupported": "composition-unsupported";
         device_busy: "device_busy";
         negotiation_failed: "negotiation_failed";
         no_signal: "no_signal";
+        no_silicon_converter: "no_silicon_converter";
+        "secondary-unavailable": "secondary-unavailable";
     }>>;
 }, z.core.$strip>;
 /** Payload of a {@link runtimeErrorEventSchema} event. */
@@ -463,9 +466,12 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
     selected: z.ZodOptional<z.ZodBoolean>;
     capture_cause: z.ZodOptional<z.ZodEnum<{
+        "composition-unsupported": "composition-unsupported";
         device_busy: "device_busy";
         negotiation_failed: "negotiation_failed";
         no_signal: "no_signal";
+        no_silicon_converter: "no_silicon_converter";
+        "secondary-unavailable": "secondary-unavailable";
     }>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"preview">;
@@ -660,9 +666,12 @@ export declare const cerastreamEventSchema: z.ZodObject<{
         reason: z.ZodOptional<z.ZodString>;
         selected: z.ZodOptional<z.ZodBoolean>;
         capture_cause: z.ZodOptional<z.ZodEnum<{
+            "composition-unsupported": "composition-unsupported";
             device_busy: "device_busy";
             negotiation_failed: "negotiation_failed";
             no_signal: "no_signal";
+            no_silicon_converter: "no_silicon_converter";
+            "secondary-unavailable": "secondary-unavailable";
         }>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"preview">;
@@ -866,9 +875,12 @@ export declare const eventSchemas: {
         reason: z.ZodOptional<z.ZodString>;
         selected: z.ZodOptional<z.ZodBoolean>;
         capture_cause: z.ZodOptional<z.ZodEnum<{
+            "composition-unsupported": "composition-unsupported";
             device_busy: "device_busy";
             negotiation_failed: "negotiation_failed";
             no_signal: "no_signal";
+            no_silicon_converter: "no_silicon_converter";
+            "secondary-unavailable": "secondary-unavailable";
         }>>;
     }, z.core.$strip>;
     readonly preview: z.ZodObject<{

package/dist/messages.d.ts

@@ -56,6 +56,18 @@ export declare const startParamsSchema: z.ZodObject<{
         uvc_h264: "uvc_h264";
         uvc_h265: "uvc_h265";
     }>>;
+    composition: z.ZodOptional<z.ZodObject<{
+        secondary_input_id: z.ZodString;
+        layout: z.ZodEnum<{
+            "pbp-left-right": "pbp-left-right";
+            "pbp-top-bottom": "pbp-top-bottom";
+            "pip-bottom-left": "pip-bottom-left";
+            "pip-bottom-right": "pip-bottom-right";
+            "pip-top-left": "pip-top-left";
+            "pip-top-right": "pip-top-right";
+        }>;
+        alpha: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type StartParams = z.infer<typeof startParamsSchema>;
 export declare const startResultSchema: z.ZodObject<{
@@ -359,6 +371,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;
@@ -373,6 +391,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<{
@@ -397,6 +420,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>;
@@ -462,6 +490,18 @@ export declare const changeConfigParamsSchema: z.ZodObject<{
         uvc_h264: "uvc_h264";
         uvc_h265: "uvc_h265";
     }>>;
+    composition: z.ZodOptional<z.ZodObject<{
+        secondary_input_id: z.ZodString;
+        layout: z.ZodEnum<{
+            "pbp-left-right": "pbp-left-right";
+            "pbp-top-bottom": "pbp-top-bottom";
+            "pip-bottom-left": "pip-bottom-left";
+            "pip-bottom-right": "pip-bottom-right";
+            "pip-top-left": "pip-top-left";
+            "pip-top-right": "pip-top-right";
+        }>;
+        alpha: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ChangeConfigParams = z.infer<typeof changeConfigParamsSchema>;
 export declare const changeConfigResultSchema: z.ZodObject<{
@@ -567,6 +607,18 @@ export declare const requestSchemas: {
                 uvc_h264: "uvc_h264";
                 uvc_h265: "uvc_h265";
             }>>;
+            composition: z.ZodOptional<z.ZodObject<{
+                secondary_input_id: z.ZodString;
+                layout: z.ZodEnum<{
+                    "pbp-left-right": "pbp-left-right";
+                    "pbp-top-bottom": "pbp-top-bottom";
+                    "pip-bottom-left": "pip-bottom-left";
+                    "pip-bottom-right": "pip-bottom-right";
+                    "pip-top-left": "pip-top-left";
+                    "pip-top-right": "pip-top-right";
+                }>;
+                alpha: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
             session_id: z.ZodString;

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 { audioBackendSchema, balancerAlgorithmSchema, bitrateControlSchema, captureDeviceKindSchema, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewEncodeModeSchema, previewTierSchema, streamStateSchema, videoCodecSchema, } from './types.js';
+import { audioBackendSchema, balancerAlgorithmSchema, bitrateControlSchema, captureDeviceKindSchema, captureDeviceSchema, cerastreamConfigSchema, compositionConfigSchema, 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 ----
@@ -172,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(),
@@ -180,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.
@@ -237,6 +239,7 @@ export const changeConfigParamsSchema = z
     // 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(),
+    composition: compositionConfigSchema.optional(),
 })
     .refine((delta) => Object.keys(delta).length > 0, {
     message: 'change-config delta must carry at least one field',

package/dist/types.d.ts

@@ -50,6 +50,30 @@ export declare const videoPassthroughSchema: z.ZodEnum<{
     off: "off";
 }>;
 export type VideoPassthrough = z.infer<typeof videoPassthroughSchema>;
+/** Exact preset nicks accepted by the first-party `rgacompositor` element. */
+export declare const compositionLayoutSchema: z.ZodEnum<{
+    "pbp-left-right": "pbp-left-right";
+    "pbp-top-bottom": "pbp-top-bottom";
+    "pip-bottom-left": "pip-bottom-left";
+    "pip-bottom-right": "pip-bottom-right";
+    "pip-top-left": "pip-top-left";
+    "pip-top-right": "pip-top-right";
+}>;
+export type CompositionLayout = z.infer<typeof compositionLayoutSchema>;
+/** One secondary capture leg composited with the primary session input. */
+export declare const compositionConfigSchema: z.ZodObject<{
+    secondary_input_id: z.ZodString;
+    layout: z.ZodEnum<{
+        "pbp-left-right": "pbp-left-right";
+        "pbp-top-bottom": "pbp-top-bottom";
+        "pip-bottom-left": "pip-bottom-left";
+        "pip-bottom-right": "pip-bottom-right";
+        "pip-top-left": "pip-top-left";
+        "pip-top-right": "pip-top-right";
+    }>;
+    alpha: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CompositionConfig = z.infer<typeof compositionConfigSchema>;
 export declare const bitrateControlSchema: z.ZodEnum<{
     encoder: "encoder";
     "source-fixed": "source-fixed";
@@ -199,6 +223,18 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
         uvc_h264: "uvc_h264";
         uvc_h265: "uvc_h265";
     }>>;
+    composition: z.ZodOptional<z.ZodObject<{
+        secondary_input_id: z.ZodString;
+        layout: z.ZodEnum<{
+            "pbp-left-right": "pbp-left-right";
+            "pbp-top-bottom": "pbp-top-bottom";
+            "pip-bottom-left": "pip-bottom-left";
+            "pip-bottom-right": "pip-bottom-right";
+            "pip-top-left": "pip-top-left";
+            "pip-top-right": "pip-top-right";
+        }>;
+        alpha: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CerastreamConfig = z.infer<typeof cerastreamConfigSchema>;
 export type PartialCerastreamConfig = z.input<typeof cerastreamConfigSchema>;

package/dist/types.js

@@ -34,6 +34,21 @@ export const videoCodecSchema = z.enum(['h264', 'h265']);
 // "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']);
+/** Exact preset nicks accepted by the first-party `rgacompositor` element. */
+export const compositionLayoutSchema = z.enum([
+    'pip-top-right',
+    'pip-top-left',
+    'pip-bottom-right',
+    'pip-bottom-left',
+    'pbp-left-right',
+    'pbp-top-bottom',
+]);
+/** One secondary capture leg composited with the primary session input. */
+export const compositionConfigSchema = z.object({
+    secondary_input_id: z.string().min(1),
+    layout: compositionLayoutSchema,
+    alpha: z.number().min(0).max(1).optional(),
+});
 // 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
@@ -138,6 +153,7 @@ export const cerastreamConfigSchema = z.object({
     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
+    composition: compositionConfigSchema.optional(),
 });
 // convenience defaults for building a config client-side
 export const DEFAULT_BITRATE_CONFIG = {

package/package.json

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