autolrc-tools 0.1.1__tar.gz

autolrc_tools-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Pre-commit
+        run: pre-commit run --all-files
+
+      - name: CLI smoke
+        run: |
+          autolrc --help
+          autolrc align --help
+          autolrc benchmark --manifest bench/manifest.yaml
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Test
+        run: python -m pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Build package
+        run: python -m build
+
+      - name: Twine check
+        run: python -m twine check dist/*

autolrc_tools-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+.autolrc-cache/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+*.egg-info/
+*.lrc
+tests/fixtures
+examples
+data/

autolrc_tools-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.4
+    hooks:
+      - id: ruff
+      - id: ruff-format

autolrc_tools-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PiPi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

autolrc_tools-0.1.1/PKG-INFO

@@ -0,0 +1,219 @@
+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/
+```

autolrc_tools-0.1.1/README.md

@@ -0,0 +1,183 @@
+# 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/
+```

autolrc_tools-0.1.1/bench/manifest.yaml

@@ -0,0 +1,9 @@
+tracks:
+  - track_id: major_revision
+    audio_path: tests/fixtures/Major Revision.wav
+    lyrics_path: tests/fixtures/Major Revision.txt
+    languages: [en]
+    is_mixed_language: false
+    has_long_intro: true
+    has_repeated_chorus: true
+    notes: Primary English release fixture for benchmark and smoke validation.

autolrc_tools-0.1.1/docs/architecture.md

@@ -0,0 +1,107 @@
+# Architecture
+
+AutoLRC is split into a few small layers so the CLI can stay simple while the alignment and
+separation backends evolve. The current benchmark manifest and release smoke workflow are
+centered on `tests/fixtures/Major Revision.wav` plus `tests/fixtures/Major Revision.txt`.
+
+## Main Modules
+
+- `cli.py`: public command surface, single-file mode, batch directory mode, benchmark
+  summary, and doctor output
+- `pipeline.py`: orchestration for one alignment run plus batch discovery and execution
+- `aligner.py`: lyric preprocessing, language resolution, runtime checks, and alignment
+  backends
+- `separator.py`: passthrough separation, `audio-separator` integration, and separator
+  runtime diagnostics
+- `repair.py`: post-alignment repair hook
+- `lrc.py`: `.lrc` rendering
+- `srt.py`: `.srt` rendering
+- `models.py`: shared dataclasses for lyrics, alignments, and batch results
+
+## Single-File Flow
+
+1. `cli.align` validates the file-oriented flags and builds an `AlignRequest`.
+2. `AutoLRCService.align` normalizes paths, derives sibling output locations, and creates a
+   per-run work directory under `.autolrc-cache`.
+3. `LyricsNormalizer.read` loads the raw `.txt`, strips bracketed notes and emoji, collapses
+   whitespace, drops empty lines, and keeps the cleaned line order as canonical.
+4. `get_separator(...)` resolves the requested separation backend.
+5. `get_aligner(...)` resolves the requested alignment backend.
+6. The aligner returns `LineAlignment` objects, which are rendered into `.lrc`, `.srt`, and a
+   `.json` report.
+
+The default path is `stable-ts` with model `medium`, device `auto`, and separator `none`.
+
+## Batch Directory Flow
+
+Batch mode is a CLI orchestration layer over repeated single-track runs, not a separate
+alignment backend.
+
+1. `cli.align` switches into batch mode when `--audio` points to a directory.
+2. Batch mode rejects flags that do not scale cleanly across multiple tracks:
+   `--lyrics`, `--output`, `--json-report`, `--title`, `--artist`, and `--lang`.
+3. `AutoLRCService.batch_align` scans only the given directory for same-stem `.wav` or `.mp3`
+   files with a sibling `.txt`.
+4. If both `.wav` and `.mp3` exist for one stem, `.wav` is selected and `.mp3` is recorded as
+   skipped.
+5. Each discovered pair is turned into a normal `AlignRequest` and processed through the
+   single-file pipeline.
+6. Failures are collected per track, later tracks still run, and the CLI prints a final
+   summary of matched, succeeded, low-confidence, failed, and skipped entries.
+
+## Language Resolution
+
+`stable-ts` alignment resolves language in this order:
+
+1. explicit `--lang`
+2. lyric-script inference from the cleaned text
+3. multi-window audio vote using `ffprobe` plus `stable-ts` transcription samples
+4. fail with an actionable message if the vote is inconclusive
+
+The current script inference is intentionally opinionated for common CJK workflows:
+
+- Kana presence resolves to `ja`
+- Hangul-majority text resolves to `ko`
+- Han-majority text without Kana or Hangul resolves to `zh`
+
+Latin-script lyrics do not force `en`; they fall through to the audio vote. The current
+primary fixture resolves to `en` via the audio-vote path on a healthy runtime.
+
+## Separation and Boost Mode
+
+`separator.py` currently exposes two modes:
+
+- `none`: passthrough, align directly on the original mix
+- `audio-separator`: generate a vocal stem before alignment
+
+`--separator-boost` is a convenience flag that selects `audio-separator`. If `--save-vocals`
+is also enabled, the separated vocal stem is copied or converted into a sibling
+`<stem>.vocals.wav`.
+
+AutoLRC does not automatically retry low-confidence runs. Instead, the report includes
+`low_confidence`, `low_confidence_threshold`, and `recommended_action`, and the CLI suggests a
+manual `--separator-boost` rerun when the average confidence is below `0.5` and the run did
+not already use real separation.
+
+## Runtime and Release Diagnostics
+
+`doctor` combines:
+
+- `aligner.py` runtime checks for `ffmpeg`, `stable-ts`, `torch`, and CUDA
+- `separator.py` importability checks for `audio-separator`
+
+The separator check goes beyond `find_spec`: it attempts to import the runtime entry point so
+environments that still miss `onnxruntime`, `onnxruntime-gpu`, or other transitive pieces are
+reported as broken instead of merely installed.
+
+That matters because extras changes in `pyproject.toml` do not retrofit existing virtual
+environments. After pulling dependency changes, users may need to refresh the environment with
+`python -m pip install -e .[gpu,dev]` or `python -m pip install -e .[cpu,dev]`.
+
+The manual release-prep loop is:
+
+1. run lint, tests, and pre-commit
+2. build wheel and sdist
+3. run `twine check dist/*`
+4. run `autolrc benchmark --manifest bench/manifest.yaml`
+5. run a real alignment smoke test against `tests/fixtures/Major Revision.*`