Streamer.bot Viewer Avatar Overlay
Streamer.bot Viewer Avatar Overlay
A browser-based avatar overlay for Twitch streams that works with Streamer.bot WebSocket events.
Viewers appear on screen as animated avatars that walk across the bottom of the stream, display chat bubbles, and react to commands.
Avatars are synchronized using the Twitch Present Viewers list, so viewers appear when they join and disappear with a poof effect when they leave.
This project is inspired by Evotars but designed specifically for Streamer.bot.
Features
Viewer Avatars
• Avatars appear when a viewer joins the Present Viewers list
• Each avatar includes:
-
Twitch profile image as the body
-
random color
-
random character skin
• Avatars walk left and right across the screen
Chat Integration
• Chat messages appear as speech bubbles above avatars
• Twitch emotes render as actual images
Supported Chat Commands
- !grow
Avatar grows until the user speaks again - !jump
Avatar jumps - !skin <name>
Change avatar skin - !color <name>
Change avatar color
Viewer Tracking
This system uses Streamer.bot Present Viewers as the source of truth.
Behavior:
- Viewer appears → avatar spawns
- Viewer disappears → avatar removed with poof effect
To prevent Twitch viewer list flicker, avatars are only removed after being missing from several viewer list updates.
Raid Support
When a raid occurs:
• Raiders fall from the top of the screen
• Then begin walking like normal avatars
Anti-Duplicate System
Usernames are normalized to lowercase to prevent duplicates when:
• Twitch display names change
• viewers refresh Twitch
• Streamer.bot receives duplicate chat events
Requirements
- Streamer.bot
- OBS Studio (Browser Source)
or any overlay software - Streamer.bot WebSocket Server enabled
Default WebSocket Server
ws://127.0.0.1:8080/
Installation
- Step 1 — Download Repository
- Step 2 — Add HTML Overlay
In OBS:
Browser Source
Recommended resolution:
1920×1080
- Step 3 — Enable Streamer.bot WebSocket Server
Streamer.bot
Servers → WebSocket Server
- Step 4 — Import Code To Streamer.bot
Import the provided Streamer.bot export:
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
