stream-doctor 0.0.2

package/dist/stream_doctor.d.ts

@@ -0,0 +1,69 @@
+import { type ChildProcess } from "node:child_process";
+export declare function bundledBinary(): string | null;
+export type Status = "streaming" | "receiving" | "waiting_for_playlist" | "ended" | "failed" | "stopped";
+export interface StreamerStatus {
+    input: string;
+    rtmp_url: string;
+    status: Status;
+    error: string | null;
+    frames_sent: number;
+}
+export interface AvDrift {
+    drift_ms: number | null;
+    frame_duration_ms: number | null;
+    latest_samples: number[];
+}
+export interface Metrics {
+    av_drift?: AvDrift;
+    error?: string;
+}
+export interface ViewerStatus {
+    id: string;
+    hls_url: string;
+    status: Status;
+    error: string | null;
+    metrics: Metrics;
+}
+export interface ServerStatus {
+    streamer: StreamerStatus | null;
+    viewers: ViewerStatus[];
+}
+export declare function session({ server, binary, }?: {
+    server?: string;
+    binary?: string;
+}): Promise<Session>;
+declare class Session {
+    server: string;
+    child: ChildProcess | null;
+    constructor(server: string, child: ChildProcess | null);
+    publish(rtmpUrl: string, { file }?: {
+        file?: string;
+    }): Streamer;
+    watch(hlsUrl: string): Promise<Viewer>;
+    status(): Promise<ServerStatus>;
+    close(): Promise<void>;
+}
+declare class Streamer {
+    server: string;
+    ready: Promise<StreamerStatus>;
+    constructor(server: string, ready: Promise<StreamerStatus>);
+    status(): Promise<StreamerStatus>;
+    waitUntilLive({ timeoutMs, intervalMs, }?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<StreamerStatus>;
+    stop(): Promise<StreamerStatus>;
+}
+declare class Viewer {
+    server: string;
+    id: string;
+    constructor(server: string, id: string);
+    status(): Promise<ViewerStatus>;
+    metrics(): Promise<Metrics>;
+    waitUntilDone({ intervalMs, onUpdate, }?: {
+        intervalMs?: number;
+        onUpdate?: (viewer: ViewerStatus) => void;
+    }): Promise<ViewerStatus>;
+    stop(): Promise<Metrics>;
+}
+export type { Session, Streamer, Viewer };

package/dist/stream_doctor.js

@@ -0,0 +1,165 @@
+// Client for the stream_doctor server. `session()` spawns the binary (the one
+// bundled for this platform, or `binary`) when no server is listening;
+// `session.close()` stops it.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+const DEFAULT_SERVER = "http://localhost:4040";
+const PLATFORM_PACKAGES = {
+    "darwin-arm64": "@stream-doctor/darwin-arm64",
+    "linux-arm64": "@stream-doctor/linux-arm64",
+    "linux-x64": "@stream-doctor/linux-x64",
+};
+// The daemon ships as one package per platform, all optional dependencies of
+// this one, so only the matching one is installed.
+export function bundledBinary() {
+    const pkg = PLATFORM_PACKAGES[`${process.platform}-${process.arch}`];
+    if (!pkg)
+        return null;
+    try {
+        return createRequire(import.meta.url).resolve(`${pkg}/bin/stream_doctor`);
+    }
+    catch {
+        return null;
+    }
+}
+async function api(method, path, body, server) {
+    let res;
+    try {
+        res = await fetch(server + path, {
+            method,
+            headers: body ? { "content-type": "application/json" } : undefined,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    catch (e) {
+        throw new Error(`${method} ${path}: cannot reach ${server} (is the server running?): ${e.message}`);
+    }
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`${method} ${path}: HTTP ${res.status}: ${text}`);
+    return JSON.parse(text);
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const TERMINAL_STATUSES = ["ended", "failed", "stopped"];
+export async function session({ server = DEFAULT_SERVER, binary, } = {}) {
+    try {
+        await api("GET", "/status", null, server);
+        return new Session(server, null);
+    }
+    catch (e) {
+        binary ??= bundledBinary() ?? undefined;
+        if (!binary) {
+            throw new Error(`${e.message}; no stream_doctor binary bundled for ${process.platform}-${process.arch}, pass one with \`binary\``);
+        }
+    }
+    return new Session(server, await spawnServer(binary, server));
+}
+async function spawnServer(binary, server) {
+    if (!fs.existsSync(binary)) {
+        throw new Error(`${binary} not found, build it with: MIX_ENV=prod mix release`);
+    }
+    console.log(`starting ${binary}`);
+    // own process group, so that killing the burrito launcher takes the BEAM with it
+    const child = spawn(binary, [], { stdio: ["ignore", "inherit", "inherit"], detached: true });
+    for (const deadline = Date.now() + 120_000; Date.now() < deadline;) {
+        if (child.exitCode !== null)
+            throw new Error(`server exited with ${child.exitCode}`);
+        await sleep(1000);
+        try {
+            await api("GET", "/status", null, server);
+            return child;
+        }
+        catch { }
+    }
+    throw new Error("server didn't come up in 2 minutes");
+}
+class Session {
+    server;
+    child;
+    constructor(server, child) {
+        this.server = server;
+        this.child = child;
+    }
+    publish(rtmpUrl, { file = "test.mp4" } = {}) {
+        const ready = api("POST", "/streamer", { input: file, rtmp_url: rtmpUrl }, this.server);
+        return new Streamer(this.server, ready);
+    }
+    async watch(hlsUrl) {
+        const { id } = await api("POST", "/viewers", { hls_url: hlsUrl }, this.server);
+        return new Viewer(this.server, id);
+    }
+    status() {
+        return api("GET", "/status", null, this.server);
+    }
+    close() {
+        const child = this.child;
+        if (!child || child.exitCode !== null || child.pid === undefined)
+            return Promise.resolve();
+        const pid = child.pid;
+        return new Promise((resolve) => {
+            setTimeout(() => process.kill(-pid, "SIGKILL"), 5000).unref();
+            child.once("exit", () => resolve());
+            process.kill(-pid, "SIGTERM");
+        });
+    }
+}
+class Streamer {
+    server;
+    ready;
+    constructor(server, ready) {
+        this.server = server;
+        this.ready = ready;
+        ready.catch(() => { });
+    }
+    status() {
+        return this.ready.then(() => api("GET", "/streamer", null, this.server));
+    }
+    async waitUntilLive({ timeoutMs = 60_000, intervalMs = 250, } = {}) {
+        await this.ready;
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const streamer = await api("GET", "/streamer", null, this.server);
+            if (streamer.frames_sent > 0)
+                return streamer;
+            if (TERMINAL_STATUSES.includes(streamer.status)) {
+                throw new Error(`streamer ${streamer.status} before going live${streamer.error ? `: ${streamer.error}` : ""}`);
+            }
+            if (Date.now() > deadline)
+                throw new Error(`streamer not live within ${timeoutMs} ms`);
+            await sleep(intervalMs);
+        }
+    }
+    async stop() {
+        await this.ready;
+        return api("DELETE", "/streamer", null, this.server);
+    }
+}
+class Viewer {
+    server;
+    id;
+    constructor(server, id) {
+        this.server = server;
+        this.id = id;
+    }
+    status() {
+        return api("GET", `/viewers/${this.id}`, null, this.server);
+    }
+    async metrics() {
+        const { metrics } = await this.status();
+        return metrics;
+    }
+    async waitUntilDone({ intervalMs = 1000, onUpdate, } = {}) {
+        for (;;) {
+            const viewer = await this.status();
+            onUpdate?.(viewer);
+            if (TERMINAL_STATUSES.includes(viewer.status))
+                return viewer;
+            await sleep(intervalMs);
+        }
+    }
+    async stop() {
+        const { metrics } = await api("DELETE", `/viewers/${this.id}`, null, this.server);
+        return metrics;
+    }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "stream-doctor",
+  "version": "0.0.2",
+  "description": "Measures the audio/video drift of a live stream, end to end",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/membraneframework-labs/stream_doctor.git"
+  },
+  "type": "module",
+  "exports": "./dist/stream_doctor.js",
+  "types": "./dist/stream_doctor.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "node --test src/*.test.ts",
+    "lint": "tsc --noEmit && eslint src examples && prettier --check src examples",
+    "format": "prettier --write src examples"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.20.2",
+    "eslint": "^9.0.0",
+    "globals": "^16.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.70.0"
+  },
+  "optionalDependencies": {
+    "@stream-doctor/darwin-arm64": "0.0.2",
+    "@stream-doctor/linux-arm64": "0.0.2",
+    "@stream-doctor/linux-x64": "0.0.2"
+  }
+}