FMOD Batch Importer

Why Use This Tool?

Importing audio assets into FMOD Studio requires several manual steps per sound: creating an event, adding an audio track, assigning a bank, routing to a bus, and organizing into folders. This process repeats for every file in your project.

FMOD Batch Importer Tool automates this workflow. Point it at a folder of audio files, and it will:

• Match audio files to existing events or create new ones
• Organize events into the correct folder structure
• Assign banks, buses, and asset folders based on your templates
• Process entire directories in a single operation

‍

‍

‍

How It Works

The FMOD Batch Importer operates directly on your FMOD project's XML files, bypassing FMOD Studio's manual workflow:

1. Project Parsing: The tool reads your .fspro project and indexes all existing events, banks, buses, and folder structures.
2. File Scanning: Audio files in the selected directory are scanned and their filenames are parsed using value-based matching to extract prefix, feature name, and action segments.
3. Event Matching: In Match Template mode, each audio file is compared against template events using fuzzy matching and scored by confidence. In Generate from Pattern mode, events are built from the naming pattern.
4. XML Generation: For each matched or generated event, the tool writes the corresponding FMOD XML structures (event definitions, audio tracks, instrument containers, bank and bus assignments).
5. FMOD Studio CLI Import: The tool invokes fmodstudiocl.exe to finalize the import and register the new assets within the project.

‍

‍

‍

CRITICAL WARNING

ALWAYS CLOSE FMOD STUDIO BEFORE USING THIS TOOL!

This tool directly manipulates XML files in your FMOD project. Having FMOD Studio open while running this tool can cause:

• Data corruption
• Loss of changes
• Conflicts between the tool and FMOD Studio
• Unpredictable behavior

Recommended workflow:

1. Close FMOD Studio completely
2. Run FMOD Batch Importer Tool
3. Complete your import
4. Open FMOD Studio
5. Save your project (Ctrl+S)

Features

• Automatically create FMOD events from audio files
• Detect and import from existing template folders
• Match audio files with events using fuzzy matching
• Organize events in specific folders
• Assign banks, buses, and asset folders
• Recursive subdirectory scanning with duplicate conflict resolution
• Dynamic Tag System with value-based parsing and $actions tag
• Case format selection (Title_Case, PascalCase, camelCase, snake_case, etc.)
• Choose between MultiSound and SoundScatterer instrument types
• Build banks directly after import
• Dark mode support

‍

‍

‍

Requirements

Required Software

FMOD Studio

• Version 2.0 or higher recommended
• Works with FMOD Studio projects (.fspro)

macOS Requirements

Important for macOS Users:

The system Python on macOS (3.9.6) ships with an outdated Tkinter 8.5 that causes GUI rendering issues (blank window). You must install Python 3.11+ with modern Tkinter 8.6.

Option 1 - Homebrew (Recommended):

brew install python@3.11 python-tk@3.11

Option 2 - Python.org:

Download Python 3.11+ from python.org

Verification:

The launcher script (launch.command) automatically detects and uses the correct Python version. It displays the detected Python and Tkinter versions at launch.

‍

‍

‍

Usage

Launching the Application

Windows:

• Double-click FmodImporter.exe
• The first launch may take a few seconds as the executable extracts its dependencies.

macOS:

• Double-click launch.command in the FmodImporter-Dev folder
• Requires Python 3.11+ (see Requirements)
• The launcher automatically detects the correct Python version

‍

‍

‍

User Guide

1. Paths

Close FMOD Studio before proceeding.

• FMOD Project (.fspro): Select your project file. The project loads automatically on selection.
• Media Files Directory: Folder containing your audio files (.wav, .mp3, etc.). Check Recursive to include subdirectories (off by default).
• FMOD Studio Executable: Path to fmodstudiocl.exe or FMOD Studio.exe. Auto-detected on macOS. Configure in Settings if not found automatically.

The Version Info panel shows the project and executable FMOD versions, with a status indicator (✓ match / ⚠ mismatch).

All paths can be saved as defaults via Settings so they load automatically on next launch.

2. Pattern Setup

This section controls how events are named and matched. It contains two import modes, selectable via radio buttons:

Match Template Mode (Default)

Use this mode when you have existing FMOD events to use as templates.

A Template Folder is an FMOD event folder containing pre-configured events with settings you want to reuse (FX chains, volume, bus routing, etc.). These events follow a consistent naming pattern with action suffixes. For example:

BossTemplate/
├── PrefixFeatureNameAlert
├── PrefixFeatureNameAmbush
├── PrefixFeatureNameAttackA
├── PrefixFeatureNameAttackB
├── PrefixFeatureNameAttackC
├── PrefixFeatureNameDeath
├── PrefixFeatureNameHit
├── PrefixFeatureNameIdleA
└── PrefixFeatureNameRun

When you create a new feature (e.g., FeatureName = "BlueEyesWhiteDragon"), the tool matches your audio files to these template events by their action suffixes (Alert, Ambush, AttackA, etc.), then duplicates the template events with their full configuration, preserving FX, volume, and routing, while renaming them to match the new feature (SfxBlueEyesWhiteDragonAlert, SfxBlueEyesWhiteDragonAttackA, etc.).

How it works:

1. Select a Template Folder containing existing events
2. The tool matches your audio files to template events using fuzzy matching
3. New events are created based on the template structure, preserving all settings

Check Auto-create missing events to generate events for files that don't match any template.

Generate from Pattern Mode

Use this mode to create events based on file naming patterns, without templates. The Template Folder field is hidden in this mode.

1. The tool parses filenames using value-based matching to find prefix and feature values
2. Events are created based on the Event Name Format pattern

Common fields (both modes)

• Prefix: Prefix for event names (e.g., "Sfx"). The tool uses this value to identify and parse your audio filenames, and to build the $prefix segment of event names.
• FeatureName: Feature or character name (e.g., "BlueEyesWhiteDragon"). Same as Prefix: the tool uses this value to parse filenames and to build the $feature segment. In Match Template mode, this is also what replaces the template's original feature name in the new events.
• Event Name Format: Pattern defining how the new events will be named (e.g., $prefix_$feature_$actions). This does not affect how existing template events are read, only how the output events are constructed. Use the ? button for tag reference.
• Case Format: Output format: Title_Case, PascalCase, camelCase, snake_case, UPPER_CASE, lowercase, or As-Is

A live preview below the pattern field shows the formatted event name based on your current settings.

Which mode should I use?

3. Import Setup

This section defines where events are created and how they are routed:

• Event Folder Path: FMOD folder where events are created
• Asset Folder Path: Audio asset folder for imported files
• Bank Path: FMOD bank to assign to events
• Bus Path: Mixing bus for events. In Match Template mode, the bus is auto-detected from the template if available. If no bus is selected or found in the template events, events default to the Master bus.

4. Preview and Workflow

Click Analyze to populate the preview. The main area shows:

A legend bar above the tree summarizes the key interactions and confidence indicators:

| Click ☑ column to toggle import | Confidence: ✓ High (≥95%)  ~ Good (≥85%)  ? Uncertain (≥70%) | + Auto-created (Double-click to rename)

Matched Events tree with columns:

• Event Name: Hierarchical view of events and their audio files
• ☑: Toggle import on/off per event
• Bank: Bank assignment
• Bus: Bus routing
• Instrument: MultiSound or SoundScatterer

Double-click an event name or press F2 to rename it. Right-click for context menu options.

Instrument type: Each event with multiple audio files uses a container instrument. Click the Instrument column on any event to toggle between MultiSound and SoundScatterer. To change all events at once, use the "All → Multi" / "All → Scatterer" buttons below the preview tree.

Confidence indicators:

• ✓: High confidence match (≥95%)
• ~: Good confidence match (≥85%)
• ?: Uncertain match (≥70%)
• +: Auto-created event (no template)

Orphan panels (right side):

• Orphan Events: Events without assigned media. Right-click or drag to assign.
• Orphan Assets: Media files without a matching event. Right-click or drag to assign.

Once satisfied with the matches, click Import.

5. Conflict Resolution

When using Recursive Scan, the tool may find multiple files with the same name in different subdirectories (e.g., FolderA/shot.wav and FolderB/shot.wav).

If conflicts are detected during analysis:

1. A Resolve File Conflicts window appears automatically
2. It lists all duplicate filenames
3. For each file, select which version (path) to use
4. Click "Confirm Selection" to proceed

6. Import and Finalization

Once satisfied with the preview, click Import.

Note: If FMOD Studio is currently open, the tool blocks the import and asks you to close it before proceeding.

A progress dialog tracks each step:

1. "Preparing to import...": Validation
2. "Copying audio files...": Files copied to FMOD Assets folder
3. "Executing FMOD Studio import...": FMOD Studio processing events

The dialog closes automatically on completion. Avoid starting another import until the current one finishes.

After a successful import:

1. You are prompted to build banks. If you accept, a setup dialog lets you select target platforms and build scope (all banks or imported banks only).

2. After the build (or if you decline), you are prompted to open FMOD Studio directly.

3. Once in FMOD Studio, save your project (Ctrl+S).

‍

‍

‍

Advanced Settings

Access via the "Settings" button at the bottom of the interface.

Default Values

Configure default values to skip repetitive setup on each launch:

1. Set up your paths and settings in the main interface
2. Click "Settings"
3. The dialog opens with current values pre-filled
4. Click "Save" to store as defaults
5. On next launch, saved values load automatically

What you can save:

• Default FMOD Project: Your .fspro file path
• FMOD Studio Executable: Path to fmodstudiocl.exe or FMOD Studio.exe
• Default Media Directory: Audio files folder
• Default Template Folder: Commonly used template folder
• Default Bank: Preferred bank
• Default Destination Folder: Default event folder
• Default Bus: Standard mixing bus
• Default Instrument Type: MultiSound or SoundScatterer

‍

‍

‍

Common Use Cases

Case 1: Create variations from a template

Scenario: You have a "WeakTemplate" and want to create events for a new character "Dragon"

1. Import Mode: Match Template (default)
2. Prefix: Sfx
3. FeatureName: Dragon
4. Template Folder: Select "WeakTemplate"
5. Destination Folder: Select or create "Dragon"
6. Media Files: Point to new audio files
7. Analyze then Import

Case 2: Import from consistently named files

Scenario: You have files like Sfx_Dragon_Attack.wav, Sfx_Dragon_Idle.wav

1. Import Mode: Match Template or Generate from Pattern
2. Event Name Format: $prefix_$feature_$actions
3. Case Format: Title_Case
4. Destination Folder: Choose target folder
5. Bank, Bus: Select appropriate values
6. Media Files: Point to your files
7. Analyze then Import

Case 3: Transform file naming to a different format

Scenario: Your files are named sfx_dragon_attack.wav but you want events named SfxDragonAttack

1. Import Mode: Match Template or Generate from Pattern
2. Event Name Format: $prefix$feature$actions
3. Case Format: PascalCase
4. Analyze then Import

‍

‍

‍

Troubleshooting

Error after reverting an import

Scenario: You just imported, then noticed missing files, wrong naming, or incorrect events. You revert the import (manual deletion or source control), adjust your settings, and try to re-import, but the tool displays an error.

Cause: The tool's internal state still reflects the previous import. The FMOD project files on disk have changed externally, but the tool has not reloaded them.

Solution: Click the Refresh button to resynchronize the tool with the current state of the FMOD project, then run Analyze again before importing.

"Could not find FMOD Studio executable"

Cause: FMOD Studio not found in standard installation paths.

Solution (Windows):

1. Click "Settings" button at bottom of window
2. Click "Browse..." next to "FMOD Studio Executable"
3. Select fmodstudiocl.exe or FMOD Studio.exe from your FMOD installation
4. Click "Save"

Solution (macOS):

1. Click "Settings" button
2. Click "Browse..." next to "FMOD Studio Executable"
3. The tool checks common locations and prompts if found
4. If not found, navigate to /Applications and select the executable inside FMOD Studio.app/Contents/MacOS/
5. Click "Save"

"Please specify prefix and feature name"

Cause: Prefix or FeatureName fields are empty or contain placeholder text.

Solution: Fill in both required fields with actual values (not "e.g. Sfx" or "e.g. Dragon").

"Please select an audio asset folder"

Cause: No asset folder selected.

Solution: Click "Select..." next to "Asset Folder" and choose a folder.

"Please select a destination folder"

Cause: Destination folder not selected.

Solution: Click "Select..." next to "Event Folder" and choose a folder.

"Please select a bank"

Cause: No bank selected.

Solution: Click "Select..." next to "Bank" and choose a bank.

Import does nothing / no changes in FMOD

Cause: Changes not saved yet, or FMOD Studio was open during import.

Solution:

1. Ensure FMOD Studio was closed during import
2. If FMOD was open during import, changes may be lost, run import again with FMOD closed
3. Open FMOD Studio
4. File > Save Project (Ctrl+S)

Import progress dialog appears stuck

Cause: Import is processing a large project or FMOD Studio is taking longer than expected.

Solution:

1. Wait, large imports may take several minutes
2. Check if FMOD Studio process is running in Task Manager
3. If stuck for an extended period, the import will timeout automatically
4. If timeout occurs, check:
   • FMOD Studio installation is working correctly
   • Project files are not corrupted
   • Sufficient disk space and permissions
5. Try importing again with a smaller batch of events

Note: The progress dialog cannot be closed manually. This prevents interrupting the FMOD Studio process mid-import, which could corrupt the project.

"FMOD version mismatch detected"

Cause: Project FMOD version doesn't match installed FMOD Studio executable version.

Solution:

1. Check the version display in the main interface (Project version vs Executable version)
2. Either:
   • Update your FMOD Studio installation to match the project version
   • Upgrade/downgrade the FMOD project to match your executable version
3. The tool prevents import until versions match to avoid compatibility issues
4. Version detection is automatic when you load a project

