Main Dictation Overlay Window in OpenWhispr: Purpose, Architecture, and Implementation

The main dictation overlay window in OpenWhispr is an always-on-top, content-protected Electron BrowserWindow that provides a minimal, privacy-aware capture interface for voice dictation while remaining isolated from the application's main Control Panel.

OpenWhispr employs a dual-window architecture to balance rich configuration capabilities with unobtrusive voice capture. The main dictation overlay window serves as the floating interface that appears when users trigger dictation hotkeys, designed to stay visible above all other applications while preventing sensitive UI elements from leaking into AI screen context requests.

Dual-Window Architecture Overview

OpenWhispr separates its interface into two distinct surfaces. The Control Panel handles settings, history, and model management as a standard application window. The dictation overlay operates as a specialized, lightweight surface that owns its own BrowserWindow instance in Electron.

This separation allows the overlay to maintain always-on-top status without interfering with the main application's state. According to the source code in src/helpers/windowManager.js, the overlay coordinates with other potential overlays—such as meeting notifications or onboarding demos—through a "one-overlay-at-a-time" rule system managed by the window manager.

Core Responsibilities of the Dictation Overlay

Always-On-Top Capture Interface

The overlay displays the Agent Dictation Pill—a compact UI component rendered in src/components/dictation/AgentDictationPillOverlay.tsx—that indicates active listening status. Because the overlay is a separate Electron window rather than a modal or panel within the main app, it can be positioned anywhere on screen without being obscured by other applications.

The component mounts through src/AppRouter.jsx, which coordinates the routing of overlay-specific components separately from the main application UI. Styling in src/styles/dictation-panel.css ensures the pill remains visually distinct yet unobtrusive during dictation sessions.

Content Protection and Privacy

The overlay is explicitly marked as content-protected, a critical privacy feature that prevents the built-in screen-context capture system from including the overlay in screenshots sent to vision-enabled AI models. This ensures that the application's own UI does not leak into AI requests, maintaining user privacy during sensitive dictation workflows.

As implemented in the window configuration logic, this protection applies at the operating system window level, meaning screen capture APIs exclude the overlay surface entirely while still capturing the underlying applications the user is working with.

Lightweight Interaction Model

Unlike the Control Panel, which hosts the note editor and complex settings, the dictation overlay handles only essential feedback: recording state indicators, audio level visualizations, and error toasts. This minimal surface area keeps the overlay fast and responsive, ensuring it does not consume resources or distract from the user's primary workflow while capturing audio input.

Isolation from Other Overlays

OpenWhispr may display multiple overlay types simultaneously—including meeting notifications, update notices, and onboarding demos. The dictation overlay maintains its own BrowserWindow instance to prevent conflicts with these secondary interfaces. The window manager in src/helpers/windowManager.js specifically coordinates focus handling, ensuring the dictation overlay hides gracefully during onboarding sequences when another overlay requires user attention.

Cross-Platform Window Policies

Platform-specific behavior is abstracted through resolveOverlayWindowType in src/helpers/windowConfig.js. This function returns appropriate window configurations for each operating system:

• macOS: Uses a normal window type that respects the platform's always-on-top policies
• Linux Wayland: May utilize GNOME overlay policy when available in the session
• Windows: Configures a frameless, top-most window that sits above other application chrome

This abstraction allows the overlay to behave consistently across platforms while respecting each OS's window-management quirks and security policies.

Technical Implementation

Creating the Overlay Window

The overlay is instantiated from the main process using platform-specific window types:

// Create the dictation overlay (called from main process)
import { BrowserWindow } from "electron";
import { resolveOverlayWindowType } from "./helpers/windowConfig";

export function createDictationOverlay() {
  const win = new BrowserWindow({
    ...resolveOverlayWindowType({ role: "main", platform: process.platform, linuxSession: getLinuxSessionInfo() }),
    webPreferences: { contextIsolation: true, preload: "./preload.js" },
  });
  win.loadURL("app://-dictation"); // loads the pill UI
  return win;
}

Handling Global Hotkeys

The overlay visibility is controlled through the window manager when global hotkeys trigger:

// Show the overlay when the global hotkey fires
import { useHotkeyRegistration } from "./hooks/useHotkeyRegistration";

function DictationHotkeyHandler() {
  const startDictation = () => {
    windowManager.showDictationOverlay(); // makes the pill visible & starts audio capture
  };
  useHotkeyRegistration("dictation", startDictation);
}

Managing Overlay Lifecycle

After transcription completes, the window manager dismisses the overlay to return focus to the user's active application:

// Hide the overlay after transcription finishes
import { useAudioRecording } from "./hooks/useAudioRecording";

function useDictationLifecycle() {
  const { stopRecording, transcript } = useAudioRecording();

  useEffect(() => {
    if (transcript) {
      windowManager.hideDictationOverlay(); // pill disappears, overlay window may be closed
    }
  }, [transcript]);
}

These patterns demonstrate the overlay's role as a transient, dedicated surface that activates only during active dictation sessions, managed entirely through the windowManager API.

Summary

• The main dictation overlay window in OpenWhispr is a separate Electron BrowserWindow that remains always-on-top for unobtrusive voice capture.
• It is content-protected to prevent its UI from appearing in screenshots sent to AI models, safeguarding user privacy.
• The overlay displays only the Agent Dictation Pill for lightweight interaction, while complex UI resides in the separate Control Panel.
• Platform-specific policies in windowConfig.js ensure consistent behavior across macOS, Linux Wayland, and Windows.
• The windowManager.js coordinates overlay states to prevent conflicts with meeting notifications and onboarding demos.

Frequently Asked Questions

How does the main dictation overlay window differ from the Control Panel?

The Control Panel is a full-featured application window for settings, history, and model management, while the dictation overlay is a minimal, always-on-top surface that appears only during active dictation. The overlay handles only essential feedback (recording state, audio levels) and owns its own BrowserWindow instance to remain independent from the main application's focus state.

Why is the dictation overlay marked as content-protected?

The content-protected flag prevents the overlay from appearing in screenshots captured by OpenWhispr's screen-context feature. Since the app can send screen captures to vision-enabled AI models, this protection ensures the application's own UI elements—like the dictation pill—do not leak into AI requests, maintaining clean context windows and user privacy.

How does OpenWhispr handle multiple overlays simultaneously?

The windowManager.js implements a "one-overlay-at-a-time" coordination system. While the dictation overlay owns its own BrowserWindow, the window manager tracks focus states to hide the dictation interface when meeting notifications or onboarding demos require user attention, preventing visual clutter and focus conflicts.

What platforms support the specialized overlay window type?

All major platforms are supported through the resolveOverlayWindowType function in windowConfig.js. macOS uses standard always-on-top windows, Windows employs frameless top-most windows, and Linux Wayland sessions may leverage GNOME overlay policies when available in the current session environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}