nixamp 0.1.0 → 0.3.0

package/dist/channels.js

@@ -0,0 +1,235 @@
+/**
+ * Several streams at once.
+ *
+ * A channel is one live source and everybody listening to it. Two or three
+ * devices can publish at the same time -- a phone, a desktop, a second window
+ * -- and each has its own audience, so a listener picks which one to hear.
+ *
+ * The fan-out is the point. One ffmpeg decodes a publisher's bytes once, and
+ * the MP3 it produces is written to every listener attached to that channel.
+ * A decode per listener would cost a CPU core each and, for a live stream,
+ * would not even agree with itself about what "now" is.
+ *
+ * A listener joining halfway through gets the stream from that moment, which is
+ * what live means. MP3 frames are self-describing, so a player finds the next
+ * frame boundary and carries on; there is nothing to catch up on.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+/** A name that can sit in a URL and be read back in a list. */
+export function cleanId(value, fallback = "main") {
+    if (typeof value !== "string")
+        return fallback;
+    const id = value.trim().toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
+    return id.slice(0, 40) || fallback;
+}
+/**
+ * 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 class Channel {
+    info;
+    options;
+    onGone;
+    listeners = new Set();
+    child = null;
+    closing = false;
+    constructor(info, options, onGone) {
+        this.info = info;
+        this.options = options;
+        this.onGone = onGone;
+    }
+    start(format) {
+        const [command, ...prefix] = this.options.ffmpeg;
+        const child = spawn(command, [
+            ...prefix,
+            "-hide_banner",
+            "-loglevel", "error",
+            // Stated, because ffmpeg mis-probes a live unseekable pipe: it reads a
+            // few kilobytes, guesses, and guesses wrong.
+            "-f", format,
+            "-i", "pipe:0",
+            "-vn",
+            "-c:a", "libmp3lame",
+            "-b:a", "192k",
+            "-f", "mp3",
+            "pipe:1",
+        ], { stdio: ["pipe", "pipe", "pipe"] });
+        child.stdout?.on("data", (chunk) => {
+            this.info.bytes += chunk.byteLength;
+            this.send(chunk);
+        });
+        // A publisher that hangs up mid-write breaks the pipe, and an unhandled
+        // EPIPE takes the whole server with it.
+        child.stdin?.on("error", () => this.close());
+        child.stdout?.on("error", () => this.close());
+        child.on("error", () => this.close());
+        child.on("close", () => this.close());
+        this.child = child;
+        this.options.onStart?.(this.info);
+    }
+    /** Feed the source. */
+    write(chunk) {
+        return this.child?.stdin?.write(chunk) ?? false;
+    }
+    async pump(body) {
+        for await (const chunk of body) {
+            if (this.closing)
+                return;
+            if (!this.write(chunk)) {
+                await new Promise((done) => this.child?.stdin?.once("drain", done) ?? done(null));
+            }
+        }
+    }
+    /**
+     * 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) {
+        this.info.bytes += chunk.byteLength;
+        this.send(chunk);
+    }
+    /** Write to everyone, and drop anybody whose socket has gone. */
+    send(chunk) {
+        for (const listener of this.listeners) {
+            try {
+                listener.write(chunk);
+            }
+            catch {
+                // One listener's broken socket is not the channel's problem.
+                this.listeners.delete(listener);
+            }
+        }
+        this.info.listeners = this.listeners.size;
+    }
+    listen(listener) {
+        this.listeners.add(listener);
+        this.info.listeners = this.listeners.size;
+        return () => {
+            this.listeners.delete(listener);
+            this.info.listeners = this.listeners.size;
+        };
+    }
+    close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        const child = this.child;
+        this.child = null;
+        try {
+            child?.stdin?.end();
+        }
+        catch {
+            // Already broken, which is usually why we are here.
+        }
+        child?.kill("SIGKILL");
+        // Listeners are ended rather than left hanging on a stream that stopped.
+        for (const listener of this.listeners) {
+            try {
+                listener.end();
+            }
+            catch {
+                // Gone already.
+            }
+        }
+        this.listeners.clear();
+        this.info.listeners = 0;
+        this.options.onEnd?.(this.info);
+        this.onGone(this.info.id);
+    }
+}
+/**
+ * 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 class Channels {
+    options;
+    open = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    list() {
+        return [...this.open.values()]
+            .map((channel) => channel.info)
+            .sort((a, b) => a.startedAt - b.startedAt);
+    }
+    get count() {
+        return this.open.size;
+    }
+    /** Total listeners across every channel. */
+    get listeners() {
+        let total = 0;
+        for (const channel of this.open.values())
+            total += channel.listeners.size;
+        return total;
+    }
+    has(id) {
+        return this.open.has(id);
+    }
+    /**
+     * 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, name, format, via) {
+        if (this.open.has(id))
+            return null;
+        const channel = new Channel({
+            id,
+            name: name || "a device",
+            format,
+            via,
+            startedAt: Date.now(),
+            bytes: 0,
+            listeners: 0,
+        }, this.options, (gone) => this.open.delete(gone));
+        this.open.set(id, channel);
+        channel.start(format);
+        return channel;
+    }
+    /** Attach a listener, or null when nothing is playing on that channel. */
+    listen(id, listener) {
+        const channel = this.open.get(id);
+        return channel ? channel.listen(listener) : null;
+    }
+    /** Feed a channel that already exists, for a publisher sending chunks. */
+    writeTo(id, chunk) {
+        return this.open.get(id)?.write(chunk) ?? false;
+    }
+    /**
+     * 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, name, format, via) {
+        if (this.open.has(id))
+            return null;
+        const channel = new Channel({ id, name: name || "a device", format, via, startedAt: Date.now(), bytes: 0, listeners: 0 }, this.options, (gone) => this.open.delete(gone));
+        this.open.set(id, channel);
+        return channel;
+    }
+    stop(id) {
+        const channel = this.open.get(id);
+        if (!channel)
+            return false;
+        channel.close();
+        return true;
+    }
+    stopAll() {
+        for (const channel of [...this.open.values()])
+            channel.close();
+    }
+}
+/** A channel id nobody chose, for a publisher that did not name one. */
+export function generatedId() {
+    return `s${randomBytes(3).toString("hex")}`;
+}

package/dist/connections.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Who is listening.
+ *
+ * A stream is a long-lived request, so the server can say exactly who is
+ * connected, to what, since when and how much has gone out. That is the whole
+ * point of the admin view: `ss -tn` tells you a socket exists, and nothing
+ * about which track is going down it.
+ */
+import type { IncomingMessage } from "node:http";
+export type Kind = "stream" | "media" | "events" | "page";
+export interface Connection {
+    id: number;
+    kind: Kind;
+    /** The remote address, with an IPv4-mapped IPv6 prefix taken off. */
+    address: string;
+    /** Where that address lives: your network, tailscale, or the internet. */
+    network: "local" | "private" | "cgnat" | "public";
+    /** What is going down it, when we know. */
+    track: string;
+    /** Whatever the client called itself, trimmed to something printable. */
+    agent: string;
+    startedAt: number;
+    /**
+     * Bytes handed to the socket, which is not the same as bytes the listener
+     * has heard: the kernel buffers, and a slow client can be several seconds
+     * behind this number. It is the right figure for "is anything going out".
+     */
+    bytes: number;
+    /** Set when it ends, so the admin view can show what just finished. */
+    endedAt: number | null;
+}
+/** ::ffff:10.0.0.1 is 10.0.0.1 wearing a hat. */
+export declare function normaliseAddress(address: string | undefined): string;
+/** Loopback is not "your network"; it is this machine. */
+export declare function networkOf(address: string): Connection["network"];
+/**
+ * A user agent, cut to the part that identifies it. Browsers write a paragraph
+ * about every engine they have ever pretended to be.
+ */
+export declare function shortAgent(agent: string | undefined): string;
+/**
+ * The live set. Finished connections are kept for a while, because "it stopped
+ * ten seconds ago" is the most useful thing an admin view can tell you when
+ * someone says the stream dropped.
+ */
+export declare class Connections {
+    private readonly keep;
+    private next;
+    private readonly items;
+    /** How many finished connections to remember. */
+    constructor(keep?: number);
+    open(request: IncomingMessage, kind: Kind, track: string): Connection;
+    close(id: number): void;
+    add(id: number, bytes: number): void;
+    /**
+     * Live first, oldest connection at the top; then the most recently finished.
+     *
+     * The id breaks ties because Date.now() has millisecond resolution and ten
+     * connections can easily end inside one, which left the order down to
+     * whatever the sort happened to do.
+     */
+    list(): Connection[];
+    /**
+     * Live connections that are actually hearing something. The state feed and
+     * the page are not listeners, and counting them would put a stream over the
+     * free allowance with nobody listening to it.
+     */
+    get listening(): number;
+    get active(): number;
+    /** Drop the oldest finished entries once there are more than we keep. */
+    private prune;
+}

