Playing Sound and Music

The Ultimate Guide to Gideros Studio

Introduction to sound system

The Sound class in Gideros lets you play back sound files of all kinds. Be it short sound effects like a gunshot or a 5-minute piece of music, it doesn’t matter. Under the hood, Gideros utilizes OpenAL for playing back WAV files and AVAudioPlayer to play back MP3 files.

The supported file formats are MP3 and WAV on iOS and Android (OGG via a plugin).

If you need to convert your sounds files to one of these formats, then try the open source software Audacity. It will help you convert your sound files in no time.

Regarding the performance, you should use .wav files for sound effects and .mp3 for background music. Here are the advantages and disadvantages of these:

• WAV files: Entire sound is loaded into memory. Consumes little CPU while playing. Suitable for simultaneously played sound effects.
• MP3 files: Sound is played by reading small chunks, therefore, consumes little memory. Consumes more CPU compared to WAV files. Suitable for background music/speech.

Playing a sound

Here is a sample to play a sound inside your app. It uses the play method of the Sound class:

-- Load a new sound and assign it to a variable
local yourSound = Sound.new("yourSoundFile.mp3")
-- Now play the sound
yourSound:play()

As you can see, it is very easy to play a sound effect or a music file. The play method of the Sound class has three optional parameters:

• startTime (number, default = 0)
• loop (number, default = 0)
• paused (boolean, default = false)

With the startTime, you can control the starting point in milliseconds, from where a sound is played back. The loop parameter will control if the sound will be played repeatedly for the given number of times. The paused parameter will tell Gideros if the sound should be paused upon creation (useful for SoundChannel). Here is a simple example that will play a sound starting from 200 milliseconds and repeat itself 5 times:

yourSound:play(200, 5)

If you want to let a sound play repeatedly, then just set the loop value to math.huge:

yourSound:play(0, math.huge)

Using sound channels

Playing back sounds inside your app is nice but sometimes you want to have a little bit more control over things. For this Gideros uses sound channels. How are they created or retrieved you might ask? Piece of cake! Whenever you play a sound, assign the returning value (the sound channel) to a variable. Like this:

local yourChannel = yourSound:play()

There is one event that will tell you when a sound channel has finished playing a sound file: Event.COMPLETE. Next is a small example on how the Event.COMPLETE event can be used:

-- Load a music file
local snd = Sound.new("DST-Psykick.mp3")
-- Start playing the music file and store the channel
local chan = snd:play()
-- Define the Event.COMPLETE function that is called
-- when the sound finishes playing
function onSoundComplete(event)
	print ("Sound complete")
end
-- Add the event listener that is firing when the sound
-- finishes playing
chan:addEventListener(Event.COMPLETE,onSoundComplete)

Releasing a sound

You don’t have to release a sound manually. It will be collected once the app ends. But if you need to release a sound during the life of your app, then just set the corresponding channel to nil:

yourSound = nil

Note: If the sound is currently playing, the sound will be released after it finishes playing.

Stopping a sound

If you want to stop a playing sound, then use your sound channel and its stop method for it:

sndChannel:stop()

Getting length of a sound file

Sometimes you need to know how long a sound file is exactly. To determine the length of a sound file you can use the getLength method. Use it with your sound channel:

local sndLength = sndChannel:getLength()

After this line is executed, sndLength will hold the length of the sound in milliseconds.

Setting and getting the volume of a sound

Before you break some ears with loud sounds, you better give your users the possibility to control the volume of the sounds your app is playing. For this, there are two methods, setVolume, and getVolume. To get the volume of a sound, try this:

local volume = sndChannel:getVolume()

And to set the volume of a channel, use setVolume like this:

sndChannel:setVolume(0.5)

The volume levels ranging from 0.0 to 1.0. The later means maximum volume.

Getting the current position of a sound playing

When you need to pause a sound or display the current position of a sound playing, you need to determine the current position of a channel. For this use the getPosition method with your channel:

local currSndPos = sndChannel:getPosition()

The position is determined in milliseconds. So if you need to pause a sound, retrieve the current position, stop the sound channel and when you resume your sound, use the stored position as a start time for the play method.

PREV.: Introduction to Fonts
NEXT: Event system

---

• Main Page
• Lua API
• Main API
• Plugins