POUNDING
← Gamepad MIDI
Pounding Systems
Documentation

Troubleshooting Guide

This guide helps you solve common issues with Gamepad MIDI.

Gamepad Detection Issues

Gamepad Not Detected

Symptoms:

  • Gamepad visualization shows "No gamepad connected"
  • Controls don't respond
  • Application doesn't recognize controller

Solutions:

1. Check Physical Connection

  • Ensure USB cable is fully plugged in
  • Try a different USB port
  • Try a different USB cable
  • For wireless: Ensure controller is powered on and paired

2. Verify System Recognition

Windows:

  • Open "Devices and Printers" (Control Panel)
  • Look for your gamepad
  • Right-click → "Game controller settings" → Test
  • If not visible, drivers may be needed

macOS:

  • Open "System Information" → Hardware → USB
  • Look for your controller
  • Should appear when connected

Linux:

  • Run: ls /dev/input/js*
  • Your gamepad should appear as /dev/input/js0 or similar
  • Check permissions: ls -l /dev/input/js0

3. Restart Gamepad MIDI

  • Close the application
  • Reconnect the gamepad
  • Launch the application

4. Update Gamepad Firmware (if applicable)

  • PlayStation controllers: Update via PS4/PS5 console
  • Xbox controllers: Update via Xbox Accessories app
  • Check manufacturer's website for firmware updates

Gamepad Connects Then Disconnects

Possible Causes:

  • Unstable USB connection
  • Low battery (wireless)
  • Power management settings
  • Interference (wireless)

Solutions:

USB Cable Issues:

  • Try a different cable
  • Use a shorter cable
  • Connect directly to computer (not through hub)

Wireless Issues:

  • Charge the controller
  • Move closer to Bluetooth receiver
  • Remove sources of interference (other wireless devices)

Power Management:

  • Windows: Device Manager → USB Controllers → Properties → Power Management → Uncheck "Allow computer to turn off this device"
  • macOS: System Preferences → Energy Saver → Disable "Put hard disks to sleep"

Wrong Controller Type Detected

Symptom:

  • Button mappings don't match your controller

Solution:

  • This is normal - SDL3 standardizes button layouts
  • The visual representation is generic
  • Focus on the button positions, not their names
  • Create mappings based on actual button positions

Controls Not Responding

Check:

  1. Is the gamepad connected? (indicator shows in app)
  2. Are you moving/pressing the control enough?
  3. Is the controller in the correct mode? (some have mode switches)
  4. Dead zone issues? Try moving sticks to extremes

Solution:

  • Recalibrate gamepad in system settings
  • Check gamepad works in other applications
  • Try a different gamepad to isolate the issue

MIDI Output Issues

No MIDI Device in Dropdown

Symptom:

  • MIDI device dropdown is empty or only shows "No device"

Solutions:

Windows (After Installation):

  • Restart your computer - Required for Bome MIDI driver
  • Verify BMIDI driver is installed:
    • Device Manager → Software devices → Look for "Bome MIDI"
  • Reinstall if needed

macOS:

  • Virtual MIDI should appear automatically
  • Check Audio MIDI Setup:
    • Applications → Utilities → Audio MIDI Setup
    • Window → Show MIDI Studio
    • Look for "Gamepad MIDI" port

Linux:

  • Check ALSA MIDI ports: aconnect -l
  • Ensure ALSA is running: ps aux | grep alsa
  • Install alsa-utils if needed: sudo apt-get install alsa-utils

MIDI Device Shows But No Output

Symptoms:

  • Device selected in dropdown
  • Controls move in visualization
  • But DAW doesn't receive MIDI

Solutions:

1. Check DAW MIDI Settings

  • Enable "Gamepad MIDI" as input device
  • Some DAWs require explicit enabling of MIDI inputs
  • Restart DAW after enabling

2. Verify MIDI Is Being Sent

  • Use a MIDI monitor application:
    • Windows: MIDI-OX
    • macOS: MIDI Monitor
    • Linux: kmidimon or aseqdump
  • Move gamepad controls
  • Verify MIDI messages appear in monitor

3. Check MIDI Channel

  • Ensure your DAW is listening to the correct MIDI channel
  • Try mapping to Channel 1 (most common default)
  • Some instruments only listen to specific channels

