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

View on GitHub
"""Normalize cut plans and maintain the render-cache sidecar."""

import json
import math
import re

from pathlib import Path

from lib import CONFIG, file_identity, get_video_duration, log


def parse_duration_seconds(value):
    """Parse seconds, 10m/1h forms, or HH:MM:SS into seconds."""
    if value is None or value == "":
        return None
    if isinstance(value, bool):
        raise ValueError(f"invalid duration: {value}")
    if isinstance(value, (int, float)):
        seconds = float(value)
        if not math.isfinite(seconds) or seconds <= 0:
            raise ValueError("duration must be positive")
        return seconds

    text = str(value).strip().lower()
    if not text:
        return None

    if ":" in text:
        parts = text.split(":")
        if len(parts) not in (2, 3):
            raise ValueError(f"invalid duration: {value}")
        try:
            nums = [float(p) for p in parts]
        except ValueError as exc:
            raise ValueError(f"invalid duration: {value}") from exc
        if any(not math.isfinite(n) for n in nums):
            raise ValueError(f"invalid duration: {value}")
        if any(n < 0 for n in nums):
            raise ValueError("duration must be positive")
        if nums[-1] >= 60 or (len(nums) == 3 and nums[-2] >= 60):
            raise ValueError(f"invalid duration: {value}")
        if len(nums) == 2:
            seconds = nums[0] * 60 + nums[1]
        else:
            seconds = nums[0] * 3600 + nums[1] * 60 + nums[2]
        if seconds <= 0:
            raise ValueError("duration must be positive")
        return seconds

    # One or more <number><unit> tokens: "600", "10m", "500ms", "2m30s", "1h5m30s".
    # A bare number is read as seconds; units may be combined (compound durations).
    factors = {"ms": 0.001, "s": 1, "m": 60, "h": 3600}
    sign = 1.0
    body = text
    if body[:1] in "+-":
        sign = -1.0 if body[0] == "-" else 1.0
        body = body[1:]
    token_re = re.compile(r"([0-9]+(?:\.[0-9]+)?)(ms|s|m|h)?")
    pos = 0
    seconds = 0.0
    matched = False
    for m in token_re.finditer(body):
        if m.start() != pos:
            break
        pos = m.end()
        matched = True
        seconds += float(m.group(1)) * factors[m.group(2) or "s"]
    if not matched or pos != len(body):
        raise ValueError(f"invalid duration: {value}")
    seconds *= sign
    if seconds <= 0:
        raise ValueError("duration must be positive")
    return seconds


def _clip_value(raw, *names):
    for name in names:
        if name in raw:
            return raw[name]
    return None


def load_clip_plan(path):
    """Load `clip_plan.json`, accepting either a list or {"clips": [...]} object."""
    return json.loads(Path(path).read_text(encoding="utf-8"))


def _edited_source_meta_path(output_path):
    return Path(str(output_path) + ".meta.json")


def _load_edited_source_meta(output_path):
    """None when never rendered; a sidecar this skill wrote but cannot parse raises."""
    meta_path = _edited_source_meta_path(output_path)
    if not meta_path.exists():
        return None
    return json.loads(meta_path.read_text(encoding="utf-8"))


def _source_identities_for_plan(validated_plan, input_video=None):
    """{path: {size, mtime_ns}} for every media file that can affect edited_source.mp4."""
    # Single-source plans carry no per-clip source_path; the CLI video is the only input.
    paths = {clip["source_path"] for clip in validated_plan["clips"] if "source_path" in clip}
    if not paths and input_video is not None:
        paths.add(str(input_video))
    return {str(Path(path)): file_identity(path) for path in sorted(paths)}


# Version of the picture-format rules in the edited_source encode (yuv420p, colour tags,
# RGB conversion; see media._output_color_tags). Bump it whenever those rules
# change, so a cached edited_source.mp4 rendered under older rules is rebuilt instead of
# reaching the final render with labels it no longer matches.
EDITED_SOURCE_PICTURE_RULES = "yuv420p-color-tags-v2"


def edited_source_render_cache_payload():
    """Render-affecting settings that invalidate edited_source.mp4 cache reuse.

    Keep this payload limited to inputs that can change rendered media bytes.
    Observational QC produced after validation/render is intentionally excluded.
    """
    return {
        "clip_join_audio_fade_ms": round(CONFIG["clip_join_audio_fade_ms"], 3),
        "picture_rules": EDITED_SOURCE_PICTURE_RULES,
    }


