How Long-Press and Hold-Until-Release Chords Function for Push-to-Talk in OpenLogi

OpenLogi implements push-to-talk functionality by binding physical buttons to HoldShortcut actions that maintain key chords for the entire duration of the physical press, automatically emitting key-up events on button release or session cancellation.

OpenLogi is an open-source input remapping system for Logitech devices that supports advanced interaction patterns including push-to-talk functionality. Understanding how long-press and hold-until-release chords function requires examining the runtime's state management and effect dispatch systems. This article analyzes the specific implementation in the AprilNEA/OpenLogi repository, tracing the flow from TOML configuration to low-level key injection.

The HoldShortcut Action Definition

In crates/openlogi-core/src/binding/action.rs, the Action enum defines HoldShortcut(KeyCombo) as the core mechanism for hold-until-release behavior. Lines 182-190 document this variant as creating a "Hold …" action in the UI, distinguishing it from instantaneous shortcuts. When the parser encounters this variant in a profile configuration, it signals the runtime to treat the chord as a complete press-hold-release cycle rather than a single keystroke.

The definition stores the target key combination (such as Ctrl+Space) within the enum variant, making it available to the dispatcher when the bound button activates.

Runtime Hook Processing and State Tracking

The crates/openlogi-agent-core/src/runtime/hook.rs file contains the input processing logic that manages chord lifecycles. When a HookEvent::Key arrives at the handle_key function (lines 496-505), the runtime evaluates whether the binding is a HoldShortcut.

If so, the system executes three critical operations:

1. State Recording: The thread-local HOLD state is borrowed and updated via HOLD.with_borrow_mut() to track the active hold
2. Key Registration: The chord is inserted into the global HELD_KEYS set to prevent duplicate presses and track current activity
3. Effect Queuing: The dispatcher receives the hold instruction for immediate injection

The HELD_KEYS set maintains a registry of all currently held chords, while the HOLD thread-local variable manages the internal state machine transitions.

Effect Translation and Key Injection

Once the hook establishes the hold state, crates/openlogi-core/src/binding/effect.rs (lines 277-282) translates the high-level HoldShortcut into Effect::HeldKey(KeyCombo). This conversion occurs in the binding evaluation pipeline before reaching the platform-specific injector.

The Effect::HeldKey variant instructs the openlogi-inject subsystem to emit a keydown event for every key in the combination. Unlike standard keypress effects, this effect maintains the pressed state indefinitely until the runtime explicitly signals release, matching the physical button's down state.

Safety Mechanisms and Cancellation

OpenLogi prevents stuck keys through robust lifecycle management in hook.rs. When the system detects HookEvent::CaptureInterrupted—such as when another application takes focus or the session ends abnormally—it immediately invokes HOLD.with_borrow_mut(HoldState::cancel).

This cancellation routine:

• Clears the HELD_KEYS set via HELD_KEYS.with_borrow_mut(HashSet::clear)
• Emits key-up events for all previously held chords
• Resets the internal hold state to prevent phantom keypresses

This safety guarantee ensures that push-to-talk chords release even if the physical button-up event is lost due to application crashes or focus changes.

Profile Configuration Example

Configuring push-to-talk requires defining a HoldShortcut action in your device profile's TOML configuration:

[[bindings]]
button = "Button4"                          # Physical button on the Logitech device

action = { HoldShortcut = "Ctrl+Space" }   # Hold Ctrl+Space while Button4 is pressed

This configuration binds Button4 to maintain the Ctrl+Space chord for the entire duration of the button press. The runtime automatically handles the press timing, keydown emission, and release sequencing without additional scripting.

The following Rust pseudocode illustrates the simplified runtime logic:

match event {
    HookEvent::Key(event) => {
        if let Action::HoldShortcut(combo) = binding {
            // Record the hold state
            HOLD.with_borrow_mut(|state| state.start(combo.clone()));
            HELD_KEYS.with_borrow_mut(|set| set.insert(combo.clone()));
            // Emit the key down for the whole chord
            dispatcher.queue_effect(Effect::HeldKey(combo));
        }
    }
    HookEvent::CaptureInterrupted => {
        // Clean up any held chords to prevent stuck keys
        HOLD.with_borrow_mut(HoldState::cancel);
        HELD_KEYS.with_borrow_mut(HashSet::clear);
    }
}

Summary

• Action::HoldShortcut in crates/openlogi-core/src/binding/action.rs defines hold-until-release semantics distinct from instantaneous shortcuts
• hook.rs maintains the HELD_KEYS set and HOLD thread-local state throughout the button press duration
• Effect::HeldKey triggers continuous keydown injection via the openlogi-inject subsystem
• CaptureInterrupted events automatically trigger HoldState::cancel to prevent stuck keys when focus is lost
• Configuration uses TOML syntax with HoldShortcut = "KeyCombo" mappings

Frequently Asked Questions

What distinguishes HoldShortcut from regular keyboard shortcuts?

Regular shortcuts emit instantaneous keypress sequences, while HoldShortcut maintains the entire chord in a pressed state for the physical duration of the button hold. This behavioral difference makes HoldShortcut essential for push-to-talk applications requiring sustained modifier combinations.

How does OpenLogi prevent stuck keys if the application crashes?

The runtime monitors HookEvent::CaptureInterrupted events in crates/openlogi-agent-core/src/runtime/hook.rs. When capture is lost or the session ends, the system automatically invokes HoldState::cancel and clears the HELD_KEYS set, ensuring all chords release regardless of the physical button state.

Can multiple buttons hold different chords simultaneously?

Yes, the HELD_KEYS global set supports tracking multiple active chords independently. Each bound button maintains its own entry in the set, allowing complex interaction patterns where several push-to-talk channels or modifier combinations remain active concurrently.

Which component handles the actual OS-level key injection?

While state management occurs in hook.rs and action.rs, the openlogi-inject crate processes Effect::HeldKey directives generated by crates/openlogi-core/src/binding/effect.rs. This separation of concerns allows the core logic to remain platform-agnostic while the injector handles platform-specific key event generation.

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