FMOD Studio is a game changing Pro Audio content creation pipeline for sound designers and musicians. FMOD Studio programmer’s API is the interface for programmers to load FMOD Studio projects and play them back in realtime. Also includes a low level API for simple sounds/channels/dsp/geometry.
SupersonicSound is a C# wrapper for the FMOD studio API. There are a few wrappers for FMOD ex, the legacy sound system, but as far as I am aware SupersonicSound is the only C# wrapper for the modern FMOD Studio programmers API.
The aim of the SupersonicSound is to present a much more C# friendly experience for using FMOD studio programmers API.
I do not control licensing of any FMOD technologies! You should go here to the FMOD sales page and check what the licensing conditions are before proceeding any further! As of January 1st 2015 the licensing conditions are very friendly to indies, non-commercial and educational uses.
This library itself is MIT licensed, see the LICENSE.md file for more details.
SupersonicSound is currently built with compatibility for FMOD 1.10.08 (latest as of August 28th 2018).
Upgrading or downgrading to other versions is relatively easy - just drag in the new C# wrapper and a new set of binaries (shipped with FMOD API). Methods which have been removed in FMOD will trigger a compile error as SupersonicSound tries to reference the now non-existant methods. New methods can be added on an as-needed basis (PRs much appreciated). The unit tests in the project will check all of the Enums in SupersonicSound to ensure they have equivalent values to the underlying FMOD enums.
The easiest way to get started using SupersonicSound is to use the nuget package. Run:
Install-Package SupersonicSound
at the nuget package manager console. Currently this package requires .Net 4.5 (due to a dependency on System.Numerics).
Unfortunately FMOD licensing does not allow for the FMOD dlls to be distributed with the nuget package and you will need to download these yourself.
SupersonicSound is almost a direct translation from the C++ API but instead does things in C# style. For example to get a parameter from an event instance in C++ is:
FMOD.Studio.ParameterInstance instance;
ERRCHECK(_eventInstance.getParameter(name, &instance));
return instance;
Doing the same in C# is:
return _eventInstance.Parameters[name]; //throws an exception if there is an error
Because the two APIs are so similar you should be able to follow along with the documentation supplied with the C++ API without any trouble. If you find any places where SupersonicSound is inconsistent then please create an issue here. Here's a more complete example of how to load banks, get an event from them and then play back a sound with a varying parameter:
using (System system = new System())
{
// Load bank from disk
var master = system.LoadBankFromFile("Master Bank.bank", BankLoadingFlags.Normal);
var strings = system.LoadBankFromFile("Master Bank.strings.bank", BankLoadingFlags.Normal);
var bank = system.LoadBankFromFile("Surround_Ambience.bank", BankLoadingFlags.Normal);
// Get a single playback event
var loopingAmbienceDescription = system.GetEvent("event:/Ambience/Country");
//Create an instance of it
var loopingAmbienceInstance = loopingAmbienceDescription.CreateInstance();
// Get a parameter from this playback instance
var timeParam = loopingAmbienceInstance.Parameters["Time"];
// Start playing it
loopingAmbienceInstance.Start();
// Loop forever, playing the sound
while (true)
{
Thread.Sleep(1);
// Update the playback system
system.Update();
// Vary the parameter we fetched earlier
timeParam.Value = (float)(DateTime.Now.TimeOfDay.TotalSeconds * 0.025f) % 1;
}
}
Supplied with the FMOD Studio API is a C# wrapper which is almost a direct translation of the C++ API. SupersonicSound is built around this wrapper and acts as a translation layer from C# conventions to the C++ conventions.
The supplied FMOD C++ wrapper is included almost unchanged in SupersonicSound/Wrapper/Fmod (some very minor changes were required to expose some private fields as internal - this seems to have been an implementation mistakes by the FMOD wrapper programmers). This means that when a new FMOD version is released (with a new FMOD wrapper) it should be very simple to update SupersonicSound to the new version - simply drop in the new wrapper and the new DLLs.
Obviously a wrapper around a native API requires some native DLLs! SupersonicSound DLLs are loaded as soon as you try to create a "System" (a core part of the FMOD API). You can load the DLLs early by calling Native.Load(). If you have already loaded the fmod DLLs yourself, you can instead call Native.SuppressLoad() - be warned this will cause a System.DllNotFoundException if you have not loaded the correct DLLs.
The required DLLs are:
- fmod.dll
- fmodstudio.dll
The wrapper supplied with FMOD allocates objects to wrap up C++ handles in C# objects. If SupersonicSound also allocated objects to wrap these objects that would make this wrapper excessively allocation heavy. Instead all the SupersonicSound wrappers are structs which have been optimised to be very small (the most commonly used ones are pointer sized). This makes using SupersonicSound almost a zero cost abstraction.
- Martin Evans - Project Owner
- Hakan Lindestaf - FMOD upgrades, examples and other improvements
Contributions are welcome! Please open up an issue before you write any code though, just in case I'm already working on something similar.
- Async file systems are not supported. There seems to be a problem with the underlying FMOD wrapper being incorrectly structured.