Plays a music pattern, or stops playing.
- The pattern number to start playing (0-63), or -1 to stop playing music.
- If not 0, fade in (or out) the music volume over a duration, given as a number of milliseconds.
- A bitfield indicating which of the four sound channels should be reserved for music. The default is 0 (no channels reserved).
A music pattern describes a part of a song to play as background music. The pattern assigns sound effects to one or more of Pico-8's four sound channels, with instructions to proceed to the next pattern, loop, or end when the sounds end. Typically, sound effects associated with music patterns are a collection of notes played at the intended tempo.
A call to
music() can include a channel mask to declare which sound channels should not be interrupted by a sound effect played by a call to sfx(). The channel mask is a bitfield, where the four channels are represented by the bit values 1, 2, 4, and 8, respectively. A call to sfx() may still take over a channel reserved by the music pattern if it specifies an explicit channel number.
When using music and sound effects together, it is a good idea to set a channel mask that reserves some channels and leaves others open for effects. Pico-8 will prioritize the use of the unmasked channels for sound effects, giving both music and sound a chance to play.
It should be noted that it is only necessary to call
music() once, to trigger playback. PICO-8 will continue playback independently afterwards. It is not necessary to call it every frame with the current music ID--in fact, doing so will cause the track to be stuck on the first note perpetually, as the music restarts over and over.
-- start music from pattern 0 music(0) -- stop the music with a 300 ms fade out music(-1, 300) -- start music from pattern 4, reserving channels 2 and 3 (4 + 8) music(4, 0, 12)