语音控制

本模块提供机器人语音相关的所有功能，包括语音识别、语音合成、语音控制等。

voice 高层接口（推荐）

底层 ROS2 接口 — voice.say

组合调用，依次触达以下 ROS2 通道（均经 Speech 单例转发）：

  1. 经 Speech.enable_tts 转发 — Service std_srvs/srv/SetBool，名称 /speech/enable_tts_engine（自动启用 TTS 引擎，request.data = True）。

  2. volume 非 None 时经 Speech.set_volume 转发 — Service speech_interface/srv/SetVolume，名称 /speech/set_volume。

  3. 经 Speech.generate_audio 转发 — Action speech_interface/action/GenerateAudio，名称 /speech/generate_audio。

  • 参数映射:

封装参数

原生字段

text

goal.text（Action Goal）

sid

goal.sid（Action Goal）

speed

goal.speed（Action Goal）

volume

request.volume（SetVolume Request；仅提供时下发）

block / timeout

客户端行为，不下发

底层 ROS2 接口 — voice.wait_for_say

经 Speech.wait_for_generate_audio 转发 — 客户端行为，不下发：仅等待最近一次非阻塞 generate_audio（Action speech_interface/action/GenerateAudio，名称 /speech/generate_audio）在客户端缓存的结果 future，不发起新的 ROS2 请求。

底层 ROS2 接口 — voice.stop_say

经 Speech.stop_playing_tts 转发。

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/stop_playing_tts

  • 参数映射:

封装参数

原生字段（Request）

（固定 True）

request.data

timeout

客户端行为，不下发

底层 ROS2 接口 — voice.listen

组合调用（经 Speech 单例转发）：

  1. 经 Speech.enable_asr 转发 — Service std_srvs/srv/SetBool，名称 /speech/enable_asr_engine（自动启用 ASR 引擎，request.data = True）。

  2. 经 Speech.register_asr_callback 转发 — Topic 订阅 /speech/asr_result（speech_interface/msg/AsrResult），仅注册进程内回调。

callback / hints / block / timeout / hint_callbacks 均为客户端行为，不下发。

底层 ROS2 接口 — voice.stop_listen

经 Speech.register_asr_callback(None) 转发 — 客户端行为，不下发：仅注销进程内 ASR 回调，不发起 ROS2 通信（/speech/asr_result 的 Topic 订阅本身保持存在）。

底层 ROS2 接口 — voice.wait_for_awaken

组合调用（经 Speech 单例转发）：

  1. 经 Speech.enable_hexaware 转发 — Service std_srvs/srv/SetBool，名称 /speech/enable_hexaware（自动启用唤醒引擎，request.data = True）。

  2. 经 Speech.register_hexaware_callback 转发 — Topic 订阅 /speech/hexaware_awaken（std_msgs/msg/String），仅注册进程内回调。

callback / block / timeout 均为客户端行为，不下发。

底层 ROS2 接口 — voice.set_volume

经 Speech.set_volume 转发。

  • 类型: Service speech_interface/srv/SetVolume

  • 名称: /speech/set_volume

  • 参数映射:

封装参数

原生字段（Request）

volume

request.volume

timeout

客户端行为，不下发

底层 ROS2 接口 — ListenHandle

ListenHandle 的各方法/属性均为客户端行为，不发起 ROS2 通信；其中 handle.stop() 会经 Speech.register_asr_callback(None) 注销进程内 ASR 回调（Topic 订阅本身保持存在）。

底层接口（精细控制）

单例与基础

static Speech.get_instance()

Get the singleton instance of Speech.

Returns:

Singleton instance.

Return type:

Speech

Examples:

speech = Speech.get_instance()

底层 ROS2 接口

无 ROS2 通道：进程内获取 Speech 单例，客户端行为，不下发。

AFE (音频前处理)

Speech.enable_afe_engine(enable, block=True, timeout=5)

Enable or disable Audio Front End (AFE) engine.

Parameters:

  • enable (bool) – True to enable, False to disable.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

EnableAfeEngineResponse.

Examples:

# Enable AFE
enable_afe_engine(True)

# Disable AFE with custom timeout
enable_afe_engine(False, timeout=10)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/enable_afe_engine

  • 参数映射:

封装参数

原生字段（Request）

enable

request.data

