lrc-audio-player 0.1.1 → 0.1.2

package/dist/react.cjs

@@ -0,0 +1,335 @@
+"use strict";
+"use client";
+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/react.ts
+var react_exports = {};
+__export(react_exports, {
+  useLyricPlayer: () => useLyricPlayer
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+
+// 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 {
+  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;
+    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));
+  }
+  // ---------------------------------------------------------------------
+  // 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 = {};
+  }
+};
+
+// src/react.ts
+function useLyricPlayer(options) {
+  const audioRef = (0, import_react.useRef)(null);
+  const [player, setPlayer] = (0, import_react.useState)(null);
+  const [currentLine, setCurrentLine] = (0, import_react.useState)(null);
+  const [currentIndex, setCurrentIndex] = (0, import_react.useState)(-1);
+  const [lines, setLines] = (0, import_react.useState)([]);
+  const optionsRef = (0, import_react.useRef)(options);
+  optionsRef.current = options;
+  (0, import_react.useEffect)(() => {
+    const audioEl = audioRef.current;
+    if (!audioEl) return;
+    const { audio, lyrics, offsetMs } = optionsRef.current;
+    if (audio) audioEl.src = audio;
+    const instance = new LyricPlayer({
+      audio: audioEl,
+      lyrics,
+      offsetMs
+    });
+    setPlayer(instance);
+    setLines(instance.lines);
+    setCurrentLine(null);
+    setCurrentIndex(-1);
+    instance.on("linechange", (line, index) => {
+      setCurrentLine(line);
+      setCurrentIndex(index);
+    });
+    return () => {
+      instance.destroy();
+      setPlayer(null);
+    };
+  }, [options.audio, options.lyrics, options.offsetMs]);
+  return { player, audioRef, currentLine, currentIndex, lines };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useLyricPlayer
+});

package/dist/react.d.cts

@@ -0,0 +1,51 @@
+import { h as LyricPlayerOptions, b as LyricPlayer, L as LyricLine } from './player-C3ZCZJVs.cjs';
+export { f as LyricSource } from './player-C3ZCZJVs.cjs';
+
+interface UseLyricPlayerOptions extends Omit<LyricPlayerOptions, "audio"> {
+    /** Audio source URL. Set on the bound <audio> element. */
+    audio?: string;
+}
+interface UseLyricPlayerResult {
+    /** The underlying player instance (null until mounted and ready). */
+    player: LyricPlayer | null;
+    /** Ref to attach to your <audio> element. */
+    audioRef: React.RefObject<HTMLAudioElement | null>;
+    /** The currently active lyric line, or null before the first line. */
+    currentLine: LyricLine | null;
+    /** Index of the currently active lyric line (-1 if none yet). */
+    currentIndex: number;
+    /** All parsed lyric lines (empty until lyrics are loaded). */
+    lines: LyricLine[];
+}
+/**
+ * React hook that creates a {@link LyricPlayer} bound to an `<audio>`
+ * element via ref, and keeps the active lyric line in sync with React
+ * state via the `linechange` event.
+ *
+ * Must be used in a Client Component - `LyricPlayer` requires a real
+ * `HTMLAudioElement`, which doesn't exist during SSR.
+ *
+ * ```tsx
+ * 'use client';
+ *
+ * const { audioRef, currentLine, lines, player } = useLyricPlayer({
+ *   audio: '/song.mp3',
+ *   lyrics: lrcText,
+ * });
+ *
+ * return (
+ *   <>
+ *     <audio ref={audioRef} controls />
+ *     <p>{currentLine?.text}</p>
+ *   </>
+ * );
+ * ```
+ *
+ * The player is recreated whenever `audio` or `lyrics` change. If you're
+ * fetching lyrics asynchronously, wait until they're loaded before calling
+ * this hook (or pass `lyrics: ''` while loading - an empty string parses
+ * to zero lines and is cheap to recreate).
+ */
+declare function useLyricPlayer(options: UseLyricPlayerOptions): UseLyricPlayerResult;
+
+export { type UseLyricPlayerOptions, type UseLyricPlayerResult, useLyricPlayer };

