Playback Control

Functions
u8	audioPlaySample (u8 sampleId)
	Play a sample with default settings.
u8	audioPlaySampleEx (u8 sampleId, u8 volume, u8 pan, u16 pitch)
	Play a sample with custom settings.
u8	audioPlaySampleOn (u8 voice, u8 sampleId, u8 volume, u8 pan, u16 pitch)
	Play a sample on a voice YOU choose.
u8	audioStopAll (void)
	Stop all audio playback.
u8	audioStopVoice (u8 voice)
	Stop a specific voice.

Detailed Description

Function Documentation

audioPlaySample()

u8 audioPlaySample

(

u8

sampleId

)

Play a sample with default settings.

Parameters

sampleId

Sample slot (0-63)

Returns

Voice number (0-7) or 0xFF on failure

Plays at full volume, center pan, default pitch.

audioPlaySampleEx()

u8 audioPlaySampleEx	(	u8	sampleId,
		u8	volume,
		u8	pan,
		u16	pitch )

Play a sample with custom settings.

Parameters

sampleId	Sample slot (0-63)
volume	Volume level (0-127)
pan	Pan position (0=left, 8=center, 15=right)
pitch	Pitch value ($1000 = normal)

Returns

Voice number (0-7) or 0xFF on failure

audioPlaySampleEx(0, 64, AUDIO_PAN_RIGHT, 0x1800);

audioPlaySampleOn()

u8 audioPlaySampleOn	(	u8	voice,
		u8	sampleId,
		u8	volume,
		u8	pan,
		u16	pitch )

Play a sample on a voice YOU choose.

audioPlaySample() and audioPlaySampleEx() pick the voice round-robin and only tell you afterwards. That is too late for anything that must be set BEFORE key-on — audioSetADSR() / audioSetGain() shape the attack — and it lets a long sound be stolen by the eighth effect after it. Choosing the voice fixes both: reserve, say, voice 7 for the engine hum, aim its envelope once, and keep effects on the automatic voices. (Added 2026-09-21; AUDIO_VOICE_AUTO had been defined since v2 with nothing to pass it to.)

An explicit voice does not advance the round-robin counter.

Parameters

voice	Voice 0-7, or AUDIO_VOICE_AUTO for the round-robin choice
sampleId	Sample slot (0-63)
volume	Volume level (0-127)
pan	Pan position (0=left, 8=center, 15=right)
pitch	Pitch value ($1000 = normal)

Returns

The voice used (0-7), or AUDIO_VOICE_NONE: voice out of range, sample not loaded, driver not ready

audioSetADSR(7, 4, 7, 7, 0);                 // slow attack, on voice 7
audioPlaySampleOn(7, SFX_ENGINE, 90, AUDIO_PAN_CENTER, 0x1000);

audioStopAll()

u8 audioStopAll

(

void

)

Stop all audio playback.

audioStopVoice()

u8 audioStopVoice

(

u8

voice

)

Stop a specific voice.

Parameters

voice

Voice number (0-7)