app_player 本地文件播放示例

📁 源码位置: samples/media/app_player/local_fs 查看源码

功能说明

演示如何使用 app_player 模块从本地文件系统（FAT32 SD 卡）播放音频文件，包括文件系统挂载、播放控制和事件回调处理。

硬件连接

PA（功放）使能引脚由板级 pinmux.h 的 PA_EN_PIN 提供，各板型不同：

板型	PA_EN_PIN	备注
arcs_evb	PA27	—
venusa_rd_evb	PA00	需将 J53 跳线拨到 PA_EN 位置

venusa_rd_evb 注意：J53 是 2×3 三选一跳线，PA00 可选 PA_EN / 摄像头 PWDN / LCD_RST。跳线不在 PA_EN 位置时功放无法使能， 代码正确也不会有声音。详见 boards/venusa_rd_evb/README.md。

• SDMMC0 接口: 连接 SD 卡/eMMC，用于存储音频文件

使用 tools/fatfs_package 工具将音频文件打包为 FAT32 镜像：

# 进入工具目录
cd tools/fatfs_package

# 生成镜像文件（示例：32MB 大小）
./tools/fatfs_package/mkfatfs.py -o fatfs.img -s 32M -d samples/media/app_player/local_fs/res/audio_file -l SD

示例步骤

1. 初始化 SD 卡并挂载 FAT32 文件系统到 /SD: 挂载点

2. 初始化 app_player 模块并配置 PA 控制回调

3. 创建播放器实例并注册事件回调

4. 播放本地 MP3 音频文件 /SD:/001_network_suc.mp3

5. 演示播放控制：播放、暂停、恢复、停止

6. 销毁播放器实例

编译

重要提示：编译前需要先确认当前示例支持的目标板型，然后将板型标识传给 -DBOARD。请按以下方式选择：

1. 确认示例限制：查看当前示例 README 中的硬件连接和注意事项，确认是否限定板型。

2. 参考示例配置：查看相关示例目录下的 sample.yaml，确认支持的板型。

3. 填写板型标识：SDK 内置板型的标识为 boards/ 下的目录名。例如实际使用的板型目录为 boards/<板型名称>/，则编译参数填写为 -DBOARD=<板型名称>。

在 SDK 根目录执行编译，并将命令中的 <示例路径> 和 <板型名称> 替换为实际值。

Linux 使用 build.sh：

# 通用命令
./build.sh -C -S samples/<示例路径> -DBOARD=<板型名称>

# 示例：使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb

Windows PowerShell 使用 build.ps1：

# 通用命令
.\build.ps1 -C -S samples/<示例路径> -DBOARD=<板型名称>

# 示例：使用 arcs_evb 开发板
.\build.ps1 -C -S samples/<示例路径> -DBOARD=arcs_evb

Note

确保已安装对应平台的工具链和 ListenAI 开发工具包。Windows 环境请先执行 .\env.ps1 或直接使用 .\build.ps1 自动加载环境。

注意事项：-DBOARD 填写的是板型标识，不是芯片系列名称。如果示例有板型专用配置或额外编译参数，以示例 README 中的说明为准。

烧录

编译完成后，使用 SDK tools/burn 目录下的 cskburn 工具烧录固件。请先根据目标板型和当前示例确定芯片系列、串口设备、烧录地址和固件路径。

Linux：

# 通用命令
./tools/burn/cskburn -C <芯片系列> -s <串口设备> -b 3000000 <烧录地址> <固件路径>

# 示例：使用 arcs_evb 开发板
./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs

Windows PowerShell：

# 通用命令
.\tools\burn\cskburn.exe -C <芯片系列> -s <串口号> -b 3000000 <烧录地址> <固件路径>

# 示例：使用 arcs_evb 开发板
.\tools\burn\cskburn.exe -C arcs -s COM7 -b 3000000 0x0 .\build\arcs.bin

Note

烧录参数说明：

• -s /dev/ttyUSB0 / -s COM7：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是 /dev/ttyUSB0 或 /dev/ttyACM0 - 可通过 ls /dev/tty* 命令查看可用串口设备 - Windows 系统：通常是 COM7、COM8 等，可在“设备管理器”的“端口”中查看 - 不同开发板或 USB 转串口芯片可能使用不同的设备名

• -b 3000000：烧录波特率（3Mbps）

• 0x0：烧录起始地址

• build/arcs.bin / .\build\arcs.bin：编译生成的固件路径

• -C arcs：芯片类型

注意事项：

• 确保开发板已正确连接到电脑

• 如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口

预期输出

[app_player_sample] App Player Local Filesystem Sample
[app_player_sample] Starting playback demo...
[app_player_sample] Player prepared
[app_player_sample] Player playing
[app_player_sample] PA ON
[app_player_sample] Player stopped
[app_player_sample] PA OFF
[app_player_sample] Playback demo completed

核心 API

API	说明
app_player_init()	初始化 app_player 模块
app_player_create()	创建播放器实例
app_player_register_callback()	注册播放事件回调函数
app_player_play()	播放指定路径的音频文件
app_player_pause()	暂停播放
app_player_resume()	恢复播放
app_player_stop()	停止播放（同步接口）
app_player_destroy()	销毁播放器实例

关键代码

/* 初始化播放器 */
app_player_config_t config = {
    .pa_ctrl_callback = pa_control_callback
};
app_player_init(&config);

/* 创建播放器实例 */
app_player_t *player = app_player_create("tone");
app_player_register_callback(player, player_event_callback, NULL);

/* 播放本地文件 */
app_player_play(player, "/SD:/001_network_suc.mp3");

/* 播放控制 */
app_player_pause(player);
app_player_resume(player);
app_player_stop(player);

注意事项

1. 文件系统镜像: 运行前需使用 mkfatfs.py 工具将音频文件打包为 FAT32 镜像并烧录到 eMMC

2. 烧录顺序: 先烧录文件系统镜像到 eMMC（使用 --emmc 参数），再烧录应用固件到 Flash

3. 文件路径格式: 播放路径必须包含挂载点前缀，如 /SD:/filename.mp3

4. PA 回调必填: app_player_init() 时必须提供 pa_ctrl_callback，用于控制功放开关

5. 音频格式: 支持 MP3、WAV 等格式，推荐 16kHz、16bit 的音频文件