Spokenly logoSpokenly Docs

Use the Dictation Key as Shortcut

Make the microphone key on a MacBook keyboard start Spokenly instead of Apple Dictation, with the built-in hidutil tool.

  • Mac
  • Not available on iPhone
  • Not available on Windows
  • Not available on Linux
  • Not available on Android

MacBook keyboards have a dictation key (microphone) in the top row. You can make it start Spokenly instead of Apple Dictation with hidutil, a tool that comes with macOS.

MacBook keyboard with the dictation key highlighted

Set up

Map the dictation key to F5

Open Terminal and run:

hidutil property --set '{"UserKeyMapping":[{
  "HIDKeyboardModifierMappingSrc":0xC000000CF,
  "HIDKeyboardModifierMappingDst":0x70000003E
}]}'

Record the shortcut in Spokenly

Open Settings > Shortcuts > Recording Shortcut, choose Record shortcut… and press the dictation key. Spokenly shows it as F5. Click Save.

The key works at once, but macOS resets the mapping when you restart the Mac. To keep it, add a LaunchAgent.

Keep the mapping after a restart

A LaunchAgent sets the mapping each time you log in.

Create the LaunchAgent file

Create ~/Library/LaunchAgents/app.spokenly.KeyRemapping.plist with this content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>app.spokenly.KeyRemapping</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/hidutil</string>
        <string>property</string>
        <string>--set</string>
        <string>{"UserKeyMapping":[{
            "HIDKeyboardModifierMappingSrc":0xC000000CF,
            "HIDKeyboardModifierMappingDst":0x70000003E
        }]}</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Load it

launchctl bootstrap gui/$(id -u) \
  ~/Library/LaunchAgents/app.spokenly.KeyRemapping.plist

Undo

Remove the mapping:

hidutil property --set '{
  "UserKeyMapping":[]
}'

If you added the LaunchAgent, remove it too:

launchctl bootout gui/$(id -u) \
  ~/Library/LaunchAgents/app.spokenly.KeyRemapping.plist
rm ~/Library/LaunchAgents/app.spokenly.KeyRemapping.plist

On some Macs that an organization manages, its policies can block hidutil.

On this page