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

View on GitHub
"""Studio Foley / transition SFX synthesis, speech-safe placement, and stem rendering."""

from __future__ import annotations

import array
import math
import random
import subprocess
import sys
import wave
from pathlib import Path

import lib
from artifacts import _load_work_json, file_identity
from source_subtitles import _load_agent_original_subtitles, _narration_gap_windows

SFX_SAMPLE_RATE = 48000
SFX_PRESETS = ("whoosh_soft", "whoosh_crisp", "impact_warm", "riser_subtle")


def synthesize_studio_sfx(preset: str, output_path: str | Path, *, seed: int = 42) -> Path:
    """Synthesize a clean stereo Foley WAV (48 kHz, 16-bit PCM)."""
    if preset not in SFX_PRESETS:
        raise ValueError(f"未知音效预设 {preset!r};可选: {', '.join(SFX_PRESETS)}")
    out = Path(output_path)
    out.parent.mkdir(parents=True, exist_ok=True)
    rng = random.Random(seed)
    sr = SFX_SAMPLE_RATE

    if preset in {"whoosh_soft", "whoosh_crisp"}:
        dur = 0.34 if preset == "whoosh_soft" else 0.25
        peak_pos = 0.46
        n = int(sr * dur)
        lp_l = lp_r = bp_l = bp_r = 0.0
        phase = 0.0
        samples = array.array("h")
        for i in range(n):
            t = i / sr
            u = i / max(1, n - 1)
            if u < peak_pos:
                env = math.sin(0.5 * math.pi * (u / peak_pos)) ** 1.7
            else:
                env = math.cos(0.5 * math.pi * ((u - peak_pos) / (1.0 - peak_pos))) ** 2.1
            cutoff = (700.0 if preset == "whoosh_soft" else 950.0) + (
                2600.0 if preset == "whoosh_soft" else 3600.0
            ) * (env ** 1.3)
            alpha = min(0.82, 2.0 * math.pi * cutoff / sr)
            hp_alpha = min(0.25, 2.0 * math.pi * 220.0 / sr)
            wn_l = rng.uniform(-1.0, 1.0)
            wn_r = rng.uniform(-1.0, 1.0) * 0.72 + wn_l * 0.28
            lp_l += alpha * (wn_l - lp_l)
            lp_r += alpha * (wn_r - lp_r)
            bp_l += hp_alpha * (lp_l - bp_l)
            bp_r += hp_alpha * (lp_r - bp_r)
            air_l = (lp_l - bp_l) * env * 0.62
            air_r = (lp_r - bp_r) * env * 0.62
            freq = 105.0 - 48.0 * u
            phase += 2.0 * math.pi * freq / sr
            body = math.sin(phase) * (env ** 1.8) * 0.28
            pan_l = 0.85 + 0.15 * math.cos(math.pi * u)
            pan_r = 0.85 - 0.15 * math.cos(math.pi * u)
            val_l = max(-0.92, min(0.92, (air_l + body) * pan_l))
            val_r = max(-0.92, min(0.92, (air_r + body) * pan_r))
            samples.append(int(val_l * 32767))
            samples.append(int(val_r * 32767))
    elif preset == "impact_warm":
        dur = 0.64
        n = int(sr * dur)
        phase1 = phase2 = lp_l = lp_r = 0.0
        samples = array.array("h")
        for i in range(n):
            t = i / sr
            u = i / max(1, n - 1)
            attack = min(1.0, t / 0.010)
            sub_env = attack * math.exp(-5.2 * u)
            transient_env = attack * math.exp(-26.0 * u)
            freq = 42.0 + 86.0 * math.exp(-16.0 * u)
            phase1 += 2.0 * math.pi * freq / sr
            phase2 += 2.0 * math.pi * (freq * 1.98) / sr
            sub = (math.sin(phase1) * 0.68 + math.sin(phase2) * 0.18) * sub_env
            wn_l = rng.uniform(-1.0, 1.0)
            wn_r = rng.uniform(-1.0, 1.0)
            alpha = min(0.45, 2.0 * math.pi * 900.0 / sr)
            lp_l += alpha * (wn_l - lp_l)
            lp_r += alpha * (wn_r - lp_r)
            val_l = math.tanh((sub + lp_l * transient_env * 0.24) * 1.15) * 0.86
            val_r = math.tanh((sub + lp_r * transient_env * 0.24) * 1.15) * 0.86
            samples.append(int(val_l * 32767))
            samples.append(int(val_r * 32767))
    else:  # riser_subtle
        dur = 0.82
        n = int(sr * dur)
        lp_l = lp_r = phase = 0.0
        samples = array.array("h")
        for i in range(n):
            u = i / max(1, n - 1)
            tail = min(1.0, (1.0 - u) / 0.06)
            env = (u ** 2.4) * tail
            cutoff = 420.0 + 3100.0 * (u ** 2.0)
            alpha = min(0.85, 2.0 * math.pi * cutoff / sr)
            lp_l += alpha * (rng.uniform(-1.0, 1.0) - lp_l)
            lp_r += alpha * (rng.uniform(-1.0, 1.0) - lp_r)
            freq = 78.0 + 110.0 * (u ** 1.6)
            phase += 2.0 * math.pi * freq / sr
            shimmer = math.sin(phase) * 0.20 * env
            val_l = max(-0.88, min(0.88, lp_l * env * 0.48 + shimmer))
            val_r = max(-0.88, min(0.88, lp_r * env * 0.48 + shimmer))
            samples.append(int(val_l * 32767))
            samples.append(int(val_r * 32767))

    if sys.byteorder != "little":
        samples.byteswap()
    with wave.open(str(out), "wb") as wf:
        wf.setnchannels(2)
        wf.setsampwidth(2)
        wf.setframerate(sr)
        wf.writeframes(samples.tobytes())
    return out


