feishu-voice

# 飞书语音消息发送技能 将文本转换为语音消息发送到飞书，支持在飞书聊天窗口直接播放。 ## 功能特性 - ✅ TTS 文字转语音（使用 **coze-tts**） - ✅ 支持语速调整（0.5-2.0x） - ✅ 自动转换为 opus 格式（飞书要求） - ✅ 读取音频时长 - ✅ 上传到飞书服务器 - ✅ 发送可播放的语音消息 ## 前置要求 ### 环境变量 **必需变量：** ```bash # 飞书配置（必需） export FEISHU_APP_ID="cli_xxx" # 飞书应用 ID export FEISHU_APP_SECRET="your_secret" # 飞书应用密钥 # Coze 配置（用于 TTS） export COZE_API_KEY="your_coze_key" # Coze API 密钥 ``` **可选变量：** ```bash # 接收者配置 export FEISHU_RECEIVER="ou_xxx" # 默认接收者 Open ID # 多应用配置（用于支持多个飞书应用） export FEISHU_APP_ID_B="cli_xxx" # 应用 B 的 ID export FEISHU_APP_SECRET_B="your_secret" # 应用 B 的密钥 export FEISHU_RECEIVER_B="ou_xxx" # 应用 B 的接收者 # 工作区路径（用于定位依赖技能） export OPENCLAW_WORKSPACE="/path/to/workspace" # OpenClaw 工作区目录 ``` ### 必需工具 - `ffmpeg` - 音频格式转换、语速调整 - `ffprobe` - 读取音频信息 - `jq` - JSON 处理 ### 依赖技能 - `coze-tts` - 文字转语音 ## 使用方法 ### 基本用法 ```bash # 发送语音消息 bash scripts/send_voice.sh "你好，这是一条语音消息" ``` ### 高级选项 ```bash # 指定 voice_id 和语速 bash scripts/send_voice.sh "你好" 2 1.2 # 参数说明： # - voice_id: Coze 音色 ID（默认 1） # - 语速: 0.5-2.0（默认 1.0） ``` ## 脚本说明 ### send_voice.sh 主脚本，完整的语音消息发送流程。 **用法：** ```bash bash scripts/send_voice.sh <文本> [voice_id] [语速] [接收者] ``` **参数：** - `文本` (必需): 要转换为语音的文字 - `voice_id` (可选): Coze 音色 ID（默认：1） - `语速` (可选): 0.5-2.0（默认：1.0） - `接收者` (可选): 飞书 open_id **环境变量：** - `FEISHU_APP_ID`: 飞书应用 ID - `FEISHU_APP_SECRET`: 飞书应用密钥 - `FEISHU_RECEIVER`: 接收者 Open ID（可选） - `COZE_API_KEY`: Coze API 密钥 ### 流程说明 1. **TTS 生成**: 使用 coze-tts 生成 MP3 格式音频 2. **语速调整**（可选）: 使用 ffmpeg atempo 滤镜调整语速 3. **格式转换**: 使用 ffmpeg 转换为 opus 格式 4. **读取时长**: 使用 ffprobe 获取音频时长（毫秒） 5. **上传文件**: 上传到飞书，指定 `file_type=opus` 和 `duration` 6. **发送消息**: 发送 `msg_type=audio` 消息 ## 技术细节 ### 音频格式要求 飞书语音消息要求： - **格式**: opus (OGG 容器) - **编码**: libopus - **比特率**: 24k - **采样率**: 24000 Hz - **声道**: 单声道 ### Duration 参数 **关键**: 必须在上传时提供 `duration` 参数（整数毫秒），否则时长显示为 0。 ```bash # 正确的上传方式 curl -X POST "https://open.feishu.cn/open-apis/im/v1/files" \ -F "file=@voice.opus" \ -F "file_type=opus" \ -F "duration=6000" # ← 关键参数（毫秒） ``` ### API 端点 | 端点 | 用途 | |------|------| | `/auth/v3/tenant_access_token/internal` | 获取访问令牌 | | `/im/v1/files` | 上传文件 | | `/im/v1/messages` | 发送消息 | ## 故障排查 ### 语音没有时长 **问题**: 发送的语音消息时长显示为 0 **解决**: 确保在上传时传递了 `duration` 参数（整数毫秒） ```bash # 获取时长（转换为毫秒） DURATION_MS=$(ffprobe -v error -show_entries format=duration \ -of default=noprint_wrappers=1:nokey=1 voice.opus | awk '{printf "%.0f", $1 * 1000}') # 上传时带上 duration（毫秒） curl ... -F "duration=$DURATION_MS" ``` ### 无法播放 **问题**: 语音消息无法播放 **可能原因**: 1. 格式不是 opus 2. `file_type` 参数错误 3. 文件损坏 **解决**: ```bash # 检查格式 ffprobe voice.opus # 重新转换 ffmpeg -i input.mp3 -c:a libopus -b:a 24k voice.opus ``` ### API 权限错误 **问题**: 上传时返回权限错误 **解决**: 确保飞书应用有以下权限： - `im:message` - `im:message:send_as_bot` ## 完整示例 ```bash # 设置环境变量 export FEISHU_APP_ID="your_app_id_here" export FEISHU_APP_SECRET="your_app_secret_here" export COZE_API_KEY="your_coze_key_here" # 发送语音（默认设置） bash scripts/send_voice.sh \ "你好，这是一条测试语音消息。" # 发送语音（指定 voice_id=2，语速 1.2x） bash scripts/send_voice.sh \ "你好，这是一条测试语音消息。" 2 1.2 ``` ## 注意事项 1. **Coze TTS 限制**: 单次文本长度请参考 Coze 文档 2. **整数时长**: duration 必须是整数毫秒 3. **opus 格式**: 飞书只接受 opus 格式的音频消息 4. **语速范围**: 支持 0.5-2.0x，使用 ffmpeg atempo 实现 5. **文件清理**: 临时文件会自动清理 ## 相关技能 - `coze-tts`: 文字转语音 - `coze-asr`: 语音转文字 ## 更新日志 **2026-03-24**: 从 zhipu-tts 迁移到 coze-tts，新增语速调整功能