Recording Overlay (On-Screen Display)

The Recording Overlay provides an immediate, cross-platform visual indicator of dictation status. It operates independently of desktop notification daemons and “Do Not Disturb” filters, displaying the state directly on the primary screen.

Visual Examples

Bottom-Left (bl)

Top-Right (tr)

Top-Right Overlay 1

Top-Right Overlay 2

Blends into dark panels and system trays

High contrast over light or complex windows

States

  • Recording (🔴): A vivid red circle with a highlighted outline (#e62222 on #181818) signals active audio recording.

  • Idle:

    • hidden (default): The window is completely withdrawn, freeing desktop space for normal interaction.

    • pentagon: Displays a subtle geometric pentagon badge (⬟) during idle mode.

Configuration

Settings are managed in config/settings.py:

# Enable/disable on-screen overlay
RECORDING_OVERLAY_ENABLED = True

# Keep window always on top without borders
RECORDING_OVERLAY_TOPMOST = True

# Placement: "tr" (top-right) or "bl" (bottom-left)
RECORDING_OVERLAY_POSITION = "tr"

# Inactivity mode: "hidden" or "pentagon"
RECORDING_OVERLAY_IDLE_MODE = "hidden"

# Window dimension in pixels
RECORDING_OVERLAY_SIZE = 36

Architecture

  • Built using the Python standard library (tkinter), requiring zero external C-dependencies.

  • Executes in a background daemon thread with thread-safe queue event handling.

  • Dynamically detects the primary monitor in multi-display environments.

(s, 10.9.’26 14:41 Thu)