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 for the full setup guide including Twitch app registration and OBS configuration.

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)