Maul Audio API reference

Generated from the public headers, which are the source of truth: 133 functions across 19 headers.

base.h

The base of the Maul Audio API: the library version, the export and attribute macros, the result codes every fallible function returns, and the allocator owner objects take.

maudVersion maudGetVersion(void);

Returns the version of the library that was linked, which may differ from the MAUD_VERSION macros a program was compiled with.

Returns: The library version.

Thread safety. Safe from any thread.

const char* maudGetResultName(maudResult result);

Returns the name of a result code, for diagnostics.

Parameters:

Returns: A static, NUL-terminated string such as "maud_errorCapacity".

Thread safety. Safe from any thread.

ambisonics.h

The ambisonic bed: sources encoded into a sound field of order 1 to 3, the field rotated, in planar channels the host owns, and decoded for both ears. Channels follow AmbiX: ACN order with SN3D normalization, the field's axes x ahead, y left and z up; directions and rotations are given in the listener's frame (maudVector3) and converted. Encoding, rotating and decoding allocate nothing and do work in proportion to their frames.

uint32_t maudGetAmbisonicChannelCount(uint32_t order);

Returns the channels a bed of an order takes.

Parameters:

Returns: (order + 1) squared, or 0 for an order out of range.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudGetAmbisonicGains(uint32_t order, maudVector3 direction, float* gainsOut);

Computes the gains that encode a direction: one per channel of the order, in ACN order with SN3D normalization.

Parameters:

Returns: maud_success; maud_errorLimit for an order past MAUD_MAX_AMBISONIC_ORDER; maud_errorInvalid for an order of 0, a NULL pointer or a direction that is not finite.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudEncodeAmbisonic(uint32_t order, const maudPanSource* from, const maudPanSource* to, const float* samples, float* const* bed, uint32_t frameCount);

Adds a mono source into a bed, its direction and gain moving linearly from from to to across the call: frame n is encoded with the gains (n + 1) / frameCount of the way.

Parameters:

Returns: maud_success; maud_errorLimit for an order past MAUD_MAX_AMBISONIC_ORDER; maud_errorInvalid for an order of 0, a NULL pointer or a value that is not finite; nothing is written on failure.

Thread safety. Safe from any thread; the bed is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudRotateAmbisonic(float* const* bed, uint32_t frameCount, uint32_t order, const maudQuaternion* from, const maudQuaternion* to);

Rotates a bed in place, the rotation moving linearly from from to to across the call (a crossfade of the two rotated fields; a large change within one call blends rather than turns). A rotation turns the field in the listener's frame: a sound from direction d comes out from the rotated d.

Parameters:

Returns: maud_success; maud_errorLimit for an order past MAUD_MAX_AMBISONIC_ORDER; maud_errorInvalid for an order of 0, a NULL pointer, or a quaternion of zero length or not finite; nothing is written on failure.

Thread safety. Safe from any thread; the bed is used by one thread at a time.

maudBinauralDecoderDef maudDefaultBinauralDecoderDef(void);

Returns the default binaural decoder def: no set, order 3, at most 1,024 frames per call.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateBinauralDecoder(const maudBinauralDecoderDef* def, maudBinauralDecoder** decoderOut);

Creates a binaural decoder: fits filters to the set by magnitude least squares (least squares below 1.5 kHz, magnitudes above), each 2 ms long and delaying the field by 0.67 ms. The fit is the heavy part, done here and never while decoding; its working memory comes from the def's allocator and goes back before this returns.

Parameters:

Returns: maud_success; maud_errorLimit for an order past MAUD_MAX_AMBISONIC_ORDER or a maxFrames past MAUD_MAX_BINAURAL_FRAMES; maud_errorInvalid for a NULL pointer, a def without its cookie, without a set or out of range, or a set whose directions cannot carry the order; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyBinauralDecoder(maudBinauralDecoder* decoder);

Destroys a binaural decoder. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the decoder is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudBinauralDecoder_Decode(maudBinauralDecoder* decoder, const float* const* bed, float* const samplesOut[2], uint32_t frameCount);

Decodes frames of a bed for both ears, written to samplesOut[0] (left) and samplesOut[1] (right).

The bed's samples must be finite: one that is not (NaN or infinite) spoils the output for the filters' length after it, or until maudBinauralDecoder_Reset.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer; maud_errorCapacity for more frames than the def's maxFrames. On failure each channel of samplesOut that is not NULL is silenced over frameCount samples, but never past the def's maxFrames (MAUD_MAX_BINAURAL_FRAMES for a NULL decoder): a failed call writes no more than a successful one could.

Thread safety. Safe from any thread; the decoder is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudBinauralDecoder_Reset(maudBinauralDecoder* decoder);

Forgets the bed a decoder has heard.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread; the decoder is used by one thread at a time.

static inline maudSpeakerDecoderDef maudDefaultSpeakerDecoderDef(void);

Returns the default speaker decoder def: stereo, order 3.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateSpeakerDecoder(const maudSpeakerDecoderDef* def, maudSpeakerDecoder** decoderOut);

Creates a speaker decoder by all-round ambisonic decoding: the bed decoded to 240 near-uniform virtual speakers with max-rE weights, each panned to the layout as a speaker panner pans, folded into one matrix. A source encoded into the bed reaches the speakers with unit energy on average over the sphere, as one panned to them does; the low-frequency channel gets nothing.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorLimit for an order past MAUD_MAX_AMBISONIC_ORDER; maud_errorInvalid for a NULL pointer, a def without its cookie, an order of 0 or a layout the library does not have; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroySpeakerDecoder(maudSpeakerDecoder* decoder);

Destroys a speaker decoder. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the decoder is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSpeakerDecoder_GetMatrix(const maudSpeakerDecoder* decoder, float* matrixOut);

Copies the decoder's matrix: the layout's channel count of rows, each the order's channel count of weights, row-major. Speaker s plays the sum over c of matrix[s][c] times bed channel c.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudSpeakerDecoder_Decode(const maudSpeakerDecoder* decoder, const float* const* bed, float* const* samplesOut, uint32_t frameCount);

Decodes frames of a bed to the layout's channels, written over samplesOut. The decoder holds no state between calls.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer or a channel of samplesOut that shares any frame with one of the bed's. On failure each channel of samplesOut that is not NULL is silenced over frameCount samples; a NULL decoder, which gives no channel count, writes nothing.

Thread safety. Safe from any thread; the output is used by one thread at a time.

binaural.h

Binaural effects: one per source, rendering its mono signal for both ears through a loaded HRTF set (maul-audio/hrtf.h). Processing runs on whatever thread the host renders on: it allocates nothing, takes no lock and does work in proportion to its frames.

maudBinauralDef maudDefaultBinauralDef(void);

Returns the default binaural def: no set, at most 1,024 frames per call, the near field on for a head of 8.75 cm.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateBinaural(const maudBinauralDef* def, maudBinaural** effectOut);

