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.

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+.

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.

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.

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

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

• 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).

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)

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).

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.