Audio Module

AudioManager is the entry point for the audio module. Do not construct AudioPlayer, AudioRecorder, AudioLocalizer, or AudioCaptureStream directly. Initialize AudioManager, then create child objects through its factory methods.

Source headers:

• include/booster/robot/audio/audio_manager.h
• include/booster/robot/audio/audio_player.h
• include/booster/robot/audio/audio_recorder.h
• include/booster/robot/audio/audio_localizer.h
• include/booster/robot/audio/audio_capture_stream.h
• include/booster/robot/audio/audio_types.h

Initialization

#include <booster/robot/audio/audio_manager.h>
#include <booster/robot/channel/channel_factory.hpp>

booster::robot::ChannelFactory::Instance()->Init(0, "<network_ip>");

booster::robot::audio::AudioManager manager;
if (manager.Init() != 0) {
    return 1;
}

const bool ready = manager.IsInitialized();
const std::string client_id = manager.GetClientId();

// Shut down the manager after all child objects have been released.
manager.Shutdown();

AudioManager

Method	Description
Init() / Shutdown()	Initialize or shut down audio resources.
IsInitialized()	Query manager state.
GetClientId()	Return the client ID registered with the audio service.
GenerateRequestId()	Generate a request ID.
CreatePlayer()	Create an audio player.
CreateRecorder()	Create an audio recorder.
CreateLocalizer()	Create a sound-source localizer.
CreateCaptureStream()	Create an audio-frame capture stream.
SetSystemVolume(float volume) / GetSystemVolume(float *volume)	Set or read system output volume. The service accepts values in [0.0, 1.0]; the getter writes the value to its output argument.
SetSystemMute(bool mute) / GetSystemMute(bool *mute)	Set or read the system mute state; the getter writes to its output argument.
GetDevices(query_type, devices)	Enumerate input or output endpoints. query_type must be GET_DEVICES_INPUTS or GET_DEVICES_OUTPUTS.
StartBluetoothScan(options) / StopBluetoothScan()	Start or stop Bluetooth discovery; timeout_ms must not be negative.
GetBluetoothDevices(include_unpaired, devices)	Return known Bluetooth devices, optionally including unpaired devices.
ConnectBluetoothDevice(options, result)	Pair/connect an endpoint and optionally apply the default route according to make_default. The connection timeout is max(5000, options.timeout_ms).
DisconnectBluetoothDevice(address)	Disconnect a device by Bluetooth address.
ForgetBluetoothDevice(address)	Remove pairing/trust information for a device.
SetProgressCallback(callback)	Register a service-level progress-topic callback.
SetEventCallback(callback)	Register a service-level event-topic callback.
SetErrorCallback(callback)	Register a service-level error-topic callback.
SetBluetoothEventCallback(callback)	Register a Bluetooth state-event callback.

System volume and mute state:

manager.SetSystemVolume(0.6F);

float volume = 0.0F;
manager.GetSystemVolume(&volume);

manager.SetSystemMute(false);

bool muted = false;
manager.GetSystemMute(&muted);

Player

AudioPlayer supports PCM, WAV, and MP3 files as well as PCM streams.

File playback:

#include <booster/robot/audio/audio_player.h>

auto player = manager.CreatePlayer();

booster::robot::audio::PlayerInitOptions options;
options.source_type = booster::robot::audio::AudioSourceType::kWavFile;
options.source_uri = "<audio.wav>";
options.priority = booster::robot::audio::PlayerPriority::kMedium;

if (player->Init(options) == 0) {
    player->Start();

    booster::robot::audio::PlayerInfo info;
    player->GetInfo(&info);

    player->Stop();
    player->Release();
}

PCM stream:

#include <cstdint>
#include <vector>

auto player = manager.CreatePlayer();

booster::robot::audio::PlayerInitOptions options;
options.source_type = booster::robot::audio::AudioSourceType::kPcmStream;
options.sample_rate_hz = 16000;
options.channels = 1;
options.bits_per_sample = 16;

if (player->Init(options) == 0) {
    player->Start();

    std::vector<uint8_t> pcm(3200, 0);
    player->PushPcmStream(pcm.data(), pcm.size());

    player->Stop();
    player->Release();
}

