nixamp 0.1.0 → 0.2.0

package/dist/daemon.js

@@ -0,0 +1,170 @@
+/**
+ * Daemon mode.
+ *
+ * `nixamp serve` holds a terminal. A server you leave running should not, and
+ * you should be able to walk away and come back to it, which means something on
+ * disk has to remember where it is and what key it minted. That file is the
+ * whole of the daemon: a pid to signal and enough to reconnect.
+ */
+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";
+/** 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");
+    return join(base, "nixamp");
+}
+export function statePath() {
+    return join(stateDir(), "daemon.json");
+}
+export function logPath() {
+    return join(stateDir(), "daemon.log");
+}
+export function readState() {
+    try {
+        return JSON.parse(readFileSync(statePath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(state) {
+    mkdirSync(dirname(statePath()), { recursive: true });
+    writeFileSync(statePath(), `${JSON.stringify(state, null, 2)}\n`);
+}
+export function clearState() {
+    rmSync(statePath(), { force: true });
+}
+/**
+ * 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 function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means it exists and belongs to someone else, which is still alive.
+        return error.code === "EPERM";
+    }
+}
+/** The daemon as far as anyone asking is concerned. */
+export function status() {
+    const state = readState();
+    if (state === null)
+        return { running: false, state: null };
+    return { running: alive(state.pid), state };
+}
+/** The URL an admin client should talk to. */
+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}`;
+}
+/**
+ * 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 async function start(argv, entry) {
+    const existing = status();
+    if (existing.running && existing.state) {
+        throw new Error(`nixamp: a daemon is already running (pid ${existing.state.pid}). Stop it first.`);
+    }
+    mkdirSync(stateDir(), { recursive: true });
+    const log = logPath();
+    const out = openSync(log, "a");
+    const child = spawn(process.execPath, [entry, "serve", ...argv, "--announce"], {
+        detached: true,
+        stdio: ["ignore", out, out],
+        env: { ...process.env, NIXAMP_DAEMON: "1" },
+    });
+    child.unref();
+    if (child.pid === undefined)
+        throw new Error("nixamp: could not start the daemon");
+    // The server prints one JSON line when it is listening, because guessing how
+    // long a start takes is how a flaky `daemon start` is written.
+    const announced = await waitForAnnounce(log, 15_000);
+    if (announced === null) {
+        try {
+            process.kill(child.pid, "SIGTERM");
+        }
+        catch {
+            // Already gone, which is the more likely reason we are here.
+        }
+        throw new Error(`nixamp: the daemon did not start. See ${log}`);
+    }
+    const state = { ...announced, pid: child.pid, startedAt: Date.now(), log };
+    writeState(state);
+    return state;
+}
+/** Poll the log for the announce line. */
+async function waitForAnnounce(log, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const from = existsSync(log) ? readFileSync(log, "utf8").length : 0;
+    while (Date.now() < deadline) {
+        await new Promise((done) => setTimeout(done, 100));
+        let text;
+        try {
+            text = readFileSync(log, "utf8").slice(from);
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split("\n")) {
+            if (!line.startsWith("{"))
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed["nixamp"] === "listening") {
+                    return {
+                        host: String(parsed["host"]),
+                        port: Number(parsed["port"]),
+                        key: parsed["key"] ?? null,
+                        source: String(parsed["source"]),
+                    };
+                }
+            }
+            catch {
+                // A partial line: it will be complete on the next pass.
+            }
+        }
+    }
+    return null;
+}
+/** Stop it, and wait for it to actually be gone. */
+export async function stop(timeoutMs = 5000) {
+    const { running, state } = status();
+    if (!state)
+        return false;
+    if (!running) {
+        clearState();
+        return false;
+    }
+    try {
+        process.kill(state.pid, "SIGTERM");
+    }
+    catch {
+        clearState();
+        return false;
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!alive(state.pid)) {
+            clearState();
+            return true;
+        }
+        await new Promise((done) => setTimeout(done, 100));
+    }
+    // It ignored SIGTERM. ffmpeg children make that more likely than it sounds.
+    try {
+        process.kill(state.pid, "SIGKILL");
+    }
+    catch {
+        // Gone between the check and the signal.
+    }
+    clearState();
+    return true;
+}

package/dist/main.js

@@ -7,11 +7,13 @@
  * ffmpeg decodes; we read every sample on its way to the speakers and draw it.
  */
 import { createApp, themes } from "@profullstack/hqtui";
+import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
 import { detectTools, formatTime, peaks, RATE, Stream, toMono, } from "./audio.js";
 import { Analyser, bandEdges, bands, decay } from "./fft.js";
 import { version } from "./meta.js";
-import { displayName, loadPlaylist } from "./playlist.js";
+import { displayName, loadSource } from "./playlist.js";
+import { isRemote } from "./sources.js";
 import { DEFAULT_PORT } from "./server.js";
 const FFT_SIZE = 2048;
 export const BAND_COUNT = 24;
@@ -41,20 +43,82 @@ export function barGlyph(value) {
 }
 const HELP = `nixamp — it really whips the terminal's ass.
 
