BranchesTags

Repository files navigation

MacRiff Logo

🎸 MacRiff

🚀 Download the Latest Release (MacRiff.zip)

Zero-Latency Universal USB-to-Keyboard Bridge for the PDP Riffmaster Guitar (macOS)

MacRiff is a lightweight, high-performance background utility that bridges the PDP Riffmaster Wireless Guitar Dongle directly to keyboard inputs on macOS. It is designed to work seamlessly with rhythm games like Clone Hero, bypassing macOS HID driver limitations to deliver a zero-latency, plug-and-play experience.

🚀 How it Works

Due to how macOS handles custom USB devices, the PDP Riffmaster wireless dongle does not register as a standard game controller out-of-the-box. MacRiff solves this using a two-part system:

  1. USB Driver Bridge (bridge.js & node-usb): Runs with administrative privileges to detach the macOS default HID driver and claim the raw wireless USB interfaces directly using libusb. It polls the guitar state at the highest USB query rate.
  2. C Key Injector (injector): Receives events from the bridge and synthesizes native macOS keyboard events (CGEventPost) to route them directly into the macOS window server, enabling standard game mapping.
  3. Menu Bar GUI App (MacRiff.app): A Swift-based menu bar status app that makes starting, stopping, and viewing logs a single-click experience.

🎮 Key Mappings

The guitar controls are bridged to the following keyboard and OS inputs (designed to match common rhythm game layouts):

Guitar ControlKeyboard / OS InputmacOS Virtual KeycodeNotes
Green FretA0Standard fret (Main & Solo frets work)
Red FretS1Standard fret (Main & Solo frets work)
Yellow FretJ38Standard fret (Main & Solo frets work)
Blue FretK40Standard fret (Main & Solo frets work)
Orange FretL37Standard fret (Main & Solo frets work)
Strum Up↑ (Up Arrow)126Menu navigation & strumming
Strum Down↓ (Down Arrow)125Menu navigation & strumming
D-pad Left← (Left Arrow)123Menu navigation
D-pad Right→ (Right Arrow)124Menu navigation
Start / OptionsEnter36Game pause / Start menu
Select / ShareEscape53Back / Menu
Whammy BarScroll WheelAnalog DeltaBridges analog value to scroll speed for true axis mapping
Tilt SensorSpacebar49Triggers Star Power when guitar is tilted up

Tip

Mapping Analog Whammy & Star Power in Clone Hero:

  • Whammy: In Clone Hero's controller binding screen, click to bind the Whammy axis, and then press down the guitar's whammy bar. The game will detect the scroll wheel pulses and bind it as a relative axis!
  • Star Power: Bind the Star Power action to the Spacebar in Clone Hero. When you tilt your guitar up, the bridge automatically presses Spacebar to trigger Star Power.

📋 Prerequisites

  1. macOS (Supports Apple Silicon M1/M2/M3 and Intel processors natively).
  2. Node.js (v16 or higher).
    • If you don't have Node.js, you can install it easily using Homebrew: 
      brew install node
      Or download it directly from nodejs.org.

📦 Installation & Setup

  1. Download the Release: Download and extract the latest MacRiff.app bundle.
  2. Grant Permissions: Copy MacRiff.app into your /Applications folder (or run it from any folder).
  3. Run the App: Double-click MacRiff.app. A guitar icon 🎸 MacRiff will appear in your menu bar.
  4. Start the Bridge:
    • Click the 🎸 MacRiff menu item and select Start Bridge.
    • You will be prompted with a native macOS password dialog. Enter your system password (or use Touch ID).

    [!NOTE] Administrative privileges are required to claim the raw USB device and detach the default macOS kernel drivers.

    • Once successfully connected, the menu bar icon updates to 🎸 MacRiff (Active).
  5. Toggle Special Inputs: If you want to disable the analog Whammy bar (scroll wheel) and Tilt sensor (Spacebar) inputs, select Disable Whammy & Star Power in the dropdown. The bridge will automatically restart in the background to apply the new setting.

🔒 Security & Accessibility Permissions (CRITICAL STEP)

macOS has strict security controls (TCC) to block background apps from generating keystrokes. You MUST grant Accessibility permissions to both the app and the Node.js runtime for keystrokes to work.

1. Grant Accessibility to MacRiff.app

At startup, MacRiff.app will trigger a macOS system prompt asking for Accessibility permission.

  • Click Open System Settings.
  • Toggle the switch next to MacRiff to ON (blue). (If you missed the prompt, go to: System Settings > Privacy & Security > Accessibility, and add/toggle MacRiff).

2. Grant Accessibility to Node.js (Very Important!)

Because MacRiff.app runs bridge.js using Node.js, the actual keypresses are generated by the node process. You must also grant Accessibility permissions to the node binary.

  • Open System Settings > Privacy & Security > Accessibility.
  • Click the + (plus) button at the bottom of the list.
  • Enter your password to unlock the settings.
  • Find your node binary and add it.
    • Where is my node binary?
      • If you installed Node.js via Homebrew (Apple Silicon): /opt/homebrew/bin/node
      • If you installed Node.js via Homebrew (Intel): /usr/local/bin/node
      • If you used NVM or another installer, open a Terminal and type: 
        which node
        This will print the exact path (e.g., /Users/username/.nvm/versions/node/v20.x.x/bin/node).
    • How to select it in the File Dialog?
      • When the file dialog opens, press Cmd + Shift + G to open the "Go to folder" search bar.
      • Paste the path to your node binary (e.g., /opt/homebrew/bin/node) and press Go (or Enter).
      • Select node and click Open.
      • Ensure it is toggled ON in the Accessibility list.

🛠️ Troubleshooting

❓ The status says "Running" (Active), but no keypresses are registered in Clone Hero or Text Edit!

This is a 100% permission inheritance issue.

  1. Go to System Settings > Privacy & Security > Accessibility.
  2. Locate node and MacRiff in the list.
  3. Toggle them OFF, wait 2 seconds, and toggle them ON again. (macOS sometimes fails to register permissions for binaries that are recompiled or updated).
  4. Restart MacRiff.app.

❓ The status stays "Stopped" or fails to start.

  1. Click View Logs... in the menu dropdown (or open the log file at /tmp/macriff.log).
  2. If you see:
    • PDP Riffmaster Dongle NOT found!: Ensure the wireless USB dongle is plugged into your Mac and the LED light is solid (paired with the guitar).
    • Failed to claim interface: Ensure you entered your sudo password correctly. Another program might be claiming the dongle. Try unplugging and re-plugging the dongle.

💻 Developer Guide: Building from Source

If you want to compile or package MacRiff yourself:

  1. Clone the Repository: 
    git clone https://github.com/cdapayne/MacRiff.git
cd MacRiff
  2. Install Dependencies: 
    npm install
  3. Compile the Key Injector: 
    npm run build
    This compiles injector.c into a native universal binary supporting both Intel and Apple Silicon.
  4. Package the App Bundle: 
    npm run package
    This compiles the Swift menu helper menu.swift as a universal binary, builds the MacRiff.app structure under the root directory, copies dependencies, and signs it.

☕ Support & Donations

If MacRiff helped you get your PDP Riffmaster guitar working on macOS, consider supporting this project! Reverse-engineering USB protocols, compiling universal binaries, and maintaining driver bridges takes time and effort.

If you'd like to buy me a coffee, you can donate via:

Thank you!!!

📄 License

MIT License. Feel free to modify and distribute!

About

Zero-latency universal USB-to-Keyboard bridge connecting the PDP Riffmaster Guitar to macOS.

www.paynebrainapps.com

Topics

