Set Stereoscopic 3D Metadata in MP4 and MKV with FFmpeg

This guide explains how to inject stereoscopic 3D metadata into MP4 and MKV video containers using FFmpeg. You will learn the exact command-line arguments needed to flag your video files as side-by-side or top-and-bottom 3D, allowing compatible media players, VR headsets, and 3D TVs to automatically recognize and display the content in 3D mode without requiring manual configuration.

Setting 3D Metadata in MKV Containers

The Matroska (MKV) container has native support for stereoscopic video layout flags using the -stereo_mode option. This method modifies the container metadata directly without re-encoding the video stream.

Side-by-Side (Left Eye First)

To set the metadata for a horizontal side-by-side (SBS) layout, use the following command:

ffmpeg -i input.mp4 -c copy -stereo_mode side_by_side_lr output.mkv

Top-and-Bottom (Left Eye First)

To set the metadata for a vertical top-and-bottom (over-under) layout, use this command:

ffmpeg -i input.mp4 -c copy -stereo_mode top_bottom_lr output.mkv

Other MKV Stereo Mode Values

If your video uses a different stereoscopic layout, you can substitute the -stereo_mode argument with one of these common values: * side_by_side_rl (Side-by-side, right eye first) * top_bottom_rl (Top-and-bottom, right eye first) * checkerboard_rl (Checkerboard, right eye first) * checkerboard_lr (Checkerboard, left eye first) * row_interleaved_rl (Row interleaved, right eye first) * row_interleaved_lr (Row interleaved, left eye first)

Setting 3D Metadata in MP4 Containers

The MP4 container does not handle stereoscopic flags at the container level as cleanly as MKV. Instead, stereoscopic metadata must be injected directly into the video bitstream’s Supplemental Enhancement Information (SEI) using FFmpeg’s bitstream filters. This process edits the stream headers without re-encoding the actual video.

For H.264 (AVC) Video Streams

Use the h264_metadata bitstream filter. The frame_packing option dictates the 3D layout:

• Value 3: Side-by-Side (horizontal sub-sampling)
• Value 4: Top-and-Bottom (vertical sub-sampling)

Side-by-Side (SBS):

ffmpeg -i input.mp4 -c copy -bsf:v h264_metadata=frame_packing=3 output.mp4

Top-and-Bottom (Over/Under):

ffmpeg -i input.mp4 -c copy -bsf:v h264_metadata=frame_packing=4 output.mp4

For H.265 (HEVC) Video Streams

If your input file uses the HEVC codec, use the hevc_metadata bitstream filter with the same frame packing values.

Side-by-Side (SBS):

ffmpeg -i input.mp4 -c copy -bsf:v hevc_metadata=frame_packing=3 output.mp4

Top-and-Bottom (Over/Under):

ffmpeg -i input.mp4 -c copy -bsf:v hevc_metadata=frame_packing=4 output.mp4