twitch-bot/README.md

Luzifer / twitch-bot

Twitch-Bot is intended as an alternative to having a bot managed by Streamlabs or Streamelements and therefore having more control over it, the availability and how it works.

At the moment it is a work-in-progress and does not yet implment all features it shall in the future.

Configuration

Please see the Wiki for documentation of the configuration file.

# twitch-bot --help
Usage of twitch-bot:
      --base-url string                  External URL of the config-editor interface (set to enable EventSub support)
      --command-timeout duration         Timeout for command execution (default 30s)
  -c, --config string                    Location of configuration file (default "./config.yaml")
      --log-level string                 Log level (debug, info, warn, error, fatal) (default "info")
      --plugin-dir string                Where to find and load plugins (default "/usr/lib/twitch-bot")
      --rate-limit duration              How often to send a message (default: 20/30s=1500ms, if your bot is mod everywhere: 100/30s=300ms, different for known/verified bots) (default 1.5s)
      --storage-conn-string string       Connection string for the database (default "./storage.db")
      --storage-conn-type string         One of: mysql, postgres, sqlite (default "sqlite")
      --storage-encryption-pass string   Passphrase to encrypt secrets inside storage (defaults to twitch-client:twitch-client-secret)
      --twitch-client string             Client ID to act as
      --twitch-client-secret string      Secret for the Client ID
      --twitch-token string              OAuth token valid for client (fallback if no token was set in interface)
  -v, --validate-config                  Loads the config, logs any errors and quits with status 0 on success
      --version                          Prints current version and exits

# twitch-bot help
Supported sub-commands are:
  actor-docs                     Generate markdown documentation for available actors
  api-token <name> <scope...>    Generate an api-token to be entered into the config
  migrate-v2 <old file>          Migrate old (*.json.gz) storage file into new database
  help                           Prints this help message

Database Connection Strings

Currently these databases are supported and need their corresponding connection strings:

MySQL

[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...&paramN=valueN]

Recommended parameters:
  ?charset=utf8mb4&parseTime=True&loc=Local

• Create your database as follows:

  CREATE DATABASE twbot_tezrian DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci;
  

• Start your bot:

  # twitch-bot \
      --storage-conn-type mysql \
      --storage-conn-string 'tezrian:mypass@tcp(mariadb:3306)/twbot_tezrian?charset=utf8mb4&parseTime=True&loc=Local' \
      ...
  

See driver documentation for more details on parameters.

Postgres

host=localhost port=5432 dbname=mydb connect_timeout=10

See Postgres documentation for more details in paramters.

SQLite

storage.db

Just pass the filename you want to use.

• Start your bot:

  # twitch-bot \
      --storage-conn-type sqlite \
      --storage-conn-string 'storage.db' \
      ...
  

Upgrade from v2.x to v3.x

With the release of v3.0.0 the bot changed a lot introducing a new storage format. As that storage backend is not compatible with the v2.x storage you need to migrate it manually before starting a v3.x bot version the first time.

Before starting the migration make sure to fully stop the bot!

This section assumes you were starting your bot the following way:

# twitch-bot --storage-file storage.json.gz --twitch-client <clientid> --twitch-client-secret <secret>

To execute the migration we need to provide the same storage-encryption-pass or twitch-client / twitch-client-secret combination if no storage-encryption-pass was used.

# twitch-bot --storage-database storage.db --twitch-client <clientid> --twitch-client-secret <secret> migrate-v2 storage.json.gz
WARN[0000] No storage encryption passphrase was set, falling back to client-id:client-secret
WARN[0000] Module registered unhandled query-param type  module=status type=integer
WARN[0000] Overlays dir not specified, no dir or non existent  dir=
INFO[0000] Starting migration...                         module=variables
INFO[0000] Starting migration...                         module=mod_punish
INFO[0000] Starting migration...                         module=mod_overlays
INFO[0000] Starting migration...                         module=mod_quotedb
INFO[0000] Starting migration...                         module=core
INFO[0000] Starting migration...                         module=counter
INFO[0000] Starting migration...                         module=permissions
INFO[0000] Starting migration...                         module=timers
INFO[0000] v2 storage file was migrated

If you see the v2 storage file was migrated message the contents of your old storage file were migrated to the new storage-database. The old file is not modified in this step.

Afterwards your need to adjust the start parameters of the bot:

# twitch-bot --storage-database storage.db --twitch-client <clientid> --twitch-client-secret <secret>