2026-05-19-00-11-40 新增Ubuntu配音工作流

工程分析/实现方案-2026-05-19-00-11-40.md

@@ -0,0 +1,31 @@
+# 实现方案
+
+开始时间：2026-05-19-00-11-40
+
+## Ubuntu 工具目录
+
+新增 `Tools_scripts_XunFei-Ubuntu/`：
+
+- `requirements-ubuntu.txt`：Ubuntu 脚本所需 Python 依赖。
+- `xfyun_tts_ubuntu.py`：核心讯飞 TTS 脚本，支持普通 TTS 与超拟人 TTS。
+- `synthesize_xfyun_tts.sh`：普通 TTS Bash 包装入口。
+- `synthesize_xfyun_super_tts.sh`：超拟人 TTS Bash 包装入口。
+- `check_audio_duration.sh`：检查音频时长的小工具。
+- `build_final_video_ubuntu.py`：将单个视频与配音音频合成为最终视频，并根据配音时长自动调整画面速度。
+
+## Ubuntu 工作流文档
+
+新增 `配音生成工作流-Ubuntu-Agent.md`：
+
+- 说明目录结构、依赖安装和环境变量配置。
+- 说明配音稿格式。
+- 给出普通 TTS、超拟人 TTS、音频时长检查、视频合成的命令示例。
+- 给出 Agent 执行清单和常见问题。
+
+## 实现要点
+
+- Python TTS 脚本通过 HMAC-SHA256 生成讯飞 WebSocket 鉴权 URL。
+- 配音稿解析兼容 `## 1.` 到 `## 4.` 分段格式。
+- `--dry-run` 可在无讯飞凭证时验证配音稿解析结果。
+- 视频合成脚本使用 `ffprobe` 计算视频与音频时长，并用 `setpts=PTS/speed` 让画面匹配旁白。
+- 输出视频使用 H.264/AAC、yuv420p、faststart，保证浏览器兼容。

工程分析/测试方案-2026-05-19-00-11-40.md

@@ -0,0 +1,42 @@
+# 测试方案
+
+开始时间：2026-05-19-00-11-40
+
+## 静态检查
+
+- `python3 -m py_compile Tools_scripts_XunFei-Ubuntu/xfyun_tts_ubuntu.py Tools_scripts_XunFei-Ubuntu/build_final_video_ubuntu.py`
+- `bash -n Tools_scripts_XunFei-Ubuntu/synthesize_xfyun_tts.sh`
+- `bash -n Tools_scripts_XunFei-Ubuntu/synthesize_xfyun_super_tts.sh`
+- `bash -n Tools_scripts_XunFei-Ubuntu/check_audio_duration.sh`
+
+执行结果：全部通过。
+
+## 功能检查
+
+- 使用临时 Markdown 配音稿运行 `xfyun_tts_ubuntu.py --dry-run`，确认能解析 4 段。
+- 使用 ffmpeg 生成临时测试视频与音频，运行 `build_final_video_ubuntu.py`，确认能输出 H.264/AAC 成片。
+- 用 `ffprobe` 检查测试成片时长、编码和音频流。
+
+执行结果：
+
+- `xfyun_tts_ubuntu.py --dry-run` 可解析 4 段配音稿。
+- 已安装并验证 `websocket-client=1.9.0`。
+- 无讯飞凭证时脚本会在解析配音稿后明确提示 `Please set XF_APPID, XF_APIKEY and XF_APISECRET first.` 并退出。
+- `build_final_video_ubuntu.py` 使用临时测试视频和两段测试音频生成成片成功。
+- 测试成片信息：H.264 视频、AAC 音频，320x180，约 2.55 秒。
+- `check_audio_duration.sh` 可列出测试音频时长。
+
+## 仓库检查
+
+- `git diff --check`
+- `git status --short`
+
+执行结果：
+
+- `git diff --check` 通过。
+- 待提交内容仅包含 Ubuntu 工具目录、Ubuntu 工作流文档和工程分析文档。
+
+## 部署检查
+
+- 本次主要新增文档和脚本，不改变 Web 服务逻辑。
+- 按既有流程重新执行 `docker compose -f docker_compose_huijutec.yaml up -d --build` 并检查健康接口。

工程分析/经验记录.md

