nixamp 0.2.0 → 0.4.0

package/dist/paywall.js

@@ -0,0 +1,162 @@
+/**
+ * Paying to listen, once a stream is busy.
+ *
+ * A nixamp serving a handful of friends should cost nothing and ask nothing.
+ * Past that it is bandwidth someone is paying for, so the gate opens: over the
+ * free listener count, a new listener is answered 402 with an x402 offer and a
+ * dollar buys a day.
+ *
+ * Three things are deliberate. The count is of *live* listeners, so a stream
+ * quietens back to free on its own. Only the audio is gated, because a 402 on
+ * /api/state would break the page that has to render the offer. And nobody is
+ * ever cut off mid-track: the gate is asked once, when a request arrives, and
+ * a listener who got in stays in.
+ */
+import { createGateway } from "@profullstack/x402-gateway";
+/** Listeners who get in for nothing. The sixth is the one who pays. */
+export const FREE_LISTENERS = 5;
+export const DEFAULT_PAYWALL = {
+    enabled: false,
+    payTo: "",
+    coinpayKey: "",
+    priceCents: 100,
+    passMinutes: 1440,
+};
+/** Only the audio is behind the gate. */
+export const GATED = ["/api/stream/", "/api/media/", "/api/live"];
+export function isGated(path) {
+    return GATED.some((prefix) => path.startsWith(prefix));
+}
+/**
+ * Whether this request should be charged at all. Configuration first, because
+ * a disabled paywall must never answer 402; then the path, then how busy the
+ * stream is.
+ */
+export function shouldCharge(config, path, liveListeners) {
+    if (!config.enabled || !config.payTo)
+        return false;
+    if (!isGated(path))
+        return false;
+    return liveListeners > FREE_LISTENERS;
+}
+/**
+ * A node http shim over the gateway's Fetch-API handler. Returns true when it
+ * answered the request, so the server's own routing can stop.
+ */
+export function createPaywall(options) {
+    let built = null;
+    /** Rebuilt when the configuration changes, because it can change at runtime. */
+    const gateway = (config, siteUrl) => {
+        const key = `${siteUrl} ${JSON.stringify(config)}`;
+        if (built?.key === key)
+            return built.handle;
+        const gate = createGateway({
+            siteUrl,
+            siteName: "nixamp",
+            payTo: config.payTo,
+            priceCents: config.priceCents,
+            passMinutes: config.passMinutes,
+            coinpay: { apiKey: config.coinpayKey },
+            header: "x-nixamp-pass",
+            path: "/listen/pay",
+            // Whether to charge is about how busy this stream is, not about who is
+            // asking, so the agent lists play no part.
+            isPaidAgent: () => true,
+            benefits: ["Listen to this stream for a day, as many tracks as you like."],
+        });
+        built = { key, handle: (request) => gate.handle(request) };
+        return built.handle;
+    };
+    return async function paywall(request, response, path) {
+        const config = options.config();
+        // The sales page answers whenever the paywall is configured, so a listener
+        // can buy a pass before the stream is busy enough to need one.
+        const selling = config.enabled && config.payTo !== "" && path.startsWith("/listen/pay");
+        if (!selling && !shouldCharge(config, path, options.liveListeners()))
+            return false;
+        if (options.exempt(request))
+            return false;
+        const siteUrl = options.siteUrl();
+        const answer = await gateway(config, siteUrl)(toRequest(request, siteUrl));
+        if (answer === null)
+            return false;
+        const body = await rewrite(answer, siteUrl);
+        response.writeHead(answer.status, {
+            ...Object.fromEntries(answer.headers),
+            "content-length": String(body.byteLength),
+        });
+        response.end(body);
+        return true;
+    };
+}
+/**
+ * The gateway sells crawl access, and says so: its 402 tells the caller that
+ * "payment is required for training crawlers". Someone trying to hear a song
+ * is not a crawler, so the sentence is replaced on the way out. The offer
+ * itself is untouched -- only the words are ours.
+ */
+export async function rewrite(answer, siteUrl) {
+    const raw = Buffer.from(await answer.arrayBuffer());
+    if (answer.status !== 402 || !(answer.headers.get("content-type") ?? "").includes("json"))
+        return raw;
+    try {
+        const parsed = JSON.parse(raw.toString("utf8"));
+        parsed["error"] =
+            `This stream has more than ${FREE_LISTENERS} people listening. ` +
+                `A pass is ${parsed.pass?.price ?? "$1"} for a day: ${siteUrl}/listen/pay`;
+        return Buffer.from(JSON.stringify(parsed));
+    }
+    catch {
+        // Not JSON after all: send exactly what the gateway produced.
+        return raw;
+    }
+}
+/**
+ * Enough of a Fetch Request for the gateway: it reads the URL, the method and
+ * headers. A body would need streaming, and nothing it gates has one.
+ */
+export function toRequest(request, siteUrl) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (value === undefined)
+            continue;
+        headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+    }
+    return new Request(new URL(request.url ?? "/", siteUrl), {
+        method: request.method ?? "GET",
+        headers,
+    });
+}
+/** Read a paywall out of the environment, for an operator who runs one by hand. */
+export function paywallFromEnv(env = process.env) {
+    const price = Number(env["NIXAMP_PRICE_CENTS"]);
+    const minutes = Number(env["NIXAMP_PASS_MINUTES"]);
+    return {
+        enabled: env["NIXAMP_X402"] === "1",
+        payTo: env["NIXAMP_PAY_TO"] ?? "",
+        coinpayKey: env["COINPAY_X402_KEY"] ?? "",
+        priceCents: Number.isFinite(price) && price > 0 ? Math.floor(price) : DEFAULT_PAYWALL.priceCents,
+        passMinutes: Number.isFinite(minutes) && minutes > 0 ? Math.floor(minutes) : DEFAULT_PAYWALL.passMinutes,
+    };
+}
+/**
+ * The directory's answer may carry a configuration, which is how a server is
+ * turned on and off from nixamp.com. Anything missing keeps what it had, and
+ * a payTo the operator did not set is never invented here.
+ */
+export function applyRemoteConfig(current, remote) {
+    if (typeof remote !== "object" || remote === null)
+        return current;
+    const record = remote;
+    const price = Number(record["priceCents"]);
+    const minutes = Number(record["passMinutes"]);
+    return {
+        enabled: typeof record["enabled"] === "boolean" ? record["enabled"] : current.enabled,
+        payTo: typeof record["payTo"] === "string" && record["payTo"] ? record["payTo"] : current.payTo,
+        coinpayKey: typeof record["coinpayKey"] === "string" && record["coinpayKey"]
+            ? record["coinpayKey"]
+            : current.coinpayKey,
+        priceCents: Number.isFinite(price) && price > 0 ? Math.floor(price) : current.priceCents,
+        passMinutes: Number.isFinite(minutes) && minutes > 0 ? Math.floor(minutes) : current.passMinutes,
+    };
+}

