# 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