Milonga DJ Pro は 会場で DJ 一人がリアルタイムに迷わず操作できることを 最優先に作られています。既存の DJ ソフトの多くは「DJ ＋ 音響エンジニア」の2人体制を 前提にしているため、現場で一人だと使いこなせない機能が多くあります。本アプリはその逆で、 ミロンガ本番で一人で完結できることを軸にしています。

- 完全オフライン動作（インターネット不要）
- データはすべてお使いの PC 内にのみ保存
- タンゴ／バルス／ミロンガ／コルティーナの専用設計

▲ アプリ全体（左：ライブラリ／中央：プレイヤー＆セットリスト／右：タンダ作成）

## 1. 起動とインストール

- MSIX 版：スタートメニューの「Milonga DJ Pro」から起動
- ファイル版：`index.html` をダブルクリック（ブラウザで開きます）

> ⚠ ファイル版で更新が反映されない場合は、ブラウザを完全に閉じてから開き直し、 `Ctrl + Shift + R`（強制リロード）してください。

## 2. 画面構成

エリア | 位置 | 役割
--- | --- | ---
ライブラリ | 左 | 取り込んだ全曲。ジャンル／お気に入りで絞り込み
プレイヤー＆セットリスト | 中央 | 再生操作・波形・候補曲リスト・本番のセットリスト
タンダ作成 | 右 | 手動作成／自動生成、似た曲おすすめ、コルティーナ

上部バー：当日モード・タイマー・EQ・設定・ヘルプ・候補曲・印刷・曲を追加・言語切替（JA/EN/ES）

## 3. ライブラリへの曲の追加（3通り）

1. ドラッグ＆ドロップ／＋ボタン：左上「＋ Drag & Drop」へ投入、または右上「＋ 曲を追加」。複数ファイル・フォルダごとOK。
2. 📁 フォルダ監視：音楽フォルダを指定すると30秒ごとに自動スキャンして新譜を取り込み（サブフォルダ対象・再起動後も復元）。
3. 📋 プレイリスト取り込み：iTunes / Rekordbox / M3U を取り込み、自動マッチング＋自動タンダ化。

取り込み時、ID3 タグから楽団名・曲名・録音年・歌手・アートワークを自動抽出。1万曲規模でも遅延デコードで瞬時に起動します。

▲ ライブラリ（ジャンル絞り込み・楽団グループ表示・＋で候補曲へ）

## 4. タンダの作成

### 4-1. 手動作成

1. ライブラリの曲の「＋」で候補曲リストに追加（中央に一覧表示）
2. 揃ったら「✦ タンダ化」でタンダ確定（ジャンルは先頭曲から自動判定）
3. タンダ内は並べ替え・削除・1曲入れ替え可

### 4-2. 自動生成（楽団 DB 利用）

楽団データベースを有効化 → 楽団 × ジャンルでタンダを一括生成（既定ジャンルはタンゴのみ／設定で変更可）。

### 4-3. 📚 タンダ集（個別保存・再利用）

組んだタンダを1つずつ保存・お気に入り登録・呼び出し。よく使うタンダを蓄積して本番で即投入。

### 4-4. 🅰🅱🅲 セットリスト・ホットスワップ

セットリストを3枠（A / B / C）で持ち替え。会場の流れに合わせて即切替。

▲ 手動作成タブ・候補曲リスト・タンダ化

## 5. ✦ 似た曲おすすめ（推薦エンジン）

右パネルの「✦ 似た曲おすすめ」ボタンでポップアップが開きます。

- 再生中／選択中の曲を基準に、似た曲を点数順で提案
- ムードドロップダウンで絞り込み
- 各曲に ▶ 再生 ／ ✎ 編集 ／ ＋ タンダ化リストに追加
- 「＋」追加でライブラリと同じく ✓（ゴールド） が付き、候補曲リストにも反映

▲ 似た曲おすすめポップアップ（基準曲・ムード絞り込み・▶✎＋）

## 6. ムードタグと Excel 連動

曲に「主ムード・副ムード・フロー・強度」等のタグを付けると、推薦エンジンが感情の流れを考慮します。

