音频
辅助头文件:
#include "brookesia/service_helper/media/audio.hpp"辅助类:
esp_brookesia::service::helper::AudioPlayback、AudioEncoder<0>、AudioDecoder<0>
概述
brookesia_service_audio 是为 ESP-Brookesia 生态系统提供的音频服务,提供:
音频播放:支持从 URL 播放音频文件,支持暂停、恢复、停止等播放控制。
音频编解码:支持多种音频编解码格式(PCM、OPUS、G711A),支持编码和解码功能。
播放状态管理:实时跟踪播放状态(空闲、播放中、暂停),并通过事件通知状态变化。
编码器管理:支持编码器的启动、停止和配置,可设置编码器读取数据大小。
解码器管理:支持解码器的启动、停止和数据输入,支持流式解码。
功能特性
音频编解码格式
Audio Service 支持以下音频编解码格式:
格式 |
编码 |
解码 |
说明 |
|---|---|---|---|
PCM |
✅ |
✅ |
无损音频格式 |
OPUS |
✅ |
✅ |
支持 VBR 和固定比特率配置 |
G711A |
✅ |
✅ |
电话音质音频格式 |
播放控制
支持从 URL 播放音频文件。
支持暂停、恢复、停止等基础播放控制。
提供播放状态事件通知,便于业务层同步 UI 与状态。
编码器配置
编解码格式:PCM、OPUS、G711A。
通道数:1-4 通道。
采样位数:8、16、24、32 位。
采样率:8000、16000、24000、32000、44100、48000 Hz。
帧时长:可配置的帧时长(毫秒)。
OPUS 扩展配置:VBR 开关、比特率设置。
解码器配置
编解码格式:PCM、OPUS、G711A。
通道数:1-4 通道。
采样位数:8、16、24、32 位。
采样率:8000、16000、24000、32000、44100、48000 Hz。
帧时长:可配置的帧时长(毫秒)。
事件通知
播放状态变化:播放状态改变时触发(Idle、Playing、Paused)。
编码器事件:编码器事件发生时触发。
编码数据就绪:编码数据准备好时触发。
服务接口
函数
播放
Play
描述
Play audio from a URL. Supports loop and interrupt playback.
执行要求
是否需要调度器: 需要
参数
Url类型:
String是否必填: 必填
描述: Audio URL, for example: "file://littlefs/example.mp3".
Config类型:
Object是否必填: 可选
默认值:
{"interrupt":true,"delay_ms":0,"loop_count":0,"loop_interval_ms":0,"timeout_ms":0}描述: Playback config. Example: {"interrupt":true,"delay_ms":0,"loop_count":0,"loop_interval_ms":0,"timeout_ms":0}
Schema JSON
展开查看 JSON
{
"name": "Play",
"description": "Play audio from a URL. Supports loop and interrupt playback.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "Url",
"description": "Audio URL, for example: \"file://littlefs/example.mp3\".",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "Config",
"description": "Playback config. Example: {\"interrupt\":true,\"delay_ms\":0,\"loop_count\":0,\"loop_interval_ms\":0,\"timeout_ms\":0}",
"type": "Object",
"required": false,
"default_value": {
"interrupt": true,
"delay_ms": 0,
"loop_count": 0,
"loop_interval_ms": 0,
"timeout_ms": 0
}
}
],
"return_value": null
}
CLI 命令
svc_call AudioPlayback Play {"Url":null,"Config":null}
PlayUrls
描述
Play audio from multiple URLs. Supports loop and interrupt playback.
执行要求
是否需要调度器: 需要
参数
Urls类型:
Array是否必填: 必填
描述: Audio URL list. Example: ["file://littlefs/example1.mp3","file://littlefs/example2.mp3"]
Config类型:
Object是否必填: 可选
默认值:
{"interrupt":true,"delay_ms":0,"loop_count":0,"loop_interval_ms":0,"timeout_ms":0}描述: Playback config. Example: {"interrupt":true,"delay_ms":0,"loop_count":0,"loop_interval_ms":0,"timeout_ms":0}
Schema JSON
展开查看 JSON
{
"name": "PlayUrls",
"description": "Play audio from multiple URLs. Supports loop and interrupt playback.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "Urls",
"description": "Audio URL list. Example: [\"file://littlefs/example1.mp3\",\"file://littlefs/example2.mp3\"]",
"type": "Array",
"required": true,
"default_value": null
},
{
"name": "Config",
"description": "Playback config. Example: {\"interrupt\":true,\"delay_ms\":0,\"loop_count\":0,\"loop_interval_ms\":0,\"timeout_ms\":0}",
"type": "Object",
"required": false,
"default_value": {
"interrupt": true,
"delay_ms": 0,
"loop_count": 0,
"loop_interval_ms": 0,
"timeout_ms": 0
}
}
],
"return_value": null
}
CLI 命令
svc_call AudioPlayback PlayUrls {"Urls":null,"Config":null}
Pause
描述
Pause playback.
执行要求
是否需要调度器: 需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "Pause",
"description": "Pause playback.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioPlayback Pause
Resume
描述
Resume playback.
执行要求
是否需要调度器: 需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "Resume",
"description": "Resume playback.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioPlayback Resume
Stop
描述
Stop playback.
执行要求
是否需要调度器: 需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "Stop",
"description": "Stop playback.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioPlayback Stop
SetVolume
描述
Set target playback volume percentage.
执行要求
是否需要调度器: 需要
参数
Volume类型:
Number是否必填: 必填
描述: Playback volume percentage in range [0, 100].
Schema JSON
展开查看 JSON
{
"name": "SetVolume",
"description": "Set target playback volume percentage.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "Volume",
"description": "Playback volume percentage in range [0, 100].",
"type": "Number",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call AudioPlayback SetVolume {"Volume":null}
GetVolume
描述
Get target playback volume percentage [0, 100].
执行要求
是否需要调度器: 需要
参数
无。
返回值
类型:
Number描述: Playback volume percentage in range [0, 100].
Schema JSON
展开查看 JSON
{
"name": "GetVolume",
"description": "Get target playback volume percentage [0, 100].",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Number",
"description": "Playback volume percentage in range [0, 100]."
}
}
CLI 命令
svc_call AudioPlayback GetVolume
SetMute
描述
Set whether audio playback is muted.
执行要求
是否需要调度器: 需要
参数
Enable类型:
Boolean是否必填: 必填
描述: True to mute playback, false to unmute it.
Schema JSON
展开查看 JSON
{
"name": "SetMute",
"description": "Set whether audio playback is muted.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "Enable",
"description": "True to mute playback, false to unmute it.",
"type": "Boolean",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call AudioPlayback SetMute {"Enable":null}
GetMute
描述
Get whether audio playback is muted.
执行要求
是否需要调度器: 需要
参数
无。
返回值
类型:
Boolean描述: True when muted, false when unmuted.
Schema JSON
展开查看 JSON
{
"name": "GetMute",
"description": "Get whether audio playback is muted.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Boolean",
"description": "True when muted, false when unmuted."
}
}
CLI 命令
svc_call AudioPlayback GetMute
LoadData
描述
Load persisted audio playback state, including volume and mute.
执行要求
是否需要调度器: 需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "LoadData",
"description": "Load persisted audio playback state, including volume and mute.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioPlayback LoadData
ResetData
描述
Reset persisted audio playback state, including volume and mute.
执行要求
是否需要调度器: 需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "ResetData",
"description": "Reset persisted audio playback state, including volume and mute.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioPlayback ResetData
编码器
Start
描述
Start audio encoder.
执行要求
是否需要调度器: 需要
参数
Config类型:
Object是否必填: 必填
描述: Audio encoder config. Example: {"type":"PCM","general":{"channels":0,"sample_bits":0,"sample_rate":0,"frame_duration":0},"extra":null,"fetch_interval_ms":10,"fetch_data_size":4096,"enable_afe":false,"afe_wake_start_timeout_ms":30000,"afe_wake_end_timeout_ms":10000}
Schema JSON
展开查看 JSON
{
"name": "Start",
"description": "Start audio encoder.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "Config",
"description": "Audio encoder config. Example: {\"type\":\"PCM\",\"general\":{\"channels\":0,\"sample_bits\":0,\"sample_rate\":0,\"frame_duration\":0},\"extra\":null,\"fetch_interval_ms\":10,\"fetch_data_size\":4096,\"enable_afe\":false,\"afe_wake_start_timeout_ms\":30000,\"afe_wake_end_timeout_ms\":10000}",
"type": "Object",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call AudioEncoder0 Start {"Config":null}
Stop
描述
Stop audio encoder.
执行要求
是否需要调度器: 需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "Stop",
"description": "Stop audio encoder.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioEncoder0 Stop
Pause
描述
Pause audio encoder.
执行要求
是否需要调度器: 需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "Pause",
"description": "Pause audio encoder.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioEncoder0 Pause
Resume
描述
Resume audio encoder.
执行要求
是否需要调度器: 需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "Resume",
"description": "Resume audio encoder.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioEncoder0 Resume
PauseWakeEnd
描述
Pause pending AFE WakeEnd event without pausing audio capture.
执行要求
是否需要调度器: 不需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "PauseWakeEnd",
"description": "Pause pending AFE WakeEnd event without pausing audio capture.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioEncoder0 PauseWakeEnd
ResumeWakeEnd
描述
Resume pending AFE WakeEnd event without resuming audio capture.
执行要求
是否需要调度器: 不需要
参数
无。
Schema JSON
展开查看 JSON
{
"name": "ResumeWakeEnd",
"description": "Resume pending AFE WakeEnd event without resuming audio capture.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": null
}
CLI 命令
svc_call AudioEncoder0 ResumeWakeEnd
GetAFEWakeWords
描述
Get AFE wake words.
执行要求
是否需要调度器: 不需要
参数
无。
返回值
类型:
Array描述: Example: ["ni hao xiao zhi","hello brookesia"]
Schema JSON
展开查看 JSON
{
"name": "GetAFEWakeWords",
"description": "Get AFE wake words.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Array",
"description": "Example: [\"ni hao xiao zhi\",\"hello brookesia\"]"
}
}
CLI 命令
svc_call AudioEncoder0 GetAFEWakeWords
解码器
GetOutputs
描述
Get audio output list.
执行要求
是否需要调度器: 不需要
参数
无。
返回值
类型:
Array描述: Example: [{"id":0,"name":"Speaker0","role":"speaker","sample_rates":[16000,22050,44100,48000],"channels":[1,2],"sample_bits":[16]}]
Schema JSON
展开查看 JSON
{
"name": "GetOutputs",
"description": "Get audio output list.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Array",
"description": "Example: [{\"id\":0,\"name\":\"Speaker0\",\"role\":\"speaker\",\"sample_rates\":[16000,22050,44100,48000],\"channels\":[1,2],\"sample_bits\":[16]}]"
}
}
CLI 命令
svc_call AudioDecoder0 GetOutputs
GetSources
描述
Get registered audio sources.
执行要求
是否需要调度器: 不需要
参数
无。
返回值
类型:
Array描述: Example: [{"id":1,"name":"TTS","role":"speech","preferred_outputs":["Speaker0"],"priority":10}]
Schema JSON
展开查看 JSON
{
"name": "GetSources",
"description": "Get registered audio sources.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Array",
"description": "Example: [{\"id\":1,\"name\":\"TTS\",\"role\":\"speech\",\"preferred_outputs\":[\"Speaker0\"],\"priority\":10}]"
}
}
CLI 命令
svc_call AudioDecoder0 GetSources
RegisterSource
描述
Register an audio source.
执行要求
是否需要调度器: 不需要
参数
Source类型:
Object是否必填: 必填
描述: Source info. Example: {"id":0,"name":"TTS","role":"speech","preferred_outputs":["Speaker0"],"priority":0}
返回值
类型:
Number描述: Registered source id.
Schema JSON
展开查看 JSON
{
"name": "RegisterSource",
"description": "Register an audio source.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "Source",
"description": "Source info. Example: {\"id\":0,\"name\":\"TTS\",\"role\":\"speech\",\"preferred_outputs\":[\"Speaker0\"],\"priority\":0}",
"type": "Object",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "Number",
"description": "Registered source id."
}
}
CLI 命令
svc_call AudioDecoder0 RegisterSource {"Source":null}
UnregisterSource
描述
Unregister an audio source by name.
执行要求
是否需要调度器: 不需要
参数
SourceName类型:
String是否必填: 必填
描述: Source name.
Schema JSON
展开查看 JSON
{
"name": "UnregisterSource",
"description": "Unregister an audio source by name.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Source name.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call AudioDecoder0 UnregisterSource {"SourceName":null}
RequestOutput
描述
Request an output for an audio source.
执行要求
是否需要调度器: 不需要
参数
SourceName类型:
String是否必填: 必填
描述: Source name.
OutputName类型:
String是否必填: 必填
描述: Output name.
Schema JSON
展开查看 JSON
{
"name": "RequestOutput",
"description": "Request an output for an audio source.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Source name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "OutputName",
"description": "Output name.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call AudioDecoder0 RequestOutput {"SourceName":null,"OutputName":null}
ReleaseOutput
描述
Release an output from an audio source.
执行要求
是否需要调度器: 不需要
参数
SourceName类型:
String是否必填: 必填
描述: Source name.
OutputName类型:
String是否必填: 必填
描述: Output name.
Schema JSON
展开查看 JSON
{
"name": "ReleaseOutput",
"description": "Release an output from an audio source.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Source name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "OutputName",
"description": "Output name.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call AudioDecoder0 ReleaseOutput {"SourceName":null,"OutputName":null}
SetActiveSource
描述
Set the active audio source for an output.
执行要求
是否需要调度器: 不需要
参数
OutputName类型:
String是否必填: 必填
描述: Output name.
SourceName类型:
String是否必填: 必填
描述: Source name.
Schema JSON
展开查看 JSON
{
"name": "SetActiveSource",
"description": "Set the active audio source for an output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Output name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "SourceName",
"description": "Source name.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call AudioDecoder0 SetActiveSource {"OutputName":null,"SourceName":null}
GetActiveSource
描述
Get the active audio source name for an output.
执行要求
是否需要调度器: 不需要
参数
OutputName类型:
String是否必填: 必填
描述: Output name.
返回值
类型:
String描述: Active source name, or an empty string when no source is active.
Schema JSON
展开查看 JSON
{
"name": "GetActiveSource",
"description": "Get the active audio source name for an output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Output name.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "String",
"description": "Active source name, or an empty string when no source is active."
}
}
CLI 命令
svc_call AudioDecoder0 GetActiveSource {"OutputName":null}
OpenStream
描述
Open a direct audio stream for a source and output.
执行要求
是否需要调度器: 不需要
参数
SourceName类型:
String是否必填: 必填
描述: Source name.
OutputName类型:
String是否必填: 必填
描述: Output name.
Config类型:
Object是否必填: 必填
描述: Stream config. Example: {"type":"PCM","general":{"channels":0,"sample_bits":0,"sample_rate":0,"frame_duration":0},"queue_size_bytes":32768,"queue_policy":"DropNewest"}
Schema JSON
展开查看 JSON
{
"name": "OpenStream",
"description": "Open a direct audio stream for a source and output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Source name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "OutputName",
"description": "Output name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "Config",
"description": "Stream config. Example: {\"type\":\"PCM\",\"general\":{\"channels\":0,\"sample_bits\":0,\"sample_rate\":0,\"frame_duration\":0},\"queue_size_bytes\":32768,\"queue_policy\":\"DropNewest\"}",
"type": "Object",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call AudioDecoder0 OpenStream {"SourceName":null,"OutputName":null,"Config":null}
CloseStream
描述
Close a direct audio stream for a source and output.
执行要求
是否需要调度器: 不需要
参数
SourceName类型:
String是否必填: 必填
描述: Source name.
OutputName类型:
String是否必填: 必填
描述: Output name.
Schema JSON
展开查看 JSON
{
"name": "CloseStream",
"description": "Close a direct audio stream for a source and output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Source name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "OutputName",
"description": "Output name.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call AudioDecoder0 CloseStream {"SourceName":null,"OutputName":null}
事件
播放
PlayStateChanged
描述
Emitted when playback state changes.
执行要求
是否需要调度器: 需要
参数
State类型:
String描述: Playback state. Allowed values: [Idle, Playing, Paused]
Schema JSON
展开查看 JSON
{
"name": "PlayStateChanged",
"description": "Emitted when playback state changes.",
"require_scheduler": true,
"items": [
{
"name": "State",
"description": "Playback state. Allowed values: [Idle, Playing, Paused]",
"type": "String"
}
]
}
CLI 命令
svc_subscribe AudioPlayback PlayStateChanged
VolumeChanged
描述
Emitted when the target audio playback volume changes.
执行要求
是否需要调度器: 需要
参数
Volume类型:
Number描述: Current target playback volume percentage [0, 100].
Schema JSON
展开查看 JSON
{
"name": "VolumeChanged",
"description": "Emitted when the target audio playback volume changes.",
"require_scheduler": true,
"items": [
{
"name": "Volume",
"description": "Current target playback volume percentage [0, 100].",
"type": "Number"
}
]
}
CLI 命令
svc_subscribe AudioPlayback VolumeChanged
MuteChanged
描述
Emitted when the target audio playback mute state changes.
执行要求
是否需要调度器: 需要
参数
IsMuted类型:
Boolean描述: Whether audio playback is currently muted. True if muted, false if unmuted.
Schema JSON
展开查看 JSON
{
"name": "MuteChanged",
"description": "Emitted when the target audio playback mute state changes.",
"require_scheduler": true,
"items": [
{
"name": "IsMuted",
"description": "Whether audio playback is currently muted. True if muted, false if unmuted.",
"type": "Boolean"
}
]
}
CLI 命令
svc_subscribe AudioPlayback MuteChanged
编码器
AFEEventHappened
描述
Emitted when an AFE event occurs.
执行要求
是否需要调度器: 需要
参数
Event类型:
String描述: AFE event. Allowed values: [VAD_Start, VAD_End, WakeStart, WakeEnd]
Schema JSON
展开查看 JSON
{
"name": "AFEEventHappened",
"description": "Emitted when an AFE event occurs.",
"require_scheduler": true,
"items": [
{
"name": "Event",
"description": "AFE event. Allowed values: [VAD_Start, VAD_End, WakeStart, WakeEnd]",
"type": "String"
}
]
}
CLI 命令
svc_subscribe AudioEncoder0 AFEEventHappened
解码器
无。