video-recap

1. 役割とフロー

このスキルは、5つの独立したスキルを軽量にオーケストレーションします。各スキルは work_dir 内の JSON / MP4 成果物を介してのみ連携し、コードは共有しません：

video-understanding ─▶ Agent 按 video-script 制定方案并写稿 ─▶ [video-cut] ─▶ video-voiceover ─▶ video-assemble

完成映像を制作リファレンスに分解することは、制作フローではありません。ユーザーが求めた場合は、完成映像に video-understanding を実行し（ASR_SEGMENT_SECONDS=5 を推奨）、続いて video-reference を使って measure、注釈付け、check、export を行います。エクスポートした production_reference.json を次回実行時の work_dir にコピーするか、リソースライブラリの production_reference テンプレートとして登録し、採用後に --project 経由で紐付けます。recap はこれを自動実行せず、新しい完成映像とリファレンスの比較も行いません。

フローは途中から再開できます。narration.json を作成した後、同じコマンドを再実行すれば続行できます。第2段階では recap_run_manifest.json に記録された元動画のパス、ファイルサイズ／更新日時、実行パラメーターを照合し、別の元動画や別のパラメーターで作成された古い作業ディレクトリの再利用を拒否します。動画理解の成果物も、元データが一致する場合にのみ再利用されます。 一時停止時に表示される再開コマンドは元のコマンドです。元の書式を維持し、動画とパスのパラメーターを絶対パスに変換して、--work-dir と環境変数からの設定を追加するため、どのディレクトリからでも直接実行できます。同じパラメーターが manifest の argv に記録されます。

映像フローの --edit-mode full|cut|dub と音声戦略の --audio-mode は、互いに独立した設定です。 narration は上記の解説フローを維持し、source-mix は吹き替えを行わず、adopted-packet-copy は現在の入力から採用済みの AAC 音声トラックをそのまま固定します。 組み合わせは以下のフローに限られ、それ以外の組み合わせは起動時にエラーになります：

入力	--edit-mode	--audio-mode	Agent の一時停止点	フロー	詳細
単一動画	full	narration	1：narration.json	理解 → 原稿作成 → 検証 → 吹き替え → 合成	§4
単一動画	cut	narration	2：clip_plan.json、続いて完成映像を見ながら narration.json を作成	理解 → 編集 → 出力時間 brief の再構築 → 原稿作成 → 吹き替え → 合成	§4
複数動画	cut	narration	2：同上。clip に source_id が必須	ソースごとに理解 → 編集 → 原稿作成 → 吹き替え → 合成	§4.3
単一動画	full	source-mix / adopted-packet-copy	なし	現在の全編を直接合成	§4.7
単一／複数動画	cut	source-mix / adopted-packet-copy	1：clip_plan.json	理解 → 編集 → 合成。原稿は作成しません	§4.7
単一動画	dub	narration	1：dub_script.json	英語の書き起こし → 翻訳原稿 → 音声クローンで全編を置換	§5
編集済みマスター	full	narration + 3つの採用済み JSON	なし	厳密な合成のみ	以下

すべての full/cut フローは、同じ仕上げ工程を共有します：（ナレーションがある場合）レビュー → TTS → 合成 → 完成映像の QC。原音モードを使用する場合は references/audio-routing.md を参照してください。

事前に用意した映像と、ローカルで採用した完全な音声 3 点セットがある場合は、厳密な assembly-only フローを利用できます：

python3 scripts/recap.py picture.mp4 --edit-mode full --work-dir NEW_WORK \
  --output-dir DELIVERY \
  --tts-meta tts_meta.json \
  --narration-adoption narration_adoption.json \
  --audio-mix-adoption audio_mix_adoption.json

3つの JSON パラメーターは必ずすべて指定してください。この入口で受け付けるのは、単一動画、full、narration、音声トラック 0、新しい作業ディレクトリ、まだ存在しない納品ファイルのみです。理解、原稿作成、解説レビュー、TTS、cut、剪映エクスポートは実行しません。意味とメディアの形式は引き続き video-assemble が厳密に検証します。recap はサブスキルの紐付け記録が、同じ採用済みファイルとマスターのパスを参照していることだけを確認し、呼び出し元が採用した音声やミックスを、自動生成または公開承認済みとは扱いません。詳しくは references/audio-routing.md を参照してください。

ここでいう単一動画はすでに編集済みのマスターです。再編集後も、変更していない WAV と tts_meta.json は再利用できますが、新しいマスターに合わせて、ミックス採用ファイルの配置と準備済みのベッドを更新する必要があります。引き継ぎ手順については、references/audio-routing.md の “Keep adopted voice after a cut” を参照してください。

