====== 🤖 VoxAI Installation Guide ====== Follow these steps in order. **Do not skip ahead**. ===== 📂 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!// ---- ===== 🟣 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 ==== - 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.// * **OAuth Redirect URLs:** ''http://localhost:17563'' * //(Copy/Paste that URL exactly. It must look exactly like that.)// * **Category:** Chat Bot - Click **Create**. ==== 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!// ==== C. Connect VoxAI ==== - Go to your ''C:\VoxAI'' folder. - Run **''twitch_setup.exe''**. - Paste your **Client ID** and **Client Secret** when prompted. - A browser window will open. Click **Authorize**. * //Success! Your Twitch tokens are now saved.// ---- ===== 🔑 Step 3: Login & License ===== - Run **''VoxAI.exe''**. - Enter the email and password you used to purchase VoxAI. - This binds the software to your PC. ---- ===== 🧠 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.// - **⚠️ IMPORTANT:** You must set up **Billing** in your OpenAI account first, or the key will not work. [[https://platform.openai.com/account/billing/overview|Add Credit Here]]. - 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:** Select ''gpt-4o-mini'' (Cheap), ''gpt-5-mini'' (Cheap / Smartest) or ''gpt-5-nano'' (Cheapest). ==== 🔵 Option B: Google Gemini ==== //Great alternative, very fast.// - 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:** Select ''gemini-2.5-flash''. You will want to create a billing account if you want to use Gemini past it's free tokens account. **Click SAVE in the settings window.** ---- ===== 🗣️ Step 5: Give it a Voice (TTS) ===== //Pick **ONE** voice provider.// ==== ☁️ Option A: Azure Speech (Fastest & Cheapest) ==== - 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 plan subscription a name (you will need to add your payment information during this step - which is not covered here) - Then click the ''Review + Create'' button - Click the ''Create'' button. After creation proceed to next step - Proceed back to Home page for Azure. You will now need to create the Speech Service that you will use inside of VoxAI. - 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 that you created earlier 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 SO''. Do not choose free tier! - Click **Review + Create**, then **Create**. - Wait for deployment to finish, then click the "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 main page and search for "VoxAI" and click the result from the search. ==== 🎙️ 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. ---- ===== 🎛️ 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. ==== 🔇 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. * 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:** 99% of the time, this means your OpenAI or Gemini trial credits have expired, or a payment method is needed. * **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. * **"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.