package/dist/connections.js

@@ -0,0 +1,128 @@
+import { classify } from "./share.js";
+/** ::ffff:10.0.0.1 is 10.0.0.1 wearing a hat. */
+export function normaliseAddress(address) {
+    if (!address)
+        return "unknown";
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+    return mapped?.[1] ?? address;
+}
+/** Loopback is not "your network"; it is this machine. */
+export function networkOf(address) {
+    if (address === "127.0.0.1" || address === "::1" || address === "unknown")
+        return "local";
+    if (!/^\d+\.\d+\.\d+\.\d+$/.test(address))
+        return "public";
+    return classify(address);
+}
+/**
+ * A user agent, cut to the part that identifies it. Browsers write a paragraph
+ * about every engine they have ever pretended to be.
+ */
+export function shortAgent(agent) {
+    if (!agent)
+        return "—";
+    const known = [
+        [/\bFirefox\/([\d.]+)/, "Firefox"],
+        [/\bEdg\/([\d.]+)/, "Edge"],
+        [/\bOPR\/([\d.]+)/, "Opera"],
+        [/\bChrome\/([\d.]+)/, "Chrome"],
+        [/\bVersion\/([\d.]+).*\bSafari\//, "Safari"],
+        [/\bVLC\/([\d.]+)/, "VLC"],
+        [/\bcurl\/([\d.]+)/, "curl"],
+        [/\bmpv\b/, "mpv"],
+        [/\bLavf\/([\d.]+)/, "ffmpeg"],
+    ];
+    for (const [pattern, name] of known) {
+        const found = pattern.exec(agent);
+        if (found)
+            return found[1] ? `${name} ${found[1].split(".")[0]}` : name;
+    }
+    return agent.slice(0, 24);
+}
+/**
+ * The live set. Finished connections are kept for a while, because "it stopped
+ * ten seconds ago" is the most useful thing an admin view can tell you when
+ * someone says the stream dropped.
+ */
+export class Connections {
+    keep;
+    next = 1;
+    items = new Map();
+    /** How many finished connections to remember. */
+    constructor(keep = 50) {
+        this.keep = keep;
+    }
+    open(request, kind, track) {
+        const address = normaliseAddress(request.socket.remoteAddress);
+        const connection = {
+            id: this.next++,
+            kind,
+            address,
+            network: networkOf(address),
+            track,
+            agent: shortAgent(request.headers["user-agent"]),
+            startedAt: Date.now(),
+            bytes: 0,
+            endedAt: null,
+        };
+        this.items.set(connection.id, connection);
+        return connection;
+    }
+    close(id) {
+        const found = this.items.get(id);
+        if (!found || found.endedAt !== null)
+            return;
+        found.endedAt = Date.now();
+        this.prune();
+    }
+    add(id, bytes) {
+        const found = this.items.get(id);
+        if (found)
+            found.bytes += bytes;
+    }
+    /**
+     * Live first, oldest connection at the top; then the most recently finished.
+     *
+     * The id breaks ties because Date.now() has millisecond resolution and ten
+     * connections can easily end inside one, which left the order down to
+     * whatever the sort happened to do.
+     */
+    list() {
+        const all = [...this.items.values()];
+        const live = all
+            .filter((c) => c.endedAt === null)
+            .sort((a, b) => a.startedAt - b.startedAt || a.id - b.id);
+        const done = all
+            .filter((c) => c.endedAt !== null)
+            .sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0) || b.id - a.id);
+        return [...live, ...done];
+    }
+    /**
+     * Live connections that are actually hearing something. The state feed and
+     * the page are not listeners, and counting them would put a stream over the
+     * free allowance with nobody listening to it.
+     */
+    get listening() {
+        let count = 0;
+        for (const item of this.items.values()) {
+            if (item.endedAt === null && (item.kind === "stream" || item.kind === "media"))
+                count++;
+        }
+        return count;
+    }
+    get active() {
+        let count = 0;
+        for (const item of this.items.values())
+            if (item.endedAt === null)
+                count++;
+        return count;
+    }
+    /** Drop the oldest finished entries once there are more than we keep. */
+    prune() {
+        const done = [...this.items.values()]
+            .filter((c) => c.endedAt !== null)
+            .sort((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0) || a.id - b.id);
+        for (const item of done.slice(0, Math.max(0, done.length - this.keep)))
+            this.items.delete(item.id);
+    }
+}