Available callbacks:

• SetStateCallback(callback)
• SetProgressCallback(callback)
• SetCompletionCallback(callback)
• SetErrorCallback(callback)

Public player interface:

C++ method	Python method	Description
Init(const PlayerInitOptions &options)	Init(options)	Create the playback session and negotiate the input format; returns 0 on success.
Start()	Start()	Start or resume playback; Init must have succeeded first.
Pause()	Pause()	Pause playback while retaining the current position.
Stop()	Stop()	Stop playback and reset the play cursor.
Reset()	Reset()	Reset a stopped or completed player for reuse.
Destroy()	Destroy()	Release the service-side playback session.
Release()	Release()	Compatibility alias for Destroy() with identical semantics.
SetVolume(float volume)	SetVolume(volume)	Set session volume in the range [0.0, 1.0].
SetPreferredDevice(const std::string &device_id)	SetPreferredDevice(device_id)	Select the preferred output endpoint for this session; use an output device ID.
GetInfo(PlayerInfo *out) const	GetInfo()	Read the cached playback snapshot, including state, byte progress, and volume.
PushPcmStream(const uint8_t *data, size_t size)	PushPcmStream(data)	Push non-empty PCM bytes to a kPcmStream session after Start.
GetSessionId() const	GetSessionId()	Return the service-side session ID.
GetCachedState() const	GetCachedState()	Read the latest locally observed state without an RPC.
SetStateCallback(callback)	SetStateCallback(callback)	Invoke the callback with PlayerState when state changes.
SetProgressCallback(callback)	SetProgressCallback(callback)	Invoke the callback with PlayerInfo on progress updates.
SetCompletionCallback(callback)	SetCompletionCallback(callback)	Invoke once when the state first becomes kCompleted.
SetErrorCallback(callback)	SetErrorCallback(callback)	Invoke with AudioError on service errors and cache kError.

Call SetPreferredDevice only after a successful Init. File source_uri values must be absolute paths readable by the robot-side audio service; PCM files also require the correct sample rate, channel count, and sample width. Streaming requires source_type == kPcmStream; the URI may be empty, but pushed data must be non-empty.

Recorder

#include <booster/robot/audio/audio_recorder.h>

auto recorder = manager.CreateRecorder();

booster::robot::audio::RecorderInitOptions options;
options.output_path = "<record.wav>";
options.sample_rate_hz = 16000;
options.channels = 1;
options.bits_per_sample = 16;

if (recorder->Init(options) == 0) {
    recorder->Start();

    booster::robot::audio::RecorderInfo info;
    recorder->GetInfo(&info);

    recorder->Stop();
    recorder->Release();
}

Available callbacks:

• SetStateCallback(callback)
• SetProgressCallback(callback)
• SetErrorCallback(callback)

Public recorder interface:

C++ method	Python method	Description
Init(const RecorderInitOptions &options)	Init(options)	Create a recording session. The output path must be an absolute path writable by the robot audio service.
Start()	Start()	Start or resume recording; Init must have succeeded first.
Pause()	Pause()	Pause recording while retaining the session.
Stop()	Stop()	Stop recording and finalize the output file.
Destroy()	Destroy()	Release the service-side recording session.
Release()	Release()	Compatibility alias for Destroy() with identical semantics.
GetInfo(RecorderInfo *out) const	GetInfo()	Read the cached recorder state and captured-byte count.
SetPreferredDevice(const std::string &device_id)	SetPreferredDevice(device_id)	Select the preferred input endpoint for this session; use an input device ID.
GetSessionId() const	GetSessionId()	Return the service-side session ID.
GetCachedState() const	GetCachedState()	Read the latest locally observed state without an RPC.
SetStateCallback(callback)	SetStateCallback(callback)	Invoke the callback with RecorderState when state changes.
SetProgressCallback(callback)	SetProgressCallback(callback)	Invoke the callback with RecorderInfo on progress updates.
SetErrorCallback(callback)	SetErrorCallback(callback)	Invoke with AudioError on service errors and cache kError.

