2026-05-19-00-28-03 记录配音工具移除校验

.dockerignore

@@ -10,6 +10,9 @@ release_packages
 packaging_build
 storage/jobs
 storage/uploads
+待配音视频
+Tools_scripts_XunFei-Ubuntu
+配音生成工作流-Ubuntu-Agent.md
 storage/**/*.raw.mp4
 *.tar.gz
 *.zip

.gitignore

@@ -10,6 +10,9 @@ data/
 storage/jobs/
 storage/uploads/
 storage/demos/
+待配音视频/
+Tools_scripts_XunFei-Ubuntu/
+配音生成工作流-Ubuntu-Agent.md
 packaging_build/
 release_packages/
 *.log

工程分析/实现方案-2026-05-18-23-35-23.md

@@ -0,0 +1,35 @@
+# 实现方案
+
+开始时间：2026-05-18-23-35-23
+
+## 忽略策略
+
+- 在 `.gitignore` 中加入 `待配音视频/`，确保原始视频、配音音频、中间文件和最终成片都不会进入 Gitea。
+- 在 `.dockerignore` 中加入 `待配音视频`，避免后续 Docker 构建上下文夹带大视频素材。
+
+## 配音稿
+
+- 按 `配音生成工作流-Agent.md` 要求创建 4 段式配音稿：
+  - 系统定位与价值。
+  - 上传样例和双视频预览。
+  - 运行分割、帧级结果和多方法对比。
+  - Docker/公网访问与总结。
+- 文案控制在约 1 分钟可朗读长度。
+
+## TTS 生成
+
+- 优先检查讯飞环境变量与 PowerShell 可用性。
+- 当前环境不满足讯飞脚本运行条件时，使用 Linux 可运行的中文 TTS 生成 mp3。
+- 生成后使用 `ffprobe` 检查配音时长。
+
+## 视频处理
+
+- 将原始 85.6 秒视频按配音目标时长进行轻度变速，使最终成片约 60 秒。
+- 使用 H.264/AAC、yuv420p 和 faststart 输出，保证浏览器和常见播放器兼容。
+- 原始录屏音频静音，仅保留新配音，避免两路声音叠加。
+
+## 输出路径
+
+- 配音稿：`待配音视频/配音稿-ISISeg系统使用视频.md`
+- 配音音频：`待配音视频/02_audio/...`
+- 最终成片：`待配音视频/05_outputs/ISISeg-系统使用视频-配音版.mp4`

工程分析/实现方案-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-28-03.md

@@ -0,0 +1,23 @@
+# 实现方案
+
+开始时间：2026-05-19-00-28-03
+
+## Git 跟踪处理
+
+- 保持 `Tools_scripts_XunFei-Ubuntu/` 与 `配音生成工作流-Ubuntu-Agent.md` 的删除状态。
+- 提交删除记录，使 Gitea 最新 `main` 不再包含这些本地配音工具。
+
+## 忽略规则
+
+- `.gitignore` 增加：
+  - `Tools_scripts_XunFei-Ubuntu/`
+  - `配音生成工作流-Ubuntu-Agent.md`
+- `.dockerignore` 增加：
+  - `Tools_scripts_XunFei-Ubuntu`
+  - `配音生成工作流-Ubuntu-Agent.md`
+
+## 校验
+
+- 使用 `git check-ignore` 验证三个路径都被忽略。
+- 使用 `git status --short` 确认待提交内容只包含删除、忽略规则与工程分析文档。
+- 推送到 Gitea 后重新部署并检查健康接口。

工程分析/测试方案-2026-05-18-22-23-07.md

@@ -48,3 +48,22 @@
 - 创建 release。
 - 上传三个附件。
 - 查询 release 附件列表确认三个包均存在。
