plexus-python 0.4.6__py3-none-any.whl → 0.4.8__py3-none-any.whl

plexus/__init__.py

@@ -7,8 +7,8 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
     px.send("temperature", 72.5)
 """
 
-from plexus.client import Plexus
+from plexus.client import Plexus, read_mjpeg_frames
 from plexus.ws import WebSocketTransport
 
-__version__ = "0.4.6"
-__all__ = ["Plexus", "WebSocketTransport"]
+__version__ = "0.4.8"
+__all__ = ["Plexus", "WebSocketTransport", "read_mjpeg_frames"]

plexus/client.py

@@ -33,14 +33,18 @@ Usage:
 Note: Requires authentication. Run 'plexus start' or set PLEXUS_API_KEY.
 """
 
+import base64
 import gzip
 import json
 import logging
 import os
+import shutil
+import subprocess
 import sys
+import threading
 import time
 from contextlib import contextmanager
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, Generator, List, Optional, Tuple, Union
 
 import requests
 
@@ -74,6 +78,36 @@ def _say(line: str) -> None:
 # Flexible value type - supports any JSON-serializable value
 FlexValue = Union[int, float, str, bool, Dict[str, Any], List[Any]]
 
+_JPEG_SOI = b"\xff\xd8"
+_JPEG_EOI = b"\xff\xd9"
+_FRAME_JPEG_MAX = 750_000  # gateway is 1MB; base64 × 1.33 + envelope ≈ 998KB at this size
+
+
+def read_mjpeg_frames(pipe, chunk: int = 65536) -> Generator[bytes, None, None]:
+    """Read a raw MJPEG byte stream (e.g. FFmpeg stdout) and yield complete JPEG frames.
+
+    Scans for SOI (\xff\xd8) / EOI (\xff\xd9) markers to delimit frames.
+    Useful when building custom FFmpeg pipelines and handing off bytes to
+    send_video_frame().
+    """
+    buf = b""
+    while True:
+        data = pipe.read(chunk)
+        if not data:
+            break
+        buf += data
+        while True:
+            start = buf.find(_JPEG_SOI)
+            if start == -1:
+                buf = b""
+                break
+            end = buf.find(_JPEG_EOI, start + 2)
+            if end == -1:
+                buf = buf[start:]  # keep partial frame
+                break
+            yield buf[start:end + 2]
+            buf = buf[end + 2:]
+
 
 class PlexusError(Exception):
     """Base exception for Plexus errors."""
@@ -134,6 +168,9 @@ class Plexus:
         self._run_id: Optional[str] = None
         self._session: Optional[requests.Session] = None
         self._store_frames: bool = False
+        self._cv2 = None
+        self._pil_image = None  # lazy PIL.Image import
+        self._fit_warned: bool = False
 
         if transport not in ("ws", "http"):
             raise ValueError(f"transport must be 'ws' or 'http', got {transport!r}")
@@ -342,6 +379,230 @@ class Plexus:
         except Exception as e:  # pragma: no cover - persistence failure is non-fatal
             logger.debug("failed to persist assigned source_id: %s", e)
 
