nwe files

some files

V4_ROADMAP.md

@@ -0,0 +1,94 @@
+# V4 Roadmap
+
+V4 is about pushing the output closer to a **real DJ mini-mix** while keeping everything **local-first** and reproducible.
+
+> Guiding principles:
+> - Local-only (no cloud, no uploads)
+> - Deterministic defaults (repeatable outputs)
+> - “DJ control knobs” > opaque magic
+> - Trance-friendly phrasing (bars/phrases matter)
+
+---
+
+## 1) Musical accuracy upgrades (core)
+
+### A. Better downbeat / phrase alignment
+- Add a stronger “1-of-bar” detector:
+  - Combine beat tracking + onset accents + low-frequency (kick) emphasis
+  - Prefer downbeats where kick energy spikes
+- Add `--phrase-bars` (e.g. 8/16) to cut on larger musical phrases
+- Add `--snap-strength` (soft vs hard snap)
+
+### B. Key detection improvements
+- Add `--key-window` to estimate key in the *selected region* (not whole track)
+- Add confidence scoring + fallback:
+  - If confidence is low, disable harmonic ordering for that track
+- Add “ignore key for breakdowns” option (`--key-harmonic-only`)
+
+### C. Transition logic upgrades
+- Add “mix-in/mix-out windows”:
+  - prefer stable groove segments for transitions
+- Add optional “filter sweep style” transitions (FFmpeg filters) as an effect:
+  - `--fx filter_sweep` (subtle, optional)
+
+---
+
+## 2) DJ-friendly automation
+
+### A. Auto tempo normalization (optional)
+- Only for teasers (not for mastering)
+- Add `--tempo-normalize`:
+  - time-stretch small BPM deltas (e.g. +/-2 BPM) for smoother blends
+
+### B. Camelot-aware graph ordering
+- Replace greedy chaining with a small graph search:
+  - minimize “harmonic distance” + tempo distance + maximize energy ramp
+- Add `--order objective`:
+  - `harmonic`
+  - `tempo`
+  - `energy`
+  - `balanced` (default)
+
+### C. Multi-style teaser modes
+- `rollcall` (fast flips)
+- `mini_mix` (longer phrases)
+- `peak_build` (energy ramp to “drop” at the end)
+- `social_15` (15s vertical-friendly teaser pacing)
+
+---
+
+## 3) Engineering / Repo upgrades
+
+### A. Single stable CLI (autoclip)
+- Publish one entrypoint:
+  - `autoclip build ...`
+  - `autoclip analyze ...`
+  - `autoclip report ...`
+
+### B. Packaging
+- Add `pyproject.toml` packaging metadata
+- Add `pipx install .` support (optional)
+- Add pinned optional dependency groups:
+  - `pip install .[dev]` -> pytest, ruff, black
+
+### C. Better testing
+- Add fast unit tests (no audio)
+- Add optional integration test that uses a tiny bundled WAV sample (if license allows)
+
+---
+
+## 4) Nice-to-have (stretch)
+
+- Spectral “drop detector” for trance peak moments
+- Auto-generated tracklist timestamps + social captions via Ollama (optional)
+- Export cue sheet (CUE) for the teaser
+- Optional waveform PNG generation for README (matplotlib)
+
+---
+
+## Suggested V4 milestone plan
+
+- **V4.0.0**: improved phrase/downbeat snap + balanced ordering + single CLI
+- **V4.1.0**: key confidence + graph ordering
+- **V4.2.0**: tempo normalize (optional) + effect transitions (optional)
+- **V4.3.0**: stronger testing + packaging polish