lrc-audio-player 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © `2026` `HangerThem`
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# 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`.
+
+## Install
+
+```bash
+npm install lrc-audio-player
+```
+
+## Quick start
+
+```ts
+import { LyricPlayer } from 'lrc-audio-player';
+
+const lrcText = await fetch('/song.lrc').then((r) => r.text());
+
+const player = new LyricPlayer({
+  audio: '/song.mp3',
+  lyrics: lrcText,
+});
+
+player.on('linechange', (line, index) => {
+  console.log(index, line?.text);
+});
+
+player.play();
+```
+
+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 });
+```
+
+## Lyric formats
+
+- **Standard LRC**: `[01:23.45]Some lyric line`
+- **Repeated lines** (e.g. choruses): `[00:10.00][00:20.00]Same line`
+- **Word-level / enhanced LRC**: `[00:01.00]<00:01.00>Hello <00:01.50>world`
+- **Metadata tags**: `[ti:]`, `[ar:]`, `[al:]`, `[by:]`/`[au:]`, `[offset:]`
+- **Plain JSON**: pass an array of `{ time, text }` objects directly, or
+  use `lyrics: { type: 'json', data: [...] }`
+
+```ts
+new LyricPlayer({
+  audio: '/song.mp3',
+  lyrics: [
+    { time: 0, text: 'First line' },
+    { time: 3.5, text: 'Second line' },
+  ],
+});
+```
+
+## API
+
+### `new LyricPlayer(options)`
+
+| 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:]`      |
+
+### Playback
+
+- `play()` / `pause()` / `toggle()` — delegate to the underlying audio element
+- `seek(seconds)` — jump to a specific time
+- `seekToLine(index)` — jump to the start of a given lyric line
+- `currentTime`, `duration`, `paused`, `volume` — pass-through getters/setters
+
+### Lyrics
+
+- `lines: LyricLine[]` — all parsed lines, sorted by time
+- `metadata` — parsed `[ti]`/`[ar]`/`[al]`/`[by]`/`[offset]` tags
+- `getCurrentLine()` / `getCurrentIndex()` — active line right now
+- `getNextLine()` — line after the current one
+- `getCurrentToken()` / `getCurrentTokenIndex()` — active word, for
+  karaoke-style word highlighting (enhanced LRC only)
+- `findLineIndexAtTime(seconds)` — binary-search lookup at an arbitrary time,
+  without touching playback state
+- `setLyrics(...)` — swap in a new lyric source at runtime
+- `setOffset(ms)` — adjust global timing offset at runtime
+
+### Events
+
+`on(event, handler)` / `off(event, handler)`:
+
+| Event        | Payload                                  |
+| ------------ | ------------------------------------------ |
+| `linechange` | `(line: LyricLine \| null, index: number)` |
+| `timeupdate` | `(currentTime: number)`                    |
+| `play`       | —                                           |
+| `pause`      | —                                           |
+| `ended`      | —                                           |
+| `error`      | `(event: Event)`                           |
+
+## Example: word-by-word highlighting
+
+```ts
+player.on('timeupdate', () => {
+  const line = player.getCurrentLine();
+  const tokenIndex = player.getCurrentTokenIndex();
+
+  if (!line?.tokens) return;
+  renderLine(line.tokens.map((tok, i) => ({
+    text: tok.text,
+    active: i === tokenIndex,
+  })));
+});
+```
+
+## Development
+
+```bash
+npm install
+npm run build      # bundle to dist/ (cjs + esm + types)
+npm test           # run vitest
+npm run typecheck  # tsc --noEmit
+```

package/dist/index.cjs

@@ -0,0 +1,310 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LyricPlayer: () => LyricPlayer,
+  parseJSONLyrics: () => parseJSONLyrics,
+  parseLRC: () => parseLRC
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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 });
+    }
+  }
+  const offsetSeconds = (metadata.offset ?? 0) / 1e3;
+  if (offsetSeconds) {
+    for (const line of lines) {
+      line.time -= offsetSeconds;
+      if (line.tokens) {
+        for (const token of line.tokens) {
+          token.time -= offsetSeconds;
+        }
+      }
+    }
+  }
+  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 {
+  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.audio = typeof options.audio === "string" ? new Audio(options.audio) : options.audio;
+    const parsed = this.resolveLyrics(options.lyrics);
+    this.metadata = parsed.metadata;
+    this.lines = parsed.lines;
+    this.offsetSeconds = (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));
+  }
+  // ---------------------------------------------------------------------
+  // 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)
+  // ---------------------------------------------------------------------
+  play() {
+    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 = {};
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LyricPlayer,
+  parseJSONLyrics,
+  parseLRC
+});

package/dist/index.d.cts

