vediocut — 逐字稿優先的 AI Vlog 剪輯工具

Open source (MIT). vediocut turns a folder of handheld phone clips into a narrative vlog by understanding what was said first and only then deciding how to cut. Local ASR (whisper.cpp), an LLM correction pass that uses world knowledge instead of hand-built glossaries, chronological “radio-edit” planning, CLIP-based B-roll retrieval with human review, and a deterministic validation gate before rendering. Designed to be driven by Claude Code; macOS only for now. Docs are in Traditional Chinese.

一句話：把一資料夾的手機毛片剪成一支有故事的 Vlog——先聽懂人在說什麼，再決定怎麼剪。

• 逐字稿優先：先轉錄、再規劃故事，關掉畫面只聽聲音也要聽得懂
• 專名還原靠世界知識：不用建詞表，模型從逐字稿自己推斷地區與領域，還原店名、路名的同音誤聽
• 輸出完整成片：1080p、燒錄字幕、配樂自動閃避人聲、片頭精華預告、選用的 B-roll 補畫面
• 每一步都有驗收：EDL 驗證閘、切點能量精修、環境體檢腳本，失敗會大聲說出原因
• 全本地 ASR：素材與聲音不離開你的電腦（校正 pass 可選擇用 API 或 Claude Code）

---

快速開始

需求

⚠ 不要把專案放在 ~/Desktop 或 ~/Documents。若開著 iCloud「桌面與文件」同步， 磁碟吃緊時素材與模型會被清成「有大小、無內容」的佔位檔，流程會在中途莫名失敗。 放 ~/Developer 或外接硬碟。

安裝

brew install ffmpeg-full whisper-cpp

ffmpeg-full 是 keg-only，不會自動加進 PATH，要自己加（寫進 ~/.zshrc 才會保留）：

export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"

git clone https://github.com/leoai123/vediocut-case-study.git ~/Developer/vediocut
cd ~/Developer/vediocut

python3.13 -m venv .venv && .venv/bin/pip install -r requirements.txt

scripts/setup_models.sh

下載 ASR 模型並以官方 checksum 驗證。視覺模型（Chinese-CLIP）會在第一次建索引時自動下載。

scripts/doctor.sh

環境體檢：逐項確認工具、套件、模型都實際可用（不只是存在），出現 ✗ 就先處理。

剪第一支片（用 Claude Code）

1. 把素材放進 footage//（.MOV，檔名不可有空格；可另放一兩首 .mp3 當配樂）

2. 在這個資料夾開啟 Claude Code，說：

   用 vediocut 把 footage/myvlog 剪成一支 vlog

Claude Code 會讀取 .claude/skills/vediocut-flow/SKILL.md， 依十二步流程執行：素材偵察 → 開案 → 抽音訊 → 轉錄 → 校正 → 視覺索引 → 故事規劃 → 驗證 → B-roll → 渲染 → 法醫驗證。每一步過了驗收條件才進下一步。

成片在 output//final.mp4，字幕檔 final.srt。

---

手動執行（不用 Claude Code）

流程裡只有故事規劃需要判斷力，其餘都是指令。以專案 myvlog、素材在 footage/myvlog/ 為例：

scripts/new_project.sh myvlog footage/myvlog daily --lang zh

第三個參數是敘事模板（選用）：food daily travel place unboxing product talking explainer realestate，各模板的適用情境見 templates/。--lang 支援 zh、en。

scripts/prepare_p1_audio.sh myvlog

scripts/transcribe_p1_perfile.sh myvlog

python3 scripts/merge_transcript.py --project myvlog

校正 pass（不可跳過，否則字幕會帶著整片的同音錯字）。有 API key 的話：