Extract Frame Timestamps and Keyframe Flags with ffprobe

This article explains how to use ffprobe—the multimedia stream analyzer included with the FFmpeg suite—to extract individual frame presentation timestamps (PTS) and identify keyframe flags from a video file. You will learn the specific command-line arguments needed to query this metadata and format the output as CSV or JSON for easy analysis.

The Basic Command for Frame Metadata

To extract the presentation timestamp and keyframe status for every frame in a video, run the following command in your terminal:

ffprobe -v error -select_streams v:0 -show_entries frame=pkt_pts_time,key_frame,pict_type -of csv=p=0 input.mp4

Command Breakdown

• -v error: Quiets the console output, suppressing the build configuration banner and showing only error messages and your requested data.
• -select_streams v:0: Targets only the first video stream, ignoring audio and subtitle tracks.
• -show_entries frame=pkt_pts_time,key_frame,pict_type: Specifies the exact fields to extract for each frame:
  • pkt_pts_time: The timestamp of the frame in seconds.
  • key_frame: A binary flag where 1 indicates a keyframe (I-frame) and 0 indicates a non-keyframe (P-frame or B-frame).
  • pict_type: The specific frame type represented by a single character (I, P, or B).
• -of csv=p=0: Formats the output as Comma-Separated Values (CSV) and hides the column headers (p=0), printing only the raw data.

The output will display line-by-line values for each frame:

0.000000,1,I
0.040000,0,B
0.080000,0,P

Exporting to JSON Format

If you are parsing the data with Python, JavaScript, or another programming language, exporting the metadata to JSON is often more convenient.

ffprobe -v error -select_streams v:0 -show_entries frame=pkt_pts_time,key_frame,pict_type -of json input.mp4

This returns a structured JSON object containing a frames array:

{
    "frames": [
        {
            "pkt_pts_time": "0.000000",
            "key_frame": 1,
            "pict_type": "I"
        },
        {
            "pkt_pts_time": "0.040000",
            "key_frame": 0,
            "pict_type": "B"
        }
    ]
}

Filtering and Extracting Keyframes Only

If you only want to retrieve the timestamps of the keyframes (I-frames) and skip all intermediary frames, you can instruct ffprobe to discard non-keyframes using the -skip_frame option:

ffprobe -v error -skip_frame nokey -select_streams v:0 -show_entries frame=pkt_pts_time -of csv=p=0 input.mp4

This command outputs a clean list of timestamps corresponding exclusively to the video’s keyframes, which is highly useful for identifying optimal video cutting points.