@@ -0,0 +1,161 @@
+/**
+ * A single token within a lyric line (for word/syllable-level timing,
+ * "enhanced LRC" style: <mm:ss.xx>word).
+ */
+interface LyricToken {
+    /** Time in seconds at which this token starts. */
+    time: number;
+    /** The text of the token (word, syllable, or chunk). */
+    text: string;
+}
+/**
+ * A single line of lyrics with its start time and optional
+ * word-level timing tokens.
+ */
+interface LyricLine {
+    /** Time in seconds at which this line starts. */
+    time: number;
+    /** Full text of the line (tokens stripped of timestamps, joined). */
+    text: string;
+    /** Optional word/syllable-level tokens, if the source had enhanced timing. */
+    tokens?: LyricToken[];
+    /** Optional metadata tag, e.g. for translation/extension lines (`[tr]` etc). */
+    tag?: string;
+}
+/**
+ * Metadata commonly found in LRC files ([ti], [ar], [al], [by], [offset], etc).
+ */
+interface LyricMetadata {
+    title?: string;
+    artist?: string;
+    album?: string;
+    author?: string;
+    /** Offset in milliseconds. Positive values make lyrics appear later. */
+    offset?: number;
+    [key: string]: string | number | undefined;
+}
+/**
+ * Parsed lyric file: metadata plus a time-sorted array of lines.
+ */
+interface ParsedLyrics {
+    metadata: LyricMetadata;
+    lines: LyricLine[];
+}
+/**
+ * Events emitted by LyricPlayer.
+ */
+interface LyricPlayerEvents {
+    /** Fired whenever the active lyric line index changes (including to -1). */
+    linechange: (line: LyricLine | null, index: number) => void;
+    /** Fired on every underlying `timeupdate` from the audio element. */
+    timeupdate: (currentTime: number) => void;
+    /** Fired when playback starts. */
+    play: () => void;
+    /** Fired when playback pauses. */
+    pause: () => void;
+    /** Fired when the track finishes playing. */
+    ended: () => void;
+    /** Fired if the audio element raises an error. */
+    error: (error: Event) => void;
+}
+type LyricPlayerEventName = keyof LyricPlayerEvents;
+
+type LyricSource = {
+    type: 'lrc';
+    data: string;
+} | {
+    type: 'json';
+    data: string | LyricLine[];
+} | {
+    type: 'parsed';
+    data: ParsedLyrics;
+};
+interface LyricPlayerOptions {
+    /** Audio source: URL/path, or an existing HTMLAudioElement to take over. */
+    audio: string | HTMLAudioElement;
+    /** Lyrics source. Defaults to LRC text if a plain string is passed. */
+    lyrics?: string | LyricLine[] | ParsedLyrics | LyricSource;
+    /**
+     * Additional offset in milliseconds applied on top of any [offset:] tag
+     * in the LRC file. Positive values shift lyrics later.
+     */
+    offsetMs?: number;
+}
+type Listener<E extends LyricPlayerEventName> = LyricPlayerEvents[E];
+/**
+ * Wraps an HTMLAudioElement together with parsed, time-synced lyrics.
+ *
+ * ```ts
+ * const player = new LyricPlayer({ audio: 'song.mp3', lyrics: lrcText });
+ * player.on('linechange', (line) => console.log(line?.text));
+ * player.play();
+ * ```
+ */
+declare class LyricPlayer {
+    readonly audio: HTMLAudioElement;
+    readonly metadata: LyricMetadata;
+    readonly lines: LyricLine[];
+    private offsetSeconds;
+    private currentIndex;
+    private listeners;
+    constructor(options: LyricPlayerOptions);
+    private resolveLyrics;
+    /** Replace the loaded lyrics at any time (e.g. after fetching a file). */
+    setLyrics(lyrics: LyricPlayerOptions['lyrics']): void;
+    /** Adjust the global lyric offset (in milliseconds) at runtime. */
+    setOffset(offsetMs: number): void;
+    play(): Promise<void>;
+    pause(): void;
+    toggle(): Promise<void> | void;
+    seek(timeSeconds: number): void;
+    /** Seek directly to the start of a given lyric line. */
+    seekToLine(index: number): void;
+    get currentTime(): number;
+    get duration(): number;
+    get paused(): boolean;
+    set volume(value: number);
+    get volume(): number;
+    /** The currently active lyric line, or null if before the first line. */
+    getCurrentLine(): LyricLine | null;
+    /** The index of the currently active lyric line (-1 if none yet). */
+    getCurrentIndex(): number;
+    /** The next lyric line after the current one, if any. */
+    getNextLine(): LyricLine | 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(): number;
+    getCurrentToken(): LyricToken | null;
+    /**
+     * Find the line index active at an arbitrary time, without affecting
+     * playback or the cached current index. Uses binary search.
+     */
+    findLineIndexAtTime(timeSeconds: number): number;
+    on<E extends LyricPlayerEventName>(event: E, listener: Listener<E>): void;
+    off<E extends LyricPlayerEventName>(event: E, listener: Listener<E>): void;
+    private emit;
+    private handleTimeUpdate;
+    /** Remove all listeners and detach from the underlying audio element. */
+    destroy(): void;
+}
+
+/**
+ * Parse an LRC-format lyric file into structured, time-sorted lines plus
+ * any metadata tags found at the top of the file.
+ *
+ * Supports:
+ *  - Standard line timestamps: `[01:23.45]Some lyric text`
+ *  - Multiple timestamps per line (repeated lines): `[00:01.00][00:05.00]Chorus`
+ *  - Word-level / "enhanced" timing: `[00:01.00]<00:01.00>Hello <00:01.50>world`
+ *  - Metadata tags: `[ti:Title]`, `[ar:Artist]`, `[al:Album]`, `[by:Author]`, `[offset:1000]`
+ */
+declare function parseLRC(lrc: string): ParsedLyrics;
+/**
+ * Parse a simple JSON lyric format:
+ * `[{ "time": 1.0, "text": "Hello" }, ...]`
+ * Useful as an alternative to LRC when you control the lyric source yourself.
+ */
+declare function parseJSONLyrics(json: string | LyricLine[]): ParsedLyrics;
+
+export { type LyricLine, type LyricMetadata, LyricPlayer, type LyricPlayerEventName, type LyricPlayerEvents, type LyricPlayerOptions, type LyricSource, type LyricToken, type ParsedLyrics, parseJSONLyrics, parseLRC };

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * A single token within a lyric line (for word/syllable-level timing,
+ * "enhanced LRC" style: <mm:ss.xx>word).
+ */
+interface LyricToken {
+    /** Time in seconds at which this token starts. */
+    time: number;
+    /** The text of the token (word, syllable, or chunk). */
+    text: string;
+}
+/**
+ * A single line of lyrics with its start time and optional
+ * word-level timing tokens.
+ */
+interface LyricLine {
+    /** Time in seconds at which this line starts. */
+    time: number;
+    /** Full text of the line (tokens stripped of timestamps, joined). */
+    text: string;
+    /** Optional word/syllable-level tokens, if the source had enhanced timing. */
+    tokens?: LyricToken[];
+    /** Optional metadata tag, e.g. for translation/extension lines (`[tr]` etc). */
+    tag?: string;
+}
+/**
+ * Metadata commonly found in LRC files ([ti], [ar], [al], [by], [offset], etc).
+ */
+interface LyricMetadata {
+    title?: string;
+    artist?: string;
+    album?: string;
+    author?: string;
+    /** Offset in milliseconds. Positive values make lyrics appear later. */
+    offset?: number;
+    [key: string]: string | number | undefined;
+}
+/**
+ * Parsed lyric file: metadata plus a time-sorted array of lines.
+ */
+interface ParsedLyrics {
+    metadata: LyricMetadata;
+    lines: LyricLine[];
+}
+/**
+ * Events emitted by LyricPlayer.
+ */
+interface LyricPlayerEvents {
+    /** Fired whenever the active lyric line index changes (including to -1). */
+    linechange: (line: LyricLine | null, index: number) => void;
+    /** Fired on every underlying `timeupdate` from the audio element. */
+    timeupdate: (currentTime: number) => void;
+    /** Fired when playback starts. */
+    play: () => void;
+    /** Fired when playback pauses. */
+    pause: () => void;
+    /** Fired when the track finishes playing. */
+    ended: () => void;
+    /** Fired if the audio element raises an error. */
+    error: (error: Event) => void;
+}
+type LyricPlayerEventName = keyof LyricPlayerEvents;
+
+type LyricSource = {
+    type: 'lrc';
+    data: string;
+} | {
+    type: 'json';
+    data: string | LyricLine[];
+} | {
+    type: 'parsed';
+    data: ParsedLyrics;
+};
+interface LyricPlayerOptions {
+    /** Audio source: URL/path, or an existing HTMLAudioElement to take over. */
+    audio: string | HTMLAudioElement;
+    /** Lyrics source. Defaults to LRC text if a plain string is passed. */
+    lyrics?: string | LyricLine[] | ParsedLyrics | LyricSource;
+    /**
+     * Additional offset in milliseconds applied on top of any [offset:] tag
+     * in the LRC file. Positive values shift lyrics later.
+     */
+    offsetMs?: number;
+}
+type Listener<E extends LyricPlayerEventName> = LyricPlayerEvents[E];
+/**
+ * Wraps an HTMLAudioElement together with parsed, time-synced lyrics.
+ *
+ * ```ts
+ * const player = new LyricPlayer({ audio: 'song.mp3', lyrics: lrcText });
+ * player.on('linechange', (line) => console.log(line?.text));
+ * player.play();
+ * ```
+ */
+declare class LyricPlayer {
+    readonly audio: HTMLAudioElement;
+    readonly metadata: LyricMetadata;
+    readonly lines: LyricLine[];
+    private offsetSeconds;
+    private currentIndex;
+    private listeners;
+    constructor(options: LyricPlayerOptions);
+    private resolveLyrics;
+    /** Replace the loaded lyrics at any time (e.g. after fetching a file). */
+    setLyrics(lyrics: LyricPlayerOptions['lyrics']): void;
+    /** Adjust the global lyric offset (in milliseconds) at runtime. */
+    setOffset(offsetMs: number): void;
+    play(): Promise<void>;
+    pause(): void;
+    toggle(): Promise<void> | void;
+    seek(timeSeconds: number): void;
+    /** Seek directly to the start of a given lyric line. */
+    seekToLine(index: number): void;
+    get currentTime(): number;
+    get duration(): number;
+    get paused(): boolean;
+    set volume(value: number);
+    get volume(): number;
+    /** The currently active lyric line, or null if before the first line. */
+    getCurrentLine(): LyricLine | null;
+    /** The index of the currently active lyric line (-1 if none yet). */
+    getCurrentIndex(): number;
+    /** The next lyric line after the current one, if any. */
+    getNextLine(): LyricLine | 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(): number;
+    getCurrentToken(): LyricToken | null;
+    /**
+     * Find the line index active at an arbitrary time, without affecting
+     * playback or the cached current index. Uses binary search.
+     */
+    findLineIndexAtTime(timeSeconds: number): number;
+    on<E extends LyricPlayerEventName>(event: E, listener: Listener<E>): void;
+    off<E extends LyricPlayerEventName>(event: E, listener: Listener<E>): void;
+    private emit;
+    private handleTimeUpdate;
+    /** Remove all listeners and detach from the underlying audio element. */
+    destroy(): void;
+}
+
+/**
+ * Parse an LRC-format lyric file into structured, time-sorted lines plus
+ * any metadata tags found at the top of the file.
+ *
+ * Supports:
+ *  - Standard line timestamps: `[01:23.45]Some lyric text`
+ *  - Multiple timestamps per line (repeated lines): `[00:01.00][00:05.00]Chorus`
+ *  - Word-level / "enhanced" timing: `[00:01.00]<00:01.00>Hello <00:01.50>world`
+ *  - Metadata tags: `[ti:Title]`, `[ar:Artist]`, `[al:Album]`, `[by:Author]`, `[offset:1000]`
+ */
+declare function parseLRC(lrc: string): ParsedLyrics;
+/**
+ * Parse a simple JSON lyric format:
+ * `[{ "time": 1.0, "text": "Hello" }, ...]`
+ * Useful as an alternative to LRC when you control the lyric source yourself.
+ */
+declare function parseJSONLyrics(json: string | LyricLine[]): ParsedLyrics;
+
+export { type LyricLine, type LyricMetadata, LyricPlayer, type LyricPlayerEventName, type LyricPlayerEvents, type LyricPlayerOptions, type LyricSource, type LyricToken, type ParsedLyrics, parseJSONLyrics, parseLRC };

