# Reviewer 審查 M8-3 ffmpeg LGPL 切換（2026-04-15）

對照文件：
- TDD spec：`/Users/jimchen/visionA/local-tool/.autoflow/04-architecture/v2/ffmpeg-lgpl.md`
- Research：`/Users/jimchen/visionA/local-tool/.autoflow/04-architecture/ffmpeg-lgpl-research.md`
- BUILD.md：`/Users/jimchen/visionA/local-tool/vendor/ffmpeg/macos/BUILD.md`

---

## 摘要

| 項目 | 結論 |
|------|------|
| 總結論 | ✅ 通過（1 Minor + 2 Suggestion + 3 待處理事項） |
| LGPL 合規 | ✅ 三平台齊備（macOS 自 build decoder-only；Windows/Linux BtbN n7.1 LGPL） |
| Binary 大小減量 | ✅ macOS 77 MB → 11.32 MB（含 ffprobe），減量約 85% |
| 阻擋 M8-10？ | ❌ 不阻擋，所有硬性條件均通過 |

---

## A. Makefile 變更正確性

對照 `Makefile:1-449` ↔ TDD §2.3/§3/§4，18 項檢查全過：

| # | 驗證項 | 結果 | 位置 |
|---|-------|------|------|
| 1 | `FFMPEG_VERSION=n7.1` + sha256 常數 | ✅ | `Makefile:73-77` |
| 2 | `vendor-ffmpeg` 退化為「驗證存在 + LGPL guard」 | ✅ | `Makefile:112-130` |
| 3 | `vendor-ffmpeg-macos-build` 僅限 Darwin + `nasm`/`yasm` | ✅ | `Makefile:136-140` |
| 4 | 下載 tarball + sha256 驗證 + fail 印實際 sha | ✅ | `Makefile:142-148` |
| 5 | configure 21 個 flag 與 TDD §2.3 逐字對齊 | ✅ | `Makefile:152-178` |
| 6 | `--disable-everything` + decoder 白名單 h264/hevc/mpeg1/2video/mpeg4/mjpeg/prores/vp8/vp9/aac/mp2/mp3/pcm_* | ✅ | `Makefile:167` |
| 7 | demuxer 白名單 mov,avi,mpegps,mpegts,matroska,image2 | ✅ | `Makefile:166` |
| 8 | strip + ad-hoc codesign | ✅ | `Makefile:184-189` |
| 9 | build 後 LGPL grep guard | ✅ | `Makefile:190-193` |
| 10 | 複製 COPYING.LGPLv3 | ✅ | `Makefile:194-195` |
| 11 | `FFMPEG_URL_WINDOWS` → BtbN n7.1 LGPL zip | ✅ | `Makefile:277` |
| 12 | `FFMPEG_URL_LINUX` → BtbN n7.1 LGPL tar.xz | ✅ | `Makefile:387` |
| 13 | `vendor-ffmpeg-windows` 解壓 ffmpeg.exe + ffprobe.exe + LICENSE + COPYING.LGPLv3 | ✅ | `Makefile:319-348` |
| 14 | `vendor-ffmpeg-linux` 解壓 ffmpeg + ffprobe + LICENSE，`strip-components=1` | ✅ | `Makefile:417-434` |
| 15 | `payload-macos` 複製 ffmpeg + ffprobe + ffmpeg-COPYING.LGPLv3 | ✅ | `Makefile:244-247` |
| 16 | `payload-windows` 複製 ffprobe.exe + LICENSE/COPYING（skipifsourcedoesntexist） | ✅ | `Makefile:358-362` |
| 17 | `payload-linux` 複製 ffprobe + ffmpeg-LICENSE.txt | ✅ | `Makefile:444-446` |
| 18 | `payload-macos:241` 有 `rm -rf payload/darwin` 清舊 | ✅ | `Makefile:241` |

**五 decoder + 五 demuxer 白名單對照 TDD 驗收條件 §10**（h264/hevc/mpeg2video/mpeg4/aac；mov-mp4/avi/mpeg/mpegts/matroska）：全數涵蓋。

---

## B. Binary 正確性（親自驗證）

```
$ ls -la vendor/ffmpeg/macos/
-rw-r--r--   10500 BUILD.md
-rw-r--r--    7651 COPYING.LGPLv3
-rwxr-xr-x 6007520 ffmpeg    (5.73 MB)
-rwxr-xr-x 5865568 ffprobe   (5.59 MB)
```

