Harmonix Guitar Driver for Mac Apple Silicon (arm64)

This project creates a user-space driver for the Harmonix Guitar for Xbox 360 on Apple Silicon Macs.

Current Implementation

A C program using libusb to read USB data from the guitar and map button presses to keyboard key events using CoreGraphics.

Button Mappings

• Green (main): A
• Red (main): S
• Yellow (main): W
• Blue (main): D
• Orange (main): E
• Green (solo): Q
• Red (solo): R
• Yellow (solo): T
• Blue (solo): Y
• Orange (solo): U
• Strum Up: Up Arrow
• Strum Down: Down Arrow
• D-Pad Left: Left Arrow
• D-Pad Right: Right Arrow
• Start: Return
• Back: Escape
• XBOX: F1
• Whammy (Up/Down): ;

Building

Use the provided Makefile:

make          # Build both executables
make read_guitar  # Build only the driver (bin/HarmonixGuitar, src/harmonix_guitar_driver.c)
make log_guitar   # Build only the logger
make package   # Build and package into self-contained app + zip
make clean    # Clean binaries

The executables will be placed in the bin/ directory.

Usage

Logger

Run make log_guitar to build, then bin/log_guitar to run.

Output format: Buttons1(hex) Buttons2(hex) LT RT LX LY RX RY

Driver

Run make read_guitar to build, then bin/HarmonixGuitar to start the keyboard simulation driver.

Important: The driver needs accessibility permissions to simulate keyboard input. The main executable now lives at Contents/MacOS/HarmonixGuitar, so you can add the .app itself to Accessibility (no digging into Resources/bin).

To grant permissions:

1. Move Harmonix Guitar Launcher.app to /Applications (don’t move it after granting).
2. Double-click the app once; when prompted, click “Open System Settings”.
3. In System Settings > Privacy & Security > Accessibility, make sure Harmonix Guitar Launcher.app is listed and checked.
4. If the prompt doesn’t appear, you can still add the .app manually via the + button and selecting it in /Applications.

Test permissions: Open TextEdit, run the app, press a guitar button — if letters appear, permissions are granted.

Launching through terminal

If YARG is in /Applications/YARC Launcher.app, you can just run ./bin/HarmonixGuitar.

The program checks for guitar connection, prompts you to press the green fret (it will detect the press automatically), waits for YARG to start, launches the driver, monitors YARG, and stops the driver when YARG exits.

GUI App

Double-click Harmonix Guitar Launcher.app to launch the driver with YARG. The app runs in the background and shows a startup notification, then dialog boxes for setup. Place it on your desktop or dock for easy access.

Limitations

• Analog inputs (whammy, tilt) are mapped as buttons.
• Only works with applications that accept keyboard input.
• For full game controller support, a virtual HID device would be needed.

Next Steps

• Implement virtual HID device using IOHIDUserDevice.

Distribution

Run make package to create HarmonixGuitarLauncher.zip, a compressed archive containing the self-contained Harmonix Guitar Launcher.app. Distribute this zip file to users.

The .app is a standard macOS application bundle that users can extract and double-click to run.