Skip to content

Building from Source

Symphoenix edited this page Aug 6, 2026 · 1 revision

Building from source

The short build is two commands. The reproducible build is a small ecosystem.
This page explains which is which before CMake begins communicating exclusively through cache variables.

SyLC combines a Python 3.14 application, an extended H.264/MVC decoder built with MinGW, a pybind11 native module built with MSVC, Direct3D 11 shaders, runtime DLLs and a Nuitka portable package. Build each layer with the toolchain it was designed for; mixing ABIs because both compilers speak C++ is a reliable way to learn about name mangling at 2 a.m.


Toolchain overview

Component Required toolchain
Python application Python 3.14, dependencies from uv.lock
edge264.dll MSYS2 / MinGW64 GCC using the checked-in build script
mvc_demuxer_cpp…pyd Visual Studio 2022 x64, CMake, vcpkg, pybind11
Native renderer Built into the .pyd; Windows SDK, D3D11/DXGI/d3dcompiler
Portable release Nuitka + MSVC using the current versioned build_exe_*.bat
Optional MV-HEVC export Bundled x265/GPAC tools plus ffmpeg/ffprobe

The shipped x64 native module requires AVX2. The edge264 DLL contains baseline, x86-64-v2 and x86-64-v3 objects and dispatches among them at runtime.


Prepare Python reproducibly

From the repository root:

uv sync --frozen

This uses the committed uv.lock, which is the dependency set used for reproducible work. pip install -r requirements.txt remains useful for development, but it does not carry the same exact-resolution promise.

Runtime Python dependencies include PySide6, python-mpv, NumPy and OpenCV. Native builds additionally need pybind11 through the configured vcpkg/MSVC environment.


Build edge264.dll

From an MSYS2/MinGW64-enabled command prompt:

cd edge264
build_sylc_edge264.bat
copy /Y edge264_candidate.dll ..\edge264.dll
cd ..

The response files deliberately avoid -march=native. They build portable CPU levels explicitly so one DLL can run across supported x64 machines and select acceleration at runtime.

For diagnostic A/B tests, SYLC_EDGE264_DLL=C:\full\path\edge264.dll selects an alternate decoder without replacing the normal copy.

Do not optimize first and verify later. The decoder has a bit-exactness gate because a build that is 8% faster and changes one eye is not an optimization. It is an unusually efficient bug.


Build the native module and D3D11 renderer

Configure with the intended Python 3.14 interpreter and x64 vcpkg triplet:

cmake -S mvc_realtime_demuxer -B build_py314 -G "Visual Studio 17 2022" -A x64 ^
  -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
  -DVCPKG_TARGET_TRIPLET=x64-windows ^
  -Dpybind11_DIR=C:/vcpkg/installed/x64-windows/share/pybind11 ^
  -DPYBIND11_FINDPYTHON=ON ^
  -DPython_EXECUTABLE=<python-3.14>/python.exe ^
  -DPython_ROOT_DIR=<python-3.14> ^
  -DBUILD_NATIVE_RENDERER=ON

cmake --build build_py314 --config Release

Copy the resulting mvc_demuxer_cpp.cp314-win_amd64.pyd from build_py314/python/Release/ to the project root.

Three options are worth understanding:

  • PYBIND11_FINDPYTHON=ON selects modern Python discovery.
  • Explicit Python_EXECUTABLE and Python_ROOT_DIR prevent vcpkg's own Python from being selected accidentally.
  • BUILD_NATIVE_RENDERER=ON compiles the D3D11 renderer and links d3d11, dxgi, dxguid and d3dcompiler.

HLSL shaders are compiled for the runtime/resource path defined by the native project; there is no separate user-facing fxc installation step for ordinary builds.


Runtime binaries

The source tree expects several runtime binaries beside the application:

Binary family Purpose
edge264.dll H.264/MVC decode
mvc_demuxer_cpp…pyd, ebml.dll, matroska.dll Native demux/decode bridge and renderer
mpv-2.dll Audio and compatibility playback
avcodec-62.dll, avformat-62.dll, related av*/sw* DLLs Native HEVC, probing and format support
ffprobe.exe Stream/subtitle analysis
onnxruntime.dll, DirectML.dll Optional 2D→3D runtime

Large redistributable DLLs may be ignored by source control while still being mandatory beside a local build. “The code compiled” and “the application has its runtime closure” are separate achievements.


Depth models are data, not build inputs

The portable application includes ONNX Runtime, DirectML and the model manifest, but not the model weights. Shipping graphs are downloaded on demand.

Current preset families use fixed-shape exports:

  • Quality: Base 756, with compatible Small fallbacks;
  • Balanced: Base 518, then Small 518;
  • Performance: Small 518;
  • adaptive widescreen variants at the supported 756- and 518-wide rectangular grids.

The manifest generator uses a hardcoded allowlist. This prevents experimental, backup or non-commercial model artifacts from wandering into a release because someone used a generous directory glob.

Only models with a verified Apache-2.0 chain belong in the shipping models/ set. Non-commercial or incompletely verified experiments remain segregated and must not enter the application package or public model repository.


Optional TensorRT

TensorRT is installed and qualified locally; it is never required for a working build. The setup flow detects GPU compute capability, obtains the matching runtime/engines or builds them, and runs a numerical gate before publishing an engine as trusted.

Each ONNX graph has its own engine identity and optimization shape. A square engine does not silently become a rectangular Scope engine through positive thinking.

Use the detailed commands and supported engine matrix in the root BUILD.md; they evolve faster than a wiki page should pretend otherwise.


Build the portable application

Use the current release-stamped script in the checkout. In the present tree that is:

build_exe_v530.bat

It produces a one-folder, no-console Nuitka build and includes the runtime DLLs, model manifest and deferred Python modules required by the current feature set.

The older build_exe_onefile.bat is not the current release path. It is retained for history/experimentation and may omit files required by modern 2D→3D support. A single executable is aesthetically tidy; a portable folder that actually contains its runtime is tidier in practice.


Minimum verification before sharing a build

  1. Launch the frozen executable, not the source tree.
  2. Play one ordinary H.264 file through edge264.
  3. Play one real MVC source and verify both eyes through a seek.
  4. Play 10-bit HEVC/HDR and inspect the active output path.
  5. Open the 2D→3D menu and confirm the manifest/model dialog works.
  6. Run the decoder bit-exactness benchmark against the reference DLL.
  7. Run the relevant Synth3D tests when native depth or shader code changed.
  8. Inspect the output folder for model weights, TensorRT caches, temporary engines and non-redistributable artifacts.

For the philosophy and concrete gates behind that list, continue with Engineering standards and validation.

Clone this wiki locally