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>
95 lines
3.7 KiB
Markdown
95 lines
3.7 KiB
Markdown
# 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?
|