Creates a binaural effect, its memory taken once from the def's allocator.

Parameters:

Returns: maud_success; maud_errorLimit for a maxFrames past MAUD_MAX_BINAURAL_FRAMES; maud_errorInvalid for a NULL pointer or a def without its cookie, without a set or out of range; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyBinaural(maudBinaural* effect);

Destroys a binaural effect. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the effect is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudBinaural_Process(maudBinaural* effect, const maudBinauralParams* params, const float* samples, float* const samplesOut[2], uint32_t frameCount);

Renders frames of a source's mono signal for both ears, written to samplesOut[0] (left) and samplesOut[1] (right). When the position changes, the old and new responses are crossfaded while each ear's delay and near-field filter move, over 2.67 ms; a change during a fade starts when it ends, the latest one winning. The first call after creation or a reset starts at its parameters.

Samples must be finite: one that is not (NaN or infinite) spoils the effect's state, and so its output after, until maudBinaural_Reset.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer or a parameter that is not finite; maud_errorCapacity for more frames than the def's maxFrames. On failure each channel of samplesOut that is not NULL is silenced over frameCount samples, but never past the def's maxFrames (MAUD_MAX_BINAURAL_FRAMES for a NULL effect): a failed call writes no more than a successful one could.

Thread safety. Safe from any thread; the effect is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudBinaural_Reset(maudBinaural* effect);

Forgets the signal an effect has heard and its parameters, as for a source that starts again.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread; the effect is used by one thread at a time.

buffer.h

Conversion between the two buffer layouts of the API: interleaved frames, which streams carry, and one array per channel, which the spatializer works on. Both hold 32-bit float samples.

MAUD_NODISCARD MAUD_API maudResult maudInterleave(const float* const* planar, uint32_t channelCount, uint32_t frameCount, float* interleavedOut);

Interleaves one array per channel into frames: sample i of channel c goes to interleavedOut[i * channelCount + c]. Samples are copied exactly. The arrays must not overlap.

Parameters:

Returns: maud_success, or maud_errorInvalid for a channel count of 0, a NULL array where samples are due, or a total that does not fit in memory.

Thread safety. Real-time safe: no allocation, lock or wait.

MAUD_NODISCARD MAUD_API maudResult maudDeinterleave(const float* interleaved, uint32_t channelCount, uint32_t frameCount, float* const* planarOut);

Splits frames into one array per channel: interleaved[i * channelCount + c] goes to sample i of channel c. Samples are copied exactly. The arrays must not overlap.

Parameters:

Returns: maud_success, or maud_errorInvalid for a channel count of 0, a NULL array where samples are due, or a total that does not fit in memory.

Thread safety. Real-time safe: no allocation, lock or wait.

context.h

The Device part's root: a context holds the connection to a backend and the streams opened through it.

static inline maudContextDef maudDefaultContextDef(void);

Returns the default context def: 8 streams, periods of at most 8,192 frames, 32 devices, 256 notifications, 256 bytes of device name and key, the C library's allocator, the native backend and an offline rate of 48,000.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateContext(const maudContextDef* def, maudContext** contextOut);

Creates a context. An offline context starts with one output and one input device at the offline rate, stereo, each the default of its direction for every role. A native context on Linux connects to PipeWire, waiting up to two seconds on the calling thread for its device list. Either starts with an empty notification queue.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorInvalid for a NULL argument, a def without its cookie, an allocator with one function, a limit other than notifications of 0, or an offline rate out of range; maud_errorLimit for a limit past its MAUD_MAX_* constant (streams, period frames, devices, notifications, device text bytes) or fewer notifications than MAUD_MIN_NOTIFICATIONS, 0 included; maud_errorUnsupported when this build or platform lacks the backend asked for, or no audio service of it answers; maud_errorCapacity when the allocator fails, or when the limits need more memory than the address space holds.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudDestroyContext(maudContext* context);

Destroys a context and every stream it still holds.

Parameters:

Returns: maud_success, or maud_errorBusy when called on a thread that is rendering one of its streams or running its allocator; the context is then left as it was and the call counts as misuse.

Thread safety. Safe from any thread; the context is used by one thread at a time. No stream of the context may be rendering on another thread.

MAUD_NODISCARD MAUD_API maudResult maudContext_Unlock(maudContext* context);

Asks the platform to let the context's audio run. Browsers hold audio until the user acts: call it from a user gesture's handler, such as a click's. On iOS an interruption that ended without the hint to resume holds audio until this is called. Streams held meanwhile are suspended with maud_suspendPolicy and resume, with a notification, once the platform lets the context run. Where no policy holds audio it does nothing. On the web it is what Web Audio calls resume(): the unlock after a gesture. It does not undo maudContext_SetSuspended, the host's own suspension, which only that call ends.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL context; maud_errorBusy when called on a thread that is rendering one of the context's streams or running its allocator, which counts as misuse.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudContext_SetSuspended(maudContext* context, bool suspended);

Suspends a context for the host's lifecycle, or resumes it: the application went to the background, its tab was hidden or the system sleeps, and later it is back. The library never infers this itself. It reports a state the host learns from the system, so it is a setter, not a switch that turns a part of the library on or off. Suspending suspends every stream that runs or only waits to run with maud_suspendHost, with a notification each, and stops its platform side; on the web it also suspends the AudioContext. Resuming lets each run again, or wait for what it waited for. A stream that lost its device keeps that reason. Calling it again the same way does nothing.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL context; maud_errorBusy when called on a thread that is rendering one of the context's streams or running its allocator, which counts as misuse.

Thread safety. Safe from any thread; the context is used by one thread at a time.

maudBackendKind maudContext_GetBackend(const maudContext* context);

Returns the backend a context talks to: the one its def named, or for maud_backendNative the one it chose.

Parameters:

Returns: The backend kind, never maud_backendNative for a context; maud_backendNative for a NULL context.

Thread safety. Safe from any thread.

uint64_t maudContext_GetMisuse(const maudContext* context);

Returns how many calls the context refused as misuse: invalid arguments against it, and calls refused because they came from host code the context was running (control calls on a thread rendering one of its streams or running its allocator, a stream rendered again from its own callback). Stale ids are not misuse.

Parameters:

Returns: The count since the context was created; 0 for a NULL context.

Thread safety. Safe from any thread.

device.h

Devices: the endpoints a context's backend offers, the default for each role, and what each device runs at natively.

MAUD_NODISCARD MAUD_API maudResult maudContext_GetDevices(const maudContext* context, maudDirection direction, maudDeviceId* idsOut, uint32_t capacity, uint32_t* countOut);

Lists the devices of one direction, in a stable order.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer where one is required or an unknown direction.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudDevice_GetInfo(const maudContext* context, maudDeviceId device, maudDeviceInfo* infoOut);

Reports what a device is and runs at.

Parameters:

Returns: maud_success; maud_errorStale for an id that names no device; maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudDevice_GetName(const maudContext* context, maudDeviceId device, char* bytesOut, size_t capacity, size_t* lengthOut);

Copies a device's display name, UTF-8, without a terminating NUL.

Parameters:

Returns: maud_success; maud_errorCapacity when the name does not fit, with zeros copied and lengthOut set; maud_errorStale; maud_errorInvalid for a NULL pointer where one is required.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudDevice_GetKey(const maudContext* context, maudDeviceId device, char* bytesOut, size_t capacity, size_t* lengthOut);

Copies a device's persistent key, UTF-8, without a terminating NUL: the same for the same device after it is unplugged and plugged again, and across restarts where the platform allows, so a host may store it.

Parameters:

Returns: maud_success; maud_errorCapacity when the key does not fit, with zeros copied and lengthOut set; maud_errorStale; maud_errorInvalid for a NULL pointer where one is required.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudContext_GetDefaultDevice(const maudContext* context, maudDirection direction, maudDeviceRole role, maudDeviceId* deviceOut);

Reports the default device of a direction for a role.

Parameters:

Returns: maud_success; maud_empty when the direction has no device; maud_errorInvalid for a NULL pointer or an unknown direction or role.

Thread safety. Safe from any thread; the context is used by one thread at a time.

direct.h

The direct effect: what the direct path does to a source before it is spatialized, in three bands (up to 800 Hz, 800 Hz to 8 kHz, above 8 kHz). Air absorption over distance, a directivity pattern, occlusion and transmission through what blocks the path; distance attenuation is the host's own curve, given as a gain. One effect per source, mono in and mono out, ahead of the binaural effect or a speaker panner.

maudDirectParams maudDefaultDirectParams(void);

Returns the default direct params: gain 1, no distance, a clear path, full transmission and directivity.

Returns: The params.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudGetAirAbsorption(float temperatureCelsius, float humidityPercent, float* absorptionOut);

Computes air absorption per band from ISO 9613 part 1 at 101.325 kPa: the standard's attenuation averaged in dB over each band, as an amplitude exponent per metre. The same bits on every platform and in any floating-point mode, since bakes take it as an input.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer or a value out of range.

Thread safety. Safe from any thread.

static inline maudDirectEffectDef maudDefaultDirectEffectDef(void);

Returns the default direct effect def: 48 kHz, air absorption of ISO 9613 part 1 at 20 degrees C, 50 % humidity and 101.325 kPa.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudGetDirectivity(const maudDirectivityPattern* pattern, maudVector3 toListener, float* directivityOut);

Computes a pattern's directivity towards the listener.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer, a weight outside 0 to 1, a power below 0 or a value that is not finite.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateDirectEffect(const maudDirectEffectDef* def, maudDirectEffect** effectOut);

Creates a direct effect.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorInvalid for a NULL pointer, a def without its cookie, a rate out of range or air absorption below 0 or not finite; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyDirectEffect(maudDirectEffect* effect);

Destroys a direct effect. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the effect is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudDirectEffect_Process(maudDirectEffect* effect, const maudDirectParams* params, const float* samples, float* samplesOut, uint32_t frameCount);

Processes frames, in place allowed. The gain and the band filters move from the previous call's params to these across the call; the first call after creation or a reset starts at these. Band shapes are refitted only when a band moves by 0.05 dB or more.

Samples must be finite: one that is not (NaN or infinite) spoils the effect's state, and so its output after, until maudDirectEffect_Reset.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer, a value that is not finite, a negative gain or distance, or an occlusion, transmission or directivity outside 0 to 1. On failure samplesOut, unless NULL, is silenced over frames samples, and so is samples when it is samplesOut.

Thread safety. Safe from any thread; the effect is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudDirectEffect_Reset(maudDirectEffect* effect);

Forgets the signal and the params an effect has seen.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread; the effect is used by one thread at a time.

focus.h

Audio focus: asking the platform for the application's turn to play, and the state of that turn as the platform reports it. The library acts on none of it; the host pauses, ducks or stops its streams.

MAUD_NODISCARD MAUD_API maudResult maudContext_RequestFocus(maudContext* context, maudFocusRequest request, maudDeviceRole role);

Asks the platform for audio focus, or gives it back. Ask right before playing; on Android an application targeting Android 15 may ask only while it is the top application or runs a foreground service. The state that follows comes as maud_notifyFocusChanged records and from maudContext_GetFocus; a request the platform delays, as during a call, is held once the platform grants it. Releasing reports maud_focusNone. The library never pauses or ducks streams for focus: the host does.

Parameters:

Returns: maud_success when granted, delayed or released; maud_errorPlatform when the platform refuses; maud_errorUnsupported where the backend has no audio focus (the desktop platforms, the web, the offline backend, and Android without the Java half); maud_errorInvalid for a NULL context, an unknown request or role; maud_errorBusy when called on a thread that is rendering one of the context's streams or running its allocator, which counts as misuse.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudContext_GetFocus(const maudContext* context, maudFocus* focusOut);

Reads where the context stands with audio focus, as of the last drain of its notifications.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread; the context is used by one thread at a time.

hrtf.h

Head-related transfer function sets, loaded from the bytes of a .maudhrtf file (docs/internals/file-formats.md) for the binaural renderer. The library reads no files: the host hands over the bytes, which the loader treats as hostile.

static inline maudHrtfDef maudDefaultHrtfDef(void);

Returns the default HRTF def: no bytes, the file's own rate, at most 65,536 directions and 1,024 taps.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudLoadHrtf(const maudHrtfDef* def, maudHrtf** hrtfOut);

Loads an HRTF set from a .maudhrtf file's bytes, checking every count, size and the checksum before it allocates or trusts anything.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorInvalid for a NULL pointer, or a def without its cookie or out of range; maud_errorFormat for bytes that are not a well-formed file (a wrong magic, field, size, ring layout, text or checksum); maud_errorVersion also for another format version, or a field only a later version writes; maud_errorCapacity when the set passes the def's limits or the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyHrtf(maudHrtf* hrtf);

Destroys an HRTF set. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the set is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudHrtf_GetInfo(const maudHrtf* hrtf, maudHrtfInfo* infoOut);

Reports what an HRTF set holds.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread; the set is used by one thread at a time.

layout.h

Channel layouts: which speaker each channel of an interleaved frame feeds, and where that speaker stands.

uint32_t maudGetLayoutChannelCount(maudChannelLayout layout);

Returns the number of channels in a layout.

Parameters:

Returns: The channel count, or 0 for maud_layoutNone and values that name no layout.

Thread safety. Safe from any thread.

maudSpeaker maudGetLayoutSpeaker(maudChannelLayout layout, uint32_t channel);

Returns the speaker one channel of a layout feeds.

Parameters:

Returns: The speaker, or maud_speakerNone when the layout names no layout or the channel is out of its range.

