Files

Tuan Nghia Nguyen 750ccff58b Plan ffmpeg migration v1

2026-04-15 23:51:30 +10:00

53 KiB

Raw Permalink Blame History

PLAN — Migrate MediaClient (and ANSCV) from FFmpeg 4.0.2 to FFmpeg 8.1

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:

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).
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.
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.
Bundle source: BtbN GitHub releases. ffmpeg-n8.1-latest-win64-lgpl-shared-8.1.zip. MSVC-compatible .lib import libraries verified by inspection.
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:

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.

Confirm the current state matches what's documented in section 3. Specifically run:

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

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.
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.
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.
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.
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.
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.

1. Background

ANSCORE's ANSCV.dll currently links against a 2018-era FFmpeg 4.0.2 vendored at MediaClient/ffmpeg/. This is causing two concrete problems:

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.
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+).
Software fallbacks: libsvtav1, libaom-av1, libopenh264, mpeg4.
Excluded (LGPL build): libx264, libx265, libxvid, libxavs2, libpostproc, libfdk-aac.
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:

ANSCV.dll builds clean with no errors and no new warnings against C:/ANSLibs/ffmpeg-n8.1 headers/libs.
MediaClient/ffmpeg/ is removed from the source tree (no longer referenced).
cmake/Dependencies.cmake points at C:/ANSLibs/ffmpeg-n8.1/.
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/).
ANSCV_PrintFFmpegLicense_S() prints LGPL version 2.1 or later (or v3) for all four libraries.
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.
All existing functional tests pass for: ANSRTSP, ANSRTMP, ANSFLV, ANSMJPEG, ANSSRT, ANSWebcam, ANSVideoPlayer, ANSFilePlayer, ANSFilePlayer_CV, VideoPlayer — i.e. RTSP playback, RTMP playback, FLV file playback, MJPEG streaming, SRT streaming, webcam capture, file player audio/video sync.
No regression in ANSLPR or any other module that consumes ANSCV indirectly.
git status in MediaClient/ shows only the intended changes.

3. Current state (verified facts before starting)

3.1 FFmpeg install

	Path	Version
Headers	`C:/Projects/CLionProjects/ANSCORE/MediaClient/ffmpeg/include/`	4.0.2
Import libs	`C:/Projects/CLionProjects/ANSCORE/MediaClient/ffmpeg/lib/x64/`	4.0.2
Runtime DLLs	`C:/Projects/SharedCore/avcodec-58.dll`, `avformat-58.dll`, `avutil-56.dll`, `swresample-3.dll`, `swscale-5.dll`, `avfilter-8.dll`	4.0.2
Build configure	`--enable-gpl` (has `libpostproc`, `libx264`, `libx265`)	GPL

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
├── bin/
│   ├── ffmpeg.exe
│   ├── ffplay.exe
│   ├── ffprobe.exe
│   ├── avcodec-62.dll
│   ├── avdevice-62.dll
│   ├── avfilter-11.dll
│   ├── avformat-62.dll
│   ├── avutil-60.dll
│   ├── swresample-6.dll
│   └── swscale-9.dll
├── include/
│   ├── libavcodec/
│   ├── libavdevice/
│   ├── libavfilter/
│   ├── libavformat/
│   ├── libavutil/
│   ├── libswresample/
│   └── libswscale/
└── lib/
    ├── avcodec.lib
    ├── avdevice.lib
    ├── avfilter.lib
    ├── avformat.lib
    ├── avutil.lib
    ├── swresample.lib
    ├── swscale.lib
    └── (.def files, .dll.a files — ignore these, MSVC uses the .lib files)

Encoders confirmed available (via C:/ANSLibs/ffmpeg-n8.1/bin/ffmpeg.exe -encoders):

hevc_nvenc, h264_nvenc, av1_nvenc
hevc_qsv, h264_qsv, av1_qsv, mjpeg_qsv, mpeg2_qsv
hevc_amf, h264_amf, av1_amf
libsvtav1, libaom-av1, libvpx-vp9, libopenh264
mpeg4 (native, MPEG-4 Part 2)

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:

if(WIN32)
    target_link_libraries(ffmpeg INTERFACE
        avcodec.lib avdevice.lib avfilter.lib avformat.lib
        avutil.lib swresample.lib swscale.lib
    )
endif()

The include and lib paths still point at the OLD FFmpeg:

