josenjc9/短影音剪輯

短影音剪輯 skill

給 AI agent 用的剪輯作業手冊。目標是做出「專業級」而不是「能看」的成片。

一個核心判斷：成品好不好，九成在開工前（事實、風格、分鏡有沒有定），一成在渲染。所以前期沒過關，不渲染整支。

本 skill 內含的工具在 tools/（路徑以下寫 <skill>/tools/，指這個資料夾）。需要的軟體：ffmpeg、python3；ocr_check.py 需要 macOS 與 swiftc；hf_lint.py 只在用 HyperFrames 做字卡時才需要。工具用法見 tools/README.md。

角色與規矩

• 「使用者」是決定者。每個關卡要使用者明確點頭才算過（引用他的原話，不憑推測）。
• 事實與文案只用使用者給的。想改或想加，列 A／B／C 選項給他選，不自己加小字、標語、情節。
• 不確定就問，不猜。沒驗證的事不要講成事實。
• 需求中途變了＝退回對應那一關重做，不在作業中偷改。
• 使用者連發好幾則短訊息時，先回「收到，等你講完」，講完再動。

開工路由（先判斷是哪一類，再讀對應的節）

一支片可以同時屬於多類，每類都讀。

任務像這樣	讀哪裡
「電影感」「預告片」「混剪」，多支素材剪成有情緒的一支	references/情境_預告片混剪.md＋ references/剪輯語法與敘事.md、跨鏡頭連續性.md、聲畫節奏與調色.md、退件與驗收格式.md
真人講話為主，要剪內容、上字幕	references/情境_口播演講片.md
主角是畫出來的角色，要互動	references/情境_角色動畫片.md
手上是靜態圖卡／資訊圖，要做成影片	references/情境_圖卡轉動態影片.md
畫中畫、分割畫面、蒙太奇、定格、變速、倒放、Ken Burns 等剪輯技法	references/技法庫.md（附已跑過的 ffmpeg 指令，標明實測或常見做法）
轉場：該不該用、選哪類、ffmpeg xfade 怎麼做	references/轉場指南.md
字卡動畫、數字圖表、轉場特效、特效層、3D／Three.js	references/動態圖形與3D.md（動態圖形手感與數字、轉場配方、動畫引擎怎麼選、3D 何時值得用）
「第 N 年」逐年滾動、時間流逝蒙太奇	references/情境_時間流逝蒙太奇.md
想不到怎麼做：要選剪輯技法、動畫、工具	references/技法與工具目錄.md（每項標明實測或常見做法）
製程類（料理、組裝、施工等一步步完成）	前期關卡 1 的「製程類先問三件事」
有寵物、家人、真實經歷	「工具與禁忌」：真實經歷不放生成畫面

流程總覽

0. 確認目標：一句話目標、對象與用途、平台與規格（比例、秒數、解析度）、素材清單、可驗的成功判準、不做什麼。
1. 腳本：創作類先給三條不同故事線的文字大綱讓使用者三選一。定稿＝分段、秒數、字幕、音效方向。
2. 分鏡初稿：鏡頭表＋分鏡板，技法欄位先留空。形容詞換成數字（「歡樂」→彈跳幅度、動作節拍）。
3. 盤點工作與風險測試：素材盤點（接觸表）；每鏡要用的技法對照「已驗證能力」；沒做過的先做 5 秒測試，不行就換簡化備選；風格包（關卡 2）在這關鎖定。過關＝使用者鎖定分鏡。
4. 粗略動態版：把分鏡板按時間和音效排成粗版，先確認節奏與長度，才進作業。
5. 作業：製作、後製。
6. 自查：渲染前掃地雷 → 渲染 → 機檢 → 大片檢查表，圖逐張看。
7. 交付與結案。

階段一：前期（三關都要使用者點頭）

關卡 1｜事實與文案（問一次，答案存進鏡頭表 meta）

• 稱呼、聲音規則（預設：不要配樂、只要音效；原聲留哪些）、比例、秒數、解析度、片名。
• 素材先做接觸表（tools/storyboard.py）看內容，不憑檔名；聲音先查頻譜或實聽。
• 知識／教學類內容，先查驗再動手：把每句定義拿去查官方來源（官方文件優先，第三方整理只當輔證），在鏡頭表旁記「這句對得上哪個來源」，查不到的標「未查證」。拿掉原稿任何一塊內容前，先判斷那塊是不是在防誤會；你自己做的簡化要講清楚「這是我的簡化，不是原稿說法」。只讀到搜尋摘要沒讀全文，要直說。
• 製程類先問三件事：①製程順序；②哪支素材屬於哪個成品、哪一步（不憑拍攝順序猜）；③一定要出現的關鍵瞬間。
• 說「素材裡沒有／拍不到」之前，整支逐格看完，不是只看動作那幾格。使用者傳截圖時，用 tools/find_frame.py 找出是哪支素材第幾秒。
• 挑片依據：素材有拍攝者口頭評語時，轉文字後當加分依據；沒有就用明確退件條件（模糊、晃動、太暗），退件要寫是哪一條、對應哪個鏡頭。這兩招只是輔助，沒保證有效。

關卡 2｜風格包（一頁，先給使用者看）

• 1～2 支參考片或參考畫面，加一句「要像它哪一點」。分析參考片時要明講維度，沒講 AI 可能只看色彩。可選：片型、字體、色彩、字卡、元素、模組（字卡進出方式、疊卡、浮標這類可重複用的組件）、免費素材（用到哪些免費素材，授權要查）、動態、節奏、轉場。
• 色彩：背景／文字／一個強調色（強調色佔畫面 ≤15%，文字對比 ≥4.5:1）；有劇情的片另寫色彩弧線（每段目標亮度）。
• 字型與字卡語言：最多兩套。
• 轉場語彙：全片 ≤3 種；特效每鏡一個主效果。
• 交一張風格示意圖（關鍵一格畫面），不是只有文字。
• 技法選型：開工先查有哪些技法能讓剪輯更精美，不設數量上限，但每個都要說得出「用在哪一鏡、為什麼合」。給使用者的清單一律用白話名稱加一句效果（例如「推進鏡頭：慢慢靠近主角」），不寫英文代號。交片時對照一次：用到的技法對得回這份清單嗎。
• 口播／社群解說片常見包裝手法：蒙版調色（只調背景）、背景換影片牆、超大字放人物後面、前後對比拉桿、打字輸入框加進度條、定格加變速、關鍵詞浮動標籤、畫中畫、數字跳動、剪氣口。沒實測過的別向使用者保證做得到，先做 5 秒測試。

關卡 3｜鏡頭表＋分鏡板

• 每鏡寫：action（畫面上實際發生的事）、shot_size（遠／中／近／特）、字幕、字卡、音效（只存相對秒數）。字卡要寫 evidence（畫面上哪裡支撐它）。
• 每個切點寫 cut_reason（為什麼在這切、為什麼接這一鏡）；用 match cut 或 cut on action 的另寫 anchor（上一鏡結尾抓什麼、下一鏡開頭接什麼）。寫不出理由的切點先刪。
• 字幕：每秒 4～5 字，上限 6；出現時間不早於該鏡切入；字幕長度決定鏡頭長度；每句字幕都要有畫面支撐，沒有就向使用者要素材。
• 排鏡要有故事線＋景別切換：先定主角與起承轉合（只把同類動作排一起不叫敘事）；每段刻意切換景別，常用「中→近→遠」或「遠→中→特」。
• 製程片的進度一致：大段落照實際製程順序；同一段裡多個成品要同步推進；已完成的成品不能插在還在做的段落中間；成品只出現在最後的定裝段（開場預敘例外）。要「不見手」就用 crop 裁特寫，只套在使用者點名的那一鏡。
• 使用者說「要有靈魂／氛圍」＝要調色：全片統一一套。
• 分鏡板用 tools/storyboard.py 從素材或成片抽格拼圖，機檢只核字面，字卡和畫面是不是同一件事要人看圖。

交鏡頭表給使用者前，自己先逐條打勾，缺一條不交：

1. 情緒問過了嗎（激勵／溫情／懸疑）；要不要配樂問過了嗎。
2. 字卡：先給 3 種 5 秒比較片（三種是不同「玩法」，不是同一種換字體）。先寫每張字卡的功能，再從 references/剪輯語法與敘事.md 的「字卡玩法菜單」挑；使用者選一種為主，整支依段落混用，字體全片一套。
3. 技法：真的去查了，清單用白話名稱，每個說得出用在哪一鏡。
4. 聲音：用真實錄製的音效，不用程式合成；每個音效對應一個畫面動作。庫裡沒有就去免費音效網站找，自行確認授權，檔名寫清楚來源並記進音效夾的 README。找不到完全對應的，找最接近的並說明。
5. 素材看完（含照片），挑片排除條件寫明；日期照拍攝時間查，不憑檔名。
6. 事實與文案只用使用者給的；你想的字卡只列選項，不自己放。
7. 風格示意圖（關鍵三格畫面）一起交；封面格另存、不加總長。
8. 使用者的簡短回覆（「A」「可以」「都行」）有兩種讀法就先確認。
9. 每個切點有 cut_reason。
10. 有配樂的片：混音前寫一張 Sound Map（層、起訖、優先權、來源）。
11. 情緒類字卡先問「能不能用鏡頭取代」：每張「替觀眾下情緒結論」的字卡（好笑、感動、尷尬、震驚），旁邊標註能否用「人物看→反應」或「A 鏡接 B 鏡」取代；能就寫替代鏡頭，素材缺或趕件才保留字卡。資訊類字卡（數字、年份、人名、地點）不受影響。這個手法的效果在學界仍有爭議，只當可 A/B 的選項，不當必成公式。真實紀錄素材不可把不同時間的反應剪成「當下反應」去製造沒發生的情緒。

階段二：製作

• 畫面：先做低畫質草稿，定了再出正式畫質；改一鏡只重做那一鏡。ffmpeg 處理 HLG／HDR 素材要先轉 SDR；每鏡量亮度（signalstats），對到色彩弧線目標。
• 真實畫面高清：網站／App 畫面用瀏覽器自動化以 3 倍解析度錄；4K 輸出要設 devicePixelRatio。素材本身解析度不夠，開工就跟使用者講上限。錄自己的 demo 站別連續快速開，會被自己的限流規則擋到錄出錯誤頁。
• 特效先查素材庫再手刻：查完沒有才手刻，並記下缺口。電影感常用：推進／拉出揭示／焦點轉移、甩鏡轉場、漏光、底片顆粒、暗角、柔焦進場字卡。醫療或溫情場景不用晃動、甩鏡、斜衝、焦距衝擊。
• 字卡（HyperFrames 或同類 HTML 動畫）：時間軸寫進 window.__timelines；fromTo 與後續 from 加 immediateRender:false；逐格填滿的元件先 set opacity 0；字幕全片同一高度；不擋主體；換鏡時上一鏡元素全部清掉。渲染前用 tools/hf_lint.py 掃地雷。
• 中文字卡排版（以 1920 寬為準）：主標 900 字重、≥120px、字距 0.01～0.03em、一行 ≤14 字、手動斷在詞間、行首不放單字或標點；內文 500～700 字重、≥32px；中英數之間半形空格；遮罩內文字行高 ≥1.18。字卡最短停留＝字數×0.18 秒＋0.6 秒。疊在畫面上的標籤用實心底加深色粗字，放空白處。
• 節奏：開場 0.3 秒內要有東西在動、第一句字 1.5 秒內出現；下一個動作在上一個結束前 0.1～0.3 秒開始；同時只讓一個主角動；退場約入場一半長。
• 自己改生成腳本後，確認檔尾沒被截斷再跑。

人物去背與蒙版

• 邊緣驗收＝放大看手指、頭髮、肩膀三處，不能只看縮圖。遮罩處理：先模糊約 1.6、再拉對比、縮 2px，邊緣才平滑沒白邊。
• 去背段落旁邊不能有疊在人旁邊的卡片、燒死的字幕（原片字幕壓在人身上會被當成「不是人」變透明）。
• 沒測過的別保證：指尖仍可能有幾像素的色邊，要直說。

實作踩坑（GSAP 與 ffmpeg）

• 總長要是整數幀（秒數×fps 為整數），否則自查幀數差 1。
• 原聲落點從計時檔算，不准寫死秒數（改鏡長後會對不上嘴）。
• 主體是黑色時別用 zoomin 轉場（會放大到全黑），改 smoothleft 或 fade。橫式照片放直式片，先裁成直式保住臉，不用模糊填底。
• GSAP 會讓畫面「出現→消失→再出現」或整支卡死的三個坑：①tl.set(群組子元素,{opacity:1},0) 放在後面 tl.from(...) 之前，會蓋掉 from 的隱藏起點；要隱藏就 tl.set(全部,{opacity:0},0)，再用 to／from 顯示。②選擇器一次選到兩個元素，被提早動畫；只動要動的那個，或用 id。③新場景的變數名與別場景撞名，會讓 onUpdate 丟錯、影片從那一鏡起凍結。新增變數前先 grep 全檔同名；改完用實際渲染的影格逐鏡抽驗，每鏡換鏡前後各抽一格。
• 後製調色不要用 colorbalance 的亮部（白底畫面會整片偏黃）；暗角用 vignette=angle=PI/8。純白網頁調完要量一次白點。
• 配音：使用者明說要才做（預設只要音效）。每句 silenceremove，必要時 atempo（≤1.2）後，用 Python 陣列依時間碼疊進同長度的 wav；ffmpeg 一次 amix 很多個 adelay 輸出會被截短。混音前確認音效檔長度＝成片長度。字幕有改，語音要同步重生成。
• 使用者嫌「太吵」只刪他點名的聲音；刪之前列出「拿掉哪些」讓他知道，原聲這類情感點寧可留一個。
• 片子做完後使用者可能中途插鏡：只改鏡頭表（加鏡、延長字幕、移動音效位置），重跑檢查、組鏡、渲染、混音，後面的起點與落點自動順移。插入照片鏡要先看構圖，字幕別壓在高飽和主體上。

