GoetiaAI Knowledgebase

Welcome to the self-service guide for configuring, running, and troubleshooting GoetiaAI. This reference is organized to help you move from first-time setup to advanced workflows, with common fixes along the way.

Quick Start Checklist

  1. Install Python 3.12 from python.org and enable "Add Python to PATH" during setup.
  2. Collect API keys:
  3. Launch GoetiaAI by double-clicking launcher.exe in the project root (run once per session).
  4. Click the Settings tab and complete the onboarding wizard.
  5. Go to Stream and start the AI.
  6. Use the dashboard Start/Stop buttons (or hotkeys) to control the AI during streams.

Feature Overview

Cohost Conversation Engine

  • Three-way dialog: balances chat questions, your spoken commentary, and AI follow-ups.
  • Intent recognition: tiers messages into streamer info, gameplay, or general chat.
  • Cooldown awareness: throttles repeated answers so chat stays fresh.

Gameplay Intelligence

  • Connects build data, stored guides, and Reddit summaries for "best build" questions.
  • Injects build URLs automatically when guide sharing is enabled.
  • Rates up-to-date posts (score ≥3) and filters duplicates for high-signal replies.

Voice & Audio

  • F9 (Whispers): toggles microphone listening; transcript length and noise filters are built-in.
  • F10 (Cohost): disables both conversation AI and TTS when you need a solo segment.
  • TTS playback: queues VoiceVox (local, free), ElevenLabs (cloud, paid), or Google Cloud Chirp 3 HD (cloud, pay-as-you-go) responses so speech never overlaps and respects cooldown timing.

TTS Providers

  • Keys & Voices panel: pick VoiceVox (free, bundled), ElevenLabs (cloud), or Google Cloud Chirp 3 HD (cloud) from the dropdown on Settings > Keys and Voices. The service status entry updates based on your selection.
  • VoiceVox: Click "Start Engine" once to launch the bundled engine, then choose a character voice and test with the built-in sample. The VoiceVox Language setting translates English replies automatically when set to Japanese.
  • ElevenLabs: Provide your API key and voice ID. ElevenLabs usage appears in the console alongside OpenAI token information.
  • Google Cloud Chirp 3 HD: Download a service account JSON key, place it inside the keys folder, enter its path (for example keys/goetiaai-yourproject.json), then refresh voices to choose a Chirp 3 HD model. Rate and pitch sliders help you fine-tune the performance.

Stream Output

  • output.txt – timed captions for text overlays.
  • reply.html – HTML for a browser source to display the AI-selected chat message it's responding to.

Audio & OBS Setup

ElevenLabs Setup

  1. Create an ElevenLabs account at elevenlabs.io. Free plans currently include limited characters per month; higher tiers unlock additional voices and quotas.
  2. After signing in, open your profile menu → Profile Settings → API Keys, and click Generate Key. Give it a name (for example GoetiaAI) and copy the generated key—this is what you paste into GoetiaAI's "ElevenLabs API Key" field. Treat it like a password.
  3. Browse voices under Voices. To add a voice to your library (required for API usage), click the voice card, then hit Add to Library. Without this, the API will reject requests for that voice.
  4. Inside the same voice card, click the ID button. ElevenLabs copies the voice ID to your clipboard (a string like WzjKoUsNQDC5sycR2RkX). Paste this into GoetiaAI's "ElevenLabs Voice ID" field.
  5. Back in GoetiaAI Settings → Keys and Voices, choose ElevenLabs as the TTS provider, paste in your API key and voice ID, then click Save Settings. Stop and restart the AI so ElevenLabs becomes the active provider.
  6. If you see "voice not found" errors, confirm the voice is in your ElevenLabs library and that the ID matches exactly. For quota or model errors, check your ElevenLabs subscription tier and switch to a supported model in their dashboard.

