Using FMOD with X-Plane

Introduction

FMOD is a high quality commercial sound engine and sound authoring environment for games. X-Plane 11 uses FMOD as its new sound engine; you can use FMOD’s authoring tools to create highly realistic sounds for your aircraft.

This document explains how X-Plane uses FMOD and how to integrate your FMOD sound projects into your aircraft. It is not an introduction or guide to FMOD itself. This document assumes that you are already familiar with FMOD, its technology, and its workflow.

If you have not already used FMOD, please first use FMOD’s documentation and tutorials to learn about:

• Sound events
• Parameters
• Buses
• Snapshots

As of this writing, FMOD sound can only be integrated onto aircraft. We expect to support FMOD for scenery and plugins in the future.

If you are upgrading your existing FMOD Studio project from X-Plane 11 to X-Plane 12, be sure to read the FMOD 2.0 upgrade notes.

Video tutorial

A video tutorial is also available on getting started with FMOD sound with X-Plane 11.

Download the X-Plane Starter Project

FMOD requires each sound bank used with X-Plane to have its own globally unique identifier (GUID). It also requires that the main mix buses of the master bank of each aircraft have the same GUIDs.

FMOD Studio does not provide a user interface to edit GUIDs, so to make it easier to create a correctly authored third party aircraft with FMOD sound, we are providing all third-party developers with an FMOD starter project that is auto-configured with the standard mix buses but a new bank GUID.

Clicking the link below will generate a project just for you. Use this link once for each new project for a new aircraft that you want to create. You only need one FMOD project for a family of .acf files that share an aircraft folder, but you need a new project for each aircraft that has its own aircraft folder.

Download the FMOD Project Template (v1.08 - for XP11)
Download the FMOD Project Template (v2.02 - for XP12)

(Note that if you later want to add sounds for a separate aircraft, you’ll need to download a new starter project, which will contain a new GUID. If you accidentally ship a project that shares a GUID with another aircraft, and a user has both aircraft loaded, the conflict will cause the sim to error out and crash when the second aircraft is loaded.)

You will need FMOD Studio to author your project, which can be downloaded from the FMOD website:

• For X-Plane 11 use FMOD Studio 1.08.xx
• For X-Plane 12 use FMOD Studio 2.02.xx

Integrating Sound Into An Aircraft

An aircraft’s sounds are either provided by FMOD or by the legacy sound system from X-Plane 10 (based on OpenAL); you cannot mix and match them. When using FMOD, every sound in the aircraft must be provided by you (via FMOD), except for radio sounds that come from the outside world (E.g. the voice of ATC, marker beacon tones and morse code identifiers).

To use FMOD, your aircraft must have:

• A folder named “fmod” in your aircraft folder.
• A file named XXX.snd in that fmod folder, where XXX is the name of your Aircraft’s .acf file with the ACF extension removed. (Example: Cessna_172SP.snd)
• A text file named GUIDs.txt that maps FMOD object names to their GUIDs. (You can get this directly by exporting it from your FMOD project – you don’t need to write it by hand.)
• The master bank for your FMOD project, named “Master Bank.bank”. This comes from building your FMOD project.

You can also optionally use additional banks by putting them in the FMOD folder, but it is not necessary.

The .snd file is a text file that describes how the sounds in your banks will be attached to your aircraft. It is an X-Plane specific text file format that connects X-Plane to FMOD.

Using Multiple Banks

FMOD allows you to partition your events into multiple banks; the motivation for this is to allow X-Plane to load only the sounds it needs. For simple aircraft you will not need to do this. But, for example, if you ship your aircraft with multiple engine types (and multiple .acf files), you could put each type of engines’ sounds into a separate bank and load only the bank you need for that aircraft.

Banks other than the master bank are loaded by using a REQUIRES_BANK directive. Every bank that is not a master bank whose objects are referenced by your .snd file must be loaded by a REQUIRES_BANK.

The GUIDs.txt file that lists all GUIDs in your fmod folder should contain the GUIDs for every bank that you load. When you export GUIDs from FMOD Studio, the single GUIDs.txt file will contain every bank already.

Events: Associating Sounds With Your Aircraft

The way you make sound in your aircraft is to attach FMOD Events to your aircraft. The .snd file for your aircraft describes how the events are attached to your aircraft, where the sound source is located, and when it plays.

