modplay.txt

libmodplay README
-------------------------
libmodplay is a library which plays music module files on your PlayStation.
You can use it to play music in your productions. It (currently) supports the ProTracker .MOD and the Composer 669 .669 formats, and this means you can grab many module files from the internet and use them in your own productions very easily and (almost) transparently.
Control is provided over Sound RAM addresses and base voices which allows playing a music and playing your own sound effects without resorting to guesses and ugly hacks.

Little tutorial
-------------------------
The music module file you want to use must be loaded in memory. How to do this will not be explained here. You will also need to initialize the SPU of the PlayStation before you use the MODPlay() function.

Pass to MODLoad() as its only argument the pointer to the memory area in which loaded the music module file. MODLoad() will then return a pointer to ModMusic structure (ModMusic *). As all the data from the module file was copied to the structure you can free or otherwise use for another purpose the memory area whose pointer you passed to MODLoad().

At this point you must load the samples of the music module to Sound RAM. There are two ways of doing this:
1) Using MODUploadSamples(). This uses the samples in PCM data from the music module data, and before
     being used by the SPU, they need to be converted at runtime (by the PS CPU) to ADPCM. This takes
     a lot of time and the resulting quality is very poor. (I needed to make it not very dog slow and if anything I'm a beginner at codecs -nextvolume)
2) Using MOD4PSX_Upload(). This loads the samples from preconverted data. The samples here are 
    directly in ADPCM, and this way is both very fast and high quality. The only shortcoming is that
    you need to use more RAM, but this problem is non-existent if you program in certain ways,
    for example by loading data from the CD filesystem into a buffer. You could first load the MOD,
    and *then* load the ADPCM sample data. An ADPCM sample data pack file is obtained from a music 
    module file by using the mod4psx tool included in the PSXSDK.
    You pass the pointer to the memory area where this pack file is loaded to MOD4PSX_Upload() as
    first argument.
    
    The base_addr argument has the same meaning for both uploading functions; it specifies the
    Sound RAM address to start uploading to. Then the two functions return the Sound RAM address
    after the uploaded sample data. base_addr should be a multiple of 8 due to hardware limitations.
    
After doing this, to play your music you have to call MODPlay(), giving the pointer to the ModMusic structure as its only argument, fifty/sixty times a second. You can do so by setting up a counter which is increased every timeVSync/VBlank happens (this means it is slightly slower on PAL if done in this way, but it's the easiest method). Check the modplayer example for more information.

When you want to stop playing the music module, call MODStop() in the same way as you called MODPlay().

Basically, this is what you have to do. It is not hard at all, just remember that the default base sound voice is 0, and that you don't need to play anything on voices 0-7 yourself, or things will not work well. Eight voices are used because this is the limit the Protracker MOD format and Composer 669 formats have.
You can change the number of the base sound voice to another value by using the MODSetBaseVoice() function before using MODPlay().

ISSUES
--------------------
- With ProTracker MODs, sample looping is not implemented yet when converting samples at runtime and many effects aren't implemented yet
  so some modules could sound differently to how they should sound.
  Always use MODs with few effects.
- Tempo is wrong for Composer 669 music modules because the format is badly documented
- Sampe looping for Composer 669 modules is not implemented yet