perso-ai/perso-dubbing-plugin

/clip

將影片剪成短影音片段 + 重新構圖。字幕不是本技能的工作 — 剪輯完成後，srt 技能會負責字幕樣式設定（請參閱下方的交接流程）。

進入點

• 明確時間碼（「剪輯這段影片的 2:00–3:00」）→ 直接剪切本地檔案：--video "<file>" --ranges "2:00-3:00,..."。不需要 STT、不需要金鑰、不消耗點數。

• 在 STT 項目上的 AI 亮點選擇 → --plan 然後 --clips（以下流程）。需要項目的轉錄稿 + 逐詞時間戳。

• 原始影片，「找出精彩時刻」（未提供時間碼）→ 沒有轉錄稿就無法挑選亮點，因此請詢問用戶想要哪一種：

  • STT（專業選擇，會消耗點數）：先執行 srt 技能的 STT 來建立項目，再用 --plan/--clips 進行剪輯。
  • 免費（無 STT）：用戶提供時間碼，你用 --video --ranges 剪切。

  根據用戶的選擇繼續進行 — 未經詢問不要執行 STT（會消耗點數）。

核心規則

• 只有 worker 能看到原始金鑰 — 絕不要打開、輸出或將其作為參數傳遞。
• 金鑰限制僅適用於 --project/--plan/--clips。 --video --ranges 和 --sidecars 完全離線 — 絕對不要為它們執行金鑰檢查/註冊。
• 在背景執行 — 編碼需要時間。
• 本技能共用配音技能的程式庫：dubbing 資料夾必須安裝在 clip 旁邊。

流程

階段 1 — 規劃。 node scripts/clip.mjs --project <seq> --plan 會列印摘要的章節對應表（主題指南）加上完整的逐句轉錄稿，每行格式為 order [start-end] text。

階段 2 — 挑選，然後剪切。 閱讀轉錄稿並選擇片段，每個片段格式為 { "title": "...", "start_order": N, "end_order": M }。評選標準：

• 鉤子開頭 — 從能抓住注意力的句子開始（提問、大膽陳述、有趣/驚人的台詞）。
• 在情緒高峰結束，而不是在第一句完整的句子就結束。 跟著節奏走到結尾 — 包含完整的反應、後續影響以及任何次要的笑點。多看幾句看似結尾之後的內容；如果仍然是同樣的反應就保留。
• 在轉折點剪切 — 就在能量下降或語氣轉變之前結束（興奮的反應 → 平鋪直敘的敘述）。
• 高峰 — 偏好有趣 / 驚人 / 感性 / 值得引用的時刻；高峰通常出現在揭曉後的一兩句。
• 長度 30–90 秒 — worker 會在超出範圍時發出警告；寧可保留完整弧線也不要過早截斷。
• 標題 — 描述該時刻；會成為檔案名稱（01_<title>.mp4）。

章節長度約等於一個章節 — 僅將章節對應表作為參考，然後縮小範圍到一個鉤子。

執行：node scripts/clip.mjs --project <seq> --clips '<json>' [--out folder]（--clips 也可接受 @path）。橫向（16:9）來源會被重新構圖為 9:16（戲劇式短片信箱）；直向來源則保持原樣。Worker 會寫入片段以及 clips.json 清單（記錄每個片段 + 後續字幕所需的轉錄稿片段）。轉發 [progress]；從 [clips-output] 傳遞檔案。

字幕 → 交接給 srt 技能

字幕預設為關閉。剪輯完成後，告知用戶片段已準備好，並詢問是否要添加字幕。如果用戶想要字幕，先顯示預設樣式 — 不要直接跳到某一種，完全按照 srt 技能的字幕樣式設定流程進行：在 Claude 應用程式中是互動式圖庫（選擇 + 套用），在其他環境則顯示靜態的 ../srt/assets/style_presets.png + node ../srt/scripts/style.mjs --list-presets 選單。讓用戶選擇預設樣式或描述一種樣式（短影音適用的預設樣式如 karaoke/bold-punch）。只有在用戶選擇後：

1. 寫入 sidecar 檔案：node scripts/clip.mjs --sidecars "<out>/clips.json" — 只有選擇 karaoke 預設樣式時才添加 --karaoke（這也會寫入 <clip>.timestamps.json 以取得計量化的逐詞時間；一般預設樣式只需 .srt）。
2. 使用 srt 技能為每個片段設定樣式：node ../srt/scripts/style.mjs "<clip>.mp4" "<clip>.srt" --preset <id>（karaoke 需附加 --word-timestamps "<clip>.timestamps.json"）。請參閱 srt 技能的「設定字幕樣式並燒錄」章節。

為遙測添加 --host <runtime>（靜默），與其他 worker 相同。

配置（環境變數）

與 /dubbing / /srt 相同（PERSO_API_BASE/PERSO_MEDIA_BASE — 僅限 https perso.ai 主機，PERSO_SPACE_SEQ、XP_API_KEY、PERSO_NO_TELEMETRY，…）。