overlay
diapason.desktop.overlay
¶
The floating dictation indicator — proof that the key was heard.
A menu-bar glyph changing from 🎙 to 🔴 is technically feedback, but it is 20 pixels away from where you are looking and it does not move. When you hold a key and speak into a machine that gives no answer, the question is never "which icon is showing" — it is "is this thing listening to me right now?". So the indicator sits above the Dock, in the middle of the screen, and its bars move with your voice: it answers the real question, because a bar that responds to sound proves the microphone is genuinely open, not merely that a code path was entered.
Two constraints shape everything here:
- It must never steal focus. Dictation ends by sending Cmd+V to the
frontmost app; a panel that activates would make itself frontmost and the
text would land in the void. Hence a non-activating
NSPanelthat ignores mouse events entirely and is ordered front "regardless". - It must never touch AppKit off the main thread. Levels and state changes arrive on the audio and key-tap threads. Rather than marshal each one, those threads only assign to plain attributes; a main-thread timer reads them and does all the drawing. One direction, no locks, no dispatch.
The geometry — how tall each bar is for a given level — is pure and tested.
Only :class:DictationOverlay touches a window server.
DictationOverlay
¶
The live panel. Import-safe: AppKit is only touched in start().
Call :meth:set_state and :meth:set_level from any thread.
bar_heights(level, *, state='recording', phase=0.0, bars=BARS)
¶
Height of each bar, 0–1, for a level and animation phase.
phase advances one full cycle per second; it is what keeps the bars
alive while the level is steady. Unknown states render as idle rather
than raising — an indicator is never worth crashing dictation over.
normalized_level(level)
¶
Map an RMS level (0–100 scale) onto 0–1 with a usable curve.
overlay_page()
¶
Where the bundled entity page lives inside the package.
state_for_status(message)
¶
Map a DictationService status line onto an overlay state.
The service speaks in human sentences ("captured 2.3s (level 1.4)"); the overlay has four faces. Keeping the mapping here means the status strings stay free to change wording without breaking the UI.