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.
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.
ANSCORE's `ANSCV.dll` currently links against a **2018-era FFmpeg 4.0.2** vendored at `MediaClient/ffmpeg/`. This is causing two concrete problems:
1.**Hardware encoders don't work.** The NVENC wrapper in FFmpeg 4.0 predates the modern `NV_ENC_PRESET_CONFIG_VER` struct version that current NVIDIA drivers (CUDA 13.x era) expect. `avcodec_open2()` for `hevc_nvenc` / `h264_nvenc` fails with `unsupported param (12)` regardless of which preset/options we pass.
2.**License entanglement.** The current FFmpeg build was compiled with `--enable-gpl` (it includes `libpostproc`, `libx265`, `libx264`). That makes `ANSCV.dll` a derivative work of GPL software, which is incompatible with closed-source commercial distribution.
A newer LGPL-only FFmpeg has been downloaded and verified at `C:/ANSLibs/ffmpeg-n8.1/`. It includes:
- All hardware encoders we want: `hevc_nvenc`, `hevc_qsv`, `hevc_amf`, `h264_*`, **and `av1_nvenc`/`av1_qsv`/`av1_amf`** (AV1 hardware encoding for RTX 40+ / Arc / RX 7000+).
- License: **LGPL v3** (verified in `C:/ANSLibs/ffmpeg-n8.1/LICENSE.txt` and via the configure string in `ffmpeg.exe -version`).
Migrating to this build resolves both problems but requires porting MediaClient's C++ code, which uses several FFmpeg APIs that have been removed across the 4.0 → 8.1 jump (5 major versions).
## 2. Goals and acceptance criteria
The migration is complete when **all** of the following are true:
1.`ANSCV.dll` builds clean with no errors and no new warnings against `C:/ANSLibs/ffmpeg-n8.1` headers/libs.
2.`MediaClient/ffmpeg/` is removed from the source tree (no longer referenced).
3.`cmake/Dependencies.cmake` points at `C:/ANSLibs/ffmpeg-n8.1/`.
4. The new FFmpeg DLLs (`avcodec-62.dll`, `avformat-62.dll`, `avutil-60.dll`, `swresample-6.dll`, `swscale-9.dll`, `avfilter-11.dll`, `avdevice-62.dll`) are deployed alongside `ANSCV.dll` runtime location (currently `C:/Projects/SharedCore/`).
5.`ANSCV_PrintFFmpegLicense_S()` prints `LGPL version 2.1 or later` (or v3) for all four libraries.
6.**`ANSCV_ImagesToMP4HW_S()` successfully encodes via `hevc_nvenc`** (or `av1_nvenc` if the GPU is RTX 40+) — the `[FF-HW] Using encoder:` log line shows a hardware encoder, not a software fallback. NO MORE `unsupported param (12)` errors.
Note: `C:/Projects/SharedCore/` also already contains `avcodec-59.dll`, `avformat-59.dll`, `avutil-57.dll` from another consumer using FFmpeg 5.x. **Leave these in place.** The new FFmpeg 8.1 DLLs use yet different major versions (avcodec-62, avformat-62, avutil-60) so all three sets coexist cleanly — Windows DLL loader picks by exact filename.
### 3.2 New FFmpeg bundle (verified)
```
C:/ANSLibs/ffmpeg-n8.1/
├── LICENSE.txt ← LGPL v3, ship this with releases
Encoders NOT available (LGPL build excludes them):
-`libx264`, `libx265`, `libxvid`, `libxavs2`
### 3.3 CMake setup
`cmake/Dependencies.cmake` lines 150–180 define the `ffmpeg` interface library. As of the start of this plan, line ~171 has **already had `postproc.lib` removed** in anticipation of switching to LGPL. The link list currently reads:
### 3.4 ANSCV functions added in preparation for this migration
These already exist in `modules/ANSCV/ANSOpenCV.{h,cpp}` and use **modern FFmpeg APIs** (`avcodec_send_frame`, `avcodec_receive_packet`, `av_packet_alloc`, `av_frame_alloc` with `av_frame_get_buffer`, `AVChannelLayout`-free since they're video-only). They will compile against FFmpeg 8.1 unchanged — but their encoder probe lists hardcode `libx265`/`libx264` which are not in the LGPL build and need updating. See Phase 4.
| Class method | C export | Path |
|---|---|---|
| `ANSCENTER::ANSOPENCV::ImagesToMP4` | `ANSCV_ImagesToMP4_S` | OpenCV `VideoWriter` (legacy, do NOT touch) |
| `ANSCENTER::ANSOPENCV::ImagesToMP4FF` | `ANSCV_ImagesToMP4FF_S` | Direct libav*, software-only |
| `ANSCENTER::ANSOPENCV::ImagesToMP4HW` | `ANSCV_ImagesToMP4HW_S` | Direct libav*, hardware-first |
| 5 | Deploy DLLs, run end-to-end tests, validate license | All acceptance criteria met |
Each phase produces an artifact you can inspect before moving on. **Do not skip phases or merge them.** The migration risk comes from doing them all at once and not knowing where a failure originated.
---
## Phase 1 — Preparation
### 1.1 Branch
```bash
cd C:/Projects/CLionProjects/ANSCORE
git checkout -b ffmpeg-8-migration
git status # should be clean except for any uncommitted work
```
If there's uncommitted work, decide whether to commit it on `main` first or carry it on the branch.
### 1.2 Backup the current FFmpeg in case of disaster
This is local-only and ignored by git (already in `.gitignore` patterns or large enough to ignore manually). The backup gives you a one-line revert if everything falls over. Do NOT commit the backup.
**Do NOT delete the live `-58.dll` files yet.** Other binaries deployed to SharedCore may still depend on them (and the `-59.dll` set is for yet another consumer). All three sets need to coexist after the migration.
### 1.4 Phase 1 acceptance
-`git status` shows only the new branch.
-`MediaClient/ffmpeg.backup-4.0.2/` exists and has the same size as `MediaClient/ffmpeg/`.
-`C:/Projects/SharedCore/backup-ffmpeg-4.0.2/` exists and contains 6 DLLs.
---
## Phase 2 — Repoint CMake and confirm baseline
### 2.1 Edit `cmake/Dependencies.cmake`
Find the FFmpeg block (around lines 162–180). Change the include and lib paths from `MediaClient/ffmpeg/...` to the absolute path `C:/ANSLibs/ffmpeg-n8.1/...`.
- An attempted build will fail (because MediaClient hasn't been ported yet) but **the failures should all be inside MediaClient files**, not anywhere else. If a non-MediaClient file breaks, investigate before continuing.
Expected error pattern at this point:
```
MediaClient/media/audio_decoder.cpp(116): error C2039: 'av_init_packet': is not a member of '...'
MediaClient/media/avcodec_mutex.cpp(41): error C3861: 'avcodec_close': identifier not found
MediaClient/media/audio_encoder.cpp(115): error C2039: 'channel_layout': is not a member of 'AVCodecContext'
... etc
```
Save this error output. It's the punch list for Phase 3.
---
## Phase 3 — Port MediaClient C++ code
This is the work-heavy phase. It's mechanical but there are ~20 call sites across ~6 files. Do them in the order below — earlier files unblock later ones.
There may be additional fallout from the channel-layout migration that surfaces only after the obvious cases are fixed. Plan to do **two compile-fix iterations**: first to address the API removals, second to address any cascading errors (e.g. struct field access that no longer compiles because the field type changed).
### 3.2 API change reference
These five removals are the entire scope for MediaClient. Examples below.
`av_init_packet()` was removed in FFmpeg 5.0. In modern FFmpeg, `AVPacket` is opaque — you allocate it with `av_packet_alloc()` and free it with `av_packet_free()`. There is no longer a stack-allocatable `AVPacket` struct.
**Before:**
```cpp
AVPacket packet;
av_init_packet(&packet);
packet.data = some_buffer;
packet.size = some_size;
int ret = avcodec_send_packet(ctx, &packet);
// ... use packet ...
// (no explicit free needed for stack packet in old code)
```
**After:**
```cpp
AVPacket* packet = av_packet_alloc();
if (!packet) {
// handle allocation failure
return -1;
}
packet->data = some_buffer;
packet->size = some_size;
int ret = avcodec_send_packet(ctx, packet);
// ... use packet ...
av_packet_free(&packet); // sets packet to nullptr after freeing
```
**Per-call-site checklist for each `av_init_packet`:**
- Find the corresponding scope where the packet's lifetime ends (function return, end of block, error exit path).
- Allocate with `av_packet_alloc()` at the same place `av_init_packet` used to be called.
- Add `av_packet_free(&pkt)` at every exit path (return statement, end of scope, error branches). RAII via `std::unique_ptr<AVPacket, decltype(&av_packet_free_wrapper)>` is cleaner if there are many exit paths — define a one-line wrapper because `av_packet_free` takes `AVPacket**` not `AVPacket*`.
- Replace all `&packet`/`packet.field` with `packet`/`packet->field`.
**Specific sites:**
| File | Line (4.0.2) | Context |
|---|---|---|
| `audio_decoder.cpp` | 116 | Inside `Decode()` or similar, packet fed from input buffer |
Line numbers are from the unmodified 4.0.2-era file. After the first fix in a file, subsequent line numbers shift — re-find by name.
#### 3.2.2 `avcodec_close(ctx)` → just remove it
`avcodec_close()` was removed in FFmpeg 7.0. In modern FFmpeg, `avcodec_free_context()` does both close and free in one call. Existing code that does both `avcodec_close()` then `avcodec_free_context()` should drop the close.
**Before:**
```cpp
if (m_pContext) {
avcodec_close(m_pContext);
avcodec_free_context(&m_pContext);
}
```
**After:**
```cpp
if (m_pContext) {
avcodec_free_context(&m_pContext);
}
```
**Specific sites:**
-`MediaClient/media/avcodec_mutex.cpp:41`
-`MediaClient/media/video_decoder.cpp:286`
In `avcodec_mutex.cpp`, the function may be a wrapper that exists specifically to take a global lock around `avcodec_close()` (some older FFmpeg APIs needed mutex protection). If so, decide whether the wrapper is still needed at all — modern `avcodec_free_context()` is internally thread-safe per-context. **Read the file before deciding.** It may just need the body to call `avcodec_free_context` instead, OR the entire wrapper may be dead code now.
#### 3.2.3 `AVCodecContext::channel_layout` (uint64_t) and `AVCodecContext::channels` → `AVCodecContext::ch_layout` (`AVChannelLayout`)
Note `swr_alloc_set_opts2` (with the `2`) — different signature, takes `AVChannelLayout*` instead of `uint64_t`, and now allocates+sets in one call writing into `&swr`.
**For `AVCodecContext` writes:** replace with `av_channel_layout_default(&m_pCodecCtx->ch_layout, n);`. The `nb_channels` field is set automatically by the helper.
**For `AVFrame` writes:** same pattern — `av_channel_layout_default(&m_pFrame->ch_layout, n);`. `AVFrame` also got a new `ch_layout` field in 5.1+. The old `AVFrame::channel_layout` and `AVFrame::channels` fields are deprecated then removed.
**Be careful in audio_encoder.cpp lines 280, 375, 403** — these write to `AVFrame->channel_layout`, not `AVCodecContext`. Same migration pattern but on the frame's `ch_layout` field.
**Audit pass needed:** after fixing these six obvious sites, search all of MediaClient/media/ for any other reference to:
-`->channels` where the left side is an `AVCodecContext*` or `AVFrame*` (not the RTSP `channels` array — be careful)
-`->channel_layout` similarly
-`av_get_default_channel_layout`
-`swr_alloc_set_opts(` (without the 2)
-`AV_CH_LAYOUT_*` macros — usually still work but may need to be wrapped in `AVChannelLayout` initialization
A safer grep is: `grep -nE 'channel_layout|->channels[^_]|av_get_default_channel_layout|swr_alloc_set_opts\(' MediaClient/media/*.cpp MediaClient/media/*.h`
#### 3.2.4 `m_pContext->codec->capabilities` — likely still works, verify
`AVCodecContext::codec` (the pointer to the `const AVCodec*` the context was opened with) is still present in FFmpeg 8.1. The capability check `m_pContext->codec->capabilities & AV_CODEC_CAP_DELAY` should compile unchanged.
If it doesn't (some niche removal I'm not remembering), the modern alternative is:
```cpp
const AVCodec* codec = avcodec_find_decoder(ctx->codec_id); // or _encoder
if (codec && (codec->capabilities & AV_CODEC_CAP_DELAY)) { ... }
```
**Sites to verify:**
-`audio_encoder.cpp:311`
-`audio_decoder.cpp:166`
-`video_decoder.cpp:964`
These are sanity checks during the cleanup loop — if the encoder supports DELAY mode, drain residual frames. The check itself doesn't need changes unless the header organization changed (it didn't, in 8.1).
#### 3.2.5 Other things to watch for
These weren't surfaced by the initial grep but are common 4.0 → 8.1 breakage points. **Search for them after the obvious fixes:**
| Removed | Replacement |
|---|---|
| `AVStream::codec` (the embedded `AVCodecContext`) | Allocate your own `AVCodecContext`, fill from `AVStream::codecpar` via `avcodec_parameters_to_context` |
| `pkt.convergence_duration` | Removed; check if used and remove |
The above are common; not all may apply to MediaClient. **Don't proactively edit anything not flagged by the compiler** — fix what fails, leave the rest.
### 3.3 Suggested per-file workflow
For each file, in order:
1. Open the file.
2. Re-grep within the file to find all current call sites of removed APIs. The line numbers in this plan are from the 4.0.2-era unmodified file and shift after the first edit.
3. Apply changes in order from bottom of file to top (so earlier line numbers stay valid for later edits in the same pass).
4. Compile **just this file** with the new headers if your build system allows isolated compilation; otherwise, do a project build and look for errors in this file specifically.
5. Iterate until the file compiles clean.
6. Move to the next file.
**Suggested order (dependency-light first, dependency-heavy last):**
1.`avcodec_mutex.cpp` — smallest, isolated
2.`video_decoder.cpp` — uses `avcodec_close`, no audio churn
3.`video_player.cpp` — three `av_init_packet`, video only
4.`file_player.cpp` — two `av_init_packet`, video focus
5.`audio_decoder.cpp` — channel layout migration
6.`audio_encoder.cpp` — channel layout migration (the most extensive)
After all six compile cleanly, do a full project build and look for cascading failures elsewhere.
- Warnings are acceptable but should be reviewed — `-Wdeprecated-declarations` warnings on FFmpeg API are the only category that's fine to ignore (they're informational about future removals).
-`ANSCV.dll` is produced in `cmake-build-release/lib/` (or wherever the project's output dir is).
-`dumpbin /dependents cmake-build-release/lib/ANSCV.dll` (or `cmake-build-release/bin/`) shows imports for `avcodec-62.dll`, `avformat-62.dll`, `avutil-60.dll`, `swresample-6.dll`, `swscale-9.dll`, `avfilter-11.dll`, `avdevice-62.dll` — NOT the `-58`/`-56`/`-3`/`-5`/`-8` versions.
The `ImagesToMP4FF` and `ImagesToMP4HW` functions in `modules/ANSCV/ANSOpenCV.cpp` currently include `libx265` and `libx264` in their probe lists. **These encoders don't exist in the LGPL build** and will be skipped at runtime. That's not a bug, but the lists will be cleaner and the fallback path will use better encoders if updated.
### 4.1 New encoder probe order (replaces existing list in `ImagesToMP4HW`)
```
1. av1_nvenc — NVIDIA AV1 (RTX 40+)
2. av1_qsv — Intel AV1 (Arc, 13th-gen iGPU+)
3. av1_amf — AMD AV1 (RX 7000+)
4. hevc_nvenc — NVIDIA HEVC (Maxwell+, all modern NVIDIA)
12. mpeg4 — last resort, LGPL native FFmpeg encoder
```
**Removed from list** (no longer present in LGPL build):
-`libx265`
-`libx264`
### 4.2 Encoder option dictionaries to use (modern NVENC preset names work in 8.1)
After the FFmpeg update, NVENC's `p1`–`p7` preset names are valid (they were added in FFmpeg 4.4). Replace the legacy `slow` preset names with the new ones — the new ones offer a more granular quality/speed trade-off and unlock options like `tune=hq` which the older names didn't support.
`ImagesToMP4FF` is the software-only variant. After the LGPL switch, replace its current list:
```
libx265 → libx264 → mpeg4 (current)
```
with:
```
libsvtav1 → libopenh264 → mpeg4
```
Or even simpler, since `libsvtav1` is fast and produces small files, and `libopenh264` covers H.264, the fallback chain is already sensible.
### 4.4 Phase 4 acceptance
-`ImagesToMP4HW` and `ImagesToMP4FF` no longer reference `libx265` or `libx264` in their encoder lists.
- The build still succeeds (this is a pure constant/data change).
- Functional behavior verified in Phase 5.
---
## Phase 5 — Build, deploy, test, validate
### 5.1 Deploy the new FFmpeg DLLs to SharedCore
```bash
cp C:/ANSLibs/ffmpeg-n8.1/bin/avcodec-62.dll \
C:/ANSLibs/ffmpeg-n8.1/bin/avformat-62.dll \
C:/ANSLibs/ffmpeg-n8.1/bin/avutil-60.dll \
C:/ANSLibs/ffmpeg-n8.1/bin/swresample-6.dll \
C:/ANSLibs/ffmpeg-n8.1/bin/swscale-9.dll \
C:/ANSLibs/ffmpeg-n8.1/bin/avfilter-11.dll \
C:/ANSLibs/ffmpeg-n8.1/bin/avdevice-62.dll \
C:/Projects/SharedCore/
```
The old `-58`, `-56`, `-3`, `-5`, `-8` DLLs from FFmpeg 4.0 stay in place. The `-59`, `-57`, `-4`, `-6`, `-7` DLLs from FFmpeg 5.x (used by another consumer) also stay in place. After this step, SharedCore contains DLLs from THREE FFmpeg generations side by side, each used by whichever binary was linked against it.
[FF-HW] Using encoder: NVIDIA HEVC (NVENC) ... (or similar - depends on GPU)
[FF-HW] Video created: ...\output_hw_test.mp4 (26 frames, 10 FPS, ~2s) via NVIDIA HEVC (NVENC)
```
The log should NOT contain:
-`unsupported param (12)` (FFmpeg version mismatch — means the wrong DLL is loaded)
-`Cannot get the preset configuration` (same)
-`Function not implemented` (same)
- A fall-through to `libsvtav1` (means hardware is actually unavailable on this machine — NOT a migration failure)
### 5.5 Smoke test 3: MediaClient functionality
This is the riskiest part — verifying that the MediaClient port didn't break anything. Run each of the following manually with known-good inputs:
| Subsystem | Test |
|---|---|
| `ANSRTSP` | Connect to a known RTSP camera, verify video frames flow and audio (if expected) plays |
| `ANSRTMP` | Connect to a known RTMP source, verify video frames flow |
| `ANSFLV` | Open a known FLV file, verify video and audio play in sync |
| `ANSMJPEG` | Connect to a known MJPEG HTTP stream, verify frames |
| `ANSSRT` | Connect to a known SRT stream, verify frames |
| `ANSWebcam` | Open a USB webcam, verify capture |
| `ANSVideoPlayer` | Open a known H.264 video file, verify HW decode (NVDEC/D3D11VA/DXVA2 path) works |
| `ANSFilePlayer` / `ANSFilePlayer_CV` | Open a known video file, verify SW decode path works |
| `VideoPlayer` | Same as above, alternate API |
**Audio paths are the highest-risk** because of the channel layout migration. Listen for:
- Silence where there should be audio
- Distorted/sped-up/slowed-down audio (sample rate or channel count mismatch)
- Channel swap (left and right channels reversed)
- Crashes in `swr_*` resampler functions
If any of these fail, the audio channel layout migration almost certainly missed a site or has a wrong channel count somewhere.
### 5.6 Phase 5 acceptance
All boxes ticked:
- [ ] Clean rebuild succeeds with zero errors
- [ ]`ANSCV_PrintFFmpegLicense_S` reports LGPL
- [ ]`ImagesToMP4HW` opens NVENC successfully (assuming the test machine has any modern NVIDIA GPU)
- [ ] All 9 MediaClient subsystems verified manually (table in 5.5)
- [ ] No regression in any module that uses ANSCV (`ANSLPR`, etc.)
If all boxes check, the migration is complete. Commit and merge.
---
## 6. Cleanup (optional, after verification)
Once the migration is verified stable on `main` and not just the branch, you can:
1.**Delete `MediaClient/ffmpeg/`** (the old vendored FFmpeg source). It's no longer referenced by anything.
2.**Delete the backup directories** (`MediaClient/ffmpeg.backup-4.0.2/` and `C:/Projects/SharedCore/backup-ffmpeg-4.0.2/`) once you're confident in the new build.
3.**Optionally remove the old DLLs from SharedCore** (`avcodec-58.dll`, `avformat-58.dll`, `avutil-56.dll`, `swresample-3.dll`, `swscale-5.dll`, `avfilter-8.dll`) — **but only if no other binary in the field still depends on them.** Check with whoever owns the broader product deployment first. Removing these DLLs when other consumers still rely on them WILL break those consumers at runtime with a `DLL not found` error.
4.**Add a `THIRDPARTY.txt`** to your release artifacts containing the LGPL v3 notice and a link to FFmpeg's source (to satisfy LGPL §6 obligations). Include the contents of `C:/ANSLibs/ffmpeg-n8.1/LICENSE.txt` in your distribution.
## 7. Rollback plan
If anything goes wrong and you need to revert:
```bash
# 1. Restore the old FFmpeg headers/libs (if you went through with deletion)
# 4. Discard the migration branch (or keep it for later)
git checkout main
git branch -D ffmpeg-8-migration # only if abandoning entirely
```
The new FFmpeg DLLs in SharedCore (`avcodec-62.dll` etc.) can stay — they don't conflict with anything. Only ANSCV.dll's link table determines which DLL it loads, and a rolled-back ANSCV.dll will be linked against the old `-58.dll` set again.
## 8. Risk register
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Audio channel layout migration introduces silent or distorted audio | High | Medium | Manual testing of every audio path in 5.5, side-by-side comparison with old build |
| A 4.0 → 8.1 API removal that I haven't catalogued surfaces during compile | Medium | Low | Mechanical fix per occurrence; FFmpeg's release notes (linked below) document every removal |
| Some other consumer of `C:/Projects/SharedCore/` was relying on `avcodec-58.dll` and we delete it during cleanup | Low | High | Only delete during cleanup phase 6, and only after verifying no other live binaries depend on the old DLLs |
| The LGPL build's lack of libx265 means `ImagesToMP4FF` software fallback degrades quality | Low | Low | Phase 4 swaps in `libsvtav1` + `libopenh264` which produce equivalent or better quality |
| NVENC still fails after the migration (e.g. NVIDIA driver still incompatible) | Very Low | Medium | FFmpeg 8.1 supports current and recent NVIDIA driver generations; if it fails, update NVIDIA driver as a separate step |
| `MediaClient/media/*.h` headers expose more FFmpeg types than expected, causing cascading edits | Medium | Medium | Plan deliberately tackles `.cpp` files first; header changes follow only if compilation requires |
## 9. Reference materials
- **FFmpeg APIchanges document** (canonical list of every API change): https://github.com/FFmpeg/FFmpeg/blob/master/doc/APIchanges
- **FFmpeg release notes** for each major version: https://github.com/FFmpeg/FFmpeg/blob/master/Changelog
- **Channel layout migration guide** (the biggest API break): https://ffmpeg.org/doxygen/trunk/group__lavu__audio__channels.html
- **AVPacket API migration**: https://ffmpeg.org/doxygen/trunk/group__lavc__packet.html
- [ ]`modules/ANSCV/ANSOpenCV.cpp` — `ImagesToMP4HW` encoder list: add `av1_nvenc`/`av1_qsv`/`av1_amf` at the top, replace `libx265`/`libx264` with `libsvtav1`/`libopenh264`/`mpeg4` in the software fallback section
- [ ]`modules/ANSCV/ANSOpenCV.cpp` — `ImagesToMP4HW` NVENC option dicts: switch from legacy preset names to `p5` + `tune=hq` + spatial/temporal AQ + multipass