@@ -239,3 +239,35 @@ B. 产生问题原因：录屏展示节奏偏慢，而旁白文案按介绍视
 C. 解决问题方案：用 `ffprobe` 计算原视频和旁白时长，按 `85.636 / 64.272 = 1.332400` 对视频做轻度变速，原始音频静音并替换为新旁白，输出 H.264/AAC 兼容格式。
 
 D. 后续如何避免问题：合成介绍视频时先确定旁白时长，再用可接受的变速范围调整画面；如果变速超过自然范围，应优先重新剪辑画面而不是强行加速。
+
+## 2026-05-19-00-11-40 Ubuntu 配音工作流
+
+### 1. PowerShell 配音脚本不能直接作为 Ubuntu 工作流
+
+A. 具体问题：原有讯飞配音脚本是 PowerShell 版本，Ubuntu 环境直接执行门槛高，且命令示例不符合 Linux 用户习惯。
+
+B. 产生问题原因：早期工作流面向 Windows/PowerShell，脚本入口、环境变量设置、路径写法和执行权限都与 Ubuntu 不同。
+
+C. 解决问题方案：新增 `Tools_scripts_XunFei-Ubuntu`，用 Bash 包装入口和 Python WebSocket 客户端实现普通 TTS、超拟人 TTS、音频时长检查和视频合成；新增 `配音生成工作流-Ubuntu-Agent.md` 写明 Ubuntu 安装与执行步骤。
+
+D. 后续如何避免问题：跨平台工作流应分开维护平台入口文档，不要只替换命令片段；至少要覆盖依赖安装、环境变量、执行权限和常见错误。
+
+### 2. 无凭证环境下也需要可测试脚本
+
+A. 具体问题：讯飞 TTS 真实请求需要 `XF_APPID`、`XF_APIKEY`、`XF_APISECRET`，没有凭证时无法验证配音稿解析和脚本基础逻辑。
+
+B. 产生问题原因：TTS 网络请求和配音稿解析原本耦合在一起，缺少离线检查路径。
+
+C. 解决问题方案：在 `xfyun_tts_ubuntu.py` 中加入 `--dry-run`，先解析配音稿并输出段落计划；只有真正合成时才检查讯飞凭证和发起 WebSocket 请求。
+
+D. 后续如何避免问题：依赖外部账号、网络或付费接口的脚本都应提供 dry-run 或 validate 模式，方便在无凭证环境完成结构校验。
+
+### 3. Ubuntu 视频合成需要避免编码兼容问题
+
+A. 具体问题：不同来源的音频段可能编码、采样率和声道数不一致，直接 concat 容易失败或生成不可播放音轨。
+
+B. 产生问题原因：ffmpeg concat demuxer 要求输入流参数一致，多段 TTS 音频不一定完全相同。
+
+C. 解决问题方案：`build_final_video_ubuntu.py` 在合并音频目录时先把每段音频统一转为 48kHz 双声道 PCM WAV，再拼接并与视频合成，最终输出 H.264/AAC MP4。
+
+D. 后续如何避免问题：多段音频拼接前先标准化采样率、声道和编码；最终成片统一使用 H.264/AAC/yuv420p/faststart。

工程分析/需求分析-2026-05-19-00-11-40.md

@@ -0,0 +1,29 @@
+# 需求分析
+
+开始时间：2026-05-19-00-11-40
+
+## 用户需求
+
+新建一套适用于 Ubuntu 的配音工具与工作流文档：
+
+- `Tools_scripts_XunFei-Ubuntu`
+- `配音生成工作流-Ubuntu-Agent.md`
+
+## 现状
+
+- 现有 `待配音视频/Tools_scripts_XunFei` 目录中的脚本为 PowerShell 版本，主要适用于 Windows 或已安装 PowerShell 的环境。
+- 现有工作流文档以 PowerShell 命令为主，不适合 Ubuntu 直接照抄执行。
+- Ubuntu 环境更适合使用 Bash + Python + ffmpeg 的组合。
+
+## 目标
+
+- 提供 Ubuntu 可执行的讯飞普通 TTS 与超拟人 TTS 脚本。
+- 保留原工作流中的配音稿格式、声音选择、语速控制、音频时长检查与视频合成步骤。
+- 提供单视频换配音并自动按旁白调整画面速度的视频合成脚本。
+- 新文档明确依赖安装、环境变量配置、常用命令、测试方式和常见问题。
+
+## 约束
+
+- 不在脚本中写入任何讯飞密钥。
+- 通过 `XF_APPID`、`XF_APIKEY`、`XF_APISECRET` 环境变量读取凭证。
+- 生成音频和视频的输出目录由用户指定，避免覆盖已有结果。