autolrc-tools 0.3.2

Generate aligned .lrc and .srt (and other) lyric files from audio and reference lyrics

AutoLRC

Generates line-level .lrc, .srt, and .vtt files from an audio file and a reference lyrics .txt.

Setup

Requires Python 3.12 and ffmpeg on PATH.

python3.12 -m venv .venv
. .venv/bin/activate
pip install --upgrade pip

# GPU (CUDA 12.8)
pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install -e .[gpu,dev]

# CPU
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -e .[cpu,dev]

Verify the install:

autolrc doctor

Single File

autolrc align --audio song.wav --lyrics song.txt

Accepts .wav, .flac, or .mp3. Outputs song.lrc, song.srt, and song.vtt alongside the audio.

Key options:

Option	Effect
--title, --artist	Write [ti], [ar] tags to the LRC
--lang <code>	Override language (default: auto-detected)
--enhanced-lrc	Karaoke-style LRC with inline word-level timestamps
--skip-existing	Skip the run if song.lrc already exists
--separator-boost	Separate vocals before aligning (improves noisy tracks)
--save-vocals	Keep the separated stem as song.vocals.wav
--json-report	Write a song.json quality report
--model	Whisper model size: base, small, medium (default), large-v3
--device	auto (default), cuda, or cpu
--to-flac, --to-alac	Also write a lossless sibling (song.flac / song.m4a) — ~50% the size of WAV
--to-aac, --to-mp3	Also write a lossy sibling (song.aac @ 256k / song.mp3 @ V0)

The [la] tag is written automatically from the detected language; --lang overrides it.

If alignment finishes with average_confidence < 0.5, inspect the output and consider rerunning with --separator-boost.

Examples:

# With metadata tags
autolrc align --audio song.wav --lyrics song.txt --title "Song Name" --artist "Artist"

# Karaoke-style LRC with word timestamps
autolrc align --audio song.wav --lyrics song.txt --enhanced-lrc

# With vocal separation and quality report
autolrc align --audio song.wav --lyrics song.txt --separator-boost --save-vocals --json-report

# Also emit a lossless FLAC sibling (and an MP3) next to the WAV
autolrc align --audio song.wav --lyrics song.txt --to-flac --to-mp3

The --to-* flags work in batch mode too. They are rejected when the source audio is .mp3 (lossy → lossless re-encoding adds no value). When the source already matches the target format (e.g. song.flac --to-flac), that conversion is skipped to avoid overwriting the source.

Batch Mode

Pass a directory to --audio to process all matching pairs at once:

autolrc align --audio ./my-songs/
autolrc align --audio ./my-songs/ --recursive --skip-existing
autolrc align --audio ./my-songs/ --artist "Artist" --enhanced-lrc --json-report

Rules:

• Matches same-stem .wav/.flac/.mp3 files with a sibling .txt; priority is .wav > .flac > .mp3
• Non-recursive by default; use --recursive to walk subdirectories
• Continues on per-track failures; exits with code 1 if any track fails
• --skip-existing skips tracks whose .lrc already exists
• --title and --lang are rejected; --artist is allowed
• When --artist is given, each LRC gets [ar:<artist>] and [ti:<file-stem>]

Per-track outputs: song.lrc, song.srt, song.vtt, and optionally song.json, song.vocals.wav

Other Commands

autolrc inspect --lyrics song.txt   # Preview normalized lyric lines
autolrc doctor                      # Show runtime diagnostics
autolrc cache clear                 # Remove the local cache directory