How to Use HoldShortcut for Push-to-Talk in OpenLogi

OpenLogi's HoldShortcut action binds a physical button to a key chord that remains pressed for the duration of the button hold, automatically releasing when the button is released—making it perfect for push-to-talk microphone control.

OpenLogi is an open-source input remapping framework that enables complex keyboard automation through its Rust-based core library. The HoldShortcut feature in the binding system allows you to simulate a held key combination (like Ctrl+Space) while a physical input button remains pressed, providing reliable push-to-talk (PTT) functionality without toggle complexity.

Understanding the HoldShortcut Action

The HoldShortcut variant is defined in crates/openlogi-core/src/binding/action.rs as part of the Action enum. Unlike standard shortcuts that emit a single keypress event, this variant wraps a KeyCombo structure and maintains the "key down" state for the entire duration of the physical button press.

When activated, the system emits the chord's down event immediately upon button press. It then holds that state until the button is released, at which point it emits the corresponding up event. This lifecycle ensures that voice chat applications recognize the key as continuously held, exactly mimicking a human holding down a keyboard shortcut.

Configuring HoldShortcut in TOML

To implement push-to-talk functionality, you assign a HoldShortcut to a button in your OpenLogi configuration file. The syntax accepts any valid key combination string that the KeyCombo parser recognizes.

Create or edit your configuration file (typically located at ~/.config/openlogi/config.toml) and add the binding under the keyboard section:

[keyboard.bindings]

# Bind the left thumb button to hold Ctrl+Space while pressed

LeftThumb = { HoldShortcut = "Ctrl+Space" }

According to the configuration documentation in docs/CONFIGURATION.md, this syntax tells the OpenLogi agent to intercept presses on the specified button and translate them into held key chords. You can substitute Ctrl+Space with any valid combination such as Alt+F, Shift+Tab, or Ctrl+Shift+M depending on your voice application's PTT requirements.

Runtime Implementation and Event Lifecycle

The actual down/up lifecycle management occurs in crates/openlogi-agent-core/src/runtime/hook.rs. When the physical button is pressed, the runtime hook triggers the down event for the specified key combination. The system maintains internal state tracking to ensure that if the capture is interrupted (for example, by the application losing focus or a system suspend), the up event is still emitted to prevent stuck keys.

This safety mechanism is critical for push-to-talk reliability—if the button is physically released or the system interrupts the input stream, OpenLogi guarantees the virtual key is released. The implementation at line 497 in the hook runtime handles both the standard release path and the cancellation path to prevent key sticking.

Creating HoldShortcut Programmatically

For developers extending OpenLogi or building custom automation tools, you can construct a HoldShortcut action programmatically using the core binding types:

use openlogi_core::binding::{Action, KeyCombo};

// Parse the key combo from a string representation
let combo: KeyCombo = "Ctrl+Space".parse().expect("valid shortcut");

// Create the HoldShortcut action variant
let ptt_action = Action::HoldShortcut(combo);

// The action can now be stored in a binding map or serialized over IPC

This approach allows dynamic configuration generation where the key combination might be user-configurable at runtime. The KeyCombo type handles normalization and validation of the chord syntax according to the core binding rules defined in the library.

UI Representation and Visualization

When displayed in the OpenLogi desktop interface, HoldShortcut actions render with a generic "Keyboard" icon to indicate their input-simulation nature. The icon mapping logic resides in crates/openlogi-core/src/binding/action_ring/icon.rs, where the variant is associated with the keyboard glyph at line 320.

The UI distinguishes HoldShortcut from other action types (like single-press shortcuts or layer switches) through both iconography and labeling, making it easy to identify push-to-talk bindings in a complex configuration at a glance.

Summary

• HoldShortcut simulates holding a key chord for the exact duration of a physical button press, implemented in crates/openlogi-core/src/binding/action.rs.

• Configure push-to-talk in config.toml using the syntax ButtonName = { HoldShortcut = "Key+Combo" } as documented in docs/CONFIGURATION.md.

• The runtime guarantees key release through the hook implementation in crates/openlogi-agent-core/src/runtime/hook.rs, preventing stuck keys even if the capture interrupts.

• Programmatically create actions by parsing a KeyCombo and wrapping it in Action::HoldShortcut.

• The desktop UI renders these actions with a keyboard icon defined in crates/openlogi-core/src/binding/action_ring/icon.rs.

Frequently Asked Questions

What is the difference between HoldShortcut and regular Shortcut in OpenLogi?

A regular Shortcut emits a single keypress event (down and up in rapid succession) when the button is clicked, while HoldShortcut keeps the key chord depressed for the entire duration of the physical button hold. For push-to-talk, you must use HoldShortcut because voice applications require the PTT key to remain active continuously while speaking.

How do I configure multiple modifier keys for push-to-talk?

The KeyCombo parser accepts standard modifier combinations in the TOML string. For example, use "Ctrl+Shift+Alt+F" or "LeftCtrl+Space" in your configuration. The parsing logic validates the chord syntax and ensures the modifiers are held in the correct order during the simulated keypress.

What happens if my system sleeps or the OpenLogi agent crashes while I'm holding a button?

The runtime hook in crates/openlogi-agent-core/src/runtime/hook.rs includes safeguards that emit the up event if the button capture is interrupted. This prevents "stuck key" scenarios where your voice application would think the PTT button is still held down after a system resume or application restart.

Where is the HoldShortcut action type defined in the source code?

The enum variant is declared at line 189 of crates/openlogi-core/src/binding/action.rs. This file also contains the serialization logic and label rendering for the action, while the semantic behavior is documented in docs/CONFIGURATION.md and implemented in the agent core runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}