How to Use the FFmpeg Shuffleframes Filter

The FFmpeg shuffleframes filter allows you to reorder, duplicate, or drop video frames within recurring blocks of a specified size. This guide explains how the filter functions, details the index-mapping syntax, and provides practical command-line examples for swapping, repeating, and deleting frames inside recurring segments.

Understanding the shuffleframes Syntax

The shuffleframes filter takes a space-separated list of zero-based indices. The total count of indices you provide sets the block size. During processing, FFmpeg inspects each block of that size and outputs the frames in the exact order specified by your list.

The basic filter syntax is:

-vf "shuffleframes=index_0 index_1 ... index_N"
  • Indices: Zero-based integers (0, 1, 2, ...) referencing the original positions of frames in the block.
  • Repeating: Using the same index more than once duplicates that frame.
  • Dropping: Using -1 discards the frame at that output slot.

Rearranging Frames

To reorder frames, write the indices in your desired output sequence.

Swap Adjacent Pairs
To swap every consecutive pair of frames (frame 0 with 1, frame 2 with 3, etc.):

ffmpeg -i input.mp4 -vf "shuffleframes=1 0" -c:a copy output.mp4

Reverse 4-Frame Blocks
To invert the playback direction in recurring 4-frame increments:

ffmpeg -i input.mp4 -vf "shuffleframes=3 2 1 0" -c:a copy output.mp4

Repeating Frames

You can repeat frames within a block by referencing the same source index multiple times.

Duplicate Every Frame
To output each frame twice within a two-frame block, doubling the output frame count:

ffmpeg -i input.mp4 -vf "shuffleframes=0 0 1 1" -c:a copy output.mp4

Freeze-and-Skip Pattern
To stretch the first frame across three slots and output the final frame of a 4-frame segment:

ffmpeg -i input.mp4 -vf "shuffleframes=0 0 0 3" -c:a copy output.mp4

Dropping Frames

Assigning -1 instructs FFmpeg to omit a frame from the output sequence entirely.

Drop Every Second Frame
To keep the first frame of a pair and drop the second:

ffmpeg -i input.mp4 -vf "shuffleframes=0 -1" -c:a copy output.mp4

Reorder and Drop Combined
In a 4-frame block, to emit frame 2 first, drop frame 1, emit frame 0, and emit frame 3:

ffmpeg -i input.mp4 -vf "shuffleframes=2 -1 0 3" -c:a copy output.mp4

Managing Timestamps and Audio

Because shuffleframes alters frame sequences and counts, audio may fall out of sync if frames are duplicated or dropped over time.

If you are changing the total frame count (adding or dropping frames), append the fps filter or adjust the presentation timestamps (PTS) using setpts to maintain proper playback timing:

ffmpeg -i input.mp4 -vf "shuffleframes=0 0 1 1,setpts=N/(FPS*TB)" -c:a copy output.mp4