package/dist/playlist.js

@@ -6,6 +6,11 @@ import { isHls, isPlaylistFile, isRemote, nameOf, parseM3u, parsePls, } from "./
 export const AUDIO_EXTENSIONS = new Set([
     ".mp3", ".flac", ".ogg", ".oga", ".opus", ".m4a", ".aac",
     ".wav", ".wma", ".aiff", ".aif", ".alac", ".mp4", ".webm",
+    // Video containers, for their audio. Everything on the way out of here is
+    // already decoded by ffmpeg and re-encoded to MP3 with -vn, so a film is a
+    // long track with a picture nobody asked for -- and a library of them was
+    // invisible to nixamp for want of the extension being on this list.
+    ".mkv", ".avi", ".mov", ".m4v", ".mpg", ".mpeg", ".wmv", ".flv",
 ]);
 export function isAudio(path) {
     const dot = path.lastIndexOf(".");

package/dist/publish.d.ts

@@ -0,0 +1,57 @@
+import { DEFAULT_DIRECTORY, type Listing } from "./directory.ts";
+export interface PublishTarget {
+    directory: string;
+    name: string;
+    /** The listen link: what a stranger opens. Never the control key. */
+    url: string;
+    /**
+     * The same stream as bytes, for a listener that cannot hold a cookie.
+     *
+     * The phone line plays this address into a call. The listen link cannot be
+     * played: it is a redirect that sets a cookie, and Telnyx fetching it once
+     * gets a 401 in JSON, which is a caller hearing nothing.
+     */
+    audio?: string;
+    tracks: number;
+    nowPlaying: () => string;
+    /**
+     * The account this stream belongs to, from `nixamp login`.
+     *
+     * The directory used to take anybody's word for a listing. It cannot any
+     * more: a listing now carries a phone code people dial and minutes somebody
+     * pays for, so it has to be attributable. Reading the directory is still
+     * open to everyone -- it is announcing that needs a name behind it.
+     */
+    token?: string;
+    /**
+     * Called with whatever configuration the directory sent back. This is how
+     * nixamp.com turns x402 on and off for a server without it restarting.
+     */
+    onConfig?: (config: unknown) => void;
+    /** Called when the directory refused us for want of an account. */
+    onRefused?: () => void;
+}
+/**
+ * Ask, with yes as the default. Returns false without asking when there is no
+ * terminal on the other end, which is the case for the daemon and for CI.
+ */
+export declare function confirm(question: string, tty?: boolean): Promise<boolean>;
+/**
+ * Announce, then keep announcing. The directory forgets an entry that stops
+ * renewing, so stopping the heartbeat is how a stream leaves the list even if
+ * the process dies without saying goodbye.
+ */
+export declare class Publisher {
+    private readonly target;
+    private readonly fetcher;
+    private id;
+    private timer;
+    /** Whether we have already said that the directory wants an account. */
+    private refused;
+    constructor(target: PublishTarget, fetcher?: typeof fetch);
+    start(): Promise<Listing | null>;
+    announce(): Promise<Listing | null>;
+    /** Leave the list now rather than waiting to be forgotten. */
+    stop(): Promise<void>;
+}
+export { DEFAULT_DIRECTORY };

package/dist/publish.js

@@ -0,0 +1,106 @@
+/**
+ * Publishing to the directory, and asking first.
+ *
+ * Listing a stream tells the world an address it can reach you on, so it is
+ * never done silently. The prompt defaults to yes; a terminal that cannot ask
+ * defaults to no, because "there was nobody to ask" is not consent.
+ */
+import { createInterface } from "node:readline/promises";
+import { DEFAULT_DIRECTORY, HEARTBEAT_MS } from "./directory.js";
+/**
+ * Ask, with yes as the default. Returns false without asking when there is no
+ * terminal on the other end, which is the case for the daemon and for CI.
+ */
+export async function confirm(question, tty = process.stdin.isTTY === true) {
+    if (!tty)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+        return answer === "" || answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Announce, then keep announcing. The directory forgets an entry that stops
+ * renewing, so stopping the heartbeat is how a stream leaves the list even if
+ * the process dies without saying goodbye.
+ */
+export class Publisher {
+    target;
+    fetcher;
+    id = null;
+    timer = null;
+    /** Whether we have already said that the directory wants an account. */
+    refused = false;
+    constructor(target, fetcher = fetch) {
+        this.target = target;
+        this.fetcher = fetcher;
+    }
+    async start() {
+        const first = await this.announce();
+        this.timer = setInterval(() => void this.announce(), HEARTBEAT_MS);
+        this.timer.unref?.();
+        return first;
+    }
+    async announce() {
+        try {
+            const response = await this.fetcher(`${this.target.directory}/api/directory`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(this.target.token ? { authorization: `Bearer ${this.target.token}` } : {}),
+                },
+                body: JSON.stringify({
+                    ...(this.id ? { id: this.id } : {}),
+                    name: this.target.name,
+                    url: this.target.url,
+                    ...(this.target.audio ? { audio: this.target.audio } : {}),
+                    tracks: this.target.tracks,
+                    nowPlaying: this.target.nowPlaying(),
+                }),
+            });
+            if (!response.ok) {
+                // Worth telling the operator about exactly once. A heartbeat that is
+                // refused every 90 seconds should not print every 90 seconds, and
+                // "could not reach the directory" would be the wrong thing to say
+                // about a directory that answered perfectly clearly.
+                if (response.status === 401 && !this.refused) {
+                    this.refused = true;
+                    this.target.onRefused?.();
+                }
+                return null;
+            }
+            const listing = (await response.json());
+            this.id = listing.id;
+            if (listing.config !== undefined)
+                this.target.onConfig?.(listing.config);
+            return listing;
+        }
+        catch {
+            // The directory being down is not a reason for a player to stop playing.
+            return null;
+        }
+    }
+    /** Leave the list now rather than waiting to be forgotten. */
+    async stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        if (this.id === null)
+            return;
+        try {
+            await this.fetcher(`${this.target.directory}/api/directory?id=${encodeURIComponent(this.id)}`, {
+                method: "DELETE",
+                ...(this.target.token ? { headers: { authorization: `Bearer ${this.target.token}` } } : {}),
+            });
+        }
+        catch {
+            // It expires on its own within the TTL, which is the point of the TTL.
+        }
+        this.id = null;
+    }
+}
+export { DEFAULT_DIRECTORY };

