FMOD Studio User Manual 2.02
This chapter lists a number of common stumbling blocks that can be encountered while working with FMOD Studio, along with techniques for overcoming them.
If you encounter a problem, and none of the techniques listed in this chapter help, post a question on the FMOD Forums for advice and support.
Make sure that all your events are assigned to banks. Events must be assigned to banks in order for them to be included in those banks when they are built.
Try rebuilding your banks and using the rebuilt banks in your game. Rebuilding your banks ensures that they include the most up-to-date version of your project's content.
After rebuilding your banks, check for error messages and warnings in the logging tab of the console window. Messages in the logging tab may describe specific issues or problems that arose while building, and addressing these issues may resolve the problem.
Check whether any snapshots that reduce the volumes of your project's buses are active. If a snapshot that silences a bus is active when it should not be, removing the unwanted instances of that snapshot should result in that bus's events becoming audible again. You can audition the effects of a snapshot in the mixer window by selecting the snapshot in the snapshots browser and pressing the play button in the transport controls.
Check that your game's code is correctly creating and starting instances of your project's events. For information about playing events in the FMOD Engine, see the Playing Events section of the FMOD Engine User Manual.
Check that the FMOD Studio system is being initialized correctly by your game's code. Failing to initialize the FMOD Studio system correctly can result in a complete failure of all audio in your game. For more information about initializing the FMOD Studio system, see the Getting Started white paper in the FMOD Engine User Manual.
Check that the FMOD_OUTPUTTYPE specified in your game's code is correct for producing audible output on the platform on which your game is being run. If you are using an ASIO output device, check that the driver is not being taken by another application, and ensure that a fallback option is available.
Check whether the affected events are subject to distance-based attenuation. An event may be subject to distance-based attenuation if it includes at least one of the following:
Events with distance attenuation may also be silent at other distances if they are subject to multiple forms of distance attenuation.
Check the affected events' stealing behavior. An event whose max instances property is less than ∞ may have its instances stolen according to its stealing property, preventing those instances from playing. Events with the oldest, quietest, virtualize, or furthest stealing behaviors may end suddenly when new instances of those events are started, and events with the furthest or none stealing behaviors may not start if too many instances of the event are already playing.
Check the stealing behavior of the group buses into which the affected events are routed. An event routed into a group bus whose max instances property is less than ∞ may have its instances stolen according to the group bus's stealing property, preventing those instances from playing. Group buses with the oldest, quietest, or furthest stealing behaviors may cause event instances to stop when new instances of those events are started, and group buses with the furthest or none stealing behaviors may prevent new event instances from starting if too many playing event instances are routed into the bus.
If you want to stop an event's instances from being stolen due to bus instance limiting, try increasing the bus's max instances property, or routing fewer events into that bus. Alternatively, setting the event's priority to Highest prevents its instances from being stolen, but may cause other events' instances to be stolen instead.
If the affected events contain programmer instruments, make sure that your game's code is correctly receiving and handling the generated callback. For information on programmer instrument callbacks, see the FMOD_STUDIO_PROGRAMMER_SOUND_PROPERTIES section of the FMOD Engine User Manual.
Check whether the affected events have content that might be causing them to stop automatically. A non-persistent event stops automatically if it is not currently producing any output and there is no further content on its timeline. If the affected events are stopping automatically when you would prefer they wouldn't, change their content so that they stop under different circumstances. For more information on when events stop naturally, see the Auditioning Events section of the Authoring Events chapter. If you prefer that an affected event does not automatically stop under any circumstances, try making it persistent.
Check the affected events' stealing behavior. An event whose max instances property is less than ∞ may have its instances stolen according to its stealing property, potentially stopping the stolen instances from playing to completion. Events with the oldest, quietest, virtualize, or furthest stealing behaviors may end suddenly when new instances of those events are started.
Check the stealing behavior of the group buses into which the affected events are routed. An event routed into a group bus whose max instances property is less than ∞ may have its instances stolen according to the group bus's stealing property, stopping the stolen instances from playing to completion. Group buses with the oldest, quietest, or furthest stealing behaviors may cause event instances to stop when new event instances are routed into that bus.
Search your project for command instruments that might stop the affected events. You can search for instruments that reference an event by right-clicking on that event in the events browser and selecting "Find References > In Events" from the context menu. If a command instrument is stopping an event when it should not be, adjust its position and trigger conditions to ensure it only stops the target event at appropriate times.
Check whether your game's code is stopping the affected events. If your game's code is designed to stop certain events, make sure it is doing so in the correct circumstances. For information about stopping events in code, see the Studio::EventInstance::stop section of the FMOD Engine User Manual. You can see whether and when a Studio::EventInstance::stop command is being called by recording a profiler session using live update.
Make sure your game's code is setting the FMOD Engine's random seed. If your code does not set a seed for the FMOD Engine's random number generation, the FMOD engine will default to a seed of 0 when the Studio::System is initialized. Using the same seed each time causes the same random numbers to be generated each of those times, which can be useful for debugging, but may be undesirable for some games. For information on setting random seeds, see the FMOD_ADVANCEDSETTINGS and System::setAdvancedSettings sections of the FMOD Engine User Manual.
If your game's code is setting the FMOD Engine's random seed, make sure it is setting a different seed each time the game is run. Using the same seed each time you initialize the Studio::System results in identical behavior each time. A popular method of guaranteeing a different seed is to use the current time.
Ensure the music assets are not set to stream. Streaming sounds depend on loading, playing, and unloading audio files a chunk at a time, meaning that streaming audio cannot scheduled for a precise moment. In addition, most platforms can only support a very small number of simultaneous streams, and produce choppy output if that number is exceeded. Switching an affected asset to not stream causes the entire asset to be loaded into memory, but improves the precision with which it can be scheduled.
Try setting the priority macro control of the affected event to Highest. The FMOD Engine's low-level voice limiting system automatically culls inaudible voices in order to keep resource consumption low, then restores those voices when they become audible. If a voice from a music event is restored in this fashion, it may start again from the beginning and be out of sync with other playing music. Setting an event's priority to Highest prevents its voices from being culled, even when they are inaudible.
Make sure the modulator isn't on a synchronous instrument. Synchronous instruments produce no output when not overlapped by the playback position, and so do not play their release periods when no longer overlapped. This means that if a synchronous instrument is untriggered because it is no longer overlapped by the playback position, it stops producing audio immediately, even if it has an AHDSR modulator.
Make sure the modulator isn't on a property of an instrument inside an instrument's playlist. Untriggering an instrument does not untrigger the individual instruments in that instrument's playlist, so untriggering an instrument does not cause AHDSR modulators on playlist entry properties to play out their releases.
Ensure the modulator is on a property that will cause it to enter its release at the correct time. Each AHDSR modulator is tied to a specific event, instrument, or snapshot, and its behavior is based on the state of that event, instrument, or snapshot.
The release periods of AHDSR modulators on instruments (including event instruments and snapshot instruments) begin when their associated instruments are untriggered. This means that the release period of an AHDSR modulator on an instrument does not start when the parent event is stopped, but when the instrument is untriggered. It also means that an AHDSR modulator on an instrument can only play out its full release period if the parent continues playing until the release period ends. This behavior allows an event to have complex stopping behavior, instead of always immediately stopping all the instruments in the event.
The release periods of AHDSR modulators on event or snapshot properties, such as macros, tracks, effects, and local parameter values, begin when the event or snapshot is stopped. This means that the release period of an AHDSR modulator on a snapshot or event begins when the snapshot or event is stopped, regardless of whether it is stopped by your game's code or by a snapshot or event instrument being untriggered.
If you want the AHDSR modulator to affect a snapshot instrument, ensure that the modulator is on an intensity property rather than a volume property. An AHDSR modulator on a track's volume affects only the volume of the signal routed through that track. Snapshot instruments do not produce any output that is mixed into the track's signal, and so are not indirectly affected by modulators on the track's volume as other instruments are.
If the snapshot is triggered as an event, make sure the snapshot's intensity macro has an AHDSR modulator. Modulators on the intensity property of a snapshot instrument only affect instances of the snapshot triggered by that snapshot instrument. If you want a snapshot triggered as an event to play out the release period of an AHDSR modulator, that modulator must be on the intensity macro of the snapshot, rather than on the intensity property of a snapshot instrument elsewhere in the project.
If the snapshot is triggered by a snapshot instrument, make sure that the instrument is untriggered when you want the release to occur. Stopping an event does not automatically untrigger any of the instruments in that event. This means that an AHDSR modulator on a snapshot instrument does not automatically enter its release period when the event containing the instrument is stopped.
If you want an instrument to stop when the event containing it is stopped, one option is to add a parameter trigger condition to the instrument, put an AHDSR modulator on the value of the parameter, and set the properties of the modulator and trigger condition such that stopping the event causes the parameter to change value and untrigger the instrument.
If the snapshot is triggered by a snapshot instrument, make sure the event continues playing until the release period of the snapshot instrument's AHDSR modulator has finished. When an event finally stops, any instrument in that event stops immediately. Designing an event so that it finally stops only after an instrument's release period finishes ensures that that instrument's release period always has time to finish.
If you want an event to not stop immediately when given a stop command, the easiest option is to add an AHDSR modulator to one of the event's properties. An AHDSR modulator on an event property causes the event to take time to stop even if the modulator does not meaningfully affect the output or behavior of the event. When multiple properties of an event have AHDSR modulators, the modulator with the longest release time determines when the event ends.
Make sure the instrument has an "event state: not stopping" trigger condition. Stopping an event instance does not automatically untrigger all the instruments in that event by default. This is to allow you to create content that continues playing or begins playing while an event instance is stopping.
Adding an "event state: not stopping" trigger condition to an instrument ensures that the instrument is untriggered when the event enters the "stopping" event state.
Check whether the instrument has an AHDSR modulator on any of its properties. An AHDSR modulator on any property of an instrument prevents that instrument from stopping immediately when it is untriggered. Such an instrument continues playing after being untriggered for a period of time equal to whichever of its attached AHDSR modulators' release properties is greatest.
When prompted, choose to restart FMOD Studio in safe mode. In some circumstances, a bad or corrupt plug-in may cause FMOD Studio to crash. Safe mode prevents most plug-ins from being automatically loaded.
Empty or rename your plug-ins folders. In some circumstances, safe mode does not prevent all plug-ins from loading. If crashes persist even in safe mode, renaming or deleting your plug-ins folders should prevent the plug-ins in those folders from being found and loaded.
Plug-ins can be found in the following locations:
%localappdata%/FMOD Studio/Plugins~/Library/Application Support/FMOD Studio/Plugins%fmod_install_directory%/plugins%fmod_bundle%/plugins%project_root_directory%/PluginsIf you are using macOS and running an accessibility application, try disabling that accessibility software. Certain accessibility applications (such as Karabiner, Teleportd, and DisableMonitor) can interfere with FMOD Studio, causing crashes. Disabling the software may prevent the crash from occurring.
If you are using MacOS X version 10.14, open your zoom options and ensure the "Use keyboard shortcut to zoom" and "Continuously with pointer" settings are unchecked. These settings are known to interfere with FMOD Studio in some cases, causing crashes. Switching to "Only when the pointer reaches an edge" instead may fix the problem.
Restore an earlier version of your FMOD Studio project from backup or source control. The data in an FMOD Studio project's metadata folder is essential to that project, and includes almost everything other than the project's audio assets. If your project's metadata folder is deleted, that project must be restored from backup or recreated from scratch.
Build a new version of the bank using the original FMOD Studio project. Bank files are not compressed archives that can be decompressed or extracted in order to recreate the FMOD Studio project from which they were built. They're a proprietary binary format, and the process of building them is not reversible.
Launch FMOD Studio with the environment variable “QTWEBENGINE_DISABLE_SANDBOX=1”. You can do this by typing the following at a terminal prompt :
QTWEBENGINE_DISABLE_SANDBOX=1 ./fmodstudio
Or, if you're using the FMOD Studio .AppImage :
QTWEBENGINE_DISABLE_SANDBOX=1 ./fmodstudio20222linux64-installer.AppImage
Verify that the issue is a bug by reading the other sections of this troubleshooting guide. Some of the stumbling blocks listed above are commonly mistaken for bugs. If any of them sounds like your issue, and you are able to solve the issue by using one of the methods described for that problem, then you'll have found your solution.
Search for the issue in the FMOD Forums. If someone else has encountered the same bug as you, there's a high chance that they have already reported it on the FMOD forums. If so, it's possible that someone has responded to their bug report with a solution or workaround that might be useful to you.
Report the bug to Firelight Technologies. There are two ways in which you can report bugs:
Whichever method you choose, be sure to include a description of the bug in your message, along with the version of FMOD Studio you're using, and an explanation of how the behavior you're experiencing differs from the behavior you expect.
Regardless of how you contact us, we'll send a reply confirming that we've received your bug report, and asking for any additional information we need to investigate the issue.
We may ask you to send us the log file of an FMOD Studio session in which the bug occurred. On Windows, FMOD Studio's log files can be found in %HOMEPATH%\AppData\Local\FMOD Studio\Logs. On macOS, they can be found in ~/Library/Application Support/FMOD Studio. On Linux, they can be found in ~home/FMOD Studio/Logs.
Once we understand the nature of the bug, we'll add it to our bug tracker, and begin working on a fix to be released in an upcoming version of FMOD Studio. We'll also let you know about any workarounds for the issue that we've discovered, so that you can keep working until the fix becomes available.