Data Structures
struct	bj_audio_properties_t
struct	bj_audio_play_note_data_t
struct	bj_audio_layer_t
struct	bj_audio_layer_create_info

Macros
#define	BJ_AUDIO_FORMAT_WIDTH(x)
#define	BJ_AUDIO_FORMAT_FLOAT(x)
#define	BJ_AUDIO_FORMAT_INT(x)
#define	BJ_AUDIO_FORMAT_BIG_ENDIAN(x)
#define	BJ_AUDIO_FORMAT_SIGNED(x)

Typedefs
typedef struct bj_audio_device_t	bj_audio_device
typedef enum bj_audio_format_t	bj_audio_format
typedef struct bj_audio_properties_t	bj_audio_properties
typedef void(*	bj_audio_callback_t) (void buffer, unsigned frames, const bj_audio_properties audio, void *user_data, uint64_t base_sample_index)
typedef struct bj_audio_play_note_data_t	bj_audio_play_note_data
typedef struct bj_audio_layer_t	bj_audio_layer

Enumerations
enum	bj_audio_format_t { BJ_AUDIO_FORMAT_UNKNOWN = 0x0000 , BJ_AUDIO_FORMAT_INT16 = 0x8010 , BJ_AUDIO_FORMAT_F32 = 0x8120 }

Functions
bj_audio_device *	bj_open_audio_device (const bj_audio_properties p_properties, bj_audio_callback_t p_callback, void p_callback_user_data, bj_error **p_error)
void	bj_close_audio_device (bj_audio_device *p_device)
void	bj_play_audio_device (bj_audio_device *p_device)
void	bj_pause_audio_device (bj_audio_device *p_device)
void	bj_reset_audio_device (bj_audio_device *p_device)
void	bj_stop_audio_device (bj_audio_device *p_device)
bj_bool	bj_audio_playing (const bj_audio_device *p_device)
void	bj_play_audio_note (void buffer, unsigned frames, const bj_audio_properties audio, void *user_data, uint64_t base_sample_index)

Detailed Description

Provide basic PCM audio playback.

The audio component offers 1-channel Pulse-Code Modulation (PCM) playback with a callback-based interface, suitable for retro-style games and basic procedural sound generation.

Banjo supports audio manipulation for Windows, GNU/Linux and WebAssembly.

Todo

Add support for audio on macOS

Add support for audio push-based API

Add support for audio WAVE format

Add support for audio MIDI format

Data Structure Documentation

◆ bj_audio_properties_t

struct bj_audio_properties_t

Describe properties of an audio device.

This structure is passed to audio callbacks to inform them about the format and limits of the current playback device.

See also: bj_audio_callback_t

Data Fields
int16_t	amplitude	Maximum amplitude of the output samples.
unsigned int	channels	Number of channels (currently always 1).
bj_audio_format	format	Sampling format.
unsigned int	sample_rate	Number of samples per second (Hz).

◆ bj_audio_layer_t

struct bj_audio_layer_t

Represent an audio backend (ALSA, MME, etc).

Internal structure used to abstract platform-specific device control.

Data Fields

void(*)(struct bj_audio_layer_t *self, bj_audio_device *device)

close_device

Close an audio device managed by this backend.

Used to stop and destroy a specific audio device instance.

Parameters

self	Pointer to the audio layer instance.
device	Pointer to the audio device to close.

struct bj_audio_layer_data_t *

data

Backend-specific data pointer.

Used internally by the backend to store platform-specific state.

void(*)(struct bj_audio_layer_t *self, bj_error **p_error)

end

Shutdown and clean up the backend.

Called during deinitialization to release all backend-related resources.

Parameters

self	Pointer to the audio layer instance.
p_error	Optional pointer to receive error information.

bj_audio_device *(*)(struct bj_audio_layer_t *self, const bj_audio_properties *p_properties, bj_audio_callback_t callback, void *user_data, bj_error **p_error)

open_device

Open an audio device through this backend.

Initializes a new audio device using the given properties and callback.

Parameters

self	Pointer to the audio layer instance.
p_properties	Optional requested device properties, or NULL.
callback	User-provided callback for audio sample generation.
user_data	Pointer passed to the audio callback on each call.
p_error	Optional pointer to receive error information.

Returns: A new audio device instance, or NULL on failure.

◆ bj_audio_layer_create_info

struct bj_audio_layer_create_info

Declare a backend and its constructor function.

Used at initialization to register available backends such as ALSA, MME, or WebAudio.

See also: bj_audio_layer

