zenstory-ai/video-recap-skills / skills/video-recap
video-recap
Verified把一段或多集视频做成带画框字幕的中文解说成片或纯原声高光短片。用户提供 .mp4 / .mov / .mkv / .webm,要求做影视解说、短剧二创、加旁白配音、跨集混剪或导出剪映草稿时使用;串联完成看片识台词、定主线与留原声、按台词停顿切镜头、写词检查、TTS 配音与混音加字幕。触发词:视频解说、影视解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narration、recap。
scripts/validate.py
View on GitHub#!/usr/bin/env python3
"""Narration validation entrypoint.
Validate an agent-written narration.json against the local speech timing evidence.
Validation never rewrites the agent's text, timing, order or metadata. Full-mode text
that does not fit its window fails lint and goes back to the author. full and cut_output
persist only the measured ``overlaps_speech`` ownership.
"""
import argparse
import json
import math
from pathlib import Path
from lib import log
from narration_lint import NarrationLintError, validate_narration_or_raise
from speech_ownership import _read_json, measure_narration_speech_ownership
def _valid_positive_duration(duration):
return (
duration is not None
and not isinstance(duration, bool)
and isinstance(duration, (int, float))
and math.isfinite(duration)
and duration > 0
)
def _validate_output_timeline_bounds(narration, duration, tolerance=0.05):
"""Hard-gate lint-validated cut_output narration against the rendered output timeline.
cut_output narration is authored in edited_source.mp4 time. If any segment falls outside
that media duration, fail before TTS/render instead of spending time on unusable audio.
"""
if not _valid_positive_duration(duration):
detail = (
f"{duration!r}"
if duration is None or isinstance(duration, bool) or not isinstance(duration, (int, float))
else f"{duration:.3f}"
)
raise SystemExit(
f"output_duration must be finite and positive, got output_duration={detail}"
)
problems = []
for idx, seg in enumerate(narration):
start, end = seg["start"], seg["end"]
if end <= -tolerance or start >= duration + tolerance:
problems.append(
f"段 {idx + 1} [{start:.3f},{end:.3f}] fully outside output_duration={duration:.3f}"
)
continue
if start < -tolerance:
problems.append(
f"段 {idx + 1} start={start:.3f} before output timeline (output_duration={duration:.3f})"
)
if end > duration + tolerance:
problems.append(
f"段 {idx + 1} end={end:.3f} exceeds output_duration={duration:.3f}"
)
if problems:
raise SystemExit(
"cut_output narration exceeds rendered output timeline: "
+ "; ".join(problems)
)
def main():
try:
_validate(_parse_args())
except NarrationLintError as exc:
# A lint failure is an ordinary result the author fixes from the summary,
# not a crash: exit non-zero with the summary only, no traceback.
raise SystemExit(str(exc)) from None
def _parse_args():
ap = argparse.ArgumentParser(
description="Validate agent-written narration.json and measure speech ownership."
)
ap.add_argument("--work-dir", required=True)
ap.add_argument("--mode", default="full", choices=["full", "cut_output"])
ap.add_argument(
"--output-duration",
type=float,
default=None,
help="cut_output: rendered edited_source.mp4 duration in seconds",
)
return ap.parse_args()
def _record_output_timeline_error(work_dir, report, message):
report["errors"].append({
"level": "error",
"index": None,
"code": "invalid_output_timeline",
"message": message,
})
report["ok"] = False
report["error_count"] = len(report["errors"])
(work_dir / "narration_lint.json").write_text(
json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8"
)
def _validate(args):
work_dir = Path(args.work_dir)
narration_path = work_dir / "narration.json"
narration = _read_json(narration_path)
if narration is None:
raise SystemExit(f"缺少 {narration_path};请先按 video-recap 规则写解说词")
cut_output = args.mode == "cut_output"
valid_duration = _valid_positive_duration(args.output_duration)
lint_duration = args.output_duration if (cut_output and valid_duration) else None
# Lint the authored shape first, then derive speech ownership (speech spans minus quiet
# windows) from the evidence and persist that measured flag for voiceover/assemble instead
# of trusting JSON.
try:
report = validate_narration_or_raise(
narration, None, mode=args.mode, work_dir=work_dir,
output_duration=lint_duration,
)
except NarrationLintError as exc:
if cut_output and not valid_duration:
msg = (
"--output-duration is required when --mode cut_output"
if args.output_duration is None
else f"output_duration must be finite and positive, got output_duration={args.output_duration:.3f}"
)
_record_output_timeline_error(work_dir, exc.report, msg)
raise
if cut_output:
try:
if args.output_duration is None:
raise SystemExit("--output-duration is required when --mode cut_output")
_validate_output_timeline_bounds(narration, args.output_duration)
except SystemExit as exc:
_record_output_timeline_error(work_dir, report, str(exc))
raise
narration = measure_narration_speech_ownership(narration, work_dir, mode=args.mode)
narration_path.write_text(
json.dumps(narration, ensure_ascii=False, indent=2), encoding="utf-8"
)
log(f"解说词验证完成: {len(narration)} 段")
print(
json.dumps(
{
"status": "validated",
"segments": len(narration),
"lint": str(work_dir / "narration_lint.json"),
},
ensure_ascii=False,
)
)
if __name__ == "__main__":
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 |