Configuration Reference¶

This reference covers all configuration options supported by StarStreamer via config.yaml. Options are organized by category and include default values, validation rules, and usage examples.

Configuration Loading¶

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

Built-in defaults - Hardcoded fallback values in Pydantic models
config.yaml file - YAML configuration file with environment variable substitution
Environment variables - Via ${VAR_NAME} substitution in YAML
Command-line arguments - Runtime parameters

Environment Variable Substitution¶

StarStreamer supports environment variable substitution in YAML using ${VAR_NAME} syntax:

twitch:
  client_id: "${TWITCH_CLIENT_ID:-h1x5odjr6qy1m8sesgev1p9wcssz63}"
  channel: "${TWITCH_CHANNEL}"

Configuration Variables¶

Twitch Authentication¶

Configuration for Twitch integration using implicit OAuth flow:

`TWITCH_CLIENT_ID`¶

Type: String
Required: No (has default value)
Default: h1x5odjr6qy1m8sesgev1p9wcssz63 (StarStreamer public client)
Description: Twitch application client ID for implicit OAuth flow
Example: TWITCH_CLIENT_ID=h1x5odjr6qy1m8sesgev1p9wcssz63
Validation: Must be non-empty string
Note: StarStreamer uses a public client with implicit OAuth flow - no client secret required

OAuth Token Storage¶

Type: Database storage (VariableRepository)
Required: Yes (for chat functionality)
Description: OAuth access token stored securely in StarStreamer's database
Storage Method: Automatically stored via VariableRepository on first setup
Security: Not stored in environment variables or config files to prevent accidental commits
Required Scopes:
user:read:chat - Read chat messages via EventSub
user:write:chat - Send chat messages via Helix API
user:bot - Appear as bot in chat
channel:bot - Join channels as bot
moderator:read:followers - Read follower events
How to get: See the guide in docs/guides/oauth-token.md

Channel Configuration¶

`TWITCH_CHANNEL`¶

