autolrc-tools 0.2.0

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

AutoLRC

AutoLRC generates line-level .lrc and .srt files from an audio file and a reference lyrics .txt file. A .json report is optional and is only written when --json-report is passed. LRC metadata applies only to the generated .lrc; source .wav and .mp3 files are not modified.

Primary release fixture:

• audio: tests/fixtures/Major Revision.wav
• lyrics: tests/fixtures/Major Revision.txt

Setup

Create a virtual environment, make sure ffmpeg is on PATH, then install one dependency set.

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

# GPU
.venv/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cu128
.venv/bin/python -m pip install -e .[gpu,dev]

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

Check the runtime:

.venv/bin/autolrc doctor

Single File

Basic run:

.venv/bin/autolrc align --audio "tests/fixtures/Major Revision.wav" --lyrics "tests/fixtures/Major Revision.txt"

Useful options:

• --title, --artist, --lang: add [ti], [ar], and [la] tags to the generated .lrc
• --json-report: also write the sibling .json report
• --separator-boost: align on a separated vocal stem
• --save-vocals: keep the sibling .vocals.wav file

Examples:

.venv/bin/autolrc align --audio "tests/fixtures/Major Revision.wav" --lyrics "tests/fixtures/Major Revision.txt" --title "Major Revision" --artist "PiPi" --lang en
.venv/bin/autolrc align --audio "tests/fixtures/Major Revision.wav" --lyrics "tests/fixtures/Major Revision.txt" --json-report
.venv/bin/autolrc align --audio "tests/fixtures/Major Revision.wav" --lyrics "tests/fixtures/Major Revision.txt" --separator-boost --save-vocals

Defaults:

• engine: stable-ts
• model: medium
• device: auto
• separator: none
• outputs: sibling .lrc and .srt

If a stable-ts run finishes with average_confidence < 0.5, inspect the output first and consider rerunning with --separator-boost.

Batch Mode

If --audio points to a directory, AutoLRC switches into batch mode.

.venv/bin/autolrc align --audio tests/fixtures --engine baseline
.venv/bin/autolrc align --audio tests/fixtures --artist "PiPi" --json-report --engine baseline

Batch rules:

• search only the given directory, not subdirectories
• match same-stem .wav or .mp3 files with a sibling .txt
• prefer .wav when both .wav and .mp3 exist for one stem
• continue after per-track failures
• exit with code 1 if any matched track fails or if no valid pairs are found

Batch metadata:

• --title and --lang are rejected
• --artist is allowed
• when --artist is provided, each generated .lrc gets [ar:<artist>] and [ti:<file-stem>]
• when --artist is omitted, batch .lrc files stay metadata-free

Per-track outputs:

• default: song.lrc, song.srt
• with --json-report: also song.json
• with --save-vocals: also song.vocals.wav

Release Checks

Run these before publishing to PyPI:

.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check src tests
.venv/bin/python -m pre_commit run --all-files
.venv/bin/python -m build
.venv/bin/python -m twine check dist/*
.venv/bin/python -m autolrc benchmark --manifest bench/manifest.yaml