package/dist/index.js

@@ -0,0 +1,281 @@
+// 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 });
+    }
+  }
+  const offsetSeconds = (metadata.offset ?? 0) / 1e3;
+  if (offsetSeconds) {
+    for (const line of lines) {
+      line.time -= offsetSeconds;
+      if (line.tokens) {
+        for (const token of line.tokens) {
+          token.time -= offsetSeconds;
+        }
+      }
+    }
+  }
+  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 {
+  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.audio = typeof options.audio === "string" ? new Audio(options.audio) : options.audio;
+    const parsed = this.resolveLyrics(options.lyrics);
+    this.metadata = parsed.metadata;
+    this.lines = parsed.lines;
+    this.offsetSeconds = (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));
+  }
+  // ---------------------------------------------------------------------
+  // 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)
+  // ---------------------------------------------------------------------
+  play() {
+    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 {
+  LyricPlayer,
+  parseJSONLyrics,
+  parseLRC
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "lrc-audio-player",
+  "version": "0.1.0",
+  "description": "Sync LRC/word-level lyrics to an HTML audio element with one constructor.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hangerthem/lrc-audio-player.git"
+  },
+  "homepage": "https://github.com/hangerthem/lrc-audio-player#readme",
+  "bugs": "https://github.com/hangerthem/lrc-audio-player/issues",
+  "author": "HangerThem",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "lyrics",
+    "lrc",
+    "audio",
+    "player",
+    "karaoke",
+    "sync"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
+  }
+}