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_storyboard.py

View on GitHub
"""Generate and cache source and edited storyboard sheets."""

import json
from pathlib import Path

from lib import CONFIG, log


from storyboard import (
    _frame_index,
    build_edited_storyboard,
    build_source_storyboard,
)


from understanding_cache import (
    _artifact_identity,
    _video_input,
    _frames_manifest_path,
    _load_json,
    _stage_cache_valid,
    _write_stage_meta,
)


def _storyboard_sample_policy():
    return {
        "max_tiles": CONFIG["storyboard_max_tiles"],
        "columns": CONFIG["storyboard_columns"],
    }


def _reuse_cached_storyboard(json_path, label):
    """The cached storyboard, or None when it is unreadable. Advisory: never raises."""
    try:
        cached = _load_json(json_path)
    except (OSError, ValueError):
        log(f"storyboard {label} 缓存命中但文件损坏,重建")
        return None
    log(f"storyboard 跳过 {label}(缓存匹配)")
    return cached


def _edited_storyboard_meta(clip_plan_validated_json, frames_manifest_path):
    """Cache key for the edited storyboard: clip plan + fps + frame-set all in the key, so an
    fps change OR a re-validated plan invalidates it. font availability is deliberately NOT in
    the key (the JSON `labels_burned` flag surfaces it instead)."""
    return {
        "schema_version": 1,
        "stage": "edited_storyboard",
        "inputs": {
            "clip_plan_validated": _artifact_identity(clip_plan_validated_json),
            "frames_manifest": _artifact_identity(frames_manifest_path),
        },
        "fps": float(CONFIG.get("fps") or 0),
        "sample_policy": _storyboard_sample_policy(),
    }


def _multi_source_edited_storyboard_meta(clip_plan_validated_json, frame_sets):
    """Cache key for a multi-source edited storyboard: the plan plus every used source's
    frames-manifest identity and fps."""
    return {
        "schema_version": 1,
        "stage": "edited_storyboard",
        "inputs": {
            "clip_plan_validated": _artifact_identity(clip_plan_validated_json),
            "frames_manifests": {
                sid: _artifact_identity(entry["manifest"]) for sid, entry in frame_sets.items()
            },
        },
        "fps": {sid: entry["fps"] for sid, entry in frame_sets.items()},
        "sample_policy": _storyboard_sample_policy(),
    }


def _generate_source_storyboard(
    work_dir, video_path, scenes, scenes_json, *, force=False
):
    """Generate (or reuse cached) the source storyboard. Advisory: returns dict|None, never raises.

    Cached via _write_stage_meta/_stage_cache_valid on storyboard/source_storyboard.json; the
    meta includes fps + the frames-manifest identity so an fps-change resume rebuilds (Principle 5).
    If frames/ is absent (cache hit skipped extraction / cleaned) → skip + log; pipeline continues.
    """
    if not CONFIG["storyboard"]:
        return None
    frames_dir = Path(work_dir) / "frames"
    if not frames_dir.is_dir() or not any(frames_dir.glob("frame_*.jpg")):
        log("storyboard 跳过 source:frames/ 缺失(缓存命中跳过了帧提取?)")
        return None
    json_path = Path(work_dir) / "storyboard" / "source_storyboard.json"
    meta = {
        "schema_version": 1,
        "stage": "source_storyboard",
        "inputs": {
            "video": _video_input(video_path),
            "scenes": _artifact_identity(scenes_json),
            "frames_manifest": _artifact_identity(_frames_manifest_path(work_dir)),
        },
        "fps": float(CONFIG.get("fps") or 0),
        "sample_policy": _storyboard_sample_policy(),
    }
    if not force and _stage_cache_valid(json_path, meta):
        cached = _reuse_cached_storyboard(json_path, "source")
        if cached is not None:
            return cached
    result = build_source_storyboard(work_dir, video_path, scenes, CONFIG["fps"])
    if result is not None and json_path.exists():
        _write_stage_meta(json_path, meta)
    return result


