Emebala Documentation

Overview & Philosophy

In ancient Sumer around 2000 BCE, translators bridging diverse dialects, cuneiform clay tablets, and trade languages were revered as Eme-bala (literally: "those who turn language to bridge worlds"). Modern digital tools, however, have increasingly compromised individual liberty by routing confidential communications and literary manuscripts through remote corporate cloud servers.

Team Sunplaza engineered the Emebala ecosystem to restore absolute sovereignty to the reader and writer. Our codebase is crafted in modern, high-performance systems languages: C++20 for the ultra-low-latency Windows desktop flagship (Emebala Chat) and Rust for the modular literary sanctuary (Emebala Reader).

• Emebala Chat (C++20 Desktop Flagship): Native Win32 / Direct2D client powered by an embedded llama.cpp runtime executing quantized GGUF weights (Hy-MT2-1.8B-Q8_0.gguf). Intercepts input buffers in any application to replace what you typed in-place, accompanied by double-Ctrl+C drag-to-translate and zero-latency Windows Speech Platform audio.
• Emebala Reader (Rust Modular Architecture): Literary engine featuring 30+ format parsers (emebala-fs), synchronized bilingual dual-page spreads, Kokoro-82M ONNX speech synthesis, PP-OCRv6 text recognition, and AES-256-GCM encrypted local vault storage.

🚀 Quickstart Installation

Both Emebala Chat and Emebala Reader are distributed as self-contained standalone Windows applications. Emebala Chat is completely portable: its configuration file (config.json) and neural weights reside directly in its executable folder, requiring no registry writes or hidden AppData directories.

Obtain the latest portable release package or setup binary from the GitHub release distribution:

Get-FileHash -Path ".\EmebalaChat.exe" -Algorithm SHA256

⚙️ System Requirements

⚡ In-Place Send-and-Replace Mechanics

In Emebalachat/src/hook.hpp, Emebala Chat implements a revolutionary keystroke replacement workflow: you simply type naturally in your native tongue inside Slack, Discord, WeChat, Teams, WhatsApp, or any browser input, and press the key you normally press to send messages.

🖱️ Floating Rosetta Badge & Drag Gestures

Emebala Chat renders a lightweight hardware-accelerated Direct2D badge widget directly on the screen (Emebalachat/src/ui/badge.cpp):

• Single Left-Click: Toggles engine between Active and Paused translation state.
• Double-Click: Instantly swaps source and target translation direction (e.g. English ↔ Korean).
• Click & Drag: Freely repositions the floating status pill anywhere across single or multi-monitor desktop setups. Coordinates persist in badge_x and badge_y.
• Double Ctrl + C Trigger ("double_ctrl_c"): Highlighting any text on screen and pressing Ctrl+C twice quickly summons the Floating Translation Tooltip right at your cursor.

🔊 Windows Speech Platform (Chat TTS)

In Emebala Chat (src/sound.cpp), speech synthesis is powered directly by the native Windows Speech Platform (Windows 내장 언어팩) through the ISpVoice COM interface and WinRT Windows.Media.SpeechSynthesis.

🔒 Low-Level Keyboard Hook Safety Model

Emebala Chat's keyboard hook architecture (src/hook.cpp) was engineered under stringent safety constraints:

• LowLevelHooksTimeout Prevention (REQ-R06): The hook callback performs zero blocking I/O, zero network calls, and zero model inference on the hook thread. Heavy workloads are dispatched asynchronously to a dedicated pipeline worker thread (src/worker.cpp).
• Zero Cloud Clipboard Leakage: When capturing and restoring text selections, the Windows flag CanIncludeInClipboardHistory = 0 is applied, preventing transient translation strings from polluting Windows 10/11 cloud clipboard synchronization history.
• Zero Telemetry Logging: Keystrokes that are not the intercepted action keys are never logged, buffered, or stored to disk.

📖 Emebala Reader: Synchronized Dual-Page Engine

Engineered in Rust with a Flutter frontend bridge, Emebala Reader delivers a desktop sanctuary for long-form literature and scholarship:

• Sentence-Level Paragraph Alignment: The original text and translated text are dynamically mapped sentence-by-sentence into twin parallel columns or facing spreads.
• Reflowable Dual-Spread Layout: Typography adapts to window width, zoom scales, and cultural reading themes while strictly preserving line and footnote alignment.
• Continuous Bilingual Scrolling: Progressing through chapters scrolls both languages in perfect unison.

📚 30+ Supported Book & Document Formats

Emebala Reader's file system crate (native/emebala-fs/src) houses 39 Rust parser modules, delivering universal compatibility across world literature, digital comics, and academic documents:

🎨 Cultural Reading Themes & Typography

To eliminate digital eye strain during prolonged contemplation, Emebala Reader incorporates three bespoke cultural themes:

🔍 PP-OCRv6 On-Device Text Recognition

Scanned manuscripts, historical documents, and image-based PDF/comics are processed via the integrated OCR pipeline in native/emebala-ai/src/ocr.rs:

• ONNX Runtime Local Inference: Uses ONNX Runtime CPU/DirectML with zero external dependencies.
• DBNet++ Text Detection: Detects irregular, rotated, and curved text lines across dense historical pages.
• SVTR_LCNet Text Recognition: High-accuracy multilingual character recognition supporting Latin, Hangul, CJK characters, Arabic, Cyrillic, and Devanagari.
• Spatial Bounding Box Reconstruction: Extracted lines preserve layout geometry on the left page while feeding clean strings to the bilingual translation engine on the right page.