### 付け方

- 個別：曲を ✎ 編集 → 主ムード／フロー／強度などを設定
- 一括：Excel（.xlsx）／CSV で管理して取り込み

### Excel 連動（Excel = マスター）

1. ⬆ タグ書き出し：現在のアプリ内タグを CSV 出力（Excel マスターの種に）
2. Excel で `primary_mood / flow_type / intensity / year / singer` 等を編集
3. 🎭 タグ取り込み（または 📋 プレイリスト）で `.xlsx` を取り込み

状況 | 動作
--- | ---
Excel に値あり | その値で上書き（Excel が正）
Excel が空欄 | アプリ側の既存値はそのまま（手作業を消さない）
楽団・曲名の表記揺れ | `[Tango]` の有無・大文字小文字・全角半角を吸収して自動照合

取り込み後、連動レポート（同期数／未反映行／まだ未タグの曲）を表示します。

▲ タグ連動レポート（Excel = マスター）

## 7. 再生操作

機能 | 内容
--- | ---
基本 | 曲をクリック → スペースで再生／一時停止
AUTO モード | タンダ→コルティーナ→次タンダを自動進行（OFF が既定）
オートクロスフェード | タンダ内・コルティーナ移行のフェード（設定画面）
🎧 ヘッドホン CUE | マスターと別出力でプレリスニング
キューポイント A/B/C | 曲中の頭出し位置を3つ登録
⏱ 開始/終了位置 | イントロ/アウトロをカットして再生
テンポ ±10% | 速さを微調整（ダブルクリックで100%）
🎵 次タンダ サウンドチェック | コルティーナ中に次タンダの音量を事前確認
LUFS 音量正規化 | SP復刻〜現代録音まで音量を自動均一化＋曲別 EQ

▲ プレイヤー（波形・L/R メーター・CUE・AGC・テンポ）

## 8. コルティーナ

コルティーナ候補をライブラリから登録 → タンダ間に自動挿入。タンダ確定時に自動で前に差し込み可能。

## 9. エネルギー構成 / 時刻軸プラン

上昇／下降／山型／谷型の4カーブでタンダを自動並べ替え。開始・ピーク・終了時刻を入力すると、目標強度を時刻に合わせてリアルタイム表示します。

## 10. 本番中・本番後

- 当日モード：本番運用に最適化した表示
- 🎭 スクリーン表示：会場プロジェクター用（アートワーク背景付き）
- タイマー：経過/残り時間管理
- 演奏ログ分析：本番後に BPM・エネルギー推移・楽団使用回数ランキング
- セットリスト保存/読み込み：JSON 保存で次回再利用・印刷可

## 11. 設定

タンダ間ギャップ秒数／クロスフェード時間／フェードイン／LUFS 目標値／自動生成の既定ジャンル／オーディオ出力（マスター＝スピーカー・キュー＝ヘッドホン）。

## 12. キーボード操作

> テキスト入力中は無効。入力欄の外をクリックしてから操作してください。

キー | 動作
--- | ---
`Space` | 再生 / 一時停止
`→` | 次の曲へ（タンダ最後なら次タンダへ）
`←` | 3秒以内＝前の曲 / 3秒以降＝曲の先頭へ

## 13. データとプライバシー

- 曲・タグ・セットリストはお使いの PC 内（ブラウザのデータベース）にのみ保存
- 外部送信なし・完全オフライン
- バックアップ：セットリストは JSON、タグは CSV 書き出しで退避可

## 14. 困ったとき

症状 | 対処
--- | ---
編集が反映されない（ファイル版） | ブラウザを全部閉じる → 開き直す → `Ctrl+Shift+R`
似た曲が出ない | 曲を再生/選択し基準を作る。タグ付きの曲が増えるほど精度向上
タグ取り込みで「該当曲なし」 | 楽団名・曲名のスペルを確認（大きな表記違いは不可）
音量がバラつく | LUFS 正規化を ON（設定）。曲別 EQ も活用
次の曲を会場に出さず確認したい | 🎧 CUE（ヘッドホン出力）を使用