package/dist/rtmp-in.d.ts

@@ -0,0 +1,22 @@
+import type { Channels } from "./channels.ts";
+export interface RtmpSlot {
+    port: number;
+    /** The channel a publisher on this port lands on. */
+    id: string;
+}
+/**
+ * Arm a listener per slot, and arm it again after each publisher leaves --
+ * otherwise a broadcaster who reconnects finds nothing listening.
+ */
+export declare class RtmpListeners {
+    private readonly channels;
+    private readonly ffmpeg;
+    private readonly key;
+    private readonly running;
+    private stopped;
+    constructor(channels: Channels, ffmpeg: string[], key: string);
+    listen(slots: RtmpSlot[]): void;
+    private arm;
+    private done;
+    stop(): void;
+}

package/dist/rtmp-in.js

@@ -0,0 +1,79 @@
+/**
+ * RTMP publishers, several at once.
+ *
+ * ffmpeg's RTMP listener serves one connection and exits, so N simultaneous
+ * publishers means N listeners on N ports. That is the honest cost of using
+ * ffmpeg as the RTMP server rather than implementing the protocol, and it buys
+ * a broadcaster that every phone and desktop app already speaks.
+ *
+ * Each listener decodes to MP3 itself, so its channel fans those bytes out
+ * without decoding them a second time.
+ */
+import { spawn } from "node:child_process";
+/**
+ * Arm a listener per slot, and arm it again after each publisher leaves --
+ * otherwise a broadcaster who reconnects finds nothing listening.
+ */
+export class RtmpListeners {
+    channels;
+    ffmpeg;
+    key;
+    running = new Map();
+    stopped = false;
+    constructor(channels, ffmpeg, key) {
+        this.channels = channels;
+        this.ffmpeg = ffmpeg;
+        this.key = key;
+    }
+    listen(slots) {
+        for (const slot of slots)
+            this.arm(slot);
+    }
+    arm(slot) {
+        if (this.stopped || this.running.has(slot.port))
+            return;
+        const [command, ...prefix] = this.ffmpeg;
+        const child = spawn(command, [
+            ...prefix,
+            "-hide_banner",
+            "-loglevel", "error",
+            "-rtmp_listen", "1",
+            // Wait indefinitely: a stream that starts tomorrow is still the stream.
+            "-timeout", "-1",
+            "-f", "flv",
+            "-i", `rtmp://0.0.0.0:${slot.port}/live/${this.key}`,
+            "-vn",
+            "-c:a", "libmp3lame",
+            "-b:a", "192k",
+            "-y",
+            "-f", "mp3",
+            "pipe:1",
+        ], { stdio: ["ignore", "pipe", "pipe"] });
+        this.running.set(slot.port, child);
+        // The first bytes are the only honest signal that a publisher turned up:
+        // ffmpeg does not announce a connect, and a healthy stream says nothing at
+        // -loglevel error.
+        let channel = null;
+        child.stdout?.on("data", (chunk) => {
+            channel ??= this.channels.attach(slot.id, "an RTMP publisher", "flv", "rtmp");
+            channel?.feed(chunk);
+        });
+        child.stdout?.on("error", () => child.kill("SIGKILL"));
+        child.on("error", () => this.done(slot, child, channel));
+        child.on("close", () => this.done(slot, child, channel));
+    }
+    done(slot, child, channel) {
+        if (this.running.get(slot.port) !== child)
+            return;
+        this.running.delete(slot.port);
+        channel?.close();
+        if (!this.stopped)
+            this.arm(slot);
+    }
+    stop() {
+        this.stopped = true;
+        for (const child of this.running.values())
+            child.kill("SIGKILL");
+        this.running.clear();
+    }
+}

package/dist/server.d.ts

@@ -1,5 +1,13 @@
 import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { Connections } from "./connections.ts";
+import { Broadcaster, type Destination, type EncoderSettings } from "./broadcast.ts";
+import { Ingest } from "./ingest.ts";
+import { Channels } from "./channels.ts";
+import { Accounts } from "./accounts.ts";
+import { Owner } from "./owner.ts";
+import { Directory } from "./directory.ts";
+import { PartyLine } from "./partyline.ts";
+import { Follows } from "./follows.ts";
 import { type Tools, type Track } from "./audio.ts";
 import { type Command, type RemoteTrack, type Snapshot } from "./protocol.ts";
 export declare const SERVE_BAND_COUNT = 24;
@@ -28,6 +36,41 @@ export interface ServeOptions {
      * failed instead of started.
      */
     announce: boolean;
+    /** Host the public directory. Only the deployment behind nixamp.com does. */
+    directory: boolean;
+    /**
+     * List this stream at nixamp.com/directory. "ask" prompts, and is the
+     * default: publishing an address without being asked is not something a
+     * player gets to decide for you.
+     */
+    publish: "ask" | "yes" | "no";
+    /** What to call it in the list. Defaults to this machine's hostname. */
+    name: string;
+    /**
+     * Charge for listening once the stream is busy. Off unless asked for, and
+     * useless without somewhere to pay: see NIXAMP_PAY_TO.
+     */
+    x402: boolean;
+    /** The account id that may administer this server, if not the signed-in one. */
+    owner: string;
+    /** Accept a live stream from a phone or a desktop, over HTTP. */
+    ingest: boolean;
+    /**
+     * Also listen for RTMP publishers on this port, which is what OBS, Larix and
+     * anything else native speaks. 0 means do not.
+     */
+    rtmpIn: number;
+    /**
+     * How many RTMP publishers may be live at once. ffmpeg's listener serves one
+     * connection per process, so this is a port and a process each: 1935, 1936,
+     * and so on. HTTP publishers are not limited by this.
+     */
+    rtmpStreams: number;
+    /**
+     * RTMP destinations, as `name=rtmp://host/app/key` or `youtube=key` for one
+     * of the presets. Repeatable.
+     */
+    rtmp: string[];
 }
 /**
  * Flags are parsed by hand: three of them do not justify a dependency, and the
@@ -120,6 +163,12 @@ export interface HandlerOptions {
     version: string;
     /** The key from the share link, or null to serve to anyone who can connect. */
     key?: string | null;