package/dist/daemon.d.ts

@@ -0,0 +1,39 @@
+export interface DaemonState {
+    pid: number;
+    host: string;
+    port: number;
+    /** The share key, so `nixamp admin` can talk to it without being told. */
+    key: string | null;
+    source: string;
+    startedAt: number;
+    /** Where its output went, for when it died and you want to know why. */
+    log: string;
+}
+/** XDG, with the usual fallback. One daemon per user, which is one too few for nobody. */
+export declare function stateDir(): string;
+export declare function statePath(): string;
+export declare function logPath(): string;
+export declare function readState(): DaemonState | null;
+export declare function writeState(state: DaemonState): void;
+export declare function clearState(): void;
+/**
+ * Signal 0 asks "could I signal this?" without sending anything. A pid file
+ * outlives the process that wrote it often enough that trusting one is how you
+ * end up reporting a daemon that has been dead since Tuesday.
+ */
+export declare function alive(pid: number): boolean;
+/** The daemon as far as anyone asking is concerned. */
+export declare function status(): {
+    running: boolean;
+    state: DaemonState | null;
+};
+/** The URL an admin client should talk to. */
+export declare function daemonUrl(state: DaemonState): string;
+/**
+ * Start one, detached, and wait until it is actually answering before saying
+ * it started. Reporting success and leaving the user to discover a crash in a
+ * log file is the thing this is meant to avoid.
+ */
+export declare function start(argv: string[], entry: string): Promise<DaemonState>;
+/** Stop it, and wait for it to actually be gone. */
+export declare function stop(timeoutMs?: number): Promise<boolean>;

package/dist/daemon.js

