nixamp 0.52.2 → 0.53.3

package/dist/stations.js

@@ -284,6 +284,10 @@ export class StationStore {
         let listed = access.listed === undefined ? station.listed : access.listed === true;
         if (visibility !== "public")
             listed = false;
+        // Made private, a station forgets what was declared for it: going public
+        // again asks afresh, so a stale (or false) declaration cannot republish it.
+        if (visibility === "private" && !access.rights)
+            station.rights = null;
         if (access.rights) {
             const basis = access.rights.basis;
             if (typeof basis !== "string" || !RIGHTS_BASES.includes(basis)) {
@@ -360,6 +364,38 @@ export function shuffled(length, random = Math.random) {
     }
     return order;
 }
+/**
+ * A radio shuffle: the whole list in a random order, with no artist twice in
+ * a row while another is left to play. A plain shuffle of a genre where a few
+ * artists have whole albums kept playing one artist in series. Each pick is
+ * an artist drawn by how many of their tracks are left, so the spread stays
+ * even to the end, then one of that artist's tracks at random.
+ */
+export function spreadByArtist(files, artistOf, random = Math.random) {
+    const groups = new Map();
+    files.forEach((file, index) => {
+        const key = artistOf(file).trim().toLowerCase();
+        const group = groups.get(key);
+        if (group)
+            group.push(index);
+        else
+            groups.set(key, [index]);
+    });
+    const left = [...groups.entries()].map(([key, indexes]) => ({ key, indexes: shuffled(indexes.length, random).map((one) => indexes[one]) }));
+    const order = [];
+    let last = "";
+    let total = files.length;
+    while (total > 0) {
+        const others = left.filter((one) => one.indexes.length > 0 && one.key !== last);
+        const pool = others.length > 0 ? others : left.filter((one) => one.indexes.length > 0);
+        let pick = random() * pool.reduce((sum, one) => sum + one.indexes.length, 0);
+        const group = pool.find((one) => (pick -= one.indexes.length) < 0) ?? pool[pool.length - 1];
+        order.push(group.indexes.pop());
+        last = group.key;
+        total -= 1;
+    }
+    return order;
+}
 /**
  * Restart after an unexpected end: 2 s, doubling, at most a minute apart.
  * After the last of these the station is offline but still wanted, and is

package/package.json

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

package/src/ai-label.ts

@@ -28,7 +28,7 @@
  */
 import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import { aiKey } from "./ai-keys.ts";
 import { composerFromEnv, OutOfCredit, type Composer } from "./ai-radio.ts";
@@ -51,6 +51,10 @@ export interface LabelSong {
   lyricsFile: string;
   /** Its music video (001. <title>.mp4), "" until made; absent on songs from before videos. */
   video?: string;
+  /** Whether the video carries its song's tags (videos from 0.52.1 and before do not, until retagged). */
+  videoTagged?: boolean;
+  /** 2 for a storyboard video (scenes that move); absent or 1 for the cover-and-waveform kind, which is made again. */
+  videoVersion?: number;
   /** Who wrote the words and who sang them, e.g. "llama-3.3 + elevenlabs/music_v2_5". */
   made: string;
   composedAt: number;
@@ -518,11 +522,98 @@ export async function workersAiCover(prompt: string, env: Record<string, string
   return image;
 }
 
-/** Writes the tags (and the cover, as the attached picture) into a copy of the file. */
+const STORYBOARD_SYSTEM = [
+  "You storyboard music videos for original songs. Write one image prompt per scene, in order, following the song's story and mood.",
+  "Keep the same main character(s), setting and color palette across scenes so it reads as one video; vary the shots (wide, close-up, action, detail).",
+  "Each prompt: cinematic, photorealistic or stylized to suit the genre, at most 300 characters. No text, letters, logos, real people or real brands.",
+  "Answer as JSON: {\"scenes\": [\"prompt\", ...]}.",
+].join(" ");
+
+/** Image prompts for a song's video, one a scene, from its words and mood. */
+export async function writeStoryboard(
+  artist: Pick<LabelArtist, "name" | "genre" | "sound">,
+  album: Pick<LabelAlbum, "title" | "concept">,
+  song: Pick<LabelSong, "title" | "style" | "lyrics">,
+  scenes: number,
+  ask: typeof askJson = askJson,
+): Promise<string[]> {
+  const answer = await ask({
+    system: STORYBOARD_SYSTEM,
+    prompt: [
+      `Song: "${song.title}" by ${artist.name} (${artist.genre}; ${artist.sound}), from "${album.title}"${album.concept ? `: ${album.concept}` : ""}`,
+      `Mood and arrangement: ${song.style}`,
+      song.lyrics ? `Lyrics:\n${song.lyrics.slice(0, 1800)}` : "",
+      `Exactly ${scenes} scenes.`,
+    ].filter(Boolean).join("\n"),
+    maxTokens: 2500,
+    timeoutMs: 90_000,
+  });
+  const list = Array.isArray(answer.value["scenes"]) ? answer.value["scenes"] : [];
+  const prompts = list.map((one) => clean(one, 400)).filter((one) => one.length > 10).slice(0, scenes);
+  if (prompts.length < 2) throw new Error("the model wrote no storyboard");
+  return prompts;
+}
+
+/** The DejaVu bold face most Linux boxes have, for the title card; "" when there is none. */
+function titleFont(): string {
+  for (const file of ["/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", "/usr/share/fonts/dejavu/DejaVuSans-Bold.ttf", "/System/Library/Fonts/Supplemental/Arial Bold.ttf"]) {
+    try { if (statSync(file).isFile()) return file; } catch { /* next */ }
+  }
+  return "";
+}
+
+/** ffmpeg at the lowest priority, so the stations it shares the machine with come first. */
+function runLow(ffmpeg: string[], args: string[], timeout: number, what: string): Promise<void> {
+  const nice = process.platform === "linux" ? (() => { try { return statSync("/usr/bin/nice").isFile(); } catch { return false; } })() : false;
+  const [bin, rest] = nice ? ["/usr/bin/nice", ["-n", "19", ffmpeg[0]!, ...args]] : [ffmpeg[0]!, args];
+  return new Promise((done, fail) => {
+    execFile(bin, rest, { timeout, maxBuffer: 4 * 1024 * 1024 }, (error) => (error ? fail(new Error(`${what}: ${error.message}`)) : done()));
+  });
+}
+
+/**
+ * A song's music video from its storyboard: each scene's picture moves (a
+ * slow zoom in, a pan, a zoom out, a pan back, in turn), scenes cross-fade,
+ * the artist and title come up at the start, and the MP3's audio and tags
+ * (title, artist, album, words) are copied in. 720p H.264.
+ */
+export function renderStoryVideo(ffmpeg: string[], input: { audio: string; images: string[]; seconds: number; artist: string; title: string; out: string }): Promise<void> {
+  const fade = 1;
+  const count = input.images.length;
+  const each = input.seconds / count + fade;
+  const frames = Math.max(25, Math.round(each * 25));
+  const moves = [
+    `z='1+0.15*on/${frames}':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'`,
+    `z='1.15':x='(iw-iw/zoom)*on/${frames}':y='ih/2-(ih/zoom/2)'`,
+    `z='1.15-0.15*on/${frames}':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'`,
+    `z='1.15':x='(iw-iw/zoom)*(1-on/${frames})':y='(ih-ih/zoom)*on/${frames}'`,
+  ];
+  const parts: string[] = [];
+  input.images.forEach((_, i) => {
+    parts.push(`[${i}:v]scale=1600:900:force_original_aspect_ratio=increase,crop=1600:900,zoompan=${moves[i % moves.length]}:d=1:s=1280x720:fps=25,setsar=1[v${i}]`);
+  });
+  let last = "v0";
+  for (let i = 1; i < count; i++) {
+    parts.push(`[${last}][v${i}]xfade=transition=fade:duration=${fade}:offset=${(i * (each - fade)).toFixed(2)}[x${i}]`);
+    last = `x${i}`;
+  }
+  const font = titleFont();
+  const card = `${input.artist} — ${input.title}`.replace(/[\\':%]/g, " ").slice(0, 80);
+  parts.push(font
+    ? `[${last}]drawtext=fontfile=${font}:text='${card}':fontcolor=white:fontsize=44:x=60:y=h-110:enable='between(t,0.5,6)':alpha='if(lt(t,1.5),t-0.5,if(gt(t,5),6-t,1))':shadowcolor=black@0.7:shadowx=2:shadowy=2,format=yuv420p[v]`
+    : `[${last}]format=yuv420p[v]`);
+  const args = ["-hide_banner", "-loglevel", "error", "-y", "-threads", "2",
+    ...input.images.flatMap((image) => ["-loop", "1", "-t", each.toFixed(2), "-i", image]),
+    "-i", input.audio, "-filter_complex", parts.join(";"),
+    "-map", "[v]", "-map", `${count}:a`, "-map_metadata", String(count), "-c:v", "libx264", "-preset", "veryfast", "-crf", "24", "-r", "25", "-c:a", "copy", "-shortest",
+    "-movflags", "+faststart+use_metadata_tags", input.out];
+  return runLow(ffmpeg, [...ffmpeg.slice(1), ...args], 60 * 60_000, "the video failed");
+}
+
 /**
- * A song's music video: its album cover over a blurred copy of itself, the
- * song's waveform along the bottom, 720p H.264 with the MP3's audio copied in.
- * Without a cover, a dark plate.
+ * A song's music video without a storyboard: its album cover over a blurred
+ * copy of itself, the song's waveform along the bottom, 720p H.264 with the
+ * MP3's audio and tags copied in. Without a cover, a dark plate.
  */
 export function renderVideo(ffmpeg: string[], audio: string, cover: string, out: string): Promise<void> {
   const picture = cover ? ["-loop", "1", "-framerate", "25", "-i", cover] : ["-f", "lavfi", "-i", "color=c=0x0d1410:s=1280x720:r=25"];
@@ -534,12 +625,21 @@ export function renderVideo(ffmpeg: string[], audio: string, cover: string, out:
     "[a][viz]overlay=0:H-160,format=yuv420p[v]",
   ].join(";");
   const args = [...ffmpeg.slice(1), "-hide_banner", "-loglevel", "error", "-y", ...picture, "-i", audio, "-filter_complex", graph,
-    "-map", "[v]", "-map", "1:a", "-c:v", "libx264", "-preset", "veryfast", "-crf", "26", "-r", "25", "-c:a", "copy", "-shortest", "-movflags", "+faststart", out];
+    "-map", "[v]", "-map", "1:a", "-map_metadata", "1", "-c:v", "libx264", "-preset", "veryfast", "-crf", "26", "-r", "25", "-c:a", "copy", "-shortest",
+    "-movflags", "+faststart+use_metadata_tags", out];
+  return runLow(ffmpeg, args, 20 * 60_000, "the video failed");
+}
+
+/** A video made before videos carried tags, given its song's: streams copied, nothing re-encoded. */
+export function retagVideo(ffmpeg: string[], video: string, audio: string, out: string): Promise<void> {
+  const args = [...ffmpeg.slice(1), "-hide_banner", "-loglevel", "error", "-y", "-i", video, "-i", audio,
+    "-map", "0:v", "-map", "0:a", "-map_metadata", "1", "-c", "copy", "-movflags", "+faststart+use_metadata_tags", out];
   return new Promise((done, fail) => {
-    execFile(ffmpeg[0]!, args, { timeout: 20 * 60_000 }, (error) => (error ? fail(new Error(`the video failed: ${error.message}`)) : done()));
+    execFile(ffmpeg[0]!, args, { timeout: 5 * 60_000 }, (error) => (error ? fail(new Error(`retagging the video failed: ${error.message}`)) : done()));
   });
 }
 
+/** Writes the tags (and the cover, as the attached picture) into a copy of the file. */
 function tagFile(ffmpeg: string[], from: string, to: string, tags: Record<string, string>, cover: string): Promise<void> {
   const args = [...ffmpeg.slice(1), "-hide_banner", "-loglevel", "error", "-y", "-i", from];
   if (cover) args.push("-i", cover, "-map", "0:a", "-map", "1:v", "-c", "copy", "-disposition:v", "attached_pic");
@@ -574,6 +674,10 @@ export interface AiLabelDeps {
   tag?: (from: string, to: string, tags: Record<string, string>, cover: string) => Promise<void>;
   /** Renders a song's music video to `out`; ffmpeg by default (renderVideo). */
   video?: (audio: string, cover: string, out: string) => Promise<void>;
+  /** Renders a storyboard music video; ffmpeg by default (renderStoryVideo). */
+  storyVideo?: (input: { audio: string; images: string[]; seconds: number; artist: string; title: string; out: string }) => Promise<void>;
+  /** A scene's picture for this prompt, or null when nothing can draw one; Workers AI by default. */
+  image?: (prompt: string) => Promise<Buffer | null>;
   /** The day's pick (artist, genre, new or not); Math.random by default. */
   random?: () => number;
   now?: () => number;
@@ -596,6 +700,8 @@ export class AiLabel {
   private filming: Promise<number> | null = null;
   /** Songs whose video failed since this server started. */
   private videoFailed = new Set<string>();
+  /** Old videos already tried as storyboards since this server started. */
+  private upgradeTried = new Set<string>();
   /** The day's album is tried at most every 30 minutes, so a failing model is not hammered. */
   private dailyTriedAt = 0;
   /** Genre stations are kept in step one change at a time. */
@@ -865,37 +971,104 @@ export class AiLabel {
     return total;
   }
 
+  /**
+   * One pass: songs without a video first, then old videos given their
+   * song's tags (seconds each), then old cover-and-waveform videos made again
+   * as storyboards.
+   */
   private async filmPass(): Promise<number> {
+    const songs = this.list().flatMap((artist) => artist.albums
+      .filter((album) => album.cover || album.coverTried)
+      .flatMap((album) => album.songs.filter((song) => song.file && !this.videoFailed.has(song.file)).map((song) => ({ artist, album, song }))));
+    const missing = songs.filter(({ song }) => !song.video);
+    const untagged = songs.filter(({ song }) => song.video && !song.videoTagged);
+    const old = songs.filter(({ song }) => song.video && song.videoTagged && (song.videoVersion ?? 1) < 2 && !this.upgradeTried.has(song.file));
     let made = 0;
-    {
-      for (const artist of this.list()) {
-        for (const album of artist.albums) {
-          if (!album.cover && !album.coverTried) continue;
-          for (const song of album.songs) {
-            if (!song.file || song.video || this.videoFailed.has(song.file) || !this.settings.videos) continue;
-            const out = join(album.folder, `${songBase(song)}.mp4`);
-            const partial = join(album.folder, `.${randomBytes(4).toString("hex")}.video.mp4`);
-            try {
-              await (this.deps.video ?? ((audio, cover, to) => renderVideo(this.deps.ffmpeg, audio, cover, to)))(song.file, album.cover, partial);
-              renameSync(partial, out);
-              song.video = out;
-              made += 1;
-              this.save();
-              // On the air as soon as it is made, not after the whole pass.
-              await this.placeVideos().catch(() => undefined);
-            } catch (error) {
-              this.videoFailed.add(song.file);
-              this.log(`no video for "${song.title}": ${(error as Error).message}`);
-            } finally {
-              rmSync(partial, { force: true });
-            }
-          }
-        }
+    for (const { album, song } of untagged) {
+      if (!this.settings.videos) break;
+      // Made before videos carried tags: give it its song's, in place.
+      const partial = join(album.folder, `.${randomBytes(4).toString("hex")}.retag.mp4`);
+      try {
+        await retagVideo(this.deps.ffmpeg, song.video!, song.file, partial);
+        renameSync(partial, song.video!);
+        song.videoTagged = true;
+        made += 1;
+        this.save();
+      } catch (error) {
+        this.log(`could not tag the video of "${song.title}": ${(error as Error).message}`);
+        song.videoTagged = true; // a storyboard remake brings the tags anyway
+      } finally {
+        rmSync(partial, { force: true });
+      }
+    }
+    for (const { artist, album, song } of [...missing, ...old]) {
+      if (!this.settings.videos) break;
+      // An old video is only made again as a storyboard, and tried once a run.
+      const upgrade = Boolean(song.video);
+      if (upgrade) this.upgradeTried.add(song.file);
+      const out = join(album.folder, `${songBase(song)}.mp4`);
+      const partial = join(album.folder, `.${randomBytes(4).toString("hex")}.video.mp4`);
+      const scenes = join(album.folder, `.scenes-${song.n}-${randomBytes(3).toString("hex")}`);
+      try {
+        song.videoVersion = await this.filmSong(artist, album, song, scenes, partial, upgrade);
+        renameSync(partial, out);
+        song.video = out;
+        song.videoTagged = true;
+        made += 1;
+        this.save();
+        // On the air as soon as it is made, not after the whole pass.
+        await this.placeVideos().catch(() => undefined);
+      } catch (error) {
+        if (!upgrade) this.videoFailed.add(song.file);
+        this.log(`no ${upgrade ? "storyboard " : ""}video for "${song.title}": ${(error as Error).message}`);
+      } finally {
+        rmSync(partial, { force: true });
+        rmSync(scenes, { recursive: true, force: true });
       }
     }
     return made;
   }
 
+  /**
+   * One song's video: a storyboard of scenes when a model can write it and an
+   * image model can draw it (version 2), else the cover-and-waveform kind (1).
+   */
+  private async filmSong(artist: LabelArtist, album: LabelAlbum, song: LabelSong, scenes: string, out: string, storyOnly = false): Promise<number> {
+    let seconds = song.seconds;
+    try {
+      const probed = await this.deps.probe(song.file);
+      if (probed.duration > 5) seconds = probed.duration;
+    } catch { /* the asked-for length */ }
+    const images: string[] = [];
+    if (this.canAsk()) {
+      try {
+        const count = Math.max(4, Math.min(16, Math.round(seconds / 9)));
+        const prompts = await writeStoryboard(artist, album, song, count, this.deps.ask ?? askJson);
+        mkdirSync(scenes, { recursive: true });
+        const draw = this.deps.image ?? ((prompt: string) => workersAiCover(prompt));
+        // A few at a time: the image model is quick, the machine is shared.
+        for (let i = 0; i < prompts.length; i += 3) {
+          const drawn = await Promise.all(prompts.slice(i, i + 3).map((prompt) => draw(`${prompt} Cinematic 16:9 music video still, no text.`).catch(() => null)));
+          drawn.forEach((picture, j) => {
+            if (!picture) return;
+            const file = join(scenes, `${String(i + j).padStart(2, "0")}.jpg`);
+            writeFileSync(file, picture);
+            images.push(file);
+          });
+        }
+      } catch (error) {
+        this.log(`no storyboard for "${song.title}" (${(error as Error).message}); the cover video instead`);
+      }
+    }
+    if (images.length >= 2) {
+      await (this.deps.storyVideo ?? ((input) => renderStoryVideo(this.deps.ffmpeg, input)))({ audio: song.file, images, seconds, artist: artist.name, title: song.title, out });
+      return 2;
+    }
+    if (storyOnly) throw new Error("no storyboard could be drawn; the video it has stays");
+    await (this.deps.video ?? ((audio, cover, to) => renderVideo(this.deps.ffmpeg, audio, cover, to)))(song.file, album.cover, out);
+    return 1;
+  }
+
   /** The label's music videos as one TV station: free to watch, with its breaks. */
   private placeVideos(): Promise<void> {
     const next = this.placing.then(async () => {
@@ -1257,6 +1430,18 @@ export class AiLabel {
     return null;
   }
 
+  /** The song's MP3 when `file` is one of the label's music videos (it holds the tags, cover and words); else `file`. */
+  audioFor(file: string): string {
+    if (!file.endsWith(".mp4")) return file;
+    for (const artist of this.artists.values()) {
+      for (const album of artist.albums) {
+        const song = album.songs.find((one) => one.video === file);
+        if (song) return song.file;
+      }
+    }
+    return file;
+  }
+
   /** A released song's MP3, when this grant's scope covers it. */
   songFile(artistKey: string, albumKey: string, n: number): string {
     return this.artists.get(artistKey)?.albums.find((one) => one.key === albumKey)?.songs.find((one) => one.n === n && one.file)?.file ?? "";

package/src/channels.ts

@@ -586,6 +586,8 @@ export class Channel {
             const seconds = Number(match[1]) / 1e6;
             if (playlistInput) {
               const place = playlistInput.place(seconds);
+              // A break (-1) belongs to no list; a track's index belongs to its own.
+              if (place.at >= 0 && this.info.playlist !== place.list) this.info.playlist = place.list as string[];
               this.info.playlistAt = place.at;
               this.info.position = place.position;
             } else this.info.position = from + seconds;

package/src/playlist-input.ts

@@ -22,7 +22,7 @@ export interface PlaylistInput {
    * pass: a station-wide shuffle is one order for everybody listening, drawn
    * again each time round. Unset is the list's own order.
    */
-  order?: (length: number) => number[];
+  order?: (length: number, files: readonly string[]) => number[];
   /** Read at every entry boundary, so an edit to the list lands on the next track. */
   current?: () => string[];
   /** Entries already known not to play, passed over without being tried. */
@@ -56,7 +56,7 @@ export const MAX_FAILURES_IN_A_ROW = 5;
  * whose input codecs differ. Only one entry is encoded at a time, with pipe
  * backpressure bounding read-ahead independently of the directory's size. */
 export class PlaylistInputStream {
-  private entries: { at: number; file: string; start: number; position: number }[] = [];
+  private entries: { at: number; file: string; start: number; position: number; list: readonly string[] }[] = [];
   error: Error | null = null;
   complete = false;
   /**
@@ -68,14 +68,20 @@ export class PlaylistInputStream {
   constructor(private readonly options: PlaylistInput) {}
 
   /** Every entry that has started, in the order it started, with where it sits in the stream. */
-  get history(): ReadonlyArray<{ at: number; file: string; start: number; position: number }> {
+  get history(): ReadonlyArray<{ at: number; file: string; start: number; position: number; list: readonly string[] }> {
     return this.entries;
   }
 
-  place(seconds: number): { at: number; position: number } {
+  /**
+   * What is on at this point of the stream. `at` indexes `list`, the list as
+   * it was when that entry started: a station re-reads its list at every
+   * boundary, so after the library changes the index no longer fits the
+   * list the channel was dialled with.
+   */
+  place(seconds: number): { at: number; position: number; list: readonly string[] } {
     const entry = this.entries.findLast(one => seconds >= one.start) ?? this.entries[0];
-    return entry ? { at: entry.at, position: Math.max(0, seconds - entry.start + entry.position) }
-      : { at: this.options.at, position: this.options.position };
+    return entry ? { at: entry.at, position: Math.max(0, seconds - entry.start + entry.position), list: entry.list }
+      : { at: this.options.at, position: this.options.position, list: this.options.files };
   }
 
   /** The decoder for the entry that is on, so skip() can end it early. */
@@ -101,7 +107,7 @@ export class PlaylistInputStream {
     let first = true;
     try {
       const orderFor = (list: string[]): number[] =>
-        o.order ? o.order(list.length).filter((one) => one >= 0 && one < list.length) : list.map((_, index) => index);
+        o.order ? o.order(list.length, list).filter((one) => one >= 0 && one < list.length) : list.map((_, index) => index);
       let files = o.current?.() ?? o.files;
       if (files.length === 0) throw new Error("The playlist is empty");
       let order = orderFor(files);
@@ -173,7 +179,7 @@ export class PlaylistInputStream {
             const room = o.video && !isBreak && o.breaks && every > 0 ? every - (offset - lastBreak) : Infinity;
             const cut = room >= 1 && full - room > 5;
             const duration = cut ? room : full;
-            this.entries.push({ at, file, start: offset, position });
+            this.entries.push({ at, file, start: offset, position, list: files });
             const hasVideo = Boolean(codecs.video);
             const extra = o.video && !hasVideo
               ? ["-f", "lavfi", "-i", `color=c=black:s=${width}x${height}:r=30`]

package/src/server.ts

@@ -3165,6 +3165,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
         },
         trackFor: (file) => trackFor(engine, file),
         ...(options.library ? { isVideo: (file: string) => options.library!.index.itemAt(file)?.video === true } : {}),
+        ...(options.library ? { durationOf: (file: string) => options.library!.index.itemAt(file)?.duration ?? 0 } : {}),
         base: `${scheme}://${request.headers.host ?? "localhost"}`,
         publicBase: options.stations.publicBase?.() ?? "",
         json,
@@ -7211,6 +7212,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     breaks: (video) => stationBreaks.next(video ? "video" : "audio"),
     onRestart: (id) => stationUsage.restarted(id),
     onFailure: (id) => stationUsage.failed(id),
+    artistOf: (file) => trackFor(engine, file)?.artist ?? "",
     store: stationStore,
     channels,
     pull: async (channelId, name, files, known) =>
@@ -7370,7 +7372,9 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   stations.holders = holderStore;
   // Covers read once per file (and its size and time), a few hundred kept.
   const covers = new Map<string, { key: string; picture: { bytes: Buffer; type: string } | null }>();
-  stations.cover = async (file) => {
+  stations.cover = async (playing) => {
+    // A label music video's cover is its song's.
+    const file = aiLabel.audioFor(playing);
     let key = "";
     try { const info = statSync(file); key = `${info.size}:${info.mtimeMs}`; } catch { return null; }
     const hit = covers.get(file);
@@ -7383,7 +7387,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   };
   // The words of what is on: the file's own tag, else nichedb.dev's.
   const lyricsFinder = new LyricsFinder({ tags: (file) => tagReader.read(file), known: (file) => trackFor(engine, file) });
-  stations.lyrics = (_station, file) => lyricsFinder.find(file);
+  stations.lyrics = (_station, file) => lyricsFinder.find(aiLabel.audioFor(file));
   // Our own songs' words, back to nichedb, when a key is set: on any station
   // change, after a library scan, and once at start.
   const lyricsPublisher = new LyricsPublisher({
@@ -7409,9 +7413,11 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     let stamp = "";
     try { stamp = String(Math.round(statSync(file).mtimeMs)); } catch { stamp = ""; }
     const art = picture ? `/api/v1/stations/${station.id}/art?t=${encodeURIComponent(station.listenToken)}&f=${sha("sha1").update(file + stamp).digest("hex").slice(0, 12)}` : "";
-    const words = await lyricsFinder.find(file).catch(() => null);
+    // A label music video is told about as its song: the MP3 holds the tags and the words.
+    const audio = aiLabel.audioFor(file);
+    const words = await lyricsFinder.find(audio).catch(() => null);
     // A label song is for sale on nixamp.com: the song, its album, everything by the artist.
-    const song = aiLabel.songAt(file);
+    const song = aiLabel.songAt(audio);
     const here = stations.publicBase?.() ?? "";
     const shop = (process.env["NIXAMP_SITE"] || "https://nixamp.com").replace(/\/+$/, "");
     const store = song && /^https:\/\//.test(here) ? {
@@ -7425,8 +7431,8 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
       art,
       ...(words ? { lyrics: `/api/v1/stations/${station.id}/lyrics?t=${encodeURIComponent(station.listenToken)}&f=${sha("sha1").update(file + stamp).digest("hex").slice(0, 12)}` } : {}),
       station, file,
-      tags: await tagReader.read(file),
-      known: trackFor(engine, file),
+      tags: await tagReader.read(audio),
+      known: trackFor(engine, audio),
       holders: holderStore.list(),
       share: share ? { basis: share.rights.basis, note: share.rights.note, by: share.by } : null,
       aiTrack: composed ? { made: composed.made } : null,

package/src/station-routes.ts

@@ -66,6 +66,8 @@ export interface StationContext {
   throttle?: () => { retryAfter: number } | null;
   /** What a listener may know about the track on the air (track-facts.ts). */
   facts?: (station: Station, file: string) => Promise<TrackFacts>;
+  /** How long a file is, in seconds (the library's probe); 0 when unknown. For the page's progress bar. */
+  durationOf?: (file: string) => number;
   /** The cover picture inside a file (JPEG/PNG bytes), or null. */
   cover?: (file: string) => Promise<{ bytes: Buffer; type: string } | null>;
   /** The words of a file, from its tags or nichedb; null when none are known. */
@@ -116,6 +118,10 @@ export function publicView(ctx: StationContext, station: Station): PublicStation
   // What the channel is carrying wins over the flag: a station made by hand
   // from films streams video whether or not anyone said so.
   const video = station.video || ctx.channels.kindOf(channelOf(station.id)) === "video";
+  // How far into the song (or film) on the air, by the encoder's clock, and how long it is.
+  const position = file ? ctx.channels.info(channelOf(station.id))?.position : undefined;
+  const duration = file && ctx.durationOf ? ctx.durationOf(file) : 0;
+  const progress = typeof position === "number" && duration > 0 ? { position: Math.round(Math.min(position, duration) * 10) / 10, duration: Math.round(duration * 10) / 10 } : null;
   return {
     id: station.id,
     name: station.name,
@@ -124,6 +130,7 @@ export function publicView(ctx: StationContext, station: Station): PublicStation
     state,
     // Tags, or nothing: a bare file name is the owner's, not the public's.
     nowPlaying: track && (track.title || track.artist) ? track : null,
+    progress,
     kind: video ? "video" : "audio",
     format: state === "stopped" || state === "offline" ? null : video
       ? { codec: "h264+aac", bitrateKbps: station.bitrate, sampleRate: 48_000, channels: 2 }

package/src/station-runner.ts

@@ -11,7 +11,7 @@
  */
 import type { Channels, ChannelInfo, PullResume } from "./channels.ts";
 import {
-  EXCLUDE_AFTER, OFFLINE_RETRY_MS, RECOVERY_DELAYS_MS, StationError, channelOf, insideRoots, shuffled,
+  EXCLUDE_AFTER, OFFLINE_RETRY_MS, RECOVERY_DELAYS_MS, StationError, channelOf, insideRoots, spreadByArtist,
   stationOfChannel, type Observed, type Station, type StationStore,
 } from "./stations.ts";
 
@@ -29,6 +29,20 @@ export interface RunnerDeps {
   onFailure?: (id: string) => void;
   /** A file for a break on a radio (false) or TV (true) station, or null for none. */
   breaks?: (video: boolean) => Promise<string | null>;
+  /** Who a file is by, from the library's tags, for a shuffle that spreads artists out; "" when unknown. */
+  artistOf?: (file: string) => string;
+}
+
+/**
+ * Who a file is by when the tags do not say: "Artist - Album/track" names
+ * them in the folder, and "Artist/Album/track" one folder up.
+ */
+export function artistFromPath(file: string): string {
+  const parts = file.split(/[\\/]/);
+  const folder = parts[parts.length - 2] ?? "";
+  const dash = folder.indexOf(" - ");
+  if (dash > 0) return folder.slice(0, dash);
+  return parts[parts.length - 3] ?? folder;
 }
 
 /** Something a listener is connected through, that can be ended. */
@@ -151,7 +165,9 @@ export class StationRunner {
           repeat: station.repeat,
           passOver: true,
           // Read at every pass, so turning shuffle on or off lands then.
-          order: (length) => (store.get(id)?.shuffle ? shuffled(length) : [...Array(length).keys()]),
+          order: (length, files) => (store.get(id)?.shuffle
+            ? spreadByArtist(files, (file) => this.deps.artistOf?.(file) || artistFromPath(file))
+            : [...Array(length).keys()]),
           // Read at every track, so an edit lands on the next one.
           current: () => {
             const now = store.get(id);

package/src/stations.ts

@@ -338,6 +338,9 @@ export class StationStore {
     }
     let listed = access.listed === undefined ? station.listed : access.listed === true;
     if (visibility !== "public") listed = false;
+    // Made private, a station forgets what was declared for it: going public
+    // again asks afresh, so a stale (or false) declaration cannot republish it.
+    if (visibility === "private" && !access.rights) station.rights = null;
     if (access.rights) {
       const basis = access.rights.basis;
       if (typeof basis !== "string" || !RIGHTS_BASES.includes(basis as RightsBasis)) {
@@ -422,6 +425,36 @@ export function shuffled(length: number, random: () => number = Math.random): nu
   return order;
 }
 
+/**
+ * A radio shuffle: the whole list in a random order, with no artist twice in
+ * a row while another is left to play. A plain shuffle of a genre where a few
+ * artists have whole albums kept playing one artist in series. Each pick is
+ * an artist drawn by how many of their tracks are left, so the spread stays
+ * even to the end, then one of that artist's tracks at random.
+ */
+export function spreadByArtist(files: readonly string[], artistOf: (file: string) => string, random: () => number = Math.random): number[] {
+  const groups = new Map<string, number[]>();
+  files.forEach((file, index) => {
+    const key = artistOf(file).trim().toLowerCase();
+    const group = groups.get(key);
+    if (group) group.push(index); else groups.set(key, [index]);
+  });
+  const left = [...groups.entries()].map(([key, indexes]) => ({ key, indexes: shuffled(indexes.length, random).map((one) => indexes[one]!) }));
+  const order: number[] = [];
+  let last = "";
+  let total = files.length;
+  while (total > 0) {
+    const others = left.filter((one) => one.indexes.length > 0 && one.key !== last);
+    const pool = others.length > 0 ? others : left.filter((one) => one.indexes.length > 0);
+    let pick = random() * pool.reduce((sum, one) => sum + one.indexes.length, 0);
+    const group = pool.find((one) => (pick -= one.indexes.length) < 0) ?? pool[pool.length - 1]!;
+    order.push(group.indexes.pop()!);
+    last = group.key;
+    total -= 1;
+  }
+  return order;
+}
+
 /**
  * Restart after an unexpected end: 2 s, doubling, at most a minute apart.
  * After the last of these the station is offline but still wanted, and is
@@ -440,6 +473,8 @@ export interface PublicStation {
   /** Radio or TV. */
   kind: "audio" | "video";
   nowPlaying: { title: string; artist: string; album: string } | null;
+  /** Seconds into what is on and how long it is, when both are known. */
+  progress?: { position: number; duration: number } | null;
   format: { codec: string; bitrateKbps: number; sampleRate: number; channels: number } | null;
   listeners: number;
 }