08 Troubleshooting and FAQ

Troubleshooting & Frequently Asked Questions (FAQ)

This guide provides troubleshooting solutions for common audio, networking, and window configuration issues, followed by frequently asked questions.

---

1. Troubleshooting Guide

Issue 1: Microphone Not Capturing Speech (Waveform Stays Flat)

Cause:

Windows privacy settings or another application is blocking microphone access.

Solution:

1. Open Windows Settings ➔ Privacy & Security ➔ Microphone.
2. Ensure Microphone access is toggled ON.
3. Under Let desktop apps access your microphone, ensure ON is enabled.
4. Open the Windows Sound Control Panel (mmsys.cpl via Win+R), go to the Recording tab, and verify that your desired microphone is set as the Default Device.
5. In WishPilot, press Ctrl + Shift + M to verify that the mic is not muted.

---

Issue 2: Groq Whisper Returns "Transcription Error"

Cause:

The Groq API key is either missing, invalid, or rate-limited.

Solution:

1. Go to the Models & Audio tab in the Studio Dashboard.
2. Verify that your Groq API key starts with gsk_ and contains no accidental leading or trailing spaces.
3. Click the Ping Test button in the dashboard to verify live connectivity to api.groq.com.
4. If rate-limited, wait 60 seconds or generate a fresh key from console.groq.com/keys.

---

Issue 3: HUD Disappeared and Cannot Be Located

Cause:

The window was minimized to the Stealth Notch, moved off-screen, or hidden via shortcut.

Solution:

1. Press Ctrl + Shift + H twice to toggle between hidden and visible states.
2. Look at the very top center of your screen for the Stealth Notch (a small 230×34px dark pill). Click the expand icon on the notch to restore the full window.
3. Press Ctrl + Shift + X followed by Ctrl + Shift + H to reset the window coordinate bounds to default.

---

Issue 4: Clicks Are Not Registering on the Floating HUD

Cause:

Click-Through mode is active (SetIgnoreMouseEvents).

Solution:

1. When Click-Through mode is enabled, mouse events intentionally pass directly through the window to the underlying code editor.
2. Press Ctrl + Shift + C to disable Click-Through mode and restore normal mouse interactions.

---

Issue 5: Antivirus Heuristic Warning on Build

Cause:

SetWindowDisplayAffinity(WDA_EXCLUDEFROMCAPTURE) is a low-level Windows User32 API used to manage desktop window visibility. Some aggressive antivirus heuristics flag applications that call this API.

Solution:

WishPilot is 100% open-source under GPL-3.0. You can inspect every line of native platform code in electron/platform/windows.cjs. To resolve local antivirus warnings, add the WishPilot folder to your antivirus whitelist or build directly from source using npm run build.

---

2. Frequently Asked Questions (FAQ)

Q1: Does WishPilot store, record, or upload my audio to external servers?

No. WishPilot has no central backend, database, or analytics tracking. Audio chunks are converted to standard 16kHz WAV format in local memory and dispatched directly over encrypted HTTPS to Groq's official Whisper API endpoint. No audio is ever stored on disk or sent to any WishPilot-owned server.

Q2: Can I use WishPilot without internet access?

WishPilot includes an offline Simulation Mode that runs built-in realistic streaming responses without requiring internet access or API credentials. However, live voice-to-text (Groq Whisper) and dynamic LLM inference require an active internet connection to communicate with the chosen AI provider.

Q3: How much do API calls cost to run?

Extremely little:

• Groq Whisper Large v3 Turbo: Costs approximately $0.0018 to $0.003 per minute of audio transcribed, and Groq provides a generous free tier for developers.
• Groq LPU Inference: openai/gpt-oss-120b and llama-3.3-70b are free during developer preview tiers.
• A full 45-minute mock interview practice session typically costs less than $0.05 total.

Q4: Can I use WishPilot with multiple monitors?

Yes. You can drag the Floating HUD to any secondary or tertiary monitor. Windows Display Affinity will protect the window on whichever physical display it resides.

Q5: How do I report a bug or suggest a new feature?

You can open an issue on the official GitHub repository: https://github.com/vishwjeet27/wishpilot/issues

For contributions, please read .github/CONTRIBUTING.md.