audio.h

#include <modkit/audio.h>92 functions · 17 structs · 6 enums · 17 typedefs · 6 macros

Playback, spatial audio, effects, capture, and recording.

Audio uses Modkit world coordinates: right-handed, Y-up, -Z-forward. Handles are generational; stale handles fail with MK_ERROR_INVALID_ARGUMENT. Unless documented otherwise, control functions are called from the app thread.

Functions

mk_audio_analyzer_attach_busfunction

mk_result mk_audio_analyzer_attach_bus(mk_audio_analyzer_t analyzer, mk_audio_bus_t bus, uint32_t order)

Attach bus for the audio analyzer.

Parameter	Type	Description
analyzer	mk_audio_analyzer_t	Value for analyzer.
bus	mk_audio_bus_t	Value for bus.
order	uint32_t	Value for order.

Returns MK_SUCCESS or an error result.

mk_audio_analyzer_attach_soundfunction

mk_result mk_audio_analyzer_attach_sound(mk_audio_analyzer_t analyzer, mk_sound_t sound, uint32_t order)

Attach sound for the audio analyzer.

Parameter	Type	Description
analyzer	mk_audio_analyzer_t	Value for analyzer.
sound	mk_sound_t	Value for sound.
order	uint32_t	Value for order.

Returns MK_SUCCESS or an error result.

mk_audio_analyzer_createfunction

mk_result mk_audio_analyzer_create(const mk_audio_analyzer_desc *desc, mk_audio_analyzer_t *out_analyzer)

Create audio analyzer.

Parameter	Type	Description
desc	const mk_audio_analyzer_desc *	Configuration descriptor.
out_analyzer	mk_audio_analyzer_t *	Receives the analyzer.

Returns MK_SUCCESS or an error result.

mk_audio_analyzer_desc_initfunction

mk_audio_analyzer_desc mk_audio_analyzer_desc_init(void)

Initialize the audio analyzer desc.

Returns The resulting value.

mk_audio_analyzer_destroyfunction

mk_result mk_audio_analyzer_destroy(mk_audio_analyzer_t analyzer)

Destroy the audio analyzer.

Parameter	Type	Description
analyzer	mk_audio_analyzer_t	Value for analyzer.

Returns MK_SUCCESS or an error result.

mk_audio_analyzer_detachfunction

mk_result mk_audio_analyzer_detach(mk_audio_analyzer_t analyzer)

Detach audio analyzer.

Parameter	Type	Description
analyzer	mk_audio_analyzer_t	Value for analyzer.

Returns MK_SUCCESS or an error result.

mk_audio_analyzer_is_validfunction

bool mk_audio_analyzer_is_valid(mk_audio_analyzer_t h)

Test whether the audio analyzer is valid.

Parameter	Type	Description
h	mk_audio_analyzer_t	Value for h.

Returns True when the condition holds.

mk_audio_analyzer_spectrumfunction

uint32_t mk_audio_analyzer_spectrum(mk_audio_analyzer_t analyzer, float *out_bins, uint32_t bin_count)

Writes linearly grouped magnitudes from DC to Nyquist and returns the number of bins written.

Values are normalized linear amplitudes, not decibels.

Parameter	Type	Description
analyzer	mk_audio_analyzer_t	Value for analyzer.
out_bins	float *	Receives the bins.
bin_count	uint32_t	Number of bin entries.

Returns The resulting value.

mk_audio_analyzer_waveformfunction

uint32_t mk_audio_analyzer_waveform(mk_audio_analyzer_t analyzer, float *out_samples, uint32_t sample_count)

Returns the number of samples written, oldest to newest.

Parameter	Type	Description
analyzer	mk_audio_analyzer_t	Value for analyzer.
out_samples	float *	Receives the samples.
sample_count	uint32_t	Number of sample entries.

Returns The resulting value.

mk_audio_blob_freefunction

void mk_audio_blob_free(mk_audio_blob *blob)

Free audio blob.

Parameter	Type	Description
blob	mk_audio_blob *	Value for blob.

mk_audio_bus_createfunction

mk_result mk_audio_bus_create(const char *name, mk_audio_bus_t *out_bus)

Create audio bus.

Parameter	Type	Description
name	const char *	Stable name.
out_bus	mk_audio_bus_t *	Receives the bus.

Returns MK_SUCCESS or an error result.

