Videohub Story Editor

VideoHub Story Editor

使用以下固定结构，不直接让模型凭摘要调用 FFmpeg：

视频和原文字幕
  -> 证据提取层
  -> 故事理解层
  -> 剪辑规划层
  -> 最终原文时间轴
  -> 后置翻译和可选润色
  -> 原声版 / TTS 解说版
  -> 确定性渲染和 QA
  -> 抖音发布包（可选）

边界

• 不安装或调用 WhisperX。
• 优先使用人工字幕或平台字幕；缺少字幕时，调用 videohub-youtube 和 src/youtube_transcriber.py 的现有 Whisper 流程。
• 故事理解和选段以原文字幕为证据。不要依赖剪辑前的逐句机翻决定剧情、因果或 说话人意图。
• 模型负责理解、选段和撰写解说；脚本负责时间计算、证据校验、翻译接入、TTS 对齐、渲染和 QA。
• 原声版和解说版必须复用同一个 story_plan.json，避免两套版本选段漂移。
• 翻译或 TTS 凭据缺失时，不得阻断证据提取、故事计划和原声原文版。
• 默认先交付分析与剪辑方案；用户明确要求成片后才执行渲染。
• 只处理用户有权下载和再创作的内容。

默认值

• 目标时长：240 秒，容差 15%。
• 输出语言：简体中文。
• 外文视频：剪辑后翻译，原声版默认双语字幕。
• 解说版：中文 TTS 字幕，原声音量 0.30。
• 播放速度：1.0 倍，不为凑时长自动改变原片对白速度。
• 分析目录：workspace/review_packs/story_editor/<job_id>/。
• 成片目录：workspace/videos_with_subtitles/ 或计划中的输出目录。
• 抖音发布包：workspace/publish_packages/douyin/<package_name>/。

剧集素材项目目录

用户只提供一个剧集目录时，不再要求分别提供视频和字幕路径。先刷新目录内的可移植项目清单：

python src/series_project.py "<series_dir>"

读取 <series_dir>/videohub_project.json，按用户给出的集数或文件名选择 episodes 中的条目。 视频位于项目根目录；本地批处理生成的字幕位于 subtitles/。选择字幕时依次优先使用：

1. subtitles.polished 中的 SRT。
2. subtitles.translated 中与目标语言匹配的 SRT。
3. subtitles.source 中的 SRT。
4. 视频内嵌字幕；仍没有字幕时再调用 VideoHub Whisper 流程。

清单只保存相对路径，移动整个剧集目录后仍可使用。空格、下划线、连字符以及 _google、_polished、语言后缀的差异由项目扫描器归一化匹配。目录包含多集而用户未说明 集数时，必须先确认目标集，不能默认把整季当成一个视频任务。

可视化时间线精修

已有解说项目完成 AI 初剪后，可以启动本地网页工作台：

cd frontend
npm install
npm run build
cd ..
python src/story_timeline_server.py

打开 http://127.0.0.1:8766/story-editor，选择包含 docs/story_job/story_plan.json 的 workspace/projectNNN_* 项目。工作台导入故事计划、 旁白计划、字幕和证据文件，显示视频、原声、TTS 旁白、原声锚点和字幕五条轨道。

• 可以预览素材，拖动切点，拆分、删除和重排片段，并撤销或重做。
• 可以修改旁白文本、单独调用 MiniMax 重生成一个语音块，拖动原声窗口和字幕边界； 预览画面中的解说字幕可上下拖动，避开原片已有的硬字幕，保存后按同一位置烧录。
• 可以设置片段音量关键帧、淡入淡出、交叉转场，并注册其他本地视频源。
• 配置 DEEPSEEK_API_KEY 后可以对选中的旁白做保守局部改写；缺少密钥时不影响其他功能。
• 保存会写入项目的 revisions/rev-*；片段缓存写入 .story_editor_cache/segments。 不覆盖源视频、原始计划、原始字幕或已有 TTS 文件。

时间线编辑器是人工精修入口。对剧情、人物和因果的判断仍应先执行下面的证据提取与故事 理解流程，不能用拖动时间线替代证据校验。

1. 证据提取层

确认视频和带时间码的原文字幕存在。没有字幕时先使用 VideoHub 现有字幕流程。

python .agents/skills/videohub-story-editor/scripts/build_evidence_pack.py `
  --video "<video_path>" `
  --subtitle "<source_subtitle.srt>" `
  --language "<source_language>" `
  --target-language "zh-CN"

新任务默认不要传 --translated-subtitle。该参数只用于兼容已经有可靠译文的旧任务。 脚本输出 evidence_pack.json、transcript.json、scenes.json、关键帧和 analysis_chunks/chunk-*.json。

场景检测或抽帧成本过高时可使用 --skip-scene-detection 或 --skip-keyframes， 但必须在分析的不确定性中说明视觉证据缺失。

2. 故事理解层

