app_player 音频焦点管理示例

功能说明

演示如何使用 app_player 的音频焦点管理功能，实现多个播放器之间的智能焦点调度，支持焦点抢占、暂停恢复和自定义回调处理。

硬件连接

PA27: PA（功放）控制引脚，用于控制音频功放的开关
WiFi: 需要设备支持 WiFi 并连接到互联网（用于播放网络音频）

示例步骤

配置焦点通道（tone/tts/music 三个优先级）并初始化 app_player
创建三个播放器实例并注册焦点变化回调
播放音乐（music 获得前景焦点）
播放提示音（tone 抢占 music，music 被暂停）
提示音播放完成后等待 TTS 播放
TTS 播放完成后 music 自动恢复

编译

重要提示：在编译前，请先确认您使用的开发板型号。SDK 目前支持以下开发板：

arcs_evb - ARCS EVB 评估板
arcs_mini - ARCS Mini 开发板

根据您的开发板型号，选择对应的编译命令：

在示例目录下执行编译:

# 使用 arcs_evb 开发板
./build.sh -C -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
./build.sh -C -DBOARD=arcs_mini

Note

如果在 SDK 根目录执行，需要指定示例路径:

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

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

Note

确保已安装对应的工具链。

烧录

编译完成后，使用 SDK tools 目录下的 cskburn 工具烧录固件:

./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs

Note

烧录参数说明：

-s /dev/ttyUSB0：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是 /dev/ttyUSB0 或 /dev/ttyACM0 - 可通过 ls /dev/tty* 命令查看可用串口设备 - 不同开发板或 USB 转串口芯片可能使用不同的设备名
-b 3000000：烧录波特率（3Mbps）
0x0：烧录起始地址
build/arcs.bin：编译生成的固件路径
-C arcs：芯片类型

注意事项：

确保开发板已正确连接到电脑
如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口

预期输出

=== Audio Focus Management Sample ===
Creating players...
All players created and registered

=== Scenario 1: Playing music ===
Music is playing...
[MUSIC] Player prepared
[MUSIC] Player playing

=== Scenario 2: Playing tone (music will pause) ===
[MUSIC] Moved to BACKGROUND (by player 0x...)
[MUSIC] Player paused
[TONE] Player prepared
[TONE] Player playing
[TONE] Player completed

=== Scenario 3: Tone completed, waiting 3s before TTS ===
Music should NOT resume yet (by_which=tone_player, blocked in callback)

=== Scenario 4: Playing TTS (music stays paused) ===
TTS is playing...
[TTS] Player prepared
[TTS] Player playing
[TTS] Player completed

=== Scenario 5: TTS completed, music should auto-resume ===
[MUSIC] Got FOREGROUND focus (by player 0x...)
[MUSIC] Player playing

=== Stopping all players ===
[MUSIC] Player stopped

=== Demo completed ===

核心 API

API	说明
`app_player_init()`	初始化 app_player 模块（含焦点配置）
`app_player_create()`	创建播放器实例（名称需匹配焦点配置）
`app_player_register_focus_cb()`	注册焦点变化回调函数
`app_player_register_callback()`	注册播放事件回调函数
`app_player_play()`	播放音频（自动申请焦点）
`app_player_pause()`	暂停播放
`app_player_resume()`	恢复播放
`app_player_stop()`	停止播放
`app_player_destroy()`	销毁播放器实例

关键代码

/* 定义焦点配置 */
app_player_focus_channel_config_t focus_configs[] = {
    {
        .name = "tone",
        .priority = 0,  // 最高优先级
        .capture_names = (const char *[]){"tts"},
        .capture_count = 1,
        .behavior = {
            .on_background = APP_PLAYER_FOCUS_LOSS_STOP,
            .on_focus_lost = APP_PLAYER_FOCUS_LOSS_STOP,
        }
    },
    {
        .name = "tts",
        .priority = 1,
        .capture_names = (const char *[]){"tone"},
        .capture_count = 1,
        .behavior = {
            .on_background = APP_PLAYER_FOCUS_LOSS_STOP,
            .on_focus_lost = APP_PLAYER_FOCUS_LOSS_STOP,
        }
    },
    {
        .name = "music",
        .priority = 2,  // 最低优先级
        .capture_names = NULL,
        .capture_count = 0,
        .behavior = {
            .on_background = APP_PLAYER_FOCUS_LOSS_PAUSE,
            .on_focus_lost = APP_PLAYER_FOCUS_LOSS_STOP,
        }
    }
};

/* 初始化 app_player（带焦点管理） */
app_player_config_t app_config = {
    .pa_ctrl_callback = pa_control_callback,
    .focus_configs = focus_configs,
    .focus_config_count = 3
};
app_player_init(&app_config);

/* 创建播放器并注册焦点回调 */
tone_player = app_player_create("tone");
app_player_register_focus_cb(tone_player, focus_change_callback, "TONE");

注意事项

焦点配置时机: 焦点配置必须在 app_player_init() 时提供，创建播放器后无法动态修改
名称匹配: 播放器名称必须与焦点配置的 name 匹配，否则该播放器不会参与焦点管理
回调返回值: 返回 false 让系统自动执行策略，返回 true 阻止自动执行
音频文件准备: 运行前需将 tone 音频文件烧录到 Flash 指定地址，并确保网络连接正常
回调执行速度: 焦点回调函数应快速返回，避免阻塞焦点管理器