音频

组件注册表： espressif/brookesia_service_audio
辅助头文件： #include "brookesia/service_helper/audio.hpp"
辅助类： esp_brookesia::service::helper::Audio

概述

brookesia_service_audio 是为 ESP-Brookesia 生态系统提供的音频服务，提供：

音频播放：支持从 URL 播放音频文件，支持暂停、恢复、停止等播放控制。
音频编解码：支持多种音频编解码格式（PCM、OPUS、G711A），支持编码和解码功能。
音量控制：支持音量设置和查询，提供完整的音量管理能力。
播放状态管理：实时跟踪播放状态（空闲、播放中、暂停），并通过事件通知状态变化。
编码器管理：支持编码器的启动、停止和配置，可设置编码器读取数据大小。
解码器管理：支持解码器的启动、停止和数据输入，支持流式解码。
持久化存储：可选搭配 brookesia_service_nvs 服务持久化保存音量等信息。

功能特性

音频编解码格式

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）。
编码器事件：编码器事件发生时触发。
编码数据就绪：编码数据准备好时触发。

服务接口

函数

`SetPlaybackConfig`

描述

Set playback config. Call before starting the service.

执行要求

是否需要调度器: 不需要

参数

Config
- 类型: Object
- 是否必填: 必填
- 描述: Playback config. Example: {“player_task”:{“name”:”Thread”,”core_id”:0,”priority”:5,”stack_size”:4096,”stack_in_ext”:true},”mixer_gain”:{“initial_gain”:6.000000238418579E-1,”target_gain”:1E0,”transition_time”:1500}}

Schema JSON

展开查看 JSON


{
  "name": "SetPlaybackConfig",
  "description": "Set playback config. Call before starting the service.",
  "require_scheduler": false,
  "parameters": [
    {
      "name": "Config",
      "description": "Playback config. Example: {\"player_task\":{\"name\":\"Thread\",\"core_id\":0,\"priority\":5,\"stack_size\":4096,\"stack_in_ext\":true},\"mixer_gain\":{\"initial_gain\":6.000000238418579E-1,\"target_gain\":1E0,\"transition_time\":1500}}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio SetPlaybackConfig {"Config":null}

`SetEncoderStaticConfig`

描述

Set encoder static config. Call before starting the service.

执行要求

是否需要调度器: 不需要

参数

Config
- 类型: Object
- 是否必填: 必填
- 描述: Encoder static config. Example: {“recorder_task”:{“name”:”Thread”,”core_id”:0,”priority”:10,”stack_size”:4096,”stack_in_ext”:true},”fetcher_task”:{“name”:”EncoderFetcher”,”core_id”:1,”priority”:12,”stack_size”:6144,”stack_in_ext”:true}}

Schema JSON

展开查看 JSON


{
  "name": "SetEncoderStaticConfig",
  "description": "Set encoder static config. Call before starting the service.",
  "require_scheduler": false,
  "parameters": [
    {
      "name": "Config",
      "description": "Encoder static config. Example: {\"recorder_task\":{\"name\":\"Thread\",\"core_id\":0,\"priority\":10,\"stack_size\":4096,\"stack_in_ext\":true},\"fetcher_task\":{\"name\":\"EncoderFetcher\",\"core_id\":1,\"priority\":12,\"stack_size\":6144,\"stack_in_ext\":true}}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio SetEncoderStaticConfig {"Config":null}

`SetDecoderStaticConfig`

描述

Set decoder static config. Call before starting the service.

执行要求

是否需要调度器: 不需要

参数

Config
- 类型: Object
- 是否必填: 必填
- 描述: Decoder static config. Example: {“feeder_task”:{“name”:”Thread”,”core_id”:1,”priority”:5,”stack_size”:4096,”stack_in_ext”:true},”mixer_gain”:{“initial_gain”:8.999999761581421E-1,”target_gain”:1E0,”transition_time”:1500}}

Schema JSON

展开查看 JSON


{
  "name": "SetDecoderStaticConfig",
  "description": "Set decoder static config. Call before starting the service.",
  "require_scheduler": false,
  "parameters": [
    {
      "name": "Config",
      "description": "Decoder static config. Example: {\"feeder_task\":{\"name\":\"Thread\",\"core_id\":1,\"priority\":5,\"stack_size\":4096,\"stack_in_ext\":true},\"mixer_gain\":{\"initial_gain\":8.999999761581421E-1,\"target_gain\":1E0,\"transition_time\":1500}}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio SetDecoderStaticConfig {"Config":null}

`SetAFE_Config`

描述

Set AFE config. Call before starting the service.

执行要求

是否需要调度器: 不需要

参数

Config
- 类型: Object
- 是否必填: 必填
- 描述: AFE config. Example: {“feeder_task”:{“name”:”Thread”,”core_id”:1,”priority”:5,”stack_size”:40960,”stack_in_ext”:true},”fetcher_task”:{“name”:”Thread”,”core_id”:0,”priority”:5,”stack_size”:6144,”stack_in_ext”:true},”vad”:null,”wakenet”:null}

Schema JSON

展开查看 JSON


{
  "name": "SetAFE_Config",
  "description": "Set AFE config. Call before starting the service.",
  "require_scheduler": false,
  "parameters": [
    {
      "name": "Config",
      "description": "AFE config. Example: {\"feeder_task\":{\"name\":\"Thread\",\"core_id\":1,\"priority\":5,\"stack_size\":40960,\"stack_in_ext\":true},\"fetcher_task\":{\"name\":\"Thread\",\"core_id\":0,\"priority\":5,\"stack_size\":6144,\"stack_in_ext\":true},\"vad\":null,\"wakenet\":null}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio SetAFE_Config {"Config":null}

`GetAFE_WakeWords`

描述

Get AFE wake words. Return type: JSON array<string>. Example: [“ni hao xiao zhi”,”hello brookesia”]

执行要求

是否需要调度器: 不需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetAFE_WakeWords",
  "description": "Get AFE wake words. Return type: JSON array<string>. Example: [\"ni hao xiao zhi\",\"hello brookesia\"]",
  "require_scheduler": false,
  "parameters": []
}

CLI 命令

svc_call Audio GetAFE_WakeWords

`PauseAFE_WakeupEnd`

描述

Pause AFE wakeup-end task.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "PauseAFE_WakeupEnd",
  "description": "Pause AFE wakeup-end task.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Audio PauseAFE_WakeupEnd

`ResumeAFE_WakeupEnd`

描述

Resume AFE wakeup-end task.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "ResumeAFE_WakeupEnd",
  "description": "Resume AFE wakeup-end task.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Audio ResumeAFE_WakeupEnd

`PlayUrl`

描述

Play audio from a URL. Supports loop and interrupt playback.

执行要求

是否需要调度器: 需要

参数

Url
- 类型: String
- 是否必填: 必填
- 描述: Audio URL, for example: “file://spiffs/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": "PlayUrl",
  "description": "Play audio from a URL. Supports loop and interrupt playback.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Url",
      "description": "Audio URL, for example: \"file://spiffs/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
      }
    }
  ]
}

CLI 命令

svc_call Audio PlayUrl {"Url":null,"Config":null}

`PlayUrls`

描述

Play audio from multiple URLs. Supports loop and interrupt playback.

执行要求

是否需要调度器: 需要

参数

Urls
- 类型: Array
- 是否必填: 必填
- 描述: Audio URL list. Example: [”file://spiffs/example1.mp3”,”file://spiffs/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,
  "parameters": [
    {
      "name": "Urls",
      "description": "Audio URL list. Example: [\"file://spiffs/example1.mp3\",\"file://spiffs/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
      }
    }
  ]
}

CLI 命令

svc_call Audio PlayUrls {"Urls":null,"Config":null}

`PlayControl`

描述

Control audio playback.

执行要求

是否需要调度器: 需要

参数

Action
- 类型: String
- 是否必填: 必填
- 描述: Playback action. Allowed values: [Pause, Resume, Stop]

Schema JSON

展开查看 JSON


{
  "name": "PlayControl",
  "description": "Control audio playback.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Action",
      "description": "Playback action. Allowed values: [Pause, Resume, Stop]",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio PlayControl {"Action":null}

`SetVolume`

描述

Set playback volume.

执行要求

是否需要调度器: 需要

参数

Volume
- 类型: Number
- 是否必填: 必填
- 描述: Volume in range [0, 100].

Schema JSON

展开查看 JSON


{
  "name": "SetVolume",
  "description": "Set playback volume.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Volume",
      "description": "Volume in range [0, 100].",
      "type": "Number",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio SetVolume {"Volume":null}

`GetVolume`

描述

Get playback volume. Return type: number. Example: 70

执行要求

是否需要调度器: 不需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetVolume",
  "description": "Get playback volume. Return type: number. Example: 70",
  "require_scheduler": false,
  "parameters": []
}

CLI 命令

svc_call Audio GetVolume

`SetMute`

描述

Set playback mute.

执行要求

是否需要调度器: 需要

参数

Enable
- 类型: Boolean
- 是否必填: 必填
- 描述: Enable mute.

Schema JSON

展开查看 JSON


{
  "name": "SetMute",
  "description": "Set playback mute.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Enable",
      "description": "Enable mute.",
      "type": "Boolean",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio SetMute {"Enable":null}

`StartEncoder`

描述

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}

Schema JSON

展开查看 JSON


{
  "name": "StartEncoder",
  "description": "Start audio encoder.",
  "require_scheduler": true,
  "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}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio StartEncoder {"Config":null}

`StopEncoder`

描述

Stop audio encoder.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "StopEncoder",
  "description": "Stop audio encoder.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Audio StopEncoder

`PauseEncoder`

描述

Pause audio encoder.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "PauseEncoder",
  "description": "Pause audio encoder.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Audio PauseEncoder

`ResumeEncoder`

描述

Resume audio encoder.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "ResumeEncoder",
  "description": "Resume audio encoder.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Audio ResumeEncoder

`StartDecoder`

描述

Start audio decoder.

执行要求

是否需要调度器: 需要

参数

Config
- 类型: Object
- 是否必填: 必填
- 描述: Audio decoder config. Example: {“type”:”PCM”,”general”:{“channels”:0,”sample_bits”:0,”sample_rate”:0,”frame_duration”:0}}

Schema JSON

展开查看 JSON


{
  "name": "StartDecoder",
  "description": "Start audio decoder.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Config",
      "description": "Audio decoder config. Example: {\"type\":\"PCM\",\"general\":{\"channels\":0,\"sample_bits\":0,\"sample_rate\":0,\"frame_duration\":0}}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio StartDecoder {"Config":null}

`StopDecoder`

描述

Stop audio decoder.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "StopDecoder",
  "description": "Stop audio decoder.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Audio StopDecoder

`FeedDecoderData`

描述

Feed audio data to the decoder.

执行要求

是否需要调度器: 不需要

参数

Data
- 类型: RawBuffer
- 是否必填: 必填
- 描述: Audio data to decode.

Schema JSON

展开查看 JSON


{
  "name": "FeedDecoderData",
  "description": "Feed audio data to the decoder.",
  "require_scheduler": false,
  "parameters": [
    {
      "name": "Data",
      "description": "Audio data to decode.",
      "type": "RawBuffer",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Audio FeedDecoderData {"Data":null}

`ResetData`

描述

Reset audio data. Includes player volume.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "ResetData",
  "description": "Reset audio data. Includes player volume.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Audio ResetData

事件

`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 Audio PlayStateChanged

`AFE_EventHappened`

描述

Emitted when an AFE event occurs.

执行要求

是否需要调度器: 需要

参数

Event
- 类型: String
- 描述: AFE event. Allowed values: [VAD_Start, VAD_End, WakeStart, WakeEnd]

Schema JSON

展开查看 JSON


{
  "name": "AFE_EventHappened",
  "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 Audio AFE_EventHappened

`EncoderDataReady`

描述

Emitted when encoder data is ready.

执行要求

是否需要调度器: 不需要

参数

Data
- 类型: RawBuffer
- 描述: Encoded audio data.

Schema JSON

展开查看 JSON


{
  "name": "EncoderDataReady",
  "description": "Emitted when encoder data is ready.",
  "require_scheduler": false,
  "items": [
    {
      "name": "Data",
      "description": "Encoded audio data.",
      "type": "RawBuffer"
    }
  ]
}

CLI 命令

svc_subscribe Audio EncoderDataReady

`RecorderDataReady`

描述

Emitted when recorder data is ready.

执行要求

是否需要调度器: 不需要

参数

Data
- 类型: RawBuffer
- 描述: Recorded raw audio data.

Schema JSON

展开查看 JSON


{
  "name": "RecorderDataReady",
  "description": "Emitted when recorder data is ready.",
  "require_scheduler": false,
  "items": [
    {
      "name": "Data",
      "description": "Recorded raw audio data.",
      "type": "RawBuffer"
    }
  ]
}

CLI 命令

svc_subscribe Audio RecorderDataReady

音频

概述

功能特性

音频编解码格式

播放控制

编码器配置

解码器配置

事件通知

服务接口

函数

SetPlaybackConfig

描述

执行要求

参数

Schema JSON

CLI 命令

SetEncoderStaticConfig

描述

执行要求

参数

Schema JSON

CLI 命令

SetDecoderStaticConfig

描述

执行要求

参数

Schema JSON

CLI 命令

SetAFE_Config

描述

执行要求

参数

Schema JSON

CLI 命令

GetAFE_WakeWords

描述

执行要求

参数

Schema JSON

CLI 命令

PauseAFE_WakeupEnd

描述

执行要求

参数

Schema JSON

CLI 命令

ResumeAFE_WakeupEnd

描述

执行要求

参数

Schema JSON

CLI 命令

PlayUrl

描述

执行要求

参数

Schema JSON

CLI 命令

PlayUrls

描述

执行要求

参数

Schema JSON

CLI 命令

PlayControl

描述

执行要求

参数

Schema JSON

CLI 命令

SetVolume

描述

执行要求

参数

Schema JSON

CLI 命令

GetVolume

描述

执行要求

参数

`SetPlaybackConfig`

`SetEncoderStaticConfig`

`SetDecoderStaticConfig`

`SetAFE_Config`

`GetAFE_WakeWords`

`PauseAFE_WakeupEnd`

`ResumeAFE_WakeupEnd`

`PlayUrl`

`PlayUrls`

`PlayControl`

`SetVolume`

`GetVolume`

`SetMute`

`StartEncoder`

`StopEncoder`

`PauseEncoder`

`ResumeEncoder`

`StartDecoder`

`StopDecoder`

`FeedDecoderData`

`ResetData`

`PlayStateChanged`

`AFE_EventHappened`

`EncoderDataReady`