Architecture

Two Layer Design

Steno/ contains the SwiftUI/AppKit application, DictationController, views, settings, onboarding, and menu bar integration. StenoKit/ contains models, protocols, services, actors, and benchmark support. StenoKit also contains platform-specific service implementations.

Pipeline

1. A recording control or hotkey changes the recording state.
2. Steno captures audio locally. If live transcription is enabled, provisional text appears in the overlay.
3. The retained Whisper helper transcribes the completed recording using the selected model. It communicates over inherited process pipes with no HTTP server or network listener.
4. The session pipeline applies text shortcuts, word corrections, local cleanup, and eligible continuation rules.
5. Insertion tries the configured transports with target checks and clipboard recovery.
6. Completed transcript data goes to History; usage metadata goes to the separate Insights store.

The helper keeps the model loaded for reuse and reloads when the model, the model file, the VAD configuration, or the thread count changes; saving other settings keeps the loaded model. If the helper's background process ends between dictations, Steno starts a new one. If the backup path stops responding, it is stopped after a time limit that grows with the recording length. Recoverable helper failures can fall back to the local CLI. Cancellation, stale responses, and VAD integrity failures do not use that retry. The CLI fallback does not include the retained helper's prompt-verification correction, so recognition can differ between the two paths.

Concurrency

Session coordination uses actors and explicit recording states to avoid overlapping sessions. UI updates run on the main actor. Cancellation and target revalidation affect processing as well as the interface. Test cancellation and target changes in the app with the editor and recording setup you use, alongside the automated tests.

Extension Points

Use the existing transcription, cleanup, insertion, capture, history, and usage interfaces when changing a service. Keep nearby editor context temporary and out of recognition prompts and persistence. Inspect the current implementation and its tests before adding a transport or changing fallback behavior.