Skip to content

zenstory-ai/video-recap-skills / skills/video-recap

video-recap

Verified

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

FileKindSize
SKILL.mdskill md18.4 KB
assets/dashboard/app.jsscript16.2 KB
assets/dashboard/index.htmlother867 B
assets/dashboard/styles.cssother22.6 KB
assets/dashboard/tokens.cssother8.9 KB
assets/dashboard/views.jsscript31.4 KB
references/audio-modes.mdmarkdown3.6 KB
references/config-playbook.mdmarkdown8.1 KB
references/creative-editing-playbook.mdmarkdown12.3 KB
references/data-schema.mdmarkdown34.6 KB
references/index-tts.mdmarkdown2.1 KB
references/jianying/LICENSE.duo-videoother1.0 KB
references/jianying/SOURCE.mdmarkdown703 B
references/jianying/empty_draft_meta_info.jsonconfig1.7 KB
references/jianying/empty_jy_material_video.jsonconfig1.8 KB
references/jianying/empty_jy_meta_material_value.jsonconfig358 B
references/jianying/empty_jy_project_info.jsonconfig3.6 KB
references/jianying/empty_jy_segment.jsonconfig1.3 KB
references/jianying/empty_jy_text_styles.jsonconfig440 B
references/jianying/empty_yj_material_audio.jsonconfig865 B
references/jianying/empty_yj_material_text.jsonconfig2.4 KB
references/packaging.mdmarkdown6.8 KB
references/promotional-copy.mdmarkdown4.1 KB
references/prompt-templates.mdmarkdown2.0 KB
references/research-guide.mdmarkdown2.7 KB
references/resource-library.mdmarkdown12.1 KB
references/shot-review.mdmarkdown4.8 KB
scripts/agent_text.pyscript2.7 KB
scripts/artifacts.pyscript972 B
scripts/asr.pyscript12.5 KB
scripts/asr_timing_evidence.pyscript4.2 KB
scripts/assemble.pyscript31.0 KB
scripts/assemble_constants.pyscript894 B
scripts/assembly_contract.pyscript10.3 KB
scripts/assembly_settings.pyscript3.8 KB
scripts/audio_automation.pyscript6.6 KB
scripts/audio_mix.pyscript18.5 KB
scripts/briefing/__init__.pyscript101 B
scripts/briefing/builder.pyscript31.1 KB
scripts/briefing/context.pyscript6.1 KB
scripts/briefing/timeline.pyscript23.0 KB
scripts/codec_peak.pyscript5.1 KB
scripts/cut.pyscript148 B
scripts/cut_cli.pyscript12.4 KB
scripts/cut_contract.pyscript13.3 KB
scripts/cut_qc.pyscript1.9 KB
scripts/cut_render.pyscript13.2 KB
scripts/dashboard/__init__.pyscript159 B
scripts/dashboard/data.pyscript24.6 KB
scripts/dashboard/io.pyscript7.1 KB
scripts/dashboard/runs.pyscript21.8 KB
scripts/dashboard/templates.pyscript9.6 KB
scripts/dashboard_server.pyscript9.3 KB
scripts/detect.pyscript22.2 KB
scripts/doctor.pyexecutablescript12.9 KB
scripts/entry_suggestion.pyscript4.6 KB
scripts/export_jianying.pyscript5.6 KB
scripts/extract.pyscript2.5 KB
scripts/final_qc.pyscript19.0 KB
scripts/frame_grid.pyscript10.6 KB
scripts/jianying/__init__.pyscript49 B
scripts/jianying/builders.pyscript11.3 KB
scripts/jianying/model.pyscript2.7 KB
scripts/jianying/optional.pyscript1012 B
scripts/jianying/schema.pyscript2.5 KB
scripts/jianying/templates.pyscript1.0 KB
scripts/jianying/timeline_contract.pyscript5.8 KB
scripts/jianying/tracks.pyscript2.0 KB
scripts/jianying/writer.pyscript7.8 KB
scripts/lib.pyscript29.6 KB
scripts/library.pyscript31.1 KB
scripts/lint_summary.pyscript5.0 KB
scripts/loudness.pyscript14.7 KB
scripts/materials.pyscript22.1 KB
scripts/media.pyscript18.8 KB
scripts/narration_audio.pyscript13.5 KB
scripts/narration_lint.pyscript24.1 KB
scripts/narrative_selection.pyscript8.9 KB
scripts/packaging.pyscript6.1 KB
scripts/packaging_fonts.pyscript12.0 KB
scripts/packaging_plates.pyscript31.2 KB
scripts/packaging_studio.pyscript34.1 KB
scripts/providers/__init__.pyscript72 B
scripts/providers/fish_audio.pyscript3.1 KB
scripts/providers/index_tts.pyscript8.8 KB
scripts/recap.pyscript183 B
scripts/recap_cli.pyscript6.9 KB
scripts/recap_inspect.pyscript16.5 KB
scripts/recap_runner.pyscript22.0 KB
scripts/recap_runtime.pyscript11.8 KB
scripts/recap_source.pyscript1.8 KB
scripts/recap_stage_qc.pyscript2.7 KB
scripts/recap_timeline.pyscript7.7 KB
scripts/render_preflight.pyscript1.7 KB
scripts/resources/__init__.pyscript200 B
scripts/resources/lock.pyscript6.8 KB
scripts/resources/project_binding.pyscript16.1 KB
scripts/sentence_boundaries.pyscript28.8 KB
scripts/sentence_gate.pyscript8.6 KB
scripts/sfx_mix.pyscript14.6 KB
scripts/shot_review.pyscript18.9 KB
scripts/source_subtitles.pyscript7.2 KB
scripts/speech_ownership.pyscript9.3 KB
scripts/storyboard.pyscript21.8 KB
scripts/subtitles/__init__.pyscript56 B
scripts/subtitles/core.pyscript19.0 KB
scripts/subtitles/render.pyscript8.0 KB
scripts/timeline.pyscript8.2 KB
scripts/timeline_emit.pyscript5.4 KB
scripts/tts_audio.pyscript9.6 KB
scripts/tts_cache.pyscript4.5 KB
scripts/understand.pyscript171 B
scripts/understanding_brief.pyscript6.3 KB
scripts/understanding_cache.pyscript8.0 KB
scripts/understanding_runner.pyscript9.8 KB
scripts/understanding_storyboard.pyscript11.9 KB
scripts/validate.pyscript5.7 KB
scripts/visual_render.pyscript10.1 KB
scripts/vlm.pyscript16.4 KB
scripts/voiceover.pyscript28.0 KB