block / timeout

客户端行为，不下发
Speech.enable_aec(enable, block=True, timeout=5)

Enable or disable Acoustic Echo Cancellation (AEC).

Parameters:

  • enable (bool) – True to enable, False to disable.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

EnableAecResponse.

Examples:

enable_aec(True)
enable_aec(False, timeout=8)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/enable_aec

  • 参数映射:

封装参数

原生字段（Request）

enable

request.data

block / timeout

客户端行为，不下发
Speech.enable_speech_enhance(enable, block=True, timeout=5)

Enable or disable speech enhancement.

Parameters:

  • enable (bool) – True to enable, False to disable.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

EnableSpeechEnhanceResponse.

Examples:

enable_speech_enhance(True)
enable_speech_enhance(False)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/enable_speech_enhance

  • 参数映射:

封装参数

原生字段（Request）

enable

request.data

block / timeout

客户端行为，不下发
Speech.set_bypass(bypass, block=True, timeout=5)

Set AFE bypass mode.

Parameters:

  • bypass (bool) – True to bypass AFE processing, False to use AFE.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

SetBypassResponse.

Examples:

set_bypass(True)
set_bypass(False, timeout=10)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/set_bypass

  • 参数映射:

封装参数

原生字段（Request）

bypass

request.data

block / timeout

客户端行为，不下发
Speech.mute_clean_mic(mute, block=True, timeout=5)

Mute or unmute clean microphone.

Parameters:

  • mute (bool) – True to mute, False to unmute.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

MuteCleanMicResponse.

Examples:

mute_clean_mic(True)
mute_clean_mic(False, timeout=6)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/mute_clean_mic

  • 参数映射:

封装参数

原生字段（Request）

mute

request.data

block / timeout

客户端行为，不下发

ASR (语音识别)

Speech.enable_asr(enable, block=True, timeout=30)

Enable or disable Automatic Speech Recognition (ASR).

Parameters:

  • enable (bool) – True to enable, False to disable.

  • timeout (int) – Timeout in seconds (default: 30).

Return type:

EnableServiceResponse

Returns:

EnableAsrResponse.

Examples:

enable_asr(True)
enable_asr(False, timeout=8)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/enable_asr_engine

  • 参数映射:

封装参数

原生字段（Request）

enable

request.data

block / timeout

客户端行为，不下发
Speech.switch_asr_device(device_name, timeout=5)

Switch ASR input device.

Parameters:

  • device_name (str) – Device name for ASR input.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

SwitchAsrDeviceResponse.

Examples:

switch_asr_device("default")
switch_asr_device("mic_array", timeout=10)

底层 ROS2 接口

  • 类型: Service speech_interface/srv/SwitchAsrDevice

  • 名称: /speech/switch_asr_device

  • 参数映射:

封装参数

原生字段（Request）

device_name

request.device_name

timeout

客户端行为，不下发

KWS (关键词唤醒)

Speech.enable_hexaware(enable, block=True, timeout=5)

Enable or disable Hexaware wake word detection.

Parameters:

  • enable (bool) – True to enable, False to disable.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

EnableHexawareResponse.

Examples:

enable_hexaware(True)
enable_hexaware(False, timeout=8)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/enable_hexaware

  • 参数映射:

封装参数

原生字段（Request）

enable

request.data

block / timeout

客户端行为，不下发
Speech.enable_kws(enable, block=True, timeout=5)

Enable or disable keyword spotting (KWS).

Parameters:

  • enable (bool) – True to enable, False to disable.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

EnableKwsResponse.

Examples:

enable_kws(True)
enable_kws(False, timeout=8)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/enable_kws

  • 参数映射:

封装参数

原生字段（Request）

enable

request.data

block / timeout

客户端行为，不下发

TTS (语音合成)

Speech.enable_tts(enable, block=True, timeout=30)

Enable or disable Text-to-Speech (TTS) engine.

Parameters:

  • enable (bool) – True to enable, False to disable.

  • timeout (int) – Timeout in seconds (default: 30).

Return type:

EnableServiceResponse

Returns:

EnableTtsResponse.

Examples:

enable_tts(True)
enable_tts(False, timeout=8)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/enable_tts_engine

  • 参数映射:

封装参数

原生字段（Request）

enable

request.data

block / timeout

