Cavern: an object based audio engine written in C#

An audio engine with an object model, not a plugin chain

The description calls Cavern an object based audio engine and codec pack, and the README is blunter, calling it a bleeding edge audio framework that gives you Dolby Atmos and top end room correction on any sound system, and an all in one toolkit for game audio development that doubles as a swiss army knife of filtering and measurement tools. The word object based is the one to hold on to. Instead of a fixed set of channels that a mix is folded into, the scene is described as sources with positions, and the renderer works out the speaker layout, which is why the feature list leads with unlimited objects and output channels without position restrictions, and why the renderer can upconvert an ordinary surround mix into three dimensions in real time. The rest of the list explains what that renderer is used for. Direction and distance virtualisation for headphones, so a binaural rendering path exists without writing one. A filter engine with the common filters integrated into the renderer rather than bolted on. A measurement subsystem for science projects. Mix repositioning based on occupied seats, and seat movement generation, which is a cinema problem rather than a game problem. And a low latency target, with the upconverter claimed to work from as low as one sample per frame. The audience is therefore two audiences at once, a game audio developer and a home cinema enthusiast, and the repository reflects that with separate Unity, sample and native C++ projects.

Clip, listener, source, render

The library quick start in the README is the clearest statement of the object model. A Clip is basically a single audio file, an effect or a piece of music, and the easiest way to load one is through the separate Cavern.Format library, which auto detects the format.

Clip clip = AudioReader.ReadClip(pathToFile);

The Listener is the centre of the sound stage and it renders the sources attached to it, with a Position and a Rotation field, in Euler angles and degrees, and all sources are rendered relative to it.

Listener listener = new Listener() {
    SampleRate = 48000, // Match this with your output
    UpdateRate = 256 // Match this with your buffer size
};

The two numbers in that snippet are the ones to copy. SampleRate has to match the output device and UpdateRate has to match the buffer size, and getting either wrong is the classic way to get a renderer that sounds wrong rather than one that fails. The listener also sets itself up from the user's saved configuration, and the number of output channels is queried through a channels property that should be respected, with the output channel count set to its length, and a static method that replaces the channel count for everyone at once, for example to force a 5.1 layout.

Listener.ReplaceChannels(6);

A Source is an audio placed in the sound space that renders its Clip at the position it holds relative to the listener, and it is attached to the listener with AttachSource and released with DetachSource when it is no longer used.

Source source = new Source() {
    Clip = clip,
    Position = new Vector3(10, 0, 0)
};
listener.AttachSource(source);

Rendering is a single call that returns the samples for the system, and the length of that array is the update rate multiplied by the channel count.

float[] output = listener.Render();

The other half of the design is that the Unity integration mirrors these semantics, with the feature list describing Unity like listener and source functionality, and the microphone API fixes including WebGL support.

Self-calibration with a microphone, and the numbers behind it

The feature that distinguishes Cavern from a spatial audio library is the advanced self calibration with a microphone, and the README attaches two specific figures to it, that it reaches the desired targets with less than 0.01 dB and less than 0.01 ms of uniformity. Those are the project's own claims about its own measurement, and they are the sort of number to test on your own room before you rely on them. Two related capabilities come with it. The first is sound bubble creation without a calibration file, which is the mode for a quick setup where you accept a generic correction rather than a measured one. The second is multi-sub handling that can use not just the subwoofers to flatten the bass in the room, which matters because the low end is where a listening room is most obviously uneven and where a single sub makes the problem worse. The pipeline the README describes is the standard one, measure with a microphone, compute a correction, apply it. The twist is where the correction can go. The Cavern.QuickEQ package handles the equalisation side, and the supported list of export targets is unusually long, which is the subject of its own section below.

The codec list, and why TrueHD is not in the library

The supported codecs are listed in the README, and the format handling is split across two libraries. The core Cavern package handles the general formats, RIFF WAVE, Core Audio Format, Audio Definition Model Broadcast Wave Format, the Limitless Audio Format and Dolby Atmos Master Format, along with E-AC-3 with Joint Object Coding, which is Dolby Digital Plus Atmos. The container list is long, with ac3, eac3, ec3, laf, m4a, m4v, mka, mkv, mov, mp4, qt, wav, weba and webm. The interesting exclusion is at the top of the list. Meridian Lossless Packing, which is what Dolby TrueHD Atmos uses, is supported in Cavernize only, and the README notes it needs the Truehdd tool. So the highest fidelity Atmos codec is not decoded by the library itself but by a companion tool in the same suite. That is a detail worth knowing before you plan a pipeline, because the file you have to open may need a separate conversion step before the library can touch it. The Cavern.Format library handles both reading and writing, and for custom rendering or transcoding the README points at a lower level than loading a Clip, with a static open function taking a path.

AudioReader reader = AudioReader.Open(string path);

The repository layout matches the split, with Cavern.Format, Cavern.QuickEQ.Format and Cavern.QuickEQ as separate projects beside the core, and the NuGet packages published under the Cavern, Cavern.Format and Cavern.QuickEQ names.

QuickEQ and the long list of hardware it can export to

The equalisation side is where the project reaches beyond software, and the list of export targets in the README is the most concrete thing it documents. On computers, the list covers PC, Mac and Linux with Equalizer APO, CamillaDSP and AU N-Band EQ. On dedicated DSP hardware it covers MiniDSP 2x4 Advanced, 2x4 HD, DDRC-88A, Flex HT and the Tide16. On receivers and processors it names Acurus Muse, Emotiva, Monolith HTP-1, Rotel, StormAudio, the Tonewinner AT series, Trinnov, WiiM and several Yamaha models including the CX-A, RX and RX-A series, and on amplifiers the Behringer NX series. Then the room correction platforms, Audyssey MultEQ-X, Dirac Live, JL Audio Tun, Roon and Wavelet. Two observations follow. First, the tool is not only for playing sound, it is a measurement and correction tool that speaks to the correction systems people already own, which is why the export list includes commercial platforms rather than only raw filter files. Second, it is the opposite of a self contained solution, because the correction has to be applied somewhere, and the list tells you where the author expected people to apply it. The user documentation page covers basic setup, in depth QuickEQ tutorials and the command line arguments.

Taking over Unity audio, and fixing the microphone API

The Unity integration is described as a one click audio takeover in the repository description, and the feature list gives the specific reasons it is worth doing. Cavern provides Unity like listener and source functionality, so the object model of the engine and the mental model of the engine match, which removes the usual friction of a third party renderer bolted onto another engine's audio model. It also fixes Unity's Microphone API, and the README adds that it works in WebGL too. That second point is the one that tends to matter in practice, since the browser's microphone handling and the WebGL build path have their own constraints, and a renderer that needs the native microphone path is not deployable to the web. The repository carries the Unity side in two directories, CavernUnity DLL and CavernUnity.WebGL, with a separate solution file for them, and there is a UnityPlugins directory and a Libraries directory for the native components. The build instructions are specific about what to change. You open the CavernUnity DLL solution in Visual Studio 2022, remove the references to UnityEngine and UnityEditor, and add the corresponding files from your own Unity installation as references, finding them under the Editor and Data and Managed path in the Unity installation folder. In other words, the integration is committed against a particular Unity build and expects to be pointed at the Unity you actually ship with, which is a reasonable trade for a native component and a small amount of setup per project.

Building the library, the samples and the native tool

Three build instructions cover three very different toolchains, and the differences tell you what kind of project this is. Cavern itself is a .NET Standard project with no dependencies, and the instruction is to open the Cavern.sln solution in Microsoft Visual Studio 2022 or later and build, with the expectation that all projects build cleanly. The sample projects live in their own solution, CavernSamples.sln, with the same instructions applying, and single purpose code samples sit under a directory called Code samples inside docs. Cavern for Unity has its own solution, CavernUnity DLL.sln, opened in the same version of Visual Studio, with the reference swapping described above. And CavernAmp is the odd one out, a g++ project, so g++ has to be available in the PATH, and since no additional libraries were used and this is standard C++17 code, importing the .cpp and .h files into any IDE is said to work. The Testing directory holds the test project, and the project also ships a Cleanup.bat script, which is the kind of file that tells you the project has been developed on Windows.

The licence deserves its own note. The repository uses a custom licence that GitHub cannot classify, with the terms in a file called LICENSE.md, and the copyright holder is the author, whose name is in the repository. For a library that is MIT licensed elsewhere in the ecosystem, that is a decision you should read rather than assume, and the same applies to the third party components under Libraries and UnityPlugins.

Editorial conclusion

Adopt Cavern if you are writing game audio in C# or Unity and want a renderer you can inspect and tune, with a calibration step that produces real correction filters rather than a preset, or if you need to decode and re-encode Atmos content on a workstation. It does not fit a team that wants a component they can drop into an existing engine without taking on a rendering model, because the object model and the listener and source semantics are the design rather than a detail. Before you adopt it, read the licensing terms in the repository, since the project uses a custom licence that GitHub cannot classify, and check that the formats you need are in the codec list, since TrueHD is handled by the separate Cavernize tool rather than the library.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. VoidXH/Cavern on GitHub