Vlog 影片
將使用者的素材資料夾轉換為一部完成的 YouTube 影片，然後根據使用者的筆記進行迭代調整，直到他們滿意為止。此處理流程是基於「Yaris 告別」影片（24 分鐘，烏克蘭語口白，iPhone + Sony 行車記錄器）所建立的；references/example_yaris.py 是該影片的完整專案檔，是了解完整剪輯成品樣貌的最佳指南。
開始之前
- 設定。
<skill>/config.json儲存了此機器的路徑（ffmpeg、melt、搭載 WhisperX 的 Python、車牌辨識模型、音樂資料夾、編碼器、口語語言）。如果該檔案遺失，或因缺少工具而導致指令碼失敗，請執行python <skill>/setup/setup.py（僅檢查）並向使用者顯示缺少了什麼；獲得使用者同意後，執行python <skill>/setup/setup.py --install。下面的所有指令碼都必須使用 config.json 中設定的 Python（"python"）來執行，因為 WhisperX 和 torch 是安裝在那個環境中的。 - 使用者。 如果
<skill>/user.md存在，請閱讀它：內容會說明使用者是誰、應使用哪種語言回覆，以及他們的慣用偏好。如果不存在：請使用使用者的語言回覆，保持回覆簡短，並使用 mm:ss 格式標註影片時間點以供使用者參考。 - 在下面的指令中，
$K表示<skill>/scripts，而python則是已設定的 Python 直譯器。
專案結構
素材保留在使用者放置的原始位置；最終的 mp4 檔案、YouTube 說明、縮圖和字幕也會放在那裡，因為那是使用者查看的地方。工作檔案則放在一個專案資料夾中（例如 C:/Data/<名稱>-video/）：
<名稱>-video/
project.py 路徑、EDL、HOOK、音樂、構圖、make_stills() （複製 references/project_template.py）
transcripts/ <片段>.json 來自 transcribe_all.py
film/ 已渲染的插入片段、<片段>_blur.mov、<名稱>.mlt、<名稱>.mp4
film_check/ 聯絡表、測試音檔、檢查影格（暫存區）
edit_notes.md 使用者的審閱筆記以及針對每條筆記的處理記錄
subs/, thumbnail/, route/
工作流程
1. 盤點
python $K/scan_meta.py <素材路徑> film_check/meta.json：取得每個檔案的時間、時長、GPS 資料。按時間排序後，即可得到故事的順序。- 在決定之前先查看內容：對於影片片段使用
python $K/contact_sheet.py <輸出.png> 6 <片段...>，對於照片則使用平鋪顯示的聯絡表；請自行查看這些圖片。注意直排片段（旋轉 -90/90 度）、顯示車牌的片段、行車記錄器檔案、螢幕錄影。旅行日期範圍內的 Tesla 行車記錄器 / 哨兵模式事件：請參考references/teslacam.md（尋找事件、透過teslacam_grade.py進行色彩校正）。 python $K/transcribe_all.py <素材路徑> transcripts：為每個談話片段產生帶有逐字時間戳記的 WhisperX 轉寫稿（可中斷續傳，語言從 config 中讀取）。全部閱讀一遍；它們是故事的原始素材。
2. 故事與 EDL
在開始建構之前，先用幾行文字向使用者提議影片結構：包括預告片、各個部分、哪些照片、地圖或靜態圖片可以輔助說明哪段談話。典型的結構如下：
- 預告片（HOOK）：選取旅行中各處 4-6 句簡短有力的話語，每句都是一個完整的主題。
- 標題卡 放置在道路畫面上，然後是談話片段，中間用 4-10 秒的道路插入畫面搭配音樂分隔。
- 在談話提及某事物時插入對應畫面：提到加油時顯示收據、提到檢驗時顯示檢驗台、在每段旅程開始時顯示路線地圖。
- 語音上的圖片（B-roll、手機截圖、說話者繼續說話時的說明文字）：在將談話片段交給 filmkit 處理之前，使用
burn_in.py將它們燒錄到片段中（filmmkit 只有在片段有說話時才會顯示它）。直排圖片（截圖、直排影片、直式照片）會以全影格高度顯示在說話者臉部的空側，這是透過人臉偵測來決定的，以確保臉部保持在畫面中；手機的時鐘和按鈕無論如何都會填滿頂部和底部區域。橫向圖片則會覆蓋整個畫面。 - 道路插入畫面的內容應與故事所需相符（在說「我們停車了」之前顯示駛入加油站的引道，在機場場景之前顯示機場停車場），而不只是隨便一段高速公路：請查看道路片段在適當時間點附近的聯絡表。
- 結尾卡片：在道路畫面上停留 20 秒，頂部顯示文字，中間留空給 YouTube 片尾資訊卡；如果使用者有的話，可以在這裡放一個推薦連結。
從 references/project_template.py 複製並撰寫 project.py；EDL 項目類型、說明文字、音樂鍵值以及每個片段的選項在該檔案中有詳細說明。談話範圍來自轉寫稿的時間戳記。
3. 建構與渲染
python $K/blur_plates.py <素材路徑> <專案>/film [--faces] IMG_0089 ... # 車牌；--faces：同時處理人物
python $K/burn_in.py film/IMG_0089_blur.mov film/IMG_0089_over.mov spec.json # 若有需要的話，在語音上疊加圖片
python $K/filmkit.py <專案>/project.py # 渲染插入片段，寫入 film/<名稱>.mlt
python $K/render_final.py <專案>/film <名稱> <素材路徑>/<名稱>_HLG.mp4 # 耗時：在背景執行
在執行大量 GPU 工作（渲染、WhisperX、配音）之前，請先執行 nvidia-smi：顯示卡的編號會在每次連線時改變，且不同工具之間可能不同，而其他工作也可能占用了一張顯示卡（參考 references/lessons.md，「GPU 與硬體編碼器」）。filmkit.py --no-media 只會重新寫入 .mlt 檔案（數秒鐘）。渲染完成時會輸出響度、時長、編解碼器/HDR 標籤以及綠色影格計數：預期結果約為 -14 LUFS、Main 10、arib-std-b67、bt2020、0 個綠色影格。
4. 在通知使用者完成之前進行驗證
使用 WhisperX 進行聆聽，而不是只信賴 EDL：對於每個新增或修改的剪輯點，從 已完成 的 mp4 檔案中剪下相同的秒數並進行轉寫（python $K/transcribe_window.py <音檔路徑> <偏移量>）。初版的轉寫稿經常在片語結束的位置上出錯，特別是在處理數字時，因此依據這些轉寫稿所做的剪輯可能會切掉結尾（例如「не 144, а 147」遺失了「а 147」）。同時，也測量相鄰區段的響度（ffmpeg -ss A -t N -i film.mp4 -af ebur128 -f null -），並檢查每個新增插入畫面的一個影格。其他常見陷阱及其解決方案：請參考 references/lessons.md。
5. 審閱回合
使用者觀看影片並附上帶有影片時間點的筆記。針對每條筆記：
python $K/timeline.py film/<名稱>.mlt 12:22會顯示該片段的名稱和來源秒數。- 檢查來源（對一段時間區間進行轉寫、測量響度、查看影格）。告訴使用者實際的內容是什麼，並引用原始話語；使用者的記憶有時會與錄音內容不同。
- 修改 EDL 並將修改記錄在
edit_notes.md中（影片時間點、片段名稱與秒數、說了什麼、做了什麼修改）。
當使用者仍在觀看時，先收集筆記，不要重新建構：最後一次建構可以省去多次長時間的渲染。當使用者說可以建構時，重新建構一次，按照步驟 4 驗證每個修改過的地方，然後更新章節。
6. 交付成果
references/youtube.md：包含章節的說明（使用 timeline.py）、縮圖（使用 make_thumb.py）、字幕（對完成的影片使用 make_subs.py 並手動校正，然後逐條翻譯，再使用 onscreen_subs.py 將畫面上的文字作為獨立的字幕條進行翻譯）、YouTube 自動配音。使用者可以透過手機使用 python $K/media_server.py --port 8765 <素材路徑> <專案>/film 來觀看渲染結果（僅限區域網路 / VPN；唯讀；亦可見於 github.com/vstoos/media-server）。
7. 配音音軌
對於使用者希望用聽的而非閱讀的語言：請參考 references/dubbing.md。語音使用 Higgs TTS 3（自 2026 年 11 月 6 日起為預設值），搭配使用者 以該語言 儲存的參考語音檔案（位於 C:/Data/voices，傳入參數 -）；所有帶有 Higgs 音軌的影片描述都須標註「採用 Boson AI 的 Higgs Audio」。字幕先透過 dub.py gen 產生，接著 dub_check.py 會逐段捕捉模型的瑕疵，dub_regen.py 則負責替換失敗的部分，最後 dub.py mix 建構音軌並印出需要聆聽檢查的內容。在 say.json 中修正發音問題。用於無聲片段（行車記錄器片段）的旁白，採用烏克蘭語的相同流程，以字幕形式撰寫。不要僅憑檢查就認為配音是乾淨無誤的：使用者的耳朵才是最終的把關者。
隱私
車牌：使用者不會模糊一般交通車輛的車牌（波蘭；浮動方框會破壞道路畫面的視覺效果）。只有在片段顯示該駕駛者可能違規或發生危險的狀況時，才模糊該車牌，以避免影片被用來對特定人士提出投訴；道路插入畫面則透過專案的 CLIP_SRC 原樣使用。模糊工作人員、路人與兒童的臉部（使用 blur_plates.py --faces；請檢查影格，因為車漆上的倒影可能誤導辨識系統）；路線地圖的起點應設定在公共場所，絕不能是使用者的住所；除非被要求，否則不要將其他人的臉部（特別是兒童）放在縮圖上。
參考檔案
references/project_template.py：附有註解的專案範本檔案，以供複製使用；EDL 語法說明。references/example_yaris.py：已完成的 Yaris 影片，展示了所有功能。references/lessons.md：關於 HDR、音訊、剪輯與構圖的常見陷阱，以及經實證有效的解決方案。references/teslacam.md：Tesla 行車記錄器 / 哨兵模式片段（HW3）：從儲存的事件中尋找事件，以及色彩校正方法（使用scripts/teslacam_grade.py）。references/youtube.md：說明、章節、縮圖、字幕、配音、片尾畫面。references/dubbing.md：以使用者克隆語音製作的獨立音軌，以及自動化的瑕疵檢查。references/example_make_route.py：來自 Yaris 影片的動畫路線地圖（使用 Sentinel-2 圖磚 + OSRM 道路）；修改其常數（邊界、城市、地標點、路段）以適用於新的旅程。