mk_audio_bus_destroyfunction

mk_result mk_audio_bus_destroy(mk_audio_bus_t bus)

Destroy the audio bus.

Parameter	Type	Description
bus	mk_audio_bus_t	Value for bus.

Returns MK_SUCCESS or an error result.

mk_audio_bus_fadefunction

mk_result mk_audio_bus_fade(mk_audio_bus_t bus, float to, double seconds)

Perform the audio bus fade operation.

Parameter	Type	Description
bus	mk_audio_bus_t	Value for bus.
to	float	Value for to.
seconds	double	Value for seconds.

Returns MK_SUCCESS or an error result.

mk_audio_bus_get_volumefunction

float mk_audio_bus_get_volume(mk_audio_bus_t bus)

Get volume from the audio bus.

Parameter	Type	Description
bus	mk_audio_bus_t	Value for bus.

Returns The resulting value.

mk_audio_bus_is_validfunction

bool mk_audio_bus_is_valid(mk_audio_bus_t h)

Test whether the audio bus is valid.

Parameter	Type	Description
h	mk_audio_bus_t	Value for h.

Returns True when the condition holds.

mk_audio_bus_masterfunction

mk_audio_bus_t mk_audio_bus_master(void)

Perform the audio bus master operation.

Returns The resulting handle or value.

mk_audio_bus_pausefunction

mk_result mk_audio_bus_pause(mk_audio_bus_t bus)

Pause the audio bus.

Parameter	Type	Description
bus	mk_audio_bus_t	Value for bus.

Returns MK_SUCCESS or an error result.

mk_audio_bus_resumefunction

mk_result mk_audio_bus_resume(mk_audio_bus_t bus)

Resume the audio bus.

Parameter	Type	Description
bus	mk_audio_bus_t	Value for bus.

Returns MK_SUCCESS or an error result.

mk_audio_bus_set_volumefunction

mk_result mk_audio_bus_set_volume(mk_audio_bus_t bus, float volume)

Set volume on the audio bus.

Parameter	Type	Description
bus	mk_audio_bus_t	Value for bus.
volume	float	Value for volume.

Returns MK_SUCCESS or an error result.

mk_audio_capture_availablefunction

uint32_t mk_audio_capture_available(mk_audio_capture_t capture)

Perform the audio capture available operation.

Parameter	Type	Description
capture	mk_audio_capture_t	Value for capture.

Returns The resulting value.

mk_audio_capture_closefunction

mk_result mk_audio_capture_close(mk_audio_capture_t capture)

Close audio capture.

Parameter	Type	Description
capture	mk_audio_capture_t	Value for capture.

Returns MK_SUCCESS or an error result.

mk_audio_capture_desc_initfunction

mk_audio_capture_desc mk_audio_capture_desc_init(void)

Initialize the audio capture desc.

Returns The resulting value.

mk_audio_capture_device_countfunction

uint32_t mk_audio_capture_device_count(void)

Perform the audio capture device count operation.

Returns The resulting value.

mk_audio_capture_device_infofunction

mk_result mk_audio_capture_device_info(uint32_t index, mk_audio_device_info *out_info)

Perform the audio capture device info operation.

Parameter	Type	Description
index	uint32_t	Zero-based index.
out_info	mk_audio_device_info *	Receives the info.

Returns MK_SUCCESS or an error result.

mk_audio_capture_get_statsfunction

mk_result mk_audio_capture_get_stats(mk_audio_capture_t capture, mk_audio_capture_stats *out_stats)

Get stats from the audio capture.

Parameter	Type	Description
capture	mk_audio_capture_t	Value for capture.
out_stats	mk_audio_capture_stats *	Receives the stats.

Returns MK_SUCCESS or an error result.

mk_audio_capture_is_validfunction

bool mk_audio_capture_is_valid(mk_audio_capture_t h)

Test whether the audio capture is valid.

Parameter	Type	Description
h	mk_audio_capture_t	Value for h.

Returns True when the condition holds.

mk_audio_capture_openfunction

mk_result mk_audio_capture_open(const mk_audio_capture_desc *desc, mk_audio_capture_t *out_capture)

Open audio capture.

Parameter	Type	Description
desc	const mk_audio_capture_desc *	Configuration descriptor.
out_capture	mk_audio_capture_t *	Receives the capture.

Returns MK_SUCCESS or an error result.

mk_audio_capture_permissionfunction

mk_audio_permission_state mk_audio_capture_permission(void)

Perform the audio capture permission operation.

Returns The resulting value.

mk_audio_capture_readfunction

uint32_t mk_audio_capture_read(mk_audio_capture_t capture, void *frames, uint32_t frame_capacity)

Read audio capture.

Parameter	Type	Description
capture	mk_audio_capture_t	Value for capture.
frames	void *	Value for frames.
frame_capacity	uint32_t	Value for frame capacity.

Returns The resulting value.

mk_audio_capture_request_permissionfunction

mk_result mk_audio_capture_request_permission(void)

Request permission for the audio capture.

Returns MK_SUCCESS or an error result.

mk_audio_capture_set_monitorfunction

mk_result mk_audio_capture_set_monitor(mk_audio_capture_t capture, mk_audio_bus_t bus, float gain)

Set monitor on the audio capture.

Parameter	Type	Description
capture	mk_audio_capture_t	Value for capture.
bus	mk_audio_bus_t	Value for bus.
gain	float	Value for gain.

Returns MK_SUCCESS or an error result.

mk_audio_capture_startfunction

mk_result mk_audio_capture_start(mk_audio_capture_t capture)

Start the audio capture.

Parameter	Type	Description
capture	mk_audio_capture_t	Value for capture.

Returns MK_SUCCESS or an error result.

mk_audio_capture_stopfunction

mk_result mk_audio_capture_stop(mk_audio_capture_t capture)

Stop the audio capture.

Parameter	Type	Description
capture	mk_audio_capture_t	Value for capture.

Returns MK_SUCCESS or an error result.

mk_audio_desc_initfunction

mk_audio_desc mk_audio_desc_init(void)

Initialize the audio desc.

Returns The resulting value.

mk_audio_effect_attach_busfunction

mk_result mk_audio_effect_attach_bus(mk_audio_effect_t effect, mk_audio_bus_t bus, uint32_t order)

Attach bus for the audio effect.

Parameter	Type	Description
effect	mk_audio_effect_t	Value for effect.
bus	mk_audio_bus_t	Value for bus.
order	uint32_t	Value for order.

Returns MK_SUCCESS or an error result.

mk_audio_effect_attach_soundfunction

mk_result mk_audio_effect_attach_sound(mk_audio_effect_t effect, mk_sound_t sound, uint32_t order)

Attach sound for the audio effect.

Parameter	Type	Description
effect	mk_audio_effect_t	Value for effect.
sound	mk_sound_t	Value for sound.
order	uint32_t	Value for order.

Returns MK_SUCCESS or an error result.

mk_audio_effect_createfunction

mk_result mk_audio_effect_create(const mk_audio_effect_desc *desc, mk_audio_effect_t *out_effect)

Create audio effect.

Parameter	Type	Description
desc	const mk_audio_effect_desc *	Configuration descriptor.
out_effect	mk_audio_effect_t *	Receives the effect.

Returns MK_SUCCESS or an error result.

mk_audio_effect_desc_initfunction

mk_audio_effect_desc mk_audio_effect_desc_init(mk_audio_effect_type type)

Initialize the audio effect desc.

Parameter	Type	Description
type	mk_audio_effect_type	Value for type.

Returns The resulting value.

mk_audio_effect_destroyfunction

mk_result mk_audio_effect_destroy(mk_audio_effect_t effect)

Destroy the audio effect.

Parameter	Type	Description
effect	mk_audio_effect_t	Value for effect.

Returns MK_SUCCESS or an error result.

mk_audio_effect_detachfunction

mk_result mk_audio_effect_detach(mk_audio_effect_t effect)

Detach audio effect.

Parameter	Type	Description
effect	mk_audio_effect_t	Value for effect.

Returns MK_SUCCESS or an error result.

mk_audio_effect_is_validfunction

bool mk_audio_effect_is_valid(mk_audio_effect_t h)

Test whether the audio effect is valid.

Parameter	Type	Description
h	mk_audio_effect_t	Value for h.

Returns True when the condition holds.

mk_audio_effect_set_bypassfunction

mk_result mk_audio_effect_set_bypass(mk_audio_effect_t effect, bool bypass)

Set bypass on the audio effect.

Parameter	Type	Description
effect	mk_audio_effect_t	Value for effect.
bypass	bool	Value for bypass.

