Record macOS Screen with FFmpeg Hardware Acceleration

Recording your screen on macOS using FFmpeg can be done efficiently by combining the native avfoundation input framework with Apple's VideoToolbox hardware acceleration. By offloading video encoding from the CPU to the GPU or dedicated Apple Silicon media engines, you achieve smooth, high-resolution recordings with minimal system overhead. This guide outlines how to identify your input devices, construct the capture command, and apply hardware encoding using h264_videotoolbox or hevc_videotoolbox.

1. Identify Available Input Devices

Before capturing, identify the device indices assigned to your displays and audio devices by querying avfoundation:

ffmpeg -f avfoundation -list_devices true -i ""

Review the terminal output under the AVFoundation video devices and AVFoundation audio devices sections. Note the index numbers:

  • Video Devices: Typically, your primary display is listed as [1] Capture screen 0 or similar.
  • Audio Devices: Built-in or external microphones will have their own index (e.g., [0] Built-in Microphone).

2. Basic Hardware-Accelerated Screen Recording

To record the screen without audio using H.264 hardware acceleration, use the following command (replace "1" with your screen index):

ffmpeg -f avfoundation -framerate 60 -i "1:none" -c:v h264_videotoolbox -pix_fmt yuv420p -b:v 6000k output.mp4

3. Screen Recording with Microphone Audio

To capture both the display and an audio source (e.g., screen 1 and microphone 0), update the input format to "1:0" and specify an audio encoder such as aac:

ffmpeg -f avfoundation -framerate 60 -i "1:0" -c:v h264_videotoolbox -b:v 6000k -pix_fmt yuv420p -c:a aac -b:a 192k output.mp4

Parameter Breakdown

  • -f avfoundation: Instructs FFmpeg to use macOS's native AVFoundation multimedia framework.
  • -framerate 60: Sets the target capture frame rate to 60 frames per second (can be reduced to 30 to lower file size).
  • -i "<video_index>:<audio_index>": Specifies the input sources. Use none for audio if you do not want sound.
  • -c:v h264_videotoolbox: Utilizes Apple's hardware-accelerated H.264 encoder. For HEVC (H.265), replace this with hevc_videotoolbox.
  • -b:v 6000k: Sets the target video bitrate to 6 Mbps. You can increase this for higher fidelity or decrease it for smaller file sizes.
  • -pix_fmt yuv420p: Converts the pixel format to YUV 4:2:0, ensuring broad compatibility across QuickTime, web browsers, and media players.
  • -c:a aac -b:a 192k: Encodes the audio stream using AAC at 192 kbps.

Permissions Notice

When running FFmpeg from the Terminal for the first time, macOS will prompt for permissions under System Settings > Privacy & Security. Ensure that Screen Recording and Microphone permissions are granted to Terminal (or your preferred terminal emulator) to prevent capture errors.