Help & Troubleshooting

VoiceDOM asks for mic permission once (not per-site) via a background page. If recording doesn't start:

1. Open the extension Settings → Microphone and click "Test microphone".
2. Check chrome://settings/content/microphone — VoiceDOM must not be blocked.
3. On macOS, also check System Settings → Privacy & Security → Microphone and make sure Chrome is allowed.
4. If you recently changed your default input device (e.g. plugged in headphones), restart the browser.

This usually means Chrome is capturing the wrong input device. Select the correct device in Settings → Microphone, then run a test recording. Bluetooth headsets can switch profiles mid-recording — if it keeps happening, try your laptop's built-in mic.

VoiceDOM is BYOK — the key must come from the provider you selected:

• Groq (free default): keys start with gsk_ — get one at console.groq.com
• OpenAI: keys start with sk-
• Deepgram / ElevenLabs / AssemblyAI: from each provider's dashboard

Make sure the key matches the selected provider in Settings, has no extra spaces, and (for OpenAI) that your account has credit.

1. Hit the retry button on the annotation — transient network errors are common.
2. Check the provider's status page (e.g. status.groq.com) — free tiers get rate-limited at peak hours.
3. Switch to another provider in Settings and retry. Your annotation and audio are never lost by a failed transcription.

Speak naturally but avoid heavy background noise. Technical terms ("div", "padding", component names) transcribe better on Whisper-based providers (Groq, OpenAI). If your notes are in Spanish or another language, Whisper handles them automatically — no setting needed. You can always edit a transcript before exporting.

Chrome blocks all extensions on certain pages: chrome:// pages, the Chrome Web Store, other extensions' pages, and some PDF viewers. On normal sites, if the picker doesn't start:

1. Refresh the tab after installing or updating VoiceDOM (content scripts only attach on load).
2. Check the site isn't blocked in chrome://extensions → VoiceDOM → "Site access".

Annotations are stored per hostname in local browser storage. Things to check:

• You're on the same hostname where you created them (app.example.com ≠ example.com, and localhost:3000 ≠ localhost:5173).
• You're in the same browser profile (not Incognito).
• "Clear browsing data" with "Hosted app data" checked wipes extension storage — annotations can't be recovered after that.

You can view everything saved per site in Settings → Annotations manager.

Selectors and XPath are captured at annotation time. If you redeploy with a different DOM structure, old selectors can go stale — that's expected. Each annotation also includes the page URL, element tag, and your note, so agents can usually still locate the element. For active development, annotate and hand off in the same session.

Component detection uses React fiber introspection and works on development and most production React builds. It won't show names when the site isn't React, or when a production build minifies component names (you'll see the CSS selector and XPath instead — the handoff still works).

1. Follow the setup guide for your client (Claude Code, Cursor, Codex).
2. Check Node.js 18+ is installed: node -v.
3. Verify the package runs: npx -y voicedom-mcp in a terminal (it should start and wait — Ctrl+C to exit).
4. Restart your MCP client after editing its config — most only read config on startup.
5. In Claude Code, run /mcp to confirm "voicedom" appears and is connected.

• The VoiceDOM extension must be running in your browser — it's what syncs annotations to the MCP server.
• Make sure you've actually saved annotations on the site (check Settings → Annotations manager).
• If you pass a hostname, it must match exactly: "localhost:3000", not "http://localhost:3000".
• MCP sync is a Pro feature — confirm Pro is active in the extension.

1. Open the extension and go to Settings → Plan → "Restore purchase" (payments are handled by ExtensionPay; it re-checks your license).
2. Make sure you're logged in with the same email you used at checkout.
3. If you reinstalled Chrome or use a new machine, restoring with that email re-activates Pro — it's a lifetime license, not tied to one device.

Still stuck? Forward your payment receipt to support@voicedom.dev and we'll activate it manually.

Email support@voicedom.dev within 30 days of purchase with the email you used at checkout. No questions asked.

API keys and annotations live in your local browser storage. Audio is sent only to the transcription provider you chose, with your own key — never to our servers. The MCP server runs locally on your machine. See the privacy policy for details.

Open Settings → Annotations manager to clear saved notes per site, or remove the extension to wipe everything (annotations, keys, preferences) — nothing is stored remotely.