nixamp 0.1.0 → 0.3.0

package/dist/admin.js

@@ -0,0 +1,209 @@
+/**
+ * `nixamp admin` — what the daemon is doing, and who is listening to it.
+ *
+ * It talks to a running server over the same HTTP API a browser uses, so it
+ * works against the local daemon, against `nixamp serve` in another terminal,
+ * or against a nixamp on a different machine entirely.
+ */
+import { createApp, themes } from "@profullstack/hqtui";
+import { daemonUrl, readState } from "./daemon.js";
+import { KEY_HEADER } from "./share.js";
+/** Where to point, from the flags or from the daemon that is running. */
+export function resolveTarget(argv) {
+    const at = argv.findIndex((a) => a === "--url" || a === "-u");
+    const keyAt = argv.findIndex((a) => a === "--key");
+    const url = at === -1 ? null : argv[at + 1];
+    const key = keyAt === -1 ? null : (argv[keyAt + 1] ?? null);
+    if (url)
+        return { url: url.replace(/\/+$/, ""), key };
+    const state = readState();
+    if (state === null) {
+        throw new Error("nixamp: no daemon is running. Start one with `nixamp daemon start`, or pass --url.");
+    }
+    return { url: daemonUrl(state), key: key ?? state.key };
+}
+/** Seconds as something a person reads at a glance. */
+export function since(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ${seconds % 60}s`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ${minutes % 60}m`;
+    return `${Math.floor(hours / 24)}d ${hours % 24}h`;
+}
+export function bytes(value) {
+    const units = ["B", "KiB", "MiB", "GiB"];
+    let n = value;
+    for (const unit of units) {
+        if (n < 1024 || unit === "GiB")
+            return `${n < 10 && unit !== "B" ? n.toFixed(1) : Math.round(n)} ${unit}`;
+        n /= 1024;
+    }
+    return `${value} B`;
+}
+/** The colour a network deserves: the internet is the one worth noticing. */
+function networkColor(theme, network) {
+    return network === "public"
+        ? theme.warning
+        : network === "cgnat"
+            ? theme.secondary
+            : network === "local"
+                ? theme.muted
+                : theme.success;
+}
+export async function admin(argv) {
+    const target = resolveTarget(argv);
+    const headers = target.key ? { [KEY_HEADER]: target.key } : {};
+    const ask = async (path) => {
+        try {
+            const response = await fetch(`${target.url}${path}`, { headers });
+            return response.ok ? (await response.json()) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    let report = null;
+    let snapshot = null;
+    let error = "";
+    let restreaming = "";
+    let typing = false;
+    const app = await createApp({ theme: themes.matrix, title: "nixamp admin", quitKeys: ["ctrl+c"] });
+    const refresh = async () => {
+        const [next, state] = await Promise.all([ask("/api/connections"), ask("/api/state")]);
+        error = next === null ? `cannot reach ${target.url}` : "";
+        if (next)
+            report = next;
+        if (state)
+            snapshot = state;
+        app.invalidate();
+    };
+    const timer = setInterval(() => void refresh(), 1000);
+    await refresh();
+    app.on("key", (event) => {
+        const key = event.key;
+        if (typing) {
+            if (key === "escape") {
+                typing = false;
+                restreaming = "";
+            }
+            else if (key === "enter") {
+                const url = restreaming.trim();
+                typing = false;
+                restreaming = "";
+                if (url)
+                    void restream(target, headers, url).then(() => refresh());
+            }
+            else if (key === "backspace")
+                restreaming = restreaming.slice(0, -1);
+            // A printable key is a character; everything else is a name like "f1".
+            else if (key.length === 1)
+                restreaming += key;
+            app.invalidate();
+            return;
+        }
+        if (key === "q") {
+            app.quit();
+            return;
+        }
+        if (key === "r") {
+            typing = true;
+            app.invalidate();
+        }
+    });
+    app.on("exit", () => clearInterval(timer));
+    app.render(({ ui, theme }) => draw(ui, theme, {
+        url: target.url, report, snapshot, error, typing, restreaming,
+    }));
+    await app.start();
+    clearInterval(timer);
+}
+/** Ask the server to play something else, which is what re-streaming is. */
+async function restream(target, headers, url) {
+    try {
+        await fetch(`${target.url}/api/source`, {
+            method: "POST",
+            headers: { ...headers, "content-type": "application/json" },
+            body: JSON.stringify({ source: url }),
+        });
+    }
+    catch {
+        // The next refresh reports the server being unreachable; this is not the
+        // place to make that noise.
+    }
+}
+export function draw(ui, theme, view) {
+    const { report, snapshot } = view;
+    const now = report?.now ?? Date.now();
+    ui.row({ size: 7, gap: 1 }, (row) => {
+        row.panel({ title: "Server" }, (p) => {
+            p.text(view.url, { fg: theme.primary });
+            p.label(snapshot?.root ?? "—");
+            p.keyValues([
+                { label: "Uptime", value: report ? since(now - report.startedAt) : "—", color: theme.accent },
+                { label: "Tracks", value: String(snapshot?.tracks.length ?? 0), color: theme.foreground },
+                { label: "Listeners", value: String(report?.active ?? 0), color: theme.success },
+            ]);
+        });
+        row.panel({ title: "Now playing" }, (p) => {
+            const track = snapshot ? snapshot.tracks[snapshot.index] : undefined;
+            p.text(track?.title ?? "nothing", { fg: theme.accent });
+            p.label(track?.artist || "—");
+            p.keyValues([
+                { label: "State", value: snapshot?.playing ? "playing" : "stopped", color: snapshot?.playing ? theme.success : theme.muted },
+                { label: "Position", value: snapshot ? since(snapshot.position * 1000) : "—", color: theme.foreground },
+            ]);
+        });
+    });
+    ui.panel({ title: `Connections (${report?.active ?? 0} live)` }, (p) => {
+        if (view.error) {
+            p.text(view.error, { fg: theme.danger });
+            return;
+        }
+        const rows = report?.connections ?? [];
+        if (rows.length === 0) {
+            p.label("Nobody is listening yet.");
+            return;
+        }
+        // A finished connection is drawn in muted colours rather than dropped: the
+        // most useful thing an admin view can say is "it stopped ten seconds ago".
+        const dim = (row, live) => (row.endedAt === null ? live : theme.muted);
+        p.table({
+            rows,
+            header: true,
+            headerColor: theme.muted,
+            zebra: false,
+            columns: [
+                { key: "address", title: "Where", min: 12, color: (row) => dim(row, theme.foreground) },
+                { key: "network", title: "Network", width: 9, color: (row) => dim(row, networkColor(theme, row.network)) },
+                { key: "kind", title: "Kind", width: 7, color: theme.muted },
+                { key: "agent", title: "Client", width: 12, color: theme.muted },
+                { key: "track", title: "Track", min: 16, color: (row) => dim(row, theme.primary),
+                    render: (row) => row.track || "—" },
+                { key: "for", title: "For", width: 10, align: "right", color: theme.muted,
+                    render: (row) => (row.endedAt === null
+                        ? since(now - row.startedAt)
+                        : `${since(row.endedAt - row.startedAt)} ago`) },
+                { key: "bytes", title: "Sent", width: 9, align: "right",
+                    color: (row) => dim(row, theme.success), render: (row) => bytes(row.bytes) },
+            ],
+        });
+    });
+    if (view.typing) {
+        ui.panel({ title: "Re-stream a URL or a path", size: 4 }, (p) => {
+            p.text(`${view.restreaming}_`, { fg: theme.accent });
+            p.label("Enter plays it here. Escape forgets it.");
+        });
+    }
+    ui.statusBar({
+        items: [
+            { key: "r", label: "Re-stream" },
+            { key: "q", label: "Quit" },
+        ],
+        right: [{ key: "", label: report ? `${report.connections.length} seen` : "connecting" }],
+    });
+}

package/dist/broadcast.d.ts

@@ -0,0 +1,96 @@
+export interface Destination {
+    id: string;
+    /** What to call it: "YouTube", "X", the name of a server. */
+    name: string;
+    /** rtmp://a.rtmp.youtube.com/live2 — without the key. */
+    url: string;
+    /** The stream key. It never leaves the machine: see redact(). */
+    key: string;
+    enabled: boolean;
+}
+export interface EncoderSettings {
+    /** kbps. */
+    videoBitrate: number;
+    audioBitrate: number;
+    framerate: number;
+    /** Seconds between keyframes. One, unless you enjoy YouTube stalling. */
+    keyframeInterval: number;
+    resolution: "720p" | "1080p";
+}
+export declare const DEFAULT_ENCODER: EncoderSettings;
+/** The RTMP ingest URLs of the places people actually go live. */
+export declare const PRESETS: Record<string, string>;
+export declare function resolutionOf(resolution: EncoderSettings["resolution"]): {
+    width: number;
+    height: number;
+};
+/** The full ingest URL. Built here so a key is never assembled by a client. */
+export declare function ingestUrl(destination: Destination): string;
+/** Somewhere to actually send RTMP. */
+export declare function isRtmp(url: string): boolean;
+/**
+ * A destination as it may be shown to anyone. A stream key is a password: it
+ * lets a stranger broadcast as you until you rotate it.
+ */
+export declare function redact(destination: Destination): Omit<Destination, "key"> & {
+    key: string;
+};
+/**
+ * A tee output. `onfail=ignore` is the important part: without it one dead
+ * destination takes the whole broadcast down with it, and the one that dies is
+ * usually the one whose key expired without telling you.
+ */
+export declare function teeOutput(url: string, options?: string[]): string;
+export interface BroadcastPlan {
+    source: string;
+    destinations: Destination[];
+    settings: EncoderSettings;
+    /** Also produce web-playable audio on stdout, from the same decode. */
+    webAudio: boolean;
+    /** The source has no video track, so one has to be invented for RTMP. */
+    needsVideo: boolean;
+}
+/**
+ * The whole ffmpeg command.
+ *
+ * RTMP platforms want a video track even when what you are sending is music,
+ * so a silent source gets a flat colour at the chosen size. It is what a radio
+ * stream looks like on YouTube either way.
+ */
+export declare function buildBroadcastArgs(plan: BroadcastPlan): string[];
+export type BroadcastState = "idle" | "live" | "failed";
+export interface BroadcastStatus {
+    state: BroadcastState;
+    since: number | null;
+    /** Names only, and never a key. */
+    destinations: string[];
+    error: string;
+}
+/**
+ * One broadcast at a time, restarted when it dies. A live stream that stops
+ * because a platform hiccupped, and stays stopped, is worse than no feature.
+ */
+export declare class Broadcaster {
+    private readonly ffmpeg;
+    /** Injected so a test never waits five real seconds. */
+    private readonly delay;
+    private child;
+    private plan;
+    private timer;
+    private attempts;
+    private state;
+    private since;
+    private error;
+    constructor(ffmpeg?: string[], 
+    /** Injected so a test never waits five real seconds. */
+    delay?: (ms: number, run: () => void) => NodeJS.Timeout);
+    status(): BroadcastStatus;
+    start(plan: BroadcastPlan): {
+        ok: boolean;
+        error: string;
+    };
+    stop(): void;
+    private spawn;
+    /** Back off, but never give up entirely while a plan is set. */
+    private retry;
+}

package/dist/broadcast.js

@@ -0,0 +1,193 @@
+/**
+ * Broadcasting out to RTMP, to as many places at once as you like.
+ *
+ * One ffmpeg, one encode, many outputs, through the `tee` muxer. Running an
+ * ffmpeg per destination is the obvious shape and it encodes the same frames
+ * four times; tee encodes once and writes the result to every URL.
+ *
+ * The encoder settings are PairUX's, which learned them the hard way against
+ * the real platforms: a one-second keyframe interval because YouTube stalls on
+ * ffmpeg's default, a forced constant frame rate because a variable-rate source
+ * makes YouTube report "not receiving enough video", and yuv420p because that
+ * is what RTMP platforms accept.
+ */
+import { spawn } from "node:child_process";
+export const DEFAULT_ENCODER = {
+    videoBitrate: 4500,
+    audioBitrate: 128,
+    framerate: 30,
+    keyframeInterval: 1,
+    resolution: "1080p",
+};
+/** The RTMP ingest URLs of the places people actually go live. */
+export const PRESETS = {
+    youtube: "rtmp://a.rtmp.youtube.com/live2",
+    x: "rtmp://ingest.x.com:1935/live",
+    facebook: "rtmps://live-api-s.facebook.com:443/rtmp",
+    tiktok: "rtmp://push.tiktokcdn.com/live",
+    twitch: "rtmp://live.twitch.tv/app",
+    kick: "rtmps://fa723fc1b171.global-contribute.live-video.net:443/app",
+};
+export function resolutionOf(resolution) {
+    return resolution === "720p" ? { width: 1280, height: 720 } : { width: 1920, height: 1080 };
+}
+/** The full ingest URL. Built here so a key is never assembled by a client. */
+export function ingestUrl(destination) {
+    return `${destination.url.replace(/\/+$/, "")}/${destination.key}`;
+}
+/** Somewhere to actually send RTMP. */
+export function isRtmp(url) {
+    return /^rtmps?:\/\/[^\s/]+/i.test(url);
+}
+/**
+ * A destination as it may be shown to anyone. A stream key is a password: it
+ * lets a stranger broadcast as you until you rotate it.
+ */
+export function redact(destination) {
+    const tail = destination.key.slice(-4);
+    return { ...destination, key: destination.key ? `••••${tail}` : "" };
+}
+/**
+ * A tee output. `onfail=ignore` is the important part: without it one dead
+ * destination takes the whole broadcast down with it, and the one that dies is
+ * usually the one whose key expired without telling you.
+ */
+export function teeOutput(url, options = ["f=flv"]) {
+    return `[${[...options, "onfail=ignore"].join(":")}]${url}`;
+}
+/**
+ * The whole ffmpeg command.
+ *
+ * RTMP platforms want a video track even when what you are sending is music,
+ * so a silent source gets a flat colour at the chosen size. It is what a radio
+ * stream looks like on YouTube either way.
+ */
+export function buildBroadcastArgs(plan) {
+    const { width, height } = resolutionOf(plan.settings.resolution);
+    const gop = plan.settings.framerate * plan.settings.keyframeInterval;
+    const args = ["-hide_banner", "-loglevel", "error"];
+    // -re only for a file: a live source already arrives in real time, and
+    // throttling it a second time drifts further behind with every track.
+    if (!/^(https?|rtmps?|pipe):/i.test(plan.source) && plan.source !== "pipe:0")
+        args.push("-re");
+    if (plan.needsVideo) {
+        args.push("-f", "lavfi", "-i", `color=c=black:s=${width}x${height}:r=${plan.settings.framerate}`);
+    }
+    args.push("-i", plan.source);
+    // Video is always input 0: either the invented colour, or the source's own.
+    // Audio moves to input 1 when a colour was pushed in front of it.
+    args.push("-map", "0:v", "-map", plan.needsVideo ? "1:a" : "0:a");
+    args.push("-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency", "-b:v", `${plan.settings.videoBitrate}k`, "-maxrate", `${Math.round(plan.settings.videoBitrate * 1.1)}k`, "-bufsize", `${plan.settings.videoBitrate * 2}k`, 
+    // A strict constant frame rate. A source that only produces frames when
+    // something changes reads to YouTube as a stream that is falling behind.
+    "-vf", `scale=${width}:${height},fps=${plan.settings.framerate}`, "-pix_fmt", "yuv420p", "-g", String(gop), "-c:a", "aac", "-b:a", `${plan.settings.audioBitrate}k`, "-ar", "44100");
+    const outputs = plan.destinations
+        .filter((d) => d.enabled && isRtmp(d.url))
+        .map((d) => teeOutput(ingestUrl(d)));
+    // The web copy rides along on the same encode, audio only, down stdout.
+    if (plan.webAudio)
+        outputs.push(teeOutput("pipe:1", ["select=a", "f=mp3"]));
+    if (outputs.length === 0)
+        return [];
+    // One output does not need the tee muxer, and ffmpeg reports its errors more
+    // clearly without it.
+    if (outputs.length === 1 && !plan.webAudio) {
+        const only = plan.destinations.find((d) => d.enabled && isRtmp(d.url));
+        args.push("-f", "flv", ingestUrl(only));
+        return args;
+    }
+    args.push("-flags", "+global_header", "-f", "tee", outputs.join("|"));
+    return args;
+}
+/**
+ * One broadcast at a time, restarted when it dies. A live stream that stops
+ * because a platform hiccupped, and stays stopped, is worse than no feature.
+ */
+export class Broadcaster {
+    ffmpeg;
+    delay;
+    child = null;
+    plan = null;
+    timer = null;
+    attempts = 0;
+    state = "idle";
+    since = null;
+    error = "";
+    constructor(ffmpeg = ["ffmpeg"], 
+    /** Injected so a test never waits five real seconds. */
+    delay = (ms, run) => setTimeout(run, ms)) {
+        this.ffmpeg = ffmpeg;
+        this.delay = delay;
+    }
+    status() {
+        return {
+            state: this.state,
+            since: this.since,
+            destinations: (this.plan?.destinations ?? []).filter((d) => d.enabled).map((d) => d.name),
+            error: this.error,
+        };
+    }
+    start(plan) {
+        const args = buildBroadcastArgs(plan);
+        if (args.length === 0)
+            return { ok: false, error: "no enabled destination with an rtmp url" };
+        this.stop();
+        this.plan = plan;
+        this.attempts = 0;
+        this.error = "";
+        this.spawn(args);
+        return { ok: true, error: "" };
+    }
+    stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.plan = null;
+        this.state = "idle";
+        this.since = null;
+        const child = this.child;
+        this.child = null;
+        child?.kill("SIGKILL");
+    }
+    spawn(args) {
+        const [command, ...prefix] = this.ffmpeg;
+        const child = spawn(command, [...prefix, ...args], { stdio: ["ignore", "pipe", "pipe"] });
+        this.child = child;
+        this.state = "live";
+        this.since = Date.now();
+        let tail = "";
+        child.stderr?.on("data", (chunk) => {
+            tail = (tail + chunk.toString()).slice(-2000);
+        });
+        child.on("error", (error) => {
+            this.error = error.message;
+            this.state = "failed";
+        });
+        child.on("close", (code) => {
+            if (this.child !== child)
+                return; // stopped on purpose, or replaced
+            this.child = null;
+            if (code === 0) {
+                this.state = "idle";
+                this.since = null;
+                return;
+            }
+            this.error = tail.trim().split("\n").pop() ?? `ffmpeg exited ${code}`;
+            this.state = "failed";
+            this.retry();
+        });
+    }
+    /** Back off, but never give up entirely while a plan is set. */
+    retry() {
+        const plan = this.plan;
+        if (plan === null)
+            return;
+        this.attempts++;
+        const wait = Math.min(30_000, 1000 * 2 ** Math.min(5, this.attempts - 1));
+        this.timer = this.delay(wait, () => {
+            if (this.plan !== plan)
+                return;
+            this.spawn(buildBroadcastArgs(plan));
+        });
+    }
+}

package/dist/channels.d.ts

@@ -0,0 +1,94 @@
+import type { Readable } from "node:stream";
+/** Somewhere for a channel's audio to go. A response, in practice. */
+export interface Listener {
+    write(chunk: Buffer): boolean;
+    end(): void;
+}
+export interface ChannelInfo {
+    id: string;
+    /** What the publisher called itself. */
+    name: string;
+    /** The container it is sending, e.g. webm from a browser, flv over RTMP. */
+    format: string;
+    /** How it arrived. */
+    via: "http" | "rtmp";
+    startedAt: number;
+    bytes: number;
+    listeners: number;
+}
+/** A name that can sit in a URL and be read back in a list. */
+export declare function cleanId(value: unknown, fallback?: string): string;
+export interface ChannelOptions {
+    ffmpeg: string[];
+    onStart?: (info: ChannelInfo) => void;
+    onEnd?: (info: ChannelInfo) => void;
+}
+/**
+ * One live source, and its audience.
+ *
+ * Everything a listener is sent has been through ffmpeg, so a publisher cannot
+ * decide what bytes reach a browser by choosing what to send.
+ */
+export declare class Channel {
+    readonly info: ChannelInfo;
+    private readonly options;
+    private readonly onGone;
+    readonly listeners: Set<Listener>;
+    private child;
+    private closing;
+    constructor(info: ChannelInfo, options: ChannelOptions, onGone: (id: string) => void);
+    start(format: string): void;
+    /** Feed the source. */
+    write(chunk: Buffer): boolean;
+    pump(body: Readable): Promise<void>;
+    /**
+     * Audio that is already in its final form, from a source we did not spawn.
+     * The bytes still only reach a listener after something decoded them; it was
+     * simply a different process that did it.
+     */
+    feed(chunk: Buffer): void;
+    /** Write to everyone, and drop anybody whose socket has gone. */
+    private send;
+    listen(listener: Listener): () => void;
+    close(): void;
+}
+/**
+ * Every channel currently live.
+ *
+ * A channel exists while somebody is publishing to it and disappears when they
+ * stop, so the list is what is actually on rather than what was once
+ * configured.
+ */
+export declare class Channels {
+    private readonly options;
+    private readonly open;
+    constructor(options: ChannelOptions);
+    list(): ChannelInfo[];
+    get count(): number;
+    /** Total listeners across every channel. */
+    get listeners(): number;
+    has(id: string): boolean;
+    /**
+     * Claim a channel and start decoding into it. Null when that channel is
+     * already being published to: two publishers on one channel would be two
+     * songs at once, which is never what anybody meant. Publishing to a
+     * *different* channel is exactly what this class exists for.
+     */
+    publish(id: string, name: string, format: string, via: ChannelInfo["via"]): Channel | null;
+    /** Attach a listener, or null when nothing is playing on that channel. */
+    listen(id: string, listener: Listener): (() => void) | null;
+    /** Feed a channel that already exists, for a publisher sending chunks. */
+    writeTo(id: string, chunk: Buffer): boolean;
+    /**
+     * A channel fed by audio somebody else is already decoding.
+     *
+     * An RTMP listener is an ffmpeg with a publisher on one end, and it produces
+     * MP3 on its own. Spawning a second ffmpeg to decode what the first one just
+     * decoded would double the work to arrive at the same bytes.
+     */
+    attach(id: string, name: string, format: string, via: ChannelInfo["via"]): Channel | null;
+    stop(id: string): boolean;
+    stopAll(): void;
+}
+/** A channel id nobody chose, for a publisher that did not name one. */
+export declare function generatedId(): string;