sample_rate_hz, channels, and bits_per_sample must all be positive. Running recording sessions currently cannot migrate input devices; stop/destroy and reinitialize with the new device. After recording, explicitly call Stop and then Destroy or Release.

Audio Capture Stream

AudioCaptureStream subscribes to audio frames and can request raw PCM and NAEC PCM.

#include <iostream>

#include <booster/robot/audio/audio_capture_stream.h>

auto capture = manager.CreateCaptureStream();

booster::robot::audio::AudioCaptureStreamOptions options;
options.enable_raw_pcm = true;
options.enable_naec_pcm = false;
options.requested_raw_format = {16000, 1, 16};

capture->SetFrameCallback(
    [](const booster::robot::audio::AudioCaptureFrame &frame) {
        if (frame.raw_valid) {
            std::cout << frame.frame_seq << " "
                      << frame.raw_pcm.size() << "\n";
        }
    });

if (capture->Init(options) == 0) {
    capture->Start();
    // Process callbacks while the stream is active.
    capture->Stop();
    capture->Destroy();
}

Available methods:

• Init(options)
• Start() / Pause() / Stop() / Destroy()
• GetInfo(out)
• SetPreferredDevice(device_id)
• SetFrameCallback, SetStateCallback, and SetErrorCallback

Sound-Source Localization

#include <booster/robot/audio/audio_localizer.h>

auto localizer = manager.CreateLocalizer();

int angle_deg = 0;
if (localizer->GetDoaAngle(&angle_deg) == 0) {
    std::cout << angle_deg << "\n";
}

Device Queries and Bluetooth

Query input and output devices:

#include <vector>

std::vector<booster::robot::audio::AudioDeviceInfo> outputs;
manager.GetDevices(
    booster::robot::audio::AudioDeviceQueryType::GET_DEVICES_OUTPUTS,
    &outputs);

for (const auto &device : outputs) {
    std::cout << device.device_id << " "
              << device.display_name << "\n";
}

Scan and connect over Bluetooth:

booster::robot::audio::BluetoothScanOptions scan;
scan.timeout_ms = 30000;
scan.audio_only = true;

manager.StartBluetoothScan(scan);

std::vector<booster::robot::audio::BluetoothDeviceInfo> devices;
manager.GetBluetoothDevices(true, &devices);
manager.StopBluetoothScan();

if (!devices.empty()) {
    booster::robot::audio::BluetoothConnectOptions options;
    options.address = devices.front().address;
    options.preferred_profile =
        booster::robot::audio::BluetoothAudioProfile::kNone;

    booster::robot::audio::BluetoothConnectResult result;
    manager.ConnectBluetoothDevice(options, &result);
}

Bluetooth methods:

• StartBluetoothScan(options)
• StopBluetoothScan()
• GetBluetoothDevices(include_unpaired, devices)
• ConnectBluetoothDevice(options, result)
• DisconnectBluetoothDevice(address)
• ForgetBluetoothDevice(address)

Event Callbacks

AudioManager supports global topic callbacks:

• SetProgressCallback(callback)
• SetEventCallback(callback)
• SetErrorCallback(callback)
• SetBluetoothEventCallback(callback)

Child objects also provide state, progress, error, completion, or frame callbacks. Callbacks run from DDS topic handling; avoid long blocking operations inside them.

Complete Types and Enums

This section merges the public audio_sdk_guide.pdf with the current public headers. When the PDF and headers differ, the current headers are authoritative. For example, AudioCaptureStreamOptions::requested_raw_format currently defaults to 16000/3/16 (16 kHz, three channels, 16 bit); the negotiated service format must still be read from AudioCaptureStreamInfo.

AudioSourceType:

Enumerator	Value	Meaning
kPcmFile	0	Read raw PCM from a robot-side file; provide the correct sample rate, channels, and width.
kWavFile	1	Play a WAV file at an absolute path accessible to the robot audio service.
kPcmStream	2	Feed PCM chunks with PushPcmStream; call Start first and never push empty data.
kMp3File	3	Play an MP3 file when the deployed audio service provides the codec.

State and priority enums:

Enum	Values	Meaning
PlayerState::kIdle / kReady / kPlaying	0 / 1 / 2	Not initialized, initialized and ready, or currently playing.
PlayerState::kPaused / kStopped / kCompleted / kError	3 / 4 / 5 / 6	Paused, stopped by the caller, reached end of source, or terminated by an error.
PlayerPriority::kLow / kMedium / kHigh	0 / 1 / 2	Low, normal, or high arbitration priority; high priority may preempt lower priority playback.
RecorderState::kIdle / kReady / kRecording	0 / 1 / 2	Not initialized, ready, or recording.
RecorderState::kPaused / kStopped / kError	3 / 4 / 5	Paused, stopped, or terminated by an error.
AudioCaptureStreamState::kIdle / kReady / kStreaming	0 / 1 / 2	Not initialized, negotiated and ready, or publishing frames.
AudioCaptureStreamState::kPaused / kStopped / kError	3 / 4 / 5	Paused, stopped, or terminated by an error.

Device and Bluetooth enums:

Enum	Values	Meaning
AudioDeviceQueryType::GET_DEVICES_INPUTS / GET_DEVICES_OUTPUTS	0 / 1	Enumerate input / output devices.
AudioDeviceDirection::INPUT / OUTPUT	0 / 1	Input / output endpoint direction.
AudioDeviceTransport::BUILTIN / USB / BLUETOOTH	0 / 1 / 2	Built-in, USB, or Bluetooth transport.
AudioDeviceTransport::VIRTUAL / UNKNOWN	3 / 4	Virtual endpoint or unknown transport.
AudioDeviceBackendAffinity::PULSE	0	PulseAudio-compatible backend.
AudioDeviceBackendAffinity::BOOSTERAEC_ARRAY	1	BoosterAEC microphone-array backend, commonly used for NAEC/localization.
AudioDeviceBackendAffinity::ALSA_DIAGNOSTIC	2	ALSA diagnostic endpoint.
BluetoothScanState::kIdle / kScanning	0 / 1	No scan is running / discovery is active.
BluetoothDeviceState::kUnknown / kPaired	0 / 1	Unknown state / paired but not connected.
BluetoothDeviceState::kConnecting / kConnected	2 / 3	Connecting / connected.
BluetoothDeviceState::kDisconnecting / kFailed	4 / 5	Disconnecting / most recent connection failed.
BluetoothMajorClass::kAudio / kPeripheral / kPhone	0 / 1 / 2	Audio/video device, peripheral, or phone class.
BluetoothMajorClass::kComputer / kOther	3 / 4	Computer class, or another/unknown class.
BluetoothAudioProfile::kNone	0	No preferred or active profile.
BluetoothAudioProfile::kA2dpSink / kA2dpSource	1 / 2	A2DP playback sink / audio source; headphones normally use the sink role.
BluetoothAudioProfile::kHfpHeadset / kHfpAg	3 / 4	HFP headset / audio-gateway role; select HFP explicitly for a headset microphone.

Public Topic enums ( include/booster/idl/audio/AudioCommon.h )

These enums classify public Topic sessions, events, and errors. Values start at zero in declaration order. They are distinct from AudioError.ret_code, which is the RPC/business error code (for example 7001).

SessionType:

Enumerator	Value	Description
PLAYER_SESSION	0	A player session; Topics describe playback state or progress.
RECORDER_SESSION	1	A recorder session; Topics describe recording state or progress.
LOCALIZER_SESSION	2	Session classification for direction-of-arrival requests or results.
CAPTURE_STREAM_SESSION	3	A raw/NAEC real-time capture stream session.

AudioErrorCode:

Enumerator	Value	Description
SERVICE_DEGRADED	0	The audio service is reachable but operating in a degraded state.
INVALID_STATE	1	The current session state does not allow the requested operation.
DEVICE_BUSY	2	The requested audio device is occupied by another operation.
NOT_SUPPORTED	3	The target hardware or backend does not support the capability.
LOCALIZATION_UNAVAILABLE	4	Direction-of-arrival localization is unavailable.
ALSA_DEVICE_NOT_FOUND	5	The requested ALSA device could not be found.
ALGO_INIT_FAILED	6	Audio algorithm initialization failed.
ALGO_PROCESS_FAILED	7	Audio algorithm processing failed.
SYSTEM_VOLUME_CTRL_FAILED	8	System-volume control failed.
SYSTEM_MUTE_CTRL_FAILED	9	System-mute control failed.
MEDIA_DECODE_FAILED	10	Media decoding failed.
MEDIA_ENCODE_FAILED	11	Media encoding failed.
MEDIA_FORMAT_UNSUPPORTED	12	The media format is unsupported.

