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

7.3 麦克风管理部分

7.3 麦克风管理部分

7.3.1 整体介绍

机器人默认可用两种不同麦克风作为交互输入源，分别为外置麦（闪客领夹麦）和内置麦（机器人自带麦克风），另外可以设置静默模式不进行交互，可以通过 AimMaster 软件进行麦克风切换和静默模式设置，同时我们也提供了 RPC 接口来进行麦克风来源切换和静默模式设置。

此外，我们还提供麦克风原始音频输出能力（包含本体降噪、回声消除以及 VAD 处理后的音频数据）。在关闭智元自身交互链路后，用户可通过该接口获取麦克风音频，并接入自定义的交互系统。

需要说明的是，静默模式是 normal 模式下的一种运行状态，支持在无需重启 agent 的情况下进行灵活切换。

7.3.2 设置静默模式 RPC 接口

接口名pb:/aimdk.protocol.AgentControlService/SetVoiceEnable
功能概述设置静默模式
接口类型 HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/SetVoiceEnable
入参
text
{
  "enable_voice": false
}
  • enable_voice: 设为 false 为开启静默模式，设为 true 为正常模式
出参
text
{
  "header": {
    "code": "0",
    "msg": "SetVoiceEnable successfully",
    "trace_id": "",
    "domin": ""
  },
  "state": "CommonState_UNKNOWN"
}
  • state：无需关注
示例脚本examples/agent/SetVoiceEnable.sh
备注

7.3.3 查询静默模式 RPC 接口

接口名pb:/aimdk.protocol.AgentControlService/GetVoiceEnable
功能概述查询静默模式状态
接口类型 HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/GetVoiceEnable
入参
text
{}
出参
text
{
  "header": {
    "code": "0",
    "msg": "GetVoiceEnable successfully",
    "trace_id": "",
    "domin": ""
  },
  "enable_voice": true
}
  • enable_voice: 设为 false 为开启静默模式，设为 true 为正常模式
示例脚本examples/agent/GetVoiceEnable.sh
备注

7.3.4 设置交互运行模式 RPC 接口

接口名pb:/aimdk.protocol.AgentControlService/SetAgentPropertiesRequest
功能概述设置交互运行模式
接口类型 HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/SetAgentPropertiesRequest
入参
text
{
  "contents": {
    "properties": {
      "2": "only_voice"
    }
  }
}
模式：
  • only_voice：仅输出降噪麦克音频 /agent/process_audio_output，后续链路全部断开
  • normal：常规运行模式，交互正常运行
出参
text
{
  "state": "CommonState_UNKNOWN"
}
示例脚本examples/agent/SetAgentPropertiesRequest.sh
备注
  • 调用后重启机器人方可生效
  • 调用后返回值为CommonState_UNKNOWN是正常现象，可以调用GetAgentPropertiesRequest接口，查看交互运行模式是否切换成功

7.3.5 获取交互运行模式 RPC 接口

接口名pb:/aimdk.protocol.AgentControlService/GetAgentPropertiesRequest
功能概述查询交互运行模式
接口类型 HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/GetAgentPropertiesRequest
入参
text
{}
出参
text
{
  "contents": {
    "properties": {
      "2": "only_voice"
    }
  }
}
模式：
  • only_voice：仅输出降噪麦克音频 /agent/process_audio_output，后续链路全部断开
  • normal：常规运行模式，交互正常运行
示例脚本examples/agent/GetAgentPropertiesRequest.sh
备注

7.3.6 降噪麦克音频 Topic 接口

接口名/agent/process_audio_output
功能概述降噪麦克音频接口
接口类型 ROS2 Topic
出参
text
{
  "stream_id": 2,
  "vad_state": "AUDIO_VAD_STATE_PROCESSING",
  "audio_data": "..."
}
  • stream_id： 麦克风标识，1 为内置麦，2 为外置麦
  • vad_state：活动音频检测状态
    • AUDIO_VAD_STATE_NONE = 0
    • AUDIO_VAD_STATE_BEGIN = 1
    • AUDIO_VAD_STATE_PROCESSING = 2
    • AUDIO_VAD_STATE_END = 3
  • audio_data：音频字节流数据
示例脚本examples/agent/get_voice.py
备注
  • 该消息的 ROS2 类型为 ros2_plugin_proto/msg/RosMsgWrapper，需要 source prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash 后使用。
  • 注意：要获取以下音频需要机器人开机时至少联网 2 分钟以上完成音频相关鉴权操作，否则将无原始音频输出，如需离线使用，请首先保证该接口有音频输出后再断网。
  • 注意：当前版本外置麦克风的接口输出 vad_state 存在问题，预期一条语音输入的状态为 122222222223，实际输出的状态为 0111111111112，此问题仅在外置麦场景下出现（内置麦正常），并计划在后续版本修复。当前版本建议手动对状态执行 +1 补偿。

7.3.7 唤醒结果上报

接口名 /agent/wakeup
功能概述唤醒结果上报
接口类型 ROS2 Topic
出参
text
{
    "language":"zh",
    "keyword":"远征远征"，
    "timestamp":"1768812507657",
    "confidence":1.0,
    "wakeup_id":"event_wMXK9pT05JMXeRAOSc706",
    "is_success":true,
    "wakeup_type":"WAKEUP_NORMAL"
}
  • confidence：语音匹配置信度，0-1 之间的数值
  • Keyword: 唤醒词
  • language:目前仅支持中文
  • wakeup_type:
    • WAKEUP_UNKNOWN ：无法确定来源或状态的唤醒（占位/异常场景）
    • WAKEUP_NORMAL ：正常语音唤醒，例如用户说出默认唤醒词。
    • WAKEUP_CUSTOM_TRIGGERED ：由自定义方式触发的唤醒，比如自定义唤醒词或外部事件。
示例脚本examples/agent/get_wakeup_result.py
备注
  • 该消息的 ROS2 类型为 ros2_plugin_proto/msg/RosMsgWrapper，需要 source prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash 后使用。

7.3.8 内外置麦切换 RPC 接口

接口名pb:/aimdk.protocol.AgentControlService/SetMicSourceRequest
功能概述切换内外置麦克风来源
接口类型 HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/SetMicSourceRequest
入参
text
{
  "mic_source": 1
}
  • mic_source: 0 代表内置麦，1 代表外置麦，其余值无效
出参
text
{
  "header": {
    "code": "0",
    "msg": "SetVoiceEnable successfully",
    "trace_id": "",
    "domin": ""
  },
  "state": "CommonState_UNKNOWN"
}
  • state: 无需关注
示例脚本examples/agent/SetMicSource.sh
备注

7.3.9 内外置麦状态获取 RPC 接口

接口名pb:/aimdk.protocol.AgentControlService/GetMicSourceRequest
功能概述获取当前使用的麦克风来源
接口类型 HTTP JSON RPC
URLhttp://10.42.10.10:59301/rpc/aimdk.protocol.AgentControlService/GetMicSourceRequest
入参
text
{}
出参
text
{
  "header": {
    "code": "0",
    "msg": "Get mic source successfully",
    "trace_id": "",
    "domin": ""
  },
  "mic_source": 0
}
  • mic_source: 0 代表内置麦，1 代表外置麦，其余值无效
示例脚本examples/agent/GetMicSource.sh
备注