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

> Learn to use HoldShortcut for push-to-talk in OpenLogi. Effortlessly control your mic with this feature, enabling seamless communication.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-08

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```toml
[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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```rust
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action.rs).

- Configure push-to-talk in [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) using the syntax `ButtonName = { HoldShortcut = "Key+Combo" }` as documented in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md).

- The runtime guarantees key release through the hook implementation in [`crates/openlogi-agent-core/src/runtime/hook.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) and implemented in the agent core runtime.