bridgecloneclone-herocloneherocontrollercp3dongleguitarguitar-heroherokeyboardkeyboard-bridgepaynebrainpdpriffmasterusb

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
BranchesTags
Repository files navigation
MacRiff Logo
🎸 MacRiff
🚀 Download the Latest Release (MacRiff.zip)
Zero-Latency Universal USB-to-Keyboard Bridge for the PDP Riffmaster Guitar (macOS)
MacRiff is a lightweight, high-performance background utility that bridges the PDP Riffmaster Wireless Guitar Dongle directly to keyboard inputs on macOS. It is designed to work seamlessly with rhythm games like Clone Hero, bypassing macOS HID driver limitations to deliver a zero-latency, plug-and-play experience.
🚀 How it Works
Due to how macOS handles custom USB devices, the PDP Riffmaster wireless dongle does not register as a standard game controller out-of-the-box. MacRiff solves this using a two-part system:
  1. USB Driver Bridge (bridge.js & node-usb): Runs with administrative privileges to detach the macOS default HID driver and claim the raw wireless USB interfaces directly using libusb. It polls the guitar state at the highest USB query rate.
  2. C Key Injector (injector): Receives events from the bridge and synthesizes native macOS keyboard events (CGEventPost) to route them directly into the macOS window server, enabling standard game mapping.
  3. Menu Bar GUI App (MacRiff.app): A Swift-based menu bar status app that makes starting, stopping, and viewing logs a single-click experience.
🎮 Key Mappings
The guitar controls are bridged to the following keyboard and OS inputs (designed to match common rhythm game layouts):
Guitar ControlKeyboard / OS InputmacOS Virtual KeycodeNotes
Green FretA0Standard fret (Main & Solo frets work)
Red FretS1Standard fret (Main & Solo frets work)
Yellow FretJ38Standard fret (Main & Solo frets work)
Blue FretK40Standard fret (Main & Solo frets work)
Orange FretL37Standard fret (Main & Solo frets work)
Strum Up↑ (Up Arrow)126Menu navigation & strumming
Strum Down↓ (Down Arrow)125Menu navigation & strumming
D-pad Left← (Left Arrow)123Menu navigation
D-pad Right→ (Right Arrow)124Menu navigation
Start / OptionsEnter36Game pause / Start menu
Select / ShareEscape53Back / Menu
Whammy BarScroll WheelAnalog DeltaBridges analog value to scroll speed for true axis mapping
Tilt SensorSpacebar49Triggers Star Power when guitar is tilted up
Tip
Mapping Analog Whammy & Star Power in Clone Hero:
  • Whammy: In Clone Hero's controller binding screen, click to bind the Whammy axis, and then press down the guitar's whammy bar. The game will detect the scroll wheel pulses and bind it as a relative axis!
  • Star Power: Bind the Star Power action to the Spacebar in Clone Hero. When you tilt your guitar up, the bridge automatically presses Spacebar to trigger Star Power.
📋 Prerequisites
  1. macOS (Supports Apple Silicon M1/M2/M3 and Intel processors natively).
  2. Node.js (v16 or higher).

    • If you don't have Node.js, you can install it easily using Homebrew:

      brew install node
      
Or download it directly from nodejs.org.
📦 Installation & Setup
  1. Download the Release: Download and extract the latest MacRiff.app bundle.
  2. Grant Permissions: Copy MacRiff.app into your /Applications folder (or run it from any folder).
  3. Run the App: Double-click MacRiff.app. A guitar icon 🎸 MacRiff will appear in your menu bar.
  4. Start the Bridge:

    • Click the 🎸 MacRiff menu item and select Start Bridge.
    • You will be prompted with a native macOS password dialog. Enter your system password (or use Touch ID).
    [!NOTE]
Administrative privileges are required to claim the raw USB device and detach the default macOS kernel drivers.
    • Once successfully connected, the menu bar icon updates to 🎸 MacRiff (Active).
  5. Toggle Special Inputs: If you want to disable the analog Whammy bar (scroll wheel) and Tilt sensor (Spacebar) inputs, select Disable Whammy & Star Power in the dropdown. The bridge will automatically restart in the background to apply the new setting.
🔒 Security & Accessibility Permissions (CRITICAL STEP)
macOS has strict security controls (TCC) to block background apps from generating keystrokes. You MUST grant Accessibility permissions to both the app and the Node.js runtime for keystrokes to work.
1. Grant Accessibility to MacRiff.app
At startup, MacRiff.app will trigger a macOS system prompt asking for Accessibility permission.
  • Click Open System Settings.
  • Toggle the switch next to MacRiff to ON (blue).
(If you missed the prompt, go to: System Settings > Privacy & Security > Accessibility, and add/toggle MacRiff).
2. Grant Accessibility to Node.js (Very Important!)
Because MacRiff.app runs bridge.js using Node.js, the actual keypresses are generated by the node process. You must also grant Accessibility permissions to the node binary.
  • Open System Settings > Privacy & Security > Accessibility.
  • Click the + (plus) button at the bottom of the list.
  • Enter your password to unlock the settings.
  • Find your node binary and add it.

    • Where is my node binary?
      • If you installed Node.js via Homebrew (Apple Silicon): /opt/homebrew/bin/node
      • If you installed Node.js via Homebrew (Intel): /usr/local/bin/node
      • If you used NVM or another installer, open a Terminal and type:

        which node
        
This will print the exact path (e.g., /Users/username/.nvm/versions/node/v20.x.x/bin/node).
    • How to select it in the File Dialog?
      • When the file dialog opens, press Cmd + Shift + G to open the "Go to folder" search bar.
      • Paste the path to your node binary (e.g., /opt/homebrew/bin/node) and press Go (or Enter).
      • Select node and click Open.
      • Ensure it is toggled ON in the Accessibility list.
🛠️ Troubleshooting
❓ The status says "Running" (Active), but no keypresses are registered in Clone Hero or Text Edit!
This is a 100% permission inheritance issue.
  1. Go to System Settings > Privacy & Security > Accessibility.
  2. Locate node and MacRiff in the list.
  3. Toggle them OFF, wait 2 seconds, and toggle them ON again. (macOS sometimes fails to register permissions for binaries that are recompiled or updated).
  4. Restart MacRiff.app.
❓ The status stays "Stopped" or fails to start.
  1. Click View Logs... in the menu dropdown (or open the log file at /tmp/macriff.log).
  2. If you see:

    • PDP Riffmaster Dongle NOT found!: Ensure the wireless USB dongle is plugged into your Mac and the LED light is solid (paired with the guitar).
    • Failed to claim interface: Ensure you entered your sudo password correctly. Another program might be claiming the dongle. Try unplugging and re-plugging the dongle.
💻 Developer Guide: Building from Source
If you want to compile or package MacRiff yourself:
  1. Clone the Repository:

    git clone https://github.com/cdapayne/MacRiff.git
cd MacRiff
  2. Install Dependencies:

    npm install
  3. Compile the Key Injector:

    npm run build
    This compiles injector.c into a native universal binary supporting both Intel and Apple Silicon.
  4. Package the App Bundle:

    npm run package
    This compiles the Swift menu helper menu.swift as a universal binary, builds the MacRiff.app structure under the root directory, copies dependencies, and signs it.