2. 制作上の責任

今回の制作は Agent が担当します。まず今回の制作制御モード（CREATE / DIRECTED / REVISION。--edit-mode とは別に選択）を判断し、吹き替えとレンダリングの前に、以下の5つの判断を完了します：

1. 演出判断：観客への約束、POV、ドラマ上の問い、感情の着地点、情報開示のペース。
2. ストーリー編集：beat は「何が変化したか」と定義し、シーンの要約にはしません。
3. 映像編集：実際に残す価値のある具体的な瞬間、反応、イン点、アウト点を選びます。
4. 音声／ナレーション：解説文を書く前に、映像、原音、無音、ナレーションの役割を割り当てます。
5. 観客視点での再確認：ナレーションなし、音声のみ、初見での体験をそれぞれ確認します。

3つの制御モードの定義、REVISION における変更／凍結ルール、制作手法、および recap_story_plan.json / visual_audio_board.json / style_card.json の書き方は、すべて video-script に従ってください。このスキルは、最初に制作ハンドブックを読むよう求めます。これらのファイルは監査可能な現在の判断のみを記録し、サービスやレンダリングへの依存関係を増やしません。

3. 環境とスクリプトのパス

# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***

同じ MiMo key で、以下を利用します：

• ASR：mimo-v2.5-asr
• VLM：mimo-v2.5
• TTS：mimo-v2.5-tts

TTS プロバイダーは --tts-provider mimo-tts|fish-audio|index-tts（または TTS_PROVIDER）で指定し、吹き替えスキルに渡します。Fish Audio とセルフホストの index-tts それぞれの環境変数、既定の音声、機能上の制限については、該当スキルを参照してください。ASR/VLM は常に MiMo を使用します。--doctor はオフラインで設定をチェックするだけです。

tp-* Token Plan キーは、既定で中国リージョンのクラスターを使用します。MIMO_TOKEN_PLAN_CLUSTER で上書きできます。

オプション機能：

• --mimo-video-overview：シーンブロックごとに MiMo による動画理解を追加します。

上書き可能な設定については references/config-playbook.md、final_qc.json のフィールドについては references/data-schema.md を参照してください。

以下の scripts/... は、すべてこのスキルのディレクトリを基準とします。実行環境がリポジトリのルートディレクトリから起動する場合は、スクリプトのパスにこのスキルの絶対パスを付けてください。オーケストレーションスクリプトは同じスキルのルートディレクトリから必要な各段階を特定します。インストール時には、5つの段階スキルとこのスキルを同じ階層に配置する必要があります。

4. 標準解説フロー（audio-mode narration）

4.1 背景調査

映画、ドラマ、またはテーマを特定できる場合は、まず video-understanding スキルの調査ガイド research-guide.md に従って調査し、work_dir/background_research.json に書き込みます。動画理解では、人物名や物語の背景を VLM のコンテキストに取り込み、「黒い服の男性」のような曖昧な描写にとどまるのを防ぎます。出典を特定できない場合は省略できます。 複数動画の実行でも、プロジェクトの work_dir に同様に書き込みます。recap は各ソースを理解する前にそれを sources/<source_id>/ にコピーします（ソースディレクトリにファイルがない場合、またはプロジェクト側のファイルより古い場合にのみコピーします。そのため、特定のエピソードだけ個別に調査する場合は、プロジェクト側のファイルを作成した後に、そのソースディレクトリへ書き込んでください）。

4.2 分析して制作のために一時停止

python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"

コマンドは動画理解を完了し、agent_narration_brief.md を出力してから一時停止します。この時点で、以下の順序で video-script を実行します：

1. 制作 brief と元映像のストーリーボードを確認します。
2. recap_story_plan.json と visual_audio_board.json を作成します。
3. full モードでは narration.json を作成します。cut モードの第1段階では clip_plan.json のみ作成します。
4. cut モードの第2段階では、編集後のストーリーボードを確認し、出力時間と音声の役割分担を補足してから narration.json を作成します。

タイトルやナレーションの文から始めず、まずストーリー体験と素材の選択を固めてください。

