nixamp 0.32.0 → 0.34.0

package/dist/owner.js

@@ -52,7 +52,10 @@ export class Owner {
                 return "";
             }
             const body = (await answer.json());
-            const id = typeof body.account?.id === "string" ? body.account.id : "";
+            // A token some app holds for the person counts here only if they gave
+            // that app the stations scope; otherwise it is not them at this door.
+            const scoped = body.grant === undefined || (Array.isArray(body.grant.scope) && body.grant.scope.includes("stations"));
+            const id = scoped && typeof body.account?.id === "string" ? body.account.id : "";
             this.cache.set(token, { id, at: now });
             return id;
         }

package/dist/server.d.ts

@@ -23,6 +23,7 @@ import { PartyLine } from "./partyline.ts";
 import { HlsPackagers } from "./hls.ts";
 import { LibraryIndex, type Probed } from "./library-index.ts";
 import { ListenerStore } from "./library-user.ts";
+import { Importer } from "./handoff.ts";
 import { StationRunner } from "./station-runner.ts";
 import { StationStore } from "./stations.ts";
 import { CompressionService } from "./compression/service.ts";
@@ -575,6 +576,8 @@ export interface HandlerOptions {
         retag: (tracks: Track[]) => void;
         listeners?: ListenerStore;
     };
+    /** Music handed over from BitTorrented. */
+    importer?: Importer;
     /** This server's stations and what keeps them on the air. */
     stations?: {
         store: StationStore;

package/dist/server.js

@@ -58,6 +58,8 @@ import { handleStations, isStationListenPath } from "./station-routes.js";
 import { handleLibrary } from "./library-routes.js";
 import { LibraryIndex, probeItem, trackOf } from "./library-index.js";
 import { ListenerStore } from "./library-user.js";
+import { Importer } from "./handoff.js";
+import { handleHandoffs } from "./handoff-routes.js";
 import { STATION_PAGE, STATION_PAGE_CSP, STATION_PAGE_HTML } from "./station-page.js";
 import { StationRunner } from "./station-runner.js";
 import { StationError, StationStore, stationOfChannel } from "./stations.js";
@@ -2227,6 +2229,17 @@ export function createHandler(engine, options) {
             });
             return;
         }
