zenstory-ai/video-recap-skills / skills/video-recap
video-recap
Verified把一段或多集视频做成带画框字幕的中文解说成片或纯原声高光短片。用户提供 .mp4 / .mov / .mkv / .webm,要求做影视解说、短剧二创、加旁白配音、跨集混剪或导出剪映草稿时使用;串联完成看片识台词、定主线与留原声、按台词停顿切镜头、写词检查、TTS 配音与混音加字幕。触发词:视频解说、影视解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narration、recap。
scripts/recap_inspect.py
View on GitHub#!/usr/bin/env python3
"""video-recap inspect — advisory, read-only orientation over a recap work_dir.
Reads ONLY the JSON artifacts already in work_dir (no ffmpeg, no frame reads, no video
probing, no new deps, no cross-skill import). A missing artifact is the legitimate
"that stage has not run yet" state and is reported as such.
Two subcommands:
state summarize the work_dir: source video, full|cut mode, which stage
artifacts are present vs missing, which file is the NEXT pause the pipeline waits
on, stale-manifest risk, and storyboard path(s) if present.
clip-map read clip_plan_validated.json and map a queried OUTPUT window to its SOURCE
window(s) with the inverse of the affine map cut.py uses
(source = clip.source_start + (out - clip.output_start), clamped to the clip),
reimplemented locally. Flags cross-clip boundaries.
Output: markdown by default; --json for machine-readable; long free text is truncated
unless --full is passed.
"""
import argparse
import json
from pathlib import Path
from lib import load_json, read_json_object
# --- artifact catalog --------------------------------------------------------
# Stage artifacts probed by `state`. Order = rough pipeline order.
_UNDERSTANDING_ARTIFACTS = [
"scenes.json",
"asr_result.json",
"silence_periods.json",
"speech_boundary_anchors.json",
"vlm_analysis.json",
"agent_narration_brief.md",
]
_CUT_ARTIFACTS = [
"multi_source_manifest.json",
"clip_plan.json",
"clip_plan_validated.json",
"edited_source.mp4",
]
_SCRIPT_ARTIFACTS = [
"narration.json",
"narration_lint.json",
"original_subtitles.json",
]
_RENDER_ARTIFACTS = [
"packaging_plan.json",
"promo_copy.json",
"tts_meta.json",
"timeline.json",
"subtitles.srt",
"subtitles.ass",
"assembly_manifest.json",
"cover.jpg",
]
_STORYBOARD_ARTIFACTS = [
"storyboard/source_storyboard.json",
"storyboard/edited_storyboard.json",
]
_COMPACT_TEXT_LIMIT = 80
def _truncate(text, compact):
text = str(text or "").strip()
if not compact or len(text) <= _COMPACT_TEXT_LIMIT:
return text
return text[: _COMPACT_TEXT_LIMIT - 1] + "…"
def _load_optional(path):
"""The artifact's JSON, or None when the stage that writes it has not run yet.
A present-but-corrupt artifact raises: every file probed here is written by this
pipeline or a sibling skill under its documented contract."""
path = Path(path)
return load_json(path) if path.exists() else None
def _fmt_seconds(value):
"""mm:ss.ss for a seconds value."""
sign = "-" if value < 0 else ""
total = abs(value)
return f"{sign}{int(total // 60):02d}:{total % 60:05.2f}"
# --- source video discovery --------------------------------------------------
def _discover_source(work_dir):
"""Find the source video path by reading recap artifacts, most authoritative first.
Returns {path, origin} with path=None + origin="unknown" when nothing records it."""
work_dir = Path(work_dir)
# 1. recap_run_manifest.json — canonical: written before the first pause with both fields.
# A multi-source manifest carries `sources` instead of `source_video`.
data = _load_optional(work_dir / "recap_run_manifest.json")
if isinstance(data, dict) and data.get("source_video"):
return {"path": data["source_video"], "origin": "recap_run_manifest.json"}
# 2. assembly_manifest.json — late stage; carries input_video (+ source_video in cut mode).
data = _load_optional(work_dir / "assembly_manifest.json")
if isinstance(data, dict):
src = data.get("source_video") or data.get("input_video")
if src:
return {"path": src, "origin": "assembly_manifest.json"}
# 3. edited_source.mp4.meta.json — cut.py records sources: {path: {size, mtime_ns}};
# a single-source cut has exactly one entry.
data = _load_optional(work_dir / "edited_source.mp4.meta.json")
sources = data.get("sources") if isinstance(data, dict) else None
if isinstance(sources, dict) and len(sources) == 1:
(path,) = sources
return {"path": path, "origin": "edited_source.mp4.meta.json"}
return {"path": None, "origin": "unknown"}
def _discover_multi_source(work_dir):
data = _load_optional(Path(work_dir) / "multi_source_manifest.json")
if not isinstance(data, dict) or not isinstance(data.get("sources"), list):
return None
return {"schema_version": data.get("schema_version"), "sources": data["sources"]}
# --- affine map -----------------------------------------------------------
def _output_to_source(out, clip):
"""Inverse of the forward affine map (same slope, clamped to the clip's source span)."""
mapped = clip["source_start"] + (out - clip["output_start"])
return round(max(clip["source_start"], min(mapped, clip["source_end"])), 3)
def _overlap(a0, a1, b0, b1):
"""Intersection [lo, hi] of two closed ranges, or None when they do not overlap.
A zero-width query (a0 == a1, e.g. --output-start 10 --output-end 10) is treated as a
POINT lookup: it returns (a0, a0) when the point lies within [b0, b1], so a point that sits
inside a clip is reported instead of silently falling through to "not in any clip".
"""
if a0 == a1:
return (a0, a0) if b0 <= a0 <= b1 else None
lo, hi = max(a0, b0), min(a1, b1)
return (lo, hi) if hi > lo else None
# --- state subcommand --------------------------------------------------------
def _present(work_dir, name):
return (Path(work_dir) / name).exists()
def _detect_mode(work_dir):
"""cut when any cut artifact is present or the run manifest says so (pass 1 has written
no cut artifact yet), else full."""
if any(_present(work_dir, n) for n in _CUT_ARTIFACTS):
return "cut"
settings = (read_json_object(Path(work_dir) / "recap_run_manifest.json") or {}).get("settings")
return "cut" if isinstance(settings, dict) and settings.get("edit_mode") == "cut" else "full"
def _uses_narration(work_dir):
manifest = read_json_object(Path(work_dir) / "recap_run_manifest.json") or {}
audio = manifest.get("audio")
mode = audio.get("mode") if isinstance(audio, dict) else None
if mode is None:
mode = (read_json_object(Path(work_dir) / "assembly_manifest.json") or {}).get("audio_mode")
return mode in (None, "narration")
def _next_pause(work_dir, mode):
"""The artifact the pipeline is currently waiting on the agent to write, or None when the
next-needed input is already present. Mirrors recap.py's two-pause cut flow / single-pause full
flow purely from file presence and audio mode (advisory; the orchestrator owns the real decision)."""
if mode == "cut" and not _present(work_dir, "clip_plan.json"):
return ("clip_plan.json", "pass1: 写剪辑计划(只写 clip_plan.json)")
if _uses_narration(work_dir) and not _present(work_dir, "narration.json"):
if mode == "cut":
return ("narration.json", "pass2: 对着剪好的成片用 OUTPUT 时间轴写解说")
return ("narration.json", "写解说 narration.json")
return None
def _stale_manifest_note(work_dir, mode):
"""Advisory stale-manifest risks read purely from file presence. Surfaces the two desync traps recap.py guards: a cut
narration without the phase ledger that ties it to a clip_plan, and a missing run manifest."""
notes = []
if not _present(work_dir, "recap_run_manifest.json"):
notes.append("缺少 recap_run_manifest.json:无法证明 work_dir 属于当前视频/参数(resume 会被拒绝)。")
if mode == "cut" and _present(work_dir, "narration.json") and not _present(work_dir, "recap_phase.json"):
notes.append("有 narration.json 但缺少 recap_phase.json:无法判断解说是否对当前剪辑写的(可能 stale)。")
return notes
def _present_storyboards(work_dir):
return [n for n in _STORYBOARD_ARTIFACTS if _present(work_dir, n)]
def cmd_state(work_dir, compact=None):
del compact
work_dir = Path(work_dir)
if not work_dir.exists():
return {"error": f"work_dir 不存在: {work_dir}"}
mode = _detect_mode(work_dir)
groups = {
"understanding": _UNDERSTANDING_ARTIFACTS,
"cut": _CUT_ARTIFACTS,
"script": _SCRIPT_ARTIFACTS,
"render": _RENDER_ARTIFACTS,
}
artifacts = {
group: {
"present": [n for n in names if _present(work_dir, n)],
"missing": [n for n in names if not _present(work_dir, n)],
}
for group, names in groups.items()
}
pause = _next_pause(work_dir, mode)
return {
"work_dir": str(work_dir),
"mode": mode,
"source_video": _discover_source(work_dir),
"multi_source": _discover_multi_source(work_dir),
"next_pause": {"artifact": pause[0], "hint": pause[1]} if pause else None,
"artifacts": artifacts,
"storyboards": _present_storyboards(work_dir),
"stale_manifest_notes": _stale_manifest_note(work_dir, mode),
}
def _render_state_md(state, compact):
if "error" in state:
return state["error"]
lines = [f"# recap work_dir 状态: {state['work_dir']}", ""]
lines.append(f"模式: **{state['mode']}**")
src = state["source_video"]
lines.append(f"源视频: {_truncate(src['path'] or 'unknown', compact)} (来源 {src['origin']})")
if state["multi_source"]:
lines.append("多源素材:")
for s in state["multi_source"]["sources"]:
lines.append(
f" - {s['source_id']}: {_truncate(s['source_path'], compact)} "
f"(work_dir {s['source_work_dir']}, material {s['material_id']})"
)
lines.append("")
if state["next_pause"]:
np = state["next_pause"]
lines.append(f"下一步暂停 → 等待写入 **{np['artifact']}** ({np['hint']})")
else:
lines.append("下一步暂停 → 无(所需输入已就绪,可继续 voiceover/assemble)")
lines.append("")
lines.append("## 各阶段产物")
for group, label in (("understanding", "理解"), ("cut", "剪辑"),
("script", "解说"), ("render", "渲染")):
info = state["artifacts"][group]
lines.append(f"### {label}")
lines.append(f" 有: {', '.join(info['present']) or '(无)'}")
lines.append(f" 缺: {', '.join(info['missing']) or '(无)'}")
lines.append("")
if state["storyboards"]:
lines.append("## storyboard")
for s in state["storyboards"]:
lines.append(f" - {s}")
lines.append("")
lines.append("## stale-manifest 风险")
if state["stale_manifest_notes"]:
for n in state["stale_manifest_notes"]:
lines.append(f" ⚠️ {n}")
else:
lines.append(" 无明显 stale 风险。")
return "\n".join(lines)
# --- clip-map subcommand -----------------------------------------------------
def cmd_clip_map(work_dir, output_start, output_end, compact):
work_dir = Path(work_dir)
validated = work_dir / "clip_plan_validated.json"
if not validated.exists():
return {"error": "clip_plan_validated.json 不存在:这不是 cut 运行,或剪辑计划尚未被 cut.py 校验。"
"(full 模式没有源↔输出映射;cut 模式请先跑 cut.py。)"}
# cut.py writes {"clips": [{clip_id, source_start, source_end, output_start,
# output_end, duration, reason}]} (cut_contract); source_id/source_path only for
# multi-source cuts.
clips = load_json(validated)["clips"]
if not clips:
return {"error": "clip_plan_validated.json 没有有效的 clip。"}
if output_start is None and output_end is None:
return {"error": "请用 --output-start/--output-end 指定要查询的窗口。"}
source_keys = {(c.get("source_id"), c.get("source_path")) for c in clips}
source_span = (
[min(c["source_start"] for c in clips), max(c["source_end"] for c in clips)]
if len(source_keys) == 1
else None
)
return {
"work_dir": str(work_dir),
"clip_count": len(clips),
"source_span": source_span,
"output_span": [clips[0]["output_start"], clips[-1]["output_end"]],
"queries": [_map_output_window(output_start, output_end, clips, compact)],
}
def _segment(clip, *, source, output, compact):
# source_id/source_path are only written for multi-source cuts.
return {
"clip_id": clip["clip_id"],
"source_id": clip.get("source_id"),
"source_path": clip.get("source_path"),
"output": output,
"source": source,
"reason": _truncate(clip["reason"], compact),
}
def _map_output_window(out_start, out_end, clips, compact):
"""Map a queried OUTPUT window to its SOURCE window(s), one per touched clip."""
out_lo = clips[0]["output_start"] if out_start is None else out_start
out_hi = clips[-1]["output_end"] if out_end is None else out_end
if out_hi < out_lo:
out_lo, out_hi = out_hi, out_lo
segments = []
for clip in clips:
ov = _overlap(out_lo, out_hi, clip["output_start"], clip["output_end"])
if not ov:
continue
segments.append(_segment(
clip,
output=[round(ov[0], 3), round(ov[1], 3)],
source=[_output_to_source(ov[0], clip), _output_to_source(ov[1], clip)],
compact=compact,
))
return {
"direction": "output→source",
"query": [round(out_lo, 3), round(out_hi, 3)],
"clips_touched": [s["clip_id"] for s in segments],
"cross_clip_boundary": len(segments) > 1,
"segments": segments,
}
def _render_clip_map_md(result, compact):
if "error" in result:
return result["error"]
lines = [f"# clip-map: {result['work_dir']}", ""]
src_label = (
f"源 {_fmt_seconds(result['source_span'][0])}–{_fmt_seconds(result['source_span'][1])}"
if result["source_span"] is not None
else "多源输入"
)
lines.append(
f"{result['clip_count']} clips · {src_label} · "
f"输出 {_fmt_seconds(result['output_span'][0])}–{_fmt_seconds(result['output_span'][1])}")
for q in result["queries"]:
lines.append("")
lines.append(f"## {q['direction']} 查询 "
f"{_fmt_seconds(q['query'][0])}–{_fmt_seconds(q['query'][1])}")
if q["cross_clip_boundary"]:
lines.append(f" ⚠️ 跨剪辑边界(涉及 clip {q['clips_touched']})")
if not q["segments"]:
lines.append(" (该窗口不落在任何保留片段内)")
for s in q["segments"]:
src = f"{_fmt_seconds(s['source'][0])}–{_fmt_seconds(s['source'][1])}"
out = f"{_fmt_seconds(s['output'][0])}–{_fmt_seconds(s['output'][1])}"
reason = f" 〔{s['reason']}〕" if s["reason"] else ""
sid = f" {s['source_id']}" if s["source_id"] else ""
spath = f" `{_truncate(s['source_path'], compact)}`" if s["source_path"] else ""
lines.append(f" clip {s['clip_id']}{sid}{spath}: 源 {src} ↔ 输出 {out}{reason}")
return "\n".join(lines)
# --- CLI ---------------------------------------------------------------------
def main(argv=None):
parser = argparse.ArgumentParser(
prog="recap_inspect.py",
description="Advisory read-only inspection of a video-recap work_dir (pure JSON).")
parser.add_argument("--work-dir", required=True, help="recap work_dir to inspect")
parser.add_argument("--json", action="store_true", help="machine-readable JSON output")
parser.add_argument("--full", dest="compact", action="store_false", default=True,
help="do not truncate long free text (truncated by default)")
sub = parser.add_subparsers(dest="command", required=True)
sub.add_parser("state", help="summarize work_dir + the next pause the pipeline is waiting on")
cm = sub.add_parser("clip-map", help="map an OUTPUT window to its SOURCE window(s)")
cm.add_argument("--output-start", type=float, default=None)
cm.add_argument("--output-end", type=float, default=None)
args = parser.parse_args(argv)
if args.command == "state":
result = cmd_state(args.work_dir)
rendered = _render_state_md(result, args.compact)
else:
result = cmd_clip_map(args.work_dir, args.output_start, args.output_end, args.compact)
rendered = _render_clip_map_md(result, args.compact)
if args.json:
print(json.dumps(result, ensure_ascii=False, indent=2))
else:
print(rendered)
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |