How MusicAPI tracks work

Important: It will be seen in the proceeding pages the terms Track and Music ID. Track refers to a MusicAPI Track data structure, while Music ID refers to the game's music IDs defined in the Music enum.

Track

The purpose of tracks:

• To store more information about how a music ID should be played
• To differentiate two game states that use the same music ID, such as Satan and Mega Satan
• To offer the ability to add more music IDs to a track, allowing for more variety in jingles and room music.

A MusicAPI track is a table stored in MusicAPI.Tracks, with IDs such as STAGE_CELLAR or BOSS_MOMS_HEART that stores one or more Music IDs, a MusicAPI Flagset, a "persistence" value, and a fade speed. The API uses these tracks for certain game states. For example, when the player enters a treasure room, the JINGLE_TREASURE_ROOM and the stage tracks are put into the MusicAPI queue.

In tracks.lua, JINGLE_TREASURE_ROOM is defined as follows:

["JINGLE_TREASURE_ROOM"] = {
	Music = {
		Music.MUSIC_JINGLE_TREASUREROOM_ENTRY_0,
		Music.MUSIC_JINGLE_TREASUREROOM_ENTRY_1,
		Music.MUSIC_JINGLE_TREASUREROOM_ENTRY_2,
		Music.MUSIC_JINGLE_TREASUREROOM_ENTRY_3
	},
	Flags = {"JINGLE"},
	Persistence = 1,
	FadeSpeed = 1,
},

• The Music key can either be a Music ID, or a table containing many Music IDs, as seen above. If multiple exist, a random one will be chosen apon the track being played.
• The Flags key contains tags that describe the track. When MusicAPI adds this track to MusicAPI.Tracks, the Flags table is converted into a MusicAPI.Flagset.
• The Persistence key determines whether this track should not be overridden by other tracks in certain circumstances.
  • nil = the track will act like normal.
  • 1 = If another track is played while this jingle is playing (say the player enters another room), and said track is the same as the one already queued, then the jingle will continue.
  • 2 = Any track that attempts to play while this jingle is playing will be queued after the jingle, rather than playing straight away. Used for the game start jingle.
• The FadeSpeed key determines how quickly the music fades in. If no value is given, it is assumed to be 0.08. Giving a value of 1 or more means it does not fade, and rather plays at full volume instantly.

To add your own track for use with MusicAPI, simply create a table like above (you may omit any of these keys, and a default value will be used), and use the MusicAPI.AddTrack(track_name, track_table) function to add it.

---

When the game wants to put a track in the queue, it will look to see if it has a music ID. If it doesn't, it will fallback to another track (what it falls back on is situation dependent). If it does, it will run it through OnTrack callbacks, and then finally add it.

Track names can be found here.