Communitygithub.com

govindgoel2001/video-editing-toolkit

透過對話編輯任何影片。自動轉錄、剪輯、調色、生成覆蓋動畫、燒錄字幕 — 適用於訪談、教學、旅遊、紀錄片等。無預設、無選單。提問、確認計劃、執行、疊代、持久化。生產正確性規則嚴格;其餘皆為藝術自由。

video-editing-toolkit 是什麼?

這是一個專為 AI 代理(如 Claude Code、Cursor、Codex)設計的影片編輯技能,核心概念是「透過對話編輯影片」。使用者不需要學習複雜的編輯軟體,而是直接以自然語言描述需求,AI 代理會根據影片素材的實際內容進行推論、提問、規劃,並在獲得使用者確認後才執行剪輯、調色、動畫與字幕等操作。該技能採用音訊優先的編輯策略,從語音轉錄(Scribe)分析出發,將剪輯點對齊詞邊界,並透過 `ffmpeg`、`PIL` 等工具實現專業級效果。其工作流程包含素材盤點、問題預掃、策略討論、分段提取、並行動畫渲染與最終合成,並內建嚴格的生產正確性規則(如字幕最後疊加、30ms 音訊淡出、避免重複編碼等)以確保輸出品質。支援多種影片類型,包括訪談、教學、產品發表、紀錄片、旅遊與音樂影片等。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/govindgoel2001/video-editing-toolkit/tree/HEAD/vendor/video-use

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

影片使用

原則

  1. LLM 從原始轉錄與按需視覺素材推論。 唯一值得保留的衍生產物是帶時間戳的短語級轉錄(takes_packed.md)。其他一切——填充詞標記、重拍偵測、鏡頭分類、強調評分——都在決策時即時推導。
  2. 音訊為主,視覺為輔。 剪輯候選點來自語音邊界與靜音間隙。僅在決策點深入檢視視覺素材。
  3. 詢問 → 確認 → 執行 → 疊代 → 持久化。 在使用者以白話文確認策略之前,絕不觸碰剪輯。
  4. 概化(Generalize)。 不要預先假設這是哪種影片。審視素材,詢問使用者,然後編輯。
  5. 藝術自由為預設。 本文檔中的每一個具體數值、預設、字型、顏色、時長、音高結構與技術,都只是一個已驗證影片的實際範例——並非強制規範。閱讀它們以了解可能性及其成功原因。然後根據實際素材與使用者的真實需求,做出你自己的品味判斷。你唯一必須遵守的事項在下方「硬性規則」部分。 其餘皆由你決定。
  6. 自由創造。 如果素材需要文中未描述的技術——分割畫面、子母畫面、下身姓名卡、反應剪輯、速度斜坡、定格畫面、交叉淡出、匹配剪輯、L-cut、J-cut、呼吸節奏速度斜坡,等等——就大膽建構。輔助工具是 ffmpeg 和 PIL。只要格式支援,它們什麼都能做。無需等待許可。
  7. 在展示給使用者之前,先自我驗證輸出。 如果你自己不願意出貨,就不要呈現。

硬性規則(生產正確性——不可協商)

這些是偏離會導致靜默失敗或輸出損壞的事項。它們關乎正確性,而非品味。請牢記。

  1. 字幕在濾鏡鏈中「最後」疊加,在所有覆蓋層之後。否則覆蓋層會遮擋字幕。靜默失敗。
  2. 分段提取 → 無損 -c copy 拼接,而非單程濾鏡圖。否則在加入覆蓋層時,每個分段都會被二次編碼。
  3. 每個分段邊界加入 30ms 音訊淡出(afade=t=in:st=0:d=0.03,afade=t=out:st={dur-0.03}:d=0.03)。否則每次剪輯都會有可聽見的爆音。
  4. 覆蓋層使用 setpts=PTS-STARTPTS+T/TB 將其第 0 幀位移至指定的顯示視窗起始點。否則在覆蓋視窗期間會看到動畫的中間部分。
  5. 主 SRT 使用輸出時間軸偏移:output_time = word.start - segment_start + segment_offset。否則字幕在分段拼接後會錯位。
  6. 絕不在詞語中間剪輯。 每個剪輯邊緣都必須對齊 Scribe 轉錄中的詞邊界。
  7. 為每個剪輯邊緣添加填補(padding)。 工作區間:30–200ms。Scribe 時間戳有 50–100ms 的漂移——填補能吸收此漂移。快節奏影片用較小值,電影感影片用較大值。
  8. 僅使用詞級逐字 ASR。 絕不使用 SRT/短語模式(會遺失亞秒級間隙數據)。絕不使用標準化填充詞(會遺失編輯信號)。
  9. 按來源快取轉錄。 除非來源檔案本身變更,否則絕不重新轉錄。
  10. 多個動畫使用並行子代理。 絕不順序執行。透過 Agent 工具一次產生 N 個;總耗時 ≈ 最慢的那個。
  11. 執行前須確認策略。 在使用者批准白話文計劃前,絕不觸碰剪輯。
  12. 所有 session 輸出位於 <videos_dir>/edit/。 絕不寫入 video-use/ 專案目錄內。

