py-roller 0.4.0__py3-none-any.whl

py_roller-0.4.0.dist-info/METADATA

@@ -0,0 +1,472 @@
+Metadata-Version: 2.4
+Name: py-roller
+Version: 0.4.0
+Summary: Composable lyric-audio alignment pipeline with staged execution, batch processing, and LRC/ASS export.
+Author: OpenAI scaffolding for David Peterson
+License: MIT
+Keywords: lyrics,subtitle,karaoke,alignment,audio,lrc,ass,cli,batch,transcription
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pypinyin>=0.50.0
+Requires-Dist: opencc-python-reimplemented>=0.1.7
+Requires-Dist: pronouncing>=0.2.0
+Requires-Dist: phonemizer>=3.3.0
+Requires-Dist: gruut[ar,ru]>=2.4.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.66.0
+Provides-Extra: audio
+Requires-Dist: demucs>=4.0.1; extra == "audio"
+Requires-Dist: whisperx>=3.1.1; extra == "audio"
+Requires-Dist: torch>=2.2.0; extra == "audio"
+Requires-Dist: librosa>=0.10.0; extra == "audio"
+Requires-Dist: transformers>=4.39.0; extra == "audio"
+Requires-Dist: numpy>=1.24.0; extra == "audio"
+Requires-Dist: soundfile>=0.12.1; extra == "audio"
+Requires-Dist: scipy>=1.10.0; extra == "audio"
+Requires-Dist: bottleneck>=1.3.8; extra == "audio"
+Requires-Dist: nara_wpe>=0.0.11; extra == "audio"
+
+# py-roller
+
+`py-roller` is a CLI Solution for automatic rolling lyrics generating.
+
+To be specific, `py-roller` is a composable lyric-audio alignment pipeline CLI for staged execution, batch processing, and LRC/ASS export. Designed to support multiple transcriber back-ends including WhisperX and wav2vec2.
+
+- Package name: `py-roller`
+- CLI command: `py-roller`
+- Python import package: `pyroller`
+
+## Quick overview
+
+`py-roller` treats alignment as a contiguous stage chain:
+
+```text
+s -> f -> t -> p -> a -> w
+splitter -> filter -> transcriber -> parser -> aligner -> writer
+```
+
+Core modes:
+
+- `run`: execute one contiguous stage chain for one task
+- `batch`: execute the same contiguous stage chain across many tasks
+
+Core artifact types:
+
+- input audio / lyrics
+- intermediate vocal and filtered audio
+- `timed_units`
+- `parsed_lyrics`
+- `alignment_result`
+- written outputs such as LRC or ASS
+
+## Installation
+
+From source:
+
+```bash
+pip install .
+```
+
+With audio backends and heavy model dependencies:
+
+```bash
+pip install .[audio]
+```
+
+After installation, the CLI command is:
+
+```bash
+py-roller
+```
+
+## Quick start
+
+### Full pipeline: audio + lyrics -> LRC
+
+```bash
+py-roller run \
+  --stages s,f,t,p,a,w \
+  --audio ./song.mp3 \
+  --lyrics ./song.txt \
+  --filter-chain noise_gate,dereverb \
+  --output-written ./song.lrc
+  --language zh # Choose as you like
+```
+
+### Start from a prepared vocal track
+
+```bash
+py-roller run \
+  --stages t,p,a,w \
+  --audio ./vocals.wav \
+  --lyrics ./song.txt \
+  --writer-backend ass_karaoke \
+  --output-written ./song.ass
+  --language zh # Choose as you like
+```
+
+### Batch processing by stem
+
+```bash
+py-roller batch \
+  --stages t,p,a,w \
+  --audio ./audio_dir \
+  --lyrics ./lyrics_dir \
+  --output-written ./out_dir
+  --language zh # Choose as you like
+```
+
+## Core execution model
+
+### Contiguous stage chains only
+
+The CLI only accepts contiguous subchains of the canonical order.
+
+Valid examples:
+
+- `s,f,t,p,a,w`
+- `t,p,a,w`
+- `a,w`
+- `w`
+
+Invalid examples:
+
+- `s,t,w`
+- `s,p,a`
+
+### Legal chain starts
+
+Explicit artifact inputs are only valid at the correct chain start:
+
+- `--audio` is valid when the chain starts at `s`, `f`, or `t`
+- `--lyrics` is valid when the chain includes `p`
+- `--timed-units` and `--parsed-lyrics` are only valid when the chain starts at `a`
+- `--alignment-result` is only valid when the chain starts at `w`
+
+### Final outputs vs intermediate artifacts
+
+Final user-requested outputs are only the explicit `--output-*` paths:
+
+- `--output-vocal-audio`
+- `--output-filtered-audio`
+- `--output-timed-units`
+- `--output-parsed-lyrics`
+- `--output-alignment-result`
+- `--output-written`
+
+Everything else created under `--intermediate` is treated as intermediate state.
+
+## Common workflows
+
+### Start from raw audio
+
+Use the full chain when you want splitting, filtering, transcription, alignment, and final writing in one command.
+
+```bash
+py-roller run \
+  --stages s,f,t,p,a,w \
+  --audio ./song.mp3 \
+  --lyrics ./song.txt \
+  --output-written ./song.lrc
+```
+
+### Start from filtered or vocal audio
+
+Skip splitter/filter when you already have a suitable track for transcription.
+
+```bash
+py-roller run \
+  --stages t,p,a,w \
+  --audio ./vocals.wav \
+  --lyrics ./song.txt \
+  --output-written ./song.lrc
+```
+
+### Start from aligner artifacts
+
+```bash
+py-roller run \
+  --stages a,w \
+  --timed-units ./song.timed_units.json \
+  --parsed-lyrics ./song.parsed_lyrics.json \
+  --output-written ./song.lrc
+```
+
+### Rewrite only from an existing alignment result
+
+```bash
+py-roller run \
+  --stages w \
+  --alignment-result ./song.alignment.json \
+  --writer-backend ass_karaoke \
+  --output-written ./song.ass
+```
+
+## Backend defaults
+
+Default backend selection is language-aware. Please note that the default selection of language is "mul" which works poorly when tested on both Chinese and English, please use the `--language` flag to specify the desired language if the language is directly supported.
+
+### Transcriber defaults
+
+- `zh` -> `mms_phonetic`
+- `en` -> `whisperx`
+- `mul` -> `wav2vec2_phoneme`
+
+### Parser defaults
+
+- `zh` -> `zh_router_pinyin`
+- `en` -> `en_arpabet`
+- `mul` -> `mul_ipa`
+
+### Other defaults
+
+- aligner backend -> `global_dp_v1`
+- writer backend -> `lrc_ms`
+- language -> `mul`
+- `reserve_spacing` -> enabled
+- `cleanup` -> `on-success`
+
+## Writer behavior
+
+### LRC
+
+The default writer is `lrc_ms` which writes LRC lines with millisecond precision. Other supported writer backends are:
+
+- `lrc_cs`: writes LRC lines with centiscond precision
+- `lrc_compressed`: writes LRC lines with millisecond precision, but compresses consecutive lines with the same timestamp
+- `ass_karaoke`: see below
+
+### ASS karaoke
+
+`ass_karaoke` writes ASS dialogue lines with karaoke timing tags.
+
+Current defaults:
+
+- structural / spacing lines are skipped by default
+- display end time prefers matched unit timing instead of blindly extending to the next line
+- unmatched lines receive a short visible duration fallback
+
+Example:
+
+```bash
+py-roller run \
+  --stages w \
+  --alignment-result ./song.alignment.json \
+  --writer-backend ass_karaoke \
+  --output-written ./song.ass
+```
+
+## Progress reporting
+
+The project exposes a reusable progress-reporting interface so CLI and future GUI frontends can share the same stage updates.
+
+Current behavior:
+
+- splitter: Demucs progress plus wrapper stage progress
+- filter: phase progress
+- transcriber: phase progress
+- aligner: phase progress plus DP row progress
+
+In single-task `run`, progress is shown as CLI progress bars when the terminal supports it. In `batch`, per-task progress is logged to avoid multiple workers fighting for one terminal.
+
+## Intermediate files and cleanup
+
+Intermediate files live under:
+
+```text
+--intermediate/<task-id>/splitter
+--intermediate/<task-id>/filter
+--intermediate/<task-id>/logs
+```
+
+Default intermediate root:
+
+```text
+<system temp>/py-roller-artifacts
+```
+
+Cleanup policy:
+
+- `--cleanup on-success` keeps successful runs tidy by removing per-task intermediate directories
+- `--cleanup never` keeps intermediate audio and logs for inspection
+
+## Batch mode
+
+`batch` uses the same stage semantics as `run`, but applies them to many tasks.
+
+### Directory pairing
+
+Directory mode currently supports:
+
+```text
+--pair-by stem
+```
+
+Default candidate globs:
+
+- `--audio-glob "*.mp3"`
+- `--lyrics-glob "*.txt"`
+
+Matching is non-recursive.
+
+Example:
+
+```bash
+py-roller batch \
+  --stages t,p,a,w \
+  --audio ./audio_dir \
+  --lyrics ./lyrics_dir \
+  --output-written ./out_dir
+```
+
+### Batch controls
+
+- `--jobs N`: maximum number of parallel workers
+- `--continue-on-error`: keep processing remaining tasks after failures
+- `--skip-existing`: skip tasks whose declared final outputs already exist
+- `--manifest jobs.yaml`: load explicit per-task paths from YAML instead of pairing by stem
+
+### Parallelism guidance
+
+`--jobs` controls how many tasks run at the same time. This is separate from any model-level batch size.
+
+Recommended starting point:
+
+- CPU-only: `--jobs 1` or `--jobs 2`
+- single GPU: usually `--jobs 1`
+
+## YAML manifest format
+
+Manifest mode is useful when filenames do not match cleanly by stem.
+
+The manifest defines per-task input and output paths only. It does not override stage selection, language, backend choice, filter settings, jobs, or other batch-level options.
+
+Supported top-level forms:
+
+```yaml
+tasks:
+  - id: song01
+    audio: ./audio/song01_master.mp3
+    lyrics: ./lyrics/song01_final.txt
+    output_written: ./out/song01.lrc
+```
+
+or:
+
+```yaml
+- id: song01
+  audio: ./audio/song01_master.mp3
+  lyrics: ./lyrics/song01_final.txt
+  output_written: ./out/song01.lrc
+```
+
+Allowed manifest input keys:
+
+- `audio`
+- `lyrics`
+- `timed_units`
+- `parsed_lyrics`
+- `alignment_result`
+
+Allowed manifest output keys:
+
+- `output_vocal_audio`
+- `output_filtered_audio`
+- `output_timed_units`
+- `output_parsed_lyrics`
+- `output_alignment_result`
+- `output_written`
+
+Optional helper key:
+
+- `id`
+
+Validation rules:
+
+- each task must be a mapping
+- unknown keys are rejected
+- inputs must match the selected chain start
+- outputs must be valid final outputs for the selected chain
+- task ids / stems must be unique
+- final output paths must not conflict across tasks
+- relative paths are resolved relative to the manifest file location
+
+## YAML config for default CLI options
+
+Use `--config` to load YAML defaults.
+
+Priority order:
+
+```text
+built-in defaults < config YAML < explicit CLI arguments
+```
+
+Section model:
+
+- `shared`: defaults applied to both `run` and `batch`
+- `run`: currently no extra keys beyond `shared`
+- `batch`: defaults for batch-only options such as `jobs` and `skip_existing`
+
+Example:
+
+```yaml
+shared:
+  language: mul
+  reserve_spacing: true
+  writer_backend: lrc_ms
+  intermediate: ./tmp/py-roller-artifacts
+  cleanup: on-success
+  transcriber_device: cpu
+  splitter_demucs_model: htdemucs
+  filter_chain:
+    - noise_gate
+    - dereverb
+
+batch:
+  jobs: 2
+  audio_glob: "*.mp3"
+  lyrics_glob: "*.txt"
+  continue_on_error: true
+```
+
+`filter_chain` can be written either as a comma-separated string or as a YAML list.
+
+## Troubleshooting
+
+### Interruption and child process cleanup
+
+Batch fail-fast actively stops launching further work after the first task failure when `--continue-on-error` is not set, and worker cleanup includes a Windows-specific process-tree branch.
+
+For older runs or already orphaned processes, Linux/macOS cleanup examples are still useful:
+
+```bash
+pkill -TERM -f 'python .*pyroller'
+pkill -TERM -f 'demucs.separate|demucs'
+```
+
+If anything still survives:
+
+```bash
+pkill -KILL -f 'python .*pyroller'
+pkill -KILL -f 'demucs.separate|demucs'
+```
+
+Inspect candidates first with:
+
+```bash
+ps -ef | grep -E 'pyroller|demucs'
+```

