Sounds

Reference ❯ Playing and Sound and Music

Music

music( asset ) top ↑

Syntax

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

Calling this function immediately plays the music track specified by asset. The loop parameter controls whether the music track plays continuously, or stops when finished.

Only one music track can be played at a time. You can modify the currently playing music track by accessing elements of the music table, such as music.volume.

Do not call this function repeatedly in your draw loop. The music function is intended to be called once each time you wish to start playing music, or when you wish to change music tracks.

asset

asset key, the asset key of the music track to play

loop

boolean, specifies whether this track should continue playing in a loop

volume

number, the initial volume of playback from 0.0 to 1.0

pan

number, the stereo panning of playback, from -1.0 to 1.0

Examples

-- play a music track music( asset.builtin.A_Hero_s_Quest.Battle )
-- play a looping music track music( asset.builtin.A_Hero_s_Quest.Battle, true )
-- play a track and control the volume -- with a parameter music( asset.builtin.A_Hero_s_Quest.Battle, true ) parameter.number( "Volume", 0, 1, 1, function(val) music.volume = val end

music.volume top ↑

Syntax

-- Getting
vol = music.volume

-- Setting
music.volume = 0.5

This variable controls the currently playing music track's volume. It ranges from 0.0 to 1.0.

Returns

Volume of the currently playing music track

music.pan top ↑

Syntax

-- Getting
pan = music.pan

-- Setting
music.pan = -1.0

This variable controls the currently playing music track's stereo panning. It ranges from -1.0 to 1.0.

Returns

Panning amount of the currently playing music track

music.currentTime top ↑

Syntax

-- Getting
time = music.currentTime

-- Setting
music.currentTime = music.duration * 0.5

This variable controls the seek position of the currently playing music track. It ranges from 0.0 (start of the track) to music.duration (end of the track).

Returns

Current time into the playing music track

music.paused top ↑

Syntax

-- Getting
isPaused = music.paused

-- Setting
music.paused = true

This variable sets the paused state of the current music track.

Returns

Paused state of the currently music track.

music.muted top ↑

Syntax

-- Getting
muted = music.muted

-- Setting
music.muted = true

This variable controls whether the music track is currently muted.

Returns

Whether the current track is muted

music.duration top ↑

Syntax

duration = music.duration

Read only. This variable returns the length of the current music track in seconds.

Returns

Length of the current music track in seconds.

music.channels top ↑

Syntax

channels = music.channels

Read only. This variable returns the number of channels supported by the current track (usually 1 or 2).

Returns

Number of channels supported by the current track.

music.name top ↑

Syntax

print( music.name )

Read only. This value returns the asset string of the currently playing music.

Returns

Asset string of current music track

music.stop() top ↑

Syntax

music.stop()

Stops the currently playing music track.

Sounds

sound( name ) top ↑

Syntax

-- For sound assets
sound( name, volume )
sound( name, volume, pitch )
sound( name, volume, pitch, pan )
sound( name, volume, pitch, pan, loop )

-- For generated sounds
sound( name )
sound( name, seed )
sound( parameterTable )
sound( buffer )

Calling this function immediately plays a sound effect, or a randomly generated sound with a type specified by name or encoded with the given parameters.

If using a sound asset (a sound from an asset pack) the sound function accepts the following optional parameters: volume, pitch, pan and loop. Please see the parameter table for an explanation of these.

sound() can use sfxr to randomly generate sounds of a given type. The name parameter is a string specifying the type of sound (see related items), and the seed parameter allows you to choose a particular random sound. Sounds with the same name and seed always sound the same. If no seed is specified the resulting sound will be a random sound of the specified type. If a parameterTable is passed in, those values are used to generate the sound.

Do not call this function repeatedly in your draw loop. The sound function is intended to be called when you wish to play a sound effect (on a game event such as the player getting hit).

name

asset, the sound effect asset or type of sound to play

This can be an asset name, such as asset.builtin.A_Hero_s_Quest.Arrow_Shoot_1 or it can be used to specify a randomly generated sound effect from the following: SOUND_BLIT, SOUND_EXPLODE, SOUND_HIT, SOUND_JUMP, SOUND_PICKUP, SOUND_POWERUP, SOUND_RANDOM or SOUND_SHOOT.

Can also be DATA followed by a base64 string encoding the parameters which is generated by Codea based on the sound picker panel properties and should not be edited

volume

number, specifies the volume of the sound effect from 0.0 to 1.0 (only for sounds from an asset pack)

pitch

number, specifies the pitch of the sound effect, where 1.0 is the normal pitch (only for sounds from an asset pack)

pan

number, specifies the stereo panning of the sound effect from -1.0 to 1.0 (only for sounds from an asset pack)

loop

boolean, specifies whether this sound effect plays on a loop (only for sounds from an asset pack)

seed

int, specifies the random seed to use when generating a sound of this type

buffer

soundbuffer, specifies the raw sound data to play

parameterTable

table, specifies the parameters to use when generating a sound. This is an advanced option, the parameters will change the noise in subtle ways. Play with the Sounds Plus example app to see what these parameters do. Any missing keys will cause the sound to use a default value for that parameter

The table can contain the following (case sensitive) keys:

Waveform - The synthesizer waveform to use, can be SOUND_NOISE, SOUND_SAWTOOTH, SOUND_SINEWAVE, or SOUND_SQUAREWAVE

AttackTime - number

SustainTime - number

SustainPunch - number

DecayTime - number

StartFrequency - number

MinimumFrequency - number

Slide - number

DeltaSlide - number

VibratoDepth - number

VibratoSpeed - number

ChangeAmount - number

ChangeSpeed - number

SquareDuty - number

DutySweep - number

RepeatSpeed - number

PhaserSweep - number

LowPassFilterCutoff - number

LowPassFilterCutoffSweep - number

LowPassFilterResonance - number

HighPassFilterCutoff - number

HighPassFilterCutoffSweep - number

Volume - number

Examples

-- play some sound assets sound( asset.builtin.A_Hero_s_Quest.Arrow_Shoot_1 ) -- At half volume sound( asset.builtin.A_Hero_s_Quest.Arrow_Shoot_1, 0.5 ) -- Looping sound( asset.builtin.A_Hero_s_Quest.Arrow_Shoot_1, 1.0, 1.0, 0.0, true )
-- play a random jump sound sound( SOUND_JUMP ) -- play a specific jump sound sound( SOUND_JUMP, 1234 )
-- using the table to define properties sound( { Waveform = SOUND_NOISE, AttackTime = 1.2, SustainTime = 1 } )

soundbuffer( data, format, freq ) top ↑

Syntax

soundbuffer( data, format, freq )

This object represents a sound buffer containing arbitrary audio data. You may create soundbuffer objects using soundbuffer( data, format, freq ) where the data is uncompressed PCM audio and the format is one of FORMAT_MONO8, FORMAT_MONO16, FORMAT_STEREO8, or FORMAT_STEREO16.

data

string, uncompressed audio data

format

FORMAT_MONO8, FORMAT_MONO16, FORMAT_STEREO8 or FORMAT_STEREO16

freq

integer, the frequency of the data

Examples

-- Creating a sound buffer object function setup() tap = false parameter.integer("freq",1,4000,800) parameter.number("length",0.1,1,0.5) end function makeBuffer() local data = "" datum="\0\xAD\"" numSamples = freq * length for i = 1,numSamples/#datum do data = data .. datum end return soundbuffer( data, FORMAT_MONO8, freq ) end function touched(touch) if touch.state == ENDED and touch.tapCount == 1 then tap = true end end function draw() background(0) if tap then b = makeBuffer() sound(b) tap = false end end

Returns

A new soundbuffer object

soundBufferSize( size ) top ↑

Syntax

soundBufferSize( size )
soundBufferSize()

Calling this function will set the maximum buffer size for sounds. Sounds are stored in a buffer so that they do not need to be recreated if reused. Sounds are removed from this buffer on a least recently used basis when the buffer is full and a new sound is added. For example, if the buffer is 2 megabytes (the default), and we add a sound that puts it over the limit, the sound we used the longest time ago is removed from the buffer and will have to be re-created if played again. Generating the sound data can take a considerable amount of time for longer sounds.Playing a sound at 0 volume counts as playing and can be used to keep a sound in the cache (and to pre-generate a sound in the setup function.) Calling this method with 0 for the size sets the buffer to no limit. This can cause Codea to crash if too many sounds are generated as it may run out of memory.Calling this with no parameters returns the max size and current size of the buffer.

size

number, the maximum size of the buffer in megabytes. This can be a fraction. If this is 0, the buffer size is unlimited. An unlimited buffer size can cause Codea to crash if it runs out of memory, so take care if it is used.

Examples

-- setting the sound buffer maximum size soundBufferSize( 3 )
-- reading the current maximum size and used size maxSize, usedSize = nsoundBufferSize()
-- setting to no limit soundBufferSize(0)

Returns

If no parameters are given, a pair of values: maxBufferSize, currentBufferSize

soundsource top ↑

Syntax

source = sound(foo)

Created when calling the sound command, represents a live sound currently playing. Can be controlled to alter the playing sound

volume

number, the current volume of the sound source

pitch

number, the current pitch of the sound source

pan

number, the 2D spatial location of the sound (-1 left, +1 right, 0 center)

looping

boolean, whether to loop the sound when it reaches the end of playback

paused

boolean, whether the sound source is currently paused

muted

boolean, whether the sound source is currently muted

soundsource.stop() top ↑

Syntax

soundsource.stop()

Stops the sound if it is currently playing

soundsource.rewind() top ↑

Syntax

soundsource.rewind()

Start the sound again from the beginning next time it is played

soundsource.fadeTo() top ↑

Syntax

soundsource.fadeTo(volume, duration)

Fades the volume of the soundsource to the specified volume over the time specified by duration

volume

number, volume to fade to, between 0 and 1

duration

number, seconds over which to fade volume

soundsource.stopFade() top ↑

Syntax

soundsource.stopFade()

Cancels the current fading action, if possible

soundsource.pitchTo() top ↑

Syntax

soundsource.pitchTo(pitch, duration)

Adjustes the pitch of the soundsource to the specified pitch over the time specified by duration

pitch

number, pitch to fade to

duration

number, seconds over which to adjust pitch

soundsource.stopPitch() top ↑

Syntax

soundsource.stopPitch()

Cancels the current pitch change action, if possible

soundsource.panTo() top ↑

Syntax

soundsource.panTo(pan, duration)

Adjustes the pan of the soundsource to pan over the time specified by duration

pitch

number, pan to fade to (-1 left, +1 right, 0 center)

duration

number, seconds over which to pan the sound

soundsource.stopPan() top ↑

Syntax

soundsource.stopPan()

Cancels the current pan change action, if possible

soundsource.stopActions() top ↑

Syntax

soundsource.stopActions()

Cancels all active actions on the soundsource, if possible

SOUND_JUMP top ↑

Syntax

SOUND_JUMP

This constant specifies a jump sound. Similar to a character jumping in a platform game.

Returns

The string "jump"

SOUND_HIT top ↑

Syntax

SOUND_HIT

This constant specifies a hit sound. For example, when the enemy collides with the player.

Returns

The string "hit"

SOUND_PICKUP top ↑

Syntax

SOUND_PICKUP

This constant specifies a pickup sound. For example, collecting coins in a game.

Returns

The string "pickup"

SOUND_POWERUP top ↑

Syntax

SOUND_POWERUP

This constant specifies a powerup sound. For example, collecting bonuses in a game.

Returns

The string "powerup"

SOUND_SHOOT top ↑

Syntax

SOUND_SHOOT

This constant specifies a shooting sound. For example, firing a bullet in a game.

Returns

The string "shoot"

SOUND_EXPLODE top ↑

Syntax

SOUND_EXPLODE

This constant specifies an explosion sound. For example, a space ship blowing up.

Returns

The string "explode"

SOUND_BLIT top ↑

Syntax

SOUND_BLIT

This constant specifies a generic "blit" sound.

Returns

The string "blit"

SOUND_RANDOM top ↑

Syntax

SOUND_RANDOM

This constant specifies a randomly generated sound. You can use this in conjunction with the seed value of the sound() function to find a sound that you like.

Returns

The string "random"

SOUND_NOISE top ↑

Syntax

SOUND_NOISE

This specifices to use a white noise function as the waveform for this sound

Returns

The integer 3

SOUND_SAWTOOTH top ↑

Syntax

SOUND_SAWTOOTH

This specifices to use a sawtooth function as the waveform for this sound

Returns

The integer 1

SOUND_SINEWAVE top ↑

Syntax

SOUND_SINEWAVE

This specifices to use a sine wave function as the waveform for this sound

Returns

The integer 2

SOUND_SQUAREWAVE top ↑

Syntax

SOUND_SQUAREWAVE

This specifices to use a square wave function as the waveform for this sound

Returns

The integer 0

Speech

speech top ↑

Syntax

speech( string )
speech.pitch
speech.volume
speech.rate
speech.preDelay
speech.postDelay

This type represents a spoken utterance that can be played back using the speech.say() function. It consists of a string and other properties which determine the volume, speed and pitch of playback.

Multiple utterances can be queued for playback with the speech.say() function. The utterances will be separated by their respective preDelay and postDelay intervals.

Note that speech can be used to construct utterances to be used later, but it can also be used as a global table that can be configured for all future speech. See the two examples for both kinds of use.

string

string, the utterance to be spoken

pitch

float, a value between 0.5 and 2.0, raises or lowers the pitch (default is 1.0)

rate

float, a value between 0.0 and 1.0, the speed at which the utterance is spoken (default is 0.1)

preDelay

float, the amount of time to wait before speaking this utterance

postDelay

float, the amount of time to wait after speaking this utterance

volume

float, a value between 0.0 and 1.0 (default is 1.0)

voices

table, an array of available voice objects

voice

voice, the default voice to use for speech, use nil for default

language

string, the language string representing the voice you wish to use

Examples

-- This example uses global speech -- functions and settings -- Set speech volume for next -- use of speech.say() speech.volume = 0.7 -- Queue up a sentence speech.say("Hello World") -- Raise the pitch speech.pitch = 1.5 -- Queue up another sentence speech.say("I'm Talking")
-- This example creates actual -- utterance objects -- Create an utterance to use local words = speech("Hello World") local moreWords = speech("I'm Talking") words.volume = 0.7 moreWords.pitch = 1.5 -- Queue up two utterances speech.say( words ) speech.say( moreWords )
-- An example of voices -- List all voices for _,v in pairs(speech.voices) do print(v) end -- Set default language speech.language = "en-GB" -- Set specific voice -- (Overrides language setting) speech.voice = speech.voices[1]

Returns

The newly created utterance to be used with speech.say

speech.say( string ) top ↑

Syntax

speech.say( string )
speech.say( utterance )

This function can be used to speak a particular string or utterance. Calling this function multiple times will add more utterances to the queue to be spoken, it will not stop anything currently being spoken. Use speech.stop or speech.pause to control playback.

string

string, a string to speak

utterance

utterance, an utterance to speak

Examples

-- Adjust the speech settings speech.volume = 0.6 -- Just speak some words immediately -- will be spoken at 0.6 volume speech.say("Hello world!") -- Adjust settings for next words speech.volume = 1.0 speech.pitch = 1.5 -- Queue up another sentence to speak -- after the above is finished -- will be spoken louder, in high pitch speech.say("I'm talking")

speech.pause() top ↑

Syntax

speech.pause()
speech.pause( immediate )

This function can be used to pause anything currently being spoken. Speech will pause after the next word by default. Pass a value of true to this function to pause speech immediately.

After speech is paused, it can be continued with the speech.continue() function.

immediate

boolean, whether to pause immediately or after the next word

Examples

-- Just speak some words immediately speech.say("Hello world!") -- Pause it speech.pause() -- Later, continue speech.continue()

speech.stop() top ↑

Syntax

speech.stop()
speech.stop( immediate )

This function can be used to stop anything currently being spoken. Speech will stop after the next word by default. Pass a value of true to this function to stop speech immediately.

Unlike speech.pause speech which has been stopped cannot be resumed with the speech.continue() function.

immediate

boolean, whether to stop immediately or after the next word

Examples

-- Just speak some words immediately speech.say("Hello world!") -- Stop it immediately speech.stop( true )

speech.continue() top ↑

Syntax

speech.continue()

Use this function to resume speech which has been paused with speech.pause

speech.speaking top ↑

Syntax

speech.speaking

Check this value to see if the speech synthesizer is currently speaking.

Returns

Boolean value indicating whether the system is currently speaking

speech.paused top ↑

Syntax

speech.paused

Check this value to see if the speech synthesizer is currently paused.

Returns

Boolean value indicating whether the system is currently paused

speech.pitch top ↑

Syntax

speech.pitch = 2.0

Set this value to control the pitch of speech playback with speech.say. This value ranges from 0.5 to 2.0, the default is 1.0.

Returns

float value, the current global speech pitch

speech.rate top ↑

Syntax

speech.rate = 0.1

Set this value to control the rate (speed) of speech playback with speech.say. This value ranges from 0.0 to 1.0, the default is 0.5.

Returns

float value, the current global speech rate

speech.preDelay top ↑

Syntax

speech.preDelay = 0.0

Set this value to control the pre delay of speech played back with speech.say. Speech will be delayed by this amount prior to playback. Defaults to 0.0.

Returns

float value, the delay in seconds prior to playing speech

speech.postDelay top ↑

Syntax

speech.postDelay = 0.0

Set this value to control the post delay of speech played back with speech.say. A pause for this amount of time will occur after speech played back and before the next queued speech.

Returns

float value, the delay in seconds after playing speech

speech.volume top ↑

Syntax

speech.volume = 1.0

Set this value to control volume of speech played back with speech.say. This value can range between 0.0 and 1.0. It defaults to 1.0.

Returns

float value, the volume of speech

Microphone

mic.start() top ↑

Syntax

mic.start()

Use this function to start tracking input from the device microphone

mic.stop() top ↑

Syntax

mic.stop()

Use this function to stop tracking input from the device microphone

mic.amplitude top ↑

Syntax

local amp = mic.amplitude

Sample this value to determine the volume of sound coming into the microphone

mic.frequency top ↑

Syntax

local freq = mic.frequency

Sample this value to determine the pitch of sound coming into the microphone