A simple sound playback library for the DS. More...

#include <nds/ndstypes.h>

Enumerations
enum	DutyCycle { DutyCycle_0 = 7 , DutyCycle_12 = 0 , DutyCycle_25 = 1 , DutyCycle_37 = 2 , DutyCycle_50 = 3 , DutyCycle_62 = 4 , DutyCycle_75 = 5 , DutyCycle_87 = 6 }
	PSG Duty cycles used by the PSG hardware. More...

enum	MicFormat { MicFormat_8Bit = 1 , MicFormat_12Bit = 0 }
	Microphone recording formats DS. More...

enum	SoundCaptureFormat { SoundCaptureFormat_16Bit = 0 , SoundCaptureFormat_8Bit = 1 }
	Sound formats used by the audio capture unit. More...

enum	SoundFormat { SoundFormat_16Bit = 1 , SoundFormat_8Bit = 0 , SoundFormat_PSG = 3 , SoundFormat_ADPCM = 2 }
	Sound formats used by the DS. More...

Functions
int	soundCaptureStart (void *buffer, u16 bufferLen, int sndcapChannel, bool addCapToChannel, bool sourceIsMixer, bool repeat, SoundCaptureFormat format)
	This starts a sound capture channel.

void	soundCaptureStop (int sndcapChannel)
	This stops a sound capture channel.

void	soundDisable (void)
	Disables Sound on the DS.

void	soundEnable (void)
	Enables Sound on the DS.

void	soundExtSetFrequency (unsigned int freq_khz)
	Set extended sound hardware frequency.

void	soundExtSetRatio (unsigned int ratio)
	Set the DSP/ARM volume ratio of the speakers output.

void	soundKill (int soundId)
	Stops the sound specified by soundId and frees any resources allocated.

void	soundMicOff (void)
	Stops the microphone from recording.

void	soundMicPowerOff (void)
	Powers off the microphone after powering it on with soundMicPowerOn().

void	soundMicPowerOn (void)
	Powers on the microphone so that it can be used by the DSP.

int	soundMicRecord (void *buffer, u32 bufferLength, MicFormat format, int freq, MicCallback callback)
	Starts a microphone recording to a double buffer specified by buffer.

void	soundPause (int soundId)
	Pause the sound specified by soundId.

static int	soundPlayNoise (u16 freq, u8 volume, u8 pan)
	Plays white noise with the specified parameters.

int	soundPlayNoiseChannel (int channel, u16 freq, u8 volume, u8 pan)
	Plays white noise with the specified parameters.

static int	soundPlayPSG (DutyCycle cycle, u16 freq, u8 volume, u8 pan)
	Pause a tone with the specified properties.

int	soundPlayPSGChannel (int channel, DutyCycle cycle, u16 freq, u8 volume, u8 pan)
	Pause a tone with the specified properties.

static int	soundPlaySample (const void *data, SoundFormat format, u32 dataSize, u16 freq, u8 volume, u8 pan, bool loop, u16 loopPoint)
	Plays a sound in the specified format at the specified frequency.

int	soundPlaySampleChannel (int channel, const void *data, SoundFormat format, u32 dataSize, u16 freq, u8 volume, u8 pan, bool loop, u16 loopPoint)
	Plays a sound in the specified format at the specified frequency.

void	soundResume (int soundId)
	Resumes a paused sound.

void	soundSetFreq (int soundId, u16 freq)
	Sets the sound frequency.

void	soundSetPan (int soundId, u8 pan)
	Sets the sound panning.

void	soundSetVolume (int soundId, u8 volume)
	Sets the sound volume.

void	soundSetWaveDuty (int soundId, DutyCycle cycle)
	Sets the Wave Duty of a PSG sound.

Detailed Description

A simple sound playback library for the DS.

Provides functionality for starting and stopping sound effects from the ARM9 side as well as access to PSG and noise hardware. Maxmod should be used in most music and sound effect situations.

Enumeration Type Documentation

◆ DutyCycle

enum DutyCycle

PSG Duty cycles used by the PSG hardware.

Enumerator
DutyCycle_0	0.0% duty cycle
DutyCycle_12	12.5% duty cycle
DutyCycle_25	25.0% duty cycle
DutyCycle_37	37.5% duty cycle
DutyCycle_50	50.0% duty cycle
DutyCycle_62	62.5% duty cycle
DutyCycle_75	75.0% duty cycle
DutyCycle_87	87.5% duty cycle

◆ MicFormat

enum MicFormat

Microphone recording formats DS.

Enumerator
MicFormat_8Bit	8-bit PCM
MicFormat_12Bit	12-bit PCM

◆ SoundCaptureFormat

enum SoundCaptureFormat

Sound formats used by the audio capture unit.

Enumerator
SoundCaptureFormat_16Bit	16-bit PCM
SoundCaptureFormat_8Bit	8-bit PCM

◆ SoundFormat

enum SoundFormat

Sound formats used by the DS.

Enumerator
SoundFormat_16Bit	16-bit PCM
SoundFormat_8Bit	8-bit PCM
SoundFormat_PSG	PSG (Programmable Sound Generator)
SoundFormat_ADPCM	IMA ADPCM compressed audio.

