{
  "schemaVersion": 1,
  "contentVersion": "ca42e61ede0a24f789d7287a0001244ad22f4abf",
  "id": "docs/tools/hardware-encoders/videotoolbox",
  "collection": "docs",
  "title": "VideoToolbox",
  "description": "VideoToolbox is Apple's hardware video encoding framework, used from FFmpeg as h264_videotoolbox, hevc_videotoolbox and prores_videotoolbox.",
  "canonicalUrl": "https://encode.wiki/tools/hardware-encoders/videotoolbox/",
  "apiUrl": "https://encode.wiki/api/v1/documents/docs/tools/hardware-encoders/videotoolbox.json",
  "markdownUrl": "https://encode.wiki/api/v1/markdown/docs/tools/hardware-encoders/videotoolbox.md",
  "status": "current",
  "tags": [
    "migrated"
  ],
  "license": "CC BY-SA 4.0",
  "dates": {
    "lastVerified": "2026-10-08T00:00:00.000Z"
  },
  "authors": [],
  "sources": [
    {
      "title": "FFmpeg 9.0.2 VideoToolbox encoders",
      "url": "https://github.com/FFmpeg/FFmpeg/blob/n9.0.2/libavcodec/videotoolboxenc.c",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "Apple VideoToolbox documentation",
      "url": "https://developer.apple.com/documentation/videotoolbox",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "HandBrake VideoToolbox documentation",
      "url": "https://handbrake.fr/docs/en/latest/technical/video-videotoolbox.html",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "Apple unveils M2 (media engine with ProRes)",
      "url": "https://www.apple.com/newsroom/2022/06/apple-unveils-m2-with-breakthrough-performance-and-capabilities/",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "HandBrake encoder table (common.c)",
      "url": "https://github.com/HandBrake/HandBrake/blob/master/libhb/common.c",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    }
  ],
  "provenance": {
    "originUrl": "https://github.com/av1-community-contributors/codec-wiki/blob/37c3317fd058b23c71a87679bed5619a98f77752/docs/encoders_hw/videotoolbox.mdx",
    "originCommit": "37c3317fd058b23c71a87679bed5619a98f77752",
    "migratedAt": "2026-08-21T00:00:00.000Z",
    "modified": true,
    "originPath": "docs/encoders_hw/videotoolbox.mdx"
  },
  "headings": [
    {
      "depth": 2,
      "text": "Hardware or software encoder?",
      "anchor": "hardware-or-software-encoder"
    },
    {
      "depth": 2,
      "text": "Codec support",
      "anchor": "codec-support"
    },
    {
      "depth": 2,
      "text": "Quality-oriented encode",
      "anchor": "quality-oriented-encode"
    },
    {
      "depth": 2,
      "text": "Full-GPU pipeline",
      "anchor": "full-gpu-pipeline"
    },
    {
      "depth": 2,
      "text": "Options that matter",
      "anchor": "options-that-matter"
    },
    {
      "depth": 2,
      "text": "HandBrake",
      "anchor": "handbrake"
    },
    {
      "depth": 2,
      "text": "Pitfalls",
      "anchor": "pitfalls"
    }
  ],
  "sections": [
    {
      "id": "_preamble",
      "title": "Page introduction",
      "depth": 0,
      "canonicalUrl": "https://encode.wiki/tools/hardware-encoders/videotoolbox/",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/_preamble.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/_preamble.md",
      "checksum": "811416782365278582713c72cd9bf7a683c287a8f470d37388b7bb0960493151",
      "bytes": 398
    },
    {
      "id": "hardware-or-software-encoder",
      "title": "Hardware or software encoder?",
      "depth": 2,
      "anchor": "hardware-or-software-encoder",
      "canonicalUrl": "https://encode.wiki/tools/hardware-encoders/videotoolbox/#hardware-or-software-encoder",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/hardware-or-software-encoder.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/hardware-or-software-encoder.md",
      "checksum": "4b6bdc19a07e58aaf03265a417b205f171f248b91dcff9173c24375fe05f4f2b",
      "bytes": 553
    },
    {
      "id": "codec-support",
      "title": "Codec support",
      "depth": 2,
      "anchor": "codec-support",
      "canonicalUrl": "https://encode.wiki/tools/hardware-encoders/videotoolbox/#codec-support",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/codec-support.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/codec-support.md",
      "checksum": "84faeae471d9b3f7363af8d440b600569d063c608e74493918209ea1e7f49e29",
      "bytes": 610
    },
    {
      "id": "quality-oriented-encode",
      "title": "Quality-oriented encode",
      "depth": 2,
      "anchor": "quality-oriented-encode",
      "canonicalUrl": "https://encode.wiki/tools/hardware-encoders/videotoolbox/#quality-oriented-encode",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/quality-oriented-encode.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/quality-oriented-encode.md",
      "checksum": "f5e86662efa17579ed12234fb4e791c862a678e94d16d3c94402a93120808615",
      "bytes": 903
    },
    {
      "id": "full-gpu-pipeline",
      "title": "Full-GPU pipeline",
      "depth": 2,
      "anchor": "full-gpu-pipeline",
      "canonicalUrl": "https://encode.wiki/tools/hardware-encoders/videotoolbox/#full-gpu-pipeline",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/full-gpu-pipeline.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/full-gpu-pipeline.md",
      "checksum": "0dad980cfd4cbd774e4e19898ff9db3a9c96250d0b620341591bfdd8e50cbe87",
      "bytes": 342
    },
    {
      "id": "options-that-matter",
      "title": "Options that matter",
      "depth": 2,
      "anchor": "options-that-matter",
      "canonicalUrl": "https://encode.wiki/tools/hardware-encoders/videotoolbox/#options-that-matter",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/options-that-matter.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/options-that-matter.md",
      "checksum": "625977fa76ac184ca64ca175f5ef6c6fc0c8a67a09274f0729179b6f5cd0bc01",
      "bytes": 874
    },
    {
      "id": "handbrake",
      "title": "HandBrake",
      "depth": 2,
      "anchor": "handbrake",
      "canonicalUrl": "https://encode.wiki/tools/hardware-encoders/videotoolbox/#handbrake",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/handbrake.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/handbrake.md",
      "checksum": "cd280d66c33733b322975579e8707c9e4dd1c950bef5e9a32c4550991e4a955f",
      "bytes": 315
    },
    {
      "id": "pitfalls",
      "title": "Pitfalls",
      "depth": 2,
      "anchor": "pitfalls",
      "canonicalUrl": "https://encode.wiki/tools/hardware-encoders/videotoolbox/#pitfalls",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/pitfalls.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/hardware-encoders/videotoolbox/pitfalls.md",
      "checksum": "b908e8772e14f91c826767eae5b164d27406743474111bcbd6204c863a1be4d5",
      "bytes": 340
    }
  ],
  "outboundReferences": [
    "/tools/hardware-encoders/nvenc/#hardware-or-software-encoder",
    "/tools/software-encoders/x264/",
    "/tools/software-encoders/x265/"
  ],
  "checksum": "35c7bf499876ad10afeeb81a511b056d6fe3f82ae3ac6e38c841b90a4dcdc7af",
  "contentFormat": "markdown",
  "markdown": "VideoToolbox is Apple's low-level framework for hardware video encoding and decoding on macOS and iOS. On Apple Silicon (and Macs with a T2 chip) the work runs on the media engine, which makes it fast and very efficient. FFmpeg exposes `h264_videotoolbox`, `hevc_videotoolbox` and `prores_videotoolbox`; HandBrake offers the same engines as its VideoToolbox H.264, H.265 and H.265 10-bit encoders.\n\n## Hardware or software encoder?\n\nAs with every hardware encoder, you get speed and low power use at the cost of compression efficiency: [x264](/tools/software-encoders/x264/) and [x265](/tools/software-encoders/x265/) at slow presets give better quality at the same bitrate. VideoToolbox is a good fit for fast exports, recordings and previews, and for hardware ProRes. For archival or size-critical H.264 and HEVC encodes, use the software encoders. More in [NVENC: hardware or software](/tools/hardware-encoders/nvenc/#hardware-or-software-encoder).\n\n## Codec support\n\n| Codec | FFmpeg encoder | Notes |\n| --- | --- | --- |\n| H.264 | `h264_videotoolbox` | 8-bit 4:2:0. |\n| HEVC | `hevc_videotoolbox` | 8-bit and 10-bit (`-profile:v main10 -pix_fmt p010le`), alpha channel input, 4:2:2 10-bit on hardware that supports it. |\n| ProRes | `prores_videotoolbox` | Profiles `proxy`, `lt`, `standard`, `hq`, `4444`, `xq`. Hardware ProRes needs a chip with a ProRes engine: M1 Pro, Max and Ultra, and every M2 or later chip. |\n| AV1 | none | FFmpeg has no AV1 VideoToolbox encoder. Apple chips from the M3 and A17 Pro decode AV1 in hardware, but that is decode only. |\n\n## Quality-oriented encode\n\nOn Apple Silicon Macs, `-q:v` sets a constant-quality target from 0 to 100, higher is better (FFmpeg enables it only in native arm64 macOS builds):\n\n```sh\nffmpeg -i input.mkv -c:v hevc_videotoolbox -q:v 60 -tag:v hvc1 -c:a copy output.mp4\n```\n\n`-tag:v hvc1` makes QuickTime, Safari and iOS accept HEVC in MP4 or MOV; without it the file carries the `hev1` tag that Apple players do not recognise. The 0–100 scale is not CRF, and a good value depends on the source, so encode a short clip and look at it. 10-bit HEVC:\n\n```sh\nffmpeg -i input.mkv -c:v hevc_videotoolbox -q:v 60 -profile:v main10 -pix_fmt p010le -tag:v hvc1 -c:a copy output.mp4\n```\n\nOn Intel Macs `-q:v` is not available (FFmpeg stops with \"-q:v qscale not available for encoder. Use -b:v bitrate instead\"), so set a bitrate:\n\n```sh\nffmpeg -i input.mkv -c:v h264_videotoolbox -b:v 8M -c:a copy output.mp4\n```\n\n## Full-GPU pipeline\n\n```sh\nffmpeg -hwaccel videotoolbox -hwaccel_output_format videotoolbox_vld -i input.mkv -vf scale_vt=1920:1080 -c:v hevc_videotoolbox -q:v 60 -tag:v hvc1 output.mp4\n```\n\nDecode, scale and encode stay on the media engine. `scale_vt` is the only scaler in this path; any other filter needs `hwdownload,format=nv12` first.\n\n## Options that matter\n\n| Option | What it does |\n| --- | --- |\n| `-q:v` | Quality 0–100, Apple Silicon only. |\n| `-b:v` | Bitrate target, used when no quality is set. `-constant_bit_rate 1` asks for true CBR (macOS 13 or newer). |\n| `-profile:v` | H.264 `baseline`, `main`, `high`, `constrained_high`; HEVC `main`, `main10`, `main42210`; ProRes names above. |\n| `-allow_sw 1`, `-require_sw 1` | Permit or force Apple's software encoder. Off by default, so a missing hardware encoder is an error, not a silent fallback. |\n| `-realtime 1` | Hint for live capture. Lowers latency, may cost efficiency. |\n| `-prio_speed 1` | Prefer speed over quality. |\n| `-power_efficient 1` | Ask for the lower-power path when available. |\n| `-spatial_aq 1` | Spatial adaptive quantization where supported. |\n| `-alpha_quality` | Quality of the alpha channel in HEVC with alpha (0–1). |\n\n## HandBrake\n\nHandBrake can drive VideoToolbox as well. In HandBrakeCLI the encoders are `vt_h264`, `vt_h265`, `vt_h265_10bit` and `vt_prores`:\n\n```sh\nHandBrakeCLI -i input.mkv -o output.mp4 --encoder vt_h265 --quality 60\n```\n\nHandBrake's own scaler is sharper than the VideoToolbox one, so prefer it for resizing.\n\n## Pitfalls\n\n- Constant quality does not work on Intel Macs or with an x86_64 FFmpeg running under Rosetta; use a bitrate there.\n- Missing `-tag:v hvc1` is the usual reason an HEVC file will not play in Apple software.\n- The hardware encoder cannot be tuned like x264/x265: there are no presets, and most encoder internals are not exposed.\n"
}