跳转到内容
开放平台文档中心
立即登录

7.2 TTS/音频播放部分

7.2 TTS/音频播放部分

Section titled “7.2 TTS/音频播放部分”

7.2.1 整体介绍

Section titled “7.2.1 整体介绍”

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

7.2.2 TTS 播报 RPC 接口

Section titled “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": "你好",
  "priority_level": "INTERACTION_L6",
  "domain": "example",
  "trace_id": "hafhjkqwjwefk",
  "is_interrupted": true
}
  • text: 播报文本内容
  • priority_level: 优先级，保持 INTERACTION_L6 即可
  • domain: 调用方来源标识，可以传入自定义的客户端字符串，方便问题排查等
  • trace_id: 播报 id，如果需要获取播报状态，则需要传入该字段，并将其值作为查询播报状态的参数
出参 
{
  "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 接口

Section titled “7.2.3 音频文件播放 RPC 接口”
接口名 pb:/aimdk.protocol.TTSService/PlayMediaFile
功能概述 音频文件播放
接口类型 HTTP JSON RPC
URL http://10.42.10.10:59301/rpc/aimdk.protocol.TTSService/PlayMediaFile
入参 
{
  "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，按指定路径读取；文件要求为 24kHz 16 位 单声道的 pcm 文件）
  • priority_level: 优先级，保持 INTERACTION_L6 即可
  • domain: 调用方来源标识，可以传入自定义的客户端字符串，方便问题排查等
  • trace_id: 播报 id，如果需要获取播报状态，则需要传入该字段，并将其值作为查询播报状态的参数
出参 
{
  "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 文件，其余头部格式以及压缩格式等均不支持，推荐使用 24kHz 16 位单声道的 pcm 文件
  • 如果传入错误或不存在的文件名，会静默失败，不会进行播放，同时 is_success 返回 true

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

Section titled “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
入参 
{
  "trace_id": "hafhjkqwjwefk"
}
  • trace_id: 播报 id，填写调用 PlayTTS 或 PlayMediaFile 接口时使用的 id
出参 
{
  "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 接口

Section titled “7.2.5 TTS/音频文件播放状态 Topic 接口”
接口名 /interaction/tts_status
功能概述 TTS/音频文件播放状态
接口类型 ROS2 Topic
出参 
{
  "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 接口

Section titled “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
入参 
{
  "trace_id": "hafhjkqwjwefk"
}
  • trace_id: 播报 id，填写调用 PlayTTS 或 PlayMediaFile 接口时使用的 id
出参 
{
  "state":"CommonState_UNKNOWN"
}
  • state: 调用请求状态，无需关注具体值，HTTP 请求返回 200 即代表成功
示例脚本 examples/agent/stop_tts.sh
备注

7.2.7 音量获取、设置 RPC 接口

Section titled “7.2.7 音量获取、设置 RPC 接口”
接口名 pb:/aimdk.protocol.HalAudioService/GetAudioVolume
功能概述 获取当前音量大小
接口类型 HTTP JSON RPC
URL http://10.42.10.10:56666/rpc/aimdk.protocol.HalAudioService/GetAudioVolume
入参 
{}
出参 
{
  "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
入参 
{
  "audio_volume": 70,
  "is_mute": false,
  "type": "SPEAKER_BUILT_IN"
}
  • audio_volume: 音量大小，0-100 的数值，注意不要调节音量超过 70，音量超出此范围扬声器经功放放大后会超额定工作，造成扬声器损坏
  • is_mute: 是否静音
  • type: 扬声器类型
出参 
{
  "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 申请音频焦点

Section titled “7.2.8 申请音频焦点”
接口名 /audio_5Fmsgs/srv/RequestAudioFocus
功能概述 申请音频焦点
接口类型 services
入参 
{
    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 释放音频焦点

Section titled “7.2.9 释放音频焦点”
接口名 /audio_5Fmsgs/srv/AbandonAudioFocus
功能概述 释放音频焦点
接口类型 services
入参 
{
    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 播放流式音频

Section titled “7.2.10 播放流式音频”
接口名 /audiohal/audio/playback
功能概述 播放流式音频
接口类型 topic
入参 
{
  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