def _write_edited_source_meta(output_path, validated_plan, input_video=None):
    meta = {
        "schema_version": 3,
        "plan": validated_plan["clips"],
        "render_cache": edited_source_render_cache_payload(),
        "sources": _source_identities_for_plan(validated_plan, input_video),
        "total_duration": validated_plan["total_duration"],
        "clip_count": len(validated_plan["clips"]),
    }
    _edited_source_meta_path(output_path).write_text(
        json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8"
    )


def should_reuse_edited_source(output_path, validated_plan, input_video=None):
    """True only when a non-empty edited_source.mp4 matches the plan, settings and sources."""
    output_path = Path(output_path)
    if not output_path.exists() or output_path.stat().st_size == 0:
        return False
    meta = _load_edited_source_meta(output_path)
    if not isinstance(meta, dict) or meta.get("schema_version") != 3:
        return False  # never rendered, or a sidecar from an older schema: re-render
    return (
        meta["plan"] == validated_plan["clips"]
        and meta["render_cache"] == edited_source_render_cache_payload()
        and meta["sources"] == _source_identities_for_plan(validated_plan, input_video)
    )


SOURCES_MANIFEST_SHAPE = (
    '{"sources": [{"source_id": ..., "source_path": ...'
    '[, "duration": seconds, "source_work_dir": ...]}]}'
)


def normalize_sources_manifest(sources_manifest):
    """Read the one accepted manifest shape into {source_id: {source_path, duration[, source_work_dir]}}.

    The shape is SOURCES_MANIFEST_SHAPE, which is what video-recap writes. A missing
    duration is probed from the media file.
    """
    rows = sources_manifest.get("sources") if isinstance(sources_manifest, dict) else None
    if not isinstance(rows, list):
        raise ValueError(f"sources manifest must be {SOURCES_MANIFEST_SHAPE}")
    sources = {}
    for idx, raw in enumerate(rows):
        if not isinstance(raw, dict):
            raise ValueError(f"source #{idx + 1} must be an object; expected {SOURCES_MANIFEST_SHAPE}")
        source_id = raw.get("source_id")
        if source_id in (None, ""):
            raise ValueError(f"source #{idx + 1} is missing source_id")
        source_id = str(source_id)
        source_path = raw.get("source_path")
        if not source_path:
            raise ValueError(f"source {source_id} is missing source_path")
        duration = raw.get("duration")
        if duration in (None, ""):
            duration = get_video_duration(source_path)
        try:
            duration = float(duration)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"source {source_id} has invalid duration") from exc
        if duration <= 0:
            raise ValueError(f"source {source_id} has invalid duration")
        sources[source_id] = {
            "source_id": source_id,
            "source_path": str(source_path),
            "duration": duration,
        }
        if raw.get("source_work_dir") not in (None, ""):
            sources[source_id]["source_work_dir"] = str(raw["source_work_dir"])
    if not sources:
        raise ValueError("sources manifest has no sources")
    return sources


