wispr-lrc 0.1.2__tar.gz

wispr_lrc-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev --locked
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Benchmark smoke
+        run: |
+          mkdir -p "$RUNNER_TEMP/wispr-ci"
+          uv run wispr benchmark tests/fixtures/jingle_bells.m4a tests/fixtures/jingle_bells.txt \
+            --backend mock \
+            --debug \
+            --force \
+            -o "$RUNNER_TEMP/wispr-ci/jingle_bells.lrc" \
+            --report "$RUNNER_TEMP/wispr-ci/jingle_bells.benchmark.json"
+          test -f "$RUNNER_TEMP/wispr-ci/jingle_bells.lrc"
+          test -f "$RUNNER_TEMP/wispr-ci/jingle_bells.benchmark.json"
+          test -f "$RUNNER_TEMP/wispr-ci/jingle_bells.debug/timings.json"
+
+      - name: Build package
+        run: uv build

wispr_lrc-0.1.2/.github/workflows/ml-benchmark.yml

@@ -0,0 +1,66 @@
+name: Manual ML Benchmark
+
+on:
+  workflow_dispatch:
+    inputs:
+      model:
+        description: WhisperX model name
+        required: true
+        default: base
+      device:
+        description: Runtime device
+        required: true
+        default: cpu
+      compute-type:
+        description: WhisperX compute type
+        required: true
+        default: int8
+
+jobs:
+  whisperx-benchmark:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ffmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+
+      - name: Install ML dependencies
+        run: uv sync --dev --extra ml --locked
+
+      - name: Run WhisperX benchmark
+        run: |
+          mkdir -p "$RUNNER_TEMP/wispr-ml"
+          uv run wispr benchmark tests/fixtures/jingle_bells.m4a tests/fixtures/jingle_bells.txt \
+            --backend whisperx \
+            --model "${{ inputs.model }}" \
+            --device "${{ inputs.device }}" \
+            --compute-type "${{ inputs['compute-type'] }}" \
+            --debug \
+            --force \
+            -o "$RUNNER_TEMP/wispr-ml/jingle_bells.lrc" \
+            --report "$RUNNER_TEMP/wispr-ml/jingle_bells.benchmark.json"
+
+      - name: Upload benchmark artifacts
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: wispr-ml-benchmark
+          path: |
+            ${{ runner.temp }}/wispr-ml/*.lrc
+            ${{ runner.temp }}/wispr-ml/*.benchmark.json
+            ${{ runner.temp }}/wispr-ml/*.debug/**

wispr_lrc-0.1.2/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+inputs/
+*.lrc
+*.benchmark.json
+*.summary.json
+*.debug/

wispr_lrc-0.1.2/.redsun/.gitignore

@@ -0,0 +1 @@
+*

wispr_lrc-0.1.2/.redsun/AGENTS.md

@@ -0,0 +1,203 @@
+# AGENTS.md
+
+## Purpose
+
+This repository implements **wispr**, a Python library and CLI for generating synchronized standard line-level `.lrc` files from full-song audio plus a canonical line-by-line lyrics file.
+
+The core product goal is not lyric generation. The system should treat the provided lyrics file as the source of truth and use transcription and forced alignment tooling primarily to recover timing information.
+
+Agents working in this repository should optimize for **software engineering quality first**: clean module boundaries, deterministic behavior, strong testability, clear failure modes, and a polished command-line user experience.
+
+## Product Scope
+
+### In scope for v1
+
+- English-only alignment.
+- Full-song processing.
+- Standard line-level `.lrc` output.
+- Audio inputs: `.wav`, `.mp3`, `.flac`, `.m4a`.
+- Optional metadata extraction from source audio.
+- Typer-based CLI plus reusable Python library.
+- Debug artifacts for transcript, alignment, and segments.
+- Warnings on weak alignment while continuing output generation.
+
+### Out of scope for v1
+
+- Word-level karaoke timing.
+- Multilingual support.
+- Docker packaging.
+- Extra subcommands like `wispr doctor`.
+- Replacing the provided lyrics with model-generated text.
+
+## Core Principles
+
+### 1. Canonical lyrics are the source of truth
+
+The contents of `lyrics.txt` must define the emitted lyric text. Do not silently rewrite lyrics to match model output.
+
+### 2. Timing over transcription
+
+Transcript and alignment stages exist to obtain usable timestamps. They do not define the final textual output.
+
+### 3. Library first, CLI second
+
+The CLI should be a thin wrapper over reusable internal modules. Business logic should not live directly inside CLI command functions.
+
+### 4. Deterministic output where possible
+
+Formatting, metadata ordering, path resolution, warning behavior, and line segmentation should be predictable and testable.
+
+### 5. Safe defaults
+
+The default experience should be optimized for likely real-world success:
+- Vocal separation on by default.
+- Output path derived from input audio filename.
+- Existing output files should not be overwritten unless `--force` is passed.
+- Missing metadata should be skipped, not treated as fatal.
+- Weak alignment should warn and continue.
+
+## User Experience Contract
+
+The primary demo path should remain:
+
+```bash
+wispr song.wav lyrics.txt
+```
+
+Expected behavior:
+- Produces `song.lrc` next to the audio file unless `-o` is provided.
+- Uses the first aligned word in each lyric line as that line's timestamp.
+- Emits metadata tags before lyric lines when metadata is available.
+- Fails on output collisions unless `--force` is provided.
+- Writes debug artifacts only when `--debug` is enabled.
+
+## Expected Output Format
+
+wispr should emit standard line-level LRC.
+
+If metadata is available, write tags in this fixed order:
+1. `[ar:]`
+2. `[al:]`
+3. `[ti:]`
+4. Timestamped lyric lines
+
+Do not emit empty placeholder metadata tags.
+
+## Recommended Project Structure
+
+```text
+wispr/
+  __init__.py
+  cli.py
+  pipeline.py
+  audio.py
+  metadata.py
+  transcribe.py
+  align.py
+  segment.py
+  lrc.py
+  models.py
+  warnings.py
+tests/
+```
+
+### Module responsibilities
+
+- `cli.py`: Typer commands, user-facing flags, terminal messaging.
+- `pipeline.py`: stage orchestration.
+- `audio.py`: validation, preprocessing, vocal-separation integration.
+- `metadata.py`: source metadata extraction and normalization.
+- `transcribe.py`: transcript and raw timestamp acquisition.
+- `align.py`: forced-alignment backend integration.
+- `segment.py`: map aligned words onto canonical lyric lines.
+- `lrc.py`: timestamp formatting and final file serialization.
+- `models.py`: shared data structures across stages.
+- `warnings.py`: structured warning types and formatting.
+
+## Implementation Guidance
+
+### Prefer explicit data models
+
+Use typed models or dataclasses for stage boundaries instead of large unstructured dictionaries.
+
+Suggested entities include:
+- `TrackMetadata`
+- `TranscriptWord`
+- `AlignedWord`
+- `LyricLine`
+- `LrcDocument`
+
+### Keep backend boundaries clean
+
+The alignment backend should be abstracted behind a narrow interface so the project can begin with WhisperX-centered alignment and later swap or add custom aligners without rewriting the whole pipeline.
+
+### Preserve inspectability
+
+When adding logic, prefer designs that make it easier to understand how a timestamp was produced. Debuggability matters more than cleverness.
+
+### Avoid premature product sprawl
+
+Do not add extra commands, frontend layers, web services, or database infrastructure unless explicitly requested. The value of this project comes from doing one CLI workflow well.
+
+## Debug Artifacts
+
+When `--debug` is enabled, write a folder of intermediate artifacts containing:
+- `transcript.json`
+- `alignment.json`
+- `segments.json`
+
+These artifacts should reflect the real internal pipeline state, not post-hoc summaries.
+
+## Warning Policy
+
+Weak alignment should not abort the entire run.
+
+Warnings should include:
+- Line number.
+- Confidence score.
+- Estimated timestamp source.
+
+Warnings should be informative enough that a user can inspect the affected line and understand why the output may be imperfect.
+
+## Testing Priorities
+
+Focus tests on deterministic logic and contract behavior.
+
+High-priority tests:
+- LRC timestamp formatting.
+- Metadata ordering and omission.
+- Line segmentation behavior.
+- Output collision handling with and without `--force`.
+- Warning generation for weak alignment.
+- Output filename derivation from input audio.
+
+Where possible, use small synthetic fixtures and mocked backend outputs instead of heavyweight full-model runs.
+
+## Documentation Expectations
+
+When updating the repo:
+- Keep architecture and behavior consistent with `ARCHITECTURE.md`.
+- Document new flags, outputs, or format changes in the README.
+- Call out any deviation from the v1 contract explicitly.
+
+## Style Expectations
+
+- Prefer small, composable functions over monolithic pipeline code.
+- Keep side effects localized.
+- Make error messages concrete and actionable.
+- Favor clarity over clever abstractions.
+- Add comments where intent is not obvious, but do not narrate trivial code.
+- "wispr" should always be typed in all lowercase. Do not use "Wispr" or "WISPR" or any other formatting
+
+## Agent Behavior
+
+Agents assisting with this project should:
+- Preserve the library-plus-CLI structure.
+- Respect the canonical-lyrics-first design.
+- Avoid introducing hidden behavior that changes lyric text.
+- Prefer incremental, reviewable changes.
+- Keep recommendations aligned with recruiter-facing SWE value and real usability.
+- Code should be structured in a clean and organized way, and be human readable. 
+- Be consise with code generation, focus on writing as few lines of code as possible.
+
+When responding, guide and explain clearly when useful, but keep implementations aligned with the repository's architecture and scope.

wispr_lrc-0.1.2/.redsun/ARCHITECTURE.md

@@ -0,0 +1,208 @@
+# wispr Architecture
+
+## Overview
+
+wispr is a Python library and CLI that converts full-song audio plus a canonical line-by-line lyrics file into a synchronized, standard line-level `.lrc` output. The CLI is the simplest interface over a reusable library, not a one-off script.[cite:58][cite:60]
+
+The project is intentionally scoped around timing alignment rather than lyric generation. Standard LRC supports line-level timestamps and optional metadata tags, which makes it a good target for a deterministic v1 that is easy to inspect, test, and demo.[cite:34][cite:65][cite:31]
+
+## Product Goals
+
+### Primary goals
+
+- Accept `.wav`, `.mp3`, `.flac`, and `.m4a` audio inputs.[cite:74][cite:78]
+- Accept a `lyrics.txt` file where each line represents one intended lyric line.
+- Produce a standard line-level `.lrc` file with one timestamp per lyric line.[cite:34][cite:65]
+- Prefer forced alignment for timing accuracy while keeping the provided lyric text as the source of truth.[cite:32][cite:42][cite:8]
+- Ship as both a reusable Python package and an installed `wispr` command via Python entry points.[cite:60]
+
+### Non-goals for v1
+
+- Word-level karaoke timing.
+- Multilingual alignment.
+- Docker packaging.
+- Additional diagnostic subcommands such as `wispr doctor`.
+
+## User Experience
+
+The default happy path should be:
+
+```bash
+wispr song.wav lyrics.txt
+```
+
+When `-o` is omitted, wispr should derive the output path from the audio filename, so `random_song232.wav` becomes `random_song232.lrc`.
+
+If the destination file already exists, the command should fail unless `--force` is passed. Alignment problems should produce warnings and continue rather than aborting the entire run.
+
+## CLI Contract
+
+wispr should use Typer for the command-line interface so the public command surface can stay small now and grow cleanly later through typed arguments and options.[cite:58]
+
+### Initial command surface
+
+```bash
+wispr <audio> <lyrics.txt>
+wispr <audio> <lyrics.txt> -o output.lrc
+wispr <audio> <lyrics.txt> --debug
+wispr <audio> <lyrics.txt> --force
+wispr <audio> <lyrics.txt> --no-separate-vocals
+```
+
+### Packaging model
+
+The package name and installed command should both be `wispr`. Installation should expose the CLI through a `console_scripts` entry point so users can run `wispr` directly from their shell after installation.[cite:60][cite:79]
+
+## Pipeline
+
+The default processing path is:
+
+1. Audio ingest and validation.
+2. Optional metadata extraction.
+3. Vocal separation, enabled by default.
+4. Transcript and word-timestamp extraction.
+5. Forced alignment against the canonical lyric text.
+6. Line segmentation.
+7. LRC emission.
+
+WhisperX is the intended alignment anchor for v1 because it is built around refining Whisper timestamps with forced alignment to improve timestamp accuracy.[cite:32][cite:42][cite:8]
+
+### Stage details
+
+#### 1. Audio ingest
+
+The input layer should validate supported extensions, normalize paths, and prepare audio for downstream tools.
+
+#### 2. Metadata extraction
+
+wispr should opportunistically extract title, artist, and album metadata from the source file. Mutagen is a good fit because it supports common audio metadata handling across formats including MP3, FLAC, and MP4-family files.[cite:74][cite:78]
+
+If metadata is missing or unreadable, wispr should skip those fields without failing the run.
+
+#### 3. Vocal separation
+
+Vocal separation should be on by default, with a user escape hatch through `--no-separate-vocals`. This keeps the default UX optimized for noisy real songs while preserving a fast path for cleaner inputs.
+
+#### 4. Transcript and alignment
+
+The transcript stage exists to recover timing signals, not to produce final lyric text. The canonical lyrics file remains the source of truth for emitted lines, while the alignment backend maps timing evidence onto those lines.[cite:32][cite:42]
+
+#### 5. Line segmentation
+
+Because the lyrics input is already line-structured, segmentation should map aligned word spans onto each original lyric line rather than trying to infer poetic phrasing from paragraph text.
+
+#### 6. LRC emission
+
+The emitted file should be standard line-level LRC. Each lyric line should use the timestamp of the first aligned word in that line.[cite:34][cite:65]
+
+If metadata exists, it should be written before the lyric body in fixed order:
+
+1. `[ar:]`
+2. `[al:]`
+3. `[ti:]`
+4. Timestamped lyric lines
+
+Metadata tags should be omitted individually when unavailable rather than written as empty placeholders.[cite:34][cite:65]
+
+## Internal Architecture
+
+wispr should be library-first with a thin CLI wrapper. The CLI exists to parse inputs and display results, while the library owns orchestration, transformation, and file generation.
+
+### Proposed package layout
+
+```text
+wispr/
+  __init__.py
+  cli.py
+  pipeline.py
+  audio.py
+  metadata.py
+  transcribe.py
+  align.py
+  segment.py
+  lrc.py
+  models.py
+  warnings.py
+tests/
+```
+
+### Module responsibilities
+
+| Module | Responsibility |
+|---|---|
+| `cli.py` | Typer commands, argument parsing, user-facing output.[cite:58] |
+| `pipeline.py` | End-to-end orchestration and stage ordering. |
+| `audio.py` | Input validation, preprocessing, and vocal-separation integration. |
+| `metadata.py` | Audio metadata extraction and normalization via Mutagen-compatible readers.[cite:74][cite:78] |
+| `transcribe.py` | Transcript and raw word-timestamp acquisition. |
+| `align.py` | Forced-alignment adapter and backend boundary.[cite:42][cite:32] |
+| `segment.py` | Map aligned tokens/spans onto lyric lines. |
+| `lrc.py` | Metadata ordering, timestamp formatting, and final `.lrc` serialization.[cite:34][cite:65] |
+| `models.py` | Shared typed data structures between stages. |
+| `warnings.py` | Structured warning types and formatting. |
+
+## Data Model
+
+The internal pipeline should pass structured models instead of ad hoc dictionaries where possible.
+
+### Core objects
+
+- `TrackMetadata`: title, artist, album, source path.
+- `TranscriptWord`: text, start time, end time, confidence, source.
+- `AlignedWord`: canonical token, start time, end time, confidence, timestamp source.
+- `LyricLine`: line number, raw text, aligned words, line start time, confidence.
+- `LrcDocument`: metadata tags plus ordered timestamped lyric lines.
+
+This keeps the CLI thin, improves unit-test boundaries, and makes it easier to swap alignment backends later.
+
+## Debug Artifacts
+
+Debug mode should write a folder of intermediate artifacts rather than a single file.
+
+### Required debug outputs
+
+- `transcript.json`
+- `alignment.json`
+- `segments.json`
+
+These files should make it possible to inspect where timing entered the pipeline, how canonical lyrics were aligned, and how final line timestamps were chosen.
+
+## Warning Policy
+
+wispr should warn and continue when a line is weakly aligned instead of failing the whole song.
+
+Each warning should include:
+
+- Line number.
+- Confidence score.
+- Estimated timestamp source.
+
+This policy preserves a usable output file while still surfacing uncertainty to the user.
+
+## Testing Priorities
+
+The highest-value unit tests should target deterministic logic rather than heavyweight model execution.
+
+### Must-test areas
+
+- LRC timestamp formatting and serialization.[cite:34][cite:65]
+- Metadata tag ordering and omission behavior.[cite:34][cite:65]
+- Line-to-span segmentation.
+- Existing-file collision behavior with and without `--force`.
+- Warning generation when confidence falls below threshold.
+
+The alignment backend itself should be wrapped behind interfaces so pure logic can be tested with synthetic fixtures instead of depending on full external model runs.
+
+## Future Extensions
+
+The current architecture should leave room for later additions without forcing a redesign.
+
+### Likely future work
+
+- Word-level karaoke timing.
+- Multilingual support.
+- Alternative alignment backends.
+- Optional Docker packaging.
+- Richer metadata support.
+
+The key design rule is that the CLI should remain the purest interface to the library: simple for end users, while the library stays modular enough for testing, reuse, and future backends.

wispr_lrc-0.1.2/AGENTS.md

@@ -0,0 +1 @@
+@.redsun/AGENTS.md