+        if (options.importer && path.startsWith("/api/v1/integrations/bittorrented/")) {
+            const control = await controlOf();
+            await handleHandoffs(request, response, path, {
+                importer: options.importer,
+                canWrite: control.allowed,
+                owner: control.account || "owner",
+                json,
+                readBody,
+            });
+            return;
+        }
         if (options.stations && (path === "/api/v1/stations" || path.startsWith("/api/v1/stations/"))) {
             const control = await controlOf();
             const encrypted = request.socket.encrypted === true;
@@ -2343,12 +2356,17 @@ export function createHandler(engine, options) {
                 return;
             }
             if (path === "/api/v1/auth/me") {
-                const who = await accounts.whoIs(tokenFrom(request.headers));
+                const token = tokenFrom(request.headers);
+                const who = await accounts.whoIs(token);
                 if (who === null) {
                     json(response, 401, { error: "not signed in" });
                     return;
                 }
-                json(response, 200, { account: who });
+                // An app acting for the person says so, with what it was allowed:
+                // a server asking "is this my owner?" must not take a token handed to
+                // some other app as the owner themselves.
+                const grant = options.authServer ? await options.authServer.grantFor(token) : null;
+                json(response, 200, { account: who, ...(grant ? { grant: { clientId: grant.clientId, scope: grant.scope } } : {}) });
                 return;
             }
             /**
@@ -3599,11 +3617,28 @@ export function createHandler(engine, options) {
         // point: a share link in a terminal you closed is a server you have lost.
         if ((path === "/api/v1/servers" || path.startsWith("/api/v1/servers/")) && options.servers && options.accounts) {
             const servers = options.servers;
-            const who = await options.accounts.whoIs(tokenFrom(request.headers));
+            const token = tokenFrom(request.headers);
+            const who = await options.accounts.whoIs(token);
             if (who === null) {
                 json(response, 401, { error: "not signed in" });
                 return;
             }
+            // An app acting for the person sees the list only with a scope that
+            // says so, may not change it, and never gets a control key: those are
+            // the person's, and an app that held one could drive the machine.
+            const grant = options.authServer ? await options.authServer.grantFor(token) : null;
+            if (grant) {
+                if (!(grant.scope.includes("streams") || grant.scope.includes("stations"))) {
+                    json(response, 403, { error: "this app was not given access to your servers", code: "insufficient_scope" });
+                    return;
+                }
+                if (!(path === "/api/v1/servers" && request.method === "GET")) {
+                    json(response, 403, { error: "an app may list your servers, not change them", code: "insufficient_scope" });
+                    return;
+                }
+                json(response, 200, { servers: (await servers.list(who.id)).map(({ key: _key, ...shown }) => shown) });
+                return;
+            }
             if (path === "/api/v1/servers" && request.method === "GET") {
                 json(response, 200, { servers: await servers.list(who.id) });
                 return;
@@ -5590,7 +5625,10 @@ export function createHandler(engine, options) {
                 return;
             }
             let file = null;
-            if (isFile(direct))
+            // The library and radio console is a page of its own, at its own names.
+            if (/^\/(radio|library)\/?$/.test(path) && isFile(join(web, "radio.html")))
+                file = join(web, "radio.html");
+            else if (isFile(direct))
                 file = direct;
             else if (isFile(join(direct, "index.html")))
                 file = join(direct, "index.html");
@@ -6144,6 +6182,16 @@ export async function serve(argv, version = "0.1.0") {
         log: (line) => console.log(line),
     });
     const stations = { store: stationStore, runner: stationRunner };
+    // Music handed over from BitTorrented, copied into a folder of our own.
+    const importer = new Importer(join(stateDir(), `handoffs-${options.port}.json`), {
+        index: libraryIndex,
+        stations: stationStore,
+        root: join(stateDir(), "imports", "bittorrented"),
+        probe: probeFile,
+        guard: (url) => refusedDestination(url),
+        log: (line) => console.log(line),
+    });
+    importer.resume();
     // Channels as HLS, on demand, for Safari on a phone: one ffmpeg copying a
     // channel's fragments into short files while somebody is asking for them.
     // What things are, from nichedb.dev, remembered beside the keys so a
@@ -6724,6 +6772,7 @@ export async function serve(argv, version = "0.1.0") {
         channels,
         stations,
         library,
+        importer,
         rememberChannels: remembering,
         catalogs,
         publishUrls: () => publishUrls,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.32.0",
+  "version": "0.34.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/handoff-routes.ts

@@ -0,0 +1,73 @@
+/**
+ * /api/v1/integrations/bittorrented/handoffs: where BitTorrented hands music
+ * over. Only this server's owner -- the control key, the owner's session, or
+ * an app the owner gave the `stations` scope -- may hand anything over, list
+ * handoffs, retry one or delete its copies.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { publicHandoff, type Importer } from "./handoff.ts";
+import { LibraryError } from "./library-index.ts";
+
+export interface HandoffContext {
+  importer: Importer;
+  canWrite: boolean;
+  /** Whose handoffs: the owner's account, or "owner" for the control key. */
+  owner: string;
+  json: (response: ServerResponse, status: number, body: unknown) => void;
+  readBody: (request: IncomingMessage) => Promise<string>;
+}
+
+const BASE = "/api/v1/integrations/bittorrented/handoffs";
+
+export async function handleHandoffs(request: IncomingMessage, response: ServerResponse, path: string, ctx: HandoffContext): Promise<boolean> {
+  if (path !== BASE && !path.startsWith(`${BASE}/`)) return false;
+  const method = request.method ?? "GET";
+  const fail = (status: number, code: string, error: string): true => {
+    ctx.json(response, status, { error, code });
+    return true;
+  };
+  if (!ctx.canWrite) return fail(403, "forbidden", "only this server's owner (or an app they gave the stations scope) hands music over");
+  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>;
+  };
+  try {
+    if (path === BASE) {
+      if (method === "GET") {
+        ctx.json(response, 200, { handoffs: ctx.importer.list(ctx.owner).map(publicHandoff) });
+        return true;
+      }
+      if (method === "POST") {
+        const { handoff, created } = ctx.importer.create(await body(), ctx.owner);
+        ctx.json(response, created ? 201 : 200, { handoff: publicHandoff(handoff), created });
+        return true;
+      }
+      return fail(405, "method_not_allowed", "GET or POST");
+    }
+    const match = /^\/api\/v1\/integrations\/bittorrented\/handoffs\/([0-9a-f]{16})(?:\/(retry))?$/.exec(path);
+    const handoff = match ? ctx.importer.get(match[1]!) : undefined;
+    if (!match || !handoff || handoff.owner !== ctx.owner) return fail(404, "not_found", "no such handoff");
+    if (match[2] === "retry") {
+      if (method !== "POST") return fail(405, "method_not_allowed", "POST");
+      ctx.json(response, 200, { handoff: publicHandoff(ctx.importer.retry(handoff.id, await body())) });
+      return true;
+    }
+    if (method === "GET") {
+      ctx.json(response, 200, { handoff: publicHandoff(handoff) });
+      return true;
+    }
+    if (method === "DELETE") {
+      const removed = ctx.importer.remove(handoff.id);
+      ctx.json(response, 200, { deleted: handoff.id, copiesRemoved: removed });
+      return true;
+    }
+    return fail(405, "method_not_allowed", "GET or DELETE");
+  } 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));
+  }
+}