Configuration

StarStreamer uses YAML-based configuration with environment variable substitution. This guide will help you set up your credentials and customize your bot.

Configuration Strategy

StarStreamer uses a dual-configuration approach to separate committed defaults from local development settings:

• config.yaml - Committed file with safe defaults for CI/tests
• config.dev.yaml - Local development file with your real API keys (not committed)

Quick Setup for Development

1. Use the provided development template:

   # config.dev.yaml is already provided as a development template
   # Just add your real API keys and credentials
   vim config.dev.yaml
   

Or copy from the default config:

cp config.yaml config.dev.yaml
vim config.dev.yaml

1. Add your credentials:

   # Edit the development config with your real API keys
   vim config.dev.yaml
   

2. Use your development config:

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

Configuration File Priority

StarStreamer loads configuration files in this order: 1. CONFIG_FILE environment variable path (if set) 2. STARSTREAMER_CONFIG environment variable path (if set) 3. config.yaml (default)

Configuration Setup

For Development (Recommended)

Create a local development configuration with your real credentials:

# Application Configuration
app:
  name: "StarStreamer"
  version: "0.6.0" 
  environment: "development"

# Database Configuration
database:
  path: "data/stream.db"

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

# OBS Configuration (Optional)
obs:
  enabled: false   # Set to true to enable OBS integration
  host: "localhost"
  port: 4455
  password: "your_obs_password"
  timeout: 60
  event_subscriptions: "minimal"
  custom_subscriptions: 0

# AI Integration using LiteLLM with OpenRouter
# Get your API key from https://openrouter.ai/keys
# Models are specified at the module level, not in configuration
ai:
  openrouter:
    enabled: false                         # Set to true to enable OpenRouter integration
    api_key: "${OPENROUTER_API_KEY}"      # OpenRouter API key (set via environment variable)

# ElevenLabs Configuration (Optional)
elevenlabs:
  enabled: false   # Set to true to enable TTS functionality
  api_key: "your_elevenlabs_api_key"

# Web Interface Configuration
web:
  host: "0.0.0.0"
  port: 8888

# Logging Configuration
logging:
  level: "INFO"
  file: ""

# Module Configuration
modules:
  chat: true
  rpg: true
  alerts: true
  obs: true
  timers: true
  ai: true        # Enable AI module (requires OpenRouter configuration)
  elevenlabs: true # Enable ElevenLabs TTS module

Twitch Configuration

Twitch OAuth Setup

StarStreamer uses implicit OAuth flow with a public Twitch application client:

1. Public Client Setup
2. StarStreamer includes a default public client ID: h1x5odjr6qy1m8sesgev1p9wcssz63
3. No client secret required for public clients

4. Uses implicit OAuth flow for secure token generation

5. Token Management

6. OAuth tokens are stored securely in the database (via VariableRepository)
7. Tokens are not stored in configuration files to prevent accidental commits

8. Web interface OAuth authorization is planned but not yet implemented

9. Generate OAuth Token

StarStreamer requires an OAuth token with EventSub scopes. Currently, tokens must be generated manually:

# See the OAuth token guide for step-by-step instructions
# docs/guides/oauth-token.md

Or use this authorization URL with the default public client:

https://id.twitch.tv/oauth2/authorize
?client_id=h1x5odjr6qy1m8sesgev1p9wcssz63
&redirect_uri=http://localhost:3000
&response_type=token
&scope=user:read:chat+user:write:chat+user:bot+channel:bot+moderator:read:followers

Required scopes for EventSub/Helix API: - user:read:chat - Read chat messages via EventSub - user:write:chat - Send chat messages via Helix API - user:bot - Appear as a bot in chat - channel:bot - Join channels as a bot - moderator:read:followers - Read follower events

Note: The token will be securely stored in StarStreamer's database, not in configuration files.

Channel Configuration

Required: Set your channel name in config.yaml:

twitch:
  channel: "your_channel_name"  # Without the # symbol

Optional: Specify the broadcaster ID directly (will be auto-fetched from channel name if not provided):

twitch:
  broadcaster_id: "123456789"

Note: StarStreamer will automatically fetch your broadcaster ID from your channel name, so you only need to set the channel field. The broadcaster_id is optional and only needed if you want to override the auto-fetch behavior.

OBS Configuration

Enable OBS WebSocket

1. Open OBS Studio (v28.0+)
2. Go to Tools → WebSocket Server Settings
3. Enable WebSocket Server
4. Set a password
5. Note the port (default: 4455)

Configure in StarStreamer

OBS_HOST=localhost
OBS_PORT=4455
OBS_PASSWORD=your_password_here

For remote OBS:

OBS_HOST=192.168.1.100
OBS_PORT=4455
OBS_PASSWORD=secure_password

Web Interface Configuration

Basic Settings

# Interface binding
WEB_HOST=0.0.0.0  # Allow external access
WEB_PORT=8888      # Web UI port

