WooferBot
DOCUMENTATION

TABLE OF CONTENT

Updating from older version

This section explains how to update WooferBot to newest version.

Update WooferBot on windows

  1. Download and extract latest WooferBot release over previous version.
  2. Start wooferbot.exe and close it after startup (This will add all new parameters into your configuration file and update any changes made between versions).
  3. Update your configuration as needed to use new features.

Update WooferBot on linux

  1. Download and extract latest WooferBot release over previous version.
  2. Go to wooferbot root directory
  3. Install dependencies python3 -m pipenv install
  4. Start python3 -m pipenv run python3 wooferbot.py and close it after startup (This will add all new parameters into your configuration file and update any changes made between versions).
  5. Update your configuration as needed to use new features.

Installation and use

This section explains installation process, broadcasting software setup and first run.

Download and prepare files on windows

  1. Download and extract latest WooferBot release.
  2. Start WooferBot using wooferbot.exe to create a default configuration file.

Download and prepare files on linux

WooferBot is developed using Python 3.9. It was confirmed to work on Python 3.5.

  1. Install python3, python3-pip
  2. Install pipenv python3 -m pip install pipenv
  3. Download and extract latest WooferBot release.
  4. Go to wooferbot root directory
  5. Install dependencies python3 -m pipenv install
  6. Start WooferBot using python3 -m pipenv run python3 wooferbot.py to create a default configuration file.

Note: Commands based on Ubuntu, may be different on other distributions. Note: You can create a shell file run wooferbot python3 -m pipenv run python3 wooferbot.py.

Configure your login information

Edit “settings.json” file and change login information for your twitch.tv account. These parameters are mandatory for bot to work.

{
    "TwitchOAUTH": ""
}

Never share your Twitch OAUTH with anyone. If someone has seen your OAUTH, generate a new one as soon as possible.

Add overlay

Add overlay.html as browser source into your broadcasting software (OBS, etc…).

Note: OBS seems to have an issue with “local file” option. If “local file” option does not work for you, open overlay.html in your browser and copy URL instead. Recommended width: 1000px
Recommended height: 500px

Best practices

Note: This approach will prevent using multiple browser sources, which would require more system resources and cause possible conflicts or missed notifications.

Starting WooferBot

To start WooferBot execute wooferbot.exe.

To customize WooferBot, adjust “settings.json” as needed (see Basic configuration section).

Basic configuration

This section explains basic configuration and global parameters.

Global parameters

Miscellaneous configurable parameters.

{
    "CurrentMascot": "malamute",
    "AlignMascot": "left",
    "GlobalVolume": 0.2,
    "MinBits": 0,
    "AutoShoutout": false,
    "AutoShoutoutTime": 10,
    "ShoutoutAccess": "mod"
    "Bots": []
}


Syntax:

"Bots": ["mybot1", "mybot2"]

Note: Following bots are already included: nightbot, streamlabs, streamelements, stay_hydrated_bot, botisimo, wizebot, moobot

Chat parser configuration

Customize notifications which relies on a chat parser.

{
    "HostMessage": "is now hosting you.",
    "AutohostMessage": "is auto hosting you",
    "FollowMessage": "Thank you for the follow!"
}

Chatbot configuration

This section explains how to enable and setup chatbot.

Enable chatbot

If you want to have WooferBot messages to appear in your chat, you have to enable chatbot. Note: You do not have to use special account for chatbot. If you dont, your main account will be used for chat messages.

{
    "TwitchBotOAUTH": "",
    "UseChatbot": false,
}

Never share your Twitch OAUTH with anyone. If someone has seen your OAUTH, generate a new one as soon as possible.

Customize speech bubble

This section explains how to customize color, shape and other properties for a speech bubble.

Styles

You can use styles to customize a speech bubble.

    "Styles": {
        "BackgroundColor": "#fef7ed",
        "BorderColor": "#ffba70",
        "BorderWidth": 4,
        "BorderRadius": 4,
        "BorderStrokeColor": "#ffffff",
        "TextFontFamily": "Fira Sans",
        "TextSize": 22,
        "TextWeight": 900,
        "TextColor": "#ffba70",
        "HighlightTextSize": 24,
        "HighlightTextSpacing": 3,
        "HighlightTextColor": "#ffba70",
        "HighlightTextStrokeColor": "#b16a16",
        "HighlightTextShadowColor": "#ffba70",
        "HighlightTextShadowOffset": 3
    }

Note: All colors are defined with hashtag, followed by 6-digit hexidecimal number. You can use web based color picker to choose or convert colors. Note: Size, width, radius, spacing and offset are defined in pixels.

Customize notifications and commands

This section explains how to customize notifications, add custom commands and timers.

Customize notifications and commands

“Messages” are used to customize replies to default notifications and commands. It is possible to define multiple replies for each message and have bot pick one at random.

Example:

    "Messages": {
        "greet": [
            "[Hello;Hi;Hey;Hewwo;Ello] {sender}, can I have some treats please?",
            "[Hello;Hi;Hey;Hewwo;Ello] {sender}!? Are you here to pet me? Or to give me wet food? Either one is fine, just let me know! ^..^"
        ],
        "sub": [
            "[Hello;Hi;Hey;Hewwo;Ello] {sender}, thank you for becoming our best friend ^..^"
        ]
    }

See List of predefined notification and commands section for all available notifications and commands.

Inline randomizer

Inline randomizer will allow you to randomize a message further by substituting the block with one of its options.

[Hello;Hi;Hey;Hewwo;Ello]

Note: Inline randomizers can be used multiple times in one message.

List of substitutes

Customize user activities

“Activities” are used for shoutout command to append customized stream category text. Same as with “Messages”, multiple reply lines and inline randomizer can be used. Blank space at the beginning of activity text is required.

Example:

    "Activities": {
        "Game": [
            " and they were last playing {activity}"
        ]
    }

List of substitutes


List of activities

Enabling/Disabling notifications and commands

You can enable or disable selective notifications and commands. By default, all notifications and commands are enabled.

Example:

    "Enabled": {
        "new_chatter": false,
        "greet": true
    }


See List of predefined notification and commands section for all available notifications and commands.

Mapping mascot poses to notifications

PoseMapping allows you to map available mascot poses to notification. All notification and commands will use DEFAULT mapping unless a mapping is created for them.

    "PoseMapping": {
        "DEFAULT": {
            "Image": "Wave",
            "Audio": "Wave"
        },
        "raid": {
            "Image": "Happy",
            "Audio": "Happy"
        },
        "!hello": {
            "Image": "Happy",
            "Audio": "Happy"
        }
    }

See List of predefined notification and commands section for all available notifications and commands.

List of predefined notification and commands

Create timed messages

This section explains how to create and edit timers.

Configuring custom timers/scheduled messages

Allows you to schedule a message to appear every X minutes.


Example:

    "ScheduledMessages": [
        {
            "Name": "Twitter",
            "Timer": 30,
            "MinLines": 5,
            "Enabled": true,
            "Command": "!twitter",
            "Image": "twitterlogo.png"
        }
    ]

List of parameters


To add text messages to timers, see Customize notifications and commands.

Mapping mascot poses to timed messages

PoseMapping allows you to map available mascot poses to timed messages. All notification and commands will use DEFAULT mapping unless a mapping is created for them.

    "PoseMapping": {
        "DEFAULT": {
            "Image": "Wave",
            "Audio": "Wave"
        },
        "Twitter": {
            "Image": "Happy",
            "Audio": "Happy"
        }
    }

Create custom commands

This section explains how to create custom commands.

Configuring custom commands

You can create simple custom replies using “Commands”.

Example:

    "Commands": {
        "!hello": {
            "Image" : "",
            "Script" : "",
            "Enabled": true,
            "ViewerOnce": false,
            "ViewerTimeout": 0,
            "GlobalTimeout": 0,
            "Access" : "",
            "Aliases": [
                "!hi",
                "!hey"
            ],
            "Hotkey": [
                "ctrl",
                "alt",
                "f12"
            ]
        }
    }

