Plan ffmpeg migration v1
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user