階段三：後製

• 調色照色彩弧線，全片同一個 look 系統，不一鏡一種濾鏡。
• 電影感調色預設要做：S 型曲線、黑位微抬（霧面）、暗角、底片顆粒放在全片最後一層。暗部偏青、亮部偏暖的分離色調只上在彩色 look，黑白段另給微冷，否則黑白會被染成黃綠舊照片色。
• 音效預設從少開始，每種聲音都對應畫面上的一個動作，交片前問自己「拿掉這個聲音會少什麼」。情境不合的拿掉；loudnorm 加 alimiter 不爆音。
• alimiter 一定加 level=disabled（預設的自動增益會把峰值推回接近 0dB）；同一步加 atrim 到片長，輸出加 -shortest，不然聲軌比畫面長、幀數檢查會失敗。收尾 loudnorm=I=-16:TP=-1.5。
• 變速鏡頭的聲音不要跟著 atempo 拉伸（會有奇怪的變音）：慢動作／快轉那鏡用原速聲音，畫面與聲音分兩個輸入取。
• 聲音最後一定請使用者戴耳機聽；量測與語音辨識只能當輔助。低頻（150Hz 以下）在筆電手機播不出來，音效要有 300Hz 以上能量。
• 輕量版 ≤9MB：-maxrate 壓不下去時改 x264 兩段式編碼。

去人聲／保留環境聲

• 不要用語音辨識找時段再靜音（人聲常被標成非語音而漏抓，時間也只到整秒）；改用音源分離工具（例如 demucs）取不含人聲的聲軌，一遍就夠。分離後再用語音辨識掃一次當複查：括號內容是非語音，不算殘留；整段重複同一句或「記得訂閱」這類是辨識幻覺。
• 分離工具會把噴槍轟聲、部分刀聲當人聲拿走：關鍵音效那幾秒把人聲分軌加回來，但挖掉 250–3800Hz 人聲頻段。

輔助工具：找切點、剪氣口、抓拍點

三項都用合成素材做過功能驗證（結果附在後面）；用真素材時門檻與效果仍要依素材調整。

• PySceneDetect：scenedetect -i 影片.mp4 detect-adaptive list-scenes，列鏡頭時間表。驗證：三段不同內容硬切接成的 6 秒影片，偵測到 3 個鏡頭，切點在 2.0 與 4.0 秒，與實際一致。動畫素材偵測出的「鏡頭」不一定是你想要的鏡頭。
• Auto-Editor：auto-editor 影片.mp4 --edit audio:threshold=5% --margin 0.15sec -o 輸出.mp4，剪口播的空白氣口。驗證：三段 1 秒聲音夾 1 秒靜音的 6 秒影片，剪成約 3.85 秒。門檻要依素材試：同一支合成素材用 15% 會把整段判成靜音、剪到空；剪完字幕、嘴型、音畫同步要重核，字幕時間要從剪後版重做。氣口剪掉不等於可以把贅字一起剪掉，字幕不准比講的少字。請用官方發行版（例如 Homebrew），不要用名稱相近的空殼套件。
• librosa：librosa.beat.beat_track 取拍點與 BPM。驗證：120 BPM 的合成鼓點，測得約 117.5 BPM、23 個拍點，誤差在 2% 內；拍點交片前仍請使用者聽。只在使用者要踩拍的片才用，悠閒的片不跟節拍。

階段四：交片前自查（每條要有證據才算過）

先跑機檢：tools/qa_video.py 成片.mp4 輸出夾 --size WxH --fps N --share 分享版.mp4（檢查解析度、fps、整數幀、聲軌長度、爆音、響度、黑畫面、凍結、換鏡前後格、分享版大小）。數字是工具核的，圖你要逐張看。逐條勾：

