Claude Skill

video-recap

从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm,并要求剪辑、添加旁白、 配音、总结、短剧/电视剧/电影/纪录片/科普解说时使用。负责编排 video-* 技能链:视频理解 → Agent 制定故事与视听方案 → 剪辑 → 配音 → 合成。触发词:视频解说、视频旁白、生成解说、 视频 recap、video recap、voiceover、narration、auto-dub、recap。

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download zenstory-ai-oh-story-dsh-packages_knowledge_video-recap_skills_video-recap-cf70e6d.zip · 377 KB

Install

skills CLI npx skills add https://github.com/zenstory-ai/oh-story-dsh/tree/main/packages/knowledge/video-recap/skills/video-recap
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install zenstory-ai-oh-story-dsh@llmmart
Git git clone https://github.com/zenstory-ai/oh-story-dsh.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole zenstory-ai/oh-story-dsh collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

1. 定位与流程

本技能是自包含的视频解说与剪辑生产技能,将视频理解、故事立意、画面剪辑、旁白撰稿、配音合成与音画混音放在同一工作目录 work_dir 下串联完成:

understand.py(视频理解)─▶ Agent 制定故事/声画方案并写 clip_plan.json 或 narration.json ─▶ [cut.py(剪辑与重出简报)] ─▶ validate.py(本地底线校验)─▶ voiceover.py(TTS 配音)─▶ assemble.py(混音与字幕渲染)

日常使用可直接运行总入口 scripts/recap.py 串联全流程并在创作节点自动暂停,也可按需单独调用 scripts/ 下的单阶段脚本(understand.py、cut.py、validate.py、voiceover.py、assemble.py)。

把外部成片拆解为制作参考(production_reference.json)不在默认生产链上。当用户要求拆片学习时:先对样片跑 understand.py(建议设 ASR_SEGMENT_SECONDS=5),再用独立的拆片技能执行测量、标注、校验与导出,将导出的 production_reference.json 放入下一轮运行的 work_dir,或登记为资源库里的 production_reference 模板并经 --project 绑定。主流程不会自动拆片,也不拿新成片与参考片做机械打分比对。

全流程支持断点续跑:写完 clip_plan.json 或 narration.json 后重跑同一条 recap.py 命令即可继续。续跑时脚本会核对 recap_run_manifest.json 记录的源视频身份与参数,若工作目录来自其他视频或不同参数组合会拒绝复用;暂停时终端打印的续跑命令已将路径转为绝对路径并补齐 --work-dir。

画面流程 --edit-mode full|cut 与声音策略 --audio-mode narration|source-mix 相互独立,支持以下五条路线(其余组合启动即报错):

输入 --edit-mode --audio-mode Agent 暂停点 流程 详见
单视频 full narration 1 次:写 narration.json 理解 → 写稿 → 校验 → 配音 → 合成 §4
单视频 cut narration 2 次:先写 clip_plan.json,剪完再对成片写 narration.json 理解 → 剪辑 → 重出输出时间简报 → 写稿 → 校验 → 配音 → 合成 §4
多视频 cut narration 2 次:同上,且每条片段必须带 source_id 逐源理解 → 剪辑 → 写稿 → 校验 → 配音 → 合成 §4.5
单视频 full source-mix 无暂停 直接合成当前整段视频(不跑理解或 TTS) §4.7
单 / 多视频 cut source-mix 1 次:写 clip_plan.json 理解 → 剪辑 → 合成(不写旁白) §4.7

2. 创作职责

创作判断由 Agent 负责。动笔前先区分本轮的创作控制模式(CREATE 新建创作 / DIRECTED 按指定方案执行 / REVISION 定稿返修,与 --edit-mode 独立),并在配音渲染前完成五项判断:

  1. 导演判断:明确观众点进来看什么、跟谁的主视角(POV)走、核心悬念是什么、情绪从哪儿起到哪儿落,以及哪张底牌留到最后揭晓。
  2. 故事编辑:每一拍(beat)交代清楚局势、关系或筹码发生了什么实质变化,不写流水账摘要。
  3. 画面剪辑:选出有动作推进与人物反应的镜头和入出点,删掉拖沓过场。
  4. 声音/旁白:先定每一拍由画面、原声对白、动作声、静音还是旁白主导,再按“垫半句、让半句、接半句”写词。
  5. 观众复核:站在首次观看的视角做关旁白看画面、闭眼纯听声音和首尾兑现检查。

控制模式分工、REVISION 锁定规则、剪辑与口播细则,以及 recap_story_plan.json、visual_audio_board.json、style_card.json 的结构详见 references/creative-editing-playbook.md。

3. 环境与远程调用说明

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

同一个 MIMO_API_KEY 即可驱动默认全链路。涉及远程网络请求的环节如下:

  • 视频理解(understand.py):将切分后的音频窗口发往 MiMo ASR(mimo-v2.5-asr),将抽帧 JPEG 连同 background_research.json 摘要发往 MiMo VLM(默认 mimo-v2.6-flash,可通过 MIMO_MODEL 切换 mimo-v2.6-pro 等)。若工作目录已有完整分析产物,传 --brief-only 或 --edited-storyboard-only 则纯本地运行、不发起网络请求。
  • 旁白配音(voiceover.py):按 --tts-provider(默认 auto 优先选已配置的 MiMo,其次 Fish Audio,不自动选 index-tts)将解说文本发往对应 TTS 服务:
    • mimo-tts:发往 MiMo TTS(mimo-v2.5-tts);若显式传了 --voice-ref <audio>,还会将该参考音频切片发往 mimo-v2.5-tts-voiceclone(使用前请确认已获声音授权)。
    • fish-audio:需配置 FISH_API_KEY,将每段解说文本与 FISH_TTS_REFERENCE_ID 发往 FISH_TTS_API_URL(默认 https://api.fish.audio/v1/tts)。
    • index-tts:仅在显式指定 --tts-provider index-tts 时启用,将文本与 INDEX_TTS_VOICE 发往用户自建的 INDEX_TTS_ENDPOINT(详见 references/index-tts.md)。
  • 解说校验(validate.py)、视频剪辑(cut.py、shot_review.py)与音画合成(assemble.py):纯本地确定性逻辑与 ffmpeg / ffprobe 调用,不发起网络请求。

以 tp- 开头的 Token Plan 密钥默认发往中国区集群,可通过 MIMO_TOKEN_PLAN_CLUSTER 切换集群。配置项见 references/config-playbook.md,产物格式见 references/data-schema.md。下文 scripts/... 均相对于本技能目录。

4. 创作与制作流程

4.1 背景调研与视频理解

只要能从文件名或用户说明识别出片名、剧集名或科普主题,开跑前先按 references/research-guide.md 核实人物关系与前情,写入 work_dir/background_research.json(多视频连剪写在项目根 work_dir,脚本会自动同步到 sources/<source_id>/)。

随后启动编排入口:

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

脚本完成音频提取、静音与句末停顿锚点检测(speech_boundary_anchors.json)、场景切分、VLM 帧分析与 ASR 转写后,生成故事板拼图 storyboard/storyboard_*.jpg 与创作简报 agent_narration_brief.md 并暂停。

4.2 导演意图与选镜计划(cut 第一阶段)

阅读 agent_narration_brief.md 并查看故事板抽帧后,先写 recap_story_plan.json(CREATE 主线清晰时写 1 个选定方案即可,仅在源片存在多角度取舍时比较 2–3 个候选假设)与 visual_audio_board.json(逐拍明确画面瞬间、进出理由、原声锚点与声音主导方)。

在 cut 模式第一阶段,编写基于**源片时间轴(SOURCE)**的 work_dir/clip_plan.json(本阶段不写 narration.json):

{
  "target_duration": "3m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 (hook):沈曼推门撞见未婚夫与千金谈联姻,入点卡推门看清两人动作,出点卡转身攥紧户口本"
    }
  ],
  "required_evidence": {
    "nodes": [
      {"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "推门撞见两人拥抱"}
    ],
    "before": []
  }
}

选镜与切点规则:

  • 简明剪辑理由(reason):用自然中文写清该段承担的节拍作用(hook | setup | turn | escalation | payoff)与入出点画面/声音依据,无需拼固定段数的竖线模板。
  • 必保画面与原声证据(required_evidence):不可丢失的关键动作、反应或原声问答可登记在 required_evidence;若边界吸附裁掉必保区间或颠倒 before 顺序,脚本会报错拦截。
  • 晚进场与冷开场取舍:默认顺时序“晚进场”(直接从冲突或反差动作切入,省去进门寒暄铺垫);正序冲突出现较晚时可前置一段冷开场悬念镜,时长随悬念动作自然收住,做到不靠铺垫也能看懂、不与正片重复同一机位、只留悬念不提前亮底牌。旁白压低原声时优先垫反应镜、动作细节或稳态画面,避免角色正脸连续张嘴说话却被压低消音。
  • 句末安全切点与收尾气口:切点须落在源片首尾、句末停顿锚点、静音窗口或同源无缝顺接处;句末吸附会在停顿窗内预留最多 0.30s 气口且不跨硬切点,单段最短 >= 0.8s,片尾最后一拍留出表情或动作落定的余韵。切进台词中途会报 unsafe_clip_sentence_boundary(若同时引发闪帧与切词冲突则报 shot_speech_conflict)。
  • 密集快切与碎镜排查:cut.py 渲染 edited_source.mp4 后会自动运行 shot_review.py 生成 shot_review.json,拦截 <= 0.20s 的极短残镜闪帧(flash_slivers)。遇到动作戏或密集反打时,也可运行 ffmpeg -i <video> -vf "select='gt(scene,0.35)',showinfo" -f null - 或 scripts/shot_review.py(见 references/shot-review.md)检查切点,区分原片切点与拼接切点——将原片自带的无关短镜头整段删除或把边界移到快切簇外侧;对由本次拼接制造的切点(如硬切边缘残留几帧邻镜),外扩入出点或合并同源相邻段,不用转场遮掩坏接点。

写好 clip_plan.json 后重跑 recap.py,脚本完成边界吸附、渲染恒定帧率 edited_source.mp4 并重映射输出时间轴证据(speech_boundary_anchors_output.json、storyboard/edited_storyboard.*),随后暂停等待写解说词。

4.3 解说词与原声留白创作(full / cut 第二阶段)

进入写稿阶段后,先查看剪后故事板、补齐 visual_audio_board.json 的成片输出时间并按需编写 style_card.json,再写 work_dir/narration.json:

[
  {
    "start": 0.2,
    "end": 5.0,
    "narration": "相恋五年揣着户口本去求婚,沈曼推开门,却撞见未婚夫正搂着千金谈联姻。",
    "pause_after_ms": 250,
    "overlaps_speech": true
  }
]

