Chapter 6. Playing Sounds and Music

We hear sound effects and music in almost every type of media we encounter daily. Many notable games such as Pac-Man, Angry Birds, and Fruit Ninja can be recognized just by their theme music or sound effects alone. Aside from the visual imagery we see in games, sounds help impact the mood conveyed in the storyline and/or during game play. Quality sound effects and music that pertain to the theme of your game helps give a realistic feel to the experience.

In this chapter, you will learn how to apply sound effects and music that can be added to your applications. You have the visual appeal down from creating Breakout and Panda Star Catcher in the previous chapters. Now, let's enhance the sensory experience for our ears!

The main points you'll be going over are:

• Loading, playing, and looping audio

• Understanding how to play, pause, resume, rewind, and stop the audio

• Memory management (disposing audio)

• Volume control

• Performance and encoding tips

Let's create some...

Corona audio system

The Corona audio system has advanced Open Audio Library (OpenAL) features. OpenAL is designed for the efficient rendering of multichannel three-dimensional positional audio. The general functionality of OpenAL is encoded in source objects, audio buffers, and a single listener. A source object contains a pointer to a buffer, the velocity, position and direction of the sound, and the intensity of the sound. Buffers contain audio data in the PCM format, either 8- or 16-bit, in either mono or stereo format. The listener object contains the velocity, position and direction of the listener, and the general gain applied to all sounds.

Note

For more information on the Corona audio system, you can go to http://developer.coronalabs.com/partner/audionotes. General information on OpenAL can be found at http://www.openal.org.

Sound formats

The following are the sound formats that are compatible with iOS and Android platforms:

• All platforms support files that are 16-bit, little endian,...

Time to play

Audio can be loaded in two different ways, as follows:

• loadSound(): This preloads an entire sound into the memory

• loadStream(): This prepares the sound to be played by reading small chunks at a time to save memory

audio.loadSound()

The audio.loadSound() function loads an entire file completely into the memory and returns a reference to the audio data. Files that are loaded completely into the memory can be reused, played, and shared simultaneously on multiple channels. So, you only need to load one instance of the file. Sounds that you would use as sound effects in your game will fit in this category.

The syntax is audio.loadSound(audiofileName [, baseDir ]).

The parameters are as follows:

• audiofileName: This specifies the name of the audio file you want to load. The supported file formats are determined by the platform the file is being run on.

• baseDir: By default, sound files are expected to be in the application resources directory. If the sound file is in the application documents...

Time for action – playing audio

We're going to learn how sound effects and music are implemented in Corona to get an idea of how it really works. To play an audio follow the steps:

1. Create a new project folder on your desktop called Playing Audio.

2. In the Chapter 6 Resources folder, copy the ring.wav and song1.mp3 sound files into your project folder and create a new main.lua file. You can download the project files that accompany this book from the Packt Publishing website.

3. Preload the following audio with loadSound() and loadStream():

   ringSound = audio.loadSound( "ring.wav" )
   backgroundSound = audio.loadStream( "song1.mp3" )

4. Play backgroundSound by setting it to channel 1, loop it infinitely, and fade in after 3 seconds:

   mySong = audio.play( backgroundSound, { channel=1, loops=-1, fadein=3000 }  )

5. Add in ringSound and play it once:

   myRingSound = audio.play( ringSound )

6. Save and run the project in the Corona Simulator to hear the results.

What just happened?

For audio that is merely a short sound...

Time to take control

We have the ability to control our sounds, now that we can play them in the simulator. If you think back to the days of cassette tape players, it had the ability to use functions such as pause, stop, and rewind. Corona's audio API library can do just that.

audio.stop()

The audio.stop() function stops playback on a channel and clears the channel, so it can be played on again.

The syntax is audio.stop( [channel] ) or audio.stop( [ { channel = c } ] ).

Having no parameters stops all active channels. The channel parameter specifies the channel to stop. Specifying 0 stops all channels.

audio.pause()

The audio.pause() function pauses playback on a channel. This has no effect on channels that aren't playing.

The syntax is audio.pause( [channel] ) or audio.pause( [ {channel = c} ] ).

Having no parameters pauses all active channels. The channel parameter specifies the channel to pause. Specifying 0 pauses all channels.

