¶ SD卡离线音乐播放教程（TF卡）
¶ 前言
本教程将指导您如何在 Arcs-mini 开发板上实现SD卡离线音乐播放功能，支持语音控制播放。
本教程示例基于 2.2.0 版本的SDK进行修改，开始之前请先更新仓库代码（git pull --rebase)
¶ 一、效果演示
通过语音指令"播放本地音乐"，设备会自动播放SD卡中的MP3文件。
演示视频：
¶ 固件下载
如果您希望直接体验效果，可直接下载固件：mcp_tool_play_offline_music_sd.lpk
下载后，可以按照文档《恢复出厂固件 & 升级固件教程》 进行烧录
¶ 二、准备音乐资源
- 将SD卡格式化为FAT32格式
- 在SD卡根目录创建
music文件夹 - 将MP3文件放入
music文件夹 - 支持中英文文件名，建议命名格式：
序号_歌手_歌名.mp3
文件名示例：
/SD:/music/
├── 001_周杰伦_晴天.mp3
├── 002_周杰伦_枫.mp3
├── 003_方大同_春风吹.mp3
├── 004_陈奕迅_葡萄成熟时.mp3
└── 005_陈奕迅_十年.mp3
提示： 已启用中文文件名支持，可以使用中文命名音乐文件。如果您的MP3文件名包含中文，确保SD卡使用 UTF-8 或 FAT32 格式化。
¶ 三、SD卡硬件连接与初始化
¶ 1. 硬件连接
ARCS Mini开发板使用SDIO接口连接SD卡，默认引脚配置如下：
| 引脚 | 功能 | 说明 |
|---|---|---|
| 3.3V | 3.3V | 电源线 |
| GND | GND | 地线 |
| PA4 | DAT1 | 数据线1 |
| PA5 | DAT0 | 数据线0 |
| PA6 | CLK | 时钟信号 |
| PA7 | CMD | 命令线 |
| PA8 | DAT3 | 数据线3 |
| PA9 | DAT2 | 数据线2 |
¶ 2. 初始化SD卡
¶ 2.1 创建离线音乐服务文件（能够使用SD卡）
在 apps/arcs-mini/services/ 目录下创建以下文件：
- service_offline_music.h：头文件，定义服务接口
- service_offline_music.c：实现文件，包含SD卡初始化、音乐扫描、播放控制等功能
提示：完整的代码文件请参考：
主要功能：
- 自动探测和初始化SD卡
- 扫描SD卡中的MP3文件（默认路径：
/SD:/music/） - 支持播放指定索引的音乐
- 提供串口调试命令
¶ 2.2 修改 CMakeLists.txt（SD卡的代码能够参与编译）
在 apps/arcs-mini/services/CMakeLists.txt 中添加源文件：
listenai_library_named(app-services)
listenai_library_sources(
service_led.c
service_brightness.c
service_volume.c
service_button.c
service_camera.c
service_alarm.c
service_image.c
service_offline_music.c # 新增：离线音乐服务
)
代码位置： apps/arcs-mini/services/CMakeLists.txt:10
¶ 2.3 在 main.c 中初始化服务（调用SD卡的逻辑）
在 apps/arcs-mini/main.c 的初始化函数中添加：
service_led_init();
service_volume_init();
service_brightness_init();
service_button_init();
service_image_init();
service_offline_music_init(); // 新增：初始化离线音乐服务
代码位置： apps/arcs-mini/main.c:209
¶ 3. 启用文件系统（能够通过文件名访问资源文件）
¶ 3.1 基础配置
确保 apps/arcs-mini/prj.conf 中已启用以下配置：
CONFIG_FILE_SYSTEM=y
CONFIG_FATFS_FILESYSTEM=y
CONFIG_LSFS_REGISTER_VFS=y
CONFIG_LVFS=y
CONFIG_LVFS_POSIX_API=y
CONFIG_LVFS_POSIX_API_ALIAS=y
¶ 3.2 中文文件名支持（重要）
问题现象： 如果不启用中文支持，中文名称的MP3文件会显示为乱码：
[0] /SD:/music/001_周杰伦_晴天.mp3 ← 显示正常（已启用中文支持）
[1] /SD:/music/002_?~1.MP3 ← 显示乱码（未启用中文支持）
解决方案： 创建 FATFS 自定义配置文件，启用 Unicode 支持。
¶ 步骤 1：创建自定义配置文件
在 apps/arcs-mini/ 目录下创建 fatfs_custom_config.h 文件：
/**
* @file fatfs_custom_config.h
* @brief FATFS 中文文件名支持配置
*/
/* 启用 UTF-8 编码支持 */
#undef FF_LFN_UNICODE
#define FF_LFN_UNICODE 2 /* 使用 UTF-8 编码 */
/* 设置简体中文代码页 */
#undef FF_CODE_PAGE
#define FF_CODE_PAGE 936 /* 简体中文 */
/* 字符串 I/O 使用 UTF-8 */
#undef FF_STRF_ENCODE
#define FF_STRF_ENCODE 3 /* UTF-8 */
文件位置： apps/arcs-mini/fatfs_custom_config.h
¶ 步骤 2：在 prj.conf 中启用配置
在 apps/arcs-mini/prj.conf 文件末尾添加：
# FATFS 中文文件名支持
CONFIG_FATFS_FFCONF_OVERRIDE=y
CONFIG_FATFS_FFCONF_NAME="fatfs_custom_config.h"
配置位置： apps/arcs-mini/prj.conf:491-492
配置说明：
| 配置项 | 说明 |
|---|---|
CONFIG_FATFS_FFCONF_OVERRIDE |
启用 FATFS 配置覆盖机制 |
CONFIG_FATFS_FFCONF_NAME |
指定自定义配置文件名 |
技术原理：
FATFS 提供了官方的配置覆盖机制。编译时，系统会：
- 读取 SDK 默认配置（
ffconf.h） - 检查是否启用覆盖机制
- 如果启用，加载自定义配置文件
- 自定义配置覆盖默认配置
- 继续编译，使用新配置
为什么使用 UTF-8 编码？
| 编码类型 | TCHAR 类型 | 优点 | 缺点 |
|---|---|---|---|
| ANSI (默认) | char | 简单 | 不支持中文 |
| UTF-16 | WCHAR | 完整 Unicode | 需要 wchar_t 支持 |
| UTF-8 | char | 兼容 C 字符串，完整 Unicode | - |
| UTF-32 | DWORD | 完整 Unicode | 占用空间大 |
UTF-8 是最佳选择，因为它：
- ✅ 完整支持 Unicode（包括中文）
- ✅ 兼容标准 C 字符串函数（strcmp, strcpy 等）
- ✅ 内存占用合理
注意： 如果不需要中文文件名支持，可以跳过此步骤。但建议启用，以便支持中文歌曲名称。
¶ 5. 编译并烧录
# 编译项目
./build -S ./apps/arcs-mini/ -C
# 烧录到设备
./res/arcs-mini/adb_download.sh
¶ 6. 测试SD卡功能
通过串口终端（波特率：921600）输入以下命令测试：
# 查看音乐列表
music list
预期输出：
如果看到类似以下输出，说明SD卡初始化成功，且中文文件名正常显示：
扫描路径: /SD:/music
曲目数量: 5
[0] /SD:/music/001_周杰伦_晴天.mp3
[1] /SD:/music/002_周杰伦_枫.mp3
[2] /SD:/music/003_方大同_春风吹.mp3
[3] /SD:/music/004_陈奕迅_葡萄成熟时.mp3
[4] /SD:/music/005_陈奕迅_十年.mp3
验证中文支持： 如果中文文件名显示正常，说明
fatfs_custom_config.h配置已生效。如果显示乱码（如?~1.MP3），请检查配置文件是否正确添加。
其他测试命令：
# 播放指定索引的音乐
music play 0
# 停止播放
music stop
¶ 第三部分：定义MCP工具实现语音控制
¶ 1. 添加MCP工具文件
在 apps/arcs-mini/mcp-tools/ 目录下创建：
- mcp_tool_offline_music.c：MCP工具实现文件
提示：完整的代码文件请参考：
主要功能：
- 向云端上报本地音乐列表
- 接收云端下发的播放指令（包含索引参数）
- 调用离线音乐服务进行播放
¶ 2. 修改 CMakeLists.txt
在 apps/arcs-mini/mcp-tools/CMakeLists.txt 中添加源文件：
listenai_library_named(app-mcp-tools)
listenai_library_sources(
mcp_tool_brightness.c
mcp_tool_volume.c
mcp_tool_device_info.c
mcp_tool_alarm.c
mcp_tool_led.c
mcp_tool_camera.c
mcp_tool_image.c
mcp_tool_duplex.c
mcp_tool_offline_music.c # 新增：离线音乐MCP工具
)
代码位置： apps/arcs-mini/mcp-tools/CMakeLists.txt:11
¶ 3. ⚠️ 重要注意事项
工具名称不要加 "ls." 前缀！
在 mcp_tool_offline_music.c 中，工具注册代码如下：
/* ❌ 错误示例（加了前缀，云端无法调用） */
MCP_TOOL_DEFINE(ls.play_offline_music, play_music_list, play_music_call);
MCP_TOOL_DEFINE(ls.stop_offline_music, stop_music_list, stop_music_call);
/* ✅ 正确示例（不加前缀） */
MCP_TOOL_DEFINE(play_offline_music, play_music_list, play_music_call);
MCP_TOOL_DEFINE(stop_offline_music, stop_music_list, stop_music_call);
原因： MCP框架会自动添加 "ls." 前缀，如果手动添加会导致工具名称变成 "ls.ls.play_offline_music"，云端无法正确调用。
¶ 4. 工具说明
¶ 4.1 play_offline_music 工具
功能： 播放指定索引的本地音乐
参数：
index（必需）：歌曲索引，从0开始
云端调用示例：
{
"tool": "play_offline_music",
"args": {
"index": 0
}
}
工具声明示例（上报给云端）：
播放SD卡离线音乐。共5首： [0]001_周杰伦_晴天.mp3 [1]002_周杰伦_枫.mp3 [2]003_方大同_春风吹.mp3 [3]004_陈奕迅_葡萄成熟时.mp3 [4]005_陈奕迅_十年.mp3。index参数为歌曲索引，从0开始。
¶ 4.2 stop_offline_music 工具
功能： 停止播放本地音乐
参数： 无
云端调用示例：
{
"tool": "stop_offline_music",
"args": {}
}
¶ 5. 编译并测试语音控制
# 重新编译项目
./build -S ./apps/arcs-mini/ -C
# 烧录到设备
./res/arcs-mini/adb_download.sh
¶ 6. 测试语音控制
确保设备已连接云端，然后对设备说：
- "播放本地音乐" - 自动播放第一首音乐
- "播放第一首音乐" - 播放索引为0的音乐
- "播放第二首音乐" - 播放索引为1的音乐
- "停止播放" - 停止音乐播放
预期效果：
¶ 常见问题
¶ 1. SD卡无法识别
可能原因：
- SD卡未格式化为FAT32格式
- SD卡损坏或不兼容
- 硬件连接不良
解决方法：
- 使用电脑重新格式化SD卡为FAT32
- 尝试更换SD卡
- 检查硬件连接
¶ 2. 音乐列表为空
可能原因：
- music文件夹不存在
- 文件夹中没有MP3文件
- 文件名格式不正确
解决方法：
- 确认
music文件夹已创建 - 确认MP3文件已放入
music文件夹 - 检查文件扩展名是否为
.mp3（不区分大小写）
¶ 3. 中文文件名显示乱码
问题现象：
[0] /SD:/music/001_周杰伦_晴天.mp3 ← 正常
[1] /SD:/music/002_?~1.MP3 ← 乱码
可能原因：
- 未创建
fatfs_custom_config.h文件 prj.conf中未添加 FATFS 配置覆盖选项- SD卡文件系统编码问题
解决方法：
-
检查配置文件是否存在
确认
apps/arcs-mini/fatfs_custom_config.h文件已创建。 -
检查 prj.conf 配置
确认
apps/arcs-mini/prj.conf中包含以下配置：CONFIG_FATFS_FFCONF_OVERRIDE=y CONFIG_FATFS_FFCONF_NAME="fatfs_custom_config.h" -
重新编译并烧录
# 清理编译缓存 ./build -S ./apps/arcs-mini/ -C --pristine # 重新烧录 ./res/arcs-mini/adb_download.sh -
检查 SD 卡格式
确认 SD 卡已格式化为 FAT32 格式。
技术说明： FATFS 默认使用 ANSI 编码，无法正确处理中文字符。通过启用 UTF-8 编码和简体中文代码页，可以完整支持中文文件名。
¶ 3. 云端无法调用工具
可能原因：
- 工具名称添加了 "ls." 前缀
- 设备未连接云端
解决方法：
- 检查
MCP_TOOL_DEFINE宏，确保工具名称没有 "ls." 前缀 - 确认设备已成功连接云端
¶ 代码结构总结
apps/arcs-mini/
├── main.c # 主程序入口（添加初始化调用）
├── prj.conf # 项目配置文件（包含中文支持配置）
├── fatfs_custom_config.h # FATFS 中文文件名支持配置
├── services/
│ ├── CMakeLists.txt # 服务编译配置（添加源文件）
│ ├── service_offline_music.h # 离线音乐服务头文件
│ └── service_offline_music.c # 离线音乐服务实现
└── mcp-tools/
├── CMakeLists.txt # MCP工具编译配置（添加源文件）
└── mcp_tool_offline_music.c # 离线音乐MCP工具实现
¶ 关键文件说明
| 文件 | 作用 | 关键配置/函数 |
|---|---|---|
main.c:209 |
初始化服务 | service_offline_music_init() |
prj.conf:491-492 |
启用中文支持 | CONFIG_FATFS_FFCONF_* |
fatfs_custom_config.h |
中文文件名配置 | FF_LFN_UNICODE=2 |
service_offline_music.c |
SD卡初始化和播放 | 扫描、播放控制 |
mcp_tool_offline_music.c |
语音控制接口 | MCP工具定义 |
¶ 进阶功能
如果需要更复杂的功能，可以扩展以下内容：
-
支持暂停/恢复播放
- 在
service_offline_music.c中添加service_offline_music_pause()和service_offline_music_resume()函数 - 在
mcp_tool_offline_music.c中添加对应的MCP工具
- 在
-
支持上一曲/下一曲
- 添加
service_offline_music_next()和service_offline_music_prev()函数 - 添加对应的MCP工具
- 添加
-
支持播放模式切换
- 添加顺序播放、单曲循环、列表循环、随机播放等模式
- 添加
service_offline_music_set_mode()函数
¶ 总结
通过本教程，您已经学会了：
✅ 如何初始化SD卡硬件
✅ 如何实现离线音乐播放服务
✅ 如何配置FATFS支持中文文件名
✅ 如何定义MCP工具实现语音控制
✅ 常见问题的排查方法
现在您可以通过语音指令控制设备播放SD卡中的音乐了！🎉
¶ 完整复现清单
按照以下步骤，您可以从零开始完整复现本教程的所有功能：
¶ 必需文件（git已添加）
| 文件路径 | 状态 | 说明 |
|---|---|---|
services/service_offline_music.h |
✅ 已添加 | 离线音乐服务头文件 |
services/service_offline_music.c |
✅ 已添加 | 离线音乐服务实现 |
mcp-tools/mcp_tool_offline_music.c |
✅ 已添加 | MCP工具实现 |
fatfs_custom_config.h |
✅ 已添加 | 中文文件名支持配置 |
¶ 必需修改（git已修改）
| 文件路径 | 修改内容 | 行号 |
|---|---|---|
main.c |
添加 service_offline_music_init() |
209 |
services/CMakeLists.txt |
添加 service_offline_music.c |
10 |
mcp-tools/CMakeLists.txt |
添加 mcp_tool_offline_music.c |
11 |
prj.conf |
添加 FATFS 中文支持配置 | 491-492 |
¶ 验证步骤
-
编译检查
./build -S ./apps/arcs-mini/ -C -
烧录测试
./res/arcs-mini/adb_download.sh -
串口验证
music list预期输出：显示中文文件名的MP3列表
-
语音测试
- 对设备说："播放本地音乐"
- 预期效果：自动播放第一首音乐