# Security
WEB_SECRET_KEY=your-secret-key-here  # For session management
WEB_CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

Authentication (Optional)

# Basic auth for web interface
WEB_USERNAME=admin
WEB_PASSWORD=secure_password

Logging Configuration

Log Levels

LOG_LEVEL=DEBUG    # DEBUG, INFO, WARNING, ERROR, CRITICAL

Log Output

# Console output
LOG_CONSOLE=true
LOG_CONSOLE_FORMAT=colored  # colored, json, simple

# File output
LOG_FILE=logs/starstreamer.log
LOG_FILE_ROTATE=true
LOG_FILE_MAX_SIZE=10485760  # 10MB
LOG_FILE_BACKUP_COUNT=5

Component-Specific Logging

# Adjust individual component levels
LOG_LEVEL_TWITCH=DEBUG
LOG_LEVEL_OBS=INFO
LOG_LEVEL_EVENTS=DEBUG
LOG_LEVEL_WEB=WARNING

Database Configuration (Optional)

For persistent storage:

# SQLite (default)
DATABASE_URL=sqlite:///starstreamer.db

# PostgreSQL
DATABASE_URL=postgresql://user:pass@localhost/starstreamer

# MySQL
DATABASE_URL=mysql://user:pass@localhost/starstreamer

Performance Tuning

Event Processing

# Event bus settings
EVENT_HANDLER_TIMEOUT=30  # Seconds before handler timeout
EVENT_HANDLER_MAX_CONCURRENT=50  # Max concurrent handlers
EVENT_QUEUE_SIZE=1000  # Max queued events

WebSocket Settings

# Twitch EventSub
TWITCH_WS_KEEPALIVE=30  # Keepalive interval
TWITCH_WS_RECONNECT_DELAY=5  # Reconnect delay
TWITCH_WS_MAX_RECONNECTS=10  # Max reconnection attempts

# OBS WebSocket
OBS_WS_TIMEOUT=10  # Request timeout
OBS_WS_HEARTBEAT=30  # Heartbeat interval

Development Configuration

Hot Reloading

StarStreamer provides intelligent hot reloading for rapid development. Enable it using the --reload command-line flag:

# Enable hot reloading during development
uv run python src/main.py --reload

# Combine with other development options
uv run python src/main.py --reload --log-level DEBUG --web-port 8080

Hot Reload Behavior: - Module changes (modules/ directory) → Hot reload (preserves connections) - Core changes (src/starstreamer/ directory) → Full restart (safe for framework changes) - Test files (test_*.py) → Ignored - Cache files (__pycache__/) → Ignored

Debug Mode

# Enhanced logging for development
LOG_LEVEL=DEBUG

# Enable detailed SQL logging
DB_ECHO=true

# Show detailed error tracebacks
DEBUG=true

Development vs Production

Development Mode:

# Development with hot reload and debug logging
uv run python src/main.py --reload --log-level DEBUG

Production Mode:

# Production with optimized settings
uv run python src/main.py --log-level INFO --web-port 8888

Testing

# Test configuration
TEST_MODE=true
TEST_TWITCH_MOCK=true
TEST_OBS_MOCK=true

# Use in-memory database for tests
DATABASE_PATH=:memory:

Configuration Priority

StarStreamer loads configuration in this order (later overrides earlier):

1. Default values (built-in)
2. config.yaml file - Primary configuration with environment variable substitution
3. Environment variables - Via ${VAR_NAME} or ${VAR_NAME:-default} substitution in YAML
4. Command-line arguments - Runtime parameter overrides

Example:

# Override port via command line
uv run python src/main.py --web-port 9000

# Override via environment variable
WEB_PORT=9000 uv run python src/main.py

Validating Configuration

Test your configuration:

# Validate all settings
uv run python -m starstreamer.config validate

# Test Twitch connection
uv run python -m starstreamer.config test-twitch

# Test OBS connection
uv run python -m starstreamer.config test-obs

Security Best Practices

1. Never commit sensitive configuration files

   config.*.yaml           # Environment-specific configs with secrets
   # config.yaml is included with safe defaults
   

2. Use strong passwords

3. OBS WebSocket password
4. Web interface password

5. Database passwords

6. Rotate tokens regularly

7. Twitch OAuth tokens expire

8. Regenerate on security concerns

9. Restrict access

   web:
     host: "127.0.0.1"  # Local only
     allowed_ips: "192.168.1.0/24"  # LAN only
   

Environment-Specific Configs

Production

# config.production.yaml
app:
  environment: "production"

logging:
  level: "WARNING"

web:
  host: "0.0.0.0"

database:
  path: "data/prod.db"

Development

# config.development.yaml  
app:
  environment: "development"

logging:
  level: "DEBUG"

web:
  host: "localhost"

database:
  path: "data/dev.db"

Testing

