ProgrammingGuide > Audio

Audio

version: Cocos2d-x v2.x, 3.x
update: Updated about 2 years ago

Your game will surely need sound! Cocos2d-x provides an audio engine so ways we call it SimpleAudioEngine. SimpleAudioEngine can be used to play background music as well as sound effects through out your game play. SimpleAudioEngine is a shared singleton object so you can simple call it from anywhere in your code. When creating a sample HelloWorld project we do all the setup required for you, out of the box. SimpleAudioEgnine support a number of formats, including MP3 and Core Audio Format

Getting Started

The SimpleAudioEngine API is very easy to use.

Play background music

Play an audio file for use as background music. This can be repeated
continuously.

1
2
3
4
5
6
7
auto audio = SimpleAudioEngine::getInstance();

// set the background music and continuously play it.
audio->playBackgroundMusic("mymusic.mp3", true);

// set the background music and play it just once.
audio->playBackgroundMusic("mymusic.mp3", false);

Play a sound effect.

Play a sound effect.

1
2
3
4
auto audio = SimpleAudioEngine::getInstance();

// play a sound effect, just once.
audio->playEffect("myEffect.mp3", false, 1.0f, 1.0f, 1.0f);

Pausing, stopping, resuming music and sound effects

After you start to play music and sound effects you might need to pause, stop or resume after certain operations. This can be done easily.

Pause

1
2
3
4
5
6
7
8
9
10
auto audio = SimpleAudioEngine::getInstance();

// pause background music.
audio->pauseBackgroundMusic();

// pause a sound effect.
audio->pauseEffect();

// pause all sound effects.
audio->pauseAllEffects();

Stop

1
2
3
4
5
6
7
8
9
10
auto audio = SimpleAudioEngine::getInstance();

// stop background music.
audio->stopBackgroundMusic();

// stop a sound effect.
audio->stopEffect();

// stops all running sound effects.
audio->stopAllEffects();

Resume

1
2
3
4
5
6
7
8
9
10
auto audio = SimpleAudioEngine::getInstance();

// resume background music.
audio->resumeBackgroundMusic();

// resume a sound effect.
audio->resumeEffect();

// resume all sound effects.
audio->resumeAllEffects();

Advanced audio functionality

Setup

It is easy to get started using the SimpleAudioEngine API. There are considerations to keep in mind when using audio in your game. Mostly when operating on mobile devices such as phones and tablets. What happens when you multi-task on your phone and are switching between apps? Or when a phone call comes in? You need to handle these exceptions in your game. Fortunately we
help you here.

In AppDelegate.cpp, notice the following methods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// This function will be called when the app is inactive. When comes a phone call,
// it's be invoked too
void AppDelegate::applicationDidEnterBackground() {
    Director::getInstance()->stopAnimation();

    // if you use SimpleAudioEngine, it must be pause
    // SimpleAudioEngine::getInstance()->pauseBackgroundMusic();
}

// this function will be called when the app is active again
void AppDelegate::applicationWillEnterForeground() {
    Director::getInstance()->startAnimation();

    // if you use SimpleAudioEngine, it must resume here
    // SimpleAudioEngine::getInstance()->resumeBackgroundMusic();
}

Notice the commented out lines for SimpleAudioEngine make sure to uncomment these if you are using SimpleAudioEngine for background sounds and sound effects.

Pre-Loading sound

When your game starts you might want to pre-load the music and effects so they are ready when you need them.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
auto audio = SimpleAudioEngine::getInstance();

// pre-loading background music and effects. You could pre-load
// effects, perhaps on app startup so they are already loaded
// when you want to use them.
audio->preloadBackgroundMusic("myMusic1.mp3");
audio->preloadBackgroundMusic("myMusic2.mp3");

audio->preloadEffect("myEffect1.mp3");
audio->preloadEffect("myEffect2.mp3");

// unload a sound from cache. If you are finished with a sound and
// you wont use it anymore in your game. unload it to free up
// resources.
audio->unloadEffect("myEffect1.mp3");

Volume

You can increase and decrease the volume of your sounds and music programmatically.

1
2
3
4
auto audio = SimpleAudioEngine::getInstance();

// setting the volume specifying value as a float
audio->setEffectsVolume(5.0f);

Supported Audio formats on different platforms

Note that on most platforms, cocos2d-x invokes different SDK API for background music (BGM) and Effects. CocosDenshion can play ONLY ONE background music at one time, but can play many effects synchronously.

Background Music

Platforms supported BGM formats
Android formats that android.media.MediaPlayer support.
iOS It supports the same formats as CocosDenshion in cocos2d-iphone. MP3 and CAF are recommended
Windows Desktop .mid and .wav are supported. Note that mp3 is not supported.

Sound Effects

Platform supported sound effects formats
Android Supports .ogg best, not so good for .wav format.
iOS .mp3, .wav, .caf
Windows Desktop .mid and .wav only

WARNING: Samsung i9100 seems have a bug in its audio driver. It CAN NOT accept too much effects concurrently. You need to limit calling SimpleAudioEngine::playEffect(const char* filePah) too frequently in your game logic code when running on Samsung i9100.

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.