Bashy
6ad661c220
Twitch stream event platform with OBS browser source overlay. Features: - Twitch OAuth login (streamer + mod access) - EventSub WebSocket for subs, gift subs, bits, channel points, follows, raids - Chat commands via tmi.js in the overlay - Gap audio — tone plays on new chat message after silence, volume/pitch scale with gap length - Self-hosted media library (upload sounds and videos) - Action configuration — map any event to sound, video, or alert - Per-action cooldowns, test button, enable/disable toggle - Multiple actions per event (all matching actions fire) - Activity log dashboard with EventSub connection status - Layout editor — iframe-based WYSIWYG with drag handles, live style preview - Custom CSS and custom JS injection into overlay - Custom DOM events (bashyoverlay:sub, bashyoverlay:raid, etc.) for custom JS hooks - deploy.sh — one-shot setup and launch script Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.7 KiB
BashyOverlay — spec
Self-hosted Twitch stream event platform. Subs, bits, channel points, and chat commands trigger configurable sound and video reactions. Think StreamElements/Streamlabs alerts, but owned and customisable.
No smart lights.
Event sources
| Source | How |
|---|---|
Chat commands (!name) |
tmi.js IRC WebSocket — no auth needed for public chat |
| Subs, bits, channel points | Twitch EventSub WebSocket — requires OAuth token |
Action types
| Action | Notes |
|---|---|
| Play a sound | From Blerp library — see open questions |
| Play a video/clip overlay | From HudFX library — see open questions |
| On-screen alert | Text, image, or animation shown in the OBS browser source |
Media libraries
- Sounds — Blerp. Meme/clip sound platform. Has Twitch integration history. API details need confirming before building — check developer docs for programmatic library access and licensing.
- Videos — HudFX. Overlay video/animation library. API access and terms need confirming before building.
Both are external dependencies. If their APIs aren't open enough, fallback is a self-hosted media library (upload your own files via the management UI).
The overlay
OBS browser source pointed at the local management server. Receives events from the backend via WebSocket and plays the configured reaction.
Chat gap audio
Passive audio notification for slow chat — not tied to a command, just fires when a new message arrives after a long silence:
- Under 30 seconds — no sound
- 30s to ~2 minutes — volume scales up with gap
- 2+ minutes — full volume + pitch scales up (caps ~5 min)
Thresholds configurable in management UI.
Architecture
Twitch ──EventSub WebSocket──► Backend ──WebSocket──► OBS Browser Source
Twitch ──IRC (tmi.js)────────────────────────────────► OBS Browser Source
The overlay holds the tmi.js connection directly. The backend holds the EventSub connection and relays events to the overlay.
Management platform
Local web app running on the streamer's machine.
Stack: FastAPI + SQLite + Jinja2 + HTMX (same as IllBring)
Features:
- Configure actions per event type (sub, bits tier, channel point reward, chat command)
- Search and preview Blerp sounds
- Browse and preview HudFX videos
- Upload custom sounds/videos as fallback
- Configure gap-audio thresholds
- Activity log / dashboard
- User access via Twitch OAuth — mods verified against channel mod list, no separate user table
Authentication
Twitch OAuth throughout:
- Streamer logs in → full admin access
- Mods log in → access if verified as mod of the channel via Twitch API
- Token used for EventSub subscriptions
Deferred
- Crypto payment notifications — watch a wallet address for incoming transactions via a blockchain API (Alchemy, Moralis, etc.), fire an overlay event on receipt. Which chains to support and whether to use raw wallet watching vs a payment processor (BTCPay Server, etc.) TBD.
Estimated effort
| Piece | Effort |
|---|---|
| OBS overlay + gap audio | 1–2 hours |
| Twitch OAuth | half day |
| EventSub WebSocket + subscriptions | half–1 day |
| Event → action mapping + management UI | 1 day |
| Blerp integration | half day (pending API review) |
| HudFX integration | half day (pending API review) |
| Dashboard / activity log | half day |
| Total v1 | ~3–4 days |
Open questions before building
- Does Blerp have a public API with library search + programmatic playback?
- Does HudFX expose a video library via API?
- If either doesn't — self-hosted media library, or a different provider?
- Crypto: which chains, wallet watching vs payment processor?