Thsound

From ProjectWiki
Jump to: navigation, search

Contents

What is this?

An audio library for the homebrew on Nintendo DS. When adding sound to games may also want to consider thmp3 for mp3 playback, maxmod with .mod/sfx/etc formats, and/or Meraman's NDS_BGMDRV which includes a software mml/midi sequencer, synth, and special effects facilities.

Features thsound:

  • Playback of 8bit, 16bit pcm, ICM-ADPCM
  • Looping
  • Noise generation
  • Tone generation using the PSG (Square wave, adjustable duty cycle, Equal Temperment tuning)
  • Arm7's audio registers accessible via arm9
  • Adjustable fade out of individual channels
  • Audio sample manager (to simplify playback)
  • Samples loadable from .wav files on nitrofs, fat-fs, etc..
  • Dynamic manipulation of playing samples.. (stopping playing samples, pitch, volume, pan, etc can all be manipulated)
  • Playback channel is selectable
  • Presetable defaults for sample rate, volume, and pan.

Todo:

  • Add auto channel selection
  • Make a list of resources used (memory, fifo channels, etc etc)

Dependencies
This library requires the thfifo library for inter-processor communications. It also requires libfat and possibly nitrofs for loading .wav files.

Where to get it

Currently the sources for this are part of LibThds and is probably the easiest to use due to its dependence on Thfifo. The latest version of the source can be downloaded via SVN (see libthds page) or directly from the svn httpd:

Note: Thfifo is required for interprocessor communications.

Functions common to both CPU

thSndInit
This needs to be called at startup on both CPU before any other audio functions in order to allocate memory, and create a fifo channel.

void thSndInit(void);

Sample loading and management functions

Sample management functions are provided to allowing loading of .wav data and to simplify playback by eliminating the need to specify start, length, loop point, sample rate, and format.

Creation functions return (or in case of thSampleDestroy take) a pointer to a structure of the thSample_t type. (todo: add macros for returning/manipulating values in this structure)

Loading sample via .wav files is prolly the simplest way to add audio to a project. :D

thSampleLoadWav
Load a sample from .wav file. Supported formats are 8bit mono, 16bit mono, and IMA-ADPCM. Stereo sample support MAY be added later.

  • name - name of file to load

Returns pointer to newly created sample.

thSample_t *thSampleLoadWav(const char *name);

thSampleCreate
Create a sample from raw audio data.

  • start - pointer to start of sample in memory
  • len - length of sample (in samples)
  • loopstart - Loop point of sample. in number of samples from start.
  • rate - sample rate in hertz (44100, 11025, etc etc)
  • opts - options. Should include one each of: SNDPCM8, SNDPCM16, SNDADPCM. Additionally may OR on SNDLOOP (or even specify a default volume, pan, but wont get into this yet.. :P)

Returns Pointer to newly created sample.

thSample_t *thSampleCreate(void *start, int len, void *loopstart, int rate, u8 opts);

thSampleDestroy
Unloads a sample freeing up any used memory. If it was loaded from .wav file will automagically unload that as well. :p

void thSampleDestroy(thSample_t *thSample);

Wave loading/playing example

thSample_t *mysample;
 mysample=thSampleLoadWav("nitro:/test.wav");
 thSndPlaySample(4, mysample, 127, 64); //thSndPlaySample(char chan, thSample_t *sample, char vol, char pan)

General Sound Functions

thPlayDefaults
Sets default sample playback options.

void thPlayDefaults(int rate, char level, char pan, u32 flags);

thSndPlaySample
Starts playing a previously loaded sample.

  • chan - channel to use for playback
  • sample - previously loaded sample
  • vol - playback volume (0 to 127)
  • pan - playback pan (0 to 127, 0 = left, 127 = right, 64 = center)
void thSndPlaySample(char chan, thSample_t *sample, char vol, char pan);

thSndPlaySampleRate
Starts playing a previously loaded sample at specified rate.

  • chan - channel to use for playback
  • sample - previously loaded sample
  • rate - sample playback rate (in hz)
  • vol - playback volume (0 to 127)
  • pan - playback pan (0 to 127, 0 = left, 127 = right, 64 = center)
void thSndPlaySampleRate(char chan, thSample_t *sample, u16 rate, char vol, char pan);

thSndPlayRaw
Plays a sound in raw format from memory on the specified channel.

  • chan - channel to use for playback (0 to 15)
  • start - pointer to start of audio data in memory
  • len - length of sample (in samples)
  • vol - playback volume (0 to 127)
  • pan - playback pan (0 to 127, 0 = left, 127 = right, 64 = center)
  • loopstart - position to start looping sound (in samples)
  • opts - options (such as SNDPCM16, SNDPCM8, etc... see options sections)
void thSndPlayRaw(char chan, void *start, int len, int rate, char vol, char pan, u32 loopstart, u32 opts);

thSndRegDirect
Direct manipulation of the arm7's audio registers from the arm9

  • chan - channel to manipulate (0 to 15)
  • start - start register
  • len - length register
  • rate - rate register
  • loopstart - loopstart register
  • opt - channel's CR register
void thSndRegDirect(char chan, u32 start, int len, int rate, u32 loopstart, u32 opts);

thSndDefPlaySample
Playback a sample use default volume and pan settings

  • chan - channel to manipulate (0 to 15)
  • sample - pointer to previously loaded audio sample
void thSndDefPlaySample(char chan, thSample_t *sample);

thSndDefPlayRaw
Playback a sample using default volume, pan, and rate settings

  • chan - channel to manipulate (0 to 15)
  • start - pointer to start of audio data
  • len - length of audio data (in samples)
void thSndDefPlayRaw(char chan, void *start, int len);

thSndPlayNote
Plays a note on the specified channel via the PSG. Note is a square wave with adjustable duty cycle when using channels 8 thru 13, and noise when using channels 14 or 15.

  • chan - channel to play note (8 to 15 only!)
  • note - note to play 0 = c, 1 = c#, 2 = d, 3 = d#, 4 = e, 5 = f, etc etc up to 64 or so (range depends on tuning)
  • duty - duty cycle of PSG (0 to 7, use 4 if in doubt ?_?)
  • duration - fade out time, in milliseconds * 1000, for instance 1000 = 1 second, 500 = .5 seconds, etc. 0 = no fadeout note must be stopped manually with thSndStop().
  • vol - playback volume (0 to 127)
  • pan - playback pan (0 to 127, 0 = left, 127 = right, 64 = center)
void thSndPlayNote(char chan, char note, char duty, u16 duration, char vol, char pan);

thSndStop
Immediately stops playing sample, note, noise, or raw data the specified channel.

  • chan - channel to stop
void thSndStop(char chan);

Changing Active Parameters

These functions change various attributes after sound has already began playing.

thSndSetVol
Change channel's volume.

  • chan - channel to change (0-15)
  • vol - playback volume (0 to 127)
void thSndSetVol(char chan, char vol);

thSndSetPan
Change channel's Pan..

  • chan - channel to change (0-15)
  • pan - playback pan (0 to 127, 0 = left, 127 = right, 64 = center)
void thSndSetPan(char chan, char pan);

thSndSetRate
Change channel's sample rate. Usefull for special effects! :p

  • chan - channel to change (0-15)
  • rate - new channel frequency (in hertz)
void thSndSetRate(char chan, u32 rate);

Change PSG's duty cycle. thSndSetDuty

  • chan - channel to play note (8 to 13 only!)
  • duty - duty cycle of PSG (0 to 7, use 4 if in doubt ?_?)
void thSndSetDuty(char chan, char duty);

thSndFade
Initiate a fadeout on specified channel. Useful for fading out repeating wavforms, mp3s, or even can be used with PSG note generation for rudamentary synth effects. Once volume reaches 0 audio playback is stopped on specified channel

  • chan - channel to change (0-15)
  • faderate - time to take fading out. (ms * 1000) for instance 1000 = 1 second, 2000 = 2 seconds, 500 = .5 seconds, etc.. up to 65535 :D
void thSndFade(char chan, u16 faderate);
Personal tools
irssi scripts
eggdrop scripts