Skip to content
Docs0.9GitHubInstall

Using itVoice notes and dictation

Transcription and dictation

The speech plugin (vendetta-speech) offers one speech-to-text service to the other plugins. Messaging uses it for Telegram, Discord, app, and web voice notes, and dictation for everything you say into a shortcut. Pick a provider in [plugins.speech.transcription]; each provider’s other keys are its own:

[plugins.speech.transcription]
provider = "command"   # command | elevenlabs | chatgpt | codex-lb
command = ["/home/YOU/.local/bin/transcribe"]  # such as a whisper.cpp wrapper
# language = "en"      # omit for automatic detection; codex-lb has no such key
# timeout_seconds = 60 # 1–300, for each part of a recording
Provider What it needs
command command: literal argv of a local program that reads a 16-bit mono WAV recording on stdin and prints the transcript. VENDETTA_TRANSCRIPTION_LANGUAGE carries language.
elevenlabs token: an ElevenLabs API key, such as { command = ["pass-cli", "item", "view", "pass://SHARE_ID/ITEM_ID/password"] }; optional model (default scribe_v2).
chatgpt token: a ChatGPT subscription access token (Codex’s login, such as { command = ["omp", "token", "openai-codex"] }), read for each recording. Uses Codex’s dictation endpoint, never the paid API.
codex-lb endpoint, such as http://127.0.0.1:2455/backend-api/transcribe; optional token (the proxy key) and prompt. A remote endpoint must use HTTPS and needs a token and allow_remote = true.

A recording can be up to 32 MiB of Ogg or WebM Opus, M4A, MP3, or WAV, and up to 30 minutes; a caller can ask for less, and longer audio is cut there rather than refused. It goes to the service in parts of about two minutes, each ending at a pause, one after another, all within ten minutes; if any part fails, the whole recording does. Formats other than 16-bit mono WAV are converted with ffmpeg on Linux and refused elsewhere. Nothing is retried, and neither the plugin nor the worker keeps audio or transcripts; dictation keeps a recording only until its text is delivered (kept dictations).

A person’s Vendetta (instance) whose own speech plugin lacks transcription or narration, or who runs none, uses yours, through your worker over its link to yours: your keys and tokens never leave your account. That is on unless you turn it off for them (vendetta instance update NAME --services own, or the switch on the apps’ People screen); their own [plugins.speech] transcription or narration, if they set one, wins. Their voice notes are transcribed by your service, and replies are read aloud in your narration voice, piece by piece. A rewrite for listening is their app plugin’s own setting.

Your worker serves only people your registry gives voice: one transcription at a time for each person, recordings up to 16 MiB, two readings open for each, closed after two idle minutes, pieces of at most 4,500 characters and 40,000 in a reading. It keeps and logs neither audio nor text, and retries nothing; if your worker cannot be reached, their voice notes are refused, as they would be without a service. Their Vendetta asks again every 10 seconds, so voice turns on for their apps once their link to you is up, whichever worker started first, and off when you stop giving it, with no restart.

The app’s Listen and voice mode read replies with the speech plugin’s voice; without one, the phone reads them with its own. Replies are read in pieces of up to 4,500 characters, so playback starts after the first sentence.

A local program reads aloud with provider = "command". It gets each piece’s text on stdin and writes MP3: to stdout, or to the file an {output} argument names. Each piece must finish within timeout_seconds and be at most 16 MiB of audio; other output is refused. With Piper and ffmpeg:

[plugins.speech.narration]
provider = "command"
command = ["/home/YOU/.local/bin/speak", "{output}"]
# timeout_seconds = 60   # 5–300, for each piece
#!/bin/sh
# ~/.local/bin/speak: text on stdin, MP3 to $1.
piper --model "$HOME/.local/share/piper/en_US-amy-medium.onnx" --output-raw |
  ffmpeg -loglevel error -f s16le -ar 22050 -ac 1 -i - -y -f mp3 "$1"

ElevenLabs reads with a voice from your account, each piece carrying its intonation on from those before. Its key is read at the start of each reading.

[plugins.speech.narration]
provider = "elevenlabs"
token = { command = ["pass-cli", "item", "view", "pass://SHARE_ID/ITEM_ID/password"] }
voice = "JBFqnCBsd6RMkjVDRZzb"   # ElevenLabs voice ID
# model = "eleven_multilingual_v2"
# timeout_seconds = 60           # 5–300, for each piece

A small model can first rewrite each reply for listening, as the reading starts. The app plugin runs it: a preset runs the provider’s CLI without your hooks, plugins, MCP servers, rules, or sessions; a command reads the instructions and reply on stdin and prints the text to read.

[plugins.app.narration.rewrite]
provider = "claude"   # claude | codex | omp; or command = [...] instead
model = "haiku"
effort = "low"        # minimal | low | medium | high
# timeout_seconds = 30  # 5–120

Press a shortcut and talk; press it again and the transcript goes to the agent in the window you were in, submitted as a prompt, or with no terminal focused, to the agent you used last. A terminal without an agent gets it pasted. Either way it is also on the clipboard. The dictation plugin records the microphone, transcribes through the speech plugin’s transcription, and submits through the worker with the same input checks as messaging; a desktop frontend copies and pastes. Vendetta ships a Hyprland frontend, and a macOS app that transcribes on the Mac and always pastes.

A recording can run for half an hour (max_seconds). Past a few minutes it is transcribed in parts, each ending at a pause, while you keep talking, so the text is ready soon after you stop.

The agent is the one in the pane the focused terminal shows as recording starts, through whichever host runs there (tmux, Kitty, or tmux inside Kitty), or running in the terminal outside every host. With another app focused, such as a browser, it is the one in the pane of the terminal used most recently. When several agents could be it, or that pane has none, the transcript is pasted; delivery = "paste" always pastes. vendetta-dictation toggle --master sends to Master instead, whatever has focus.

