From 8b4cff819719544ebeae613177ebad8958ebf8d7 Mon Sep 17 00:00:00 2001
From: admin <572701190@qq.com>
Date: Thu, 21 May 2026 16:04:26 +0800
Subject: [PATCH] =?UTF-8?q?2026-05-21-15-50-21=20=E8=AE=B0=E5=BD=95?=
 =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E4=BD=BF=E7=94=A8=E8=A7=86=E9=A2=91=E9=85=8D?=
 =?UTF-8?q?=E9=9F=B3=E7=94=9F=E6=88=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 工程分析/实现方案-2026-05-21-15-50-21.md | 55 ++++++++++++++++
 工程分析/测试方案-2026-05-21-15-50-21.md | 84 ++++++++++++++++++++++++
 工程分析/经验记录.md                     | 18 +++++
 工程分析/需求分析-2026-05-21-15-50-21.md | 57 ++++++++++++++++
 4 files changed, 214 insertions(+)
 create mode 100644 工程分析/实现方案-2026-05-21-15-50-21.md
 create mode 100644 工程分析/测试方案-2026-05-21-15-50-21.md
 create mode 100644 工程分析/需求分析-2026-05-21-15-50-21.md

diff --git a/工程分析/实现方案-2026-05-21-15-50-21.md b/工程分析/实现方案-2026-05-21-15-50-21.md
new file mode 100644
index 0000000..f1de962
--- /dev/null
+++ b/工程分析/实现方案-2026-05-21-15-50-21.md
@@ -0,0 +1,55 @@
+# 实现方案：系统使用视频配音版生成
+
+实现方案文档路径：`工程分析/实现方案-2026-05-21-15-50-21.md`
+
+## 修改目标
+
+生成 5 分钟版和 10 分钟版系统使用视频的中文配音成片，并保证音视频最终时长一致。
+
+## 涉及路径
+
+- `视频配音/基于模型逆向体素化及DICOM分割标注系统-使用视频-5min版.mp4`
+- `视频配音/基于模型逆向体素化及DICOM分割标注系统-使用视频-10min版.mp4`
+- `视频配音/配音生成工作流-Ubuntu-Agent.md`
+- `视频配音/Tools_scripts_XunFei-Ubuntu/`
+- `视频配音/01_scripts/`
+- `视频配音/02_audio/`
+- `视频配音/04_intermediate/`
+- `视频配音/05_outputs/`
+
+## 技术路线
+
+1. 使用 `ffprobe` 获取两个视频的准确时长、分辨率、帧率和音轨信息。
+2. 抽样生成 contact sheet，快速阅览视频内容与操作流程。
+3. 根据画面内容分别撰写 5 分钟和 10 分钟配音稿。
+4. 优先检查讯飞 TTS 环境变量；当前环境缺少讯飞凭证时，使用已安装的 `edge-tts` 生成中文 MP3。
+5. 将 TTS 音频规范化为 48kHz stereo WAV。
+6. 使用 `ffmpeg` 通过 `apad` 与 `atrim` 将旁白音频严格对齐视频时长。
+7. 将原视频静音并合入新旁白，输出 H.264/AAC MP4。
+8. 使用 `ffprobe` 校验最终视频格式、音轨和时长差。
+
+## 执行步骤
+
+- 创建配音工作子目录。
+- 写入 `配音稿-5min.md` 与 `配音稿-10min.md`。
+- 对配音稿做 TTS 干跑或等效段落检查。
+- 使用 `edge-tts` 分别生成原始旁白音频。
+- 根据视频时长生成对齐后的 WAV 音轨。
+- 用 `ffmpeg -map 0:v:0 -map 1:a:0 -shortest` 合成配音版视频。
+- 对原始视频、旁白音频、对齐音频和最终视频做时长比对。
+
+## 兼容性与回滚方案
+
+- 原始视频不修改，输出文件单独放在 `05_outputs/`。
+- 如后续提供讯飞凭证，可复用配音稿重新运行 `Tools_scripts_XunFei-Ubuntu` 的讯飞脚本生成更接近指定工作流的音色。
+- 若用户希望调整语气或文案，只需改 `01_scripts/` 下对应配音稿并重新生成音频与合成视频。
+
+## 预计文件变更
+
+- 新增视频配音脚本、音频、最终视频和校验记录。
+- 新增三份工程分析文档并追加 `经验记录.md`。
+
+## 提交与部署策略
+
+- 本次不需要重新部署 WebSite，因为不修改程序服务。
+- 按工作流提交工程分析文档备份，避免把大体积视频产物混入 Git 提交。
diff --git a/工程分析/测试方案-2026-05-21-15-50-21.md b/工程分析/测试方案-2026-05-21-15-50-21.md
new file mode 100644
index 0000000..af4cb08
--- /dev/null
+++ b/工程分析/测试方案-2026-05-21-15-50-21.md
@@ -0,0 +1,84 @@
+# 测试方案：系统使用视频配音版生成
+
+测试方案文档路径：`工程分析/测试方案-2026-05-21-15-50-21.md`
+
+## 静态检查
+
+- 检查原始视频是否存在且可被 `ffprobe` 识别。
+- 检查 `ffmpeg`、`ffprobe`、`python3`、TTS 工具是否可用。
+- 检查输出目录不覆盖原始视频。
+
+## 构建检查
+
+- 本次不涉及前端或后端构建。
+- 以音视频合成为构建动作，检查 `ffmpeg` 命令是否成功退出。
+
+## 关键业务场景验证
+
+- 5 分钟版视频生成带配音成片。
+- 10 分钟版视频生成带配音成片。
+- 原视频音轨被替换，不出现原声与旁白叠加。
+- 最终视频能被 `ffprobe` 识别为 H.264/AAC MP4。
+
+## 医学影像数据相关边界验证
+
+- 配音内容围绕 DICOM 影像、STL 模型、逆向分割映射、构件层级、位姿调整、项目库、导出和系统管理等功能展开。
+- 不在配音中暗示该演示系统已经完成真实临床诊断或自动诊断结论。
+
+## 音视频对齐验证
+
+- 读取原始视频时长。
+- 读取原始 TTS 音频时长。
+- 读取对齐后音频时长。
+- 读取最终配音视频时长。
+- 要求最终视频和最终音频流时长误差控制在 0.1 秒以内。
+
+## 部署验证
+
+- 本次不重新部署 WebSite。
+- 如需服务状态佐证，可读取当前健康接口。
+
+## Git/Gitea 备份验证
+
+- 只提交本次工程分析文档和经验记录。
+- 不把大体积 MP4/音频产物加入 Git。
+
+## 风险与回归关注点
+
+- 若 TTS 音频明显短于视频，通过 `apad` 补齐会在结尾产生无声段；需尽量让配音稿长度接近视频时长。
+- 若 TTS 音频长于视频，则通过 `atrim` 裁切会截断尾句；生成后需检查原始音频与目标时长差。
+- 合成后必须确认音频流存在，不能只检查视频文件存在。
+
+## 实际验证结果
+
+- 已确认 `ffmpeg`、`ffprobe`、`python3` 可用。
+- 当前环境未配置 `XF_APPID`、`XF_APIKEY`、`XF_APISECRET`，无法直接调用讯飞 TTS；本机已安装 `edge-tts`，本次使用 `zh-CN-XiaoxiaoNeural` 作为替代中文 TTS 引擎。
+- 已抽样生成并阅览 contact sheet：
+  - `视频配音/00_review_frames/5min_contact.jpg`
+  - `视频配音/00_review_frames/10min_contact.jpg`
+- 已生成配音稿与 TTS 文本：
+  - `视频配音/01_scripts/配音稿-5min版.md`
+  - `视频配音/01_scripts/配音稿-10min版.md`
+  - `视频配音/01_scripts/配音文本-5min版.txt`
+  - `视频配音/01_scripts/配音文本-10min版.txt`
+- 原始视频信息：
+  - 5min 版：视频流 `297.500s`，容器 `297.600s`，`1920x1080`，`50fps`。
+  - 10min 版：视频流 `594.980s`，容器 `595.072s`，`1920x1080`，`50fps`。
+- 原始 TTS 音频：
+  - 5min 版：`298.080s`，使用 `edge-tts --rate=-1%`。
+  - 10min 版：`592.632s`，使用 `edge-tts --rate=+1%`。
+- 为避免视频流结束后仍有声音，最终以视频流时长作为对齐目标，而不是容器时长：
+  - 5min 版 `atempo=1.00194958`，对齐后音轨 `297.500s`。
+  - 10min 版 `atempo=0.99605365`，对齐后音轨 `594.980s`。
+- 已生成最终配音视频：
+  - `视频配音/05_outputs/基于模型逆向体素化及DICOM分割标注系统-使用视频-5min版-配音版.mp4`
+  - `视频配音/05_outputs/基于模型逆向体素化及DICOM分割标注系统-使用视频-10min版-配音版.mp4`
+- `ffprobe` 校验最终视频：
+  - 5min 版：H.264 视频流 `297.500s`，AAC 音频流 `297.500s`，误差 `0.000s`。
+  - 10min 版：H.264 视频流 `594.980s`，AAC 音频流 `594.980s`，误差 `0.000s`。
+- `ffmpeg -v error -f null -` 解码检查：
+  - 5min 版通过。
+  - 10min 版通过。
+- 已写入校验记录：
+  - `视频配音/06_reports/配音生成校验-2026-05-21-15-50-21.md`
+- 本次仅生成视频配音产物，不修改 WebSite 服务代码；因此不重启服务，避免影响当前 Docker 访问。
diff --git a/工程分析/经验记录.md b/工程分析/经验记录.md
index 705c0f0..e7f9fbc 100644
--- a/工程分析/经验记录.md
+++ b/工程分析/经验记录.md
@@ -1567,3 +1567,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 后续同一版本存在多个部署形态、系统架构或环境模板时，优先使用“一个 Release + 多个命名附件”的发布模型；只有当版本号、功能内容或源码状态确实不同，才拆成多个 Release。删除旧 Release 前必须先确认新 Release 的附件数量、名称和大小均已从 Gitea API 读回，避免页面清理造成发布物短暂缺失。
+
+## 2026-05-21-15-50-21 视频配音应以视频流时长对齐而非容器时长
+
+A. 具体问题
+
+用户要求为 5 分钟版和 10 分钟版系统使用视频生成配音版，并明确不能出现视频结束后仍有声音，或声音结束后视频继续播放。原始 MP4 的容器时长与视频流时长存在约 0.1 秒差异，如果直接按容器时长对齐音频，末尾可能出现极短的音频尾巴。
+
+B. 产生问题原因
+
+MP4 容器时长通常取所有流的最大持续时间，原始录屏中音频流和容器时长略长于视频流。配音合成时如果只读取 `format=duration`，会把旁白音轨拉到容器时长；播放器显示上虽然总时长一致，但最后一帧之后仍可能存在很短音频区间，不符合“视频结束不要还有声音”的交付要求。
+
+C. 解决问题方案
+
+先用 `ffprobe` 分别读取视频流时长、容器时长和音频时长，再以 `v:0` 视频流时长作为最终目标。TTS 原始音频与目标时长差距较小时，使用 `ffmpeg atempo` 做小幅伸缩，并用 `apad + atrim` 精确裁定到视频流时长。最终合成时只映射原视频流和新配音音轨，去除原始音轨，并再次用 `ffprobe` 验证视频流和音频流时长完全一致。
+
+D. 后续如何避免问题
+
+后续生成配音、字幕或二次包装视频时，不能只看 MP4 容器总时长；必须同时检查视频流和音频流时长。若目标是避免片尾空声，应以视频流时长为准；若目标是保留完整旁白，则需要明确允许画面补帧或拉伸。大幅时长差不要依赖静音填充，应优先调整文案长度和 TTS 语速，再做细微 `atempo` 对齐。
diff --git a/工程分析/需求分析-2026-05-21-15-50-21.md b/工程分析/需求分析-2026-05-21-15-50-21.md
new file mode 100644
index 0000000..db10eda
--- /dev/null
+++ b/工程分析/需求分析-2026-05-21-15-50-21.md
@@ -0,0 +1,57 @@
+# 需求分析：系统使用视频配音版生成
+
+开始时间：2026-05-21-15-50-21
+
+## 原始需求摘要
+
+用户要求阅读 `视频配音/` 中两个当前系统使用视频：
+
+- `基于模型逆向体素化及DICOM分割标注系统-使用视频-5min版.mp4`
+- `基于模型逆向体素化及DICOM分割标注系统-使用视频-10min版.mp4`
+
+并参考 `配音生成工作流-Ubuntu-Agent.md` 生成带配音的最终视频。要求配音文本、音频与视频长度一致，避免出现视频结束后仍有声音，或声音结束后视频继续播放的情况。
+
+## 业务目标
+
+- 为 5 分钟版和 10 分钟版系统使用视频生成中文旁白。
+- 输出两个带配音的 MP4 成片。
+- 最终成片音轨与画面时长严格对齐。
+- 生成过程保留配音稿、音频和校验记录，便于后续复用与调整。
+
+## 输入与输出
+
+输入：
+
+- 两个原始系统使用视频。
+- `视频配音/配音生成工作流-Ubuntu-Agent.md`。
+- `视频配音/Tools_scripts_XunFei-Ubuntu/` 中的配音与合成工具。
+
+输出：
+
+- 5 分钟版配音稿、音频和配音成片。
+- 10 分钟版配音稿、音频和配音成片。
+- 本次工程分析记录与测试结果。
+
+## 影响范围
+
+- 新增 `视频配音/` 下的配音稿、音频、中间文件和最终视频。
+- 新增本次 `工程分析/` 文档，追加经验记录。
+- 不修改 WebSite 业务代码。
+
+## 关键约束
+
+- 不覆盖原始视频。
+- 最终视频需去除原视频声音，只保留新旁白。
+- 音频总时长必须和输出视频时长一致。
+- 当前环境没有 `XF_APPID`、`XF_APIKEY`、`XF_APISECRET`，若无法调用讯飞 TTS，则使用本机可用中文 TTS 方案完成交付，并记录偏差。
+
+## 风险点
+
+- TTS 服务网络或凭证不可用导致无法按讯飞流程生成。
+- 旁白文案长度与视频长度差距过大，会导致音频拉伸或静音过多。
+- 大视频合成耗时较长，需用 `ffprobe` 校验最终时长和音轨。
+
+## 默认假设
+
+- 允许在讯飞凭证缺失时使用本机已有 `edge-tts` 作为替代 TTS 引擎。
+- 输出视频可放在 `视频配音/05_outputs/`，无需覆盖原始视频。