Harmonia Media Player

PC内のローカル音楽ファイルを美しく・快適に再生・管理するためのプレミアムなデスクトップオーディオプレイヤーです。
Spotifyライクなイマーシブ・ダークテーマUIを採用し、高機能な再生エンジン、CDリッピング、完全ローカル分析によるスマートプレイリスト自動生成、音質無劣化（ロスレス）でのメタデータ/カバーアート編集、非ネイティブ音源の透過トランスコード再生を提供します。

---

主な特徴

1. Spotifyライクなイマーシブ・ダークUI

• 洗練されたダークテーマ: コンテンツ（ジャケット画像）を引き立てるニアブラック（#121212）基調のUI。
• 直感的な操作性: ピル型ボタン、サークルコントロール、Spotifyスタイルの右クリックコンテキストメニュー。
• レスポンシブ & スムーズな遷移: 楽曲からアルバム詳細、アーティスト別の絞り込み表示へシームレスに移動可能。

2. 高速＆大容量対応のローカルライブラリ管理

• ミリ秒クラスの超高速表示: Zustandインメモリキャッシュと仮想分割レンダリング（初期80曲+スクロール追従）により、10,000曲規模のライブラリでも瞬時に表示。
• バックグラウンドスキャン & 進捗通知: 音楽再生やUI操作を中断することなく、画面右下のプログレスバナーでスキャン進捗（件数、進行度、処理中ファイル）をリアルタイム表示。
• 自動カバー修復 (Healing): 欠損または破損したアルバムアートを起動時にバックグラウンドで自動再抽出。

3. 高度な再生エンジン & 10バンドイコライザー

