第一期：最小可用播放器 — 项目结构与关键代码框架

目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
music-player/
├── app/
│   ├── build.gradle.kts
│   ├── src/main/
│   │   ├── AndroidManifest.xml
│   │   ├── java/com/example/musicplayer/
│   │   │   │
│   │   │   ├── MusicPlayerApp.kt                 # Application 入口
│   │   │   │
│   │   │   ├── player/                            # ★ 播放器核心（接口隔离层）
│   │   │   │   ├── PlayerController.kt            #   播放控制接口
│   │   │   │   ├── PlaybackState.kt               #   播放状态数据类
│   │   │   │   ├── AudioOutputBackend.kt          #   音频输出后端接口（为后期 USB 预留）
│   │   │   │   └── ExoPlayerController.kt         #   第一期实现：基于 Media3 ExoPlayer
│   │   │   │
│   │   │   ├── service/                           # 后台播放服务
│   │   │   │   └── PlaybackService.kt             #   MediaSessionService 实现
│   │   │   │
│   │   │   ├── scanner/                           # 文件扫描
│   │   │   │   └── FileScanner.kt                 #   简易文件扫描器
│   │   │   │
│   │   │   ├── model/                             # 数据模型
│   │   │   │   └── AudioFile.kt                   #   音频文件模型
│   │   │   │
│   │   │   ├── ui/                                # Compose UI
│   │   │   │   ├── MainActivity.kt                #   主 Activity
│   │   │   │   ├── theme/
│   │   │   │   │   ├── Theme.kt
│   │   │   │   │   ├── Color.kt
│   │   │   │   │   └── Type.kt
│   │   │   │   ├── navigation/
│   │   │   │   │   └── AppNavigation.kt           #   导航路由
│   │   │   │   ├── screen/
│   │   │   │   │   ├── FileBrowserScreen.kt       #   文件浏览页
│   │   │   │   │   └── NowPlayingScreen.kt        #   正在播放页
│   │   │   │   └── component/
│   │   │   │       ├── MiniPlayer.kt              #   底部迷你播放条
│   │   │   │       └── PermissionHandler.kt       #   权限请求组件
│   │   │   │
│   │   │   └── di/                                # 依赖注入
│   │   │       └── AppModule.kt                   #   Hilt 模块
│   │   │
│   │   └── res/
│   │       ├── values/strings.xml
│   │       └── drawable/                          # 图标资源
│   │
│   └── src/test/                                  # 单元测试
│
├── build.gradle.kts                               # 项目级构建文件
├── settings.gradle.kts
└── gradle/libs.versions.toml                      # 版本目录

1. 依赖配置

gradle/libs.versions.toml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
[versions]
agp = "8.5.0"
kotlin = "2.0.0"
compose-bom = "2024.06.00"
media3 = "1.3.1"
hilt = "2.51.1"
navigation = "2.7.7"
lifecycle = "2.8.2"
coil = "2.6.0"

[libraries]
# Compose
compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
compose-ui = { group = "androidx.compose.ui", name = "ui" }
compose-material3 = { group = "androidx.compose.material3", name = "material3" }
compose-icons-extended = { group = "androidx.compose.material", name = "material-icons-extended" }
compose-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }

# Media3 (ExoPlayer)
media3-exoplayer = { group = "androidx.media3", name = "media3-exoplayer", version.ref = "media3" }
media3-session = { group = "androidx.media3", name = "media3-session", version.ref = "media3" }
media3-ui = { group = "androidx.media3", name = "media3-ui", version.ref = "media3" }

# Navigation
navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigation" }

# Hilt
hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
hilt-compiler = { group = "com.google.dagger", name = "hilt-android-compiler", version.ref = "hilt" }
hilt-navigation-compose = { group = "androidx.hilt", name = "hilt-navigation-compose", version = "1.2.0" }

# Lifecycle
lifecycle-runtime-compose = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose", version.ref = "lifecycle" }
lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }

# Image loading (封面图)
coil-compose = { group = "io.coil-kt", name = "coil-compose", version.ref = "coil" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
compose-compiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
ksp = { id = "com.google.devtools.ksp", version = "2.0.0-1.0.22" }

app/build.gradle.kts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.compose.compiler)
    alias(libs.plugins.hilt)
    alias(libs.plugins.ksp)
}

android {
    namespace = "com.example.musicplayer"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.example.musicplayer"
        minSdk = 26  // Android 8.0+，USB Host API 稳定
        targetSdk = 34
    }

    buildFeatures {
        compose = true
    }
}

dependencies {
    // Compose
    implementation(platform(libs.compose.bom))
    implementation(libs.compose.ui)
    implementation(libs.compose.material3)
    implementation(libs.compose.icons.extended)
    debugImplementation(libs.compose.tooling)

    // Media3
    implementation(libs.media3.exoplayer)
    implementation(libs.media3.session)
    implementation(libs.media3.ui)

    // Navigation
    implementation(libs.navigation.compose)

    // DI
    implementation(libs.hilt.android)
    ksp(libs.hilt.compiler)
    implementation(libs.hilt.navigation.compose)

    // Lifecycle
    implementation(libs.lifecycle.runtime.compose)
    implementation(libs.lifecycle.viewmodel.compose)

    // Image
    implementation(libs.coil.compose)
}

2. 核心接口设计（★ 重中之重）

这些接口是整个架构的骨架。后期换 FFmpeg + USB 独占时，只需要新增实现类，UI 层和 Service 层完全不动。

player/PlaybackState.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
package com.example.musicplayer.player

import com.example.musicplayer.model.AudioFile

/**
 * 播放状态，UI 层唯一需要观察的数据源
 */
data class PlaybackState(
    val currentTrack: AudioFile? = null,
    val isPlaying: Boolean = false,
    val positionMs: Long = 0L,
    val durationMs: Long = 0L,
    val queue: List<AudioFile> = emptyList(),
    val currentIndex: Int = -1,
    // 后期扩展：采样率、位深、输出设备等信息
    val outputInfo: OutputInfo = OutputInfo()
)

data class OutputInfo(
    val sampleRate: Int = 0,
    val bitDepth: Int = 0,
    val outputDevice: String = "System Default"
)

player/PlayerController.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
package com.example.musicplayer.player

import com.example.musicplayer.model.AudioFile
import kotlinx.coroutines.flow.StateFlow

/**
 * ★ 播放器控制接口 — 所有 UI 和 Service 只依赖这个接口
 *
 * 第一期实现：ExoPlayerController
 * 后期实现：NativePlayerController (FFmpeg + Oboe/USB)
 */
interface PlayerController {

    /** 播放状态的响应式数据流 */
    val playbackState: StateFlow<PlaybackState>

    /** 播放指定文件 */
    fun play(track: AudioFile)

    /** 播放队列中的指定位置 */
    fun playAt(index: Int)

    /** 设置播放队列 */
    fun setQueue(tracks: List<AudioFile>, startIndex: Int = 0)

    /** 暂停 / 恢复 */
    fun togglePlayPause()

    /** 跳到指定位置 (毫秒) */
    fun seekTo(positionMs: Long)

    /** 下一首 */
    fun next()

    /** 上一首 */
    fun previous()

    /** 停止并释放资源 */
    fun release()
}

player/AudioOutputBackend.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
package com.example.musicplayer.player

/**
 * ★ 音频输出后端接口 — 为后期 USB 独占预留
 *
 * 第一期：不需要直接使用，ExoPlayer 内部自带输出
 * 第三期：Oboe 实现
 * 第四期：USB Exclusive 实现
 *
 * 现在定义好接口，确保未来的架构方向
 */
interface AudioOutputBackend {

    /** 输出后端的名称 */
    val name: String

    /** 初始化输出设备 */
    fun open(sampleRate: Int, channels: Int, bitDepth: Int): Boolean

    /** 写入 PCM 数据 */
    fun write(buffer: ByteArray, offsetBytes: Int, sizeBytes: Int): Int

