Compare commits

...
Author SHA1 Message Date
Andrew Beveridge 9e53bb7934 Merge remote-tracking branch 'origin/main' into feature/annotation-toggle 2025-12-18 01:53:10 -05:00
Andrew Beveridge ☄️ a85727b147 Merge pull request #28 from nomadkaraoke/fix-flac-fetcher
Fix flacfetch API compatibility and use rich CLI output
2025-12-18 01:52:32 -05:00
Andrew Beveridge 3eb8f707b6 Add toggle to disable annotation prompts when editing lyrics
- Add "Feedback On/Off" chip in header next to title
- Toggle persists to localStorage for session continuity
- Defaults to enabled (annotation prompts shown)
- Hidden in read-only mode
- Tooltip explains functionality

Version bump: 0.71.63 -> 0.71.64
2025-12-18 01:46:41 -05:00
Andrew Beveridge 4b26fe9eac Add integration tests for flacfetch compatibility
Add comprehensive tests that would have caught both recent bugs:

1. TestGetManagerIntegration - Tests that actually execute _get_manager():
   - test_get_manager_imports_work: Would have caught YouTubeProvider rename
   - test_get_manager_registers_*: Would have caught missing downloader registration

2. TestFlacFetchReleaseModelCompatibility - Tests against real flacfetch models:
   - test_release_model_has_expected_attributes: Verifies attribute names match
   - test_search_converts_release_attributes_correctly: Tests with real Release objects

3. TestFlacFetchCLIHandlerCompatibility - Tests CLIHandler integration:
   - test_cli_handler_import_works: Verifies import path
   - test_cli_handler_works_with_real_releases: Tests with real Quality objects

These tests use real flacfetch classes instead of mocks to catch API changes.

Bump version to 0.71.63
2025-12-18 01:37:00 -05:00
Andrew Beveridge 4de3ecc85d Register downloaders for flacfetch sources
- Register YoutubeDownloader for YouTube source
- Register TorrentDownloader for Redacted and OPS sources
- Handle optional TorrentDownloader import (has extra dependencies)

This fixes "No downloader registered for source: Redacted" error when
trying to download from torrent tracker sources.

Bump version to 0.71.62
2025-12-18 01:32:52 -05:00
Andrew Beveridge cbb4cd8f9e Fix flacfetch API compatibility and use rich CLI output
- Update YouTubeProvider import to YoutubeProvider (API change in flacfetch 0.2.0)
- Update attribute names to match flacfetch Release model:
  - provider -> source_name
  - duration -> duration_seconds
  - url -> download_url
  - id -> info_hash
- Use flacfetch's built-in CLIHandler for rich, colorized interactive selection
- Add fallback to basic display if CLIHandler fails (e.g., in tests)
- Update tests to use correct flacfetch attribute names

Bump version to 0.71.61
2025-12-18 01:25:55 -05:00
Andrew Beveridge ☄️ 218011cf2a Merge pull request #27 from nomadkaraoke/refactor/instrumental-review-ui-improvements
Refactor instrumental review UI: extract frontend to static file and improve UX
2025-12-18 01:22:55 -05:00
Andrew Beveridge 22c6e7ed41 Fix audio listeners not attached after DOM rebuild
Track audio element reference instead of boolean flag to detect when the
audio element is replaced during render(). Re-attach listeners when the
element changes, ensuring new audio elements have proper event handlers.

Version bump: 0.71.59 → 0.71.60
2025-12-18 01:13:19 -05:00
Andrew Beveridge e104fb9252 Add original audio option to instrumental review UI
Backend:
- Add original_audio_path parameter to InstrumentalReviewServer
- Add /api/audio/original endpoint for streaming original audio
- Add "original" to valid selection options

Frontend:
- Add "Original" toggle button (shown first when available)
- Add "Original Audio" selection option with description
- Add original to success message labels

Helper script:
- Find original audio files matching "(Original)" pattern
- Log and pass original_audio_path to server

Version bump: 0.71.58 → 0.71.59
2025-12-18 01:05:11 -05:00
Andrew Beveridge 31931cc55d Address CodeRabbit PR review comments
Frontend (index.html):
- Fix duplicate event listeners: add audioListenersInitialized flag and named
  handlers (onAudioPlay, onAudioPause, onAudioEnded) to prevent accumulation
- Remove redundant removeEventListener in loadeddata handler (already using once: true)
- Use data-audio-type attributes on toggle buttons for robust type detection
- Add escapeHtml() helper to prevent XSS in artist/title/filename interpolation
- Guard updatePlayhead() against NaN/Infinity when duration is 0 or invalid
- Add explicit 'uploaded' branch in success message ternary

Backend (server.py):
- Wrap temp file handling in try/finally to ensure cleanup on error
- Track file_moved state to only unlink temp file if not successfully moved

Version bump: 0.71.57 → 0.71.58
2025-12-18 00:45:55 -05:00
Andrew Beveridge d21729bf3d Fix JavaScript syntax error and improve file discovery in helper script
- Fix invalid escape sequences in updateMuteRegionsPanel() - use string
  concatenation instead of nested template literals
- Update helper script to find instrumental files in main job directory
  (not just stems/) and handle "+BV" naming convention

Version bump: 0.71.56 → 0.71.57
2025-12-18 00:39:07 -05:00
Andrew Beveridge b49a09e1c6 Add helper script to run instrumental review UI from existing job folder
New script: scripts/run_instrumental_review.py
- Takes a karaoke job directory path as input
- Auto-discovers backing vocals, clean instrumental, and combined files in stems/
- Runs audio analysis and generates waveform if needed
- Starts the review server for frontend development iteration

Usage:
  python scripts/run_instrumental_review.py "Artist - Title"
  python scripts/run_instrumental_review.py "path/to/job" --port 9000
  python scripts/run_instrumental_review.py "path/to/job" --no-browser

Version bump: 0.71.55 → 0.71.56
2025-12-18 00:34:41 -05:00
Andrew Beveridge e6b2194272 Preserve scroll position when adding/removing mute regions while zoomed
- Replace full render() calls with targeted updates when modifying mute regions
- Add updateMuteRegionsPanel() to update only the mute panel DOM
- Just redraw waveform canvas instead of rebuilding entire UI
- Scroll position is now preserved when adding, removing, or clearing regions

Version bump: 0.71.54 → 0.71.55
2025-12-18 00:31:51 -05:00
Andrew Beveridge a08b83df40 Add custom instrumental upload and waveform zoom features
Upload feature:
- Add POST /api/jobs/local/upload-instrumental endpoint
- Validate uploaded audio duration matches original (±0.5s tolerance)
- Support .flac, .mp3, .wav, .m4a, .ogg formats
- Show upload progress overlay with spinner
- Auto-select uploaded audio after successful upload
- Add "Uploaded" option to audio toggles and final selection

Zoom feature:
- Add 1x, 2x, 4x zoom levels for waveform precision
- Waveform container is horizontally scrollable when zoomed
- Zoom controls in toolbar with active state indication
- Maintain proportional scroll position when changing zoom
- Playhead and selection overlay work correctly at all zoom levels

Version bump: 0.71.53 → 0.71.54
2025-12-18 00:27:38 -05:00
Andrew Beveridge 53d2ed2828 Fix duplicate audio when switching sources during playback
- Remove full render() call from setActiveAudio() to avoid recreating audio element
- Update toggle button states directly via classList instead of DOM rebuild
- Check actual audio.paused state instead of isPlaying variable (which gets stale)
- Prevents multiple audio streams playing simultaneously

Version bump: 0.71.52 → 0.71.53
2025-12-18 00:10:58 -05:00
Andrew Beveridge ff20b5ffb3 Fix audio playback AbortError when DOM rebuilds during render
- Pause audio before rebuilding DOM in render() to prevent AbortError
- Use loadeddata event to safely restore playback position and state
- Handle audio lifecycle properly in setActiveAudio() and createCustomInstrumental()
- Prevents duplicate audio playback and console errors

Version bump: 0.71.51 → 0.71.52
2025-12-18 00:09:08 -05:00
Andrew Beveridge 49290f94d7 Refactor instrumental review UI: extract frontend to static file and improve UX
- Move inline HTML/CSS/JS from server.py to static/index.html for better maintainability
- Add proper syntax highlighting, formatting, and linting support for frontend code
- Server now reads HTML from file using Path(__file__).parent / "static"

UI/UX improvements:
- Click on waveform now seeks AND starts playback automatically
- Switching audio sources (Backing/Clean/Combined) maintains playback state
- Clearer audio mode labels: "Backing Vocals Only", "Pure Instrumental", "Instrumental + Backing"
- Replace M key toggle mode with Shift+drag for intuitive mute region selection
- Update help text and keyboard hints

Package configuration:
- Add karaoke_gen/instrumental_review/static/* to pyproject.toml includes
- Verified static files are correctly packaged in wheel for pip installs

Version bump: 0.71.48 → 0.71.51
2025-12-18 00:07:13 -05:00
Andrew Beveridge ☄️ 9b114fcb3d Merge pull request #26 from nomadkaraoke/fix/waveform-generator-param-name
fix: correct parameter name in WaveformGenerator.generate() call
2025-12-17 23:34:34 -05:00
Andrew Beveridge e507b3f685 fix: prevent duplicate log messages from external package side effects
External packages like lyrics_converter call logging.info() directly on the
root logger, which triggers Python's 'last resort' handler. This causes log
messages to appear twice: once from our custom handler and once from the
root logger's default handler.

Fixed by setting logger.propagate = False on all loggers that have their
own handlers configured. This prevents logs from propagating to the root
logger while still displaying through our custom formatted handlers.

Affected files:
- karaoke_gen/karaoke_finalise/karaoke_finalise.py
- karaoke_gen/karaoke_gen.py
- karaoke_gen/utils/gen_cli.py
- karaoke_gen/utils/remote_cli.py
- karaoke_gen/utils/bulk_cli.py

Also updated tests to use capsys instead of caplog since caplog relies
on log propagation to capture messages.

Bumps version to 0.71.47
2025-12-17 23:17:29 -05:00
Andrew Beveridge 6d0c765f4d test: add integration tests for run_instrumental_review parameter contract
Added tests that verify:
- WaveformGenerator.generate() is called with 'segments' (not 'audible_segments')
- Correct parameter values are passed between components
- Error handling and edge cases

These tests would have caught the parameter name bug that broke
the instrumental review flow. They exercise the actual function
with properly mocked components instead of mocking the entire function.

Bumps version to 0.71.46
2025-12-17 23:04:51 -05:00
Andrew Beveridge 8086242d38 fix: correct parameter name in WaveformGenerator.generate() call
The WaveformGenerator.generate() method expects 'segments' parameter,
not 'audible_segments'. This caused the instrumental review to fail
with 'unexpected keyword argument' error during karaoke-gen CLI execution.

Bumps version to 0.71.45
2025-12-17 22:56:59 -05:00
Andrew Beveridge ☄️ 3c3680632b Merge pull request #25 from nomadkaraoke/fix/instrumental-selection-single-path
Remove legacy instrumental selection fallback, fix path resolution
2025-12-17 22:23:46 -05:00
Andrew Beveridge dd5f05b291 fix: update integration test to use --skip_instrumental_review
The integration test was failing because it didn't provide the
separated_audio data structure expected by run_instrumental_review.
Since the test uses mocked audio data, it makes sense to use the
--skip_instrumental_review flag with auto_select_instrumental instead.

- Added --skip_instrumental_review to test CLI args
- Updated mock_process_audio_separation to return clean_instrumental
  data structure needed by auto_select_instrumental
- Bumped version to 0.71.44
2025-12-14 13:30:47 -05:00
Andrew Beveridge 9340ed5d9f Remove legacy instrumental selection fallback, fix path resolution
This change eliminates the silent fallback to the legacy numbered instrumental
selection in KaraokeFinalise and ensures a single code path for instrumental
selection:

1. **Path resolution fix**: Added `_resolve_path_for_cwd()` helper to correctly
   resolve paths in `separated_audio` after `os.chdir(track_dir)`. The paths
   were stored relative to the original directory, causing `os.path.exists()`
   to fail after the directory change.

2. **No silent fallback**: When `run_instrumental_review()` fails, the CLI now
   exits with a clear error message explaining what went wrong and how to fix
   it, rather than silently falling back to the legacy numbered selection.

3. **Auto-select for non-interactive mode**: Added `auto_select_instrumental()`
   function for `--skip_instrumental_review` mode that intelligently selects
   the best instrumental (preferring padded+combined > padded > combined > clean).

4. **Clear error messages**: When instrumental selection fails, users now get
   detailed diagnostics about what to check and how to recover.

The legacy `choose_instrumental_audio_file()` method in KaraokeFinalise is
preserved for direct usage but is no longer called from the gen_cli flow.

Includes comprehensive tests for the new helper functions.

Bump version to 0.71.43.
2025-12-14 13:10:29 -05:00
Andrew Beveridge ☄️ 8959da63a1 Merge pull request #24 from nomadkaraoke/fix/instrumental-review-path-resolution
Fix instrumental review UI path resolution after chdir
2025-12-14 12:56:07 -05:00
Andrew Beveridge ☄️ cb7b4863f5 Merge pull request #13 from nomadkaraoke/feature/batch-5-flacfetch-audio-search
feat: Batch 5 - Flacfetch audio search for remote CLI
2025-12-14 12:53:45 -05:00
Andrew Beveridge e84a511676 Fix instrumental review UI path resolution after chdir
The instrumental review UI was being skipped with "No backing vocals file
found" because file paths stored in separated_audio were relative to the
original working directory, but os.chdir(track_dir) had already been called
before the paths were checked with os.path.exists().

This fix:
- Adds _resolve_path_for_cwd() helper to convert paths that were created
  relative to the original directory to work from the new current directory
- Applies path resolution to backing_vocals, clean_instrumental, and
  combined_instrumentals paths before checking their existence
- Updates waveform and output paths to use current directory since we're
  already inside track_dir after chdir

Includes unit tests for the new helper function.

Bump version to 0.71.42.
2025-12-11 20:27:11 -05:00
Andrew Beveridge aee2b48ffd Merge origin/main into feature/batch-5-flacfetch-audio-search
Resolved conflicts to combine:
- Batch 4 (YouTube URL input) from main
- Batch 5 (Flacfetch audio search) from this branch

Both features are now fully integrated:
- P2 (YouTube URLs): ✅ COMPLETE
- P3 (Flacfetch search): ✅ COMPLETE
- A1 (--auto-download): ✅ COMPLETE

remote_cli.py now supports:
- File upload mode (original)
- YouTube URL mode (from main)
- Audio search mode (from this branch)

Documentation updated to reflect both batches complete.
Version bumped to 0.71.42.
2025-12-11 20:10:03 -05:00
Andrew Beveridge ☄️ a7652ba72d Merge pull request #23 from nomadkaraoke/fix/local-cli-instrumental-review-integration
fix: integrate instrumental review UI into local CLI workflow
2025-12-11 19:42:21 -05:00
Andrew Beveridge 0ce5225bde fix: integrate instrumental review UI into local CLI workflow
The instrumental review UI was built but never integrated into the
local CLI (karaoke-gen) workflow. This fix:

1. Adds run_instrumental_review() function to gen_cli.py that:
   - Analyzes backing vocals using AudioAnalyzer
   - Generates waveform visualization
   - Starts InstrumentalReviewServer and opens browser
   - Returns the user's selected instrumental file path

2. Integrates the review into the finalization loop:
   - Runs before KaraokeFinalise for each track
   - Passes selected_instrumental_file to KaraokeFinalise
   - Skips review if --skip_instrumental_review flag is set

3. Adds --skip_instrumental_review CLI flag for backwards compatibility

4. Adds comprehensive tests in test_cli_feature_parity.py that verify:
   - gen_cli.py has run_instrumental_review function
   - The function uses AudioAnalyzer, WaveformGenerator, and InstrumentalReviewServer
   - The --skip_instrumental_review flag works correctly

These tests would have caught this integration gap and will prevent
similar regressions in the future.

Version bump: 0.71.40 → 0.71.41
2025-12-11 19:15:37 -05:00
Andrew Beveridge ☄️ c494685211 Merge pull request #22 from nomadkaraoke/feature/instrumental-review-ui
feat: Add intelligent instrumental selection with web-based review UI
2025-12-11 19:01:40 -05:00
Andrew Beveridge 599625e21a fix: address CodeRabbit PR review comments and improve test coverage
CodeRabbit fixes:
- Chain exceptions with 'from e' in jobs.py for proper tracebacks
- Use logger.exception() for automatic stack traces
- Add end_seconds validation warning in audio_editing_service.py
- Handle recommended_selection='with_backing' explicitly in frontend
- Sync audio player state with actual audio element via event listeners
- Fix muted duration stats overcounting by clamping to audio duration
- Add num_points validation (1-10000) in server waveform endpoint
- Improve exception handling in server endpoints

Test coverage improvements:
- Add comprehensive tests for InstrumentalReviewServer
- Test request/response models
- Test server initialization and configuration
- Test FastAPI endpoints with TestClient
- Coverage: karaoke_gen 73.05% (above 70% minimum)

Version bump: 0.71.39 → 0.71.40
2025-12-11 18:33:20 -05:00
Andrew Beveridge 5c4404839b chore: remove unused imports from server.py 2025-12-11 18:09:50 -05:00
Andrew Beveridge f699850d30 feat: rewrite local review server with FastAPI and full-featured standalone UI
- Replace http.server with FastAPI for better async/CORS support
- Add complete standalone HTML/CSS/JS frontend with all features:
  - Dark theme matching React frontend
  - Interactive waveform display with Canvas rendering
  - Audio playback with source selection
  - Region selection via click/drag or quick-add from segments
  - Custom instrumental creation
  - Final selection submission with success feedback
- API endpoints now match cloud backend for true feature parity
- Update CLI parity tests for new FastAPI-based server structure
- Add test-instrumental-review.py script for local testing

This enables the same user experience for instrumental review
whether running locally (karaoke-gen) or remotely (karaoke-gen-remote).

Version bump: 0.71.38 → 0.71.39
2025-12-11 18:08:04 -05:00
Andrew Beveridge e8d9871d3e feat: Add intelligent instrumental selection with web-based review UI
Adds a comprehensive instrumental selection workflow with:
- Audio analysis to detect backing vocals (>-40dB threshold)
- Waveform visualization with segment highlighting
- Interactive web UI for audio playback and region selection
- Custom instrumental creation by muting selected regions
- Smart recommendations based on analysis results
- Feature parity between local (karaoke-gen) and remote (karaoke-gen-remote) CLIs

Key components:
- Shared core module (karaoke_gen/instrumental_review/) with AudioAnalyzer,
  AudioEditor, WaveformGenerator, and InstrumentalReviewServer
- Backend services wrapping core module with GCS integration
- New API endpoints for analysis, audio streaming, and custom creation
- React frontend components for waveform display, audio playback, region selection
- Local HTTP server for browser-based review in local CLI workflow
- 1280 tests passing with comprehensive coverage

Closes the need for manual Audacity editing when selecting instrumentals.
2025-12-11 17:12:49 -05:00
Andrew Beveridge ☄️ 473253b5ab Merge pull request #21 from nomadkaraoke/fix/enable-cloud-tasks-deployment
fix: Enable Cloud Tasks in deployment for scalable architecture
2025-12-11 16:20:00 -05:00
Andrew Beveridge 89cc9e9113 fix: Enable Cloud Tasks in deployment for scalable architecture
The scalable architecture (Cloud Tasks queues, IAM, infrastructure) was
deployed via Pulumi but never activated in the Cloud Run deployment.

Changes:
- Enable ENABLE_CLOUD_TASKS=true environment variable
- Set CLOUD_RUN_SERVICE_URL for Cloud Tasks callbacks
- Set GCP_REGION for queue location consistency
- Change concurrency from 4 to 1 for true container isolation
- Increase max-instances from 10 to 50 for higher throughput

This completes Phase 1 of the scalable architecture migration, ensuring
each job gets dedicated container resources with no contention.
2025-12-11 15:45:03 -05:00
Andrew Beveridge ☄️ ec5a816b68 Merge pull request #20 from nomadkaraoke/anchor-sequence-optimization
feat: Optimize AnchorSequenceFinder for cloud compatibility and performance
2025-12-11 14:37:06 -05:00
Andrew Beveridge 651cbbdbca feat: Batch 5 - Flacfetch audio search for remote CLI
Add support for searching and downloading audio by artist+title in remote mode,
enabling the same functionality as the local CLI's flacfetch integration.

New features:
- `karaoke-gen-remote "Artist" "Title"` - search for audio without providing a file
- `--auto-download` flag for automatic best-quality selection
- `-y` flag also triggers auto-download mode
- Interactive mode displays search results for user selection

Backend changes:
- New AudioSearchService integrating flacfetch library
- New API endpoints: POST /api/audio-search/search, GET /api/audio-search/{job_id}/results, POST /api/audio-search/{job_id}/select
- New job statuses: searching_audio, awaiting_audio_selection, downloading_audio
- Job model extended with audio_search_artist, audio_search_title, auto_download fields

Remote CLI changes:
- Detects artist+title input without file path
- Displays search results interactively
- Handles audio source selection flow
- Supports both interactive and auto-download modes

Tests:
- 20+ unit tests for AudioSearchService and Job model fields
- Tests for state transitions and API response handling

Documentation:
- Updated BACKEND-FEATURE-PARITY-PLAN.md with batch 5 status

Version bump: 0.71.26 -> 0.71.28
2025-12-11 02:38:41 -05:00
54 changed files with 13464 additions and 181 deletions

No files matched your search

@@ -0,0 +1,717 @@
---
name: Instrumental Review UI
overview: Add an intelligent instrumental selection workflow with audio analysis, waveform visualization, playback controls, and the ability to mute sections of backing vocals to create custom instrumentals. This replaces the current text-only CLI prompt with a web UI that works for both local and remote workflows, with shared core logic for DRY/maintainable code.
todos:
- id: shared-core-module
content: Create karaoke_gen/instrumental_review/ shared module with AudioAnalyzer and AudioEditor classes (used by both local and remote)
status: completed
- id: shared-core-tests
content: Add comprehensive unit tests for shared module with >80% coverage (tests/unit/test_instrumental_review.py)
status: completed
- id: backend-services
content: Create backend service wrappers that use shared core module (audio_analysis_service.py, audio_editing_service.py)
status: completed
- id: backend-services-tests
content: Add unit tests for backend services with mocked GCS interactions (backend/tests/test_audio_services.py)
status: completed
- id: api-endpoints
content: Add new API endpoints for analysis, audio streaming, and custom instrumental creation
status: completed
- id: api-endpoints-tests
content: Add API endpoint tests with >80% coverage (backend/tests/test_instrumental_api.py)
status: completed
- id: render-worker-integration
content: Integrate audio analysis into render_video_worker before transitioning to awaiting_instrumental_selection
status: completed
- id: render-worker-tests
content: Add/update render_video_worker tests to cover new analysis integration
status: completed
- id: frontend-components
content: Create React components (WaveformDisplay, AudioPlayer, RegionSelector, InstrumentalReviewPage)
status: completed
- id: local-cli-integration
content: Update local gen_cli.py to use shared core module with local file paths (feature parity with remote)
status: completed
- id: local-cli-review-server
content: Add lightweight review server to local CLI for browser-based review (similar to lyrics review pattern)
status: completed
- id: remote-cli-update
content: Update remote_cli.py to use new analysis API and open browser for review
status: completed
- id: cli-tests
content: Add CLI tests verifying feature parity between local and remote modes
status: completed
- id: integration-tests
content: Add end-to-end integration tests for the full instrumental review workflow
status: completed
---
# Intelligent Instrumental Selection Plan
## Current State
The instrumental selection workflow currently:
- Presents a simple 1/2 choice in the CLI (clean vs. with_backing)
- Requires manual inspection in Audacity to evaluate backing vocals quality
- Cannot handle the common "Scenario 3" where backing vocals need partial muting
- Has no audio preview capability in remote mode
## Target Architecture
```
┌────────────────────────────────────────────────────────────────────────────┐
│ INSTRUMENTAL REVIEW WORKFLOW │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. AUDIO ANALYSIS (automatic after render_video completes) │
│ │ │
│ ├── Analyze backing vocals stem for amplitude │
│ ├── Detect audible segments (> -40dB threshold) │
│ ├── Generate waveform visualization image │
│ └── Store analysis results in job state_data │
│ │
│ 2. AUTO-DECISION CHECK │
│ │ │
│ └── IF no audible segments detected: │
│ ├── Set recommended_selection = "clean" │
│ └── Skip to step 4 (or show minimal UI with suggestion) │
│ │
│ 3. HUMAN REVIEW (Web UI) │
│ │ │
│ ├── Display waveform with time axis │
│ ├── Show audible segment markers │
│ ├── Audio playback with waveform-click seeking │
│ ├── Toggle between: clean / with_backing / preview-custom │
│ ├── Select regions to mute (click/drag on waveform) │
│ └── Create custom instrumental if regions selected │
│ │
│ 4. SELECTION SUBMISSION │
│ │ │
│ └── POST /api/jobs/{job_id}/select-instrumental │
│ with selection = "clean" | "with_backing" | "custom" │
│ │
└────────────────────────────────────────────────────────────────────────────┘
```
## Architecture: Shared Core for DRY/SOLID
To ensure feature parity between local and remote CLIs while keeping code maintainable, we use a **shared core module** pattern:
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ SHARED CORE ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ karaoke_gen/instrumental_review/ <── SHARED CORE MODULE │
│ ├── __init__.py │
│ ├── analyzer.py # AudioAnalyzer class (pure Python, no GCS) │
│ ├── editor.py # AudioEditor class (pure Python, no GCS) │
│ ├── waveform.py # WaveformGenerator class (matplotlib) │
│ └── models.py # Pydantic models: AnalysisResult, MuteRegion │
│ │
│ ┌─────────────────────┐ ┌──────────────────────┐ │
│ │ LOCAL CLI │ │ REMOTE BACKEND │ │
│ │ (karaoke-gen) │ │ (Cloud Run) │ │
│ ├─────────────────────┤ ├──────────────────────┤ │
│ │ │ │ │ │
│ │ gen_cli.py │ │ audio_analysis_ │ │
│ │ └── uses shared ───┼──────────────┼──► service.py │ │
│ │ core directly │ │ └── wraps shared│ │
│ │ with local │ │ core with │ │
│ │ file paths │ │ GCS I/O │ │
│ │ │ │ │ │
│ │ local_review_ │ │ audio_editing_ │ │
│ │ server.py │ │ service.py │ │
│ │ └── serves same ───┼──────────────┼──► (same pattern) │ │
│ │ React UI │ │ │ │
│ │ │ │ │ │
│ └─────────────────────┘ └──────────────────────┘ │
│ │
│ BENEFITS: │
│ ✓ Single source of truth for analysis logic │
│ ✓ Bug fixes apply to both local and remote │
│ ✓ Easy to test core logic without GCS mocks │
│ ✓ Backend services are thin wrappers (Single Responsibility) │
│ ✓ Same React UI served by both local server and Cloud Run │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### Shared Core Module Design
```python
# karaoke_gen/instrumental_review/analyzer.py
class AudioAnalyzer:
"""
Analyzes audio files for backing vocals content.
Pure Python - no cloud dependencies. Works with local file paths.
"""
def __init__(self, silence_threshold_db: float = -40.0,
min_segment_duration_ms: int = 100):
self.silence_threshold_db = silence_threshold_db
self.min_segment_duration_ms = min_segment_duration_ms
def analyze(self, audio_path: str) -> AnalysisResult:
"""Analyze audio file and return structured result."""
...
def get_amplitude_envelope(self, audio_path: str,
window_ms: int = 100) -> List[float]:
"""Get amplitude envelope for waveform rendering."""
...
# karaoke_gen/instrumental_review/editor.py
class AudioEditor:
"""
Creates custom instrumentals by muting regions of backing vocals.
Pure Python - no cloud dependencies.
"""
def create_custom_instrumental(
self,
clean_instrumental_path: str,
backing_vocals_path: str,
mute_regions: List[MuteRegion],
output_path: str
) -> str:
"""Create custom instrumental with muted regions."""
...
# karaoke_gen/instrumental_review/waveform.py
class WaveformGenerator:
"""Generates waveform visualization images."""
def generate(self, audio_path: str, output_path: str,
segments: List[AudibleSegment] = None,
width: int = 1200, height: int = 200) -> str:
"""Generate waveform PNG with optional segment highlighting."""
...
```
## Implementation Components
### 1. Shared Core Module (karaoke_gen/instrumental_review/)
Create the shared module first - this is the foundation:
```python
# karaoke_gen/instrumental_review/models.py
from pydantic import BaseModel
from typing import List, Optional
from enum import Enum
class RecommendedSelection(str, Enum):
CLEAN = "clean"
WITH_BACKING = "with_backing"
REVIEW_NEEDED = "review_needed"
class AudibleSegment(BaseModel):
start_seconds: float
end_seconds: float
duration_seconds: float
avg_amplitude_db: float
class MuteRegion(BaseModel):
start_seconds: float
end_seconds: float
class AnalysisResult(BaseModel):
has_audible_content: bool
total_duration_seconds: float
audible_segments: List[AudibleSegment]
recommended_selection: RecommendedSelection
waveform_data: Optional[List[float]] = None # For JSON API response
```
### 2. Backend Service Wrappers
Create `backend/services/audio_analysis_service.py`:
```python
# Key functionality:
- analyze_backing_vocals(audio_path) -> AnalysisResult
- Uses pydub for audio loading
- Calculates RMS amplitude in dB across time windows
- Detects audible segments (contiguous regions > threshold)
- Returns: {
"has_audible_content": bool,
"total_duration_seconds": float,
"audible_segments": [
{"start_seconds": float, "end_seconds": float,
"duration_seconds": float, "avg_amplitude_db": float}
],
"recommended_selection": "clean" | "with_backing" | "review_needed"
}
- generate_waveform_image(audio_path, output_path, segments=None) -> str
- Uses matplotlib to render amplitude envelope over time
- Highlights audible segments with different colors
- Returns path to generated PNG image
```
### 2. Audio Editing Service
Create `backend/services/audio_editing_service.py`:
```python
# Key functionality:
- create_custom_instrumental(
clean_instrumental_path: str,
backing_vocals_path: str,
mute_regions: List[Tuple[float, float]], # [(start_s, end_s), ...]
output_path: str
) -> str
- Loads backing vocals
- Applies silence to mute_regions
- Mixes with clean instrumental
- Saves as new FLAC file
```
### 3. Backend API Endpoints
Add to `backend/api/routes/jobs.py`:
```python
GET /api/jobs/{job_id}/instrumental-analysis
# Returns analysis data + waveform URL
GET /api/jobs/{job_id}/audio-stream/{stem_type}
# Stream audio for playback (clean, backing_vocals, combined)
POST /api/jobs/{job_id}/create-custom-instrumental
# Body: {"mute_regions": [[0.5, 2.3], [45.0, 48.5]]}
# Creates custom instrumental, updates job state
POST /api/jobs/{job_id}/select-instrumental
# Extended to accept: "clean" | "with_backing" | "custom"
```
### 4. Frontend Web UI
Create `frontend/app/jobs/[id]/instrumental-review/page.tsx`:
```
Components needed:
- WaveformDisplay: SVG/Canvas waveform with time axis
- AudioPlayer: HTML5 audio with controls + waveform sync
- RegionSelector: Click/drag to select mute regions
- InstrumentalOptions: Radio buttons for clean/backing/custom
- SegmentList: Table showing detected audible segments
```
Key interactions:
- Click on waveform to seek playback position
- Drag on waveform to select mute region
- Toggle audio source (clean/backing/preview)
- Submit selection
### 5. Backend Worker Updates
Modify `backend/workers/render_video_worker.py`:
```python
# After video render completes, before transitioning to AWAITING_INSTRUMENTAL_SELECTION:
1. Download backing_vocals stem
2. Run audio analysis
3. Generate waveform image
4. Upload waveform to GCS
5. Store analysis results in job.state_data
6. If no audible content: set recommended_selection = "clean"
7. Transition to AWAITING_INSTRUMENTAL_SELECTION
```
### 6. CLI Updates
Modify `karaoke_gen/utils/remote_cli.py`:
```python
def handle_instrumental_selection(self, job_id: str):
# Get analysis data
analysis = self.client.get_instrumental_analysis(job_id)
# If no backing vocals detected, suggest auto-select
if analysis['recommended_selection'] == 'clean':
if self.config.non_interactive:
# Auto-select clean
self.client.select_instrumental(job_id, 'clean')
return
else:
# Show suggestion, offer to open browser for verification
self.logger.info("No backing vocals detected - recommending clean instrumental")
# Open browser anyway so user can verify if desired
# Open browser to instrumental review UI
self.open_instrumental_review_ui(job_id)
# Poll until selection made
while job.status == 'awaiting_instrumental_selection':
time.sleep(self.config.poll_interval)
```
### 7. Local CLI Integration (Feature Parity)
The local CLI (`karaoke-gen`) uses the **same shared core module** as the backend:
```python
# karaoke_gen/utils/gen_cli.py - Updated instrumental selection flow
def handle_instrumental_selection(self, output_dir: str, base_name: str):
"""Handle instrumental selection using shared core module."""
from karaoke_gen.instrumental_review import AudioAnalyzer, WaveformGenerator
# Paths to local files (already exist from audio separation)
backing_vocals_path = os.path.join(output_dir, "stems",
f"{base_name} (Backing Vocals ...).flac")
clean_instrumental_path = os.path.join(output_dir, "stems",
f"{base_name} (Instrumental ...).flac")
# Use SAME analyzer as backend
analyzer = AudioAnalyzer(silence_threshold_db=-40.0)
analysis = analyzer.analyze(backing_vocals_path)
# Generate waveform locally
waveform_path = os.path.join(output_dir, "backing_vocals_waveform.png")
WaveformGenerator().generate(backing_vocals_path, waveform_path,
analysis.audible_segments)
if not analysis.has_audible_content:
self.logger.info("No backing vocals detected - using clean instrumental")
if not self.non_interactive:
# Offer to open browser for verification
...
return "clean"
# Start local review server (serves same React UI)
from karaoke_gen.instrumental_review.server import InstrumentalReviewServer
server = InstrumentalReviewServer(
output_dir=output_dir,
base_name=base_name,
analysis=analysis,
waveform_path=waveform_path,
)
server.start_and_open_browser() # Blocking until user submits selection
return server.get_selection()
```
### 8. Local Review Server
Create `karaoke_gen/instrumental_review/server.py`:
```python
"""
Lightweight local server for instrumental review.
Serves the same React frontend used by the cloud backend.
Similar pattern to LyricsTranscriber's ReviewServer.
"""
from http.server import HTTPServer, SimpleHTTPRequestHandler
import json
import threading
class InstrumentalReviewServer:
"""
Local HTTP server for instrumental review UI.
Endpoints:
- GET /api/analysis - Returns analysis data
- GET /api/audio/{type} - Streams audio files
- GET /api/waveform - Returns waveform image
- POST /api/create-custom - Creates custom instrumental
- POST /api/select - Submits selection
- GET /* - Serves React frontend static files
"""
def __init__(self, output_dir: str, base_name: str,
analysis: AnalysisResult, waveform_path: str):
...
def start_and_open_browser(self, port: int = 8765):
"""Start server, open browser, block until selection submitted."""
...
def get_selection(self) -> str:
"""Get the user's selection after browser submission."""
...
```
## Testing Strategy
### Test Coverage Requirements
All new code must meet the project's **70% minimum coverage** requirement, with critical paths targeting **>80%**:
| Module | Target Coverage | Test File |
|--------|----------------|-----------|
| `karaoke_gen/instrumental_review/analyzer.py` | >90% | `tests/unit/test_instrumental_analyzer.py` |
| `karaoke_gen/instrumental_review/editor.py` | >90% | `tests/unit/test_instrumental_editor.py` |
| `karaoke_gen/instrumental_review/waveform.py` | >80% | `tests/unit/test_instrumental_waveform.py` |
| `karaoke_gen/instrumental_review/server.py` | >70% | `tests/unit/test_instrumental_server.py` |
| `backend/services/audio_analysis_service.py` | >80% | `backend/tests/test_audio_analysis_service.py` |
| `backend/services/audio_editing_service.py` | >80% | `backend/tests/test_audio_editing_service.py` |
| `backend/api/routes/jobs.py` (new endpoints) | >80% | `backend/tests/test_instrumental_api.py` |
### Test Categories
**1. Unit Tests (Shared Core) - tests/unit/test_instrumental_*.py**
```python
# tests/unit/test_instrumental_analyzer.py
class TestAudioAnalyzer:
def test_analyze_silent_audio_returns_no_audible_content(self):
"""Silent audio should return has_audible_content=False."""
def test_analyze_audio_with_content_detects_segments(self):
"""Audio with content should detect audible segments."""
def test_segment_detection_respects_threshold(self):
"""Segments below threshold should not be detected."""
def test_segment_merging_for_close_segments(self):
"""Close segments should be merged into one."""
def test_recommended_selection_clean_for_silent(self):
"""Silent audio should recommend 'clean'."""
def test_recommended_selection_review_for_content(self):
"""Audio with content should recommend 'review_needed'."""
# tests/unit/test_instrumental_editor.py
class TestAudioEditor:
def test_mute_single_region(self):
"""Single mute region should be applied correctly."""
def test_mute_multiple_regions(self):
"""Multiple mute regions should all be applied."""
def test_mute_region_boundaries(self):
"""Mute region at start/end of audio should work."""
def test_output_format_is_flac(self):
"""Output should be FLAC format."""
def test_combines_with_clean_instrumental(self):
"""Result should be backing vocals mixed with clean instrumental."""
```
**2. Unit Tests (Backend Services) - backend/tests/test_audio_*_service.py**
```python
# backend/tests/test_audio_analysis_service.py
class TestAudioAnalysisService:
@pytest.fixture
def mock_storage(self):
"""Mock GCS storage service."""
def test_analyze_downloads_from_gcs(self, mock_storage):
"""Service should download audio from GCS before analysis."""
def test_analyze_uploads_waveform_to_gcs(self, mock_storage):
"""Service should upload waveform image to GCS."""
def test_analyze_updates_job_state_data(self, mock_storage):
"""Service should store analysis in job.state_data."""
```
**3. API Endpoint Tests - backend/tests/test_instrumental_api.py**
```python
# backend/tests/test_instrumental_api.py
class TestInstrumentalAnalysisEndpoint:
def test_get_analysis_returns_data(self, client, mock_job):
"""GET /instrumental-analysis should return analysis data."""
def test_get_analysis_requires_correct_status(self, client, mock_job):
"""Should return 400 if job not in correct status."""
class TestAudioStreamEndpoint:
def test_stream_backing_vocals(self, client, mock_job):
"""Should stream backing vocals audio."""
def test_stream_clean_instrumental(self, client, mock_job):
"""Should stream clean instrumental audio."""
class TestCreateCustomInstrumental:
def test_create_with_mute_regions(self, client, mock_job):
"""Should create custom instrumental with mute regions."""
def test_validates_mute_regions(self, client, mock_job):
"""Should validate mute region boundaries."""
```
**4. Integration Tests - tests/integration/test_instrumental_review.py**
```python
# tests/integration/test_instrumental_review_flow.py
class TestInstrumentalReviewFlow:
"""End-to-end tests for instrumental review workflow."""
def test_full_flow_clean_selection(self):
"""Test complete flow: analysis -> review -> select clean."""
def test_full_flow_with_backing_selection(self):
"""Test complete flow: analysis -> review -> select with_backing."""
def test_full_flow_custom_creation(self):
"""Test complete flow: analysis -> mute regions -> custom."""
def test_auto_recommend_clean_for_silent_backing(self):
"""When no backing vocals, should recommend clean."""
```
**5. CLI Feature Parity Tests - tests/unit/test_cli_feature_parity.py**
```python
# tests/unit/test_cli_feature_parity.py
class TestCLIFeatureParity:
"""Verify local and remote CLIs have equivalent functionality."""
def test_both_clis_use_same_analyzer(self):
"""Both CLIs should use AudioAnalyzer from shared module."""
def test_both_clis_support_custom_instrumental(self):
"""Both CLIs should support creating custom instrumentals."""
def test_analysis_results_identical(self):
"""Same audio should produce identical analysis from both CLIs."""
```
### Test Data
Create test fixtures in `tests/data/instrumental_review/`:
- `silent_backing_vocals.flac` - Silent/near-silent audio (~10s)
- `backing_vocals_with_content.flac` - Audio with clear backing vocals (~30s)
- `backing_vocals_mixed_quality.flac` - Audio with some good/some bad sections (~30s)
Use pydub to programmatically generate these in `tests/conftest.py` fixtures.
## File Changes Summary
| Category | Files to Create/Modify |
|----------|------------------------|
| **Shared Core** | `karaoke_gen/instrumental_review/__init__.py` (new) |
| Shared Core | `karaoke_gen/instrumental_review/models.py` (new) |
| Shared Core | `karaoke_gen/instrumental_review/analyzer.py` (new) |
| Shared Core | `karaoke_gen/instrumental_review/editor.py` (new) |
| Shared Core | `karaoke_gen/instrumental_review/waveform.py` (new) |
| Shared Core | `karaoke_gen/instrumental_review/server.py` (new) |
| **Backend Services** | `backend/services/audio_analysis_service.py` (new) |
| Backend Services | `backend/services/audio_editing_service.py` (new) |
| **API** | `backend/api/routes/jobs.py` (modify - add endpoints) |
| API | `backend/api/routes/instrumental.py` (new - if endpoints get large) |
| **Workers** | `backend/workers/render_video_worker.py` (modify) |
| **Models** | `backend/models/job.py` (add analysis fields to state_data) |
| **Frontend** | `frontend/app/jobs/[id]/instrumental-review/page.tsx` (new) |
| Frontend | `frontend/components/waveform-display.tsx` (new) |
| Frontend | `frontend/components/audio-player-with-waveform.tsx` (new) |
| Frontend | `frontend/components/region-selector.tsx` (new) |
| **Local CLI** | `karaoke_gen/utils/gen_cli.py` (modify) |
| **Remote CLI** | `karaoke_gen/utils/remote_cli.py` (modify) |
| **Tests - Shared** | `tests/unit/test_instrumental_analyzer.py` (new) |
| Tests - Shared | `tests/unit/test_instrumental_editor.py` (new) |
| Tests - Shared | `tests/unit/test_instrumental_waveform.py` (new) |
| Tests - Shared | `tests/unit/test_instrumental_server.py` (new) |
| **Tests - Backend** | `backend/tests/test_audio_analysis_service.py` (new) |
| Tests - Backend | `backend/tests/test_audio_editing_service.py` (new) |
| Tests - Backend | `backend/tests/test_instrumental_api.py` (new) |
| **Tests - Parity** | `tests/unit/test_cli_feature_parity.py` (new) |
| **Tests - Integration** | `tests/integration/test_instrumental_review.py` (new) |
| **Test Data** | `tests/conftest.py` (modify - add fixtures) |
## Dependencies
Already available in `pyproject.toml`:
- `pydub>=0.25.1` - Audio loading and manipulation
- `matplotlib>=3` - Waveform visualization
- `numpy>=2` - Audio array processing
Frontend:
- React/Next.js (existing)
- HTML5 Audio API (native)
- Canvas or SVG for waveform (native)
## Implementation Order
Execute in this order to enable incremental testing:
### Phase 1: Shared Core Module (Foundation)
1. Create `karaoke_gen/instrumental_review/` package with models, analyzer, editor, waveform
2. Add comprehensive unit tests for shared core (>90% coverage)
3. Create test audio fixtures in `tests/conftest.py`
### Phase 2: Backend Integration
4. Create backend service wrappers with GCS integration
5. Add backend service unit tests with mocked GCS
6. Add new API endpoints to `backend/api/routes/jobs.py`
7. Add API endpoint tests
8. Integrate analysis into `render_video_worker.py`
9. Update render worker tests
### Phase 3: Frontend
10. Create React components (WaveformDisplay, AudioPlayer, RegionSelector)
11. Create instrumental review page
12. Test frontend manually with backend
### Phase 4: CLI Integration
13. Update `remote_cli.py` to use new analysis API and open browser
14. Create local review server `karaoke_gen/instrumental_review/server.py`
15. Update `gen_cli.py` to use shared core and local server
16. Add CLI feature parity tests
### Phase 5: Integration Testing
17. Add end-to-end integration tests
18. Manual testing of full workflow (local and remote)
### Verification Checklist
- [ ] All unit tests pass: `pytest tests/unit/ -v`
- [ ] All backend tests pass: `pytest backend/tests/ -v`
- [ ] Coverage meets 70% minimum: `pytest --cov=karaoke_gen --cov-fail-under=70`
- [ ] Local CLI works: `karaoke-gen "Artist" "Title"` (reaches instrumental selection)
- [ ] Remote CLI works: `karaoke-gen-remote ./audio.flac "Artist" "Title"`
- [ ] Both CLIs produce identical analysis for same audio
- [ ] Custom instrumental creation works in both modes
- [ ] Version bumped in `pyproject.toml`
+543
View File
@@ -0,0 +1,543 @@
"""
Audio search API routes for artist+title search mode.
This module provides endpoints for:
1. Creating a job with audio search (artist+title without file)
2. Getting search results for a job
3. Selecting an audio source to download
The flow is:
1. POST /api/audio-search/search - Create job and search for audio
2. GET /api/audio-search/{job_id}/results - Get search results
3. POST /api/audio-search/{job_id}/select - Select audio source
"""
import asyncio
import logging
import os
import tempfile
from typing import Optional, List, Dict, Any
from fastapi import APIRouter, HTTPException, BackgroundTasks, Request
from pydantic import BaseModel, Field
from backend.models.job import JobCreate, JobStatus
from backend.services.job_manager import JobManager
from backend.services.storage_service import StorageService
from backend.services.worker_service import get_worker_service
from backend.services.credential_manager import get_credential_manager, CredentialStatus
from backend.services.audio_search_service import (
get_audio_search_service,
AudioSearchResult,
AudioSearchError,
NoResultsError,
DownloadError,
)
from backend.config import get_settings
from backend.version import VERSION
logger = logging.getLogger(__name__)
router = APIRouter(tags=["audio-search"])
# Initialize services
job_manager = JobManager()
storage_service = StorageService()
worker_service = get_worker_service()
# ============================================================================
# Pydantic models
# ============================================================================
class AudioSearchRequest(BaseModel):
"""Request to search for audio by artist and title."""
artist: str = Field(..., description="Artist name to search for")
title: str = Field(..., description="Song title to search for")
# Auto-download mode
auto_download: bool = Field(False, description="Automatically select best result and download")
# Processing options
enable_cdg: bool = Field(True, description="Generate CDG+MP3 package")
enable_txt: bool = Field(True, description="Generate TXT+MP3 package")
# Finalisation options
brand_prefix: Optional[str] = Field(None, description="Brand code prefix (e.g., NOMAD)")
enable_youtube_upload: bool = Field(False, description="Upload to YouTube")
youtube_description: Optional[str] = Field(None, description="YouTube video description text")
discord_webhook_url: Optional[str] = Field(None, description="Discord webhook URL for notifications")
# Distribution options
dropbox_path: Optional[str] = Field(None, description="Dropbox folder path for organized output")
gdrive_folder_id: Optional[str] = Field(None, description="Google Drive folder ID for public share uploads")
# Lyrics configuration
lyrics_artist: Optional[str] = Field(None, description="Override artist name for lyrics search")
lyrics_title: Optional[str] = Field(None, description="Override title for lyrics search")
subtitle_offset_ms: int = Field(0, description="Subtitle timing offset in milliseconds")
# Audio separation model configuration
clean_instrumental_model: Optional[str] = Field(None, description="Model for clean instrumental separation")
backing_vocals_models: Optional[List[str]] = Field(None, description="Models for backing vocals separation")
other_stems_models: Optional[List[str]] = Field(None, description="Models for other stems")
class AudioSearchResultResponse(BaseModel):
"""A single audio search result."""
index: int
title: str
artist: str
provider: str
url: str
duration: Optional[int] = None
quality: Optional[str] = None
source_id: Optional[str] = None
class AudioSearchResponse(BaseModel):
"""Response from audio search."""
status: str
job_id: str
message: str
results: Optional[List[AudioSearchResultResponse]] = None
results_count: int = 0
auto_download: bool = False
server_version: str
class AudioSelectRequest(BaseModel):
"""Request to select an audio source."""
selection_index: int = Field(..., description="Index of the selected audio source from search results")
class AudioSelectResponse(BaseModel):
"""Response from audio source selection."""
status: str
job_id: str
message: str
selected_index: int
selected_title: str
selected_artist: str
selected_provider: str
def extract_request_metadata(request: Request, created_from: str = "audio_search") -> Dict[str, Any]:
"""Extract metadata from request for job tracking."""
headers = dict(request.headers)
client_ip = headers.get('x-forwarded-for', '').split(',')[0].strip()
if not client_ip and request.client:
client_ip = request.client.host
user_agent = headers.get('user-agent', '')
environment = headers.get('x-environment', '')
client_id = headers.get('x-client-id', '')
custom_headers = {}
for key, value in headers.items():
if key.lower().startswith('x-') and key.lower() not in ('x-forwarded-for', 'x-forwarded-proto', 'x-forwarded-host'):
custom_headers[key] = value
return {
'client_ip': client_ip,
'user_agent': user_agent,
'environment': environment,
'client_id': client_id,
'server_version': VERSION,
'created_from': created_from,
'custom_headers': custom_headers,
}
async def _trigger_workers_parallel(job_id: str) -> None:
"""Trigger both audio and lyrics workers in parallel."""
await asyncio.gather(
worker_service.trigger_audio_worker(job_id),
worker_service.trigger_lyrics_worker(job_id)
)
async def _download_and_start_processing(
job_id: str,
selection_index: int,
audio_search_service,
background_tasks: BackgroundTasks,
) -> Dict[str, Any]:
"""
Download selected audio and start job processing.
This is called either:
- Immediately after search if auto_download=True
- When user calls the select endpoint
"""
job = job_manager.get_job(job_id)
if not job:
raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
# Get search results from state_data
search_results = job.state_data.get('audio_search_results', [])
if not search_results:
raise HTTPException(status_code=400, detail="No search results available")
if selection_index < 0 or selection_index >= len(search_results):
raise HTTPException(
status_code=400,
detail=f"Invalid selection index {selection_index}. Valid range: 0-{len(search_results)-1}"
)
selected = search_results[selection_index]
# Transition to downloading state
job_manager.transition_to_state(
job_id=job_id,
new_status=JobStatus.DOWNLOADING_AUDIO,
progress=10,
message=f"Downloading from {selected['provider']}: {selected['artist']} - {selected['title']}",
state_data_updates={
'selected_audio_index': selection_index,
'selected_audio_provider': selected['provider'],
}
)
try:
# Download to temp directory
temp_dir = tempfile.mkdtemp(prefix=f"audio_download_{job_id}_")
result = audio_search_service.download(
result_index=selection_index,
output_dir=temp_dir,
)
# Upload to GCS
filename = os.path.basename(result.filepath)
audio_gcs_path = f"uploads/{job_id}/audio/{filename}"
with open(result.filepath, 'rb') as f:
storage_service.upload_fileobj(
f,
audio_gcs_path,
content_type='audio/flac' # flacfetch typically returns FLAC
)
logger.info(f"Uploaded audio to GCS: {audio_gcs_path}")
# Clean up temp file
try:
os.remove(result.filepath)
os.rmdir(temp_dir)
except Exception as e:
logger.warning(f"Failed to clean up temp files: {e}")
# Update job with GCS path and transition to DOWNLOADING
job_manager.update_job(job_id, {
'input_media_gcs_path': audio_gcs_path,
'filename': filename,
})
job_manager.transition_to_state(
job_id=job_id,
new_status=JobStatus.DOWNLOADING,
progress=15,
message="Audio downloaded, starting processing"
)
# Trigger workers
background_tasks.add_task(_trigger_workers_parallel, job_id)
return {
'selected_index': selection_index,
'selected_title': selected['title'],
'selected_artist': selected['artist'],
'selected_provider': selected['provider'],
}
except DownloadError as e:
job_manager.fail_job(job_id, f"Audio download failed: {e}")
raise HTTPException(status_code=500, detail=f"Download failed: {e}")
except Exception as e:
job_manager.fail_job(job_id, f"Audio download failed: {e}")
raise HTTPException(status_code=500, detail=f"Download failed: {e}")
@router.post("/audio-search/search", response_model=AudioSearchResponse)
async def search_audio(
request: Request,
background_tasks: BackgroundTasks,
body: AudioSearchRequest,
):
"""
Search for audio by artist and title, creating a new job.
This endpoint:
1. Creates a job in PENDING state
2. Searches for audio using flacfetch
3. Either returns search results for user selection, or
4. If auto_download=True, automatically selects best and starts processing
Use cases:
- Interactive mode (default): Returns results, user calls /select endpoint
- Auto mode (auto_download=True): Automatically selects and downloads best
"""
try:
# Apply default distribution settings
settings = get_settings()
effective_dropbox_path = body.dropbox_path or settings.default_dropbox_path
effective_gdrive_folder_id = body.gdrive_folder_id or settings.default_gdrive_folder_id
effective_discord_webhook_url = body.discord_webhook_url or settings.default_discord_webhook_url
# Validate credentials if distribution services are requested
invalid_services = []
credential_manager = get_credential_manager()
if body.enable_youtube_upload:
result = credential_manager.check_youtube_credentials()
if result.status != CredentialStatus.VALID:
invalid_services.append(f"youtube ({result.message})")
if effective_dropbox_path:
result = credential_manager.check_dropbox_credentials()
if result.status != CredentialStatus.VALID:
invalid_services.append(f"dropbox ({result.message})")
if effective_gdrive_folder_id:
result = credential_manager.check_gdrive_credentials()
if result.status != CredentialStatus.VALID:
invalid_services.append(f"gdrive ({result.message})")
if invalid_services:
raise HTTPException(
status_code=400,
detail={
"error": "credentials_invalid",
"message": f"Distribution services need re-authorization: {', '.join(invalid_services)}",
"invalid_services": invalid_services,
}
)
# Extract request metadata
request_metadata = extract_request_metadata(request, created_from="audio_search")
# Create job
job_create = JobCreate(
artist=body.artist,
title=body.title,
enable_cdg=body.enable_cdg,
enable_txt=body.enable_txt,
brand_prefix=body.brand_prefix,
enable_youtube_upload=body.enable_youtube_upload,
youtube_description=body.youtube_description,
discord_webhook_url=effective_discord_webhook_url,
dropbox_path=effective_dropbox_path,
gdrive_folder_id=effective_gdrive_folder_id,
lyrics_artist=body.lyrics_artist,
lyrics_title=body.lyrics_title,
subtitle_offset_ms=body.subtitle_offset_ms,
clean_instrumental_model=body.clean_instrumental_model,
backing_vocals_models=body.backing_vocals_models,
other_stems_models=body.other_stems_models,
audio_search_artist=body.artist,
audio_search_title=body.title,
auto_download=body.auto_download,
request_metadata=request_metadata,
)
job = job_manager.create_job(job_create)
job_id = job.job_id
logger.info(f"Created job {job_id} for audio search: {body.artist} - {body.title}")
# Update job with audio search fields
job_manager.update_job(job_id, {
'audio_search_artist': body.artist,
'audio_search_title': body.title,
'auto_download': body.auto_download,
})
# Transition to searching state
job_manager.transition_to_state(
job_id=job_id,
new_status=JobStatus.SEARCHING_AUDIO,
progress=5,
message=f"Searching for: {body.artist} - {body.title}"
)
# Perform search
audio_search_service = get_audio_search_service()
try:
search_results = audio_search_service.search(body.artist, body.title)
except NoResultsError as e:
job_manager.fail_job(job_id, f"No audio sources found for: {body.artist} - {body.title}")
raise HTTPException(
status_code=404,
detail={
"error": "no_results",
"message": str(e),
"job_id": job_id,
}
)
except AudioSearchError as e:
job_manager.fail_job(job_id, f"Audio search failed: {e}")
raise HTTPException(status_code=500, detail=f"Search failed: {e}")
# Store results in job state_data
results_dicts = [r.to_dict() for r in search_results]
job_manager.update_job(job_id, {
'state_data': {
'audio_search_results': results_dicts,
'audio_search_count': len(results_dicts),
}
})
# If auto_download, select best and start processing
if body.auto_download:
best_index = audio_search_service.select_best(search_results)
logger.info(f"Auto-download enabled, selecting result {best_index}")
selection_info = await _download_and_start_processing(
job_id=job_id,
selection_index=best_index,
audio_search_service=audio_search_service,
background_tasks=background_tasks,
)
return AudioSearchResponse(
status="success",
job_id=job_id,
message=f"Audio found and download started: {selection_info['selected_artist']} - {selection_info['selected_title']} ({selection_info['selected_provider']})",
results=None, # Don't return results in auto mode
results_count=len(search_results),
auto_download=True,
server_version=VERSION,
)
# Interactive mode: return results for user selection
job_manager.transition_to_state(
job_id=job_id,
new_status=JobStatus.AWAITING_AUDIO_SELECTION,
progress=10,
message=f"Found {len(search_results)} audio sources. Waiting for selection."
)
# Convert to response format
result_responses = [
AudioSearchResultResponse(
index=r.index,
title=r.title,
artist=r.artist,
provider=r.provider,
url=r.url,
duration=r.duration,
quality=r.quality,
source_id=r.source_id,
)
for r in search_results
]
return AudioSearchResponse(
status="awaiting_selection",
job_id=job_id,
message=f"Found {len(search_results)} audio sources. Call /api/audio-search/{job_id}/select to choose one.",
results=result_responses,
results_count=len(search_results),
auto_download=False,
server_version=VERSION,
)
except HTTPException:
raise
except Exception as e:
logger.error(f"Error in audio search: {e}", exc_info=True)
raise HTTPException(status_code=500, detail=str(e))
@router.get("/audio-search/{job_id}/results")
async def get_audio_search_results(job_id: str):
"""
Get audio search results for a job.
Returns the cached search results so user can select one.
"""
job = job_manager.get_job(job_id)
if not job:
raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
search_results = job.state_data.get('audio_search_results', [])
if not search_results:
raise HTTPException(
status_code=400,
detail="No search results available for this job"
)
return {
"status": "success",
"job_id": job_id,
"job_status": job.status,
"results": search_results,
"results_count": len(search_results),
}
@router.post("/audio-search/{job_id}/select", response_model=AudioSelectResponse)
async def select_audio_source(
job_id: str,
background_tasks: BackgroundTasks,
body: AudioSelectRequest,
):
"""
Select an audio source and start job processing.
This endpoint:
1. Validates the job is awaiting selection
2. Downloads the selected audio
3. Uploads to GCS
4. Triggers audio and lyrics workers
"""
job = job_manager.get_job(job_id)
if not job:
raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
# Verify job is awaiting selection
if job.status != JobStatus.AWAITING_AUDIO_SELECTION:
raise HTTPException(
status_code=400,
detail=f"Job is not awaiting audio selection (status: {job.status})"
)
# Re-instantiate the audio search service (it caches raw results from search)
# For production, we'd need to re-search or store raw results differently
audio_search_service = get_audio_search_service()
# Re-run search to populate the cache
# This is necessary because the service caches raw results in memory
search_results = job.state_data.get('audio_search_results', [])
if not search_results:
raise HTTPException(status_code=400, detail="No search results cached for this job")
artist = job.audio_search_artist or job.artist
title = job.audio_search_title or job.title
try:
# Re-search to populate cache
audio_search_service.search(artist, title)
except Exception as e:
logger.warning(f"Re-search failed, trying direct download: {e}")
selection_info = await _download_and_start_processing(
job_id=job_id,
selection_index=body.selection_index,
audio_search_service=audio_search_service,
background_tasks=background_tasks,
)
return AudioSelectResponse(
status="success",
job_id=job_id,
message="Audio selected and download started",
selected_index=selection_info['selected_index'],
selected_title=selection_info['selected_title'],
selected_artist=selection_info['selected_artist'],
selected_provider=selection_info['selected_provider'],
)
+307 -1
View File
@@ -19,7 +19,8 @@ from backend.models.requests import (
CorrectionsSubmission,
InstrumentalSelection,
StartReviewRequest,
CancelJobRequest
CancelJobRequest,
CreateCustomInstrumentalRequest,
)
from backend.services.job_manager import JobManager
from backend.services.worker_service import get_worker_service
@@ -523,6 +524,311 @@ async def get_instrumental_options(job_id: str) -> Dict[str, Any]:
}
@router.get("/{job_id}/instrumental-analysis")
async def get_instrumental_analysis(job_id: str) -> Dict[str, Any]:
"""
Get audio analysis data for instrumental selection.
Returns:
- Analysis of backing vocals (audible segments, recommendation)
- Waveform image URL
- Audio stream URLs for playback
This endpoint enables intelligent instrumental selection by providing
detailed analysis of the backing vocals track.
"""
job = job_manager.get_job(job_id)
if not job:
raise HTTPException(status_code=404, detail="Job not found")
if job.status != JobStatus.AWAITING_INSTRUMENTAL_SELECTION:
raise HTTPException(
status_code=400,
detail=f"Job not ready for instrumental analysis (current status: {job.status})"
)
storage = StorageService()
# Get analysis from state_data (populated by render_video_worker)
analysis_data = job.state_data.get('backing_vocals_analysis', {})
# Get URLs
stems = job.file_urls.get('stems', {})
analysis_files = job.file_urls.get('analysis', {})
clean_url = stems.get('instrumental_clean')
backing_vocals_url = stems.get('backing_vocals')
with_backing_url = stems.get('instrumental_with_backing')
waveform_url = analysis_files.get('backing_vocals_waveform')
custom_instrumental_url = stems.get('instrumental_custom')
# Build response
response = {
"job_id": job_id,
"artist": job.artist,
"title": job.title,
"status": job.status,
# Analysis results
"analysis": {
"has_audible_content": analysis_data.get('has_audible_content', False),
"total_duration_seconds": analysis_data.get('total_duration_seconds', 0),
"audible_segments": analysis_data.get('audible_segments', []),
"recommended_selection": analysis_data.get('recommended_selection', 'review_needed'),
"total_audible_duration_seconds": analysis_data.get('total_audible_duration_seconds', 0),
"audible_percentage": analysis_data.get('audible_percentage', 0),
"silence_threshold_db": analysis_data.get('silence_threshold_db', -40.0),
},
# Audio URLs for playback
"audio_urls": {
"clean_instrumental": storage.generate_signed_url(clean_url, expiration_minutes=120) if clean_url else None,
"backing_vocals": storage.generate_signed_url(backing_vocals_url, expiration_minutes=120) if backing_vocals_url else None,
"with_backing": storage.generate_signed_url(with_backing_url, expiration_minutes=120) if with_backing_url else None,
"custom_instrumental": storage.generate_signed_url(custom_instrumental_url, expiration_minutes=120) if custom_instrumental_url else None,
},
# Waveform image URL
"waveform_url": storage.generate_signed_url(waveform_url, expiration_minutes=120) if waveform_url else None,
# Whether a custom instrumental has been created
"has_custom_instrumental": custom_instrumental_url is not None,
}
return response
@router.get("/{job_id}/audio-stream/{stem_type}")
async def stream_audio(job_id: str, stem_type: str):
"""
Stream an audio file for playback in the browser.
Supported stem_type values:
- clean_instrumental: Clean instrumental (no backing vocals)
- backing_vocals: Backing vocals only
- with_backing: Instrumental with backing vocals
- custom_instrumental: Custom instrumental (if created)
Returns audio as a streaming response with proper headers for
browser audio playback.
"""
from fastapi.responses import StreamingResponse
import tempfile
job = job_manager.get_job(job_id)
if not job:
raise HTTPException(status_code=404, detail="Job not found")
# Map stem_type to file_urls key
stem_map = {
'clean_instrumental': ('stems', 'instrumental_clean'),
'backing_vocals': ('stems', 'backing_vocals'),
'with_backing': ('stems', 'instrumental_with_backing'),
'custom_instrumental': ('stems', 'instrumental_custom'),
}
if stem_type not in stem_map:
raise HTTPException(
status_code=400,
detail=f"Invalid stem_type. Must be one of: {list(stem_map.keys())}"
)
category, key = stem_map[stem_type]
gcs_path = job.file_urls.get(category, {}).get(key)
if not gcs_path:
raise HTTPException(
status_code=404,
detail=f"Audio file not available: {stem_type}"
)
# Determine content type
ext = gcs_path.split('.')[-1].lower()
content_types = {
'flac': 'audio/flac',
'mp3': 'audio/mpeg',
'wav': 'audio/wav',
'm4a': 'audio/mp4',
}
content_type = content_types.get(ext, 'audio/flac')
try:
storage = StorageService()
with tempfile.NamedTemporaryFile(delete=False, suffix=f'.{ext}') as tmp:
tmp_path = tmp.name
storage.download_file(gcs_path, tmp_path)
def file_iterator():
try:
with open(tmp_path, 'rb') as f:
while chunk := f.read(8192):
yield chunk
finally:
import os
os.unlink(tmp_path)
filename = gcs_path.split('/')[-1]
return StreamingResponse(
file_iterator(),
media_type=content_type,
headers={
'Content-Disposition': f'inline; filename="{filename}"',
'Accept-Ranges': 'bytes',
}
)
except Exception as e:
logger.exception(f"Error streaming audio {gcs_path}: {e}")
raise HTTPException(status_code=500, detail=f"Error streaming audio: {e}") from e
@router.post("/{job_id}/create-custom-instrumental")
async def create_custom_instrumental(
job_id: str,
request: CreateCustomInstrumentalRequest,
) -> Dict[str, Any]:
"""
Create a custom instrumental by muting regions of backing vocals.
This endpoint:
1. Takes a list of time ranges to mute in the backing vocals
2. Creates a custom instrumental (clean + muted backing vocals)
3. Stores the result and makes it available for selection
After calling this endpoint, the user can select "custom" in the
select-instrumental endpoint.
"""
from backend.services.audio_editing_service import AudioEditingService
from karaoke_gen.instrumental_review import MuteRegion
job = job_manager.get_job(job_id)
if not job:
raise HTTPException(status_code=404, detail="Job not found")
if job.status != JobStatus.AWAITING_INSTRUMENTAL_SELECTION:
raise HTTPException(
status_code=400,
detail=f"Job not ready for custom instrumental creation (current status: {job.status})"
)
# Get stem paths
stems = job.file_urls.get('stems', {})
clean_path = stems.get('instrumental_clean')
backing_path = stems.get('backing_vocals')
if not clean_path or not backing_path:
raise HTTPException(
status_code=500,
detail="Required audio files not available"
)
try:
# Convert request mute regions to model objects
mute_regions = [
MuteRegion(
start_seconds=r.start_seconds,
end_seconds=r.end_seconds
)
for r in request.mute_regions
]
# Create custom instrumental
editing_service = AudioEditingService()
# Determine output path
output_path = f"jobs/{job_id}/stems/instrumental_custom.flac"
result = editing_service.create_custom_instrumental(
gcs_clean_instrumental_path=clean_path,
gcs_backing_vocals_path=backing_path,
mute_regions=mute_regions,
gcs_output_path=output_path,
job_id=job_id,
)
# Update job file_urls with custom instrumental
job_manager.update_file_url(job_id, 'stems', 'instrumental_custom', output_path)
# Store mute regions in state_data for reference
job_manager.update_state_data(job_id, 'custom_instrumental_mute_regions', [
{"start_seconds": r.start_seconds, "end_seconds": r.end_seconds}
for r in mute_regions
])
logger.info(f"Job {job_id}: Custom instrumental created with {len(mute_regions)} mute regions")
# Generate signed URL for the new file
storage = StorageService()
return {
"status": "success",
"message": "Custom instrumental created successfully",
"custom_instrumental_url": storage.generate_signed_url(output_path, expiration_minutes=120),
"mute_regions_applied": len(result.mute_regions_applied),
"total_muted_duration_seconds": result.total_muted_duration_seconds,
"output_duration_seconds": result.output_duration_seconds,
}
except Exception as e:
logger.exception(f"Error creating custom instrumental for job {job_id}: {e}")
raise HTTPException(status_code=500, detail=str(e)) from e
@router.get("/{job_id}/waveform-data")
async def get_waveform_data(job_id: str, num_points: int = 500) -> Dict[str, Any]:
"""
Get waveform amplitude data for client-side rendering.
This endpoint returns raw amplitude data that the frontend can use
to render a waveform using Canvas or SVG, enabling interactive
features like click-to-seek.
Args:
num_points: Number of data points to return (default 500)
Returns:
{
"amplitudes": [0.1, 0.2, ...], # Normalized 0-1 values
"duration_seconds": 180.5,
"num_points": 500
}
"""
from backend.services.audio_analysis_service import AudioAnalysisService
job = job_manager.get_job(job_id)
if not job:
raise HTTPException(status_code=404, detail="Job not found")
if job.status != JobStatus.AWAITING_INSTRUMENTAL_SELECTION:
raise HTTPException(
status_code=400,
detail=f"Job not ready for waveform data (current status: {job.status})"
)
backing_vocals_path = job.file_urls.get('stems', {}).get('backing_vocals')
if not backing_vocals_path:
raise HTTPException(status_code=404, detail="Backing vocals file not found")
try:
analysis_service = AudioAnalysisService()
amplitudes, duration = analysis_service.get_waveform_data(
gcs_audio_path=backing_vocals_path,
job_id=job_id,
num_points=num_points,
)
return {
"amplitudes": amplitudes,
"duration_seconds": duration,
"num_points": len(amplitudes),
}
except Exception as e:
logger.exception(f"Error getting waveform data for job {job_id}: {e}")
raise HTTPException(status_code=500, detail=str(e)) from e
@router.post("/{job_id}/select-instrumental")
async def select_instrumental(
job_id: str,
+2 -1
View File
@@ -7,7 +7,7 @@ from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from backend.config import settings
from backend.api.routes import health, jobs, internal, file_upload, review, auth
from backend.api.routes import health, jobs, internal, file_upload, review, auth, audio_search
from backend.services.tracing import setup_tracing, instrument_app, get_current_trace_id
@@ -108,6 +108,7 @@ app.include_router(file_upload.router, prefix="/api") # File upload endpoint
app.include_router(internal.router, prefix="/api") # Internal worker endpoints
app.include_router(review.router, prefix="/api") # Review UI compatibility endpoints
app.include_router(auth.router, prefix="/api") # OAuth credential management
app.include_router(audio_search.router, prefix="/api") # Audio search (artist+title mode)
@app.get("/")
+26 -3
View File
@@ -14,8 +14,8 @@ class JobStatus(str, Enum):
"""
Job status enumeration - Complete state machine.
The workflow has 8 main stages with 2 human interaction points:
1. Input & Setup
The workflow has 8 main stages with 3 human interaction points:
1. Input & Setup (may include audio source selection)
2. Parallel Processing (audio + lyrics)
3. Title/End Screen Generation
4. Countdown Padding Synchronization
@@ -26,6 +26,12 @@ class JobStatus(str, Enum):
"""
# Initial states
PENDING = "pending" # Job created, queued for processing
# Audio search states (for artist+title search mode)
SEARCHING_AUDIO = "searching_audio" # Searching for audio sources via flacfetch
AWAITING_AUDIO_SELECTION = "awaiting_audio_selection" # ⚠️ WAITING FOR USER - select audio source
DOWNLOADING_AUDIO = "downloading_audio" # Downloading selected audio from source
DOWNLOADING = "downloading" # Downloading from URL or processing upload
# Stage 2a: Audio separation (parallel track 1)
@@ -80,7 +86,14 @@ class JobStatus(str, Enum):
# Valid state transitions
STATE_TRANSITIONS = {
JobStatus.PENDING: [JobStatus.DOWNLOADING, JobStatus.FAILED, JobStatus.CANCELLED],
# PENDING can go to DOWNLOADING (file upload) or SEARCHING_AUDIO (artist+title search)
JobStatus.PENDING: [JobStatus.DOWNLOADING, JobStatus.SEARCHING_AUDIO, JobStatus.FAILED, JobStatus.CANCELLED],
# Audio search flow (for artist+title search mode)
JobStatus.SEARCHING_AUDIO: [JobStatus.AWAITING_AUDIO_SELECTION, JobStatus.DOWNLOADING_AUDIO, JobStatus.FAILED],
JobStatus.AWAITING_AUDIO_SELECTION: [JobStatus.DOWNLOADING_AUDIO, JobStatus.FAILED, JobStatus.CANCELLED],
JobStatus.DOWNLOADING_AUDIO: [JobStatus.DOWNLOADING, JobStatus.FAILED],
# DOWNLOADING allows parallel processing (audio + lyrics) and then screens when both complete
JobStatus.DOWNLOADING: [JobStatus.SEPARATING_STAGE1, JobStatus.TRANSCRIBING, JobStatus.GENERATING_SCREENS, JobStatus.FAILED],
@@ -225,6 +238,11 @@ class Job(BaseModel):
# Existing instrumental configuration (Batch 3)
existing_instrumental_gcs_path: Optional[str] = None # GCS path to user-provided instrumental file
# Audio search configuration (Batch 5 - artist+title search mode)
audio_search_artist: Optional[str] = None # Artist name used for audio search
audio_search_title: Optional[str] = None # Title used for audio search
auto_download: bool = False # Auto-select best audio source (skip selection)
# Processing state
track_output_dir: Optional[str] = None # Local output directory (temp)
audio_hash: Optional[str] = None # Hash for deduplication
@@ -401,6 +419,11 @@ class JobCreate(BaseModel):
# Existing instrumental configuration (Batch 3)
existing_instrumental_gcs_path: Optional[str] = None # GCS path to user-provided instrumental file
# Audio search configuration (Batch 5 - artist+title search mode)
audio_search_artist: Optional[str] = None # Artist name used for audio search
audio_search_title: Optional[str] = None # Title used for audio search
auto_download: bool = False # Auto-select best audio source (skip selection)
# Request metadata (set by API endpoint from request headers)
request_metadata: Dict[str, Any] = Field(default_factory=dict)
"""
+38 -3
View File
@@ -59,19 +59,54 @@ class InstrumentalSelection(BaseModel):
Request to select instrumental audio option.
This is the second critical human-in-the-loop interaction point.
User chooses between clean instrumental or instrumental with backing vocals.
User chooses between clean instrumental, instrumental with backing vocals,
or a custom instrumental (created via create-custom-instrumental endpoint).
"""
selection: str # "clean" or "with_backing"
selection: str # "clean", "with_backing", or "custom"
@validator('selection')
def validate_selection(cls, v):
"""Validate selection is a valid option."""
valid_options = ['clean', 'with_backing']
valid_options = ['clean', 'with_backing', 'custom']
if v not in valid_options:
raise ValueError(f"Selection must be one of: {valid_options}")
return v
class MuteRegionRequest(BaseModel):
"""A region to mute in the backing vocals."""
start_seconds: float
end_seconds: float
@validator('start_seconds')
def validate_start(cls, v):
if v < 0:
raise ValueError("start_seconds must be non-negative")
return v
@validator('end_seconds')
def validate_end(cls, v, values):
if 'start_seconds' in values and v <= values['start_seconds']:
raise ValueError("end_seconds must be greater than start_seconds")
return v
class CreateCustomInstrumentalRequest(BaseModel):
"""
Request to create a custom instrumental with muted backing vocal regions.
The mute_regions specify time ranges in the backing vocals track that
should be silenced before mixing with the clean instrumental.
"""
mute_regions: List[MuteRegionRequest]
@validator('mute_regions')
def validate_regions(cls, v):
if not v:
raise ValueError("At least one mute region is required")
return v
class StartReviewRequest(BaseModel):
"""Request to mark job as in-review (user opened interface)."""
pass # No body needed, just triggers state transition
+243
View File
@@ -0,0 +1,243 @@
"""
Audio analysis service for analyzing backing vocals.
This service wraps the shared karaoke_gen.instrumental_review module
to provide GCS-integrated audio analysis capabilities.
"""
import logging
import os
import tempfile
from typing import Optional
from backend.services.storage_service import StorageService
from karaoke_gen.instrumental_review import (
AudioAnalyzer,
AnalysisResult,
WaveformGenerator,
)
logger = logging.getLogger(__name__)
class AudioAnalysisService:
"""
Service for analyzing backing vocals audio files stored in GCS.
This service acts as a thin wrapper around the shared AudioAnalyzer
and WaveformGenerator classes, handling GCS download/upload operations.
The actual analysis logic is in the shared karaoke_gen.instrumental_review
module, ensuring feature parity between local and remote workflows.
"""
def __init__(
self,
storage_service: Optional[StorageService] = None,
silence_threshold_db: float = -40.0,
min_segment_duration_ms: int = 100,
):
"""
Initialize the audio analysis service.
Args:
storage_service: GCS storage service. If not provided, a new
instance will be created.
silence_threshold_db: Threshold for considering audio as silent.
Default is -40.0 dB.
min_segment_duration_ms: Minimum duration for audible segments.
Default is 100ms.
"""
self.storage_service = storage_service or StorageService()
self.analyzer = AudioAnalyzer(
silence_threshold_db=silence_threshold_db,
min_segment_duration_ms=min_segment_duration_ms,
)
self.waveform_generator = WaveformGenerator()
def analyze_backing_vocals(
self,
gcs_audio_path: str,
job_id: str,
) -> AnalysisResult:
"""
Analyze a backing vocals audio file from GCS.
This method:
1. Downloads the audio file from GCS to a temp file
2. Runs the analysis using the shared AudioAnalyzer
3. Returns the analysis result
Args:
gcs_audio_path: Path to the audio file in GCS
job_id: Job ID for logging
Returns:
AnalysisResult containing analysis data
"""
logger.info(f"[{job_id}] Analyzing backing vocals: {gcs_audio_path}")
with tempfile.TemporaryDirectory() as temp_dir:
# Download audio file
local_audio_path = os.path.join(temp_dir, "backing_vocals.flac")
self.storage_service.download_file(gcs_audio_path, local_audio_path)
# Run analysis
result = self.analyzer.analyze(local_audio_path)
logger.info(
f"[{job_id}] Analysis complete: "
f"has_audible={result.has_audible_content}, "
f"segments={result.segment_count}, "
f"recommendation={result.recommended_selection.value}"
)
return result
def analyze_and_generate_waveform(
self,
gcs_audio_path: str,
job_id: str,
gcs_waveform_destination: str,
) -> tuple[AnalysisResult, str]:
"""
Analyze backing vocals and generate a waveform image.
This method:
1. Downloads the audio file from GCS
2. Runs analysis using AudioAnalyzer
3. Generates waveform image using WaveformGenerator
4. Uploads the waveform image to GCS
5. Returns analysis result and waveform GCS path
Args:
gcs_audio_path: Path to the audio file in GCS
job_id: Job ID for logging
gcs_waveform_destination: Where to upload the waveform image in GCS
Returns:
Tuple of (AnalysisResult, waveform_gcs_path)
"""
logger.info(f"[{job_id}] Analyzing and generating waveform: {gcs_audio_path}")
with tempfile.TemporaryDirectory() as temp_dir:
# Download audio file
local_audio_path = os.path.join(temp_dir, "backing_vocals.flac")
self.storage_service.download_file(gcs_audio_path, local_audio_path)
# Run analysis
result = self.analyzer.analyze(local_audio_path)
# Generate waveform
local_waveform_path = os.path.join(temp_dir, "waveform.png")
self.waveform_generator.generate(
audio_path=local_audio_path,
output_path=local_waveform_path,
segments=result.audible_segments,
show_time_axis=True,
silence_threshold_db=self.analyzer.silence_threshold_db,
)
# Upload waveform to GCS
self.storage_service.upload_file(
local_waveform_path,
gcs_waveform_destination
)
logger.info(
f"[{job_id}] Analysis and waveform generation complete. "
f"Waveform uploaded to: {gcs_waveform_destination}"
)
return result, gcs_waveform_destination
def get_waveform_data(
self,
gcs_audio_path: str,
job_id: str,
num_points: int = 500,
) -> tuple[list[float], float]:
"""
Get waveform data (amplitude envelope) for client-side rendering.
This is useful when the frontend wants to render the waveform
itself using Canvas or SVG, rather than displaying a pre-generated
image.
Args:
gcs_audio_path: Path to the audio file in GCS
job_id: Job ID for logging
num_points: Number of data points to return
Returns:
Tuple of (amplitude_values, duration_seconds)
"""
logger.info(f"[{job_id}] Getting waveform data: {gcs_audio_path}")
with tempfile.TemporaryDirectory() as temp_dir:
# Download audio file
local_audio_path = os.path.join(temp_dir, "backing_vocals.flac")
self.storage_service.download_file(gcs_audio_path, local_audio_path)
# Generate waveform data
amplitudes, duration = self.waveform_generator.generate_data_only(
audio_path=local_audio_path,
num_points=num_points,
)
return amplitudes, duration
def generate_waveform_with_mutes(
self,
gcs_audio_path: str,
job_id: str,
gcs_waveform_destination: str,
mute_regions: list,
) -> str:
"""
Generate a waveform image with mute regions highlighted.
This is useful for showing the user which regions will be muted
in the custom instrumental.
Args:
gcs_audio_path: Path to the audio file in GCS
job_id: Job ID for logging
gcs_waveform_destination: Where to upload the waveform image
mute_regions: List of MuteRegion objects to highlight
Returns:
GCS path to the uploaded waveform image
"""
from karaoke_gen.instrumental_review import MuteRegion
logger.info(
f"[{job_id}] Generating waveform with {len(mute_regions)} mute regions"
)
with tempfile.TemporaryDirectory() as temp_dir:
# Download audio file
local_audio_path = os.path.join(temp_dir, "backing_vocals.flac")
self.storage_service.download_file(gcs_audio_path, local_audio_path)
# First run analysis to get segments
result = self.analyzer.analyze(local_audio_path)
# Generate waveform with mute regions
local_waveform_path = os.path.join(temp_dir, "waveform_with_mutes.png")
self.waveform_generator.generate(
audio_path=local_audio_path,
output_path=local_waveform_path,
segments=result.audible_segments,
mute_regions=mute_regions,
show_time_axis=True,
)
# Upload to GCS
self.storage_service.upload_file(
local_waveform_path,
gcs_waveform_destination
)
return gcs_waveform_destination
+278
View File
@@ -0,0 +1,278 @@
"""
Audio editing service for creating custom instrumentals.
This service wraps the shared karaoke_gen.instrumental_review module
to provide GCS-integrated audio editing capabilities.
"""
import logging
import os
import tempfile
from typing import List, Optional
from backend.services.storage_service import StorageService
from karaoke_gen.instrumental_review import (
AudioEditor,
MuteRegion,
)
from karaoke_gen.instrumental_review.models import CustomInstrumentalResult
logger = logging.getLogger(__name__)
class AudioEditingService:
"""
Service for creating custom instrumental tracks with GCS integration.
This service acts as a thin wrapper around the shared AudioEditor
class, handling GCS download/upload operations.
The actual editing logic is in the shared karaoke_gen.instrumental_review
module, ensuring feature parity between local and remote workflows.
"""
def __init__(
self,
storage_service: Optional[StorageService] = None,
output_format: str = "flac",
):
"""
Initialize the audio editing service.
Args:
storage_service: GCS storage service. If not provided, a new
instance will be created.
output_format: Output audio format. Default is "flac".
"""
self.storage_service = storage_service or StorageService()
self.editor = AudioEditor(output_format=output_format)
def create_custom_instrumental(
self,
gcs_clean_instrumental_path: str,
gcs_backing_vocals_path: str,
mute_regions: List[MuteRegion],
gcs_output_path: str,
job_id: str,
) -> CustomInstrumentalResult:
"""
Create a custom instrumental by muting regions of backing vocals.
This method:
1. Downloads clean instrumental and backing vocals from GCS
2. Applies mute regions to backing vocals
3. Combines with clean instrumental
4. Uploads result to GCS
Args:
gcs_clean_instrumental_path: Path to clean instrumental in GCS
gcs_backing_vocals_path: Path to backing vocals in GCS
mute_regions: List of regions to mute in backing vocals
gcs_output_path: Where to upload the custom instrumental in GCS
job_id: Job ID for logging
Returns:
CustomInstrumentalResult with details about the created file
"""
logger.info(
f"[{job_id}] Creating custom instrumental with "
f"{len(mute_regions)} mute regions"
)
with tempfile.TemporaryDirectory() as temp_dir:
# Download input files
local_clean_path = os.path.join(temp_dir, "clean_instrumental.flac")
local_backing_path = os.path.join(temp_dir, "backing_vocals.flac")
local_output_path = os.path.join(temp_dir, "custom_instrumental.flac")
logger.debug(f"[{job_id}] Downloading clean instrumental")
self.storage_service.download_file(
gcs_clean_instrumental_path,
local_clean_path
)
logger.debug(f"[{job_id}] Downloading backing vocals")
self.storage_service.download_file(
gcs_backing_vocals_path,
local_backing_path
)
# Create custom instrumental using shared editor
result = self.editor.create_custom_instrumental(
clean_instrumental_path=local_clean_path,
backing_vocals_path=local_backing_path,
mute_regions=mute_regions,
output_path=local_output_path,
)
# Upload result to GCS
logger.debug(f"[{job_id}] Uploading custom instrumental to GCS")
self.storage_service.upload_file(local_output_path, gcs_output_path)
# Update result with GCS path
result.output_path = gcs_output_path
logger.info(
f"[{job_id}] Custom instrumental created: {gcs_output_path}, "
f"muted {result.total_muted_duration_seconds:.1f}s across "
f"{len(result.mute_regions_applied)} regions"
)
return result
def create_preview(
self,
gcs_clean_instrumental_path: str,
gcs_backing_vocals_path: str,
mute_regions: List[MuteRegion],
gcs_preview_path: str,
job_id: str,
preview_duration_seconds: Optional[float] = None,
) -> str:
"""
Create a preview of the custom instrumental.
This is similar to create_custom_instrumental but optimized for
quick preview generation (optionally truncated duration).
Args:
gcs_clean_instrumental_path: Path to clean instrumental in GCS
gcs_backing_vocals_path: Path to backing vocals in GCS
mute_regions: List of regions to mute
gcs_preview_path: Where to upload the preview in GCS
job_id: Job ID for logging
preview_duration_seconds: Optional max duration for preview
Returns:
GCS path to the uploaded preview
"""
logger.info(f"[{job_id}] Creating preview with {len(mute_regions)} mute regions")
with tempfile.TemporaryDirectory() as temp_dir:
# Download input files
local_clean_path = os.path.join(temp_dir, "clean_instrumental.flac")
local_backing_path = os.path.join(temp_dir, "backing_vocals.flac")
local_preview_path = os.path.join(temp_dir, "preview.flac")
self.storage_service.download_file(
gcs_clean_instrumental_path,
local_clean_path
)
self.storage_service.download_file(
gcs_backing_vocals_path,
local_backing_path
)
# Generate preview
from pydub import AudioSegment
preview = self.editor.preview_with_mutes(
clean_instrumental_path=local_clean_path,
backing_vocals_path=local_backing_path,
mute_regions=mute_regions,
)
# Optionally truncate
if preview_duration_seconds:
max_ms = int(preview_duration_seconds * 1000)
preview = preview[:max_ms]
# Export and upload
preview.export(local_preview_path, format="flac")
self.storage_service.upload_file(local_preview_path, gcs_preview_path)
logger.info(f"[{job_id}] Preview created: {gcs_preview_path}")
return gcs_preview_path
def mute_backing_vocals_only(
self,
gcs_backing_vocals_path: str,
mute_regions: List[MuteRegion],
gcs_output_path: str,
job_id: str,
) -> str:
"""
Apply mute regions to backing vocals without combining with instrumental.
This is useful for creating an edited backing vocals track that
can be combined with the instrumental later.
Args:
gcs_backing_vocals_path: Path to backing vocals in GCS
mute_regions: List of regions to mute
gcs_output_path: Where to upload the edited backing vocals
job_id: Job ID for logging
Returns:
GCS path to the uploaded edited backing vocals
"""
logger.info(
f"[{job_id}] Muting backing vocals with {len(mute_regions)} regions"
)
with tempfile.TemporaryDirectory() as temp_dir:
local_backing_path = os.path.join(temp_dir, "backing_vocals.flac")
local_output_path = os.path.join(temp_dir, "muted_backing.flac")
self.storage_service.download_file(
gcs_backing_vocals_path,
local_backing_path
)
self.editor.apply_mute_to_single_track(
audio_path=local_backing_path,
mute_regions=mute_regions,
output_path=local_output_path,
)
self.storage_service.upload_file(local_output_path, gcs_output_path)
logger.info(f"[{job_id}] Muted backing vocals: {gcs_output_path}")
return gcs_output_path
def validate_mute_regions(
self,
mute_regions: List[MuteRegion],
total_duration_seconds: float,
) -> List[str]:
"""
Validate mute regions for consistency.
Args:
mute_regions: List of mute regions to validate
total_duration_seconds: Total duration of the audio
Returns:
List of validation error messages (empty if valid)
"""
errors = []
for i, region in enumerate(mute_regions):
if region.start_seconds < 0:
errors.append(
f"Region {i}: start_seconds ({region.start_seconds}) cannot be negative"
)
if region.end_seconds <= region.start_seconds:
errors.append(
f"Region {i}: end_seconds ({region.end_seconds}) must be after "
f"start_seconds ({region.start_seconds})"
)
if region.start_seconds > total_duration_seconds:
errors.append(
f"Region {i}: start_seconds ({region.start_seconds}) exceeds "
f"audio duration ({total_duration_seconds})"
)
if region.end_seconds > total_duration_seconds:
# Not an error, but log a warning - the region will be clamped
logger.warning(
f"Region {i}: end_seconds ({region.end_seconds}) exceeds "
f"audio duration ({total_duration_seconds}), will be clamped"
)
return errors
+348
View File
@@ -0,0 +1,348 @@
"""
Audio search service for finding and downloading audio files.
This service integrates with flacfetch to search for audio from various sources
(YouTube, music trackers, etc.) and download the selected audio file.
"""
import logging
import os
import tempfile
from dataclasses import dataclass, asdict
from typing import List, Optional, Dict, Any
logger = logging.getLogger(__name__)
@dataclass
class AudioSearchResult:
"""
Represents a single search result for audio.
This is a serializable representation of a search result that can be
stored in Firestore and sent to clients.
"""
title: str
artist: str
provider: str
url: str
duration: Optional[int] = None # Duration in seconds
quality: Optional[str] = None # e.g., "FLAC", "320kbps", etc.
source_id: Optional[str] = None # Unique ID from the source
index: int = 0 # Index in the results list (for selection)
def to_dict(self) -> Dict[str, Any]:
"""Convert to dict for JSON serialization."""
return asdict(self)
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "AudioSearchResult":
"""Create from dict."""
return cls(**data)
@dataclass
class AudioDownloadResult:
"""Result of downloading an audio file."""
filepath: str
artist: str
title: str
provider: str
duration: Optional[int] = None
quality: Optional[str] = None
class AudioSearchError(Exception):
"""Base exception for audio search errors."""
pass
class NoResultsError(AudioSearchError):
"""Raised when no search results are found."""
pass
class DownloadError(AudioSearchError):
"""Raised when download fails."""
pass
class AudioSearchService:
"""
Service for searching and downloading audio files using flacfetch.
This service is used by the backend to:
1. Search for audio by artist/title
2. Return results for user selection
3. Download the selected audio to a local file
"""
# Sentinel value to indicate "use environment variable"
_USE_ENV = object()
def __init__(
self,
redacted_api_key: Optional[str] = _USE_ENV,
ops_api_key: Optional[str] = _USE_ENV,
):
"""
Initialize the audio search service.
Args:
redacted_api_key: API key for Redacted tracker (optional, uses env if not provided)
ops_api_key: API key for OPS tracker (optional, uses env if not provided)
"""
# Use environment variables if not explicitly provided
if redacted_api_key is self._USE_ENV:
self._redacted_api_key = os.environ.get("REDACTED_API_KEY")
else:
self._redacted_api_key = redacted_api_key
if ops_api_key is self._USE_ENV:
self._ops_api_key = os.environ.get("OPS_API_KEY")
else:
self._ops_api_key = ops_api_key
self._manager = None
self._raw_results = {} # Cache raw results for download
def _get_manager(self):
"""Lazily initialize and return the FetchManager."""
if self._manager is None:
try:
from flacfetch.core.manager import FetchManager
from flacfetch.providers.youtube import YouTubeProvider
except ImportError as e:
logger.error(f"flacfetch not installed: {e}")
raise AudioSearchError(
"flacfetch library is not installed. "
"Install with: pip install flacfetch"
) from e
self._manager = FetchManager()
# Add providers based on available API keys
if self._redacted_api_key:
try:
from flacfetch.providers.redacted import RedactedProvider
self._manager.add_provider(RedactedProvider(api_key=self._redacted_api_key))
logger.debug("Added Redacted provider")
except ImportError:
logger.warning("Redacted provider not available")
if self._ops_api_key:
try:
from flacfetch.providers.ops import OPSProvider
self._manager.add_provider(OPSProvider(api_key=self._ops_api_key))
logger.debug("Added OPS provider")
except ImportError:
logger.warning("OPS provider not available")
# Always add YouTube as a fallback provider
self._manager.add_provider(YouTubeProvider())
logger.debug("Added YouTube provider")
return self._manager
def search(self, artist: str, title: str) -> List[AudioSearchResult]:
"""
Search for audio matching the given artist and title.
Args:
artist: The artist name to search for
title: The track title to search for
Returns:
List of AudioSearchResult objects
Raises:
NoResultsError: If no results are found
AudioSearchError: For other errors
"""
try:
from flacfetch.core.models import TrackQuery
except ImportError as e:
raise AudioSearchError("flacfetch not installed") from e
manager = self._get_manager()
query = TrackQuery(artist=artist, title=title)
logger.info(f"Searching for audio: {artist} - {title}")
try:
results = manager.search(query)
except Exception as e:
logger.error(f"Search failed: {e}")
raise AudioSearchError(f"Search failed: {e}") from e
if not results:
raise NoResultsError(f"No results found for: {artist} - {title}")
# Convert to our AudioSearchResult format and cache raw results
search_results = []
self._raw_results.clear()
for i, result in enumerate(results):
search_result = AudioSearchResult(
title=getattr(result, "title", title),
artist=getattr(result, "artist", artist),
provider=getattr(result, "provider", "Unknown"),
url=getattr(result, "url", ""),
duration=getattr(result, "duration", None),
quality=getattr(result, "quality", None),
source_id=getattr(result, "id", str(i)),
index=i,
)
search_results.append(search_result)
# Cache raw result for later download
self._raw_results[i] = result
logger.info(f"Found {len(search_results)} results for: {artist} - {title}")
return search_results
def select_best(self, results: List[AudioSearchResult]) -> int:
"""
Select the best result from a list of search results.
Uses flacfetch's built-in quality ranking to select the best source.
Args:
results: List of search results
Returns:
Index of the best result
"""
if not results:
return 0
manager = self._get_manager()
# Get raw results for the indices we have
raw_results = [self._raw_results.get(r.index) for r in results if r.index in self._raw_results]
if raw_results:
try:
best = manager.select_best(raw_results)
# Find index of best result
for i, raw in enumerate(raw_results):
if raw == best:
return results[i].index
except Exception as e:
logger.warning(f"select_best failed, using first result: {e}")
# Fallback: return first result
return results[0].index if results else 0
def download(
self,
result_index: int,
output_dir: str,
output_filename: Optional[str] = None,
) -> AudioDownloadResult:
"""
Download audio from a search result.
Args:
result_index: Index of the result to download (from search results)
output_dir: Directory to save the downloaded file
output_filename: Optional filename (without extension)
Returns:
AudioDownloadResult with the downloaded file path
Raises:
DownloadError: If download fails
"""
if result_index not in self._raw_results:
raise DownloadError(f"No cached result for index {result_index}. Run search() first.")
raw_result = self._raw_results[result_index]
manager = self._get_manager()
# Ensure output directory exists
os.makedirs(output_dir, exist_ok=True)
# Get metadata from raw result
artist = getattr(raw_result, "artist", "Unknown")
title = getattr(raw_result, "title", "Unknown")
provider = getattr(raw_result, "provider", "Unknown")
# Generate filename if not provided
if output_filename is None:
output_filename = f"{artist} - {title}"
logger.info(f"Downloading: {artist} - {title} from {provider}")
try:
filepath = manager.download(
raw_result,
output_path=output_dir,
output_filename=output_filename,
)
if filepath is None:
raise DownloadError(f"Download returned no file path for: {artist} - {title}")
logger.info(f"Downloaded to: {filepath}")
return AudioDownloadResult(
filepath=filepath,
artist=artist,
title=title,
provider=provider,
duration=getattr(raw_result, "duration", None),
quality=getattr(raw_result, "quality", None),
)
except Exception as e:
raise DownloadError(f"Failed to download {artist} - {title}: {e}") from e
def search_and_download_auto(
self,
artist: str,
title: str,
output_dir: str,
output_filename: Optional[str] = None,
) -> AudioDownloadResult:
"""
Search for audio and automatically download the best result.
This is a convenience method that combines search(), select_best(),
and download() for automated/non-interactive usage.
Args:
artist: The artist name to search for
title: The track title to search for
output_dir: Directory to save the downloaded file
output_filename: Optional filename (without extension)
Returns:
AudioDownloadResult with the downloaded file path
Raises:
NoResultsError: If no results are found
DownloadError: If download fails
"""
# Search
results = self.search(artist, title)
# Select best
best_index = self.select_best(results)
logger.info(f"Auto-selected result {best_index}: {results[best_index].artist} - {results[best_index].title} ({results[best_index].provider})")
# Download
return self.download(best_index, output_dir, output_filename)
# Singleton instance
_audio_search_service: Optional[AudioSearchService] = None
def get_audio_search_service() -> AudioSearchService:
"""Get the singleton AudioSearchService instance."""
global _audio_search_service
if _audio_search_service is None:
_audio_search_service = AudioSearchService()
return _audio_search_service
+386
View File
@@ -0,0 +1,386 @@
"""
Tests for audio search functionality (Batch 5).
Tests the audio search service, API routes, and job model fields.
"""
import pytest
import os
from unittest.mock import Mock, patch, MagicMock
from datetime import datetime
from backend.models.job import Job, JobCreate, JobStatus, STATE_TRANSITIONS
from backend.services.audio_search_service import (
AudioSearchService,
AudioSearchResult,
AudioDownloadResult,
AudioSearchError,
NoResultsError,
DownloadError,
get_audio_search_service,
)
class TestJobModelAudioSearchFields:
"""Test Job model has audio search fields."""
def test_job_has_audio_search_fields(self):
"""Test Job model has audio search configuration fields."""
job = Job(
job_id="test123",
status=JobStatus.PENDING,
created_at=datetime.utcnow(),
updated_at=datetime.utcnow(),
artist="ABBA",
title="Waterloo",
audio_search_artist="ABBA",
audio_search_title="Waterloo",
auto_download=True,
)
assert job.audio_search_artist == "ABBA"
assert job.audio_search_title == "Waterloo"
assert job.auto_download is True
def test_job_audio_search_fields_default_values(self):
"""Test default values for audio search fields."""
job = Job(
job_id="test123",
status=JobStatus.PENDING,
created_at=datetime.utcnow(),
updated_at=datetime.utcnow(),
)
assert job.audio_search_artist is None
assert job.audio_search_title is None
assert job.auto_download is False
def test_job_create_has_audio_search_fields(self):
"""Test JobCreate model has audio search fields."""
job_create = JobCreate(
artist="ABBA",
title="Waterloo",
audio_search_artist="ABBA",
audio_search_title="Waterloo",
auto_download=True,
)
assert job_create.audio_search_artist == "ABBA"
assert job_create.audio_search_title == "Waterloo"
assert job_create.auto_download is True
class TestJobStatusAudioSearchStates:
"""Test Job status includes audio search states."""
def test_audio_search_statuses_exist(self):
"""Test audio search status values exist."""
assert hasattr(JobStatus, 'SEARCHING_AUDIO')
assert hasattr(JobStatus, 'AWAITING_AUDIO_SELECTION')
assert hasattr(JobStatus, 'DOWNLOADING_AUDIO')
assert JobStatus.SEARCHING_AUDIO == "searching_audio"
assert JobStatus.AWAITING_AUDIO_SELECTION == "awaiting_audio_selection"
assert JobStatus.DOWNLOADING_AUDIO == "downloading_audio"
def test_state_transitions_include_audio_search_flow(self):
"""Test state transitions include audio search flow."""
# PENDING can go to SEARCHING_AUDIO
assert JobStatus.SEARCHING_AUDIO in STATE_TRANSITIONS[JobStatus.PENDING]
# SEARCHING_AUDIO can go to AWAITING_AUDIO_SELECTION or DOWNLOADING_AUDIO
assert JobStatus.AWAITING_AUDIO_SELECTION in STATE_TRANSITIONS[JobStatus.SEARCHING_AUDIO]
assert JobStatus.DOWNLOADING_AUDIO in STATE_TRANSITIONS[JobStatus.SEARCHING_AUDIO]
# AWAITING_AUDIO_SELECTION can go to DOWNLOADING_AUDIO
assert JobStatus.DOWNLOADING_AUDIO in STATE_TRANSITIONS[JobStatus.AWAITING_AUDIO_SELECTION]
# DOWNLOADING_AUDIO can go to DOWNLOADING
assert JobStatus.DOWNLOADING in STATE_TRANSITIONS[JobStatus.DOWNLOADING_AUDIO]
class TestAudioSearchResult:
"""Test AudioSearchResult dataclass."""
def test_create_audio_search_result(self):
"""Test creating an AudioSearchResult."""
result = AudioSearchResult(
title="Waterloo",
artist="ABBA",
provider="YouTube",
url="https://youtube.com/watch?v=abc123",
duration=180,
quality="FLAC",
source_id="abc123",
index=0,
)
assert result.title == "Waterloo"
assert result.artist == "ABBA"
assert result.provider == "YouTube"
assert result.url == "https://youtube.com/watch?v=abc123"
assert result.duration == 180
assert result.quality == "FLAC"
assert result.source_id == "abc123"
assert result.index == 0
def test_to_dict(self):
"""Test converting to dict for serialization."""
result = AudioSearchResult(
title="Waterloo",
artist="ABBA",
provider="YouTube",
url="https://youtube.com/watch?v=abc123",
index=0,
)
data = result.to_dict()
assert data['title'] == "Waterloo"
assert data['artist'] == "ABBA"
assert data['provider'] == "YouTube"
assert data['url'] == "https://youtube.com/watch?v=abc123"
assert data['index'] == 0
def test_from_dict(self):
"""Test creating from dict."""
data = {
'title': "Waterloo",
'artist': "ABBA",
'provider': "YouTube",
'url': "https://youtube.com/watch?v=abc123",
'duration': 180,
'quality': "FLAC",
'source_id': "abc123",
'index': 0,
}
result = AudioSearchResult.from_dict(data)
assert result.title == "Waterloo"
assert result.artist == "ABBA"
assert result.provider == "YouTube"
assert result.index == 0
class TestAudioSearchServiceInit:
"""Test AudioSearchService initialization."""
@patch.dict('os.environ', {'REDACTED_API_KEY': '', 'OPS_API_KEY': ''}, clear=False)
def test_init_with_no_keys(self):
"""Test initialization without API keys."""
# Pass explicit None to override environment
service = AudioSearchService(redacted_api_key=None, ops_api_key=None)
# When explicitly passed None, it should be None (not from env)
assert service._redacted_api_key is None
assert service._ops_api_key is None
assert service._manager is None
def test_init_with_keys(self):
"""Test initialization with API keys."""
service = AudioSearchService(
redacted_api_key="test_redacted_key",
ops_api_key="test_ops_key",
)
assert service._redacted_api_key == "test_redacted_key"
assert service._ops_api_key == "test_ops_key"
def test_init_reads_from_environment(self):
"""Test initialization reads keys from environment variables."""
import os
# Just test that the service can be initialized
service = AudioSearchService()
# The service should have API keys from env or None
assert service._manager is None # Not yet initialized
class TestAudioSearchServiceSearch:
"""Test AudioSearchService.search() method."""
@patch('backend.services.audio_search_service.AudioSearchService._get_manager')
def test_search_returns_results(self, mock_get_manager):
"""Test search returns AudioSearchResult list."""
# Mock the flacfetch result
mock_result = Mock()
mock_result.title = "Waterloo"
mock_result.artist = "ABBA"
mock_result.provider = "YouTube"
mock_result.url = "https://youtube.com/watch?v=abc123"
mock_result.duration = 180
mock_result.quality = "FLAC"
mock_result.id = "abc123"
mock_manager = Mock()
mock_manager.search.return_value = [mock_result]
mock_get_manager.return_value = mock_manager
service = AudioSearchService()
results = service.search("ABBA", "Waterloo")
assert len(results) == 1
assert results[0].title == "Waterloo"
assert results[0].artist == "ABBA"
assert results[0].provider == "YouTube"
assert results[0].index == 0
@patch('backend.services.audio_search_service.AudioSearchService._get_manager')
def test_search_no_results_raises_error(self, mock_get_manager):
"""Test search raises NoResultsError when no results."""
mock_manager = Mock()
mock_manager.search.return_value = []
mock_get_manager.return_value = mock_manager
service = AudioSearchService()
with pytest.raises(NoResultsError) as exc_info:
service.search("Unknown Artist", "Unknown Song")
assert "No results found" in str(exc_info.value)
@patch('backend.services.audio_search_service.AudioSearchService._get_manager')
def test_search_multiple_results(self, mock_get_manager):
"""Test search returns multiple results with correct indices."""
mock_results = []
for i in range(3):
mock_result = Mock()
mock_result.title = f"Song {i}"
mock_result.artist = "Artist"
mock_result.provider = ["YouTube", "Redacted", "OPS"][i]
mock_result.url = f"https://example.com/{i}"
mock_result.duration = 180 + i * 10
mock_result.quality = ["320kbps", "FLAC", "FLAC"][i]
mock_result.id = str(i)
mock_results.append(mock_result)
mock_manager = Mock()
mock_manager.search.return_value = mock_results
mock_get_manager.return_value = mock_manager
service = AudioSearchService()
results = service.search("Artist", "Song")
assert len(results) == 3
assert results[0].index == 0
assert results[1].index == 1
assert results[2].index == 2
class TestAudioSearchServiceSelectBest:
"""Test AudioSearchService.select_best() method."""
@patch('backend.services.audio_search_service.AudioSearchService._get_manager')
def test_select_best_uses_manager(self, mock_get_manager):
"""Test select_best uses flacfetch's select_best."""
# First need to do a search to populate cache
mock_result = Mock()
mock_result.title = "Waterloo"
mock_result.artist = "ABBA"
mock_result.provider = "YouTube"
mock_result.url = "https://youtube.com/watch?v=abc123"
mock_result.duration = 180
mock_result.quality = "FLAC"
mock_result.id = "abc123"
mock_manager = Mock()
mock_manager.search.return_value = [mock_result]
mock_manager.select_best.return_value = mock_result
mock_get_manager.return_value = mock_manager
service = AudioSearchService()
results = service.search("ABBA", "Waterloo")
best_index = service.select_best(results)
assert best_index == 0
def test_select_best_empty_list_returns_zero(self):
"""Test select_best returns 0 for empty list."""
service = AudioSearchService()
best_index = service.select_best([])
assert best_index == 0
class TestAudioSearchServiceDownload:
"""Test AudioSearchService.download() method."""
@patch('backend.services.audio_search_service.AudioSearchService._get_manager')
def test_download_without_search_raises_error(self, mock_get_manager):
"""Test download without prior search raises error."""
mock_manager = Mock()
mock_get_manager.return_value = mock_manager
service = AudioSearchService()
with pytest.raises(DownloadError) as exc_info:
service.download(0, "/tmp")
assert "No cached result" in str(exc_info.value)
@patch('backend.services.audio_search_service.AudioSearchService._get_manager')
def test_download_after_search(self, mock_get_manager):
"""Test download after search works."""
import tempfile
import os
# Create a temp file to simulate downloaded file
temp_dir = tempfile.mkdtemp()
temp_file = os.path.join(temp_dir, "test.flac")
with open(temp_file, 'w') as f:
f.write("test")
mock_result = Mock()
mock_result.title = "Waterloo"
mock_result.artist = "ABBA"
mock_result.provider = "YouTube"
mock_result.url = "https://youtube.com/watch?v=abc123"
mock_result.duration = 180
mock_result.quality = "FLAC"
mock_result.id = "abc123"
mock_manager = Mock()
mock_manager.search.return_value = [mock_result]
mock_manager.download.return_value = temp_file
mock_get_manager.return_value = mock_manager
service = AudioSearchService()
service.search("ABBA", "Waterloo")
result = service.download(0, temp_dir)
assert result.filepath == temp_file
assert result.artist == "ABBA"
assert result.title == "Waterloo"
assert result.provider == "YouTube"
# Cleanup
os.remove(temp_file)
os.rmdir(temp_dir)
class TestGetAudioSearchService:
"""Test get_audio_search_service singleton."""
def test_get_audio_search_service_returns_instance(self):
"""Test get_audio_search_service returns an instance."""
# Reset singleton
import backend.services.audio_search_service as module
module._audio_search_service = None
service = get_audio_search_service()
assert service is not None
assert isinstance(service, AudioSearchService)
def test_get_audio_search_service_singleton(self):
"""Test get_audio_search_service returns same instance."""
service1 = get_audio_search_service()
service2 = get_audio_search_service()
assert service1 is service2
+363
View File
@@ -0,0 +1,363 @@
"""
Unit tests for audio analysis and editing services.
These tests verify the backend service wrappers that use the shared
karaoke_gen.instrumental_review module with GCS integration.
"""
import os
import tempfile
import pytest
from unittest.mock import MagicMock, patch, ANY
from pydub import AudioSegment
from pydub.generators import Sine
from karaoke_gen.instrumental_review import MuteRegion
class TestAudioAnalysisService:
"""Tests for AudioAnalysisService."""
@pytest.fixture
def mock_storage_service(self):
"""Create a mock storage service."""
mock = MagicMock()
return mock
@pytest.fixture
def temp_audio_file(self, tmp_path):
"""Create a temporary audio file for testing."""
audio_path = tmp_path / "test_audio.flac"
# Create a simple sine wave audio
tone = Sine(440).to_audio_segment(duration=5000) - 15
tone.export(str(audio_path), format="flac")
return str(audio_path)
@pytest.fixture
def silent_audio_file(self, tmp_path):
"""Create a silent audio file for testing."""
audio_path = tmp_path / "silent_audio.flac"
audio = AudioSegment.silent(duration=5000, frame_rate=44100)
audio.export(str(audio_path), format="flac")
return str(audio_path)
def test_service_initialization(self, mock_storage_service):
"""Test service initializes with default parameters."""
from backend.services.audio_analysis_service import AudioAnalysisService
service = AudioAnalysisService(storage_service=mock_storage_service)
assert service.storage_service == mock_storage_service
assert service.analyzer.silence_threshold_db == -40.0
def test_service_custom_threshold(self, mock_storage_service):
"""Test service accepts custom silence threshold."""
from backend.services.audio_analysis_service import AudioAnalysisService
service = AudioAnalysisService(
storage_service=mock_storage_service,
silence_threshold_db=-35.0,
)
assert service.analyzer.silence_threshold_db == -35.0
def test_analyze_backing_vocals_downloads_file(
self, mock_storage_service, temp_audio_file
):
"""Test that analyze_backing_vocals downloads file from GCS."""
from backend.services.audio_analysis_service import AudioAnalysisService
# Set up mock to copy the temp file to the download location
def mock_download(gcs_path, local_path):
import shutil
shutil.copy(temp_audio_file, local_path)
return local_path
mock_storage_service.download_file.side_effect = mock_download
service = AudioAnalysisService(storage_service=mock_storage_service)
result = service.analyze_backing_vocals(
gcs_audio_path="jobs/test/stems/backing_vocals.flac",
job_id="test-job",
)
# Verify download was called
mock_storage_service.download_file.assert_called_once()
# Verify result is valid
assert result is not None
assert hasattr(result, 'has_audible_content')
def test_analyze_silent_audio_returns_no_audible(
self, mock_storage_service, silent_audio_file
):
"""Test that silent audio returns has_audible_content=False."""
from backend.services.audio_analysis_service import AudioAnalysisService
def mock_download(gcs_path, local_path):
import shutil
shutil.copy(silent_audio_file, local_path)
return local_path
mock_storage_service.download_file.side_effect = mock_download
service = AudioAnalysisService(storage_service=mock_storage_service)
result = service.analyze_backing_vocals(
gcs_audio_path="jobs/test/stems/backing_vocals.flac",
job_id="test-job",
)
assert result.has_audible_content is False
assert len(result.audible_segments) == 0
def test_analyze_and_generate_waveform_uploads_image(
self, mock_storage_service, temp_audio_file
):
"""Test that analyze_and_generate_waveform uploads waveform to GCS."""
from backend.services.audio_analysis_service import AudioAnalysisService
def mock_download(gcs_path, local_path):
import shutil
shutil.copy(temp_audio_file, local_path)
return local_path
mock_storage_service.download_file.side_effect = mock_download
mock_storage_service.upload_file.return_value = "jobs/test/analysis/waveform.png"
service = AudioAnalysisService(storage_service=mock_storage_service)
result, waveform_path = service.analyze_and_generate_waveform(
gcs_audio_path="jobs/test/stems/backing_vocals.flac",
job_id="test-job",
gcs_waveform_destination="jobs/test/analysis/waveform.png",
)
# Verify upload was called
mock_storage_service.upload_file.assert_called_once()
# Verify waveform path is returned
assert waveform_path == "jobs/test/analysis/waveform.png"
def test_get_waveform_data_returns_amplitudes(
self, mock_storage_service, temp_audio_file
):
"""Test that get_waveform_data returns amplitude data."""
from backend.services.audio_analysis_service import AudioAnalysisService
def mock_download(gcs_path, local_path):
import shutil
shutil.copy(temp_audio_file, local_path)
return local_path
mock_storage_service.download_file.side_effect = mock_download
service = AudioAnalysisService(storage_service=mock_storage_service)
amplitudes, duration = service.get_waveform_data(
gcs_audio_path="jobs/test/stems/backing_vocals.flac",
job_id="test-job",
num_points=100,
)
# Verify we get amplitude data
assert isinstance(amplitudes, list)
assert len(amplitudes) > 0
assert all(isinstance(a, float) for a in amplitudes)
# Verify duration is reasonable
assert duration > 0
assert duration <= 10 # Our test file is 5 seconds
class TestAudioEditingService:
"""Tests for AudioEditingService."""
@pytest.fixture
def mock_storage_service(self):
"""Create a mock storage service."""
mock = MagicMock()
return mock
@pytest.fixture
def temp_audio_files(self, tmp_path):
"""Create temporary audio files for testing."""
clean_path = tmp_path / "clean_instrumental.flac"
backing_path = tmp_path / "backing_vocals.flac"
# Create clean instrumental (chord)
tone1 = Sine(220).to_audio_segment(duration=5000) - 15
tone2 = Sine(330).to_audio_segment(duration=5000) - 15
clean = tone1.overlay(tone2)
clean.export(str(clean_path), format="flac")
# Create backing vocals
backing = Sine(440).to_audio_segment(duration=5000) - 20
backing.export(str(backing_path), format="flac")
return str(clean_path), str(backing_path)
def test_service_initialization(self, mock_storage_service):
"""Test service initializes correctly."""
from backend.services.audio_editing_service import AudioEditingService
service = AudioEditingService(storage_service=mock_storage_service)
assert service.storage_service == mock_storage_service
assert service.editor.output_format == "flac"
def test_create_custom_instrumental_downloads_files(
self, mock_storage_service, temp_audio_files
):
"""Test that create_custom_instrumental downloads input files."""
from backend.services.audio_editing_service import AudioEditingService
clean_path, backing_path = temp_audio_files
# Track which files were downloaded
downloaded_files = []
def mock_download(gcs_path, local_path):
downloaded_files.append(gcs_path)
# Copy the appropriate test file
import shutil
if 'clean' in gcs_path:
shutil.copy(clean_path, local_path)
else:
shutil.copy(backing_path, local_path)
return local_path
mock_storage_service.download_file.side_effect = mock_download
mock_storage_service.upload_file.return_value = "jobs/test/stems/custom.flac"
service = AudioEditingService(storage_service=mock_storage_service)
mute_regions = [MuteRegion(start_seconds=1.0, end_seconds=2.0)]
result = service.create_custom_instrumental(
gcs_clean_instrumental_path="jobs/test/stems/clean.flac",
gcs_backing_vocals_path="jobs/test/stems/backing.flac",
mute_regions=mute_regions,
gcs_output_path="jobs/test/stems/custom.flac",
job_id="test-job",
)
# Verify both files were downloaded
assert len(downloaded_files) == 2
assert mock_storage_service.upload_file.called
def test_create_custom_instrumental_uploads_result(
self, mock_storage_service, temp_audio_files
):
"""Test that create_custom_instrumental uploads the result."""
from backend.services.audio_editing_service import AudioEditingService
clean_path, backing_path = temp_audio_files
def mock_download(gcs_path, local_path):
import shutil
if 'clean' in gcs_path:
shutil.copy(clean_path, local_path)
else:
shutil.copy(backing_path, local_path)
return local_path
mock_storage_service.download_file.side_effect = mock_download
mock_storage_service.upload_file.return_value = "jobs/test/stems/custom.flac"
service = AudioEditingService(storage_service=mock_storage_service)
mute_regions = [MuteRegion(start_seconds=1.0, end_seconds=2.0)]
result = service.create_custom_instrumental(
gcs_clean_instrumental_path="jobs/test/stems/clean.flac",
gcs_backing_vocals_path="jobs/test/stems/backing.flac",
mute_regions=mute_regions,
gcs_output_path="jobs/test/stems/custom.flac",
job_id="test-job",
)
# Verify upload was called with correct destination
mock_storage_service.upload_file.assert_called_once()
call_args = mock_storage_service.upload_file.call_args
assert call_args[0][1] == "jobs/test/stems/custom.flac"
# Verify result has correct path
assert result.output_path == "jobs/test/stems/custom.flac"
def test_create_custom_instrumental_returns_statistics(
self, mock_storage_service, temp_audio_files
):
"""Test that create_custom_instrumental returns correct statistics."""
from backend.services.audio_editing_service import AudioEditingService
clean_path, backing_path = temp_audio_files
def mock_download(gcs_path, local_path):
import shutil
if 'clean' in gcs_path:
shutil.copy(clean_path, local_path)
else:
shutil.copy(backing_path, local_path)
return local_path
mock_storage_service.download_file.side_effect = mock_download
mock_storage_service.upload_file.return_value = "jobs/test/stems/custom.flac"
service = AudioEditingService(storage_service=mock_storage_service)
mute_regions = [
MuteRegion(start_seconds=1.0, end_seconds=2.0),
MuteRegion(start_seconds=3.0, end_seconds=4.0),
]
result = service.create_custom_instrumental(
gcs_clean_instrumental_path="jobs/test/stems/clean.flac",
gcs_backing_vocals_path="jobs/test/stems/backing.flac",
mute_regions=mute_regions,
gcs_output_path="jobs/test/stems/custom.flac",
job_id="test-job",
)
# Verify statistics
assert len(result.mute_regions_applied) == 2
assert result.total_muted_duration_seconds == 2.0 # 1s + 1s
assert result.output_duration_seconds > 0
def test_validate_mute_regions_returns_errors_for_invalid(
self, mock_storage_service
):
"""Test that validate_mute_regions catches invalid regions."""
from backend.services.audio_editing_service import AudioEditingService
service = AudioEditingService(storage_service=mock_storage_service)
mute_regions = [
MuteRegion(start_seconds=0.0, end_seconds=1.0), # Valid
MuteRegion(start_seconds=100.0, end_seconds=110.0), # Beyond duration
]
errors = service.validate_mute_regions(mute_regions, total_duration_seconds=60.0)
# Should have error for region exceeding duration
assert len(errors) == 1
assert "exceeds" in errors[0].lower()
def test_validate_mute_regions_returns_empty_for_valid(
self, mock_storage_service
):
"""Test that validate_mute_regions returns empty for valid regions."""
from backend.services.audio_editing_service import AudioEditingService
service = AudioEditingService(storage_service=mock_storage_service)
mute_regions = [
MuteRegion(start_seconds=0.0, end_seconds=1.0),
MuteRegion(start_seconds=10.0, end_seconds=15.0),
]
errors = service.validate_mute_regions(mute_regions, total_duration_seconds=60.0)
assert len(errors) == 0
+457
View File
@@ -0,0 +1,457 @@
"""
API endpoint tests for instrumental review functionality.
Tests for:
- GET /api/jobs/{job_id}/instrumental-analysis
- GET /api/jobs/{job_id}/audio-stream/{stem_type}
- POST /api/jobs/{job_id}/create-custom-instrumental
- GET /api/jobs/{job_id}/waveform-data
"""
import pytest
from datetime import datetime
from unittest.mock import MagicMock, patch, AsyncMock
from fastapi.testclient import TestClient
from backend.models.job import Job, JobStatus
@pytest.fixture
def mock_job_manager():
"""Create a mock job manager."""
with patch('backend.api.routes.jobs.job_manager') as mock:
yield mock
@pytest.fixture
def mock_storage_service():
"""Create a mock storage service."""
with patch('backend.api.routes.jobs.StorageService') as mock:
mock_instance = MagicMock()
mock_instance.generate_signed_url.return_value = "https://storage.googleapis.com/signed-url"
mock.return_value = mock_instance
yield mock_instance
@pytest.fixture
def sample_job():
"""Create a sample job for testing."""
return Job(
job_id="test-job-123",
artist="Test Artist",
title="Test Song",
status=JobStatus.AWAITING_INSTRUMENTAL_SELECTION,
created_at=datetime.now(),
updated_at=datetime.now(),
file_urls={
"stems": {
"instrumental_clean": "jobs/test/stems/instrumental_clean.flac",
"backing_vocals": "jobs/test/stems/backing_vocals.flac",
"instrumental_with_backing": "jobs/test/stems/instrumental_with_backing.flac",
},
"analysis": {
"backing_vocals_waveform": "jobs/test/analysis/waveform.png",
},
},
state_data={
"backing_vocals_analysis": {
"has_audible_content": True,
"total_duration_seconds": 180.0,
"audible_segments": [
{
"start_seconds": 10.0,
"end_seconds": 20.0,
"duration_seconds": 10.0,
"avg_amplitude_db": -25.0,
},
{
"start_seconds": 60.0,
"end_seconds": 80.0,
"duration_seconds": 20.0,
"avg_amplitude_db": -30.0,
},
],
"recommended_selection": "review_needed",
"total_audible_duration_seconds": 30.0,
"audible_percentage": 16.67,
"silence_threshold_db": -40.0,
}
},
)
@pytest.fixture
def silent_job():
"""Create a job with silent backing vocals."""
return Job(
job_id="test-job-silent",
artist="Test Artist",
title="Test Song",
status=JobStatus.AWAITING_INSTRUMENTAL_SELECTION,
created_at=datetime.now(),
updated_at=datetime.now(),
file_urls={
"stems": {
"instrumental_clean": "jobs/test/stems/instrumental_clean.flac",
"backing_vocals": "jobs/test/stems/backing_vocals.flac",
"instrumental_with_backing": "jobs/test/stems/instrumental_with_backing.flac",
},
"analysis": {
"backing_vocals_waveform": "jobs/test/analysis/waveform.png",
},
},
state_data={
"backing_vocals_analysis": {
"has_audible_content": False,
"total_duration_seconds": 180.0,
"audible_segments": [],
"recommended_selection": "clean",
"total_audible_duration_seconds": 0.0,
"audible_percentage": 0.0,
"silence_threshold_db": -40.0,
}
},
)
class TestGetInstrumentalAnalysis:
"""Tests for GET /api/jobs/{job_id}/instrumental-analysis."""
def test_get_analysis_returns_data(self, mock_job_manager, mock_storage_service, sample_job):
"""GET /instrumental-analysis should return analysis data."""
mock_job_manager.get_job.return_value = sample_job
from backend.api.routes.jobs import get_instrumental_analysis
import asyncio
result = asyncio.get_event_loop().run_until_complete(
get_instrumental_analysis("test-job-123")
)
assert result["job_id"] == "test-job-123"
assert result["artist"] == "Test Artist"
assert result["title"] == "Test Song"
assert result["analysis"]["has_audible_content"] is True
assert len(result["analysis"]["audible_segments"]) == 2
def test_get_analysis_includes_audio_urls(self, mock_job_manager, mock_storage_service, sample_job):
"""GET /instrumental-analysis should include audio URLs."""
mock_job_manager.get_job.return_value = sample_job
from backend.api.routes.jobs import get_instrumental_analysis
import asyncio
result = asyncio.get_event_loop().run_until_complete(
get_instrumental_analysis("test-job-123")
)
assert "audio_urls" in result
assert "clean_instrumental" in result["audio_urls"]
assert "backing_vocals" in result["audio_urls"]
assert "with_backing" in result["audio_urls"]
def test_get_analysis_includes_waveform_url(self, mock_job_manager, sample_job):
"""GET /instrumental-analysis should include waveform URL."""
mock_job_manager.get_job.return_value = sample_job
# Need to mock StorageService at module level for the signed URL
with patch('backend.api.routes.jobs.StorageService') as mock_storage_cls:
mock_storage = MagicMock()
mock_storage.generate_signed_url.return_value = "https://storage.googleapis.com/signed-url"
mock_storage_cls.return_value = mock_storage
from backend.api.routes.jobs import get_instrumental_analysis
import asyncio
result = asyncio.get_event_loop().run_until_complete(
get_instrumental_analysis("test-job-123")
)
assert "waveform_url" in result
# Waveform URL should be generated from the file_urls
assert result["waveform_url"] == "https://storage.googleapis.com/signed-url"
def test_get_analysis_silent_audio(self, mock_job_manager, mock_storage_service, silent_job):
"""GET /instrumental-analysis should correctly report silent audio."""
mock_job_manager.get_job.return_value = silent_job
from backend.api.routes.jobs import get_instrumental_analysis
import asyncio
result = asyncio.get_event_loop().run_until_complete(
get_instrumental_analysis("test-job-silent")
)
assert result["analysis"]["has_audible_content"] is False
assert result["analysis"]["recommended_selection"] == "clean"
assert len(result["analysis"]["audible_segments"]) == 0
def test_get_analysis_job_not_found(self, mock_job_manager):
"""GET /instrumental-analysis should return 404 for non-existent job."""
mock_job_manager.get_job.return_value = None
from backend.api.routes.jobs import get_instrumental_analysis
from fastapi import HTTPException
import asyncio
with pytest.raises(HTTPException) as exc_info:
asyncio.get_event_loop().run_until_complete(
get_instrumental_analysis("non-existent")
)
assert exc_info.value.status_code == 404
def test_get_analysis_wrong_status(self, mock_job_manager, sample_job):
"""GET /instrumental-analysis should return 400 for wrong job status."""
sample_job.status = JobStatus.PENDING
mock_job_manager.get_job.return_value = sample_job
from backend.api.routes.jobs import get_instrumental_analysis
from fastapi import HTTPException
import asyncio
with pytest.raises(HTTPException) as exc_info:
asyncio.get_event_loop().run_until_complete(
get_instrumental_analysis("test-job-123")
)
assert exc_info.value.status_code == 400
class TestAudioStream:
"""Tests for GET /api/jobs/{job_id}/audio-stream/{stem_type}."""
def test_stream_backing_vocals_valid(self, mock_job_manager, sample_job):
"""Should return redirect for backing vocals stream."""
mock_job_manager.get_job.return_value = sample_job
from backend.api.routes.jobs import stream_audio
import asyncio
# This will try to stream from GCS which we can't test easily
# Instead, verify the function exists and has correct signature
assert callable(stream_audio)
def test_stream_invalid_stem_type(self, mock_job_manager, sample_job):
"""Should return 400 for invalid stem type."""
mock_job_manager.get_job.return_value = sample_job
from backend.api.routes.jobs import stream_audio
from fastapi import HTTPException
import asyncio
with pytest.raises(HTTPException) as exc_info:
asyncio.get_event_loop().run_until_complete(
stream_audio("test-job-123", "invalid_stem")
)
assert exc_info.value.status_code == 400
def test_stream_job_not_found(self, mock_job_manager):
"""Should return 404 for non-existent job."""
mock_job_manager.get_job.return_value = None
from backend.api.routes.jobs import stream_audio
from fastapi import HTTPException
import asyncio
with pytest.raises(HTTPException) as exc_info:
asyncio.get_event_loop().run_until_complete(
stream_audio("non-existent", "backing_vocals")
)
assert exc_info.value.status_code == 404
class TestCreateCustomInstrumental:
"""Tests for POST /api/jobs/{job_id}/create-custom-instrumental."""
@pytest.fixture
def mock_audio_editing_service(self):
"""Mock the audio editing service."""
with patch('backend.api.routes.jobs.AudioEditingService') as mock:
mock_instance = MagicMock()
mock_instance.create_custom_instrumental.return_value = MagicMock(
output_path="jobs/test/stems/custom_instrumental.flac",
mute_regions_applied=[
MagicMock(start_seconds=10.0, end_seconds=20.0),
],
total_muted_duration_seconds=10.0,
output_duration_seconds=180.0,
)
mock.return_value = mock_instance
yield mock_instance
def test_create_custom_validates_mute_regions(self):
"""Should validate mute regions at model level."""
from backend.models.requests import CreateCustomInstrumentalRequest, MuteRegionRequest
from pydantic import ValidationError
# Empty mute regions should fail at model validation
with pytest.raises(ValidationError) as exc_info:
CreateCustomInstrumentalRequest(mute_regions=[])
assert "At least one mute region is required" in str(exc_info.value)
def test_create_custom_job_not_found(self, mock_job_manager):
"""Should return 404 for non-existent job."""
mock_job_manager.get_job.return_value = None
from backend.api.routes.jobs import create_custom_instrumental
from backend.models.requests import CreateCustomInstrumentalRequest, MuteRegionRequest
from fastapi import HTTPException
import asyncio
request = CreateCustomInstrumentalRequest(
mute_regions=[MuteRegionRequest(start_seconds=10.0, end_seconds=20.0)]
)
with pytest.raises(HTTPException) as exc_info:
asyncio.get_event_loop().run_until_complete(
create_custom_instrumental("non-existent", request)
)
assert exc_info.value.status_code == 404
def test_create_custom_wrong_status(self, mock_job_manager, sample_job):
"""Should return 400 for wrong job status."""
sample_job.status = JobStatus.PENDING
mock_job_manager.get_job.return_value = sample_job
from backend.api.routes.jobs import create_custom_instrumental
from backend.models.requests import CreateCustomInstrumentalRequest, MuteRegionRequest
from fastapi import HTTPException
import asyncio
request = CreateCustomInstrumentalRequest(
mute_regions=[MuteRegionRequest(start_seconds=10.0, end_seconds=20.0)]
)
with pytest.raises(HTTPException) as exc_info:
asyncio.get_event_loop().run_until_complete(
create_custom_instrumental("test-job-123", request)
)
assert exc_info.value.status_code == 400
class TestGetWaveformData:
"""Tests for GET /api/jobs/{job_id}/waveform-data."""
def test_get_waveform_data_job_not_found(self, mock_job_manager):
"""Should return 404 for non-existent job."""
mock_job_manager.get_job.return_value = None
from backend.api.routes.jobs import get_waveform_data
from fastapi import HTTPException
import asyncio
with pytest.raises(HTTPException) as exc_info:
asyncio.get_event_loop().run_until_complete(
get_waveform_data("non-existent")
)
assert exc_info.value.status_code == 404
def test_get_waveform_data_wrong_status(self, mock_job_manager, sample_job):
"""Should return 400 for wrong job status."""
sample_job.status = JobStatus.PENDING
mock_job_manager.get_job.return_value = sample_job
from backend.api.routes.jobs import get_waveform_data
from fastapi import HTTPException
import asyncio
with pytest.raises(HTTPException) as exc_info:
asyncio.get_event_loop().run_until_complete(
get_waveform_data("test-job-123")
)
assert exc_info.value.status_code == 400
def test_waveform_data_endpoint_exists(self):
"""Verify the endpoint function exists and is callable."""
from backend.api.routes.jobs import get_waveform_data
assert callable(get_waveform_data)
# Verify it's an async function
import inspect
assert inspect.iscoroutinefunction(get_waveform_data)
class TestRequestModels:
"""Tests for API request models."""
def test_mute_region_request_valid(self):
"""MuteRegionRequest should accept valid values."""
from backend.models.requests import MuteRegionRequest
region = MuteRegionRequest(start_seconds=10.0, end_seconds=20.0)
assert region.start_seconds == 10.0
assert region.end_seconds == 20.0
def test_mute_region_request_invalid_start(self):
"""MuteRegionRequest should reject negative start."""
from backend.models.requests import MuteRegionRequest
from pydantic import ValidationError
with pytest.raises(ValidationError):
MuteRegionRequest(start_seconds=-1.0, end_seconds=20.0)
def test_mute_region_request_invalid_order(self):
"""MuteRegionRequest should reject end before start."""
from backend.models.requests import MuteRegionRequest
from pydantic import ValidationError
with pytest.raises(ValidationError):
MuteRegionRequest(start_seconds=20.0, end_seconds=10.0)
def test_create_custom_instrumental_request_valid(self):
"""CreateCustomInstrumentalRequest should accept valid mute regions."""
from backend.models.requests import (
CreateCustomInstrumentalRequest,
MuteRegionRequest,
)
request = CreateCustomInstrumentalRequest(
mute_regions=[
MuteRegionRequest(start_seconds=10.0, end_seconds=20.0),
MuteRegionRequest(start_seconds=60.0, end_seconds=80.0),
]
)
assert len(request.mute_regions) == 2
class TestInstrumentalSelectionExtension:
"""Tests for extended instrumental selection (including 'custom')."""
def test_instrumental_selection_accepts_custom(self):
"""InstrumentalSelection should accept 'custom' as valid selection."""
from backend.models.requests import InstrumentalSelection
selection = InstrumentalSelection(selection="custom")
assert selection.selection == "custom"
def test_instrumental_selection_accepts_clean(self):
"""InstrumentalSelection should accept 'clean' as valid selection."""
from backend.models.requests import InstrumentalSelection
selection = InstrumentalSelection(selection="clean")
assert selection.selection == "clean"
def test_instrumental_selection_accepts_with_backing(self):
"""InstrumentalSelection should accept 'with_backing' as valid selection."""
from backend.models.requests import InstrumentalSelection
selection = InstrumentalSelection(selection="with_backing")
assert selection.selection == "with_backing"
def test_instrumental_selection_rejects_invalid(self):
"""InstrumentalSelection should reject invalid values."""
from backend.models.requests import InstrumentalSelection
from pydantic import ValidationError
with pytest.raises(ValidationError):
InstrumentalSelection(selection="invalid_option")
+78
View File
@@ -869,3 +869,81 @@ class TestDownloadAudioWithUrl:
# Should have called storage.download_file
mock_storage.download_file.assert_called()
class TestBackingVocalsAnalysis:
"""Tests for backing vocals analysis in render_video_worker."""
def test_analyze_backing_vocals_function_exists(self):
"""Test that _analyze_backing_vocals function exists in render_video_worker."""
from backend.workers.render_video_worker import _analyze_backing_vocals
assert callable(_analyze_backing_vocals)
def test_analyze_backing_vocals_is_async(self):
"""Test that _analyze_backing_vocals is an async function."""
import inspect
from backend.workers.render_video_worker import _analyze_backing_vocals
assert inspect.iscoroutinefunction(_analyze_backing_vocals)
def test_render_video_worker_imports_analysis_service(self):
"""Test that render_video_worker can import AudioAnalysisService."""
# This verifies the import path is correct
from backend.services.audio_analysis_service import AudioAnalysisService
assert AudioAnalysisService is not None
@pytest.mark.asyncio
async def test_analyze_backing_vocals_handles_missing_job(self):
"""Test that analysis returns early when job not found (no error stored)."""
mock_job_manager = MagicMock()
mock_job_manager.get_job.return_value = None # No job found
mock_job_manager.update_state_data = MagicMock()
mock_storage = MagicMock()
mock_logger = MagicMock()
from backend.workers.render_video_worker import _analyze_backing_vocals
# Should not raise when job not found, just log warning and return
await _analyze_backing_vocals(
"nonexistent", mock_job_manager, mock_storage, mock_logger
)
# Should log warning but not update state (early return)
mock_logger.warning.assert_called()
# No state_data update since we return early
mock_job_manager.update_state_data.assert_not_called()
@pytest.mark.asyncio
async def test_analyze_backing_vocals_handles_missing_stems(self):
"""Test that analysis returns early when stems not found (no error stored)."""
mock_job = MagicMock()
mock_job.file_urls = {} # No stems
mock_job_manager = MagicMock()
mock_job_manager.get_job.return_value = mock_job
mock_job_manager.update_state_data = MagicMock()
mock_storage = MagicMock()
mock_logger = MagicMock()
from backend.workers.render_video_worker import _analyze_backing_vocals
# Should not raise when stems not found, just log warning and return
await _analyze_backing_vocals(
"test123", mock_job_manager, mock_storage, mock_logger
)
# Should log warning but not update state (early return)
mock_logger.warning.assert_called()
# No state_data update since we return early
mock_job_manager.update_state_data.assert_not_called()
def test_analysis_service_can_be_instantiated(self):
"""Test that AudioAnalysisService can be instantiated."""
from backend.services.audio_analysis_service import AudioAnalysisService
mock_storage = MagicMock()
service = AudioAnalysisService(storage_service=mock_storage)
assert service is not None
assert service.storage_service == mock_storage
+109 -1
View File
@@ -266,7 +266,11 @@ async def process_render_video(job_id: str) -> bool:
job_log.info("Uploaded corrected.txt")
logger.info(f"Job {job_id}: Uploaded corrected.txt")
# 11. Transition to awaiting instrumental selection
# 11. Analyze backing vocals for intelligent instrumental selection
job_log.info("Analyzing backing vocals for instrumental selection...")
await _analyze_backing_vocals(job_id, job_manager, storage, job_log)
# 12. Transition to awaiting instrumental selection
job_manager.transition_to_state(
job_id=job_id,
new_status=JobStatus.AWAITING_INSTRUMENTAL_SELECTION,
@@ -302,5 +306,109 @@ def _extract_gcs_path(url: str) -> str:
return url
async def _analyze_backing_vocals(
job_id: str,
job_manager: JobManager,
storage: StorageService,
job_log: logging.Logger,
) -> None:
"""
Analyze backing vocals to help with intelligent instrumental selection.
This function:
1. Downloads the backing vocals stem from GCS
2. Runs audio analysis to detect audible content
3. Generates a waveform visualization image
4. Stores analysis results and waveform URL in job state
The analysis data is then used by the frontend to provide an
intelligent instrumental selection experience.
"""
from backend.services.audio_analysis_service import AudioAnalysisService
try:
# Get the job to access file URLs
job = job_manager.get_job(job_id)
if not job:
job_log.warning(f"Could not get job {job_id} for backing vocals analysis")
return
# Get backing vocals path
backing_vocals_path = job.file_urls.get('stems', {}).get('backing_vocals')
if not backing_vocals_path:
job_log.warning("No backing vocals file found - skipping analysis")
return
job_log.info(f"Analyzing backing vocals: {backing_vocals_path}")
# Create analysis service and run analysis
analysis_service = AudioAnalysisService()
# Define output path for waveform
waveform_gcs_path = f"jobs/{job_id}/analysis/backing_vocals_waveform.png"
# Run analysis and generate waveform
result, waveform_path = analysis_service.analyze_and_generate_waveform(
gcs_audio_path=backing_vocals_path,
job_id=job_id,
gcs_waveform_destination=waveform_gcs_path,
)
# Store analysis results in job state_data
analysis_data = {
'has_audible_content': result.has_audible_content,
'total_duration_seconds': result.total_duration_seconds,
'audible_segments': [
{
'start_seconds': seg.start_seconds,
'end_seconds': seg.end_seconds,
'duration_seconds': seg.duration_seconds,
'avg_amplitude_db': seg.avg_amplitude_db,
'peak_amplitude_db': seg.peak_amplitude_db,
}
for seg in result.audible_segments
],
'recommended_selection': result.recommended_selection.value,
'total_audible_duration_seconds': result.total_audible_duration_seconds,
'audible_percentage': result.audible_percentage,
'silence_threshold_db': result.silence_threshold_db,
}
job_manager.update_state_data(job_id, 'backing_vocals_analysis', analysis_data)
# Store waveform URL
job_manager.update_file_url(job_id, 'analysis', 'backing_vocals_waveform', waveform_path)
job_log.info(
f"Backing vocals analysis complete: "
f"has_audible={result.has_audible_content}, "
f"segments={result.segment_count}, "
f"recommendation={result.recommended_selection.value}"
)
# Log segment details if there are any
if result.audible_segments:
job_log.info(f"Audible segments ({len(result.audible_segments)}):")
for i, seg in enumerate(result.audible_segments[:5]): # Log first 5
job_log.info(
f" [{i+1}] {seg.start_seconds:.1f}s - {seg.end_seconds:.1f}s "
f"({seg.duration_seconds:.1f}s, avg: {seg.avg_amplitude_db:.1f}dB)"
)
if len(result.audible_segments) > 5:
job_log.info(f" ... and {len(result.audible_segments) - 5} more")
except Exception as e:
# Log the error but don't fail the job - analysis is a nice-to-have
job_log.warning(f"Backing vocals analysis failed (non-fatal): {e}")
logger.warning(f"Job {job_id}: Backing vocals analysis failed: {e}")
# Store empty analysis so the frontend knows analysis was attempted
job_manager.update_state_data(job_id, 'backing_vocals_analysis', {
'has_audible_content': None,
'analysis_error': str(e),
'recommended_selection': 'review_needed',
})
# For compatibility with worker service
render_video_worker = process_render_video
+4 -3
View File
@@ -54,6 +54,7 @@ steps:
- 'us-central1-docker.pkg.dev/$PROJECT_ID/karaoke-repo/karaoke-backend:latest'
# Deploy to Cloud Run with version from pyproject.toml
# Uses Cloud Tasks for worker coordination (scalable architecture)
- name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
entrypoint: 'bash'
args:
@@ -71,10 +72,10 @@ steps:
--cpu-boost \
--execution-environment gen2 \
--timeout 1800 \
--concurrency 4 \
--max-instances 10 \
--concurrency 1 \
--max-instances 50 \
--min-instances 0 \
--set-env-vars "GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GCS_BUCKET_NAME=karaoke-gen-storage-$PROJECT_ID,FIRESTORE_COLLECTION=jobs,ENVIRONMENT=production,AUDIO_SEPARATOR_API_URL=https://nomadkaraoke--audio-separator-api.modal.run,KARAOKE_GEN_VERSION=$$VERSION,DEFAULT_DROPBOX_PATH=/MediaUnsynced/Karaoke/Tracks-Organized,DEFAULT_GDRIVE_FOLDER_ID=1laRKAyxo0v817SstfM5XkpbWiNKNAMSX" \
--set-env-vars "GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GCS_BUCKET_NAME=karaoke-gen-storage-$PROJECT_ID,FIRESTORE_COLLECTION=jobs,ENVIRONMENT=production,AUDIO_SEPARATOR_API_URL=https://nomadkaraoke--audio-separator-api.modal.run,KARAOKE_GEN_VERSION=$$VERSION,DEFAULT_DROPBOX_PATH=/MediaUnsynced/Karaoke/Tracks-Organized,DEFAULT_GDRIVE_FOLDER_ID=1laRKAyxo0v817SstfM5XkpbWiNKNAMSX,ENABLE_CLOUD_TASKS=true,CLOUD_RUN_SERVICE_URL=https://api.nomadkaraoke.com,GCP_REGION=us-central1" \
--set-secrets "AUDIOSHAKE_API_TOKEN=audioshake-api-key:latest,GENIUS_API_TOKEN=genius-api-key:latest,SPOTIFY_COOKIE_SP_DC=spotify-cookie:latest,RAPIDAPI_KEY=rapidapi-key:latest,DEFAULT_DISCORD_WEBHOOK_URL=discord-releases-webhook:latest,ADMIN_TOKENS=admin-tokens:latest"
images:
@@ -1,7 +1,7 @@
# Backend Feature Parity Plan
**Last Updated:** 2024-12-11
**Status:** ✅ Core Feature Parity Achieved (v0.71.0) | Batch 1 ✅ | Batch 2 ✅ | Batch 3 ✅ | Batch 4 ✅
**Status:** ✅ Core Feature Parity Achieved (v0.71.0) | Batch 1 ✅ | Batch 2 ✅ | Batch 3 ✅ | Batch 4 ✅ | Batch 5 ✅
This document tracks the progress toward complete feature parity between the local `karaoke-gen` CLI and the cloud backend, enabling the `karaoke-gen-remote` CLI to have equivalent functionality.
@@ -15,14 +15,14 @@ This document tracks the progress toward complete feature parity between the loc
| Style Configuration | 1 | 4 | **25%** | S2-S4 are MEDIUM priority |
| Workflow Control | 0 | 3 | **0%** | W1/W2 HIGH, W7 MEDIUM (skip flags deferred) |
| Audio Processing | 4 | 4 | **100%** | ✅ **Batch 2 & 3 Complete** (AP1-AP3, AP5) |
| Input Modes | 2 | 3 | **67%** | ✅ **Batch 4 Complete** (P2), P3 remaining |
| Audio Fetching | 0 | 1 | **0%** | A1 is HIGH priority |
| Input Modes | 3 | 3 | **100%** | ✅ **Batch 4 & 5 Complete** (P2, P3) |
| Audio Fetching | 1 | 1 | **100%** | ✅ **Batch 5 Complete** (A1) |
| Flags to Remove | - | - | - | I3-I6, AP6 (simplify codebase) |
**Overall:** Core workflow complete. See [CLI Parameter Parity Analysis](#-cli-parameter-parity-analysis) for detailed parameter list with implementation plans.
**Priority Summary:**
- **HIGH**: L1-L4 (lyrics), AP1-AP5 (audio models/instrumental), P2-P3 (YouTube/flacfetch), A1 (interactive search), W1/W2 (prep/finalise phases), F15 (keep-brand-code)
- **HIGH**: L1-L4 ✅, AP1-AP5 ✅, P3 ✅, A1 ✅ | P2 (YouTube URLs), W1/W2 (prep/finalise phases), F15 (keep-brand-code)
- **MEDIUM**: S2-S4 (style overrides/video bg), W7 (edit-lyrics), F14 (email template)
- **LOW/DEFERRED**: W3-W6 (skip flags), D2-D3 (debugging)
- **REMOVE**: I3, I4, I5, I6, AP6 (unnecessary options)
@@ -80,12 +80,12 @@ This section provides a comprehensive comparison of all CLI parameters between `
|---|-----------|-------|--------|-------------|
| P1 | `<file>` | ✅ | ✅ | **Local audio file path.** Copies file to output directory, converts to WAV for processing. Supports MP3, FLAC, WAV, M4A, OGG, AAC. |
| P2 | `<url>` (YouTube) | ✅ | ✅ | **YouTube/online URL.** Uses yt-dlp to download audio and extract metadata (artist/title from video title). |
| P3 | `<artist> <title>` | ✅ | ❌ | **Audio search mode.** When no file is provided, uses flacfetch to search Deezer/Tidal/etc for high-quality audio and downloads it. |
| P3 | `<artist> <title>` | ✅ | ✅ | **Audio search mode.** When no file is provided, uses flacfetch to search Deezer/Tidal/etc for high-quality audio and downloads it. |
| P4 | `<folder>` | ✅ | ❌ | **Batch folder processing.** Process all audio files in a folder, using `--filename_pattern` to extract track titles from filenames. |
**Remote Implementation Status:** ✅ **BATCH 4 COMPLETE** (v0.71.26)
**Remote Implementation Status:** ✅ **BATCH 4 & 5 COMPLETE** (v0.71.42)
- **P2 YouTube URLs**: ✅ IMPLEMENTED. Backend accepts URL via `/api/jobs/create-from-url` endpoint. Uses yt-dlp to download audio and extract metadata (artist/title). Remote CLI detects URLs and routes to URL endpoint.
- **P3 Flacfetch search**: HIGH PRIORITY. Backend integrates flacfetch to search Deezer/Tidal/etc. IMPORTANT: Must support interactive mode via API - return search results to client, let user select, then proceed. Default should be interactive (not auto-select). Use case: Eventually expose audio source selection in web UI.
- **P3 Flacfetch search**: ✅ IMPLEMENTED. Remote CLI submits artist+title, backend searches via flacfetch. Returns results for interactive selection (or auto-selects with `-y`/`--auto-download`). New job statuses: `searching_audio`, `awaiting_audio_selection`, `downloading_audio`.
- **P4 Folder batch**: LOW PRIORITY. Could accept ZIP upload, process each as separate job. Defer for now.
---
@@ -149,12 +149,12 @@ This section provides a comprehensive comparison of all CLI parameters between `
| # | Parameter | Local | Remote | Description |
|---|-----------|-------|--------|-------------|
| A1 | `--auto-download` | ✅ | ❌ | **Auto-select audio source.** When using artist+title search mode (flacfetch), automatically select the best quality source instead of prompting for manual selection. Useful for scripted/batch processing. |
| A1 | `--auto-download` | ✅ | ✅ | **Auto-select audio source.** When using artist+title search mode (flacfetch), automatically select the best quality source instead of prompting for manual selection. Useful for scripted/batch processing. |
**Remote Implementation Plan:**
- **A1 `--auto-download`**: HIGH PRIORITY. Backend must support BOTH modes:
- **Interactive (default)**: API returns search results to client. Client displays options, user selects, client sends selection back to backend. Use case: Web UI will show audio source picker.
- **Auto-download (`--auto-download` or `-y`)**: Backend auto-selects best quality source. Use case: Automated/batch processing.
**Remote Implementation Status:** ✅ **BATCH 5 COMPLETE** (v0.71.28)
- **A1 `--auto-download`**: ✅ IMPLEMENTED. Backend supports BOTH modes:
- **Interactive (default)**: API returns search results to client. Client displays options, user selects via `/api/audio-search/{job_id}/select` endpoint.
- **Auto-download (`--auto-download` or `-y`)**: Backend auto-selects best quality source using flacfetch's ranking.
---
@@ -394,22 +394,28 @@ Bump the patch version in `pyproject.toml` before committing.
---
### Batch 5: Flacfetch Audio Search (HIGH)
### Batch 5: Flacfetch Audio Search (HIGH) ✅ COMPLETE
**Parameters:** P3 `<artist> <title>` (search mode), A1 `--auto-download`
**Scope:**
- Remote CLI: Detect artist+title without file, trigger search flow
- Backend: New endpoint to search for audio sources via flacfetch
- Backend: Return search results to client for interactive selection
- Remote CLI: Display results, let user select, send selection back
- Backend: Download selected audio, proceed with job
- Support `--auto-download` / `-y` to skip interactive selection
**Status:** ✅ **IMPLEMENTED** - PR #13 merged (v0.71.28)
**Files to modify:**
- `karaoke_gen/utils/remote_cli.py` - search flow, display results, selection
- `backend/api/routes/` - new search endpoint
- `backend/services/` - flacfetch integration service
- `backend/workers/` - download from selected source
**Implementation Summary:**
- Remote CLI: Detects artist+title without file, calls `/api/audio-search/search` endpoint
- Backend: New `AudioSearchService` integrates flacfetch for searching
- Backend: New job statuses `searching_audio`, `awaiting_audio_selection`, `downloading_audio`
- Backend: Returns search results for interactive selection, or auto-selects with `auto_download=true`
- Remote CLI: Displays results interactively, user selects, sends to `/api/audio-search/{job_id}/select`
- Backend: Downloads selected audio to GCS, proceeds with normal job flow
- Support `--auto-download` / `-y` for non-interactive auto-selection
**Files modified:**
- `karaoke_gen/utils/remote_cli.py` - search flow, display results, `search_audio()`, `select_audio_source()`, `handle_audio_selection()`
- `backend/api/routes/audio_search.py` - NEW: search and select endpoints
- `backend/services/audio_search_service.py` - NEW: flacfetch integration service
- `backend/models/job.py` - New statuses and fields (`audio_search_artist`, `audio_search_title`, `auto_download`)
- `backend/main.py` - Register audio_search router
**Tests added:** 20+ unit tests covering Job model fields, AudioSearchService, state transitions
**Complexity:** High (new interactive API flow, new service integration)
@@ -516,14 +522,14 @@ Bump the patch version in `pyproject.toml` before committing.
| 2 | AP1-AP3 (model selection) | HIGH | Low | ✅ **COMPLETE** (PR #9) |
| 3 | AP5 (existing instrumental) | HIGH | Medium | ✅ **COMPLETE** (PR #10) |
| 4 | P2 (YouTube URLs) | HIGH | Medium-High | ✅ **COMPLETE** |
| 5 | P3, A1 (flacfetch search) | HIGH | High | ⏳ Pending |
| 5 | P3, A1 (flacfetch search) | HIGH | High | ✅ **COMPLETE** (PR #13) |
| 6 | W1, W2, F15 (two-phase) | HIGH | High | ⏳ Pending |
| 7 | S2 (style overrides) | MEDIUM | Medium | ⏳ Pending |
| 8 | S3, S4 (video background) | MEDIUM | Medium | ⏳ Pending |
| 9 | W7 (edit-lyrics) | MEDIUM | Medium-High | ⏳ Pending |
| 10 | F14, D2, D3, removals | LOW | Mixed | ⏳ Pending |
**Recommended Order:** ~~1~~ → ~~2~~ → ~~3~~ → ~~4~~ → 5 → 6 → 7 → 8 → 9 → 10
**Recommended Order:** ~~1~~ → ~~2~~ → ~~3~~ → ~~4~~ → ~~5~~ → 6 → 7 → 8 → 9 → 10
Batches 1-4 are quick wins that add significant value. Batches 5-6 are larger but high priority. Batches 7-10 can be done as time permits.
@@ -632,6 +638,7 @@ The karaoke-gen system supports multiple interfaces to the same core functionali
| Feature | Version | PR | Notes |
|---------|---------|-----|-------|
| Flacfetch audio search | v0.71.42 | #13 | `artist title` (search mode), `--auto-download` - search and download audio by artist+title |
| YouTube URL input | v0.71.26 | - | `<url>` positional argument for YouTube/online URLs |
| Existing instrumental | v0.71.26 | #10 | `--existing_instrumental` - upload and use user-provided instrumental |
| Audio model selection | v0.71.24 | #9 | `--clean_instrumental_model`, `--backing_vocals_models`, `--other_stems_models` |
@@ -645,7 +652,6 @@ The karaoke-gen system supports multiple interfaces to the same core functionali
| Skip separation/transcription | MEDIUM | Workflow control for re-processing |
| Edit lyrics mode | MEDIUM | `--edit-lyrics` for fixing existing tracks |
| Background video | MEDIUM | `--background_video` requires video upload |
| Audio search (flacfetch) | HIGH | Artist+title search, auto-download |
| Two-phase workflow | HIGH | `--prep-only`, `--finalise-only` |
| Batch folder processing | LOW | Process multiple files at once |
| Gmail draft creation | LOW | Nice-to-have, not blocking |
@@ -812,6 +818,19 @@ DEFAULT_DISCORD_WEBHOOK_URL=https://discord.com/...
## Recent Changes Log
### 2024-12-11: v0.71.28 - Batch 5 Complete (Flacfetch Audio Search)
**PR #13: Flacfetch Audio Search for Remote CLI**
- ✅ `artist title` (search mode) - Search for audio by artist and title without providing a file
- ✅ `--auto-download` - Auto-select best audio source (skip interactive selection)
- New job statuses: `searching_audio`, `awaiting_audio_selection`, `downloading_audio`
- New API endpoints: `POST /api/audio-search/search`, `GET /api/audio-search/{job_id}/results`, `POST /api/audio-search/{job_id}/select`
- Interactive mode: Returns search results for user selection
- Auto mode: Uses flacfetch's quality ranking to auto-select best source
- Added 20+ unit tests for new functionality
- Files: `remote_cli.py`, `audio_search.py` (new route), `audio_search_service.py` (new service), `job.py`
### 2024-12-11: v0.71.26 - Batch 3 Complete (Existing Instrumental Support)
**PR #10: Existing Instrumental Support for Remote CLI**
@@ -907,12 +926,13 @@ DEFAULT_DISCORD_WEBHOOK_URL=https://discord.com/...
- Requires: yt-dlp in container
- Enables: Processing niche live versions only on YouTube
5. ✅ **Flacfetch Audio Search** (Batch 5 - COMPLETE)
- Interactive audio source selection via API
- v0.71.28
### Medium-Term: Workflow Features
1. **Flacfetch Audio Search** (Batch 5)
- Interactive audio source selection via API
2. **Two-Phase Workflow** (Batch 6)
1. **Two-Phase Workflow** (Batch 6)
- `--prep-only` and `--finalise-only` modes
3. **Style Override** (Batch 7)
@@ -1,7 +1,7 @@
# Scalable Architecture Plan
**Last Updated:** 2025-12-11
**Status:** Analysis Complete - Ready for Implementation
**Status:** Phase 1 Complete - Cloud Tasks Enabled
This document outlines the plan for evolving karaoke-gen's cloud backend to support **100+ concurrent jobs** with no performance degradation, while also achieving a clean, maintainable codebase with proper separation of concerns.
@@ -756,7 +756,11 @@ wait
## Success Criteria
### Phase 1 (Cloud Tasks)
- [ ] 50 concurrent jobs complete without failures
- [x] Cloud Tasks queues created and configured via Pulumi
- [x] WorkerService updated to support Cloud Tasks mode
- [x] Deployment configured with ENABLE_CLOUD_TASKS=true
- [x] Container concurrency set to 1 for true isolation
- [ ] 50 concurrent jobs complete without failures (to be validated)
- [ ] Processing time per job unchanged (same as 1 job)
- [ ] No resource contention (CPU/memory per job consistent)
- [ ] Automatic retry on transient failures works
@@ -0,0 +1,603 @@
"use client"
import { useParams, useRouter } from "next/navigation"
import { useState, useEffect, useCallback } from "react"
import { AppHeader } from "@/components/app-header"
import { ProtectedRoute } from "@/components/protected-route"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { Alert, AlertDescription } from "@/components/ui/alert"
import { Badge } from "@/components/ui/badge"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { Label } from "@/components/ui/label"
import { Skeleton } from "@/components/ui/skeleton"
import {
WaveformDisplay,
AudioPlayer,
RegionSelector,
} from "@/components/instrumental-review"
import {
ArrowLeft,
AlertCircle,
CheckCircle2,
Loader2,
Music,
VolumeX,
Volume2,
} from "lucide-react"
interface AudibleSegment {
start_seconds: number
end_seconds: number
duration_seconds: number
avg_amplitude_db: number
peak_amplitude_db?: number
}
interface MuteRegion {
start_seconds: number
end_seconds: number
}
interface AnalysisData {
has_audible_content: boolean
total_duration_seconds: number
audible_segments: AudibleSegment[]
recommended_selection: string
total_audible_duration_seconds: number
audible_percentage: number
silence_threshold_db: number
}
interface InstrumentalAnalysisResponse {
job_id: string
artist: string
title: string
status: string
analysis: AnalysisData
audio_urls: {
clean_instrumental: string | null
backing_vocals: string | null
with_backing: string | null
custom_instrumental: string | null
}
waveform_url: string | null
has_custom_instrumental: boolean
}
// Get API base URL from environment or default to relative path
const API_BASE = process.env.NEXT_PUBLIC_API_URL || "/api"
function InstrumentalReviewContent() {
const params = useParams()
const router = useRouter()
const jobId = params.id as string
// State
const [isLoading, setIsLoading] = useState(true)
const [error, setError] = useState<string | null>(null)
const [analysisData, setAnalysisData] = useState<InstrumentalAnalysisResponse | null>(null)
const [waveformData, setWaveformData] = useState<{ amplitudes: number[]; duration: number } | null>(null)
const [selectedOption, setSelectedOption] = useState<string>("clean")
const [muteRegions, setMuteRegions] = useState<MuteRegion[]>([])
const [isSelectionMode, setIsSelectionMode] = useState(false)
const [currentTime, setCurrentTime] = useState(0)
const [seekTo, setSeekTo] = useState<number | undefined>(undefined)
const [isCreatingCustom, setIsCreatingCustom] = useState(false)
const [isSubmitting, setIsSubmitting] = useState(false)
const [activeAudio, setActiveAudio] = useState<"clean" | "backing" | "with_backing" | "custom">("backing")
// Fetch analysis data
const fetchAnalysis = useCallback(async () => {
try {
setIsLoading(true)
setError(null)
const response = await fetch(`${API_BASE}/jobs/${jobId}/instrumental-analysis`)
if (!response.ok) {
const errorData = await response.json().catch(() => ({}))
throw new Error(errorData.detail || `Failed to fetch analysis: ${response.status}`)
}
const data: InstrumentalAnalysisResponse = await response.json()
setAnalysisData(data)
// Set initial selection based on recommendation
const recommendation = data.analysis.recommended_selection
if (recommendation === "clean") {
setSelectedOption("clean")
} else if (recommendation === "with_backing") {
setSelectedOption("with_backing")
} else {
// "review_needed" - default to with_backing but user should review
setSelectedOption("with_backing")
}
// Fetch waveform data for interactive display
const waveformResponse = await fetch(`${API_BASE}/jobs/${jobId}/waveform-data?num_points=600`)
if (waveformResponse.ok) {
const waveform = await waveformResponse.json()
setWaveformData(waveform)
}
} catch (err) {
setError(err instanceof Error ? err.message : "Failed to load analysis data")
} finally {
setIsLoading(false)
}
}, [jobId])
useEffect(() => {
fetchAnalysis()
}, [fetchAnalysis])
// Handle seeking from waveform click
const handleSeek = (time: number) => {
setSeekTo(time)
// Reset seekTo after a short delay
setTimeout(() => setSeekTo(undefined), 100)
}
// Handle adding a mute region
const handleAddRegion = (region: MuteRegion) => {
setMuteRegions((prev) => {
// Check for overlaps and merge if needed
const newRegions = [...prev, region].sort((a, b) => a.start_seconds - b.start_seconds)
// Merge overlapping regions
const merged: MuteRegion[] = []
for (const r of newRegions) {
if (merged.length === 0) {
merged.push(r)
} else {
const last = merged[merged.length - 1]
if (r.start_seconds <= last.end_seconds) {
last.end_seconds = Math.max(last.end_seconds, r.end_seconds)
} else {
merged.push(r)
}
}
}
return merged
})
setIsSelectionMode(false)
}
// Handle removing a mute region
const handleRemoveRegion = (index: number) => {
setMuteRegions((prev) => prev.filter((_, i) => i !== index))
}
// Handle clearing all mute regions
const handleClearAll = () => {
setMuteRegions([])
}
// Create custom instrumental
const handleCreateCustom = async () => {
if (muteRegions.length === 0) {
setError("Please select at least one region to mute")
return
}
try {
setIsCreatingCustom(true)
setError(null)
const response = await fetch(`${API_BASE}/jobs/${jobId}/create-custom-instrumental`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
mute_regions: muteRegions.map((r) => ({
start_seconds: r.start_seconds,
end_seconds: r.end_seconds,
})),
}),
})
if (!response.ok) {
const errorData = await response.json().catch(() => ({}))
throw new Error(errorData.detail || "Failed to create custom instrumental")
}
// Refresh analysis to get updated URLs
await fetchAnalysis()
setSelectedOption("custom")
setActiveAudio("custom")
} catch (err) {
setError(err instanceof Error ? err.message : "Failed to create custom instrumental")
} finally {
setIsCreatingCustom(false)
}
}
// Submit selection
const handleSubmit = async () => {
let selection = selectedOption
// If "review" is selected, determine based on mute regions
if (selectedOption === "review") {
if (muteRegions.length > 0 && analysisData?.has_custom_instrumental) {
selection = "custom"
} else {
selection = "with_backing"
}
}
try {
setIsSubmitting(true)
setError(null)
const response = await fetch(`${API_BASE}/jobs/${jobId}/select-instrumental`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ selection }),
})
if (!response.ok) {
const errorData = await response.json().catch(() => ({}))
throw new Error(errorData.detail || "Failed to submit selection")
}
// Navigate back to job page
router.push(`/jobs/${jobId}`)
} catch (err) {
setError(err instanceof Error ? err.message : "Failed to submit selection")
} finally {
setIsSubmitting(false)
}
}
// Get current audio URL based on active selection
const getCurrentAudioUrl = () => {
if (!analysisData) return null
switch (activeAudio) {
case "clean":
return analysisData.audio_urls.clean_instrumental
case "backing":
return analysisData.audio_urls.backing_vocals
case "with_backing":
return analysisData.audio_urls.with_backing
case "custom":
return analysisData.audio_urls.custom_instrumental
default:
return null
}
}
// Loading state
if (isLoading) {
return (
<div className="min-h-screen bg-background">
<AppHeader />
<main className="container mx-auto px-4 py-8 max-w-5xl">
<Skeleton className="h-8 w-48 mb-4" />
<Skeleton className="h-4 w-96 mb-8" />
<Skeleton className="h-[200px] w-full mb-4" />
<Skeleton className="h-32 w-full" />
</main>
</div>
)
}
// Error state
if (error && !analysisData) {
return (
<div className="min-h-screen bg-background">
<AppHeader />
<main className="container mx-auto px-4 py-8 max-w-5xl">
<Alert variant="destructive">
<AlertCircle className="h-4 w-4" />
<AlertDescription>{error}</AlertDescription>
</Alert>
<Button variant="outline" className="mt-4" onClick={() => router.push(`/jobs/${jobId}`)}>
<ArrowLeft className="w-4 h-4 mr-2" />
Back to Job
</Button>
</main>
</div>
)
}
const analysis = analysisData?.analysis
return (
<div className="min-h-screen bg-background">
<AppHeader />
<main className="container mx-auto px-4 py-8 max-w-6xl">
{/* Header */}
<Button variant="ghost" className="mb-6" onClick={() => router.push(`/jobs/${jobId}`)}>
<ArrowLeft className="w-4 h-4 mr-2" />
Back to Job
</Button>
<div className="mb-8">
<h1 className="text-3xl font-bold mb-2">
Select Instrumental Track
</h1>
<p className="text-muted-foreground">
{analysisData?.artist} - {analysisData?.title}
</p>
</div>
{/* Error Alert */}
{error && (
<Alert variant="destructive" className="mb-6">
<AlertCircle className="h-4 w-4" />
<AlertDescription>{error}</AlertDescription>
</Alert>
)}
{/* Analysis Summary */}
{analysis && (
<Card className="mb-6">
<CardHeader>
<CardTitle className="text-lg flex items-center gap-2">
<Music className="h-5 w-5" />
Backing Vocals Analysis
</CardTitle>
<CardDescription>
Automated analysis of the backing vocals stem
</CardDescription>
</CardHeader>
<CardContent>
<div className="flex flex-wrap gap-4">
<div className="flex items-center gap-2">
{analysis.has_audible_content ? (
<Volume2 className="h-4 w-4 text-yellow-500" />
) : (
<VolumeX className="h-4 w-4 text-green-500" />
)}
<span className="text-sm">
{analysis.has_audible_content
? "Backing vocals detected"
: "No backing vocals detected"}
</span>
</div>
{analysis.has_audible_content && (
<>
<Badge variant="outline">
{analysis.audible_segments.length} audible segments
</Badge>
<Badge variant="outline">
{analysis.audible_percentage.toFixed(1)}% of track
</Badge>
<Badge variant="outline">
{analysis.total_audible_duration_seconds.toFixed(1)}s total
</Badge>
</>
)}
<Badge
variant={analysis.recommended_selection === "clean" ? "default" : "secondary"}
>
Recommended: {analysis.recommended_selection === "clean" ? "Clean Instrumental" : "Review Needed"}
</Badge>
</div>
</CardContent>
</Card>
)}
{/* Waveform Display */}
{waveformData && analysis && (
<Card className="mb-6">
<CardHeader>
<CardTitle className="text-lg">Backing Vocals Waveform</CardTitle>
<CardDescription>
Click to seek • {isSelectionMode ? "Drag to select mute region" : "Click 'Add Region' to start selecting"}
</CardDescription>
</CardHeader>
<CardContent>
<WaveformDisplay
amplitudes={waveformData.amplitudes}
duration={waveformData.duration}
currentTime={currentTime}
segments={analysis.audible_segments}
muteRegions={muteRegions}
onSeek={handleSeek}
onRegionSelect={handleAddRegion}
isSelecting={isSelectionMode}
width={900}
height={150}
className="w-full overflow-x-auto"
/>
</CardContent>
</Card>
)}
<div className="grid lg:grid-cols-2 gap-6 mb-6">
{/* Audio Players */}
<Card>
<CardHeader>
<CardTitle className="text-lg">Audio Preview</CardTitle>
<CardDescription>
Listen to different instrumental options
</CardDescription>
</CardHeader>
<CardContent className="space-y-4">
{/* Audio source selector */}
<div className="flex flex-wrap gap-2">
<Button
variant={activeAudio === "backing" ? "default" : "outline"}
size="sm"
onClick={() => setActiveAudio("backing")}
>
Backing Vocals
</Button>
<Button
variant={activeAudio === "clean" ? "default" : "outline"}
size="sm"
onClick={() => setActiveAudio("clean")}
>
Clean Instrumental
</Button>
<Button
variant={activeAudio === "with_backing" ? "default" : "outline"}
size="sm"
onClick={() => setActiveAudio("with_backing")}
>
With Backing
</Button>
{analysisData?.has_custom_instrumental && (
<Button
variant={activeAudio === "custom" ? "default" : "outline"}
size="sm"
onClick={() => setActiveAudio("custom")}
>
Custom
</Button>
)}
</div>
{/* Audio player */}
{getCurrentAudioUrl() && (
<AudioPlayer
src={getCurrentAudioUrl()!}
onTimeUpdate={setCurrentTime}
seekTo={seekTo}
label={
activeAudio === "backing"
? "Backing Vocals Only"
: activeAudio === "clean"
? "Clean Instrumental"
: activeAudio === "custom"
? "Custom Instrumental"
: "Instrumental + Backing Vocals"
}
/>
)}
</CardContent>
</Card>
{/* Region Selector */}
<RegionSelector
muteRegions={muteRegions}
audibleSegments={analysis?.audible_segments}
onAddRegion={handleAddRegion}
onRemoveRegion={handleRemoveRegion}
onClearAll={handleClearAll}
onSeekTo={handleSeek}
isSelectionMode={isSelectionMode}
onToggleSelectionMode={() => setIsSelectionMode(!isSelectionMode)}
/>
</div>
{/* Create Custom Button */}
{muteRegions.length > 0 && !analysisData?.has_custom_instrumental && (
<Card className="mb-6">
<CardContent className="py-4">
<div className="flex items-center justify-between">
<div>
<p className="font-medium">Ready to create custom instrumental</p>
<p className="text-sm text-muted-foreground">
{muteRegions.length} region{muteRegions.length > 1 ? "s" : ""} will be muted
</p>
</div>
<Button onClick={handleCreateCustom} disabled={isCreatingCustom}>
{isCreatingCustom ? (
<>
<Loader2 className="h-4 w-4 mr-2 animate-spin" />
Creating...
</>
) : (
"Create Custom Instrumental"
)}
</Button>
</div>
</CardContent>
</Card>
)}
{/* Selection Options */}
<Card className="mb-6">
<CardHeader>
<CardTitle className="text-lg">Final Selection</CardTitle>
<CardDescription>
Choose which instrumental to use for your karaoke video
</CardDescription>
</CardHeader>
<CardContent>
<RadioGroup value={selectedOption} onValueChange={setSelectedOption}>
<div className="space-y-4">
<div className="flex items-center space-x-3">
<RadioGroupItem value="clean" id="clean" />
<Label htmlFor="clean" className="flex-1 cursor-pointer">
<div className="font-medium">Clean Instrumental</div>
<div className="text-sm text-muted-foreground">
Use the instrumental with no backing vocals at all
</div>
</Label>
{analysis?.recommended_selection === "clean" && (
<Badge variant="default" className="bg-green-600">
<CheckCircle2 className="h-3 w-3 mr-1" />
Recommended
</Badge>
)}
</div>
<div className="flex items-center space-x-3">
<RadioGroupItem value="with_backing" id="with_backing" />
<Label htmlFor="with_backing" className="flex-1 cursor-pointer">
<div className="font-medium">Instrumental with Backing Vocals</div>
<div className="text-sm text-muted-foreground">
Use the instrumental with all backing vocals included
</div>
</Label>
</div>
{analysisData?.has_custom_instrumental && (
<div className="flex items-center space-x-3">
<RadioGroupItem value="custom" id="custom" />
<Label htmlFor="custom" className="flex-1 cursor-pointer">
<div className="font-medium">Custom Instrumental</div>
<div className="text-sm text-muted-foreground">
Use your custom instrumental with {muteRegions.length} muted region{muteRegions.length > 1 ? "s" : ""}
</div>
</Label>
<Badge variant="secondary">Custom</Badge>
</div>
)}
</div>
</RadioGroup>
</CardContent>
</Card>
{/* Submit Button */}
<div className="flex gap-4">
<Button
size="lg"
onClick={handleSubmit}
disabled={isSubmitting}
className="flex-1 max-w-md"
>
{isSubmitting ? (
<>
<Loader2 className="h-4 w-4 mr-2 animate-spin" />
Submitting...
</>
) : (
<>
<CheckCircle2 className="h-4 w-4 mr-2" />
Confirm Selection & Continue
</>
)}
</Button>
</div>
</main>
</div>
)
}
export default function InstrumentalReviewPage() {
return (
<ProtectedRoute>
<InstrumentalReviewContent />
</ProtectedRoute>
)
}
+9 -2
View File
@@ -190,8 +190,15 @@ function JobDetailContent() {
{job.status === "awaiting_instrumental" && (
<Alert className="bg-secondary/10 border-secondary/30">
<AlertCircle className="h-4 w-4 text-secondary" />
<AlertDescription className="text-foreground">
Multiple instrumental versions were detected. Please select your preferred version to continue.
<AlertDescription className="text-foreground flex items-center justify-between">
<span>Multiple instrumental versions were detected. Please select your preferred version to continue.</span>
<Button
size="sm"
onClick={() => router.push(`/jobs/${job.id}/instrumental-review`)}
className="ml-4"
>
Select Instrumental
</Button>
</AlertDescription>
</Alert>
)}
@@ -0,0 +1,263 @@
"use client"
import { useRef, useState, useEffect, useCallback } from "react"
import { Button } from "@/components/ui/button"
import { Slider } from "@/components/ui/slider"
import { Play, Pause, SkipBack, SkipForward, Volume2, VolumeX } from "lucide-react"
interface AudioPlayerProps {
src: string
onTimeUpdate?: (currentTime: number) => void
onDurationChange?: (duration: number) => void
seekTo?: number
label?: string
className?: string
}
export function AudioPlayer({
src,
onTimeUpdate,
onDurationChange,
seekTo,
label,
className = "",
}: AudioPlayerProps) {
const audioRef = useRef<HTMLAudioElement>(null)
const [isPlaying, setIsPlaying] = useState(false)
const [currentTime, setCurrentTime] = useState(0)
const [duration, setDuration] = useState(0)
const [volume, setVolume] = useState(1)
const [isMuted, setIsMuted] = useState(false)
const [isLoading, setIsLoading] = useState(true)
// Handle external seek requests
useEffect(() => {
if (seekTo !== undefined && audioRef.current && !isNaN(seekTo)) {
audioRef.current.currentTime = seekTo
}
}, [seekTo])
// Handle audio events
useEffect(() => {
const audio = audioRef.current
if (!audio) return
const handleTimeUpdate = () => {
setCurrentTime(audio.currentTime)
onTimeUpdate?.(audio.currentTime)
}
const handleDurationChange = () => {
setDuration(audio.duration)
onDurationChange?.(audio.duration)
}
const handleLoadedData = () => {
setIsLoading(false)
setDuration(audio.duration)
onDurationChange?.(audio.duration)
}
const handleEnded = () => {
setIsPlaying(false)
}
const handleLoadStart = () => {
setIsLoading(true)
}
const handleCanPlay = () => {
setIsLoading(false)
}
// Sync isPlaying state with actual audio element state
const handlePlay = () => {
setIsPlaying(true)
}
const handlePause = () => {
setIsPlaying(false)
}
audio.addEventListener("timeupdate", handleTimeUpdate)
audio.addEventListener("durationchange", handleDurationChange)
audio.addEventListener("loadeddata", handleLoadedData)
audio.addEventListener("ended", handleEnded)
audio.addEventListener("loadstart", handleLoadStart)
audio.addEventListener("canplay", handleCanPlay)
audio.addEventListener("play", handlePlay)
audio.addEventListener("pause", handlePause)
return () => {
audio.removeEventListener("timeupdate", handleTimeUpdate)
audio.removeEventListener("durationchange", handleDurationChange)
audio.removeEventListener("loadeddata", handleLoadedData)
audio.removeEventListener("ended", handleEnded)
audio.removeEventListener("loadstart", handleLoadStart)
audio.removeEventListener("canplay", handleCanPlay)
audio.removeEventListener("play", handlePlay)
audio.removeEventListener("pause", handlePause)
}
}, [onTimeUpdate, onDurationChange])
// Update volume
useEffect(() => {
if (audioRef.current) {
audioRef.current.volume = isMuted ? 0 : volume
}
}, [volume, isMuted])
const togglePlay = useCallback(async () => {
const audio = audioRef.current
if (!audio) return
try {
if (audio.paused) {
await audio.play()
} else {
audio.pause()
}
// State will be updated by the play/pause event listeners
} catch (error) {
// Play was prevented (e.g., user hasn't interacted with page yet)
console.warn("Audio playback was prevented:", error)
}
}, [])
const handleSeek = useCallback((value: number[]) => {
const audio = audioRef.current
if (!audio) return
const newTime = value[0]
audio.currentTime = newTime
setCurrentTime(newTime)
}, [])
const skipBackward = useCallback(() => {
const audio = audioRef.current
if (!audio) return
audio.currentTime = Math.max(0, audio.currentTime - 5)
}, [])
const skipForward = useCallback(() => {
const audio = audioRef.current
if (!audio) return
audio.currentTime = Math.min(duration, audio.currentTime + 5)
}, [duration])
const toggleMute = useCallback(() => {
setIsMuted(!isMuted)
}, [isMuted])
const handleVolumeChange = useCallback((value: number[]) => {
setVolume(value[0])
if (value[0] > 0 && isMuted) {
setIsMuted(false)
}
}, [isMuted])
const formatTime = (time: number) => {
if (isNaN(time)) return "0:00"
const minutes = Math.floor(time / 60)
const seconds = Math.floor(time % 60)
return `${minutes}:${seconds.toString().padStart(2, "0")}`
}
return (
<div className={`bg-card rounded-lg p-4 ${className}`}>
<audio ref={audioRef} src={src} preload="metadata" />
{label && (
<div className="text-sm font-medium text-muted-foreground mb-3">
{label}
</div>
)}
{/* Progress bar */}
<div className="mb-4">
<Slider
value={[currentTime]}
max={duration || 100}
step={0.1}
onValueChange={handleSeek}
disabled={isLoading}
className="w-full"
/>
<div className="flex justify-between text-xs text-muted-foreground mt-1">
<span>{formatTime(currentTime)}</span>
<span>{formatTime(duration)}</span>
</div>
</div>
{/* Controls */}
<div className="flex items-center justify-between">
<div className="flex items-center gap-2">
<Button
variant="ghost"
size="icon"
onClick={skipBackward}
disabled={isLoading}
className="h-8 w-8"
>
<SkipBack className="h-4 w-4" />
</Button>
<Button
variant="default"
size="icon"
onClick={togglePlay}
disabled={isLoading}
className="h-10 w-10"
>
{isPlaying ? (
<Pause className="h-5 w-5" />
) : (
<Play className="h-5 w-5 ml-0.5" />
)}
</Button>
<Button
variant="ghost"
size="icon"
onClick={skipForward}
disabled={isLoading}
className="h-8 w-8"
>
<SkipForward className="h-4 w-4" />
</Button>
</div>
{/* Volume control */}
<div className="flex items-center gap-2">
<Button
variant="ghost"
size="icon"
onClick={toggleMute}
className="h-8 w-8"
>
{isMuted || volume === 0 ? (
<VolumeX className="h-4 w-4" />
) : (
<Volume2 className="h-4 w-4" />
)}
</Button>
<Slider
value={[isMuted ? 0 : volume]}
max={1}
step={0.1}
onValueChange={handleVolumeChange}
className="w-20"
/>
</div>
</div>
{isLoading && (
<div className="text-xs text-muted-foreground text-center mt-2">
Loading audio...
</div>
)}
</div>
)
}
@@ -0,0 +1,3 @@
export { WaveformDisplay } from "./waveform-display"
export { AudioPlayer } from "./audio-player"
export { RegionSelector } from "./region-selector"
@@ -0,0 +1,222 @@
"use client"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Badge } from "@/components/ui/badge"
import { Trash2, VolumeX, Plus } from "lucide-react"
interface MuteRegion {
start_seconds: number
end_seconds: number
}
interface AudibleSegment {
start_seconds: number
end_seconds: number
duration_seconds: number
avg_amplitude_db: number
}
interface RegionSelectorProps {
muteRegions: MuteRegion[]
audibleSegments?: AudibleSegment[]
onAddRegion: (region: MuteRegion) => void
onRemoveRegion: (index: number) => void
onClearAll: () => void
onSeekTo?: (time: number) => void
isSelectionMode: boolean
onToggleSelectionMode: () => void
className?: string
}
export function RegionSelector({
muteRegions,
audibleSegments = [],
onAddRegion,
onRemoveRegion,
onClearAll,
onSeekTo,
isSelectionMode,
onToggleSelectionMode,
className = "",
}: RegionSelectorProps) {
const formatTime = (seconds: number) => {
const mins = Math.floor(seconds / 60)
const secs = Math.floor(seconds % 60)
const ms = Math.floor((seconds % 1) * 100)
return `${mins}:${secs.toString().padStart(2, "0")}.${ms.toString().padStart(2, "0")}`
}
const formatDuration = (seconds: number) => {
if (seconds < 1) {
return `${Math.round(seconds * 1000)}ms`
}
return `${seconds.toFixed(1)}s`
}
const totalMutedDuration = muteRegions.reduce(
(sum, r) => sum + (r.end_seconds - r.start_seconds),
0
)
// Quick mute: add mute region for an audible segment
const handleQuickMute = (segment: AudibleSegment) => {
onAddRegion({
start_seconds: segment.start_seconds,
end_seconds: segment.end_seconds,
})
}
// Check if a segment is already muted
const isSegmentMuted = (segment: AudibleSegment) => {
return muteRegions.some(
(r) =>
r.start_seconds <= segment.start_seconds &&
r.end_seconds >= segment.end_seconds
)
}
return (
<div className={`space-y-4 ${className}`}>
{/* Selection Mode Toggle */}
<Card>
<CardHeader className="pb-3">
<div className="flex items-center justify-between">
<CardTitle className="text-lg">Mute Regions</CardTitle>
<Button
variant={isSelectionMode ? "default" : "outline"}
size="sm"
onClick={onToggleSelectionMode}
>
<Plus className="h-4 w-4 mr-2" />
{isSelectionMode ? "Click waveform to select" : "Add Region"}
</Button>
</div>
</CardHeader>
<CardContent>
{muteRegions.length === 0 ? (
<p className="text-sm text-muted-foreground">
No mute regions selected. Click "Add Region" and drag on the waveform to select areas to mute.
</p>
) : (
<div className="space-y-2">
{muteRegions.map((region, index) => (
<div
key={index}
className="flex items-center justify-between p-2 bg-muted/50 rounded-lg group"
>
<div className="flex items-center gap-3">
<VolumeX className="h-4 w-4 text-destructive" />
<button
onClick={() => onSeekTo?.(region.start_seconds)}
className="text-sm font-mono hover:text-primary transition-colors"
>
{formatTime(region.start_seconds)}
</button>
<span className="text-muted-foreground">→</span>
<button
onClick={() => onSeekTo?.(region.end_seconds)}
className="text-sm font-mono hover:text-primary transition-colors"
>
{formatTime(region.end_seconds)}
</button>
<Badge variant="secondary" className="ml-2">
{formatDuration(region.end_seconds - region.start_seconds)}
</Badge>
</div>
<Button
variant="ghost"
size="icon"
onClick={() => onRemoveRegion(index)}
className="h-8 w-8 opacity-0 group-hover:opacity-100 transition-opacity"
>
<Trash2 className="h-4 w-4 text-destructive" />
</Button>
</div>
))}
<div className="flex items-center justify-between pt-2 border-t mt-3">
<span className="text-sm text-muted-foreground">
Total muted: {formatDuration(totalMutedDuration)}
</span>
<Button
variant="ghost"
size="sm"
onClick={onClearAll}
className="text-destructive hover:text-destructive"
>
Clear All
</Button>
</div>
</div>
)}
</CardContent>
</Card>
{/* Detected Audible Segments */}
{audibleSegments.length > 0 && (
<Card>
<CardHeader className="pb-3">
<CardTitle className="text-lg">Detected Backing Vocals</CardTitle>
</CardHeader>
<CardContent>
<p className="text-sm text-muted-foreground mb-3">
Click a segment to jump to that time, or click the mute button to add it as a mute region.
</p>
<div className="space-y-2 max-h-64 overflow-y-auto">
{audibleSegments.map((segment, index) => {
const isMuted = isSegmentMuted(segment)
return (
<div
key={index}
className={`flex items-center justify-between p-2 rounded-lg transition-colors ${
isMuted ? "bg-destructive/10" : "bg-muted/50 hover:bg-muted"
}`}
>
<button
onClick={() => onSeekTo?.(segment.start_seconds)}
className="flex items-center gap-3 text-left"
>
<span className="text-sm font-mono">
{formatTime(segment.start_seconds)} - {formatTime(segment.end_seconds)}
</span>
<Badge variant="outline" className="text-xs">
{formatDuration(segment.duration_seconds)}
</Badge>
<Badge
variant="outline"
className={`text-xs ${
segment.avg_amplitude_db > -20
? "border-yellow-500 text-yellow-500"
: "border-muted-foreground"
}`}
>
{segment.avg_amplitude_db.toFixed(1)}dB
</Badge>
</button>
{!isMuted && (
<Button
variant="ghost"
size="sm"
onClick={() => handleQuickMute(segment)}
className="text-xs"
>
<VolumeX className="h-3 w-3 mr-1" />
Mute
</Button>
)}
{isMuted && (
<Badge variant="destructive" className="text-xs">
Muted
</Badge>
)}
</div>
)
})}
</div>
</CardContent>
</Card>
)}
</div>
)
}
@@ -0,0 +1,259 @@
"use client"
import { useRef, useEffect, useState, useCallback } from "react"
interface AudibleSegment {
start_seconds: number
end_seconds: number
duration_seconds: number
avg_amplitude_db: number
}
interface MuteRegion {
start_seconds: number
end_seconds: number
}
interface WaveformDisplayProps {
amplitudes: number[]
duration: number
currentTime?: number
segments?: AudibleSegment[]
muteRegions?: MuteRegion[]
onSeek?: (time: number) => void
onRegionSelect?: (region: MuteRegion) => void
isSelecting?: boolean
width?: number
height?: number
className?: string
}
export function WaveformDisplay({
amplitudes,
duration,
currentTime = 0,
segments = [],
muteRegions = [],
onSeek,
onRegionSelect,
isSelecting = false,
width = 800,
height = 150,
className = "",
}: WaveformDisplayProps) {
const canvasRef = useRef<HTMLCanvasElement>(null)
const [isDragging, setIsDragging] = useState(false)
const [dragStart, setDragStart] = useState<number | null>(null)
const [dragEnd, setDragEnd] = useState<number | null>(null)
const [hoveredTime, setHoveredTime] = useState<number | null>(null)
// Convert time to x position
const timeToX = useCallback((time: number) => {
return (time / duration) * width
}, [duration, width])
// Convert x position to time
const xToTime = useCallback((x: number) => {
return (x / width) * duration
}, [duration, width])
// Draw the waveform
useEffect(() => {
const canvas = canvasRef.current
if (!canvas) return
const ctx = canvas.getContext("2d")
if (!ctx) return
// Clear canvas
ctx.fillStyle = "#1a1a2e"
ctx.fillRect(0, 0, width, height)
const barWidth = width / amplitudes.length
const centerY = height / 2
// Draw mute regions background
ctx.fillStyle = "rgba(255, 107, 107, 0.2)"
for (const region of muteRegions) {
const startX = timeToX(region.start_seconds)
const endX = timeToX(region.end_seconds)
ctx.fillRect(startX, 0, endX - startX, height)
}
// Draw current drag selection
if (isDragging && dragStart !== null && dragEnd !== null) {
const startX = Math.min(timeToX(dragStart), timeToX(dragEnd))
const endX = Math.max(timeToX(dragStart), timeToX(dragEnd))
ctx.fillStyle = "rgba(255, 107, 107, 0.3)"
ctx.fillRect(startX, 0, endX - startX, height)
}
// Draw segment highlights
for (const segment of segments) {
const startX = timeToX(segment.start_seconds)
const endX = timeToX(segment.end_seconds)
const startIdx = Math.floor((segment.start_seconds / duration) * amplitudes.length)
const endIdx = Math.ceil((segment.end_seconds / duration) * amplitudes.length)
ctx.fillStyle = "rgba(233, 69, 96, 0.4)"
for (let i = startIdx; i < endIdx && i < amplitudes.length; i++) {
const amplitude = amplitudes[i]
const barHeight = amplitude * height * 0.8
const x = i * barWidth
ctx.fillRect(x, centerY - barHeight / 2, barWidth - 1, barHeight)
}
}
// Draw main waveform
ctx.fillStyle = "#4a90d9"
for (let i = 0; i < amplitudes.length; i++) {
const amplitude = amplitudes[i]
const barHeight = amplitude * height * 0.8
const x = i * barWidth
ctx.fillRect(x, centerY - barHeight / 2, barWidth - 1, barHeight)
}
// Draw silence threshold line
ctx.strokeStyle = "rgba(255, 255, 255, 0.2)"
ctx.setLineDash([5, 5])
ctx.beginPath()
const thresholdY = height * 0.5 // Visual representation
ctx.moveTo(0, thresholdY)
ctx.lineTo(width, thresholdY)
ctx.stroke()
ctx.setLineDash([])
// Draw playhead
if (currentTime > 0) {
const playheadX = timeToX(currentTime)
ctx.strokeStyle = "#ffffff"
ctx.lineWidth = 2
ctx.beginPath()
ctx.moveTo(playheadX, 0)
ctx.lineTo(playheadX, height)
ctx.stroke()
}
// Draw hover position
if (hoveredTime !== null && !isDragging) {
const hoverX = timeToX(hoveredTime)
ctx.strokeStyle = "rgba(255, 255, 255, 0.5)"
ctx.lineWidth = 1
ctx.beginPath()
ctx.moveTo(hoverX, 0)
ctx.lineTo(hoverX, height)
ctx.stroke()
}
// Draw time axis
ctx.fillStyle = "#ffffff"
ctx.font = "10px sans-serif"
ctx.textAlign = "center"
const tickInterval = duration > 300 ? 60 : duration > 60 ? 30 : 10
for (let t = 0; t <= duration; t += tickInterval) {
const x = timeToX(t)
const minutes = Math.floor(t / 60)
const seconds = Math.floor(t % 60)
const label = `${minutes}:${seconds.toString().padStart(2, "0")}`
ctx.fillText(label, x, height - 5)
// Tick mark
ctx.strokeStyle = "rgba(255, 255, 255, 0.3)"
ctx.beginPath()
ctx.moveTo(x, height - 20)
ctx.lineTo(x, height - 15)
ctx.stroke()
}
}, [amplitudes, duration, currentTime, segments, muteRegions, width, height, isDragging, dragStart, dragEnd, hoveredTime, timeToX])
// Handle mouse events for seeking and region selection
const handleMouseDown = (e: React.MouseEvent<HTMLCanvasElement>) => {
const canvas = canvasRef.current
if (!canvas) return
const rect = canvas.getBoundingClientRect()
const x = e.clientX - rect.left
const time = xToTime(x)
if (isSelecting) {
setIsDragging(true)
setDragStart(time)
setDragEnd(time)
} else if (onSeek) {
onSeek(time)
}
}
const handleMouseMove = (e: React.MouseEvent<HTMLCanvasElement>) => {
const canvas = canvasRef.current
if (!canvas) return
const rect = canvas.getBoundingClientRect()
const x = e.clientX - rect.left
const time = xToTime(x)
setHoveredTime(time)
if (isDragging && isSelecting) {
setDragEnd(time)
}
}
const handleMouseUp = () => {
if (isDragging && dragStart !== null && dragEnd !== null && onRegionSelect) {
const start = Math.min(dragStart, dragEnd)
const end = Math.max(dragStart, dragEnd)
// Only create region if it's at least 0.1 seconds
if (end - start >= 0.1) {
onRegionSelect({ start_seconds: start, end_seconds: end })
}
}
setIsDragging(false)
setDragStart(null)
setDragEnd(null)
}
const handleMouseLeave = () => {
setHoveredTime(null)
if (isDragging) {
handleMouseUp()
}
}
// Format time for tooltip
const formatTime = (time: number) => {
const minutes = Math.floor(time / 60)
const seconds = Math.floor(time % 60)
const ms = Math.floor((time % 1) * 100)
return `${minutes}:${seconds.toString().padStart(2, "0")}.${ms.toString().padStart(2, "0")}`
}
return (
<div className={`relative ${className}`}>
<canvas
ref={canvasRef}
width={width}
height={height}
className={`rounded-lg ${isSelecting ? "cursor-crosshair" : "cursor-pointer"}`}
onMouseDown={handleMouseDown}
onMouseMove={handleMouseMove}
onMouseUp={handleMouseUp}
onMouseLeave={handleMouseLeave}
/>
{/* Time tooltip */}
{hoveredTime !== null && (
<div
className="absolute top-0 transform -translate-x-1/2 bg-black/80 text-white text-xs px-2 py-1 rounded pointer-events-none"
style={{ left: timeToX(hoveredTime) }}
>
{formatTime(hoveredTime)}
</div>
)}
</div>
)
}
+85 -24
View File
@@ -169,25 +169,38 @@ class FlacFetchAudioFetcher(AudioFetcher):
if self._manager is None:
# Import flacfetch here to avoid import errors if not installed
from flacfetch.core.manager import FetchManager
from flacfetch.providers.youtube import YouTubeProvider
from flacfetch.providers.youtube import YoutubeProvider
from flacfetch.downloaders.youtube import YoutubeDownloader
# Try to import TorrentDownloader (has optional dependencies)
try:
from flacfetch.downloaders.torrent import TorrentDownloader
except ImportError:
TorrentDownloader = None
self.logger.debug("TorrentDownloader not available (missing dependencies)")
self._manager = FetchManager()
# Add providers based on available API keys
# Add providers and downloaders based on available API keys
if self._redacted_api_key:
from flacfetch.providers.redacted import RedactedProvider
self._manager.add_provider(RedactedProvider(api_key=self._redacted_api_key))
if TorrentDownloader:
self._manager.register_downloader("Redacted", TorrentDownloader())
self.logger.debug("Added Redacted provider")
if self._ops_api_key:
from flacfetch.providers.ops import OPSProvider
self._manager.add_provider(OPSProvider(api_key=self._ops_api_key))
if TorrentDownloader:
self._manager.register_downloader("OPS", TorrentDownloader())
self.logger.debug("Added OPS provider")
# Always add YouTube as a fallback provider
self._manager.add_provider(YouTubeProvider())
# Always add YouTube as a fallback provider with its downloader
self._manager.add_provider(YoutubeProvider())
self._manager.register_downloader("YouTube", YoutubeDownloader())
self.logger.debug("Added YouTube provider")
return self._manager
@@ -220,15 +233,19 @@ class FlacFetchAudioFetcher(AudioFetcher):
# Convert to our AudioSearchResult format
search_results = []
for result in results:
# Get quality as string if it's a Quality object
quality = getattr(result, "quality", None)
quality_str = str(quality) if quality else None
search_results.append(
AudioSearchResult(
title=getattr(result, "title", title),
artist=getattr(result, "artist", artist),
url=getattr(result, "url", ""),
provider=getattr(result, "provider", "Unknown"),
duration=getattr(result, "duration", None),
quality=getattr(result, "quality", None),
source_id=getattr(result, "id", None),
url=getattr(result, "download_url", "") or "",
provider=getattr(result, "source_name", "Unknown"),
duration=getattr(result, "duration_seconds", None),
quality=quality_str,
source_id=getattr(result, "info_hash", None),
raw_result=result,
)
)
@@ -265,7 +282,7 @@ class FlacFetchAudioFetcher(AudioFetcher):
if output_filename is None:
output_filename = f"{result.artist} - {result.title}"
self.logger.info(f"Downloading: {result.artist} - {result.title} from {result.provider}")
self.logger.info(f"Downloading: {result.artist} - {result.title} from {result.provider or 'Unknown'}")
try:
# Use flacfetch to download
@@ -336,7 +353,7 @@ class FlacFetchAudioFetcher(AudioFetcher):
if auto_select:
# Auto mode: select best result based on flacfetch's ranking
selected = manager.select_best(results)
self.logger.info(f"Auto-selected: {getattr(selected, 'title', title)} from {getattr(selected, 'provider', 'Unknown')}")
self.logger.info(f"Auto-selected: {getattr(selected, 'title', title)} from {getattr(selected, 'source_name', 'Unknown')}")
else:
# Interactive mode: present options to user
selected = self._interactive_select(results, artist, title)
@@ -351,7 +368,7 @@ class FlacFetchAudioFetcher(AudioFetcher):
if output_filename is None:
output_filename = f"{artist} - {title}"
self.logger.info(f"Downloading from {getattr(selected, 'provider', 'Unknown')}...")
self.logger.info(f"Downloading from {getattr(selected, 'source_name', 'Unknown')}...")
try:
filepath = manager.download(
@@ -365,13 +382,17 @@ class FlacFetchAudioFetcher(AudioFetcher):
self.logger.info(f"Downloaded to: {filepath}")
# Get quality as string if it's a Quality object
quality = getattr(selected, "quality", None)
quality_str = str(quality) if quality else None
return AudioFetchResult(
filepath=filepath,
artist=artist,
title=title,
provider=getattr(selected, "provider", "Unknown"),
duration=getattr(selected, "duration", None),
quality=getattr(selected, "quality", None),
provider=getattr(selected, "source_name", "Unknown"),
duration=getattr(selected, "duration_seconds", None),
quality=quality_str,
)
except Exception as e:
@@ -381,35 +402,75 @@ class FlacFetchAudioFetcher(AudioFetcher):
"""
Present search results to the user for interactive selection.
Uses flacfetch's built-in CLIHandler for rich, colorized output.
Args:
results: List of search results from flacfetch
results: List of Release objects from flacfetch
artist: The artist name being searched
title: The track title being searched
Returns:
The selected result object
The selected Release object
"""
try:
# Use flacfetch's built-in CLIHandler for rich display
from flacfetch.interface.cli import CLIHandler
handler = CLIHandler(target_artist=artist)
return handler.select_release(results)
except ImportError:
# Fallback to basic display if CLIHandler not available
return self._basic_interactive_select(results, artist, title)
except (KeyboardInterrupt, EOFError):
print("\nCancelled")
return None
except (AttributeError, TypeError):
# Fallback if results aren't proper Release objects (e.g., in tests)
return self._basic_interactive_select(results, artist, title)
def _basic_interactive_select(self, results: list, artist: str, title: str) -> object:
"""
Basic fallback for interactive selection without rich formatting.
Args:
results: List of Release objects from flacfetch
artist: The artist name being searched
title: The track title being searched
Returns:
The selected Release object
"""
print(f"\n{'=' * 60}")
print(f"Search Results for: {artist} - {title}")
print(f"{'=' * 60}\n")
for i, result in enumerate(results, 1):
provider = getattr(result, "provider", "Unknown")
# Use correct flacfetch attribute names
source_name = getattr(result, "source_name", "Unknown")
result_title = getattr(result, "title", "Unknown")
result_artist = getattr(result, "artist", "Unknown")
quality = getattr(result, "quality", "")
duration = getattr(result, "duration", None)
quality = getattr(result, "quality", None)
duration_seconds = getattr(result, "duration_seconds", None)
seeders = getattr(result, "seeders", None)
target_file = getattr(result, "target_file", None)
# Format duration if available
duration_str = ""
if duration:
minutes = duration // 60
seconds = duration % 60
if duration_seconds:
minutes = duration_seconds // 60
seconds = duration_seconds % 60
duration_str = f" [{minutes}:{seconds:02d}]"
# Format quality - it's a Quality object with __str__
quality_str = f" ({quality})" if quality else ""
print(f" {i}. [{provider}] {result_artist} - {result_title}{quality_str}{duration_str}")
# Format seeders for torrent sources
seeders_str = f" Seeders: {seeders}" if seeders is not None else ""
# Format target file
file_str = f' "{target_file}"' if target_file else ""
print(f" {i}. [{source_name}] {result_artist} - {result_title}{quality_str}{duration_str}{seeders_str}{file_str}")
print()
print(" 0. Cancel")
@@ -0,0 +1,45 @@
"""
Instrumental Review Module - Shared core for both local and remote CLI.
This module provides audio analysis and editing functionality for instrumental
selection in karaoke generation. It's designed to be:
- Pure Python with no cloud dependencies (GCS, etc.)
- Reusable by both local CLI (karaoke-gen) and remote backend (Cloud Run)
- Easy to test without mocking cloud services
Classes:
AudioAnalyzer: Analyzes backing vocals audio for audible content
AudioEditor: Creates custom instrumentals by muting regions
WaveformGenerator: Generates waveform visualization images
InstrumentalReviewServer: Local HTTP server for browser-based review
Models:
AnalysisResult: Result of audio analysis
AudibleSegment: A detected segment of audible content
MuteRegion: A region to mute in the backing vocals
RecommendedSelection: Enum of selection recommendations
"""
from .models import (
AnalysisResult,
AudibleSegment,
MuteRegion,
RecommendedSelection,
)
from .analyzer import AudioAnalyzer
from .editor import AudioEditor
from .waveform import WaveformGenerator
from .server import InstrumentalReviewServer
__all__ = [
# Models
"AnalysisResult",
"AudibleSegment",
"MuteRegion",
"RecommendedSelection",
# Classes
"AudioAnalyzer",
"AudioEditor",
"WaveformGenerator",
"InstrumentalReviewServer",
]
+408
View File
@@ -0,0 +1,408 @@
"""
Audio analyzer for detecting audible content in backing vocals.
This module provides the AudioAnalyzer class which analyzes audio files
to detect segments of audible content above a silence threshold. It's used
to help determine whether backing vocals should be included in the final
karaoke instrumental.
"""
import logging
import math
from pathlib import Path
from typing import List, Optional, Tuple
from pydub import AudioSegment
from .models import AnalysisResult, AudibleSegment, RecommendedSelection
logger = logging.getLogger(__name__)
class AudioAnalyzer:
"""
Analyzes audio files for backing vocals content.
This class is pure Python with no cloud dependencies. It works with
local file paths and uses pydub for audio loading and analysis.
The analyzer detects segments of audible content (above a silence threshold)
and provides recommendations for instrumental selection based on the
analysis results.
Attributes:
silence_threshold_db: Amplitude threshold below which audio is
considered silent (default: -40.0 dB)
min_segment_duration_ms: Minimum duration for a segment to be
considered audible (default: 100ms)
merge_gap_ms: Maximum gap between segments to merge them
(default: 500ms)
window_ms: Analysis window size in milliseconds (default: 50ms)
Example:
>>> analyzer = AudioAnalyzer(silence_threshold_db=-40.0)
>>> result = analyzer.analyze("/path/to/backing_vocals.flac")
>>> if result.has_audible_content:
... print(f"Found {result.segment_count} audible segments")
... for seg in result.audible_segments:
... print(f" {seg.start_seconds:.1f}s - {seg.end_seconds:.1f}s")
"""
def __init__(
self,
silence_threshold_db: float = -40.0,
min_segment_duration_ms: int = 100,
merge_gap_ms: int = 500,
window_ms: int = 50,
):
"""
Initialize the audio analyzer.
Args:
silence_threshold_db: Amplitude threshold below which audio is
considered silent. Default is -40.0 dB.
min_segment_duration_ms: Minimum duration for a segment to be
reported as audible. Segments shorter than this are ignored.
Default is 100ms.
merge_gap_ms: If two audible segments are separated by a gap
shorter than this, they are merged into one segment.
Default is 500ms.
window_ms: Size of the analysis window in milliseconds.
Smaller windows give more precise timing but slower analysis.
Default is 50ms.
"""
self.silence_threshold_db = silence_threshold_db
self.min_segment_duration_ms = min_segment_duration_ms
self.merge_gap_ms = merge_gap_ms
self.window_ms = window_ms
def analyze(self, audio_path: str) -> AnalysisResult:
"""
Analyze an audio file for audible content.
This method loads the audio file, calculates amplitude levels across
the duration, and identifies segments where the amplitude exceeds
the silence threshold.
Args:
audio_path: Path to the audio file to analyze. Supports formats
that pydub/ffmpeg can read (FLAC, WAV, MP3, etc.)
Returns:
AnalysisResult containing:
- has_audible_content: Whether any audible content was found
- total_duration_seconds: Total duration of the audio
- audible_segments: List of detected audible segments
- recommended_selection: Recommendation for which instrumental
- Various statistics about the audible content
Raises:
FileNotFoundError: If the audio file doesn't exist
Exception: If the audio file cannot be loaded
"""
path = Path(audio_path)
if not path.exists():
raise FileNotFoundError(f"Audio file not found: {audio_path}")
logger.info(f"Analyzing audio file: {audio_path}")
# Load audio file
audio = AudioSegment.from_file(audio_path)
total_duration_ms = len(audio)
total_duration_seconds = total_duration_ms / 1000.0
logger.debug(f"Audio duration: {total_duration_seconds:.2f}s, "
f"channels: {audio.channels}, "
f"sample_rate: {audio.frame_rate}")
# Convert to mono for consistent analysis
if audio.channels > 1:
audio = audio.set_channels(1)
# Analyze amplitude in windows
audible_windows = self._find_audible_windows(audio)
# Merge adjacent windows into segments
raw_segments = self._windows_to_segments(audible_windows, audio)
# Merge close segments and filter short ones
segments = self._merge_and_filter_segments(raw_segments)
# Calculate statistics
total_audible_ms = sum(
seg.duration_seconds * 1000 for seg in segments
)
total_audible_seconds = total_audible_ms / 1000.0
audible_percentage = (
(total_audible_seconds / total_duration_seconds * 100)
if total_duration_seconds > 0 else 0.0
)
has_audible_content = len(segments) > 0
# Determine recommendation
recommended_selection = self._get_recommendation(
has_audible_content,
segments,
audible_percentage
)
logger.info(
f"Analysis complete: {len(segments)} segments, "
f"{audible_percentage:.1f}% audible, "
f"recommendation: {recommended_selection.value}"
)
return AnalysisResult(
has_audible_content=has_audible_content,
total_duration_seconds=total_duration_seconds,
audible_segments=segments,
recommended_selection=recommended_selection,
silence_threshold_db=self.silence_threshold_db,
total_audible_duration_seconds=total_audible_seconds,
audible_percentage=audible_percentage,
)
def get_amplitude_envelope(
self,
audio_path: str,
window_ms: int = 100,
normalize: bool = True,
) -> List[float]:
"""
Get the amplitude envelope for waveform visualization.
This method returns a list of amplitude values suitable for
rendering a waveform display. Each value represents the RMS
amplitude of a window of audio.
Args:
audio_path: Path to the audio file
window_ms: Size of each window in milliseconds. Smaller values
give more detail but larger data. Default is 100ms.
normalize: If True, normalize amplitudes to 0.0-1.0 range.
Default is True.
Returns:
List of amplitude values (floats). If normalize=True, values
are in the range [0.0, 1.0]. Otherwise, values are in dBFS.
"""
path = Path(audio_path)
if not path.exists():
raise FileNotFoundError(f"Audio file not found: {audio_path}")
audio = AudioSegment.from_file(audio_path)
# Convert to mono
if audio.channels > 1:
audio = audio.set_channels(1)
amplitudes = []
duration_ms = len(audio)
for start_ms in range(0, duration_ms, window_ms):
end_ms = min(start_ms + window_ms, duration_ms)
window = audio[start_ms:end_ms]
# Get RMS amplitude in dBFS
if window.rms > 0:
db = 20 * math.log10(window.rms / window.max_possible_amplitude)
else:
db = -100.0 # Effectively silent
amplitudes.append(db)
if normalize and amplitudes:
# Normalize to 0.0 - 1.0 range
# Map from [silence_threshold, 0] to [0, 1]
min_db = self.silence_threshold_db
max_db = 0.0
amplitudes = [
max(0.0, min(1.0, (db - min_db) / (max_db - min_db)))
for db in amplitudes
]
return amplitudes
def _find_audible_windows(
self,
audio: AudioSegment
) -> List[Tuple[int, float, float]]:
"""
Find windows with amplitude above the silence threshold.
Returns a list of tuples: (start_ms, avg_db, peak_db)
"""
audible_windows = []
duration_ms = len(audio)
for start_ms in range(0, duration_ms, self.window_ms):
end_ms = min(start_ms + self.window_ms, duration_ms)
window = audio[start_ms:end_ms]
# Calculate RMS amplitude in dB
if window.rms > 0:
avg_db = 20 * math.log10(window.rms / window.max_possible_amplitude)
# Peak is approximated as max sample value
peak_db = window.dBFS if hasattr(window, 'dBFS') else avg_db
else:
avg_db = -100.0
peak_db = -100.0
if avg_db > self.silence_threshold_db:
audible_windows.append((start_ms, avg_db, peak_db))
return audible_windows
def _windows_to_segments(
self,
audible_windows: List[Tuple[int, float, float]],
audio: AudioSegment
) -> List[AudibleSegment]:
"""
Convert list of audible windows into contiguous segments.
"""
if not audible_windows:
return []
segments = []
segment_start_ms = audible_windows[0][0]
segment_dbs = [audible_windows[0][1]]
segment_peaks = [audible_windows[0][2]]
last_end_ms = audible_windows[0][0] + self.window_ms
for i in range(1, len(audible_windows)):
start_ms, avg_db, peak_db = audible_windows[i]
# Check if this window is contiguous with the previous
gap_ms = start_ms - last_end_ms
if gap_ms <= self.window_ms:
# Extend current segment
segment_dbs.append(avg_db)
segment_peaks.append(peak_db)
last_end_ms = start_ms + self.window_ms
else:
# Save current segment and start a new one
segments.append(self._create_segment(
segment_start_ms, last_end_ms, segment_dbs, segment_peaks
))
segment_start_ms = start_ms
segment_dbs = [avg_db]
segment_peaks = [peak_db]
last_end_ms = start_ms + self.window_ms
# Don't forget the last segment
segments.append(self._create_segment(
segment_start_ms, last_end_ms, segment_dbs, segment_peaks
))
return segments
def _create_segment(
self,
start_ms: int,
end_ms: int,
dbs: List[float],
peaks: List[float]
) -> AudibleSegment:
"""Create an AudibleSegment from window data."""
return AudibleSegment(
start_seconds=start_ms / 1000.0,
end_seconds=end_ms / 1000.0,
duration_seconds=(end_ms - start_ms) / 1000.0,
avg_amplitude_db=sum(dbs) / len(dbs) if dbs else -100.0,
peak_amplitude_db=max(peaks) if peaks else -100.0,
)
def _merge_and_filter_segments(
self,
segments: List[AudibleSegment]
) -> List[AudibleSegment]:
"""
Merge segments that are close together and filter out short ones.
"""
if not segments:
return []
# Sort by start time
segments = sorted(segments, key=lambda s: s.start_seconds)
# Merge segments with small gaps
merged = []
current = segments[0]
for next_seg in segments[1:]:
gap_ms = (next_seg.start_seconds - current.end_seconds) * 1000
if gap_ms <= self.merge_gap_ms:
# Merge segments
combined_duration = (
next_seg.end_seconds - current.start_seconds
)
# Weight average amplitude by duration
total_duration = (
current.duration_seconds + next_seg.duration_seconds
)
weighted_avg_db = (
(current.avg_amplitude_db * current.duration_seconds +
next_seg.avg_amplitude_db * next_seg.duration_seconds)
/ total_duration
) if total_duration > 0 else -100.0
current = AudibleSegment(
start_seconds=current.start_seconds,
end_seconds=next_seg.end_seconds,
duration_seconds=combined_duration,
avg_amplitude_db=weighted_avg_db,
peak_amplitude_db=max(
current.peak_amplitude_db,
next_seg.peak_amplitude_db
),
)
else:
merged.append(current)
current = next_seg
merged.append(current)
# Filter out segments shorter than minimum duration
min_duration_seconds = self.min_segment_duration_ms / 1000.0
filtered = [
seg for seg in merged
if seg.duration_seconds >= min_duration_seconds
]
return filtered
def _get_recommendation(
self,
has_audible_content: bool,
segments: List[AudibleSegment],
audible_percentage: float
) -> RecommendedSelection:
"""
Determine the recommended instrumental selection.
Logic:
- If no audible content: recommend clean instrumental
- If audible content covers > 20% of the audio: likely has
meaningful backing vocals, recommend review
- Otherwise: minimal content, recommend clean
"""
if not has_audible_content:
return RecommendedSelection.CLEAN
# If there's significant audible content, recommend review
if audible_percentage > 20.0:
return RecommendedSelection.REVIEW_NEEDED
# If there are loud segments, recommend review
loud_segments = [seg for seg in segments if seg.is_loud]
if loud_segments:
return RecommendedSelection.REVIEW_NEEDED
# Minimal content - recommend clean
return RecommendedSelection.CLEAN
+322
View File
@@ -0,0 +1,322 @@
"""
Audio editor for creating custom instrumentals with muted regions.
This module provides the AudioEditor class which creates custom instrumental
tracks by muting specified regions of backing vocals audio and combining
it with the clean instrumental.
"""
import logging
import os
from pathlib import Path
from typing import List, Optional
from pydub import AudioSegment
from .models import CustomInstrumentalResult, MuteRegion
logger = logging.getLogger(__name__)
class AudioEditor:
"""
Creates custom instrumentals by muting regions of backing vocals.
This class is pure Python with no cloud dependencies. It works with
local file paths and uses pydub for audio manipulation.
The editor takes a clean instrumental and backing vocals track,
applies silence to specified regions of the backing vocals, and
combines them to create a custom instrumental track.
Example:
>>> editor = AudioEditor()
>>> mute_regions = [
... MuteRegion(start_seconds=45.0, end_seconds=48.5),
... MuteRegion(start_seconds=120.0, end_seconds=125.0),
... ]
>>> result = editor.create_custom_instrumental(
... clean_instrumental_path="/path/to/clean.flac",
... backing_vocals_path="/path/to/backing.flac",
... mute_regions=mute_regions,
... output_path="/path/to/custom.flac"
... )
>>> print(f"Created: {result.output_path}")
"""
def __init__(self, output_format: str = "flac"):
"""
Initialize the audio editor.
Args:
output_format: Output audio format. Default is "flac".
Supported formats depend on ffmpeg installation.
"""
self.output_format = output_format
def create_custom_instrumental(
self,
clean_instrumental_path: str,
backing_vocals_path: str,
mute_regions: List[MuteRegion],
output_path: str,
) -> CustomInstrumentalResult:
"""
Create a custom instrumental by muting regions of backing vocals.
This method:
1. Loads the clean instrumental and backing vocals tracks
2. Applies silence to the specified regions of the backing vocals
3. Combines the clean instrumental with the edited backing vocals
4. Exports the result to the specified output path
Args:
clean_instrumental_path: Path to the clean instrumental audio file
backing_vocals_path: Path to the backing vocals audio file
mute_regions: List of regions to mute in the backing vocals
output_path: Path where the output file should be saved
Returns:
CustomInstrumentalResult containing the output path and statistics
Raises:
FileNotFoundError: If input files don't exist
ValueError: If mute regions are invalid
"""
# Validate inputs
if not Path(clean_instrumental_path).exists():
raise FileNotFoundError(
f"Clean instrumental not found: {clean_instrumental_path}"
)
if not Path(backing_vocals_path).exists():
raise FileNotFoundError(
f"Backing vocals not found: {backing_vocals_path}"
)
# Normalize and validate mute regions
normalized_regions = self._normalize_mute_regions(mute_regions)
logger.info(
f"Creating custom instrumental with {len(normalized_regions)} "
f"mute regions"
)
# Load audio files
logger.debug(f"Loading clean instrumental: {clean_instrumental_path}")
clean_instrumental = AudioSegment.from_file(clean_instrumental_path)
logger.debug(f"Loading backing vocals: {backing_vocals_path}")
backing_vocals = AudioSegment.from_file(backing_vocals_path)
# Ensure same duration (use shorter one)
clean_duration_ms = len(clean_instrumental)
backing_duration_ms = len(backing_vocals)
if abs(clean_duration_ms - backing_duration_ms) > 1000:
logger.warning(
f"Duration mismatch: clean={clean_duration_ms}ms, "
f"backing={backing_duration_ms}ms. Using shorter duration."
)
target_duration_ms = min(clean_duration_ms, backing_duration_ms)
clean_instrumental = clean_instrumental[:target_duration_ms]
backing_vocals = backing_vocals[:target_duration_ms]
# Apply mute regions to backing vocals
edited_backing = self._apply_mute_regions(
backing_vocals, normalized_regions
)
# Combine: clean instrumental + edited backing vocals
# The backing vocals are mixed on top of the clean instrumental
combined = clean_instrumental.overlay(edited_backing)
# Ensure output directory exists
output_dir = Path(output_path).parent
output_dir.mkdir(parents=True, exist_ok=True)
# Export
logger.info(f"Exporting custom instrumental to: {output_path}")
combined.export(output_path, format=self.output_format)
# Calculate statistics with clamping to actual audio duration
output_duration_seconds = len(combined) / 1000.0
total_muted_ms = sum(
(min(r.end_seconds, output_duration_seconds) - max(r.start_seconds, 0)) * 1000
for r in normalized_regions
if r.start_seconds < output_duration_seconds # Skip regions entirely outside audio
)
return CustomInstrumentalResult(
output_path=output_path,
mute_regions_applied=normalized_regions,
total_muted_duration_seconds=max(0, total_muted_ms / 1000.0),
output_duration_seconds=output_duration_seconds,
)
def apply_mute_to_single_track(
self,
audio_path: str,
mute_regions: List[MuteRegion],
output_path: str,
) -> str:
"""
Apply mute regions to a single audio track.
This is useful for muting sections of backing vocals without
combining with the clean instrumental.
Args:
audio_path: Path to the input audio file
mute_regions: List of regions to mute
output_path: Path where the output file should be saved
Returns:
Path to the output file
"""
if not Path(audio_path).exists():
raise FileNotFoundError(f"Audio file not found: {audio_path}")
normalized_regions = self._normalize_mute_regions(mute_regions)
logger.info(f"Applying {len(normalized_regions)} mute regions to audio")
audio = AudioSegment.from_file(audio_path)
edited = self._apply_mute_regions(audio, normalized_regions)
output_dir = Path(output_path).parent
output_dir.mkdir(parents=True, exist_ok=True)
edited.export(output_path, format=self.output_format)
return output_path
def _normalize_mute_regions(
self,
regions: List[MuteRegion]
) -> List[MuteRegion]:
"""
Normalize mute regions: sort, validate, and merge overlapping ones.
"""
if not regions:
return []
# Validate regions
for region in regions:
if region.start_seconds < 0:
raise ValueError(
f"Mute region start cannot be negative: {region.start_seconds}"
)
if region.end_seconds <= region.start_seconds:
raise ValueError(
f"Mute region end ({region.end_seconds}) must be after "
f"start ({region.start_seconds})"
)
# Sort by start time
sorted_regions = sorted(regions, key=lambda r: r.start_seconds)
# Merge overlapping regions
merged = [sorted_regions[0]]
for region in sorted_regions[1:]:
last = merged[-1]
# Check if overlapping or adjacent
if region.start_seconds <= last.end_seconds:
# Merge
merged[-1] = MuteRegion(
start_seconds=last.start_seconds,
end_seconds=max(last.end_seconds, region.end_seconds)
)
else:
merged.append(region)
return merged
def _apply_mute_regions(
self,
audio: AudioSegment,
regions: List[MuteRegion]
) -> AudioSegment:
"""
Apply silence to the specified regions of an audio segment.
"""
if not regions:
return audio
duration_ms = len(audio)
result = audio
for region in regions:
start_ms = int(region.start_seconds * 1000)
end_ms = int(region.end_seconds * 1000)
# Clamp to audio boundaries
start_ms = max(0, start_ms)
end_ms = min(duration_ms, end_ms)
if start_ms >= end_ms:
continue
# Create silence segment
silence_duration = end_ms - start_ms
silence = AudioSegment.silent(
duration=silence_duration,
frame_rate=audio.frame_rate
)
# Replace the region with silence
before = result[:start_ms]
after = result[end_ms:]
result = before + silence + after
logger.debug(
f"Muted region: {start_ms/1000:.2f}s - {end_ms/1000:.2f}s"
)
return result
def preview_with_mutes(
self,
clean_instrumental_path: str,
backing_vocals_path: str,
mute_regions: List[MuteRegion],
output_path: Optional[str] = None,
) -> AudioSegment:
"""
Create a preview of the custom instrumental (in memory).
This is useful for creating temporary previews without saving
to disk. If output_path is provided, the preview is also saved.
Args:
clean_instrumental_path: Path to the clean instrumental
backing_vocals_path: Path to the backing vocals
mute_regions: Regions to mute
output_path: Optional path to save the preview
Returns:
AudioSegment of the preview
"""
clean_instrumental = AudioSegment.from_file(clean_instrumental_path)
backing_vocals = AudioSegment.from_file(backing_vocals_path)
# Match durations
target_duration = min(len(clean_instrumental), len(backing_vocals))
clean_instrumental = clean_instrumental[:target_duration]
backing_vocals = backing_vocals[:target_duration]
# Apply mutes
normalized = self._normalize_mute_regions(mute_regions)
edited_backing = self._apply_mute_regions(backing_vocals, normalized)
# Combine
combined = clean_instrumental.overlay(edited_backing)
if output_path:
Path(output_path).parent.mkdir(parents=True, exist_ok=True)
combined.export(output_path, format=self.output_format)
return combined
+171
View File
@@ -0,0 +1,171 @@
"""
Pydantic models for the instrumental review module.
These models define the data structures used for audio analysis results,
mute regions, and recommendations. They're designed to be serializable
to JSON for API responses.
"""
from enum import Enum
from typing import List, Optional
from pydantic import BaseModel, Field
class RecommendedSelection(str, Enum):
"""Recommendation for which instrumental to use."""
CLEAN = "clean"
"""Use clean instrumental - no backing vocals detected or recommended."""
WITH_BACKING = "with_backing"
"""Use instrumental with backing vocals - backing vocals sound good."""
REVIEW_NEEDED = "review_needed"
"""Human review needed - backing vocals detected but quality uncertain."""
class AudibleSegment(BaseModel):
"""A detected segment of audible content in the backing vocals."""
start_seconds: float = Field(
...,
ge=0,
description="Start time of the segment in seconds"
)
end_seconds: float = Field(
...,
ge=0,
description="End time of the segment in seconds"
)
duration_seconds: float = Field(
...,
ge=0,
description="Duration of the segment in seconds"
)
avg_amplitude_db: float = Field(
...,
description="Average amplitude of the segment in dB"
)
peak_amplitude_db: float = Field(
default=0.0,
description="Peak amplitude of the segment in dB"
)
@property
def is_loud(self) -> bool:
"""Check if this segment is relatively loud (> -20dB average)."""
return self.avg_amplitude_db > -20.0
class MuteRegion(BaseModel):
"""A region to mute in the backing vocals audio."""
start_seconds: float = Field(
...,
ge=0,
description="Start time of the region to mute in seconds"
)
end_seconds: float = Field(
...,
ge=0,
description="End time of the region to mute in seconds"
)
@property
def duration_seconds(self) -> float:
"""Duration of the mute region in seconds."""
return self.end_seconds - self.start_seconds
def overlaps(self, other: "MuteRegion") -> bool:
"""Check if this region overlaps with another."""
return not (self.end_seconds <= other.start_seconds or
self.start_seconds >= other.end_seconds)
def merge(self, other: "MuteRegion") -> "MuteRegion":
"""Merge this region with another overlapping region."""
return MuteRegion(
start_seconds=min(self.start_seconds, other.start_seconds),
end_seconds=max(self.end_seconds, other.end_seconds)
)
class AnalysisResult(BaseModel):
"""Result of analyzing backing vocals audio for audible content."""
has_audible_content: bool = Field(
...,
description="Whether any audible content was detected"
)
total_duration_seconds: float = Field(
...,
ge=0,
description="Total duration of the audio file in seconds"
)
audible_segments: List[AudibleSegment] = Field(
default_factory=list,
description="List of detected audible segments"
)
recommended_selection: RecommendedSelection = Field(
...,
description="Recommended instrumental selection based on analysis"
)
silence_threshold_db: float = Field(
default=-40.0,
description="Threshold used to detect silence (in dB)"
)
total_audible_duration_seconds: float = Field(
default=0.0,
ge=0,
description="Total duration of all audible segments combined"
)
audible_percentage: float = Field(
default=0.0,
ge=0,
le=100,
description="Percentage of audio that is audible"
)
waveform_data: Optional[List[float]] = Field(
default=None,
description="Amplitude envelope data for waveform rendering (optional)"
)
@property
def segment_count(self) -> int:
"""Number of audible segments detected."""
return len(self.audible_segments)
def get_segments_in_range(
self,
start_seconds: float,
end_seconds: float
) -> List[AudibleSegment]:
"""Get segments that overlap with the given time range."""
return [
seg for seg in self.audible_segments
if not (seg.end_seconds <= start_seconds or
seg.start_seconds >= end_seconds)
]
class CustomInstrumentalResult(BaseModel):
"""Result of creating a custom instrumental with muted regions."""
output_path: str = Field(
...,
description="Path to the created custom instrumental file"
)
mute_regions_applied: List[MuteRegion] = Field(
default_factory=list,
description="List of mute regions that were applied"
)
total_muted_duration_seconds: float = Field(
default=0.0,
ge=0,
description="Total duration of muted audio in seconds"
)
output_duration_seconds: float = Field(
default=0.0,
ge=0,
description="Duration of the output file in seconds"
)
+423
View File
@@ -0,0 +1,423 @@
"""
Local FastAPI server for instrumental review.
This module provides a local HTTP server that serves the instrumental review
UI for local CLI usage. It provides the same API endpoints as the cloud backend
to enable UI reuse.
Similar pattern to LyricsTranscriber's ReviewServer.
"""
import logging
import os
from pathlib import Path
import threading
import webbrowser
from typing import List, Optional
from fastapi import FastAPI, HTTPException, UploadFile, File
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import FileResponse, HTMLResponse
from pydantic import BaseModel
import shutil
import tempfile
import uvicorn
from pydub import AudioSegment
from karaoke_gen.instrumental_review import (
AnalysisResult,
AudioAnalyzer,
AudioEditor,
MuteRegion,
WaveformGenerator,
)
logger = logging.getLogger(__name__)
# Request/Response Models
class MuteRegionRequest(BaseModel):
start_seconds: float
end_seconds: float
class CreateCustomRequest(BaseModel):
mute_regions: List[MuteRegionRequest]
class SelectionRequest(BaseModel):
selection: str
class InstrumentalReviewServer:
"""
Local FastAPI server for instrumental review UI.
This server provides a web interface for reviewing and selecting
instrumental tracks in the local CLI workflow. It serves the same
API endpoints as the cloud backend to enable UI reuse.
"""
def __init__(
self,
output_dir: str,
base_name: str,
analysis: AnalysisResult,
waveform_path: str,
backing_vocals_path: str,
clean_instrumental_path: str,
with_backing_path: Optional[str] = None,
original_audio_path: Optional[str] = None,
):
"""
Initialize the review server.
Args:
output_dir: Directory containing the audio files
base_name: Base name for output files (e.g., "Artist - Title")
analysis: Analysis result from AudioAnalyzer
waveform_path: Path to the waveform image
backing_vocals_path: Path to the backing vocals audio file
clean_instrumental_path: Path to the clean instrumental audio file
with_backing_path: Path to the instrumental with backing vocals
original_audio_path: Path to the original audio file (with vocals)
"""
self.output_dir = output_dir
self.base_name = base_name
self.analysis = analysis
self.waveform_path = waveform_path
self.backing_vocals_path = backing_vocals_path
self.clean_instrumental_path = clean_instrumental_path
self.with_backing_path = with_backing_path
self.original_audio_path = original_audio_path
self.custom_instrumental_path: Optional[str] = None
self.uploaded_instrumental_path: Optional[str] = None
self.selection: Optional[str] = None
self._app: Optional[FastAPI] = None
self._server_thread: Optional[threading.Thread] = None
self._selection_event = threading.Event()
self._shutdown_event = threading.Event()
def _create_app(self) -> FastAPI:
"""Create and configure the FastAPI application."""
app = FastAPI(title="Instrumental Review", docs_url=None, redoc_url=None)
# Configure CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Register routes
self._register_routes(app)
return app
def _register_routes(self, app: FastAPI) -> None:
"""Register API routes."""
@app.get("/")
async def serve_frontend():
"""Serve the frontend HTML."""
return HTMLResponse(content=self._get_frontend_html())
@app.get("/api/jobs/local/instrumental-analysis")
async def get_analysis():
"""Get analysis data for the instrumental review."""
return {
"job_id": "local",
"artist": self.base_name.split(" - ")[0] if " - " in self.base_name else "",
"title": self.base_name.split(" - ")[1] if " - " in self.base_name else self.base_name,
"status": "awaiting_instrumental_selection",
"analysis": {
"has_audible_content": self.analysis.has_audible_content,
"total_duration_seconds": self.analysis.total_duration_seconds,
"audible_segments": [
{
"start_seconds": seg.start_seconds,
"end_seconds": seg.end_seconds,
"duration_seconds": seg.duration_seconds,
"avg_amplitude_db": seg.avg_amplitude_db,
"peak_amplitude_db": seg.peak_amplitude_db,
}
for seg in self.analysis.audible_segments
],
"recommended_selection": self.analysis.recommended_selection.value,
"total_audible_duration_seconds": self.analysis.total_audible_duration_seconds,
"audible_percentage": self.analysis.audible_percentage,
"silence_threshold_db": self.analysis.silence_threshold_db,
},
"audio_urls": {
"clean_instrumental": "/api/audio/clean_instrumental" if self.clean_instrumental_path else None,
"backing_vocals": "/api/audio/backing_vocals" if self.backing_vocals_path else None,
"with_backing": "/api/audio/with_backing" if self.with_backing_path else None,
"custom_instrumental": "/api/audio/custom_instrumental" if self.custom_instrumental_path else None,
"uploaded_instrumental": "/api/audio/uploaded_instrumental" if self.uploaded_instrumental_path else None,
"original": "/api/audio/original" if self.original_audio_path else None,
},
"waveform_url": "/api/waveform" if self.waveform_path else None,
"has_custom_instrumental": self.custom_instrumental_path is not None,
"has_uploaded_instrumental": self.uploaded_instrumental_path is not None,
"has_original": self.original_audio_path is not None,
}
@app.get("/api/jobs/local/waveform-data")
async def get_waveform_data(num_points: int = 600):
"""Get waveform amplitude data for client-side rendering."""
# Validate num_points parameter
if num_points <= 0 or num_points > 10000:
raise HTTPException(
status_code=400,
detail="num_points must be between 1 and 10000"
)
if not self.backing_vocals_path or not os.path.exists(self.backing_vocals_path):
raise HTTPException(status_code=404, detail="Backing vocals file not found")
try:
generator = WaveformGenerator()
amplitudes, duration = generator.generate_data_only(self.backing_vocals_path, num_points)
return {"amplitudes": amplitudes, "duration": duration}
except Exception as e:
logger.exception(f"Error generating waveform data: {e}")
raise HTTPException(status_code=500, detail=str(e)) from e
@app.get("/api/audio/{stem_type}")
async def stream_audio(stem_type: str):
"""Stream audio file."""
path_map = {
"clean_instrumental": self.clean_instrumental_path,
"backing_vocals": self.backing_vocals_path,
"with_backing": self.with_backing_path,
"custom_instrumental": self.custom_instrumental_path,
"uploaded_instrumental": self.uploaded_instrumental_path,
"original": self.original_audio_path,
}
audio_path = path_map.get(stem_type)
if not audio_path or not os.path.exists(audio_path):
raise HTTPException(status_code=404, detail=f"Audio file not found: {stem_type}")
# Determine content type
ext = os.path.splitext(audio_path)[1].lower()
content_types = {
".flac": "audio/flac",
".mp3": "audio/mpeg",
".wav": "audio/wav",
}
content_type = content_types.get(ext, "application/octet-stream")
return FileResponse(audio_path, media_type=content_type)
@app.get("/api/waveform")
async def get_waveform_image():
"""Serve waveform image."""
if not self.waveform_path or not os.path.exists(self.waveform_path):
raise HTTPException(status_code=404, detail="Waveform image not found")
return FileResponse(self.waveform_path, media_type="image/png")
@app.post("/api/jobs/local/create-custom-instrumental")
async def create_custom_instrumental(request: CreateCustomRequest):
"""Create a custom instrumental with muted regions."""
if not request.mute_regions:
raise HTTPException(status_code=400, detail="No mute regions provided")
try:
mute_regions = [
MuteRegion(
start_seconds=r.start_seconds,
end_seconds=r.end_seconds,
)
for r in request.mute_regions
]
editor = AudioEditor()
output_path = os.path.join(
self.output_dir,
f"{self.base_name} (Instrumental Custom).flac"
)
result = editor.create_custom_instrumental(
clean_instrumental_path=self.clean_instrumental_path,
backing_vocals_path=self.backing_vocals_path,
mute_regions=mute_regions,
output_path=output_path,
)
self.custom_instrumental_path = result.output_path
return {
"status": "success",
"custom_instrumental_url": "/api/audio/custom_instrumental",
"statistics": {
"mute_regions_applied": len(result.mute_regions_applied),
"total_muted_duration_seconds": result.total_muted_duration_seconds,
"output_duration_seconds": result.output_duration_seconds,
},
}
except Exception as e:
logger.exception(f"Error creating custom instrumental: {e}")
raise HTTPException(status_code=500, detail=str(e)) from e
@app.post("/api/jobs/local/upload-instrumental")
async def upload_instrumental(file: UploadFile = File(...)):
"""Upload a custom instrumental audio file."""
# Validate file type
allowed_extensions = {".flac", ".mp3", ".wav", ".m4a", ".ogg"}
ext = os.path.splitext(file.filename or "")[1].lower()
if ext not in allowed_extensions:
raise HTTPException(
status_code=400,
detail=f"Invalid file type. Allowed: {', '.join(allowed_extensions)}"
)
tmp_path = None
file_moved = False
try:
# Save to temp file first to validate
with tempfile.NamedTemporaryFile(delete=False, suffix=ext) as tmp:
shutil.copyfileobj(file.file, tmp)
tmp_path = tmp.name
# Load and check duration
uploaded_audio = AudioSegment.from_file(tmp_path)
uploaded_duration = len(uploaded_audio) / 1000.0 # ms to seconds
expected_duration = self.analysis.total_duration_seconds
duration_diff = abs(uploaded_duration - expected_duration)
if duration_diff > 0.5:
raise HTTPException(
status_code=400,
detail=f"Duration mismatch: uploaded file is {uploaded_duration:.2f}s, "
f"expected {expected_duration:.2f}s (±0.5s allowed)"
)
# Move to final location
output_path = os.path.join(
self.output_dir,
f"{self.base_name} (Instrumental Uploaded){ext}"
)
shutil.move(tmp_path, output_path)
file_moved = True
self.uploaded_instrumental_path = output_path
return {
"status": "success",
"uploaded_instrumental_url": "/api/audio/uploaded_instrumental",
"duration_seconds": uploaded_duration,
"filename": file.filename,
}
except HTTPException:
raise
except Exception as e:
logger.exception(f"Error uploading instrumental: {e}")
raise HTTPException(status_code=500, detail=str(e)) from e
finally:
# Clean up temp file if it wasn't moved
if tmp_path and not file_moved and os.path.exists(tmp_path):
try:
os.unlink(tmp_path)
except OSError:
pass # Best effort cleanup
@app.post("/api/jobs/local/select-instrumental")
async def select_instrumental(request: SelectionRequest):
"""Submit instrumental selection."""
if request.selection not in ("clean", "with_backing", "custom", "uploaded", "original"):
raise HTTPException(status_code=400, detail=f"Invalid selection: {request.selection}")
self.selection = request.selection
self._selection_event.set()
return {"status": "success", "selection": request.selection}
@staticmethod
def _get_static_dir() -> Path:
"""Get the path to the static assets directory."""
return Path(__file__).parent / "static"
def _get_frontend_html(self) -> str:
"""Return the frontend HTML by reading from the static file."""
static_file = self._get_static_dir() / "index.html"
if static_file.exists():
return static_file.read_text(encoding="utf-8")
else:
# Fallback error message if file is missing
return """<!DOCTYPE html>
<html>
<head><title>Error</title></head>
<body style="background:#1a1a1a;color:#fff;font-family:sans-serif;padding:2rem;">
<h1>Frontend assets not found</h1>
<p>The static/index.html file is missing from the instrumental_review module.</p>
</body>
</html>"""
def start_and_open_browser(self, port: int = 8765) -> str:
"""
Start server, open browser, and block until selection is submitted.
Args:
port: Port to run the server on
Returns:
The user's selection ("clean", "with_backing", or "custom")
"""
self._app = self._create_app()
# Run uvicorn in a separate thread
config = uvicorn.Config(
self._app,
host="127.0.0.1",
port=port,
log_level="warning",
)
server = uvicorn.Server(config)
def run_server():
server.run()
self._server_thread = threading.Thread(target=run_server, daemon=True)
self._server_thread.start()
# Wait a moment for server to start
import time
time.sleep(0.5)
url = f"http://localhost:{port}/"
logger.info(f"Instrumental review server started at {url}")
# Open browser
webbrowser.open(url)
# Wait for selection
logger.info("Waiting for instrumental selection...")
self._selection_event.wait()
# Give a moment for response to be sent
time.sleep(0.5)
return self.get_selection()
def stop(self) -> None:
"""Stop the server."""
self._shutdown_event.set()
def get_selection(self) -> str:
"""Get the user's selection."""
if self.selection is None:
raise ValueError("No selection has been made")
return self.selection
def get_custom_instrumental_path(self) -> Optional[str]:
"""Get the path to the custom instrumental if one was created."""
return self.custom_instrumental_path
def get_uploaded_instrumental_path(self) -> Optional[str]:
"""Get the path to the uploaded instrumental if one was uploaded."""
return self.uploaded_instrumental_path
File diff suppressed because it is too large. Load diff
+409
View File
@@ -0,0 +1,409 @@
"""
Waveform visualization generator for audio files.
This module provides the WaveformGenerator class which creates waveform
images suitable for display in the instrumental review UI.
"""
import logging
import math
from pathlib import Path
from typing import List, Optional, Tuple
import matplotlib
matplotlib.use('Agg') # Use non-interactive backend
import matplotlib.pyplot as plt
import numpy as np
from pydub import AudioSegment
from .models import AudibleSegment, MuteRegion
logger = logging.getLogger(__name__)
class WaveformGenerator:
"""
Generates waveform visualization images from audio files.
This class creates PNG images showing the amplitude envelope of an
audio file over time. It can highlight detected audible segments
and mute regions with different colors.
The generated images are suitable for display in web UIs and can
be used for interactive seeking (click-to-seek) functionality.
Attributes:
width: Width of the output image in pixels (default: 1200)
height: Height of the output image in pixels (default: 200)
background_color: Background color (default: "#1a1a2e")
waveform_color: Main waveform color (default: "#4a90d9")
segment_color: Color for audible segments (default: "#e94560")
mute_color: Color for mute regions (default: "#ff6b6b")
time_axis_color: Color for time axis (default: "#ffffff")
Example:
>>> generator = WaveformGenerator(width=1200, height=200)
>>> generator.generate(
... audio_path="/path/to/backing_vocals.flac",
... output_path="/path/to/waveform.png",
... segments=analysis_result.audible_segments
... )
"""
def __init__(
self,
width: int = 1200,
height: int = 200,
background_color: str = "#1a1a2e",
waveform_color: str = "#4a90d9",
segment_color: str = "#e94560",
mute_color: str = "#ff6b6b",
time_axis_color: str = "#ffffff",
dpi: int = 100,
):
"""
Initialize the waveform generator.
Args:
width: Width of the output image in pixels
height: Height of the output image in pixels
background_color: Background color (hex or named color)
waveform_color: Main waveform color
segment_color: Color for highlighting audible segments
mute_color: Color for highlighting mute regions
time_axis_color: Color for time axis labels
dpi: DPI for the output image
"""
self.width = width
self.height = height
self.background_color = background_color
self.waveform_color = waveform_color
self.segment_color = segment_color
self.mute_color = mute_color
self.time_axis_color = time_axis_color
self.dpi = dpi
def generate(
self,
audio_path: str,
output_path: str,
segments: Optional[List[AudibleSegment]] = None,
mute_regions: Optional[List[MuteRegion]] = None,
show_time_axis: bool = True,
silence_threshold_db: float = -40.0,
) -> str:
"""
Generate a waveform image from an audio file.
Args:
audio_path: Path to the audio file
output_path: Path where the PNG image will be saved
segments: Optional list of audible segments to highlight
mute_regions: Optional list of mute regions to highlight
show_time_axis: Whether to show time axis labels
silence_threshold_db: Threshold for visual reference line
Returns:
Path to the generated image file
Raises:
FileNotFoundError: If the audio file doesn't exist
"""
path = Path(audio_path)
if not path.exists():
raise FileNotFoundError(f"Audio file not found: {audio_path}")
logger.info(f"Generating waveform for: {audio_path}")
# Load audio
audio = AudioSegment.from_file(audio_path)
duration_seconds = len(audio) / 1000.0
# Convert to mono if needed
if audio.channels > 1:
audio = audio.set_channels(1)
# Get amplitude envelope
envelope = self._get_envelope(audio)
# Create the figure
fig, ax = self._create_figure(duration_seconds, show_time_axis)
# Draw waveform
self._draw_waveform(ax, envelope, duration_seconds)
# Highlight mute regions (if any) - draw first so waveform is on top
if mute_regions:
self._draw_mute_regions(ax, mute_regions, duration_seconds)
# Highlight audible segments (if any)
if segments:
self._draw_segments(ax, segments, envelope, duration_seconds)
# Draw silence threshold reference line
self._draw_threshold_line(ax, silence_threshold_db, duration_seconds)
# Save the figure
output_dir = Path(output_path).parent
output_dir.mkdir(parents=True, exist_ok=True)
fig.savefig(
output_path,
facecolor=self.background_color,
edgecolor='none',
bbox_inches='tight',
pad_inches=0.1,
)
plt.close(fig)
logger.info(f"Waveform saved to: {output_path}")
return output_path
def generate_data_only(
self,
audio_path: str,
num_points: int = 500,
) -> Tuple[List[float], float]:
"""
Generate waveform data without creating an image.
This is useful for sending data to a frontend that will
render the waveform itself (e.g., using Canvas or SVG).
Args:
audio_path: Path to the audio file
num_points: Number of data points to return
Returns:
Tuple of (amplitude_values, duration_seconds)
Amplitude values are normalized to 0.0-1.0 range.
"""
path = Path(audio_path)
if not path.exists():
raise FileNotFoundError(f"Audio file not found: {audio_path}")
audio = AudioSegment.from_file(audio_path)
duration_seconds = len(audio) / 1000.0
if audio.channels > 1:
audio = audio.set_channels(1)
# Calculate window size to get desired number of points
duration_ms = len(audio)
window_ms = max(1, duration_ms // num_points)
amplitudes = []
for start_ms in range(0, duration_ms, window_ms):
end_ms = min(start_ms + window_ms, duration_ms)
window = audio[start_ms:end_ms]
if window.rms > 0:
db = 20 * math.log10(window.rms / window.max_possible_amplitude)
else:
db = -100.0
# Normalize to 0-1 range (mapping -60dB to 0dB -> 0 to 1)
normalized = max(0.0, min(1.0, (db + 60) / 60))
amplitudes.append(normalized)
return amplitudes, duration_seconds
def _get_envelope(
self,
audio: AudioSegment,
window_ms: int = 50,
) -> np.ndarray:
"""
Extract amplitude envelope from audio.
Returns array of amplitude values in dB.
"""
duration_ms = len(audio)
amplitudes = []
for start_ms in range(0, duration_ms, window_ms):
end_ms = min(start_ms + window_ms, duration_ms)
window = audio[start_ms:end_ms]
if window.rms > 0:
db = 20 * math.log10(window.rms / window.max_possible_amplitude)
else:
db = -100.0
amplitudes.append(db)
return np.array(amplitudes)
def _create_figure(
self,
duration_seconds: float,
show_time_axis: bool,
) -> Tuple[plt.Figure, plt.Axes]:
"""
Create matplotlib figure and axes.
"""
fig_width = self.width / self.dpi
fig_height = self.height / self.dpi
fig, ax = plt.subplots(figsize=(fig_width, fig_height), dpi=self.dpi)
# Set background
fig.patch.set_facecolor(self.background_color)
ax.set_facecolor(self.background_color)
# Configure axes
ax.set_xlim(0, duration_seconds)
ax.set_ylim(-60, 0) # dB range
# Remove spines
for spine in ax.spines.values():
spine.set_visible(False)
# Configure ticks
if show_time_axis:
ax.tick_params(
axis='x',
colors=self.time_axis_color,
labelsize=8,
)
ax.tick_params(axis='y', left=False, labelleft=False)
# Set time axis ticks
self._set_time_ticks(ax, duration_seconds)
else:
ax.tick_params(
axis='both',
left=False,
bottom=False,
labelleft=False,
labelbottom=False,
)
return fig, ax
def _set_time_ticks(self, ax: plt.Axes, duration_seconds: float):
"""
Set appropriate time axis tick marks.
"""
if duration_seconds <= 60:
# Under 1 minute: tick every 10 seconds
tick_interval = 10
elif duration_seconds <= 300:
# Under 5 minutes: tick every 30 seconds
tick_interval = 30
else:
# Over 5 minutes: tick every minute
tick_interval = 60
ticks = np.arange(0, duration_seconds + 1, tick_interval)
ax.set_xticks(ticks)
# Format tick labels as MM:SS
labels = []
for t in ticks:
minutes = int(t // 60)
seconds = int(t % 60)
labels.append(f"{minutes}:{seconds:02d}")
ax.set_xticklabels(labels)
def _draw_waveform(
self,
ax: plt.Axes,
envelope: np.ndarray,
duration_seconds: float,
):
"""
Draw the main waveform.
"""
num_points = len(envelope)
time_points = np.linspace(0, duration_seconds, num_points)
# Draw as filled area
ax.fill_between(
time_points,
envelope,
-60, # Bottom of range
color=self.waveform_color,
alpha=0.7,
)
# Draw outline
ax.plot(
time_points,
envelope,
color=self.waveform_color,
linewidth=0.5,
alpha=0.9,
)
def _draw_segments(
self,
ax: plt.Axes,
segments: List[AudibleSegment],
envelope: np.ndarray,
duration_seconds: float,
):
"""
Highlight audible segments on the waveform.
"""
num_points = len(envelope)
time_points = np.linspace(0, duration_seconds, num_points)
for segment in segments:
# Find indices corresponding to this segment
start_idx = int(segment.start_seconds / duration_seconds * num_points)
end_idx = int(segment.end_seconds / duration_seconds * num_points)
start_idx = max(0, min(start_idx, num_points - 1))
end_idx = max(0, min(end_idx, num_points))
if start_idx >= end_idx:
continue
segment_time = time_points[start_idx:end_idx]
segment_envelope = envelope[start_idx:end_idx]
# Highlight this segment with a different color
ax.fill_between(
segment_time,
segment_envelope,
-60,
color=self.segment_color,
alpha=0.6,
)
def _draw_mute_regions(
self,
ax: plt.Axes,
mute_regions: List[MuteRegion],
duration_seconds: float,
):
"""
Draw mute region overlays.
"""
for region in mute_regions:
ax.axvspan(
region.start_seconds,
region.end_seconds,
color=self.mute_color,
alpha=0.3,
zorder=0,
)
def _draw_threshold_line(
self,
ax: plt.Axes,
threshold_db: float,
duration_seconds: float,
):
"""
Draw a reference line at the silence threshold.
"""
ax.axhline(
y=threshold_db,
color=self.time_axis_color,
linestyle='--',
linewidth=0.5,
alpha=0.3,
)
@@ -54,6 +54,9 @@ class KaraokeFinalise:
if logger is None:
self.logger = logging.getLogger(__name__)
self.logger.setLevel(log_level)
# Prevent log propagation to root logger to avoid duplicate logs
# when external packages (like lyrics_converter) configure root logger handlers
self.logger.propagate = False
self.log_handler = logging.StreamHandler()
+3
View File
@@ -84,6 +84,9 @@ class KaraokePrep:
if logger is None:
self.logger = logging.getLogger(__name__)
self.logger.setLevel(log_level)
# Prevent log propagation to root logger to avoid duplicate logs
# when external packages (like lyrics_converter) configure root logger handlers
self.logger.propagate = False
self.log_handler = logging.StreamHandler()
+3
View File
@@ -19,6 +19,9 @@ from karaoke_gen.karaoke_finalise import KaraokeFinalise
# Global logger
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO) # Set initial log level
# Prevent log propagation to root logger to avoid duplicate logs
# when external packages (like lyrics_converter) configure root logger handlers
logger.propagate = False
async def process_track_prep(row, args, logger, log_formatter):
+5
View File
@@ -208,6 +208,11 @@ def create_parser(prog: str = "karaoke-gen") -> argparse.ArgumentParser:
default="flac",
help="Optional: format / file extension for instrumental track to use for remux (default: %(default)s). Example: --instrumental_format=mp3",
)
audio_group.add_argument(
"--skip_instrumental_review",
action="store_true",
help="Optional: Skip the interactive instrumental review UI and use the old numeric selection. Example: --skip_instrumental_review",
)
# Lyrics Configuration
lyrics_group = parser.add_argument_group("Lyrics Configuration")
+319
View File
@@ -14,14 +14,277 @@ import sys
import json
import asyncio
import time
import glob
import pyperclip
from karaoke_gen import KaraokePrep
from karaoke_gen.karaoke_finalise import KaraokeFinalise
from karaoke_gen.instrumental_review import (
AudioAnalyzer,
WaveformGenerator,
InstrumentalReviewServer,
)
from .cli_args import create_parser, process_style_overrides, is_url, is_file
def _resolve_path_for_cwd(path: str, track_dir: str) -> str:
"""
Resolve a path that may have been created relative to the original working directory.
After os.chdir(track_dir), paths like './TrackDir/stems/file.flac' become invalid.
This function converts such paths to work from the new current directory.
Args:
path: The path to resolve (may be relative or absolute)
track_dir: The track directory we've chdir'd into
Returns:
A path that's valid from the current working directory
"""
if os.path.isabs(path):
return path
# Normalize both paths for comparison
norm_path = os.path.normpath(path)
norm_track_dir = os.path.normpath(track_dir)
# If path starts with track_dir, strip it to get the relative path from within track_dir
# e.g., './Four Lanes Male Choir - The White Rose/stems/file.flac' -> 'stems/file.flac'
if norm_path.startswith(norm_track_dir + os.sep):
return norm_path[len(norm_track_dir) + 1:]
elif norm_path.startswith(norm_track_dir):
return norm_path[len(norm_track_dir):].lstrip(os.sep) or '.'
# If path doesn't start with track_dir, it might already be relative to track_dir
# or it's a path that doesn't need transformation
return path
def auto_select_instrumental(track: dict, track_dir: str, logger: logging.Logger) -> str:
"""
Auto-select the best instrumental file when --skip_instrumental_review is used.
Selection priority:
1. Padded combined instrumental (+BV) - synchronized with vocals + backing vocals
2. Non-padded combined instrumental (+BV) - has backing vocals
3. Padded clean instrumental - synchronized with vocals
4. Non-padded clean instrumental - basic instrumental
Args:
track: The track dictionary from KaraokePrep containing separated audio info
track_dir: The track output directory (we're already chdir'd into it)
logger: Logger instance
Returns:
Path to the selected instrumental file
Raises:
FileNotFoundError: If no suitable instrumental file can be found
"""
separated = track.get("separated_audio", {})
# Look for combined instrumentals first (they include backing vocals)
combined = separated.get("combined_instrumentals", {})
for model, path in combined.items():
if path:
resolved = _resolve_path_for_cwd(path, track_dir)
# Prefer padded version if it exists
base, ext = os.path.splitext(resolved)
padded = f"{base} (Padded){ext}"
if os.path.exists(padded):
logger.info(f"Auto-selected padded combined instrumental: {padded}")
return padded
if os.path.exists(resolved):
logger.info(f"Auto-selected combined instrumental: {resolved}")
return resolved
# Fall back to clean instrumental
clean = separated.get("clean_instrumental", {})
if clean.get("instrumental"):
resolved = _resolve_path_for_cwd(clean["instrumental"], track_dir)
# Prefer padded version if it exists
base, ext = os.path.splitext(resolved)
padded = f"{base} (Padded){ext}"
if os.path.exists(padded):
logger.info(f"Auto-selected padded clean instrumental: {padded}")
return padded
if os.path.exists(resolved):
logger.info(f"Auto-selected clean instrumental: {resolved}")
return resolved
# If separated_audio doesn't have what we need, search the directory
# This handles edge cases and custom instrumentals
logger.info("No instrumental found in separated_audio, searching directory...")
instrumental_files = glob.glob("*(Instrumental*.flac") + glob.glob("*(Instrumental*.wav")
# Sort to prefer padded versions and combined instrumentals
padded_combined = [f for f in instrumental_files if "(Padded)" in f and "+BV" in f]
if padded_combined:
logger.info(f"Auto-selected from directory: {padded_combined[0]}")
return padded_combined[0]
padded_files = [f for f in instrumental_files if "(Padded)" in f]
if padded_files:
logger.info(f"Auto-selected from directory: {padded_files[0]}")
return padded_files[0]
combined_files = [f for f in instrumental_files if "+BV" in f]
if combined_files:
logger.info(f"Auto-selected from directory: {combined_files[0]}")
return combined_files[0]
if instrumental_files:
logger.info(f"Auto-selected from directory: {instrumental_files[0]}")
return instrumental_files[0]
raise FileNotFoundError(
"No instrumental file found. Audio separation may have failed. "
"Check the stems/ directory for separated audio files."
)
def run_instrumental_review(track: dict, logger: logging.Logger) -> str | None:
"""
Run the instrumental review UI to let user select the best instrumental track.
This analyzes the backing vocals, generates a waveform, and opens a browser
with an interactive UI for reviewing and selecting the instrumental.
Args:
track: The track dictionary from KaraokePrep containing separated audio info
logger: Logger instance
Returns:
Path to the selected instrumental file, or None to use the old numeric selection
"""
track_dir = track.get("track_output_dir", ".")
artist = track.get("artist", "")
title = track.get("title", "")
base_name = f"{artist} - {title}"
# Get separation results
separated = track.get("separated_audio", {})
if not separated:
logger.info("No separated audio found, skipping instrumental review UI")
return None
# Find the backing vocals file
# Note: Paths in separated_audio may be relative to the original working directory,
# but we've already chdir'd into track_dir. Use _resolve_path_for_cwd to fix paths.
backing_vocals_path = None
backing_vocals_result = separated.get("backing_vocals", {})
for model, paths in backing_vocals_result.items():
if paths.get("backing_vocals"):
backing_vocals_path = _resolve_path_for_cwd(paths["backing_vocals"], track_dir)
break
if not backing_vocals_path or not os.path.exists(backing_vocals_path):
logger.info("No backing vocals file found, skipping instrumental review UI")
return None
# Find the clean instrumental file
clean_result = separated.get("clean_instrumental", {})
raw_clean_path = clean_result.get("instrumental")
clean_instrumental_path = _resolve_path_for_cwd(raw_clean_path, track_dir) if raw_clean_path else None
if not clean_instrumental_path or not os.path.exists(clean_instrumental_path):
logger.info("No clean instrumental file found, skipping instrumental review UI")
return None
# Find the combined instrumental (with backing vocals) file - these have "(Padded)" suffix if padded
combined_result = separated.get("combined_instrumentals", {})
with_backing_path = None
for model, path in combined_result.items():
resolved_path = _resolve_path_for_cwd(path, track_dir) if path else None
if resolved_path and os.path.exists(resolved_path):
with_backing_path = resolved_path
break
try:
logger.info("=== Starting Instrumental Review ===")
logger.info(f"Analyzing backing vocals: {backing_vocals_path}")
# Analyze backing vocals
analyzer = AudioAnalyzer()
analysis = analyzer.analyze(backing_vocals_path)
logger.info(f"Analysis complete:")
logger.info(f" Has audible content: {analysis.has_audible_content}")
logger.info(f" Total duration: {analysis.total_duration_seconds:.1f}s")
logger.info(f" Audible segments: {len(analysis.audible_segments)}")
logger.info(f" Recommendation: {analysis.recommended_selection.value}")
# Generate waveform
# Note: We're already in track_dir after chdir, so use current directory
logger.info("Generating waveform visualization...")
waveform_generator = WaveformGenerator()
waveform_path = f"{base_name} (Backing Vocals Waveform).png"
waveform_generator.generate(
audio_path=backing_vocals_path,
output_path=waveform_path,
segments=analysis.audible_segments,
)
# Start the review server
# Note: We're already in track_dir after chdir, so output_dir is "."
logger.info("Starting instrumental review UI...")
server = InstrumentalReviewServer(
output_dir=".",
base_name=base_name,
analysis=analysis,
waveform_path=waveform_path,
backing_vocals_path=backing_vocals_path,
clean_instrumental_path=clean_instrumental_path,
with_backing_path=with_backing_path,
)
# Start server and open browser, wait for selection
server.start_and_open_browser()
logger.info("Waiting for instrumental selection in browser...")
logger.info("(Close the browser tab or press Ctrl+C to cancel)")
try:
# Wait for user selection (blocking)
server._selection_event.wait()
selection = server.get_selection()
logger.info(f"User selected: {selection}")
# Stop the server
server.stop()
# Return the selected instrumental path
if selection == "clean":
return clean_instrumental_path
elif selection == "with_backing":
return with_backing_path
elif selection == "custom":
custom_path = server.get_custom_instrumental_path()
if custom_path and os.path.exists(custom_path):
return custom_path
else:
logger.warning("Custom instrumental not found, falling back to clean")
return clean_instrumental_path
else:
logger.warning(f"Unknown selection: {selection}, falling back to numeric selection")
return None
except KeyboardInterrupt:
logger.info("Instrumental review cancelled by user")
server.stop()
return None
except Exception as e:
logger.error(f"Error during instrumental review: {e}")
logger.info("Falling back to numeric selection")
return None
async def async_main():
logger = logging.getLogger(__name__)
# Prevent log propagation to root logger to avoid duplicate logs
# when external packages (like lyrics_converter) configure root logger handlers
logger.propagate = False
log_handler = logging.StreamHandler()
log_formatter = logging.Formatter(fmt="%(asctime)s.%(msecs)03d - %(levelname)s - %(module)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
log_handler.setFormatter(log_formatter)
@@ -461,6 +724,61 @@ async def async_main():
logger.info(f"Changing to directory: {track_dir}")
os.chdir(track_dir)
# Select instrumental file - either via web UI or auto-selection
# This ALWAYS produces a selected file - no silent fallback to legacy code
selected_instrumental_file = None
skip_review = getattr(args, 'skip_instrumental_review', False)
if skip_review:
# Auto-select instrumental when review is skipped (non-interactive mode)
logger.info("Instrumental review skipped (--skip_instrumental_review), auto-selecting instrumental file...")
try:
selected_instrumental_file = auto_select_instrumental(
track=track,
track_dir=track_dir,
logger=logger,
)
except FileNotFoundError as e:
logger.error(f"Failed to auto-select instrumental: {e}")
logger.error("Check that audio separation completed successfully.")
sys.exit(1)
return # Explicit return for testing
else:
# Run instrumental review web UI
selected_instrumental_file = run_instrumental_review(
track=track,
logger=logger,
)
# If instrumental review failed/returned None, show error and exit
# NO SILENT FALLBACK - we want to know if the new flow has issues
if selected_instrumental_file is None:
logger.error("")
logger.error("=" * 70)
logger.error("INSTRUMENTAL SELECTION FAILED")
logger.error("=" * 70)
logger.error("")
logger.error("The instrumental review UI could not find the required files.")
logger.error("")
logger.error("Common causes:")
logger.error(" - No backing vocals file was found (check stems/ directory)")
logger.error(" - No clean instrumental was found (audio separation may have failed)")
logger.error(" - Path resolution failed after directory change")
logger.error("")
logger.error("To investigate:")
logger.error(" - Check the stems/ directory for: *Backing Vocals*.flac and *Instrumental*.flac")
logger.error(" - Look for separation errors earlier in the log")
logger.error(" - Verify audio separation completed without errors")
logger.error("")
logger.error("Workarounds:")
logger.error(" - Re-run with --skip_instrumental_review to auto-select an instrumental")
logger.error(" - Re-run the full pipeline to regenerate stems")
logger.error("")
sys.exit(1)
return # Explicit return for testing
logger.info(f"Selected instrumental file: {selected_instrumental_file}")
# Load CDG styles if CDG generation is enabled
cdg_styles = None
if args.enable_cdg:
@@ -504,6 +822,7 @@ async def async_main():
cdg_styles=cdg_styles,
keep_brand_code=getattr(args, 'keep_brand_code', False),
non_interactive=args.yes,
selected_instrumental_file=selected_instrumental_file,
)
try:
+434 -40
View File
@@ -41,6 +41,11 @@ from .cli_args import create_parser, process_style_overrides, is_url, is_file
class JobStatus(str, Enum):
"""Job status values (matching backend)."""
PENDING = "pending"
# Audio search states (Batch 5)
SEARCHING_AUDIO = "searching_audio"
AWAITING_AUDIO_SELECTION = "awaiting_audio_selection"
DOWNLOADING_AUDIO = "downloading_audio"
# Main workflow
DOWNLOADING = "downloading"
SEPARATING_STAGE1 = "separating_stage1"
SEPARATING_STAGE2 = "separating_stage2"
@@ -763,7 +768,18 @@ class RemoteKaraokeClient:
error_detail = response.text
raise RuntimeError(f"Error getting instrumental options: {error_detail}")
return response.json()
def get_instrumental_analysis(self, job_id: str) -> Dict[str, Any]:
"""Get instrumental analysis data including backing vocals detection."""
response = self._request('GET', f'/api/jobs/{job_id}/instrumental-analysis')
if response.status_code != 200:
try:
error_detail = response.json()
except Exception:
error_detail = response.text
raise RuntimeError(f"Error getting instrumental analysis: {error_detail}")
return response.json()
def select_instrumental(self, job_id: str, selection: str) -> Dict[str, Any]:
"""Submit instrumental selection."""
response = self._request(
@@ -875,6 +891,122 @@ class RemoteKaraokeClient:
error_detail = response.text
raise RuntimeError(f"Error completing review: {error_detail}")
return response.json()
def search_audio(
self,
artist: str,
title: str,
auto_download: bool = False,
style_params_path: Optional[str] = None,
enable_cdg: bool = True,
enable_txt: bool = True,
brand_prefix: Optional[str] = None,
discord_webhook_url: Optional[str] = None,
youtube_description: Optional[str] = None,
enable_youtube_upload: bool = False,
dropbox_path: Optional[str] = None,
gdrive_folder_id: Optional[str] = None,
lyrics_artist: Optional[str] = None,
lyrics_title: Optional[str] = None,
subtitle_offset_ms: int = 0,
clean_instrumental_model: Optional[str] = None,
backing_vocals_models: Optional[list] = None,
other_stems_models: Optional[list] = None,
) -> Dict[str, Any]:
"""
Search for audio by artist and title (Batch 5 - Flacfetch integration).
This creates a job and searches for audio sources. If auto_download is True,
it automatically selects the best source. Otherwise, it returns search results
for user selection.
Args:
artist: Artist name to search for
title: Song title to search for
auto_download: Automatically select best audio source (skip interactive selection)
... other args same as submit_job()
Returns:
Dict with job_id, status, and optionally search results
"""
self.logger.info(f"Searching for audio: {artist} - {title}")
request_data = {
'artist': artist,
'title': title,
'auto_download': auto_download,
'enable_cdg': enable_cdg,
'enable_txt': enable_txt,
}
if brand_prefix:
request_data['brand_prefix'] = brand_prefix
if discord_webhook_url:
request_data['discord_webhook_url'] = discord_webhook_url
if youtube_description:
request_data['youtube_description'] = youtube_description
if enable_youtube_upload:
request_data['enable_youtube_upload'] = enable_youtube_upload
if dropbox_path:
request_data['dropbox_path'] = dropbox_path
if gdrive_folder_id:
request_data['gdrive_folder_id'] = gdrive_folder_id
if lyrics_artist:
request_data['lyrics_artist'] = lyrics_artist
if lyrics_title:
request_data['lyrics_title'] = lyrics_title
if subtitle_offset_ms != 0:
request_data['subtitle_offset_ms'] = subtitle_offset_ms
if clean_instrumental_model:
request_data['clean_instrumental_model'] = clean_instrumental_model
if backing_vocals_models:
request_data['backing_vocals_models'] = backing_vocals_models
if other_stems_models:
request_data['other_stems_models'] = other_stems_models
response = self._request('POST', '/api/audio-search/search', json=request_data)
if response.status_code == 404:
try:
error_detail = response.json()
except Exception:
error_detail = response.text
raise ValueError(f"No audio sources found: {error_detail}")
if response.status_code != 200:
try:
error_detail = response.json()
except Exception:
error_detail = response.text
raise RuntimeError(f"Error searching for audio: {error_detail}")
return response.json()
def get_audio_search_results(self, job_id: str) -> Dict[str, Any]:
"""Get audio search results for a job awaiting selection."""
response = self._request('GET', f'/api/audio-search/{job_id}/results')
if response.status_code != 200:
try:
error_detail = response.json()
except Exception:
error_detail = response.text
raise RuntimeError(f"Error getting search results: {error_detail}")
return response.json()
def select_audio_source(self, job_id: str, selection_index: int) -> Dict[str, Any]:
"""Select an audio source and start processing."""
response = self._request(
'POST',
f'/api/audio-search/{job_id}/select',
json={'selection_index': selection_index}
)
if response.status_code != 200:
try:
error_detail = response.json()
except Exception:
error_detail = response.text
raise RuntimeError(f"Error selecting audio: {error_detail}")
return response.json()
class JobMonitor:
@@ -886,6 +1018,7 @@ class JobMonitor:
self.logger = logger
self._review_opened = False
self._instrumental_prompted = False
self._audio_selection_prompted = False # Batch 5: audio source selection
self._last_timeline_index = 0
self._last_log_index = 0
self._show_worker_logs = True # Enable worker log display
@@ -895,6 +1028,11 @@ class JobMonitor:
# Status descriptions for user-friendly logging
STATUS_DESCRIPTIONS = {
'pending': 'Job queued, waiting to start',
# Audio search states (Batch 5)
'searching_audio': 'Searching for audio sources',
'awaiting_audio_selection': 'Waiting for audio source selection',
'downloading_audio': 'Downloading selected audio',
# Main workflow
'downloading': 'Downloading and preparing input files',
'separating_stage1': 'AI audio separation (stage 1 of 2)',
'separating_stage2': 'AI audio separation (stage 2 of 2)',
@@ -1009,39 +1147,97 @@ class JobMonitor:
time.sleep(self.config.poll_interval)
def handle_instrumental_selection(self, job_id: str) -> None:
"""Handle instrumental selection interaction."""
"""Handle instrumental selection interaction with analysis-based recommendations."""
self.logger.info("=" * 60)
self.logger.info("INSTRUMENTAL SELECTION NEEDED")
self.logger.info("=" * 60)
# In non-interactive mode, auto-select clean instrumental
if self.config.non_interactive:
self.logger.info("Non-interactive mode: Auto-selecting clean instrumental")
selection = 'clean'
else:
self.logger.info("")
self.logger.info("Choose which instrumental track to use for the final video:")
self.logger.info("")
self.logger.info(" 1) Clean Instrumental (no backing vocals)")
self.logger.info(" Best for songs where you want ONLY the lead vocal removed")
self.logger.info("")
self.logger.info(" 2) Instrumental with Backing Vocals")
self.logger.info(" Best for songs where backing vocals add to the karaoke experience")
self.logger.info("")
# Try to get analysis data for smart recommendations
analysis_data = None
try:
analysis_data = self.client.get_instrumental_analysis(job_id)
analysis = analysis_data.get('analysis', {})
selection = ""
while not selection:
# Display analysis summary
self.logger.info("")
self.logger.info("=== Backing Vocals Analysis ===")
if analysis.get('has_audible_content'):
self.logger.info(f" Backing vocals detected: YES")
self.logger.info(f" Audible segments: {len(analysis.get('audible_segments', []))}")
self.logger.info(f" Audible duration: {analysis.get('total_audible_duration_seconds', 0):.1f}s "
f"({analysis.get('audible_percentage', 0):.1f}% of track)")
else:
self.logger.info(f" Backing vocals detected: NO")
self.logger.info(f" Recommendation: {analysis.get('recommended_selection', 'review_needed')}")
self.logger.info("")
except Exception as e:
self.logger.warning(f"Could not fetch analysis data: {e}")
self.logger.info("Falling back to manual selection...")
# In non-interactive mode, use analysis recommendation or default to clean
if self.config.non_interactive:
if analysis_data and analysis_data.get('analysis', {}).get('recommended_selection') == 'clean':
self.logger.info("Non-interactive mode: Auto-selecting clean instrumental (recommended)")
selection = 'clean'
else:
self.logger.info("Non-interactive mode: Auto-selecting clean instrumental (default)")
selection = 'clean'
else:
# Check if we should recommend clean based on analysis
recommend_clean = (
analysis_data and
not analysis_data.get('analysis', {}).get('has_audible_content', True)
)
if recommend_clean:
self.logger.info("No backing vocals detected - recommending clean instrumental.")
self.logger.info("")
self.logger.info("Options:")
self.logger.info(" 1) Accept recommendation (clean instrumental)")
self.logger.info(" 2) Open browser to review and select")
self.logger.info("")
try:
choice = input("Enter your choice (1 or 2): ").strip()
if choice == '1':
selection = 'clean'
elif choice == '2':
selection = 'with_backing'
else:
self.logger.error("Invalid choice. Please enter 1 or 2.")
self._open_instrumental_review_and_wait(job_id)
return # Selection will be submitted via browser
except KeyboardInterrupt:
print()
raise
else:
# Backing vocals detected or analysis unavailable - offer browser review
self.logger.info("Choose how to select your instrumental:")
self.logger.info("")
self.logger.info(" 1) Clean Instrumental (no backing vocals)")
self.logger.info(" Best for songs where you want ONLY the lead vocal removed")
self.logger.info("")
self.logger.info(" 2) Instrumental with Backing Vocals")
self.logger.info(" Best for songs where backing vocals add to the karaoke experience")
self.logger.info("")
self.logger.info(" 3) Open Browser for Advanced Review")
self.logger.info(" Listen to audio, view waveform, and optionally mute sections")
self.logger.info(" to create a custom instrumental")
self.logger.info("")
selection = ""
while not selection:
try:
choice = input("Enter your choice (1, 2, or 3): ").strip()
if choice == '1':
selection = 'clean'
elif choice == '2':
selection = 'with_backing'
elif choice == '3':
self._open_instrumental_review_and_wait(job_id)
return # Selection will be submitted via browser
else:
self.logger.error("Invalid choice. Please enter 1, 2, or 3.")
except KeyboardInterrupt:
print()
raise
self.logger.info(f"Submitting selection: {selection}")
@@ -1054,6 +1250,126 @@ class JobMonitor:
except Exception as e:
self.logger.error(f"Error submitting selection: {e}")
def handle_audio_selection(self, job_id: str) -> None:
"""Handle audio source selection interaction (Batch 5)."""
self.logger.info("=" * 60)
self.logger.info("AUDIO SOURCE SELECTION NEEDED")
self.logger.info("=" * 60)
try:
# Get search results
results_data = self.client.get_audio_search_results(job_id)
results = results_data.get('results', [])
if not results:
self.logger.error("No search results available")
return
# In non-interactive mode, auto-select first result
if self.config.non_interactive:
self.logger.info("Non-interactive mode: Auto-selecting first result")
selection_index = 0
else:
self.logger.info("")
self.logger.info("Choose which audio source to download:")
self.logger.info("")
for result in results:
index = result.get('index', 0)
provider = result.get('provider', 'Unknown')
artist = result.get('artist', 'Unknown')
title = result.get('title', 'Unknown')
quality = result.get('quality', '')
duration = result.get('duration')
# Format duration if available
duration_str = ""
if duration:
minutes = duration // 60
seconds = duration % 60
duration_str = f" [{minutes}:{seconds:02d}]"
quality_str = f" ({quality})" if quality else ""
self.logger.info(f" {index + 1}) [{provider}] {artist} - {title}{quality_str}{duration_str}")
self.logger.info("")
selection_index = -1
while selection_index < 0:
try:
choice = input(f"Enter your choice (1-{len(results)}): ").strip()
choice_num = int(choice)
if 1 <= choice_num <= len(results):
selection_index = choice_num - 1
else:
self.logger.error(f"Please enter a number between 1 and {len(results)}")
except ValueError:
self.logger.error("Please enter a valid number")
except KeyboardInterrupt:
print()
raise
selected = results[selection_index]
self.logger.info(f"Selected: [{selected.get('provider')}] {selected.get('artist')} - {selected.get('title')}")
self.logger.info("")
# Submit selection
result = self.client.select_audio_source(job_id, selection_index)
if result.get('status') == 'success':
self.logger.info(f"Selection submitted successfully")
else:
self.logger.error(f"Error submitting selection: {result}")
except Exception as e:
self.logger.error(f"Error handling audio selection: {e}")
def _open_instrumental_review_and_wait(self, job_id: str) -> None:
"""Open browser to instrumental review UI and wait for selection."""
review_url = f"{self.config.review_ui_url}/jobs/{job_id}/instrumental-review"
self.logger.info("")
self.logger.info("=" * 60)
self.logger.info("OPENING BROWSER FOR INSTRUMENTAL REVIEW")
self.logger.info("=" * 60)
self.logger.info(f"Review URL: {review_url}")
self.logger.info("")
self.logger.info("In the browser you can:")
self.logger.info(" - View the backing vocals waveform")
self.logger.info(" - Listen to clean instrumental, backing vocals, or combined")
self.logger.info(" - Select regions to mute and create a custom instrumental")
self.logger.info(" - Submit your final selection")
self.logger.info("")
self.logger.info("Waiting for selection to be submitted...")
self.logger.info("(Press Ctrl+C to cancel)")
self.logger.info("")
# Open browser
webbrowser.open(review_url)
# Poll until job status changes from awaiting_instrumental_selection
while True:
try:
job_data = self.client.get_job(job_id)
current_status = job_data.get('status')
if current_status != 'awaiting_instrumental_selection':
selection = job_data.get('state_data', {}).get('instrumental_selection', 'unknown')
self.logger.info(f"Selection received: {selection}")
self.logger.info(f"Job status: {current_status}")
return
time.sleep(self.config.poll_interval)
except KeyboardInterrupt:
print()
self.logger.info("Cancelled. You can resume this job later with --resume")
raise
except Exception as e:
self.logger.warning(f"Error checking status: {e}")
time.sleep(self.config.poll_interval)
def download_outputs(self, job_id: str, job_data: Dict[str, Any]) -> None:
"""
Download all output files for a completed job.
@@ -1461,7 +1777,14 @@ class JobMonitor:
self._polls_without_updates = 0
# Handle human interaction points
if status in ['awaiting_review', 'in_review']:
if status == 'awaiting_audio_selection':
if not self._audio_selection_prompted:
self.logger.info("")
self.handle_audio_selection(job_id)
self._audio_selection_prompted = True
self._last_timeline_index = 0 # Reset to catch any events
elif status in ['awaiting_review', 'in_review']:
if not self._review_opened:
self.logger.info("")
self.handle_review(job_id)
@@ -1556,6 +1879,9 @@ def main():
"""Main entry point for the remote CLI."""
# Set up logging - same format as gen_cli.py
logger = logging.getLogger(__name__)
# Prevent log propagation to root logger to avoid duplicate logs
# when external packages (like lyrics_converter) configure root logger handlers
logger.propagate = False
log_handler = logging.StreamHandler()
log_formatter = logging.Formatter(
fmt="%(asctime)s.%(msecs)03d - %(levelname)s - %(module)s - %(message)s",
@@ -1899,8 +2225,7 @@ def main():
ignored_features.append("--lyrics-only")
if args.background_video:
ignored_features.append("--background_video")
if getattr(args, 'auto_download', False):
ignored_features.append("--auto-download (audio search not yet supported)")
# --auto-download is now supported (Batch 5)
# These are now supported but server-side handling may be partial
if args.organised_dir:
ignored_features.append("--organised_dir (local-only)")
@@ -1921,6 +2246,7 @@ def main():
# Handle new job submission - parse input arguments same as gen_cli
input_media, artist, title, filename_pattern = None, None, None, None
use_audio_search = False # Batch 5: audio search mode
is_url_input = False
if not args.args:
@@ -1929,7 +2255,7 @@ def main():
# Allow 3 forms of positional arguments:
# 1. URL or Media File only
# 2. Artist and Title only
# 2. Artist and Title only (audio search mode - Batch 5)
# 3. URL/File, Artist, and Title
if args.args and (is_url(args.args[0]) or is_file(args.args[0])):
input_media = args.args[0]
@@ -1950,35 +2276,103 @@ def main():
logger.error("Folder processing is not yet supported in remote mode")
return 1
elif len(args.args) > 1:
# Audio search mode: artist + title without file (Batch 5)
artist = args.args[0]
title = args.args[1]
logger.error("Audio search (artist+title) is not yet supported in remote mode.")
logger.error("Please provide a local audio file path or YouTube URL instead.")
logger.error("")
logger.error("For local flacfetch search, use karaoke-gen instead:")
logger.error(f" karaoke-gen \"{artist}\" \"{title}\"")
return 1
use_audio_search = True
else:
parser.print_help()
return 1
# Validate input
if not input_media:
logger.error("No input media or URL provided")
# Validate artist and title are provided
if not artist or not title:
logger.error("Artist and Title are required")
parser.print_help()
return 1
# For file input, validate file exists and artist/title are provided
if not is_url_input:
if not os.path.isfile(input_media):
# For file/URL input modes, validate input exists
if not use_audio_search:
if not input_media:
logger.error("No input media or URL provided")
return 1
# For file input (not URL), validate file exists
if not is_url_input and not os.path.isfile(input_media):
logger.error(f"File not found: {input_media}")
logger.error("Please provide a valid path to an audio file (mp3, wav, flac, m4a, ogg, aac)")
return 1
# Handle audio search mode (Batch 5)
if use_audio_search:
logger.info("=" * 60)
logger.info("Karaoke Generator (Remote) - Audio Search Mode")
logger.info("=" * 60)
logger.info(f"Searching for: {artist} - {title}")
if getattr(args, 'auto_download', False) or config.non_interactive:
logger.info(f"Auto-download: enabled (will auto-select best source)")
if args.style_params_json:
logger.info(f"Style: {args.style_params_json}")
logger.info(f"CDG: {args.enable_cdg}, TXT: {args.enable_txt}")
if args.brand_prefix:
logger.info(f"Brand: {args.brand_prefix}")
logger.info(f"Service URL: {config.service_url}")
logger.info("")
if not artist or not title:
logger.error("Artist and Title are required for file uploads")
parser.print_help()
# Read youtube description from file if provided
youtube_description = None
if args.youtube_description_file and os.path.isfile(args.youtube_description_file):
try:
with open(args.youtube_description_file, 'r') as f:
youtube_description = f.read()
logger.info(f"Loaded YouTube description from: {args.youtube_description_file}")
except Exception as e:
logger.warning(f"Failed to read YouTube description file: {e}")
try:
# Determine auto_download mode
auto_download = getattr(args, 'auto_download', False) or config.non_interactive
result = client.search_audio(
artist=artist,
title=title,
auto_download=auto_download,
enable_cdg=args.enable_cdg,
enable_txt=args.enable_txt,
brand_prefix=args.brand_prefix,
discord_webhook_url=args.discord_webhook_url,
youtube_description=youtube_description,
enable_youtube_upload=getattr(args, 'enable_youtube_upload', False),
dropbox_path=getattr(args, 'dropbox_path', None),
gdrive_folder_id=getattr(args, 'gdrive_folder_id', None),
lyrics_artist=getattr(args, 'lyrics_artist', None),
lyrics_title=getattr(args, 'lyrics_title', None),
subtitle_offset_ms=getattr(args, 'subtitle_offset_ms', 0) or 0,
clean_instrumental_model=getattr(args, 'clean_instrumental_model', None),
backing_vocals_models=getattr(args, 'backing_vocals_models', None),
other_stems_models=getattr(args, 'other_stems_models', None),
)
job_id = result.get('job_id')
results_count = result.get('results_count', 0)
server_version = result.get('server_version', 'unknown')
logger.info(f"Job created: {job_id}")
logger.info(f"Server version: {server_version}")
logger.info(f"Audio sources found: {results_count}")
logger.info("")
# Monitor job
return monitor.monitor(job_id)
except ValueError as e:
logger.error(str(e))
return 1
except Exception as e:
logger.error(f"Error: {e}")
logger.exception("Full error details:")
return 1
# File upload mode (original flow)
logger.info("=" * 60)
logger.info("Karaoke Generator (Remote) - Job Submission")
logger.info("=" * 60)
@@ -1,4 +1,4 @@
import { Box, Button, Typography, useMediaQuery, useTheme, Switch, FormControlLabel, Tooltip, Paper, IconButton } from '@mui/material'
import { Box, Button, Typography, useMediaQuery, useTheme, Switch, FormControlLabel, Tooltip, Paper, IconButton, Chip } from '@mui/material'
import LockIcon from '@mui/icons-material/Lock'
import UploadFileIcon from '@mui/icons-material/UploadFile'
import FindReplaceIcon from '@mui/icons-material/FindReplace'
@@ -7,6 +7,7 @@ import UndoIcon from '@mui/icons-material/Undo'
import RedoIcon from '@mui/icons-material/Redo'
import TimerIcon from '@mui/icons-material/Timer'
import RestoreIcon from '@mui/icons-material/Restore'
import RateReviewIcon from '@mui/icons-material/RateReview'
import { CorrectionData, InteractionMode } from '../types'
import CorrectionMetrics from './CorrectionMetrics'
import AgenticCorrectionMetrics from './AgenticCorrectionMetrics'
@@ -41,6 +42,8 @@ interface HeaderProps {
onRedo: () => void
canUndo: boolean
canRedo: boolean
annotationsEnabled?: boolean
onAnnotationsToggle?: (enabled: boolean) => void
}
export default function Header({
@@ -65,6 +68,8 @@ export default function Header({
onRedo,
canUndo,
canRedo,
annotationsEnabled = true,
onAnnotationsToggle,
}: HeaderProps) {
const theme = useTheme()
const isMobile = useMediaQuery(theme.breakpoints.down('md'))
@@ -135,17 +140,38 @@ export default function Header({
<Typography variant="h4" sx={{ fontSize: isMobile ? '1.3rem' : '1.5rem' }}>
Nomad Karaoke: Lyrics Transcription Review
</Typography>
{isReadOnly && (
<Button
variant="outlined"
size="small"
startIcon={<UploadFileIcon />}
onClick={onFileLoad}
fullWidth={isMobile}
>
Load File
</Button>
)}
<Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
{!isReadOnly && onAnnotationsToggle && (
<Tooltip title={annotationsEnabled
? "Click to disable annotation prompts when editing"
: "Click to enable annotation prompts when editing"
}>
<Chip
icon={<RateReviewIcon />}
label={annotationsEnabled ? "Feedback On" : "Feedback Off"}
onClick={() => onAnnotationsToggle(!annotationsEnabled)}
color={annotationsEnabled ? "primary" : "default"}
variant={annotationsEnabled ? "filled" : "outlined"}
size="small"
sx={{
cursor: 'pointer',
'& .MuiChip-icon': { fontSize: '1rem' }
}}
/>
</Tooltip>
)}
{isReadOnly && (
<Button
variant="outlined"
size="small"
startIcon={<UploadFileIcon />}
onClick={onFileLoad}
fullWidth={isMobile}
>
Load File
</Button>
)}
</Box>
</Box>
<Box sx={{
@@ -200,6 +200,8 @@ interface MemoizedHeaderProps {
canUndo: boolean
canRedo: boolean
onUnCorrectAll: () => void
annotationsEnabled: boolean
onAnnotationsToggle: (enabled: boolean) => void
}
// Create a memoized Header component
@@ -224,7 +226,9 @@ const MemoizedHeader = memo(function MemoizedHeader({
onRedo,
canUndo,
canRedo,
onUnCorrectAll
onUnCorrectAll,
annotationsEnabled,
onAnnotationsToggle
}: MemoizedHeaderProps) {
return (
<Header
@@ -249,6 +253,8 @@ const MemoizedHeader = memo(function MemoizedHeader({
canUndo={canUndo}
canRedo={canRedo}
onUnCorrectAll={onUnCorrectAll}
annotationsEnabled={annotationsEnabled}
onAnnotationsToggle={onAnnotationsToggle}
/>
);
});
@@ -295,13 +301,18 @@ export default function LyricsAnalyzer({ data: initialData, onFileLoad, apiClien
wordIdsAffected: string[]
gapId?: string
} | null>(null)
const [annotationsEnabled] = useState(() => {
const [annotationsEnabled, setAnnotationsEnabled] = useState(() => {
// Check localStorage for user preference
const saved = localStorage.getItem('annotationsEnabled')
return saved !== null ? saved === 'true' : true // Default: enabled
// TODO: Add UI toggle to enable/disable via setAnnotationsEnabled
})
// Persist annotation preference to localStorage
const handleAnnotationsToggle = useCallback((enabled: boolean) => {
setAnnotationsEnabled(enabled)
localStorage.setItem('annotationsEnabled', String(enabled))
}, [])
// Correction detail card state
const [correctionDetailOpen, setCorrectionDetailOpen] = useState(false)
const [selectedCorrection, setSelectedCorrection] = useState<{
@@ -1164,6 +1175,8 @@ export default function LyricsAnalyzer({ data: initialData, onFileLoad, apiClien
canUndo={canUndo}
canRedo={canRedo}
onUnCorrectAll={handleUnCorrectAll}
annotationsEnabled={annotationsEnabled}
onAnnotationsToggle={handleAnnotationsToggle}
/>
<Grid container direction={isMobile ? 'column' : 'row'}>
+2 -1
View File
@@ -1,6 +1,6 @@
[tool.poetry]
name = "karaoke-gen"
version = "0.71.35"
version = "0.71.64"
description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens."
authors = ["Andrew Beveridge <andrew@beveridge.uk>"]
license = "MIT"
@@ -10,6 +10,7 @@ packages = [
{ include = "lyrics_transcriber", from = "lyrics_transcriber_temp" }
]
include = [
"karaoke_gen/instrumental_review/static/*",
"lyrics_transcriber_temp/lyrics_transcriber/frontend/web_assets",
"lyrics_transcriber_temp/lyrics_transcriber/frontend/web_assets/**/*",
"lyrics_transcriber_temp/lyrics_transcriber/output/fonts/*",
+249
View File
@@ -0,0 +1,249 @@
#!/usr/bin/env python3
"""
Helper script to run the Instrumental Review UI from an existing karaoke job folder.
This allows iterating on the frontend without running a full karaoke generation.
Usage:
python scripts/run_instrumental_review.py "path/to/Artist - Title"
# Or with optional port:
python scripts/run_instrumental_review.py "path/to/Artist - Title" --port 8888
"""
import argparse
import glob
import logging
import os
import sys
# Add parent directory to path for imports
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from karaoke_gen.instrumental_review import (
AudioAnalyzer,
InstrumentalReviewServer,
WaveformGenerator,
)
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
)
logger = logging.getLogger(__name__)
def find_file(directory: str, patterns: list[str]) -> str | None:
"""Find a file matching any of the given patterns."""
for pattern in patterns:
matches = glob.glob(os.path.join(directory, pattern))
if matches:
return matches[0]
return None
def find_audio_files(job_dir: str) -> dict:
"""
Find the required audio files in a karaoke job directory.
Returns dict with paths to:
- backing_vocals: The backing vocals stem (in stems/)
- clean_instrumental: The clean instrumental (no backing vocals) - in job_dir
- with_backing: The instrumental with backing vocals (optional) - in job_dir
- original: The original audio file (optional) - in job_dir
"""
stems_dir = os.path.join(job_dir, "stems")
# Find backing vocals in stems/ directory
backing_vocals = None
if os.path.exists(stems_dir):
backing_vocals = find_file(stems_dir, [
"*Backing Vocals*.flac",
"*Backing Vocals*.mp3",
"*Backing Vocals*.wav",
"*backing_vocals*.flac",
"*backing_vocals*.mp3",
])
# Also check main directory for backing vocals
if not backing_vocals:
backing_vocals = find_file(job_dir, [
"*Backing Vocals*.flac",
"*Backing Vocals*.mp3",
"*Backing Vocals*.wav",
])
if not backing_vocals:
raise FileNotFoundError(f"No backing vocals file found in {job_dir}")
# Find original audio file - look for "(Original)" in name
original = find_file(job_dir, [
"*(Original)*.flac",
"*(Original)*.mp3",
"*(Original)*.wav",
])
# Find instrumentals in main job directory
# Look for "(Instrumental ...)" files - clean ones don't have "+BV" or "Backing"
all_instrumentals = glob.glob(os.path.join(job_dir, "*Instrumental*.flac"))
all_instrumentals += glob.glob(os.path.join(job_dir, "*Instrumental*.mp3"))
# Also check stems/ directory
if os.path.exists(stems_dir):
all_instrumentals += glob.glob(os.path.join(stems_dir, "*Instrumental*.flac"))
all_instrumentals += glob.glob(os.path.join(stems_dir, "*Instrumental*.mp3"))
# Filter: files with "+BV" or "Backing" are combined, others are clean
clean_instrumental = None
with_backing = None
for inst in all_instrumentals:
basename = os.path.basename(inst)
if "+BV" in basename or "Backing" in basename or "backing" in basename:
with_backing = inst
elif "Custom" not in basename: # Skip custom instrumentals from previous runs
clean_instrumental = inst
if not clean_instrumental:
raise FileNotFoundError(f"No clean instrumental file found in {job_dir}")
return {
"backing_vocals": backing_vocals,
"clean_instrumental": clean_instrumental,
"with_backing": with_backing,
"original": original,
}
def main():
parser = argparse.ArgumentParser(
description="Run the Instrumental Review UI from an existing karaoke job folder",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
Examples:
python scripts/run_instrumental_review.py "Sabrina Carpenter - Please, Please, Please"
python scripts/run_instrumental_review.py "./output/Artist - Song" --port 9000
""",
)
parser.add_argument(
"job_dir",
help="Path to the karaoke job directory (containing stems/ folder)",
)
parser.add_argument(
"--port",
type=int,
default=8765,
help="Port to run the server on (default: 8765)",
)
parser.add_argument(
"--no-browser",
action="store_true",
help="Don't automatically open browser",
)
args = parser.parse_args()
job_dir = os.path.abspath(args.job_dir)
if not os.path.exists(job_dir):
logger.error(f"Directory not found: {job_dir}")
sys.exit(1)
# Extract base name from directory name
base_name = os.path.basename(job_dir)
logger.info(f"Job directory: {job_dir}")
logger.info(f"Base name: {base_name}")
# Find audio files
try:
files = find_audio_files(job_dir)
except FileNotFoundError as e:
logger.error(str(e))
sys.exit(1)
logger.info(f"Found backing vocals: {os.path.basename(files['backing_vocals'])}")
logger.info(f"Found clean instrumental: {os.path.basename(files['clean_instrumental'])}")
if files["with_backing"]:
logger.info(f"Found with backing: {os.path.basename(files['with_backing'])}")
else:
logger.info("No combined instrumental found (optional)")
if files["original"]:
logger.info(f"Found original: {os.path.basename(files['original'])}")
else:
logger.info("No original audio found (optional)")
# Analyze backing vocals
logger.info("Analyzing backing vocals...")
analyzer = AudioAnalyzer()
analysis = analyzer.analyze(files["backing_vocals"])
logger.info(f" Has audible content: {analysis.has_audible_content}")
logger.info(f" Total duration: {analysis.total_duration_seconds:.1f}s")
logger.info(f" Audible segments: {len(analysis.audible_segments)}")
logger.info(f" Audible percentage: {analysis.audible_percentage:.1f}%")
logger.info(f" Recommendation: {analysis.recommended_selection.value}")
# Generate or find waveform
waveform_path = os.path.join(job_dir, f"{base_name} (Backing Vocals Waveform).png")
if os.path.exists(waveform_path):
logger.info(f"Using existing waveform: {os.path.basename(waveform_path)}")
else:
logger.info("Generating waveform visualization...")
waveform_generator = WaveformGenerator()
waveform_generator.generate(
audio_path=files["backing_vocals"],
output_path=waveform_path,
segments=analysis.audible_segments,
)
logger.info(f"Generated waveform: {os.path.basename(waveform_path)}")
# Create and start server
logger.info(f"Starting instrumental review server on port {args.port}...")
server = InstrumentalReviewServer(
output_dir=job_dir,
base_name=base_name,
analysis=analysis,
waveform_path=waveform_path,
backing_vocals_path=files["backing_vocals"],
clean_instrumental_path=files["clean_instrumental"],
with_backing_path=files["with_backing"],
original_audio_path=files["original"],
)
url = f"http://localhost:{args.port}/"
logger.info(f"Server URL: {url}")
if args.no_browser:
logger.info("Browser auto-open disabled. Open the URL manually.")
# Start server without opening browser
import uvicorn
app = server._create_app()
uvicorn.run(app, host="127.0.0.1", port=args.port, log_level="warning")
else:
logger.info("Opening browser...")
logger.info("Press Ctrl+C to stop the server")
try:
selection = server.start_and_open_browser(port=args.port)
logger.info(f"Selection: {selection}")
if selection == "custom":
custom_path = server.get_custom_instrumental_path()
if custom_path:
logger.info(f"Custom instrumental saved to: {custom_path}")
if selection == "uploaded":
uploaded_path = server.get_uploaded_instrumental_path()
if uploaded_path:
logger.info(f"Uploaded instrumental saved to: {uploaded_path}")
except KeyboardInterrupt:
logger.info("\nServer stopped")
server.stop()
if __name__ == "__main__":
main()
+183
View File
@@ -0,0 +1,183 @@
#!/usr/bin/env python
"""
Test script for the Instrumental Review UI.
Usage:
python scripts/test-instrumental-review.py <backing_vocals_path> <clean_instrumental_path> [with_backing_path]
Example:
python scripts/test-instrumental-review.py \
"/path/to/Artist - Song (Backing Vocals).flac" \
"/path/to/Artist - Song (Instrumental).flac"
This will:
1. Analyze the backing vocals file
2. Generate a waveform visualization
3. Start a local web server
4. Open your browser to the review UI
"""
import argparse
import logging
import os
import sys
import tempfile
# Add the project root to the path
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from karaoke_gen.instrumental_review import (
AudioAnalyzer,
WaveformGenerator,
InstrumentalReviewServer,
)
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger(__name__)
def main():
parser = argparse.ArgumentParser(
description="Test the Instrumental Review UI locally"
)
parser.add_argument(
"backing_vocals",
help="Path to backing vocals audio file (e.g., 'Artist - Song (Backing Vocals).flac')"
)
parser.add_argument(
"clean_instrumental",
help="Path to clean instrumental audio file (e.g., 'Artist - Song (Instrumental).flac')"
)
parser.add_argument(
"with_backing",
nargs="?",
default=None,
help="Optional: Path to instrumental with backing vocals file"
)
parser.add_argument(
"--port",
type=int,
default=8765,
help="Port to run the server on (default: 8765)"
)
parser.add_argument(
"--threshold",
type=float,
default=-40.0,
help="Silence threshold in dB (default: -40.0)"
)
args = parser.parse_args()
# Validate files exist
if not os.path.exists(args.backing_vocals):
logger.error(f"Backing vocals file not found: {args.backing_vocals}")
sys.exit(1)
if not os.path.exists(args.clean_instrumental):
logger.error(f"Clean instrumental file not found: {args.clean_instrumental}")
sys.exit(1)
if args.with_backing and not os.path.exists(args.with_backing):
logger.error(f"With backing file not found: {args.with_backing}")
sys.exit(1)
# Extract base name from backing vocals file
base_name = os.path.basename(args.backing_vocals)
# Remove common suffixes
for suffix in [" (Backing Vocals)", "(Backing Vocals)", "_backing_vocals", "-backing"]:
if suffix in base_name:
base_name = base_name.replace(suffix, "")
break
# Remove extension
base_name = os.path.splitext(base_name)[0]
output_dir = os.path.dirname(args.backing_vocals) or "."
logger.info("=" * 60)
logger.info("INSTRUMENTAL REVIEW UI TEST")
logger.info("=" * 60)
logger.info(f"Backing vocals: {args.backing_vocals}")
logger.info(f"Clean instrumental: {args.clean_instrumental}")
if args.with_backing:
logger.info(f"With backing: {args.with_backing}")
logger.info(f"Base name: {base_name}")
logger.info(f"Output dir: {output_dir}")
logger.info("")
# Step 1: Analyze backing vocals
logger.info("[1/3] Analyzing backing vocals...")
analyzer = AudioAnalyzer(silence_threshold_db=args.threshold)
analysis = analyzer.analyze(args.backing_vocals)
logger.info(f" Has audible content: {analysis.has_audible_content}")
logger.info(f" Total duration: {analysis.total_duration_seconds:.1f}s")
logger.info(f" Audible segments: {len(analysis.audible_segments)}")
logger.info(f" Audible duration: {analysis.total_audible_duration_seconds:.1f}s ({analysis.audible_percentage:.1f}%)")
logger.info(f" Recommendation: {analysis.recommended_selection.value}")
if analysis.audible_segments:
logger.info(" Segments:")
for i, seg in enumerate(analysis.audible_segments[:5]):
logger.info(
f" [{i+1}] {seg.start_seconds:.1f}s - {seg.end_seconds:.1f}s "
f"({seg.duration_seconds:.1f}s, avg: {seg.avg_amplitude_db:.1f}dB)"
)
if len(analysis.audible_segments) > 5:
logger.info(f" ... and {len(analysis.audible_segments) - 5} more")
logger.info("")
# Step 2: Generate waveform
logger.info("[2/3] Generating waveform visualization...")
waveform_path = os.path.join(output_dir, f"{base_name}_waveform.png")
generator = WaveformGenerator()
generator.generate(
audio_path=args.backing_vocals,
output_path=waveform_path,
segments=analysis.audible_segments,
)
logger.info(f" Waveform saved to: {waveform_path}")
logger.info("")
# Step 3: Start review server
logger.info("[3/3] Starting review server...")
logger.info(f" URL: http://localhost:{args.port}/")
logger.info("")
logger.info("=" * 60)
logger.info("REVIEW UI READY")
logger.info("=" * 60)
logger.info("")
logger.info("The review UI should open in your browser.")
logger.info("Select your instrumental choice and click 'Submit'.")
logger.info("Press Ctrl+C to stop the server.")
logger.info("")
server = InstrumentalReviewServer(
output_dir=output_dir,
base_name=base_name,
analysis=analysis,
waveform_path=waveform_path,
backing_vocals_path=args.backing_vocals,
clean_instrumental_path=args.clean_instrumental,
with_backing_path=args.with_backing,
)
try:
selection = server.start_and_open_browser(port=args.port)
logger.info("")
logger.info("=" * 60)
logger.info(f"SELECTION: {selection}")
logger.info("=" * 60)
custom_path = server.get_custom_instrumental_path()
if custom_path:
logger.info(f"Custom instrumental created: {custom_path}")
except KeyboardInterrupt:
logger.info("\nServer stopped by user.")
server.stop()
if __name__ == "__main__":
main()
+9 -2
View File
@@ -759,14 +759,20 @@ async def test_full_cli_integration(tmp_path, mocker):
print(f"MOCK process_audio_separation: Creating dummy separated files for {artist_title}")
# Create dummy instrumental files (using a generic model name)
instrumental_file = os.path.join(track_output_dir, f"{artist_title} (Instrumental model_bs_roformer_ep_317_sdr_12.9755.ckpt).flac")
model_name = "model_bs_roformer_ep_317_sdr_12.9755.ckpt"
instrumental_file = os.path.join(track_output_dir, f"{artist_title} (Instrumental {model_name}).flac")
with open(instrumental_file, "w") as f:
f.write("dummy instrumental audio content")
# Return data in the format expected by auto_select_instrumental
return {
"instrumental_path": instrumental_file,
"vocals_path": None, # Not needed for this test
# clean_instrumental is what auto_select_instrumental looks for
"clean_instrumental": {
"instrumental": instrumental_file
},
}
mocker.patch('karaoke_gen.audio_processor.AudioProcessor.process_audio_separation',
@@ -1093,7 +1099,8 @@ async def test_full_cli_integration(tmp_path, mocker):
'--enable_cdg', # Named: enable CDG creation
'--enable_txt', # Named: enable TXT creation
'-y', # Named: auto-confirm (bypass user confirmation)
'--log_level', 'DEBUG' # Named: log level
'--log_level', 'DEBUG', # Named: log level
'--skip_instrumental_review', # Named: skip instrumental review UI (use auto-select)
]
# Now run the actual karaoke generation pipeline
+268 -25
View File
@@ -162,16 +162,16 @@ class TestFlacFetchAudioFetcher:
@patch('karaoke_gen.audio_fetcher.FlacFetchAudioFetcher._get_manager')
def test_search_success(self, mock_get_manager, fetcher):
"""Test successful search returns results."""
# Set up mock
# Set up mock using correct flacfetch Release attribute names
mock_manager = MagicMock()
mock_result = MagicMock()
mock_result.title = "Found Song"
mock_result.artist = "Found Artist"
mock_result.url = "https://example.com/song"
mock_result.provider = "YouTube"
mock_result.duration = 200
mock_result.quality = "320kbps"
mock_result.id = "abc123"
mock_result.download_url = "https://example.com/song"
mock_result.source_name = "YouTube"
mock_result.duration_seconds = 200
mock_result.quality = MagicMock(__str__=MagicMock(return_value="320kbps"))
mock_result.info_hash = "abc123"
mock_manager.search.return_value = [mock_result]
mock_get_manager.return_value = mock_manager
@@ -273,14 +273,14 @@ class TestFlacFetchAudioFetcher:
@patch('karaoke_gen.audio_fetcher.FlacFetchAudioFetcher._get_manager')
def test_search_and_download_auto_select(self, mock_get_manager, fetcher, tmp_path):
"""Test search_and_download with auto_select=True uses select_best."""
# Set up mock
# Set up mock using correct flacfetch Release attribute names
mock_manager = MagicMock()
mock_result = MagicMock()
mock_result.title = "Test Song"
mock_result.artist = "Test Artist"
mock_result.provider = "YouTube"
mock_result.duration = 180
mock_result.quality = "FLAC"
mock_result.source_name = "YouTube"
mock_result.duration_seconds = 180
mock_result.quality = MagicMock(__str__=MagicMock(return_value="FLAC 16bit CD"))
mock_manager.search.return_value = [mock_result]
mock_manager.select_best.return_value = mock_result
downloaded_path = str(tmp_path / "song.flac")
@@ -305,14 +305,16 @@ class TestFlacFetchAudioFetcher:
@patch('builtins.input', return_value='1')
def test_search_and_download_interactive_select(self, mock_input, mock_get_manager, fetcher, tmp_path, capsys):
"""Test search_and_download with interactive selection."""
# Set up mock
# Set up mock using correct flacfetch Release attribute names
mock_manager = MagicMock()
mock_result = MagicMock()
mock_result.title = "Test Song"
mock_result.artist = "Test Artist"
mock_result.provider = "YouTube"
mock_result.duration = 180
mock_result.quality = "320kbps"
mock_result.source_name = "YouTube"
mock_result.duration_seconds = 180
mock_result.quality = MagicMock(__str__=MagicMock(return_value="320kbps"))
mock_result.seeders = None
mock_result.target_file = None
mock_manager.search.return_value = [mock_result]
downloaded_path = str(tmp_path / "song.flac")
mock_manager.download.return_value = downloaded_path
@@ -352,12 +354,15 @@ class TestFlacFetchAudioFetcher:
@patch('builtins.input', return_value='0')
def test_interactive_select_cancel(self, mock_input, fetcher):
"""Test interactive selection returns None when user cancels."""
# Use correct flacfetch Release attribute names for fallback display
mock_result = MagicMock()
mock_result.provider = "YouTube"
mock_result.source_name = "YouTube"
mock_result.title = "Test"
mock_result.artist = "Artist"
mock_result.quality = "FLAC"
mock_result.duration = 180
mock_result.quality = MagicMock(__str__=MagicMock(return_value="FLAC 16bit CD"))
mock_result.duration_seconds = 180
mock_result.seeders = None
mock_result.target_file = None
result = fetcher._interactive_select([mock_result], "Artist", "Test")
assert result is None
@@ -366,11 +371,13 @@ class TestFlacFetchAudioFetcher:
def test_interactive_select_invalid_then_valid(self, mock_input, fetcher):
"""Test interactive selection handles invalid input gracefully."""
mock_result = MagicMock()
mock_result.provider = "YouTube"
mock_result.source_name = "YouTube"
mock_result.title = "Test"
mock_result.artist = "Artist"
mock_result.quality = "FLAC"
mock_result.duration = 180
mock_result.quality = MagicMock(__str__=MagicMock(return_value="FLAC 16bit CD"))
mock_result.duration_seconds = 180
mock_result.seeders = None
mock_result.target_file = None
result = fetcher._interactive_select([mock_result], "Artist", "Test")
assert result == mock_result
@@ -379,11 +386,13 @@ class TestFlacFetchAudioFetcher:
def test_interactive_select_out_of_range_then_valid(self, mock_input, fetcher, capsys):
"""Test interactive selection handles out-of-range input."""
mock_result = MagicMock()
mock_result.provider = "YouTube"
mock_result.source_name = "YouTube"
mock_result.title = "Test"
mock_result.artist = "Artist"
mock_result.quality = "FLAC"
mock_result.duration = 180
mock_result.quality = MagicMock(__str__=MagicMock(return_value="FLAC 16bit CD"))
mock_result.duration_seconds = 180
mock_result.seeders = None
mock_result.target_file = None
result = fetcher._interactive_select([mock_result], "Artist", "Test")
assert result == mock_result
@@ -395,11 +404,13 @@ class TestFlacFetchAudioFetcher:
def test_interactive_select_keyboard_interrupt(self, mock_input, fetcher, capsys):
"""Test interactive selection handles keyboard interrupt."""
mock_result = MagicMock()
mock_result.provider = "YouTube"
mock_result.source_name = "YouTube"
mock_result.title = "Test"
mock_result.artist = "Artist"
mock_result.quality = None
mock_result.duration = None
mock_result.duration_seconds = None
mock_result.seeders = None
mock_result.target_file = None
result = fetcher._interactive_select([mock_result], "Artist", "Test")
assert result is None
@@ -448,6 +459,238 @@ class TestFlacFetchManagerInitialization:
assert fetcher._ops_api_key == "ops_key"
class TestGetManagerIntegration:
"""
Integration tests for _get_manager that verify real flacfetch imports and registration.
These tests catch issues like:
- Import errors from renamed classes (e.g., YouTubeProvider vs YoutubeProvider)
- Missing downloader registration
- API changes in flacfetch
"""
def test_get_manager_imports_work(self):
"""Test that _get_manager can import all required flacfetch modules.
This test would have caught the YouTubeProvider -> YoutubeProvider rename.
"""
fetcher = FlacFetchAudioFetcher()
# Actually call _get_manager to verify imports work
manager = fetcher._get_manager()
# Verify manager was created
assert manager is not None
assert fetcher._manager is manager # Should be cached
# Verify calling again returns same instance (lazy init)
manager2 = fetcher._get_manager()
assert manager is manager2
def test_get_manager_registers_youtube_provider_and_downloader(self):
"""Test that YouTube provider AND downloader are registered.
This test would have caught the missing downloader registration.
"""
fetcher = FlacFetchAudioFetcher()
manager = fetcher._get_manager()
# Verify YouTube provider is registered
provider_names = [p.name for p in manager.providers]
assert "YouTube" in provider_names
# Verify YouTube downloader is registered
assert "YouTube" in manager._downloader_map, \
"YouTube downloader must be registered to download from YouTube"
def test_get_manager_registers_redacted_with_api_key(self):
"""Test that Redacted provider and downloader are registered when API key is provided."""
fetcher = FlacFetchAudioFetcher(redacted_api_key="test_key")
manager = fetcher._get_manager()
# Verify Redacted provider is registered
provider_names = [p.name for p in manager.providers]
assert "Redacted" in provider_names
# Verify Redacted downloader is registered (if TorrentDownloader is available)
# Note: TorrentDownloader may not be available in all environments
try:
from flacfetch.downloaders.torrent import TorrentDownloader
assert "Redacted" in manager._downloader_map, \
"Redacted downloader must be registered when TorrentDownloader is available"
except ImportError:
# TorrentDownloader not available, which is okay
pass
def test_get_manager_registers_ops_with_api_key(self):
"""Test that OPS provider and downloader are registered when API key is provided."""
fetcher = FlacFetchAudioFetcher(ops_api_key="test_key")
manager = fetcher._get_manager()
# Verify OPS provider is registered
provider_names = [p.name for p in manager.providers]
assert "OPS" in provider_names
# Verify OPS downloader is registered (if TorrentDownloader is available)
try:
from flacfetch.downloaders.torrent import TorrentDownloader
assert "OPS" in manager._downloader_map, \
"OPS downloader must be registered when TorrentDownloader is available"
except ImportError:
pass
def test_get_manager_with_all_providers(self):
"""Test manager setup with all providers configured."""
fetcher = FlacFetchAudioFetcher(
redacted_api_key="red_key",
ops_api_key="ops_key",
)
manager = fetcher._get_manager()
provider_names = [p.name for p in manager.providers]
# All three providers should be registered
assert "Redacted" in provider_names
assert "OPS" in provider_names
assert "YouTube" in provider_names
# YouTube downloader should always be registered
assert "YouTube" in manager._downloader_map
class TestFlacFetchReleaseModelCompatibility:
"""
Tests to verify our code is compatible with flacfetch's Release model.
These tests use real flacfetch models to catch attribute name mismatches.
"""
def test_release_model_has_expected_attributes(self):
"""Verify flacfetch Release model has the attributes we expect.
This serves as a canary test - if flacfetch changes attribute names,
this test will fail immediately.
"""
from flacfetch.core.models import Release, Quality, AudioFormat, MediaSource
# Create a real Release object
quality = Quality(format=AudioFormat.FLAC, bit_depth=16, media=MediaSource.CD)
release = Release(
title="Test Song",
artist="Test Artist",
quality=quality,
source_name="Redacted",
)
# Verify the attributes we use in audio_fetcher.py exist
assert hasattr(release, 'title')
assert hasattr(release, 'artist')
assert hasattr(release, 'source_name') # NOT 'provider'
assert hasattr(release, 'quality')
assert hasattr(release, 'download_url')
assert hasattr(release, 'duration_seconds') # NOT 'duration'
assert hasattr(release, 'info_hash') # NOT 'id'
assert hasattr(release, 'seeders')
assert hasattr(release, 'target_file')
# Verify quality can be converted to string
quality_str = str(quality)
assert isinstance(quality_str, str)
assert "FLAC" in quality_str
def test_search_converts_release_attributes_correctly(self):
"""Test that search() correctly maps Release attributes to AudioSearchResult."""
from flacfetch.core.models import Release, Quality, AudioFormat, MediaSource
fetcher = FlacFetchAudioFetcher()
# Create a real Release object with all fields populated
quality = Quality(format=AudioFormat.FLAC, bit_depth=24, media=MediaSource.WEB)
real_release = Release(
title="Real Song",
artist="Real Artist",
quality=quality,
source_name="Redacted",
download_url="https://example.com/download",
duration_seconds=240,
info_hash="abc123hash",
seeders=50,
target_file="01 - Real Song.flac",
)
# Mock the manager to return our real release
with patch.object(fetcher, '_get_manager') as mock_get_manager:
mock_manager = MagicMock()
mock_manager.search.return_value = [real_release]
mock_get_manager.return_value = mock_manager
results = fetcher.search("Real Artist", "Real Song")
# Verify correct attribute mapping
assert len(results) == 1
result = results[0]
assert result.title == "Real Song"
assert result.artist == "Real Artist"
assert result.provider == "Redacted" # source_name -> provider
assert result.duration == 240 # duration_seconds -> duration
assert result.url == "https://example.com/download" # download_url -> url
assert result.source_id == "abc123hash" # info_hash -> source_id
assert "FLAC" in result.quality # quality converted to string
assert result.raw_result is real_release
class TestFlacFetchCLIHandlerCompatibility:
"""Tests to verify compatibility with flacfetch's CLIHandler for rich output."""
def test_cli_handler_import_works(self):
"""Verify we can import CLIHandler from flacfetch."""
from flacfetch.interface.cli import CLIHandler
handler = CLIHandler(target_artist="Test Artist")
assert handler is not None
def test_cli_handler_works_with_real_releases(self):
"""Test that CLIHandler can display real Release objects.
This ensures we're passing proper Release objects, not mocks with wrong attributes.
"""
from flacfetch.core.models import Release, Quality, AudioFormat, MediaSource
from flacfetch.interface.cli import CLIHandler
quality = Quality(format=AudioFormat.FLAC, bit_depth=16, media=MediaSource.CD)
release = Release(
title="Test Song",
artist="Test Artist",
quality=quality,
source_name="Redacted",
seeders=25,
)
handler = CLIHandler(target_artist="Test Artist")
# This should not raise any AttributeError
# (Previously would fail if quality.is_lossless() didn't exist)
try:
# We can't easily test the full select_release without mocking input,
# but we can at least verify _print_release works
import io
import sys
# Capture stdout
captured = io.StringIO()
sys.stdout = captured
try:
handler._print_release(1, release)
finally:
sys.stdout = sys.__stdout__
output = captured.getvalue()
assert "Test Artist" in output or "Test Song" in output
except AttributeError as e:
pytest.fail(f"CLIHandler failed with AttributeError: {e}")
class TestDownloadWithCustomFilename:
"""Tests for download with custom filename."""
+297
View File
@@ -0,0 +1,297 @@
"""
Tests verifying feature parity between local and remote CLIs.
These tests ensure that both local (karaoke-gen) and remote (karaoke-gen-remote)
CLIs use the same shared core module for instrumental review functionality.
"""
import pytest
from unittest.mock import MagicMock, patch
class TestSharedCoreModuleAccess:
"""Verify both CLIs can access the shared core module."""
def test_local_cli_can_import_analyzer(self):
"""Local CLI should be able to import AudioAnalyzer."""
from karaoke_gen.instrumental_review import AudioAnalyzer
assert AudioAnalyzer is not None
def test_local_cli_can_import_editor(self):
"""Local CLI should be able to import AudioEditor."""
from karaoke_gen.instrumental_review import AudioEditor
assert AudioEditor is not None
def test_local_cli_can_import_waveform_generator(self):
"""Local CLI should be able to import WaveformGenerator."""
from karaoke_gen.instrumental_review import WaveformGenerator
assert WaveformGenerator is not None
def test_local_cli_can_import_review_server(self):
"""Local CLI should be able to import InstrumentalReviewServer."""
from karaoke_gen.instrumental_review import InstrumentalReviewServer
assert InstrumentalReviewServer is not None
def test_backend_can_import_analyzer(self):
"""Backend should be able to import AudioAnalyzer."""
from karaoke_gen.instrumental_review import AudioAnalyzer
# Backend service wrapper imports from the same module
from backend.services.audio_analysis_service import AudioAnalysisService
# Verify they use the same analyzer class
mock_storage = MagicMock()
service = AudioAnalysisService(storage_service=mock_storage)
assert service.analyzer.__class__.__name__ == "AudioAnalyzer"
def test_backend_can_import_editor(self):
"""Backend should be able to import AudioEditor."""
from karaoke_gen.instrumental_review import AudioEditor
from backend.services.audio_editing_service import AudioEditingService
mock_storage = MagicMock()
service = AudioEditingService(storage_service=mock_storage)
assert service.editor.__class__.__name__ == "AudioEditor"
class TestAnalyzerParity:
"""Verify that both CLIs get identical analysis results."""
def test_analyzer_parameters_match(self):
"""Analyzer should have same default parameters for both CLIs."""
from karaoke_gen.instrumental_review import AudioAnalyzer
# Default analyzer for local CLI
local_analyzer = AudioAnalyzer()
# The backend service uses the same analyzer with defaults
from backend.services.audio_analysis_service import AudioAnalysisService
mock_storage = MagicMock()
backend_service = AudioAnalysisService(storage_service=mock_storage)
# Same default threshold
assert local_analyzer.silence_threshold_db == backend_service.analyzer.silence_threshold_db
assert local_analyzer.silence_threshold_db == -40.0
# Same default min segment duration
assert local_analyzer.min_segment_duration_ms == backend_service.analyzer.min_segment_duration_ms
class TestEditorParity:
"""Verify that both CLIs create identical custom instrumentals."""
def test_editor_output_format_match(self):
"""Editor should produce same output format for both CLIs."""
from karaoke_gen.instrumental_review import AudioEditor
# Default editor for local CLI
local_editor = AudioEditor()
# Backend service uses same editor with same defaults
from backend.services.audio_editing_service import AudioEditingService
mock_storage = MagicMock()
backend_service = AudioEditingService(storage_service=mock_storage)
# Same default output format
assert local_editor.output_format == backend_service.editor.output_format
assert local_editor.output_format == "flac"
class TestModelConsistency:
"""Verify that models are consistent across CLIs."""
def test_mute_region_model_shared(self):
"""MuteRegion model should be shared across CLIs."""
from karaoke_gen.instrumental_review import MuteRegion
from backend.models.requests import MuteRegionRequest
# Both should validate start < end
region = MuteRegion(start_seconds=10.0, end_seconds=20.0)
request = MuteRegionRequest(start_seconds=10.0, end_seconds=20.0)
assert region.start_seconds == request.start_seconds
assert region.end_seconds == request.end_seconds
def test_analysis_result_fields_match(self):
"""AnalysisResult should have fields expected by both CLIs."""
from karaoke_gen.instrumental_review import AnalysisResult, RecommendedSelection
# Create an analysis result
result = AnalysisResult(
has_audible_content=True,
total_duration_seconds=180.0,
audible_segments=[],
recommended_selection=RecommendedSelection.REVIEW_NEEDED,
silence_threshold_db=-40.0,
)
# Fields expected by the API response
assert hasattr(result, 'has_audible_content')
assert hasattr(result, 'total_duration_seconds')
assert hasattr(result, 'audible_segments')
assert hasattr(result, 'recommended_selection')
assert hasattr(result, 'total_audible_duration_seconds')
assert hasattr(result, 'audible_percentage')
class TestReviewServerParity:
"""Verify that local review server matches backend API."""
def test_review_server_exists(self):
"""Local review server should exist."""
from karaoke_gen.instrumental_review.server import InstrumentalReviewServer
assert InstrumentalReviewServer is not None
def test_review_server_can_be_instantiated(self):
"""Local review server should be instantiable with proper parameters."""
from karaoke_gen.instrumental_review.server import InstrumentalReviewServer
from karaoke_gen.instrumental_review import AnalysisResult, RecommendedSelection
# Create mock analysis
analysis = AnalysisResult(
has_audible_content=False,
total_duration_seconds=180.0,
audible_segments=[],
recommended_selection=RecommendedSelection.CLEAN,
silence_threshold_db=-40.0,
)
# Should be able to create server instance
server = InstrumentalReviewServer(
output_dir="/tmp",
base_name="Test - Song",
analysis=analysis,
waveform_path="/tmp/waveform.png",
backing_vocals_path="/tmp/backing.flac",
clean_instrumental_path="/tmp/clean.flac",
)
assert server is not None
assert server.output_dir == "/tmp"
assert server.base_name == "Test - Song"
def test_review_server_api_endpoints_match_backend(self):
"""Review server should serve same API endpoints as backend."""
from karaoke_gen.instrumental_review.server import InstrumentalReviewServer
# The server should have methods to create app and register routes
assert hasattr(InstrumentalReviewServer, '_create_app')
assert hasattr(InstrumentalReviewServer, '_register_routes')
assert hasattr(InstrumentalReviewServer, '_get_frontend_html')
# Server should have the main interface methods
assert hasattr(InstrumentalReviewServer, 'start_and_open_browser')
assert hasattr(InstrumentalReviewServer, 'get_selection')
assert hasattr(InstrumentalReviewServer, 'get_custom_instrumental_path')
class TestRemoteCLIAnalysisIntegration:
"""Verify remote CLI uses the analysis API."""
def test_remote_cli_has_analysis_method(self):
"""Remote CLI client should have get_instrumental_analysis method."""
from karaoke_gen.utils.remote_cli import RemoteKaraokeClient
# The client should have the analysis method
assert hasattr(RemoteKaraokeClient, 'get_instrumental_analysis')
def test_remote_cli_has_browser_method(self):
"""Remote CLI should be able to open browser for review."""
from karaoke_gen.utils.remote_cli import JobMonitor
# The job monitor should have browser review method
assert hasattr(JobMonitor, '_open_instrumental_review_and_wait')
def test_remote_cli_handle_instrumental_selection_exists(self):
"""Remote CLI should have handle_instrumental_selection method."""
from karaoke_gen.utils.remote_cli import JobMonitor
assert hasattr(JobMonitor, 'handle_instrumental_selection')
class TestLocalCLIIntegration:
"""Verify local CLI actually integrates the instrumental review UI.
These tests ensure the local CLI (gen_cli.py) actually uses the
InstrumentalReviewServer to provide the interactive review experience,
not just that the classes exist.
"""
def test_gen_cli_has_run_instrumental_review_function(self):
"""gen_cli.py should have run_instrumental_review function."""
from karaoke_gen.utils import gen_cli
# The function should exist
assert hasattr(gen_cli, 'run_instrumental_review')
assert callable(gen_cli.run_instrumental_review)
def test_gen_cli_imports_instrumental_review_components(self):
"""gen_cli.py should import necessary instrumental review components."""
import karaoke_gen.utils.gen_cli as gen_cli
import inspect
# Get the source of the module to verify imports
source = inspect.getsource(gen_cli)
# Should import the key components
assert 'from karaoke_gen.instrumental_review import' in source
assert 'AudioAnalyzer' in source
assert 'WaveformGenerator' in source
assert 'InstrumentalReviewServer' in source
def test_run_instrumental_review_uses_analyzer(self):
"""run_instrumental_review should use AudioAnalyzer."""
import inspect
from karaoke_gen.utils.gen_cli import run_instrumental_review
source = inspect.getsource(run_instrumental_review)
# Should create and use analyzer
assert 'AudioAnalyzer()' in source or 'AudioAnalyzer(' in source
assert 'analyzer.analyze' in source or 'analysis = analyzer' in source
def test_run_instrumental_review_uses_waveform_generator(self):
"""run_instrumental_review should use WaveformGenerator."""
import inspect
from karaoke_gen.utils.gen_cli import run_instrumental_review
source = inspect.getsource(run_instrumental_review)
# Should create and use waveform generator
assert 'WaveformGenerator()' in source or 'WaveformGenerator(' in source
assert 'waveform_generator.generate' in source or 'generator.generate' in source
def test_run_instrumental_review_uses_server(self):
"""run_instrumental_review should use InstrumentalReviewServer."""
import inspect
from karaoke_gen.utils.gen_cli import run_instrumental_review
source = inspect.getsource(run_instrumental_review)
# Should create and use the review server
assert 'InstrumentalReviewServer(' in source
assert 'server.start_and_open_browser' in source
assert 'server.get_selection' in source
def test_gen_cli_has_skip_instrumental_review_flag(self):
"""gen_cli should support --skip_instrumental_review flag."""
from karaoke_gen.utils.cli_args import create_parser
parser = create_parser(prog="test")
# Parse with the flag
args = parser.parse_args(['--skip_instrumental_review', 'Test', 'Song'])
assert hasattr(args, 'skip_instrumental_review')
assert args.skip_instrumental_review == True
def test_gen_cli_skip_instrumental_review_defaults_false(self):
"""skip_instrumental_review should default to False."""
from karaoke_gen.utils.cli_args import create_parser
parser = create_parser(prog="test")
# Parse without the flag
args = parser.parse_args(['Test', 'Song'])
assert hasattr(args, 'skip_instrumental_review')
assert args.skip_instrumental_review == False
+252 -26
View File
@@ -130,7 +130,7 @@ def mock_sleep():
@patch("karaoke_gen.utils.gen_cli.is_url", return_value=True)
@patch("karaoke_gen.utils.gen_cli.is_file", return_value=False)
@patch("karaoke_gen.utils.gen_cli.KaraokePrep") # Use default MagicMock for class
async def test_arg_parsing_url_only(mock_kprep_class, mock_isfile, mock_isurl, mock_base_args, mock_logger, caplog):
async def test_arg_parsing_url_only(mock_kprep_class, mock_isfile, mock_isurl, mock_base_args, mock_logger, capsys):
"""Test URL-only argument parsing."""
mock_base_args.args = ["https://example.com/song.mp3"]
mock_kprep_instance = MagicMock()
@@ -145,8 +145,9 @@ async def test_arg_parsing_url_only(mock_kprep_class, mock_isfile, mock_isurl, m
# Verify that input_media=URL is passed
assert mock_kprep_class.call_args.kwargs["input_media"] == "https://example.com/song.mp3"
mock_kprep_instance.process.assert_awaited_once()
# Verify warning in log
assert "Input media provided without Artist and Title" in caplog.text
# Verify warning in log (captured in stderr since logger.propagate = False)
captured = capsys.readouterr()
assert "Input media provided without Artist and Title" in captured.err
@patch("karaoke_gen.utils.gen_cli.is_url", return_value=True)
@patch("karaoke_gen.utils.gen_cli.is_file", return_value=False)
@@ -194,7 +195,7 @@ async def test_arg_parsing_file_artist_title(mock_kprep_class, mock_isfile, mock
@patch("karaoke_gen.utils.gen_cli.is_file", return_value=False)
@patch("karaoke_gen.utils.gen_cli.os.path.isdir", return_value=False)
@patch("karaoke_gen.utils.gen_cli.KaraokePrep") # Use default MagicMock for class
async def test_arg_parsing_artist_title_only(mock_kprep_class, mock_isdir, mock_isfile, mock_isurl, mock_base_args, mock_logger, caplog):
async def test_arg_parsing_artist_title_only(mock_kprep_class, mock_isdir, mock_isfile, mock_isurl, mock_base_args, mock_logger, capsys):
"""Test Artist and Title only argument parsing."""
mock_base_args.args = ["Test Artist", "Test Title"]
mock_kprep_instance = MagicMock()
@@ -211,8 +212,9 @@ async def test_arg_parsing_artist_title_only(mock_kprep_class, mock_isdir, mock_
assert mock_kprep_class.call_args.kwargs["title"] == "Test Title"
assert mock_kprep_class.call_args.kwargs["input_media"] is None
mock_kprep_instance.process.assert_awaited_once()
# Verify message about flacfetch search is shown
assert "flacfetch will search for" in caplog.text
# Verify message about flacfetch search is shown (in stderr since logger.propagate = False)
captured = capsys.readouterr()
assert "flacfetch will search for" in captured.err
@patch("karaoke_gen.utils.gen_cli.is_url", return_value=False)
@patch("karaoke_gen.utils.gen_cli.is_file", return_value=False)
@@ -281,7 +283,8 @@ async def test_workflow_prep_only(mock_kfinalise, mock_kprep_class, mock_base_ar
@patch("karaoke_gen.utils.gen_cli.KaraokePrep") # Should not be called
@patch("karaoke_gen.utils.gen_cli.KaraokeFinalise")
@patch("builtins.open", new_callable=mock_open) # Mock open for style JSON if CDG enabled
async def test_workflow_finalise_only(mock_open, mock_kfinalise, mock_kprep, mock_base_args, mock_logger):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_workflow_finalise_only(mock_run_review, mock_open, mock_kfinalise, mock_kprep, mock_base_args, mock_logger):
"""Test --finalise-only workflow."""
mock_base_args.finalise_only = True
mock_kfinalise_instance = mock_kfinalise.return_value
@@ -304,7 +307,8 @@ async def test_workflow_finalise_only(mock_open, mock_kfinalise, mock_kprep, moc
@patch("karaoke_gen.utils.gen_cli.os.path.basename", return_value="Edit Artist - Edit Title")
@patch("karaoke_gen.utils.gen_cli.os.getcwd", return_value="/fake/path/Edit Artist - Edit Title")
@patch("builtins.open", new_callable=mock_open) # Mock open for style JSON if CDG enabled
async def test_workflow_edit_lyrics(mock_open, mock_getcwd, mock_basename, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_workflow_edit_lyrics(mock_run_review, mock_open, mock_getcwd, mock_basename, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger):
"""Test --edit-lyrics workflow."""
mock_base_args.edit_lyrics = True
mock_base_args.enable_cdg = False # Simplify for now
@@ -370,7 +374,8 @@ async def test_workflow_test_email_template(mock_kfinalise, mock_base_args, mock
@patch("karaoke_gen.utils.gen_cli.KaraokePrep") # Use default MagicMock for class
@patch("karaoke_gen.utils.gen_cli.KaraokeFinalise")
async def test_workflow_lyrics_only(mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_workflow_lyrics_only(mock_run_review, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger):
"""Test --lyrics-only workflow sets environment variables and skips."""
mock_base_args.args = ["Artist", "Title"]
mock_base_args.lyrics_only = True
@@ -404,7 +409,8 @@ async def test_workflow_lyrics_only(mock_kfinalise, mock_kprep_class, mock_base_
@patch("builtins.open", new_callable=mock_open, read_data=SAMPLE_STYLE_JSON)
@patch("karaoke_gen.utils.gen_cli.os.chdir") # Mock chdir
@patch("karaoke_gen.utils.gen_cli.os.path.exists", return_value=True) # Assume track dir exists
async def test_finalise_cdg_style_loading(mock_exists, mock_chdir, mock_open, mock_kfinalise, mock_kprep_class, mock_base_args):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_finalise_cdg_style_loading(mock_run_review, mock_exists, mock_chdir, mock_open, mock_kfinalise, mock_kprep_class, mock_base_args):
"""Test that CDG styles are loaded correctly when --enable_cdg is used."""
mock_base_args.args = ["Artist", "Title"]
mock_base_args.enable_cdg = True
@@ -437,7 +443,8 @@ async def test_finalise_cdg_style_loading(mock_exists, mock_chdir, mock_open, mo
@patch("karaoke_gen.utils.gen_cli.os.chdir")
@patch("karaoke_gen.utils.gen_cli.os.path.exists", return_value=True)
@patch("karaoke_gen.utils.gen_cli.sys.exit")
async def test_finalise_cdg_style_file_not_found(mock_exit, mock_exists, mock_chdir, mock_open, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_finalise_cdg_style_file_not_found(mock_run_review, mock_exit, mock_exists, mock_chdir, mock_open, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger):
"""Test exit if CDG enabled but style file not found."""
mock_base_args.args = ["Artist", "Title"]
mock_base_args.enable_cdg = True
@@ -465,7 +472,8 @@ async def test_finalise_cdg_style_file_not_found(mock_exit, mock_exists, mock_ch
@patch("karaoke_gen.utils.gen_cli.os.chdir")
@patch("karaoke_gen.utils.gen_cli.os.path.exists", return_value=True)
@patch("karaoke_gen.utils.gen_cli.sys.exit")
async def test_finalise_cdg_style_invalid_json(mock_exit, mock_exists, mock_chdir, mock_open, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_finalise_cdg_style_invalid_json(mock_run_review, mock_exit, mock_exists, mock_chdir, mock_open, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger):
"""Test exit if CDG enabled but style file has invalid JSON."""
mock_base_args.args = ["Artist", "Title"]
mock_base_args.enable_cdg = True
@@ -490,7 +498,7 @@ async def test_finalise_cdg_style_invalid_json(mock_exit, mock_exists, mock_chdi
@patch("karaoke_gen.utils.gen_cli.KaraokePrep") # Use default MagicMock for class
@patch("karaoke_gen.utils.gen_cli.KaraokeFinalise")
async def test_error_handling_kprep_failure(mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger, caplog):
async def test_error_handling_kprep_failure(mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger):
"""Test error handling if KaraokePrep.process fails."""
mock_base_args.args = ["Artist", "Title"]
mock_kprep_instance = MagicMock()
@@ -512,7 +520,8 @@ async def test_error_handling_kprep_failure(mock_kfinalise, mock_kprep_class, mo
@patch("karaoke_gen.utils.gen_cli.KaraokeFinalise")
@patch("karaoke_gen.utils.gen_cli.os.chdir")
@patch("karaoke_gen.utils.gen_cli.os.path.exists", return_value=True)
async def test_error_handling_kfinalise_failure(mock_exists, mock_chdir, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger, caplog):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_error_handling_kfinalise_failure(mock_run_review, mock_exists, mock_chdir, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger, capsys):
"""Test error handling if KaraokeFinalise.process fails."""
mock_base_args.args = ["Artist", "Title"]
mock_kprep_instance = MagicMock()
@@ -533,13 +542,15 @@ async def test_error_handling_kfinalise_failure(mock_exists, mock_chdir, mock_kf
mock_kfinalise.assert_called_once() # Finalise is called
mock_kfinalise_instance.process.assert_called_once() # Process is called
# Check the error message in log
assert "An error occurred during finalisation, see stack trace below: KFinalise Failed!" in caplog.text
# Check the error message in log (in stderr since logger.propagate = False)
captured = capsys.readouterr()
assert "An error occurred during finalisation, see stack trace below: KFinalise Failed!" in captured.err
@patch("karaoke_gen.utils.gen_cli.KaraokePrep") # Use default MagicMock for class
@patch("karaoke_gen.utils.gen_cli.KaraokeFinalise")
async def test_argument_passthrough(mock_kfinalise, mock_kprep_class, mock_base_args):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_argument_passthrough(mock_run_review, mock_kfinalise, mock_kprep_class, mock_base_args):
"""Test that various arguments are passed correctly to KaraokePrep/Finalise."""
mock_base_args.args = ["Artist", "Title"]
mock_base_args.render_bounding_boxes = True
@@ -595,7 +606,8 @@ async def test_argument_passthrough(mock_kfinalise, mock_kprep_class, mock_base_
@patch("karaoke_gen.utils.gen_cli.os.chdir")
@patch("karaoke_gen.utils.gen_cli.os.path.exists", return_value=True)
@patch("karaoke_gen.utils.gen_cli.pyperclip.copy")
async def test_clipboard_copy_success(mock_copy, mock_exists, mock_chdir, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger, caplog):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_clipboard_copy_success(mock_run_review, mock_copy, mock_exists, mock_chdir, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger, capsys):
"""Test logging when clipboard copy succeeds."""
mock_base_args.args = ["Artist", "Title"]
@@ -615,9 +627,10 @@ async def test_clipboard_copy_success(mock_copy, mock_exists, mock_chdir, mock_k
await gen_cli.async_main()
mock_kprep_instance.process.assert_awaited_once()
# Check log capture for success messages
assert "(Folder link copied to clipboard)" in caplog.text
assert "(YouTube URL copied to clipboard)" in caplog.text
# Check log capture for success messages (in stderr since logger.propagate = False)
captured = capsys.readouterr()
assert "(Folder link copied to clipboard)" in captured.err
assert "(YouTube URL copied to clipboard)" in captured.err
mock_copy.assert_has_calls([
call("http://share.link/fake"),
@@ -630,7 +643,8 @@ async def test_clipboard_copy_success(mock_copy, mock_exists, mock_chdir, mock_k
@patch("karaoke_gen.utils.gen_cli.os.chdir")
@patch("karaoke_gen.utils.gen_cli.os.path.exists", return_value=True)
@patch("karaoke_gen.utils.gen_cli.pyperclip.copy", side_effect=Exception("Clipboard Error"))
async def test_clipboard_copy_failure(mock_copy, mock_exists, mock_chdir, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger, caplog):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_clipboard_copy_failure(mock_run_review, mock_copy, mock_exists, mock_chdir, mock_kfinalise, mock_kprep_class, mock_base_args, mock_logger, capsys):
"""Test logging when clipboard copy fails."""
mock_base_args.args = ["Artist", "Title"]
@@ -650,9 +664,10 @@ async def test_clipboard_copy_failure(mock_copy, mock_exists, mock_chdir, mock_k
await gen_cli.async_main()
mock_kprep_instance.process.assert_awaited_once()
# Check log capture for warning messages
assert "Failed to copy folder link to clipboard: Clipboard Error" in caplog.text
assert "Failed to copy YouTube URL to clipboard: Clipboard Error" in caplog.text
# Check log capture for warning messages (in stderr since logger.propagate = False)
captured = capsys.readouterr()
assert "Failed to copy folder link to clipboard: Clipboard Error" in captured.err
assert "Failed to copy YouTube URL to clipboard: Clipboard Error" in captured.err
# Verify clipboard calls were attempted
mock_copy.assert_has_calls([
@@ -662,7 +677,8 @@ async def test_clipboard_copy_failure(mock_copy, mock_exists, mock_chdir, mock_k
@patch("karaoke_gen.utils.gen_cli.KaraokePrep")
async def test_style_override_parsing(mock_kprep_class, mock_base_args):
@patch("karaoke_gen.utils.gen_cli.run_instrumental_review", return_value="selected_instrumental.flac")
async def test_style_override_parsing(mock_run_review, mock_kprep_class, mock_base_args):
"""Test that --style_override arguments are parsed correctly."""
mock_base_args.args = ["Artist", "Title"]
mock_base_args.style_override = ["intro.background_image=new_image.png", "end.video_duration=10"]
@@ -685,3 +701,213 @@ async def test_style_override_parsing(mock_kprep_class, mock_base_args):
"end.video_duration": "10"
}
assert prep_kwargs["style_overrides"] == expected_overrides
# --- Test _resolve_path_for_cwd helper function ---
class TestResolvePathForCwd:
"""Tests for the _resolve_path_for_cwd helper function.
This function resolves paths that were created relative to the original working
directory after os.chdir(track_dir) has been called.
"""
def test_absolute_path_unchanged(self):
"""Absolute paths should be returned unchanged."""
from karaoke_gen.utils.gen_cli import _resolve_path_for_cwd
path = "/absolute/path/to/file.flac"
track_dir = "./Artist - Title"
result = _resolve_path_for_cwd(path, track_dir)
assert result == path
def test_relative_path_starting_with_track_dir(self):
"""Paths starting with track_dir should have track_dir stripped."""
from karaoke_gen.utils.gen_cli import _resolve_path_for_cwd
path = "./Artist - Title/stems/file.flac"
track_dir = "./Artist - Title"
result = _resolve_path_for_cwd(path, track_dir)
assert result == "stems/file.flac"
def test_relative_path_with_different_format(self):
"""Paths without ./ prefix should also be handled."""
from karaoke_gen.utils.gen_cli import _resolve_path_for_cwd
path = "Artist - Title/stems/file.flac"
track_dir = "Artist - Title"
result = _resolve_path_for_cwd(path, track_dir)
assert result == "stems/file.flac"
def test_path_not_starting_with_track_dir(self):
"""Paths not starting with track_dir should be returned unchanged."""
from karaoke_gen.utils.gen_cli import _resolve_path_for_cwd
path = "different/path/to/file.flac"
track_dir = "./Artist - Title"
result = _resolve_path_for_cwd(path, track_dir)
assert result == path
def test_path_with_complex_track_name(self):
"""Test with a track name containing special characters."""
from karaoke_gen.utils.gen_cli import _resolve_path_for_cwd
path = "./Four Lanes Male Choir - The White Rose/stems/backing_vocals.flac"
track_dir = "./Four Lanes Male Choir - The White Rose"
result = _resolve_path_for_cwd(path, track_dir)
assert result == "stems/backing_vocals.flac"
def test_path_exactly_matching_track_dir(self):
"""Test when path exactly matches track_dir (edge case)."""
from karaoke_gen.utils.gen_cli import _resolve_path_for_cwd
path = "./Artist - Title"
track_dir = "./Artist - Title"
result = _resolve_path_for_cwd(path, track_dir)
assert result == "."
def test_normalized_path_comparison(self):
"""Test that path normalization works correctly."""
from karaoke_gen.utils.gen_cli import _resolve_path_for_cwd
# Paths with extra slashes or dots should be normalized
path = "./Artist - Title//stems/./file.flac"
track_dir = "./Artist - Title/"
result = _resolve_path_for_cwd(path, track_dir)
# After normalization: "Artist - Title/stems/file.flac" vs "Artist - Title"
assert result == "stems/file.flac"
# --- Test auto_select_instrumental helper function ---
class TestAutoSelectInstrumental:
"""Tests for the auto_select_instrumental function.
This function automatically selects the best instrumental file when
--skip_instrumental_review is used.
"""
def test_prefers_padded_combined_over_non_padded(self, tmp_path, mock_logger):
"""Padded combined instrumental should be preferred."""
from karaoke_gen.utils.gen_cli import auto_select_instrumental
# Create test files
combined = tmp_path / "Artist - Title (Instrumental +BV model.ckpt).flac"
combined_padded = tmp_path / "Artist - Title (Instrumental +BV model.ckpt) (Padded).flac"
combined.touch()
combined_padded.touch()
track = {
"track_output_dir": str(tmp_path),
"separated_audio": {
"combined_instrumentals": {
"model.ckpt": str(combined)
}
}
}
# Change to temp directory (simulating the chdir in gen_cli)
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
result = auto_select_instrumental(track, str(tmp_path), mock_logger)
assert "(Padded)" in result
finally:
os.chdir(original_dir)
def test_prefers_combined_over_clean(self, tmp_path, mock_logger):
"""Combined instrumental (+BV) should be preferred over clean."""
from karaoke_gen.utils.gen_cli import auto_select_instrumental
# Create test files
clean = tmp_path / "Artist - Title (Instrumental model.ckpt).flac"
combined = tmp_path / "Artist - Title (Instrumental +BV model.ckpt).flac"
clean.touch()
combined.touch()
track = {
"track_output_dir": str(tmp_path),
"separated_audio": {
"clean_instrumental": {
"instrumental": str(clean)
},
"combined_instrumentals": {
"model.ckpt": str(combined)
}
}
}
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
result = auto_select_instrumental(track, str(tmp_path), mock_logger)
assert "+BV" in result
finally:
os.chdir(original_dir)
def test_falls_back_to_clean_when_no_combined(self, tmp_path, mock_logger):
"""Should use clean instrumental if no combined available."""
from karaoke_gen.utils.gen_cli import auto_select_instrumental
# Create test file
clean = tmp_path / "Artist - Title (Instrumental model.ckpt).flac"
clean.touch()
track = {
"track_output_dir": str(tmp_path),
"separated_audio": {
"clean_instrumental": {
"instrumental": str(clean)
},
"combined_instrumentals": {}
}
}
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
result = auto_select_instrumental(track, str(tmp_path), mock_logger)
assert "Instrumental" in result
finally:
os.chdir(original_dir)
def test_raises_error_when_no_instrumental_found(self, tmp_path, mock_logger):
"""Should raise FileNotFoundError when no instrumental available."""
from karaoke_gen.utils.gen_cli import auto_select_instrumental
track = {
"track_output_dir": str(tmp_path),
"separated_audio": {
"clean_instrumental": {},
"combined_instrumentals": {}
}
}
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
with pytest.raises(FileNotFoundError, match="No instrumental file found"):
auto_select_instrumental(track, str(tmp_path), mock_logger)
finally:
os.chdir(original_dir)
def test_searches_directory_as_fallback(self, tmp_path, mock_logger):
"""Should search directory if separated_audio is missing data."""
from karaoke_gen.utils.gen_cli import auto_select_instrumental
# Create test file in directory but not in separated_audio
instrumental = tmp_path / "Artist - Title (Instrumental model.ckpt).flac"
instrumental.touch()
track = {
"track_output_dir": str(tmp_path),
"separated_audio": {} # Empty - nothing in separated_audio
}
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
result = auto_select_instrumental(track, str(tmp_path), mock_logger)
assert "Instrumental" in result
finally:
os.chdir(original_dir)
@@ -0,0 +1,9 @@
"""
Unit tests for the instrumental_review module.
This package contains comprehensive unit tests for:
- AudioAnalyzer: Audio analysis for backing vocals
- AudioEditor: Custom instrumental creation with mute regions
- WaveformGenerator: Waveform visualization generation
- Models: Pydantic models for data structures
"""
@@ -0,0 +1,189 @@
"""
Test fixtures for instrumental_review tests.
This module provides pytest fixtures that generate test audio files
programmatically using pydub. This avoids the need for static test
audio files in the repository.
"""
import os
import math
import tempfile
from pathlib import Path
from typing import Generator
import pytest
from pydub import AudioSegment
from pydub.generators import Sine, WhiteNoise
@pytest.fixture
def temp_dir() -> Generator[str, None, None]:
"""Create a temporary directory for test files."""
with tempfile.TemporaryDirectory() as temp_dir:
yield temp_dir
@pytest.fixture
def silent_audio_path(temp_dir: str) -> str:
"""
Create a silent audio file (10 seconds).
This represents backing vocals with no audible content.
"""
duration_ms = 10000 # 10 seconds
# Create silent audio
audio = AudioSegment.silent(duration=duration_ms, frame_rate=44100)
# Save to file
output_path = os.path.join(temp_dir, "silent_backing_vocals.flac")
audio.export(output_path, format="flac")
return output_path
@pytest.fixture
def loud_audio_path(temp_dir: str) -> str:
"""
Create an audio file with consistent audible content (10 seconds).
This represents backing vocals with clear, continuous content.
"""
duration_ms = 10000 # 10 seconds
# Create a sine wave tone
tone = Sine(440).to_audio_segment(duration=duration_ms)
# Reduce volume to -10dB
tone = tone - 10
# Save to file
output_path = os.path.join(temp_dir, "loud_backing_vocals.flac")
tone.export(output_path, format="flac")
return output_path
@pytest.fixture
def mixed_audio_path(temp_dir: str) -> str:
"""
Create an audio file with alternating silent and audible sections.
Pattern: 2s silent, 3s audible, 2s silent, 3s audible = 10s total
This represents backing vocals with some good sections and some
sections that might need muting.
"""
# Create segments
silence1 = AudioSegment.silent(duration=2000, frame_rate=44100) # 2s
tone1 = Sine(440).to_audio_segment(duration=3000) - 15 # 3s at -15dB
silence2 = AudioSegment.silent(duration=2000, frame_rate=44100) # 2s
tone2 = Sine(880).to_audio_segment(duration=3000) - 15 # 3s at -15dB
# Combine
audio = silence1 + tone1 + silence2 + tone2
# Save to file
output_path = os.path.join(temp_dir, "mixed_backing_vocals.flac")
audio.export(output_path, format="flac")
return output_path
@pytest.fixture
def quiet_audio_path(temp_dir: str) -> str:
"""
Create an audio file with very quiet content (below -40dB threshold).
This represents backing vocals that technically have content but
are quiet enough to be considered silent.
"""
duration_ms = 10000 # 10 seconds
# Create a very quiet sine wave (-50dB)
tone = Sine(440).to_audio_segment(duration=duration_ms)
tone = tone - 50 # Very quiet
# Save to file
output_path = os.path.join(temp_dir, "quiet_backing_vocals.flac")
tone.export(output_path, format="flac")
return output_path
@pytest.fixture
def clean_instrumental_path(temp_dir: str) -> str:
"""
Create a clean instrumental audio file.
This is used for testing the audio editor.
"""
duration_ms = 10000 # 10 seconds
# Create a chord-like sound (multiple frequencies)
tone1 = Sine(220).to_audio_segment(duration=duration_ms) - 12 # A
tone2 = Sine(277).to_audio_segment(duration=duration_ms) - 12 # C#
tone3 = Sine(330).to_audio_segment(duration=duration_ms) - 12 # E
# Mix the tones
chord = tone1.overlay(tone2).overlay(tone3)
# Save to file
output_path = os.path.join(temp_dir, "clean_instrumental.flac")
chord.export(output_path, format="flac")
return output_path
@pytest.fixture
def backing_vocals_with_issues_path(temp_dir: str) -> str:
"""
Create backing vocals with some sections that should be muted.
Pattern:
- 0-3s: Good backing vocals (harmonies)
- 3-5s: Bad section (lead vocal bleed - louder)
- 5-8s: Good backing vocals
- 8-10s: Bad section (artifacts)
"""
# Good section 1: Quiet harmonies
good1 = Sine(330).to_audio_segment(duration=3000) - 20 # 3s at -20dB
# Bad section 1: Loud lead vocal bleed
bad1 = Sine(440).to_audio_segment(duration=2000) - 5 # 2s at -5dB (loud)
# Good section 2: Quiet harmonies
good2 = Sine(392).to_audio_segment(duration=3000) - 20 # 3s at -20dB
# Bad section 2: Artifacts (noise-like)
bad2 = WhiteNoise().to_audio_segment(duration=2000) - 15 # 2s at -15dB
# Combine
audio = good1 + bad1 + good2 + bad2
# Save to file
output_path = os.path.join(temp_dir, "backing_vocals_with_issues.flac")
audio.export(output_path, format="flac")
return output_path
@pytest.fixture
def stereo_audio_path(temp_dir: str) -> str:
"""
Create a stereo audio file for testing channel handling.
"""
duration_ms = 5000 # 5 seconds
# Create stereo audio
left = Sine(440).to_audio_segment(duration=duration_ms) - 15
right = Sine(550).to_audio_segment(duration=duration_ms) - 15
stereo = AudioSegment.from_mono_audiosegments(left, right)
# Save to file
output_path = os.path.join(temp_dir, "stereo_backing_vocals.flac")
stereo.export(output_path, format="flac")
return output_path
@@ -0,0 +1,321 @@
"""
Unit tests for AudioAnalyzer.
Tests cover:
- Analysis of silent audio
- Analysis of audio with content
- Segment detection and merging
- Threshold behavior
- Recommendation logic
- Edge cases
"""
import os
import pytest
from pydub import AudioSegment
from pydub.generators import Sine
from karaoke_gen.instrumental_review import (
AudioAnalyzer,
AnalysisResult,
AudibleSegment,
RecommendedSelection,
)
class TestAudioAnalyzerInit:
"""Tests for AudioAnalyzer initialization."""
def test_default_parameters(self):
"""Test analyzer creates with sensible defaults."""
analyzer = AudioAnalyzer()
assert analyzer.silence_threshold_db == -40.0
assert analyzer.min_segment_duration_ms == 100
assert analyzer.merge_gap_ms == 500
assert analyzer.window_ms == 50
def test_custom_parameters(self):
"""Test analyzer accepts custom parameters."""
analyzer = AudioAnalyzer(
silence_threshold_db=-35.0,
min_segment_duration_ms=200,
merge_gap_ms=300,
window_ms=100,
)
assert analyzer.silence_threshold_db == -35.0
assert analyzer.min_segment_duration_ms == 200
assert analyzer.merge_gap_ms == 300
assert analyzer.window_ms == 100
class TestAnalyzeSilentAudio:
"""Tests for analyzing silent/near-silent audio."""
def test_silent_audio_returns_no_audible_content(self, silent_audio_path):
"""Silent audio should return has_audible_content=False."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(silent_audio_path)
assert result.has_audible_content is False
assert len(result.audible_segments) == 0
assert result.total_audible_duration_seconds == 0.0
assert result.audible_percentage == 0.0
def test_silent_audio_recommends_clean(self, silent_audio_path):
"""Silent audio should recommend clean instrumental."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(silent_audio_path)
assert result.recommended_selection == RecommendedSelection.CLEAN
def test_quiet_audio_below_threshold_is_silent(self, quiet_audio_path):
"""Audio below threshold should be considered silent."""
analyzer = AudioAnalyzer(silence_threshold_db=-40.0)
result = analyzer.analyze(quiet_audio_path)
# Very quiet audio (-50dB) should be below -40dB threshold
assert result.has_audible_content is False
assert result.recommended_selection == RecommendedSelection.CLEAN
class TestAnalyzeAudibleAudio:
"""Tests for analyzing audio with audible content."""
def test_loud_audio_has_audible_content(self, loud_audio_path):
"""Loud audio should return has_audible_content=True."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(loud_audio_path)
assert result.has_audible_content is True
assert len(result.audible_segments) > 0
assert result.total_audible_duration_seconds > 0
def test_loud_audio_high_audible_percentage(self, loud_audio_path):
"""Consistently loud audio should have high audible percentage."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(loud_audio_path)
# Should be mostly audible
assert result.audible_percentage > 80.0
def test_loud_audio_recommends_review(self, loud_audio_path):
"""Loud audio should recommend review."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(loud_audio_path)
assert result.recommended_selection == RecommendedSelection.REVIEW_NEEDED
class TestSegmentDetection:
"""Tests for segment detection and merging."""
def test_mixed_audio_detects_multiple_segments(self, mixed_audio_path):
"""Mixed audio should detect distinct audible segments."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(mixed_audio_path)
assert result.has_audible_content is True
# Should detect the two audible sections (3s each)
assert len(result.audible_segments) >= 1
def test_segment_timing_is_accurate(self, mixed_audio_path):
"""Detected segment timings should be approximately correct."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(mixed_audio_path)
# First audible section should start around 2s (after 2s silence)
if result.audible_segments:
first_segment = result.audible_segments[0]
# Allow some tolerance for window-based analysis
assert first_segment.start_seconds >= 1.5
assert first_segment.start_seconds <= 2.5
def test_short_segments_are_filtered(self, temp_dir):
"""Segments shorter than min_segment_duration_ms should be filtered."""
# Create audio with very short audible blips
silence1 = AudioSegment.silent(duration=1000, frame_rate=44100)
blip = Sine(440).to_audio_segment(duration=50) - 10 # 50ms blip
silence2 = AudioSegment.silent(duration=1000, frame_rate=44100)
audio = silence1 + blip + silence2
audio_path = os.path.join(temp_dir, "short_blip.flac")
audio.export(audio_path, format="flac")
# Analyzer with 100ms minimum should filter out 50ms blip
analyzer = AudioAnalyzer(min_segment_duration_ms=100)
result = analyzer.analyze(audio_path)
# The short blip should be filtered
assert len(result.audible_segments) == 0
def test_close_segments_are_merged(self, temp_dir):
"""Close segments should be merged based on merge_gap_ms."""
# Create audio with two close audible sections
tone1 = Sine(440).to_audio_segment(duration=1000) - 10 # 1s
gap = AudioSegment.silent(duration=200, frame_rate=44100) # 200ms gap
tone2 = Sine(440).to_audio_segment(duration=1000) - 10 # 1s
audio = tone1 + gap + tone2
audio_path = os.path.join(temp_dir, "close_segments.flac")
audio.export(audio_path, format="flac")
# With 500ms merge gap, the 200ms gap should cause merging
analyzer = AudioAnalyzer(merge_gap_ms=500)
result = analyzer.analyze(audio_path)
# Should merge into one segment
assert len(result.audible_segments) == 1
class TestThresholdBehavior:
"""Tests for silence threshold behavior."""
def test_custom_threshold_affects_detection(self, temp_dir):
"""Different thresholds should detect different content."""
# Create audio at -35dB
tone = Sine(440).to_audio_segment(duration=5000)
tone = tone - 35
audio_path = os.path.join(temp_dir, "threshold_test.flac")
tone.export(audio_path, format="flac")
# With -40dB threshold, -35dB audio should be detected
analyzer_low = AudioAnalyzer(silence_threshold_db=-40.0)
result_low = analyzer_low.analyze(audio_path)
# With -30dB threshold, -35dB audio should NOT be detected
analyzer_high = AudioAnalyzer(silence_threshold_db=-30.0)
result_high = analyzer_high.analyze(audio_path)
assert result_low.has_audible_content is True
assert result_high.has_audible_content is False
def test_threshold_stored_in_result(self, silent_audio_path):
"""The threshold used should be stored in the result."""
threshold = -42.5
analyzer = AudioAnalyzer(silence_threshold_db=threshold)
result = analyzer.analyze(silent_audio_path)
assert result.silence_threshold_db == threshold
class TestRecommendationLogic:
"""Tests for instrumental selection recommendations."""
def test_no_content_recommends_clean(self, silent_audio_path):
"""No audible content should recommend clean."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(silent_audio_path)
assert result.recommended_selection == RecommendedSelection.CLEAN
def test_high_percentage_recommends_review(self, loud_audio_path):
"""High audible percentage (>20%) should recommend review."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(loud_audio_path)
assert result.audible_percentage > 20.0
assert result.recommended_selection == RecommendedSelection.REVIEW_NEEDED
def test_loud_segments_recommend_review(self, temp_dir):
"""Loud segments (>-20dB) should recommend review."""
# Create audio with a loud section
silence = AudioSegment.silent(duration=5000, frame_rate=44100)
loud_section = Sine(440).to_audio_segment(duration=500) - 5 # Very loud
audio = silence + loud_section + silence
audio_path = os.path.join(temp_dir, "loud_section.flac")
audio.export(audio_path, format="flac")
analyzer = AudioAnalyzer()
result = analyzer.analyze(audio_path)
# Even though percentage is low, loud segment should trigger review
assert result.recommended_selection == RecommendedSelection.REVIEW_NEEDED
class TestAmplitudeEnvelope:
"""Tests for amplitude envelope extraction."""
def test_envelope_length_matches_duration(self, loud_audio_path):
"""Envelope should have expected number of points."""
analyzer = AudioAnalyzer()
window_ms = 100
envelope = analyzer.get_amplitude_envelope(loud_audio_path, window_ms=window_ms)
# 10 second audio with 100ms windows = ~100 points
assert len(envelope) >= 90
assert len(envelope) <= 110
def test_envelope_normalized_to_0_1(self, loud_audio_path):
"""Normalized envelope should have values between 0 and 1."""
analyzer = AudioAnalyzer()
envelope = analyzer.get_amplitude_envelope(
loud_audio_path, normalize=True
)
assert all(0.0 <= v <= 1.0 for v in envelope)
def test_envelope_unnormalized_in_db(self, loud_audio_path):
"""Unnormalized envelope should be in dB."""
analyzer = AudioAnalyzer()
envelope = analyzer.get_amplitude_envelope(
loud_audio_path, normalize=False
)
# dB values should be negative (below full scale)
assert all(v <= 0 for v in envelope)
# Most values should be above -60dB for loud audio
assert sum(1 for v in envelope if v > -60) > len(envelope) * 0.5
class TestEdgeCases:
"""Tests for edge cases and error handling."""
def test_nonexistent_file_raises_error(self):
"""Analyzing non-existent file should raise FileNotFoundError."""
analyzer = AudioAnalyzer()
with pytest.raises(FileNotFoundError):
analyzer.analyze("/nonexistent/path/to/audio.flac")
def test_stereo_audio_handled(self, stereo_audio_path):
"""Stereo audio should be converted to mono and analyzed."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(stereo_audio_path)
# Should not raise and should detect content
assert result.has_audible_content is True
def test_total_duration_accurate(self, mixed_audio_path):
"""Total duration should match audio file duration."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(mixed_audio_path)
# Mixed audio is 10 seconds
assert abs(result.total_duration_seconds - 10.0) < 0.5
class TestAnalysisResultMethods:
"""Tests for AnalysisResult methods."""
def test_segment_count_property(self, mixed_audio_path):
"""segment_count should return number of segments."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(mixed_audio_path)
assert result.segment_count == len(result.audible_segments)
def test_get_segments_in_range(self, mixed_audio_path):
"""get_segments_in_range should filter segments correctly."""
analyzer = AudioAnalyzer()
result = analyzer.analyze(mixed_audio_path)
# Get segments in the first 5 seconds
segments_in_range = result.get_segments_in_range(0, 5)
# All returned segments should overlap with [0, 5]
for seg in segments_in_range:
assert not (seg.end_seconds <= 0 or seg.start_seconds >= 5)
@@ -0,0 +1,416 @@
"""
Unit tests for AudioEditor.
Tests cover:
- Muting single and multiple regions
- Region boundary handling
- Custom instrumental creation
- Region normalization and merging
- Error handling
"""
import os
import pytest
from pydub import AudioSegment
from karaoke_gen.instrumental_review import (
AudioEditor,
MuteRegion,
)
from karaoke_gen.instrumental_review.models import CustomInstrumentalResult
class TestAudioEditorInit:
"""Tests for AudioEditor initialization."""
def test_default_output_format(self):
"""Test editor creates with FLAC as default format."""
editor = AudioEditor()
assert editor.output_format == "flac"
def test_custom_output_format(self):
"""Test editor accepts custom output format."""
editor = AudioEditor(output_format="wav")
assert editor.output_format == "wav"
class TestMuteRegionModel:
"""Tests for MuteRegion model."""
def test_duration_property(self):
"""Test duration_seconds property calculation."""
region = MuteRegion(start_seconds=1.0, end_seconds=3.0)
assert region.duration_seconds == 2.0
def test_overlaps_returns_true_for_overlapping(self):
"""Test overlaps method for overlapping regions."""
region1 = MuteRegion(start_seconds=1.0, end_seconds=3.0)
region2 = MuteRegion(start_seconds=2.0, end_seconds=4.0)
assert region1.overlaps(region2) is True
assert region2.overlaps(region1) is True
def test_overlaps_returns_false_for_non_overlapping(self):
"""Test overlaps method for non-overlapping regions."""
region1 = MuteRegion(start_seconds=1.0, end_seconds=2.0)
region2 = MuteRegion(start_seconds=3.0, end_seconds=4.0)
assert region1.overlaps(region2) is False
assert region2.overlaps(region1) is False
def test_overlaps_edge_case_adjacent(self):
"""Test overlaps method for adjacent regions (touching but not overlapping)."""
region1 = MuteRegion(start_seconds=1.0, end_seconds=2.0)
region2 = MuteRegion(start_seconds=2.0, end_seconds=3.0)
# Adjacent regions should not be considered overlapping
assert region1.overlaps(region2) is False
def test_merge_regions(self):
"""Test merge method combines overlapping regions."""
region1 = MuteRegion(start_seconds=1.0, end_seconds=3.0)
region2 = MuteRegion(start_seconds=2.0, end_seconds=4.0)
merged = region1.merge(region2)
assert merged.start_seconds == 1.0
assert merged.end_seconds == 4.0
class TestMuteSingleRegion:
"""Tests for muting a single region."""
def test_mute_single_region_creates_output(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Muting a single region should create output file."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
mute_regions = [MuteRegion(start_seconds=2.0, end_seconds=4.0)]
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
assert os.path.exists(output_path)
assert result.output_path == output_path
def test_mute_single_region_duration_correct(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Output duration should match input duration."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
mute_regions = [MuteRegion(start_seconds=2.0, end_seconds=4.0)]
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
# Check output duration (should be ~10 seconds)
output_audio = AudioSegment.from_file(output_path)
assert abs(len(output_audio) / 1000.0 - 10.0) < 0.5
def test_mute_region_statistics(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Result should include correct mute statistics."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
mute_regions = [MuteRegion(start_seconds=2.0, end_seconds=4.0)]
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
assert len(result.mute_regions_applied) == 1
assert result.total_muted_duration_seconds == 2.0
class TestMuteMultipleRegions:
"""Tests for muting multiple regions."""
def test_mute_multiple_regions(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Multiple mute regions should all be applied."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
mute_regions = [
MuteRegion(start_seconds=1.0, end_seconds=2.0),
MuteRegion(start_seconds=5.0, end_seconds=6.0),
MuteRegion(start_seconds=8.0, end_seconds=9.0),
]
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
assert os.path.exists(output_path)
assert len(result.mute_regions_applied) == 3
assert result.total_muted_duration_seconds == 3.0
def test_overlapping_regions_are_merged(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Overlapping mute regions should be merged."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
# These overlap: [1-3] and [2-4] should become [1-4]
mute_regions = [
MuteRegion(start_seconds=1.0, end_seconds=3.0),
MuteRegion(start_seconds=2.0, end_seconds=4.0),
]
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
# Should be merged into 1 region
assert len(result.mute_regions_applied) == 1
assert result.mute_regions_applied[0].start_seconds == 1.0
assert result.mute_regions_applied[0].end_seconds == 4.0
class TestMuteRegionBoundaries:
"""Tests for mute region boundary handling."""
def test_mute_at_start(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Muting at the start of audio should work."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
mute_regions = [MuteRegion(start_seconds=0.0, end_seconds=2.0)]
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
assert os.path.exists(output_path)
assert result.total_muted_duration_seconds == 2.0
def test_mute_at_end(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Muting at the end of audio should work."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
mute_regions = [MuteRegion(start_seconds=8.0, end_seconds=10.0)]
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
assert os.path.exists(output_path)
def test_mute_region_clamped_to_audio_length(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Mute region extending beyond audio should be clamped."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
# Region extends beyond 10 second audio
mute_regions = [MuteRegion(start_seconds=8.0, end_seconds=15.0)]
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
# Should not raise error
assert os.path.exists(output_path)
class TestCustomInstrumentalCombination:
"""Tests for combining clean instrumental with muted backing vocals."""
def test_output_combines_both_tracks(
self, clean_instrumental_path, mixed_audio_path, temp_dir
):
"""Output should be combination of clean instrumental and edited backing."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
mute_regions = [MuteRegion(start_seconds=3.0, end_seconds=5.0)]
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=mixed_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
assert os.path.exists(output_path)
output_audio = AudioSegment.from_file(output_path)
# Output should be stereo or have similar properties
assert len(output_audio) > 0
def test_no_mute_regions_still_combines(
self, clean_instrumental_path, mixed_audio_path, temp_dir
):
"""Empty mute regions should still combine tracks."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
result = editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=mixed_audio_path,
mute_regions=[],
output_path=output_path,
)
assert os.path.exists(output_path)
assert len(result.mute_regions_applied) == 0
class TestApplyMuteToSingleTrack:
"""Tests for apply_mute_to_single_track method."""
def test_mute_single_track(self, loud_audio_path, temp_dir):
"""Should mute regions in a single track."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "muted_backing.flac")
mute_regions = [MuteRegion(start_seconds=2.0, end_seconds=4.0)]
result_path = editor.apply_mute_to_single_track(
audio_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
assert os.path.exists(result_path)
assert result_path == output_path
class TestErrorHandling:
"""Tests for error handling."""
def test_nonexistent_clean_instrumental_raises_error(
self, loud_audio_path, temp_dir
):
"""Non-existent clean instrumental should raise FileNotFoundError."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
with pytest.raises(FileNotFoundError):
editor.create_custom_instrumental(
clean_instrumental_path="/nonexistent/clean.flac",
backing_vocals_path=loud_audio_path,
mute_regions=[],
output_path=output_path,
)
def test_nonexistent_backing_vocals_raises_error(
self, clean_instrumental_path, temp_dir
):
"""Non-existent backing vocals should raise FileNotFoundError."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
with pytest.raises(FileNotFoundError):
editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path="/nonexistent/backing.flac",
mute_regions=[],
output_path=output_path,
)
def test_invalid_region_start_raises_error(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Negative region start should raise ValidationError at model level."""
from pydantic import ValidationError
# Pydantic validates at model creation time
with pytest.raises(ValidationError):
MuteRegion(start_seconds=-1.0, end_seconds=2.0)
def test_invalid_region_end_before_start_raises_error(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Region end before start should raise ValueError."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "custom_instrumental.flac")
mute_regions = [MuteRegion(start_seconds=5.0, end_seconds=3.0)]
with pytest.raises(ValueError):
editor.create_custom_instrumental(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
class TestPreviewWithMutes:
"""Tests for preview_with_mutes method."""
def test_preview_returns_audio_segment(
self, clean_instrumental_path, loud_audio_path
):
"""Preview should return AudioSegment in memory."""
editor = AudioEditor()
mute_regions = [MuteRegion(start_seconds=2.0, end_seconds=4.0)]
preview = editor.preview_with_mutes(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
)
assert isinstance(preview, AudioSegment)
assert len(preview) > 0
def test_preview_can_save_to_file(
self, clean_instrumental_path, loud_audio_path, temp_dir
):
"""Preview should optionally save to file."""
editor = AudioEditor()
output_path = os.path.join(temp_dir, "preview.flac")
mute_regions = [MuteRegion(start_seconds=2.0, end_seconds=4.0)]
preview = editor.preview_with_mutes(
clean_instrumental_path=clean_instrumental_path,
backing_vocals_path=loud_audio_path,
mute_regions=mute_regions,
output_path=output_path,
)
assert os.path.exists(output_path)
@@ -0,0 +1,388 @@
"""
Unit tests for instrumental_review models.
Tests cover:
- Model creation and validation
- Property methods
- Serialization/deserialization
- Edge cases
"""
import pytest
from pydantic import ValidationError
from karaoke_gen.instrumental_review import (
AnalysisResult,
AudibleSegment,
MuteRegion,
RecommendedSelection,
)
from karaoke_gen.instrumental_review.models import CustomInstrumentalResult
class TestRecommendedSelection:
"""Tests for RecommendedSelection enum."""
def test_enum_values(self):
"""Test enum has expected values."""
assert RecommendedSelection.CLEAN.value == "clean"
assert RecommendedSelection.WITH_BACKING.value == "with_backing"
assert RecommendedSelection.REVIEW_NEEDED.value == "review_needed"
def test_enum_from_string(self):
"""Test creating enum from string value."""
assert RecommendedSelection("clean") == RecommendedSelection.CLEAN
assert RecommendedSelection("with_backing") == RecommendedSelection.WITH_BACKING
assert RecommendedSelection("review_needed") == RecommendedSelection.REVIEW_NEEDED
class TestAudibleSegment:
"""Tests for AudibleSegment model."""
def test_create_valid_segment(self):
"""Test creating a valid audible segment."""
segment = AudibleSegment(
start_seconds=1.0,
end_seconds=3.0,
duration_seconds=2.0,
avg_amplitude_db=-15.0,
)
assert segment.start_seconds == 1.0
assert segment.end_seconds == 3.0
assert segment.duration_seconds == 2.0
assert segment.avg_amplitude_db == -15.0
def test_default_peak_amplitude(self):
"""Test default peak amplitude is 0.0."""
segment = AudibleSegment(
start_seconds=0.0,
end_seconds=1.0,
duration_seconds=1.0,
avg_amplitude_db=-20.0,
)
assert segment.peak_amplitude_db == 0.0
def test_is_loud_property_true(self):
"""Test is_loud returns True for loud segments."""
segment = AudibleSegment(
start_seconds=0.0,
end_seconds=1.0,
duration_seconds=1.0,
avg_amplitude_db=-15.0, # Louder than -20dB
)
assert segment.is_loud is True
def test_is_loud_property_false(self):
"""Test is_loud returns False for quiet segments."""
segment = AudibleSegment(
start_seconds=0.0,
end_seconds=1.0,
duration_seconds=1.0,
avg_amplitude_db=-25.0, # Quieter than -20dB
)
assert segment.is_loud is False
def test_negative_start_invalid(self):
"""Test negative start_seconds is invalid."""
with pytest.raises(ValidationError):
AudibleSegment(
start_seconds=-1.0,
end_seconds=1.0,
duration_seconds=2.0,
avg_amplitude_db=-15.0,
)
def test_negative_duration_invalid(self):
"""Test negative duration_seconds is invalid."""
with pytest.raises(ValidationError):
AudibleSegment(
start_seconds=0.0,
end_seconds=1.0,
duration_seconds=-1.0,
avg_amplitude_db=-15.0,
)
def test_serialization_to_dict(self):
"""Test segment can be serialized to dict."""
segment = AudibleSegment(
start_seconds=1.0,
end_seconds=3.0,
duration_seconds=2.0,
avg_amplitude_db=-15.0,
peak_amplitude_db=-10.0,
)
data = segment.model_dump()
assert data["start_seconds"] == 1.0
assert data["end_seconds"] == 3.0
assert data["duration_seconds"] == 2.0
assert data["avg_amplitude_db"] == -15.0
assert data["peak_amplitude_db"] == -10.0
class TestMuteRegion:
"""Tests for MuteRegion model."""
def test_create_valid_region(self):
"""Test creating a valid mute region."""
region = MuteRegion(start_seconds=1.0, end_seconds=3.0)
assert region.start_seconds == 1.0
assert region.end_seconds == 3.0
def test_duration_property(self):
"""Test duration_seconds property."""
region = MuteRegion(start_seconds=1.0, end_seconds=3.0)
assert region.duration_seconds == 2.0
def test_overlaps_method(self):
"""Test overlaps method with overlapping regions."""
region1 = MuteRegion(start_seconds=1.0, end_seconds=3.0)
region2 = MuteRegion(start_seconds=2.0, end_seconds=4.0)
assert region1.overlaps(region2) is True
def test_overlaps_method_no_overlap(self):
"""Test overlaps method with non-overlapping regions."""
region1 = MuteRegion(start_seconds=1.0, end_seconds=2.0)
region2 = MuteRegion(start_seconds=3.0, end_seconds=4.0)
assert region1.overlaps(region2) is False
def test_overlaps_contained(self):
"""Test overlaps when one region contains another."""
region1 = MuteRegion(start_seconds=1.0, end_seconds=5.0)
region2 = MuteRegion(start_seconds=2.0, end_seconds=3.0)
assert region1.overlaps(region2) is True
assert region2.overlaps(region1) is True
def test_merge_method(self):
"""Test merge method creates combined region."""
region1 = MuteRegion(start_seconds=1.0, end_seconds=3.0)
region2 = MuteRegion(start_seconds=2.0, end_seconds=4.0)
merged = region1.merge(region2)
assert merged.start_seconds == 1.0
assert merged.end_seconds == 4.0
def test_negative_start_invalid(self):
"""Test negative start_seconds is invalid."""
with pytest.raises(ValidationError):
MuteRegion(start_seconds=-1.0, end_seconds=1.0)
def test_serialization_to_dict(self):
"""Test region can be serialized to dict."""
region = MuteRegion(start_seconds=1.0, end_seconds=3.0)
data = region.model_dump()
assert data["start_seconds"] == 1.0
assert data["end_seconds"] == 3.0
class TestAnalysisResult:
"""Tests for AnalysisResult model."""
def test_create_valid_result(self):
"""Test creating a valid analysis result."""
result = AnalysisResult(
has_audible_content=True,
total_duration_seconds=120.0,
audible_segments=[],
recommended_selection=RecommendedSelection.REVIEW_NEEDED,
)
assert result.has_audible_content is True
assert result.total_duration_seconds == 120.0
assert result.recommended_selection == RecommendedSelection.REVIEW_NEEDED
def test_default_values(self):
"""Test default values are set correctly."""
result = AnalysisResult(
has_audible_content=False,
total_duration_seconds=60.0,
recommended_selection=RecommendedSelection.CLEAN,
)
assert result.audible_segments == []
assert result.silence_threshold_db == -40.0
assert result.total_audible_duration_seconds == 0.0
assert result.audible_percentage == 0.0
assert result.waveform_data is None
def test_segment_count_property(self):
"""Test segment_count property."""
segments = [
AudibleSegment(
start_seconds=0.0, end_seconds=1.0,
duration_seconds=1.0, avg_amplitude_db=-15.0
),
AudibleSegment(
start_seconds=2.0, end_seconds=3.0,
duration_seconds=1.0, avg_amplitude_db=-15.0
),
]
result = AnalysisResult(
has_audible_content=True,
total_duration_seconds=10.0,
audible_segments=segments,
recommended_selection=RecommendedSelection.REVIEW_NEEDED,
)
assert result.segment_count == 2
def test_get_segments_in_range(self):
"""Test get_segments_in_range method."""
segments = [
AudibleSegment(
start_seconds=1.0, end_seconds=2.0,
duration_seconds=1.0, avg_amplitude_db=-15.0
),
AudibleSegment(
start_seconds=5.0, end_seconds=6.0,
duration_seconds=1.0, avg_amplitude_db=-15.0
),
AudibleSegment(
start_seconds=8.0, end_seconds=9.0,
duration_seconds=1.0, avg_amplitude_db=-15.0
),
]
result = AnalysisResult(
has_audible_content=True,
total_duration_seconds=10.0,
audible_segments=segments,
recommended_selection=RecommendedSelection.REVIEW_NEEDED,
)
# Get segments between 0-3 seconds
in_range = result.get_segments_in_range(0.0, 3.0)
assert len(in_range) == 1
assert in_range[0].start_seconds == 1.0
def test_get_segments_in_range_partial_overlap(self):
"""Test get_segments_in_range with partial overlap."""
segments = [
AudibleSegment(
start_seconds=2.0, end_seconds=6.0,
duration_seconds=4.0, avg_amplitude_db=-15.0
),
]
result = AnalysisResult(
has_audible_content=True,
total_duration_seconds=10.0,
audible_segments=segments,
recommended_selection=RecommendedSelection.REVIEW_NEEDED,
)
# Segment overlaps with range [4, 8]
in_range = result.get_segments_in_range(4.0, 8.0)
assert len(in_range) == 1
def test_audible_percentage_validation(self):
"""Test audible_percentage must be 0-100."""
with pytest.raises(ValidationError):
AnalysisResult(
has_audible_content=True,
total_duration_seconds=60.0,
recommended_selection=RecommendedSelection.CLEAN,
audible_percentage=150.0, # Invalid
)
def test_serialization_to_dict(self):
"""Test result can be serialized to dict."""
segments = [
AudibleSegment(
start_seconds=1.0, end_seconds=2.0,
duration_seconds=1.0, avg_amplitude_db=-15.0
),
]
result = AnalysisResult(
has_audible_content=True,
total_duration_seconds=60.0,
audible_segments=segments,
recommended_selection=RecommendedSelection.REVIEW_NEEDED,
total_audible_duration_seconds=1.0,
audible_percentage=1.67,
)
data = result.model_dump()
assert data["has_audible_content"] is True
assert data["total_duration_seconds"] == 60.0
assert len(data["audible_segments"]) == 1
assert data["recommended_selection"] == "review_needed"
def test_serialization_to_json(self):
"""Test result can be serialized to JSON."""
result = AnalysisResult(
has_audible_content=False,
total_duration_seconds=60.0,
recommended_selection=RecommendedSelection.CLEAN,
)
json_str = result.model_dump_json()
assert '"has_audible_content":false' in json_str.lower().replace(" ", "")
assert '"recommended_selection":"clean"' in json_str.lower().replace(" ", "")
class TestCustomInstrumentalResult:
"""Tests for CustomInstrumentalResult model."""
def test_create_valid_result(self):
"""Test creating a valid custom instrumental result."""
mute_regions = [
MuteRegion(start_seconds=1.0, end_seconds=2.0),
]
result = CustomInstrumentalResult(
output_path="/path/to/custom.flac",
mute_regions_applied=mute_regions,
total_muted_duration_seconds=1.0,
output_duration_seconds=60.0,
)
assert result.output_path == "/path/to/custom.flac"
assert len(result.mute_regions_applied) == 1
assert result.total_muted_duration_seconds == 1.0
assert result.output_duration_seconds == 60.0
def test_default_values(self):
"""Test default values are set correctly."""
result = CustomInstrumentalResult(
output_path="/path/to/output.flac",
)
assert result.mute_regions_applied == []
assert result.total_muted_duration_seconds == 0.0
assert result.output_duration_seconds == 0.0
def test_serialization_to_dict(self):
"""Test result can be serialized to dict."""
result = CustomInstrumentalResult(
output_path="/path/to/custom.flac",
mute_regions_applied=[
MuteRegion(start_seconds=1.0, end_seconds=2.0),
],
total_muted_duration_seconds=1.0,
output_duration_seconds=60.0,
)
data = result.model_dump()
assert data["output_path"] == "/path/to/custom.flac"
assert len(data["mute_regions_applied"]) == 1
@@ -0,0 +1,535 @@
"""
Unit tests for the InstrumentalReviewServer module.
Tests the local FastAPI server for instrumental review, including:
- Server initialization
- Request/Response models
- API endpoint logic
"""
import os
import pytest
import tempfile
from pathlib import Path
from unittest.mock import MagicMock, patch, AsyncMock
from karaoke_gen.instrumental_review.server import (
InstrumentalReviewServer,
MuteRegionRequest,
CreateCustomRequest,
SelectionRequest,
)
from karaoke_gen.instrumental_review import (
AnalysisResult,
AudibleSegment,
RecommendedSelection,
)
class TestRequestModels:
"""Test Pydantic request models."""
def test_mute_region_request_valid(self):
"""Test creating a valid MuteRegionRequest."""
region = MuteRegionRequest(start_seconds=1.0, end_seconds=2.0)
assert region.start_seconds == 1.0
assert region.end_seconds == 2.0
def test_mute_region_request_negative_values(self):
"""Test MuteRegionRequest accepts negative values (validation elsewhere)."""
region = MuteRegionRequest(start_seconds=-1.0, end_seconds=2.0)
assert region.start_seconds == -1.0
def test_create_custom_request_valid(self):
"""Test creating a valid CreateCustomRequest."""
request = CreateCustomRequest(
mute_regions=[
MuteRegionRequest(start_seconds=1.0, end_seconds=2.0),
MuteRegionRequest(start_seconds=5.0, end_seconds=6.0),
]
)
assert len(request.mute_regions) == 2
def test_create_custom_request_empty(self):
"""Test CreateCustomRequest with empty mute_regions."""
request = CreateCustomRequest(mute_regions=[])
assert len(request.mute_regions) == 0
def test_selection_request_valid(self):
"""Test creating a valid SelectionRequest."""
request = SelectionRequest(selection="clean")
assert request.selection == "clean"
def test_selection_request_any_string(self):
"""Test SelectionRequest accepts any string (validation in endpoint)."""
request = SelectionRequest(selection="invalid")
assert request.selection == "invalid"
class TestServerInitialization:
"""Test InstrumentalReviewServer initialization."""
@pytest.fixture
def mock_analysis(self):
"""Create a mock analysis result."""
return AnalysisResult(
has_audible_content=True,
total_duration_seconds=180.0,
audible_segments=[
AudibleSegment(
start_seconds=10.0,
end_seconds=15.0,
duration_seconds=5.0,
avg_amplitude_db=-30.0,
peak_amplitude_db=-25.0,
)
],
recommended_selection=RecommendedSelection.REVIEW_NEEDED,
total_audible_duration_seconds=5.0,
audible_percentage=2.78,
silence_threshold_db=-40.0,
)
@pytest.fixture
def temp_files(self, tmp_path):
"""Create temporary audio files for testing."""
backing = tmp_path / "backing.flac"
clean = tmp_path / "clean.flac"
waveform = tmp_path / "waveform.png"
backing.write_bytes(b"fake audio")
clean.write_bytes(b"fake audio")
waveform.write_bytes(b"fake png")
return {
"output_dir": str(tmp_path),
"backing_vocals_path": str(backing),
"clean_instrumental_path": str(clean),
"waveform_path": str(waveform),
}
def test_server_initialization(self, mock_analysis, temp_files):
"""Test server initializes with all required parameters."""
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
assert server.output_dir == temp_files["output_dir"]
assert server.base_name == "Artist - Title"
assert server.analysis == mock_analysis
assert server.backing_vocals_path == temp_files["backing_vocals_path"]
assert server.clean_instrumental_path == temp_files["clean_instrumental_path"]
assert server.waveform_path == temp_files["waveform_path"]
assert server.with_backing_path is None
assert server.custom_instrumental_path is None
assert server.selection is None
def test_server_initialization_with_optional_paths(self, mock_analysis, temp_files):
"""Test server initializes with optional with_backing_path."""
with_backing = Path(temp_files["output_dir"]) / "with_backing.flac"
with_backing.write_bytes(b"fake audio")
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
with_backing_path=str(with_backing),
)
assert server.with_backing_path == str(with_backing)
def test_get_selection_raises_without_selection(self, mock_analysis, temp_files):
"""Test get_selection raises when no selection made."""
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
with pytest.raises(ValueError, match="No selection has been made"):
server.get_selection()
def test_get_selection_returns_selection(self, mock_analysis, temp_files):
"""Test get_selection returns the selection after it's set."""
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
server.selection = "clean"
assert server.get_selection() == "clean"
def test_get_custom_instrumental_path_none_by_default(self, mock_analysis, temp_files):
"""Test custom instrumental path is None by default."""
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
assert server.get_custom_instrumental_path() is None
def test_get_custom_instrumental_path_returns_path(self, mock_analysis, temp_files):
"""Test custom instrumental path is returned when set."""
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
server.custom_instrumental_path = "/path/to/custom.flac"
assert server.get_custom_instrumental_path() == "/path/to/custom.flac"
class TestServerAppCreation:
"""Test FastAPI app creation and routes."""
@pytest.fixture
def mock_analysis(self):
"""Create a mock analysis result."""
return AnalysisResult(
has_audible_content=True,
total_duration_seconds=180.0,
audible_segments=[],
recommended_selection=RecommendedSelection.CLEAN,
total_audible_duration_seconds=0.0,
audible_percentage=0.0,
silence_threshold_db=-40.0,
)
@pytest.fixture
def temp_files(self, tmp_path):
"""Create temporary files."""
backing = tmp_path / "backing.flac"
clean = tmp_path / "clean.flac"
waveform = tmp_path / "waveform.png"
backing.write_bytes(b"fake audio")
clean.write_bytes(b"fake audio")
waveform.write_bytes(b"fake png")
return {
"output_dir": str(tmp_path),
"backing_vocals_path": str(backing),
"clean_instrumental_path": str(clean),
"waveform_path": str(waveform),
}
def test_create_app_returns_fastapi_app(self, mock_analysis, temp_files):
"""Test _create_app returns a FastAPI application."""
from fastapi import FastAPI
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
app = server._create_app()
assert isinstance(app, FastAPI)
def test_app_has_cors_middleware(self, mock_analysis, temp_files):
"""Test app has CORS middleware configured."""
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
app = server._create_app()
# Check middleware is configured (FastAPI stores middleware in user_middleware)
middleware_classes = [m.cls.__name__ for m in app.user_middleware]
assert "CORSMiddleware" in middleware_classes
def test_get_frontend_html_returns_string(self, mock_analysis, temp_files):
"""Test _get_frontend_html returns HTML string."""
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
html = server._get_frontend_html()
assert isinstance(html, str)
assert "<!DOCTYPE html>" in html
assert "Instrumental Review" in html
def test_get_frontend_html_contains_required_elements(self, mock_analysis, temp_files):
"""Test frontend HTML contains all required UI elements."""
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
html = server._get_frontend_html()
# Check for key UI components
assert "waveform" in html.lower()
assert "audio" in html.lower()
assert "mute" in html.lower()
assert "selection" in html.lower()
assert "clean" in html.lower()
class TestServerStop:
"""Test server stop functionality."""
@pytest.fixture
def mock_analysis(self):
"""Create a mock analysis result."""
return AnalysisResult(
has_audible_content=False,
total_duration_seconds=180.0,
audible_segments=[],
recommended_selection=RecommendedSelection.CLEAN,
total_audible_duration_seconds=0.0,
audible_percentage=0.0,
silence_threshold_db=-40.0,
)
@pytest.fixture
def temp_files(self, tmp_path):
"""Create temporary files."""
backing = tmp_path / "backing.flac"
clean = tmp_path / "clean.flac"
waveform = tmp_path / "waveform.png"
backing.write_bytes(b"fake audio")
clean.write_bytes(b"fake audio")
waveform.write_bytes(b"fake png")
return {
"output_dir": str(tmp_path),
"backing_vocals_path": str(backing),
"clean_instrumental_path": str(clean),
"waveform_path": str(waveform),
}
def test_stop_sets_shutdown_event(self, mock_analysis, temp_files):
"""Test stop() sets the shutdown event."""
server = InstrumentalReviewServer(
output_dir=temp_files["output_dir"],
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=temp_files["waveform_path"],
backing_vocals_path=temp_files["backing_vocals_path"],
clean_instrumental_path=temp_files["clean_instrumental_path"],
)
assert not server._shutdown_event.is_set()
server.stop()
assert server._shutdown_event.is_set()
class TestServerAPIEndpoints:
"""Test FastAPI endpoint handlers using TestClient."""
@pytest.fixture
def mock_analysis(self):
"""Create a mock analysis result."""
return AnalysisResult(
has_audible_content=True,
total_duration_seconds=180.0,
audible_segments=[
AudibleSegment(
start_seconds=10.0,
end_seconds=15.0,
duration_seconds=5.0,
avg_amplitude_db=-30.0,
peak_amplitude_db=-25.0,
)
],
recommended_selection=RecommendedSelection.REVIEW_NEEDED,
total_audible_duration_seconds=5.0,
audible_percentage=2.78,
silence_threshold_db=-40.0,
)
@pytest.fixture
def server_with_files(self, tmp_path, mock_analysis):
"""Create server with real temp files."""
from pydub import AudioSegment
from pydub.generators import Sine
# Create a real audio file for testing
audio = Sine(440).to_audio_segment(duration=1000) # 1 second of 440Hz sine
backing = tmp_path / "backing.flac"
clean = tmp_path / "clean.flac"
waveform = tmp_path / "waveform.png"
audio.export(str(backing), format="flac")
audio.export(str(clean), format="flac")
waveform.write_bytes(b"\x89PNG\r\n\x1a\n") # PNG magic bytes
server = InstrumentalReviewServer(
output_dir=str(tmp_path),
base_name="Artist - Title",
analysis=mock_analysis,
waveform_path=str(waveform),
backing_vocals_path=str(backing),
clean_instrumental_path=str(clean),
)
return server
@pytest.fixture
def client(self, server_with_files):
"""Create TestClient for the server."""
from fastapi.testclient import TestClient
app = server_with_files._create_app()
return TestClient(app)
def test_root_returns_html(self, client):
"""Test root endpoint returns HTML page."""
response = client.get("/")
assert response.status_code == 200
assert "text/html" in response.headers["content-type"]
assert "Instrumental Review" in response.text
def test_get_analysis_returns_data(self, client, mock_analysis):
"""Test analysis endpoint returns correct data."""
response = client.get("/api/jobs/local/instrumental-analysis")
assert response.status_code == 200
data = response.json()
assert data["job_id"] == "local"
assert data["status"] == "awaiting_instrumental_selection"
assert data["analysis"]["has_audible_content"] == True
assert data["analysis"]["total_duration_seconds"] == 180.0
assert len(data["analysis"]["audible_segments"]) == 1
assert data["audio_urls"]["backing_vocals"] is not None
assert data["audio_urls"]["clean_instrumental"] is not None
def test_get_waveform_data_returns_amplitudes(self, client):
"""Test waveform data endpoint returns amplitudes."""
response = client.get("/api/jobs/local/waveform-data?num_points=100")
assert response.status_code == 200
data = response.json()
assert "amplitudes" in data
assert "duration" in data
assert isinstance(data["amplitudes"], list)
assert len(data["amplitudes"]) == 100
def test_get_waveform_data_validates_num_points(self, client):
"""Test waveform data validates num_points parameter."""
# Test invalid num_points (0)
response = client.get("/api/jobs/local/waveform-data?num_points=0")
assert response.status_code == 400
assert "num_points must be between" in response.json()["detail"]
# Test invalid num_points (negative)
response = client.get("/api/jobs/local/waveform-data?num_points=-10")
assert response.status_code == 400
# Test invalid num_points (too large)
response = client.get("/api/jobs/local/waveform-data?num_points=100000")
assert response.status_code == 400
def test_stream_audio_returns_file(self, client):
"""Test audio streaming endpoint returns audio file."""
response = client.get("/api/audio/backing_vocals")
assert response.status_code == 200
assert "audio/flac" in response.headers["content-type"]
def test_stream_audio_invalid_type(self, client):
"""Test audio streaming with invalid stem type."""
response = client.get("/api/audio/invalid_type")
assert response.status_code == 404
def test_get_waveform_image(self, client):
"""Test waveform image endpoint."""
response = client.get("/api/waveform")
assert response.status_code == 200
assert "image/png" in response.headers["content-type"]
def test_select_instrumental_clean(self, client, server_with_files):
"""Test selecting clean instrumental."""
response = client.post(
"/api/jobs/local/select-instrumental",
json={"selection": "clean"}
)
assert response.status_code == 200
assert response.json()["status"] == "success"
assert server_with_files.selection == "clean"
def test_select_instrumental_with_backing(self, client, server_with_files):
"""Test selecting instrumental with backing vocals."""
response = client.post(
"/api/jobs/local/select-instrumental",
json={"selection": "with_backing"}
)
assert response.status_code == 200
assert server_with_files.selection == "with_backing"
def test_select_instrumental_invalid(self, client):
"""Test selecting invalid option."""
response = client.post(
"/api/jobs/local/select-instrumental",
json={"selection": "invalid"}
)
assert response.status_code == 400
assert "Invalid selection" in response.json()["detail"]
def test_create_custom_instrumental(self, client, server_with_files, tmp_path):
"""Test creating custom instrumental."""
response = client.post(
"/api/jobs/local/create-custom-instrumental",
json={
"mute_regions": [
{"start_seconds": 0.1, "end_seconds": 0.3},
]
}
)
assert response.status_code == 200
data = response.json()
assert data["status"] == "success"
assert data["custom_instrumental_url"] == "/api/audio/custom_instrumental"
assert server_with_files.custom_instrumental_path is not None
def test_create_custom_instrumental_empty_regions(self, client):
"""Test creating custom instrumental with no regions fails."""
response = client.post(
"/api/jobs/local/create-custom-instrumental",
json={"mute_regions": []}
)
assert response.status_code == 400
assert "No mute regions" in response.json()["detail"]
@@ -0,0 +1,415 @@
"""
Unit tests for WaveformGenerator.
Tests cover:
- Waveform image generation
- Segment highlighting
- Mute region highlighting
- Data-only generation
- Error handling
"""
import os
import pytest
from pathlib import Path
from karaoke_gen.instrumental_review import (
WaveformGenerator,
AudibleSegment,
MuteRegion,
)
class TestWaveformGeneratorInit:
"""Tests for WaveformGenerator initialization."""
def test_default_parameters(self):
"""Test generator creates with sensible defaults."""
generator = WaveformGenerator()
assert generator.width == 1200
assert generator.height == 200
assert generator.dpi == 100
assert generator.background_color == "#1a1a2e"
def test_custom_parameters(self):
"""Test generator accepts custom parameters."""
generator = WaveformGenerator(
width=800,
height=150,
background_color="#000000",
waveform_color="#00ff00",
dpi=150,
)
assert generator.width == 800
assert generator.height == 150
assert generator.background_color == "#000000"
assert generator.waveform_color == "#00ff00"
assert generator.dpi == 150
class TestWaveformImageGeneration:
"""Tests for waveform image generation."""
def test_generate_creates_image_file(self, loud_audio_path, temp_dir):
"""Generate should create a PNG image file."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
result = generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
)
assert os.path.exists(output_path)
assert result == output_path
def test_generate_output_is_png(self, loud_audio_path, temp_dir):
"""Generated file should be a valid PNG."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
)
# Check PNG magic bytes
with open(output_path, 'rb') as f:
header = f.read(8)
assert header[:4] == b'\x89PNG'
def test_generate_creates_parent_directories(self, loud_audio_path, temp_dir):
"""Generate should create parent directories if needed."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "subdir", "nested", "waveform.png")
generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
)
assert os.path.exists(output_path)
def test_generate_silent_audio(self, silent_audio_path, temp_dir):
"""Generate should work with silent audio."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
result = generator.generate(
audio_path=silent_audio_path,
output_path=output_path,
)
assert os.path.exists(output_path)
def test_generate_mixed_audio(self, mixed_audio_path, temp_dir):
"""Generate should work with mixed audio."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
result = generator.generate(
audio_path=mixed_audio_path,
output_path=output_path,
)
assert os.path.exists(output_path)
class TestSegmentHighlighting:
"""Tests for audible segment highlighting."""
def test_generate_with_segments(self, loud_audio_path, temp_dir):
"""Generate with segment highlights should work."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
segments = [
AudibleSegment(
start_seconds=2.0,
end_seconds=4.0,
duration_seconds=2.0,
avg_amplitude_db=-15.0,
),
AudibleSegment(
start_seconds=6.0,
end_seconds=8.0,
duration_seconds=2.0,
avg_amplitude_db=-20.0,
),
]
result = generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
segments=segments,
)
assert os.path.exists(output_path)
def test_generate_with_empty_segments(self, loud_audio_path, temp_dir):
"""Generate with empty segment list should work."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
result = generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
segments=[],
)
assert os.path.exists(output_path)
class TestMuteRegionHighlighting:
"""Tests for mute region highlighting."""
def test_generate_with_mute_regions(self, loud_audio_path, temp_dir):
"""Generate with mute region highlights should work."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
mute_regions = [
MuteRegion(start_seconds=3.0, end_seconds=5.0),
MuteRegion(start_seconds=7.0, end_seconds=8.0),
]
result = generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
mute_regions=mute_regions,
)
assert os.path.exists(output_path)
def test_generate_with_segments_and_mute_regions(
self, loud_audio_path, temp_dir
):
"""Generate with both segments and mute regions should work."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
segments = [
AudibleSegment(
start_seconds=2.0,
end_seconds=6.0,
duration_seconds=4.0,
avg_amplitude_db=-15.0,
),
]
mute_regions = [
MuteRegion(start_seconds=3.0, end_seconds=5.0),
]
result = generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
segments=segments,
mute_regions=mute_regions,
)
assert os.path.exists(output_path)
class TestTimeAxis:
"""Tests for time axis rendering."""
def test_generate_with_time_axis(self, loud_audio_path, temp_dir):
"""Generate with time axis should work."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
result = generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
show_time_axis=True,
)
assert os.path.exists(output_path)
def test_generate_without_time_axis(self, loud_audio_path, temp_dir):
"""Generate without time axis should work."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
result = generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
show_time_axis=False,
)
assert os.path.exists(output_path)
class TestDataOnlyGeneration:
"""Tests for data-only waveform generation."""
def test_generate_data_only_returns_tuple(self, loud_audio_path):
"""generate_data_only should return (amplitudes, duration) tuple."""
generator = WaveformGenerator()
result = generator.generate_data_only(loud_audio_path)
assert isinstance(result, tuple)
assert len(result) == 2
def test_generate_data_only_amplitudes_are_list(self, loud_audio_path):
"""Amplitudes should be a list of floats."""
generator = WaveformGenerator()
amplitudes, duration = generator.generate_data_only(loud_audio_path)
assert isinstance(amplitudes, list)
assert all(isinstance(v, float) for v in amplitudes)
def test_generate_data_only_duration_is_float(self, loud_audio_path):
"""Duration should be a float."""
generator = WaveformGenerator()
amplitudes, duration = generator.generate_data_only(loud_audio_path)
assert isinstance(duration, float)
# 10 second audio
assert abs(duration - 10.0) < 0.5
def test_generate_data_only_respects_num_points(self, loud_audio_path):
"""num_points should control number of data points."""
generator = WaveformGenerator()
amplitudes_100, _ = generator.generate_data_only(
loud_audio_path, num_points=100
)
amplitudes_500, _ = generator.generate_data_only(
loud_audio_path, num_points=500
)
# Should be close to requested (may vary slightly due to rounding)
assert len(amplitudes_100) >= 90
assert len(amplitudes_100) <= 110
assert len(amplitudes_500) >= 450
assert len(amplitudes_500) <= 550
def test_generate_data_only_normalized(self, loud_audio_path):
"""Amplitudes should be normalized to 0-1 range."""
generator = WaveformGenerator()
amplitudes, _ = generator.generate_data_only(loud_audio_path)
assert all(0.0 <= v <= 1.0 for v in amplitudes)
class TestStereoHandling:
"""Tests for stereo audio handling."""
def test_generate_handles_stereo(self, stereo_audio_path, temp_dir):
"""Generate should handle stereo audio correctly."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
result = generator.generate(
audio_path=stereo_audio_path,
output_path=output_path,
)
assert os.path.exists(output_path)
def test_generate_data_only_handles_stereo(self, stereo_audio_path):
"""generate_data_only should handle stereo audio."""
generator = WaveformGenerator()
amplitudes, duration = generator.generate_data_only(stereo_audio_path)
assert len(amplitudes) > 0
assert duration > 0
class TestErrorHandling:
"""Tests for error handling."""
def test_nonexistent_file_raises_error(self, temp_dir):
"""Non-existent audio file should raise FileNotFoundError."""
generator = WaveformGenerator()
output_path = os.path.join(temp_dir, "waveform.png")
with pytest.raises(FileNotFoundError):
generator.generate(
audio_path="/nonexistent/audio.flac",
output_path=output_path,
)
def test_generate_data_only_nonexistent_raises_error(self):
"""generate_data_only with non-existent file should raise."""
generator = WaveformGenerator()
with pytest.raises(FileNotFoundError):
generator.generate_data_only("/nonexistent/audio.flac")
class TestCustomColors:
"""Tests for custom color configuration."""
def test_custom_colors_applied(self, loud_audio_path, temp_dir):
"""Custom colors should be applied without error."""
generator = WaveformGenerator(
background_color="#ffffff",
waveform_color="#ff0000",
segment_color="#00ff00",
mute_color="#0000ff",
time_axis_color="#000000",
)
output_path = os.path.join(temp_dir, "waveform.png")
segments = [
AudibleSegment(
start_seconds=2.0,
end_seconds=4.0,
duration_seconds=2.0,
avg_amplitude_db=-15.0,
),
]
mute_regions = [
MuteRegion(start_seconds=6.0, end_seconds=8.0),
]
result = generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
segments=segments,
mute_regions=mute_regions,
)
assert os.path.exists(output_path)
class TestCustomDimensions:
"""Tests for custom image dimensions."""
def test_different_widths(self, loud_audio_path, temp_dir):
"""Different widths should work."""
for width in [600, 1200, 1920]:
generator = WaveformGenerator(width=width)
output_path = os.path.join(temp_dir, f"waveform_{width}.png")
generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
)
assert os.path.exists(output_path)
def test_different_heights(self, loud_audio_path, temp_dir):
"""Different heights should work."""
for height in [100, 200, 300]:
generator = WaveformGenerator(height=height)
output_path = os.path.join(temp_dir, f"waveform_{height}.png")
generator.generate(
audio_path=loud_audio_path,
output_path=output_path,
)
assert os.path.exists(output_path)
+441
View File
@@ -0,0 +1,441 @@
"""
Unit tests for run_instrumental_review function.
These tests verify that run_instrumental_review correctly integrates:
- AudioAnalyzer
- WaveformGenerator
- InstrumentalReviewServer
Importantly, these tests verify that the correct parameter names are used
when calling the underlying components, which caught the 'audible_segments'
vs 'segments' parameter name bug.
"""
import pytest
import os
import logging
from unittest.mock import MagicMock, patch, PropertyMock
from karaoke_gen.instrumental_review import (
AnalysisResult,
RecommendedSelection,
AudibleSegment,
)
class TestRunInstrumentalReviewIntegration:
"""Tests for run_instrumental_review that verify component integration."""
@pytest.fixture
def mock_logger(self):
"""Create a mock logger."""
logger = MagicMock(spec=logging.Logger)
return logger
@pytest.fixture
def sample_analysis(self):
"""Create a sample AnalysisResult."""
return AnalysisResult(
has_audible_content=True,
total_duration_seconds=180.0,
audible_segments=[
AudibleSegment(
start_seconds=10.0,
end_seconds=20.0,
duration_seconds=10.0,
avg_amplitude_db=-25.0,
),
AudibleSegment(
start_seconds=60.0,
end_seconds=75.0,
duration_seconds=15.0,
avg_amplitude_db=-22.0,
),
],
recommended_selection=RecommendedSelection.REVIEW_NEEDED,
silence_threshold_db=-40.0,
)
@pytest.fixture
def sample_track(self, tmp_path):
"""Create a sample track dictionary with test files."""
# Create fake files
stems_dir = tmp_path / "stems"
stems_dir.mkdir()
backing_vocals = stems_dir / "Test - Song (Backing Vocals model.ckpt).flac"
backing_vocals.touch()
clean_instrumental = tmp_path / "Test - Song (Instrumental model.ckpt).flac"
clean_instrumental.touch()
combined_instrumental = tmp_path / "Test - Song (Instrumental +BV model.ckpt).flac"
combined_instrumental.touch()
return {
"artist": "Test",
"title": "Song",
"track_output_dir": str(tmp_path),
"separated_audio": {
"backing_vocals": {
"model.ckpt": {
"backing_vocals": str(backing_vocals),
}
},
"clean_instrumental": {
"instrumental": str(clean_instrumental),
},
"combined_instrumentals": {
"model.ckpt": str(combined_instrumental),
},
},
}
def test_waveform_generator_called_with_correct_param_names(
self, sample_track, sample_analysis, mock_logger, tmp_path
):
"""
CRITICAL TEST: Verify WaveformGenerator.generate() is called with
'segments' parameter, NOT 'audible_segments'.
This test would have caught the bug where 'audible_segments' was
incorrectly used instead of 'segments'.
"""
from karaoke_gen.utils.gen_cli import run_instrumental_review
# Change to the track directory (simulating gen_cli behavior)
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
with patch('karaoke_gen.utils.gen_cli.AudioAnalyzer') as MockAnalyzer, \
patch('karaoke_gen.utils.gen_cli.WaveformGenerator') as MockWaveformGen, \
patch('karaoke_gen.utils.gen_cli.InstrumentalReviewServer') as MockServer:
# Setup analyzer mock
mock_analyzer_instance = MockAnalyzer.return_value
mock_analyzer_instance.analyze.return_value = sample_analysis
# Setup waveform generator mock
mock_waveform_instance = MockWaveformGen.return_value
mock_waveform_instance.generate.return_value = "waveform.png"
# Setup server mock - simulate user selecting "clean"
mock_server_instance = MockServer.return_value
mock_server_instance._selection_event = MagicMock()
mock_server_instance._selection_event.wait.return_value = None
mock_server_instance.get_selection.return_value = "clean"
# Call the function
result = run_instrumental_review(
track=sample_track,
logger=mock_logger,
)
# CRITICAL ASSERTION: Verify correct parameter name
# The method should be called with 'segments=', not 'audible_segments='
mock_waveform_instance.generate.assert_called_once()
call_kwargs = mock_waveform_instance.generate.call_args.kwargs
# This is the key check that would have caught the bug
assert 'segments' in call_kwargs, \
"WaveformGenerator.generate() should be called with 'segments' parameter"
assert 'audible_segments' not in call_kwargs, \
"WaveformGenerator.generate() should NOT use 'audible_segments' (wrong param name)"
# Verify the segments value is the analysis segments
assert call_kwargs['segments'] == sample_analysis.audible_segments
finally:
os.chdir(original_dir)
def test_waveform_generator_receives_analysis_segments(
self, sample_track, sample_analysis, mock_logger, tmp_path
):
"""Verify the analysis audible_segments are passed to waveform generator."""
from karaoke_gen.utils.gen_cli import run_instrumental_review
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
with patch('karaoke_gen.utils.gen_cli.AudioAnalyzer') as MockAnalyzer, \
patch('karaoke_gen.utils.gen_cli.WaveformGenerator') as MockWaveformGen, \
patch('karaoke_gen.utils.gen_cli.InstrumentalReviewServer') as MockServer:
mock_analyzer_instance = MockAnalyzer.return_value
mock_analyzer_instance.analyze.return_value = sample_analysis
mock_waveform_instance = MockWaveformGen.return_value
mock_waveform_instance.generate.return_value = "waveform.png"
mock_server_instance = MockServer.return_value
mock_server_instance._selection_event = MagicMock()
mock_server_instance._selection_event.wait.return_value = None
mock_server_instance.get_selection.return_value = "clean"
run_instrumental_review(track=sample_track, logger=mock_logger)
# Verify the correct segments were passed
call_kwargs = mock_waveform_instance.generate.call_args.kwargs
passed_segments = call_kwargs['segments']
assert len(passed_segments) == 2
assert passed_segments[0].start_seconds == 10.0
assert passed_segments[1].start_seconds == 60.0
finally:
os.chdir(original_dir)
def test_analyzer_called_with_backing_vocals_path(
self, sample_track, sample_analysis, mock_logger, tmp_path
):
"""Verify AudioAnalyzer.analyze() is called with backing vocals path."""
from karaoke_gen.utils.gen_cli import run_instrumental_review
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
with patch('karaoke_gen.utils.gen_cli.AudioAnalyzer') as MockAnalyzer, \
patch('karaoke_gen.utils.gen_cli.WaveformGenerator') as MockWaveformGen, \
patch('karaoke_gen.utils.gen_cli.InstrumentalReviewServer') as MockServer:
mock_analyzer_instance = MockAnalyzer.return_value
mock_analyzer_instance.analyze.return_value = sample_analysis
mock_waveform_instance = MockWaveformGen.return_value
mock_waveform_instance.generate.return_value = "waveform.png"
mock_server_instance = MockServer.return_value
mock_server_instance._selection_event = MagicMock()
mock_server_instance._selection_event.wait.return_value = None
mock_server_instance.get_selection.return_value = "clean"
run_instrumental_review(track=sample_track, logger=mock_logger)
# Verify analyzer was called with a backing vocals path
mock_analyzer_instance.analyze.assert_called_once()
analyzed_path = mock_analyzer_instance.analyze.call_args[0][0]
assert "Backing Vocals" in analyzed_path or os.path.exists(analyzed_path)
finally:
os.chdir(original_dir)
def test_server_started_with_correct_parameters(
self, sample_track, sample_analysis, mock_logger, tmp_path
):
"""Verify InstrumentalReviewServer is created with correct parameters."""
from karaoke_gen.utils.gen_cli import run_instrumental_review
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
with patch('karaoke_gen.utils.gen_cli.AudioAnalyzer') as MockAnalyzer, \
patch('karaoke_gen.utils.gen_cli.WaveformGenerator') as MockWaveformGen, \
patch('karaoke_gen.utils.gen_cli.InstrumentalReviewServer') as MockServer:
mock_analyzer_instance = MockAnalyzer.return_value
mock_analyzer_instance.analyze.return_value = sample_analysis
mock_waveform_instance = MockWaveformGen.return_value
mock_waveform_instance.generate.return_value = "waveform.png"
mock_server_instance = MockServer.return_value
mock_server_instance._selection_event = MagicMock()
mock_server_instance._selection_event.wait.return_value = None
mock_server_instance.get_selection.return_value = "clean"
run_instrumental_review(track=sample_track, logger=mock_logger)
# Verify server was created with expected parameters
MockServer.assert_called_once()
server_kwargs = MockServer.call_args.kwargs
assert server_kwargs['base_name'] == "Test - Song"
assert server_kwargs['analysis'] == sample_analysis
assert 'waveform_path' in server_kwargs
assert 'backing_vocals_path' in server_kwargs
assert 'clean_instrumental_path' in server_kwargs
finally:
os.chdir(original_dir)
def test_returns_clean_instrumental_when_clean_selected(
self, sample_track, sample_analysis, mock_logger, tmp_path
):
"""Verify correct path returned when user selects 'clean'."""
from karaoke_gen.utils.gen_cli import run_instrumental_review
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
with patch('karaoke_gen.utils.gen_cli.AudioAnalyzer') as MockAnalyzer, \
patch('karaoke_gen.utils.gen_cli.WaveformGenerator') as MockWaveformGen, \
patch('karaoke_gen.utils.gen_cli.InstrumentalReviewServer') as MockServer:
mock_analyzer_instance = MockAnalyzer.return_value
mock_analyzer_instance.analyze.return_value = sample_analysis
mock_waveform_instance = MockWaveformGen.return_value
mock_waveform_instance.generate.return_value = "waveform.png"
mock_server_instance = MockServer.return_value
mock_server_instance._selection_event = MagicMock()
mock_server_instance._selection_event.wait.return_value = None
mock_server_instance.get_selection.return_value = "clean"
result = run_instrumental_review(track=sample_track, logger=mock_logger)
# Should return the clean instrumental path
assert result is not None
assert "Instrumental" in result
assert "+BV" not in result
finally:
os.chdir(original_dir)
def test_returns_with_backing_when_selected(
self, sample_track, sample_analysis, mock_logger, tmp_path
):
"""Verify correct path returned when user selects 'with_backing'."""
from karaoke_gen.utils.gen_cli import run_instrumental_review
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
with patch('karaoke_gen.utils.gen_cli.AudioAnalyzer') as MockAnalyzer, \
patch('karaoke_gen.utils.gen_cli.WaveformGenerator') as MockWaveformGen, \
patch('karaoke_gen.utils.gen_cli.InstrumentalReviewServer') as MockServer:
mock_analyzer_instance = MockAnalyzer.return_value
mock_analyzer_instance.analyze.return_value = sample_analysis
mock_waveform_instance = MockWaveformGen.return_value
mock_waveform_instance.generate.return_value = "waveform.png"
mock_server_instance = MockServer.return_value
mock_server_instance._selection_event = MagicMock()
mock_server_instance._selection_event.wait.return_value = None
mock_server_instance.get_selection.return_value = "with_backing"
result = run_instrumental_review(track=sample_track, logger=mock_logger)
# Should return the combined instrumental path (with backing vocals)
assert result is not None
assert "+BV" in result
finally:
os.chdir(original_dir)
def test_returns_none_when_no_backing_vocals(
self, mock_logger, tmp_path
):
"""Verify None returned when no backing vocals file exists."""
from karaoke_gen.utils.gen_cli import run_instrumental_review
track = {
"artist": "Test",
"title": "Song",
"track_output_dir": str(tmp_path),
"separated_audio": {
"backing_vocals": {}, # No backing vocals
"clean_instrumental": {},
"combined_instrumentals": {},
},
}
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
result = run_instrumental_review(track=track, logger=mock_logger)
assert result is None
finally:
os.chdir(original_dir)
def test_returns_none_when_no_separated_audio(
self, mock_logger, tmp_path
):
"""Verify None returned when no separated_audio in track."""
from karaoke_gen.utils.gen_cli import run_instrumental_review
track = {
"artist": "Test",
"title": "Song",
"track_output_dir": str(tmp_path),
"separated_audio": {},
}
result = run_instrumental_review(track=track, logger=mock_logger)
assert result is None
def test_handles_exception_gracefully(
self, sample_track, mock_logger, tmp_path
):
"""Verify exceptions are caught and None is returned."""
from karaoke_gen.utils.gen_cli import run_instrumental_review
original_dir = os.getcwd()
os.chdir(tmp_path)
try:
with patch('karaoke_gen.utils.gen_cli.AudioAnalyzer') as MockAnalyzer:
# Make analyzer raise an exception
mock_analyzer_instance = MockAnalyzer.return_value
mock_analyzer_instance.analyze.side_effect = Exception("Test error")
result = run_instrumental_review(track=sample_track, logger=mock_logger)
# Should return None on error
assert result is None
# Should log the error
mock_logger.error.assert_called()
finally:
os.chdir(original_dir)
class TestWaveformGeneratorParameterContract:
"""
Contract tests to verify WaveformGenerator.generate() parameter signature.
These tests ensure the interface is stable and document expected parameters.
"""
def test_generate_accepts_segments_parameter(self):
"""Verify generate() method accepts 'segments' as a keyword argument."""
from karaoke_gen.instrumental_review import WaveformGenerator
import inspect
sig = inspect.signature(WaveformGenerator.generate)
params = sig.parameters
assert 'segments' in params, \
"WaveformGenerator.generate() must have a 'segments' parameter"
def test_generate_does_not_have_audible_segments_parameter(self):
"""
Verify generate() does NOT have 'audible_segments' parameter.
This documents that the correct parameter name is 'segments',
not 'audible_segments' (which matches the model field name).
"""
from karaoke_gen.instrumental_review import WaveformGenerator
import inspect
sig = inspect.signature(WaveformGenerator.generate)
params = sig.parameters
assert 'audible_segments' not in params, \
"WaveformGenerator.generate() should use 'segments', not 'audible_segments'"
def test_generate_parameter_types_documented(self):
"""Verify generate() method has proper type annotations."""
from karaoke_gen.instrumental_review import WaveformGenerator
import inspect
sig = inspect.signature(WaveformGenerator.generate)
params = sig.parameters
# Key parameters should have annotations
assert params['audio_path'].annotation == str
assert params['output_path'].annotation == str