☕ Support & Donations
If MacRiff helped you get your PDP Riffmaster guitar working on macOS, consider supporting this project! Reverse-engineering USB protocols, compiling universal binaries, and maintaining driver bridges takes time and effort.
If you'd like to buy me a coffee, you can donate via:
Thank you!!!
📄 License
MIT License. Feel free to modify and distribute!
About
Zero-latency universal USB-to-Keyboard bridge connecting the PDP Riffmaster Guitar to macOS.
www.paynebrainapps.com
Topics
bridgecloneclone-herocloneherocontrollercp3dongleguitarguitar-heroherokeyboardkeyboard-bridgepaynebrainpdpriffmasterusb
Resources
Readme
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
MacRiff Logo
🎸 MacRiff
🚀 Download the Latest Release (MacRiff.zip)
Zero-Latency Universal USB-to-Keyboard Bridge for the PDP Riffmaster Guitar (macOS)
MacRiff is a lightweight, high-performance background utility that bridges the PDP Riffmaster Wireless Guitar Dongle directly to keyboard inputs on macOS. It is designed to work seamlessly with rhythm games like Clone Hero, bypassing macOS HID driver limitations to deliver a zero-latency, plug-and-play experience.
🚀 How it Works
Due to how macOS handles custom USB devices, the PDP Riffmaster wireless dongle does not register as a standard game controller out-of-the-box. MacRiff solves this using a two-part system:
  1. USB Driver Bridge (bridge.js & node-usb): Runs with administrative privileges to detach the macOS default HID driver and claim the raw wireless USB interfaces directly using libusb. It polls the guitar state at the highest USB query rate.
  2. C Key Injector (injector): Receives events from the bridge and synthesizes native macOS keyboard events (CGEventPost) to route them directly into the macOS window server, enabling standard game mapping.
  3. Menu Bar GUI App (MacRiff.app): A Swift-based menu bar status app that makes starting, stopping, and viewing logs a single-click experience.
🎮 Key Mappings
The guitar controls are bridged to the following keyboard and OS inputs (designed to match common rhythm game layouts):
Guitar ControlKeyboard / OS InputmacOS Virtual KeycodeNotes
Green FretA0Standard fret (Main & Solo frets work)
Red FretS1Standard fret (Main & Solo frets work)
Yellow FretJ38Standard fret (Main & Solo frets work)
Blue FretK40Standard fret (Main & Solo frets work)
Orange FretL37Standard fret (Main & Solo frets work)
Strum Up↑ (Up Arrow)126Menu navigation & strumming
Strum Down↓ (Down Arrow)125Menu navigation & strumming
D-pad Left← (Left Arrow)123Menu navigation
D-pad Right→ (Right Arrow)124Menu navigation
Start / OptionsEnter36Game pause / Start menu
Select / ShareEscape53Back / Menu
Whammy BarScroll WheelAnalog DeltaBridges analog value to scroll speed for true axis mapping
Tilt SensorSpacebar49Triggers Star Power when guitar is tilted up
Tip
Mapping Analog Whammy & Star Power in Clone Hero:
  • Whammy: In Clone Hero's controller binding screen, click to bind the Whammy axis, and then press down the guitar's whammy bar. The game will detect the scroll wheel pulses and bind it as a relative axis!
  • Star Power: Bind the Star Power action to the Spacebar in Clone Hero. When you tilt your guitar up, the bridge automatically presses Spacebar to trigger Star Power.
📋 Prerequisites
  1. macOS (Supports Apple Silicon M1/M2/M3 and Intel processors natively).
  2. Node.js (v16 or higher).

    • If you don't have Node.js, you can install it easily using Homebrew:

      brew install node
      
Or download it directly from nodejs.org.
📦 Installation & Setup
  1. Download the Release: Download and extract the latest MacRiff.app bundle.
  2. Grant Permissions: Copy MacRiff.app into your /Applications folder (or run it from any folder).
  3. Run the App: Double-click MacRiff.app. A guitar icon 🎸 MacRiff will appear in your menu bar.
  4. Start the Bridge:

    • Click the 🎸 MacRiff menu item and select Start Bridge.
    • You will be prompted with a native macOS password dialog. Enter your system password (or use Touch ID).
    [!NOTE]
Administrative privileges are required to claim the raw USB device and detach the default macOS kernel drivers.
    • Once successfully connected, the menu bar icon updates to 🎸 MacRiff (Active).
  5. Toggle Special Inputs: If you want to disable the analog Whammy bar (scroll wheel) and Tilt sensor (Spacebar) inputs, select Disable Whammy & Star Power in the dropdown. The bridge will automatically restart in the background to apply the new setting.
🔒 Security & Accessibility Permissions (CRITICAL STEP)
macOS has strict security controls (TCC) to block background apps from generating keystrokes. You MUST grant Accessibility permissions to both the app and the Node.js runtime for keystrokes to work.
1. Grant Accessibility to MacRiff.app
At startup, MacRiff.app will trigger a macOS system prompt asking for Accessibility permission.
  • Click Open System Settings.
  • Toggle the switch next to MacRiff to ON (blue).
(If you missed the prompt, go to: System Settings > Privacy & Security > Accessibility, and add/toggle MacRiff).
2. Grant Accessibility to Node.js (Very Important!)
Because MacRiff.app runs bridge.js using Node.js, the actual keypresses are generated by the node process. You must also grant Accessibility permissions to the node binary.
  • Open System Settings > Privacy & Security > Accessibility.
  • Click the + (plus) button at the bottom of the list.
  • Enter your password to unlock the settings.
  • Find your node binary and add it.

    • Where is my node binary?
      • If you installed Node.js via Homebrew (Apple Silicon): /opt/homebrew/bin/node
      • If you installed Node.js via Homebrew (Intel): /usr/local/bin/node
      • If you used NVM or another installer, open a Terminal and type:

        which node
        
This will print the exact path (e.g., /Users/username/.nvm/versions/node/v20.x.x/bin/node).
    • How to select it in the File Dialog?
      • When the file dialog opens, press Cmd + Shift + G to open the "Go to folder" search bar.
      • Paste the path to your node binary (e.g., /opt/homebrew/bin/node) and press Go (or Enter).
      • Select node and click Open.
      • Ensure it is toggled ON in the Accessibility list.
🛠️ Troubleshooting
❓ The status says "Running" (Active), but no keypresses are registered in Clone Hero or Text Edit!
This is a 100% permission inheritance issue.
  1. Go to System Settings > Privacy & Security > Accessibility.
  2. Locate node and MacRiff in the list.
  3. Toggle them OFF, wait 2 seconds, and toggle them ON again. (macOS sometimes fails to register permissions for binaries that are recompiled or updated).
  4. Restart MacRiff.app.
❓ The status stays "Stopped" or fails to start.
  1. Click View Logs... in the menu dropdown (or open the log file at /tmp/macriff.log).
  2. If you see:

    • PDP Riffmaster Dongle NOT found!: Ensure the wireless USB dongle is plugged into your Mac and the LED light is solid (paired with the guitar).
    • Failed to claim interface: Ensure you entered your sudo password correctly. Another program might be claiming the dongle. Try unplugging and re-plugging the dongle.
💻 Developer Guide: Building from Source
If you want to compile or package MacRiff yourself:
  1. Clone the Repository:

    git clone https://github.com/cdapayne/MacRiff.git
cd MacRiff
  2. Install Dependencies:

    npm install
  3. Compile the Key Injector:

    npm run build
    This compiles injector.c into a native universal binary supporting both Intel and Apple Silicon.
  4. Package the App Bundle:

    npm run package
    This compiles the Swift menu helper menu.swift as a universal binary, builds the MacRiff.app structure under the root directory, copies dependencies, and signs it.
