videohub-story-editor

# VideoHub Story Editor 使用以下固定结构，不直接让模型凭摘要调用 FFmpeg： ```text 视频和原文字幕 -> 证据提取层 -> 故事理解层 -> 剪辑规划层 -> 最终原文时间轴 -> 后置翻译和可选润色 -> 原声版 / 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>/`。 ## 剧集素材项目目录 用户只提供一个剧集目录时，不再要求分别提供视频和字幕路径。先刷新目录内的可移植项目清单： ```powershell 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 初剪后，可以启动本地网页工作台： ```powershell 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 现有字幕流程。 ```powershell 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](references/story-analysis-schema.md) 和 [editing-strategies.md](references/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](references/model-workflow.md) 分批提交证据， 不要让供应商响应格式进入后续脚本。 ```powershell 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](references/story-plan-schema.md)，外文视频默认设置： ```json { "subtitle_mode": "bilingual", "translation_stage": "post_edit", "translation_polish": true } ``` 每个片段填写 `kind`、`story_role`、源时间范围、`analysis_refs`、 `story_reason`、`audio_mode` 和 `transition`。对白片段优先显式列出 `source_subtitle_ids`。允许重排，但不能改变事实、因果、教程步骤、问题与回答关系， 或拼出说话者没有表达过的观点。 ```powershell 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： ```powershell 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 全局轻度润色，并保留可对比的基础翻译与润色版。 ```powershell 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. 原声版 原声版保留原片声音，并把剪辑后翻译注入最终时间轴： ```powershell 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](references/narration-plan-schema.md)，根据完整故事分析、 剪辑计划和来源映射撰写 `narration_plan.json`。解说可以串联和概括选中内容，但每个 叙述块都必须引用证据，不能虚构原片没有提供的事实。 电影、电视剧或短剧需要“第三者旁白为主、关键场面恢复影视原声”时，改用 `videohub-film-commentary` Skill。它仍复用本流程，但会增加不与旁白重叠的 `source_audio_windows`、动态原声音量和合并字幕。 ```powershell 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。 ```powershell 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，校验实际时长，生成与最终成片对齐的完整旁白轨和 中文字幕。然后渲染解说版： ```powershell 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 个可见字符 的中文文案：概括具体内容和看点，不虚构结论，不使用与视频无关的夸张标题；话题标签 单独保存，不用标签凑文案长度。 ```powershell 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。