video-stream-data 0.1.6__py3-none-any.whl

video_stream_data/__init__.py

@@ -0,0 +1,177 @@
+"""Provide unified meta data definition for video streaming."""
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+
+
+class StreamControlType(str, Enum):
+    """Different configuration types for the stream.
+
+    Taken from opencv2 device controls.
+    """
+
+    INT = 'int'
+    BOOL = 'bool'
+    MENU = 'menu'
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class Encoding(str, Enum):
+    """Defines how the video stream gets encodied.
+
+    Should default to 'passthrough'.
+    Normally BGR in ROS, RGB in h264.
+    """
+
+    PASSTHROUGH = 'passthrough'
+    BGR = 'bgr'
+    GREY = 'grey'
+    GREY16 = 'grey16'
+    RGB = 'rgb'
+    BGRA = 'bgra'
+    RGBA = 'rgba'
+
+    def __str__(self) -> str:
+        return self.value
+
+    def to_ros_bridge(self) -> str:
+        """Create string to use with the ROS2 CvBridge."""
+        return _ROS_ENCODINGS.get(self, self.value)
+
+
+_ROS_ENCODINGS = {
+    Encoding.BGR: 'bgr8',
+    Encoding.RGB: 'rgb8',
+    Encoding.BGRA: 'bgra8',
+    Encoding.RGBA: 'rgba8',
+    Encoding.GREY: 'mono8',
+    Encoding.GREY16: 'mono16',
+}
+
+
+class Codec(str, Enum):
+    """Codec type/Pixel format as fourcc."""
+
+    # see linuxpy/video/raw.py
+
+    MJPEG = 'MJPEG'  # Motion-JPEG
+    YUYV = 'YUYV'
+    XVID = 'XVID'  # MP4 files
+    H264 = 'H264'
+    GREY = 'GREY'
+    UNKNOWN = 'unknown'
+
+    def __str__(self) -> str:
+        return self.value
+
+    def to_text(self) -> str:
+        """Create human readable text."""
+        return _CODEC_TEXT.get(self, self.value)
+
+    def to_fourcc(self) -> str:
+        """Create FourCC-Text for configuration of OpenCV2 VideoWriter."""
+        if self is Codec.MJPEG:
+            return 'MJPG'
+        return self.value
+
+
+_CODEC_TEXT = {
+    Codec.MJPEG: 'Motion-JPEG',
+    Codec.YUYV: 'YUYV',
+    Codec.XVID: 'XVID/MP4',
+}
+
+
+@dataclass
+class StreamControl:
+    """Provide a value the user can configure."""
+
+    type: StreamControlType  # noqa: A003
+    name: str
+    writable: bool = False
+    min: float = 0  # noqa: A003
+    max: float = 0  # noqa: A003
+    step: int = 1
+    value: int | float | bool | None = None
+    # (key, label) pairs of a MENU control
+    options: list[tuple[str, str]] = field(default_factory=list)
+
+    def __post_init__(self):
+        self.type = StreamControlType(self.type)
+        # JSON and YAML have no tuples
+        self.options = [tuple(option) for option in self.options]
+
+
+@dataclass
+class StreamValue:
+    """Values requested by the user."""
+
+    # selected resolution [width, height]
+    resolution: list[int]
+    # current fps
+    fps: float
+    # selected control configurations
+    controls: dict[str, int | float | bool | None]
+    # selected encoding, e.g. bgr
+    encoding: Encoding = Encoding.PASSTHROUGH
+    # selected codec e.g. MJPEG for "Motion-JPEG" or YUYV for "YUYV 4:2:2"
+    codec: Codec = Codec.UNKNOWN
+
+    def __post_init__(self):
+        self.resolution = list(self.resolution)
+        self.encoding = Encoding(self.encoding)
+        self.codec = Codec(self.codec)
+
+
+@dataclass
+class StreamInfo:
+    """Stream information provided by the device/host."""
+
+    name: str
+    # unique stream path
+    stream_path: str
+    # current configuration as own data structure so it can easily be handed
+    # over as dict from any service
+    values: StreamValue
+    # driver for example "uvcvideo" for a local OpenCV webcam or
+    # "webrtc" for a WebRTC Video Stream
+    driver: str = ''
+    # available codec
+    codec: list[Codec] = field(default_factory=list)
+    # all available controls from linuxpy
+    controls: list[StreamControl] = field(default_factory=list)
+    # all available resolutions [width, height], starting with the default
+    resolutions: list[list[int]] = field(default_factory=list)
+    # max. possible fps (at default resolution)
+    max_fps: float = 30.0
+    backend: str = 'v4l2'  # (optional) OpenCV2 Backend (only if cv2 is used)
+
+    def __post_init__(self):
+        self.codec = [Codec(c) for c in self.codec]
+        if isinstance(self.values, dict):
+            self.values = StreamValue(**self.values)
+        self.controls = [
+            StreamControl(**c) if isinstance(c, dict) else c
+            for c in self.controls
+        ]
+        self.resolutions = [list(r) for r in self.resolutions]
+
+
+def _dict_factory(data):
+    def convert_value(obj):
+        if isinstance(obj, Enum):
+            return obj.value
+        elif isinstance(obj, (list, tuple)):
+            return [convert_value(x) for x in obj]
+        elif isinstance(obj, set):
+            return {convert_value(x) for x in obj}
+        return obj
+    return {k: convert_value(v) for k, v in data}
+
+
+def stream_as_dict(stream_obj):
+    """Serialize stream information as dict."""
+    return asdict(
+        stream_obj,
+        dict_factory=_dict_factory)