客户端行为，不下发
Speech.stop_playing_tts(enable, block=True, timeout=5)

Stop playing current TTS audio.

Parameters:

  • enable (bool) – True to stop, False to ignore.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

StopPlayingTtsResponse.

Examples:

stop_playing_tts(True)
stop_playing_tts(True, timeout=8)
Parameters:

block (bool) –

底层 ROS2 接口

  • 类型: Service std_srvs/srv/SetBool

  • 名称: /speech/stop_playing_tts

  • 参数映射:

封装参数

原生字段（Request）

enable

request.data

block / timeout

客户端行为，不下发
Speech.switch_tts_device(device_name, timeout=5)

Switch TTS output device.

Parameters:

  • device_name (str) – Device name for TTS output.

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

SwitchTtsDeviceResponse.

Examples:

switch_tts_device("default")
switch_tts_device("speaker", timeout=10)

底层 ROS2 接口

  • 类型: Service speech_interface/srv/SwitchTtsDevice

  • 名称: /speech/switch_tts_device

  • 参数映射:

封装参数

原生字段（Request）

device_name

request.device_name

timeout

客户端行为，不下发
Speech.set_volume(volume, timeout=5)

Set TTS playback volume.

Parameters:

  • volume (float) – Volume in the range [0.0, 1.0].

  • timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

SetVolumeResponse.

Examples:

set_volume(0.5)
set_volume(1.0, timeout=10)

底层 ROS2 接口

  • 类型: Service speech_interface/srv/SetVolume

  • 名称: /speech/set_volume

  • 参数映射:

封装参数

原生字段（Request）

volume

request.volume

timeout

客户端行为，不下发
Speech.generate_audio(text, sid=0, speed=1.0, block=True, timeout=60, complete_cb=None, feedback_cb=None)

Generate and play audio from text.

Parameters:

  • text (str) – Text to convert to speech.

  • sid (int) – Speaker ID (default: 0).

  • speed (float) – Speech speed (default: 1.0).

  • block (bool) – Whether to block until completion (default: True).

  • timeout (int) – Timeout in seconds (default: 60).

  • complete_cb (callable) – Callback for completion (default: None).

  • feedback_cb (callable) – Callback for progress updates (default: None).

Return type:

GenerateAudioResponse

Returns:

GenerateAudioResponse.

Examples:

# Simple usage
generate_audio("Hello, world!")

# Customize speaker and speed
generate_audio("Hello", sid=1, speed=1.2)

# Non-blocking
generate_audio(text="Hello", block=False)

# With callbacks
def on_complete(response):
    print(f"Done: {response.result.message}")

def on_progress(event):
    print(f"Progress: {event.progress * 100:.1f}%")

generate_audio("Hello", complete_cb=on_complete, feedback_cb=on_progress)

底层 ROS2 接口

  • 类型: Action speech_interface/action/GenerateAudio

  • 名称: /speech/generate_audio

  • 参数映射:

封装参数

原生字段（Goal）

text

goal.text

sid

goal.sid

speed

goal.speed

block / timeout

客户端行为，不下发

complete_cb / feedback_cb

客户端行为，不下发（分别消费该 Action 的 Result / Feedback，仅当次调用生效）
Speech.wait_for_generate_audio(timeout=30)

Wait for the most recent non-blocking generate_audio call to complete.

Speech internally caches the last GenerateAudioResponse, so no resp argument is needed. Equivalent to the manual pattern:

if resp.has_future():
    if resp.future.wait_for(timeout=30):
        result = resp.future.get()
    else:
        # timeout / canceled
Parameters:

timeout (int) – Seconds to wait (default: 30). 0 means wait indefinitely.

Return type:

GenerateAudioResult

Returns:

GenerateAudioResult with success=True on completion, or success=False and message=”Timeout or canceled” on failure.

Examples:

speech.generate_audio("Hello", block=False)
# do other work ...
result = speech.wait_for_generate_audio(timeout=30)
if result.success:
    print("Done:", result.message)
else:
    print("Failed:", result.message)

底层 ROS2 接口

无独立 ROS2 通道：纯客户端行为——等待最近一次非阻塞 generate_audio（Action speech_interface/action/GenerateAudio，名称 /speech/generate_audio）在客户端 缓存的 result future，不发起任何新的 ROS2 请求；timeout 为客户端等待时长 （0 = 无限等待）。