编排 cut 模式下,narration.json 直接填写剪后成片的 OUTPUT 时间戳(0 .. 成片总时长)(单独调校验器传 validate.py --mode cut_output)。核心写作要求(细则与正反例见 references/creative-editing-playbook.md):

  • 背景、筹码与点名节奏:讲清前情关系、动机筹码与动作后果,不复述画面表象;60 秒内短片点名 1–2 个核心人物即可(次要角色用身份关系称呼),3–10 分钟中长解说随节拍推进自然引入关键人物。
  • “垫半句、让半句、接半句”与原声边界:原声重头台词或关键动作声前提前收口让位,尾音落定后再接半句点破后果;压低原声切入(overlaps_speech: true)须对齐句末锚点或静音窗(违者报 interrupts_source_sentence / unsafe_source_handoff),释放原声同样避免落在角色半句话中途(对白区间内后续 3s 无锚点时给出 unsafe_source_release 复核提示,合成端做 bounded_release 平滑回升)。
  • 字数预算、完整收句与去套话:每段以完整句末标点收尾(残句报 incomplete_sentence),靠精炼字数匹配窗口(full 模式超预算 1.25 倍报 over_budget,不静默删字)。写连贯自然的口语长短句,不写阅读理解式升华套话;结局交给画面与原声演完,兑现后不再补总结旁白。
  • 配乐与原声留白字幕:外部配乐(BGM_PATH)只用纯器乐,原片已有高音量人声插曲时不叠外部配乐。传入 --subtitle-y-top/--subtitle-y-bot 默认仅在旁白区间开启 1.0 不透明像素带遮罩(留白段继续露出原片自带硬字幕);若原片无硬字幕,或额外设置 SOURCE_SUBTITLE_MASK_TIMING=all(或同时设 MASK_SOURCE_SUBTITLES=true + SOURCE_SUBTITLE_MASK_TIMING=all + SUBTITLE_MASK_OPACITY=1.0)开启全片不透明遮罩并保留了原声对白,可在 work_dir/original_subtitles.json 按成片时间写入校对后的原声字幕(若留白段原片硬字幕仍可见,合成器会自动跳过以免叠字)。
  • 平台宣发备忘与画布包装分开落盘:故事定稿后如需输出平台标题、封面帧与简介方案,按 references/promotional-copy.md 写入 work_dir/promo_copy.json;成片画布视觉包装按 references/packaging.md 写入 work_dir/packaging_plan.json。

4.4 配音合成与音画混音渲染

写好 narration.json 后重跑同一条 recap.py 命令:

  1. 本地确定性校验(validate.py):输出 narration_lint.json。对时间重叠/越界、残句、抢断原话、full 模式超预算与模板占位符泄漏做硬阻断(errors);对原声释放点无邻近锚点(unsafe_source_release)、开场留白偏长(weak_cold_open_silence)、长段无声留白(excessive_dead_air)、外貌泛称(generic_character_label)与评论套话(editorial_commentary_tone)给出非阻断提示(warnings)。
  2. TTS 配音(voiceover.py):逐段合成语音写入 tts_segments/ 与 tts_meta.json,缓存按文本、音色、模型与参考音频指纹命中;若实测语速低于下限(TTS_MIN_SPEECH_RATE,即合成音频异常拖长)疑似异常合成,会自动重试并将异常音频另存为 *.rejected.wav。
  3. 音画合成(assemble.py):将画面、逐段旁白、动态闪避与句末回升后的原声、可选 BGM、可选音效(work_dir/sfx_plan.json 或 packaging_plan.json.sfx)、画布包装(work_dir/packaging_plan.json 或 packaging_layers.json,见 references/packaging.md)与片尾音频淡出合成为最终 MP4,自动抽帧导出 work_dir/cover.jpg(若 promo_copy.json 指定了封面秒数则优先采用),并输出 timeline.json(传 --export-jianying 可将视频、旁白、BGM、字幕与包装图片导出为剪映草稿)。若旁白在微加速上限内仍装不进可用时间窗,直接报 no_safe_fit 阻断,不截断尾音。声音模式与路由规则见 references/audio-modes.md。

4.5 多视频连剪与资源库

多视频输入仅支持 cut 模式,项目级简报会列出各片源的 source_id,clip_plan.json 中每条片段均须填写 source_id:

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

可通过 --material-library-dir .video-materials --save-materials 与 --use-materials 跨集复用单源理解缓存;同一库根目录下还可登记配乐、音效、音色、字体、贴图及可复用模板(subtitle_style、packaging、production_reference),用 scripts/library.py check|list|show 查询并通过 --project recap_project.json 绑定,合成后自动生成 work_dir/resource_lock.json(详见 references/resource-library.md)。测量原片硬字幕纵向遮罩区间可查看抽帧图片,或在源码仓库下运行 tools/measure_subtitle.py <video> 后传入 --subtitle-y-top 与 --subtitle-y-bot。

4.6 最终观看与交付复核

交付前必须直接打开最终成片文件完成视听复核:

  1. 原速通看:不倍速从头看到尾,记下画面跳脱或节奏拖沓处。
  2. 检查拼接点:抽查切点前后 0.5–1 秒,排查闪帧、动作跳接与半句截断的原声。
  3. 纯听音轨:闭眼听一遍,确认口播连贯自然、原声闪避过渡平顺、关键台词清晰。
  4. 复核开场、高潮与收尾:单独重看开场前 5 秒、中段转折戏眼与片尾收束,确认切入时机与余韵立得住。
  5. 返修核对与 final_qc.json 检查:REVISION 模式确认修改项已落实且冻结项未回退;核对 final_qc.json 的解码、时长与规格结果,若 metadata.warnings 非空(如 partial_tts 或缺少 libass 导致 subtitle_burn_degraded 降级为外挂 .srt),须如实告知用户。

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

