zenstory-ai/video-recap-skills

video-reference

按需把一部优秀成片拆成可复用的制作参考:实测镜头节奏与音量起伏,标注段落与声音分工,把原片剧情事实与通用剪辑手法分开,导出不含原片人名和台词的 productionreference.json 供下次做片参考。独立于日常做片流程。触发词:拆片、拆解成片、制作参考、参考模板、production reference。

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/zenstory-ai/video-recap-skills --skill video-reference

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

1. 定位

本技能用于按需拆解一部已经做好的优秀解说成片,把它的剪辑节奏、声音分工与叙事手法提炼成下次做片可直接参考的方法卡片与实测指标。全程在本地运行,只输出测量数据、拆片标注与脱敏参考文件,不调用 MiMo,也不会给日常做片打分或设卡拦截。

Agent 在此扮演拆片编辑:先把“这条成片具体是怎么剪、怎么配的”(原片事实)如实记下来,再从中提炼出“换一部新素材还能怎么借鉴”(可迁移方法)。事实与方法必须彻底分家:包含原片人名、剧情和具体台词的事实只留在本地拆片目录里,最终导出的 production_reference.json 只保留通用方法与实测节奏数值。

2. 输入

  • 待拆解的成片视频文件(支持 .mp4 / .mov / .mkv / .webm)。
  • 针对这部成片跑出的视频理解产物目录 U(建议在理解阶段设 ASR_SEGMENT_SECONDS=5,分窗越细,测算出的旁白语速越准)。本技能会从中读取可选的 asr_result.json、asr_timing_evidence.json 与 background_research.json(其中登记的角色名、别名及 ASR 台词都会纳入防剧透泄漏扫描);Agent 做人工标注时还应结合故事板拼图(storyboard)与 vlm_analysis.json 一起看。

即使没有跑过视频理解,本技能也能单独运行,只是导出的旁白语速字段为空、防泄漏扫描词表仅依赖 Agent 手写的 entities,且 check 会给出相应警告;此时可用 frames --span 0,<时长> --step 2 抽帧生成拼图来辅助看片。

以下 scripts/... 路径均相对于本技能目录。

3. 拆片流程

bash
python3 scripts/reference.py measure <成片> --work-dir U        # 跑一次 ffmpeg 实测切点与响度,按文件身份缓存
python3 scripts/reference.py frames  <成片> --work-dir U --review          # 对被算法压下的疑似切点逐帧出图复核
python3 scripts/reference.py frames  <成片> --work-dir U --longest 5       # 抽出最长的 5 个镜头,排查里面有无漏检切点
python3 scripts/reference.py check   --work-dir U [--json]      # 校验拆片稿并打印派生指标
python3 scripts/reference.py export  --work-dir U --out <下次运行的 work_dir>/production_reference.json
  1. 实测镜头与响度(`measure`):由脚本生成 U/reference_measurements.json(人工切勿手改),记录全片镜头切点、镜头时长分布、每分钟切点数、10 秒滑动窗口切点密度曲线、整体响度(Integrated LUFS)、响度动态范围(LRA)、真峰值以及逐秒短期响度。该步骤需完整解码整部成片(5 分钟 720p 视频约耗时 15–70 秒,4K 视频约 7 分钟);只要成片文件未变就会直接复用缓存,单独调整 --soft-score 或 --hard-score 阈值无需重新解码。
  • 切点初筛逻辑:scdet 场景切换得分 ≥10 的帧直接判为切点;得分在 4 到 10 之间时,只有当该帧得分达到前后 0.3 秒窗口内其余非相邻帧最高分的两倍以上(明显高出周围帧的局部峰值),才判为切点。这样能过滤掉大部分跟拍晃动、急推拉和闪光灯,把这些拿不准的帧归入待复核窗口 shots.review_windows。此外,由于 scdet 得分会扣减上一帧的画面变化量,从剧烈运动镜头突然硬切到静止画面时,scdet 得分可能被压到只有 1 分左右;因此工具会把帧间画面差(mafd)自身突起的峰值也一并收进 shots.review_windows 供人工看图确认,但不会直接算作自动切点。
  1. 看图复核切点(`frames`):任何固定阈值在真实成片面前都会顾此失彼(昏暗夜戏的硬切可能只有 5–7 分,而激烈打斗的一个长镜头里每隔 0.2 秒就能蹦出 7–8 分的峰值),因此必须看图复核。运行 frames --review 会把每个待复核窗口逐帧拼成图片,运行 frames --longest 5 会在全片最长的 5 个镜头里各均匀抽取 12 帧拼图;图片输出在 U/reference_frames/ 下,终端会打印每一格对应的时间秒数。看完图后在 labels.cut_fixes 中登记修正:add 填入算法漏掉的真切点秒数,remove 填入算法误报的假切点秒数(与测得切点误差在 ±0.1 秒内即可匹配);若确认全部准确、无需增删,显式写 "cut_fixes": {} 表示已复核。注意:一旦重跑 measure 导致待复核窗口发生变化,旧的 cut_fixes 不再算数,Agent 必须对照新窗口重新核对更新。复核完成后,后续所有镜头统计指标、段落切点密度和最终导出物都会按修正后的切点重新计算。
  2. 标注音轨与段落(`labels`):由 Agent 在 U/reference_breakdown.json 中填写 labels——包括音轨归属 audio_spans、叙事功能段落 sections、字幕版式 subtitles 与标注依据 basis。
  • 音轨边界必须卡在真实声音起止点:audio_spans 的切换点要落在耳朵真正听见人声开口或收声的时刻,不要照抄字幕条出现或消失的时刻(按字幕切入帧标注的旁白收尾点,实测往往比真实现场收声晚 0.24–0.42 秒)。若目录内已有 U/speech_boundary_anchors.json,直接对照其中的 acoustic_pauses(start 即上一句收声点,end 即下一句开口点)对齐边界;因为声画同步换手率 switch_on_cut_share 只认切点前后 ±0.25 秒的误差,边界一旦标偏,算出来的换手率就会严重失真。原片人物自带的画外音或内心独白仍属于原片音轨,统一标为 original_dialogue,如需在做法上区分,写进后面的 source_facts 与 methods 即可。
  • 填完 labels 后即可先跑一次 check,查看终端打印出的派生统计值 derived(各音轨时长占比、各段落切点密度、旁白字速、声音换手落在画面硬切上的比例、全片各叙事功能段落在时间轴上的起止占比 structure,以及第一次原声亮相的相对位置 first_original_at)。
  1. 提炼事实与可迁移方法(`source_facts` 与 `methods`):对照刚刚算出的客观派生数据,在同一份 reference_breakdown.json 中继续填写原片事实 source_facts(必须锚定具体时间区间或测量路径,并显式列出涉及的专有名称 entities)与可迁移方法 methods(包含做法规则 rule、适用场景 applies_when、避坑条件 avoid_when、作用的下游文件 applies_to、支撑证据 evidence 与量化参考指标 targets)。注意:targets 里只写引用路径 {"from": "<测量路径>"}(数值叶子或白名单派生对象),建议不要在 rule 正文里直接手写阿拉伯数字(手写数字会触发非阻断 warning 提醒核查);导出时脚本会自动把实测数值填进去。
  2. 校验并导出(`check` → `export`):运行 check 确认零 error 后,执行 export 导出 production_reference.json;导出器在写盘前会对产物再做一遍全字段防剧透泄漏扫描。

