Architecture

MixBox is an automated DJ pipeline carrying audio from source tracks to final mixed output; core pipelines use localized dependencies instead of mandatory global ServiceRegistries.

DJ Path

flowchart TD
    A["Entry: mixbox.cli.commands.main"] --> B["Validated Config (Pydantic)"]
    B --> C["Analysis / Service layer: AnalysisService, bounded asyncio.Semaphore"]
    C --> D["Planning and Transitions: RecipeService, MixPlanService, TimelinePreviewViewModel"]
    D --> E["Mixer (grid-aligned)"]
    E --> F["Outputs: audio + mix_report.json"]

#	Stage	Detail
1	Entry	mixbox.cli.commands.main parses input paths and CLI overrides
2	Validated Config	mixbox.config.config.Config / models.py populated and validated via Pydantic
3	Analysis / Service layer	AnalysisService extracts BPM, key, and energy with caching, concurrency bounded by asyncio.Semaphore
4	Planning & Transitions	RecipeService, MixPlanService, TimelinePreviewViewModel compute compatible transition windows, beats, and effect parameters
5	Mixer	Audio segments aligned to a grid and transitioned seamlessly
6	Outputs	Mix exported to output-dir plus a structured mix_report.json of timing and quality metrics

uv run mixbox mix track1.wav track2.wav --output-dir out/
uv run mixbox plan track1.wav track2.wav --output mix_plan.json

Conventions

Convention	Rule
Asynchronous execution	Heavy analysis runs via asyncio.gather with bounded semaphores offloading CPU-bound DSP, maintaining stability
Dependency injection	Services receive instantiated config objects and localized deps; ServiceRegistry is strictly for NiceGUI composition and ViewModels, while CLI and review runtimes construct services directly
UI split	NiceGUI drives reactive timeline previews (TimelinePreviewViewModel); the FastAPI review server serves a separate prebuilt static UI
Audio loading	No repository-wide librosa ban; loading and mixing paths rely on the shared audio-core package
Error handling	Analysis tasks return Track(path=track_path, error=str(e)) instead of halting the batch