Metadata-Version: 2.4
Name: autolrc-tools
Version: 0.1.1
Summary: Generate line-level .lrc and .srt lyric files from audio and reference lyrics
Author: PiPi
License: MIT
License-File: LICENSE
Keywords: alignment,lrc,lyrics,srt,whisper
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.11
Requires-Dist: pyyaml<7.0.0,>=6.0.1
Requires-Dist: typer<1.0.0,>=0.12.3
Provides-Extra: cpu
Requires-Dist: audio-separator[cpu]>=0.26.0; extra == 'cpu'
Requires-Dist: rapidfuzz>=3.9.0; extra == 'cpu'
Requires-Dist: stable-ts>=2.17.0; extra == 'cpu'
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
Requires-Dist: pytest>=8.3.4; extra == 'dev'
Requires-Dist: ruff>=0.11.0; extra == 'dev'
Requires-Dist: twine>=6.1.0; extra == 'dev'
Provides-Extra: gpu
Requires-Dist: audio-separator[gpu]>=0.26.0; extra == 'gpu'
Requires-Dist: rapidfuzz>=3.9.0; extra == 'gpu'
Requires-Dist: stable-ts>=2.17.0; extra == 'gpu'
Description-Content-Type: text/markdown

# 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.

```bash
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:

```bash
.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:

```bash
.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:

```bash
.venv\Scripts\autolrc doctor
```

## Single-File Usage

```bash
.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:

```bash
.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.

```bash
.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:

```bash
.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:

```bash
.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:

```bash
.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

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