Repository files navigation

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

• 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
  • Speaker character matching 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: Acurus Muse, Emotiva, Monolith HTP-1, Sony ES series, StormAudio, Tonewinner AT series
    • Amplifiers: Behringer NX series
    • Others: Audyssey MultEQ-X, Dirac Live, Wavelet, 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 theCavern documentation webpage.Please go to this page for basic setup, in-depth QuickEQ tutorials, andcommand-line arguments.

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

Cavern is a .NET Standard project with no dependencies. Open theCavern.slnsolution with Microsoft Visual Studio 2022 or later and all projects shouldbuild.

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

Single-purpose sample codes are found underdocs/Code samples.

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

This is a Code::Blocks project, set up for the MingW compiler. No additionallibraries 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. AClip is basically asingle audio file, which can be an effect or music. The easiest method ofloading from a file is through theCavern.Format library, which willauto-detect the format:

Clipclip=AudioReader.ReadClip(pathToFile);

Refer to thescripting APIfor the complete description of this object.

TheListener is the center of the sound stage, which will render the audiosources attached to it. The listener has aPosition andRotation (Eulerangles, degrees) field for spatial placement. All sources will be renderedrelative to it. Here's its creation:

Listenerlistener=newListener(){SampleRate=48000,// Match this with your outputUpdateRate=256// Match this with your buffer size};

TheListener will set up itself automatically with the user's savedconfiguration. The used audio channels can be queried throughListener.Channels, which should be respected, and the output audio channelcount should be set to its length. If this is not possible, the layout could beset to a standard by the number of channels, for example, this line will set upall listeners to 5.1:

Listener.ReplaceChannels(6);

Refer to thescripting APIfor the complete description of this object.

This is an audio placed in the sound space, renders aClip at where it'spositioned relative to theListener. Here's how to create a new source at agiven position and attach it to the listener:

Sourcesource=newSource(){Clip=clip,Position=newVector3(10,0,0)};listener.AttachSource(source);

Sources that are no longer used should be detached from the listener usingDetachSource. Refer to thescripting APIfor the complete description of this object.

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

float[]output=listener.Render();

The length of this array islistener.UpdateRate * Listener.Channels.Length.

TheCavern.Format library handles reading and writing audio files. For customrendering or transcoding, they can be handled on a lower level than loading aClip.

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

AudioReaderreader=AudioReader.Open(stringpath);

There is an overload forAudioReader.Open to read audio files from anarbitraryStream. After opening a file, the following workflows are available.

TheRead() function of anAudioReader returns all samples from the file inan interlaced array with the size ofreader.ChannelCount * reader.Length.

For real-time use or cases where progress should be displayed, an audio file canbe read block-by-block. First, the header must be read, this is not doneautomatically. Until the header is not read, metadata like length or channelcount are unavailable. Header reading is accomplished by callingreader.ReadHeader().

TheReadBlock(float[] samples, long from, long to) function of anAudioReader reads the next interlaced sample block to the specified array inthe specified index range. Samples are counted for all channels. A version ofReadBlock for multichannel arrays (float[channel][sample]) is alsoavailable, but in this case, the index range is given for a single channel.

Seeking in local files are supported by callingreader.Seek(long sample). Thetime insamples is relative toreader.Length, which means it's per a singlechannel.

Thereader.GetRenderer() function returns aRenderer instance that createsSources for each channel or audio object. These can be retrieved from theObjects property of the renderer. When all of them are attached to aListener, they will handle fetching the samples. Seeking the reader or therenderer works in this use case.

To create an audio file, use anAudioWriter:

AudioWriterwriter=AudioWriter.Create(stringpath,intchannelCount,longlength,intsampleRate,BitDepthbits);

This will create theAudioWriter for the appropriate file extension if it'ssupported.

Just likeAudioReader, anAudioWriter can be used with a single call(Write(float[] samples) orWrite(float[][] samples)) or block by block(WriteHeader() andWriteBlock(float[] samples, long from, long to)).

Cavern works exactly the same way as Unity's audio engine, only the names aredifferent. ForAudioSource, there'sAudioSource3D, and forAudioListener,there'sAudioListener3D, and so on. You will find all Cavern components in thecomponent browser, under audio, and they will automatically add all their Unitydependencies.

• Knowledge base
• API browser with descriptions of all public members for all public classes
• Virtualizer repository which contains the raw IR measurements and detailed information about their use

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

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

By downloading, using, copying, modifying, or compiling the source code or abuild, you are accepting the licenceavailable here.

This licence heavily discourages commercial usage. If you're not supporting theopen source community with your work, you will need to contact the originalauthor for a Cavern Pro licence through the Cavern website's contact form.