☕ Support & Donations
If MacRiff helped you get your PDP Riffmaster guitar working on macOS, consider supporting this project! Reverse-engineering USB protocols, compiling universal binaries, and maintaining driver bridges takes time and effort.
If you'd like to buy me a coffee, you can donate via:
Thank you!!!
📄 License
MIT License. Feel free to modify and distribute!
About
Zero-latency universal USB-to-Keyboard bridge connecting the PDP Riffmaster Guitar to macOS.
www.paynebrainapps.com
Topics
bridgecloneclone-herocloneherocontrollercp3dongleguitarguitar-heroherokeyboardkeyboard-bridgepaynebrainpdpriffmasterusb
Resources
Readme
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
MacRiff Logo
🎸 MacRiff
🚀 Download the Latest Release (MacRiff.zip)
Zero-Latency Universal USB-to-Keyboard Bridge for the PDP Riffmaster Guitar (macOS)
MacRiff is a lightweight, high-performance background utility that bridges the PDP Riffmaster Wireless Guitar Dongle directly to keyboard inputs on macOS. It is designed to work seamlessly with rhythm games like Clone Hero, bypassing macOS HID driver limitations to deliver a zero-latency, plug-and-play experience.
🚀 How it Works
Due to how macOS handles custom USB devices, the PDP Riffmaster wireless dongle does not register as a standard game controller out-of-the-box. MacRiff solves this using a two-part system:
  1. USB Driver Bridge (bridge.js & node-usb): Runs with administrative privileges to detach the macOS default HID driver and claim the raw wireless USB interfaces directly using libusb. It polls the guitar state at the highest USB query rate.
  2. C Key Injector (injector): Receives events from the bridge and synthesizes native macOS keyboard events (CGEventPost) to route them directly into the macOS window server, enabling standard game mapping.
  3. Menu Bar GUI App (MacRiff.app): A Swift-based menu bar status app that makes starting, stopping, and viewing logs a single-click experience.
🎮 Key Mappings
The guitar controls are bridged to the following keyboard and OS inputs (designed to match common rhythm game layouts):
Guitar ControlKeyboard / OS InputmacOS Virtual KeycodeNotes
Green FretA0Standard fret (Main & Solo frets work)
Red FretS1Standard fret (Main & Solo frets work)
Yellow FretJ38Standard fret (Main & Solo frets work)
Blue FretK40Standard fret (Main & Solo frets work)
Orange FretL37Standard fret (Main & Solo frets work)
Strum Up↑ (Up Arrow)126Menu navigation & strumming
Strum Down↓ (Down Arrow)125Menu navigation & strumming
D-pad Left← (Left Arrow)123Menu navigation
D-pad Right→ (Right Arrow)124Menu navigation
Start / OptionsEnter36Game pause / Start menu
Select / ShareEscape53Back / Menu
Whammy BarScroll WheelAnalog DeltaBridges analog value to scroll speed for true axis mapping
Tilt SensorSpacebar49Triggers Star Power when guitar is tilted up
Tip
Mapping Analog Whammy & Star Power in Clone Hero:
  • Whammy: In Clone Hero's controller binding screen, click to bind the Whammy axis, and then press down the guitar's whammy bar. The game will detect the scroll wheel pulses and bind it as a relative axis!
  • Star Power: Bind the Star Power action to the Spacebar in Clone Hero. When you tilt your guitar up, the bridge automatically presses Spacebar to trigger Star Power.
📋 Prerequisites
  1. macOS (Supports Apple Silicon M1/M2/M3 and Intel processors natively).
  2. Node.js (v16 or higher).

    • If you don't have Node.js, you can install it easily using Homebrew:

      brew install node
      
Or download it directly from nodejs.org.
📦 Installation & Setup
  1. Download the Release: Download and extract the latest MacRiff.app bundle.
  2. Grant Permissions: Copy MacRiff.app into your /Applications folder (or run it from any folder).
  3. Run the App: Double-click MacRiff.app. A guitar icon 🎸 MacRiff will appear in your menu bar.
  4. Start the Bridge:

    • Click the 🎸 MacRiff menu item and select Start Bridge.
    • You will be prompted with a native macOS password dialog. Enter your system password (or use Touch ID).
    [!NOTE]
Administrative privileges are required to claim the raw USB device and detach the default macOS kernel drivers.
    • Once successfully connected, the menu bar icon updates to 🎸 MacRiff (Active).
  5. Toggle Special Inputs: If you want to disable the analog Whammy bar (scroll wheel) and Tilt sensor (Spacebar) inputs, select Disable Whammy & Star Power in the dropdown. The bridge will automatically restart in the background to apply the new setting.
🔒 Security & Accessibility Permissions (CRITICAL STEP)
macOS has strict security controls (TCC) to block background apps from generating keystrokes. You MUST grant Accessibility permissions to both the app and the Node.js runtime for keystrokes to work.
1. Grant Accessibility to MacRiff.app
At startup, MacRiff.app will trigger a macOS system prompt asking for Accessibility permission.
  • Click Open System Settings.
  • Toggle the switch next to MacRiff to ON (blue).
(If you missed the prompt, go to: System Settings > Privacy & Security > Accessibility, and add/toggle MacRiff).
2. Grant Accessibility to Node.js (Very Important!)
Because MacRiff.app runs bridge.js using Node.js, the actual keypresses are generated by the node process. You must also grant Accessibility permissions to the node binary.
  • Open System Settings > Privacy & Security > Accessibility.
  • Click the + (plus) button at the bottom of the list.
  • Enter your password to unlock the settings.
  • Find your node binary and add it.

    • Where is my node binary?
      • If you installed Node.js via Homebrew (Apple Silicon): /opt/homebrew/bin/node
      • If you installed Node.js via Homebrew (Intel): /usr/local/bin/node
      • If you used NVM or another installer, open a Terminal and type:

        which node
        
This will print the exact path (e.g., /Users/username/.nvm/versions/node/v20.x.x/bin/node).
    • How to select it in the File Dialog?
      • When the file dialog opens, press Cmd + Shift + G to open the "Go to folder" search bar.
      • Paste the path to your node binary (e.g., /opt/homebrew/bin/node) and press Go (or Enter).
      • Select node and click Open.
      • Ensure it is toggled ON in the Accessibility list.
🛠️ Troubleshooting
❓ The status says "Running" (Active), but no keypresses are registered in Clone Hero or Text Edit!
This is a 100% permission inheritance issue.
  1. Go to System Settings > Privacy & Security > Accessibility.
  2. Locate node and MacRiff in the list.
  3. Toggle them OFF, wait 2 seconds, and toggle them ON again. (macOS sometimes fails to register permissions for binaries that are recompiled or updated).
  4. Restart MacRiff.app.
❓ The status stays "Stopped" or fails to start.
  1. Click View Logs... in the menu dropdown (or open the log file at /tmp/macriff.log).
  2. If you see:

    • PDP Riffmaster Dongle NOT found!: Ensure the wireless USB dongle is plugged into your Mac and the LED light is solid (paired with the guitar).
    • Failed to claim interface: Ensure you entered your sudo password correctly. Another program might be claiming the dongle. Try unplugging and re-plugging the dongle.
💻 Developer Guide: Building from Source
If you want to compile or package MacRiff yourself:
  1. Clone the Repository:

    git clone https://github.com/cdapayne/MacRiff.git
cd MacRiff
  2. Install Dependencies:

    npm install
  3. Compile the Key Injector:

    npm run build
    This compiles injector.c into a native universal binary supporting both Intel and Apple Silicon.
  4. Package the App Bundle:

    npm run package
    This compiles the Swift menu helper menu.swift as a universal binary, builds the MacRiff.app structure under the root directory, copies dependencies, and signs it.
