17 KiB
17 KiB
Viet+
Vietnamese Input Method for Linux
Zero underline • No pre-edit buffer • Backspace-Replay sync • Built in Rust
What is Viet+?
Viet+ is a Vietnamese input method for Linux that takes a fundamentally different approach from every other IME: Direct Input.
Most Vietnamese IMEs use a pre-edit buffer — you type into a temporary buffer with an ugly underline, and the text only becomes real Vietnamese when you commit it. This causes:
- Duplicate text (buffer + committed)
- Underline distraction
- Broken copy/paste
- Desync between engine state and what's on screen
Viet+ eliminates all of this. Keystrokes are instantly converted to Unicode — what you type is what you see. No buffer. No underline. No duplication.
How It Works
Data Flow: Keypress to Screen
Physical Keyboard
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Stage 1: KEY CAPTURE │
│ │
│ evdev: /dev/input/event* grabs keyboard (primary, reliable) │
│ X11: XRecord passive monitoring (fallback) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ evdev grab │ │ X11Capture │ │ Window switch │ │
│ │ (libevdev) │ │ (XRecord) │ │ detection (250ms)│ │
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Stage 2: KEY ROUTING │
│ │
│ Modifier keys (Ctrl/Alt/Super) → forward directly │
│ Ctrl+Space → toggle Vietnamese ON/OFF │
│ Backspace → replay_backspace() │
│ Characters → replay_and_inject(ch) │
│ VNI control keys → consume when no match │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Stage 3: BAMBOO ENGINE │
│ │
│ Transformation model: keystrokes produce composition │
│ changes. Marks and tones modify existing characters. │
│ Flexible backtracking scans up to 5 chars for vowels. │
│ Smart uo→ươ cluster with backtrack. │
│ Only emits Replace events when output actually changes. │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Stage 4: KEY INJECTION │
│ │
│ Primary: uinput injection (evdev keycodes, correct on all │
│ display servers — routed through libinput on modern X11) │
│ ASCII: direct Linux keycodes via /dev/uinput │
│ Backspace: Linux keycode 14 via uinput │
│ Vietnamese Unicode: clipboard paste + trailing ASCII via │
│ uinput (split only at whitespace/punctuation boundary) │
│ uinput Ctrl+V via /dev/uinput (no X11 dependency) │
│ │
│ Fallback: X11 XTest injection (X11 keycodes = evdev + 8) │
└──────────────────────────────────────────────────────────────┘
│
▼
Application receives keystrokes
and renders Vietnamese text on screen
Event Sourcing + Backspace-Replay
This is Viet+'s core innovation. Traditional IMEs track state incrementally — each keystroke updates an internal buffer. But this buffer can desync from what's actually on screen (due to focus changes, external pastes, etc.).
Viet+ uses Event Sourcing: every input action is recorded as a typed InputEvent (KeyTyped, Backspace, Flush, Paste) in an EventStore. On every keystroke, the entire event history is replayed from scratch through a fresh engine to compute the correct diff — no incremental state to desync.
Traditional IME:
keystroke → update buffer → emit event → hope it matches screen
Viet+ (Event Sourcing):
keystroke → append InputEvent → replay ALL events in fresh engine → compute diff
On every keystroke:
- The keystroke is appended as an
InputEventto theEventStore - A brand new
Engineis created - The entire event history is replayed through it via
Engine::replay_events() - The engine's buffer is the correct screen output
- Viet+ computes the diff:
Engine::replay_events_to_commands()returns Type/Backspace commands
This means:
- Zero state desync — always recomputed from scratch
- Self-healing — if anything goes wrong, the next keystroke fixes it
- Privacy-safe —
EventStore::pattern_hash()provides a sha256 of the event type sequence for pattern detection without any ability to recover original text - Simple — no complex state tracking or synchronization
Architecture
vietc/
├── engine/ # Vietnamese composition engine (bamboo-core Rust port)
│ ├── engine.rs # Orchestrator + replay_events(), replay_events_to_commands()
│ ├── event.rs # Event Sourcing: InputEvent, EventStore, Command
│ ├── bamboo.rs # Bamboo engine: transformation model, composition, tone placement
│ ├── input_method.rs # VNI rule definitions
│ └── spelling.rs # Vietnamese syllable validation
│
├── protocol/ # Keyboard capture & injection
│ ├── inject.rs # KeyInjector trait
│ ├── x11_capture.rs # XRecord keyboard capture via C helper
│ ├── x11_inject.rs # XTest injection (fallback)
│ ├── uinput_monitor.rs # /dev/uinput injection (primary)
│ ├── uinput_client.rs # Unix socket client for vietc-uinputd
│ └── wayland_im.rs # Wayland IM protocol
│
├── daemon/ # Main daemon process
│ ├── main.rs # Event loops, Backspace-Replay, CPU pinning
│ ├── config.rs # TOML config loader + hot reload
│ ├── app_state.rs # Per-app Vietnamese/English memory
│ └── display.rs # X11/Wayland/compositor detection
│
├── uinputd/ # Privileged uinput backspace daemon (VMK-style)
│ └── main.rs # Unix socket server for /dev/uinput injection
│
├── ui/ # System tray icon
│ └── main.rs # Tray + daemon launcher
│
├── cli/ # Interactive test harness
├── packaging/ # .deb packaging scripts
└── vietc.toml # Default configuration
Component Interaction
┌─────────────────────────────────────────────────────────────┐
│ vietc-tray │
│ (System tray icon, daemon launcher) │
└───────────────────────┬─────────────────────────────────────┘
│ starts
▼
┌─────────────────────────────────────────────────────────────┐
│ vietc-daemon │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Config │ │ App State │ │ Display │ │
│ │ (hot reload) │ │ (per-app) │ │ (X11/Wayland) │ │
│ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └─────────────────┼────────────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ Event Loop │ │
│ │ │ │
│ │ evdev: grab │ │
│ │ keyboard │ │
│ │ │ │
│ │ Process │ │
│ │ keystroke │ │
│ │ │ │
│ │ Replay all │ │
│ │ history │ │
│ │ │ │
│ │ Inject │ │
│ │ diff │ │
│ └─────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ vietc-engine │ │
│ │ VniEngine / EnglishDict / Spelling │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ vietc-protocol │ │
│ │ UinputInjector / X11Injector / X11Capture / Wayland │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Input Methods
VNI (default, Telex coming in next version)
| Key | Result | Example |
|---|---|---|
1 |
á (sắc) | a1 → á |
2 |
à (huyền) | a2 → à |
3 |
ả (hỏi) | a3 → ả |
4 |
ã (ngã) | a4 → ã |
5 |
ạ (nặng) | a5 → ạ |
6 |
â/ê/ô | a6 → â, e6 → ê, o6 → ô |
7 |
ơ/ư | o7 → ơ, u7 → ư |
8 |
ă | a8 → ă |
9 |
đ | d9 → đ |
Flexible typing: type the full syllable, then add marks/tone keys at the end. Example: nguye6n4 → nguyễn. The engine scans backward up to 5 characters to find the target vowel.
Features
| Feature | How It Works |
|---|---|
| Direct Input | No pre-edit buffer. Keystrokes instantly become text via uinput injection |
| Bamboo Engine | Transformation model ported from bamboo-core — composition, marks, tones, flexible backtracking |
| Flexible Backtrack | Type tone/modifier at end of syllable (tran5 → trạn). Scans up to 5 chars backward |
| Smart Clusters | uo → ươ with backtrack (chuong7 → chương) |
| Tone Placement | Correct tone positioning for all Vietnamese diphthongs (io→gió, uâ→xuất, yê→nguyễn) |
| Macro Expansion | ko → không, dc → được, custom shortcuts |
| Casing Preservation | Tieengs → Tiếng, TIEENGS → TIẾNG |
| App Memory | Per-app Vietnamese/English state, saved to overrides.toml |
| Hot Reload | Config changes apply without restart (polls mtime every 1.5s) |
| Window-Switch Reset | Active window ID verified on every keystroke — Alt+Tab instantly clears engine state. No stale composition across apps |
| CPU Priority | Pins daemon to P-cores (0-3) + nice(-10) for low-latency input |
| Uinput Injection | Uses /dev/uinput for reliable keyboard injection without X11 dependency. Falls back to XTest on systems without uinput access |
Installation
Single Command (from Source)
Depending on which repository you prefer to clone from, you can use one of the following commands to install or update Viet+ in a single step:
From GitHub (Recommended)
Install / Update:
git clone https://github.com/vndangkhoa/vietc.git /tmp/vietc && cd /tmp/vietc && sudo ./install.sh
Uninstall:
curl -sSL https://raw.githubusercontent.com/vndangkhoa/vietc/main/uninstall.sh | sudo bash
From Forgejo (Self-Hosted)
Install / Update:
git clone https://git.khoavo.myds.me/vndangkhoa/vietc.git /tmp/vietc && cd /tmp/vietc && sudo ./install.sh
Uninstall:
curl -sSL https://git.khoavo.myds.me/vndangkhoa/vietc/raw/branch/main/uninstall.sh | sudo bash
Debian Package (recommended)
System tray icon + daemon + desktop entry. Requires user to be in the input group for keyboard capture.
# Install
sudo dpkg -i vietc_0.1.6-1_amd64.deb
# Log out and log back in (for input group membership to take effect)
# Then launch "Viet+" from your application menu
The post-install script will:
- Kill any running tray/daemon processes
- Remove stale binaries from
/usr/local/bin/ - Add your user to the
inputgroup - Prompt you to log out and back in
Build from Source
git clone https://github.com/vndangkhoa/vietc.git
cd vietc
make deb
sudo dpkg -i packaging/deb/vietc_0.1.6-1_amd64.deb
Requires Rust toolchain, pkg-config, libx11-dev, libxtst-dev, libevdev-dev. See packaging/deb/build-deb.sh for details.
Configuration
Config file: ~/.config/vietc/config.toml or ./vietc.toml
input_method = "vni" # "vni" or "telex"
toggle_key = "space" # Ctrl+Space to toggle
start_enabled = true # Vietnamese by default
grab = true # grab keyboard (evdev)
[auto_restore]
enabled = true
trigger_keys = ["space", "escape"]
[app_state]
enabled = true
english_apps = ["code", "vim", "kitty", "foot"]
vietnamese_apps = ["telegram", "discord", "firefox"]
[macros]
ko = "không"
dc = "được"
vs = "với"
lm = "làm"
License
MIT License — see LICENSE for details.
Made with love for the Vietnamese Linux community