| name | feishu-voice-note-ffmpeg |
| description | 解决飞书 IM 语音气泡问题——通过 ffmpeg 将 TTS 输出的 mp3 转为飞书支持的 ogg-opus 格式。适用场景：(1) 在飞书机器人的 TTS 回复中需要显示语音气泡而非文件附件, (2) Edge TTS 或其他只支持 mp3/webm 输出的 TTS 引擎需要适配飞书, (3) 自定义 TTS provider 的飞书集成。包含核心原理、ffmpeg 命令、OpenClaw pipeline 集成方案。 |
| metadata | {"openclaw":{"homepage":"https://open.feishu.cn/document/ukTMukTMukTM/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create_json"}} |
飞书语音气泡 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 参数判断），如果是则：
- 调用目标 TTS 引擎生成 mp3
- 自动调用 ffmpeg 转成 ogg-opus
- 返回
.opus 文件路径给消息发送管线
- 飞书通道检测到
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
实施建议
- 优先在 TTS provider 输出后、消息发送前 做转码
- 不建议把转码逻辑塞进上层业务逻辑；媒体格式适配应尽量留在音频管线内部
- 先保证失败可降级，再追求“始终发语音气泡”
已知限制
- ffmpeg 必须安装在系统 PATH 中
- 转码增加约 50-200ms 延迟（取决于音频时长）
- 临时文件需要及时清理，避免磁盘占用
- 更新 TTS provider 或消息通道组件后，集成代码可能需要重新应用
- 飞书 API 要求 opus 文件大小不超过一定限制（通常语音消息几秒内的文件无问题）
