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

View on GitHub
"""Snap clip boundaries to complete speech and clean shot transitions."""

import json
import re
import subprocess
from pathlib import Path

from frame_grid import edge_frame_snapper, snap_edges_to_frames
from lib import log
from sentence_gate import (
    _GATE_TOLERANCE,
    _continuous_source_join,
    _edge_classifier,
    _edge_joined,
    _unverified_window,
    enforce_clip_sentence_boundaries,
)
from speech_ownership import _dialogue_speech_spans


def _find_source_artifact(work_dir, filename, source_id=None, source_work_dir=None):
    """First existing copy of a per-source understanding artifact, by layout precedence."""
    candidates = []
    if source_work_dir:
        candidates.append(Path(work_dir) / source_work_dir / filename)
    if source_id is not None:
        candidates.append(Path(work_dir) / "sources" / source_id / filename)
    candidates.append(Path(work_dir) / filename)
    return next((path for path in candidates if path.exists()), None)


def _load_sentence_boundary_windows(work_dir, source_id=None, source_work_dir=None):
    """Load usable sentence-end pause windows produced by understand.py.

    A sentence anchor's `time` is the acoustic pause end, while `pause_start` is already
    after the final spoken sample. Any cut within that closed interval is word-safe.
    `boundary_use: unverified` anchors (coarse-ASR estimates) stay usable but keep that
    label so an edge resting on one is reported as such; `none` anchors are excluded.
    """
    path = _find_source_artifact(
        work_dir, "speech_boundary_anchors.json", source_id, source_work_dir
    )
    if path is None:
        return []
    payload = json.loads(path.read_text(encoding="utf-8"))
    windows = []
    for anchor in payload["sentence_anchors"]:
        # Schema-1 anchors (no `boundary_use`) came from the old coarse estimator: high/medium
        # labels there are usable but unverified.
        use = anchor.get("boundary_use") or (
            "unverified" if anchor["confidence"] in {"high", "medium"} else "none"
        )
        if use == "none":
            continue
        windows.append({
            "start": round(anchor["pause_start"], 3),
            "end": round(anchor["time"], 3),
            "kind": "sentence_anchor",
            "confidence": anchor["confidence"],
            "boundary_use": use,
        })
    return sorted(windows, key=lambda row: (row["start"], row["end"]))


def _load_source_speech_spans(work_dir, source_id=None, source_work_dir=None):
    """Merged dialogue spans from asr_result.json.

    Only used to decide whether an unsafe edge blocks; a missing transcript means unchecked.
    """
    path = _find_source_artifact(work_dir, "asr_result.json", source_id, source_work_dir)
    rows = json.loads(path.read_text(encoding="utf-8")) if path is not None else []
    return _dialogue_speech_spans(row for row in rows if row["text"].strip())


def _combine_boundary_windows(*groups):
    """Dedupe windows by span; a span backed by any verified/quiet row counts as verified."""
    unique = {}
    for group in groups:
        for row in group:
            key = (round(row["start"], 3), round(row["end"], 3))
            if key not in unique or _unverified_window(unique[key]):
                unique[key] = row
    combined = []
    for (start, end), row in sorted(unique.items()):
        item = {"start": start, "end": end, "kind": row.get("kind", "quiet_window")}
        if _unverified_window(row):
            item["boundary_use"] = "unverified"
        combined.append(item)
    return combined


def _recompute_clip_timeline(clips):
    cursor = 0.0
    for clip in clips:
        duration = round(clip["source_end"] - clip["source_start"], 3)
        clip["duration"] = duration
        clip["output_start"] = round(cursor, 3)
        clip["output_end"] = round(cursor + duration, 3)
        cursor += duration
    return round(cursor, 3)


