语音控制服务

约 5110 字大约 17 分钟

2025-05-29

提供机器人系统语音服务控制器，通过 AudioController 可以使用 RPC 方式实现对机器人音频的指令控制和状态获取。

接口定义

AudioController 是一个封装音频控制功能的 C++ 类，主要用于音频播放控制、TTS 播放、音量设置、查询，订阅语音原始数据等场景。

AudioController

项目	内容
函数名	AudioController
函数声明	`AudioController();`
功能概述	初始化音频控制器对象，构造内部状态，分配资源等。
备注	构造内部状态。

~AudioController

项目	内容
函数名	~AudioController
函数声明	`~AudioController();`
功能概述	释放音频控制器资源，确保停止播放并清理底层资源。
备注	确保资源安全释放。

Initialize

项目	内容
函数名	Initialize
函数声明	`bool Initialize();`
功能概述	初始化音频控制模块，准备播放资源与设备。
返回值	`true` 表示成功，`false` 表示失败。
备注	与 `Shutdown()` 配对使用。

Shutdown

项目	内容
函数名	Shutdown
函数声明	`void Shutdown();`
功能概述	关闭音频控制器并释放资源。
备注	确保在销毁前调用。

GetVoiceConfig

项目	内容
函数名	GetVoiceConfig
函数声明	`Status GetVoiceConfig(GetSpeechConfig& config);`
功能概述	获取语音系统的完整配置信息。
参数说明	`config`：通过引用返回语音系统配置信息。
返回值	`Status::OK` 表示成功，其他为失败状态。
备注	阻塞接口，获取的配置包含音色、智能体、唤醒、对话等所有子配置，以及当前使用的语音模型类型。

SwitchTtsVoiceModel

项目	内容
函数名	SwitchTtsVoiceModel
函数声明	`Status SwitchTtsVoiceModel(TtsType tts_type, GetSpeechConfig& config);`
功能概述	切换语音模型并获取更新后的配置信息。
参数说明	`tts_type`：要切换的语音模型类型 `config`：通过引用返回切换后的语音系统配置信息
返回值	`Status::OK` 表示成功，其他为失败状态。
备注	阻塞接口，切换语音模型后会自动更新配置信息。

SetVoiceConfig

项目	内容
函数名	SetVoiceConfig
函数声明	`Status SetVoiceConfig(const SetSpeechConfig& config);`
功能概述	设置语音系统的完整配置信息。
参数说明	`config`：要设置的语音系统配置信息。
返回值	`Status::OK` 表示成功，其他为失败状态。
备注	阻塞接口，设置的配置将完全覆盖当前所有语音相关配置。

Play

项目	内容
函数名	Play
函数声明	`Status Play(const TtsCommand& cmd);`
功能概述	播放 TTS（文本转语音）语音命令。
参数说明	`cmd`：TTS 命令，包含文本、语速、语调等。
返回值	`Status::OK` 表示成功，其他为失败状态。
备注	阻塞接口，调用前需确保已初始化模块。

Stop

项目	内容
函数名	Stop
函数声明	`Status Stop();`
功能概述	停止当前音频播放。
返回值	`Status::OK` 表示成功，其他为失败状态。
备注	阻塞接口，通常用于中断当前语音。

SetVolume

项目	内容
函数名	SetVolume
函数声明	`Status SetVolume(int volume);`
功能概述	设置音频输出的音量。
参数说明	`volume`：音量值，通常范围为 0~100。
返回值	`Status::OK` 表示成功，其他为失败状态。
备注	阻塞接口，设置后立即生效。

GetVolume

项目	内容
函数名	GetVolume
函数声明	`Status GetVolume(int& volume);`
功能概述	获取当前音频输出音量。
参数说明	`volume`：通过引用返回当前音量值。
返回值	`Status::OK` 表示成功，其他为失败状态。
备注	阻塞接口，返回值需检查后再使用 `volume`。

ControlVoiceStream

项目	内容
函数名	ControlVoiceStream
函数声明	`Status ControlVoiceStream(bool raw_data, bool bf_data);`
功能概述	控制语音数据流
参数说明	`raw_data`：是否发送原始数据 `bf_data`：是否发送 bf 数据
返回值	`Status::OK` 表示成功，其他为失败。
备注	阻塞接口，用于控制语音数据流的开启和关闭。

SubscribeOriginVoiceData

项目	内容
函数名	SubscribeOriginVoiceData
函数声明	`void SubscribeOriginVoiceData(const RawVoiceDataCallback callback);`
功能概述	订阅原始语音数据
参数说明	callback：接收到原始语音数据后的处理回调
备注	非阻塞接口，回调函数会在数据更新时被调用。

SubscribeBfVoiceData

项目	内容
函数名	SubscribeBfVoiceData
函数声明	`void SubscribeBfVoiceData(const BfVoiceDataCallback callback);`
功能概述	订阅 BF 语音数据
参数说明	callback：接收到 BF 语音数据后的处理回调
备注	非阻塞接口，回调函数会在数据更新时被调用。

类型定义

`TtsPriority` — TTS 播报优先级等级

用于控制不同 TTS 任务之间的中断行为。优先级越高的任务将中断当前低优先级任务的播放。

枚举值	数值	描述
`TtsPriority::HIGH`	0	最高优先级，例如：低电告警、紧急提醒
`TtsPriority::MIDDLE`	1	中优先级，例如：系统提示、状态播报
`TtsPriority::LOW`	2	最低优先级，例如：日常语音对话、背景播报

`TtsMode` — 同一优先级下的任务调度策略

