Target OS: macOS 10.8 and later, on Intel and Apple Silicon Macs

What Is VideoToolbox

VideoToolbox is the part of macOS that encodes and decodes video in hardware. It uses the video encoding hardware in your Mac (on Apple Silicon, the media engine) to encode video fast.

Mac Supported Codecs
Intel Mac (2011 and later) H.264
Intel Mac (2017 and later) H.264, H.265
Apple Silicon (M1/M2/M3) H.264, H.265, ProRes (partial)

Prerequisites

VideoToolbox comes with macOS, so you do not need any drivers. FFmpeg, however, must be built with VideoToolbox support.

The Homebrew build of FFmpeg has it turned on:

※ This command requires an Apple Silicon / macOS environment
brew install ffmpeg

Check which VideoToolbox encoders your FFmpeg has:

※ This command requires an Apple Silicon / macOS environment
ffmpeg -encoders | grep videotoolbox

Basic h264_videotoolbox Command

※ This command requires an Apple Silicon / macOS environment
ffmpeg -i input.mp4 -c:v h264_videotoolbox -b:v 4M -c:a aac -b:a 128k output_vt.mp4

VideoToolbox has no -crf option. Control the quality with a bitrate (-b:v), or on Apple Silicon Macs set a quality level with -q:v (1–100, higher is better). On Intel Macs, FFmpeg refuses -q:v with -q:v qscale not available for encoder. Use -b:v bitrate instead.

hevc_videotoolbox (H.265)

※ This command requires an Apple Silicon / macOS environment
ffmpeg -i input.mp4 -c:v hevc_videotoolbox -b:v 2M -c:a aac -b:a 128k output_hevc_vt.mp4

H.265 gives the same quality as H.264 in a smaller file. The saving often quoted, 40–50%, is too optimistic: at matched VMAF, a measured comparison found 26–35%. That comparison used the libx265 and libx264 software encoders, not VideoToolbox.

Bitrate Control Options

Option Description
-b:v 4M Target bitrate (4 Mbit/s)
-maxrate 6M Maximum bitrate (a hard limit for every one-second stretch)
-bufsize 8M No effect: the VideoToolbox encoders do not use it

A VBR example that favors quality:

※ This command requires an Apple Silicon / macOS environment
ffmpeg -i input.mp4 -c:v h264_videotoolbox -b:v 5M -maxrate 8M -bufsize 10M -c:a aac output.mp4

Profile Specification

To set the H.264 profile:

※ This command requires an Apple Silicon / macOS environment
ffmpeg -i input.mp4 -c:v h264_videotoolbox -profile:v high -b:v 4M output.mp4

Available profiles: baseline, constrained_baseline, main, high, constrained_high, extended

Apple Silicon (M1/M2/M3)-Specific Considerations

Apple Silicon Macs have a more efficient media engine. FFmpeg’s VideoToolbox encoders use it automatically, with no extra options.

hevc_videotoolbox encodes a 10-bit input as 10-bit HEVC (Main10) and keeps its color tags, such as BT.2020 with PQ or HLG. It does not write Dolby Vision data or HDR10 metadata (mastering display and content light level):

※ This command requires an Apple Silicon / macOS environment
ffmpeg -i input_hdr.mp4 -c:v hevc_videotoolbox -b:v 8M -tag:v hvc1 output_hdr.mp4

Add -tag:v hvc1 so that the file plays on Apple devices (iPhone, iPad, Apple TV).

Common Errors and How to Fix Them

Unknown encoder 'h264_videotoolbox'

  • Your FFmpeg was built without VideoToolbox support.
  • Install the Homebrew build (brew install ffmpeg).
  • Check with ffmpeg -encoders | grep videotoolbox.

An H.265 .avi file will not play

  • FFmpeg writes the file without an error, but AVI has no standard way to store H.265, so other programs cannot read it.
  • Write to .mp4 or .mov instead.

Low Quality / Blocking Artifacts

  • VideoToolbox has no CRF mode, so raise -b:v (5M–8M).
  • For high quality, use the libx264 / libx265 software encoders.

Choosing Between Software and Hardware Encoding