def _plan_with_snapped_clips(plan, clips, boundary_key, events):
    """Copy of `plan` carrying the snapped clips, a cursor-based output timeline, and the
    per-pass boundary events under qc.boundary_status[boundary_key]."""
    result = dict(plan)
    result["clips"] = clips
    result["total_duration"] = _recompute_clip_timeline(clips)
    qc = dict(plan.get("qc", {}))
    boundary = dict(qc.get("boundary_status", {}))
    boundary[boundary_key] = events
    qc["boundary_status"] = boundary
    result["qc"] = qc
    return result


def _same_clip_source(left, right):
    return left.get("source_id") == right.get("source_id") and left.get(
        "source_path"
    ) == right.get("source_path")


def _seamless_internal_seams(clips, tolerance=0.02):
    """Return (locked_starts, locked_ends) indices of contiguous same-source splits."""
    locked_starts, locked_ends = set(), set()
    for i in range(len(clips) - 1):
        left, right = clips[i], clips[i + 1]
        if (
            right.get("clip_id", i + 1) - left.get("clip_id", i) == 1
            and _same_clip_source(left, right)
            and abs(float(left["source_end"]) - float(right["source_start"])) <= tolerance
        ):
            locked_ends.add(i)
            locked_starts.add(i + 1)
    return locked_starts, locked_ends


def _candidate_overlaps(clips, idx, new_start, new_end):
    return any(
        new_start < other["source_end"] and new_end > other["source_start"]
        for j, other in enumerate(clips)
        if j != idx
    )


def snap_clip_starts_to_lines(
    plan,
    silence_periods,
    video_duration,
    max_prepend,
    max_trim=0.35,
    min_clip_duration=0.3,
    *,
    shot_cuts=(),
    flash_sliver_max_seconds=0.0,
    locked_starts=(),
):
    """Snap clip starts to natural quiet boundaries, preferring safe prepend over trim.

    Policy:
    - start already inside a quiet window: keep.
    - speech start: prepend to nearest prior quiet window end if within max_prepend.
    - no usable prior quiet: keep and warn, except an extremely near next quiet start
      (<= max_trim) may trim forward if duration/overlap safety holds.
    - never overlap/collapse when allow_overlap is false; unsafe attempts keep-and-warn.
    """
    if not silence_periods:
        return plan

    clips = [dict(c) for c in plan["clips"]]
    allow_overlap = plan["allow_overlap"]
    events = []

    for i, clip in enumerate(clips):
        original_start = clip["source_start"]
        source_end = clip["source_end"]
        event = {
            "clip_id": clip["clip_id"],
            "source_id": clip.get("source_id"),
            "original_start": round(original_start, 3),
            "action": "kept",
        }

        if i in locked_starts:
            event["reason"] = "continuous_source_join"
            events.append(event)
            continue

        if any(w["start"] <= original_start <= w["end"] for w in silence_periods):
            event["reason"] = "already_quiet"
            events.append(event)
            continue

        prior_ends = [w["end"] for w in silence_periods if w["end"] <= original_start]
        if prior_ends:
            candidate_start = max(prior_ends)
            if original_start - candidate_start <= max_prepend:
                candidate_start = round(candidate_start, 3)
                creates_sliver = (
                    flash_sliver_max_seconds > 0
                    and any(
                        candidate_start + 1e-3 < cut <= min(
                            original_start + 1e-3,
                            candidate_start + flash_sliver_max_seconds + 1e-6,
                        )
                        for cut in shot_cuts
                    )
                )
                safe = (
                    not creates_sliver
                    and candidate_start < source_end - min_clip_duration + 1e-9
                )
                if safe and not allow_overlap:
                    safe = not _candidate_overlaps(clips, i, candidate_start, source_end)
                if safe:
                    clip["source_start"] = candidate_start
                    event.update(
                        {
                            "action": "prepended",
                            "new_start": candidate_start,
                            "delta": round(original_start - candidate_start, 3),
                        }
                    )
                    events.append(event)
                    continue
                reason = "prepend_creates_flash_sliver" if creates_sliver else "overlap_or_collapse"
            else:
                reason = "prior_quiet_too_far"
        else:
            reason = "no_prior_quiet"

        next_starts = [w["start"] for w in silence_periods if w["start"] >= original_start]
        if next_starts:
            candidate_start = min(next_starts)
            trim_delta = candidate_start - original_start
            if 0 < trim_delta <= max_trim:
                candidate_start = round(min(video_duration, candidate_start), 3)
                safe = source_end - candidate_start >= min_clip_duration
                if safe and not allow_overlap:
                    safe = not _candidate_overlaps(clips, i, candidate_start, source_end)
                if safe:
                    clip["source_start"] = candidate_start
                    event.update(
                        {
                            "action": "trimmed",
                            "new_start": candidate_start,
                            "delta": round(trim_delta, 3),
                            "fallback_from": reason,
                        }
                    )
                    events.append(event)
                    continue
                reason = "unsafe_forward_trim"

        event["start_unsnapped_reason"] = reason
        event["warning_code"] = "clip_start_unsnapped"
        events.append(event)

    result = _plan_with_snapped_clips(plan, clips, "start_snaps", events)
    warnings = list(result["qc"].get("warnings", []))
    for event in events:
        if "warning_code" in event:
            warnings.append(
                {
                    "code": event["warning_code"],
                    "clip_id": event["clip_id"],
                    "source_id": event["source_id"],
                    "start_unsnapped_reason": event["start_unsnapped_reason"],
                }
            )
    if warnings:
        result["qc"]["warnings"] = warnings
    return result


