{"id":13783333,"url":"https://github.com/leomccormack/Spatial_Audio_Framework","last_synced_at":"2025-05-11T18:31:45.988Z","repository":{"id":37601440,"uuid":"128790913","full_name":"leomccormack/Spatial_Audio_Framework","owner":"leomccormack","description":"A cross-platform framework for developing spatial audio algorithms and software in C/C++","archived":false,"fork":false,"pushed_at":"2024-06-06T08:51:25.000Z","size":361444,"stargazers_count":543,"open_issues_count":6,"forks_count":87,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-08-03T19:07:46.961Z","etag":null,"topics":["3d-audio","ambisonics","microphone-array-processing","multi-source-tracking","sofa-reader","spatial-audio","spatial-audio-framework","spherical-harmonics","vbap"],"latest_commit_sha":null,"homepage":"https://leomccormack.github.io/Spatial_Audio_Framework/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leomccormack.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"leomccormack"}},"created_at":"2018-04-09T15:11:06.000Z","updated_at":"2024-07-17T06:13:04.000Z","dependencies_parsed_at":"2024-01-16T00:37:55.850Z","dependency_job_id":"a81a15a8-0e0f-495b-a5bd-f5bee883d96c","html_url":"https://github.com/leomccormack/Spatial_Audio_Framework","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leomccormack%2FSpatial_Audio_Framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leomccormack%2FSpatial_Audio_Framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leomccormack%2FSpatial_Audio_Framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leomccormack%2FSpatial_Audio_Framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leomccormack","download_url":"https://codeload.github.com/leomccormack/Spatial_Audio_Framework/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225081893,"owners_count":17418037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-audio","ambisonics","microphone-array-processing","multi-source-tracking","sofa-reader","spatial-audio","spatial-audio-framework","spherical-harmonics","vbap"],"created_at":"2024-08-03T19:00:19.071Z","updated_at":"2024-11-17T19:31:42.580Z","avatar_url":"https://github.com/leomccormack.png","language":"C","funding_links":["https://github.com/sponsors/leomccormack"],"categories":["DSP Libraries"],"sub_categories":[],"readme":"![GitHub release (latest by date)](https://img.shields.io/github/v/release/leomccormack/Spatial_Audio_Framework) ![GitHub Release Date](https://img.shields.io/github/release-date/leomccormack/Spatial_Audio_Framework) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4707945.svg)](https://doi.org/10.5281/zenodo.4118286)  \n\n\u003cimg src=\"saf.svg\"\u003e \n\n* git: [https://github.com/leomccormack/Spatial_Audio_Framework](https://github.com/leomccormack/Spatial_Audio_Framework)\n* doxygen: [https://leomccormack.github.io/Spatial_Audio_Framework/](https://leomccormack.github.io/Spatial_Audio_Framework/)\n\n# About\n\nThe Spatial_Audio_Framework (SAF) is an open-source and cross-platform framework for developing spatial audio related algorithms and software in C/C++. Originally intended as a resource for researchers in the field, the framework has gradually grown into a large codebase comprising a number of distinct [**modules**](framework/modules); with each module targeting a specific sub-field of spatial audio, such as: Ambisonics encoding/decoding, spherical array processing, amplitude-panning, HRIR processing, room simulation, etc.. The framework also makes use of highly optimised linear algebra libraries (such as: Intel MKL, Apple Accelerate, OpenBLAS) as well as x86 SIMD intrinsics (SSE, AVX, AVX-512). \n\nSeveral [**examples**](examples/include) are also included in the repository, which serve to demonstrate the functionality of the framework and may also act as a starting point for new projects. These examples have also been realised as VST/LV2 audio plug-ins under the [**SPARTA**](https://github.com/leomccormack/SPARTA) banner.\n\nOwing to its modular design, expanding the framework is relatively straightforward, and contributions from researchers and developers of spatial audio technologies is encouraged! :-) \n\n# Prerequisites\n\nThe framework requires the following external libraries:\n* Any library (or libraries) conforming to the [CBLAS](https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms#Implementations) and [LAPACK](https://en.wikipedia.org/wiki/LAPACK) standards\n* (**Optional**) Intel's [Integrated Performance Primitives (IPP)](https://software.intel.com/content/www/us/en/develop/tools/integrated-performance-primitives.html) for the FFT and/or resampler\n* (**Optional**) [FFTW](https://www.fftw.org/) for the FFT\n* (**Optional**) a SSE, AVX, AVX-512 supporting CPU\n\nIn order to inform SAF which CBLAS/LAPACK supporting library/libraries you have linked to your project, simply add **one** of the following global pre-processor definitions:\n```\nSAF_USE_INTEL_MKL_LP64        # great option, but only for x86 architectures (using the LP64 config [int32])\nSAF_USE_INTEL_MKL_ILP64       # great option, but only for x86 architectures (using the ILP64 config [int64])\nSAF_USE_OPEN_BLAS_AND_LAPACKE # good option, works on everything\nSAF_USE_APPLE_ACCELERATE      # good option (x86 and ARM), faster than OpenBLAS, but MacOSX only \u0026 slower than MKL\nSAF_USE_ATLAS                 # bad option (x86 and ARM), many LAPACK functions are missing\nSAF_USE...                    # please get in touch if you use something else! :-)\n```\n[Detailed instructions regarding how to build and link these libraries can be found here](docs/PERFORMANCE_LIBRARY_INSTRUCTIONS.md).\n\n## Framework structure\n\nThe [framework](docs/FRAMEWORK_STRUCTURE.md) comprises the following core modules (**ISC** License):\n* **saf_hoa** - a collection of higher-order Ambisonics binaural and loudspeaker decoders.\n* **saf_sh** - spherical harmonic and spherical array processing related functions.\n* **saf_vbap** - Vector-base Amplitude Panning (VBAP) functions.\n* **saf_cdf4sap** - Covariance Domain Framework for Spatial Audio Processing (CDF4SAP).\n* **saf_hrir** - HRIR/HRTF related functions (estimating ITDs, HRTF interpolation, diffuse-field EQ etc.).\n* **saf_reverb** - a collection of reverbs and room simulation algorithms.\n* **saf_utilities** - a collection of useful utility functions and cross-platform wrappers.\n\nThe framework also includes the following optional modules:\n* **saf_sofa_reader** - a simple SOFA file reader (**ISC** License).\n* **saf_tracker** - a particle-filtering based tracker (**GPLv2** License).\n* **saf_hades** - for binaural rendering of Hearing-Assistive/Augmented-reality Devices (HADES)  (**GPLv2** License).\n\nTo enable optional framework modules, simply add the relevant pre-processor definition:\n```\nSAF_ENABLE_SOFA_READER_MODULE  # to enable saf_sofa_reader\nSAF_ENABLE_TRACKER_MODULE      # to enable saf_tracker\nSAF_ENABLE_HADES_MODULE        # to enable saf_hades\n```\n\n### Additional options\n\nThe framework can be configured further, with the following options:\n```\nSAF_USE_INTEL_IPP # To use Intel IPP for performing the DFT/FFT and resampling\nSAF_USE_FFTW      # To use the FFTW library for performing the DFT/FFT \nSAF_ENABLE_SIMD   # To enable SIMD (SSE3, AVX2 and/or AVX512) intrinsics for certain vector operations\n```\n\n# Using the framework\n\nOnce a CBLAS/LAPACK flag is defined (and the correct libraries are linked to your project), add the files found in the **framework** folder to your project and add the following directory to your project's header search paths:\n\n```\nSpatial_Audio_Framework/framework/include  \n```\n\nThe framework's master include header is then:\n\n```c\n#include \"saf.h\"\n#include \"saf_externals.h\"  /* (Optional) To also carry over CBLAS/LAPACK routines and other external functions. */\n```\n\n## Building with CMake \n\n![CMake Build](https://github.com/leomccormack/Spatial_Audio_Framework/workflows/CMake%20Build/badge.svg?branch=master)\n\nThe framework may also be included within an existing CMake workflow with simply:\n```\nadd_subdirectory(Spatial_Audio_Framework)\ntarget_link_libraries(${PROJECT_NAME} PRIVATE saf)\n```\n\nThe available SAF-related CMake options (and their default values) are:\n```\n-DSAF_PERFORMANCE_LIB=SAF_USE_INTEL_MKL_LP64 # performance library to employ\n-DSAF_ENABLE_SOFA_READER_MODULE=0            # enable/disable the saf_sofa_reader module \n-DSAF_ENABLE_TRACKER_MODULE=0                # enable/disable the saf_tracker module \n-DSAF_ENABLE_HADES_MODULE=0                  # enable/disable the saf_hades module \n-DSAF_BUILD_EXAMPLES=1                       # build saf examples\n-DSAF_BUILD_EXTRAS=0                         # build safmex etc.\n-DSAF_BUILD_TESTS=1                          # build unit testing program\n-DSAF_USE_INTEL_IPP=0                        # link and use Intel IPP for the FFT, resampler, etc.\n-DSAF_ENABLE_SIMD=0                          # enable/disable SSE3, AVX2, and/or AVX-512 support\n-DSAF_ENABLE_NETCDF=0                        # enable the use of NetCDF (requires external libs)\n-DSAF_ENABLE_FAST_MATH_FLAG=1                # enable the -ffast-math compiler flag on clang/gcc\n```\n\nIf using e.g. **SAF_USE_INTEL_MKL_LP64** as the performance library, note that the default header and library search paths may be overridden [according to your setup](docs/PERFORMANCE_LIBRARY_INSTRUCTIONS.md) with:\n``` \n-DINTEL_MKL_HEADER_PATH=\"path/to/mkl/headers\"\n-DINTEL_MKL_LIB=\"path/to/mkl/libs/mkl_rt(.so/.dylib/.lib)\"   # OR:\n-DINTEL_MKL_LIB=\"path/to/custom/mkl/lib/saf_mkl_custom_lp64(.so/.dylib/.lib)\"\n```\n\nFor Linux/MacOS users: the framework, examples, and unit testing program may be built as follows:\n```\n# By default:\ncmake -S . -B build \n# Or to also enable e.g. SSE3, AVX2, and/or AVX-512 intrinsics (for both C and C++ code):\ncmake -S . -B build -DSAF_ENABLE_SIMD=1\n# Or to build Universal binaries for macOS (ARM/x86), which must therefore use Apple Accelerate:\ncmake -S . -B build -DSAF_PERFORMANCE_LIB=SAF_USE_APPLE_ACCELERATE -DCMAKE_OSX_ARCHITECTURES=\"arm64;x86_64\"\n# Then to build and run the unit testing program:\ncd build\nmake\ntest/saf_test \n```\n\nOr for Visual Studio users (using x64 Native Tools Command Prompt for VS):\n```\n# e.g. for VS2019:\ncmake -S . -B build -G \"Visual Studio 16\" -A x64  \n# e.g. for VS2017:\ncmake -S . -B build -G \"Visual Studio 15 2017\" -DCMAKE_GENERATOR_PLATFORM=x64\n# Then to build and run the unit testing program:\ncd build\nmsbuild ALL_BUILD.vcxproj /p:Configuration=Release /m\ncd test/Release\nsaf_test.exe  \n```\n\n## Documentation \n\n![Doxygen Generate](https://github.com/leomccormack/Spatial_Audio_Framework/workflows/Doxygen%20Generate/badge.svg?branch=master)\n\n[Doxygen](http://www.doxygen.nl/index.html)-based documentation is generated via a GitHub Action everytime a commit is pushed to the master branch. The documentation is hosted [here](https://leomccormack.github.io/Spatial_Audio_Framework/).\n\nAlternatively, you may generate the documentation yourself (e.g. for the other branches) with the following commands:\n```\ncd docs/doxygen\ndoxygen doxygen_config\n# (optional) to also build the pdf version:\ncd latex\nmake\n```\n\n## Examples\n\nSeveral **examples** have also been included in the repository, which may serve as a starting point for learning how to use the framework:\n\n* **ambi_bin** - a binaural Ambisonic decoder with built-in rotator. It supports the following decoding options: least-squares (LS), spatial re-sampling (SPR), Time-alignment (TA), Magnitude Least-Squares (MagLS).\n* **ambi_dec** - a frequency-dependent Ambisonic decoder. It supports the following decoding options: sampling Ambisonic decoder (SAD), AllRAD, Energy-Preserving decoder (EPAD), Mode-Matching decoder (MMD).\n* **ambi_drc** - a frequency-dependent dynamic range compressor (DRC) for Ambisonic signals.\n* **ambi_enc** - a basic Ambisonic encoder.\n* **ambi_roomsim** - an Ambisonic encoder that also includes reflections and source distance based on an image-source model of a shoebox room. Multiple sources and Ambisonic receivers are supported.\n* **array2sh** - converts microphone array signals into spherical harmonic signals (aka Ambisonic signals), based on theoretical descriptions of the array configuration and construction.\n* **beamformer** - a beamformer/virtual microphone generator for Ambisonic signals, with several different beam pattern options.\n* **binauraliser** - convolves input audio with interpolated HRTFs, which can be optionally loaded from a SOFA file.\n* **binauraliser_nf** - binauraliser, with the addition of proximity filtering for near field sound sources.\n* **decorrelator** - a basic multi-channel signal decorrelator.\n* **dirass** - a sound-field visualiser based on re-assigning the energy of beamformers. This re-assignment is based on the DoA estimates extracted from spatially-localised active-intensity vectors, which are biased towards each beamformer direction.\n* **matrixconv** - a basic matrix convolver with an optional partitioned convolution mode. \n* **multiconv** - a basic multi-channel convolver with an optional partitioned convolution mode. \n* **tvconv** - a time-varying partitioned convolution multi-channel convolver for SOFA files containing RIRs with multiple listener positions.\n* **panner** - a frequency-dependent VBAP panner, which accommodates a source loudness compensation (as a function of the room) option.\n* **pitch_shifter** - a basic multi-channel pitch shifter, based on the phase vocoder approach.\n* **powermap** - sound-field visualiser based on beamformer (PWD, MVDR) energy or subspace methods (MUSIC).\n* **rotator** - rotates spherical harmonic signals (aka Ambisonic signals) given yaw-pitch-roll Euler rotation angles.\n* **sldoa** - a sound-field visualiser based on directly depicting the DoA estimates extracted from multiple spatially-localised active-intensity vectors for multiple frequencies. \n* **spreader** - an arbitrary array panner (HRIRs, microphone array IRs, etc.) with coherent and incoherent spreading modes.\n\nMany of these examples have also been released as VST audio plug-ins under the [SPARTA](https://github.com/leomccormack/SPARTA) banner. The following open-source projects also employ the framework: [HADES](https://github.com/jananifernandez/HADES), [Super-Hearing](https://github.com/leomccormack/Super-Hearing/), [HO-SIRR-GUI](https://github.com/leomccormack/HO-SIRR-GUI), and [CroPaC-Binaural](https://github.com/leomccormack/CroPaC-Binaural).\n\n## Extras\n\nThe repository also includes the following **extras**:\n\n* [matlab](extras/matlab/SAF_MATLAB_CODE.md) - a bunch of MATLAB scripts/functions to accompany the framework (a script to generate saf_default_hrirs.c, MATLAB versions of certain SAF functions, etc.).\n* [safmex](extras/safmex/SAFMEX.md) - a bunch of MATLAB MEX wrappers, which allow certain SAF functions to be used within MATLAB.\n* [safpy](extras/safpy/SAFPY.md) - a bunch of Python wrappers, which allow certain SAF functions to be used within Python.\n* [safwwise](extras/safwwise/SAFWWISE.md) - a proof of concept regarding how one might integrate SAF into Wwise.\n\n## Contributing\n\nSuggestions and contributions to the code are both welcomed and encouraged. It should be highlighted that the framework has been designed to be highly modular with plenty of room for expansion. Therefore:\n* if you are researcher who has developed a spatial-audio related method and want to integrate it into the framework... or\n* if you notice that an existing piece of code can be rewritten to make it clearer, faster, or to fix a bug...\n\nthen please feel free to do so and submit a pull request. We may also be able to help with the implementation if needed, just get in touch :- )\n\n## Contributors\n\n* **Leo McCormack** - C programming and algorithm design (contact: leo.mccormack(at)aalto.fi)\n* **Symeon Delikaris-Manias** - algorithm design\n* **Archontis Politis** - algorithm design\n* **Ville Pulkki** - algorithm design\n* **Juhani Paasonen** - C programming\n* **Chris Hold** - C programming and algorithm design \n* **Janani Fernandez** - C programming and algorithm design \n\n# License\n\nThis software is dual-licensed. By default, this software is provided permissively under the terms of the [ISC License](https://choosealicense.com/licenses/isc/); since all of the core (non-optional) modules are licensed as such. However, including and enabling certain optional modules, which are instead provided under the copy-left [GNU GPLv2 License](https://choosealicense.com/licenses/gpl-2.0/), will mean that the use of this software is instead governed by the GNU GPLv2 licencing terms.\n\nFor full licensing terms see [LICENSE.md](LICENSE.md).\n\nNote that, while we do not force any copyleft philosophies onto the permissively licensed modules, we would still appreciate it if improvements and/or bug fixes are also merged into this public repository where possible :-)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleomccormack%2FSpatial_Audio_Framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleomccormack%2FSpatial_Audio_Framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleomccormack%2FSpatial_Audio_Framework/lists"}