From 750ccff58bf86579b7109aa6397233e72d111e6b Mon Sep 17 00:00:00 2001 From: Tuan Nghia Nguyen Date: Wed, 15 Apr 2026 23:51:30 +1000 Subject: [PATCH] Plan ffmpeg migration v1 --- .claude/settings.local.json | 5 +- docs/PLAN_FFmpeg8_MediaClient_Migration.md | 135 ++++++++++++++++++++- 2 files changed, 137 insertions(+), 3 deletions(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index aed92fe..6ba8b40 100644 --- a/.claude/settings.local.json +++ b/.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)" ] } } diff --git a/docs/PLAN_FFmpeg8_MediaClient_Migration.md b/docs/PLAN_FFmpeg8_MediaClient_Migration.md index 856e294..7d0e5cb 100644 --- a/docs/PLAN_FFmpeg8_MediaClient_Migration.md +++ b/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 . +Phases 1 through are already done. Walk me through Phase +step by step. After each file edit, pause and let me compile. After Phase + 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/.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.