VoxAI Plugin API Reference

Last Updated: 08/22/2026 (v1.3.2)

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

VoxAI routes all plugin interactions through an AppProxy boundary to safeguard the broadcaster's environment. Plugins do not have direct access to internal configuration files, OpenAI/Gemini keys, or Twitch secrets (app.config and app.twitch_settings will raise an Access Denied error). Always use the officially exposed methods and event handlers documented below.

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)
  • Fired for ALL subs and resubs. For initial subs, streak is “1”. For resubs, streak is cumulative months (e.g. “5”).
• prime_sub → (user) (Fired on Prime paid upgrades)
• gift → (gifter, recipient, tier, is_anon)
• giftbomb → (gifter, count, tier, is_anon)
• communitypayforward → (gifter, recipient)
• raid → (raider, viewers)
• shoutout → (shouter, viewers)
• follow → (user_name)
• cheer → (user, amount, message) (Fired when cheer meets streamer's alert threshold)
• raw_cheer_bits → (user, amount, message) (Fired for ALL bit cheers regardless of threshold)
• powerup → (user, type, cost) (Fired on Gigantify, Message Effects, and Custom Power Ups)
• redemption → (user, reward_title, user_input, raw_event) (Channel Point Rewards)

• hype_train_start → (level)
• hype_train_update → (level) (Fires when leveling up)
• hype_train_end → (level)
• hype_train_data → (data) (Dictionary with 'level', 'progress', and 'goal')

• obs_connection_changed → (is_connected) (Fired when OBS WebSocket connects or disconnects)

app.register_command(name, function) Registers a '!command'.

• Handler signature: function(args, user)
• Note: If you need chatter badges (Mod, Sub, VIP), use app.plugin_chat_hooks instead.

app.plugin_chat_hooks (list) Append a function to this list to read every single chat message.

• Hook signature: function(user, message, tags=None)
• tags (dict): The raw Twitch EventSub payload containing 'badges', 'chatter_user_id', and chat metadata.

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. Because VoxAI is compiled into a single executable, dynamically loaded plugins have direct access to these pre-packaged tools:

• sqlite3: Built-in lightweight SQL database engine. Perfect for storing historical plugin data, archives, or complex user stats.
• matplotlib: For generating advanced data visualizations, graphs, and charts. (Note: matplotlib.pyplot and matplotlib.backends.backend_tkagg.FigureCanvasTkAgg are explicitly bundled, allowing you to embed interactive dark-mode graphs directly into CustomTkinter UIs).
• CustomTkinter: For building modern, dark-mode UI windows and dashboards.
• pydirectinput: Hardware-level keyboard and mouse emulation for DirectX/Unity games.
• pygetwindow (`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 and array handling.
• Pillow (`PIL`): For image manipulation and processing.