Plan ffmpeg migration v1

.claude/settings.local.json

@@ -169,7 +169,10 @@
       "Bash(\"C:/ANSLibs/ffmpeg-n8.1/bin/ffmpeg.exe\" -version)",
       "Bash(\"C:/ANSLibs/ffmpeg-n8.1/bin/ffmpeg.exe\" -hide_banner -encoders)",
       "Bash(find \"C:/Projects/CLionProjects/ANSCORE/MediaClient\" -name \"*.h\" -exec grep -l \"AVFrame\\\\|AVCodec[A-Z]\\\\|AVFormatContext\\\\|AVPacket\\\\|AVStream\\\\b\" {} \\\\;)",
-      "Bash(grep -l \"AVFrame\\\\|AVCodecContext\\\\|AVFormatContext\\\\|AVPacket\\\\|AVStream\" \"C:/Projects/CLionProjects/ANSCORE/MediaClient/media/\"*.h)"
+      "Bash(grep -l \"AVFrame\\\\|AVCodecContext\\\\|AVFormatContext\\\\|AVPacket\\\\|AVStream\" \"C:/Projects/CLionProjects/ANSCORE/MediaClient/media/\"*.h)",
+      "Bash(\"C:/ANSLibs/ffmpeg-n8.1/bin/ffmpeg.exe\" -hide_banner -decoders)",
+      "Bash(\"C:/ANSLibs/ffmpeg-n8.1/bin/ffmpeg.exe\" -hide_banner -protocols)",
+      "Bash(\"C:/ANSLibs/ffmpeg-n8.1/bin/ffmpeg.exe\" -hide_banner -formats)"
     ]
   }
 }

docs/PLAN_FFmpeg8_MediaClient_Migration.md

@@ -1,10 +1,78 @@
 # PLAN — Migrate MediaClient (and ANSCV) from FFmpeg 4.0.2 to FFmpeg 8.1
 
-**Status:** Not started
+**Status:** Approved, ready to execute (not yet started)
 **Target FFmpeg:** n8.1 LGPL shared (`C:/ANSLibs/ffmpeg-n8.1`)
 **Current FFmpeg:** 4.0.2 GPL shared (`C:/Projects/CLionProjects/ANSCORE/MediaClient/ffmpeg`)
 **Estimated effort:** 1–2 focused days of editing + retesting all audio/video paths
 **Risk:** Medium (touches ~10 MediaClient files, audio channel-layout migration is fiddly)
