Audio

[中文]

  • Component registry: espressif/brookesia_service_audio

  • Helper header: #include "brookesia/service_helper/audio.hpp"

  • Helper class: esp_brookesia::service::helper::Audio

Overview

brookesia_service_audio provides:

  • Playback: Stream from URL; pause, resume, stop.

  • Codecs: PCM, OPUS, G711A encode/decode.

  • Volume: Set and query volume.

  • Playback state: Idle / playing / paused with events.

  • Encoder: Start/stop/configure; configurable read size.

  • Decoder: Start/stop and feed compressed data; streaming decode.

  • Persistence: Optional brookesia_service_nvs for volume and related settings.

Features

Codec Formats

The audio service supports the following codec formats:

Format

Encode

Decode

Notes

PCM

Yes

Yes

Lossless

OPUS

Yes

Yes

VBR and fixed bitrate

G711A

Yes

Yes

Telephony quality

Playback

  • URL playback.

  • Pause, resume, stop.

  • State events for UI sync.

Encoder Configuration

  • Codecs: PCM, OPUS, G711A.

  • Channels: 1–4.

  • Bits per sample: 8, 16, 24, 32.

  • Sample rates: 8000, 16000, 24000, 32000, 44100, 48000 Hz.

  • Frame duration (ms).

  • OPUS: VBR and bitrate.

Decoder Configuration

  • Codecs: PCM, OPUS, G711A.

  • Channels: 1–4.

  • Bits per sample: 8, 16, 24, 32.

  • Sample rates: 8000, 16000, 24000, 32000, 44100, 48000 Hz.

  • Frame duration (ms).

Events

  • Playback state changes (Idle, Playing, Paused).

  • Encoder events.

  • Encoded data ready.

Standard Include / Helper Class

  • Standard include: #include \"brookesia/service_helper/audio.hpp\"

  • Helper class: esp_brookesia::service::helper::Audio

Service Interfaces

Functions

SetPlaybackConfig

Description

Set playback config. Call before starting the service.

Execution

  • Requires scheduler: Not required

Parameters

  • Config

    • Type: Object

    • Required: required

    • 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}}

Schema JSON
Show raw 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 Command
svc_call Audio SetPlaybackConfig {"Config":null}

SetEncoderStaticConfig

Description

Set encoder static config. Call before starting the service.

Execution

  • Requires scheduler: Not required

Parameters

  • Config

    • Type: Object

    • Required: required

    • 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}}

Schema JSON
Show raw 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 Command
svc_call Audio SetEncoderStaticConfig {"Config":null}

SetDecoderStaticConfig

Description

Set decoder static config. Call before starting the service.

Execution

  • Requires scheduler: Not required

Parameters

  • Config

    • Type: Object

    • Required: required

    • 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}}

Schema JSON
Show raw 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 Command
svc_call Audio SetDecoderStaticConfig {"Config":null}

SetAFE_Config

Description

Set AFE config. Call before starting the service.

Execution

  • Requires scheduler: Not required

Parameters

  • Config

    • Type: Object

    • Required: required

    • 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}

Schema JSON
Show raw 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 Command
svc_call Audio SetAFE_Config {"Config":null}

GetAFE_WakeWords

Description

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

Execution

  • Requires scheduler: Not required

Parameters

  • No parameters.

Schema JSON
Show raw 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 Command
svc_call Audio GetAFE_WakeWords

PauseAFE_WakeupEnd

Description

Pause AFE wakeup-end task.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

ResumeAFE_WakeupEnd

Description

Resume AFE wakeup-end task.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

PlayUrl

Description

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

Execution

  • Requires scheduler: Required

Parameters

  • Url

  • Config

    • Type: Object

    • Required: optional

    • Default: {"interrupt":true,"delay_ms":0,"loop_count":0,"loop_interval_ms":0,"timeout_ms":0}

    • Description: Playback config. Example: {“interrupt”:true,”delay_ms”:0,”loop_count”:0,”loop_interval_ms”:0,”timeout_ms”:0}