VoiceVox Setup

  1. VoiceVox is bundled with GoetiaAI. To install it automatically, open Settings → Keys and Voices → VoiceVox and click Download Engine. When it finishes, click Start Engine to launch the bundled copy. If you prefer an external installation, install the official engine from voicevox.hiroshiba.jp and enter its API URL (usually http://localhost:50021).
  2. Once the engine is running, click Refresh Voice List (labelled "Test Voice" in onboarding/settings). GoetiaAI fetches the available speakers and populates the dropdown.
  3. Use the VoiceVox Language selector to choose how speech is handled:
    • English: Sends text to VoiceVox as-is. Apostrophes and hyphens are pre-processed to avoid awkward pauses.
    • Japanese: Automatically translates the GPT response to Japanese before sending it to VoiceVox. The original English text still appears in subtitles.
  4. Select a voice/speaker from the dropdown, then click Test Voice. The bundled engine responds with a short sample; if you're using an external install, ensure its HTTP API is reachable.
  5. Click Save Settings, then stop and restart the AI so VoiceVox becomes the active provider. The dashboard will display "Playing VoiceVox TTS" when the engine is used.
  6. If VoiceVox fails to respond, verify the engine status indicator on the settings page is green, and make sure VOICEVOX_API_URL in core/creds.py points to the correct host/port.

Google Cloud TTS Setup

  1. Visit console.cloud.google.com and sign in (or create a free Google account). Click the project dropdown in the header and choose New Project. Name it something easy to remember (for example GoetiaAI-TTS) and click Create.
  2. Select your new project, then open Billing. Attach an existing billing profile or create a new one. Chirp 3 HD voices require billing to be enabled, even when you're within the free trial credits.
  3. Go to APIs & Services → Library, search for "Text-to-Speech API," and click Enable. Without this step, Google will respond with "403 Cloud Text-to-Speech API has not been used" errors.
  4. Open APIs & Services → Credentials, click Create credentials → Service account, and follow the prompts. The default "Editor" role is sufficient; you don't need to assign extra permissions.
  5. Inside the service account page, open the Keys tab, click Add key → Create new key → JSON, and download the generated key file. This file is your secure credential—keep it private.
  6. Move the JSON file into GoetiaAI's keys directory (for example C:\Users\Username\Desktop\GoetiaAI\keys\goetiaai-tts.json). Create the folder first if it doesn't exist.
  7. Back in GoetiaAI Settings → Keys and Voices, choose Google Cloud Chirp 3 HD, enter the relative JSON path (for example keys/goetiaai-tts.json), then click Refresh Voices. Pick an English Chirp 3 HD voice and click Test Voice.
  8. If testing fails with a 403 or similar error, wait a minute for Google to register billing activation, then refresh voices again. Double-check that billing is linked and the JSON file path is correct.
  9. After a successful test, click Save Settings, stop the AI, and start it again so Google TTS becomes the active provider. Monitor usage from APIs & Services → Dashboard to stay on top of credits and costs.

Audio Routing

  1. For VTuber setups: Route the TTS audio (VoiceVox, ElevenLabs, or Google Cloud) into your VTuber model using a virtual audio cable (VB-CABLE or Voicemeeter).
  2. Set MICROPHONE_INDEX_NUMBER in core/creds.py to your streaming microphone to prevent feedback loops.
  3. Test audio playback by starting the AI and checking that TTS generates output.mp3 (ElevenLabs & Google Cloud) or output.wav (VoiceVox) files.

OBS Integration

  1. Add reply.html as a browser source to your OBS scene to display the AI's selected chat message it's responding to.
  2. Add output.txt as a text source (File input) to display AI responses as captions. Style the text source CSS to match your overlay design.
  3. Position and size both sources to fit your stream layout.
  4. Refresh browser sources after making changes to reply.html to see updates.

Setup Guides by Scenario

1. Standard Keyboard & Mouse Streamer

  1. Complete settings onboarding with schedule, channel type, and gameplay info.
  2. Map F9/F10/F8 (Stream Deck recommended).
  3. Use reply.html as a browser source for a branded on-stream cohost bubble.

2. VTuber + VTube Studio

  1. Route the TTS audio output (VoiceVox, ElevenLabs, or Google Cloud) into your VTuber model using a virtual cable (VB-CABLE or Voicemeeter).
  2. Enable mouth tracking on the audio input so GoetiaAI speech drives lip-sync.
  3. Set MICROPHONE_INDEX_NUMBER to your streaming mic to prevent feedback.
  4. Add the reply.html browser source to your OBS scene to display the AI's selected topic to reply to.
  5. Add output.txt as a text source to your OBS scene to display the AI's responses as captions, styling the CSS on the source to match your overlay.

3. Art / Creative Streams

  1. Fill "Tools & Materials" and "Commissions" fields in onboarding.
  2. Be as complete as possible if you want to refer viewers to specific digital brush packs or other materials.
  3. Use the default text overlay to show AI replies while hands stay on tablet/brush.

Daily Operations

Dashboard Flow

  1. Launch package_main.py (or packaged executable) and verify the service checks on the Stream tab.
  2. Update the settings with the stream category and any applicable build guide URL
  3. Use "Start AI" to spawn GoetiaAI in chat and start the conversation.
  4. "Stop AI" ends the current conversation thread—wait for the green confirmation before restarting.
  5. Any live settings require an AI restart to load the updates.

Hotkey Reference

HotkeyActionNotes
F8Usage SummaryPrints OpenAI usage for the current session.
F9Toggle WhispersStops microphone capture mid-stream.
F10Toggle CohostSilences on-stream AI + TTS, but continues chat text operations.

Troubleshooting & FAQ

AI Won't Connect to Twitch

  • Ensure the Start AI modal reports success; if not, check service_status.json.
  • Verify your Twitch OAuth token hasn't expired (regenerate at twitchapps.com/tmi).
  • If you see "Event loop is closed," click Stop AI, wait for the success modal, then Start again.

No Audio or TTS Playback

  • If you are using ElevenLabs, confirm the API key and voice ID are valid. For VoiceVox, ensure the bundled engine is installed and the status indicator shows "Connected".
  • If you are using Google Cloud, double-check the JSON key path, confirm billing is enabled on your project, and refresh the voice list to make sure a Chirp 3 HD voice is selected.
  • Check system sound output—TTS saves to output.mp3; if it exists, audio generated correctly.
  • Restart the AI after changing TTS settings or switching virtual cables.

Whispers Ignoring My Voice

  • Run python -c "import sounddevice as sd; print(sd.query_devices())" and set MICROPHONE_INDEX_NUMBER to the correct device.
  • Whispers ignore clips shorter than 10 characters or mostly filler words—speak full sentences for best results.
  • Toggle F9 off/on if the mic was muted before starting the AI.

Chat Questions Returning Wrong Info

  • Open Settings → About You to confirm location, channel type, schedule, and socials are filled.
  • After saving, stop and restart the AI so core/creds.py is reloaded.
  • Check prompt_chat.txt to verify the generated persona includes the latest details.

Reddit Answers Missing

  • Reddit search is skipped when the AI detects no relevant keywords—try including "best", "popular", or "worst".
  • Check console log for any actual error messages.

OBS Caption Not Updating

  • Ensure the OBS text source points to the correct output.txt path, and that it is not hidden underneath other overlay elements.
  • If using reply.html, refresh the browser source cache after layout changes.
  • If the filenames are missing from your GoetiaAI folder, Start AI once to create them, set them up in OBS once, then Stop AI until ready to stream.

Useful Files & Logs

  • core/creds.py – channel and feature configuration.
  • prompt_chat.txt – AI persona and tone directives.
  • README.md – contains additional troubleshooting steps and FAQ.

If you encounter an issue not covered here, check the console output; it will contain everything needed to diagnose configuration problems quickly.