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

285 lines
9.1 KiB
Markdown
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):
- Visit http://127.0.0.1:8765/config
- Click "Login with Twitch" or "Login with YouTube"
- Authorize in browser popup
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)
Reference in a new issue View git blame Copy permalink