AIMA开放平台文档中心AimDK A2-lite

7.3 音频播放部分

7.3 音频播放部分

7.3.1 整体介绍

A2 青春款机器人无麦克风，无法进行语音交互等功能，但是配有扬声器，可以进行基本的音频文件播放和音量调节，同时可以支持队列播放、播放状态查询以及打断等控制逻辑。

7.3.2 音频文件播放 RPC 接口

接口名pb:/aimdk.protocol.TTSService/PlayMediaFile
功能概述音频文件播放
接口类型 HTTP JSON RPC
URLhttp://127.0.0.1:59201/rpc/aimdk.protocol.TTSService/PlayMediaFile
入参
text
{
  "file_name": "wake.pcm",
  "priority_level": "INTERACTION_L6",
  "domain": "example",
  "trace_id": "hafhjkqwjwefk",
  "is_interrupted": true
}
  • file_name: 文件名（存放于/agibot/data/var/interaction/audio/，比如 wake.pcm, 文件要求为 24kHz 16 位 单声道的 pcm 文件，需要创建单独文件夹，传入 文件夹名/文件名，比如 file/wake.pcm）
  • priority_level: 优先级，保持 INTERACTION_L6 即可
  • domain: 调用方来源标识，可以传入自定义的客户端字符串，方便问题排查等
  • trace_id: 播报 id，如果需要获取播报状态，则需要传入该字段，并将其值作为查询播报状态的参数
  • is_interrupted: 是否打断同等优先级播报，请默认传 true，有队列播报的需求可以使用 false
出参
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: 优先级等级，无需关注
  • pritority_weight: 优先级权重，无需关注
  • domain: 调用方来源标识，返回请求中传入的自定义字符串，方便问题排查
  • trace_id: 播报 id，返回请求中传入的自定义字符串，方便问题排查
  • is_success: 优先级校验是否成功，一般均为 true，不代表会播放，例如传入错误或不存在的文件名仍会返回 true，只有当前有更高优先级的内容播报时才会返回 true，例如当前有故障报警播报时
  • estimated_duration: 无效字段，无需关注，无法估算播放时长
示例脚本examples/audio/play_media_file.sh
备注
  • 同时支持标准 44 字节头部 Linear PCM 的 wav 文件，其余头部格式以及压缩格式等均不支持，推荐使用 24kHz 16 位单声道的 pcm 文件
  • 如果传入错误或不存在的文件名，会静默失败，不会进行播放，同时 is_success 返回 true

7.3.3 音频文件播放状态查询 RPC 接口

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

7.3.4 音频文件播放打断 RPC 接口

我们提供了单个文件播放打断接口和整个播报队列清空接口。

接口名pb:/aimdk.protocol.TTSService/StopTTSTraceId
功能概述打断单个文件播放
接口类型 HTTP JSON RPC
URLhttp://127.0.0.1:59201/rpc/aimdk.protocol.TTSService/StopTTSTraceId
入参
text
{
  "trace_id": "hafhjkqwjwefk"
}
  • trace_id: 播报 id，填写调用 PlayMediaFile 接口时传入的自定义 id
出参
text
{
  "state":"CommonState_UNKNOWN"
}
  • state: 调用请求状态，无需关注具体值，HTTP 请求返回 200 即代表成功
示例脚本examples/audio/stop_trace_id.sh
备注
接口名pb:/aimdk.protocol.TTSService/StopTTS
功能概述终止所有音频文件播放，包括当前播放任务和所有队列中的任务
接口类型 HTTP JSON RPC
URLhttp://127.0.0.1:59201/rpc/aimdk.protocol.TTSService/StopTTS
入参
text
{}
  • trace_id: 播报 id，填写调用 PlayMediaFile 接口时传入的自定义 id
出参
text
{
  "state":"CommonState_UNKNOWN"
}
  • state: 调用请求状态，无需关注具体值，HTTP 请求返回 200 即代表成功
示例脚本examples/audio/stop_all.sh
备注

7.3.5 音量获取、设置 RPC 接口

接口名pb:/aimdk.protocol.HalAudioService/GetAudioVolume
功能概述获取当前音量大小
接口类型 HTTP JSON RPC
URLhttp://127.0.0.1:59201/rpc/aimdk.protocol.HalAudioService/GetAudioVolume
入参
text
{}
出参
text
{
  "header": {
    "code": "0",
    "msg": "GetAudioVolume successfully",
    "trace_id": "",
    "domin": ""
  },
  "audio_volume": 80,
  "is_mute": false
}
  • audio_volume: 音量大小，0-100 的数值
  • is_mute: 是否静音
示例脚本examples/audio/get_audio_volume.sh
备注
接口名pb:/aimdk.protocol.HalAudioService/SetAudioVolume
功能概述调节音量
接口类型 HTTP JSON RPC
URLhttp://127.0.0.1:59201/rpc/aimdk.protocol.HalAudioService/SetAudioVolume
入参
text
{
  "audio_volume": 70,
  "is_mute": false
}
  • audio_volume: 音量大小，0-100 的数值，注意不要调节音量超过 70，音量超出此范围扬声器经功放放大后会超额定工作，造成扬声器损坏
  • is_mute: 是否静音
出参
text
{
  "header": {
    "code": "0",
    "msg": "SetAudioVolume successfully",
    "trace_id": "",
    "domin": ""
  },
  "pkg_name": "",
  "is_success": false
}
  • pkg_name: 无效字段，无需关注
  • is_success: 无效字段，无需关注
示例脚本examples/audio/set_audio_volume.sh
备注