lrc-audio-player 0.1.1 → 0.1.3

package/README.md

@@ -1,9 +1,9 @@
 # lrc-audio-player
 
 Sync LRC (and word-level "enhanced" LRC) lyrics to an `HTMLAudioElement`
-from a single constructor. Gives you the current line, the next line,
-word-level highlighting, seeking by line, and change events — without
-re-scanning the whole lyric file on every `timeupdate`.
+with accurate seeking. Automatically converts variable-bitrate (VBR)
+audio to constant bitrate (CBR) for precise `currentTime` synchronization
+— critical for lyrics that must stay locked to the audio.
 
 ## Install
 
@@ -11,6 +11,16 @@ re-scanning the whole lyric file on every `timeupdate`.
 npm install lrc-audio-player
 ```
 
+**Optional:** If you need CBR conversion (recommended), also install:
+
+```bash
+npm install @ffmpeg/ffmpeg @ffmpeg/util
+```
+
+> `ffmpeg.wasm` is loaded on-demand and only when needed. If you skip
+> installing it, you must set `skipCBR: true` and provide CBR-encoded
+> audio files yourself.
+
 ## Quick start
 
 ```ts
@@ -18,7 +28,8 @@ import { LyricPlayer } from 'lrc-audio-player';
 
 const lrcText = await fetch('/song.lrc').then((r) => r.text());
 
