General Commands - adambiser/agk-adlib-plugin GitHub Wiki

Init

Init(emulator as integer) as integer

emulator - The emulator to use.
1 = Nuked OPL3 emulator
2 = DOSBox emulator.
3 = Ken Silverman's emulator.
4 = Tatsuyuki Satoh's emulator.
5 = Dual OPL.

Initializes the OPL2 soft synth. This method should be called before attempting to do anything else with this plugin.

All emulators play as 16-bit stereo 44100 Hz sounds.

Returns: 1 on success; otherwise 0.

Update

Update()

Must be called each frame to ensure that the sound buffers are being loaded.

Shutdown

Shutdown()

Destroys the OPL2 soft synth and removes all songs. This is done when the plugin unloads and does not need to be explicitly called.

DeleteAllExternalData

DeleteAllExternalData()

Deletes all external data entries.

DeleteAllMusic

DeleteAllMusic()

Deletes all music managed by the plugin.

DeleteExternalData

DeleteExternalData(entryname as string)

entryname - The name of the entry to remove.

Deletes an external data entry.

DeleteMusic

DeleteMusic(songID as integer)

songID - The song ID to delete.

Deletes the song information and invalidates the ID.

GetMusicAuthor

GetMusicAuthor(songID as integer) as string

songID - The ID of the song.

Returns a song's author.

Returns: A string.

GetMusicDescription

GetMusicDescription(songID as integer) as string

songID - The ID of the song.

Returns the song's description.

Returns: A string.

GetMusicDuration

GetMusicDuration(songID as integer) as float

songID - The song ID.

Returns the duration of the song in seconds. This should not be called on a song while it is playing or the song will start again from the beginning.

Returns: Duration in seconds.

GetMusicExists

GetMusicExists(songID as integer) as integer

songID -

Checks the existence for the given song ID.

Returns: 1 if a song exists at the specified ID; otherwise 0.

GetMusicLoopCount

GetMusicLoopCount() as integer

Returns the number of times the current song has looped.

Returns: The loop count.

GetMusicPaused

GetMusicPaused() as integer

Returns whether music playback is paused.

Returns: 1 if paused; otherwise 0.

GetMusicPlaying

GetMusicPlaying() as integer

Returns whether the OPL synth is playing.

Returns: 1 if playing; otherwise 0.

GetMusicPosition

GetMusicPosition(songID as integer) as float

songID - The song ID.

Returns the current position in the music file in seconds, between 0 for the beginning of the song and GetMusicDuration for the end of the song. This position is only an approximation.

Returns: Position in seconds.

GetMusicRate

GetMusicRate(songID as integer) as integer

songID - The song ID.

Returns the song's playback rate.

Returns: The song's rate.

GetMusicSoundInstance

GetMusicSoundInstance() as integer

Returns the sound instance used for music playback. There should be no need to change the sound instance directly. Use the available plugin methods instead.

Returns: The sound instance ID.

GetMusicSubsong

GetMusicSubsong(songID as integer) as integer

songID - The ID of the song.

Returns the current subsong for a song.

Returns: A 0-based subsong index.

GetMusicSubsongCount

GetMusicSubsongCount(songID as integer) as integer

songID - The ID of the song.

Returns the number of subsongs in a song.

Returns: The number of subsongs in a song.

GetMusicSystemVolume

GetMusicSystemVolume() as integer

Returns the volume of the emulator.

Returns: An integer from 0 to 100.

GetMusicTitle

GetMusicTitle(songID as integer) as string

songID - The ID of the song.

Returns a song's title.

Returns: A string.

GetMusicType

GetMusicType(songID as integer) as string

songID - The ID of the song.

Returns a song's file type.

Returns: A string.

GetMusicVolume

GetMusicVolume(songID as integer) as integer

songID - The song ID.

Returns the volume of the given song ID.

Returns: An integer from 0 to 100.

LoadExternalDataFromFile

LoadExternalDataFromFile(filename as string)

filename - The file to load. This is used as the entry name internally.

Load external data required for some music file formats from a file. Will raise an error if an entry with this name already exists.

ie: The standard.bnk for ROL files.

LoadExternalDataFromFileEx

LoadExternalDataFromFileEx(filename as string, entryname as string)

filename - The file to load.

entryname - The name of the entry. Each music file format has its own naming convention.

Loads external data required for some music file formats from a file. Will raise an error if an entry with this name already exists.

ie: The standard.bnk for ROL files.

This is the same as LoadExternalDataFromFile, but allows the internal entry name to be set.

LoadExternalDataFromMemblock

LoadExternalDataFromMemblock(memblockID as integer, entryname as string)

memblockID - The memblock to load.

entryname - The name of the entry. Each music file format has its own naming convention.

Loads external data required for some music file formats from a memblock. Will raise an error if an entry with this name already exists.

An internal copy of the memblock is made. The memblock in the calling code can be deleted after calling this method.

ie: The standard.bnk for ROL files.

LoadMusicFromFile

LoadMusicFromFile(filename as string) as integer

filename - The name of the file to load.

Loads song information from the given file name.

Returns: The music ID of the loaded song or 0 if an error occurs.

LoadMusicFromMemblock

LoadMusicFromMemblock(memblockID as integer, filetype as string) as integer

memblockID - The memblock containing song information.

filetype - The file extension without the leading period indicating the type of data in the memblock.

Loads song information from the given memblock.

Returns: The music ID of the loaded song or 0 if an error occurs.

PauseMusic

PauseMusic()

Pauses music playback. GetMusicPlaying will continue to return 1.

PlayMusic

PlayMusic(songID as integer, loop as integer)

songID - The song ID to play.

loop - The number of times to loop, or 1 to loop forever.

Play the song ID.

PlaySound

PlaySound(songID as integer, subsong as integer)

songID - The song ID containing the subsong.

subsong - The subsong to play.

Plays a subsong as a sound effect. Some file formats, such as ADL files, contain many subsongs, some that are music and some that are sound effects. Sound effects can be played simultaneously with the songs.

If the given song is not currently playing, the plugin will change to the given song. The subsong will be played one time.

ResumeMusic

ResumeMusic()

Resumes music playback if it was paused.

SeekMusic

SeekMusic(songID as integer, seconds as float, mode as integer)

songID - The song ID.

seconds - The time in seconds to seek to.

mode - 0 for absolute seeking, 1 for relative seeking.

Seeks to a given time value within the song. If the song is currently playing, it will continue playing from the new position. If the song is not currently playing, it will take effect after the next call to PlayMusic.

If the song contains subsongs, this only affects the current subsong. Changing subsongs resets the seek position to the beginning.

SetMusicLoopCount

SetMusicLoopCount(loop as integer)

loop - The number of times to loop, or 1 to loop forever.

Changes the number of times the current song will loop. This resets the loop count to 0.

SetMusicSubsong

SetMusicSubsong(songID as integer, subsong as integer)

songID - The ID of the song.

subsong - The subsong index.

Sets the subsong for a song. This also resets the seek position for the song to 0.

If changing the subsong for the currently playing song, the subsong will immediately begin playing from the beginning.

SetMusicSystemVolume

SetMusicSystemVolume(volume as integer)

volume - A number between 0 and 100 inclusive.

Sets the volume of the emulator.

SetMusicVolume

SetMusicVolume(songID as integer, volume as integer)

songID - The ID of the song to change.

volume - A number between 0 and 100 inclusive.

Sets the volume for a song. By default, songs start with a volume of 100.

StopMusic

StopMusic()

Stops music playback.