☰

AIMA开放平台文档中心AimDK A3-ultra

7.2 TTS/音频播放部分

7.2 TTS/音频播放部分

7.2.1 整体介绍

A3-Ultra 机器人配有扬声器，在有网络的情况下可以进行 TTS 播报，无网络时可以进行基本的音频文件播放和音量调节，同时可以支持播放状态查询以及打断等控制逻辑。

7.2.2 TTS 播报 RPC 接口

接口名	`pb:/aimdk.protocol.TTSService/PlayTTS`
功能概述	TTS 播报接口，依赖联网
接口类型	HTTP JSON RPC
URL	http://10.42.10.10:59301/rpc/aimdk.protocol.TTSService/PlayTTS
入参	text `{ "text": "你好", "priority_level": "INTERACTION_L6", "domain": "example", "trace_id": "hafhjkqwjwefk", "is_interrupted": true }` text: 播报文本内容 priority_level: 优先级，保持 INTERACTION_L6 即可 domain: 调用方来源标识，可以传入自定义的客户端字符串，方便问题排查等 trace_id: 播报 id，如果需要获取播报状态，则需要传入该字段，并将其值作为查询播报状态的参数
出参	text `{ "text": "你好", "priority_level": "INTERACTION_L6", "priority_weight": 0, "domain": "example", "trace_id": "hafhjkqwjwefk_18bZZLTk5VfJGSy8Cylsu4", "is_sucess": true, "error_message": "", "estimated_duration": 0 }` text: 播报文本内容 priority_level: 优先级等级，无需关注 priority_weight: 优先级权重，无需关注 domain: 调用方来源标识，返回请求中传入的自定义字符串，方便问题排查 trace_id: 播报 id，返回请求中传入的自定义字符串 + 一段随机字符串，用于播报状态查询等 is_success: 优先级校验是否成功，一般均为 true，不代表会播放，例如传入错误或不存在的文件名仍会返回 true，只有当前有更高优先级的内容播报时才会返回 true，例如当前有故障报警播报时 error_message: 错误信息 estimated_duration: 无效字段，无需关注，无法估算播放时长
示例脚本	examples/agent/tts_broadcast.sh
备注	只支持短文本请求，最高只 1024 字节，约 200 个中文/英文

7.2.3 音频文件播放 RPC 接口

接口名	`pb:/aimdk.protocol.TTSService/PlayMediaFile`
功能概述	音频文件播放
接口类型	HTTP JSON RPC
URL	http://10.42.10.10:59301/rpc/aimdk.protocol.TTSService/PlayMediaFile
入参	text `{ "file_name": "wake.pcm", "priority_level": "INTERACTION_L6", "domain": "example", "trace_id": "hafhjkqwjwefk", "is_interrupted": true }` file_name: 文件名（支持传入相对路径或绝对路径，若使用相对路径，默认从 HDU `/agibot/data/var/interaction/audio/`读取，例如可传入 `wake.pcm`；若使用绝对路径，例如可传入 `/agibot/data/home/agi/Desktop/wake.pcm`，按指定路径读取；文件要求为 16kHz 16 位单声道的 pcm 文件） priority_level: 优先级，保持 INTERACTION_L6 即可 domain: 调用方来源标识，可以传入自定义的客户端字符串，方便问题排查等 trace_id: 播报 id，如果需要获取播报状态，则需要传入该字段，并将其值作为查询播报状态的参数
出参	text `{ "text": "wake.pcm", "priority_level": "INTERACTION_L6", "priority_weight": 0, "domain": "example", "trace_id": "hafhjkqwjwefk", "is_sucess": true, "error_message": "", "estimated_duration": 0 }` text: 文件名 priority_level: 优先级等级，无需关注 priority_weight: 优先级权重，无需关注 domain: 调用方来源标识，返回请求中传入的自定义字符串，方便问题排查 trace_id: 播报 id，返回请求中传入的自定义字符串，用于请求播报状态或打断 is_success: 优先级校验是否成功，一般均为 true，不代表会播放，例如传入错误或不存在的文件名仍会返回 true，只有当前有更高优先级的内容播报时才会返回 true，例如当前有故障报警播报时 error_message: 错误信息 estimated_duration: 无效字段，无需关注，无法估算播放时长
示例脚本	examples/agent/play_media_file.sh
备注	同时支持标准 44 字节头部 Linear PCM 的 wav 文件，其余头部格式以及压缩格式等均不支持，推荐使用 16kHz 16 位单声道的 pcm 文件如果传入错误或不存在的文件名，会静默失败，不会进行播放，同时 is_success 返回 true