Function Documentation

◆ soundCaptureStart()

int soundCaptureStart	(	void *	buffer,
		u16	bufferLen,
		int	sndcapChannel,
		bool	addCapToChannel,
		bool	sourceIsMixer,
		bool	repeat,
		SoundCaptureFormat	format
	)

This starts a sound capture channel.

Audio capture channel 0 requires the frequency of sound channel 1 to be set with soundSetFreq(), for example. For audio capture channel 1, you need to do the same to sound channel 3. The sample rate of the capture circuit matches the one of its corresponding sound channel because the channels are the ones that can output the captured audio. Even if the channel is disabled, as long as the frequency is set, audio capture will work.

Parameters

buffer	Buffer to store the captured audio.
bufferLen	Size of the buffer in words. A value of 0 will be treated as 1.
sndcapChannel	The audio capture channel to use.
addCapToChannel	For audio capture channel 0: If false, nothing special is done with the output of sound channel 1. If true, the output of sound channel 1 is added to sound channel 0. For audio capture channel 1: If false, nothing special is done with the output of sound channel 3. If true, the output of sound channel 3 is added to sound channel 2.
sourceIsMixer	For audio capture channel 0: If true, the capture source is the output of the left mixer. If false, the capture source is sound channel 0. For audio capture channel 1: If true, the capture source is the output of the right mixer. If false, the capture source is sound channel 2.
repeat	If true, the capture will continue even after the buffer is full (it will go back to the start).
format	The audio format that will be used to store data in the provided buffer.

Returns: It returns the capture channel index on success, -1 on error.

◆ soundCaptureStop()

void soundCaptureStop ( int sndcapChannel )

This stops a sound capture channel.

Parameters

sndcapChannel The channel to stop.

◆ soundEnable()

void soundEnable ( void )

Enables Sound on the DS.

It should be called prior to attempting sound playback.

◆ soundExtSetFrequency()

void soundExtSetFrequency ( unsigned int freq_khz )

Set extended sound hardware frequency.

Parameters

freq_khz Frequency in KHz. The default is 32, but 47 is allowed too.

◆ soundExtSetRatio()

void soundExtSetRatio ( unsigned int ratio )

Set the DSP/ARM volume ratio of the speakers output.

Parameters

ratio Value from 0 to 8 where 0 is 100% DSP, 8 is 100% ARM, 4 is 50% DSP and 50% ARM.

◆ soundKill()

void soundKill ( int soundId )

Stops the sound specified by soundId and frees any resources allocated.

Parameters

soundId The sound ID returned by play sound.

◆ soundMicPowerOn()

void soundMicPowerOn ( void )

Powers on the microphone so that it can be used by the DSP.

It won't record anything, it will simply remain powered on. You can power it off with soundMicPowerOff().

This isn't required for soundMicRecord(), this is only required for the DSP. Don't use it for anything else

◆ soundMicRecord()

int soundMicRecord	(	void *	buffer,
		u32	bufferLength,
		MicFormat	format,
		int	freq,
		MicCallback	callback
	)

Starts a microphone recording to a double buffer specified by buffer.

Note: The microphone uses timer 1 in the ARM7.

Parameters

buffer	A pointer to the start of the double buffer.
bufferLength	The length of the buffer in bytes (both halfs of the double buffer).
format	Microphone can record in 8 or 12 bit format. 12 bit is shifted up to 16 bit PCM.
freq	The sample frequency.
callback	Called every time the buffer is full or half full.

Returns: Returns non zero for success.

◆ soundPause()

void soundPause ( int soundId )

Pause the sound specified by soundId.

Parameters

soundId The sound ID returned by play sound.

◆ soundPlayNoise()

static int soundPlayNoise	(	u16	freq,
		u8	volume,
		u8	pan
	)

inlinestatic

Plays white noise with the specified parameters.

libnds will select a free channel to play the sound.

Parameters

freq	The frequency in Hz of the sample.
volume	The channel volume. 0 to 127 (min to max).
pan	The channel pan 0 to 127 (left to right with 64 being centered).

Returns: An integer id coresponding to the channel of playback. This value can be used to pause, resume, or kill the sound as well as adjust volume, pan, and frequency.

◆ soundPlayNoiseChannel()

int soundPlayNoiseChannel	(	int	channel,
		u16	freq,
		u8	volume,
		u8	pan
	)

Plays white noise with the specified parameters.

Parameters

channel	Channel to be used for this sound. If -1 is used, libnds will select a free channel and use it.
freq	The frequency in Hz of the sample.
volume	The channel volume. 0 to 127 (min to max).
pan	The channel pan 0 to 127 (left to right with 64 being centered).

Returns: An integer id coresponding to the channel of playback. This value can be used to pause, resume, or kill the sound as well as adjust volume, pan, and frequency.

◆ soundPlayPSG()

static int soundPlayPSG	(	DutyCycle	cycle,
		u16	freq,
		u8	volume,
		u8	pan
	)

