Table of Contents
The mappings file lives at ~/.config/dome-key/mappings.dkmap. All +mappings should be written there. Three types of mappings can be defined: +maps, commands, and modes.
Maps are used to simulate keyboard keys. Commands run shell commands. +Modes, when activated, enable you to define multiple actions for the same +headphone buttons.
Map and command mappings are composed of three parts, each separated by +whitespace (one or more spaces or tabs):
MAP_TYPE TRIGGER ACTION
Mappings must be written on a single line. No line continuation operator +is available.
Comment lines are prefixed with a ‘#’ and must appear on their own line. +They are not permitted on the same line as mapping definitions.
ACTION corresponds to a sequence of keyboard keys that will be pressed +virtually. For example,
map <Up> Hello<Enter>
will type "Hello" with a newline at the end. Simulated keys are pressed in +succession as quickly as possible. There is no way to wait or sleep +between keys.
ACTION must be a shell command. In:
cmd <Down> say "Good morning"
the /usr/bin/say command will be executed, playing "Good morning" in +audible speech.
This map type is useful for running arbitrary code that can’t be expressed +by simulating keyboard keys with a map.
Commands are executed with $SHELL -c ACTION. If $SHELL isn’t set, +/bin/sh is used instead.
You can think of modes like Vim modes. They enable you to map the same +trigger more than once. Let’s look at an example:
cmd <Play> open -a Firefox
mode <Up> {
+ map <Play> <Space>
+}Here, the <Play> headphone button will open Firefox. But when the mode +is active, pressing <Play> instead simulates the Space key.
Modes are both activated and deactivated by pressing the TRIGGER sequence +written after the mode keyword. The trigger functions as a toggle. In +our example, pressing <Up> activates the mode. If the mode is active, +pressing <Up> will deactivate the mode, causing top-level mappings to +become available again.
Any number of maps and commands can be defined inside a mode. These are +enclosed by curly braces. Mode mappings should not use the same trigger +as the mode’s. Mappings with the same trigger are ignored:
mode <Play> {
+ # The following mapping is ignored:
+ map <Play> Hello
+}Modes cannot be nested.
Special keys are enclosed in ‘<’ ‘>’ brackets (e.g. <Play>). These are +used in map actions to simulate a key press.
Home, End, PageUp, PageDown
CapsLock, NumLock
Tab, Space
BrightnessUp, BrightnessDown, ContrastUp, ContrastDown
Help
Power, Eject
Modifiers can be applied to any key used in map actions. Modifiers can +also be chained. Modifiers must be prefixed to the key they’re modifying, +both of which are surrounded by ‘<’ ‘>’ brackets.
Video controls:
map <Up> <Left> +map <Play> <Space> +map <Down> <Right>
Don’t launch iTunes when pressing the middle button:
map <Play> <Nop>
Let volume buttons function normally, and activate video controls when +pressing <Play> twice:
mode <Play><Play> {
+ map <Up> <Left>
+ map <Play> <Space>
+ map <Down> <Right>
+}Open frequently used applications:
cmd <Up> open -a Terminal +cmd <Play> open -a Xcode +cmd <Down> open -a Firefox +cmd <Up><Play> open -a Dictionary
Compile code in Vim:
map <Play> <Esc>:make<CR>
Table of Contents
Enables customisation of headphone buttons. The dome-key program runs +in the background listening to button events, executing user-defined +actions in response to these events.
Headphone button mappings are defined in a file called +~/.config/dome-key/mappings.dkmap. See MAPPINGS or +dome-key-mappings(7) for more information.
An optional configuration file can be added at +~/.config/dome-key/config.toml.
Presently, only one configuration option is available. Here’s an example +config:
timeout = 400
Mappings are defined in ~/.config/dome-key/mappings.dkmap. See +dome-key-mappings(7) for a complete explanation of the syntax.
If a button is not mapped, it retains its normal function. The following +mappings apply when undefined, even without a mappings file:
map <Up> <VolumeUp> +map <Play> <Play> +map <Down> <VolumeDown>
It’s recommended that you run the program in the background using +launchd(8). Here’s an example plist:
<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" + "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> +<plist version="1.0"> +<dict> + <key>Label</key> + <string>com.teddywing.dome-key</string> + <key>ProgramArguments</key> + <array> + <string>/usr/local/bin/dome-key</string> + <string>--daemon</string> + <string>--audio</string> + </array> + <key>RunAtLoad</key> + <true/> + <key>KeepAlive</key> + <true/> + <key>StandardErrorPath</key> + <string>/tmp/dome-key.log</string> +</dict> +</plist>
You can also use brew services to do this automatically if the program +was installed with Homebrew.
Copyright © 2018 Teddy Wing
Copyright © 2005-2010 Lucas Newman and other contributors. All rights +reserved.
Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS +IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR +CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
cmd <Play> osascript -e 'activate application "Terminal"' -e 'tell application "System Events" to keystroke "2" using command down'+
+ dome-key(1), + dome-key-mappings(7) +
+