Force Keyframe-Aligned GOPs in ABR Streams with FFmpeg

The Problem: ABR Stream Hitching

Adaptive Bitrate (ABR) streaming relies on players seamlessly switching between different video quality renditions. A smooth transition, known as a down-switch or up-switch, requires that both the current rendition and the target rendition have a keyframe (an IDR frame in H.264/H.265) at the exact same media time. When this alignment breaks, the player cannot immediately display the new rendition without a visual stutter or a brief freeze. This is often reported as zero rebuffering events in Quality of Experience (QoE) dashboards because, technically, the stream is still playing. The issue isn't a lack of data, but a collision at the seam between renditions. This problem commonly surfaces with FFmpeg versions 7.x and is reproducible with both x264 and NVENC encoders, as well as verification tools like MP4Box from the GPAC suite.

The Solution: Consistent Keyframe Cadence

The core principle to achieve keyframe alignment across an ABR ladder is to enforce a single, consistent keyframe interval for all renditions. This interval is typically determined by the desired segment duration and the video's framerate. A common practice is to set the keyframe interval to be equal to the segment duration. For example, if you are segmenting your video into 2-second chunks and your framerate is 30 frames per second, you would aim for a keyframe every 60 frames (2 seconds * 30 fps). FFmpeg provides parameters to control this behavior directly during encoding.

Implementing Keyframe Alignment with FFmpeg

To force keyframe alignment, you need to configure FFmpeg's encoding parameters meticulously. The primary parameters involved are related to the Group of Pictures (GOP) structure and the insertion of keyframes.

Key FFmpeg Parameters:

• -g [keyframe_interval]: This sets the maximum number of frames between keyframes. It's crucial to set this value consistently across all your ABR renditions.
• -keyint_min [keyframe_interval]: This ensures that keyframes are inserted at least this frequently, preventing overly long GOPs. Setting this equal to -g is a common strategy.
• -sc_threshold [value]: This parameter influences scene change detection for keyframe insertion. While often useful, for strict alignment, it's often best to disable automatic scene change keyframes or set a very high value if relying solely on the fixed interval.
• -force_key_frames 'expr:gte(t,n_forced*KEYFRAME_INTERVAL)': This is a more explicit way to force keyframes at exact time intervals, irrespective of scene changes. For instance, `expr:gte(t,n_forced*2)` would force a keyframe every 2 seconds. This is particularly powerful when combined with a fixed segment duration.

Example FFmpeg Command Structure:

When building an ABR ladder, you would apply these settings uniformly to each encoding pass. The goal is to ensure that if your segment duration is 2 seconds, each rendition will have a keyframe at 0s, 2s, 4s, 6s, and so on, regardless of resolution or bitrate.

Consider an ABR ladder with renditions at 1080p, 720p, and 480p, each segmented into 2-second chunks. The FFmpeg commands for each would look similar:

# For 1080p rendition
ffmpeg -i input.mp4 -c:v libx264 -preset medium -b:v 3000k -g 60 -keyint_min 60 -sc_threshold 0 -force_key_frames "expr:gte(t,n_forced*2)" -c:a aac -b:a 128k -f hls -hls_time 2 -hls_playlist_type vod -hls_segment_filename "1080p_%03d.ts" output_1080p.m3u8

# For 720p rendition (adjust bitrate and potentially other params)
ffmpeg -i input.mp4 -c:v libx264 -preset medium -b:v 1500k -g 60 -keyint_min 60 -sc_threshold 0 -force_key_frames "expr:gte(t,n_forced*2)" -c:a aac -b:a 96k -f hls -hls_time 2 -hls_playlist_type vod -hls_segment_filename "720p_%03d.ts" output_720p.m3u8

# For 480p rendition (adjust bitrate and potentially other params)
ffmpeg -i input.mp4 -c:v libx264 -preset medium -b:v 800k -g 60 -keyint_min 60 -sc_threshold 0 -force_key_frames "expr:gte(t,n_forced*2)" -c:a aac -b:a 64k -f hls -hls_time 2 -hls_playlist_type vod -hls_segment_filename "480p_%03d.ts" output_480p.m3u8

In this example, -g 60 and -keyint_min 60 are set assuming a 30fps source, making the GOP size 60 frames (2 seconds). The -force_key_frames "expr:gte(t,n_forced*2)" explicitly ensures keyframes appear at 0s, 2s, 4s, etc., overriding any scene change logic. The -sc_threshold 0 further discourages automatic keyframe insertion based on scene changes.