Platform-Specific Setup

Neurode MIDI works seamlessly on both macOS and iOS/iPadOS, but each platform has unique features and requirements. This guide covers platform-specific setup steps and best practices.

Distribution note: Public App Store distribution is not live yet. Use the build channel you were given, or build locally from source when working from this repository.

macOS Setup

System Requirements

• macOS 15.0 (Sequoia) or later
• Apple Silicon (M1/M2/M3) or Intel (x86_64) Macs
• USB MIDI interface (optional, for external devices)
• IAC Driver (for DAW integration, see below)

First Launch

1. Obtain a build of Neurode MIDI:
   • Build locally from source (make app-macos or Xcode)
   • Or use a signed/internal macOS build from the release channel you were given
2. Open the app - it may ask for permissions
3. If macOS warns about verification, use Privacy & Security → Open Anyway for local or unsigned preview builds
4. Grant MIDI access when prompted (required for device detection)

Permissions required:

• ✅ MIDI: Access CoreMIDI for device detection
• ✅ Network (optional): Enable Network MIDI (Settings → Connectivity)

Setting Up IAC Driver (DAW Integration)

The IAC Driver creates virtual MIDI ports for routing between apps (e.g., Logic Pro ↔ Neurode MIDI ↔ External Synth).

Enabling IAC Driver

1. Open Audio MIDI Setup (/Applications/Utilities/Audio MIDI Setup.app)
2. Window → Show MIDI Studio (or press Cmd+2)
3. Double-click IAC Driver icon
4. ✅ Check "Device is online"
5. Click + to add ports (recommend at least 2: "Bus 1", "Bus 2")
6. Apply and close

IAC Driver creates:

• IAC Driver Bus 1 - Virtual MIDI port (source + destination)
• IAC Driver Bus 2 - Second virtual port (for multi-app routing)

Using IAC Driver with Neurode MIDI

Routing DAW → Neurode MIDI → Hardware Synth:

1. In your DAW (Logic Pro, Ableton Live, etc.):

   • Create MIDI track
   • Set MIDI Out to IAC Driver Bus 1
   • Play notes in DAW

2. In Neurode MIDI:

   • Source: IAC Driver Bus 1 (appears automatically)
   • Destination: Your hardware synth (USB MIDI interface)
   • Create route between them

3. Result: DAW notes → Neurode MIDI → Hardware synth

Routing Hardware → Neurode MIDI → DAW:

1. In Neurode MIDI:

   • Source: Your MIDI keyboard (USB)
   • Destination: IAC Driver Bus 1
   • Add transform if desired (transpose, filter, etc.)

2. In your DAW:

   • Create MIDI track
   • Enable MIDI In from IAC Driver Bus 1
   • Arm track for recording

3. Result: Keyboard → Neurode MIDI (with transforms) → DAW

Drag-and-Drop Presets (macOS)

macOS supports drag-and-drop for .ns (NeuroScript) and .nssigned (signed preset) files:

1. Locate preset file in Finder
2. Drag file onto Neurode MIDI window
3. Drop on route editor - Script loads automatically
4. Or drop on Presets folder - Preset added to library

Revealing Presets Folder:

1. Open Presets Browser
2. Click "Open Presets Folder" (folder icon in toolbar)
3. Finder opens to ~/Library/Application Support/NeurodeMIDI/Presets/

Adding presets manually:

# Reveal hidden Library folder
open ~/Library

# Navigate to Presets
cd ~/Library/Application\ Support/NeurodeMIDI/Presets/

# Copy preset files here
cp ~/Downloads/my-preset.ns .

Keyboard Shortcuts (macOS)

Neurode MIDI currently defines a small set of app-specific macOS shortcuts:

Shortcut	Action
Cmd+Shift+R	Refresh MIDI devices
Cmd+Shift+.	Panic (All Notes Off)
Cmd+?	Open Help

Multi-Window Support

macOS supports multiple windows for advanced workflows:

1. Window → New Window
2. Drag tabs to create separate windows
3. Different views per window (for example, Routing + Statistics or Routing + Event Visualizer)

