*************************************************************************** Instructions for using "medplayer.library" and "octaplayer.library" V2.00/V3.00, by Teijo Kinnunen. *************************************************************************** medplayer.library ~~~~~~~~~~~~~~~~~ "medplayer.library" is a shared library, which can be used to load and play MED/OctaMED 4-channel modules You can call its functions from any language which supports library calls (C, Assembler, Basic...) First you must install "medplayer.library" to your LIBS: drawer (click Install_Libraries to do that). You can also load it with ARP's "loadlib" command. "medplayer.library" supports only 4-channel MED songs!! For OctaMED 5 - 8 channel songs there's "octaplayer.library". There's a header file 'libproto.h' that contains the prototypes and #pragmas for use with SAS/Lattice C V5. Here's the complete list of the functions in "medplayer.library" (in RKM autodoc-style): --------------------------------------------------------------------------- --------------------------------------------------------------------------- GetPlayer NAME GetPlayer -- get and initialize the player routine SYNOPSIS error = GetPlayer(midi) D0 D0 FUNCTION This routine allocates the audio channels and CIAB timer A/B and prepares the interrupt. If "midi" is nonzero, serial port is allocated and initialized. You should call this routine when your programs starts up. INPUTS midi = 0 no midi, 1 set up midi. When you use a song that has only Amiga samples, there's no reason to allocate the serial port. Then set midi to 0. RESULT If everything is OK, GetPlayer() returns zero. If initialization failed or somebody else is currently using the library, then GetPlayer() returns nonzero value. NOTE: Even if GetPlayer() returned an error, you can still call the library functions without making harm. They just won't work (except LoadModule(), UnLoadModule(), RelocModule() and GetCurrentModule(), which always work). SEE ALSO FreePlayer --------------------------------------------------------------------------- --------------------------------------------------------------------------- FreePlayer NAME FreePlayer -- free the resources allocated by GetPlayer() SYNOPSIS FreePlayer() FUNCTION This routine frees all resources allocated by GetPlayer(). Remember always call this routine before your program exits. It doesn't harm to call this if GetPlayer() failed. If you don't call this function during exit, audio channels, timer etc. will remain allocated until reboot. SEE ALSO GetPlayer --------------------------------------------------------------------------- --------------------------------------------------------------------------- PlayModule NAME PlayModule -- play module from the beginning SYNOPSIS PlayModule(module) A0 FUNCTION This routine starts to play the module from the beginning. The module can be obtained by calling LoadModule() or it can be incorporated directly into your program. The module has to be relocated before calling PlayModule()! INPUTS module = pointer to the module. SEE ALSO ContModule, StopPlayer --------------------------------------------------------------------------- --------------------------------------------------------------------------- ContModule NAME ContModule -- continue playing the module from where it stopped SYNOPSIS ContModule(module) A0 FUNCTION ContModule() functions just like PlayModule() except if you have stopped playing with StopPlayer(), the playing will continue where it stopped. When you play the module first time, you should use PlayModule(). INPUTS module = pointer to module. SEE ALSO PlayModule, StopPlayer --------------------------------------------------------------------------- --------------------------------------------------------------------------- StopPlayer NAME StopPlayer -- stops playing immediately SYNOPSIS StopPlayer() FUNCTION Stop. SEE ALSO PlayModule, ContModule --------------------------------------------------------------------------- --------------------------------------------------------------------------- DimOffPlayer NOTE This is an obsolete function! It was removed in V2 of the library, and it now just does StopPlayer()! --------------------------------------------------------------------------- --------------------------------------------------------------------------- SetTempo NAME SetTempo -- modify the playing speed SYNOPSIS SetTempo(tempo) D0 FUNCTION If you want to modify the playback speed, you can call this one. This number should be 1 - 240. Note that tempos 1 - 10 are recognized as SoundTracker tempos. This function probably has not much use. INPUTS tempo = new tempo --------------------------------------------------------------------------- --------------------------------------------------------------------------- LoadModule NAME LoadModule -- load a MED module from disk and relocate it SYNOPSIS module = LoadModule(name) D0 A0 FUNCTION When you want to load a module from disk, call this function. The function loads only MED modules (MMD0). It doesn't load Tracker-modules, MED songs or object files. Only MMD0's (MMD0 is the identification word at the beginning of the file). Because the module contains many pointers, they must be relocated. This function relocates the module automatically. If you include the module as a binary file converted with Objconv, YOU must relocate it. This is an easy thing to do. Just call RelocModule(). Version 3 of medplayer.library also handles OctaMED Pro type modules (MMD1). INPUTS name = pointer to file name (null-terminated) RESULT module = pointer to module. If failed to load for some reason (disk error, out of memory, not a module), zero will be returned. SEE ALSO UnLoadModule --------------------------------------------------------------------------- --------------------------------------------------------------------------- UnLoadModule NAME UnLoadModule -- frees the module from memory SYNOPSIS UnLoadModule(module) A0 FUNCTION When you don't need the module anymore, you MUST free the memory it has used. Use this routine for it. Remember to stop the player before unloading the module it is playing. NOTE: unload only those modules which are loaded with LoadModule(). If you attempt to free module which is a part of the program, you will cause guru 81000009/81000005. INPUTS module = pointer to module. If zero, nothing happens. SEE ALSO LoadModule --------------------------------------------------------------------------- --------------------------------------------------------------------------- GetCurrentModule NAME GetCurrentModule -- returns the address of module currently playing SYNOPSIS module = GetCurrentModule() D0 FUNCTION Simply returns the pointer of the module, which is currently playing (or if player is stopped, which was played last). This works also if some other task is currently playing. In this case, because of multitasking, you should have no use for the value (the module can be already unloaded). You may ask what use this function has. Well, I'm not sure, but because this function takes only 2 machine language instructions (8 bytes of memory) there's not much harm of it. RESULT module = pointer to current module --------------------------------------------------------------------------- --------------------------------------------------------------------------- ResetMIDI NAME ResetMIDI -- reset all pitchbenders and modulation wheels and ask player to resend the preset values SYNOPSIS ResetMIDI() FUNCTION This function resets pitchbenders and modulation wheels on all MIDI channels. It also asks the player to send again the preset change requests for all instruments, so that the presets will be correct if the user has changed them. It performs the same function as Ctrl-Space in OctaMED. --------------------------------------------------------------------------- --------------------------------------------------------------------------- NOTE: THE FOLLOWING FUNCTIONS ARE ONLY AVAILABLE IN MEDPLAYER.LIBRARY V2 OR LATER, BE SURE THAT YOU'RE REALLY USING V2 OF THE LIBRARY e.g. MEDPlayerBase = OpenLibrary("medplayer.library",2); --------------------------------------------------------------------------- --------------------------------------------------------------------------- SetModnum NAME SetModnum -- select the number of the song (in multi-module) SYNOPSIS SetModnum(modnum) D0 FUNCTION Use this function to set the number of song you want to play. Call this before PlayModule(). 0 is the first song, 1 is the second, and so on. If the module is not a multi-module, this function has no effect. --------------------------------------------------------------------------- --------------------------------------------------------------------------- RelocModule NAME RelocModule -- relocate module SYNOPSIS RelocModule(module) A0 FUNCTION This function relocates the module. It should be used if you've incorporated the module with Objconv program before using the module. Note that LoadModule() automatically relocs everything. --------------------------------------------------------------------------- *************************************************************************** octaplayer.library ~~~~~~~~~~~~~~~~~~ This library is made for playing OctaMED 5 - 8 channel songs ONLY. It doesn't support MIDI or 4-channel songs. The functions in it work quite similarly as medplayer.library's functions. See the medplayer.library docs above for explanation of the functions, as the functions in octaplayer.library work in the same way. The functions are: GetPlayer8() FreePlayer8() PlayModule8(module) ContModule8(module) StopPlayer8() LoadModule8(filename) UnLoadModule8(module) SetModnum8(modnum) RelocModule8(module) As you can see, every function has '8' in its name, and some functions that are in medplayer.library don't exist. *************************************************************************** Note: ~~~~~ Version 3 of both medplayer.library and octaplayer.library handle the new MMD1 module type correctly. No changes are required to programs calling these libraries. If you absolutely want MMD1 support, be sure to request V3 of the libraries. (e.g. OpenLibrary("medplayer.library",3); ) ***************************************************************************