FMOD Studio provides a Scripting API that allows us to control and edit the application by writing JavaScript code. This is extremely useful when automating tasks or to extend functionalities of the editor. It is possible to create scripts to bulk rename markers, parse spreadsheets to create events, create ScriptableObjects .cs files for Unity for example.
There a three ways to use the Scripting API:
- Directly executing commands in the console interface.
- Writing and executing .js scripts.
- Sending commands via TCP/IP.
Let’s have a brief look at each method.
Using the console to execute commands
We can input commands directly into the console. You can open the console by pressing CTRL+0 or clicking on the menu item Window->Console:
Creating and executing a script
To execute a script in FMOD Studio you need to create a Scripts folder in the root directory of your FMOD Project. Alternatively, you can use the scripts folder already present in the installation directory of FMOD Studio. There is also a system-wide Scripts folder placed under %localappdata%/FMOD Studio/Scripts
on Windows and ~/Library/Application Support/FMOD Studio/Scripts
on macOS. A minimal JavaScript script example might look like this:
Here we are adding a new menu item to the Scripts menu bar by calling studio.menu.addMenuItem
. After reloading your scripts by clicking on Scripts->Reload you’ll find the new menu entry in the scripts menu bar. By clicking on the script the code inside the execute function will be executed. In this example we are printing hello world to the console.
Sending commands via TCP/IP
When opening the console you can see the IP and port you can connect to:
You can test the connection by using a software like Packet Sender to send commands to FMOD Studio:
If you are working on an external tool, it should be easy to interface with FMOD Studio. Managing and editing a FMOD project inside your game engine should also be possible with a few scripts.
Command list
Here you can find a list of commands I personally find useful. For a more complete overview of the API, consult the Scripting API documentation page. You can get the properties of any object in FMOD Studio project by calling dump()
on that object.
Event commands
Getting all events
findInstances() will return an array containing all event ManagedObjects
.
Getting the current selected event in the event browser
Getting an event
Creating an event
Setting the name of the event
Creating a folder
Assigning a folder to an event
Adding a group track to the event
Adding instruments to a group track
parameter is the parameter we are adding the instrument to. If you want to add an instrument to the timeline sheet, use the timeline
property of a ManagedObject:Event. start and length is the respective start time and length in seconds.
To add a Single Instrument to the track on the timeline we would write:
The following instruments are available:
SingleSound
MultiSound
ProgrammerSound
SoundScatterer
Importing an audio asset into the FMOD project
path is the file path. It will return an AudioFile ManagedObject. It will return null
if it can’t find the file.
Assigning an audio asset to a Single Instrument
Assigning Single Instruments to a Multi Instrument
First, create a new multi instrument:
Then set the multi instrument to the owner of the single instrument :
The same principle applies to a scatterer instrument.
Adding effects to the master track of an event
The following effects are available:
ThreeEQEffect
GainEffect
ChannelMixEffect
ChorusEffect
CompressorEffect
ConvolutionReverbEffect
DistortionEffect
DelayEffect
FlangerEffect
LimiterEffect
MultibandEqEffect
PitchShifterEffect
SFXReverbEffect
TransceiverEffect
TremoloEffect
HighpassEffect
HighpassSimpleEffect
LowpassEffect
LowpassSimpleEffect
ParamEqEffect
SpatialiserEffect
ObjectSpatialiserEffect
LoudnessMeter
Getting the currently selected item in the editor window
This can be a marker, an instrument and so on.
Setting the max instances value of an event
Parameter commands
Getting all the parameters of an event
Adding a new parameter to an event
studio.project.parameterType corresponds to the parameter types available. These are:
User
Distance
Direction
Elevation
EventConeAngle
EventOrientation
UserEnumeration
Adding a labeled parameter to an event
First, create a parameter with the UserEnumeration parameterType:
Create an array containing your parameter values and assign the array to the enumerationLabels of the parameter:
Setting the initial value of a parameter
Mixer commands
Getting all mixer groups
findInstances() will return an array containing all mixer groups.