vinoWhisper

Live captions for anything playing on your Linux laptop, running on the NPU that came with it. No cloud, no API key, no account, no audio leaving the machine. Point it at whatever is playing and it captions in your terminal, or in a floating box above everything else on screen. The same box does dictation too: hold a key, talk, and let go to type what you said. There is nothing to configure: start it and it goes.

pip install vinowhisper && vinowhisper-setup && vinowhisper-caption

To be upfront about the bias: I did not build this because local speech-to-text is hard to find. I built it because my laptop has an Intel NPU rated at 16 TOPS that was doing absolutely nothing, and captioning a video turns out to be the rare workload that suits it: continuous, latency-sensitive, and small enough to fit. 16 TOPS is a coprocessor, not a GPU, and whisper-small.en is one of the genuinely useful models that fits in it.

So the pitch is not "another Whisper wrapper." It is: the transcription runs on a chip that is otherwise idle, so it costs you no CPU, no GPU, no fan, and no network. openvino-genai's WhisperPipeline with device="NPU" does the work, the same idea as vinoAuthFace, different feature.

Measured on this laptop (Wildcat Lake, stepping A0), whisper-small.en on the NPU, 2026-09-12:

The Intel iGPU does the same window in 0.95s and the CPU in 2.30s, so both fallbacks are usable, just laggier.

Words are never rewritten once printed. The stitcher runs LocalAgreement-2: a word is committed only when two overlapping windows independently agree on it. That is why the transcript can live in your terminal's own scrollback, where it survives quitting and where your terminal's selection and search still work on it. The hearing… line is the words heard once and still waiting on a second opinion, so the two-cycle commit delay is visible rather than felt as a freeze.

It scales to zero, the systemd way. The NPU model load costs 10-30s, so something has to hold it. A socket unit owns the port at boot with no process running, systemd spawns the server on the first connection, and the server exits itself after 30 minutes idle. Serverless, on your laptop, with no framework.

The model download is verified. The export is hashed against pins in vinowhisper/model_digests.json before anything loads it, and the check tells a toolchain upgrade apart from bytes changing under a toolchain that did not. Details in SECURITY.md.

A missing NPU degrades instead of bricking. Selection walks NPU, then GPU, then CPU, and a fallback is never silent: it shows up in the server journal, in /health, in vinowhisper-doctor, and on the status bar as a red border.

It tells you how to fix it. Nearly every error path here prints the command that resolves it, in your distro's package names (see Supported distros).

The overlay is optional, and native. vinowhisper-gui is a 6.3MB Rust binary that floats a caption box above every window, fullscreen video included, with a tray icon, a global shortcut and a start-at-login toggle. It links nothing but libc and adds nothing to the Python install. It draws the same event stream as the terminal UI rather than reimplementing any of it. It also does dictation: hold Meta+H (the dictation key on laptops that have one), talk, and let go to type what you said into the focused window, one NPU decode per utterance. docs/gui.md

curl -fsSL https://raw.githubusercontent.com/karanshukla/vinoWhisper/main/scripts/install.sh | bash

That installs uv, clones the repo, builds the environment, and hands over to vinowhisper-setup, which is where every machine-specific decision happens: your capture tool, your NPU driver, the model export your device needs, and systemd units generated against paths that actually exist. It prints every command before running it and asks first. The desktop overlay (floating captions and dictation) is one more command once that is done: vinowhisper-setup --gui, which downloads it from the GitHub release and checks it against a digest pinned in the Python package.

From a checkout, or to see what it would do without doing it:

git clone https://github.com/karanshukla/vinoWhisper && cd vinoWhisper
uv sync --extra export               # --extra export: the one-time model export
uv run vinowhisper-setup --dry-run   # the whole plan, nothing changed
uv run vinowhisper-setup             # for real, one prompt per step

Or from PyPI, if you would rather wire up the machine yourself:

pip install vinowhisper   # needs Python 3.11-3.13
vinowhisper-setup         # still worth running: NPU driver, model export, units

pip install gets you the six vinowhisper-* commands and the Python dependencies. It cannot get you an NPU driver, a model export or systemd units, which is what vinowhisper-setup is for either way. See docs/install.md for the OpenVINO version floor and why this could not be a pip install until 2026-08-31.

The NPU needs a userspace driver half that no distro packages completely, and vinowhisper-doctor will tell you exactly which half is missing. docs/hardware.md covers every way it fails to appear.

