fmod_flutter

A Flutter plugin for FMOD Studio audio engine integration. Add professional game audio to your Flutter apps with FMOD's powerful features including 3D audio, real-time parameters, and adaptive music.

Features

✅ Play FMOD Studio events (music, sound effects, ambient audio)
✅ Real-time parameter control
✅ Pause/resume/stop events
✅ Volume control per event
✅ Multiple bank loading
✅ Cross-platform:
- iOS: Full native integration (device & simulator)
- Android: Full native integration
- Windows: Full native integration (x64)
- macOS: Full native integration
- Web: Experimental WebAssembly support

Quick Start: Run the Example App

The example app includes audio banks, but you need to set up FMOD Engine native libraries first.

1. Clone Repository

git clone https://github.com/SuperWes/fmod_flutter.git
cd fmod_flutter

What you have now:

✅ Example app code and audio banks
❌ FMOD Engine native libraries (required to run)

2. Download FMOD Engine

FMOD Engine files are proprietary and not included in this repo. Each developer must download them:

Create free account at fmod.com/download
Download FMOD Studio API (NOT FMOD Studio) for your platform:
- iOS: fmodstudioapi*ios-installer.dmg
- Android: fmodstudioapi*android.tar.gz
- macOS: fmodstudioapi*mac-installer.dmg
- Windows: fmodstudioapi*win-installer.exe (see Windows Setup below)
- Web: fmodstudioapi*html5.zip

3. Run Setup Script

Important: Run these commands from the plugin root (fmod_flutter/), NOT from the example directory.

# Make sure you're in the plugin root directory
# pwd should show: .../fmod_flutter

# Create engines directory
mkdir engines

# Move your downloaded FMOD files to engines/
# engines/fmodstudioapi*ios-installer.dmg
# engines/fmodstudioapi*android.tar.gz
# engines/fmodstudioapi*html5.zip

# Run setup (extracts SDKs and copies native libraries)
dart tool/setup_fmod.dart

What this does:

Extracts FMOD SDKs
Copies iOS libraries to ios/FMOD/
Copies Android libraries to example/android/app/src/main/jniLibs/
Copies Windows libraries to windows/FMOD/
Copies macOS libraries to macos/FMOD/
Copies Web files to example/web/fmod/

4. Run Example

Now you can move to the example directory and run the app:

cd example
flutter run

The example app demonstrates:

FMOD initialization
Loading banks
Playing music and sound effects
Parameter control
Event management

Add to Your Own Project

Step 1: Add Plugin

# pubspec.yaml
dependencies:
  fmod_flutter:
    git:
      url: https://github.com/SuperWes/fmod_flutter.git
  # Or when published: fmod_flutter: ^0.1.0

flutter pub get

Step 2: Set Up FMOD

# In your project root
mkdir engines

# Download FMOD Studio API from fmod.com
# Place downloaded files in engines/

# Run setup script
dart run fmod_flutter:setup_fmod

The script will:

Extract SDK archives
Copy native libraries to android/app/src/main/jniLibs/
Copy iOS libraries to ios/FMOD/
Copy macOS libraries to macos/FMOD/
Copy Windows libraries/DLLs to windows/FMOD/
Copy web files to web/fmod/

Step 3: Add Your Audio Banks

Option A: Use Sample Banks (Quick Test)

Copy example banks from this plugin:

