Version
menu_open
link
Wwise SDK 2022.1.7
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  Copyright (c) 2023 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 // AkiOSSoundEngine.h
28 
29 /// \file
30 /// Main Sound Engine interface, specific iOS.
31 
32 #ifndef _AK_IOS_SOUND_ENGINE_H_
33 #define _AK_IOS_SOUND_ENGINE_H_
34 
35 #include <AK/SoundEngine/Common/AkTypes.h>
36 #include <AK/Tools/Common/AkPlatformFuncs.h>
37 
38 #include <AudioToolbox/AudioToolbox.h>
39 
40 /// 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.
41 ///
42 /// \sa
43 /// - \ref AkPlatformInitSettings
44 /// - \ref AkAudioSessionCategoryOptions
45 /// - \ref AkAudioSessionProperties
46 enum AkAudioSessionCategory
47 {
48  AkAudioSessionCategoryAmbient, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryAmbient constant
49  AkAudioSessionCategorySoloAmbient, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategorySoloAmbient constant
50  AkAudioSessionCategoryPlayAndRecord, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayAndRecord constant
51  AkAudioSessionCategoryPlayback ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayback constant
52 };
53 
54 /// 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.
55 /// \remark These options only have an effect with specific audio session categories. See the documentation for each option to learn which category they affect.
56 ///
57 /// \sa
58 /// - \ref AkPlatformInitSettings
59 /// - \ref AkAudioSessionCategory
60 /// - \ref AkAudioSessionProperties
61 enum AkAudioSessionCategoryOptions
62 {
63  AkAudioSessionCategoryOptionMixWithOthers = 1, ///< Same as AVAudioSessionCategoryOptionMixWithOthers. Only affects PlayAndRecord and Playback categories.
64  AkAudioSessionCategoryOptionDuckOthers = 2, ///< Same as AVAudioSessionCategoryOptionDuckOthers. Implicitely sets the MixWithOthers option. Only affects PlayAndRecord and Playback categories.
65  AkAudioSessionCategoryOptionAllowBluetooth = 4, ///< Same as AVAudioSessionCategoryOptionAllowBluetooth. Only affects PlayAndRecord category.
66  AkAudioSessionCategoryOptionDefaultToSpeaker = 8, ///< Same as AVAudioSessionCategoryOptionDefaultToSpeaker. Only affects PlayAndRecord category.
67  AkAudioSessionCategoryOptionAllowBluetoothA2DP = 0x20 ///< Same as AVAudioSessionCategoryOptionAllowBluetoothA2DP. Only affects PlayAndRecord category.
68 };
69 
70 /// 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.
71 ///
72 /// \sa
73 /// - \ref AkPlatformInitSettings
74 /// - \ref AkAudioSessionProperties
75 enum AkAudioSessionMode
76 {
77  AkAudioSessionModeDefault = 0, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeDefault constant
78  AkAudioSessionModeVoiceChat, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVoiceChat constant
79  AkAudioSessionModeGameChat, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeGameChat constant
80  AkAudioSessionModeVideoRecording, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVideoRecording constant
81  AkAudioSessionModeMeasurement, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMeasurement constant
82  AkAudioSessionModeMoviePlayback, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant
83  AkAudioSessionModeVideoChat ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant
84 };
85 
86 /// The behavior flags for when iOS audio session is activated. These IDs are functionally equivalent to the corresponding constants defined by the iOS audio session service backend (AVAudioSession). Refer to Xcode documentation for details on the audio session options. The original prefix "AV" is replaced with "Ak" for the ID names.
87 ///
88 /// \sa
89 /// - \ref AkPlatformInitSettings
90 /// - \ref AkAudioSessionProperties
91 enum AkAudioSessionSetActiveOptions
92 {
93  AkAudioSessionSetActiveOptionNotifyOthersOnDeactivation = 1 ///< Audio session activation option corresponding to the AVAudiosession's AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation constant
94 };
95 
96 /// Flags that can modify the default Sound Engine behavior related to the management of the audio session. These do not have equivalences in the official iOS SDK; they apply uniquely to Wwise's approach to interruption handling.
97 enum AkAudioSessionBehaviorOptions
98 {
99  AkAudioSessionBehaviorSuspendInBackground = 0x1 ///< By default, the Sound Engine continues to render audio in the background when using PlayAndRecord or Playback categories. Setting this flag causes the Sound Engine to suspend audio rendering when in the background, thus disabling background audio. Only affects Playback and PlayAndRecord audio session categories.
100 };
101 
102 /// The API structure used with AkPlatformInitSettings for specifying iOS audio session for the sound engine.
103 ///
104 /// \sa
105 /// - \ref AkPlatformInitSettings
106 /// - \ref AkAudioSessionCategory
107 /// - \ref AkAudioSessionCategoryOptions
108 /// - \ref AkAudioSessionMode
109 /// - \ref AkAudioSessionSetActiveOptions
110 struct AkAudioSessionProperties
111 {
112  AkAudioSessionCategory eCategory; ///< \sa AkAudioSessionCategory
113  AkAudioSessionCategoryOptions eCategoryOptions; ///< \sa AkAudioSessionCategoryOptions
114  AkAudioSessionMode eMode; ///< \sa AkAudioSessionMode
115  AkAudioSessionSetActiveOptions eSetActivateOptions; ///< \sa AkAudioSessionSetActiveOptions
116  AkAudioSessionBehaviorOptions eAudioSessionBehavior; ///< Flags to change the default Sound Engine behavior related to the management of the iOS Audio Session with regards to application lifecycle events. \sa AkAudioSessionBehaviorFlags
117 };
118 
119 namespace AK
120 {
121  namespace SoundEngine
122  {
123  namespace iOS
124  {
125  /// iOS-only callback function prototype used for audio input source plugin. Implement this function to transfer the
126  /// input sample data to the sound engine and perform brief custom processing.
127  /// \remark See the remarks of \ref AkGlobalCallbackFunc.
128  ///
129  /// \sa
130  /// - \ref AkPlatformInitSettings
131  typedef AKRESULT ( * AudioInputCallbackFunc )(
132  AudioBufferList* io_Data, ///< An exposed CoreAudio structure that holds the input audio samples generated from
133  ///< audio input hardware. The buffer is pre-allocated by the sound engine and the buffer
134  ///< size can be obtained from the structure. Refer to the microphone demo of the IntegrationDemo for an example of usage.
135  void* in_pCookie ///< User-provided data, e.g., a user structure.
136  );
137 
138  /// iOS-only callback function prototype used for handling audio session interruptions.
139  /// Implementing this is optional, but useful for application-specific responses to interruptions. For example, an application can enable or disable certain UI elements when an interruption begins and ends.
140  /// \remark
141  /// - 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.
142  /// - When in_bEnterInterruption is true, this callback is called \a before the sound engine calls AK::SoundEngine::Suspend(), where the user can take actions to prepare for the suspend, e.g., posting global pause events or switching to a special user interface.
143  /// - When in_bEnterInterruption is false, this callback is called \a before the sound engine calls AK::SoundEngine::WakeFromSuspend(). In this callback, the user can restore suspended resources, e.g., post global resume events or switch back to the default user interface.
144  /// - To receive a callback \a after the Sound Engine has woken up from suspend after an interruption, use AK::SoundEngine::RegisterGlobalCallback with the AkGlobalCallbackLocation_WakeupFromSuspend location instead.
145  ///
146  /// \sa
147  /// - \ref AkGlobalCallbackFunc
148  /// - \ref AkPlatformInitSettings
149  /// - \ref AK::SoundEngine::Suspend
150  /// - \ref AK::SoundEngine::WakeupFromSuspend
151  /// - \ref AK::SoundEngine::RegisterGlobalCallback
152  typedef void ( * AudioInterruptionCallbackFunc )(
153  bool in_bEnterInterruption, ///< Indicating whether or not an interruption is about to start (e.g., an incoming
154  ///< call is received) or end (e.g., the incoming call is dismissed).
155 
156  void* in_pCookie ///< User-provided data, e.g., a user structure.
157  );
158 
159  /// Change the category and options of the app's AVAudioSession without restarting the entire Sound Engine.
160  /// \remark
161  /// As per Apple recommendations, the AVAudioSession will be deactivated and then reactivated. Therefore,
162  /// the primary output device must be reinitialized, which causes all audio to stop for a short period of time.
163  /// For a seamless transition, call this API during moments of complete silence in your game.
164  ///
165  /// \sa
166  /// - \ref AkAudioSessionProperties
167  AK_EXTERNAPIFUNC( void, ChangeAudioSessionProperties )(
168  const AkAudioSessionProperties &in_properties ///< New properties to apply to the app's AVAudioSession shared instance.
169  );
170  }
171  }
172 }
173 
174 /// The API structure used for specifying all iOS-specific callback functions and user data from the app side.
175 ///
176 /// \sa
177 /// - \ref AkPlatformInitSettings
178 struct AkAudioCallbacks
179 {
180  AK::SoundEngine::iOS::AudioInputCallbackFunc inputCallback; ///< Application-defined audio input callback function
181  void* inputCallbackCookie; ///< Application-defined user data for the audio input callback function
182  AK::SoundEngine::iOS::AudioInterruptionCallbackFunc interruptionCallback; ///< Application-defined audio interruption callback function
183  void* interruptionCallbackCookie; ///< Application-defined user data for the audio interruption callback function
184 };
185 
186 /// \cond !(Web)
187 /// Platform specific initialization settings
188 /// \sa AK::SoundEngine::Init
189 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
190 /// - \ref AK::SoundEngine::iOS::AkAudioSessionCategory
191 struct AkPlatformInitSettings
192 {
193  // Threading model.
194  AkThreadProperties threadLEngine; ///< Lower engine threading properties
195  AkThreadProperties threadOutputMgr; ///< Ouput thread threading properties
196  AkThreadProperties threadBankManager; ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
197  AkThreadProperties threadMonitor; ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
198 
199  AkUInt32 uSampleRate; ///< Sampling Rate. Default 48000 Hz
200  // Voices.
201  AkUInt16 uNumRefillsInVoice; ///< Number of refill buffers in voice buffer. 2 == double-buffered, defaults to 4
202  AkAudioSessionProperties audioSession; ///< iOS audio session properties
203  AkAudioCallbacks audioCallbacks; ///< iOS audio callbacks
204 
205  bool bVerboseSystemOutput; ///< Print additional debugging information specific to iOS to the system output log.
206 };
207 /// \endcond
208 
209 
210 #endif //_AK_IOS_SOUND_ENGINE_H_
AkUInt16
uint16_t AkUInt16
Unsigned 16-bit integer.
Definition: AkNumeralTypes.h:37
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:31
AkAudioSessionCategoryOptionMixWithOthers
@ AkAudioSessionCategoryOptionMixWithOthers
Same as AVAudioSessionCategoryOptionMixWithOthers. Only affects PlayAndRecord and Playback categories...
Definition: AkiOSSoundEngine.h:63
AkAudioSessionCategoryPlayback
@ AkAudioSessionCategoryPlayback
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayback constant.
Definition: AkiOSSoundEngine.h:51
AkAudioSessionProperties::eCategoryOptions
AkAudioSessionCategoryOptions eCategoryOptions
Definition: AkiOSSoundEngine.h:113
AkAudioSessionCategory
AkAudioSessionCategory
Definition: AkiOSSoundEngine.h:47
AkAudioSessionMode
AkAudioSessionMode
Definition: AkiOSSoundEngine.h:76
AK::SoundEngine::iOS::ChangeAudioSessionProperties
AKSOUNDENGINE_API void ChangeAudioSessionProperties(const AkAudioSessionProperties &in_properties)
AkAudioCallbacks::inputCallback
AK::SoundEngine::iOS::AudioInputCallbackFunc inputCallback
Application-defined audio input callback function.
Definition: AkiOSSoundEngine.h:180
AK_EXTERNAPIFUNC
#define AK_EXTERNAPIFUNC(_type, _name)
Definition: AkSoundEngineExport.h:81
AkAudioSessionCategoryOptionAllowBluetooth
@ AkAudioSessionCategoryOptionAllowBluetooth
Same as AVAudioSessionCategoryOptionAllowBluetooth. Only affects PlayAndRecord category.
Definition: AkiOSSoundEngine.h:65
AKRESULT
AKRESULT
Standard function call result.
Definition: AkTypes.h:199
AkAudioSessionProperties::eCategory
AkAudioSessionCategory eCategory
Definition: AkiOSSoundEngine.h:112
AkAudioCallbacks::interruptionCallback
AK::SoundEngine::iOS::AudioInterruptionCallbackFunc interruptionCallback
Application-defined audio interruption callback function.
Definition: AkiOSSoundEngine.h:182
AkAudioCallbacks::inputCallbackCookie
void * inputCallbackCookie
Application-defined user data for the audio input callback function.
Definition: AkiOSSoundEngine.h:181
AkAudioSessionModeMeasurement
@ AkAudioSessionModeMeasurement
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMeasurement constant.
Definition: AkiOSSoundEngine.h:81
AkAudioSessionBehaviorOptions
AkAudioSessionBehaviorOptions
Flags that can modify the default Sound Engine behavior related to the management of the audio sessio...
Definition: AkiOSSoundEngine.h:98
AkAudioSessionModeDefault
@ AkAudioSessionModeDefault
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeDefault constant.
Definition: AkiOSSoundEngine.h:77
AkAudioSessionCategorySoloAmbient
@ AkAudioSessionCategorySoloAmbient
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategorySoloAmbient consta...
Definition: AkiOSSoundEngine.h:49
AK::SoundEngine::iOS::AudioInterruptionCallbackFunc
void(* AudioInterruptionCallbackFunc)(bool in_bEnterInterruption, void *in_pCookie)
Definition: AkiOSSoundEngine.h:152
AkAudioSessionModeVideoChat
@ AkAudioSessionModeVideoChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant.
Definition: AkiOSSoundEngine.h:83
AkAudioSessionCategoryAmbient
@ AkAudioSessionCategoryAmbient
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryAmbient constant.
Definition: AkiOSSoundEngine.h:48
AkAudioSessionProperties::eAudioSessionBehavior
AkAudioSessionBehaviorOptions eAudioSessionBehavior
Flags to change the default Sound Engine behavior related to the management of the iOS Audio Session ...
Definition: AkiOSSoundEngine.h:116
AkAudioSessionSetActiveOptionNotifyOthersOnDeactivation
@ AkAudioSessionSetActiveOptionNotifyOthersOnDeactivation
Audio session activation option corresponding to the AVAudiosession's AVAudioSessionSetActiveOptionNo...
Definition: AkiOSSoundEngine.h:93
AkAudioSessionCategoryPlayAndRecord
@ AkAudioSessionCategoryPlayAndRecord
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayAndRecord cons...
Definition: AkiOSSoundEngine.h:50
AkAudioSessionCategoryOptionDefaultToSpeaker
@ AkAudioSessionCategoryOptionDefaultToSpeaker
Same as AVAudioSessionCategoryOptionDefaultToSpeaker. Only affects PlayAndRecord category.
Definition: AkiOSSoundEngine.h:66
AkAudioSessionProperties::eMode
AkAudioSessionMode eMode
Definition: AkiOSSoundEngine.h:114
AkAudioSessionModeVoiceChat
@ AkAudioSessionModeVoiceChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVoiceChat constant.
Definition: AkiOSSoundEngine.h:78
AkAudioSessionBehaviorSuspendInBackground
@ AkAudioSessionBehaviorSuspendInBackground
By default, the Sound Engine continues to render audio in the background when using PlayAndRecord or ...
Definition: AkiOSSoundEngine.h:99
AkAudioSessionCategoryOptions
AkAudioSessionCategoryOptions
Definition: AkiOSSoundEngine.h:62
AkAudioSessionModeGameChat
@ AkAudioSessionModeGameChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeGameChat constant.
Definition: AkiOSSoundEngine.h:79
AkAudioSessionCategoryOptionAllowBluetoothA2DP
@ AkAudioSessionCategoryOptionAllowBluetoothA2DP
Same as AVAudioSessionCategoryOptionAllowBluetoothA2DP. Only affects PlayAndRecord category.
Definition: AkiOSSoundEngine.h:67
AK::SoundEngine::iOS::AudioInputCallbackFunc
AKRESULT(* AudioInputCallbackFunc)(AudioBufferList *io_Data, void *in_pCookie)
Definition: AkiOSSoundEngine.h:131
AkAudioSessionSetActiveOptions
AkAudioSessionSetActiveOptions
Definition: AkiOSSoundEngine.h:92
AkAudioCallbacks::interruptionCallbackCookie
void * interruptionCallbackCookie
Application-defined user data for the audio interruption callback function.
Definition: AkiOSSoundEngine.h:183
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:38
AkAudioSessionModeVideoRecording
@ AkAudioSessionModeVideoRecording
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVideoRecording constant.
Definition: AkiOSSoundEngine.h:80
AkAudioSessionProperties::eSetActivateOptions
AkAudioSessionSetActiveOptions eSetActivateOptions
Definition: AkiOSSoundEngine.h:115
AkAudioSessionCategoryOptionDuckOthers
@ AkAudioSessionCategoryOptionDuckOthers
Same as AVAudioSessionCategoryOptionDuckOthers. Implicitely sets the MixWithOthers option....
Definition: AkiOSSoundEngine.h:64
PlatformID::iOS
AK_ID_DECLARE BasePlatformID iOS
Definition: PlatformID.h:102
AkAudioSessionModeMoviePlayback
@ AkAudioSessionModeMoviePlayback
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant.
Definition: AkiOSSoundEngine.h:82

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise