Version
Wwise SDK 2021.1.10
AkiOSSoundEngine.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Version: v2021.1.10 Build: 7883
25  Copyright (c) 2006-2022 Audiokinetic Inc.
26 *******************************************************************************/
27 
28 // AkiOSSoundEngine.h
29 
30 /// \file
31 /// Main Sound Engine interface, specific iOS.
32 
33 #ifndef _AK_IOS_SOUND_ENGINE_H_
34 #define _AK_IOS_SOUND_ENGINE_H_
35 
38 
39 #include <AudioToolbox/AudioToolbox.h>
40 
41 /// The IDs of the iOS audio session categories, useful for defining app-level audio behaviours such as inter-app audio mixing policies and audio routing behaviours. These IDs are funtionally equivalent to the corresponding constants defined by the iOS audio session service backend (AVAudioSession). Refer to Xcode documentation for details on the audio session categories. The original prefix "AV" is replaced with "Ak" for the ID names.
42 ///
43 /// \remark An audio session category may demand a fixed value for a certain category options (AkAudioSessionCategoryOptions) depending on the underlying audio session services. Ensure that AkPlatformInitSettings.audioSession.eCategory and AkPlatformInitSettings.audioSession.eCategoryOptions be compatible with each other. If conflicts are detected between the user-specified audio sessoin category and category options, the sound engine will try to fix them during the initialization according to the underlying policies defined by the audio services. The policies are:
44 /// - The audio session category AkAudioSessionCategory_AmbientSound forbid the use of the category options: AkAudioSessionCategoryOptionAllowBluetooth and AkAudioSessionCategoryOptionDefaultToSpeaker.
45 /// - AkAudioSessionCategory_SoloAmbientSound forbid the use of the category options: AkAudioSessionCategoryOptionAllowBluetooth and AkAudioSessionCategoryOptionDefaultToSpeaker.
46 ///
47 /// \sa
48 /// - \ref AkPlatformInitSettings
49 /// - \ref AkAudioSessionCategoryOptions
50 /// - \ref AkAudioSessionProperties
52 {
53  AkAudioSessionCategoryAmbient, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryAmbient constant
54  AkAudioSessionCategorySoloAmbient, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategorySoloAmbient constant
55  AkAudioSessionCategoryPlayAndRecord, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayAndRecord constant
56  AkAudioSessionCategoryPlayback ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayback constant
57 };
58 
59 /// The IDs of the iOS audio session category options, used for customizing the audio session category features. These IDs are funtionally equivalent to the corresponding constants defined by the iOS audio session service backend (AVAudioSession). Refer to Xcode documentation for details on the audio session category options. The original prefix "AV" is replaced with "Ak" for the ID names.
60 ///
61 /// \sa
62 /// - \ref AkPlatformInitSettings
63 /// - \ref AkAudioSessionCategory
64 /// - \ref AkAudioSessionProperties
66 {
67  AkAudioSessionCategoryOptionMixWithOthers = 1, ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionMixWithOthers constant
68  AkAudioSessionCategoryOptionDuckOthers = 2, ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDuckOthers constant
69  AkAudioSessionCategoryOptionAllowBluetooth = 4, ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionAllowBluetooth constant
70  AkAudioSessionCategoryOptionDefaultToSpeaker = 8 ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDefaultToSpeaker constant
71 };
72 
73 /// The IDs of the iOS audio session modes, used for customizing the audio session for typical app types. These IDs are funtionally equivalent to the corresponding constants defined by the iOS audio session service backend (AVAudioSession). Refer to Xcode documentation for details on the audio session category options. The original prefix "AV" is replaced with "Ak" for the ID names.
74 ///
75 /// \sa
76 /// - \ref AkPlatformInitSettings
77 /// - \ref AkAudioSessionProperties
79 {
80  AkAudioSessionModeDefault = 0, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeDefault constant
81  AkAudioSessionModeVoiceChat, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVoiceChat constant
82  AkAudioSessionModeGameChat, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeGameChat constant
83  AkAudioSessionModeVideoRecording, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVideoRecording constant
84  AkAudioSessionModeMeasurement, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMeasurement constant
85  AkAudioSessionModeMoviePlayback, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant
86  AkAudioSessionModeVideoChat ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant
87 };
88 
89 /// The behaviour flags for when iOS audio session is activated. These IDs are funtionally equivalent to the corresponding constants defined by the iOS audio session service backend (AVAudioSession). Refer to Xcode documentation for details on the audio session category options. The original prefix "AV" is replaced with "Ak" for the ID names.
90 ///
91 /// \sa
92 /// - \ref AkPlatformInitSettings
93 /// - \ref AkAudioSessionProperties
95 {
96  AkAudioSessionSetActiveOptionNotifyOthersOnDeactivation = 1 ///< Audio session activation option corresponding to the AVAudiosession's AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation constant
97 };
98 
99 /// The API structure used with AkPlatformInitSettings for specifying iOS audio session for the sound engine.
100 ///
101 /// \sa
102 /// - \ref AkPlatformInitSettings
103 /// - \ref AkAudioSessionCategory
104 /// - \ref AkAudioSessionCategoryOptions
105 /// - \ref AkAudioSessionMode
106 /// - \ref AkAudioSessionSetActiveOptions
108 {
109  AkAudioSessionCategory eCategory; ///< \sa AkAudioSessionCategory
110  AkAudioSessionCategoryOptions eCategoryOptions; ///< \sa AkAudioSessionCategoryOptions
111  AkAudioSessionMode eMode; ///< \sa AkAudioSessionMode
112  AkAudioSessionSetActiveOptions eSetActivateOptions; ///< \sa AkAudioSessionSetActiveOptions
113 };
114 
115 namespace AK
116 {
117  namespace SoundEngine
118  {
119  namespace iOS
120  {
121  /// iOS-only callback function prototype used for audio input source plugin. Implement this function to transfer the
122  /// input sample data to the sound engine and perform brief custom processing.
123  /// \remark See the remarks of \ref AkGlobalCallbackFunc.
124  ///
125  /// \sa
126  /// - \ref AkPlatformInitSettings
128  AudioBufferList* io_Data, ///< An exposed CoreAudio structure that holds the input audio samples generated from
129  ///< audio input hardware. The buffer is pre-allocated by the sound engine and the buffer
130  ///< size can be obtained from the structure. Refer to the microphone demo of the IntegrationDemo for an example of usage.
131  void* in_pCookie ///< User-provided data, e.g., a user structure.
132  );
133 
134  /// iOS-only callback function prototype used for handling audio session interruption. It is mandatory to implement
135  /// this callback to respond to audio interruptions such as phone calls or alarms according to the application logic.
136  /// The examples of such responses include calling relevant sound engine API to suspend the device or wake up the
137  /// device from suspend, and enabling certain UI elements when an interruption happens.
138  /// \remark
139  /// - Under interruptible (non-mixable) audio session categories, the app needs to respond to audio interruptions such as phone calls, alarms, or the built-in music player control from various remote control interfaces, according to app's own policy. Such a policy may include pausing and resuming the sound engine pipeline, pausing and resuming the entire game, and updating UI elements either as the feedback to users about the interruption status, or as a means for the users to restore the audio manually if the application requires the user intervention.
140  /// - There is no need to call AK::SoundEngine::Suspend() and AK::SoundEngine::WakeupFromSuspend() in this callback. The sound engine call them internally depending on the interruption status.
141  /// - When in_bEnterInterruption is true, this callback is called before the sound engine calls AK::SoundEngine::Suspend(), where user can take actions to prepare for the suspend, e.g., posting global pause events or switching to a special user interface; when in_bEnterInterruption is false, this callback is called after the sound engine calls AK::SoundEngine::WakeFromSuspend() and only when waking up succeeds, so that user can restore suspended resources, e.g., post global resume events or switching back to default user interface. This is useful for games in which audio is essential to the gameplay.
142  /// - Under the AkAudioSessionCategorySoloAmbient audio session category, to avoid remote-control-related audio loss, any pause event posted in this callback when entering interruption needs to be paired with a resume event in the AudioSourceChangeCallbackFunc's conditional branch for when other app's audio is not playing. This is because by Apple's design, under this category, the end of interruption will trigger the source change callback instead of the interruption callback if the interruption source is the user music.
143  /// - Starting from iOS 7, under the AkAudioSessionCategorySoloAmbient audio session category, this callback will be triggered with an end-of-interruption flag when app returns to the foreground from previous backgrounding, e.g., after a home-screen-and-back cycle, or a locking-unlocking cycle. It is triggered after the applicationDidBecomeActive: call. This means that the background music decisions made within applicationDidBecomeActive: can be overriden by the interruption callback.
144  ///
145  /// \sa
146  /// - \ref AkGlobalCallbackFunc
147  /// - \ref AkPlatformInitSettings
148  /// - \ref AK::SoundEngine::Suspend
149  /// - \ref AK::SoundEngine::WakeupFromSuspend
151  bool in_bEnterInterruption, ///< Indicating whether or not an interruption is about to start (e.g., an incoming
152  ///< call is received) or end (e.g., the incoming call is dismissed).
153 
154  void* in_pCookie ///< User-provided data, e.g., a user structure.
155  );
156  }
157  }
158 }
159 
160 /// The API structure used for specifying all iOS-specific callback functions and user data from the app side.
161 ///
162 /// \sa
163 /// - \ref AkPlatformInitSettings
165 {
166  AK::SoundEngine::iOS::AudioInputCallbackFunc inputCallback; ///< Application-defined audio input callback function
167  void* inputCallbackCookie; ///< Application-defined user data for the audio input callback function
168  AK::SoundEngine::iOS::AudioInterruptionCallbackFunc interruptionCallback; ///< Application-defined audio interruption callback function
169  void* interruptionCallbackCookie; ///< Application-defined user data for the audio interruption callback function
170 };
171 
172 /// \cond !(Web)
173 /// Platform specific initialization settings
174 /// \sa AK::SoundEngine::Init
175 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
176 /// - \ref AK::SoundEngine::iOS::AkAudioSessionCategory
178 {
179  // Threading model.
180  AkThreadProperties threadLEngine; ///< Lower engine threading properties
181  AkThreadProperties threadOutputMgr; ///< Ouput thread threading properties
182  AkThreadProperties threadBankManager; ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
183  AkThreadProperties threadMonitor; ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
184 
185  AkUInt32 uSampleRate; ///< Sampling Rate. Default 48000 Hz
186  // Voices.
187  AkUInt16 uNumRefillsInVoice; ///< Number of refill buffers in voice buffer. 2 == double-buffered, defaults to 4
188  AkAudioSessionProperties audioSession; ///< iOS audio session properties
189  AkAudioCallbacks audioCallbacks; ///< iOS audio callbacks
190 };
191 /// \endcond
192 
193 
194 #endif //_AK_IOS_SOUND_ENGINE_H_
Audiokinetic namespace.
@ AkAudioSessionCategoryOptionMixWithOthers
Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionMixWi...
Definition: AkiOSSoundEngine.h:67
@ AkAudioSessionCategoryPlayback
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayback constant.
Definition: AkiOSSoundEngine.h:56
AkAudioSessionCategoryOptions eCategoryOptions
AkAudioSessionCategory
Definition: AkiOSSoundEngine.h:52
AkAudioSessionMode
Definition: AkiOSSoundEngine.h:79
AK::SoundEngine::iOS::AudioInputCallbackFunc inputCallback
Application-defined audio input callback function.
@ AkAudioSessionCategoryOptionAllowBluetooth
Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionAllow...
Definition: AkiOSSoundEngine.h:69
AKRESULT
Standard function call result.
Definition: AkTypes.h:127
AkAudioSessionCategory eCategory
AK::SoundEngine::iOS::AudioInterruptionCallbackFunc interruptionCallback
Application-defined audio interruption callback function.
void * inputCallbackCookie
Application-defined user data for the audio input callback function.
@ AkAudioSessionModeMeasurement
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMeasurement constant.
Definition: AkiOSSoundEngine.h:84
@ AkAudioSessionModeDefault
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeDefault constant.
Definition: AkiOSSoundEngine.h:80
AKRESULT(* AudioInterruptionCallbackFunc)(bool in_bEnterInterruption, void *in_pCookie)
@ AkAudioSessionCategorySoloAmbient
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategorySoloAmbient consta...
Definition: AkiOSSoundEngine.h:54
@ AkAudioSessionModeVideoChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant.
Definition: AkiOSSoundEngine.h:86
@ AkAudioSessionCategoryAmbient
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryAmbient constant.
Definition: AkiOSSoundEngine.h:53
@ AkAudioSessionSetActiveOptionNotifyOthersOnDeactivation
Audio session activation option corresponding to the AVAudiosession's AVAudioSessionSetActiveOptionNo...
Definition: AkiOSSoundEngine.h:96
@ AkAudioSessionCategoryPlayAndRecord
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayAndRecord cons...
Definition: AkiOSSoundEngine.h:55
@ AkAudioSessionCategoryOptionDefaultToSpeaker
Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDefau...
Definition: AkiOSSoundEngine.h:70
AkAudioSessionMode eMode
uint16_t AkUInt16
Unsigned 16-bit integer.
Definition: AkTypes.h:58
@ AkAudioSessionModeVoiceChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVoiceChat constant.
Definition: AkiOSSoundEngine.h:81
AkAudioSessionCategoryOptions
Definition: AkiOSSoundEngine.h:66
@ AkAudioSessionModeGameChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeGameChat constant.
Definition: AkiOSSoundEngine.h:82
AKRESULT(* AudioInputCallbackFunc)(AudioBufferList *io_Data, void *in_pCookie)
AkAudioSessionSetActiveOptions
Definition: AkiOSSoundEngine.h:95
void * interruptionCallbackCookie
Application-defined user data for the audio interruption callback function.
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:59
@ AkAudioSessionModeVideoRecording
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVideoRecording constant.
Definition: AkiOSSoundEngine.h:83
AkAudioSessionSetActiveOptions eSetActivateOptions
@ AkAudioSessionCategoryOptionDuckOthers
Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDuckO...
Definition: AkiOSSoundEngine.h:68
AK_ID_DECLARE BasePlatformID iOS
Definition: PlatformID.h:103
@ AkAudioSessionModeMoviePlayback
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant.
Definition: AkiOSSoundEngine.h:85