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

View on GitHub
"""Orchestrate the understanding stages."""

import argparse


import json
import os

from pathlib import Path

from lib import CONFIG, TTS_PROVIDERS, log, get_video_duration, api_call, offline_ignored_settings

from extract import extract_frames

from detect import detect_scenes, detect_silence_periods, detect_speech_boundary_anchors

from asr import transcribe_audio
from asr_timing_evidence import write_asr_timing_evidence

from vlm import analyze_scenes

from understanding_brief import (
    _finish_brief,
    _research_context,
    _write_brief_from_existing_artifacts,
)
from understanding_storyboard import _write_edited_storyboard_only
from understanding_cache import (
    _asr_cache_payload,
    _asr_cache_state,
    _frames_cache_valid,
    _load_json,
    _remove_stage_meta,
    _scene_cache_payload,
    _silence_cache_payload,
    _stage_cache_valid,
    _vlm_cache_payload,
    _write_frames_manifest,
    _write_stage_meta,
)


def _refuse_keyless_overwrite(asr_json):
    """Stop before a key-less ASR miss replaces a real transcript with the [] placeholder.

    The cache can miss for reasons that say nothing about the transcript, e.g. a work_dir
    copied without keeping mtimes changes the recorded artifact identity."""
    if CONFIG["mimo_asr_api_key"] or not asr_json.exists():
        return
    try:
        existing = json.loads(asr_json.read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return
    if isinstance(existing, list) and existing:
        raise SystemExit(
            "ASR 缓存与当前视频、设置或文件时间不匹配(常见原因:复制 work_dir 或视频时没保留"
            "修改时间),且未设置 MIMO_ASR_API_KEY / MIMO_API_KEY,无法重新转写;"
            f"已保留现有 asr_result.json({len(existing)} 段),未覆盖。"
            "请用保留时间的方式重新复制(cp -p / cp -Rp / rsync -t),"
            "或设置 MIMO_ASR_API_KEY 或 MIMO_API_KEY 后重跑(会重新转写)。"
            "不要用 --skip-asr 绕过:它会把现有转写替换成 []。"
        )


def main():
    ap = argparse.ArgumentParser(
        description="Analyze a video into local understanding artifacts + narration brief."
    )
    ap.add_argument("video")
    ap.add_argument("--work-dir", required=True)
    ap.add_argument(
        "--context", default="", help="extra context (show name, character names, ...)"
    )
    ap.add_argument("--scene-threshold", type=float, default=None)
    ap.add_argument("--style", default="纪录片")
    ap.add_argument(
        "--edit-mode",
        default=None,
        choices=["full", "cut"],
        help="recap mode to document in the writing brief",
    )
    ap.add_argument(
        "--target-duration",
        default=None,
        help="cut-mode target duration to document in the writing brief",
    )
    ap.add_argument(
        "--tts-provider",
        default=None,
        choices=TTS_PROVIDERS,
        help="TTS provider hint for narration brief emotion field formatting",
    )
    ap.add_argument("--skip-asr", action="store_true")
    ap.add_argument(
        "--force", action="store_true", help="ignore cached artifacts and recompute"
    )
    ap.add_argument(
        "--brief-only",
        action="store_true",
        help="rebuild agent_narration_brief.md from existing artifacts only; no extraction/API",
    )
    ap.add_argument(
        "--edited-storyboard-only",
        action="store_true",
        help=(
            "write storyboard/edited_storyboard.* from clip_plan_validated.json (single- or "
            "multi-source) and add its pointer to the existing brief; no extraction/API"
        ),
    )
    args = ap.parse_args()
    # Removed after v0.6.2. Refused for one release: an unread EDIT_MODE=cut would silently write a full brief.
    for name, flag in (("EDIT_MODE", "--edit-mode"), ("TARGET_DURATION", "--target-duration")):
        if os.environ.get(name):
            ap.error(f"环境变量 {name} 已移除:请从环境里删掉它,改传 {flag}")
    if args.brief_only and args.edited_storyboard_only:
        ap.error("--brief-only 与 --edited-storyboard-only 互斥,不能同时指定")

    video = args.video
    work_dir = Path(args.work_dir)
    work_dir.mkdir(parents=True, exist_ok=True)
    # Story research (if the agent wrote background_research.json first) feeds the VLM
    # context, so scene analysis can name characters and read scenes with plot knowledge.
    research_ctx = _research_context(work_dir)
    context_parts = [p for p in (research_ctx, args.context) if p and p.strip()]
    if context_parts:
        CONFIG["context_info"] = " ".join(context_parts)
    if research_ctx:
        log(f"已并入 background_research.json 到理解上下文({len(research_ctx)} 字)")
    if args.scene_threshold is not None:
        CONFIG["scene_threshold"] = args.scene_threshold
    if args.edit_mode is not None:
        CONFIG["edit_mode"] = args.edit_mode
    if args.target_duration is not None:
        CONFIG["target_duration"] = args.target_duration
    if args.tts_provider is not None:
        CONFIG["tts_provider"] = args.tts_provider
        CONFIG["_explicit_tts_provider"] = args.tts_provider

    video_duration = get_video_duration(video)
    if CONFIG["fps"] <= 0:
        CONFIG["fps"] = (
            2 if video_duration <= 60 else (1.5 if video_duration <= 300 else 1)
        )
    log(f"FPS: {CONFIG['fps']} (视频时长: {video_duration:.1f}s)")

    if args.brief_only:
        _write_brief_from_existing_artifacts(video, work_dir, args, video_duration)
        return
    if args.edited_storyboard_only:
        _write_edited_storyboard_only(video, work_dir)
        return

    scenes_json = work_dir / "scenes.json"
    asr_json = work_dir / "asr_result.json"
    silence_json = work_dir / "silence_periods.json"
    vlm_json = work_dir / "vlm_analysis.json"
    frames_dir = work_dir / "frames"

    # Step 1: frame extraction
    if not args.force and _frames_cache_valid(video, work_dir, CONFIG["fps"]):
        frames = sorted(frames_dir.glob("frame_*.jpg"))
        log(f"跳过帧提取(缓存匹配 {len(frames)} 帧)")
    else:
        frames = extract_frames(video, work_dir)
        _write_frames_manifest(work_dir, video, CONFIG["fps"], frames)

    # Step 2: scene detection
    scenes_meta = _scene_cache_payload(video)
    if not args.force and _stage_cache_valid(scenes_json, scenes_meta):
        scenes = _load_json(scenes_json)
        log(f"跳过场景检测(已存在 {len(scenes)} 个场景)")
    else:
        scenes = detect_scenes(video, work_dir, CONFIG["scene_threshold"])
        _write_stage_meta(scenes_json, scenes_meta)

    # The VLM cache does not depend on ASR, so an offline run that would stop at Step 4 stops
    # here instead, before Step 3 can rewrite the transcript or the silence windows.
    vlm_meta = _vlm_cache_payload(video, work_dir, scenes_json, frames)
    vlm_offline = offline_ignored_settings(CONFIG["api_key"], "api_url")
    vlm_cached = not args.force and _stage_cache_valid(
        vlm_json, vlm_meta, ignore_settings=vlm_offline
    )
    if not vlm_cached and not CONFIG["api_key"]:
        key_name = CONFIG["api_env_var"]
        raise SystemExit(f"请设置 {key_name} 环境变量(VLM 画面分析需要)")

    # Step 3: ASR
    asr_meta = _asr_cache_payload(video, skip_asr=args.skip_asr)
    cache_state = None
    if not args.skip_asr and not args.force:
        cache_state = _asr_cache_state(asr_json, asr_meta, video)
    if args.skip_asr:
        asr_result = []
        asr_json.write_text(
            json.dumps(asr_result, ensure_ascii=False, indent=2), encoding="utf-8"
        )
        _write_stage_meta(asr_json, asr_meta)
        write_asr_timing_evidence(
            work_dir, video, "EXPLICITLY_SKIPPED", final_segments=asr_result
        )
        log("跳过 ASR(--skip-asr)")
    elif cache_state == "FRESH":
        asr_result = _load_json(asr_json)
        log(f"跳过 ASR(证据匹配,已存在 {len(asr_result)} 段)")
    else:
        _refuse_keyless_overwrite(asr_json)
        try:
            asr_result = transcribe_audio(video, work_dir)
        except Exception as e:
            _remove_stage_meta(asr_json)
            asr_json.unlink(missing_ok=True)
            raise RuntimeError(
                f"ASR 失败;未写入可复用缓存,请修复后重试或显式使用 --skip-asr: {e}"
            ) from e
        _write_stage_meta(asr_json, asr_meta)

    # Step 3.5: silence detection
    silence_meta = _silence_cache_payload(video, asr_json)
    if not args.force and _stage_cache_valid(silence_json, silence_meta):
        silence_periods = _load_json(silence_json)
        log(f"跳过静音检测(已存在 {len(silence_periods)} 个窗口)")
        if not (work_dir / "speech_boundary_anchors.json").exists():
            detect_speech_boundary_anchors(work_dir, asr_result)
    else:
        silence_periods = detect_silence_periods(video, work_dir, asr_result)
        _write_stage_meta(silence_json, silence_meta)

    # Step 4: VLM analysis (the only stage that requires the chat API key)
    if vlm_cached:
        vlm_analysis = _load_json(vlm_json)
        log(f"跳过 VLM 分析(已存在 {len(vlm_analysis)} 个场景)")
    else:
        log("VLM API 连通性预检...")
        api_call(
            {
                "model": CONFIG["vlm_model"],
                "messages": [{"role": "user", "content": "hi"}],
                "max_tokens": 5,
            }
        )
        vlm_analysis = analyze_scenes(scenes, frames, work_dir, resume=not args.force)
        _write_stage_meta(vlm_json, vlm_meta)

    _finish_brief(
        video, work_dir, args, video_duration,
        storyboard_scenes=scenes, brief_scenes=vlm_analysis,
        asr_result=asr_result, silence_periods=silence_periods,
        status="analyzed", done_label="理解完成", force=args.force,
    )
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