nixamp 0.5.1 → 0.5.2

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/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)
@@ -300,7 +303,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 +317,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}.`);
@@ -2053,11 +2088,23 @@ export async function serve(argv, version = "0.1.0") {
     if (options.announce) {
         console.log(JSON.stringify({ nixamp: "listening", host: options.host, port, key, source: root }));
     }
+    // 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 addresses = reachableAddresses(options.host, port, options.publicUrl);
     const width = Math.max(...addresses.map((a) => a.label.length));
     for (const { label, url } of addresses) {
         console.log(`  ${label.padEnd(width)}  ${shareLink(url, key)}`);

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.2",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

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)
@@ -334,7 +337,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 +353,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}.`);
@@ -2342,12 +2394,25 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     console.log(JSON.stringify({ nixamp: "listening", host: options.host, port, key, source: root }));
   }
 
+  // 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 addresses = reachableAddresses(options.host, port, options.publicUrl);
   const width = Math.max(...addresses.map((a) => a.label.length));
   for (const { label, url } of addresses) {
     console.log(`  ${label.padEnd(width)}  ${shareLink(url, key)}`);

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-1788936569431";
 const PRECACHE = [
   "/",
   "/apple-touch-icon.png",