Codea icon Sound

Reference › Playing and generating audio and sound effects

Guides

Sound in Codea top ↑

Overview

Use sound to play music and audio files or create your own sound effects.

Playing Audio Files

Play a file from the project or built-in assets with sound.play:

-- Play a built-in sound
sound.play(asset.builtin.A_Spaceship.Laser_Shoot)

-- Play a project sound and control it
local src = sound.play(asset .. "music.mp3", { loop = true, volume = 0.5 })

sound.play returns a sound.source that lets you control the audio after it starts:

local src = sound.play(asset .. "music.mp3", { loop = true })

-- Pause and resume
src:pause()
src:play()

-- Adjust volume and pitch at runtime
src.volume = 0.3
src.pitch = 1.2

-- Stop completely
src:stop()

Loading vs Playing

For sounds you play frequently (like a gun shot), load the source once in setup() and call play() on it:

function setup()
    shootSound = sound.load(asset.builtin.A_Spaceship.Laser_Shoot)
end

function draw()
    if input.key.space then
        shootSound:play()
    end
end

Loading once avoids decoding the same audio each time you play it.

Procedural Sound

Create a sound effect without an audio file using sound.synthesize:

-- A retro blip sound
local blip = sound.synthesize({
    wave = SINE,
    startFreq = 440,
    endFreq = 880,
    sustainTime = 0.1,
    decayTime = 0.05,
    volume = 0.8
})
blip:play()

Parameters let you shape the sound’s frequency envelope, waveform, and timing.

Background Music

For longer music tracks, use sound.play with { loop = true }. Keep a reference to stop or fade it:

function setup()
    music = sound.play(asset .. "background.mp3", { loop = true, volume = 0.4 })
end

function cleanup()
    if music then
        music:stop()
    end
end

Sound

sound top ↑

Module

The sound module provides a way to play and manage sound effects and background music

sound.play(preset, seed)

Static Method

Syntax

sound.play(preset, seed)

Plays a preset procedural SFXR sound effect using a given preset and optional seed

Parameters

preset integer.

Procedural sound preset constant, such as SOUND_COIN.
seed integer, optional.

Random seed used to generate a repeatable variation of the preset.

Returns

sound.instance

sound.play(source, volume, pitch, pan, paused)

Static Method

Syntax

sound.play(source, volume, pitch, pan, paused)

Plays a sound.source in 2D, returning an active sound.instance object that can be adjusted, paused/resumed and stopped

Parameters

source sound.source.

Loaded or generated sound to play.
volume number, optional, default 1.

Playback gain; 1 is the original volume and 0 is silent.
pitch number, optional, default 1.

Playback rate multiplier; 1 is the original pitch and speed.
pan number, optional, default 0.

Stereo position from -1 (left) to 1 (right), with 0 centered.
paused boolean, optional, default false.

Whether playback starts paused; defaults to false.

Returns

sound.instance

sound.play(assetKey, volume, pitch, pan, paused)

Static Method

Syntax

sound.play(assetKey, volume, pitch, pan, paused)

Plays a sound using an asset key in 2D, returning an active sound.instance object that can be adjusted, paused/resumed and stopped

Parameters

assetKey asset.key.

Asset key identifying the audio file.
volume number, optional, default 1.

Playback gain; 1 is the original volume and 0 is silent.
pitch number, optional, default 1.

Playback rate multiplier; 1 is the original pitch and speed.
pan number, optional, default 0.

Stereo position from -1 (left) to 1 (right), with 0 centered.
paused boolean, optional, default false.

Whether playback starts paused; defaults to false.

sound.play3d(source, volume, pitch, paused)

Static Method

Syntax

sound.play3d(source, volume, pitch, paused)

Plays a sound.source in 3D, returning an active sound.instance object that can be adjusted, paused/resumed and stopped

Parameters

source sound.source.

Loaded or generated sound to play.
volume number, optional, default 1.

Playback gain; 1 is the original volume and 0 is silent.
pitch number, optional, default 1.

Playback rate multiplier; 1 is the original pitch and speed.
paused boolean, optional, default false.

Whether playback starts paused; defaults to false.

Returns

sound.instance

sound.play3d(assetKey, volume, pitch, paused)

Static Method

Syntax

sound.play3d(assetKey, volume, pitch, paused)

Plays a sound using an asset key in 3D, returning an active sound.instance object that can be adjusted, paused/resumed and stopped

Parameters

assetKey asset.key.

Asset key identifying the audio file.
volume number, optional, default 1.

Playback gain; 1 is the original volume and 0 is silent.
pitch number, optional, default 1.

Playback rate multiplier; 1 is the original pitch and speed.
paused boolean, optional, default false.

Whether playback starts paused; defaults to false.

Returns

sound.instance

sound.playBackground(source, volume, pitch, paused)

Static Method

Syntax

sound.playBackground(source, volume, pitch, paused)

Plays a sound.source in the background (no spatialisation), returning an active sound.instance object that can be adjusted, paused/resumed and stopped

Parameters

source sound.source.

Loaded or generated sound to play.
volume number, optional, default 1.

Playback gain; 1 is the original volume and 0 is silent.
pitch number, optional, default 1.

Playback rate multiplier; 1 is the original pitch and speed.
paused boolean, optional, default false.

Whether playback starts paused; defaults to false.

Returns

sound.instance

sound.playBackground(assetKey, volume, pitch, paused)

Static Method

Syntax

sound.playBackground(assetKey, volume, pitch, paused)

Plays an asset.key in the background (no spatialisation), returning an active sound.instance object that can be adjusted, paused/resumed and stopped

Parameters

assetKey asset.key.

Asset key identifying the audio file.
volume number, optional, default 1.