完整字段定义、枚举词表以及好/坏方法写法对比见 references/reference-schema.md。

4. 校验与防泄漏规则

reference.py check 遇到以下任一错误(error)都会以退出码 1 阻断:

规则编号校验要求
R1顶层、labels、fact、method、target、cut_fixes 均采用严格封闭键集与封闭枚举;fact 不得混入方法字段,method 不得混入事实字段;编号须形如 f1… / m1… 且全局唯一;subtitles 字段类型固定;skipped_dimensions 的原因说明必须为非空字符串
R2audio_spans 与 sections 必须按时间升序排列、互不重叠、相邻间隙 ≤0.5 秒且完整覆盖全片时长;字幕取证时间点必须落在全片时长内;cut_fixes.remove 必须匹配某个已测得的切点,add 不得与已有切点重复
R3每条 fact 必须在时间锚点 t: [a, b](落在成片时长内)与测量锚点 measure: [路径](解析到 shots / loudness / derived 下的非字符串数值)之间二选一,且必须显式填写 entities 数组
R4每条 method 至少绑定一条支撑证据:引用已定义的 fact ID,或引用 measure:<路径>(同样仅限上述三个根路径)
R5target 只允许写 from 键,指向 shots、loudness 或 derived 下的数值叶子节点或白名单派生对象(见 schema),不可使用列表下标
R6rule、applies_when、avoid_when 以及 skipped_dimensions 的原因说明中,不得出现:原片专有名称(忽略空格比对)、与 ASR 台词或背景资料完全重合的连续 8 个汉字(跨标点、跨相邻 ASR 窗口同样拦截)或连续 5 个英文单词、绝对时间码、“第 N 秒”或“N 分 M 秒”(含汉字数字)、本地绝对路径
R7methods 至少提炼一条可迁移方法;五个制作维度(narrative_structure、pacing、shots_editing、narration_subtitles、audio_visual)按成片实际亮点提炼,未覆盖且未在 skipped_dimensions 写明原因的维度仅报 warning 提示
R8导出 production_reference.json 时,对所有键名和字符串值再跑一遍 R6 防泄漏扫描,且导出物任意层级不得出现 source_facts、labels、entities、evidence、statement、from、path 键

防泄漏词表会自动汇总 source_facts[].entities、background_research.json 中的角色与 character_details 别名、不超过 5 个字的 cultural_notes 词条,以及资料中带《》「」引号的短词。

以下情况仅报警告(warning),不阻断导出:method 与 source_facts 的描述共有连续 8 字或 5 词(提醒核查是否带入原片情节;通用剪辑表述无需硬换近义词)、五个维度中存在未覆盖也未登记 skipped_dimensions 的维度、method 未填 applies_when、rule 正文里直接写了阿拉伯数字、ASR 精度不是 AVAILABLE_COARSE、成片含中文对白但理解产物与资料库均未提供人名(此时仅靠手写的 entities 把关)、basis 为空、理解产物记录的视频文件身份与当前测量的成片不一致、存在待复核切点窗口但未填写 cut_fixes。

