nixamp 0.30.3 → 0.33.0

package/dist/station-mcp.js

@@ -26,7 +26,7 @@ export const STATION_TOOLS = [
     },
     {
         name: "station_create",
-        description: "Make a station from a folder in the library (path relative to it, \"\" for all of it) or from track indexes. It starts private and stopped; nothing is published.",
+        description: "Make a station from a folder in the library (path relative to it, \"\" for all of it), a playlist, or track indexes. It starts private and stopped; nothing is published.",
         inputSchema: {
             type: "object",
             properties: {
@@ -34,6 +34,7 @@ export const STATION_TOOLS = [
                 name: STRING,
                 folder: { ...STRING, description: "A folder under the library, e.g. \"Albums/Late Night\"." },
                 items: { type: "array", items: { type: "integer" }, description: "Track indexes, as /api/state lists them." },
+                playlist: { ...STRING, description: "A playlist id (playlist_list): the station plays its ready items in order." },
                 description: STRING,
                 shuffle: { type: "boolean" },
                 repeat: { type: "boolean", description: "Round and round (default) or once." },
@@ -84,6 +85,24 @@ export const STATION_TOOLS = [
     },
 ];
 const say = (value, isError = false) => ({ content: [{ type: "text", text: value }], ...(isError ? { isError: true } : {}) });
+/** Where to send a tool's request, and with which credential. */
+export function connect(args, options) {
+    const server = typeof args["server"] === "string" ? args["server"].replace(/\/+$/, "") : "";
+    const headers = { "content-type": "application/json" };
+    if (server === "") {
+        const local = options.local === undefined ? (() => { const state = readState(); return state ? { url: daemonUrl(state), key: state.key } : null; })() : options.local;
+        if (!local)
+            return { error: "No nixamp daemon runs on this machine. Start one (nixamp daemon start ~/Music) or pass `server`." };
+        if (local.key)
+            headers[KEY_HEADER] = local.key;
+        return { base: local.url, headers };
+    }
+    const session = options.session === undefined ? readSession() : options.session;
+    if (!session)
+        return { error: "Another server needs this machine signed in as its owner: nixamp login." };
+    headers["authorization"] = `Bearer ${session.token}`;
+    return { base: server, headers };
+}
 export function isStationTool(name) {
     return STATION_TOOLS.some((tool) => tool.name === name);
 }
@@ -95,23 +114,10 @@ function line(station) {
 }
 export async function callStationTool(name, args, options = {}) {
     const send = options.fetcher ?? fetch;
-    const server = typeof args["server"] === "string" ? args["server"].replace(/\/+$/, "") : "";
-    let base = server;
-    const headers = { "content-type": "application/json" };
-    if (server === "") {
-        const local = options.local === undefined ? (() => { const state = readState(); return state ? { url: daemonUrl(state), key: state.key } : null; })() : options.local;
-        if (!local)
-            return say("No nixamp daemon runs on this machine. Start one (nixamp daemon start ~/Music) or pass `server`.", true);
-        base = local.url;
-        if (local.key)
-            headers[KEY_HEADER] = local.key;
-    }
-    else {
-        const session = options.session === undefined ? readSession() : options.session;
-        if (!session)
-            return say("Another server's stations need this machine signed in as its owner: nixamp login.", true);
-        headers["authorization"] = `Bearer ${session.token}`;
-    }
+    const target = connect(args, options);
+    if ("error" in target)
+        return say(target.error, true);
+    const { base, headers } = target;
     const id = typeof args["id"] === "string" ? args["id"] : "";
     const call = async (method, path, body) => {
         const response = await send(`${base}${path}`, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
@@ -135,7 +141,7 @@ export async function callStationTool(name, args, options = {}) {
             return answer.ok ? say(JSON.stringify(answer.body["station"], null, 2)) : refused(answer.body);
         }
         if (name === "station_create") {
-            const answer = await call("POST", "/api/v1/stations", pick(["name", "folder", "items", "description", "shuffle", "repeat", "bitrate", "idempotencyKey"]));
+            const answer = await call("POST", "/api/v1/stations", pick(["name", "folder", "items", "playlist", "description", "shuffle", "repeat", "bitrate", "idempotencyKey"]));
             return answer.ok ? say(`Made, private and stopped: ${line(answer.body["station"])}`) : refused(answer.body);
         }
         if (name === "station_update") {

package/dist/station-page.d.ts

@@ -1,5 +1,5 @@
 /** A station page's path: /station/<id>. */
 export declare const STATION_PAGE: RegExp;
-export declare const STATION_PAGE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<meta name=\"robots\" content=\"noindex\">\n<link rel=\"icon\" href=\"data:,\">\n<title>Station \u00B7 nixamp</title>\n<style>\n:root{--bg:#f6f5f2;--fg:#17171a;--muted:#5d5d66;--card:#fff;--line:#dedcd6;--accent:#1f6feb;--live:#0b7a3b;--warn:#9a6700;--off:#8c2f39}\n@media (prefers-color-scheme:dark){:root{--bg:#121214;--fg:#ececf1;--muted:#a4a4b0;--card:#1c1c20;--line:#2c2c33;--accent:#6aa7ff;--live:#3fbf7f;--warn:#e3b341;--off:#f0838f}}\n*{box-sizing:border-box}html,body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,-apple-system,\"Segoe UI\",sans-serif}\nmain{max-width:560px;margin:0 auto;padding:48px 16px}\n.card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:24px}\nh1{font-size:1.6rem;line-height:1.2;margin:0 0 4px}\n.about{color:var(--muted);margin:0 0 20px}\n.chip{display:inline-flex;align-items:center;gap:8px;font-size:.85rem;font-weight:600;padding:4px 10px;border-radius:999px;border:1px solid var(--line)}\n.chip::before{content:\"\";width:8px;height:8px;border-radius:50%;background:currentColor}\n.live{color:var(--live)}.reconnecting{color:var(--warn)}.unavailable,.stopped{color:var(--off)}\n.now{margin:20px 0;min-height:3em}.now .title{font-weight:600}.now .by{color:var(--muted)}\n.controls{display:flex;align-items:center;gap:16px;flex-wrap:wrap}\nbutton{font:inherit;font-weight:600;border:0;border-radius:999px;padding:12px 28px;background:var(--accent);color:#fff;cursor:pointer;min-width:120px}\nbutton:disabled{opacity:.5;cursor:not-allowed}\nbutton:focus-visible,input:focus-visible,a:focus-visible{outline:3px solid var(--accent);outline-offset:3px}\nlabel{display:flex;align-items:center;gap:8px;color:var(--muted);font-size:.9rem}\ninput[type=range]{width:120px;accent-color:var(--accent)}\n.small{margin-top:20px;font-size:.85rem;color:var(--muted)}.small a{color:inherit}\n.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}\n@media (prefers-reduced-motion:no-preference){.live::before{animation:pulse 2s ease-in-out infinite}}\n@keyframes pulse{50%{opacity:.35}}\n</style>\n</head>\n<body>\n<main>\n  <div class=\"card\">\n    <span id=\"state\" class=\"chip unavailable\" role=\"status\">Loading</span>\n    <h1 id=\"name\">&nbsp;</h1>\n    <p id=\"about\" class=\"about\" hidden></p>\n    <div class=\"now\" aria-live=\"polite\"><div id=\"title\" class=\"title\"></div><div id=\"by\" class=\"by\"></div></div>\n    <div class=\"controls\">\n      <button id=\"play\" type=\"button\" aria-pressed=\"false\" disabled>Play</button>\n      <label>Volume <input id=\"volume\" type=\"range\" min=\"0\" max=\"1\" step=\"0.05\" value=\"1\"></label>\n    </div>\n    <p class=\"small\"><a id=\"m3u\" href=\"#\">Open in another player (.m3u)</a> \u00B7 Pausing here does not pause the station.</p>\n  </div>\n  <p class=\"small\">Played by <a href=\"https://nixamp.com\">nixamp</a>.</p>\n  <div id=\"announce\" class=\"sr\" aria-live=\"assertive\"></div>\n</main>\n<script>\n(() => {\n  const id = location.pathname.split(\"/\").filter(Boolean)[1] || \"\";\n  const token = new URLSearchParams(location.search).get(\"t\") || \"\";\n  const q = \"?t=\" + encodeURIComponent(token);\n  const api = \"/api/v1/stations/\" + encodeURIComponent(id);\n  const $ = (s) => document.querySelector(s);\n  const audio = new Audio();\n  audio.preload = \"none\";\n  let wanted = false, retry = 0, timer = 0, last = null;\n  const chip = (state, text) => { const c = $(\"#state\"); c.className = \"chip \" + state; c.textContent = text; };\n  const say = (text) => { $(\"#announce\").textContent = text; };\n  const draw = (s) => {\n    last = s;\n    document.title = s.name + \" \u00B7 nixamp\";\n    $(\"#name\").textContent = s.name;\n    $(\"#about\").textContent = s.description || \"\";\n    $(\"#about\").hidden = !s.description;\n    const playing = s.nowPlaying;\n    $(\"#title\").textContent = playing ? (playing.title || \"Untitled\") : (s.state === \"live\" ? \"On the air\" : \"\");\n    $(\"#by\").textContent = playing ? [playing.artist, playing.album].filter(Boolean).join(\" \u00B7 \") : \"\";\n    if (wanted && retry > 0) chip(\"reconnecting\", \"Reconnecting\");\n    else if (s.state === \"live\") chip(\"live\", \"Live\");\n    else if (s.state === \"starting\" || s.state === \"recovering\") chip(\"reconnecting\", \"Coming back\");\n    else if (s.state === \"stopped\") chip(\"stopped\", \"Off the air\");\n    else chip(\"unavailable\", \"Unavailable\");\n    $(\"#play\").disabled = !(s.state === \"live\" || s.state === \"recovering\" || s.state === \"starting\");\n    $(\"#m3u\").href = api + \"/listen.m3u\" + q;\n  };\n  const poll = async () => {\n    try {\n      const r = await fetch(api + \"/state\" + q, { cache: \"no-store\" });\n      if (r.status === 404) { $(\"#name\").textContent = \"This station is not available\"; chip(\"unavailable\", \"Unavailable\"); $(\"#play\").disabled = true; stop(); return; }\n      if (r.ok) draw(await r.json());\n    } catch {}\n  };\n  // Always the live edge: a fresh request, never a cached or paused one.\n  const join = () => { audio.src = api + \"/stream\" + q + \"&n=\" + Date.now(); audio.play().catch(() => { wanted = false; button(); }); };\n  const stop = () => { wanted = false; clearTimeout(timer); audio.pause(); audio.removeAttribute(\"src\"); audio.load(); button(); };\n  const button = () => { const b = $(\"#play\"); b.textContent = wanted ? \"Stop\" : \"Play\"; b.setAttribute(\"aria-pressed\", String(wanted)); };\n  const again = () => {\n    if (!wanted) return;\n    retry += 1;\n    if (last) draw(last);\n    clearTimeout(timer);\n    timer = setTimeout(join, Math.min(15000, 1000 * 2 ** Math.min(retry, 4)));\n  };\n  audio.addEventListener(\"playing\", () => { if (retry) say(\"Back on\"); retry = 0; if (last) draw(last); });\n  audio.addEventListener(\"error\", again);\n  audio.addEventListener(\"ended\", again);\n  audio.addEventListener(\"stalled\", () => { if (wanted && audio.readyState < 3) again(); });\n  $(\"#play\").addEventListener(\"click\", () => { if (wanted) { stop(); say(\"Stopped\"); } else { wanted = true; retry = 0; button(); join(); say(\"Playing\"); } });\n  $(\"#volume\").addEventListener(\"input\", (e) => { audio.volume = Number(e.target.value); });\n  poll();\n  setInterval(poll, 5000);\n})();\n</script>\n</body>\n</html>\n";
+export declare const STATION_PAGE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<meta name=\"robots\" content=\"noindex\">\n<link rel=\"icon\" href=\"data:,\">\n<title>Station \u00B7 nixamp</title>\n<style>\n:root{--bg:#f6f5f2;--fg:#17171a;--muted:#5d5d66;--card:#fff;--line:#dedcd6;--accent:#1f6feb;--live:#0b7a3b;--warn:#9a6700;--off:#8c2f39}\n@media (prefers-color-scheme:dark){:root{--bg:#121214;--fg:#ececf1;--muted:#a4a4b0;--card:#1c1c20;--line:#2c2c33;--accent:#6aa7ff;--live:#3fbf7f;--warn:#e3b341;--off:#f0838f}}\n*{box-sizing:border-box}html,body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,-apple-system,\"Segoe UI\",sans-serif}\nmain{max-width:560px;margin:0 auto;padding:48px 16px}\n.card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:24px}\nh1{font-size:1.6rem;line-height:1.2;margin:0 0 4px}\n.about{color:var(--muted);margin:0 0 20px}\n.chip{display:inline-flex;align-items:center;gap:8px;font-size:.85rem;font-weight:600;padding:4px 10px;border-radius:999px;border:1px solid var(--line)}\n.chip::before{content:\"\";width:8px;height:8px;border-radius:50%;background:currentColor}\n.live{color:var(--live)}.reconnecting{color:var(--warn)}.unavailable,.stopped{color:var(--off)}\n.now{margin:20px 0;min-height:3em}.now .title{font-weight:600}.now .by{color:var(--muted)}\n.controls{display:flex;align-items:center;gap:16px;flex-wrap:wrap}\nbutton{font:inherit;font-weight:600;border:0;border-radius:999px;padding:12px 28px;background:var(--accent);color:#fff;cursor:pointer;min-width:120px}\nbutton:disabled{opacity:.5;cursor:not-allowed}\nbutton:focus-visible,input:focus-visible,a:focus-visible{outline:3px solid var(--accent);outline-offset:3px}\nlabel{display:flex;align-items:center;gap:8px;color:var(--muted);font-size:.9rem}\ninput[type=range]{width:120px;accent-color:var(--accent)}\n.small{margin-top:20px;font-size:.85rem;color:var(--muted)}.small a{color:inherit}\n.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}\n@media (prefers-reduced-motion:no-preference){.live::before{animation:pulse 2s ease-in-out infinite}}\n@keyframes pulse{50%{opacity:.35}}\n</style>\n</head>\n<body>\n<main>\n  <div class=\"card\">\n    <span id=\"state\" class=\"chip unavailable\" role=\"status\">Loading</span>\n    <h1 id=\"name\">&nbsp;</h1>\n    <p id=\"about\" class=\"about\" hidden></p>\n    <div class=\"now\" aria-live=\"polite\"><div id=\"title\" class=\"title\"></div><div id=\"by\" class=\"by\"></div></div>\n    <div class=\"controls\">\n      <button id=\"play\" type=\"button\" aria-pressed=\"false\" disabled>Play</button>\n      <label>Volume <input id=\"volume\" type=\"range\" min=\"0\" max=\"1\" step=\"0.05\" value=\"1\"></label>\n    </div>\n    <p class=\"small\"><a id=\"m3u\" href=\"#\">Open in another player (.m3u)</a> \u00B7 Pausing here does not pause the station.</p>\n  </div>\n  <p class=\"small\">Played by <a href=\"https://nixamp.com\">nixamp</a>.</p>\n  <div id=\"announce\" class=\"sr\" aria-live=\"assertive\"></div>\n</main>\n<script>\n(() => {\n  const id = location.pathname.split(\"/\").filter(Boolean)[1] || \"\";\n  const token = new URLSearchParams(location.search).get(\"t\") || \"\";\n  const q = \"?t=\" + encodeURIComponent(token);\n  const api = \"/api/v1/stations/\" + encodeURIComponent(id);\n  const $ = (s) => document.querySelector(s);\n  const audio = new Audio();\n  audio.preload = \"none\";\n  let wanted = false, retry = 0, timer = 0, last = null, live = false;\n  const chip = (state, text) => { const c = $(\"#state\"); c.className = \"chip \" + state; c.textContent = text; };\n  const say = (text) => { $(\"#announce\").textContent = text; };\n  const draw = (s) => {\n    last = s;\n    document.title = s.name + \" \u00B7 nixamp\";\n    $(\"#name\").textContent = s.name;\n    $(\"#about\").textContent = s.description || \"\";\n    $(\"#about\").hidden = !s.description;\n    if (!live) title(s);\n    if (wanted && retry > 0) chip(\"reconnecting\", \"Reconnecting\");\n    else if (s.state === \"live\") chip(\"live\", \"Live\");\n    else if (s.state === \"starting\" || s.state === \"recovering\") chip(\"reconnecting\", \"Coming back\");\n    else if (s.state === \"stopped\") chip(\"stopped\", \"Off the air\");\n    else chip(\"unavailable\", \"Unavailable\");\n    $(\"#play\").disabled = !(s.state === \"live\" || s.state === \"recovering\" || s.state === \"starting\");\n    $(\"#m3u\").href = api + \"/listen.m3u\" + q;\n  };\n  const title = (s) => {\n    const playing = s.nowPlaying;\n    $(\"#title\").textContent = playing ? (playing.title || \"Untitled\") : (s.state === \"live\" ? \"On the air\" : \"\");\n    $(\"#by\").textContent = playing ? [playing.artist, playing.album].filter(Boolean).join(\" \u00B7 \") : \"\";\n  };\n  // What is ahead of the speaker: the sound the player holds and has not\n  // played yet. A new title waits that long, so it changes with the song.\n  const ahead = () => {\n    if (!wanted || audio.paused || audio.buffered.length === 0) return 0;\n    return Math.max(0, Math.min(30, audio.buffered.end(audio.buffered.length - 1) - audio.currentTime));\n  };\n  const listen = () => {\n    if (!window.EventSource) return;\n    const events = new EventSource(api + \"/events\" + q);\n    events.addEventListener(\"hello\", (e) => { live = true; title(JSON.parse(e.data)); });\n    events.addEventListener(\"now\", (e) => {\n      const s = JSON.parse(e.data);\n      setTimeout(() => { title(s); say(s.nowPlaying ? \"Now playing \" + (s.nowPlaying.title || \"\") : \"\"); }, ahead() * 1000);\n    });\n    events.addEventListener(\"state\", () => poll());\n    events.onerror = () => { live = false; };\n  };\n  const poll = async () => {\n    try {\n      const r = await fetch(api + \"/state\" + q, { cache: \"no-store\" });\n      if (r.status === 404) { $(\"#name\").textContent = \"This station is not available\"; chip(\"unavailable\", \"Unavailable\"); $(\"#play\").disabled = true; stop(); return; }\n      if (r.ok) draw(await r.json());\n    } catch {}\n  };\n  // Always the live edge: a fresh request, never a cached or paused one.\n  const join = () => { audio.src = api + \"/stream\" + q + \"&n=\" + Date.now(); audio.play().catch(() => { wanted = false; button(); }); };\n  const stop = () => { wanted = false; clearTimeout(timer); audio.pause(); audio.removeAttribute(\"src\"); audio.load(); button(); };\n  const button = () => { const b = $(\"#play\"); b.textContent = wanted ? \"Stop\" : \"Play\"; b.setAttribute(\"aria-pressed\", String(wanted)); };\n  const again = () => {\n    if (!wanted) return;\n    retry += 1;\n    if (last) draw(last);\n    clearTimeout(timer);\n    timer = setTimeout(join, Math.min(15000, 1000 * 2 ** Math.min(retry, 4)));\n  };\n  audio.addEventListener(\"playing\", () => { if (retry) say(\"Back on\"); retry = 0; if (last) draw(last); });\n  audio.addEventListener(\"error\", again);\n  audio.addEventListener(\"ended\", again);\n  audio.addEventListener(\"stalled\", () => { if (wanted && audio.readyState < 3) again(); });\n  $(\"#play\").addEventListener(\"click\", () => { if (wanted) { stop(); say(\"Stopped\"); } else { wanted = true; retry = 0; button(); join(); say(\"Playing\"); } });\n  $(\"#volume\").addEventListener(\"input\", (e) => { audio.volume = Number(e.target.value); });\n  poll();\n  listen();\n  setInterval(poll, 5000);\n})();\n</script>\n</body>\n</html>\n";
 /** Only its own script and style, only its own server, never framed. */
 export declare const STATION_PAGE_CSP: string;

package/dist/station-page.js

@@ -42,7 +42,7 @@ const SCRIPT = `
   const $ = (s) => document.querySelector(s);
   const audio = new Audio();
   audio.preload = "none";
-  let wanted = false, retry = 0, timer = 0, last = null;
+  let wanted = false, retry = 0, timer = 0, last = null, live = false;
   const chip = (state, text) => { const c = $("#state"); c.className = "chip " + state; c.textContent = text; };
   const say = (text) => { $("#announce").textContent = text; };
   const draw = (s) => {
@@ -51,9 +51,7 @@ const SCRIPT = `
     $("#name").textContent = s.name;
     $("#about").textContent = s.description || "";
     $("#about").hidden = !s.description;
-    const playing = s.nowPlaying;
-    $("#title").textContent = playing ? (playing.title || "Untitled") : (s.state === "live" ? "On the air" : "");
-    $("#by").textContent = playing ? [playing.artist, playing.album].filter(Boolean).join(" · ") : "";
+    if (!live) title(s);
     if (wanted && retry > 0) chip("reconnecting", "Reconnecting");
     else if (s.state === "live") chip("live", "Live");
     else if (s.state === "starting" || s.state === "recovering") chip("reconnecting", "Coming back");
@@ -62,6 +60,28 @@ const SCRIPT = `
     $("#play").disabled = !(s.state === "live" || s.state === "recovering" || s.state === "starting");
     $("#m3u").href = api + "/listen.m3u" + q;
   };
+  const title = (s) => {
+    const playing = s.nowPlaying;
+    $("#title").textContent = playing ? (playing.title || "Untitled") : (s.state === "live" ? "On the air" : "");
+    $("#by").textContent = playing ? [playing.artist, playing.album].filter(Boolean).join(" · ") : "";
+  };
+  // What is ahead of the speaker: the sound the player holds and has not
+  // played yet. A new title waits that long, so it changes with the song.
+  const ahead = () => {
+    if (!wanted || audio.paused || audio.buffered.length === 0) return 0;
+    return Math.max(0, Math.min(30, audio.buffered.end(audio.buffered.length - 1) - audio.currentTime));
+  };
+  const listen = () => {
+    if (!window.EventSource) return;
+    const events = new EventSource(api + "/events" + q);
+    events.addEventListener("hello", (e) => { live = true; title(JSON.parse(e.data)); });
+    events.addEventListener("now", (e) => {
+      const s = JSON.parse(e.data);
+      setTimeout(() => { title(s); say(s.nowPlaying ? "Now playing " + (s.nowPlaying.title || "") : ""); }, ahead() * 1000);
+    });
+    events.addEventListener("state", () => poll());
+    events.onerror = () => { live = false; };
+  };
   const poll = async () => {
     try {
       const r = await fetch(api + "/state" + q, { cache: "no-store" });
@@ -87,6 +107,7 @@ const SCRIPT = `
   $("#play").addEventListener("click", () => { if (wanted) { stop(); say("Stopped"); } else { wanted = true; retry = 0; button(); join(); say("Playing"); } });
   $("#volume").addEventListener("input", (e) => { audio.volume = Number(e.target.value); });
   poll();
+  listen();
   setInterval(poll, 5000);
 })();
 `;

package/dist/station-routes.js

@@ -1,6 +1,6 @@
 import { StationError, channelOf, tokensMatch, } from "./stations.js";
 /** The three things a station's link opens. */
-const LISTEN = /^\/api\/v1\/stations\/([a-z0-9]{10})\/(stream|state|listen\.m3u)$/;
+const LISTEN = /^\/api\/v1\/stations\/([a-z0-9]{10})\/(stream|state|listen\.m3u|events)$/;
 /** Whether this path is one a station's own link may open, without the server's key. */
 export function isStationListenPath(path) {
     return LISTEN.test(path);
@@ -80,6 +80,59 @@ export async function handleStations(request, response, path, url, ctx) {
             return true;
         }
         const what = listen[2];
+        if (what === "events") {
+            // Now playing as it changes, for a player to show when its own sound
+            // gets there: each "now" is sent when the station's encoder moves on to
+            // the next file, and a listener is behind that by its own buffer.
+            response.writeHead(200, {
+                ...ctx.headers,
+                "content-type": "text/event-stream; charset=utf-8",
+                "cache-control": "no-store",
+                connection: "keep-alive",
+                "x-accel-buffering": "no",
+            });
+            let instance = 0;
+            let lastFile = nowPlayingFile(ctx, station);
+            let lastState = ctx.runner.observed(station.id);
+            const send = (event, data) => {
+                response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+            };
+            const now = () => {
+                const view = publicView(ctx, station);
+                return { station: station.id, playback: `${station.id}:${ctx.channels.info(channelOf(station.id))?.startedAt ?? 0}`, track: `${station.id}:${instance}`, at: Date.now(), state: view.state, nowPlaying: view.nowPlaying };
+            };
+            send("hello", now());
+            const tick = setInterval(() => {
+                const current = ctx.store.get(station.id);
+                if (!current) {
+                    response.end();
+                    return;
+                }
+                const file = nowPlayingFile(ctx, current);
+                const state = ctx.runner.observed(current.id);
+                if (file !== lastFile) {
+                    lastFile = file;
+                    instance += 1;
+                    send("now", now());
+                }
+                else if (state !== lastState) {
+                    send("state", now());
+                }
+                lastState = state;
+            }, 500);
+            tick.unref?.();
+            const beat = setInterval(() => response.write(": beat\n\n"), 20_000);
+            beat.unref?.();
+            const untrack = ctx.runner.track(station.id, { end: () => response.end() });
+            const leave = () => {
+                clearInterval(tick);
+                clearInterval(beat);
+                untrack();
+            };
+            request.on("close", leave);
+            response.on("close", leave);
+            return true;
+        }
         if (what === "state") {
             ctx.json(response, 200, publicView(ctx, station));
             return true;

package/dist/station-usage.d.ts

@@ -1,2 +1,2 @@
 /** `nixamp station` usage, apart so `nixamp help station` does not load the client. */
-export declare const USAGE = "nixamp station \u2014 make a collection into a station\n\n  nixamp station list\n  nixamp station create --name NAME (--folder PATH | --items 0,1,2) [--shuffle] [--no-repeat] [--bitrate 128]\n  nixamp station show ID\n  nixamp station status ID\n  nixamp station start ID\n  nixamp station stop ID\n  nixamp station skip ID\n  nixamp station retry ID          try every left-out file again\n  nixamp station publish ID --basis owned|permission|licensed|public-domain [--note TEXT] [--unlisted] [--no-list]\n  nixamp station unpublish ID [--private]\n  nixamp station link ID [--rotate]\n  nixamp station delete ID\n\n  --json        machine-readable output\n  --url, --key  another server, as with `nixamp admin`\n\nA new station is private and stopped. Starting it does not publish it.";
+export declare const USAGE = "nixamp station \u2014 make a collection into a station\n\n  nixamp station list\n  nixamp station create --name NAME (--folder PATH | --playlist ID | --items 0,1,2) [--shuffle] [--no-repeat] [--bitrate 128]\n  nixamp station show ID\n  nixamp station status ID\n  nixamp station start ID\n  nixamp station stop ID\n  nixamp station skip ID\n  nixamp station retry ID          try every left-out file again\n  nixamp station publish ID --basis owned|permission|licensed|public-domain [--note TEXT] [--unlisted] [--no-list]\n  nixamp station unpublish ID [--private]\n  nixamp station link ID [--rotate]\n  nixamp station delete ID\n\n  --json        machine-readable output\n  --url, --key  another server, as with `nixamp admin`\n\nA new station is private and stopped. Starting it does not publish it.";

package/dist/station-usage.js

@@ -2,7 +2,7 @@
 export const USAGE = `nixamp station — make a collection into a station
 
   nixamp station list
-  nixamp station create --name NAME (--folder PATH | --items 0,1,2) [--shuffle] [--no-repeat] [--bitrate 128]
+  nixamp station create --name NAME (--folder PATH | --playlist ID | --items 0,1,2) [--shuffle] [--no-repeat] [--bitrate 128]
   nixamp station show ID
   nixamp station status ID
   nixamp station start ID

package/package.json

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

package/src/channels.ts

@@ -295,9 +295,28 @@ export class Channel {
   /** The list being played entry by entry, when it is one; what skip() moves on. */
   private playlistInput: PlaylistInputStream | null = null;
 
-  /** On to the next entry of a list of files. False when this is not one. */
+  /**
+   * On to the entry after the one listeners hear now. False when this is
+   * not a list of files.
+   *
+   * The list's decoder runs ahead of the speaker by whatever the pipes hold,
+   * so ending the entry it is decoding would skip the wrong song -- usually
+   * the next one, while this one plays on. Instead the channel is dialled
+   * again from the next entry, which also drops what was read ahead. Not a
+   * failure, so it does not count as a redial.
+   */
   skip(): boolean {
-    return this.playlistInput?.skip() ?? false;
+    const list = this.info.playlist;
+    if (!this.playlistInput || !list?.length) return false;
+    const redials = this.info.redials;
+    this.info.playlistAt = ((this.info.playlistAt ?? 0) + 1) % list.length;
+    this.info.position = 0;
+    // MP3 frames carry on into the same connections, as a list advancing
+    // does; a picture needs a fresh start, and the player rejoins on its own.
+    const done = this.restart(this.info.kind === "audio");
+    if (redials === undefined) delete this.info.redials;
+    else this.info.redials = redials;
+    return done;
   }
 
   /** An entry's tags, as read when it was put on. */
@@ -635,7 +654,7 @@ export class Channel {
    * decided the thing is worth another go, and should not inherit the four
    * strikes a dead CDN ran up an hour ago.
    */
-  restart(): boolean {
+  restart(preserveListeners = false): boolean {
     if (this.closing) return false;
     // Started over from the outro: the show itself, from its beginning.
     if (this.outroOn && this.dialed) {
@@ -666,7 +685,7 @@ export class Channel {
     const old = this.child;
     this.child = null;
     old?.kill("SIGKILL");
-    this.startOver();
+    this.startOver(preserveListeners);
     dial();
     return true;
   }

package/src/library-cli.ts

@@ -0,0 +1,175 @@
+/**
+ * `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.ts";
+import { KEY_HEADER } from "./share.ts";
+
+import { LIBRARY_COMMANDS, LIBRARY_USAGE } from "./library-usage.ts";
+
+export { LIBRARY_COMMANDS, LIBRARY_USAGE };
+
+function flag(argv: string[], name: string): string | undefined {
+  const at = argv.indexOf(name);
+  return at === -1 ? undefined : argv[at + 1];
+}
+
+/** Words that are not flags or flag values. */
+function words(argv: string[]): string[] {
+  const out: string[] = [];
+  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: string[]): Promise<number> {
+  const [command] = argv;
+  const json = argv.includes("--json");
+  let target;
+  try {
+    target = resolveTarget(argv);
+  } catch (error) {
+    console.error((error as Error).message);
+    return 3;
+  }
+  const headers: Record<string, string> = { "content-type": "application/json", ...(target.key ? { [KEY_HEADER]: target.key } : {}) };
+  const call = async (method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> }> => {
+    let response: 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 as Error).message}`), { unreachable: true });
+    }
+    const parsed = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+    return { status: response.status, body: parsed };
+  };
+  const out = (answer: { status: number; body: Record<string, unknown> }, line: (body: Record<string, unknown>) => string): number => {
+    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: Record<string, unknown> | null | undefined): string =>
+    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: Record<string, unknown>): string =>
+    `${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"] as Record<string, number>;
+          const sources = (body["sources"] as Record<string, unknown>[]) ?? [];
+          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"] as Record<string, unknown> | null)}`),
+          ].join("\n");
+        });
+      case "sources":
+        return out(await call("GET", "/api/v1/library/sources"), (body) =>
+          ((body["sources"] as Record<string, unknown>[]) ?? []).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"] as Record<string, unknown>)["root"])} as ${String((body["source"] as Record<string, unknown>)["id"])}.`);
+      }
+      case "scan": {
+        let [source] = rest;
+        if (!source) {
+          const listed = await call("GET", "/api/v1/library/sources");
+          const all = (listed.body["sources"] as Record<string, unknown>[]) ?? [];
+          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"] as Record<string, unknown>)["jobId"])}.`);
+        const jobId = String((started.body["job"] as Record<string, unknown>)["jobId"]);
+        for (;;) {
+          const polled = await call("GET", `/api/v1/library/jobs/${jobId}`);
+          const job = polled.body["job"] as Record<string, unknown> | undefined;
+          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"] as Record<string, unknown>[]) ?? [];
+          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: Record<string, unknown> = {};
+        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"] as Record<string, unknown>));
+      }
+      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"] as Record<string, unknown>[]) ?? []).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: Record<string, unknown>): string => {
+          const list = body["playlist"] as Record<string, unknown>;
+          const items = (list["items"] as Record<string, unknown>[] | undefined) ?? [];
+          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 as { unreachable?: boolean }).unreachable) {
+      console.error(`nixamp: ${(error as Error).message}`);
+      return 3;
+    }
+    throw error;
+  }
+}