Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Audio

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)
#define BJ_AUDIO_PLAY_SINE   BJ_AUDIO_WAVEFORM_SINE
#define BJ_AUDIO_PLAY_SQUARE   BJ_AUDIO_WAVEFORM_SQUARE
#define BJ_AUDIO_PLAY_TRIANGLE   BJ_AUDIO_WAVEFORM_TRIANGLE
#define BJ_AUDIO_PLAY_SAWTOOTH   BJ_AUDIO_WAVEFORM_SAWTOOTH

Typedefs

typedef enum bj_audio_format bj_audio_format
typedef void(* bj_audio_callback_fn) (void *buffer, unsigned frames, const struct bj_audio_properties *audio, void *user_data, uint64_t base_sample_index)
typedef enum bj_audio_waveform bj_audio_waveform

Enumerations

enum  bj_audio_format { BJ_AUDIO_FORMAT_UNKNOWN = 0x0000 , BJ_AUDIO_FORMAT_INT16 = 0x8010 , BJ_AUDIO_FORMAT_F32 = 0x8120 }
enum  bj_audio_waveform { BJ_AUDIO_WAVEFORM_SINE , BJ_AUDIO_WAVEFORM_SQUARE , BJ_AUDIO_WAVEFORM_TRIANGLE , BJ_AUDIO_WAVEFORM_SAWTOOTH }

Functions