+    def _encode_frame(self, frame, quality: int) -> Tuple[bytes, int, int]:
+        """Normalize any supported frame type to (jpeg_bytes, width, height).
+
+        Accepted inputs:
+          - bytes/bytearray: raw JPEG passthrough (magic \\xff\\xd8), or any
+            Pillow-readable format (PNG, BMP, WebP) which is decoded and re-encoded
+          - numpy ndarray: encoded via OpenCV (cv2 must be installed)
+        """
+        import io
+
+        # --- bytes input ---
+        if isinstance(frame, (bytes, bytearray)):
+            if frame[:2] == b"\xff\xd8":
+                # Already JPEG — passthrough, extract dimensions via Pillow if available
+                try:
+                    pil = self._get_pil()
+                    img = pil.open(io.BytesIO(frame))
+                    return bytes(frame), img.width, img.height
+                except Exception:
+                    # Pillow unavailable or unreadable — send as-is, dimensions unknown
+                    return bytes(frame), 0, 0
+            # Non-JPEG bytes (PNG, BMP, WebP, …) — Pillow decode then re-encode as JPEG
+            pil = self._get_pil(required=True)
+            img = pil.open(io.BytesIO(frame))
+            return self._pil_to_jpeg(img, quality)
+
+        # --- numpy array (OpenCV path) ---
+        if hasattr(frame, "shape"):
+            cv2 = self._get_cv2(required=True)
+            height, width = frame.shape[:2]
+            ok, buf = cv2.imencode(".jpg", frame, [cv2.IMWRITE_JPEG_QUALITY, quality])
+            if not ok:
+                raise PlexusError("cv2.imencode failed to encode frame")
+            return buf.tobytes(), width, height
+
+        raise ValueError(
+            f"Unsupported frame type: {type(frame).__name__}. "
+            "Expected bytes/bytearray (JPEG or Pillow-readable) or numpy ndarray."
+        )
+
+    def _get_cv2(self, required: bool = False):
+        if self._cv2 is None:
+            try:
+                import cv2 as _cv2
+                self._cv2 = _cv2
+            except ImportError as e:
+                if required:
+                    raise ImportError(
+                        "This frame type requires opencv-python. "
+                        "Install with: pip install opencv-python"
+                    ) from e
+        return self._cv2
+
+    def _get_pil(self, required: bool = False):
+        if self._pil_image is None:
+            try:
+                import PIL.Image as _PILImage
+                self._pil_image = _PILImage
+            except ImportError as e:
+                if required:
+                    raise ImportError(
+                        "This frame type requires Pillow. "
+                        "Install with: pip install plexus-python[video]"
+                    ) from e
+        return self._pil_image
+
+    def _pil_to_jpeg(self, img, quality: int) -> Tuple[bytes, int, int]:
+        import io
+        if img.mode not in ("RGB", "L"):
+            img = img.convert("RGB")
+        buf = io.BytesIO()
+        img.save(buf, format="JPEG", quality=quality)
+        return buf.getvalue(), img.width, img.height
+
+    def _fit_to_wire(self, jpeg_bytes: bytes, requested_quality: int) -> bytes:
+        """Re-encode JPEG at lower quality if it would exceed the gateway 1MB limit.
+
+        Warns once per Plexus instance so the user sees the issue at startup
+        without being flooded during a live stream.
+        """
+        import io
+        if len(jpeg_bytes) <= _FRAME_JPEG_MAX:
+            return jpeg_bytes
+        target_quality = max(10, int(requested_quality * _FRAME_JPEG_MAX / len(jpeg_bytes)))
+        pil = self._get_pil()
+        if pil is None:
+            if not self._fit_warned:
+                self._fit_warned = True
+                wire_kb = len(jpeg_bytes) * 4 // 3 // 1024
+                _say(
+                    f"frame too large (~{wire_kb}KB on wire) and Pillow is not installed — "
+                    "install plexus-python[video] to enable automatic downsampling"
+                )
+            return jpeg_bytes
+        try:
+            img = pil.open(io.BytesIO(jpeg_bytes))
+            buf = io.BytesIO()
+            if img.mode not in ("RGB", "L"):
+                img = img.convert("RGB")
+            img.save(buf, format="JPEG", quality=target_quality)
+            result = buf.getvalue()
+            if not self._fit_warned:
+                self._fit_warned = True
+                wire_kb = len(jpeg_bytes) * 4 // 3 // 1024
+                _say(
+                    f"frame too large (quality={requested_quality}, ~{wire_kb}KB on wire), "
+                    f"re-encoded at quality={target_quality} — lower quality or resolution to silence"
+                )
+            return result
+        except Exception as e:
+            logger.debug("_fit_to_wire re-encode failed: %s", e)
+            return jpeg_bytes
+
+    def send_video_frame(
+        self,
+        frame,
+        camera_id: str = "camera:0",
+        quality: int = 85,
+        timestamp: Optional[float] = None,
+    ) -> bool:
+        """Send a single video frame to Plexus (WebSocket transport only).
+
+        Args:
+            frame: One of:
+                - numpy ndarray (H, W, C) — from cv2.VideoCapture or picamera2
+                - bytes/bytearray — raw JPEG passthrough (zero re-encode), or any
+                  Pillow-readable format (PNG, BMP, WebP) which is decoded and re-encoded
+            camera_id: Logical camera identifier (e.g. "picam:0", "usb:1")
+            quality: JPEG compression quality, 1-100. Default 85. Also used as the
+                baseline when adaptive downsampling kicks in for oversized frames.
+            timestamp: Unix timestamp in seconds. If not provided, uses current time.
+
+        Returns:
+            True if the frame was sent successfully.
+
+        Raises:
+            PlexusError: If transport is not 'ws'.
+            ValueError: If frame type is not supported.
+            ImportError: If a required optional dependency is missing.
+        """
+        if self.transport != "ws":
+            raise PlexusError("send_video_frame requires transport='ws'")
+
+        jpeg_bytes, width, height = self._encode_frame(frame, quality)
+        jpeg_bytes = self._fit_to_wire(jpeg_bytes, quality)
+        b64 = base64.b64encode(jpeg_bytes).decode()
+
+        ws = self._ensure_ws()
+        if not ws.is_authenticated:
+            ws.wait_authenticated(timeout=min(self.timeout, 5.0))
+
+        return ws._send_frame({
+            "type": "video_frame",
+            "source_id": self.source_id,
+            "camera_id": camera_id,
+            "frame": b64,
+            "width": width,
+            "height": height,
+            "timestamp": self._normalize_ts_ms(timestamp),
+        })
+
+    def stream_camera(
+        self,
+        url: str,
+        camera_id: str = "camera:0",
+        fps: int = 15,
+        quality: int = 85,
+    ) -> "threading.Event":
+        """Stream video from an RTSP URL or file path via FFmpeg (WebSocket only).
+
+        Requires FFmpeg to be installed and available on $PATH.
+
+        Args:
+            url: RTSP stream URL (rtsp://...), video file path, or any FFmpeg-supported source.
+            camera_id: Logical camera identifier forwarded in each frame.
+            fps: Maximum frames per second to send. Default 15.
+            quality: JPEG quality for re-encoded frames, 1-100. Default 85.
+
+        Returns:
+            A threading.Event. Call .set() on it to stop streaming.
+
+        Raises:
+            PlexusError: If transport is not 'ws' or FFmpeg is not found.
+
+        Example:
+            stop = px.stream_camera("rtsp://192.168.1.100/stream", camera_id="front:0")
+            time.sleep(60)
+            stop.set()
+        """
+        if self.transport != "ws":
+            raise PlexusError("stream_camera requires transport='ws'")
+        if shutil.which("ffmpeg") is None:
+            raise PlexusError(
+                "FFmpeg not found. Install it: https://ffmpeg.org/download.html"
+            )
+
+        stop_event = threading.Event()
+
+        def _run():
+            cmd = [
+                "ffmpeg", "-loglevel", "error",
+                "-i", url,
+                "-vf", f"fps={fps}",
+                "-f", "image2pipe",
+                "-vcodec", "mjpeg",
+                "pipe:1",
+            ]
+            proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+            try:
+                for jpeg in read_mjpeg_frames(proc.stdout):
+                    if stop_event.is_set():
+                        break
+                    try:
+                        self.send_video_frame(jpeg, camera_id=camera_id, quality=quality)
+                    except Exception as e:
+                        logger.debug("stream_camera send error: %s", e)
+            finally:
+                proc.terminate()
+                proc.wait()
+
+        t = threading.Thread(target=_run, daemon=True)
+        t.start()
+        return stop_event
+
     def on_command(
         self,
         name: str,

plexus/ws.py

@@ -292,7 +292,6 @@ class WebSocketTransport:
             _say(f"✓ Reconnected as {self.source_id}")
         else:
             _say(f"✓ Connected to gateway as {self.source_id}")
-            _say(f"  endpoint: {self.ws_url}")
 
         # 3. Read loop with heartbeat pump
         ws.settimeout(1.0)

{plexus_python-0.4.6.dist-info → plexus_python-0.4.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.4.6
+Version: 0.4.8
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -30,6 +30,8 @@ Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: websockets>=12; extra == 'dev'
+Provides-Extra: video
+Requires-Dist: pillow>=9.0; extra == 'video'
 Description-Content-Type: text/markdown
 
 # plexus-python

plexus_python-0.4.8.dist-info/RECORD

@@ -0,0 +1,11 @@
+plexus/__init__.py,sha256=TSQdqBAXxoyHxbeAr-UNcqZG411PCmxiM8kpI-hcc2s,385
+plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
+plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
+plexus/client.py,sha256=qWooAr2-Y8FUr_wpwnjXwdygGuHhPZLCYuVVU2cBziY,33047
+plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
+plexus/ws.py,sha256=4nmNganwS_1BujdFkH3u3lLBB7rEkPYd_oYrbdYkdY4,14818
+plexus_python-0.4.8.dist-info/METADATA,sha256=ssT_r6xkkeT5E6SBx2RWCP008vYhlMqtFMyi1yBRhd4,8188
+plexus_python-0.4.8.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plexus_python-0.4.8.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.4.8.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.4.8.dist-info/RECORD,,

plexus_python-0.4.6.dist-info/RECORD

@@ -1,11 +0,0 @@
-plexus/__init__.py,sha256=upqHP1A19Sp_CnCeCBHHJ1GUKKzeCJiJw5w3wD2K4cE,345
-plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
-plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
-plexus/client.py,sha256=JmEKKRu4ik548uBPMEOCcB_r_asRmuNORZF4snjFosQ,22956
-plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
-plexus/ws.py,sha256=aynJTH8LHRA4_U1OfIu-2aaOg1tLniUcWbzB2yuiQvU,14865
-plexus_python-0.4.6.dist-info/METADATA,sha256=d6Vp27f4EsfSHeS0NT6z9oWF85UIsLskMzzborehyQQ,8121
-plexus_python-0.4.6.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-plexus_python-0.4.6.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
-plexus_python-0.4.6.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
-plexus_python-0.4.6.dist-info/RECORD,,