Quick Start Guide

This page aims to give users an introduction to the Key Mapper interface and a demonstration on how to perform typical tasks with the app. For specific troubleshooting, consult the FAQ.

Info

This guide is updated to match current stable release UI. Report inaccuracies.

First time setup¶

When you open Key Mapper, you will be presented with this screen. This screen is referred to as the Key Mapper home screen.

Set up the accessibility service¶

Tapping the FIX button next to the accessibility service prompt will allow you to grant Key Mapper permission to run its accessibility service. You must do this for the app to work at all.

You can then tap Key Mapper in your list of available services. There may be many others on this screen and your interface may be slightly different.

Attention

If nothing happens when you tap FIX, or if you can't enable the service, see this page or ask for help in the Discord server.

Disable app-killing¶

Important

If you are using a Huawei or Xiaomi branded device, a device with 2GB of RAM or less, or intend to use the app while playing a mobile game, it is especially important to follow the next step.

Tapping the FIX button next to the battery optimisation prompt will allow you to turn off features of your device that may prevent Key Mapper's essential services from running in the background. This is usually the source of the common 'Key Mapper randomly stops working' issue.

Devices older than Android 6.0 do not have this prompt in Key Mapper. However, I was still able to find the setting in my device settings app. Read more below for details.

The screen that opens after tapping FIX may vary depending on your device. In my case, to disable optimisation I found the app(s) in the list, tapped them to open their settings, and chose 'Don't optimise' and on the second device, 'Disabled'.

Tip

There is an excellent guide at dontkillmyapp.com that explains how to disable battery and/or memory optimisation for your specific device. If Key Mapper randomly stops working even after you complete these steps, ask for help in the Discord server.

Creating a key map¶

Summary

A key map is an association between a user input (such as pushing a key or button) and a response from the device (sending information about what key was pressed and for how long).

In Key Mapper, 'user inputs' that are recognised by the app are called 'triggers'. The responses from your device that were due to a trigger being pressed are called 'actions'.

Key Mapper lets you assign actions to triggers that may be different from their default use. A 'volume up' trigger normally increases the volume when pressed, but this app can change that to something else.

This guide deals with 'Key event' triggers. If you want to remap fingerprint gestures, check out this guide.

Setting the trigger(s)¶

To create your first key map, tap the + icon at the bottom of the Key Mapper home screen. You will see the screen below. On larger screens this will look slightly different because multiple tabs will be merged into one tab.

In either case, the first step is to record a trigger. Tap the red 'Record trigger' button and then press the physical button that you want to change the function of. In this guide I will demonstrate with 'volume down'.

Key Mapper can also create a key map with multiple triggers. If you want to use more than one trigger for one key map, you can press the buttons in the order you will press them to execute the key map. For example, if you wanted to map 'Ctrl' + 'H' to show the device home menu you should press 'Ctrl' and then 'H'.

Key Mapper can also remap fingerprint gestures on many devices. You can learn how to do this here.

You should see this screen after pressing volume down.

Setup the ability to properly remap volume buttons¶

You only need to do this on Android 6.0+. If you want to remap volume buttons and use them when Do Not Disturb is enabled, you should grant Key Mapper permission to do so. Key Mapper will show the error in the picture above if you need to do this.

Tapping FIX will allow you to grant the permission. Find Key Mapper in the list and tap it in order to choose 'Allowed'.

Setting the action(s)¶

Next, it's time to choose an action. If you have a large screen, you will see the 'Add action' button at the bottom of the screen. Otherwise, tap the 'Actions' tab at the top of the screen and then you will see the 'Add action' button.

Tap the 'Add action' button at the bottom of this screen. The action selection screen will open. Here you can choose from a long list of actions. There is also a list of all the actions here.

For this simple demonstration I will choose KEYCODE_0 from the Keycode tab. This action will emulate pressing the 0 key on a keyboard. Key Mapper will let you know if you need to do any extra steps so that an action can work. In the picture there is an error message in the action telling you to 'enable' a Key Mapper keyboard. Tapping the action will take you to the correct place so that you can fix the error. I will walk through how to set up a key code action since these are the most used.

Tip

Key Mapper can also create a key map with multiple actions. If you want to add more actions to execute in series you can do so by tapping 'Add action' again and choosing the next action in the chain. You can drag and drop the actions into whatever order you like. In the next section you can specify a delay between those actions if you wish.

Fixing the action(s)¶

Tap the action to fix the error.
If you are creating a key code, key event or text action then you MUST read this guide
In this case tapping the action will take you to the 'Language & Input' settings on your device. On a stock Android 11 Pixel 2 this is what it looks like. You will see a list of all the installed input methods on your device.
It is important to have read the guide in step 2 to understand what is happening from now on. On my device I installed the Key Mapper GUI Keyboard so I am going to turn this one on. Press back to go back to Key Mapper.
There is now a 2nd thing that needs to be fixed as you can see in the picture.
Tap the action again and the input method picker will show up as shown in the picture. On Android 11+ Key Mapper can fix this error for you without showing the input method picker if you have enabled the accessibility service.
Since I enabled the Key Mapper GUI Keyboard I will use that input method with Key Mapper.
If you followed these steps correctly then Key Mapper will stop showing any error messages underneath the action as shown. This action will now work.

Customising a key map¶

You may wish to customise your triggers and actions to have specific behaviours. Most people will want to do at least some customisation.

Trigger settings¶

Starting with the triggers, tap the 3 dot menu to the right of the trigger's name to bring up the following menu.

You can choose from four different settings. Turning on "Do not override default action" will mean that Key Mapper will not replace the normal operation of your trigger, instead it will execute the key map as well as the default operation.

One trigger can have three different click types. Choose from short press, long press and double press. Read more.

Customising actions¶

Next, tap the 3 stacked dots to the right of the action's name to bring up the following menu.

Here you can customise a lot of the operation of your key map, including timing and multipliers.

The following details refer to action timing settings.

Delay before next action (ms)

Key Mapper 2.2.0+

This option takes effect if you have multiple actions in your mapping. The slider sets the amount of time between this action and the next.

How many times

Key Mapper 2.1.0+

On Key Mapper 2.2.0 and 2.1.0 this is called "action count".

This option serves as a multiplier. If this is equal to 5 when your mapping is triggered then your action will be performed 5 times. If this is used with the 'repeat' option then this will perform the action this many times every time it repeats.

Repeating actions¶

Repeat

When this is turned on, Key Mapper will execute your actions repeatedly. This is particularly useful when emulating a keyboard key press, where in most applications holding down the key would result in a repeating output. The default settings in Key Mapper are designed to emulate that behaviour when 'Repeat' is turned on.

Repeat every... (ms)

This option sets the time period for your repeating action. If this is set to 200, your action will repeat every 200ms, or in terms of frequency, 5 times per second. Some people prefer to think about this setting as a repeat rate, commonly measured in 'clicks' per second or cps. To calculate the appropriate time period for this option from a desired frequency, use this equation:

Time period (ms) = 1000 / Frequency ('cps')

Delay until repeat... (ms)

This option sets the amount of time between the first action and the second action (or the first repeat). This is part of the keyboard key behaviour simulation. If you want your repeating action to begin straight away, you can make this 0.

Hold down actions¶

Hold down

Key Mapper 2.1.0+

This setting provides the ability to simulate holding down a key or tapping a coordinate (Android 8.0+). With this turned on (and repeat turned off), the default behaviour is that holding down your trigger will translate to holding down the action, for as long as you hold down the trigger.

^{_{Hold down until trigger is...}}
^_Released ^{_{Pressed again}}

Key Mapper 2.2.0+

This setting allows you to choose from two behaviours. If 'Released' is selected, holding down your trigger key(s) will translate to holding down the action, for as long as you hold down the trigger key(s).

If you choose 'Pressed again', pressing your trigger key(s) once will be sufficient to start holding down the action. To stop the key map, you will need to press the trigger key(s) a second time.

Using 'Hold down' and 'Repeat' together¶

Key Mapper 2.2.0+

You can use turn on both of these settings to unlock an additional setting. A repeating hold down action behaves like a normal 'Repeat' action in that the action repeats itself with a given frequency. It also behaves like a 'Hold down' action in that each individual action will be held for a certain amount of time in each cycle.

Hold down duration (ms)

This allows you to set how long the action is held down for before repeating.

Special options¶

You can see explanations of more options here.

Adding constraints¶

Constraints allow you to restrict your mappings to only work in some situations.

To add a constraint fron the 'Constraints and more' or 'Options' tab, tap 'Add constraint'.

Go here to see how you can configure constraints.

Managing key maps¶

To save your key map and return to the home screen, tap the save :fontawesome-solid-save: icon in the bottom right of the screen.

Now your key map should already be working. To pause/unpause all of your key maps, pull down the notification tray and tap the Key Mapper notification to toggle between Paused and Running.

On the Key Mapper home screen, tap the 3 bar menu to open the Key Mapper general settings. You will see the following options.

Here you can pause/unpause/enable/disable all of your key maps at once.
You can also back up and restore key maps here. Learn more about back up and restore.

Tapping 'Show input method picker' allows for switching between a Key Mapper compatible keyboard and any other.

Tip

Key Mapper can also remap fingerprint gestures on many devices. You can learn how to do this here.