struct bj_audio_device * bj_create_audio_device (const struct bj_audio_properties *properties, bj_audio_callback_fn callback, void *callback_user_data, struct bj_error **error)
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_destroy_audio_device (struct bj_audio_device *device)
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_device_is_playing (const 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

Generate and play sound samples from your application.

This subsystem lets your program produce sound. The model is simple: you tell Banjo "open a connection to the speakers, and call this function of mine whenever you need more sound to play." Banjo then runs your function in the background, asking for the next batch of numbers (samples) each time the speaker is about to drain.

Sound on a computer is just a stream of numbers (one number per time slice) that describes the position of the speaker cone at that instant. Play back tens of thousands of those per second (44 100 / s is the CD-quality standard) and the ear hears continuous sound. This format is called PCM (Pulse-Code Modulation) and it's the lingua franca every audio system uses. Banjo gives you raw PCM in and out: no music files, no streaming containers, just numbers.

You don't push samples: Banjo pulls them

The common beginner mistake is to imagine "I write some samples into a buffer, and the speakers play them." That works for recorded clips, but for live or generated audio it has too much latency: by the time you finished filling the buffer the sound is already delayed by however long the buffer holds.

Banjo follows the standard real-time pattern: you give the subsystem a function of yours (your audio callback, bj_audio_callback_fn) and the audio subsystem calls it from a separate background thread whenever the speaker's playback buffer needs refilling. Each call gives you a buffer to write the next handful of samples into.

Two practical consequences:

  • Your callback runs on a background thread that has tight timing. If the callback is slow or blocks, the speaker drops to silence and the user hears a click. So inside the callback: no memory allocation, no I/O, no locks, no printf, no slow work, just compute samples and return.
  • If you want to control the sound from elsewhere (e.g. the main thread setting a "play this note now" flag), the two threads are sharing memory. For single values like an int or a double that fit in one CPU word, a plain write usually works; for anything more elaborate, use atomic primitives.

You can skip writing a callback for simple tones

bj_play_audio_note is a ready-made callback that generates continuous sine, square, triangle, or sawtooth waveforms. Hand it to bj_create_audio_device along with a bj_audio_play_note_data describing the frequency and shape, then change data.frequency from your main thread whenever you want the pitch to move. The audio thread picks up the new value on the next sample. No custom callback needed.

The audio_pcm.c tutorial walks through that approach; pong.c shows how to write your own callback for short triggered beeps instead of a continuous tone.

Platforms and runtime selection

Note
The "Platforms and runtime selection" block in window.h is the sibling of this one. Keep them in sync (priority order, fake-fallback behaviour, log line).

Audio works on Linux, Windows, macOS, and WebAssembly. By default you don't pick the platform: bj_begin (called with BJ_AUDIO_SYSTEM) probes the compiled-in backends at startup, in the order bj_audio_backends lists them (Emscripten, CoreAudio, MME, ALSA, then fake), and uses the first that initialises. To override that, call bj_begin_system before bj_begin and pass a name from bj_audio_backends (or NULL to keep auto-selecting); the chosen backend is then pinned for the subsystem's lifetime. A no-op fallback (the fake backend) means bj_create_audio_device returns a valid handle even on a headless host with no sound card; that device plays like any other, calling your callback at the pace of its sample rate, and what the callback writes is discarded. On success, startup logs audio selected: <name>; on total failure, which includes a build with no audio backend at all, bj_begin returns BJ_FALSE with BJ_ERROR_INITIALIZE.

Lifecycle in one paragraph

Open a device with bj_create_audio_device (passing your callback). Control playback with bj_play_audio_device, bj_pause_audio_device, bj_stop_audio_device, bj_reset_audio_device, and bj_audio_device_is_playing. Close with bj_destroy_audio_device as it joins the audio thread before returning, so by the time the call completes your callback is guaranteed to have stopped (you can free any state it was reading).

See also
Windows for the analogous video subsystem, Building Banjo for which Audio platforms are enabled in a given build and what they need to run.

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
Examples
audio_pcm.c.

Definition at line 193 of file audio.h.

Data Fields
int16_t amplitude Maximum amplitude of the output samples.
unsigned int channels Number of interleaved channels (1 = mono, 2 = stereo, ...). The opened device may negotiate a different value.
enum bj_audio_format format Sampling format.
unsigned int sample_rate Number of samples per second (Hz).

◆ bj_audio_play_note_data

struct 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
Examples
audio_pcm.c.

Definition at line 400 of file audio.h.

Data Fields
double frequency Frequency of the waveform (Hz).

It may change between calls, and the waveform stays continuous.

enum bj_audio_waveform function Type of waveform to generate.
double phase Phase of the next sample, in radians, which bj_play_audio_note advances and wraps to [0, 2π).

Set it to 0 to restart the note.

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
xAudio format code (enum bj_audio_format).
Returns
Non-zero if big-endian, zero otherwise.

Definition at line 175 of file audio.h.

◆ BJ_AUDIO_FORMAT_FLOAT

#define BJ_AUDIO_FORMAT_FLOAT ( x)
Value:
((x) & (1u<<8))

Test whether the audio format is floating point.

Parameters
xAudio format code (enum bj_audio_format).
Returns
Non-zero if float, zero otherwise.

Definition at line 159 of file audio.h.

◆ BJ_AUDIO_FORMAT_INT

#define BJ_AUDIO_FORMAT_INT ( x)
Value:
(!((x) & (1u<<8)))

Test whether the audio format is integer PCM.

Parameters
xAudio format code (enum bj_audio_format).
Returns
Non-zero if integer PCM, zero otherwise.

Definition at line 167 of file audio.h.

◆ BJ_AUDIO_FORMAT_SIGNED

#define BJ_AUDIO_FORMAT_SIGNED ( x)
Value:
((x) & (1u<<15))

Test whether integer samples are signed.

Parameters
xAudio format code (enum bj_audio_format).
Returns
Non-zero if signed, zero otherwise.

Definition at line 183 of file audio.h.

◆ 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
xAudio format code (enum bj_audio_format).
Returns
Unsigned integer width in bits (e.g., 16 or 32).

Definition at line 151 of file audio.h.

◆ BJ_AUDIO_PLAY_SAWTOOTH

#define BJ_AUDIO_PLAY_SAWTOOTH   BJ_AUDIO_WAVEFORM_SAWTOOTH
Deprecated
Renamed to BJ_AUDIO_WAVEFORM_SAWTOOTH. Removed in 2.0.

Definition at line 391 of file audio.h.

◆ BJ_AUDIO_PLAY_SINE

#define BJ_AUDIO_PLAY_SINE   BJ_AUDIO_WAVEFORM_SINE
Deprecated
Renamed to BJ_AUDIO_WAVEFORM_SINE. Removed in 2.0.

Definition at line 385 of file audio.h.

◆ BJ_AUDIO_PLAY_SQUARE

#define BJ_AUDIO_PLAY_SQUARE   BJ_AUDIO_WAVEFORM_SQUARE
Deprecated
Renamed to BJ_AUDIO_WAVEFORM_SQUARE. Removed in 2.0.

Definition at line 387 of file audio.h.

◆ BJ_AUDIO_PLAY_TRIANGLE

#define BJ_AUDIO_PLAY_TRIANGLE   BJ_AUDIO_WAVEFORM_TRIANGLE
Deprecated
Renamed to BJ_AUDIO_WAVEFORM_TRIANGLE. Removed in 2.0.

Definition at line 389 of file audio.h.

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, only while the device plays.

Parameters
bufferOutput buffer of frames × channels interleaved samples, in the format of audio (int16_t for BJ_AUDIO_FORMAT_INT16, float for BJ_AUDIO_FORMAT_F32).
framesNumber of audio frames to generate.
audioPointer to audio device properties (read-only).
user_dataUser-defined pointer passed at device creation.
base_sample_indexIndex of the first frame in the current buffer, counted from 0 while the device plays: it does not advance while paused, and bj_reset_audio_device sets it back to 0.
See also
bj_create_audio_device
struct bj_audio_properties

Definition at line 221 of file audio.h.

◆ bj_audio_format

Definition at line 142 of file audio.h.

◆ bj_audio_waveform

Definition at line 381 of file audio.h.

Enumeration Type Documentation

◆ 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.

Definition at line 136 of file audio.h.

◆ bj_audio_waveform

Waveform types for audio note generation.

See also
bj_play_audio_note
bj_audio_play_note_data
Enumerator
BJ_AUDIO_WAVEFORM_SINE 

Generate a sine wave.

BJ_AUDIO_WAVEFORM_SQUARE 

Generate a square wave.

BJ_AUDIO_WAVEFORM_TRIANGLE 

Generate a triangle wave.

BJ_AUDIO_WAVEFORM_SAWTOOTH 

Generate a sawtooth wave.

Definition at line 374 of file audio.h.

Function Documentation

◆ bj_audio_device_is_playing()

bj_bool bj_audio_device_is_playing ( const struct bj_audio_device * device)

Query whether the device is currently playing audio.

Parameters
devicePointer to the audio device, or NULL.
Returns
BJ_TRUE if playing, BJ_FALSE if paused or stopped, or if device is NULL.
See also
bj_play_audio_device
bj_pause_audio_device

◆ bj_audio_playing()

bj_bool bj_audio_playing ( const struct bj_audio_device * device)
Deprecated
Renamed to bj_audio_device_is_playing. Removed in 2.0.

◆ bj_close_audio_device()

void bj_close_audio_device ( struct bj_audio_device * device)
Deprecated
Renamed to bj_destroy_audio_device. Removed in 2.0.

◆ bj_create_audio_device()

struct bj_audio_device * bj_create_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.

Opens the device paused: call bj_play_audio_device to start the provided callback. Fails with BJ_ERROR_AUDIO while audio is not running.

Parameters
propertiesOptional pointer to requested properties, or NULL for 16-bit integer samples, 1 channel and 44100 Hz. The opened device may differ from the request.
callbackUser audio callback used to produce samples, or NULL to play silence.
callback_user_dataOpaque pointer passed to the callback on each call, NULL included.
errorOptional pointer to receive error information on failure. May be NULL.
Returns
A handle to the opened audio device, or NULL on failure.
See also
bj_audio_callback_fn
bj_destroy_audio_device
bj_play_audio_device
bj_pause_audio_device
Examples
audio_pcm.c.

Referenced by setup().

◆ bj_destroy_audio_device()

void bj_destroy_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.

Ending audio, through bj_end or the last bj_end_system, closes every device still open the same way; destroying one of those afterwards does nothing.

Parameters
devicePointer to the audio device to close, or NULL, which does nothing.
See also
bj_create_audio_device
Examples
audio_pcm.c.

Referenced by teardown().

◆ 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 )
Deprecated
Renamed to bj_create_audio_device. Removed in 2.0.