The frontend needs hyprctl and wl-copy, on a Hyprland with the Lua API (hyprctl eval). The recording shows in the desktop HUD, so enable [plugins.hud] too; install.sh builds both when GTK layer shell is installed. Dictation offers dictation:toggle, dictation:master, while it records or transcribes dictation:cancel, and while a failed dictation is kept dictation:retry; the shortcuts plugin gives them keys. Enable both:

[plugins.dictation]
# delivery = "paste"               # always paste; default "agent"

[plugins.dictation.frontend]
command = ["vendetta-dictation-hyprland"]
# paste_modifiers = "CTRL"                   # paste in most windows
# terminal_paste_modifiers = "CTRL SHIFT"     # paste in a terminal
# terminal_window_classes = ["kitty", "foot"] # replaces the built-in list of common terminals
# blocked_window_classes = ["org.keepassxc.KeePassXC"]
# allow_multiline_paste = false

[plugins.shortcuts]
[plugins.shortcuts.keys]
"dictation:toggle" = "super+d"          # start, or stop and send
"dictation:master" = "super+shift+d"    # the same, for Master
"dictation:cancel" = "escape"           # only while recording or transcribing
"dictation:retry" = "super+shift+r"     # only while a failed dictation is kept

# [plugins.dictation.recording]
# device = "pipewire:alsa_input.usb-Mic"   # from `vendetta-dictation devices`
# max_seconds = 1800                       # up to 7200

A changed key applies within a second. To hold to talk instead, bind vendetta-dictation start to a key’s press and vendetta-dictation stop to its release in Hyprland yourself.

The HUD’s dictation card, first in its column unless placed, shows the recording and where the transcript will go; typing stays where it was. Press the shortcut again to finish, or Escape to discard the recording: the dictation:cancel key is bound only while it records or transcribes, and does nothing else meanwhile. The card stays until the agent has the transcript and says Sent; when the agent is working, it adds that the agent reads it after its current step. A failed session shows why, and the card leaves on its own. Each session’s timings go to the worker’s log: transcription after the stop, then the handover, split into reading the agent’s state and the worker’s send_message. A paste goes only into the window that had focus when recording began, and not when focus changed, for multiline text, or into a blocked class. vendetta-dictation status shows the plugin’s state; vendetta-dictation-hyprland doctor checks that hyprctl and wl-copy are there.

A recording stays on disk until its text is delivered, so a dictation that fails is not lost: when transcription fails or times out, the frontend goes away, the agent refuses it or is gone, the worker does not confirm the prompt, or the worker stops mid-recording, the card says Kept to send again and why. When transcription fails while you are still talking, recording goes on, and all of it is kept.

vendetta-dictation retry, or the dictation:retry key, transcribes what was not transcribed yet and sends the newest kept dictation where it was meant to go: the same agent, found by its conversation, through the usual input checks; Master for --master; the clipboard for one that was to be pasted. An agent that cannot take it leaves the text on the clipboard, and the recording stays. Nothing is sent again on its own. When the worker did not confirm the last delivery, it may have arrived: retry says so, and sends only when you retry again within 10 seconds.

vendetta-dictation kept lists them, newest first: name, time, length, where to, and why. retry NAME sends one, and discard NAME deletes it. They live in $XDG_STATE_HOME/vendetta/dictation (~/.local/state/vendetta/dictation), a private directory of the recording’s WAV segments and the text of those already transcribed; the newest 20 stay, up to 1 GiB in all, for a week. The macOS app’s sessions keep theirs there too, and kept lists them.

Vendetta ships dictation frontends for Hyprland and macOS only. A frontend for another desktop is any program [plugins.dictation.frontend] command names. The plugin starts it for each session with the shortcut’s environment; the table’s other keys reach it as JSON in VENDETTA_DICTATION_SETTINGS, and VENDETTA_DICTATION_PLUGIN names the plugin’s executable, whose cancel subcommand a key can run. They talk one JSON object per line over the frontend’s stdin and stdout, each line at most 256 KiB.

From the plugin:

Line Meaning
{"type":"event","event":EVENT} What to show. EVENT has a phase: listening with recording_ms, input_level (0–1000), and message (or null); transcribing; sending with agent, the name it goes to; completed with title and message; error with message, and kept, the kept recording’s name, when there is one; canceled.
{"type":"request","id":N,"request":{"kind":"release_keyboard"}} Give the keyboard back to the window that had focus as recording began. Answer within half a second, or the transcript only goes onto the clipboard.
{"type":"request","id":N,"request":{"kind":"deliver","transcript":TEXT,"intent":INTENT}} Put TEXT on the clipboard, and with intent captured_target also paste it into the window that had focus as recording began; clipboard_only copies only. Answer within 15 seconds.
{"type":"finished","ok":BOOL} The session ended. Show the ending, then exit; the plugin closes stdin and ends the frontend after 5 seconds.

From the frontend:

Line Meaning
{"type":"focus","pid":PID} Once, at the start: the process of the window that had focus. The plugin submits to the agent that window shows.
{"type":"control","control":C} start, stop, toggle, or cancel.
{"type":"response","id":N,"ok":BOOL,"outcome":O,"error":TEXT} The answer to request N. A delivery’s outcome is pasted, copied, focus_changed, multiline, blocked, or target_unavailable; all but pasted leave the text on the clipboard. error says why when ok is false.

Unknown fields in the frontend’s lines are refused. Never log a transcript. A display, such as the HUD, follows the worker’s dictation events instead; see docs/protocol.md.