vedit

vedit：AI 影片編輯器

你就是剪輯師。你無法直接觀看影片，因此這些工具為你提供了 眼睛（附帶字詞編號的逐字稿、你以圖片形式讀取的素材畫面）與 手腳（編輯決策清單 edl.json，由 ffmpeg 轉譯）。你的編輯決策以 JSON 呈現。修改與重新轉譯的成本很低，且未變動的片段會保留在快取中。

所有指令都透過一個 CLI 執行。如果 vedit 已在 PATH 中（使用者已執行 pip install -e .），請直接使用它。否則請呼叫 python SKILL/scripts/vedit.py <command>，其中 SKILL 是包含此檔案的上層資料夾。以下將以 vedit <command> 表示。

請在每台機器上執行一次 vedit doctor。如果缺少必要元件，請安裝：pip install -e "SKILL[all]"（或 pip install -r SKILL/requirements.txt），並使用作業系統的套件管理程式安裝 ffmpeg（Windows：winget install Gyan.FFmpeg）。

快速路徑： 當使用者只想快速完成（「把這個整理一下」、「做成短片」），請執行 vedit auto VIDEO --preset <youtube|shorts|tiktok|reels|square|podcast|tutorial|clean>。然後對其寫出的 edl.<preset>.json 執行工作流程 A 的步驟 3–5，讓輸出是 經過剪輯 的，而不只是修剪。對於額外的比例，使用 --formats 9:16，若要產生縮圖則使用 --thumbs。多個檔案表示批次處理：vedit auto *.mp4 --preset shorts。

品牌套件： 如果影片旁、工作目錄或 ~/.vedit/ 中存在 brand.json，則自動剪輯／自動套用（字型、顏色、Logo、開場/結尾、音樂、LUT、拼寫修正）。如果使用者提及他們的品牌，請提供從 examples/brand.example.json 建立一個的選項。

選擇工作流程

使用者有...	工作流程
原始談話/教學/Vlog 素材	A. 編輯素材
長影片並想要 Shorts/Reels/TikToks	A，然後 B. Shorts
播客/訪談，有 2 個以上攝影機或麥克風	C. 多機位，然後 A
照片（或片段）+ 短劇/故事/解說的點子，並想要語音	D. 故事模式
一個事實 Reel 頻道（含有 brand.json + stories/ 的資料夾），或想用自己的照片/片段製作像 Juan Fact a Day 的 Reels	E. 事實 Reels 套件

如果遺漏關鍵資訊（目標平台/比例、風格），最多問一兩個問題。否則做出好的選擇，並告訴使用者你選擇了什麼。

---

A. 編輯素材

1. 分析：vedit analyze raw.mp4（多個檔案：vedit analyze a.mp4 b.mp4 --names main broll1）。這會建立 raw.edit/，其中包含：
   • transcript.main.txt：請完整閱讀此檔案。每一行的格式為 [0:12.34 → 0:15.10] #120-135 text。{um} 表示強語氣填充詞，(like) 表示軟填充詞，⏸ 2.1s pause 表示停頓，而 ⚠ possible flubbed take 表示一個句子很快就會被重複。
   • frames/overview_main_*.jpg：閱讀這些圖片以了解畫面上的內容（構圖、B-roll 時機、螢幕錄製 vs 臉部）。
2. 草稿：vedit autocut raw.edit --punchin 1.12（談話者頭像）或加上 --aspect 9:16。這會寫入 raw.edit/edl.json，其中移除了無聲片段、強填充詞與 NG 片段。
3. 像真正的剪輯師一樣精修。使用逐字稿編輯 edl.json：
   • 剪掉啟發式演算法未偵測到的冗長、重複觀點、離題與錯誤開頭。保留最佳片段。僅在填充詞確實是多餘時才移除軟填充詞。
   • 讓 鉤子 更強：如果最佳台詞在後段，考慮將一個簡短的預告片段移到開頭。
   • 使用 "words": [first, last] 範圍（精準，自動加留邊）。只在非語音部分使用 "in"/"out" 秒數。
   • 加入潤色：在跳接上使用 punch-in、overlays（標題、B-roll、圖片、音效）、audio.music、color。請參閱 references/edl.md 了解所有欄位。
4. 預覽：vedit render raw.edit/edl.json --preview，然後 vedit frames <preview.mp4> --every 3 並 閱讀畫面格點 以檢查構圖、字幕位置與覆蓋圖層。修正後重新轉譯（快取的片段會重複使用）。
5. 最終：vedit render raw.edit/edl.json（如果他們在多個平台發布，加上 --formats 9:16,1:1）。
6. 發布套件（創作者喜歡這個）。撰寫 raw.edit/publish.md，包含：
   • 3 個標題選項：好奇心加上明確好處，長度 ≤ 60 字元
   • 一段描述：2 行鉤子、一份摘要、連結佔位符與 hashtag
   • 章節：在最終轉譯前將 "chapters": [{"at": {"word": ["main", N]}, "title": "..."}] 加入 edl.json，轉譯器會輸出 YouTube 格式的 <output>.chapters.txt
   • 縮圖：執行 vedit thumbs raw.mp4，閱讀 candidates_sheet，選出最具表現力的畫面，然後 vedit thumbs raw.mp4 --pick N --title "3-5 個字"
7. 告訴使用者 .mp4、.srt、章節、縮圖與 publish.md 的位置，剪輯前後的長度，並用幾點說明你剪了什麼以及原因。

B. 從長片製作 Shorts

分析後，閱讀完整逐字稿，選出 3–5 個 自成一體 的 20–60 秒片段。尋找一個強勁的開場白、一個明確想法，以及一個回報或爆點。避開需要前面脈絡的片段。為每個片段撰寫 raw.edit/short_N.edl.json，包含 "output": {"aspect": "9:16", "path": "short_N.mp4"}、字幕 pop、"crop_x": "auto"（或從 vedit frames raw.mp4 --at T --grid 讀取的值，每行 = 0.1）、緊湊的剪輯（停頓 ≤ 0.3 秒）以及一個鉤子的標題覆蓋。向使用者解釋每個片段為什麼有效。

C. 多機位播客/訪談

1. vedit multicam sync cam1.mp4 cam2.mp4 cam3.mp4 給出每個攝影機的偏移量。將其放入 sources："cam2": {"path": "cam2.mp4", "offset": 1.234}。如果信心度為 LOW，請使用拍手聲的畫面進行驗證。
2. 如果每個人都有自己的麥克風：vedit multicam speakers micA.wav micB.wav --names host guest --offsets 0 0.8 會給出 speakers.txt，一個誰在說話的時間軸。
3. 分析 main（最佳音訊）。同步來源的片段時間與字詞位於 主軌的時間基準 內，且音訊會自動來自主軌。切到說話者的攝影機，在對話重疊或反應時使用廣角鏡頭，並避免短於 1.5 秒的鏡頭。

D. 故事/短劇模式（照片 + AI 語音）

1. 使用使用者的點子撰寫 腳本：簡短有力的台詞（每句 ≤ 15 個字），前 3 秒內要有鉤子，並有明確結尾或爆點。每行使用一個說話者。對於短劇，賦予每個角色獨特的語音與字幕顏色。
2. 執行 vedit story grid story.json 並 閱讀 每個 grid_sceneN.jpg 以取得每個角色臉部的 focus 點。在網格上，x 使用黃色標籤，y 使用青色標籤。
3. 撰寫 story.json（完整結構請見 references/story.md）。角色說話時使用近景 shot + focus，旁白時使用廣角或 Ken Burns motion。在場景之間加入 sfx、title、transition: fade 與 music。
4. vedit story voices story.json 合成台詞並印出時間表。檢查節奏（短片通常 ≤ 60 秒）。
5. vedit story build story.json --preview，然後檢查畫面，再執行 vedit story build story.json。

語音：edge 是免費且自然的，無需 API 金鑰。使用 vedit tts --list-voices --lang en 挑選語音（菲律賓語：--lang fil）。僅在使用者擁有金鑰且要求高級語音時，才使用 openai（透過 "style" 進行表演指示）或 elevenlabs。絕不發明真實人物的聲音或模仿真人。

---

E. 事實 Reels 套件（原始照片/片段 → 品牌化事實 Reels）

指南：templates/fact_reels/README.md。新頻道：vedit reels new DIR；新影片：vedit reels story DIR NAME。

1. 查看使用者的原始檔案（片段用 vedit frames clip.mp4）並選擇場景類型：image + 帶旁白的 card、video + lines（B-roll，有旁白，靜音），或 video + 不帶 lines 的 keep_audio: true（使用者直接說話：真實聲音，自動字幕）。從畫面/逐字稿選擇 in/out。
2. 撰寫 story.json：鉤子 → 事實 → 「你知道嗎？」→ 事實 → ... → 評論/分享/關注，約 185 字 ≈ 60 秒，流暢的旁白。對於語音可能誤讀的數字、年份與名稱，使用 say。卡片文字：*星星* = 強調。
3. vedit reels build STORY_DIR --only cards 並 閱讀 卡片與 thumbnail.jpg。修正溢出的文字。
4. vedit reels build STORY_DIR --preview，檢查畫面，然後以最高品質建構。驗證每一項事實；將來源放入 caption.txt。

---

剪輯判斷（如何讓它更好）

• 節奏：對於 YouTube 談話頭像，將停頓縮短至約 0.3–0.45 秒。對於 Shorts，剪得更緊湊（約 0.2–0.3 秒）。在爆點或情緒節拍之後保留呼吸空間（在該片段上設定 "pad": [0.1, 0.6]）。
• 隱藏跳接：交替使用 punch-in（1.0 ↔ 1.10–1.15）或切入 B-roll。在螢幕錄製中，不要對每個剪輯都進行 punch-in，那會損害可讀性。轉為垂直時，改用 "fit": "blur" 或 "pad"。
• 字幕：Shorts/Reels 使用 pop，長片與教學使用 clean，背景雜亂時使用 box。使用 captions.replace 修正品牌名稱與聽錯的詞彙。
• 音訊 佔影片的一半。保持 normalize 開啟（社群/YouTube 為 −14 LUFS）。僅在房間吵雜時設定 denoise: true。將音樂保持在 0.1–0.2 並啟用閃避。
• 務必在視覺上驗證 後才宣告完成，並說明你檢查了什麼。
• 長時間轉譯：先使用 vedit render edl.json --preview --clips 0-10 預覽一個片段。

疑難排解

• Whisper 錯過了填充詞：已提示它保留，但如果仍然遺漏，請使用 --model medium 或根據停頓進行剪輯。
• 語言錯誤：vedit analyze raw.mp4 --language tl（他加祿語）、es 等。
• 字幕字型錯誤：將 captions.font 設定為已安裝的字型（Montserrat、Poppins、Arial），或將 .ttf 檔案放入 SKILL/fonts/。
• 某個片段轉譯失敗：錯誤訊息會指出片段索引。檢查其 in/out 是否超出來源持續時間。
• 最終的 ffmpeg 指令會儲存在 <workdir>/.render_cache/last_final_cmd.txt。