Collaboration diagram for bj_audio_layer_create_info:

[legend]

Data Fields
bj_audio_layer ()(bj_error **)	create	Factory function to instantiate the backend.
const char *	name	Name of the backend (e.g., "alsa", "mme").

Macro Definition Documentation

◆ BJ_AUDIO_FORMAT_BIG_ENDIAN

#define BJ_AUDIO_FORMAT_BIG_ENDIAN ( x )

Value:

((x) & (1u<<12))

Test whether the audio format uses big-endian byte order.

Parameters

x	Audio format code (bj_audio_format).

Returns: Non-zero if big-endian, zero otherwise.

◆ BJ_AUDIO_FORMAT_FLOAT

#define BJ_AUDIO_FORMAT_FLOAT ( x )

Value:

((x) & (1u<<8))

Test whether the audio format is floating point.

Parameters

x	Audio format code (bj_audio_format).

Returns: Non-zero if float, zero otherwise.

◆ BJ_AUDIO_FORMAT_INT

#define BJ_AUDIO_FORMAT_INT ( x )

Value:

(!((x) & (1u<<8)))

Test whether the audio format is integer PCM.

Parameters

x	Audio format code (bj_audio_format).

Returns: Non-zero if integer PCM, zero otherwise.

◆ BJ_AUDIO_FORMAT_SIGNED

#define BJ_AUDIO_FORMAT_SIGNED ( x )

Value:

((x) & (1u<<15))

Test whether integer samples are signed.

Parameters

x	Audio format code (bj_audio_format).

Returns: Non-zero if signed, zero otherwise.

◆ BJ_AUDIO_FORMAT_WIDTH

#define BJ_AUDIO_FORMAT_WIDTH ( x )

Value:

((x) & (0xFFu))

Extract the sample width (in bits) from an audio format code.

Parameters

x	Audio format code (bj_audio_format).

Returns: Unsigned integer width in bits (e.g., 16 or 32).

Typedef Documentation

◆ bj_audio_callback_t

typedef void(* bj_audio_callback_t) (void *buffer, unsigned frames, const bj_audio_properties *audio, void *user_data, uint64_t base_sample_index)

Define a callback for generating audio samples.

This callback is called periodically from a dedicated audio thread to generate PCM audio data.

Parameters

buffer	Output buffer to write int16_t samples into.
frames	Number of audio frames to generate.
audio	Pointer to audio device properties (read-only).
user_data	User-defined pointer passed at device creation.
base_sample_index	Index of the first sample in the current buffer.

See also: bj_open_audio_device; bj_audio_properties

◆ bj_audio_device

typedef struct bj_audio_device_t bj_audio_device

Opaque handle to an audio device instance.

Instances are created with bj_open_audio_device and must be released with bj_close_audio_device.

See also: bj_open_audio_device; bj_close_audio_device

◆ bj_audio_format

typedef enum bj_audio_format_t bj_audio_format

Audio sample format descriptor.

Encodes sample width, sign, float/integer, and endianness flags. Use the helper macros to inspect properties.

See also: BJ_AUDIO_FORMAT_WIDTH; BJ_AUDIO_FORMAT_FLOAT; BJ_AUDIO_FORMAT_INT; BJ_AUDIO_FORMAT_BIG_ENDIAN; BJ_AUDIO_FORMAT_SIGNED

◆ bj_audio_layer

typedef struct bj_audio_layer_t bj_audio_layer

Represent an audio backend (ALSA, MME, etc).

Internal structure used to abstract platform-specific device control.

◆ bj_audio_play_note_data

typedef struct bj_audio_play_note_data_t bj_audio_play_note_data

Define parameters for generating simple waveforms.

Used with bj_play_audio_note to synthesize tones such as sine or square.

See also: bj_play_audio_note

◆ bj_audio_properties

typedef struct bj_audio_properties_t bj_audio_properties

Describe properties of an audio device.

This structure is passed to audio callbacks to inform them about the format and limits of the current playback device.

See also: bj_audio_callback_t

Enumeration Type Documentation

◆ bj_audio_format_t

enum bj_audio_format_t

Audio sample format descriptor.

Encodes sample width, sign, float/integer, and endianness flags. Use the helper macros to inspect properties.

See also: BJ_AUDIO_FORMAT_WIDTH; BJ_AUDIO_FORMAT_FLOAT; BJ_AUDIO_FORMAT_INT; BJ_AUDIO_FORMAT_BIG_ENDIAN; BJ_AUDIO_FORMAT_SIGNED