+
+执行结果：
+
+- main 已推送到 Gitea。
+- tag 已推送：`v2026-05-18-22-23-07-docker-packages`。
+- release 已创建：`http://192.168.31.5:5002/admin/ISISeg/releases/tag/v2026-05-18-22-23-07-docker-packages`。
+- release 附件查询结果为 3 个：
+  - `isiseg-clean-install-2026-05-18-22-23-07.tar.gz`，895561 bytes。
+  - `isiseg-huijutec-direct-2026-05-18-22-23-07.tar.gz`，895096 bytes。
+  - `isiseg-qnap-nas-2026-05-18-22-23-07.tar.gz`，895352 bytes。
+
+## 重新部署校验
+
+- 执行 `docker compose -f docker_compose_huijutec.yaml up -d --build`。
+- `isiseg_app` 状态为 healthy，本机映射为 `0.0.0.0:10004->8001/tcp`。
+- 本机 `http://127.0.0.1:10004/api/health` 返回 `{"status":"ok","service":"ISISeg","version":"0.1.0"}`。
+- frpc 日志显示 `proxy added: [ISISeg]` 和 `start proxy success`。
+- 公网 `https://isiseg.huijutec.cn/api/health` 返回健康状态。
+- 公网 `https://isiseg.huijutec.cn/` 使用 GET 返回首页 HTML，HTTP 200。

工程分析/测试方案-2026-05-18-23-35-23.md

@@ -0,0 +1,52 @@
+# 测试方案
+
+开始时间：2026-05-18-23-35-23
+
+## Git 忽略校验
+
+- `git check-ignore -v 待配音视频/ISISeg-介入导丝视频分割工作台-使用展示.mp4`
+- `git status --short` 确认 `待配音视频` 内容不出现在待提交列表。
+- 检查 `.dockerignore` 包含 `待配音视频`。
+
+执行结果：
+
+- `待配音视频/` 命中 `.gitignore` 第 13 行规则。
+- `.dockerignore` 已加入 `待配音视频`。
+- 原始视频、旁白音频和最终成片均不会进入 Gitea 提交。
+
+## 音视频校验
+
+- `ffprobe` 检查原始视频时长、分辨率、编码。
+- `ffprobe` 检查配音音频时长。
+- `ffprobe` 检查最终视频时长、分辨率、视频编码和音频编码。
+- 使用 `ffmpeg` 抽取最终视频首帧或关键帧，确认画面非空。
+
+执行结果：
+
+- 原始视频：1920x1080、HEVC、50fps、约 85.636 秒。
+- 旁白音频：4 段中文配音合成为 64.272 秒。
+- 视频变速系数：`1.332400`，将 85.636 秒录屏压缩到旁白时长。
+- 最终视频：1920x1080、H.264、30fps、AAC，约 64.234 秒。
+- 最终视频完整解码通过：`decode-ok`。
+- 音量检查：平均音量约 `-30.0 dB`，峰值约 `-5.4 dB`，音轨非静音。
+- 已抽取中间帧查看，画面为系统工作台界面，非空白。
+
+## 交付校验
+
+- 最终视频存在于 `待配音视频/05_outputs`。
+- 最终视频时长约 1 分钟。
+- Gitea 提交只包含 `.gitignore` 与工程分析文档，不包含 `待配音视频`。
+
+执行结果：
+
+- 最终成片：`待配音视频/05_outputs/ISISeg-系统使用视频-配音版.mp4`。
+- 旁白音频：`待配音视频/02_audio/final_mix/ISISeg-系统使用视频-旁白.mp3`。
+- 配音稿：`待配音视频/配音稿-ISISeg系统使用视频.md`。
+
+## 重新部署校验
+
+- 执行 `docker compose -f docker_compose_huijutec.yaml up -d --build`。
+- Docker 构建上下文约 1.12kB，确认未夹带 `待配音视频` 大文件。
+- `isiseg_app` 状态为 healthy，本机映射为 `0.0.0.0:10004->8001/tcp`。
+- 本机 `http://127.0.0.1:10004/api/health` 返回健康状态。
+- 公网 `https://isiseg.huijutec.cn/api/health` 返回健康状态。

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

@@ -0,0 +1,49 @@
+# 测试方案
+
+开始时间：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` 并检查健康接口。
+
+执行结果：
+
+- Docker 镜像重新构建成功，Web 服务容器重新创建。
+- `isiseg_app` 状态为 healthy，端口映射为 `0.0.0.0:10004->8001/tcp`。
+- 本机 `http://127.0.0.1:10004/api/health` 返回 `{"status":"ok","service":"ISISeg","version":"0.1.0"}`。
+- 公网 `https://isiseg.huijutec.cn/api/health` 返回同样健康状态。

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