set(FFMPEG_INCLUDE_DIR "${CMAKE_SOURCE_DIR}/MediaClient/ffmpeg/include")
set(FFMPEG_LIB_DIR     "${CMAKE_SOURCE_DIR}/MediaClient/ffmpeg/lib/x64")

These need to change. See Phase 2.

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
(helper)	`ANSCV_PrintFFmpegLicense_S`	Diagnostic — prints library license strings

The ImagesToMP4 (original) function is the user's preserved baseline and must not be modified.

4. Out of scope

Updating other ANSLibs dependencies (CUDA, OpenCV, ONNX Runtime, TensorRT, etc.). FFmpeg only.
Adding new features beyond what's needed to compile and run.
Refactoring MediaClient's overall architecture. This is a port, not a rewrite.
Switching audio resampler to swresample if it isn't already (most of MediaClient already uses swresample, but verify).
Implementing AV1 hardware encoding configuration in ImagesToMP4HW. That's a follow-up after migration succeeds.
Updating cmake-build-release/ cache layout — assume a clean rebuild after the migration.

5. Strategy overview

Five phases, each independently verifiable:

Phase	What	Verifiable by
1	Preparation: backup, branch, scope review	`git status` clean, backup exists
2	Repoint CMake at new FFmpeg, confirm everything compiles for build targets that don't use MediaClient	non-MediaClient targets build clean
3	Port MediaClient C++ files (the hard part)	MediaClient compiles, ANSCV.dll links
4	Update ANSCV encoder probe lists for LGPL build	NVENC opens, software fallback uses `libsvtav1`/`mpeg4` instead of `libx265`/`libx264`
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

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

cp -r MediaClient/ffmpeg MediaClient/ffmpeg.backup-4.0.2

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.

1.3 Backup the runtime DLLs

mkdir -p C:/Projects/SharedCore/backup-ffmpeg-4.0.2
cp C:/Projects/SharedCore/avcodec-58.dll \
   C:/Projects/SharedCore/avformat-58.dll \
   C:/Projects/SharedCore/avutil-56.dll \
   C:/Projects/SharedCore/swresample-3.dll \
   C:/Projects/SharedCore/swscale-5.dll \
   C:/Projects/SharedCore/avfilter-8.dll \
   C:/Projects/SharedCore/backup-ffmpeg-4.0.2/

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/....

Before:

else()
    set(FFMPEG_INCLUDE_DIR "${CMAKE_SOURCE_DIR}/MediaClient/ffmpeg/include")
    set(FFMPEG_LIB_DIR     "${CMAKE_SOURCE_DIR}/MediaClient/ffmpeg/lib/x64")
    add_library(ffmpeg INTERFACE)
    target_include_directories(ffmpeg INTERFACE ${FFMPEG_INCLUDE_DIR})
    target_link_directories(ffmpeg INTERFACE ${FFMPEG_LIB_DIR})
    if(WIN32)
        target_link_libraries(ffmpeg INTERFACE
            avcodec.lib avdevice.lib avfilter.lib avformat.lib
            avutil.lib swresample.lib swscale.lib
        )
    else()
        target_link_libraries(ffmpeg INTERFACE
            avcodec avdevice avfilter avformat
            avutil swresample swscale
        )
    endif()
    message(STATUS "FFmpeg: using ANSLibs at ${FFMPEG_INCLUDE_DIR}")
endif()

After:

else()
    # FFmpeg 8.1 LGPL shared build
    # See docs/PLAN_FFmpeg8_MediaClient_Migration.md
    if(WIN32)
        set(FFMPEG_INCLUDE_DIR "C:/ANSLibs/ffmpeg-n8.1/include")
        set(FFMPEG_LIB_DIR     "C:/ANSLibs/ffmpeg-n8.1/lib")
    else()
        set(FFMPEG_INCLUDE_DIR "${ANSLIBS_DIR}/ffmpeg-n8.1/include")
        set(FFMPEG_LIB_DIR     "${ANSLIBS_DIR}/ffmpeg-n8.1/lib")
    endif()
    add_library(ffmpeg INTERFACE)
    target_include_directories(ffmpeg INTERFACE ${FFMPEG_INCLUDE_DIR})
    target_link_directories(ffmpeg INTERFACE ${FFMPEG_LIB_DIR})
    if(WIN32)
        target_link_libraries(ffmpeg INTERFACE
            avcodec.lib avdevice.lib avfilter.lib avformat.lib
            avutil.lib swresample.lib swscale.lib
        )
    else()
        target_link_libraries(ffmpeg INTERFACE
            avcodec avdevice avfilter avformat
            avutil swresample swscale
        )
    endif()
    message(STATUS "FFmpeg: using ANSLibs at ${FFMPEG_INCLUDE_DIR}")
endif()

Note: postproc.lib was already removed during preparation and stays removed (LGPL builds don't have it).

2.2 Wipe CMake cache and reconfigure

rm -rf cmake-build-release/CMakeCache.txt cmake-build-release/CMakeFiles
# Then trigger CMake reconfigure, either through CLion or:
cmake -S . -B cmake-build-release -G Ninja -DCMAKE_BUILD_TYPE=Release

The reconfigure should succeed. The configure-time message(STATUS "FFmpeg: ...") should print C:/ANSLibs/ffmpeg-n8.1/include.

2.3 Phase 2 acceptance

cmake-build-release/CMakeCache.txt shows FFMPEG_INCLUDE_DIR=C:/ANSLibs/ffmpeg-n8.1/include.
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.

3.1 Files to touch (complete list)

#	File	What needs to change
1	`MediaClient/media/avcodec_mutex.cpp`	Remove `avcodec_close()` call
2	`MediaClient/media/avcodec_mutex.h`	Possibly drop `avcodec_close()` declaration if exposed
3	`MediaClient/media/audio_decoder.cpp`	`av_init_packet`, `channel_layout`, `av_get_default_channel_layout`
4	`MediaClient/media/audio_decoder.h`	Update if it stores channel info as `int channels` + `uint64_t channel_layout`
5	`MediaClient/media/audio_encoder.cpp`	`channel_layout`, `av_get_default_channel_layout` (4 sites)
6	`MediaClient/media/audio_encoder.h`	Update if it stores channel info
7	`MediaClient/media/video_decoder.cpp`	Remove `avcodec_close()` call
8	`MediaClient/media/video_decoder.h`	Possibly minor — check after .cpp is fixed
9	`MediaClient/media/video_player.cpp`	`av_init_packet` (3 sites: lines 274, 458, 829)
10	`MediaClient/media/file_player.cpp`	`av_init_packet` (2 sites: lines 427, 749)

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.

3.2.1 `av_init_packet(&pkt)` → `av_packet_alloc()` / `av_packet_free()`

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:

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:

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
`file_player.cpp`	427	Inside read loop
`file_player.cpp`	749	Inside read/seek path
`video_player.cpp`	274	Inside decode-while-streaming
`video_player.cpp`	458	Inside another decode path
`video_player.cpp`	829	Inside encode/relay path

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:

if (m_pContext) {
    avcodec_close(m_pContext);
    avcodec_free_context(&m_pContext);
}

After:

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`)

This is the most invasive change. The old API:

AVCodecContext* ctx;
ctx->channels = 2;
ctx->channel_layout = AV_CH_LAYOUT_STEREO;  // uint64_t bitmask

The new API (FFmpeg 5.1+, mandatory in 7.0+):

AVCodecContext* ctx;
av_channel_layout_default(&ctx->ch_layout, 2);
// OR explicitly:
AVChannelLayout layout = AV_CHANNEL_LAYOUT_STEREO;
av_channel_layout_copy(&ctx->ch_layout, &layout);

AVChannelLayout is a struct with these fields you typically read:

int nb_channels — replaces the old channels int
enum AVChannelOrder order — usually AV_CHANNEL_ORDER_NATIVE
uint64_t mask (when order is NATIVE) — equivalent to the old channel_layout uint64_t

To get the channel count from a stream/codec context:

// Old:
int n = ctx->channels;

// New:
int n = ctx->ch_layout.nb_channels;

Functions that take channel layouts changed signatures. Notable ones used in MediaClient:

av_get_default_channel_layout(int n) -> uint64_t — removed. Use:

AVChannelLayout layout;
av_channel_layout_default(&layout, n);
// ... use layout ...
av_channel_layout_uninit(&layout);

swr_alloc_set_opts(SwrContext*, uint64_t out_ch_layout, AVSampleFormat out_fmt, int out_rate, uint64_t in_ch_layout, AVSampleFormat in_fmt, int in_rate, int log_offset, void* log_ctx) -> SwrContext* — removed. Use:

SwrContext* swr = nullptr;
AVChannelLayout out_layout, in_layout;
av_channel_layout_default(&out_layout, out_channels);
av_channel_layout_default(&in_layout,  in_channels);
int ret = swr_alloc_set_opts2(
    &swr,
    &out_layout, out_fmt, out_rate,
    &in_layout,  in_fmt,  in_rate,
    0, nullptr);
// (don't forget to swr_init() afterwards)
av_channel_layout_uninit(&out_layout);
av_channel_layout_uninit(&in_layout);

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.

Specific sites:

File	Line (4.0.2)	Field/Function
`audio_encoder.cpp`	115	`m_pCodecCtx->channel_layout = av_get_default_channel_layout(m_EncoderParams.DstChannels);`
`audio_encoder.cpp`	280	`m_pFrame->channel_layout = av_get_default_channel_layout(m_EncoderParams.DstChannels);`
`audio_encoder.cpp`	375	`m_pFrame->channel_layout = av_get_default_channel_layout(m_EncoderParams.SrcChannels);`
`audio_encoder.cpp`	403	`m_pResampleFrame->channel_layout = av_get_default_channel_layout(m_EncoderParams.DstChannels);`
`audio_decoder.cpp`	65	`m_pContext->channel_layout = av_get_default_channel_layout(channels);`
`audio_decoder.cpp`	223	`m_pResampleFrame->channel_layout = av_get_default_channel_layout(m_nChannels);`

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:

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`
`AVFormatContext::filename`	`AVFormatContext::url`
`AVFrame::pkt_pts`	`AVFrame::pts` (use directly)
`AVFrame::pkt_duration`	`AVFrame::duration`
`av_frame_get_pkt_duration(frame)`	`frame->duration`
`av_frame_get_pkt_pts(frame)`	`frame->pts`
`av_register_all()`, `avcodec_register_all()`, `avformat_network_init()` (for av_register_all)	Just delete the call
`AVCodec*` (non-const pointers)	`const AVCodec*` — required since 5.0
`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:

Open the file.
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.
Apply changes in order from bottom of file to top (so earlier line numbers stay valid for later edits in the same pass).
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.
Iterate until the file compiles clean.
Move to the next file.

Suggested order (dependency-light first, dependency-heavy last):

avcodec_mutex.cpp — smallest, isolated
video_decoder.cpp — uses avcodec_close, no audio churn
video_player.cpp — three av_init_packet, video only
file_player.cpp — two av_init_packet, video focus
audio_decoder.cpp — channel layout migration
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.

3.4 Phase 3 acceptance

cmake --build cmake-build-release --target ANSCV --config Release succeeds with zero errors.
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.

Phase 4 — Update ANSCV encoder probe lists for LGPL build

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)
5. hevc_qsv        — Intel HEVC   (Skylake+)
6. hevc_amf        — AMD HEVC     (most modern AMD)
7. h264_nvenc      — NVIDIA H.264 (universal NVIDIA fallback)
8. h264_qsv        — Intel H.264
9. h264_amf        — AMD H.264
10. libsvtav1      — software AV1, multithreaded, fast in 8.1
11. libopenh264    — software H.264 (BSD-licensed — fully LGPL-clean fallback)
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.

Recommended option dicts after the update:

Encoder	Options
`av1_nvenc`	`{rc=vbr, cq=30, preset=p5, tune=hq, multipass=fullres, spatial_aq=1, temporal_aq=1, rc-lookahead=32}`
`hevc_nvenc`	`{rc=vbr, cq=28, preset=p5, tune=hq, multipass=fullres, spatial_aq=1, temporal_aq=1, rc-lookahead=32, b_ref_mode=middle}`
`h264_nvenc`	`{rc=vbr, cq=24, preset=p5, tune=hq, multipass=fullres, spatial_aq=1, temporal_aq=1, rc-lookahead=32, b_ref_mode=middle, weighted_pred=1}`
`av1_qsv`	`{global_quality=30, preset=slower, look_ahead=1, look_ahead_depth=40}`
`hevc_qsv`	`{global_quality=28, preset=slower, look_ahead=1, look_ahead_depth=40}`
`h264_qsv`	`{global_quality=24, preset=slower, look_ahead=1, look_ahead_depth=40}`
`av1_amf`	`{quality=quality, rc=cqp, qp_i=30, qp_p=32, qp_b=34}`
`hevc_amf`	`{quality=quality, rc=cqp, qp_i=24, qp_p=26, qp_b=28}`
`h264_amf`	`{quality=quality, rc=cqp, qp_i=22, qp_p=24, qp_b=26}`
`libsvtav1`	`{crf=32, preset=6}` (preset 0=slowest/best, 13=fastest, 6 is balanced)
`libopenh264`	`{}` (limited tuning available; defaults are decent)
`mpeg4`	(no opts, set `codec_ctx->bit_rate = 1500000`)

Pixel formats per encoder:

NVENC: AV_PIX_FMT_YUV420P (works), or AV_PIX_FMT_NV12 (slightly faster, no conversion needed inside the encoder)
QSV: AV_PIX_FMT_NV12 (required)
AMF: AV_PIX_FMT_NV12 (preferred)
libsvtav1, libopenh264, mpeg4: AV_PIX_FMT_YUV420P

4.3 What to update in `ImagesToMP4FF`

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

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.

5.2 Full clean rebuild

rm -rf cmake-build-release/CMakeCache.txt cmake-build-release/CMakeFiles
cmake -S . -B cmake-build-release -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-release --config Release -j

Expect the build to take longer than usual (clean rebuild). All targets should succeed.

5.3 Smoke test 1: license verification

Run the unit test (or any binary that calls ANSCV_PrintFFmpegLicense_S()):

./cmake-build-release/bin/ANSCV-UnitTest.exe

Expected output:

[FFmpeg] avutil   license: LGPL version 2.1 or later   (or v3)
[FFmpeg] avcodec  license: LGPL version 2.1 or later
[FFmpeg] avformat license: LGPL version 2.1 or later
[FFmpeg] swscale  license: LGPL version 2.1 or later

If it shows GPL — STOP. Either the wrong build was deployed or CMake is still pointing at the old FFmpeg.

5.4 Smoke test 2: hardware encoder probe

Run ImagesToMP4HW against a known input folder:

ANSCV_ImagesToMP4HW_S("E:/Programs/DemoAssets/ImageSeries", "E:/output_hw_test.mp4", 0, 10);

Expected log:

[FF-HW Thread ...] Image: 1920x1085 -> Video: 1920x1084 | 26 frames @ 10 FPS (~2s)
[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:

Delete MediaClient/ffmpeg/ (the old vendored FFmpeg source). It's no longer referenced by anything.
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.
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.
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:

# 1. Restore the old FFmpeg headers/libs (if you went through with deletion)
cp -r MediaClient/ffmpeg.backup-4.0.2 MediaClient/ffmpeg

# 2. Revert the CMake change
git checkout main -- cmake/Dependencies.cmake

# 3. Wipe the build cache and rebuild
rm -rf cmake-build-release/CMakeCache.txt cmake-build-release/CMakeFiles
cmake -S . -B cmake-build-release -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-release --config Release -j

# 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
NVENC FFmpeg documentation (preset/option reference): https://ffmpeg.org/ffmpeg-codecs.html#nvenc
BtbN FFmpeg builds release page (where the bundle came from): https://github.com/BtbN/FFmpeg-Builds/releases
LGPL v3 text: C:/ANSLibs/ffmpeg-n8.1/LICENSE.txt

Appendix A — Complete file modification checklist

Print this and tick boxes as you go.

MediaClient C++ source

MediaClient/media/avcodec_mutex.cpp — remove avcodec_close() (line 41, may be in a wrapper function)
MediaClient/media/avcodec_mutex.h — drop wrapper declaration if entire wrapper is now redundant
MediaClient/media/audio_decoder.cpp — av_init_packet (line 116), channel_layout (lines 65, 223), av_get_default_channel_layout (lines 65, 223)
MediaClient/media/audio_decoder.h — verify channel-related public fields/methods still match new API
MediaClient/media/audio_encoder.cpp — channel_layout (lines 115, 280, 375, 403), av_get_default_channel_layout (same lines)
MediaClient/media/audio_encoder.h — verify channel-related public fields/methods
MediaClient/media/video_decoder.cpp — avcodec_close() (line 286)
MediaClient/media/video_decoder.h — verify no breakage
MediaClient/media/video_player.cpp — av_init_packet (lines 274, 458, 829)
MediaClient/media/file_player.cpp — av_init_packet (lines 427, 749)

ANSCV C++ source (for Phase 4)

modules/ANSCV/ANSOpenCV.cpp — ImagesToMP4FF encoder list: replace libx265/libx264 with libsvtav1/libopenh264/mpeg4
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

CMake

cmake/Dependencies.cmake — postproc.lib already removed (Phase 0 / preparation)
cmake/Dependencies.cmake — repoint FFMPEG_INCLUDE_DIR and FFMPEG_LIB_DIR to C:/ANSLibs/ffmpeg-n8.1

Deployment

Copy 7 new FFmpeg DLLs to C:/Projects/SharedCore/
Add THIRDPARTY.txt with LGPL notice to release artifacts
Include LICENSE.txt from FFmpeg bundle in release artifacts

Testing

License print is LGPL
ImagesToMP4HW uses NVENC (or appropriate hardware)
RTSP playback works (video and audio)
RTMP playback works
FLV playback works
MJPEG streaming works
SRT streaming works
Webcam capture works
HW video decoder (ANSVideoPlayer) works
SW video decoder (ANSFilePlayer, VideoPlayer) works
ANSLPR and other downstream modules unaffected

Appendix B — Quick API reference

Old (FFmpeg 4.0)	New (FFmpeg 8.1)	Removed in
`av_init_packet(&pkt)` then declare `AVPacket pkt;`	`AVPacket* pkt = av_packet_alloc();` ... `av_packet_free(&pkt);`	5.0
`avcodec_close(ctx)`	(delete) — `avcodec_free_context(&ctx)` covers it	7.0
`ctx->channels = N;` `ctx->channel_layout = X;`	`av_channel_layout_default(&ctx->ch_layout, N);`	7.0
`frame->channels`, `frame->channel_layout`	`frame->ch_layout.nb_channels`, `frame->ch_layout`	7.0
`av_get_default_channel_layout(N)` (returns uint64_t)	`av_channel_layout_default(&layout, N)` (writes to AVChannelLayout)	7.0
`swr_alloc_set_opts(swr, out_layout_u64, ...)`	`swr_alloc_set_opts2(&swr, &out_layout, ...)`	7.0
`AVCodec*` (non-const)	`const AVCodec*`	5.0
`AVStream::codec` (embedded AVCodecContext)	Allocate own AVCodecContext, fill from `AVStream::codecpar`	5.0
`AVFormatContext::filename`	`AVFormatContext::url`	5.0
`AVFrame::pkt_pts`	`AVFrame::pts`	6.0
`AVFrame::pkt_duration`	`AVFrame::duration`	7.0
`av_register_all()`	(delete) — automatic	5.0
`avcodec_register_all()`	(delete) — automatic	5.0
`pkt.convergence_duration`	(removed, no replacement, just delete)	6.0

Appendix C — Known-good CMake snippet

After Phase 2, cmake/Dependencies.cmake lines 162–180 should look like this (Windows path version):

else()
    # FFmpeg 8.1 LGPL shared build (BtbN distribution)
    # Migration plan: docs/PLAN_FFmpeg8_MediaClient_Migration.md
    if(WIN32)
        set(FFMPEG_INCLUDE_DIR "C:/ANSLibs/ffmpeg-n8.1/include")
        set(FFMPEG_LIB_DIR     "C:/ANSLibs/ffmpeg-n8.1/lib")
    else()
        set(FFMPEG_INCLUDE_DIR "${ANSLIBS_DIR}/ffmpeg-n8.1/include")
        set(FFMPEG_LIB_DIR     "${ANSLIBS_DIR}/ffmpeg-n8.1/lib")
    endif()
    add_library(ffmpeg INTERFACE)
    target_include_directories(ffmpeg INTERFACE ${FFMPEG_INCLUDE_DIR})
    target_link_directories(ffmpeg INTERFACE ${FFMPEG_LIB_DIR})
    if(WIN32)
        target_link_libraries(ffmpeg INTERFACE
            avcodec.lib avdevice.lib avfilter.lib avformat.lib
            avutil.lib swresample.lib swscale.lib
        )
    else()
        target_link_libraries(ffmpeg INTERFACE
            avcodec avdevice avfilter avformat
            avutil swresample swscale
        )
    endif()
    message(STATUS "FFmpeg: using ANSLibs at ${FFMPEG_INCLUDE_DIR}")
endif()

postproc.lib is intentionally absent — the LGPL build does not include libpostproc.

Appendix D — Quick test commands

# Verify FFmpeg version and configuration after deployment
C:/ANSLibs/ffmpeg-n8.1/bin/ffmpeg.exe -version

# List available encoders
C:/ANSLibs/ffmpeg-n8.1/bin/ffmpeg.exe -hide_banner -encoders | grep -iE "nvenc|qsv|amf|svtav1|openh264|mpeg4"

# Smoke-test NVENC HEVC encoding directly (independent of ANSCV)
C:/ANSLibs/ffmpeg-n8.1/bin/ffmpeg.exe \
    -y -hide_banner \
    -framerate 10 \
    -pattern_type glob -i "E:/Programs/DemoAssets/ImageSeries/*.jpg" \
    -c:v hevc_nvenc -preset p5 -tune hq -rc vbr -cq 28 \
    -movflags +faststart \
    E:/test_nvenc_direct.mp4

# Confirm ANSCV.dll's import table after rebuild
dumpbin /dependents cmake-build-release/lib/ANSCV.dll | grep -i "av\|sw\|postproc"
# Should show avcodec-62.dll, avformat-62.dll, avutil-60.dll, swresample-6.dll, swscale-9.dll
# Should NOT show avcodec-58.dll, postproc-*.dll

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.

53 KiB Raw Permalink Blame History Unescape Escape

PLAN — Migrate MediaClient (and ANSCV) from FFmpeg 4.0.2 to FFmpeg 8.1

Decisions already made (do not re-litigate)

Pre-work already completed (do NOT redo)

Quick Start for a new session

How to invoke this plan in a new session

Context the new session might need that isn't in this plan

1. Background

2. Goals and acceptance criteria

3. Current state (verified facts before starting)

3.1 FFmpeg install

3.2 New FFmpeg bundle (verified)

3.3 CMake setup

3.4 ANSCV functions added in preparation for this migration

4. Out of scope

5. Strategy overview

Phase 1 — Preparation

1.1 Branch

1.2 Backup the current FFmpeg in case of disaster

1.3 Backup the runtime DLLs

1.4 Phase 1 acceptance

Phase 2 — Repoint CMake and confirm baseline

2.1 Edit cmake/Dependencies.cmake

2.2 Wipe CMake cache and reconfigure

2.3 Phase 2 acceptance

Phase 3 — Port MediaClient C++ code

3.1 Files to touch (complete list)

3.2 API change reference

3.2.1 av_init_packet(&pkt) → av_packet_alloc() / av_packet_free()

3.2.2 avcodec_close(ctx) → just remove it

3.2.3 AVCodecContext::channel_layout (uint64_t) and AVCodecContext::channels → AVCodecContext::ch_layout (AVChannelLayout)

3.2.4 m_pContext->codec->capabilities — likely still works, verify

3.2.5 Other things to watch for

3.3 Suggested per-file workflow

3.4 Phase 3 acceptance

Phase 4 — Update ANSCV encoder probe lists for LGPL build

4.1 New encoder probe order (replaces existing list in ImagesToMP4HW)

4.2 Encoder option dictionaries to use (modern NVENC preset names work in 8.1)

4.3 What to update in ImagesToMP4FF

4.4 Phase 4 acceptance

Phase 5 — Build, deploy, test, validate

5.1 Deploy the new FFmpeg DLLs to SharedCore

5.2 Full clean rebuild

5.3 Smoke test 1: license verification

5.4 Smoke test 2: hardware encoder probe

5.5 Smoke test 3: MediaClient functionality

5.6 Phase 5 acceptance

6. Cleanup (optional, after verification)

7. Rollback plan

8. Risk register

9. Reference materials

Appendix A — Complete file modification checklist

MediaClient C++ source

ANSCV C++ source (for Phase 4)

CMake

Deployment

Testing

Appendix B — Quick API reference

Appendix C — Known-good CMake snippet

Appendix D — Quick test commands

Appendix E — Copy-paste prompts for a new Claude session

Starting from scratch (Phase 1)

Resuming a partial migration

Just executing one specific phase

Just porting one specific MediaClient file

53 KiB

Raw Permalink Blame History

2.1 Edit `cmake/Dependencies.cmake`

3.2.1 `av_init_packet(&pkt)` → `av_packet_alloc()` / `av_packet_free()`

3.2.2 `avcodec_close(ctx)` → just remove it

3.2.3 `AVCodecContext::channel_layout` (uint64_t) and `AVCodecContext::channels` → `AVCodecContext::ch_layout` (`AVChannelLayout`)

3.2.4 `m_pContext->codec->capabilities` — likely still works, verify

4.1 New encoder probe order (replaces existing list in `ImagesToMP4HW`)

4.3 What to update in `ImagesToMP4FF`