注意:R6 只能拦住字面重合,拦不住换了词却仍在复述原片剧情的写法;编写 method 时要总结“遇到什么素材特征时怎么处理”,不要写成“主角进门后怎么剪”。此外,校验器不检查自然语言语义是否与数据吻合——动笔写“哪类段落切镜更密”前,先核对 check 打印出的 cuts_per_min 实测值,不要凭印象写出与实测数据相反的结论。

5. 交付物与后续使用

最终导出的 production_reference.json 只包含:成片总时长与画布尺寸、cut_detection(切点检测参数及人工增删的切点数)、profile(核心节奏与响度指标,附带数据来源标记 provenance:measured 表示纯算法实测、reviewed 表示经过 cut_fixes 人工复核、labeled 表示依赖人工音轨/段落标注)、全片各叙事段落在时间轴上的相对位置分布 structure、字幕版式特征 subtitles、可迁移方法列表 methods 以及跳过的维度说明 skipped_dimensions。

使用方法:将导出的 production_reference.json 放进下一次制作任务的 work_dir(或通过资源库的 production_reference 模板绑定)。下游写稿阶段发现该文件存在时会主动读取,并在 recap_story_plan.json 的可选字段 reference_methods 中逐条记录对每条方法的采纳决定(adopt / adapt / skip)。借鉴参考方法时始终以新素材的真实画面和台词为准,不要把参考片的切点密度或留白比例当成硬指标生搬硬套。后续做片脚本不会校验这份参考文件,也不会因为它的存在而改变任何检查结果。

U/ 目录下的 reference_breakdown.json 与 reference_frames/ 抽帧拼图包含原片剧情事实与画面,仅供本机拆片使用,切勿复制进新项目或提交到公共仓库。

6. 能力边界

  • 全程纯本地计算,不调用 MiMo 或任何大模型,不修改上游视频理解产物,也不给成片好坏打分或计算“新片与参考片的差距”。
  • 镜头切点基于 ffmpeg scdet 分数加人工看图复核:慢速叠化转场无法被算法自动检出;间隔不足 0.3 秒的连续快切、恰好卡在 soft_score 临界线上的切点(不同 ffmpeg 版本可能存在微小浮点差异)、以及剧烈运动后突入暗场的硬切(得分可能低于 1.0)都不会直接算作自动切点,而是收进 shots.review_windows 交由 frames --review 人工看图确认。
  • 旁白占比与语速属于 labeled 级别精度:由人工标注的音轨区间结合 ASR 分段转写估算得出,不等同于逐字对轴的时间戳。
  • 防剧透泄漏扫描基于字面字符串比对,Agent 落笔时仍需主动自查,确保 methods 只写通用剪辑与叙事手法,不带入原片故事梗概。
from this repository

More skills

All skills
zenstory-ai
Community

video-recap

把一段或多集视频做成带画框字幕的中文解说成片或纯原声高光短片。用户提供 .mp4 / .mov / .mkv / .webm,要求做影视解说、短剧二创、加旁白配音、跨集混剪或导出剪映草稿时使用;串联完成看片识台词、定主线与留原声、按台词停顿切镜头、写词检查、TTS 配音与混音加字幕。触发词:视频解说、影视解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narration、recap。

1h installs
1
GitHub stars
645
Updated
Nov 20
zenstory-ai
Community

video-assemble

合成视频解说最终成片:把旁白音频铺到源视频上,按旁白窗口压低原声,生成 SRT / ASS 字幕并可烧录, 最后做响度标准化。作为最终合成阶段使用。输入源视频、ttsmeta.json 与旁白位置; 输出 recap 成片和字幕。触发词:视频合成、混音、字幕、压字幕、assemble video、mux、ducking、subtitles、成片。

1h installs
1
GitHub stars
606
Updated
Nov 6
zenstory-ai
Community

video-cut

把长视频按 Agent 选择的原片区间剪成短片。作为两阶段创作流程中的剪辑环节,读取 clipplan.json 与源视频, 输出 editedsource.mp4;随后 Agent 按输出时间线写 narration.json。支持单视频与多视频(sources manifest)拼剪, 本工具不读取、不映射旁白。 触发词:视频剪辑、剪辑式解说、video cut、clip plan、拼剪。

1h installs
1
GitHub stars
606
Updated
Nov 6
zenstory-ai
Community

video-understanding

把视频分析为结构化理解索引:场景检测、ASR 转写、逐场景 VLM 观察、静音窗口、融合时间线和写作 brief。 用于理解、索引或总结视频,也作为后续创作前的分析阶段。输入视频文件;输出 scenes.json、 asrresult.json、vlmanalysis.json、silenceperiods.json、timelinefusion.json、agentnarrationbrief.md。 触发词:视频理解、视频分析、视频索引、video understanding、analyze video、看懂视频。

1h installs
1
GitHub stars
606
Updated
Nov 6