Audio callbacks

⭐ New in 0.2.9.

Audio callbacks runs concurrently with calling thread until noted otherwise. See explanation of callback annotations here. Example use of play and finish callbacks along with audio system initialization:

main [exit: 0] {
	; Initialize audio system
	;
	audio_init(\
		cb_track_play:		"cb_play", \
		cb_track_mode:		NULL, \
		cb_track_finish:	"cb_finish", \
		cb_track_restart:	NULL, \
		cb_track_cancel:	NULL, \
		cb_track_pan:		NULL, \
		cb_track_vol:		NULL, \
		cb_master_vol:		NULL, \
		cb_buffer_start:	NULL, \
		cb_buffer_done:		NULL)

	; Generate 2 seconds of white noise and play it
	;
	_hnd = audio_create_noise_white(\
		seconds:		2.0)

	if_invalid error

	_hnd.play(\
		volume:			1.0, \
		pan:			0.0)

	; Wait until track completes and free it
	;
	_hnd.wait()
	_hnd.eject()

	exit
error:
	print "Failed to initialize audio subsystem.\n"
}

_AUDIOCB_PLAY_ callback cb_play (_hnd, _vol, _pan, _data_size, \
	_ch1_data, _ch1_vol, _ch2_data, _ch2_vol) {

	print "Track playing.\n"
}

_AUDIOCB_FINISH_ callback cb_finish (_hnd, _data_size, \
	_ch1_data, _ch2_data) {

	print "Track finished.\n"
}

Play track callback

Play track callback runs when track starts playing.

_AUDIOCB_PLAY_ callback cb_play (track_handle, track_vol, track_pan, data_size, \
	ch1_data, ch1_vol, ch2_data, ch2_vol, \
	[ch3_data, ch3_vol, ...]) {
	;
	; This callback runs when track starts playing.
	; Track is identified by track_handle variable.
	;
	; track_vol is from 0.0 to 1.0, from silence to maximum volume,
	; respectively.
	;
	; track_pan is from -1.0 to 1.0, from far left to far right,
	; respectively. Zero is the center.
	;
	; data_size is in samples, not bytes.
	;
	; Amount of ch*_data and ch*_vol pairs must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default. ch*_data buffer
	; type is float, each sample ranging from -1.0 to 1.0.
	;
	; ch*_vol is from 0.0 to 1.0, from silence to maximum volume,
	; respectively.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; track_vol ...... float
	; track_pan ...... float
	; data_size ...... usize
	; ch*_data ....... pointer
	; ch*_vol ........ float
	;
}

Track mode callback

Track mode callback runs when track mode changes, for example, when mute is set, or playing mode is changed to loop.

_AUDIOCB_MODE_ callback cb_mode (track_handle, sample_state, sample_mode) {
	;
	; This callback runs when track state or mode changes.
	; Track is identified by track_handle variable.
	;
	; sample_state is one of:
	;  SAMPLE_STATE_NONE - track is allocated but stopped
	;  SAMPLE_STATE_BUSY - track is about to be played
	;  SAMPLE_STATE_PLAY - track is playing normally
	;  SAMPLE_STATE_HOLD - track is paused
	;  SAMPLE_STATE_MUTE - track is playing but silently
	;
	; sample_mode is one of:
	;  SAMPLE_MODE_NONE - track plays only once
	;  SAMPLE_MODE_LOOP - track plays again when it completes
	;
	; Parameter types:
	;
	; track_handle ... handle
	; sample_state ... uint
	; sample_mode .... uint
	;
}

Track finished callback

Track finished callback runs when track is finished.

_AUDIOCB_FINISH_ callback cb_finish (track_handle, data_size, \
	ch1_data, ch2_data, \
	[ch3_data, ...]) {
	;
	; This callback runs when track completes playing.
	; Track is identified by track_handle variable.
	;
	; data_size is in samples, not bytes.
	;
	; Amount of ch*_data variables must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default. ch*_data buffer
	; type is float, each sample ranging from -1.0 to 1.0.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; data_size ...... usize
	; ch*_data ....... pointer
	;
}

Track restart callback

Track restart callback runs when track is restarted.

_AUDIOCB_RESTART_ callback cb_restart (track_handle, data_size, \
	ch1_data, ch2_data, \
	[ch3_data, ...]) {
	;
	; This callback runs when track restarts playing in loop mode.
	; Track is identified by track_handle variable.
	;
	; data_size is in samples, not bytes.
	;
	; Amount of ch*_data variables must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default. ch*_data buffer
	; type is float, each sample ranging from -1.0 to 1.0.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; data_size ...... usize
	; ch*_data ....... pointer
	;
}