scripts/cut_cli.py

View on GitHub
"""Command-line orchestration for the cut stage."""

import json
import os


from pathlib import Path

from lib import CONFIG, file_identity, get_video_duration, log

from cut_contract import (
    SOURCES_MANIFEST_SHAPE,
    _write_edited_source_meta,
    load_clip_plan,
    normalize_clip_plan,
    normalize_multi_source_clip_plan,
    parse_duration_seconds,
    should_reuse_edited_source,
)
from cut_render import build_edited_source_video
from frame_grid import record_frame_grid, source_frame_grids
from media import _has_audio_stream, _select_output_geometry
from narrative_selection import check_required_evidence
from cut_qc import update_cut_qc
from sentence_boundaries import snap_multi_source_clips, snap_source_clips
import shot_review


def run_cut_shot_review(
    edited_source_path, plan_path, work_dir, validated_plan, *, reused=False, scene_roi=None
):
    """Scan rendered edited_source.mp4 for internal shot candidates and block flash slivers."""
    report_path = Path(work_dir) / "shot_review.json"
    if not CONFIG["cut_shot_review"]:
        report_path.unlink(missing_ok=True)
        return None
    report = None
    if reused and report_path.is_file():
        try:
            cached = json.loads(report_path.read_text(encoding="utf-8"))
            cached_identity = (
                (cached.get("media") or {}).get("identity") if isinstance(cached, dict) else None
            )
            cached_roi = cached.get("scene_roi") if isinstance(cached, dict) else None
            roi_matches = (
                cached_roi == list(scene_roi) if scene_roi is not None else cached_roi is None
            )
            if (
                isinstance(cached, dict)
                and cached.get("scan_complete") is True
                and (cached.get("plan_binding") or {}).get("path") == str(Path(plan_path).resolve())
                and cached_identity is not None
                and cached_identity == file_identity(edited_source_path)
                and cached.get("scene_threshold") == CONFIG["shot_review_threshold"]
                and (cached.get("policy") or {}).get("flash_sliver_max_seconds")
                == CONFIG["flash_sliver_max_seconds"]
                and roi_matches
            ):
                report = cached
        except (OSError, ValueError):
            report = None
    if report is None:
        scan_kwargs = {}
        if scene_roi is not None:
            scan_kwargs["roi"] = scene_roi
        report = shot_review.write_scan(
            edited_source_path,
            report_path,
            threshold=CONFIG["shot_review_threshold"],
            plan_path=plan_path,
            flash_sliver_max_seconds=CONFIG["flash_sliver_max_seconds"],
            **scan_kwargs,
        )
    slivers = report.get("flash_slivers") or []
    if slivers:
        validated_plan["qc"].setdefault("blocking", []).append(
            {
                "code": "flash_frame_sliver",
                "flash_sliver_count": len(slivers),
                "flash_slivers": slivers,
                "report_path": str(report_path),
            }
        )
        Path(plan_path).write_text(
            json.dumps(validated_plan, ensure_ascii=False, indent=2), encoding="utf-8"
        )
        raise SystemExit(
            f"clip_plan QC blocking: detected {len(slivers)} flash-frame sliver(s) "
            f"(<= {CONFIG['flash_sliver_max_seconds']:.2f}s) in edited_source.mp4. "
            "Trim/adjust clip boundaries and inspect shot_review.json."
        )
    return report


