@ceralive/cerastream 2026.9.3 → 2026.9.4

package/README.md

@@ -16,6 +16,8 @@ engine's JSON-RPC 2.0 / NDJSON control plane over a Unix domain socket.
 - 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;
   composition-only changes use live layout/alpha writes and secondary rebind

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.14.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}. */

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.14.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}. */

package/dist/errors.d.ts

@@ -97,22 +97,26 @@ 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,8 @@ export const captureCauseSchema = z.enum([
     'no_signal',
     'device_busy',
     'no_silicon_converter',
+    'decoder-unavailable',
+    'software-pixel-path-rejected',
     'composition-unsupported',
     'secondary-unavailable',
 ]);

package/dist/events.d.ts

@@ -241,11 +241,13 @@ export declare const runtimeErrorEventSchema: z.ZodObject<{
     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. */
@@ -467,11 +469,13 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     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">;
@@ -667,11 +671,13 @@ export declare const cerastreamEventSchema: z.ZodObject<{
         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">;
@@ -876,11 +882,13 @@ export declare const eventSchemas: {
         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";
     }>>;
@@ -172,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<{
@@ -371,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";
@@ -434,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;
@@ -469,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<{
@@ -476,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";
     }>>;
@@ -573,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";
             }>>;

package/dist/messages.js

@@ -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

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";
 }>;
@@ -189,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";
     }>>;

package/dist/types.js

@@ -28,7 +28,7 @@ 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);

package/package.json

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