Obsidian/项目文档/同力/蓝牙音乐/蓝牙音乐模块功能流程梳理_2026-07-13.md

# 蓝牙音乐模块功能流程梳理

更新时间：2026-07-13  
工程路径：`F:\zdCode\tongli`  
当前蓝牙音乐提交：`8ec79048 modify(YX_BlueTooth):新增蓝牙音乐功能`

## 1. 一句话结论

蓝牙音乐模块不是本地音乐播放器，而是 **车机作为 A2DP Sink 接收手机音频 + 作为 AVRCP Controller 控制手机播放器**。

也就是说：

- 音频从手机通过蓝牙 A2DP 传到车机。
- 播放、暂停、上一首、下一首通过 AVRCP 控制手机端播放器。
- 歌名、歌手、播放进度、总时长来自手机蓝牙媒体会话回调。
- 当前 UI 按老项目效果固定显示默认蓝牙音乐封面，不加载手机专辑图。

## 2. 模块边界

### 2.1 负责的功能

| 功能 | 当前实现 |
|---|---|
| 蓝牙音乐入口 | 主界面左侧“蓝牙音乐”菜单进入 `BtMusicFragment` |
| 独立音乐页 | `BluetoothMusicActivity` 已注册，但当前主要入口是主界面 Fragment |
| A2DP 状态 | 判断 A2DP 是否连接，未连接时显示连接提示 |
| A2DP 自动连接 | 已有手机设备且 A2DP 未连接时，尝试连接 A2DP |
| 播放控制 | 播放、暂停、上一首、下一首 |
| 歌曲信息 | 歌名、歌手、当前时间、总时长、进度 |
| 音频焦点 | 播放前申请蓝牙音乐焦点，焦点丢失时暂停/静音 |
| UI 对齐 | 已按老项目蓝牙音乐页 UI 对齐 |

### 2.2 不负责的功能

| 不负责项 | 说明 |
|---|---|
| 本地音乐扫描 | 不扫描 U 盘、本地文件或歌单 |
| 本地解码播放 | 不直接解码 mp3/flac 等媒体文件 |
| 手机歌单浏览 | 当前只做基础播放控制，不展示手机媒体库列表 |
| 专辑封面展示 | 当前按老项目固定显示默认蓝牙音乐图 |
| 蓝牙配对搜索完整流程 | 属于蓝牙设置模块 |

## 3. 关键代码入口

| 层级 | 文件 | 作用 |
|---|---|---|
| 主入口 | `YX_BlueTooth/src/main/java/com/yaxon/bluetooth/main/MainActivity.java` | 左侧菜单切换到蓝牙音乐页 |
| Fragment UI | `YX_BlueTooth/src/main/java/com/yaxon/bluetooth/fragment/BtMusicFragment.java` | 主界面内的蓝牙音乐页面 |
| 独立 Activity | `YX_BlueTooth/src/main/java/com/yaxon/bluetooth/main/BluetoothMusicActivity.java` | 独立蓝牙音乐页面 |
| ViewModel | `YX_BlueTooth/src/main/java/com/yaxon/bluetooth/viewmodel/BtMusicViewModel.java` | UI 与 SDK 之间的桥接层 |
| 控制门面 | `YX_BluetoothSDK/src/main/java/com/yaxon/bluetoothsdk/manager/BtMusicControlManager.java` | 对外提供蓝牙音乐控制 API |
| 音乐管理 | `YX_BluetoothSDK/src/main/java/com/yaxon/bluetoothsdk/modules/BtMusicManager.java` | 处理 AVRCP、A2DP、回调分发 |
| AVRCP 客户端 | `YX_BluetoothSDK/src/main/java/com/yaxon/bluetoothsdk/platform/BluetoothAvrcpClient.java` | 连接系统蓝牙媒体服务，发送播放控制 |
| MediaBrowser | `YX_BluetoothSDK/src/main/java/com/yaxon/bluetoothsdk/platform/MediaBrowserClient.java` | 连接 `com.android.bluetooth.avrcpcontroller.BluetoothMediaBrowserService` |
| 音频焦点 | `YX_BluetoothSDK/src/main/java/com/yaxon/bluetoothsdk/audio/BtMusicAudioManager.java` | 申请/释放音频焦点，处理焦点变化 |
| A2DP 设置 | `YX_BluetoothSDK/src/main/java/com/yaxon/bluetoothsdk/manager/BtSettingControlManager.java` | 判断/连接 A2DP |

