jyapayne/stream-bot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial working version

Browse source
This commit is contained in:
Joey Yakimowich-Payne 2025-05-14 17:45:07 -06:00
commit ec1c5958ce
33 changed files with 4547 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

388
README.md Normal file
View file

@ -0,0 +1,388 @@
# Twitch Chat Interaction Bot
A simple Python bot that connects to Twitch chat and performs actions based on user commands.
## Features
- Easy connection to Twitch chat via IRC
- Command-based interaction system
- Simple API for adding custom commands
- Example commands included
- Queue system for asynchronous command processing
- Robust authentication handling with token management
- Advanced features (optional):
- Interactive polls and voting system
- Timer system for scheduled messages
- Points system for viewers
- Sound effects (Windows only)
- Game control (optional):
- Control games via Twitch chat
- Direct control mode for immediate actions
- Voting mode for democratic game control
- User stats tracking for game commands
- Streamer override mode for exclusive control
- Multiple input methods:
- Keyboard and mouse simulation
- Virtual Xbox controller emulation (Windows only)
## Requirements
- Python 3.6+
- Socket library (included in Python standard library)
- Requests library (`pip install requests`) for Twitch authentication
- For keyboard/mouse control: pynput library (`pip install pynput`)
- For Xbox controller emulation: vgamepad library (`pip install vgamepad`) - Windows only
- For queue functionality: huey library (`pip install huey`)
## Setup
1. Clone this repository:
```
git clone https://github.com/yourusername/stream-interact.git
cd stream-interact
```
2. Install dependencies:
```
pip install -r requirements.txt
```
3. Set up your Twitch API credentials:
- Go to [https://dev.twitch.tv/console/apps](https://dev.twitch.tv/console/apps)
- Create a new application (or use an existing one)
- Generate a client secret
- Note your client ID and client secret
- Run the setup script to generate authentication tokens:
```
python scripts/setup_twitch_auth.py
```
- For detailed authentication setup instructions, see [Authentication Setup Guide](docs/twitch_auth_setup.md)
4. Set your environment variables:
```
# On Windows
set TWITCH_USERNAME=your_bot_username
set TWITCH_CLIENT_ID=your_client_id
set TWITCH_CLIENT_SECRET=your_client_secret
set TWITCH_CHANNEL=your_channel_name
set TWITCH_ADMIN_USERS=bot_username,mod_username
# On Linux/Mac
export TWITCH_USERNAME=your_bot_username
export TWITCH_CLIENT_ID=your_client_id
export TWITCH_CLIENT_SECRET=your_client_secret
export TWITCH_CHANNEL=your_channel_name
export TWITCH_ADMIN_USERS=bot_username,mod_username
```
Alternatively, you can edit the `main.py` file and set these values directly.
5. Configuration file:
You can also create a `default_config.json` file in the root directory with the following structure:
```json
{
"admin_users": ["bot_username", "mod_username"],
"cooldown": 2.0,
"game_mode": "direct",
"input_type": "keyboard",
"use_queue": false,
"token_cache_file": "data/cache/token_cache.json",
"features": {
"advanced": false,
"game_control": false
}
}
```
6. Run the bot:
```
# Basic functionality
python main.py
# With advanced features
python main.py --advanced
# With game control (keyboard & mouse, direct mode)
python main.py --game-control
# With game control (Xbox controller, direct mode)
python main.py --game-control --input-type controller
# With game control (voting mode)
python main.py --game-control --game-mode vote
# With game control (Xbox controller, voting mode)
python main.py --game-control --game-mode vote --input-type controller
# With both advanced features and game control
python main.py --advanced --game-control
# Customize cooldown time (in seconds)
python main.py --game-control --cooldown 5.0
# With queue system for processing commands
python main.py --use-queue
# With additional admin users
python main.py --admin-users bot_username,mod_username
# With custom config file
python main.py --config my_config.json
```
## Admin Users
Admin users have the same permissions as the channel owner. This is useful if:
- You have a separate bot account that will be used on your channel
- You want to give moderators special privileges
- You're running the bot for another streamer
Admin users can:
- Stop the bot with !stop
- Check token status with !token
- Take control of the game with !takeover
- Start and end voting with !startvote and !endvote
- End polls with !endpoll
- Give points to users with !give
Admin users can be configured in three ways (in order of priority):
1. Command line: `--admin-users bot_username,mod_username`
2. Environment variable: `TWITCH_ADMIN_USERS=bot_username,mod_username`
3. Config file: `"admin_users": ["bot_username", "mod_username"]` in default_config.json
## Basic Commands
The bot comes with several example commands:
- `!hello` - The bot will say hello back to the user
- `!dice [sides]` - Roll a dice with the specified number of sides (default: 6)
- `!echo [message]` - The bot will echo back the provided message
- `!8ball` - Ask the Magic 8-Ball a question and get a random answer
## Advanced Features
When running with the `--advanced` flag, these additional commands become available:
### Voting System
- `!poll "Question" "Option1" "Option2" ["Option3"...]` - Start a new poll
- `!vote <number>` - Vote in the active poll
- `!endpoll` - End the active poll and show results
### Timer System
- `!timer <seconds> <message>` - Set a timer to send a message after specified seconds
### Points System
- `!points [@user]` - Check points for yourself or another user
- `!give <user> <points>` - Give points to a user (channel owner only)
### Sound Effects (Windows only)
- `!sound <sound_name>` - Play a sound effect
- Add .wav files to the `sounds` directory to use this feature
### Queue System
For high-volume chats or intensive commands, you can use the queue system:
```
# Start the bot with queue enabled
python main.py --use-queue
# Start a consumer in a separate terminal to process tasks
python -m huey.bin.huey_consumer src.queue.server.huey
```
For detailed documentation on the queue system, see [Queue System Guide](docs/queue.md)
## Game Control
The game control feature allows Twitch chat to control a game via keyboard/mouse inputs or a virtual Xbox controller.
### General Commands
- `!gamehelp` - Show available game control commands
- `!gamestats [@user]` - Check game control stats for a user
### Keyboard & Mouse Mode
When using keyboard & mouse mode (`--input-type keyboard`), the following commands are available:
- `!up` - Press W key (move up/forward)
- `!down` - Press S key (move down/backward)
- `!left` - Press A key (move left)
- `!right` - Press D key (move right)
- `!jump` - Press Space bar (jump)
- `!attack` - Press left mouse button (attack)
- `!interact` - Press E key (interact)
- `!inventory` - Press I key (inventory)
- `!skill1` - Press 1 key (skill 1)
- `!skill2` - Press 2 key (skill 2)
- `!skill3` - Press 3 key (skill 3)
- `!ultimate` - Press R key (ultimate ability)
### Xbox Controller Mode (Windows only)
When using controller mode (`--input-type controller`), the following commands are available:
- Movement:
- `!up` - Move left stick up (forward)
- `!down` - Move left stick down (backward)
- `!left` - Move left stick left
- `!right` - Move left stick right
- Camera:
- `!look_up` - Move right stick up
- `!look_down` - Move right stick down
- `!look_left` - Move right stick left
- `!look_right` - Move right stick right
- Action Buttons:
- `!jump` - Press A button
- `!action` - Press B button
- `!interact` - Press X button
- `!menu` - Press Y button
- Shoulder Buttons & Triggers:
- `!block` - Press left shoulder (LB)
- `!attack` - Press right shoulder (RB)
- `!aim` - Press left trigger (LT)
- `!shoot` - Press right trigger (RT)
- D-pad:
- `!item1` - Press D-pad up
- `!item2` - Press D-pad right
- `!item3` - Press D-pad down
- `!item4` - Press D-pad left
- Menu Buttons:
- `!start` - Press start button
- `!select` - Press select/back button
### Direct Mode
In direct mode, commands are executed immediately when received. Each user has a cooldown between commands to prevent spam.
### Vote Mode
In vote mode, commands are collected through voting:
- `!startvote [seconds]` - Start a vote session (streamer only)
- `!vote <command>` - Vote for a specific command
- `!endvote` - End the current vote session (streamer only)
After the voting period, the command with the most votes is executed.
### Streamer Override Mode
The streamer override feature allows the channel owner to take exclusive control of the game when needed:
- `!takeover` - Channel owner takes exclusive control (only their commands will work)
- `!givecontrol` - Return control to the chat (viewers can use commands again)
When streamer override is active:
- Only the channel owner's commands will be executed
- The channel owner bypasses all cooldowns that apply to viewers
- If there's an active vote, it will be cancelled
- Viewers cannot start new votes until the streamer gives control back
#### Controller Redirection
When using controller mode (`--input-type controller`), the streamer override feature includes physical controller redirection:
- When `!takeover` is used, the streamer's physical controller inputs are automatically redirected to the virtual controller
- This allows the streamer to directly control the game using their own controller during takeover
- The redirection ends automatically when `!givecontrol` is used
- Requires a physical controller to be connected to the PC running the bot
Requirements for controller redirection:
- pygame library (`pip install pygame`)
- A physical controller connected to the PC
- Windows operating system (due to vgamepad dependency)
This feature is particularly useful when the streamer needs to:
- Quickly navigate a challenging section of a game
- Demonstrate something specific to viewers
- Override the chat's decisions temporarily
### Customizing Game Controls
You can customize the key/button mappings in the code:
- For keyboard/mouse controls, edit the keyboard commands in `game_control.py`
- For Xbox controller, edit the controller commands in `game_control.py`
## Adding Custom Commands
You can easily add your own commands by creating a handler function and registering it with the bot:
```python
def my_custom_command(username, args, bot):
# Do something interesting
bot.send_message(f"@{username}, your command was processed!")
# In main.py
bot.register_command("mycommand", my_custom_command)
```
Users can then trigger this command by typing `!mycommand` in the Twitch chat.
## Advanced Usage
You can extend the TwitchBot class to add more functionality, such as:
- User permission levels
- Cooldowns for commands
- Custom events (subscriptions, follows, etc.)
- Integration with other APIs
### Queue System
For high-traffic channels or resource-intensive commands, the queue system allows you to process messages and commands asynchronously:
- Moves command execution to a background process
- Prevents the bot from getting overwhelmed during high activity
- Allows for distributed processing across multiple machines
- Provides statistics and monitoring capabilities
See [Queue System Documentation](docs/queue.md) for detailed setup and usage instructions.
## Authentication
The bot uses Twitch's Client Credentials Grant Flow for authentication:
1. Create a Twitch application at [dev.twitch.tv/console/apps](https://dev.twitch.tv/console/apps)
2. Get your Client ID and generate a Client Secret
3. Set these as environment variables:
```
TWITCH_CLIENT_ID=your_client_id
TWITCH_CLIENT_SECRET=your_client_secret
```
4. Run the authentication setup script:
```
python scripts/setup_twitch_auth.py
```
This will guide you through the authentication process and store your tokens.
For detailed authentication setup instructions, see [Authentication Setup Guide](docs/twitch_auth_setup.md)
### Token Management
The bot uses a token cache file to minimize API requests. When you run the bot:
1. It checks for a cached token in `twitch_token_cache.json`
2. If a valid cached token exists, it uses that token
3. If no valid token is found, it requests a new one from Twitch
4. The new token is saved to the cache file for future use
The token cache can be configured with these options:
```
# Use a custom token cache location
python main.py --token-cache /path/to/your/cache.json
# Check token status while the bot is running (channel owner only)
!token
```
## License
This project is open source and available under the MIT License.