Use cases:

• Dual monitors: Routing on main screen, Statistics or Event Visualizer on the second screen
• Live performance: Minimal control window on stage, full monitoring backstage

Troubleshooting macOS Issues

"Neurode MIDI cannot be opened because the developer cannot be verified":

1. System Settings → Privacy & Security
2. Scroll to Security section
3. Click "Open Anyway" next to Neurode MIDI warning
4. Relaunch the app

Devices not appearing:

1. Open Audio MIDI Setup
2. Window → Show MIDI Studio
3. Verify device appears in MIDI Studio
4. Refresh devices in Neurode MIDI (Cmd+Shift+R)

Permissions denied:

1. System Settings → Privacy & Security → MIDI Devices
2. ✅ Enable Neurode MIDI
3. Restart app to apply changes

---

iOS/iPadOS Setup

System Requirements

• iOS 18.0 or iPadOS 18.0 or later
• iPhone 12 or newer (iPhone 13+ recommended for performance)
• iPad Pro, iPad Air, or iPad mini (any model supporting iOS 18+)
• USB-C or Lightning port (depending on device)
• Camera Adapter (for USB MIDI devices, see below)

First Launch

1. Install Neurode MIDI from the build channel you were given:
   • Xcode for local development
   • TestFlight or another internal distribution channel when provided
2. Open the app
3. Grant permissions when prompted:
   • ✅ Local Network (for Network MIDI discovery)
   • ✅ Bluetooth (for Bluetooth MIDI devices)

USB MIDI on iOS (Camera Adapter Required)

iOS does not support USB MIDI natively - you need an adapter.

Required Hardware

For Lightning devices (iPhone 14 and earlier, older iPads):

• Apple Lightning to USB Camera Adapter (Model A1440)
• Or Lightning to USB3 Camera Adapter (Model MK0W2AM/A, supports charging + MIDI)

For USB-C devices (iPhone 15+, iPad Pro 2018+):

• Apple USB-C to USB Adapter (Model MJ1M2AM/A)
• Or USB-C hub with USB-A ports (must be USB 2.0/3.0 compatible)

Connecting USB MIDI Devices

1. Plug Camera Adapter into iPhone/iPad
2. Plug USB MIDI device into adapter (keyboard, interface, etc.)
3. Wait 2-3 seconds for device detection
4. Open Neurode MIDI - Device appears in Sources list

Power requirements:

• Class-compliant devices (most keyboards): No external power needed
• Bus-powered devices (some interfaces): May require powered USB hub
• Lightning to USB3 Camera Adapter: Allows charging while using MIDI

Troubleshooting USB MIDI:

Problem	Solution
Device not appearing	Unplug and replug adapter, wait 5 seconds
"Accessory not supported"	Use official Apple adapter, check device compatibility
Device powers off	Use powered USB hub or Lightning to USB3 adapter with charging
Intermittent connection	Check cable quality, try different USB port on hub

Bluetooth MIDI

iOS supports Bluetooth MIDI natively - no adapter needed!

Pairing Bluetooth MIDI Devices

1. Put device in pairing mode (see device manual)
2. Open Neurode MIDI → Settings → Connectivity
3. Tap "Bluetooth MIDI"
4. Select device from discovered list
5. Wait for "Connected" status
6. Device appears in Sources list automatically

Supported devices:

• MIDI keyboards with Bluetooth (Korg, Roland, Yamaha, etc.)
• Bluetooth MIDI adapters (Yamaha MD-BT01, CME WIDI, etc.)
• iOS/Mac running CoreMIDI Bluetooth session
• Android devices with Bluetooth MIDI apps

Bluetooth MIDI latency:

• Expected: 10-30ms (vs <1ms for USB)
• Best case: 8-12ms (close proximity, good signal)
• Worst case: 50-100ms (distance, interference, multiple devices)

Tips for low latency:

• Stay within 3 meters of iOS device
• Minimize Bluetooth interference (turn off nearby Wi-Fi 2.4GHz)
• Use Bluetooth 5.0+ devices when possible
• Disable other Bluetooth accessories during performance

