Audio callbacks

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:

;
; @ANO_SCRIPT_NAME		audio_play
; @ANO_SCRIPT_VERSION		0.0.1
; @ANO_SCRIPT_DESCRIPTION	Simple audio noise player example
;
; @ANO_FLAGS_USE_PROTOS		[ ]
; @ANO_FLAGS_VAR_NAME_SUBS	[ ]
; @ANO_FLAGS_VAR_WARN_UNUSED	[ ]
;
; Copyright (c) 2016-2026, Jani Salonen <salojan@goto10.co>
; All rights reserved.
;
; Small demonstration how to create audible noise and play that along with
; some audio callback functions.
;

main [exit: 0] {
	; Initialize audio system, this example does nothing if
	; --disable-audio was passed to configure script.
	;
	audio_enabled {
		mov buf_printed (0)
		mov buf_played (0)

		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:	"cb_buf_start", \
			cb_buffer_done:		"cb_buf_done")

		; Create one second white noise...
		;
		_ahnd = audio_create_noise (\
			seconds: 1.0, pink: 0.0, brown: 0.0)

		; ...start playing it...
		;
		audio_play (\
			audio_handle: _ahnd, volume: 0.1, pan: 0.0)

		; ...wait until it finishes...
		;
		audio_wait (\
			audio_handle: _ahnd)

		; ...and close audio track.
		;
		audio_close (\
			audio_handle: _ahnd)
	}
}

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

	; This callback is called when track starts playing.
	;
	print "Track " . _hnd . " playing " . _data_size . " samples using" \
		" volume of " . _vol . " and panning of " . _pan . ".\n\n"
}

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

	; This callback is called when track finishes playing.
	;
	print "Track " . _hnd . " finished playing " . _data_size . \
		" samples, " . buf_played . " buffers in total.\n\n"
}

_AUDIOCB_START_ callback cb_buf_start (_buf_data, _buf_channels, _buf_speed, \
	_buf_size, _buf_samplesize, _buf_be, _buf_signed) {

	; This callback is called when internal data buffer is about to be
	; processed.
	;

	; Print buffer info only once.
	;
	mov rc (buf_printed)
	end_unless_zero

	print "Buffer start, data address: " . _buf_data . "\n"
	print "Buffer size: " . _buf_size . " bytes\n"
	print "Channels:    " . _buf_channels . "\n"
	print "Sample rate: " . _buf_speed . " Hz\n"
	print "Sample size: " . _buf_samplesize . " bytes\n"
	print "Big endian:  " . _buf_be . "\n"
	print "Signed:      " . _buf_signed . "\n\n"
}

_AUDIOCB_DONE_ callback cb_buf_done (_buf_data, _buf_channels, _buf_speed, \
	_buf_size, _buf_samplesize, _buf_be, _buf_signed, _usecs) {

	; This callback is called when internal data buffer was processed.
	;
	inc buf_played

	; Print buffer info only once.
	;
	mov rc (buf_printed)
	end_unless_zero
	mov buf_printed (1)

	print "One buffer done, processing time in μsecs: " . _usecs . "\n\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
	;
}