nixamp 0.1.0

package/dist/main.d.ts

@@ -0,0 +1,47 @@
+/**
+ * nixamp — it really whips the terminal's ass.
+ *
+ *   bunx nixamp ~/Music
+ *   bunx nixamp track.flac
+ *
+ * ffmpeg decodes; we read every sample on its way to the speakers and draw it.
+ */
+import { type BrailleCanvas, type Container, type Theme } from "@profullstack/hqtui";
+import { type Track } from "./audio.ts";
+export declare const BAND_COUNT = 24;
+export interface State {
+    tracks: Track[];
+    index: number;
+    offset: number;
+    playing: boolean;
+    position: number;
+    bars: number[];
+    peakHold: number[];
+    levels: [number, number];
+    note: string;
+    silent: boolean;
+    root: string;
+}
+export declare function createState(tracks: Track[], root: string, silent: boolean): State;
+export declare function current(state: State): Track | undefined;
+export declare function barGlyph(value: number): string;
+/**
+ * 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,
+ * because the flag is false in a module that was imported rather than run.
+ */
+export declare function main(): Promise<void>;
+/**
+ * The bars, on a braille canvas: four vertical pixels per cell, so a bar moves
+ * smoothly instead of stepping through eight block glyphs.
+ *
+ * Each band gets a column of pixels with a one-pixel gap, and its peak is held
+ * as a single floating pixel that sinks — the detail that made Winamp's
+ * analyser readable rather than just busy.
+ */
+export declare function drawSpectrum(canvas: BrailleCanvas, state: State): void;
+export declare function view({ ui, theme, height }: {
+    ui: Container;
+    theme: Theme;
+    height: number;
+}, state: State): void;

package/dist/main.js