4. Test with Different Software

  • Try a different DAW or MIDI software
  • Isolates whether issue is with Gamepad MIDI or your DAW
  • Virtual MIDI instruments are good for testing

Stuck Notes

Symptom:

  • Note keeps playing after releasing control
  • "Hanging" notes that won't stop

Immediate Fix:

  • Move the control again to send Note Off
  • Or press the button again if using Toggle mode

Permanent Solutions:

1. Check Mapping Configuration

  • Verify note mapping is configured correctly
  • Toggle vs Trigger mode might need adjustment
  • Threshold might be too sensitive

2. Clean Up Stuck Notes

  • Edit and re-save the mapping
  • Application will send Note Off when mappings change
  • Delete and recreate mapping if persistent

3. Send All Notes Off

  • Use CC 123 (All Notes Off) mapping on a button
  • Quick panic button for stuck notes

MIDI Latency Issues

Symptom:

  • Delay between moving control and hearing result

Check Total Latency:

  • Gamepad MIDI: 5-10ms base
  • Smoothing adds: 5-20ms (depending on setting)
  • DAW latency: Varies
  • Total: Usually 20-50ms

Solutions:

Reduce Smoothing:

  • Lower smoothing values in System tab
  • Faster response, potentially more jitter
  • Test 0.70-0.80 for lower latency

DAW Buffer Size:

  • Reduce audio buffer size in DAW
  • Lower = less latency, higher CPU usage
  • Find balance for your system

USB vs Bluetooth:

  • USB is slightly lower latency
  • Bluetooth adds 5-10ms typically
  • Use wired for critical timing

Mapping Issues

Mappings Not Saving

Symptom:

  • Create mappings, close app, mappings are gone

Solutions:

1. Check File Permissions

  • Ensure write access to configuration directory
  • Windows: %APPDATA%\PoundingSystems\Gamepad\
  • macOS: ~/Library/Application Support/PoundingSystems/Gamepad/
  • Linux: ~/.config/PoundingSystems/Gamepad/

2. Disk Space

  • Verify sufficient disk space
  • Mapping files are small, but full disk prevents writing

3. Save Explicitly

  • Use Presets → "Save Current Preset"
  • Export presets as backup

4. Check for Crashes

  • If app crashes before saving, changes are lost
  • Auto-save happens on clean exit

Mapping Behavior Is Wrong

Symptom:

  • CC sends wrong values
  • Note triggers incorrectly
  • Inverted control

Check:

1. Min/Max Values

  • Verify min is less than max (unless intentionally inverted)
  • Check range is appropriate (0-127 for full range)

2. MIDI Channel

  • Ensure channel matches what your instrument expects
  • Channel 1 is most common default

3. Note Mode

  • Toggle vs Trigger - verify correct mode for your use
  • Threshold setting for axis-to-note mappings

4. Multiple Mappings

  • Check if multiple mappings exist on the control
  • Could be sending conflicting data
  • Remove unwanted mappings

Can't Delete or Edit Mapping

Solutions:

1. Click Correct Button

  • Each mapping has Edit and Delete buttons
  • Make sure you're clicking the right mapping's buttons

2. Restart Application

  • Close and reopen Gamepad MIDI
  • UI might be in unexpected state

3. Manual Deletion

  • Close application
  • Edit midi_mappings.json file
  • Remove mapping entry (advanced users only)

Preset Issues

Presets Not Loading

Symptom:

  • Select preset, but mappings don't change

Solutions:

1. Check for Errors

  • Preset file might be corrupted
  • Re-import or recreate the preset

2. Verify Preset Exists

  • Check presets folder
  • Preset file should be valid JSON

3. Restart Application

  • Close and reopen
  • Refresh preset list

Preset Import Fails

Symptom:

  • Error when importing preset file

Solutions:

1. Verify File Format

  • Must be .json file
  • Created by Gamepad MIDI or compatible format

2. Check File Integrity

  • Open in text editor
  • Verify valid JSON syntax
  • No corruption during transfer

3. File Source

  • Ensure preset is from compatible Gamepad MIDI version
  • Older/newer versions might have format changes

Can't Export Preset

Solutions:

1. Check Write Permissions

  • Ensure you can write to selected directory

2. Choose Different Location

  • Try saving to Documents or Desktop

