Quick Start¶

Get StarStreamer running in 5 minutes! This guide will help you set up a basic streaming bot with chat commands.

Prerequisites¶

Make sure you have: - ✅ Python 3.11+ installed - ✅ uv package manager installed - ✅ Twitch account and API credentials

Step 1: Clone and Install¶

# Clone the repository
git clone https://github.com/Arross-Twitch/StarStreamer.git
cd StarStreamer

# Install dependencies (includes OBS and ElevenLabs support)
uv sync

Step 2: Configure Environment¶

Create a local development configuration:

# Copy the default config to your development config
cp config.yaml config.dev.yaml

Edit config.dev.yaml with your credentials:

# Twitch Configuration
twitch:
  client_id: "h1x5odjr6qy1m8sesgev1p9wcssz63"
  channel: "your_channel_name"

# Optional: OBS Configuration
obs:
  enabled: true
  host: "localhost"
  port: 4455
  password: "your_obs_password"

# Optional: ElevenLabs Configuration
elevenlabs:
  enabled: true
  api_key: "your_elevenlabs_api_key"

Getting Twitch Credentials

See Configuration Guide for detailed instructions on obtaining Twitch API credentials.

Step 3: Run StarStreamer¶

Start the bot with your development configuration:

CONFIG_FILE=config.dev.yaml uv run python src/main.py

You should see:

INFO: Starting StarStreamer...
INFO: Connected to Twitch EventSub
INFO: Subscribed to channel.chat.message for your_channel
INFO: Web interface available at http://localhost:8888
INFO: StarStreamer is ready!

Step 4: Test Your Bot¶

StarStreamer comes with several modules pre-installed. Try these commands in your Twitch chat:

Chat Module Commands¶

!hello - Get a friendly greeting
!ping - Check bot responsiveness
!commands - List available commands
!uptime - See stream uptime
!clip - Create a Twitch clip

RPG Module Commands¶

!balance - Check your virtual currency
!work - Earn currency (5-minute cooldown)
!daily - Get your daily bonus
!give @user amount - Transfer currency to another user
!gamble amount - Try your luck gambling
!leaderboard - See the richest users

ElevenLabs Module Commands (if enabled)¶

!tts <text> - Convert text to speech (max 500 characters)
!voices - List available voices from your ElevenLabs account
!ttshelp - Show TTS command help

Step 5: Add Custom Commands¶

You can add custom commands to existing modules. For example, edit src/modules/chat/actions/basic_commands.py:

from starstreamer import on_event
from starstreamer.triggers import trigger, CommandTrigger
from starstreamer.plugins.twitch import TwitchClient
from starstreamer.runtime.types import Event

@on_event("twitch.chat.message")
@trigger(CommandTrigger("!discord"))
async def discord_command(event: Event, twitch: TwitchClient):
    """Share Discord invite link"""
    await twitch.send_message(
        "Join our Discord: https://discord.gg/yourchannel"
    )

@on_event("twitch.chat.message") 
@trigger(CommandTrigger("!socials"))
async def socials_command(event: Event, twitch: TwitchClient):
    """Share social media links"""
    user = event.data.get("user", {})
    username = user.get("display_name", "friend")

    await twitch.send_message(
        f"@{username} Follow me on: "
        "Twitter: @yourhandle | "
        "YouTube: youtube.com/yourchannel"
    )

Restart StarStreamer and your new commands will be automatically loaded!

Step 6: Add Active Triggers ✨ New!¶

Active Triggers let you schedule tasks and monitor conditions automatically, without waiting for chat commands!

Timer-Based Actions¶

Create actions that run on schedules:

# Add to src/modules/chat/actions/basic_commands.py
from starstreamer.triggers import TimerTrigger

@on_event("active_trigger.execute")
async def hourly_reminder(event: Event, twitch: TwitchClient):
    """Send a reminder every hour"""
    if event.data.get("trigger_type") == "TimerTrigger":
        trigger = event.data.get("trigger")
        if trigger and trigger.name == "social_reminder":
            await twitch.send_message(
                "🔔 Don't forget to follow for updates! Social links: !socials"
            )

# Register the timer in your module's setup (see Module System docs)
# Timer: TimerTrigger(interval=3600, name="social_reminder")  # Every hour

State Monitoring¶

Monitor conditions and react automatically:

from starstreamer.triggers import ConditionTrigger
from datetime import datetime