# config.test.yaml
app:
  environment: "test"

logging:
  level: "ERROR"

database:
  path: ":memory:"

Load specific environment:

# Load production config
cp config.production.yaml config.yaml
uv run python src/main.py

# Or specify config file directly
uv run python src/main.py --config config.production.yaml

Troubleshooting

Missing Configuration

ERROR: TWITCH_CLIENT_ID not set

Solution: Ensure config.yaml file exists with the required Twitch client_id and channel configuration.

Invalid OAuth Token

ERROR: 401 Unauthorized - Invalid OAuth token

Solutions: 1. Regenerate token with correct scopes using the guide in docs/guides/oauth-token.md 2. Ensure token is properly stored in StarStreamer's database (not in config files) 3. Verify token has required EventSub scopes for TwitchIO v3 compatibility

OBS Connection Failed

ERROR: Cannot connect to OBS WebSocket

Solutions: - Verify OBS WebSocket is enabled - Check password is correct - Ensure firewall allows connection - Verify OBS is running

AI Integration Configuration (Optional)

Getting OpenRouter API Key

1. Create an OpenRouter Account
2. Go to openrouter.ai
3. Sign up for an account

4. Add credits or choose a model with free tier access

5. Get Your API Key

6. Go to API Keys
7. Create a new API key
8. Set the OPENROUTER_API_KEY environment variable

Configure in StarStreamer

# AI Integration configuration
# Models are specified at the module level, not in configuration
ai:
  openrouter:
    enabled: true
    api_key: "${OPENROUTER_API_KEY}"

Or using environment variables:

# Set environment variable for OpenRouter API key
OPENROUTER_API_KEY=your_openrouter_api_key_here

Available Commands

Once configured, the following AI commands are available:

• !ask <question> - Ask the AI a question
• !explain <topic> - Get an explanation of a topic
• !tldr <text> - Get a summary of provided text

Model Selection

Models are specified at the module level within the AI commands, not in configuration files. The current implementations use:

AI Commands: - !ask and !explain use anthropic/claude-3.5-sonnet for comprehensive responses - !tldr uses anthropic/claude-3.5-haiku for faster summarization

Available OpenRouter Models: OpenRouter provides access to many AI models including: - anthropic/claude-3.5-sonnet - Best balance of quality and speed
- anthropic/claude-3.5-haiku - Faster responses for simple tasks - meta-llama/llama-3.1-8b-instruct:free - Free tier option - openai/gpt-3.5-turbo - Cost-effective - anthropic/claude-3-opus - Highest capability - openai/gpt-4o - Latest OpenAI model

To change models, modify the AI command implementations in src/modules/ai/actions/ai_commands.py.

Usage Examples

!ask What is the best programming language for beginners?
!explain machine learning
!tldr Machine learning is a subset of artificial intelligence that enables computers to learn and make decisions from data without being explicitly programmed for each task.

Troubleshooting AI Integration

Invalid API Key

ERROR: AI completion failed - Authentication failed

Solution: Verify your OpenRouter API key is correct and your account is active.

Model Not Available

ERROR: Invalid model name

Solutions: - Check OpenRouter Models for available options - Verify model name spelling in configuration - Ensure your OpenRouter account has access to the model

Rate Limiting

ERROR: Rate limit exceeded

Solution: Add credits to your OpenRouter account or wait for rate limit reset.

---

ElevenLabs Configuration (Optional)

Getting ElevenLabs API Key

1. Create an ElevenLabs Account
2. Go to elevenlabs.io
3. Sign up for an account

4. Choose a subscription plan (free tier available)

5. Get Your API Key

6. Go to your ElevenLabs Profile
7. Copy your API key from the profile page
8. Add it to your configuration

Configure in StarStreamer

# ElevenLabs Configuration
elevenlabs:
  enabled: true
  api_key: "your_elevenlabs_api_key_here"

Or using environment variables:

ELEVENLABS_ENABLED=true
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

Available Commands

Once configured, the following TTS commands are available:

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

Voice Selection

StarStreamer automatically uses the first available voice from your ElevenLabs account. The system will fetch available voices when the TTS commands are used.

Usage Examples

!tts Hello everyone, welcome to the stream!
!tts This is a test of the text-to-speech system
!voices

Troubleshooting ElevenLabs

Invalid API Key

ERROR: ElevenLabs API authentication failed

Solution: Verify your API key is correct and your ElevenLabs account is active.

No Voices Available

ERROR: No voices are available for TTS

Solutions: - Check your ElevenLabs subscription includes voice access - Verify API key has proper permissions - Check ElevenLabs service status

Rate Limiting

ERROR: ElevenLabs rate limit exceeded

Solution: Upgrade your ElevenLabs plan or wait for rate limit reset.

Next Steps

• Quick Start - Run your first bot
• Your First Action - Create custom commands
• Environment Variables Reference - Full list of options