Class Documentation
Music |
1.0 |
ID_MUSIC |
Beta |
Audio |
May 2003 |
Rocklyte Systems |
Rocklyte Systems, 1998-2003. All rights reserved. |
Plays digital music files. |
Description
The Music class is provided for the purpose of playing music modules
created with popular programs such as ProTracker. Music objects are very
easy to create - just specify a data source, then Init and Activate
the object to start playing a module. A variety of extra functions are also
provided for adding extra manipulations to digital music, for example fading,
tempo and volume adjustments, pause, replay and so on.
The Music class is fully compatible with DML. Here is an example that
illustrates how to load and play a music file automatically:
<music src="athene:audio/music/fallofseraphs.mod"/>
Currently the Music class supports FastTracker (XM), ScreamTracker (S3M),
ProTracker (MOD) and Impulse Tracker (IT) modules. Raw audio streams such
as CD audio, MP3 and OGG are not supported through the Music class - the Sound
class is the appropriate place to support these formats.
Actions
The Music class supports the following actions:
Activate | Plays digital music. |
ClosingTag | If the object is non-static, this action will play the music. |
Deactivate | Stops music playback at its current position. |
Disable | Temporarily pauses a music object up until the next Enable action. |
Enable | Continues playing digital music if the object has been disabled. |
Init | Prepares a music object for usage. |
Reset | Sets the music playback position back to the beginning of the score. |
Seek | Seeks to a new position within a music object. |
Structure
The Music object consists of the following public fields:
Active | This field is set to TRUE when a music object is playing audio. |
Audio | Refers to an audio object to use for digital audio output. |
Author | The name of the person or band that created the music. |
Callback | Used for receiving feedback during music playback. |
Copyright | Copyright details of an audio sample. |
Description | Long description for a music file. |
Disclaimer | The disclaimer associated with a digital music file. |
Flags | Special flags. |
Header | Contains the first 128 bytes of data in a music object's file header. |
Location | The location of a music object's audio data. |
Position | The current playback position in a digital music object. |
Software | The name of the application that was used to record or create the audio data. |
SongLength | The length of a musical score. |
Static | Set to TRUE to make the object static. |
Tempo | Current playback tempo. |
Title | The title of the musical score. |
TotalChannels | The total number of channels present in a digital music file. |
TotalInstruments | The total number of instruments present in a digital music file. |
TotalPatterns | The total number of patterns recorded in a digital music file. |
Volume | Determines the maximum volume allowed when playing a music object. |
Deactivate |
Stops music playback at its current position. |
Deactivating a music object will force it to stop playing all audio output,
as well as reducing any CPU time normally dedicated to music playback. If
possible, audio resources will be given back to the system when the music
object is deactivated.
Playback of the music object can be restarted with the Activate action.
The playback position will be set back to the beginning of the song when you
do this. If you would rather pause the song at its current position, use the
Disable and Enable actions instead.
|
|
Reset |
Sets the music playback position back to the beginning of the score. |
You can Reset a music object at any time to force the playback position
back to the beginning of the song.
|
|
Field: | Active |
Short: | This field is set to TRUE when a music object is playing audio. |
Type: | LONG |
Status: | Get |
You can read this field at any stage to determine whether or not a music
object is playing audio.
|
|
Field: | Audio |
Short: | Refers to an audio object to use for digital audio output. |
Type: | LONG |
Status: | Read/Init |
If you would like to specify an audio object to use for the output of
digital audio, you may make a reference to that object here. Otherwise, you
should leave this field as is and the music object will select the default
"SystemAudio" object on initialisation.
|
|
Field: | Author |
Short: | The name of the person or band that created the music. |
Type: | STRING |
Status: | Get/Set |
The name of the person or band that created the digital music track is
normally specified here. This provides a means for the original author/s to
claim credit for the work.
|
|
Field: | Callback |
Short: | Used for receiving feedback during music playback. |
Type: | void Callback(LONG Info, LONG Position, LONG Row) |
Status: | Read/Set |
You can set the Callback field if the music module contains embedded feedback
commands. For FastTracker and ScreamTracker modules, the Wxx command is
interpreted as the feedback command. When the playback of the module hits
one of these commands, your callback routine will be called with a reference
to the music object and the xx part of the command is returned in the Info
argument.
The format of the callback routine is:
void Callback(struct Music *, LONG Info)
|
|
Field: | Copyright |
Short: | Copyright details of an audio sample. |
Type: | STRING |
Status: | Get/Set |
Copyright details related to a music file may be specified here. The
copyright should be short and to the point, for example "Copyright
Season of Mist (c) 2000. All rights reserved."
|
|
Field: | Description |
Short: | Long description for a music file. |
Type: | STRING |
Status: | Get/Set |
A long description for a music file may be entered in this field. There is
no strict limit on the length of the description.
|
|
Field: | Disclaimer |
Short: | The disclaimer associated with a digital music file. |
Type: | STRING |
Status: | Get/Set |
If it is necessary to associate a disclaimer with a music object, the legal
text may be entered in this field. The Disclaimer field is set on
initialisation if the music source contains a disclaimer string.
|
|
Field: | Flags |
Short: | Special flags. |
Type: | LONG |
Status: | Read/Set |
Special flags may be set in this field. Currently valid flags are:
LOOP | If set, the music player will loop back to the beginning when it reaches the end of a song. |
ACTIVE | Readable flag that indicates that the music object is currently playing. |
|
|
Field: | Header |
Short: | Contains the first 128 bytes of data in a music object's file header. |
Type: | POINTER |
Status: | Get |
The Header field is a pointer to a 128 byte buffer that contains the first
128 bytes of information loaded from a music file on initialisation. This
special field is considered to be helpful only to developers writing add-on
components for the Music class.
The buffer that is referred to by the Header field is not populated until
the Init action is called on the music object.
|
|
Field: | Location |
Short: | The location of a music object's audio data. |
Type: | STRING |
Status: | Get/Set |
This compulsory field must refer to a file that contains the music data
that you want to load.
|
|
Field: | Position |
Short: | The current playback position in a digital music object. |
Type: | DOUBLE |
Status: | Read |
If you need to know the current playback position in a digital music
object, read this field. The position value is measured in seconds.
If you would like to move the playback position, use the Seek action
to play from a different area in the musical score.
|
|
Field: | Software |
Short: | The name of the application that was used to record or create the audio data. |
Type: | STRING |
Status: | Get/Set |
The Software field declares the name of the application that was used to
record or generate the original audio data.
|
|
Field: | SongLength |
Short: | The length of a musical score. |
Type: | DOUBLE |
Status: | Read |
Read this field if you would like to know the length of a musical score,
measured in seconds.
|
|
Field: | Static |
Short: | Set to TRUE to make the object static. |
Type: | BOOLEAN |
Status: | Read/Init |
To make a music object static, set this field to TRUE. If the object is
not made static then it will automatically play when a closing tag is
received.
|
|
Field: | Tempo |
Short: | Current playback tempo. |
Type: | FLOAT |
Status: | Get/Set |
The tempo is a percentage setting that indicates the speed that the music
is playing at. 100% is the default setting that will play the music at a
normal pace. Here are some examples:
25% - Play at 1/4 of the pace.
50% - Half the speed.
200% - Double the speed.
The maximum setting of 1000% will play the music at 10 times the normal
speed. The minimum possible tempo setting is 1%.
|
|
Field: | Title |
Short: | The title of the musical score. |
Type: | STRING |
Status: | Get/Set |
If a musical score has a title it must be declared through the Title
field in order for it to be recognised.
|
|
Field: | TotalChannels |
Short: | The total number of channels present in a digital music file. |
Type: | LONG |
Status: | Read |
If you would like to know the total number of channels that have been used
for recording a digital music file, read this field. A 'channel' is a flow of
sound that cannot be interrupted by other sound flows. By using multiple
channels, a musician can ensure that each instrument sample is given adequate
time to play completely. Channels are mixed during music playback into a
single stream of stereo output - this has an impact on speed depending on the
amount of channels in use.
|
|
Field: | TotalInstruments |
Short: | The total number of instruments present in a digital music file. |
Type: | LONG |
Status: | Read |
If you would like to know the total number of instruments loaded into a
digital music file, read this field.
|
|
Field: | TotalPatterns |
Short: | The total number of patterns recorded in a digital music file. |
Type: | LONG |
Status: | Read |
If you would like to know the total number of patterns recorded in a
digital music file, read this field. A 'pattern' is a segment of recorded
music. Music files will usually consist of multiple patterns to assist
the musician in arranging the music.
If patterns are not used in a music object, a value of zero will be set
for this field.
|
|
Field: | Volume |
Short: | Determines the maximum volume allowed when playing a music object. |
Type: | LONG |
Status: | Get/Set |
The volume of a musical score is measured as a percentage in the range of
0 - 100%. A volume of zero will not be heard, while a volume of 100 is the
loudest possible value (with respect to the master volume setting).
This field can be set during playback for dynamic volume alteration.
|
|