package/dist/react.d.ts

@@ -0,0 +1,51 @@
+import { h as LyricPlayerOptions, b as LyricPlayer, L as LyricLine } from './player-C3ZCZJVs.js';
+export { f as LyricSource } from './player-C3ZCZJVs.js';
+
+interface UseLyricPlayerOptions extends Omit<LyricPlayerOptions, "audio"> {
+    /** Audio source URL. Set on the bound <audio> element. */
+    audio?: string;
+}
+interface UseLyricPlayerResult {
+    /** The underlying player instance (null until mounted and ready). */
+    player: LyricPlayer | null;
+    /** Ref to attach to your <audio> element. */
+    audioRef: React.RefObject<HTMLAudioElement | null>;
+    /** The currently active lyric line, or null before the first line. */
+    currentLine: LyricLine | null;
+    /** Index of the currently active lyric line (-1 if none yet). */
+    currentIndex: number;
+    /** All parsed lyric lines (empty until lyrics are loaded). */
+    lines: LyricLine[];
+}
+/**
+ * React hook that creates a {@link LyricPlayer} bound to an `<audio>`
+ * element via ref, and keeps the active lyric line in sync with React
+ * state via the `linechange` event.
+ *
+ * Must be used in a Client Component - `LyricPlayer` requires a real
+ * `HTMLAudioElement`, which doesn't exist during SSR.
+ *
+ * ```tsx
+ * 'use client';
+ *
+ * const { audioRef, currentLine, lines, player } = useLyricPlayer({
+ *   audio: '/song.mp3',
+ *   lyrics: lrcText,
+ * });
+ *
+ * return (
+ *   <>
+ *     <audio ref={audioRef} controls />
+ *     <p>{currentLine?.text}</p>
+ *   </>
+ * );
+ * ```
+ *
+ * The player is recreated whenever `audio` or `lyrics` change. If you're
+ * fetching lyrics asynchronously, wait until they're loaded before calling
+ * this hook (or pass `lyrics: ''` while loading - an empty string parses
+ * to zero lines and is cheap to recreate).
+ */
+declare function useLyricPlayer(options: UseLyricPlayerOptions): UseLyricPlayerResult;
+
+export { type UseLyricPlayerOptions, type UseLyricPlayerResult, useLyricPlayer };

package/dist/react.js

@@ -0,0 +1,43 @@
+"use client";
+import {
+  LyricPlayer
+} from "./chunk-O4Y7SZ2V.js";
+
+// src/react.ts
+import { useEffect, useRef, useState } from "react";
+function useLyricPlayer(options) {
+  const audioRef = useRef(null);
+  const [player, setPlayer] = useState(null);
+  const [currentLine, setCurrentLine] = useState(null);
+  const [currentIndex, setCurrentIndex] = useState(-1);
+  const [lines, setLines] = useState([]);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  useEffect(() => {
+    const audioEl = audioRef.current;
+    if (!audioEl) return;
+    const { audio, lyrics, offsetMs } = optionsRef.current;
+    if (audio) audioEl.src = audio;
+    const instance = new LyricPlayer({
+      audio: audioEl,
+      lyrics,
+      offsetMs
+    });
+    setPlayer(instance);
+    setLines(instance.lines);
+    setCurrentLine(null);
+    setCurrentIndex(-1);
+    instance.on("linechange", (line, index) => {
+      setCurrentLine(line);
+      setCurrentIndex(index);
+    });
+    return () => {
+      instance.destroy();
+      setPlayer(null);
+    };
+  }, [options.audio, options.lyrics, options.offsetMs]);
+  return { player, audioRef, currentLine, currentIndex, lines };
+}
+export {
+  useLyricPlayer
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lrc-audio-player",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Sync LRC/word-level lyrics to an HTML audio element with one constructor. Includes an optional React hook at lrc-audio-player/react.",
   "repository": {
     "type": "git",
@@ -33,11 +33,11 @@
     "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",
+    "build": "tsup src/index.ts src/react.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts src/react.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
   },
   "keywords": [
     "lyrics",