autolrc-tools 0.2.1

Generate line-level .lrc and .srt lyric files from audio and reference lyrics

AutoLRC

Generates line-level .lrc and .srt files from an audio file and a reference lyrics .txt. Source audio is never modified.

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

Outputs song.lrc and song.srt alongside the audio file.

Key options:

Option	Effect
--title, --artist	Write [ti], [ar] tags to the LRC
--lang <code>	Override language (default: auto-detected)
--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"

# 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/ --artist "Artist" --json-report

Rules:

• Scans the given directory only (not recursive)
• Matches same-stem .wav/.mp3 with a sibling .txt; prefers .wav when both exist
• Continues on per-track failures; exits with code 1 if any track fails
• --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, 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