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 Your Mom'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 bield, 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.

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