How the Control Panel Window Differs from the Dictation Overlay in OpenWhispr

The Control Panel window functions as a full-featured configuration interface with standard window decorations and navigation, while the dictation overlay operates as a frameless, always-on-top, privacy-protected surface optimized solely for real-time speech capture.

OpenWhispr employs a dual-window architecture to cleanly separate application configuration from active dictation workflows. Understanding how the Control Panel window differs from the dictation overlay reveals the sophisticated design philosophy behind this Electron-based voice interface. Both windows are instantiated by the main process in src/helpers/windowManager.*, yet they exhibit fundamentally distinct BrowserWindow configurations, React component hierarchies, and security postures.

BrowserWindow Configuration and Visual Properties

The two windows diverge immediately at the Electron main process level, where each is constructed with purpose-specific options.

Control Panel Window Attributes

The Control Panel is created as a standard desktop window via createControlPanel() in src/helpers/windowManager.ts. It utilizes frame: true, appears in the taskbar, supports resizing, and does not enable content protection. This allows screen-sharing tools to capture the settings interface when users need to demonstrate configuration steps.

// src/helpers/windowManager.ts
export function createControlPanel(): BrowserWindow {
  return new BrowserWindow({
    title: "OpenWhispr – Settings",
    width: 1200,
    height: 800,
    show: false,
    frame: true,
    resizable: true,
    skipTaskbar: false,
    webPreferences: { preload: PRELOAD_PATH },
  });
}

Dictation Overlay Attributes

In contrast, the dictation overlay is instantiated through createDictationOverlay() with aggressive minimalism and privacy safeguards. The configuration sets frame: false, transparent: true, alwaysOnTop: true, and contentProtection: true. These options ensure the overlay remains invisible to screen-recording utilities while floating above all other applications.

// src/helpers/windowManager.ts
export function createDictationOverlay(): BrowserWindow {
  return new BrowserWindow({
    title: "OpenWhispr – Dictation",
    width: 320,
    height: 80,
    frame: false,
    transparent: true,
    alwaysOnTop: true,
    skipTaskbar: true,
    resizable: false,
    focusable: false,
    contentProtection: true,
    webPreferences: { preload: PRELOAD_PATH },
  });
}

UI Implementation and Component Architecture

The visual implementations reflect their distinct purposes, utilizing separate React component trees.

Control Panel Component Hierarchy

The Control Panel UI is implemented in src/components/ControlPanel.tsx as a comprehensive settings surface. It imports ControlPanelSidebar.tsx for navigation and renders multiple sub-components including SettingsPage.tsx, WhisperModelPicker.tsx, and ReasoningModelSelector.tsx. The interface follows the shadcn/ui design system and hosts full routing capabilities.

// src/components/ControlPanel.tsx
export default function ControlPanel() {
  return (
    <div className="flex h-full">
      <ControlPanelSidebar />
      <main className="flex-1 overflow-auto p-6">
        <Outlet /> {/* Renders /settings, /history, /integrations */}
      </main>
    </div>
  );
}

Dictation Overlay Component Structure

The dictation overlay resides in src/components/App.jsx and presents a minimal "pill" UI. It leverages hooks such as useAudioRecording.js and useLiveTranscriptPanel.js to manage media capture and live transcription preview. The component contains no navigation elements—only a transcription display and recording status indicator.

// src/components/App.jsx (dictation overlay)
export default function DictationOverlay() {
  const { transcript, isRecording } = useAudioRecording();
  return (
    <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
      <div className="bg-white/90 px-4 py-2 rounded shadow-lg">
        {isRecording ? "Listening…" : "Press hotkey to start"}
        <p className="mt-1 text-sm">{transcript}</p>
      </div>
    </div>
  );
}

Routing and Navigation Models

The Control Panel mounts a full React Router implementation supporting routes such as /settings, /history, and /integrations. It serves as the entry point for the #/ route when the application launches in panel mode.

The dictation overlay uses an isolated /dictation route mounted in a hidden BrowserWindow context. It exposes no navigation UI and cannot transition between views, maintaining a single-purpose interface.

Interaction Models and Input Handling

User interaction patterns differ drastically between the two windows.

• Control Panel: Supports standard mouse and keyboard interaction with UI controls (buttons, selects, inputs). Users can resize, minimize, or close the window using native operating system chrome.

• Dictation Overlay: Relies entirely on global hotkeys registered in src/helpers/hotkeyManager.js for activation. Mouse interaction is limited to drag events handled by src/helpers/dragManager.js. The overlay cannot be resized and uses focusable: false to prevent stealing input focus from active applications.

Security and Privacy Considerations

The dictation overlay enables content protection via Electron's contentProtection: true flag, preventing screen-recording utilities from capturing spoken text. This privacy feature is critical for sensitive dictation scenarios.

The Control Panel explicitly disables content protection, allowing screen-sharing and recording of configuration sessions. This reflects the intended use case: the panel contains no sensitive ephemeral data, while the overlay processes confidential voice input.

Lifecycle and Resource Management

The Control Panel instantiates on application startup or when accessed via the system tray/menu. It persists for the entire session duration, entering a hidden state rather than destroying the window object when dismissed.

The dictation overlay follows a more dynamic lifecycle. It instantiates when dictation begins (or remains alive but hidden to reduce overhead). When hidden, the window stays alive in the background to avoid the performance cost of repeated BrowserWindow creation.

Summary

• The Control Panel is a resizable, framed window with full navigation that hosts OpenWhispr's settings and configuration UI in src/components/ControlPanel.tsx.
• The dictation overlay is a frameless, always-on-top, privacy-protected window managed by src/components/App.jsx that solely handles speech capture.
• BrowserWindow options differ fundamentally: the panel uses standard desktop window flags while the overlay uses transparent, alwaysOnTop, and contentProtection.
• Interaction models separate standard UI controls from global hotkey triggering via src/helpers/hotkeyManager.js.
• Routing architectures isolate the full router implementation to the Control Panel while the overlay maintains a single-route mount.

Frequently Asked Questions

How does the Control Panel window handle resizing compared to the dictation overlay?

The Control Panel is instantiated with resizable: true and standard window chrome, allowing users to adjust the viewport dimensions freely. The dictation overlay sets resizable: false and fixes dimensions (typically 320x80 pixels) to maintain a consistent "pill" appearance that does not interfere with underlying applications.

Why does the dictation overlay use content protection while the Control Panel does not?

The dictation overlay processes sensitive spoken text that users may not want captured by screen-recording software, so it enables contentProtection: true in src/helpers/windowManager.ts. The Control Panel displays configuration settings that users typically want to share or demonstrate, so it disables content protection to allow screen capture.

Which source files manage window creation for both interfaces?

Both windows are created in src/helpers/windowManager.*, which exports createControlPanel() and createDictationOverlay() functions. The Control Panel UI lives in src/components/ControlPanel.tsx, while the overlay UI resides in src/components/App.jsx with audio handling logic in src/hooks/useAudioRecording.js.

Can the dictation overlay be minimized to the taskbar?

No, the dictation overlay sets skipTaskbar: true and frame: false in its BrowserWindow options, ensuring it never appears in the taskbar or window switcher. This keeps the interface truly transient and non-intrusive. The Control Panel, conversely, appears in the taskbar like a standard application window.

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