lrc_parser 0.0.1

An ANTLR4-based library to parse, validate, and edit LRC lyrics file. Supports normal, word and hybrid level of lyrics with time-shifting capabilities.

Dart LRC Parser & Editor

An ANTLR4-based Dart library for processing LRC lyrics files. This library supports parsing, validating, modifying, and exporting lyrics in Normal (line-level), Extended (word-level), and Hybrid formats.

Features

• Parsing: Handles mixed formats, duplicated tags, and overly precise timestamps.
• Validation: Detects syntax errors, duplicate metadata keys, and logic errors.
• Editor: A tool to:
  • Shift timestamps.
  • Scale playback speed (speed-up/slow-down).
  • Add new lyrics (both simple and word-synced).
  • Edit metadata with type safety.
• Flexible Export: formatting options to output collapsed or linear LRC strings.

Installation

1. Add the ANTLR runtime to your pubspec.yaml.

dependencies:
  antlr4: 4.13.2

2. Import the statement in your project.

import 'package:lrc_parser/lrc_parser.dart';

Usage

1. Parsing LRC Content

Use the LrcParser class to convert a raw string into an LrcFile object.

import 'package:lrc_parser/lrc_parser.dart';

void main() {
  const rawLrc = """
[ti:Example Song]
[ar:Artist Name]
[00:10.00]Line one lyrics
[00:15.00]<00:15.00>Kara <00:15.50>oke <00:16.00>Mode
""";

  // Parse the string
  final lrcFile = LrcParser.parseString(rawLrc);

  // Access Metadata
  print("Title: ${lrcFile.title}");
  print("Type: ${lrc.type}"); // LrcType.hybrid

  // Access Lines
  for (var line in lrcFile.lines) {
    print("[${line.timestamp}] ${line.text}");

    // Check for sub-timestamps
    if (line.words.length > 1) {
      print("  -> Details: ${line.words}");
    }
  }
}

2. Error Handling

The parser collects errors found in the errors list during the parsing process.

if (lrcFile.errors.isNotEmpty) {
  print("--- Errors Detected ---");
  for (var e in lrcFile.errors) {
    // Example: Line 3: Timestamp precision too high...
    print("Line ${e.line}: ${e.message} (Found: '${e.invalidCharacter}')");
  }
}

3. Editing with LrcEditor

The LrcEditor allows you to modify an existing file or build one from scratch.

import 'package:lrc_parser/lrc_parser.dart';

// Initialize from parsed model
final editor = LrcEditor.fromModel(lrcFile);

// OR Initialize empty
// final editor = LrcEditor();

// --- Editing Metadata ---
editor.artist = "New Artist";
editor.length = Duration(minutes: 3, seconds: 45); // Sets [length:03:45]
editor.tool = "Testing"; // Sets [re:Testing]
editor.addCustomTag("any", "hello the world");

// --- Editing Lyrics ---

// 1. Time Shifting: Delay song by 500ms
editor.shiftTime(Duration(milliseconds: 500));

// 2. Speed Scaling: Convert for 1.2x speed (shorter durations)
editor.scaleTime(1 / 1.2);

// 3. Adding a new Standard Line
editor.addLyricsLine(
  timestamp: Duration(seconds: 20),
  text: "New standard line inserted chronologically"
);

// 4. Adding a new Word-Synced Line
editor.addLyricsLine(
  timestamp: Duration(seconds: 25),
  wordParts: [
    (Duration(seconds: 25), "Sin"),
    (Duration(milliseconds: 25500), "gle"),
    (Duration(seconds: 26), " Word"),
  ]
);

4. Exporting / Saving

Convert the edited content back to a string.

// Standard Output
String output = editor.format();

// Collapsed Output
// Merges identical lines (e.g. [00:10][00:20]Chorus)
String compactOutput = editor.format(isCollapsed: true);

print(compactOutput);

Detail

Parser

The core parsing logic of this library is built using ANTLR4.

The files inside lib/src/generated are generated from the grammar files from another repository.