FMOD Engine User Manual 2.03
FMOD is compiled using the following tools.
FMOD supports devices of the below ABIs back to API 10.
Substitute $ABI with your desired ABI from the 'Compatibility' list above.
Core API library
Studio API library (used in conjunction with the Core API library)
FMOD is primarily a native C/C++ library implementation but does provide a limited JavaScript interface to provide necessary data to the engine.
It is also highly recommended that you initialize the FMOD JavaScript interface, as this will allow loading assets from the App package. This should be done before System_Create or Studio::System::create, and should be closed after System::release or Studio::System::release.
To access the JavaScript interface you must create index.d.ts in src\main\cpp\types\libfmod with the following:
export const init: (ability: UIAbility) => void;
export const close: () => void;
Create an oh-package.json5 in src\main\cpp\types\libfmod with the following:
{
"name": "libfmod.so",
"types": "./index.d.ts",
"version": "",
"description": "FMOD Core Library."
}
Reference the .d.ts in oh-package.json5 for the target (not application), which goes in devDependencies:
"devDependencies": {
"@types/libfmod.so": "file:./src/main/cpp/types/libfmod"
},
To call FMOD JavaScript functions you need to edit your Ability.ts and add the following import:
import fmod from 'libfmod.so';
In your Ability onCreate function add:
fmod.init(this);
In your Ability onDestroy function add:
fmod.close();
It is expected that the API for FMOD is called from your existing native code in C++. It is important when initializing FMOD to not call the init function too early otherwise the audio device will fail. Make sure you call FMOD after the WindowStage ACTIVE event occurs, for example, you can edit your Ability.ts, and edit onWindowStageCreate to include the following:
windowStage.on('windowStageEvent', (data) => {
if (data == window.WindowStageEventType.ACTIVE) {
// Call you JS entry point for FMOD creation here
}
else if (data == window.WindowStageEventType.INACTIVE) {
// Call you JS entry point for FMOD destruction here
}
});
All threads will default to FMOD_THREAD_AFFINITY_CORE_ALL, this is recommended due to the wide variety of devices available but can be customized with Thread_SetAttributes.
The relationship between FMOD platform agnostic thread priority and the platform specific values is as follows:
The system will pause FMOD when your app goes into the background, however it will not resume it when returning to the foreground. To handle this, call System::mixerSuspend from your UIAbility onBackground callback and call System::mixerResume from your UIAbility onForeground callback.
For SDK 10 devices, the hardware latency is fixed at ~90ms, for FMOD to operate in this high latency environment you must increase the FMOD buffer size to handle the latency. We recommend calling System::setDSPBufferSize with 2048 as the buffer length and 4 as the number of buffers.
For SDK 11 and newer devices, the hardware latency is internally configured to match the FMOD buffer length. If you do not call System::setDSPBufferSize, the default of 1024 buffer length and 4 buffers will be used, which the hardware can use without stuttering. If you want to set the buffer length lower than the default 1024, we recommend using FAST mode.
FAST mode is available on all devices and can be selected by calling System::setDriver with 1 before System::init (the default of 0 represents normal mode). With FAST mode activated you should be able to set the FMOD buffer length down to 512, with 4 buffers and achieve glitch free playback. However, please note some development boards cannot handle FAST mode and will result in a crash, thankfully we have seen no such crash in any consumer devices.