@@ -0,0 +1,42 @@
+# 测试方案
+
+开始时间：2026-05-19-00-28-03
+
+## 忽略校验
+
+- `git check-ignore -v 待配音视频/任意文件`
+- `git check-ignore -v Tools_scripts_XunFei-Ubuntu/任意文件`
+- `git check-ignore -v 配音生成工作流-Ubuntu-Agent.md`
+
+执行结果：
+
+- `待配音视频/` 命中 `.gitignore` 第 13 行规则。
+- `Tools_scripts_XunFei-Ubuntu/` 命中 `.gitignore` 第 14 行规则。
+- `配音生成工作流-Ubuntu-Agent.md` 命中 `.gitignore` 第 15 行规则。
+- `.dockerignore` 也已加入这三个不需要进入构建上下文的路径。
+
+## Git 校验
+
+- `git diff --check`
+- `git status --short`
+- `git ls-files Tools_scripts_XunFei-Ubuntu 配音生成工作流-Ubuntu-Agent.md 待配音视频`
+
+执行结果：
+
+- `git diff --check` 通过。
+- `待配音视频/` 没有被 Git 跟踪。
+- `Tools_scripts_XunFei-Ubuntu/` 与 `配音生成工作流-Ubuntu-Agent.md` 曾在上一轮被纳入 Git，本次保持删除状态并提交删除，让 Gitea 最新 `main` 不再包含它们。
+- 删除提交并推送后，`git ls-files Tools_scripts_XunFei-Ubuntu 配音生成工作流-Ubuntu-Agent.md 待配音视频` 输出为空。
+
+## 部署校验
+
+- `docker compose -f docker_compose_huijutec.yaml up -d --build`
+- `curl -fsS http://127.0.0.1:10004/api/health`
+- `curl -fsS https://isiseg.huijutec.cn/api/health`
+
+执行结果：
+
+- Docker 镜像重新构建成功，`.dockerignore` 已生效。
+- `isiseg_app` 状态为 healthy，端口映射为 `0.0.0.0:10004->8001/tcp`。
+- 本机健康接口返回 `{"status":"ok","service":"ISISeg","version":"0.1.0"}`。
+- 公网健康接口 `https://isiseg.huijutec.cn/api/health` 返回同样健康状态。

工程分析/经验记录.md

@@ -207,3 +207,79 @@ B. 产生问题原因：自动化测试和 Docker 构建前已运行 Python 代
 C. 解决问题方案：重新打包时排除 `__pycache__`、`.pyc`、临时目录和发布目录，并新增 `.gitignore` 避免后续误提交。
 
 D. 后续如何避免问题：发布包生成后必须执行包内文件检查，至少确认无缓存、无临时目录、无本地数据和无敏感配置外泄。
+
+## 2026-05-18-23-35-23 使用视频配音与成片
+
+### 1. 待配音素材不能进入 Gitea
+
+A. 具体问题：`待配音视频` 下包含原始录屏、配音音频、中间文件和最终成片，文件体积较大且属于交付素材，不应上传到源码仓库。
+
+B. 产生问题原因：该目录不在原 `.gitignore` 中，后续如果手动 `git add .` 容易误提交视频素材。
+
+C. 解决问题方案：在 `.gitignore` 中加入 `待配音视频/`，并用 `git check-ignore` 校验原始视频、旁白音频和最终成片均被忽略。
+
+D. 后续如何避免问题：所有录屏、配音、导出视频和临时剪辑目录都应先加入忽略规则，再生成大文件，提交前必须查看 `git status --short`。
+
+### 2. 讯飞配音脚本运行条件不满足
+
+A. 具体问题：配音工作流文档默认使用讯飞 PowerShell 脚本，但当前环境未设置讯飞三项环境变量，也没有 PowerShell 运行时。
+
+B. 产生问题原因：该工作流来自 Windows/讯飞环境，当前执行环境是 Linux，缺少对应账号环境与脚本运行时。
+
+C. 解决问题方案：保留工作流中的四段式配音稿、TTS、时长检查和视频合成步骤；TTS 引擎替换为当前环境可运行的中文神经配音工具，并记录实际声音和时长。
+
+D. 后续如何避免问题：配音工作流应预先区分“讯飞凭证可用”和“本地/在线替代 TTS”两条路径；任务开始时先检查环境变量和运行时，避免到合成阶段才发现不可用。
+
+### 3. 原视频时长与旁白时长不一致
+
+A. 具体问题：原始录屏约 85.6 秒，目标视频约 1 分钟，直接换音轨会出现画面比旁白长的问题。
+
+B. 产生问题原因：录屏展示节奏偏慢，而旁白文案按介绍视频压缩到了约 64 秒。
+
+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-28-03 配音工具不纳入 Gitea 备份
+
+### 1. 临时配音工具误纳入源码备份
+
+A. 具体问题：Ubuntu 版配音工具和工作流文档属于本地辅助材料，用户明确说明它们和 `待配音视频` 一样不需要 Gitea 备份。
+
+B. 产生问题原因：上一轮把“新建工具”理解为需要随仓库保存，未先确认这些本地配音工具是否属于源码交付范围。
+
+C. 解决问题方案：从 Git 跟踪中移除 `Tools_scripts_XunFei-Ubuntu/` 与 `配音生成工作流-Ubuntu-Agent.md`，并将它们加入 `.gitignore` 与 `.dockerignore`；`待配音视频/` 继续保持忽略。
+
+D. 后续如何避免问题：凡是视频、配音、录屏、临时工具和本地工作流材料，默认先按“不进入源码仓库”处理；只有用户明确要求备份时再纳入 Gitea。