Speech.cancel_generate_audio(timeout=5)

Cancel ongoing audio generation.

Parameters:

timeout (int) – Timeout in seconds (default: 5).

Return type:

EnableServiceResponse

Returns:

CancelGenerateAudioResponse.

Examples:

# Cancel current audio generation
cancel_generate_audio()

# Cancel with custom timeout
cancel_generate_audio(timeout=8)

底层 ROS2 接口

  • 类型: Action 取消请求（rclcpp_action 内置取消通道 action_msgs/srv/CancelGoal）

  • 名称: /speech/generate_audio（对当前活动 goal 调 async_cancel_goal）

  • 参数映射:

封装参数

原生字段

timeout

客户端行为，不下发

事件回调

Speech.register_asr_callback(callback=None)

Register callback for ASR (speech recognition) results.

Parameters:

callback (callable) – Callback function that receives AsrResultEvent. Pass None to unregister.

Return type:

None

Returns:

None.

Examples:

def on_asr(event):
    print(f"Recognized: {event.text}")

register_asr_callback(on_asr)
# Unregister
register_asr_callback(None)

底层 ROS2 接口

  • 类型: Topic 订阅 speech_interface/msg/AsrResult

  • 名称: /speech/asr_result

  • 说明: 订阅在 Speech 初始化时已创建；本方法仅注册/注销进程内回调（客户端行为，不下发）。

Speech.register_hexaware_callback(callback=None)

Register callback for wake word detection.

Parameters:

callback (callable) – Callback function that receives HexawareAwakenEvent. Pass None to unregister.

Return type:

None

Returns:

None.

Examples:

def on_wake_word(event):
    print(f"Wake word detected: {event.keyword}")

register_hexaware_callback(on_wake_word)
register_hexaware_callback(None)

底层 ROS2 接口

  • 类型: Topic 订阅 std_msgs/msg/String

  • 名称: /speech/hexaware_awaken

  • 说明: 订阅在 Speech 初始化时已创建；本方法仅注册/注销进程内回调（客户端行为，不下发）。

Speech.register_kws_message_callback(callback=None)

Register callback for keyword spotting messages.

Parameters:

callback (callable) – Callback function that receives KwsMessageEvent. Pass None to unregister.

Return type:

None

Returns:

None.

Examples:

def on_kws_message(event):
    print(f"KWS message: {event.message}")

register_kws_message_callback(on_kws_message)
register_kws_message_callback(None)

底层 ROS2 接口

  • 类型: Topic 订阅 std_msgs/msg/String

  • 名称: /speech/kws_message

  • 说明: 订阅在 Speech 初始化时已创建；本方法仅注册/注销进程内回调（客户端行为，不下发）。

Speech.register_nlu_format_callback(callback=None)

Register callback for NLU format messages.

Parameters:

callback (callable) – Callback function that receives NluFormatEvent. Pass None to unregister.

Return type:

None

Returns:

None.

Examples:

def on_nlu_format(event):
    print(f"Input: {event.input_text}, Format: {event.format_text}")

register_nlu_format_callback(on_nlu_format)
register_nlu_format_callback(None)

底层 ROS2 接口

  • 类型: Topic 订阅 speech_interface/msg/NluFormat

  • 名称: /speech/nlu_format

  • 说明: 订阅在 Speech 初始化时已创建；本方法仅注册/注销进程内回调（客户端行为，不下发）。

Speech.register_generate_audio_callbacks(complete_cb, feedback_cb)

Register callbacks for audio generation progress and completion.

Parameters:

  • complete_cb (callable) – Callback for completion, receives GenerateAudioResponse.

  • feedback_cb (callable) – Callback for progress updates, receives GenerateAudioProgressEvent.

Return type:

None

Returns:

None.

Examples:

def on_complete(response):
    print(f"Audio generation complete: {response.result.message}")

def on_progress(event):
    print(f"Progress: {event.progress * 100:.1f}%")

register_generate_audio_callbacks(on_complete, on_progress)

底层 ROS2 接口

无独立 ROS2 通道：进程内注册 Action speech_interface/action/GenerateAudio（名称 /speech/generate_audio）的 Result / Feedback 回调，客户端行为，不下发。