CocosDenshion is an audio library for the iOS and Mac OS X operating systems. The main focus is meeting the audio needs of games. CocosDenshion includes a low latency sound engine for playback of game sound effects with modification of pitch, pan and gain as well as an audio manager that provides playback of multiple tracks of compressed audio and audio session management for iOS.
CocosDenshion provides multiple APIs. At the most basic level CDSoundEngine implements a low latency sound playback engine with a choice of stateless or object oriented APIs. CDAudioManager builds upon CDSoundEngine and adds playback of multiple tracks of long duration audio (typically compressed using mp3, ima4 or aac) as well as audio session management. Audio session management makes it easy to provide features such as allowing the user to listen to their own music or ensuring audio is suppressed when the device is muted using the silent switch. Finally, the SimpleAudioEngine API provides a simplified audio API that is extremely easy to understand but with the possibility to drop down to the CDAudioManager and CDSoundEngine APIs when more functionality is required.
CocosDenshion is the official audio API of the cocos2d for iPhone project and is ready to be used in any project created using one of the cocos2d templates. CocosDenshion has had millions of installs through being used in two number one AppStore applications (Stick Wars and Zombie Smash) as well as hundreds of other successful cocos2d games.
The name CocosDenshion was derived by combining the cocos from cocos2d with a Japanese word meaning “electronic sound”.
Yes, although CocosDenshion is part of cocos2d for iPhone it has been designed to be usable independently as well. It will work in UIKit apps, Cocoa apps and has even been used successfully in other iPhone frameworks.
However, there is some extra functionality that is dependent on cocos2d - for example, fading out sounds using cocos2d actions. Classes that have cocos2d dependencies are kept in the CocosDenshionExtras directory.
There are 3 different ways of using CocosDenshion. Depending on which you choose you will need to include different files and frameworks.
This is the simplest and most popular API. It offers a deliberately reduced functionality to make learning simpler but provides the option of using the CDAudioManager and CDSoundEngine APIs for enhanced functionality.
CDAudioManager is utilised by SimpleAudioEngine. It provides playback of multiple tracks of long duration audio and audio session management. The main differences it offers over SimpleAudioEngine is that sounds are identified by a numeric id rather than a file name and it gives more flexibility in how the playback of simultaneous sounds is managed.
CDSoundEngine is a sound engine built upon OpenAL. It can playback up to 32 sounds simultaneously with control over pitch, pan and gain. It can be set up to handle audio session interruption automatically. You may decide to use CDSoundEngine directly instead of CDAudioManager or SimpleAudioEngine because you require OS 2.1.x compatibility. Note that if you use CDSoundEngine directly you will need to manage audio session interruption on iOS as described in the iPhone Audio Programming Guide.
Bob Ueland has produced a nice video tutorial: http://bobueland.com/cocos2d/?p=195
Many of Ray Wenderlich's Cocos2d tutorials also use CocosDenshion. http://www.raywenderlich.com/tag/cocos2d
SimpleAudioEngine was originally designed by João Caxaria as an addition to CocosDenshion so the name has been retained to respect this origin. However, the CD* prefix is designed to prevent naming collisions with other classes and it is considered highly unlikely that someone will be using two classes named SimpleAudioEngine.
Yes, this is how CocosDenshion is utilised in the cocos2d project and the MyFirstGame demo project supplied with cocos2d has CocosDenshion set up this way.
No, that is purely your choice. CocosDenshion has been designed to be easy to add to a project by simply adding the files to the project and including them in a build target.
No, the CocosDenshion demo does this to show how to asynchronously load sounds as this is the most complex way of loading sounds. You can load sounds synchronously using loadBuffer. It is also possible to mix synchronous and asynchronous loading of sounds. If you wanted to play a sound shortly after application startup it is recommended to load that sound synchronously but beware that the CDAudioManager will need to be initialised before any audio playback can occur and this can take several seconds.
For background music any format that is supported by AVAudioPlayer should work. For testing purposes mp3 files are used and therefore known to work.
For sound effects played with CDSoundEngine it is recommended to use 16 bit mono wave files for uncompressed audio and IMA4 for lossy compressed audio. IMA4 sounds are around one quarter the size of the corresponding wave file. However, note that using compressed audio for sound effects will only reduce the size of your application download - it does not reduce your memory requirements as all sounds are stored in memory in 16 bit uncompressed PCM format which will use roughly the same amount of memory as the file size of the corresponding 16 bit wave file.
From OS 3.0 onward it is possible to use mp3 files for sound effects (e.g playEffect). However, you must be aware that this will not work on any OS before 3.0: for this reason using mp3 files for sound effects is not recommended and not supported - use them at your own risk.
The recommended way is to use the afconvert command line tool. For example, the following command will create an IMA4 compressed file called mysound.caf from the wave file called mysound.wav.
afconvert -f caff -d ima4 mysound.wav
No, because both APIs assume they are managing the OpenAL context.
Usable pitch values range from 0.5f to 2.0f where 0.5f is half the speed (one octave lower) and 2.0f is twice the speed (one octave higher). A pitch value of 1.0f plays back the sample unchanged.
A pan value of -1.0f is fully left, no signal will appear in the right channel and a pan value of 1.0f is fully right, no signal will appear in the left channel. A pan value of 0.0f is centered. So there is a spectrum ranging between -1.0f and 1.0f with 0.0f the centre. Note that panning only works for mono sounds.
A value of 1.0 means un-attenuated/unchanged. Each division by 2 equals an attenuation of -6dB e.g 0.5 is a 6dB reduction. Each multiplicaton with 2 equals an amplification of +6dB. Despite what is said in the OpenAL headers increasing gain above 1.0 has no effect on iOS 3.1.3 and 4.x
SimpleAudioEngine, CDAudioManager and CDSoundEngine APIs are all accessed through a shared singleton instance. This is a common pattern that is used throughout Cocoa Touch and cocos2d. The shared instance should not be retained or released.
If you need to completely shut down CocosDenshion and free all resources it was using then call the end method on the highest level API you are using. For example if you are using SimpleAudioEngine then just call [SimpleAudioEngine end].
If you use CDSoundSource objects you must obtain them through one of the factory methods such as soundSourceForFile. The CDSoundSource that is returned is autoreleased, that means if you want to use it outside the scope of the current method you must retain it. If you retain a CDSoundSource you should release it when you are finished using it.
CocosDenshion currently has no support for recording audio data. You can use AVAudioRecorder but you must set the audio manager to kAMM_PlayAndRecord before recording.
Firstly, determine if it is a problem with your project or your environment. You can do this by building and testing one of the CocosDenshion samples such as FadeToGrey. If it works then we now know it is a problem with your project. If it doesn't work it is something wrong with your environment.
If the CocosDenshion sample is not working then it is useful to know if other audio applications are working. Download Apple's oalTouch and avTouch samples and build and test these. If neither of these work then you have a general audio issue. If oalTouch doesn't work but avTouch does then you have a general OpenAL issue.
If these both work but CocosDenshion does not then it appears you have found a bug with CocosDenshion. Please follow the steps for reporting an issue with cocos2d (i.e. create an issue).
You probably don't have all the necessary frameworks included in your project. The required frameworks depend on how you want to use CocosDenshion (see above for details). If you are unsure how to add frameworks to your project check the XCode documentation.
Also make sure you do not have multiple copies of any files.
Check this article: http://cowboyprogramming.com/2009/03/20/iphone-openal-linking-problem/
Lack of sound in the simulator is usually caused by a problem with the OpenAL driver. Some know problems are:
This is a “feature” caused by the operating system trying to manage audio sessions. If it causes you problems consider stopping the sound. If you are using CDAudioManager you can set it up to automatically handle this situation by setting the resign behavior and use the StopPlay or Stop modes.
Yes, it is. Before reporting any issues occurring with background music in the simulator please test that they are also occurring on the device. Simulator only issues will not be fixed.
Some mp3 files have been found to cause problems such as delays in resuming, try encoding the file with afconvert. The output of the following mp3 conversion software is know to be problematic:
There are different formats for wave files. CocosDenshion needs little endian encoding. If you have a wave file that doesn't work it may be using a different encoding. Luckily the afconvert command line tool can be used to create files in the correct format. For example the following command will create a file called working.wav in the correct format from one called notworking.wav. Alternatively the Audacity editor is known to save files in the correct format when they are saved as a wave file.
afconvert -v -f WAVE -d LEI16 notworking.wav working.wav
Are your sounds samples mono? If they are stereo then panning will not work.
Also consider the device hardware configuration, if you are listening on the internal speaker and there is only a single speaker then panning can not work. Even with two speakers if the device is rotated panning will not work as expected.
CocosDenshion will log some tracing information when it starts up and when any errors occur. However, these statements will only appear when CD_DEBUG is defined, you can adjust this by editing the CDConfig.h file.
There is a known issue with the simulator where stopping an AVAudioPlayer (as used for playing background music) will stop the OpenAL audio (as used for sound effects) from working correctly. The workaround is to not use stopBackgroundMusic in the simulator, use pauseBackgroundMusic instead.
CDAudioManager's backgroundMusic object was changed to be an instance of CDLongAudioSource instead of AVAudioPlayer. If you had code that directly access AVAudioPlayer properties of backgroundMusic then you need to now access the audioSourcePlayer property of backgroundMusic. e.g backgroundMusic.numberOfChannels becomes backgroundMusic.audioSourcePlayer.numberOfChannels
The update adds two features:
The two issues you will have when upgrading are: