ESP-Player-Service 组件

ESP Player Service 简介

ESP Player Service 是乐鑫在 ESP-ADF 中提供的 播放侧（SINK） 服务，底层基于 ESP Player 完成解封装、解码与渲染；产品侧则用一个播放实例统一管理一块开发板上的扬声器和屏幕。

相比直接使用 ESP Player，本服务额外提供 多路同时播、混音与抢占、播放列表，以及和采集 / 协议服务直连，适合音箱、故事机、语音助手、带屏影音这类要在同一设备上叠背景音乐、提示音、TTS 或视频的产品。

三个组件怎么选

可基于板子能力选择子类：无屏产品用音频子类；带屏产品用视频子类。若已有音频实例、后续才加屏，在原实例上挂显示即可，无需再开一路播放服务。同一块板上不要同时创建音频实例和视频实例，否则同一喇叭会变成两套混音。

组件	定位	典型客户
esp_audio_player_service	自动对接板级 DAC	无屏音箱、故事机、语音助手
esp_video_player_service	自动对接板级 LCD 和 DAC，同一实例出声出画	带屏影音、可视门铃、智能显示
esp_player_service	播放核心；PCM 出口不是板级 DAC 时才直接用	自定义写 PCM、自管 codec 的方案

无屏产品用音频子类；带屏产品用视频子类。若已有音频实例、后续才加屏，在原实例上挂显示即可，不要再开一路播放服务。

主要能力

能力	说明
多路播放	一个实例对应一块板的输出；背景音乐、TTS、提示音、视频等作为不同路叠加
混音与抢占	可按路设置音量；三档优先级（背景 / 通知 / 紧急），可共存压低或独占打断
多种输入	本地 / HTTP(S) / HLS 的 URL；应用喂帧（如 TTS）；与采集、RTSP / RTMP / SIP 等源服务直连，不必应用自己搬帧
播放控制	播放、暂停、继续、停止、Seek、倍速；可查时长、进度和状态
播放列表	上一首 / 下一首 / 跳转、循环模式、播完自动切歌
音视频一体	同一路里最多一路音频 + 一路视频，可做音视频同步；一块屏共用一个显示
ID3	裸 MP3 可解析歌名等信息

典型应用场景

场景	说明
音箱 / 故事机	背景音乐与提示音、TTS 同时出声，通知到来时压低或打断音乐
语音助手	播报回答时与正在播放的内容共存或抢占
带屏终端	本地或网络视频播放，同时叠提示音或 TTS
与协议 / 采集级联	摄像头预览、对讲、拉流等源服务的媒体直接送到本机播放，无需应用转发

和 ESP Player 如何分工

ESP Player 是底层播放器：一条源、解封装到出声出画。ESP Player Service 是产品层封装：多路、混音、列表、和其它媒体服务对接，并按开发板自动接 DAC / LCD。

客户只要单路播放、自己管输出，推荐 ESP Player；要多路叠加或和采集 / 协议服务串起来，推荐本服务。

如何使用

无屏产品添加 espressif/esp_audio_player_service，带屏产品添加 espressif/esp_video_player_service。可以通过在工程中输入以下命令 idf.py add-dependency "espressif/esp_audio_player_service"，将对应组件加入工程。板级外设由 ESP Board Manager 管理。详细用法见各组件 README。

FAQ

能不能同时创建音频服务和视频服务？

同一喇叭不要各建一个实例。带屏直接用视频播放服务；先做音频、后来加屏，在已有实例上挂显示。

和 ESP Player、Audio Simple Player 怎么选？

只播一路音频、能力要求简单：Audio Simple Player。单路音视频、自己接渲染：ESP Player。产品上要多路混音、列表或和采集 / SIP / RTSP 直连：ESP Player Service。