Version
menu_open
link
Wwise SDK 2022.1.4
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 
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
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
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
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
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.
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
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
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
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
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
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_
uint16_t AkUInt16
Unsigned 16-bit integer.
Definition: AkNumeralTypes.h:37
Audiokinetic namespace.
@ AkAudioSessionCategoryOptionMixWithOthers
Same as AVAudioSessionCategoryOptionMixWithOthers. Only affects PlayAndRecord and Playback categories...
Definition: AkiOSSoundEngine.h:63
@ AkAudioSessionCategoryPlayback
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayback constant.
Definition: AkiOSSoundEngine.h:51
AkAudioSessionCategoryOptions eCategoryOptions
AkAudioSessionCategory
Definition: AkiOSSoundEngine.h:47
AkAudioSessionMode
Definition: AkiOSSoundEngine.h:76
AKSOUNDENGINE_API void ChangeAudioSessionProperties(const AkAudioSessionProperties &in_properties)
AK::SoundEngine::iOS::AudioInputCallbackFunc inputCallback
Application-defined audio input callback function.
#define AK_EXTERNAPIFUNC(_type, _name)
@ AkAudioSessionCategoryOptionAllowBluetooth
Same as AVAudioSessionCategoryOptionAllowBluetooth. Only affects PlayAndRecord category.
Definition: AkiOSSoundEngine.h:65
AKRESULT
Standard function call result.
Definition: AkTypes.h:193
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:81
AkAudioSessionBehaviorOptions
Flags that can modify the default Sound Engine behavior related to the management of the audio sessio...
Definition: AkiOSSoundEngine.h:98
@ AkAudioSessionModeDefault
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeDefault constant.
Definition: AkiOSSoundEngine.h:77
@ AkAudioSessionCategorySoloAmbient
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategorySoloAmbient consta...
Definition: AkiOSSoundEngine.h:49
void(* AudioInterruptionCallbackFunc)(bool in_bEnterInterruption, void *in_pCookie)
@ AkAudioSessionModeVideoChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant.
Definition: AkiOSSoundEngine.h:83
@ AkAudioSessionCategoryAmbient
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryAmbient constant.
Definition: AkiOSSoundEngine.h:48
AkAudioSessionBehaviorOptions eAudioSessionBehavior
Flags to change the default Sound Engine behavior related to the management of the iOS Audio Session ...
@ AkAudioSessionSetActiveOptionNotifyOthersOnDeactivation
Audio session activation option corresponding to the AVAudiosession's AVAudioSessionSetActiveOptionNo...
Definition: AkiOSSoundEngine.h:93
@ AkAudioSessionCategoryPlayAndRecord
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayAndRecord cons...
Definition: AkiOSSoundEngine.h:50
@ AkAudioSessionCategoryOptionDefaultToSpeaker
Same as AVAudioSessionCategoryOptionDefaultToSpeaker. Only affects PlayAndRecord category.
Definition: AkiOSSoundEngine.h:66
AkAudioSessionMode eMode
@ AkAudioSessionModeVoiceChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVoiceChat constant.
Definition: AkiOSSoundEngine.h:78
@ AkAudioSessionBehaviorSuspendInBackground
By default, the Sound Engine continues to render audio in the background when using PlayAndRecord or ...
Definition: AkiOSSoundEngine.h:99
AkAudioSessionCategoryOptions
Definition: AkiOSSoundEngine.h:62
@ AkAudioSessionModeGameChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeGameChat constant.
Definition: AkiOSSoundEngine.h:79
@ AkAudioSessionCategoryOptionAllowBluetoothA2DP
Same as AVAudioSessionCategoryOptionAllowBluetoothA2DP. Only affects PlayAndRecord category.
Definition: AkiOSSoundEngine.h:67
AKRESULT(* AudioInputCallbackFunc)(AudioBufferList *io_Data, void *in_pCookie)
AkAudioSessionSetActiveOptions
Definition: AkiOSSoundEngine.h:92
void * interruptionCallbackCookie
Application-defined user data for the audio interruption callback function.
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:38
@ AkAudioSessionModeVideoRecording
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVideoRecording constant.
Definition: AkiOSSoundEngine.h:80
AkAudioSessionSetActiveOptions eSetActivateOptions
@ AkAudioSessionCategoryOptionDuckOthers
Same as AVAudioSessionCategoryOptionDuckOthers. Implicitely sets the MixWithOthers option....
Definition: AkiOSSoundEngine.h:64
AK_ID_DECLARE BasePlatformID iOS
Definition: PlatformID.h:102
@ 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