Bashy
c46f2f2fc3
- 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>
78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
# 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)
|