FFmpeg: Unsupported Frame Rate for Screen Recording on macOS

Understanding the Error Cause

The error typically appears when FFmpeg attempts to initialize the avfoundation input device on macOS. Unlike Linux or Windows where hardware encoders might handle variable inputs gracefully, macOS's Quartz Display Copying Service often outputs frames at irregular intervals, especially when the system load fluctuates or when displaying content with dynamic refresh rates like animations or videos.

When you run a command without specifying a fixed frame rate, FFmpeg tries to infer the rate from the incoming stream. If the inferred rate is non-standard (such as 59.94 fps instead of 60 fps) or if the container format requires a strict integer value, the muxer will reject the stream. This results in errors stating that the frame rate is unsupported or that the stream is corrupted.

Common Scenarios

• High Refresh Rate Monitors: If your Mac is connected to a 120Hz or 144Hz display, the default capture may attempt to record at these higher rates, which many standard MP4 containers do not handle well by default.
• Variable Frame Rate (VFR): Some applications or desktop environments output VFR streams. FFmpeg’s default behavior for certain codecs may struggle to pack these into a Constant Frame Rate (CFR) container without explicit instructions.
• Incorrect Pixel Format: While less common for this specific error, mismatched pixel formats can sometimes compound timing issues, leading to broader initialization failures.

Solving the Issue with the -r Flag

The primary solution is to explicitly set the frame rate using the -r option in your FFmpeg command. This forces FFmpeg to either drop or duplicate frames to match the specified rate, ensuring the output stream is compliant with standard video specifications. For most use cases, setting the rate to 30 or 60 frames per second resolves the incompatibility.

ffmpeg -f avfoundation -framerate 30 -i "0:0" -c:v libx264 -pix_fmt yuv420p output.mp4

In this example, -framerate 30 tells the input device to sample at 30 frames per second. Note that -framerate is an input option, while -r can be used as an output option to re-encode if necessary. Using -framerate at the input stage is generally more efficient as it reduces the processing load on the encoder.

Configuring AVFoundation Input Correctly

On macOS, FFmpeg uses the avfoundation demuxer to access the screen. It is crucial to understand how to specify the correct devices. The input format is typically "index:index", where the first index refers to the video device (screen) and the second to the audio device (microphone).

Identifying Your Devices

To find the correct indices, list all available AVFoundation devices by running:

ffmpeg -f avfoundation -list_devices true -i ""

This command will output a list similar to:

[avfoundation @ ...] List of supported devices:
[avfoundation @ ...] 0: Capture screen 0
[avfoundation @ ...] 1: FaceTime HD Camera
[avfoundation @ ...] 2: Built-in Microphone

If you are experiencing frame rate issues, ensure you are selecting the correct screen index. Sometimes, multiple monitors can cause confusion in indexing. Use the exact number shown in the list for your primary display.

Advanced Settings for Stability

If simply setting the frame rate does not resolve the issue, consider adjusting other parameters to stabilize the stream. Adding -vsync vfr or -vsync cfr can help manage timestamp synchronization, though this is rarely needed if the frame rate is fixed correctly.

Additionally, specifying the pixel format explicitly can prevent encoding errors that might masquerade as frame rate issues. The -pix_fmt yuv420p flag is widely compatible with almost all players and web platforms.

ffmpeg -f avfoundation -framerate 60 -i "0:1" -c:v libx264 -preset fast -crf 18 -pix_fmt yuv420p output.mp4

This command records both screen (0) and audio (1) at 60 fps. The -preset fast balances CPU usage and encoding speed, while -crf 18 provides high-quality output. Adjust the -crf value between 18 and 28 based on your storage constraints.

Alternative Tools and Considerations

If FFmpeg continues to fail despite correct configuration, the issue might lie deeper within macOS permissions or driver conflicts. Ensure that Terminal has Screen Recording permissions enabled in System Preferences > Security & Privacy > Privacy > Screen Recording. Without this permission, FFmpeg may receive incomplete or malformed data streams.

For users who frequently need high-fidelity screen captures, dedicated software like OBS Studio or QuickTime Player may offer more robust handling of variable frame rates out of the box. However, for automated scripts or headless servers, FFmpeg remains the best choice once configured correctly.

If you are troubleshooting network-related issues alongside recording problems, such as latency affecting stream stability, you might also want to check your DNS settings. Proper configuration can prevent intermittent connectivity drops that might interfere with remote recording setups.

Frequently Asked Questions

Why does my recorded video look choppy even after setting -r?

Choppiness usually indicates that the system cannot maintain the requested frame rate due to CPU overload or inefficient encoding presets. Try switching from -preset ultrafast to -preset medium or slow to allow the encoder more time to process frames smoothly, reducing dropped frames.

Can I record at 120fps on a 120Hz monitor with FFmpeg?

Yes, but you must ensure your hardware can sustain the write speed and CPU encoding load. Set -framerate 120 and use a lightweight codec like libx264 with a -preset fast. Be aware that file sizes will increase significantly compared to 30fps recordings.

What if FFmpeg still says 'Unsupported pixel format'?

This error often occurs when the source stream uses a format incompatible with the target container. Explicitly add -pix_fmt yuv420p to your command line to convert the pixel format on the fly, which is universally supported by MP4 containers and media players.

How do I record only a specific region of the screen?

Use the -video_size and -i offset options. For example, -video_size 1920x1080 -i "0:0+100,100" records a 1920x1080 area starting at coordinates (100, 100). Combine this with -framerate to ensure stable timing for the cropped region.

Is there a way to automatically detect the best frame rate?

FFmpeg does not have a built-in auto-detect flag for optimal frame rates. You must manually specify it based on your content. For general desktop use, 30fps is sufficient; for gaming or smooth animations, 60fps is recommended. Always test with a short clip first to verify performance.