+    /**
+     * A second key that may listen but not drive. The public directory hands
+     * this one out: a link that lets a stranger pause your music is not a link
+     * you can publish.
+     */
+    listenKey?: string | null;
     /** How to run ffmpeg, for the sources a browser cannot play by itself. */
     ffmpeg?: string[];
     /** Who is listening, for the admin view. */
@@ -129,6 +178,43 @@ export interface HandlerOptions {
      * imported so the handler stays a plain function of a request.
      */
     load: (source: string) => Promise<Track[]>;
+    /**
+     * The public directory, on the instance that hosts one. Only nixamp.com
+     * passes this; a nixamp on your laptop is a publisher, not a registry.
+     */
+    directory?: Directory;
+    /** Answers a request itself when listening has to be paid for. */
+    paywall?: (request: IncomingMessage, response: ServerResponse, path: string) => Promise<boolean>;
+    /** Live audio coming in from a phone or a desktop. */
+    ingest?: Ingest;
+    /** Several live streams at once, each with its own audience. */
+    channels?: Channels;
+    /** Live audio going out to RTMP. */
+    broadcaster?: Broadcaster;
+    /** Where a broadcast should send, and what it should look like. */
+    broadcast?: () => {
+        destinations: Destination[];
+        settings: EncoderSettings;
+    };
+    /** Accounts, on the instance that keeps them. Only nixamp.com passes this. */
+    accounts?: Accounts;
+    /** True when this instance is reached over https, for the cookie's Secure. */
+    secureCookies?: boolean;
+    /** Who may administer this server. */
+    owner?: Owner;
+    /**
+     * The dial-in party line, on the instance that answers the phone number.
+     * Only nixamp.com passes this; a nixamp on a laptop has no number.
+     */
+    partyLine?: PartyLine;
+    /**
+     * Following broadcasters, and where to reach the people who do. Durable,
+     * unlike everything else here, because the point of a follow is to outlive
+     * the stream.
+     */
+    follows?: Follows;
+    /** The VAPID public key a browser needs before it can subscribe. */
+    vapidPublicKey?: string;
 }
 /**
  * The whole HTTP surface, as a plain function of a request — so a test can
@@ -137,3 +223,11 @@ export interface HandlerOptions {
 export declare function createHandler(engine: Engine, options: HandlerOptions): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
 export declare function createServer(engine: Engine, options: HandlerOptions): Server;
 export declare function serve(argv: string[], version?: string): Promise<void>;
+/**
+ * `--rtmp youtube=<key>` or `--rtmp name=rtmp://host/app/key`.
+ *
+ * A key is a password, so it is taken from the command line or the environment
+ * and never from a request: a client that could name its own destination could
+ * point your broadcast at itself.
+ */
+export declare function parseDestinations(specs: string[]): Destination[];