Returns MK_SUCCESS or an error result.

mk_audio_effect_updatefunction

mk_result mk_audio_effect_update(mk_audio_effect_t effect, const mk_audio_effect_desc *desc)

Update audio effect.

Parameter	Type	Description
effect	mk_audio_effect_t	Value for effect.
desc	const mk_audio_effect_desc *	Configuration descriptor.

Returns MK_SUCCESS or an error result.

mk_audio_get_infofunction

mk_result mk_audio_get_info(mk_audio_info *out_info)

Get info from the audio.

Parameter	Type	Description
out_info	mk_audio_info *	Receives the info.

Returns MK_SUCCESS or an error result.

mk_audio_get_master_volumefunction

float mk_audio_get_master_volume(void)

Get master volume from the audio.

Returns The resulting value.

mk_audio_initfunction

mk_result mk_audio_init(const mk_audio_desc *desc)

Initialize the audio.

Parameter	Type	Description
desc	const mk_audio_desc *	Configuration descriptor.

Returns MK_SUCCESS or an error result.

mk_audio_is_initializedfunction

bool mk_audio_is_initialized(void)

Test whether the audio is initialized.

Returns True when the condition holds.

mk_audio_listener_set_transformfunction

mk_result mk_audio_listener_set_transform(uint32_t listener, mk_vec3 position, mk_vec3 forward, mk_vec3 up)

Set transform on the audio listener.

Parameter	Type	Description
listener	uint32_t	Value for listener.
position	mk_vec3	Value for position.
forward	mk_vec3	Value for forward.
up	mk_vec3	Value for up.

Returns MK_SUCCESS or an error result.

mk_audio_listener_set_velocityfunction

mk_result mk_audio_listener_set_velocity(uint32_t listener, mk_vec3 velocity)

Set velocity on the audio listener.

Parameter	Type	Description
listener	uint32_t	Value for listener.
velocity	mk_vec3	Value for velocity.

Returns MK_SUCCESS or an error result.

mk_audio_pause_allfunction

void mk_audio_pause_all(void)

Pause the all for the audio.

mk_audio_record_file_startfunction

mk_result mk_audio_record_file_start(mk_audio_capture_t capture, const char *wav_path, mk_audio_recording_t *out_recording)

Start the audio record file.

Parameter	Type	Description
capture	mk_audio_capture_t	Value for capture.
wav_path	const char *	Value for wav path.
out_recording	mk_audio_recording_t *	Receives the recording.

Returns MK_SUCCESS or an error result.

mk_audio_record_memory_startfunction

mk_result mk_audio_record_memory_start(mk_audio_capture_t capture, size_t max_bytes, mk_audio_recording_t *out_recording)

Start the audio record memory.

Parameter	Type	Description
capture	mk_audio_capture_t	Value for capture.
max_bytes	size_t	Max bytes in bytes.
out_recording	mk_audio_recording_t *	Receives the recording.

Returns MK_SUCCESS or an error result.

mk_audio_record_stopfunction

mk_result mk_audio_record_stop(mk_audio_recording_t recording, mk_audio_blob *out_wav)

Stops and destroys a recording handle.

out_wav is required for memory recordings and ignored (but cleared when provided) for file recordings.

Parameter	Type	Description
recording	mk_audio_recording_t	Value for recording.
out_wav	mk_audio_blob *	Receives the wav.

Returns MK_SUCCESS or an error result.

mk_audio_recording_is_validfunction

bool mk_audio_recording_is_valid(mk_audio_recording_t h)

Test whether the audio recording is valid.

Parameter	Type	Description
h	mk_audio_recording_t	Value for h.

Returns True when the condition holds.

mk_audio_resume_allfunction

void mk_audio_resume_all(void)

Resume the all for the audio.

mk_audio_set_master_volumefunction

mk_result mk_audio_set_master_volume(float volume)

Set master volume on the audio.

Parameter	Type	Description
volume	float	Value for volume.

Returns MK_SUCCESS or an error result.

mk_audio_shutdownfunction

void mk_audio_shutdown(void)

Perform the audio shutdown operation.

mk_audio_spatial_desc_initfunction

mk_audio_spatial_desc mk_audio_spatial_desc_init(void)

Initialize the audio spatial desc.

Returns The resulting value.

mk_audio_stop_allfunction

