vibevibe

Offline Chinese-English code-switching dictation for Linux. Press a key, speak, and the text lands at your cursor — nothing leaves your machine.

PyPI · Releases · Issues

Highlights

• Built for mixed Chinese-English speech. Powered by Qwen3-ASR, the only open ASR family explicitly trained for code-switching — 40 000+ English keywords were injected into its Chinese training data.
• CPU only. No CUDA, no PyTorch, no VRAM. Runs on ONNX Runtime, so dictation keeps working while your GPU is busy training something else.
• Fully offline. No account, no API key, no network calls at runtime.
• 0.4–0.8 s from key-up to text, measured on a Ryzen 7 9800X3D with 4 inference threads.
• Memory you control. A tray switch flips between "model resident" (~3.9 GB) and "load on demand" (~0.24 GB); turning the service off frees everything.
• Bilingual UI. Interface and logs in English or Simplified Chinese, switchable at runtime.

Table of Contents

• Why this exists
• Benchmarks
• Requirements
• Quick Start
• Usage
• Configuration
• Project Structure
• Run the benchmark yourself
• Troubleshooting
• Status
• Links
• Acknowledgments

Why this exists

Typing is the bottleneck when working with coding agents. Dictation solves that — unless you speak the way many engineers do: Chinese sentences with English technical terms embedded in them. That single constraint rules out nearly everything:

Linux + offline + code-switching was an empty intersection. vibevibe fills it.

Benchmarks

Measured on 12 recordings of the author's own speech containing 30 technical terms, captured with a webcam microphone at maximum gain — i.e. realistic conditions including clipping, not a clean lab recording.

Technical-term hit rate is the metric that matters here. The characteristic failure of code-switching ASR is transliterating an English word into Chinese characters: the sentence still reads fluently, so CER barely moves, but the output is unusable. In one measured sample commit / push / remote were all transliterated and CER was still only 0.47.

RTF = processing time ÷ audio duration. Lower is faster; 0.15 means an 8-second utterance is transcribed in about 1.2 s.

Requirements

System packages, installed by your package manager rather than pip:

sudo apt install xdotool xclip                                  # text injection
sudo apt install python3-gi gir1.2-ayatanaappindicator3-0.1     # tray icon (optional)

On GNOME 46+ the tray icon needs a shell extension. Ubuntu ships ubuntu-appindicators and enables it by default.

Quick Start

pip install vibevibe
vibevibe setup

setup handles everything pip cannot. It asks before each step, it is idempotent, and it never runs sudo for you — if a system package is missing it prints the command for you to run.

[1/8] Python dependencies
[2/8] System tools
[3/8] Command-line entry     makes `vibevibe` runnable from your shell
[4/8] Config file            ~/.config/vibevibe/config.toml
[5/8] Model weights          ~4 GB
[6/8] Desktop shortcut       default: Super+Shift+V
[7/8] Autostart service      systemd --user
[8/8] Tray icon

Then press Super+Shift+V, say something, press it again. The text appears at your cursor.

Triggering

Two independent channels, both active at once:

The keypad channel reads the input device directly, so it can use F13–F24 — keys that desktop shortcuts cannot bind at all. The macropad's firmware is flashed with F19 too, so it works on any machine without installing anything.

Why Super+Shift+V and not Ctrl+Shift+V: the latter is "paste as plain text" in browsers, VS Code and terminals. Those are in-application bindings, invisible to any system-level check. Applications rarely touch Super — it belongs to the desktop environment — so Super combos are the safe choice.

Settings → Keys lets you rebind either channel by pressing the key you want (combos included). Every candidate is checked for conflicts first:

• already bound by a system shortcut → rejected
• already bound by vibevibe's own shortcut → rejected (both channels would fire, and in toggle mode that cancels out — it looks like nothing happened)
• has an X11 keysym → allowed with a warning, because it will also reach the focused application

Usage

Dictating

Feedback is audible rather than visual on purpose: while dictating you are looking at the text field, not at the top of the screen.

Tray icon

A double-V icon appears in the top bar, acting as both control panel and status indicator:

Two switches:

The menu also has About, which shows the version, the paths in use, and a button to open the log.

Two quit entries — do not mix them up:

The tray is a separate process from the daemon. It has to be — otherwise "stop the service" would kill the very thing you use to start it again. And because they are two processes, quitting the whole program has to stop both explicitly.

Settings

Tray → Settings…, or vibevibe settings.

Changes are staged, not applied immediately. Nothing touches the config file until you press Save; Cancel means nothing ever happened. The footer shows ● N unsaved change(s), and closing the window with pending changes asks first.