本文檔中其他一切均為實際範例。當素材需要時,可以偏離。

目錄結構

技能本體位於 video-use/。使用者素材放在他們指定的任何位置。所有 session 輸出都放入 <videos_dir>/edit/。

<videos_dir>/
├── <來源檔案,保持原樣>
└── edit/
    ├── project.md               ← session 記憶;每次 session 都追加
    ├── takes_packed.md          ← 短語級轉錄,LLM 的主要閱讀視圖
    ├── edl.json                 ← 剪輯決策
    ├── transcripts/<name>.json  ← 快取的原始 Scribe JSON
    ├── animations/slot_<id>/    ← 每個動畫的來源 + 渲染 + 推理過程
    ├── clips_graded/            ← 已調色並含淡出的分段提取
    ├── master.srt               ← 輸出時間軸字幕
    ├── downloads/               ← yt-dlp 輸出
    ├── verify/                  ← 偵錯幀 / 時間軸 PNG
    ├── preview.mp4
    └── final.mp4

設定

首次安裝說明在 install.md 中(克隆、依賴、ffmpeg、技能註冊、API 金鑰)。不要在每次 session 都重新執行;冷啟動時只需驗證:

  • ELEVENLABS_API_KEY 可解析——存在於環境變數或 video-use 儲存庫根目錄的 .env 檔案中。如果遺失,要求使用者貼上一個並寫入 .env(絕不寫入使用者的 <videos_dir>)。
  • ffmpeg + ffprobe 在 PATH 中。
  • Python 依賴已安裝(在儲存庫內執行 uv sync 或 pip install -e .)。
  • 如果 session 需要 HyperFrames 或 Remotion 插槽,需有 Node.js + npm。HyperFrames 目前需要 Node.js 22+。
  • yt-dlp、HyperFrames、Remotion、Manim 僅在首次使用時安裝。
  • 首次使用的動畫設定在插槽目錄內進行,絕不在 video-use 儲存庫根目錄。HyperFrames 可用 npx --yes hyperframes ... 調用;Remotion 可用 npx create-video@latest 搭建,或作為專案本地依賴安裝後再使用其 remotion render 指令。
  • 此技能附帶 skills/manim-video/。建立 Manim 插槽時,請閱讀其 SKILL.md。

輔助腳本(helpers/transcribe.py、helpers/render.py 等)與此 SKILL.md 位於同一目錄。解析它們的路徑時,請相對於包含此文件的目錄——該技能通常被符號連結至 ~/.claude/skills/video-use/ 或 ~/.codex/skills/video-use/。

