Profiles

Profiles save your complete MIDI routing configuration, allowing you to switch between different setups instantly. Perfect for live performances, multi-song set lists, or maintaining separate studio vs live profiles.

What Are Profiles?

A profile is a complete snapshot of your routing state, including:

• Enabled sources - Which MIDI devices are active
• Route configurations - All source→destination routes and their settings
• NeuroScript transforms - Transform code for each route
• Network MIDI settings - Network session enable/policy
• Clock routing - Master clock source and destinations
• Feature flags - AI engine, visualizer, background routing toggles

Switching profiles instantly reconfigures the entire MIDI system to match the saved state.

Use Cases

Live Performance Set Lists

Create a profile per song or set section:

• "Song 1 - Intro" - Piano to pad synth, minimal routing
• "Song 2 - Chorus" - Full routing with transpose and echo effects
• "Song 3 - Outro" - Simplified routing, different clock source

Switch between songs with one tap during performance.

Studio vs Live Profiles

Maintain separate setups for different contexts:

• "Studio" - All devices enabled, Network MIDI on, AI engine enabled
• "Live" - USB-only sources, Network MIDI off, power-optimized

Switch when going from rehearsal to performance without manual reconfiguration.

Multi-Synth Setups

Save different routing configurations for different instruments:

• "Nord Lead" - Routes optimized for Nord keyboard
• "Prophet Rev2" - Routes for Sequential synth with different splits
• "iPad Ensemble" - Network MIDI to multiple iPad synths

Switch when changing primary controller without rebuilding routes.

Testing and Development

Create experimental profiles for trying new ideas:

• "Experiment - Generative" - Test generative MIDI scripts
• "Experiment - Clock Sync" - Test new clock routing approaches
• "Default" - Fall back to known-good configuration

Safely experiment without losing working configurations.

Managing Profiles

Creating a Profile

1. Open Settings (gear icon in top navigation)
2. Scroll to Profiles section
3. Tap "Create New Profile"
4. Enter profile name (e.g., "Live Set A")
5. Tap "Create"

The new profile starts with a copy of your current state - effectively duplicating your current routing. You can then modify it as needed.

Switching Profiles

From Settings:

1. Open Settings → Profiles
2. Tap the Active Profile picker
3. Select desired profile from list
4. Routing system reconfigures immediately

Current state is saved before switching - your changes are never lost.

Deleting a Profile

1. Open Settings → Profiles
2. Select the profile you want to delete (switch to it if needed)
3. Tap "Delete Current Profile" (red button)
4. Confirm deletion

Cannot delete "Default" profile - it always exists as a fallback.

Exporting a Profile

Save a profile as a JSON file for backup or sharing:

1. Open Settings → Profiles
2. Switch to the profile you want to export
3. Tap "Export Current Profile"
4. Choose save location
5. File is saved with .json extension

Export file contains:

• All routing configuration
• NeuroScript source code
• Clock and network settings
• Feature flags
• Timestamps and versioning metadata

Use cases:

• Backup critical profiles to cloud storage
• Share profiles with collaborators or other users
• Version control profiles with git
• Transfer profiles between devices

Importing a Profile

There is no guided import UI yet. For now, import profiles manually:

1. Locate the exported profile JSON file
2. Copy it into Neurode MIDI's Documents directory
3. Rename it to <profile-name>.json if needed
4. Relaunch Neurode MIDI so the profile list refreshes from disk

When a dedicated import UI ships, it should handle discovery and conflict resolution for you.

Default Profile

The "Default" profile is special:

• Always exists - Cannot be deleted
• Fallback - Used when requested profile is unavailable
• First run - Active on initial launch

Default contains:

• Empty routing configuration (no routes)
• Network MIDI disabled
• All features enabled (AI, visualizer, background routing)
• No custom settings

You can modify Default like any other profile - it's just a name, not a protected state.

Profile Storage

Profiles are persisted as JSON files in the app's Documents directory via PersistenceController.

The exact filesystem path depends on the platform and app container location, so prefer the built-in export flow over hand-editing files in place.

Each profile is a single file:

Default.json
Live Set A.json
Studio.json

JSON format is documented but considered internal - use export/import features instead of hand-editing when possible.

Auto-Save Behavior

Profiles save automatically in these cases:

1. When switching profiles - Current state saved before loading new profile
2. On app quit - Current state saved to active profile
3. After edits settle - Routing and profile changes are debounced, then written automatically

You don't need to manually save - profile system handles persistence automatically.

Last-Used Profile

Neurode MIDI remembers your last-used profile and restores it on launch.

Storage: UserDefaults key MidiMatrixRouterLastProfile

If the last-used profile is deleted or unavailable, the system falls back to "Default".

Factory Reset

Destructive operation that deletes all profiles and resets to empty state:

1. Open Settings → Advanced (scroll to bottom)
2. Tap "Factory Reset"
3. Confirm the destructive action

What gets deleted:

• All profile JSON files (including Default)
• Last-used profile preference
• Routing state resets to empty

What is preserved:

• User presets (NeuroScript files)
• App settings (language, interface mode, feature flags)
• Bundled presets and examples

Use this when:

• Starting fresh after major version upgrade
• Troubleshooting profile corruption
• Transferring device to another user

Profile Format

Profiles are JSON files with this structure:

{
  "version": 1,
  "timestamp": "2026-01-19T12:34:56Z",
  "enabledSourceIDs": [123456, 234567],
  "routesBySourceID": {
    "123456": {
      "enabled": true,
      "routes": [
        {
          "destinationID": 345678,
          "transformType": "neuroscript",
          "scriptSource": "keep note where ch == 1",
          "enabled": true
        }
      ]
    }
  },
  "networkMIDI": {
    "enabled": true,
    "policy": 0
  },
  "clockRouting": {
    "masterSourceID": 123456,
    "destinationIDs": [345678]
  },
  "features": {
    "aiEngineEnabled": true,
    "visualizerEnabled": true,
    "backgroundRoutingEnabled": true
  }
}

Fields:

• version - Profile format version (currently 1)
• timestamp - ISO 8601 timestamp of last save
• enabledSourceIDs - Array of MIDI unique IDs for enabled sources
• routesBySourceID - Nested routing configuration per source
• networkMIDI - Network session settings
• clockRouting - Clock source/destination configuration
• features - Feature flag state

Thread Safety

Profile operations run on @MainActor - all state changes happen on the main thread.

Callbacks are synchronous:

• onStateLoaded - System loads profile state into routing engine
• onStateWillSave - System captures current state for persistence
• onProfilesChanged - UI refreshes available profiles list
• onLog - Logs messages for debugging

Performance

• Switch time: <10ms (state swap only, no compilation)
• Save time: 10-50ms depending on routing complexity
• Load time: 10-50ms depending on file size
• Compilation: Happens asynchronously after profile loads (doesn't block switching)

Switching profiles is fast enough for live performance use cases.

Troubleshooting

Profile Won't Switch

Problem: Selecting a profile doesn't change routing configuration.

Solutions:

1. Check profile exists - Profile file may be corrupted or deleted
2. Check logs - Settings → Logs may show file access errors
3. Restart app - Force reload of profile system
4. Factory reset - Last resort, deletes all profiles

Profile Switch Incomplete

Problem: Some settings don't restore after switching.

Solutions:

1. Check feature flags - Some features may be disabled in target profile
2. Verify source availability - Profile may reference disconnected MIDI sources
3. Re-save profile - Switch to profile, modify, switch away to force re-save
4. Check permissions - Ensure app can write to Profiles directory

Lost Profiles After Update

Problem: Profiles disappeared after app update.

Solutions:

1. Check migration - App may have migrated profiles to new format
2. Check backup - Time Machine or iCloud may have profile backups
3. Check old location - Older versions may have used different directory
4. Export frequently - Best practice to export critical profiles as backup

Profile File Corruption

Problem: Profile loads but routing is broken or incomplete.

Solutions:

1. Delete profile - Remove corrupted file from Profiles directory
2. Re-create from scratch - Rebuild routing configuration manually
3. Restore from export - Use previously exported JSON if available
4. Report bug - Profile corruption is a serious issue, please report

Advanced: Profile Callbacks

Developers extending Neurode MIDI can hook into profile operations:

let manager = ProfileManager()

manager.onStateLoaded = { state in
    // Apply loaded state to MIDI system
    applyRoutingState(state)
}

manager.onStateWillSave = {
    // Return current state for persistence
    return captureCurrentRoutingState()
}

manager.onProfilesChanged = {
    // Refresh UI to show new profile list
    refreshProfilePicker()
}

manager.onLog = { message in
    // Log profile operations
    logger.info("\(message)")
}

All callbacks run on @MainActor - safe to update UI directly.

Related Features

• Routing - What profiles save and restore (see Routing Guide)
• NeuroScript - Transform scripts saved in profiles (see NeuroScript Guide)
• Clock Routing - Clock configuration saved in profiles (see Clock Routing)
• Network MIDI - Network settings saved in profiles (see Network MIDI)

Best Practices

Profile Organization

Use descriptive names:

• ❌ "Profile 1", "Test 2"
• ✅ "Live Set - Song 1", "Studio - iPad Ensemble"

Limit profiles to what you actually use:

• Too many profiles → hard to find the right one
• 5-10 profiles is a good target for most users

Export critical profiles:

• Back up to cloud storage (iCloud, Dropbox, etc.)
• Version control with git if you're a developer
• Keep exports before major app updates

Performance vs Flexibility

For live use:

• Pre-create all profiles before the show
• Test switching between profiles during rehearsal
• Verify all sources are available in each profile
• Consider minimal profiles for faster switching

For studio use:

• Use fewer, more comprehensive profiles
• Enable all features (AI, visualizer, network)
• Export frequently during configuration changes

Naming Conventions

For set lists:

01 - Song Name - Intro
02 - Song Name - Verse
03 - Song Name - Chorus

For contexts:

Studio - Full Setup
Live - Minimal Routing
Rehearsal - Test Config

For instruments:

Nord Lead - Split A
Prophet Rev2 - Pad Layer
iPad Ensemble - 4-Way Split

Consistent naming makes profiles easier to find and reduces mistakes during live switching.