def _write_validated_plan(path, plan, raw_plan_paths):
    """Write clip_plan_validated.json unless the file already holds exactly this plan.

    Downstream output-clock evidence binds to this file's {size, mtime_ns}, so a resumed
    run that re-validates an unchanged plan must leave it alone. The file is still
    rewritten when any raw plan is newer, so "validated older than raw = stale" holds."""
    text = json.dumps(plan, ensure_ascii=False, indent=2)
    if path.exists() and path.read_text(encoding="utf-8") == text:
        written = path.stat().st_mtime_ns
        if all(not raw.exists() or raw.stat().st_mtime_ns <= written for raw in raw_plan_paths):
            return
    path.write_text(text, encoding="utf-8")


def _required_ranges_by_source(raw_plan, source_paths):
    """{plan source path: [(start, end)]} of declared required-evidence nodes.

    Only a hint for frame snapping; check_required_evidence validates the contract itself.
    """
    nodes = raw_plan.get("required_evidence") if isinstance(raw_plan, dict) else None
    nodes = nodes.get("nodes") if isinstance(nodes, dict) else None
    by_realpath = {os.path.realpath(path): path for path in source_paths}
    ranges = {}
    for node in nodes if isinstance(nodes, list) else []:
        try:
            path = by_realpath.get(os.path.realpath(node["source"]))
            start, end = float(node["start"]), float(node["end"])
        except (KeyError, TypeError, ValueError):
            continue
        if path is not None:
            ranges.setdefault(path, []).append((start, end))
    return ranges