List of parameters


To add text messages to custom commands, see Customize notifications and commands.

Mapping mascot poses to custom commands

PoseMapping allows you to map available mascot poses to your custom commands. All notification and commands will use DEFAULT mapping unless a mapping is created for them.

    "PoseMapping": {
        "DEFAULT": {
            "Image": "Wave",
            "Audio": "Wave"
        },
        "!hello": {
            "Image": "Happy",
            "Audio": "Happy"
        }
    }

Create watchdog trigger

This section explains how to create and edit watchdog triggers.

Configuring custom watchdog trigers

Allows you to watch file for changes and trigger a notification.


Example:

    "Watchdog": [
        {
            "Name": "Now Playing",
            "Filename": "d:\\streaming\\now_playing.txt",
            "Enabled": true,
            "Command": "",
            "Message": "Now Playing: ",
            "Image": ""
        }
    ]

List of parameters

Note: Always use double backslash in Filename.

Mapping mascot poses to watchdog triggers

PoseMapping allows you to map available mascot poses to watchdog triggers. All notification and commands will use DEFAULT mapping unless a mapping is created for them.

    "PoseMapping": {
        "DEFAULT": {
            "Image": "Wave",
            "Audio": "Wave"
        },
        "Twitter": {
            "Image": "Happy",
            "Audio": "Happy"
        }
    }

Customize subscription and bit notifications

This section explains how to further customize notification for subscription and bits.

Create special notification ranges

You can define separate notification for specific amount or ranges.


Example:

    "CustomBits": [
        {
            "Name": "bits100",
            "From": 100,
            "To": 999
        },
        {
            "Name": "bits1000",
            "From": 1000,
            "To": 1000
        }
    ],
    "CustomSubs": [
        {
            "Name": "sub12",
            "Tier": "",
            "From": 12,
            "To": 12
        }
    ]

List of parameters

Note: You do not have to create a custom message for CustomBits/CustomSubs range. In that case, default bit message will be used. To add text messages to custom bit range, see Customize notifications and commands.

Customize viewer specific greetings

This section explains how to further customize viewer notifications.

Create viewer specific greeting messages

You can define special greeting message for any viewer. It is possible to define multiple replies for each message and have bot pick one at random.


Example:

    "Messages": {
        "viewer_testname": [
            "[Hello;Hi;Hey;Hewwo;Ello] {sender}, can I have some treats please?",
            "[Hello;Hi;Hey;Hewwo;Ello] {sender}!? Are you here to pet me? Or to give me wet food? Either one is fine, just let me know! ^..^"
        ]
    }

Note: If not defined, default “greet” message will be used. For more information about messages, see Customize notifications and commands.

Create viewer specific greeting pose mapping

You can map a separate post for special greeting for any viewer. Notification will be mapped to “greet” if not defined.


Example:

    "PoseMapping": {
        "viewer_testname": {
            "Image": "Wave",
            "Audio": "Wave"
        }
    }

Note: If not defined, default “greet” pose mapping will be used. Note: You have to use “viewer_” prefix for special greeting pose mapping.

Configure Philips Hue

This section explains how to integrate your Philips Hue lights and use them for notifications.

Initial configuration

Enable Philips Hue in the configuration file. IP will be automatically detected and quick setup will guide you and setup token.

{
    "HueEnabled": true,
    "HueIP": "10.0.0.1",
    "HueToken": "qwertyuiopasdfghjklzxcvbnm"
}

Note: Variables HueIP and HueToken are configured automatically.

Configuring Philips Hue lights for mascot poses

Add “Hue” variable into pose mapping and add all lights you want to use for each pose.

    "PoseMapping": {
        "follow": {
            "Image": "Wave",
            "Audio": "Wave",
            "Hue": {
                "Hue lightstrip outdoor 1": {
                    "Brightness": 100,
                    "Color": "#b16a16"
                },
                "Hue color lamp 1": {
                    "Brightness": 100,
                    "Color": "#ff0000"
                }
            },
            "HuePersistent": false
        }
    }

