Class Documentation

Name:Music
Version:1.0
ID:ID_MUSIC
Status:Beta
Category:Audio
Date:May 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1998-2003. All rights reserved.
Short:  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.
Action:Deactivate
Short: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.


Action:Reset
Short: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:

FlagDescription
LOOPIf set, the music player will loop back to the beginning when it reaches the end of a song.
ACTIVEReadable 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.