def _load_raw_sfx_events(work_dir: Path) -> list[dict]:
    plan = _load_work_json(work_dir, "packaging_plan.json")
    if isinstance(plan, dict) and isinstance(plan.get("sfx"), list):
        return list(plan["sfx"])
    standalone = _load_work_json(work_dir, "sfx_plan.json")
    if isinstance(standalone, dict) and isinstance(standalone.get("events"), list):
        return list(standalone["events"])
    if isinstance(standalone, list):
        return list(standalone)
    return []


def _kept_dialogue_windows(work_dir: Path, tts_segments: list[dict], video_duration: float) -> list[tuple[float, float]]:
    """Return intervals where original dialogue is audible in narration gaps."""
    gaps = _narration_gap_windows(tts_segments, video_duration, min_gap=0.45)
    if not gaps:
        return []
    protected: list[tuple[float, float]] = []
    orig_subs = _load_agent_original_subtitles(work_dir) or []
    for row in orig_subs:
        s, e = float(row["start"]), float(row["end"])
        for gs, ge in gaps:
            cs, ce = max(s, gs), min(e, ge)
            if ce - cs >= 0.2:
                protected.append((cs, ce))
    is_cut_mode = (work_dir / "clip_plan_validated.json").is_file()
    anchors = _load_work_json(work_dir, "speech_boundary_anchors_output.json")
    if anchors is None and not is_cut_mode:
        anchors = _load_work_json(work_dir, "speech_boundary_anchors.json")
    if isinstance(anchors, dict):
        for span in anchors.get("speech_spans") or ():
            s, e = float(span.get("start", 0.0)), float(span.get("end", 0.0))
            for gs, ge in gaps:
                cs, ce = max(s, gs), min(e, ge)
                if ce - cs >= 0.25:
                    protected.append((cs, ce))
    return sorted(protected)


