jyapayne/streamer-widgets
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
streamer-widgets/IMPLEMENTATION_SUMMARY.md

9.1 KiB
Raw Blame History

Live Chat Widget - Implementation Summary

Overview

A comprehensive live chat widget system has been implemented that supports both Twitch and YouTube live chat with extensive emote support (FrankerFaceZ, BetterTTV, 7TV) and real-time WebSocket streaming to OBS.

Architecture

Frontend Components

  1. Chat Widget (app/assets/web/widgets/livechat/)

    • index.html - Minimal HTML structure
    • style.css - Styled chat interface with platform indicators, badges, animations
    • app.js - WebSocket client, message rendering, emote parsing, auto-scroll

  2. Configuration UI (app/assets/web/config.html)

    • Platform authentication controls
    • Channel/video configuration
    • Emote provider toggles
    • Display settings
    • Real-time status indicators

Backend Components

  1. Data Models (app/chat_models.py)

    • Platform - Enum for Twitch/YouTube
    • UserRole - Broadcaster, Mod, VIP, Subscriber, Viewer
    • Emote - Code, URL, provider, animation flag
    • ChatBadge - Badge name and icon
    • ChatUser - User ID, name, color, roles, badges
    • ChatMessage - Complete message with user, text, emotes, timestamp
    • AuthTokens - OAuth token storage with expiry
    • ChatConfig - All widget configuration options

  2. State Management (app/state.py)

    • Extended AppState with:
      • chat_messages - Deque of recent messages (max 100)
      • chat_config - Current configuration
      • twitch_tokens / youtube_tokens - OAuth credentials
    • Methods for adding messages and broadcasting to WebSocket clients

  3. Twitch Integration (app/providers/twitch_chat.py)

    • IRC WebSocket client (wss://irc-ws.chat.twitch.tv:443)
    • Supports anonymous and authenticated connections
    • IRC message parsing (PRIVMSG, tags, badges, emotes)
    • Emote loading from:
      • Twitch native (from IRC tags)
      • FrankerFaceZ API (global + channel)
      • BetterTTV API (global + channel)
      • 7TV API (global + channel)
    • Auto-reconnect on disconnect

  4. YouTube Integration (app/providers/youtube_chat.py)

    • YouTube Live Chat API polling client
    • OAuth required (YouTube Data API v3)
    • Fetches live chat ID from video
    • Polls for new messages with adaptive interval
    • Parses user roles (owner, moderator, sponsor)

  5. Authentication System (app/auth.py)

    • OAuth flow handlers for Twitch and YouTube
    • Token storage in %LOCALAPPDATA%/StreamerWidgets/tokens.json
    • Automatic token loading on startup
    • Browser-based authentication with popup windows
    • Callback URL handling at /auth/{platform}/callback

  6. Chat Manager (app/chat_manager.py)

    • Coordinates Twitch and YouTube clients
    • Starts/stops based on configuration
    • Manages asyncio tasks for each platform
    • Graceful shutdown and restart

  7. WebServer Updates (app/webserver.py)

    • Added livechat widget to WIDGETS list
    • /api/chat/messages - Get recent messages
    • /api/chat/config - GET/POST configuration
    • /config - Configuration UI page
    • OAuth routes registered via register_auth_routes()
    • Enhanced WebSocket to send chat history on connect

  8. Main Integration (app/main.py)

    • Load saved OAuth tokens on startup
    • Initialize and start ChatManager
    • Graceful shutdown of chat connections

Features Implemented

Core Functionality

  • ✅ Real-time chat from Twitch and YouTube
  • ✅ WebSocket streaming to OBS browser source
  • ✅ Unified message stream (both platforms mixed)
  • ✅ Platform-specific visual indicators (color borders, icons)
  • ✅ User badges (broadcaster, mod, VIP, subscriber)
  • ✅ Username colors (Twitch native colors)
  • ✅ Timestamps
  • ✅ Message animations (slide-in effect)
  • ✅ Auto-scroll with manual scroll detection

Emote Support

  • ✅ Twitch native emotes
  • ✅ FrankerFaceZ (FFZ) global and channel emotes
  • ✅ BetterTTV (BTTV) global and channel emotes
  • ✅ 7TV global and channel emotes
  • ✅ Animated emote support
  • ✅ Emote caching
  • ✅ Configurable emote provider toggles

Authentication

  • ✅ Twitch OAuth (optional, anonymous reading supported)
  • ✅ YouTube OAuth (required for YouTube API)
  • ✅ Secure token storage
  • ✅ Token persistence across restarts
  • ✅ Browser-based auth flow

Configuration

  • ✅ Web-based configuration UI
  • ✅ Platform enable/disable
  • ✅ Channel/video ID settings
  • ✅ Emote provider toggles
  • ✅ Display options (timestamps, badges, max messages)
  • ✅ Live status indicators

OBS Integration

  • ✅ Transparent background
  • ✅ Customizable CSS styling
  • ✅ Responsive design
  • ✅ Low resource usage
  • ✅ Auto-reconnecting WebSocket

API Endpoints

Widget Access

  • GET /widgets/livechat/ - Chat widget HTML
  • GET /config - Configuration page

REST API

  • GET /api/chat/messages?limit=50 - Fetch recent messages
  • GET /api/chat/config - Get current configuration
  • POST /api/chat/config - Update configuration

WebSocket

  • GET /ws - Real-time message stream
    • Sends chat_history on connect
    • Sends chat_message for each new message

OAuth

  • GET /auth/twitch/login - Initiate Twitch OAuth
  • GET /auth/twitch/callback - Twitch OAuth callback
  • GET /auth/youtube/login - Initiate YouTube OAuth
  • GET /auth/youtube/callback - YouTube OAuth callback

File Structure

app/
├── chat_models.py           # Data models for chat system
├── chat_manager.py          # Chat client coordinator
├── auth.py                  # OAuth handlers
├── state.py                 # Extended with chat state
├── webserver.py             # Added chat endpoints
├── main.py                  # Integrated chat manager
├── providers/
│   ├── twitch_chat.py       # Twitch IRC client
│   └── youtube_chat.py      # YouTube API client
└── assets/web/
    ├── config.html          # Configuration UI
    └── widgets/
        └── livechat/
            ├── index.html   # Widget HTML
            ├── style.css    # Widget styles
            └── app.js       # WebSocket client

CHAT_SETUP.md                # User setup guide
IMPLEMENTATION_SUMMARY.md    # This file

Configuration Requirements

For Twitch (Optional OAuth)

Users who want authenticated Twitch access need to:

  1. Create app at https://dev.twitch.tv/console/apps
  2. Set redirect URI to http://localhost:8765/auth/twitch/callback
  3. Edit app/auth.py with Client ID and Secret

Anonymous reading works without OAuth.

For YouTube (Required OAuth)

Users need to:

  1. Create Google Cloud project
  2. Enable YouTube Data API v3
  3. Create OAuth credentials (Web application)
  4. Set redirect URI to http://localhost:8765/auth/youtube/callback
  5. Edit app/auth.py with Client ID and Secret

Usage Flow

  1. Start Server: uv run streamer-widgets --tray
  2. Configure (if using OAuth):
  3. Set Channel/Video:
    • Enter Twitch channel name
    • Enter YouTube video ID
    • Save configuration
  4. Add to OBS:
    • Create Browser Source
    • URL: http://127.0.0.1:8765/widgets/livechat/
    • Size: 400x600 (or custom)
  5. Chat appears in OBS with live updates

Technical Highlights

Twitch IRC

  • Efficient IRC WebSocket connection
  • Minimal overhead (no polling)
  • Supports IRC tags for rich metadata
  • Handles PING/PONG keepalive
  • Graceful reconnection

YouTube API

  • Polling-based with adaptive intervals
  • Respects API rate limits
  • Extracts live chat ID automatically
  • Handles OAuth token refresh

Emote Systems

  • Parallel API calls for fast loading
  • Caching to avoid repeated requests
  • Fallback for missing emotes
  • Support for both static and animated

WebSocket Broadcasting

  • Efficient message distribution
  • Dead client cleanup
  • Initial history on connect
  • Type-safe message format

Performance

  • Message limit (deque with maxlen)
  • Auto-scroll optimization
  • Lazy emote replacement
  • Minimal DOM updates

Future Enhancements

Potential additions (not implemented):

  • Separate column view (Twitch | YouTube)
  • Message filtering by keywords/roles
  • Custom badge images
  • Sound notifications
  • Chat replay
  • Custom themes
  • Viewer count display
  • Raid/host notifications
  • Chat commands
  • Donation/sub alerts

Testing Checklist

  • Twitch anonymous connection
  • Twitch authenticated connection
  • YouTube authenticated connection
  • FFZ emotes display
  • BTTV emotes display
  • 7TV emotes display
  • User badges display
  • Platform indicators
  • WebSocket reconnection
  • Configuration persistence
  • OAuth token storage
  • Multiple browser sources
  • OBS transparency
  • Auto-scroll behavior
  • Manual scroll detection

Notes

  • All dependencies already present (aiohttp)
  • No additional packages required for basic functionality
  • OAuth credentials must be user-provided
  • Tokens stored locally (not cloud)
  • Chat history is in-memory only (not persisted to disk)
  • Anonymous Twitch reading has no rate limits
  • YouTube API has daily quota (sufficient for chat reading)