Add 360 Spherical Metadata to MP4 Using FFmpeg

Injecting spherical metadata into an MP4 file is essential for video players and social media platforms to recognize and display your video in an interactive 360-degree format. This article provides the exact FFmpeg commands needed to embed equirectangular projection metadata into your MP4 container without re-encoding your video.

To add 360-degree metadata to an MP4 video, you can use FFmpeg’s built-in spherical video option (-sv3d). This option writes the sv3d box into the MP4 container, which defines the video projection type.

The Basic Command for Monoscopic 360 Video

For standard (monoscopic) 2D 360-degree videos using equirectangular projection, use the following command:

ffmpeg -i input.mp4 -c copy -sv3d equirectangular output.mp4

Command Breakdown: * -i input.mp4: Specifies your source video file. * -c copy: Instructs FFmpeg to stream-copy the video and audio. This avoids re-encoding, preserving the original quality and completing the process instantly. * -sv3d equirectangular: Injects the spherical 3D metadata box, specifying the projection as equirectangular. * output.mp4: The path for the newly generated 360-degree compatible video file.

Command for Stereoscopic (3D) 360 Video

If your video is stereoscopic (3D 360) where the left-eye and right-eye views are stacked, you must specify the layout using the stereo3d filter before injecting the spherical metadata. Note that because video filters are applied, the video stream must be re-encoded rather than copied:

For a top-bottom (over-under) layout:

ffmpeg -i input.mp4 -vf "stereo3d=in=tb:out=tb" -sv3d equirectangular -c:v libx264 -crf 18 -c:a copy output.mp4

Verifying the Metadata

Once the process is complete, you can verify that the spherical metadata has been successfully injected using the ffprobe tool:

ffprobe -v error -show_entries stream_side_data_list -of default=noprint_wrappers=1 output.mp4

If successful, the console output will display side_data_type=Spherical Video, indicating that media players and online platforms will now correctly render the video as an interactive 360-degree sphere.