zenstory-ai/video-recap-skills

video-understanding

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

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/zenstory-ai/video-recap-skills --skill video-understanding

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

1. 定位

本技能把源视频转成 Agent 与下游阶段可读取的理解索引,以素材观察员 / 场记的角色记录证据:

  • 先观察,再解释;事实与推断分开。
  • 除了“发生了什么”,还要让下游看见知识、权力、目标、关系或情绪在哪一刻变化。
  • 标出由谁的 POV 承载变化、哪个反应或表演不可替代,以及哪里存在完整台词/动作的自然剪辑边界。
  • 证据不足时保留不确定性,不制造戏剧结论。

2. 处理阶段

  1. 场景检测:写 scenes.json,包含切点、时长和废片段过滤结果。
  2. 抽帧:为视觉分析提取代表帧。
  3. ASR:通过 mimo-v2.5-asr 写粗分段对白 asr_result.json,并写

asr_timing_evidence.json 说明可用性、有限时间精度与文本修正来源。

  1. 静音检测:写 silence_periods.json,标注安静窗口与 has_speech。
  2. VLM 观察:写 vlm_analysis.json,包含场景描述、深层分析和 frame_facts。
  3. 时间线融合与创作 brief:写 timeline_fusion.json、asr_writing_chunks.json 和 agent_narration_brief.md。

各阶段只有在输出产物与 provenance sidecar 同时匹配当前视频及影响结果的设置时才会复用;--force 强制重算。

3. 环境要求

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

ASR 使用 mimo-v2.5-asr;VLM 使用 mimo-v2.5。--skip-asr 可跳过对白转写,但完整理解仍需要 MIMO_API_KEY 运行 VLM。--mimo-video-overview 可开启按场景块的视频概览。未设置 key 时重跑会复用已缓存的转写、画面分析、概览与故事索引(key 决定的默认 endpoint 不参与比对);需要请求模型的 consolidation 记为 skipped_no_key,不发请求。缓存对不上(例如复制 work_dir 时没保留文件时间)而已有转写时,运行停下并保留转写:用 cp -p / cp -Rp / rsync -t 保留时间重新复制,或设置 key 后重跑(会重新转写)。不要用 --skip-asr 绕过,它会把现有转写替换成 []。

若 work_dir/background_research.json 存在,本技能会把剧情梗概和角色名折入 VLM 上下文;--context 可补充一条简短提示。

远程调用与本地读取

ASR 把分窗音频发给 MiMo ASR;逐场景 VLM 把代表帧、帧时间和分析提示发给 MiMo;启用 --mimo-video-overview 时,还会把按场景截取的视频片段发给 MiMo 视频模型。故事索引汇总和可选 ASR 清洗发送的是画面描述、转写与背景资料文字。

请求使用 MiMo 的 chat 接口。MIMO_API_URL 可指定地址;ASR 与视频概览可分别用 MIMO_ASR_API_URL、MIMO_VIDEO_API_URL 覆盖,凭据同样支持各自的 key。未覆盖时,按量 key 使用 https://api.xiaomimimo.com/v1,Token Plan key 使用 MIMO_TOKEN_PLAN_CLUSTER 选择的集群。逐场景帧分析与汇总使用 MIMO_API_KEY。

--skip-asr 只关闭音频转写,--no-consolidate 只关闭索引汇总;它们不会关闭 VLM。需要只在本地处理已有产物时,使用 --brief-only 或 --edited-storyboard-only,这两条路径不调用 API。

下面的 scripts/... 均相对于本技能目录。若执行器从仓库根目录启动,请给脚本路径加上本技能的绝对目录。

4. 运行命令

