Dieses Dokuwiki verwendet ein von Anymorphic Webdesign erstelltes Thema.
Table of Contents

CocosDenshion FAQ

General

What is CocosDenshion?

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.

What does CocosDenshion mean?

The name CocosDenshion was derived by combining the cocos from cocos2d with a Japanese word meaning “electronic sound”.

Can I use CocosDenshion without using cocos2d for iPhone?

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.

How do I use CocosDenshion in my project ?

There are 3 different ways of using CocosDenshion. Depending on which you choose you will need to include different files and frameworks.

SimpleAudioEngine

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.

  • Requires: iOS 3.0 or greater or Mac OS X 10.6 or greater
  • Required Files: SimpleAudioEngine.*, CocosDenshion.*, CDAudioManager.*, CDOpenALSupport.h, CDConfig.h
  • Required Frameworks: OpenAL, AudioToolbox, AVFoundation (except on Mac OS X where you must include the CDXMacOSXSupport.* files from CocosDenshionExtras).

CDAudioManager

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.

  • Requires: iOS 3.0 or greater or Mac OS X 10.6 or greater
  • Required Files: CDAudioManager.*, CocosDenshion.*, CDOpenALSupport.h, CDConfig.h
  • Required Frameworks: OpenAL, AudioToolbox, AVFoundation (except on Mac OS X where you must include the CDXMacOSXSupport.* files from CocosDenshionExtras).

CDSoundEngine

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.

  • Requires: iOS 2.1.x or greater or Mac OS X 10.6 or greater
  • Required Files: CocosDenshion.*, CDOpenALSupport.h, CDConfig.h
  • Required Frameworks: OpenAL, AudioToolbox

I need more help are there any tutorials?

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

Why isn't SimpleAudioEngine called CDSimpleAudioEngine?

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.

Can I build CocosDenshion as a static library?

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.

Do I have to include CocosDenshion as a static library?

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.

Do I have to load sounds asynchronously and/or in a batch when using CDAudioManager?

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.

What sound formats can I use?

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.

I want to use IMA4 compressed files, how do I create them?

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

Can I use CocosDenshion with PASoundMgr?

No, because both APIs assume they are managing the OpenAL context.

What are some tips for saving memory with my sounds?

  • Look at your sound sample in an editor like Audacity and make sure there is no unnecessary silence at the beginning or end, if so trim it.
  • Use mono sounds unless you need stereo. That will halve your memory requirements.
  • Consider using lower sampling rates.

What values can I use for pitch?

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.

What values can I use for pan?

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.

What values can I use for gain?

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

What should I retain/release?

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.

Can I record audio data with CocosDenshion ?

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.

Troubleshooting

General troubleshooting steps ?

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).

I'm getting linker errors when I compile, what should I do ?

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.

I've added the OpenAL framework but I still get linker errors for OpenAL functions, what should I do ?

I don't get any sound in the simulator ?

Lack of sound in the simulator is usually caused by a problem with the OpenAL driver. Some know problems are:

  • You have a hackintosh with an unsupported sound card - nothing you can do;
  • You have a PPC based Mac - if it doesn't work you are probably out of luck;
  • There is a DivX codec causing problems - remove the codec;
  • Audio output is being directed to the simulator - go into System Preferences/Sound and set a different output.
  • Audio input is being directed to the simulator - go into System Preferences/Sound and set a different input.
  • The Built-in Output sample rate does not match the simulators. Run the Audio MIDI Setup utility from Applications/Utilities and check the Format value for the Built-in Output. Make sure this is set to 44100.0 Hz. It is possible that installing Final Cut modifies this value to one that is not compatible with the Simulator.

My background music was paused but after a begin active event it starts playing?

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.

Background music seems unreliable in the simulator?

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.

I am having problems with play back of an mp3 file

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:

  • Power Audio Editor Ver 11 on Windows

I've got some wave files but they don't work, what can I do?

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

Panning doesn't seem to be working?

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.

I'm not seeing any trace statements in the console?

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.

In the simulator my sound effects stop playing after I stop the background music?

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.

I'm upgrading to a newer version of CocosDenshion and now I get errors?

cocos2d Pre 0.99 to 0.99+ Upgrade

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

CocosDenshion Pre 2.0 to 2.0 Upgrade

The update adds two features:

  • Load sounds from a path rather than a filename so you have much more flexibility now in where the sounds are located;
  • Removal of C++ dependencies which greatly simplifies the inclusion of CocosDenshion in a static library.

The two issues you will have when upgrading are:

  • All methods that previously took fileName now take filePath so just go and change fileName to filePath;
  • All .mm files are now .m files - you will need to remove the .mm files and add the .m versions to your project.
cocosdenshion/faq.txt · Last modified: 2011/08/03 02:52 by steveoldmeadow
Trace: faq
Dieses Dokuwiki verwendet ein von Anymorphic Webdesign erstelltes Thema.
CC Attribution-Noncommercial-Share Alike 3.0 Unported
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0