Thread safety. Safe from any thread.

maudSpeakerPosition maudGetLayoutSpeakerPosition(maudChannelLayout layout, uint32_t channel);

Returns the nominal position of the speaker one channel of a layout feeds.

Parameters:

Returns: The position. It is zero for the low-frequency channel, which has no direction, and when the layout names no layout or the channel is out of its range.

Thread safety. Safe from any thread.

notification.h

The context's notification queue: typed records of what changed in its devices and streams, drained by the host off the audio thread.

MAUD_NODISCARD MAUD_API maudResult maudContext_NextNotification(maudContext* context, maudNotification* notificationOut);

Takes the oldest notification from the context's queue. On native backends whose platform reports changes through a loop the library owns, such as PipeWire, it first takes in what the platform reported since the last call, without blocking, and reconnects to a platform service that went away; a host that drains the queue regularly keeps the device table current.

Parameters:

Returns: maud_success; maud_empty when the queue is drained; maud_errorInvalid for a NULL pointer; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

objects.h

Object streams: an output stream whose callback places mono objects around the listener beside the stream's ordinary output, the bed, for a platform renderer to spatialize (Windows' spatial sound objects, Apple's spatial mixer). A device's spatializer and spatialObjectCount say what the platform takes there. The host still computes what the path does to each source (distance, occlusion, air) and applies it to an object's frames; only the binaural or panning step moves to the platform.

MAUD_NODISCARD MAUD_API maudResult maudStream_RenderObjects(maudContext* context, maudStreamId stream, float* bedOut, maudStreamObject* objectsOut, uint32_t objectCount, uint32_t frameCount);

Renders the next frames of an offline object stream to the caller, which stands in for the platform's renderer: the bed into bedOut and each object's frames into the buffer its samples point to, with the position, gain and activity the callback last gave it. The block offers every object (availableObjectCount is the stream's objectCount). The stream's clock advances by frameCount.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL pointer where frames are due, a stream without objects, another object count or a total that does not fit in memory; maud_errorUnsupported on a context that is not offline; maud_errorState for a stopped or suspended stream; maud_errorBusy for one already rendering, or on a thread running the context's allocator.

Thread safety. Real-time safe: no allocation, lock or wait. A stream renders on one thread at a time.

offline.h

The offline backend's scripted devices: a host adds and removes devices and sets defaults, and the context reacts as it would to the platform, so device changes can be tested without hardware.

maudOfflineDeviceDef maudDefaultOfflineDeviceDef(void);

Returns the default offline device def: an output, stereo, at 48,000, of unknown form, with an empty name and key.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateOfflineDevice(maudContext* context, const maudOfflineDeviceDef* def, maudDeviceId* deviceOut);

Adds a device to an offline context. If its direction had no device it becomes the default for both roles, and streams waiting for one move to it.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer where one is required, a def without its cookie, or a value out of range; maud_errorCapacity past the device limit or the name and key limit; maud_errorUnsupported on a context that is not offline; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudDestroyOfflineDevice(maudContext* context, maudDeviceId device);

Removes a device from an offline context, as an unplug would. A default it was passes to the first remaining device of its direction. Streams on it move or are suspended.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL context; maud_errorUnsupported on a context that is not offline; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudOfflineDevice_SetDefault(maudContext* context, maudDeviceId device, maudDeviceRole role);

Makes a device the default of its direction for a role. Streams that follow that default move to it.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL context or an unknown role; maud_errorUnsupported on a context that is not offline; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudOfflineDevice_SetForm(maudContext* context, maudDeviceId device, maudDeviceForm form);

Changes what a device leads to, as plugging headphones into its jack does: a change posts maud_notifyRouteChanged.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL context or an unknown form; maud_errorUnsupported on a context that is not offline; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudOfflineDevice_SetFormat(maudContext* context, maudDeviceId device, maudChannelLayout layout, uint32_t sampleRate);

Changes a device's native layout and rate, as a user picking another format in the system's settings does: a change posts maud_notifyDeviceFormatChanged, and streams on the device that follow its rate take the new one.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL context, an unknown layout or a rate out of range; maud_errorUnsupported on a context that is not offline; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudOfflineDevice_SetSpatializer( maudContext* context, maudDeviceId device, maudPlatformSpatializer spatializer, bool headTracking, uint32_t objectCount);

Changes what a platform spatializer does on an output device, as a user turning one on does: a change posts maud_notifySpatializerChanged. Offline outputs start with none.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL context, an unknown state, objects while not on, or an input device; maud_errorUnsupported on a context that is not offline; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

reverb.h

The parametric reverb: a feedback delay network whose decay follows reverberation times given per band (up to 800 Hz, 800 Hz to 8 kHz, above 8 kHz). It takes the host's mono reverb send and adds a diffuse tail into a first-order ambisonic bed, which the binaural and speaker decoders render. Where a coupled space decays in two slopes, a reverb made with a tail renders the slower one too. One per listener; it allocates nothing once made.

static inline maudReverbDef maudDefaultReverbDef(void);

Returns the default reverb def: 48 kHz, no input delay.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateReverb(const maudReverbDef* def, maudReverb** reverbOut);

Creates a reverb, silent.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorInvalid for a NULL pointer, a def without its cookie, a rate or longest delay out of range; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyReverb(maudReverb* reverb);

Destroys a reverb. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the reverb is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudReverb_Process(maudReverb* reverb, const maudReverbParams* params, const float* samples, float* const* bed, uint32_t frameCount);

Runs frames of the send through the reverb, adding its tail into a first-order bed (four channels, ACN order, SN3D), the send delayed and leveled per band first. When the times or levels change they move to the new ones across the call (a new delay takes effect at once); refitting the filters then takes some tens of microseconds on the calling thread, bounded and without allocation.

Samples must be finite: one that is not (NaN or infinite) spoils the reverb's state, and so its tail after, until maudReverb_Reset.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer or a time, level or delay out of range or not finite (a tail's too); nothing is written then.

Thread safety. Safe from any thread; the reverb is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudReverb_Reset(maudReverb* reverb);

Silences a reverb's tail.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread; the reverb is used by one thread at a time.

scene.h

Acoustic scenes: the library's own geometry and ray tracer, for hosts without one and for work whose results must match on every platform. A scene's static meshes are fixed when it is made; instances of its instancing meshes are made, moved and destroyed at any time and take effect at a commit. Between commits any number of threads query it at once; changes and commits must not overlap queries. Its query functions have the spatializer's hook signatures, the scene as their context. Creating, committing and querying a scene, and making and moving instances, compute in round to nearest with subnormals kept, whatever the calling thread's floating-point mode, and leave that mode as they found it.

static inline maudSceneDef maudDefaultSceneDef(void);

Returns the default acoustic scene def: no meshes, no instances, 16,777,216 triangles at most.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateScene(const maudSceneDef* def, maudScene** sceneOut);