☕ Support & Donations
If MacRiff helped you get your PDP Riffmaster guitar working on macOS, consider supporting this project! Reverse-engineering USB protocols, compiling universal binaries, and maintaining driver bridges takes time and effort.
If you'd like to buy me a coffee, you can donate via:
Thank you!!!
📄 License
MIT License. Feel free to modify and distribute!
About
Zero-latency universal USB-to-Keyboard bridge connecting the PDP Riffmaster Guitar to macOS.
www.paynebrainapps.com
Topics
bridgecloneclone-herocloneherocontrollercp3dongleguitarguitar-heroherokeyboardkeyboard-bridgepaynebrainpdpriffmasterusb
Resources
Readme
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
BranchesTags
Repository files navigation
MacRiff Logo
🎸 MacRiff
🚀 Download the Latest Release (MacRiff.zip)
Zero-Latency Universal USB-to-Keyboard Bridge for the PDP Riffmaster Guitar (macOS)
MacRiff is a lightweight, high-performance background utility that bridges the PDP Riffmaster Wireless Guitar Dongle directly to keyboard inputs on macOS. It is designed to work seamlessly with rhythm games like Clone Hero, bypassing macOS HID driver limitations to deliver a zero-latency, plug-and-play experience.
🚀 How it Works
Due to how macOS handles custom USB devices, the PDP Riffmaster wireless dongle does not register as a standard game controller out-of-the-box. MacRiff solves this using a two-part system:
  1. USB Driver Bridge (bridge.js & node-usb): Runs with administrative privileges to detach the macOS default HID driver and claim the raw wireless USB interfaces directly using libusb. It polls the guitar state at the highest USB query rate.
  2. C Key Injector (injector): Receives events from the bridge and synthesizes native macOS keyboard events (CGEventPost) to route them directly into the macOS window server, enabling standard game mapping.
  3. Menu Bar GUI App (MacRiff.app): A Swift-based menu bar status app that makes starting, stopping, and viewing logs a single-click experience.
🎮 Key Mappings
The guitar controls are bridged to the following keyboard and OS inputs (designed to match common rhythm game layouts):
Guitar ControlKeyboard / OS InputmacOS Virtual KeycodeNotes
Green FretA0Standard fret (Main & Solo frets work)
Red FretS1Standard fret (Main & Solo frets work)
Yellow FretJ38Standard fret (Main & Solo frets work)
Blue FretK40Standard fret (Main & Solo frets work)
Orange FretL37Standard fret (Main & Solo frets work)
Strum Up↑ (Up Arrow)126Menu navigation & strumming
Strum Down↓ (Down Arrow)125Menu navigation & strumming
D-pad Left← (Left Arrow)123Menu navigation
D-pad Right→ (Right Arrow)124Menu navigation
Start / OptionsEnter36Game pause / Start menu
Select / ShareEscape53Back / Menu
Whammy BarScroll WheelAnalog DeltaBridges analog value to scroll speed for true axis mapping
Tilt SensorSpacebar49Triggers Star Power when guitar is tilted up
Tip
Mapping Analog Whammy & Star Power in Clone Hero:
  • Whammy: In Clone Hero's controller binding screen, click to bind the Whammy axis, and then press down the guitar's whammy bar. The game will detect the scroll wheel pulses and bind it as a relative axis!
  • Star Power: Bind the Star Power action to the Spacebar in Clone Hero. When you tilt your guitar up, the bridge automatically presses Spacebar to trigger Star Power.
📋 Prerequisites
  1. macOS (Supports Apple Silicon M1/M2/M3 and Intel processors natively).
  2. Node.js (v16 or higher).

    • If you don't have Node.js, you can install it easily using Homebrew:

      brew install node
      
Or download it directly from nodejs.org.
📦 Installation & Setup
  1. Download the Release: Download and extract the latest MacRiff.app bundle.
  2. Grant Permissions: Copy MacRiff.app into your /Applications folder (or run it from any folder).
  3. Run the App: Double-click MacRiff.app. A guitar icon 🎸 MacRiff will appear in your menu bar.
  4. Start the Bridge:

    • Click the 🎸 MacRiff menu item and select Start Bridge.
    • You will be prompted with a native macOS password dialog. Enter your system password (or use Touch ID).
    [!NOTE]
Administrative privileges are required to claim the raw USB device and detach the default macOS kernel drivers.
    • Once successfully connected, the menu bar icon updates to 🎸 MacRiff (Active).
  5. Toggle Special Inputs: If you want to disable the analog Whammy bar (scroll wheel) and Tilt sensor (Spacebar) inputs, select Disable Whammy & Star Power in the dropdown. The bridge will automatically restart in the background to apply the new setting.
🔒 Security & Accessibility Permissions (CRITICAL STEP)
macOS has strict security controls (TCC) to block background apps from generating keystrokes. You MUST grant Accessibility permissions to both the app and the Node.js runtime for keystrokes to work.
1. Grant Accessibility to MacRiff.app
At startup, MacRiff.app will trigger a macOS system prompt asking for Accessibility permission.
  • Click Open System Settings.
  • Toggle the switch next to MacRiff to ON (blue).
(If you missed the prompt, go to: System Settings > Privacy & Security > Accessibility, and add/toggle MacRiff).
2. Grant Accessibility to Node.js (Very Important!)
Because MacRiff.app runs bridge.js using Node.js, the actual keypresses are generated by the node process. You must also grant Accessibility permissions to the node binary.
  • Open System Settings > Privacy & Security > Accessibility.
  • Click the + (plus) button at the bottom of the list.
  • Enter your password to unlock the settings.
  • Find your node binary and add it.

    • Where is my node binary?
      • If you installed Node.js via Homebrew (Apple Silicon): /opt/homebrew/bin/node
      • If you installed Node.js via Homebrew (Intel): /usr/local/bin/node
      • If you used NVM or another installer, open a Terminal and type:

        which node
        
This will print the exact path (e.g., /Users/username/.nvm/versions/node/v20.x.x/bin/node).
    • How to select it in the File Dialog?
      • When the file dialog opens, press Cmd + Shift + G to open the "Go to folder" search bar.
      • Paste the path to your node binary (e.g., /opt/homebrew/bin/node) and press Go (or Enter).
      • Select node and click Open.
      • Ensure it is toggled ON in the Accessibility list.
🛠️ Troubleshooting
❓ The status says "Running" (Active), but no keypresses are registered in Clone Hero or Text Edit!
This is a 100% permission inheritance issue.
  1. Go to System Settings > Privacy & Security > Accessibility.
  2. Locate node and MacRiff in the list.
  3. Toggle them OFF, wait 2 seconds, and toggle them ON again. (macOS sometimes fails to register permissions for binaries that are recompiled or updated).
  4. Restart MacRiff.app.
❓ The status stays "Stopped" or fails to start.
  1. Click View Logs... in the menu dropdown (or open the log file at /tmp/macriff.log).
  2. If you see:

    • PDP Riffmaster Dongle NOT found!: Ensure the wireless USB dongle is plugged into your Mac and the LED light is solid (paired with the guitar).
    • Failed to claim interface: Ensure you entered your sudo password correctly. Another program might be claiming the dongle. Try unplugging and re-plugging the dongle.
💻 Developer Guide: Building from Source
If you want to compile or package MacRiff yourself:
  1. Clone the Repository:

    git clone https://github.com/cdapayne/MacRiff.git
cd MacRiff
  2. Install Dependencies:

    npm install
  3. Compile the Key Injector:

    npm run build
    This compiles injector.c into a native universal binary supporting both Intel and Apple Silicon.
  4. Package the App Bundle:

    npm run package
    This compiles the Swift menu helper menu.swift as a universal binary, builds the MacRiff.app structure under the root directory, copies dependencies, and signs it.
