Getting started

Use a Mac’s media hardware from your Linux, Windows or macOS FFmpeg client. For a Plex server, go directly to the Plex guide; stock libva applications use the VA-API guide.

For cameras, desktop capture and applications producing raw NV12/P010 frames, use the capture and remote encoding guide.

Requirements

Install the release binaries

Download the archives and checksum files from the latest release. Verify the downloaded tarball against SHA256SUMS.txt with shasum -a 256 on macOS or sha256sum on Linux.

Machine Archive
Apple Silicon Mac server vtremoted-macos-arm64.tar.gz
Intel Mac server vtremoted-macos-x86_64.tar.gz
Linux x86_64 client ffmpeg-linux-x86_64.tar.gz
Linux arm64 client ffmpeg-linux-arm64.tar.gz — read the runtime requirements
macOS client ffmpeg-macos-arm64.tar.gz or ffmpeg-macos-x86_64.tar.gz
Windows x86_64 client ffmpeg-windows-x86_64.tar.gz

On the Apple Silicon Mac:

tar -xzf vtremoted-macos-arm64.tar.gz
brew install lz4 zstd
./vtremoted/vtremoted --version
./vtremoted/vtremoted --listen 192.168.1.20:5555 --log-level 1

Replace 192.168.1.20 with your Mac’s private address. Intel users unpack the x86_64 archive. The daemon defaults to 127.0.0.1:5555; other machines cannot connect until you choose a reachable listen address or use a tunnel.

LZ4/Zstd are optional runtime libraries for the daemon. FFmpeg and OBS request LZ4 by default; install LZ4 for that mode, and Zstd for clients using Zstd or automatic selection. You can explicitly choose -vt_remote_wire_compression none for an FFmpeg session without wire compression.

On a Linux x86_64 client:

mkdir -p ffmpeg-client
tar -xzf ffmpeg-linux-x86_64.tar.gz -C ffmpeg-client
./ffmpeg-client/ffmpeg -hide_banner -encoders

Unpack the corresponding archive on other client platforms. Use its ffmpeg binary for the following examples (ffmpeg.exe on Windows).

Your first remote encode

./ffmpeg-client/ffmpeg -i input.mkv \
  -c:v h264_videotoolbox_remote \
  -vt_remote_host 192.168.1.20:5555 \
  -b:v 6M -g 240 -c:a copy -c:s copy \
  output.mkv

FFmpeg decodes and filters locally, sends raw video frames to the Mac, then muxes the returned H.264 packets. Audio and subtitles are copied in this example. Select hevc_videotoolbox_remote for HEVC; use supported 10-bit formats and -profile:v main10 for HEVC Main 10.

Packet transcoding for batch jobs

For H.264/HEVC input, keep decoded frames on the Mac and send compressed packets in both directions:

./ffmpeg-client/ffmpeg -i input.mkv -map 0 -c copy \
  -vt_remote_transcode:v:0 \
  -vt_remote_host 192.168.1.20 -vt_remote_port 5555 \
  -vt_remote_out_codec:v:0 hevc -b:v:0 6M \
  output.mkv

The first video stream is transcoded; other mapped streams are copied. The Mac performs video decode, optional configured resize/pixel-format conversion and encode. Client-side audio, subtitles, files and muxing stay local. Arbitrary video filters are not part of this server path; use the remote encoder after local filtering for those jobs.

HDR to SDR

On macOS 15+, add vt_remote_hdr_to_sdr=1 to the packet-transcode BSF to convert 10-bit HEVC HDR10/PQ or HLG to limited-range BT.709 SDR:

./ffmpeg-client/ffmpeg -i hdr.mkv -map 0 -c copy \
  -bsf:v "vtremote_transcode=vt_remote_host=${MAC_HOST}:vt_remote_port=5555:vt_remote_hdr_to_sdr=1:vt_remote_out_codec=h264:vt_remote_bitrate=6000000" \
  sdr.mkv

Set MAC_HOST to the Mac endpoint. Input must be 10-bit 4:2:0 HEVC with BT.2020 primaries, BT.2020 non-constant-luminance matrix, and PQ or HLG transfer. The Mac decodes to P010, applies native Core Image headroom tone mapping in 32-bit floating-point linear colour, then converts to BT.709 and encodes. Video remains compressed in both network directions. The example produces H.264/NV12; select vt_remote_out_codec=hevc:vt_remote_pix_fmt=2 for 10-bit SDR HEVC. HDR mastering, content-light, Dolby Vision, dynamic HDR and ICC metadata are removed from the SDR output; colour tags describe the converted pixels. Tone mapping uses Core Image’s GPU renderer in arm64 builds and CPU renderer in x86_64 builds. Decode and encode remain in VideoToolbox.

