Mp3AdvDll.dll -- GameStudio Mp3 Player v1.0 -- First Release

Author: Cameron Aycock xagon7@yahoo.com -- xagon7 on the GameStudio Forum
Date: April 10 , 2002

Place the DLL and the WDL file in the project you want to play the Audio files... I also suggest placing the audio files int he same directory as well. INclude the WDL in your project to include the "dllfunction" definitions.


Mp3AdvDll.dll is Creditware .. unlike tmAudioPlugin .. which requires the bass.dll .. and is $100 for shareware, OR the GSAudio dll.... which is $20 for commercial use, the Mp3AdvDll.dll can be used for ANY and ALL purposes, provided that I (Cameron Aycock) am given credit in the credits of the game or application with the following string:

"Additional audio programming by Cameron Aycock xagon7@yahoo.com"


 ... failing that, include it in your readme file or other documentation.. that is all that I ask.

This document describes how to use the Mp3AdvDll.dll file with GameStudio. This version was written with A5 of the GameStudio engine and has not been tested with any other versions.

The Mp3AdvDll.dll is a Mp3 / Windows MEdia audio player for the A5 engine. It supports almost all audio formats as Windows Media PLayer, ad it is based on the same DirectShow interface.

Requirements.. as far as I know only the latest version of DirectX ... 8.1 at the time of this writing. And a beefy enough computer for A5 ;)




Features:

SIMULTANEOUS PLAYBACK OF MULTIPLE SONGS
Looping Play
SeekToAPosition
Play
Stop
Pause
Balance modification
Volume mondification


function List:

InitMp3Adv(); // loads the Mp3Manager for the songs

CloseMp3Adv(); //closes and frees memory for the Mp3Player

LoadSongSlot(FileName);returns SongSlotID (integer) //Load "FileName" (string) into a slot .. returns the SongSlotID (number) of the SongSlot ....keep the SongSlotID in a variable

GetIndexFromFile(FileName); returns SongSlotID (integer) //Get the associated SongSlotID for a given "filename" (string)

PlaySong(SongSlotID,Loop); //Play the specified by the SongSlotID (integer) .. if "Loop" (integer) is 1 then the song will repeat after completion

StopSong(SongSlotID); //Play the specified by the given SongSlotID

PauseSong(SongSlotID); //Pause the specified by the given SongSlotID

GetVolume(SongSlotID); returns the volume (integer) //gets the volume (from 0 to 10000) of the song specified by SongSlotID

SetVolume(SongSlotID, NewVolume); //Sets the Volume of the given SongSlotID to NewVolume (integer) .. values from 0 to 10000

GetBalance(SongSlotID); returns Balance (integer) // returns the Balance information for the given SongSlotID .. values are from 0 (full left .. to 20000 (full right) .. with 10000 being dead center


SetBalance(SongSlotID, NeBalance); // sets the Balance information for the given SongSlotID to the value in "NewBalance" (integer).. values are from 0 (full left .. to 20000 (full right) .. with 10000 being dead center

GetPosition(SongSlotID); returns CurrentPosition (integer) // returns the current playing position for a given SongSlotID .. there are 1,000,000 positions per song .. 0 is the start and 1,000,000 is the end and 500,000 is the middle of the song

SetPosition(SongSlotID, NewPosition); //Sets the song playing in SongSlotID to the Position supplied by "NewPosition" (integer)



As you have probably noticed by now .. all songs once loaded into memory by LoadSongSlot() are refrenced by a SongSlotID. Once a SongSlot is filled it cannot be removed or replaced until the application calls CloseMp3Adv .. which clears all slots and unloads any ram. Here is a little better explanation.

There are virtually an unlimited number of SongSlots for playing.

consider the following WDL code

tmp1 = LoadSongSlot("MySongA.mp3");
tmp2 = LoadSongSlot("MySongB.mp3")
tmp3 = LoadSongSlot("MySongC.mp3")

will load 3 mp3 files into memory and ready them for playing.

To perform any other function you must refrence the song by it's SongSlotID (tmp1 .. tmp3 in our above example)

to play "MySongB.mp3" we do this:

PlaySong(tmp2, 1); 

the 1 tells the player that we want to loop the song when it is finished

... now we have "MySongB.mp3" playing .. we want to have "MySongC.mp3" play slightly lower in the background .. so we write:

SetVolume(tmp3, 7000);
PlaySong(tmp3, 0); //0 since we don't want it to loop.




AVOID RE_LOADING the SAME SONG IN THE SAME SESSION. .. unless you are doing a rendition of Row Row Row you boat and need the same song played at slightly different offsets. 

For instance .. refer to the above example again, once tmp3 ("MySongC.mp3") has finished playing, to play it again, we do NOT call LoadSongSlot .. we just use the following code:

SetPosition(tmp3, 0);
PlaySong(tmp3, 0);


This dll should play even between level loads. When you are through or want to load up another set of songs call CloseMp3Adv() .. but don't forget to call InitMp3Adv() again before loading songs.

Easy enough? .. I hope so .. post to the forum if you have trouble or questions.













