Play a sound effect and return the channel used, or nil if the sound cannot be played. With no channel, this uses the first idle channel from 0 to 3. If all four are busy, it replaces the one that has been playing the longest, and it leaves a looping channel alone until every channel in the search is looping. Pass a channel number to pin that channel. Pass true to loop until stopAudio. start and end select a column range. end is not played. Omit them to play the whole sound.

• playSFX(sound) -> number|nil
• playSFX(sound, loop) -> number|nil
• playSFX(sound, channel) -> number|nil
• playSFX(sound, channel, loop) -> number|nil
• playSFX(sound, loop, start, [end]) -> number|nil
• playSFX(sound, channel, loop, start, [end]) -> number|nil

Parameters

• sound — Sound index (0-based) or the sound name from the Sound Editor, such as `Jump`.
• channel — Audio channel from 0 to 3. Replaces whatever is already playing there, including a loop.
• loop — When true, repeat until stopAudio. Pass true or false as the second argument to use any channel, or after the channel number to pin one. false plays once.
• start — 0-based column to start from. Notes that begin on an earlier column are skipped. Omit, along with end, to play from the first column.
• [end] — End column. This column is not played. Omit it to play through the last note. A call whose end is at or before start plays nothing and returns nil.

Returns

• number|nil — The channel used, from 0 to 3, or nil if the sound cannot be played.

Examples

-- Play sound 'Jump' on the first free channel.
playSFX("Jump")

-- Loop sound 'Alarm' on the first free channel.
playSFX("Alarm", true)

-- Play sound 'Alarm' on channel 2, replacing whatever is already there.
playSFX("Alarm", 2)

-- Loop sound 'Alarm' on channel 2.
playSFX("Alarm", 2, true)

-- Loop from column 16 until column 24 (24 is not played).
local ch = playSFX("Jump", true, 16, 24)

-- Play that same range once on channel 2.
playSFX("Jump", 2, false, 16, 24)

-- Stop that channel if it is still sounding.
if audioPlaying(ch) then
  stopAudio(ch)
end

Play a tune on its own channel. playTune(tune) loops: the intro plays once, then the marked section repeats until endTuneLooping, playTuneEnding, or stopAudio. Pass false to play the intro, the marked section once, and then the ending. Pass a number to repeat the marked section that many times. That number is a loop count, not a start column. Pass start and end to play those columns once, including end, and ignore the saved intro, loop, and ending. If a tune is already playing, the new one crossfades in over 4 columns.

• playTune(tune) -> void
• playTune(tune, loop) -> void
• playTune(tune, times) -> void
• playTune(tune, start, end) -> void

Parameters

• tune — Tune index (0-based) or the tune name from the Sound Editor. Tune 0 is not sound effect 0.
• loop — true loops the marked section after the intro. false plays the intro, the marked section once, and then the ending. Omitting it is the same as true.
• times — How many times to play the marked section. This is a loop count, not a start column. 1 matches false. The intro plays once, then the ending plays after the last repeat.
• start — 0-based column. Together with end, plays that range once and ignores the saved intro, loop, and ending.
• end — Last column to play. This column is included.

Returns

• void — Nothing. tunePlaying() is true while the tune is sounding.

Examples

-- Loop the tune 'Theme': the intro plays once, then the marked section repeats.
playTune("Theme")

-- Play the intro, the marked section once, then the ending.
playTune("Theme", false)

-- Play the intro, repeat the marked section 16 times, then the ending.
-- The number is a loop count, not a start column.
playTune("Theme", 16)

-- Play columns 0 through 32 once, including column 32.
playTune("Theme", 0, 32)

Leave the loop and play the ending at full volume. During the intro, the intro finishes, the marked section plays once, and then the ending plays. During the loop, playback continues to the red marker and then the ending plays. During the ending, this does nothing. If there is no ending, playback stops at the red marker.

• endTuneLooping() -> void

Returns

• void — Nothing.

Examples

-- Finish the current loop, then play the ending.
endTuneLooping()

Fade out wherever the tune is and fade in the ending. The default fade is 4 columns, one beat. Pass a column count to set that length. If nothing is playing, the ending fades in from silence. If there is no ending, the tune fades out and stops.

• playTuneEnding() -> void
• playTuneEnding(steps) -> void

Parameters

• [steps] — Crossfade length in columns. The default is 4, which is one beat.

Returns

• void — Nothing.

Examples

-- Fade out over one beat and fade in the ending.
playTuneEnding()

-- Use an 8-column crossfade.
playTuneEnding(8)

Return true while the tune is sounding, including the intro, the loop, and the ending.

• tunePlaying() -> bool

Returns

• bool — True while the tune is sounding, otherwise false.

Examples

-- Stop everything, including the tune, when the tune is still sounding.
if tunePlaying() then
  stopAudio()
end

Return true while that channel is still sounding, including rests inside the sound and a loop that has not been stopped. Return false when the channel is idle or the number is outside 0 to 3.

• audioPlaying(channel) -> bool

Parameters

• channel — Audio channel from 0 to 3. Replaces whatever is already playing there, including a loop.

Returns

• bool — True while the channel is still sounding, otherwise false.

Examples

-- True while channel 0 is still playing, including a loop.
if audioPlaying(0) then
  stopAudio(0)
end

Deprecated. Use playTune for a tune from the Sound Editor. playMusic still starts an older music pattern. Pass a fade length in frames to fade it in, and a channel mask to choose which music channels play.

• playMusic(musicIndex) -> void
• playMusic(musicIndex, fadeLength) -> void
• playMusic(musicIndex, fadeLength, channelMask) -> void

Parameters

• musicIndex — Which music pattern to play.
• fadeLength — Fade time in frames.
• channelMask — Which music channels are on.

Returns

• void — No return value.

Examples

-- Start music pattern 0 straight away.
playMusic(0)

-- Fade music pattern 0 in over 30 frames.
playMusic(0, 30)

-- Fade pattern 0 in over 30 frames, using channel mask 1.
playMusic(0, 30, 1)

Stop the tune and every sound effect immediately. Pass a channel from 0 to 3 to stop only that effect channel. A channel number does not stop the tune.

• stopAudio() -> void
• stopAudio(channel) -> void

Parameters

• channel — Audio channel from 0 to 3. Replaces whatever is already playing there, including a loop.

Returns

• void — No return value.

Examples

-- Stop every sound and the music.
stopAudio()

-- Stop only channel 2.
stopAudio(2)