====== VoxAI Plugin API Reference ======

**Last Updated: 02/20/2026** (v1.2.1)

This reference lists the methods and attributes available via the ''app'' object passed to your plugin's ''register(app)'' function.

----

===== 🎙️ Audio Engine & Lip Sync =====

Plugins can listen to the raw volume levels of the bot's voice to create avatars, visualizers, or reactive lighting.

**How to use:** Register an event handler for ''audio_level''.

  * **tts_start** → No arguments. Fired the exact millisecond audio begins playing (useful for syncing hardware actions).
  * **tts_end** → No arguments. Fired when playback finishes.
  * **audio_level** → ''(level)''
    * Fired continuously (~50 times/sec) while audio plays.
    * ''level'' (//float//): The RMS amplitude (loudness). Silence is ''0.0''; Max is ''1.0+''.

----

===== 🧠 Core AI & Interaction =====

**app.ask_ai(prompt)**
Sends a text prompt to the currently active AI provider (GPT or Gemini) and gets a direct response.
  * ''prompt'' (//string//): The full question or instruction.
  * **Returns**: A //string// containing the response. //(Blocking call - use threading)//.

**app.speak_text(text)**
Generates audio from text and plays it immediately through the configured output device.

**app.synthesize_tts(text)**
Generates audio bytes but does **not** play them. Use this to prepare audio for the ''audio_queue''.
  * **Returns**: Audio ''bytes'', or ''None''.

**app.add_chat(message)**
Writes a message directly into VoxAI’s main chat log window.

**app.persona** (//string//)
Read-only attribute containing the name of the currently active AI persona.

----

===== 💾 Memory & Context =====

**app.last_stream_category** (//string//)
Retrieve the name of the game currently being played on Twitch (e.g., "Mon Bazou"). Updated automatically via EventSub. Use this to make AI prompts game-aware.

**app.add_to_persona_local_memory(username, message)**
Adds a line to the persona's "short-term memory" file for the current session.

**app.get_persona_local_memory_lines()**
Retrieves the recent lines from short-term memory as a list.

----

===== 📡 Twitch Interaction =====

**app.send_twitch_chat(message)**
Sends a message to Twitch chat. (Thread-safe).

**app.send_api_whisper(target_username, message)**
Sends a reliable whisper via the Twitch API.

**app.create_clip()**
Triggers a clip of the stream and posts the URL to chat.

**app.channel** (//string//)
The streamer’s lowercase username.

**app.is_channel_live()** → //bool//
**app.get_broadcaster_id()** → //string//

----

===== ⚡ Event Hooks =====

Register these with ''app.register_event_handler(event_name, function)''.

==== Stream Events ====
  * **sub** → ''(user, tier, streak)''
  * **gift** → ''(gifter, recipient, tier, is_anon)''
  * **giftbomb** → ''(gifter, count, tier, is_anon)''
  * **raid** → ''(raider, viewers)''
  * **follow** → ''(user_name)''
  * **bits** → ''(user, amount)'' (Universal bit event)
  * **redemption** → ''(user, reward_title, user_input, raw_event)'' (Channel Point Rewards)

**app.register_command(name, function)**
Registers a ''!command''. 
**Updated in v1.2.1:** Handler must now accept ''(args, user, tags=None)''. 
  * ''tags'' (//dict//): The raw Twitch EventSub payload. Contains ''badges'' (Moderator, Subscriber, VIP status), ''color'', and other metadata.

**app.plugin_chat_hooks** (//list//)
Append a function to this list to read every single chat message.
**Updated in v1.2.1:** Hook function should now accept ''(user, message, tags=None)''.

----

===== 🎬 OBS Control =====

**app.obs_switch_scene(scene_name)**
**app.obs_set_source_visibility(scene, source, visible)**
**app.obs_set_filter_enabled(source, filter, enabled)**
**app.obs_flip_source(scene, source, direction)**

----

===== 🎨 Overlays & UI =====

**app.add_plugin_menu_command(label, command)**
Adds a clickable item to the "Plugins" top dropdown menu.

**app.master**
Reference to the root window (required for creating ''tk.Toplevel'' or ''customtkinter'' windows).

----

===== 📚 Included Libraries =====

VoxAI imports these libraries globally. You can use them in your plugins without any additional installation.

  * **pydirectinput**: Hardware-level keyboard and mouse emulation for DirectX/Unity games.
  * **pygetwindow (imported as `gw`)**: OS-level window management (Focus detection/Window sizing).
  * **BeautifulSoup (`bs4`)**: For web scraping and parsing HTML.
  * **Requests**: For making HTTP calls to external APIs.
  * **Numpy**: For advanced math operations.
  * **Pillow (PIL)**: For image manipulation.
  * **CustomTkinter**: For building modern, dark-mode UI windows.