3. Use Different Filename

  • Special characters might cause issues
  • Use simple alphanumeric names

Motion Sensor Issues

Gyroscope Not Working

Check:

1. Controller Support

  • Not all gamepads have gyroscope
  • DualShock 4, DualSense, Switch Pro Controller support it
  • Xbox controllers typically don't have gyroscope

2. Enable Gyroscope

  • Open Gyroscope tab
  • Toggle "Enable Gyroscope" at top
  • Application must have permission to access sensors

3. Create Mappings

  • Gyroscope needs MIDI mappings to send data
  • Add mappings to Gyro X/Y axes

4. Increase Smoothing

  • Gyroscope is noisy - needs high smoothing (0.92+)
  • Too low smoothing = unusable jittery output

Accelerometer Not Working

Same as gyroscope troubleshooting above

Additional:

  • Requires physical movement/shaking
  • Might need more pronounced movement to detect
  • Check smoothing isn't too high (dampening all movement)

Motion Sensors Too Jittery

Solution:

  • Increase smoothing to 0.93-0.98
  • Motion sensors require high smoothing
  • Adjust until jitter is acceptable

Motion Sensors Not Sensitive Enough

Solutions:

1. Lower Smoothing

  • Decrease smoothing value
  • Balance between jitter and responsiveness

2. Adjust Min/Max Range

  • Use wider MIDI value range
  • Min: 0, Max: 127 for full sensitivity

3. Larger Movements

  • Motion sensors require noticeable movement
  • Tilt/shake more dramatically

Performance Issues

Application Freezes or Crashes

Solutions:

1. Update Graphics Drivers

  • Outdated drivers can cause crashes
  • Update from manufacturer website

2. Reduce Active Mappings

  • Many active mappings = more MIDI traffic
  • Disable unused mappings

3. Check System Resources

  • Close unnecessary applications
  • Gamepad MIDI uses minimal CPU, but DAW might not

4. Reinstall Application

  • Clean install might resolve corruption
  • Export presets first

High CPU Usage

Gamepad MIDI Should Use <5% CPU

If higher:

1. Disable Motion Sensors

  • Gyroscope/accelerometer generate continuous data
  • Disable if not needed

2. Reduce Smoothing (counterintuitive)

  • Very high smoothing requires more calculations
  • Try 0.85-0.92 range

3. Check for Background Processes

  • Other software might be the culprit
  • Use Task Manager / Activity Monitor to identify

Battery Drain (Wireless Controllers)

Solutions:

1. Disable Motion Sensors

  • Biggest battery drain
  • Only enable when needed

2. Reduce LED Brightness

  • Configure in system settings (if available)

3. Use Wired Connection

  • USB cable provides power
  • No battery drain

Platform-Specific Issues

Windows Specific

Virtual MIDI Not Available:

  • Restart required after installation
  • Check Device Manager for Bome MIDI driver
  • Reinstall if driver missing

SmartScreen Warning:

  • Click "More info" → "Run anyway"
  • Application is safe, not yet widely recognized

macOS Specific

"App is damaged" Error:

  • Run in Terminal: xattr -cr /Applications/Gamepad\ MIDI.app
  • Gatekeeper quarantine issue

Permission Denied:

  • Grant necessary permissions in System Preferences → Security & Privacy
  • Input Monitoring might be needed

Linux Specific

Gamepad Permission Denied:

  • Add user to input group: sudo usermod -a -G input $USER
  • Log out and back in

No ALSA MIDI:

  • Install: sudo apt-get install alsa-utils
  • Start ALSA: sudo alsa force-reload

JACK Issues:

  • Use a2jmidid to bridge ALSA to JACK
  • Run: a2jmidid -e &

Getting Additional Help

Before Requesting Support

Gather Information:

  1. Operating system and version
  2. Gamepad model
  3. Steps to reproduce the issue
  4. Error messages (if any)
  5. What you've already tried

Check Logs

Application Logs (if available):

  • May contain error details
  • Look in application directory or system logs

Community Resources

Reporting Bugs

Include:

  • Detailed description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • System information
  • Screenshots if relevant

Still Having Issues?

If this guide doesn't solve your problem:

  • Check the FAQ for quick answers
  • Visit the project repository for updates
  • Report bugs via the issue tracker
  • Check for application updates that might fix your issue