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

7.3 麦克风管理部分

7.3 麦克风管理部分

Section titled “7.3 麦克风管理部分”

7.3.1 整体介绍

Section titled “7.3.1 整体介绍”

目前机器人仅支持使用外置麦克风（闪客领夹麦）作为交互输入源，内置麦克风尚未配置或启用。 同时，系统支持通过 AimMaster 设置静默模式，也提供了 RPC 接口用于程序化控制静默模式的开关。

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

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

7.3.2 设置静默模式 RPC 接口

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

7.3.3 查询静默模式 RPC 接口

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

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

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

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

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

7.3.6 降噪麦克音频 Topic 接口

Section titled “7.3.6 降噪麦克音频 Topic 接口”
接口名 /agent/process_audio_output
功能概述 降噪麦克音频接口
接口类型 ROS2 Topic
出参 
{
  "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 唤醒结果上报

Section titled “7.3.7 唤醒结果上报”
接口名 /agent/wakeup
功能概述 唤醒结果上报
接口类型 ROS2 Topic
出参
 
{
    "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 后使用。