曲に「ムード（感情）」などのタグを付けると、Milonga DJ Pro の推薦エンジンが 感情の流れを考えてタンダを提案できるようになります。タグは Excel ファイルでまとめて管理するのが最も効率的です。
この手引き書は「Excel をゼロから書く」のではなく、 アプリから書き出した表を土台に、少しずつ育てていく方法を説明します。 時間のかかる DB 作りを、ムダなく安全に進められます。

## 0. 大前提：Excel が「正（マスター）」

- 取り込み時、Excel に値がある欄 → その値で上書き（Excel が勝つ）
- Excel が空欄 → アプリ側の既存タグはそのまま（手作業は空欄で消えません）
- つまり Excel ファイルを大切に保管・更新していけば、それが常に正本になります

> 時間をかけて作るのは Excel です。アプリ側はその"写し"。 Excel を毎回上書き保存し、バックアップも取ってください。

## 1. 全体の流れ（往復ワークフロー）

STEP 1　種を書き出す
アプリ上部バーの `⬆ タグ書き出し` をクリック → `tango-library-tags_YYYYMMDD.csv` がダウンロードされます。
これは「今ライブラリにある全曲の一覧（曲名・楽団・年・既存タグ）」です。ゼロから打ち込まずに済みます。

STEP 2　Excel で開いて編集
その CSV を Excel で開く → 必須3タグ（後述）を埋める → Excel 形式（.xlsx）で保存 （ファイル名は自由。例：`tango-library-tags.xlsx`）。

STEP 3　取り込む
アプリ上部バーの `🎭 タグ取り込み` をクリック → 編集した `.xlsx` を選択。

STEP 4　連動レポートを確認
取り込み後に表示される「タグ連動レポート」で 同期数 / 未反映の Excel 行 / まだ未タグの曲を確認。
未反映行は Excel を直して再取り込み、未タグの曲は次回の作業対象にします。

STEP 5　少しずつ繰り返す
一度に全曲やらず、よく使う楽団・タンダから順に。STEP1〜4 を繰り返して育てます。

## 2. 列の一覧と書き方

1行目は見出し（英語）。2行目以降が1曲ずつのデータです。見出しの綴りは変えないでください。

列名 | 必須 | 内容・書き方
--- | --- | ---
`track_id` | — | アプリ内ID。書き出した CSV にあれば触らない（最優先で照合）
`title` | ◎ | 曲名（例：Bahía Blanca）
`orchestra` | ◎ | 楽団名（例：Carlos Di Sarli）
`genre` | ○ | `tango` / `vals` / `milonga` / `cortina`
`year` | △ | 録音年（1900〜2100）。値があれば取り込み時に反映
`singer` | △ | 歌手名（空欄＝インスト）。値があれば反映
`bpm` | △ | テンポ（数値）。空欄なら自動解析値を使用
`key` | △ | 調（例：Am, D minor, F# minor）
`primary_mood` | ◎ | 主ムード（下記13種類から1つ）。これが空欄の行は同期対象外
`secondary_moods` | △ | 副ムード。カンマ区切りで複数可（例：`郷愁,切望`）
`flow_type` | ◎ | `Descent` / `Ascent` / `Sustain` / `Bounce`
`intensity` | ◎ | 1〜5（1＝環境的, 5＝クライマックス）
`notes` | △ | 自由メモ（用途・開幕向け 等）

> まず埋めるのは必須3つだけ：`primary_mood` / `flow_type` / `intensity`。`title` と `orchestra` は 書き出した時点で既に入っています。同楽団・同年代のタンダはタグ傾向が似るので、 コピペで効率化できます。

## 3. primary_mood（主ムード）13種類の選び方