## 4. 总体架构流程

这一节先看分层，再看两条主链路：**控制链路** 和 **回调链路**。这样比一张横向大图更清楚。

### 4.1 分层架构图

图里只保留层级关系，详细类名放到下方表格，避免图过大。

```mermaid
flowchart TB
    A["页面层"]
    B["ViewModel"]
    C["SDK 管理层"]
    D["系统蓝牙服务"]
    E["手机端"]

    A --> B
    B --> C
    C --> D
    D --> E
```

| 层级 | 关键类 | 作用 |
|---|---|---|
| UI | `BtMusicFragment` / `BluetoothMusicActivity` | 显示界面，接收按钮点击 |
| ViewModel | `BtMusicViewModel` | 连接 UI 和 SDK，分发 LiveData |
| SDK 控制 | `BtMusicControlManager` / `BtSettingControlManager` | 对外提供播放控制、A2DP 连接接口 |
| 业务管理 | `BtMusicManager` | 组织 AVRCP、A2DP、焦点和回调 |
| AVRCP 控制 | `BluetoothAvrcpClient` / `MediaBrowserClient` | 控制手机播放器，接收媒体状态 |
| A2DP 音频 | `BluetoothA2dpSinkClient` | 接收手机蓝牙音频 |
| 音频焦点 | `BtMusicAudioManager` / `AudioManager` | 申请焦点、静音/解除静音、处理焦点丢失 |
| 系统蓝牙 | `BluetoothMediaBrowserService` / A2DP Sink Service | Android 蓝牙系统服务 |
| 手机 | 手机音乐播放器 / 手机蓝牙音频 | 真正播放音乐并输出 A2DP 音频 |

SDK 管理层内部再分三条线：

| 内部链路 | 关键类 | 解决的问题 |
|---|---|---|
| AVRCP 控制 | `BtMusicManager` / `BluetoothAvrcpClient` / `MediaBrowserClient` | 播放、暂停、上一首、下一首 |
| A2DP 音频 | `BtSettingControlManager` / `BluetoothA2dpSinkClient` | 建立手机到车机的音频通道 |
| 音频焦点 | `BtMusicAudioManager` / `AudioManager` | 决定蓝牙音乐能不能出声、是否要暂停或静音 |

### 4.2 播放控制链路

用户点按钮时，命令从上往下走，最后控制手机播放器。

```mermaid
flowchart TB
    A["用户操作"]
    B["页面处理"]
    C["ViewModel 转发"]
    D["SDK 控制"]
    E["系统媒体控制"]
    F["手机播放器"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
```

| 步骤 | 代码定位 | 说明 |
|---|---|---|
| 用户操作 | `iv_bt_music_state` / `iv_bt_music_pre` / `iv_bt_music_next` | 用户点击播放控制按钮 |
| 页面处理 | `BtMusicFragment.onClick` / `BluetoothMusicActivity.onClick` | 判断操作类型 |
| ViewModel 转发 | `BtMusicViewModel.playBtMusic / pauseBtMusic / preBtMusic / nextBtMusic` | UI 不直接碰 SDK |
| SDK 控制 | `BtMusicControlManager` / `BtMusicManager` | 申请焦点并组织 AVRCP 命令 |
| 系统媒体控制 | `BluetoothAvrcpClient` / `MediaBrowserClient` / `TransportControls` | 调用系统蓝牙媒体控制 |
| 手机播放器 | 手机音乐 App | 最终执行播放、暂停、切歌 |

### 4.3 状态回调链路

手机端播放状态变化后，状态从下往上回到 UI。

```mermaid
flowchart TB
    A["手机播放器"]
    B["系统媒体服务"]
    C["SDK 回调处理"]
    D["ViewModel LiveData"]
    E["页面刷新"]

    A --> B
    B --> C
    C --> D
    D --> E
```