    /** 获取当前已播放的帧数（用于计算播放位置） */
    fun getPlayedFrames(): Long

    /** 暂停输出 */
    fun pause()

    /** 恢复输出 */
    fun resume()

    /** 关闭并释放 */
    fun close()
}

3. ExoPlayer 实现

player/ExoPlayerController.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
package com.example.musicplayer.player

import android.content.Context
import androidx.media3.common.MediaItem
import androidx.media3.common.Player
import androidx.media3.exoplayer.ExoPlayer
import com.example.musicplayer.model.AudioFile
import dagger.hilt.android.qualifiers.ApplicationContext
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class ExoPlayerController @Inject constructor(
    @ApplicationContext private val context: Context
) : PlayerController {

    private val _state = MutableStateFlow(PlaybackState())
    override val playbackState: StateFlow<PlaybackState> = _state.asStateFlow()

    private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
    private var positionJob: Job? = null

    private val exoPlayer: ExoPlayer by lazy {
        ExoPlayer.Builder(context).build().also { player ->
            player.addListener(object : Player.Listener {

                override fun onIsPlayingChanged(isPlaying: Boolean) {
                    _state.update { it.copy(isPlaying = isPlaying) }
                    if (isPlaying) startPositionTracking() else stopPositionTracking()
                }

                override fun onMediaItemTransition(mediaItem: MediaItem?, reason: Int) {
                    val index = player.currentMediaItemIndex
                    val queue = _state.value.queue
                    _state.update {
                        it.copy(
                            currentTrack = queue.getOrNull(index),
                            currentIndex = index,
                            durationMs = player.duration.coerceAtLeast(0)
                        )
                    }
                }

                override fun onPlaybackStateChanged(state: Int) {
                    if (state == Player.STATE_READY) {
                        _state.update { it.copy(durationMs = player.duration.coerceAtLeast(0)) }
                    }
                }
            })
        }
    }

    override fun play(track: AudioFile) {
        setQueue(listOf(track), 0)
    }

    override fun setQueue(tracks: List<AudioFile>, startIndex: Int) {
        _state.update { it.copy(queue = tracks, currentIndex = startIndex) }
        val mediaItems = tracks.map { MediaItem.fromUri(it.uri) }
        exoPlayer.setMediaItems(mediaItems, startIndex, 0L)
        exoPlayer.prepare()
        exoPlayer.play()
    }

    override fun playAt(index: Int) {
        exoPlayer.seekTo(index, 0L)
        exoPlayer.play()
    }

    override fun togglePlayPause() {
        if (exoPlayer.isPlaying) exoPlayer.pause() else exoPlayer.play()
    }

    override fun seekTo(positionMs: Long) {
        exoPlayer.seekTo(positionMs)
        _state.update { it.copy(positionMs = positionMs) }
    }

    override fun next() {
        if (exoPlayer.hasNextMediaItem()) exoPlayer.seekToNextMediaItem()
    }

    override fun previous() {
        // 播放超过 3 秒则回到开头，否则上一首
        if (exoPlayer.currentPosition > 3000) {
            exoPlayer.seekTo(0)
        } else if (exoPlayer.hasPreviousMediaItem()) {
            exoPlayer.seekToPreviousMediaItem()
        }
    }

    override fun release() {
        stopPositionTracking()
        scope.cancel()
        exoPlayer.release()
    }

    // ---------- 内部方法 ----------

    /** 每 200ms 更新一次播放进度 */
    private fun startPositionTracking() {
        stopPositionTracking()
        positionJob = scope.launch {
            while (isActive) {
                _state.update { it.copy(positionMs = exoPlayer.currentPosition.coerceAtLeast(0)) }
                delay(200)
            }
        }
    }

    private fun stopPositionTracking() {
        positionJob?.cancel()
        positionJob = null
    }

    /** 暴露内部 ExoPlayer 实例，仅供 PlaybackService 使用 */
    fun getExoPlayer(): ExoPlayer = exoPlayer
}

4. 后台播放服务

service/PlaybackService.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
package com.example.musicplayer.service

