飞书语音气泡 ffmpeg 方案

在飞书机器人中，语音消息只有以 ogg-opus 格式发送才会显示为可播放的语音气泡。

纯文本附件或其他格式会显示为文件附件，无法内联播放。

使用方式

适合在以下场景直接套用：

• TTS 已经能正常生成音频，但飞书里只显示为附件
• 希望把现有 mp3 / webm-opus 输出适配成飞书语音气泡
• 正在做 OpenClaw / 自定义机器人 / 自定义消息管线的飞书语音集成

核心原理

TTS 引擎（Edge TTS）
  → 输出 mp3（Edge TTS 原生仅支持 mp3 和 webm-opus）
    → ffmpeg 转码为 ogg-opus
      → 飞书 API 接收 ogg → 显示语音气泡 ✅

为什么需要转码：

• Edge TTS 仅支持 audio-24khz-48kbitrate-mono-mp3（mp3）和 webm-opus 格式
• 飞书官方只将 ogg-opus 识别为语音消息（msg_type: audio）
• webm 容器的 opus 文件飞书不识别，可能被当作视频或未知格式
• mp3 文件在飞书中只能作为文件附件发送

飞书官方推荐命令

ffmpeg -i input.mp3 -acodec libopus -ac 1 -ar 16000 output.opus

参数说明：

• -acodec libopus — 使用 Opus 编码器
• -ac 1 — 单声道（语音消息标准）
• -ar 16000 — 16kHz 采样率（语音质量与文件大小的平衡点）

在 OpenClaw 中的集成方案

方案概述

在 TTS provider 的 synthesize 函数中，检测当前通道是否要求语音气泡（通过 target 参数判断），如果是则：

1. 调用目标 TTS 引擎生成 mp3
2. 自动调用 ffmpeg 转成 ogg-opus
3. 返回 .opus 文件路径给消息发送管线
4. 飞书通道检测到 fileType: "opus" 后以 msg_type: "audio" 发送 → 语音气泡

关键集成点

TTS provider synthesize()
  → 生成 mp3 临时文件
  → 若 target === "voice-note"（飞书通道自动触发）:
    → ffmpeg -i temp.mp3 ... temp.opus
    → 返回 temp.opus 路径
  → 否则直接返回 mp3 路径

出错处理

• 如果 ffmpeg 转码失败（未安装、参数错误等），降级为返回原始 mp3 文件
• 降级后 mp3 会作为文件附件发送，不会导致崩溃

格式验证

转码后的 opus 文件可通过以下方式验证：

# 查看文件格式
ffprobe output.opus

# 确认编码器
ffprobe -show_streams output.opus | findstr codec

# 确认飞书兼容性
# 文件扩展名必须为 .opus
# MIME 类型应为 audio/opus 或 audio/ogg

实施建议

• 优先在 TTS provider 输出后、消息发送前 做转码
• 不建议把转码逻辑塞进上层业务逻辑；媒体格式适配应尽量留在音频管线内部
• 先保证失败可降级，再追求“始终发语音气泡”

已知限制

• ffmpeg 必须安装在系统 PATH 中
• 转码增加约 50-200ms 延迟（取决于音频时长）
• 临时文件需要及时清理，避免磁盘占用
• 更新 TTS provider 或消息通道组件后，集成代码可能需要重新应用
• 飞书 API 要求 opus 文件大小不超过一定限制（通常语音消息几秒内的文件无问题）