nixamp 0.23.1 → 0.23.3

package/dist/server.d.ts

@@ -2,7 +2,7 @@ import { type IncomingMessage, type Server, type ServerResponse } from "node:htt
 import { Connections } from "./connections.ts";
 import { Broadcaster, type Destination, type EncoderSettings } from "./broadcast.ts";
 import { Ingest } from "./ingest.ts";
-import { Channels, type Channel, type RememberedChannel } from "./channels.ts";
+import { Channels, type Channel, type ChannelInfo, type RememberedChannel } from "./channels.ts";
 import { Accounts } from "./accounts.ts";
 import { Handles } from "./handles.ts";
 import { OpenDirs } from "./opendirs.ts";
@@ -11,7 +11,8 @@ import { SignIn } from "./oauth.ts";
 import { AuthorizationServer } from "./oauth-server.ts";
 import { WatchParties } from "./watch-party.ts";
 import { Owner } from "./owner.ts";
-import { Directory } from "./directory.ts";
+import { Directory, type LineupEntry } from "./directory.ts";
+import { ArtCache } from "./art.ts";
 import { PartyLine } from "./partyline.ts";
 import { HlsPackagers } from "./hls.ts";
 import { CompressionService } from "./compression/service.ts";
@@ -407,6 +408,9 @@ export interface KnownSource {
     /** A list of entries to play in turn, and which one was on. */
     playlist?: string[];
     playlistAt?: number;
+    /** A picture and a line about it, from the site or the list that named it. */
+    art?: string;
+    about?: string;
 }
 /** How many times a source that answers nothing is asked, and how far apart. */
 export declare const PROBE_TRIES = 3;
@@ -425,6 +429,26 @@ export declare const PROBE_RETRY_MS = 1500;
  */
 export declare function hevcChannelsAllowed(env?: NodeJS.ProcessEnv): boolean;
 export declare function pullChannel(channels: Channels, ffprobe: string[], id: string, name: string, source: string, input?: string[], audio?: string, known?: KnownSource): Promise<Channel | null>;
+/** Whether a name is only a file's: something.mp3, with nothing said about it. */
+export declare function looksLikeFileName(name: string): boolean;
+/**
+ * Where a channel's picture is, for the page and the directory.
+ *
+ * The site's own thumbnail as it is; else this server's art route, when
+ * the channel has a picture to read one from -- a sleeve in the file, or a
+ * moving picture to take a frame of. "" for a channel of sound with no
+ * sleeve, which has no picture to be had.
+ */
+export declare function artOf(info: Pick<ChannelInfo, "id" | "art" | "kind" | "codecs">): string;
+/**
+ * The same, as a crawler reaches it: an absolute address on this server
+ * with the listen key on it, since a preview is fetched by nobody who
+ * holds the cookie. The listen link is what the directory publishes
+ * already, so the key on the picture gives away nothing new.
+ */
+export declare function absoluteArtOf(listenLink: string, info: Pick<ChannelInfo, "id" | "art" | "kind" | "codecs">): string;
+/** A channel as the directory's lineup wants it: id, name, kind, picture, line. */
+export declare function lineupEntry(listenLink: string, info: ChannelInfo): LineupEntry;
 /**
  * A Netscape cookies file beside the state, if the operator has put one there.
  *
@@ -479,15 +503,20 @@ export declare function brandOf(shell: string, site: string): string;
  * query is not used: a page that titled itself with whatever the address said
  * would be a preview anyone could put words in.
  */
-export declare function joinSubject(url: URL, options: Pick<HandlerOptions, "directory" | "channels" | "serverName">): {
+/** What a join link opens, as the shell's head says it: a name, where it is, and a picture and a line when it has them. */
+export interface JoinSubject {
     title: string;
     where: string;
-} | null;
-/** The shell, titled for what a join link opens. */
-export declare function joinDocument(shell: string, subject: {
-    title: string;
-    where: string;
-}, site: string): string;
+    /** An absolute picture address a crawler can fetch, or "". */
+    image?: string;
+    /** A line about it, or "". */
+    about?: string;
+    /** Whether the picture is a frame of a moving picture (wide) or a sleeve (square). */
+    kind?: "audio" | "video";
+}
+export declare function joinSubject(url: URL, options: Pick<HandlerOptions, "directory" | "channels" | "serverName" | "live">): JoinSubject | null;
+/** 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 {
     web: string | null;
     media: boolean;
@@ -514,6 +543,8 @@ export interface HandlerOptions {
     ytdlp?: string[] | null;
     /** Channels as HLS, for Safari on a phone, which plays a live stream no other way. */
     hls?: HlsPackagers;
+    /** The pictures of channels already taken, so a card unfurled by five crawlers costs one ffmpeg. */
+    art?: ArtCache;
     /** Captions for a channel: its sound, as lines, as they are heard. Needs ffmpeg and a sign-in. */
     captions?: Captions;
     /** Lossless relay compression, its policies, diagnostics and static representations. */

package/dist/server.js

@@ -37,6 +37,7 @@ import { playJingle } from "./jingle.js";
 import { stateDir } from "./daemon.js";
 import { readSession } from "./session.js";
 import { Directory, ENDED_TTL_MS, parseAnnouncement } from "./directory.js";
+import { ArtCache, coverArtOf, stillFrom } from "./art.js";
 import { PartyLine, telnyxSms } from "./partyline.js";
 import { HlsPackagers, segmentType, withKey } from "./hls.js";
 import { CompressionService } from "./compression/service.js";
@@ -70,7 +71,7 @@ import { confirm, DEFAULT_DIRECTORY, Publisher } from "./publish.js";
 import { applyRemoteConfig, createPaywall, FREE_LISTENERS, paywallFromEnv, } from "./paywall.js";
 import { isRemote, isTransportStream, playsInBrowser, sourceLabel } from "./sources.js";
 import { codecsOf, probeAsync, transportInputArgs, videoArgs } from "./audio.js";
-import { allowedForListening, elevate, firewallInUse, certifiable, keyCookie, keyInPath, rememberedKeys, keyFrom, lookupPublicIp, portCommands, reachableAddresses, scopeOf, shareLink, audioLink, } from "./share.js";
+import { allowedForListening, elevate, firewallInUse, certifiable, keyCookie, keyInPath, rememberedKeys, keyFrom, lookupPublicIp, portCommands, reachableAddresses, scopeOf, shareLink, audioLink, KEY_QUERY, } from "./share.js";
 import { extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { detectTools, peaks, RATE, Stream, toMono, } from "./audio.js";
@@ -902,7 +903,11 @@ export async function pullChannel(channels, ffprobe, id, name, source, input = [
     // 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.
     const opening = [...transportInputArgs(source, codecs.container), ...input];
-    const channel = channels.pull(id, name, source, encode, kind, true, undefined, opening, kind === "video" ? audio : "", { live, position: known.position ?? 0, ...(playlist ? { playlist } : {}) }, 
+    // A bare file is named by its file name until the file says better: an
+    // 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 } : {}) }, 
     // 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);
@@ -910,6 +915,32 @@ export async function pullChannel(channels, ffprobe, id, name, source, input = [
         channel.info.codecs = codecs;
     if (channel && playlist && known.playlistAt !== undefined)
         channel.info.playlistAt = known.playlistAt;
+    if (channel) {
+        // Its picture from wherever it came with one, and a line about it: what
+        // was given, else the show and the album the file's own tags name.
+        if (known.art && /^https?:\/\//i.test(known.art))
+            channel.info.art = known.art;
+        const byTags = [codecs.tags?.artist, codecs.tags?.album].filter((one) => Boolean(one)).join(" · ");
+        const about = (known.about ?? byTags).trim().slice(0, 200);
+        if (about !== "")
+            channel.info.about = about;
+        // A channel of sound put back from what an older nixamp wrote down was
+        // never asked whether its file carries a sleeve. Asked now, once, after
+        // it is on: reading the head of an MP3 on a CDN costs nothing and
+        // opens no second connection a panel would count (that is a film's
+        // trap, and a film has a picture of its own to take a frame of).
+        if (kind === "audio" && !channel.info.art && known.codecs && codecs.cover === undefined) {
+            void codecsOf(tools, source, input).then((later) => {
+                if (channel.info.codecs && later.cover)
+                    channel.info.codecs.cover = true;
+                if (!channel.info.about) {
+                    const line = [later.tags?.artist, later.tags?.album].filter((one) => Boolean(one)).join(" · ");
+                    if (line !== "")
+                        channel.info.about = line;
+                }
+            });
+        }
+    }
     // What comes out, as opposed to what went in. An H.265 source copied
     // through stays H.265; one re-encoded arrives as H.264, and a packager
     // told otherwise would cut fMP4 segments for a stream that did not need
@@ -919,6 +950,52 @@ export async function pullChannel(channels, ffprobe, id, name, source, input = [
     }
     return channel;
 }
+/** Whether a name is only a file's: something.mp3, with nothing said about it. */
+export function looksLikeFileName(name) {
+    return /\.[a-z0-9]{2,5}$/i.test(name.trim());
+}
+/**
+ * Where a channel's picture is, for the page and the directory.
+ *
+ * The site's own thumbnail as it is; else this server's art route, when
+ * the channel has a picture to read one from -- a sleeve in the file, or a
+ * moving picture to take a frame of. "" for a channel of sound with no
+ * sleeve, which has no picture to be had.
+ */
+export function artOf(info) {
+    if (info.art)
+        return info.art;
+    return info.codecs?.cover === true || info.kind === "video" ? `/api/channels/${encodeURIComponent(info.id)}/art` : "";
+}
+/**
+ * The same, as a crawler reaches it: an absolute address on this server
+ * with the listen key on it, since a preview is fetched by nobody who
+ * holds the cookie. The listen link is what the directory publishes
+ * already, so the key on the picture gives away nothing new.
+ */
+export function absoluteArtOf(listenLink, info) {
+    const art = artOf(info);
+    if (art === "" || /^https?:\/\//i.test(art))
+        return art;
+    try {
+        const link = new URL(listenLink);
+        const key = /\/(?:view|admin)\/([^/?#]+)$/.exec(link.pathname)?.[1] ?? "";
+        return `${link.origin}${art}${key ? `?${KEY_QUERY}=${encodeURIComponent(key)}` : ""}`;
+    }
+    catch {
+        return "";
+    }
+}
+/** A channel as the directory's lineup wants it: id, name, kind, picture, line. */
+export function lineupEntry(listenLink, info) {
+    return {
+        id: info.id,
+        name: info.name,
+        kind: info.kind ?? "audio",
+        art: absoluteArtOf(listenLink, info),
+        about: info.about ?? "",
+    };
+}
 /** What a link resolves to, kept so a download can be named without asking twice. */
 const links = new Map();
 /**
@@ -961,6 +1038,9 @@ function shownLink(channelId, link, channel) {
         download: !live && link.extractor !== "direct",
         // How many things a list holds, for the page to say.
         entries: link.playlist?.length ?? 0,
+        // Its picture and its line, for the meta line and the lock screen.
+        art: channel ? artOf(channel) : link.thumbnail,
+        about: channel?.about ?? link.about,
     };
 }
 export function liveOnes(engine) {
@@ -1104,20 +1184,16 @@ function eventDocument(shell, event, site) {
         .replace(/<meta property="og:description" content="[^"]*"\s*\/>/, `<meta property="og:description" content="${htmlText(description)}" />`)
         .replace("</head>", `${event.visibility === "public" ? "" : '<meta name="robots" content="noindex,nofollow" />'}\n    <meta property="og:url" content="${htmlText(canonical)}" />\n    <link rel="canonical" href="${htmlText(canonical)}" />\n    <script type="application/ld+json">${structured}</script>\n  </head>`);
 }
-/**
- * What a join link is for, named by something this server actually knows.
- *
- * A link preview reads the page before any script runs, so the shell has to
- * say what is on the air. On the directory that is the listing the link
- * points at, and the channel on it if one is asked for; on a server it is
- * the server itself, or one of its channels. A name that only appears in the
- * query is not used: a page that titled itself with whatever the address said
- * would be a preview anyone could put words in.
- */
 export function joinSubject(url, options) {
     const play = url.searchParams.get("play") ?? "";
     const wanted = play.startsWith("channel:") ? play.slice("channel:".length) : "";
     const link = url.searchParams.get("url") ?? "";
+    const withArt = (subject, entry) => ({
+        ...subject,
+        ...(entry?.art ? { image: entry.art } : {}),
+        ...(entry?.about ? { about: entry.about } : {}),
+        ...(entry ? { kind: entry.kind } : {}),
+    });
     if (options.directory) {
         if (link === "")
             return null;
@@ -1132,8 +1208,16 @@ export function joinSubject(url, options) {
         });
         if (!listing)
             return null;
-        if (wanted !== "" && listing.channels.includes(wanted))
-            return { title: wanted, where: listing.name };
+        if (wanted !== "") {
+            // A join link names a channel by id; the directory row names it by
+            // name; the lineup knows both. An older server's listing has names
+            // alone, and is matched on those as before.
+            const entry = listing.lineup.find((one) => one.id === wanted) ?? listing.lineup.find((one) => one.name === wanted);
+            if (entry)
+                return withArt({ title: entry.name, where: listing.name }, entry);
+            if (listing.channels.includes(wanted))
+                return { title: wanted, where: listing.name };
+        }
         return { title: listing.name, where: "" };
     }
     // A link to somewhere else is that server's to name.
@@ -1142,18 +1226,38 @@ export function joinSubject(url, options) {
     const name = options.serverName ?? "";
     if (wanted !== "") {
         const channel = options.channels?.list().find((one) => one.id === wanted || one.name === wanted);
-        return channel ? { title: channel.name, where: name } : null;
+        if (!channel)
+            return null;
+        // Its picture as a crawler reaches it: absolute, with the listen key,
+        // which the listing this server publishes carries anyway.
+        const listen = options.live?.status().url ?? "";
+        const entry = listen ? lineupEntry(listen, channel) : undefined;
+        return withArt({ title: channel.name, where: name }, entry);
     }
     return name === "" ? null : { title: name, where: "" };
 }
-/** The shell, titled for what a join link opens. */
+/** The shell, titled for what a join link opens, with its picture on the card. */
 export function joinDocument(shell, subject, site) {
     const brand = brandOf(shell, site);
     const shellTitle = /<title>([^<]*)<\/title>/i.exec(shell)?.[1] ?? "";
     const title = `${subject.title} — ${brand}`;
-    const description = subject.where === ""
+    const where = subject.where === ""
         ? `${subject.title} is live on ${brand}. Tune in free, no account needed.`
         : `${subject.title} is live on ${subject.where}. Tune in free on ${brand}, no account needed.`;
+    // What it is about comes first, then where it is: a card has two lines.
+    const description = subject.about ? `${subject.about} — ${where}` : where;
+    const image = subject.image ?? "";
+    // A frame of a picture is wide and fills the card; a sleeve is square and
+    // sits beside the words. Twitter has a card for each and picks neither
+    // without being told; everything else reads og:image and decides itself.
+    const card = image === "" ? "" : [
+        `<meta property="og:image" content="${htmlText(image)}" />`,
+        `<meta property="og:image:alt" content="${htmlText(subject.title)}" />`,
+        `<meta name="twitter:card" content="${subject.kind === "video" ? "summary_large_image" : "summary"}" />`,
+        `<meta name="twitter:title" content="${htmlText(subject.title)}" />`,
+        `<meta name="twitter:description" content="${htmlText(description)}" />`,
+        `<meta name="twitter:image" content="${htmlText(image)}" />`,
+    ].map((line) => `${line}\n    `).join("");
     return shell
         .replace(/<title>.*?<\/title>/s, `<title>${htmlText(title)}</title>`)
         .replace(/<meta name="description" content="[^"]*"\s*\/>/, `<meta name="description" content="${htmlText(description)}" />`)
@@ -1161,7 +1265,7 @@ export function joinDocument(shell, subject, site) {
         .replace(/<meta property="og:description" content="[^"]*"\s*\/>/, `<meta property="og:description" content="${htmlText(description)}" />`)
         // What the tab is called once the page takes over, so it does not stack
         // the channel on a title that already names the channel.
-        .replace("</head>", `<meta name="nixamp-shell-title" content="${htmlText(shellTitle)}" />\n  </head>`);
+        .replace("</head>", `${card}<meta name="nixamp-shell-title" content="${htmlText(shellTitle)}" />\n  </head>`);
 }
 function json(response, code, body) {
     const text = JSON.stringify(body);
@@ -2680,6 +2784,9 @@ export function createHandler(engine, options) {
                     ...(one.playlist ? { entries: one.playlist.length, entry: one.playlistAt ?? 0 } : {}),
                     // The member who put it on, when one did: theirs to take off.
                     startedBy: one.startedBy ?? "",
+                    // A picture of it, and a line about it, where there is one.
+                    art: artOf(one),
+                    about: one.about ?? "",
                 })),
                 // Anything re-streamed into this server is a live stream too, and was
                 // sitting in the middle of the playlist among the files -- which is
@@ -2799,7 +2906,9 @@ export function createHandler(engine, options) {
                         json(response, 429, { error: `this server is already carrying ${MAX_ON_DEMAND} channels on demand; try again in a minute` });
                         return;
                     }
-                    const started = await pullChannel(options.channels, options.ffprobe ?? ["ffprobe"], channelId, entry.title, entry.source);
+                    const started = await pullChannel(options.channels, options.ffprobe ?? ["ffprobe"], channelId, entry.title, entry.source, [], "", 
+                    // The logo the list gave it is its picture.
+                    entry.logo ? { art: entry.logo, about: entry.group } : {});
                     if (!started) {
                         json(response, 409, { error: "that channel is already starting" });
                         return;
@@ -2833,7 +2942,9 @@ export function createHandler(engine, options) {
                     }
                 }
                 if (!options.channels.has(channelId)) {
-                    const started = await pullChannel(options.channels, options.ffprobe ?? ["ffprobe"], channelId, entry.title, entry.source);
+                    const started = await pullChannel(options.channels, options.ffprobe ?? ["ffprobe"], channelId, entry.title, entry.source, [], "", 
+                    // The logo the list gave it is its picture.
+                    entry.logo ? { art: entry.logo, about: entry.group } : {});
                     if (!started) {
                         json(response, 409, { error: "that channel is already starting" });
                         return;
@@ -3020,7 +3131,11 @@ export function createHandler(engine, options) {
                     });
                     return;
                 }
-                const started = await pullChannel(options.channels, options.ffprobe ?? ["ffprobe"], channelId, resolved.title, resolved.media, inputArgsFor(resolved.headers), resolved.audio, resolved.playlist ? { playlist: resolved.playlist } : {});
+                const started = await pullChannel(options.channels, options.ffprobe ?? ["ffprobe"], channelId, resolved.title, resolved.media, inputArgsFor(resolved.headers), resolved.audio, {
+                    ...(resolved.playlist ? { playlist: resolved.playlist } : {}),
+                    ...(resolved.thumbnail ? { art: resolved.thumbnail } : {}),
+                    ...(resolved.about ? { about: resolved.about } : {}),
+                });
                 if (!started) {
                     json(response, 409, { error: "that link is already starting" });
                     return;
@@ -3225,6 +3340,48 @@ export function createHandler(engine, options) {
             const compression = compressionCtx();
             if (compression && (await handleChannelCompression(request, response, compression, id, action, file)))
                 return;
+            // A picture of the channel: the sleeve in the file, or one frame of
+            // what it is sending, as a JPEG. This is what a link preview shows
+            // and what the lock screen shows, and a crawler fetches it with the
+            // listen key on the address, since it holds no cookie.
+            if (action === "art" && (request.method === "GET" || request.method === "HEAD")) {
+                const info = channels.info(id);
+                if (!info || options.carries === false) {
+                    json(response, 404, { error: "nothing is playing on that channel" });
+                    return;
+                }
+                // The site's own picture is where it is; sent there, so one address
+                // per channel serves whichever kind it has.
+                if (info.art && /^https?:\/\//i.test(info.art)) {
+                    response.writeHead(302, { ...CORS, location: info.art, "cache-control": "public, max-age=300" });
+                    response.end();
+                    return;
+                }
+                const ffmpeg = options.ffmpeg ?? ["ffmpeg"];
+                const cover = info.codecs?.cover === true && Boolean(info.source);
+                const cache = options.art ?? new ArtCache();
+                const bytes = cover
+                    ? await cache.get(`${id}:cover:${info.startedAt}`, true, () => {
+                        // With the headers its site wanted, when it came from a link.
+                        const link = [...links.values()].find((one) => one.media === info.source);
+                        return coverArtOf(ffmpeg, info.source, link ? inputArgsFor(link.headers) : []);
+                    })
+                    : info.kind === "video"
+                        ? await cache.get(`${id}:still`, false, () => stillFrom(ffmpeg, channels.opening(id)))
+                        : null;
+                if (!bytes) {
+                    json(response, 404, { error: "that channel has no picture yet" });
+                    return;
+                }
+                response.writeHead(200, {
+                    ...CORS,
+                    "content-type": "image/jpeg",
+                    "content-length": bytes.byteLength,
+                    "cache-control": cover ? "public, max-age=3600" : "public, max-age=60",
+                });
+                response.end(request.method === "HEAD" ? undefined : bytes);
+                return;
+            }
             // The same channel as HLS: a playlist of short files, which is what
             // Safari on an iPhone plays live -- it will not take the endless MP4
             // below, and spun on it a few times before giving up. Packaged on
@@ -4488,10 +4645,15 @@ export async function serve(argv, version = "0.1.0") {
         // The operator drives with the control key, and is not a customer.
         exempt: (request) => key !== null && scopeOf(keyFrom(request, new URL(request.url ?? "/", "http://localhost")), key, null) === "control",
     });
+    // The pictures of channels, taken once each and kept while the channel is on.
+    const art = new ArtCache();
     const channels = new Channels({
         ffmpeg: tools.ffmpeg,
         onStart: (info) => console.log(`  ${info.name} is publishing to "${info.id}" (${info.format} over ${info.via}).`),
-        onEnd: (info) => console.log(`  "${info.id}" stopped.`),
+        onEnd: (info) => {
+            console.log(`  "${info.id}" stopped.`);
+            art.forget(info.id);
+        },
     });
     // 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.
@@ -4534,6 +4696,8 @@ export async function serve(argv, version = "0.1.0") {
             ...(one.position !== undefined ? { position: one.position } : {}),
             ...(one.live !== undefined ? { live: one.live } : {}),
             ...(one.playlist ? { playlist: one.playlist, playlistAt: one.playlistAt ?? 0 } : {}),
+            ...(one.art ? { art: one.art } : {}),
+            ...(one.about ? { about: one.about } : {}),
         }).then((channel) => {
             if (!channel)
                 console.log(`  "${one.id}" is already on.`);
@@ -4984,6 +5148,7 @@ export async function serve(argv, version = "0.1.0") {
         carries: tools.carries !== false,
         cookies: cookiesFile(),
         hls,
+        art,
         ...(captions ? { captions } : {}),
         compression,
         enricher,
@@ -5308,6 +5473,9 @@ export async function serve(argv, version = "0.1.0") {
             // live: CNN" is one somebody can decide about; "5717 tracks" was not.
             playing: () => engine.snapshot(false).playing,
             channels: () => channels.list().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)),
             // 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/package.json

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

package/src/art.ts

@@ -0,0 +1,151 @@
+/**
+ * A picture of a channel, for the places a picture goes: the card a link
+ * unfurls into on a chat or a timeline, the lock screen while it plays,
+ * the row in the directory.
+ *
+ * Three places one can come from, tried in this order by whoever asks.
+ * The site's own, when a pasted link resolved to a thumbnail -- that is a
+ * URL and costs nothing. The sleeve in the file, when a podcast's MP3
+ * carries its cover as an attached picture; ffmpeg reads that one frame
+ * out of the head of the file. And for anything with a picture, a frame
+ * of the picture itself: the channel keeps the last few seconds of what
+ * it is sending, and one frame of that is a screenshot of what is on --
+ * taken from our own output, never by opening the source a second time,
+ * because a panel that allows one connection per film counts that one
+ * against the channel and drops it.
+ *
+ * Every picture comes back as a JPEG no wider than a card wants.
+ */
+import { spawn } from "node:child_process";
+
+/** As wide as a preview card is drawn; anything bigger is bytes for nothing. */
+export const ART_WIDTH = 960;
+/** A picture bigger than this is not a thumbnail. */
+export const ART_MAX_BYTES = 2 * 1024 * 1024;
+/** How long ffmpeg gets to produce one frame before it is not going to. */
+export const ART_TIMEOUT_MS = 20_000;
+/** How long a frame of a live picture stays the frame: it changes, but not that fast. */
+export const STILL_TTL_MS = 60_000;
+
+/** The ffmpeg arguments that turn whatever is on `-i` into one JPEG on stdout. */
+function oneFrame(input: string[], scale = true): string[] {
+  return [
+    "-hide_banner", "-loglevel", "error", "-nostdin",
+    ...input,
+    "-map", "0:v:0",
+    "-frames:v", "1",
+    // No wider than the card, never upscaled, and an even height so the
+    // encoder does not refuse an odd one.
+    ...(scale ? ["-vf", `scale='min(${ART_WIDTH},iw)':-2`] : []),
+    "-c:v", "mjpeg", "-q:v", "4",
+    "-f", "image2", "pipe:1",
+  ];
+}
+
+/**
+ * Run ffmpeg for one picture: feed it `stdin` when there is something to
+ * feed, read stdout until it ends, and answer the JPEG or null. Never
+ * throws: a source with no picture, a decoder that cannot start, a frame
+ * that takes too long, all answer null and the caller shows nothing.
+ */
+function picture(ffmpeg: string[], args: string[], stdin: Buffer[] | null): Promise<Buffer | null> {
+  const [command, ...prefix] = ffmpeg;
+  if (!command) return Promise.resolve(null);
+  return new Promise((done) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let settled = false;
+    const finish = (answer: Buffer | null): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      done(answer);
+    };
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command, [...prefix, ...args], { stdio: [stdin ? "pipe" : "ignore", "pipe", "ignore"] });
+    } catch {
+      finish(null);
+      return;
+    }
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish(null);
+    }, ART_TIMEOUT_MS);
+    child.on("error", () => finish(null));
+    child.stdout?.on("data", (chunk: Buffer) => {
+      size += chunk.byteLength;
+      if (size <= ART_MAX_BYTES) chunks.push(chunk);
+    });
+    child.on("close", () => {
+      const bytes = Buffer.concat(chunks);
+      // A JPEG starts FF D8; anything else is ffmpeg having written nothing.
+      finish(size > 0 && size <= ART_MAX_BYTES && bytes[0] === 0xff && bytes[1] === 0xd8 ? bytes : null);
+    });
+    if (stdin && child.stdin) {
+      const input = child.stdin;
+      input.on("error", () => { /* ffmpeg stopped reading once it had its frame */ });
+      for (const piece of stdin) input.write(piece);
+      input.end();
+    }
+  });
+}
+
+/**
+ * The sleeve in a file: the attached picture at the head of a podcast's
+ * MP3 or M4A, read with the same input arguments the channel dials with
+ * (a site's headers, say). ffmpeg stops after the one frame, so a file of
+ * an hour costs the head of it. Null when there is none.
+ */
+export function coverArtOf(ffmpeg: string[], source: string, input: string[] = []): Promise<Buffer | null> {
+  return picture(ffmpeg, oneFrame([...input, "-i", source]), null);
+}
+
+/**
+ * One frame of what a channel is sending now, decoded from the opening
+ * boxes and the recent backlog it hands every new listener. The bytes are
+ * a fragmented MP4 that ffmpeg reads from a pipe as it would from a file.
+ * Null while the channel has no backlog yet, or for a channel of sound.
+ */
+export function stillFrom(ffmpeg: string[], opening: Buffer[]): Promise<Buffer | null> {
+  if (opening.length === 0 || opening.every((piece) => piece.byteLength === 0)) return Promise.resolve(null);
+  return picture(ffmpeg, oneFrame(["-f", "mp4", "-i", "pipe:0"]), opening);
+}
+
+/**
+ * The pictures already taken, so a card that is unfurled by five crawlers
+ * at once costs one ffmpeg, and a sleeve is read from the file once. A
+ * still of a live picture is kept for a minute and taken again; a sleeve
+ * is kept for as long as the channel is on.
+ */
+export class ArtCache {
+  private readonly kept = new Map<string, { at: number; forever: boolean; bytes: Buffer | null; pending?: Promise<Buffer | null> }>();
+
+  constructor(private readonly now: () => number = () => Date.now()) {}
+
+  /**
+   * The picture for a key, taking it with `take` when there is none fresh
+   * enough. A picture that came back null is remembered as null for the
+   * same while, so a channel with no picture is not asked every second.
+   */
+  async get(key: string, forever: boolean, take: () => Promise<Buffer | null>): Promise<Buffer | null> {
+    const have = this.kept.get(key);
+    if (have) {
+      if (have.pending) return have.pending;
+      if (have.forever || this.now() - have.at < STILL_TTL_MS) return have.bytes;
+    }
+    const pending = take().then((bytes) => {
+      this.kept.set(key, { at: this.now(), forever: forever && bytes !== null, bytes });
+      return bytes;
+    });
+    this.kept.set(key, { at: this.now(), forever: false, bytes: null, pending });
+    return pending;
+  }
+
+  /** A channel went off: its pictures with it. */
+  forget(prefix: string): void {
+    for (const key of this.kept.keys()) {
+      if (key === prefix || key.startsWith(`${prefix}:`)) this.kept.delete(key);
+    }
+  }
+}