edit | blame | history | raw

lm-livekit-helper

lm-livekit-helper 是 Combrabo Voice 的 LiveKit 媒体 worker。它从 lmrobot-app 接收每次通话的 CV_* 运行参数，加入 LiveKit 房间，发布 bot 音轨，播放主动问候音频，并在 S7 阶段承接用户语音 turn 的媒体输入输出。

它不是业务服务，不承担鉴权、数据库、订单、ASR/LLM/TTS 权威、消息落库或 diagnostics 聚合。业务权威仍在 lmrobot-app。

当前职责

  1. 读取 lmrobot-app 注入的 CV_* 环境变量；
  2. 使用 bot token 连接 LiveKit room；
  3. 发布 bot 本地音轨；
  4. 播放 WAV / MP3 主动问候音频；
  5. 在 smoke 模式下通过 LiveKit reliable Data Message 下发 device_output；
  6. S7 阶段通过 Java runtime turn bridge 复用后端 ASR / TextChat / TTS / Message 能力。

本机构建

cargo build --release

helper 目录内带 .cargo/config.toml，本机构建建议通过本仓库根目录执行，确保使用同一套 registry / retry 配置。

本机运行

推荐通过包装脚本启动：

./run-local.sh

如果本地还没有 release 二进制，脚本会先执行构建。macOS 默认优先使用 Docker 模式，避免 host 侧 WebRTC native 依赖链路反复阻塞。

可预先准备运行模式：

./run-local.sh --prepare
./run-local.sh --prepare --rebuild

本机固定问候音频

helper 支持 WAV / MP3 音频自动识别。主动问候 prepare 生成的 MP3 可以直接进入 helper；本地 smoke 仍可使用 WAV fixture 作为固定兜底样本。

在 macOS local 环境，可先生成一份本机固定问候 WAV fixture：

./generate-local-fixture.sh

默认输出：

.local/greeting-local.wav

lmrobot-app 接线示例

export COMBRABO_VOICE_RUNTIME_WORKDIR=/opt/lmrobot/lm-livekit-helper
export COMBRABO_VOICE_RUNTIME_LAUNCH_COMMAND=/opt/lmrobot/lm-livekit-helper/run-local.sh
export COMBRABO_VOICE_RUNTIME_HELPER_MODE=docker
export COMBRABO_VOICE_RUNTIME_HELPER_IMAGE=registry.example.com/lm-livekit-helper:git-sha
export COMBRABO_VOICE_RUNTIME_FALLBACK_GREETING_AUDIO_PATH=/opt/lmrobot/lm-livekit-helper/.local/greeting-local.wav

CV_LIVEKIT_URL、CV_LIVEKIT_ROOM_ID、CV_LIVEKIT_BOT_TOKEN、CV_LIVEKIT_BOT_PARTICIPANT_IDENTITY 等连接材料由 lmrobot-app 在每次 calls/start 时生成并注入，不写入仓库。

LiveKit Data 设备输出 smoke

需要验证 NativeSDK 是否能收到设备输出 Data Message 时，在启动 lmrobot-app 前打开：

export CV_DEVICE_OUTPUT_SMOKE_ENABLED=true

helper 会在 bot 进房并发布音轨后，向 CV_LIVEKIT_USER_PARTICIPANT_IDENTITY 指向的 SDK client 发送 reliable Data Message：

  • topic: device_output
  • type: device_output
  • schemaVersion: 1.0
  • commandCode: 例如 vibration.start
  • params: 设备参数

如需指定接收方，可使用英文逗号分隔：

export CV_DEVICE_OUTPUT_DESTINATION_IDENTITIES=client-identity-a,client-identity-b

如果没有指定接收方且没有 CV_LIVEKIT_USER_PARTICIPANT_IDENTITY，helper 会广播到 room。设备控制建议继续使用 reliable/ordered Data Message；ACK / 执行结果首版建议走 HTTP，便于落库、重试和排查。

文档

安全要求

仓库内只允许提交 .env.example 这类脱敏样例。禁止提交真实 LiveKit token、API key、secret、roomId、participantIdentity、用户语音内容、ASR 文本、LLM 回复全文或完整 prompt。