◆ 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
devicePointer to the audio device, or NULL, which does nothing.
See also
bj_play_audio_device
bj_stop_audio_device
bj_audio_device_is_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
devicePointer to the audio device, or NULL, which does nothing.
See also
bj_pause_audio_device
bj_stop_audio_device
bj_audio_device_is_playing
Examples
audio_pcm.c.

Referenced by setup().

◆ 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.

Writes the same sample to every channel of each frame, then advances the phase by 2π × frequency / sample rate. With BJ_AUDIO_FORMAT_F32 the sample is the waveform itself, from -1 to 1; with BJ_AUDIO_FORMAT_INT16 it is the waveform times audio->amplitude, truncated toward zero. Any other format gets silence, as many bytes per sample as its width: zero, or mid-scale for an unsigned integer format.

Without note data, or at a sample rate of 0, the whole buffer gets that silence and the phase stays where it was.

With t the phase divided by 2π, the sine is sin(phase); the square is 0.2 for 0 < t < 1/2 and -0.2 otherwise; the triangle rises from -1 at t = 0 to 1 at t = 1/2 and falls back; the sawtooth rises from 0 at t = 0 toward 1, jumps to -1 at t = 1/2 and rises back toward 0. Any other waveform is silence.

Parameters
bufferOutput buffer to write samples into, or NULL, which writes nothing.
framesNumber of frames to generate.
audioAudio device properties, or NULL, which writes nothing.
user_dataPointer to a struct bj_audio_play_note_data instance, or NULL, which plays silence.
base_sample_indexUnused: the waveform follows the phase of user_data.
See also
struct bj_audio_play_note_data
bj_audio_callback_fn
Examples
audio_pcm.c.

Referenced by setup().

◆ 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
devicePointer to the audio device, or NULL, which does nothing.
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
devicePointer to the audio device, or NULL, which does nothing.
See also
bj_pause_audio_device
bj_reset_audio_device