Skip to content

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 NSPanel that 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.

on_status(message)

Adapter for DictationService(on_status=…).

set_bands(bands)

Per-band energies, 0–1, low frequencies first.

start()

Create the panel and begin the animation timer. False if no GUI.

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.