main ff0f6cb

Push-to-talk dictation for Wayland: speak, see a level overlay, get the transcript typed into the focused window.

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_v1 with 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.

License

GNU Affero General Public License v3.0.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 1

Tags 1

↑↓ moveenter openesc close