Schema JSON
Show raw 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 Command
svc_call Audio PlayUrl {"Url":null,"Config":null}

PlayUrls

Description

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

Execution

  • Requires scheduler: Required

Parameters

  • Urls

  • Config

    • Type: Object

    • Required: optional

    • Default: {"interrupt":true,"delay_ms":0,"loop_count":0,"loop_interval_ms":0,"timeout_ms":0}

    • Description: Playback config. Example: {“interrupt”:true,”delay_ms”:0,”loop_count”:0,”loop_interval_ms”:0,”timeout_ms”:0}

Schema JSON
Show raw 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 Command
svc_call Audio PlayUrls {"Urls":null,"Config":null}

PlayControl

Description

Control audio playback.

Execution

  • Requires scheduler: Required

Parameters

  • Action

    • Type: String

    • Required: required

    • Description: Playback action. Allowed values: [Pause, Resume, Stop]

Schema JSON
Show raw 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 Command
svc_call Audio PlayControl {"Action":null}

SetVolume

Description

Set playback volume.

Execution

  • Requires scheduler: Required

Parameters

  • Volume

    • Type: Number

    • Required: required

    • Description: Volume in range [0, 100].

Schema JSON
Show raw 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 Command
svc_call Audio SetVolume {"Volume":null}

GetVolume

Description

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

Execution

  • Requires scheduler: Not required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

SetMute

Description

Set playback mute.

Execution

  • Requires scheduler: Required

Parameters

  • Enable

    • Type: Boolean

    • Required: required

    • Description: Enable mute.

Schema JSON
Show raw JSON 

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

StartEncoder

Description

Start audio encoder.

Execution

  • Requires scheduler: Required

Parameters

  • Config

    • Type: Object

    • Required: required

    • 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}

Schema JSON
Show raw 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 Command
svc_call Audio StartEncoder {"Config":null}

StopEncoder

Description

Stop audio encoder.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

PauseEncoder

Description

Pause audio encoder.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

ResumeEncoder

Description

Resume audio encoder.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

StartDecoder

Description

Start audio decoder.

Execution

  • Requires scheduler: Required

Parameters

  • Config

    • Type: Object

    • Required: required

    • Description: Audio decoder config. Example: {“type”:”PCM”,”general”:{“channels”:0,”sample_bits”:0,”sample_rate”:0,”frame_duration”:0}}

Schema JSON
Show raw 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 Command
svc_call Audio StartDecoder {"Config":null}

StopDecoder

Description

Stop audio decoder.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

FeedDecoderData

Description

Feed audio data to the decoder.

Execution

  • Requires scheduler: Not required

Parameters

  • Data

    • Type: RawBuffer

    • Required: required

    • Description: Audio data to decode.

Schema JSON
Show raw 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 Command
svc_call Audio FeedDecoderData {"Data":null}

ResetData

Description

Reset audio data. Includes player volume.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

Events

PlayStateChanged

Description

Emitted when playback state changes.

Execution

  • Requires scheduler: Required

Items

  • State

    • Type: String

    • Description: Playback state. Allowed values: [Idle, Playing, Paused]

Schema JSON
Show raw 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 Command
svc_subscribe Audio PlayStateChanged

AFE_EventHappened

Description

Emitted when an AFE event occurs.

Execution

  • Requires scheduler: Required

Items

  • Event

    • Type: String

    • Description: AFE event. Allowed values: [VAD_Start, VAD_End, WakeStart, WakeEnd]

Schema JSON
Show raw 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 Command
svc_subscribe Audio AFE_EventHappened

EncoderDataReady

Description

Emitted when encoder data is ready.

Execution

  • Requires scheduler: Not required

Items

  • Data

    • Type: RawBuffer

    • Description: Encoded audio data.

Schema JSON
Show raw JSON 

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

RecorderDataReady

Description

Emitted when recorder data is ready.

Execution

  • Requires scheduler: Not required

Items

  • Data

    • Type: RawBuffer

    • Description: Recorded raw audio data.

Schema JSON
Show raw JSON 

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