nixamp 0.54.0 → 0.55.0

package/dist/ai-label.d.ts

@@ -1,5 +1,6 @@
 import { type Composer } from "./ai-radio.ts";
 import { askJson } from "./ai-text.ts";
+import { type SyncedLine } from "./lyrics.ts";
 import type { LibraryIndex, Probed } from "./library-index.ts";
 import type { StationRunner } from "./station-runner.ts";
 import { type StationStore } from "./stations.ts";
@@ -15,6 +16,8 @@ export interface LabelSong {
     /** The MP3, "" until composed. */
     file: string;
     lyricsFile: string;
+    /** Its words timed to the recording (001. <title>.lrc, enhanced LRC), for karaoke on the station page; absent until aligned. */
+    lrc?: 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). */
@@ -127,6 +130,21 @@ export declare function writeLyrics(artist: Pick<LabelArtist, "name" | "genre" |
  * OPENAI_API_KEY its token); null when there is no image model to ask.
  */
 export declare function workersAiCover(prompt: string, env?: Record<string, string | undefined>, fetcher?: typeof fetch): Promise<Buffer | null>;
+/** A timed word from an aligner: seconds from the start of the song. */
+export interface TimedWord {
+    text: string;
+    start: number;
+    end: number;
+}
+/** ElevenLabs forced alignment: the song and its words in, each word's time out. */
+export declare function elevenLabsAligner(key: string, fetcher?: typeof fetch): (audio: string, text: string) => Promise<TimedWord[]>;
+/** The sung lines of a song's words: section tags ([Chorus]) and blank lines are not sung. */
+export declare function sungLines(lyrics: string): string[];
+/**
+ * Timed words laid back onto the lines they were written in, in order, so
+ * each line and each word knows when it is sung.
+ */
+export declare function syncLines(lyrics: string, timed: TimedWord[]): SyncedLine[];
 /** Image prompts for a song's video, one a scene, from its words and mood. */
 export declare function writeStoryboard(artist: Pick<LabelArtist, "name" | "genre" | "sound">, album: Pick<LabelAlbum, "title" | "concept">, song: Pick<LabelSong, "title" | "style" | "lyrics">, scenes: number, ask?: typeof askJson): Promise<string[]>;
 /**
@@ -169,6 +187,8 @@ 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>;
+    /** Times each sung word in a recording; ElevenLabs forced alignment by default, null without a key. */
+    align?: ((audio: string, text: string) => Promise<TimedWord[]>) | null;
     /** Renders a storyboard music video; ffmpeg by default (renderStoryVideo). */
     storyVideo?: (input: {
         audio: string;
@@ -200,6 +220,8 @@ export declare class AiLabel {
     private filming;
     /** Songs whose video failed since this server started. */
     private videoFailed;
+    /** Songs whose words were already sent to the aligner since this server started. */
+    private alignTried;
     /** Old videos already tried as storyboards since this server started. */
     private upgradeTried;
     /** The day's album is tried at most every 30 minutes, so a failing model is not hammered. */
@@ -246,6 +268,10 @@ export declare class AiLabel {
      * song's tags (seconds each), then old cover-and-waveform videos made again
      * as storyboards.
      */
+    /** The aligner this server can use: the dependency, else ElevenLabs with its key, else none. */
+    private aligner;
+    /** A song's words timed to its recording, written as 001. <title>.lrc beside it. Once per song (a failure is not retried this run). */
+    private sync;
     private filmPass;
     /**
      * One song's video: a storyboard of scenes when a model can write it and an

package/dist/ai-label.js

@@ -33,6 +33,7 @@ import { dirname, join, resolve, sep } from "node:path";
 import { aiKey } from "./ai-keys.js";
 import { composerFromEnv, OutOfCredit } from "./ai-radio.js";
 import { askJson, hasModel } from "./ai-text.js";
+import { formatLrc } from "./lyrics.js";
 import { StationError } from "./stations.js";
 /**
  * The label's first roster: invented names, one genre each, sung in English.
@@ -408,6 +409,53 @@ export async function workersAiCover(prompt, env = process.env, fetcher = fetch)
         throw new Error("the cover model answered with no picture");
     return image;
 }
+/** ElevenLabs forced alignment: the song and its words in, each word's time out. */
+export function elevenLabsAligner(key, fetcher = fetch) {
+    return async (audio, text) => {
+        const form = new FormData();
+        form.append("file", new Blob([readFileSync(audio)], { type: "audio/mpeg" }), "song.mp3");
+        form.append("text", text);
+        const response = await fetcher("https://api.elevenlabs.io/v1/forced-alignment", {
+            method: "POST",
+            headers: { "xi-api-key": key },
+            body: form,
+            signal: AbortSignal.timeout(5 * 60_000),
+        });
+        if (response.status === 401 || response.status === 402)
+            throw new OutOfCredit(`elevenlabs answered HTTP ${response.status} to the alignment`);
+        if (!response.ok)
+            throw new Error(`the alignment answered HTTP ${response.status}`);
+        const body = await response.json();
+        return (body.words ?? [])
+            .map((one) => ({ text: String(one.text ?? "").trim(), start: Number(one.start), end: Number(one.end) }))
+            .filter((one) => one.text && Number.isFinite(one.start) && Number.isFinite(one.end));
+    };
+}
+/** The sung lines of a song's words: section tags ([Chorus]) and blank lines are not sung. */
+export function sungLines(lyrics) {
+    return lyrics.split("\n").map((line) => line.trim()).filter((line) => line && !/^\[[^\]]*\]$/.test(line));
+}
+/**
+ * Timed words laid back onto the lines they were written in, in order, so
+ * each line and each word knows when it is sung.
+ */
+export function syncLines(lyrics, timed) {
+    const out = [];
+    let at = 0;
+    for (const line of sungLines(lyrics)) {
+        const words = line.split(/\s+/).filter(Boolean);
+        const placed = words.map((word) => {
+            const hit = timed[at];
+            if (hit)
+                at += 1;
+            return hit ? { text: word, start: hit.start, end: hit.end } : null;
+        }).filter((one) => one !== null);
+        if (placed.length === 0)
+            break;
+        out.push({ start: placed[0].start, end: placed[placed.length - 1].end, text: line, words: placed });
+    }
+    return out;
+}
 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).",
@@ -555,6 +603,8 @@ export class AiLabel {
     filming = null;
     /** Songs whose video failed since this server started. */
     videoFailed = new Set();
+    /** Songs whose words were already sent to the aligner since this server started. */
+    alignTried = new Set();
     /** Old videos already tried as storyboards since this server started. */
     upgradeTried = new Set();
     /** The day's album is tried at most every 30 minutes, so a failing model is not hammered. */
@@ -844,7 +894,43 @@ export class AiLabel {
      * song's tags (seconds each), then old cover-and-waveform videos made again
      * as storyboards.
      */
+    /** The aligner this server can use: the dependency, else ElevenLabs with its key, else none. */
+    aligner() {
+        if (this.deps.align !== undefined)
+            return this.deps.align;
+        const key = aiKey("ELEVENLABS_API_KEY");
+        return key ? elevenLabsAligner(key) : null;
+    }
+    /** A song's words timed to its recording, written as 001. <title>.lrc beside it. Once per song (a failure is not retried this run). */
+    async sync(artist, album, song) {
+        const align = this.aligner();
+        if (!align || !song.file || !song.lyrics || song.lrc || this.alignTried.has(song.file))
+            return false;
+        this.alignTried.add(song.file);
+        try {
+            const timed = await align(song.file, sungLines(song.lyrics).join("\n"));
+            const lines = syncLines(song.lyrics, timed);
+            if (lines.length === 0)
+                throw new Error("the aligner placed no words");
+            const file = join(album.folder, `${songBase(song)}.lrc`);
+            writeFileSync(file, formatLrc(lines, { title: song.title, artist: artist.name, album: album.title }));
+            song.lrc = file;
+            this.save();
+            return true;
+        }
+        catch (error) {
+            this.log(`could not time the words of "${song.title}": ${error.message}`);
+            return false;
+        }
+    }
     async filmPass() {
+        // Words timed first: quick, and what the station page's karaoke needs.
+        for (const artist of this.list()) {
+            for (const album of artist.albums) {
+                for (const song of album.songs)
+                    await this.sync(artist, album, song);
+            }
+        }
         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 }))));