def snap_clip_ends_to_lines(
    plan,
    silence_periods,
    video_duration,
    max_extend,
    *,
    pause_pad=0.0,
    shot_cuts=(),
    locked_ends=(),
):
    """Extend each clip's source_end forward to the next natural pause, preventing mid-sentence cuts.

    - No quiet windows: the plan is returned unchanged.
    - A source_end already inside a quiet window is left alone.
    - Otherwise extend to the next quiet window start (plus up to `pause_pad` inside that pause
      so the speaker's reaction/breath lands cleanly instead of chopping at 0 ms), capped by
      max_extend, any nearby shot cut inside the pause pad, and video_duration.
    - When plan["allow_overlap"] is False, never extend into another clip's source range.
    - Recomputes output_start/output_end/duration for all clips cursor-based.
    """
    if not silence_periods:
        return plan

    clips = [dict(c) for c in plan["clips"]]
    allow_overlap = plan["allow_overlap"]
    events = []
    pad = max(0.0, float(pause_pad))

    for i, clip in enumerate(clips):
        source_end = clip["source_end"]
        event = {
            "clip_id": clip["clip_id"],
            "source_id": clip.get("source_id"),
            "original_end": round(source_end, 3),
            "action": "kept",
        }

        if i in locked_ends:
            event["reason"] = "continuous_source_join"
            events.append(event)
            continue

        if any(w["start"] <= source_end <= w["end"] for w in silence_periods):
            event["reason"] = "already_quiet"
            events.append(event)
            continue

        candidate_windows = [w for w in silence_periods if w["start"] >= source_end]
        if not candidate_windows:
            event["end_unsnapped_reason"] = "no_next_quiet"
            events.append(event)
            continue
        target_window = min(candidate_windows, key=lambda w: (w["start"], -w["end"]))
        next_quiet_start = target_window["start"]

        if next_quiet_start > source_end + max_extend:
            event["end_unsnapped_reason"] = "next_quiet_too_far"
            events.append(event)
            continue
        padded_target = next_quiet_start
        if pad > 0.0:
            padded_target = min(target_window["end"], next_quiet_start + pad)
            cuts_in_pad = [c for c in shot_cuts if next_quiet_start + 1e-3 < c <= padded_target]
            if cuts_in_pad:
                padded_target = max(next_quiet_start, min(cuts_in_pad) - 0.001)
            padded_target = min(padded_target, source_end + max_extend)
        candidate_end = min(padded_target, video_duration)
        if candidate_end <= source_end:
            event["end_unsnapped_reason"] = "non_forward_candidate"
            events.append(event)
            continue

        # When overlaps are forbidden, cap against every other clip's source range.
        if not allow_overlap:
            source_start = clip["source_start"]
            other_starts = [
                c["source_start"]
                for j, c in enumerate(clips)
                if j != i
                and _same_clip_source(clip, c)
                and c["source_end"] > source_start
                and c["source_start"] >= source_end - 1e-6
            ]
            if other_starts:
                candidate_end = min(candidate_end, min(other_starts))
            if candidate_end <= source_end:
                event["end_unsnapped_reason"] = "overlap_or_collapse"
                events.append(event)
                continue

        clip["source_end"] = round(candidate_end, 3)
        event.update(
            {
                "action": "extended",
                "new_end": clip["source_end"],
                "delta": round(clip["source_end"] - source_end, 3),
            }
        )
        events.append(event)

    return _plan_with_snapped_clips(plan, clips, "end_snaps", events)