def _multi_source_frame_sets(work_dir, plan_sources, clips):
    """{source_id: {paths, numbers, fps, source_path}} for a multi-source validated plan.

    Each source's frames live in its own work_dir (`sources.<id>.source_work_dir`, relative to
    the project work_dir) at the fps recorded in that source's frames manifest — sources of
    different lengths are extracted at different fps. A source without frames is left out, and
    so is one no clip in `clips` uses: it must not take an S<n> label, be listed under `sources`,
    set the tile size or enter the cache key.
    """
    used = {clip.get("source_id") for clip in clips if isinstance(clip, dict)}
    frame_sets = {}
    for source_id, source in plan_sources.items():
        if source_id not in used:
            continue
        if not isinstance(source, dict):
            log(f"storyboard edited:来源 {source_id} 不是对象,跳过")
            continue
        rel = source.get("source_work_dir")
        if not rel:
            log(f"storyboard edited:来源 {source_id} 未登记 source_work_dir,跳过")
            continue
        source_dir = Path(work_dir) / rel
        manifest_path = _frames_manifest_path(source_dir)
        try:
            fps = float(_load_json(manifest_path)["fps"])
        except (OSError, ValueError, TypeError, KeyError):
            log(f"storyboard edited:来源 {source_id} 缺少可读的 frames_manifest.json,跳过")
            continue
        paths, numbers = _frame_index(source_dir)
        if not paths or fps <= 0:
            log(f"storyboard edited:来源 {source_id} 的 frames/ 缺失,跳过")
            continue
        frame_sets[source_id] = {
            "paths": paths,
            "numbers": numbers,
            "fps": fps,
            "source_path": source.get("source_path"),
            "manifest": manifest_path,
        }
    return frame_sets


def _generate_edited_storyboard(work_dir, source_video_path, *, force=False):
    """Generate (or reuse cached) the edited storyboard, GATED on clip_plan_validated.json
    file-presence (NOT on edit_mode — recap.py forwards --edit-mode cut in BOTH passes, so the
    validated plan presence is the only reliable pass2 signal). Advisory: returns dict|None.

    A multi-source plan (one with `sources`) reads every source's frames from its own work_dir
    under the project work_dir; the single-source plan reads work_dir/frames.
    """
    if not CONFIG["storyboard"]:
        return None
    clip_plan_validated_json = Path(work_dir) / "clip_plan_validated.json"
    if not clip_plan_validated_json.exists():
        return None  # pass1 (no validated plan yet) → no edited storyboard
    try:
        clip_plan_validated = _load_json(clip_plan_validated_json)
    except (OSError, ValueError):
        log("storyboard 跳过 edited:clip_plan_validated.json 无法解析")
        return None
    if not isinstance(clip_plan_validated, dict):
        log("storyboard 跳过 edited:clip_plan_validated.json 不是对象")
        return None
    plan_sources = clip_plan_validated.get("sources")
    if isinstance(plan_sources, dict) and plan_sources:
        clips = clip_plan_validated.get("clips")
        if not isinstance(clips, list) or not clips:
            log("storyboard 跳过 edited:clip_plan_validated 无 clips")
            return None
        frame_sets = _multi_source_frame_sets(work_dir, plan_sources, clips)
        if not frame_sets:
            log("storyboard 跳过 edited:剪辑用到的来源都没有 frames/")
            return None
        meta = _multi_source_edited_storyboard_meta(clip_plan_validated_json, frame_sets)
    else:
        frame_sets = None
        frames_dir = Path(work_dir) / "frames"
        if not frames_dir.is_dir() or not any(frames_dir.glob("frame_*.jpg")):
            log("storyboard 跳过 edited:frames/ 缺失(缓存命中跳过了帧提取?)")
            return None
        meta = _edited_storyboard_meta(
            clip_plan_validated_json, _frames_manifest_path(work_dir)
        )
    json_path = Path(work_dir) / "storyboard" / "edited_storyboard.json"
    if not force and _stage_cache_valid(json_path, meta):
        cached = _reuse_cached_storyboard(json_path, "edited")
        if cached is not None:
            return cached
    result = build_edited_storyboard(
        work_dir, source_video_path, clip_plan_validated, CONFIG["fps"],
        source_frames=frame_sets,
    )
    if result is not None and json_path.exists():
        _write_stage_meta(json_path, meta)
    return result


