Demo | npm | Documention

Lyrica.js

Lyrica.js is an open-source JavaScript library for working with .lrc lyric files. It provides tools for parsing lyrics, synchronizing them with audio, rendering them in the browser, and extracting structured lyric data.

Lyrica.js is under development, and some APIs may change between releases as the architecture continues to improve.

Features

• Core Features:

  • Sync - Render lyrics and synchronize them in real time with an HTML <audio> element.

  • Print - Render lyrics from .lrc files without syncing.

  • Extract - Parse .lrc files to get structured lyric, timing, and metadata data.

• Rendering - Two styles: normal (static) and slide. Optional auto-scroll, wheel/touch scroll handling, and click-to-seek.

• Playback Control - Start, pause, next, previous, go to a specific lyric/time, retrieve current lyric info in real-time.

• Search - Find a lyric by time or find the timestamp(s) for a given lyric.

Installation

via npm

npm i lyrica

Manual

Download Lyrica.umd.js from dist folder and include it in your project:

<script src="./Lyrica.umd.js"></script>

Quick Start

HTML:

<audio id="my-audio" src="song.mp3" controls></audio>
<div class="lyrica-container"></div>

JavaScript

const example = new Lyrica("./example.lrc", {
    type: "sync",
    audio_selector: "#my-audio",
    container_selector: ".lyrica-container",
    animations: {
        animation_type: "slide",
        auto_scroll: true
    }
});

Basic Usage

const example = new Lyrica(Path, Options)

Path

The first parameter is a string that can be either a .lrc file path or raw .lrc text. (required)

Options

The second parameter is an options object that configures the class.(required)

Option	Type	Default	Description
type	string	-	"sync", "print, "extract" (required)
isRaw	boolean	false	Pass raw .lrc text instead of file path
offset	number	inset .lrc offset / 0	Adjust lyric timing in millisecond
audio_selector	string	-	CSS selector for <audio> element (required for "sync")
container_selector	string	-	CSS selector for lyrics container (required for "sync")
animations	object	-	Animation settings (see below)
isKaraoke	boolean	false	Enable advanced timing parse
actKaraoke	boolean	isKaraoke's value	Whether to actively display karaoke segment

Animations

Key	Type	Default	Description
animation_type	string	"normal"	"normal" or "slide"
auto_scroll	boolean	false	Automatically scroll to the active lyric (only in "slide")
wheel_scroll	boolean	true	Enable mouse-wheel scrolling within sync scroll constraints (only in "slide")
touch_scroll	boolean	true	Enable touch scrolling within sync scroll constraints (only in "slide")
change_onclick	boolean	true	Clicking a lyric seeks audio (only in "slide")
keyframe_id	string	"LyricaLyricIn"	The name of a CSS keyframe animation that will be applied only when a lyric becomes active in "normal" mode.
animation_parameters	string	'ease-out 0.2s'	Additional parameters passed to the animation call

Options Object Structure

{
  type: "sync" | "print" | "extract", // Required
  audio_selector: "#audio", // Required for "sync" type
  container_selector: "#lyrics", // Required for "sync" and "print" types
  isKaraoke: false, // Optional
  actKaraoke: false, // Optional
  isRaw: false, // Optional
  autoStart: true, // Optional
  offset: 0, // Optional
  animations: { // Optional
    animation_type: "normal" | "slide",
    animation_parameters: "ease-out 0.2s",
    keyframe_id: "LyricaLyricIn",
    auto_scroll: true,
    wheel_scroll: true,
    touch_scroll: true
  }
}

---

Methods

Constructor and Static Methods

Method	Parameters	Description	Example
constructor(path, options)	path: String options: Object	Initializes a new Lyrica instance with the given LRC file path and options	new Lyrica("lyrics.lrc", {type: "sync"})
static load(path, options)	path: String options: Object	Asynchronously creates and initializes a Lyrica instance	await Lyrica.load("lyrics.lrc", {type: "sync"})

Core Methods

Method	Parameters	Return Value	Description	Example
getData()	None	Object	Returns all lyrics data including times, lyrics text, and metadata	example.getData()
getCurrent()	None	Array	Returns current lyric info [text, time, index]. Only works in "sync" mode	example.getCurrent()
start()	None	None	Starts syncing lyrics with audio. Only works in "sync" mode	example.start()
pause()	None	None	Pauses lyric syncing. Only works in "sync" mode	example.pause()

Navigation Methods

Method	Parameters	Return Value	Description	Example
next(distance)	distance: Number (optional)	Array/undefined	Jumps to next lyric. Returns [text, time, index] or undefined	example.next() or example.next(2)
previous(distance)	distance: Number (optional)	Array/undefined	Jumps to previous lyric. Returns [text, time, index] or undefined	example.previous() or example.previous(2)
last()	None	Array/undefined	Returns to last played lyric. Returns [text, time, index] or undefined	example.last()

Search Methods

Method	Parameters	Return Value	Description	Example
searchLyric(time, exact, index)	time: String/Number exact: Boolean index: Boolean	Array	Finds lyrics by timestamp	example.searchLyric("1:30.00", false, true)
searchTime(lyric, index)	lyric: String index: Boolean	Array	Finds timestamp(s) for given lyric text	example.searchTime("Hello", true)
goTo(place)	place: Object	Array/undefined	Jumps to specific position by time, lyric text, or index	example.goTo({time: "1:30.00"})

---

CSS Classes

• Each lyric line is rendered inside an element with the class .lyric (applies to both normal and slide modes).
• Active state:
  • In slide mode: the current line or current word (in karaoke) receives the .active class.
  • In normal mode: only the current word receives the .active class.
• Passed lines: any line that has already been played is marked with the .passed class. (only in "slide")
• Tag types:
  • By default (no karaoke), each line is a <p> element in both normal and slide modes.
  • When isKaraoke: true and actKaraoke: true, each word inside the line is wrapped in a <span> for fine-grained karaoke highlighting.
• In karaoke + actKaraoke, the line itself still has the .lyric class, but instead of plain text, its words are split into <span>s so timing can highlight each word individually.

---

License

MIT License © mahan-ameri

---