# 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?