src/cocoa/AngbandAudio.h

   1 /**
   2  * \file AngbandAudio.h
   3  * \brief Declare an interface for handling incidental sounds and background
   4  * music in the OS X front end.
   5  */
   6 #ifndef INCLUDED_ANGBAND_AUDIO_H
   7 #define INCLUDED_ANGBAND_AUDIO_H
   8
   9 #import <AVFAudio/AVFAudio.h>
  10
  11 @class AngbandAudioManager;
  12
  13
  14 @interface AngbandActiveAudio : NSObject <AVAudioPlayerDelegate> {
  15 @private
  16         AVAudioPlayer *player;
  17         NSTimer *fadeTimer;
  18 }
  19
  20 @property (nonatomic, readonly, getter=isPlaying) BOOL playing;
  21
  22 @property (nonatomic, readonly, weak) AngbandActiveAudio *priorAudio;
  23
  24 @property (nonatomic, readonly, strong) AngbandActiveAudio *nextAudio;
  25
  26 - (id)initWithPlayer:(AVAudioPlayer *)aPlayer fadeInBy:(NSInteger)fadeIn
  27                 prior:(AngbandActiveAudio *)p paused:(BOOL)isPaused
  28                 NS_DESIGNATED_INITIALIZER;
  29
  30 - (id)init NS_UNAVAILABLE;
  31
  32 - (void)pause;
  33
  34 - (void)resume;
  35
  36 - (void)stop;
  37
  38 - (void)fadeOutBy:(NSInteger)t;
  39
  40 - (void)changeVolumeTo:(NSInteger)v;
  41
  42 /* Methods for internal use to manage the lifetime of the active audio track. */
  43 - (void)handleFadeOutTimer:(NSTimer *)timer;
  44
  45 - (void)audioPlayerDidFinishPlaying:(AVAudioPlayer *)aPlayer
  46                 successfully:(BOOL)flag;
  47
  48 @end
  49
  50
  51 @interface AngbandAudioManager : NSObject {
  52 @private
  53         /**
  54          * These are sentinels for the beginning and end, respectively, of
  55          * the background muisc tracks currently playing in the order they
  56          * were started.
  57          */
  58         AngbandActiveAudio *tracksPlayingHead;
  59         AngbandActiveAudio *tracksPlayingTail;
  60
  61         /**
  62          * Stores instances of AVAudioPlayer keyed by path so the same
  63          * incidental sound can be used for multiple events.
  64          */
  65         NSMutableDictionary *soundsByPath;
  66
  67         /**
  68          * Stores arrays of AVAudioPlayer instances keyed by event number.
  69          */
  70         NSMutableDictionary *soundArraysByEvent;
  71
  72         /**
  73          * Stores paths to music tracks keyed first by the music type and
  74          * then the music id.
  75          */
  76         NSMutableDictionary *musicByTypeAndID;
  77
  78         /**
  79          * If NO, then do not play beeps or incidental sounds and pause
  80          * the background music track if isPausedWhenInactive is YES.
  81          */
  82         BOOL appActive;
  83 }
  84
  85 /**
  86  * Holds whether a beep will be played.  If NO, then playBeep effectively
  87  * becomes a do nothing operation.
  88  */
  89 @property (nonatomic, getter=isBeepEnabled) BOOL beepEnabled;
  90
  91 /**
  92  * Holds whether incidental sounds will be played.  If NO, then playSound
  93  * effectively becomes a do nothing operation.
  94  */
  95 @property (nonatomic, getter=isSoundEnabled) BOOL soundEnabled;
  96
  97 /**
  98  * Holds the volume (as a percentage, 0 - 100, of the system volume) for
  99  * incidental sounds.
 100  */
 101 @property (nonatomic) NSInteger soundVolume;
 102
 103 /**
 104  * Holds whether background music will be played.  If NO, then playMusicType
 105  * effectively becomes a do nothing operation.
 106  */
 107 @property (nonatomic, getter=isMusicEnabled) BOOL musicEnabled;
 108
 109 /**
 110  * Holds whether music is paused when the application is iconified or otherwise
 111  * marked as being an inactive application.  Beeps and incidental sounds are
 112  * never played when the application is an inactive application.
 113  */
 114 @property (nonatomic, getter=isMusicPausedWhenInactive)
 115                 BOOL musicPausedWhenInactive;
 116
 117 /**
 118  * Holds the volume (as a percentage, 0 - 100, of the system volume) for
 119  * background music.
 120  */
 121 @property (nonatomic) NSInteger musicVolume;
 122
 123 /**
 124  * Holds the amount of time, in milliseconds, for transitions between
 125  * different music tracks.  If less than or equal to zero, there's no
 126  * transition interval:  one track stops playing and the other starts playing
 127  * at full volume.
 128  */
 129 @property (nonatomic) NSInteger musicTransitionTime;
 130
 131 /**
 132  * Set up for lazy initialization in playSound() and playMusicType().  Set
 133  * appActive to YES, beepEnabled to YES, soundEnabled to YES, soundVolume
 134  * to 30, musicEnabled to YES, pausedWhenInactive to YES,
 135  * musicVolume to 20, and musicTransitionTime to 3000.
 136  */
 137 - (id)init;
 138
 139 /**
 140  * If self.beepEnabed is YES, make a beep.
 141  */
 142 - (void)playBeep;
 143
 144 /**
 145  * If self.soundEnabled is YES and the given event has one or more sounds
 146  * corresponding to it in the catalog, plays one of those sounds, chosen at
 147  * random.
 148  */
 149 - (void)playSound:(int)event;
 150
 151 /**
 152  * If self.musicEnabled is YES and the given music type and id exists, play
 153  * it.
 154  */
 155 - (void)playMusicType:(int)t ID:(int)i;
 156
 157 /**
 158  * Return YES if combination of the given type and ID is in the music
 159  * catalog.  Otherwise, return NO.
 160  */
 161 - (BOOL)musicExists:(int)t ID:(int)i;
 162
 163 /**
 164  * Stop all currently playing music tracks.
 165  */
 166 - (void)stopAllMusic;
 167
 168 /**
 169  * Set up to act appropiately if the containing application is inactive.
 170  */
 171 - (void)setupForInactiveApp;
 172
 173 /**
 174  * Set up to act appropriately if the containing application is active.
 175  */
 176 - (void)setupForActiveApp;
 177
 178 /**
 179  * Impose an arbitrary limit on the number of possible samples for an
 180  * incidental sound event or the background music tracks for a type/ID
 181  * combination.
 182  */
 183 @property (class, nonatomic, readonly) NSInteger maxSamples;
 184
 185 /**
 186  * Return the shared audio manager instance, creating it if it does not
 187  * exist yet.
 188  */
 189 @property (class, nonatomic, strong, readonly) AngbandAudioManager
 190                 *sharedManager;
 191
 192 /**
 193  * Release any resources associated with the shared audio manager.
 194  */
 195 + (void)clearSharedManager;
 196
 197 /**
 198  * Help playSound() to set up a catalog of the incidental sounds.
 199  */
 200 + (NSMutableDictionary *)setupSoundArraysByEvent;
 201
 202 /**
 203  * Help playMusicType() to set up a catalog of the background music.
 204  */
 205 + (NSMutableDictionary *)setupMusicByTypeAndID;
 206
 207 @end
 208
 209
 210 #endif /* include guard */