VideoToolbox Bitrate Control in FFmpeg

Apple's VideoToolbox framework provides hardware-accelerated video encoding on macOS and iOS, accessible in FFmpeg primarily through the h264_videotoolbox and hevc_videotoolbox encoders. Controlling the output bitrate requires specific FFmpeg flags that map directly to Apple's underlying compression session properties. This guide outlines the essential parameters available for configuring Average Bitrate (ABR), Constrained Bitrate, and Variable Bitrate (VBR) or Constant Quality modes when encoding with VideoToolbox.

Core Bitrate Control Parameters

  • -b:v (Target Bitrate): Sets the target average video bitrate. When used alone, VideoToolbox operates in an Average Bitrate (ABR) mode, attempting to keep the overall file size aligned with this value while dynamically adjusting complex scenes.
    • Example: -b:v 5M (targets 5 Mbps)
  • -maxrate (Maximum Bitrate): Defines the upper limit for the bitrate buffer. When paired with -b:v, it restricts bandwidth spikes, which is critical for HTTP Live Streaming (HLS) or hardware decoders with strict bandwidth limits.
    • Example: -b:v 4M -maxrate 5M
  • -q:v or -global_quality (Quality-Based VBR): Configures quality-targeted variable bitrate encoding. VideoToolbox maps this to the kVTCompressionPropertyKey_Quality property. In FFmpeg, this takes an integer typically ranging from 1 (lowest quality) to 100 (highest quality). Setting -q:v disables average bitrate targeting in favor of perceptual quality preservation.
    • Example: -q:v 65

Advanced Rate Control Flags

  • -spatial_aq (Spatial Adaptive Quantization): A boolean parameter (1 to enable, 0 to disable) that instructs the encoder to allocate more bits to perceptually important areas, such as detailed textures or human faces, and fewer bits to flat or noisy areas.
    • Example: -spatial_aq 1
  • -realtime (Realtime Encoding): A boolean flag (1 or 0) that configures the encoder for low-latency live scenarios. When enabled, the rate control algorithm prioritizes meeting frame-rate deadlines over strict bitrate accuracy or compression efficiency.
    • Example: -realtime 1
  • -priors / Frame Dependencies: While not directly setting a bit budget, properties such as -bf (B-frames) and -g (GOP size/keyframe interval) heavily influence rate distribution efficiency. VideoToolbox adjusts macroblock quantizers based on the distance between I-frames defined by -g.

Common Implementation Patterns

Constant Quality (VBR): To prioritize visual fidelity without a strict size limit, omit -b:v and specify quality:

ffmpeg -i input.mp4 -c:v h264_videotoolbox -q:v 70 output.mp4

Constrained Variable Bitrate (CVBR): To achieve an average target while capping maximum data bursts:

ffmpeg -i input.mp4 -c:v hevc_videotoolbox -b:v 6M -maxrate 8M -spatial_aq 1 output.mp4

Low-Latency Streaming: For live delivery where consistent network throughput is mandatory:

ffmpeg -i input.mp4 -c:v h264_videotoolbox -b:v 3M -maxrate 3.5M -realtime 1 output.mp4