def _decode_sfx_pcm(audio_path: Path) -> array.array:
    """Decode any audio file to 48 kHz stereo signed 16-bit PCM array."""
    if audio_path.suffix.lower() == ".wav":
        try:
            with wave.open(str(audio_path), "rb") as wf:
                if wf.getnchannels() == 2 and wf.getsampwidth() == 2 and wf.getframerate() == SFX_SAMPLE_RATE:
                    pcm = array.array("h")
                    pcm.frombytes(wf.readframes(wf.getnframes()))
                    if sys.byteorder != "little":
                        pcm.byteswap()
                    return pcm
        except wave.Error:
            pass
    res = subprocess.run(
        [
            "ffmpeg", "-v", "error", "-i", str(audio_path),
            "-f", "s16le", "-acodec", "pcm_s16le", "-ac", "2", "-ar", str(SFX_SAMPLE_RATE), "-",
        ],
        capture_output=True,
        check=False,
    )
    if res.returncode != 0 or not res.stdout:
        stderr = (res.stderr or b"").decode("utf-8", errors="replace").strip()
        raise RuntimeError(f"无法解码音效文件 {audio_path}: {stderr}")
    usable = len(res.stdout) - (len(res.stdout) % 4)
    pcm = array.array("h")
    pcm.frombytes(res.stdout[:usable])
    if sys.byteorder != "little":
        pcm.byteswap()
    return pcm