@@ -0,0 +1,307 @@
+/**
+ * nixamp — it really whips the terminal's ass.
+ *
+ *   bunx nixamp ~/Music
+ *   bunx nixamp track.flac
+ *
+ * ffmpeg decodes; we read every sample on its way to the speakers and draw it.
+ */
+import { createApp, themes } from "@profullstack/hqtui";
+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 { DEFAULT_PORT } from "./server.js";
+const FFT_SIZE = 2048;
+export const BAND_COUNT = 24;
+export function createState(tracks, root, silent) {
+    return {
+        tracks,
+        index: 0,
+        offset: 0,
+        playing: false,
+        position: 0,
+        bars: new Array(BAND_COUNT).fill(0),
+        peakHold: new Array(BAND_COUNT).fill(0),
+        levels: [0, 0],
+        note: silent ? "No audio output found (install ffplay) — analyser only." : "",
+        silent,
+        root,
+    };
+}
+export function current(state) {
+    return state.tracks[state.index];
+}
+/** The classic block ramp, low to high. */
+const RAMP = "▁▂▃▄▅▆▇█";
+export function barGlyph(value) {
+    const i = Math.max(0, Math.min(RAMP.length - 1, Math.round(value * (RAMP.length - 1))));
+    return RAMP[i];
+}
+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 update [version]        re-run the installer, keeping your choices
+  nixamp uninstall [--yes]       remove everything the installer created
+
+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)
+      --web DIR    directory of built PWA files to serve at /
+      --no-media   do not stream the library's bytes to remotes
+
+  -v, --version    print the version
+      --help       print this
+`;
+/**
+ * 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,
+ * because the flag is false in a module that was imported rather than run.
+ */
+export async function main() {
+    const [first, ...rest] = process.argv.slice(2);
+    if (first === "serve") {
+        const { serve } = await import("./server.js");
+        await serve(rest, version());
+        return;
+    }
+    if (first === "update" || first === "uninstall") {
+        const manage = await import("./manage.js");
+        process.exitCode = first === "update" ? manage.update(rest) : manage.uninstall(rest);
+        return;
+    }
+    if (first === "--version" || first === "-v") {
+        console.log(version());
+        return;
+    }
+    if (first === "--help") {
+        console.log(HELP);
+        return;
+    }
+    const target = resolve(first ?? ".");
+    const tools = detectTools();
+    const tracks = loadPlaylist(tools, target);
+    if (tracks.length === 0) {
+        console.error(`nixamp: no audio files under ${target}`);
+        process.exit(1);
+    }
+    const state = createState(tracks, target, tools.play === null);
+    const app = await createApp({ theme: themes.matrix, title: "nixamp", quitKeys: ["ctrl+c"] });
+    const analyser = new Analyser(FFT_SIZE, RATE);
+    const edges = bandEdges(BAND_COUNT, RATE, FFT_SIZE);
+    // Samples accumulate until there are enough for one transform.
+    let pending = new Float32Array(0);
+    const stream = new Stream(tools, {
+        onSamples: (pcm) => {
+            state.levels = peaks(pcm);
+            state.position = stream.position;
+            const mono = toMono(pcm);
+            const joined = new Float32Array(pending.length + mono.length);
+            joined.set(pending);
+            joined.set(mono, pending.length);
+            let at = 0;
+            while (joined.length - at >= FFT_SIZE) {
+                analyser.run(joined.subarray(at, at + FFT_SIZE));
+                state.bars = decay(state.bars, bands(analyser.magnitudes, edges));
+                state.peakHold = state.peakHold.map((p, i) => Math.max(state.bars[i], p - 0.02));
+                at += FFT_SIZE;
+            }
+            pending = joined.subarray(at);
+            app.invalidate();
+        },
+        onEnd: (error) => {
+            if (error) {
+                state.note = error;
+                state.playing = false;
+                app.invalidate();
+                return;
+            }
+            next(1);
+        },
+    });
+    const play = () => {
+        const track = current(state);
+        if (!track)
+            return;
+        pending = new Float32Array(0);
+        state.position = 0;
+        state.playing = true;
+        state.note = state.silent ? "No audio output found (install ffplay) — analyser only." : "";
+        stream.start(track);
+        app.invalidate();
+    };
+    const next = (delta) => {
+        if (state.tracks.length === 0)
+            return;
+        state.index = (state.index + delta + state.tracks.length) % state.tracks.length;
+        if (state.playing)
+            play();
+        else {
+            state.position = 0;
+            app.invalidate();
+        }
+    };
+    const stopAll = () => {
+        stream.stop();
+        state.playing = false;
+        state.bars = new Array(BAND_COUNT).fill(0);
+        state.peakHold = new Array(BAND_COUNT).fill(0);
+        state.levels = [0, 0];
+        state.position = 0;
+        app.invalidate();
+    };
+    app.on("key", (event) => {
+        switch (event.key) {
+            case "q":
+                stream.stop();
+                app.quit();
+                return;
+            case "space":
+                state.playing ? stopAll() : play();
+                return;
+            case "enter":
+                play();
+                return;
+            case "s":
+                stopAll();
+                return;
+            case "n":
+            case "right":
+                next(1);
+                return;
+            case "p":
+            case "left":
+                next(-1);
+                return;
+            case "up":
+                state.index = Math.max(0, state.index - 1);
+                if (state.playing)
+                    play();
+                else
+                    app.invalidate();
+                return;
+            case "down":
+                state.index = Math.min(state.tracks.length - 1, state.index + 1);
+                if (state.playing)
+                    play();
+                else
+                    app.invalidate();
+                return;
+        }
+    });
+    app.on("exit", () => stream.stop());
+    app.render((args) => view(args, state));
+    await app.start();
+}
+/**
+ * The bars, on a braille canvas: four vertical pixels per cell, so a bar moves
+ * smoothly instead of stepping through eight block glyphs.
+ *
+ * Each band gets a column of pixels with a one-pixel gap, and its peak is held
+ * as a single floating pixel that sinks — the detail that made Winamp's
+ * analyser readable rather than just busy.
+ */
+export function drawSpectrum(canvas, state) {
+    const high = canvas.height;
+    const wide = canvas.width;
+    if (high <= 0 || wide <= 0)
+        return;
+    const perBand = Math.max(1, Math.floor(wide / state.bars.length));
+    state.bars.forEach((value, i) => {
+        const x0 = i * perBand;
+        const top = Math.round((1 - value) * (high - 1));
+        for (let x = x0; x < x0 + Math.max(1, perBand - 1) && x < wide; x++) {
+            canvas.vline(x, top, high - 1);
+            canvas.pixel(x, Math.round((1 - state.peakHold[i]) * (high - 1)));
+        }
+    });
+}
+export function view({ ui, theme, height }, state) {
+    const track = current(state);
+    const duration = track?.duration ?? 0;
+    const progress = duration > 0 ? Math.min(1, state.position / duration) : 0;
+    ui.row({ size: 1 }, (header) => {
+        header.text(" ⣿ NIXAMP", { fg: theme.title, bold: true, size: 11 });
+        header.text(state.playing ? "▶ PLAYING" : "■ STOPPED", {
+            fg: state.playing ? theme.success : theme.muted,
+            size: 12,
+        });
+        header.text(`${state.tracks.length} tracks  ${state.root} `, { fg: theme.muted, align: "right" });
+    });
+    ui.panel({ title: "Now Playing", size: 6 }, (p) => {
+        if (!track) {
+            p.label("Nothing loaded.");
+            return;
+        }
+        p.text(displayName(track), { fg: theme.accent, bold: true, size: 1 });
+        p.text(track.album || "—", { fg: theme.muted, size: 1 });
+        p.row({ size: 1 }, (r) => {
+            r.text(formatTime(state.position), { fg: theme.foreground, size: 7 });
+            r.progress({ value: progress, color: theme.success });
+            r.text(duration > 0 ? formatTime(duration) : "--:--", {
+                fg: theme.muted, size: 7, align: "right",
+            });
+        });
+    });
+    ui.row({ size: height - 10, gap: 1 }, (row) => {
+        row.panel({ title: "Spectrum Analyser", width: "1.3fr" }, (p) => {
+            // Braille gives four vertical pixels per cell, so the bars move smoothly
+            // rather than stepping through eight block glyphs.
+            p.canvas((canvas) => {
+                drawSpectrum(canvas, state);
+            }, { color: theme.success });
+            p.row({ size: 1 }, (r) => {
+                r.text(state.bars.map(barGlyph).join(""), { fg: theme.success });
+                r.text(`L${"▮".repeat(Math.round(state.levels[0] * 6)).padEnd(6, "·")} ` +
+                    `R${"▮".repeat(Math.round(state.levels[1] * 6)).padEnd(6, "·")}`, { fg: theme.accent, align: "right" });
+            });
+        });
+        row.panel({ title: `Playlist (${state.tracks.length})`, width: "1fr" }, (p) => {
+            if (state.tracks.length === 0) {
+                p.label("Empty.");
+                return;
+            }
+            p.table({
+                rows: state.tracks.map((t, i) => ({
+                    n: String(i + 1).padStart(2, " "),
+                    name: displayName(t),
+                    time: t.duration > 0 ? formatTime(t.duration) : "--:--",
+                    playing: i === state.index && state.playing,
+                })),
+                selected: state.index,
+                offset: state.offset,
+                followSelection: true,
+                scrollbar: true,
+                onScroll: (d) => { state.offset = Math.max(0, state.offset + d); },
+                header: false,
+                columns: [
+                    { key: "n", title: "", width: 3, color: theme.muted },
+                    {
+                        key: "name", title: "", min: 8,
+                        color: (row) => (row.playing ? theme.success : theme.foreground),
+                    },
+                    { key: "time", title: "", width: 6, align: "right", color: theme.muted },
+                ],
+            });
+        });
+    });
+    if (state.note !== "")
+        ui.text(state.note, { fg: theme.warning, size: 1 });
+    ui.statusBar({
+        items: [
+            { key: "Space", label: state.playing ? "Stop" : "Play", active: state.playing },
+            { key: "↑↓", label: "Select" },
+            { key: "n/p", label: "Next/Prev" },
+            { key: "Enter", label: "Play" },
+            { key: "q", label: "Quit" },
+        ],
+    });
+}
+if (import.meta.main) {
+    main().catch((error) => {
+        console.error(error);
+        process.exit(1);
+    });
+}

package/dist/manage.d.ts

@@ -0,0 +1,25 @@
+/** What the installer recorded about this install. */
+export interface Manifest {
+    version: string;
+    method: string;
+    installer: string;
+    installedAt: string;
+    prefix: string;
+    desktop: boolean;
+    paths: string[];
+}
+/**
+ * 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
+ * file covers a shim from an older install that did not set it.
+ */
+export declare function installRoot(from?: string): string | null;
+export declare function readManifest(root: string): Manifest | null;
+/**
+ * Update by re-running the installer with the same choices. It is the one
+ * place that knows how to lay an install out, so an update gets every fix the
+ * installer has had since, rather than only a newer tarball.
+ */
+export declare function update(argv: string[]): number;
+/** Run the uninstall script the installer left beside the manifest. */
+export declare function uninstall(argv: string[]): number;

package/dist/manage.js

@@ -0,0 +1,117 @@
+/**
+ * `nixamp update` and `nixamp uninstall`.
+ *
+ * Both belong on the CLI rather than in a second script the user has to find.
+ * Removal reads the manifest the installer wrote, so it is exact and works
+ * offline: a tool that needs the network to uninstall itself is one you cannot
+ * remove on a plane.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+const SITE = "https://nixamp.com";
+/**
+ * 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
+ * file covers a shim from an older install that did not set it.
+ */
+export function installRoot(from = new URL(".", import.meta.url).pathname) {
+    const declared = process.env["NIXAMP_HOME"];
+    if (declared && existsSync(join(declared, "manifest.json")))
+        return declared;
+    // dist/ -> the CLI directory -> share/nixamp for a CLI-only install, or the
+    // app bundle's resources for a desktop one.
+    let dir = resolve(from);
+    for (let i = 0; i < 6; i++) {
+        if (existsSync(join(dir, "manifest.json")))
+            return dir;
+        const share = join(dir, "share", "nixamp");
+        if (existsSync(join(share, "manifest.json")))
+            return share;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+export function readManifest(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, "manifest.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The message for a copy that no installer put here: a checkout, an npx run, or
+ * a package manager's own install. Telling someone to run `rm -rf` on a
+ * directory we did not create would be worse than saying so.
+ */
+function notInstalled(what) {
+    console.error(`nixamp: this copy was not put here by the installer, so there is nothing to ${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`);
+    return 69;
+}
+/**
+ * Update by re-running the installer with the same choices. It is the one
+ * place that knows how to lay an install out, so an update gets every fix the
+ * installer has had since, rather than only a newer tarball.
+ */
+export function update(argv) {
+    const root = installRoot();
+    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 wanted = argv.find((a) => !a.startsWith("-"));
+    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.");
+        return 69;
+    }
+    // Piping the script into sh is what the documented install line does, so an
+    // update takes exactly the path a fresh install takes.
+    const script = spawnSync(fetcher[0], fetcher.slice(1), { encoding: "utf8" });
+    if (script.status !== 0 || !script.stdout) {
+        console.error(`nixamp: could not fetch ${installer}`);
+        return 1;
+    }
+    const run = spawnSync("sh", args, { input: script.stdout, stdio: ["pipe", "inherit", "inherit"] });
+    return run.status ?? 1;
+}
+/** Run the uninstall script the installer left beside the manifest. */
+export function uninstall(argv) {
+    const root = installRoot();
+    const manifest = root ? readManifest(root) : null;
+    if (!root || !manifest)
+        return notInstalled("uninstall");
+    // Saying what would go needs only the manifest, so it comes first: a missing
+    // script is a problem for removing, not for describing.
+    if (!argv.includes("--yes") && !argv.includes("-y")) {
+        console.log(`This removes nixamp ${manifest.version} and everything the installer created:`);
+        for (const path of manifest.paths)
+            console.log(`  ${path}`);
+        console.log("");
+        console.log("Your music is not touched. Run `nixamp uninstall --yes` to go ahead.");
+        return 0;
+    }
+    const script = join(root, "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" });
+    return run.status ?? 1;
+}
+function which(command) {
+    return spawnSync("sh", ["-c", `command -v ${command}`], { stdio: "ignore" }).status === 0;
+}

package/dist/meta.d.ts

@@ -0,0 +1,2 @@
+/** The version we were installed as, or 0.0.0 when the manifest is missing. */
+export declare function version(): string;

package/dist/meta.js

@@ -0,0 +1,12 @@
+/** Facts about this install that both the terminal app and the server want. */
+import { readFileSync } from "node:fs";
+/** The version we were installed as, or 0.0.0 when the manifest is missing. */
+export function version() {
+    try {
+        const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+        return JSON.parse(raw).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}

package/dist/playlist.d.ts

@@ -0,0 +1,11 @@
+import { type Tools, type Track } from "./audio.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[];
+/**
+ * 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.
+ */
+export declare function loadPlaylist(tools: Tools, root: string, probeTags?: boolean): Track[];
+export declare function displayName(track: Track): string;

package/dist/playlist.js

@@ -0,0 +1,66 @@
+/** The playlist: audio files found on disk, in a stable order. */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { probe } from "./audio.js";
+export const AUDIO_EXTENSIONS = new Set([
+    ".mp3", ".flac", ".ogg", ".oga", ".opus", ".m4a", ".aac",
+    ".wav", ".wma", ".aiff", ".aif", ".alac", ".mp4", ".webm",
+]);
+export function isAudio(path) {
+    const dot = path.lastIndexOf(".");
+    return dot > 0 && AUDIO_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** Every audio file under `root`, depth first. A single file is a playlist of one. */
+export function findAudio(root) {
+    const out = [];
+    let stats;
+    try {
+        stats = statSync(root);
+    }
+    catch {
+        return out;
+    }
+    if (stats.isFile())
+        return isAudio(root) ? [root] : out;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir).sort();
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith("."))
+                continue;
+            const full = join(dir, entry);
+            let s;
+            try {
+                s = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (s.isDirectory())
+                walk(full);
+            else if (isAudio(full))
+                out.push(full);
+        }
+    };
+    walk(root);
+    return out;
+}
+/**
+ * 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.
+ */
+export function loadPlaylist(tools, root, probeTags = true) {
+    return findAudio(root).map((path) => probeTags ? probe(tools, path) : {
+        path,
+        title: path.split("/").pop() ?? path,
+        artist: "", album: "", duration: 0,
+    });
+}
+export function displayName(track) {
+    return track.artist ? `${track.artist} — ${track.title}` : track.title;
+}

package/dist/protocol.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The wire format between a running nixamp and any remote that drives it.
+ *
+ * Kept free of node imports on purpose: the browser client type-checks against
+ * this same file, so a change to the protocol breaks both sides at once rather
+ * than one of them at runtime.
+ */
+/** A track as a remote sees it — no filesystem path leaves the machine. */
+export interface RemoteTrack {
+    title: string;
+    artist: string;
+    album: string;
+    /** Seconds; 0 when ffprobe could not tell us. */
+    duration: number;
+}
+/** Everything a remote needs to draw the player. */
+export interface Snapshot {
+    /** Bumped on every push so a client can drop an out-of-order frame. */
+    revision: number;
+    tracks: RemoteTrack[];
+    index: number;
+    playing: boolean;
+    position: number;
+    /** Analyser bands, 0..1, one per bar. */
+    bars: number[];
+    /** Left and right peak levels, 0..1. */
+    levels: [number, number];
+    /** Whether this machine can actually make sound. */
+    silent: boolean;
+    note: string;
+    root: string;
+}
+export type Command = {
+    type: "play";
+    index?: number;
+} | {
+    type: "toggle";
+} | {
+    type: "stop";
+} | {
+    type: "next";
+} | {
+    type: "prev";
+} | {
+    type: "select";
+    index: number;
+};
+export declare const COMMAND_TYPES: readonly ["play", "toggle", "stop", "next", "prev", "select"];
+/**
+ * Commands arrive as untrusted JSON from a browser on the LAN, so nothing is
+ * assumed: an unknown type or a non-integer index is a null, not a throw.
+ */
+export declare function parseCommand(input: unknown): Command | null;
+/** The name a remote shows for a track. */
+export declare function remoteName(track: RemoteTrack): string;
+export declare function emptySnapshot(): Snapshot;