autolrc-tools 0.1.1

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

AutoLRC

AutoLRC generates line-level .lrc and .srt lyric files from an audio file and a reference lyrics text file. The default path uses stable-ts, writes a sibling .json report, and preserves the cleaned lyric line order from the input text file.

The primary release fixture pair is:

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

Current Scope

• autolrc align supports single-file alignment and same-directory batch alignment
• autolrc inspect shows cleaned lyric lines before alignment
• autolrc benchmark validates the benchmark manifest and prints a summary
• autolrc doctor reports ffmpeg, stable-ts, torch, CUDA, and optional dependency health
• autolrc cache clear removes local working files

The baseline aligner still exists as an explicit debug fallback with --engine baseline.

Runtime Setup

Recreate the local virtual environment before using the ML-backed path.

py -3.12 -m venv .venv
.venv\Scripts\python -m pip install --upgrade pip

Install ffmpeg so it is available on PATH, then install PyTorch before AutoLRC.

GPU-first setup:

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

CPU fallback:

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

Use autolrc doctor before a long run:

.venv\Scripts\autolrc doctor

Single-File Usage

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

Default behavior:

• engine: stable-ts
• model: medium
• device: auto (cuda first, cpu fallback)
• separator: none
• outputs: sibling .lrc, .srt, and .json files using the audio stem
• lyric preprocessing: trim lines, remove (), {}, and [] spans, strip emoji, and drop empty lines
• language resolution order: explicit --lang, lyric-script inference, then multi-window audio vote

Useful overrides:

.venv\Scripts\autolrc align --audio "tests/fixtures/Major Revision.wav" --lyrics "tests/fixtures/Major Revision.txt" --device cpu
.venv\Scripts\autolrc align --audio "tests/fixtures/Major Revision.wav" --lyrics "tests/fixtures/Major Revision.txt" --engine baseline
.venv\Scripts\autolrc align --audio "tests/fixtures/Major Revision.wav" --lyrics "tests/fixtures/Major Revision.txt" --separator-boost --save-vocals

When a stable-ts run finishes with average_confidence < 0.5, AutoLRC does not retry automatically. It tells you to inspect the generated files first and suggests --separator-boost as a manual follow-up when appropriate.

Batch Directory Mode

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

.venv\Scripts\autolrc align --audio tests/fixtures --engine baseline

Batch mode rules:

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

Batch mode forbids per-track flags that do not scale cleanly:

• --lyrics
• --output
• --json-report
• --title
• --artist
• --lang

Allowed batch-wide flags include --engine, --model, --device, --separator, --separator-boost, --save-vocals, and --keep-temp.

Per-track outputs still use the audio stem in the same directory:

• song.wav + song.txt -> song.lrc, song.srt, song.json
• song.wav + song.txt + --save-vocals -> also song.vocals.wav

The batch summary reports:

• matched tracks
• succeeded tracks
• low-confidence tracks
• failed tracks
• skipped files

Benchmark Fixture

bench/manifest.yaml currently points to the Major Revision release fixture:

.venv\Scripts\autolrc benchmark --manifest bench/manifest.yaml

Separator Troubleshooting

--separator-boost enables the audio-separator backend and aligns against the separated vocal stem. This can improve difficult tracks, but it uses more time, memory, and disk than the default path.

If audio-separator shows up as installed but not runnable, the most common cause is an older virtual environment that predates the current extras definition. Changing pyproject.toml extras is normal packaging work, but existing environments do not automatically gain those new optional dependencies.

After pulling this repo update, refresh the environment:

.venv\Scripts\python -m pip install -e .[gpu,dev]
.venv\Scripts\python -m pip install -e .[cpu,dev]

Use only one of those reinstall commands for the environment you want. The GPU command is for CUDA-capable machines; the CPU command is the fallback.

Release Checks

The manual release-prep flow is:

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

Repo Layout

src/autolrc/
  aligner.py
  cli.py
  lrc.py
  models.py
  pipeline.py
  repair.py
  separator.py
  srt.py
tests/
bench/
docs/