From 64d527c980d30485ced6503228bf9e65110e65f7 Mon Sep 17 00:00:00 2001 From: Matthias Hryniszak Date: Tue, 2 Jun 2026 13:52:24 +0200 Subject: [PATCH 1/5] Updated MediaSDK and dependencies to version 3.1.1.0-20250922_191110 --- .gitignore | 2 ++ Dockerfile | 11 +++++++---- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index ba34711..9924098 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ libMediaSDK-dev_2.0-0_amd64_ubuntu18.04.deb libMediaSDK-dev_2.0-6_amd64_ubuntu18.04.deb +libMediaSDK-dev-3.1.1.0-20250922_191110-amd64.deb **/.DS_Store +datadir/** diff --git a/Dockerfile b/Dockerfile index cdf580c..0fa5be8 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,12 +1,15 @@ # For exiftool 12.40 FROM ubuntu:22.04 -ARG MEDIASDK_UBUNTU_DEB=libMediaSDK-dev_2.0-6_amd64_ubuntu18.04.deb +ARG MEDIASDK_UBUNTU_DEB=libMediaSDK-dev-3.1.1.0-20250922_191110-amd64.deb ENV PATH="${PATH}:/root/scripts" -RUN apt update && apt install software-properties-common -y && \ - apt install curl git build-essential libjpeg-dev libtiff-dev ffmpeg exiftool bc -y +RUN apt update && \ + apt install -y software-properties-common && \ + apt install -y curl git build-essential libjpeg-dev libtiff-dev ffmpeg exiftool bc libvulkan1 libvulkan-dev vulkan-tools libglfw3-dev libdc1394-dev mesa-utils && \ + rm -rf /var/lib/apt/lists/* + WORKDIR /root COPY ${MEDIASDK_UBUNTU_DEB} . RUN dpkg -i ${MEDIASDK_UBUNTU_DEB} -COPY scripts scripts \ No newline at end of file +COPY scripts scripts From d6ac1a99a1dfb8a110c82839ee2c635d194e83a6 Mon Sep 17 00:00:00 2001 From: Matthias Hryniszak Date: Tue, 2 Jun 2026 13:52:51 +0200 Subject: [PATCH 2/5] Added script to start the container with all necessary options --- start.sh | 3 +++ 1 file changed, 3 insertions(+) create mode 100755 start.sh diff --git a/start.sh b/start.sh new file mode 100755 index 0000000..759fd51 --- /dev/null +++ b/start.sh @@ -0,0 +1,3 @@ +#!/bin/sh + +docker run --runtime=nvidia --gpus all -v "$(pwd)/datadir":/root/datadir --rm -it ubuntu:insta360 From 3428fffb834edf9335e1d91b7d4d32fbcc2772cb Mon Sep 17 00:00:00 2001 From: Ning Shang Date: Fri, 5 Jun 2026 15:53:19 -0700 Subject: [PATCH 3/5] Add CUDA support for computer with GPU Update the Dockerfile and documentation to support running the Insta360 media SDK tools with and without an NVIDIA GPU. - Simplify installation of the media SDK in Dockerfile - Update README.md to support both cases (with and without GPU) - Remove start.sh It's trivial to write a host-side script for building and running the Docker container. We provide the recipe in README.md, and will not provide the starting script. --- Dockerfile | 18 +++++----- README.md | 84 +++++++++++++++++++++++++++++++++-------------- scripts/join-insv | 3 ++ start.sh | 3 -- 4 files changed, 72 insertions(+), 36 deletions(-) delete mode 100755 start.sh diff --git a/Dockerfile b/Dockerfile index 0fa5be8..3b8dca4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,15 +1,15 @@ -# For exiftool 12.40 -FROM ubuntu:22.04 +# From repo root directory, build Docker image with command: +# docker build --tag ubuntu:insta360 [--build-arg="MEDIASDK_UBUNTU_DEB="] . +# Need exiftool 12.40 or above +FROM ubuntu:24.04 -ARG MEDIASDK_UBUNTU_DEB=libMediaSDK-dev-3.1.1.0-20250922_191110-amd64.deb +ARG MEDIASDK_UBUNTU_DEB=libMediaSDK-dev_2.0-6_amd64_ubuntu18.04.deb ENV PATH="${PATH}:/root/scripts" -RUN apt update && \ - apt install -y software-properties-common && \ - apt install -y curl git build-essential libjpeg-dev libtiff-dev ffmpeg exiftool bc libvulkan1 libvulkan-dev vulkan-tools libglfw3-dev libdc1394-dev mesa-utils && \ - rm -rf /var/lib/apt/lists/* - WORKDIR /root COPY ${MEDIASDK_UBUNTU_DEB} . -RUN dpkg -i ${MEDIASDK_UBUNTU_DEB} +RUN apt update && \ + apt install exiftool ffmpeg bc -y +RUN apt install "./${MEDIASDK_UBUNTU_DEB}" -y + COPY scripts scripts diff --git a/README.md b/README.md index 923f3f8..f7b76ee 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Insta360 360-degree video processing in command-line +# Insta360 360-degree video processing from the command line This repository contains the utility and instructions to process Insta360 360-degree videos (with extension `.insv`) from the command line, @@ -7,13 +7,12 @@ Studio](https://www.insta360.com/download/insta360-x3) (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. +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 +- Enough free disk space 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 latest media SDK I have access to is `LinuxSDK20241128.zip`. It contains @@ -21,38 +20,75 @@ If you are a Linux user, this utility can come in handy, because as of early 18.04, which is the only file I need from the zip. - According to [Insta360's note](https://github.com/Insta360Develop/Desktop-MediaSDK-Cpp/blob/cb70fdf197ac55473e876a010f297192e6e20e3e/README.md?plain=1#L3), - GPU is required in version 3.x.x. For better portability, we suggest that - you use an earlier version of the media SDK. + GPU is required in version 3.x.x. If your computer doesn't have an NVIDIA + GPU, we suggest that you use an earlier version of the media SDK. ## My workflow for converting and joining 360-degree videos -1. Clone this repo. +1. Clone this repository. ```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. +2. Extract the aforementioned `.deb` file from the media SDK zip, and place it + in the root directory of the cloned repository. -3. Build the Docker container image in which the SDK is installed. +3. Build the Docker container image in which the SDK is installed. Suppose the + file's name is `libMediaSDK-dev_2.0-6_amd64_ubuntu18.04.deb`. ```bash - # Under repo's directory root - docker build --tag ubuntu:insta360 . + # From the repository root + docker build --tag ubuntu:insta360 \ + --build-arg="MEDIASDK_UBUNTU_DEB=libMediaSDK-dev_2.0-6_amd64_ubuntu18.04.deb" . ``` -4. Run the container, mounting host directory `datadir/` to the container's path - `/root/`, for host-container data sharing. +4. Run the container, mounting the host directory `datadir/` to the container + path `/root/datadir`, for host-container data sharing. + +
+ If you don't have an NVIDIA GPU + + As mentioned above, you need to use a media SDK whose version is below + `3.0.0`. In this case, you can perform video processing using the CPU. + + ```bash + docker run -v "$(pwd)/datadir":/root/datadir --rm -it ubuntu:insta360 + ``` +
+ +
+ If you have an NVIDIA GPU + + You can use the GPU for video processing (tested on a PC with NVIDIA GeForce + RTX™ 4060 Ti running Ubuntu). + + Before running the Docker container with CUDA support, perform the following prerequisite steps: + + 1. Install the [NVIDIA Container + Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) + 2. Configure Docker so that it can use the NVIDIA Container Runtime + + ```bash + sudo nvidia-ctk runtime configure --runtime=docker + # restart the Docker daemon + sudo systemctl restart docker + ``` + + The above steps only need to be done once on the host PC. Now you can run the + CUDA container. ```bash - docker run -v "$(pwd)/datadir":/root/datadir -it ubuntu:insta360 + docker run --runtime=nvidia --gpus all \ + -v "$(pwd)/datadir":/root/datadir \ + --rm -it ubuntu:insta360 ``` +
- Copy/move `.insv` files to "$(pwd)/datadir" on host, for processing in the + Copy or move `.insv` files into `datadir/` on the host for processing in the container. -5. Inside the Docker container, in shell prompt +5. Inside the Docker container, at the shell prompt: ```bash MERGED_VIDEO="merged.mp4" @@ -66,7 +102,7 @@ If you are a Linux user, this utility can come in handy, because as of early 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) + # Join MP4 files into one (assuming filenames are sorted in chronological 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" @@ -80,15 +116,15 @@ If you are a Linux user, this utility can come in handy, because as of early -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 + `"$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 + `-inputs` argument of `MediaSDKTest`, in the aforementioned order. For example, ```bash @@ -102,15 +138,15 @@ If you are a Linux user, this utility can come in handy, because as of early ## Utility: `join-insv` The utility `join-insv` is available in the container to automate the above -workflow. Example +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 ... + /path/to/input-1.insv /path/to/input-2.insv ... # For 5.7K -join-insv --output /path/to/merged_5.7k_360video.mp4 \ +join-insv --is_57k --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 \ ... diff --git a/scripts/join-insv b/scripts/join-insv index 6c958dd..dd2ff9c 100755 --- a/scripts/join-insv +++ b/scripts/join-insv @@ -86,6 +86,9 @@ join_insv() { -acodec copy \ -f mp4 "$tmpfile" + # Remove output file if it already exists, otherwise exiftool will fail + rm -rf "${outfile}" + exiftool -XMP-GSpherical:Spherical="true" \ -XMP-GSpherical:Stitched="true" \ -XMP-GSpherical:ProjectionType="equirectangular" \ diff --git a/start.sh b/start.sh deleted file mode 100755 index 759fd51..0000000 --- a/start.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/bin/sh - -docker run --runtime=nvidia --gpus all -v "$(pwd)/datadir":/root/datadir --rm -it ubuntu:insta360 From c430365a9ca2b34caa3fdbe6eddb3e14894b3475 Mon Sep 17 00:00:00 2001 From: Ning Shang Date: Fri, 5 Jun 2026 16:18:59 -0700 Subject: [PATCH 4/5] Remove datadir/** from .gitignore This is so that one can use git clean -df to clean up datadir/ --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 9924098..359fd9d 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,3 @@ libMediaSDK-dev_2.0-0_amd64_ubuntu18.04.deb libMediaSDK-dev_2.0-6_amd64_ubuntu18.04.deb libMediaSDK-dev-3.1.1.0-20250922_191110-amd64.deb **/.DS_Store -datadir/** From ba35f59ac94db5a1931ca41d0328c2d20ea2c03a Mon Sep 17 00:00:00 2001 From: Ning Shang Date: Fri, 5 Jun 2026 16:29:14 -0700 Subject: [PATCH 5/5] Clean up `datadir/` Update `README.md` to add a tip for cleaning up `datadir/`. Tweak `.gitignore` to remove `datadir/**` from the list. --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index f7b76ee..be3b7e7 100644 --- a/README.md +++ b/README.md @@ -135,6 +135,15 @@ If you are a Linux user, this utility can come in handy, because as of early -enable_directionlock -enable_flowstate -enable_denoise ``` +6. Clean up `datadir/` + + After processing is complete and you have copied the files you need out of + `datadir/`, you can remove its contents from the repository root with: + + ```bash + git clean -df datadir/ + ``` + ## Utility: `join-insv` The utility `join-insv` is available in the container to automate the above