6.3 KiB
6.3 KiB
配音生成工作流 Ubuntu Agent
本文档用于指导 Agent 在 Ubuntu 环境中使用 Tools_scripts_XunFei-Ubuntu，将配音稿文字转为讯飞配音音频，并与视频合成为最终介绍视频。
1. 目录约定
建议保持以下结构：
项目目录/
配音稿.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. 安装依赖
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
如果使用虚拟环境：
python3 -m venv .venv-tts
source .venv-tts/bin/activate
python -m pip install -r Tools_scripts_XunFei-Ubuntu/requirements-ubuntu.txt
3. 配置讯飞环境变量
export XF_APPID="你的AppId"
export XF_APIKEY="你的ApiKey"
export XF_APISECRET="你的ApiSecret"
如需长期生效，可以写入 ~/.bashrc：
cat >> ~/.bashrc <<'EOF'
export XF_APPID="你的AppId"
export XF_APIKEY="你的ApiKey"
export XF_APISECRET="你的ApiSecret"
EOF
source ~/.bashrc
脚本不会保存密钥，也不要把真实密钥写入仓库。
4. 配音稿格式
脚本识别 Markdown 中的分段标题：
## 1. 第一段标题
第一段配音正文。
## 2. 第二段标题
第二段配音正文。
## 3. 第三段标题
第三段配音正文。
## 4. 第四段标题
第四段配音正文。
注意：
- 标题建议保持
## 1.到## 4.。 - 输出文件名会使用段号和标题，例如
1-第一段标题.mp3。 说明：、时长：、备注：、镜头：、画面：等元信息行会被忽略。- 正文只放最终朗读内容，不要放内部提示词。
可先做干跑检查：
python3 Tools_scripts_XunFei-Ubuntu/xfyun_tts_ubuntu.py \
--script 配音稿.md \
--dry-run
5. 普通 TTS 合成
普通 TTS 适合快速生成清晰稳定的中文配音。
./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 更适合项目汇报、系统介绍和宣传片。
./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
如果接口要求明文文本模式，可加：
./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. 检查音频时长
./Tools_scripts_XunFei-Ubuntu/check_audio_duration.sh 02_audio/super_tts_x5_lingfeiyi
如果总时长过长：
- 优先删减配音稿。
- 其次略微提高
--speed。 - 最后再调整视频变速。
不建议为了追赶过长旁白而大幅加速视频，否则画面会不自然。
9. 合成最终视频
如果已有一个完整录屏和一组分段配音：
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
如果已经有合并好的单个旁白音频：
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 执行清单
- 确认
Tools_scripts_XunFei-Ubuntu存在。 - 检查
ffmpeg、ffprobe、python3是否可用。 - 安装
requirements-ubuntu.txt中的依赖。 - 检查
XF_APPID、XF_APIKEY、XF_APISECRET。 - 创建或读取配音稿，并用
--dry-run校验分段。 - 根据场景选择普通 TTS 或超拟人 TTS。
- 设置独立输出目录，避免覆盖不同声音和语速的试听结果。
- 生成音频后运行
check_audio_duration.sh。 - 用
build_final_video_ubuntu.py合成最终视频。 - 用
ffprobe检查最终视频时长、编码和音频流。
11. 常见问题
Missing dependency: websocket-client
运行：
python3 -m pip install -r Tools_scripts_XunFei-Ubuntu/requirements-ubuntu.txt
Please set XF_APPID, XF_APIKEY and XF_APISECRET first
说明当前终端没有讯飞凭证环境变量。设置后重新执行脚本：
export XF_APPID="你的AppId"
export XF_APIKEY="你的ApiKey"
export XF_APISECRET="你的ApiSecret"
Cannot find script Markdown file
请使用 --script 配音稿.md 显式指定配音稿。
ffmpeg 或 ffprobe 不存在
运行：
sudo apt install -y ffmpeg