# How the Control Panel Window Differs from the Dictation Overlay in OpenWhispr
> Discover how the OpenWhispr Control Panel window differs from the dictation overlay for efficient speech capture and configuration.
- Repository: [OpenWhispr/openwhispr](https://github.com/OpenWhispr/openwhispr)
- Tags: deep-dive
- Published: 2026-09-06
---
**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`](https://github.com/OpenWhispr/openwhispr/blob/main/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.
```typescript
// 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.
```typescript
// 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`](https://github.com/OpenWhispr/openwhispr/blob/main/src/components/ControlPanel.tsx) as a comprehensive settings surface. It imports [`ControlPanelSidebar.tsx`](https://github.com/OpenWhispr/openwhispr/blob/main/ControlPanelSidebar.tsx) for navigation and renders multiple sub-components including [`SettingsPage.tsx`](https://github.com/OpenWhispr/openwhispr/blob/main/SettingsPage.tsx), [`WhisperModelPicker.tsx`](https://github.com/OpenWhispr/openwhispr/blob/main/WhisperModelPicker.tsx), and [`ReasoningModelSelector.tsx`](https://github.com/OpenWhispr/openwhispr/blob/main/ReasoningModelSelector.tsx). The interface follows the shadcn/ui design system and hosts full routing capabilities.
```tsx
// src/components/ControlPanel.tsx
export default function ControlPanel() {
return (
{/* Renders /settings, /history, /integrations */}
);
}
```
### Dictation Overlay Component Structure
The dictation overlay resides in [`src/components/App.jsx`](https://github.com/OpenWhispr/openwhispr/blob/main/src/components/App.jsx) and presents a minimal "pill" UI. It leverages hooks such as [`useAudioRecording.js`](https://github.com/OpenWhispr/openwhispr/blob/main/useAudioRecording.js) and [`useLiveTranscriptPanel.js`](https://github.com/OpenWhispr/openwhispr/blob/main/useLiveTranscriptPanel.js) to manage media capture and live transcription preview. The component contains no navigation elements—only a transcription display and recording status indicator.
```tsx
// src/components/App.jsx (dictation overlay)
export default function DictationOverlay() {
const { transcript, isRecording } = useAudioRecording();
return (
{isRecording ? "Listening…" : "Press hotkey to start"}
{transcript}
);
}
```
## 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`](https://github.com/OpenWhispr/openwhispr/blob/main/src/helpers/hotkeyManager.js) for activation. Mouse interaction is limited to drag events handled by [`src/helpers/dragManager.js`](https://github.com/OpenWhispr/openwhispr/blob/main/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`](https://github.com/OpenWhispr/openwhispr/blob/main/src/components/ControlPanel.tsx).
- The **dictation overlay** is a frameless, always-on-top, privacy-protected window managed by [`src/components/App.jsx`](https://github.com/OpenWhispr/openwhispr/blob/main/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`](https://github.com/OpenWhispr/openwhispr/blob/main/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`](https://github.com/OpenWhispr/openwhispr/blob/main/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`](https://github.com/OpenWhispr/openwhispr/blob/main/src/components/ControlPanel.tsx), while the overlay UI resides in [`src/components/App.jsx`](https://github.com/OpenWhispr/openwhispr/blob/main/src/components/App.jsx) with audio handling logic in [`src/hooks/useAudioRecording.js`](https://github.com/OpenWhispr/openwhispr/blob/main/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.