py_roller-0.4.0.dist-info/RECORD

@@ -0,0 +1,56 @@
+pyroller/__init__.py,sha256=64K32e0xATU23z-GeH9rS9ddPNCMeQkDCaCwcY3DId4,48
+pyroller/batch.py,sha256=DEsSE1ey2mT3XaG4v0imxPUD2B6CHvG3u-jFMEQXumo,20757
+pyroller/logging_utils.py,sha256=00gnuiPy4D5uJZfc-nSZvAhuWQaWXY5N5EqI2osOyEA,1421
+pyroller/process_control.py,sha256=Q2Bq8_d_MhIlThW0GVaJsxu753gH_OZ1byjLF1PnSzY,2850
+pyroller/progress.py,sha256=x5mfdu-vwjcFQB-23V9unGbF6ZM0NBgFDgI26efesKg,3841
+pyroller/aligner/__init__.py,sha256=FSVjun6xZ3Slbo9ng-yL7U9IKMoFVu1DJvmodxZ3nGE,250
+pyroller/aligner/base.py,sha256=dhzbgfvfzgtgR9iTsFEt1a6tqdDS3MGRvia0fCXEluc,525
+pyroller/aligner/common.py,sha256=WDyVfnFbVYTIRhtWNyR31g6sGA1J9-0HOrPYluMrM7Q,19779
+pyroller/aligner/global_dp_v1.py,sha256=tw0pHTL8MnQRyOKjZ22h8vazRHt8MOInf023YTOC_Cs,19484
+pyroller/aligner/registry.py,sha256=VPEBA3fDqMisep76imvkt5RDVTNOmbnZXJ4v9v5VKeQ,1177
+pyroller/cli/__init__.py,sha256=juqd9PbXs4yg45zMJ7BHAOPQjb7sgEbWE9InBtGZhfo,24
+pyroller/cli/__main__.py,sha256=Vdhw8YA1K3wPMlbJQYL5WqvRzAKVeZ16mZQFO9VRmCo,62
+pyroller/cli/config.py,sha256=PPZQ7r-3ghdmnI8YxzR-QbtTBAqvev0gWQ50J650S60,4654
+pyroller/cli/main.py,sha256=elY1zb_K7I-XnlaSizBcbhowf0h0yAJiT4myygCKey0,20088
+pyroller/domain/__init__.py,sha256=Rj6FczbbzQEja5sVHFC1veL8MUDr0cMYfYFwI1iA_5I,625
+pyroller/domain/models.py,sha256=CMTcrosugCoCjiY37LmUR_vXWMDd1ZIgE2MwVXmC5rQ,11460
+pyroller/filter/__init__.py,sha256=iD6kpwk8uYpx8ICkJ0RQI31nScLMHOo3VCJmCRsiTK0,468
+pyroller/filter/base.py,sha256=BvF4fGoY8ItU57QDulQEsJsxxbDTBmFjZyFtQl8h2qs,437
+pyroller/filter/chain.py,sha256=grGLtOj64YprNY8aEkE5nHNSy2ZqXf41GpAnCEhDQ8A,2664
+pyroller/filter/dereverb_nara_wpe.py,sha256=yw69rNBPt1d4H1FRnnLHoSKWg3DAganbQHP5fP4zdak,6337
+pyroller/filter/noise_gate.py,sha256=WxDMXt52jM9b3DC8fObioskXjlZFWfeD-uJ8r3J9vkQ,6277
+pyroller/filter/registry.py,sha256=a9OzjfgQtZbT5oRddUqNoTIeZZsX6CCLOsIZS0PtftY,1607
+pyroller/parser/__init__.py,sha256=Gb7DuzGDhHw0G_MU1WXNH_qeUCxFyYB28aOn7qgBR4Q,495
+pyroller/parser/base.py,sha256=SRE0488whfClcEb0CgICPGiXpt_ZYeC2TtDYdGn7NgY,395
+pyroller/parser/en_arpabet.py,sha256=4GaDEUfJOBmcIFyRLHeuIapza3ojCuGd1Zvu4ynoY7U,2395
+pyroller/parser/mul_ipa.py,sha256=n8Jkqo8oA0IPz66qM-xpLhDJATEsQseSBI7dTd4zfaM,4083
+pyroller/parser/registry.py,sha256=jLuU0TlRDWDo3LRjPbciOBK_6dYXodXfezwrWRFkLpI,2408
+pyroller/parser/zh_pinyin.py,sha256=3nPcHEkz5d-qgFcyw8k1p9UcGrkXf8JUtjNxWBwpQu4,2373
+pyroller/parser/zh_router_pinyin.py,sha256=F0i1uPY2_kpZJ1s6R7dRvGEHrw20R9FLR5hT2iLQeJw,5102
+pyroller/pipeline/__init__.py,sha256=srlFTEmAMjemWzNBF-izsChRjEfafq2T6DmLng4HmIw,85
+pyroller/pipeline/runner.py,sha256=EhHMcq3n9qcXisG1KEVYAjSzG4b6OSvHDlwbT8Jhox4,31704
+pyroller/splitter/__init__.py,sha256=ZaGX8V-WAzK4uMtoRSXuXDqbQ5DPQ16xbQQgFGhJWNg,104
+pyroller/splitter/base.py,sha256=fe-xvficdywlu73o1HR8nCa_s-Tv-RKIZOrQCa28O1E,445
+pyroller/splitter/demucs.py,sha256=sTIIIs39y3q1dqO2BYfBSPNl4Uu5EtKz4PdDQrQCtsw,2059
+pyroller/transcriber/__init__.py,sha256=woIGykFLxMyiXHGo028o_KdAlbKZEtx5BGiM_ejIXNM,578
+pyroller/transcriber/base.py,sha256=6gEiGLW5My2OzgLiF90Ckr-m3CivzDgY60y5c-sCnzI,540
+pyroller/transcriber/en_whisperx.py,sha256=RAylTY4dgIncpVwsBof3tvLwhh_jfpjpSIWTQrv4uGI,8048
+pyroller/transcriber/mms_phonetic.py,sha256=qZCbOs8VrLe64nOxkRxB9f88Jg2keTbuFDjF0eVXJes,15120
+pyroller/transcriber/mul_wav2vec2_phoneme.py,sha256=sacRB5KLojsu1bgOf4VsdXONkDD6F7Mce3ZbfcuB32g,12826
+pyroller/transcriber/registry.py,sha256=tcW6hHBkMCAA4qEz2yo-GirQTW1ZWah46QV1I5Hpuwg,3955
+pyroller/transcriber/whisperx.py,sha256=dC7NdAZZChw4q3c2DTyoy9P6HnDCh52r0S-qdz7_Nek,8215
+pyroller/utils/__init__.py,sha256=wBvwwcI-PRMSG9moT_mL87KdVJlfRAOHsz3CCQsMmpg,91
+pyroller/utils/ids.py,sha256=1FmjmDsRf6wzM5EVolA-212xCZIYrSzjnro-3EO27UM,130
+pyroller/utils/json.py,sha256=q6mpIj06upA8mIjsBuZSc4WLDxCgTd7Y8S4hJj3K3Jo,654
+pyroller/utils/text.py,sha256=IyUPks1yy24i1JK4SnWI7WNQoro6zsAsR8BLspPusgo,37072
+pyroller/utils/time.py,sha256=PlTlSTj1qqzvEJC-JqEfjmJk68zyaG5p71j8Nl37aKw,942
+pyroller/writer/__init__.py,sha256=kIrq2Ej-KdqpVMJbeslHJT6UzSGeDGGkErWdl--LM2I,289
+pyroller/writer/ass_karaoke.py,sha256=HA3IYLETCH119IKduWksLqcMzSHf1RmccTaphx5Qu0o,5376
+pyroller/writer/base.py,sha256=kW-r_emRzojlBjsX0vLnyU-kARYeU-ZFsqw8AV-MBjM,313
+pyroller/writer/lrc.py,sha256=kwWWqddSYjAaWEbjUgkDu8pyxw56uQ0JqI6YxCWOSaI,4002
+pyroller/writer/registry.py,sha256=Ollbm3c_-AEa8AW0Oy_oy5M2BiPlaYMExOia40dV37A,1643
+py_roller-0.4.0.dist-info/METADATA,sha256=l1QCkhoFcAYqU6ao0wKdTGwb2KZHUeW4zPmvEyEe618,11560
+py_roller-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+py_roller-0.4.0.dist-info/entry_points.txt,sha256=leTOy5j6XuYvi7W2Ao_-aYVQJXAu-GQXTi35EWoD5xU,53
+py_roller-0.4.0.dist-info/top_level.txt,sha256=CPPRlFDCiTdYsa0ok7daAxQYUR33XtDodyju4qogpis,9
+py_roller-0.4.0.dist-info/RECORD,,

py_roller-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_roller-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+py-roller = pyroller.cli.main:main

py_roller-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyroller

pyroller/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.4.0"

pyroller/aligner/__init__.py

@@ -0,0 +1,10 @@
+from .base import Aligner
+from .global_dp_v1 import GlobalDPAligner
+from .registry import build_aligner, list_available_aligner_backends
+
+__all__ = [
+    "Aligner",
+    "GlobalDPAligner",
+    "build_aligner",
+    "list_available_aligner_backends",
+]

pyroller/aligner/base.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from pyroller.domain import AlignmentResult, ParsedLyrics, TranscriptionResult
+from pyroller.progress import ProgressReporter
+
+
+class Aligner(ABC):
+    name = "aligner"
+    accepts = ("timed_units", "parsed_lyrics")
+    produces = "alignment_result"
+
+    @abstractmethod
+    def align(self, transcription: TranscriptionResult, parsed_lyrics: ParsedLyrics, progress: ProgressReporter | None = None) -> AlignmentResult:
+        raise NotImplementedError