"Failed to load project"

Possible causes:

• FMOD Studio is currently open with the project
• .fspro file is corrupted
• Metadata folder doesn't exist
• Insufficient permissions
• XML files are locked by FMOD Studio

Solution:

1. Close FMOD Studio completely
2. Verify the project opens correctly in FMOD Studio
3. Close FMOD Studio again before using the tool

Audio files not detected

Check:

• Files have extension .wav, .mp3, .ogg, .flac, etc.
• Folder path is correct
• You have read permissions

macOS: Blank window / GUI not visible

Cause: Using system Python 3.9.6 with outdated Tkinter 8.5.

Solution:

1. Install Python 3.11+ with modern Tkinter:
   
   • brew install python@3.11 python-tk@3.11
2. The launcher script automatically detects and uses it
3. Verify: You should see "Tkinter version: Tk 8.6" when launching

If you see this warning:

WARNING: Using system Python (may have old Tkinter 8.5)

Install Python 3.11+ as described above.

‍

‍

‍

Tips and Best Practices

Do

• Always backup your FMOD project before using the tool
• Verify matches before importing
• Use consistent file names for better automatic matching
• Test with a small set of files first

Avoid

• Don't have FMOD Studio open while using this tool (see Critical Warning)
• Don't interrupt import in progress
• Don't modify FMOD project files while tool is running
• Don't use special characters in file names

‍

‍

‍

Updates

To update the tool:

1. Download the new version of FmodImporter.exe
2. Replace the old executable

‍

‍

‍

Support

In case of problems:

1. Check the Troubleshooting section
2. Verify FMOD Studio is correctly installed
3. Test with a simple FMOD project
4. Report bugs with screenshots and steps to reproduce here FMOD Batch Importer Bug Report
5. If you have any suggestion to improve the tool, please report it here FMOD Batch Importer Feature Request

‍

‍

‍

License

This tool is provided "as is" without warranty. Use at your own risk.

Version: 0.17.0 Last update: February 2026

‍

‍

‍

Changelog

v0.17.0 (February 2026)

Branding:

• Added Demute company logo in the header (top-left), clickable to website
• Added social/documentation links in the footer bar (Discord, Documentation, Website)
• Theme-aware logos: automatically swap between light and dark variants

v0.16.8 – v0.16.11 (February 2026)

UI Polish:

• Dynamic scrollbar: hidden when content fits, appears only when needed
• Window height now fits content dynamically at startup
• Renamed UI labels for clarity: "Event Folder" → "Event Folder Path", "Bank" → "Bank Path", "Bus" → "Bus Path"
• Renamed "New" button to "New Folder" in folder dialogs

v0.16.7 (February 2026)

Bank Selection Fix:

• Fixed modal window closing instantly when creating a new folder
• Added validation to block folder selection as bank target

v0.16.6 (February 2026)

Template Bus Routing Fix:

• Fixed template events not displaying their bus paths in preview
• Fixed bus not being auto-detected when template is restored from settings

v0.16.4 – v0.16.5 (January 2026)

Cache Staleness Detection:

• Tool now validates that selected references still exist on disk before importing
• Detects external modifications made in FMOD Studio while tool was idle
• Error messages now display actual names of deleted items

v0.16.2 – v0.16.3 (January 2026)

UI Simplification:

• Removed obsolete Asset Name Pattern field (value-based parsing handles this automatically)
• Removed separator fields (auto-detected from pattern)
• Save and restore Case Format in presets

v0.16.1 (January 2026)

Tag Order Fix:

• Fixed bug where pattern tag order was ignored during event name building
• Tags are now case-insensitive in patterns

v0.16.0 (January 2026)

Dynamic Tag System:

• Value-based parsing: finds prefix/feature values in filenames instead of positions
• $actions tag captures all remaining segments as an array
• No more hardcoded action list, any action name works
• Multi-word feature matching via normalization

Case Format Dropdown:

• Choose event name output format: Title_Case, PascalCase, camelCase, snake_case, UPPER_CASE, lowercase, As-Is
• Separator override syntax: $actions(-), $actions(_), $actions() for custom action separators

v0.15.0 (January 2026)

Scatterer Instrument Option:

• Choose between MultiSound and SoundScatterer instrument types
• Default Instrument Type setting in Settings
• Per-event editing and bulk selection buttons

v0.14.0 (January 2026)

Build Banks After Import:

• Prompt to build banks directly after import without opening FMOD Studio
• Platform selection and build scope options

v0.13.3 (January 2026)

macOS Improvements:

• Scrollable interface with automatic screen size adaptation
• Auto-detection of FMOD Studio executable on macOS
• Cross-platform mousewheel scrolling support