AudioEventCode:

Enumerator	Value	Description
PLAYER_INIT_SUCCEEDED	0	Player initialization succeeded.
PLAYER_START_SUCCEEDED	1	Player start or resume succeeded.
PLAYER_PAUSE_SUCCEEDED	2	Player pause succeeded.
PLAYER_STOP_SUCCEEDED	3	Player stop succeeded.
PLAYER_RESET_SUCCEEDED	4	Player reset succeeded.
PLAYER_DESTROY_SUCCEEDED	5	Player session destruction succeeded.
RECORDER_INIT_SUCCEEDED	6	Recorder initialization succeeded.
RECORDER_START_SUCCEEDED	7	Recorder start or resume succeeded.
RECORDER_PAUSE_SUCCEEDED	8	Recorder pause succeeded.
RECORDER_STOP_SUCCEEDED	9	Recorder stop succeeded.
RECORDER_DESTROY_SUCCEEDED	10	Recorder session destruction succeeded.
PLAYER_TERMINAL_STATE_CHANGED	11	The player entered a terminal state such as completed or error.
SYSTEM_VOLUME_SET_SUCCEEDED	12	System-volume update succeeded.
SYSTEM_MUTE_SET_SUCCEEDED	13	System-mute update succeeded.
CAPTURE_STREAM_INIT_SUCCEEDED	14	Capture-stream initialization and format negotiation succeeded.
CAPTURE_STREAM_START_SUCCEEDED	15	Capture-stream publishing started successfully.
CAPTURE_STREAM_PAUSE_SUCCEEDED	16	Capture-stream pause succeeded.
CAPTURE_STREAM_STOP_SUCCEEDED	17	Capture-stream stop succeeded.
CAPTURE_STREAM_DESTROY_SUCCEEDED	18	Capture-stream session destruction succeeded.

AudioErrorCategory:

Enumerator	Value	Description
RPC_ERROR	0	RPC transport or common request error.
PLAYBACK_ERROR	1	Playback business error.
RECORD_ERROR	2	Recording business error.
CAPTURE_STREAM_RUNTIME_ERROR	3	Capture-stream runtime error.
LOCALIZATION_ERROR	4	Direction-of-arrival localization error.
SYSTEM_VOLUME_ERROR	5	System-volume control error.
SYSTEM_MUTE_ERROR	6	System-mute control error.
INTERNAL_ERROR	7	Internal service error; applications should still record ret_msg.

AudioErrorDetail:

Enumerator	Value	Description
ERROR_DETAIL_NONE	0	No more specific operation is identified.
ERROR_DETAIL_INIT_PLAYER	1	Player initialization operation.
ERROR_DETAIL_START_PLAYER	2	Player start operation.
ERROR_DETAIL_PAUSE_PLAYER	3	Player pause operation.
ERROR_DETAIL_STOP_PLAYER	4	Player stop operation.
ERROR_DETAIL_RESET_PLAYER	5	Player reset operation.
ERROR_DETAIL_DESTROY_PLAYER	6	Player destruction operation.
ERROR_DETAIL_GET_PLAYER_INFO	7	Player-information query.
ERROR_DETAIL_SEND_PCM_DATA	8	PCM stream data submission.
ERROR_DETAIL_INIT_RECORDER	9	Recorder initialization operation.
ERROR_DETAIL_START_RECORDER	10	Recorder start operation.
ERROR_DETAIL_PAUSE_RECORDER	11	Recorder pause operation.
ERROR_DETAIL_STOP_RECORDER	12	Recorder stop operation.
ERROR_DETAIL_DESTROY_RECORDER	13	Recorder destruction operation.
ERROR_DETAIL_GET_RECORDER_INFO	14	Recorder-information query.
ERROR_DETAIL_GET_DOA_ANGLE	15	Direction-of-arrival query.
ERROR_DETAIL_SET_SYSTEM_VOLUME	16	System-volume update operation.
ERROR_DETAIL_GET_SYSTEM_VOLUME	17	System-volume query.
ERROR_DETAIL_SET_SYSTEM_MUTE	18	System-mute update operation.
ERROR_DETAIL_GET_SYSTEM_MUTE	19	System-mute query.
ERROR_DETAIL_INIT_CAPTURE_STREAM	20	Capture-stream initialization operation.
ERROR_DETAIL_START_CAPTURE_STREAM	21	Capture-stream start operation.
ERROR_DETAIL_PAUSE_CAPTURE_STREAM	22	Capture-stream pause operation.
ERROR_DETAIL_STOP_CAPTURE_STREAM	23	Capture-stream stop operation.
ERROR_DETAIL_DESTROY_CAPTURE_STREAM	24	Capture-stream destruction operation.
ERROR_DETAIL_GET_CAPTURE_STREAM_INFO	25	Capture-stream information query.

