DJ_Teaser_Clipper/V4_ROADMAP.md

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