void mk_audio_stop_all(void)

Stop the all for the audio.

mk_audio_updatefunction

void mk_audio_update(void)

Update audio.

mk_sound_create_streamfunction

mk_result mk_sound_create_stream(const mk_sound_stream_desc *desc, mk_sound_t *out_sound)

Create an application-fed bounded PCM stream.

Parameter	Type	Description
desc	const mk_sound_stream_desc *	Configuration descriptor.
out_sound	mk_sound_t *	Receives the sound.

Returns MK_SUCCESS or an error result.

mk_sound_desc_initfunction

mk_sound_desc mk_sound_desc_init(void)

Initialize the sound desc.

Returns The resulting value.

mk_sound_destroyfunction

mk_result mk_sound_destroy(mk_sound_t sound)

Destroy the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns MK_SUCCESS or an error result.

mk_sound_get_durationfunction

double mk_sound_get_duration(mk_sound_t sound)

Get duration from the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns The resulting value.

mk_sound_get_positionfunction

double mk_sound_get_position(mk_sound_t sound)

Get position from the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns The resulting value.

mk_sound_get_statefunction

mk_sound_state mk_sound_get_state(mk_sound_t sound)

Get state from the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns The resulting value.

mk_sound_get_volumefunction

float mk_sound_get_volume(mk_sound_t sound)

Get volume from the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns The resulting value.

mk_sound_is_at_endfunction

bool mk_sound_is_at_end(mk_sound_t sound)

Test whether the sound is at end.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns True when the condition holds.

mk_sound_is_playingfunction

bool mk_sound_is_playing(mk_sound_t sound)

Test whether the sound is playing.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns True when the condition holds.

mk_sound_is_validfunction

bool mk_sound_is_valid(mk_sound_t h)

Test whether the sound is valid.

Parameter	Type	Description
h	mk_sound_t	Value for h.

Returns True when the condition holds.

mk_sound_load_filefunction

mk_result mk_sound_load_file(const char *path, const mk_sound_desc *desc, mk_sound_t *out_sound)

Load file for the sound.

Parameter	Type	Description
path	const char *	Value for path.
desc	const mk_sound_desc *	Configuration descriptor.
out_sound	mk_sound_t *	Receives the sound.

Returns MK_SUCCESS or an error result.

mk_sound_load_memoryfunction

mk_result mk_sound_load_memory(const void *data, size_t size, const mk_sound_desc *desc, mk_sound_t *out_sound)

Copies encoded input bytes; the caller may release data after return.

Parameter	Type	Description
data	const void *	Data buffer.
size	size_t	Size in bytes.
desc	const mk_sound_desc *	Configuration descriptor.
out_sound	mk_sound_t *	Receives the sound.

Returns MK_SUCCESS or an error result.

mk_sound_pausefunction

mk_result mk_sound_pause(mk_sound_t sound)

Pause the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns MK_SUCCESS or an error result.

mk_sound_playfunction

mk_result mk_sound_play(mk_sound_t sound)

Play sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns MK_SUCCESS or an error result.

mk_sound_resumefunction

mk_result mk_sound_resume(mk_sound_t sound)

Resume the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns MK_SUCCESS or an error result.

mk_sound_seekfunction

mk_result mk_sound_seek(mk_sound_t sound, double seconds)

Seek sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.
seconds	double	Value for seconds.

Returns MK_SUCCESS or an error result.

mk_sound_set_busfunction

mk_result mk_sound_set_bus(mk_sound_t sound, mk_audio_bus_t bus)

Set bus on the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.
bus	mk_audio_bus_t	Value for bus.

Returns MK_SUCCESS or an error result.

mk_sound_set_loopingfunction

mk_result mk_sound_set_looping(mk_sound_t sound, bool loop)

Set looping on the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.
loop	bool	Value for loop.

Returns MK_SUCCESS or an error result.

mk_sound_set_panfunction

mk_result mk_sound_set_pan(mk_sound_t sound, float pan)

Set pan on the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.
pan	float	Value for pan.

Returns MK_SUCCESS or an error result.

mk_sound_set_pitchfunction

mk_result mk_sound_set_pitch(mk_sound_t sound, float pitch)

Set pitch on the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.
pitch	float	Value for pitch.

Returns MK_SUCCESS or an error result.

mk_sound_set_spatialfunction

