How to Set 3D Metadata in MP4 and MKV Using FFmpeg

Setting stereoscopic 3D metadata ensures that 3D TVs, VR headsets, and media players automatically detect the correct layout—such as Side-by-Side (SBS) or Top-and-Bottom (TAB)—without requiring manual configuration. This guide outlines how to inject stereoscopic metadata into Matroska (MKV) and MP4 containers using FFmpeg, covering both lossless container-level tagging and codec-level bitstream injection.

Setting 3D Metadata in MKV Containers

The Matroska (MKV) format natively supports stereoscopic tags through the StereoMode container element. This can be applied instantly without re-encoding the video using stream copying (-c copy).

The FFmpeg Command

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

Supported Layout Values

You can replace left_right with any of the following standard Matroska stereo layouts:

Layout Name	Value	Description
Side-by-Side (Left Eye First)	`left_right` or `1`	Left eye on the left, right eye on the right
Side-by-Side (Right Eye First)	`right_left` or `2`	Right eye on the left, left eye on the right
Top-and-Bottom (Right Eye First)	`bottom_top` or `3`	Right eye on top, left eye on bottom
Top-and-Bottom (Left Eye First)	`top_bottom` or `4`	Left eye on top, right eye on bottom

Setting 3D Metadata in MP4 Containers

The MP4 container specification relies primarily on H.264/H.265 Supplemental Enhancement Information (SEI) Frame Packing Arrangement messages rather than simple container flags.

Method 1: Encoding with x264 Frame Packing Flags

If you are encoding or re-encoding your video, you can pass the frame-packing parameter directly to the libx264 encoder.

Side-by-Side (SBS):

ffmpeg -i input.mov -c:v libx264 -x264-params "frame-packing=3" -c:a copy output.mp4

Top-and-Bottom (Over/Under):

ffmpeg -i input.mov -c:v libx264 -x264-params "frame-packing=4" -c:a copy output.mp4

Standard Frame Packing Values for H.264:

3: Side-by-Side (Left eye first)
4: Top-and-Bottom (Left eye first)
5: Frame Sequential

Method 2: Using the `stereo3d` Filter

If you need FFmpeg to automatically handle both layout transformations and metadata assignment during a transcode, use the stereo3d video filter.

To set Side-by-Side metadata while maintaining the existing SBS frame layout:

ffmpeg -i input.mp4 -vf "stereo3d=sbsl:sbsl" -c:v libx264 -crf 18 -c:a copy output.mp4

To set Top-and-Bottom metadata while maintaining the existing layout:

ffmpeg -i input.mp4 -vf "stereo3d=abl:abl" -c:v libx264 -crf 18 -c:a copy output.mp4

Verifying the Metadata

To verify that the stereoscopic metadata was correctly embedded, inspect the file with ffprobe:

ffprobe -show_streams input.mkv

Look for the DISPOSITION or SIDE_DATA blocks in the output. A successfully tagged file will display an entry such as:

Side data:
    stereo3d: side by side