mkdir -p assets/audio
cp path/to/fmod_flutter/example/assets/audio/*.bank assets/audio/

Option B: Create Your Own (Recommended)

Download FMOD Studio from fmod.com/download
Create your audio project
Build banks: File → Build
Copy .bank files to assets/audio/

Update pubspec.yaml:

flutter:
  assets:
    - assets/audio/Master.bank
    - assets/audio/Master.strings.bank
    - assets/audio/Music.bank
    - assets/audio/SFX.bank

Step 4: Initialize FMOD

import 'package:fmod_flutter/fmod_flutter.dart';

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final fmod = FmodService();
  bool _isReady = false;

  @override
  void initState() {
    super.initState();
    _initFmod();
  }

  Future<void> _initFmod() async {
    // Initialize
    final initialized = await fmod.initialize();
    if (!initialized) {
      print('FMOD initialization failed');
      return;
    }

    // Load banks
    final loaded = await fmod.loadBanks([
      'assets/audio/Master.bank',
      'assets/audio/Master.strings.bank',
      'assets/audio/Music.bank',
      'assets/audio/SFX.bank',
    ]);

    setState(() => _isReady = initialized && loaded);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('FMOD Flutter')),
        body: Center(
          child: _isReady
              ? ElevatedButton(
                  onPressed: () => fmod.playEvent('event:/main_music'),
                  child: Text('Play Music'),
                )
              : CircularProgressIndicator(),
        ),
      ),
    );
  }
}

Step 5: Play Audio

// Play events
await fmod.playEvent('event:/main_music');
await fmod.playEvent('event:/gun_shoot');

// Stop events
await fmod.stopEvent('event:/main_music');

// Control parameters
await fmod.setParameter('event:/main_music', 'Intensity', 0.8);

// Pause/resume
await fmod.setPaused('event:/main_music', true);
await fmod.setPaused('event:/main_music', false);

// Volume control (0.0 to 1.0)
await fmod.setVolume('event:/main_music', 0.5);

Platform Setup Details

iOS

The setup script copies FMOD libraries to your app's ios/FMOD/ directory:

ios/FMOD/include/ - Header files
ios/FMOD/lib/device/ - Device libraries (libfmod_iphoneos.a, libfmodstudio_iphoneos.a)
ios/FMOD/lib/simulator/ - Simulator libraries (libfmod_iphonesimulator.a, libfmodstudio_iphonesimulator.a)

The plugin's podspec automatically links the correct libraries for device vs simulator builds. No Podfile modifications needed!

First build: May take longer as CocoaPods processes FMOD libraries.

Troubleshooting:

cd ios
pod deintegrate
pod install
cd ..
flutter clean
flutter run

Android

✅ Full JNI integration - uses native C++ to call FMOD's C++ API via JNI (Java Native Interface).

The setup script copies FMOD files to your app:

android/app/src/main/jniLibs/*/libfmod.so - native libraries
android/app/src/main/jniLibs/*/libfmodstudio.so - native libraries
android/app/libs/fmod/fmod.jar - Java classes

Supported architectures:

arm64-v8a (modern 64-bit devices)
armeabi-v7a (older 32-bit devices)
x86 & x86_64 (emulators)

The plugin uses CMake to build the native JNI wrapper that bridges Kotlin to FMOD's C++ API. At build time, gradle copies the FMOD files from your app to the plugin.

Troubleshooting: Rerun dart run fmod_flutter:setup_fmod to restore libraries.

Windows

The Windows FMOD SDK is distributed as an .exe installer, which the setup script cannot extract automatically. You must run the installer first, then copy the installed SDK folder.

Step-by-step:

Run fmodstudioapi*win-installer.exe — this installs to C:\Program Files (x86)\FMOD SoundSystem\FMOD Studio API Windows\ by default

Copy the installed folder into engines/windows/:

# From your project root
mkdir engines\windows\fmodstudioapi20312win
xcopy "C:\Program Files (x86)\FMOD SoundSystem\FMOD Studio API Windows\*" engines\windows\fmodstudioapi20312win\ /E /I

Run the setup script:
```
dart run fmod_flutter:setup_fmod
```

The setup script copies FMOD files to your app's windows/FMOD/ directory:

windows/FMOD/lib/ - Import libraries (fmod_vc.lib, fmodstudio_vc.lib)
windows/FMOD/dll/ - Runtime DLLs (fmod.dll, fmodstudio.dll)
windows/FMOD/include/ - Header files

Important: The folder inside engines/windows/ must be named fmodstudioapi* (e.g. fmodstudioapi20312win). If you just dump the files directly into engines/windows/, the setup script won't find the SDK.

Troubleshooting:

# Verify the SDK structure is correct:
dir engines\windows\fmodstudioapi*\api\core\lib\x64\
# Should show fmod.dll and fmod_vc.lib

macOS

The setup script copies FMOD libraries to your app's macos/FMOD/ directory:

macos/FMOD/lib/ - Dynamic libraries (libfmod.dylib, libfmodstudio.dylib)
macos/FMOD/include/ - Header files

The plugin's podspec automatically links the libraries. No Podfile modifications needed!

Troubleshooting: Rerun dart run fmod_flutter:setup_fmod to restore libraries.

Web (Experimental)

Add to web/index.html in <head>:

<script src="fmod/fmodstudio.js" defer></script>

Note: Web support is experimental. Production builds may require additional configuration.

.gitignore Configuration

For Private/Closed-Source Projects

You can commit FMOD files! For your private game repository, it's often easier to commit:

✅ engines/ (or the extracted SDK files)
✅ android/app/src/main/jniLibs/libfmod*.so
✅ ios/FMOD/
✅ macos/FMOD/
✅ windows/FMOD/
✅ web/fmod/

Your team members just clone and build - no setup needed!

For Open Source / Public Repositories

Don't commit FMOD files. Add to your .gitignore:

# FMOD SDK files (proprietary - can't redistribute publicly)
engines/
android/app/src/main/jniLibs/libfmod*.so
android/app/libs/fmod/
ios/FMOD/
macos/FMOD/
windows/FMOD/
web/fmod/

Each user downloads FMOD with their own account and runs dart run fmod_flutter:setup_fmod.

Why? FMOD's license prohibits public redistribution. Anyone using your open source project must download FMOD themselves.

API Reference

FmodService

final fmod = FmodService();

// Initialize FMOD engine
Future<bool> initialize()

// Load bank files
Future<bool> loadBanks(List<String> paths)

// Play an event
Future<void> playEvent(String eventPath)

// Stop an event
Future<void> stopEvent(String eventPath)

// Set event parameter
Future<void> setParameter(String eventPath, String paramName, double value)

// Pause/resume event
Future<void> setPaused(String eventPath, bool paused)

// Set event volume (0.0 to 1.0)
Future<void> setVolume(String eventPath, double volume)

// Release resources (call on app shutdown)
Future<void> release()

Troubleshooting

"FMOD not initialized" or "Banks not loaded"

Solution:

# Rerun setup
dart run fmod_flutter:setup_fmod

# Clean and rebuild
flutter clean
flutter pub get
flutter run

iOS: CocoaPods errors

Solution:

cd ios
pod deintegrate
rm Podfile.lock
pod install
cd ..
flutter clean
flutter run

Android: "Library not found"

Solution: Verify libraries exist:

ls -la android/app/src/main/jniLibs/arm64-v8a/
# Should show libfmod.so and libfmodstudio.so

If missing, rerun: dart run fmod_flutter:setup_fmod

"Event not found"

Solution:

Verify event paths match FMOD Studio (case-sensitive!)
Check console logs for available events
Ensure banks are loaded before playing events

Web: "FMOD not loaded"

Solution:

Verify web/fmod/fmodstudio.js exists
Check web/index.html includes script tag
Try production build: flutter build web

Team Workflow

For Private Projects (Recommended)

Commit FMOD files to your repo:

Team setup:

One person runs dart run fmod_flutter:setup_fmod
Commit the generated ios/FMOD/, android/.../jniLibs/, etc.
Team members just clone and build - done!

For Open Source Projects

Each team member downloads FMOD:

Clone your project
Run flutter pub get
Create engines/ directory
Download FMOD SDKs from fmod.com (with their account)
Run dart run fmod_flutter:setup_fmod
Build and run!

(Don't commit engines/ or FMOD native files - see .gitignore section)

FMOD Resources

Download FMOD: fmod.com/download
FMOD Documentation: fmod.com/docs
FMOD Studio: Video Tutorials
Licensing: fmod.com/licensing
- Free for indie (< $500k revenue/year)
- Commercial licenses available

License

Plugin: MIT License

FMOD Engine: Proprietary license from Firelight Technologies

Free for indie developers
Requires account at fmod.com
See fmod.com/licensing

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Example App

See example/ directory for a complete demo with:

Initialization flow
Bank loading
Music playback
Sound effects
Parameter control
UI feedback

Run it: cd example && flutter run

Support

Issues: GitHub Issues
Questions: Open a discussion on GitHub
FMOD Help: FMOD Forums

Made with 🎵 for Flutter game developers

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
android		android
assets/images		assets/images
bin		bin
engines		engines
example		example
ios		ios
lib		lib
macos		macos
tool		tool
web		web
windows		windows
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
QUICK_START.md		QUICK_START.md
README.md		README.md
analysis_options.yaml		analysis_options.yaml
pubspec.yaml		pubspec.yaml

License

SuperWes/fmod_flutter

Folders and files

Latest commit

History

Repository files navigation

fmod_flutter

Features

Quick Start: Run the Example App

1. Clone Repository

2. Download FMOD Engine

3. Run Setup Script

4. Run Example

Add to Your Own Project

Step 1: Add Plugin

Step 2: Set Up FMOD

Step 3: Add Your Audio Banks

Option A: Use Sample Banks (Quick Test)

Option B: Create Your Own (Recommended)

Update pubspec.yaml:

Step 4: Initialize FMOD

Step 5: Play Audio

Platform Setup Details

iOS

Android

Windows

macOS

Web (Experimental)

.gitignore Configuration

For Private/Closed-Source Projects

For Open Source / Public Repositories

API Reference

FmodService

Troubleshooting

"FMOD not initialized" or "Banks not loaded"

iOS: CocoaPods errors

Android: "Library not found"

"Event not found"

Web: "FMOD not loaded"

Team Workflow

For Private Projects (Recommended)

For Open Source Projects

FMOD Resources

License

Contributing

Example App

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages