Milonga DJ Pro is built first and foremost so that a single DJ can operate it in real time at the venue without confusion. Most existing DJ software assumes a separate DJ and sound engineer, so many features simply can't be used alone in the field. This app is the opposite: it is designed so one person can run a whole milonga.

- Fully offline (no internet required)
- All data stays only on your own PC
- Purpose-built for Tango / Vals / Milonga / Cortina

▲ The app at a glance (left: Library / center: Player & Setlist / right: Tanda builder)

## 1. Launching & Installation

- MSIX version: launch "Milonga DJ Pro" from the Start menu
- File version: double-click `index.html` (opens in your browser)

> ⚠ If a change doesn't appear in the file version, fully close the browser, reopen `index.html`, then press `Ctrl + Shift + R` (hard reload).

## 2. Screen Layout

Area | Position | Role
--- | --- | ---
Library | Left | All imported tracks. Filter by genre / favorites
Player & Setlist | Center | Playback, waveform, candidate list, the live setlist
Tanda builder | Right | Manual / auto creation, similar-song suggestions, cortina

Top bar: Event mode, Timer, EQ, Settings, Help, Candidates, Print, Add tracks, language switch (JA/EN/ES).

## 3. Adding Tracks to the Library (3 ways)

1. Drag & drop / + button: drop files onto the top-left "+ Drag & Drop" area, or use top-right "+ Add tracks". Multiple files/folders supported.
2. 📁 Folder watch: point to a music folder and it auto-scans every 30s for new tracks (recursive, restored on restart).
3. 📋 Playlist import: import iTunes / Rekordbox / M3U, auto-matched and auto-grouped into tandas.

On import, orchestra, title, year, singer and artwork are auto-extracted from ID3 tags. Even a 10,000-track library starts instantly thanks to lazy decoding.

▲ Library (genre filter, grouped by orchestra, "+" to add to candidates)

## 4. Building Tandas

### 4-1. Manual creation

1. Press "+" on a library track to add it to the candidate list (shown in the center)
2. When ready, press "✦ Create Tanda" (genre auto-detected from the first track)
3. Reorder, delete, or swap a single track within a tanda

### 4-2. Auto generation (orchestra DB)

Enable the orchestra database → generate tandas in bulk by orchestra × genre (default genre: Tango only; configurable).

### 4-3. 📚 Tanda collection (save & reuse)

Save individual tandas, mark favorites and recall them. Build up a library of go-to tandas for instant use during an event.

### 4-4. 🅰🅱🅲 Setlist hot-swap

Keep three setlist slots (A / B / C) and switch instantly to match the room.

▲ Manual tab, candidate list, Create Tanda

## 5. ✦ Similar-Song Suggestions (recommendation engine)

The "✦ Similar songs" button on the right opens a popup.

- Suggests similar tracks ranked by score, based on the playing/selected track as reference
- Filter by mood dropdown
- Each row has ▶ Play / ✎ Edit / + Add to tanda list
- Adding with "+" marks it ✓ (gold) just like the library, and it appears in the candidate list

▲ Similar-songs popup (reference track, mood filter, ▶✎+)

## 6. Mood Tags & Excel Sync

Tagging tracks with primary/secondary mood, flow and intensity lets the engine consider the emotional arc.

### How to tag

- Individually: ✎ Edit a track → set primary mood / flow / intensity
- In bulk: manage in Excel (.xlsx) / CSV and import

### Excel sync (Excel = master)

1. ⬆ Export tags: export current in-app tags to CSV (a seed for the Excel master)
2. Edit `primary_mood / flow_type / intensity / year / singer` etc. in Excel
3. 🎭 Import tags (or 📋 Playlist) to import the `.xlsx`

Situation | Behavior
--- | ---
Excel cell has a value | Overwrites with that value (Excel wins)
Excel cell is blank | Keeps the existing in-app value (manual work is never wiped)
Orchestra/title variations | Absorbs `[Tango]`, case and full/half-width differences automatically

After import, a sync report shows synced count / unmatched rows / still-untagged tracks.

▲ Tag sync report (Excel = master)

## 7. Playback Controls

Feature | Description
--- | ---
Basic | Click a track → Space to play/pause
AUTO mode | Auto-advance tanda → cortina → next tanda (OFF by default)
Auto crossfade | Fade within tanda / into cortina (Settings)
🎧 Headphone CUE | Pre-listen on a separate output from master
Cue points A/B/C | Register three in-track start points
⏱ Start/End trim | Cut intro/outro for playback
Tempo ±10% | Fine-tune speed (double-click to reset 100%)
🎵 Next-tanda sound check | Pre-check next tanda's level during the cortina
LUFS normalization | Auto-level from 1930s SP reissues to modern recordings + per-track EQ

▲ Player (waveform, L/R meters, CUE, AGC, tempo)

## 8. Cortina

Register cortina candidates from the library → auto-insert between tandas. Optionally auto-insert one before a tanda on creation.

## 9. Energy Arc / Time-Axis Plan

Auto-reorder tandas along four curves (rising / falling / peak / valley). Enter start, peak and end times and the target intensity is shown in real time against the clock.

## 10. During & After the Event

- Event mode: display optimized for live operation
- 🎭 Screen display: for the venue projector (with artwork background)
- Timer: elapsed / remaining time management
- Play-log analytics: post-event BPM, energy trend, orchestra-usage ranking
- Setlist save/load: save as JSON to reuse next time; printable

## 11. Settings

Tanda gap seconds / crossfade time / fade-in / LUFS target / default auto-gen genre / audio output (master = speakers, cue = headphones).

## 12. Keyboard Shortcuts

> Disabled while typing in a text field. Click outside the field first.

Key | Action
--- | ---
`Space` | Play / Pause
`→` | Next track (next tanda if at tanda's last track)
`←` | Within 3s = previous track / after 3s = back to start

## 13. Data & Privacy

- Tracks, tags and setlists are stored only on your PC (browser database)
- No external transmission · fully offline
- Backup: setlists as JSON, tags via CSV export

## 14. Troubleshooting

Symptom | Fix
--- | ---
Changes not reflected (file version) | Close the browser fully → reopen → `Ctrl+Shift+R`
No similar songs | Play/select a track to set a reference. More tagged tracks = better accuracy
"No matching track" on tag import | Check orchestra/title spelling (large variations can't be matched)
Uneven volume | Turn on LUFS normalization (Settings); use per-track EQ
Check next track without sending to the room | Use 🎧 CUE (headphone output)