7.2.4 TTS/音频文件播放状态查询 RPC 接口

接口名	`pb:/aimdk.protocol.TTSService/GetAudioStatus`
功能概述	TTS/音频文件播放状态查询
接口类型	HTTP JSON RPC
URL	http://10.42.10.10:59301/rpc/aimdk.protocol.TTSService/GetAudioStatus
入参	text `{ "trace_id": "hafhjkqwjwefk" }` trace_id: 播报 id，填写调用 PlayTTS 或 PlayMediaFile 接口时使用的 id
出参	text `{ "tts_status": { "text": "", "priority": 0, "trace_id": "", "tts_status": "TTSStatusType_Playing", "domain": "", "error_message": "" } }` tts_status: 播报状态，枚举值 TTSStatusType_Unknown: 未知状态 TTSStatusType_Begin: 开始播报，短暂，一般查询不到这个状态 TTSStatusType_Playing: 播报中 TTSStatusType_End: 播报结束，短暂，一般查询不到这个状态 TTSStatusType_Stop: 暂停播报/取消播报/中断播报 TTSStatusType_Error: 播报失败 TTSStatusType_InQue: 在播报队列中，尚未开始播报 TTSStatusType_NOTInQue: 播报队列无此文本，也不在播报，播报结束后会进入此状态其余字段均为无效字段，无需关注
示例脚本	examples/agent/tts_status_rpc.sh
备注	成功的播报通过该 RPC 接口查询一般会返回 InQue、Playing 和 NOTInQue 状态

7.2.5 TTS/音频文件播放状态 Topic 接口

接口名	/interaction/tts_status
功能概述	TTS/音频文件播放状态
接口类型	ROS2 Topic
出参	text `{ "text": "你好", "priority": 600, "trace_id": "hafhjkqwjwefk_5WC7uy69bqCuO101aalJ1T", "tts_status": "TTSStatusType_End", "domain": "example", "header": { "seq": 110 } }` text: 文件名 trace_id：播报 id domain：调用方来源 tts_status: 播报状态，枚举值 TTSStatusType_Unknown: 未知状态 TTSStatusType_Begin: 开始播报，短暂，一般查询不到这个状态 TTSStatusType_Playing: 播报中 TTSStatusType_End: 播报结束，短暂，一般查询不到这个状态 TTSStatusType_Stop: 暂停播报/取消播报/中断播报 TTSStatusType_Error: 播报失败 TTSStatusType_InQue: 在播报队列中，尚未开始播报 TTSStatusType_NOTInQue: 播报队列无此文本，也不在播报，播报结束后会进入此状态其余字段均为无效字段，无需关注
示例脚本	examples/agent/tts_status_topic.py
备注	该消息的 ROS2 类型为 ros2_plugin_proto/msg/RosMsgWrapper，需要 source prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash 后使用。该接口需要将交互运行模式设置为 normal 模式才会发布，only_voice 模式下无消息

7.2.6 TTS/音频文件播放打断 RPC 接口

接口名	`pb:/aimdk.protocol.TTSService/StopTTSTraceId`
功能概述	打断单个文件/TTS 播放
接口类型	HTTP JSON RPC
URL	http://10.42.10.10:59301/rpc/aimdk.protocol.TTSService/StopTTSTraceId
入参	text `{ "trace_id": "hafhjkqwjwefk" }` trace_id: 播报 id，填写调用 PlayTTS 或 PlayMediaFile 接口时使用的 id
出参	text `{ "state":"CommonState_UNKNOWN" }` state: 调用请求状态，无需关注具体值，HTTP 请求返回 200 即代表成功
示例脚本	examples/agent/stop_tts.sh
备注