Creates an acoustic scene: copies the meshes and builds a bounding volume hierarchy over their triangles, the same on every platform. A triangle with no area (its corners on one line) covers nothing: it is left out, and no ray hits it. It still counts toward maxTriangles and keeps its place in the order ties go by.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorLimit for a maxTriangles past MAUD_MAX_TRIANGLES or an instanceCapacity past MAUD_MAX_INSTANCES; maud_errorInvalid for a NULL pointer, a def without its cookie, a maxTriangles of 0, a mesh with a NULL array it needs, a vertex index past its vertices or a vertex that is not finite; maud_errorCapacity for more triangles in all than the def's maxTriangles or when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyScene(maudScene* scene);

Destroys an acoustic scene. NULL is ignored. No query may be running on it.

Parameters:

Thread safety. Safe from any thread.

uint64_t maudScene_GetMisuse(const maudScene* scene);

Returns how many calls the scene refused as misuse: invalid arguments to the functions that change its instances. Stale ids are not misuse.

Parameters:

Returns: The count since the scene was created; 0 for a NULL scene.

Thread safety. Safe from any thread.

void maudFindAnyHit(const maudRay* rays, uint32_t count, uint8_t* occludedOut, void* scene);

Answers any-hit queries against a scene (a maudAnyHitFunction): a ray hits when a triangle lies within [minDistance, maxDistance] along it. A ray through an edge or vertex shared by triangles hits. A ray whose origin or direction is not finite, whose direction is zero, or whose distance is NaN misses.

Parameters:

Thread safety. Safe from any thread.

void maudFindClosestHit(const maudRay* rays, uint32_t count, maudRayHit* hitsOut, void* scene);

Answers closest-hit queries against a scene (a maudClosestHitFunction): the nearest triangle within a ray's distances, equal distances going to the triangle listed first (meshes in order, then their triangles); its unit normal faces the side the triangle is wound counterclockwise from. A miss has distance INFINITY. A ray whose origin or direction is not finite, whose direction is zero, or whose distance is NaN misses.

Parameters:

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateSceneInstance( maudScene* scene, uint32_t mesh, const maudSceneInstanceTransform* transform, maudSceneInstanceId* instanceOut);

Makes an instance of one of the scene's instancing meshes. It is part of queries from the next commit on.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer, a mesh out of range, a transform out of range or not finite, or one that puts the mesh's bounds past the float range; maud_errorCapacity when the scene has its capacity of instances. The mesh's bounds are those of the triangles with an area: a mesh whose triangles all have none has no bounds, and any finite transform in range places it.

Thread safety. Safe from any thread; the scene is used by one thread at a time. Changes and commits must not overlap its queries.

MAUD_NODISCARD MAUD_API maudResult maudSceneInstance_Move(maudScene* scene, maudSceneInstanceId instance, const maudSceneInstanceTransform* transform);

Moves an instance, from the next commit on.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer, a 0 or unknown id, a transform out of range or not finite, or one that puts the mesh's bounds, as maudCreateSceneInstance defines them, past the float range; maud_errorStale for a destroyed instance's id.

Thread safety. Safe from any thread; the scene is used by one thread at a time. Changes and commits must not overlap its queries.

MAUD_NODISCARD MAUD_API maudResult maudDestroySceneInstance(maudScene* scene, maudSceneInstanceId instance);

Destroys an instance; it leaves queries at the next commit.

Parameters:

Returns: maud_success, maud_errorInvalid for a NULL scene or a 0 or unknown id, or maud_errorStale for a destroyed instance's id.

Thread safety. Safe from any thread; the scene is used by one thread at a time. Changes and commits must not overlap its queries.

MAUD_NODISCARD MAUD_API maudResult maudScene_Commit(maudScene* scene);

Commits the instances' changes: the live instances, where they are now, are what queries see from here on. The top level is rebuilt over their boxes, the same on every platform.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL scene.

Thread safety. Safe from any thread; the scene is used by one thread at a time. Changes and commits must not overlap its queries.

spatializer.h

The Spatial part's root. A spatializer has two sides. The simulation side, called from the host's own threads or tasks, makes sources, sets their poses and runs steps that work out what the direct path does to each source. The rendering side, on the audio thread, latches the newest step and reads each source's result without allocating, locking or waiting; a step is published whole, never torn. The host passes the results to the direct effect and to the binaural effect or a panner. The simulation side's calls that compute or check floats (creating a spatializer or a source, setting poses and materials, steps, probe sets and bakes, loading a bake) and every task they hand the task hooks run in round to nearest with subnormals kept, and leave the thread's floating-point mode as they found it: a host's flush-to-zero, denormals-are-zero or rounding mode changes no result. The ray queries are called in the library's mode too, not the thread's; the allocator and the task hooks' enqueueTask and finishTask run in the thread's own. The rendering side never changes the mode. Positions are in metres in the host's world, right-handed with +y up; an orientation turns the frame of the listener or a source (+x right, +y up, -z ahead) into the world's.

static inline maudSpatializerDef maudDefaultSpatializerDef(void);

Returns the default spatializer def: 256 sources, up to 64 occlusion points each, transmission paths of up to 4 surfaces, 64 materials, reverberation estimates of 2048 rays through air at 20 degrees and 50 % humidity, no geometric reflections (when asked for: 1 s at 48 kHz), no ray queries, no task hooks.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

maudSourceDef maudDefaultSourceDef(void);

Returns the default source def: omnidirectional, occlusion by one ray (for volumetric occlusion a sphere of 1 m with 32 points), transmission walked.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateSpatializer(const maudSpatializerDef* def, maudSpatializer** spatializerOut);

Creates a spatializer, allocating everything it will use.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorLimit for a count past its MAUD_MAX_* bound or a ray count below MAUD_MIN_REVERB_RAYS; maud_errorInvalid for a NULL pointer, a def without its cookie, a capacity or limit of 0, an air absorption below 0 or not finite, a reflection duration or rate out of range (or reflections without reverberation rays), or one task hook without the other; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroySpatializer(maudSpatializer* spatializer);

Destroys a spatializer and its sources. NULL is ignored. Neither side may be in use. Called from host code the spatializer is running (its hooks or allocator), it does nothing and counts as misuse.

Parameters:

Thread safety. Safe from any thread; the spatializer is used by one thread at a time.

uint64_t maudSpatializer_GetMisuse(const maudSpatializer* spatializer);

Returns how many calls the spatializer refused as misuse: invalid arguments to the functions that change it (a bake file not well formed is not misuse), and calls refused because host code the spatializer was running made them. Stale ids are not misuse.

Parameters:

Returns: The count since the spatializer was created; 0 for a NULL spatializer.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateSource(maudSpatializer* spatializer, const maudSourceDef* def, maudSourceId* sourceOut);

