# 配音生成工作流 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
```