Skip to content

Key Maps

Refer to the Quick Start Guide for help with creating key maps. This page gives more detail about every option.

Make sure to save :fontawesome-solid-save: your key map after applying these changes.

Trigger

A trigger is a combination of keys that must be pressed in a certain way to 'trigger' the key map. A key map can only have one trigger. You can change the order of the keys by holding down on one and then dragging it into a new position.

This is the page to create a trigger for a key map.

Trigger modes

A trigger with one key doesn't have a mode. Triggers with more than one key can be one of two trigger modes: 'parallel' and 'sequence'. The button for a parallel trigger says 'at the same time' because this is more descriptive. The plus symbol between the keys will change to an arrow if the trigger is a sequence trigger. The developer has called them "parallel" triggers because you press it is one word and you press the keys in parallel.

Parallel

You must press the keys down at the same time to trigger the key map and the must be pressed down in the order as displayed from top to bottom. E.g For the trigger screenshot you must press volume up first and then volume down and not the other away around.

Sequence

You must press the keys down and up one after another to trigger the key map in a specified amount of time. This timeout is 1000ms by default and this default can be changed in the app settings. You can change the timeout for a specific key map by going to the options page for the key map as explained further down this page.

Key click type

There are 3 click types: short press, long press and double press.

Parallel triggers can only be short pressed or long pressed. The click type can be customised for each key in a sequence trigger by pressing on the 3 dot button on each key.

Short press

This is a simple press of the key and there are no restrictions to how you press it. The key map is triggered when this key is pressed down and doesn't need to be released to activate it. There are no options for this click type.

Long press

You need to hold down the key for at least some amount of time for it to trigger the key map. This is 500ms by default and this default can be changed in the app settings. You can change the long press delay for all keys in a key map by going to the options page for the key map as explained further down this page.

Double press

You need to press down and release the key in rapid succession for it to trigger the key map. You must do this within 300ms by default and this default can be changed in the app settings. You can change the double press timeout for all keys in a key map by going to the options page for the key map as explained further down this page.

Key device

Tap the button on a key so that Key Mapper only detects the key when it comes from a specific device. The default device is 'this device', which means the Android device that you've installed Key Mapper on.

External devices are only listed if they are connected to your Android device when you configure the key map. If you have multiple devices with the same name then turn on the setting to show the first 5 characters of the device ID in the app settings. This will help you distinguish between them.

Key options

This menu pops up if you press the 3 dot button on a key.

Do not remap

  Do not override default action

This is turned off by default. If this is turned on for a key then the key will still do it's normal thing even though it is remapped. E.g a volume down key with this option will still turn the volume down.

This option doesn't remap the trigger key, which means it will continue do its normal thing when clicked as well as your action. This will be automatically

Click type

This will change the click type for a key in a sequence trigger. A parallel trigger key will not have the click type option because all the keys have the same click type. You will find the buttons to change a parallel trigger's click type above the trigger mode buttons as shown in the image at the top of this Trigger section.

Customising actions

You can tap the pencil icon 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. There are two buttons to 'replace' and 'edit' the action. The 'edit' button isn't shown for all actions because you can't configure what they do.


 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.


 Repeat limit

Key Mapper 2.3.0+

Changing this will change how many times the action will repeat. By default this is set to "no limit".


 Stop repeating when...
    Trigger is released                        Trigger is pressed again                        Limit reached

  • Trigger is released. You will need to hold down the trigger in order for the keys to repeat. If you let go of the trigger, the repeating will stop.

  • Trigger is pressed again. Pressing your trigger once will be sufficient to start your repeating key map. To stop the key map, you will need to press the trigger a second time.

  • Limit reached. (Key Mapper 2.3.0+). Your key map will stop repeating once the limit has been reached regardless of whether the trigger is being held down.

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

There are options for a key map under the 'Options' or 'Constraints and more' tab. Here are explanations of each option.

Allow other apps to trigger this key map (2.3.0+)

This allows you to trigger the key map by using a shortcut or by sending an Intent to Key Mapper. Turning this off will stop any shortcuts or Intents for this key map from working.

Home screen (launcher) shortcut

You can create a home screen shortcut by tapping "create launcher shortcut" or by adding the shortcut to your home screen in the same way as a widget. You can also use this shortcut from automation apps like Tasker and Automate without having to create a home screen shortcut.

Note

This button will be disabled if your launcher doesn't let 3rd party apps tell it to create shortcuts so you'll have to create it manually.

Intent

There are many apps that can automate broadcasting Intents such as Tasker and Automate.

Intent action
io.github.sds100.keymapper.ACTION_TRIGGER_KEYMAP_BY_UID
Intent string extra
io.github.sds100.keymapper.EXTRA_KEYMAP_UID

The extra value is the UUID of the key map. You can copy the UUID in Key Mapper by turning on the "Trigger from other apps" option.


  Show an on-screen message

When this is turned on, the following notice will come up at the bottom of the screen when ever you trigger your mapping.

You can have your device vibrate instead of an on-screen message if you want. This option is below.


  Vibrate

 Vibrate duration (ms)

Tapping 'Vibrate' will cause your device to vibrate whenever you trigger your mapping. You can change how long your device vibrates with the slider.

  Vibrate when keys are initially pressed and again when long pressed

This is only shown if the 'at the same time' trigger mode is selected and the trigger needs to be long pressed.

This behaves similarly to the on-screen message option above.


  Detect trigger when screen is off. ROOT only.

These are the buttons which can be detected when the screen is off. Let the developer know about any buttons you would also like to be supported.

Note

Please send the output of pressing the buttons while running the adb shell getevent -lq command so the developer knows which key event name they need to add.

  • Volume Up
  • Volume Down
  • Headset button
  • Camera focus button
  • Camera button
  • Menu button (on some devices the Bixby button is detected by Key Mapper as a menu button)
  • Search button

 Long press delay (ms)

This is only shown if a trigger has at least one key that needs to long pressed. This option will change for how long these keys need to be held down.


 Double press timeout (ms)

This is only shown if a trigger has at least one key that needs to double pressed. This option will change the maximum amount of time that a button needs to be double pressed so that it is detected as a double press.


 Sequence trigger timeout (ms)

This is only shown if you've chosen the 'in sequence' trigger mode. This option will change the time limit for how fast you need to complete the trigger.

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.