godice-overlay 0.1.0

OBS streaming overlay for GoDice Bluetooth dice

GoDice Overlay

OBS overlay that shows your GoDice rolls on stream. You roll the physical die, the value pops up in OBS.

Supports all die types (D4, D6, D8, D10, D10X, D12, D20), multiple dice at once, and reconnects automatically if a die drops out.

What it does

• Connects to GoDice over Bluetooth, shows rolls as an animated OBS browser source
• Comes with 4 themes (Minimal, Neon, Classic, Parchment)
• Detects fake rolls (dropped, not actually thrown) and suspicious ones (moved before settling). You pick what to do with them: ignore, show a warning, or just treat them as normal
• LED feedback on roll: die color, white, or crit mode (green on max, red on min)
• Warns you when battery is low (red LED on the die)
• Keeps roll history in SQLite, exportable to CSV
• Admin UI for managing everything

Requirements

• Python 3.14+
• uv
• Bluetooth adapter (BLE)
• GoDice dice

Install

git clone <repo-url>
cd godice-overlay
uv sync

Or just run it directly:

uvx godice-overlay

Run

uv run godice-overlay

Opens a server on localhost:8080:

• / is the admin page where you scan for dice, connect them, tweak settings, and check roll history
• /overlay is the transparent page you point OBS at

OBS setup

1. Run uv run godice-overlay
2. Add a Browser Source in OBS
3. URL: http://localhost:8080/overlay
4. Match width/height to your canvas (1920x1080 or whatever you use)
5. That's it

Admin page

From the admin page you can:

• Scan and connect dice
• Label them, pick colors, set die types
• Pick a theme, overlay position, text size, how long the roll stays on screen
• Choose LED mode (off, die color, white, crit)
• Decide what happens with fake/suspicious rolls
• Browse the roll log, export to CSV

Where stuff lives

• Config: ~/.config/godice-overlay/config.yaml
• Roll database: ~/.local/share/godice-overlay/rolls.db (rolls older than 30 days get cleaned up)
• Logs: ~/.local/state/godice-overlay/logs/

Dev

uv run pytest
uv run godice-overlay

Built with

• NiceGUI for the UI
• godice for talking to the dice over BLE
• bleak for Bluetooth
• aiosqlite for the roll database

License

MIT. Note that the godice dependency has its own proprietary license that restricts usage to personal and academic purposes.