Configure nanoleaf

This section explains how to integrate Nanoleaf and use light scenes for notifications.

Initial configuration

Enable Nanoleaf in the configuration file. IP will be automatically detected and quick setup will guide you and setup token.

{
    "NanoleafEnabled": true,
    "NanoleafIP": "10.0.0.1",
    "NanoleafToken": "qwertyuiopasdfghjklzxcvbnm"
}

Note: Variables NanoleafIP and NanoleafToken are configured automatically.

Configuring Nanoleaf motions for mascot poses

Add “Nanoleaf” variable into pose mapping and enter Nanoleaf motion as its value.

    "PoseMapping": {
        "follow": {
            "Image": "Wave",
            "Audio": "Wave",
            "Nanoleaf": "Nemo",
            "NanoleafPersistent": false
        },
        "sub": {
            "Image": "Sub",
            "Audio": "Sub",
            "Nanoleaf": "Orange Beat"
        }
    }

Configure Yeelight

This section explains how to integrate your Yeelight lights and use them for notifications.

Initial configuration

Enable LAN Control for each Yeelight device you want to control using Yeelight APP.

Enable Yeelight in the configuration file.

{
    "YeelightEnabled": true
}

Note: You will have to name all your Yeelight lights during first run.

Configuring Yeelight lights for mascot poses

Add “Yeelight” variable into pose mapping and add all lights you want to use for each pose.

    "PoseMapping": {
        "follow": {
            "Image": "Wave",
            "Audio": "Wave",
            "Yeelight": {
                "Yeelight Lightstrip 1": {
                    "Brightness": 50,
                    "Color": "#0000ff",
                    "Transition": true,
                    "TransitionTime": 1000
                }
            },
            "YeelightPersistent": true
        }
    }

Creating a mascot

This section provides guidelines and explains how to create custom mascots.

Mascot images

For smooth looking transitions, all mascot images should follow these guidelines:


Recommended poses:

Directory structure

  1. Create a subdirectory within “Mascots” directory with the name of your mascot.
  2. Create following subdirectories within your mascot directory: “images”, “audio”
  3. Create an empty configuration file within your mascot directory: “mascot.json”


Example directory structure:

\mascots\mymascot\
\mascots\mymascot\audio\
\mascots\mymascot\images\
\mascots\mymascot\mascot.json

Configure mascot

Mascot configuration file is used to map mascot pose names to custom images and their parameters.


Example:

{
    "mascotImages": {
        "Idle": {
            "Image": "idle.png"
        },
        "Wave": {
            "Image": "wave.png",
            "MouthHeight": 87,
            "Time": 5000
        },
        "Happy": {
            "Image": "happy.png",
            "MouthHeight": 95,
            "Time": 7000
        },
        "Snack": {
            "Image": "snack.png",
            "MouthHeight": 90,
            "Time": 7000
        }
    },
    "mascotAudio": {
        "Wave": {
            "Audio": ["hi.mp3", "hello.mp3"],
            "Volume": 0.2
        },
        "Happy": {
            "Audio": ["happy.mp3"],
            "Volume": 0.2
        },
        "Snack": {
            "Audio": ["nom.mp3"],
            "Volume": 0.2
        }
    },
    "mascotStyles": {
        "MascotMaxWidth": 150
    }
}

Note: Configuration parameters are case sensitive. Changing parameter case will break them. Change only values or pose names. Note: JSON format requires comma to be present after every parameter within a block, except at the end (before closing curly brackets).

Pose naming rules and recommendations


List of recommended poses


List of image parameters


List of audio parameters


List of styles

Developing WooferBot

This section describes how to prepare WooferBot development environment and build from source.

Prepare development environment

WooferBot is developed using Python 3.8. It was confirmed to work on Python 3.5.

  1. pip install pipenv
  2. git clone https://github.com/tomaae/WooferBot.git
  3. cd WooferBot
  4. pipenv install -d

Building from source

Windows only: Execute build.cmd