pycentauri 0.3.0__tar.gz → 0.4.0__tar.gz

{pycentauri-0.3.0 → pycentauri-0.4.0}/CHANGELOG.md

@@ -6,6 +6,42 @@ Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-22
+
+### Added
+- **RTSP bridge.** Re-stream the printer's MJPEG webcam as RTSP/H.264
+  so VLC, Home Assistant, Jellyfin, Frigate, Synology Surveillance, and
+  any other RTSP client can consume it. Powered by `MediaMTX` +
+  on-demand `ffmpeg` transcode — the transcoder only runs while at least
+  one client is connected, so idle cost is zero. Two ways to drive it:
+  - **Standalone**: `centauri rtsp --host <printer>` runs in the
+    foreground until Ctrl-C. Flags: `--port`, `--bind`, `--path`,
+    `--fps`, `--bitrate`, `--preset`, `--webrtc/--no-webrtc`,
+    `--hls/--no-hls`, and `--mediamtx-path` / `--ffmpeg-path`
+    overrides.
+  - **Integrated with `centauri server --rtsp`**: adds a "STREAM" panel
+    to the built-in web UI with start/stop buttons, a copy-URL button,
+    and live status. New endpoints: `GET /api/rtsp`,
+    `POST /api/rtsp/start`, `POST /api/rtsp/stop`.
+- Requires `mediamtx` and `ffmpeg` on `$PATH` — clear install hints
+  surface in the API response and the UI panel if either is missing,
+  and nothing changes for users who don't enable the feature.
+
+## [0.3.1] - 2026-04-22
+
+### Changed
+- **Web UI redesign.** Moved from the generic dark-dashboard look to an
+  industrial instrument-panel aesthetic — amber-on-near-black, viewfinder
+  corner brackets and a faint crosshair over the webcam, ruler-style
+  progress bar with diagonal-hatch fill, tabular-numeric temperature
+  gauges with per-channel setpoint bars, kinematics readout with X/Y/Z
+  cells and fan/Z-offset/mainboard telemetry, keyboard-key-style F1/F2/F3
+  control buttons (with real keyboard shortcuts). Typography: Space Mono
+  for display numerals, IBM Plex Mono for data, IBM Plex Sans Condensed
+  for SCADA-style labels.
+- Webcam MJPEG element now auto-recovers if the stream stalls for 15s.
+- Added a favicon so browsers stop 404-ing `/favicon.ico`.
+
 ## [0.3.0] - 2026-04-22
 
 ### Added