Public structure fields

• PcmFormat contains sample_rate_hz (default 16000), channels (default 1), and bits_per_sample (default 16).
• PlayerInitOptions contains source_type, source_uri, sample rate, channels, width, and priority. File paths must be accessible to the robot audio service; a PCM stream may leave the URI empty.
• RecorderInitOptions contains output_path, sample rate, channels, and width. The path must be an absolute, writable robot-side path and numeric values must be positive.
• AudioCaptureStreamOptions contains enable_raw_pcm (default true), enable_naec_pcm (default false), and requested_raw_format. At least one stream must be enabled; raw requests currently accept only 16-bit samples and NAEC depends on BoosterAEC/hardware support.
• PlayerInfo contains state, played_bytes, total_bytes, and volume; RecorderInfo contains state and captured_bytes.
• AudioCaptureFrame contains frame_seq, timestamp_ms, and for raw/NAEC each *_valid flag, actual format, samples per channel, and an int16 *_pcm array.
• AudioCaptureStreamInfo contains state, raw/NAEC enable flags, negotiated formats, published_frames, and dropped_frames.
• AudioDeviceInfo contains device ID, display name, direction, transport, backend affinity, availability/default flags, input/output capabilities, provider/native IDs, and metadata_json.
• AudioError contains ret_code, ret_msg, error_category, and error_detail.
• BluetoothDeviceInfo contains address, name, RSSI, state, major class, paired/trusted/ connected flags, sink/source/HFP capabilities, connected profiles, Pulse sink/source IDs, and the last-seen timestamp.
• BluetoothScanOptions contains timeout_ms (default 30000, never negative) and audio_only.
• BluetoothConnectOptions contains required address, auto_pair, make_default, preferred_profile, and timeout_ms (strictly positive). The connection RPC timeout is max(5000, timeout_ms).
• BluetoothConnectResult contains the connected device, Pulse sink/source IDs, active profile, endpoint readiness, default-route flags, and default-route error code/message.

Lifecycle, callbacks, and routing

Audio objects follow manager.Init -> object.Init -> Start/Pause/Stop -> Destroy. Release exists only on player and recorder and is equivalent to Destroy; capture streams have no Release. GetCachedState reads local cache and does not make an RPC; call GetInfo for a service-side snapshot. Running recorder/capture sessions currently cannot migrate input devices, so stop and reinitialize them.

SetPreferredDevice selects the current session’s preferred endpoint; it does not change the system default. Players use IDs from GetDevices(GET_DEVICES_OUTPUTS); recorders and capture streams use input IDs. Global topics can contain messages for multiple objects in one process; filter by client_id, request_id, session_type, session_id, and timestamp_ms.

Bluetooth headphones are normally connected with A2DP for playback. To use a headset microphone, disconnect and reconnect with BluetoothAudioProfile::kHfpHeadset. Automatic reconnect normally remains A2DP and does not switch to HFP. Inspect default_* fields in BluetoothConnectResult when make_default is enabled.

Error codes