import androidx.media3.common.Player
import androidx.media3.session.MediaSession
import androidx.media3.session.MediaSessionService
import com.example.musicplayer.player.ExoPlayerController
import dagger.hilt.android.AndroidEntryPoint
import javax.inject.Inject

/**
 * 后台播放服务
 *
 * 负责：
 * - 保持后台播放
 * - 显示通知栏控制
 * - 响应蓝牙/耳机按键
 * - 与系统 MediaSession 集成（锁屏控制等）
 */
@AndroidEntryPoint
class PlaybackService : MediaSessionService() {

    @Inject
    lateinit var playerController: ExoPlayerController

    private var mediaSession: MediaSession? = null

    override fun onCreate() {
        super.onCreate()
        mediaSession = MediaSession.Builder(this, playerController.getExoPlayer())
            .build()
    }

    override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaSession? {
        return mediaSession
    }

    override fun onDestroy() {
        mediaSession?.run {
            player.release()
            release()
        }
        mediaSession = null
        super.onDestroy()
    }
}

5. 数据模型与文件扫描

model/AudioFile.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
package com.example.musicplayer.model

import android.net.Uri

data class AudioFile(
    val uri: Uri,
    val displayName: String,
    val title: String = displayName,
    val artist: String = "未知艺术家",
    val album: String = "未知专辑",
    val durationMs: Long = 0L,
    val size: Long = 0L,
    val mimeType: String = "",
    // 后期扩展
    val sampleRate: Int = 0,
    val bitDepth: Int = 0
)

scanner/FileScanner.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
package com.example.musicplayer.scanner

import android.content.ContentUris
import android.content.Context
import android.provider.MediaStore
import com.example.musicplayer.model.AudioFile
import dagger.hilt.android.qualifiers.ApplicationContext
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import javax.inject.Inject
import javax.inject.Singleton

@Singleton
class FileScanner @Inject constructor(
    @ApplicationContext private val context: Context
) {
    /**
     * 通过 MediaStore 扫描本地音频文件
     * 简单高效，不需要自己遍历文件系统
     */
    suspend fun scanAllAudio(): List<AudioFile> = withContext(Dispatchers.IO) {
        val audioFiles = mutableListOf<AudioFile>()

        val projection = arrayOf(
            MediaStore.Audio.Media._ID,
            MediaStore.Audio.Media.DISPLAY_NAME,
            MediaStore.Audio.Media.TITLE,
            MediaStore.Audio.Media.ARTIST,
            MediaStore.Audio.Media.ALBUM,
            MediaStore.Audio.Media.DURATION,
            MediaStore.Audio.Media.SIZE,
            MediaStore.Audio.Media.MIME_TYPE
        )

        // 过滤掉短音频（铃声、通知音等）
        val selection = "${MediaStore.Audio.Media.DURATION} > ?"
        val selectionArgs = arrayOf("30000") // > 30 秒

        val sortOrder = "${MediaStore.Audio.Media.TITLE} ASC"

        context.contentResolver.query(
            MediaStore.Audio.Media.EXTERNAL_CONTENT_URI,
            projection,
            selection,
            selectionArgs,
            sortOrder
        )?.use { cursor ->
            val idCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media._ID)
            val nameCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.DISPLAY_NAME)
            val titleCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.TITLE)
            val artistCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.ARTIST)
            val albumCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.ALBUM)
            val durationCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.DURATION)
            val sizeCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.SIZE)
            val mimeCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.MIME_TYPE)

            while (cursor.moveToNext()) {
                val id = cursor.getLong(idCol)
                val uri = ContentUris.withAppendedId(
                    MediaStore.Audio.Media.EXTERNAL_CONTENT_URI, id
                )
                audioFiles.add(
                    AudioFile(
                        uri = uri,
                        displayName = cursor.getString(nameCol) ?: "Unknown",
                        title = cursor.getString(titleCol) ?: "Unknown",
                        artist = cursor.getString(artistCol) ?: "未知艺术家",
                        album = cursor.getString(albumCol) ?: "未知专辑",
                        durationMs = cursor.getLong(durationCol),
                        size = cursor.getLong(sizeCol),
                        mimeType = cursor.getString(mimeCol) ?: ""
                    )
                )
            }
        }

        audioFiles
    }
}

