UE4 Integration 2.00

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.

2.1 Installing the integration

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.

2.1.1 Windows

Browse to your UE4 Engine folder and unzip FMODStudio into the plugins directory.

UE4 Engine Tree

2.1.2 Mac

Use Finder to browse to your /Users/Shared/UnrealEngine/4.X/Engine directory and drop FMODStudio into the plugins directory.

UE4 Engine Tree OSX

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.

2.2 Updating/Upgrading the Integration

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.

2.3 Setting up 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.

2.3.1 Automatically

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:

2.3.2 Manually

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.

Studio export 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.

2.3.3 Confirm the Banks are Built and Loaded

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.

Content browser

For more information about banks, see the Banks page.

2.4 Compiling the plugin (Optional)

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:

To compile the plugin after downloading the source from github, do the following

When rebuilding the plugin inside a code project, make sure you haven't also left it in the engine directory as well!

2.5 Programming Support

You are able to interface with the FMOD UE4 Integration and/or the FMOD C++ APIs.

2.5.1 Programming with the FMOD UE4 Integration

To reference FMOD Studio, the programmer will need to add the following to their .Build.cs file:

To add some FMOD Events to a class, do the following:

To play the event at a location, do the following:

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.

2.5.2 Programming with the FMOD Studio C++ API

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

2.5.3 Further Programming Documentation

For further documentation, see:
- Integration API Reference
- FMOD API Reference.

2.6 Making sounds

The FMOD UE4 integration provides multiple ways in which Studio events can be played.

2.6.1 Ambient Sounds

The simplest way to play a looping ambience, is to drag and drop an event from the content browser into a scene viewport.

Drag sample

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.

2.6.2 Playing Sounds From Blueprint

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.

Blueprint Sample

In the example shown below, the Single_Explosion event is triggered at the location of the camera, every time the spacebar is pressed.

Blueprint simple playback

2.6.3 Other avenues

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.

2.7 Listener

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.

2.7.1 Example

Using SetAudioListenerOverride allows you either attach the listener to a component or set the transform and rotation manually.

Listener Override

2.8 Working with Banks

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.

Studio bank layout

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.

2.8.1 Studio Bank Output Directory

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.

Studio export path

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.

Project Settings

2.8.2 Assigning Events to Banks

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.

Assign events to banks

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.

Build menu

2.8.3 Loading Banks within Unreal

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.

In Editor

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.

Content view

In Game

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.

Banks blueprint

The Master Bank does not need to be loaded manually. It is automatically loaded at startup.

2.9 Sequencer Integration

FMOD is integrated into Unreal Engine 4's Sequencer.

2.9.1 Adding FMOD Events to a Level Sequence

Events can be added in one of two ways:

  1. Ambient sounds already placed in the level may be possessed by the level sequence. Add ambient sound actors to the sequence by clicking the Add actor button 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.
    Possess actor
    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).

  2. 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.
    Audio Table
    Spawned events will not automatically play when spawned.

2.9.2 Adding Event Sub-Tracks

Once added to a sequence additional sub-tracks are required to do anything interesting. Sub-tracks can be added by clicking the Add track button button in the object's track. FMOD adds two new sub-track types for events in addition to the standard Sequencer sub-tracks.

  1. Event control tracks allow events to be played and stopped.
  2. Parameter tracks allow event parameters to be animated using Sequencer's keyframe animation tools.

Event tracks

2.9.3 Event Control Sub-Track

Keyframes on the event control sub-track can be used to Play or Stop the event.

Control track

2.9.4 Parameter Track

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 Add parameter button button in the FMOD Event Parameter Track.

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.

Parameter keyframe track

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.

2.10 Occlusion

The FMOD UE4 integration supports the use of ray casts, to drive a specified parameter, for per instance occlusion of sounds.

2.10.1 Occlusion Settings

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.

Occlusion Settings

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.

Occlusion Settings

2.11 Reverb Zones

The FMOD UE4 integration supports the use of the standard UE4 audio volumes to trigger Studio's advanced snapshot system.

2.11.1 Snapshot Reverb Effects

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.

Reverb assets

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.

Reverb settings

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.

Reverb snapshot intensity

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.

2.11.2 Ambient Zone Settings

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.

Reverb ambient

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.

Reverb user property

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.

2.12 Callbacks

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.

Callback enable

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.

Callback blueprints

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.

Callback example

2.13 Localization

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.

2.13.1 Setting up Audio Tables

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 Table

2.13.2 Loading Localized Banks

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.

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:

Load locale bank

2.14 Programmer Sounds

FMOD Studio events can include programmer sound modules that are controlled at runtime. There are a few different ways of hooking them up.

2.14.1 Programmer Sounds via Audio Tables

With this approach, you don't need to do any programming at all!

Choosing the audio entry to play

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.

Studio programmer sound

To select at runtime what audio entry to use, set the programmer sound name field in the FMODAudioComponent.

Programmer asset name

Or you can assign the name via blueprint.

Programmer 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.

2.14.2 Programmer Sounds by Path

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.

Programmer file path

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.

2.14.3 Programmer Sounds via API

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.
        }
    }
}

2.14.4 Troubleshooting

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.

2.15 Deployment

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.

2.15.1 Packaging banks

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:

We recommend using Directories to Package so that bank files are bundled into the package file automatically.

Project deployment

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:

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.

2.15.2 Bank Files Inside Content Directory

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:

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.

2.15.3 Deploying FMOD audio plugins

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:

fmod_gain

2.15.4 Loading blueprints before plugin load

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();

2.15.5 Disabling Unreal Audio Device

By default FMOD Studio works side-by-side with the inbuilt Unreal audio device on the following platforms:

Any of the platforms listed below will not work with the inbuilt Unreal audio:

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.

2.15.6 Enabling Live Update

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

UE4 Integration 2.00.10 (2020-07-14). © 2020 Firelight Technologies Pty Ltd.