-  nixamp [path]                  play a directory or a file in the terminal
-  nixamp serve [path] [options]  play here, and hand out a browser remote
+  nixamp [source]                play it in the terminal
+  nixamp serve [source] [options]  play here, and hand out a browser remote
+  nixamp daemon start|stop|status  serve in the background, and let go of it
+  nixamp admin [--url U] [--key K] who is connected, and re-stream to them
   nixamp update [version]        re-run the installer, keeping your choices
   nixamp uninstall [--yes]       remove everything the installer created
 
+A source is a directory, a file, an .m3u, an .m3u8, a .pls, or a URL to any
+of those.
+
 Options for serve:
   -p, --port N     port to listen on (default ${DEFAULT_PORT})
-  -h, --host HOST  address to bind (default 127.0.0.1; 0.0.0.0 for the LAN)
+  -h, --host HOST  address to bind (default 0.0.0.0, every interface)
       --web DIR    directory of built PWA files to serve at /
       --no-media   do not stream the library's bytes to remotes
+      --no-key     serve to anyone who can reach the port, with no share link
+      --open-port  let the port through the local firewall, and close it on exit
 
   -v, --version    print the version
       --help       print this
 `;
+/**
+ * `nixamp daemon <start|stop|status>`.
+ *
+ * The daemon is `nixamp serve` with nobody holding its terminal, so this is
+ * mostly bookkeeping: start it detached, remember where it went, and be able
+ * to answer whether it is still there.
+ */
+async function runDaemon(argv) {
+    const d = await import("./daemon.js");
+    const [action = "status", ...rest] = argv;
+    const entry = fileURLToPath(new URL("./main.js", import.meta.url));
+    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");
+            return 0;
+        }
+        catch (error) {
+            console.error(error.message);
+            return 1;
+        }
+    }
+    if (action === "stop") {
+        const stopped = await d.stop();
+        console.log(stopped ? "nixamp daemon stopped" : "nixamp: no daemon was running");
+        return 0;
+    }
+    if (action === "status") {
+        const { running, state } = d.status();
+        if (!state) {
+            console.log("nixamp: no daemon. Start one with `nixamp daemon start`.");
+            return 1;
+        }
+        // A pid file outlives its process often enough that saying "running"
+        // without checking is how you report a daemon that died on Tuesday.
+        if (!running) {
+            console.log(`nixamp: the daemon (pid ${state.pid}) is gone. See ${state.log}`);
+            return 1;
+        }
+        const url = d.daemonUrl(state);
+        console.log(`nixamp daemon running (pid ${state.pid})`);
+        console.log(`  ${state.key ? `${url}/s/${state.key}` : url}`);
+        console.log(`  ${state.source}`);
+        console.log(`  up ${Math.round((Date.now() - state.startedAt) / 1000)}s`);
+        return 0;
+    }
+    console.error(`nixamp daemon: unknown action ${action}. Try start, stop or status.`);
+    return 64;
+}
 /**
  * The whole CLI, as a function. `bin/nixamp.mjs` imports and calls it: relying
  * on `import.meta.main` there would leave the installed binary doing nothing,
@@ -67,6 +131,15 @@ export async function main() {
         await serve(rest, version());
         return;
     }
+    if (first === "daemon") {
+        process.exitCode = await runDaemon(rest);
+        return;
+    }
+    if (first === "admin") {
+        const { admin } = await import("./admin.js");
+        await admin(rest);
+        return;
+    }
     if (first === "update" || first === "uninstall") {
         const manage = await import("./manage.js");
         process.exitCode = first === "update" ? manage.update(rest) : manage.uninstall(rest);
@@ -80,9 +153,12 @@ export async function main() {
         console.log(HELP);
         return;
     }
-    const target = resolve(first ?? ".");
+    // resolve() would turn https://host/x into /cwd/https:/host/x, so a URL is
+    // left exactly as it was typed.
+    const asked = first ?? ".";
+    const target = isRemote(asked) ? asked : resolve(asked);
     const tools = detectTools();
-    const tracks = loadPlaylist(tools, target);
+    const tracks = await loadSource(tools, target);
     if (tracks.length === 0) {
         console.error(`nixamp: no audio files under ${target}`);
         process.exit(1);

package/dist/manage.js

@@ -10,6 +10,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 const SITE = "https://nixamp.com";
+/** Windows has its own installer, its own shim and its own removal script. */
+const windows = process.platform === "win32";
 /**
  * Where the installer put things. `NIXAMP_HOME` is exported by the shim it
  * wrote, which is the only thing that knows for certain; the walk up from this
@@ -53,7 +55,9 @@ function notInstalled(what) {
     console.error("");
     console.error("  Installed with npm or bun:  npm uninstall -g nixamp");
     console.error("  Running from a checkout:    delete the checkout");
-    console.error(`  Wanted the installed one:   curl -fsSL ${SITE}/install.sh | sh`);
+    console.error(windows
+        ? `  Wanted the installed one:   irm ${SITE}/install.ps1 | iex`
+        : `  Wanted the installed one:   curl -fsSL ${SITE}/install.sh | sh`);
     return 69;
 }
 /**
@@ -66,12 +70,24 @@ export function update(argv) {
     const manifest = root ? readManifest(root) : null;
     if (!root || !manifest)
         return notInstalled("update");
-    const installer = manifest.installer || `${SITE}/install.sh`;
-    const args = ["-s", "--", manifest.desktop ? "--desktop" : "--cli-only", "--prefix", manifest.prefix];
+    const installer = manifest.installer || `${SITE}/${windows ? "install.ps1" : "install.sh"}`;
     const wanted = argv.find((a) => !a.startsWith("-"));
+    console.log(`nixamp ${manifest.version} is installed. Fetching the installer...`);
+    if (windows) {
+        // PowerShell fetches and runs it in one expression, which is also the
+        // documented install line, so an update takes a fresh install's path.
+        const flags = [manifest.desktop ? "" : "-CliOnly", "-Prefix", quote(manifest.prefix)];
+        if (wanted)
+            flags.push("-Version", quote(wanted));
+        const expression = `& ([scriptblock]::Create((irm ${installer}))) ${flags.filter(Boolean).join(" ")}`;
+        const run = spawnSync("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", expression], {
+            stdio: "inherit",
+        });
+        return run.status ?? 1;
+    }
+    const args = ["-s", "--", manifest.desktop ? "--desktop" : "--cli-only", "--prefix", manifest.prefix];
     if (wanted)
         args.push("--version", wanted);
-    console.log(`nixamp ${manifest.version} is installed. Fetching the installer...`);
     const fetcher = which("curl") ? ["curl", "-fsSL", installer] : which("wget") ? ["wget", "-qO-", installer] : null;
     if (!fetcher) {
         console.error("nixamp: curl or wget is required to update.");
@@ -103,15 +119,21 @@ export function uninstall(argv) {
         console.log("Your music is not touched. Run `nixamp uninstall --yes` to go ahead.");
         return 0;
     }
-    const script = join(root, "uninstall.sh");
+    const script = join(root, windows ? "uninstall.ps1" : "uninstall.sh");
     if (!existsSync(script)) {
         console.error(`nixamp: ${script} is missing, so removal cannot be exact.`);
         console.error(`  The manifest lists: ${manifest.paths.join(", ")}`);
         return 1;
     }
-    const run = spawnSync("sh", [script], { stdio: "inherit" });
+    const run = windows
+        ? spawnSync("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script], { stdio: "inherit" })
+        : spawnSync("sh", [script], { stdio: "inherit" });
     return run.status ?? 1;
 }
+/** A PowerShell single-quoted string: the only escape inside one is a doubled quote. */
+function quote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
 function which(command) {
     return spawnSync("sh", ["-c", `command -v ${command}`], { stdio: "ignore" }).status === 0;
 }

package/dist/playlist.d.ts

@@ -1,8 +1,24 @@
 import { type Tools, type Track } from "./audio.ts";
+import { type Entry } from "./sources.ts";
 export declare const AUDIO_EXTENSIONS: Set<string>;
 export declare function isAudio(path: string): boolean;
 /** Every audio file under `root`, depth first. A single file is a playlist of one. */
 export declare function findAudio(root: string): string[];
+/**
+ * Read a playlist, from disk or over the network. An HLS playlist is not a list
+ * of tracks but one stream in segments, so it comes back as a single entry and
+ * ffmpeg is left to do what it is good at.
+ */
+export declare function readPlaylist(source: string): Promise<Entry[]>;
+/**
+ * Everything `nixamp <thing>` can be handed: a directory, a file, a playlist,
+ * or a URL to any of those.
+ *
+ * Reading tags means an ffprobe per file, which is slow for a large library and
+ * slower still over the network, so it is only done for local files the caller
+ * asked about.
+ */
+export declare function loadSource(tools: Tools, source: string, probeTags?: boolean): Promise<Track[]>;
 /**
  * Reading tags means an ffprobe per file, which is slow for a large library, so
  * the caller decides when to pay for it. Untagged entries still play.

package/dist/playlist.js

@@ -1,7 +1,8 @@
-/** The playlist: audio files found on disk, in a stable order. */
-import { readdirSync, statSync } from "node:fs";
+/** The playlist: audio found on disk or named by a playlist, in a stable order. */
+import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { probe } from "./audio.js";
+import { isHls, isPlaylistFile, isRemote, nameOf, parseM3u, parsePls, } from "./sources.js";
 export const AUDIO_EXTENSIONS = new Set([
     ".mp3", ".flac", ".ogg", ".oga", ".opus", ".m4a", ".aac",
     ".wav", ".wma", ".aiff", ".aif", ".alac", ".mp4", ".webm",
@@ -50,6 +51,60 @@ export function findAudio(root) {
     walk(root);
     return out;
 }
+/** An entry that was never probed: playable, just not described. */
+function bare(entry) {
+    return { path: entry.source, title: entry.title, artist: "", album: "", duration: entry.duration };
+}
+/**
+ * Read a playlist, from disk or over the network. An HLS playlist is not a list
+ * of tracks but one stream in segments, so it comes back as a single entry and
+ * ffmpeg is left to do what it is good at.
+ */
+export async function readPlaylist(source) {
+    let text;
+    if (isRemote(source)) {
+        const response = await fetch(source, { redirect: "follow" });
+        if (!response.ok)
+            throw new Error(`nixamp: ${source} answered ${response.status}`);
+        text = await response.text();
+    }
+    else {
+        text = readFileSync(source, "utf8");
+    }
+    if (isHls(text))
+        return [{ source, title: nameOf(source), duration: 0 }];
+    const entries = /\.pls$/i.test(source) ? parsePls(text, source) : parseM3u(text, source);
+    return entries;
+}
+/**
+ * Everything `nixamp <thing>` can be handed: a directory, a file, a playlist,
+ * or a URL to any of those.
+ *
+ * Reading tags means an ffprobe per file, which is slow for a large library and
+ * slower still over the network, so it is only done for local files the caller
+ * asked about.
+ */
+export async function loadSource(tools, source, probeTags = true) {
+    if (isPlaylistFile(source)) {
+        let entries;
+        try {
+            entries = await readPlaylist(source);
+        }
+        catch (error) {
+            // The playlist is the whole argument, so failing to read it is fatal --
+            // but it is fatal with a sentence, not a stack.
+            throw new Error(`nixamp: could not read ${source}: ${error.message.replace(/^nixamp: /, "")}`);
+        }
+        return entries.map((entry) => probeTags && !isRemote(entry.source) && entry.duration === 0
+            ? { ...probe(tools, entry.source), title: entry.title || probe(tools, entry.source).title }
+            : bare(entry));
+    }
+    // A bare URL is one remote thing to play. Whether it is a song or a live
+    // stream is ffmpeg's problem, and it is good at it.
+    if (isRemote(source))
+        return [bare({ source, title: nameOf(source), duration: 0 })];
+    return loadPlaylist(tools, source, probeTags);
+}
 /**
  * Reading tags means an ffprobe per file, which is slow for a large library, so
  * the caller decides when to pay for it. Untagged entries still play.

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { Connections } from "./connections.ts";
 import { type Tools, type Track } from "./audio.ts";
 import { type Command, type RemoteTrack, type Snapshot } from "./protocol.ts";
 export declare const SERVE_BAND_COUNT = 24;
@@ -11,6 +12,22 @@ export interface ServeOptions {
     web: string | null;
     /** Stream the library's bytes to remotes. Off keeps the audio on this box. */
     media: boolean;
+    /**
+     * Require the key from the share link. Off serves to anyone who can reach the
+     * port, which is what the public deployment wants and no private one does.
+     */
+    key: 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.
+     */
+    openPort: boolean;
+    /**
+     * Print one JSON line once listening. `nixamp daemon start` reads it rather
+     * than sleeping and hoping, so a daemon that failed to bind is reported as
+     * failed instead of started.
+     */
+    announce: boolean;
 }
 /**
  * Flags are parsed by hand: three of them do not justify a dependency, and the
@@ -40,6 +57,12 @@ export interface Engine {
     subscribe(listener: (snapshot: Snapshot) => void): () => void;
     /** Absolute path of a track, or undefined when the index is not one. */
     trackPath(index: number): string | undefined;
+    /**
+     * Play something else instead. Re-streaming is the whole reason the admin
+     * view exists: point a running server at a URL without restarting it and
+     * dropping every listener.
+     */
+    replace(tracks: Track[], root: string): void;
     stop(): void;
 }
 export declare function toRemoteTracks(tracks: Track[]): RemoteTrack[];
@@ -49,8 +72,8 @@ export declare function toRemoteTracks(tracks: Track[]): RemoteTrack[];
  * its way past so a remote can draw the same spectrum the TUI would.
  */
 export declare class PlayerEngine implements Engine {
-    private readonly tracks;
-    private readonly root;
+    private tracks;
+    private root;
     /** Frames a second pushed to remotes. */
     private readonly fps;
     private readonly listeners;
@@ -78,6 +101,7 @@ export declare class PlayerEngine implements Engine {
     subscribe(listener: (snapshot: Snapshot) => void): () => void;
     private push;
     stop(): void;
+    replace(tracks: Track[], root: string): void;
 }
 /** An engine with no library behind it, for the hosted PWA. */
 export declare class EmptyEngine implements Engine {
@@ -87,12 +111,24 @@ export declare class EmptyEngine implements Engine {
     command(): void;
     subscribe(listener: (snapshot: Snapshot) => void): () => void;
     trackPath(): undefined;
+    replace(): void;
     stop(): void;
 }
 export interface HandlerOptions {
     web: string | null;
     media: boolean;
     version: string;
+    /** The key from the share link, or null to serve to anyone who can connect. */
+    key?: string | null;
+    /** How to run ffmpeg, for the sources a browser cannot play by itself. */
+    ffmpeg?: string[];
+    /** Who is listening, for the admin view. */
+    connections?: Connections;
+    /**
+     * How to turn a source into tracks, for re-streaming. Injected rather than
+     * imported so the handler stays a plain function of a request.
+     */
+    load: (source: string) => Promise<Track[]>;
 }
 /**
  * The whole HTTP surface, as a plain function of a request — so a test can
@@ -100,6 +136,4 @@ export interface HandlerOptions {
  */
 export declare function createHandler(engine: Engine, options: HandlerOptions): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
 export declare function createServer(engine: Engine, options: HandlerOptions): Server;
-/** Where a remote on another device should point its browser. */
-export declare function addressesFor(host: string, port: number): string[];
 export declare function serve(argv: string[], version?: string): Promise<void>;