ModernLrc 1.2.0

ModernLrc

Modern, performance-first LRC (lyrics) parser and writer for .NET 10. AOT-compatible, trim-safe, zero non-BCL runtime dependencies.

📖 Full documentation, API reference, and topical guides: https://anthonyy232.github.io/ModernLrcParser (also browseable in the docs/ folder).

Features

• Full LRC support — simple [mm:ss.xx]text, multi-timestamp [t1][t2]…, Enhanced LRC word timing <…>, Walaoke voice markers (M: / F: / D:) with state propagation.
• Tolerant by default with rich diagnostics; opt-in LrcStrictness.Strict for fail-fast behaviour.
• Span-first hand-rolled scanner — no regex, no backtracking, zero per-token transient allocations.
• Every input shape — string, ReadOnlySpan<char>, ReadOnlyMemory<char>, TextReader, ReadOnlySpan<byte>, byte[], Stream, file paths; sync and async.
• Zero-allocation writer via IBufferWriter<char> and UTF-8 byte sinks; the Write → string, TextWriter, TryWrite, and Stream sinks pre-size their staging buffer to the document's estimated size so large renders don't accumulate copy-on-grow waste; atomic file write via temp + rename.
• Encoding pipeline — BOM detection (UTF-8, UTF-16 LE/BE) → caller override → UTF-8 validation → caller-supplied fallback.
• Diagnostics catalogue — every recoverable concern surfaces as a stable diagnostic code (LRC0001–LRC0099) with line/column location.

Install

dotnet add package ModernLrc

Requirements

• .NET 10 runtime (consumers).
• .NET 10 SDK (pinned via global.json) only required to build from source.

Quick start

using ModernLrc;
using ModernLrc.Model;

// Parse
var result = LrcParser.Parse("[ti:Demo]\n[00:01.00]hello\n");
Console.WriteLine(result.Document.Metadata.Title); // Demo

// Author + write
var doc = new LrcDocumentBuilder()
    .WithTitle("My Song")
    .AddLine("00:12.00", "first line")
    .AddLine("00:14.20", "second line", LrcVoice.Female)
    .Build();
string lrc = LrcWriter.Write(doc);

Design notes

Offset model

Documents store the [offset:N] tag verbatim in Metadata.Offset. Line timestamps are NOT mutated at parse time. Apply the offset on demand:

var doc = LrcParser.Parse(text).Document;
TimeSpan effective = doc.GetEffectiveTime(line.Timestamp);
LrcLine? current = doc.FindLineAt(currentPlayhead);  // already factors offset in

This preserves round-trip fidelity — re-writing the document emits the original [offset:N] tag rather than collapsing it into mutated timestamps.

Round-trip fidelity applies to supported LRC syntax. If authored plain lyric text contains valid-looking LRC markers such as <00:01.00>, a later parse will treat those markers as syntax.

Encoding model

Byte/stream input uses this priority:

1. BOM detection (UTF-8 EF BB BF, UTF-16 LE FF FE, UTF-16 BE FE FF).
2. Caller-supplied LrcParseOptions.Encoding if set.
3. UTF-8 validation (rejects malformed sequences).
4. LrcParseOptions.FallbackEncoding (default Encoding.UTF8); emits LRC0010 at Error severity if it kicks in. Set FallbackEncoding = null to fail loudly instead.

For non-Unicode encodings without a BOM (Shift-JIS, GBK, Big5), provide the encoding explicitly — statistical detection is intentionally out of scope.

Whitespace and empty lines

Lyric text is preserved verbatim, including whitespace-only lines and trailing whitespace. Apply display filters at the UI layer:

foreach (var line in doc.Lines)
{
    if (line is LrcPlainLine p && string.IsNullOrWhiteSpace(p.Text)) continue;
    Render(line);
}

Tolerantly accepted variants

Beyond the canonical [mm:ss.xx], the parser accepts these in tolerant mode (the default), each producing an informational diagnostic:

Set LrcParseOptions.Strictness = LrcStrictness.Strict to throw LrcParseException on the first error-severity diagnostic. Tolerant mode collects everything for inspection on LrcParseResult.Diagnostics.

Comparison

ModernLrc compared to other .NET LRC parsers as of 2026-04-28.

Performance

Throughput on synthetic basic-LRC inputs (Small ≈ 20 lines, Medium ≈ 200 lines, Large ≈ 2,000 lines). Lower is better. Ratio is relative to ModernLrc.

Parse

Write

ModernLrc edges Opportunity.LrcParser on small inputs and trails by 19–27% on larger inputs; the gap is the cost of its broader feature surface (recovery, structured diagnostics, voice tracking, encoding detection, word-level timing, stable sort with reorder detection). Allocation is within 2% across all sizes. ModernLrc leads on write across every input size — 13–26% faster than Opportunity.LrcParser and ~1.7–2.1× faster than karaoke-dev/LrcParser — while still emitting consecutive same-text lines as a collapsed [t1][t2]text group by default for round-trip fidelity.

Features

¹ SharpLyrics has internal word-time extraction, but the public API surfaces only single-timestamp lines from a file path — no string input. ² Opportunity.LrcParser exposes LineWithSpeaker for Speaker: text patterns, not the Walaoke M:/F:/D: voice protocol with state propagation. ³ Opportunity.LrcParser collects parse exceptions in a list, but they are unstructured (no diagnostic codes or severity).

Methodology

• Workload: synthetic basic-LRC inputs ([mm:ss.xx]text + ID3 metadata header), Small ≈ 20 lines, Medium ≈ 200 lines, Large ≈ 2,000 lines. Inputs are stored as string constants — no file I/O on the timed path. SharpLyrics requires a file path, so its corpus is staged to a temp file in [GlobalSetup] (one-time cost outside the timed region).
• Each parser called via the smallest possible idiomatic public entry point — no tuning.
• Write benchmarks start from each library's own parsed model (parsed once in [GlobalSetup]) so the timed region measures serialisation only, not cross-model conversion.
• Environment: BenchmarkDotNet 0.15.8, .NET 10.0.7 (SDK 10.0.202), Windows 11, AMD Ryzen 5 5600 (6 cores, 12 threads).
• Numbers will drift across machines and SDK versions — treat ratios as the reliable signal, absolute numbers as a snapshot of one machine on one day.

Tools

Development hooks

pre-commit install
pre-commit run --all-files

The hook set runs common file hygiene checks and dotnet format.

Sample CLI

dotnet run --project samples/ModernLrc.Samples.Console -- parse path/to/song.lrc
dotnet run --project samples/ModernLrc.Samples.Console -- shift path/to/song.lrc 500

Benchmarks

dotnet run -c Release --project bench/ModernLrc.Benchmarks -- --filter '*'

Uses BenchmarkDotNet. Filter to a benchmark group with e.g. --filter ParseBenchmarks*.

License

MIT — see LICENSE.