6. 依赖注入

di/AppModule.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
package com.example.musicplayer.di

import com.example.musicplayer.player.ExoPlayerController
import com.example.musicplayer.player.PlayerController
import dagger.Binds
import dagger.Module
import dagger.hilt.InstallIn
import dagger.hilt.components.SingletonComponent

@Module
@InstallIn(SingletonComponent::class)
abstract class AppModule {

    /**
     * ★ 关键绑定：所有依赖 PlayerController 接口的地方
     *   都会拿到 ExoPlayerController 的实例
     *
     * 后期切换引擎时，只需要改这一行：
     *   ExoPlayerController → NativePlayerController
     */
    @Binds
    abstract fun bindPlayerController(
        impl: ExoPlayerController
    ): PlayerController
}

MusicPlayerApp.kt

1
2
3
4
5
6
7
package com.example.musicplayer

import android.app.Application
import dagger.hilt.android.HiltAndroidApp

@HiltAndroidApp
class MusicPlayerApp : Application()

7. UI 层

ui/MainActivity.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
package com.example.musicplayer.ui

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import com.example.musicplayer.ui.navigation.AppNavigation
import com.example.musicplayer.ui.theme.MusicPlayerTheme
import dagger.hilt.android.AndroidEntryPoint

@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            MusicPlayerTheme {
                AppNavigation()
            }
        }
    }
}

ui/navigation/AppNavigation.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
package com.example.musicplayer.ui.navigation

import androidx.compose.foundation.layout.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.rememberNavController
import com.example.musicplayer.ui.component.MiniPlayer
import com.example.musicplayer.ui.screen.FileBrowserScreen
import com.example.musicplayer.ui.screen.NowPlayingScreen

@Composable
fun AppNavigation() {
    val navController = rememberNavController()

    // Scaffold 结构：主内容 + 底部迷你播放条
    Box(modifier = Modifier.fillMaxSize()) {
        Column(modifier = Modifier.fillMaxSize()) {
            // 主内容区域
            NavHost(
                navController = navController,
                startDestination = "browser",
                modifier = Modifier.weight(1f)
            ) {
                composable("browser") {
                    FileBrowserScreen(
                        onTrackClick = { /* 点击歌曲时的处理在 ViewModel 中 */ },
                        onOpenNowPlaying = { navController.navigate("now_playing") }
                    )
                }
                composable("now_playing") {
                    NowPlayingScreen(
                        onBack = { navController.popBackStack() }
                    )
                }
            }

            // 底部迷你播放条（始终显示）
            MiniPlayer(
                onClick = { navController.navigate("now_playing") }
            )
        }
    }
}

ui/screen/FileBrowserScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
package com.example.musicplayer.ui.screen

import android.Manifest
import android.os.Build
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.MusicNote
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import com.example.musicplayer.model.AudioFile
import com.example.musicplayer.player.PlayerController
import com.example.musicplayer.scanner.FileScanner
import com.example.musicplayer.ui.component.PermissionHandler
import dagger.hilt.android.lifecycle.HiltViewModel
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import javax.inject.Inject

// ---------- ViewModel ----------

@HiltViewModel
class FileBrowserViewModel @Inject constructor(
    private val scanner: FileScanner,
    private val player: PlayerController
) : ViewModel() {

    private val _tracks = MutableStateFlow<List<AudioFile>>(emptyList())
    val tracks = _tracks.asStateFlow()

    private val _isLoading = MutableStateFlow(false)
    val isLoading = _isLoading.asStateFlow()

    fun loadTracks() {
        viewModelScope.launch {
            _isLoading.value = true
            _tracks.value = scanner.scanAllAudio()
            _isLoading.value = false
        }
    }

    fun onTrackClick(index: Int) {
        val trackList = _tracks.value
        if (index in trackList.indices) {
            player.setQueue(trackList, index)
        }
    }
}

