===== ❓ Troubleshooting =====

Having trouble? Here are solutions to the most common issues.

//**Always check the Log Console (About > Log Console) for errors first.**//

----

==== 🔴 Symptom: "Twitch: Offline" or "Refresh Failed" (Red Text) ====
This means VoxAI cannot connect to Twitch chat.

  * **Cause A:** Your Twitch authorization tokens have expired or are invalid.
    * **Solution:** Close VoxAI, go to your installation folder, and run ''twitch_setup.exe'' again. Authorize the app to generate fresh tokens.
  * **Cause B:** Your internet connection is down or a firewall/antivirus is blocking VoxAI.
    * **Solution:** Check your internet connection. Add an exception for ''VoxAI.exe'' in your firewall and antivirus software.

==== 🔴 Symptom: "AI Ready" (Red Text) or "AI_ERROR" ====
This means your AI provider is not configured correctly or rejected the request.

  * **Cause A:** Missing or Incorrect API Key.
    * **Solution:** Go to **AI > AI Settings**. Ensure you have selected the correct **AI Provider** at the top (OpenAI or Gemini) and that the API key is pasted into the corresponding field.
  * **Cause B:** Billing/Credit Issues.
    * **Solution:** Even for "Free" trials, providers often require billing setup. Log into OpenAI or Google AI Studio and ensure you have active credits or a valid payment method.

==== 🔇 Symptom: AI is silent / "[TTS ERROR]" ====
The text appears in the chat window, but no voice is heard.

  * **Cause A:** Wrong Output Device.
    * **Solution:** Go to **Audio > Audio Output** and ensure your speakers/headphones (or Virtual Cable) are selected.
  * **Cause B:** Bad TTS Configuration.
    * **Solution:** Go to **AI > AI Settings**. Check your Voice Provider (Azure or ElevenLabs).
      * **Azure:** Ensure the **Region** is correct (e.g., ''eastus'', not "East US") and matches your Azure Portal exactly.
      * **ElevenLabs:** Ensure you have not run out of character characters for the month.

==== ⚠️ Symptom: Bot ignores Ads or Power-ups (Gigantify) ====
The bot works for chat, but stays silent during Ad Breaks or Gigantify events.

  * **Cause:** Missing Permissions (Scopes).
  * **Solution:** If you recently updated VoxAI, you **MUST** run ''twitch_setup.exe'' again. We added new permissions to detect Ads and Power-ups; the bot cannot see them until you re-authorize.

==== 🎤 Symptom: Push-to-Talk (PTT) isn't working ====
  * **Cause A:** Wrong Microphone.
    * **Solution:** Go to **Audio > Mic Selection** and ensure your primary microphone is selected.
  * **Cause B:** Muted Hardware/Windows.
    * **Solution:** Check physical mute switches. Right-click the Windows speaker icon > "Sound settings" and check input volume.
  * **Cause C:** Key Conflict.
    * **Solution:** Another app might be "stealing" the key. Go to **Audio > PTT Keybind** and try binding it to a mouse button instead.
  * **Cause D:** Exclusive Mode.
    * **Solution:** Some games take exclusive control of the mic. Go to Windows Sound Settings > Your Mic > Properties > Advanced and uncheck "Allow applications to take exclusive control".
  * **Cause E:** Permissions.
    * **Solution:** Run VoxAI as **Administrator**.

==== 🎬 Symptom: Overlays or Scene Switching not working ====
  * **Cause:** OBS WebSocket is disabled.
  * **Solution:** In OBS Studio, go to **Tools > WebSocket Server Settings**. Ensure "Enable WebSocket Server" is checked. Verify the Port (4455) and Password match your VoxAI plugin settings.

==== 💥 Symptom: Crash on Startup / Plugin Errors ====
  * **Cause A:** Corrupt Settings.
    * **Solution:** Delete the ''settings.json'' file in your VoxAI folder and restart. You will need to re-enter your API keys.
  * **Cause B:** Bad Plugin.
    * **Solution:** Go to **Plugins > Plugin Loader** and uncheck recently added plugins, or remove them from the ''/plugins/'' folder manually.

----
//If all else fails, try running **VoxAI.exe** as an Administrator to resolve Windows permission issues.//