Type: String
Required: Yes (if TWITCH_BROADCASTER_ID not set)
Description: Target channel name (without # symbol)
Example: TWITCH_CHANNEL=your_channel_name
Validation: Alphanumeric, underscores, length 4-25 characters

`TWITCH_BROADCASTER_ID`¶

Type: String (numeric)
Required: No (auto-fetched from channel name)
Description: Broadcaster's Twitch user ID
Example: TWITCH_BROADCASTER_ID=123456789
Validation: Must be numeric or empty
Usage: Set if you know the ID to avoid API lookup

`TWITCH_BOT_USER_ID`¶

Type: String (numeric)
Required: No (defaults to broadcaster_id)
Description: Bot's Twitch user ID
Example: TWITCH_BOT_USER_ID=987654321
Usage: Set if bot account differs from broadcaster

`TWITCH_BOT_USERNAME`¶

Type: String
Required: No
Description: Bot's username for auto-fetching bot_user_id
Example: TWITCH_BOT_USERNAME=my_bot_account

Optional Twitch Configuration¶

`TWITCH_REFRESH_TOKEN`¶

Type: String
Required: No
Description: OAuth refresh token for automatic token renewal
Example: TWITCH_REFRESH_TOKEN=abcdef123456
Security: Store securely, used for token refresh

`TWITCH_EVENTSUB_WEBSOCKET_URL`¶

Type: String (URL)
Required: No
Default: wss://eventsub.wss.twitch.tv/ws
Description: EventSub WebSocket endpoint
Example: TWITCH_EVENTSUB_WEBSOCKET_URL=wss://eventsub.wss.twitch.tv/ws

`TWITCH_API_BASE_URL`¶

Type: String (URL)
Required: No
Default: https://api.twitch.tv/helix
Description: Twitch API base URL
Example: TWITCH_API_BASE_URL=https://api.twitch.tv/helix

`TWITCH_WS_KEEPALIVE`¶

Type: Integer (seconds)
Required: No
Default: 30
Description: WebSocket keepalive interval
Example: TWITCH_WS_KEEPALIVE=30
Range: 10-300 seconds

`TWITCH_WS_RECONNECT_DELAY`¶

Type: Integer (seconds)
Required: No
Default: 5
Description: Delay between reconnection attempts
Example: TWITCH_WS_RECONNECT_DELAY=5
Range: 1-60 seconds

`TWITCH_WS_MAX_RECONNECTS`¶

Type: Integer
Required: No
Default: 10
Description: Maximum reconnection attempts
Example: TWITCH_WS_MAX_RECONNECTS=10
Range: 1-100

Database Configuration¶

`DATABASE_PATH`¶

Type: String (file path)
Required: No
Default: data/stream.db
Description: SQLite database file path
Example: DATABASE_PATH=/var/lib/starstreamer/stream.db

`DATABASE_URL`¶

Type: String (connection URL)
Required: No
Description: Alternative database connection URL

Examples:

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

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

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

Web Interface Configuration¶

`WEB_HOST`¶

Type: String (IP address)
Required: No
Default: localhost
Description: Web interface bind address

Examples:

WEB_HOST=localhost       # Local only
WEB_HOST=0.0.0.0        # All interfaces
WEB_HOST=192.168.1.100  # Specific IP

`WEB_PORT`¶

Type: Integer
Required: No
Default: 8888
Description: Web interface port
Example: WEB_PORT=8080
Range: 1024-65535 (non-privileged ports)

`WEB_SECRET_KEY`¶

Type: String
Required: No (generated if not set)
Description: Secret key for session management
Example: WEB_SECRET_KEY=your-super-secret-key-here
Security: Use long, random string for production

`WEB_CORS_ORIGINS`¶

Type: String (comma-separated URLs)
Required: No
Description: Allowed CORS origins
Example: WEB_CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

`WEB_USERNAME`¶

Type: String
Required: No
Description: Basic auth username for web interface
Example: WEB_USERNAME=admin
Security: Enable basic auth for production deployments

`WEB_PASSWORD`¶

Type: String
Required: No (if WEB_USERNAME is set)
Description: Basic auth password for web interface
Example: WEB_PASSWORD=secure_password_123
Security: Use strong password

`WEB_ALLOWED_IPS`¶

Type: String (comma-separated IPs/CIDRs)
Required: No
Description: IP whitelist for web interface access
Example: WEB_ALLOWED_IPS=192.168.1.0/24,10.0.0.1

OBS Integration Configuration¶

`OBS_HOST`¶

Type: String (hostname/IP)
Required: No
Default: localhost
Description: OBS WebSocket server hostname

Examples:

OBS_HOST=localhost       # Local OBS
OBS_HOST=192.168.1.50   # Remote OBS
OBS_HOST=obs.example.com # Remote host

`OBS_PORT`¶

Type: Integer
Required: No
Default: 4455
Description: OBS WebSocket server port
Example: OBS_PORT=4455
Range: 1-65535

`OBS_PASSWORD`¶

Type: String
Required: No (if OBS WebSocket has no password)
Description: OBS WebSocket server password
Example: OBS_PASSWORD=my_obs_password
Security: Use strong password in OBS settings

`OBS_WS_TIMEOUT`¶

Type: Integer (seconds)
Required: No
Default: 10
Description: OBS WebSocket request timeout
Example: OBS_WS_TIMEOUT=15
Range: 5-60 seconds

`OBS_WS_HEARTBEAT`¶

Type: Integer (seconds)
Required: No
Default: 30
Description: OBS WebSocket heartbeat interval
Example: OBS_WS_HEARTBEAT=30
Range: 10-300 seconds

`OBS_AUTO_RECONNECT`¶

Type: Boolean
Required: No
Default: true
Description: Enable automatic reconnection to OBS
Example: OBS_AUTO_RECONNECT=false
Values: true, false, 1, 0

`OBS_MAX_RECONNECT_ATTEMPTS`¶

Type: Integer
Required: No
Default: 5
Description: Maximum OBS reconnection attempts
Example: OBS_MAX_RECONNECT_ATTEMPTS=10
Range: 1-100

Logging Configuration¶

`LOG_LEVEL`¶

Type: String
Required: No
Default: INFO
Description: Global logging level
Values: DEBUG, INFO, WARNING, ERROR, CRITICAL
Example: LOG_LEVEL=DEBUG

`LOG_FILE`¶

Type: String (file path)
Required: No
Description: Log file path (console only if not set)
Example: LOG_FILE=logs/starstreamer.log

`LOG_CONSOLE`¶

Type: Boolean
Required: No
Default: true
Description: Enable console logging
Example: LOG_CONSOLE=false

`LOG_CONSOLE_FORMAT`¶

Type: String
Required: No
Default: colored
Description: Console log format
Values: colored, json, simple
Example: LOG_CONSOLE_FORMAT=json

`LOG_FILE_ROTATE`¶

Type: Boolean
Required: No
Default: true
Description: Enable log file rotation
Example: LOG_FILE_ROTATE=false

`LOG_FILE_MAX_SIZE`¶

Type: Integer (bytes)
Required: No
Default: 10485760 (10MB)
Description: Maximum log file size before rotation
Example: LOG_FILE_MAX_SIZE=5242880

`LOG_FILE_BACKUP_COUNT`¶

Type: Integer
Required: No
Default: 5
Description: Number of backup log files to keep
Example: LOG_FILE_BACKUP_COUNT=10
Range: 1-100

Component-Specific Logging¶

Set logging levels for individual components:

`LOG_LEVEL_TWITCH`¶

Type: String
Default: Inherits from LOG_LEVEL
Description: Twitch platform logging level
Example: LOG_LEVEL_TWITCH=DEBUG

`LOG_LEVEL_OBS`¶

Type: String
Default: Inherits from LOG_LEVEL
Description: OBS integration logging level
Example: LOG_LEVEL_OBS=WARNING

`LOG_LEVEL_EVENTS`¶

Type: String
Default: Inherits from LOG_LEVEL
Description: Event system logging level
Example: LOG_LEVEL_EVENTS=DEBUG

`LOG_LEVEL_WEB`¶

Type: String
Default: Inherits from LOG_LEVEL
Description: Web interface logging level
Example: LOG_LEVEL_WEB=ERROR

`LOG_LEVEL_DATABASE`¶

Type: String
Default: Inherits from LOG_LEVEL
Description: Database operations logging level
Example: LOG_LEVEL_DATABASE=WARNING

Performance Configuration¶

Event System¶

`EVENT_HANDLER_TIMEOUT`¶

Type: Integer (seconds)
Required: No
Default: 30
Description: Handler execution timeout
Example: EVENT_HANDLER_TIMEOUT=60
Range: 1-300 seconds

`EVENT_HANDLER_MAX_CONCURRENT`¶

Type: Integer
Required: No
Default: 50
Description: Maximum concurrent handlers
Example: EVENT_HANDLER_MAX_CONCURRENT=100
Range: 1-1000

`EVENT_QUEUE_SIZE`¶

Type: Integer
Required: No
Default: 1000
Description: Maximum queued events
Example: EVENT_QUEUE_SIZE=5000
Range: 100-50000

Development & Testing¶

`DEBUG`¶

Type: Boolean
Required: No
Default: false
Description: Enable debug mode
Example: DEBUG=true
Effects: More verbose logging, detailed error messages

`DEVELOPMENT_MODE`¶

Type: Boolean
Required: No
Default: false
Description: Enable development features
Example: DEVELOPMENT_MODE=true
Effects: Hot reload, dev-only endpoints

`HOT_RELOAD`¶

Type: Boolean
Required: No
Default: false
Description: Enable automatic reloading on file changes
Example: HOT_RELOAD=true
Requirements: DEVELOPMENT_MODE=true

`TEST_MODE`¶

Type: Boolean
Required: No
Default: false
Description: Enable test mode
Example: TEST_MODE=true
Effects: Uses in-memory database, mock services

`TEST_TWITCH_MOCK`¶

Type: Boolean
Required: No
Default: false
Description: Use mock Twitch client in tests
Example: TEST_TWITCH_MOCK=true

`TEST_OBS_MOCK`¶

Type: Boolean
Required: No
Default: false
Description: Use mock OBS client in tests
Example: TEST_OBS_MOCK=true

Environment-Specific Examples¶

Production Environment¶

# .env.production
# Twitch Configuration
TWITCH_CLIENT_ID=h1x5odjr6qy1m8sesgev1p9wcssz63
TWITCH_CHANNEL=your_channel

# Database
DATABASE_PATH=/var/lib/starstreamer/stream.db

# Web Interface
WEB_HOST=0.0.0.0
WEB_PORT=8888
WEB_SECRET_KEY=super-secure-production-key-here
WEB_USERNAME=admin
WEB_PASSWORD=secure-admin-password
WEB_ALLOWED_IPS=192.168.1.0/24

# Logging
LOG_LEVEL=WARNING
LOG_FILE=/var/log/starstreamer/app.log
LOG_FILE_ROTATE=true
LOG_FILE_MAX_SIZE=10485760
LOG_FILE_BACKUP_COUNT=10

# Performance
EVENT_HANDLER_TIMEOUT=60
EVENT_HANDLER_MAX_CONCURRENT=100

# Security
DEBUG=false
DEVELOPMENT_MODE=false

Development Environment¶

# .env.development
# Twitch Configuration
TWITCH_CLIENT_ID=h1x5odjr6qy1m8sesgev1p9wcssz63
TWITCH_CHANNEL=test_channel

# Database
DATABASE_PATH=data/dev.db

# Web Interface
WEB_HOST=localhost
WEB_PORT=8888

# OBS (local development)
OBS_HOST=localhost
OBS_PORT=4455
OBS_PASSWORD=dev_password

# Logging
LOG_LEVEL=DEBUG
LOG_CONSOLE=true
LOG_CONSOLE_FORMAT=colored

# Development Features
DEBUG=true
DEVELOPMENT_MODE=true
HOT_RELOAD=true

# Performance (relaxed for dev)
EVENT_HANDLER_TIMEOUT=300

Testing Environment¶

# .env.test
# Minimal config for tests
TEST_MODE=true
TEST_TWITCH_MOCK=true
TEST_OBS_MOCK=true

# Database (in-memory)
DATABASE_URL=sqlite:///:memory:

# Logging (quiet during tests)
LOG_LEVEL=ERROR
LOG_CONSOLE=false

# Minimal Twitch config for tests
TWITCH_CLIENT_ID=test_client_id
TWITCH_CHANNEL=test_channel

Loading Environment Files¶

Manual Loading¶

# Load specific environment
cp .env.production .env
uv run python src/main.py

# Or specify file directly
uv run python -m dotenv -f .env.production run python src/main.py

Programmatic Loading¶

from dotenv import load_dotenv
import os

# Load based on environment
env = os.getenv("ENVIRONMENT", "development")
dotenv_path = f".env.{env}"

if os.path.exists(dotenv_path):
    load_dotenv(dotenv_path)
else:
    load_dotenv()  # Fallback to .env

Validation Commands¶

Validate your configuration:

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

# Test specific connections
uv run python -m starstreamer.config test-twitch
uv run python -m starstreamer.config test-obs
uv run python -m starstreamer.config test-database

# Show current config (sanitized)
uv run python -m starstreamer.config show

Security Best Practices¶

Never commit sensitive configuration files (the main config.yaml is safe with defaults):

config.*.yaml           # Environment-specific configs with secrets
# config.yaml is included with safe defaults (no tokens)

Use environment-specific files:

config.production.yaml   # Production secrets
config.development.yaml  # Development config
config.test.yaml        # Test config
config.yaml             # Main config (included in repo)

Rotate tokens regularly:
Twitch tokens can expire
Regenerate on security concerns
Use refresh tokens when available

Restrict access in production:

WEB_HOST=127.0.0.1              # Local only
WEB_ALLOWED_IPS=192.168.1.0/24  # LAN only
WEB_USERNAME=admin              # Require auth
WEB_PASSWORD=strong_password    # Strong password

Use strong passwords:
OBS WebSocket password
Web interface credentials
Database passwords (if applicable)

Troubleshooting¶

Missing Required Variables¶

Error: TWITCH_CLIENT_ID not set or Missing Twitch client ID

Solution: Ensure config.yaml file exists with the required Twitch channel configuration. The client_id has a default value but can be overridden if needed.

Invalid OAuth Token¶

Error: 401 Unauthorized - Invalid OAuth token

Solutions: 1. Regenerate token: See the guide in docs/guides/oauth-token.md 2. Ensure token is stored in StarStreamer's database (not config files) 3. Check token has required EventSub scopes for TwitchIO v3 compatibility 4. Verify token hasn't expired

Database Connection Issues¶

Error: Failed to initialize database

Solutions: 1. Check DATABASE_PATH directory exists 2. Verify write permissions 3. For PostgreSQL/MySQL, verify connection string

Web Interface Access Issues¶

Error: Cannot access web interface

Solutions: 1. Check WEB_HOST and WEB_PORT settings 2. Verify firewall allows connections 3. Check WEB_ALLOWED_IPS if set 4. Try WEB_HOST=0.0.0.0 for external access

OBS Connection Failed¶

Error: Cannot connect to OBS WebSocket

Solutions: 1. Verify OBS WebSocket is enabled 2. Check OBS_HOST, OBS_PORT, and OBS_PASSWORD 3. Ensure OBS is running 4. Check firewall settings

Configuration Reference¶

Configuration Loading¶

Environment Variable Substitution¶

Configuration Variables¶

Twitch Authentication¶

TWITCH_CLIENT_ID¶

OAuth Token Storage¶

Channel Configuration¶

TWITCH_CHANNEL¶

TWITCH_BROADCASTER_ID¶

TWITCH_BOT_USER_ID¶

TWITCH_BOT_USERNAME¶

Optional Twitch Configuration¶

TWITCH_REFRESH_TOKEN¶

TWITCH_EVENTSUB_WEBSOCKET_URL¶

TWITCH_API_BASE_URL¶

TWITCH_WS_KEEPALIVE¶

TWITCH_WS_RECONNECT_DELAY¶

TWITCH_WS_MAX_RECONNECTS¶

Database Configuration¶

DATABASE_PATH¶

DATABASE_URL¶

Web Interface Configuration¶

WEB_HOST¶

WEB_PORT¶

WEB_SECRET_KEY¶

WEB_CORS_ORIGINS¶

WEB_USERNAME¶

WEB_PASSWORD¶

WEB_ALLOWED_IPS¶

OBS Integration Configuration¶

OBS_HOST¶

OBS_PORT¶

OBS_PASSWORD¶

OBS_WS_TIMEOUT¶

OBS_WS_HEARTBEAT¶

OBS_AUTO_RECONNECT¶

OBS_MAX_RECONNECT_ATTEMPTS¶

Logging Configuration¶

LOG_LEVEL¶

LOG_FILE¶

LOG_CONSOLE¶

LOG_CONSOLE_FORMAT¶

LOG_FILE_ROTATE¶

LOG_FILE_MAX_SIZE¶

LOG_FILE_BACKUP_COUNT¶

Component-Specific Logging¶

LOG_LEVEL_TWITCH¶

LOG_LEVEL_OBS¶

LOG_LEVEL_EVENTS¶

LOG_LEVEL_WEB¶

LOG_LEVEL_DATABASE¶

Performance Configuration¶

Event System¶

EVENT_HANDLER_TIMEOUT¶

EVENT_HANDLER_MAX_CONCURRENT¶

EVENT_QUEUE_SIZE¶

Development & Testing¶

DEBUG¶

DEVELOPMENT_MODE¶

HOT_RELOAD¶

TEST_MODE¶

TEST_TWITCH_MOCK¶

TEST_OBS_MOCK¶

Environment-Specific Examples¶

Production Environment¶

Development Environment¶

Testing Environment¶

Loading Environment Files¶

Manual Loading¶

Programmatic Loading¶

Validation Commands¶

Security Best Practices¶

Troubleshooting¶

Missing Required Variables¶

Invalid OAuth Token¶

Database Connection Issues¶

Web Interface Access Issues¶

OBS Connection Failed¶

See Also¶

`TWITCH_CLIENT_ID`¶

`TWITCH_CHANNEL`¶

`TWITCH_BROADCASTER_ID`¶

`TWITCH_BOT_USER_ID`¶

`TWITCH_BOT_USERNAME`¶

`TWITCH_REFRESH_TOKEN`¶

`TWITCH_EVENTSUB_WEBSOCKET_URL`¶

`TWITCH_API_BASE_URL`¶

`TWITCH_WS_KEEPALIVE`¶

`TWITCH_WS_RECONNECT_DELAY`¶

`TWITCH_WS_MAX_RECONNECTS`¶

`DATABASE_PATH`¶

`DATABASE_URL`¶

`WEB_HOST`¶

`WEB_PORT`¶

`WEB_SECRET_KEY`¶

`WEB_CORS_ORIGINS`¶

`WEB_USERNAME`¶

`WEB_PASSWORD`¶

`WEB_ALLOWED_IPS`¶

`OBS_HOST`¶

`OBS_PORT`¶

`OBS_PASSWORD`¶

`OBS_WS_TIMEOUT`¶

`OBS_WS_HEARTBEAT`¶

`OBS_AUTO_RECONNECT`¶

`OBS_MAX_RECONNECT_ATTEMPTS`¶

`LOG_LEVEL`¶

`LOG_FILE`¶

`LOG_CONSOLE`¶

`LOG_CONSOLE_FORMAT`¶

`LOG_FILE_ROTATE`¶

`LOG_FILE_MAX_SIZE`¶

`LOG_FILE_BACKUP_COUNT`¶

`LOG_LEVEL_TWITCH`¶

`LOG_LEVEL_OBS`¶

`LOG_LEVEL_EVENTS`¶

`LOG_LEVEL_WEB`¶

`LOG_LEVEL_DATABASE`¶

`EVENT_HANDLER_TIMEOUT`¶

`EVENT_HANDLER_MAX_CONCURRENT`¶

`EVENT_QUEUE_SIZE`¶

`DEBUG`¶

`DEVELOPMENT_MODE`¶

`HOT_RELOAD`¶

`TEST_MODE`¶

`TEST_TWITCH_MOCK`¶

`TEST_OBS_MOCK`¶