First you will need a third party keyboard-remapping application called Karabiner (formerly KeyRemap4MacBook). The application is a bit user unfriendly but in theory you only need to do this once. Also it currently doesn't work on MacOS Sierra...so keep that in mind.
Here we go...
You should give it some accessibility permissions if you want all the features.
Use the Helper Application "EventViewer" to get keycodes
Open the EventViewer to get keycodes/application/device ids:
Go to the Main tab and then press the key(s) on your keyboard, bluetooth remote, etc you want to re-map. In this case you can see keycodes for Media-Forward and Media-Back on my Satechi bluetooth remote (which I want to re-map to arrow keys left/right).
Go ahead and "copy to pasteboard" and paste it in a text document for later. Now depending on your use case you may go to the App or the Devices tab.
If you want to limit your key remapping to specific applications, then you will want to create a mapping rule that is for a specific application ID (e.g. google chrome). So you would go to the app tab and get the application ID for your application of interest (to be used later when we create the rule).
In my case I ONLY want to remap these keys on my Satechi bluetooth remote and don't want to mess up how my existing keyboard keys work...so I want to make a device specific rule. So I go to the Devices tab.
Note!!! For apps and devices, you should also copy and paste into a text file so you have the complete device/app id strings for use in our rule.
Building the rules
Now that you have keycodes, app and/or device ids copied and pasted into a text file for reference later, you can close the EventViewer and go back to the main app.
The default rules aren't very interesting to us, so we need to create a custom rule but editing
This will just launch a finder window showing private.xml. Go ahead and open private.xml in your favorite text editor.
Now you are ready to build rules...
Documentation on the format of this file is here:
<item> you need minimum
<autogen>. Name is just a name for you. Identifier is also made up by you but should be unique. autogen is where you specify the rule/mapping (ie key of interest should send keys foo bar).
Of further interest you can specify the rule only runs for specific active applications (I think this is where the MacOS Accessibility permissions come into play...so Karabiner can determine the active window). This is done with
Also of interest (to me) is
<device_only> which allows me to make a rule only for a specific keyboard (ie my satechi bluetooth remote). See the link above for more details.
Anyway. Use the keycode IDs, device IDs and application ids you got from the EventViewer to construct your custom rules.
Mine looks like this:
<autogen>__KeyToKey__ ConsumerKeyCode::MUSIC_NEXT_17, KeyCode::CURSOR_RIGHT</autogen>
<autogen>__KeyToKey__ ConsumerKeyCode::MUSIC_PREV_18, KeyCode::CURSOR_LEFT</autogen>
Summary: 2 rules. Satechi bluetooth remote device only. "next" media button maps to right arrow, "prev" media button to left arrow. Applies to all applications.
Load the rules
Save your XML file.
Go back to the Karabiner app.
Go to the "Change Key" tab.
Click "Reload XML" in the top left.
Your new rules should now show up.
Check the boxes to enable the rules.
Test that your new key mappings work as expected.
The app is definitely not user friendly but enabled me to setup exactly what I wanted pretty easily once I understood the options. Karabiner is a bit buggy...I had some events stop showing up in the event viewer even though the remapping rules were still working... restart helps.