# 画面設計書 17-Music Player

## 概要

本ドキュメントは、Doom EmacsにおけるMusic Player（音楽プレイヤー）画面の設計仕様を定義するものである。EMM（Emacs Multimedia System）パッケージを利用した音楽再生機能について、そのプレイリスト管理、再生コントロール、およびMPD連携を記載する。

### 本画面の処理概要

Music Player画面は、Emacs内で音楽ファイルを再生・管理するための機能を提供する。

**業務上の目的・背景**：開発作業中にBGMを聴きながら作業したいユーザー向けに、Emacsを離れることなく音楽再生を制御できる機能を提供する。MPD（Music Player Daemon）との連携により、システム全体の音楽再生を管理可能。プレイリストの保存・読み込みにより、作業シーンに応じた音楽環境を簡単に切り替えられる。

**画面へのアクセス方法**：EMSコマンド群（`emms`, `emms-play-file`, `emms-play-directory`等）で音楽再生を開始。プレイリストバッファは`emms-playlist-mode`で表示される。

**主要な操作・処理内容**：
1. 音楽ファイルの再生・一時停止・停止
2. プレイリストの表示と管理
3. トラックのシャッフル
4. リピート設定（プレイリスト/トラック）
5. ファイル/ディレクトリの追加
6. プレイリストの保存・読み込み

**画面遷移**：emmsコマンドでプレイリストバッファが開く。バッファ内でトラックを選択して再生。ミニバッファにはMPD接続状態や再生状態が表示される。

**権限による表示制御**：本機能に権限による表示制御はない。全ユーザーが同一の機能を利用可能である。ただし、音楽ファイルへのアクセス権限はOSレベルで管理される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Doomコアシステム | 補助機能 | EMMS連携（app/emms） |

## 画面種別

一覧（プレイリスト形式）

## URL/ルーティング

Emacsモード: `emms-playlist-mode`
バッファ名: `*EMMS Playlist*`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| 音楽ファイル | 入力 | ファイルパス | 再生する音楽ファイル |
| ディレクトリ | 入力 | ディレクトリパス | 音楽ファイルを含むディレクトリ |
| プレイリスト | 入力 | ファイル | 保存されたプレイリストファイル |
| 再生状態 | 出力 | 状態 | 再生中/一時停止/停止 |
| 現在のトラック | 出力 | トラック情報 | 再生中のトラック名、アーティスト等 |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|---------|------|
| トラック名 | 左側 | 音楽トラックの名前 |
| アーティスト | 中央 | アーティスト名（メタデータより） |
| 再生時間 | 右側 | トラックの長さ |
| 現在位置マーカー | 左端 | 再生中のトラックを示すマーカー |

## イベント仕様

### 1-プレイリストリピートトグル

`SPC m l`（localleader + l）で`emms-toggle-repeat-playlist`を実行し、プレイリストのリピート再生を切り替え。

### 2-プレイリスト挿入

`SPC m p`（localleader + p）で`emms-insert-playlist`を実行し、既存のプレイリストファイルを現在のプレイリストに追加。

### 3-ファイル挿入

`SPC m i`（localleader + i）で`emms-insert-file`を実行し、個別の音楽ファイルをプレイリストに追加。

### 4-トラックリピートトグル

`SPC m t`（localleader + t）で`emms-toggle-repeat-track`を実行し、現在のトラックのリピート再生を切り替え。

### 5-プレイリスト保存

`SPC m s`（localleader + s）で`emms-playlist-save`を実行し、現在のプレイリストをファイルに保存。

### 6-シャッフル

`SPC m m`（localleader + m）で`emms-shuffle`を実行し、プレイリストをシャッフル。

### 7-MPDデーモン起動

`+emms/mpd-start-music-daemon`でMPDデーモンを起動し、接続・キャッシュ同期を実行。

### 8-MPDデーモン停止

`+emms/mpd-kill-music-daemon`でEMSSを停止し、MPDデーモンを終了。

### 9-MPDデータベース更新

`+emms/mpc-update-database`でMPDのデータベースを更新し、新しい音楽ファイルを認識。

### 10-MPDデーモン再起動

`+emms/mpd-restart-music-daemon`でMPDの停止と起動を連続実行。

## データベース更新仕様

EMSSは独自のキャッシュシステムを使用する：

| 操作 | 対象 | 説明 |
|-----|------|------|
| キャッシュ保存 | emms-cache-file | トラックメタデータのキャッシュ |
| MPD同期 | emms-cache-set-from-mpd-all | MPDデータベースとの同期 |

