Go to file
emerald 31cebbd71c
bump version
2024-01-09 15:55:11 -05:00
src fix: use raw body for chat processing 2024-01-09 15:54:30 -05:00
.dockerignore containerization 2024-01-03 22:58:06 -05:00
.gitignore containerization 2024-01-03 22:58:06 -05:00
Containerfile containerization 2024-01-03 22:58:06 -05:00
LICENSE Add LICENSE 2024-01-08 21:50:37 +00:00
README.md typo 2024-01-08 16:14:35 -05:00
bun.lockb update readme 2024-01-08 16:13:50 -05:00
compose.yml Update compose.yml 2024-01-08 22:21:43 +00:00
package.json bump version 2024-01-09 15:55:11 -05:00
tsconfig.json tweak for publishing 2024-01-04 18:06:00 -05:00

README.md

birchbot

An easy to use bot framrwork for owncast

env variables

Variable Default Value
BIRCH_PORT 8008
BIRCH_HOST localhost
BIRCH_CMD_DIR commands
BIRCH_HANDLER_DIR handlers
BIRCH_CMD_PREFIX !
BIRCH_REMOTE
BIRCH_TOKEN

installation

Docker Compose is an easy way to orchestrate docker containers. There is an example compose file in this repo that you can adapt to you needs or use as is. The quickest way to get started is to clone this repo:

git clone https://codeberg.org/AnActualEmerald/birchbot.git

Then:

cd birchbot
docker-compose up

And BirchBot should be up an running! See the usage section below for ways to add commands and customize behavior.

manual

If you want you can also run BirchBot witout docker. The only prerequisite is that you have bun installed. Then clone the repo and run:

bun install --production

This will install any dependencies without all the types and stuff used for development. Then you can start the server with:

bun run src

usage

By default BirchBot doesn't do anything when it recieves a WebHook from owncast. Its job is to dispatch the WebHook payloads to user-defined handlers. There are two main ways to define behavior for BirchBot: chat commands and webhook handlers. The breakdown is like this:

Event Type Handler (.ts|.js|.cjs)
CHAT commands/*
CHAT handlers/chat
NAME_CHANGED handlers/nameChanged
USER_JOINED handlers/userJoined
STREAM_STARTED handlers/streamStart
STREAM_STOPPED handlers/streamStop
STREAM_TITLE_UPDATED handlers/streamTitle
VISIBILITY-UPDATE handlers/visibility

Each file on the right should have a .ts, .js, or .cjs extension and must export a run function. That function should accept an argument that will be a Context<T> object, where the generic type is the value of Event Type in the table. The Context will contain the data from the webhook, as well as methods for sending API requests to the server.

chat commands

Handlers in the commands folder are treated somewhat differently. The name of the file will be the name of the command that it responds to. Command handlers also have a second argument passed to their run function which contains the rest of the text of the message in an array, split by spaces, excluding the name of the command itself. In order for an event to trigger a chat command the message must begin with the value of BIRCH_CMD_PREFIX, which defaults to !. The Context passed to a command handler also has some additional methods for replying to the user that invoked the command.

example handler

This is a very basic example that just logs out each chat message recieved

import type { Context } from "birchbot";
//handlers/chat.ts
export const run = async (ctx: Context<"CHAT">) => {
    console.log(ctx.event.user.displayName, "said", ctx.event.body, "at", ctx.event.timestamp);
}