nixamp 0.1.0 → 0.2.0

package/README.md

@@ -48,6 +48,18 @@ curl -fsSL https://nixamp.com/install.sh | sh -s -- --version 0.1.0
 curl -fsSL https://nixamp.com/install.sh | sh -s -- --prefix ~/opt
 ```
 
+On Windows, in PowerShell:
+
+```
+irm https://nixamp.com/install.ps1 | iex
+```
+
+That lands under `%LOCALAPPDATA%\nixamp`, adds itself to your user PATH, and
+needs no administrator rights. Nothing is code signed, so SmartScreen will warn
+the first time.
+
+Builds are published for Linux, macOS and Windows, on both x64 and arm64.
+
 Then:
 
 ```
@@ -63,6 +75,48 @@ network. Your music is never touched.
 If you would rather not pipe a script into a shell, `npm i -g nixamp` and
 `bunx nixamp ~/Music` both work; that route needs Node 24 or newer.
 
+## Leaving it running
+
+`nixamp serve` holds a terminal. `nixamp daemon` does not.
+
+```
+nixamp daemon start ~/Music --open-port
+nixamp daemon status
+nixamp daemon stop
+```
+
+Start writes down where it went and the key it minted, waits until the server
+is actually answering before saying it started, and prints the share link. It is
+one daemon per user, and the state lives in `$XDG_STATE_HOME/nixamp`.
+
+## Watching it
+
+```
+nixamp admin
+```
+
+Who is connected, from where, to what, for how long and how much has gone out.
+It reads the daemon's own state file, so it needs no arguments; point it
+anywhere else with `--url` and `--key`.
+
+```
+╭─ Server ─────────────────────────╮ ╭─ Now playing ────────────────────╮
+│ http://127.0.0.1:4321            │ │ long.flac                        │
+│ /home/anthony/Music              │ │ —                                │
+│ Uptime                        3s │ │ State                    stopped │
+│ Tracks                         1 │ │ Position                      0s │
+│ Listeners                      2 │ │                                  │
+╰──────────────────────────────────╯ ╰──────────────────────────────────╯
+╭─ Connections (2 live) ────────────────────────────────────────────────╮
+│ Where        Network   Kind    Client    Track          For      Sent │
+│ 10.0.0.42    private   media   VLC 3     long.flac       3s   2.6 MiB │
+│ 100.65.1.7   tailscale stream  Safari 17 long.flac      41s    18 MiB │
+╰───────────────────────────────────────────────────────────────────────╯
+```
+
+Press `r` to re-stream: hand the running server a different URL or path and the
+listeners stay connected while what they are hearing changes under them.
+
 ## How it works
 
 One decode feeds both your speakers and the display. `ffmpeg` writes raw 32-bit float samples to a pipe; nixamp reads every sample on its way past, runs an FFT over it, and hands the same bytes to `ffplay`.

package/bin/nixamp.mjs

@@ -2,6 +2,9 @@
 import { main } from "../dist/main.js";
 
 main().catch((error) => {
-  console.error(error);
+  // A message we wrote is a message the user can act on; anything else is a
+  // bug and deserves its stack.
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message.startsWith("nixamp:") ? message : error);
   process.exit(1);
 });

package/dist/admin.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `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 { type Container, type Theme } from "@profullstack/hqtui";
+import type { Connection } from "./connections.ts";
+interface Report {
+    connections: Connection[];
+    active: number;
+    startedAt: number;
+    now: number;
+}
+interface Snapshot {
+    tracks: {
+        title: string;
+        artist: string;
+        duration: number;
+    }[];
+    index: number;
+    playing: boolean;
+    position: number;
+    root: string;
+    note: string;
+}
+export interface AdminOptions {
+    url: string;
+    key: string | null;
+}
+/** Where to point, from the flags or from the daemon that is running. */
+export declare function resolveTarget(argv: string[]): AdminOptions;
+/** Seconds as something a person reads at a glance. */
+export declare function since(ms: number): string;
+export declare function bytes(value: number): string;
+export declare function admin(argv: string[]): Promise<void>;
+export interface View {
+    url: string;
+    report: Report | null;
+    snapshot: Snapshot | null;
+    error: string;
+    typing: boolean;
+    restreaming: string;
+}
+export declare function draw(ui: Container, theme: Theme, view: View): void;
+export {};

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/connections.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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[];
+    get active(): number;
+    /** Drop the oldest finished entries once there are more than we keep. */
+    private prune;
+}

package/dist/connections.js

@@ -0,0 +1,115 @@
+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];
+    }
+    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>;