Skip to content

Mach1Studios/m1-sdk

Repository files navigation

MACH1 SPATIAL SDK

Slack Channel YouTube Channel Mach1SpatialAPI CocoaPods Mach1SpatialAPI Jitpack

IMPORTANT NOTICE: PLEASE READ CAREFULLY BEFORE DOWNLOADING, INSTALLING OR USING THE MACH1 SPATIAL SDK:

  • BY CLICKING ON THE “ACCEPT” BUTTON, OR BY DOWNLOADING, INSTALLING, OR USING THE MACH1 SPATIAL SDK, YOU AGREE TO THE TERMS OF THIS AGREEMENT, AND ALL INCORPORATED TERMS INCLUDING THE PRIVACY POLICY, AS APPLICABLE, WHICH WILL BIND YOU.
  • YOU MUST JOIN THE SPATIALAUDIO.SLACK.COM WORKSPACE TO KEEP IN TOUCH ABOUT THIS LICENSE AND MOST RECENT FEATURES ABOUT THE MACH1 SPATIAL SDK.
  • The most current version of the MACH1 SPATIAL SDK ROYALTY FREE LICENSE will be posted at www.mach1.tech/license. If the Current Version has a more recent effective date than this document, then this document is replaced by the Currnt Version and by clicking on the appropriate button below, or by downloading, installing, activating or using any of the SDK, or any other update method Mach1 may choose, you agree to be bound by the Current Version. You may not use an old version of any SDK if you have not agreed to the Current Version.
  • IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, WE WILL NOT LICENSE THE MACH1 SPATIAL SDK TO YOU AND YOU MUST DISCONTINUE THE INSTALLATION OR DOWNLOAD PROCESS OR CEASE USE OF THE MACH1 SPATIAL SDK.

By downloading and/or using the Mach1 Spatial SDK, including use of any of the contents within the mach1spatial-libs/, 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.

Mach1 Spatial VVBP (Virtual Vector Based Panning) is a controlled virtual version of traditional VBAP (Vector Based Amplitude Panning) or SPS (Spatial PCM Sampling). The Mach1 Spatial formats 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 format 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. Bringing controlled post-produced spatial audio into new mediums 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.

CMake

There are several ways to link or fetch the pre-built m1-sdk libs and includes for a cmake project.

  • Using FetchContent() & Find_Library() to link required libs as needed
# Avoid warning about DOWNLOAD_EXTRACT_TIMESTAMP in CMake 3.24:
if (CMAKE_VERSION VERSION_GREATER_EQUAL "3.24.0")
	cmake_policy(SET CMP0135 NEW)
endif()

include(FetchContent)

# Fetch the latest pre-built libs
FetchContent_Declare(
  m1-sdk
  URL      https://github.com/mach1studios/m1-sdk/releases/latest/download/mach1spatial-libs.zip
)

FetchContent_GetProperties(m1-sdk)

if (NOT m1-sdk_POPULATED)
    FetchContent_Populate(m1-sdk)

    # Perform arbitrary actions on the m1-sdk project
    # Avoid `add_subdirectory()` until a CMakeFile.txt is added to this directory
    set(MACH1SPATIAL_LIBS_PATH "${m1-sdk_SOURCE_DIR}")
endif()

# collect and add source files
set(SOURCES 
	src/main.cpp
	${MACH1SPATIAL_LIBS_PATH}/xcode/include/Mach1Decode.cpp
	)

# create the executable
add_executable(${CMAKE_PROJECT_NAME} ${SOURCES})

# link libraries
find_library(MACH1DECODE_LIBRARY 
             NAMES Mach1DecodeCAPI libMach1DecodeCAPI libMach1DecodeCAPI.a libMach1DecodeCAPI.so libMach1DecodeCAPI.lib
             PATHS ${MACH1SPATIAL_LIBS_UNIX_PATH}/lib ${MACH1SPATIAL_LIBS_PATH}/windows-x86 ${MACH1SPATIAL_LIBS_PATH}/windows-x86_64
)

# include headers
set(MACH1SPATIAL_INCLUDES ${MACH1SPATIAL_LIBS_PATH}/linux/include ${MACH1SPATIAL_LIBS_PATH}/linux/include/M1DSP ${MACH1SPATIAL_LIBS_PATH}/xcode/include ${MACH1SPATIAL_LIBS_PATH}/xcode/include/M1DSP ${MACH1SPATIAL_LIBS_PATH}/windows-x86/include ${MACH1SPATIAL_LIBS_PATH}/windows-x86/include/M1DSP)
include_directories(${MACH1SPATIAL_INCLUDES})

target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE ${MACH1DECODE_LIBRARY})

Prebuilt libraries

  • Android (libs prebuilt in multiple archs, jitpack)
  • iOS (cocoapod, lib, frameworks)
  • MacOS (xcode)
  • Linux (x86 & ARM)
  • Win-x86 (MD, MDd, MT, MTd)
  • Win-x86_64 (MD, MDd, MT, MTd)
  • Windows-x86 (Visual Studio)
  • Windows-x86-64 (Visual Studio)
  • RaspberryPi2
  • RaspberryPi3
  • Various embedded ARM chipsets

Includes

  • C/C++
  • C#
  • Java
  • js/web
  • Swift/Obj-C
  • Python (in progress)
  • Golang (in progress)

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.

General: whatsup@mach1.tech