Command line

vibevibe toggle      # start/stop recording — this is what the hotkey runs
vibevibe status      # daemon state, memory, last transcription
vibevibe doctor      # check dependencies, weights, config (loads no model)
vibevibe devices     # list microphones and keyboard devices
vibevibe settings    # open the settings window
vibevibe tray        # start the tray icon
vibevibe daemon      # run the daemon in the foreground, for debugging
vibevibe quit        # quit: stop the service and the daemon (the tray closes separately)

The daemon normally runs under systemd:

systemctl --user status vibevibe
journalctl --user -u vibevibe -f
systemctl --user disable vibevibe   # stop it from starting at login

Configuration

~/.config/vibevibe/config.toml. The settings window covers the common options; the file holds all 70-plus, each with a comment explaining how its default was measured.

Unknown keys make the program fail loudly rather than being ignored — a silently dropped typo would leave you believing a setting took effect when it did not.

The two knobs most worth knowing:

[daemon]
# Keep the model in RAM. Off = load on demand, ~0.24 GB, +1.7~2.5 s per use.
hot_reload = true

[asr.qwen_onnx_1p7b]
# 0 = use every core. This is the main CPU-usage dial.
intra_op_num_threads = 4

Project Structure

vibevibe/
  config.py           every tunable lives here; nothing is hardcoded elsewhere
  asr/                pluggable recognition backends
    qwen_onnx.py        Qwen3-ASR via ONNX Runtime — the default
    whisper_ct2.py      Whisper large-v3-turbo — comparison baseline
    qwen_hf.py          Qwen3-ASR via PyTorch — optional, needs torch
  recorder.py         audio capture
  audio_preproc.py    de-clipping, off by default (see Benchmarks)
  guard.py            blocks the known Qwen3-ASR runaway-repetition bug
  daemon.py           state machine + Unix socket server
  hotkey_evdev.py     raw input-device channel, for a dedicated macropad
  inject.py           puts text at the cursor
  sound.py            audio cues, synthesized — no asset files
  tray.py             system tray icon
  service.py          systemd user-service control, and "stop vibevibe entirely"
  launchers.py        the three places that record a launch command; reads and liveness
  settings_dialog.py  GTK settings window
  setup_wizard.py     `vibevibe setup`
  i18n.py             English / Chinese strings
  data/               config template, udev rule, systemd unit, icons
bench/                model comparison tooling
  corpus.toml           sentences to read aloud
  record_gui.py         recording UI with live waveform
  compare.py            benchmark runner
  metrics.py            CER / WER / technical-term hit rate

Run the benchmark yourself

The published numbers came from one person's voice and speaking habits. Yours will differ, so the tooling is included — measure instead of trusting:

python bench/record_gui.py                         # record the corpus (GUI, live waveform)
python bench/compare.py --label mine \
    --backends qwen_onnx_1p7b,qwen_onnx \
    --preproc both --threads 4

A two-backend comparison over 12 clips takes about a minute.

Troubleshooting

vibevibe doctor       # run this first — it checks whether the bound command still resolves
vibevibe status

xprop WM_CLASS          # the cursor becomes a cross — click the terminal window

[inject.paste_key_by_window_class]
"your-terminal-class" = "ctrl+shift+v"

sudo apt install python3-gi gir1.2-ayatanaappindicator3-0.1
gnome-extensions list --enabled | grep appindicator

Status

Alpha. Working and used daily by the author, but young.

• CPU inference, model choice backed by measurements
• Hotkey channel via GNOME shortcuts
• Tray icon, settings window, bilingual UI
• systemd user service, PyPI release
• Two-key macropad — keys flashed over the VIA protocol (left → F19, right → Enter), verified on real hardware
• Wayland support
• Context biasing to fix the remaining proper nouns

Links

• PyPI — https://pypi.org/project/vibevibe/
• Source — https://github.com/jeffliulab/vibevibe
• Qwen3-ASR — paper · repo

Acknowledgments

The ONNX pipeline is adapted from the reference implementation shipped with Daumee/Qwen3-ASR-0.6B-ONNX-CPU (Apache-2.0). It is not vendored here; fetch it if you want to compare:

curl -O https://huggingface.co/Daumee/Qwen3-ASR-0.6B-ONNX-CPU/raw/main/onnx_inference.py

Model weights: andrewleech/qwen3-asr-1.7b-onnx · Daumee/Qwen3-ASR-0.6B-ONNX-CPU · Zoont/faster-whisper-large-v3-turbo-int8-ct2

Licensed under Apache-2.0.