Class LrcDocumentBuilder

Namespace

ModernLrc

Assembly

ModernLrc.dll

Mutable builder for LrcDocument. Maintains insertion order; Build() sorts and freezes. Single-threaded contract — concurrent use from multiple threads is undefined (mirrors StringBuilder).

public sealed class LrcDocumentBuilder

Inheritance

object

LrcDocumentBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using ModernLrc;
using ModernLrc.Model;

var doc = new LrcDocumentBuilder()
    .WithTitle("Song")
    .WithArtist("Artist")
    .WithOffset(TimeSpan.FromMilliseconds(-150))
    .AddLine("00:01.00", "intro")
    .AddLine("00:05.00", "she sings", LrcVoice.Female)
    .AddEnhancedLine(
        LrcTimestamp.FromMilliseconds(10_000),
        [(LrcTimestamp.FromMilliseconds(10_000), "word "),
         (LrcTimestamp.FromMilliseconds(10_500), "by word")])
    .Build();

Remarks

Build() is idempotent: it does not mutate the builder, so the same builder instance can keep adding lines and produce updated documents.

Constructors

LrcDocumentBuilder()

Empty builder.

public LrcDocumentBuilder()

LrcDocumentBuilder(LrcDocument)

Seed from an existing document (shallow copy — records are immutable so sharing is safe).

public LrcDocumentBuilder(LrcDocument source)

Parameters

source LrcDocument

Properties

LineCount

Number of lines currently held (in insertion order).

public int LineCount { get; }

Property Value

int

Methods

AddEnhancedLine(LrcTimestamp, IEnumerable<(LrcTimestamp Time, string Text)>, LrcVoice)

Add an enhanced (word-timed) line from a tuple sequence.

public LrcDocumentBuilder AddEnhancedLine(LrcTimestamp lineTimestamp, IEnumerable<(LrcTimestamp Time, string Text)> words, LrcVoice voice = LrcVoice.Default)

Parameters

lineTimestamp LrcTimestamp

words IEnumerable<(LrcTimestamp Time, string Text)>

voice LrcVoice

Returns

LrcDocumentBuilder

AddEnhancedLine(LrcTimestamp, ReadOnlySpan<LrcWord>, LrcVoice)

Add an enhanced (word-timed) line at a single timestamp.

public LrcDocumentBuilder AddEnhancedLine(LrcTimestamp lineTimestamp, ReadOnlySpan<LrcWord> words, LrcVoice voice = LrcVoice.Default)

Parameters

lineTimestamp LrcTimestamp

words ReadOnlySpan<LrcWord>

voice LrcVoice

Returns

LrcDocumentBuilder

AddEnhancedLineGroup(ReadOnlySpan<LrcTimestamp>, ReadOnlySpan<LrcWord>, LrcVoice)

Add the same enhanced line content at multiple top-level timestamps. Each timestamp produces its own LrcEnhancedLine sharing the same words.

public LrcDocumentBuilder AddEnhancedLineGroup(ReadOnlySpan<LrcTimestamp> lineTimestamps, ReadOnlySpan<LrcWord> words, LrcVoice voice = LrcVoice.Default)

Parameters

lineTimestamps ReadOnlySpan<LrcTimestamp>

words ReadOnlySpan<LrcWord>

voice LrcVoice

Returns

LrcDocumentBuilder

AddLine(LrcLine)

Append a fully-constructed LrcLine (reference held; records are immutable).

public LrcDocumentBuilder AddLine(LrcLine line)

Parameters

line LrcLine

Returns

LrcDocumentBuilder

AddLine(LrcTimestamp, string, LrcVoice)

Add a plain line at timestamp.

public LrcDocumentBuilder AddLine(LrcTimestamp timestamp, string text, LrcVoice voice = LrcVoice.Default)

Parameters

timestamp LrcTimestamp

text string

voice LrcVoice

Returns

LrcDocumentBuilder

AddLine(string, string, LrcVoice)

Add a plain line whose timestamp is parsed from timestamp.

public LrcDocumentBuilder AddLine(string timestamp, string text, LrcVoice voice = LrcVoice.Default)

Parameters

timestamp string

text string

voice LrcVoice

Returns

LrcDocumentBuilder

AddLine(TimeSpan, string, LrcVoice)

Add a plain line at timestamp (TimeSpan overload).

public LrcDocumentBuilder AddLine(TimeSpan timestamp, string text, LrcVoice voice = LrcVoice.Default)

Parameters

timestamp TimeSpan

text string

voice LrcVoice

Returns

LrcDocumentBuilder

AddLineGroup(ReadOnlySpan<LrcTimestamp>, string, LrcVoice)

Add the same plain text at multiple timestamps. Each timestamp produces its own LrcPlainLine sharing the same text reference. The writer's CollapseIdenticalLines setting controls whether they re-emit as a [t1][t2]text group.

public LrcDocumentBuilder AddLineGroup(ReadOnlySpan<LrcTimestamp> timestamps, string text, LrcVoice voice = LrcVoice.Default)

Parameters

