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/recap_runtime.py

View on GitHub
"""Provide subprocess, manifest, and preflight runtime helpers."""

import json
import math
import os
import shlex
import shutil
import subprocess
import sys
from pathlib import Path

import materials as material_lib
from lib import env_bool, ffmpeg_has_subtitles_filter, file_identity, load_json, material_id_for
from recap_source import audio_binding

SCRIPT_DIR = Path(__file__).resolve().parent

RUN_MANIFEST = "recap_run_manifest.json"

MULTI_SOURCE_MANIFEST = "multi_source_manifest.json"


def _run(stage, script, *cli_args):
    cmd = [sys.executable, str(_entry(script)), *map(str, cli_args)]
    print(f"[video-recap] ▶ {stage}/{script}", flush=True)
    # Stage scripts log Chinese; on Windows a piped stdout defaults to cp1252 and the
    # first log line would crash the child with UnicodeEncodeError.
    res = subprocess.run(
        cmd, env={**os.environ, "PYTHONIOENCODING": "utf-8", "PYTHONUTF8": "1"}
    )
    if res.returncode != 0:
        raise SystemExit(f"{stage}/{script} 失败 (exit {res.returncode})")


def _read_video_duration_or_raise(path):
    """Return media duration via ffprobe, or hard-fail before downstream TTS/render."""
    path = Path(path)
    cmd = [
        "ffprobe",
        "-v",
        "quiet",
        "-show_entries",
        "format=duration",
        "-of",
        "csv=p=0",
        str(path),
    ]
    res = subprocess.run(
        cmd, capture_output=True, text=True, encoding="utf-8", errors="replace"
    )
    if res.returncode != 0:
        detail = (res.stderr or res.stdout or "ffprobe failed").strip()
        raise SystemExit(f"无法读取成片时长: {path} ({detail})")
    try:
        duration = float(res.stdout.strip())
    except ValueError:
        raise SystemExit(f"无法读取成片时长: {path} (ffprobe 输出无效: {res.stdout!r})") from None
    if not math.isfinite(duration) or duration <= 0:
        raise SystemExit(f"无法读取成片时长: {path} (duration={duration:.3f})")
    return duration


# Subtitle Y coordinates are display-canvas rows; a near-square SAR only changes the canvas
# width (or, rotated, the row scale the renderer converts exactly). Same value as the
# renderer's and the measuring tool's copies (parity-tested).
SUBTITLE_BAND_SAR_TOLERANCE = 0.02


def _probe_display_size_or_raise(path, *, require_near_square_pixels=False):
    """Return ffmpeg's display-coordinate (width, height), accounting for rotation and SAR."""
    cmd = [
        "ffprobe",
        "-v",
        "error",
        "-select_streams",
        "v:0",
        "-show_entries",
        "stream=width,height,sample_aspect_ratio:stream_tags=rotate:stream_side_data=rotation",
        "-of",
        "json",
        str(path),
    ]
    res = subprocess.run(
        cmd, capture_output=True, text=True, encoding="utf-8", errors="replace"
    )
    try:
        stream = json.loads(res.stdout)["streams"][0]
        width, height = int(stream["width"]), int(stream["height"])
    except (IndexError, KeyError, ValueError):
        detail = (res.stderr or res.stdout or "ffprobe failed").strip()
        raise SystemExit(f"无法读取视频画布: {path} ({detail})") from None
    sar = stream.get("sample_aspect_ratio", "1:1")
    try:
        num, den = sar.split(":", 1)
        sar_ratio = float(num) / float(den)
    except (ValueError, ZeroDivisionError):
        sar_ratio = math.nan
    if sar in {"0:1", "N/A"}:
        sar_ratio = 1.0  # unspecified SAR: ffmpeg (and the renderer's canvas) treat it as square
    if require_near_square_pixels and (
        not math.isfinite(sar_ratio) or abs(sar_ratio - 1.0) > SUBTITLE_BAND_SAR_TOLERANCE + 1e-9
    ):
        raise SystemExit(
            "subtitle Y coordinates require square or near-square pixels "
            f"(SAR within {SUBTITLE_BAND_SAR_TOLERANCE:.0%} of 1:1); got {sar}"
        )
    display_width = max(1, round(width * sar_ratio)) if math.isfinite(sar_ratio) else width
    rotation_values = [
        stream.get("tags", {}).get("rotate"),
        *(item.get("rotation") for item in stream.get("side_data_list", [])),
    ]
    rotation = next(
        (int(round(float(value))) % 360 for value in rotation_values if value not in (None, "")),
        0,
    )
    return (height, display_width) if rotation in {90, 270} else (display_width, height)


