Development

Notes for contributors working on the client codecs, protocol, or daemon.

Repository Layout

Build Instructions

macOS (Server & Client)

The easiest way to build everything on a Mac:

make build

Release builds default to MACOSX_DEPLOYMENT_TARGET=13.0. Keep that default when building on macOS 27 or newer SDKs unless a release intentionally raises the minimum supported macOS version.

This produces:

The vtremoted binary must not hard-link Homebrew liblz4 or libzstd; those libraries are runtime-only optional dependencies for LZ4/Zstd wire compression. The release smoke test checks both the macOS 13.0 minimum OS and the absence of absolute Homebrew dylib load commands.

Linux / Windows (Client Only)

Linux FFmpeg CI and release artifacts target x86_64 and arm64 (aarch64). The arm64 job runs natively on GitHub-hosted ubuntu-24.04-arm, with the same codec/filter, mock integration, and packaged-artifact smoke checks as x86_64. See arm64 runtime requirements for the Ubuntu 24.04 shared-library baseline. The project does not publish or test 32-bit i686 Linux builds.

The VA-API driver job runs on Ubuntu 24.04 and builds the pinned libva 2.22 / VA-API 1.22 headers from source. Release artifacts target glibc 2.39. Locally on Linux, run make test-vaapi-driver. The test suite uses the shared repository mock and stock FFmpeg’s VA-API encoders.

FFmpeg sync candidates run the full CI matrix before promotion. After promotion, the release tag runs validation and packaging; the identical tagged sync push to main skips duplicate builds. FFmpeg compiler-cache checks require actual compilation hits or misses, so a bypassed cache fails CI.

  1. Install assembler and library dependencies (assemblers are needed for x86 builds):
    nasm -v
    yasm --version
    

    Install current nasm and yasm before building. FFmpeg’s x86 assembly can fail early with older or missing assemblers.

  2. Configure:
    cd ffmpeg
    ./configure --enable-videotoolbox-remote --enable-liblz4 --enable-libzstd \
      --enable-libvmaf --enable-libaom --enable-libdav1d --enable-libsvtav1
    
  3. Build:
    make -j$(nproc)
    

The repository Makefile wraps the same build with project defaults:

make build-ffmpeg

If a Linux x86_64 source build fails in FFmpeg x86 assembly after installing current assemblers, use the diagnostic compatibility fallback:

make clean-ffmpeg
make build-ffmpeg FFMPEG_DISABLE_X86ASM=1

This appends --disable-x86asm. It is slower and should not be the default path, but it confirms whether the failure is limited to the assembler/toolchain surface.

Testing & Benchmarks

Integration scripts are located in tests/integration/.

Setup

Export the path to your server binary:

export VTREMOTED="$PWD/vtremoted/.build/release/vtremoted"

Key Scripts

Measuring performance

Follow the performance comparison setup to reproduce the current results. performance.py dispatches workers to designated Linux and Mac hosts. Native and remote VideoToolbox use the same Mac; the coordinating computer does not encode video.

Keep raw captures outside Git. Publish only the runner’s allowlisted measurements, versions and hashes; never commit real server names, usernames, addresses or private paths.

Adaptive options

-vt_remote_wire_compression auto   # pick LZ4 vs Zstd based on resolution/FPS
-vt_remote_inflight auto           # adjust inflight over time

GitHub Metadata and Release Notes

FFmpeg sync uses a squashed upstream parent to preserve local changes in the vendored tree. Keep git-subtree-dir and git-subtree-split trailers on that upstream commit, not on the repository merge commit. Merge subtree updates and tracking repairs with a merge commit; squashing or rebasing the PR can discard the upstream parent. bash scripts/check_ffmpeg_subtree.sh checks the tracking record before CI builds and automated syncs.

The repository includes small gh-based helpers for keeping the public GitHub surfaces in sync.

Prerequisite:

gh auth status

Key commands:

make sync-github-metadata
make release-notes TAG=v0.10.16
make release-notes-all
bash scripts/generate_release_notes.sh v0.10.16
bash tests/test_llms_release_version.sh

What they do:

Release checklist:

The dependency-free CI wiring regression runs with:

bash tests/test_ffmpeg_linux_arm64_ci.sh

Artifact Smoke Checks

CI smoke-tests packaged tarballs after creating them. To reproduce locally:

bash scripts/smoke_release_artifact.sh ffmpeg ffmpeg-linux-x86_64.tar.gz
bash scripts/smoke_release_artifact.sh ffmpeg ffmpeg-linux-arm64.tar.gz
bash scripts/smoke_release_artifact.sh vtremoted vtremoted-macos-arm64.tar.gz

The FFmpeg smoke check unpacks the tarball and verifies the remote encoders, remote decoders, vtremote_transcode, and quality filters are present. The vtremoted smoke check verifies --version and --help without binding a socket.

Documentation site

GitHub Pages builds docs/ with Jekyll. The release number in docs/_config.yml supplies the landing page, navigation and structured data; keep it aligned with docs/llms.txt, the daemon and changelog. Navigation lives in docs/_data/navigation.yml.

For a local preview with Jekyll and the configured plugins installed:

jekyll serve --source docs --host 127.0.0.1

Open http://127.0.0.1:4000/videotoolbox_remote/. Check desktop and mobile navigation, code copying, diagrams, local links and release metadata after theme/content edits. The Performance page contains the current measured comparison; remove obsolete result tables rather than relabeling them as fresh measurements.