nixamp 0.5.1 → 0.5.3

package/README.md

@@ -268,6 +268,27 @@ 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`.
 
+### Somewhere the rest of the world can reach
+
+The addresses nixamp prints are the ones its own interfaces have, so a machine
+behind NAT only ever sees `192.168.x` -- no use to anybody else, and nothing it
+can publish. Tell it the address it answers on from outside:
+
+```
+nixamp serve ~/Music --public-url https://nixamp.example.com   # or NIXAMP_PUBLIC_URL
+```
+
+That address is what the share links print and what the directory listing
+carries. Getting one is your business, not nixamp's: a forwarded port, a reverse
+proxy, or a tunnel, e.g.
+
+```
+cloudflared tunnel --url http://localhost:8420
+```
+
+Without it, `--publish` is skipped entirely rather than listing a stream nobody
+outside the house can open.
+
 ### Detaching, and coming back
 
 `d` in the player hands the music to a daemon and gives you your terminal back.

package/dist/daemon.d.ts

@@ -8,6 +8,20 @@ export interface DaemonState {
     startedAt: number;
     /** Where its output went, for when it died and you want to know why. */
     log: string;
+    /**
+     * The labelled addresses the server itself worked out, share key not applied.
+     *
+     * Recorded rather than recomputed because only the server knows them: a
+     * daemon bound to every interface has no single host to print, and the
+     * public one may be a tunnel it was told about rather than an interface
+     * anybody here can see. Absent on a state file written by an older nixamp.
+     */
+    urls?: {
+        label: string;
+        url: string;
+    }[];
+    /** The firewall standing between this port and the rest of the network. */
+    firewall?: string | null;
 }
 /** XDG, with the usual fallback. One daemon per user, which is one too few for nobody. */
 export declare function stateDir(): string;
@@ -29,6 +43,17 @@ export declare function status(): {
 };
 /** The URL an admin client should talk to. */
 export declare function daemonUrl(state: DaemonState): string;
+/**
+ * What `nixamp daemon start` prints, as lines, so it can be tested without
+ * starting a daemon.
+ *
+ * Every address the server found, not one loopback link: the point of a daemon
+ * is the phone in the other room, and 127.0.0.1 is the single address that
+ * cannot be handed to anybody. The firewall warning comes with it because the
+ * server writes that into a log file nobody reads, not to the person who just
+ * typed the command.
+ */
+export declare function daemonLines(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

package/dist/daemon.js

@@ -10,6 +10,7 @@ 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";
+import { portCommands } from "./share.js";
 /** 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");
@@ -63,6 +64,36 @@ 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}`;
 }
