Soundtrack Manager for RPG Maker MV and MZ

This plugin allows you a greater variety of control with your BGM tracks in RPG Maker MV. Play from a set point, change the loop parameters, cross-fade between tracks, load them ahead of time to cancel out the usual delay, and it includes an updated version of the Variable Mix plugin!

The instructions below are for the MV version of this plugin. MZ uses the same basic parameters, but streamlined into MZ's plugin features.

Loading a track

Plugin command:
 LoadBGM nameOfTrack parameter=value parameter=value ...

This command loads a BGM track into memory. If not loaded, PlayBGM will not work. Loading takes a second or two, so make sure to load it before you need it.

"nameOfTrack" is the file name of the track in your audio\bgm folder. Do not include the extension. Names cannot contain spaces, so you should_use_underscores OrCamelCase when naming tracks.

Loaded tracks are saved to the game's save file, and will be automatically  re-loaded when the save file is loaded.

All parameters are optional. They are separated by spaces, but cannot contain any spaces within them (including before and after = signs). Valid parameters are:

alias=thisTracksAlias

If you give a track an alias, you can refer to it by that alias in the future when playing back or clearing it. This also allows you to create multiple instances of a single track with different parameters.

 The default alias is the same as the name of the track.  No two loaded tracks can have the same alias. If you try to load another track with the same alias, the first will be unloaded and replaced by the second.

volume=50

Sets the volume of the track. Works the same as the default editor, but allows for more values. Default is 100.

pan=10

Sets the left/right pan of the track. Works the same as the default editor, but allows for more values. Default is 0.

pitch=125

Sets the pitch of the track. Works the same as the default editor, but allows for more values. Default is 100.

Please note that the built-in AudioManager sometimes behaves oddly with pitch values other than 100, and it might prevent variable mix from working, or user-defined starting points from being used.

tempoRatio=120/160

Used for variable mix tracks. One track must be considered the "default" tempo, and all others must be defined as ratios of the default tempo over the other tracks'. For example, if the "default" is 180 beats per minute, and you want to load a track with a tempo of 144 beats per minute, then the tempoRatio of the second track should be 180/144 (or 5/4). Ignored when not played as a variable mix. Accepts fractions and decimals. Default is 1.0.

loopstart=12345

Overrides the track's LOOPSTART metadata. If not included, the standard LOOPSTART will be used. Use sample number as you would in LOOPSTART.

looplength=23456

Overrides the track's LOOPLENGTH metadata. If not included, the standard LOOPLENGTH will be used. Use sample number as you would in LOOPLENGTH.

playFrom=5432

Starts playback at the sample number included. Ignored for variable mix playback, or when playing another instance of the same track (forceFromStart in the PlayBGM command can force it to start from this point anyway.) Default is 0.

sampleRate=56789

You usually won't need this. This is only useful if the file is not a normal OGG file and the sample rate is something other than the standard 44.1kHz. But otherwise, put the sample rate in Hz here to properly calculate loop points and "playFrom" settings.

Loop points and "playFrom" use sample numbers; use them even if you're not using a standard OGG file (it may be useful to have an OGG file on hand to refer to.)

Playing a track

Plugin command:
PlayBGM trackAlias [parameter=value] [parameter=value] ...

Plays a loaded BGM from its alias. If the given BGM was not loaded, this command will do nothing.

Some parameters from loading can be overridden by the play command. Notably, pitch is not one of them (it has inconsistent behavior), so if you want to play the track at a different pitch, set it with the load command.

"trackAlias" is the name or alias of the track that was loaded. If an alias was provided, it must be used here; using the name of the track won't work.

Since loading tracks takes time, if given enough load time before calling PlayBGM, the tracks will start significantly sooner than they would otherwise.

All parameters are optional. They are separated by spaces, but cannot contain any spaces within them (including before and after = signs). Valid parameters are:

volume=70

Overrides the volume setting.

pan=-5

Overrides the pan setting.

loopstart=5432

Overrides both the LOOPSTART setting in the track's metadata and the loopstart setting in the LoadBGM command.

looplength=6543

Overrides both the LOOPLENGTH setting in the track's metadata and the looplength setting in the LoadBGM command.

playfrom=787878

Starts playback at the sample number included. Ignored for variable mix playback, or when playing another instance of the same track when forceFromStart is not set. Overrides any value given in the LoadBGM command.

variable (or variablemix or continue)

When set, the track starts from a point relative to the current playback position of the current track. Used for allowing the music to flow cleanly between related tracks. When the tracks have defined tempoRatio values, it calculates the starting point based on the ratio of their tempos; otherwise, it starts from the same sample number. Automatically sets crossFade, but the "instant" parameter can cancel that.

crossFade

When set, the currently-playing track will fade out and the new track will fade in simultaneously. If there is no track currently playing, there will not be any fade-in unless the fadeIn parameter is set. You cannot use cross-fading between two tracks with the same alias (but you can use it between two instances of the same track with different aliases); if you try, it will be ignored.

fadeIn

When set, and when cross-fading is not set or does not apply, the track will fade in as it starts playing. There is no fadeOut command, because the standard RPG Maker command works fine.

instant

Cancels the automatic application of crossFade from variable mix tracks.

fadeTime=1.5

Sets how long, in seconds, cross-fading and fadeIn commands take. Allows decimals. Default is 1.0.

forceFromStart

Normally, when a new "Play BGM" command is played using the same track as what is presently playing, it continues playback from the same point. "forceFromStart" changes this behavior, so it will always start from the beginning of the track (or the "playFrom" point). Ignored for variable tracks, and meaningless when the currently-playing track is not the same as the track being played.

Clearing a track

Plugin command:
ClearBGM trackAlias

Too many tracks loaded into memory at once will slow the game and may even crash it. Though I've found that a decent-quality PC can keep literally hundreds of BGM tracks loaded simultaneously, best not to push it - especially if you're aiming to create a mobile game! 

If you provide an alias to the command, it will clear that track from memory (if it hasn't been loaded, nothing will happen.) If you don't, all tracks will be cleared from memory at once. This will not affect any tracks currently playing; they won't be able to be called with PlayBGM any more, but they'll continue playing.

Other things to note

If you play the same track that is currently playing with different loop settings, without forceFromStart, it will work fine and continue playing with the new loop settings, which can be used for helping sync scenes with the action in the game... just so long as the new end of the loop is after the sample that is currently playing. If it is before, the track will jump back to a point inside the new loop, which may sound jarring and should probably be avoided (it won't hurt anything, though.)

Any loaded track whose alias is the same as its track name will be played as though run through PlayBGM if played through any normal playback methods, allowing you to use some of the features for automatic playback situations (like battles or riding vehicles.)