# Sound

Playing and generating audio and sound effects

[Reference](index.md)

<a id="section-Guides"></a>

## Guides

<a id="Sound-in-Codea"></a>

### Sound in Codea

Use [`sound`](#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`:

```lua
-- 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:

```lua
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:

```lua
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`:

```lua
-- 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:

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

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

<a id="section-Sound"></a>

## Sound

<a id="sound"></a>

### sound

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

<a id="sound.play"></a>

### sound.play(preset, seed)

```lua
sound.play(preset, seed)
```

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

play a sound or procedural preset in 2D

#### 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**: 

<a id="sound.play-2"></a>

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

```lua
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

play a sound or procedural preset in 2D

#### 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**: 

<a id="sound.play-3"></a>

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

```lua
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

play a sound or procedural preset in 2D

#### 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.

<a id="sound.play3d"></a>

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

```lua
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

play a sound in 3D

#### 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**: 

<a id="sound.play3d-2"></a>

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

```lua
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

play a sound in 3D

#### 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**: 

<a id="sound.playBackground"></a>

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

```lua
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

play background audio

#### 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**: 

<a id="sound.playBackground-2"></a>

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

```lua
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

play background audio

#### 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**: 

<a id="sound.read"></a>

### sound.read(assetKey)

```lua
sound.read(assetKey)
```

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

Supported formats are - `wav`, `ogg`, `mp3`, `flac`

load a sound from an asset

#### Parameters

- **assetKey** (asset.key): Asset key identifying the audio file.

#### Returns

- **sound.source**: 

<a id="sound.generator"></a>

### sound.generator(table)

```lua
sound.generator(table)
```

create a procedural sound generator

#### Parameters

- **table** (table): SFXR generator settings table defining the procedural sound.

<a id="sound.source"></a>

### sound.source

```lua
sound.source
```

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

default playback volume

<a id="sound.source.volume"></a>

### sound.source.volume

```lua
sound.source.volume
```

Adjusts the default volume of sounds played with this sound source

default playback volume

<a id="sound.source.loop"></a>

### sound.source.loop

```lua
sound.source.loop
```

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

default looping state

<a id="sound.source.length"></a>

### sound.source.length

```lua
sound.source.length
```

Gets the length of this sound source (in seconds)

length of the sound in seconds

<a id="sound.instance"></a>

### sound.instance

```lua
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

current playback volume

<a id="sound.instance.volume"></a>

### sound.instance.volume

```lua
sound.instance.volume
```

Adjusts the volume of the sound instance

current playback volume

<a id="sound.instance.pitch"></a>

### sound.instance.pitch

```lua
sound.instance.pitch
```

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

current playback pitch

<a id="sound.instance.loop"></a>

### sound.instance.loop

```lua
sound.instance.loop
```

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

whether the sound loops

<a id="sound.instance.paused"></a>

### sound.instance.paused

```lua
sound.instance.paused
```

Set the paused state of the sound instance

whether the sound is paused

<a id="sound.instance.time"></a>

### sound.instance.time

```lua
sound.instance.time
```

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

current playback time

<a id="sound.instance:stop"></a>

### sound.instance:stop()

```lua
sound.instance:stop()
```

Stop the sound instance from playing

stop the sound

<a id="entry.SOUND_COIN"></a>

### SOUND_COIN

```lua
SOUND_COIN
```

Procedural coin sound preset (SFXR)

coin sound effect constant

<a id="entry.SOUND_LASER"></a>

### SOUND_LASER

```lua
SOUND_LASER
```

Procedural laser sound preset (SFXR)

laser sound effect constant

<a id="entry.SOUND_EXPLOSION"></a>

### SOUND_EXPLOSION

```lua
SOUND_EXPLOSION
```

Procedural explosion sound preset (SFXR)

explosion sound effect constant

<a id="entry.SOUND_POWERUP"></a>

### SOUND_POWERUP

```lua
SOUND_POWERUP
```

Procedural powerup sound preset (SFXR)

power-up sound effect constant

<a id="entry.SOUND_HURT"></a>

### SOUND_HURT

```lua
SOUND_HURT
```

Procedural hurt sound preset (SFXR)

hurt sound effect constant

<a id="entry.SOUND_JUMP"></a>

### SOUND_JUMP

```lua
SOUND_JUMP
```

Procedural jump sound preset (SFXR)

jump sound effect constant

<a id="entry.SOUND_BLIP"></a>

### SOUND_BLIP

```lua
SOUND_BLIP
```

Procedural blip sound preset (SFXR)

blip sound effect constant

<a id="section-Music"></a>

## Music

<a id="Playing-Background-Music"></a>

### Playing Background Music

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`.

```lua
-- 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)
```

<a id="music"></a>

### music(asset, loop, volume, pan)

```lua
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.

play a background music track

#### 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.

<a id="music-2"></a>

### music

<a id="music.stop"></a>

### music.stop()

```lua
music.stop()
```

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

stop the music track

<a id="music.volume"></a>

### music.volume

```lua
music.volume
```

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

playback volume from 0 to 1

<a id="music.pan"></a>

### music.pan

```lua
music.pan
```

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

stereo pan from -1 (left) to 1 (right)

<a id="music.currentTime"></a>

### music.currentTime

```lua
music.currentTime
```

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

playback position in seconds

<a id="music.paused"></a>

### music.paused

```lua
music.paused
```

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

whether a loaded track is not playing

<a id="music.muted"></a>

### music.muted

```lua
music.muted
```

Whether music is muted. Unmuting restores the saved volume.

whether music is muted

<a id="music.duration"></a>

### music.duration

```lua
music.duration
```

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

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

<a id="music.channels"></a>

### music.channels

```lua
music.channels
```

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

number of audio channels, or zero when no track is loaded

<a id="music.name"></a>

### music.name

```lua
music.name
```

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

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

<a id="section-Microphone"></a>

## Microphone

<a id="mic"></a>

### mic

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.

<a id="mic.start"></a>

### mic.start()

```lua
mic.start()
```

Start tracking input from the device microphone

start tracking the microphone

#### Example

```lua
function setup()
    mic.start()
end

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

<a id="mic.stop"></a>

### mic.stop()

```lua
mic.stop()
```

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

stop tracking the microphone

<a id="mic.amplitude"></a>

### mic.amplitude

```lua
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

volume of the microphone input

<a id="mic.frequency"></a>

### mic.frequency

```lua
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

pitch of the microphone input in hertz