def _detect_shot_changes(video, win_start, win_end, threshold, lead=0.25):
    """Absolute source-time hard cuts inside [win_start, win_end] via ffmpeg's scene metric.

    Input-seek to a little before the window: the rebased output PTS restarts at ~0 at the seek
    target, so `seek + pts_time` recovers absolute source time. The `lead` keeps the seek/keyframe
    settling artifact frame outside [win_start, win_end] so it is filtered out, not mistaken for a
    cut.
    """
    if win_end - win_start < 1e-3:
        return []
    seek = max(0.0, win_start - lead)
    dur = (win_end - seek) + 0.1
    cmd = [
        "ffmpeg",
        "-hide_banner",
        "-nostats",
        "-ss",
        f"{seek:.3f}",
        "-i",
        str(video),
        "-t",
        f"{dur:.3f}",
        "-an",
        "-sn",
        "-filter:v",
        f"select='gt(scene,{threshold})',showinfo",
        "-f",
        "null",
        "-",
    ]
    proc = subprocess.run(cmd, capture_output=True, text=True)
    if proc.returncode != 0:
        raise RuntimeError(f"ffmpeg 切镜头检测失败: {video}: {proc.stderr.strip()[-500:]}")
    changes = set()
    for m in re.finditer(r"pts_time:([0-9.]+)", proc.stderr):
        t = seek + float(m.group(1))
        if win_start <= t <= win_end:
            changes.add(round(t, 3))
    return sorted(changes)


# How far past each edge's own search window the shot-change scan also looks, so a hard cut
# within a frame on the other side of the edge is known to the frame-grid pass.
_FRAME_CUT_SCAN_PAD = 0.1


