Version
menu
Target Platform(s):
Wwise SDK 2025.1.0
AkAndroidSoundEngine.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) 2025 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 // AkAndroidSoundEngine.h
28 
29 /// \file
30 /// Main Sound Engine interface, specific Android.
31 
32 #pragma once
33 
34 #include <AK/SoundEngine/Common/AkTypes.h>
35 #include <AK/Tools/Common/AkPlatformFuncs.h>
36 #include <SLES/OpenSLES.h>
37 #include "SLES/OpenSLES_Android.h"
38 #include <jni.h>
39 
40 ///< API used for audio output
41 ///< Use with AkPlatformInitSettings to select the API used for audio output.
42 ///< Use AkAPI_Default, it will select the more appropriate API depending on the computer's capabilities. Other values should be used for testing purposes.
43 ///< \sa AK::SoundEngine::Init
44 typedef enum AkAudioAPIAndroid
45 {
46  AkAudioAPI_AAudio = 1 << 0, ///< Use AAudio (lower latency, available only for Android 8.1 or above)
47  AkAudioAPI_OpenSL_ES = 1 << 1, ///< Use OpenSL ES (older API, compatible with all Android devices)
48  AkAudioAPI_DolbyAtmos = 1 << 8, ///< Add this bit to opt into the Dolby Atmos API for 3D audio where available.
49  AkAudioAPI_AndroidSpatializer = 1 << 9, ///< Add this bit to opt into the Android Spatializer API for 3D audio where available. Note that this may have a noticeable negative impact on audio output latency.
50 
51  AkAudioAPI_Default = AkAudioAPI_AAudio | AkAudioAPI_OpenSL_ES | AkAudioAPI_DolbyAtmos, ///< Default value, will select the more appropriate API (Dolby Atmos for supported devices, AAudio for most devices, OpenSL for older devices)
52 } AkAudioAPI;
53 
54 enum AkAudioPath
55 {
56  // Use the legacy path for audio output. This path has the highest latency but best compatibility with the widest range of devices.
57  AkAudioPath_Legacy,
58 
59  // Attempt to use a low-latency path to the system audio mixer. This gives improved latency and good compatibility.
60  // Devices that don't support a low-latency path automatically fall back to the Legacy path.
61  // This is the default path.
62  AkAudioPath_LowLatency,
63 
64  // Attempt to open an exclusive audio stream to the audio driver, bypassing the system audio mixer for best latency.
65  // When available, this mode gives the best latency. However, it has several drawbacks to be aware of:
66  // - App audio will not be mixed with other apps. Other apps will be prevented from using exclusive mode while this output stream is active.
67  // - Screen recordings may not contain any audio.
68  // - When the app is put in the background, there is a possibility that another app 'steals' this path. When the Wwise app comes back to the foreground, this mode can become unavailable.
69  // - Audio will bypass system-level DSP effects like volume normalization and spatialization. 3D Audio will not work, and output volume may be abnormally loud or quiet.
70  // - Other functionality such as audio recording may be disabled when using this path.
71  //
72  // Not all devices support exclusive mode. Devices that don't support exclusive mode can fallback to either LowLatency or Legacy depending on device capabilities.
73  AkAudioPath_Exclusive,
74 
75  // The default audio path.
76  AkAudioPath_Default = AkAudioPath_LowLatency,
77 };
78 
79 /// Platform specific initialization settings
80 /// \sa AK::SoundEngine::Init
81 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
82 struct AkPlatformInitSettings
83 {
84  // Threading model.
85  AkThreadProperties threadLEngine; ///< Lower engine threading properties
86  AkThreadProperties threadOutputMgr; ///< Ouput thread threading properties
87  AkThreadProperties threadBankManager; ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
88  AkThreadProperties threadMonitor; ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
89 
90  AkAudioAPI eAudioAPI; ///< Main audio API to use. Leave to AkAPI_Default for the default sink (default value). \ref AkAudioAPI
91  AkAudioPath eAudioPath; ///< Which audio path to use. See enum for details. Default: AkAudioPath_LowLatency
92 
93  AkUInt32 uSampleRate; ///< Sampling Rate. Set to 0 to get the native sample rate. Default value is 0.
94  AkUInt16 uNumRefillsInVoice; ///< Number of refill buffers in voice buffer. Defaults to 4.
95 
96  SLObjectItf pSLEngine; ///< OpenSL engine reference for sharing between various audio components.
97  JavaVM* pJavaVM; ///< Active JavaVM for the app, used for internal system calls. Usually provided through the android_app structure given at startup or the NativeActivity. This parameter needs to be set to allow the sound engine initialization.
98  jobject jActivity; ///< android.app.Activity instance for this application. Usually provided through the android_app structure, or through other means if your application has an overridden activity.
99 
100  bool bVerboseSink; ///< Enable this to inspect sink behavior. Useful for debugging non-standard Android devices.
101 };
102 
103 struct AkInitSettings;
104 
105 namespace AK
106 {
107  namespace SoundEngine
108  {
109  /// Get instance of OpenSL created by the sound engine at initialization.
110  /// \return NULL if sound engine is not initialized
111  AK_EXTERNAPIFUNC( SLObjectItf, GetWwiseOpenSLInterface )();
112 
113  /// Gets specific settings for the fast audio path on Android. Call this function after AK::SoundEngine::GetDefaultSettings and AK::SoundEngine::GetPlatformDefaultSettings to modify settings for the fast path.
114  /// in_pfSettings.pJavaVM and in_pfSettings.jNativeActivity must be filled properly prior to calling GetFastPathSettings.
115  /// The fast path constraints are:
116  /// -The sample rate must match the hardware native sample rate
117  /// -The number of samples per frame must be a multiple of the hardware buffer size.
118  /// Not fulfilling these constraints makes the audio hardware less efficient.
119  /// In general, using the fast path means a higher CPU usage. Complex audio designs may not be feasible while using the fast path.
120  AKRESULT GetFastPathSettings(AkInitSettings &in_settings, AkPlatformInitSettings &in_pfSettings);
121  };
122 };
AkAudioPath_Legacy
@ AkAudioPath_Legacy
Definition: AkAndroidSoundEngine.h:57
AkUInt16
uint16_t AkUInt16
Unsigned 16-bit integer.
Definition: AkNumeralTypes.h:33
AK
Definition of data structures for AkAudioObject.
Definition: AkWwiseSDKVersion.cs:31
AkAudioAPI_AAudio
@ AkAudioAPI_AAudio
Use AAudio (lower latency, available only for Android 8.1 or above)
Definition: AkAndroidSoundEngine.h:46
AkAudioPath_Exclusive
@ AkAudioPath_Exclusive
Definition: AkAndroidSoundEngine.h:73
AkAudioPath_Default
@ AkAudioPath_Default
Definition: AkAndroidSoundEngine.h:76
AK_EXTERNAPIFUNC
#define AK_EXTERNAPIFUNC(_type, _name)
Definition: AkSoundEngineExport.h:81
AK::SoundEngine::GetWwiseOpenSLInterface
AKSOUNDENGINE_API SLObjectItf GetWwiseOpenSLInterface()
AkAudioAPI_AndroidSpatializer
@ AkAudioAPI_AndroidSpatializer
Add this bit to opt into the Android Spatializer API for 3D audio where available....
Definition: AkAndroidSoundEngine.h:49
AkAudioPath_LowLatency
@ AkAudioPath_LowLatency
Definition: AkAndroidSoundEngine.h:62
AkPlatformInitSettings::threadMonitor
AkThreadProperties threadMonitor
Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL)....
Definition: AkAndroidSoundEngine.h:88
AkPlatformInitSettings::threadLEngine
AkThreadProperties threadLEngine
Lower engine threading properties.
Definition: AkAndroidSoundEngine.h:85
AkAudioAPI_Default
@ AkAudioAPI_Default
Default value, will select the more appropriate API (Dolby Atmos for supported devices,...
Definition: AkAndroidSoundEngine.h:51
AkPlatformInitSettings::bVerboseSink
bool bVerboseSink
Enable this to inspect sink behavior. Useful for debugging non-standard Android devices.
Definition: AkAndroidSoundEngine.h:100
AkPlatformInitSettings::uNumRefillsInVoice
AkUInt16 uNumRefillsInVoice
Number of refill buffers in voice buffer. Defaults to 4.
Definition: AkAndroidSoundEngine.h:94
AkAudioAPI_DolbyAtmos
@ AkAudioAPI_DolbyAtmos
Add this bit to opt into the Dolby Atmos API for 3D audio where available.
Definition: AkAndroidSoundEngine.h:48
AkPlatformInitSettings::threadOutputMgr
AkThreadProperties threadOutputMgr
Ouput thread threading properties.
Definition: AkAndroidSoundEngine.h:86
AkPlatformInitSettings::eAudioPath
AkAudioPath eAudioPath
Which audio path to use. See enum for details. Default: AkAudioPath_LowLatency.
Definition: AkAndroidSoundEngine.h:91
AkPlatformInitSettings::jActivity
jobject jActivity
android.app.Activity instance for this application. Usually provided through the android_app structur...
Definition: AkAndroidSoundEngine.h:98
AkPlatformInitSettings::pSLEngine
SLObjectItf pSLEngine
OpenSL engine reference for sharing between various audio components.
Definition: AkAndroidSoundEngine.h:96
AKRESULT
AKRESULT
Definition: AkEnums.h:32
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:35
AkPlatformInitSettings::eAudioAPI
AkAudioAPI eAudioAPI
Main audio API to use. Leave to AkAPI_Default for the default sink (default value)....
Definition: AkAndroidSoundEngine.h:90
AkPlatformInitSettings::uSampleRate
AkUInt32 uSampleRate
Sampling Rate. Set to 0 to get the native sample rate. Default value is 0.
Definition: AkAndroidSoundEngine.h:93
AK::SoundEngine::GetFastPathSettings
AKRESULT GetFastPathSettings(AkInitSettings &in_settings, AkPlatformInitSettings &in_pfSettings)
AkPlatformInitSettings::threadBankManager
AkThreadProperties threadBankManager
Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
Definition: AkAndroidSoundEngine.h:87
AkPlatformInitSettings::pJavaVM
JavaVM * pJavaVM
Active JavaVM for the app, used for internal system calls. Usually provided through the android_app s...
Definition: AkAndroidSoundEngine.h:97
AkAudioAPI_OpenSL_ES
@ AkAudioAPI_OpenSL_ES
Use OpenSL ES (older API, compatible with all Android devices)
Definition: AkAndroidSoundEngine.h:47

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