/* Copyright (c) 2010 Steve Oldmeadow Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. $Id$ */ #import "CocosDenshion.h" #if __IPHONE_OS_VERSION_MIN_REQUIRED >= 30000 #import #else #import "CDXMacOSXSupport.h" #endif /** Different modes of the engine */ typedef enum { kAMM_FxOnly, //!Other apps will be able to play audio kAMM_FxPlusMusic, //!Only this app will play audio kAMM_FxPlusMusicIfNoOtherAudio, //!If another app is playing audio at start up then allow it to continue and don't play music kAMM_MediaPlayback, //!This app takes over audio e.g music player app kAMM_PlayAndRecord //!App takes over audio and has input and output } tAudioManagerMode; /** Possible states of the engine */ typedef enum { kAMStateUninitialised, //!Audio manager has not been initialised - do not use kAMStateInitialising, //!Audio manager is in the process of initialising - do not use kAMStateInitialised //!Audio manager is initialised - safe to use } tAudioManagerState; typedef enum { kAMRBDoNothing, //Audio manager will not do anything on resign or becoming active kAMRBStopPlay, //Background music is stopped on resign and resumed on become active kAMRBStop //Background music is stopped on resign but not resumed - maybe because you want to do this from within your game } tAudioManagerResignBehavior; /** Notifications */ extern NSString * const kCDN_AudioManagerInitialised; @interface CDAsynchInitialiser : NSOperation {} @end /** CDAudioManager supports two long audio source channels called left and right*/ typedef enum { kASC_Left = 0, kASC_Right = 1 } tAudioSourceChannel; typedef enum { kLAS_Init, kLAS_Loaded, kLAS_Playing, kLAS_Paused, kLAS_Stopped, } tLongAudioSourceState; @class CDLongAudioSource; @protocol CDLongAudioSourceDelegate @optional /** The audio source completed playing */ - (void) cdAudioSourceDidFinishPlaying:(CDLongAudioSource *) audioSource; /** The file used to load the audio source has changed */ - (void) cdAudioSourceFileDidChange:(CDLongAudioSource *) audioSource; @end /** CDLongAudioSource represents an audio source that has a long duration which makes it costly to load into memory for playback as an effect using CDSoundEngine. Examples include background music and narration tracks. The audio file may or may not be compressed. Bear in mind that current iDevices can only use hardware to decode a single compressed audio file at a time and playing multiple compressed files will result in a performance drop as software decompression will take place. @since v0.99 */ @interface CDLongAudioSource : NSObject { AVAudioPlayer *audioSourcePlayer; NSString *audioSourceFilePath; NSInteger numberOfLoops; float volume; id delegate; BOOL mute; BOOL enabled_; BOOL backgroundMusic; @public BOOL systemPaused;//Used for auto resign handling NSTimeInterval systemPauseLocation;//Used for auto resign handling @protected tLongAudioSourceState state; } @property (readonly) AVAudioPlayer *audioSourcePlayer; @property (readonly) NSString *audioSourceFilePath; @property (readwrite, nonatomic) NSInteger numberOfLoops; @property (readwrite, nonatomic) float volume; @property (assign) id delegate; /* This long audio source functions as background music */ @property (readwrite, nonatomic) BOOL backgroundMusic; /** Loads the file into the audio source */ -(void) load:(NSString*) filePath; /** Plays the audio source */ -(void) play; /** Stops playing the audio soruce */ -(void) stop; /** Pauses the audio source */ -(void) pause; /** Rewinds the audio source */ -(void) rewind; /** Resumes playing the audio source if it was paused */ -(void) resume; /** Returns whether or not the audio source is playing */ -(BOOL) isPlaying; @end /** CDAudioManager manages audio requirements for a game. It provides access to a CDSoundEngine object for playing sound effects. It provides access to two CDLongAudioSource object (left and right channel) for playing long duration audio such as background music and narration tracks. Additionally it manages the audio session to take care of things like audio session interruption and interacting with the audio of other apps that are running on the device. Requirements: - Firmware: OS 2.2 or greater - Files: CDAudioManager.*, CocosDenshion.* - Frameworks: OpenAL, AudioToolbox, AVFoundation @since v0.8 */ @interface CDAudioManager : NSObject { 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; //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