rocket-welder-sdk 1.0.4__py3-none-any.whl → 1.1.0__py3-none-any.whl

rocket_welder_sdk/gst_metadata.py

@@ -0,0 +1,240 @@
+"""
+GStreamer metadata structures for RocketWelder SDK.
+Matches C# GstCaps and GstMetadata functionality.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class GstCaps:
+    """
+    GStreamer capabilities representation.
+
+    Represents video format capabilities including format, dimensions, framerate, etc.
+    """
+
+    format: str | None = None
+    width: int | None = None
+    height: int | None = None
+    framerate: str | None = None  # e.g., "30/1" or "25/1"
+    pixel_aspect_ratio: str | None = None  # e.g., "1/1"
+    interlace_mode: str | None = None  # e.g., "progressive"
+    colorimetry: str | None = None
+    chroma_site: str | None = None
+
+    # Additional fields can be stored here
+    extra_fields: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> GstCaps:
+        """
+        Create GstCaps from dictionary.
+
+        Args:
+            data: Dictionary containing caps data
+
+        Returns:
+            GstCaps instance
+        """
+        # Extract known fields
+        caps = cls(
+            format=data.get("format"),
+            width=data.get("width"),
+            height=data.get("height"),
+            framerate=data.get("framerate"),
+            pixel_aspect_ratio=data.get("pixel-aspect-ratio"),
+            interlace_mode=data.get("interlace-mode"),
+            colorimetry=data.get("colorimetry"),
+            chroma_site=data.get("chroma-site"),
+        )
+
+        # Store any extra fields
+        known_fields = {
+            "format",
+            "width",
+            "height",
+            "framerate",
+            "pixel-aspect-ratio",
+            "interlace-mode",
+            "colorimetry",
+            "chroma-site",
+        }
+
+        for key, value in data.items():
+            if key not in known_fields:
+                caps.extra_fields[key] = value
+
+        return caps
+
+    @classmethod
+    def from_string(cls, caps_string: str) -> GstCaps:
+        """
+        Parse GStreamer caps string.
+
+        Args:
+            caps_string: GStreamer caps string (e.g., "video/x-raw,format=RGB,width=640,height=480")
+
+        Returns:
+            GstCaps instance
+        """
+        if not caps_string:
+            return cls()
+
+        # Remove media type prefix if present
+        if "/" in caps_string and "," in caps_string:
+            # Has media type prefix (e.g., "video/x-raw,format=RGB")
+            _, params = caps_string.split(",", 1)
+        else:
+            # No media type prefix (e.g., "format=RGB,width=320")
+            params = caps_string
+
+        # Parse parameters
+        data: dict[str, Any] = {}
+        for param in params.split(","):
+            if "=" in param:
+                key, value = param.split("=", 1)
+                key = key.strip()
+                value_str = value.strip()
+
+                # Try to parse numeric values
+                if value_str.isdigit():
+                    data[key] = int(value_str)
+                elif key in ["width", "height"] and value_str.startswith("(int)"):
+                    data[key] = int(value_str[5:].strip())
+                else:
+                    data[key] = value_str
+
+        return cls.from_dict(data)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        result: dict[str, Any] = {}
+
+        if self.format is not None:
+            result["format"] = self.format
+        if self.width is not None:
+            result["width"] = self.width
+        if self.height is not None:
+            result["height"] = self.height
+        if self.framerate is not None:
+            result["framerate"] = self.framerate
+        if self.pixel_aspect_ratio is not None:
+            result["pixel-aspect-ratio"] = self.pixel_aspect_ratio
+        if self.interlace_mode is not None:
+            result["interlace-mode"] = self.interlace_mode
+        if self.colorimetry is not None:
+            result["colorimetry"] = self.colorimetry
+        if self.chroma_site is not None:
+            result["chroma-site"] = self.chroma_site
+
+        # Add extra fields
+        result.update(self.extra_fields)
+
+        return result
+
+    def to_string(self) -> str:
+        """Convert to GStreamer caps string format."""
+        params = []
+
+        if self.format:
+            params.append(f"format={self.format}")
+        if self.width is not None:
+            params.append(f"width={self.width}")
+        if self.height is not None:
+            params.append(f"height={self.height}")
+        if self.framerate:
+            params.append(f"framerate={self.framerate}")
+        if self.pixel_aspect_ratio:
+            params.append(f"pixel-aspect-ratio={self.pixel_aspect_ratio}")
+        if self.interlace_mode:
+            params.append(f"interlace-mode={self.interlace_mode}")
+
+        # Add extra fields
+        for key, value in self.extra_fields.items():
+            params.append(f"{key}={value}")
+
+        if params:
+            return "video/x-raw," + ",".join(params)
+        else:
+            return "video/x-raw"
+
+    @property
+    def framerate_tuple(self) -> tuple[int, int] | None:
+        """Get framerate as a tuple of (numerator, denominator)."""
+        if not self.framerate or "/" not in self.framerate:
+            return None
+
+        try:
+            num, denom = self.framerate.split("/")
+            return (int(num), int(denom))
+        except (ValueError, AttributeError):
+            return None
+
+    @property
+    def fps(self) -> float | None:
+        """Get framerate as floating-point FPS value."""
+        fr = self.framerate_tuple
+        if fr and fr[1] != 0:
+            return fr[0] / fr[1]
+        return None
+
+
+@dataclass
+class GstMetadata:
+    """
+    GStreamer metadata structure.
+
+    Matches the JSON structure written by GStreamer plugins.
+    """
+
+    type: str
+    version: str
+    caps: GstCaps
+    element_name: str
+
+    @classmethod
+    def from_json(cls, json_data: str | bytes | dict[str, Any]) -> GstMetadata:
+        """
+        Create GstMetadata from JSON data.
+
+        Args:
+            json_data: JSON string, bytes, or dictionary
+
+        Returns:
+            GstMetadata instance
+        """
+        data = json.loads(json_data) if isinstance(json_data, (str, bytes)) else json_data
+
+        # Parse caps
+        caps_data = data.get("caps", {})
+        if isinstance(caps_data, str):
+            caps = GstCaps.from_string(caps_data)
+        elif isinstance(caps_data, dict):
+            caps = GstCaps.from_dict(caps_data)
+        else:
+            caps = GstCaps()
+
+        return cls(
+            type=data.get("type", ""),
+            version=data.get("version", ""),
+            caps=caps,
+            element_name=data.get("element_name", ""),
+        )
+
+    def to_json(self) -> str:
+        """Convert to JSON string."""
+        return json.dumps(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            "type": self.type,
+            "version": self.version,
+            "caps": self.caps.to_dict(),
+            "element_name": self.element_name,
+        }

rocket_welder_sdk/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561
+# This package contains inline type hints

rocket_welder_sdk/rocket_welder_client.py

@@ -0,0 +1,170 @@
+"""
+Enterprise-grade RocketWelder client for video streaming.
+Main entry point for the RocketWelder SDK.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import TYPE_CHECKING, Any, Callable
+
+import numpy as np
+
+from .connection_string import ConnectionMode, ConnectionString, Protocol
+from .controllers import DuplexShmController, IController, OneWayShmController
+
+if TYPE_CHECKING:
+    from .gst_metadata import GstMetadata
+
+# Type alias for OpenCV Mat
+Mat = np.ndarray[Any, Any]
+
+
+class RocketWelderClient:
+    """
+    Main client for RocketWelder video streaming services.
+
+    Provides a unified interface for different connection types and protocols.
+    """
+
+    def __init__(self, connection: str | ConnectionString, logger: logging.Logger | None = None):
+        """
+        Initialize the RocketWelder client.
+
+        Args:
+            connection: Connection string or ConnectionString object
+            logger: Optional logger instance
+        """
+        if isinstance(connection, str):
+            self._connection = ConnectionString.parse(connection)
+        else:
+            self._connection = connection
+
+        self._logger = logger or logging.getLogger(__name__)
+        self._controller: IController | None = None
+        self._lock = threading.Lock()
+
+    @property
+    def connection(self) -> ConnectionString:
+        """Get the connection configuration."""
+        return self._connection
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the client is running."""
+        with self._lock:
+            return self._controller is not None and self._controller.is_running
+
+    def get_metadata(self) -> GstMetadata | None:
+        """
+        Get the current GStreamer metadata.
+
+        Returns:
+            GstMetadata or None if not available
+        """
+        with self._lock:
+            if self._controller:
+                return self._controller.get_metadata()
+            return None
+
+    def start(
+        self,
+        on_frame: Callable[[Mat], None] | Callable[[Mat, Mat], None],
+        cancellation_token: threading.Event | None = None,
+    ) -> None:
+        """
+        Start receiving/processing video frames.
+
+        Args:
+            on_frame: Callback for frame processing.
+                     For one-way: (input_frame) -> None
+                     For duplex: (input_frame, output_frame) -> None
+            cancellation_token: Optional cancellation token
+
+        Raises:
+            RuntimeError: If already running
+            ValueError: If connection type is not supported
+        """
+        with self._lock:
+            if self._controller and self._controller.is_running:
+                raise RuntimeError("Client is already running")
+
+            # Create appropriate controller based on connection
+            if self._connection.protocol == Protocol.SHM:
+                if self._connection.connection_mode == ConnectionMode.DUPLEX:
+                    self._controller = DuplexShmController(self._connection, self._logger)
+                else:
+                    self._controller = OneWayShmController(self._connection, self._logger)
+            else:
+                raise ValueError(f"Unsupported protocol: {self._connection.protocol}")
+
+            # Start the controller
+            self._controller.start(on_frame, cancellation_token)  # type: ignore[arg-type]
+            self._logger.info("RocketWelder client started with %s", self._connection)
+
+    def stop(self) -> None:
+        """Stop the client and clean up resources."""
+        with self._lock:
+            if self._controller:
+                self._controller.stop()
+                self._controller = None
+                self._logger.info("RocketWelder client stopped")
+
+    def __enter__(self) -> RocketWelderClient:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.stop()
+
+    @classmethod
+    def create_oneway_shm(
+        cls,
+        buffer_name: str,
+        buffer_size: str = "256MB",
+        metadata_size: str = "4KB",
+        logger: logging.Logger | None = None,
+    ) -> RocketWelderClient:
+        """
+        Create a one-way shared memory client.
+
+        Args:
+            buffer_name: Name of the shared memory buffer
+            buffer_size: Size of the buffer (e.g., "256MB")
+            metadata_size: Size of metadata buffer (e.g., "4KB")
+            logger: Optional logger
+
+        Returns:
+            Configured RocketWelderClient instance
+        """
+        connection_str = (
+            f"shm://{buffer_name}?size={buffer_size}&metadata={metadata_size}&mode=OneWay"
+        )
+        return cls(connection_str, logger)
+
+    @classmethod
+    def create_duplex_shm(
+        cls,
+        buffer_name: str,
+        buffer_size: str = "256MB",
+        metadata_size: str = "4KB",
+        logger: logging.Logger | None = None,
+    ) -> RocketWelderClient:
+        """
+        Create a duplex shared memory client.
+
+        Args:
+            buffer_name: Name of the shared memory buffer
+            buffer_size: Size of the buffer (e.g., "256MB")
+            metadata_size: Size of metadata buffer (e.g., "4KB")
+            logger: Optional logger
+
+        Returns:
+            Configured RocketWelderClient instance
+        """
+        connection_str = (
+            f"shm://{buffer_name}?size={buffer_size}&metadata={metadata_size}&mode=Duplex"
+        )
+        return cls(connection_str, logger)