# BashyOverlay

Self-hosted Twitch stream alert and overlay platform. Subs, bits, channel points, follows, raids, and chat commands trigger configurable sound and video reactions — all running locally on your machine, no third-party alert service required.

## Features

- **OBS browser source overlay** — transparent chat display with gap audio (tone plays when chat goes quiet, volume and pitch scale with silence duration)
- **Twitch EventSub** — real-time events for subs, gift subs, bits, channel points, follows, and raids
- **Chat commands** — `!command` triggers via tmi.js, no bot account needed for public channels
- **Action system** — map any event to a sound, video clip, or on-screen alert; multiple actions per event; per-action cooldowns and enable/disable toggle
- **Test button** — fire any action instantly from the management UI without waiting for a real event
- **Self-hosted media library** — upload your own MP3s and MP4s
- **Layout editor** — WYSIWYG iframe editor; drag chat and alert widgets, resize chat, live style preview
- **Custom CSS / JS** — inject code directly into the overlay; hook into `bashyoverlay:sub`, `bashyoverlay:raid`, etc.
- **Management UI** — dashboard with activity log, EventSub status, action config, media library
- **Twitch OAuth** — login with your Twitch account; no passwords anywhere

## Stack

- Python 3.10+ · FastAPI · SQLModel · SQLite
- Jinja2 · HTMX · Pico CSS (dark theme)
- tmi.js · Twitch EventSub WebSocket
- interact.js (layout editor drag and resize)

## Quick start

See **[INSTRUCTIONS.md](INSTRUCTIONS.md)** for the full setup guide including Twitch app registration and OBS configuration.

```bash
cp .env.example .env
# fill in your Twitch credentials and a SECRET_KEY
./deploy.sh
```

## Project structure

```
app/
  main.py          — FastAPI app, lifespan, EventSub startup
  models.py        — SQLModel table definitions
  database.py      — engine, session dependency, singleton helpers
  auth.py          — Twitch OAuth helpers, session dependency
  eventsub.py      — EventSub WebSocket background task, token refresh
  dispatch.py      — event → action resolution, cooldowns, DB log, broadcast
  ws.py            — WebSocket connection manager for overlay clients
  cooldowns.py     — in-memory cooldown tracking per action
  routers/
    auth.py        — /auth/login, /auth/callback, /auth/logout
    dashboard.py   — / dashboard with activity log
    overlay.py     — /overlay (live), /overlay/preview, /ws/overlay
    actions.py     — /actions CRUD, test, toggle
    media.py       — /media upload and delete
    layout.py      — /layout editor, /layout/positions (drag save)
    settings.py    — /settings
templates/
  overlay.html          — OBS browser source (live tmi.js + WebSocket)
  overlay_preview.html  — layout editor preview (mock data, no live connections)
  layout.html           — iframe-based drag-and-drop layout editor
  base.html             — management UI shell
  dashboard.html        — activity log
  actions.html          — action configuration
  media.html            — media library
  settings.html         — settings including custom CSS/JS
  login.html            — Twitch OAuth login page
  partials/             — HTMX response fragments
static/
  overlay.css   — overlay styles using CSS custom properties
  style.css     — management UI styles
  media/        — uploaded sounds and videos (gitignored)
```

## Deferred / upcoming

- Blerp sound library integration
- HudFX video library integration
- Crypto payment notifications (Base/ETH wallet watching)
- Alert variable interpolation (`{username}` in alert text)
- Mod access (currently streamer-only login)