輔助工具

  • transcribe.py <video> — 單檔案 Scribe 調用。可選參數 --num-speakers N。結果會被快取。
  • transcribe_batch.py <videos_dir> — 4 工作執行緒並行轉錄。適用於多個拍攝片段。
  • pack_transcripts.py --edit-dir <dir> — 將 transcripts/*.json 轉換為 takes_packed.md(短語級,在靜音 ≥ 0.5s 處斷句)。
  • timeline_view.py <video> <start> <end> — 輸出包含膠片條與波形圖的 PNG。按需的視覺深入查看工具。非掃描工具——僅在決策點使用,而非持續使用。
  • render.py <edl.json> -o <out> — 分段提取 → 拼接 → 覆蓋層(PTS 位移)→ 字幕(最後)。使用 --preview 進行 720p 快速渲染。使用 --build-subtitles 即時生成 master.srt。
  • grade.py <in> -o <out> — ffmpeg 濾鏡鏈調色。內建預設 + 使用 --filter '<原始 ffmpeg>' 來自訂。

對於動畫,使用 Bash 建立 <edit>/animations/slot_<id>/,並透過 Agent 工具產生子代理。

工作流程

  1. 盤點。 對每個來源執行 ffprobe。對目錄執行 transcribe_batch.py。執行 pack_transcripts.py 產生 takes_packed.md。取一兩個 timeline_view 樣本以獲得視覺上的第一印象。

  2. 問題預掃。 快速瀏覽 takes_packed.md,記錄口誤、明顯的用詞不當或應避免的措辭。形成簡潔列表,供編輯簡報使用。

  3. 對話。 以白話文描述你所看到的。根據素材內容提出問題。收集:內容類型、目標長度/比例、美學/品牌方向、節奏感、必須保留的時刻、必須剪除的時刻、動畫與調色偏好、字幕需求。不要使用固定的檢查清單——每次的正確問題都不同。

  4. 提出策略。 4–8 句話:結構、拍攝片段選擇、剪輯方向、動畫計劃、調色方向、字幕風格、預估長度。等待確認。

  5. 執行。 透過編輯子代理簡報產生 edl.json。在模稜兩可的時刻使用 timeline_view 深入查看。在並行子代理中建構動畫。對每個分段應用調色。透過 render.py 合成。

  6. 預覽。 執行 render.py --preview。

  7. 自我評估(在展示給使用者之前)。 在渲染輸出(而非來源)的每個剪輯邊界(±1.5s 視窗)上執行 timeline_view。檢查每個影像:

    • 剪輯處是否有視覺不連續 / 閃爍 / 跳動
    • 邊界處是否有波形尖峰(音訊爆音,可能逃過 30ms 淡出)
    • 字幕是否被覆蓋層遮擋(違反規則 1)
    • 覆蓋層是否錯位或顯示錯誤的幀(違反規則 4)

    同時抽樣:前 2 秒、後 2 秒、以及 2–3 個中段——檢查調色一致性、字幕可讀性、整體連貫性。對輸出執行 ffprobe 以確認時長符合 EDL 預期。

    如果任何項目失敗:修正 → 重新渲染 → 重新評估。自我評估最多 3 輪——如果 3 輪後仍有問題,將其標記給使用者,而非無限循環。只有當自我評估通過後,才能呈現預覽。

  8. 疊代 + 持久化。 自然語言反饋、重新規劃、重新渲染。絕不重新轉錄。確認後進行最終渲染。將過程追加到 project.md。

剪輯工藝(技術)

  • 音訊優先。 候選剪輯點來自詞邊界與靜音間隙。
  • 保留高潮。 笑聲、妙語、強調節拍。將剪輯點延伸到妙語之後以包含反應——笑聲本身就是節拍。
  • 演講者交接 需要在話語之間有空氣。常用值:400–600ms。快節奏用較小值,電影感用較大值。品味判斷。
  • 音訊事件作為信號。 (笑聲)、(嘆氣)、(掌聲) 標記節拍。將剪輯點延伸到它們之後。
  • 靜音間隙是剪輯候選點。 ≥400ms 的靜音通常是最乾淨的。150–400ms 的短語邊界在視覺檢查後可以使用。<150ms 不安全(短語中間)。
  • 範例剪輯填補(本技能隨附的啟動影片):第一個保留詞前 50ms,最後一個保留詞後 80ms。節奏緊湊的蒙太奇用較小值,紀錄片用較大值。保持在 30–200ms 的工作區間內(硬性規則 7)。
  • 絕不獨立地處理音訊與視覺素材。 每個剪輯都必須在兩個軌道上都成立。

已打包的轉錄(主要閱讀視圖)

pack_transcripts.py 讀取所有 transcripts/*.json,產生一個 markdown 檔案,其中每個拍攝片段是一個短語級行列表,每行以其 [起始-結束] 時間範圍為前綴。短語在任何靜音 ≥ 0.5s 或說話者變更處斷開。這是編輯子代理閱讀以選擇剪輯的工件——它僅從文字提供詞邊界精度,而 Token 數僅為原始 JSON 的十分之一。

範例行:

## C0103  (時長:43.0s,8 個短語)
  [002.52-005.36] S0 一個網頁代理所做的百分之九十都是完全浪費的。
  [006.08-006.74] S0 我們修正了這個問題。

編輯子代理簡報(用於多個拍攝片段的選擇)

當任務是「從多個片段中選出每個節拍的最佳拍攝片段」時,產生一個專門的子代理,其簡報類似如下。結構是重要的;音高形狀的範例則非必要。

你正在編輯一部<類型>影片。選出每個節拍的最佳拍攝片段,
並按節拍的邏輯順序(而非來源剪輯順序)組裝。

輸入:
  - takes_packed.md(所有拍攝片段附時間戳的短語級轉錄)
  - 產品/敘事背景:<使用者提供的 2 句話>
  - 演講者:<姓名、角色、表達風格備註>
  - 預期結構:<選擇一個架構原型或自行創造>
  - 應避免的口誤:<從預掃階段得出的列表>
  - 目標時長:<秒數>

常見結構原型(選擇、調整或創造):
  - 技術發表 / 展示:  鉤子 → 問題 → 解決方案 → 益處 → 範例 → 行動呼籲
  - 教學:             簡介 → 設定 → 步驟 → 陷阱 → 回顧
  - 訪談:             (問題 → 回答 → 追問)重複
  - 旅遊 / 活動:      抵達 → 亮點 → 寧靜時刻 → 離開
  - 紀錄片:           論點 → 證據 → 反論 → 結論
  - 音樂 / 表演:      前奏 → 主歌 → 副歌 → 橋段 → 尾奏
  - 或自行創造。

規則:
  - 開始/結束時間必須落在轉錄中的詞邊界上。
  - 為剪輯邊界添加填補(工作區間 30–200ms)。
  - 偏好 ≥ 400ms 的靜音作為剪輯目標。
  - 如果沒有更好的拍攝片段,則保留無可避免的口誤。在「原因」中註明。
  - 如果超出預算,則修訂:刪除一個節拍或修剪結尾。回報總時長並自我修正。

輸出(JSON 陣列,無散文):
  [{

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

govindgoel2001/video-editing-toolkit

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

govindgoel2001/video-editing-toolkit

HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.

govindgoel2001/video-editing-toolkit

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

govindgoel2001/video-editing-toolkit

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.

govindgoel2001/video-editing-toolkit

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

govindgoel2001/video-editing-toolkit

Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content.

相關技能