+**Owner:** Tuan Nghia Nguyen
+**Branch to create:** `ffmpeg-8-migration`
+
+### Decisions already made (do not re-litigate)
+
+These were debated and settled in the planning conversation. A new session should treat these as fixed:
+
+1. **Chose LGPL over GPL.** The current FFmpeg 4.0.2 is GPL (has `libpostproc` + `libx265` + `libx264`), which makes `ANSCV.dll` a derivative work of GPL software — incompatible with closed-source commercial distribution. The LGPL build at `C:/ANSLibs/ffmpeg-n8.1` resolves this. Verified by reading `LICENSE.txt` (LGPL v3) and the `ffmpeg.exe -version` configure string (no `--enable-gpl`, explicit `--disable-libx264 --disable-libx265`).
+2. **Chose FFmpeg 8.1 over 6.1 or 7.1.** Latest stable, all features available, fully modern NVENC. Trade-off accepted: more API breakage from the 4.0 → 8.1 jump, but the migration plan covers it explicitly.
+3. **Chose Option B (port MediaClient) over Option C (subprocess to `ffmpeg.exe`).** Option C was the lower-effort alternative — invoke `ffmpeg.exe` as a child process from a new C++ function, leaving MediaClient on FFmpeg 4.0. We're not doing that; we're doing the full library-level migration so the *whole* project benefits (RTSP, RTMP, file player, video player, etc.), not just the image-encoder code paths.
+4. **Bundle source: BtbN GitHub releases.** `ffmpeg-n8.1-latest-win64-lgpl-shared-8.1.zip`. MSVC-compatible `.lib` import libraries verified by inspection.
+5. **Software decoders (h264, hevc) will continue to be used for RTSP.** Hardware decode (NVDEC/QSV/AMF) is out of scope for this migration — it's a separate optional enhancement after the migration is stable.
+
+### Pre-work already completed (do NOT redo)
+
+- ✅ `cmake/Dependencies.cmake` lines 168–178: `postproc.lib` removed from the Windows and Linux link lists. (LGPL builds don't have libpostproc.)
+- ✅ New FFmpeg bundle downloaded, extracted, and verified at `C:/ANSLibs/ffmpeg-n8.1`. License confirmed LGPL v3. Encoder list confirmed to include `hevc_nvenc`, `h264_nvenc`, `av1_nvenc`, `hevc_qsv`, `h264_qsv`, `av1_qsv`, `hevc_amf`, `h264_amf`, `av1_amf`, `libsvtav1`, `libopenh264`, `mpeg4`. Decoder list confirmed to include `h264`, `hevc`, `mjpeg`, `mpeg4`, `mpeg2video`, `vp8`, `vp9`, `av1`.
+- ✅ New ANSCV functions exist in `modules/ANSCV/ANSOpenCV.{h,cpp}` and use modern FFmpeg APIs that are compatible with both 4.0 and 8.1:
+    - `ANSCENTER::ANSOPENCV::ImagesToMP4FF` (software-only direct libav* encoder)
+    - `ANSCENTER::ANSOPENCV::ImagesToMP4HW` (hardware-first direct libav* encoder)
+    - `ANSCENTER::ANSOPENCV::ImagesToMP4` (legacy OpenCV `VideoWriter` path — DO NOT MODIFY)
+- ✅ Three new C exports declared and implemented:
+    - `ANSCV_ImagesToMP4FF_S`
+    - `ANSCV_ImagesToMP4HW_S`
+    - `ANSCV_PrintFFmpegLicense_S` (used during Phase 5 to verify LGPL status post-migration)
+- ✅ Unit test wired up to call `ANSCV_PrintFFmpegLicense_S()` in `main()` of `tests/ANSCV-UnitTest/ANSCV-UnitTest.cpp`.
+
+---
+
+## Quick Start for a new session
+
+If you're a fresh Claude session and the user has asked you to execute this migration, do the following BEFORE making any edits:
+
+1. **Read this entire document end-to-end**, including the appendices. Don't skim — the details matter, especially the API change reference in section 3.2 and the per-file checklist in Appendix A.
+2. **Confirm the current state matches what's documented in section 3.** Specifically run:
+   ```bash
+   ls "C:/ANSLibs/ffmpeg-n8.1/"                          # verify bundle present
+   ls "C:/Projects/CLionProjects/ANSCORE/MediaClient/ffmpeg/lib/x64/"  # verify old FFmpeg present
+   git status                                              # current branch and uncommitted state
+   ```
+3. **Verify the pre-work is still done** — open `cmake/Dependencies.cmake` lines 168–178 and confirm `postproc.lib` is absent from the link list (it should already be removed). Open `modules/ANSCV/ANSOpenCV.cpp` and grep for `ImagesToMP4FF` and `ImagesToMP4HW` to confirm those functions still exist.
+4. **Ask the user which phase to start with.** First-time execution: start with Phase 1.1 (branch creation). If resuming a partial migration, ask which phase was last completed and start from the next one.
+5. **Use the TodoWrite tool** to track progress through the phases. The five-phase structure is the natural top-level todo list. Mark each phase complete only when its acceptance criteria are met.
+6. **Work in small, verifiable increments.** Edit one file at a time. After each meaningful edit, ask the user to compile and report errors. Do not batch up edits across multiple files before verifying any of them.
+7. **Treat the audio channel-layout migration in section 3.2.3 as the highest-risk part.** Spend extra care on `audio_decoder.cpp` and `audio_encoder.cpp`. After porting them, ask the user to manually verify audio playback before moving on — broken audio is the most likely silent failure mode.
+8. **Do not modify `ANSCENTER::ANSOPENCV::ImagesToMP4`** (the legacy OpenCV `VideoWriter` path). The user explicitly asked for it to be preserved as-is.
+
+### How to invoke this plan in a new session
+
+The user can paste any of these to start:
+
+> "Read `docs/PLAN_FFmpeg8_MediaClient_Migration.md` and walk me through executing it phase by phase. Start with Phase 1, ask me to confirm before moving to the next phase."
+
+> "Continue the FFmpeg 8 migration. Read `docs/PLAN_FFmpeg8_MediaClient_Migration.md` first, then ask me what's been done so far."
+
+> "Execute Phase 3 of the migration plan in `docs/PLAN_FFmpeg8_MediaClient_Migration.md`. I've already finished Phases 1 and 2."
+
+### Context the new session might need that isn't in this plan
+
+- **Build system:** CLion 2026.1 with the bundled CMake (`C:\Users\nghia\AppData\Local\Programs\CLion 2026.1\bin\cmake\win\x64\bin\cmake.exe`). Build directory: `cmake-build-release`. Generator: Ninja.
+- **Compiler:** MSVC 2022 (`v144` toolchain).
+- **OS:** Windows 11 Pro.
+- **Shell:** bash (Git Bash / MSYS).
+- **Project root:** `C:/Projects/CLionProjects/ANSCORE` (also the git working tree).
+- **Runtime DLL deployment directory:** `C:/Projects/SharedCore/`. This directory is shared with other binaries; **do NOT delete the existing `avcodec-58.dll` / `-59.dll` sets** — other ANSCENTER products may still depend on them.
+- **There is no system FFmpeg on PATH** — only the bundled ones in `MediaClient/ffmpeg/` (current) and `C:/ANSLibs/ffmpeg-n8.1/` (target).
+- **CUDA 13.1** is installed (`C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v13.1/`). This is the reason the FFmpeg 4.0.2 NVENC wrapper fails — it predates the modern NVENC ABI by years.
+- **The user previously confirmed** the new bundle works at the CLI level: `ffmpeg.exe -version`, `-encoders`, and `-decoders` all run cleanly. Hardware encoder support depends on the test machine's GPU; the migration itself works regardless.
 
 ---
 
@@ -905,4 +973,67 @@ dumpbin /dependents cmake-build-release/lib/ANSCV.dll | grep -i "av\|sw\|postpro
 
 ---
 
-**End of plan. Last updated when initial draft was written. Update as the migration progresses with notes about anything discovered along the way.**
+## Appendix E — Copy-paste prompts for a new Claude session
+
+These are ready-to-paste prompts. Pick the one that matches your situation.
+
+### Starting from scratch (Phase 1)
+
+```
+Read docs/PLAN_FFmpeg8_MediaClient_Migration.md end-to-end, including all
+appendices. Then verify the pre-work in the "Pre-work already completed"
+section is still in place: check that postproc.lib is absent from
+cmake/Dependencies.cmake link list, and that ImagesToMP4FF / ImagesToMP4HW /
+ANSCV_PrintFFmpegLicense_S exist in modules/ANSCV/ANSOpenCV.cpp.
+
+Once verified, start Phase 1.1 — create the ffmpeg-8-migration branch and
+back up the current MediaClient/ffmpeg/ tree. Walk me through each phase
+step by step, asking me to confirm before moving to the next phase. Use the
+TodoWrite tool to track progress through the five phases.
+
+Do NOT modify ANSCENTER::ANSOPENCV::ImagesToMP4 (the legacy OpenCV
+VideoWriter path) — it is preserved as-is by explicit user request.
+```
+
+### Resuming a partial migration
+
+```
+Read docs/PLAN_FFmpeg8_MediaClient_Migration.md end-to-end. Then ask me
+which phase was last completed so we can pick up from there. Verify the
+state of any files that should already be modified by running git diff
+against main.
+
+Use TodoWrite to track remaining phases. Work in small verifiable steps
+and ask me to compile after each meaningful edit.
+```
+
+### Just executing one specific phase
+
+```
+Read docs/PLAN_FFmpeg8_MediaClient_Migration.md, focusing on Phase <N>.
+Phases 1 through <N-1> are already done. Walk me through Phase <N>
+step by step. After each file edit, pause and let me compile. After Phase
+<N> is complete and verified, stop — do NOT proceed to the next phase
+without explicit confirmation.
+```
+
+### Just porting one specific MediaClient file
+
+```
+Read docs/PLAN_FFmpeg8_MediaClient_Migration.md sections 3.1 and 3.2
+(API change reference). Then port MediaClient/media/<filename>.cpp to
+the FFmpeg 8.1 API. Show me each change as a diff before applying it.
+After all edits in this file are applied, ask me to compile and report
+errors before moving to the next file.
+```
+
+---
+
+**End of plan.**
+
+This document was authored before any execution work began. It captures the planning
+discussion in full so that a new Claude session can pick up the work without seeing
+the original conversation. Update this document as the migration progresses — record
+what was discovered, what surprised you, what additional fixes were needed beyond
+the cataloged ones — so the next maintainer (whether human or another Claude session)
+can learn from your experience.