_STORYBOARD_HEADING = "## Storyboard(先看 storyboard 再写;路径相对 work_dir)"


def _write_edited_storyboard_only(video, work_dir):
    """--edited-storyboard-only: build the cut-output storyboard and point the brief at it.

    For callers that write the pass-2 brief themselves (a multi-source orchestrator): no
    extraction, ASR, VLM or API; the existing work_dir/agent_narration_brief.md, if any, gets
    the same storyboard header a --brief-only rebuild would carry. Advisory: a storyboard
    failure only logs.
    """
    work_dir = Path(work_dir)
    edited = _generate_edited_storyboard(work_dir, video)
    brief_path = work_dir / "agent_narration_brief.md"
    if edited and brief_path.exists():
        _prepend_storyboard_brief_header(brief_path, None, edited, cut_mode=True)
    print(
        json.dumps(
            {
                "status": "edited_storyboard" if edited else "edited_storyboard_skipped",
                "work_dir": str(work_dir),
                "page_images": (edited or {}).get("page_images", []),
            },
            ensure_ascii=False,
        )
    )


def _prepend_storyboard_brief_header(
    brief_path, source_storyboard, edited_storyboard, *, cut_mode
):
    """Post-process the RETURNED brief markdown FILE (C1): prepend a short storyboard header.

    Branches the edited-storyboard line on clip_plan_validated presence (edited_storyboard truthy)
    so pass1 never prints a not-yet-existing path. If labels_burned:false, point to inspect clip-map.
    """
    if not source_storyboard and not edited_storyboard:
        return
    try:
        brief_path = Path(brief_path)
        lines = [_STORYBOARD_HEADING, ""]
        any_labels_missing = False
        if source_storyboard:
            pages = source_storyboard.get("page_images") or []
            lines.append(
                f"- 源时间线 storyboard: {', '.join(pages)}(tiles 时间戳=原片时间)"
            )
            if not source_storyboard.get("labels_burned", False):
                any_labels_missing = True
        if cut_mode and edited_storyboard:
            pages = edited_storyboard.get("page_images") or []
            lines.append(
                f"- 成片(output)时间线 storyboard: {', '.join(pages)}"
                "(每块双标 out 时间 / src 原片时间;注意区分两条时间线)"
            )
            if not edited_storyboard.get("labels_burned", False):
                any_labels_missing = True
            sources = edited_storyboard.get("sources") or []
            if sources:
                lines.append(
                    "- 来源标签: "
                    + ",".join(f"{s['label']}={s['source_id']}" for s in sources)
                )
        if any_labels_missing:
            lines.append(
                "- 时间戳未烧入 → 用 `scripts/recap_inspect.py --work-dir <work_dir> clip-map --output-start <s> --output-end <e>` 查时间(JSON sidecar 仍为权威时间源)"
            )
        lines.append("")
        header = "\n".join(lines) + "\n"
        existing = brief_path.read_text(encoding="utf-8") if brief_path.exists() else ""
        if existing.startswith(_STORYBOARD_HEADING):
            # Re-running on the same brief replaces the earlier header instead of stacking.
            end = existing.find("\n\n", existing.find("\n") + 2)
            existing = existing[end + 2:] if end >= 0 else ""
        brief_path.write_text(header + existing, encoding="utf-8")
    except OSError as exc:
        log(f"storyboard brief 头部写入失败(忽略): {exc}")
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