====== 📖 VoxAI User Guide ======

Welcome to your new AI co-host! This guide covers how to interact with VoxAI, use voice commands, and manage your stream.

===== 🗣️ How to Talk to VoxAI =====

There are two ways to interact with your AI companion: **Text** and **Voice**.

==== 1. Text Chat ====
You can type directly into the input box at the bottom of the VoxAI window.
  * **How to use:** Type your message and press **Enter** or click **Send**.
  * **Result:** VoxAI will read your message, think for a moment, reply in the chat window, and speak the response out loud.
  * //Use this for testing or silent communication during a stream.//

==== 2. Push-to-Talk (Voice) ====
You can speak to VoxAI using your microphone, just like talking to a real person.
  * **Default Key:** ''F10'' (This can be changed in **Audio > PTT Keybind**).
  * **How to use:**
    - **Hold down** the key.
    - Wait for the "Mic Ready" status to turn **Orange**.
    - Speak your question or command clearly.
    - **Release** the key.
  * **Result:** VoxAI will transcribe your audio, generate a response, and speak back to you.

----

===== 🎙️ Special Voice Commands =====

VoxAI listens for specific phrases to perform actions on your stream. You can say these via Push-to-Talk or type them in the text box.

==== "Clip That" ====
Creates a clip of the last 30 seconds of your stream.
  * **Command:** Say //"Clip that"// or //"Clip this"//.
  * **Requirement:** You must be **Live** on Twitch.
  * **Result:** VoxAI will instantly request a clip from Twitch, post the URL in the chat log, and confirm verbally (e.g., "Clip created!").

==== "Shields Up" (Shield Mode) ====
Instantly locks down your chat in case of a hate raid or harassment.
  * **Command:** Say //"Shields up"//.
  * **Result:** VoxAI will activate **Twitch Shield Mode** immediately. This usually prevents first-time chatters from posting and enables strict automod settings (depending on your Twitch configuration).

==== "Shields Down" ====
Returns your chat to normal.
  * **Command:** Say //"Shields down"//.
  * **Result:** Deactivates Shield Mode.

----

===== 📡 Automatic Stream Monitoring =====

VoxAI connects to Twitch EventSub to watch your stream in real-time. You don't need to do anything; the bot will react automatically to these events:

  * **New Follows:** Welcomes the new follower.
  * **Subscriptions & Resubs:** Thanks the user and mentions their streak.
  * **Cheers (Bits):** Reacts to the amount. (Note: Only cheers above your configured "Bits Threshold" trigger a voice response).
  * **Raids:** Announces the raider and the viewer count.
  * **Gift Subs / Gift Bombs:** Thanks the gifter.
  * **Hype Trains:** Announces when a train starts, levels up, or ends.
  * **Power-ups:** Reacts when viewers use **Gigantify**, **Message Effects**, or **On-Screen Celebrations**.
  * **Ad Breaks:** warns the stream when an automated or manual ad break begins.

//You can toggle any of these on or off in the **Twitch > Twitch Settings** menu.//

----

    
===== 🎆 Using Overlays =====

VoxAI comes with built-in visual effects that react to stream events. To use them, you must add them as **Browser Sources** in OBS.

==== Overlay URLs ====

Copy and paste these URLs into OBS Browser Sources:

| Effect | URL | Description |
| :--- | :--- | :--- |
| **Fireworks** | ''http://localhost:5000/fireworks'' | Explosive effects. Good for Subscriptions/Raids. |
| **Confetti** | ''http://localhost:5001/confetti'' | Gentle falling confetti. Good for Follows/Cheers. |
| **Full Overlay** | ''http://localhost:5003/full'' | Combines both effects in one source. |

**Recommended OBS Settings:**
  * **Width:** 1920
  * **Height:** 1080 (or your canvas resolution)
  * **Custom CSS:** Clear out the default CSS so the background remains transparent.
  * **Shutdown source when not visible:** Unchecked.

----

==== Customizing Triggers ====

Once added to OBS, you can decide exactly which Twitch events trigger which effects.

  - Go to **Overlays > Overlay Settings** in the VoxAI app.
  - Check the boxes to map events to effects.
  - //Example: You might want **Fireworks** for a Subscription, but only **Confetti** for a Follow.//

----  

===== 🎭 The Persona System =====

You can change VoxAI's personality on the fly.

  * **Switching Personas:** Go to **AI > Persona** and select a different file from the dropdown. The bot will instantly change its name, voice, and attitude.
  * **Memory:** VoxAI has "Short Term Memory." It remembers the last 5-10 interactions to keep the conversation flowing.
  * **Wiping Memory:** If the bot gets confused or stuck in a loop, go to **AI > Persona** and click **Wipe Memory**. This clears the current session's context.

----

===== 🧠 The Status Bar =====

At the bottom of the window, you will see the health of your bot:

  * **Thinking Status (Left):**
    * ''Idle'': Ready for input.
    * ''Working...'': Processing an AI response or generating audio.
  * **Twitch Status (Right):**
    * ''Connected'' (Green): Everything is good.
    * ''Disconnected'' (Red): Connection lost. Restart the app or check your internet.
  * **Mic Status (Right):**
    * ''Mic Ready'' (Green): Mic is initialized.
    * ''Listening'' (Orange): You are holding the PTT key.