音樂播放器

一個基於 Jetpack Compose 與 Media3 的 Android 音樂播放器。

功能

• 匯入音樂/影片 — 透過系統檔案選擇器加入 audio/mpeg 與 video/mp4 檔案
• 音樂庫瀏覽 — 依標題排序的所有歌曲列表，支援目前播放歌曲高亮
• 播放控制 — 播放/暫停、上一首/下一首、Seek 滑桿、重複模式（關閉/全部/單首）、隨機播放
• 影片播放 — 自動偵測影片格式並以 SurfaceView 16:9 顯示
• 播放清單 — 建立、刪除、拖曳排序、新增/移除歌曲、批次加入
• 批次操作 — 多選模式：批次刪除、批次加入播放清單
• 睡眠定時器 — 5/10/15/30/45/60 分鐘預設，倒數顯示於通知，結束後自動停止服務
• 背景播放 — Foreground Service 搭配 Media3 MediaSession，通知欄 5 個操作按鈕（上一首、播放/暫停、下一首、循環、關閉）
• 外部裝置控制 — 透過 Media3 MediaSession 支援藍牙、Android Auto 等控制
• 等化器 — 5 頻段滑桿 UI（視覺展示，尚未接入 DSP）
• 深色主題 — Spotify 風格綠色主色調

截圖

（待補）

技術棧

類別	套件
語言	Kotlin 1.9.24
UI	Jetpack Compose + Material 3
導航	Navigation Compose
播放器	Media3 ExoPlayer 1.3.1、Media3 Session
資料庫	Room 2.6.1（KSP）
非同步	Kotlin Coroutines 1.8.0
圖片載入	Coil 2.6.0（Compose + SVG）
拖曳排序	reorderable 2.1.1
最低 SDK	26（Android 8.0）
目標 SDK	34（Android 14）

架構

MVVM（Model-View-ViewModel）

UI Layer (Compose Screens)
    ↕ StateFlow
PlayerViewModel (AndroidViewModel)
    ↕
MusicConnection ←→ MusicService (LifecycleService)
                        ↕ ExoPlayer + MediaSession
    ↕
Repository ←→ Room Database

主要元件

• MusicService — 前景服務，管理 ExoPlayer、MediaSession、通知、睡眠定時器
• MusicConnection — ServiceConnection 封裝層，將服務端的 PlayerState 以 StateFlow 中繼至 ViewModel
• PlayerViewModel — 唯一的 ViewModel，管理播放狀態、匯入、播放清單操作
• MusicRepository — 資料層，封裝 Room DAO 與 ContentResolver 邏輯

專案結構

app/src/main/java/com/musicplayer/app/
├── MusicPlayerApp.kt          — Application，Coil ImageLoader 設定
├── MainActivity.kt             — 單一 Activity
├── data/
│   ├── db/                     — Room Database、DAO
│   ├── model/                  — Entity：Song、Playlist、PlaylistSongCrossRef
│   └── repository/             — MusicRepository
├── player/
│   ├── MusicService.kt         — ExoPlayer + 通知 + 睡眠定時器
│   ├── MusicConnection.kt      — Binder 封裝 + 狀態中繼
│   └── StopMusicReceiver.kt    — 關閉通知廣播接收器
├── viewmodel/
│   └── PlayerViewModel.kt      — 全 APP 共用 ViewModel
└── ui/
    ├── navigation/             — 底部導航 + NavHost
    ├── screens/                — HomeScreen、PlayerScreen、PlaylistScreen、PlaylistDetailScreen
    ├── components/             — PlayerControls、SongItem、SleepTimerDialog、EqualizerDialog
    └── theme/                  — 深色主題（Color、Type、Theme）

建置

./gradlew assembleDebug

權限

• POST_NOTIFICATIONS (Android 13+)
• FOREGROUND_SERVICE_MEDIA_PLAYBACK (Android 14+)
• READ_EXTERNAL_STORAGE / READ_MEDIA_AUDIO（透過系統檔案選擇器，非直接請求）