Music

Overview

This guide provides an overview of loading and playing music in AppGameKit Studio.

What formats are supported?

AppGameKit Studio uses the OGG compressed music format as its main standard for loading and playing music files. The format is compressed, has a high quality and the decoding of the music is done on a separate thread to avoid any performance issues. It's easy to convert your music tracks to OGG format with the many different sound file converters.

How do I load music?

The command LoadMusicOGG allows you to load a music track. Here are the available options:

LoadMusicOGG ( id, file )
id = LoadMusicOGG ( file )

void LoadMusicOGG ( UINT id, uString file );
UINT LoadMusicOGG ( uString file );

A music file can be loaded by either assigning an ID number manually or having it provided to you automatically. The next step is to let AppGameKit Studio know which file you want to load e.g. "myMusic.ogg". Please note that ID numbers are unique for a command set. Therefore it's feasible to have a music track loaded with an ID number of 1 and a sprite with an ID of 1. Music resources are limited, so only ID numbers betwen 0 - 50 are valid.

Here's one approach to loading a music track. The command LoadMusicOGG is called, an ID number of 1 is specified and the file to load is "myMusic.ogg":

LoadMusicOGG ( 1, "myMusic.ogg" )

agk::LoadMusicOGG ( 1, "myMusic.ogg" );

This alternative method demonstrates how a music track can be loaded with an automatically assigned ID number:

sound = LoadMusicOGG ( "myMusic.ogg" )

sound = agk::LoadMusicOGG ( "myMusic.ogg" );

How can I play music?

Once music has been loaded it can be played with the PlayMusic command. Several variants of this command exist:

PlayMusicOGG ( id )
PlayMusicOGG ( id, loop )

agk::PlayMusicOGG ( UINT id, int loop = 1 );

The parameters for this command are as follows:

• ID
• loop

The ID number refers to the ID of the music you want to play. The loop parameter controls whether the music will be looped. When this value is set to 0 the music track will play through once and then stop. When this value is set to 1 the playback will continually loop.

This example shows how to load and play music that will loop:

LoadMusicOGG ( 1, "myMusic.ogg" )
PlayMusicOGG ( 1, 1 )

agk::LoadMusicOGG ( 1, "myMusic.ogg" );
agk::PlayMusicOGG ( 1, 1 );

How do I stop music from playing?

To stop all music from playing call the StopMusic command. This command has no parameters. The following code loads music into ID 1, plays it with looping turned on and then stops the playback:

LoadMusicOGG ( 1, "myMusic.ogg" )
PlayMusicOGG ( 1, 1 )
StopMusicOGG ( )

agk::LoadMusicOGG ( 1, "myMusic.ogg" );
agk::PlayMusicOGG ( 1, 1 );
agk::StopMusicOGG ( );

How do I delete music?

It may be necessary to delete previously loaded music and free up available memory. To delete music call the command DeleteMusic:

DeleteMusicOGG ( id )

void DeleteMusicOGG ( UINT id );

This command only requires the ID number of the music you want to delete.

Here's an example of loading music and then deleting it:

LoadMusicOGG ( 1, "myMusic.ogg" )
DeleteMusicOGG ( 1 )

agk::LoadMusicOGG ( 1, "myMusic.ogg" );
agk::DeleteMusicOGG ( 1 );