@ceralive/cerastream 2026.6.0-rc.1

package/dist/transport.js

@@ -0,0 +1,98 @@
+import { MAX_LINE_BYTES } from "./constants.js";
+/**
+ * A single Unix-socket connection that frames bytes into NDJSON lines. Construct,
+ * `open()` (rejects if the socket can't be reached), `send()` lines, `close()`
+ * when done. Not reusable across reconnects — the client makes a new one.
+ */
+export class LineSocket {
+    socketPath;
+    socket;
+    buffer = "";
+    bufferedBytes = 0;
+    handlers;
+    closed = false;
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+    }
+    /** Connect to the socket and start framing. Rejects on a connect failure. */
+    async open(handlers) {
+        this.handlers = handlers;
+        this.socket = await Bun.connect({
+            unix: this.socketPath,
+            socket: {
+                data: (_s, chunk) => this.onData(chunk),
+                close: () => this.fireClose(),
+                end: () => this.fireClose(),
+                error: (_s, err) => this.fireClose(err),
+            },
+        });
+    }
+    /** Write one NDJSON line (the trailing newline is added here). */
+    send(line) {
+        if (this.closed || !this.socket) {
+            throw new Error("LineSocket.send: socket is not open");
+        }
+        this.socket.write(`${line}\n`);
+        this.socket.flush();
+    }
+    /** Close the connection. Idempotent; does not fire {@link LineSocketHandlers.onClose}. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.handlers = undefined;
+        try {
+            this.socket?.end();
+        }
+        catch {
+            // already gone
+        }
+        this.socket = undefined;
+    }
+    onData(chunk) {
+        if (this.closed)
+            return;
+        this.buffer += chunk.toString("utf8");
+        this.bufferedBytes += chunk.byteLength;
+        let nl = this.buffer.indexOf("\n");
+        if (nl === -1) {
+            // No complete line yet — guard the unbounded-line case (fatal framing error).
+            if (this.bufferedBytes > MAX_LINE_BYTES) {
+                this.fail(new Error(`line exceeded the ${MAX_LINE_BYTES}-byte framing cap (fatal protocol error)`));
+            }
+            return;
+        }
+        while (nl !== -1) {
+            const line = this.buffer.slice(0, nl);
+            this.buffer = this.buffer.slice(nl + 1);
+            if (line.length > MAX_LINE_BYTES) {
+                this.fail(new Error(`line exceeded the ${MAX_LINE_BYTES}-byte framing cap (fatal protocol error)`));
+                return;
+            }
+            if (line.length > 0)
+                this.handlers?.onLine(line);
+            nl = this.buffer.indexOf("\n");
+        }
+        this.bufferedBytes = Buffer.byteLength(this.buffer, "utf8");
+    }
+    fail(err) {
+        this.fireClose(err);
+        try {
+            this.socket?.end();
+        }
+        catch {
+            // already gone
+        }
+        this.socket = undefined;
+        this.closed = true;
+    }
+    fireClose(err) {
+        if (this.closed)
+            return;
+        const handlers = this.handlers;
+        this.handlers = undefined;
+        this.closed = true;
+        this.socket = undefined;
+        handlers?.onClose(err);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+export declare const streamStateSchema: z.ZodEnum<{
+    idle: "idle";
+    starting: "starting";
+    streaming: "streaming";
+    stopping: "stopping";
+}>;
+export type StreamState = z.infer<typeof streamStateSchema>;
+export declare const inputModeSchema: z.ZodEnum<{
+    manual: "manual";
+    auto: "auto";
+}>;
+export type InputMode = z.infer<typeof inputModeSchema>;
+export declare const balancerAlgorithmSchema: z.ZodEnum<{
+    adaptive: "adaptive";
+    fixed: "fixed";
+    aimd: "aimd";
+}>;
+export type BalancerAlgorithm = z.infer<typeof balancerAlgorithmSchema>;
+export declare const mediaClassSchema: z.ZodEnum<{
+    video: "video";
+    audio: "audio";
+}>;
+export type MediaClass = z.infer<typeof mediaClassSchema>;
+export declare const previewTierSchema: z.ZodEnum<{
+    webcodecs: "webcodecs";
+    webrtc: "webrtc";
+}>;
+export type PreviewTier = z.infer<typeof previewTierSchema>;
+/** SRT transport config. Mirrors schema.md `start.srt` exactly. */
+export declare const srtConfigSchema: z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodNumber;
+    streamid: z.ZodOptional<z.ZodString>;
+    latency_ms: z.ZodNumber;
+    reduced_packet_size: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SrtConfig = z.infer<typeof srtConfigSchema>;
+/** Bitrate / balancer config. Mirrors schema.md `start.bitrate` exactly. */
+export declare const bitrateConfigSchema: z.ZodObject<{
+    min_bitrate: z.ZodNumber;
+    max_bitrate: z.ZodNumber;
+    balancer: z.ZodDefault<z.ZodEnum<{
+        adaptive: "adaptive";
+        fixed: "fixed";
+        aimd: "aimd";
+    }>>;
+}, z.core.$strip>;
+export type BitrateConfig = z.infer<typeof bitrateConfigSchema>;
+/**
+ * Unified cerastream engine config — the complete shape needed to `start` a
+ * stream and the canonical persisted profile. `start` params ARE this config
+ * (messages.ts re-exports it), so the wire contract and the stored config can
+ * never drift.
+ */
+export declare const cerastreamConfigSchema: z.ZodObject<{
+    pipeline: z.ZodString;
+    srt: z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodNumber;
+        streamid: z.ZodOptional<z.ZodString>;
+        latency_ms: z.ZodNumber;
+        reduced_packet_size: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    bitrate: z.ZodObject<{
+        min_bitrate: z.ZodNumber;
+        max_bitrate: z.ZodNumber;
+        balancer: z.ZodDefault<z.ZodEnum<{
+            adaptive: "adaptive";
+            fixed: "fixed";
+            aimd: "aimd";
+        }>>;
+    }, z.core.$strip>;
+    input_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CerastreamConfig = z.infer<typeof cerastreamConfigSchema>;
+export type PartialCerastreamConfig = z.input<typeof cerastreamConfigSchema>;
+export declare const DEFAULT_BITRATE_CONFIG: {
+    readonly min_bitrate: 300;
+    readonly max_bitrate: 6000;
+    readonly balancer: "adaptive";
+};
+export declare const DEFAULT_SRT_LATENCY_MS = 2000;
+export declare const captureCapSchema: z.ZodObject<{
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    framerate: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CaptureCap = z.infer<typeof captureCapSchema>;
+export declare const captureDeviceSchema: z.ZodObject<{
+    input_id: z.ZodString;
+    device_path: z.ZodString;
+    display_name: z.ZodString;
+    media_class: z.ZodEnum<{
+        video: "video";
+        audio: "audio";
+    }>;
+    caps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        framerate: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CaptureDevice = z.infer<typeof captureDeviceSchema>;
+export declare const srtStatsSchema: z.ZodObject<{
+    rtt_ms: z.ZodNumber;
+    send_buffer: z.ZodNumber;
+    pkt_loss: z.ZodNumber;
+}, z.core.$strip>;
+export type SrtStats = z.infer<typeof srtStatsSchema>;

package/dist/types.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { DEFAULT_BALANCER, DEFAULT_MAX_BITRATE, DEFAULT_MIN_BITRATE, DEFAULT_SRT_LATENCY, } from "./constants.js";
+// Shared domain enums + the unified engine config. Field names are domain-level
+// (snake_case, matching the ceracoder config convention) — never engine
+// internals (schema.md "Conventions").
+export const streamStateSchema = z.enum([
+    "idle",
+    "starting",
+    "streaming",
+    "stopping",
+]);
+export const inputModeSchema = z.enum(["manual", "auto"]);
+// re-used from ceracoder (schema.md §"v1 messages" shared fragments)
+export const balancerAlgorithmSchema = z.enum(["adaptive", "fixed", "aimd"]);
+export const mediaClassSchema = z.enum(["video", "audio"]);
+export const previewTierSchema = z.enum(["webcodecs", "webrtc"]);
+// ---- config sub-schemas (canonical; reused by `start` + the unified config) ----
+/** SRT transport config. Mirrors schema.md `start.srt` exactly. */
+export const srtConfigSchema = z.object({
+    host: z.string(),
+    port: z.number().int().min(1).max(65535),
+    streamid: z.string().optional(),
+    latency_ms: z.number().int().min(100).max(10_000),
+    reduced_packet_size: z.boolean().optional(),
+});
+/** Bitrate / balancer config. Mirrors schema.md `start.bitrate` exactly. */
+export const bitrateConfigSchema = z.object({
+    min_bitrate: z.number().int().min(1),
+    max_bitrate: z.number().int().min(1),
+    balancer: balancerAlgorithmSchema.default(DEFAULT_BALANCER),
+});
+/**
+ * Unified cerastream engine config — the complete shape needed to `start` a
+ * stream and the canonical persisted profile. `start` params ARE this config
+ * (messages.ts re-exports it), so the wire contract and the stored config can
+ * never drift.
+ */
+export const cerastreamConfigSchema = z.object({
+    pipeline: z.string(), // pipeline id / profile name (NOT a Rust graph)
+    srt: srtConfigSchema,
+    bitrate: bitrateConfigSchema,
+    input_id: z.string().optional(), // initial active input; defaults to primary
+});
+// convenience defaults for building a config client-side
+export const DEFAULT_BITRATE_CONFIG = {
+    min_bitrate: DEFAULT_MIN_BITRATE,
+    max_bitrate: DEFAULT_MAX_BITRATE,
+    balancer: DEFAULT_BALANCER,
+};
+export const DEFAULT_SRT_LATENCY_MS = DEFAULT_SRT_LATENCY;
+// ---- capture device (list-devices result + device event) ----
+export const captureCapSchema = z.object({
+    width: z.number().int().optional(),
+    height: z.number().int().optional(),
+    framerate: z.string().optional(), // e.g. "30/1"
+});
+export const captureDeviceSchema = z.object({
+    input_id: z.string(), // stable id used by switch-input
+    device_path: z.string(), // e.g. /dev/video0 (dedup key)
+    display_name: z.string(),
+    media_class: mediaClassSchema,
+    caps: z.array(captureCapSchema).optional(),
+});
+// ---- transport telemetry (srt-stats event payload) ----
+export const srtStatsSchema = z.object({
+    rtt_ms: z.number(),
+    send_buffer: z.number().int(),
+    pkt_loss: z.number(),
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ceralive/cerastream",
+  "version": "2026.6.0-rc.1",
+  "description": "Type-safe TypeScript bindings + IPC client for the cerastream Rust streaming engine (JSON-RPC 2.0 / NDJSON over UDS). See ADR-0002.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "bun x tsc -p tsconfig.json",
+    "typecheck": "bun x tsc -p tsconfig.json --noEmit",
+    "lint": "bun x tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "prepare": "bun run build"
+  },
+  "dependencies": {
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.5",
+    "typescript": "^5.9.3"
+  },
+  "license": "GPL-3.0",
+  "keywords": [
+    "cerastream",
+    "srt",
+    "srtla",
+    "gstreamer",
+    "ceralive",
+    "json-rpc",
+    "ipc",
+    "schema"
+  ]
+}