sound.h File Reference

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. 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	SoundFormat {   SoundFormat_16Bit = 1,   SoundFormat_8Bit = 0,   SoundFormat_PSG = 3,   SoundFormat_ADPCM = 2 }
	Sound formats used by the DS. More...
Functions
void	soundDisable (void)
	Disables Sound on the DS.
void	soundEnable (void)
	Enables Sound on the DS. Should be called prior to attempting sound playback.
void	soundKill (int soundId)
	Stops the sound specified by soundId and frees any resources allocated.
void	soundMicOff (void)
	Stops the microphone from recording.
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.
int	soundPlayNoise (u16 freq, u8 volume, u8 pan)
	Plays white noise with the specified parameters.
int	soundPlayPSG (DutyCycle cycle, u16 freq, u8 volume, u8 pan)
	Pause a tone with the specified properties.
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.
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 pan.
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

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

enum MicFormat

Microphone recording formats DS.

Enumerator:

MicFormat_8Bit	8-bit PCM
MicFormat_12Bit	12-bit PCM

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

void soundKill

(

int

soundId

)

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

Parameters:

soundId

The sound ID returned by play sound

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

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

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	This will be called every time the buffer is full or half full

Returns:

Returns non zero for success.

Examples:

audio/micrecord/source/micrecord.c.

void soundPause

(

int

soundId

)

Pause the sound specified by soundId.

Parameters:

soundId

The sound ID returned by play sound

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

Plays white noise with the specified parameters.

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

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

Pause a tone with the specified properties.

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

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.

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

Examples:

audio/micrecord/source/micrecord.c.

void soundResume

(

int

soundId

)

Resumes a paused sound.

Parameters:

soundId

The sound ID returned by play sound

void soundSetFreq	(	int	soundId,
		u16	freq
	)

Sets the sound frequency.

Parameters:

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

void soundSetPan	(	int	soundId,
		u8	pan
	)

Sets the sound pan.

Parameters:

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

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)

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