| 步骤 | 代码定位 | 说明 |
|---|---|---|
| 手机播放器 | 手机音乐 App | 歌曲、进度、播放状态变化 |
| 系统媒体服务 | `BluetoothMediaBrowserService` | Android 蓝牙 AVRCP Controller 媒体服务 |
| SDK 回调处理 | `MediaBrowserClient` / `BluetoothAvrcpClient` / `BtMusicManager` | 接收并转换媒体状态 |
| ViewModel LiveData | `BtMusicViewModel.mLiveDataMusicInfo` / `mLiveDataPlayState` | 把状态推给 UI |
| 页面刷新 | `BtMusicFragment` / `BluetoothMusicActivity` | 刷新按钮、歌名、时间、进度 |

### 4.4 A2DP 与音频焦点链路

这条链路决定车机是否能真正出声。

先看 A2DP 音频通道：

```mermaid
flowchart TB
    A["进入音乐页"]
    B["检查 A2DP"]
    C["连接手机 A2DP"]
    D["音频通道就绪"]
    E["车机扬声器输出"]

    A --> B
    B --> C
    C --> D
    D --> E
```

再看音频焦点：

```mermaid
flowchart TB
    A["点击播放"]
    B["申请音频焦点"]
    C["解除 A2DP 静音"]
    D["发送播放命令"]
    E["手机开始播放"]

    A --> B
    B --> C
    C --> D
    D --> E
```

| 链路 | 成功条件 | 失败表现 |
|---|---|---|
| A2DP 音频通道 | 手机 A2DP 已连接或连接成功 | UI 保持未连接，车机无蓝牙音乐声 |
| 音频焦点 | `requestAudioFocus` 成功 | 手机可能在播，但车机可能无声或被其他音源压住 |
| AVRCP 控制 | `TransportControls` 可用 | 播放/暂停/切歌命令可能无效 |

核心理解：

- UI 不直接操作系统蓝牙。
- UI 只调用 `BtMusicViewModel`。
- `BtMusicViewModel` 调 `BtMusicControlManager` 和 `BtSettingControlManager`。
- 真正播放控制走 `BluetoothAvrcpClient -> MediaBrowserClient -> TransportControls`。
- 真正音频通道走 A2DP Sink。
- 真正能不能出声，还取决于 A2DP 是否连接和音频焦点是否申请成功。

## 5. 初始化流程

蓝牙 SDK 初始化在应用启动时完成。

```mermaid
flowchart TD
    A["应用启动"]
    B["初始化蓝牙 SDK"]
    C["创建音乐管理器"]
    D["准备控制与音频能力"]
    E["注册媒体回调"]

    A --> B
    B --> C
    C --> D
    D --> E
```

涉及文件：

- `BluetoothApplication.java`
- `BluetoothSdkApplication.java`
- `BtMusicControlManager.java`
- `BtMusicManager.java`
- `BluetoothAvrcpClient.java`
- `MediaBrowserClient.java`
- `BtMusicAudioManager.java`

初始化细节：

| 步骤 | 代码定位 | 结果 |
|---|---|---|
| 应用启动 | `BluetoothApplication` | 进入蓝牙 SDK 应用基类 |
| 初始化蓝牙 SDK | `BluetoothSdkApplication.setPlatform` | 初始化各蓝牙业务模块 |
| 创建音乐管理器 | `BtMusicControlManager.init` | 持有 `BtMusicManager` |
| 准备控制与音频能力 | `BluetoothAvrcpClient` / `BtMusicAudioManager` / `BluetoothA2dpSinkClient` | 准备 AVRCP、焦点、A2DP |
| 注册媒体回调 | `MediaBrowserClient` | 连接系统媒体服务并监听状态 |

## 6. 入口切换流程

主界面左侧菜单有四个入口：

| 位置 | 入口 |
|---|---|
| 0 | 蓝牙拨号 |
| 1 | 联系人 |
| 2 | 蓝牙音乐 |
| 3 | 蓝牙设置 |

`Constant.TAB_BLUETOOTH_MUSIC = 2`。

```mermaid
flowchart TD
    A["点击蓝牙音乐"]
    B["切换菜单位置"]
    C["更新左侧选中态"]
    D["切到音乐 Fragment"]
    E["显示音乐页面"]

    A --> B
    B --> C
    C --> D
    D --> E
```

关键代码：

- `MainActivity.setPositionFragment`
- `Constant.TAB_BLUETOOTH_MUSIC`
- `BtMusicFragment`

入口代码定位：

