pycentauri 0.3.1__tar.gz → 0.4.0__tar.gz

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

@@ -6,6 +6,27 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycentauri
-Version: 0.3.1
+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.1 → 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.1 → pycentauri-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycentauri"
-version = "0.3.1"
+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.1 → pycentauri-0.4.0}/src/pycentauri/__init__.py

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

{pycentauri-0.3.1 → 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",
+]

{pycentauri-0.3.1 → pycentauri-0.4.0}/src/pycentauri/server.py

@@ -28,6 +28,7 @@ import asyncio
 import contextlib
 import json
 import logging
+import subprocess
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from importlib.resources import files as resource_files
@@ -41,6 +42,7 @@ from pydantic import BaseModel, Field
 from sse_starlette.sse import EventSourceResponse
 
 from pycentauri import __version__
+from pycentauri import rtsp as rtsp_module
 from pycentauri.camera import CAMERA_PATH, CAMERA_PORT
 from pycentauri.client import ControlDisabledError, Printer, PrinterError
 from pycentauri.discovery import DiscoveredPrinter
@@ -143,6 +145,75 @@ class PrinterManager:
             backoff = min(backoff * 2, RECONNECT_BACKOFF_MAX)
 
 
+class RtspController:
+    """Start / stop a MediaMTX subprocess on demand from the HTTP server.
+
+    Designed to be held on ``app.state`` alongside the PrinterManager and
+    driven by the web UI. Idempotent: multiple start calls while already
+    running are a no-op; stop on a stopped server is a no-op.
+    """
+
+    def __init__(self, cfg: rtsp_module.RtspConfig) -> None:
+        self.cfg = cfg
+        self._proc: subprocess.Popen[bytes] | None = None
+        self._cfg_path: str | None = None
+        self._last_error: str | None = None
+        self._lock = asyncio.Lock()
+
+    @property
+    def running(self) -> bool:
+        return self._proc is not None and self._proc.poll() is None
+
+    @property
+    def last_error(self) -> str | None:
+        return self._last_error
+
+    def urls(self, advertised_host: str | None = None) -> list[str]:
+        return rtsp_module.build_urls(self.cfg, advertised_host=advertised_host)
+
+    def available(self) -> bool:
+        try:
+            rtsp_module.ensure_binaries(self.cfg)
+            return True
+        except rtsp_module.RtspError:
+            return False
+
+    def unavailable_reason(self) -> str | None:
+        try:
+            rtsp_module.ensure_binaries(self.cfg)
+            return None
+        except rtsp_module.RtspError as err:
+            return str(err)
+
+    async def start(self) -> None:
+        async with self._lock:
+            if self.running:
+                return
+            # The subprocess spawn itself is fast but blocks briefly; run it
+            # in a thread so we don't stall the event loop.
+            loop = asyncio.get_running_loop()
+            try:
+                proc, cfg_path = await loop.run_in_executor(
+                    None, rtsp_module.start_detached, self.cfg
+                )
+            except rtsp_module.RtspError as err:
+                self._last_error = str(err)
+                raise
+            self._proc = proc
+            self._cfg_path = cfg_path
+            self._last_error = None
+
+    async def stop(self) -> None:
+        async with self._lock:
+            proc, cfg_path = self._proc, self._cfg_path
+            self._proc = None
+            self._cfg_path = None
+        if proc is None and cfg_path is None:
+            return
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, rtsp_module.stop_detached, proc, cfg_path)
+
+
 # --- Pydantic request bodies ------------------------------------------------
 
 
@@ -183,22 +254,28 @@ def create_app(
     *,
     enable_control: bool = False,
     mainboard_id: str | None = None,
+    rtsp_config: rtsp_module.RtspConfig | None = None,
 ) -> FastAPI:
     """Build the FastAPI app. ``host`` is the printer's IP/hostname.
 
     The app runs a single background :class:`PrinterManager` that owns the
     WebSocket lifecycle. Control endpoints are registered only when
-    ``enable_control`` is ``True``.
+    ``enable_control`` is ``True``. ``rtsp_config`` enables the
+    ``/api/rtsp/*`` endpoints and the "STREAM" panel in the web UI.
     """
 
     @asynccontextmanager
     async def lifespan(app: FastAPI) -> AsyncIterator[None]:
         manager = PrinterManager(host, enable_control=enable_control, mainboard_id=mainboard_id)
         app.state.manager = manager