Track cancel callback

Track cancel callback runs when track is stopped before it is finished.

_AUDIOCB_CANCEL_ callback cb_cancel (track_handle) {
	;
	; This callback runs when track cancels playing.
	; Track is identified by track_handle variable.
	;
	; Parameter types:
	;
	; track_handle ... handle
	;
}

Track panning callback

Track panning callback runs when track panning changes.

_AUDIOCB_PAN_ callback cb_pan (track_handle, track_pan) {
	;
	; This callback runs when track panning changes.
	; Track is identified by track_handle variable.
	;
	; track_pan is from -1.0 to 1.0, from far left to far right,
	; respectively. Zero is the center.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; track_pan ...... float
	;
}

Track volume callback

Track volume callback runs when track volume changes.

_AUDIOCB_VOL_ callback cb_vol (track_handle, ch1_vol, ch2_vol, \
	[ch3_vol, ...]) {
	;
	; This callback runs when track volume changes.
	; Track is identified by track_handle variable.
	;
	; ch*_vol is from 0.0 to 1.0, from silence to maximum volume,
	; respectively.
	;
	; Amount of ch*_vol variables must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; ch*_vol ........ float
	;
}

Master volume callback

Master volume callback runs when master volume changes. This callback blocks calling thread until it is complete.

_AUDIOCB_MASTER_ callback cb_master_vol (ch1_vol, ch2_vol, \
	[ch3_vol, ...]) {
	;
	; This callback runs when master volume changes.
	;
	; ch*_vol is from 0.0 to 1.0, from silence to maximum volume,
	; respectively.
	;
	; Amount of ch*_vol variables must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default.
	;
	; This callback does not run concurrently, but blocks mixer thread
	; until callback function is complete.
	;
	; Parameter types:
	;
	; ch*_vol ........ float
	;
}

Buffer start callback

Buffer start callback runs when mixing buffer is about to start playing. This callback blocks calling thread until it is complete.

_AUDIOCB_START_ callback cb_buffer_start (buf_data, buf_channels, buf_speed, buf_size, buf_samplesize, \
	buf_be, buf_signed) {
	;
	; This callback runs just before mixing buffer playback starts.
	; Application command line parameters may affect these values.
	;
	; buf_data is pointer to yet uninitialized buffer data.
	; Buffer type is float, each sample ranging from -1.0 to 1.0.
	;
	; buf_channels is amount of channels in buffer.
	;
	; buf_speed is buffer samplerate in Hz.
	;
	; buf_size is total buffer size in bytes.
	;
	; buf_samplesize is buffer sample size in bytes, aka physical width.
	;
	; buf_be is zero if buffer is little endian, nonzero otherwise.
	;
	; buf_signed is zero if buffer not signed, nonzero otherwise.
	;
	; This callback does not run concurrently, but blocks mixer thread
	; until callback function is complete.
	;
	; Parameter types:
	;
	; buf_data ....... pointer
	; buf_channels ... int
	; buf_speed ...... int
	; buf_size ....... usize
	; buf_samplesize . usize
	; buf_be ......... uint
	; buf_signed ..... uint
	;
}

Buffer done callback

Buffer done callback runs when mixing buffer is done but not necessarily played yet. This callback blocks calling thread until it is complete.

_AUDIOCB_DONE_ callback cb_buffer_done (buf_data, buf_channels, buf_speed, buf_size, buf_samplesize, \
	buf_be, buf_signed, usecs) {
	;
	; This callback runs right after mixing buffer playback completes.
	; Application command line parameters may affect these values.
	;
	; buf_data is pointer to now initialized buffer data.
	; Buffer type is float, each sample ranging from -1.0 to 1.0.
	;
	; buf_channels is amount of channels in buffer.
	;
	; buf_speed is buffer samplerate in Hz.
	;
	; buf_size is total buffer size in bytes.
	;
	; buf_samplesize is buffer sample size in bytes, aka physical width.
	;
	; buf_be is zero if buffer is little endian, nonzero otherwise.
	;
	; buf_signed is zero if buffer not signed, nonzero otherwise.
	;
	; usecs is time in microseconds consumed by mixer for last buffer.
	; Time includes possible buffer start callback execution as well.
	;
	; This callback does not run concurrently, but blocks mixer thread
	; until callback function is complete.
	;
	; Parameter types:
	;
	; buf_data ....... pointer
	; buf_channels ... int
	; buf_speed ...... int
	; buf_size ....... usize
	; buf_samplesize . usize
	; buf_be ......... uint
	; buf_signed ..... uint
	; usecs .......... ulong
	;
}