用于细化控制在相同优先级条件下多个 TTS 任务的播放顺序和清除逻辑。

枚举值	数值	描述
`TtsMode::CLEARTOP`	0	清空当前优先级所有任务（包括正在播放和等待队列），立即播放本次请求
`TtsMode::ADD`	1	将本次请求追加到当前优先级队列尾部，顺序播放（不打断当前播放）
`TtsMode::CLEARBUFFER`	2	清空队列中未播放的请求，保留当前播放，之后播放本次请求

结构体定义

`TtsCommand` — TTS 播放命令结构体

描述一次 TTS 播放请求的完整信息，支持设置唯一标识、文本内容、优先级控制以及同优先级下的调度模式。

字段名	类型	描述
`id`	`std::string`	TTS 任务唯一 ID，例如 `"id_01"`，用于追踪播放状态
`content`	`std::string`	要播放的文本内容，例如 `"你好，欢迎使用智能语音系统。"`
`priority`	`TtsPriority`	播报优先级，控制是否中断正在播放的低优先级语音
`mode`	`TtsMode`	同优先级下的调度策略，控制任务是否追加、覆盖等

`CustomBotInfo` — 自定义智能体配置结构体

描述一个自定义智能体的基本配置信息。

字段名	类型	描述
`name`	`std::string`	智能体名称
`workflow`	`std::string`	工作流 ID
`token`	`std::string`	用户授权 token

`CustomBotMap` — 自定义智能体映射表

项目	内容
类型	`std::map<std::string, CustomBotInfo>`
描述	自定义智能体映射表，键为智能体 ID，值为智能体配置信息

`SetSpeechConfig` — 语音配置参数结构体

用于设置语音系统的各项配置参数。

字段名	类型	描述
`speaker_id`	`std::string`	音色 ID
`region`	`std::string`	音色地区
`bot_id`	`std::string`	模式 ID
`is_front_doa`	`bool`	是否强制正前方识别
`is_fullduplex_enable`	`bool`	自然对话开关
`is_enable`	`bool`	语音开关
`is_doa_enable`	`bool`	是否打开唤醒方位转头
`speaker_speed`	`float`	TTS 播放语速，范围 [1,2]
`wakeup_name`	`std::string`	唤醒名字
`custom_bot`	`CustomBotMap`	自定义智能体配置

`SpeakerConfigSelected` — 音色选中配置结构体

当前音色配置

字段名	类型	描述
`region`	`std::string`	选中的地区
`speaker_id`	`std::string`	选中的音色 ID

`SpeakerConfig` — 音色配置结构体

音色配置

字段名	类型	描述
`data`	`std::map<std::string, std::vector<std::array<std::string, 2>>>`	音色数据：地区->音色 ID->音色名称
`selected`	`SpeakerConfigSelected`	当前选中的音色配置
`speaker_speed`	`float`	语速

`BotInfo` — 智能体配置信息结构体

描述一个标准智能体的基本信息。

字段名	类型	描述
`name`	`std::string`	工作场景名称
`workflow`	`std::string`	工作流 ID

`BotConfigSelected` — 智能体选中项结构体

字段名	类型	描述
`bot_id`	`std::string`	选中的智能体 ID

`BotConfig` — 智能体配置结构体

描述智能体相关的配置信息，包括标准智能体和自定义智能体。

字段名	类型	描述
`data`	`std::map<std::string, BotInfo>`	标准智能体数据：智能体 ID->智能体信息
`custom_data`	`std::map<std::string, CustomBotInfo>`	自定义智能体数据：智能体 ID->自定义智能体信息
`selected`	`BotConfigSelected`	当前选中的智能体配置

`WakeupConfig` — 唤醒配置结构体

描述唤醒相关的配置信息。

字段名	类型	描述
`name`	`std::string`	唤醒名称
`data`	`std::map<std::string, std::string>`	唤醒词数据：唤醒词->拼音

`DialogConfig` — 对话配置结构体

描述对话相关的配置参数。

字段名	类型	描述
`is_front_doa`	`bool`	是否强制正前方加强拾音
`is_fullduplex_enable`	`bool`	是否打开全双工对话
`is_enable`	`bool`	是否打开语音
`is_doa_enable`	`bool`	是否打开唤醒方位转头

`TtsType` — 语音模型枚举

描述可选的语音合成模型类型。

枚举值	数值	描述
`TtsType::NONE`	0	无语音模型
`TtsType::DOUBAO`	1	豆包语音模型
`TtsType::GOOGLE`	2	谷歌语音模型

`GetSpeechConfig` — 语音系统完整配置结构体

描述语音系统的完整配置信息，包含所有子配置模块。

字段名	类型	描述
`speaker_config`	`SpeakerConfig`	音色配置
`bot_config`	`BotConfig`	智能体配置
`wakeup_config`	`WakeupConfig`	唤醒配置
`dialog_config`	`DialogConfig`	对话配置
`tts_type`	`TtsType`	语音模型，默认值为 `TtsType::NONE`

`MultiArrayDimension` — 多维数组维度描述

字段名	类型	描述
`label`	`std::string`	维度标签
`size`	`int32_t`	维度大小
`stride`	`int32_t`	步长

`MultiArrayLayout` — 多维数组布局描述

字段名	类型	描述
`dim_size`	`int32_t`	维度数量
`dim`	`std::vector<MultiArrayDimension>`	维度数组
`data_offset`	`int32_t`	数据偏移量

`ByteMultiArray` — 字节数组数据结构

字段名	类型	描述
`layout`	`MultiArrayLayout`	数组布局信息
`data`	`std::vector<uint8_t>`	字节数据数组