In addition to common RPC statuses (-1 invalid, 0 success, 100 timeout, 400 bad request, 409 conflict, 429 too frequent, 500 internal, 501 refused, and 502 state transition failed), common audio-service codes are: 2001 service degraded, 4001 Bluetooth unavailable, 4002 busy, 4003 unknown device, 4004 pairing failed, 4005 connection failed, 4006 timeout, 4007 not an audio device, 4008 profile unsupported, 4009 authentication rejected, 5001 device busy, 7001 kAudioErrNotSupported, 7002 localization unavailable, 7003 ALSA not found, 7004/7005 algorithm initialization/processing failed, 7006 system-volume failure, 7007 mute failure, 7008 decode failure, 7009 encode failure, and 7010 format unsupported. Also record AudioError.ret_msg.

PDF guide and Python

Complete audio guide: download audio_sdk_guide.pdf. The PDF’s C++ lifecycle, WAV/PCM streaming, recording, raw/NAEC capture, device, and Bluetooth examples are merged into this page. Python bindings use PascalCase names such as GetDevices, SetPreferredDevice, and ConnectBluetoothDevice; high-level failures are commonly wrapped as RuntimeError. Interactive examples include player_init, player_stream_init, rec_init, devices inputs|outputs, bt_scan, bt_connect, cap_init, and cap_destroy.

Detailed Public Interfaces

The following tables enumerate the methods in the current public headers. Check every int32_t return value: 0 means that local validation and the RPC succeeded; a nonzero value reports a transport, service, or argument error.

AudioManager methods

Interface	Description
AudioManager() / ~AudioManager()	Construct an uninitialized manager; destruction removes listeners and releases RPC resources.
Init()	Initialize the DDS audio runtime and register a client_id with the service.
Shutdown()	Stop global topic subscribers and release manager resources; call it after child sessions are destroyed.
IsInitialized()	Return whether manager initialization completed; no RPC is made.
GetClientId()	Return the service-registered client ID used to filter global callback messages.
GenerateRequestId()	Generate a client-unique request ID for diagnostics and topic correlation.
CreatePlayer() / CreateRecorder() / CreateLocalizer() / CreateCaptureStream()	Create the corresponding child object. Player, recorder, and capture objects still need Init; localizer has no independent session.
SetSystemVolume(volume) / GetSystemVolume(volume)	Set or query the global output volume. The output overload writes through its pointer.
SetSystemMute(mute) / GetSystemMute(mute)	Set or query the global mute switch; this is not a player-session volume.
GetDevices(query_type, devices)	Enumerate input or output endpoints using GET_DEVICES_INPUTS or GET_DEVICES_OUTPUTS.
StartBluetoothScan(options) / StopBluetoothScan()	Start or stop discovery; timeout and audio_only come from BluetoothScanOptions.
GetBluetoothDevices(include_unpaired, devices)	Return known Bluetooth devices, optionally including unpaired devices.
ConnectBluetoothDevice(options, result)	Pair/connect by address, optionally selecting A2DP/HFP and applying a default route.
DisconnectBluetoothDevice(address)	Disconnect an endpoint without removing pairing information.
ForgetBluetoothDevice(address)	Remove pairing/trust information so that the device must be paired again.
SetProgressCallback(callback) / SetEventCallback(callback)	Register global progress or event topic callbacks; messages can belong to multiple sessions.
SetErrorCallback(callback) / SetBluetoothEventCallback(callback)	Register global audio-error or Bluetooth-event callbacks.

AudioPlayer methods

Interface	Description
Init(options)	Create the service playback session; file sources need robot-side absolute paths, while streaming uses kPcmStream.
Start() / Pause() / Stop()	Start or resume, pause, or stop playback. Streaming must start before data is pushed.
Reset()	Reset a stopped or completed player for reuse without allocating another session ID.
Destroy() / Release()	Release the service session; Release is the compatibility alias.
SetVolume(volume)	Set this playback session’s volume without changing the system volume.
SetPreferredDevice(device_id)	Select the output endpoint for this session; use an output ID from GetDevices.
GetInfo(PlayerInfo *out)	Query a service-side snapshot of state, byte progress, and session volume.
PushPcmStream(data, size)	Push nonempty PCM bytes to a kPcmStream session after Init and Start.
GetSessionId() / GetCachedState()	Return the service session ID or read local state without making an RPC.
SetStateCallback(callback) / SetProgressCallback(callback)	Receive PlayerState changes or PlayerInfo progress snapshots.
SetCompletionCallback(callback)	Invoke once when the session first reaches kCompleted.
SetErrorCallback(callback)	Receive an AudioError for this session and update its cached state to kError.