mk_result mk_sound_set_spatial(mk_sound_t sound, const mk_audio_spatial_desc *desc)

Set spatial on the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.
desc	const mk_audio_spatial_desc *	Configuration descriptor.

Returns MK_SUCCESS or an error result.

mk_sound_set_volumefunction

mk_result mk_sound_set_volume(mk_sound_t sound, float volume)

Set volume on the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.
volume	float	Value for volume.

Returns MK_SUCCESS or an error result.

mk_sound_stopfunction

mk_result mk_sound_stop(mk_sound_t sound)

Stop the sound.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns MK_SUCCESS or an error result.

mk_sound_stream_capacityfunction

uint32_t mk_sound_stream_capacity(mk_sound_t sound)

Perform the sound stream capacity operation.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns The resulting value.

mk_sound_stream_consumed_framesfunction

uint64_t mk_sound_stream_consumed_frames(mk_sound_t sound)

Perform the sound stream consumed frames operation.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns The resulting value.

mk_sound_stream_desc_initfunction

mk_sound_stream_desc mk_sound_stream_desc_init(void)

Initialize the sound stream desc.

Returns The resulting value.

mk_sound_stream_finishfunction

mk_result mk_sound_stream_finish(mk_sound_t sound)

Mark the stream complete; playback ends after queued PCM is consumed.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns MK_SUCCESS or an error result.

mk_sound_stream_flushfunction

mk_result mk_sound_stream_flush(mk_sound_t sound)

Drop queued PCM and reset stream counters/end-of-stream state.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns MK_SUCCESS or an error result.

mk_sound_stream_overflowsfunction

uint64_t mk_sound_stream_overflows(mk_sound_t sound)

Perform the sound stream overflows operation.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns The resulting value.

mk_sound_stream_queued_framesfunction

uint32_t mk_sound_stream_queued_frames(mk_sound_t sound)

Perform the sound stream queued frames operation.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns The resulting value.

mk_sound_stream_underrunsfunction

uint64_t mk_sound_stream_underruns(mk_sound_t sound)

Perform the sound stream underruns operation.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.

Returns The resulting value.

mk_sound_stream_writefunction

mk_result mk_sound_stream_write(mk_sound_t sound, const void *frames, uint32_t frame_count, uint32_t *out_written)

Write interleaved PCM frames without blocking.

out_written receives the number accepted. MK_ERROR_QUEUE_FULL means the ring could not accept the entire request; a partial write may still have occurred and is reported through out_written.

Parameter	Type	Description
sound	mk_sound_t	Value for sound.
frames	const void *	Value for frames.
frame_count	uint32_t	Number of frame entries.
out_written	uint32_t *	Receives the written.

Returns MK_SUCCESS or an error result.

Structs

mk_audio_analyzer_descstruct

A transparent PCM tap.

Attach it anywhere in a sound or bus effect chain, then read a recent mono waveform or FFT spectrum from the app thread.

Field	Type	Description
fft_size	uint32_t	Power of two from 256..4096; zero defaults to 1024.
smoothing	float	Spectrum smoothing from 0 (none) to <1.

mk_audio_analyzer_tstruct

Data for audio analyzer.

Field	Type	Description
id	uint32_t	The ID.

mk_audio_blobstruct

Data for audio blob.

Field	Type	Description
data	void *	The data.
size	size_t	The size.

mk_audio_bus_tstruct

Data for audio bus.

Field	Type	Description
id	uint32_t	The ID.

mk_audio_capture_descstruct

Data for audio capture desc.

Field	Type	Description
device_index	uint32_t	UINT32_MAX selects the default device.
format	mk_audio_sample_format	The format.
channels	uint32_t	Zero selects the device default.
sample_rate	uint32_t	Zero selects the device default.
buffer_milliseconds	uint32_t	Zero defaults to 500 ms.

mk_audio_capture_statsstruct

Data for audio capture stats.

Field	Type	Description
frames_captured	uint64_t	The frames captured.
frames_dropped	uint64_t	The frames dropped.
frames_available	uint32_t	The frames available.

mk_audio_capture_tstruct

Data for audio capture.

Field	Type	Description
id	uint32_t	The ID.

mk_audio_descstruct

Data for audio desc.