☕ Support & Donations
If MacRiff helped you get your PDP Riffmaster guitar working on macOS, consider supporting this project! Reverse-engineering USB protocols, compiling universal binaries, and maintaining driver bridges takes time and effort.
If you'd like to buy me a coffee, you can donate via:
Thank you!!!
📄 License
MIT License. Feel free to modify and distribute!
About
Zero-latency universal USB-to-Keyboard bridge connecting the PDP Riffmaster Guitar to macOS.
www.paynebrainapps.com
Topics
bridgecloneclone-herocloneherocontrollercp3dongleguitarguitar-heroherokeyboardkeyboard-bridgepaynebrainpdpriffmasterusb
Resources
Readme
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
MacRiff Logo
🎸 MacRiff
🚀 Download the Latest Release (MacRiff.zip)
Zero-Latency Universal USB-to-Keyboard Bridge for the PDP Riffmaster Guitar (macOS)
MacRiff is a lightweight, high-performance background utility that bridges the PDP Riffmaster Wireless Guitar Dongle directly to keyboard inputs on macOS. It is designed to work seamlessly with rhythm games like Clone Hero, bypassing macOS HID driver limitations to deliver a zero-latency, plug-and-play experience.
🚀 How it Works
Due to how macOS handles custom USB devices, the PDP Riffmaster wireless dongle does not register as a standard game controller out-of-the-box. MacRiff solves this using a two-part system:
  1. USB Driver Bridge (bridge.js & node-usb): Runs with administrative privileges to detach the macOS default HID driver and claim the raw wireless USB interfaces directly using libusb. It polls the guitar state at the highest USB query rate.
  2. C Key Injector (injector): Receives events from the bridge and synthesizes native macOS keyboard events (CGEventPost) to route them directly into the macOS window server, enabling standard game mapping.
  3. Menu Bar GUI App (MacRiff.app): A Swift-based menu bar status app that makes starting, stopping, and viewing logs a single-click experience.
🎮 Key Mappings
The guitar controls are bridged to the following keyboard and OS inputs (designed to match common rhythm game layouts):
Guitar ControlKeyboard / OS InputmacOS Virtual KeycodeNotes
Green FretA0Standard fret (Main & Solo frets work)
Red FretS1Standard fret (Main & Solo frets work)
Yellow FretJ38Standard fret (Main & Solo frets work)
Blue FretK40Standard fret (Main & Solo frets work)
Orange FretL37Standard fret (Main & Solo frets work)
Strum Up↑ (Up Arrow)126Menu navigation & strumming
Strum Down↓ (Down Arrow)125Menu navigation & strumming
D-pad Left← (Left Arrow)123Menu navigation
D-pad Right→ (Right Arrow)124Menu navigation
Start / OptionsEnter36Game pause / Start menu
Select / ShareEscape53Back / Menu
Whammy BarScroll WheelAnalog DeltaBridges analog value to scroll speed for true axis mapping
Tilt SensorSpacebar49Triggers Star Power when guitar is tilted up
Tip
Mapping Analog Whammy & Star Power in Clone Hero:
  • Whammy: In Clone Hero's controller binding screen, click to bind the Whammy axis, and then press down the guitar's whammy bar. The game will detect the scroll wheel pulses and bind it as a relative axis!
  • Star Power: Bind the Star Power action to the Spacebar in Clone Hero. When you tilt your guitar up, the bridge automatically presses Spacebar to trigger Star Power.
📋 Prerequisites
  1. macOS (Supports Apple Silicon M1/M2/M3 and Intel processors natively).
  2. Node.js (v16 or higher).

    • If you don't have Node.js, you can install it easily using Homebrew:

      brew install node
      
Or download it directly from nodejs.org.
📦 Installation & Setup
  1. Download the Release: Download and extract the latest MacRiff.app bundle.
  2. Grant Permissions: Copy MacRiff.app into your /Applications folder (or run it from any folder).
  3. Run the App: Double-click MacRiff.app. A guitar icon 🎸 MacRiff will appear in your menu bar.
  4. Start the Bridge:

    • Click the 🎸 MacRiff menu item and select Start Bridge.
    • You will be prompted with a native macOS password dialog. Enter your system password (or use Touch ID).
    [!NOTE]
Administrative privileges are required to claim the raw USB device and detach the default macOS kernel drivers.
    • Once successfully connected, the menu bar icon updates to 🎸 MacRiff (Active).
  5. Toggle Special Inputs: If you want to disable the analog Whammy bar (scroll wheel) and Tilt sensor (Spacebar) inputs, select Disable Whammy & Star Power in the dropdown. The bridge will automatically restart in the background to apply the new setting.
🔒 Security & Accessibility Permissions (CRITICAL STEP)
macOS has strict security controls (TCC) to block background apps from generating keystrokes. You MUST grant Accessibility permissions to both the app and the Node.js runtime for keystrokes to work.
1. Grant Accessibility to MacRiff.app
At startup, MacRiff.app will trigger a macOS system prompt asking for Accessibility permission.
  • Click Open System Settings.
  • Toggle the switch next to MacRiff to ON (blue).
(If you missed the prompt, go to: System Settings > Privacy & Security > Accessibility, and add/toggle MacRiff).
2. Grant Accessibility to Node.js (Very Important!)
Because MacRiff.app runs bridge.js using Node.js, the actual keypresses are generated by the node process. You must also grant Accessibility permissions to the node binary.
  • Open System Settings > Privacy & Security > Accessibility.
  • Click the + (plus) button at the bottom of the list.
  • Enter your password to unlock the settings.
  • Find your node binary and add it.

    • Where is my node binary?
      • If you installed Node.js via Homebrew (Apple Silicon): /opt/homebrew/bin/node
      • If you installed Node.js via Homebrew (Intel): /usr/local/bin/node
      • If you used NVM or another installer, open a Terminal and type:

        which node
        
This will print the exact path (e.g., /Users/username/.nvm/versions/node/v20.x.x/bin/node).
    • How to select it in the File Dialog?
      • When the file dialog opens, press Cmd + Shift + G to open the "Go to folder" search bar.
      • Paste the path to your node binary (e.g., /opt/homebrew/bin/node) and press Go (or Enter).
      • Select node and click Open.
      • Ensure it is toggled ON in the Accessibility list.
🛠️ Troubleshooting
❓ The status says "Running" (Active), but no keypresses are registered in Clone Hero or Text Edit!
This is a 100% permission inheritance issue.
  1. Go to System Settings > Privacy & Security > Accessibility.
  2. Locate node and MacRiff in the list.
  3. Toggle them OFF, wait 2 seconds, and toggle them ON again. (macOS sometimes fails to register permissions for binaries that are recompiled or updated).
  4. Restart MacRiff.app.
❓ The status stays "Stopped" or fails to start.
  1. Click View Logs... in the menu dropdown (or open the log file at /tmp/macriff.log).
  2. If you see:

    • PDP Riffmaster Dongle NOT found!: Ensure the wireless USB dongle is plugged into your Mac and the LED light is solid (paired with the guitar).
    • Failed to claim interface: Ensure you entered your sudo password correctly. Another program might be claiming the dongle. Try unplugging and re-plugging the dongle.
💻 Developer Guide: Building from Source
If you want to compile or package MacRiff yourself:
  1. Clone the Repository:

    git clone https://github.com/cdapayne/MacRiff.git
cd MacRiff
  2. Install Dependencies:

    npm install
  3. Compile the Key Injector:

    npm run build
    This compiles injector.c into a native universal binary supporting both Intel and Apple Silicon.
  4. Package the App Bundle:

    npm run package
    This compiles the Swift menu helper menu.swift as a universal binary, builds the MacRiff.app structure under the root directory, copies dependencies, and signs it.
