Bambu X2D → OBS overlay
A locally hosted, transparent HTML overlay for streaming Bambu Lab X2D prints with OBS. It shows live job
progress, time left, elapsed time, layers, both nozzle temperatures, bed and chamber temperatures, the plate
preview rendered by the slicer, the filament in use and AMS slots (optionally also the model title, a
"by maker" credit and the MakerWorld link). Six switchable layouts are included, and the accent colour follows the
filament being printed. It can also pan the camera crop in OBS smoothly when a print starts or ends, draw a
Winamp-style two-channel audio meter from OBS's own levels, and show your live Twitch viewer count.
No wall-clock times (ETA, clock) are shown on purpose: viewers are in other time zones, durations aren't.
| Glass | Lower third | HUD |
|---|
| | |
| Sidebar | Orb | Minimal |
| | |
(Screenshots: the overlay with live data from a print, over a frame of the camera.)
Quick start
cp .env.example .env # then fill in the printer IP + access code
./tools/build-app.sh # builds "Bambu Overlay.app" (needs Xcode command line tools)
open "Bambu Overlay.app" # menu-bar app that runs server.py; allow "local network" when asked
The app puts a printer icon in the menu bar with a status line, Open Control Panel, Show Log,
Restart Server, Start at Login and Quit. Server output goes to cache/server.log.
Why an app? macOS 15+ only lets a program reach devices on the local network (the printer) if there's an
app it can ask for permission. Run straight from a background terminal or tmux, python3 server.py gets a
silent [Errno 65] No route to host. Under the app, macOS asks once ("Bambu Overlay would like to find devices on
your local network") and remembers it. A foreground Terminal.app window works too, since Terminal gets the prompt.
Rebuilding the app changes its signature, so macOS may ask again.
python3 server.py (Python 3.10+, standard library only) still works anywhere the network isn't restricted.
No printer? Without .env the server starts in demo mode: run python3 server.py and open
http://127.0.0.1:8787/preview?demo=1 to see a simulated print (add &layout=hud, ticker, … to switch layouts).
| URL | What |
|---|
http://127.0.0.1:8787/ | The overlay: add it to OBS as a Browser source |
http://127.0.0.1:8787/control | Control panel: layout, options, OBS crop, live previews, printer status |
http://127.0.0.1:8787/preview | The overlay on top of a frame of the stream (accepts the same URL params) |
http://<your-mac>.local:8787/control | The same from any device on your network (phone, tablet, second PC); the server prints the exact name at startup |
The server listens on the whole local network by default (OVERLAY_HOST=0.0.0.0). Anyone on your LAN can open
the control panel and change overlay/crop settings, but nothing reaches the printer. Set OVERLAY_HOST=127.0.0.1
to keep it to this Mac.
OBS
- Sources → + → Browser, URL
http://127.0.0.1:8787/, Width 1280, Height 720 (1920×1080 works too:
everything is laid out on a 1280×720 stage and scaled to fit).
- Place it above the camera source and stretch it over the canvas. The page background is transparent.
- In the camera's Media Source (Local File off, input
rtsps://bblp:<access code>@<printer IP>:322/streaming/live/1),
set FFmpeg Options to timeout=10000000. A printer that is switched off goes silent without closing the
connection, and OBS then holds the last frame forever: its own 30 s timeout uses an option name that current
FFmpeg no longer has. With the option, the source clears after 10 s and OBS retries every Reconnect Delay until
the printer is back.
- Optional: Sources → + → Image →
web/testcard.png, at the bottom of the scene under the camera. It is only
seen while the camera is down ("Camera offline"). web/testcard.html is its source.
- Optional: Docks → Custom Browser Docks → add
http://127.0.0.1:8787/control to switch layouts without leaving OBS.
The control panel changes every overlay that has no URL parameters. To pin a source to one look, add parameters,
e.g. one scene with /?layout=hud and another with /?layout=minimal:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