Field	Type	Description
sample_rate	uint32_t	0 selects the device-native rate.
channels	uint32_t	0 selects the device-native channel count.
listener_count	uint32_t	1..4; zero defaults to one.
max_sounds	uint32_t	Zero defaults to 256.
max_buses	uint32_t	Zero defaults to 32.
max_effects	uint32_t	Zero defaults to 64.
max_analyzers	uint32_t	Zero defaults to 16.
max_captures	uint32_t	Zero defaults to 8.
no_device	bool	Offline/headless engine for tests and tools.

mk_audio_device_infostruct

Data for audio device info.

Field	Type	Description
index	uint32_t	Enumeration-snapshot index used by capture descriptors.
name	char	The name.
is_default	bool	The is default.

mk_audio_effect_descstruct

Data for audio effect desc.

Field	Type	Description
type	mk_audio_effect_type	The type.
cutoff_hz	float	Low/high-pass.
order	uint32_t	Low/high-pass order, 1..8.
delay_seconds	float	Delay.
decay	float	Delay feedback.
wet	float	The wet.
dry	float	The dry.
room_size	float	Reverb.
damping	float	Reverb.
width	float	Reverb.

mk_audio_effect_tstruct

Data for audio effect.

Field	Type	Description
id	uint32_t	The ID.

mk_audio_infostruct

Data for audio info.

Field	Type	Description
sample_rate	uint32_t	The sample rate.
channels	uint32_t	The channels.
listener_count	uint32_t	The listener count.
playback_device	char	The playback device.

mk_audio_recording_tstruct

Data for audio recording.

Field	Type	Description
id	uint32_t	The ID.

mk_audio_spatial_descstruct

Data for audio spatial desc.

Field	Type	Description
position	mk_vec3	The position.
velocity	mk_vec3	The velocity.
direction	mk_vec3	The direction.
positioning	mk_audio_positioning	The positioning.
attenuation	mk_audio_attenuation	The attenuation.
listener	uint32_t	The listener.
min_distance	float	The min distance.
max_distance	float	The max distance.
min_gain	float	The min gain.
max_gain	float	The max gain.
rolloff	float	The rolloff.
doppler	float	The doppler.
cone_inner_radians	float	The cone inner radians.
cone_outer_radians	float	The cone outer radians.
cone_outer_gain	float	The cone outer gain.

mk_sound_descstruct

Data for sound desc.

Field	Type	Description
stream	bool	The stream.
loop	bool	The loop.
spatial	bool	The spatial.
listener_relative	bool	The listener relative.
listener	uint32_t	The listener.
bus	mk_audio_bus_t	The bus.

mk_sound_stream_descstruct

Descriptor for an application-fed bounded PCM stream.

Frames are interleaved. A zero sample rate selects the audio engine rate, zero channels select the engine channel count, and zero capacity selects a 500 ms ring. Streams are ordinary sounds and can be routed through buses, effects, analyzers, fades, pitch, and volume.

Field	Type	Description
format	mk_audio_sample_format	The format.
channels	uint32_t	The channels.
sample_rate	uint32_t	The sample rate.
capacity_frames	uint32_t	The capacity frames.
bus	mk_audio_bus_t	The bus.

mk_sound_tstruct

Data for sound.

Field	Type	Description
id	uint32_t	The ID.

Enums

mk_audio_attenuationenum

Values for audio attenuation.

Value	Description
MK_AUDIO_ATTENUATION_NONE	Selects none.
MK_AUDIO_ATTENUATION_INVERSE	Selects inverse.
MK_AUDIO_ATTENUATION_LINEAR	Selects linear.
MK_AUDIO_ATTENUATION_EXPONENTIAL	Selects exponential.

mk_audio_effect_typeenum

Values for audio effect type.

Value	Description
MK_AUDIO_EFFECT_LOWPASS	Selects lowpass.
MK_AUDIO_EFFECT_HIGHPASS	Selects highpass.
MK_AUDIO_EFFECT_DELAY	Selects delay.
MK_AUDIO_EFFECT_REVERB	Selects reverb.

mk_audio_permission_stateenum

Values for audio permission state.

Value	Description
MK_AUDIO_PERMISSION_UNKNOWN	Selects unknown.
MK_AUDIO_PERMISSION_PENDING	Selects pending.
MK_AUDIO_PERMISSION_GRANTED	Selects granted.
MK_AUDIO_PERMISSION_DENIED	Selects denied.
MK_AUDIO_PERMISSION_UNAVAILABLE	Selects unavailable.

