mirror of
https://github.com/nomadkaraoke/karaoke-gen.git
synced 2026-11-20 13:07:57 +09:00
## Summary Final piece of the review-page speed work (#1024 → #1028 → #1029): the Waveforms-mode strips no longer require downloading + WebAudio-decoding the entire vocals stem (~7.5MB, ~4–6s) — the backend now serves a **precomputed 400-peaks/s envelope as ~150KB of uint8/base64 JSON**, cached in GCS and pre-warmed at prep time, so strips paint sub-second. ## How - **`WaveformGenerator.generate_peaks()`** — numpy max-abs envelope, bucket-for-bucket identical to the frontend's `computePeaks` (same drift-free fractional-stride bucketing; exact match vs a naive reference in tests). - **`AudioAnalysisService.get_vocals_peaks()`** — GCS cache at `review-audio/vocals_peaks_400.json`, validated against the stem path; miss decodes the small transcoded OGG; upload best-effort. - **`GET /api/review/{job_id}/vocals-peaks`** — off the event loop under the shared waveform semaphore; `202 Retry-After: 15` while separation runs (mirrors `/audio/vocals`); `Cache-Control: private, max-age=600`; `peaks_per_second` clamped 50–1000. - **`screens_worker`** pre-computes the envelope next to the existing OGG + waveform pre-warm, so it's a pure cache read by the time a job reaches review. - **Frontend** — `VocalsAudioDataLoader` prefers the peaks endpoint (one quick retry on transient errors) and **falls back to the original full download+decode** on any terminal peaks failure, so a peaks-side problem can never cost a user their waveforms. Local mode (no peaks URL) uses the old path unchanged. Vocal stem selection factored into `backend/utils/stems.py` (shared by routes + worker). ## Testing - Package: 4 tests incl. exact naive-reference parity (**106 passed**) - Backend: 4 service + 4 endpoint tests (**4518 passed**) - Frontend: `fetchVocalsPeaks` units + 5 loader-behavior tests (prefers peaks / falls back / one-retry-then-fallback / 202 polling / audio-only mode) (**1307 passed**) - `review-fast-load.spec.ts` prod E2E extended with a cached vocals-peaks latency/shape check - Post-deploy: will verify the endpoint on a real in-review job and confirm payload size + latency ## Notes - Existing in-review jobs have no cache yet — their first Waveforms open computes + caches lazily (bounded); every open after that is sub-second. New jobs are pre-warmed. - 8-bit amplitude quantization is visually lossless at strip heights (14px). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Unit Tests for KaraokePrep
This directory contains unit tests for the KaraokePrep class.
Test Files
The tests are organized into the following files:
test_initialization.py: Tests for initialization and basic functionalitytest_file_operations.py: Tests for file operations (copy, download, convert)test_metadata.py: Tests for metadata extraction and parsingtest_lyrics.py: Tests for lyrics processingtest_audio.py: Tests for audio processing and separationtest_video.py: Tests for video creation and processingtest_async.py: Tests for async methods
Running the Tests
To run the tests, you need to have the test dependencies installed:
pip install -r requirements-test.txt
Then you can run the tests with:
python run_tests.py
This will run all the tests and generate a coverage report.
Checking Test Files
If you want to check if the test files are valid Python code without running the tests, you can use:
python check_tests.py
This will check if all the test files can be imported without errors.
Test Coverage
The tests aim to cover all the functionality of the KaraokePrep class. The coverage report will show you which parts of the code are covered by the tests.