zenstory-ai/video-recap-skills / skills/video-recap
video-recap
Verified把一段或多集视频做成带画框字幕的中文解说成片或纯原声高光短片。用户提供 .mp4 / .mov / .mkv / .webm,要求做影视解说、短剧二创、加旁白配音、跨集混剪或导出剪映草稿时使用;串联完成看片识台词、定主线与留原声、按台词停顿切镜头、写词检查、TTS 配音与混音加字幕。触发词:视频解说、影视解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narration、recap。
scripts/dashboard/runs.py
View on GitHub"""Server-side views of one recap work_dir for the read-only dashboard.
Each stage view parses its own artifact (clip_plan_validated.json, narration.json,
timeline.json, QC reports, resource_lock.json) into plain rows the UI only lays out.
A missing artifact is "that stage has not run"; an unreadable one becomes
``{"status": "unparseable", "error", "raw"}`` for that view alone. Run state itself comes
from ``recap_inspect.cmd_state``. Media is only what the run declares: the
``assembly_manifest.json`` ``final_output`` and the cut stage's ``edited_source.mp4``.
"""
from __future__ import annotations
import math
import os
from pathlib import Path, PurePosixPath, PureWindowsPath
import recap_inspect
from dashboard.io import (RUN_FILE, dir_of, media_entry, nearest, raw_text,
read_json, read_object, unreadable_reason)
# Files cmd_state parses; each must stay under the JSON cap before it is handed over.
STATE_MANIFEST_FILES = (
RUN_FILE,
"assembly_manifest.json",
"edited_source.mp4.meta.json",
"multi_source_manifest.json",
)
QC_FILES = (
("final_qc.json", "成片 QC"),
("assembly_qc.json", "合成 QC"),
)
STAGES = (("home", "概况"), ("understanding", "理解"), ("cut", "剪辑"), ("narration", "旁白"),
("film", "成片"), ("qc", "QC"), ("resources", "资源"))
GENERIC_DIR_NAMES = {"work", "work_dir", "workdir", "artifacts", "out", "output"}
MAX_FINDINGS = 20
def is_material_artifact(rel: str) -> bool:
parts = PurePosixPath(rel).parts
return len(parts) >= 3 and parts[-3] == "materials" and parts[-1] == "artifacts"
def _display_title(root: Path, rel: str) -> str:
"""Human-readable run title: promote parent folder when work_dir uses a generic name."""
if rel == ".":
return root.name
parts = PurePosixPath(rel).parts
leaf = parts[-1]
if len(parts) >= 2:
parent_name = parts[-2]
if leaf in GENERIC_DIR_NAMES:
return parent_name
if leaf.endswith("_work") and len(leaf) > 5:
return f"{parent_name} · {leaf[:-5].replace('_', ' ')}"
return leaf or root.name
def _fallback(path: Path, error: str) -> dict:
return {"status": "unparseable", "error": error, "raw": raw_text(path)}
def _num(value) -> float:
if isinstance(value, bool) or not isinstance(value, (int, float)):
raise ValueError(f"不是数字: {value!r}")
return float(value)
def _run_state_with_culprit(rdir: Path) -> tuple[dict | None, str | None, str | None]:
# recap_inspect only parses these four manifest files; ignore large analysis JSONs.
for name in STATE_MANIFEST_FILES:
path = rdir / name
if not os.path.lexists(path):
continue
reason = unreadable_reason(path)
if reason:
return None, f"{name} {reason}", name
try:
return recap_inspect.cmd_state(rdir), None, None
except (OSError, ValueError, KeyError, TypeError, AttributeError) as exc:
culprit = RUN_FILE
for name in STATE_MANIFEST_FILES:
path = rdir / name
if os.path.lexists(path) and read_json(path)[1] is not None:
culprit = name
break
return None, f"无法解析运行状态: {exc}", culprit
def run_state(rdir: Path):
state, error, _ = _run_state_with_culprit(rdir)
return state, error
def _audio_mode(rdir: Path) -> str:
manifest, _ = read_object(rdir / RUN_FILE)
audio = (manifest or {}).get("audio")
mode = audio.get("mode") if isinstance(audio, dict) else None
return mode if isinstance(mode, str) else "narration"
# --- stage views -------------------------------------------------------------------------
def cut_view(rdir: Path) -> dict:
path = rdir / "clip_plan_validated.json"
if not path.is_file():
pending = (rdir / "clip_plan.json").is_file()
return {"status": "pending" if pending else "missing"}
data, error = read_object(path)
if error:
return _fallback(path, error)
try:
clips = []
for index, clip in enumerate(data["clips"]):
reason = str(clip.get("reason") or "")
clips.append({
"index": index, "id": clip.get("clip_id", index), "source_id": clip.get("source_id"),
"source_start": _num(clip["source_start"]), "source_end": _num(clip["source_end"]),
"output_start": _num(clip["output_start"]), "output_end": _num(clip["output_end"]),
"reason": reason, "beat": reason.split("|")[0].strip(),
})
except (KeyError, TypeError, ValueError, AttributeError) as exc:
return _fallback(path, f"剪辑片段字段不完整: {exc}")
qc = data.get("qc") if isinstance(data.get("qc"), dict) else {}
blocking = [{"code": str(b.get("code", "")), "message": str(b.get("message", ""))}
for b in qc.get("blocking", []) if isinstance(b, dict)] if isinstance(qc.get("blocking"), list) else []
total = data.get("total_duration")
return {"status": "ok", "clips": clips, "blocking": blocking,
"total": total if isinstance(total, (int, float)) else (clips[-1]["output_end"] if clips else 0),
"target": data.get("target_duration") if isinstance(data.get("target_duration"), (int, float)) else None,
"sources": sorted({c["source_id"] for c in clips if c["source_id"]})}
def narration_view(rdir: Path) -> dict:
path = rdir / "narration.json"
if not path.is_file():
return {"status": "missing"}
data, error = read_json(path)
if error:
return _fallback(path, error)
segments = data.get("segments") if isinstance(data, dict) else data
try:
rows = [{"index": i, "start": _num(s["start"]), "end": _num(s["end"]),
"text": str(s.get("narration") or s.get("text") or ""),
"overlaps_speech": s.get("overlaps_speech") is True}
for i, s in enumerate(segments)]
except (KeyError, TypeError, ValueError, AttributeError) as exc:
return _fallback(path, f"旁白段落字段不完整: {exc}")
tts = None
meta, meta_error = read_object(rdir / "tts_meta.json") if (rdir / "tts_meta.json").is_file() else (None, None)
if meta is not None:
failures = meta.get("failures") if isinstance(meta.get("failures"), list) else []
tts = {"engine": meta.get("engine"), "partial": meta.get("partial") is True, "failures": len(failures)}
elif meta_error:
tts = {"error": meta_error}
return {"status": "ok", "segments": rows, "chars": sum(len(r["text"]) for r in rows), "tts": tts}
def _track_rows(track: dict, key: str) -> list:
rows = []
for item in track.get(key) or []:
if not isinstance(item, dict):
continue
start, end = _num(item["timeline_start"]), _num(item["timeline_end"])
label = str(item.get("text") or Path(str(item.get("source_path") or "")).name)
rows.append({"start": start, "end": end, "label": label})
return rows
def timeline_view(rdir: Path) -> dict:
path = rdir / "timeline.json"
if not path.is_file():
return {"status": "missing"}
data, error = read_object(path)
if error:
return _fallback(path, error)
lanes = {"video": [], "narration": [], "bgm": [], "subtitles": []}
try:
for track in data["tracks"]:
kind, role = track.get("kind"), track.get("role") or track.get("name")
if kind == "video":
lanes["video"] += _track_rows(track, "clips")
elif kind == "audio" and role in ("narration", "bgm"):
lanes[role] += _track_rows(track, "segments")
elif kind == "text":
lanes["subtitles"] += _track_rows(track, "segments")
except (KeyError, TypeError, ValueError, AttributeError) as exc:
return _fallback(path, f"时间线字段不完整: {exc}")
ends = [row["end"] for rows in lanes.values() for row in rows]
duration = data.get("duration") if isinstance(data.get("duration"), (int, float)) else max(ends, default=0)
canvas = data.get("canvas") if isinstance(data.get("canvas"), dict) else None
return {"status": "ok", "duration": duration, "canvas": canvas, "lanes": lanes}
def final_video(root: Path, rdir: Path) -> dict | None:
"""The video ``assembly_manifest.json`` binds as ``final_output``; never guessed by name."""
path = rdir / "assembly_manifest.json"
if not path.is_file():
return None
manifest, error = read_object(path)
if error:
return {"path": None, "name": "assembly_manifest.json", "note": error}
output = manifest.get("final_output")
if not isinstance(output, str) or not output:
return None
declared = Path(output) if Path(output).is_absolute() else rdir / output
return media_entry(root, declared) or {
"path": None, "name": declared.name, "note": "成片不在 --root 内或不存在,不提供预览"}
def _findings(data: dict) -> list:
rows = []
for item in data.get("findings") or []:
if isinstance(item, dict):
rows.append({"code": str(item.get("code", "")), "message": str(item.get("message", "")),
"blocking": item.get("blocking") is True})
rows.sort(key=lambda r: not r["blocking"])
return rows[:MAX_FINDINGS]
def _qc_card(rdir: Path, name: str, label: str) -> dict | None:
path = rdir / name
if not path.is_file():
return None
card = {"file": name, "label": label, "findings": []}
data, error = read_object(path)
if error:
return {**card, "level": "unparseable", "blockers": 0, "text": error}
if name == "assembly_qc.json":
verdict, codes = data.get("verdict"), data.get("blocking_codes") or []
if verdict == "PASS":
return {**card, "level": "ok", "blockers": 0, "text": "通过"}
if verdict == "FAIL":
detail = f":{', '.join(map(str, codes))}" if codes else ""
return {**card, "level": "error", "blockers": max(len(codes), 1), "text": f"未通过{detail}"}
return {**card, "level": "warn", "blockers": 0, "text": f"结论未知({verdict})"}
ok, count = data.get("ok"), data.get("blocker_count")
card["findings"] = _findings(data)
if ok is True and count == 0:
return {**card, "level": "ok", "blockers": 0, "text": "通过,无阻断项"}
if isinstance(count, int) and not isinstance(count, bool) and count > 0:
return {**card, "level": "error", "blockers": count, "text": f"{count} 个阻断项"}
return {**card, "level": "warn", "blockers": 0, "text": f"摘要不完整(ok={ok}, blocker_count={count})"}
def qc_cards(rdir: Path) -> list:
return [c for c in (_qc_card(rdir, name, label) for name, label in QC_FILES) if c]
def lock_view(rdir: Path) -> dict:
path = rdir / "resource_lock.json"
if not path.is_file():
return {"status": "missing"}
data, error = read_object(path)
if error:
return _fallback(path, error)
def rows(key):
value = data.get(key)
return [r for r in value if isinstance(r, dict)] if isinstance(value, list) else []
library = data.get("library")
resources = [{**entry, **_lock_file(entry), "registry": _registry(entry, library)} for entry in rows("resources")]
return {"status": "ok", "generated_at": data.get("generated_at"), "library": library,
"project": data.get("project") if isinstance(data.get("project"), dict) else None,
"templates": rows("templates"), "resources": resources, "attention": rows("attention")}
def _lock_file(entry: dict) -> dict:
"""File name and directory of a lock entry's path, split for display."""
path = entry.get("path")
if not isinstance(path, str) or not path:
return {"name": None, "dir": None}
pure = PureWindowsPath(path) if "\\" in path else PurePosixPath(path)
return {"name": pure.name, "dir": str(pure.parent)}
def _registry(entry: dict, library) -> str:
"""Where a resource is accounted for: the resource library, the material library (source
videos are never registered as resources, by design), unregistered, or not applicable."""
if entry.get("role") == "source_video":
return "material"
if isinstance(entry.get("library"), dict):
return "library"
if library and (entry.get("path") or entry.get("role") == "voice"):
return "unregistered"
return "none"
# --- stage bar ---------------------------------------------------------------------------
def _stage_bar(mode, audio_mode, state, views, qc) -> list:
"""Each stage's dot: ok, danger (must fix: QC or cut blockers), warn (advisory or unreadable),
todo (waiting for the agent) or "" (not reached)."""
pause = ((state or {}).get("next_pause") or {}).get("artifact")
understanding = ((state or {}).get("artifacts") or {}).get("understanding") or {"present": [], "missing": []}
total = len(understanding["present"]) + len(understanding["missing"])
cut, narration, film, lock = views["cut"], views["narration"], views["film"], views["resources"]
blockers = sum(c["blockers"] for c in qc)
cells = {
"home": ("", ""),
"understanding": ("ok" if "agent_narration_brief.md" in set(understanding["present"])
else "", f"{len(understanding['present'])}/{total}" if total else ""),
"cut": {"ok": ("danger" if cut.get("blocking") else "ok", f"{len(cut.get('clips', []))} 段"),
"pending": ("todo", "待校验"), "unparseable": ("warn", "无法解析"),
}.get(cut["status"], ("todo", "等剪辑计划") if pause == "clip_plan.json" else ("", "未剪")),
"narration": {"ok": ("warn" if (narration.get("tts") or {}).get("partial") else "ok",
f"{len(narration.get('segments', []))} 段"),
"unparseable": ("warn", "无法解析"),
}.get(narration["status"], ("todo", "等解说") if pause == "narration.json" else ("", "未写")),
"film": (("ok", _clock(film["timeline"].get("duration")) if film["timeline"]["status"] == "ok" else "已合成")
if (film["video"] or {}).get("path")
else ("warn", "无法预览") if film["video"] else ("", "未合成")),
"qc": (("danger", f"{blockers} 阻断") if blockers
else ("warn", "无法解析") if any(c["level"] == "unparseable" for c in qc)
else ("ok", "通过") if qc else ("", "未运行")),
"resources": {"ok": ("warn", f"{len(lock.get('attention', []))} 注意") if lock.get("attention")
else ("ok", f"{len(lock.get('resources', []))} 项"),
"unparseable": ("warn", "无法解析")}.get(lock["status"], ("", "无记录")),
}
shown = [key for key, _ in STAGES
if not (key == "cut" and mode != "cut") and not (key == "narration" and audio_mode != "narration")]
labels = dict(STAGES)
return [{"key": key, "label": labels[key], "state": cells[key][0], "meta": cells[key][1]} for key in shown]
def _clock(seconds) -> str:
if not isinstance(seconds, (int, float)) or seconds <= 0:
return "已合成"
whole = int(round(seconds))
return f"{whole // 60}:{whole % 60:02d}"
def storyboard_views(root: Path, rdir: Path, state: dict | None) -> list:
"""Contact-sheet images declared by storyboard JSON artifacts inside ``rdir``."""
items = []
seen = set()
resolved_rdir = rdir.resolve()
for rel_json in (state or {}).get("storyboards") or []:
if not isinstance(rel_json, str) or not rel_json:
continue
sb_path = (rdir / rel_json).resolve()
if sb_path.parent != resolved_rdir and resolved_rdir not in sb_path.parents:
continue
data, error = read_object(sb_path)
if error or not data:
continue
timeline = str(data.get("timeline") or "")
label = "剪后分镜板" if timeline == "output" else "原片分镜板" if timeline == "source" else sb_path.stem
tiles = len(data["tiles"]) if isinstance(data.get("tiles"), list) else 0
pages = data.get("page_images") if isinstance(data.get("page_images"), list) else []
for page in pages:
if not isinstance(page, str) or not page:
continue
media = media_entry(root, rdir / page)
if media and media["path"] not in seen:
seen.add(media["path"])
items.append({"label": label, "timeline": timeline, "tiles": tiles, "media": media})
return items
def _clean_str(value) -> str:
return value.strip() if isinstance(value, str) else ""
def _opt_nonneg_float(value) -> float | None:
if isinstance(value, bool) or not isinstance(value, (int, float)):
return None
num = float(value)
return round(num, 3) if math.isfinite(num) and num >= 0 else None
def promo_view(rdir: Path) -> dict:
"""Normalized promotional copy (`promo_copy.json`), safe for direct UI rendering."""
path = rdir / "promo_copy.json"
if not os.path.lexists(path):
return {"status": "missing"}
data, error = read_object(path)
if error:
return _fallback(path, error)
titles: list = []
raw_titles = data.get("titles")
if isinstance(raw_titles, list):
for item in raw_titles:
if isinstance(item, str) and item.strip():
titles.append(item.strip())
elif isinstance(item, dict):
text = _clean_str(item.get("text") or item.get("title"))
label = _clean_str(item.get("label") or item.get("type") or item.get("platform"))
if text:
titles.append({"label": label, "text": text} if label else text)
elif isinstance(raw_titles, str) and raw_titles.strip():
titles.append(raw_titles.strip())
raw_cover = data.get("cover")
cover = None
if isinstance(raw_cover, str) and raw_cover.strip():
cover = {"timestamp": None, "frame_reason": "", "top_line": "", "bottom_line": "", "text": raw_cover.strip()}
elif isinstance(raw_cover, dict):
ts = _opt_nonneg_float(raw_cover.get("timestamp"))
frame_reason = _clean_str(raw_cover.get("frame_reason"))
top_line = _clean_str(raw_cover.get("top_line"))
bottom_line = _clean_str(raw_cover.get("bottom_line"))
text = _clean_str(raw_cover.get("text") or raw_cover.get("title"))
if any((ts is not None, frame_reason, top_line, bottom_line, text)):
cover = {
"timestamp": ts,
"frame_reason": frame_reason,
"top_line": top_line,
"bottom_line": bottom_line,
"text": text,
}
raw_tags = data.get("tags")
tags = [s for item in raw_tags if isinstance(item, str) and (s := item.strip())] if isinstance(raw_tags, list) else []
return {
"status": "ok",
"core_angle": _clean_str(data.get("core_angle")),
"payoff_timestamp": _opt_nonneg_float(data.get("payoff_timestamp")),
"titles": titles,
"cover": cover,
"description": _clean_str(data.get("description") or data.get("summary")),
"tags": tags,
}
# --- runs --------------------------------------------------------------------------------
def run_views(root: Path, rel: str, runs: set) -> dict:
"""Everything the dashboard shows about one run; each view degrades on its own."""
rdir = dir_of(root, rel)
parent = nearest(rel, runs)
state, state_error, state_bad_file = _run_state_with_culprit(rdir)
mode = (state or {}).get("mode") or ("cut" if (rdir / "clip_plan.json").is_file() else "full")
audio_mode = _audio_mode(rdir)
qc = qc_cards(rdir)
edited = rdir / "edited_source.mp4"
promo = promo_view(rdir)
views = {
"cut": {**cut_view(rdir), "video": media_entry(root, edited) if mode == "cut" else None},
"narration": narration_view(rdir),
"film": {
"video": final_video(root, rdir),
"timeline": timeline_view(rdir),
"promo_copy": promo if promo["status"] == "ok" else None,
},
"resources": lock_view(rdir),
}
tl = views["film"]["timeline"]
cut = views["cut"]
raw_dur = tl.get("duration") if tl["status"] == "ok" else cut.get("total") if cut.get("status") == "ok" else None
duration = float(raw_dur) if isinstance(raw_dur, (int, float)) and raw_dur > 0 else None
video_info = views["film"]["video"] or {}
unparseable = [c["file"] for c in qc if c["level"] == "unparseable"]
unparseable += [name for name, view in (("clip_plan_validated.json", views["cut"]),
("narration.json", views["narration"]),
("timeline.json", views["film"]["timeline"]),
("promo_copy.json", promo),
("resource_lock.json", views["resources"]))
if view["status"] == "unparseable"]
if state_bad_file and state_bad_file not in unparseable:
unparseable.insert(0, state_bad_file)
return {
"path": rel, "name": rdir.name or root.name, "title": _display_title(root, rel),
"work_dir": str(rdir), "parent": parent,
"internal": bool(parent is not None or is_material_artifact(rel)),
"mode": mode, "audio_mode": audio_mode,
"duration": duration, "canvas": tl.get("canvas") if tl["status"] == "ok" else None,
"video_name": video_info.get("name") if video_info.get("path") else None,
"state": state, "state_error": state_error,
"next_pause": (state or {}).get("next_pause"),
"qc": qc, "blockers": sum(c["blockers"] for c in qc), "unparseable": unparseable,
"lock_attention": len(views["resources"].get("attention", [])),
"has_video": bool(video_info.get("path")),
"storyboards": storyboard_views(root, rdir, state),
"stages": _stage_bar(mode, audio_mode, state, views, qc),
"views": views,
}
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 |