nixamp 0.7.25 → 0.7.28

package/README.md

@@ -363,6 +363,18 @@ until you restart it.
 An added block can be taken back out from the playlist itself: its heading
 carries an `×`.
 
+## The noise it makes
+
+nixamp plays a jingle when it starts, once per session, the way Winamp did.
+Any mp3 in your home directory with `nixamp` in its name is used instead of the
+ones that ship, and with more than one it picks at random -- a rotation you can
+predict is one you stop hearing. `--no-jingle`, or `NIXAMP_NO_JINGLE=1`, turns
+it off.
+
+On the web it plays on a fresh page if the browser allows it, and otherwise on
+your first click -- browsers spent a decade learning to refuse pages that make
+noise unasked, and this one does not argue with 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/dist/admin.d.ts

@@ -39,6 +39,14 @@ export interface AdminOptions {
         label: string;
         url: string;
     }[];
+    /**
+     * The key that only watches, when this server has one.
+     *
+     * The links built from it are the ones to hand other people. Absent when
+     * pointed at a server by hand, since a listening key is not something you
+     * can work out from a control one.
+     */
+    listenKey?: string | null;
     /** What it is serving, so the admin view says so without being asked. */
     source: string;
 }
@@ -76,6 +84,8 @@ export interface View {
         url: string;
     }[];
     key: string | null;
+    /** The key that only watches, for the links you hand to other people. */
+    listenKey?: string | null;
     source: string;
 }
 export declare function draw(ui: Container, theme: Theme, view: View): void;

package/dist/admin.js

@@ -39,6 +39,7 @@ export function resolveTarget(argv) {
     return {
         url: url_,
         key: key ?? state.key,
+        ...(state.listenKey ? { listenKey: state.listenKey } : {}),
         // A state file written before 0.5.3 has no list; loopback stands in.
         links: state.urls ?? [{ label: "here", url: daemonUrl(state) }],
         source: state.source,
@@ -176,7 +177,7 @@ export async function admin(argv) {
     app.on("exit", () => clearInterval(timer));
     app.render(({ ui, theme }) => draw(ui, theme, {
         url: target.url, report, snapshot, error, typing, restreaming, replacing,
-        links: target.links, key: target.key, source: target.source,
+        links: target.links, key: target.key, listenKey: target.listenKey, source: target.source,
     }));
     await app.start();
     clearInterval(timer);
@@ -229,13 +230,31 @@ export function draw(ui, theme, view) {
     // reach it. The key is on them: without it every address is a 401.
     if (view.links.length > 0) {
         const width = Math.max(...view.links.map((link) => link.label.length));
-        ui.panel({ title: "Share links", size: view.links.length + (view.source ? 3 : 2) }, (p) => {
+        // Both kinds, labelled, because they are not interchangeable and the
+        // operator had only ever been shown the one that drives. Handing that to
+        // somebody who wanted to watch hands them the controls with it, and
+        // there was nothing else to hand them.
+        // Counted rather than guessed: a heading of its own, the links, the second
+        // heading and its links when there is a viewing key, the source, and the
+        // two borders. A panel one line short silently drops the last row.
+        const rows = 1 + view.links.length
+            + (view.listenKey ? 1 + view.links.length : 0)
+            + (view.source ? 1 : 0);
+        ui.panel({ title: "Your links, and the ones to share", size: rows + 2 }, (p) => {
+            p.label("Yours -- these administer this server:");
             for (const link of view.links) {
-                const full = shareLink(link.url, view.key);
-                p.text(`${link.label.padEnd(width)}  ${full}`, {
+                p.text(`${link.label.padEnd(width)}  ${shareLink(link.url, view.key)}`, {
                     fg: link.label === "on the internet" ? theme.accent : theme.foreground,
                 });
             }
+            if (view.listenKey) {
+                p.label("To share -- these watch and listen, and change nothing:");
+                for (const link of view.links) {
+                    p.text(`${link.label.padEnd(width)}  ${shareLink(link.url, view.listenKey, false)}`, {
+                        fg: link.label === "on the internet" ? theme.accent : theme.foreground,
+                    });
+                }
+            }
             if (view.source)
                 p.label(view.source);
         });

package/dist/daemon.d.ts

@@ -4,6 +4,13 @@ export interface DaemonState {
     port: number;
     /** The share key, so `nixamp admin` can talk to it without being told. */
     key: string | null;
+    /**
+     * The key that only views, for handing to somebody who should watch.
+     *
+     * Absent on a state file written by an older nixamp, and absent on a server
+     * running with no key at all.
+     */
+    listenKey?: string | null;
     source: string;
     startedAt: number;
     /** Where its output went, for when it died and you want to know why. */

package/dist/daemon.js

@@ -121,8 +121,11 @@ function spell(ms) {
  * typed the command.
  */
 export function daemonLines(state, uptimeMs) {
-    // The daemon's own key is the one that administers, so it is an /a/ link.
+    // Two links per address: the one that drives this server and the one that
+    // only watches it. Printing just the first left the operator with nothing to
+    // hand anybody -- and handing over the wrong one hands over the controls.
     const link = (url) => shareLink(url, state.key ?? null);
+    const viewLink = (url) => shareLink(url, state.listenKey ?? null, false);
     // 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) }];
@@ -131,6 +134,15 @@ export function daemonLines(state, uptimeMs) {
     for (const { label, url } of addresses)
         lines.push(`  ${label.padEnd(width)}  ${link(url)}`);
     lines.push(`  ${"source".padEnd(width)}  ${state.source}`);
+    // The viewing links, said separately and said as what they are. Somebody who
+    // should be able to watch your library should not be handed the link that
+    // re-streams it, and the operator had nothing else to give them.
+    if (state.listenKey) {
+        lines.push("", "  To share -- these watch and listen, and change nothing:");
+        for (const { label, url } of addresses) {
+            lines.push(`  ${label.padEnd(width)}  ${viewLink(url)}`);
+        }
+    }
     if (uptimeMs !== undefined)
         lines.push(`  ${"up".padEnd(width)}  ${spell(uptimeMs)}`);
     if (state.guessedPublic) {
@@ -227,6 +239,7 @@ async function waitForAnnounce(log, timeoutMs) {
                         host: String(parsed["host"]),
                         port: Number(parsed["port"]),
                         key: parsed["key"] ?? null,
+                        ...(typeof parsed["listenKey"] === "string" ? { listenKey: parsed["listenKey"] } : {}),
                         source: String(parsed["source"]),
                         ...(Array.isArray(urls) ? { urls: urls } : {}),
                         ...(typeof parsed["firewall"] === "string" ? { firewall: parsed["firewall"] } : {}),

package/dist/jingle.d.ts

@@ -0,0 +1,45 @@
+import type { Tools } from "./audio.ts";
+/** Turned off by `--no-jingle` or by setting this in the environment. */
+export declare const OFF = "NIXAMP_NO_JINGLE";
+/**
+ * Every jingle available, yours first, in a stable order.
+ *
+ * The match is deliberately loose -- any mp3 whose name contains "nixamp" --
+ * because the point is that a file you drop in your home directory is picked
+ * up, not that you named it exactly right. `001. NixAmp Whips the D-M-C-As.mp3`
+ * is a name a person actually uses, and an anchored pattern missed it.
+ */
+export declare function findJingles(home?: string, packaged?: string[], read?: (dir: string) => string[]): string[];
+/**
+ * One to play, chosen at random.
+ *
+ * Random rather than in turn: a rotation you can predict is one you stop
+ * hearing, and there is no state worth keeping between runs for this.
+ */
+export declare function findJingle(home?: string, packaged?: string[], read?: (dir: string) => string[], pick?: (upTo: number) => number): string | null;
+/**
+ * Play it, without making anybody wait for it.
+ *
+ * Detached and unwatched: a jingle that delays the player, or that fails
+ * loudly because a codec is missing, is worse than no jingle. Nothing here is
+ * awaited and nothing it does can stop a start.
+ */
+export declare function playJingle(tools: Tools, path?: string | null, 
+/** Injected so a test can see what would be run on a machine with speakers. */
+start?: Spawner, env?: Record<string, string | undefined>): boolean;
+/**
+ * Play it and stop, with no window.
+ *
+ * `-nodisp` because a jingle is not something to open a window for, and
+ * `-autoexit` because a player that lingers after the sound is a process
+ * somebody has to notice and kill.
+ */
+export declare const JINGLE_ARGS: readonly ["-autoexit", "-nodisp", "-loglevel", "quiet"];
+type Spawner = (command: string, args: string[], options: {
+    stdio: "ignore";
+    detached: boolean;
+}) => {
+    on: (event: "error", run: () => void) => unknown;
+    unref?: () => void;
+};
+export {};

package/dist/jingle.js

@@ -0,0 +1,129 @@
+/**
+ * The noise nixamp makes when it wakes up.
+ *
+ * Winamp had one, and it is half of why anybody remembers Winamp. This plays
+ * once when a player starts and once on a fresh page at nixamp.com, and never
+ * again in that session -- a sound you like the first time is a sound you
+ * resent the fourth.
+ *
+ * Yours win: any mp3 in your home directory with "nixamp" in its name, so you
+ * can drop one in without touching anything. Otherwise the ones that ship are
+ * used, so it works on a machine that has never heard of any of this.
+ *
+ * With more than one, it picks at random rather than cycling, because a
+ * rotation you can predict is one you stop hearing.
+ */
+import { spawn } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Turned off by `--no-jingle` or by setting this in the environment. */
+export const OFF = "NIXAMP_NO_JINGLE";
+/**
+ * Every jingle available, yours first, in a stable order.
+ *
+ * The match is deliberately loose -- any mp3 whose name contains "nixamp" --
+ * because the point is that a file you drop in your home directory is picked
+ * up, not that you named it exactly right. `001. NixAmp Whips the D-M-C-As.mp3`
+ * is a name a person actually uses, and an anchored pattern missed it.
+ */
+export function findJingles(home = homedir(), packaged = packagedJingles(), read = safeRead) {
+    // Guarded here rather than only inside the default reader: whether a jingle
+    // can be found is this function's promise to keep, and it should not depend
+    // on which reader it was handed.
+    let names;
+    try {
+        names = read(home);
+    }
+    catch {
+        names = [];
+    }
+    const mine = names
+        .filter((name) => name.toLowerCase().endsWith(".mp3") && name.toLowerCase().includes("nixamp"))
+        .sort()
+        .map((name) => join(home, name));
+    return mine.length > 0 ? mine : packaged;
+}
+/**
+ * One to play, chosen at random.
+ *
+ * Random rather than in turn: a rotation you can predict is one you stop
+ * hearing, and there is no state worth keeping between runs for this.
+ */
+export function findJingle(home = homedir(), packaged = packagedJingles(), read = safeRead, pick = (upTo) => Math.floor(Math.random() * upTo)) {
+    const all = findJingles(home, packaged, read);
+    if (all.length === 0)
+        return null;
+    return all[Math.min(all.length - 1, Math.max(0, pick(all.length)))] ?? null;
+}
+function safeRead(dir) {
+    return readdirSync(dir);
+}
+/**
+ * The ones that ship, read from the list the web build writes.
+ *
+ * A list rather than a name, so adding another jingle is dropping a file in
+ * and rebuilding rather than editing this.
+ */
+function packagedJingles() {
+    try {
+        // dist/jingle.js -> the package root -> web/dist, which is what `files`
+        // in package.json actually ships.
+        const dir = fileURLToPath(new URL("../web/dist/jingles", import.meta.url));
+        const listed = JSON.parse(readFileSync(join(dir, "index.json"), "utf8"));
+        if (!Array.isArray(listed))
+            return [];
+        return listed
+            .filter((name) => typeof name === "string")
+            .map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Play it, without making anybody wait for it.
+ *
+ * Detached and unwatched: a jingle that delays the player, or that fails
+ * loudly because a codec is missing, is worse than no jingle. Nothing here is
+ * awaited and nothing it does can stop a start.
+ */
+export function playJingle(tools, path = findJingle(), 
+/** Injected so a test can see what would be run on a machine with speakers. */
+start = spawn, env = process.env) {
+    if (path === null)
+        return false;
+    if (env[OFF])
+        return false;
+    const play = tools.play;
+    if (play === null)
+        return false;
+    const [command, ...rest] = play;
+    if (command === undefined)
+        return false;
+    try {
+        const child = start(command, [...rest, ...JINGLE_ARGS, path], {
+            stdio: "ignore",
+            detached: false,
+        });
+        child.on("error", () => {
+            // No player, a file it will not open, or a machine with no sound card at
+            // all -- which is most servers. Silence is the fallback, and it is not
+            // worth a line of output on every start.
+        });
+        child.unref?.();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Play it and stop, with no window.
+ *
+ * `-nodisp` because a jingle is not something to open a window for, and
+ * `-autoexit` because a player that lingers after the sound is a process
+ * somebody has to notice and kill.
+ */
+export const JINGLE_ARGS = ["-autoexit", "-nodisp", "-loglevel", "quiet"];

package/dist/main.js

@@ -16,6 +16,7 @@ import { displayName, loadSource, loadTagged } from "./playlist.js";
 import { isRemote } from "./sources.js";
 import { DEFAULT_PORT } from "./server.js";
 import { shareLink } from "./share.js";
+import { playJingle } from "./jingle.js";
 const FFT_SIZE = 2048;
 export const BAND_COUNT = 24;
 export function createState(tracks, root, silent) {
@@ -60,6 +61,10 @@ const HELP = `nixamp — it really whips the terminal's ass.
 A source is a directory, a file, an .m3u, an .m3u8, a .pls, or a URL to any
 of those.
 
+It plays a jingle when it starts, picked at random. Any mp3 in your home
+directory with nixamp in the name is yours and wins; otherwise the ones that
+ship are used. --no-jingle, or NIXAMP_NO_JINGLE=1, for silence.
+
 Options for serve:
   -p, --port N     port to listen on (default ${DEFAULT_PORT})
   -h, --host HOST  address to bind (default 0.0.0.0, every interface)
@@ -344,6 +349,11 @@ export async function main() {
     const asked = first ?? ".";
     const target = isRemote(asked) ? asked : resolve(asked);
     const tools = detectTools();
+    // The noise it makes when it wakes up. Started before the library is walked
+    // so it plays over the wait rather than after it, and never awaited: a
+    // jingle that delays the player is worse than no jingle.
+    if (!rest.includes("--no-jingle"))
+        playJingle(tools);
     // 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.

package/dist/server.d.ts

@@ -31,6 +31,8 @@ export interface ServeOptions {
     key: boolean;
     /** Mint a new share key rather than reusing the one this port had. */
     newKey: boolean;
+    /** Start without the noise it makes when it wakes up. */
+    noJingle: boolean;
     /**
      * Ask the local firewall to let the port through, and put it back on the way
      * out. Off by default because it changes the machine, not just this process.

package/dist/server.js

@@ -29,6 +29,7 @@ import { DeviceGrants } from "./device.js";
 import { BAD_KEY_LIMIT, callerOf, Guard, SIGN_IN_LIMIT } from "./guard.js";
 import { deviceDonePage, devicePage, exchangeCode, providersFrom, signInFailedPage, SignIn, } from "./oauth.js";
 import { needsAdmin, Owner } from "./owner.js";
+import { playJingle } from "./jingle.js";
 import { stateDir } from "./daemon.js";
 import { readSession } from "./session.js";
 import { Directory, ENDED_TTL_MS, parseAnnouncement } from "./directory.js";
@@ -70,6 +71,7 @@ export function parseServeArgs(argv) {
         media: true,
         key: true,
         newKey: false,
+        noJingle: false,
         openPort: false,
         announce: false,
         directory: false,
@@ -162,6 +164,9 @@ export function parseServeArgs(argv) {
         else if (arg === "--new-key") {
             options.newKey = true;
         }
+        else if (arg === "--no-jingle") {
+            options.noJingle = true;
+        }
         else if (arg === "--ingest") {
             options.ingest = true;
         }
@@ -2607,6 +2612,10 @@ export async function serve(argv, version = "0.1.0") {
     // Empty on purpose. The walk happens below, once the port is open: it is
     // the slowest part of starting and nothing about it needs to happen first.
     const engine = new PlayerEngine([], root, tools);
+    // A serving machine with speakers is still a player. A headless one has no
+    // ffplay, and playJingle answers that by doing nothing.
+    if (!options.noJingle)
+        playJingle(tools);
     const web = options.web !== null ? resolve(options.web) : defaultWebDir();
     // The same keys this port used last time, so a link somebody was given
     // still works after a restart -- and a server is restarted to pick up a new
@@ -2962,6 +2971,10 @@ export async function serve(argv, version = "0.1.0") {
             host: options.host,
             port,
             key,
+            // The other half of the pair. Without it `nixamp admin` can only draw
+            // the links that administer, so the operator has nothing to hand
+            // somebody who should be able to watch and not to drive.
+            listenKey,
             source: root,
             urls: addresses,
             firewall,

package/package.json

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

package/src/admin.ts

@@ -38,6 +38,14 @@ export interface AdminOptions {
    * anybody. These are the ones worth reading off the screen.
    */
   links: { label: string; url: string }[];
+  /**
+   * The key that only watches, when this server has one.
+   *
+   * The links built from it are the ones to hand other people. Absent when
+   * pointed at a server by hand, since a listening key is not something you
+   * can work out from a control one.
+   */
+  listenKey?: string | null;
   /** What it is serving, so the admin view says so without being asked. */
   source: string;
 }
@@ -76,6 +84,7 @@ export function resolveTarget(argv: string[]): AdminOptions {
   return {
     url: url_,
     key: key ?? state.key,
+    ...(state.listenKey ? { listenKey: state.listenKey } : {}),
     // A state file written before 0.5.3 has no list; loopback stands in.
     links: state.urls ?? [{ label: "here", url: daemonUrl(state) }],
     source: state.source,
@@ -198,7 +207,7 @@ export async function admin(argv: string[]): Promise<void> {
   app.on("exit", () => clearInterval(timer));
   app.render(({ ui, theme }) => draw(ui, theme, {
     url: target.url, report, snapshot, error, typing, restreaming, replacing,
-    links: target.links, key: target.key, source: target.source,
+    links: target.links, key: target.key, listenKey: target.listenKey, source: target.source,
   }));
 
   await app.start();
@@ -242,6 +251,8 @@ export interface View {
   /** Labelled addresses, and the key that makes them work. */
   links: { label: string; url: string }[];
   key: string | null;
+  /** The key that only watches, for the links you hand to other people. */
+  listenKey?: string | null;
   source: string;
 }
 
@@ -276,13 +287,32 @@ export function draw(ui: Container, theme: Theme, view: View): void {
   // reach it. The key is on them: without it every address is a 401.
   if (view.links.length > 0) {
     const width = Math.max(...view.links.map((link) => link.label.length));
-    ui.panel({ title: "Share links", size: view.links.length + (view.source ? 3 : 2) }, (p) => {
+    // Both kinds, labelled, because they are not interchangeable and the
+    // operator had only ever been shown the one that drives. Handing that to
+    // somebody who wanted to watch hands them the controls with it, and
+    // there was nothing else to hand them.
+    // Counted rather than guessed: a heading of its own, the links, the second
+    // heading and its links when there is a viewing key, the source, and the
+    // two borders. A panel one line short silently drops the last row.
+    const rows =
+      1 + view.links.length
+      + (view.listenKey ? 1 + view.links.length : 0)
+      + (view.source ? 1 : 0);
+    ui.panel({ title: "Your links, and the ones to share", size: rows + 2 }, (p) => {
+      p.label("Yours -- these administer this server:");
       for (const link of view.links) {
-        const full = shareLink(link.url, view.key);
-        p.text(`${link.label.padEnd(width)}  ${full}`, {
+        p.text(`${link.label.padEnd(width)}  ${shareLink(link.url, view.key)}`, {
           fg: link.label === "on the internet" ? theme.accent : theme.foreground,
         });
       }
+      if (view.listenKey) {
+        p.label("To share -- these watch and listen, and change nothing:");
+        for (const link of view.links) {
+          p.text(`${link.label.padEnd(width)}  ${shareLink(link.url, view.listenKey, false)}`, {
+            fg: link.label === "on the internet" ? theme.accent : theme.foreground,
+          });
+        }
+      }
       if (view.source) p.label(view.source);
     });
   }

package/src/daemon.ts

@@ -18,6 +18,13 @@ export interface DaemonState {
   port: number;
   /** The share key, so `nixamp admin` can talk to it without being told. */
   key: string | null;
+  /**
+   * The key that only views, for handing to somebody who should watch.
+   *
+   * Absent on a state file written by an older nixamp, and absent on a server
+   * running with no key at all.
+   */
+  listenKey?: string | null;
   source: string;
   startedAt: number;
   /** Where its output went, for when it died and you want to know why. */
@@ -164,8 +171,11 @@ function spell(ms: number): string {
  * typed the command.
  */
 export function daemonLines(state: DaemonState, uptimeMs?: number): string[] {
-  // The daemon's own key is the one that administers, so it is an /a/ link.
+  // Two links per address: the one that drives this server and the one that
+  // only watches it. Printing just the first left the operator with nothing to
+  // hand anybody -- and handing over the wrong one hands over the controls.
   const link = (url: string): string => shareLink(url, state.key ?? null);
+  const viewLink = (url: string): string => shareLink(url, state.listenKey ?? null, false);
   // 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) }];
@@ -174,6 +184,16 @@ export function daemonLines(state: DaemonState, uptimeMs?: number): string[] {
   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}`);
+
+  // The viewing links, said separately and said as what they are. Somebody who
+  // should be able to watch your library should not be handed the link that
+  // re-streams it, and the operator had nothing else to give them.
+  if (state.listenKey) {
+    lines.push("", "  To share -- these watch and listen, and change nothing:");
+    for (const { label, url } of addresses) {
+      lines.push(`  ${label.padEnd(width)}  ${viewLink(url)}`);
+    }
+  }
   if (uptimeMs !== undefined) lines.push(`  ${"up".padEnd(width)}  ${spell(uptimeMs)}`);
 
   if (state.guessedPublic) {
@@ -300,6 +320,7 @@ async function waitForAnnounce(
             host: String(parsed["host"]),
             port: Number(parsed["port"]),
             key: (parsed["key"] as string | null) ?? null,
+            ...(typeof parsed["listenKey"] === "string" ? { listenKey: parsed["listenKey"] } : {}),
             source: String(parsed["source"]),
             ...(Array.isArray(urls) ? { urls: urls as { label: string; url: string }[] } : {}),
             ...(typeof parsed["firewall"] === "string" ? { firewall: parsed["firewall"] } : {}),