vinowhisper-setup and vinowhisper-doctor read /etc/os-release and print install commands in your distro's own package names. Eight families are covered:

Anything else gets generic advice, and says so. Derivatives not listed are matched through ID_LIKE. On every distro the NPU compiler library (libopenvino_intel_npu_compiler.so) comes from Intel's release archive, because nobody packages it; the doctor detects that and prints the steps. docs/audio.md has the capture side.

vinowhisper-caption                       # caption system audio
vinowhisper-caption --source mic          # caption yourself
vinowhisper-caption --list-targets        # capture one app instead of the whole sink
vinowhisper-caption --debug               # per-cycle timings, levels, raw transcript
vinowhisper-caption --record ~/sess       # save the session for replay
vinowhisper-caption --plain > out.txt     # no status bar (implied when piping)
vinowhisper-caption --json                # one event per line, what the overlay reads

vinowhisper-gui                           # the floating overlay and tray icon
vinowhisper-gui toggle                    # show/hide it; Meta+Alt+C does the same
vinowhisper-gui dictate                   # start/finish dictating; hold Meta+H does the same
vinowhisper-gui --install --autostart     # launcher entry, and the tray at login
                                          #   (or tick "Start at login" in the tray)

vinowhisper-setup                         # guided install; re-runnable, idempotent
vinowhisper-setup --dry-run               # print the plan, change nothing
vinowhisper-setup --print-units           # the systemd units it would generate
vinowhisper-setup --gui                   # just the optional overlay and dictation

vinowhisper-doctor                        # devices, model, digests, audio, live levels
vinowhisper-doctor --json                 # the same, for a bug report
vinowhisper-doctor --no-probe             # skip the 2s-per-target level capture

vinowhisper-replay ~/sess --restitch      # re-run the merge logic offline
vinowhisper-replay ~/sess --sweep 8,12,20 # measure what --window actually costs

Worth saying before you install it, because the numbers above are all from one machine:

• Every benchmark here is n=1, on one laptop, with early-silicon NPU drivers. The GPU and CPU fallbacks have run on this laptop's Xe3 iGPU and Core 5 320 and nowhere else, and 2 of 15 GPU model loads segfaulted inside OpenVINO's GPU plugin.
• Captions trail the audio by roughly twice the cycle time. That is inherent to a two-cycle commit policy, not a bug to be tuned away. docs/latency.md explains the one knob that moves it.
• Wording drifts between cycles, because each window is re-decoded with more right-context than the last. The stitcher hides most of it and not all.
• The overlay needs wlr-layer-shell. Tested on KDE Plasma 6.7 only. GNOME does not offer the protocol, so there the overlay refuses to start and the terminal UI is the way in. Sway, Hyprland, niri and COSMIC should work and are untested.
• Dictation pastes into whatever has focus. Wayland does not say what that is, so it cannot check, and the clipboard is cleared after each paste. The paste keys come from /dev/uinput when udev lets you open it, else the compositor's virtual keyboard (Sway, Hyprland, niri, COSMIC, KWin), else the desktop portal, and KDE then posts a notification for every dictation. The virtual-keyboard route has not been tried on a live compositor yet.
• Only Fedora's package names have been used for real. The other seven families come from their package indexes. If one is wrong for yours, that is expected, and it is the fastest thing in this repo to fix. The PulseAudio capture backend has never run against a real PulseAudio server either.
• The NPU export needs transformers<5.4. Bisected on hardware 2026-09-04: 5.4.0 and up produce a graph that compiles and then fails at generate() with Port for tensor name cache_position was not found. The vinowhisper[export] extra holds the pin, so the wizard's export is fine, but an optimum-cli installed some other way is not. That pinned version carries two open transformers CVEs; both need you to export a malicious model repo, which the default openai/whisper-small.en is not. docs/install.md has the bisect table.

• CONTRIBUTING.md, where the useful contributions are distro corrections and reports from hardware that isn't this laptop
• SECURITY.md, what stays on the machine and what the loopback server's trust boundary actually is
• CHANGELOG.md

If you run this on hardware that isn't a Wildcat Lake laptop, I want the report, working or not. That is the one thing I cannot test myself, and an issue with vinowhisper-doctor --json pasted into it is worth more than any benchmark I can run here.

MIT licensed.