Overview

Sorahk is a Windows application for automating repetitive key press operations. It provides configurable input-to-output mappings with adjustable timing controls through a graphical interface. The application runs in the system tray and uses native Windows APIs for input detection and event simulation.

Platform Requirement: Windows 10 or later.

Screenshots

Light Theme

Main Interface

Dark Theme

Main Interface

Features

User Interface

• Graphical configuration management through egui framework
• Multi-language support: English, Simplified Chinese, Traditional Chinese, Japanese
• Light and dark theme options
• System tray integration
• Real-time status monitoring

Input/Output Support

• Single keys and combinations with modifier support
• Five standard mouse buttons (left, right, middle, X1, X2)
• Eight-directional cursor control with configurable speed
• Vertical scrolling with configurable wheel delta
• Xbox-compatible gamepad support via polling
• HID device integration for other controllers
• Input sequence detection for combo triggers
• Sequential output for macro execution

Key Mapping

• Flexible input-to-output mapping configuration
• Support for key combinations as both triggers and targets
• Sequence input triggers with configurable time windows
• Sequential output targets with customizable intervals
• Three target modes: Single, Multi, Sequence
• Individual turbo mode control per mapping
• Adjustable repeat interval and press duration
• Multiple simultaneous input mappings
• Process whitelist for application-specific operation

Performance

• Multi-threaded event processing with worker pool
• Lock-free concurrent data structures for sequence matching
• Atomic operations for minimal synchronization overhead
• Cache-aligned data structures for better CPU performance
• Ring buffer for efficient input history tracking
• Optional AVX2 SIMD acceleration (compile-time)
• SmallVec optimization to reduce heap allocations
• Optimized pattern matching for sequence detection
• Native Windows API integration for input handling

Installation

Binary Release

Download pre-built executables from the releases page:

• sorahk-x.y.z-$target.zip - Standard build (compatible with all x86_64 CPUs)
• sorahk-avx2-x.y.z-$target.zip - AVX2-optimized build (Intel 2013+ / AMD 2015+ CPUs)

Extract the archive and run sorahk.exe. The application will generate a default Config.toml on first launch.

Building from Source

Prerequisites:

• Rust toolchain (stable channel)
• Windows 10 or later

Build commands:

# Clone repository
git clone https://github.com/llnut/Sorahk.git
cd Sorahk

# Standard build
cargo build --release

# AVX2-optimized build (requires AVX2 support)
# PowerShell:
$env:RUSTFLAGS="-C target-feature=+avx2"; cargo build --release

# CMD:
set RUSTFLAGS=-C target-feature=+avx2 && cargo build --release

# Auto-detect CPU features:
$env:RUSTFLAGS="-C target-cpu=native"; cargo build --release

# Output: target\release\sorahk.exe

Configuration

Sorahk reads settings from Config.toml in the executable directory. The file is created automatically with default values on first run.

Basic Example

# General settings
show_tray_icon = true
show_notifications = false
always_on_top = false
dark_mode = false
language = "English"

# Performance settings
input_timeout = 10
interval = 5
event_duration = 5
worker_count = 0

# Control settings
switch_key = "DELETE"

# Process whitelist (empty = all processes)
process_whitelist = []

# Key mappings
[[mappings]]
trigger_key = "A"
target_key = "A"
interval = 5
event_duration = 5
turbo_enabled = true

[[mappings]]
trigger_key = "LCTRL+C"
target_keys = ["LCTRL+V"]
turbo_enabled = true

# Sequence trigger example (fighting game combo)
[[mappings]]
trigger_sequence = "LS_Down,LS_DownRight,LS_Right,A"
target_keys = ["J"]
sequence_window_ms = 500
turbo_enabled = true

# Sequence output example (macro)
[[mappings]]
trigger_key = "F5"
target_keys = ["H", "E", "L", "L", "O"]
target_mode = 2
interval = 50
turbo_enabled = false