def snap_clips_off_shot_changes(
    plan,
    video,
    margin,
    threshold,
    min_keep=0.5,
    found_cuts=None,
    *,
    start_lookback=0.0,
    locked_starts=(),
    locked_ends=(),
):
    """Nudge each clip's boundaries clear of the ORIGINAL footage's hard cuts to avoid 闪烁.

    A clip whose source_start sits just before a shot-change opens on a brief sliver of the old
    shot that then hard-cuts again; one whose source_end sits just after a shot-change closes on a
    sliver of the next shot. Both flash at the edit point. So:
      - move source_start FORWARD onto a shot-change in (start, start+margin]  → clean open
      - move source_end   BACK   onto a shot-change in [end-margin, end)       → clean close
    Boundaries already on a cut, or with no nearby cut, are left untouched. Snaps that would shrink
    a clip below `min_keep` are skipped. Recomputes the output timeline cursor-based.

    `found_cuts` (a set) collects every cut the scan saw, including those up to
    `_FRAME_CUT_SCAN_PAD` on the far side of each edge, for the frame-grid pass's tie-break.
    """
    if margin <= 0:
        return plan
    pad = _FRAME_CUT_SCAN_PAD if found_cuts is not None else 0.0
    found_cuts = set() if found_cuts is None else found_cuts
    clips = [dict(c) for c in plan["clips"]]
    n_start = n_end = 0
    events = []
    for idx, clip in enumerate(clips):
        s = clip["source_start"]
        e = clip["source_end"]
        new_s, new_e = s, e
        event = {
            "clip_id": clip["clip_id"],
            "source_id": clip.get("source_id"),
            "original_start": round(s, 3),
            "original_end": round(e, 3),
            "start_action": "kept",
            "end_action": "kept",
        }
        # Opening: a shot-change just AFTER source_start leaves an old-shot sliver before it.
        if idx in locked_starts:
            event["start_reason"] = "continuous_source_join"
        else:
            seen = _detect_shot_changes(
                video, max(0.0, s - max(pad, start_lookback)), min(e, s + margin), threshold
            )
            found_cuts.update(seen)
            start_changes = [c for c in seen if c > s + 1e-3]
            if start_changes:
                cand = max(start_changes)  # open after the last rapid cut in the window
                if cand < e - min_keep:
                    new_s = round(cand, 3)
                    event["start_action"] = "moved_forward"
                    event["new_start"] = new_s
                else:
                    event["start_unsnapped_reason"] = "collapse"
        # Closing: a shot-change just BEFORE source_end leaves a next-shot sliver after it.
        if idx in locked_ends:
            event["end_reason"] = "continuous_source_join"
        else:
            seen = _detect_shot_changes(video, max(new_s, e - margin), e + pad, threshold)
            found_cuts.update(seen)
            end_changes = [c for c in seen if c < e - 1e-3]
            if end_changes:
                cand = min(end_changes)  # close before the first rapid cut in the window
                if cand > new_s + min_keep:
                    new_e = round(cand, 3)
                    event["end_action"] = "moved_back"
                    event["new_end"] = new_e
                else:
                    event["end_unsnapped_reason"] = "collapse"
        n_start += new_s != s
        n_end += new_e != e
        clip["source_start"] = new_s
        clip["source_end"] = new_e
        events.append(event)

    if n_start or n_end:
        log(
            f"避让原片切镜头: {n_start} 个起点前移、{n_end} 个终点回收 (margin={margin}s, 阈值={threshold})"
        )
    return _plan_with_snapped_clips(plan, clips, "shot_snaps", events)


def _revert_unsafe_shot_snaps(plan, before, classify, *, flash_sliver_max_seconds=0.0):
    """Undo a shot-change move that left an edge in speech where the plan's own edge was safe.

    Sound outranks picture cleanup for ordinary L-cut overlaps (> flash_sliver_max_seconds).
    However, when reverting would re-expose a <= flash_sliver_max_seconds (1-5 frame) flash
    sliver at the edit point while keeping the shot cut would truncate speech, neither choice
    is acceptable: record a blocking `shot_speech_conflict` so the clip plan adjusts the cut.
    """
    events = plan.get("qc", {}).get("boundary_status", {}).get("shot_snaps", [])
    if len(events) != len(before):
        return plan
    clips = [dict(c) for c in plan["clips"]]
    events = [dict(e) for e in events]
    reverted = 0
    conflicts = []
    for idx, (clip, old, event) in enumerate(zip(clips, before, events)):
        for edge, key, moved in (("start", "source_start", "moved_forward"),
                                 ("end", "source_end", "moved_back")):
            if event[f"{edge}_action"] != moved:
                continue
            status, reason = classify(edge, clip[key], _edge_joined(clips, idx, edge))
            if status != "blocking" or classify(
                    edge, old[key], _edge_joined(before, idx, edge))[0] != "safe":
                continue
            sliver_seconds = abs(clip[key] - old[key])
            if flash_sliver_max_seconds > 0 and sliver_seconds <= flash_sliver_max_seconds + 1e-6:
                event[f"{edge}_action"] = "blocked_shot_speech_conflict"
                event[f"{edge}_conflict_reason"] = reason
                conflicts.append({
                    "code": "shot_speech_conflict",
                    "clip_id": clip["clip_id"],
                    "source_id": clip.get("source_id"),
                    "edge": edge,
                    "original_time": round(old[key], 3),
                    "shot_cut_time": round(clip[key], 3),
                    "sliver_seconds": round(sliver_seconds, 3),
                    "speech_reason": reason,
                })
                continue
            span = {**clip, key: old[key]}
            if not plan["allow_overlap"] and _candidate_overlaps(
                    clips, idx, span["source_start"], span["source_end"]):
                continue
            clip[key] = old[key]
            event[f"{edge}_action"] = "reverted_unsafe"
            event[f"rejected_{edge}"] = event.pop(f"new_{edge}")
            event[f"{edge}_revert_reason"] = reason
            reverted += 1
    if not reverted and not conflicts:
        return plan
    if reverted:
        log(f"切镜头避让会截断原声,已撤回 {reverted} 处边界")
    updated = _plan_with_snapped_clips(plan, clips, "shot_snaps", events)
    if conflicts:
        updated["qc"].setdefault("blocking", []).extend(conflicts)
    return updated


