@ceralive/cerastream 2026.9.2 → 2026.9.4

package/README.md

@@ -10,12 +10,17 @@ engine's JSON-RPC 2.0 / NDJSON control plane over a Unix domain socket.
 - 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
+- Per-codec encoder capability entries with format, resolution/framerate, and
+  explicit 4K60 qualification-gate truth
 - 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/client.d.ts

@@ -1,6 +1,6 @@
 import { type HelloResult } from './envelope.js';
 import { type EventParams } from './events.js';
-import { type ChangeConfigParams, type ChangeConfigResult, type GetCapabilitiesResult, type ListDevicesParams, type ListDevicesResult, type PreviewSessionParams, type PreviewSessionResult, type ReloadConfigParams, type ReloadConfigResult, type SetBitrateParams, type SetBitrateResult, type StartParams, type StartResult, type StopParams, type StopResult, type SubscribeEventsParams, type SubscribeEventsResult, type SwitchInputParams, type SwitchInputResult } from './messages.js';
+import { type ChangeConfigParams, type ChangeConfigResult, type GetCapabilitiesResult, type ListDevicesParams, type ListDevicesResult, type PreviewSessionParams, type PreviewSessionResult, type ReloadConfigParams, type ReloadConfigResult, type RequestKeyframeResult, type SetBitrateParams, type SetBitrateResult, type StartParams, type StartResult, type StopParams, type StopResult, type SubscribeEventsParams, type SubscribeEventsResult, type SwitchInputParams, type SwitchInputResult } from './messages.js';
 /** Options for {@link connect}. All optional — `connect({})` is valid. */
 export interface ConnectOptions {
     /** Control socket path override. Defaults to the resolved /run/cerastream/control.sock. */
@@ -64,6 +64,7 @@ export interface CerastreamClient {
      * @throws {CerastreamRpcError} when the value is out of the configured range.
      */
     setBitrate(params: SetBitrateParams): Promise<SetBitrateResult>;
+    requestKeyframe(): Promise<RequestKeyframeResult>;
     /**
      * Switch the active capture source (manual) or hand selection to failover (auto).
      * @param params The target input id and switch mode.

package/dist/client.js

@@ -3,7 +3,7 @@ import { CONTROL_SOCKET_PATH, PROTOCOL_VERSION } from './constants.js';
 import { helloResultSchema, rpcErrorSchema, rpcResponseSchema, } from './envelope.js';
 import { CerastreamConnectionError, CerastreamRpcError, CerastreamTimeoutError, } from './errors.js';
 import { eventParamsSchema } from './events.js';
-import { changeConfigParamsSchema, changeConfigResultSchema, getCapabilitiesResultSchema, requestSchemas, } from './messages.js';
+import { changeConfigParamsSchema, changeConfigResultSchema, getCapabilitiesResultSchema, requestKeyframeResultSchema, requestSchemas, } from './messages.js';
 import { controlSocketPath } from './paths.js';
 import { LineSocket } from './transport.js';
 const DEFAULTS = {
@@ -70,6 +70,9 @@ class ClientImpl {
     setBitrate(params) {
         return this.call('set-bitrate', params);
     }
+    async requestKeyframe() {
+        return requestKeyframeResultSchema.parse(await this.rawRequest('request-keyframe', {}));
+    }
     switchInput(params) {
         return this.call('switch-input', params);
     }

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.16.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.16.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,19 +96,27 @@ export declare const processErrorCodeSchema: z.ZodEnum<{
 }>;
 export type ProcessErrorCode = z.infer<typeof processErrorCodeSchema>;
 export declare const captureCauseSchema: z.ZodEnum<{
+    "composition-unsupported": "composition-unsupported";
+    "decoder-unavailable": "decoder-unavailable";
     device_busy: "device_busy";
     negotiation_failed: "negotiation_failed";
     no_signal: "no_signal";
     no_silicon_converter: "no_silicon_converter";
+    "secondary-unavailable": "secondary-unavailable";
+    "software-pixel-path-rejected": "software-pixel-path-rejected";
 }>;
 export type CaptureCause = z.infer<typeof captureCauseSchema>;
 export declare const captureCauseEntrySchema: z.ZodObject<{
     device: z.ZodString;
     cause: z.ZodEnum<{
+        "composition-unsupported": "composition-unsupported";
+        "decoder-unavailable": "decoder-unavailable";
         device_busy: "device_busy";
         negotiation_failed: "negotiation_failed";
         no_signal: "no_signal";
         no_silicon_converter: "no_silicon_converter";
+        "secondary-unavailable": "secondary-unavailable";
+        "software-pixel-path-rejected": "software-pixel-path-rejected";
     }>;
 }, z.core.$strip>;
 export type CaptureCauseEntry = z.infer<typeof captureCauseEntrySchema>;

package/dist/errors.js

@@ -143,6 +143,10 @@ export const captureCauseSchema = z.enum([
     'no_signal',
     'device_busy',
     'no_silicon_converter',
+    'decoder-unavailable',
+    'software-pixel-path-rejected',
+    'composition-unsupported',
+    'secondary-unavailable',
 ]);
 export const captureCauseEntrySchema = z.object({
     device: z.string(),

package/dist/events.d.ts

@@ -240,10 +240,14 @@ 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";
+        "decoder-unavailable": "decoder-unavailable";
         device_busy: "device_busy";
         negotiation_failed: "negotiation_failed";
         no_signal: "no_signal";
         no_silicon_converter: "no_silicon_converter";
+        "secondary-unavailable": "secondary-unavailable";
+        "software-pixel-path-rejected": "software-pixel-path-rejected";
     }>>;
 }, z.core.$strip>;
 /** Payload of a {@link runtimeErrorEventSchema} event. */
@@ -464,10 +468,14 @@ 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";
+        "decoder-unavailable": "decoder-unavailable";
         device_busy: "device_busy";
         negotiation_failed: "negotiation_failed";
         no_signal: "no_signal";
         no_silicon_converter: "no_silicon_converter";
+        "secondary-unavailable": "secondary-unavailable";
+        "software-pixel-path-rejected": "software-pixel-path-rejected";
     }>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"preview">;
@@ -662,10 +670,14 @@ 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";
+            "decoder-unavailable": "decoder-unavailable";
             device_busy: "device_busy";
             negotiation_failed: "negotiation_failed";
             no_signal: "no_signal";
             no_silicon_converter: "no_silicon_converter";
+            "secondary-unavailable": "secondary-unavailable";
+            "software-pixel-path-rejected": "software-pixel-path-rejected";
         }>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"preview">;
@@ -869,10 +881,14 @@ export declare const eventSchemas: {
         reason: z.ZodOptional<z.ZodString>;
         selected: z.ZodOptional<z.ZodBoolean>;
         capture_cause: z.ZodOptional<z.ZodEnum<{
+            "composition-unsupported": "composition-unsupported";
+            "decoder-unavailable": "decoder-unavailable";
             device_busy: "device_busy";
             negotiation_failed: "negotiation_failed";
             no_signal: "no_signal";
             no_silicon_converter: "no_silicon_converter";
+            "secondary-unavailable": "secondary-unavailable";
+            "software-pixel-path-rejected": "software-pixel-path-rejected";
         }>>;
     }, z.core.$strip>;
     readonly preview: z.ZodObject<{

package/dist/messages.d.ts

@@ -22,6 +22,7 @@ export declare const startParamsSchema: z.ZodObject<{
     }, z.core.$strip>;
     input_id: z.ZodOptional<z.ZodString>;
     codec: z.ZodOptional<z.ZodEnum<{
+        av1: "av1";
         h264: "h264";
         h265: "h265";
     }>>;
@@ -56,6 +57,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<{
@@ -160,6 +173,12 @@ export declare const setBitrateResultSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SetBitrateResult = z.infer<typeof setBitrateResultSchema>;
+export declare const requestKeyframeParamsSchema: z.ZodObject<{}, z.core.$strip>;
+export type RequestKeyframeParams = z.infer<typeof requestKeyframeParamsSchema>;
+export declare const requestKeyframeResultSchema: z.ZodObject<{
+    applied: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type RequestKeyframeResult = z.infer<typeof requestKeyframeResultSchema>;
 export declare const switchInputParamsSchema: z.ZodObject<{
     input_id: z.ZodString;
     mode: z.ZodDefault<z.ZodEnum<{
@@ -359,6 +378,27 @@ export declare const encoderCapsSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type EncoderCaps = z.infer<typeof encoderCapsSchema>;
+export declare const encoderGateStatusSchema: z.ZodEnum<{
+    kept: "kept";
+    measured: "measured";
+    untested: "untested";
+}>;
+export type EncoderGateStatus = z.infer<typeof encoderGateStatusSchema>;
+export declare const encoderCapabilitySchema: z.ZodObject<{
+    codec: z.ZodString;
+    max_resolution: z.ZodString;
+    max_framerate: z.ZodNumber;
+    formats: z.ZodArray<z.ZodString>;
+    gates: z.ZodObject<{
+        '4k60': z.ZodEnum<{
+            kept: "kept";
+            measured: "measured";
+            untested: "untested";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type EncoderCapability = z.infer<typeof encoderCapabilitySchema>;
 export declare const platformConverterSchema: z.ZodEnum<{
     librga: "librga";
     none: "none";
@@ -422,6 +462,20 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
             unit: z.ZodString;
         }, z.core.$strip>;
     }, z.core.$strip>;
+    encoders: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        codec: z.ZodString;
+        max_resolution: z.ZodString;
+        max_framerate: z.ZodNumber;
+        formats: z.ZodArray<z.ZodString>;
+        gates: z.ZodObject<{
+            '4k60': z.ZodEnum<{
+                kept: "kept";
+                measured: "measured";
+                untested: "untested";
+            }>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
     sources: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         supports_audio: z.ZodBoolean;
@@ -457,6 +511,7 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
     }, z.core.$strip>>;
     network_embedded_audio: z.ZodOptional<z.ZodBoolean>;
     features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pixel_paths: z.ZodOptional<z.ZodLiteral<"silicon-only">>;
 }, z.core.$strip>;
 export type GetCapabilitiesResult = z.infer<typeof getCapabilitiesResultSchema>;
 export declare const changeConfigParamsSchema: z.ZodObject<{
@@ -464,6 +519,7 @@ export declare const changeConfigParamsSchema: z.ZodObject<{
     resolution: z.ZodOptional<z.ZodString>;
     framerate: z.ZodOptional<z.ZodNumber>;
     codec: z.ZodOptional<z.ZodEnum<{
+        av1: "av1";
         h264: "h264";
         h265: "h265";
     }>>;
@@ -478,6 +534,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<{
@@ -549,6 +617,7 @@ export declare const requestSchemas: {
             }, z.core.$strip>;
             input_id: z.ZodOptional<z.ZodString>;
             codec: z.ZodOptional<z.ZodEnum<{
+                av1: "av1";
                 h264: "h264";
                 h265: "h265";
             }>>;
@@ -583,6 +652,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 ----
@@ -72,6 +72,8 @@ export const setBitrateResultSchema = z.object({
     bitrate_control: bitrateControlSchema.optional(),
     reason: z.string().optional(),
 });
+export const requestKeyframeParamsSchema = z.object({});
+export const requestKeyframeResultSchema = z.object({ applied: z.literal(true) });
 // ---- 5. switch-input ----
 export const switchInputParamsSchema = z.object({
     input_id: z.string(), // device/input identifier from list-devices
@@ -172,6 +174,17 @@ export const encoderCapsSchema = z.object({
     codecs: z.array(z.string()),
     bitrate_range: bitrateRangeCapsSchema,
 });
+export const encoderGateStatusSchema = z.enum(['measured', 'kept', 'untested']);
+export const encoderCapabilitySchema = z.object({
+    codec: z.string(),
+    max_resolution: z.string(),
+    max_framerate: z.number().int().positive(),
+    formats: z.array(z.string()),
+    gates: z.object({
+        '4k60': encoderGateStatusSchema,
+        reason: z.string().optional(),
+    }),
+});
 export const platformConverterSchema = z.enum(['librga', 'v4l2-rga2', 'none']);
 export const platformCapsSchema = z.object({
     supports_h265: z.boolean(),
@@ -202,6 +215,7 @@ export const previewAvailabilitySchema = z.object({
 export const getCapabilitiesResultSchema = z.object({
     platform: platformCapsSchema,
     encoder: encoderCapsSchema,
+    encoders: z.array(encoderCapabilitySchema).optional(),
     sources: z.array(videoSourceCapSchema),
     audio_live_switch: z.boolean().optional(),
     audio_backends: z
@@ -217,6 +231,7 @@ export const getCapabilitiesResultSchema = z.object({
     preview: previewAvailabilitySchema.optional(), // preview-server availability (unbound vs down)
     network_embedded_audio: z.boolean().optional(), // engine routes network-ingest embedded audio to the mux
     features: z.array(z.string()).optional(), // named engine features (e.g. "video-passthrough") for fail-closed negotiation
+    pixel_paths: z.literal('silicon-only').optional(),
 });
 // ---- 10. change-config (0.10.0, additive) ----
 // Deliberately absent from V1_METHODS / requestSchemas, like get-capabilities and
@@ -239,6 +254,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

@@ -40,6 +40,7 @@ export declare const previewEncodeFallbackSchema: z.ZodDiscriminatedUnion<[z.Zod
 }, z.core.$strip>], "code">;
 export type PreviewEncodeFallback = z.infer<typeof previewEncodeFallbackSchema>;
 export declare const videoCodecSchema: z.ZodEnum<{
+    av1: "av1";
     h264: "h264";
     h265: "h265";
 }>;
@@ -50,6 +51,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";
@@ -165,6 +190,7 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
     }, z.core.$strip>;
     input_id: z.ZodOptional<z.ZodString>;
     codec: z.ZodOptional<z.ZodEnum<{
+        av1: "av1";
         h264: "h264";
         h265: "h265";
     }>>;
@@ -199,6 +225,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

@@ -28,12 +28,27 @@ export const previewEncodeFallbackSchema = z.discriminatedUnion('code', [
 // 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.
-export const videoCodecSchema = z.enum(['h264', 'h265']);
+export const videoCodecSchema = z.enum(['h264', 'h265', 'av1']);
 // Same-codec passthrough policy (0.5.0, additive). Absent ⇒ "auto". "auto" =
 // passthrough only when adaptive bitrate is inactive and eligibility holds;
 // "force" = passthrough whenever eligible (typed start failure otherwise);
 // "off" = always transcode. See schema.md and the engine's layer-C matrix.
 export const videoPassthroughSchema = z.enum(['auto', 'force', 'off']);
+/** 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.2",
+	"version": "2026.9.4",
 	"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",