edit | blame | history | raw

本地视频语音转写 4 小时长视频优化编码方案 V001

创建人员：dev.developer.project
文件职责：冻结长视频有界分块、时间轴合并、资源验收和失败清理的最小实现方案。
管理规范/模板：../../../dev-doc/编码规范.md；../../../dev-doc/开发审计规范.md；../../../../common/dev-doc/编码规范.md。
引用文件：../../../ai-media-processor/draft/本地视频语音转写_4小时长视频性能与资源优化需求_v0.1.md；../../../dev/project-dev/transcribe_media.py；../../../dev/project-dev/test/test_transcribe_media.py；../本地视频语音转写工具.md。
记录方式：重型性能优化编码方案；方案审核通过后按本版本实现，变化另建后继版本。

1. 事项与边界

  • 事项：DEV-PROJECT-INFO-LOCAL-MEDIA-TRANSCRIBE-LONG-VIDEO-OPT-20260801-001。
  • 目标：保持命令、模型和四文件合同不变，使约 4 小时视频不再把完整波形、VAD 拼接结果和频谱一次装入 Python 内存。
  • 只修改 dev/project-dev/transcribe_media.py、对应测试和使用说明；不新增模型、CPU 降级、批处理、断点续跑、服务或数据库。
  • 原视频只读；完整 FLAC 仍为正式候选输出；失败统一删除暂存目录，四个正式文件只在全部成功后提交。

2. 模块和接口

现有公开 CLI 与 transcribe_video(video_path, output_dir, language, ...) 不变，只增加内部函数：

  1. _probe_audio_duration：对已生成的完整 FLAC 获取有限、正数时长。
  2. _plan_audio_chunks：当时长大于 1200 s 时生成顺序核心区间；核心长度 1200 s，两侧重叠 5 s，首尾裁到 [0,duration]。
  3. _extract_audio_chunk：从完整 FLAC 生成唯一临时块；固定 16 kHz、单声道 FLAC、-n，失败显式停止。
  4. _collect_chunked_transcript：复用同一模型逐块转写；每块结束后在 finally 删除临时块。
  5. _project_chunk_segments：块内时间加音频块全局起点；按分段中点落入对应核心 [core_start, core_end)，仅末块允许中点等于总时长；排序后输出全局分段。

短视频 duration <= 1200 s 继续调用现有 _collect_transcript(model, full_flac, language)，不创建音频块。

3. 语言与模型合同

  • large-v3、device=cuda、compute_type=float16、vad_filter=True 不变。
  • 模型在完整 FLAC 生成后只加载一次。
  • 显式语言传给所有块；未指定语言时首块不传语言，保存其检测语言和概率，后续块固定复用检测语言。
  • 任一块失败不走 CPU、其他模型或参数降级。

4. 时间轴与去重

对第 i 块：

  • core_start = i * 1200
  • core_end = min(duration, core_start + 1200)
  • audio_start = max(0, core_start - 5)
  • audio_end = min(duration, core_end + 5)
  • global_start/end = audio_start + local_start/end
  • midpoint = (global_start + global_end) / 2

只保留中点属于本块核心区间的分段；这是一条唯一归属规则，不增加模糊文本去重或重写识别结果。最终分段按 (start,end,text) 升序，TXT/SRT/JSON 继续由同一个结果对象生成。

5. 资源与失败安全

  • 暂存目录同时包含完整 FLAC 和最多一个固定名临时块；临时块写完、转写后立即删除。
  • 进度输出 正在转写分块 i/n 并立即刷新，便于资源采样关联块号。
  • 中断、FFmpeg 或 GPU 失败由现有外层 finally 清理整个暂存目录；块函数另有局部 finally，确保当前块先删除。
  • 不在 Python 中读取完整 FLAC 字节，不保存完整波形或频谱。
  • 正式输出冲突检查、相邻暂存、四文件提交和回滚逻辑不变。

6. 测试与验收

6.1 离线测试

  • 20 分钟阈值两侧；4 小时生成 12 个核心块。
  • 首块、内部块、末块的 5 秒重叠和裁边。
  • 边界中点唯一归属、全局偏移、排序和无重复序号。
  • 模型只加载一次；未指定语言时首块检测、后续复用。
  • 任意块失败时临时块和暂存目录清理。
  • 现有无音轨、FFmpeg 失败、输出冲突和禁止 CPU 降级回归。

6.2 真实回归

  1. 使用原 1193.64 s 视频走未分块路径，核对 705 段、四文件对应、源哈希不变。
  2. 在专属临时目录用只读源循环复用生成约 14400 s 测试副本。
  3. 完整运行采样 Python 与 FFmpeg 合计工作集、RTX 3090 显存、当前块号和临时块大小。
  4. 验证 exit 0、耗时 <=100 min、RAM <=12 GB、GPU <10 GB、临时块 <500 MB、前后三块峰值差、FLAC 时长、文本非空、SRT/JSON 可解析和全部 20 分钟边界。
  5. 保留 4 小时媒体与输出供 case_analysis.media_processor 只读复核。

7. 重跑与恢复

  • 不实现断点续跑；失败后换新输出目录整任务重跑。
  • 已存在任一正式输出即拒绝，不复用半成品。
  • 4 小时验收副本和结果只位于 dev/project-dev/tmp/DEV-PROJECT-INFO-LOCAL-MEDIA-TRANSCRIBE-LONG-VIDEO-OPT-20260801-001/。

8. 高风险点与门禁

  • 边界中点比较错误会导致重复或漏段，必须由合成分段单元测试冻结。
  • 若未在每块 finally 删除临时块，会违反 500 MB 和单块上限。
  • 若后续块仍传 language=None，会造成语言漂移；测试必须检查调用参数。
  • 若短视频错误进入分块，19:54 基线会漂移；真实回归必须证明仍走单次路径。
  • 方案审核未通过前不修改代码；实现后按需求执行完整资源验收，再提交实现审核或请求方验收。

9. 当前状态

PENDING_INDEPENDENT_DESIGN_REVIEW