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

1. 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).
2. Place it above the camera source and stretch it over the canvas. The page background is transparent.
3. 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.
4. 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.
5. 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:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