病毒式影片編輯

一套完整的方法，用於製作節拍完美、特效整合的垂直音樂影片，使其達到 S 級攝影水平。本技能源自一個實際運作的生產系統（一位獨立音樂人的短片宣傳活動）及其累積的客戶回饋。唯一的成功指標是表現（留存率 + 分享數），以下的每一條規則之所以存在，都是因為其違反行為在實戰中被觀察到會導致失敗。

法則（不可協商；每一條都是從慘痛經驗中學到的）

僅限整合式特效。 特效必須融合到鏡頭中——錨定於主體的遮罩、場景幾何結構或鏡頭本身的像素。絕不剪接到獨立的特效片段；絕不交替使用全幀特效與全幀素材；未經追蹤的合成元素看起來就像貼紙。在添加任何特效之前，請先閱讀 references/integrated-fx.md。
好看比遵循參數更重要。 如果要求的素材或結構會影響品質，請改變結構並明確說明。即使有共同的主題，大量不匹配的片段在節拍邊界處拼接起來也只會顯得混亂。
豐富，而非克制——也絕不廉價。 工作風格是豐富的濃郁調色（純黑、對比 S 曲線、明確的調色盤）+ 在節拍網格上每個鏡頭進行一次扎實的現實扭曲。純粹的克制看起來平淡無趣；每個鏡頭隨機做一次效果則顯得混亂。每段剪輯使用一種特效語言，並隨歌曲結構升級。
根據歌曲提供的內容進行剪輯。 基於 onset 鎖定的剪輯：在每個真實 onset 處進行剪輯（合併低於 0.13 秒的 onset，保留較強者），稀疏時保持靜止，密集時爆發——絕不進行脫離網格的填充式剪輯，也絕不使用覆蓋歌曲的密度預設。對於以分享為主的影片，則採取相反極端：一個連續鏡頭，零剪輯，由歌曲的包絡線驅動光度變換。
透過建構達成同步。 所有特效渲染都必須針對與編輯完全相同的時間視窗（--start/--dur）和剪輯列表生成。將估算的節拍對齊到真實檢測到的 onset（≤60ms）。風格切換必須落在包含瞬變的影格上（取 floor，而非 round）。
近黑 + 發光 適用於所有程式化圖像。色彩柔和的色調每次都失敗；光必須從黑暗中雕刻出來。
鉤子必須通過 5 測試關卡（瞄一眼/說出口/記名字/留懸念/引點擊，≥4/5 通過）。不寫詩，不用「沒有人：」，不用互動誘餌指令。請參閱 references/hooks-and-text.md。
鏡頭級別的素材把關。 在搜尋素材前先確定氛圍規格；優先使用最高層級的來源；對每個鏡頭進行品質把關 + 人工檢視連環快照；只有通過的鏡頭才能進入編輯。每個檔案都需要驗證授權。請參閱 references/footage-sourcing.md。
自動化 QA 永遠無法取代人工觀看。 每個交付成品都必須獲得檢測報告，並且有人眼檢查連環快照、以正常速度和手機比例觀看完整渲染。請參閱 references/delivery-qa.md。
在穩定的基礎設施上以編號版本進行迭代。 僅在版本之間更改特效語言；當客戶喜歡一個 2 秒的時刻，就在下一個版本中將該時刻作為整個特效語言。

標準格式

1080×1920 @ 30fps 垂直影片，libx264 yuv420p +faststart，aac 192k，CRF 17（影格管線最終版）/ 18–19（片段最終版）。循環無縫結尾。檔案命名版本化，置於 outputs/<project>/ 目錄下。每個編輯成品都附帶連環快照 + 時間軸檔案 + QA 報告。

工作流程

對於任何非平凡的工作，先寫下計劃（設計文檔/逐鏡頭列表——references/design-docs.md），對於新的活動，先進行試點：V1 證明語法，獲得批准後再處理批次。

分析歌曲 → 節拍網格、每拍能量/剪輯優先級、段落、8 拍樂句。然後選擇時間視窗（15–30 秒），考慮因素包括：重複性（副歌感）、能量上升、循環接縫、歌詞位置、藝人過往作品。→ references/song-analysis.md
搜尋素材並把關 → 氛圍規格、分層來源、對每個鏡頭進行品質把關並生成鏡頭對應表、當概念需要特定內容時進行語義契約檢查。→ references/footage-sourcing.md
撰寫鉤子組合 → 5 測試關卡、第二行下降動態（第 1 行在影格 0，第 2 行在 0.8–1.3 秒 ±100ms 處節拍融合）、在溫馨有趣與安靜具體之間進行 A/B 組合。→ references/hooks-and-text.md
建構剪輯 → 選擇時鐘（音樂小節用 beats CSV；瞬變剪輯用 onset 網格），以節拍為單位撰寫鏡頭規劃，確保結構錨點（下降點在其小節 ±0.02s）。架構：片段→拼接→後期圖形（僅限 ffmpeg）用於剪輯驅動的編輯；影格管線 numpy 用於逐像素特效；著色器內融合用於最深層的整合。→ references/integrated-fx.md
整合特效 → 人物遮罩（Apple Vision，經過品質把關）、基於遮罩/場景/像素的效果、經過驗證的 base.mp4→mattes→effects-table 管道；在相同時間視窗渲染的程式化元素，透過場景幾何結構進入。→ references/integrated-fx.md，references/procedural-renderers.md
調色與工藝層 → 精確的電影配方（光暈、ACES、分裂色調、顆粒、暗角、信箱效果）、遮罩中心推近、升級主幹、循環接縫。→ references/cinematic-grade.md
QA 與交付 → 儘早對前 3-5 秒進行廉價測試；檢測 + 連環快照 + 觀看；連貫性檢查（任何貼紙感或剪出鏡頭 = 修訂）；使用清單和圖庫打包變體；將發文記錄到實驗循環中。→ references/delivery-qa.md

選擇賽道

需求	賽道
情感/抒情歌曲，以分享為重	一個連續鏡頭 + 由歌曲包絡線驅動的光度變換（調色漸變、光線到來、輝光）；肯定身份鉤子
能量歌曲，以留存為重	基於 onset 鎖定的快速剪輯，來自大量經過把關的素材庫（60+ 個鏡頭），在頂四分位數的 onset 處加入突入強調
藝人入鏡展示	電影工藝層 + 每個鏡頭一個基於遮罩的簽名特效（風格閃爍、迴音分身、主體↔世界切換、節拍烙印多重影像）
抽象/視覺熱門	程式化 GLSL 渲染器（隧道/萬花筒/星爆），近黑 + 發光，onset→重擊低音→輝光能量→速度；當有主體時透過著色器內編織與素材融合
主打標題/品牌作品	先寫設計文檔；分階段動態時間軸；TDD 建構；對照參考資料進行比較視覺審計

參考資料（按需閱讀）

references/song-analysis.md — 分析公式、病毒視窗評分、onset 網格、節拍數學、包絡跟隨器。在開始分析新歌曲或除錯同步時閱讀。
references/integrated-fx.md — 核心工藝準則：錨定規則、失敗模式、遮罩管道、三種建構架構、合成陷阱（RGB 中的螢幕混合！）、主體特效詞彙表。在任何特效工作前閱讀。
references/procedural-renderers.md — moderngl 骨架、GLSL 內部庫、標準色彩完成、近黑法則、入口編織融合、TouchDesigner 賽道。在渲染程式化視覺時閱讀。
references/cinematic-grade.md — 精確的調色配方、鏡頭語言、升級主幹以及迭代案例研究（dreamcatcher v1→v5，with-u v4→v7，portal arc）。當編輯必須看起來像電影，或在迭代版本之前閱讀。
references/hooks-and-text.md — 5 測試關卡、容器格式、文字動態、競賽方法、實戰參考、最佳化循環。在撰寫任何影片文字或選擇創意方法時閱讀。
references/footage-sourcing.md — 氛圍規格、來源層級、確切把關門檻、授權、語義契約、遮罩配對契約。在搜尋或接收任何素材前閱讀。
references/delivery-qa.md — 編碼設定、交付成品、QA 流程、判決格式、發布套件。在宣告任何成果完成前閱讀。
references/design-docs.md — 點子表 → 列表 → 設計文檔 → 規劃模式。在規劃新的製作或活動時閱讀。

配套腳本（可執行，不僅是描述）

這些是核心引擎的實際實現——在從頭開始編寫新的之前，請優先使用它們。所有腳本都是純 CLI 工具；執行 --help 或閱讀每個檔案頂部的文檔字串。

scripts/choose_viral_window.py — 病毒視窗選擇 (song-analysis.md §2)。--audio song.wav [--transcript whisper.json] [--tiktok-start SEC] [--durations 15,22,30] --out DIR。
scripts/scan_shot_quality.py — 鏡頭品質把關 (footage-sourcing.md)。--root path/to/footage [--min-shot 1.2] [--jobs 3] → 寫入 shot_map.json。需要 opencv-python、scenedetect、pytesseract。
scripts/build_onset_cut.py — 基於 onset 鎖定的 v2 剪輯引擎 (song-analysis.md §3, integrated-fx.md 架構 A)。--config job.json [--shot-map shot_map.json]；請參閱文檔字串了解 job schema。
scripts/matte/generate_local_person_matte.swift — 透過 Apple Vision 進行逐影格人物遮罩 (integrated-fx.md)。使用 swiftc generate_local_person_matte.swift -O -framework AVFoundation -framework Vision -framework CoreImage -framework ImageIO -o mattegen 編譯（macOS 14+），然後執行 mattegen source.mp4 proposal_dir/。
scripts/matte/media_contract.py — 遮罩品質把關的實現（validate_matte_statistics、matte_statistics、probe_media、validate_sync）——將 integrated-fx.md 中的確切門檻值以程式碼形式呈現，而非僅是文字。
scripts/procedural/ — 10 個獨立的 moderngl/GLSL 渲染器（render_color_tunnel.py、render_glass_bloom.py、render_mandala.py、render_fractal_neon.py、render_shader_pack.py、render_neon_cathedral.py、render_dream_portal.py、render_hyper_space_jump.py、render_hyper_kaleido.py、render_portal_weave.py）加上 footage_fx.py（對真實素材的整幀特效）和 subject_fx.py（基於遮罩的主體特效取樣器）——請參閱 procedural-renderers.md。每個渲染器都接受 --audio --start --dur --out [--fps 30 --w 1080 --h 1920]；其中幾個還支援 --still 用於快速藝術方向檢查。需要 moderngl、librosa、numpy、Pillow。

歌曲分析腳本（script/analyze_song_for_editing.py，負責產生節拍/段落/能量資料）未包含在此處——請使用配套的 song-edit-analysis 技能（相同套件）中已捆綁的等效腳本，或根據 song-analysis.md §1 重新實現。

在主儲存庫中工作

如果此技能在其被提取出的原始生產工作區中執行，則優先使用該儲存庫自身擁有的這些腳本副本（它們可能累積了修復）及其批次/素材基礎設施（作業生成器、圖庫建構器、發文實驗循環），而非此處的捆綁版本。在其他地方——這是此公開技能的常見情況——捆綁的 scripts/ 目錄是完整的實現；參考文檔包含擴展或重新實現它們所需的所有關鍵常數。

viral-video-edits