+
2. User Guide
+
The FMOD UE4 Integration is a plugin that allows you to use the FMOD APIs and projects from the FMOD Studio authoring tool in your UE4 game.
+
Normally you will just need one copy of the integration. If you develop for multiple platforms at once, you can copy multiple integrations over the top of each other.
+
+
+
The integration consists of a single FMODStudio folder which can be placed in either the Engine/Plugins directory or your UE4 game's Plugin directory {ProjectName}/Plugins. The next steps show how to install it into your Engine directory, so it will be available for all projects using UE4.
+
+
Browse to your UE4 Engine folder and unzip FMODStudio into the plugins directory.
+
+
+
Use Finder to browse to your /Users/Shared/UnrealEngine/4.X/Engine directory and drop FMODStudio into the plugins directory.
+
+
If you have trouble getting the plugin working on a certain platform, then try putting FMODStudio in your game's Plugins directory instead of the engine.
+
Otherwise see the TroubleShooting section.
+
+
+
Start by replacing the old FMODStudio folder with the new version:
+
+
If you are updating to a newer minor version of FMOD no additional steps are required unless specified in the revision history.
+
Upgrading to a newer major version of FMOD is usually only recommend for projects at or near the beginning of development, because new major versions may introduce behavioral and breaking changes. If you are upgrading to a new major version, you will need to read over:
+
+
These will describe specific changes that might need to be made to your project.
+
+
There are settings in both UE4 and FMOD Studio that need to be configured to link the two together.
+
If you have any trouble setting up your project, use the automatic method. These settings can always be changed later.
+
+
You can run the "Help > FMOD Validate" option in the UE4 Help menu. It finds and fixes common issues, and can automatically set up your FMOD Studio project for you!
+
It will check the following:
+
+- You are running the right version of FMOD Studio
+- Your FMOD Studio bank export path is correct
+- Banks have been exported
+- Studio events have been added to the banks
+- Any plugins have been added to the plugin list
+- FMOD has been added to the packaging settings for deployment
+
+
+
From your FMOD Studio Project, select "Edit > Preferences..." ("FMOD Studio > Preferences..." on Mac) and select the build tab. Set your built banks output directory to a directory called "FMOD" under your game's content path.
+
+
Now select "File > Build". This will build bank files for events that have been assigned to banks. You should do this whenever project data has been modified.
+
+
Now, open UE4 and look at the content browser. The plug-in defaults to looking in Content/FMOD directory for banks, so if you have exported banks there, assets should appear in the content window automatically. These represent items in your Studio project which update automatically when banks are built.
+
+
For more information about banks, see the Banks page.
+
+
+
If you want to recompile the plugin, you can drop the plugin into a code project under your game's Plugins/FMODStudio directory, then re-generate the project. This might be useful if you want to use the plugin with a different version of the engine, such as a new pre-release of UE4. You can also do this if you want to get the plugin from github.
+
To recompile the plugin after downloading it from FMOD, do the following:
+
+- Delete the
FMODStudio/Intermediate directory.
+- Delete the
FMODStudio/Binaries/Platform/UE4*.* files. Leave the fmod libraries in the binaries directory!
+- Create a new code project using UE4.
+- Copy the plugin into
YourGame/Plugins/FMODStudio.
+- Regenerate the game's solution or xcode project.
+- Build the game for "Development Editor".
+- Build the game for whatever other configurations you need.
+
+
To compile the plugin after downloading the source from github, do the following
+
+- Add FMOD dynamic libraries into the
FMODStudio/Binaries/Platform/ directory. The libs can be obtained in the programmers API download or from the FMOD for UE4 download.
+- Create a new code project using UE4.
+- Copy the plugin into
YourGame/Plugins/FMODStudio.
+- Regenerate the game's solution or XCode project.
+- Build the game for development editor.
+- Build the game for whatever other configurations you need.
+
+
When rebuilding the plugin inside a code project, make sure you haven't also left it in the engine directory as well!
+
+
+
You are able to interface with the FMOD UE4 Integration and/or the FMOD C++ APIs.
+
+
To reference FMOD Studio, the programmer will need to add the following to their .Build.cs file:
+
+- Add "FMODStudio" to
PrivateDependencyModuleNames
+
+
To add some FMOD Events to a class, do the following:
+
+- Include "FMODEvent.h" at the top of your own class
+- Add a UFMODEvent * and mark with the
UPROPERTY macro like any other field
+
+
To play the event at a location, do the following:
+
+- Include "FMODBlueprintStatics.h" in the file you want to trigger the sound
+- Call UFMODBlueprintStatics::PlayEventAtLocation with the following arguments:
+- Set WorldContextObject to any UObject in the world, such as the owning actor object
+- Set Event to the UFMODEvent stored in the class or passed into your function
+- Set Transform to the place in the world you want to play the sound
+- Set bAutoPlay to true so that it starts the sound automatically
+
+
+
+
You can also call UFMODBlueprintStatics::PlayEventAttached to create a new audio component attached to an actor, which will update the location automatically as the actor moves around the world.
+
+
Programmers can interface with FMOD Studio directly by including "fmod_studio.hpp".
+
The Studio system can be obtained by GetStudioSystem. The function takes an enum because there may be a separate Studio system for auditioning in-editor and the proper system for play-in-editor. Normally, you will want to obtain the system with EFMODSystemContext.Runtime since that is the real system used in game.
+
if (IFMODStudioModule::IsAvailable())
+{
+ FMOD::Studio::System* StudioSystem = IFMODStudioModule::Get().GetStudioSystem(EFMODSystemContext::Runtime);
+ if (StudioSystem)
+ {
+ // Use it here
+ }
+}
+
+
+
+
You can use a mixture of FMOD Studio wrapper and FMOD Studio API functions. For example:
+
// Call wrapper helper function to create and start an event instance
+FFMODEventInstance InstanceWrapper = UFMODBlueprintStatics::PlayEventAtLocation(ThisActor, MyEvent, FTransform(MyLocation), true);
+FMOD::Studio::EventInstance* Instance = InstanceWrapper.Instance;
+// Call into FMOD API directly
+Instance->setVolume(0.5f);
+// The instance handle will be cleaned up automatically when the sound finishes
+
+
+
+
+
For further documentation, see:
+- Integration API Reference
+- FMOD API Reference.
+
+
+
The FMOD UE4 integration provides multiple ways in which Studio events can be played.
+
+
The simplest way to play a looping ambience, is to drag and drop an event from the content browser into a scene viewport.
+
+
For example, try dragging the Game/FMOD/Events/Ambience/Forest event into a level. This will create an FMODAmbientSound. Hit Play to begin playing in editor, and you should immediately hear the Forest ambience.
+
Make sure you drag an event into the main viewport. Dragging a bank into main viewport won't do anything.
+
+
Another easy way to trigger a sound is via blueprint. You can use the play event at location function to quickly trigger any given event.
+
+
In the example shown below, the Single_Explosion event is triggered at the location of the camera, every time the spacebar is pressed.
+
+
+
Keep in mind that more advanced control is also available from blueprints. There are graph functions for playing and stopping events, setting parameters, and loading or unloading banks. You can also add FMODAudioComponents to blueprints, allowing you attach audio directly to an object.
+
+
+
FMOD can support up to 8 listeners in game. The FMODListeners will follow the UE4 listeners which by default is attached to the camera, but we can move them by moving the UE4 listeners.
+
This is particularly useful for Third-Person and Top-Down style games.
+
+
Using SetAudioListenerOverride allows you either attach the listener to a component or set the transform and rotation manually.
+
+
+
+
Content created in FMOD Studio is exported into bank files. These bank files can then be loaded within Unreal using the FMOD UE4 integration. Banks can contain multiple events, which will implicitly pull in any audio assets they depend on.
+
+
Loading a bank will load all metadata, which contains information about all the events, parameters, and other data needed for all events assigned to that bank.
+
+
It is highly recommended that banks are exported to the Content directory of your project (see Deployment for more information). This can set via the built banks output directory setting in the FMOD Studio, which can be found in "Edit > Preferences..." on Windows (or "FMOD Studio > Preferences..." on Mac), under the Build tab.
+
+
When using the UE4 editor, as long as you match the FMOD Studio built banks output directory to the bank output directory specified in the Unreal project settings ("Edit > Project Settings > FMOD Studio"), the integration will find and load all bank content automatically.
+
+
+
Before a new FMOD Studio event can be used in Unreal, it must first be assigned and built to a bank which can be loaded by Unreal. This can be done within FMOD Studio via the context menu of an event, or by dragging and dropping an event onto a bank.
+
+
Events are typically assigned to the same bank when they should be loaded and unloaded at the same time. For example, you might put all the events for the Goblin enemy within the Goblin bank.
+
Once you have assigned your events to a bank, you should rebuild your banks. This is done via the "File > Build..." menu item.
+
+
+
The banks built in FMOD Studio are loaded in editor by the plugin, so that you can browse Events, Buses, Snapshots, etc. from the Studio Project. You are able to customize the way the banks are loaded in game, to suit your requirement, otherwise by default all the banks will be loaded at initialization.
+
+
Within the Unreal editor, banks are loaded automatically as soon they are built. When correctly configured, any data within banks (e.g. events, mixer strips) should appear within the content browser under Game/FMOD by default.
+
+
+
The FMOD UE4 integration will load all banks by default. If you would like to manually control bank loading, this behavior can be disabled via the load all banks checkbox withing the FMOD Studio settings dialog ("Edit > Project Settings > FMOD Studio").
+
If using split banks, make sure to load the assets bank first and using load sample data on the metadata bank.
+
Banks can then manually be loaded and unloaded using the Load Bank and Unload Bank blueprint functions.
+
+
+
The Master Bank does not need to be loaded manually. It is automatically loaded at startup.
+
+
+
+
FMOD is integrated into Unreal Engine 4's Sequencer.
+
+
Events can be added in one of two ways:
+
+-
+
Ambient sounds already placed in the level may be possessed by the level sequence. Add ambient sound actors to the sequence by clicking the 
button in the Sequencer editor and choosing the ambient sound actor to add. Alternatively the actor can be dragged from the World Outliner into the Sequencer editor.
+
+Possessed events will retain any state set by the level sequence when playback is complete. The level sequence's Restore State setting can be enabled to restore the state of possessed events (and any other actors possessed by the level sequence).
+
+-
+
New events may be spawned from Sequencer. Sequencer can spawn FMOD events during playback. To create a spawned event drag an FMOD event from the Content Browser into the Sequencer editor.
+
+Spawned events will not automatically play when spawned.
+
+
+
+
Once added to a sequence additional sub-tracks are required to do anything interesting. Sub-tracks can be added by clicking the 
button in the object's track. FMOD adds two new sub-track types for events in addition to the standard Sequencer sub-tracks.
+
+- Event control tracks allow events to be played and stopped.
+- Parameter tracks allow event parameters to be animated using Sequencer's keyframe animation tools.
+
+
+
+
Keyframes on the event control sub-track can be used to Play or Stop the event.
+
+
+
An FMOD Event Parameter Track allows additional sub-tracks to be added for each parameter in the targeted FMOD event. Additional sub-tracks can be added by clicking the 
button in the FMOD Event Parameter Track.
+
+
Keyframes may be added to the parameter sub-tracks to control the value of the event parameter during playback of the level sequence. The Unreal Engine 4 curve editor may be used to create rich curves for FMOD event parameters.
+
+
The FMOD UE4 integration is unable to validate the range of parameter values set by Sequencer. The FMOD Engine will clamp any parameter value outside the range specified in FMOD Studio.
+
+
+
The FMOD UE4 integration supports the use of ray casts, to drive a specified parameter, for per instance occlusion of sounds.
+
+
To enable occlusion ray casts for FMOD in your UE4 project, set the name of the parameter that will be used for occlusion in Studio.
+
+
If an Event contains this parameter, the integration will set the parameter value any time the occlusion value changes.
+You can disable occlusion, per instance, and adjust the Trace Channel in the Component Details window.
+
+
+
+
The FMOD UE4 integration supports the use of the standard UE4 audio volumes to trigger Studio's advanced snapshot system.
+
+
The workflow to use reverb zones is to set up snapshots in FMOD Studio. Snapshots can modify global reverb effects, change any bus volume, and modify any DSP value. To help trigger snapshots for reverb effects, the integration exports all snapshots as reverb effects in the FMOD/Reverbs folder.
+
+
These reverb effects can be dragged into audio volume Reverb Settings panel to be triggered when the audio listener enters the audio zone. It uses the same logic as the inbuilt UE4 audio system to determine which audio volume should be enabled, based on the priority of the volume.
+
+
By default, snapshots apply instantly. To have a snapshot fade in, one of two things can be done. The first is by adding a AHDSR modulation to the intensity dial. The second way is to expose the intensity as a parameter, which allows it to be driven from the integration.
+
+
If the snapshot has its intensity exposed as a parameter, then the integration will ramp in the intensity over time based on the audio volume's Volume and Fade Time settings. If the snapshot does not expose its intensity as a parameter, then these values will not do anything.
+
+
Another feature of the UE4 audio system is the ability to have an ambient effect applied to selected instances, based on both the listener position and the emitter position. Unlike the global reverb effects, this is something which is applied per instance.
+
+
Only some sounds should be affected by the ambient settings. To enable the ambient effect your Events will need two parameters, one for volume and one for LPF.
+You will need to add these parameter names to the integration settings.
+
+
If an Event contains these parameters, the integration will set the parameter value any time the ambient values change.
+
+
Only FMOD audio components are affected by ambient zones. The simpler PlayEventAtLocation blueprint function to spawn one-shots does not apply ambient effects.
+
+
+
+
You can hook up event callbacks using blueprints. FMOD Audio component callbacks are only triggered if the enable callback option is ticked. This is because each component that triggers callbacks can incur a small CPU overhead, so it has to be turned on explicitly for the components you want to use.
+
+
Once enabled, then tempo beat callbacks and timeline callbacks can be added in blueprints. One way is via the Assign On Timeline Beat and Assign On Timeline Marker blueprint actions. For FMOD audio components used in blueprint actors, you can add events from the details window instead.
+
+
You can trigger various actions to occur on the beat or when a timeline hits a named marker. The event contains the same fields as FMOD_STUDIO_TIMELINE_BEAT_PROPERTIES and FMOD_STUDIO_TIMELINE_MARKER_PROPERTIES.
+
+
+
+
Localized audio tables are a special kind of audio table with features that facilitate localization. We recommend using localized audio tables if your game supports multiple spoken languages, or if you intend to add support for additional languages in a future patch.
+
+
Audio Tables are lists of audio files stored outside your FMOD Studio project's asset folder. You can use audio tables to control localized sounds. See the Dialogue and Localization section of the FMOD Studio Docs on how to set up an audio table in your project.
+
+
+
Audio tables are assigned to an associated bank, this means that in order to change the currently loaded audio table you will need to change the bank. Only one localized bank should be loaded at a time, otherwise just the first one to be loaded will be used.
+
You will need to define the different locale names and codes in the Localization Settings.
+
+
Only the locale that is selected as default will have it's bank loaded at startup, if Load All Banks has been enabled in the settings.
+
To change the locale, you will need to:
+
+- unload the bank
+- change the locale
+- then reload the bank
+
+
+
+
+
FMOD Studio events can include programmer sound modules that are controlled at runtime. There are a few different ways of hooking them up.
+
+
With this approach, you don't need to do any programming at all!
+
+
Create an event with a programmer sound module on it. If the module has a name, then if nothing else is assigned then that sound will be used. For example, if the sound designer sets the module name as "Welcome", then the audio table entry "Welcome" will be used by default.
+
+
To select at runtime what audio entry to use, set the programmer sound name field in the FMODAudioComponent.
+
+
Or you can assign the name via blueprint.
+
+
The name has to be one of the audio asset entries of a loaded audio table, or it won't find the sound to play.
+
Be careful to set the name before you play the audio component. If the name is assigned after the event has started, it may not play the right sound.
+
+
With this approach, you can easily play any media file for your event.
+
You can set up a programmer sound to point directly to a file. To do this, set the FMOD audio component's programmer sound name to the path to the .wav or .ogg file that you want to load. If this path is relative, it will be looked up relative to the content directory.
+
+
If you do this, you'll need to make sure that directory with the media files is added to directories to package in the packaging settings, otherwise it will work in the editor, but not when packaged into the final game.
+
+
With this approach, you have the most flexibility for programmers.
+
If you are writing code, you can programmatically set the FMOD Sound to use by calling the FMOD audio component function SetProgrammerSound. Here is an example of setting the sound from code:
+
void AExampleGameMode::InitAudio(UFMODAudioComponent* AudioComponent)
+{
+ if (AudioComponent)
+ {
+ FMOD::Studio::System* System = IFMODStudioModule::Get().GetStudioSystem(EFMODSystemContext::Runtime);
+ FMOD::System* CoreSystem = nullptr;
+ System->getCoreSystem(&CoreSystem);
+
+ // Create sound in memory
+ static const int EXAMPLE_SOUND_LEN = 4096;
+ float ExampleData[EXAMPLE_SOUND_LEN];
+ for (int i=0; i<EXAMPLE_SOUND_LEN; ++i)
+ {
+ ExampleData[i] = FMath::Sin((float)i);
+ }
+
+ FMOD_CREATESOUNDEXINFO SoundInfo = {0};
+ SoundInfo.cbsize = sizeof(SoundInfo);
+ SoundInfo.format = FMOD_SOUND_FORMAT_PCMFLOAT;
+ SoundInfo.defaultfrequency = 12000;
+ SoundInfo.numchannels = 1;
+ SoundInfo.length = sizeof(float) * EXAMPLE_SOUND_LEN;
+
+ FMOD::Sound* Sound = nullptr;
+ if (CoreSystem->createSound(reinterpret_cast<const char*>(ExampleData), FMOD_OPENMEMORY | FMOD_OPENRAW | FMOD_LOOP_OFF, &SoundInfo, &Sound) == FMOD_OK)
+ {
+ AudioComponent->SetProgrammerSound(Sound);
+ // Note: Need to remember to release the sound *after* the audio component has finished using it.
+ }
+ }
+}
+
+
+
+
+
Also, when setting the name to an audio table entry, you will need to make sure the audio table bank is already loaded before the event starts.
+
The FMOD audio component only supports a single programmer sound per event. If you want to have an event that has multiple programmer sounds, each one playing a different sound, then you'll need to create the event directly via the FMOD API and provide your own callback. You can look at how the FMOD audio component programmer sound callback works and use that as a base for your own class.
+
+
+
These steps describe how to prepare your project for deployment. This is relevant to both the Launch option as well as the "File > Package Project" menu item.
+If any platforms require specific steps, they can be found in Platform Specifics.
+
+
Banks need to be packaged and included in the game data. This can be done by selecting the "Edit > Project Settings..." menu item. Navigating to the Packaging section from the left hand pane, under the game heading, presents you with options for specifying directories that include extra assets. There are two ways of doing this:
+
+- Additional Non-Asset Directories to Package: Will copy banks inside the final package file.
+- Additional Non-Asset Directories to Copy: Will copy banks as loose files.
+
+
We recommend using Directories to Package so that bank files are bundled into the package file automatically.
+
+
Each platform will look for its own type of banks in its own directory. Make sure you have added the platform to FMOD Studio project. The platforms are:
+
+- Desktop (Windows, Mac, Linux)
+- PS4
+- XBox One
+- Switch
+- Mobile (Android, iOS, tvOS)
+
+
If you only have the Desktop banks and want to run on another platform, you can set force platform name to Desktop in the FMOD advanced settings.
+
+
The above directory name is relative to your Content directory. It is highly recommended that banks be placed within the content directory, as paths outside this directory will not deploy correctly to all platforms. For example:
+
+- Mac doesn't allow support directories outside the content directory at all.
+- Windows and Android have issues looking up directories outside the Content directory when used with packages.
+
+
This doesn't mean you need to put your whole Studio project inside the content directory. You can customize Studio by editing the Preferences and choosing a directory to export banks to, as described in the Working with Banks page.
+
The integration will load the platform bank files automatically. On PC it will load from FMOD/Desktop but on Android and IOS it will look for banks under FMOD/Mobile.
+
If you use FMOD as the directory to deploy and have multiple platform banks exported, then they will all be packaged up. To slim down your final package size, you may need to tweak the additional directories setting on a per platform basis. That way you only package FMOD/Mobile for Android, FMOD/Desktop for PC, FMOD/PS4 for PS4, etc.
+
+
You will need to make sure the plugins are deployed as well. Unreal deployment doesn't access to the settings information so you will need to create an extra file that lists the plugins you want to deploy.
+
Create a file "plugins.txt" in the FMODStudio/Binaries/Platform/ directory. The text file should contain the plugin names (just the name without file extension).
+
For example, to deploy fmod_gain.dll on Win64 builds, create a file FMODStudio/Binaries/Win64/plugins.txt with the following contents:
+
+
+
+
+
One issue to be aware of is where blueprints are serialized from disk too early, before any plugins are loaded. This can occur from the following code, which is included by default in example C++ projects constructor:
+
static ConstructorHelpers::FClassFinder<APawn> PlayerPawnClassFinder(TEXT("/Game/FirstPersonCPP/Blueprints/FirstPersonCharacter"));
+
+
+
+
The finder will serialize the first person character blueprint, but any FMOD references will fail to load since the FMOD plugin has not been created yet. To make sure that the FMOD plugin is loaded first, add the line of code above the class finder.
+
IFMODStudioModule::Get();
+
+
+
+
+
By default FMOD Studio works side-by-side with the inbuilt Unreal audio device on the following platforms:
+
+- Windows Desktop
+- Universal Windows Platform
+- Linux
+- MacOS
+- Android
+- PS4
+- Switch
+- Stadia
+
+
Any of the platforms listed below will not work with the inbuilt Unreal audio:
+
+- iOS / tvOS - Both UE4 and FMOD require exclusive control of the AudioSession to correctly handle interruptions.
+- Xbox One - Both UE4 and FMOD will attempt to consume all of the available XMA resources, this will cause the second system to fail initialization.
+
+
To disable the Unreal audio while leaving the FMOD Studio audio, the standard Unreal ini file setting can be used.
+
For each required platform, add a new file /Config/{Platform}/{Platform}Engine.ini with this section:
+
[Audio]
+AudioDeviceModuleName=
+AudioMixerModuleName=
+
+
+
+
The audio device can be disabled for every platform that you want to ship with.
+
+
The default permissions won't allow FMOD to set up a socket properly for live update. Uncheck the enable live update option in FMOD settings to avoid errors.
+
If you get a deployment error "resource.resw is in use by other process", go to the YourGame/Config/DefaultGame.ini and remove the following:
+
-CulturesToStage=en
++CulturesToStage=en
+