def _normalize_clips(raw_plan, target_duration, min_clip_duration, allow_overlap, resolve_source):
    """The normalize loop both plan shapes share.

    `resolve_source(raw, idx)` returns (overlap_key, source_duration, clip_fields):
    overlap is judged per key (None for a single source), the clip is clamped to
    source_duration, and clip_fields are added right after `clip_id`. Clip order
    follows the raw plan, so montage ordering is possible.
    """
    if isinstance(raw_plan, dict):
        raw_clips = raw_plan.get("clips", [])
        plan_target = raw_plan.get("target_duration")
        if target_duration is None and plan_target not in (None, ""):
            target_duration = parse_duration_seconds(plan_target)
        if raw_plan.get("allow_overlap") is True:
            allow_overlap = True
    elif isinstance(raw_plan, list):
        raw_clips = raw_plan
    else:
        raise ValueError(
            "clip_plan.json must be a JSON array or an object with a clips array"
        )

    if not isinstance(raw_clips, list):
        raise ValueError("clip_plan.json field `clips` must be an array")

    min_duration = max(0.05, min_clip_duration)
    clips = []
    skipped_short = []
    accepted_ranges = {}
    cursor = 0.0

    for idx, raw in enumerate(raw_clips):
        if not isinstance(raw, dict):
            log(f"  跳过无效 clip #{idx + 1}: 不是 JSON 对象")
            continue
        overlap_key, source_duration, clip_fields = resolve_source(raw, idx)
        try:
            raw_start = float(_clip_value(raw, "start", "source_start", "in"))
            raw_end = float(_clip_value(raw, "end", "source_end", "out"))
        except (TypeError, ValueError):
            log(f"  跳过无效 clip #{idx + 1}: 缺少数值型 start/end")
            continue
        if raw_end - raw_start < min_duration:
            log(f"  跳过过短 clip #{idx + 1}: {raw_start:.1f}-{raw_end:.1f}s")
            skipped_short.append({"index": idx + 1, "start": round(raw_start, 3), "end": round(raw_end, 3)})
            continue
        start = round(max(0.0, min(raw_start, source_duration)), 3)
        end = round(max(0.0, min(raw_end, source_duration)), 3)
        if end - start < min_duration:
            log(f"  跳过过短 clip #{idx + 1}: {start:.1f}-{end:.1f}s")
            skipped_short.append({"index": idx + 1, "start": start, "end": end})
            continue
        ranges = accepted_ranges.setdefault(overlap_key, [])
        if not allow_overlap and any(raw_start < e and raw_end > s for s, e in ranges):
            where = "" if overlap_key is None else f" for source_id {overlap_key}"
            raise ValueError(
                f"clip #{idx + 1} overlaps an earlier source range{where}; "
                "split or remove duplicate source footage in the clip plan"
            )
        ranges.append((raw_start, raw_end))

        duration = round(end - start, 3)
        clips.append({
            "clip_id": len(clips),
            **clip_fields,
            "source_start": start,
            "source_end": end,
            "output_start": round(cursor, 3),
            "output_end": round(cursor + duration, 3),
            "duration": duration,
            "reason": str(raw.get("reason", raw.get("note", ""))).strip(),
        })
        cursor += duration

    if not clips:
        raise ValueError("clip_plan.json has no valid clips")

    result = {
        "clips": clips,
        "total_duration": round(sum(c["duration"] for c in clips), 3),
        "target_duration": round(target_duration, 3) if target_duration else None,
        "allow_overlap": bool(allow_overlap),
    }
    if skipped_short:
        result["qc"] = {
            "warnings": [{
                "code": "clip_too_short_skipped",
                "severity": "warning",
                "min_clip_duration": round(min_duration, 3),
                "skipped_clips": skipped_short,
            }]
        }
    return result


def normalize_multi_source_clip_plan(
    raw_plan,
    sources_manifest,
    target_duration=None,
    min_clip_duration=0.3,
    allow_overlap=False,
):
    """Validate a multi-source clip plan and map source_id clips to source paths/durations.

    Clip order follows the raw plan; overlap validation is isolated per source_id.
    """
    sources = normalize_sources_manifest(sources_manifest)

    def resolve_source(raw, idx):
        source_id = raw.get("source_id")
        if source_id in (None, ""):
            raise ValueError(f"clip #{idx + 1} is missing source_id")
        source_id = str(source_id)
        source = sources.get(source_id)
        if not source:
            raise ValueError(
                f"clip #{idx + 1} references unknown source_id: {source_id}"
            )
        fields = {"source_id": source_id, "source_path": source["source_path"]}
        return source_id, source["duration"], fields

    plan = _normalize_clips(
        raw_plan, target_duration, min_clip_duration, allow_overlap, resolve_source
    )
    plan["sources"] = {
        sid: {
            "source_path": s["source_path"],
            "duration": round(s["duration"], 3),
            **({"source_work_dir": s["source_work_dir"]} if s.get("source_work_dir") else {}),
        }
        for sid, s in sources.items()
    }
    return plan


def normalize_clip_plan(
    raw_plan,
    video_duration,
    target_duration=None,
    min_clip_duration=0.3,
    allow_overlap=False,
):
    """Validate and enrich an agent-authored single-source clip plan.

    Returns a dict with validated `clips`, `total_duration`, and target metadata.
    """
    plan = _normalize_clips(
        raw_plan,
        target_duration,
        min_clip_duration,
        allow_overlap,
        lambda raw, idx: (None, video_duration, {}),
    )
    plan["source_duration"] = round(video_duration, 3)
    return plan
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