Tagging tracks with "mood" and other attributes lets the Milonga DJ Pro recommendation engine consider the emotional arc when suggesting tandas. The most efficient way to manage tags is in a single Excel file.
This guide does not ask you to write Excel from scratch — instead you grow it gradually from a table the app exports for you, so the slow work of building a DB stays efficient and safe.

## 0. Core principle: Excel is the "master"

- On import, a cell with a value → overwrites (Excel wins)
- A blank Excel cell → keeps the existing in-app tag (manual work is never wiped by a blank)
- So if you keep and update the Excel file carefully, it always remains the source of truth

> The thing you invest time in is the Excel file. The app side is a "copy". Save the Excel file each time and keep backups.

## 1. The overall flow (round-trip workflow)

STEP 1 — Export the seed
Click `⬆ Export tags` in the top bar → `tango-library-tags_YYYYMMDD.csv` downloads. It is "a list of every track in your library (title, orchestra, year, existing tags)", so you never type from scratch.

STEP 2 — Edit in Excel
Open that CSV in Excel → fill the 3 required tags (below) → save as Excel (.xlsx) (any filename, e.g. `tango-library-tags.xlsx`).

STEP 3 — Import
Click `🎭 Import tags` in the top bar → choose the edited `.xlsx`.

STEP 4 — Check the sync report
The "Tag sync report" shown after import lists synced count / unmatched Excel rows / still-untagged tracks.
Fix unmatched rows in Excel and re-import; treat untagged tracks as the next batch.

STEP 5 — Iterate in small steps
Don't do everything at once. Start with the orchestras/tandas you use most. Repeat STEP 1–4 to grow it.

## 2. Columns & how to fill them

Row 1 is the header (English). Rows 2+ are one track each. Do not change the header spelling.

Column | Required | Content / how to fill
--- | --- | ---
`track_id` | — | In-app ID. If present in the exported CSV, don't touch it (matched first)
`title` | ◎ | Track title (e.g. Bahía Blanca)
`orchestra` | ◎ | Orchestra (e.g. Carlos Di Sarli)
`genre` | ○ | `tango` / `vals` / `milonga` / `cortina`
`year` | △ | Recording year (1900–2100). Applied if present
`singer` | △ | Singer (blank = instrumental). Applied if present
`bpm` | △ | Tempo (number). If blank, the auto-analyzed value is used
`key` | △ | Key (e.g. Am, D minor, F# minor)
`primary_mood` | ◎ | Primary mood (one of the 13 below). Rows with this blank are not synced
`secondary_moods` | △ | Secondary moods. Comma-separated, multiple allowed (e.g. `nostalgia,longing`)
`flow_type` | ◎ | `Descent` / `Ascent` / `Sustain` / `Bounce`
`intensity` | ◎ | 1–5 (1 = ambient, 5 = climax)
`notes` | △ | Free memo (use case, "for the opening", etc.)

> Fill only the 3 required ones first: `primary_mood` / `flow_type` / `intensity`. `title` and `orchestra` are already filled by the export. Tracks of the same orchestra/era tend to share tags, so copy-paste speeds it up.

## 3. Choosing primary_mood (13 moods)

Mood (JA) | Meaning (EN) | Family | Typical use
--- | --- | --- | ---
哀愁 | Aishū — wistful sorrow | melancholic | Early milonga / closing masterpieces
郷愁 | Kyōshū — nostalgia | melancholic | Nostalgic / a moderate opening
諦念 | Teinen — resignation | melancholic | Sense of acceptance
切望 | Setsubō — yearning | longing | Craving to move forward
回想 | Kaisō — reminiscence | calm | Quiet memories
安らぎ | Yasuragi — serenity | calm | Calm, settled
希望 | Kibō — hope | positive | The start of a rise
情熱 | Jōnetsu — passion | passionate | The core of the climax
決意 | Ketsui — resolve | passionate | Strength of will
喜び | Yorokobi — joy | positive | Elation / finale
華やかさ | Hanayakasa — splendor | positive | Glittering elation
軽快 | Keikai — lightness | positive | Good tempo, brisk
緊張 | Kinchō — tension | tense | Dramatic tautness

> The same family (e.g. 哀愁⇔郷愁⇔諦念) connects naturally; a sudden jump across families needs a bridge track, which the engine accounts for. When unsure, choose by "what the dancer feels in this track". Enter the Japanese term in the cell.

## 4. flow_type (the track's shape)

Value | Meaning | Example
--- | --- | ---
`Descent` | Descending. From peak to calm | Tail-fade type (Bahía Blanca-like)
`Ascent` | Ascending. From calm to heat | Drama type (Adiós Nonino-like)
`Sustain` | Sustained, steady energy | Continuous tension (La Yumba-like)
`Bounce` | Bouncing, undulating | Catchy type (El Choclo-like)

## 5. intensity (1–5)

Value | Level | Feel
--- | --- | ---
1 | Ambient | Atmospheric, light intro
2 | Low | Calm, moderate
3 | Medium | Standard tango
4 | High | Builds up
5 | Max Peak | Climax, finale

## 6. Example (one track)

Column | Value
--- | ---
title | Bahía Blanca
orchestra | Carlos Di Sarli
genre | tango
year | 1957
singer | (blank = instrumental)
primary_mood | 哀愁
secondary_moods | 郷愁, 切望
flow_type | Descent
intensity | 3
notes | Downer masterpiece / for opening or closing

## 7. When a track won't match (matching tips)

On import the app searches in this order:

1. `track_id` matches
2. Title matches + orchestra loosely matches (`Biagi` and `Rodolfo Biagi` both OK)
3. If the title is unique in the library, match by that

Case, full/half-width and bracket notation like `[Tango]` are absorbed automatically. If it still says "No matching track":

- Check that title/orchestra spelling isn't very different from the library (especially feat. notation)
- Most reliable: base your file on the CSV from `⬆ Export tags` (it has `track_id`, so it always matches)
- If multiple same-titled tracks exist and orchestra can't disambiguate, it is intentionally skipped to avoid wrong matches

## 8. Don'ts & cautions

- Don't change the header spelling (row 1) or delete columns
- Don't leave `primary_mood` blank and assume it's "tagged" (blank rows aren't synced)
- Don't break formatting by "saving over" the CSV → for importing, save as .xlsx
- Don't keep the Excel in only one place → back it up often (it is the source of truth)

> Import = "Excel wins / blanks are left alone". Importing with blank columns won't erase existing tags, but a cell where you did put a value will overwrite. Review once before importing.

## 9. Recommended approach

1. Start with the orchestras you use most (your standard tandas)
2. Copy-paste `primary_mood` across same orchestra/era at once
3. Once the 3 required are done, flesh out `secondary_moods` and `year/singer`
4. While building tandas live, note tracks where a suggestion "felt wrong" → reflect in Excel
5. Use the report's "still-untagged tracks" as your to-do list for next time