autolrc-tools 0.3.1

Generate line-level .lrc and .srt 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

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

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