Insta360 360-degree video processing in command-line

This repository contains the utility and instructions to process Insta360 360-degree videos (with extension .insv) from the command line, without using the Insta360 Studio (Insta360's desktop editing software).

If you are a Linux user, this utility can come in handy, because as of early 2025, Insta360 Studio has not shipped a Linux version.

Prerequisites

• A machine that runs Docker
• Enough free space on your local file system to store original and processed video files
• Fill out the application, get approved, and download the Insta360 media SDK for Linux
  • The latest media SDK I have access to is LinuxSDK20241128.zip. It contains a pre-built package libMediaSDK-dev_2.0-6_amd64_ubuntu18.04.deb for Ubuntu 18.04, which is the only file I need from the zip

My workflow for converting and joining 360-degree videos

1. Clone this repo.

   git clone https://github.com/syncom/insta360-cli-utils.git

2. Extract the aforementioned .deb file from the media SDK zip, and put it under the directory root of the just cloned repository.

3. Build the Docker container image in which the SDK is installed.

   # Under repo's directory root
   docker build --tag ubuntu:insta360 .

4. Run the container, mounting host directory datadir/ to the container's path /root/, for host-container data sharing.

   docker run -v "$(pwd)/datadir":/root/datadir -it ubuntu:insta360

   Copy/move .insv files to "$(pwd)/datadir" on host, for processing in the container.

5. Inside the Docker container, in shell prompt

   MERGED_VIDEO="merged.mp4"
   MERGED_VIDEO_360="merged360.mp4"
   
   # Change to the host-mapped data directory in container
   cd datadir/
   
   # Convert to MP4, for 4K and lower resolution videos
   for i in *.insv; do \
     MediaSDKTest -inputs "$i" -output "${i}.mp4" \
     -enable_directionlock -enable_flowstate -enable_denoise
   done
   # Join MP4 files into one (assuming file names are sorted in time order)
   ls *.mp4 > list.txt
   sed -i.bak 's/^/file /g' list.txt
   ffmpeg -safe 0 -f concat -i list.txt -vcodec copy -acodec copy "$MERGED_VIDEO"
   # Inject metadata (RDF/XML GSpherical tags)
   exiftool -XMP-GSpherical:Spherical="true" \
    -XMP-GSpherical:Stitched="true" \
    -XMP-GSpherical:ProjectionType="equirectangular" \
    -XMP-GSpherical:StereoMode="mono" \
    -api largefilesupport=1 \
    "$MERGED_VIDEO" \
    -o "$MERGED_VIDEO_360"

   "$MERGED_VIDEO_360" is the merged 360-degree video that can be viewed in VLC media player or uploaded to YouTube as a 360 video.

   For 5.7K videos, separate video files like /path/to/VID_20240528_113402_00_032.insv and /path/to/VID_20240528_113402_10_032.insv are generated by the camera for the left-eye and right-eye views. Both files need to be supplied to the -input argument of MediaSDKTest, in the aforementioned order. For example,

   # For 5.7K video
   MediaSDKTest \
     -inputs VID_20240528_113402_00_032.insv VID_20240528_113402_10_032.insv \
     -output "both_eyes.mp4" \
     -enable_directionlock -enable_flowstate -enable_denoise

Utility: join-insv

The utility join-insv is available in the container to automate the above workflow. Example

# For 4K and lower resolution
join-insv --output /path/to/merged_360video.mp4 \
  /path/to/input-1. insv /path/to/input-2.insv ...

# For 5.7K
join-insv --output /path/to/merged_5.7k_360video.mp4 \
  /path/to/VID_20240528_113402_00_001.insv /path/to/VID_20240528_113402_10_001.insv \
  /path/to/VID_20240528_120003_00_002.insv /path/to/VID_20240528_120003_10_002.insv \
  ...

The synopsis of join-insv is as follows.

Usage: join-insv
    [ -H | --is_57k ]
    [ -o | --output outfile ]
    [ -h | --help ]
    <infile> [infiles]