**sha256 與 BUILD.md `lines 26-30` 100% 吻合**：
```
c3cb9f1dad66730267c12fca92c6344d2f8939ab227889caac33005f8947992c  ffmpeg
bd388fb4372ed5f7e44ee331a51be6383d702fb2c067bf562cabbdfbdd8b0c5e  ffprobe
da7eabb7bafdf7d3ae5e9f223aa5bdc1eece45ac569dc21b3b037520b4464768  COPYING.LGPLv3
```

**`ffmpeg -version` configuration**：
- ✅ 無 `--enable-gpl`、無 `libx264`、無 `libx265`
- ✅ 有 `--enable-version3`、`--disable-network`、`--disable-autodetect`、`--enable-static`、`--disable-everything`

**Decoder 驗證**：`ffmpeg -decoders | grep -E ' (h264|hevc|aac|mpeg2video|mpeg4) '` 五個全中。

**Demuxer 驗證**：`ffmpeg -demuxers` 顯示 `avi` / `matroska,webm` / `mov,mp4,m4a,3gp,3g2,mj2` / `mpeg` / `mpegts` 五個全中。

**`otool -L` 動態依賴**：
```
/usr/lib/libSystem.B.dylib
/System/Library/Frameworks/CoreFoundation.framework/.../CoreFoundation
/System/Library/Frameworks/CoreVideo.framework/.../CoreVideo
/System/Library/Frameworks/CoreMedia.framework/.../CoreMedia
```
ffprobe 相同四項。**無任何第三方 dylib**（x264/x265/vpx/opus/aom 都不在），符合 LGPL static self-contained。

**`ffprobe -version`**：可執行，顯示同一 configuration。

**`codesign -v`**：ffmpeg + ffprobe 皆 exit 0（ad-hoc signing 通過）。

---

## C. .gitignore 雙層

**Inner `local-tool/.gitignore:6-15`**：
```
/vendor/**
!/vendor/.gitkeep
!/vendor/README.md
!/vendor/ffmpeg/
!/vendor/ffmpeg/macos/
!/vendor/ffmpeg/macos/**
```

**Outer `visionA/.gitignore:20-27`**：同樣四行 un-ignore + `local-tool/vendor/**` 為基底。

`git check-ignore` 驗證：

| 路徑 | inner repo | outer repo |
|------|-----------|-----------|
| `vendor/ffmpeg/macos/ffmpeg` | exit 1（未 ignore ✅） | exit 1 ✅ |
| `vendor/ffmpeg/macos/BUILD.md` | exit 1 ✅ | exit 1 ✅ |
| `vendor/ffmpeg/windows/ffmpeg.exe` | exit 0（ignored ✅） | exit 0 ✅ |
| `vendor/ffmpeg/linux/ffmpeg` | exit 0 ✅ | exit 0 ✅ |

`git status --ignored vendor/` 顯示：
- `?? vendor/ffmpeg/macos/`（untracked，待 `git add`）
- `!! vendor/ffmpeg/{linux,windows}/`、`!! vendor/{python,wheels,yt-dlp}/`（ignored）

雙層規則正確；outer repo `local-tool/vendor/` 仍為整個 untracked，需在交付前 `git add` — 屬待處理事項而非實作錯誤。

---

## D. BUILD.md 可重現性

BUILD.md（295 行）完整度：

| 欄位 | 有無 |
|------|------|
| ffmpeg release n7.1 + source URL + sha256 | ✅ |
| Build host（macOS 14.7.6，Apple clang 16.0.0） | ✅ |
| Toolchain（nasm 3.01、brew 5.1.6、Xcode CLT） | ✅ |
| Configure flags 完整複製貼上 | ✅ |
| Binary sha256（三項） | ✅ |
| Binary 大小（bytes + 人類可讀） | ✅ |
| Build 耗時（2 分 44 秒，user 559s/sys 56s） | ✅ |
| 實測驗證輸出（ffmpeg -version / decoder / demuxer / otool / codesign 節錄） | ✅ |
| Rebuild 指令 `make vendor-ffmpeg-macos-build` | ✅ |
| Commit 清單（僅允許 ffmpeg/ffprobe/COPYING/BUILD.md 四檔） | ✅ |

**兩年後重現評估**：可以。source tarball URL + sha256 固定、configure flags 可直貼、系統依賴明列、Makefile 本身就是 reproducibility script。唯一風險是 Homebrew nasm/clang 版本漂移，但 ffmpeg 7.1 對 toolchain 包容度高，不預期 break。

---