+/**
+ * What `nixamp daemon start` prints, as lines, so it can be tested without
+ * starting a daemon.
+ *
+ * Every address the server found, not one loopback link: the point of a daemon
+ * is the phone in the other room, and 127.0.0.1 is the single address that
+ * cannot be handed to anybody. The firewall warning comes with it because the
+ * server writes that into a log file nobody reads, not to the person who just
+ * typed the command.
+ */
+export function daemonLines(state) {
+    const link = (url) => (state.key ? `${url}/s/${state.key}` : url);
+    // A state file written by an older nixamp has no list, so host and port
+    // still stand in rather than printing nothing at all.
+    const addresses = state.urls ?? [{ label: "here", url: daemonUrl(state) }];
+    const width = Math.max(...addresses.map((a) => a.label.length), "source".length);
+    const lines = [`nixamp daemon running (pid ${state.pid})`];
+    for (const { label, url } of addresses)
+        lines.push(`  ${label.padEnd(width)}  ${link(url)}`);
+    lines.push(`  ${"source".padEnd(width)}  ${state.source}`);
+    if (state.firewall) {
+        const { open } = portCommands(state.firewall, state.port);
+        lines.push("", `  ${state.firewall} is running, so nothing else can reach port ${state.port} yet:`, `    sudo ${open.join(" ")}`, "  or `nixamp daemon stop` and start again with --open-port.");
+    }
+    if (!addresses.some((a) => a.label === "on the internet")) {
+        lines.push("", "  None of those work from outside this network. If it should:", "    nixamp daemon start ... --public-url https://your-tunnel.example.com");
+    }
+    lines.push("", "  nixamp attach       the player, in front of it", "  nixamp admin        who is connected", "  nixamp daemon stop  when you are done");
+    return lines;
+}
 /**
  * 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
@@ -119,11 +150,14 @@ async function waitForAnnounce(log, timeoutMs) {
             try {
                 const parsed = JSON.parse(line);
                 if (parsed["nixamp"] === "listening") {
+                    const urls = parsed["urls"];
                     return {
                         host: String(parsed["host"]),
                         port: Number(parsed["port"]),
                         key: parsed["key"] ?? null,
                         source: String(parsed["source"]),
+                        ...(Array.isArray(urls) ? { urls: urls } : {}),
+                        ...(typeof parsed["firewall"] === "string" ? { firewall: parsed["firewall"] } : {}),
                     };
                 }
             }

package/dist/main.js

@@ -67,6 +67,9 @@ Options for serve:
       --publish    list it at nixamp.com/directory without asking first
       --no-publish never list it, and do not ask
       --name NAME  what to call it in the directory (default: this hostname)
+      --public-url URL  the address this server is reachable at from outside,
+                   when that is a tunnel or a forwarded port rather than one of
+                   its own interfaces. Also NIXAMP_PUBLIC_URL
       --ingest     accept a live stream in at POST /api/ingest
       --rtmp-in N  also listen for RTMP publishers (OBS, Larix) from port N
       --rtmp-streams N  how many may publish at once (default 3, a port each)
@@ -192,13 +195,8 @@ async function runDaemon(argv) {
     if (action === "start") {
         try {
             const state = await d.start(rest, entry);
-            console.log(`nixamp daemon running (pid ${state.pid})`);
-            const url = d.daemonUrl(state);
-            console.log(`  ${state.key ? `${url}/s/${state.key}` : url}`);
-            console.log(`  ${state.source}`);
-            console.log("");
-            console.log("  nixamp admin        who is connected");
-            console.log("  nixamp daemon stop  when you are done");
+            for (const line of d.daemonLines(state))
+                console.log(line);
             return 0;
         }
         catch (error) {
@@ -300,7 +298,10 @@ export async function main() {
     const asked = first ?? ".";
     const target = isRemote(asked) ? asked : resolve(asked);
     const tools = detectTools();
-    const tracks = await loadSource(tools, target);
+    // Names now, tags later: an ffprobe per file over a large library is minutes
+    // of a blank terminal before the player appears. The list is the same list;
+    // only the titles arrive late, and they arrive into a player already running.
+    const tracks = await loadSource(tools, target, false);
     if (tracks.length === 0) {
         console.error(`nixamp: no audio files under ${target}`);
         process.exit(1);
@@ -311,6 +312,22 @@ export async function main() {
     // gone. A field rather than a local, because a local assigned only inside a
     // closure stays narrowed to null for the checker.
     const handoff = { to: null };
+    // The titles, arriving into a player that is already up. Not awaited, and
+    // applied only if the list is still the one it describes.
+    if (!isRemote(target)) {
+        void loadSource(tools, target, true)
+            .then((tagged) => {
+            if (tagged.length !== state.tracks.length)
+                return;
+            if (tagged.some((track, at) => track.path !== state.tracks[at]?.path))
+                return;
+            state.tracks = tagged;
+            app.invalidate();
+        })
+            .catch(() => {
+            // Filenames play. Nothing to say about tags that would not read.
+        });
+    }
     const analyser = new Analyser(FFT_SIZE, RATE);
     const edges = bandEdges(BAND_COUNT, RATE, FFT_SIZE);
     // Samples accumulate until there are enough for one transform.

package/dist/server.d.ts

@@ -47,6 +47,15 @@ export interface ServeOptions {
     publish: "ask" | "yes" | "no";
     /** What to call it in the list. Defaults to this machine's hostname. */
     name: string;
