nixamp 0.30.1 → 0.32.0

package/dist/channels.d.ts

@@ -232,6 +232,12 @@ export declare class Channel {
     private playlistInput;
     /** On to the next entry of a list of files. False when this is not one. */
     skip(): boolean;
+    /** An entry's tags, as read when it was put on. */
+    tagsOf(file: string): {
+        title: string;
+        artist: string;
+        album: string;
+    } | undefined;
     private failures;
     private timer;
     /** Fires when a pulled source has said nothing for STALL. */
@@ -497,6 +503,12 @@ export declare class Channels {
     setThrough(provider: ThroughProvider | null): void;
     /** The kind of a channel, for a relay to say what it is carrying. */
     kindOf(id: string): "audio" | "video" | undefined;
+    /** An entry's tags on a channel playing a list of files. */
+    tagsOf(id: string, file: string): {
+        title: string;
+        artist: string;
+        album: string;
+    } | undefined;
     /** The next entry, now, on a channel playing a list of files. */
     skip(id: string): boolean;
     stop(id: string): boolean;

package/dist/channels.js

@@ -141,6 +141,10 @@ export class Channel {
     skip() {
         return this.playlistInput?.skip() ?? false;
     }
+    /** An entry's tags, as read when it was put on. */
+    tagsOf(file) {
+        return this.playlistInput?.tags.get(file);
+    }
     failures = 0;
     timer = null;
     /** Fires when a pulled source has said nothing for STALL. */
@@ -1168,6 +1172,10 @@ export class Channels {
     kindOf(id) {
         return this.open.get(id)?.info.kind;
     }
+    /** An entry's tags on a channel playing a list of files. */
+    tagsOf(id, file) {
+        return this.open.get(id)?.tagsOf(file);
+    }
     /** The next entry, now, on a channel playing a list of files. */
     skip(id) {
         return this.open.get(id)?.skip() ?? false;

package/dist/library-cli.d.ts

@@ -0,0 +1,3 @@
+import { LIBRARY_COMMANDS, LIBRARY_USAGE } from "./library-usage.ts";
+export { LIBRARY_COMMANDS, LIBRARY_USAGE };
+export declare function libraryTool(argv: string[]): Promise<number>;

package/dist/library-cli.js

@@ -0,0 +1,198 @@
+/**
+ * `nixamp library <command>`: the index, from a terminal or a script.
+ *
+ * `nixamp library ~/Music` still sets the folder a daemon serves (library.ts);
+ * these are the questions you ask once it is running. Same conventions as
+ * `nixamp station`: the daemon on this machine unless --url/--key, --json for
+ * scripts, exit 0 done, 1 refused, 2 usage, 3 unreachable.
+ */
+import { resolveTarget } from "./admin.js";
+import { KEY_HEADER } from "./share.js";
+import { LIBRARY_COMMANDS, LIBRARY_USAGE } from "./library-usage.js";
+export { LIBRARY_COMMANDS, LIBRARY_USAGE };
+function flag(argv, name) {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+}
+/** Words that are not flags or flag values. */
+function words(argv) {
+    const out = [];
+    for (let at = 0; at < argv.length; at++) {
+        const one = argv[at];
+        if (one.startsWith("--")) {
+            if (!["--json", "--force", "--wait"].includes(one))
+                at += 1;
+            continue;
+        }
+        out.push(one);
+    }
+    return out;
+}
+export async function libraryTool(argv) {
+    const [command] = argv;
+    const json = argv.includes("--json");
+    let target;
+    try {
+        target = resolveTarget(argv);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 3;
+    }
+    const headers = { "content-type": "application/json", ...(target.key ? { [KEY_HEADER]: target.key } : {}) };
+    const call = async (method, path, body) => {
+        let response;
+        try {
+            response = await fetch(`${target.url}${path}`, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+        }
+        catch (error) {
+            throw Object.assign(new Error(`could not reach ${target.url}: ${error.message}`), { unreachable: true });
+        }
+        const parsed = (await response.json().catch(() => ({})));
+        return { status: response.status, body: parsed };
+    };
+    const out = (answer, line) => {
+        if (json)
+            console.log(JSON.stringify(answer.body, null, 2));
+        else if (answer.status < 400)
+            console.log(line(answer.body));
+        if (answer.status >= 400) {
+            if (!json)
+                console.error(`nixamp: ${String(answer.body["error"] ?? "refused")} (${String(answer.body["code"] ?? answer.status)})`);
+            return 1;
+        }
+        return 0;
+    };
+    const scanLine = (scan) => scan ? `${String(scan["status"])}: ${String(scan["found"])} found, ${String(scan["unchanged"])} unchanged, ${String(scan["probed"])} read, ${String(scan["failed"])} failed, ${String(scan["missing"])} gone` : "never scanned";
+    const itemLine = (item) => `${String(item["id"])}  ${String(item["artist"] || "?")} — ${String(item["title"])}${item["album"] ? `  (${String(item["album"])})` : ""}${item["state"] !== "ready" ? `  [${String(item["state"])}]` : ""}`;
+    const rest = words(argv.slice(1));
+    try {
+        switch (command) {
+            case "status":
+                return out(await call("GET", "/api/v1/library"), (body) => {
+                    const counts = body["counts"];
+                    const sources = body["sources"] ?? [];
+                    return [
+                        `${String(body["items"])} items: ${Object.entries(counts).filter(([, n]) => n > 0).map(([state, n]) => `${n} ${state}`).join(", ") || "none"}`,
+                        ...sources.map((one) => `  ${String(one["id"])}  ${String(one["root"] ?? "")}${one["enabled"] ? "" : " (off)"}\n    last scan ${scanLine(one["lastScan"])}`),
+                    ].join("\n");
+                });
+            case "sources":
+                return out(await call("GET", "/api/v1/library/sources"), (body) => (body["sources"] ?? []).map((one) => `${String(one["id"])}  ${String(one["root"] ?? "")}${one["enabled"] ? "" : " (off)"}`).join("\n") || "No sources.");
+            case "add": {
+                const [path] = rest;
+                if (!path) {
+                    console.error("nixamp library add needs a folder");
+                    return 2;
+                }
+                const { resolve } = await import("node:path");
+                const { homedir } = await import("node:os");
+                return out(await call("POST", "/api/v1/library/sources", { root: resolve(path.replace(/^~(?=$|\/)/, homedir())) }), (body) => `Indexing ${String(body["source"]["root"])} as ${String(body["source"]["id"])}.`);
+            }
+            case "scan": {
+                let [source] = rest;
+                if (!source) {
+                    const listed = await call("GET", "/api/v1/library/sources");
+                    const all = listed.body["sources"] ?? [];
+                    if (all.length !== 1) {
+                        console.error("Which source? `nixamp library sources` lists them.");
+                        return 2;
+                    }
+                    source = String(all[0]["id"]);
+                }
+                const started = await call("POST", `/api/v1/library/sources/${source}/scan`, { force: argv.includes("--force") });
+                if (started.status >= 400 || !argv.includes("--wait"))
+                    return out(started, (body) => `Scanning: job ${String(body["job"]["jobId"])}.`);
+                const jobId = String(started.body["job"]["jobId"]);
+                for (;;) {
+                    const polled = await call("GET", `/api/v1/library/jobs/${jobId}`);
+                    const job = polled.body["job"];
+                    if (polled.status >= 400 || !job || job["status"] !== "running")
+                        return out(polled, () => scanLine(job));
+                    await new Promise((next) => setTimeout(next, 1000));
+                }
+            }
+            case "search": {
+                const query = new URLSearchParams({ q: rest.join(" "), limit: flag(argv, "--limit") ?? "20", sort: "artist" });
+                for (const name of ["artist", "album", "genre", "state", "folder"]) {
+                    const value = flag(argv, `--${name}`);
+                    if (value)
+                        query.set(name, value);
+                }
+                return out(await call("GET", `/api/v1/library/items?${query}`), (body) => {
+                    const items = body["items"] ?? [];
+                    return items.length ? `${items.map(itemLine).join("\n")}\n${String(body["total"])} in all` : "Nothing matches.";
+                });
+            }
+            case "show": {
+                const [item] = rest;
+                if (!item) {
+                    console.error("nixamp library show needs an item id");
+                    return 2;
+                }
+                return out(await call("GET", `/api/v1/library/items/${item}`), (body) => JSON.stringify(body["item"], null, 2));
+            }
+            case "fix": {
+                const [item] = rest;
+                if (!item) {
+                    console.error("nixamp library fix needs an item id");
+                    return 2;
+                }
+                const patch = {};
+                for (const name of ["title", "artist", "album", "albumArtist", "genre"]) {
+                    const value = flag(argv, `--${name}`);
+                    if (value !== undefined)
+                        patch[name] = value;
+                }
+                for (const name of ["track", "disc", "year"]) {
+                    const value = flag(argv, `--${name}`);
+                    if (value !== undefined)
+                        patch[name] = Number(value);
+                }
+                if (Object.keys(patch).length === 0) {
+                    console.error("nixamp library fix needs at least one of --title --artist --album --genre --track --disc --year");
+                    return 2;
+                }
+                return out(await call("PATCH", `/api/v1/library/items/${item}`, patch), (body) => itemLine(body["item"]));
+            }
+            case "remove": {
+                const [source] = rest;
+                if (!source) {
+                    console.error("nixamp library remove needs a source id");
+                    return 2;
+                }
+                return out(await call("DELETE", `/api/v1/library/sources/${source}`), (body) => `Forgot ${String(body["forgotten"])} items. No file was touched.`);
+            }
+            case "playlists":
+                return out(await call("GET", "/api/v1/library/playlists"), (body) => (body["playlists"] ?? []).map((one) => `${String(one["id"])}  ${String(one["name"])} (${String(one["count"])})`).join("\n") || "No playlists yet.");
+            case "playlist": {
+                const [verb, first, ...others] = rest;
+                const showList = (body) => {
+                    const list = body["playlist"];
+                    const items = list["items"] ?? [];
+                    return [`${String(list["id"])}  ${String(list["name"])} (revision ${String(list["revision"])})`, ...items.map((one, at) => `  ${at + 1}. ${itemLine(one)}`)].join("\n");
+                };
+                if (verb === "new" && first)
+                    return out(await call("POST", "/api/v1/library/playlists", { name: first, items: others }), showList);
+                if (verb === "show" && first)
+                    return out(await call("GET", `/api/v1/library/playlists/${first}`), showList);
+                if (verb === "add" && first && others.length)
+                    return out(await call("POST", `/api/v1/library/playlists/${first}/items`, { items: others }), showList);
+                if (verb === "delete" && first)
+                    return out(await call("DELETE", `/api/v1/library/playlists/${first}`), () => `Deleted playlist ${first}.`);
+                console.error("nixamp library playlist new NAME [ITEM...] | show ID | add ID ITEM... | delete ID");
+                return 2;
+            }
+            default:
+                console.log(LIBRARY_USAGE);
+                return 2;
+        }
+    }
+    catch (error) {
+        if (error.unreachable) {
+            console.error(`nixamp: ${error.message}`);
+            return 3;
+        }
+        throw error;
+    }
+}

package/dist/library-index.d.ts

@@ -0,0 +1,190 @@
+import type { Track, Tools } from "./audio.ts";
+export type ItemState = "pending" | "ready" | "unsupported" | "failed" | "unavailable";
+export interface Tags {
+    title: string;
+    artist: string;
+    album: string;
+    albumArtist: string;
+    track: number;
+    disc: number;
+    genre: string;
+    year: number;
+}
+export declare const TAG_FIELDS: readonly (keyof Tags)[];
+export interface LibraryItem extends Tags {
+    id: string;
+    sourceId: string;
+    /** Absolute; never shown to anybody but the owner. */
+    path: string;
+    /** Inside the source, with forward slashes. */
+    rel: string;
+    size: number;
+    mtimeMs: number;
+    state: ItemState;
+    error: string;
+    /** Seconds; 0 until known. */
+    duration: number;
+    codec: string;
+    bitrate: number;
+    sampleRate: number;
+    channels: number;
+    video: boolean;
+    hasArt: boolean;
+    /** The owner's corrections, applied over what the file says. */
+    override: Partial<Tags>;
+    firstSeen: number;
+    lastSeen: number;
+    probedAt: number;
+}
+export interface ScanReport {
+    jobId: string;
+    sourceId: string;
+    status: "running" | "done" | "failed" | "cancelled";
+    startedAt: number;
+    finishedAt: number;
+    found: number;
+    unchanged: number;
+    probed: number;
+    ready: number;
+    failed: number;
+    unsupported: number;
+    missing: number;
+    /** Paths that lead outside the source (symlinks), left out. */
+    outside: number;
+    error: string;
+}
+export interface LibrarySource {
+    id: string;
+    kind: "folder";
+    root: string;
+    owner: string;
+    host: string;
+    enabled: boolean;
+    createdAt: number;
+    lastScan: ScanReport | null;
+}
+/** What one probe found. */
+export interface Probed {
+    state: "ready" | "unsupported" | "failed";
+    error: string;
+    tags: Partial<Tags>;
+    duration: number;
+    codec: string;
+    bitrate: number;
+    sampleRate: number;
+    channels: number;
+    video: boolean;
+    hasArt: boolean;
+}
+export declare class LibraryError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}
+/** Tags as ffprobe names them, in any case, from the container or the first audio stream. */
+export declare function tagsFrom(raw: Record<string, string>): Partial<Tags>;
+/** What ffprobe says about one file, read as a library needs it. */
+export declare function readProbe(json: string): Probed;
+/** Ask ffprobe about one file, without holding the event loop and never for ever. */
+export declare function probeItem(tools: Tools, path: string, timeoutMs?: number): Promise<Probed>;
+/**
+ * Every playable file under a root, in name order, without leaving it.
+ *
+ * Directory symlinks are followed only when they land inside the root and
+ * have not been seen before, so a link back to a parent is not a loop and a
+ * link to somewhere else is not a door. Counted, so the scan can say how many
+ * were left out.
+ */
+export declare function walkSource(root: string, every?: number): Promise<{
+    files: string[];
+    outside: number;
+}>;
+export interface SearchQuery {
+    q?: string;
+    artist?: string;
+    album?: string;
+    genre?: string;
+    folder?: string;
+    sourceId?: string;
+    state?: ItemState | "all";
+    sort?: "path" | "title" | "artist" | "album" | "recent";
+    limit?: number;
+    offset?: number;
+}
+export type Browse = "artists" | "albums" | "genres" | "folders";
+/** An item as it should read: the owner's corrections over the file's tags over its name. */
+export declare function shown(item: LibraryItem): Tags;
+/** The library of one server, in one file beside its keys. */
+export declare class LibraryIndex {
+    private readonly file;
+    private readonly io;
+    private readonly now;
+    private items;
+    private byPath;
+    private sourceList;
+    private timer;
+    private dirty;
+    private jobs;
+    constructor(file: string, io?: {
+        read: (path: string) => string | null;
+        write: (path: string, body: string) => void;
+    }, now?: () => number);
+    static fileFor(stateDir: string, port: number): string;
+    /** Written soon, not now: a scan changes thousands of items. */
+    private touch;
+    flush(): void;
+    sources(): LibrarySource[];
+    source(id: string): LibrarySource | undefined;
+    /** The folders this server's files have to be inside: every enabled source. */
+    roots(): string[];
+    /** A folder as a source: refused when it is not one a library may be. */
+    addSource(root: string, owner: string, host?: string): LibrarySource;
+    /** The folder this server was started on, as a source, made once. */
+    ensureSource(root: string, owner: string): LibrarySource | null;
+    setEnabled(id: string, enabled: boolean): LibrarySource;
+    /** Forget a source and what was learned from it. Its files are not touched. */
+    removeSource(id: string): number;
+    item(id: string): LibraryItem | undefined;
+    itemAt(path: string): LibraryItem | undefined;
+    get size(): number;
+    job(id: string): ScanReport | undefined;
+    running(sourceId: string): ScanReport | undefined;
+    /**
+     * Look at a source again: new files are found, changed ones asked about,
+     * gone ones marked unavailable. Returns at once with the job; `done`
+     * settles when it is finished. One scan per source at a time.
+     */
+    scan(sourceId: string, probe: (path: string) => Promise<Probed>, options?: {
+        concurrency?: number;
+        onProgress?: (changed: LibraryItem[]) => void;
+        force?: boolean;
+    }): {
+        report: ScanReport;
+        done: Promise<ScanReport>;
+    };
+    private runScan;
+    /** The owner's corrections; an empty value clears that field's correction. */
+    correct(id: string, patch: Record<string, unknown>): LibraryItem;
+    search(query?: SearchQuery): {
+        items: LibraryItem[];
+        total: number;
+    };
+    /** Grouped: every artist, album, genre or top-level folder, with how many ready items. */
+    browse(kind: Browse, options?: {
+        q?: string;
+        limit?: number;
+        offset?: number;
+    }): {
+        groups: Array<{
+            name: string;
+            count: number;
+            artist?: string;
+        }>;
+        total: number;
+    };
+    /** How the player should name each file it already has, from what is known. */
+    tracksFor(paths: string[]): Track[];
+    counts(): Record<ItemState, number>;
+}
+/** A library item as the player's Track. */
+export declare function trackOf(item: LibraryItem): Track;