• カスタム特権プロトコル (media://): HTTP Rangeリクエスト（Partial Content 206）対応により、大容量ハイレゾ音源でもシークが即座に反応。
• 透過的トランスコード再生: Chromiumが標準非対応のフォーマット（WMA等）を自動検知し、裏で高品質MP3（320kbps）へオンデマンド変換・キャッシュ再生。
• Web Audio API 10バンドEQ: 32Hz〜16kHzのグラフィックイコライザー、豊富なプリセット（Bass Boost, Vocal, Rock, Pop 等）および3つのカスタム保存枠を搭載。

4. ロスレス メタデータ & カバーアート編集

• 音質無劣化ファイル書き込み: FFmpeg（c:a copy）を活用し、音声データを再エンコードすることなくID3v2/メタデータおよびカバー画像をファイル本体へ直接埋め込み。
• アルバム一括編集: アルバム名、アーティスト、ジャンル、リリース年の一括更新およびジャケット画像（JPG/PNG/WebP/GIF）の設定に対応。

5. スマートプレイリスト自動生成 (ローカル分析エンジン)

• 完全オフライン & 超高速: 外部API通信やAPIキーなしで動作。DSP波形信号解析（RMS音圧、BPM、Brightness）とタグ情報を組み合わせ、1秒未満でムード別プレイリストを自動選出。
• 多彩なシチュエーション: リラックス＆カフェ、集中＆ワーク、エネルギッシュ、ドライブ、ヘビーローテーション、隠れた名曲などをワンクリックで生成・保存。

6. CD取り込み (CD Ripper)

• メタデータ自動取得: MusicBrainz API と連携し、DiscIDからアルバム名、アーティスト、トラック情報を自動取得。
• 高品質エンコード: FLAC（Lossless）、MP3、AAC、OGG、WAV へのエンコードおよび出力先カスタマイズに対応。

---

技術スタック

区分	技術	用途
デスクトップ基盤	Electron 34, TypeScript 5, Vite 6	メイン/レンダラー統合ビルド、クロスプラットフォーム対応
フロントエンド	React 19, Zustand 5, Lucide React	コンポーネント設計、状態管理、モダンアイコン
スタイリング	Vanilla CSS	Spotifyデザインシステムに準拠したデザイントークン設計
データベース	SQLite 3 (better-sqlite3)	高速メタデータ管理、再生履歴・統計保持（WALモード）
メディア処理	Web Audio API, music-metadata, FFmpeg (ffmpeg-static)	音声再生、タグ抽出、ロスレス書き込み、オンデマンド変換
外部連携	MusicBrainz API	CDアルバムメタデータ検索

---

画面構成

• Home: クイック検索、最近の再生、おすすめアルバム、ライブラリサマリー
• Library: 全曲（TrackList）、アルバムグリッド、アーティスト別絞り込み
• AlbumDetail: アルバムごとの楽曲一覧、カバー画像、一括再生、メタデータ編集
• PlaylistDetail: プレイリストの楽曲一覧・再生・管理
• SmartDiscovery: オフラインスマート分析によるシチュエーション別プレイリスト生成
• CDImport: CDの読み取り、メタデータ自動照合、リッピング
• Search: 楽曲・アルバム・アーティストの総合リアルタイム検索
• Settings: 音楽フォルダの追加/削除、再スキャン、ライブラリ管理

---

キーボードショートカット

キー	動作
Space	再生 / 一時停止
Ctrl + →	次の曲へスキップ
Ctrl + ←	前の曲へ戻る
Ctrl + ↑	音量アップ (+5%)
Ctrl + ↓	音量ダウン (-5%)
Ctrl + F	ホーム画面へ移動 / 検索フォーカス

---

必要要件

• Node.js: v18.0.0 以上 (v20+ 推奨)
• npm: v9.0.0 以上
• OS: Windows 10/11, Linux (Ubuntu/Fedora等)

---

インストール & 起動方法

1. リポジトリのクローンと依存関係のインストール

git clone <repository-url>
cd media-player
npm install

2. 開発サーバーの起動 (Vite + Electron)

npm run dev

3. プロダクションビルド

npm run build

4. 実行可能ファイル (.exe / インストーラー) の生成

# インストーラー (Harmonia Setup 1.0.0.exe) およびポータブル版 (Harmonia 1.0.0.exe) を生成
npm run dist

# またはポータブル版単体のみを生成
npm run build:portable

# またはインストーラー単体のみを生成
npm run build:installer

生成された実行ファイルは release/ フォルダに出力されます。

---

プロジェクト構成

media-player/
├── index.html                 # Renderer エントリHTML
├── package.json               # プロジェクト定義・依存関係
├── tsconfig.json              # TypeScript設定
├── vite.config.ts             # Vite + Electronビルド設定
├── DESIGN.md                  # Spotifyテーマ デザインガイドライン
├── README.md                  # 本ドキュメント
├── docs/
│   └── spec.md                # 詳細機能・設計仕様書
├── src/
│   ├── main/                  # Electron メインプロセス
│   │   ├── index.ts           # アプリ起動・IPCハンドラ・media://プロトコル
│   │   ├── preload.ts         # Preloadスクリプト (安全なAPIブリッジ)
│   │   └── services/          # バックエンドサービス群
│   │       ├── database.ts    # SQLite DB操作
│   │       ├── scanner.ts     # フォルダ走査 & メタデータ抽出
│   │       ├── tag-writer.ts  # FFmpegによるロスレスメタデータ書き込み
│   │       ├── transcoder.ts  # 非ネイティブ音源のMP3オンデマンド変換
│   │       ├── auto-playlist.ts # ローカルスマート分析エンジン
│   │       ├── audio-analyzer.ts # DSP波形信号解析
│   │       ├── cd-ripper.ts   # CD取り込み & MusicBrainz連携
│   │       └── ai.ts          # AI音楽アシスタント基盤
│   ├── renderer/              # Electron レンダラープロセス (React)
│   │   ├── main.tsx           # Reactエントリポイント
│   │   ├── App.tsx            # ルートコンポーネント & ウィンドウ制御
│   │   ├── styles/            # CSSデザインシステム
│   │   ├── components/        # 共通コンポーネント (NowPlaying, TrackList, 各種Modal等)
│   │   ├── pages/             # 各画面 (Home, Library, AlbumDetail, CDImport等)
│   │   ├── stores/            # Zustand状態管理 (player, library, playlist)
│   │   └── utils/             # ユーティリティ (URL変換, フォーマッタ)
│   └── shared/                # メイン・レンダラー共有の型定義 (TypeScript)

---

ライセンス

本プロジェクトは ISC License のもとで公開されています。