🎧 Kokoro ONNX & Windows SMTC Audio Controls

For long-form book listening, Emebala Reader embeds state-of-the-art neural audio synthesis (native/emebala-ai/src/tts/):

• Kokoro-82M ONNX TTS (kokoro.rs): Ultra-natural expressive voice generation running locally on ONNX Runtime with low memory overhead.
• Supertonic TTS (supertonic.rs): High-throughput streaming voice synthesis for rapid passage audition.
• Windows System Media Transport Controls (SMTC): Native Windows OS integration (audio_service_win). Control book playback, volume, pause/resume, and chapter skipping using physical keyboard media keys and the Windows lock screen media overlay.

🌐 Hy-MT2 33 World Languages Specification

The core translation engine supports 33 World Languages (1,056 bidirectional translation pairs) organized across five major geographical and linguistic families:

🏔️ 5 Regional Dialects & Indigenous Heritages

Beyond the 33 major world languages, Emebala safeguards 5 regional dialects and indigenous tongues often neglected by commercial translation cloud providers:

⚡ Dual Inference Architecture (llama.cpp & CTranslate2)

Emebala tailors its neural execution layer to the operational demands of each application:

Emebala Chat embeds llama.cpp directly via CMake FetchContent. It executes quantized GGUF weights (models/Hy-MT2-1.8B-Q8_0.gguf) with hardware acceleration:

• Zero Dynamic Allocations during Translation: The context and KV cache are pinned in memory for instantaneous keystroke response (~40ms).
• WinHTTP Cloud Fallback Client (src/google_translate.cpp): When cloud_fallback_enabled: true is explicitly configured by the user, Chat includes a native WinHTTP client for fallback translation. When false (default), zero external traffic is ever permitted.

In native/emebala-ai/src/translation/, Emebala Reader implements two modular backends:

• HyMt2Backend (hymt2.rs): Powered by llama-cpp-2 for Hy-MT2 1.8B and 7B GGUF models.
• Ct2Backend (ct2.rs): Powered by CTranslate2 for rapid concurrent batch translation across multi-paragraph book chapters.

🛡️ AES-256-GCM Vault & Memory Security

In native/emebala-crypto/src/, Emebala implements enterprise-grade cryptographic sovereignty:

• AES-256-GCM Authenticated Encryption: Reading logs, bookmarks, and confidential notes are encrypted with 256-bit Galois/Counter Mode to guarantee confidentiality and data integrity.
• Argon2id Key Derivation: Master passphrases are stretched using memory-hard Argon2id parameters to resist GPU/ASIC brute-force attacks.
• Memory Scrubbing on Drop (zeroize): Sensitive encryption keys and decrypted text chunks are wrapped in zeroize::ZeroizeOnDrop containers, guaranteeing memory pages are scrubbed immediately upon release.
• Windows DPAPI & Credential Manager: Encryption seeds on Windows are guarded by DPAPI, binding keys to the user's hardware TPM.

🔎 SQLite with FTS5 Trigram Full-Text Search

In native/emebala-db/src/, book contents, bilingual sentence alignments, and reading notes are indexed locally using SQLite FTS5 with trigram tokenizers:

• Sub-String & CJK Search: Trigram indexing enables instant search across Korean, Japanese, and Chinese texts without requiring complex word-break dictionaries.
• Cross-Language Querying: Search source and translated texts simultaneously across thousand-page books in milliseconds.

🕊️ Zero-Telemetry Verification Protocol

Verify Emebala's zero-cloud guarantee using your preferred network monitoring tool (Wireshark, Fiddler, or Windows Resource Monitor):

Get-NetTCPConnection | Where-Object { (Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue).ProcessName -like "*Emebala*" }

The output is completely empty. No outbound socket connects, no telemetry pings, and no background analytics ever leave your device.

⌨️ Global Hotkeys & Keyboard Shortcuts Matrix

The definitive shortcuts verified directly against Emebalachat/src/hook.hpp and src/config.hpp:

🔧 Portable config.json Schema

In Emebala Chat (Emebalachat/src/config.cpp#L477-483), configuration is stored directly beside the executable as GetExecutableDir() / "config.json". Below is the exact 18-key flat schema from code:

{
  "ui_language": "auto",
  "engine_type": "auto",
  "model_path": "models/Hy-MT2-1.8B-Q8_0.gguf",
  "source_language": "Auto Detect",
  "target_language": "English",
  "auto_send": false,
  "sound_enabled": true,
  "drag_to_translate": true,
  "cloud_fallback_enabled": false,
  "drag_hotkey": "double_ctrl_c",
  "hotkey_toggle": "F9",
  "hotkey_lang": "Ctrl+F9",
  "hotkey_mode": "Ctrl+Shift+Enter",
  "temperature": 0.7,
  "top_p": 0.6,
  "top_k": 20,
  "repetition_penalty": 1.05,
  "badge_x": -1,
  "badge_y": -1
}

❓ Troubleshooting & Frequently Asked Questions

Windows User Interface Privilege Isolation (UIPI) restricts standard user applications from sending synthetic keyboard events to elevated processes. If you wish to translate inside elevated terminals, run Emebala Chat as Administrator.

Navigate to Windows Settings > Time & Language > Speech > Manage Voices > Add voices. Install your preferred language pack. Emebala Chat's COM enumerator detects new voices immediately without requiring a restart.

Because Emebala Chat is fully portable, simply exit the application via system tray and delete its folder. There are no leftover background registry keys or background services.