Add 360 Spherical Metadata to MP4 Using FFmpeg

This guide explains how spherical 360-degree video metadata (equirectangular projection) is handled within an MP4 container and how to apply it using FFmpeg and complementary command-line utilities. While FFmpeg natively preserves and passes through spherical metadata during encoding and remuxing, it does not feature an internal command-line flag to synthesize new spherical atoms from scratch. The sections below cover how to preserve metadata in FFmpeg, inject missing equirectangular metadata using standard CLI tools, and verify the resulting file.

How 360 Metadata Works in MP4

For a video player or platform (such as YouTube, VLC, or Meta Quest) to recognize a video as 360-degree equirectangular footage, the MP4 container must contain specific metadata. This is typically stored in one of two formats:

  1. The sv3d Box: An ISO base media file format standard atom that defines spherical video layout and projection parameters.
  2. The Google Spherical Video UUID Box: A custom MP4 atom containing an XML payload defining <rdf:SphericalVideo> tags.

FFmpeg's MP4 muxer (movenc) automatically generates the sv3d atom if the input stream already contains spherical packet side data (AV_PKT_DATA_SPHERICAL). However, FFmpeg cannot generate this side data from a flat video file without prior metadata.

Preserving 360 Metadata During FFmpeg Processing

If your source file already contains 360-degree metadata, FFmpeg can process or re-encode the stream without stripping the spherical tags.

1. Lossless Stream Copy

To trim, remux, or swap audio while preserving existing spherical tags, use stream copy mode:

ffmpeg -i input_360.mp4 -c copy output_360.mp4

2. Re-encoding Video

When re-encoding equirectangular video (for example, applying compression or changing codecs), modern FFmpeg builds forward the video stream's side data automatically to the output MP4 container:

ffmpeg -i input_360.mp4 -c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k output_360.mp4

Injecting Missing 360 Metadata into an MP4

If you rendered an equirectangular video from 3D software or an editor that output a "flat" MP4 without metadata, you must inject the metadata atom. The following CLI tools provide the fastest and most reliable methods.

ExifTool can write the equirectangular projection tags directly into an existing MP4 file in place without re-encoding:

exiftool -ProjectionType="equirectangular" video.mp4

To add full 360 metadata including stereoscopic configuration if needed:

# For Monoscopic 360:
exiftool -ProjectionType="equirectangular" -UseEcho="true" video.mp4

# For Stereoscopic (Top-Bottom) 360:
exiftool -ProjectionType="equirectangular" -StereoMode="top-bottom" video.mp4

Option 2: Using Google Spatial Media Metadata Injector

Google provides the reference CLI utility for injecting the spherical XML atom required by YouTube and most web players:

  1. Install the tool using Python:

    pip install spatialmedia

  2. Inject the equirectangular metadata:

    python -m spatialmedia -i input.mp4 output_360.mp4

For top-bottom stereoscopic 360:

python -m spatialmedia -i --stereo=top-bottom input.mp4 output_360.mp4

Option 3: Using MP4Box (GPAC)

If you use GPAC tools alongside FFmpeg, MP4Box can inject the native sv3d box into the MP4 container:

MP4Box -add video.mp4:sv3d=proj=equi output_360.mp4

Verifying 360 Metadata with FFprobe

To confirm that the MP4 container now possesses spherical metadata, run ffprobe to inspect the video stream's side data:

ffprobe -v error -show_entries stream_side_data_list -select_streams v:0 input.mp4

A properly tagged file will output side data matching the following structure:

[SIDE_DATA]
side_data_type=Spherical Mapping
projection=equirectangular
yaw=0
pitch=0
roll=0
[/SIDE_DATA]