Web Interface¶

StarStreamer includes a modern web management interface built with NiceGUI that provides comprehensive control over your streaming automation setup.

Overview¶

The web interface runs alongside StarStreamer and provides:

Real-time monitoring of events and module status
Configuration management with live editing capabilities
Module management with enable/disable/reload functionality
OAuth integration for platform connections
Event filtering and history viewing

Accessing the Interface¶

The web interface is automatically started when you run StarStreamer:

uv run python src/main.py
# Web interface available at: http://localhost:8888

Configuration¶

The web server can be configured in your config.yaml:

web:
  port: 8888              # Web server port
  host: "127.0.0.1"      # Bind address
  cors_origins:           # Allowed CORS origins
    - "http://localhost:3000"

Pages¶

Dashboard (`/`)¶

The main dashboard provides an overview of your StarStreamer instance:

Event Statistics - Total events processed and actions triggered
System Status - Overall health and performance metrics
Quick Navigation - Access to all other interface sections

Settings (`/settings`)¶

Comprehensive configuration management with tabbed interface:

Application - Basic app settings like name, version, and environment
Web Server - Web interface configuration (port, host)
Twitch - Twitch integration settings and OAuth status
OBS - OBS WebSocket connection settings
AI Services - OpenRouter and ElevenLabs configuration
Modules - Module-specific settings and disabled modules list

All settings are loaded from your configuration files and display current values with proper form controls.

Modules (`/modules`)¶

Module management interface with real-time control:

Module Statistics - Total, enabled, and loaded module counts
Module List - All discovered modules with their current status
Module Actions - Enable, disable, and reload modules dynamically
Module Information - View module descriptions and dependencies

Module Management Features¶

Load/Unload - Dynamically load modules without restarting
Enable/Disable - Control module activation state
Hot Reload - Reload module code for development
Status Tracking - Real-time status updates

Events (`/events`)¶

Real-time event monitoring and filtering:

Event Statistics - Live counters for processed events and triggered actions
Event Filters - Filter by source (twitch, obs) or event type
Event History - Recent events with expandable details
Real-time Updates - Live event stream as they occur

Event Filtering¶

Source Filter: twitch          # Show only Twitch events
Type Filter: chat.message      # Show only chat messages

Connections (`/connections`)¶

OAuth and platform integration management:

Twitch Integration - Broadcaster and bot account status
OAuth Flow - Secure token management via implicit OAuth
Account Status - Connected accounts with user information
Disconnect Options - Safely disconnect platform accounts

OAuth Integration¶

StarStreamer uses implicit OAuth flow for secure authentication:

Click authentication links in the Connections page
Complete OAuth flow on platform (Twitch)
Tokens are securely stored in the database
No sensitive credentials in configuration files

Architecture¶

NiceGUI Integration¶

The web interface is built with NiceGUI, providing:

Reactive UI - Real-time updates without page refreshes
Professional Design - Modern, clean interface
Type Safety - Full Python type hints
Easy Extension - Simple to add new pages and components

Backend Integration¶

The web interface integrates directly with StarStreamer's core systems:

# Web interface components
src/starstreamer/web/
├── app.py              # FastAPI backend server
└── ui/                 # NiceGUI frontend
    ├── app.py          # NiceGUI app setup
    ├── components/     # Reusable components
    ├── pages/          # Interface pages
    └── stores.py       # State management

State Management¶

The interface uses stores to manage UI state:

AppStore - Application data (events, stats, actions)
AuthStore - Authentication state and OAuth tokens
ConfigStore - Configuration management and editing

Development¶

Adding New Pages¶

Create a new page class:

# src/starstreamer/web/ui/pages/my_page.py
from nicegui import ui
from starstreamer.web.ui.stores import AppStore, AuthStore

class MyPage:
    def __init__(self, app_store: AppStore, auth_store: AuthStore):
        self.app_store = app_store
        self.auth_store = auth_store

    async def create(self) -> None:
        ui.label("My Custom Page")
        # Add your UI components here

Register the route in the main app:

# src/starstreamer/web/ui/app.py
@ui.page("/my-page")
async def my_page():
    from .pages.my_page import MyPage
    await create_header()
    page = MyPage(app_store, auth_store)
    await page.create()

Custom Components¶

Create reusable components:

# src/starstreamer/web/ui/components/my_component.py
from nicegui import ui

def create_status_card(title: str, value: str):
    with ui.card().classes("p-4"):
        ui.label(title).classes("text-sm text-gray-500")
        ui.label(value).classes("text-2xl font-bold")

Security¶

Authentication¶

The web interface uses secure OAuth flows:

No secrets in config - All sensitive tokens stored in database
Implicit OAuth - Secure browser-based authentication
Token encryption - Database tokens are properly secured

Network Security¶

Local binding - Default host binding to 127.0.0.1
CORS configuration - Configurable CORS origins
No external dependencies - Self-contained web server

Troubleshooting¶

Common Issues¶

Web interface not accessible:

# Check if port is in use
netstat -an | grep 8888

# Use different port
uv run python src/main.py --web-port 8889

Module management not working: - Ensure service container is properly initialized - Check that modules are discoverable in the modules/ directory - Verify module classes follow naming conventions

OAuth flow issues: - Check Twitch client ID configuration - Verify network connectivity - Clear browser cache and cookies

Debug Mode¶

Enable debug mode for detailed logging:

uv run python src/main.py --debug

This will show: - Detailed request/response logging - UI component creation traces - Service resolution debugging