Creates a source, at the world's origin facing -z until its pose is set. It appears in results from the next step on.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer, a def without its cookie, an invalid directivity pattern, an unknown occlusion method, or a volumetric radius or point count out of range; maud_errorCapacity when the spatializer has its capacity of sources; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudDestroySource(maudSpatializer* spatializer, maudSourceId source);

Destroys a source. Results from steps before this still hold it; later steps do not.

Parameters:

Returns: maud_success, maud_errorInvalid for a NULL spatializer or a 0 or unknown id, or maud_errorStale for a destroyed source's id; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSource_SetPose(maudSpatializer* spatializer, maudSourceId source, const maudPose* pose);

Sets a source's pose for the steps that follow.

Parameters:

Returns: maud_success, maud_errorInvalid for a NULL pointer, a 0 or unknown id, a value that is not finite or a zero orientation, or maud_errorStale for a destroyed source's id; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSpatializer_SimulateDirect(maudSpatializer* spatializer, const maudPose* listener);

Runs a direct step for a listener and publishes its results. Its occlusion rays go to the any-hit query, and then the transmission walks of the sources it found occluded to the closest-hit query, a surface at a time, in a fixed order and in batches of at most 64, through the task hooks if set; no result depends on how the tasks split the work.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer, a value that is not finite or a zero orientation; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSpatializer_SetMaterials( maudSpatializer* spatializer, const maudAcousticMaterial* materials, uint32_t count);

Replaces the material table that hits' indices name. A hit on a material outside it lets nothing through.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer or a value outside 0 to 1; maud_errorCapacity for more than the capacity; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse. Nothing changes on failure.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSpatializer_SimulateReverb(maudSpatializer* spatializer, const maudPose* listener);

Estimates the reverberation times at the listener's position from the scene: rays from the listener in batches of 64, each hit lit back toward it through the any-hit query, energy per band in 10 ms bins, a fit of the decay from -5 to -25 dB. The batches go through the task hooks if set. The estimate is the same bits on every platform, however the tasks split the batches and whatever the threads' floating-point modes. Without a closest-hit query there is nothing to reflect and the times are 0.1 s. The next direct step publishes the times with its results. If the def asks for reflections, the same rays' energy, on spherical harmonics of its arrival direction, becomes a response (noise shaped per 10 ms and per band) published at once for maudSpatializer_RenderReflections.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer, a value that is not finite or a zero orientation; maud_errorUnsupported when the def asked for no estimates; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

uint64_t maudSpatializer_LatchResults(maudSpatializer* spatializer);

Latches the newest published step for the rendering side; until the next latch, results come from it.

Parameters:

Returns: The step's number (the first step is 1), or 0 if none has been published or spatializer is NULL.

Thread safety. Real-time safe: no allocation, lock or wait. The rendering side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSource_GetDirectResult( const maudSpatializer* spatializer, maudSourceId source, maudDirectResult* resultOut);

Reads a source's result from the latched step.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer or a 0 or unknown id; maud_errorState before the first latched step; maud_errorStale when the latched step does not hold the source (made after it, or destroyed before it).

Thread safety. Real-time safe: no allocation, lock or wait. The rendering side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSpatializer_RenderReflections( maudSpatializer* spatializer, const maudQuaternion* orientation, const float* send, float* const* bed, uint32_t frameCount);

Renders geometric reflections: convolves the host's mono send with the newest response published and adds the result into a bed of the def's order (ACN, SN3D) in the listener's frame. The response is advanced by the convolution's 128-frame block, so the output does not lag. A long response is convolved in two stages, 128-frame blocks for its start and longer ones (2,048 frames for a second at 48 kHz) for the rest; a new response takes over at the next of those longer blocks and is heard whole within three of them (128 ms for a second at 48 kHz), its start crossfaded over 128 frames and the rest over a block.

The send's samples must be finite: one that is not (NaN or infinite) spoils the bed for about the response's length after it (reflectionDuration).

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer or an orientation of zero length or not finite, as the thread's floating-point mode reads it (denormals-are-zero reads subnormal components as 0); maud_errorUnsupported when the def asked for no reflections.

Thread safety. Real-time safe: no allocation, lock or wait. The rendering side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSpatializer_GetReverbResult( const maudSpatializer* spatializer, maudReverbResult* resultOut);

Reads the reverberation estimate the latched step published.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer; maud_errorState before the first latched step.

Thread safety. Real-time safe: no allocation, lock or wait. The rendering side is used by one thread at a time.

maudProbeSetDef maudDefaultProbeSetDef(void);

Returns the default probe set def: no points and an empty box (set one or the other), 2 m spacing, 1.5 m height, a 5 m range.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateProbeSet(maudSpatializer* spatializer, const maudProbeSetDef* def, maudProbeSetId* setOut);

Creates a probe set: the def's points, or probes generated over its box; then the links, a ray for each pair within range (every pair is linked without an any-hit query). The rays go through the task hooks; the same scene and def give the same set however they run.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer, a def without its cookie, a value out of range or not finite, or neither points nor a box (one with height); maud_errorUnsupported to generate on a spatializer without a closest-hit query; maud_errorLimit for a box of more than MAUD_MAX_PROBE_COLUMNS (16,777,216) columns; maud_errorCapacity when the spatializer has its capacity of sets, past maxProbes or maxProbePairs, or when memory runs out; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudDestroyProbeSet(maudSpatializer* spatializer, maudProbeSetId set);

Destroys a probe set. Its id is stale before its memory goes back to the allocator, so the allocator's free finds the set gone if it reads it back.

Parameters:

Returns: maud_success, maud_errorInvalid for a NULL spatializer or a 0 or unknown id, or maud_errorStale for a destroyed set's id; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudProbeSet_GetInfo(const maudSpatializer* spatializer, maudProbeSetId set, uint32_t first, maudProbeSetInfo* infoOut, maudVector3* pointsOut, uint32_t count);

Reads what a probe set holds and, if pointsOut is not NULL, copies its probes from first on into pointsOut, count of them.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL spatializer or info, a 0 or unknown id, or probes past the set's; maud_errorStale for a destroyed set's id.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSpatializer_SetPathingProbeSet(maudSpatializer* spatializer, maudProbeSetId set);

Sets the probe set occluded sources look for paths over, from the next direct step on; 0 for none. Destroying the set ends its use.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL spatializer or an unknown id; maud_errorStale for a destroyed set's id; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudProbeSet_Bake(maudSpatializer* spatializer, maudProbeSetId set);

Bakes a probe set: a reverberation estimate at every probe, as maudSpatializer_SimulateReverb makes one there, with the energy field when the spatializer renders reflections; it replaces an earlier bake. The rays go through the task hooks, and the bake's values are the same bits on every platform, however the tasks run and whatever the threads' floating-point modes. Its memory: 24 bytes a probe, and with reflections 12 times the bed's channels times the response's 10 ms bins in bytes more. A re-bake builds the new bake beside the earlier one, which the set keeps until the new one is whole, so both are held for that time.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL spatializer or a 0 or unknown id; maud_errorStale for a destroyed set's id; maud_errorUnsupported on a spatializer without reverberation rays or a closest-hit query; maud_errorCapacity when memory runs out (an earlier bake is then gone); maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSpatializer_SetReverbProbeSet(maudSpatializer* spatializer, maudProbeSetId set);

