nixamp 0.2.0 → 0.4.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,186 @@
+/**
+ * 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;
+    /**
+     * A six-digit code for this stream, stable across the whole run.
+     *
+     * This is what somebody keys into the phone line. It has to be short enough
+     * to read out and survive being remembered, which the id is not.
+     */
+    code: string;
+    name: string;
+    /**
+     * The account that announced it.
+     *
+     * Set from the signed-in publisher, never from the announcement body -- a
+     * stream that could name its own owner could name somebody else's, and
+     * followers would be told about a broadcast that person is not making.
+     */
+    ownerId: string;
+    /** The listen link, which is what a browser opens. */
+    url: string;
+    /**
+     * The same stream as bytes, for something that is not a browser.
+     *
+     * `url` is a share link: it answers 302, sets a cookie and redirects to the
+     * player page. That is exactly right for a person and useless to anything
+     * that cannot hold a cookie -- the phone line hands this address to Telnyx
+     * to play into a call, and Telnyx fetches it once, anonymously, and expects
+     * audio back. Handed the share link it gets a 401 in JSON and the caller
+     * hears silence after being told the stream is about to start.
+     *
+     * So a publisher announces both: the link a person opens, and the address
+     * that answers with audio/mpeg to a plain GET. Empty when the publisher is
+     * an older nixamp that only knows about `url`.
+     */
+    audio: string;
+    tracks: number;
+    nowPlaying: string;
+    /** Set by the directory from the request, never by the publisher. */
+    updatedAt: number;
+    /** When this stream first announced itself: the "started at" a caller hears. */
+    startedAt: number;
+}
+/**
+ * A stream that has stopped, kept for a while after it fell out of the list.
+ *
+ * The directory proper forgets a stream the moment it stops renewing, which is
+ * right for a list of what is on -- but it means there is nobody left to say
+ * *when* it ended, and "call back later" with no time in it is not worth
+ * saying. So an ended stream leaves this behind: enough to answer the phone
+ * truthfully, and nothing anybody could listen to.
+ */
+export interface Ended {
+    id: string;
+    code: string;
+    name: string;
+    ownerId: string;
+    /** Kept so a stream returning on the same url is recognised as the same one. */
+    url: string;
+    nowPlaying: string;
+    startedAt: number;
+    /** The last heartbeat we saw, which is as close to "ended" as we can know. */
+    endedAt: number;
+}
+/** How long an ended stream is still worth telling a caller about. */
+export declare const ENDED_TTL_MS: number;
+/** What a publisher sends. Everything else about a listing is ours to decide. */
+export interface Announcement {
+    id?: string;
+    name: string;
+    url: string;
+    /** Where the audio actually is. See `Listing.audio`. */
+    audio?: 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;
+    /** Injected so a test can make a code predictable rather than guess it. */
+    private readonly randomCode;
+    /**
+     * Called when a stream starts, and only then.
+     *
+     * A publisher announces every ninety seconds for as long as it is up, so
+     * "announced" is not "went live" -- telling followers on every heartbeat
+     * would be telling them forty times an hour. This fires on the transition
+     * and not on the renewals that follow it.
+     */
+    private readonly onLive;
+    private readonly items;
+    /** Streams that stopped, so the phone line can say when. */
+    private readonly ended;
+    private sequence;
+    /**
+     * Somewhere to echo the ended list, so it survives a restart.
+     *
+     * Attached after construction rather than taken as a constructor argument:
+     * this is a mirror, not a dependency, and the directory works exactly as it
+     * did without one.
+     */
+    private mirror;
+    /** Start echoing ended streams somewhere durable. */
+    persistTo(mirror: {
+        save: (item: Ended) => void;
+        drop: (id: string) => void;
+    }): void;
+    /**
+     * Put back what a previous process knew.
+     *
+     * Only fills gaps: anything already here was announced since we started and
+     * is newer than a row written before the restart.
+     */
+    seedEnded(items: readonly Ended[]): void;
+    constructor(ttl?: number, now?: () => number, 
+    /** Injected so a test can make a code predictable rather than guess it. */
+    randomCode?: () => string, 
+    /**
+     * Called when a stream starts, and only then.
+     *
+     * A publisher announces every ninety seconds for as long as it is up, so
+     * "announced" is not "went live" -- telling followers on every heartbeat
+     * would be telling them forty times an hour. This fires on the transition
+     * and not on the renewals that follow it.
+     */
+    onLive?: (listing: Listing) => void);
+    announce(announcement: Announcement, ownerId?: string): Listing;
+    withdraw(id: string): void;
+    list(): Listing[];
+    /** The live stream on this code, if there is one. */
+    liveByCode(code: string): Listing | undefined;
+    /**
+     * Streams that stopped recently, most recent first.
+     *
+     * Kept for the phone line, which has to say when a stream ended -- but they
+     * answer a second question the live list cannot: who is there to follow.
+     * Following exists to hear about broadcasts you would otherwise miss, and a
+     * directory that only lists what is on can only be used to follow somebody
+     * during a broadcast you did not miss.
+     */
+    recentlyEnded(): Ended[];
+    /** The name last used by an account, live or recently ended. */
+    nameOf(ownerId: string): string;
+    /** Whether this account is streaming right now. */
+    isLive(ownerId: string): boolean;
+    /** The stream that used to be on this code, if it stopped recently. */
+    endedByCode(code: string): Ended | undefined;
+    private endedByUrl;
+    private remember;
+    /** A code no live and no recently-ended stream is using. */
+    private freeCode;
+    /** Forget anything that stopped renewing, keeping a note of when it did. */
+    private sweep;
+}