def main():
    import argparse

    parser = argparse.ArgumentParser(
        description="cut.py: build edited_source.mp4 from an agent clip plan; narration is authored afterwards on the output timeline."
    )
    parser.add_argument("video", help="source video path")
    parser.add_argument(
        "--work-dir",
        required=True,
        help="dir holding clip_plan.json",
    )
    parser.add_argument(
        "--clip-plan",
        default=None,
        help="clip plan json (default: <work-dir>/clip_plan.json)",
    )
    parser.add_argument(
        "--sources-manifest",
        default=None,
        help=f"multi-source manifest json: {SOURCES_MANIFEST_SHAPE}",
    )
    parser.add_argument(
        "--target-duration",
        default=None,
        help="target output duration, e.g. 10m / 600 / 00:10:00",
    )
    parser.add_argument(
        "--allow-overlap",
        action="store_true",
        help="allow overlapping/duplicate source ranges",
    )
    parser.add_argument(
        "--normalize-only",
        action="store_true",
        help="normalize, snap and QC the clip plan, write clip_plan_validated.json, then exit "
        "without rendering",
    )
    args = parser.parse_args()

    work_dir = Path(args.work_dir)
    work_dir.mkdir(parents=True, exist_ok=True)
    clip_plan_path = (
        Path(args.clip_plan) if args.clip_plan else work_dir / "clip_plan.json"
    )
    raw_plan = load_clip_plan(clip_plan_path)

    target_seconds = (
        parse_duration_seconds(args.target_duration) if args.target_duration else None
    )
    sources_manifest = (
        json.loads(Path(args.sources_manifest).read_text(encoding="utf-8"))
        if args.sources_manifest
        else None
    )
    # Visual shot-change cleanup runs first; the sentence/quiet pass is the final authority,
    # so a prettier edit point never moves a boundary back inside a spoken sentence.
    snap_options = {
        "line_max_extend": CONFIG["clip_snap_max_extend"],
        "end_pause_pad": CONFIG["clip_end_pause_pad"],
        "scene_margin": CONFIG["scene_cut_snap_margin"],
        "scene_threshold": CONFIG["scene_cut_detect_threshold"],
        "start_max_prepend": CONFIG["clip_start_snap_max_prepend"],
        "start_max_trim": CONFIG["clip_start_snap_max_trim"],
        "flash_sliver_max_seconds": CONFIG["flash_sliver_max_seconds"],
        "do_line_snap": CONFIG["snap_clip_line_end"],
        "do_scene_snap": CONFIG["scene_cut_snap"],
    }
    if sources_manifest is None:
        video_duration = get_video_duration(args.video)
        validated_plan = normalize_clip_plan(
            raw_plan,
            video_duration,
            target_duration=target_seconds,
            min_clip_duration=CONFIG["min_clip_duration"],
            allow_overlap=args.allow_overlap,
        )
    else:
        validated_plan = normalize_multi_source_clip_plan(
            raw_plan,
            sources_manifest,
            target_duration=target_seconds,
            min_clip_duration=CONFIG["min_clip_duration"],
            allow_overlap=args.allow_overlap,
        )
    # The canvas (and so the output frame rate) is chosen before snapping because the
    # frame-grid pass snaps clip lengths to whole output frames; the same geometry is
    # recorded in clip_plan_validated.json and used for the render.
    # Single-source clips carry no source_path; the CLI video is the only input.
    source_paths = list(
        dict.fromkeys(
            clip["source_path"] for clip in validated_plan["clips"] if "source_path" in clip
        )
    ) or [str(args.video)]
    _, _, _, geometry_qc = _select_output_geometry(source_paths, validated_plan["clips"])
    frame_grids = source_frame_grids(geometry_qc)
    for path, ranges in _required_ranges_by_source(raw_plan, source_paths).items():
        frame_grids[path]["keep_ranges"] = ranges
    if sources_manifest is None:
        validated_plan = snap_source_clips(
            validated_plan, args.video, video_duration, work_dir,
            frame_grid=frame_grids[str(args.video)], **snap_options,
        )
    else:
        # Each clip snaps against ITS OWN source's pauses, shot changes and frame grid.
        validated_plan = snap_multi_source_clips(
            validated_plan, validated_plan["sources"], work_dir,
            frame_grids={
                sid: frame_grids[source["source_path"]]
                for sid, source in validated_plan["sources"].items()
                if source["source_path"] in frame_grids
            },
            **snap_options,
        )

    validated_plan.setdefault("qc", {})["join_fade_ms"] = round(
        CONFIG["clip_join_audio_fade_ms"], 3
    )
    validated_plan["qc"]["output_geometry"] = geometry_qc
    validated_plan["qc"]["output_geometry_reason"] = geometry_qc["reason"]
    record_frame_grid(validated_plan, geometry_qc)
    update_cut_qc(validated_plan)
    if isinstance(raw_plan, dict) and 'required_evidence' in raw_plan:
        # Re-evaluate the final snapped ranges even when the media cache can be reused.
        contract = raw_plan['required_evidence']
        plan_sources = {str(Path(path).resolve()): path for path in source_paths}
        source_audio = {}

        def has_source_audio(source):
            # Probed lazily, once per source, only for validated audio nodes.
            if source not in source_audio:
                source_audio[source] = source in plan_sources and _has_audio_stream(plan_sources[source])
            return source_audio[source]

        report = check_required_evidence(contract, validated_plan, input_video=args.video,
                                         source_audio=has_source_audio)
        validated_plan['qc']['required_evidence'] = {**report, 'contract': contract}
        if report['selection_status'] == 'BLOCK':
            validated_plan['qc'].setdefault('blocking', []).extend(report['findings'])
    plan_path = work_dir / "clip_plan_validated.json"
    raw_plan_paths = {clip_plan_path, work_dir / "clip_plan.json"}
    edited_source_path = work_dir / "edited_source.mp4"
    reuse = (
        not validated_plan["qc"].get("blocking")
        and not args.normalize_only
        and should_reuse_edited_source(edited_source_path, validated_plan, args.video)
    )
    if not reuse:
        _write_validated_plan(plan_path, validated_plan, raw_plan_paths)
    if validated_plan["qc"].get("blocking"):
        raise SystemExit(
            "clip_plan QC blocking: fix required source evidence or unsafe sentence boundaries. "
            "Sentence truncation is never allowed. See clip_plan_validated.json['qc']."
        )
    if args.normalize_only:
        print(
            json.dumps(
                {
                    "status": "normalized",
                    "clips": len(validated_plan["clips"]),
                    "total_duration": validated_plan["total_duration"],
                },
                ensure_ascii=False,
            )
        )
        return

    if reuse:
        log(f"复用剪辑源视频: {edited_source_path}")
        _write_edited_source_meta(edited_source_path, validated_plan, args.video)
    else:
        build_edited_source_video(
            args.video, validated_plan, work_dir, edited_source_path
        )
    _write_validated_plan(plan_path, validated_plan, raw_plan_paths)
    run_cut_shot_review(
        edited_source_path, plan_path, work_dir, validated_plan, reused=reuse
    )

    log(
        f"剪辑模式: {len(validated_plan['clips'])} 个片段 → {validated_plan['total_duration']:.1f}s"
    )
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall