Cavern is a fully adaptive object-based audio rendering engine and (up)mixer without limitations for home, cinema, and stage use. Audio transcoding and self-calibration libraries built on the Cavern engine are also available. This repository also features a Unity plugin and a standalone converter called Cavernize.

• Unlimited objects and output channels without position restrictions
• Audio transcoder library with a custom spatial format
• Supported codecs:
  • E-AC-3 with Joint Object Coding (Dolby Digital Plus Atmos)
  • Limitless Audio Format
  • RIFF WAVE
  • Audio Definition Model Broadcast Wave Format
  • Supported containers: .ac3, .eac3, .ec3, .laf, .m4a, .m4v, .mka, .mkv, .mov, .mp4, .qt, .wav, .weba, .webm
• Advanced self-calibration with a microphone
  • Results in close to perfectly flat frequency response, <0.01 dB and <0.01 ms of uniformity
  • Uniformity can be achieved without a calibration file
  • Supported software/hardware for EQ/filter set export:
    • PC: Equalizer APO, CamillaDSP
    • DSP: MiniDSP 2x4 Advanced, MiniDSP 2x4 HD, MiniDSP DDRC-88A
    • Processors: Emotiva, StormAudio
    • Amplifiers: Behringer NX series
    • Others: Audyssey MultEQ-X, Dirac Live, YPAO
• Direction and distance virtualization for headphones
• Real-time upconversion of regular surround sound mixes to 3D
• Mix repositioning based on occupied seats
• Seat movement generation
• Ultra low latency, even the upconverter can work from as low as one sample per frame
• Unity-like listener and source functionality
• Fixes for Unity's Microphone API
  • Works in WebGL too

User documentation can be found at the Cavern documentation webpage. Please go to this page for basic setup, in-depth QuickEQ tutorials, and command-line arguments.

The full list of changes for each version can be found in CHANGELOG.md.

Cavern is a .NET Standard project with no dependencies. Open the Cavern.sln solution with Microsoft Visual Studio 2022 or later and all projects should build.

These examples use the Cavern library to show how it works. The solution containing all sample projects is found at CavernSamples/CavernSamples.sln. The same build instructions apply as to the base project.

Single-purpose sample codes are found under docs/Code.

Open the CavernUnity DLL.sln solution with Microsoft Visual Studio 2022. Remove the references from the CavernUnity DLL project to UnityEngine and UnityEditor. Add these files from your own Unity installation as references. They are found in Editor\Data\Managed under Unity's installation folder.

This is a Code::Blocks project, set up for the MingW compiler. No additional libraries were used, this is standard C++ code, so importing just the .cpp and .h files into any IDE will work perfectly.

Cavern is using audio clips to render the audio scene. A Clip is basically a single audio file, which can be an effect or music. The easiest method of loading from a file is through the Cavern.Format library, which will auto-detect the format:

Clip clip = AudioReader.ReadClip(pathToFile);

Refer to the scripting API for the complete description of this object.

The Listener is the center of the sound stage, which will render the audio sources attached to it. The listener has a Position and Rotation (Euler angles, degrees) field for spatial placement. All sources will be rendered relative to it. Here's its creation:

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

The Listener will set up itself automatically with the user's saved configuration. The used audio channels can be queried through Listener.Channels, which should be respected, and the output audio channel count should be set to its length. If this is not possible, the layout could be set to a standard by the number of channels, for example, this line will set up all listeners to 5.1:

Listener.ReplaceChannels(6);

Refer to the scripting API for the complete description of this object.

This is an audio placed in the sound space, renders a Clip at where it's positioned relative to the Listener. Here's how to create a new source at a given position and attach it to the listener:

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

Sources that are no longer used should be detached from the listener using DetachSource. Refer to the scripting API for the complete description of this object.

To generate the output of the audio space and get the audio samples which should be output to the system, use the following line:

float[] output = listener.Render();

The length of this array is listener.UpdateRate * Listener.Channels.Length.

The Cavern.Format library handles reading and writing audio files. For custom rendering or transcoding, they can be handled on a lower level than loading a Clip.

To open any supported audio file for reading, use the following static function:

AudioReader reader = AudioReader.Open(string path);

After opening a file, the following workflows are available.

The Read() function of an AudioReader returns all samples from the file in an interlaced array with the size of reader.ChannelCount * reader.Length.

For real-time use or cases where progress should be displayed, an audio file can be read block-by-block. First, the header must be read, this is not done automatically. Until the header is not read, metadata like length or channel count are unavailable. Header reading is accomplished by calling reader.ReadHeader().

The ReadBlock(float[] samples, long from, long to) function of an AudioReader reads the next interlaced sample block to the specified array in the specified index range. Samples are counted for all channels. A version of ReadBlock for multichannel arrays (float[channel][sample]) is also available, but in this case, the index range is given for a single channel.

Seeking in local files are supported by calling reader.Seek(long sample). The time in samples is relative to reader.Length, which means it's per a single channel.

The reader.GetRenderer() function returns a Renderer instance that creates Sources for each channel or audio object. These can be retrieved from the Objects property of the renderer. When all of them are attached to a Listener, they will handle fetching the samples. Seeking the reader or the renderer works in this use case.

To create an audio file, use an AudioWriter:

AudioWriter writer = AudioWriter.Create(string path, int channelCount, long length, int sampleRate, BitDepth bits);

This will create the AudioWriter for the appropriate file extension if it's supported.

Just like AudioReader, an AudioWriter can be used with a single call (Write(float[] samples) or Write(float[][] samples)) or block by block (WriteHeader() and WriteBlock(float[] samples, long from, long to)).

Cavern works exactly the same way as Unity's audio engine, only the names are different. For AudioSource, there's AudioSource3D, and for AudioListener, there's AudioListener3D, and so on. You will find all Cavern components in the component browser, under audio, and they will automatically add all their Unity dependencies.

• Scripting API with descriptions of all public members for all public classes
• Virtualizer repository which contains the raw IR measurements and detailed information about their use
• Limitless Audio Format for storing Cavern mixes in a CPU-effective spatial format
• Cavern DCP channel order compared to DCP standards

Cavern is a performance software written in an environment that wasn't made for it. This means that clean code policies like DRY are broken many times if the code is faster this way, usually by orders of magnitude. Most changes should be benchmarked in the target environment, and the fastest code should be chosen, regardless of how bad it looks. This, however, can't result in inconsistent interfaces. In that case, wrappers should be used with the least possible method calls.

While Cavern itself is open-source, the setup utility and most converter interfaces are not, because they are built on licences not allowing it. However, their functionality is almost entirely using this plugin. Builds can be downloaded from the Cavern website.

By downloading, using, copying, modifying, or compiling the source code or a build, you are accepting the licence available here.