nefervox
Push-to-talk dictation for Wayland. Press a key to talk: a small overlay shows the microphone level. Press it again: the audio goes to a speech-to-text provider and the text is typed into the focused window.
- Overlay: a click-through layer-shell pill drawn with NeferGUI; it never takes focus.
- Typing:
zwp_virtual_keyboard_v1with a keymap built from the transcript, so accents,',~,^and non-Latin text come out exactly, whatever the keyboard layout or dead keys. Line breaks become spaces. - If typing fails, the text goes to the clipboard (
wl-copy). - Audio:
pw-record, 16 kHz mono, kept in memory.
Usage
nefervox # start, or stop and type
nefervox cancel # discard the running dictation
nefervox login [P] # log in to provider P (default: the configured one)
nefervox logout P
nefervox providers # providers and login state (* = configured)
nefervox transcribe a.wav
nefervox type "texte" # type text into the focused window
nefervox version
NeferWL binds:
bind.cmd+v = spawn nefervox
bind.shift+cmd+v = spawn nefervox cancel
Logs: ~/.local/state/nefervox/nefervox.log (never the transcript).
Providers
| Name | nefervox login |
Without a login | Notes |
|---|---|---|---|
chatgpt (default) |
ChatGPT account in the browser (Codex OAuth, callback on localhost:1455) |
zut's ChatGPT login (~/.local/state/zut/auth.json) |
ChatGPT's private dictation endpoint; OpenAI keeps audio 30 days. |
openai |
API key, typed without echo | $OPENAI_API_KEY (name set by openai.api-key-env), which wins over the stored key |
/audio/transcriptions; any compatible endpoint through openai.base-url. |
Logins live in ~/.local/state/nefervox/auth.json (mode 0600). Expired OAuth tokens are refreshed and saved before use.
Configuration
~/.config/nefervox/config, every key optional:
provider = chatgpt
language = fr # empty: auto-detect
output = type # or clipboard
max-duration = 5m
timeout = 60s
typing = natural # phrases flow, random pauses only after , ; : . ! ? …; or instant
typing.max-duration = 1.5s # natural typing never takes longer (unless type-delay forces it)
type-delay = 2ms # pause between keys; the shortest one when natural
trailing-space = true # space after each dictation, so two in a row don't stick
overlay.position = bottom # or top
prompt = # vocabulary hint (openai)
openai.model = gpt-4o-transcribe
openai.base-url = https://api.openai.com/v1
openai.api-key-env = OPENAI_API_KEY
# recorder = cmd,arg,... # must write raw s16le mono 16 kHz to stdout
Architecture
Hexagonal: internal/core runs a dictation through the interfaces in internal/ports; types live in internal/domain; internal/adapters implement the ports.
Adding a provider: a package under internal/adapters/stt/ implementing ports.Transcriber (multipart APIs reuse stt/upload), plus one stt.Providers entry giving its transcriber and its ports.Authenticator (credentials/apikey covers API keys).
Development
make check # vet + race tests
make mocks # regenerate port mocks (mockery)
make install # ~/.local/bin/nefervox
make go-install # $GOBIN, or $GOPATH/bin
Requires Go 1.27, pw-record, Vulkan with DMA-BUF (NeferGUI), and a compositor with zwp_virtual_keyboard_v1 and zwlr_layer_shell_v1.