mk_audio_positioningenum

Values for audio positioning.

Value	Description
MK_AUDIO_POSITION_ABSOLUTE	Selects absolute.
MK_AUDIO_POSITION_LISTENER_RELATIVE	Selects listener relative.

mk_audio_sample_formatenum

Values for audio sample format.

Value	Description
MK_AUDIO_FORMAT_F32	Selects f32.
MK_AUDIO_FORMAT_S16	Selects s16.

mk_sound_stateenum

Values for sound state.

Value	Description
MK_SOUND_STATE_INVALID	Selects invalid.
MK_SOUND_STATE_READY	Selects ready.
MK_SOUND_STATE_PLAYING	Selects playing.
MK_SOUND_STATE_PAUSED	Selects paused.
MK_SOUND_STATE_ENDED	Selects ended.
MK_SOUND_STATE_ERROR	Selects error.

Typedefs

mk_audio_analyzer_desctypedef

typedef struct mk_audio_analyzer_desc mk_audio_analyzer_desc

A transparent PCM tap.

Attach it anywhere in a sound or bus effect chain, then read a recent mono waveform or FFT spectrum from the app thread.

mk_audio_attenuationtypedef

typedef enum mk_audio_attenuation mk_audio_attenuation

Values for audio attenuation.

mk_audio_blobtypedef

typedef struct mk_audio_blob mk_audio_blob

Data for audio blob.

mk_audio_capture_desctypedef

typedef struct mk_audio_capture_desc mk_audio_capture_desc

Data for audio capture desc.

mk_audio_capture_statstypedef

typedef struct mk_audio_capture_stats mk_audio_capture_stats

Data for audio capture stats.

mk_audio_desctypedef

typedef struct mk_audio_desc mk_audio_desc

Data for audio desc.

mk_audio_device_infotypedef

typedef struct mk_audio_device_info mk_audio_device_info

Data for audio device info.

mk_audio_effect_desctypedef

typedef struct mk_audio_effect_desc mk_audio_effect_desc

Data for audio effect desc.

mk_audio_effect_typetypedef

typedef enum mk_audio_effect_type mk_audio_effect_type

Values for audio effect type.

mk_audio_infotypedef

typedef struct mk_audio_info mk_audio_info

Data for audio info.

mk_audio_permission_statetypedef

typedef enum mk_audio_permission_state mk_audio_permission_state

Values for audio permission state.

mk_audio_positioningtypedef

typedef enum mk_audio_positioning mk_audio_positioning

Values for audio positioning.

mk_audio_sample_formattypedef

typedef enum mk_audio_sample_format mk_audio_sample_format

Values for audio sample format.

mk_audio_spatial_desctypedef

typedef struct mk_audio_spatial_desc mk_audio_spatial_desc

Data for audio spatial desc.

mk_sound_desctypedef

typedef struct mk_sound_desc mk_sound_desc

Data for sound desc.

mk_sound_statetypedef

typedef enum mk_sound_state mk_sound_state

Values for sound state.

mk_sound_stream_desctypedef

typedef struct mk_sound_stream_desc mk_sound_stream_desc

Descriptor for an application-fed bounded PCM stream.

Frames are interleaved. A zero sample rate selects the audio engine rate, zero channels select the engine channel count, and zero capacity selects a 500 ms ring. Streams are ordinary sounds and can be routed through buses, effects, analyzers, fades, pitch, and volume.

Macros

MK_AUDIO_ANALYZER_INVALIDdefine

MK_AUDIO_ANALYZER_INVALID

Invalid sentinel for audio analyzer.

MK_AUDIO_BUS_INVALIDdefine

MK_AUDIO_BUS_INVALID

Invalid sentinel for audio bus.

MK_AUDIO_CAPTURE_INVALIDdefine

MK_AUDIO_CAPTURE_INVALID

Invalid sentinel for audio capture.

MK_AUDIO_EFFECT_INVALIDdefine

MK_AUDIO_EFFECT_INVALID

Invalid sentinel for audio effect.

MK_AUDIO_RECORDING_INVALIDdefine

MK_AUDIO_RECORDING_INVALID

Invalid sentinel for audio recording.

MK_SOUND_INVALIDdefine

MK_SOUND_INVALID

Invalid sentinel for sound.