Network MIDI (Wi-Fi)

Connect iOS to macOS/Windows over Wi-Fi without cables.

Enabling Network MIDI on iOS

1. Open Neurode MIDI → Settings → Connectivity
2. Toggle "Enable Network Session" ON
3. Choose network policy:
   • Anyone - Open network (home studio)
   • Contacts Only - Paired devices only
   • No One - Disabled

Connecting to macOS

On macOS:

1. Open Audio MIDI Setup
2. Window → Show MIDI Network Setup
3. Enable network session
4. Look for your iPhone/iPad in Directory
5. Click Connect

On iOS (Neurode MIDI):

1. Source appears automatically (macOS network MIDI)
2. Create routes as normal

Troubleshooting Network MIDI:

• Same Wi-Fi network: Both devices must be on same SSID
• Router firewall: Check UDP port 5004 is allowed
• VPN/Proxy: Disable VPNs that block local network discovery
• Airplane Mode: Disable airplane mode (blocks Wi-Fi)

Files App Integration

Access presets via Files app:

1. Open Files app on iOS
2. Navigate to On My iPhone/iPad → Neurode MIDI → Presets
3. Copy .ns files here from cloud storage or AirDrop
4. Presets appear in Presets Browser automatically

Importing presets:

1. Save .ns file from email/web/messages
2. Tap file → Share → Save to Files
3. Choose Neurode MIDI → Presets folder
4. Open Neurode MIDI and refresh Presets Browser

Share Sheet Integration

Share presets from Neurode MIDI:

1. Open Presets Browser
2. Long-press preset row
3. Tap "Share"
4. Choose destination (AirDrop, Messages, Mail, Files, etc.)

Shared format: .ns plain text file (editable, shareable)

Split View & Slide Over (iPad)

iPad supports multitasking for simultaneous apps:

Split View (side-by-side):

1. Open Neurode MIDI
2. Swipe up from bottom to reveal Dock
3. Drag another app (e.g., GarageBand) to left or right edge
4. Both apps run simultaneously

Use case: Monitor MIDI routing in Neurode MIDI while playing in DAW

Slide Over (floating window):

1. Swipe up from bottom to reveal Dock
2. Drag app to middle of screen
3. Floating window appears over Neurode MIDI

Use case: Quick access to MIDI monitor while working in another app

External Display Support (iPad)

iPad supports external displays via USB-C or AirPlay:

1. Connect display via USB-C (or AirPlay to Apple TV)
2. Open Neurode MIDI
3. Routing matrix appears on external display (mirrored or extended)

Stage Manager (iPadOS 16+):

• Neurode MIDI appears as window on external display
• Resize and position freely
• Run multiple MIDI apps side-by-side

Apple Pencil Support (iPad)

Use Apple Pencil for precise editing:

• Tap routes with Pencil (more accurate than finger)
• Drag connections with Pencil (smooth gestures)
• Edit NeuroScript with Pencil (handwriting recognition not supported, but can tap/select)

Scribble (iPadOS 14+):

• Write in text fields with Apple Pencil
• Handwriting converts to typed text
• Useful for naming routes and profiles

Dark Mode

iOS respects system Dark Mode:

1. Settings (iOS system) → Display & Brightness
2. Choose Dark or Automatic
3. Neurode MIDI adapts immediately

Or override in app:

1. Neurode MIDI → Settings → Appearance
2. Choose Light, Dark, or System

Troubleshooting iOS Issues

App crashes on launch:

1. Force quit (swipe up in App Switcher)
2. Relaunch app
3. If persists: Delete and reinstall from the same build channel (Xcode, TestFlight, or internal distribution)

MIDI messages delayed:

1. Close background apps (free up CPU)
2. Disable Low Power Mode (Settings → Battery)
3. Check buffer size (Neurode MIDI → Settings → Performance)

Bluetooth MIDI won't pair:

1. Turn Bluetooth off and on (Settings → Bluetooth)
2. Forget device and re-pair
3. Restart iOS device
4. Update device firmware (check manufacturer website)

