Music

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

Plays a music pattern, or stops playing.

n

The pattern number to start playing (0-63), or -1 to stop playing music.

fadems

If not 0, fade in (or out) the music volume over a duration, given as a number of milliseconds.

channelmask

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 the 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 channels 0, 1, 2, and 3 are represented by the corresponding bits, with 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

-- 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
-- by setting bits 2 and 3, whose values are 4 and 8, totaling 12
music(4, 0, 12)

See also

• sfx()