前言

音乐文件存在在本地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更新，防止云端更新把刚烧录的固件刷掉了。

固件下载

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

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

示例代码

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

源码下载：apps.zip

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

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

开发实现步骤

一、准备音乐资源

1. 将SD卡格式化为FAT32格式
2. 在SD卡根目录创建 music 文件夹
3. 将MP3文件放入 music 文件夹
4. 支持中英文文件名，建议命名格式：序号_歌手_歌名.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卡初始化、音乐扫描、播放控制等功能

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

• service_offline_music.h
• service_offline_music.c

主要功能：

• 自动探测和初始化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=yCONFIG_FATFS_FILESYSTEM=yCONFIG_LSFS_REGISTER_VFS=yCONFIG_LVFS=yCONFIG_LVFS_POSIX_API=yCONFIG_LVFS_POSIX_API_ALIAS=y3.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 提供了官方的配置覆盖机制。编译时，系统会：

1. 读取 SDK 默认配置（ffconf.h）
2. 检查是否启用覆盖机制
3. 如果启用，加载自定义配置文件
4. 自定义配置覆盖默认配置
5. 继续编译，使用新配置

为什么使用 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工具定义

进阶功能

如果需要更复杂的功能，可以扩展以下内容：

1. 支持暂停/恢复播放
   • 在 service_offline_music.c 中添加 service_offline_music_pause() 和 service_offline_music_resume() 函数
   • 在 mcp_tool_offline_music.c 中添加对应的MCP工具
2. 支持上一曲/下一曲
   • 添加 service_offline_music_next() 和 service_offline_music_prev() 函数
   • 添加对应的MCP工具
3. 支持播放模式切换
   • 添加顺序播放、单曲循环、列表循环、随机播放等模式
   • 添加 service_offline_music_set_mode() 函数

更多资料参考

以上为LS26开发套件（Arcs mini）接入龙虾的操作，如需克隆IP角色、自建RAG知识库、控制外设家居、接入MCP等更多云端服务、可以参考这个文档内容实现：https://docs2.listenai.com/x/Scs0mxNw6