Enumerator
BJ_AUDIO_FORMAT_UNKNOWN	Unknown/unspecified format.
BJ_AUDIO_FORMAT_INT16	16-bit signed integer PCM.
BJ_AUDIO_FORMAT_F32	32-bit IEEE-754 float PCM.

Function Documentation

◆ bj_audio_playing()

bj_bool bj_audio_playing ( const bj_audio_device * p_device )

Query whether the device is currently playing audio.

Parameters

p_device Pointer to the audio device.

Returns: BJ_TRUE if playing, BJ_FALSE if paused or stopped.

See also: bj_play_audio_device; bj_pause_audio_device

◆ bj_close_audio_device()

void bj_close_audio_device ( bj_audio_device * p_device )

Close an audio device and release all associated resources.

Stops playback and joins the audio thread before cleanup.

Parameters

p_device Pointer to the audio device to close.

See also: bj_open_audio_device

◆ bj_open_audio_device()

bj_audio_device * bj_open_audio_device	(	const bj_audio_properties *	p_properties,
		bj_audio_callback_t	p_callback,
		void *	p_callback_user_data,
		bj_error **	p_error )

Open the default audio device for playback.

Initializes the audio backend and starts playback immediately using the provided callback.

Parameters

p_properties	Optional pointer to requested properties, or NULL. The opened device may differ from the request.
p_callback	User audio callback used to produce samples.
p_callback_user_data	Opaque pointer passed to the callback on each call.
p_error	Optional pointer to receive error information on failure.

Returns: A handle to the opened audio device, or NULL on failure.

See also: bj_audio_callback_t; bj_close_audio_device; bj_play_audio_device; bj_pause_audio_device

◆ bj_pause_audio_device()

void bj_pause_audio_device ( bj_audio_device * p_device )

Pause audio playback.

While paused, the audio thread continues running and outputs silence.

Parameters

p_device Pointer to the audio device.

See also: bj_play_audio_device; bj_stop_audio_device; bj_audio_playing

◆ bj_play_audio_device()

void bj_play_audio_device ( bj_audio_device * p_device )

Resume audio playback.

Playback resumes from where it was previously paused.

Parameters

p_device Pointer to the audio device.

See also: bj_pause_audio_device; bj_stop_audio_device; bj_audio_playing

◆ bj_play_audio_note()

void bj_play_audio_note	(	void *	buffer,
		unsigned	frames,
		const bj_audio_properties *	audio,
		void *	user_data,
		uint64_t	base_sample_index )

Generate a basic waveform tone using a built-in callback.

Can be used as a bj_audio_callback_t and uses bj_audio_play_note_data_t.

Parameters

buffer	Output buffer to write samples into.
frames	Number of frames to generate.
audio	Audio device properties.
user_data	Pointer to a bj_audio_play_note_data_t instance.
base_sample_index	Starting sample index (for phase computation).

See also: bj_audio_play_note_data_t; bj_audio_callback_t

◆ bj_reset_audio_device()

void bj_reset_audio_device ( bj_audio_device * p_device )

Reset the playback stream sample index to 0.

Does not stop or pause playback. Only resets timing.

Parameters

p_device Pointer to the audio device.

See also: bj_stop_audio_device; bj_audio_callback_t

◆ bj_stop_audio_device()

void bj_stop_audio_device ( bj_audio_device * p_device )

Stop playback and reset the sample stream.

Equivalent to calling pause followed by reset.

Parameters

p_device Pointer to the audio device.

See also: bj_pause_audio_device; bj_reset_audio_device

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ bj_audio_properties_t

◆ bj_audio_layer_t

◆ bj_audio_layer_create_info

Macro Definition Documentation

◆ BJ_AUDIO_FORMAT_BIG_ENDIAN

◆ BJ_AUDIO_FORMAT_FLOAT

◆ BJ_AUDIO_FORMAT_INT

◆ BJ_AUDIO_FORMAT_SIGNED

◆ BJ_AUDIO_FORMAT_WIDTH

Typedef Documentation

◆ bj_audio_callback_t

◆ bj_audio_device

◆ bj_audio_format

◆ bj_audio_layer

◆ bj_audio_play_note_data

◆ bj_audio_properties

Enumeration Type Documentation

◆ bj_audio_format_t

Function Documentation

◆ bj_audio_playing()

◆ bj_close_audio_device()

◆ bj_open_audio_device()

◆ bj_pause_audio_device()

◆ bj_play_audio_device()

◆ bj_play_audio_note()

◆ bj_reset_audio_device()

◆ bj_stop_audio_device()