Linux VA-API driver

Use stock Linux FFmpeg’s h264_vaapi and hevc_vaapi encoders while the actual encode runs on a Mac over LAN. The driver is Linux x86_64 and encode-only: decode, filters and raw-frame upload stay on the application host.

For a GPU-less Plex host, use the separate Plex packet integration. It offloads decode, resize and encode without a Linux render node; it does not route video through this driver.

Supported operations

Capability Driver support
H.264 encode Constrained Baseline, Main, High
HEVC encode Main and Main 10
Software-uploaded surfaces NV12 and P010
Rate control CBR, VBR, CQP
Decode / VPP / scale / deinterlace / tone mapping Local application responsibility
B-frames / external DMA-BUF surfaces Unsupported

The target Mac must support the requested codec and format. Driver profile support does not guarantee every Mac supports every mode.

Install the binary release

Start the Mac daemon, then download vtremote-vaapi-linux-x86_64.tar.gz and its checksum from the latest release.

The binary artifact targets Ubuntu 24.04 (glibc 2.39) or a compatible newer distribution. Install your distribution’s LZ4 and Zstd runtime packages; stock FFmpeg also needs a compatible libva runtime. Unpack and install:

tar -xzf vtremote-vaapi-linux-x86_64.tar.gz
sudo ./vtremote-vaapi/install-binary.sh
export LIBVA_DRIVERS_PATH=/opt/vtremote-vaapi/lib/dri
export LIBVA_DRIVER_NAME=vtremote
export VTREMOTE_HOST=192.168.1.20:5555
export VTREMOTE_WIRE_COMPRESSION=auto
# If the Mac daemon requires a token:
# export VTREMOTE_TOKEN=YOUR_TOKEN
/opt/vtremote-vaapi/bin/vtremote-probe --host "$VTREMOTE_HOST" --codec h264

The installer uses /opt/vtremote-vaapi and refuses to overwrite an existing installation. See the binary installation instructions for upgrades, dependencies and checksums.

Choose a render node

Libva still needs a DRM render node to initialize, even though encoding happens on the remote Mac. Use an accessible physical render node or, where the kernel provides it, a VGEM node:

sudo modprobe vgem
ls -l /dev/dri/renderD*

VGEM availability depends on the host kernel; some NAS kernels omit it. Choose the actual node and grant the application user appropriate render-group/device access. renderD128 below is an example, not a guaranteed VGEM assignment. The repository’s render-node helper lists available nodes.

Encode with stock FFmpeg

H.264 with local software decode and NV12 upload:

ffmpeg -init_hw_device vaapi=remote:/dev/dri/renderD128 \
  -filter_hw_device remote -i input.mkv \
  -vf format=nv12,hwupload \
  -c:v h264_vaapi -bf 0 -b:v 6M -c:a copy \
  output.mkv

HEVC Main 10 with P010 upload:

ffmpeg -init_hw_device vaapi=remote:/dev/dri/renderD128 \
  -filter_hw_device remote -i input.mkv \
  -vf format=p010le,hwupload \
  -c:v hevc_vaapi -profile:v main10 -bf 0 -b:v 6M -c:a copy \
  output-main10.mkv

Keep scale, deinterlace or tone mapping before hwupload. The driver has no VPP pipeline and accepts software-uploaded surfaces rather than another GPU’s DMA-BUF frames. Raw-frame transport can become the limiting factor at high resolutions; see Performance.

Connection settings

Variable Meaning / default
VTREMOTE_HOST Required host:port endpoint
VTREMOTE_TOKEN Optional daemon authentication token
VTREMOTE_WIRE_COMPRESSION auto (default), none, lz4, zstd
VTREMOTE_TIMEOUT_MS Operation timeout, default 10000
VTREMOTE_LOG Diagnostic logging, default 0

Automatic compression chooses Zstd below 200 Mbit/s of estimated raw traffic and LZ4 above that threshold. Compression savings depend on content. The daemon must have the corresponding runtime library installed. Network traffic is plain TCP; see security.

vgem_drv_video.so provides a discovery alias. Use LIBVA_DRIVER_NAME=vtremote explicitly where possible. Keep any application-specific discovery aliases in an isolated driver directory; do not replace system iHD drivers.

Build, SDK and tests

Run make test-vaapi-driver on Linux for driver checks with stock FFmpeg and the repository mock server. The driver README contains source-build dependencies and Docker instructions.

The package also includes an experimental static C SDK (libvtremote_client.a, headers and pkg-config metadata). It exposes connection, configure, frame/packet and flush operations with bounded in-flight work. Its ABI changed in v0.9.0; rebuild applications against the matching release. See the SDK reference.

For Plex deployment and real playback verification, continue with the Plex guide.