source-mix 同样执行原声响度归一、可选 BGM 混音、片尾淡出与音频重编码;切换音频模式须换用新工作目录。详见 references/audio-modes.md。

5. 自检与只读看板

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

doctor.py 检查本机 ffmpeg / ffprobe、字幕滤镜与远程服务密钥配置;dashboard_server.py 在本地 127.0.0.1 启动只读审片台(仅响应 GET 与 HEAD),浏览 --root 下的成片目录、解说时间轴与素材库。

6. 输出与参数

核心交付物:

  • 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 及各阶段脚本 --help 为准;--style 作为自由文本原样传给写稿 Agent,不映射为固定枚举。

7. 能力边界

  • 确定性底线检查(残镜闪帧、台词截断、旁白抢断或半句释放原声、full 模式字数硬上限、超长削尾、必保画面丢失、占位符泄漏、解码与封装规格)作为硬门禁运行。
  • 故事立意、开场节奏、留白长短、角色点名密度与口播文风不设机械打分门禁,由 Agent 结合画面证据、原声时间轴与 references/creative-editing-playbook.md 自主把控并经成片视听复核确认。
Files (oh-story-dsh)
  • references
    • jianying
      • empty_draft_meta_info.json 1.7 KB
        Loading…
      • empty_jy_material_video.json 1.8 KB
        Loading…
      • empty_jy_meta_material_value.json 358 B
        Loading…
      • empty_jy_project_info.json 3.6 KB
        Loading…
      • empty_jy_segment.json 1.3 KB
        Loading…
      • empty_jy_text_styles.json 440 B
        Loading…
      • empty_yj_material_audio.json 865 B
        Loading…
      • empty_yj_material_text.json 2.4 KB
        Loading…
      • LICENSE.duo-video 1 KB · in bundle
      • SOURCE.md 703 B
        Loading…
    • audio-modes.md 3.6 KB
      Loading…
    • config-playbook.md 8 KB
      Loading…
    • creative-editing-playbook.md 12.3 KB
      Loading…
    • data-schema.md 34.6 KB
      Loading…
    • index-tts.md 2.1 KB
      Loading…
    • packaging.md 6.8 KB
      Loading…
    • promotional-copy.md 4.1 KB
      Loading…
    • prompt-templates.md 2 KB
      Loading…
    • research-guide.md 2.7 KB
      Loading…
    • resource-library.md 12.1 KB
      Loading…
    • shot-review.md 4.8 KB
      Loading…
  • scripts
    • briefing
      • builder.py 31.1 KB
        Loading…
      • context.py 6.1 KB
        Loading…
      • timeline.py 23 KB
        Loading…
      • __init__.py 101 B
        Loading…
    • jianying
      • builders.py 11.3 KB
        Loading…
      • model.py 2.7 KB
        Loading…
      • optional.py 1012 B
        Loading…
      • schema.py 2.5 KB
        Loading…
      • templates.py 1 KB
        Loading…
      • timeline_contract.py 5.8 KB
        Loading…
      • tracks.py 2 KB
        Loading…
      • writer.py 7.8 KB
        Loading…
      • __init__.py 49 B
        Loading…
    • providers
      • fish_audio.py 3.1 KB
        Loading…
      • index_tts.py 8.8 KB
        Loading…
      • __init__.py 72 B
        Loading…
    • resources
      • lock.py 6.8 KB
        Loading…
      • project_binding.py 16.1 KB
        Loading…
      • __init__.py 200 B
        Loading…
    • subtitles
      • core.py 19 KB
        Loading…
      • render.py 8 KB
        Loading…
      • __init__.py 56 B
        Loading…
    • agent_text.py 2.7 KB
      Loading…
    • artifacts.py 972 B
      Loading…
    • asr.py 12.5 KB
      Loading…
    • asr_timing_evidence.py 4.2 KB
      Loading…
    • assemble.py 31 KB
      Loading…
    • assemble_constants.py 894 B
      Loading…
    • assembly_contract.py 10.3 KB
      Loading…
    • assembly_settings.py 3.8 KB
      Loading…
    • audio_automation.py 6.6 KB
      Loading…
    • audio_mix.py 18.5 KB
      Loading…
    • codec_peak.py 5.1 KB
      Loading…
    • cut.py 148 B
      Loading…
    • cut_cli.py 12.4 KB
      Loading…
    • cut_contract.py 13.3 KB
      Loading…
    • cut_qc.py 1.9 KB
      Loading…
    • cut_render.py 13.2 KB
      Loading…
    • detect.py 22.2 KB
      Loading…
    • doctor.py 12.9 KB
      Loading…
    • entry_suggestion.py 4.6 KB
      Loading…
    • export_jianying.py 5.6 KB
      Loading…
    • extract.py 2.5 KB
      Loading…
    • final_qc.py 19 KB
      Loading…
    • frame_grid.py 10.6 KB
      Loading…
    • lib.py 29.6 KB
      Loading…
    • library.py 31.1 KB
      Loading…
    • lint_summary.py 5 KB
      Loading…
    • loudness.py 14.7 KB
      Loading…
    • materials.py 22.1 KB
      Loading…
    • media.py 18.8 KB
      Loading…
    • narration_audio.py 13.5 KB
      Loading…
    • narration_lint.py 24.1 KB
      Loading…
    • narrative_selection.py 8.9 KB
      Loading…
    • packaging.py 6.1 KB
      Loading…
    • packaging_fonts.py 12 KB
      Loading…
    • packaging_plates.py 31.2 KB
      Loading…
    • packaging_studio.py 34.1 KB
      Loading…
    • recap.py 183 B
      Loading…
    • recap_cli.py 6.9 KB
      Loading…
    • recap_inspect.py 16.5 KB
      Loading…
    • recap_runner.py 22 KB
      Loading…
    • recap_runtime.py 11.8 KB
      Loading…
    • recap_source.py 1.8 KB
      Loading…
    • recap_stage_qc.py 2.7 KB
      Loading…
    • recap_timeline.py 7.7 KB
      Loading…
    • render_preflight.py 1.7 KB
      Loading…
    • sentence_boundaries.py 28.8 KB
      Loading…
    • sentence_gate.py 8.6 KB
      Loading…
    • sfx_mix.py 14.6 KB
      Loading…
    • shot_review.py 18.9 KB
      Loading…
    • source_subtitles.py 7.2 KB
      Loading…
    • speech_ownership.py 9.3 KB
      Loading…
    • storyboard.py 21.8 KB
      Loading…
    • timeline.py 8.2 KB
      Loading…
    • timeline_emit.py 5.4 KB
      Loading…
    • tts_audio.py 9.6 KB
      Loading…
    • tts_cache.py 4.5 KB
      Loading…
    • understand.py 171 B
      Loading…
    • understanding_brief.py 6.3 KB
      Loading…
    • understanding_cache.py 8 KB
      Loading…
    • understanding_runner.py 9.8 KB
      Loading…
    • understanding_storyboard.py 11.9 KB
      Loading…
    • validate.py 5.7 KB
      Loading…
    • visual_render.py 10.1 KB
      Loading…
    • vlm.py 16.4 KB
      Loading…
    • voiceover.py 28 KB
      Loading…
  • SKILL.md 18.4 KB
    ---
    name: video-recap
    description: 从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm,并要求剪辑、添加旁白、配音、总结或制作短剧/电视剧/电影/纪录片/科普解说时使用。在同一个自包含技能内完成视频理解、导演立意与选镜剪辑、解说撰稿与校验、TTS 配音及音画混音合成。触发词:视频解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narration、recap。
    ---
    
    ## 1. 定位与流程
    
    本技能是自包含的视频解说与剪辑生产技能,将视频理解、故事立意、画面剪辑、旁白撰稿、配音合成与音画混音放在同一工作目录 `work_dir` 下串联完成:
    
    ```text
    understand.py(视频理解)─▶ Agent 制定故事/声画方案并写 clip_plan.json 或 narration.json ─▶ [cut.py(剪辑与重出简报)] ─▶ validate.py(本地底线校验)─▶ voiceover.py(TTS 配音)─▶ assemble.py(混音与字幕渲染)
    ```
    
    日常使用可直接运行总入口 `scripts/recap.py` 串联全流程并在创作节点自动暂停,也可按需单独调用 `scripts/` 下的单阶段脚本(`understand.py`、`cut.py`、`validate.py`、`voiceover.py`、`assemble.py`)。
    
    把外部成片拆解为制作参考(`production_reference.json`)不在默认生产链上。当用户要求拆片学习时:先对样片跑 `understand.py`(建议设 `ASR_SEGMENT_SECONDS=5`),再用独立的拆片技能执行测量、标注、校验与导出,将导出的 `production_reference.json` 放入下一轮运行的 `work_dir`,或登记为资源库里的 `production_reference` 模板并经 `--project` 绑定。主流程不会自动拆片,也不拿新成片与参考片做机械打分比对。
    
    全流程支持断点续跑:写完 `clip_plan.json` 或 `narration.json` 后重跑同一条 `recap.py` 命令即可继续。续跑时脚本会核对 `recap_run_manifest.json` 记录的源视频身份与参数,若工作目录来自其他视频或不同参数组合会拒绝复用;暂停时终端打印的续跑命令已将路径转为绝对路径并补齐 `--work-dir`。
    
    画面流程 `--edit-mode full|cut` 与声音策略 `--audio-mode narration|source-mix` 相互独立,支持以下五条路线(其余组合启动即报错):
    
    | 输入 | `--edit-mode` | `--audio-mode` | Agent 暂停点 | 流程 | 详见 |
    |---|---|---|---|---|---|
    | 单视频 | full | narration | 1 次:写 `narration.json` | 理解 → 写稿 → 校验 → 配音 → 合成 | §4 |
    | 单视频 | cut | narration | 2 次:先写 `clip_plan.json`,剪完再对成片写 `narration.json` | 理解 → 剪辑 → 重出输出时间简报 → 写稿 → 校验 → 配音 → 合成 | §4 |
    | 多视频 | cut | narration | 2 次:同上,且每条片段必须带 `source_id` | 逐源理解 → 剪辑 → 写稿 → 校验 → 配音 → 合成 | §4.5 |
    | 单视频 | full | source-mix | 无暂停 | 直接合成当前整段视频(不跑理解或 TTS) | §4.7 |
    | 单 / 多视频 | cut | source-mix | 1 次:写 `clip_plan.json` | 理解 → 剪辑 → 合成(不写旁白) | §4.7 |
    
    ## 2. 创作职责
    
    创作判断由 Agent 负责。动笔前先区分本轮的**创作控制模式**(`CREATE` 新建创作 / `DIRECTED` 按指定方案执行 / `REVISION` 定稿返修,与 `--edit-mode` 独立),并在配音渲染前完成五项判断:
    
    1. **导演判断**:明确观众点进来看什么、跟谁的主视角(POV)走、核心悬念是什么、情绪从哪儿起到哪儿落,以及哪张底牌留到最后揭晓。
    2. **故事编辑**:每一拍(beat)交代清楚局势、关系或筹码发生了什么实质变化,不写流水账摘要。
    3. **画面剪辑**:选出有动作推进与人物反应的镜头和入出点,删掉拖沓过场。
    4. **声音/旁白**:先定每一拍由画面、原声对白、动作声、静音还是旁白主导,再按“垫半句、让半句、接半句”写词。
    5. **观众复核**:站在首次观看的视角做关旁白看画面、闭眼纯听声音和首尾兑现检查。
    
    控制模式分工、`REVISION` 锁定规则、剪辑与口播细则,以及 `recap_story_plan.json`、`visual_audio_board.json`、`style_card.json` 的结构详见 `references/creative-editing-playbook.md`。
    
    ## 3. 环境与远程调用说明
    
    ```bash
    # ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
    export MIMO_API_KEY=***
    ```
    
    同一个 `MIMO_API_KEY` 即可驱动默认全链路。涉及远程网络请求的环节如下:
    
    - **视频理解(`understand.py`)**:将切分后的音频窗口发往 MiMo ASR(`mimo-v2.5-asr`),将抽帧 JPEG 连同 `background_research.json` 摘要发往 MiMo VLM(默认 `mimo-v2.6-flash`,可通过 `MIMO_MODEL` 切换 `mimo-v2.6-pro` 等)。若工作目录已有完整分析产物,传 `--brief-only` 或 `--edited-storyboard-only` 则纯本地运行、不发起网络请求。
    - **旁白配音(`voiceover.py`)**:按 `--tts-provider`(默认 `auto` 优先选已配置的 MiMo,其次 Fish Audio,不自动选 `index-tts`)将解说文本发往对应 TTS 服务:
      - `mimo-tts`:发往 MiMo TTS(`mimo-v2.5-tts`);若显式传了 `--voice-ref <audio>`,还会将该参考音频切片发往 `mimo-v2.5-tts-voiceclone`(使用前请确认已获声音授权)。
      - `fish-audio`:需配置 `FISH_API_KEY`,将每段解说文本与 `FISH_TTS_REFERENCE_ID` 发往 `FISH_TTS_API_URL`(默认 `https://api.fish.audio/v1/tts`)。
      - `index-tts`:仅在显式指定 `--tts-provider index-tts` 时启用,将文本与 `INDEX_TTS_VOICE` 发往用户自建的 `INDEX_TTS_ENDPOINT`(详见 `references/index-tts.md`)。
    - **解说校验(`validate.py`)、视频剪辑(`cut.py`、`shot_review.py`)与音画合成(`assemble.py`)**:纯本地确定性逻辑与 `ffmpeg` / `ffprobe` 调用,不发起网络请求。
    
    以 `tp-` 开头的 Token Plan 密钥默认发往中国区集群,可通过 `MIMO_TOKEN_PLAN_CLUSTER` 切换集群。配置项见 `references/config-playbook.md`,产物格式见 `references/data-schema.md`。下文 `scripts/...` 均相对于本技能目录。
    
    ## 4. 创作与制作流程
    
    ### 4.1 背景调研与视频理解
    
    只要能从文件名或用户说明识别出片名、剧集名或科普主题,开跑前先按 `references/research-guide.md` 核实人物关系与前情,写入 `work_dir/background_research.json`(多视频连剪写在项目根 `work_dir`,脚本会自动同步到 `sources/<source_id>/`)。
    
    随后启动编排入口:
    
    ```bash
    python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"
    ```
    
    脚本完成音频提取、静音与句末停顿锚点检测(`speech_boundary_anchors.json`)、场景切分、VLM 帧分析与 ASR 转写后,生成故事板拼图 `storyboard/storyboard_*.jpg` 与创作简报 `agent_narration_brief.md` 并暂停。
    
    ### 4.2 导演意图与选镜计划(cut 第一阶段)
    
    阅读 `agent_narration_brief.md` 并查看故事板抽帧后,先写 `recap_story_plan.json`(`CREATE` 主线清晰时写 1 个选定方案即可,仅在源片存在多角度取舍时比较 2–3 个候选假设)与 `visual_audio_board.json`(逐拍明确画面瞬间、进出理由、原声锚点与声音主导方)。
    
    在 `cut` 模式第一阶段,编写基于**源片时间轴(SOURCE)**的 `work_dir/clip_plan.json`(本阶段不写 `narration.json`):
    
    ```json
    {
      "target_duration": "3m",
      "clips": [
        {
          "start": 12.0,
          "end": 38.0,
          "reason": "b01 (hook):沈曼推门撞见未婚夫与千金谈联姻,入点卡推门看清两人动作,出点卡转身攥紧户口本"
        }
      ],
      "required_evidence": {
        "nodes": [
          {"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "推门撞见两人拥抱"}
        ],
        "before": []
      }
    }
    ```
    
    选镜与切点规则:
    
    - **简明剪辑理由(`reason`)**:用自然中文写清该段承担的节拍作用(`hook | setup | turn | escalation | payoff`)与入出点画面/声音依据,无需拼固定段数的竖线模板。
    - **必保画面与原声证据(`required_evidence`)**:不可丢失的关键动作、反应或原声问答可登记在 `required_evidence`;若边界吸附裁掉必保区间或颠倒 `before` 顺序,脚本会报错拦截。
    - **晚进场与冷开场取舍**:默认顺时序“晚进场”(直接从冲突或反差动作切入,省去进门寒暄铺垫);正序冲突出现较晚时可前置一段冷开场悬念镜,时长随悬念动作自然收住,做到不靠铺垫也能看懂、不与正片重复同一机位、只留悬念不提前亮底牌。旁白压低原声时优先垫反应镜、动作细节或稳态画面,避免角色正脸连续张嘴说话却被压低消音。
    - **句末安全切点与收尾气口**:切点须落在源片首尾、句末停顿锚点、静音窗口或同源无缝顺接处;句末吸附会在停顿窗内预留最多 `0.30s` 气口且不跨硬切点,单段最短 `>= 0.8s`,片尾最后一拍留出表情或动作落定的余韵。切进台词中途会报 `unsafe_clip_sentence_boundary`(若同时引发闪帧与切词冲突则报 `shot_speech_conflict`)。
    - **密集快切与碎镜排查**:`cut.py` 渲染 `edited_source.mp4` 后会自动运行 `shot_review.py` 生成 `shot_review.json`,拦截 `<= 0.20s` 的极短残镜闪帧(`flash_slivers`)。遇到动作戏或密集反打时,也可运行 `ffmpeg -i <video> -vf "select='gt(scene,0.35)',showinfo" -f null -` 或 `scripts/shot_review.py`(见 `references/shot-review.md`)检查切点,区分原片切点与拼接切点——将**原片自带的无关短镜头整段删除**或把边界移到快切簇外侧;对**由本次拼接制造的切点**(如硬切边缘残留几帧邻镜),外扩入出点或合并同源相邻段,不用转场遮掩坏接点。
    
    写好 `clip_plan.json` 后重跑 `recap.py`,脚本完成边界吸附、渲染恒定帧率 `edited_source.mp4` 并重映射输出时间轴证据(`speech_boundary_anchors_output.json`、`storyboard/edited_storyboard.*`),随后暂停等待写解说词。
    
    ### 4.3 解说词与原声留白创作(full / cut 第二阶段)
    
    进入写稿阶段后,先查看剪后故事板、补齐 `visual_audio_board.json` 的成片输出时间并按需编写 `style_card.json`,再写 `work_dir/narration.json`:
    
    ```json
    [
      {
        "start": 0.2,
        "end": 5.0,
        "narration": "相恋五年揣着户口本去求婚,沈曼推开门,却撞见未婚夫正搂着千金谈联姻。",
        "pause_after_ms": 250,
        "overlaps_speech": true
      }
    ]
    ```
    
    **编排 `cut` 模式下,`narration.json` 直接填写剪后成片的 OUTPUT 时间戳(`0 .. 成片总时长`)**(单独调校验器传 `validate.py --mode cut_output`)。核心写作要求(细则与正反例见 `references/creative-editing-playbook.md`):
    
    - **背景、筹码与点名节奏**:讲清前情关系、动机筹码与动作后果,不复述画面表象;60 秒内短片点名 1–2 个核心人物即可(次要角色用身份关系称呼),3–10 分钟中长解说随节拍推进自然引入关键人物。
    - **“垫半句、让半句、接半句”与原声边界**:原声重头台词或关键动作声前提前收口让位,尾音落定后再接半句点破后果;压低原声切入(`overlaps_speech: true`)须对齐句末锚点或静音窗(违者报 `interrupts_source_sentence` / `unsafe_source_handoff`),释放原声同样避免落在角色半句话中途(对白区间内后续 3s 无锚点时给出 `unsafe_source_release` 复核提示,合成端做 `bounded_release` 平滑回升)。
    - **字数预算、完整收句与去套话**:每段以完整句末标点收尾(残句报 `incomplete_sentence`),靠精炼字数匹配窗口(`full` 模式超预算 1.25 倍报 `over_budget`,不静默删字)。写连贯自然的口语长短句,不写阅读理解式升华套话;结局交给画面与原声演完,兑现后不再补总结旁白。
    - **配乐与原声留白字幕**:外部配乐(`BGM_PATH`)只用纯器乐,原片已有高音量人声插曲时不叠外部配乐。传入 `--subtitle-y-top`/`--subtitle-y-bot` 默认仅在旁白区间开启 `1.0` 不透明像素带遮罩(留白段继续露出原片自带硬字幕);若原片无硬字幕,或额外设置 `SOURCE_SUBTITLE_MASK_TIMING=all`(或同时设 `MASK_SOURCE_SUBTITLES=true` + `SOURCE_SUBTITLE_MASK_TIMING=all` + `SUBTITLE_MASK_OPACITY=1.0`)开启全片不透明遮罩并保留了原声对白,可在 `work_dir/original_subtitles.json` 按成片时间写入校对后的原声字幕(若留白段原片硬字幕仍可见,合成器会自动跳过以免叠字)。
    - **平台宣发备忘与画布包装分开落盘**:故事定稿后如需输出平台标题、封面帧与简介方案,按 `references/promotional-copy.md` 写入 `work_dir/promo_copy.json`;成片画布视觉包装按 `references/packaging.md` 写入 `work_dir/packaging_plan.json`。
    
    ### 4.4 配音合成与音画混音渲染
    
    写好 `narration.json` 后重跑同一条 `recap.py` 命令:
    
    1. **本地确定性校验(`validate.py`)**:输出 `narration_lint.json`。对时间重叠/越界、残句、抢断原话、`full` 模式超预算与模板占位符泄漏做硬阻断(`errors`);对原声释放点无邻近锚点(`unsafe_source_release`)、开场留白偏长(`weak_cold_open_silence`)、长段无声留白(`excessive_dead_air`)、外貌泛称(`generic_character_label`)与评论套话(`editorial_commentary_tone`)给出非阻断提示(`warnings`)。
    2. **TTS 配音(`voiceover.py`)**:逐段合成语音写入 `tts_segments/` 与 `tts_meta.json`,缓存按文本、音色、模型与参考音频指纹命中;若实测语速低于下限(`TTS_MIN_SPEECH_RATE`,即合成音频异常拖长)疑似异常合成,会自动重试并将异常音频另存为 `*.rejected.wav`。
    3. **音画合成(`assemble.py`)**:将画面、逐段旁白、动态闪避与句末回升后的原声、可选 BGM、可选音效(`work_dir/sfx_plan.json` 或 `packaging_plan.json.sfx`)、画布包装(`work_dir/packaging_plan.json` 或 `packaging_layers.json`,见 `references/packaging.md`)与片尾音频淡出合成为最终 MP4,自动抽帧导出 `work_dir/cover.jpg`(若 `promo_copy.json` 指定了封面秒数则优先采用),并输出 `timeline.json`(传 `--export-jianying` 可将视频、旁白、BGM、字幕与包装图片导出为剪映草稿)。若旁白在微加速上限内仍装不进可用时间窗,直接报 `no_safe_fit` 阻断,不截断尾音。声音模式与路由规则见 `references/audio-modes.md`。
    
    ### 4.5 多视频连剪与资源库
    
    多视频输入仅支持 `cut` 模式,项目级简报会列出各片源的 `source_id`,`clip_plan.json` 中每条片段均须填写 `source_id`:
    
    ```bash
    python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep
    ```
    
    可通过 `--material-library-dir .video-materials --save-materials` 与 `--use-materials` 跨集复用单源理解缓存;同一库根目录下还可登记配乐、音效、音色、字体、贴图及可复用模板(`subtitle_style`、`packaging`、`production_reference`),用 `scripts/library.py check|list|show` 查询并通过 `--project recap_project.json` 绑定,合成后自动生成 `work_dir/resource_lock.json`(详见 `references/resource-library.md`)。测量原片硬字幕纵向遮罩区间可查看抽帧图片,或在源码仓库下运行 `tools/measure_subtitle.py <video>` 后传入 `--subtitle-y-top` 与 `--subtitle-y-bot`。
    
    ### 4.6 最终观看与交付复核
    
    交付前必须直接打开**最终成片文件**完成视听复核:
    
    1. **原速通看**:不倍速从头看到尾,记下画面跳脱或节奏拖沓处。
    2. **检查拼接点**:抽查切点前后 0.5–1 秒,排查闪帧、动作跳接与半句截断的原声。
    3. **纯听音轨**:闭眼听一遍,确认口播连贯自然、原声闪避过渡平顺、关键台词清晰。
    4. **复核开场、高潮与收尾**:单独重看开场前 5 秒、中段转折戏眼与片尾收束,确认切入时机与余韵立得住。
    5. **返修核对与 `final_qc.json` 检查**:`REVISION` 模式确认修改项已落实且冻结项未回退;核对 `final_qc.json` 的解码、时长与规格结果,若 `metadata.warnings` 非空(如 `partial_tts` 或缺少 `libass` 导致 `subtitle_burn_degraded` 降级为外挂 `.srt`),须如实告知用户。
    
    ### 4.7 不需要解说的原声成片
    
    ```bash
    # 对当前整段输入直接混音合成;不隐式跑理解、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
    ```
    
    `source-mix` 同样执行原声响度归一、可选 BGM 混音、片尾淡出与音频重编码;切换音频模式须换用新工作目录。详见 `references/audio-modes.md`。
    
    ## 5. 自检与只读看板
    
    ```bash
    python3 scripts/doctor.py
    python3 scripts/dashboard_server.py --root <目录> [--port 0] [--open]
    ```
    
    `doctor.py` 检查本机 `ffmpeg` / `ffprobe`、字幕滤镜与远程服务密钥配置;`dashboard_server.py` 在本地 `127.0.0.1` 启动只读审片台(仅响应 `GET` 与 `HEAD`),浏览 `--root` 下的成片目录、解说时间轴与素材库。
    
    ## 6. 输出与参数
    
    核心交付物:
    
    - `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` 及各阶段脚本 `--help` 为准;`--style` 作为自由文本原样传给写稿 Agent,不映射为固定枚举。
    
    ## 7. 能力边界
    
    - 确定性底线检查(残镜闪帧、台词截断、旁白抢断或半句释放原声、`full` 模式字数硬上限、超长削尾、必保画面丢失、占位符泄漏、解码与封装规格)作为硬门禁运行。
    - 故事立意、开场节奏、留白长短、角色点名密度与口播文风不设机械打分门禁,由 Agent 结合画面证据、原声时间轴与 `references/creative-editing-playbook.md` 自主把控并经成片视听复核确认。
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.