Source headroom uses available content-light metadata or mastering peak. With no peak metadata, PQ uses 10,000 nits and HLG uses 1,000 nits. The server must advertise transcode.hdr_to_sdr.v1; unsupported requests fail during setup. Omitting this option retains the existing HDR-preserving and SDR paths.

Applications request an accurate presentation window with the BSF options vt_remote_start_time (inclusive) and vt_remote_end_time (exclusive). Values are durations in the input packet clock. The caller supplies the window and keeps compressed preroll available to the decoder; the Mac trims decoded frames before encoding. A daemon advertising transcode.presentation_window.v1 is required. FFmpeg’s own seek handling remains unchanged.

For example, set MAC_HOST to the Mac endpoint. With input-side -ss 2, FFmpeg normalizes timestamps around the seek, so the retained video window starts at zero. This produces the next three seconds:

./ffmpeg-client/ffmpeg -ss 2 -i input.mkv -map 0:v:0 -c:v copy \
  -copypriorss 1 -t 3 \
  -bsf:v "vtremote_transcode=vt_remote_host=${MAC_HOST}:vt_remote_port=5555:vt_remote_start_time=0:vt_remote_end_time=3" \
  -an output.mkv

With -copyts, supply bounds on the preserved source clock instead. Applications handle audio trimming and timestamp normalization on the same clock.

For a directory of MKV files, run jobs sequentially to begin:

mkdir -p converted
for input in ./*.mkv; do
  [ -f "$input" ] || continue
  ./ffmpeg-client/ffmpeg -n -i "$input" -map 0 -c copy \
    -vt_remote_transcode:v:0 \
    -vt_remote_host 192.168.1.20 -vt_remote_port 5555 \
    -vt_remote_out_codec:v:0 hevc -b:v:0 6M \
    "converted/${input##*/}" || break
done

Review bitrate, output format and visual quality on representative files before a whole-library conversion. A fast preset and higher concurrency can change throughput, quality and power; choose them from measurements on your own hardware.

Share the endpoint securely

For token authentication, store a secret in a file readable only by the daemon user and start the server with:

./vtremoted/vtremoted --listen 192.168.1.20:5555 \
  --token-file /path/to/vtremote-token --log-level 1

Add -vt_remote_token YOUR_TOKEN to FFmpeg commands, or VTREMOTE_TOKEN to the VA-API/Plex environment. Tokens do not encrypt media or credentials. Use an SSH tunnel or VPN on untrusted networks; keep port 5555 private.

Linux arm64 release runtime

The arm64/aarch64 archive contains ffmpeg, ffprobe and ffplay. It is dynamically linked, built on Ubuntu 24.04, and needs glibc 2.39+ with matching codec, compression, font and SDL2 libraries. These include x264, x265, libvpx, dav1d, libaom, Opus, Vorbis, LAME, LZ4, Zstd, libass and libvmaf. CI installs libvmaf 3.0.0 under /usr/local; that shared library must be available on the client. SVT-AV1 4.0.1 is linked statically.

Debian 12 and Raspberry Pi OS Bookworm have an older glibc. Build on your target distribution or use a compatible Ubuntu 24.04 arm64 environment with the required libraries. A newer glibc alone does not supply every dependency. Inspect missing libraries with:

ldd ffmpeg-client/ffmpeg
ldd ffmpeg-client/ffprobe
ldd ffmpeg-client/ffplay

This asset is an FFmpeg client only. VA-API and Plex integrations remain Linux x86_64; no i686 release is published.

Build from source

Clone the repository on each machine that needs a build:

git clone https://github.com/davelindo/videotoolbox_remote.git
cd videotoolbox_remote

On macOS, install Xcode command line tools and the runtime compression libraries, then build the daemon:

brew install lz4 zstd pkg-config
make build-vtremoted
vtremoted/.build/release/vtremoted --listen 192.168.1.20:5555 --log-level 1

The default deployment target is macOS 13.0. To install as a background service from the checkout:

make install-vtremoted-restart VTREMOTED_LISTEN=192.168.1.20:5555

For FFmpeg, install development packages for LZ4, Zstd, libvmaf and the codec libraries enabled by the build, plus pkg-config and a compiler. Both compression development libraries are required by the standard build. See development for configuration and platform notes, then run:

make build-ffmpeg

The built client is ffmpeg/ffmpeg. If a Linux x86 assembly build fails, install current nasm and yasm; the assembler diagnostic can isolate toolchain errors.

Next steps