ムード | 系統 | 使いどころのイメージ
--- | --- | ---
哀愁 | メランコリック | ミロンガ前半・閉幕の名作
郷愁 | メランコリック | 懐かしさ／中庸な開幕
諦念 | メランコリック | 受け入れ感
切望 | 渇望 | 前進への渇望
回想 | 静 | 静かな思い出
安らぎ | 静 | 落ち着き
希望 | ポジティブ | 上昇のスタート
情熱 | パッション | クライマックスの軸
決意 | パッション | 意思の強さ
喜び | ポジティブ | 高揚／フィナーレ
華やかさ | ポジティブ | 煌びやかな高揚
軽快 | ポジティブ | テンポの良さ
緊張 | テンス | ドラマチックな張り

> 同じ系統（例：哀愁⇔郷愁⇔諦念）は自然につながり、系統をまたぐ急変は ブリッジ曲が必要、とエンジンが判断します。迷ったら「踊り手がこの曲で何を感じるか」で選んでください。

## 4. flow_type（曲の流れ）

値 | 意味 | 例
--- | --- | ---
`Descent` | 下降型。ピークから落ち着きへ | 曲尾フェード型（Bahía Blanca 系）
`Ascent` | 上昇型。穏やかから熱量へ | ドラマ型（Adiós Nonino 系）
`Sustain` | 維持型。安定したエネルギー | 継続的緊張（La Yumba 系）
`Bounce` | 跳ね返り型。波打つ | キャッチー型（El Choclo 系）

## 5. intensity（強度 1〜5）

値 | レベル | 体感
--- | --- | ---
1 | Ambient | 環境音的・軽い導入
2 | Low | 落ち着いた中庸
3 | Medium | 標準的なタンゴ
4 | High | 盛り上がる
5 | Max Peak | クライマックス・フィナーレ

## 6. 記入例（1曲）

列 | 値
--- | ---
title | Bahía Blanca
orchestra | Carlos Di Sarli
genre | tango
year | 1957
singer | （空欄＝インスト）
primary_mood | 哀愁
secondary_moods | 郷愁, 切望
flow_type | Descent
intensity | 3
notes | ダウナーな名作 / 開幕や閉幕向け

## 7. 曲がうまく結びつかない時（照合のコツ）

取り込み時、アプリは次の順で曲を探します：

1. `track_id` が一致
2. 曲名一致 ＋ 楽団がゆるく一致（`Biagi` と `Rodolfo Biagi` もOK）
3. 曲名がライブラリ内で一意ならそれで一致

大文字小文字・全角半角・`[Tango]` のような括弧表記の違いは自動で吸収します。 それでも「ライブラリに該当曲なし」と出る場合：

- 曲名・楽団の綴りがライブラリと大きく違わないか確認（特に feat. 表記の差）
- 一番確実なのは、`⬆ タグ書き出し`で出た CSV を土台にすること （`track_id` が入っているので確実に一致します）
- 同名異曲が複数あり楽団でも絞れない時は、誤マッチ防止のため意図的にスキップされます

## 8. やってはいけないこと / 注意

- 見出し行（1行目の英語）の綴り変更・列の削除
- `primary_mood` を空欄のまま「タグ付けしたつもり」になる（空欄行は同期されません）
- CSV を「上書き保存」して書式を壊す → 取り込み用は .xlsx で保存が安全
- Excel を1か所でしか持たない → こまめにバックアップ（これが正本のため）

> 取り込みは「Excel が勝つ／空欄は触らない」。 一括で空欄の列を入れて取り込んでも既存タグは消えませんが、 意図せず値を入れた欄は上書きされます。送る前に一度見直してください。

## 9. おすすめの進め方

1. まずよく使う楽団（自分の定番タンダ）から着手
2. 同楽団・同年代は `primary_mood` をコピペで一気に
3. 必須3つが一通り終わったら `secondary_moods` や `year/singer` を肉付け
4. 本番でタンダを組みながら「この提案は違う」と感じた曲を都度メモ → Excel に反映
5. 連動レポートの「まだタグの無い曲」を次回の宿題リストとして使う