Personal Dictionary & Custom Terms
Relevant source files
The following files were used as context for generating this wiki page:
The Personal Dictionary is a core feature of mausVoice designed to improve transcription accuracy by allowing users to define custom names, technical jargon, and shorthand. It enables the system to remember specific terminology across sessions, ensuring that frequently misunderstood words are correctly identified or automatically replaced during the post-processing phase.
This system operates through a combination of local SQLite storage for persistence and TypeScript-based logic for real-time text replacement and LLM prompt engineering. By integrating custom terms directly into the AI cleanup and transcription workflows, mausVoice provides a personalized dictation experience that adapts to individual user vocabularies.
Sources: llms.txt:59-60, README.md:46, apps/desktop/src/components/dictionary/DictionaryPage.tsx:90-93
Architecture and Data Flow
The Personal Dictionary follows the project's "Rust is the API, TypeScript is the Brain" architecture. Business logic for managing terms resides in TypeScript (Zustand store and actions), while native capabilities like SQLite persistence are handled via Tauri commands.
Dictionary Data Flow
The following diagram illustrates how a user interaction in the UI flows through the application layers to update the dictionary state and persistent storage.
The dictionary lifecycle starts with user input in the DictionaryPage, which triggers asynchronous actions to update both the global state and the local database via the TermRepo.
Sources: llms.txt:30-36, apps/desktop/src/components/dictionary/DictionaryPage.tsx:32-62
Term Management
Terms in mausVoice are categorized into two primary types: Glossary terms and Replacement rules. Glossary terms help the transcription engine recognize specific words, while Replacement rules actively transform specific source values into preferred destination values.
Data Structures
Terms are defined by the Term interface, which includes fields for identification, timing, and functional behavior.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier generated via createId(). |
createdAt | string | ISO timestamp of term creation. |
sourceValue | string | The original word or phrase to be recognized or replaced. |
destinationValue | string | The target value for replacement rules (empty for glossary terms). |
isReplacement | boolean | Flag indicating if the term is a replacement rule. |
Sources: apps/desktop/src/components/dictionary/DictionaryPage.tsx:37-43
Logical Operations
The DictionaryPage component orchestrates several key operations:
- Initialization: Uses
useAsyncEffectto callloadDictionary()on mount, populating the UI from the database. - Addition: The
addTermfunction performs optimistic updates to the Zustand store before attempting to persist the new term throughgetTermRepo().createTerm(). - Rollback: If the database operation fails, the action catches the error, reverts the state change in the store, and triggers a visual error notification.
Sources: apps/desktop/src/components/dictionary/DictionaryPage.tsx:29-62
String Replacement Engine
The application employs a sophisticated string manipulation utility to apply dictionary rules to transcribed text. This engine handles complex matching scenarios, including multi-word phrases and punctuation preservation.
Matching Logic
Replacements are applied using a phrase-based approach. The engine prioritizes longer phrases (e.g., "New York City") over shorter ones (e.g., "New York") to ensure the most specific rule is applied first.
The algorithm uses Levenshtein edit distance with a similarity threshold of 0.95 to allow for minor transcription variances while still identifying the correct term for replacement.
Sources: apps/desktop/src/utils/string.utils.ts:133-145, apps/desktop/src/utils/string.utils.ts:180-210
Punctuation and Formatting
The extractPunctuation utility ensures that when a word is replaced, its surrounding context is not lost. It separates leading and trailing punctuation (including possessive suffixes like "'s") from the core word before performing the substitution.
Sources: apps/desktop/src/utils/string.utils.ts:89-106
Integration with AI Pipelines
Dictionary entries are leveraged to steer both the transcription and post-processing AI models.
Transcription Steering
Glossary terms are injected into the transcription prompt to bias the model toward recognizing custom vocabulary. This is especially critical for local Whisper models and streaming services like Deepgram. The system provides localized prompts for over 50 languages to ensure language consistency.
Sources: apps/desktop/src/utils/prompt.utils.ts:121-200
Prompt Construction
The collectDictionaryEntries function prepares the data for AI ingestion:
- Sanitization: Removes null characters and collapses whitespace.
- Deduplication: Uses case-insensitive maps to ensure unique entries.
- Automatic Inclusions: The app name "mausVoice" and the user's name are automatically added to the transcription glossary.
Sources: apps/desktop/src/utils/prompt.utils.ts:16-59
Summary of Dictionary Entries Structure
| Component | Description | Source File |
|---|---|---|
sources | A flat list of strings representing the custom vocabulary (glossary). | prompt.utils.ts |
replacements | An array of ReplacementRule objects mapping source to destination. | prompt.utils.ts |
SYMBOL_CONVERSIONS | Built-in regex rules for converting spoken words (e.g., "hashtag") to symbols ("#"). | string.utils.ts |
Sources: apps/desktop/src/utils/prompt.utils.ts:114-118, apps/desktop/src/utils/string.utils.ts:74-80
The Personal Dictionary system ensures that mausVoice remains a professional-grade tool by handling specialized terminology that standard AI models might otherwise misinterpret. Through the combination of fuzzy matching, punctuation preservation, and cross-platform SQLite persistence, the dictionary provides a reliable mechanism for vocabulary personalization.