タイムラインには、緩和できない2つの制約があります。原音を切り替えたり、切り出したり、復帰させたりできるのは、信頼できる文末または無音の境界だけです。ナレーションには段落ごとの音声全体を使用する必要があり、clip のマッピングによる切り詰め、TTS の末尾カット、または剪映でより長い高速化前の素材を参照することはすべて、処理を中断します。Agent が interrupts_source_sentence / unsafe_clip_sentence_boundary / no_safe_fit / timeline_audio_mismatch を受け取った場合は、境界を移動するか、文全体を短くするか、そのブロックを削除してください。割り込み override を追加してはいけません。unsafe_clip_sentence_boundary に付属する nearest_safe は、前後で最も近い安全な境界時刻を示します。

4.3 多视频与素材库

多视频只支持 cut 模式。项目 brief 会列出稳定的 source_id，clip_plan.json 中每个片段都必须填写来源：

python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep

第二阶段与单视频一样生成剪后故事板 storyboard/edited_storyboard.*，取自各来源 sources/<source_id>/frames/，brief 顶部列出 S1/S2… 对应的 source_id；素材库恢复的来源没有抽帧，这些片段不出现在故事板里，用 inspect clip-map 核对。

可选文件系统素材库：

python3 scripts/recap.py ep1.mp4 --material-library-dir .video-materials --save-materials
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --material-library-dir .video-materials --use-materials

素材检索只是对 JSON / MD / JSONL 做 grep，例如 grep -R "keyword" .video-materials。当前版本不复制原始媒体，也不提供数据库、向量或语义搜索。

同一根目录还可以登记可复用的资源（BGM、音效、音色、字体、图片）、带版本与采用记录的模板（字幕样式、包装图层、制作参考）和样片。 格式与 scripts/library.py check|list|show 只读工具见 references/resource-library.md。用 --project recap_project.json 把已采用的字幕样式、包装、制作参考、音色与 BGM 绑定到这次运行； 每次 full / cut 合成后 work_dir/resource_lock.json 记下实际用到的资源与授权状态。

4.4 继续生成成片

写好所需产物后，重复同一条命令：

python3 scripts/recap.py <video> --work-dir <work_dir>  # 可追加 --edit-mode cut / --no-burn-subtitles

流程会校验当前阶段的硬输入（clip_plan.json / narration.json）；两份创作计划仍是 Agent 与建议型评审使用的工作记录，不是渲染门禁。cut 模式随后生成 edited_source.mp4，再合成旁白并输出 recap_<name>.mp4。

校验从不改写解说稿（只更新实测的 overlaps_speech）；full 模式下文本装不下时间窗会以 over_budget error 退回给 Agent。已有批准解说稿时加 --preserve-approved-text，TTS 也原样保留批准稿，装不下时间窗即失败，不缩稿、不降级为部分成功。

4.5 字幕与克隆旁白

若要把旁白字幕固定在原片字幕区域，先测量位置。完整源码安装可在仓库根目录运行以下工具；单独安装技能时，由 Agent 查看视频帧测出同一显示画布上的上下边界：

python3 tools/measure_subtitle.py <video>

再传入测得的 --subtitle-y-top/--subtitle-y-bot。坐标基于 ffmpeg 自动旋转后的显示画布，区间为半开 [top, bot)，并要求底对齐 ASS 样式；显式设置后，该区域默认使用不透明的旁白窗口遮罩；可用 SUBTITLE_MASK_OPACITY 调整。

解说模式如需克隆参考声音，使用 --voice-ref <audio>；它与 dub 模式不同。

4.6 最终观看与交付复核

脚本、接点检测、样帧和 QC 报告都不能替代观看。每轮准备交付前，必须检查本轮实际要交付的最终文件，而不是旧别名、无字幕母版或中间代理：

1. 正常速度完整播放一次短片，不边看边改；先记录真实观看问题。
2. 播放每个拼接点前后约 0.5–1 秒，检查闪帧、原片叠化被截断、动作跳变和半句原声。
3. 完整只听声音一次，检查旁白是否碎成一句一停、场景间声音是否接得上、关键原声是否完整。
4. 单独复看开头、核心情绪/表演点和结尾，确认进入时机、回报停留和收束都成立。
5. REVISION 分别验证本轮修改项已经改变、冻结项没有意外变化；然后再做解码、时长、音画规格等机械检查。

scene score、亮度统计、contact sheet 与自动 QC 只负责定位候选问题；最终判断以真实播放为准。密集切点的来源判断与处理规则按剪辑技能执行。修复失败时回到剪点、声音或文案层，不用更多包装掩盖。

