Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

Automate Insta360 360-degree video processing tasks, no GUI
https://github.com/syncom/insta360-cli-utils

Last synced: 4 days ago
JSON representation

Automate Insta360 360-degree video processing tasks, no GUI

Awesome Lists containing this project

README 

        
# 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](https://www.insta360.com/download/insta360-x3) (Insta360's desktop

editing software).



## 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](https://www.insta360.com/sdk/home), get approved,

  and download the Insta360 media SDK for Linux

  - The media SDK I have access to is `LinuxSDK20231211.zip`. It contains a

    pre-built package `libMediaSDK-dev_2.0-0_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.



   ```bash

   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.



   ```bash

   # 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.



   ```bash

   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



   ```bash

   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](https://www.videolan.org/) 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,



   ```bash

   # 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



```bash

# 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.



```bash

Usage: join-insv

    [ -H | --is_57k ]

    [ -o | --output outfile ]

    [ -h | --help ]

     [infiles]

```