🤖 VoxAI Installation Guide

Follow these steps in order. Do not skip ahead. Each step ends with a ✅ Checkpoint. If you don't see what it says, stop and fix that step before moving on.

📌 A note about other websites: Twitch, OpenAI, Google and Azure change their websites from time to time, so a button may have moved or been renamed since this guide was written. The steps are essentially the same, so look for the closest match to what is described. If you get stuck, ask in the VoxAI Discord.

Have these ready. It will save you a lot of back-and-forth.

1. A Twitch account with two-factor authentication (2FA) turned on. Twitch will not let you create an app without it. Turn it on at Twitch > Settings > Security and Privacy. Your email on the account must also be verified.
2. A payment card. AI and voice services charge per use (usually pennies), and OpenAI and Azure both require one.
3. About 30 minutes. Step 2 and Step 5 are the longest.
4. A notepad open to paste keys into. Keep it off stream.

1. Download the .zip file.
2. Right-click the file and select Extract All.
3. Move the extracted folder to a simple location (e.g., C:\VoxAI).
   • Do not run it from inside the zip file!
   • Avoid folders that Windows protects or syncs, like Program Files, Desktop or OneDrive.

✅ Checkpoint: You can open C:\VoxAI and see VoxAI.exe and twitch_setup.exe inside it.

This is a one-time setup to let VoxAI read your chat. Please read carefully.

1. Make sure 2FA is on (see Before You Start).
2. Open the Twitch Developer Console.
3. Log in and click Register Your Application (on the right).
4. Fill in the form exactly like this:
   • Name: Give it a unique name (e.g., MyStreamBot_YourName). Note: This name must be unique across ALL of Twitch, not just your account. If Twitch says the name is taken, add some numbers to it.
   • OAuth Redirect URLs: http://localhost:17563
     • Copy/Paste that URL exactly. It must look exactly like that: http (not https), no trailing slash, no spaces. Click Add after typing it, so it appears in the list.
   • Category: Chat Bot
   • Client Type: If you see this option, choose Confidential. (Only confidential apps get a Client Secret.)
5. Tick the I'm not a robot box, then click Create.

✅ Checkpoint: You can see your new app in the list on the console page.

1. Click Manage next to the app you just created.
2. Copy the Client ID. Save it in a notepad.
3. Click the New Secret button.
4. Copy the Client Secret. Save it in a notepad.
   • Warning: Do not show this Secret on stream!
   • Twitch only shows the Secret once. If you lose it, click New Secret again (this makes the old one stop working).

✅ Checkpoint: You have a Client ID and a Client Secret saved in your notepad.

1. Go to your C:\VoxAI folder.
2. Run twitch_setup.exe.
   • If Windows shows a blue “Windows protected your PC” screen, click More info > Run anyway. If your antivirus blocks it, allow the VoxAI folder.
3. Paste your Client ID and Client Secret when prompted.
4. A browser window will open. Make sure you are logged into the Twitch account you want VoxAI to use, then click Authorize.
   • Success! Your Twitch tokens are now saved.

✅ Checkpoint: The setup tool tells you it succeeded, and the browser page says authorization is complete.

1. Run VoxAI.exe.
2. Enter the email and password you used to purchase VoxAI.
3. This binds the software to your PC.

✅ Checkpoint: The main VoxAI window opens.

You need an API key to make the AI smart. Pick ONE provider below.

Best for conversation quality and the most reliable choice.

1. ⚠️ IMPORTANT: You must set up Billing and add some credit in your OpenAI account first, or the key will not work. Add Credit Here. A few dollars goes a long way.
2. Go to OpenAI API Keys.
3. Click Create new secret key.
4. Name it “VoxAI” and copy the key (starts with sk-…).
5. In VoxAI: Go to AI > AI Settings.
6. Select Provider: OpenAI and paste your key.
7. Model: Leave the default. VoxAI keeps it up to date and switches automatically if OpenAI retires a model.

Fast and very cheap, with a free tier. Requires VoxAI 1.3.3 or newer. If you are on an older version, use OpenAI instead.

1. Go to Google AI Studio.
2. Click Create API Key.
3. In VoxAI: Go to AI > AI Settings.
4. Select Provider: Gemini and paste your key.
5. Model: Leave the default. VoxAI keeps it up to date and switches automatically if Google retires or overloads a model.
6. The free tier has limits. If you run past them, set up a billing account in Google AI Studio.

Click SAVE in the settings window.

✅ Checkpoint: Type Hello in the chat box and press Enter. The bot should answer in text (the voice comes in the next step). If you see AI_ERROR or an error message, check the Troubleshooting section.

Pick ONE voice provider.

This is the longest step. Azure's website changes often, so use the names below as a guide rather than exact button positions.

First, create a payment plan (a “subscription”):

1. Go to the Azure Portal.
2. Click on Subscriptions. You will be creating a “Pay as you go” plan.
3. Click the + ADD button on this screen.
4. Click Add a different type of subscription.
5. Choose Pay as you go.
6. In the new window, give your Pay as you go subscription a name. You will need to add your payment information during this step (not covered here).
7. Click the Review + Create button.
8. Click the Create button. After creation, proceed to the next part.
9. Go back to the Home page for Azure.

Then create the Speech Service that VoxAI will use:

1. Search for Speech services at the top in the search box and click the Speech Services result.
2. Click the + Create button on the Speech Services page.
3. Select your Pay as you go subscription in the Subscription box.
4. In Resource Group, create a new group and call it “Main”.
5. Region: Pick a region close to you (generally East US (eastus) will be fine).
6. In the Name box put “VoxAI”.
7. In Pricing Tier choose Standard S0 (that is a zero, not the letter O). Do not choose the free tier!
8. Click Review + Create, then Create.
9. Wait for deployment to finish, then click Go to resource (or “Deployment Details” and select “VoxAI”).*
10. On the left menu, click Keys and Endpoint under Resource Management.
11. Copy Key 1 and Location/Region.
12. In VoxAI: Go to AI > AI Settings → Voice Provider: Azure.
13. Paste your Key and Region. Click Save.

*If you cannot find your created Speech Service or lost it somehow, head to the Azure home page, search for “VoxAI” and click the result.

1. Go to ElevenLabs.
2. Click your profile icon → Profile + API Key.
3. Copy the API Key.
4. In VoxAI: Go to AI > AI Settings → Voice Provider: ElevenLabs.
5. Paste the key and click Fetch Voices.
6. Select a voice and click Save.

This option is only recommended if you do not mind investing a lot more money to get a real sounding voice.

✅ Checkpoint: Type Hello in the chat box again. You should now hear the reply as well as see it.

1. Select Audio Devices:
   • Audio > Audio Output: Choose where you want to hear the bot (Speakers/Headphones).
   • Audio > Mic Selection: Choose your microphone (for voice commands).
2. Create the Persona:
   • AI > Persona: Give your bot a name (e.g., “GLaDOS”) and a personality (e.g., “Sarcastic robot”).
   • Tip: Be descriptive! “You are a helpful assistant” is boring. “You are a grumpy dwarf who loves gold” is fun.
3. Restart VoxAI:
   • Close the app and open it again.
4. Test It:
   • Look at the status bar. It should be green: Twitch: Connected.
   • Type Hello in the chat box and hit Enter.
   • If the bot replies with text and audio, you are ready to stream!

If VoxAI isn't behaving as expected, check these common solutions first. Open About > Log Console to see what VoxAI is reporting. It usually names the problem.

• “I can't register an app on the Twitch console.”
  • Turn on two-factor authentication (Twitch > Settings > Security and Privacy), make sure your email is verified, then refresh the developer console.
• “Twitch says the app name is taken.”
  • App names must be unique across all of Twitch. Add numbers or your channel name.
• “The browser says redirect URI mismatch” (or similar) when I click Authorize.
  • The OAuth Redirect URL on your Twitch app must be exactly http://localhost:17563: http, no trailing slash, no spaces. Fix it on the Manage page, click Save, and run twitch_setup.exe again.
• “No browser window opened” or the setup tool seems stuck.
  • Close twitch_setup.exe and run it again. Make sure no other copy of it is still open, and check that your antivirus or firewall isn't blocking it.
• “I lost my Client Secret.”
  • Click New Secret on the Twitch Manage page and use the new one.

• “I see the text in chat, but I hear no voice.”
  • Go to Audio > Audio Output and ensure the correct device is selected.
  • Check that your voice provider key and region are saved (Step 5).
  • If using a Virtual Audio Cable (VAC), ensure the cable is not muted in Windows Sound settings.
  • Exclusive Mode: Some applications (like games) take exclusive control of audio. Try disabling “Allow applications to take exclusive control” in your Windows Sound Device properties.

• “The mic isn't picking me up.”
  • Go to Audio > Mic Selection and re-select your microphone.
  • Ensure the “Mic Ready” text in the status bar turns Orange (“Listening”) when you press the Push-to-Talk key (Default: F10).

• “Overlays or Scene switching isn't working.”
  • In OBS Studio, go to Tools > WebSocket Server Settings.
  • Ensure “Enable WebSocket Server” is checked.
  • Verify the Port (Default: 4455) and Password match what is configured in VoxAI plugins.
  • Note: VoxAI requires OBS Studio version 28.0 or newer.

• “AI says 'AI_ERROR' or stops responding.”
  • Check Billing: Most of the time, this means your OpenAI or Gemini credits have run out, or a payment method is needed.
  • Check your key: Re-paste the API key in AI > AI Settings (no spaces before or after) and click Save.
  • Check Internet: A momentary drop in internet will cause the AI request to fail.
  • Check Log: Go to About > Log Console to see the specific error message from the provider.
• “The log says the AI model is busy or high demand.”
  • That is the provider being overloaded, not your setup. VoxAI automatically tries another model, and the next message usually works.
• “VoxAI says it switched to a different model.”
  • That's normal. The provider retired or restricted the old model, and VoxAI picked one that works for your key. You can change it in AI > AI Settings.

• “Bot is ignoring specific events (Ads / Gigantify).”
  • Scope Update Required: If you recently updated VoxAI, you MUST run twitch_setup.exe again.
  • We added new permissions (Scopes) for Ads and Power-ups. Running the setup tool authorizes these new features.

• “Twitch Status says 'Disconnected' in Red.”
  • Your login token may have expired. Close VoxAI, run twitch_setup.exe, authorize the app again, and relaunch VoxAI.
• “Key/Region Invalid” (Azure)
  • Double-check you copied the Region exactly (e.g., eastus, not East US) and that there are no spaces.