工程分析/需求分析-2026-05-18-23-35-23.md

@@ -0,0 +1,22 @@
+# 需求分析
+
+开始时间：2026-05-18-23-35-23
+
+## 用户需求
+
+1. `待配音视频` 文件夹不需要上传到 Gitea。
+2. 将待配音视频处理为约 1 分钟左右。
+3. 参考 `待配音视频/配音生成工作流-Agent.md`，生成系统介绍配音，并合成为完整的系统使用视频。
+
+## 约束与现状
+
+- 原始素材：`待配音视频/ISISeg-介入导丝视频分割工作台-使用展示.mp4`。
+- 原始视频信息：1920x1080、50fps、HEVC、总时长约 85.6 秒，含 AAC 音频。
+- 配音工作流文档使用讯飞 TTS PowerShell 脚本，但当前 Linux 环境未配置 `XF_APPID`、`XF_APIKEY`、`XF_APISECRET`，且无 PowerShell 运行时。
+- 为保证任务可落地，沿用工作流的分段稿件、TTS、时长检查、视频合成步骤，TTS 引擎使用当前环境可执行的中文配音工具替代。
+
+## 输出目标
+
+- 在 `待配音视频` 下生成约 1 分钟的最终成片。
+- 最终视频包含系统介绍旁白，并与画面时长匹配。
+- 提交到 Gitea 的内容只包含忽略规则和工程分析文档，不包含 `待配音视频` 中的素材和成片。

工程分析/需求分析-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` 环境变量读取凭证。
+- 生成音频和视频的输出目录由用户指定，避免覆盖已有结果。

工程分析/需求分析-2026-05-19-00-28-03.md

@@ -0,0 +1,25 @@
+# 需求分析
+
+开始时间：2026-05-19-00-28-03
+
+## 用户需求
+
+用户明确说明：刚创建的 Ubuntu 配音工具与工作流文档，以及 `待配音视频`，都不需要备份到 Gitea。
+
+## 需处理对象
+
+- `Tools_scripts_XunFei-Ubuntu/`
+- `配音生成工作流-Ubuntu-Agent.md`
+- `待配音视频/`
+
+## 目标
+
+- 从 Git 跟踪中移除 Ubuntu 配音工具目录和 Ubuntu 工作流文档。
+- 将上述路径加入 `.gitignore`，避免后续误提交。
+- 将上述路径加入 `.dockerignore`，避免 Docker 构建上下文夹带配音工具和视频素材。
+- 保留工程分析文档用于记录本次处理过程。
+
+## 注意
+
+- `待配音视频/` 已在上一轮加入 `.gitignore` 和 `.dockerignore`，本次继续保留。
+- 当前工作区中 Ubuntu 配音工具目录和 Ubuntu 工作流文档已经处于删除状态，本次不恢复文件，直接确认从 Gitea 最新版本移除。