キャッシュパス: `~/.doom.d/cache/emms`
データディレクトリ: `~/.doom.d/data/emms/`

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| 起動通知 | `MPD Started!` | +emms/mpd-start-music-daemon実行時 |
| 停止通知 | `MPD Killed!` | +emms/mpd-kill-music-daemon実行時 |
| 更新通知 | `MPD Database Updated!` | +emms/mpc-update-database実行時 |
| 再起動通知 | `MPD Restarted!` | +emms/mpd-restart-music-daemon実行時 |

## 例外処理

| 例外状態 | 処理内容 |
|---------|---------|
| MPD未インストール | MPD関連コマンドがエラー（要mpdインストール） |
| 音楽ファイルなし | 空のプレイリストを表示 |
| 再生エラー | エラーをミニバッファに表示 |

## 備考

- EMSSはEmacs Multimedia Systemの略
- MPD（Music Player Daemon）との連携が推奨される
- サポートされるフォーマットはMPDまたはシステムのオーディオプレイヤーに依存
- emms-directory: `~/.doom.d/data/emms/`
- emms-cache-file: `~/.doom.d/cache/emms`
- `emms-all`と`emms-default-players`で標準設定が適用される

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

EMMSの設定変数とデータディレクトリを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/app/emms/config.el` | 5-7行目: データ/キャッシュディレクトリ設定 |

**読解のコツ**: `emms-`プレフィックスの変数がEMMSパッケージ設定。Doomのprofileディレクトリ構造に従ってパスが設定される。

#### Step 2: エントリーポイントを理解する

EMMSパッケージの基本設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/app/emms/config.el` | 3-18行目: emms設定全体 |

**主要処理フロー**:
1. **6行目**: `emms-directory`をDoomのdataディレクトリに設定
2. **7行目**: `emms-cache-file`をDoomのcacheディレクトリに設定
3. **9行目**: `emms-all`で全機能を有効化
4. **10行目**: `emms-default-players`でデフォルトプレイヤーを設定

#### Step 3: キーバインドを理解する

プレイリストモードのキーバインドを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/app/emms/config.el` | 11-18行目: キーマップ設定 |

**主要処理フロー**:
- **13行目**: `l`でプレイリストリピートトグル
- **14行目**: `p`でプレイリスト挿入
- **15行目**: `i`でファイル挿入
- **16行目**: `t`でトラックリピートトグル
- **17行目**: `s`でプレイリスト保存
- **18行目**: `m`でシャッフル

#### Step 4: MPD連携を理解する

MPDデーモンとの連携を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload.el | `modules/app/emms/autoload.el` | 全体: MPD制御関数 |

**主要処理フロー**:
- **4-10行目**: `+emms/mpd-start-music-daemon`でMPD起動
- **13-17行目**: `+emms/mpd-kill-music-daemon`でMPD停止
- **20-23行目**: `+emms/mpc-update-database`でDB更新
- **26-30行目**: `+emms/mpd-restart-music-daemon`で再起動

### プログラム呼び出し階層図

```
emms (EMMS起動)
    │
    ├─ emms-all (全機能有効化)
    │
    ├─ emms-default-players (デフォルトプレイヤー設定)
    │
    └─ emms-playlist-mode
           │
           ├─ SPC m l → emms-toggle-repeat-playlist
           ├─ SPC m p → emms-insert-playlist
           ├─ SPC m i → emms-insert-file
           ├─ SPC m t → emms-toggle-repeat-track
           ├─ SPC m s → emms-playlist-save
           └─ SPC m m → emms-shuffle

+emms/mpd-start-music-daemon
    │
    ├─ start-process "mpd"
    ├─ +emms/mpc-update-database
    │      └─ call-process "mpc" "update"
    ├─ emms-player-mpd-connect
    └─ emms-cache-set-from-mpd-all

+emms/mpd-kill-music-daemon
    │
    ├─ emms-stop
    └─ call-process "mpd" "--kill"
```

### データフロー図

```
[入力]                   [処理]                      [出力]

音楽ファイル/       ───▶ emms-insert-file      ───▶ プレイリストに追加
ディレクトリ              emms-insert-playlist

プレイリスト        ───▶ emms-playlist-mode    ───▶ トラック一覧表示

再生コマンド        ───▶ emms-start            ───▶ 音声出力
                          (MPD/システムプレイヤー)

MPD起動コマンド     ───▶ start-process "mpd"   ───▶ デーモン起動
                              │
                              ├─ mpc update   ───▶ DB更新
                              │
                              └─ emms-player  ───▶ MPD接続
                                 -mpd-connect
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/app/emms/config.el` | ソース | メイン設定ファイル、EMMS設定 |
| autoload.el | `modules/app/emms/autoload.el` | ソース | MPD制御関数 |
| packages.el | `modules/app/emms/packages.el` | 設定 | パッケージ依存関係定義 |