full/cut 交付如需让确定性的最终检查影响命令退出状态，显式传 --require-final-qc。只有 final_qc.json 的摘要为 ok: true 且整数 blocker_count: 0 才打印完成并返回成功；缺失、畸形或 blocker 会保留报告和已渲染诊断媒体，但命令非零退出且不打印完成。默认仍是仅报告、不阻断。 该参数不支持 --edit-mode dub；dub 未传该参数时的准备和渲染行为不变。

交付时读 final_qc.json 的 metadata.warnings，有内容就原样告诉用户，不能只报“完成”。subtitle_burn_degraded 表示 ffmpeg 缺 libass、默认烧录被降级：新字幕保存在成片旁的同名 .srt，原片已有硬字幕仍保留。用户要烧录字幕，就请他装带 libass 的 ffmpeg 后重跑；显式传 --burn-subtitles 时缺 libass 会在开跑前报错。旁白里写了 visual_overlays 而 ffmpeg 缺 drawtext 时，流程在配音前停下，按报错删掉叠加或换 ffmpeg 后续跑。

4.7 不需要解说的片子

# 对当前整段输入直接合成；不隐式跑理解/ASR/TTS
python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
# 剪辑计划仍按 cut 流程产生，剪完不再暂停等待 narration.json
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix
# 只换包装时冻结当前整片 AAC；不允许同时加 BGM/TTS
python3 scripts/recap.py adopted.mp4 --work-dir packaging_work --audio-mode adopted-packet-copy

source-mix 仍会混音和重编码；cut + adopted-packet-copy 冻结的是剪后中间片的声音，不是原片的 AAC 包。 当前严格字幕轨只支持 adopted 模式；其他字幕来源没有因此变成精确对齐。切换声音模式须新工作目录，不得把旧 TTS、QC 或自动生成的解说花字混入本轮原声生产。细节见 references/audio-routing.md。

5. 英译中原声复刻模式

--edit-mode dub 是实验功能：把英文视频翻译为中文，并用原说话者的克隆音色替换人声；它不是在压低原声上叠加解说。只在用户明确要求英译中配音时使用。

dub 会把源视频音轨分窗发给 MiMo ASR 转写，并把截取的约 10 秒原说话人声音作为参考，连同每句译文发给 MiMo voiceclone。因此必须带 --confirm-voice-rights：先向用户确认他有权使用这段视频与音频、且说话人同意被克隆声音，确认后才加这个参数；缺少时启动即报错，不抽音频、不发请求。该参数只用于 dub，其他模式传入会报错。

python3 scripts/recap.py <video> --edit-mode dub --confirm-voice-rights --work-dir <work_dir>

准备阶段会转写英文、提取一段参考音频，并写出 dub_brief.md 与 dub_transcript.json。Agent 按 dub_brief.md 里的翻译要求（逐句忠实、时间窗、语速）写 dub_script.json：

[{"start": 0.0, "end": 2.0, "zh": "中文译文"}]

重复同一命令后先做确定性 lint（dub_lint.json，空行、重叠、越界即中止），再输出 dub_<name>.mp4。每句单独克隆并贴回原时间线；只有即将覆盖下一句时才局部加速。当前版本只支持单说话者、整轨替换，不分离背景音乐。

6. 自检与只读 dashboard

python3 scripts/recap.py --doctor

6.1 只读 dashboard

python3 scripts/dashboard_server.py --root <目录> [--port 0] [--open]

前台运行并打印本机地址（只绑定 127.0.0.1，Agent 启动时放到后台）。它在 --root 下按 library.json、recap_project.json、 recap_run_manifest.json 发现资源库、项目与运行，按阶段显示剪辑节奏、旁白、成片与时间线、QC 和 resource_lock.json。 严格只读：只接受 GET / HEAD，不写任何文件；页面上的「复制给助手」只复制一句请求，改动回到对话里做。

7. 输出与参数

主要输出：

• recap_<video>.mp4：最终成片。
• subtitles.srt / subtitles.ass：字幕。
• work_dir/：全部中间产物，契约见 references/data-schema.md。
• work_dir/recap_story_plan.json / visual_audio_board.json：Agent 创作意图与剪辑决定。

完整参数列表以 python3 scripts/recap.py --help 为准。--style 是原样传给 Agent 的自由文本指导，不是 preset、枚举、开关或有限风格分类。

8. 能力边界

• 语义评审默认建议型、失败开放；只有调用方显式启用严格解说评审时，事实矛盾、残句或评审不可用才会在 TTS 前阻断。确定性校验阶段始终负责硬校验。
• 宣发标题、花字或外部文案回填交给 video-script，由它读取自己的宣发参考。