# Auto Clip (V_1 / V_2 / V_3)

Et lokalt, offline-venligt toolkit til at lave **DJ-style album teasers** ved automatisk at finde highlights i dine tracks og klippe dem sammen til en kort teaser med **Python + FFmpeg**.

Repoet er tænkt organiseret sådan her:

```
Auto Clip/
  V_1/
  V_2/
  V_3/
```

Hver version bygger ovenpå den forrige og giver mere “DJ-feel” og automation.

---

## Hvad den gør ✅

Du giver en mappe med tracks (WAV/MP3/FLAC osv.), og scripts kan:

- **Scanne tracks automatisk** (med max-grænse, fx 20)
- **Vælge tracks efter index** (fx `1,2,5,7` eller `1-4,9`) eller automatisk vælge en **best-of**
- Finde **highlight-sektioner** (energi + onset/transients)
- Snappe cuts til et **bar-grid** (phrase-aligned “DJ” cuts)
- Valgfri **pre-roll** (starter 1 bar før highlight)
- Render klip og samle med **acrossfades**
- Eksportere **WAV + MP3**
- Lave en **JSON rapport** med timestamps og metadata

> Note: Det her er **audio-analyse + heuristik**, ikke “generativ musik-AI”.  
> LLM/Ollama kan hjælpe med README/promo/tracklist, men selve klipningen laves lokalt med librosa + FFmpeg.

---

## Versioner 🧩

### V_1 — Minimal MVP
**Formål:** Hurtig proof-of-concept.

Typisk:
- Highlight detection (energi/onset)
- Simpel render + acrossfade teaser
- JSON rapport

**Bedst når:** du vil i gang hurtigt.

---

### V_2 — Valg + Best-of + DJ ordering
**Formål:** Git-klar CLI og bedre “DJ flow”.

Tilføjer:
- Folder scan (max 20)
- Track selection via index/range (`--select 1-4,7`)
- Auto selection (`--select auto --auto-n 8`)
- Ordering heuristics (tempo clustering + energy ramp)
- WAV + MP3 eksport
- JSON rapport

**Bedst når:** du vil have et praktisk tool du kan bruge igen og igen.

---

### V_3 — Harmonic mixing + downbeat-ish snap + 2-pass loudness
**Formål:** Trance-venlig “DJ teaser” kvalitet.

Tilføjer:
- Key detection (chroma) + **Camelot** mapping (best effort)
- Harmonic ordering (Camelot neighbors) → mere smooth transitions
- “Downbeat-ish” bar-start snap (beat grid + onset accent heuristik)
- **2-pass loudnorm** pr klip (mere ens output)

**Bedst når:** du laver old school trance, og det skal føles som mini-mix.

---

## Krav 🛠️

### System
- **FFmpeg** installeret og i PATH
- Python **3.10+** anbefalet (3.11+ er perfekt)

### Python pakker
Standard:
- `numpy`
- `librosa`
- `soundfile`

Valgfrit:
- `requests` (kun hvis du bruger Ollama helper til README/promo assets)

---

## Install (anbefalet) 🐍

Lav et virtualenv:

```bash
python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows PowerShell:
# .\.venv\Scripts\Activate.ps1

pip install -U pip
pip install numpy librosa soundfile
```

Hvis du vil bruge Ollama helper:
```bash
pip install requests
```

---

## FFmpeg install hints 🎬

### Debian/Ubuntu
```bash
sudo apt-get update
sudo apt-get install -y ffmpeg
```

### Windows
Installer FFmpeg og sørg for at `ffmpeg.exe` ligger i PATH (så `ffmpeg -version` virker).

---

## Brug 🚀

> Scripts ligger under `V_1/`, `V_2/`, `V_3/` alt efter repo-strukturen.
> Eksemplerne antager at du kører fra en version-mappe og har en `tracks/` mappe.

### Input
Læg dine filer her:

```
tracks/
  01 - Track.wav
  02 - Track.mp3
  ...
```

---

## V_2 eksempler

### Brug alle tracks (max scan gælder stadig)
```bash
python dj_teaser_v2.py --tracks-dir ./tracks --select all --mode rollcall --teaser 60 --bars 2 --preroll-bars 1
```

### Vælg konkrete tracks via index
```bash
python dj_teaser_v2.py --tracks-dir ./tracks --select 1,2,3,7,9 --teaser 60 --bars 2
```

### Range + mix
```bash
python dj_teaser_v2.py --tracks-dir ./tracks --select 1-4,7,10-12 --teaser 60 --bars 2
```

### Auto best-of (vælg top N tracks)
```bash
python dj_teaser_v2.py --tracks-dir ./tracks --select auto --auto-n 8 --mode bestof --teaser 75 --bars 4 --preroll-bars 1
```

---

## V_3 eksempler (anbefalet til trance)

### Rollcall (alle tracks, hurtigt DJ flip)
```bash
python dj_teaser_v3.py --tracks-dir ./tracks --select all --teaser 60 --bars 2 --preroll-bars 1 --avoid-intro 30 --harmonic
```

### Best-of mini-mix vibe
```bash
python dj_teaser_v3.py --tracks-dir ./tracks --select auto --auto-n 8 --teaser 75 --bars 4 --preroll-bars 1 --avoid-intro 30 --harmonic
```

---

## Output 📦

Typisk:

- `out/album_teaser.wav`
- `out/album_teaser.mp3`
- `out/teaser_report.json`

Rapporten indeholder:
- valgt track order
- estimeret BPM
- key/camelot (V_3)
- clip start og varighed

---

## Tuning tips (old school trance) 💡

- **Undgå lange intros**: `--avoid-intro 30` eller `45`
- **DJ phrasing**:
  - `--bars 2` til rollcall med mange tracks (14+)
  - `--bars 4` hvis du vil have mere “rigtig trance”
- **Lead-in**: `--preroll-bars 1` giver ofte mere naturlige transitions
- **Crossfade**:
  - 0.20–0.35 sek er typisk sweetspot
- **Harmonic mode** (V_3): `--harmonic` anbefales, men key detection er best-effort

---

## Begrænsninger ⚠️

- Beat og key detection er **heuristik**; nogle tracks kan blive “off”, især med:
  - lange breakdowns
  - meget pad/noise
  - ambient intro/outro
- “Downbeat” er approx (beat grid + onset accent), ikke en trænet downbeat-model
- Hvis du vil have det helt perfekt, så tweak:
  - `--avoid-intro`, `--bars`, `--preroll-bars`, `--select` og track order

---

## Valgfrit: Ollama (tekst) 🤖

Hvis du kører Ollama lokalt (fx `http://192.168.2.60:11434`) kan du bruge den til:

- README tekst
- promo tekst (TikTok/IG/YouTube)
- tracklist med timestamps (ud fra `teaser_report.json`)

Anbefalet model (som du har):
- `llama3.1:8b-instruct-q4_0`

> Ollama er valgfri og ikke nødvendig for audio-klipningen.

---

## Repo hygiene 🧼

Foreslået `.gitignore`:

```
.venv/
__pycache__/
work/
out/
*.wav
*.mp3
```

---

## License
Vælg det der passer (MIT er typisk).  
Hvis du ikke har valgt endnu, kan du tilføje MIT senere.

---

## Credits
- **FFmpeg** til audio processing
- **librosa** til audio analyse