Hammerspoon script to bind hotkeys to system key events

bindsystemkeys.lua

--
-- Bind keyboard shortcuts to macOS media key actions.
-- For example, bind F11/F12 to volume down/up.
--
-- If binding to a function key doesn't work work, check:
--     System Preferences > Keyboard > Shortcuts
-- for a shortcut that is already using the function key.
-- For example, F11 is usually bound to Show Dashboard.
-- Even if that shortcut is unchecked, it can interfere.
-- Make sure the shortcut is set to some other key.
--

-- `mods` and `key` are as hs.hotkey.bind() expects.
-- `systemKeyName` is as hs.eventtap.event.newSystemKeyEvent() expects.
-- `isrepeatable` indicates whether key should repeat when held down.
local function bindHotkeyToSystemEvent(mods, key, systemKeyName, isrepeatable)
    -- Convert `mods` from what hs.hotkey.bind() expects
    -- into what hs.eventtap.event:setFlags() expects.
    -- TODO: handle case when `mods` is a string.
    local eventMods = {}
    for _, v in pairs(mods) do
        eventMods[v] = true
    end
    local eventDown = hs.eventtap.event.newSystemKeyEvent(systemKeyName, true)
    local eventUp = hs.eventtap.event.newSystemKeyEvent(systemKeyName, false)
    eventDown:setFlags(eventMods)
    eventUp:setFlags(eventMods)
    local pressedfn = function() eventDown:post() end
    local releasedfn = function() eventUp:post() end
    local repeatfn = nil
    if isrepeatable then
        repeatfn = function()
            pressedfn()
            -- keyRepeatInterval corresponds to:
            --   System Preferences > Keyboard > Keyboard > Delay Until Repeat
            -- But Hammerspoon only seems to realize changes to that setting
            -- when it starts up. TODO: file bug
            hs.timer.usleep(hs.eventtap.keyRepeatInterval())
            releasedfn()
        end
    end
    hs.hotkey.bind(mods, key, pressedfn, releasedfn, repeatfn)
end

-- A list of valid bindable keys (e.g. "f12") can be found here:
-- https://www.hammerspoon.org/docs/hs.keycodes.html#map

-- A list of valid system key names (e.g. "SOUND_UP") can be found here:
-- https://www.hammerspoon.org/docs/hs.eventtap.event.html#newSystemKeyEvent

-- bind F7 - F12 to their usual macOS actions.
bindHotkeyToSystemEvent({}, 'f7', 'PREVIOUS', false)
bindHotkeyToSystemEvent({}, 'f8', 'PLAY', false)
bindHotkeyToSystemEvent({}, 'f9', 'NEXT', false)
bindHotkeyToSystemEvent({}, 'f10', 'MUTE', false)
bindHotkeyToSystemEvent({}, 'f11', 'SOUND_DOWN', true)
bindHotkeyToSystemEvent({}, 'f12', 'SOUND_UP', true)

-- bind shift-volumekeys to their usual macOS action:
--   inverting the sense of "Play feedback when volume is changed".
bindHotkeyToSystemEvent({'shift'}, 'f10', 'MUTE', false)
bindHotkeyToSystemEvent({'shift'}, 'f11', 'SOUND_DOWN', true)
bindHotkeyToSystemEvent({'shift'}, 'f12', 'SOUND_UP', true)

-- bind alt-volumekeys to their usual macOS action:
--   opening System Preferences > Sound.
bindHotkeyToSystemEvent({'alt'}, 'f10', 'MUTE', false)
bindHotkeyToSystemEvent({'alt'}, 'f11', 'SOUND_DOWN', false)
bindHotkeyToSystemEvent({'alt'}, 'f12', 'SOUND_UP', false)

-- bind shift-alt-volumekeys to their usual macOS action:
--   adjusting the volume in smaller steps.
bindHotkeyToSystemEvent({'shift', 'alt'}, 'f11', 'SOUND_DOWN', true)
bindHotkeyToSystemEvent({'shift', 'alt'}, 'f12', 'SOUND_UP', true)