@on_event("active_trigger.execute")
async def stream_schedule_reminder(event: Event, twitch: TwitchClient):
    """Remind about stream times during prime hours"""
    if event.data.get("trigger_type") == "ConditionTrigger":
        trigger = event.data.get("trigger")
        if trigger and trigger.name == "prime_time":
            await twitch.send_message(
                "🕒 It's prime time! Stream usually starts around 8 PM EST!"
            )

# Condition: ConditionTrigger(
#     condition=lambda: 19 <= datetime.now().hour <= 21,  # 7-9 PM
#     check_interval=300,  # Check every 5 minutes
#     once=True,  # Only once per condition becoming true
#     name="prime_time"
# )

Active Triggers vs Chat Commands

Chat Commands → React to viewer messages
Active Triggers → Proactive automation (timers, monitoring, conditions)

Use both together for a fully automated streaming experience!

Learn more: Active Triggers Guide

Step 7: Create Your Own Module¶

For more complex features, create a new module:

# Create module structure
mkdir -p src/modules/mymodule/actions
touch src/modules/mymodule/__init__.py
touch src/modules/mymodule/module.py
touch src/modules/mymodule/actions/__init__.py
touch src/modules/mymodule/actions/commands.py

Example module structure in src/modules/mymodule/module.py:

from modules.base import BaseModule

class MyModule(BaseModule):
    @property
    def module_name(self) -> str:
        return "mymodule"

    async def register_actions(self) -> None:
        # Import your actions to register them
        from modules.mymodule.actions import commands  # noqa: F401

See the Module System documentation for complete details.

Project Structure¶

StarStreamer/
├── src/
│   ├── main.py         # Application entry point
│   ├── modules/        # Feature modules
│   │   ├── base.py     # BaseModule abstract class
│   │   ├── chat/       # Chat commands module
│   │   ├── alerts/     # Stream alerts module
│   │   └── rpg/        # Economy/RPG module
│   └── starstreamer/   # Core framework
│       ├── core/       # Event bus, DI, decorators, active triggers
│       ├── plugins/    # Twitch, OBS integrations
│       ├── triggers/   # Command, cooldown, timer, state triggers
│       └── services/   # Business logic services
├── tests/              # Unit tests
├── data/               # SQLite database
└── config.yaml         # Your configuration

Web Interface¶

Open your browser to http://localhost:8888 to access the modern NiceGUI-based management interface:

📊 Dashboard - Real-time event statistics and system overview
⚙️ Settings - Comprehensive configuration management with tabbed interface
🧩 Modules - Enable, disable, and reload modules dynamically
📋 Events - Real-time event monitoring with filtering and history
🔗 Connections - OAuth platform integration management

The interface provides live updates and interactive controls for managing your StarStreamer instance without restarts.

Development Mode¶

For development with auto-reload:

# Run with hot reload enabled
uv run python src/main.py --reload

# Or with specific port
uv run python src/main.py --reload --web-port 8080

# Combined with debug logging
uv run python src/main.py --reload --web-port 8080 --debug

Hybrid Reload Strategy¶

StarStreamer uses an intelligent hybrid reload approach:

Module changes (modules/ directory) → Hot reload - Preserves connections and state
Core changes (src/starstreamer/ directory) → Full restart - Ensures safety for framework changes

This means you can iterate quickly on module development while maintaining robust handling of core framework modifications.

Troubleshooting¶

Bot Not Responding¶

Check your OAuth token has the required scopes: - user:read:chat - user:write:chat - user:bot - channel:bot

Use the URL in docs/guides/oauth-token.md to generate a proper token.

Connection Failed¶

Verify your config.yaml configuration:

# Test Twitch connection
uv run python -c "from starstreamer.plugins.twitch import TwitchClient; import asyncio; asyncio.run(TwitchClient().connect())"

Commands Not Working¶

Modules are automatically loaded from the src/modules/ directory. If your module isn't loading:

Check that your module extends BaseModule
Ensure your module is in src/modules/yourmodule/
Verify your actions are imported in the module's register_actions() method
Check logs for any import errors

Module Not Found Errors¶

Make sure you're running from the project root:

cd /path/to/StarStreamer
uv run python src/main.py

Next Steps¶

Now that you have StarStreamer running:

📖 Learn about the Module System
✍️ Write Your First Action
🎯 Explore Triggers and Filters
⏰ Master Active Triggers for automation
🔧 Study Advanced Configuration