backup 2026-05-21-22-53-56

语音生成相关/配音生成工作流-Ubuntu-Agent.md

@@ -0,0 +1,242 @@
+# 配音生成工作流 Ubuntu Agent
+
+本文档用于指导 Agent 在 Ubuntu 环境中使用 `Tools_scripts_XunFei-Ubuntu`，将配音稿文字转为讯飞配音音频，并与视频合成为最终介绍视频。
+
+## 1. 目录约定
+
+建议保持以下结构：
+
+```text
+项目目录/
+  配音稿.md
+  Tools_scripts_XunFei-Ubuntu/
+    requirements-ubuntu.txt
+    xfyun_tts_ubuntu.py
+    synthesize_xfyun_tts.sh
+    synthesize_xfyun_super_tts.sh
+    check_audio_duration.sh
+    build_final_video_ubuntu.py
+```
+
+其中：
+
+- `xfyun_tts_ubuntu.py`：核心 Python 脚本，支持普通 TTS 和超拟人 TTS。
+- `synthesize_xfyun_tts.sh`：普通讯飞 TTS 入口，默认声音 `xiaoyan`。
+- `synthesize_xfyun_super_tts.sh`：讯飞超拟人 TTS 入口，默认声音 `x5_lingfeiyi_flow`。
+- `check_audio_duration.sh`：批量查看 mp3、wav、m4a 等音频时长。
+- `build_final_video_ubuntu.py`：将单个视频与配音音频合成为最终视频，并按旁白时长自动调整画面速度。
+
+## 2. 安装依赖
+
+```bash
+sudo apt update
+sudo apt install -y python3 python3-pip ffmpeg
+python3 -m pip install -r Tools_scripts_XunFei-Ubuntu/requirements-ubuntu.txt
+chmod +x Tools_scripts_XunFei-Ubuntu/*.sh Tools_scripts_XunFei-Ubuntu/*.py
+```
+
+如果使用虚拟环境：
+
+```bash
+python3 -m venv .venv-tts
+source .venv-tts/bin/activate
+python -m pip install -r Tools_scripts_XunFei-Ubuntu/requirements-ubuntu.txt
+```
+
+## 3. 配置讯飞环境变量
+
+```bash
+export XF_APPID="你的AppId"
+export XF_APIKEY="你的ApiKey"
+export XF_APISECRET="你的ApiSecret"
+```
+
+如需长期生效，可以写入 `~/.bashrc`：
+
+```bash
+cat >> ~/.bashrc <<'EOF'
+export XF_APPID="你的AppId"
+export XF_APIKEY="你的ApiKey"
+export XF_APISECRET="你的ApiSecret"
+EOF
+source ~/.bashrc
+```
+
+脚本不会保存密钥，也不要把真实密钥写入仓库。
+
+## 4. 配音稿格式
+
+脚本识别 Markdown 中的分段标题：
+
+```markdown
+## 1. 第一段标题
+第一段配音正文。
+
+## 2. 第二段标题
+第二段配音正文。
+
+## 3. 第三段标题
+第三段配音正文。
+
+## 4. 第四段标题
+第四段配音正文。
+```
+
+注意：
+
+- 标题建议保持 `## 1.` 到 `## 4.`。
+- 输出文件名会使用段号和标题，例如 `1-第一段标题.mp3`。
+- `说明：`、`时长：`、`备注：`、`镜头：`、`画面：` 等元信息行会被忽略。
+- 正文只放最终朗读内容，不要放内部提示词。
+
+可先做干跑检查：
+
+```bash
+python3 Tools_scripts_XunFei-Ubuntu/xfyun_tts_ubuntu.py \
+  --script 配音稿.md \
+  --dry-run
+```
+
+## 5. 普通 TTS 合成
+
+普通 TTS 适合快速生成清晰稳定的中文配音。
+
+```bash
+./Tools_scripts_XunFei-Ubuntu/synthesize_xfyun_tts.sh \
+  --script 配音稿.md \
+  --output-dir 02_audio/tts_audio_xiaoyan \
+  --voice xiaoyan \
+  --speed 50 \
+  --volume 70 \
+  --pitch 50
+```
+
+## 6. 超拟人 TTS 合成
+
+超拟人 TTS 更适合项目汇报、系统介绍和宣传片。
+
+```bash
+./Tools_scripts_XunFei-Ubuntu/synthesize_xfyun_super_tts.sh \
+  --script 配音稿.md \
+  --output-dir 02_audio/super_tts_x5_lingfeiyi \
+  --voice x5_lingfeiyi_flow \
+  --speed 50 \
+  --volume 70 \
+  --pitch 50
+```
+
+如果接口要求明文文本模式，可加：
+
+```bash
+./Tools_scripts_XunFei-Ubuntu/synthesize_xfyun_super_tts.sh \
+  --script 配音稿.md \
+  --output-dir 02_audio/super_tts_raw \
+  --raw-text
+```
+
+## 7. 声音和语速选择
+
+- `--voice`：讯飞发音人，也就是 `vcn`。
+- `--speed`：语速，通常 `0-100`，默认 `50`。
+- `--volume`：音量，通常 `0-100`，默认 `70`。
+- `--pitch`：音调，通常 `0-100`，默认 `50`。
+- `--overwrite`：覆盖已存在的音频文件。
+
+建议：
+
+- 系统介绍：优先用超拟人 TTS，例如 `x5_lingfeiyi_flow`。
+- 快速校稿：使用普通 TTS，例如 `xiaoyan`。
+- 需要缩短成片时长：先压缩文案，再把 `--speed` 调到 `55-60`。
+
+## 8. 检查音频时长
+
+```bash
+./Tools_scripts_XunFei-Ubuntu/check_audio_duration.sh 02_audio/super_tts_x5_lingfeiyi
+```
+
+如果总时长过长：
+
+- 优先删减配音稿。
+- 其次略微提高 `--speed`。
+- 最后再调整视频变速。
+
+不建议为了追赶过长旁白而大幅加速视频，否则画面会不自然。
+
+## 9. 合成最终视频
+
+如果已有一个完整录屏和一组分段配音：
+
+```bash
+python3 Tools_scripts_XunFei-Ubuntu/build_final_video_ubuntu.py \
+  --video 待配音视频/ISISeg-介入导丝视频分割工作台-使用展示.mp4 \
+  --audio-dir 02_audio/super_tts_x5_lingfeiyi \
+  --output 05_outputs/ISISeg-系统使用视频-配音版.mp4
+```
+
+如果已经有合并好的单个旁白音频：
+
+```bash
+python3 Tools_scripts_XunFei-Ubuntu/build_final_video_ubuntu.py \
+  --video input.mp4 \
+  --audio voiceover.mp3 \
+  --output 05_outputs/final_voiceover.mp4
+```
+
+脚本会：
+
+- 用 `ffprobe` 读取视频和旁白时长。
+- 自动计算画面变速系数。
+- 静音原视频音轨，只保留新旁白。
+- 输出 H.264/AAC、yuv420p、faststart MP4。
+
+常用参数：
+
+- `--width 1920 --height 1080`：输出分辨率。
+- `--fps 30`：输出帧率。
+- `--silence 0.35`：多段配音之间插入的静音秒数。
+- `--video-speed 1.25`：手动指定画面速度，覆盖自动计算。
+
+## 10. Agent 执行清单
+
+1. 确认 `Tools_scripts_XunFei-Ubuntu` 存在。
+2. 检查 `ffmpeg`、`ffprobe`、`python3` 是否可用。
+3. 安装 `requirements-ubuntu.txt` 中的依赖。
+4. 检查 `XF_APPID`、`XF_APIKEY`、`XF_APISECRET`。
+5. 创建或读取配音稿，并用 `--dry-run` 校验分段。
+6. 根据场景选择普通 TTS 或超拟人 TTS。
+7. 设置独立输出目录，避免覆盖不同声音和语速的试听结果。
+8. 生成音频后运行 `check_audio_duration.sh`。
+9. 用 `build_final_video_ubuntu.py` 合成最终视频。
+10. 用 `ffprobe` 检查最终视频时长、编码和音频流。
+
+## 11. 常见问题
+
+### Missing dependency: websocket-client
+
+运行：
+
+```bash
+python3 -m pip install -r Tools_scripts_XunFei-Ubuntu/requirements-ubuntu.txt
+```
+
+### Please set XF_APPID, XF_APIKEY and XF_APISECRET first
+
+说明当前终端没有讯飞凭证环境变量。设置后重新执行脚本：
+
+```bash
+export XF_APPID="你的AppId"
+export XF_APIKEY="你的ApiKey"
+export XF_APISECRET="你的ApiSecret"
+```
+
+### Cannot find script Markdown file
+
+请使用 `--script 配音稿.md` 显式指定配音稿。
+
+### ffmpeg 或 ffprobe 不存在
+
+运行：
+
+```bash
+sudo apt install -y ffmpeg
+```