Sets the baked probe set reverberation estimates come from, from the next maudSpatializer_SimulateReverb on; 0 for none. An estimate then blends the 4 nearest probes the listener sees within the set's range (Shepard's weights, cut off at the fifth nearest, so moving is smooth) and traces nothing; with no probe in sight it traces. Destroying the set ends its use.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL spatializer or an unknown id; maud_errorStale for a destroyed set's id; maud_errorState for a set without a bake; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudProbeSet_Save(const maudSpatializer* spatializer, maudProbeSetId set, void* bytesOut, size_t capacity, size_t* sizeOut);

Saves a probe set as a .maudbake file (docs/internals/file-formats.md): its probes, links and bake. A set saves to the same bytes on every platform.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL spatializer or size, or a 0 or unknown id; maud_errorStale for a destroyed set's id; maud_errorCapacity when capacity is short of the size, a part of the file would pass the 4 GiB a field holds (the energy fields of about 55,800 probes at order 3 and 401 bins), or the size does not fit in size_t. On failure bytesOut, unless NULL, is zeroed over capacity bytes, so it never holds an earlier save.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudLoadProbeSet(maudSpatializer* spatializer, const void* bytes, size_t size, maudProbeSetId* setOut);

Loads a probe set from a .maudbake file, treated as hostile: every count is checked against the spatializer's limits before anything is allocated, and every value against its range. A file with a bake loads only if its fields match the spatializer's reflections (none, or the same order and length).

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL pointer; maud_errorFormat for a file not well formed; maud_errorVersion for another format version or a field only a later version writes; maud_errorUnsupported for energy fields that do not match; maud_errorCapacity past maxProbes or maxProbePairs, with the spatializer's sets all taken or none asked for, or when memory runs out; maud_errorBusy when host code the spatializer is running (its hooks or allocator) makes the call, which counts as misuse.

Thread safety. Safe from any thread; the simulation side is used by one thread at a time.

speakers.h

Panning to speakers: a panner per channel layout, made once from the layout's nominal positions, pans sources by vector base amplitude panning (VBAP) into the layout's channels. Once made it is read-only: any number of sources share it, from any thread. Panning allocates nothing and does work in proportion to its frames.

static inline maudSpeakerPannerDef maudDefaultSpeakerPannerDef(void);

Returns the default speaker panner def: stereo.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateSpeakerPanner(const maudSpeakerPannerDef* def, maudSpeakerPanner** pannerOut);

Creates a speaker panner. Mono passes a source through; stereo pans by how far to the side a source is (one behind counts as in front); other layouts by VBAP over the triangles between their speakers, with imaginary speakers above and below whose share goes to their real neighbours. Gains keep the energy; the low-frequency channel gets nothing.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorInvalid for a NULL pointer, a def without its cookie or a layout the library does not have; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroySpeakerPanner(maudSpeakerPanner* panner);

Destroys a speaker panner. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the panner is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudSpeakerPanner_GetGains(const maudSpeakerPanner* panner, maudVector3 direction, float* gainsOut);

Computes a direction's gain for every channel of the layout.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer or a direction that is not finite.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudSpeakerPanner_Pan( const maudSpeakerPanner* panner, const maudPanSource* from, const maudPanSource* to, const float* samples, float* const* channels, uint32_t frameCount);

Adds a mono source into the layout's channels, its direction and gain moving linearly from from to to across the call: frame n uses the gains (n + 1) / frameCount of the way.

Parameters:

Returns: maud_success, or maud_errorInvalid for a NULL pointer or a value that is not finite; nothing is written then.

Thread safety. Safe from any thread; the output is used by one thread at a time.

stream.h

Streams: one direction of audio between a host and a device, in interleaved 32-bit float frames, handed to the host's real-time callback one fixed period at a time.

maudStreamDef maudDefaultStreamDef(void);

Returns the default stream def: an output stream in callback mode, stereo, at the device's native rate, with the backend's default period, following the general role's default device, and no callback.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateStream(maudContext* context, const maudStreamDef* def, maudStreamId* streamOut);

Creates a stream, stopped, and allocates everything it will use.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL argument, a def without its cookie or callback, or a value out of range; maud_errorLimit for an objectCount past MAUD_MAX_STREAM_OBJECTS; maud_errorUnsupported for what the backend cannot do (the offline backend has only pull mode and no converter; ALSA, Core Audio, iOS and AAudio have no loopback, and no platform an exclusive one); maud_errorCapacity past the stream or period limit or when the allocator fails; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudDestroyStream(maudContext* context, maudStreamId stream);

Destroys a stream. Its id becomes stale, before the stream's memory goes back to the allocator, so the allocator's free finds the stream gone if it reads it back. On a platform backend its callback has returned for the last time when this returns.

Parameters:

Returns: maud_success; maud_errorStale for an id that names no stream; maud_errorInvalid for a NULL context; maud_errorBusy on a thread rendering one of the context's streams or running its allocator, or, on the offline backend, while another thread renders the stream.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudStream_Start(maudContext* context, maudStreamId stream);

Starts a stream. Starting a started stream does nothing.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL context; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudStream_Stop(maudContext* context, maudStreamId stream);

Stops a stream. Stopping a stopped stream does nothing.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL context; maud_errorBusy on a thread rendering one of the context's streams or running its allocator.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudStream_GetFormat(const maudContext* context, maudStreamId stream, maudStreamFormat* formatOut);

Reports what a stream runs at.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudStream_GetStatus(const maudContext* context, maudStreamId stream, maudStreamStatus* statusOut);

Reports whether a stream is started, suspended, and on which device.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudStream_GetPosition(const maudContext* context, maudStreamId stream, uint64_t* positionOut);

Reports how many frames a stream has moved to or from its device.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudStream_GetClock(const maudContext* context, maudStreamId stream, maudStreamClock* clockOut);

Reports where a stream's frames meet the host clock. The platform stamps it at each callback, so it follows route changes; a frame's time follows from it at the stream's rate.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL pointer.

Thread safety. Safe from any thread. It never makes the rendering thread wait.

int64_t maudGetHostNanoseconds(void);

Returns the host clock streams are stamped with: CLOCK_MONOTONIC on Linux and other POSIX systems, the performance counter on Windows, the HAL's host time on macOS, performance.now() on the web.

Returns: Nanoseconds since an unspecified start.

Thread safety. Real-time safe: no allocation, lock or wait.