## E. GPL flag 清除 grep

全 repo grep `VISIONA_ALLOW_GPL_FFMPEG` / `--enable-gpl` / `libx264` / `libx265`：

| 類別 | 殘存位置 | 評估 |
|------|---------|------|
| `.autoflow/*`（progress/TDD/research/spec） | 允許（歷史紀錄） | ✅ |
| `Makefile:126,190-193` | guard 驗證邏輯 | ✅ |
| `vendor/ffmpeg/macos/BUILD.md` | 驗證輸出說明 | ✅ |
| `build/ffmpeg-macos/src/*` | upstream source tarball 解壓產物 | ✅（非專案碼） |
| `scripts/bootstrap-{windows,linux}.*` | 已改為 `LGPL v3 build` 標語 | ✅ |
| `.github/workflows/build.yml` | 零殘留 | ✅ |
| `installer/**` | 零殘留 | ✅ |
| `server/**.go` + `visiona-local/**.go` | 零殘留 | ✅ |

**GPL flag 完全清除**，只剩文件類歷史 + guard 邏輯。

---

## F. Installer / Bootstrap / CI

- **Windows Inno Setup** `installer/windows/visiona-local.iss:74-79`：含 ffmpeg.exe + ffprobe.exe + ffmpeg-LICENSE.txt + ffmpeg-COPYING.LGPLv3（後兩者用 `skipifsourcedoesntexist` fallback）✅
- **Linux AppImage** `installer/linux/build-appimage.sh:61-76`：`for tool in ffmpeg ffprobe` 迴圈 + 把 ffmpeg-LICENSE.txt 放到 `AppDir/usr/share/doc/visiona-local/` ✅
- **macOS**：無獨立 installer，payload-macos 直接把 COPYING.LGPLv3 複製到 `payload/darwin/bin/ffmpeg-COPYING.LGPLv3`，經 stage-macos 進 `.app/Contents/Resources/bin/` ✅
- **bootstrap-windows.ps1:71 / bootstrap-linux.sh:58**：只剩 LGPL 提示語，無 GPL flag ✅
- **`.github/workflows/build.yml`**：只保留 `vendor-ffmpeg-windows`（line 135）和 `vendor-ffmpeg-linux`（line 232）呼叫，無 env var 設定 ✅

---

## G. Payload 流程相容性 + 真實 decode 測試

### G.1 server runtime 相容性

`server/main.go:88-93` 把 `VISIONA_BUNDLE_BIN_DIR` prepend 到 PATH；`server/internal/deps/checker.go:23-94` 的 `resolveTool` 優先在 `$VISIONA_BUNDLE_BIN_DIR/<name>` 找；`visiona-local/app.go:482-484` Wails shell 啟動 server 時注入 `VISIONA_BUNDLE_BIN_DIR = locateBundleBinDir()`（macOS→`Contents/Resources/bin`，Windows/Linux→`<exe>/bin`，開發→`cwd/payload/<os>/bin`）。

payload-macos `Makefile:244-245` 把 `ffmpeg` + `ffprobe` 放到 `payload/darwin/bin/`，stage-macos 會完整複製到 bundle Resources。`server/internal/camera/video_source.go:24` 的 `exec.Command("ffprobe", ...)` 依賴 basename lookup，加入 ffprobe 後完全相容。✅

### G.2 實際 decode 測試

先用系統 ffmpeg 產生 h264 mp4：`/usr/local/bin/ffmpeg -f lavfi -i "testsrc=duration=1:size=320x240:rate=10" -c:v libx264 ... /tmp/testsrc.mp4`。

LGPL ffmpeg 解碼 → mjpeg：
```
$ ./vendor/ffmpeg/macos/ffmpeg -i /tmp/testsrc.mp4 \
    -frames:v 1 -f image2pipe -vcodec mjpeg -q:v 5 /tmp/test_out.jpg
Stream #0:0(und): Video: mjpeg, yuv444p, 320x240, 10 fps ...
frame=    1 fps=0.0 q=5.0 Lsize=       9KiB
$ file /tmp/test_out.jpg
/tmp/test_out.jpg: JPEG image data, JFIF standard 1.02, ..., 320x240
```

LGPL ffprobe probe h264 stream：
```
$ ./vendor/ffmpeg/macos/ffprobe -v error -show_streams /tmp/testsrc.mp4
codec_name=h264  codec_type=video  width=320  height=240  pix_fmt=yuv444p
```

**真實 decode 路徑通過**，server extract first-frame 流程可直接使用。