Supported Input Types

Keyboard Keys:

• Letters: A to Z
• Numbers: 0 to 9
• Function keys: F1 to F24
• Navigation: UP, DOWN, LEFT, RIGHT, HOME, END, PAGEUP, PAGEDOWN
• Editing: SPACE, RETURN, TAB, ESCAPE, BACKSPACE, DELETE, INSERT
• Modifiers: LSHIFT, RSHIFT, LCTRL, RCTRL, LALT, RALT, LWIN, RWIN
• Numpad: NUMPAD0 to NUMPAD9, MULTIPLY, ADD, SUBTRACT, DECIMAL, DIVIDE
• System: SNAPSHOT, PAUSE, SCROLL, CAPITAL, NUMLOCK

Key Combinations:

• Format: MODIFIER+KEY (e.g., LCTRL+C, LALT+RSHIFT+F1)
• Left and right modifiers are distinguished

Mouse:

• Buttons: LBUTTON, RBUTTON, MBUTTON, XBUTTON1, XBUTTON2
• Movement: MOUSE_UP, MOUSE_DOWN, MOUSE_LEFT, MOUSE_RIGHT, MOUSE_UP_LEFT, etc.
• Scroll: SCROLL_UP, SCROLL_DOWN

XInput Controllers:

• Format: GAMEPAD_VID_ButtonName (e.g., GAMEPAD_045E_A)
• Buttons: A, B, X, Y, Start, Back, LB, RB, LT, RT, LS_Click, RS_Click
• D-Pad: DPad_Up, DPad_Down, DPad_Left, DPad_Right
• Analog sticks: LS_Up, LS_Down, RS_Left, RS_Right, etc.
• Combinations: GAMEPAD_045E_LS_RightUp+A

Raw Input Devices:

• Format: DEVICE_VID_PID_SERIAL_Bx.x
• Requires initial device activation to establish baseline data

Sequence Triggers:

• Format: trigger_sequence = "Key1,Key2,Key3"
• Comma-separated input sequence (e.g., "DOWN,RIGHT,A")
• Configurable time window for completion (default: 500ms)
• Smart transition tolerance for intermediate inputs
• Bidirectional diagonal matching for XInput sticks

Sequence Targets:

• Format: target_keys = ["Key1", "Key2", "Key3"] with target_mode = 2
• Execute keys in sequential order
• Configurable interval between keys
• Turbo mode for repeating sequences

For complete configuration documentation, see the example Config.toml generated on first run.

Usage

1. Run sorahk.exe to start the application
2. Configure mappings through the GUI or by editing Config.toml
3. Press the switch key (default: DELETE) to toggle operation
4. Application runs in system tray when minimized

GUI Key Capture

When capturing input through the settings dialog:

1. Click the capture button for the desired field
2. Press the key or button to capture
3. For combinations, hold all keys/buttons, then release
4. Captured input appears in the field automatically

Testing

Sorahk includes a test suite covering core functionality. Run tests with:

For detailed testing information, see TESTING.md.

Performance

Sorahk has been benchmarked against AutoHotkey v2.0.19 using microsecond-precision measurements with a 5ms target interval (200 Hz). Tests were conducted using sorahk-perf-monitor, recording 1000 events per scenario.

Results

Test Environment:

• Processor: Intel Core i9-13900H @ 2.60 GHz
• Memory: 32 GB RAM
• OS: Windows 11 23H2
• Measurement: RDTSC-based timing (calibrated at 2995.19 MHz)

Contributing

Bug reports and feature requests can be submitted through the issue tracker. Code contributions should follow Rust coding conventions and maintain compatibility with existing functionality.

License

MIT License - see the LICENSE file for details.

Acknowledgements

Built with:

• Rust - Systems programming language
• windows-rs - Windows API bindings
• egui - Immediate mode GUI framework
• eframe - Application framework for egui
• toml - Configuration file parser