MAUD_NODISCARD MAUD_API maudResult maudStream_Render(maudContext* context, maudStreamId stream, float* framesOut, uint32_t frameCount);

Renders the next frames of an offline output stream into a caller buffer, calling the stream's callback once per period as needed, on the calling thread. The stream's clock advances by frameCount. A rate change from a move to another device applies from the first block this call produces.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL pointer where frames are due, an input stream or a total that does not fit in memory; maud_errorUnsupported on a context that is not offline; maud_errorState for a stopped or suspended stream; maud_errorBusy for one already rendering, or on a thread running the context's allocator.

Thread safety. Real-time safe: no allocation, lock or wait. A stream renders on one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudStream_Feed(maudContext* context, maudStreamId stream, const float* frames, uint32_t frameCount);

Feeds the next frames to an offline input stream from a caller buffer, calling the stream's callback once per completed period, on the calling thread. The stream's clock advances by frameCount. A loopback stream is fed the same way, with what its device played.

Parameters:

Returns: maud_success; maud_errorStale; maud_errorInvalid for a NULL pointer where frames are due, an output stream or a total that does not fit in memory; maud_errorUnsupported on a context that is not offline; maud_errorState for a stopped or suspended stream; maud_errorBusy for one already rendering, or on a thread running the context's allocator.

Thread safety. Real-time safe: no allocation, lock or wait. A stream renders on one thread at a time.

voice.h

First-party voice processing: a voice activity detector and an automatic gain control. They stand apart from contexts and streams; a host runs them on captured frames, in its callback or anywhere else.

static inline maudVoiceDetectorDef maudDefaultVoiceDetectorDef(void);

Returns the default voice detector def: 48,000, mono, aggressiveness 1, a 200 ms hangover, the default allocator.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateVoiceDetector(const maudVoiceDetectorDef* def, maudVoiceDetector** detectorOut);

Creates a voice activity detector.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorInvalid for a NULL pointer or a def out of range; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyVoiceDetector(maudVoiceDetector* detector);

Destroys a voice activity detector. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the detector is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudVoiceDetector_Detect(maudVoiceDetector* detector, const float* frames, uint32_t frameCount, maudVoiceState* stateOut);

Analyzes interleaved frames, in any count: what does not complete a 10 ms frame waits for the next call, so the results do not depend on how the frames are cut.

Samples must be finite: one that is not (NaN or infinite) spoils the detector's state, and so all it reports after, until it is destroyed and made again. Samples within 2^64 of zero, far past full scale, keep all it reports finite.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL detector, or NULL frames with a frameCount.

Thread safety. Real-time safe: no allocation, lock or wait. The detector is used by one thread at a time.

static inline maudGainControlDef maudDefaultGainControlDef(void);

Returns the default gain control def: 48,000, mono, a target of -25 dBFS, gains from -10 to 50 dB starting at 15, 6 dB per second, noise kept under -50 dBFS, aggressiveness 1, the default allocator.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateGainControl(const maudGainControlDef* def, maudGainControl** gainOut);

Creates an automatic gain control.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorInvalid for a NULL pointer or a def out of range; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyGainControl(maudGainControl* gain);

Destroys an automatic gain control. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the gain control is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudGainControl_Apply(maudGainControl* gain, float* frames, uint32_t frameCount, maudGainState* stateOut);

Applies the gain to interleaved frames in place, in any count; the output does not depend on how the frames are cut. The gain follows what the frames before them showed, so it adds no delay.

Samples must be finite: one that is not (NaN or infinite) spoils the gain control's state, and so its output after, until it is destroyed and made again. Samples within 2^64 of zero, far past full scale, keep its output and state finite.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL gain control, or NULL frames with a frameCount.

Thread safety. Real-time safe: no allocation, lock or wait. The gain control is used by one thread at a time.

static inline maudNoiseSuppressorDef maudDefaultNoiseSuppressorDef(void);

Returns the default noise suppressor def: 48,000, mono, a floor of -30 dB, a high-pass at 100 Hz, the default allocator.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateNoiseSuppressor( const maudNoiseSuppressorDef* def, maudNoiseSuppressor** suppressorOut);

Creates a noise suppressor.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorInvalid for a NULL pointer or a def out of range; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyNoiseSuppressor(maudNoiseSuppressor* suppressor);

Destroys a noise suppressor. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the noise suppressor is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudNoiseSuppressor_Suppress(maudNoiseSuppressor* suppressor, float* frames, uint32_t frameCount, maudNoiseState* stateOut);

Suppresses noise in interleaved frames in place, in any count; the output does not depend on how the frames are cut. It lags the input by 20 ms, two of its 10 ms hops: a hop goes out from the 20 ms frame that reaches into the next. The first 10 ms out are silence.

Samples must be finite: one that is not (NaN or infinite) spoils the noise suppressor's state, and so its output after, until it is destroyed and made again. Samples within 2^64 of zero, far past full scale, keep its output and state finite.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL noise suppressor, or NULL frames with a frameCount.

Thread safety. Real-time safe: no allocation, lock or wait. The noise suppressor is used by one thread at a time.

static inline maudEchoCancellerDef maudDefaultEchoCancellerDef(void);

Returns the default echo canceller def: 48,000, a path of 0.2 s, a noise floor of -15 dB, the default allocator.

The default is built in the program from the headers it includes, so the version it stamps is the program's.

Returns: The def, with a valid cookie and version.

Thread safety. Safe from any thread.

MAUD_NODISCARD MAUD_API maudResult maudCreateEchoCanceller(const maudEchoCancellerDef* def, maudEchoCanceller** cancellerOut);

Creates an echo canceller.

Parameters:

Returns: maud_success; maud_errorVersion for a def stamped with another binary interface than the library's, checked before anything else of it; maud_errorInvalid for a NULL pointer or a def out of range; maud_errorCapacity when the allocator fails.

Thread safety. Safe from any thread.

void maudDestroyEchoCanceller(maudEchoCanceller* canceller);

Destroys an echo canceller. NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the echo canceller is used by one thread at a time.

MAUD_NODISCARD MAUD_API maudResult maudEchoCanceller_Cancel(maudEchoCanceller* canceller, float* capture, const float* render, uint32_t frameCount, maudEchoState* stateOut);

Takes the echo of the render out of the capture, in place, in any count of frames; the output does not depend on how the frames are cut. It works in blocks of the smallest power of two of frames lasting 8 ms or more (128 at 16,000, 512 at 48,000) and lags the input by two: the first two blocks out are silence.

Samples of both must be finite: one that is not (NaN or infinite) spoils the echo canceller's state, and so its output after, until it is destroyed and made again. Samples within 2^64 of zero, far past full scale, keep its output and state finite.

Parameters:

Returns: maud_success; maud_errorInvalid for a NULL echo canceller, or NULL frames with a frameCount.

Thread safety. Real-time safe: no allocation, lock or wait. The echo canceller is used by one thread at a time.