+        app.state.rtsp = RtspController(rtsp_config) if rtsp_config is not None else None
         await manager.start()
         try:
             yield
         finally:
+            if app.state.rtsp is not None:
+                with contextlib.suppress(Exception):
+                    await app.state.rtsp.stop()
             await manager.stop()
 
     app = FastAPI(
@@ -342,6 +419,62 @@ def create_app(
 
         return EventSourceResponse(gen())
 
+    # --- RTSP bridge --------------------------------------------------------
+
+    def _rtsp_state(request: Request) -> dict[str, Any]:
+        controller: RtspController | None = getattr(request.app.state, "rtsp", None)
+        if controller is None:
+            return {
+                "enabled": False,
+                "available": False,
+                "running": False,
+                "urls": [],
+                "advertised_urls": [],
+                "reason": "RTSP feature not enabled on server; pass --rtsp on centauri server",
+            }
+        advertised_host = request.url.hostname
+        return {
+            "enabled": True,
+            "available": controller.available(),
+            "running": controller.running,
+            "port": controller.cfg.rtsp_port,
+            "path": controller.cfg.path,
+            "fps": controller.cfg.fps,
+            "bitrate": controller.cfg.bitrate,
+            "urls": controller.urls(),
+            "advertised_urls": controller.urls(advertised_host=advertised_host),
+            "reason": controller.unavailable_reason() or controller.last_error,
+        }
+
+    @app.get("/api/rtsp", tags=["rtsp"])
+    async def rtsp_status(request: Request) -> dict[str, Any]:
+        return _rtsp_state(request)
+
+    @app.post("/api/rtsp/start", tags=["rtsp"])
+    async def rtsp_start(request: Request) -> dict[str, Any]:
+        controller: RtspController | None = getattr(request.app.state, "rtsp", None)
+        if controller is None:
+            raise HTTPException(
+                status_code=404,
+                detail="RTSP feature not enabled. Launch server with --rtsp.",
+            )
+        try:
+            await controller.start()
+        except rtsp_module.RtspError as err:
+            raise HTTPException(status_code=503, detail=str(err)) from err
+        return _rtsp_state(request)
+
+    @app.post("/api/rtsp/stop", tags=["rtsp"])
+    async def rtsp_stop(request: Request) -> dict[str, Any]:
+        controller: RtspController | None = getattr(request.app.state, "rtsp", None)
+        if controller is None:
+            raise HTTPException(
+                status_code=404,
+                detail="RTSP feature not enabled. Launch server with --rtsp.",
+            )
+        await controller.stop()
+        return _rtsp_state(request)
+
     # --- Meta / health ------------------------------------------------------
 
     @app.get("/api/info", tags=["meta"])
@@ -444,6 +577,7 @@ def run(
     enable_control: bool = False,
     mainboard_id: str | None = None,
     log_level: str = "info",
+    rtsp_config: rtsp_module.RtspConfig | None = None,
 ) -> None:
     """Launch the server with uvicorn (blocks).
 
@@ -453,7 +587,12 @@ def run(
     """
     import uvicorn
 
-    app = create_app(host, enable_control=enable_control, mainboard_id=mainboard_id)
+    app = create_app(
+        host,
+        enable_control=enable_control,
+        mainboard_id=mainboard_id,
+        rtsp_config=rtsp_config,
+    )
     uvicorn.run(app, host=bind, port=port, log_level=log_level)
 
 

{pycentauri-0.3.1 → pycentauri-0.4.0}/src/pycentauri/web/app.js

@@ -251,6 +251,120 @@ function wireControls() {
   });
 }
 
