{"id":25554773,"url":"https://github.com/videolabs/libspatialaudio","last_synced_at":"2025-03-31T07:08:54.117Z","repository":{"id":43288090,"uuid":"88265349","full_name":"videolabs/libspatialaudio","owner":"videolabs","description":"Ambisonic encoding / decoding and binauralization library in C++","archived":false,"fork":false,"pushed_at":"2024-05-06T17:14:36.000Z","size":2435,"stargazers_count":211,"open_issues_count":19,"forks_count":40,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-03-24T05:04:48.750Z","etag":null,"topics":["3d-audio","ambisonics","audio","sofa","vr"],"latest_commit_sha":null,"homepage":"","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/videolabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2017-04-14T12:21:33.000Z","updated_at":"2025-02-05T09:05:57.000Z","dependencies_parsed_at":"2024-05-06T18:44:51.677Z","dependency_job_id":null,"html_url":"https://github.com/videolabs/libspatialaudio","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videolabs%2Flibspatialaudio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videolabs%2Flibspatialaudio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videolabs%2Flibspatialaudio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videolabs%2Flibspatialaudio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/videolabs","download_url":"https://codeload.github.com/videolabs/libspatialaudio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246429484,"owners_count":20775807,"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","audio","sofa","vr"],"created_at":"2025-02-20T13:42:03.247Z","updated_at":"2025-03-31T07:08:54.092Z","avatar_url":"https://github.com/videolabs.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"Ambisonic encoding / decoding and binauralization library\n=============\n\n**libspatialaudio** is an open-source and cross-platform C++ library for **Ambisonic** encoding and decoding, filtering and **binaural** rendering.\nIt is targetted to render *High-Order Ambisonic* (**HOA**) and *VR/3D audio* samples in multiple environments, from headphones to classic loudspeakers.\nIts *binaural rendering* can be used for classical 5.1/7.1 spatial channels as well as Ambisonics inputs.\n\nOriginally it is a fork of **ambisonic-lib** from Aristotel Digenis. This version was developed to support Higher Order Ambisonics *HOA* and to support **ACN/SN3D** Ambisonics audio streams following the **Google spatial audio** specification:\nhttps://github.com/google/spatial-media/blob/master/docs/spatial-audio-rfc.md and the **IETF codec Ambisonics** specification https://tools.ietf.org/html/draft-ietf-codec-ambisonics\n\nThe library allows you to encode, decode, rotate, zoom **HOA Ambisonics** audio streams up to the *3rd order*. It can output to standard and custom loudspeakers arrays. To playback with headphones, the binauralizer applies an HRTF *(either a SOFA file or  the included MIT HRTF)* to provide a spatial binaural rendering effect. The binauralization can also be used to render multichannels streams (5.1, 7.1...).\n\nA central part of the library is the CBFormat object which acts as a buffer for B-Format. There are several other objects, each with a specific tasks, such as encoding, decoding, and processing for Ambisonics. All of these objects handle CBFormat objects at some point.\n\n\n## Features\n### Encoder (CAmbisonicEncoder):\nSimple encoder up to 3rd order 3D, without any distance cues.\n\n### Encoder with distance (CAmbisonicEncoderDist):\nAs the simple encoder, but with the addition of the following:\n* Distance level-simulation\n* Fractional delay lines\n* Interior effect (W-Panning)\n\n### Decoder (CAmbisonicDecoder):\nSimple decoder up to the 3rd Order 3D with:\n* Preset \u0026 custom speaker arrays\n* Decoder that improves the rendering with a 5.1 speaker set\n\n### Processor (CAmbisonicProcessor):\nUp to 3rd order 3D yaw/roll/pitch of the soundfield\n\nUp to 3rd order psychoacoustic optimisation shelf-filters for 2D and 3D playback\n\n### Binauralizer (CAmbisonicBinauralizer):\nUp to 3rd order 3D decoding to headphones\n\nOptional symmetric head decoder to reduce the number of convolutions\n\n### Zoomer (CAmbisonicZoomer):\nUp to 1st order 3D front-back dominance control of the soundfield\n\n## Overview of the Implemented Algorithms\n### Psychoacoustic Optimisation Shelf-filters\nImplemented as linear phase FIR shelf-filters ensure basic and max rE decodes in low- and high-frequency ranges respectively. See [[1]](#ref1) for more details why and [[2]](#ref2) for the mathematical theory used for higher orders.\n\nThe transition frequency between the two decoder types depends on the order being decoded, increasing with Ambisonic order.\n\nThe frequency is given by [[3]](#ref3):\n```c\n\nf_lim = speedofsound*M / (4*R*(M+1)*sin(PI / (2*M+2)))\n```\nwhere speedofsound = 343 m/s, R = 0.09 m (roughly the radius of human head) and M = Ambisonic order.\n\nA different gain is applied to each of the channels of a particular order. These are given by [[2](#ref2),[4](#ref4)]:\n```c\n2D: g_m = cos(pi*m/(2M + 2))\n3D: g_m = legendre(m, cos(137.9*(PI/180)/(M+1.51)))\n```\nwhere m = floor(sqrt(Channel Number)) and legendre(m,x) is a Legendre polynomial of degree m evaluated for a value of x.\n\n\n### Binaural Decoding\nThe binaural decoder uses a two different virtual loudspeaker arrays depending on the order:\n* 1st order: cuboid loudspeaker array\n* 2nd and 3rd order: Dodecahedron\n\nTo keep the number of convolutions to a minimum, the HRTFs are decomposed into spherical harmonics. This gives a pair of HRTF filters for each of the Ambisonics channel.\nThe advantage of this method is that the number of convolutions is limited to the number of Ambisonic channels, regardless of the number of virtual loudspeakers used.\n\n### Symmetric Head Binaural Decoder\nThe binaural decoder can reduce the number of convolutions needed for the binaural decoding by two.\n\nThe Ambisonic input channels are convolved with the corresponding HRTF channel for the left ear. The left ear signal is the sum of these convolved channels. To generate the right ear signal the soundfield is reflected left-right by multiplying several of the convolved channels by -1. These are then summed to produce the right ear signal.\n\n## How do I use it?\n\nThe following sample code shows the encoding of a sine wave into an Ambisonic soundfield, and then decoding that soundfield over a Quad speaker setup.\n\n```c\n// Generation of mono test signal\nfloat sinewave[512];\nfor(int ni = 0; ni \u003c 512; ni++)\n    sinewave[ni] = (float)sin((ni / 128.f) * (M_PI * 2));\n\n// CBFormat as 1st order 3D, and 512 samples\nCBFormat myBFormat;\n\n// Ambisonic encoder, also 3rd order 3D\nCAmbisonicEncoder myEncoder;\nmyEncoder.Configure(1, true, 0);\n\n// Set test signal's position in the soundfield\nPolarPoint position;\nposition.fAzimuth = 0;\nposition.fElevation = 0;\nposition.fDistance = 5;\nmyEncoder.SetPosition(position);\nmyEncoder.Refresh();\n\n// Encode test signal into BFormat buffer\nmyEncoder.Process(sinewave, 512, \u0026myBFormat);\n\n// Ambisonic decoder, also 1st order 3D, for a 5.0 setup\nCAmbisonicDecoder myDecoder;\nmyDecoder.Configure(1, true, kAmblib_50, 5);\n\n// Allocate buffers for speaker feeds\nfloat** ppfSpeakerFeeds = new float*[5];\nfor(int niSpeaker = 0; niSpeaker \u003c 5; niSpeaker++)\n    ppfSpeakerFeeds[niSpeaker] = new float[512];\n\n// Decode to get the speaker feeds\nmyDecoder.Process(\u0026myBFormat, 512, ppfSpeakerFeeds);\n\n// De-allocate speaker feed buffers\nfor(int niSpeaker = 0; niSpeaker \u003c 5; niSpeaker++)\n    delete [] ppfSpeakerFeeds[niSpeaker];\ndelete [] ppfSpeakerFeeds;\n```\n\n## References\n\n\u003ca name=\"ref1\"\u003e[1] M. A. Gerzon, “Practical Periphony: The Reproduction of Full-Sphere Sound,” in Audio Engineering Society Convention, 1980, pp. 1–12.\u003c/a\u003e\n\n\u003ca name=\"ref2\"\u003e[2] J. Daniel, “Représentation de champs acoustiques, application à la transmission et à la reproduction de scènes sonores complexes dans un contexte multimédia,” University of Paris, 2000.\u003c/a\u003e\n\n\u003ca name=\"ref3\"\u003e[3] S. Bertet, J. Daniel, E. Parizet, and O. Warusfel, “Investigation on localisation accuracy for first and higher order Ambisonics reproduced sound sources,” Acta Acust. united with Acust., vol. 99, no. 4, pp. 642–657, 2013.\u003c/a\u003e\n\n\u003ca name=\"ref4\"\u003e[4] F. Zotter and M. Frank, “All-round ambisonic panning and decoding,” J. Audio Eng. Soc., vol. 60, no. 10, pp. 807–820, 2012.\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvideolabs%2Flibspatialaudio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvideolabs%2Flibspatialaudio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvideolabs%2Flibspatialaudio/lists"}