Table of Contents
- MADPlug Control
- MADDriver Class
- MADMusic Class
- MADChannel Class
- MADInstrument Class
Introduction
The MADPlug is a control for REALbasic built on top of the PlayerPRO MAD Library, written by
Antoine Rosset. MADPlug allows developers to playback a variety of different 'tracker' file formats,
such as MOD, MAD, S3M, XM, IT, OKTA, MTM, and MED.
Requirements
- A PowerMacintosh computer
- Stereo headphones or speakers are recommended
Installation
- Ensure that there is a folder named Plugins inside the folder that contains your copy of
REALbasic. If there isn't one, create one.
- Move the InputWidget plugin from the InputWidget folder into the Plugins folder.
- Restart REALbasic.
MADPlug Control
Introduction
The MADPlug Control is the main part of the MADPlug plugin.
The MADPlug Control is an 'invisible' control - that means it only shows
up in the IDE, but not in the actual application. A MADPlug is created by
dragging it onto a window.
Before the MADPlug can play anything, a file must be loaded into it using
one of the Load methods. After a file has been loaded, the Play method can
be called to start MADPlug playing the music file.
MADPlug supports the following 'tracker' file formats:
- MAD(I, F, H) - PlayerPro
- MOD - SoundTracker
- S3M - ScreamTracker
- XM - FastTracker
- IT
- OKTA
- MED
- MTM
Properties
[ Note - not all of the properties are visible from the Properties palette. They are only accessible from code,
and are marked Runtime Only ]
- Duration as Integer
The length of the music file in Ticks (60ths of a second)
- Position as Integer
Position in the music in Ticks (60ths of a second)
- Volume as Integer
The playback volume for the MADPlug. The volume must be in the range [0 ... 64].
- Driver as MADDriver
The driver currently being used to play back the music. See the MADDriver section for more
information.
- Music as MADMusic
The music data for the music currently being played. See the MADMusic section for more
information.
- ChannelCount as Integer
The number of channels allocated by the MADPlug to play the music.
- Channel(index) as MADChannel
The information for the channels allocated by the MADPlug. See the MADChannel section for
more information
Methods
- Load(file as FolderItem) as Integer
This method loads the music data from the FolderItem object file. After the music data has been
loaded, the Driver, Music and Channel properties can be used.
- Load(id as Integer) as Integer
This method loads the music data from a MADI resource with the resource ID matching that
specified by id. After the music data has been loaded, the Driver, Music and Channel properties
can be used.
- Close
Closes the currently open music data.
- Play() as Integer
Plays the currently loaded music data.
- Stop
Stops the MADPlug playing.
- Pause
Pauses the MADPlug.
- StartFrom(position as Integer)
Starts the MADPlug playing the music at the position specified by position. Position is given in
Ticks (60ths of a second.)
Events
- Open
Called after the InputWidget has been created. This usually happens when
a window is opened
- Close
Called before the InputWidget is destroyed. This usually happens when a
window is closed
- Error(errorCode as Integer)
Called when an error occurs internally. See the error code table at the end
of this document for more information on the error codes.
MADDriver Class
Introduction
A MADDriver object is created for every MADPlug control. This class holds the
configuration for the MADPlug.
It is presently unimplemented. In future, it will expose properties and methods for
configuration the playback engine such as bit-depth (8/16), sample-rate (22kHz, 44kHz.)
It will also allow you to write the configuration out in a string so it can be read back
in again at a later date.
MADMusic Class
Introduction
A MADMusic object is created every time music data is loaded in (either from a file
or a resource.) It presents information about the current music data.
Properties
- Name as String
The internal name of the song being played.
- InstrumentCount as Integer
The number of instruments used by the song.
- Instrument(index) as MADInstrument
Array of instrument objects. See the MADInstrument section for more information.
MADChannel Class
Introduction
SoundTracker files are multi-channel music files which are mixed down to a stereo pair
of channels at playback time. To playback the files, a number of MADChannels are
allocated. The parameters (volume, panning) of these channels can be altered in realtime.
Properties
- Volume as Integer
The volume of the channel. This value lies in the range [0 ... 64.]
- Pan as Integer
The pan (left or right) of the channel. This value lies in the range [0 ... 64.]
The channel is panned central when the pan value is 32.
- Level as Integer
The peak level of the channel. This level is updated every time a new sound is
played on the channel. This property is both read and write, and if it is to be used for
a VU meter it must be decremented by 1 at regular intervals (every 1 or 2 Ticks.)
MADInstrument Class
Introduction
Properties
- Name as String
The internal name of the instrument.
Error Codes
- Out of memory = -1
- Error reading music = -2
- Incompatible file = -3
- MADLibrary not initialised = -4
- Parameter error = -5
- Unknown error = -6
- SoundManager error = -7
- File not supported error = -9
- Cannot find translator = -10
- Music has no driver = -11
- Driver has no music = -12
- Bad FolderItem specified = -20
- Bad file = -21
MADPlug is a product of Essence Software.
Contact:
Phone: +44 (0)1577 861917
Fax: +44 (0)1577 861914
Email: info@essencesw.com
58 Montgomery Street
Kinross
Scotland
KY13 8EB