{pycentauri-0.3.0 → pycentauri-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycentauri
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python client and MCP server for Elegoo Centauri Carbon 3D printers
 Project-URL: Homepage, https://github.com/bjan/pycentauri
 Project-URL: Repository, https://github.com/bjan/pycentauri
@@ -52,7 +52,7 @@ Python client, CLI, and MCP server for the [Elegoo Centauri
 Carbon](https://www.elegoo.com/) 3D printer.
 
 `pycentauri` speaks the printer's native SDCP v3 protocol over its local
-WebSocket (port 3030) — no cloud account required. It exposes five surfaces:
+WebSocket (port 3030) — no cloud account required. It exposes six surfaces:
 
 1. An **async Python library** for direct integration.
 2. A **`centauri` CLI** for quick status checks, snapshots, and control.
@@ -60,8 +60,10 @@ WebSocket (port 3030) — no cloud account required. It exposes five surfaces:
    MCP-compatible client) can monitor and drive the printer as a tool.
 4. An **HTTP + SSE server** for dashboards, reverse-proxy integration, and
    anything that wants a plain REST API.
-5. A **built-in web UI** (dark theme, mobile-friendly) served at `/ui/` by
-   the HTTP server — live webcam, progress, temperatures, and control.
+5. A **built-in web UI** (industrial instrument-panel theme, mobile-friendly)
+   served at `/ui/` by the HTTP server.
+6. An **RTSP bridge** that re-streams the printer's MJPEG webcam as
+   H.264/RTSP for Home Assistant, Jellyfin, VLC, Frigate, and NVRs.
 
 > **Status:** alpha. The protocol has been reverse-engineered from the official
 > [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link) C++ SDK and the
@@ -155,6 +157,32 @@ The server holds a single long-lived WebSocket to the printer and reuses
 it for every request — no per-request reconnect, and it won't bump into
 the firmware's 5-slot limit.
 
+## Quick start — RTSP bridge
+
+```sh
+# Install dependencies first:
+#   mediamtx  https://github.com/bluenviron/mediamtx/releases  (or `brew install mediamtx`)
+#   ffmpeg    `brew install ffmpeg` or `apt install ffmpeg`
+
+# Standalone: foreground, Ctrl-C to stop
+centauri rtsp --host 192.168.1.209
+# → rtsp://<this-host>:8554/printer
+
+# Or, integrated with the HTTP server + web UI
+centauri server --host 192.168.1.209 --rtsp --bind 0.0.0.0
+# Web UI gains a STREAM panel with a toggle, a copy-URL button, and live status
+# at http://<this-host>:8787/ui/
+```
+
+Open that URL in **VLC** (Media → Open Network Stream), point **Home Assistant**
+at it via the Generic Camera integration, or feed it to **Frigate** / **Jellyfin**
+/ **Synology Surveillance** for NVR recording and motion detection.
+
+MediaMTX runs the ffmpeg transcode only while at least one client is actually
+connected, so idle cost is zero. Tunable: `--fps`, `--bitrate`, `--preset`,
+`--path`, `--port`, `--bind`. Run `centauri rtsp --help` (or
+`centauri server --help`) for the full list.
+
 ## Quick start — MCP
 
 Register the server with your agent. With Claude Code:

{pycentauri-0.3.0 → pycentauri-0.4.0}/README.md

@@ -4,7 +4,7 @@ Python client, CLI, and MCP server for the [Elegoo Centauri
 Carbon](https://www.elegoo.com/) 3D printer.
 
 `pycentauri` speaks the printer's native SDCP v3 protocol over its local
-WebSocket (port 3030) — no cloud account required. It exposes five surfaces:
+WebSocket (port 3030) — no cloud account required. It exposes six surfaces:
 
 1. An **async Python library** for direct integration.
 2. A **`centauri` CLI** for quick status checks, snapshots, and control.
@@ -12,8 +12,10 @@ WebSocket (port 3030) — no cloud account required. It exposes five surfaces:
    MCP-compatible client) can monitor and drive the printer as a tool.
 4. An **HTTP + SSE server** for dashboards, reverse-proxy integration, and
    anything that wants a plain REST API.
-5. A **built-in web UI** (dark theme, mobile-friendly) served at `/ui/` by
-   the HTTP server — live webcam, progress, temperatures, and control.
+5. A **built-in web UI** (industrial instrument-panel theme, mobile-friendly)
+   served at `/ui/` by the HTTP server.
+6. An **RTSP bridge** that re-streams the printer's MJPEG webcam as
+   H.264/RTSP for Home Assistant, Jellyfin, VLC, Frigate, and NVRs.
 
 > **Status:** alpha. The protocol has been reverse-engineered from the official
 > [`elegoo-link`](https://github.com/ELEGOO-3D/elegoo-link) C++ SDK and the
@@ -107,6 +109,32 @@ The server holds a single long-lived WebSocket to the printer and reuses
 it for every request — no per-request reconnect, and it won't bump into
 the firmware's 5-slot limit.
 
+## Quick start — RTSP bridge
+
+```sh
+# Install dependencies first:
+#   mediamtx  https://github.com/bluenviron/mediamtx/releases  (or `brew install mediamtx`)
+#   ffmpeg    `brew install ffmpeg` or `apt install ffmpeg`
+
+# Standalone: foreground, Ctrl-C to stop
+centauri rtsp --host 192.168.1.209
+# → rtsp://<this-host>:8554/printer
+
+# Or, integrated with the HTTP server + web UI
+centauri server --host 192.168.1.209 --rtsp --bind 0.0.0.0
+# Web UI gains a STREAM panel with a toggle, a copy-URL button, and live status
+# at http://<this-host>:8787/ui/
+```
+
+Open that URL in **VLC** (Media → Open Network Stream), point **Home Assistant**
+at it via the Generic Camera integration, or feed it to **Frigate** / **Jellyfin**
+/ **Synology Surveillance** for NVR recording and motion detection.
+
+MediaMTX runs the ffmpeg transcode only while at least one client is actually
+connected, so idle cost is zero. Tunable: `--fps`, `--bitrate`, `--preset`,
+`--path`, `--port`, `--bind`. Run `centauri rtsp --help` (or
+`centauri server --help`) for the full list.
+
 ## Quick start — MCP
 
 Register the server with your agent. With Claude Code:

{pycentauri-0.3.0 → pycentauri-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycentauri"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python client and MCP server for Elegoo Centauri Carbon 3D printers"
 readme = "README.md"
 license = "Apache-2.0"

{pycentauri-0.3.0 → pycentauri-0.4.0}/src/pycentauri/__init__.py

@@ -15,4 +15,4 @@ __all__ = [
     "discover",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{pycentauri-0.3.0 → pycentauri-0.4.0}/src/pycentauri/cli.py

@@ -345,6 +345,18 @@ def cmd_server(
     port: int = typer.Option(8787, "--port", "-p"),
     enable_control: ControlOpt = False,
     log_level: str = typer.Option("info", "--log-level"),
+    rtsp: bool = typer.Option(
+        False,
+        "--rtsp/--no-rtsp",
+        help="Enable /api/rtsp/* endpoints and the STREAM panel in the web UI.",
+    ),
+    rtsp_port: int = typer.Option(8554, "--rtsp-port", help="RTSP port (when --rtsp)."),
+    rtsp_path: str = typer.Option("printer", "--rtsp-path", help="RTSP URL path."),
+    rtsp_bind: str = typer.Option(
+        "0.0.0.0", "--rtsp-bind", help="Interface MediaMTX binds to for RTSP."
+    ),
+    rtsp_fps: int = typer.Option(15, "--rtsp-fps"),
+    rtsp_bitrate: str = typer.Option("2M", "--rtsp-bitrate"),
 ) -> None:
     """Run the HTTP + SSE server (requires `pip install 'pycentauri[server]'`)."""
     try:
@@ -358,6 +370,20 @@ def cmd_server(
         return await _resolve_target(host)
 
     h, mid = asyncio.run(resolve())
+
+    rtsp_cfg = None
+    if rtsp:
+        from pycentauri.rtsp import RtspConfig
+
+        rtsp_cfg = RtspConfig(
+            printer_host=h,
+            rtsp_port=rtsp_port,
+            bind=rtsp_bind,
+            path=rtsp_path,
+            fps=rtsp_fps,
+            bitrate=rtsp_bitrate,
+        )
+
     run_server(
         h,
         bind=bind,
@@ -365,7 +391,62 @@ def cmd_server(
         enable_control=enable_control,
         mainboard_id=mid,
         log_level=log_level,
+        rtsp_config=rtsp_cfg,
+    )
+
+
+@app.command("rtsp")
+def cmd_rtsp(
+    host: HostOpt = None,
+    port: int = typer.Option(8554, "--port", "-p", help="RTSP TCP port."),
+    bind: str = typer.Option("0.0.0.0", "--bind", help="Interface to bind MediaMTX on."),
+    stream_path: str = typer.Option("printer", "--path", help="RTSP path, e.g. rtsp://.../<path>"),
+    fps: int = typer.Option(15, "--fps", help="Re-encode frame rate cap."),
+    bitrate: str = typer.Option("2M", "--bitrate", help="ffmpeg video bitrate (e.g. 2M, 4M)."),
+    preset: str = typer.Option("veryfast", "--preset", help="libx264 preset."),
+    mediamtx_path: str = typer.Option(
+        None, "--mediamtx-path", help="Override mediamtx binary path."
+    ),
+    ffmpeg_path: str = typer.Option(None, "--ffmpeg-path", help="Override ffmpeg binary path."),
+    enable_webrtc: bool = typer.Option(
+        False, "--webrtc/--no-webrtc", help="Also serve WebRTC (MediaMTX defaults)."
+    ),
+    enable_hls: bool = typer.Option(False, "--hls/--no-hls", help="Also serve HLS."),
+) -> None:
+    """Re-stream the printer's MJPEG webcam as RTSP/H.264 via MediaMTX.
+
+    Requires ``mediamtx`` and ``ffmpeg`` on $PATH (or supply --*-path).
+    Transcoding only happens while a client is actually connected to the
+    RTSP URL, so idle cost is zero.
+    """
+    from pycentauri.rtsp import RtspConfig, RtspError, run
+
+    async def resolve() -> tuple[str, str | None]:
+        return await _resolve_target(host)
+
+    h, _mid = asyncio.run(resolve())
+
+    cfg = RtspConfig(
+        printer_host=h,
+        rtsp_port=port,
+        bind=bind,
+        path=stream_path,
+        fps=fps,
+        bitrate=bitrate,
+        preset=preset,
+        mediamtx_path=mediamtx_path,
+        ffmpeg_path=ffmpeg_path,
+        enable_webrtc=enable_webrtc,
+        enable_hls=enable_hls,
     )
+    try:
+        exit_code = run(cfg)
+    except RtspError as err:
+        _echo_err(str(err))
+        raise typer.Exit(code=1) from err
+    except KeyboardInterrupt:
+        exit_code = 0
+    raise typer.Exit(code=exit_code)
 
 
 @app.command("mcp")

pycentauri-0.4.0/src/pycentauri/rtsp.py

@@ -0,0 +1,259 @@
+"""Expose the printer's MJPEG webcam as an RTSP stream.
+
+The Centauri Carbon serves MJPEG on ``http://<host>:3031/video``. Most
+consumer video clients (VLC, Home Assistant, Jellyfin, Frigate, NVRs,
+Synology Surveillance, most Android Shield/STB camera apps) prefer
+RTSP/H.264. This module launches `MediaMTX`_ as a subprocess with an
+on-demand transcode pipeline::
+
+    printer MJPEG  →  ffmpeg (MJPEG → H.264)  →  MediaMTX (RTSP server)
+
+MediaMTX only spawns the ffmpeg process while at least one client is
+connected to the RTSP path, so idle cost is zero.
+
+External binaries required at runtime:
+
+* ``mediamtx``  — https://github.com/bluenviron/mediamtx/releases
+* ``ffmpeg``    — any recent build on ``$PATH``
+
+.. _MediaMTX: https://github.com/bluenviron/mediamtx
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+import signal
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class RtspError(RuntimeError):
+    """Raised for setup failures — missing binaries, etc."""
+
+
+@dataclass(slots=True)
+class RtspConfig:
+    """Parameters for the RTSP bridge."""
+
+    printer_host: str
+    rtsp_port: int = 8554
+    bind: str = "0.0.0.0"
+    path: str = "printer"
+    camera_port: int = 3031
+    camera_path: str = "/video"
+    # ffmpeg encode tuning. ``veryfast`` + ``zerolatency`` keeps CPU low
+    # and glass-to-glass latency around 500 ms to 1 s on modest hardware.
+    preset: str = "veryfast"
+    tune: str = "zerolatency"
+    bitrate: str = "2M"
+    fps: int = 15
+    # Override binary paths if they're not on ``$PATH``.
+    mediamtx_path: str | None = None
+    ffmpeg_path: str | None = None
+    # If set, also serve WebRTC / HLS on default ports; otherwise RTSP-only.
+    enable_webrtc: bool = False
+    enable_hls: bool = False
+    log_level: str = "info"
+
+
+INSTALL_HINT = (
+    "MediaMTX is required and was not found on $PATH.\n"
+    "Install it:\n"
+    "  macOS:   brew install mediamtx\n"
+    "  Linux:   download the latest linux_amd64 binary from\n"
+    "           https://github.com/bluenviron/mediamtx/releases\n"
+    "           and move it to /usr/local/bin/mediamtx (chmod +x)\n"
+    "  Or pass --mediamtx-path /full/path/to/mediamtx."
+)
+
+FFMPEG_HINT = (
+    "ffmpeg is required and was not found on $PATH.\n"
+    "  macOS:   brew install ffmpeg\n"
+    "  Linux:   sudo apt install ffmpeg (or your distro's equivalent)\n"
+    "  Or pass --ffmpeg-path /full/path/to/ffmpeg."
+)
+
+
+def find_binary(name: str, override: str | None = None) -> str | None:
+    """Locate a binary by name, respecting an explicit override."""
+    if override:
+        if Path(override).is_file() and os.access(override, os.X_OK):
+            return override
+        return None
+    return shutil.which(name)
+
+
+def _mediamtx_yaml(cfg: RtspConfig, ffmpeg_bin: str) -> str:
+    """Render a MediaMTX YAML config for the requested parameters.
+
+    ``runOnDemand`` keeps the ffmpeg process idle until the first RTSP
+    reader connects; ``runOnDemandRestart`` restarts it if it exits while
+    readers are still attached (printer reboots, network blips).
+    """
+    cam_url = f"http://{cfg.printer_host}:{cfg.camera_port}{cfg.camera_path}"
+    rtsp_address = f"{cfg.bind}:{cfg.rtsp_port}" if cfg.bind != "0.0.0.0" else f":{cfg.rtsp_port}"
+    webrtc_line = "" if cfg.enable_webrtc else "webrtc: no\n"
+    hls_line = "" if cfg.enable_hls else "hls: no\n"
+
+    # ffmpeg: take the MJPEG multipart stream, re-encode to H.264 baseline,
+    # cap fps, push it to MediaMTX on localhost as a relay source. MediaMTX
+    # substitutes $RTSP_PORT and $MTX_PATH when it executes this command.
+    ffmpeg_cmd = (
+        f"{ffmpeg_bin} -hide_banner -loglevel warning "
+        f"-fflags nobuffer -flags low_delay "
+        f"-f mjpeg -use_wallclock_as_timestamps 1 -i {cam_url} "
+        f"-r {cfg.fps} "
+        f"-c:v libx264 -preset {cfg.preset} -tune {cfg.tune} "
+        f"-profile:v baseline -pix_fmt yuv420p -g {cfg.fps * 2} "
+        f"-b:v {cfg.bitrate} -maxrate {cfg.bitrate} -bufsize {cfg.bitrate} "
+        f"-an -f rtsp -rtsp_transport tcp rtsp://127.0.0.1:$RTSP_PORT/$MTX_PATH"
+    )
+
+    return (
+        f"# pycentauri-generated MediaMTX config — safe to delete.\n"
+        f"logLevel: {cfg.log_level}\n"
+        f"logDestinations: [stdout]\n"
+        f"rtspAddress: {rtsp_address}\n"
+        f"rtmp: no\n"
+        f"{hls_line}"
+        f"{webrtc_line}"
+        f"srt: no\n"
+        f"paths:\n"
+        f"  {cfg.path}:\n"
+        f"    runOnDemand: {ffmpeg_cmd}\n"
+        f"    runOnDemandRestart: yes\n"
+        f"    runOnDemandCloseAfter: 30s\n"
+    )
+
+
+def render_config(cfg: RtspConfig, ffmpeg_bin: str | None = None) -> str:
+    """Public entry point for tests — render the YAML config as a string."""
+    ffmpeg = ffmpeg_bin or find_binary("ffmpeg", cfg.ffmpeg_path) or "ffmpeg"
+    return _mediamtx_yaml(cfg, ffmpeg)
+
+
+def ensure_binaries(cfg: RtspConfig) -> tuple[str, str]:
+    """Return ``(mediamtx_bin, ffmpeg_bin)`` or raise :class:`RtspError`."""
+    mediamtx = find_binary("mediamtx", cfg.mediamtx_path)
+    if mediamtx is None:
+        raise RtspError(INSTALL_HINT)
+    ffmpeg = find_binary("ffmpeg", cfg.ffmpeg_path)
+    if ffmpeg is None:
+        raise RtspError(FFMPEG_HINT)
+    return mediamtx, ffmpeg
+
+
+def build_urls(cfg: RtspConfig, *, advertised_host: str | None = None) -> list[str]:
+    """Return the RTSP URLs a client should use to connect."""
+    host = advertised_host or cfg.bind
+    if host in ("0.0.0.0", "::", ""):
+        host = "<this-host>"
+    return [f"rtsp://{host}:{cfg.rtsp_port}/{cfg.path}"]
+
+
+def run(cfg: RtspConfig) -> int:
+    """Launch MediaMTX in the foreground. Returns its exit code.
+
+    The caller owns the lifecycle — we block until MediaMTX exits or we get
+    SIGINT/SIGTERM, then propagate the signal into the child and wait for
+    it to clean up.
+    """
+    mediamtx_bin, ffmpeg_bin = ensure_binaries(cfg)
+
+    yaml_text = _mediamtx_yaml(cfg, ffmpeg_bin)
+
+    # Write the config to a tempfile that outlives this scope only until
+    # MediaMTX has read it (which happens immediately at startup).
+    fd, cfg_path = tempfile.mkstemp(prefix="pycentauri-mediamtx-", suffix=".yml", text=True)
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(yaml_text)
+
+        print(f"pycentauri: launching MediaMTX ({mediamtx_bin})")
+        print(f"  printer MJPEG → {cfg.printer_host}:{cfg.camera_port}{cfg.camera_path}")
+        print("  RTSP URLs (share with VLC / HASS / Jellyfin / Frigate):")
+        for url in build_urls(cfg):
+            print(f"    {url}")
+        print(f"  config: {cfg_path}")
+        print("  (Ctrl-C to stop)")
+
+        proc = subprocess.Popen(
+            [mediamtx_bin, cfg_path],
+            stdout=None,
+            stderr=None,
+            start_new_session=True,
+        )
+
+        def _forward(signum: int, _frame: object) -> None:
+            proc.send_signal(signum)
+
+        old_int = signal.signal(signal.SIGINT, _forward)
+        old_term = signal.signal(signal.SIGTERM, _forward)
+        try:
+            return proc.wait()
+        finally:
+            signal.signal(signal.SIGINT, old_int)
+            signal.signal(signal.SIGTERM, old_term)
+    finally:
+        with contextlib.suppress(OSError):
+            os.unlink(cfg_path)
+
+
+def start_detached(cfg: RtspConfig) -> tuple[subprocess.Popen[bytes], str]:
+    """Spawn MediaMTX as a detached subprocess for supervised lifetimes.
+
+    Returns ``(process, config_path)``. The caller owns cleanup:
+    :func:`stop_detached` terminates the process and removes the config file.
+    Useful when the HTTP server manages RTSP toggling from the web UI.
+    """
+    mediamtx_bin, ffmpeg_bin = ensure_binaries(cfg)
+    yaml_text = _mediamtx_yaml(cfg, ffmpeg_bin)
+    fd, cfg_path = tempfile.mkstemp(prefix="pycentauri-mediamtx-", suffix=".yml", text=True)
+    with os.fdopen(fd, "w") as f:
+        f.write(yaml_text)
+    proc = subprocess.Popen(
+        [mediamtx_bin, cfg_path],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    return proc, cfg_path
+
+
+def stop_detached(
+    proc: subprocess.Popen[bytes] | None,
+    cfg_path: str | None,
+    *,
+    timeout: float = 5.0,
+) -> None:
+    """Clean up a :func:`start_detached` pair. Idempotent."""
+    if proc is not None and proc.poll() is None:
+        proc.terminate()
+        try:
+            proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            with contextlib.suppress(Exception):
+                proc.wait(timeout=2.0)
+    if cfg_path:
+        with contextlib.suppress(OSError):
+            os.unlink(cfg_path)
+
+
+__all__ = [
+    "FFMPEG_HINT",
+    "INSTALL_HINT",
+    "RtspConfig",
+    "RtspError",
+    "build_urls",
+    "ensure_binaries",
+    "find_binary",
+    "render_config",
+    "run",
+    "start_detached",
+    "stop_detached",
+]