☕ Support & Donations
If MacRiff helped you get your PDP Riffmaster guitar working on macOS, consider supporting this project! Reverse-engineering USB protocols, compiling universal binaries, and maintaining driver bridges takes time and effort.
If you'd like to buy me a coffee, you can donate via:
Thank you!!!
📄 License
MIT License. Feel free to modify and distribute!
About
Zero-latency universal USB-to-Keyboard bridge connecting the PDP Riffmaster Guitar to macOS.
www.paynebrainapps.com
Topics
bridgecloneclone-herocloneherocontrollercp3dongleguitarguitar-heroherokeyboardkeyboard-bridgepaynebrainpdpriffmasterusb
Resources
Readme
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
MacRiff Logo
🎸 MacRiff
🚀 Download the Latest Release (MacRiff.zip)
Zero-Latency Universal USB-to-Keyboard Bridge for the PDP Riffmaster Guitar (macOS)
MacRiff is a lightweight, high-performance background utility that bridges the PDP Riffmaster Wireless Guitar Dongle directly to keyboard inputs on macOS. It is designed to work seamlessly with rhythm games like Clone Hero, bypassing macOS HID driver limitations to deliver a zero-latency, plug-and-play experience.
🚀 How it Works
Due to how macOS handles custom USB devices, the PDP Riffmaster wireless dongle does not register as a standard game controller out-of-the-box. MacRiff solves this using a two-part system:
  1. USB Driver Bridge (bridge.js & node-usb): Runs with administrative privileges to detach the macOS default HID driver and claim the raw wireless USB interfaces directly using libusb. It polls the guitar state at the highest USB query rate.
  2. C Key Injector (injector): Receives events from the bridge and synthesizes native macOS keyboard events (CGEventPost) to route them directly into the macOS window server, enabling standard game mapping.
  3. Menu Bar GUI App (MacRiff.app): A Swift-based menu bar status app that makes starting, stopping, and viewing logs a single-click experience.
🎮 Key Mappings
The guitar controls are bridged to the following keyboard and OS inputs (designed to match common rhythm game layouts):
Guitar ControlKeyboard / OS InputmacOS Virtual KeycodeNotes
Green FretA0Standard fret (Main & Solo frets work)
Red FretS1Standard fret (Main & Solo frets work)
Yellow FretJ38Standard fret (Main & Solo frets work)
Blue FretK40Standard fret (Main & Solo frets work)
Orange FretL37Standard fret (Main & Solo frets work)
Strum Up↑ (Up Arrow)126Menu navigation & strumming
Strum Down↓ (Down Arrow)125Menu navigation & strumming
D-pad Left← (Left Arrow)123Menu navigation
D-pad Right→ (Right Arrow)124Menu navigation
Start / OptionsEnter36Game pause / Start menu
Select / ShareEscape53Back / Menu
Whammy BarScroll WheelAnalog DeltaBridges analog value to scroll speed for true axis mapping
Tilt SensorSpacebar49Triggers Star Power when guitar is tilted up
Tip
Mapping Analog Whammy & Star Power in Clone Hero:
  • Whammy: In Clone Hero's controller binding screen, click to bind the Whammy axis, and then press down the guitar's whammy bar. The game will detect the scroll wheel pulses and bind it as a relative axis!
  • Star Power: Bind the Star Power action to the Spacebar in Clone Hero. When you tilt your guitar up, the bridge automatically presses Spacebar to trigger Star Power.
📋 Prerequisites
  1. macOS (Supports Apple Silicon M1/M2/M3 and Intel processors natively).
  2. Node.js (v16 or higher).

    • If you don't have Node.js, you can install it easily using Homebrew:

      brew install node
      
Or download it directly from nodejs.org.
📦 Installation & Setup
  1. Download the Release: Download and extract the latest MacRiff.app bundle.
  2. Grant Permissions: Copy MacRiff.app into your /Applications folder (or run it from any folder).
  3. Run the App: Double-click MacRiff.app. A guitar icon 🎸 MacRiff will appear in your menu bar.
  4. Start the Bridge:

    • Click the 🎸 MacRiff menu item and select Start Bridge.
    • You will be prompted with a native macOS password dialog. Enter your system password (or use Touch ID).
    [!NOTE]
Administrative privileges are required to claim the raw USB device and detach the default macOS kernel drivers.
    • Once successfully connected, the menu bar icon updates to 🎸 MacRiff (Active).
  5. Toggle Special Inputs: If you want to disable the analog Whammy bar (scroll wheel) and Tilt sensor (Spacebar) inputs, select Disable Whammy & Star Power in the dropdown. The bridge will automatically restart in the background to apply the new setting.
🔒 Security & Accessibility Permissions (CRITICAL STEP)
macOS has strict security controls (TCC) to block background apps from generating keystrokes. You MUST grant Accessibility permissions to both the app and the Node.js runtime for keystrokes to work.
1. Grant Accessibility to MacRiff.app
At startup, MacRiff.app will trigger a macOS system prompt asking for Accessibility permission.
  • Click Open System Settings.
  • Toggle the switch next to MacRiff to ON (blue).
(If you missed the prompt, go to: System Settings > Privacy & Security > Accessibility, and add/toggle MacRiff).
2. Grant Accessibility to Node.js (Very Important!)
Because MacRiff.app runs bridge.js using Node.js, the actual keypresses are generated by the node process. You must also grant Accessibility permissions to the node binary.
  • Open System Settings > Privacy & Security > Accessibility.
  • Click the + (plus) button at the bottom of the list.
  • Enter your password to unlock the settings.
  • Find your node binary and add it.

    • Where is my node binary?
      • If you installed Node.js via Homebrew (Apple Silicon): /opt/homebrew/bin/node
      • If you installed Node.js via Homebrew (Intel): /usr/local/bin/node
      • If you used NVM or another installer, open a Terminal and type:

        which node
        
This will print the exact path (e.g., /Users/username/.nvm/versions/node/v20.x.x/bin/node).
    • How to select it in the File Dialog?
      • When the file dialog opens, press Cmd + Shift + G to open the "Go to folder" search bar.
      • Paste the path to your node binary (e.g., /opt/homebrew/bin/node) and press Go (or Enter).
      • Select node and click Open.
      • Ensure it is toggled ON in the Accessibility list.
🛠️ Troubleshooting
❓ The status says "Running" (Active), but no keypresses are registered in Clone Hero or Text Edit!
This is a 100% permission inheritance issue.
  1. Go to System Settings > Privacy & Security > Accessibility.
  2. Locate node and MacRiff in the list.
  3. Toggle them OFF, wait 2 seconds, and toggle them ON again. (macOS sometimes fails to register permissions for binaries that are recompiled or updated).
  4. Restart MacRiff.app.
❓ The status stays "Stopped" or fails to start.
  1. Click View Logs... in the menu dropdown (or open the log file at /tmp/macriff.log).
  2. If you see:

    • PDP Riffmaster Dongle NOT found!: Ensure the wireless USB dongle is plugged into your Mac and the LED light is solid (paired with the guitar).
    • Failed to claim interface: Ensure you entered your sudo password correctly. Another program might be claiming the dongle. Try unplugging and re-plugging the dongle.
💻 Developer Guide: Building from Source
If you want to compile or package MacRiff yourself:
  1. Clone the Repository:

    git clone https://github.com/cdapayne/MacRiff.git
cd MacRiff
  2. Install Dependencies:

    npm install
  3. Compile the Key Injector:

    npm run build
    This compiles injector.c into a native universal binary supporting both Intel and Apple Silicon.
  4. Package the App Bundle:

    npm run package
    This compiles the Swift menu helper menu.swift as a universal binary, builds the MacRiff.app structure under the root directory, copies dependencies, and signs it.
