nixamp 0.29.1 → 0.30.1

package/dist/channels.js

@@ -1252,7 +1252,10 @@ export function rememberedChannels(dir, port) {
  */
 export function rememberedNow(channels) {
     return channels.list()
-        .filter((one) => one.via === "pull" && one.source && !channels.isEphemeral(one.id))
+        // A station's channel is put back by its station, which knows whether it
+        // is still wanted; remembering it here too would bring back one its
+        // owner had stopped.
+        .filter((one) => one.via === "pull" && one.source && !channels.isEphemeral(one.id) && !one.id.startsWith("station-"))
         .map((one) => {
         const kept = { id: one.id, name: one.name, source: one.source };
         if (one.kind)

package/dist/directory.d.ts

@@ -146,6 +146,8 @@ export interface LineupEntry {
     kind: "audio" | "video";
     art: string;
     about: string;
+    /** A station's own listening page, on the same server; only for a station its owner listed. */
+    listen?: string;
 }
 /** Trim and flatten, so one publisher cannot draw a box in someone's terminal. */
 export declare function clean(value: unknown, max: number): string;
@@ -158,7 +160,7 @@ export declare function clean(value: unknown, max: number): string;
 export declare function publishable(raw: string): URL | null;
 export declare function parseAnnouncement(input: unknown): Announcement | null;
 /** One lineup entry as a publisher sent it, cleaned, or null when it is not one. */
-export declare function parseLineupEntry(input: unknown): LineupEntry | null;
+export declare function parseLineupEntry(input: unknown, origin?: string): LineupEntry | null;
 /**
  * The registry. In memory on purpose: see the note at the top of the file.
  * One entry per URL, so a publisher restarting does not leave a ghost of

package/dist/directory.js

@@ -95,12 +95,12 @@ export function parseAnnouncement(input) {
             }
             : {}),
         ...(Array.isArray(record["lineup"])
-            ? { lineup: record["lineup"].map(parseLineupEntry).filter((one) => one !== null).slice(0, MAX_CHANNELS) }
+            ? { lineup: record["lineup"].map((one) => parseLineupEntry(one, listen.origin)).filter((one) => one !== null).slice(0, MAX_CHANNELS) }
             : {}),
     };
 }
 /** One lineup entry as a publisher sent it, cleaned, or null when it is not one. */
-export function parseLineupEntry(input) {
+export function parseLineupEntry(input, origin = "") {
     if (typeof input !== "object" || input === null)
         return null;
     const record = input;
@@ -120,6 +120,12 @@ export function parseLineupEntry(input) {
         // page in a tag, and javascript: is a page in a tag that runs.
         art: publishable(art) !== null ? art : "",
         about: clean(record["about"], MAX_ABOUT),
+        // The same server as the listing, or nothing, like the audio address.
+        ...(() => {
+            const offered = typeof record["listen"] === "string" ? record["listen"].slice(0, MAX_ART) : "";
+            const parsed = offered && origin ? publishable(offered) : null;
+            return parsed !== null && parsed.origin === origin ? { listen: offered } : {};
+        })(),
     };
 }
 /**

package/dist/main.d.ts

@@ -1,11 +1,3 @@
-/**
- * nixamp — it really whips the terminal's ass.
- *
- *   bunx nixamp ~/Music
- *   bunx nixamp track.flac
- *
- * ffmpeg decodes; we read every sample on its way to the speakers and draw it.
- */
 import { type BrailleCanvas, type Container, type Theme } from "@profullstack/hqtui";
 import { type Track } from "./audio.ts";
 export declare const BAND_COUNT = 24;

package/dist/main.js

@@ -7,6 +7,7 @@ import { t as uiMessage, i18n, terminalUiLanguage, uiLanguage } from "./i18n.js"
  *
  * ffmpeg decodes; we read every sample on its way to the speakers and draw it.
  */
+import { USAGE as STATION_USAGE } from "./station-usage.js";
 import { createApp, themes } from "@profullstack/hqtui";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
@@ -206,6 +207,7 @@ keeps serving its browser remote. One per user.
 
   nixamp attach   put the player back in front of it
   nixamp admin    who is connected, and re-stream to them
+  nixamp station  make a folder into a station others can join (see: nixamp station help)
 
 From inside the player, d hands the music to a daemon without stopping it.
 `,
@@ -367,6 +369,8 @@ q or d leaves; neither stops anything. \`nixamp daemon stop\` is what stops it.
 `,
 };
 export function helpFor(topic) {
+    if (topic === "station" || topic === "stations")
+        return STATION_USAGE;
     return (topic ? TOPICS[topic] : undefined) ?? HELP;
 }
 /**
@@ -524,6 +528,11 @@ export async function main() {
         process.exitCode = await runDaemon(rest);
         return;
     }
+    if (first === "station" || first === "stations") {
+        const { station } = await import("./station-cli.js");
+        process.exitCode = await station(rest);
+        return;
+    }
     if (first === "admin") {
         const { admin } = await import("./admin.js");
         await admin(rest);

package/dist/server.d.ts

@@ -5,7 +5,7 @@ import { LiveVoice } from "./live-voice.ts";
 import { Connections } from "./connections.ts";
 import { Broadcaster, type Destination, type EncoderSettings } from "./broadcast.ts";
 import { Ingest } from "./ingest.ts";
-import { Channels, type Channel, type ChannelInfo, type RememberedChannel } from "./channels.ts";
+import { Channels, type Channel, type ChannelInfo, type PullResume, type RememberedChannel } from "./channels.ts";
 import { Accounts } from "./accounts.ts";
 import { type ResetMail } from "./password-reset.ts";
 import { Handles } from "./handles.ts";
@@ -21,6 +21,8 @@ import { Directory, type LineupEntry } from "./directory.ts";
 import { ArtCache } from "./art.ts";
 import { PartyLine } from "./partyline.ts";
 import { HlsPackagers } from "./hls.ts";
+import { StationRunner } from "./station-runner.ts";
+import { StationStore } from "./stations.ts";
 import { CompressionService } from "./compression/service.ts";
 import { Enricher } from "./enrich.ts";
 import { Follows } from "./follows.ts";
@@ -438,7 +440,26 @@ export interface KnownSource {
     /** A picture and a line about it, from the site or the list that named it. */
     art?: string;
     about?: string;
+    /** A station's rotation (see PullResume.rotation). */
+    rotation?: PullResume["rotation"];
+    /** kbps for an audio rendition; 192 when unset. */
+    audioBitrate?: number;
 }
+/**
+ * A station's files, chosen by track index (as /api/folders/live takes them)
+ * or by a folder under the library; null when neither was given. Only files
+ * on this machine and inside the library: a station never reaches past it.
+ */
+export declare function selectStationFiles(engine: Engine, body: {
+    items?: unknown;
+    folder?: unknown;
+}): string[] | null;
+/** What the library knows about one file: its tags, for a now-playing line. */
+export declare function trackFor(engine: Engine, file: string): {
+    title: string;
+    artist: string;
+    album: string;
+} | null;
 /** How many times a source that answers nothing is asked, and how far apart. */
 export declare const PROBE_TRIES = 3;
 export declare const PROBE_RETRY_MS = 1500;
@@ -545,6 +566,11 @@ export declare function joinSubject(url: URL, options: Pick<HandlerOptions, "dir
 /** The shell, titled for what a join link opens, with its picture on the card. */
 export declare function joinDocument(shell: string, subject: JoinSubject, site: string): string;
 export interface HandlerOptions {
+    /** This server's stations and what keeps them on the air. */
+    stations?: {
+        store: StationStore;
+        runner: StationRunner;
+    };
     web: string | null;
     /** Branded clients on this same backend, keyed by an explicitly configured host. */
     webSites?: ReadonlyMap<string, import("./web-sites.ts").WebSite>;

package/dist/server.js

@@ -54,6 +54,10 @@ import { ArtCache, coverArtOf, stillFrom } from "./art.js";
 import { PartyLine, telnyxSms } from "./partyline.js";
 import { HlsPackagers, segmentType, withKey } from "./hls.js";
 import { refusedDestination } from "./destinations.js";
+import { handleStations, isStationListenPath } from "./station-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";
 import { CompressionService } from "./compression/service.js";
 import { handleChannelCompression, handleCompressionApi, handleStaticRelay } from "./compression/routes.js";
 import { DEFAULT_SITE as NICHEDB, Enricher, FIXTURE_TTL_MS } from "./enrich.js";
@@ -876,6 +880,63 @@ export function memberLiveRefusal(channels, account) {
     }
     return "";
 }
+/**
+ * A station's files, chosen by track index (as /api/folders/live takes them)
+ * or by a folder under the library; null when neither was given. Only files
+ * on this machine and inside the library: a station never reaches past it.
+ */
+export function selectStationFiles(engine, body) {
+    const root = engine.snapshot(false).root;
+    if (Array.isArray(body.items)) {
+        const indices = [...new Set(body.items.filter((one) => Number.isInteger(one) && one >= 0))];
+        const files = indices.map((index) => engine.trackPath(index)).filter((one) => typeof one === "string" && !isRemote(one));
+        if (indices.length !== body.items.length || files.length !== indices.length) {
+            throw new StationError("unknown_items", "one or more of those tracks are not files in this library");
+        }
+        return files;
+    }
+    if (typeof body.folder === "string") {
+        const folder = body.folder.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+        if (folder.split("/").includes(".."))
+            throw new StationError("invalid_folder", "a folder inside the library, please");
+        const files = [];
+        const count = engine.snapshot(false).trackCount;
+        for (let index = 0; index < count; index++) {
+            const file = engine.trackPath(index);
+            if (!file || isRemote(file))
+                continue;
+            const served = relative(root, file).replaceAll("\\", "/");
+            if (served.startsWith("../"))
+                continue;
+            if (folder === "" || served.startsWith(`${folder}/`))
+                files.push(file);
+        }
+        if (files.length === 0)
+            throw new StationError("empty_folder", "that folder has no files that play");
+        return files;
+    }
+    return null;
+}
+const tracksByPath = new WeakMap();
+/** What the library knows about one file: its tags, for a now-playing line. */
+export function trackFor(engine, file) {
+    const revision = engine.snapshot(false).revision;
+    let index = tracksByPath.get(engine);
+    if (!index || index.revision !== revision) {
+        const tracks = engine.snapshot().tracks ?? [];
+        const byPath = new Map();
+        tracks.forEach((track, at) => {
+            const path = engine.trackPath(at);
+            // Tags only: a title that is the file's own name is not a tag.
+            const named = track.title && !looksLikeFileName(track.title) ? track.title : "";
+            if (path)
+                byPath.set(path, { title: named, artist: track.artist ?? "", album: track.album ?? "" });
+        });
+        index = { revision, byPath };
+        tracksByPath.set(engine, index);
+    }
+    return index.byPath.get(file) ?? null;
+}
 /** How many times a source that answers nothing is asked, and how far apart. */
 export const PROBE_TRIES = 3;
 export const PROBE_RETRY_MS = 1500;
@@ -944,7 +1005,7 @@ export async function pullChannel(channels, ffprobe, id, name, source, input = [
         ]
         // No picture in it, so none is invented: MP3 is the thing every browser
         // plays and the thing a listener can join halfway through.
-        : ["-vn", "-c:a", "libmp3lame", "-b:a", "192k", "-f", "mp3"];
+        : ["-vn", "-c:a", "libmp3lame", "-b:a", `${known.audioBitrate ?? 192}k`, "-f", "mp3"];
     // A transport stream is read further into before it is decoded, and given
     // the timestamps a recording cut mid-stream does not carry. Ahead of the
     // caller's own input arguments, which are headers for the address itself.
@@ -953,7 +1014,7 @@ export async function pullChannel(channels, ffprobe, id, name, source, input = [
     // MP3's tags name the episode and the show, and "Inspiring Founders" is a
     // card; "ep-0412-final.mp3" is not.
     const tagged = looksLikeFileName(name) && codecs.tags?.title ? codecs.tags.title : name;
-    const channel = channels.pull(id, tagged, source, encode, kind, true, undefined, opening, kind === "video" ? audio : "", { live, position: known.position ?? 0, ...(playlist ? { playlist, playlistAt: known.playlistAt ?? 0 } : {}) }, 
+    const channel = channels.pull(id, tagged, source, encode, kind, true, undefined, opening, kind === "video" ? audio : "", { live, position: known.position ?? 0, ...(playlist ? { playlist, playlistAt: known.playlistAt ?? 0 } : {}), ...(known.rotation ? { rotation: known.rotation } : {}) }, 
     // Known before the first dial: whether the source is a transport stream
     // decides whether it can be read here for a source-boundary relay.
     assumed ? undefined : codecs);
@@ -2072,6 +2133,9 @@ export function createHandler(engine, options) {
             path !== "/api/health" &&
             path !== "/api/directory" &&
             !isSignInPath(path) &&
+            // A station's link is its own key, checked by the station.
+            !isStationListenPath(path) &&
+            !STATION_PAGE.test(path) &&
             !eventChannelRequest) {
             let scope = scopeOf(keyFrom(request, url), key, listenKey);
             // Kept for the routes below that answer a listener with less.
@@ -2108,6 +2172,55 @@ export function createHandler(engine, options) {
                 return;
             }
         }
+        // Whether this request may administer: the control key, an open server,
+        // or the owner's nixamp.com session. Asked by the routes that do not go
+        // through the admin gate further down.
+        const controlOf = async () => {
+            if (key === null)
+                return { allowed: true, account: "" };
+            if (scopeOf(keyFrom(request, url), key, listenKey) === "control")
+                return { allowed: true, account: "" };
+            if (options.owner) {
+                const session = tokenFrom(request.headers) || url.searchParams.get("session") || "";
+                if (session !== "" && (await options.owner.check(false, session)).allowed) {
+                    return { allowed: true, account: (await options.owner.accountFor(session)) || "" };
+                }
+            }
+            return { allowed: false, account: "" };
+        };
+        // The page a station's link opens. The same bytes for every station: it
+        // reads its id and token from its own address.
+        if (options.stations && STATION_PAGE.test(path) && (request.method === "GET" || request.method === "HEAD")) {
+            response.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-cache",
+                "content-security-policy": STATION_PAGE_CSP,
+                "referrer-policy": "no-referrer",
+                "x-content-type-options": "nosniff",
+            });
+            response.end(request.method === "HEAD" ? undefined : STATION_PAGE_HTML);
+            return;
+        }
+        if (options.stations && (path === "/api/v1/stations" || path.startsWith("/api/v1/stations/"))) {
+            const control = await controlOf();
+            const encrypted = request.socket.encrypted === true;
+            const forwarded = behindProxy ? String(request.headers["x-forwarded-proto"] ?? "").split(",")[0]?.trim() : "";
+            const scheme = forwarded === "https" || encrypted ? "https" : "http";
+            await handleStations(request, response, path, url, {
+                store: options.stations.store,
+                runner: options.stations.runner,
+                channels: options.channels,
+                canControl: control.allowed,
+                account: control.account,
+                select: (body) => selectStationFiles(engine, body),
+                trackFor: (file) => trackFor(engine, file),
+                base: `${scheme}://${request.headers.host ?? "localhost"}`,
+                json,
+                readBody,
+                headers: CORS,
+            });
+            return;
+        }
         if (path === "/api/health") {
             json(response, 200, { name: "nixamp", version: options.version, media: options.media });
             return;
@@ -3852,7 +3965,7 @@ export function createHandler(engine, options) {
                     // offering something that always failed.
                     carries: options.carries !== false && Boolean(options.channels),
                 },
-                channels: (options.channels?.list() ?? []).map((one) => ({
+                channels: (options.channels?.list() ?? []).filter((one) => !stationOfChannel(one.id)).map((one) => ({
                     id: one.id,
                     name: one.name,
                     via: one.via,
@@ -4478,7 +4591,8 @@ export function createHandler(engine, options) {
             // on, and the address a channel is pulled from is the one thing about
             // it that is not theirs to have.
             json(response, 200, {
-                channels: options.channels.list().map(({ source: _source, ...shown }) => shown),
+                // Stations answer for themselves, under /api/v1/stations.
+                channels: options.channels.list().filter((one) => !stationOfChannel(one.id)).map(({ source: _source, ...shown }) => shown),
                 listeners: options.channels.listeners,
             });
             return;
@@ -4490,6 +4604,12 @@ export function createHandler(engine, options) {
             const rest = path.slice("/api/channels/".length);
             const [rawId, action, file] = rest.split("/");
             const id = cleanId(rawId);
+            // A station's channel is heard through the station's own link, which
+            // knows whether it is private. Through here, only by its owner.
+            if (stationOfChannel(id) && !(await controlOf()).allowed) {
+                json(response, 404, { error: "nothing is playing on that channel" });
+                return;
+            }
             const event = await eventForChannel();
             if (event) {
                 const account = await options.accounts?.whoIs(tokenFrom(request.headers)) ?? null;
@@ -5932,6 +6052,9 @@ export async function serve(argv, version = "0.1.0") {
     // same ffmpeg that carries the channels. No ffmpeg, no outro, and a show
     // that ends closes its channel as before.
     const outro = new Outro({ ffmpeg: tools.ffmpeg, dir: join(stateDir(), "outro"), onEvent: (message) => console.log(message) });
+    // Made once the channels exist; told of every channel that ends, so a
+    // station that died is brought back and one that was stopped is not.
+    let stationRunner = null;
     const channels = new Channels({
         ffmpeg: tools.ffmpeg,
         ffprobe: tools.ffprobe,
@@ -5941,8 +6064,24 @@ export async function serve(argv, version = "0.1.0") {
         onEnd: (info) => {
             console.log(`  "${info.id}" stopped.`);
             art.forget(info.id);
+            stationRunner?.onChannelEnd(info);
         },
     });
+    const stationStore = new StationStore(StationStore.fileFor(stateDir(), options.port));
+    stationRunner = new StationRunner({
+        store: stationStore,
+        channels,
+        pull: async (channelId, name, files, known) => Boolean(await pullChannel(channels, tools.ffprobe, channelId, name, files[0], [], "", {
+            playlist: files,
+            live: true,
+            rotation: known.rotation,
+            audioBitrate: known.audioBitrate,
+        })),
+        // The library as it is now, or as it was chosen while it is still being read.
+        roots: () => [engine.snapshot(false).root || chosen].filter((one) => one !== ""),
+        log: (line) => console.log(line),
+    });
+    const stations = { store: stationStore, runner: stationRunner };
     // 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
@@ -5991,6 +6130,7 @@ export async function serve(argv, version = "0.1.0") {
                 console.log(`  "${one.id}" is already on.`);
         });
     }
+    stationRunner.restore();
     // Where each film has got to, written down every so often, so a restart
     // picks it up from about there rather than from the start. Only when it
     // has changed: a server carrying nothing but live television writes
@@ -6520,6 +6660,7 @@ export async function serve(argv, version = "0.1.0") {
         media: options.media,
         owner,
         channels,
+        stations,
         rememberChannels: remembering,
         catalogs,
         publishUrls: () => publishUrls,
@@ -6929,6 +7070,11 @@ export async function serve(argv, version = "0.1.0") {
      * A declaration rather than an assignment, so it exists from the moment the
      * function is entered -- the port is open well before this line is reached.
      */
+    /** The station behind this channel, when its owner made it public and listed it. */
+    function listedStation(channelId) {
+        const station = stationStore.get(stationOfChannel(channelId));
+        return station && station.visibility === "public" && station.listed ? station : undefined;
+    }
     function makePublisher() {
         if (!publishable_)
             return null;
@@ -6953,10 +7099,20 @@ export async function serve(argv, version = "0.1.0") {
             // which channels are on. A directory row that says "5,717 files,
             // live: CNN" is one somebody can decide about; "5717 tracks" was not.
             playing: () => engine.snapshot(false).playing,
-            channels: () => channels.list().map((one) => one.name),
+            // Stations only when their owner listed them; every other channel as before.
+            channels: () => channels.list().filter((one) => !stationOfChannel(one.id) || listedStation(one.id)).map((one) => one.name),
             // The same with what a link preview needs: the id a join link names
             // a channel by, a picture, a line.
-            lineup: () => channels.list().map((one) => lineupEntry(listen, one)),
+            lineup: () => channels.list()
+                .filter((one) => !stationOfChannel(one.id) || listedStation(one.id))
+                .map((one) => {
+                const entry = lineupEntry(listen, one);
+                const station = listedStation(one.id);
+                // A station is listened to through its own link, never the server's.
+                return station
+                    ? { ...entry, listen: `${publishable_.url}/station/${station.id}?t=${encodeURIComponent(station.listenToken)}` }
+                    : entry;
+            }),
             // From `nixamp login`. The directory will not list a stream it cannot
             // attribute to somebody, because a listing is now a phone code that
             // costs money to answer.

package/dist/station-cli.d.ts

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

package/dist/station-cli.js

@@ -0,0 +1,201 @@
+/**
+ * `nixamp station`: stations from a terminal, a script or a cron job.
+ *
+ * Talks to the daemon on this machine with its control key, or to another
+ * server with --url and --key, exactly as `nixamp admin` does. Every command
+ * takes --json for a script; without it, a line a person can read. Exit codes
+ * a script can branch on: 0 done, 1 the server said no (the reason and a
+ * stable code are printed), 2 the command was wrong, 3 the server could not
+ * be reached.
+ *
+ * Nothing here publishes as a side effect. `create` and `start` leave a
+ * station private; `publish` is its own command and says on what basis.
+ */
+import { resolveTarget } from "./admin.js";
+import { readState } from "./daemon.js";
+import { KEY_HEADER } from "./share.js";
+import { USAGE } from "./station-usage.js";
+export { USAGE };
+function flag(argv, name) {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+}
+function has(argv, name) {
+    return argv.includes(name);
+}
+class Unreachable extends Error {
+}
+export async function station(argv) {
+    const [command, id] = argv;
+    const json = has(argv, "--json");
+    if (!command || command === "help" || has(argv, "--help")) {
+        console.log(USAGE);
+        return command ? 0 : 2;
+    }
+    let target;
+    try {
+        target = resolveTarget(argv);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 3;
+    }
+    const headers = { "content-type": "application/json", ...(target.key ? { [KEY_HEADER]: target.key } : {}) };
+    const call = async (method, path, body) => {
+        let response;
+        try {
+            response = await fetch(`${target.url}${path}`, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+        }
+        catch (error) {
+            throw new Unreachable(`could not reach ${target.url}: ${error.message}`);
+        }
+        const text = await response.text();
+        let parsed = {};
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = { error: text };
+        }
+        return { status: response.status, body: parsed };
+    };
+    const needId = () => {
+        if (!id || id.startsWith("--")) {
+            console.error(`nixamp station ${command} needs a station id. \`nixamp station list\` shows them.`);
+            return null;
+        }
+        return id;
+    };
+    const show = (answer, line) => {
+        if (json) {
+            console.log(JSON.stringify(answer.body, null, 2));
+        }
+        else if (answer.status < 400) {
+            console.log(line(answer.body));
+        }
+        if (answer.status >= 400) {
+            if (!json)
+                console.error(`nixamp: ${String(answer.body["error"] ?? "refused")} (${String(answer.body["code"] ?? answer.status)})`);
+            return 1;
+        }
+        return 0;
+    };
+    const describe = (station) => {
+        const links = (station["links"] ?? {});
+        return [
+            `${String(station["name"])}  [${String(station["id"])}]`,
+            `  state       ${String(station["state"])} (wanted ${String(station["desired"])})`,
+            `  visibility  ${String(station["visibility"])}${station["listed"] ? ", listed in the directory" : ""}`,
+            `  rotation    ${station["shuffle"] ? "shuffle" : "in order"}${station["repeat"] ? ", repeating" : ", once"}; ${station["items"]?.length ?? 0} files at ${String(station["bitrate"])} kbps`,
+            ...(station["error"] ? [`  problem     ${String(station["error"])}`] : []),
+            ...(station["excluded"]?.length ? [`  left out   ${station["excluded"].length} files (nixamp station retry)`] : []),
+            ...(station["visibility"] !== "private" && links["page"] ? [`  listen      ${links["page"]}`] : []),
+        ].join("\n");
+    };
+    try {
+        switch (command) {
+            case "list": {
+                const answer = await call("GET", "/api/v1/stations?limit=200");
+                return show(answer, (body) => {
+                    const all = body["stations"] ?? [];
+                    return all.length === 0 ? "No stations yet. nixamp station create --name NAME --folder PATH" : all.map(describe).join("\n\n");
+                });
+            }
+            case "create": {
+                const name = flag(argv, "--name");
+                if (!name) {
+                    console.error("nixamp station create needs --name");
+                    return 2;
+                }
+                const items = flag(argv, "--items");
+                let folder = flag(argv, "--folder");
+                if (folder !== undefined) {
+                    // A path under the library is taken relative to it.
+                    const root = readState()?.source ?? "";
+                    if (root && folder.startsWith(root))
+                        folder = folder.slice(root.length);
+                }
+                if (items === undefined && folder === undefined) {
+                    console.error("nixamp station create needs --folder PATH or --items 0,1,2");
+                    return 2;
+                }
+                const bitrate = flag(argv, "--bitrate");
+                const answer = await call("POST", "/api/v1/stations", {
+                    name,
+                    ...(items !== undefined ? { items: items.split(",").map((one) => Number(one.trim())) } : { folder }),
+                    shuffle: has(argv, "--shuffle"),
+                    repeat: !has(argv, "--no-repeat"),
+                    ...(bitrate ? { bitrate: Number(bitrate) } : {}),
+                });
+                return show(answer, (body) => `Made (private, stopped):\n${describe(body["station"])}`);
+            }
+            case "show":
+            case "status": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                return show(await call("GET", `/api/v1/stations/${station}`), (body) => describe(body["station"]));
+            }
+            case "start":
+            case "stop":
+            case "skip":
+            case "retry": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                return show(await call("POST", `/api/v1/stations/${station}/${command}`, {}), (body) => describe(body["station"]));
+            }
+            case "publish": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                const basis = flag(argv, "--basis");
+                const unlisted = has(argv, "--unlisted");
+                const access = {
+                    visibility: unlisted ? "unlisted" : "public",
+                    listed: !unlisted && !has(argv, "--no-list"),
+                    ...(basis ? { rights: { basis, note: flag(argv, "--note") ?? "" } } : {}),
+                };
+                return show(await call("POST", `/api/v1/stations/${station}/access`, access), (body) => describe(body["station"]));
+            }
+            case "unpublish": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                const access = has(argv, "--private") ? { visibility: "private" } : { listed: false };
+                return show(await call("POST", `/api/v1/stations/${station}/access`, access), (body) => {
+                    const dropped = Number(body["dropped"] ?? 0);
+                    return `${describe(body["station"])}${dropped ? `\n  ${dropped} listener(s) disconnected; old links no longer work.` : ""}`;
+                });
+            }
+            case "link": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                const answer = has(argv, "--rotate")
+                    ? await call("POST", `/api/v1/stations/${station}/rotate-link`, {})
+                    : await call("GET", `/api/v1/stations/${station}`);
+                return show(answer, (body) => {
+                    const links = (body["station"]["links"] ?? {});
+                    return [`page    ${links["page"]}`, `stream  ${links["stream"]}`, `m3u     ${links["m3u"]}`].join("\n");
+                });
+            }
+            case "delete": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                return show(await call("DELETE", `/api/v1/stations/${station}`), () => `Deleted ${station}. Its files were not touched.`);
+            }
+            default:
+                console.error(`nixamp station: no command "${command}".\n\n${USAGE}`);
+                return 2;
+        }
+    }
+    catch (error) {
+        if (error instanceof Unreachable) {
+            console.error(`nixamp: ${error.message}`);
+            return 3;
+        }
+        throw error;
+    }
+}