README.md

June 12, 2025 ยท View on GitHub

MACH1 SPATIAL SDK

libmach1spatial Version Test YouTube Channel Mach1SpatialAPI CocoaPods Mach1SpatialAPI Jitpack

LICENSE

By downloading and/or using the Mach1 Spatial SDK, including use of any of the contents within the libmach1spatial/, you agree to and acknowledge the terms of use set forth by the Mach1 Spatial SDK License. If you do not agree to the terms set forth by the Mach1 Spatial SDK License you are not permitted to use, link, compile and/or distribute any of the contents of this repository.

Please view the license/ directory for more information and proper attribution resources.

SUMMARY

Mach1 Spatial VVBP (Virtual Vector Based Panning) is a virtual VBAP (Vector Based Amplitude Panning) or SPS (Spatial PCM Sampling) framework of multichannel symmetrical layouts designed for inter-operability with other multichannel audio approaches and packaged in flexible APIs for use. The Mach1 Spatial layouts are designed for simplicity and ease of use & implementation both for the content creators and the developers. The Mach1 Spatial audio mixes are based on only amplitude based coefficients changes for both encoding and decoding, and unlike many other spatial audio approaches, there are no additional signal altering processes (such as room modeling, delays or filters) to create coherent and accurate spatial sound fields and play them back from a first person headtracked perspective. Due to the simplicity of the framework and vector space it relies on, it is also ideal for converting and carrying surround and spatial audio mixes without altering the mix to do so, making it an ideal server side audio middleman container and bringing controlled post-produced spatial audio into new mediums more easily.

The Mach1 Spatial SDK includes four components and libraries:

  • Mach1Encode: Encode and process input streams/audio into a Mach1Spatial VVBP format.
  • Mach1Decode: Decode and process a Mach1Spatial VVBP format with device orientation / headtracking to output directional spatial audio.
  • Mach1DecodePositional: Add additional optional decoding layer to decode spatial mixes with 6DOF for positional and orientational decoding.
  • Mach1Transcode: Transcode / convert any audio format (surround/spatial) to or from a Mach1Spatial VVBP format.

SETUP

CMake

The easiest way to use this project is to use CMake from the root directory to setup all the APIs, examples and tests as needed. An example of this is running the following from this directory:

  • cmake . -B build -DM1S_BUILD_TESTS=ON -DM1S_BUILD_EXAMPLES=ON -DM1ENCODE_INLINE_DECODE=ON -DM1TRANSCODE_INLINE_ENCODE=ON -DM1S_BUILD_SIGNAL_SUITE=ON
  • cmake --build build --config Release

View the CMakeLists.txt file to see any options, by default the examples and tests are enabled.

Options
  • M1ENCODE_INLINE_DECODE: Includes Mach1Decode API into Mach1Encode API as a dependency to allow more features.
  • M1TRANSCODE_INLINE_ENCODE: Includes Mach1Encode API into Mach1Transcode API as a dependency to allow more features.

Makefile

The makefile also has quick commands for setting up and building the entire SDK

  • make test
  • make build

INSTALL

CMake

Linking or including any of the APIs to a project can also be easily done via cmake, and the APIs are individually modular in case you want to limit which of them is needed.

Rebuild Cocoapods libs
  • cmake . -B_builds/ios -GXcode \ -DM1S_BUILD_EXAMPLES=OFF -DBUILD_COCOAPODS_LIBS=ON -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_TOOLCHAIN_FILE=libmach1spatial/cmake/ios-cmake/ios.toolchain.cmake -DPLATFORM=OS64COMBINED
  • cmake --build _builds/ios --config Release # separate build and install steps for fat-lib
  • cmake --install _builds/ios --config Release
Rebuild Android libs

Make sure you have setup or preinstalled your Android NDK and set the following environment var: CMAKE_ANDROID_NDK

  • cmake . -B_builds/android-arm64-v8a \ -DM1S_BUILD_EXAMPLES=OFF -DBUILD_JITPACK_LIBS=ON -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_TOOLCHAIN_FILE=${CMAKE_ANDROID_NDK}/build/cmake/android.toolchain.cmake \ -DCMAKE_SYSTEM_NAME=Android \ -DANDROID_PLATFORM=21 \ -DANDROID_ABI=arm64-v8a \ -DCMAKE_ANDROID_STL_TYPE=c++_static \ -DCMAKE_ANDROID_NDK=${CMAKE_ANDROID_NDK}
  • cmake --build _builds/android-arm64-v8a --config Release --target install

Makefile

Call any of these premade make commands from this directory to quickly recompile any libs as needed.

Rebuild WASM/JS Web libs
  • make deploy-web
Rebuild Cocoapods libs
  • make deploy-ios
Rebuild Android libs
  • make deploy-android

Implementation Examples

DOCUMENTATION

open or load docs/index.html into your preferred browser to run through all the API documentation or visit our hosted documentation

Migration

Migration guides from older versions of the Mach1 Spatial SDK can be found in MIGRATIONS.md.

CONTACT

General: whatsup@mach1.tech