nixamp 0.2.0 → 0.3.0

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;

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

@@ -60,6 +60,12 @@ export declare class Connections {
      * 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

@@ -97,6 +97,19 @@ export class Connections {
             .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())

package/dist/directory.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The public directory.
+ *
+ * A nixamp that agrees to be listed announces itself to nixamp.com every so
+ * often and is forgotten when it stops. There is no database behind it: an
+ * entry lives for a few minutes and a heartbeat renews it, so a restart of the
+ * directory costs one heartbeat rather than a migration, and a stream that
+ * dies falls out of the list without anyone having to notice.
+ *
+ * What is published is the *listen* link. The control key never leaves the
+ * machine it was minted on.
+ */
+/** How long an entry survives without a heartbeat. */
+export declare const TTL_MS: number;
+/** How often a publisher renews. Comfortably inside the TTL. */
+export declare const HEARTBEAT_MS: number;
+export declare const DEFAULT_DIRECTORY = "https://nixamp.com";
+export interface Listing {
+    /** Assigned by the directory, so a publisher cannot claim someone else's. */
+    id: string;
+    name: string;
+    /** The listen link, which is what a browser opens. */
+    url: string;
+    tracks: number;
+    nowPlaying: string;
+    /** Set by the directory from the request, never by the publisher. */
+    updatedAt: number;
+}
+/** What a publisher sends. Everything else about a listing is ours to decide. */
+export interface Announcement {
+    id?: string;
+    name: string;
+    url: string;
+    tracks: number;
+    nowPlaying: string;
+}
+/** Trim and flatten, so one publisher cannot draw a box in someone's terminal. */
+export declare function clean(value: unknown, max: number): string;
+/**
+ * A URL we are willing to list. It has to be somewhere a browser can go, and
+ * it must not be a loopback or link-local address: those are only reachable
+ * from the machine that published them, so listing one is an entry nobody but
+ * the publisher can ever open.
+ */
+export declare function publishable(raw: string): URL | null;
+export declare function parseAnnouncement(input: unknown): Announcement | null;
+/**
+ * The registry. In memory on purpose: see the note at the top of the file.
+ * One entry per URL, so a publisher restarting does not leave a ghost of
+ * itself behind next to the entry that replaced it.
+ */
+export declare class Directory {
+    private readonly ttl;
+    private readonly now;
+    private readonly items;
+    private sequence;
+    constructor(ttl?: number, now?: () => number);
+    announce(announcement: Announcement): Listing;
+    withdraw(id: string): void;
+    list(): Listing[];
+    /** Forget anything that stopped renewing. */
+    private sweep;
+}

package/dist/directory.js

@@ -0,0 +1,111 @@
+/**
+ * The public directory.
+ *
+ * A nixamp that agrees to be listed announces itself to nixamp.com every so
+ * often and is forgotten when it stops. There is no database behind it: an
+ * entry lives for a few minutes and a heartbeat renews it, so a restart of the
+ * directory costs one heartbeat rather than a migration, and a stream that
+ * dies falls out of the list without anyone having to notice.
+ *
+ * What is published is the *listen* link. The control key never leaves the
+ * machine it was minted on.
+ */
+/** How long an entry survives without a heartbeat. */
+export const TTL_MS = 4 * 60 * 1000;
+/** How often a publisher renews. Comfortably inside the TTL. */
+export const HEARTBEAT_MS = 90 * 1000;
+export const DEFAULT_DIRECTORY = "https://nixamp.com";
+const MAX_NAME = 60;
+const MAX_TRACK = 120;
+/** Trim and flatten, so one publisher cannot draw a box in someone's terminal. */
+export function clean(value, max) {
+    if (typeof value !== "string")
+        return "";
+    // Control characters include the escape that starts an ANSI sequence, and
+    // this text is rendered in a terminal as well as a browser.
+    return value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, max);
+}
+/**
+ * A URL we are willing to list. It has to be somewhere a browser can go, and
+ * it must not be a loopback or link-local address: those are only reachable
+ * from the machine that published them, so listing one is an entry nobody but
+ * the publisher can ever open.
+ */
+export function publishable(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return null;
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host === "::1" || host.endsWith(".localhost"))
+        return null;
+    if (/^127\./.test(host) || /^169\.254\./.test(host))
+        return null;
+    return url;
+}
+export function parseAnnouncement(input) {
+    if (typeof input !== "object" || input === null)
+        return null;
+    const record = input;
+    const url = typeof record["url"] === "string" ? record["url"] : "";
+    if (publishable(url) === null)
+        return null;
+    const name = clean(record["name"], MAX_NAME);
+    const tracks = Number(record["tracks"]);
+    return {
+        ...(typeof record["id"] === "string" ? { id: clean(record["id"], 40) } : {}),
+        name: name || "a nixamp",
+        url,
+        tracks: Number.isFinite(tracks) && tracks >= 0 ? Math.min(1_000_000, Math.floor(tracks)) : 0,
+        nowPlaying: clean(record["nowPlaying"], MAX_TRACK),
+    };
+}
+/**
+ * The registry. In memory on purpose: see the note at the top of the file.
+ * One entry per URL, so a publisher restarting does not leave a ghost of
+ * itself behind next to the entry that replaced it.
+ */
+export class Directory {
+    ttl;
+    now;
+    items = new Map();
+    sequence = 0;
+    constructor(ttl = TTL_MS, now = Date.now) {
+        this.ttl = ttl;
+        this.now = now;
+    }
+    announce(announcement) {
+        this.sweep();
+        const existing = [...this.items.values()].find((item) => item.url === announcement.url);
+        const id = existing?.id ?? `s${++this.sequence}${this.now().toString(36)}`;
+        const listing = {
+            id,
+            name: announcement.name,
+            url: announcement.url,
+            tracks: announcement.tracks,
+            nowPlaying: announcement.nowPlaying,
+            updatedAt: this.now(),
+        };
+        this.items.set(id, listing);
+        return listing;
+    }
+    withdraw(id) {
+        this.items.delete(id);
+    }
+    list() {
+        this.sweep();
+        return [...this.items.values()].sort((a, b) => b.updatedAt - a.updatedAt || a.id.localeCompare(b.id));
+    }
+    /** Forget anything that stopped renewing. */
+    sweep() {
+        const cutoff = this.now() - this.ttl;
+        for (const [id, item] of this.items)
+            if (item.updatedAt < cutoff)
+                this.items.delete(id);
+    }
+}