def _load_silence_for_source(work_dir, source_id, source_work_dir=None):
    """Read a source's silence_periods.json (project layout when source_id is None); [] when absent."""
    path = _find_source_artifact(work_dir, "silence_periods.json", source_id, source_work_dir)
    return json.loads(path.read_text(encoding="utf-8")) if path else []


def snap_source_clips(
    plan,
    video,
    duration,
    work_dir,
    *,
    line_max_extend,
    scene_margin,
    scene_threshold,
    start_max_prepend,
    start_max_trim,
    end_pause_pad=0.0,
    flash_sliver_max_seconds=0.0,
    do_line_snap=True,
    do_scene_snap=True,
    source_id=None,
    source_work_dir=None,
    frame_grid=None,
):
    """Snap every clip of ONE source: shot changes, quiet starts/ends, frame grid, then the gate.

    Visual cleanup goes first. Sentence/quiet snapping is the sound authority because a
    clean picture is never allowed to reintroduce a mid-sentence audio cut (a shot-change
    move line snapping cannot repair is reverted when the plan's own edge was gate-safe);
    the frame-grid pass only moves an edge by under a frame and prefers the side that keeps
    it safe, then the side that does not straddle a hard cut the shot-change scan saw, and
    the gate judges the final, frame-aligned edges. source_id None reads the
    project-level understanding artifacts (single-source layout). frame_grid is a
    frame_grid.source_frame_grids() entry; None leaves edges off the grid.
    """
    locked_starts, locked_ends = _seamless_internal_seams(plan["clips"])
    before_shot_snap = [dict(c) for c in plan["clips"]]
    scene_cuts = set()
    if do_scene_snap:
        plan = snap_clips_off_shot_changes(
            plan,
            video,
            margin=scene_margin,
            threshold=scene_threshold,
            found_cuts=scene_cuts,
            start_lookback=start_max_prepend if do_line_snap else 0.0,
            locked_starts=locked_starts,
            locked_ends=locked_ends,
        )
    boundaries = _combine_boundary_windows(
        _load_silence_for_source(work_dir, source_id, source_work_dir),
        _load_sentence_boundary_windows(work_dir, source_id, source_work_dir),
    )
    if do_line_snap:
        plan = snap_clip_starts_to_lines(
            plan,
            boundaries,
            duration,
            start_max_prepend,
            max_trim=start_max_trim,
            shot_cuts=scene_cuts,
            flash_sliver_max_seconds=flash_sliver_max_seconds,
            locked_starts=locked_starts,
        )
        plan = snap_clip_ends_to_lines(
            plan,
            boundaries,
            duration,
            line_max_extend,
            pause_pad=end_pause_pad,
            shot_cuts=scene_cuts,
            locked_ends=locked_ends,
        )
    speech_spans = _load_source_speech_spans(work_dir, source_id, source_work_dir)
    video_start = frame_grid["origin"] if frame_grid is not None else 0.0
    classify = _edge_classifier(boundaries, speech_spans, duration, _GATE_TOLERANCE,
                                video_start)
    if do_scene_snap:
        plan = _revert_unsafe_shot_snaps(
            plan,
            before_shot_snap,
            classify,
            flash_sliver_max_seconds=flash_sliver_max_seconds,
        )
    if frame_grid is None:
        return enforce_clip_sentence_boundaries(plan, boundaries, speech_spans, duration)

    frame_grid = {**frame_grid, "scene_cuts": sorted(scene_cuts)}
    clips = plan["clips"]
    joined = [
        idx > 0 and (idx in locked_starts or _continuous_source_join(clips[idx - 1], clip))
        for idx, clip in enumerate(clips)
    ]
    clips, events = snap_edges_to_frames(
        clips, frame_grid, boundaries, classify, duration,
        allow_overlap=plan["allow_overlap"], joined_to_previous=joined,
    )
    plan = _plan_with_snapped_clips(plan, clips, "frame_snaps", events)
    return enforce_clip_sentence_boundaries(
        plan, boundaries, speech_spans, duration, video_start=video_start,
        frame_snap=edge_frame_snapper(frame_grid, boundaries, classify, duration),
    )