bash
python3 scripts/understand.py <video> --work-dir <work_dir> [选项]
选项默认作用
<video>必填源视频
--work-dir必填产物目录;不存在时创建
--context "..."空补充给 VLM 的简短上下文(节目名、角色名),与 background_research.json 合并
--scene-threshold0.1场景检测阈值
--style纪录片写进创作简报的解说风格
`--edit-mode full\cut`不设写进简报的 recap 模式;cut 时按剪后时长估算旁白预算,已有 edited_source.mp4 时句末锚点改用剪后时间
--target-duration不设写进简报的 cut 目标时长;尚无 clip_plan_validated.json 时用它估算旁白预算
--skip-asr关不转写对白,把 asr_result.json 写成 [](已有转写会被覆盖),ASR 证据标为显式跳过
--mimo-video-overview关按场景块运行 MiMo 视频概览,并作为逐场景主描述
--force关忽略缓存,全部重算
--brief-only关只用现有产物重建 agent_narration_brief.md,不抽帧、不调 API
--edited-storyboard-only关只按 clip_plan_validated.json 写剪后时间线 storyboard/edited_storyboard.*,并在已有的 agent_narration_brief.md 顶部加 storyboard 指引;多源计划(带 sources)从各来源 source_work_dir 的 frames/ 按其 frames_manifest.json 的 fps 取帧,tile 标 S1/S2…;不抽帧、不调 API,故事板生成失败只记日志。与 --brief-only 互斥
--consolidate / --no-consolidate开生成全局故事索引 understanding_index.*
--consolidate-asr关另外清洗 ASR 文本,写 asr_clean.json

5. 输出契约

默认运行写出下表产物;各阶段产物旁的 *.meta.json 是缓存 provenance sidecar。

文件内容
frames/frame_*.jpg、frames_manifest.json按 fps 抽出的帧及其清单
scenes.json场景切点、起止时间与时长
audio.wav16 kHz 单声道音频,供 ASR、静音检测与句末锚点使用
asr_result.json[{start, end, text}] 时间戳对白
asr_timing_evidence.jsonASR 可用性状态、粗窗口精度、glossary 前后文本,以及它所描述的源视频/音频/结果文件(路径存在性 + size/mtime)
silence_periods.json[{start, end, duration, has_speech}] 安静窗口
speech_boundary_anchors.jsonASR 句末标点对齐到短停顿的句末锚点;缺音频或 ASR 时 status: unavailable
vlm_analysis.json逐场景描述、深层分析与 frame_facts
mimo_video_overview.status.json视频概览状态(未启用时为 disabled);启用成功另写 mimo_video_overview.json
understanding_index.json、understanding_index.md全局故事索引(--no-consolidate 时不写)
consolidation.status.json故事索引与 ASR 清洗的运行状态
storyboard/source_storyboard.{json,jpg}原片时间线抽帧拼图(超页时续写 _001.jpg 等);已有 clip_plan_validated.json 时另写 edited_storyboard.*;STORYBOARD=0 关闭
timeline_fusion.jsonVLM、ASR 与静音信息的统一时间线
asr_writing_chunks.json按句界和场景切分的 ASR 写作块
agent_narration_brief.mdAgent 首先阅读的创作简报

后续写作阶段根据创作简报与索引制定方案并写 narration.json。

6. 参考资料

  • 背景调研:references/research-guide.md,产出 background_research.json。
  • JSON 结构:references/data-schema.md。

7. 能力边界

  • 不写解说词,也不做解说评分;只负责生成理解索引与创作简报。
  • 不编造信号无法支持的剧情;当 ASR / VLM 过薄时输出素材警告。
  • MiMo ASR 的 start/end 是固定分片形成的粗窗口,不是词级对齐;空文本只表示原因未知,

不能当作已证实静音。asr_timing_evidence.json 的状态字段见 references/data-schema.md。

같은 저장소의 Skills

더 많은 Skills

모든 Skills
zenstory-ai
커뮤니티

video-recap

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

1시간 설치 수
1
GitHub Stars
645
업데이트
11월 20일
zenstory-ai
커뮤니티

video-reference

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

1시간 설치 수
1
GitHub Stars
643
업데이트
11월 19일
zenstory-ai
커뮤니티

video-assemble

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

1시간 설치 수
1
GitHub Stars
606
업데이트
11월 6일
zenstory-ai
커뮤니티

video-cut

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

1시간 설치 수
1
GitHub Stars
606
업데이트
11월 6일