Version
menu_open
Wwise SDK 2023.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) 2024 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 ///< API used for audio output
120 ///< Use with AkPlatformInitSettings to select the API used for audio output. The selected API may be ignored if the device does not support it.
121 ///< Use AkAPI_Default, it will select the more appropriate API depending on the device's capabilities. Other values should be used for testing purposes.
122 ///< \sa AK::SoundEngine::Init
123 typedef enum AkAudioAPIiOS
124 {
125  AkAudioAPI_AVAudioEngine = 1 << 0, ///< Use AVFoundation framework (modern, has more capabilities, not available for iOS/tvOS 12 or below)
126  AkAudioAPI_AudioUnit = 1 << 1, ///< Use AudioUnit framework (basic functionality, compatible with all iOS devices)
127  AkAudioAPI_Default = AkAudioAPI_AVAudioEngine | AkAudioAPI_AudioUnit, ///< Default value, will select the more appropriate API (AVAudioEngine for compatible devices, AudioUnit for others)
128 } AkAudioAPI;
129 
130 namespace AK
131 {
132  namespace SoundEngine
133  {
134  namespace iOS
135  {
136  /// iOS-only callback function prototype used for audio input source plugin. Implement this function to transfer the
137  /// input sample data to the sound engine and perform brief custom processing.
138  /// \remark See the remarks of \ref AkGlobalCallbackFunc.
139  ///
140  /// \sa
141  /// - \ref AkPlatformInitSettings
143  const AudioBufferList* io_Data, ///< An exposed CoreAudio structure that holds the input audio samples generated from
144  ///< audio input hardware. The buffer is pre-allocated by the sound engine and the buffer
145  ///< size can be obtained from the structure. Refer to the microphone demo of the IntegrationDemo for an example of usage.
146  void* in_pCookie ///< User-provided data, e.g., a user structure.
147  );
148 
149  /// iOS-only callback function prototype used for handling audio session interruptions.
150  /// 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.
151  /// \remark
152  /// - 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.
153  /// - 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.
154  /// - 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.
155  /// - 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.
156  ///
157  /// \sa
158  /// - \ref AkGlobalCallbackFunc
159  /// - \ref AkPlatformInitSettings
160  /// - \ref AK::SoundEngine::Suspend
161  /// - \ref AK::SoundEngine::WakeupFromSuspend
162  /// - \ref AK::SoundEngine::RegisterGlobalCallback
163  typedef void ( * AudioInterruptionCallbackFunc )(
164  bool in_bEnterInterruption, ///< Indicating whether or not an interruption is about to start (e.g., an incoming
165  ///< call is received) or end (e.g., the incoming call is dismissed).
166 
167  void* in_pCookie ///< User-provided data, e.g., a user structure.
168  );
169 
170  /// Change the category and options of the app's AVAudioSession without restarting the entire Sound Engine.
171  /// \remark
172  /// As per Apple recommendations, the AVAudioSession will be deactivated and then reactivated. Therefore,
173  /// the primary output device must be reinitialized, which causes all audio to stop for a short period of time.
174  /// For a seamless transition, call this API during moments of complete silence in your game.
175  ///
176  /// \sa
177  /// - \ref AkAudioSessionProperties
179  const AkAudioSessionProperties &in_properties ///< New properties to apply to the app's AVAudioSession shared instance.
180  );
181  }
182 
183  /// Get the motion device ID corresponding to a GCController player index. This device ID can be used to add/remove motion output for that gamepad.
184  /// The player index is 0-based, and corresponds to a value of type GCControllerPlayerIndex in the Core.Haptics framework.
185  /// \note The ID returned is unique to Wwise and does not correspond to any sensible value outside of Wwise.
186  /// \return Unique device ID
188  }
189 }
190 
191 /// The API structure used for specifying all iOS-specific callback functions and user data from the app side.
192 ///
193 /// \sa
194 /// - \ref AkPlatformInitSettings
196 {
197  AK::SoundEngine::iOS::AudioInputCallbackFunc inputCallback; ///< Application-defined audio input callback function
198  void* inputCallbackCookie; ///< Application-defined user data for the audio input callback function
199  AK::SoundEngine::iOS::AudioInterruptionCallbackFunc interruptionCallback; ///< Application-defined audio interruption callback function
200  void* interruptionCallbackCookie; ///< Application-defined user data for the audio interruption callback function
201 };
202 
203 /// Platform specific initialization settings
204 /// \sa AK::SoundEngine::Init
205 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
206 /// - \ref AK::SoundEngine::iOS::AkAudioSessionCategory
208 {
209  // Threading model.
210  AkThreadProperties threadLEngine; ///< Lower engine threading properties
211  AkThreadProperties threadOutputMgr; ///< Ouput thread threading properties
212  AkThreadProperties threadBankManager; ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
213  AkThreadProperties threadMonitor; ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
214 
215  AkUInt32 uSampleRate; ///< Sampling Rate. Default 48000 Hz
216  // Voices.
217  AkUInt16 uNumRefillsInVoice; ///< Number of refill buffers in voice buffer. 2 == double-buffered, defaults to 4
218  AkAudioSessionProperties audioSession; ///< iOS audio session properties
219  AkAudioCallbacks audioCallbacks; ///< iOS audio callbacks
220 
221  AkAudioAPI eAudioAPI; ///< Main audio API to use. Leave to AkAPI_Default for the default sink (default value).
222  ///< \ref AkAudioAPI
223 
224  AkUInt32 uNumSpatialAudioPointSources; ///< Number of Apple Spatial Audio point sources to allocate for 3D audio use (each point source is a system audio object). Default: 128
225 
226  bool bVerboseSystemOutput; ///< Print additional debugging information specific to iOS to the system output log.
227 };
228 
229 
230 #endif //_AK_IOS_SOUND_ENGINE_H_
AkAudioAPI
uint16_t AkUInt16
Unsigned 16-bit integer.
Audiokinetic namespace.
@ AkAudioSessionCategoryOptionMixWithOthers
Same as AVAudioSessionCategoryOptionMixWithOthers. Only affects PlayAndRecord and Playback categories...
AkAudioSessionProperties audioSession
iOS audio session properties
@ AkAudioSessionCategoryPlayback
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayback constant.
AkAudioSessionCategoryOptions eCategoryOptions
AkAudioSessionCategory
AkAudioSessionMode
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.
AKRESULT
Standard function call result.
Definition: AkTypes.h:131
AkAudioSessionCategory eCategory
AkUInt32 AkDeviceID
I/O device ID.
Definition: AkTypes.h:78
AKRESULT(* AudioInputCallbackFunc)(const AudioBufferList *io_Data, void *in_pCookie)
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.
AkAudioSessionBehaviorOptions
Flags that can modify the default Sound Engine behavior related to the management of the audio sessio...
AkThreadProperties threadMonitor
Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL)....
AkThreadProperties threadLEngine
Lower engine threading properties.
@ AkAudioSessionModeDefault
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeDefault constant.
@ AkAudioAPI_Default
Default value, will select the more appropriate API (AVAudioEngine for compatible devices,...
AkUInt16 uNumRefillsInVoice
Number of refill buffers in voice buffer. Defaults to 4.
@ AkAudioSessionCategorySoloAmbient
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategorySoloAmbient consta...
void(* AudioInterruptionCallbackFunc)(bool in_bEnterInterruption, void *in_pCookie)
@ AkAudioSessionModeVideoChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant.
@ AkAudioSessionCategoryAmbient
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryAmbient constant.
AkUInt32 uNumSpatialAudioPointSources
Number of Apple Spatial Audio point sources to allocate for 3D audio use (each point source is a syst...
AkAudioSessionBehaviorOptions eAudioSessionBehavior
Flags to change the default Sound Engine behavior related to the management of the iOS Audio Session ...
AkThreadProperties threadOutputMgr
Ouput thread threading properties.
@ AkAudioSessionSetActiveOptionNotifyOthersOnDeactivation
Audio session activation option corresponding to the AVAudiosession's AVAudioSessionSetActiveOptionNo...
bool bVerboseSystemOutput
Print additional debugging information specific to iOS to the system output log.
@ AkAudioSessionCategoryPlayAndRecord
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayAndRecord cons...
@ AkAudioSessionCategoryOptionDefaultToSpeaker
Same as AVAudioSessionCategoryOptionDefaultToSpeaker. Only affects PlayAndRecord category.
AkAudioSessionMode eMode
@ AkAudioAPI_AudioUnit
Use AudioUnit framework (basic functionality, compatible with all iOS devices)
@ AkAudioSessionModeVoiceChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVoiceChat constant.
@ AkAudioSessionBehaviorSuspendInBackground
By default, the Sound Engine continues to render audio in the background when using PlayAndRecord or ...
AkAudioSessionCategoryOptions
@ AkAudioSessionModeGameChat
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeGameChat constant.
@ AkAudioSessionCategoryOptionAllowBluetoothA2DP
Same as AVAudioSessionCategoryOptionAllowBluetoothA2DP. Only affects PlayAndRecord category.
AkAudioSessionSetActiveOptions
void * interruptionCallbackCookie
Application-defined user data for the audio interruption callback function.
@ AkAudioAPI_AVAudioEngine
Use AVFoundation framework (modern, has more capabilities, not available for iOS/tvOS 12 or below)
uint32_t AkUInt32
Unsigned 32-bit integer.
@ AkAudioSessionModeVideoRecording
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVideoRecording constant.
AkAudioSessionSetActiveOptions eSetActivateOptions
AkAudioCallbacks audioCallbacks
iOS audio callbacks
AkUInt32 uSampleRate
Sampling Rate. Set to 0 to get the native sample rate. Default value is 0.
AKSOUNDENGINE_API AkDeviceID GetDeviceIDFromPlayerIndex(int playerIndex)
@ AkAudioSessionCategoryOptionDuckOthers
Same as AVAudioSessionCategoryOptionDuckOthers. Implicitely sets the MixWithOthers option....
AK_ID_DECLARE BasePlatformID iOS
Definition: PlatformID.h:102
AkThreadProperties threadBankManager
Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
@ AkAudioSessionModeMoviePlayback
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant.

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