@ceralive/cerastream
v2026.11.1
Published
Type-safe TypeScript schema + IPC client for the cerastream streaming engine (JSON-RPC 2.0 / NDJSON over a Unix domain socket).
Maintainers
Readme
@ceralive/cerastream
Prepared 2026.11.1 / schema 0.23.0 carries audio input configs, track routing,
per-input levels, client.setAudioMix(), and a free composition.rect with the
additional custom layout. The shared limits and the audio-mix and
composition-geometry feature tokens are exported. Gate use on the running
engine's capabilities, not the exported catalog. This preparation does not
publish the package; verify the separately authorized registry release before
consumer upgrades.
Prepared 2026.9.11 / schema 0.21.0 adds an optional capture-status report
and source-mode fields on switch targets plus a closed retime/adapt input
policy. Capture status accepts future token strings without dropping a status
event; malformed capture blocks become absent without hiding encode data.
INTERNAL_TRANSITION_WORST_CASE_BOUND_MS is 65_000 in both IPC and bindings.
This is not a published release or engine recovery implementation. Publish before
consumer use; capability tokens are not advertised by the engine yet.
Prepared 2026.9.10 / schema 0.20.0 carries optional
active_encode.skip_to_live alongside encoder health counters. It counts
age-based RAM backlog discards in the current session, not outages or lost frames.
Absence is unknown; zero is not loss-free delivery. Reconnect preserves the count,
and session replacement resets it. Publish before consumer use.
Prepared 2026.9.9 / schema 0.19.0 adds raw_video and unknown capture
classifications. They do not promise a selectable capture mode. camlink remains
unchanged for identified Elgato hardware. Publish before consumer merge: older
closed-enum validators can reject the entire device reply. This is not a publish receipt.
Type-safe control-IPC schema + client for the cerastream streaming engine. A zero-native-dependency package — the published contract for driving the engine's JSON-RPC 2.0 / NDJSON control plane over a Unix domain socket.
- JSON-RPC 2.0 envelope +
hellohandshake schemas - The eight v1 control methods (Zod params + result schemas + inferred types)
- 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
(including HDMI
unsupported-format,interlaced-unsupported,source-changed) - Typed platform capture-converter reporting (
librga,v4l2-rga2, ornone) - Typed RK3588 composition config (secondary input, six PiP/PbP layouts, alpha),
gated by the READY-trialled
compositioncapability token - A unified engine config schema (=
startparams) - A
CerastreamClientinterface +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.setEdidProfile()— switch the HDMI-RX EDID between the namedfull/robust-4k60profiles as one transaction: written, byte-verified, persisted, then the device projection re-read only after the link settles - 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 2026.9.8 is prepared with changeConfig({composition: null})
to disable composition through a full graph transaction. Omission preserves the
live mode. Import ChangeConfigParams from this package. Verify publication of
bindings-v2026.9.8 before consumer merge; a prepared version is not a registry
receipt. The device engine separately needs the correction from PR #170.
The Zod schemas, types, and constants are the frozen wire contract; connect()
drives that contract over an NDJSON/UDS transport with no native dependencies.
Install
npm i @ceralive/cerastream
# or
bun add @ceralive/cerastreamUsage
The schemas validate any control message on either side of the wire:
import { startParamsSchema, eventParamsSchema } from '@ceralive/cerastream';
const params = startParamsSchema.parse({
pipeline: 'h264_camlink_1080p',
srt: { host: 'relay.example.com', port: 8890, latency_ms: 2000 },
bitrate: { min_bitrate: 500, max_bitrate: 6000 }, // balancer defaults to "adaptive"
});
const event = eventParamsSchema.parse(incomingNotification.params); // typed by `type`Drive the engine through the control plane:
import { connect } from '@ceralive/cerastream';
const client = await connect({ autoReconnect: true }); // hello handshake runs here
console.log(client.hello.engine_version);
const capabilities = await client.getCapabilities();
console.log(capabilities.preview?.bound);
const sub = await client.subscribeEvents({ topics: ['status', 'bitrate'] }, (ev) => {
if (ev.type === 'bitrate') console.log('bitrate', ev.current_bitrate);
});
await client.start({
pipeline: 'h264_camlink_1080p',
srt: { host: 'relay.example.com', port: 8890, latency_ms: 2000 },
bitrate: { min_bitrate: 500, max_bitrate: 6000 },
});
await client.setBitrate({ max_bitrate: 4500 });
await client.switchInput({ input_id: 'video0' });
await client.stop();
sub.close();
await client.close(); // closes the connection; never spawns the engineconnect() honours socketPath, requestTimeoutMs, and autoReconnect
(capped backoff + re-handshake + re-subscribe). The engine runs as a
systemd-owned service — the client connects to it and never spawns it.
Versioning
Version 2026.9.6 / schema 0.18.0 adds
client.listSwitchTargets() and optional active_encode.switch_targets.
Targets are {input_id, kind: "capture"|"synthetic"|"network"}; the query returns
{session_id?, active_input?, switch_targets: [...]}. They describe built live
legs, not idle capabilities; passthrough/composition explicitly return [].
Import SessionSwitchTarget and ListSwitchTargetsResult from this package,
never shadow the wire types. Re-query before switching and handle refusal; the
snapshot does not reserve a leg. Release/publish must happen before consumption.
Two independent version axes. The wire-schema version (PROTOCOL_VERSION +
SCHEMA_VERSION) is pinned cross-language with the engine and is additive-only
within cerastream-ipc/1. The npm package version is CalVer
(YYYY.MINOR.PATCH) with SemVer intent applied to the exported TypeScript
surface; release candidates use -rc.N (npm next dist-tag).
License
GPL-3.0