Network MIDI not appearing:

1. Check same Wi-Fi network (Settings → Wi-Fi)
2. Disable VPN (Settings → VPN)
3. Restart router (unplug 30 seconds, replug)
4. Check firewall settings (on Mac/PC)

---

Platform Comparison

Feature	macOS	iOS/iPadOS
USB MIDI	✅ Native (plug and play)	⚠️ Requires Camera Adapter
Bluetooth MIDI	✅ Native	✅ Native
Network MIDI	✅ Native	✅ Native
IAC Driver	✅ Built-in virtual MIDI	❌ Not available (use Network MIDI)
Drag-and-Drop	✅ Presets, profiles	❌ Use Files app instead
Multi-Window	✅ Full support	✅ Split View / Slide Over (iPad only)
Keyboard Shortcuts	✅ Full keyboard support	⚠️ Limited (iPad with keyboard)
Menu Commands	✅ MIDI + Help commands in the macOS menu bar	❌ N/A
External Display	✅ Multi-monitor	✅ iPad only (mirrored or extended)
File System	✅ Full Finder access	⚠️ Sandboxed (Files app only)
Background Routing	✅ Always (if running)	✅ With Background Audio enabled

Cross-Platform Workflows

Scenario 1: Studio (macOS) + Live (iOS)

Setup:

1. Studio setup (macOS):

   • Complex routing with NeuroScript transforms
   • Multiple DAWs, soft synths, hardware
   • Export profile as JSON

2. Live setup (iOS):

   • Import profile from iCloud/AirDrop
   • Simplified routing (fewer devices)
   • Battery-optimized (disable visualizer, AI)

Workflow:

• Rehearse on macOS with full studio rig
• Export profile for iOS
• Simplify routes for live performance (remove studio-only devices)
• Perform on iOS with iPad + USB MIDI keyboard

Scenario 2: Jamming with Network MIDI

Setup:

1. Mac: Running DAW (Logic Pro, Ableton Live)
2. iPad: Running Neurode MIDI + hardware synth
3. Network MIDI: Connect Mac ↔ iPad over Wi-Fi

Workflow:

1. Enable Network MIDI on both Mac and iPad
2. On Mac: DAW outputs to Network MIDI session
3. On iPad: Neurode MIDI receives from Network MIDI
4. Neurode MIDI routes to hardware synth via USB
5. Result: DAW (Mac) → Network MIDI → Neurode MIDI (iPad) → Hardware Synth

Latency: 10-20ms typical (acceptable for jamming, not for tight sequencing)

Scenario 3: Preset Development & Sharing

Develop on macOS (easier file management):

1. Write .ns presets in text editor (VS Code, Xcode, etc.)
2. Test in Neurode MIDI (drag-and-drop to route editor)
3. Refine and iterate
4. Save to Presets folder

Share to iOS:

1. AirDrop preset files from Mac to iOS
2. Or upload to iCloud Drive and download on iOS
3. Copy to Presets folder via Files app
4. Presets appear in Presets Browser on iOS

---

Platform-Specific Best Practices

macOS Best Practices

• Use IAC Driver for DAW integration (lowest latency)
• Use the MIDI menu commands for quick refresh and panic actions
• Organize presets in subfolders (Finder makes this easy)
• Use keyboard shortcuts for fast navigation
• Multi-window layout for dual-monitor setups

iOS/iPadOS Best Practices

• Always carry Lightning/USB-C adapter for unexpected USB MIDI needs
• Test Bluetooth latency before live performance (use USB if critical)
• Disable Low Power Mode during performance (prevents CPU throttling)
• Close background apps to free CPU for MIDI processing
• Use Split View (iPad) to monitor MIDI while playing in DAW
• Keep presets in iCloud for sync across devices
• Export profiles frequently as backup (Files app → iCloud Drive)

---

Related Topics

• Network MIDI - Detailed Wi-Fi MIDI setup
• Bluetooth MIDI - BLE MIDI pairing and troubleshooting
• Profiles - Cross-platform profile management
• Presets Browser - Managing presets across platforms