Video Cut

video-cut

從 macOS 照片圖庫自動找素材、用 GPS 與時間還原行程、剪成短片並上字幕配樂。

市面上的剪片工具多半假設「你已經有一支片，告訴我怎麼剪」。這支補的是前面那段： **素材在哪、哪些能用、怎麼分群**。

給 [Claude Code](https://claude.com/claude-code) 用的 skill，也可以把 `scripts/` 裡的 三支腳本當獨立的命令列工具跑。

只支援 macOS

它讀 macOS「照片」App 的圖庫（`~/Pictures/Photos Library.photoslibrary`）， 並用 `sips` 轉 HEIC。Linux 和 Windows 不能用。

需要

brew install ffmpeg
pip3 install Pillow

`sips` 是 macOS 內建。ffmpeg 不需要完整版，這支 skill 不依賴 `drawtext` 或 `subtitles`，字幕是用 Pillow 產 PNG 再 overlay 疊上去的。

安裝

git clone https://github.com/<你的帳號>/video-cut.git ~/.claude/skills/video-cut

最小流程

# 1. 掃素材：去重、按 GPS 與時間分群、讀本機的地名
python3 ~/.claude/skills/video-cut/scripts/scan_library.py --from 2026-06-13 --to 2026-06-13

# 2. 抽格做檢視表，用眼睛選片
python3 ~/.claude/skills/video-cut/scripts/sheets.py videos videos.json --out v
python3 ~/.claude/skills/video-cut/scripts/sheets.py photos photos.json --out p --sample 3

# 3. 寫 edl.json（格式見 SKILL.md），然後渲染
VW=1920 VH=1080 python3 ~/.claude/skills/video-cut/scripts/render.py
ffmpeg -y -f concat -safe 0 -i concat.txt -c copy out.mp4

完整的剪輯表欄位、三種字幕、配樂與雙版本流程都寫在 [SKILL.md](SKILL.md)。

它幫你避開的坑

實際剪過幾十支片累積下來的：

• .mov 的時間戳是 UTC，照片是當地時間。混著排序，影片會全部跑到早上
• originals 裡 96% 的 .mov 是 Live Photo 的 2 秒動態，按副檔名抓片會剪出一團碎片
• 同一支影片可能被匯入兩次（別人 AirDrop 過來的），用時間＋時長＋檔案大小判定重複
• sips 不套 EXIF 方向，照片會倒立，一定要走 ImageOps.exif_transpose
• iPhone 雙擷取的畫中畫會在角落放一個自拍視窗，可以用 crop 裁掉而不必整支放棄
• 渲染偶爾產出截斷的 mp4 而 ffmpeg 回傳 0，合成前要逐段驗證
• 地名讀本機資料庫，不把 GPS 座標送去外部 API

已知限制

• 相依於 Photos.sqlite 的 schema。Apple 改欄位名就可能壞掉 （開發時就遇過 ZTIMEZONEOFFSET 在某些版本不存在）。 跑不動的話先看 scan_library.py 裡的 SQL。
• 原檔要留在本機。iCloud 開了「最佳化 Mac 儲存空間」的話原檔可能不在，剪不了。
• HDR 素材沒有正規的 tone mapping。iPhone 的 HLG 直接轉 8-bit， 實測畫面可接受，要更準的顏色需要有 zscale 的 ffmpeg。
• 分群的距離與時間閾值是經驗值，不同行程要自己調 --gap 和 --dist。

配樂

`references/environment.md` 列了 macOS 內建、授權可用於自己作品的音樂來源 （iMovie 主題音樂、Apple Loops），以及在聽不到聲音時怎麼用波形和頻譜挑曲子。

**不要用來路不明的網路音樂。**

授權

MIT，見 [LICENSE]