The New Wayland Global Shortcuts Protocol

Technological focus: Wayland global hotkeys/shortcuts

The video discusses the “Wayland Global Shortcuts Protocol” (auto-captioned as XXHotKeyV1 Global Hotkey Protocol) and argues it’s likely not to be merged upstream into the main Wayland repositories. However, it may still be adopted bottom-up by individual compositors and/or clients.

A “global shortcut” here means triggering actions even when the app window isn’t focused—for example, push-to-talk in Discord while playing a game.

Current state of the problem on Wayland

On Wayland, global shortcuts don’t work consistently, unlike on X11/Windows/macOS, where global hotkeys are more standard.

Some desktops (e.g., KDE) provide workarounds, but they’re described as hacks and not fully reliable.

Practical workaround path mentioned

A common workaround highlighted is:

• OBS can emulate global hotkey behavior via OBS WebSockets / OBS Web server
• External hardware (e.g., a Stream Deck) can send commands that trigger OBS actions (like overlay changes)

This approach is considered not ideal because it doesn’t provide native “like X11/Windows” global hotkey semantics.

The existing “solution”: Global Shortcuts Portal

The speaker frames the XDG/Global Keyboard Shortcut Portal as the accepted Wayland approach:

• Implemented and merged in XDG Portal repositories
• Many desktops have portal implementations
• It’s described as actively used, with OBS as an outlier

Why applications might avoid the portal

Applications may avoid it because:

• It forces shortcut configuration into desktop-specific UX/settings, not the app’s own UI
• UX fragmentation across desktop environments (DEs)
• Some advanced app behaviors are hard or impossible via the portal, such as:
  • Non-standard shortcut setups
  • Multiple keybinds
  • Rules like preventing double-binding

The speaker characterizes the portal as a “UX nightmare” for app developers.

Why the new protocol instead of a portal? (key technical arguments)

The video argues the proposed protocol has better technical/architectural properties:

• Trigger key semantics

  • The protocol uses key symbols (keysym) aligned with Wayland’s keyboard keymap (from wl_keyboard on the seat).
  • The speaker claims the portal’s trigger strings don’t reliably map to a keymap, leading to uncertain bindings.

• Activation token / input serial behavior

  • Wayland’s design allows the compositor to consume the hotkey while still routing activation through normal pathways.
  • The speaker claims the portal + D-Bus activation approach can’t carry a valid Wayland input serial / activation token, which matters for raising surfaces from hotkeys.

• Dependency concerns

  • Portals can require a running portal service and a D-Bus session, which some compositor users avoid.

Protocol behavior described (what it aims to guarantee)

Based on the protocol description as presented in the video, the key expectations include:

• A client can choose and freely reconfigure its own global hotkeys at runtime.
• The compositor stays the arbiter:
  • Accepts or denies key combinations
  • Can revoke bindings at any time
• The client receives explicit feedback:
  • Bound or denied responses
  • Reason codes
  • Optional human-readable messages
• Withdrawals:
  • A bound hotkey can be revoked, with reason info indicating whether re-requesting is acceptable
• No reliance on:
  • Out-of-band user configuration
  • Persisted compositor state

The speaker contrasts this with portal behavior, where clients may not reliably know the true binding state.

Adoption / implementation status (bottom-up momentum)

The video claims the protocol already has real deployments even if upstream standardization stalls:

• Merged into Hyprland (timeline mentioned: opened June 7, merged by June 14)
• Other adoption mentions:
  • Ghostty Terminal: merged
  • Niri: open discussion (less activity)
  • An OBS-related PR: reopened/closed/active discussion (described as especially interesting due to OBS constraints)

The speaker suggests this resembles earlier Wayland history: protocols spread through compositors/clients first, then later become upstream-standard, rather than following a top-down “FDO/Wayland repo” model.

OBS as the central blocker (portal vs protocol)

OBS is presented as a major example of why adoption is complicated:

• OBS reportedly had an open Global Shortcuts Portal issue from Dec 2022 with no resolution yet.
• The developer/community response includes:
  • OBS can mostly rely on portals for cross-DE behavior, but that requires coordinated changes across both OBS and portal implementations
  • OBS also argues a compositor-specific or non-portal protocol may not “spread” widely enough
  • Another concern: global shortcuts “out of focus” are handled by portals rather than Wayland protocols, meaning both areas would need coordinated change

The video also includes triage/moderation context, noting that a prominent OBS maintainer/triager (Joel Bethke / Fenrith Viddy) is said to have reopened the PR for further discussion.

Arguments about protocol standardization strategy (upstream vs downstream)

The video includes debate about whether pushing compositor/client implementations to drive upstream standardization is “backwards.”

Counterpoints mentioned include:

• Many EXT-like protocols became standards because they were already shipping and in use.
• Standardization often follows deployment rather than preceding it.

The speaker emphasizes that getting adoption in major environments (e.g., Plasma, GNOME, Cosmic) matters more than niche compositors like Hyprland/Niri (described as having low market share).

Notable technical claims about D-Bus dependency vs reality

A highlighted comment disputes some of the speaker’s objections:

• It claims the global shortcuts portal already exists and is used by apps and compositors (except OBS)
• It disputes stated objections:
  • The commenter claims the portal can produce activation tokens
  • It argues the “trigger keysym” critique is an anti-feature, because the solution should work across devices (e.g., systems without a keyboard) and support touch gestures

Speaker’s concluding expectation

The video’s expectation is:

• the new protocol may not be merged upstream into “main Wayland repos,” but
• adoption by clients/compositors could still pressure eventual acceptance.

Main sources / speakers

• Primary speaker/host: The YouTube narrator (name not provided in the subtitles)
• Referenced participants in repo/discussions:
  • MrTitan652
  • Joel Bethke / Fenrith Viddy
  • m e w h a k 9 0 (auto-captioned username: “mehawk90”)
  • Sebastian Wick