@@ -1184,7 +1270,8 @@ export class AiLabel {
             this.save();
             this.writeAlbumJson(artist, album);
             await this.place(artist.genre);
-            // Its video is made beside it, without holding up the next song.
+            // Its words timed to the recording, then its video, without holding up the next song.
+            await this.sync(artist, album, song).catch(() => undefined);
             void this.videos();
         }
         catch (error) {
@@ -1364,6 +1451,8 @@ export class AiLabel {
             for (const song of songs) {
                 entries.push({ name: `${folder}/${songBase(song)}.mp3`, path: song.file });
                 entries.push({ name: `${folder}/${songBase(song)}.lyrics.txt`, bytes: Buffer.from(`${song.lyrics}\n`) });
+                if (song.lrc)
+                    entries.push({ name: `${folder}/${songBase(song)}.lrc`, path: song.lrc });
                 if (song.video)
                     entries.push({ name: `${folder}/${songBase(song)}.mp4`, path: song.video });
             }

package/dist/lyrics.d.ts

@@ -1,18 +1,3 @@
-/**
- * The words of the song on the air, for a station's page.
- *
- * Two places they come from, in this order:
- *  1. the file itself: an ID3 USLT frame (ffprobe calls it `lyrics-eng`, or
- *     `lyrics-<description>-<lang>`), a Vorbis/APE `LYRICS` or
- *     `UNSYNCEDLYRICS` tag. Suno writes the words it sang into USLT, so our
- *     own catalog carries them already;
- *  2. nichedb.dev's lyrics, asked by artist and title, which is where a file
- *     without the tag gets them (and where ours are published back to:
- *     lyrics-publish.ts).
- * Each answer is kept: the tags with the file (by size and time, TagReader),
- * nichedb's for ten minutes, misses included, so a station of tracks nobody
- * has words for asks once per track per ten minutes and never waits long.
- */
 export interface Lyrics {
     title: string;
     artist: string;
@@ -21,7 +6,32 @@ export interface Lyrics {
     source: string;
     /** ISO 639-1 where we know the mapping, else what the tag said; "" when unsaid. */
     language: string;
+    /** When a .lrc beside the file says when each line (and word) is sung: seconds from the file's start. */
+    synced?: SyncedLine[];
+}
+export interface SyncedLine {
+    start: number;
+    end: number;
+    text: string;
+    words: Array<{
+        start: number;
+        end: number;
+        text: string;
+    }>;
 }
+/**
+ * Enhanced LRC: `[mm:ss.xx]` before each sung line, and `<mm:ss.xx>` before
+ * each word when the words are timed. Tags like `[ar:...]` and lines without a
+ * time are skipped. Ends are the next start (the last line runs 4 s).
+ */
+export declare function parseLrc(text: string): SyncedLine[];
+export declare function formatLrc(lines: SyncedLine[], head?: {
+    title?: string;
+    artist?: string;
+    album?: string;
+}): string;
+/** The .lrc that sits beside a file (same name, .lrc), or "". */
+export declare function lrcBeside(file: string): string;
 export declare const NICHEDB_LYRICS = "https://nichedb.dev";
 /** Text as it may be shown: newlines kept, control characters gone, trimmed, capped. */
 export declare function cleanLyrics(text: string): string;

package/dist/lyrics.js

@@ -13,6 +13,67 @@
  * nichedb's for ten minutes, misses included, so a station of tracks nobody
  * has words for asks once per track per ten minutes and never waits long.
  */
+import { readFileSync } from "node:fs";
+const STAMP = /^(\d{1,3}):(\d{2})(?:[.:](\d{1,3}))?$/;
+function seconds(stamp) {
+    const match = STAMP.exec(stamp);
+    if (!match)
+        return Number.NaN;
+    const fraction = match[3] ? Number(`0.${match[3]}`) : 0;
+    return Number(match[1]) * 60 + Number(match[2]) + fraction;
+}
+function stamp(at) {
+    const whole = Math.max(0, at);
+    const minutes = Math.floor(whole / 60);
+    const rest = whole - minutes * 60;
+    return `${String(minutes).padStart(2, "0")}:${rest.toFixed(2).padStart(5, "0")}`;
+}
+/**
+ * Enhanced LRC: `[mm:ss.xx]` before each sung line, and `<mm:ss.xx>` before
+ * each word when the words are timed. Tags like `[ar:...]` and lines without a
+ * time are skipped. Ends are the next start (the last line runs 4 s).
+ */
+export function parseLrc(text) {
+    const lines = [];
+    for (const raw of text.replace(/\r\n?/g, "\n").split("\n")) {
+        const head = /^\[([^\]]+)\](.*)$/.exec(raw.trim());
+        if (!head)
+            continue;
+        const start = seconds(head[1]);
+        if (!Number.isFinite(start))
+            continue;
+        const body = head[2];
+        const words = [];
+        const parts = body.split(/<([^>]+)>/);
+        if (parts.length > 1) {
+            for (let i = 1; i < parts.length; i += 2) {
+                const at = seconds(parts[i]);
+                const word = (parts[i + 1] ?? "").trim();
+                if (Number.isFinite(at) && word)
+                    words.push({ start: at, end: at, text: word });
+            }
+        }
+        const plain = (parts.length > 1 ? words.map((one) => one.text).join(" ") : body).trim();
+        if (!plain)
+            continue;
+        lines.push({ start, end: start, text: plain, words });
+    }
+    lines.sort((a, b) => a.start - b.start);
+    lines.forEach((line, i) => {
+        line.end = lines[i + 1]?.start ?? line.start + 4;
+        line.words.forEach((word, j) => { word.end = line.words[j + 1]?.start ?? line.end; });
+    });
+    return lines;
+}
+export function formatLrc(lines, head = {}) {
+    const tags = [head.artist ? `[ar:${head.artist}]` : "", head.title ? `[ti:${head.title}]` : "", head.album ? `[al:${head.album}]` : ""].filter(Boolean);
+    const body = lines.map((line) => `[${stamp(line.start)}]${line.words.length ? line.words.map((word) => ` <${stamp(word.start)}>${word.text}`).join("") : line.text}`);
+    return `${[...tags, ...body].join("\n")}\n`;
+}
+/** The .lrc that sits beside a file (same name, .lrc), or "". */
+export function lrcBeside(file) {
+    return file.replace(/\.[^./]+$/, "") + ".lrc";
+}
 export const NICHEDB_LYRICS = "https://nichedb.dev";
 const MAX_TEXT = 20_000;
 /** ID3 / ISO 639-2 codes for the languages we are likely to meet, as 639-1. */
@@ -94,8 +155,18 @@ export class LyricsFinder {
         const title = tags["title"] || known?.title || "";
         const artist = tags["artist"] || tags["album_artist"] || known?.artist || "";
         const own = lyricsFromTags(tags);
+        // Timed words beside the file (karaoke): the page follows along with them.
+        let synced = [];
+        try {
+            synced = parseLrc(readFileSync(lrcBeside(file), "utf8"));
+        }
+        catch {
+            synced = [];
+        }
         if (own)
-            return { title, artist, text: own.text, source: "embedded", language: own.language };
+            return { title, artist, text: own.text, source: "embedded", language: own.language, ...(synced.length ? { synced } : {}) };
+        if (synced.length)
+            return { title, artist, text: synced.map((line) => line.text).join("\n"), source: "embedded", language: "", synced };
         if (!title || !artist || !this.base)
             return null;
         return this.lookup(artist, title);

package/dist/station-routes.js

@@ -240,7 +240,7 @@ export async function handleStations(request, response, path, url, ctx) {
                 ctx.json(response, 404, { error: "no lyrics for what is playing", code: "not_found" });
                 return true;
             }
-            ctx.json(response, 200, { lyrics: { title: lyrics.title, artist: lyrics.artist, text: lyrics.text, source: lyrics.source, language: lyrics.language } });
+            ctx.json(response, 200, { lyrics: { title: lyrics.title, artist: lyrics.artist, text: lyrics.text, source: lyrics.source, language: lyrics.language, ...(lyrics.synced ? { synced: lyrics.synced } : {}) } });
             return true;
         }
         if (what === "now") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "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

@@ -33,6 +33,7 @@ import { dirname, join, resolve, sep } from "node:path";
 import { aiKey } from "./ai-keys.ts";
 import { composerFromEnv, OutOfCredit, type Composer } from "./ai-radio.ts";
 import { askJson, hasModel } from "./ai-text.ts";
+import { formatLrc, type SyncedLine } from "./lyrics.ts";
 import type { LibraryIndex, Probed } from "./library-index.ts";
 import type { StationRunner } from "./station-runner.ts";
 import { StationError, type StationStore } from "./stations.ts";
@@ -49,6 +50,8 @@ export interface LabelSong {
   /** The MP3, "" until composed. */
   file: string;
   lyricsFile: string;
+  /** Its words timed to the recording (001. <title>.lrc, enhanced LRC), for karaoke on the station page; absent until aligned. */
+  lrc?: 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). */
@@ -522,6 +525,55 @@ export async function workersAiCover(prompt: string, env: Record<string, string
   return image;
 }
 
+/** A timed word from an aligner: seconds from the start of the song. */
+export interface TimedWord { text: string; start: number; end: number }
+
+/** ElevenLabs forced alignment: the song and its words in, each word's time out. */
+export function elevenLabsAligner(key: string, fetcher: typeof fetch = fetch): (audio: string, text: string) => Promise<TimedWord[]> {
+  return async (audio, text) => {
+    const form = new FormData();
+    form.append("file", new Blob([readFileSync(audio)], { type: "audio/mpeg" }), "song.mp3");
+    form.append("text", text);
+    const response = await fetcher("https://api.elevenlabs.io/v1/forced-alignment", {
+      method: "POST",
+      headers: { "xi-api-key": key },
+      body: form,
+      signal: AbortSignal.timeout(5 * 60_000),
+    });
+    if (response.status === 401 || response.status === 402) throw new OutOfCredit(`elevenlabs answered HTTP ${response.status} to the alignment`);
+    if (!response.ok) throw new Error(`the alignment answered HTTP ${response.status}`);
+    const body = await response.json() as { words?: Array<{ text?: unknown; start?: unknown; end?: unknown }> };
+    return (body.words ?? [])
+      .map((one) => ({ text: String(one.text ?? "").trim(), start: Number(one.start), end: Number(one.end) }))
+      .filter((one) => one.text && Number.isFinite(one.start) && Number.isFinite(one.end));
+  };
+}
+
+/** The sung lines of a song's words: section tags ([Chorus]) and blank lines are not sung. */
+export function sungLines(lyrics: string): string[] {
+  return lyrics.split("\n").map((line) => line.trim()).filter((line) => line && !/^\[[^\]]*\]$/.test(line));
+}
+
+/**
+ * Timed words laid back onto the lines they were written in, in order, so
+ * each line and each word knows when it is sung.
+ */
+export function syncLines(lyrics: string, timed: TimedWord[]): SyncedLine[] {
+  const out: SyncedLine[] = [];
+  let at = 0;
+  for (const line of sungLines(lyrics)) {
+    const words = line.split(/\s+/).filter(Boolean);
+    const placed = words.map((word) => {
+      const hit = timed[at];
+      if (hit) at += 1;
+      return hit ? { text: word, start: hit.start, end: hit.end } : null;
+    }).filter((one): one is { text: string; start: number; end: number } => one !== null);
+    if (placed.length === 0) break;
+    out.push({ start: placed[0]!.start, end: placed[placed.length - 1]!.end, text: line, words: placed });
+  }
+  return out;
+}
+
 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).",