package/dist/ingest.d.ts

@@ -0,0 +1,80 @@
+import type { Readable } from "node:stream";
+/** A live source is one session at a time: two would be two songs at once. */
+export interface IngestSession {
+    id: string;
+    /** What the sender called itself. */
+    name: string;
+    /** The container the sender is producing, e.g. webm from MediaRecorder. */
+    format: string;
+    startedAt: number;
+    bytes: number;
+}
+export interface IngestStatus {
+    live: boolean;
+    session: IngestSession | null;
+    /** Where a native broadcaster should publish, when one is being listened for. */
+    rtmp: {
+        port: number;
+        path: string;
+    } | null;
+}
+/**
+ * ffmpeg's `-f` is a demuxer name, and passing an unknown one is how a stream
+ * dies four seconds in with a message nobody sees. An unrecognised container is
+ * refused up front instead.
+ */
+export declare function normaliseFormat(value: unknown): string | null;
+export interface IngestOptions {
+    ffmpeg: string[];
+    /** Where the decoded audio should go: a file ffmpeg writes, or a pipe. */
+    sink: string;
+    /** Called when a session starts, so the player can switch to it. */
+    onStart: (session: IngestSession) => void;
+    /** Called when it ends, cleanly or otherwise. */
+    onEnd: (session: IngestSession, error: string) => void;
+    /** Encoded audio, as it arrives from a live publisher. */
+    onAudio?: (chunk: Buffer) => void;
+}
+/**
+ * The live input.
+ *
+ * One session at a time: a second sender is refused rather than mixed, because
+ * mixing two uninvited streams is never what anybody meant.
+ */
+export declare class Ingest {
+    private readonly options;
+    private child;
+    private session;
+    private closing;
+    /** The RTMP listener, which outlives any one publisher. */
+    private rtmpChild;
+    private rtmpPort;
+    private rtmpKey;
+    constructor(options: IngestOptions);
+    status(): IngestStatus;
+    get live(): boolean;
+    /**
+     * Open a session. Returns the session, or null when one is already running:
+     * the caller answers 409, because "somebody else is already broadcasting" is
+     * a different problem from "your request was wrong".
+     */
+    open(name: string, format: string): IngestSession | null;
+    /** Feed it. Returns false once the session is over. */
+    write(chunk: Buffer): boolean;
+    /** Pipe a whole request body in, for a sender that can stream one. */
+    pump(body: Readable): Promise<void>;
+    /**
+     * Wait for an RTMP publisher, and keep waiting after each one leaves.
+     *
+     * ffmpeg is the RTMP server here: `-rtmp_listen 1` binds the port and blocks
+     * until somebody publishes. It serves one publisher and exits, so the
+     * listener is started again afterwards -- otherwise a broadcaster who
+     * reconnects finds nothing listening.
+     */
+    listenRtmp(port: number, key: string): void;
+    /** Stop waiting for publishers. */
+    stopRtmp(): void;
+    private armRtmp;
+    /** End the session, whoever ended it. */
+    close(error?: string): void;
+}