读取 story-analysis-schema.md 和 editing-strategies.md。

1. 逐个读取 analysis_chunks，记录人物或说话人、事件、观点、问题、答案、步骤和结果。
2. 实际检查关键帧后再填写视觉发现；未看画面时不得猜测动作、表情或地点。
3. 汇总全片时间线、因果关系、主题、指代和连续性约束。
4. 提出一到三个故事方案，选择一个方案。
5. 所有结论保留 sub-*、scene-*、frame-*、visual-* 或 chunk-* 引用。

Codex、Claude Code 或 DeepSeek 都必须写出同一数据契约的 story_analysis.json。 调用 API 模型时，按 model-workflow.md 分批提交证据， 不要让供应商响应格式进入后续脚本。

python .agents/skills/videohub-story-editor/scripts/validate_story_analysis.py `
  "<job_dir>/story_analysis.json" `
  --evidence "<job_dir>/evidence_pack.json"

有错误时不得进入剪辑规划。

3. 剪辑规划层

根据选中的故事方案创建 story_plan.draft.json。读取 story-plan-schema.md，外文视频默认设置：

{
  "subtitle_mode": "bilingual",
  "translation_stage": "post_edit",
  "translation_polish": true
}

每个片段填写 kind、story_role、源时间范围、analysis_refs、 story_reason、audio_mode 和 transition。对白片段优先显式列出 source_subtitle_ids。允许重排，但不能改变事实、因果、教程步骤、问题与回答关系， 或拼出说话者没有表达过的观点。

python .agents/skills/videohub-story-editor/scripts/compile_story_plan.py `
  "<job_dir>/story_plan.draft.json" `
  --evidence "<job_dir>/evidence_pack.json" `
  --analysis "<job_dir>/story_analysis.json" `
  --output "<job_dir>/story_plan.json"