☕ Support & Donations
If MacRiff helped you get your PDP Riffmaster guitar working on macOS, consider supporting this project! Reverse-engineering USB protocols, compiling universal binaries, and maintaining driver bridges takes time and effort.
If you'd like to buy me a coffee, you can donate via:
Thank you!!!
📄 License
MIT License. Feel free to modify and distribute!
About
Zero-latency universal USB-to-Keyboard bridge connecting the PDP Riffmaster Guitar to macOS.
www.paynebrainapps.com
Topics
bridgecloneclone-herocloneherocontrollercp3dongleguitarguitar-heroherokeyboardkeyboard-bridgepaynebrainpdpriffmasterusb
Resources
Readme
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
BranchesTags
Repository files navigation
MacRiff Logo
🎸 MacRiff
🚀 Download the Latest Release (MacRiff.zip)
Zero-Latency Universal USB-to-Keyboard Bridge for the PDP Riffmaster Guitar (macOS)
MacRiff is a lightweight, high-performance background utility that bridges the PDP Riffmaster Wireless Guitar Dongle directly to keyboard inputs on macOS. It is designed to work seamlessly with rhythm games like Clone Hero, bypassing macOS HID driver limitations to deliver a zero-latency, plug-and-play experience.
🚀 How it Works
Due to how macOS handles custom USB devices, the PDP Riffmaster wireless dongle does not register as a standard game controller out-of-the-box. MacRiff solves this using a two-part system:
  1. USB Driver Bridge (bridge.js & node-usb): Runs with administrative privileges to detach the macOS default HID driver and claim the raw wireless USB interfaces directly using libusb. It polls the guitar state at the highest USB query rate.
  2. C Key Injector (injector): Receives events from the bridge and synthesizes native macOS keyboard events (CGEventPost) to route them directly into the macOS window server, enabling standard game mapping.
  3. Menu Bar GUI App (MacRiff.app): A Swift-based menu bar status app that makes starting, stopping, and viewing logs a single-click experience.
🎮 Key Mappings
The guitar controls are bridged to the following keyboard and OS inputs (designed to match common rhythm game layouts):
Guitar ControlKeyboard / OS InputmacOS Virtual KeycodeNotes
Green FretA0Standard fret (Main & Solo frets work)
Red FretS1Standard fret (Main & Solo frets work)
Yellow FretJ38Standard fret (Main & Solo frets work)
Blue FretK40Standard fret (Main & Solo frets work)
Orange FretL37Standard fret (Main & Solo frets work)
Strum Up↑ (Up Arrow)126Menu navigation & strumming
Strum Down↓ (Down Arrow)125Menu navigation & strumming
D-pad Left← (Left Arrow)123Menu navigation
D-pad Right→ (Right Arrow)124Menu navigation
Start / OptionsEnter36Game pause / Start menu
Select / ShareEscape53Back / Menu
Whammy BarScroll WheelAnalog DeltaBridges analog value to scroll speed for true axis mapping
Tilt SensorSpacebar49Triggers Star Power when guitar is tilted up
Tip
Mapping Analog Whammy & Star Power in Clone Hero:
  • Whammy: In Clone Hero's controller binding screen, click to bind the Whammy axis, and then press down the guitar's whammy bar. The game will detect the scroll wheel pulses and bind it as a relative axis!
  • Star Power: Bind the Star Power action to the Spacebar in Clone Hero. When you tilt your guitar up, the bridge automatically presses Spacebar to trigger Star Power.
📋 Prerequisites
  1. macOS (Supports Apple Silicon M1/M2/M3 and Intel processors natively).
  2. Node.js (v16 or higher).

    • If you don't have Node.js, you can install it easily using Homebrew:

      brew install node
      
Or download it directly from nodejs.org.
📦 Installation & Setup
  1. Download the Release: Download and extract the latest MacRiff.app bundle.
  2. Grant Permissions: Copy MacRiff.app into your /Applications folder (or run it from any folder).
  3. Run the App: Double-click MacRiff.app. A guitar icon 🎸 MacRiff will appear in your menu bar.
  4. Start the Bridge:

    • Click the 🎸 MacRiff menu item and select Start Bridge.
    • You will be prompted with a native macOS password dialog. Enter your system password (or use Touch ID).
    [!NOTE]
Administrative privileges are required to claim the raw USB device and detach the default macOS kernel drivers.
    • Once successfully connected, the menu bar icon updates to 🎸 MacRiff (Active).
  5. Toggle Special Inputs: If you want to disable the analog Whammy bar (scroll wheel) and Tilt sensor (Spacebar) inputs, select Disable Whammy & Star Power in the dropdown. The bridge will automatically restart in the background to apply the new setting.
🔒 Security & Accessibility Permissions (CRITICAL STEP)
macOS has strict security controls (TCC) to block background apps from generating keystrokes. You MUST grant Accessibility permissions to both the app and the Node.js runtime for keystrokes to work.
1. Grant Accessibility to MacRiff.app
At startup, MacRiff.app will trigger a macOS system prompt asking for Accessibility permission.
  • Click Open System Settings.
  • Toggle the switch next to MacRiff to ON (blue).
(If you missed the prompt, go to: System Settings > Privacy & Security > Accessibility, and add/toggle MacRiff).
2. Grant Accessibility to Node.js (Very Important!)
Because MacRiff.app runs bridge.js using Node.js, the actual keypresses are generated by the node process. You must also grant Accessibility permissions to the node binary.
  • Open System Settings > Privacy & Security > Accessibility.
  • Click the + (plus) button at the bottom of the list.
  • Enter your password to unlock the settings.
  • Find your node binary and add it.

    • Where is my node binary?
      • If you installed Node.js via Homebrew (Apple Silicon): /opt/homebrew/bin/node
      • If you installed Node.js via Homebrew (Intel): /usr/local/bin/node
      • If you used NVM or another installer, open a Terminal and type:

        which node
        
This will print the exact path (e.g., /Users/username/.nvm/versions/node/v20.x.x/bin/node).
    • How to select it in the File Dialog?
      • When the file dialog opens, press Cmd + Shift + G to open the "Go to folder" search bar.
      • Paste the path to your node binary (e.g., /opt/homebrew/bin/node) and press Go (or Enter).
      • Select node and click Open.
      • Ensure it is toggled ON in the Accessibility list.
🛠️ Troubleshooting
❓ The status says "Running" (Active), but no keypresses are registered in Clone Hero or Text Edit!
This is a 100% permission inheritance issue.
  1. Go to System Settings > Privacy & Security > Accessibility.
  2. Locate node and MacRiff in the list.
  3. Toggle them OFF, wait 2 seconds, and toggle them ON again. (macOS sometimes fails to register permissions for binaries that are recompiled or updated).
  4. Restart MacRiff.app.
❓ The status stays "Stopped" or fails to start.
  1. Click View Logs... in the menu dropdown (or open the log file at /tmp/macriff.log).
  2. If you see:

    • PDP Riffmaster Dongle NOT found!: Ensure the wireless USB dongle is plugged into your Mac and the LED light is solid (paired with the guitar).
    • Failed to claim interface: Ensure you entered your sudo password correctly. Another program might be claiming the dongle. Try unplugging and re-plugging the dongle.
💻 Developer Guide: Building from Source
If you want to compile or package MacRiff yourself:
  1. Clone the Repository:

    git clone https://github.com/cdapayne/MacRiff.git
cd MacRiff
  2. Install Dependencies:

    npm install
  3. Compile the Key Injector:

    npm run build
    This compiles injector.c into a native universal binary supporting both Intel and Apple Silicon.
  4. Package the App Bundle:

    npm run package
    This compiles the Swift menu helper menu.swift as a universal binary, builds the MacRiff.app structure under the root directory, copies dependencies, and signs it.
☕ Support & Donations
If MacRiff helped you get your PDP Riffmaster guitar working on macOS, consider supporting this project! Reverse-engineering USB protocols, compiling universal binaries, and maintaining driver bridges takes time and effort.
If you'd like to buy me a coffee, you can donate via:
Thank you!!!
📄 License
MIT License. Feel free to modify and distribute!
About
Zero-latency universal USB-to-Keyboard bridge connecting the PDP Riffmaster Guitar to macOS.
www.paynebrainapps.com
Topics
bridgecloneclone-herocloneherocontrollercp3dongleguitarguitar-heroherokeyboardkeyboard-bridgepaynebrainpdpriffmasterusb
Resources
Readme
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages