Data Structures
struct	bj_audio_properties
struct	bj_audio_play_note_data

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 void(*	bj_audio_callback_fn) (void buffer, unsigned frames, const struct bj_audio_properties audio, void *user_data, uint64_t base_sample_index)

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

Functions
struct bj_audio_device *	bj_open_audio_device (const struct bj_audio_properties properties, bj_audio_callback_fn callback, void callback_user_data, struct bj_error **error)
void	bj_close_audio_device (struct bj_audio_device *device)
void	bj_play_audio_device (struct bj_audio_device *device)
void	bj_pause_audio_device (struct bj_audio_device *device)
void	bj_reset_audio_device (struct bj_audio_device *device)
void	bj_stop_audio_device (struct bj_audio_device *device)
bj_bool	bj_audio_playing (const struct bj_audio_device *device)
void	bj_play_audio_note (void buffer, unsigned frames, const struct 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 push-based API

Add support for audio WAVE format

Add support for audio MIDI format

Data Structure Documentation

◆ bj_audio_properties

struct 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_fn

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

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 (enum 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 (enum 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 (enum 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 (enum 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 (enum bj_audio_format).

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

Typedef Documentation

◆ bj_audio_callback_fn

typedef void(* bj_audio_callback_fn) (void *buffer, unsigned frames, const struct 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; struct bj_audio_properties

Enumeration Type Documentation

◆ bj_audio_format

enum 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

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 struct bj_audio_device * device )

Query whether the device is currently playing audio.

Parameters

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 ( struct bj_audio_device * device )

Close an audio device and release all associated resources.

Stops playback and joins the audio thread before cleanup.

Parameters

device Pointer to the audio device to close.

See also: bj_open_audio_device

◆ bj_open_audio_device()

struct bj_audio_device * bj_open_audio_device	(	const struct bj_audio_properties *	properties,
		bj_audio_callback_fn	callback,
		void *	callback_user_data,
		struct bj_error **	error )

Open the default audio device for playback.

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

Parameters

properties	Optional pointer to requested properties, or NULL. The opened device may differ from the request.
callback	User audio callback used to produce samples.
callback_user_data	Opaque pointer passed to the callback on each call.
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_fn; bj_close_audio_device; bj_play_audio_device; bj_pause_audio_device

◆ bj_pause_audio_device()

void bj_pause_audio_device ( struct bj_audio_device * device )

Pause audio playback.

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

Parameters

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 ( struct bj_audio_device * device )

Resume audio playback.

Playback resumes from where it was previously paused.

Parameters

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 struct 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_fn and uses struct bj_audio_play_note_data.

Parameters

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

See also: struct bj_audio_play_note_data; bj_audio_callback_fn

◆ bj_reset_audio_device()

void bj_reset_audio_device ( struct bj_audio_device * device )

Reset the playback stream sample index to 0.

Does not stop or pause playback. Only resets timing.

Parameters

device Pointer to the audio device.

See also: bj_stop_audio_device; bj_audio_callback_fn

◆ bj_stop_audio_device()

void bj_stop_audio_device ( struct bj_audio_device * device )

Stop playback and reset the sample stream.

Equivalent to calling pause followed by reset.

Parameters

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

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_fn

Enumeration Type Documentation

◆ bj_audio_format

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()