@3sv1n/lrc

A pure, framework-agnostic parser and serializer for LRC lyric files.

Features

• Zero dependencies: Works in browser and Node.js.
• Robust parsing: Handles standard [mm:ss.xx] and [mm:ss.xxx] timestamp formats.
• Utility functions: Built-in tools for offsetting, shifting, and finding the active lyric line for a given time.

Installation

npm install @3sv1n/lrc
# or
yarn add @3sv1n/lrc
# or
pnpm add @3sv1n/lrc

Basic Usage

Parsing LRC

import { parseLrc } from '@3sv1n/lrc';

const rawLrc = `
[00:12.00]Line 1 lyrics
[00:15.30]Line 2 lyrics
`;

const lines = parseLrc(rawLrc);
/*
[
  { time: 12.00, text: "Line 1 lyrics" },
  { time: 15.30, text: "Line 2 lyrics" }
]
*/

Finding the Active Line

Given an array of parsed LyricLines and a current playback time in seconds, you can quickly find which line is currently active.

import { getActiveLineIndex } from '@3sv1n/lrc';

const activeIndex = getActiveLineIndex(lines, 13.5); 
// Returns 0 (Line 1 lyrics)

API Reference

Types

interface LyricLine {
  time: number; // Time in seconds
  text: string;
}

interface ParseOptions {
  /** Whether to trim whitespace from the beginning and end of lyric text. Default is true. */
  trimWhitespace?: boolean;
}

parseLrc(lrcString: string, options?: ParseOptions): LyricLine[]

Parses an LRC format string into an array of chronologically sorted LyricLine objects.

serializeLrc(lines: LyricLine[]): string

Serializes an array of LyricLine objects back into an LRC format string. It automatically sorts the lines chronologically before outputting.

getActiveLineIndex(lines: LyricLine[], timeInSeconds: number): number

Returns the index of the active lyric line for a given time. Returns -1 if the time is before the first line.

offsetLyrics(lines: LyricLine[], offsetSeconds: number): LyricLine[]

Returns a new array of lines with the offset added to the time of each line. Useful when audio and lyrics are slightly out of sync.

shiftLyrics(lines: LyricLine[], scaleFactor: number): LyricLine[]

Returns a new array of lines with their times multiplied by scaleFactor.

sortLyrics(lines: LyricLine[]): LyricLine[]

Returns a chronologically sorted copy of the lyric lines.

validateLyrics(lines: LyricLine[]): boolean

Returns true if the lines array is chronologically sorted and times are non-negative.