Troubleshooting

Common issues and how to resolve them. If your issue isn't listed here, use the bug report option in the Help menu.

Permissions Issues

VoxInk doesn't detect my hotkey

This is the most common issue. VoxInk needs both Accessibility and Input Monitoring permissions to detect hotkeys globally.

To fix this:

1. Open System Settings → Privacy & Security → Accessibility
2. Find VoxInk in the list and toggle it ON
3. Navigate to Privacy & Security → Input Monitoring and do the same
4. Restart VoxInk from the menu bar (click the icon → Quit, then relaunch)

"VoxInk wants to access the microphone" keeps appearing

This is normal on first use. Click Allow to grant microphone access. If you accidentally denied it:

1. Open System Settings → Privacy & Security → Microphone
2. Find VoxInk and toggle it ON

Permissions were granted but VoxInk still doesn't work

Sometimes macOS caches stale permission state. Try removing and re-adding the permissions:

1. Open System Settings → Privacy & Security → Accessibility
2. Toggle VoxInk OFF, then back ON
3. Repeat for Input Monitoring
4. Restart VoxInk

Audio Issues

No audio detected / very short recordings

• Check your microphone is working — open Voice Memos and record a test clip
• Make sure VoxInk has microphone permission (see Permissions section above)
• If using Bluetooth headphones, see the Bluetooth section below
• Try increasing your hold time — recordings shorter than 0.4 seconds are automatically discarded

Bluetooth headphone issues

Bluetooth audio can occasionally disconnect or mismatch input/output devices. VoxInk includes automatic recovery:

• If no audio is detected for 5+ seconds, VoxInk automatically resets the audio stream
• If you switch Bluetooth devices while VoxInk is running, it auto-detects the change

If problems persist:

1. Disconnect and reconnect your Bluetooth device from System Settings
2. Restart VoxInk from the menu bar
3. Try using the built-in microphone to confirm VoxInk itself is working

Audio quality is poor

• Use a headset or external microphone for best results
• Reduce background noise — close windows, move away from fans or air conditioning
• Speak clearly and at a normal pace
• The closer the microphone is to your mouth, the better the signal-to-noise ratio

Transcription Issues

Transcription is inaccurate

Several factors affect transcription accuracy. Try these in order:

• Use a larger model: Menu bar → Config → set stt_local_model to large-v3 for the highest accuracy
• Add custom vocabulary: Add frequently misrecognised words to your custom vocabulary list
• Enable Dental Terminology: If you're dictating medical or dental content, enable the dental vocabulary option
• Improve audio quality: Speak clearly with minimal background noise, and use a quality microphone
• Try a cloud provider: Switch to Deepgram or OpenAI for comparison — cloud models are trained on more data and may handle your accent or domain better

Transcription is slow

• Use a smaller model: Try small or large-v3-turbo for faster processing
• Try a cloud provider: Cloud transcription is typically faster than local processing
• Free up GPU resources: Close other GPU-intensive applications (video editors, games, other AI tools)
• First-run delay: The first transcription after launching VoxInk is slower because the model needs to load into memory. Subsequent transcriptions will be faster.

Model download stuck or failed

Whisper models are downloaded from HuggingFace on first use. If a download fails:

1. Check your internet connection
2. Check available disk space — models range from 75 MB (tiny) to 3 GB (large-v3)
3. Try downloading a smaller model first to confirm the download mechanism works
4. If the download is stuck, quit VoxInk and restart it to retry

Hotkey Issues

Wrong modifier key is being used

The default hotkey is Left Option (⌥). Your keyboard layout may map keys differently, especially on non-Apple keyboards.

• Try pressing all modifier keys to find which one VoxInk responds to
• Some keyboards label the Option key as Alt
• External keyboards may have different key mappings — check your keyboard's documentation
• You can change the hotkey in the menu bar under Hotkey

Double-tap lock isn't working

• Ensure Lock Mode is enabled: menu bar → Hotkey → Double-Tap to Lock
• The double-tap must be quick — within approximately 400ms
• Lock Mode requires a Pro plan or higher

Hotkey conflicts with other apps

Some applications capture modifier keys before VoxInk can detect them:

• Try a different hotkey — for example, switch from Left Option to Right Control
• Check if other global hotkey apps are running (e.g., Alfred, Raycast, Karabiner)
• VoxInk cannot capture keys that the system has reserved (such as Caps Lock without remapping)

Text Cleanup Issues

Cleanup is slow or not working

• Check that your AI backend is properly configured in the settings
• If using a local LLM, ensure the LLM server is running and accessible
• If using a cloud provider, verify your API key is valid and has available credits
• Try switching to the managed API (the default) to confirm cleanup works — this isolates whether the issue is with your custom backend

Text is being modified too aggressively

• Switch from Rephrase to Cleanup for lighter editing that preserves more of your original phrasing
• Or disable text cleanup entirely for raw transcription output
• If using a custom template, review your template instructions — overly broad instructions lead to aggressive changes

Network / Remote Issues

Remote dictation not sending to the remote machine

• Check the remote_url in your config file — make sure the IP address and port are correct
• Verify the receiver application is running on the remote machine
• Test network connectivity: can you ping the remote machine's IP address?
• Check firewall settings on the remote machine — port 9876 must be open for incoming connections

STT server not accessible from other devices

• Verify the server is enabled: Share on Network → Enable
• Note the IP address and port displayed in the Share on Network panel
• Ensure your firewall allows incoming connections on the configured port
• Try accessing the server URL from a browser on the other device to test connectivity
• Both devices must be on the same local network (or connected via VPN)

General Issues

VoxInk won't launch

1. Check Console.app for error messages — filter by "VoxInk" to find relevant logs
2. Try launching from Terminal to see error output: open /Applications/Vox\ Ink.app
3. Delete preferences and restart: remove ~/Library/Application Support/VoxInk/config.json
4. Re-download and reinstall from voxink.app/download

VoxInk is using too much memory or CPU

• Larger Whisper models consume more memory and CPU during active transcription
• Resource usage drops to near zero when VoxInk is idle (not transcribing)
• If resources are limited, switch to a smaller model like small or base
• Cloud transcription offloads processing entirely and uses minimal local resources

How to completely reset VoxInk

If you want to start fresh with a clean installation:

1. Quit VoxInk from the menu bar
2. Delete the config file: ~/Library/Application Support/VoxInk/config.json
3. Delete the app: drag Vox Ink from Applications to Trash
4. Remove permissions in System Settings → Privacy & Security (Accessibility, Input Monitoring, Microphone)
5. Re-download and install from voxink.app/download

Still Need Help?

If your issue isn't covered here, use the Help menu in VoxInk to:

• Report a Bug — submits a detailed bug report with system information to help us diagnose the issue
• Request a Feature — suggest improvements or new capabilities

You can also browse the full documentation at voxink.app/docs.