Playback gain; 1 is the original volume and 0 is silent.
pitch number, optional, default 1.

Playback rate multiplier; 1 is the original pitch and speed.
paused boolean, optional, default false.

Whether playback starts paused; defaults to false.

Returns

sound.instance

sound.read(assetKey)

Static Method

Syntax

sound.read(assetKey)

Reads a sound.source using an asset.key from the filesystem

Supported formats are - wav, ogg, mp3, flac

Parameters

assetKey asset.key.

Asset key identifying the audio file.

Returns

sound.source

sound.generator(table)

Static Method

Syntax

sound.generator(table)

Parameters

table table.

SFXR generator settings table defining the procedural sound.

sound.source

Type

Syntax

sound.source

A source of sound data to be used with sound.play

sound.source.volume

Property

Syntax

sound.source.volume

Adjusts the default volume of sounds played with this sound source

sound.source.loop

Property

Syntax

sound.source.loop

Adjusts the default looping state of sounds played with this sound source

sound.source.length

Property

Syntax

sound.source.length

Gets the length of this sound source (in seconds)

sound.instance

Type

Syntax

sound.instance

An instance of a playing sound from sound.play and associated methods

Sound instances can be used to monitor and adjust sounds while playing

sound.instance.volume

Property

Syntax

sound.instance.volume

Adjusts the volume of the sound instance

sound.instance.pitch

Property

Syntax

sound.instance.pitch

Adjusts the pitch of the sounds (increases/decreases play speed)

sound.instance.loop

Property

Syntax

sound.instance.loop

The looping state of the sound instance. When set to true the sound instance will continuously loop

sound.instance.paused

Property

Syntax

sound.instance.paused

Set the paused state of the sound instance

sound.instance.time

Property

Syntax

sound.instance.time

Get/set the current time of the sound instances play head (in seconds)

sound.instance:stop()

Method

Syntax

sound.instance:stop()

Stop the sound instance from playing

SOUND_COIN top ↑

Property

Syntax

SOUND_COIN

Procedural coin sound preset (SFXR)

SOUND_LASER top ↑

Property

Syntax

SOUND_LASER

Procedural laser sound preset (SFXR)

SOUND_EXPLOSION top ↑

Property

Syntax

SOUND_EXPLOSION

Procedural explosion sound preset (SFXR)

SOUND_POWERUP top ↑

Property

Syntax

SOUND_POWERUP

Procedural powerup sound preset (SFXR)

SOUND_HURT top ↑

Property

Syntax

SOUND_HURT

Procedural hurt sound preset (SFXR)

SOUND_JUMP top ↑

Property

Syntax

SOUND_JUMP

Procedural jump sound preset (SFXR)

SOUND_BLIP top ↑

Property

Syntax

SOUND_BLIP

Procedural blip sound preset (SFXR)

Music

Playing Background Music top ↑

Overview

Use music for one background track. Starting another track replaces it. Use sound.play for overlapping effects or independently controlled sounds. Choose an audio asset with the asset picker and pass its key to music.

-- Replace the key with an audio asset from your project.
music(asset .. "Theme.m4a", true, 0.5)
parameter.boolean("Paused", false, function(value)
    music.paused = value
end)

music(asset, loop, volume, pan) top ↑

Function

Syntax

music(asset, loop, volume, pan)

Starts playing an audio asset. Defaults are no looping, full volume, and centered pan. Calling it without an asset does nothing; use music.stop() to stop playback. A failed load reports a warning.

Parameters

asset asset.key or string.

Audio asset key, or a resolved local file path.
loop boolean, optional.

Whether to repeat the track indefinitely, default false.
volume number, optional.

Playback volume from 0 to 1, default 1.
pan number, optional.

Stereo pan from -1 (left) to 1 (right), default 0.

music top ↑

Module

music.stop()

Function

Syntax

music.stop()

Stops the current track and releases it. music.name becomes nil.

music.volume

Property

Syntax

music.volume

Playback volume from 0 to 1. While muted, setting it updates the volume restored on unmute.

music.pan

Property

Syntax

music.pan

Stereo pan from -1 (left) to 1 (right).

music.currentTime

Property

Syntax

music.currentTime

Playback position in seconds. Set it to seek within the track.

music.paused

Property

Syntax

music.paused

Whether a loaded track is not playing. Set true to pause and false to resume.

music.muted

Property

Syntax

music.muted

Whether music is muted. Unmuting restores the saved volume.

music.duration

Property

Syntax

music.duration

Track duration in seconds, or zero when no track is loaded.

music.channels

Property

Syntax

music.channels

Number of audio channels, or zero when no track is loaded.

music.name

Property

Syntax

music.name

Asset name or path of the loaded track, or nil when none is loaded.

Microphone

mic top ↑

Module

Tracks the volume and pitch of sound coming into the device microphone.

The first call to mic.start asks the user for permission to use the microphone. While the microphone is running, other sounds keep playing through the speaker.

mic.start()

Function

Syntax

mic.start()

Start tracking input from the device microphone

function setup()
    mic.start()
end

function draw()
    background(40)
    text(string.format("%.2f Hz", mic.frequency), WIDTH/2, HEIGHT/2)
end

mic.stop()

Function

Syntax

mic.stop()

Stop tracking input from the device microphone. The microphone also stops automatically when the project exits

mic.amplitude

Property

Syntax

mic.amplitude

The volume of sound coming into the microphone. Silence is close to 0, and a loud, full-scale sound reaches about 2

Returns 0 when the microphone is not running

mic.frequency

Property

Syntax

mic.frequency

The pitch of sound coming into the microphone, in hertz. Keeps its last value when the input goes quiet or has no clear pitch

Returns 0 when the microphone is not running