Building from source

For developers. If you were handed a compiled package and just want VDM running on a laptop, you do not need any of this — go to Installation instead.

• Read this first: FFmpeg is required to build
• Toolchain
• Installing SDL3
• Installing FFmpeg libav
• How CMake finds FFmpeg
• Configure and build
• Build outputs
• Running the tests
• Compiler and linker flags
• Build troubleshooting

Read this first: FFmpeg is required to build

Shared FFmpeg DLLs alone are not enough for a build. You need the include/ and lib/ trees as well — that is, a development or shared distribution, not the -essentials package that ships only ffmpeg.exe.

Toolchain

The codebase is native C11 targeting Windows. There is no C++ in the product code, no cross-platform layer, and no scripting runtime at build time.

Installing SDL3

1. Download the SDL3 development libraries from github.com/libsdl-org/SDL/releases — take the SDL3-devel-<version>-VC.zip package.
2. Extract to C:\SDL3. The directory must contain cmake/, include/ and lib/ subdirectories.
3. Pass -DSDL3_DIR=C:/SDL3/cmake when configuring. If you installed elsewhere, point that at your own cmake/ directory.

To build SDL3 from source instead:

git clone https://github.com/libsdl-org/SDL.git
cd SDL
cmake -B build -G "Visual Studio 17 2022" -DCMAKE_INSTALL_PREFIX=C:/SDL3
cmake --build build --config Release
cmake --install build --config Release

Installing FFmpeg libav

You need a shared build with development files. The -shared suffix in the package name is the thing to look for; a static -essentials build contains only ffmpeg.exe and will not satisfy the build.

Option A — prebuilt from BtbN (recommended in the project's own dev docs)

1. Download from github.com/BtbN/FFmpeg-Builds/releases.
2. Take ffmpeg-master-latest-win64-lgpl-shared.zip. The lgpl flavour is preferred if the result will be redistributed; the GPL flavours pull in x264/x265.
3. Extract into external/ffmpeg/ at the repository root, flattened so that include/, lib/ and bin/ sit directly under VideoDistanceMarking\external\ffmpeg\.

Option B — prebuilt from gyan.dev

From gyan.dev/ffmpeg/builds, take ffmpeg-release-full-shared.7z (or a version-tagged equivalent). Requires 7-Zip to unpack. Note that gyan.dev's full builds are GPL-licensed because of x264/x265; if you redistribute, ship FFmpeg's LICENSE.txt alongside.

Option C — vcpkg

vcpkg install ffmpeg[core,avcodec,avformat,avfilter,avutil,swscale]:x64-windows

Option D — build FFmpeg from source under MSYS2

The repository carries tools/build_ffmpeg_from_source.sh for this. Budget 35–60 minutes for a first run.

1. Install MSYS2 from msys2.org (default location C:\msys64).
2. Launch the MSYS2 MinGW64 shell — not the plain MSYS2 MSYS shell. Confirm with echo $MSYSTEM, which must print MINGW64.
3. Update and install the toolchain:

   pacman -Syu
   pacman -S --needed base-devel mingw-w64-x86_64-toolchain \
     mingw-w64-x86_64-nasm mingw-w64-x86_64-yasm \
     mingw-w64-x86_64-pkg-config mingw-w64-x86_64-gcc git curl gnupg

4. Change into the repository and run the script. It defaults to FFmpeg 7.1:

   cd /c/path/to/VideoDistanceMarking
   export FFMPEG_VERSION=7.1
   bash tools/build_ffmpeg_from_source.sh

   The script downloads the tarball and signature from ffmpeg.org/releases and verifies the GPG signature. You may also pin FFMPEG_SHA256 if you want a checksum gate as well. The compile itself takes 15–40 minutes.
5. Return to a normal Windows shell for the CMake build — do not build VDM from inside the MSYS2 shell.

The configure line the script uses is deliberately narrow: --disable-everything with selective re-enabling, plus --disable-programs, --disable-doc, --disable-network, --disable-static, --disable-debug and --enable-optimizations. The result is a small shared build carrying only what VDM actually links against.

How CMake finds FFmpeg

cmake/FindFFmpegLibav.cmake probes these locations in this order and stops at the first hit. Each probe looks for <root>/include/libavcodec/avcodec.h.

On success the module sets the cache variable FFMPEG_LIBAV_FOUND to TRUE, derives FFMPEG_INCLUDE_DIR, FFMPEG_LIB_DIR and FFMPEG_BIN_DIR from the detected root, and defines the imported interface target FFmpeg::Libav. It resolves four components by import library: avformat, avcodec, avutil and swscale (as avcodec.lib and friends; MinGW-style libavcodec.dll.a names are accepted as a fallback).

A helper function vdm_install_ffmpeg_dlls(target) copies the runtime DLLs alongside the built executables. The DLL glob is wider than the four link components — it also collects swresample-*, avfilter-*, avdevice-*, postproc-*, libbz2-*, libwinpthread-*, libiconv-* and zlib*.

Configure and build

Open a Developer Command Prompt for VS 2022 or a Developer PowerShell for VS 2022, then:

cd VideoDistanceMarking
cmake -B build -G "Visual Studio 17 2022" -DSDL3_DIR=C:/SDL3/cmake
cmake --build build --config Release

Add -DFFMPEG_ROOT=... if your FFmpeg is somewhere the search order does not cover.

If CMake is not on PATH, use the copy bundled with Visual Studio:

"C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe" -B build -G "Visual Studio 17 2022" -DSDL3_DIR=C:/SDL3/cmake

Build outputs

All executables land in build/Release/. Thirteen non-test executables are defined:

There is also a static library target common (shared types, shared memory, IPC, settings parsing, logging) and a custom target copy_help_docs.

Running the tests

Twenty-three tests are registered with CTest — twenty-two unconditional, plus test_libav_encoder_stitching which only exists when FFmpeg was found.

ctest --test-dir build -C Release

Individual tests can be run directly from build\Release\. The registered set:

If your test count comes back as 22 rather than 23, FFmpeg was not detected — go back to the top of this page. That count is the cheapest available check on whether the encode path built.

Compiler and linker flags

Under MSVC the build applies:

Also defined project-wide: _CRT_SECURE_NO_WARNINGS and WIN32_LEAN_AND_MEAN. On non-MSVC compilers the equivalent set is -O2 -Wall -Wextra.

Three targets link with /STACK:4194304 — a 4 MB stack: motion, test_blob_detect and test_pipeline. The blob detector is recursive and overflows the default 1 MB stack on large connected components. If you add a new target that calls into blob detection, it needs the same link option.

Build troubleshooting

Deploying a build

To turn build\Release\ into a runnable install, copy its contents to C:\VDM\, then add the data files that live in the repository root rather than the build tree — numbers.txt, jumpers.csv, NorgeLogo.png and a settings.txt. Those must sit next to the executables. The full deployment shape is documented in Installation § folder layout.