nixamp 0.30.3 → 0.33.0

package/src/library-mcp.ts

@@ -0,0 +1,132 @@
+/**
+ * The library as MCP tools: what is here, find something, look again.
+ *
+ * Same target and credential rules as the station tools (station-mcp.ts):
+ * this machine's daemon by its control key, or another server as its owner.
+ */
+import { connect, type StationToolOptions } from "./station-mcp.ts";
+
+const STRING = { type: "string" } as const;
+const SERVER = { ...STRING, description: "A nixamp server's address; this machine's daemon when omitted." };
+
+export const LIBRARY_TOOLS = [
+  {
+    name: "library_status",
+    description: "How many items the library has in each state (ready, pending, failed, unsupported, unavailable), its sources, and their last scans.",
+    inputSchema: { type: "object", properties: { server: SERVER } },
+  },
+  {
+    name: "library_search",
+    description: "Find items in the library by words (title, artist, album, genre, folder) and filters. Returns ids usable for stations (as track paths) and corrections.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        server: SERVER,
+        q: STRING, artist: STRING, album: STRING, genre: STRING, folder: STRING,
+        state: { type: "string", enum: ["ready", "pending", "failed", "unsupported", "unavailable", "all"] },
+        limit: { type: "integer" }, offset: { type: "integer" },
+      },
+    },
+  },
+  {
+    name: "library_browse",
+    description: "The library grouped: every artist, album, genre or top-level folder, with counts.",
+    inputSchema: {
+      type: "object",
+      properties: { server: SERVER, kind: { type: "string", enum: ["artists", "albums", "genres", "folders"] }, q: STRING, limit: { type: "integer" } },
+      required: ["kind"],
+    },
+  },
+  {
+    name: "playlist_list",
+    description: "This listener's playlists on the server: id, name, how many items.",
+    inputSchema: { type: "object", properties: { server: SERVER } },
+  },
+  {
+    name: "playlist_create",
+    description: "A new playlist from library item ids (from library_search), in order. A playlist can then be a station: station_create with playlist.",
+    inputSchema: { type: "object", properties: { server: SERVER, name: STRING, items: { type: "array", items: STRING } }, required: ["name"] },
+  },
+  {
+    name: "playlist_add",
+    description: "Add library items to a playlist, at the end or at a place.",
+    inputSchema: { type: "object", properties: { server: SERVER, id: STRING, items: { type: "array", items: STRING }, at: { type: "integer" } }, required: ["id", "items"] },
+  },
+  {
+    name: "library_scan",
+    description: "Look at a source again: new files are read, changed ones re-read, gone ones marked unavailable. Returns a job id; library_status shows when it is done.",
+    inputSchema: { type: "object", properties: { server: SERVER, source: STRING, force: { type: "boolean" } } },
+  },
+];
+
+export function isLibraryTool(name: string): boolean {
+  return LIBRARY_TOOLS.some((tool) => tool.name === name);
+}
+
+type Result = { content: { type: "text"; text: string }[]; isError?: boolean };
+const say = (text: string, isError = false): Result => ({ content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) });
+
+export async function callLibraryTool(name: string, args: Record<string, unknown>, options: StationToolOptions = {}): Promise<Result> {
+  const send = options.fetcher ?? fetch;
+  const target = connect(args, options);
+  if ("error" in target) return say(target.error, true);
+  const get = async (method: string, path: string, body?: unknown): Promise<{ ok: boolean; body: Record<string, unknown> }> => {
+    const response = await send(`${target.base}${path}`, { method, headers: target.headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    return { ok: response.ok, body: (await response.json().catch(() => ({}))) as Record<string, unknown> };
+  };
+  const refused = (body: Record<string, unknown>): Result => say(`${String(body["error"] ?? "refused")} (${String(body["code"] ?? "error")})`, true);
+  try {
+    if (name === "library_status") {
+      const answer = await get("GET", "/api/v1/library");
+      return answer.ok ? say(JSON.stringify(answer.body, null, 2)) : refused(answer.body);
+    }
+    if (name === "library_search") {
+      const query = new URLSearchParams();
+      for (const key of ["q", "artist", "album", "genre", "folder", "state"]) if (typeof args[key] === "string") query.set(key, args[key] as string);
+      for (const key of ["limit", "offset"]) if (typeof args[key] === "number") query.set(key, String(args[key]));
+      const answer = await get("GET", `/api/v1/library/items?${query}`);
+      if (!answer.ok) return refused(answer.body);
+      const items = (answer.body["items"] as Record<string, unknown>[]) ?? [];
+      const lines = items.map((one) => `${String(one["id"])}  ${String(one["artist"] || "?")} — ${String(one["title"])}${one["album"] ? ` (${String(one["album"])})` : ""}  ${String(one["rel"])}`);
+      return say(lines.length ? `${lines.join("\n")}\n${String(answer.body["total"])} in all` : "Nothing matches.");
+    }
+    if (name === "library_browse") {
+      const kind = String(args["kind"] ?? "");
+      const query = new URLSearchParams();
+      if (typeof args["q"] === "string") query.set("q", args["q"]);
+      if (typeof args["limit"] === "number") query.set("limit", String(args["limit"]));
+      const answer = await get("GET", `/api/v1/library/browse/${encodeURIComponent(kind)}?${query}`);
+      if (!answer.ok) return refused(answer.body);
+      const groups = (answer.body["groups"] as Array<{ name: string; count: number; artist?: string }>) ?? [];
+      return say(groups.map((one) => `${one.name}${one.artist ? ` — ${one.artist}` : ""} (${one.count})`).join("\n") || "Nothing yet.");
+    }
+    if (name === "playlist_list") {
+      const answer = await get("GET", "/api/v1/library/playlists");
+      if (!answer.ok) return refused(answer.body);
+      const lists = (answer.body["playlists"] as Array<Record<string, unknown>>) ?? [];
+      return say(lists.map((one) => `${String(one["id"])}  ${String(one["name"])} (${String(one["count"])})`).join("\n") || "No playlists yet.");
+    }
+    if (name === "playlist_create" || name === "playlist_add") {
+      const answer = name === "playlist_create"
+        ? await get("POST", "/api/v1/library/playlists", { name: args["name"], items: args["items"] ?? [] })
+        : await get("POST", `/api/v1/library/playlists/${encodeURIComponent(String(args["id"] ?? ""))}/items`, { items: args["items"], ...(typeof args["at"] === "number" ? { at: args["at"] } : {}) });
+      if (!answer.ok) return refused(answer.body);
+      const list = answer.body["playlist"] as Record<string, unknown>;
+      return say(`${String(list["id"])}  ${String(list["name"])}: ${String(list["count"])} items, revision ${String(list["revision"])}`);
+    }
+        if (name === "library_scan") {
+      let source = typeof args["source"] === "string" ? args["source"] : "";
+      if (!source) {
+        const listed = await get("GET", "/api/v1/library/sources");
+        const all = (listed.body["sources"] as Record<string, unknown>[]) ?? [];
+        if (all.length !== 1) return say("Which source? library_status lists them.", true);
+        source = String(all[0]!["id"]);
+      }
+      const answer = await get("POST", `/api/v1/library/sources/${source}/scan`, { force: args["force"] === true });
+      return answer.ok ? say(`Scanning; job ${String((answer.body["job"] as Record<string, unknown>)["jobId"])}.`) : refused(answer.body);
+    }
+  } catch (error) {
+    return say(`Could not reach ${target.base}: ${(error as Error).message}`, true);
+  }
+  return say(`No such tool: ${name}`, true);
+}

package/src/library-routes.ts

@@ -0,0 +1,282 @@
+/**
+ * /api/v1/library: the owner's files, as sources, items and groups.
+ *
+ * Reading -- search, browse, an item, its stream -- is for whoever got past
+ * the server's key: the owner, or somebody the owner gave the listen link to,
+ * which has always been how a library is shared. Only the owner sees where a
+ * file lives (`path`); everybody else gets its place inside the library.
+ * Changing anything -- sources, scans, corrections -- is the owner's.
+ * A station's link reaches none of this.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { hostname } from "node:os";
+import {
+  LibraryError, shown, trackOf, type Browse, type ItemState, type LibraryIndex, type LibraryItem, type Probed, type SearchQuery,
+} from "./library-index.ts";
+import type { Track } from "./audio.ts";
+import type { ListenerStore, Playlist, Queue } from "./library-user.ts";
+
+export interface LibraryContext {
+  index: LibraryIndex;
+  /** Past the server's key: may read. */
+  canRead: boolean;
+  /** The control key or the owner: may change things. */
+  canWrite: boolean;
+  account: string;
+  /** Who this is, for their playlists and queue; null when nobody in particular. */
+  principal: string | null;
+  listeners?: ListenerStore;
+  probe: (path: string) => Promise<Probed>;
+  /** Tell the player about tags that changed. */
+  retag: (tracks: Track[]) => void;
+  sendFile: (request: IncomingMessage, response: ServerResponse, file: string, cache: string) => void;
+  json: (response: ServerResponse, status: number, body: unknown) => void;
+  readBody: (request: IncomingMessage) => Promise<string>;
+}
+
+/** An item as a caller may see it: the path only for the owner. */
+export function itemView(item: LibraryItem, owner: boolean): Record<string, unknown> {
+  const tags = shown(item);
+  return {
+    id: item.id,
+    sourceId: item.sourceId,
+    rel: item.rel,
+    ...(owner ? { path: item.path, override: item.override, size: item.size } : {}),
+    state: item.state,
+    ...(item.error && owner ? { error: item.error } : {}),
+    ...tags,
+    duration: item.duration,
+    format: { codec: item.codec, bitrateKbps: item.bitrate, sampleRate: item.sampleRate, channels: item.channels },
+    video: item.video,
+    hasArt: item.hasArt,
+  };
+}
+
+const STATES = new Set(["pending", "ready", "unsupported", "failed", "unavailable", "all"]);
+const SORTS = new Set(["path", "title", "artist", "album", "recent"]);
+const KINDS = new Set(["artists", "albums", "genres", "folders"]);
+
+export async function handleLibrary(
+  request: IncomingMessage,
+  response: ServerResponse,
+  path: string,
+  url: URL,
+  ctx: LibraryContext,
+): Promise<boolean> {
+  if (path !== "/api/v1/library" && !path.startsWith("/api/v1/library/")) return false;
+  const method = request.method ?? "GET";
+  const { index } = ctx;
+  const fail = (status: number, code: string, error: string): true => {
+    ctx.json(response, status, { error, code });
+    return true;
+  };
+  if (!ctx.canRead) return fail(401, "unauthorized", "this library needs its link, or sign in as its owner");
+  const needWrite = (): boolean => {
+    if (ctx.canWrite) return true;
+    fail(403, "forbidden", "only this server's owner changes its library");
+    return false;
+  };
+  const body = async (): Promise<Record<string, unknown>> => {
+    const raw = await ctx.readBody(request);
+    if (raw.trim() === "") return {};
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new LibraryError("bad_json", "the body is not a JSON object");
+    return parsed as Record<string, unknown>;
+  };
+  const number = (name: string): number | undefined => {
+    const value = url.searchParams.get(name);
+    return value === null ? undefined : Number(value) || 0;
+  };
+  const text = (name: string): string | undefined => url.searchParams.get(name) ?? undefined;
+
+  try {
+    if (path === "/api/v1/library" && method === "GET") {
+      ctx.json(response, 200, {
+        items: index.size,
+        counts: index.counts(),
+        sources: index.sources().map((one) => ({ id: one.id, enabled: one.enabled, lastScan: one.lastScan, ...(ctx.canWrite ? { root: one.root, host: one.host } : {}) })),
+      });
+      return true;
+    }
+
+    if (path === "/api/v1/library/sources") {
+      if (method === "GET") {
+        ctx.json(response, 200, { sources: index.sources().map((one) => (ctx.canWrite ? one : { id: one.id, enabled: one.enabled, lastScan: one.lastScan })) });
+        return true;
+      }
+      if (method === "POST") {
+        if (!needWrite()) return true;
+        const input = await body();
+        if (typeof input["root"] !== "string" || input["root"].trim() === "") throw new LibraryError("root_required", "say which folder: {\"root\": \"/path\"}");
+        const { existsSync, statSync } = await import("node:fs");
+        const root = input["root"].trim();
+        if (!existsSync(root) || !statSync(root).isDirectory()) throw new LibraryError("not_a_folder", "that is not a folder on this machine");
+        const source = index.addSource(root, ctx.account, hostname());
+        const { report } = index.scan(source.id, ctx.probe, { onProgress: (changed) => ctx.retag(changed.filter((one) => one.state === "ready").map(trackOf)) });
+        ctx.json(response, 201, { source, job: report });
+        return true;
+      }
+      return fail(405, "method_not_allowed", "GET or POST");
+    }
+
+    const sourceMatch = /^\/api\/v1\/library\/sources\/([0-9a-f]{16})(?:\/(scan))?$/.exec(path);
+    if (sourceMatch) {
+      const id = sourceMatch[1]!;
+      if (sourceMatch[2] === "scan") {
+        if (method !== "POST") return fail(405, "method_not_allowed", "POST");
+        if (!needWrite()) return true;
+        const input = await body();
+        const { report } = index.scan(id, ctx.probe, {
+          force: input["force"] === true,
+          onProgress: (changed) => ctx.retag(changed.filter((one) => one.state === "ready").map(trackOf)),
+        });
+        ctx.json(response, 202, { job: report });
+        return true;
+      }
+      if (method === "GET") {
+        const source = index.source(id);
+        if (!source) return fail(404, "not_found", "no such source");
+        ctx.json(response, 200, { source: ctx.canWrite ? source : { id: source.id, enabled: source.enabled, lastScan: source.lastScan } });
+        return true;
+      }
+      if (!needWrite()) return true;
+      if (method === "PATCH") {
+        const input = await body();
+        if (typeof input["enabled"] !== "boolean") throw new LibraryError("invalid_value", "enabled must be true or false");
+        ctx.json(response, 200, { source: index.setEnabled(id, input["enabled"]) });
+        return true;
+      }
+      if (method === "DELETE") {
+        const forgotten = index.removeSource(id);
+        ctx.json(response, 200, { deleted: id, forgotten, filesTouched: 0 });
+        return true;
+      }
+      return fail(405, "method_not_allowed", "GET, PATCH or DELETE");
+    }
+
+    if (path === "/api/v1/library/queue" || path === "/api/v1/library/playlists" || path.startsWith("/api/v1/library/playlists/")) {
+      const listeners = ctx.listeners;
+      if (!listeners) return fail(404, "not_found", "nothing here");
+      const who = ctx.principal;
+      if (who === null) return fail(401, "sign_in_required", "sign in to nixamp.com to keep playlists and pick up where you left off");
+      const known = (id: string): boolean => index.item(id) !== undefined;
+      const resolved = (ids: string[]): Array<Record<string, unknown>> => ids.map((id) => {
+        const item = index.item(id);
+        return item ? itemView(item, ctx.canWrite) : { id, state: "unavailable" };
+      });
+      const playlistView = (one: Playlist, withItems: boolean): Record<string, unknown> => ({
+        id: one.id, name: one.name, count: one.items.length, revision: one.revision, createdAt: one.createdAt, updatedAt: one.updatedAt,
+        ...(withItems ? { items: resolved(one.items) } : {}),
+      });
+      const queueView = (queue: Queue): Record<string, unknown> => ({ ...queue, items: resolved(queue.items), current: queue.items[queue.at] ?? null });
+
+      if (path === "/api/v1/library/queue") {
+        if (method === "GET") {
+          ctx.json(response, 200, { queue: queueView(listeners.queueOf(who)) });
+          return true;
+        }
+        if (method === "PUT" || method === "PATCH") {
+          ctx.json(response, 200, { queue: queueView(listeners.setQueue(who, await body(), known)) });
+          return true;
+        }
+        return fail(405, "method_not_allowed", "GET, PUT or PATCH");
+      }
+      if (path === "/api/v1/library/playlists") {
+        if (method === "GET") {
+          ctx.json(response, 200, { playlists: listeners.playlistsOf(who).map((one) => playlistView(one, false)) });
+          return true;
+        }
+        if (method === "POST") {
+          ctx.json(response, 201, { playlist: playlistView(listeners.create(who, await body(), known), true) });
+          return true;
+        }
+        return fail(405, "method_not_allowed", "GET or POST");
+      }
+      const playlistMatch = /^\/api\/v1\/library\/playlists\/([0-9a-f]{16})(?:\/(items))?$/.exec(path);
+      if (!playlistMatch) return fail(404, "not_found", "no such playlist");
+      const id = playlistMatch[1]!;
+      if (playlistMatch[2] === "items") {
+        if (method !== "POST") return fail(405, "method_not_allowed", "POST");
+        ctx.json(response, 200, { playlist: playlistView(listeners.add(who, id, await body(), known), true) });
+        return true;
+      }
+      if (method === "GET") {
+        ctx.json(response, 200, { playlist: playlistView(listeners.playlist(who, id), true) });
+        return true;
+      }
+      if (method === "PATCH") {
+        ctx.json(response, 200, { playlist: playlistView(listeners.update(who, id, await body(), known), true) });
+        return true;
+      }
+      if (method === "DELETE") {
+        listeners.remove(who, id);
+        ctx.json(response, 200, { deleted: id });
+        return true;
+      }
+      return fail(405, "method_not_allowed", "GET, PATCH or DELETE");
+    }
+
+    const jobMatch = /^\/api\/v1\/library\/jobs\/([0-9a-f]{16})$/.exec(path);
+    if (jobMatch) {
+      const job = index.job(jobMatch[1]!);
+      if (!job) return fail(404, "not_found", "no such job (jobs are kept until the server restarts)");
+      ctx.json(response, 200, { job });
+      return true;
+    }
+
+    if (path === "/api/v1/library/items" && method === "GET") {
+      const state = text("state");
+      const sort = text("sort");
+      const query: SearchQuery = {
+        q: text("q"), artist: text("artist"), album: text("album"), genre: text("genre"), folder: text("folder"), sourceId: text("source"),
+        ...(state && STATES.has(state) ? { state: state as ItemState | "all" } : {}),
+        ...(sort && SORTS.has(sort) ? { sort: sort as SearchQuery["sort"] } : {}),
+        limit: number("limit"), offset: number("offset"),
+      };
+      const { items, total } = index.search(query);
+      ctx.json(response, 200, { items: items.map((one) => itemView(one, ctx.canWrite)), total, limit: Math.min(500, Math.max(1, query.limit ?? 50)), offset: Math.max(0, query.offset ?? 0) });
+      return true;
+    }
+
+    const browseMatch = /^\/api\/v1\/library\/browse\/([a-z]+)$/.exec(path);
+    if (browseMatch && method === "GET") {
+      const kind = browseMatch[1]!;
+      if (!KINDS.has(kind)) return fail(404, "not_found", "browse artists, albums, genres or folders");
+      ctx.json(response, 200, index.browse(kind as Browse, { q: text("q"), limit: number("limit"), offset: number("offset") }));
+      return true;
+    }
+
+    const itemMatch = /^\/api\/v1\/library\/items\/([0-9a-f]{16})(?:\/(stream))?$/.exec(path);
+    if (itemMatch) {
+      const item = index.item(itemMatch[1]!);
+      if (!item) return fail(404, "not_found", "no such item");
+      if (itemMatch[2] === "stream") {
+        if (method !== "GET" && method !== "HEAD") return fail(405, "method_not_allowed", "GET");
+        if (item.state !== "ready") return fail(409, "not_ready", `that item is ${item.state}`);
+        const source = index.source(item.sourceId);
+        if (!source?.enabled) return fail(409, "source_disabled", "that item's source is turned off");
+        // Private: a browser may keep it, a shared cache may not.
+        ctx.sendFile(request, response, item.path, "private, max-age=3600");
+        return true;
+      }
+      if (method === "GET") {
+        ctx.json(response, 200, { item: itemView(item, ctx.canWrite) });
+        return true;
+      }
+      if (method === "PATCH") {
+        if (!needWrite()) return true;
+        const corrected = index.correct(item.id, await body());
+        if (corrected.state === "ready") ctx.retag([trackOf(corrected)]);
+        ctx.json(response, 200, { item: itemView(corrected, true) });
+        return true;
+      }
+      return fail(405, "method_not_allowed", "GET or PATCH");
+    }
+
+    return fail(404, "not_found", "nothing here");
+  } catch (error) {
+    if (error instanceof LibraryError) return fail(error.status, error.code, error.message);
+    if (error instanceof SyntaxError) return fail(400, "bad_json", "the body is not JSON");
+    return fail(500, "internal", error instanceof Error ? error.message : String(error));
+  }
+}

package/src/library-usage.ts

@@ -0,0 +1,21 @@
+/** `nixamp library` subcommands and usage, apart so help does not load the client. */
+export const LIBRARY_COMMANDS = new Set(["status", "sources", "add", "scan", "search", "show", "fix", "remove", "playlists", "playlist"]);
+
+export const LIBRARY_USAGE = `nixamp library — what this server has, indexed
+
+  nixamp library PATH                 the folder the daemon serves (set once)
+  nixamp library status               items by state, sources, last scans
+  nixamp library sources
+  nixamp library add PATH             index another folder (inside your home, not hidden)
+  nixamp library scan [SOURCE] [--force] [--wait]
+  nixamp library search WORDS [--artist A] [--album A] [--state failed] [--limit 20]
+  nixamp library show ITEM
+  nixamp library fix ITEM --title T [--artist A] [--album A] [--genre G] [--track N] [--year N]
+  nixamp library remove SOURCE        forget a folder; its files are not touched
+  nixamp library playlists
+  nixamp library playlist new NAME [ITEM...]
+  nixamp library playlist show|delete PLAYLIST
+  nixamp library playlist add PLAYLIST ITEM...
+
+  --json        machine-readable output
+  --url, --key  another server, as with \`nixamp admin\``;

package/src/library-user.ts

@@ -0,0 +1,218 @@
+/**
+ * What belongs to one listener of a library: their playlists, and where
+ * they are in what they were playing.
+ *
+ * A listener here is somebody this server can recognise next time from
+ * another device: a nixamp.com account, or the owner holding the control key
+ * (who is "owner"). Somebody with only the listen link is not anybody in
+ * particular, so they get a player and no memory, which is what the PRD means
+ * by resuming "after authentication".
+ *
+ * Playlists hold item ids, not paths: a playlist survives a rescan, and an
+ * item that went missing stays in it, shown as unavailable, until somebody
+ * takes it out. Every change bumps a revision; an edit that names an older
+ * revision is refused rather than quietly overwriting what another device
+ * just did.
+ *
+ * The queue is one per listener, written whenever playback moves on, so a
+ * phone picks up where the laptop stopped.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { LibraryError } from "./library-index.ts";
+
+export interface Playlist {
+  id: string;
+  owner: string;
+  name: string;
+  items: string[];
+  revision: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export type Repeat = "off" | "all" | "one";
+
+export interface Queue {
+  owner: string;
+  items: string[];
+  /** Index into items of what is on. */
+  at: number;
+  /** Seconds into it. */
+  position: number;
+  shuffle: boolean;
+  repeat: Repeat;
+  /** Which device moved it last, as it named itself. */
+  device: string;
+  revision: number;
+  updatedAt: number;
+}
+
+const MAX_PLAYLISTS = 500;
+const MAX_ITEMS = 10_000;
+
+export class ListenerStore {
+  private playlists = new Map<string, Playlist>();
+  private queues = new Map<string, Queue>();
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly file: string,
+    private readonly io: { read: (path: string) => string | null; write: (path: string, body: string) => void } = {
+      read: (path) => { try { return readFileSync(path, "utf8"); } catch { return null; } },
+      write: (path, body) => {
+        mkdirSync(dirname(path), { recursive: true });
+        const temporary = `${path}.${process.pid}.tmp`;
+        writeFileSync(temporary, body, { mode: 0o600 });
+        renameSync(temporary, path);
+      },
+    },
+    private readonly now: () => number = Date.now,
+  ) {
+    const body = io.read(file);
+    if (body === null) return;
+    try {
+      const parsed = JSON.parse(body) as { playlists?: Playlist[]; queues?: Queue[] };
+      for (const one of parsed.playlists ?? []) if (one?.id) this.playlists.set(one.id, one);
+      for (const one of parsed.queues ?? []) if (one?.owner) this.queues.set(one.owner, one);
+    } catch {
+      // Started over.
+    }
+  }
+
+  static fileFor(stateDir: string, port: number): string {
+    return join(stateDir, `listeners-${port}.json`);
+  }
+
+  private touch(): void {
+    if (this.timer) return;
+    this.timer = setTimeout(() => this.flush(), 1_000);
+    this.timer.unref?.();
+  }
+
+  flush(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.io.write(this.file, JSON.stringify({ version: 1, playlists: [...this.playlists.values()], queues: [...this.queues.values()] }));
+  }
+
+  playlistsOf(owner: string): Playlist[] {
+    return [...this.playlists.values()].filter((one) => one.owner === owner).sort((a, b) => a.createdAt - b.createdAt);
+  }
+
+  /** Somebody's own playlist; anybody else's is the same "not found". */
+  playlist(owner: string, id: string): Playlist {
+    const found = this.playlists.get(id);
+    if (!found || found.owner !== owner) throw new LibraryError("not_found", "no such playlist", 404);
+    return found;
+  }
+
+  private items(value: unknown, known: (id: string) => boolean): string[] {
+    if (!Array.isArray(value) || value.some((one) => typeof one !== "string")) throw new LibraryError("invalid_items", "items is a list of item ids");
+    if (value.length > MAX_ITEMS) throw new LibraryError("too_many_items", `a list holds at most ${MAX_ITEMS} items`);
+    const unknown = (value as string[]).filter((one) => !known(one));
+    if (unknown.length) throw new LibraryError("unknown_items", `${unknown.length} of those items are not in this library`);
+    return value as string[];
+  }
+
+  private name(value: unknown): string {
+    const name = typeof value === "string" ? value.trim().replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, 120) : "";
+    if (!name) throw new LibraryError("name_required", "a playlist needs a name");
+    return name;
+  }
+
+  create(owner: string, input: { name?: unknown; items?: unknown }, known: (id: string) => boolean): Playlist {
+    if (this.playlistsOf(owner).length >= MAX_PLAYLISTS) throw new LibraryError("too_many_playlists", `at most ${MAX_PLAYLISTS} playlists each`, 409);
+    const now = this.now();
+    const playlist: Playlist = {
+      id: randomBytes(8).toString("hex"),
+      owner,
+      name: this.name(input.name),
+      items: input.items === undefined ? [] : this.items(input.items, known),
+      revision: 1,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.playlists.set(playlist.id, playlist);
+    this.touch();
+    return playlist;
+  }
+
+  /** Rename, reorder or replace the items; `revision` must be the one the caller saw. */
+  update(owner: string, id: string, input: { name?: unknown; items?: unknown; revision?: unknown }, known: (id: string) => boolean): Playlist {
+    const playlist = this.playlist(owner, id);
+    if (input.revision !== undefined && input.revision !== playlist.revision) {
+      throw new LibraryError("stale_revision", `the playlist changed (revision ${playlist.revision}); fetch it and try again`, 409);
+    }
+    if (input.name !== undefined) playlist.name = this.name(input.name);
+    if (input.items !== undefined) playlist.items = this.items(input.items, known);
+    playlist.revision += 1;
+    playlist.updatedAt = this.now();
+    this.touch();
+    return playlist;
+  }
+
+  /** Items added, at the end or at a place. */
+  add(owner: string, id: string, input: { items?: unknown; at?: unknown }, known: (id: string) => boolean): Playlist {
+    const playlist = this.playlist(owner, id);
+    const added = this.items(input.items, known);
+    const at = typeof input.at === "number" && Number.isInteger(input.at) ? Math.max(0, Math.min(playlist.items.length, input.at)) : playlist.items.length;
+    if (playlist.items.length + added.length > MAX_ITEMS) throw new LibraryError("too_many_items", `a list holds at most ${MAX_ITEMS} items`);
+    playlist.items.splice(at, 0, ...added);
+    playlist.revision += 1;
+    playlist.updatedAt = this.now();
+    this.touch();
+    return playlist;
+  }
+
+  remove(owner: string, id: string): void {
+    this.playlist(owner, id);
+    this.playlists.delete(id);
+    this.touch();
+  }
+
+  queueOf(owner: string): Queue {
+    return this.queues.get(owner) ?? { owner, items: [], at: 0, position: 0, shuffle: false, repeat: "off", device: "", revision: 0, updatedAt: 0 };
+  }
+
+  /**
+   * A new queue (items given) or where playback has got to (at/position).
+   * Last writer wins for where you are -- that is what moving to another
+   * device means -- but a whole new list names the revision it replaces.
+   */
+  setQueue(owner: string, input: Record<string, unknown>, known: (id: string) => boolean): Queue {
+    const queue = { ...this.queueOf(owner) };
+    if (input["items"] !== undefined) {
+      if (input["revision"] !== undefined && input["revision"] !== queue.revision) {
+        throw new LibraryError("stale_revision", `the queue changed on another device (revision ${queue.revision})`, 409);
+      }
+      queue.items = this.items(input["items"], known);
+      queue.at = 0;
+      queue.position = 0;
+    }
+    if (input["at"] !== undefined) {
+      if (!Number.isInteger(input["at"]) || (input["at"] as number) < 0 || (input["at"] as number) >= Math.max(1, queue.items.length)) {
+        throw new LibraryError("invalid_value", "at is a place in the queue");
+      }
+      queue.at = input["at"] as number;
+      if (input["position"] === undefined) queue.position = 0;
+    }
+    if (input["position"] !== undefined) {
+      const position = Number(input["position"]);
+      if (!Number.isFinite(position) || position < 0) throw new LibraryError("invalid_value", "position is seconds into the item");
+      queue.position = Math.round(position * 10) / 10;
+    }
+    if (input["shuffle"] !== undefined) queue.shuffle = input["shuffle"] === true;
+    if (input["repeat"] !== undefined) {
+      if (!["off", "all", "one"].includes(String(input["repeat"]))) throw new LibraryError("invalid_value", "repeat is off, all or one");
+      queue.repeat = input["repeat"] as Repeat;
+    }
+    if (typeof input["device"] === "string") queue.device = input["device"].slice(0, 80);
+    queue.revision += 1;
+    queue.updatedAt = this.now();
+    this.queues.set(owner, queue);
+    this.touch();
+    return queue;
+  }
+}