前言

音乐文件存在在本地TF卡调用无云端延迟，点播响应迅速，整体运行更稳定可靠，播放中平稳不卡顿不受网络影响。

本文以LS26视觉语音开发板搭配 TF卡配置调用音乐文件为例，讲解如何实现语音点播本地音乐。

效果演示

通过语音指令"播放本地音乐"，设备会自动播放SD卡中的MP3文件。

演示视频：https://docs2.listenai.com/zz/11645.mp4?shortId=tM66w5gUl

通过本教程，您可以学会：

✅ 如何初始化SD卡硬件

✅ 如何实现离线音乐播放服务

✅ 如何配置FATFS支持中文文件名

✅ 如何定义MCP工具实现语音控制

✅ 常见问题的排查方法现在您可以通过语音指令控制设备播放SD卡中的音乐了！

开始之前请先检查

SDK版本

实操之前，请确保已根据文档《Arcs-Mini 开发环境搭建指南》（ https://docs2.listenai.com/x/wgjKAyNwz）搭建开发环境。

本篇示例在 2.4.1 版本的 SDK 进行修改

可通过命令 git log 查看版本，如果版本不一致，请使用命令 git checkout mini-v2.4.1 切到指定SDK版本

关闭云端OTA更新

参考文档2.1烧录工具安装教程 | 聆思文档中心安装ADB工具

执行命令 adb shell kv set int user.disable_app_update 1 关闭云端OTA更新，防止云端更新把刚烧录的固件刷掉了。

固件下载

如果您不想重新编译代码而希望直接体验本固件，可点击下载。

固件下载链接：mcp_tool_play_offline_music_sd.hex
参考文档 2.2固件烧录教程(ADB工具) | 聆思文档中心将.hex 文件拖入 cskburn desktop 后选择 ADB 设备进行烧录即可。

示例代码

如果您想直接查看所有代码，可点击下载。

源码下载：apps.zip

1.下载后，将其替换 arcs_mini 项目的 apps 文件夹

2.参考文档1.SDK编译教程 | 聆思文档中心编译烧录即可

开发实现步骤

一、准备音乐资源

将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=yCONFIG_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工具实现文件

提示：完整的代码文件请参考：

mcp_tool_offline_music.c

主要功能：

向云端上报本地音乐列表
接收云端下发的播放指令（包含索引参数）
调用离线音乐服务进行播放

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的音乐
"停止播放" - 停止音乐播放

预期效果：

代码结构

关键文件说明

|--------------------------|-----------|------------------------------|
| 文件 | 作用 | 关键配置/函数 |
| 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() 函数

详解小聆AI语音视觉开发板实现语音点播本地TF卡中音乐的开发实现方法

前言

效果演示

开始之前请先检查

SDK版本

关闭云端OTA更新

固件下载

示例代码

开发实现步骤

一、准备音乐资源

二、SD卡硬件连接与初始化

1. 硬件连接

2. 初始化SD卡

2.1 创建离线音乐服务文件（能够使用SD卡）

2.2 修改 CMakeLists.txt（SD卡的代码能够参与编译）

2.3 在 main.c 中初始化服务（调用SD卡的逻辑）

3. 启用文件系统（能够通过文件名访问资源文件）

3.1 基础配置

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 中文文件名支持（重要）

步骤 1：创建自定义配置文件

步骤 2：在 prj.conf 中启用配置

FATFS 中文文件名支持CONFIG_FATFS_FFCONF_OVERRIDE=yCONFIG_FATFS_FFCONF_NAME="fatfs_custom_config.h"配置位置： apps/arcs-mini/prj.conf:491-492

5. 编译并烧录

6. 测试SD卡功能

三：定义MCP工具实现语音控制

1. 添加MCP工具文件

2. 修改 CMakeLists.txt

3. ⚠️ 重要注意事项

4. 工具说明

4.1 play_offline_music 工具

播放SD卡离线音乐。共5首： $0$ 001_周杰伦_晴天.mp3 $1$ 002_周杰伦_枫.mp3 $2$ 003_方大同_春风吹.mp3 $3$ 004_陈奕迅_葡萄成熟时.mp3 $4$ 005_陈奕迅_十年.mp3。index参数为歌曲索引，从0开始。 4.2 stop_offline_music 工具

5. 编译并测试语音控制

6. 测试语音控制

代码结构

关键文件说明

进阶功能

更多资料参考

详解小聆AI语音视觉开发板实现语音点播本地TF卡中音乐的开发实现方法

前言

效果演示

开始之前请先检查

SDK版本

关闭云端OTA更新

固件下载

示例代码

开发实现步骤

一、准备音乐资源

二**、SD卡硬件连接与初始化**

1. 硬件连接

2. 初始化SD卡

2.1 创建离线音乐服务文件（能够使用SD卡）

2.2 修改 CMakeLists.txt（SD卡的代码能够参与编译）

2.3 在 main.c 中初始化服务（调用SD卡的逻辑）

3. 启用文件系统（能够通过文件名访问资源文件）

3.1 基础配置

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 中文文件名支持（重要）

步骤 1：创建自定义配置文件

步骤 2：在 prj.conf 中启用配置

FATFS 中文文件名支持CONFIG_FATFS_FFCONF_OVERRIDE=yCONFIG_FATFS_FFCONF_NAME="fatfs_custom_config.h"配置位置： apps/arcs-mini/prj.conf:491-492

5. 编译并烧录

6. 测试SD卡功能

三**：定义MCP工具实现语音控制**

1. 添加MCP工具文件

2. 修改 CMakeLists.txt

3. ⚠️ 重要注意事项

4. 工具说明

4.1 play_offline_music 工具

播放SD卡离线音乐。共5首： 0001_周杰伦_晴天.mp3 1002_周杰伦_枫.mp3 2003_方大同_春风吹.mp3 3004_陈奕迅_葡萄成熟时.mp3 4005_陈奕迅_十年.mp3。index参数为歌曲索引，从0开始。 4.2 stop_offline_music 工具

5. 编译并测试语音控制

6. 测试语音控制

代码结构

关键文件说明

进阶功能

更多资料参考

二、SD卡硬件连接与初始化

三：定义MCP工具实现语音控制

播放SD卡离线音乐。共5首： $0$ 001_周杰伦_晴天.mp3 $1$ 002_周杰伦_枫.mp3 $2$ 003_方大同_春风吹.mp3 $3$ 004_陈奕迅_葡萄成熟时.mp3 $4$ 005_陈奕迅_十年.mp3。index参数为歌曲索引，从0开始。 4.2 stop_offline_music 工具