Bashy c46f2f2fc3 Add README, CLAUDE.md, INSTRUCTIONS.md, and CI workflow

- README.md: feature list, stack, project structure, deferred items
- CLAUDE.md: architecture, conventions, route map, CSS variable system,
  EventSub subscription table, data model, custom event names
- INSTRUCTIONS.md: step-by-step initial deploy guide (Twitch app
  registration through OBS setup and custom CSS/JS), plus git workflow,
  first push, GitHub Actions, branching, and update procedure
- .github/workflows/ci.yml: syntax check and import check on every push

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-22 23:58:23 +03:00

3.7 KiB

Raw Blame History

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)

3.7 KiB Raw Blame History