python .agents/skills/videohub-story-editor/scripts/validate_story_plan.py `
  "<job_dir>/story_plan.json" `
  --evidence "<job_dir>/evidence_pack.json" `
  --analysis "<job_dir>/story_analysis.json"

同时交付 story_outline.md 和 story_source_map.csv 供人工审核。校验错误必须修正； 警告必须解释或修正。

4. 剪辑后翻译

先按最终选段和重排顺序重建原文 SRT：

python .agents/skills/videohub-story-editor/scripts/prepare_story_subtitles.py `
  "<job_dir>/story_plan.json" `
  --evidence "<job_dir>/evidence_pack.json" `
  --analysis "<job_dir>/story_analysis.json" `
  --output "<job_dir>/final_source.srt"

source_subtitle_ids 是剧情证据引用，不保证覆盖片段里的全部对白。影视解说需要在底部 持续显示完整原声字幕时，渲染器必须使用 --source-subtitle-policy all-intersecting，按每个 入选片段的源时间范围收集并裁切全部相交字幕。默认 explicit 保持证据引用模式，兼容已有 计划。

再翻译最终 SRT。translation_polish=true 或显式 --polish 时，复用 VideoHub 现有的 Google 基础翻译和 DeepSeek 全局轻度润色，并保留可对比的基础翻译与润色版。

python .agents/skills/videohub-story-editor/scripts/translate_story_subtitles.py `
  "<job_dir>/story_plan.json" `
  --source "<job_dir>/final_source.srt" `
  --output "<job_dir>/final_zh-CN.srt" `
  --polish

没有 DEEPSEEK_API_KEY 时自动跳过润色并保留基础翻译；翻译失败也不能破坏已经生成的 原文字幕、故事计划或源视频。脚本生成 post_edit_translation.json 记录实际状态。

5. 原声版

原声版保留原片声音，并把剪辑后翻译注入最终时间轴：

python .agents/skills/videohub-story-editor/scripts/render_story.py `
  "<job_dir>/story_plan.json" `
  --evidence "<job_dir>/evidence_pack.json" `
  --analysis "<job_dir>/story_analysis.json" `
  --translated-subtitle "<job_dir>/final_zh-CN.srt" `
  --burn-subtitles bilingual `
  --subtitle-prefix "<job_dir>/source_audio" `
  --output "<output_dir>/<name>_source_audio.mp4" `
  --qa-report "<job_dir>/source_audio_qa.md"

--burn-subtitles 允许 none、source、translated、bilingual。外文视频烧录 译文或双语字幕时，必须提供覆盖全部最终字幕条目的后置翻译。

6. TTS 解说版

读取 narration-plan-schema.md，根据完整故事分析、 剪辑计划和来源映射撰写 narration_plan.json。解说可以串联和概括选中内容，但每个 叙述块都必须引用证据，不能虚构原片没有提供的事实。

电影、电视剧或短剧需要“第三者旁白为主、关键场面恢复影视原声”时，改用 videohub-film-commentary Skill。它仍复用本流程，但会增加不与旁白重叠的 source_audio_windows、动态原声音量和合并字幕。

python .agents/skills/videohub-story-editor/scripts/validate_narration_plan.py `
  "<job_dir>/narration_plan.json" `
  --story-plan "<job_dir>/story_plan.json" `
  --evidence "<job_dir>/evidence_pack.json" `
  --analysis "<job_dir>/story_analysis.json"

MiniMax 使用 MINIMAX_API_KEY；豆包使用 DOUBAO_TTS_APP_ID、 DOUBAO_TTS_ACCESS_TOKEN，可选 DOUBAO_TTS_RESOURCE_ID。凭据只放在本地环境变量 或 .env，不要写进 JSON。

python .agents/skills/videohub-story-editor/scripts/synthesize_story_narration.py `
  "<job_dir>/narration_plan.json" `
  --story-plan "<job_dir>/story_plan.json" `
  --evidence "<job_dir>/evidence_pack.json" `
  --analysis "<job_dir>/story_analysis.json"

合成器按文案和音色缓存分段 WAV，校验实际时长，生成与最终成片对齐的完整旁白轨和 中文字幕。然后渲染解说版：

python .agents/skills/videohub-story-editor/scripts/render_story.py `
  "<job_dir>/story_plan.json" `
  --evidence "<job_dir>/evidence_pack.json" `
  --analysis "<job_dir>/story_analysis.json" `
  --narration-audio "<job_dir>/narration_audio_minimax.wav" `
  --narration-subtitle "<job_dir>/narration_minimax.srt" `
  --background-volume 0.30 `
  --burn-subtitles translated `
  --subtitle-prefix "<job_dir>/narration_minimax" `
  --output "<output_dir>/<name>_narration_minimax.mp4" `
  --qa-report "<job_dir>/narration_minimax_qa.md"

豆包版本将文件名中的 minimax 换成 doubao。默认把原声降到 30%，但保留环境声、 音乐和关键对白。叙述文本过长时先改写；只有在不超过计划上限时才自动轻度加速。

7. 确定性渲染和交付

渲染器必须：

• 只接受校验通过且来源指纹一致的计划。
• 按原片时间范围重新编码片段并按 output_order 拼接。
• 根据片段交集裁切原字幕，并换算到重排后的输出时间轴。
• 分别输出原声版和解说版字幕、成片及 QA 报告，不互相覆盖。
• 完整解码成片，检查时长和字幕边界；QA 通过后才清理中间片段。
• 不删除源视频、证据包、计划和 TTS 缓存。

当前渲染器支持普通切换和 crossfade，也支持片段级视频/音频淡入淡出、音量关键帧、 片段缓存以及多个本地视频源。多个来源会统一到主视频的分辨率和帧率后再拼接。旧计划中的 fade 转场不会被当作独立转场类型；需要淡入淡出时，应设置片段的 fade_in_sec 和 fade_out_sec。

至少交付：

• evidence_pack.json
• story_analysis.json
• story_plan.json
• story_outline.md
• story_source_map.csv
• 原声版 MP4、最终原文/译文/双语字幕和 QA 报告
• 请求解说版时，再交付 narration_plan.json、TTS 音轨、中文字幕、解说版 MP4 和 QA 报告

8. 抖音发布包

用户要求“适合发到抖音的文件夹”“发布包”或“配一段发布文案”时，在成片 QA 通过后 生成发布包。先根据 story_analysis.json、最终解说稿和实际成片撰写 50-100 个可见字符 的中文文案：概括具体内容和看点，不虚构结论，不使用与视频无关的夸张标题；话题标签 单独保存，不用标签凑文案长度。

python .agents/skills/videohub-story-editor/scripts/build_douyin_publish_package.py `
  "<final_video.mp4>" `
  --title "<发布标题>" `
  --caption "<50-100字中文文案>" `
  --hashtag "<话题1>" `
  --hashtag "<话题2>" `
  --source-url "<source_url>" `
  --qa-report "<job_dir>/qa.md" `
  --cover-time <representative_second>

发布包至少包含：

• 经过媒体探测的 H.264/AAC MP4；已符合要求时优先硬链接，避免重复占用空间。
• caption.txt：仅保存 50-100 字正文。
• hashtags.txt：独立保存建议话题。
• cover.jpg：用户要求或有合适代表画面时生成。
• publish_notes.md：供人工发布前检查。
• publish_manifest.json：记录媒体参数、文案长度、来源、QA 报告和 SHA-256。

横版成片默认保持原构图和 1080P，不自动强裁为竖屏。用户明确要求竖版时，应先重新 设计画面布局并完成单独 QA，不能直接裁掉人物、字幕或关键物体。发布前仍需人工检查 平台规则、版权授权、标题、封面和字幕。

不得把重排前的字幕时间码直接复制到成片。每个成片片段、原声字幕和解说块都必须 能回溯到原视频时间范围或证据 ID。