GMSync Documentation

Quick start

The simplest possible example of using GMSync would look something like this:

First we play the audio we're going to sync to. Then we use sync_init() to setup data related to our track. The first argument is the BPM for the track, and the second argument is the delay until the first musical element of the song occurs, in seconds. This is only needed if your music track doesn't begin the moment you play it. This isn't common for game development, but if for some reason your track has some empty space in the front then you can use this value to account for that. Be sure that your delay is in seconds, with up to three decimal places for milliseconds for the best timing.

When you run sync_init(), it does a few calculations to determine the length of various note values with your given BPM. The overhead of pre-calculating these values should be fairly small, but if you have a large number of music tracks you're planning to set up syncing with, it might be worth doing all of your sync_init() calls at the start of your game and storing the values in a global variable of some kind. If more than one song have the same BPM and delay, you can use that sync information for each of those tracks.

After things have been setup with sync_init() and your audio is playing, you'll want to run sync_check() every step of your game. The first argument is the sync information returned by sync_init(), and the second argument is the sound id of the playing audio. The final argument is the note value you want to check for. This will be an enum of type SyncNote or SyncNoteTriplet. sync_check() will return true if the current frame of the game lines up with the given note value in the song.

Patterns

There may be times where you want to sync an element of your game to a more detailed sequence of notes, rather than just checking for specific note values. An example of where this might be useful is if a part of your song has a drum fill that you want to react to. To setup syncing to patterns like this you can set things up like this:

The setup is similar to using sync_check() to check for individual notes, but this time we setup an array of notes to check for. Once the first note happens (as indicated by the first_note_time variable in the example) then sync_pattern_check() will check each note in the pattern array in order from then on.

Time check

If you want to check if the song is at an arbitrary timestamp (in seconds) you can use sync_check_time() like this:

This works just like sync_check(), but the last argument is the timestamp you want to check. This is useful if there's a specific point in your music that you want to react to. This method is gamespeed independant, making it more reliable than using audio_sound_get_track_position().

Caveats

It should be noted that there may be times where sync_check() will return true more than one frame in a row, depending on your FPS and the BPM of the track. Another important note is that the GMSync system will not work if you change your game's FPS after running sync_init(). This is due to how timing calculations are done to account for frame speed.

Along the same lines, if your music changes tempo at any point, GMSync will not work. To work with songs that have a variable BPM, you'll have to use sync_init() with each different BPM, making the delay equal to when that BPM begins.