spatialinject

English | 한국어

A cross-platform spatial-media metadata toolkit for MP4/MOV — inspect, verify, and inject 360°/spatial metadata. Injection is one capability; inspection and verification are equally first-class (dump / verify / inject).

A modern, clean-room replacement for Google's Spatial Media Metadata Injector (Google Spherical V1 + V2 and SA3D ambisonic audio), with Apple Projected Media Profile (APMP) planned. It edits container metadata only — it never re-encodes video, and never overwrites the original.

• Core: a hand-written ISO-BMFF / QuickTime box parser/writer (no external deps).
• Targets: Windows 10/11, macOS 13+, Linux. CLI/core are pure standard C++17.
• GUI: wxWidgets desktop app (SpatialInject) on top of the same core library.

Trust first

SpatialInject's guiding principle: it must never corrupt a media file.

• No re-encoding. Only container boxes are edited; the mdat media payload is copied byte-for-byte (verified bit-exact).
• Never overwrites the original. Output is always a new file.
• Mandatory post-inject re-verification. Every inject re-reads its output and confirms the metadata round-trips and that every stco/co64 chunk offset is in bounds; on any mismatch the output is set aside, never silently kept.
• Heavily tested. Lossless identity-write invariant, mutation + coverage-guided fuzzing, AddressSanitizer/UBSan, and a regression suite — including a full inject→write→re-read round-trip over every recognized video sample-entry type.

Status

Phase 1 complete — release-ready. Reaches and exceeds the capability of Google's Spatial Media Metadata Injector (Google's tool emits V1 only; SpatialInject writes V1 and V2), implemented clean-room.

Feature	State
Box-tree parser (32/64-bit, uuid, meta ISO+QT, stsd/sample entries, sv3d/proj)	✅ done
CLI dump (tree + spherical/APMP summary)	✅ done
CLI verify (ftyp/moov/video-track/metadata checks)	✅ done
CLI inject — Google Spherical V1 (uuid+XML) + V2 (st3d/sv3d), stco/co64 rewrite, post-verify	✅ done
Spatial audio (SA3D ambiX) — --spatial-audio, auto order from channel count	✅ done
Fragmented-MP4 rejection (moof/styp/sidx/mvex)	✅ done
wxWidgets desktop GUI (Analyze / Inject / Verify, i18n-ready)	✅ done
Unit + regression tests, ASan/UBSan, fuzzing	✅ done
180°/VR180	⬜ planned (Phase 1.5)
APMP vexu inject	⬜ planned (Phase 3)

Validated end-to-end on the real workflow — Insta360 X4 → encoder → SpatialInject — with the output recognized as a 360° video by YouTube and the media stream byte-identical to the input.

Clean-room. The container parser/writer and metadata boxes are implemented solely from ISO/IEC 14496-12 and the public Spherical/Spatial-Audio specs (see docs/format_notes_google_spherical.md). No third-party MP4 library and no code from any existing injector is used; compatibility is validated on output files.

Install (macOS, Apple Silicon)

Download the macOS app (SpatialInject-<version>-macos-arm64.zip) from the Releases page, unzip it, and move SpatialInject.app to your Applications folder. (Apple Silicon only for now — on Intel, Linux, or Windows, build from source below.)

The app is not yet code-signed or notarized, so on first launch macOS will say it can't verify the developer. To open it, do one of:

• Right-click SpatialInject.app → Open → Open in the dialog, or
• System Settings → Privacy & Security → scroll down → Open Anyway, or
• Terminal: xattr -dr com.apple.quarantine /path/to/SpatialInject.app

The CLI is a single dependency-free binary — build it from source (below).

Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

Requires CMake ≥ 3.16 and a C++17 compiler. The CLI/core have no third-party dependencies. To also build the desktop GUI: -DSPATIALINJECT_BUILD_GUI=ON (needs wxWidgets 3.x; brew install wxwidgets on macOS).

Usage

spatialinject dump   input.mp4      # box tree + detected spatial metadata
spatialinject verify input.mp4      # structural sanity checks

# Inject Google Spherical V1+V2 (defaults: equirectangular projection, mono):
spatialinject inject input.mp4 -o output.mp4

# Side-by-side stereo + ambisonic spatial audio:
spatialinject inject --stereo side-by-side --spatial-audio input.mp4 -o output.mp4

# Choose standards explicitly (default is v1,v2):
spatialinject inject --metadata v1,v2 --projection equirectangular input.mp4 -o output.mp4

inject options: --projection equirectangular|none, --stereo mono|side-by-side|over-under (+ --swap-eyes), --spatial-audio, --metadata v1,v2, --force, -o <out>. The original is never modified; output defaults to <input>_injected.<ext>.

Layout

core/   parser + analyzer + injector + writer (portable, GUI-free)
cli/    command-line front end
gui/    wxWidgets desktop front end (build with -DSPATIALINJECT_BUILD_GUI=ON)
tests/  unit + regression tests
docs/   format notes, charter

Acknowledgments

spatialinject is authored by manobit, developed in an iterative, human-directed loop with two AI assistants: ChatGPT (OpenAI) for architecture and design review, and Claude (Anthropic) for implementation, testing, and validation. All code is original and clean-room — written from the specifications, with no code from any existing injector (see NOTICE).

License

Apache License 2.0 — see LICENSE. Copyright (c) 2026 manobit.

spatialinject is an independent, clean-room implementation built from ISO/IEC 14496-12 and public spherical/spatial-audio specifications; it contains no code from any existing metadata injector. See NOTICE for full provenance and trademark notes.