inlinestatic

Pause a tone with the specified properties.

libnds will select a free channel to play the sound.

Parameters

cycle	The DutyCycle of the sound wave.
freq	The frequency in Hz of the sample.
volume	The channel volume. 0 to 127 (min to max)
pan	The channel pan 0 to 127 (left to right with 64 being centered).

Returns: An integer id coresponding to the channel of playback. This value can be used to pause, resume, or kill the sound as well as adjust volume, pan, and frequency.

◆ soundPlayPSGChannel()

int soundPlayPSGChannel	(	int	channel,
		DutyCycle	cycle,
		u16	freq,
		u8	volume,
		u8	pan
	)

Pause a tone with the specified properties.

Parameters

channel	Channel to be used for this sound. If -1 is used, libnds will select a free channel and use it.
cycle	The DutyCycle of the sound wave.
freq	The frequency in Hz of the sample.
volume	The channel volume. 0 to 127 (min to max)
pan	The channel pan 0 to 127 (left to right with 64 being centered).

Returns: An integer id coresponding to the channel of playback. This value can be used to pause, resume, or kill the sound as well as adjust volume, pan, and frequency.

◆ soundPlaySample()

static int soundPlaySample	(	const void *	data,
		SoundFormat	format,
		u32	dataSize,
		u16	freq,
		u8	volume,
		u8	pan,
		bool	loop,
		u16	loopPoint
	)

inlinestatic

Plays a sound in the specified format at the specified frequency.

libnds will select a free channel to play the sound.

Parameters

data	A pointer to the sound data.
format	The format of the data (only 16-bit and 8-bit pcm and ADPCM formats are supported by this function).
dataSize	The size in bytes of the sound data.
freq	The frequency in Hz of the sample.
volume	The channel volume. 0 to 127 (min to max).
pan	The channel pan 0 to 127 (left to right with 64 being centered).
loop	If true, the sample will loop playing once then repeating starting at the offset stored in loopPoint.
loopPoint	The offset for the sample loop to restart when repeating.

Returns: An integer id coresponding to the channel of playback. This value can be used to pause, resume, or kill the sound as well as adjust volume, pan, and frequency

◆ soundPlaySampleChannel()

int soundPlaySampleChannel	(	int	channel,
		const void *	data,
		SoundFormat	format,
		u32	dataSize,
		u16	freq,
		u8	volume,
		u8	pan,
		bool	loop,
		u16	loopPoint
	)

Plays a sound in the specified format at the specified frequency.

Parameters

channel	Channel to be used for this sound. If -1 is used, libnds will select a free channel and use it.
data	A pointer to the sound data.
format	The format of the data (only 16-bit and 8-bit pcm and ADPCM formats are supported by this function).
dataSize	The size in bytes of the sound data.
freq	The frequency in Hz of the sample.
volume	The channel volume. 0 to 127 (min to max).
pan	The channel pan 0 to 127 (left to right with 64 being centered).
loop	If true, the sample will loop playing once then repeating starting at the offset stored in loopPoint.
loopPoint	The offset for the sample loop to restart when repeating.

Returns: An integer id coresponding to the channel of playback. This value can be used to pause, resume, or kill the sound as well as adjust volume, pan, and frequency

◆ soundResume()

void soundResume ( int soundId )

Resumes a paused sound.

Parameters

soundId The sound ID returned by play sound.

◆ soundSetFreq()

void soundSetFreq	(	int	soundId,
		u16	freq
	)

Sets the sound frequency.

Parameters

soundId	The sound ID returned by play sound.
freq	The frequency in Hz.

◆ soundSetPan()

void soundSetPan	(	int	soundId,
		u8	pan
	)

Sets the sound panning.

Parameters

soundId	The sound ID returned by play sound.
pan	The new pan value (0 to 127 left to right, 64 = center).

◆ soundSetVolume()

void soundSetVolume	(	int	soundId,
		u8	volume
	)

Sets the sound volume.

Parameters

soundId	The sound ID returned by play sound.
volume	The new volume (0 to 127 min to max).

◆ soundSetWaveDuty()

void soundSetWaveDuty	(	int	soundId,
		DutyCycle	cycle
	)

Sets the Wave Duty of a PSG sound.

Parameters

soundId	The sound ID returned by play sound.
cycle	The DutyCycle of the sound wave.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ DutyCycle

◆ MicFormat

◆ SoundCaptureFormat

◆ SoundFormat

Function Documentation

◆ soundCaptureStart()

◆ soundCaptureStop()

◆ soundEnable()

◆ soundExtSetFrequency()

◆ soundExtSetRatio()

◆ soundKill()

◆ soundMicPowerOn()

◆ soundMicRecord()

◆ soundPause()

◆ soundPlayNoise()

◆ soundPlayNoiseChannel()

◆ soundPlayPSG()

◆ soundPlayPSGChannel()

◆ soundPlaySample()

◆ soundPlaySampleChannel()

◆ soundResume()

◆ soundSetFreq()

◆ soundSetPan()

◆ soundSetVolume()

◆ soundSetWaveDuty()