====== 🤖 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.// ---- ===== 📋 Before You Start ===== Have these ready. It will save you a lot of back-and-forth. - 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. - A **payment card**. AI and voice services charge per use (usually pennies), and OpenAI and Azure both require one. - **About 30 minutes**. Step 2 and Step 5 are the longest. - A notepad open to paste keys into. Keep it **off stream**. ---- ===== 📂 Step 1: Unzip & Prepare ===== - Download the ''.zip'' file. - **Right-click** the file and select **Extract All**. - 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. ---- ===== 🟣 Step 2: Twitch Integration (The Hard Part) ===== //This is a one-time setup to let VoxAI read your chat. Please read carefully.// ==== A. Create the App on Twitch ==== - Make sure 2FA is on (see **Before You Start**). - Open the [[https://dev.twitch.tv/console/apps|Twitch Developer Console]]. - Log in and click **Register Your Application** (on the right). - 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.)// - 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. ==== B. Get Your Secrets ==== - Click **Manage** next to the app you just created. - Copy the **Client ID**. Save it in a notepad. - Click the **New Secret** button. - 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. ==== C. Connect VoxAI ==== - Go to your ''C:\VoxAI'' folder. - 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.// - Paste your **Client ID** and **Client Secret** when prompted. - 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. ---- ===== 🔑 Step 3: Login & License ===== - Run **''VoxAI.exe''**. - Enter the email and password you used to purchase VoxAI. - This binds the software to your PC. **✅ Checkpoint:** The main VoxAI window opens. ---- ===== 🧠 Step 4: Connect the Brain (AI) ===== //You need an API key to make the AI smart. Pick **ONE** provider below.// ==== 🟢 Option A: OpenAI (Recommended) ==== //Best for conversation quality and the most reliable choice.// - **⚠️ IMPORTANT:** You must set up **Billing** and add some credit in your OpenAI account first, or the key will not work. [[https://platform.openai.com/account/billing/overview|Add Credit Here]]. A few dollars goes a long way. - Go to [[https://platform.openai.com/api-keys|OpenAI API Keys]]. - Click **Create new secret key**. - Name it "VoxAI" and copy the key (starts with ''sk-...''). - In VoxAI: Go to **AI > AI Settings**. - Select **Provider: OpenAI** and paste your key. - **Model:** Leave the default. VoxAI keeps it up to date and switches automatically if OpenAI retires a model. ==== 🔵 Option B: Google Gemini ==== //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.// - Go to [[https://aistudio.google.com/app/apikey|Google AI Studio]]. - Click **Create API Key**. - In VoxAI: Go to **AI > AI Settings**. - Select **Provider: Gemini** and paste your key. - **Model:** Leave the default. VoxAI keeps it up to date and switches automatically if Google retires or overloads a model. - 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. ---- ===== 🗣️ Step 5: Give it a Voice (TTS) ===== //Pick **ONE** voice provider.// ==== ☁️ Option A: Azure Speech (Fastest & Cheapest) ==== //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"): - Go to the [[https://portal.azure.com/|Azure Portal]]. - Click on **Subscriptions**. You will be creating a "Pay as you go" plan. - Click the ''+ ADD'' button on this screen. - Click ''Add a different type of subscription''. - Choose ''Pay as you go''. - 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). - Click the ''Review + Create'' button. - Click the ''Create'' button. After creation, proceed to the next part. - Go back to the Home page for Azure. Then create the Speech Service that VoxAI will use: - Search for ''Speech services'' at the top in the search box and click the **Speech Services** result. - Click the ''+ Create'' button on the Speech Services page. - Select your Pay as you go subscription in the Subscription box. - In Resource Group, create a new group and call it "Main". - Region: Pick a region close to you (generally ''East US'' (''eastus'') will be fine). - In the Name box put "VoxAI". - In Pricing Tier choose ''Standard S0'' (that is a **zero**, not the letter O). **Do not choose the free tier!** - Click **Review + Create**, then **Create**. - Wait for deployment to finish, then click **Go to resource** (or "Deployment Details" and select "VoxAI").* - On the left menu, click **Keys and Endpoint** under Resource Management. - Copy **Key 1** and **Location/Region**. - In VoxAI: Go to **AI > AI Settings** -> **Voice Provider: Azure**. - 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. ==== 🎙️ Option B: ElevenLabs (High Quality, Higher Cost) ==== - Go to [[https://elevenlabs.io/|ElevenLabs]]. - Click your profile icon -> **Profile + API Key**. - Copy the API Key. - In VoxAI: Go to **AI > AI Settings** -> **Voice Provider: ElevenLabs**. - Paste the key and click **Fetch Voices**. - 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. ---- ===== 🎛️ Step 6: Final Config & Go Live ===== - **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). - **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.// - **Restart VoxAI:** * Close the app and open it again. - **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! ---- ===== ❓ Troubleshooting ===== 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. ==== 🟣 Twitch Setup ==== * **"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. ==== 🔇 Audio & Voice Issues ==== * **"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). ==== 🎬 OBS Integration ==== * **"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 & Logic ==== * **"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. ==== 🔐 Connection ==== * **"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.