audiofile.h

Audio files beyond WAV.

#include <sonore/audiofile.h>

13other declarations

On this page

Design notes

AIFF (and AIFF-C "sowt") because Mac-sourced sample libraries still ship it, and FLAC because impulse-response packs do. The FLAC decoder is OUR OWN implementation of the published format (no library, no licence to carry), and it is graded the only way a lossless codec honestly can be: decode and compare SAMPLE-EXACT against the same material as PCM (see sdk_tests).

MP3 and Ogg Vorbis come from vendored public-domain decoders (see audiofile_codecs.h) because there is nothing to differentiate in a Huffman table; FLAC and AIFF are ours because they are simple enough to own and to prove sample-exact.

Offline-only by design, like wav.h: these allocate and do file IO, so they belong in prepare()-time code and tools, never in process().

Everything funnels into the same WavData a caller already handles; readAudioFile() sniffs the magic and dispatches, so callers need not care which container the user dropped on them. An application that wants the operating system's decoders behind that (M4A, WMA...) opts in through system_audio_format.h; the set here stays the default.

Functions 12

fninline bool readAiff(const char* path, WavData* out, size_t maxSamples = kMaxDecodedSamples)
Read an AIFF or AIFF-C file: 16/24-bit PCM, big-endian ("NONE") or little-endian ("sowt", what modern Macs actually write).
audiofile.h:75
fninline void writeU32BE(std::vector<uint8_t>& out, uint32_t v)
Append v as four bytes, most significant first, as AIFF stores it.
aiffwrite::writeU32BE · audiofile.h:176
fninline void writeU16BE(std::vector<uint8_t>& out, uint16_t v)
Append v as two bytes, most significant first.
aiffwrite::writeU16BE · audiofile.h:184
fninline void writeExtended80(std::vector<uint8_t>& out, double rate)
The sample rate as an 80-bit IEEE extended float, which is the one field that makes AIFF awkward to write. Only positive, finite rates need to survive, so the general case is not attempted.
aiffwrite::writeExtended80 · audiofile.h:192
fninline int32_t quantise(float v, double full)
v in steps of 1/full, rounded and clipped to [-full, full - 1].
aiffwrite::quantise · audiofile.h:208
fninline bool writeAiff(const char* path, const float* interleaved, size_t numFrames, uint16_t numChannels, uint32_t sampleRate, int bitDepth = 24)
Write an AIFF file: 16- or 24-bit PCM, big-endian, which is what the format means by default and what a Mac tool expects to find.
audiofile.h:219
fninline bool readFlac(const char* path, WavData* out)
Read a FLAC file: our own decoder for the published format. 16/24-bit, one to eight channels (and all four stereo decorrelation modes), any block size. It stopped at two, while writeFlac writes up to eight: the SDK could not read back its own 5.1 file.
audiofile.h:649
fninline bool readMp3(const char* path, WavData* out, size_t maxSamples = kMaxDecodedSamples)
Read an MP3. Frames are decoded one at a time; the decoder finds its own sync, so ID3 tags and other leading junk are skipped rather than parsed.
More
Refused past maxSamples decoded samples, the ceiling every other format here is held to. MP3 had none, and it expands 30 to 60 times: a long mix dropped onto a sampler asked for gigabytes, and the bad_alloc took the host with it. The parameter exists for the test; callers leave it.
audiofile.h:944
fninline bool readOgg(const char* path, WavData* out)
Read an Ogg Vorbis file.
audiofile.h:1014
fninline void setAudioFileFallback(AudioFileFallback decoder)
Install (or, with nullptr, remove) the decoder of last resort.
audiofile.h:1099
fninline AudioFileFallback audioFileFallback()
[any thread] The decoder setAudioFileFallback() installed in this module, or null for none.
audiofile.h:1105
fninline bool readAudioFile(const char* path, WavData* out)
Read whichever of WAV/AIFF/FLAC/MP3/Ogg the user actually dropped on the plugin: sniff the magic, dispatch. The built-in decoder always goes first when the magic names one; the fallback, if one is installed, only ever sees what they could not open.
audiofile.h:1113

Aliases 1

usingusing AudioFileFallback = bool (*)(const char* path, WavData* out)
A decoder of last resort for readAudioFile: called with whatever the built-in decoders did not open -- a container none of them knows (M4A, WMA), or one they know carrying a codec they refuse (MP3 or ADPCM inside a RIFF). Null by default, which keeps the fixed set: a file opens or not by what the PLUGIN contains, identically on every machine.
More
system_audio_format.h is what installs one -- enableSystemAudioFormats() hands the operating system's decoders this slot -- and it is a slot rather than an #include because those decoders need <windows.h> and Media Foundation, which this header must not drag into every plugin that reads a WAV.
audiofile.h:1084