def _detect_peak_offset_ms(pcm: array.array) -> float:
    """Locate the highest-energy stereo frame in ``pcm`` and return its offset in milliseconds."""
    frames = len(pcm) // 2
    if frames <= 0:
        return 0.0
    best_idx = 0
    best_mag = -1
    step = max(1, frames // 2400)
    for f in range(0, frames, step):
        mag = abs(pcm[2 * f]) + abs(pcm[2 * f + 1])
        if mag > best_mag:
            best_mag = mag
            best_idx = f
    return round(best_idx * 1000.0 / SFX_SAMPLE_RATE, 1)


def build_sfx_track(
    work_dir: str | Path,
    video_duration: float,
    tts_segments: list[dict],
) -> tuple[Path | None, list[dict]]:
    """Render timed SFX into work_dir/sfx_track.wav; return (None, []) when none configured."""
    root = Path(work_dir)
    raw_events = _load_raw_sfx_events(root)
    out_wav = root / "sfx_track.wav"
    if not raw_events:
        out_wav.unlink(missing_ok=True)
        return None, []

    assets_dir = root / "packaging_assets"
    assets_dir.mkdir(parents=True, exist_ok=True)
    protected = _kept_dialogue_windows(root, tts_segments, video_duration)
    total_frames = max(1, int(round(float(video_duration) * SFX_SAMPLE_RATE)))
    placed_events: list[tuple[int, int, int, float, array.array]] = []
    applied: list[dict] = []

    for idx, item in enumerate(raw_events):
        if not isinstance(item, dict):
            raise RuntimeError(f"音效条目 #{idx + 1} 必须是对象")
        start = float(item.get("start", 0.0))
        gain = float(item.get("gain", 0.28))
        if gain <= 0.0 or start >= video_duration - 0.05:
            continue
        start = max(0.0, start)
        raw_path = str(item.get("path") or "").strip()
        preset = str(item.get("preset") or "").strip()
        if raw_path:
            src_path = Path(raw_path).expanduser()
            if not src_path.is_absolute():
                src_path = (root / src_path).resolve()
            else:
                src_path = src_path.resolve()
            if not src_path.is_file():
                raise RuntimeError(f"音效文件不存在: {src_path}")
        elif preset:
            src_path = assets_dir / f"sfx_{preset}.wav"
            if not src_path.is_file():
                synthesize_studio_sfx(preset, src_path, seed=42 + idx)
        else:
            raise RuntimeError(f"音效条目 #{idx + 1} 必须提供 path 或 preset")

        pcm = _decode_sfx_pcm(src_path)
        frames = len(pcm) // 2
        if frames <= 0:
            continue
        dur = frames / SFX_SAMPLE_RATE
        raw_peak_ms = item.get("peak_offset_ms")
        if isinstance(raw_peak_ms, (int, float)) and not isinstance(raw_peak_ms, bool) and raw_peak_ms > 0:
            peak_ms = float(raw_peak_ms)
        elif item.get("align_peak") is True:
            peak_ms = _detect_peak_offset_ms(pcm)
        else:
            peak_ms = 0.0
        if peak_ms > 0.0:
            start = max(0.0, start - min(dur * 0.9, peak_ms / 1000.0))
        end = min(float(video_duration), start + dur)

        if not item.get("allow_over_dialogue", False):
            overlaps = [
                (ps, pe) for ps, pe in protected
                if min(end, pe) - max(start, ps) > 0.04
            ]
            if overlaps:
                ps, _pe = overlaps[0]
                shifted_end = ps - 0.02
                shifted_start = shifted_end - dur
                if shifted_start >= 0.0 and abs(shifted_start - start) <= 0.25 and all(
                    min(shifted_end, b) - max(shifted_start, a) <= 0.02 for a, b in protected
                ):
                    start, end = shifted_start, shifted_end
                else:
                    lib.log(f"  ⚠️ 跳过覆盖原声台词的音效 #{idx + 1} ({start:.2f}s–{end:.2f}s)")
                    continue

        s_frame = int(round(start * SFX_SAMPLE_RATE))
        max_copy = min(frames, total_frames - s_frame)
        if max_copy <= 0:
            continue
        placed_events.append((idx, s_frame, max_copy, gain, pcm))

        applied.append({
            "index": idx,
            "path": str(src_path),
            "preset": preset or None,
            "start": round(start, 3),
            "end": round(start + max_copy / SFX_SAMPLE_RATE, 3),
            "gain": round(gain, 4),
            "peak_offset_ms": round(peak_ms, 1),
            **file_identity(src_path),
        })

    if not applied:
        out_wav.unlink(missing_ok=True)
        return None, []

    spans: list[list] = []
    for ev in sorted(placed_events, key=lambda e: (e[1], e[0])):
        s_frame, max_copy = ev[1], ev[2]
        e_frame = s_frame + max_copy
        if spans and s_frame < spans[-1][1]:
            spans[-1][1] = max(spans[-1][1], e_frame)
            spans[-1][2].append(ev)
        else:
            spans.append([s_frame, e_frame, [ev]])

    out_pcm = array.array("h", bytes(total_frames * 4))
    for span_s, span_e, group in spans:
        span_len = span_e - span_s
        span_l = [0.0] * span_len
        span_r = [0.0] * span_len
        for _idx, s_frame, max_copy, gain, pcm in sorted(group, key=lambda e: e[0]):
            offset = s_frame - span_s
            fade_frames = min(int(0.015 * SFX_SAMPLE_RATE), max_copy // 3)
            for f in range(max_copy):
                env = gain
                if fade_frames > 0 and f < fade_frames:
                    env *= f / fade_frames
                elif fade_frames > 0 and f > max_copy - fade_frames:
                    env *= (max_copy - f) / fade_frames
                span_l[offset + f] += (pcm[2 * f] / 32768.0) * env
                span_r[offset + f] += (pcm[2 * f + 1] / 32768.0) * env
        base = span_s * 2
        for i in range(span_len):
            out_pcm[base + 2 * i] = int(max(-0.96, min(0.96, math.tanh(span_l[i]))) * 32767)
            out_pcm[base + 2 * i + 1] = int(max(-0.96, min(0.96, math.tanh(span_r[i]))) * 32767)

    if sys.byteorder != "little":
        out_pcm.byteswap()
    with wave.open(str(out_wav), "wb") as wf:
        wf.setnchannels(2)
        wf.setsampwidth(2)
        wf.setframerate(SFX_SAMPLE_RATE)
        wf.writeframes(out_pcm.tobytes())
    lib.log(f"音效合成轨: {out_wav} ({len(applied)} 处音效)")
    return out_wav, applied


def sfx_settings(work_dir: str | Path | None) -> dict:
    """Audit record for assembly_manifest.json."""
    if work_dir is None:
        return {"present": False, "events": []}
    root = Path(work_dir)
    events = _load_raw_sfx_events(root)
    if not events:
        return {"present": False, "events": []}
    return {
        "present": True,
        "count": len(events),
        "events": [
            {
                "start": float(e.get("start", 0.0)),
                "gain": float(e.get("gain", 0.28)),
                "preset": e.get("preset"),
                "path": str(Path(e["path"]).expanduser().resolve()) if e.get("path") else None,
            }
            for e in events if isinstance(e, dict)
        ],
    }
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