music( n, [fadems,] [channelmask] )

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.

Examples Edit

-- start music from pattern 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)

See also Edit