### G.3 `payload/darwin/bin/` 當前為舊 GPL 77 MB binary

```
$ shasum -a 256 payload/darwin/bin/ffmpeg
b68f795f7fb4528daf697f57a2b6780846a1ae762a71907e994442ad103ee88f
```

**非 M8-3 實作錯誤**：payload-macos 尚未在 M8-3 後重跑。`Makefile:241` 的 `rm -rf payload/darwin` 與 `stage-macos:265` 的 `rm -rf visiona-local/build/darwin/Resources` 會自動清乾淨。列入待處理。

---

## H. Size 比較

| 項目 | 舊 GPL | 新 LGPL | 差異 |
|------|-------|--------|------|
| macOS ffmpeg | ~77 MB（progress.md M6-1 紀錄） | **5.73 MB** | −71.3 MB（−92%） |
| macOS ffprobe | 未附 | **5.59 MB** | 新增 |
| macOS 合計 | ~77 MB | **11.32 MB** | **−65.7 MB（−85%）** |

macOS 成果超越 TDD §2.1「~20 MB」目標，`--disable-everything` + 白名單策略效益顯著。Windows/Linux BtbN LGPL build 大小待 M8-10 CI runner 下載後驗證。

---

## I. 問題清單

### Critical / Major

無。

### Minor

| # | 位置 | 問題 | 建議 |
|---|------|------|------|
| 1 | `vendor/ffmpeg/macos/BUILD.md:186-194` §Verification §5 | 預期 `spctl --assess --verbose` 為「accepted」不準確：實測 ad-hoc signed binary 在 macOS 14.7 下被 `rejected`（exit 3）。Gatekeeper 由 outer `.app` bundle signing 決定，不對內嵌 binary 單獨 assess | 把該步驟改為 `codesign -v`（exit 0 即可），並註記「Gatekeeper 最終由 outer `.app` bundle signing 決定」 |

### Suggestion

| # | 位置 | 建議 |
|---|------|------|
| 1 | `Makefile:126-130` `vendor-ffmpeg` target | 可多驗 `shasum -a 256` 對照 BUILD.md 記錄，防 binary 被意外覆蓋 / 損毀（非必要，git 已保護） |
| 2 | `Makefile:361-362` payload-windows | 兩份授權檔都用 `skipifsourcedoesntexist`，若 BtbN zip 內 LICENSE.txt 與 COPYING.LGPLv3 同時缺失，installer 會無授權檔交付。建議補「至少其中一個存在」assertion |

### 待處理（非 M8-3 scope，但影響 release）

1. **outer repo `git add`**：`/Users/jimchen/visionA/` 的 `git status` 仍顯示 `local-tool/vendor/` 為整個 untracked。交付前須 `git add local-tool/vendor/ffmpeg/macos/{ffmpeg,ffprobe,COPYING.LGPLv3,BUILD.md}` 並 commit。
2. **`payload/darwin/bin/ffmpeg` 仍為舊 GPL 77 MB binary**：下次 `make payload-macos` 會自動清。M8-10 前應重跑。
3. **`vendor/yt-dlp/` 目錄仍在**：屬 M8-2 清理範圍，非 M8-3。

---

## J. 結論

**M8-3 ffmpeg LGPL 切換：✅ 通過。**

核心成果確認：
- Makefile 三平台變更逐字對齊 TDD §2-§4
- macOS binary 親測 LGPL 合規（無 gpl/x264/x265，有 version3）、五 decoder + 五 demuxer 全中、只依賴 macOS 系統 framework
- sha256 與 BUILD.md 100% 吻合
- 實測 h264 mp4 decode → mjpeg JPEG 成功；ffprobe probe 成功
- 雙層 `.gitignore` inner + outer 規則均正確
- BUILD.md 完整可重現（兩年後可 rebuild）
- GPL flag 在程式碼 / installer / bootstrap / CI 完全清除
- Installer Windows/Linux 含 ffprobe + 授權檔
- Size 減量 85%

**僅 1 Minor（BUILD.md 的 spctl 預期描述錯誤）+ 2 Suggestion + 3 待處理事項，不阻擋 M8-10。**

Orchestrator 建議：
1. Minor #1（BUILD.md spctl 描述修正）列為 M8-3 尾巴，由 Architect/DevOps 補
2. M8-10 CI 交付前執行 outer repo `git add` + commit
3. M8-10 時確保 `make payload-macos` + `stage-macos` 重跑清掉舊 GPL payload