media-folder-compare

比對兩個資料夾的媒體檔案內容，找出來源資料夾中已存在於參考資料夾的檔案，並將其移至 exists_in_photos/ 子目錄。

比對方式

採用兩階段比對策略：

階段	方法	說明
Phase 1	SHA256 精確比對	快速路徑，逐位元組完全一致
Phase 2a	圖片 pHash	感知雜湊，容許重新壓縮/調整尺寸（Hamming distance ≤ 閾值）
Phase 2b	影片 pHash	duration 篩選 + 5 幀取樣平均相似度比對

支援格式

• 圖片：jpg, jpeg, png, gif, bmp, heic, heif, webp, tiff, tif
• 影片：mp4, mov, avi, mkv, 3gp, m4v, wmv, mpg, mpeg, mts

安裝

pip install -r requirements.txt

影片 pHash 比對（Phase 2b）需要額外安裝 ffmpeg：

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

若未安裝 ffmpeg，程式仍可執行，僅跳過影片 pHash 比對。

使用方式

# 預覽模式（僅比對，不移動檔案）
python3 media_folder_compare.py <source_dir> <reference_dir> --dry-run

# 僅 SHA256 比對
python3 media_folder_compare.py <source_dir> <reference_dir> --sha256-only

# 完整比對並移動檔案
python3 media_folder_compare.py <source_dir> <reference_dir>

參數說明

參數	說明
source_dir	待比對的來源資料夾（符合的檔案會從此移出）
reference_dir	參考資料夾（用來比對是否已存在）
--base-dir	快取與報告輸出目錄（預設為當前目錄）
--dry-run	預覽模式，僅比對不實際移動
--sha256-only	僅使用 SHA256 比對，跳過 pHash
--phash-threshold	圖片 pHash Hamming distance 門檻（預設 3）
--video-similarity	影片幀相似度門檻（預設 0.95）
--workers	multiprocessing worker 數量（預設自動偵測）
-v, --verbose	顯示詳細輸出（DEBUG 層級）
-q, --quiet	僅顯示警告與錯誤

輸出

• 符合的檔案移至 <source_dir>/exists_in_photos/，保留原始相對路徑結構
• 比對報告寫入 <base_dir>/existing_in_photos_report.txt
• 快取檔案（JSON）存於 <base_dir>/，加速後續重複執行

相依套件

• imagehash - 感知雜湊計算
• numpy - 向量化 Hamming distance
• Pillow - 圖片處理
• pillow-heif - HEIC/HEIF 格式支援
• ffmpeg（選用）- 影片幀擷取與 duration 取得