+// ---------------------------------------------------------------------------
+// RTSP bridge
+
+function setRtspMsg(text, kind) {
+  const el = $("rtsp-msg");
+  el.classList.remove("ok", "err", "warn");
+  if (kind) el.classList.add(kind);
+  el.textContent = text || "";
+}
+
+function renderRtsp(info) {
+  const panel = $("rtsp-panel");
+  if (!info || !info.enabled) {
+    panel.hidden = true;
+    return;
+  }
+  panel.hidden = false;
+
+  const state = $("rtsp-state");
+  const btn   = $("btn-rtsp-toggle");
+  const lbl   = $("btn-rtsp-label");
+  const url   = $("rtsp-url");
+  const meta  = $("rtsp-meta");
+
+  // URL — prefer the advertised URL that uses the hostname the user hit us with.
+  const shown = (info.advertised_urls && info.advertised_urls[0]) ||
+                (info.urls && info.urls[0]) ||
+                "rtsp://—";
+  url.textContent = shown;
+  url.classList.toggle("dim", !info.running);
+
+  // Meta: port, path, fps, bitrate
+  const parts = [];
+  if (info.port)    parts.push(`PORT ${info.port}`);
+  if (info.path)    parts.push(`PATH /${info.path}`);
+  if (info.fps)     parts.push(`FPS ${info.fps}`);
+  if (info.bitrate) parts.push(`BR ${info.bitrate}`);
+  meta.textContent = parts.join("   ·   ");
+
+  // State + button
+  state.classList.remove("on", "off", "err", "na");
+  if (!info.available) {
+    state.textContent = "N/A";
+    state.classList.add("na");
+    lbl.textContent = "N/A";
+    btn.disabled = true;
+    setRtspMsg(info.reason || "MediaMTX or ffmpeg not available.", "err");
+    return;
+  }
+  if (info.running) {
+    state.textContent = "ONLINE";
+    state.classList.add("on");
+    lbl.textContent = "STOP";
+  } else {
+    state.textContent = "OFFLINE";
+    state.classList.add("off");
+    lbl.textContent = "START";
+  }
+  btn.disabled = false;
+
+  if (info.reason && !info.running) {
+    setRtspMsg(info.reason, "warn");
+  } else if (info.running) {
+    setRtspMsg("MediaMTX running · ffmpeg transcode is on-demand", "ok");
+  } else {
+    setRtspMsg("", null);
+  }
+}
+
+async function loadRtsp() {
+  try {
+    const r = await fetch("/api/rtsp");
+    if (!r.ok) { $("rtsp-panel").hidden = true; return; }
+    renderRtsp(await r.json());
+  } catch (e) {
+    $("rtsp-panel").hidden = true;
+  }
+}
+
+async function toggleRtsp() {
+  const btn = $("btn-rtsp-toggle");
+  const isRunning = $("rtsp-state").classList.contains("on");
+  const path = isRunning ? "/api/rtsp/stop" : "/api/rtsp/start";
+  btn.disabled = true;
+  setRtspMsg(isRunning ? "stopping MediaMTX…" : "starting MediaMTX…");
+  try {
+    const r = await fetch(path, { method: "POST" });
+    if (!r.ok) throw new Error(`HTTP ${r.status}: ${await r.text()}`);
+    renderRtsp(await r.json());
+  } catch (e) {
+    setRtspMsg(`${isRunning ? "stop" : "start"} failed — ${e.message}`, "err");
+    btn.disabled = false;
+  }
+}
+
+function wireRtsp() {
+  $("btn-rtsp-toggle")?.addEventListener("click", toggleRtsp);
+  $("btn-rtsp-copy")?.addEventListener("click", async () => {
+    const url = $("rtsp-url").textContent;
+    const btn = $("btn-rtsp-copy");
+    try {
+      await navigator.clipboard.writeText(url);
+      btn.classList.add("done");
+      btn.textContent = "OK";
+      setTimeout(() => {
+        btn.classList.remove("done");
+        btn.textContent = "COPY";
+      }, 1200);
+    } catch (_) {
+      setRtspMsg("clipboard blocked — select the URL and copy manually", "warn");
+    }
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Webcam resilience — if the MJPEG stream stalls, reload it.
 
@@ -274,9 +388,13 @@ function wireWebcamKeepalive() {
 
 (async function main() {
   wireControls();
+  wireRtsp();
   wireWebcamKeepalive();
   await loadInfo();
+  await loadRtsp();
   await pollOnce();
   connectSSE();
   setInterval(loadInfo, 60000);
+  // RTSP state changes are external, poll occasionally.
+  setInterval(loadRtsp, 8000);
 })();

{pycentauri-0.3.1 → pycentauri-0.4.0}/src/pycentauri/web/index.html

@@ -167,6 +167,27 @@
         </div>
       </div>
 
+      <!-- RTSP stream control -->
+      <div class="panel rtsp-panel" id="rtsp-panel" hidden>
+        <header class="panel-header">
+          <span class="panel-tag">STREAM</span>
+          <span class="panel-rule"></span>
+          <span class="panel-idx" id="rtsp-state-idx">06</span>
+        </header>
+        <div class="rtsp-row">
+          <span class="rtsp-state" id="rtsp-state">—</span>
+          <button id="btn-rtsp-toggle" class="kbd-btn rtsp-toggle" type="button" disabled>
+            <span class="kbd-label" id="btn-rtsp-label">—</span>
+          </button>
+        </div>
+        <div class="rtsp-url-wrap">
+          <code class="rtsp-url" id="rtsp-url">rtsp://—</code>
+          <button id="btn-rtsp-copy" class="copy-btn" type="button" title="Copy URL">COPY</button>
+        </div>
+        <div class="rtsp-meta" id="rtsp-meta"></div>
+        <div class="rtsp-msg" id="rtsp-msg" aria-live="polite"></div>
+      </div>
+
       <!-- Kinematics + fans -->
       <div class="panel tele-panel">
         <header class="panel-header">

{pycentauri-0.3.1 → pycentauri-0.4.0}/src/pycentauri/web/styles.css

@@ -707,6 +707,96 @@ body {
 .ctrl-msg.warn { border-left-color: var(--warn);   color: var(--warn); }
 .ctrl-msg.err  { border-left-color: var(--danger); color: var(--danger); }
 
+/* ---- RTSP panel ------------------------------------------- */
+
+.rtsp-panel { padding-bottom: 14px; }
+
+.rtsp-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 14px;
+  margin-bottom: 12px;
+}
+.rtsp-state {
+  font-family: var(--f-display);
+  font-weight: 700;
+  font-size: 20px;
+  letter-spacing: 0.04em;
+  color: var(--fg-dim);
+  text-transform: uppercase;
+}
+.rtsp-state.on  { color: var(--ok); }
+.rtsp-state.off { color: var(--fg-dim); }
+.rtsp-state.err { color: var(--danger); }
+.rtsp-state.na  { color: var(--fg-faint); }
+
+.rtsp-toggle {
+  min-width: 110px;
+  padding: 10px 14px;
+  border-bottom-width: 3px;
+}
+
+.rtsp-url-wrap {
+  display: flex;
+  align-items: stretch;
+  gap: 6px;
+  margin-bottom: 10px;
+}
+.rtsp-url {
+  flex: 1;
+  font-family: var(--f-mono);
+  font-size: 11px;
+  color: var(--cyan);
+  background: var(--bg-inset);
+  border: 1px solid var(--rule);
+  padding: 8px 10px;
+  overflow-x: auto;
+  white-space: nowrap;
+  user-select: all;
+}
+.rtsp-url.dim { color: var(--fg-faint); }
+
+.copy-btn {
+  padding: 0 12px;
+  font-family: var(--f-label);
+  font-size: 10px;
+  letter-spacing: 0.2em;
+  font-weight: 700;
+  color: var(--fg-dim);
+  background: var(--bg-inset);
+  border: 1px solid var(--rule);
+  cursor: pointer;
+  transition: color 0.15s, border-color 0.15s, background 0.15s;
+}
+.copy-btn:hover {
+  color: var(--amber);
+  border-color: var(--amber);
+  background: #1a1812;
+}
+.copy-btn.done { color: var(--ok); border-color: var(--ok); }
+
+.rtsp-meta {
+  font-family: var(--f-mono);
+  font-size: 10px;
+  color: var(--fg-dim);
+  letter-spacing: 0.04em;
+  padding: 4px 0;
+}
+
+.rtsp-msg {
+  margin-top: 6px;
+  font-family: var(--f-mono);
+  font-size: 11px;
+  color: var(--fg-dim);
+  min-height: 1.2em;
+  padding-left: 10px;
+  border-left: 2px solid var(--rule);
+}
+.rtsp-msg.ok   { border-left-color: var(--ok);     color: var(--ok); }
+.rtsp-msg.err  { border-left-color: var(--danger); color: var(--danger); }
+.rtsp-msg.warn { border-left-color: var(--warn);   color: var(--warn); }
+
 /* ---- Load-in cascade -------------------------------------- */
 
 .panel, .viewport {

pycentauri-0.4.0/tests/test_rtsp.py

@@ -0,0 +1,113 @@
+"""Unit tests for the RTSP launcher — no processes actually spawned."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from pycentauri.rtsp import (
+    FFMPEG_HINT,
+    INSTALL_HINT,
+    RtspConfig,
+    RtspError,
+    build_urls,
+    ensure_binaries,
+    find_binary,
+    render_config,
+)
+
+
+def test_find_binary_rejects_missing_override(tmp_path: Path) -> None:
+    assert find_binary("mediamtx", override=str(tmp_path / "does-not-exist")) is None
+
+
+def test_find_binary_accepts_executable_override(tmp_path: Path) -> None:
+    fake = tmp_path / "fake-bin"
+    fake.write_text("#!/bin/sh\nexit 0\n")
+    fake.chmod(0o755)
+    assert find_binary("whatever", override=str(fake)) == str(fake)
+
+
+def test_ensure_binaries_raises_when_mediamtx_missing(tmp_path: Path) -> None:
+    cfg = RtspConfig(
+        printer_host="192.168.1.209",
+        mediamtx_path=str(tmp_path / "nope"),
+    )
+    with pytest.raises(RtspError) as excinfo:
+        ensure_binaries(cfg)
+    assert INSTALL_HINT in str(excinfo.value)
+
+
+def test_ensure_binaries_raises_when_ffmpeg_missing(tmp_path: Path) -> None:
+    mtx = tmp_path / "mediamtx"
+    mtx.write_text("#!/bin/sh\nexit 0\n")
+    mtx.chmod(0o755)
+    cfg = RtspConfig(
+        printer_host="192.168.1.209",
+        mediamtx_path=str(mtx),
+        ffmpeg_path=str(tmp_path / "no-ffmpeg"),
+    )
+    with pytest.raises(RtspError) as excinfo:
+        ensure_binaries(cfg)
+    assert FFMPEG_HINT in str(excinfo.value)
+
+
+def test_render_config_contains_expected_fields() -> None:
+    cfg = RtspConfig(
+        printer_host="192.168.1.209",
+        rtsp_port=8554,
+        bind="0.0.0.0",
+        path="printer",
+        fps=15,
+        bitrate="2M",
+    )
+    yaml = render_config(cfg, ffmpeg_bin="/usr/bin/ffmpeg")
+    assert "rtspAddress: :8554" in yaml
+    assert "http://192.168.1.209:3031/video" in yaml
+    assert "paths:" in yaml
+    assert "  printer:" in yaml
+    assert "runOnDemand:" in yaml
+    assert "/usr/bin/ffmpeg" in yaml
+    assert "libx264" in yaml
+    assert "-b:v 2M" in yaml
+    assert "-r 15" in yaml
+    assert "webrtc: no" in yaml
+    assert "hls: no" in yaml
+
+
+def test_render_config_explicit_bind() -> None:
+    cfg = RtspConfig(printer_host="h", bind="127.0.0.1", rtsp_port=9000)
+    yaml = render_config(cfg, ffmpeg_bin="ffmpeg")
+    assert "rtspAddress: 127.0.0.1:9000" in yaml
+
+
+def test_render_config_custom_path() -> None:
+    cfg = RtspConfig(printer_host="h", path="workshop-cam-1")
+    yaml = render_config(cfg, ffmpeg_bin="ffmpeg")
+    assert "  workshop-cam-1:" in yaml
+
+
+def test_render_config_enables_webrtc_and_hls_when_requested() -> None:
+    cfg = RtspConfig(printer_host="h", enable_webrtc=True, enable_hls=True)
+    yaml = render_config(cfg, ffmpeg_bin="ffmpeg")
+    assert "webrtc: no" not in yaml
+    assert "hls: no" not in yaml
+
+
+def test_build_urls_masks_wildcard_bind() -> None:
+    cfg = RtspConfig(printer_host="h", bind="0.0.0.0", rtsp_port=8554, path="printer")
+    urls = build_urls(cfg)
+    assert urls == ["rtsp://<this-host>:8554/printer"]
+
+
+def test_build_urls_uses_advertised_host() -> None:
+    cfg = RtspConfig(printer_host="h", bind="0.0.0.0", rtsp_port=8554, path="printer")
+    assert build_urls(cfg, advertised_host="nix.brancloud.online") == [
+        "rtsp://nix.brancloud.online:8554/printer"
+    ]
+
+
+def test_build_urls_with_explicit_bind() -> None:
+    cfg = RtspConfig(printer_host="h", bind="192.168.1.101", rtsp_port=8554, path="cam")
+    assert build_urls(cfg) == ["rtsp://192.168.1.101:8554/cam"]

{pycentauri-0.3.1 → pycentauri-0.4.0}/tests/test_server.py

@@ -7,6 +7,7 @@ We hit the app through httpx's ASGI transport — no real HTTP port bound.
 
 from __future__ import annotations
 
+from pathlib import Path
 from typing import Any
 
 import httpx
@@ -96,6 +97,105 @@ async def test_control_endpoints_registered_when_enabled(monkeypatch: pytest.Mon
     await server.stop()
 
 
+async def test_rtsp_disabled_by_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    server = _FakePrinter()
+    await server.start()
+    monkeypatch.setattr("pycentauri.client.WS_PORT", server.port)
+
+    app = server_module.create_app("127.0.0.1", mainboard_id=MAINBOARD)
+    async with app.router.lifespan_context(app), await _asgi_client(app) as client:
+        r = await client.get("/api/rtsp")
+        assert r.status_code == 200
+        body = r.json()
+        assert body["enabled"] is False
+        assert body["running"] is False
+
+        # Start/stop should 404 when feature is off.
+        r = await client.post("/api/rtsp/start")
+        assert r.status_code == 404
+    await server.stop()
+
+
+async def test_rtsp_enabled_reports_state(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    # Don't actually spawn mediamtx — point the override at a fake binary so
+    # the availability check passes for /api/rtsp/start's "could not launch"
+    # path to be exercised, then end with a real stop() no-op.
+    fake_mtx = tmp_path / "mediamtx"
+    fake_mtx.write_text("#!/bin/sh\nsleep 60\n")
+    fake_mtx.chmod(0o755)
+    fake_ffmpeg = tmp_path / "ffmpeg"
+    fake_ffmpeg.write_text("#!/bin/sh\nsleep 60\n")
+    fake_ffmpeg.chmod(0o755)
+
+    from pycentauri.rtsp import RtspConfig
+
+    cfg = RtspConfig(
+        printer_host="192.168.1.209",
+        rtsp_port=18554,
+        bind="127.0.0.1",
+        path="printer",
+        mediamtx_path=str(fake_mtx),
+        ffmpeg_path=str(fake_ffmpeg),
+    )
+
+    fake_ws = _FakePrinter()
+    await fake_ws.start()
+    monkeypatch.setattr("pycentauri.client.WS_PORT", fake_ws.port)
+
+    app = server_module.create_app("127.0.0.1", mainboard_id=MAINBOARD, rtsp_config=cfg)
+    async with app.router.lifespan_context(app), await _asgi_client(app) as client:
+        r = await client.get("/api/rtsp")
+        assert r.status_code == 200
+        body = r.json()
+        assert body["enabled"] is True
+        assert body["available"] is True
+        assert body["running"] is False
+        assert body["port"] == 18554
+        assert body["path"] == "printer"
+        assert body["urls"] == ["rtsp://127.0.0.1:18554/printer"]
+
+        # Start will spawn the fake binary (which just sleeps).
+        r = await client.post("/api/rtsp/start")
+        assert r.status_code == 200
+        assert r.json()["running"] is True
+
+        # Stop cleans up.
+        r = await client.post("/api/rtsp/stop")
+        assert r.status_code == 200
+        assert r.json()["running"] is False
+    await fake_ws.stop()
+
+
+async def test_rtsp_unavailable_when_binaries_missing(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    from pycentauri.rtsp import RtspConfig
+
+    cfg = RtspConfig(
+        printer_host="192.168.1.209",
+        mediamtx_path=str(tmp_path / "does-not-exist"),
+    )
+
+    fake_ws = _FakePrinter()
+    await fake_ws.start()
+    monkeypatch.setattr("pycentauri.client.WS_PORT", fake_ws.port)
+
+    app = server_module.create_app("127.0.0.1", mainboard_id=MAINBOARD, rtsp_config=cfg)
+    async with app.router.lifespan_context(app), await _asgi_client(app) as client:
+        r = await client.get("/api/rtsp")
+        body = r.json()
+        assert body["enabled"] is True
+        assert body["available"] is False
+        assert body["running"] is False
+        assert "MediaMTX" in (body["reason"] or "")
+
+        # Start should 503 with an install hint.
+        r = await client.post("/api/rtsp/start")
+        assert r.status_code == 503
+        assert "MediaMTX" in r.text
+    await fake_ws.stop()
+
+
 async def test_start_print_request_body_validation(monkeypatch: pytest.MonkeyPatch) -> None:
     server = _FakePrinter()
     await server.start()