clipwise：長影片 → 垂直 Shorts
一切都在本地端執行（CPU 即可；若有 CUDA 則用於轉錄）。
下方的 SKILL_DIR 代表此檔案所在的資料夾。所有指令的格式為
python3 SKILL_DIR/scripts/run.py ...；腳本會自行切換到 clipwise 的虛擬環境。
工作會寫入 ~/clipwise-work/<job>/（或 $CLIPWISE_WORK），或使用 --workdir DIR。
0. 設定檢查（每次工作階段，一次）
python3 SKILL_DIR/scripts/run.py check
必須以 ready 結尾。如果不是，請告知使用者 clipwise 需要一次性設定（約
2 GB：Python 套件加上 whisper 模型），請他們閱讀 SKILL_DIR/setup.sh，並在
同意後執行 bash SKILL_DIR/setup.sh。如果缺少 ffmpeg 或 Python 3.10+：setup.sh 會
印出對應作業系統的安裝指令；未經詢問請勿安裝系統套件。
工作流程
- 準備（擷取 + 轉錄，一個指令）：
工作資料夾中的輸出：python3 SKILL_DIR/scripts/run.py prep "<路徑或連結>" --job <名稱> [--start S --max-seconds N] [--cookies cookies.txt] [--model large-v3-turbo] [--language xx]source.mp4（第一個影片+音訊串流，SDR，CFR 30 若重新編碼）、probe.json、transcript.txt（每行一段[start-end] (wN) text，以來源秒數為準）、transcript.json、words.tsv。對於長影片，請使用--start/--max-seconds指定值得剪輯的部分；轉錄在 CPU 上約為即時的 0.6-1 倍。 - 自行挑選片段。 閱讀
transcript.txt（以及頂部的任何# WARNING行）， 參考SKILL_DIR/references/viral-rubric.md。撰寫<job>/picks.json：每個片段 10-50 秒、 鉤子在前、乾淨的收尾。數量：請見下方規則。 - 渲染前取得核准。 每個片段顯示一行：時間戳記、鉤子、標題、 一行說明原因。在小 CPU 上渲染每個片段約需 1-2 分鐘。如果您手寫了字幕文字 （非英語或混合語碼語音），請同時顯示那些行。
- 渲染：
每個片段在python3 SKILL_DIR/scripts/run.py render --job <名稱> [--fast] [--only 2] [--music bed.mp3]<job>/out/中：clip_<id>.mp4、clip_<id>.txt（標題、說明、置頂 留言、標籤、原因）、clip_<id>.json（探測數值、佈局、人臉覆蓋、音效、 時間）、clip_<id>_cutmap.json、clip_<id>_sheet.png。--fast= 預覽品質。 - 檢查每一個
clip_<id>_sheet.png使用您的影像/視覺工具（10 幀；紅線 = y 1620，平台 UI 在其下方）。檢查：人臉在畫面內、字幕可讀、字幕未遮住 人臉、紅線下方無重要內容、顏色未過淡。修正（片段選擇、字幕覆寫、--layout、--font-size）並使用--only <id>重新渲染。 - 交付 MP4 路徑和
.txt內容。提供run.py clean --job <名稱>（刪除source.mp4和暫存目錄，保留out/）。
每部影片的 Shorts 數量
-
使用者指定了數字（"從 <連結> 製作 5 支 Shorts"）：製作恰好那麼多。如果 影片沒有足夠的強力片段，請在渲染前告知，並提出誠實的數量（"我找到 3 個 通過檢查表的片段；另外 2 個會很弱"）。
-
未指定數量： 根據來源長度（或轉錄的視窗長度）調整：
來源長度 Shorts 數量 低於 5 分鐘 1-2 5-15 分鐘 3-5 15-45 分鐘 5-8 45 分鐘以上（Podcast、訪談） 8-15 -
只有通過評分標準檢查表的片段才算數。切勿為了達到數量而塞入弱片段。
picks.json（最小範例）
[{"id": "1", "start": 65.5, "end": 110.3, "title": "Is every flood caused by climate change?",
"hook_start": 74.85, "hook_end": 80.1, "payoff_start": 102.0,
"why": "先以出人意料的說法開頭，最後再解答。", "comment_bait": "你知道這件事嗎？",
"description": "...", "hashtags": ["#shorts", "#climate"],
"caption_overrides": [{"w": 219, "text": ""}, {"start": 90.1, "end": 92.4, "text": "這裡放確切的文字"}]}]
必要欄位：id、start、end（來源秒數）。hook_start/hook_end 會將 2-3 秒的行移
至前方（"hook_mode": "repeat" 則仍保留在主體內）。payoff_start 放置低沉的
重擊音效。caption_overrides：{"w": N, "text": ""} 編輯/刪除第 N 個字（transcript.txt 中的 (wN)，
words.tsv 中的 i）；{"start", "end", "text"} 取代該時間範圍內的所有字詞。
完整結構與評分：references/viral-rubric.md。
渲染旗標
| 旗標 | 效果 |
|---|---|
--fast | x264 ultrafast CRF 24，4 fps 人臉取樣（預覽）。預設值：preset faster，CRF 20 |
--only ID | 僅渲染一個片段（可重複） |
| `--layout auto | crop |
--music FILE | 使用者提供的背景音樂，音量約為語音下方 17 LU，並透過側鏈壓縮做閃避效果。--music-db 20 = 更安靜 |
--sfx-dir DIR | 使用您自己的 whoosh_fast、whoosh_soft、thud_low、pop、tick（.wav/.mp3/.flac/.ogg）取代合成的音效 |
--no-sfx、--no-silence-cut | 關閉那些功能 |
--font "Lato Black"、--font-size 84、`--highlight yellow | green、--no-upper` |
--preset、--crf、--keep-tmp | 編碼器覆寫；保留語音/混音 wav 和 captions.ass 以供除錯 |
環境變數：CLIPWISE_HOME（預設 ~/.clipwise）、CLIPWISE_VENV、CLIPWISE_WORK、
CLIPWISE_MODEL（預設 large-v3-turbo）、CLIPWISE_DEVICE（auto|cpu|cuda）。
每個片段的渲染內容
鉤子移至前方，裁切 > 0.35 秒的靜音（門檻值來自片段本身的語音/噪音 位準），保留的部分對齊至 30 fps 格點，使音訊樣本等於影格數。人臉追蹤 使用 YuNet 處理裁切後仍存在的影格：主要人臉、黏著性（新人臉必須持續 1.2 秒 且大 1.6 倍才會接管）、具死區的平滑鏡頭移動、僅在切點跳切。每 2-4 秒 拉近縮放 1.0/1.12 倍。逐字 ASS 字幕（最多 4 個字，當前字高亮顯示） 放置於下巴下方且 y 1620 以上。語音清理、合成音效、可選的側鏈壓縮 背景音樂、雙通道 loudnorm 標準化至 -14 LUFS / -1.5 dBTP。H.264 + AAC 48 kHz， 1080x1920，30 fps。最終 A/V 串流時長會經過斷言確認。
實測時間（2 核心 CPU，無 GPU）
| 步驟 | 實測 |
|---|---|
| 擷取：85 MB 1080p VP9 網路下載 + 3 分鐘視窗重新編碼為 H.264 | 總計 7.7 分鐘（下載為主，約 5 分鐘） |
| 擷取：20 秒 10 位元 HDR iPhone 片段（色調映射 + CFR） | 45 秒（HDR 約耗時 2.3 倍於片段時長） |
| 轉錄 large-v3-turbo，3 分鐘英文 | 110 秒 ASR（0.61 倍即時）+ 19 秒模型載入 |
| 預設渲染，40.6 秒片段 | 85 秒 |
--fast 渲染，26.4 秒片段 / 17.1 秒 pad 片段 | 32 秒 / 30 秒 |
常見陷阱
- YouTube 機器人驗證牆（"Sign in to confirm you're not a bot"）：間歇性、依 IP 而定。
fetch 會以退出碼 3 結束。請使用者提供
--cookies cookies.txt（從瀏覽器匯出）或 該檔案本身 / 一個 Drive 或 Dropbox 連結。請勿在 yt-dlp 播放器客戶端或代理上迴圈。 私人 Drive 連結會以退出碼 2 結束：請要求開啟「任何擁有連結的人」分享或提供本地檔案。 - 影音同步是硬性規則。 每個輸出的音訊和視訊串流時長必須相差在 0.1 秒內
（渲染會斷言）。切勿在非零起始點使用串流複製來修剪，也切勿使用
aselect來 裁切音訊；請使用腳本。 - ASR 配方是固定的： 先正規化音訊、自動偵測語言、無 VAD、無
initial_prompt（它會洩漏到轉錄文字中）。保持使用 large-v3-turbo；small在帶有口音或 混合語碼的語音上會循環並產生幻覺（轉錄時會發出關於循環的警告）。 - 非英語語音可能會被翻譯回來。 對於許多以非拉丁字母書寫的語言
（以及混合語碼語音），whisper 會回傳英文。此時轉錄文字僅作為
時間與意義的參考：請使用
caption_overrides的{"start", "end", "text"}範圍，以 說話者自己的語言和文字來撰寫字幕行，並在渲染前向使用者顯示。標題和標籤也 遵循說話者的語言。 - 字幕： 切勿遮住人臉，且應位於底部約 300 像素以上（平台 UI）。如果
格狀圖顯示衝突，請縮短片段、使用
--layout pad，或降低--font-size。 - 追蹤器跟隨最大的人臉，而非說話者。 對於兩人對話的寬鏡頭，請使用
--layout pad，或選擇一人說話的時段。 - 放大： 1080p 16:9 來源會裁切為 608x1080 並縮放 1.8 倍；720p 來源會 縮放 2.7 倍且看起來模糊。建議優先下載 1080p 以上的來源。
- 小型 CPU： 請勿同時執行兩個編碼，或轉錄和編碼同時進行； 渲染會一個接一個處理片段（run.py 已經這樣做）。