-const player = new LyricPlayer({
+// Async factory — handles CBR conversion in the background
+const player = await LyricPlayer.create({
   audio: '/song.mp3',
   lyrics: lrcText,
 });
@@ -34,9 +45,20 @@ You can also hand it an existing `<audio>` element instead of a URL:
 
 ```ts
 const audioEl = document.querySelector('audio')!;
-const player = new LyricPlayer({ audio: audioEl, lyrics: lrcText });
+const player = await LyricPlayer.create({ audio: audioEl, lyrics: lrcText });
 ```
 
+## Why CBR conversion?
+
+Browsers estimate `audio.currentTime` from average bitrate when seek tables
+are missing. With VBR files, this causes drift — lyrics appear early or
+late after seeking. **CBR guarantees linear time-to-byte mapping**, so
+seeking is sample-accurate.
+
+By default, `lrc-audio-player` detects VBR MP3s and re-encodes them to
+CBR using `ffmpeg.wasm` (all in-browser, no server needed). If your audio
+is already CBR, set `skipCBR: true` to skip conversion.
+
 ## Lyric formats
 
 - **Standard LRC**: `[01:23.45]Some lyric line`
@@ -47,7 +69,7 @@ const player = new LyricPlayer({ audio: audioEl, lyrics: lrcText });
   use `lyrics: { type: 'json', data: [...] }`
 
 ```ts
-new LyricPlayer({
+await LyricPlayer.create({
   audio: '/song.mp3',
   lyrics: [
     { time: 0, text: 'First line' },
@@ -58,13 +80,30 @@ new LyricPlayer({
 
 ## API
 
-### `new LyricPlayer(options)`
+### `LyricPlayer.create(options)` (recommended)
+
+Async factory that waits for CBR conversion (if needed) before returning
+a ready-to-use player.
 
-| Option     | Type                                              | Description                                  |
-| ---------- | ------------------------------------------------- | --------------------------------------------- |
-| `audio`    | `string \| HTMLAudioElement`                      | Audio source URL, or an existing element       |
-| `lyrics`   | `string \| LyricLine[] \| ParsedLyrics \| LyricSource` | LRC text, JSON lines, or pre-parsed lyrics |
-| `offsetMs` | `number` (optional)                               | Extra global offset on top of `[offset:]`      |
+| Option       | Type                                                | Description                                      |
+| ------------ | --------------------------------------------------- | ------------------------------------------------ |
+| `audio`      | `string \| HTMLAudioElement`                        | Audio source URL, or an existing element         |
+| `lyrics`     | `string \| LyricLine[] \| ParsedLyrics \| LyricSource` | LRC text, JSON lines, or pre-parsed lyrics    |
+| `offsetMs`   | `number` (optional)                                 | Extra global offset on top of `[offset:]`        |
+| `skipCBR`    | `boolean` (optional, default `false`)               | Skip CBR conversion if your file is already CBR  |
+| `cbrBitrate` | `string` (optional, default `'128k'`)               | Target bitrate for CBR conversion              |
+
+### `new LyricPlayer(options)` (advanced)
+
+Synchronous constructor. The instance is returned immediately but
+**is not ready until `await player.ready()` resolves**. Use this if you
+need to attach listeners before initialization completes.
+
+```ts
+const player = new LyricPlayer({ audio: '/song.mp3', lyrics: lrcText });
+await player.ready();
+player.play();
+```
 
 ### Playback
 
@@ -90,13 +129,13 @@ new LyricPlayer({
 
 `on(event, handler)` / `off(event, handler)`:
 
-| Event        | Payload                                  |
+| Event        | Payload                                    |
 | ------------ | ------------------------------------------ |
 | `linechange` | `(line: LyricLine \| null, index: number)` |
 | `timeupdate` | `(currentTime: number)`                    |
-| `play`       | —                                           |
-| `pause`      | —                                           |
-| `ended`      | —                                           |
+| `play`       | —                                          |
+| `pause`      | —                                          |
+| `ended`      | —                                          |
 | `error`      | `(event: Event)`                           |
 
 ## Example: word-by-word highlighting
@@ -114,6 +153,16 @@ player.on('timeupdate', () => {
 });
 ```
 
+## Example: skip CBR for already-optimized files
+
+```ts
+const player = await LyricPlayer.create({
+  audio: '/song-cbr.mp3',
+  lyrics: lrcText,
+  skipCBR: true, // No conversion — instant load
+});
+```
+
 ## Development
 
 ```bash
@@ -122,3 +171,7 @@ npm run build      # bundle to dist/ (cjs + esm + types)
 npm test           # run vitest
 npm run typecheck  # tsc --noEmit
 ```
+
+## License
+
+MIT

package/dist/chunk-3A2M5KTA.js

@@ -0,0 +1,365 @@
+// src/parser.ts
+var TIME_TAG = /\[(\d{1,2}):(\d{2})(?:[.:](\d{1,3}))?\]/g;
+var META_TAG = /^\[([a-zA-Z]+):(.*)\]$/;
+var WORD_TAG = /<(\d{1,2}):(\d{2})(?:[.:](\d{1,3}))?>/g;
+var KNOWN_META_KEYS = {
+  ti: "title",
+  ar: "artist",
+  al: "album",
+  au: "author",
+  by: "author",
+  offset: "offset"
+};
+function timeToSeconds(min, sec, frac) {
+  const fraction = frac ? Number(`0.${frac}`) : 0;
+  return Number(min) * 60 + Number(sec) + fraction;
+}
+function parseTokens(raw, lineTime) {
+  if (!WORD_TAG.test(raw)) {
+    return { text: raw.trim() };
+  }
+  WORD_TAG.lastIndex = 0;
+  const tokens = [];
+  let lastIndex = 0;
+  let lastTime = lineTime;
+  let match;
+  let plain = "";
+  while (match = WORD_TAG.exec(raw)) {
+    const chunk = raw.slice(lastIndex, match.index);
+    if (chunk.length) {
+      tokens.push({ time: lastTime, text: chunk });
+      plain += chunk;
+    }
+    lastTime = timeToSeconds(match[1], match[2], match[3]);
+    lastIndex = WORD_TAG.lastIndex;
+  }
+  const tail = raw.slice(lastIndex);
+  if (tail.length) {
+    tokens.push({ time: lastTime, text: tail });
+    plain += tail;
+  }
+  return { text: plain.trim(), tokens };
+}
+function parseLRC(lrc) {
+  const metadata = {};
+  const lines = [];
+  const rawLines = lrc.split(/\r?\n/);
+  for (const rawLine of rawLines) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) continue;
+    const metaMatch = trimmed.match(META_TAG);
+    if (metaMatch && !TIME_TAG.test(trimmed)) {
+      const key = metaMatch[1].toLowerCase();
+      const value = metaMatch[2].trim();
+      const knownKey = KNOWN_META_KEYS[key];
+      if (knownKey === "offset") {
+        metadata.offset = Number(value);
+      } else if (knownKey) {
+        metadata[knownKey] = value;
+      } else {
+        metadata[key] = value;
+      }
+      TIME_TAG.lastIndex = 0;
+      continue;
+    }
+    TIME_TAG.lastIndex = 0;
+    const times = [];
+    let rest = trimmed;
+    let leadingMatch;
+    while (leadingMatch = rest.match(/^\[(\d{1,2}):(\d{2})(?:[.:](\d{1,3}))?\]/)) {
+      times.push(
+        timeToSeconds(leadingMatch[1], leadingMatch[2], leadingMatch[3])
+      );
+      rest = rest.slice(leadingMatch[0].length);
+    }
+    if (times.length === 0) {
+      continue;
+    }
+    for (const time of times) {
+      const { text, tokens } = parseTokens(rest, time);
+      lines.push({ time, text, tokens });
+    }
+  }
+  lines.sort((a, b) => a.time - b.time);
+  return { metadata, lines };
+}
+function parseJSONLyrics(json) {
+  const lines = typeof json === "string" ? JSON.parse(json) : json;
+  const sorted = [...lines].sort((a, b) => a.time - b.time);
+  return { metadata: {}, lines: sorted };
+}
+
+// src/player.ts
+var LyricPlayer = class _LyricPlayer {
+  constructor(options) {
+    this.currentIndex = -1;
+    this.listeners = {};
+    this.handleTimeUpdate = () => {
+      const time = this.audio.currentTime;
+      const newIndex = this.findLineIndexAtTime(time);
+      if (newIndex !== this.currentIndex) {
+        this.currentIndex = newIndex;
+        this.emit("linechange", this.getCurrentLine(), newIndex);
+      }
+      this.emit("timeupdate", time);
+    };
+    this._readyPromise = this.initialize(options);
+  }
+  static async create(options) {
+    const player = new _LyricPlayer(options);
+    await player.ready();
+    return player;
+  }
+  async initialize(options) {
+    const { skipCBR = false, cbrBitrate = "128k" } = options;
+    let audioSrc;
+    let audioEl;
+    if (typeof options.audio === "string") {
+      audioSrc = options.audio;
+      audioEl = new Audio();
+    } else {
+      audioEl = options.audio;
+      audioSrc = options.audio.src || options.audio.currentSrc;
+    }
+    if (!skipCBR && audioSrc) {
+      const needsConversion = await this.detectNeedsCBR(audioSrc);
+      if (needsConversion) {
+        audioSrc = await this.convertToCBR(audioSrc, cbrBitrate);
+      }
+    }
+    audioEl.src = audioSrc;
+    this.audio = audioEl;
+    const parsed = this.resolveLyrics(options.lyrics);
+    this.metadata = parsed.metadata;
+    this.lines = parsed.lines;
+    const tagOffsetMs = parsed.metadata.offset ?? 0;
+    this.offsetSeconds = (tagOffsetMs + (options.offsetMs ?? 0)) / 1e3;
+    this.audio.addEventListener("timeupdate", this.handleTimeUpdate);
+    this.audio.addEventListener("play", () => this.emit("play"));
+    this.audio.addEventListener("pause", () => this.emit("pause"));
+    this.audio.addEventListener("ended", () => this.emit("ended"));
+    this.audio.addEventListener("error", (e) => this.emit("error", e));
+  }
+  /** Wait for initialization (CBR conversion, etc.) before playing. */
+  ready() {
+    return this._readyPromise;
+  }
+  /** Detect if file is VBR or lacks proper seek tables. */
+  async detectNeedsCBR(src) {
+    try {
+      const response = await fetch(src, { method: "HEAD" });
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("audio/mpeg") || src.endsWith(".mp3")) {
+        const probe = await fetch(src, { headers: { Range: "bytes=0-1023" } });
+        const buffer = new Uint8Array(await probe.arrayBuffer());
+        return this.hasVBRHeader(buffer);
+      }
+      return true;
+    } catch {
+      return true;
+    }
+  }
+  hasVBRHeader(buffer) {
+    const decoder = new TextDecoder("latin1");
+    const header = decoder.decode(buffer);
+    return /Xing|Info|VBRI/.test(header);
+  }
+  /** Convert audio to CBR using ffmpeg.wasm. */
+  async convertToCBR(src, bitrate) {
+    const [{ FFmpeg }, { fetchFile }] = await Promise.all([
+      import("@ffmpeg/ffmpeg"),
+      import("@ffmpeg/util")
+    ]);
+    const ffmpeg = new FFmpeg();
+    await ffmpeg.load();
+    await ffmpeg.writeFile("input", await fetchFile(src));
+    await ffmpeg.exec([
+      "-i",
+      "input",
+      "-c:a",
+      "libmp3lame",
+      "-b:a",
+      bitrate,
+      "-minrate",
+      bitrate,
+      "-maxrate",
+      bitrate,
+      "-bufsize",
+      "256k",
+      "-preset",
+      "ultrafast",
+      "-fflags",
+      "+fastseek",
+      // Optimize for seeking
+      "-id3v2_version",
+      "3",
+      // Better metadata compatibility
+      "output.mp3"
+    ]);
+    const data = await ffmpeg.readFile("output.mp3");
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    const blob = new Blob(
+      // @ts-ignore — Uint8Array is valid per spec, TS types are overly strict
+      [bytes],
+      { type: "audio/mpeg" }
+    );
+    return URL.createObjectURL(blob);
+  }
+  // ---------------------------------------------------------------------
+  // Lyric source resolution
+  // ---------------------------------------------------------------------
+  resolveLyrics(lyrics) {
+    if (!lyrics) return { metadata: {}, lines: [] };
+    if (typeof lyrics === "string") {
+      return parseLRC(lyrics);
+    }
+    if (Array.isArray(lyrics)) {
+      return parseJSONLyrics(lyrics);
+    }
+    if ("type" in lyrics) {
+      switch (lyrics.type) {
+        case "lrc":
+          return parseLRC(lyrics.data);
+        case "json":
+          return parseJSONLyrics(lyrics.data);
+        case "parsed":
+          return lyrics.data;
+      }
+    }
+    return lyrics;
+  }
+  /** Replace the loaded lyrics at any time (e.g. after fetching a file). */
+  setLyrics(lyrics) {
+    const parsed = this.resolveLyrics(lyrics);
+    this.metadata = parsed.metadata;
+    this.lines.length = 0;
+    this.lines.push(...parsed.lines);
+    this.currentIndex = -1;
+    this.handleTimeUpdate();
+  }
+  /** Adjust the global lyric offset (in milliseconds) at runtime. */
+  setOffset(offsetMs) {
+    this.offsetSeconds = offsetMs / 1e3;
+    this.currentIndex = -1;
+    this.handleTimeUpdate();
+  }
+  // ---------------------------------------------------------------------
+  // Playback controls (thin wrappers over the audio element)
+  // ---------------------------------------------------------------------
+  async play() {
+    await this.ready();
+    return this.audio.play();
+  }
+  pause() {
+    this.audio.pause();
+  }
+  toggle() {
+    return this.audio.paused ? this.audio.play() : this.audio.pause();
+  }
+  seek(timeSeconds) {
+    this.audio.currentTime = Math.max(0, timeSeconds);
+    this.handleTimeUpdate();
+  }
+  /** Seek directly to the start of a given lyric line. */
+  seekToLine(index) {
+    const line = this.lines[index];
+    if (line) this.seek(line.time + this.offsetSeconds);
+  }
+  get currentTime() {
+    return this.audio.currentTime;
+  }
+  get duration() {
+    return this.audio.duration;
+  }
+  get paused() {
+    return this.audio.paused;
+  }
+  set volume(value) {
+    this.audio.volume = value;
+  }
+  get volume() {
+    return this.audio.volume;
+  }
+  // ---------------------------------------------------------------------
+  // Lyric lookup
+  // ---------------------------------------------------------------------
+  /** The currently active lyric line, or null if before the first line. */
+  getCurrentLine() {
+    return this.currentIndex >= 0 ? this.lines[this.currentIndex] : null;
+  }
+  /** The index of the currently active lyric line (-1 if none yet). */
+  getCurrentIndex() {
+    return this.currentIndex;
+  }
+  /** The next lyric line after the current one, if any. */
+  getNextLine() {
+    const next = this.lines[this.currentIndex + 1];
+    return next ?? null;
+  }
+  /**
+   * For lines with word-level timing, returns the index of the active
+   * token within the current line (-1 if no tokens or none active yet).
+   */
+  getCurrentTokenIndex() {
+    const line = this.getCurrentLine();
+    if (!line?.tokens?.length) return -1;
+    const t = this.audio.currentTime - this.offsetSeconds;
+    let idx = -1;
+    for (let i = 0; i < line.tokens.length; i++) {
+      if (line.tokens[i].time <= t) idx = i;
+      else break;
+    }
+    return idx;
+  }
+  getCurrentToken() {
+    const line = this.getCurrentLine();
+    const idx = this.getCurrentTokenIndex();
+    return line?.tokens && idx >= 0 ? line.tokens[idx] : null;
+  }
+  /**
+   * Find the line index active at an arbitrary time, without affecting
+   * playback or the cached current index. Uses binary search.
+   */
+  findLineIndexAtTime(timeSeconds) {
+    const t = timeSeconds - this.offsetSeconds;
+    const lines = this.lines;
+    if (lines.length === 0 || t < lines[0].time) return -1;
+    let lo = 0;
+    let hi = lines.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (lines[mid].time <= t) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo;
+  }
+  // ---------------------------------------------------------------------
+  // Event handling
+  // ---------------------------------------------------------------------
+  on(event, listener) {
+    let set = this.listeners[event];
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners[event] = set;
+    }
+    set.add(listener);
+  }
+  off(event, listener) {
+    this.listeners[event]?.delete(listener);
+  }
+  emit(event, ...args) {
+    this.listeners[event]?.forEach((listener) => listener(...args));
+  }
+  /** Remove all listeners and detach from the underlying audio element. */
+  destroy() {
+    this.audio.removeEventListener("timeupdate", this.handleTimeUpdate);
+    this.audio.pause();
+    this.listeners = {};
+  }
+};
+
+export {
+  parseLRC,
+  parseJSONLyrics,
+  LyricPlayer
+};

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -118,7 +128,7 @@ function parseJSONLyrics(json) {
 }
 
 // src/player.ts
-var LyricPlayer = class {
+var LyricPlayer = class _LyricPlayer {
   constructor(options) {
     this.currentIndex = -1;
     this.listeners = {};
@@ -131,7 +141,32 @@ var LyricPlayer = class {
       }
       this.emit("timeupdate", time);
     };
-    this.audio = typeof options.audio === "string" ? new Audio(options.audio) : options.audio;
+    this._readyPromise = this.initialize(options);
+  }
+  static async create(options) {
+    const player = new _LyricPlayer(options);
+    await player.ready();
+    return player;
+  }
+  async initialize(options) {
+    const { skipCBR = false, cbrBitrate = "128k" } = options;
+    let audioSrc;
+    let audioEl;
+    if (typeof options.audio === "string") {
+      audioSrc = options.audio;
+      audioEl = new Audio();
+    } else {
+      audioEl = options.audio;
+      audioSrc = options.audio.src || options.audio.currentSrc;
+    }
+    if (!skipCBR && audioSrc) {
+      const needsConversion = await this.detectNeedsCBR(audioSrc);
+      if (needsConversion) {
+        audioSrc = await this.convertToCBR(audioSrc, cbrBitrate);
+      }
+    }
+    audioEl.src = audioSrc;
+    this.audio = audioEl;
     const parsed = this.resolveLyrics(options.lyrics);
     this.metadata = parsed.metadata;
     this.lines = parsed.lines;
@@ -143,6 +178,71 @@ var LyricPlayer = class {
     this.audio.addEventListener("ended", () => this.emit("ended"));
     this.audio.addEventListener("error", (e) => this.emit("error", e));
   }
+  /** Wait for initialization (CBR conversion, etc.) before playing. */
+  ready() {
+    return this._readyPromise;
+  }
+  /** Detect if file is VBR or lacks proper seek tables. */
+  async detectNeedsCBR(src) {
+    try {
+      const response = await fetch(src, { method: "HEAD" });
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("audio/mpeg") || src.endsWith(".mp3")) {
+        const probe = await fetch(src, { headers: { Range: "bytes=0-1023" } });
+        const buffer = new Uint8Array(await probe.arrayBuffer());
+        return this.hasVBRHeader(buffer);
+      }
+      return true;
+    } catch {
+      return true;
+    }
+  }
+  hasVBRHeader(buffer) {
+    const decoder = new TextDecoder("latin1");
+    const header = decoder.decode(buffer);
+    return /Xing|Info|VBRI/.test(header);
+  }
+  /** Convert audio to CBR using ffmpeg.wasm. */
+  async convertToCBR(src, bitrate) {
+    const [{ FFmpeg }, { fetchFile }] = await Promise.all([
+      import("@ffmpeg/ffmpeg"),
+      import("@ffmpeg/util")
+    ]);
+    const ffmpeg = new FFmpeg();
+    await ffmpeg.load();
+    await ffmpeg.writeFile("input", await fetchFile(src));
+    await ffmpeg.exec([
+      "-i",
+      "input",
+      "-c:a",
+      "libmp3lame",
+      "-b:a",
+      bitrate,
+      "-minrate",
+      bitrate,
+      "-maxrate",
+      bitrate,
+      "-bufsize",
+      "256k",
+      "-preset",
+      "ultrafast",
+      "-fflags",
+      "+fastseek",
+      // Optimize for seeking
+      "-id3v2_version",
+      "3",
+      // Better metadata compatibility
+      "output.mp3"
+    ]);
+    const data = await ffmpeg.readFile("output.mp3");
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    const blob = new Blob(
+      // @ts-ignore — Uint8Array is valid per spec, TS types are overly strict
+      [bytes],
+      { type: "audio/mpeg" }
+    );
+    return URL.createObjectURL(blob);
+  }
   // ---------------------------------------------------------------------
   // Lyric source resolution
   // ---------------------------------------------------------------------
@@ -184,7 +284,8 @@ var LyricPlayer = class {
   // ---------------------------------------------------------------------
   // Playback controls (thin wrappers over the audio element)
   // ---------------------------------------------------------------------
-  play() {
+  async play() {
+    await this.ready();
     return this.audio.play();
   }
   pause() {