@@ -0,0 +1,170 @@
+/**
+ * Daemon mode.
+ *
+ * `nixamp serve` holds a terminal. A server you leave running should not, and
+ * you should be able to walk away and come back to it, which means something on
+ * disk has to remember where it is and what key it minted. That file is the
+ * whole of the daemon: a pid to signal and enough to reconnect.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** XDG, with the usual fallback. One daemon per user, which is one too few for nobody. */
+export function stateDir() {
+    const base = process.env["XDG_STATE_HOME"] || join(homedir(), ".local", "state");
+    return join(base, "nixamp");
+}
+export function statePath() {
+    return join(stateDir(), "daemon.json");
+}
+export function logPath() {
+    return join(stateDir(), "daemon.log");
+}
+export function readState() {
+    try {
+        return JSON.parse(readFileSync(statePath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(state) {
+    mkdirSync(dirname(statePath()), { recursive: true });
+    writeFileSync(statePath(), `${JSON.stringify(state, null, 2)}\n`);
+}
+export function clearState() {
+    rmSync(statePath(), { force: true });
+}
+/**
+ * Signal 0 asks "could I signal this?" without sending anything. A pid file
+ * outlives the process that wrote it often enough that trusting one is how you
+ * end up reporting a daemon that has been dead since Tuesday.
+ */
+export function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means it exists and belongs to someone else, which is still alive.
+        return error.code === "EPERM";
+    }
+}
+/** The daemon as far as anyone asking is concerned. */
+export function status() {
+    const state = readState();
+    if (state === null)
+        return { running: false, state: null };
+    return { running: alive(state.pid), state };
+}
+/** The URL an admin client should talk to. */
+export function daemonUrl(state) {
+    const host = state.host === "0.0.0.0" || state.host === "::" ? "127.0.0.1" : state.host;
+    return `http://${host.includes(":") ? `[${host}]` : host}:${state.port}`;
+}
+/**
+ * Start one, detached, and wait until it is actually answering before saying
+ * it started. Reporting success and leaving the user to discover a crash in a
+ * log file is the thing this is meant to avoid.
+ */
+export async function start(argv, entry) {
+    const existing = status();
+    if (existing.running && existing.state) {
+        throw new Error(`nixamp: a daemon is already running (pid ${existing.state.pid}). Stop it first.`);
+    }
+    mkdirSync(stateDir(), { recursive: true });
+    const log = logPath();
+    const out = openSync(log, "a");
+    const child = spawn(process.execPath, [entry, "serve", ...argv, "--announce"], {
+        detached: true,
+        stdio: ["ignore", out, out],
+        env: { ...process.env, NIXAMP_DAEMON: "1" },
+    });
+    child.unref();
+    if (child.pid === undefined)
+        throw new Error("nixamp: could not start the daemon");
+    // The server prints one JSON line when it is listening, because guessing how
+    // long a start takes is how a flaky `daemon start` is written.
+    const announced = await waitForAnnounce(log, 15_000);
+    if (announced === null) {
+        try {
+            process.kill(child.pid, "SIGTERM");
+        }
+        catch {
+            // Already gone, which is the more likely reason we are here.
+        }
+        throw new Error(`nixamp: the daemon did not start. See ${log}`);
+    }
+    const state = { ...announced, pid: child.pid, startedAt: Date.now(), log };
+    writeState(state);
+    return state;
+}
+/** Poll the log for the announce line. */
+async function waitForAnnounce(log, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const from = existsSync(log) ? readFileSync(log, "utf8").length : 0;
+    while (Date.now() < deadline) {
+        await new Promise((done) => setTimeout(done, 100));
+        let text;
+        try {
+            text = readFileSync(log, "utf8").slice(from);
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split("\n")) {
+            if (!line.startsWith("{"))
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed["nixamp"] === "listening") {
+                    return {
+                        host: String(parsed["host"]),
+                        port: Number(parsed["port"]),
+                        key: parsed["key"] ?? null,
+                        source: String(parsed["source"]),
+                    };
+                }
+            }
+            catch {
+                // A partial line: it will be complete on the next pass.
+            }
+        }
+    }
+    return null;
+}
+/** Stop it, and wait for it to actually be gone. */
+export async function stop(timeoutMs = 5000) {
+    const { running, state } = status();
+    if (!state)
+        return false;
+    if (!running) {
+        clearState();
+        return false;
+    }
+    try {
+        process.kill(state.pid, "SIGTERM");
+    }
+    catch {
+        clearState();
+        return false;
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!alive(state.pid)) {
+            clearState();
+            return true;
+        }
+        await new Promise((done) => setTimeout(done, 100));
+    }
+    // It ignored SIGTERM. ffmpeg children make that more likely than it sounds.
+    try {
+        process.kill(state.pid, "SIGKILL");
+    }
+    catch {
+        // Gone between the check and the signal.
+    }
+    clearState();
+    return true;
+}