Use Case Recommendation
High-quality archiving libx264 / libx265 (software)
Fast transcoding / batch processing VideoToolbox
Final Cut Pro workflows VideoToolbox (hvc1 tag)
You need CRF quality control Software encoding

Speed and Quality

Results vary with the chip (M1–M3, Intel) and the resolution.

  • Encode speed: VideoToolbox is usually faster than libx264 -preset medium. M1 Max has two video encode engines and M1 Ultra has four (Apple).
  • Quality: To reach the same VMAF score, VideoToolbox usually needs a higher bitrate than libx264. How much higher depends on the chip generation and the video. With no CRF, a bitrate that is too low soon shows up as blocking.
  • HEVC: hevc_videotoolbox usually gives similar quality to H.264 in a clearly smaller file, which helps for both streaming and storage.

Common Pitfalls

-crf/-cq has no effect

  • Symptom: Adding -crf 23 gives an error or does nothing.
  • Cause: VideoToolbox has no CRF. Its quality setting is -q:v (1–100, higher is better), which FFmpeg accepts only on Apple Silicon Macs.
  • Fix: Set a target with -b:v (for example 5M) and a ceiling with -maxrate, or use -q:v on Apple Silicon. If the quality is not good enough, raise the bitrate, or switch to libx264 -crf to encode by quality.

-q:v behaves differently than in libx264

  • Symptom: You set -q:v, but the quality is not what you expected, or FFmpeg stops with -q:v qscale not available for encoder. Use -b:v bitrate instead.
  • Cause: VideoToolbox’s -q:v runs from 1 to 100, and a higher value gives higher quality. FFmpeg accepts it only on Apple Silicon Macs; on Intel Macs it stops with that message.
  • Fix: On Apple Silicon, raise -q:v for higher quality. On Intel Macs, use -b:v.

Apple Silicon and Intel Macs don’t match on quality/speed

  • Symptom: The same command gives different results on an Intel Mac and on Apple Silicon.
  • Cause: The media engines are different generations. Apple Silicon’s dedicated engine is efficient, and its quality differs from an Intel iGPU’s.
  • Fix: Adjust the bitrate for each machine. Older Intel Macs may not support H.265. ffmpeg -encoders still lists hevc_videotoolbox on them, because it shows what your FFmpeg was built with, so encode a short test clip to check.

Plays in .mp4 but shows no video on Apple devices

  • Symptom: An HEVC file plays in VLC on the Mac but shows no picture on an iPhone or Apple TV.
  • Cause: The file has the HEVC codec tag hev1. Apple devices and apps work better with the hvc1 tag.
  • Fix: Add -tag:v hvc1 for Apple playback, and use an .mp4 or .mov container.

FAQ

Can I do CRF quality control with VideoToolbox?

There is no -crf. On Apple Silicon Macs, -q:v (1–100, higher is better) sets a quality level instead of a bitrate. Intel Macs refuse -q:v; there, set a target with -b:v and a ceiling with -maxrate. If you want CRF-style encoding (the size varies, the quality stays the same) on any Mac, use libx264 -crf.

Can I use the same command on M1 and Intel Macs?

Yes, the basic -b:v commands are the same (-q:v works only on Apple Silicon). Apple Silicon’s media engine is more efficient, though, so the same bitrate gives different quality and speed. Older Intel Macs may not support H.265. ffmpeg -encoders lists what your FFmpeg was built with, not what the Mac can do, so try a short encode first.

Can VideoToolbox output ProRes?

Some Apple Silicon generations offer prores_videotoolbox. It is useful as an intermediate (editing) codec for Final Cut Pro. Whether it works depends on the chip generation. ffmpeg -encoders | grep prores only shows that your FFmpeg includes it, so try a short encode.

How do I encode with low latency for streaming?

Use -realtime true (on builds that support it). -bufsize has no effect with VideoToolbox, so a smaller value does not lower latency. For very low latency, keep the bitrate steady with settings close to CBR (constant bitrate).

What bitrate should I set?

For 1080p, start at about 4–6 Mbps for H.264 or 2–4 Mbps for HEVC. For fast motion, or if you see blocking, raise it by 10–20%. Without CRF, it is safer to leave some bitrate to spare.