vinoWhisper

NPU-accelerated local live captioning for Linux, using OpenVINO GenAI's WhisperPipeline on an Intel NPU. Named after vinoAuthFace, same idea of OpenVINO doing the NPU work, different feature.

Point it at whatever is playing and it captions in your terminal. Nothing leaves the machine. Start it and it goes; there is nothing to interact with.

The transcript scrolls above that bar in your terminal's own scrollback, so it is still there after you quit and your terminal's selection and search still work on it. hearing… is the words heard once but still waiting on a second cycle to agree, which is the two-cycle commit delay made visible rather than felt as a freeze.

Install

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 the paths that actually exist. It prints every command before running it and asks first.

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

git clone https://github.com/karanshukla/vinoWhisper && cd vinoWhisper
uv sync
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 five 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.

Commands

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-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-doctor                        # devices, model, 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

Hardware

The NPU is the point. Everything below it exists so a broken driver degrades the tool instead of bricking it.

Selection is automatic 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. The two model exports are not interchangeable, and the NPU needs a userspace driver half that no distro packages completely. docs/hardware.md covers all of it, including what to do when the NPU does not show up.

Audio capture works on PipeWire (pw-record) or PulseAudio (parec), picked automatically, and package names for eight distro families live in one table in vinowhisper/distro.py. If a name is wrong for your distro, that is expected, and it is the fastest thing here to fix.

Docs

More

• Design doc, benchmarks, and the three export bugs hit getting to a working NPU pipeline: wildcat-lake-linux/input/f5-voice-typing.md
• 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

MIT licensed.