def snap_multi_source_clips(plan, sources, work_dir, frame_grids=None, **snap_options):
    """Per-source snap_source_clips for a multi-source validated plan.

    Each clip is snapped using ITS OWN source's silence windows / shot changes, frame grid
    and duration (a clip in source B never constrains a clip in source A), then the global
    OUTPUT timeline is recomputed once in plan order. Missing silence data leaves a boundary
    unchanged. `frame_grids` maps source_id to its frame grid; `snap_options` are
    snap_source_clips' keyword options.
    """
    clips = plan["clips"]
    allow_overlap = plan["allow_overlap"]
    groups = {}
    for clip in clips:
        groups.setdefault(clip["source_id"], []).append(clip)
    boundary_accum = {
        "start_snaps": [],
        "end_snaps": [],
        "shot_snaps": [],
        "frame_snaps": [],
        "sentence_checks": [],
    }
    blocking_accum = []
    for sid, group in groups.items():
        source = sources[sid]
        mini = snap_source_clips(
            {"clips": [dict(c) for c in group], "allow_overlap": allow_overlap},
            source["source_path"],
            source["duration"],
            work_dir,
            source_id=sid,
            source_work_dir=source.get("source_work_dir"),
            frame_grid=(frame_grids or {}).get(sid),
            **snap_options,
        )
        mini_boundary = mini["qc"]["boundary_status"]
        for key, events in boundary_accum.items():
            events.extend(mini_boundary.get(key, []))
        blocking_accum.extend(mini["qc"].get("blocking", []))
        for original, snapped in zip(group, mini["clips"]):
            original["source_start"] = snapped["source_start"]
            original["source_end"] = snapped["source_end"]
    # Recompute the global output timeline cursor-based, in plan order (not group order).
    plan["total_duration"] = _recompute_clip_timeline(clips)

    qc = plan.setdefault("qc", {})
    boundary = qc.setdefault("boundary_status", {})
    for key, events in boundary_accum.items():
        if events:
            boundary.setdefault(key, []).extend(events)
    warnings = qc.setdefault("warnings", [])
    for event in boundary_accum["start_snaps"]:
        if "warning_code" in event:
            warnings.append(
                {
                    "code": event["warning_code"],
                    "clip_id": event["clip_id"],
                    "source_id": event["source_id"],
                    "start_unsnapped_reason": event["start_unsnapped_reason"],
                }
            )
    # A mid-sentence cut must never be dropped because some sibling QC list came back empty.
    if blocking_accum:
        qc.setdefault("blocking", []).extend(blocking_accum)
    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