7.2.7 音量获取、设置 RPC 接口

接口名	`pb:/aimdk.protocol.HalAudioService/GetAudioVolume`
功能概述	获取当前音量大小
接口类型	HTTP JSON RPC
URL	http://10.42.10.10:56666/rpc/aimdk.protocol.HalAudioService/GetAudioVolume
入参	text `{}`
出参	text `{ "header": { "code": "0", "msg": "GetAudioVolume successfully", "trace_id": "", "domin": "" }, "audio_volume": 30, "is_mute": false, "type": "SPEAKRE_BUILT_IN" }` audio_volume: 音量大小，0-100 的数值 is_mute: 是否静音 type: 扬声器类型 SPEAKRE_BUILT_IN 内置扬声器 SPEAKER_BLUETOOTH 蓝牙扬声器
示例脚本	examples/hal_audio/GetAudioVolume.sh
备注

接口名	`pb:/aimdk.protocol.HalAudioService/SetAudioVolume`
功能概述	调节音量
接口类型	HTTP JSON RPC
URL	http://10.42.10.10:56666/rpc/aimdk.protocol.HalAudioService/SetAudioVolume
入参	text `{ "audio_volume": 70, "is_mute": false, "type": "SPEAKER_BUILT_IN" }` audio_volume: 音量大小，0-100 的数值，注意不要调节音量超过 70，音量超出此范围扬声器经功放放大后会超额定工作，造成扬声器损坏 is_mute: 是否静音 type: 扬声器类型
出参	text `{ "header": { "code": "0", "msg": "SetAudioVolume successfully", "trace_id": "", "domin": "" }, "pkg_name": "", "is_success": false }` pkg_name: 无效字段，无需关注 is_success: 无效字段，无需关注
示例脚本	examples/hal_audio/SetAudioVolume.sh
备注	如需静音，请将 audio_volume 字段设为 0，is_mute 设为 true。

7.2.8 申请音频焦点

接口名	`/audio_5Fmsgs/srv/RequestAudioFocus`
功能概述	申请音频焦点
接口类型	services
入参	text `{ focus_requester: { pkg_name: audio_examples_sender, priority: 6, priority_weight: 1} }` pkg_name：ROS包名 priority：优先级（音频播放只使用6） priority_weight：音频权重
示例脚本	examples/agent/RequestAudioFocus.sh
备注	使用前需加载ros环境 source prebuilt/audio_msgs_proto_aarch64/share/audio_msgs/local_setup.bash

7.2.9 释放音频焦点

接口名	`/audio_5Fmsgs/srv/AbandonAudioFocus`
功能概述	释放音频焦点
接口类型	services
入参	text `{ focus_requester: { pkg_name: audio_examples_sender, priority: 6, priority_weight: 1} }` pkg_name：ROS包名 priority：优先级（音频播放只使用6） priority_weight：音频权重
示例脚本	examples/agent/AbandonAudioFocus.sh
备注	使用前需加载ros环境 source prebuilt/audio_msgs_proto_aarch64/share/audio_msgs/local_setup.bash

7.2.10 播放流式音频

接口名	`/audiohal/audio/playback`
功能概述	播放流式音频
接口类型	topic
入参	text `{ stamps: <当前时间> focus_requester: pkg_name: audio_examples_sender priority: 6 priority_weight: 1 info: channels: 1 sample_rate: 16000 sample_format: S16LE coding_format: pcm data: audio_bytes: \x00\x01\x02\x03\x04\x05\x06\x07 # uint8数组（PCM数据）` `pkg_name: audio_examples_sender token_id: token-0001 }` stamp：时间戳 pkg_name：ROS包名 priority：优先级（音频播放只使用6） priority_weight：音频权重 channels：声道数 sample_rate：采样频率 sample_format：采样格式 coding_format：数据格式 audio_bytes：数据流 token_id：可不填默认即可
示例脚本	examples/agent/audio_examples_sender
备注	使用前需加载ros环境 source prebuilt/audio_msgs_proto_aarch64/share/audio_msgs/local_setup.bash