video_stream_data/utils.py

@@ -0,0 +1,20 @@
+"""Utility functions like saving and loading YAML files."""
+from pathlib import Path
+
+import yaml
+
+from . import stream_as_dict, StreamInfo
+
+
+def load(filename: Path | str) -> list[StreamInfo]:
+    """Load the yaml file and return it as list of StreamInfo."""
+    with open(filename, 'r', encoding='utf-8') as data:
+        yaml_data = yaml.safe_load(data)
+    return [StreamInfo(**stream) for stream in yaml_data]
+
+
+def save(data: list[StreamInfo], filename: Path | str) -> None:
+    """Save list of StreamInfo to yaml file."""
+    yaml_data = [stream_as_dict(s) for s in data]
+    with open(filename, 'w', encoding='utf-8') as data:
+        data.write(yaml.safe_dump(yaml_data))

video_stream_data-0.1.6.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: video_stream_data
+Version: 0.1.6
+Summary: Unified data format for video streams (devices, server, ...)
+Author-email: Andreas Bresser <Andreas.Bresser@dfki.de>
+License: BSD-3-Clause
+Project-URL: Homepage, https://codeberg.org/brean/video_stream_data
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: yaml
+Requires-Dist: pyyaml; extra == "yaml"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pyyaml; extra == "test"
+Dynamic: license-file
+
+# Video Stream Data
+Dependency-free data structures for video streaming.
+
+## Installation
+Use **pip** to install. Its recommended to install in a virtual environment
+
+```bash
+python3 -m venv video-streaming-pipeline
+# install using system-site-packages (like opencv and pyudev)
+source video-streaming-pipeline/bin/activate --system-site-packages
+pip3 install video_stream_data
+```
+
+Although not recommended a user installation with `--break-system-packages` would also be okay as it does not have any dependencies.
+
+## Usage
+Simply import the data classes you want to have, you can use the parser to load the video stream settings from a file (see `test/`-folder).
+
+You can use the data structure to manually create any kind of video stream.
+
+
+```mermaid
+classDiagram
+    direction LR
+
+    class StreamControlType {
+        <<enumeration>>
+        +INT: str = 'int'
+        +BOOL: str = 'bool'
+        +MENU: str = 'menu'
+    }
+
+    class Encoding {
+        <<enumeration>>
+        +PASSTHROUGH: str = 'passthrough'
+        +BGR: str = 'bgr'
+        +GREY: str = 'grey'
+        +GREY16: str = 'grey16'
+        +GRB: str = 'rbg'
+        +BGRA: str = 'bgra'
+        +RGBA: str = 'rgba'
+
+    }
+
+    class Codec {
+        <<enumeration>>
+        +MJPEG: str = 'MJPEG'  # Motion-JPEG
+        +YUYV: str = 'YUYV'  # e.g. YUYV 4:2:2
+        +XVID: str = 'XVID'  # e.g. mp4 files
+        +H264: str = 'H264'
+        +UNKNOWN: str = 'unknown'
+    }
+
+    class StreamControl {
+        +type: StreamControlType
+        +name: str
+        +writable: bool = False
+        +min: float = 0
+        +max: float = 0
+        +step: int = 1
+        +value: float | bool | None = None
+        +options: list = []
+    }
+
+    class StreamValue {
+        # desired video resolution
+        +resolution: list[int]
+        +fps: float  # desired FPS by user
+        # desired configuration
+        +controls: dict[str, int | float | bool | None]
+        +encoding: Encoding = Encoding.PASSTHROUGH
+        +codec: Codec = Codec.UNKNOWN
+    }
+
+    class StreamInfo {
+        +name: str
+        +stream_path: str
+        +driver: str
+        +codec: list[str]
+        +controls: list[StreamControl]
+        +resolutions: list[int, int]
+        +max_fps: float
+        +values: StreamValue
+        +backend: str = 'v4l2'
+    }
+
+    StreamControlType <|-- StreamControl
+    Encoding <|-- StreamValue
+    Codec <|-- StreamValue
+    StreamControl --> StreamInfo : controls
+    StreamValue --> StreamInfo : values
+
+```
+*Fig. 1: Data Model for the StreamInfo generated from any device*

video_stream_data-0.1.6.dist-info/RECORD

@@ -0,0 +1,7 @@
+video_stream_data/__init__.py,sha256=RtVgtl5dbF-aLrOFPHOgLGZcYbVZez02R-gYjBUoWWU,4795
+video_stream_data/utils.py,sha256=4jC2OxKuFFN6mbEHIUv70xBXPdS-DmLW_66KlB_e5Tk,681
+video_stream_data-0.1.6.dist-info/licenses/LICENSE,sha256=9eS7gmlDqQI_plfhhfriVsVbRBzCzIjH1QH0qSyNB40,1502
+video_stream_data-0.1.6.dist-info/METADATA,sha256=14AybSQ-7V9JtYicEeTd65_DTe9L-rDzstXrRqA5f2o,3097
+video_stream_data-0.1.6.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+video_stream_data-0.1.6.dist-info/top_level.txt,sha256=iH0zMRQNzh7YijSv9kSwoX3kXQzj90T99BYZYnDywu4,18
+video_stream_data-0.1.6.dist-info/RECORD,,

video_stream_data-0.1.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

video_stream_data-0.1.6.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Andreas Bresser
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

video_stream_data-0.1.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+video_stream_data