| 步骤 | 代码定位 | 说明 |
|---|---|---|
| 点击蓝牙音乐 | `MainActivity.onItemClick` | 左侧菜单点击 |
| 切换菜单位置 | `setPositionFragment(position = 2)` | `2` 对应蓝牙音乐 |
| 更新左侧选中态 | `mMenuAdapter.setSelectedPosition` | 菜单高亮 |
| 切到音乐 Fragment | `toFragment(mBtMusicFragment)` | 页面容器替换 |
| 显示音乐页面 | `fragment_bt_music.xml` | 展示蓝牙音乐 UI |

## 7. 页面 UI 状态流程

蓝牙音乐 UI 由 `isBtConnect` 控制两种状态。

```mermaid
flowchart TD
    A["进入音乐页"]
    B{"A2DP 已连接"}
    C["音乐控制面板"]
    D["未连接提示"]

    A --> B
    B -->|是| C
    B -->|否| D
```

UI 文件：

- `fragment_bt_music.xml`
- `activity_bluetooth_music.xml`

主要控件：

| 控件 ID | 作用 |
|---|---|
| `iv_bt_music_album` | 默认蓝牙音乐封面 |
| `tv_bt_music_title` | 歌曲名 |
| `tv_bt_music_artist` | 歌手 |
| `seek_bt_music` | 播放进度展示，不允许拖动 |
| `tv_cur_time` | 当前播放时间 |
| `tv_song_time` | 总时长 |
| `iv_bt_music_pre` | 上一首 |
| `iv_bt_music_state` | 播放 / 暂停 |
| `iv_bt_music_next` | 下一首 |
| `ll_bt_connect_panel` | 未连接提示页 |
| `tv_connect_btn` | 连接蓝牙按钮，目前未实现跳转 |

状态对应关系：

| 状态 | 显示内容 | 触发条件 |
|---|---|---|
| 音乐控制面板 | 默认封面、歌名、歌手、进度条、三个控制按钮 | `isA2dpConnected == true` |
| 未连接提示 | 连接手机提示、连接蓝牙按钮 | `isA2dpConnected == false` |

## 8. A2DP 连接流程

A2DP 是手机音乐音频传到车机的通道。

进入页面后的检查：

```mermaid
flowchart TD
    A["进入音乐页"]
    B["检查 A2DP"]
    C["获取手机设备"]
    D["发起 A2DP 连接"]
    E["等待连接结果"]

    A --> B
    B --> C
    C --> D
    D --> E
```

分支规则：

| 判断点 | 是 | 否 |
|---|---|---|
| A2DP 是否已连接 | 显示音乐控制面板 | 继续获取已连接手机设备 |
| 已连接设备是否为手机 | 检查 A2DP 是否正在连接 | 保持未连接状态 |
| A2DP 是否正在连接 | 等待连接结果 | 调用 `connectA2dp(mac)` |

调用定位：

| 步骤 | 代码定位 |
|---|---|
| 进入音乐页 | `BtMusicFragment.onResume` / `BluetoothMusicActivity.onResume` |
| 检查 A2DP | `BtMusicViewModel.isA2dpConnected` |
| 获取手机设备 | `BtMusicFragment.btMusicInfo` / `BluetoothMusicActivity.btMusicInfo` |
| 发起连接 | `BtMusicViewModel.connectA2dp` |
| 底层连接 | `BtSettingControlManager.connectA2dp` / `BluetoothA2dpSinkClient` |

触发位置：

- `BtMusicFragment.btMusicInfo`
- `BluetoothMusicActivity.btMusicInfo`
- `BtMusicViewModel.connectA2dp`
- `BtSettingControlManager.connectA2dp`

连接结果回调：

```mermaid
flowchart TD
    A["A2DP 状态变化"]
    B["SDK 连接监听"]
    C["音乐管理器处理"]
    D["LiveData 通知"]
    E["UI 切换状态"]

    A --> B
    B --> C
    C --> D
    D --> E
```