+    /**
+     * The address this server is reachable at from outside, when that is not one
+     * of its own interfaces: a tunnel, a reverse proxy, a forwarded port.
+     *
+     * Without it a machine behind NAT has nothing to publish -- every address it
+     * can see is a 192.168 one that is no use to anybody else -- so the directory
+     * listing is skipped and the printed links only work inside the house.
+     */
+    publicUrl: string;
     /**
      * Charge for listening once the stream is busy. Off unless asked for, and
      * useless without somewhere to pay: see NIXAMP_PAY_TO.
@@ -107,6 +116,16 @@ export interface Engine {
      * dropping every listener.
      */
     replace(tracks: Track[], root: string): void;
+    /**
+     * The same tracks, now with their tags.
+     *
+     * Startup lists filenames and begins serving immediately, because an ffprobe
+     * per file over a real library takes minutes; the tags arrive afterwards and
+     * land here. Unlike `replace` this must not disturb anything -- whoever is
+     * listening keeps listening, and the only visible change is that the titles
+     * fill in.
+     */
+    retag(tracks: Track[], root: string): void;
     stop(): void;
 }
 export declare function toRemoteTracks(tracks: Track[]): RemoteTrack[];
@@ -146,6 +165,7 @@ export declare class PlayerEngine implements Engine {
     private push;
     stop(): void;
     replace(tracks: Track[], root: string): void;
+    retag(tracks: Track[], root: string): void;
 }
 /** An engine with no library behind it, for the hosted PWA. */
 export declare class EmptyEngine implements Engine {
@@ -156,6 +176,7 @@ export declare class EmptyEngine implements Engine {
     subscribe(listener: (snapshot: Snapshot) => void): () => void;
     trackPath(): undefined;
     replace(): void;
+    retag(): void;
     stop(): void;
 }
 /**

package/dist/server.js

@@ -66,6 +66,7 @@ export function parseServeArgs(argv) {
         directory: false,
         publish: "ask",
         name: "",
+        publicUrl: process.env["NIXAMP_PUBLIC_URL"] ?? "",
         x402: false,
         owner: "",
         ingest: false,
@@ -117,6 +118,15 @@ export function parseServeArgs(argv) {
         else if (arg === "--no-publish") {
             options.publish = "no";
         }
+        else if (arg === "--public-url") {
+            const given = value().trim();
+            // A hostname on its own is the likely typo, and it fails much later --
+            // as a directory listing nobody can open -- so it is refused here.
+            if (!/^https?:\/\/[^\s/]+/i.test(given)) {
+                throw new Error("nixamp serve: --public-url must be a URL, e.g. https://nixamp.example.com");
+            }
+            options.publicUrl = given.replace(/\/+$/, "");
+        }
         else if (arg === "--name") {
             options.name = value();
         }
@@ -444,6 +454,19 @@ export class PlayerEngine {
         this.state.note = "";
         this.push();
     }
+    retag(tracks, root) {
+        // Dropped rather than applied if the library moved underneath: somebody
+        // re-streamed while the tagging was still running, and these tags describe
+        // something nobody is playing any more.
+        if (root !== this.root || tracks.length !== this.tracks.length)
+            return;
+        if (tracks.some((track, at) => track.path !== this.tracks[at]?.path))
+            return;
+        this.tracks = tracks;
+        // No stop, no index reset: the only thing that changes is what the titles
+        // say, and every remote finds out because a snapshot goes out.
+        this.push();
+    }
 }
 /** An engine with no library behind it, for the hosted PWA. */
 export class EmptyEngine {
@@ -463,6 +486,7 @@ export class EmptyEngine {
         return undefined;
     }
     replace() { }
+    retag() { }
     stop() { }
 }
 const CORS = {
@@ -1804,7 +1828,18 @@ export async function serve(argv, version = "0.1.0") {
     const options = parseServeArgs(argv);
     const root = isRemote(options.root) ? options.root : resolve(options.root);
     const tools = detectTools();
-    const tracks = await loadSource(tools, root);
+    // Names now, tags later.
+    //
+    // Reading tags is an ffprobe per file, which over a real library is minutes,
+    // and every one of them used to happen before this process printed a word or
+    // listened on a port. `nixamp serve ~/music` looked hung, and `nixamp daemon
+    // start` was worse: it waits fifteen seconds for the announce line, killed a
+    // daemon that was working perfectly, and reported a failure whose log was
+    // empty because nothing had been written to it yet.
+    //
+    // So the filenames are enough to start: the server is up and answering in the
+    // time it takes to walk the directory, and the titles fill in behind it.
+    const tracks = await loadSource(tools, root, false);
     const engine = tracks.length > 0
         ? new PlayerEngine(tracks, root, tools)
         : new EmptyEngine(`No audio files under ${root}.`);
@@ -2050,14 +2085,45 @@ export async function serve(argv, version = "0.1.0") {
             return { status: done.status, stdout: done.stdout ?? "" };
         },
     };
+    // The link, not the address. Without the key the address is a 401, so
+    // printing a bare host:port would be printing something that does not work.
+    const addresses = reachableAddresses(options.host, port, options.publicUrl);
+    // Listening on every interface proves the socket is open here and nothing
+    // about the path between here and the phone.
+    const listening = options.host === "0.0.0.0" || options.host === "::";
+    const firewall = listening ? firewallInUse(io) : null;
     if (options.announce) {
-        console.log(JSON.stringify({ nixamp: "listening", host: options.host, port, key, source: root }));
+        // Everything `nixamp daemon start` needs to print what this would have
+        // printed. Without the addresses it could only reconstruct host and port,
+        // which for a server bound to every interface means it printed 127.0.0.1 --
+        // an address that works on exactly the machine you are already sitting at.
+        // The firewall matters for the same reason: the warning was going into a
+        // log file nobody reads instead of to the person who just typed the
+        // command.
+        console.log(JSON.stringify({
+            nixamp: "listening",
+            host: options.host,
+            port,
+            key,
+            source: root,
+            urls: addresses,
+            firewall,
+        }));
+    }
+    // The other half of "names now, tags later". It runs while the banner is
+    // printed and while the publish prompt waits, and it is deliberately not
+    // awaited: nothing downstream needs it, and a library that takes a minute to
+    // read should cost nobody a minute of silence.
+    if (tracks.length > 0 && !isRemote(root)) {
+        void loadSource(tools, root, true)
+            .then((tagged) => engine.retag(tagged, root))
+            .catch(() => {
+            // Filenames are a working player. A failure here is worth nothing but
+            // titles that stay as they are.
+        });
     }
     console.log(`nixamp serve — ${tracks.length} tracks under ${root}`);
     console.log("");
-    // The link, not the address. Without the key the address is a 401, so
-    // printing a bare host:port would be printing something that does not work.
-    const addresses = reachableAddresses(options.host, port);
     const width = Math.max(...addresses.map((a) => a.label.length));
     for (const { label, url } of addresses) {
         console.log(`  ${label.padEnd(width)}  ${shareLink(url, key)}`);
@@ -2114,10 +2180,6 @@ export async function serve(argv, version = "0.1.0") {
     }
     if (web === null)
         console.log("  No built PWA found, so / has nothing to serve: run `bun run web:build`.");
-    // Listening on every interface proves the socket is open here and nothing
-    // about the path between here and the phone.
-    const listening = options.host === "0.0.0.0" || options.host === "::";
-    const firewall = listening ? firewallInUse(io) : null;
     let closePort = null;
     if (firewall !== null) {
         const { open, close } = portCommands(firewall, port);

package/dist/share.d.ts

@@ -31,7 +31,7 @@ export declare function classify(address: string): "private" | "cgnat" | "public
  * somewhere else can open. It is labelled for what it is, because the key in
  * the link is then the only thing between a stranger and the library.
  */
-export declare function reachableAddresses(host: string, port: number): {
+export declare function reachableAddresses(host: string, port: number, publicUrl?: string): {
     label: string;
     url: string;
 }[];

package/dist/share.js

@@ -80,14 +80,19 @@ export function classify(address) {
  * somewhere else can open. It is labelled for what it is, because the key in
  * the link is then the only thing between a stranger and the library.
  */
-export function reachableAddresses(host, port) {
+export function reachableAddresses(host, port, publicUrl = "") {
     const link = (address) => {
         // A bare IPv6 address needs brackets before it is a URL.
         const authority = address.includes(":") ? `[${address}]` : address;
         return `http://${authority}:${port}`;
     };
+    // An address somebody told us about, because it is one this machine cannot
+    // know: a tunnel, a reverse proxy, or a router forwarding a port. It goes
+    // first so that it, and not a guess from an interface, is the address this
+    // stream is published under.
+    const told = publicUrl ? [{ label: "on the internet", url: publicUrl.replace(/\/+$/, "") }] : [];
     if (host !== "0.0.0.0" && host !== "::")
-        return [{ label: "here", url: link(host) }];
+        return [...told, { label: "here", url: link(host) }];
     const LABELS = { private: "on your network", cgnat: "on tailscale", public: "on the internet" };
     const found = [];
     for (const [name, entries] of Object.entries(networkInterfaces())) {
@@ -104,6 +109,7 @@ export function reachableAddresses(host, port) {
     const order = { private: 0, cgnat: 1, public: 2 };
     found.sort((x, y) => order[x.kind] - order[y.kind]);
     return [
+        ...told,
         { label: "here", url: `http://localhost:${port}` },
         ...found.map(({ label, url }) => ({ label, url })),
     ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/daemon.ts

@@ -10,6 +10,7 @@ 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";
+import { type Firewall, portCommands } from "./share.ts";
 
 export interface DaemonState {
   pid: number;
@@ -21,6 +22,17 @@ export interface DaemonState {
   startedAt: number;
   /** Where its output went, for when it died and you want to know why. */
   log: string;
+  /**
+   * The labelled addresses the server itself worked out, share key not applied.
+   *
+   * Recorded rather than recomputed because only the server knows them: a
+   * daemon bound to every interface has no single host to print, and the
+   * public one may be a tunnel it was told about rather than an interface
+   * anybody here can see. Absent on a state file written by an older nixamp.
+   */
+  urls?: { label: string; url: string }[];
+  /** The firewall standing between this port and the rest of the network. */
+  firewall?: string | null;
 }
 
 /** XDG, with the usual fallback. One daemon per user, which is one too few for nobody. */
@@ -82,6 +94,53 @@ export function daemonUrl(state: DaemonState): string {
   return `http://${host.includes(":") ? `[${host}]` : host}:${state.port}`;
 }
 
+/**
+ * What `nixamp daemon start` prints, as lines, so it can be tested without
+ * starting a daemon.
+ *
+ * Every address the server found, not one loopback link: the point of a daemon
+ * is the phone in the other room, and 127.0.0.1 is the single address that
+ * cannot be handed to anybody. The firewall warning comes with it because the
+ * server writes that into a log file nobody reads, not to the person who just
+ * typed the command.
+ */
+export function daemonLines(state: DaemonState): string[] {
+  const link = (url: string): string => (state.key ? `${url}/s/${state.key}` : url);
+  // A state file written by an older nixamp has no list, so host and port
+  // still stand in rather than printing nothing at all.
+  const addresses = state.urls ?? [{ label: "here", url: daemonUrl(state) }];
+  const width = Math.max(...addresses.map((a) => a.label.length), "source".length);
+
+  const lines = [`nixamp daemon running (pid ${state.pid})`];
+  for (const { label, url } of addresses) lines.push(`  ${label.padEnd(width)}  ${link(url)}`);
+  lines.push(`  ${"source".padEnd(width)}  ${state.source}`);
+
+  if (state.firewall) {
+    const { open } = portCommands(state.firewall as Firewall, state.port);
+    lines.push(
+      "",
+      `  ${state.firewall} is running, so nothing else can reach port ${state.port} yet:`,
+      `    sudo ${open.join(" ")}`,
+      "  or `nixamp daemon stop` and start again with --open-port.",
+    );
+  }
+  if (!addresses.some((a) => a.label === "on the internet")) {
+    lines.push(
+      "",
+      "  None of those work from outside this network. If it should:",
+      "    nixamp daemon start ... --public-url https://your-tunnel.example.com",
+    );
+  }
+
+  lines.push(
+    "",
+    "  nixamp attach       the player, in front of it",
+    "  nixamp admin        who is connected",
+    "  nixamp daemon stop  when you are done",
+  );
+  return lines;
+}
+
 /**
  * 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
@@ -142,11 +201,14 @@ async function waitForAnnounce(
       try {
         const parsed = JSON.parse(line) as { nixamp?: string } & Record<string, unknown>;
         if (parsed["nixamp"] === "listening") {
+          const urls = parsed["urls"];
           return {
             host: String(parsed["host"]),
             port: Number(parsed["port"]),
             key: (parsed["key"] as string | null) ?? null,
             source: String(parsed["source"]),
+            ...(Array.isArray(urls) ? { urls: urls as { label: string; url: string }[] } : {}),
+            ...(typeof parsed["firewall"] === "string" ? { firewall: parsed["firewall"] } : {}),
           };
         }
       } catch {

package/src/main.ts

@@ -91,6 +91,9 @@ Options for serve:
       --publish    list it at nixamp.com/directory without asking first
       --no-publish never list it, and do not ask
       --name NAME  what to call it in the directory (default: this hostname)
+      --public-url URL  the address this server is reachable at from outside,
+                   when that is a tunnel or a forwarded port rather than one of
+                   its own interfaces. Also NIXAMP_PUBLIC_URL
       --ingest     accept a live stream in at POST /api/ingest
       --rtmp-in N  also listen for RTMP publishers (OBS, Larix) from port N
       --rtmp-streams N  how many may publish at once (default 3, a port each)
@@ -221,13 +224,7 @@ async function runDaemon(argv: string[]): Promise<number> {
   if (action === "start") {
     try {
       const state = await d.start(rest, entry);
-      console.log(`nixamp daemon running (pid ${state.pid})`);
-      const url = d.daemonUrl(state);
-      console.log(`  ${state.key ? `${url}/s/${state.key}` : url}`);
-      console.log(`  ${state.source}`);
-      console.log("");
-      console.log("  nixamp admin        who is connected");
-      console.log("  nixamp daemon stop  when you are done");
+      for (const line of d.daemonLines(state)) console.log(line);
       return 0;
     } catch (error) {
       console.error((error as Error).message);
@@ -334,7 +331,10 @@ export async function main(): Promise<void> {
   const asked = first ?? ".";
   const target = isRemote(asked) ? asked : resolve(asked);
   const tools = detectTools();
-  const tracks = await loadSource(tools, target);
+  // Names now, tags later: an ffprobe per file over a large library is minutes
+  // of a blank terminal before the player appears. The list is the same list;
+  // only the titles arrive late, and they arrive into a player already running.
+  const tracks = await loadSource(tools, target, false);
   if (tracks.length === 0) {
     console.error(`nixamp: no audio files under ${target}`);
     process.exit(1);
@@ -347,6 +347,21 @@ export async function main(): Promise<void> {
   // closure stays narrowed to null for the checker.
   const handoff: { to: { daemon: DaemonState; url: string } | null } = { to: null };
 
+  // The titles, arriving into a player that is already up. Not awaited, and
+  // applied only if the list is still the one it describes.
+  if (!isRemote(target)) {
+    void loadSource(tools, target, true)
+      .then((tagged) => {
+        if (tagged.length !== state.tracks.length) return;
+        if (tagged.some((track, at) => track.path !== state.tracks[at]?.path)) return;
+        state.tracks = tagged;
+        app.invalidate();
+      })
+      .catch(() => {
+        // Filenames play. Nothing to say about tags that would not read.
+      });
+  }
+
   const analyser = new Analyser(FFT_SIZE, RATE);
   const edges = bandEdges(BAND_COUNT, RATE, FFT_SIZE);
   // Samples accumulate until there are enough for one transform.

package/src/server.ts

@@ -119,6 +119,15 @@ export interface ServeOptions {
   publish: "ask" | "yes" | "no";
   /** What to call it in the list. Defaults to this machine's hostname. */
   name: string;
+  /**
+   * The address this server is reachable at from outside, when that is not one
+   * of its own interfaces: a tunnel, a reverse proxy, a forwarded port.
+   *
+   * Without it a machine behind NAT has nothing to publish -- every address it
+   * can see is a 192.168 one that is no use to anybody else -- so the directory
+   * listing is skipped and the printed links only work inside the house.
+   */
+  publicUrl: string;
   /**
    * Charge for listening once the stream is busy. Off unless asked for, and
    * useless without somewhere to pay: see NIXAMP_PAY_TO.
@@ -168,6 +177,7 @@ export function parseServeArgs(argv: string[]): ServeOptions {
     directory: false,
     publish: "ask",
     name: "",
+    publicUrl: process.env["NIXAMP_PUBLIC_URL"] ?? "",
     x402: false,
     owner: "",
     ingest: false,
@@ -208,6 +218,14 @@ export function parseServeArgs(argv: string[]): ServeOptions {
       options.publish = "yes";
     } else if (arg === "--no-publish") {
       options.publish = "no";
+    } else if (arg === "--public-url") {
+      const given = value().trim();
+      // A hostname on its own is the likely typo, and it fails much later --
+      // as a directory listing nobody can open -- so it is refused here.
+      if (!/^https?:\/\/[^\s/]+/i.test(given)) {
+        throw new Error("nixamp serve: --public-url must be a URL, e.g. https://nixamp.example.com");
+      }
+      options.publicUrl = given.replace(/\/+$/, "");
     } else if (arg === "--name") {
       options.name = value();
     } else if (arg === "--owner") {
@@ -343,6 +361,16 @@ export interface Engine {
    * dropping every listener.
    */
   replace(tracks: Track[], root: string): void;
+  /**
+   * The same tracks, now with their tags.
+   *
+   * Startup lists filenames and begins serving immediately, because an ffprobe
+   * per file over a real library takes minutes; the tags arrive afterwards and
+   * land here. Unlike `replace` this must not disturb anything -- whoever is
+   * listening keeps listening, and the only visible change is that the titles
+   * fill in.
+   */
+  retag(tracks: Track[], root: string): void;
   stop(): void;
 }
 
@@ -542,6 +570,18 @@ export class PlayerEngine implements Engine {
     this.state.note = "";
     this.push();
   }
+
+  retag(tracks: Track[], root: string): void {
+    // Dropped rather than applied if the library moved underneath: somebody
+    // re-streamed while the tagging was still running, and these tags describe
+    // something nobody is playing any more.
+    if (root !== this.root || tracks.length !== this.tracks.length) return;
+    if (tracks.some((track, at) => track.path !== this.tracks[at]?.path)) return;
+    this.tracks = tracks;
+    // No stop, no index reset: the only thing that changes is what the titles
+    // say, and every remote finds out because a snapshot goes out.
+    this.push();
+  }
 }
 
 /** An engine with no library behind it, for the hosted PWA. */
@@ -559,6 +599,7 @@ export class EmptyEngine implements Engine {
     return undefined;
   }
   replace(): void {}
+  retag(): void {}
   stop(): void {}
 }
 
@@ -2062,7 +2103,18 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   const options = parseServeArgs(argv);
   const root = isRemote(options.root) ? options.root : resolve(options.root);
   const tools = detectTools();
-  const tracks = await loadSource(tools, root);
+  // Names now, tags later.
+  //
+  // Reading tags is an ffprobe per file, which over a real library is minutes,
+  // and every one of them used to happen before this process printed a word or
+  // listened on a port. `nixamp serve ~/music` looked hung, and `nixamp daemon
+  // start` was worse: it waits fifteen seconds for the announce line, killed a
+  // daemon that was working perfectly, and reported a failure whose log was
+  // empty because nothing had been written to it yet.
+  //
+  // So the filenames are enough to start: the server is up and answering in the
+  // time it takes to walk the directory, and the titles fill in behind it.
+  const tracks = await loadSource(tools, root, false);
   const engine: Engine = tracks.length > 0
     ? new PlayerEngine(tracks, root, tools)
     : new EmptyEngine(`No audio files under ${root}.`);
@@ -2338,16 +2390,52 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     },
   };
 
+  // The link, not the address. Without the key the address is a 401, so
+  // printing a bare host:port would be printing something that does not work.
+  const addresses = reachableAddresses(options.host, port, options.publicUrl);
+
+  // Listening on every interface proves the socket is open here and nothing
+  // about the path between here and the phone.
+  const listening = options.host === "0.0.0.0" || options.host === "::";
+  const firewall = listening ? firewallInUse(io) : null;
+
   if (options.announce) {
-    console.log(JSON.stringify({ nixamp: "listening", host: options.host, port, key, source: root }));
+    // Everything `nixamp daemon start` needs to print what this would have
+    // printed. Without the addresses it could only reconstruct host and port,
+    // which for a server bound to every interface means it printed 127.0.0.1 --
+    // an address that works on exactly the machine you are already sitting at.
+    // The firewall matters for the same reason: the warning was going into a
+    // log file nobody reads instead of to the person who just typed the
+    // command.
+    console.log(
+      JSON.stringify({
+        nixamp: "listening",
+        host: options.host,
+        port,
+        key,
+        source: root,
+        urls: addresses,
+        firewall,
+      }),
+    );
+  }
+
+  // The other half of "names now, tags later". It runs while the banner is
+  // printed and while the publish prompt waits, and it is deliberately not
+  // awaited: nothing downstream needs it, and a library that takes a minute to
+  // read should cost nobody a minute of silence.
+  if (tracks.length > 0 && !isRemote(root)) {
+    void loadSource(tools, root, true)
+      .then((tagged) => engine.retag(tagged, root))
+      .catch(() => {
+        // Filenames are a working player. A failure here is worth nothing but
+        // titles that stay as they are.
+      });
   }
 
   console.log(`nixamp serve — ${tracks.length} tracks under ${root}`);
   console.log("");
 
-  // The link, not the address. Without the key the address is a 401, so
-  // printing a bare host:port would be printing something that does not work.
-  const addresses = reachableAddresses(options.host, port);
   const width = Math.max(...addresses.map((a) => a.label.length));
   for (const { label, url } of addresses) {
     console.log(`  ${label.padEnd(width)}  ${shareLink(url, key)}`);
@@ -2404,10 +2492,6 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   }
   if (web === null) console.log("  No built PWA found, so / has nothing to serve: run `bun run web:build`.");
 
-  // Listening on every interface proves the socket is open here and nothing
-  // about the path between here and the phone.
-  const listening = options.host === "0.0.0.0" || options.host === "::";
-  const firewall = listening ? firewallInUse(io) : null;
   let closePort: (() => void) | null = null;
 
   if (firewall !== null) {

package/src/share.ts

@@ -93,14 +93,24 @@ export function classify(address: string): "private" | "cgnat" | "public" {
  * somewhere else can open. It is labelled for what it is, because the key in
  * the link is then the only thing between a stranger and the library.
  */
-export function reachableAddresses(host: string, port: number): { label: string; url: string }[] {
+export function reachableAddresses(
+  host: string,
+  port: number,
+  publicUrl = "",
+): { label: string; url: string }[] {
   const link = (address: string): string => {
     // A bare IPv6 address needs brackets before it is a URL.
     const authority = address.includes(":") ? `[${address}]` : address;
     return `http://${authority}:${port}`;
   };
 
-  if (host !== "0.0.0.0" && host !== "::") return [{ label: "here", url: link(host) }];
+  // An address somebody told us about, because it is one this machine cannot
+  // know: a tunnel, a reverse proxy, or a router forwarding a port. It goes
+  // first so that it, and not a guess from an interface, is the address this
+  // stream is published under.
+  const told = publicUrl ? [{ label: "on the internet", url: publicUrl.replace(/\/+$/, "") }] : [];
+
+  if (host !== "0.0.0.0" && host !== "::") return [...told, { label: "here", url: link(host) }];
 
   const LABELS = { private: "on your network", cgnat: "on tailscale", public: "on the internet" } as const;
   const found: { label: string; url: string; kind: keyof typeof LABELS }[] = [];
@@ -116,6 +126,7 @@ export function reachableAddresses(host: string, port: number): { label: string;
   const order = { private: 0, cgnat: 1, public: 2 } as const;
   found.sort((x, y) => order[x.kind] - order[y.kind]);
   return [
+    ...told,
     { label: "here", url: `http://localhost:${port}` },
     ...found.map(({ label, url }) => ({ label, url })),
   ];

package/web/dist/sw.js

@@ -1,5 +1,5 @@
 /* nixamp service worker — generated, do not edit */
-const CACHE = "nixamp-1788934596148";
+const CACHE = "nixamp-1788937268228";
 const PRECACHE = [
   "/",
   "/apple-touch-icon.png",