v0.6.1

Security

Resolves all open Dependabot advisories by bumping the example module's
transitive dependencies golang.org/x/net and golang.org/x/image to
v0.38.0.

These were development-only dependencies pulled in by the examples' GUI
libraries. The importable hotkey module — which depends only on
golang.design/x/mainthread — was never affected, and its code is unchanged
from v0.6.0.

Full changelog: v0.6.0...v0.6.1

v0.6.0

This release changes how hotkeys work on macOS. Linux and Windows are unaffected.

⚠️ macOS: Accessibility permission is now required for all hotkeys

macOS hotkeys are now delivered through a CGEventTap instead of Carbon RegisterEventHotKey — a single mechanism now serves both regular and media keys, and the tap can consume the event so it does not also reach the focused app. (#46, closes #45)

As a result, every macOS hotkey now requires the application to be trusted for Accessibility (Input Monitoring) — previously only media keys (added in v0.5.0) needed it, and regular hotkeys needed no permission at all.

• Grant permission in System Settings → Privacy & Security → Accessibility.
• Without it, Register() returns an error (it does not crash or silently no-op).
• Sandboxed apps may be unable to use global hotkeys under this model.

🔒 Privacy note

To deliver hotkeys this way, the package now installs a global keyboard event tap. By construction such a tap can observe keyboard events system-wide; this package uses it only to match the specific key combinations you register and forward their press/release — it does not store, log, or transmit anything. The Accessibility permission prompt the OS shows reflects this capability. If you ship an application built on this package, mention the Accessibility requirement to your users.

Notes

• If you only need media keys, or you want the previous permission-free behavior for regular hotkeys on macOS, stay on v0.5.0 (Carbon for regular hotkeys + a tap for media keys).
• Docs (package doc + README) now describe the macOS Accessibility requirement.

Full changelog: v0.5.0...v0.6.0

v0.5.0

⚠️ Breaking changes

• Minimum Go is now 1.24 (was 1.17). (#37, #42)
• Key is now uint32 on all platforms (was uint8 on macOS, uint16 on Linux/Windows). Explicit narrowing casts such as uint16(key) must be updated; hotkey.KeyA and hotkey.Key(0x15) are unaffected. (#42)
• Register/Unregister error messages were normalized across platforms (text changed). (#41)

New features

• Media keys on all platforms — KeyMediaPlayPause, KeyMediaNext, KeyMediaPrev, KeyMediaStop, KeyVolumeUp, KeyVolumeDown, KeyVolumeMute. Linux uses XF86* keysyms, Windows VK_MEDIA_*, macOS a CGEventTap. See examples/media. (#42, #43, #44)
  • macOS: media keys require Accessibility (Input Monitoring) permission; without it Register() returns an error. KeyMediaStop is not available on macOS. Normal hotkeys are unchanged and still need no permission.
• OpenBSD (X11) support. (#36)

Fixes

• Linux: KeyTab was aliased to KeyEscape — corrected to the proper keysym. (#35)
• Linux: hotkeys now fire regardless of NumLock/CapsLock state. (#39)
• Linux: Unregister() now interrupts the X11 event loop instead of waiting for the next keypress (fixes a freeze on unregister). (#38)
• Linux: registering a combination already grabbed by another application now returns an error instead of crashing the process. (#40)
• macOS: fixed the dispatch.h import on case-sensitive filesystems. (#31)
• Windows: improved KeyDown/KeyUp detection. (#23)

Internal

• Modernized CI: actions/checkout@v4 / setup-go@v5, Go 1.24 + stable, arm64 runners (Linux/macOS/Windows), a CGO cross-build sweep, and an OpenBSD VM job. (#37)

Full changelog: v0.4.1...v0.5.0

v0.4.1

• Improve documentation without any functional changes.

Full Changelog: v0.4.0...v0.4.1

v0.4.0

What's Changed

• Adds more special keys and key parsing by @data-niklas in #14

New Contributors

• @data-niklas made their first contribution in #14

Full Changelog: v0.3.0...v0.4.0

v0.3.0

This version solves multiple limitations from the previous release.

1. The package can work with Fyne, Ebiten, Gio, Glfw, or even simple Go applications. Instructions and examples are provided.
2. This release contains breaking changes and bug fixes, but the migration is expected low due to the simplicity of the API design.
3. Registered hotkeys can be unregistered at runtime (#7).
4. Hotkeys trigger key down events and can trigger key up events (#9).

v0.2.1

This version improves the error message when CGO_ENABLED is set to 0.

v0.2.0

This version brings the following updates and requires Go 1.17:

• Use runtime/cgo
• Improve error message
• Retry on Linux if hotkey failed

v0.1.2

• Hotkey registration on windows bug fix

v0.1.1

• Explicit typing for modifier constants