| 步骤 | 代码定位 | 说明 |
|---|---|---|
| A2DP 状态变化 | 系统蓝牙服务 | A2DP 连接或断开 |
| SDK 连接监听 | `BluetoothConnectListenerClient` | 接收系统连接状态 |
| 音乐管理器处理 | `BtMusicManager.onA2dpConnect / onA2dpDisconnect` | 清理或恢复蓝牙音乐状态 |
| LiveData 通知 | `BtMusicViewModel.mLiveDataA2dpConnectStatus` | 通知 UI |
| UI 切换状态 | `BtMusicFragment` / `BluetoothMusicActivity` | 显示音乐页或未连接页 |

## 9. 播放控制流程

### 9.1 点击播放 / 暂停

```mermaid
flowchart TD
    A["点击按钮"]
    B{"当前在播放"}
    C["走暂停链路"]
    D["走播放链路"]
    E["手机播放器响应"]

    A --> B
    B -->|是| C
    B -->|否| D
    C --> E
    D --> E
```

| 分支 | 调用顺序 | 说明 |
|---|---|---|
| 播放 | `onClick -> isMusicPlaying == false -> playBtMusic -> requestFocus -> AVRCP play` | 先拿焦点，再发送播放 |
| 暂停 | `onClick -> isMusicPlaying == true -> pauseBtMusic -> AVRCP pause` | 暂停不需要重新申请焦点 |
| UI 更新 | `mLiveDataPlayState -> updatePlayState` | 最终以回调状态刷新图标 |

### 9.2 点击上一首 / 下一首

```mermaid
flowchart TD
    A["点击切歌"]
    B["ViewModel 转发"]
    C["SDK 申请焦点"]
    D["发送 AVRCP 命令"]
    E["手机播放器切歌"]

    A --> B
    B --> C
    C --> D
    D --> E
```

底层实际命令：

| 操作 | 页面入口 | ViewModel | 最终调用 |
|---|---|---|---|
| 播放 | `onClick` | `playBtMusic` | `TransportControls.play()` |
| 暂停 | `onClick` | `pauseBtMusic` | `TransportControls.pause()` |
| 下一首 | `onClick` | `nextBtMusic` | `TransportControls.skipToNext()` |
| 上一首 | `onClick` | `preBtMusic` | `TransportControls.skipToPrevious()` |

## 10. 歌曲信息与播放状态刷新流程

手机通过系统蓝牙 MediaBrowser 回传媒体状态。

播放状态回调：

```mermaid
flowchart TD
    A["手机播放状态变化"]
    B["系统媒体回调"]
    C["SDK 转换状态"]
    D["LiveData 通知"]
    E["刷新按钮和进度"]

    A --> B
    B --> C
    C --> D
    D --> E
```

歌曲信息回调：

```mermaid
flowchart TD
    A["手机歌曲变化"]
    B["系统元数据回调"]
    C["SDK 转换歌曲信息"]
    D["LiveData 通知"]
    E["刷新歌名和时长"]

    A --> B
    B --> C
    C --> D
    D --> E
```

代码定位：

| 回调类型 | SDK 入口 | ViewModel 入口 | UI 刷新内容 |
|---|---|---|---|
| 播放状态 | `onPlaybackStateChanged` | `onPlayMusicState / onPlayMusicInfo` | 播放按钮、当前进度、当前时间 |
| 歌曲信息 | `onMetadataChanged` | `onPlayMusicInfo` | 歌名、歌手、总时长 |

字段来源：

| 字段 | 来源 |
|---|---|
| 歌名 | `MediaMetadata.METADATA_KEY_TITLE` |
| 歌手 | `MediaMetadata.METADATA_KEY_ARTIST` |
| 专辑 | `MediaMetadata.METADATA_KEY_ALBUM` |
| 总时长 | `MediaMetadata.METADATA_KEY_DURATION` |
| 当前进度 | `PlaybackStateCompat.getPosition()` |
| 播放状态 | `PlaybackStateCompat.STATE_PLAYING` |

当前 UI 特殊点：

- `albumUrl` 虽然会接收，但 UI 不展示手机封面。
- 默认封面固定使用 `R.mipmap.icon_bluetooth_music`。

## 11. 音频焦点流程

蓝牙音乐播放前需要申请音频焦点，否则可能出现手机在播但车机无声或被其他音源压住。

申请焦点：

```mermaid
flowchart TD
    A["准备播放"]
    B["确认 A2DP"]
    C["请求音频焦点"]
    D["解除 A2DP 静音"]
    E["允许播放命令"]

    A --> B
    B --> C
    C --> D
    D --> E
```

失败规则：

| 失败点 | 结果 |
|---|---|
| A2DP 未连接 | `requestFocus` 返回 `false` |
| 音频焦点申请失败 | 不应认为蓝牙音乐已经有效播放 |
| MediaSession 未就绪 | AVRCP 控制可能无效 |

焦点变化：

```mermaid
flowchart TD
    A["焦点变化"]
    B["静音或恢复 A2DP"]
    C["暂停或恢复播放"]
    D["刷新音乐状态"]

    A --> B
    B --> C
    C --> D
```

焦点变化处理：

| 焦点事件 | 当前处理 |
|---|---|
| `AUDIOFOCUS_GAIN` | 解除 A2DP 静音；如果丢焦前在播，则恢复播放 |
| `AUDIOFOCUS_LOSS` | 释放焦点；暂停蓝牙音乐；清空 Launcher 音乐信息 |
| `AUDIOFOCUS_LOSS_TRANSIENT` | A2DP 静音；记录是否正在播放；暂停 |
| `AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK` | 降低 A2DP 音量 |

## 12. 断开与关闭流程

```mermaid
flowchart TD
    A["连接断开"]
    B["SDK 收到回调"]
    C["清空音乐缓存"]
    D["通知 UI 未连接"]
    E["显示未连接面板"]

    A --> B
    B --> C
    C --> D
    D --> E
```

相关回调：

- `onDisconnect`
- `onA2dpDisconnect`
- `onClose`
- `onBtDisconnect`
- `onBtClose`

清理内容：

| 清理项 | 目的 |
|---|---|
| `title / artist / album` | 避免断开后继续显示旧歌曲 |
| `progress / duration` | 避免进度条停在旧状态 |
| 播放状态 | 播放按钮恢复为播放图标 |
| `mLiveDataA2dpConnectStatus = false` | UI 切回未连接面板 |

## 13. 当前实现中的关键状态

| 状态 | 位置 | 含义 |
|---|---|---|
| `mLastPlayState` | `BtMusicFragment` / `BluetoothMusicActivity` | 记录上次播放状态，用于页面恢复时决定是否续播 |
| `musicPlaying` | `BtMusicViewModel` | 音频焦点丢失前是否在播放 |
| `mMusicInfo` | `BtMusicViewModel` | 最近一次音乐信息缓存 |
| `mLiveDataMusicInfo` | `BtMusicViewModel` | 歌曲信息 UI 通知 |
| `mLiveDataPlayState` | `BtMusicViewModel` | 播放状态 UI 通知 |
| `mLiveDataA2dpConnectStatus` | `BtMusicViewModel` | A2DP 连接状态 UI 通知 |
| `isFocus` | `BtMusicAudioManager` | 蓝牙音乐是否持有音频焦点 |
| `isPlayingLossFocus` | `BtMusicAudioManager` | 丢失焦点前是否在播放 |

## 14. 和老项目对齐的现状

已对齐：

- 主界面增加“蓝牙音乐”入口。
- 蓝牙音乐 UI 使用老项目默认封面和圆形控制按钮。
- 进度条资源复用老项目。
- 封面固定使用默认蓝牙音乐图，不使用手机专辑图。
- 歌名、歌手、进度、时间通过现有 SDK 刷新。
- 播放、暂停、上一首、下一首继续走新项目 SDK，不搬旧项目业务代码。

未完全补齐：

- 未连接状态下 `tv_connect_btn` 目前没有跳转蓝牙设置页。
- 没有“连接中”状态，例如 A2DP 正在连接时的进度提示。
- MediaBrowser 未连接时没有明显错误提示。
- 播放控制失败没有 UI 反馈。
- Fragment 与 Activity 两套蓝牙音乐逻辑重复，后续可抽公共逻辑。

## 15. 开发切入点

### 15.1 要改 UI

优先看：

- `fragment_bt_music.xml`
- `activity_bluetooth_music.xml`
- `selector_music_play.xml`
- `selector_music_pause.xml`
- `selector_music_pre.xml`
- `selector_music_next.xml`
- `bt_music_progress_layer.xml`

### 15.2 要改播放控制

优先看：

- `BtMusicFragment.onClick`
- `BluetoothMusicActivity.onClick`
- `BtMusicViewModel.playBtMusic / pauseBtMusic / preBtMusic / nextBtMusic`
- `BtMusicControlManager`
- `BtMusicManager`
- `BluetoothAvrcpClient`

### 15.3 要改连接逻辑

优先看：

- `BtMusicFragment.btMusicInfo`
- `BluetoothMusicActivity.btMusicInfo`
- `BtMusicViewModel.connectA2dp`
- `BtSettingControlManager.connectA2dp`
- `BluetoothA2dpSinkClient`

### 15.4 要改音频焦点

优先看：

- `BtMusicAudioManager.requestAudioFocus`
- `BtMusicAudioManager.releaseAudioFocus`
- `BtMusicAudioManager.mAudioFocusListener`
- `BtMusicManager.requestFocus`

## 16. 建议补齐的功能

| 优先级 | 功能 | 原因 |
|---|---|---|
| P0 | 未连接按钮跳转蓝牙设置页 | 用户当前只有蓝牙音乐入口，通过设置页跳转时需要闭环 |
| P0 | A2DP 连接中状态 | 避免点击后无反馈 |
| P1 | MediaBrowser 未连接提示 | 手机蓝牙媒体服务未就绪时便于定位 |
| P1 | 播放控制失败日志/提示 | AVRCP 命令可能因手机端播放器未启动而无效 |
| P1 | Fragment 和 Activity 逻辑复用 | 降低后续维护成本 |
| P2 | 进度条拖动 seek | 当前只展示，不支持拖动 |
| P2 | 专辑图开关 | 如果后续产品要求展示手机专辑图，可恢复 `albumUrl` 加载 |

## 17. 测试清单

### 17.1 正常流程

- 手机已配对并连接 HFP。
- 进入蓝牙音乐页。
- 自动检查并连接 A2DP。
- 手机打开音乐播放器。
- 点击播放，车机出声。
- 点击暂停，手机播放器暂停。
- 点击上一首/下一首，手机播放器切歌。
- 歌名、歌手、时间、进度刷新。

### 17.2 连接异常

- 未连接手机进入蓝牙音乐页，应显示未连接面板。
- 手机只连 HFP 未连 A2DP，进入音乐页应尝试连接 A2DP。
- A2DP 连接失败，应能从日志看到 `connectA2dp` 相关信息。
- 手机断开蓝牙，UI 应切回未连接状态。

### 17.3 焦点与打断

- 蓝牙音乐播放时来电，音乐应暂停或静音。
- 通话结束后，如果丢焦前在播，应尝试恢复。
- 切到收音机/USB 音乐，蓝牙音乐应释放或失去焦点。
- 重新切回蓝牙音乐，按状态恢复播放。

### 17.4 兼容性

- 不同手机品牌测试 AVRCP 元数据。
- 手机音乐 App 未打开时点击播放。
- 手机音乐 App 开着但无播放队列。
- 蓝牙断开后快速重连。
- 系统重启后首次进入蓝牙音乐。

## 18. 日志关键字

调试时可优先过滤这些关键字：

```text
BtMusicFragment
BluetoothMusicActivity
BtMusicViewModel
BtMusicControlManager
BtMusicManager
BtMusicAudioManager
BluetoothAvrcpClient
MediaBrowserHelper
connectA2dp
onA2dpConnect
onA2dpDisconnect
onPlaybackStateChanged
onMetadataChanged
requestAudioFocus
AUDIOFOCUS_GAIN
AUDIOFOCUS_LOSS
```

## 19. 总结

蓝牙音乐模块可以按四条主线理解：

1. **入口线**：`MainActivity -> BtMusicFragment`。
2. **连接线**：`BtMusicFragment -> BtMusicViewModel -> BtSettingControlManager -> A2DP`。
3. **控制线**：`按钮点击 -> BtMusicViewModel -> BtMusicControlManager -> BtMusicManager -> BluetoothAvrcpClient -> 手机播放器`。
4. **回调线**：`手机媒体状态 -> MediaBrowserClient -> BluetoothAvrcpClient -> BtMusicManager -> BtMusicViewModel LiveData -> UI`。

开发这个模块时，优先保证 A2DP 连接、AVRCP 控制、音频焦点三条链路可验证，再做 UI 微调和异常状态补齐。