# Introduction to VoiceInk (/docs/introduction) ## Welcome to VoiceInk [#welcome-to-voiceink] VoiceInk is a powerful, native macOS application designed to transcribe your speech into text with exceptional speed and accuracy. It's built with privacy and efficiency at its core, running 100% offline to ensure your data remains secure on your device. Whether you're a writer, developer, student, or anyone who wants to type faster and more naturally, VoiceInk offers a suite of features to streamline your workflow. ## Core Features [#core-features] VoiceInk is more than a transcription tool. These are the core pieces you will use most: * **Accurate, instant transcription**: Local AI models turn speech into text quickly, with strong accuracy for everyday dictation. * **Privacy first**: Voice data is processed on your Mac, so private drafts stay on your device. * **[Power Mode](/docs/power-mode)**: Apply different transcription and enhancement settings based on the app or website you are using. * **[Context-aware AI](/docs/contextual-awareness)**: Let VoiceInk use screen context to improve formatting and accuracy. * **Global shortcuts**: Configure system-wide shortcuts for recording and push-to-talk. * **Personal dictionary**: Teach VoiceInk names, technical terms, and phrases you use often. * **AI enhancement**: Switch between prompts for email, chat, summaries, cleanup, and more. * **AI Assistant**: Ask questions, summarize text, or give commands with your voice. ## How to Use VoiceInk [#how-to-use-voiceink] 1. **Launch**: Open VoiceInk from your `Applications` folder. You will see a new icon in your menu bar. 2. **Record**: Use your configured keyboard shortcut to start and stop recording your voice. 3. **Transcribe**: As you speak, VoiceInk will transcribe your words in near real-time. 4. **Insert**: The transcribed text will automatically be inserted at your current cursor position. These articles walk through the settings and workflows that help VoiceInk feel natural day to day. # Installation (/docs/installation) ## System Requirements [#system-requirements] Before installing VoiceInk, please ensure your Mac meets the following requirements: * **macOS Version**: macOS 14.4 or later. * **Hardware**: Local models are optimized for Apple Silicon (M1, M2, M3, etc.). While the application runs on Intel processors, performance for local transcription may not be optimal. For Intel-based Macs, using cloud models is recommended for the best experience. VoiceInk can run on Intel Macs, but local transcription is optimized for Apple Silicon. If you use an Intel Mac, cloud transcription is usually the better experience. ## Installation Steps [#installation-steps] ### Download [#download] Navigate to the official VoiceInk website: [tryvoiceink.com](https://tryvoiceink.com). Click on the "Download" button to get the latest version of the application. ### Install VoiceInk [#install-voiceink] If you downloaded from the website, open the `.dmg` file from your `Downloads` folder. Drag the VoiceInk application icon into your `Applications` folder. If you installed from the Mac App Store, the application will be automatically installed in your `Applications` folder. ### Launch VoiceInk [#launch-voiceink] Open your `Applications` folder and double-click on the VoiceInk icon. The first time you launch the application, you may be prompted to grant necessary permissions for microphone access and accessibility features. Please approve these for the app to function correctly. ## Initial Setup [#initial-setup] Upon first launch, VoiceInk will guide you through a quick onboarding process. Please follow the on-screen instructions to grant all the necessary permissions for the app to function correctly. # Recommended AI Models (/docs/recommended-models) ## Transcription [#transcription] ### Models for turning speech into text [#models-for-turning-speech-into-text] | Model | Best use | | -------------------------- | ------------------------------------------------------------------------ | | **Parakeet model** | Best first choice for fast, real-time offline transcription. | | **Whisper large v3 turbo** | Strong Whisper option when you want broad accuracy and reliable results. | ### Local vs cloud transcription [#local-vs-cloud-transcription] Local models are best when privacy and low latency matter. Cloud models can help with less common languages or when local processing is not suitable, but they depend on your internet connection. Use a local model when privacy, speed, and offline use are the priority. This is the recommended path for daily dictation on Apple Silicon Macs. Use a cloud model when local processing is too slow, the language is less common, or your Mac is not a good fit for local transcription. ## Enhancement [#enhancement] ### Models for improving the final text [#models-for-improving-the-final-text] | Provider | Models | | -------------- | ------------------------- | | **Groq** | `gpt-oss-120b` | | **Cerebras** | `gpt-oss-120b`, `GLM-4.7` | | **Gemini** | `gemini-3.1-flash-lite` | | **OpenRouter** | `gpt-oss-120b` | If enhancement regularly takes longer than two seconds, switch providers. Fast inference keeps dictation feeling natural. ### Choose a fast transcription model [#choose-a-fast-transcription-model] Start with **Parakeet model** for local transcription. ### Pick a low-latency enhancement provider [#pick-a-low-latency-enhancement-provider] Start with **Groq** and `gpt-oss-120b` when you want fast cleanup after transcription. ### Check the full session timing [#check-the-full-session-timing] If dictation feels slow, open transcript history, select transcripts, and use the analyze option in the bottom toolbar. ### Free tiers are enough to start [#free-tiers-are-enough-to-start] The listed providers have free tiers that are useful for testing and daily use before you decide whether paid models are worth it. You can understand what is taking time during a VoiceInk session by opening transcript history, selecting transcripts, and using the analyze option in the bottom toolbar. # License Key Management (/docs/license-management) ## License Key Not Received After Purchase [#license-key-not-received-after-purchase] After purchasing, your license key is sent to the email used at checkout. **If you haven't received it:** 1. Check your spam or junk folder 2. If you used Apple's "Hide My Email" during checkout, the email may not have forwarded — check your iCloud inbox or use your real Apple ID email on the portal 3. Retrieve it yourself from the [Polar Portal](https://polar.sh/beingpax/portal/request) — enter your purchase email and you'll get a verification code to access your license Still not finding it? [Contact me](/contact) with your receipt and we'll resend it. ## Activating Your License [#activating-your-license] 1. Open VoiceInk 2. When prompted, paste your license key 3. Follow the on-screen instructions to complete activation ## License Activation Failed [#license-activation-failed] If you see "Invalid License" or "Trial Expired" after entering your key: * **Copied incorrectly** — make sure you copied the full key with no extra spaces * **Wrong email** — you may be checking the portal with a different email than the one used at checkout * **Device limit reached** — each license covers a set number of Macs. If you've activated on another device, deactivate it first via the [Polar Portal](https://polar.sh/beingpax/portal/request) * **v1.22 bug** — there was a known issue in v1.22 where licenses showed as expired incorrectly. Update to the latest version to fix this ## Still Having Issues? [#still-having-issues] [Contact me](/contact) with your purchase email and the specific error you're seeing. # Shortcuts (/docs/shortcuts) ## Recording Shortcuts [#recording-shortcuts] VoiceInk supports up to two global recording hotkeys. Each hotkey can be set to a specific key and a recording mode. **Available keys:** Right Option, Left Option, Right Command, Right Control, Left Control, Right Shift, Fn, or a fully custom key combination. **Recording modes:** * **Toggle** — press once to start, press again to stop * **Push-to-Talk** — hold to record, release to stop * **Hybrid** — short press works like Toggle (press to start, press again to stop); long press works like Push-to-Talk (hold to record, release to stop) You can add a second shortcut from Settings → Shortcuts → **Add Second Shortcut**. ## Additional Shortcuts [#additional-shortcuts] These are set globally and work even when the recorder isn't visible: | Shortcut | Action | | ------------ | ----------------------------------- | | Configurable | Paste Last Transcription (Original) | | Configurable | Paste Last Transcription (Enhanced) | | Configurable | Retry Last Transcription | | Configurable | Open History Window | **Paste Last Transcription** re-pastes the most recent transcription without re-recording. Useful if you switched apps and need to paste again. **Retry Last Transcription** re-runs the last audio recording through the current model — handy for testing a different model on the same audio. **Open History Window** opens your transcription history in a separate window. ## Custom Cancel Shortcut [#custom-cancel-shortcut] By default, pressing Escape twice within 1.5 seconds cancels an active recording. The first press plays a confirmation sound and shows a prompt; the second press actually cancels. You can set a custom cancel shortcut if you prefer a single-key cancel. Enable **Custom Cancel Shortcut** in Settings → Additional Shortcuts, then assign any key. When a custom cancel shortcut is set, it cancels immediately on a single press and the double-Escape behavior is disabled. ## Middle-Click Recording [#middle-click-recording] Enables starting and stopping recording by clicking your middle mouse button (scroll wheel click). * Enable in Settings → Additional Shortcuts → **Middle-Click Recording** * Set an **Activation Delay** (in milliseconds) to avoid accidental triggers when scrolling ## Enhancement Shortcuts [#enhancement-shortcuts] These work while the Mini Recorder is visible: | Shortcut | Action | | ------------------- | ----------------------------------------------------------------------- | | ⌘E | Toggle AI Enhancement on/off | | ⌘1 – ⌘0 | Switch to enhancement prompt 1–10 | | Option+1 – Option+0 | Switch Power Mode 1–10 (when [Power Mode](/docs/power-mode) is enabled) | For a detailed article on prompt switching, see [Switching Enhancement Prompts](/docs/switching-enhancement-prompts). # Audio Input (/docs/audio-input) ## Overview [#overview] The Audio Input tab lets you control which microphone VoiceInk records from. There are three modes to choose from. ## System Default [#system-default] Uses whatever microphone macOS is currently set to use. This is the simplest option — if you change your input device in System Settings, VoiceInk follows automatically. ## Custom [#custom] Lets you pick a specific microphone regardless of what macOS has set as default. Useful if you always want to use a particular external mic even when other devices are connected. * Click **Refresh** to reload the list of available devices * The currently active device is shown with a green "Active" badge * Select any device to lock VoiceInk to it ## Prioritized [#prioritized] Sets up a ranked fallback list. VoiceInk tries each device in order — if the first is unavailable, it moves to the next. If none of your prioritized devices are available, it falls back to the built-in microphone. **Setting it up:** 1. In the Available Devices list, click **+** on any device to add it to your priority list 2. Use the up/down arrows to reorder priority 3. Click **−** to remove a device from the priority list This is ideal if you regularly switch between a headset and your MacBook's built-in mic — just add both, put the headset first, and VoiceInk handles the rest automatically. # Recording Feedback (/docs/recording-feedback) ## Sound Feedback [#sound-feedback] VoiceInk plays a sound when you start and stop recording so you always know the recorder is active. * Toggle **Sound Feedback** on or off in Settings → Recording Feedback * When enabled, expand the section to customize the start and stop sounds with your own audio files ## Mute Audio While Recording [#mute-audio-while-recording] Mutes your Mac's system audio output while you're recording, then restores it when you stop. This prevents sound from other apps bleeding into the microphone. * Enable **Mute Audio While Recording** in Settings → Recording Feedback * Set a **Resume Delay** (0–5 seconds) to control how quickly audio resumes after you stop recording ## Restore Clipboard After Paste [#restore-clipboard-after-paste] VoiceInk pastes transcribed text using your clipboard (it temporarily sets the clipboard to the transcription, sends Cmd+V, then restores your original clipboard content). * Enable **Restore Clipboard After Paste** to get your previous clipboard content back after each transcription * Set a **Restore Delay** — if your old clipboard content keeps getting pasted instead of the transcription, increase this to 0.5–1 second. See [Clipboard Issues](/docs/clipboard-issues) for more details. ## Use AppleScript Paste [#use-applescript-paste] An alternative paste method that uses AppleScript to send Cmd+V instead of simulated key events. Enable this if VoiceInk is not pasting correctly with your keyboard layout (for example, custom layouts like Neo2 or other non-standard setups). ## Pause Media While Recording (Experimental) [#pause-media-while-recording-experimental] Pauses any playing music or video while you record and resumes it when you stop. * Enable in Settings → Experimental → **Pause Media While Recording** * Set a **Resume Delay** to control when media resumes after recording ends # General Settings (/docs/settings-general) ## Interface [#interface] **Recorder Style** — Choose how the recording interface appears on screen: * **Notch** — a compact bar that sits in the notch area at the top of your display * **Mini** — a small floating window you can position anywhere ## General [#general] | Setting | Description | | ------------------ | ----------------------------------------------------------- | | Hide Dock Icon | Run VoiceInk as a menu bar-only app with no Dock presence | | Launch at Login | Start VoiceInk automatically when you log in to your Mac | | Auto-check Updates | Automatically check for new versions in the background | | Show Announcements | Display in-app announcements about new features and updates | | Check for Updates | Manually trigger an update check | | Reset Onboarding | Re-run the setup screens the next time VoiceInk launches | ## Privacy [#privacy] **Auto-delete Transcripts** — Automatically delete your transcription history after a set period: * Options: Immediately, 1 hour, 1 day, 3 days, 7 days * You can also run a manual cleanup at any time **Auto-delete Audio Files** — Delete the recorded audio files while keeping the text transcripts: * Options: 1 day, 3 days, 7 days, 14 days, 30 days * Frees up disk space without losing your transcription text Note: If Auto-delete Transcripts is enabled, the Audio Files option is hidden (deleting transcripts also removes the associated audio). ## Backup [#backup] Export and import all your VoiceInk settings in one file: * **Export Settings** — saves everything: settings, prompts, power modes, dictionary entries, and custom models * **Import Settings** — restores a previously exported configuration This is useful when migrating to a new Mac or sharing a configuration between devices. ## Diagnostics [#diagnostics] The Diagnostics section lets you export a log file to send to support when troubleshooting an issue. # AI Models for Transcription (/docs/transcription-models) ## Understanding Transcription Models [#understanding-transcription-models] VoiceInk gives you the flexibility to choose from a variety of transcription models, each with different characteristics in terms of speed, accuracy, and cost. Models are categorized into three main types: * **Local Models**: These models run directly on your Mac. They are completely private and do not require an internet connection. They offer a good balance of speed and accuracy. * **Cloud Models**: These models are hosted on third-party services (e.g., Groq, ElevenLabs, Deepgram, Parakeet, Gemini, Mistral, Soniox). They typically offer the highest accuracy and fastest transcription speeds but require an active internet connection and may have associated costs. * **Custom Models**: You can add your own custom cloud models that are compatible with the OpenAI API format. This is useful for users who have access to specialized or private models. :::note **Apple Speech Native Model**: The Apple Speech model uses the native macOS Speech framework and requires macOS 26 or later. This model provides excellent transcription quality but is only available on the latest macOS versions. ::: ## Managing Your AI Models [#managing-your-ai-models] You can manage all your transcription models from the **AI Models** section in the VoiceInk application. For a more detailed article on configuring models, see [AI Model Configuration](/docs/enhancements-configuring-models). ### Selecting Your Default Model [#selecting-your-default-model] 1. Navigate to the **AI Models** tab in the main window. 2. At the top of the view, you will see your currently selected **Default Model**. 3. To change the default model, browse through the list of available models. 4. Click the **Set as Default** button on the card of the model you wish to use. This will be your primary model for all transcriptions. ### Downloading Local Models [#downloading-local-models] * Local models need to be downloaded before you can use them. * Find the local model you want to use in the model list. * Click the **Download** button. A progress bar will show the download status. * Once downloaded, you can set it as your default model. ### Deleting a Model [#deleting-a-model] * If you no longer need a downloaded local model, you can delete it to free up disk space. * Click the **trash icon** on the model card to remove the downloaded files. ### Using Cloud & Custom Models [#using-cloud--custom-models] * Cloud models are available for use without any download required. * To use a cloud model, you may need to add an API key for the respective service. * You can add a **Custom Model** by selecting the "Custom" filter and clicking the "Add Custom Model" card. You will need to provide a model name, API endpoint, and API key. ## Language Selection [#language-selection] You can specify the language for your transcription to improve accuracy. This setting is in the **AI Models** tab. Setting a specific language is recommended for non-English dictation — leaving it on Auto-Detect can sometimes cause the model to switch languages unexpectedly. ## Model Settings [#model-settings] Click the **gear icon** in the AI Models tab to access additional transcription settings. ### Output Format [#output-format] For Whisper-based local models, you can provide a custom prompt that shapes the output formatting. This is not an instruction to an LLM — it is a style example that shows the model exactly how you want text formatted. For example, to ensure numbers are always written as digits, enter a sample like: `I need 2 apples and 10 oranges.` Output format is set per language, so you can have different formatting for different languages. ### Add Space After Paste [#add-space-after-paste] When enabled, VoiceInk appends a space after pasting your transcription. Useful if you dictate frequently mid-sentence and want to continue typing without manually adding a space. ### Automatic Text Formatting [#automatic-text-formatting] When enabled, VoiceInk applies basic text formatting to the transcription — capitalizing the first word and adding a period at the end if none is present. Disable this if you prefer raw output or if AI enhancement is handling formatting. ### Voice Activity Detection (VAD) [#voice-activity-detection-vad] When enabled, VoiceInk uses voice activity detection to automatically detect when you start and stop speaking, and can trim silence from the recording. This can improve transcription accuracy and reduce unnecessary processing. ### Prewarm Model (Experimental) [#prewarm-model-experimental] When enabled, VoiceInk loads the transcription model into memory in the background so it is ready to transcribe immediately when you start recording. Reduces the delay on the first transcription after launching the app. Marked experimental as it increases memory usage. ### Filler Words [#filler-words] The gear icon panel also contains the [Filler Words](/docs/filler-words) settings — toggle filler word removal on/off and manage your custom filler word list directly from here. # Transcription History (/docs/transcription-history) ## Accessing Your History [#accessing-your-history] VoiceInk automatically saves every transcription you make, creating a comprehensive log that you can access at any time. To view your past transcriptions, navigate to the **History** tab in the main application window. ## Features of the History View [#features-of-the-history-view] * **Search**: A powerful search bar at the top of the view allows you to quickly find specific transcriptions. You can search by keywords, phrases, or any text contained within the original or enhanced transcription. * **Transcription Cards**: Each transcription is displayed on its own card, showing a preview of the text, the date it was created, and any enhancements that were applied. * **Detailed View**: Click on any transcription card to expand it. The expanded view shows the full text of the transcription, and if applicable, the enhanced version of the text. * **Listen to Original Audio**: If the audio for a transcription was saved, you can play it back directly from the history view. This is useful for verifying the accuracy of a transcription. ## Managing Transcriptions [#managing-transcriptions] You have full control over your transcription history. You can manage individual transcriptions or perform bulk actions on multiple entries. ### Single Transcription Actions [#single-transcription-actions] * **Copy**: Quickly copy the original or enhanced text to your clipboard. * **Delete**: To delete a single transcription, click the trash icon on the transcription card. This will also delete the associated audio file, if one exists. ### Bulk Actions [#bulk-actions] * **Select Multiple Transcriptions**: You can select multiple transcriptions by clicking the checkbox on each card. * **Selection Toolbar**: Once you have selected one or more items, a toolbar will appear at the bottom of the screen with the following options: * **Analyze**: This tool helps you understand the performance of your transcriptions. It shows a breakdown of the time taken by the model for [transcription](/docs/transcription-taking-too-long) and, if applicable, for [enhancement](/docs/enhancements-configuring-models). If you are experiencing slow transcription times, you can use this to analyze what might be causing the issue. * **Delete**: Permanently delete all selected transcriptions and their associated audio files. * **Select All / Deselect All**: Quickly select or deselect all transcriptions that match the current search or filter. # Transcribe Audio Files (/docs/transcribe-audio-files) ## Overview [#overview] The **Transcribe Audio** tab lets you transcribe any audio or video file using the same AI models as live recording. This is useful for transcribing meetings, interviews, voice memos, or any recorded content. ## How to Use [#how-to-use] 1. Go to the **Transcribe Audio** tab 2. Drop an audio or video file onto the view, or click to browse for a file 3. Select the transcription model to use 4. Click **Transcribe** 5. The transcription appears in the view and is saved to your History ## Supported Formats [#supported-formats] VoiceInk supports common audio and video formats including MP3, M4A, WAV, AIFF, MP4, MOV, and more. ## AI Enhancement [#ai-enhancement] If AI Enhancement is enabled, VoiceInk will run the transcription through your selected enhancement prompt after transcribing — just like live recording. ## Output [#output] Completed transcriptions are saved to your [Transcription History](/docs/transcription-history), where you can search, copy, and replay the audio alongside the text. # Custom Local Whisper Models (/docs/custom-local-whisper-models) ## Why use a custom local model? [#why-use-a-custom-local-model] * **Domain accuracy**: Fine‑tuned models (e.g., medical, legal, meetings, accents) can outperform general models on your data. * **Latency and cost**: Local inference avoids network latency and API costs, though it can be slightly slower than Core ML optimized models if you're only using the GGML whisper.cpp compatible format. ## Requirements [#requirements] * A local Whisper model that you are trying to add should be whisper.cpp compatible format with the `.bin` extension (e.g., `ggml-large-v3-turbo.bin`). * Optional: For Core ML support, the Core ML model should have exactly the same name as the GGML model, with the format `[model-name]-encoder.mlmodelc` (e.g., `ggml-large-v3-turbo-encoder.mlmodelc`). ## Available Fine-Tuned Models [#available-fine-tuned-models] **Language-Specific Models (Ready to Use):** * **[Finnish/Swedish](https://huggingface.co/Finnish-NLP/Finnish-finetuned-whisper-models-ggml-format/tree/main)** (`Large-v3`) * **[Nepali](https://huggingface.co/kiranpantha/whisper-large-v3-nepali)** (`Large-v3`) * **[German](https://huggingface.co/cstr/whisper-large-v3-turbo-german-ggml)** (`Large-v3-Turbo`) * **[Hebrew](https://huggingface.co/ivrit-ai/whisper-large-v3-ggml)** (`Large-v3`) * **[Korean](https://huggingface.co/royshilkrot/whisper-medium-korean-ggml)** (`Medium`) * **[Swedish](https://huggingface.co/jayant-yadav/ggml-kb-whisper-large_strict)** (`Large`) * **[Hindi](https://huggingface.co/khidrew/whisper-base-hindi-ggml)** (`Base`) **Models Requiring Conversion (PyTorch format):** * **[Medical](https://huggingface.co/Na0s/Medical-Whisper-Large-v3)** (`Large-v3`) * **[Clinical](https://huggingface.co/clinical-assistance/whisper-large-v3-clinical-assistance)** (`Large-v3`) * **[Russian](https://huggingface.co/dvislobokov/whisper-large-v3-turbo-russian)** (`Large-v3-Turbo`) * **[Chinese](https://huggingface.co/BELLE-2/Belle-whisper-large-v3-turbo-zh)** (`Large-v3-Turbo`) ### Conversion Resources [#conversion-resources] * **GGML whisper.cpp compatible conversion**: [whisper.cpp GGML format](https://github.com/ggml-org/whisper.cpp?tab=readme-ov-file#ggml-format) * **Core ML conversion**: [whisper.cpp Core ML support](https://github.com/ggml-org/whisper.cpp?tab=readme-ov-file#core-ml-support) For more background, see VoiceInk docs: [Custom Local Whisper Models](https://tryvoiceink.com/docs/custom-local-whisper-models). ## How to import in VoiceInk [#how-to-import-in-voiceink] 1. Open VoiceInk → `AI Models`. 2. Go to the `Local` tab. 3. Scroll to the bottom and click `Import Local Model…`. 4. Select your `.bin` file. You will be able to use it now with VoiceInk. 5. Click `Set as Default` on the imported model to use it for transcription. ## Deleting and managing models [#deleting-and-managing-models] * From the model card menu, choose `Delete Model` to remove the file from VoiceInk. The card disappears immediately. * `Show in Finder` reveals the actual `.bin` file in the models directory. # Configuring AI Enhancements (/docs/enhancements-configuring-models) ## What is AI Enhancement? [#what-is-ai-enhancement] AI Enhancement takes your raw transcription and sends it to a Large Language Model (LLM) for post-processing. This lets you automatically reformat text, fix grammar, summarize content, or change the tone of your writing. You can create different prompts for different tasks — a professional email prompt, a casual message prompt, a code comment prompt, and so on. To use this feature, enable it and configure an AI provider. ## Enabling Enhancement [#enabling-enhancement] 1. Navigate to the **Enhancement** tab. 2. Toggle on the **Enable Enhancement** switch at the top. You can also toggle enhancement on and off quickly with **⌘E** while the Mini Recorder is visible. See [Shortcuts](/docs/shortcuts) for all keyboard shortcuts. ## Connecting to an AI Provider [#connecting-to-an-ai-provider] ### Supported Providers [#supported-providers] * **Ollama (Free & Local)** — Run open-source models locally. Best for privacy and offline use. * **Groq (Free Tier)** — Very fast inference speeds. * **Cerebras (Free Tier)** — High-speed inference with generous free limits. * **OpenAI (Paid)** — GPT-4o and other OpenAI models. * **Gemini (Free Tier)** — Google's Gemini models, with a generous free tier. * **Anthropic (Paid)** — Claude family of models. * **Mistral (Paid)** — Mistral AI models. * **OpenRouter (Paid)** — Access many providers through a single API key. * **Custom** — Connect to any OpenAI-compatible API endpoint. ### How to Configure a Provider [#how-to-configure-a-provider] 1. In the **Enhancement** tab, find the **AI Provider Integration** section. 2. Select your provider from the dropdown. 3. Enter your API key. A green "Connected" status confirms the key is valid. 4. Select a model from the list that appears once connected. ### Using Ollama for Local Enhancement [#using-ollama-for-local-enhancement] 1. Install and run the Ollama application on your Mac. 2. Select **Ollama** as your provider in VoiceInk. 3. VoiceInk connects automatically to `http://localhost:11434`. 4. Select any model you have pulled in Ollama. ## Enhancement Settings [#enhancement-settings] Click the **gear icon** in the Enhancement tab to access additional settings. ### Clipboard Context [#clipboard-context] When enabled, VoiceInk reads the current contents of your clipboard and passes it to the AI as additional context. This is useful when you want the AI to rewrite or respond to something you've copied. ### Screen Context [#screen-context] When enabled, VoiceInk takes a one-time screenshot of your active window, extracts the visible text using on-device OCR, and passes it to the AI as context. Your screen is not recorded continuously, and the image itself is never sent to any provider — only the extracted text. For full details on how this works and privacy implications, see [Contextual Awareness](/docs/contextual-awareness). ### Skip Short Transcriptions [#skip-short-transcriptions] When enabled, very short transcriptions are sent to the AI as-is without running enhancement. You can set the **Minimum words** threshold (1–15 words, default is 3). Transcriptions shorter than this threshold skip enhancement entirely. This avoids wasting API calls on single-word dictations or accidental recordings. ### Enhancement Shortcuts [#enhancement-shortcuts] * **⌘E** — Toggle AI Enhancement on/off while the Mini Recorder is visible * **⌘1 – ⌘0** — Switch to enhancement prompt 1–10 See [Shortcuts](/docs/shortcuts) for the full shortcuts reference. ## Enhancement Prompts [#enhancement-prompts] Your prompts are shown as a grid in the Enhancement tab. You can: * **Add** a prompt with the **+** button * **Reorder** by dragging prompts * **Edit** by double-clicking a prompt * **Right-click** for options (duplicate, delete, set as default) ### Quickly Switching Prompts [#quickly-switching-prompts] Press **⌘1–⌘0** while the Mini Recorder is open to switch prompts instantly without opening the app. See [Switching Enhancement Prompts](/docs/switching-enhancement-prompts) for details. ### Trigger Words [#trigger-words] You can assign keywords to any prompt so it activates automatically when that word appears at the start or end of your speech — no keyboard shortcut needed. See [Trigger Words](/docs/enhancements-trigger-words). ### Assistant Mode [#assistant-mode] Enhancement prompts can be set to **Assistant Mode**, which treats your speech as a question or command directed at the AI rather than text to reformat. See [Assistant Mode](/docs/enhancements-assistant-mode). # Trigger Words for Enhancements (/docs/enhancements-trigger-words) ## What are Trigger Words? [#what-are-trigger-words] Trigger Words are specific keywords or phrases that you can associate with any of your custom enhancement prompts. When VoiceInk detects one of these triggers at the **exact beginning or end** of your transcription, it will automatically activate the associated prompt for that specific task. If AI Enhancement is currently turned off, detecting a trigger word will automatically enable it for the current transcription. After the enhancement is complete, your settings will revert to their previous state. ## How to Assign and Use Trigger Words [#how-to-assign-and-use-trigger-words] 1. **Choose Your Words**: When creating or editing an enhancement prompt, you can assign one or more trigger words or phrases. 2. **Prefer Shorter Triggers**: While multi-word phrases (e.g., "send email") are supported, it is recommended to use **shorter, single words** (e.g., `email`, `tweet`, `fix`) for the highest accuracy. Longer phrases are more likely to be misinterpreted by the speech-to-text model itself. 3. **Add Variations**: Speech-to-text is not always perfect. The model might hear "summarize" as "summary." To make trigger words functionality more reliable, it's a good practice to add common variations. For a summarization prompt, you could add `summarize`, `summary`, and `summaries` as trigger words. 4. **Speak Your Trigger**: To use a trigger, you must say the keyword or phrase at the very beginning or very end of your speech. * **Prefix Example**: `"Email` *the rest of your speech goes here...* `"` * **Suffix Example**: `"` *...your speech ends here,* `summarize."` 5. **Automatic Processing**: VoiceInk detects the trigger, removes it from the text, and then processes the remaining content with the correct enhancement prompt. ## Example Use Case [#example-use-case] Imagine you have a prompt for drafting emails with the assigned trigger words: `email`, `mail`. To use it, you would activate VoiceInk and say: > **"Email** I think you should move forward with the new design." VoiceInk will detect "Email," remove it, and then use your email prompt to format the rest of the text into a properly structured email. This powerful feature allows you to switch between different AI tasks on the fly, without ever taking your hands off the keyboard. # AI Assistant Mode (/docs/enhancements-assistant-mode) ## What is Assistant Mode? [#what-is-assistant-mode] Assistant Mode transforms VoiceInk from a transcription tool into a conversational AI assistant, similar to ChatGPT. Instead of simply transcribing and formatting your words, Assistant Mode interprets your speech as a question or command and provides a direct answer. This mode is perfect for when you need to quickly get information, perform a calculation, brainstorm ideas, or get a second opinion on a piece of text without leaving your current application. ## How to Use Assistant Mode [#how-to-use-assistant-mode] 1. **Enable AI Enhancement**: Assistant Mode is a part of the AI Enhancement suite. You must have enhancements enabled and an AI provider configured. See [Configuring AI Enhancements](/docs/enhancements-configuring-models) if you haven't set this up yet. 2. **Select the Assistant Prompt**: In the **Enhancement** tab, under the **Enhancement Prompt** section, select the "Assistant" prompt. This will change the behavior of the AI from formatting text to answering questions. 3. **Start a Conversation**: Use your normal recording shortcut and speak your query. For example: * `"What is the capital of Australia?"` * `"Give me three ideas for an article about productivity."` * `"Translate 'hello, how are you' into French."` 4. **Get Your Answer**: Instead of transcribing your question, VoiceInk will replace it with the AI's answer, ready to be pasted anywhere. ## Contextual Awareness [#contextual-awareness] Assistant Mode can also use context from your screen to provide more relevant answers. * **Selected Text**: If you highlight a piece of text in any application and then activate the assistant, it will use that selected text as context for your query. For example, you could highlight a paragraph and say, `"Summarize this for me."` * **Clipboard & Screen Context**: If enabled in the Enhancement settings, the assistant can also use text from your clipboard or the active window to better understand your request. ## Using a Trigger Word for Assistant Mode [#using-a-trigger-word-for-assistant-mode] You can also activate Assistant Mode on the fly using a trigger word, without needing to select it manually. The Assistant prompt is a built-in prompt, and you can edit it to assign a trigger word like `assistant` or `question`. Once assigned, you can say your trigger word at the beginning of your query, for example: `"Assistant, what is the weather like today?"` This will temporarily activate Assistant Mode for that single request and give you an answer. Your settings will revert back immediately afterwards. To learn more, read the full article on [Trigger Words for Enhancements](/docs/enhancements-trigger-words). ## Switching Back to Transcription [#switching-back-to-transcription] To go back to the standard transcription and enhancement functionality, simply select a different prompt (like the "Default" prompt) from the **Enhancement** tab. # Power Mode (/docs/power-mode) ## What is Power Mode? [#what-is-power-mode] Power Mode is an advanced feature that allows you to create custom "modes" that automatically activate when you are using specific applications or websites. Each mode can have its own unique settings for transcription and enhancement, allowing VoiceInk to seamlessly adapt to your workflow. For example, you could have a "Coding Mode" that activates in your code editor, a "Formal Writing Mode" for Google Docs, and a "Casual Chat Mode" for your messaging apps. ## Enabling Power Mode [#enabling-power-mode] 1. Open VoiceInk and go to the **Settings** tab in the sidebar. 2. Find the **Power Mode** section. 3. Toggle on the **Power Mode** switch. Once enabled, a dedicated **Power Mode** item appears in the sidebar where you can create and manage your modes. ## Auto-Restore Preferences [#auto-restore-preferences] When Power Mode is enabled, you have the option to enable **Auto-Restore Preferences** (found in Settings → Power Mode section, below the toggle). ### Default Behavior (Auto-Restore Preferences Disabled) [#default-behavior-auto-restore-preferences-disabled] By default, when a Power Mode is activated (triggered by an application or website), that Power Mode's settings will persist. Once activated, the Power Mode will remain active for subsequent recordings until you manually change it or switch to a different context that triggers another Power Mode. ### With Auto-Restore Preferences Enabled [#with-auto-restore-preferences-enabled] When you enable **Auto-Restore Preferences**, the behavior changes: * **No Persistence**: After you finish recording with an active Power Mode, VoiceInk will automatically switch back to your previous settings instead of keeping the Power Mode active. This means the Power Mode will not persist for your next recording session. * **Restoring Previous Settings**: If you have previous settings stored, Auto-Restore Preferences will restore them after the current Power Mode recording is complete. This ensures that when you start your next recording session, you'll begin working from your previous settings, providing continuity in your workflow. * **Main Purpose**: The primary use case for this feature is when switching to a context that does not have a specific Power Mode configured. Instead of maintaining the last activated Power Mode, it automatically restores your standard settings, allowing you to work from your previous configuration. ## How Power Mode Works [#how-power-mode-works] 1. **Create a Mode**: Go to the **Power Mode** tab in the sidebar and click **Add Power Mode** to create a new mode. Give it a name and an emoji for easy identification. 2. **Assign Triggers**: You can assign one or more triggers to a mode. A trigger can be either an application (e.g., Slack, VS Code) or a website URL (e.g., `gmail.com`, `notion.so`). 3. **Customize Settings**: For each mode, you can customize the following settings: * **Transcription Model**: Choose a specific local or cloud model for transcription. * **Language**: Set the transcription language. * **AI Enhancement**: Enable or disable AI enhancement. * **Enhancement Prompt**: Select a specific enhancement prompt to use. * **AI Provider & Model**: Choose the AI provider and model for enhancement. * **Context Awareness**: Decide whether the mode should use screen capture for context. * **Auto Send**: Automatically press a key combination after pasting text. Options: None, Return, Shift + Return, or Command + Return. Useful for chat applications or forms that use different send shortcuts. * **Set as Default**: Mark this mode as your default configuration when no specific triggers match. * **Keyboard Shortcut**: Assign a unique keyboard shortcut to instantly activate this Power Mode and start recording — even when the Mini Recorder is not visible. 4. **Automatic Switching**: Once configured, VoiceInk will automatically apply the corresponding settings based on the active application or website you're working with. When you switch to a context that doesn't have a specific mode, it will use your default mode settings if one is configured, otherwise your original settings are restored. ## Default Mode Behavior [#default-mode-behavior] You can designate one of your Power Modes as the **Default Mode**. This mode's settings will be used when: * You're in an application or website that doesn't have a specific Power Mode configured * No Power Mode triggers match your current context Only one mode can be marked as default at a time. If you don't have a default mode configured, VoiceInk will fall back to your global default settings. ## Quickly Switching Power Modes [#quickly-switching-power-modes] When Power Mode is enabled, you can quickly switch between your configured modes using keyboard shortcuts. This is especially useful when you need to manually override the automatic switching or jump to a specific mode. For a detailed article, see [Quickly Switching Power Modes](/docs/switching-power-modes). Power Mode is a game-changer for productivity, making VoiceInk a truly intelligent assistant that adapts to you, not the other way around. # Quickly Switching Power Modes (/docs/switching-power-modes) ## Manual Power Mode Selection [#manual-power-mode-selection] VoiceInk provides multiple ways to manually select and switch between your configured [Power Modes](/docs/power-mode), giving you full control over when and how different modes are applied. ## Power Mode Button in Mini Recorder [#power-mode-button-in-mini-recorder] When the Mini Recorder is visible and expanded (hover over it), you'll see a power mode button on the right side displaying the icon for the currently active mode. If no mode is active, VoiceInk shows the default sparkles indicator. Click this button to open a popover showing all your enabled power modes, allowing you to manually select any mode. ## Keyboard Shortcuts [#keyboard-shortcuts] When the Mini Recorder is open, you can use the number keys on your keyboard, combined with the `Option` key, to select a Power Mode. * **`Option + 1`**: Activates the first enabled Power Mode in your list. * **`Option + 2`**: Activates the second enabled Power Mode in your list. * **`Option + 3`**: Activates the third enabled Power Mode, and so on up to **`Option + 0`** for the tenth mode. ### Important Notes [#important-notes] * **Order Matters**: The shortcuts correspond to the order of your enabled Power Modes as they appear in the **Power Mode** tab in the sidebar. * **Mini Recorder Must Be Active**: These shortcuts only work when the Mini Recorder is visible on your screen. * **Only Enabled Modes**: The shortcuts only work with power modes that are currently enabled in your configuration. ## Use Case Example [#use-case-example] Let's say you have the following Power Modes configured: 1. **Writing Mode** (For focused writing) 2. **Coding Mode** (For VS Code) 3. **Email Mode** (For Gmail) When you are in the middle of transcribing, you can: * Press `Option + 1` to instantly switch to your **Writing Mode** settings. * Press `Option + 2` to apply your **Coding Mode** configuration. * Press `Option + 3` to activate your **Email Mode** settings. This allows for rapid, on-the-fly adjustments to your transcription and enhancement settings without ever needing to open the main application window, keeping you in the flow of your work. # Quickly Switching Enhancement Prompts (/docs/switching-enhancement-prompts) ## On-the-Fly Prompt Switching [#on-the-fly-prompt-switching] VoiceInk provides a fast and intuitive way to switch between your different enhancement prompts using keyboard shortcuts. This allows you to change the AI's behavior mid-workflow without interrupting your train of thought. This functionality is available when the Mini Recorder window is active. ## How It Works [#how-it-works] While the Mini Recorder is open, you can use the `Command` key in combination with the number keys (`1` through `0`) to select an enhancement prompt. * **`Command + 1`**: Activates the first enhancement prompt in your list. * **`Command + 2`**: Activates the second prompt. * **`Command + 3`**: Activates the third prompt, and so on up to **`Command + 0`** for the tenth prompt. ### Key Behaviors [#key-behaviors] * **Automatic Enablement**: If AI Enhancement is currently turned off, using one of these shortcuts will automatically enable it and select the corresponding prompt. * **Order is Key**: The number corresponds to the order of the prompts in your list in the **Enhancement** tab in the sidebar. * **Mini Recorder Focus**: These shortcuts are only active when the Mini Recorder is visible. ### Trigger Word Activation [#trigger-word-activation] In addition to keyboard shortcuts, you can also activate specific enhancement prompts using [Trigger Words](/docs/enhancements-trigger-words). This allows for a more natural, voice-driven way to switch prompts. ## Toggling Enhancement [#toggling-enhancement] You can also quickly toggle the AI Enhancement feature on or off without selecting a new prompt. * **`Command + E`**: Toggles the main **Enable Enhancement** switch on or off. ## Use Case Example [#use-case-example] Suppose you have the following enhancement prompts set up: 1. **Default** (For general text cleanup) 2. **Assistant** (For asking questions) 3. **Summarize** (To create summaries) 4. **Translate to Spanish** (For translation) During a recording session, you can: * Start by dictating normally with the **Default** prompt active (`Command + 1`). * Need to ask a quick question? Press `Command + 2` to switch to **Assistant** mode and speak your query. * Want to summarize the last paragraph you wrote? Press `Command + 3` to activate the **Summarize** prompt. * Finished with enhancements for now? Press `Command + E` to toggle them off completely. These shortcuts make the enhancement features incredibly powerful, allowing you to fluidly move between different AI behaviors as your needs change. # Contextual Awareness (/docs/contextual-awareness) ## What is Contextual Awareness? [#what-is-contextual-awareness] Contextual Awareness is a powerful feature that allows VoiceInk to understand the content of your active application window. By seeing the text on your screen, the AI can provide much more accurate and relevant transcriptions and enhancements. This feature is particularly useful when your speech contains jargon, code, or specific names that appear on the screen. ## How It Works (And Protects Your Privacy) [#how-it-works-and-protects-your-privacy] VoiceInk's Contextual Awareness is designed with privacy as the top priority. Here’s a step-by-step breakdown of the process: 1. **One-Time Screenshot**: When you use a feature that requires context, VoiceInk takes a temporary, one-time screenshot of your currently active window. **It does not record your screen continuously.** 2. **On-Device OCR**: The screenshot is processed directly on your Mac using Apple's native Vision framework. This technology scans the image for text and converts it into plain text. This process is often referred to as Optical Character Recognition (OCR). 3. **Context for the AI**: This extracted text is then used as additional context for the AI model. ### Data and Privacy [#data-and-privacy] * **Local AI Models**: If you are using a local transcription model (like the default Whisper model) and a local enhancement provider (like Ollama), **no data from the screenshot ever leaves your machine.** The entire process, from screenshot to OCR to AI processing, happens offline. * **Cloud AI Providers**: If you are using a cloud-based [AI provider](/docs/enhancements-configuring-models) for enhancement (like OpenAI, Groq, etc.), only the **extracted text** from the screenshot is sent to the provider as part of the request. The image itself is never uploaded. ## How to Enable It [#how-to-enable-it] Contextual awareness has two separate toggles, both found in the Enhancement tab's **settings panel** (gear icon): * **Clipboard Context** — includes your current clipboard contents as context for the AI * **Screen Context** — takes a one-time screenshot, extracts on-screen text via OCR, and passes it to the AI You can enable either or both independently. See [Configuring AI Enhancements](/docs/enhancements-configuring-models) for more details on the Enhancement settings panel. # Word Replacements (/docs/word-replacements) ## How Word Replacements Work [#how-word-replacements-work] Word Replacements allow you to define a word or phrase that will be automatically replaced with a different text snippet. This feature is primarily designed to correct speech recognition errors where the same word or phrase might be transcribed differently, but it can also be used for expanding abbreviations and inserting boilerplate text. Word replacements are applied after the initial transcription and before AI enhancement, ensuring your text is corrected before any AI processing. ### Use Cases [#use-cases] * **Correct speech recognition mistakes**: Speech-to-text systems sometimes transcribe the same word differently (e.g., "VoiceInk" might be transcribed as "Voicing", "Voice ink", or "Voiceing") * **Expand abbreviations**: For example, you could have "brb" automatically replaced with "be right back" * **Insert boilerplate text**: For frequent phrases, you can create shortcuts * **Standardize terminology**: Ensure technical terms or proper names are always transcribed correctly ## How to Use Word Replacements [#how-to-use-word-replacements] 1. Go to the **Dictionary** tab in the sidebar. 2. Select the **Word Replacements** section. 3. Click the **+** button to add a new replacement. 4. Enter the original word or phrase and the text you want to replace it with. ### Adding Multiple Words at Once [#adding-multiple-words-at-once] You can specify multiple original words or phrases that should all be replaced with the same replacement text. This is particularly useful for correcting speech recognition variations: * **Separate with commas**: Enter multiple originals separated by commas in the "Original Text" field * **All variants map to one replacement**: Each comma-separated term will be replaced with the same replacement text * **Case-insensitive matching**: Replacements work regardless of capitalization **Example**: `Voicing, Voice ink, Voiceing` → `VoiceInk` ## Practical Examples [#practical-examples] Here are some real-world examples of how word replacements can correct common speech recognition issues: ### Example 1: Correcting Product/Service Names [#example-1-correcting-productservice-names] **Original**: `github, git hub, get hub`\ **Replacement**: `GitHub`\ *Why*: Speech recognition often mishears "GitHub" as "Git hub" or "Get hub" ### Example 2: Technical Terminology [#example-2-technical-terminology] **Original**: `api, a p i, aapi`\ **Replacement**: `API`\ *Why*: Technical acronyms are frequently transcribed with spaces or misheard variations ### Example 3: Proper Names [#example-3-proper-names] **Original**: `chat gpt, chatgpt, chat g b t`\ **Replacement**: `ChatGPT`\ *Why*: AI model names are commonly transcribed with spaces or pronunciation variations ### Example 4: Expanding Abbreviations [#example-4-expanding-abbreviations] **Original**: `brb, be right back`\ **Replacement**: `be right back`\ *Why*: Convert spoken abbreviations to their full forms for clarity ### Important Notes [#important-notes] * **Case-insensitive**: Word replacements work regardless of capitalization. "GitHub", "github", and "GITHUB" will all be replaced if you specify "github" as the original. * **Word boundaries**: Replacements respect word boundaries to avoid partial matches within other words. * **Processing order**: Word replacements are applied after the initial transcription and before [AI enhancement](/docs/enhancements-configuring-models). This means that the replacement text will be included in the context provided to the AI, which can be useful for providing additional instructions or formatting. ## Related [#related] * [Correct Spellings](/docs/correct-spellings) — teach the Whisper model to recognize specific words before transcription * [Filler Words](/docs/filler-words) — automatically remove words like "uh", "um", and "hmm" # Correct Spellings (/docs/correct-spellings) ## How Vocabulary Works [#how-vocabulary-works] The Vocabulary feature helps you improve transcription accuracy by providing a list of important words that might not be recognized otherwise. This is especially useful for: * **Technical terms**: Words specific to your industry or field. * **Proper nouns**: Names of people, places, or products. * **Unique spellings**: Words that are often misspelled by transcription models. When you add a word to your vocabulary, it is passed to the AI enhancement model as important context. The AI uses this vocabulary list to ensure these words are spelled and formatted correctly in the final output. ## How to Use Vocabulary [#how-to-use-vocabulary] 1. Go to the **Dictionary** tab in the sidebar. 2. Select the **Vocabulary** section. 3. Type a word or phrase into the text field and press Enter or click the **+** button. ### Important Notes [#important-notes] * **Requires AI Enhancement**: This feature works through AI enhancement. You must have AI Enhancement enabled for vocabulary words to take effect. * **Add and Remove**: You can add words to your vocabulary list and remove them when they are no longer needed. ## Related [#related] * [Word Replacements](/docs/word-replacements) — replace misheard words or expand abbreviations after transcription * [Filler Words](/docs/filler-words) — automatically remove filler sounds like "uh" and "um" # Filler Words (/docs/filler-words) ## What Are Filler Words? [#what-are-filler-words] Filler words are the sounds people naturally make while thinking — "uh", "um", "hmm", "like", "you know". VoiceInk can automatically strip these from your transcription so your output reads cleanly without manual editing. ## Enabling Filler Word Removal [#enabling-filler-word-removal] Go to the **AI Models** tab → click the **gear icon** → scroll to the **Filler Words** section and toggle on **Remove filler words**. ## Default Filler Words [#default-filler-words] VoiceInk comes with a built-in list: `uh`, `um`, `uhm`, `umm`, `uhh`, `uhhh`, `hmm`, `hm`, `mmm`, `mm`, `mh`, `ehh` ## Adding Custom Filler Words [#adding-custom-filler-words] You can add any word to the list: 1. Type the word in the text field 2. Press Return or click the **+** button 3. The word is added as a chip — click the × on any chip to remove it This is useful for personal habits like "like", "basically", "you know", "right", or domain-specific filler you want to clean up. ## Notes [#notes] * Filler word removal is case-insensitive * It only removes standalone occurrences — if the word appears as part of a real word or phrase, it won't be removed * Works with both raw transcription and AI-enhanced output ## Related [#related] * [Word Replacements](/docs/word-replacements) — replace misheard words or expand abbreviations * [Correct Spellings](/docs/correct-spellings) — help the Whisper model recognize specific words # Common Issues (/docs/common-issues) ## Common Issues and Solutions [#common-issues-and-solutions] This page covers the most frequently encountered issues with VoiceInk and provides step-by-step solutions. ## License and Activation Issues [#license-and-activation-issues] ### Lost or Missing License Key [#lost-or-missing-license-key] If you've lost your license key or need to retrieve it: 1. **Visit the Polar Portal**: Go to [https://polar.sh/beingpax/portal/request](https://polar.sh/beingpax/portal/request) 2. **Enter Your Email**: Use the same email address you used when purchasing VoiceInk 3. **Access Your Purchases**: You'll receive a verification code to access your license information 4. **Copy Your License Key**: Once logged in, you can view and copy your license key ### License Activation Problems [#license-activation-problems] If you're unable to activate your current license: * **Check Device Limitations**: Ensure you're not using the license on a previous device * **Verify Plan Limits**: Your license is limited based on the plan you purchased * **Deactivate Previous Device**: If you've used the license on another device, deactivate it first For detailed license management information, see the [License Management](/docs/license-management) article. ## Transcription Issues [#transcription-issues] ### Transcription Failing [#transcription-failing] If VoiceInk is unable to transcribe your speech: * **Check Microphone Permissions**: Ensure VoiceInk has access to your microphone * **Verify Audio Input**: Check that your microphone is working and selected in System Preferences * **Restart the Application**: Sometimes a simple restart resolves audio detection issues For more details, see [Transcription Failing](/docs/transcription-failing). ### Transcription Taking Too Long [#transcription-taking-too-long] If transcription is slower than expected: * **Check Model Selection**: Ensure you're using an appropriate model for your device * **Verify System Resources**: Close other resource-intensive applications * **Consider Cloud Models**: For Intel Macs, cloud models may provide better performance Learn more in [Transcription Taking Too Long](/docs/transcription-taking-too-long). ### Poor Transcription Quality [#poor-transcription-quality] For accuracy issues: * **Use Power Mode**: Enable Power Mode for context-aware transcription * **Check Model Settings**: Ensure you're using the right model for your use case * **Review Personal Dictionary**: Add custom words and phrases to improve recognition ## Model and Language Issues [#model-and-language-issues] ### Model Changing Automatically [#model-changing-automatically] If your transcription model keeps switching: * **Check Power Mode Settings**: Power Mode may be changing models based on context * **Review App-Specific Configurations**: Check if you have different models set for different applications * **Disable Auto-Switching**: You can turn off automatic model switching in preferences See [Model or Language Changing Automatically](/docs/model-or-language-changing-automatically) for more information. ### Custom Model Problems [#custom-model-problems] If you're having issues with custom Whisper models: * **Verify Model Format**: Ensure your model is in the correct format * **Check File Location**: Place models in the designated VoiceInk models folder * **Restart Application**: Restart VoiceInk after adding new models ## Enhancement and Power Mode Issues [#enhancement-and-power-mode-issues] ### Power Mode Not Working [#power-mode-not-working] If Power Mode isn't functioning as expected: * **Check Permissions**: Ensure VoiceInk has accessibility permissions * **Verify App Detection**: Make sure the target applications are properly detected * **Review Configuration**: Check your Power Mode settings and rules ### Enhancement Prompts Not Working [#enhancement-prompts-not-working] If AI enhancements aren't functioning: * **Verify Model Selection**: Ensure you have a compatible model selected * **Check Internet Connection**: Some features may require internet access * **Review Settings**: Check your enhancement configuration ## Still Need Help? [#still-need-help] If you continue to experience issues: 1. **Check Related Articles**: Use the links above to find detailed articles 2. **Contact Support**: [Contact me](/contact) for personalized assistance 3. **Check System Requirements**: Ensure your Mac meets the minimum requirements For immediate license retrieval, always start with the [Polar Portal](https://polar.sh/beingpax/portal/request) using your purchase email address. # Transcription Taking Too Long (/docs/transcription-taking-too-long) ## Understanding Transcription Delays [#understanding-transcription-delays] If you find that transcription is slower than expected, there are a few factors that could be contributing to the delay. ### Local AI Models & Core ML Optimization [#local-ai-models--core-ml-optimization] VoiceInk uses local AI models for transcription. For optimal performance on **Apple Silicon** devices (M1, M2, M3, etc.), VoiceInk utilizes **Core ML**, Apple's machine learning framework. When you first download a non-quantized model, VoiceInk performs a **one-time optimization process** to prepare the model for Core ML. This can take **several minutes**, depending on your system's resources. Subsequent transcriptions using that model will be significantly faster, often 2-4x faster than without Core ML. If you are using an **Intel-based Mac**, local models are almost unusable. For the best UX, it is strongly recommended to use a **cloud-based transcription service** like Groq or Deepgram. You can configure these in the **[AI Models](/docs/transcription-models)** section of the app. ### AI Enhancement [#ai-enhancement] If you have [AI Enhancement](/docs/enhancements-configuring-models) enabled, this will add an extra step to the process, which can increase the time it takes to get your final text. The speed of this enhancement depends on the AI provider you are using. * **Gemini**: While powerful, Gemini can sometimes be slower, especially on the free tier. * **Groq**: Known for its very fast performance. ### Performance Analysis [#performance-analysis] If you want to understand exactly how long each part of the transcription process is taking, you can use the built-in performance analysis tool. 1. Go to the **[Transcription History](/docs/transcription-history)** tab. 2. Select the transcription you want to analyze. 3. At the bottom of the view, click the **Analyze** button. This will show you a breakdown of the time taken for each step, including: * **Transcription Time**: The time it took for the AI model to transcribe the audio. * **Enhancement Time**: The time it took for the AI enhancement to process the text (if enabled). # Model or Language Changing Automatically (/docs/model-or-language-changing-automatically) ## Why Are My Settings Changing? [#why-are-my-settings-changing] If you notice that your transcription model, language, or AI enhancement settings are changing automatically when you start recording, it is likely because you have **Power Mode** enabled. ### What is Power Mode? [#what-is-power-mode] [Power Mode](/docs/power-mode) is a feature that allows you to create different configurations for different applications or even specific websites. For example, you could have a configuration that automatically switches to a technical language model when you are in your code editor, and another that uses a more casual model when you are in your email client. ### How to Check if Power Mode is Active [#how-to-check-if-power-mode-is-active] Look at the VoiceInk menu bar icon. If Power Mode is active, you will see the emoji of the current configuration next to the icon. ### The Default Mode Is Applying Everywhere [#the-default-mode-is-applying-everywhere] A common cause of unexpected setting changes is a Power Mode marked as **Default**. A Default mode activates automatically in any app or website that doesn't have its own specific Power Mode configured — which means it can silently override your settings everywhere. To check for this: 1. Open VoiceInk → go to the **Power Mode** tab in the sidebar 2. Look for any mode marked as **Default** 3. Open that mode and uncheck the **Set as default** option if you don't want it applying globally ### How to Manage Power Mode [#how-to-manage-power-mode] * **Disable Power Mode**: If you don't want your settings to change automatically, you can disable Power Mode from the main menu. * **Customize Power Mode**: Edit your configurations to better suit your workflow in the Power Mode settings. # Repeated Text or Hallucinations (/docs/repeated-text-or-hallucinations) ## Issue: Repeated or Imaginary Text [#issue-repeated-or-imaginary-text] You might notice that sometimes your transcription contains words or phrases that you didn't actually speak, or words and phrases that get repeated. This is a phenomenon known as **hallucination**, where the AI model generates content that wasn't present in the original audio. Different AI models have different tendencies for this. For example, larger models might be more prone to hallucination in some cases, while smaller models might be less prone. ## Solution to Hallucination Issue [#solution-to-hallucination-issue] ### Turn on VAD [#turn-on-vad] Make sure that **Voice Activity Detection** is turned on. To do this, go to the **[AI Models](/docs/transcription-models)** tab, click the gear icon next to it AI Models filter. In the settings menu that appears, ensure that **Voice Activity Detection** is enabled. This helps to reduce repeated or hallucinated text in your transcriptions. If this doesn't help, the underlying model doesn't understand the audio correctly, so please use a different model for that case. ### Change Your AI Model [#change-your-ai-model] If you are experiencing hallucinations, the best solution is to try a different [transcription model](/docs/transcription-models). 1. Navigate to the **[AI Models](/docs/transcription-models)** tab in the VoiceInk application. 2. Select a different AI model from the list. I recommend trying a smaller model like **Base** or **Tiny** if you are experiencing issues with a larger one. 3. Go to the **[Transcription History](/docs/transcription-history)** view, find the recording you want to fix, and re-transcribe it with the newly selected model. # Transcription Failing/No Output or Accuracy issues (/docs/transcription-failing) ## Issue: No Transcription Output [#issue-no-transcription-output] If you are are using the app but VoiceInk isn't producing any transcribed text, or the transcription is failing, here are some common reasons and solutions. ### Audio Input Configuration [#audio-input-configuration] Make sure your microphone is set up correctly in VoiceInk and in your Mac's System Settings. 1. **Check VoiceInk Settings**: In VoiceInk's settings, confirm that the right microphone is chosen as your input device. 2. **Check Mac System Settings**: Go to System Settings > Sound > Input. Ensure your microphone is selected and the input level moves when you speak. ### Recommended Microphones [#recommended-microphones] For the best transcription quality: * **Built-in Microphones**: The microphones built into your Mac (especially MacBooks) are often good for voice input. * **External Microphones**: If your Mac doesn't have a high-quality built-in microphone, or if you need better performance, an external USB or professional microphone is highly recommended for clear audio. *** ## Issue: Inaccurate Transcription [#issue-inaccurate-transcription] If VoiceInk is producing text, but it's not accurate or contains many errors, your audio input might be the cause. ### Avoid Using Headphones as Input [#avoid-using-headphones-as-input] Many headphones (especially wireless ones) are not ideal for transcription. This can lead to inaccurate transcriptions or missing words. If you are using headphones and getting poor results, try switching to your Mac's built-in microphone or a dedicated external microphone. # Clipboard Issues (/docs/clipboard-issues) ## How VoiceInk Pastes Text [#how-voiceink-pastes-text] VoiceInk pastes transcribed text by temporarily placing it on your clipboard and sending Cmd+V to the active app. If **Restore Clipboard** is enabled in settings, it then restores whatever was on your clipboard before. All paste and clipboard settings are in **Settings → [Recording Feedback](/docs/recording-feedback)**. ## Old Clipboard Content Gets Pasted Instead of Transcription [#old-clipboard-content-gets-pasted-instead-of-transcription] This happens when the clipboard is restored before the paste completes — the timing between the paste and the restore is too tight, so the app ends up pasting your old clipboard content instead of the transcription. **Fix:** Go to VoiceInk **Settings** and increase the **Clipboard Restore Delay**. A value of 0.5–1 second usually resolves this. ## Transcription Overwrites Your Clipboard [#transcription-overwrites-your-clipboard] If **Restore Clipboard** is turned off, your previous clipboard content is replaced by the transcription after every recording. **Fix:** Enable **Restore Clipboard** in VoiceInk Settings so your original clipboard content is recovered after each paste. ## Text Is Transcribed But Nothing Gets Pasted [#text-is-transcribed-but-nothing-gets-pasted] This usually happens because the target app lost focus between when you stopped recording and when VoiceInk tried to paste. **Fix:** * Make sure you click into the app or text field before starting a recording * If the issue persists, try enabling **AppleScript Paste** in VoiceInk Settings, which uses a different paste method that works better in some apps # iOS and macOS Licenses Are Separate (/docs/ios-macos-license-confusion) ## My macOS License Doesn't Work on iPhone [#my-macos-license-doesnt-work-on-iphone] Your macOS VoiceInk license does **not** activate the iOS app — they are separate products. * The iOS app is currently **free while in beta** — no license key is needed * There is no field to enter a license key in the iOS app * iOS licensing will be handled separately through the App Store in the future ## I Bought a 2-Device License Thinking It Covered My iPhone [#i-bought-a-2-device-license-thinking-it-covered-my-iphone] The 2-device macOS license covers two Macs, not a Mac and an iPhone. If you purchased it expecting iPhone coverage, [contact support](/contact) and we'll sort out a refund or adjustment. ## Do I Need to Do Anything to Use the iOS App? [#do-i-need-to-do-anything-to-use-the-ios-app] No. Just download VoiceInk from the App Store and it's ready to use — no license key or account required during the beta period.