haybale-stream 0.0.1__tar.gz

haybale_stream-0.0.1/.gitignore

@@ -0,0 +1,28 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.coverage
+htmlcov/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/

haybale_stream-0.0.1/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: haybale-stream
+Version: 0.0.1
+Summary: Share video frames between applications over Syphon, Spout, NDI and OMT
+Project-URL: Homepage, https://github.com/going-haywire/haybale-stream
+Project-URL: Documentation, https://github.com/going-haywire/haybale-stream#readme
+Project-URL: Issues, https://github.com/going-haywire/haybale-stream/issues
+Project-URL: Source, https://github.com/going-haywire/haybale-stream
+Author: maybites
+License: MIT
+Keywords: ndi,omt,spout,streaming,syphon,texture sharing,video
+Requires-Python: >=3.12
+Requires-Dist: cyndilib>=0.1.3
+Requires-Dist: cyomtlib>=0.1.2
+Requires-Dist: haybale-image>=0.3.4
+Requires-Dist: haywire-core>=0.3.0
+Requires-Dist: numpy
+Requires-Dist: spoutgl>=0.1.1; sys_platform == 'win32'
+Requires-Dist: syphon-python>=0.2.0; sys_platform == 'darwin'
+Description-Content-Type: text/markdown
+
+# Haybale Stream
+
+A haywire library that sends and receives video frames between applications over
+[Syphon](https://syphon.github.io/) (macOS), [Spout](https://spout.zeal.co/) (Windows),
+[NDI](https://ndi.video) and [OMT](https://www.openmediatransport.org) (Open Media Transport,
+cross-platform).
+
+Ideas and backend code come from [TextureSharing](https://github.com/maybites/TextureSharing)
+(Spout for Blender).
+
+| Backend | Linux | macOS | Windows |
+|---------|:-----:|:-----:|:-------:|
+| NDI     | yes   | yes   | yes     |
+| OMT     | yes   | yes   | yes     |
+| Syphon  |       | yes   |         |
+| Spout   |       |       | yes     |
+
+Frames travel as `IMAGE` values from `haybale-image`. See [docs/design.md](https://github.com/going-haywire/haybale-stream/blob/main/docs/design.md).
+
+## Nodes
+
+| Node | What it does |
+|------|--------------|
+| Send Frame | Publishes an `IMAGE` under a name on NDI, OMT, Syphon or Spout. |
+| Receive Frame | Fetches the newest frame from a named source as `IMAGE_RGBA`; exits through `Frame` or `No frame`. |
+| Receive Frame Emit | Receives on its own thread and emits a callback per frame to connected Image Event nodes (from haybale-image) (like the visiongraph camera nodes). |
+
+Status: NDI and OMT are tested on Linux. Syphon and Spout are implemented but not yet run
+on macOS / Windows.
+
+## Subscribe
+
+<!-- marketstall:share-url:start -->
+<!-- marketstall:share-url:end -->
+
+## Getting started
+
+```sh
+uv sync
+uv run haywire
+uv run pytest
+```
+
+Develop from `../haywire-repo` (this package is symlinked into its `barn/`); see [CLAUDE.md](CLAUDE.md).
+
+## Share the library
+
+Run from this repo's root (not from `../haywire-repo`):
+
+```shell
+uv run --frozen haywire share --dry-run                  # first: report only, writes nothing
+uv run --frozen haywire share --bump patch|minor|major   # or an explicit X.Y.Z
+```
+
+This bumps every `barn/*` library in lockstep, regenerates docs and `marketstall.toml`,
+then commits, tags `v<version>` and pushes to `origin` itself. It needs a clean working tree
+and the default branch checked out (`--frozen` keeps `uv.lock` from being re-locked; `git checkout uv.lock` first if it is dirty). The project uses `distribute = "pypi"`, so uploading the
+package to PyPI is a separate step (see `publish-to-pypi.md` in the haywire docs).
+
+## Credits
+
+Syphon: Tom Butterworth and Anton Marini. Spout: Lynn Jarvis. SpoutGL: Jason Lai.
+syphon-python: Florian Bruggisser. cyndilib: Matthew Reid. OMT: the Open Media Transport project
+(cyomtlib wrapper). NDI® is a registered trademark of Vizrt NDI AB; NDI runtime © Vizrt NDI AB, bundled in the cyndilib wheel under the NDI SDK license (http://ndi.link/ndisdk_license).
+
+Martin Froehlich. Implementation for [haywire](https://github.com/going-haywire/haywire)

haybale_stream-0.0.1/README.md

@@ -0,0 +1,66 @@
+# Haybale Stream
+
+A haywire library that sends and receives video frames between applications over
+[Syphon](https://syphon.github.io/) (macOS), [Spout](https://spout.zeal.co/) (Windows),
+[NDI](https://ndi.video) and [OMT](https://www.openmediatransport.org) (Open Media Transport,
+cross-platform).
+
+Ideas and backend code come from [TextureSharing](https://github.com/maybites/TextureSharing)
+(Spout for Blender).
+
+| Backend | Linux | macOS | Windows |
+|---------|:-----:|:-----:|:-------:|
+| NDI     | yes   | yes   | yes     |
+| OMT     | yes   | yes   | yes     |
+| Syphon  |       | yes   |         |
+| Spout   |       |       | yes     |
+
+Frames travel as `IMAGE` values from `haybale-image`. See [docs/design.md](https://github.com/going-haywire/haybale-stream/blob/main/docs/design.md).
+
+## Nodes
+
+| Node | What it does |
+|------|--------------|
+| Send Frame | Publishes an `IMAGE` under a name on NDI, OMT, Syphon or Spout. |
+| Receive Frame | Fetches the newest frame from a named source as `IMAGE_RGBA`; exits through `Frame` or `No frame`. |
+| Receive Frame Emit | Receives on its own thread and emits a callback per frame to connected Image Event nodes (from haybale-image) (like the visiongraph camera nodes). |
+
+Status: NDI and OMT are tested on Linux. Syphon and Spout are implemented but not yet run
+on macOS / Windows.
+
+## Subscribe
+
+<!-- marketstall:share-url:start -->
+<!-- marketstall:share-url:end -->
+
+## Getting started
+
+```sh
+uv sync
+uv run haywire
+uv run pytest
+```
+
+Develop from `../haywire-repo` (this package is symlinked into its `barn/`); see [CLAUDE.md](CLAUDE.md).
+
+## Share the library
+
+Run from this repo's root (not from `../haywire-repo`):
+
+```shell
+uv run --frozen haywire share --dry-run                  # first: report only, writes nothing
+uv run --frozen haywire share --bump patch|minor|major   # or an explicit X.Y.Z
+```
+
+This bumps every `barn/*` library in lockstep, regenerates docs and `marketstall.toml`,
+then commits, tags `v<version>` and pushes to `origin` itself. It needs a clean working tree
+and the default branch checked out (`--frozen` keeps `uv.lock` from being re-locked; `git checkout uv.lock` first if it is dirty). The project uses `distribute = "pypi"`, so uploading the
+package to PyPI is a separate step (see `publish-to-pypi.md` in the haywire docs).
+
+## Credits
+
+Syphon: Tom Butterworth and Anton Marini. Spout: Lynn Jarvis. SpoutGL: Jason Lai.
+syphon-python: Florian Bruggisser. cyndilib: Matthew Reid. OMT: the Open Media Transport project
+(cyomtlib wrapper). NDI® is a registered trademark of Vizrt NDI AB; NDI runtime © Vizrt NDI AB, bundled in the cyndilib wheel under the NDI SDK license (http://ndi.link/ndisdk_license).
+
+Martin Froehlich. Implementation for [haywire](https://github.com/going-haywire/haywire)

haybale_stream-0.0.1/haybale_stream/__init__.py

@@ -0,0 +1,23 @@
+"""Haybale Stream: send and receive video frames over NDI, OMT, Syphon and Spout."""
+
+from pathlib import Path
+
+from haywire.core.library.base import BaseLibrary
+from haywire.core.library.decorator import library
+from haywire.core.node.registry import NodeRegistry
+
+
+@library(file_watcher=False)
+class Library(BaseLibrary):
+    """Stream library: frame-sharing nodes over the backends in ``haybale_stream.backends``."""
+
+    def register_components(self):
+        """Register the node folder."""
+        base_path = Path(__file__).parent
+        self.add_folder_to_registry(folder_path=str(base_path / "nodes"), registry_cls=NodeRegistry)
+
+    def validate(self) -> bool:
+        return True
+
+
+__all__ = ["Library"]

haybale_stream-0.0.1/haybale_stream/backends/__init__.py

@@ -0,0 +1,41 @@
+"""Frame-sharing backends behind one sender/receiver contract. See ``base``."""
+
+from __future__ import annotations
+
+from .base import Backend, BackendUnavailable, ClockedSender, Frame, Receiver, Sender
+from .ndi import NDIBackend
+from .omt import OMTBackend
+from .spout import SpoutBackend
+from .syphon import SyphonBackend
+
+#: Every backend by key, in menu order. Importing this is safe on any platform: native
+#: dependencies are imported only when a sender, receiver or discovery is actually used.
+BACKENDS: dict[str, type[Backend]] = {
+    b.key: b for b in (NDIBackend, OMTBackend, SyphonBackend, SpoutBackend)
+}
+
+
+def get_backend(key: str) -> type[Backend]:
+    """Return the backend registered as ``key`` (case-insensitive)."""
+    try:
+        return BACKENDS[key.lower()]
+    except KeyError:
+        raise KeyError(f"unknown backend {key!r}; known: {', '.join(BACKENDS)}") from None
+
+
+def available_backends() -> list[type[Backend]]:
+    """The backends that can run on this machine right now."""
+    return [b for b in BACKENDS.values() if b.is_available()]
+
+
+__all__ = [
+    "BACKENDS",
+    "Backend",
+    "BackendUnavailable",
+    "ClockedSender",
+    "Frame",
+    "Receiver",
+    "Sender",
+    "available_backends",
+    "get_backend",
+]

haybale_stream-0.0.1/haybale_stream/backends/base.py

@@ -0,0 +1,215 @@
+"""The backend-neutral sender/receiver contract.
+
+A backend moves **packed 8-bit 4-channel frames** (``H×W×4`` uint8) between processes.
+It knows nothing about haywire or ``ImageValue``: ``convert.py`` bridges the two, so a
+backend module imports only its own native dependency, and only when it is used.
+
+Channel order is a property of the backend (``Backend.channel_order``): NDI and Spout
+take RGBA, OMT and Syphon's raw readback are BGRA. The bridge converts once, on the
+way in or out, so a backend never swaps channels itself.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import ClassVar, Self
+
+import numpy as np
+
+log = logging.getLogger(__name__)
+
+
+class BackendUnavailable(RuntimeError):
+    """The backend cannot run here: wrong platform, or its native dependency is missing."""
+
+
+@dataclass(frozen=True)
+class Frame:
+    """One received frame: ``pixels`` is ``H×W×4`` uint8 in the backend's channel order."""
+
+    pixels: np.ndarray
+    timestamp: float | None = None
+
+    @property
+    def width(self) -> int:
+        return int(self.pixels.shape[1])
+
+    @property
+    def height(self) -> int:
+        return int(self.pixels.shape[0])
+
+
+class Sender(ABC):
+    """Publishes frames under a name that receivers discover."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    @abstractmethod
+    def open(self) -> None:
+        """Start publishing. Raises ``BackendUnavailable`` if the backend cannot run."""
+
+    @abstractmethod
+    def send(self, pixels: np.ndarray, frame_rate: float = 30.0) -> None:
+        """Publish one ``H×W×4`` uint8 frame. May return before the frame is on the wire."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Stop publishing and release native resources. Safe to call twice."""
+
+    def __enter__(self) -> Self:
+        self.open()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class ClockedSender(Sender):
+    """A sender whose native send call blocks for one frame period (NDI, OMT).
+
+    The caller's thread must not block on the network clock, so ``send`` only stores the
+    newest frame; a worker thread writes it. Frames sent faster than the clock are
+    dropped (latest wins). With ``steady_stream`` the last frame is resent while the
+    caller is idle, which keeps receivers from showing "no signal" on a still image.
+    """
+
+    def __init__(self, name: str, steady_stream: bool = False) -> None:
+        super().__init__(name)
+        self.steady_stream = steady_stream
+        self._latest: tuple[np.ndarray, float] | None = None
+        self._lock = threading.Lock()
+        self._new = threading.Event()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self.frames_written = 0
+
+    @abstractmethod
+    def _open_native(self) -> None: ...
+
+    @abstractmethod
+    def _write(self, pixels: np.ndarray, frame_rate: float) -> None:
+        """Blocking native write; runs on the worker thread only."""
+
+    @abstractmethod
+    def _close_native(self) -> None: ...
+
+    def open(self) -> None:
+        self._open_native()
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._run, name=f"{type(self).__name__}-{self.name}", daemon=True
+        )
+        self._thread.start()
+
+    def send(self, pixels: np.ndarray, frame_rate: float = 30.0) -> None:
+        # Own the bytes: the caller's array may be a read-only view of an image other nodes
+        # still read, and native writers want a writable buffer. np.array always copies.
+        frame = np.array(pixels, dtype=np.uint8, order="C")
+        with self._lock:
+            self._latest = (frame, frame_rate)
+        self._new.set()
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            if (not self.steady_stream or self._latest is None) and not self._new.wait(0.1):
+                continue
+            self._new.clear()
+            with self._lock:
+                latest = self._latest
+            if latest is None or self._stop.is_set():
+                continue
+            try:
+                self._write(*latest)
+                self.frames_written += 1
+            except Exception:
+                log.exception("%s send failed", type(self).__name__)
+                self._stop.wait(0.1)
+
+    def close(self) -> None:
+        self._stop.set()
+        self._new.set()
+        thread, self._thread = self._thread, None
+        if thread is not None:
+            thread.join(timeout=5.0)
+        self._close_native()
+
+
+class Receiver(ABC):
+    """Receives frames from one named source."""
+
+    def __init__(self, source: str) -> None:
+        self.source = source
+
+    @abstractmethod
+    def open(self, timeout: float = 5.0) -> None:
+        """Connect, waiting up to ``timeout`` s for the source to appear.
+
+        Raises ``BackendUnavailable`` or ``LookupError`` (source not found).
+        """
+
+    @abstractmethod
+    def poll(self, timeout: float = 0.0) -> Frame | None:
+        """Return the newest frame not yet returned, or ``None`` if there is none (waits up to ``timeout`` s)."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Disconnect and release native resources. Safe to call twice."""
+
+    def __enter__(self) -> Self:
+        self.open()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class Backend(ABC):
+    """One transport: knows whether it can run here, lists sources, builds senders and receivers."""
+
+    key: ClassVar[str]
+    label: ClassVar[str]
+    #: ``sys.platform`` prefixes the backend runs on.
+    platforms: ClassVar[tuple[str, ...]] = ("linux", "darwin", "win32")
+    #: Channel order of the frames this backend sends and receives: ``"rgba"`` or ``"bgra"``.
+    channel_order: ClassVar[str] = "rgba"
+    #: Whether a sender can be told to resend its last frame (see ``ClockedSender``).
+    supports_steady_stream: ClassVar[bool] = False
+
+    @classmethod
+    def supported_here(cls) -> bool:
+        import sys
+
+        return sys.platform.startswith(cls.platforms)
+
+    @classmethod
+    def unavailable_reason(cls) -> str | None:
+        """Why this backend cannot run here, or ``None`` when it can."""
+        if not cls.supported_here():
+            return f"{cls.label} is not available on this platform (needs {'/'.join(cls.platforms)})"
+        return cls._check_dependency()
+
+    @classmethod
+    def is_available(cls) -> bool:
+        return cls.unavailable_reason() is None
+
+    @classmethod
+    @abstractmethod
+    def _check_dependency(cls) -> str | None:
+        """Import the native dependency; return a message if it is missing, else ``None``."""
+
+    @classmethod
+    @abstractmethod
+    def discover(cls, wait: float = 0.0) -> list[str]:
+        """Names of the sources currently visible. ``wait`` seconds to let discovery settle."""
+
+    @classmethod
+    @abstractmethod
+    def create_sender(cls, name: str, *, steady_stream: bool = False) -> Sender: ...
+
+    @classmethod
+    @abstractmethod
+    def create_receiver(cls, source: str) -> Receiver: ...

haybale_stream-0.0.1/haybale_stream/backends/convert.py

@@ -0,0 +1,31 @@
+"""Bridge between ``ImageValue`` and the packed 4-channel frames backends move."""
+
+from __future__ import annotations
+
+import numpy as np
+from haybale_image.value import ChannelOrder, ImageValue, Layout, convert_layout
+
+from .base import Backend, Frame
+
+
+def image_to_pixels(image: ImageValue, order: str) -> np.ndarray:
+    """Return ``image`` as a C-contiguous ``H×W×4`` uint8 array in ``order`` (``"rgba"`` / ``"bgra"``).
+
+    Gray and RGB images get an opaque alpha. The array may be shared with ``image``'s
+    cache and is read-only: copy before writing.
+    """
+    rgba = convert_layout(image, Layout.RGBA)
+    channel = ChannelOrder.BGR if order == "bgra" else ChannelOrder.RGB
+    return np.ascontiguousarray(rgba.array(np.uint8, channel))
+
+
+def pixels_to_image(pixels: np.ndarray, order: str) -> ImageValue:
+    """Wrap an ``H×W×4`` uint8 frame in ``order`` as an RGBA ``ImageValue`` (no copy)."""
+    if pixels.ndim != 3 or pixels.shape[2] != 4 or pixels.dtype != np.uint8:
+        raise ValueError(f"expected an H×W×4 uint8 frame, got {pixels.dtype} {pixels.shape}")
+    channel = ChannelOrder.BGR if order == "bgra" else ChannelOrder.RGB
+    return ImageValue.from_array(pixels, order=channel)
+
+
+def frame_to_image(frame: Frame, backend: type[Backend]) -> ImageValue:
+    return pixels_to_image(frame.pixels, backend.channel_order)

haybale_stream-0.0.1/haybale_stream/backends/ndi.py

@@ -0,0 +1,160 @@
+"""NDI backend, on cyndilib (wheels bundle the NDI runtime on Linux, macOS and Windows)."""
+
+from __future__ import annotations
+
+import time
+from fractions import Fraction
+
+import numpy as np
+
+from .base import Backend, BackendUnavailable, ClockedSender, Frame, Receiver, Sender
+
+
+class NDISender(ClockedSender):
+    def __init__(self, name: str, steady_stream: bool = False) -> None:
+        super().__init__(name, steady_stream)
+        self._sender = None
+        self._size: tuple[int, int] | None = None
+        self._rate: Fraction | None = None
+
+    def _open_native(self) -> None:
+        from cyndilib.sender import Sender as NativeSender
+
+        self._sender = NativeSender(self.name)
+
+    def _configure(self, width: int, height: int, frame_rate: float) -> None:
+        """(Re)build the video frame; NDI can only swap it while the sender is closed."""
+        from cyndilib.video_frame import VideoSendFrame
+        from cyndilib.wrapper.ndi_structs import FourCC
+
+        sender = self._sender
+        if self._size is not None:
+            sender.close()
+        frame = VideoSendFrame()
+        frame.set_fourcc(FourCC.RGBA)
+        frame.set_resolution(width, height)
+        rate = Fraction(frame_rate).limit_denominator(1001)
+        frame.set_frame_rate(rate)
+        sender.set_video_frame(frame)
+        sender.open()
+        self._size, self._rate = (width, height), rate
+
+    def _write(self, pixels: np.ndarray, frame_rate: float) -> None:
+        height, width = pixels.shape[:2]
+        rate = Fraction(frame_rate).limit_denominator(1001)
+        if self._size != (width, height) or self._rate != rate:
+            self._configure(width, height, frame_rate)
+        self._sender.write_video(pixels.reshape(-1))
+
+    def _close_native(self) -> None:
+        sender, self._sender = self._sender, None
+        if sender is not None and self._size is not None:
+            sender.close()
+        self._size = None
+
+
+class NDIReceiver(Receiver):
+    def __init__(self, source: str) -> None:
+        super().__init__(source)
+        self._finder = None
+        self._receiver = None
+        self._video = None
+        self._last_ts: float | None = None
+
+    def open(self, timeout: float = 5.0) -> None:
+        from cyndilib.finder import Finder
+        from cyndilib.receiver import Receiver as NativeReceiver
+        from cyndilib.video_frame import VideoFrameSync
+        from cyndilib.wrapper.ndi_recv import RecvBandwidth, RecvColorFormat
+
+        finder = Finder()
+        finder.open()
+        try:
+            deadline = time.monotonic() + timeout
+            found = None
+            while found is None:
+                finder.wait_for_sources(0.5)
+                found = next((s for s in finder if s.name == self.source), None)
+                if time.monotonic() >= deadline:
+                    break
+            if found is None:
+                raise LookupError(f"NDI source {self.source!r} not found")
+            receiver = NativeReceiver(
+                color_format=RecvColorFormat.RGBX_RGBA, bandwidth=RecvBandwidth.highest
+            )
+            video = VideoFrameSync()
+            receiver.frame_sync.set_video_frame(video)
+            receiver.set_source(found)
+        except BaseException:
+            finder.close()
+            raise
+        self._finder, self._receiver, self._video = finder, receiver, video
+
+    def poll(self, timeout: float = 0.0) -> Frame | None:
+        if self._receiver is None:
+            return None
+        deadline = time.monotonic() + timeout
+        while True:
+            # frame_sync repeats the last frame; the timestamp tells a new one from a repeat.
+            self._receiver.frame_sync.capture_video()
+            video = self._video
+            if video.get_data_size() > 0:
+                ts = video.get_timestamp_posix()
+                if ts != self._last_ts:
+                    self._last_ts = ts
+                    width, height = video.get_resolution()
+                    pixels = np.array(video.get_array(), dtype=np.uint8).reshape(height, width, 4)
+                    return Frame(pixels, ts)
+            if time.monotonic() >= deadline:
+                return None
+            time.sleep(0.005)
+
+    def close(self) -> None:
+        receiver, self._receiver = self._receiver, None
+        finder, self._finder = self._finder, None
+        if receiver is not None:
+            receiver.disconnect()
+        if finder is not None:
+            finder.close()
+
+
+class NDIBackend(Backend):
+    key = "ndi"
+    label = "NDI"
+    channel_order = "rgba"
+    supports_steady_stream = True
+
+    @classmethod
+    def _check_dependency(cls) -> str | None:
+        try:
+            import cyndilib  # noqa: F401
+        except ImportError as exc:
+            return f"NDI needs the 'cyndilib' package ({exc})"
+        return None
+
+    @classmethod
+    def discover(cls, wait: float = 0.0) -> list[str]:
+        if (reason := cls.unavailable_reason()) is not None:
+            raise BackendUnavailable(reason)
+        from cyndilib.finder import Finder
+
+        finder = Finder()
+        finder.open()
+        try:
+            if wait > 0:
+                finder.wait_for_sources(wait)
+            return sorted(s.name for s in finder)
+        finally:
+            finder.close()
+
+    @classmethod
+    def create_sender(cls, name: str, *, steady_stream: bool = False) -> Sender:
+        if (reason := cls.unavailable_reason()) is not None:
+            raise BackendUnavailable(reason)
+        return NDISender(name, steady_stream)
+
+    @classmethod
+    def create_receiver(cls, source: str) -> Receiver:
+        if (reason := cls.unavailable_reason()) is not None:
+            raise BackendUnavailable(reason)
+        return NDIReceiver(source)