GNU Info

(mikmod.info)Modules and Player Control

---

Next: Loading Data from Memory Prev: Samples and Voice Control Up: Using the Library

---

Enter node , (file) or (file)node

Modules and Player Control
==========================

   As for the sound drivers, you have to register the module loaders
you want to use for MikMod to be able to load modules. You can either
register all the module loaders with `MikMod_RegisterAllLoaders', or
only a few of them with `MikMod_RegisterLoader'. Be careful if you
choose this solution, as the 15 instrument MOD loader has to be
registered last, since loaders are called in the order they were
register to identify modules, and the detection of this format is not
fully reliable, so other modules might be mistaken as 15 instrument MOD
files.

   You can get some printable information regarding the registered
loaders with `MikMod_InfoLoader'; don't forget to call `free' on the
returned string when you don't need it anymore.

   Note that, contrary to the sound drivers, you can register module
loaders at any time, it doesn't matter.

   For playlists, you might be interested in knowing the module title
first, and `Player_LoadTitle' will give you this information. Don't
forget to `free' the returned text when you don't need it anymore.

   You can load a module either with `Player_Load' and the name of the
module, or with `Player_LoadFP' and an open `FILE*' pointer. These
functions also expect a maximal number of voices, and a curiosity flag.
Unless you have excellent reasons not to do so, choose a big limit,
such as 64 or even 128 for complex Impulse Tracker modules. Both
functions return a pointer to an `MODULE' structure, or `NULL' if an
error occurs.

   You'll find some useful information in this structure:
   - `numchn' contains the number of module "real" channels.

   - `numvoices' contains the number of voices reserved by the player
     for the real channels and the virtual channels (NNA).

   - `numpas' and `numpat' contain the number of song positions and
     song patterns.

   - `numins' and `numsmp' contain the number of instruments and
     samples.

   - `songname' contains the song title.

   - `modtype' contains the name of the tracker used to create the song.

   - `comment' contains the song comment, if it has one.

   - `sngtime' contains the time elapsed in the module, in 2^-10
     seconds (not exactly a millisecond).

   - `sngspd' and `bpm' contain the song speed and tempo.

   - `realchn' contains the actual number of active channels.

   - `totalchn' contains the actual number of active virtual channels,
     i.e. the sum of `realchn' and the number of NNA virtual channels.

   Now that the module is loaded, you need to tell the module player
that you want to play this particular module with `Player_Start' (the
player can only play one module, but you can have several modules in
memory). The playback begins. Should you forget which module is
playing, `Player_GetModule' will return it to you.

   You can change the current song position with the functions
`Player_NextPosition', `Player_PrevPosition' and `Player_SetPosition',
the speed with `Player_SetSpeed' and `Player_SetTempo', and the volume
(ranging from 0 to 128) with `Player_SetVolume'.

   Playback can be paused or resumed with `Player_TogglePause'. Be sure
to check with `Player_Paused' that it isn't already in the state you
want !

   Fine player control is achieved by the functions `Player_Mute',
`Player_UnMute' and `Player_ToggleMute' which can silence or resume a
set of module channels. The function `Player_Muted' will return the
state of a given channel. And if you want even more control, you can
get the voice corresponding to a module channel with
`Player_GetChannelVoice' and act directly on the voice.

   Modules play only once, but can loop indefinitely if they are
designed to do so.  You can change this behavior with the `wrap' and
`loop' of the `MODULE' structure; the first one, if set, will make the
module restart when it's finished, and the second one, if set, will
prevent the module from jumping backwards.

   You can test if the module is still playing with `Player_Active',
and you can stop it at any time with `Player_Stop'. When the module
isn't needed anymore, get rid of it with `Player_Free'.