Events should not always be playing unless it is absolutely necessary! There is a CPU cost to every playing event even if it is not making any sound, so you should only start an event when it is needed. For example, once engines are completely off, stop the event!

Events are started and stopped by trigger conditions defined in your .snd file. There are two ways to do triggering:

• Dataref expressions. You can specify the conditions under which a dataref starts and stops in terms of a dataref changing its value. For example, you could start a dataref when the fuel flow is > 0 and stop it when the fuel flow is <= 0. This technique is good for creating sounds that are the result of things, e.g. the noise made by the engine turning.
• Commands. You can specify an event to play in response to a command being pressed. This technique is good for cockpit switches and other physical manipulations by the user; the commands will pick up switch movement from any source – mouse, joystick, custom hardware, etc.

When using datarefs, please be careful to use the result datarefs, not the cause datarefs. For example, if you are making an engine sound, something in sim/flightmodel2/engine will tell you what the engine is actually doing, while something in sim/cockpit2/ will tell you what the pilot is doing or seeing. Use flightmodel2 so the engine makes sound based on what it is really doing, not what the indicators are doing.

See the .snd file format for specific directives to control triggering.

Sound event locations are specified in coordinates relative to the aircraft’s CG. The .snd file also has short-cuts to attach sounds directly to engines and the cockpit.

A sound event may be enabled for AI aircraft, or limited to only the user aircraft. Only include exterior sounds like engines for AI aircraft – X-Plane cannot correctly mix the interior sounds of AI aircraft.

Snapshots Are Events Too!

While this might not be obvious from using FMOD studio, snapshots are actually specialized events in FMOD. Therefore, to use a snapshot you must “attach” it to the aircraft just like a regular sound event, and it must be playing to affect the mix.

If you have a snapshot that must be continuously run, there is a .snd directive for an always-playing event (for the life of your aircraft being loaded), but it is better to stop snapshots when their mix effect is completely disabled, just like you would another sound.

For example, if you have a snapshot that muffles sound when inside the aircraft, stop the snapshot when the user is fully outside the aircraft.

Parameters: Controlling Sounds

Events in FMOD are controlled via parameters; besides the default parameters always available in FMOD, X-Plane allows you to use datarefs as the input parameters to your sound – this is how you customize how your events sound in real-time in response to the sim.

To use a dataref to modulate a sound, simply add a custom parameter to your FMOD event and set its name to the dataref you’d like to use. Make sure to set the minimum and maximum to correlate the dataref’s range to FMOD. Use the following format for the parameter name:

• X-Plane 11: The dataref name. sim/flightmodel2/engines/N2_percent[0]
• X-Plane 12: Replace “/” with “.”. sim.flightmodel2.engines.N2_percent[0]

You can use wild-cards in the dataref name for indices; when you do this the index of the dataref is taken from the attachment of the FMOD event in the .snd file. Use PARAM_DREF_IDX in the .snd file, and for the array subscript in your dataref use the following convention:

• X-Plane 11: Use “*”. sim/flightmodel2/engines/N2_percent[*]
• X-Plane 12: Use “#”. sim.flightmodel2.engines.N2_percent[#]

The intention of this feature is to let you build a single event for an engine and then place four instances in the .snd file with the dataref index mapping the engine sounds to the correct engine number in X-Plane. Without this, you would have to duplicate your engine just to change the parameter names to match the correct engine.

Providing a Master Bank

Your aircraft must provide a master bank with all of the standard buses.

In order for your FMOD project to work with X-Plane, follow these rules:

1. ALWAYS start your project with a “starter project” from Laminar Research! We provide a download tool that makes a unique starter for you to customize that will be compatible with X-Plane.
2. NEVER delete the standard buses that come with the project! If you delete them and create your own, they will not work even if the names are the same!

The Standard Busses

X-Plane’s project template comes with a standard set of buses which you must preserve for your FMOD project to work with X-Plane. The standard bus layout is:

Here is the intended use of each bus:

• Master. The master bus is the parent to all buses – it should have no signal processing; it exists to allow X-Plane to control the volume of all sounds at once.
• Radios. This bus will be used in the future for audio that the pilot hears over the radios via a headset.
• Copilot. This bus will be used in the future for audio of the copilot talking to the pilot over a headset.
• Interior. This is the bus for sounds inside the cockpit. Signal process only if (for example) there is an echo inside the aircraft.
• Exterior Unprocessed. This bus is the destination for exterior aircraft sounds that automatically sound muffled when the listener is inside due to swapping between two sets of recordings. Do not put any signal processing on this bus.
• Exterior Processed. This bus is the common destination for all sound that is outside of the aircraft and needs to be muted by signal processing when the pilot/listener is inside the cockpit. Put your muting signal processing on this bus!
• Aircraft. This bus is specific for “outside” aircraft sounds that need signal processing, e.g. engine records that are not muffled. This bus is routed to the more general Exterior Processed bus, so do not signal process this bus —  the aircraft and environment are separated for UI control of levels.
• Environment. This is a sub-bus of the Exterior Processed bus that is used for environmental sounds, e.g. wind, birds, trucks, etc. Again, do not signal process here — the parent exterior processed bus does this.

For reference, this is the required GUIDs for each bus; use our starter project to ensure the GUIDs are correct. If your project will not load, you can check your GUIDs.txt file to see if a bus has the wrong GUID.

Required BUS GUIDs

Interior and Exterior Spaces

X-Plane provides standard tools and a standard setup to create differing sound based on whether the user is inside or outside of your aircraft. There are two basic audio techniques to create interiors and exteriors:

• Substitution. You can provide different sounds for the interior and exterior of your aircraft. For example, on our Cessna we have recordings of the engine from both inside and outside the aircraft, and we play different ones depending on the camera location. (This was the only technique available in X-Plane 10 and earlier.)
• Mixing. You can use the live sound processing capabilities of FMOD to change the signal processing on your audio in real-time based on the camera location. For example, you can use a low-pass filter to cut high frequencies from your sounds when inside the aircraft.

For the sounds you provide with your aircraft, you can pick between substitution and mixing. However, you must customize the mix bus to provide signal processing to muffle exterior sounds from inside the aircraft (if your aircraft has any interior sound proofing or sound shaping) so that AI aircraft and other environmental sounds change their processing. In other words: you provide the “interior” muffling since it is your aircraft, and the interior of an old GA aircraft and a modern airliner have very different sound proofing.

Defining Spaces on the ACF

Before you can customize your sound for interior and exterior views (with substitution or mixing), you must first know where the listener is – X-Plane provides sound spaces to let you do that.

A sound space is an arbitrary 3-d volume on your aircraft that the camera is within. You can define up to 64 sound spaces, but you do not have to use them, and you may only need one.

Sound spaces are defined as the union of one or more solid 3-d shapes; X-Plane provide axis aligned bounding boxes and spheres. You can overlap these shapes and use more than one of them to make arbitrary and unusual spaces.

Sound spaces can define transition widths; when tracking the camera into and out of your sound space, the distance inside the space (from its border) will form a smooth transition from outside to inside; this can help avoid sudden audio changes in your mix.

The dataref sim/operation/sound/inside_ratio provides a ratio indicating how far ‘inside’ each sound space you are. If sound space overlap, X-Plane will split the difference, e.g. you might have 0.5 for two sound spaces if you are fully inside both. If all sound spaces are 0, you are outside the aircraft.

The intention is for this dataref to be tied to the intensity of a snapshot to bring in a mix change. To do this you would:

1. Make a snapshot for your mix change.
2. Add a custom parameter matching a dataref, e.g. sim/operation/sound/inside_ratio[0]
3. On the tab for that dataref custom parameter, add an automation track for intensity (disclose the master track of the snapshot, right-click on “intensity” and pick “add automation)”.
4. Key-frame an increase in intensity with an increase in the dataref value.

Finally, please note that the inside_ratio datarefs take into account the camera location but not the status of doors or any openings.

• If the sound proofing of your aircraft becomes a lot worse when the door is open, apply a secondary mix change (besides the location snapshot) based on the door-opening datarefs or canopy datarefs.
• If the sound proofing loss due to the open door is localized (e.g. an open airliner door adversely affects sound proofing mostly near the door) consider breaking the interior into two spaces and applying the door loss to the snapshot for the door only.

Logic tracks can be cumulative – you can apply an intensity automation to your snapshot for both the inside ratio and the door open ratio.

Using Pre-Recorded Interior and Exterior Sounds

If you have specific pre-recorded sounds inside and outside the aircraft, you can wire them up in FMOD by:

1. Creating sub-events inside the main event, one for inside, one for outside.
2. Adding a custom dataref parameter for an inside ratio, door ratio, etc. for both the outer and inner events. (The inner event needs the parameter to key-frame, and the outer one needs it for X-Plane to drive.)
3. Add automation to the master volume of the inner event to fade the event in and out with the dataref.

Events built in this manner should be sent to the Exterior Unprocessed bus to avoid processing that mutes the event when inside – your recorded sound already does this!

Using the Mixer For Interior Sounds

To use a mix bus to process sounds (e.g. to make an exterior recording to sound like an interior recording), connect it to the Aircraft bus.

Mixing Interior Sounds

Many sounds in the cockpit are very audible to the pilot in the aircraft but completely inaudible outside the aircraft, e.g. the click of switches on the panel. Wire these up to the interior bus and do not mark the sound as ‘for AI aircraft’.

Mixing Techniques and Notes

This section contains a some notes and tips we’ve learned while working with FMOD on our own aircraft.

Understanding Tracks and Parameters

FMOD is a little bit different from a traditional digital audio workstation (like ProTools) in that each sound event has multiple timelines instead of just one. Each time you add a parameter, you get a new set of tracks specific to that parameter.

When a sound (e.g. a sub-event or audio file region) sits inside a set of tracks, it will begin to play as soon as the play-head enters it, no matter what speed the play-head is moving.

This matters because the play-heads of parameters other than “time” do not move in real-time; rather they move arbitrarily based on X-Plane.

For example, let’s say you set up sim/flightmodel2/engines/N1[0] as a custom dataref parameter – you now have a timeline based on the N1 speed of your left engine. If you put a sub-event or region in the timeline range from 20 to 30, then when N1 goes from 19 to 20%, the region will start playing, and then play forever as long as N1 stays in that range. If N1 levels out at 21%, the sound keeps playing.

This works because each sub-event or region has its own “playhead” that causes it to play in real-time. Typically there are two separate ways of working:

• If the track is a true “timeline” track, the play-head will exit the region about when its full duration has passed. Thus you can sequence consecutive regions.
• If the track is a parameter track, the play-head may sit in your event forever, and you will want your sound to loop.

Nested Mixing and Multiple Parameters

Given that each new parameter introduces a new independent set of tracks with a new independent set of play-heads, how do we mix and key-frame based on multiple parameters? Here are two techniques:

If you simply need to apply automation based on parameters, put all of your regions in a single set of tracks (for a single master source like the timeline or a given dataref) and only use the other track sets for automation by adding logic tracks. For example, you could make a flap actuator sound whose primary track is timeline (with a starting sound, a looping region, and an end, all sequenced on the main timeline) but then make a separate dataref-based parameter track to modulate the master volume (e.g. based on the door being open). The logic tracks will run based on the parameter, changing mix levels.

Another option is to use sub-events. Because each event has its own “playhead”, you can run a parent event’s play-head based on one dataref and a child-event’s play-head based on another.

For example, if you have a series of engine recordings varying by RPM, but you also have them at different viewer orientations, and another set for inside the aircraft (without orientation), you might:

1. Create an outer event for the engines, with RPM, inside ratio, and orientation all as parameters.
2. Build two sub-events within the inside-outside timeline (cross-faded), one each for the inside and outside event.
3. Inside these sub-events, build cross-faded regions on the RPM tracks.
4. Build multiple parallel in the RPM range for the outside recordings for all mic positions.
5. Add a logic track to the event orientation built-in parameter for these tracks to fade up and down each mic orientation as the camera orientation moves.

Live Mixing From Inside X-Plane

You can mix your audio from FMOD studio while X-Plane is running – this lets you test your mix with real input parameters from X-Plane while flying. To do this:

1. Launch X-Plane from the command line with --fmod_live_update in the prompt, e.g.
   X-Plane.exe --fmod_live_update
2. Open your FMOD project.
3. Once both are running, pick “Connect to Game” in the file menu and accept localhost as the IP address.

Once you do this, you can change your mix levels and processing parameters in FMOD studio and hear the results immediately inside X-Plane.

Snapshot mixing via the live mixer is not fully functional: you can edit your snapshot mix levels and test them by moving the camera in X-Plane, but you cannot arbitrarily “play” a snapshot by simply hitting “play” in FMOD (the way you would if you were simply working on your project); in live update mode all event playback comes from X-Plane.