audio.resume()

The audio.resume() function resumes playback on a channel...

Time for action – controlling audio

Let's simulate our own little music player by creating user interface buttons that will control the audio calls as follows:

1. In the Chapter 6 folder, copy the Controlling Audio project folder to your desktop. You will notice several art assets, a ui.lua library, config.lua file, and a song2.mp3 file inside. You can download the project files accompanying this book from the Packt Publishing website.

   

2. In the same project folder, create a brand new main.lua file.

3. Load the audio file via loadStream(), name it music, and call the UI library. Also add it in a local variable called myMusic:

   local ui = require("ui")
   local music = audio.loadStream( "song2.mp3" ) local myMusicChannel

4. Create a local function called onPlayTouch() with an event parameter to play the audio file. Add an if statement that contains event.phase == "release" so that the music starts playing when the button releases. Apply the playBtn display object as a new UI button:

   local onPlayTouch = function...

Memory management

It is important to call audio.dispose() on your loaded audio when you are completely done with the audio file. Doing so allows you to recover the memory.

audio.dispose()

The audio.dispose() function releases the audio memory associated with the handle.

The syntax is audio.dispose( audioHandle ).

The parameter is as follows:

• audioHandle: The handle returned by the audio.loadSound() or audio.loadStream() functions that you want to free.

  Tip

  You must not use the handle once the memory is freed. The audio should not be playing or paused on any channel when you try to free it.

For example:

mySound = audio.loadSound( "sound1.wav" )
myMusic = audio.loadStream( "music.mp3" )

audio.dispose( mySound )
audio.dispose( myMusic )

mySound = nil
myMusic = nil

Have a go hero – disposing audio

You have just learned how to dispose audio files properly to recover memory in your application. Try the following:

• Load your audio file and have it play for a specified time. Create a function that will dispose...

Alterations to audio

The audio system also has the ability to alter the minimum and maximum states of audio volume, as well as fading the audio when needed.

Volume control

The volume of the audio can be set with values ranging from 0 to 1.0. This setting can be adjusted at any time before or during the extended sound playback.

audio.setVolume()

The audio.setVolume function sets the volume.

The syntax is audio.setVolume( volume [, [options] ] ) --upon success, should return true.

The parameters are as follows:

• volume: This lets you set the volume level you want to apply. Valid numbers range from 0.0 to 1.0, where 1.0 is the maximum volume value. The default volume is based on your device ringer volume and will vary.

• options: This is a table that supports the channel number you want to set the volume on. You can set the volume on any channel between 1 to 32. Specify 0 to apply the volume to all the channels. Omitting this parameter entirely sets the master volume, which is different from the channel...

Performance tips

When creating good quality audios for your games, refer to the helpful notes mentioned here.

Preloading phase

It is best to preload the files you regularly use on startup of your application. While loadStream() is generally fast, loadSound() may take a while since it must load and decode the entire file the instant it needs to be used. Generally, you don't want to be calling loadSound() in the parts of your application that users expect it to be running smoothly when events occur, such as during game play.

audioPlayFrequency

In the config.lua file, you may specify a field called audioPlayFrequency:

application =
{
  content =
  {
    width = 480,
    height = 960,
    scale = "letterbox",
    audioPlayFrequency = 22050
  },
}

This tells the OpenAL system what sample rate to mix and playback at. For best results, set this no higher than you actually need. So if you never need better than 22,050 Hz playback, set this to 22,050. It produces quality speech recordings or middle-quality...

Summary

You now understand the important aspects of using audio files in the Corona SDK. Now, you can go off adding your own sound effects and music to your games, or even add them to any of the samples you made in the previous chapters. By doing so, you add another part of the user experience that will draw players into the environment you have created.

Until now, you learned how to:

• Preload and play sound effects and music using loadSound() and loadStream()

• Control audio functions that pause, resume, stop, and rewind a music track under the Audio System API

• Dispose audio from memory when it is no longer in use

• Adjust volume in your audio files

In the next chapter, you will combine everything you have learned so far to create your final game in this book. You'll also be going over other ways to implement physical objects and collision mechanics that are popular in mobile games in the market today. More exciting information to learn awaits you. Let's power through!