def _analysis_settings(args):
    return {
        "context": args.context,
        "scene_threshold": args.scene_threshold,
        "style": args.style,
        "edit_mode": args.edit_mode,
        "target_duration": args.target_duration,
        "skip_asr": bool(args.skip_asr),
        # Frozen at False: restore_material compares these settings by equality, so dropping a
        # retired key would turn every saved material into a paid re-analysis.
        "mimo_video_overview": False,
        "consolidate_asr": False,
    }


def _run_manifest_payload(video, args):
    return {
        "schema_version": 1,
        "source_video": str(Path(video).resolve()),
        "source_video_identity": file_identity(video),
        "settings": _analysis_settings(args),
        "audio": audio_binding(args),
    }


# Settings main() can take from the environment rather than argv, with their no-env value.
# A resume shell may not carry the same environment, so the resume argv pins them.
_ENV_FILLED = (
    ("tts_provider", "auto"),
    ("voice_ref", None),
)


def _resume_argv(work_dir, args):
    """The argv that resumes this run: what the user typed (paths made absolute by
    recap_cli), plus the work dir and any environment-filled setting it did not spell out.
    Values a --project binding filled in are re-derived from --project on resume."""
    argv = list(args._argv)
    explicit = args._explicit_options
    bound = getattr(args, "_bound_from_project", frozenset())
    if "--work-dir" not in explicit:
        argv += ["--work-dir", str(work_dir)]
    for dest, unset in _ENV_FILLED:
        flag = "--" + dest.replace("_", "-")
        value = getattr(args, dest)
        if flag not in explicit and dest not in bound and value != unset:
            argv += [flag, str(value)]
    return argv


def _write_manifest_with_argv(work_dir, payload, args):
    extra = {}
    if getattr(args, "audio_mode", "narration") == "narration":
        provider = getattr(args, "tts_provider", None)
        if isinstance(provider, str) and provider.strip():
            extra["tts_provider"] = provider.strip().lower()
    (work_dir / RUN_MANIFEST).write_text(
        json.dumps(
            {**payload, **extra, "argv": _resume_argv(work_dir, args)},
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )


def _write_run_manifest(work_dir, video, args):
    _write_manifest_with_argv(work_dir, _run_manifest_payload(video, args), args)


def _build_multi_source_records(videos, args):
    records = []
    for video in videos:
        identity = file_identity(video)
        records.append(
            {
                "source_path": str(video),
                "source_name": video.name,
                "source_video_identity": identity,
                "settings": _analysis_settings(args),
                "material_id": material_id_for(video, identity),
            }
        )
    records = material_lib.assign_source_ids(records)
    for record in records:
        record["source_work_dir"] = f"sources/{record['source_id']}"
    return records


def _multi_run_manifest_payload(args, source_records):
    return {
        "schema_version": 2,
        "mode": "multi_source",
        "sources": [
            {
                "source_id": s["source_id"],
                "source_path": s["source_path"],
                "source_video_identity": s["source_video_identity"],
                "source_work_dir": s["source_work_dir"],
                "material_id": s["material_id"],
            }
            for s in source_records
        ],
        "settings": _analysis_settings(args),
        "audio": audio_binding(args),
    }


def _write_project_run_manifest(work_dir, args, source_records):
    _write_manifest_with_argv(work_dir, _multi_run_manifest_payload(args, source_records), args)


def _write_multi_source_manifest(work_dir, source_records):
    path = Path(work_dir) / MULTI_SOURCE_MANIFEST
    payload = {
        "schema_version": 1,
        "sources": [
            {
                "source_id": s["source_id"],
                "source_path": s["source_path"],
                "source_name": s["source_name"],
                "source_video_identity": s["source_video_identity"],
                "source_work_dir": s["source_work_dir"],
                "material_id": s["material_id"],
            }
            for s in source_records
        ],
    }
    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
    return path


def _load_run_manifest(work_dir):
    """The run manifest, or None before Phase A has written one."""
    path = Path(work_dir) / RUN_MANIFEST
    return load_json(path) if path.exists() else None


def _burn_subtitles_intended(args):
    """Effective burn-subtitles state at orchestrator level. Mirrors assemble.py's
    CONFIG default `env_bool("BURN_SUBTITLES", True)` (burn is ON by default); an explicit
    CLI flag (--burn-subtitles / --no-burn-subtitles) overrides the env."""
    if args.burn_subtitles is not None:
        return args.burn_subtitles
    return env_bool("BURN_SUBTITLES", True)


def _ffmpeg_present_but_cannot_burn():
    """True only when ffmpeg EXISTS but lacks the libass `subtitles` filter — the specific
    "subtitle-burn environment unsupported" case. Returns False when ffmpeg is absent
    entirely: that is a more fundamental problem that surfaces at the first stage (understand
    calls ffprobe/ffmpeg) and is reported by doctor, so this guard stays narrow — and does
    not fire in mocked, ffmpeg-less test environments."""
    if shutil.which("ffmpeg") is None:
        return False
    return not ffmpeg_has_subtitles_filter()


def _burn_subtitles_explicit(args):
    """Burn was asked for, not inherited: --burn-subtitles, or a truthy BURN_SUBTITLES."""
    if args.burn_subtitles is not None:
        return args.burn_subtitles
    return "BURN_SUBTITLES" in os.environ and env_bool("BURN_SUBTITLES", True)


def _preflight_burn_subtitles(args):
    """Settle subtitle burn-in BEFORE any understanding/VLM/ASR/TTS spend when this ffmpeg
    lacks libass. An explicit request fails fast here, since otherwise the run only dies at
    the final assemble `-vf subtitles=` step. The default burn only warns: assemble then
    delivers the .srt sidecar and records `subtitle_burn_degraded` in visual_qc.json, which
    final_qc.json carries in metadata.warnings."""
    if not _burn_subtitles_intended(args):
        return
    if not _ffmpeg_present_but_cannot_burn():
        return
    doctor = f"python3 {shlex.quote(str(_entry('doctor.py')))}"
    if _burn_subtitles_explicit(args):
        raise SystemExit(
            "已显式要求烧录字幕(--burn-subtitles 或 BURN_SUBTITLES),但当前 ffmpeg 不支持"
            " subtitles/libass 滤镜,整条流程会跑到最后渲染才失败。\n"
            "  解决其一:(1) 安装带 libass 的 ffmpeg;(2) 去掉显式烧录要求,默认运行会改为输出"
            " .srt 外挂字幕;(3) 加 --no-burn-subtitles。\n"
            f"  自检:{doctor}"
        )
    print(
        "[video-recap] ⚠ 当前 ffmpeg 不支持 subtitles/libass 滤镜:本次成片不烧录字幕。"
        "有字幕条目时改为在成片旁输出同名 .srt 外挂字幕(final_qc.json 的 metadata.warnings"
        " 会记录 subtitle_burn_degraded);没有字幕条目的运行(如 source 音频模式且没有"
        " original_subtitles.json)不输出 .srt,也不记警告。要烧录字幕请安装带 libass 的 ffmpeg;"
        f"自检:{doctor}",
        flush=True,
    )


def _entry(script):
    return SCRIPT_DIR / script
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