@@ -674,6 +726,8 @@ 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>;
+  /** Times each sung word in a recording; ElevenLabs forced alignment by default, null without a key. */
+  align?: ((audio: string, text: string) => Promise<TimedWord[]>) | null;
   /** 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. */
@@ -700,6 +754,8 @@ export class AiLabel {
   private filming: Promise<number> | null = null;
   /** Songs whose video failed since this server started. */
   private videoFailed = new Set<string>();
+  /** Songs whose words were already sent to the aligner since this server started. */
+  private alignTried = 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. */
@@ -976,7 +1032,40 @@ export class AiLabel {
    * song's tags (seconds each), then old cover-and-waveform videos made again
    * as storyboards.
    */
+  /** The aligner this server can use: the dependency, else ElevenLabs with its key, else none. */
+  private aligner(): ((audio: string, text: string) => Promise<TimedWord[]>) | null {
+    if (this.deps.align !== undefined) return this.deps.align;
+    const key = aiKey("ELEVENLABS_API_KEY");
+    return key ? elevenLabsAligner(key) : null;
+  }
+
+  /** A song's words timed to its recording, written as 001. <title>.lrc beside it. Once per song (a failure is not retried this run). */
+  private async sync(artist: LabelArtist, album: LabelAlbum, song: LabelSong): Promise<boolean> {
+    const align = this.aligner();
+    if (!align || !song.file || !song.lyrics || song.lrc || this.alignTried.has(song.file)) return false;
+    this.alignTried.add(song.file);
+    try {
+      const timed = await align(song.file, sungLines(song.lyrics).join("\n"));
+      const lines = syncLines(song.lyrics, timed);
+      if (lines.length === 0) throw new Error("the aligner placed no words");
+      const file = join(album.folder, `${songBase(song)}.lrc`);
+      writeFileSync(file, formatLrc(lines, { title: song.title, artist: artist.name, album: album.title }));
+      song.lrc = file;
+      this.save();
+      return true;
+    } catch (error) {
+      this.log(`could not time the words of "${song.title}": ${(error as Error).message}`);
+      return false;
+    }
+  }
+
   private async filmPass(): Promise<number> {
+    // Words timed first: quick, and what the station page's karaoke needs.
+    for (const artist of this.list()) {
+      for (const album of artist.albums) {
+        for (const song of album.songs) await this.sync(artist, album, song);
+      }
+    }
     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 }))));
