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
- A Mac with Apple Silicon or supported T2 hardware, running macOS 13 or newer, including macOS 27.
- A Linux, Windows or macOS client with a matching release or source build.
- A reachable private endpoint over wired LAN or Thunderbolt networking. Use the raw frame bandwidth table for capture workflows. Packet transcoding sends compressed video both ways.
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
- Capture and live video: produce frames on any PC and encode them on the Mac.
- Plex: keep Plex on Linux and use a Mac as the external video engine.
- VA-API: use stock Linux applications through the encode-only driver.
- OBS: build the experimental remote live encoder.
- Performance: compare video quality, throughput and resource use.
- Troubleshooting: connection, codec and performance checks.