Notice

Although super cool software, this is beta super cool software. Please be sure to test it before trusting it with mission-critical tasks, and (though it will be avoided as much as possible) configs / custom plugins may break between versions.

About audiencekit

audiencekit is a streamer-centric automation tool and bot platform:

• Pulls events (chat messages, donations, etc) from various livestreaming platforms, normalizing them into generalized types
• Provides a rich system for reacting to (or mutating) those events
• Exposes the end-result as a simple websocket event steam

Part of (but usable independent from) the Open Vtuber ToolKit

For (Power) Users

As you would hope, this system comes with batteries included, allowing you play sounds, do text-to-speech, control OBS, and much more, right out of the box. A love-it-or-hate-it decision, audiencekit assumes nothing about how you want these done, and instead lets you automate it all via plain-text config files.

That might seem scary at first, but if you've ever edited an ini file or messed with html, you'll be glad to know this just as (if not more) simple:

• The syntax, KDL, is inspired by the best of XML and command lines. Cuddly, just like you~
• The config is ran when the application starts (mostly) from top to bottom, and can be split up into multiple files.
• Things can be placed inside other things (like trigger), usually to make them happen later (rather than at application start), and sometimes to configure advanced properties.

For example, a simple raid automation looks like:

trigger event="Raid" {
  reply "Thank you very much for the raid!"
}

For developers

Extending audiencekit's automation abilities is made as simple as possible. For example, a plugin that automatically changes "simp" to "shrimp" in every message (as seen by those consuming this project's output) is simply:

from ovtk_audiencekit.plugins import PluginBase
from ovtk_audiencekit.events import Message

class Plugin(PluginBase):
    def on_bus_event(self, event):
      if isinstance(event, Message):
          event.text.replace('simp', 'shrimp')
      return event

Nearly all built-in functionality is written as plugins to help make them discoverable by example, so even if you're new to Python you should be able to copy + paste your way to a solution in no time (don't worry by the way, we all do that)!

Beside the plugin system, audiencekit's biggest feature is that it streams the events it sees (or generates internally) on a simple websocket, letting you use it as a quick way to pipe livestreaming data into anything else with websocket support!

Install

NOTE: Compiled builds are in progress! You currently have to install this as if you were a developer (the hard way, but it's not that bad, I believe in you~)

Manual / Development Install

1. Install dependencies

   You'll need Python 3.10, PDM, and some audio libraries. Not to fear though, there is instructions on how to do that for your specific OS!

2. Download the repository and open a terminal inside it

   Extract the tar / zip, or clone via git~

3. Run pdm sync

   Some dependencies may fail to install initially, but should be retried using a method that works automatically (your terminal should show "Retrying initially failed dependencies..." or similar).

   If the install still fails, I've likely missed something in the os-specific install instructions, so please feel free to open an issue with your OS and the error you got!

Installed! What now?

As alluded to earlier, audiencekit does nearly nothing by default.

If you want some more tutorializing, head on over to the Wiki. If you'd rather a crash-course:

• Read up a bit on KDL's syntax if you haven't already
• Crack open your favorite text editor and follow the instructions in the config.kdl file
• Open a terminal in the project location and start it using either:
  • pdm run start, or
  • activate the venv once per terminal session, and then use ./audiencekit.py start thereafter. This is recommended for development usage.
• Test your configuration using the ws subcommand (pdm run ws or ./audiencekit.py ws)
  • The built-in CLI will help for this and more! Just add "--help" to the end of anything, ie ./audiencekit.py --help, pdm run ws mkevent --help, etc
• Make mistakes and ask questions!

---

Made with ❤️ by the Vtopia Collective and contributors