Dictate anywhere from the i3bar tray
Most Linux applications have no dictation feature. dictate-tray is a tray icon for i3bar that adds one to all of them: click it, speak, click again, and the text is on the clipboard. Paste works everywhere, so dictation works everywhere: browser, editor, chat, terminal.
Transcription runs locally with Whisper. No audio leaves the machine. It is one Python file, about 500 lines.
Use
exec --no-startup-id dictate-tray
bindsym $mod+Shift+d exec --no-startup-id dictate-tray toggle
Press the binding, talk, press it again, paste. The icon says what is happening:
| Icon | State |
|---|---|
| grey mic | idle |
| amber mic | microphone opening, not capturing yet |
| red with bars | recording, bars are the live input level |
| orange with bars | stop pressed, capturing the last 400 ms |
| blue spinner | transcribing |
| green check | text is on the clipboard |
| yellow exclamation mark | failed, hover for the reason |
Left click toggles. Right click gives Cancel recording and Quit.
The Whisper model loads when the first recording starts, so it warms up while you talk. It stays loaded for back-to-back dictations and unloads after 60 idle seconds. With tiny on CPU the loaded worker holds about 0.8 GB of RAM, and nothing when idle.
Dependencies
X11 only. Arch:
sudo pacman -S python-gobject python-cairo python-numpy gtk3 libpulse xsel libnotify
pipx install openai-whisper
Debian: python3-gi python3-gi-cairo gir1.2-gtk-3.0 python3-cairo python3-numpy pulseaudio-utils xsel libnotify-bin.
Build spec
The rest of this post is the spec. It is written so that you, or a coding agent pointed at this URL, can rebuild the script without the source.
Shape
- One executable file,
dictate-tray, shebang#!/usr/bin/python3, installed to~/.local/bin. - Python standard library plus PyGObject (GTK 3), pycairo, numpy. External commands:
parec,xsel, optionalnotify-send. - Three entry points in
main():- no arguments: run the tray. Exit with a message if an instance is already running.
toggle: sendSIGUSR1to the running instance. Exit with an error if none is running.--worker <model>: run the Whisper worker loop. Internal, started by the tray.
- Configuration from environment:
DICTATE_MODEL(defaulttiny),DICTATE_DEVICE(cpuorcuda, defaultcpu),DICTATE_IDLE(seconds before unloading the model, default60). - Import GTK, cairo, and whisper inside the functions that use them, not at module top. The tray process must never import whisper, and the worker must never import GTK.
Two interpreters
The tray needs the system Python, because that is where PyGObject lives. Whisper usually lives in a pipx venv. The script bridges them by re-running itself as a worker under Whisper's interpreter, which it reads from the shebang of the whisper command:
def whisper_python():
exe = shutil.which("whisper")
if exe:
try:
with open(exe, "rb") as fh:
first = fh.readline().decode().strip()
if first.startswith("#!"):
return first[2:].split()[0]
except OSError:
pass
return sys.executable
The tray starts the worker with [whisper_python(), os.path.abspath(__file__), "--worker", MODEL], pipes for stdin and stdout, text mode, and stderr appended to ~/.cache/dictate-tray.log.
Worker protocol
Line-delimited JSON over stdout, file paths over stdin. Whisper and torch print to stdout, which would corrupt the protocol, so the worker first moves the real stdout to a private file descriptor and points fd 1 at stderr:
def worker_main(model_name):
out = os.fdopen(os.dup(1), "w")
os.dup2(2, 1)
import numpy as np
import whisper
device = DEVICE
try:
model = whisper.load_model(model_name, device=device)
except Exception:
device = "cpu"
model = whisper.load_model(model_name, device=device)
out.write(json.dumps({"ready": device}) + "\n")
out.flush()
for line in sys.stdin:
path = line.strip()
if not path:
continue
try:
audio = np.fromfile(path, dtype=np.int16).astype(np.float32) / 32768.0
result = model.transcribe(
audio, language="en", fp16=(device == "cuda"),
condition_on_previous_text=False)
reply = {"text": " ".join(result["text"].split())}
except Exception as exc:
reply = {"error": str(exc)}
out.write(json.dumps(reply) + "\n")
out.flush()
Passing a float32 numpy array to transcribe skips ffmpeg entirely. The input file is raw 16 kHz mono signed 16-bit PCM, no header.
The tray side is a Worker class with a lock around transcribe(path):
- Start the process if it is not running.
- If the
readyline has not been read yet, read it. - Write the path and a newline, flush, read one reply line.
- Record
last_use. Raise on{"error": ...}, returntextotherwise. - An empty read means the worker died. Raise
whisper worker died, see <log path>.
start() is also called at the moment recording begins, without waiting for ready, so the model loads while the user speaks. A GLib timer every 15 seconds terminates the worker when the tray is idle and last_use is older than DICTATE_IDLE.
Recording
subprocess.Popen(
["parec", "--raw", "--format=s16le", "--rate=16000",
"--channels=1", "--latency-msec=30",
"--client-name=dictate-tray"],
stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
A daemon thread reads parec stdout with os.read(fd, 4096) until EOF, appending to a buffer. For each chunk it computes the peak absolute sample (as int32, to avoid overflow on -32768) divided by 32768 and keeps the maximum in a shared peak attribute. After EOF it trims the buffer to an even byte count and hands it to the main loop with GLib.idle_add.
Details that matter:
- Amber state.
parectakes a moment to open the microphone, and words spoken in that gap are lost. The state isSTARTINGuntil the first chunk arrives, thenRECORDING. The icon colour tells you when to start talking. - Tail. A stop click sets
FINISHINGand terminatesparec400 ms later withGLib.timeout_add. Without the tail, the last word gets clipped. - Generation counter. Every new recording and every cancel increments an integer. Each thread callback carries the generation it started with and is ignored if it no longer matches. This is what makes cancel safe.
- If
parecexits while the state is stillSTARTINGorRECORDING, fail withRecording stopped unexpectedly (no microphone?). - Under 0.3 seconds of audio, fail with
Recording too short.
Transcribe and copy
In another daemon thread: write the PCM to a temp file in $XDG_RUNTIME_DIR, call worker.transcribe(path), fail with No speech recognised on empty text, pipe the text to xsel --clipboard --input, delete the temp file in a finally. Report back to the main loop with GLib.idle_add. All GTK calls happen on the main loop, never in a thread.
On success, show the green check for 2.5 seconds and send a notification with the text. On failure, show the error icon for 4 seconds and send the reason. The notification uses a replace hint so repeated dictations do not stack:
notify-send -a Dictate -t 3000 -h string:x-canonical-private-synchronous:dictate "Copied to clipboard" "$text"
State machine
IDLE, STARTING, RECORDING, FINISHING, TRANSCRIBING, DONE, ERROR.
- Toggle from
IDLE,DONE, orERRORstarts a recording. - Toggle from
STARTINGorRECORDINGstops it. - Toggle during
FINISHINGorTRANSCRIBINGis ignored. - Cancel is valid in
STARTING,RECORDING,FINISHING. It bumps the generation, terminatesparec, and returns toIDLE.
Tray icon
Gtk.StatusIcon. Deprecated, but it is the XEmbed tray icon that i3bar accepts.activateis left click,popup-menuis right click,size-changedreports the pixel size to draw at.- Draw every icon with cairo onto an
ImageSurfaceat that size, thenicon.set_from_pixbuf(Gdk.pixbuf_get_from_surface(surface, 0, 0, s, s)). No image files. - Idle is a light grey mic glyph on a transparent background. Every other state is a rounded square of the state colour with a white glyph: mic, level bars, a 270 degree arc rotating with the tick counter, a check mark. The error icon is a yellow exclamation mark on dark grey.
- An 80 ms GLib timer drives animation. During capture states it takes the shared
peak, resets it to zero, converts to decibels, maps -50 dB..0 dB onto 0..1, appends to adeque(maxlen=32), and redraws. Bars are 2 or 3 pixels wide, vertically centred, newest on the right. - Set the tooltip on every redraw: recording duration while recording, last result or error otherwise.
- Keep a reference to the popup
Gtk.Menuon the object. Otherwise it is garbage collected before it shows.
Single instance and toggle
- Write the pid to
$XDG_RUNTIME_DIR/dictate-tray.pidat startup. - An instance counts as running only if that pid exists and
/proc/<pid>/cmdlinecontainsdictate-tray. This survives stale pid files. - Handle signals with
GLib.unix_signal_add, not thesignalmodule, so handlers run on the GTK main loop.SIGUSR1toggles and returnsTrueto stay installed.SIGINTandSIGTERMterminateparec, stop the worker, remove the pid file, and quit.
Acceptance checks
dictate-tray &shows a grey mic in the i3bar tray. A seconddictate-trayexits withalready running.dictate-tray toggleturns the icon amber, then red, and the bars move when you speak.- A second toggle goes orange, blue, green, and
xsel --clipboard --outputprints what you said. - Right click, Cancel recording mid-sentence returns to grey and leaves the clipboard untouched.
- After 60 idle seconds,
pgrep -f 'dictate-tray --worker'prints nothing. - With
whisperinstalled through pipx and no whisper module in/usr/bin/python3, all of the above still works.