win-dictate/src/DESIGN.md

Windows Dictation App Design Document

Goals

• Create a "polished" Windows app for dictation.
• Small memory footprint.
• Real-time transcription.
• Global hotkey support.
• On-demand GPU usage.

Architecture

The application is a native Win32 C++ application. It avoids heavy UI frameworks (Electron, .NET, Qt) to strictly adhere to the "small memory footprint" requirement and integration with the C++ codebase.

Components

1. Main Entry (WinMain):

   • Initializes the application.
   • Registers the global hotkey (RegisterHotKey).
   • Creates the main window (hidden by default).
   • Creates the System Tray icon (Shell_NotifyIcon).
   • Runs the standard Windows Message Loop.

2. UI Layer (Win32 API):

   • Main Window: A simple Dialog or Window containing:
     • EDIT control (Multiline, VScroll) for text output.
     • BUTTON controls for Record/Stop/Clear.
     • STATUS bar for model state.
   • Tray Icon: Context menu for Open/Exit.

3. Audio & Inference Layer (Transcriber):

   • Runs in a separate Worker Thread to prevent freezing the UI.
   • Audio Capture: Uses SDL2 (reusing common-sdl.cpp logic) for cross-platform consistency with the repo, or potentially native WASAPI if dependencies become an issue. For now, SDL2 is assumed as it's standard in this repo.
   • Inference: Uses whisper.cpp library (whisper_full).
   • VAD (Voice Activity Detection): Uses the simple energy-based VAD from common.cpp to detect when to transcribe.

Threading Model

• UI Thread: Handles Windows messages, paints the UI, processes hotkeys.
• Worker Thread:
  • Loops continuously when "Recording" is active.
  • Captures PCM audio chunks.
  • Runs whisper_full on the buffer.
  • Uses PostMessage(hWindow, WM_USER_TEXT_READY, ...) to send transcribed text back to the UI thread safely.

Resource Management (GPU/Memory)

• Startup: Does not load the model immediately to save RAM/VRAM.
• On Record: Checks if context exists. If not, loads the model (whisper_init_from_file).
• Inactive Timeout: A timer in the UI thread monitors inactivity. If inactive for X minutes, it signals the worker to destroy the whisper context (whisper_free), releasing VRAM.

Key APIs

• RegisterHotKey: For global shortcuts.
• Shell_NotifyIcon: For system tray.
• CreateWindowEx / DialogBox: For UI.
• whisper_full: For inference.

File Structure

• main.cpp: Entry point, Window Proc, Message Loop.
• transcriber.h/cpp: Wraps the Whisper context and SDL audio loop.
• resource.rc: Defines the UI layout (dialogs, menus, icons).
• CMakeLists.txt: Build definition.

Future Improvements

• Settings dialog to select Model path.
• Select Audio Input device.