Song class

Sequences and plays synthesized or sampled music files.

Methods

Constructor()

Create a new Song object.

function GetInstrumentCallback()

Return the currently registered callback function.

function GetOrderCallback()

Return the currently registered callback function.

function GetRowCallback()

Return the currently registered callback function.

function GetZxxCallback()

Return the currently registered callback function.

bool IsFinished()

Return if the song has finished playing at least once, even if it is looping.

bool IsPaused()

Return if the song is currently paused or not.

bool IsPlaying()

Return if the song is in the midst of playing or not. A song that is paused is still considered playing.

Pause()

Pause a currently playing song.

Play()

Play a currently stopped song from the beginning. Resume a paused song.

SetInstrumentCallback(function func, list inst_nums)

Registers a function to be called when the specified instruments play a note in this song. The inst_nums parameter must contain integers in the range (0,255) representing the instrument numbers. The callback function must follow this prototype:

OnInstrumentSong(Song, int)

where the first argument is the playing song and the second is the number of the instrument currently sounding.

Only works for sampled music files, not MIDIs.

SetOrderCallback(function func, int order_step)

Registers a function to be called every order_step orders in the song. The callback function must follow this prototype:

OnOrderSong(Song, int)

where the first argument is the playing song and the second is the current order number.

Only works for sampled music files, not MIDIs.

SetRowCallback(function func, int row_step)

Registers a function to be called every row_step rows in the song. The callback function must follow this prototype:

OnRowSong(Song, int)

where the first argument is the playing song and the second is the current row number.

Only works for sampled music files, not MIDIs.

SetZxxCallback(function)

Registers a function to be called whenever a Zxx command is encountered in the song. The callback function must follow this prototype:

OnOrderSong(Song, int)

where the first argument is the playing song and the second is the command value.

Only works for sampled music files, not MIDIs.

Stop()

Stop a currently playing or paused song.

Properties

int BPM (read)

The tempo of the song in beats per minute. Only works for sampled music files, not MIDIs.

float CurrentTime (read)

The current position in seconds of the playing song.

bool Looping (write)

The flag indicating whether the song loops or not.

string Name (read)

The name of the song.

int NumChannels (read)

The number of channels in a sampled song.

int NumInstruments (read)

The number of instruments in a sampled song.

int NumOrders (read)

The number of orders in a sampled song.

int NumPatterns (read)

The number of patterns in a sampled song.

int NumSamples (read)

The number of samples (patches) in a sampled song.

int Order (read/write)

The current order in a playing song. The song must be playing before this value can be set. Only works for sampled songs, not MIDIs. Only works for sampled songs, not MIDIs.

float PanSeparation (write)

The pan separation of stereo songs. Values range from 1.0 (full separation) to 0.0 (mono).

int Pattern (read)

The current pattern in a playing song. Only works for sampled songs, not MIDIs.

bool Reverb (write)

The flag indicating if reverb is enabled for MIDI songs or not.

int Row (read)

The current row in a playing song. Only works for sampled songs, not MIDIs.

int Speed (read)

The current speed of the song. Only works for sampled songs, not MIDIs.

int UserSpeed (write)

The factor by which the speed of a song is scaled. Values range from 0.0 (stopped) to 10.0, a 10x scaling of the default song speed. The default value is 1.0, or normal speed.

int Volume (read/write)

The master volume of the song. Values range from 0 to 255.