How to Add I-FRAMES-ONLY to HLS Playlists in FFmpeg

This article explains how to use the hls_flags parameter in FFmpeg to generate an HLS playlist containing the #EXT-X-I-FRAMES-ONLY tag. You will learn the exact FFmpeg command required to enable this flag and how to correctly configure your video settings to output a valid I-frame-only playlist for scrubbing and trick-play features.

Understanding the I-FRAMES-ONLY Tag

The #EXT-X-I-FRAMES-ONLY tag in an HTTP Live Streaming (HLS) playlist indicates to media players that the segments in the playlist contain only keyframes (I-frames). This is essential for implementing "trick play" features, such as fast-forward, rewind, and visual scrubbing, because the player can quickly download and render these small keyframe-only segments without decoding the entire video stream.

The FFmpeg Command for I-FRAMES-ONLY

To add the #EXT-X-I-FRAMES-ONLY tag to your playlist, you must pass the iframes_only value to the -hls_flags parameter.

However, simply adding the flag does not force FFmpeg to output only I-frames; it merely adds the tag to the playlist header. To ensure the playlist is valid, you must combine this flag with video filters or encoding settings that strip out non-keyframes (P-frames and B-frames).

Here is the complete FFmpeg command to generate a valid I-frame-only playlist:

ffmpeg -i input.mp4 \
  -vf "select='eq(pict_type,I)'" -vsync vfr \
  -an \
  -f hls \
  -hls_flags iframes_only \
  -hls_time 2 \
  -hls_playlist_type vod \
  output_iframe.m3u8

Command Breakdown:

  • -i input.mp4: Specifies the source video file.
  • -vf "select='eq(pict_type,I)'" -vsync vfr: This video filter selects only the keyframes (I-frames) from the source video and discards all other frames. -vsync vfr (variable frame rate) prevents FFmpeg from duplicating frames to maintain the original frame rate.
  • -an: Disables audio, as I-frame playlists for trick play do not require audio tracks.
  • -f hls: Specifies the output format as HLS.
  • -hls_flags iframes_only: Adds the #EXT-X-I-FRAMES-ONLY tag to the header of the output .m3u8 playlist file.
  • -hls_time 2: Sets the target segment length (in seconds).
  • output_iframe.m3u8: The name of the output index file.

Verifying the Output

Once the command finishes processing, open the generated output_iframe.m3u8 file in a text editor. The header will include the required tag:

#EXTM3U
#EXT-X-VERSION:4
#EXT-X-I-FRAMES-ONLY
#EXT-X-TARGETDURATION:2
#EXT-X-MEDIA-SEQUENCE:0
...

If you are building a master playlist, you should reference this generated I-frame playlist using the #EXT-X-I-FRAME-STREAM-INF tag to point players to the scrubbing stream.