Mac Media Keys Forwarder

A macOS menu bar app that forwards media keys (play/pause, next, previous) to a specific media application of your choice.

This is a modern replacement for Mac Media Key Forwarder, designed to work with macOS Sequoia (15.x), Tahoe (26.x), and later.

Why?

I find macOS’s media key handling behavior mildly infuriating. When I hit play/pause on my keyboard I just want it to toggle playback in whatever music streaming app I'm listening to. I never want it to launch Apple Music. I never want it to pause the video I'm watching. Just pause or resume music. That's it. Nothing else.

But that's not what happens, and while I understand why it does what it does, I'm frequently surprised and annoyed by it. And that's what this app tries to fix. Bind the play/pause and prev/next keys to a specific app of my choosing.

Full disclosure: I am a professional developer but I am not a macOS/Swift/Obj-C developer. This is 100% vibe-coded except where contributions from others are involved. (Thanks, @polderleo!)

Features

• Intercepts media keys and forwards them to your chosen app
• Prevents Apple Music from hijacking your media keys
• Built-in support for Spotify and Apple Music
• Add any custom media app via "Configure Apps..."
• Menu bar icon for easy access
• Remembers your selected app between launches
• Checks for updates and installs them in place from the About window

Download

Download the latest release from the Releases page.

Installation

Homebrew

brew install --cask rayhatfield/mac-media-keys/mac-media-keys

To update later:

brew upgrade --cask mac-media-keys

Manual

1. Download MacMediaKeys.zip from the latest release
2. Unzip and drag MacMediaKeys.app to your Applications folder
3. Grant Accessibility permission when prompted:
   • Click "Open System Settings" or go to System Settings → Privacy & Security → Accessibility
   • Enable MacMediaKeys
4. Restart the app after granting permission

The app also checks for new releases automatically and will offer to install the update for you — no re-download or re-drag needed (this can be disabled in Settings). You can also check on demand from About MacMediaKeys.

Usage

1. Click the music note (♪) icon in the menu bar
2. Select your target media app from the list
3. Press media keys on your keyboard - they will be forwarded to the selected app

Adding Custom Apps

1. Click the menu bar icon
2. Select "Configure Apps..."
3. Click "Add App..." and select any .app file
4. The app will now appear in your target list

Requirements

• macOS 13.0 (Ventura) or later
• Accessibility permission (required to intercept media keys)

Building from Source

# Clone the repository
git clone https://github.com/rayhatfield/mac-media-keys.git
cd mac-media-keys

# Build with Xcode
xcodebuild -scheme MacMediaKeys -configuration Release build

# The app will be in:
# ~/Library/Developer/Xcode/DerivedData/MacMediaKeys-*/Build/Products/Release/MacMediaKeys.app

Installing a Debug build

If you want to install and run a local debug build instead of the release zip:

xcodebuild -scheme MacMediaKeys -configuration Debug build

Then install the built app:

1. Open ~/Library/Developer/Xcode/DerivedData/
2. Find MacMediaKeys-*/Build/Products/Debug/MacMediaKeys.app
3. Drag MacMediaKeys.app to your Applications folder
4. Launch it and grant Accessibility permission in System Settings → Privacy & Security → Accessibility

If you already have a release build installed, replace it with the Debug build so macOS is launching the version you expect.

How It Works

The app uses CGEventTap to intercept system-defined media key events before they reach other applications. When a media key is pressed, the app sends the corresponding command to your selected media player via AppleScript (for supported apps) or direct keystroke injection (for other apps).

Key technical details:

• Taps at the HID level (cghidEventTap), ahead of the system's own media-key routing. A session-level tap sits behind rcd/mediaremoted and behind apps that register global media-key shortcuts (many Electron players do), so one keypress could reach both that app and this one — toggling playback twice. Falls back to a session-level tap if the HID tap can't be created.
• Intercepts both key-down AND key-up events to prevent mediaremoted from launching Apple Music
• Uses NSApplicationActivationPolicyAccessory for Sequoia/Tahoe compatibility
• Falls back to spacebar/arrow key injection for apps without AppleScript support
• Learns at runtime which apps AppleScript can actually drive. For apps it can't, next/previous are passed through to the app's own media-key handling instead of being swallowed — so track navigation keeps working, though those two keys follow normal system routing rather than being retargeted. Play/pause is always retargeted.

Why Not on the Mac App Store?

This app requires Accessibility permissions to intercept and consume media key events. Mac App Store apps must be sandboxed, and sandboxed apps cannot request Accessibility permissions. This is why similar apps like BeardedSpice are also distributed outside the App Store.

License

MIT