How to Align MKV Clusters with Keyframes in FFmpeg

Aligning Matroska (MKV) clusters with keyframe boundaries in FFmpeg is essential for creating highly seekable, streamable, and adaptive bitrate-friendly video files. This article provides a straightforward guide on how to configure the FFmpeg MKV muxer using the -dash flag and encoder settings to force cluster creation exactly at video keyframes.

Understanding MKV Clusters and Keyframes

In an MKV container, media data is organized into “clusters.” By default, the FFmpeg Matroska muxer writes clusters based on default time limits (typically every 5 seconds) or size limits. However, for seamless seeking and chunk-based streaming (like DASH), clusters must begin precisely with an IDR frame (keyframe).

The Solution: Using the -dash Muxer Flag

The most direct way to force the FFmpeg MKV muxer to output clusters at keyframe boundaries is by enabling the dash private muxer option. When set to 1, this option forces the container to start a new cluster at every keyframe.

Here is the basic command template:

ffmpeg -i input.mp4 -c:v libx264 -dash 1 output.mkv

Step-by-Step Configuration

To ensure perfect alignment, you must configure both the video encoder (to generate keyframes at predictable intervals) and the MKV muxer (to split clusters at those keyframes).

1. Configure the Encoder GOP Size

You must tell the video encoder how often to place a keyframe. For example, if your video is 30 frames per second (fps) and you want a keyframe every 2 seconds, set the GOP (Group of Pictures) size to 60.

• -g 60: Sets the maximum keyframe interval to 60 frames.
• -keyint_min 60: Sets the minimum keyframe interval to 60 frames (forces a consistent interval).
• -sc_threshold 0: Disables scene-change detection to prevent the encoder from inserting extra, unexpected keyframes.

2. Apply the MKV Muxer Options

• -f matroska: Specifies the Matroska container format.
• -dash 1: Forces cluster boundaries to align with the keyframes generated by the encoder.

Complete Command Example

Combine these settings into a single command to transcode a video with clusters locked to keyframe boundaries:

ffmpeg -i input.mp4 \
  -c:v libx264 -g 60 -keyint_min 60 -sc_threshold 0 \
  -c:a aac \
  -f matroska -dash 1 output.mkv

Verifying the Output

To verify that your MKV file has clusters aligned with keyframes, you can use ffprobe to analyze the packet structure:

ffprobe -show_packets -select_streams v output.mkv

Look for the flags=K_ (keyframe) packet designation. With -dash 1 enabled, every packet marked as a keyframe will correspond directly to the start of a new cluster block in the container payload.