michael-treadgold/win-dictate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Docs refresh: add user manual & architecture review; update README with accurate details

Browse Source
This commit is contained in:
Win Dictation Dev
2026-06-11 20:52:24 +12:00
parent e04b003bf8
commit a94ba824d6
19 changed files with 1609 additions and 466 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+60 -43
View File
@@ -1,8 +1,6 @@
# Win Dictation - AI Voice to Text for Windows
# Win Dictation — Voice to Text for Windows
A push-to-talk speech-to-text utility for Windows using OpenAI's Whisper model. Record, transcribe, and paste with a single hotkey.
![Win Dictation Screenshot](screenshot.png)
A push-to-talk speech-to-text utility for Windows. Press a hotkey, speak, and your words land in whatever app you were just using — fully offline, powered by Whisper.
## Quick Download
@@ -12,12 +10,18 @@ Extract the ZIP file and run `win-dictation.exe`. The release includes all requi
---
## Documentation
- **[User Manual](win-dictation-user-manual.html)** — How to use every feature
- **[Architecture & Engineering Review](win-dictation-architecture-engineering-review.html)** — Deep dive into the codebase for developers
---
## Features
### Performance
- **Physical-core threading**: Uses one thread per physical core for efficient batch transcription
- **CPU-only**: Optimised for the target Intel i5-7th-gen 2-core/4-thread machine
- **Smart model selection**: Auto-selects tiny.en for CPU-only, base.en when GPU is present
- **CPU-only**: Optimised for ordinary laptops — no GPU required
- **Self-calibrating progress**: Learns transcription speed per model and machine, delivering a smooth countdown
### User Interface
@@ -28,23 +32,25 @@ Extract the ZIP file and run `win-dictation.exe`. The release includes all requi
### Audio Processing
- **Push-to-talk**: Press Ctrl+Shift+Space, speak, press again to transcribe
- **500ms auto-end**: Stops recording after 500ms of silence
- **Multiple microphones**: Select from all available input devices
- **16kHz sample rate**: Optimised for Whisper
- **16 kHz sample rate**: Optimised for Whisper
- **Silence trimming**: Leading and trailing silence is trimmed before transcription
## Usage
## Quick Start
1. Launch `win-dictation.exe`
2. Click into wherever you want text, then press `Ctrl+Shift+Space`
3. Speak, then press `Ctrl+Shift+Space` again
4. Your words appear in the app you were using
Full instructions in the [User Manual](win-dictation-user-manual.html).
### Controls
- **Record**: Click the Record pill or press `Ctrl+Shift+Space`
- **Record/Stop**: Click the pill or press `Ctrl+Shift+Space`
- **Hide window**: `Ctrl+Shift+H`
- **Pin**: Keep window always-on-top
- **Copy / Paste / Clear**: Text actions
- **Model / Mic**: Select from popup menus
- **Hide**: `Ctrl+Shift+H` hides the window
### Indicators
- **Level**: Live audio energy during recording
- **Progress bar**: Smooth, counting-down estimate during transcription
- **Status**: Thread count at idle, elapsed time during recording
- **Copy / Paste / Clear**: Text actions below the transcript
- **Model / Mic / History**: Select from popup menus
## Building from Source
@@ -52,13 +58,13 @@ Extract the ZIP file and run `win-dictation.exe`. The release includes all requi
- **Windows 10/11**
- **CMake** 3.5+
- **Visual Studio 2022/2026** with C++ workload
- **Visual Studio 2022** with C++ workload
- **SDL2** (included in deps/)
### Build Steps
```powershell
cmake -S . -B build -G "Visual Studio 18 2026" \
cmake -S . -B build -G "Visual Studio 17 2022" ^
-DSDL2_DIR="deps/SDL2-2.28.5/cmake"
cmake --build build --config Release
```
@@ -73,36 +79,45 @@ The executable will be at `build\bin\Release\win-dictation.exe`.
Hotkey → SDL Capture → Stop → Batch whisper_full → Text → Auto-paste
```
1. **SDL audio capture**: 16kHz mono recording into memory
2. **Stop-and-transcribe**: Press stop or hit max length (600s), then one `whisper_full` call
3. **Progress estimation**: Linear model fitted per machine/model, fused with whisper's chunk progress
4. **Text output**: Appended to transcript, copied to clipboard, optionally auto-pasted
1. **SDL audio capture**: 16 kHz mono recording into memory. CPU stays near idle while recording.
2. **Stop-and-transcribe**: One `whisper_full` call processes the full clip at once.
3. **Progress estimation**: Decayed online least-squares model per machine/model, fused with whisper's chunk progress into a strictly monotonic countdown.
4. **Text output**: Inserted at cursor with smart spacing, copied to clipboard, and optionally auto-pasted into the window you came from.
### Model
### Models
Place `.bin` files in `models/` next to the executable. The app auto-detects available models:
Place `.bin` files in `models/` next to the executable, or download them from the Settings screen in-app:
| Model | Size | Params | Best for |
|-------|------|--------|----------|
| tiny.en | 75 MB | 39M | CPU-only systems |
| base.en | 140 MB | 74M | GPU-accelerated systems |
| Model | Size | Best for |
|-------|------|----------|
| tiny.en | ~75 MB | Fastest — everyday dictation |
| tiny.en-q8_0 | ~42 MB | Same speed, smaller file |
| base.en-q5_1 | ~59 MB | Good accuracy bump for little cost |
| base.en | ~142 MB | More accurate; still reasonable on two cores |
| small.en-q5_1 | ~182 MB | Accurate, but slower |
| small.en | ~466 MB | Most accurate — and slowest |
## Project Structure
```
win-dictation/
├── src/ # Application source
│ ├── main.cpp # UI and message handling
│ ├── transcriber.* # Recording and transcription
│ ├── timing.h # Progress estimation engine
│ ├── settings.h # INI persistence
│ ├── text_util.h # Transcript helpers
│ └── logging.h # Log utilities
├── whisper/ # Whisper.cpp library
├── ggml/ # GGML tensor library
├── models/ # Whisper model files
├── release/ # Pre-built package
└── CMakeLists.txt # Build configuration
├── src/ # Application source
│ ├── main.cpp # Window, painting, interaction, settings, clipboard, popups
│ ├── transcriber.* # SDL capture, Whisper preload/inference, progress callbacks
│ ├── timing.h # Learned timing model + live progress estimator
│ ├── history.h # Session text files, index, pruning
│ ├── downloader.h # WinHTTP model downloader (background thread)
│ ├── stats.h # Lifetime usage totals + derived figures
│ ├── settings.h # INI persistence
│ ├── text_util.h # Transcript concatenation helpers
│ ├── logging.h # Timestamped file log
│ └── tests/ # Unit tests (test-core.exe)
├── whisper/ # Whisper.cpp library
├── ggml/ # GGML tensor library
├── models/ # Whisper model files
├── history/ # Saved dictation sessions
├── release/ # Pre-built package
└── CMakeLists.txt # Build configuration
```
## License
@@ -111,5 +126,7 @@ MIT — follows [whisper.cpp](https://github.com/ggerganov/whisper.cpp).
## Resources
- [User Manual](win-dictation-user-manual.html)
- [Architecture & Engineering Review](win-dictation-architecture-engineering-review.html)
- [Whisper.cpp](https://github.com/ggerganov/whisper.cpp)
- [Model Download](https://huggingface.co/ggerganov/whisper.cpp)
- [Model Downloads](https://huggingface.co/ggerganov/whisper.cpp)