// ---------- Screen ----------

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun FileBrowserScreen(
    onTrackClick: () -> Unit = {},
    onOpenNowPlaying: () -> Unit = {},
    viewModel: FileBrowserViewModel = hiltViewModel()
) {
    val tracks by viewModel.tracks.collectAsStateWithLifecycle()
    val isLoading by viewModel.isLoading.collectAsStateWithLifecycle()

    // 处理存储权限
    val permission = if (Build.VERSION.SDK_INT >= 33) {
        Manifest.permission.READ_MEDIA_AUDIO
    } else {
        Manifest.permission.READ_EXTERNAL_STORAGE
    }

    PermissionHandler(
        permission = permission,
        onGranted = { viewModel.loadTracks() }
    )

    Scaffold(
        topBar = {
            TopAppBar(title = { Text("音乐库") })
        }
    ) { padding ->
        Box(
            modifier = Modifier
                .fillMaxSize()
                .padding(padding)
        ) {
            when {
                isLoading -> {
                    CircularProgressIndicator(
                        modifier = Modifier.align(Alignment.Center)
                    )
                }
                tracks.isEmpty() -> {
                    Text(
                        text = "未找到音频文件",
                        modifier = Modifier.align(Alignment.Center),
                        style = MaterialTheme.typography.bodyLarge
                    )
                }
                else -> {
                    LazyColumn(modifier = Modifier.fillMaxSize()) {
                        itemsIndexed(tracks) { index, track ->
                            TrackItem(
                                track = track,
                                onClick = { viewModel.onTrackClick(index) }
                            )
                        }
                    }
                }
            }
        }
    }
}

@Composable
private fun TrackItem(track: AudioFile, onClick: () -> Unit) {
    ListItem(
        headlineContent = {
            Text(track.title, maxLines = 1, overflow = TextOverflow.Ellipsis)
        },
        supportingContent = {
            Text(
                "${track.artist} · ${formatDuration(track.durationMs)}",
                maxLines = 1,
                overflow = TextOverflow.Ellipsis
            )
        },
        leadingContent = {
            Icon(Icons.Default.MusicNote, contentDescription = null)
        },
        modifier = Modifier.clickable(onClick = onClick)
    )
}

private fun formatDuration(ms: Long): String {
    val totalSeconds = ms / 1000
    val minutes = totalSeconds / 60
    val seconds = totalSeconds % 60
    return "%d:%02d".format(minutes, seconds)
}

ui/screen/NowPlayingScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
package com.example.musicplayer.ui.screen

import androidx.compose.foundation.layout.*
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.filled.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import com.example.musicplayer.player.PlaybackState
import com.example.musicplayer.player.PlayerController
import dagger.hilt.android.lifecycle.HiltViewModel
import javax.inject.Inject

@HiltViewModel
class NowPlayingViewModel @Inject constructor(
    private val player: PlayerController
) : ViewModel() {
    val playbackState = player.playbackState

    fun togglePlayPause() = player.togglePlayPause()
    fun seekTo(ms: Long) = player.seekTo(ms)
    fun next() = player.next()
    fun previous() = player.previous()
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun NowPlayingScreen(
    onBack: () -> Unit,
    viewModel: NowPlayingViewModel = hiltViewModel()
) {
    val state by viewModel.playbackState.collectAsStateWithLifecycle()

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("正在播放") },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, "返回")
                    }
                }
            )
        }
    ) { padding ->
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(padding)
                .padding(24.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            // 专辑封面占位（后期替换为真实封面）
            Card(
                modifier = Modifier.size(280.dp),
                colors = CardDefaults.cardColors(
                    containerColor = MaterialTheme.colorScheme.surfaceVariant
                )
            ) {
                Box(
                    modifier = Modifier.fillMaxSize(),
                    contentAlignment = Alignment.Center
                ) {
                    Icon(
                        Icons.Default.MusicNote,
                        contentDescription = null,
                        modifier = Modifier.size(80.dp),
                        tint = MaterialTheme.colorScheme.onSurfaceVariant
                    )
                }
            }

            Spacer(Modifier.height(32.dp))

            // 歌曲信息
            Text(
                text = state.currentTrack?.title ?: "未播放",
                style = MaterialTheme.typography.headlineSmall,
                maxLines = 1,
                overflow = TextOverflow.Ellipsis,
                textAlign = TextAlign.Center
            )
            Text(
                text = state.currentTrack?.artist ?: "",
                style = MaterialTheme.typography.bodyMedium,
                color = MaterialTheme.colorScheme.onSurfaceVariant,
                maxLines = 1
            )

            Spacer(Modifier.height(24.dp))

            // 进度条
            Column(modifier = Modifier.fillMaxWidth()) {
                Slider(
                    value = if (state.durationMs > 0) {
                        state.positionMs.toFloat() / state.durationMs.toFloat()
                    } else 0f,
                    onValueChange = { fraction ->
                        viewModel.seekTo((fraction * state.durationMs).toLong())
                    }
                )
                Row(
                    modifier = Modifier.fillMaxWidth(),
                    horizontalArrangement = Arrangement.SpaceBetween
                ) {
                    Text(formatTime(state.positionMs), style = MaterialTheme.typography.bodySmall)
                    Text(formatTime(state.durationMs), style = MaterialTheme.typography.bodySmall)
                }
            }

            Spacer(Modifier.height(16.dp))

            // 播放控制按钮
            Row(
                modifier = Modifier.fillMaxWidth(),
                horizontalArrangement = Arrangement.SpaceEvenly,
                verticalAlignment = Alignment.CenterVertically
            ) {
                IconButton(onClick = { viewModel.previous() }) {
                    Icon(Icons.Default.SkipPrevious, "上一首", Modifier.size(36.dp))
                }
                FilledIconButton(
                    onClick = { viewModel.togglePlayPause() },
                    modifier = Modifier.size(64.dp)
                ) {
                    Icon(
                        if (state.isPlaying) Icons.Default.Pause else Icons.Default.PlayArrow,
                        contentDescription = if (state.isPlaying) "暂停" else "播放",
                        modifier = Modifier.size(36.dp)
                    )
                }
                IconButton(onClick = { viewModel.next() }) {
                    Icon(Icons.Default.SkipNext, "下一首", Modifier.size(36.dp))
                }
            }

            Spacer(Modifier.height(16.dp))

            // 输出信息（为后期 USB 独占做预留展示）
            if (state.outputInfo.sampleRate > 0) {
                Text(
                    text = "${state.outputInfo.sampleRate}Hz / ${state.outputInfo.bitDepth}bit · ${state.outputInfo.outputDevice}",
                    style = MaterialTheme.typography.labelSmall,
                    color = MaterialTheme.colorScheme.outline
                )
            }
        }
    }
}

private fun formatTime(ms: Long): String {
    val totalSec = ms / 1000
    return "%d:%02d".format(totalSec / 60, totalSec % 60)
}

ui/component/MiniPlayer.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
package com.example.musicplayer.ui.component

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.*
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.MusicNote
import androidx.compose.material.icons.filled.Pause
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material3.*
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import com.example.musicplayer.player.PlayerController
import dagger.hilt.android.lifecycle.HiltViewModel
import javax.inject.Inject

@HiltViewModel
class MiniPlayerViewModel @Inject constructor(
    private val player: PlayerController
) : ViewModel() {
    val playbackState = player.playbackState
    fun togglePlayPause() = player.togglePlayPause()
}

@Composable
fun MiniPlayer(
    onClick: () -> Unit,
    viewModel: MiniPlayerViewModel = hiltViewModel()
) {
    val state by viewModel.playbackState.collectAsStateWithLifecycle()
    val track = state.currentTrack ?: return  // 没有在播放时不显示

    Surface(tonalElevation = 3.dp) {
        Column {
            // 进度指示条
            if (state.durationMs > 0) {
                LinearProgressIndicator(
                    progress = { state.positionMs.toFloat() / state.durationMs.toFloat() },
                    modifier = Modifier.fillMaxWidth().height(2.dp),
                )
            }
            Row(
                modifier = Modifier
                    .fillMaxWidth()
                    .clickable(onClick = onClick)
                    .padding(horizontal = 16.dp, vertical = 8.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                Icon(Icons.Default.MusicNote, null, Modifier.size(40.dp))
                Spacer(Modifier.width(12.dp))
                Column(modifier = Modifier.weight(1f)) {
                    Text(
                        track.title,
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis,
                        style = MaterialTheme.typography.bodyMedium
                    )
                    Text(
                        track.artist,
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis,
                        style = MaterialTheme.typography.bodySmall,
                        color = MaterialTheme.colorScheme.onSurfaceVariant
                    )
                }
                IconButton(onClick = { viewModel.togglePlayPause() }) {
                    Icon(
                        if (state.isPlaying) Icons.Default.Pause else Icons.Default.PlayArrow,
                        contentDescription = null
                    )
                }
            }
        }
    }
}

ui/component/PermissionHandler.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package com.example.musicplayer.ui.component

import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.result.contract.ActivityResultContracts
import androidx.compose.runtime.*

@Composable
fun PermissionHandler(
    permission: String,
    onGranted: () -> Unit
) {
    var hasPermission by remember { mutableStateOf(false) }

    val launcher = rememberLauncherForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->
        hasPermission = granted
        if (granted) onGranted()
    }

    LaunchedEffect(Unit) {
        launcher.launch(permission)
    }
}

8. AndroidManifest.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- 读取音频文件 -->
    <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
        android:maxSdkVersion="32" />

    <!-- 前台服务（后台播放） -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <!-- ★ 后期 USB 独占用 -->
    <uses-feature android:name="android.hardware.usb.host" android:required="false" />
    <uses-permission android:name="android.permission.USB_PERMISSION" />

    <application
        android:name=".MusicPlayerApp"
        android:label="Music Player"
        android:icon="@mipmap/ic_launcher"
        android:theme="@style/Theme.MusicPlayer"
        android:allowBackup="true">

        <activity
            android:name=".ui.MainActivity"
            android:exported="true"
            android:launchMode="singleTop">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <service
            android:name=".service.PlaybackService"
            android:exported="true"
            android:foregroundServiceType="mediaPlayback">
            <intent-filter>
                <action android:name="androidx.media3.session.MediaSessionService" />
            </intent-filter>
        </service>

    </application>
</manifest>

9. 架构要点总结

为什么这样设计

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
               ┌──────────────┐
               │   UI 层      │  只依赖 PlayerController 接口
               │  (Compose)   │  通过 StateFlow 观察状态
               └──────┬───────┘
                      │
               ┌──────▼───────┐
               │ PlayerController │  ← 接口
               └──────┬───────┘
                      │
         ┌────────────┼────────────┐
         │                         │
┌────────▼────────┐     ┌─────────▼──────────┐
│ ExoPlayerController │  │ NativePlayerController │
│   (第一期)          │  │   (第三/四期)           │
│   Media3 ExoPlayer  │  │   FFmpeg + Oboe/USB   │
└─────────────────┘     └────────────────────┘

后期替换引擎只需要做三件事

  1. 写一个 NativePlayerController 实现 PlayerController 接口
  2. 写一个 UsbExclusiveBackend 实现 AudioOutputBackend 接口
  3. 在 AppModule.kt 中把绑定改一行：
    1
    2
    3
    4
    @Binds
    abstract fun bindPlayerController(
        impl: NativePlayerController  // 改这里
    ): PlayerController

UI 层和 Service 层 零修改。

第一期完成后的效果

  • 打开 App → 自动请求权限 → 扫描音频
  • 看到歌曲列表（标题、艺术家、时长）
  • 点击播放，底部出现迷你播放条
  • 点击迷你播放条进入全屏播放页
  • 支持暂停/恢复、上一首/下一首、进度拖动
  • 切到后台继续播放，通知栏显示控制按钮
  • 蓝牙耳机/有线耳机按键可控制

说些什么吧！

beaudar