[一位菜鸟的COCOS-2D编程之路]COCOS2D 声音 --SimpleAudioEngine 和CDAudioManager

声音的接口主要有三个API：

SimpleAudioEngine，CDAudioManager，和CDSoundEngine

1.SimpleAudioEngine

@interface SimpleAudioEngine : NSObject <CDAudioInterruptProtocol> {

	BOOL	mute_;
	BOOL	enabled_;
}

/** Background music volume. Range is 0.0f to 1.0f. This will only have an effect if willPlayBackgroundMusic returns YES */
@property (readwrite) float backgroundMusicVolume;  //背景音乐的声音
/** Effects volume. Range is 0.0f to 1.0f */
@property (readwrite) float effectsVolume;  //音效的声音设置
/** If NO it indicates background music will not be played either because no background music is loaded or the audio session does not permit it.*/
@property (readonly) BOOL willPlayBackgroundMusic; //是否 即将播放背景音乐，预先加载的话为YES。

/** returns the shared instance of the SimpleAudioEngine object */
+ (SimpleAudioEngine*) sharedEngine;  //单例类方法。 在使用实例方法的时候都会使用
// [SimpleAudioEngine sharedEngine]实例方法

//预先加载背景音乐
/** Preloads a music file so it will be ready to play as background music */
-(void) preloadBackgroundMusic:(NSString*) filePath;

//通过路径来加载背景音乐
/** plays background music in a loop*/
-(void) playBackgroundMusic:(NSString*) filePath;
/** plays background music, if loop is true the music will repeat otherwise it will be played once */

-(void) playBackgroundMusic:(NSString*) filePath loop:(BOOL) loop;

//停止/暂停 播放背景音乐
/** stops playing background music */
-(void) stopBackgroundMusic;
/** pauses the background music */
-(void) pauseBackgroundMusic;

//继续播放背景音乐
/** resume background music that has been paused */
-(void) resumeBackgroundMusic;

//重新播放背景音乐
/** rewind the background music */
-(void) rewindBackgroundMusic;

//是否正在播放背景音乐
/** returns whether or not the background music is playing */
-(BOOL) isBackgroundMusicPlaying;

//以下是音效的设置。和背景音乐的设置类似，但是多了三个参数  pitch：音高（调） pan：声源  gain 音量
/** plays an audio effect with a file path*/
-(ALuint) playEffect:(NSString*) filePath;
/** stop a sound that is playing, note you must pass in the soundId that is returned when you started playing the sound with playEffect */
-(void) stopEffect:(ALuint) soundId;
/** plays an audio effect with a file path, pitch, pan and gain */
-(ALuint) playEffect:(NSString*) filePath pitch:(Float32) pitch pan:(Float32) pan gain:(Float32) gain;
/** preloads an audio effect */
-(void) preloadEffect:(NSString*) filePath;

//卸载此音效
/** unloads an audio effect from memory */
-(void) unloadEffect:(NSString*) filePath;
/** Gets a CDSoundSource object set up to play the specified file. */
-(CDSoundSource *) soundSourceForFile:(NSString*) filePath;

//结束音效
/** Shuts down the shared audio engine instance so that it can be reinitialised */
+(void) end;

@end

2. CDAudioManager 是比SimpleAudioEngine 复杂一点的API。

@interface CDAudioManager : NSObject <CDLongAudioSourceDelegate, CDAudioInterruptProtocol, AVAudioSessionDelegate> {
	CDSoundEngine		*soundEngine;
	CDLongAudioSource	*backgroundMusic;
	NSMutableArray		*audioSourceChannels;
	NSString*			_audioSessionCategory;
	BOOL				_audioWasPlayingAtStartup;
	tAudioManagerMode	_mode;
	SEL backgroundMusicCompletionSelector;
	id backgroundMusicCompletionListener;
	BOOL willPlayBackgroundMusic;
	BOOL _mute;  //静音
	BOOL _resigned;
	BOOL _interrupted;  //是否被打断
	BOOL _audioSessionActive;
	BOOL enabled_;  //是否结束

	//For handling resign/become active
	BOOL _isObservingAppEvents;
	tAudioManagerResignBehavior _resignBehavior;
}

@property (readonly) CDSoundEngine *soundEngine;
@property (readonly) CDLongAudioSource *backgroundMusic;
@property (readonly) BOOL willPlayBackgroundMusic;

/** Returns the shared singleton */
+ (CDAudioManager *) sharedManager;
+ (tAudioManagerState) sharedManagerState;
/** Configures the shared singleton with a mode*/
+ (void) configure: (tAudioManagerMode) mode;
/** Initializes the engine asynchronously with a mode */
+ (void) initAsynchronously: (tAudioManagerMode) mode;
/** Initializes the engine synchronously with a mode, channel definition and a total number of channels */
- (id) init: (tAudioManagerMode) mode;
-(void) audioSessionInterrupted;
-(void) audioSessionResumed;
-(void) setResignBehavior:(tAudioManagerResignBehavior) resignBehavior autoHandle:(BOOL) autoHandle;
/** Returns true is audio is muted at a hardware level e.g user has ringer switch set to off */
-(BOOL) isDeviceMuted; //被打断
/** Returns true if another app is playing audio such as the iPod music player */
-(BOOL) isOtherAudioPlaying;

/** Sets the way the audio manager interacts with the operating system such as whether it shares output with other apps or obeys the mute switch */
-(void) setMode:(tAudioManagerMode) mode;
/** Shuts down the shared audio manager instance so that it can be reinitialised */
+(void) end;

/** Call if you want to use built in resign behavior but need to do some additional audio processing on resign active. */
- (void) applicationWillResignActive;
/** Call if you want to use built in resign behavior but need to do some additional audio processing on become active. */
- (void) applicationDidBecomeActive;

//New AVAudioPlayer API
/** Loads the data from the specified file path to the channel's audio source */
-(CDLongAudioSource*) audioSourceLoad:(NSString*) filePath channel:(tAudioSourceChannel) channel;
/** Retrieves the audio source for the specified channel */
-(CDLongAudioSource*) audioSourceForChannel:(tAudioSourceChannel) channel;

//和 simpleAudioEngine 相同的部分
//Legacy AVAudioPlayer API
/** Plays music in background. The music can be looped or not
 It is recommended to use .aac files as background music since they are decoded by the device (hardware).
 */
-(void) playBackgroundMusic:(NSString*) filePath loop:(BOOL) loop;
/** Preloads a background music */
-(void) preloadBackgroundMusic:(NSString*) filePath;
/** Stops playing the background music */
-(void) stopBackgroundMusic;
/** Pauses the background music */
-(void) pauseBackgroundMusic;
/** Rewinds the background music */
-(void) rewindBackgroundMusic;
/** Resumes playing the background music */
-(void) resumeBackgroundMusic;
/** Returns whether or not the background music is playing */
-(BOOL) isBackgroundMusicPlaying;

-(void) setBackgroundMusicCompletionListener:(id) listener selector:(SEL) selector;

@end

/** Fader for long audio source objects */
@interface CDLongAudioSourceFader : CDPropertyModifier{}
@end

static const int kCDNoBuffer = -1;

/** Allows buffers to be associated with file names */
@interface CDBufferManager:NSObject{
	NSMutableDictionary* loadedBuffers;
	NSMutableArray	*freedBuffers;
	CDSoundEngine *soundEngine;
	int nextBufferId;
}

-(id) initWithEngine:(CDSoundEngine *) theSoundEngine;
-(int) bufferForFile:(NSString*) filePath create:(BOOL) create;
-(void) releaseBufferForFile:(NSString *) filePath;

@end