0. 乾淨度（每次交片都做）：每鏡抽第一格、中間格、最後一格拼成一張圖逐張看。手或影子晃進來、沒交代的動作、整鏡什麼都沒發生、快轉後影子閃爍，一律縮短或換段。
1. 切點連續性（多鏡有情緒的片必做）：tools/cuts_sheet.py 抽每個切點前後各 2 格，逐張看方向、視線、動作相位、景別、光線。問題照 references/退件與驗收格式.md 寫成帶圖路徑的 issue。自己修最多 2 輪，仍不過給使用者裁決。
2. 規格：解析度、幀數、比例與使用者要的一致；成片從 4K 或更高縮下來。
3. 文案：畫面上每個字都是使用者給的。有原稿可比對時，用 tools/ocr_check.py 把成片關鍵影格和原稿都轉成文字逐句比，沒對上的回頭看原文（辨識誤差不等於畫面錯）。文字對得上不等於內容正確，內容另查來源。
4. 字卡＝畫面：每張字卡的名稱對得上該鏡實際發生的事。選段落與裁切時就要看那一段的實際影格，不是看自己寫的描述。
5. 字幕：每秒字數合格、沒提前到上一鏡、全片同高、沒自動換行。
6. 可讀性：所有字在分享版（壓縮後）上仍清楚。
7. 乾淨：換鏡無殘留元素、無疊影、沒錄到錯誤頁或測試資料。
8. 一致：轉場 ≤3 種、色彩照弧線、字卡語言 ≤2 套。
9. 節奏：開場 0.3 秒內有動、沒有同時兩個主角在動、字卡停留時間夠。
10. 聲音：無爆音、每個音效都有對應動作、沒有不合情境的音效。
11. 可重現：同一時間點渲染兩次，截圖雜湊相同（程式動畫要寫成時間的純函數）。
12. 誠實：畫質救不回的鏡頭、沒驗到的項目，交付時直說。

階段五：交付與結案

交付資料夾（自己定位置，以下是建議結構），一支片一個資料夾，先日期再名稱（YYYYMMDD_片名）：

• 成品/：高畫質版、輕量版（傳聊天軟體用，≤9MB）、封面、字幕檔。
• 初剪/：過程版本與輸入素材。
• 定稿圖表/：風格包、分鏡板、鏡頭表（機器可讀的檔加一份人看的 .md）、原始碼/（重做用的腳本加 README）。
• 測試類的東西（新工具、5 秒樣張）放另一個 測試/日期_名稱/，正式要出的才進專案夾。
• 用 tools/deliver.sh 合音效、壓輕量版、複製、核 md5；同名檔不覆蓋。
• 成品改版後，定稿圖表要一起更新：分鏡板、鏡頭表的秒數與起點都要跟成品一致，否則留下講舊版的文件。

只留定稿：中間產物放專案 .work/。清理時用 tools/safe_trash.sh 移垃圾桶，不直接刪，先列清單給使用者確認。別人的作業區不碰。

結案必做五件（每支片都做）

1. 定稿：先核封面。片頭要有封面格（標題加主角），另存封面圖；封面不加總長，從開頭素材扣回。封面文案從片中的結論字卡推，不從檔名或過程段落推。成品改正式檔名 <片名>_<秒數>.mp4，輕量版 ≤9MB。定稿圖表/ 的分鏡板與鏡頭表要照成品重做。md5 核對。
2. 清理：被取代的舊分鏡、舊腳本、各版初剪、工作目錄，全部 safe_trash.sh 移垃圾桶；README 寫明垃圾桶裡的名稱，重做時去拿。
3. 關單：為這支片開的待辦或任務全部標結案。
4. 覆盤：每一版使用者改了什麼（引原話）、根因、下次怎麼擋；自己的失誤另列；可重用的做法；沒驗證的推論標「未驗證」。
5. 優化這份 skill：覆盤裡「下次怎麼擋」能變成規則的，寫回這份 SKILL.md 對應的段落，不要只堆在檔尾。

工具與禁忌

• 真實素材優先（ffmpeg 加 HTML 動畫）。沒拍到的畫面：靜態圖像生成（不要生成中文字，中文字用 HTML 疊）→ 其他外部素材。真實經歷（寵物、家人、客戶案例）不放生成畫面。
• 裝任何新的工具、套件、模型之前，先查來源與授權，問過使用者再裝，不要邊做邊裝。
• 不執行會把自由文字外送的指令（例如工具的 feedback 指令）；工具的統計回報預設關掉。
• 不要把未經確認的內容、使用者的私人素材與個人資料寫進公開的樣張或範例。