timestamps ReadOnlySpan<LrcTimestamp>

text string

voice LrcVoice

Returns

LrcDocumentBuilder

AddLines(IEnumerable<LrcLine>)

Append every line from a sequence.

public LrcDocumentBuilder AddLines(IEnumerable<LrcLine> lines)

Parameters

lines IEnumerable<LrcLine>

Returns

LrcDocumentBuilder

Build()

Materialize an immutable LrcDocument. Sorts by timestamp (stable: ties resolved by insertion order). Idempotent — does not mutate the builder.

public LrcDocument Build()

Returns

LrcDocument

A fresh immutable document. Calling Build() again after further fluent calls produces an updated document; the builder stays usable.

Remarks

The sort takes a fast O(N) path when lines were added in ascending timestamp order (the common case); otherwise an indexed stable sort is used.

Clear()

Drop both lines and metadata.

public LrcDocumentBuilder Clear()

Returns

LrcDocumentBuilder

ClearLines()

Drop all lines (metadata kept).

public LrcDocumentBuilder ClearLines()

Returns

LrcDocumentBuilder

ClearMetadata()

Drop all metadata (lines kept).

public LrcDocumentBuilder ClearMetadata()

Returns

LrcDocumentBuilder

GetLineAt(int)

Get a line in insertion order. Use Build() to retrieve sorted output.

public LrcLine GetLineAt(int index)

Parameters

index int

Returns

LrcLine

RemoveLineAt(int)

Remove the line at index (insertion order).

public LrcDocumentBuilder RemoveLineAt(int index)

Parameters

index int

Returns

LrcDocumentBuilder

RemoveLinesWhere(Func<LrcLine, bool>)

Remove every line for which predicate returns true.

public LrcDocumentBuilder RemoveLinesWhere(Func<LrcLine, bool> predicate)

Parameters

predicate Func<LrcLine, bool>

Returns

LrcDocumentBuilder

RemoveRawTag(string)

Remove every raw tag whose key matches (ordinal).

public LrcDocumentBuilder RemoveRawTag(string key)

Parameters

key string

Returns

LrcDocumentBuilder

ReplaceLine(int, LrcLine)

Replace the line at index (insertion order).

public LrcDocumentBuilder ReplaceLine(int index, LrcLine replacement)

Parameters

index int

replacement LrcLine

Returns

LrcDocumentBuilder

ShiftAll(TimeSpan)

Add delta to every line and word timestamp. Validates upfront — if any resulting timestamp would be negative, throws ArgumentOutOfRangeException and the builder is unchanged. To shift past zero, edit Offset instead.

public LrcDocumentBuilder ShiftAll(TimeSpan delta)

Parameters

delta TimeSpan

Positive or negative offset.

Returns

LrcDocumentBuilder

The builder, for chaining.

Exceptions

ArgumentOutOfRangeException

A resulting timestamp would be negative, or the addition overflowed.

WithAlbum(string?)

Set or clear the album (al).

public LrcDocumentBuilder WithAlbum(string? value)

Parameters

value string

Returns

LrcDocumentBuilder

WithArtist(string?)

Set or clear the artist (ar).

public LrcDocumentBuilder WithArtist(string? value)

Parameters

value string

Returns

LrcDocumentBuilder

WithAuthor(string?)

Set or clear the author (au).

public LrcDocumentBuilder WithAuthor(string? value)

Parameters

value string

Returns

LrcDocumentBuilder

WithCreatedBy(string?)

Set or clear the created-by attribution (by).

public LrcDocumentBuilder WithCreatedBy(string? value)

Parameters

value string

Returns

LrcDocumentBuilder

WithLength(TimeSpan?)

Set or clear the track length (length:mm:ss).

public LrcDocumentBuilder WithLength(TimeSpan? value)

Parameters

value TimeSpan?

Returns

LrcDocumentBuilder

WithLyricist(string?)

Set or clear the lyricist (lr).

public LrcDocumentBuilder WithLyricist(string? value)

Parameters

value string

Returns

LrcDocumentBuilder

WithOffset(TimeSpan)

Set the document offset (offset:±N ms).

public LrcDocumentBuilder WithOffset(TimeSpan value)

Parameters

value TimeSpan

Returns

LrcDocumentBuilder

WithRawTag(string, string)

Append a raw tag entry (preserves insertion order). key must be non-empty (whitespace-only is rejected — it would round-trip to [ :value] which the parser cannot read back).

public LrcDocumentBuilder WithRawTag(string key, string value)

Parameters

key string

value string

Returns

LrcDocumentBuilder

WithTitle(string?)

Set or clear the title (ti).

public LrcDocumentBuilder WithTitle(string? value)

Parameters

value string

Returns

LrcDocumentBuilder

WithTool(string?)

Set or clear the tool (re / tool).

public LrcDocumentBuilder WithTool(string? value)

Parameters

value string

Returns

LrcDocumentBuilder

WithVersion(string?)

Set or clear the version (ve).

public LrcDocumentBuilder WithVersion(string? value)

Parameters

value string

Returns

LrcDocumentBuilder