@@ -1289,7 +1378,8 @@ export class AiLabel {
       this.save();
       this.writeAlbumJson(artist, album);
       await this.place(artist.genre);
-      // Its video is made beside it, without holding up the next song.
+      // Its words timed to the recording, then its video, without holding up the next song.
+      await this.sync(artist, album, song).catch(() => undefined);
       void this.videos();
     } catch (error) {
       this.failed(artist, error);
@@ -1465,6 +1555,7 @@ export class AiLabel {
       for (const song of songs) {
         entries.push({ name: `${folder}/${songBase(song)}.mp3`, path: song.file });
         entries.push({ name: `${folder}/${songBase(song)}.lyrics.txt`, bytes: Buffer.from(`${song.lyrics}\n`) });
+        if (song.lrc) entries.push({ name: `${folder}/${songBase(song)}.lrc`, path: song.lrc });
         if (song.video) entries.push({ name: `${folder}/${songBase(song)}.mp4`, path: song.video });
       }
       if (album.cover) entries.push({ name: `${folder}/cover.jpg`, path: album.cover });

package/src/lyrics.ts

@@ -13,6 +13,7 @@
  * nichedb's for ten minutes, misses included, so a station of tracks nobody
  * has words for asks once per track per ten minutes and never waits long.
  */
+import { readFileSync } from "node:fs";
 
 export interface Lyrics {
   title: string;
@@ -22,6 +23,76 @@ export interface Lyrics {
   source: string;
   /** ISO 639-1 where we know the mapping, else what the tag said; "" when unsaid. */
   language: string;
+  /** When a .lrc beside the file says when each line (and word) is sung: seconds from the file's start. */
+  synced?: SyncedLine[];
+}
+
+export interface SyncedLine {
+  start: number;
+  end: number;
+  text: string;
+  words: Array<{ start: number; end: number; text: string }>;
+}
+
+const STAMP = /^(\d{1,3}):(\d{2})(?:[.:](\d{1,3}))?$/;
+
+function seconds(stamp: string): number {
+  const match = STAMP.exec(stamp);
+  if (!match) return Number.NaN;
+  const fraction = match[3] ? Number(`0.${match[3]}`) : 0;
+  return Number(match[1]) * 60 + Number(match[2]) + fraction;
+}
+
+function stamp(at: number): string {
+  const whole = Math.max(0, at);
+  const minutes = Math.floor(whole / 60);
+  const rest = whole - minutes * 60;
+  return `${String(minutes).padStart(2, "0")}:${rest.toFixed(2).padStart(5, "0")}`;
+}
+
+/**
+ * Enhanced LRC: `[mm:ss.xx]` before each sung line, and `<mm:ss.xx>` before
+ * each word when the words are timed. Tags like `[ar:...]` and lines without a
+ * time are skipped. Ends are the next start (the last line runs 4 s).
+ */
+export function parseLrc(text: string): SyncedLine[] {
+  const lines: SyncedLine[] = [];
+  for (const raw of text.replace(/\r\n?/g, "\n").split("\n")) {
+    const head = /^\[([^\]]+)\](.*)$/.exec(raw.trim());
+    if (!head) continue;
+    const start = seconds(head[1]!);
+    if (!Number.isFinite(start)) continue;
+    const body = head[2]!;
+    const words: SyncedLine["words"] = [];
+    const parts = body.split(/<([^>]+)>/);
+    if (parts.length > 1) {
+      for (let i = 1; i < parts.length; i += 2) {
+        const at = seconds(parts[i]!);
+        const word = (parts[i + 1] ?? "").trim();
+        if (Number.isFinite(at) && word) words.push({ start: at, end: at, text: word });
+      }
+    }
+    const plain = (parts.length > 1 ? words.map((one) => one.text).join(" ") : body).trim();
+    if (!plain) continue;
+    lines.push({ start, end: start, text: plain, words });
+  }
+  lines.sort((a, b) => a.start - b.start);
+  lines.forEach((line, i) => {
+    line.end = lines[i + 1]?.start ?? line.start + 4;
+    line.words.forEach((word, j) => { word.end = line.words[j + 1]?.start ?? line.end; });
+  });
+  return lines;
+}
+
+export function formatLrc(lines: SyncedLine[], head: { title?: string; artist?: string; album?: string } = {}): string {
+  const tags = [head.artist ? `[ar:${head.artist}]` : "", head.title ? `[ti:${head.title}]` : "", head.album ? `[al:${head.album}]` : ""].filter(Boolean);
+  const body = lines.map((line) => `[${stamp(line.start)}]${line.words.length ? line.words.map((word) => ` <${stamp(word.start)}>${word.text}`).join("") : line.text}`);
+  return `${[...tags, ...body].join("\n")}\n`;
+}
+
+/** The .lrc that sits beside a file (same name, .lrc), or "". */
+export function lrcBeside(file: string): string {
+  return file.replace(/\.[^./]+$/, "") + ".lrc";
 }
 
 export const NICHEDB_LYRICS = "https://nichedb.dev";
@@ -116,7 +187,11 @@ export class LyricsFinder {
     const title = tags["title"] || known?.title || "";
     const artist = tags["artist"] || tags["album_artist"] || known?.artist || "";
     const own = lyricsFromTags(tags);
-    if (own) return { title, artist, text: own.text, source: "embedded", language: own.language };
+    // Timed words beside the file (karaoke): the page follows along with them.
+    let synced: SyncedLine[] = [];
+    try { synced = parseLrc(readFileSync(lrcBeside(file), "utf8")); } catch { synced = []; }
+    if (own) return { title, artist, text: own.text, source: "embedded", language: own.language, ...(synced.length ? { synced } : {}) };
+    if (synced.length) return { title, artist, text: synced.map((line) => line.text).join("\n"), source: "embedded", language: "", synced };
     if (!title || !artist || !this.base) return null;
     return this.lookup(artist, title);
   }

package/src/station-routes.ts

@@ -324,7 +324,7 @@ export async function handleStations(
         ctx.json(response, 404, { error: "no lyrics for what is playing", code: "not_found" });
         return true;
       }
-      ctx.json(response, 200, { lyrics: { title: lyrics.title, artist: lyrics.artist, text: lyrics.text, source: lyrics.source, language: lyrics.language } });
+      ctx.json(response, 200, { lyrics: { title: lyrics.title, artist: lyrics.artist, text: lyrics.text, source: lyrics.source, language: lyrics.language, ...(lyrics.synced ? { synced: lyrics.synced } : {}) } });
       return true;
     }
     if (what === "now") {

package/web/dist/assets/{ar-CHJqwLbG.js → ar-CCVdTxXd.js}

@@ -1 +1 @@
-import{t as e}from"./main-BpsUYSCl.js";var t={...e,"No parties live right now.":`لا توجد جلسات مباشرة الآن.`,"Could not refresh parties.":`تعذر تحديث الجلسات.`,"Pick a server in the directory, or paste its link here.":`اختر خادمًا من الدليل أو الصق رابطه هنا.`,"Interface language":`لغة الواجهة`,Language:`اللغة`,"Translation language":`لغة الترجمة`,"Original (auto-detect)":`الأصل (اكتشاف تلقائي)`,Play:`تشغيل`,Pause:`إيقاف مؤقت`,Stop:`إيقاف`,Next:`التالي`,Previous:`السابق`,Select:`اختيار`,"Next/Prev":`التالي/السابق`,Quit:`خروج`,"Now Playing":`قيد التشغيل`,"Spectrum Analyser":`محلل الطيف`,Playlist:`قائمة التشغيل`,Files:`الملفات`,"Open files":`فتح ملفات`,"Open folder":`فتح مجلد`,"Add to library":`إضافة إلى المكتبة`,"Replace playlist":`استبدال قائمة التشغيل`,Filter:`تصفية`,Search:`بحث`,"Nothing loaded.":`لم يُحمّل أي محتوى.`,"Empty.":`فارغ.`,"Loading…":`جارٍ التحميل…`,"Connecting…":`جارٍ الاتصال…`,Connected:`متصل`,"Not connected":`غير متصل`,"No source":`لا يوجد مصدر`,Playing:`يعمل`,Stopped:`متوقف`,Volume:`مستوى الصوت`,Seek:`موضع التشغيل`,"Full screen":`ملء الشاشة`,Download:`تنزيل`,Share:`مشاركة`,Copy:`نسخ`,"Copy link":`نسخ الرابط`,Copied:`تم النسخ`,Save:`حفظ`,Cancel:`إلغاء`,Close:`إغلاق`,Remove:`إزالة`,Delete:`حذف`,Edit:`تعديل`,Add:`إضافة`,Send:`إرسال`,Retry:`إعادة المحاولة`,Back:`رجوع`,"Next page":`الصفحة التالية`,"Previous page":`الصفحة السابقة`,"Show more":`عرض المزيد`,Panels:`اللوحات`,"Reset layout":`إعادة ضبط التخطيط`,Show:`إظهار`,Hide:`إخفاء`,Collapse:`طي`,Expand:`توسيع`,"Move up":`نقل لأعلى`,"Move down":`نقل لأسفل`,Install:`تثبيت`,"TV mode":`وضع التلفاز`,On:`مفعّل`,Off:`معطّل`,Account:`الحساب`,"Sign in":`تسجيل الدخول`,"Sign out":`تسجيل الخروج`,"Create account":`إنشاء حساب`,Email:`البريد الإلكتروني`,Password:`كلمة المرور`,"Forgot password?":`نسيت كلمة المرور؟`,"Welcome back":`مرحبًا بعودتك`,Profile:`الملف الشخصي`,Handle:`اسم المستخدم`,"Your servers":`خوادمك`,Server:`الخادم`,Connect:`اتصال`,Disconnect:`قطع الاتصال`,Directory:`الدليل`,Favourites:`المفضلة`,Follow:`متابعة`,Unfollow:`إلغاء المتابعة`,Notifications:`الإشعارات`,"Phone number":`رقم الهاتف`,"Save number":`حفظ الرقم`,Transcript:`النص المفرغ`,Captions:`الترجمة النصية`,"Translate audio":`ترجمة الصوت`,"Audio language":`لغة الصوت`,"Audio options":`خيارات الصوت`,"Keep background sound":`الاحتفاظ بأصوات الخلفية`,"Background level":`مستوى صوت الخلفية`,"Speaker voices":`أصوات المتحدثين`,"Any voice":`أي صوت`,"Male voice":`صوت رجالي`,"Female voice":`صوت نسائي`,"Original audio.":`الصوت الأصلي.`,"Buy translated audio":`شراء الصوت المترجم`,"Audio credit":`رصيد الصوت`,"Buy pass":`شراء تصريح`,Pass:`تصريح`,"Pay with":`الدفع باستخدام`,"Check payment":`التحقق من الدفع`,"Open checkout":`الانتقال للدفع`,"Free sessions":`جلسات مجانية`,"Usage rates and expiry":`الأسعار ومدة الصلاحية`,Catalogs:`الكتالوجات`,"Add catalog":`إضافة كتالوج`,"Catalog name":`اسم الكتالوج`,Link:`الرابط`,"Play link":`تشغيل الرابط`,"Go live":`بدء بث مباشر`,Publish:`نشر`,Listen:`استماع`,"Live now":`مباشر الآن`,Upcoming:`قريبًا`,Parties:`حفلات المشاهدة`,"Join party":`الانضمام للحفلة`,"Invite code":`رمز الدعوة`,Invite:`دعوة`,Chat:`الدردشة`,"Chat message":`رسالة دردشة`,People:`الأشخاص`,Speaker:`متحدث`,Speakers:`المتحدثون`,Listener:`مستمع`,Moderator:`مشرف`,"Raise hand":`رفع اليد`,"Hand raises":`الأيدي المرفوعة`,Questions:`الأسئلة`,Resources:`الموارد`,Replay:`إعادة العرض`,Schedule:`الجدول`,Event:`الفعالية`,Host:`المضيف`,About:`حول`,Stage:`المنصة`,Title:`العنوان`,Description:`الوصف`,Topic:`الموضوع`,Public:`عام`,"Anyone with the link":`أي شخص لديه الرابط`,"Invited people":`الأشخاص المدعوون`,"Who can join":`من يمكنه الانضمام`,"Date and time":`التاريخ والوقت`,"Expected length":`المدة المتوقعة`,Repeat:`تكرار`,"Does not repeat":`لا يتكرر`,"Every day":`كل يوم`,"Every week":`كل أسبوع`,Homepage:`الموقع الإلكتروني`,"Host name":`اسم المضيف`,"Profile photo URL":`رابط صورة الملف الشخصي`,"Broadcast link":`رابط البث`,"Edit event":`تعديل الفعالية`,"Save changes":`حفظ التغييرات`,"Create live":`إنشاء بث مباشر`,"Schedule class":`جدولة درس`,"Start class":`بدء الدرس`,"End event":`إنهاء الفعالية`,"End session":`إنهاء الجلسة`,"Session ended":`انتهت الجلسة`,"Event ended":`انتهت الفعالية`,Cancelled:`ملغاة`,"Replay available":`إعادة العرض متاحة`,Join:`انضمام`,"Create invite":`إنشاء دعوة`,"Invite as":`الدعوة بصفة`,"Watch now":`شاهد الآن`,"Start a room":`إنشاء غرفة`,"Recent replays":`إعادات العرض الأخيرة`,"Your account":`حسابك`,"Write with AI":`الكتابة بالذكاء الاصطناعي`,"Suggested title":`العنوان المقترح`,"Suggested description":`الوصف المقترح`,"Suggested topic":`الموضوع المقترح`,"Use these details":`استخدام هذه التفاصيل`,"Learn something live.":`تعلّم شيئًا مباشرة.`,"Screen share":`مشاركة الشاشة`,"Upload and broadcast":`رفع وبث`,Help:`مساعدة`,"Reload Player":`إعادة تحميل المشغل`,"Copy Bundled CLI Path":`نسخ مسار أداة سطر الأوامر المضمنة`,"Developer tools":`أدوات المطور`,Undo:`تراجع`,Redo:`إعادة`,Cut:`قص`,Paste:`لصق`,"Select all":`تحديد الكل`,Status:`الحالة`,"Activity log":`سجل النشاط`,Admin:`الإدارة`,"Playback controls":`عناصر التحكم بالتشغيل`,"Tracks and folders":`المقاطع والمجلدات`,"Original-language captions.":`ترجمة نصية باللغة الأصلية.`,"Skip to playback controls":`الانتقال إلى عناصر التحكم بالتشغيل`,"Skip to playlist":`الانتقال إلى قائمة التشغيل`,"Skip to transcript and translated audio":`الانتقال إلى النص المفرغ والصوت المترجم`};export{t as default};
+import{t as e}from"./main-Coq6MRdf.js";var t={...e,"No parties live right now.":`لا توجد جلسات مباشرة الآن.`,"Could not refresh parties.":`تعذر تحديث الجلسات.`,"Pick a server in the directory, or paste its link here.":`اختر خادمًا من الدليل أو الصق رابطه هنا.`,"Interface language":`لغة الواجهة`,Language:`اللغة`,"Translation language":`لغة الترجمة`,"Original (auto-detect)":`الأصل (اكتشاف تلقائي)`,Play:`تشغيل`,Pause:`إيقاف مؤقت`,Stop:`إيقاف`,Next:`التالي`,Previous:`السابق`,Select:`اختيار`,"Next/Prev":`التالي/السابق`,Quit:`خروج`,"Now Playing":`قيد التشغيل`,"Spectrum Analyser":`محلل الطيف`,Playlist:`قائمة التشغيل`,Files:`الملفات`,"Open files":`فتح ملفات`,"Open folder":`فتح مجلد`,"Add to library":`إضافة إلى المكتبة`,"Replace playlist":`استبدال قائمة التشغيل`,Filter:`تصفية`,Search:`بحث`,"Nothing loaded.":`لم يُحمّل أي محتوى.`,"Empty.":`فارغ.`,"Loading…":`جارٍ التحميل…`,"Connecting…":`جارٍ الاتصال…`,Connected:`متصل`,"Not connected":`غير متصل`,"No source":`لا يوجد مصدر`,Playing:`يعمل`,Stopped:`متوقف`,Volume:`مستوى الصوت`,Seek:`موضع التشغيل`,"Full screen":`ملء الشاشة`,Download:`تنزيل`,Share:`مشاركة`,Copy:`نسخ`,"Copy link":`نسخ الرابط`,Copied:`تم النسخ`,Save:`حفظ`,Cancel:`إلغاء`,Close:`إغلاق`,Remove:`إزالة`,Delete:`حذف`,Edit:`تعديل`,Add:`إضافة`,Send:`إرسال`,Retry:`إعادة المحاولة`,Back:`رجوع`,"Next page":`الصفحة التالية`,"Previous page":`الصفحة السابقة`,"Show more":`عرض المزيد`,Panels:`اللوحات`,"Reset layout":`إعادة ضبط التخطيط`,Show:`إظهار`,Hide:`إخفاء`,Collapse:`طي`,Expand:`توسيع`,"Move up":`نقل لأعلى`,"Move down":`نقل لأسفل`,Install:`تثبيت`,"TV mode":`وضع التلفاز`,On:`مفعّل`,Off:`معطّل`,Account:`الحساب`,"Sign in":`تسجيل الدخول`,"Sign out":`تسجيل الخروج`,"Create account":`إنشاء حساب`,Email:`البريد الإلكتروني`,Password:`كلمة المرور`,"Forgot password?":`نسيت كلمة المرور؟`,"Welcome back":`مرحبًا بعودتك`,Profile:`الملف الشخصي`,Handle:`اسم المستخدم`,"Your servers":`خوادمك`,Server:`الخادم`,Connect:`اتصال`,Disconnect:`قطع الاتصال`,Directory:`الدليل`,Favourites:`المفضلة`,Follow:`متابعة`,Unfollow:`إلغاء المتابعة`,Notifications:`الإشعارات`,"Phone number":`رقم الهاتف`,"Save number":`حفظ الرقم`,Transcript:`النص المفرغ`,Captions:`الترجمة النصية`,"Translate audio":`ترجمة الصوت`,"Audio language":`لغة الصوت`,"Audio options":`خيارات الصوت`,"Keep background sound":`الاحتفاظ بأصوات الخلفية`,"Background level":`مستوى صوت الخلفية`,"Speaker voices":`أصوات المتحدثين`,"Any voice":`أي صوت`,"Male voice":`صوت رجالي`,"Female voice":`صوت نسائي`,"Original audio.":`الصوت الأصلي.`,"Buy translated audio":`شراء الصوت المترجم`,"Audio credit":`رصيد الصوت`,"Buy pass":`شراء تصريح`,Pass:`تصريح`,"Pay with":`الدفع باستخدام`,"Check payment":`التحقق من الدفع`,"Open checkout":`الانتقال للدفع`,"Free sessions":`جلسات مجانية`,"Usage rates and expiry":`الأسعار ومدة الصلاحية`,Catalogs:`الكتالوجات`,"Add catalog":`إضافة كتالوج`,"Catalog name":`اسم الكتالوج`,Link:`الرابط`,"Play link":`تشغيل الرابط`,"Go live":`بدء بث مباشر`,Publish:`نشر`,Listen:`استماع`,"Live now":`مباشر الآن`,Upcoming:`قريبًا`,Parties:`حفلات المشاهدة`,"Join party":`الانضمام للحفلة`,"Invite code":`رمز الدعوة`,Invite:`دعوة`,Chat:`الدردشة`,"Chat message":`رسالة دردشة`,People:`الأشخاص`,Speaker:`متحدث`,Speakers:`المتحدثون`,Listener:`مستمع`,Moderator:`مشرف`,"Raise hand":`رفع اليد`,"Hand raises":`الأيدي المرفوعة`,Questions:`الأسئلة`,Resources:`الموارد`,Replay:`إعادة العرض`,Schedule:`الجدول`,Event:`الفعالية`,Host:`المضيف`,About:`حول`,Stage:`المنصة`,Title:`العنوان`,Description:`الوصف`,Topic:`الموضوع`,Public:`عام`,"Anyone with the link":`أي شخص لديه الرابط`,"Invited people":`الأشخاص المدعوون`,"Who can join":`من يمكنه الانضمام`,"Date and time":`التاريخ والوقت`,"Expected length":`المدة المتوقعة`,Repeat:`تكرار`,"Does not repeat":`لا يتكرر`,"Every day":`كل يوم`,"Every week":`كل أسبوع`,Homepage:`الموقع الإلكتروني`,"Host name":`اسم المضيف`,"Profile photo URL":`رابط صورة الملف الشخصي`,"Broadcast link":`رابط البث`,"Edit event":`تعديل الفعالية`,"Save changes":`حفظ التغييرات`,"Create live":`إنشاء بث مباشر`,"Schedule class":`جدولة درس`,"Start class":`بدء الدرس`,"End event":`إنهاء الفعالية`,"End session":`إنهاء الجلسة`,"Session ended":`انتهت الجلسة`,"Event ended":`انتهت الفعالية`,Cancelled:`ملغاة`,"Replay available":`إعادة العرض متاحة`,Join:`انضمام`,"Create invite":`إنشاء دعوة`,"Invite as":`الدعوة بصفة`,"Watch now":`شاهد الآن`,"Start a room":`إنشاء غرفة`,"Recent replays":`إعادات العرض الأخيرة`,"Your account":`حسابك`,"Write with AI":`الكتابة بالذكاء الاصطناعي`,"Suggested title":`العنوان المقترح`,"Suggested description":`الوصف المقترح`,"Suggested topic":`الموضوع المقترح`,"Use these details":`استخدام هذه التفاصيل`,"Learn something live.":`تعلّم شيئًا مباشرة.`,"Screen share":`مشاركة الشاشة`,"Upload and broadcast":`رفع وبث`,Help:`مساعدة`,"Reload Player":`إعادة تحميل المشغل`,"Copy Bundled CLI Path":`نسخ مسار أداة سطر الأوامر المضمنة`,"Developer tools":`أدوات المطور`,Undo:`تراجع`,Redo:`إعادة`,Cut:`قص`,Paste:`لصق`,"Select all":`تحديد الكل`,Status:`الحالة`,"Activity log":`سجل النشاط`,Admin:`الإدارة`,"Playback controls":`عناصر التحكم بالتشغيل`,"Tracks and folders":`المقاطع والمجلدات`,"Original-language captions.":`ترجمة نصية باللغة الأصلية.`,"Skip to playback controls":`الانتقال إلى عناصر التحكم بالتشغيل`,"Skip to playlist":`الانتقال إلى قائمة التشغيل`,"Skip to transcript and translated audio":`الانتقال إلى النص المفرغ والصوت المترجم`};export{t as default};