Vocabulary & Snippets
Relevant source files
The following files were used as context for generating this wiki page:
The Vocabulary & Snippets system in MacParakeet is a deterministic text-processing layer designed to transform raw Speech-to-Text (STT) output into polished, professional text. It operates as a 5-step pipeline that executes in sub-millisecond time, ensuring predictable results without the overhead of an LLM. The system allows users to define custom word corrections and natural language "triggers" that expand into complex text snippets or simulate keyboard actions.
Sources: spec/07-text-processing.md:1-10, plans/completed/2026-04-vocabulary-import-export.md:5-10
Deterministic Text Processing Pipeline
The pipeline is a pure function that processes raw STT text through a series of transformations. It is active when the user selects the "Clean" processing mode, whereas "Raw" mode bypasses most steps except for terminal action extraction.
Sources: spec/07-text-processing.md:12-18, spec/07-text-processing.md:76-80
Pipeline Execution Order
The pipeline ensures that common speech hesitations are removed, user-specific vocabulary is correctly cased, and shortcuts are expanded before final normalization.
Sources: spec/07-text-processing.md:16-18
Key Pipeline Components
- Filler Removal: Automatically strips hesitation sounds like "um" and "uh" using regular expressions with word boundaries.
- Custom Word Replacements: Applies user-defined corrections using case-insensitive matching. It is used both in dictation and to correct finalized meeting transcripts.
- Trailing Action Extraction: Identifies triggers at the end of text (e.g., "press return") to simulate keystrokes instead of printing the literal phrase.
- Snippet Expansion: Replaces spoken natural language phrases with their full expansion text, matching the longest triggers first to prevent partial collision.
- Whitespace Cleanup: Normalizes spaces, fixes punctuation attachment, and applies casing styles (Sentence or Inline).
Sources: spec/07-text-processing.md:20-74
Data Models
The system relies on two primary data structures stored in the local SQLite database via GRDB.
Custom Words
Custom words are used to enforce correct casing for technical terms or fix recurring STT misidentifications.
| Field | Type | Description |
|---|---|---|
word | String | The raw token emitted by the STT engine (case-insensitive). |
replacement | String? | The intended substitute (null indicates a vocabulary anchor). |
source | Source | .manual (user-created) or .learned (auto-detected). |
isEnabled | Bool | Whether the rule is currently active. |
Sources: Sources/MacParakeetCore/Models/CustomWord.swift:11-20, spec/07-text-processing.md:92-105
Text Snippets
Snippets map spoken natural language triggers to larger blocks of text or specific post-paste actions.
| Field | Type | Description |
|---|---|---|
trigger | String | The natural phrase spoken by the user. |
expansion | String | The text to be pasted into the active application. |
action | SnippetAction? | Optional keystroke (e.g., .returnKey) to send after pasting. |
useCount | Int | Internal counter for expansion frequency. |
Sources: Sources/MacParakeetCore/Models/TextSnippet.swift:10-25, spec/07-text-processing.md:110-125
Import & Export (Vocabulary Bundles)
Users can manage their curated vocabulary through a versioned JSON bundle format (macparakeet.vocabulary). This allows for portability between Macs and serves as a local backup mechanism.
Sources: plans/completed/2026-04-vocabulary-import-export.md:12-16, Sources/CLI/Commands/VocabBundleCommands.swift:10-15
Bundle Schema Architecture
The export process strips local-only data such as UUIDs and usage counts to prevent conflicts during import on different machines.
Sources: plans/completed/2026-04-vocabulary-import-export.md:33-45, Sources/CLI/Commands/VocabBundleCommands.swift:171-220
Conflict Resolution Policies
When importing a bundle, the VocabularyImportExportService supports two primary conflict policies:
- Skip (Default): Existing records remain untouched; incoming duplicates are discarded.
- Replace: Existing records are deleted and replaced with the imported data, generating fresh UUIDs.
Sources: Sources/CLI/Commands/VocabBundleCommands.swift:75-85, plans/completed/2026-04-vocabulary-import-export.md:47-51
Automation & CLI Support
The Vocabulary system is a first-class citizen of the macparakeet-cli, allowing for headless management and integration with other automation tools.
Available CLI Commands
| Command Group | Purpose | Examples |
|---|---|---|
vocab process | Run the Clean pipeline on arbitrary text. | vocab process "um hello kubernetes" |
vocab words | List, add, or delete custom word rules. | vocab words add "aye pee eye" "API" |
vocab snippets | Manage trigger-expansion shortcuts. | vocab snippets list |
vocab export | Write the entire vocabulary to JSON. | vocab export --output backup.json |
vocab import | Apply a JSON bundle to the database. | vocab import --input backup.json |
Sources: spec/07-text-processing.md:130-170, Sources/CLI/Commands/VocabBundleCommands.swift:12-100
JSON Bundle Example
{
"schema": "macparakeet.vocabulary",
"version": 1,
"exportedAt": "2026-04-28T12:34:56Z",
"appVersion": "0.6.0",
"customWords": [
{ "word": "kubernetes", "replacement": "Kubernetes", "isEnabled": true }
],
"textSnippets": [
{ "trigger": "my address", "expansion": "123 Main St", "isEnabled": true }
]
}
Sources: plans/completed/2026-04-vocabulary-import-export.md:25-32, Sources/CLI/Commands/VocabBundleCommands.swift:232-250
User Interface
The Vocabulary tab provides a central dashboard for managing corrections and snippets. A dedicated "Backup & Restore" section allows users to trigger file-based import/export operations directly from the GUI.
Backup View Logic
The Vocabulary & Snippets system provides the essential bridge between raw machine speech recognition and human-ready text. By combining a deterministic pipeline with robust import/export capabilities, it ensures that MacParakeet adapts to the user's specific terminology and workflow needs while maintaining a local-first, high-performance posture.