影片工藝（Video Craft）
兩項任務，同一標準。剪輯他人錄製的素材，或製作從品牌工具包和文案產生的影片。無論哪種，工作都在渲染前先規劃、透過精確的腳本進行渲染，並在告知任何人完成前，先以測量結果進行檢查。
讓影片看起來專業的要素，依序為：
- 結構。 前 3 秒要有鉤子，一個想法，任何不值得花時間的東西都刪掉。
- 節奏。 剪切與移動落在人聲和節拍上；沒有死寂，沒有匆促。
- 工藝細節。 每個剪切周圍保留呼吸空間，字幕易讀，動畫減速到位，聲音夠大且從不爆音。
- 驗證。
qa.py通過，且聯絡表已檢視過。
快速路徑
| 需求 | 操作 |
|---|---|
| 「剪輯／清理這段錄音」 | 轉寫 → 規劃剪輯 → 檢視 EDL → 渲染 → QA |
| 「從這段製作 Short/Reel/TikTok」 | 同上，再加上 captions.py --style punch、render.py --preset shorts --fit crop（螢幕錄影則用 blur） |
| 「加入字幕」 | transcribe.py → captions.py → render.py --captions（或輸出 .srt 檔案） |
| 「加入音樂」 | render.py --music bed.mp3（自動降低音量以配合人聲） |
| 「讓它夠大聲／修復音訊」 | render.py --voice --denoise，目標請參閱 platforms.md |
| 「品牌片頭／Logo 揭示／短動畫」 | 複製 films/brand-sting，填寫品牌工具包，靜態圖 → 草稿 → 主版 → QA |
| 「發表影片／宣傳片／廣告」 | 複製 films/launch，撰寫文案，選擇格式，靜態圖 → 草稿 → 主版 → QA |
| 「檢查這部影片」 | qa.py video.mp4 --sheet sheet.jpg [--safe] |
| 專案已在使用 Remotion | references/remotion.md |
需求
編輯需要 ffmpeg 6+ 和 Python 3.9+。轉寫：pip install faster-whisper（或 openai-whisper、whisper.cpp）。影片製作：Node 18+ 和 Playwright（npm i -D playwright && npx playwright install chromium）。字幕使用 libass 燒錄（當 ffmpeg 有編譯時），否則使用 Pillow 繪製（pip install pillow）。執行 python3 scripts/doctor.py 來查看已安裝的項目。
所有腳本都接受 --help。每個工作請在專屬資料夾中進行：work/ 儲存中間檔，out/ 儲存最終成品。
剪輯素材
python3 scripts/transcribe.py raw.mp4 -o work/words.json # 逐字稿（含時間點）
python3 scripts/plan_cuts.py raw.mp4 --words work/words.json -o work/edl.json
python3 scripts/captions.py work/words.json --edl work/edl.json --style clean -o work/cap
python3 scripts/render.py work/edl.json -o out/final.mp4 --preset youtube \
--captions work/cap.cues.json --music bed.mp3 --voice --zoom auto
python3 scripts/qa.py out/final.mp4 --edl work/edl.json --sheet out/sheet.jpg \
--words work/words.json --words-check
- 先閱讀逐字稿，決定結構：哪些段落完全移除（段落剪輯看起來乾淨；許多句中剪輯看起來急促），以及鉤子是什麼。必要時，將整個段落的決定手動放入 EDL 的
segments中。 plan_cuts.py移除靜音（縮短為一次呼吸，而非歸零）、填充詞和廢棄的重拍（保留最後一次拍攝）。靜音是根據每段錄音測量，每個邊界都對齊實際音訊，前後間距不對稱（前 80 毫秒，後 140 毫秒），且絕不延伸到已移除的字詞中。閱讀它的清單：強調性的重複可能看起來像重拍。- 任何較長的工作，與專案負責人確認：剪輯前/後的持續時間、刪除的段落、放棄的重拍。他們的註記會變成 EDL 編輯。
render.py在一個 ffmpeg 圖表中完成所有工作：幀精確修剪、每個剪輯處 8 毫秒淡入淡出、固定幀率、推近、重新構圖、字幕、聲音優化、壓低音樂音量以及兩次通過的響度設定。qa.py，然後查看聯絡表。--words-check會重新轉寫結果，並標出任何被剪切吞掉的字詞。
判斷、數字與失敗模式：references/editing.md。音訊：references/sound.md。
製作影片（品牌片頭、發表廣告、廣告）
cp -r films/brand-sting my-film && python3 scripts/sfx.py --out my-film/sfx
# 編輯 my-film/index.html 中的 PARAMS（或傳遞 --params '{"name": "...", ...}'）
node scripts/render_film.mjs my-film/index.html --stills 0.5,1.6,2.4,3.5 -o work/stills # 檢視它們
node scripts/render_film.mjs my-film/index.html --draft -o work/draft.mp4 # 判斷節奏
node scripts/render_film.mjs my-film/index.html --blur 4 -o out/intro.mp4 # 主版
python3 scripts/qa.py out/intro.mp4 --no-gaps --sheet out/intro.sheet.jpg --safe
- 品牌工具包優先（
references/brand-intro.md）：官方 Logo 檔案、十六進位色碼、字型、確切的文字、語域、格式、聲音，以及每個數字的來源。絕不重繪或重新著色 Logo；絕不編造聲稱、客戶或產品 UI。 - 先有拍點表再有程式碼： 每個拍點包含其時間、移動內容、緩動及音效。選擇一個語域（高端、乾淨、科技、大膽、趣味），並以此縮放整個時間軸。
- 基於
assets/film.js建立： 每個像素都是t的函數。使用Film.tween、Film.spring、Film.stagger、Film.random(seed)；不使用 CSS 動畫、計時器或Date.now。在瀏覽器中開啟 HTML 即可即時拖曳時間軸。 - 在每個拍點輸出靜態圖，然後是草稿，最後才是主版。 在渲染影片前，先修正靜態圖顯示的內容。主版渲染速度約每秒 2–5 幀；草稿則快 10 倍。
- 聲音是影片的一部分。
scripts/sfx.py合成音效工具包（撞擊聲、轟鳴聲、咻聲 ×3、上升音、爆音、滴答聲、鈴聲、背景音）；提示點位於影片設定檔中，由渲染器混合並設定響度。撞擊聲的峰值會落在揭示畫面上。
模板：films/brand-sting（3–7 秒 Logo 揭示，五種語域，16:9 / 9:16 / 1:1）和 films/launch（15 秒鉤子 → 問題 → 揭示 → 證明 → 行動呼籲，三種格式，9:16 在平台安全區域內，*word* 強調）。將它們作為起點；當簡報需要時，可以改變結構。
原則（時間點、依角色緩動、交錯、字體大小、顏色、有原因的轉場、應避免的通用風格以及可捕捉它們的測試）：references/motion.md。
始終適用的規則
- 每個修剪都重新編碼。 直接複製串流修剪會對齊關鍵幀。
- 所有輸出檔案使用固定幀率；採用 H.264 + yuv420p + AAC +
+faststart。 - 以測量為基礎的響度：網頁與社交平台目標 -14 LUFS / ≤ -1 dBTP，Podcast 目標 -16。
- 文字在安全區域內：對 9:16 影片，頂部 288 px、底部 672 px、右側 192 px（在 1080×1920 解析度下）之內不要有文字。1080 解析度下字體 ≥ 28 px。
- 誠實的內容：使用真實 Logo、附來源的真實數字、真實的產品 UI；若音樂、人聲或素材為生成內容須明確標示。
- 僅使用授權音樂。 絕不從影片或串流服務中擷取音訊。
- 完成即意味著已檢查：
qa.py通過、聯絡表已檢視，並且任何無法檢查的項目都已清楚說明。
檔案
| 路徑 | 用途 |
|---|---|
scripts/transcribe.py | 產生含有字詞時間點的 words.json（faster-whisper / whisper / whisper.cpp） |
scripts/plan_cuts.py | EDL：移除停頓、填充詞、重拍，並附帶原因 |
scripts/captions.py | 在編輯後的時間軸上產生 SRT、樣式化 ASS 與提示 JSON |
scripts/render.py | EDL → 完成影片（預設集、重新構圖、字幕、音樂、響度） |
scripts/qa.py | 檢查格式、長度、黑畫面、凍結、靜音、響度、字詞、聯絡表 |
scripts/sfx.py | 合成音效工具包 |
scripts/render_film.mjs | HTML 影片 → MP4（草稿、含動態模糊的主版、靜態圖、海報） |
scripts/doctor.py | 查看已安裝與缺少的項目 |
assets/film.js | 確定性動畫引擎 + 含拖曳時間軸的瀏覽器預覽 |
films/ | brand-sting 與 launch 模板 |
references/ | 剪輯、動畫、品牌片頭、聲音、平台、ffmpeg、Remotion 參考文件 |