AudioRecorder methods

Interface	Description
Init(options)	Create a recording session; output_path must be an absolute writable robot-side path and all format values must be positive.
Start() / Pause() / Stop()	Start or resume, pause, or stop recording; stop explicitly to finalize the output file.
Destroy() / Release()	Release the recording session; Release is the compatibility alias.
GetInfo(RecorderInfo *out)	Query recording state and captured byte count; bytes can estimate duration.
SetPreferredDevice(device_id)	Select the input endpoint for this session; use an ID from GET_DEVICES_INPUTS.
GetSessionId() / GetCachedState()	Return the service session ID or read local state without making an RPC.
SetStateCallback(callback) / SetProgressCallback(callback)	Receive RecorderState changes or RecorderInfo progress snapshots.
SetErrorCallback(callback)	Receive recording errors and update the cached state.

AudioLocalizer methods

Interface	Description
GetDoaAngle(int *angle_deg)	Query direction of arrival in degrees; a BoosterAEC/microphone-array backend is required, otherwise 7002 or kAudioErrNotSupported may be returned.

AudioCaptureStream methods

Interface	Description
Init(options)	Negotiate raw/NAEC streams and create a dedicated DDS data subscriber; at least one stream is required and raw requests currently accept only 16-bit samples.
Start() / Pause() / Stop()	Start, pause, or stop frame delivery while retaining the session.
Destroy()	Close the data subscriber and release the service capture session; this class has no Release method.
GetInfo(AudioCaptureStreamInfo *out)	Query negotiated formats, enable flags, and published/dropped frame counters.
SetPreferredDevice(device_id)	Select the input endpoint; live migration is normally unsupported.
GetSessionId() / GetCachedState()	Return the service session ID or read local state without making an RPC.
SetFrameCallback(callback)	Receive each captured frame; process or hand off data quickly.
SetStateCallback(callback) / SetErrorCallback(callback)	Receive state changes or AudioError values; unsupported NAEC commonly reports 7001.

Callback topic fields

Global callback arguments come from booster_msgs::audio. Python bindings expose the same callback message classes using PascalCase names:

Type or field	Description
AudioTopicHeader::client_id / request_id	The manager client ID and request ID; use them to filter and correlate messages.
AudioTopicHeader::session_type / session_id	Session category (player, recorder, capture, and so on) and service session ID.
AudioTopicHeader::timestamp_ms	Millisecond timestamp generated by the service.
AudioProgressTopic::position_bytes / duration_bytes	Current position and total bytes; streaming sources may report zero/unknown duration.
AudioProgressTopic::state	Service state integer converted by the SDK to the object state.
AudioEventTopic::event_code / state / detail	Event value, state at event time, and backend diagnostic detail.
AudioErrorTopic::ret_code / ret_msg	Error status and human-readable message.
AudioErrorTopic::error_category / error_detail	Error classification and detail values for RPC, device, format, and other sources.
BluetoothEventTopic::timestamp_ms / event_type / address	Event time, event name, and associated Bluetooth address.
BluetoothEventTopic::payload_json / error_code	Version-dependent event JSON and the operation error code (normally zero on success).

Python mapping

src/python/binding.cpp exposes PascalCase names such as Init, Shutdown, CreatePlayer, CreateRecorder, CreateLocalizer, CreateCaptureStream, GetDevices, SetPreferredDevice, and ConnectBluetoothDevice. Output-pointer arguments become returned objects (for example, GetInfo() returns PlayerInfo), and nonzero statuses are usually raised as RuntimeError. PushPcmStream accepts bytes; capture and global callbacks receive the corresponding bound message objects.