videohubwire 0.1.0.dev0__tar.gz

videohubwire-0.1.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Romanenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

videohubwire-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: videohubwire
+Version: 0.1.0.dev0
+Summary: Blackmagic Videohub Ethernet Protocol client (TCP 9990): state snapshot, routing, label editing
+Author: Lucas Romanenko
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# videohubwire
+
+videohubwire is a small, dependency-free Python client for Blackmagic
+**Videohub** routers speaking the Videohub Ethernet Protocol on TCP 9990. It
+connects, parses the router's state dump into a snapshot (device info, input
+and output labels, output locks, routing), routes a source to a destination
+with ACK/NAK handling, renames ports, and keeps the snapshot current by
+applying the update blocks the router pushes when any client changes
+something. It is synchronous and single-socket by design: open, read, act,
+close, in milliseconds on a LAN, which suits per-request use from a web
+backend or a script.
+
+## Features
+
+- `Videohub` context manager: `connect()` parses the preamble, `close()` shuts the socket, `state()` returns a UI-ready dict.
+- `route(dest, src)` sends one `VIDEO OUTPUT ROUTING` change, waits for `ACK`/`NAK`, and applies any pushed blocks that arrive in between.
+- `set_input_label()` / `set_output_label()` with newline collapsing and a 64-character cap before anything hits the wire.
+- `ping()` liveness check.
+- Output lock states (`U` / `O` / `L`) surfaced per destination; the client never takes locks.
+- Bounds checks against the router's own port counts; a `NAK` or timeout raises `VideohubError`.
+- Works with and without the `END PRELUDE:` marker, so old and new firmware both connect.
+- One connect retry for cold-ARP first-packet loss; malformed lines are logged and skipped, not fatal.
+- Pure standard library; a `socket_factory` hook lets the whole suite run without hardware.
+
+## Install
+
+```sh
+pip install "git+https://github.com/lucas-romanenko/videohubwire.git@v0.1.0.dev0"
+```
+
+Python 3.10 or newer. To run the tests from a checkout:
+
+```sh
+pip install ".[test]"
+python -m pytest
+```
+
+## Usage
+
+```python
+from videohubwire import Videohub, VideohubError
+
+with Videohub('192.0.2.31') as vh:
+    snap = vh.state()
+    print(snap['device']['model_name'], snap['device']['video_inputs'], 'x',
+          snap['device']['video_outputs'])
+    for out in snap['outputs']:
+        print(out['index'], out['label'], '<-', out['source'], out['lock'])
+
+    try:
+        vh.route(dest=3, src=12)          # 0-based, like the wire
+    except VideohubError as e:
+        print('refused:', e)               # locked destination, NAK, or timeout
+
+    vh.set_output_label(3, 'Wall Monitor 1')
+```
+
+## Protocol notes
+
+Blackmagic documents the block format, the block names and the `ACK` / `NAK`
+replies in the Videohub Ethernet Protocol document that ships with the
+Videohub SDK; this section covers only what that document does not settle
+or what this client does on top of it.
+
+- **Preamble end detection.** Newer firmware ends the initial state dump with an `END PRELUDE:` block; older firmware simply stops sending. The client accepts either: it returns as soon as the marker arrives, or once a `VIDEOHUB DEVICE:` block and a `VIDEO OUTPUT ROUTING:` block have both been seen and the wire has been quiet for 0.3 s. A router that sends neither the marker nor a routing block is reported as "no state preamble"; that is a known limitation for an unusual device rather than a supported case.
+- **Pushed updates interleave with replies.** After the preamble the router pushes the same block shapes whenever state changes from any client. Those pushes can land between a command and its `ACK`/`NAK`, so `route()`, the label setters and `ping()` apply any non-reply block they read and keep waiting for the reply. `state()` drains pending pushes with a short non-blocking read before building the snapshot.
+- **Optimistic routing apply.** On `ACK` the client records the new route immediately instead of waiting for the router's own `VIDEO OUTPUT ROUTING:` broadcast, so a `state()` call right after `route()` is already correct.
+- **Lock letters.** `VIDEO OUTPUT LOCKS` reports `U` (unlocked), `O` (locked by this connection) and `L` (locked by another client). This client never sends a lock command; it reports the letters so a caller can render locked destinations read-only. Routing a destination locked elsewhere returns `NAK`, which is raised as `VideohubError`.
+- **Labels with spaces and empty labels.** Indexed body lines are `<index> <value>`; only the first token is the index and the rest, spaces included, is the value. A line such as `3 ` (index and nothing else) is a cleared label; `state()` substitutes `Input N` / `Output N` (1-based) for display.
+- **Label limits.** The router rejects labels containing newlines because they break the block framing, and caps labels at roughly 64 characters. The client collapses all whitespace runs to single spaces and refuses labels longer than 64 characters before sending.
+- **Port counts.** `video_inputs` / `video_outputs` come from the `VIDEOHUB DEVICE:` block. If those keys are absent the snapshot sizes itself from the highest label index seen. A non-numeric count in that block raises `ValueError` rather than `VideohubError`.
+- **Ignored blocks.** `CONFIGURATION:`, `SERIAL PORT ...`, `MONITORING OUTPUT ...`, `VIDEO INPUT STATUS`, and any other block the client does not model are parsed past and dropped. Only `PROTOCOL PREAMBLE`, `VIDEOHUB DEVICE`, `INPUT LABELS`, `OUTPUT LABELS`, `VIDEO OUTPUT ROUTING` and `VIDEO OUTPUT LOCKS` update state.
+- **Connect retry.** The first TCP connect to a router the host has not spoken to recently is sometimes lost to ARP resolution. `connect()` retries once after 0.3 s on any `OSError`; a second failure propagates unchanged.
+- **Timeouts.** Connect and read timeouts default to 3 s. A read timeout while waiting for a reply raises `VideohubError`; the router closing the connection raises it too, rather than looping.
+- **What the test fixture reflects.** The canned preamble in the tests has the shape of a Smart Videohub 40 x 40 reporting protocol version 2.7 (device block, labels, locks, routing, optional marker). Other models were not exercised.
+
+## License
+
+MIT. See `LICENSE`.

videohubwire-0.1.0.dev0/README.md

@@ -0,0 +1,79 @@
+# videohubwire
+
+videohubwire is a small, dependency-free Python client for Blackmagic
+**Videohub** routers speaking the Videohub Ethernet Protocol on TCP 9990. It
+connects, parses the router's state dump into a snapshot (device info, input
+and output labels, output locks, routing), routes a source to a destination
+with ACK/NAK handling, renames ports, and keeps the snapshot current by
+applying the update blocks the router pushes when any client changes
+something. It is synchronous and single-socket by design: open, read, act,
+close, in milliseconds on a LAN, which suits per-request use from a web
+backend or a script.
+
+## Features
+
+- `Videohub` context manager: `connect()` parses the preamble, `close()` shuts the socket, `state()` returns a UI-ready dict.
+- `route(dest, src)` sends one `VIDEO OUTPUT ROUTING` change, waits for `ACK`/`NAK`, and applies any pushed blocks that arrive in between.
+- `set_input_label()` / `set_output_label()` with newline collapsing and a 64-character cap before anything hits the wire.
+- `ping()` liveness check.
+- Output lock states (`U` / `O` / `L`) surfaced per destination; the client never takes locks.
+- Bounds checks against the router's own port counts; a `NAK` or timeout raises `VideohubError`.
+- Works with and without the `END PRELUDE:` marker, so old and new firmware both connect.
+- One connect retry for cold-ARP first-packet loss; malformed lines are logged and skipped, not fatal.
+- Pure standard library; a `socket_factory` hook lets the whole suite run without hardware.
+
+## Install
+
+```sh
+pip install "git+https://github.com/lucas-romanenko/videohubwire.git@v0.1.0.dev0"
+```
+
+Python 3.10 or newer. To run the tests from a checkout:
+
+```sh
+pip install ".[test]"
+python -m pytest
+```
+
+## Usage
+
+```python
+from videohubwire import Videohub, VideohubError
+
+with Videohub('192.0.2.31') as vh:
+    snap = vh.state()
+    print(snap['device']['model_name'], snap['device']['video_inputs'], 'x',
+          snap['device']['video_outputs'])
+    for out in snap['outputs']:
+        print(out['index'], out['label'], '<-', out['source'], out['lock'])
+
+    try:
+        vh.route(dest=3, src=12)          # 0-based, like the wire
+    except VideohubError as e:
+        print('refused:', e)               # locked destination, NAK, or timeout
+
+    vh.set_output_label(3, 'Wall Monitor 1')
+```
+
+## Protocol notes
+
+Blackmagic documents the block format, the block names and the `ACK` / `NAK`
+replies in the Videohub Ethernet Protocol document that ships with the
+Videohub SDK; this section covers only what that document does not settle
+or what this client does on top of it.
+
+- **Preamble end detection.** Newer firmware ends the initial state dump with an `END PRELUDE:` block; older firmware simply stops sending. The client accepts either: it returns as soon as the marker arrives, or once a `VIDEOHUB DEVICE:` block and a `VIDEO OUTPUT ROUTING:` block have both been seen and the wire has been quiet for 0.3 s. A router that sends neither the marker nor a routing block is reported as "no state preamble"; that is a known limitation for an unusual device rather than a supported case.
+- **Pushed updates interleave with replies.** After the preamble the router pushes the same block shapes whenever state changes from any client. Those pushes can land between a command and its `ACK`/`NAK`, so `route()`, the label setters and `ping()` apply any non-reply block they read and keep waiting for the reply. `state()` drains pending pushes with a short non-blocking read before building the snapshot.
+- **Optimistic routing apply.** On `ACK` the client records the new route immediately instead of waiting for the router's own `VIDEO OUTPUT ROUTING:` broadcast, so a `state()` call right after `route()` is already correct.
+- **Lock letters.** `VIDEO OUTPUT LOCKS` reports `U` (unlocked), `O` (locked by this connection) and `L` (locked by another client). This client never sends a lock command; it reports the letters so a caller can render locked destinations read-only. Routing a destination locked elsewhere returns `NAK`, which is raised as `VideohubError`.
+- **Labels with spaces and empty labels.** Indexed body lines are `<index> <value>`; only the first token is the index and the rest, spaces included, is the value. A line such as `3 ` (index and nothing else) is a cleared label; `state()` substitutes `Input N` / `Output N` (1-based) for display.
+- **Label limits.** The router rejects labels containing newlines because they break the block framing, and caps labels at roughly 64 characters. The client collapses all whitespace runs to single spaces and refuses labels longer than 64 characters before sending.
+- **Port counts.** `video_inputs` / `video_outputs` come from the `VIDEOHUB DEVICE:` block. If those keys are absent the snapshot sizes itself from the highest label index seen. A non-numeric count in that block raises `ValueError` rather than `VideohubError`.
+- **Ignored blocks.** `CONFIGURATION:`, `SERIAL PORT ...`, `MONITORING OUTPUT ...`, `VIDEO INPUT STATUS`, and any other block the client does not model are parsed past and dropped. Only `PROTOCOL PREAMBLE`, `VIDEOHUB DEVICE`, `INPUT LABELS`, `OUTPUT LABELS`, `VIDEO OUTPUT ROUTING` and `VIDEO OUTPUT LOCKS` update state.
+- **Connect retry.** The first TCP connect to a router the host has not spoken to recently is sometimes lost to ARP resolution. `connect()` retries once after 0.3 s on any `OSError`; a second failure propagates unchanged.
+- **Timeouts.** Connect and read timeouts default to 3 s. A read timeout while waiting for a reply raises `VideohubError`; the router closing the connection raises it too, rather than looping.
+- **What the test fixture reflects.** The canned preamble in the tests has the shape of a Smart Videohub 40 x 40 reporting protocol version 2.7 (device block, labels, locks, routing, optional marker). Other models were not exercised.
+
+## License
+
+MIT. See `LICENSE`.

videohubwire-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "videohubwire"
+version = "0.1.0.dev0"
+description = "Blackmagic Videohub Ethernet Protocol client (TCP 9990): state snapshot, routing, label editing"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Lucas Romanenko" }]
+dependencies = []
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools.packages.find]
+include = ["videohubwire", "videohubwire.*"]
+exclude = ["videohubwire.tests"]

videohubwire-0.1.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

videohubwire-0.1.0.dev0/videohubwire/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+"""videohubwire — Blackmagic Videohub Ethernet Protocol client.
+
+Synchronous, stdlib-only. See ``client.py`` for the protocol
+notes. Public surface::
+
+    from videohubwire import Videohub, VideohubError
+
+    with Videohub('192.0.2.31') as vh:
+        snapshot = vh.state()
+        vh.route(dest=3, src=12)
+"""
+
+from videohubwire.client import Videohub, VideohubError
+
+__all__ = ['Videohub', 'VideohubError']

videohubwire-0.1.0.dev0/videohubwire/client.py

@@ -0,0 +1,376 @@
+# SPDX-License-Identifier: MIT
+"""videohubwire.client — Videohub Ethernet Protocol client.
+
+Text-based, block-oriented protocol over TCP 9990, documented in
+Blackmagic's "Videohub Ethernet Protocol" PDF (ships with the Videohub
+SDK). A block is a header line ending in ``:``, zero or more body
+lines, and a blank-line terminator::
+
+    VIDEO OUTPUT ROUTING:
+    0 12
+    3 7
+    <blank>
+
+On connect the hub dumps its full state as a run of blocks (protocol
+preamble, device info, input/output labels, output locks, routing —
+newer firmware ends the dump with ``END PRELUDE:``). After that it
+PUSHES the same block shapes whenever state changes from any client
+(another panel routes, a label edit), and answers commands with a bare
+``ACK`` or ``NAK`` block.
+
+This client is synchronous and single-socket (no worker thread): connect parses the preamble into a state snapshot;
+:meth:`state` drains any pushed updates and returns the current view;
+:meth:`route` sends one routing change and waits for ACK/NAK, applying
+any interleaved push blocks on the way. Intended usage is short-lived,
+per-request connections: the preamble for even a 120x120 hub is a few
+KB, so connect-read-act-close takes milliseconds on a LAN.
+
+Lock states in ``VIDEO OUTPUT LOCKS``: ``U`` unlocked, ``O`` locked by
+this connection ("owned"), ``L`` locked by another client. This client
+never takes locks; it reports them so the UI can render locked
+destinations read-only. Routing a locked destination gets a NAK.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import time
+from typing import Callable, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_PORT = 9990
+DEFAULT_CONNECT_TIMEOUT = 3.0
+DEFAULT_READ_TIMEOUT = 3.0
+
+# The preamble has no length header and pre-END-PRELUDE firmware never
+# marks its end. Treat it as complete once the essential blocks arrived
+# and the wire has gone quiet for this long.
+PREAMBLE_QUIET_S = 0.3
+
+# One retry on the initial TCP connect: the first packet to a device the
+# host hasn't talked to recently can be eaten by ARP resolution (the
+# same cold-target behaviour other Blackmagic devices show).
+CONNECT_RETRY_DELAY_S = 0.3
+
+
+class VideohubError(Exception):
+    """Protocol-level failure: NAK from the hub, closed connection, or
+    a timeout waiting for a response."""
+
+
+class Videohub:
+    """Client for one Videohub. Context manager::
+
+        with Videohub(ip) as vh:
+            snap = vh.state()
+            vh.route(dest, src)
+
+    ``socket_factory`` is a hook for tests: a callable with the
+    signature of :func:`socket.create_connection` returning an object
+    with ``sendall``, ``recv``, ``settimeout``, ``close``, ``shutdown``.
+    """
+
+    def __init__(self,
+                 host: str,
+                 port: int = DEFAULT_PORT,
+                 *,
+                 connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+                 read_timeout: float = DEFAULT_READ_TIMEOUT,
+                 socket_factory: Optional[Callable] = None):
+        self.host = host
+        self.port = port
+        self.connect_timeout = connect_timeout
+        self.read_timeout = read_timeout
+        self._socket_factory = socket_factory or socket.create_connection
+        self._sock = None
+        self._buf = b''
+
+        # State assembled from preamble + pushed blocks. Dicts keyed by
+        # int index — the hub addresses everything 0-based.
+        self.protocol_version: str = ''
+        self.device: Dict[str, str] = {}
+        self.input_labels: Dict[int, str] = {}
+        self.output_labels: Dict[int, str] = {}
+        self.routing: Dict[int, int] = {}     # dest -> src
+        self.locks: Dict[int, str] = {}       # dest -> 'U' | 'O' | 'L'
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> 'Videohub':
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def connect(self) -> None:
+        """Open the TCP connection and parse the state preamble."""
+        if self._sock is not None:
+            self.close()
+        try:
+            self._sock = self._socket_factory((self.host, self.port),
+                                              timeout=self.connect_timeout)
+        except OSError:
+            time.sleep(CONNECT_RETRY_DELAY_S)
+            self._sock = self._socket_factory((self.host, self.port),
+                                              timeout=self.connect_timeout)
+        self._buf = b''
+        try:
+            self._read_preamble()
+        except Exception:
+            self.close()
+            raise
+
+    def close(self) -> None:
+        if self._sock is None:
+            return
+        try:
+            self._sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+        try:
+            self._sock.close()
+        except OSError:
+            pass
+        self._sock = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def video_inputs(self) -> int:
+        return int(self.device.get('video inputs') or 0)
+
+    @property
+    def video_outputs(self) -> int:
+        return int(self.device.get('video outputs') or 0)
+
+    def state(self) -> dict:
+        """Drain pending pushed updates and return a UI-ready snapshot.
+
+        Shape::
+
+            {'device': {'model_name', 'friendly_name', 'video_inputs',
+                        'video_outputs', 'protocol_version'},
+             'inputs':  [{'index', 'label'}, ...],
+             'outputs': [{'index', 'label', 'source', 'lock'}, ...]}
+        """
+        self._drain()
+        n_in = self.video_inputs or (max(self.input_labels, default=-1) + 1)
+        n_out = self.video_outputs or (max(self.output_labels, default=-1) + 1)
+        return {
+            'device': {
+                'model_name': self.device.get('model name', ''),
+                'friendly_name': self.device.get('friendly name', ''),
+                'video_inputs': n_in,
+                'video_outputs': n_out,
+                'protocol_version': self.protocol_version,
+            },
+            'inputs': [
+                {'index': i,
+                 'label': self.input_labels.get(i) or f'Input {i + 1}'}
+                for i in range(n_in)
+            ],
+            'outputs': [
+                {'index': i,
+                 'label': self.output_labels.get(i) or f'Output {i + 1}',
+                 'source': self.routing.get(i),
+                 'lock': self.locks.get(i, 'U')}
+                for i in range(n_out)
+            ],
+        }
+
+    def route(self, dest: int, src: int) -> None:
+        """Route ``src`` to ``dest``. Raises :class:`VideohubError` on
+        NAK (typically a locked destination) or response timeout."""
+        dest, src = int(dest), int(src)
+        if dest < 0 or src < 0:
+            raise VideohubError(f'invalid route {dest} <- {src}')
+        n_out, n_in = self.video_outputs, self.video_inputs
+        if (n_out and dest >= n_out) or (n_in and src >= n_in):
+            raise VideohubError(
+                f'route {dest} <- {src} outside this hub '
+                f'({n_in}x{n_out})')
+        self._send(f'VIDEO OUTPUT ROUTING:\n{dest} {src}\n\n')
+        deadline = time.monotonic() + self.read_timeout
+        while True:
+            block = self._recv_block(deadline - time.monotonic())
+            if block is None:
+                raise VideohubError(
+                    f'timed out waiting for ACK routing {dest} <- {src}')
+            header = block[0].strip()
+            if header == 'ACK':
+                # The hub also broadcasts the changed ROUTING block;
+                # apply optimistically so a state() right after is
+                # correct even if that push is still in flight.
+                self.routing[dest] = src
+                return
+            if header == 'NAK':
+                raise VideohubError(
+                    f'hub refused route {dest} <- {src} '
+                    f'(destination locked?)')
+            # Interleaved push (someone else routing, etc.) — apply and
+            # keep waiting for our answer.
+            self._apply_block(block)
+
+    def set_input_label(self, index: int, label: str) -> None:
+        """Rename an input port. Empty label is allowed (clears it —
+        consumers fall back to 'Input N')."""
+        self._set_label('INPUT LABELS', self.input_labels,
+                        self.video_inputs, index, label)
+
+    def set_output_label(self, index: int, label: str) -> None:
+        """Rename an output port."""
+        self._set_label('OUTPUT LABELS', self.output_labels,
+                        self.video_outputs, index, label)
+
+    def _set_label(self, block: str, target: dict, count: int,
+                   index: int, label: str) -> None:
+        index = int(index)
+        # Newlines would break the block framing; the hub caps labels
+        # around 64 chars — enforce both before they hit the wire.
+        label = ' '.join(str(label).split())
+        if len(label) > 64:
+            raise VideohubError('label too long (max 64 characters)')
+        if index < 0 or (count and index >= count):
+            raise VideohubError(f'{block.lower()} index {index} outside '
+                                f'this hub')
+        self._send(f'{block}:\n{index} {label}\n\n')
+        deadline = time.monotonic() + self.read_timeout
+        while True:
+            resp = self._recv_block(deadline - time.monotonic())
+            if resp is None:
+                raise VideohubError(
+                    f'timed out waiting for ACK renaming {block.lower()} '
+                    f'{index}')
+            header = resp[0].strip()
+            if header == 'ACK':
+                target[index] = label
+                return
+            if header == 'NAK':
+                raise VideohubError(
+                    f'hub refused label change on {block.lower()} {index}')
+            self._apply_block(resp)
+
+    def ping(self) -> None:
+        """Cheap liveness check (``PING:`` block, ACK expected)."""
+        self._send('PING:\n\n')
+        deadline = time.monotonic() + self.read_timeout
+        while True:
+            block = self._recv_block(deadline - time.monotonic())
+            if block is None:
+                raise VideohubError('timed out waiting for PING ack')
+            if block[0].strip() == 'ACK':
+                return
+            self._apply_block(block)
+
+    # ------------------------------------------------------------------
+    # Wire I/O
+    # ------------------------------------------------------------------
+
+    def _send(self, text: str) -> None:
+        if self._sock is None:
+            raise VideohubError('not connected')
+        self._sock.sendall(text.encode('utf-8'))
+
+    def _recv_block(self, timeout: float) -> Optional[List[str]]:
+        """Read one blank-line-terminated block. Returns the block's
+        lines (header first), or None if ``timeout`` elapses first."""
+        deadline = time.monotonic() + max(0.0, timeout)
+        while b'\n\n' not in self._buf:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return None
+            self._sock.settimeout(remaining)
+            try:
+                chunk = self._sock.recv(4096)
+            except socket.timeout:
+                return None
+            if not chunk:
+                raise VideohubError('connection closed by hub')
+            self._buf += chunk
+        raw, _, self._buf = self._buf.partition(b'\n\n')
+        return raw.decode('utf-8', 'replace').split('\n')
+
+    def _read_preamble(self) -> None:
+        """Consume the initial state dump.
+
+        Newer firmware terminates it with ``END PRELUDE:``; older
+        firmware just stops talking. Accept either: done on the marker,
+        or once the essential blocks have arrived and the wire has been
+        quiet for PREAMBLE_QUIET_S.
+        """
+        deadline = time.monotonic() + self.read_timeout
+        while True:
+            has_essentials = bool(self.device) and bool(self.routing)
+            block = self._recv_block(
+                PREAMBLE_QUIET_S if has_essentials
+                else deadline - time.monotonic())
+            if block is None:
+                if has_essentials:
+                    return
+                raise VideohubError(
+                    f'no state preamble from {self.host} — is this a '
+                    f'Videohub?')
+            if self._apply_block(block) == 'END PRELUDE:':
+                return
+
+    def _drain(self) -> None:
+        """Apply any pushed blocks sitting in the socket, non-blocking."""
+        while True:
+            block = self._recv_block(0.05)
+            if block is None:
+                return
+            self._apply_block(block)
+
+    # ------------------------------------------------------------------
+    # Block parsing
+    # ------------------------------------------------------------------
+
+    def _apply_block(self, lines: List[str]) -> str:
+        """Apply one block to local state; returns the header line."""
+        header = lines[0].strip()
+        body = [ln for ln in lines[1:] if ln.strip()]
+        if header == 'PROTOCOL PREAMBLE:':
+            for key, val in self._kv(body):
+                if key == 'version':
+                    self.protocol_version = val
+        elif header == 'VIDEOHUB DEVICE:':
+            for key, val in self._kv(body):
+                self.device[key] = val
+        elif header == 'INPUT LABELS:':
+            self._apply_indexed(body, self.input_labels, str)
+        elif header == 'OUTPUT LABELS:':
+            self._apply_indexed(body, self.output_labels, str)
+        elif header == 'VIDEO OUTPUT ROUTING:':
+            self._apply_indexed(body, self.routing, int)
+        elif header == 'VIDEO OUTPUT LOCKS:':
+            self._apply_indexed(body, self.locks, str)
+        # Everything else (CONFIGURATION:, SERIAL PORT..., MONITORING
+        # OUTPUT..., END PRELUDE:, ACK echoes) is deliberately ignored.
+        return header
+
+    @staticmethod
+    def _kv(body: List[str]):
+        for line in body:
+            key, sep, val = line.partition(':')
+            if sep:
+                yield key.strip().lower(), val.strip()
+
+    @staticmethod
+    def _apply_indexed(body: List[str], target: dict, cast) -> None:
+        """Parse ``<index> <value>`` lines. Values may contain spaces
+        (labels like ``0 CAM 1``) — only the first token is the index.
+        A malformed line is skipped and logged, not fatal."""
+        for line in body:
+            tok, _, rest = line.strip().partition(' ')
+            try:
+                target[int(tok)] = cast(rest.strip())
+            except (ValueError, TypeError):
+                logger.warning('videohubwire: skipping malformed line %r', line)

videohubwire-0.1.0.dev0/videohubwire.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: videohubwire
+Version: 0.1.0.dev0
+Summary: Blackmagic Videohub Ethernet Protocol client (TCP 9990): state snapshot, routing, label editing
+Author: Lucas Romanenko
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# videohubwire
+
+videohubwire is a small, dependency-free Python client for Blackmagic
+**Videohub** routers speaking the Videohub Ethernet Protocol on TCP 9990. It
+connects, parses the router's state dump into a snapshot (device info, input
+and output labels, output locks, routing), routes a source to a destination
+with ACK/NAK handling, renames ports, and keeps the snapshot current by
+applying the update blocks the router pushes when any client changes
+something. It is synchronous and single-socket by design: open, read, act,
+close, in milliseconds on a LAN, which suits per-request use from a web
+backend or a script.
+
+## Features
+
+- `Videohub` context manager: `connect()` parses the preamble, `close()` shuts the socket, `state()` returns a UI-ready dict.
+- `route(dest, src)` sends one `VIDEO OUTPUT ROUTING` change, waits for `ACK`/`NAK`, and applies any pushed blocks that arrive in between.
+- `set_input_label()` / `set_output_label()` with newline collapsing and a 64-character cap before anything hits the wire.
+- `ping()` liveness check.
+- Output lock states (`U` / `O` / `L`) surfaced per destination; the client never takes locks.
+- Bounds checks against the router's own port counts; a `NAK` or timeout raises `VideohubError`.
+- Works with and without the `END PRELUDE:` marker, so old and new firmware both connect.
+- One connect retry for cold-ARP first-packet loss; malformed lines are logged and skipped, not fatal.
+- Pure standard library; a `socket_factory` hook lets the whole suite run without hardware.
+
+## Install
+
+```sh
+pip install "git+https://github.com/lucas-romanenko/videohubwire.git@v0.1.0.dev0"
+```
+
+Python 3.10 or newer. To run the tests from a checkout:
+
+```sh
+pip install ".[test]"
+python -m pytest
+```
+
+## Usage
+
+```python
+from videohubwire import Videohub, VideohubError
+
+with Videohub('192.0.2.31') as vh:
+    snap = vh.state()
+    print(snap['device']['model_name'], snap['device']['video_inputs'], 'x',
+          snap['device']['video_outputs'])
+    for out in snap['outputs']:
+        print(out['index'], out['label'], '<-', out['source'], out['lock'])
+
+    try:
+        vh.route(dest=3, src=12)          # 0-based, like the wire
+    except VideohubError as e:
+        print('refused:', e)               # locked destination, NAK, or timeout
+
+    vh.set_output_label(3, 'Wall Monitor 1')
+```
+
+## Protocol notes
+
+Blackmagic documents the block format, the block names and the `ACK` / `NAK`
+replies in the Videohub Ethernet Protocol document that ships with the
+Videohub SDK; this section covers only what that document does not settle
+or what this client does on top of it.
+
+- **Preamble end detection.** Newer firmware ends the initial state dump with an `END PRELUDE:` block; older firmware simply stops sending. The client accepts either: it returns as soon as the marker arrives, or once a `VIDEOHUB DEVICE:` block and a `VIDEO OUTPUT ROUTING:` block have both been seen and the wire has been quiet for 0.3 s. A router that sends neither the marker nor a routing block is reported as "no state preamble"; that is a known limitation for an unusual device rather than a supported case.
+- **Pushed updates interleave with replies.** After the preamble the router pushes the same block shapes whenever state changes from any client. Those pushes can land between a command and its `ACK`/`NAK`, so `route()`, the label setters and `ping()` apply any non-reply block they read and keep waiting for the reply. `state()` drains pending pushes with a short non-blocking read before building the snapshot.
+- **Optimistic routing apply.** On `ACK` the client records the new route immediately instead of waiting for the router's own `VIDEO OUTPUT ROUTING:` broadcast, so a `state()` call right after `route()` is already correct.
+- **Lock letters.** `VIDEO OUTPUT LOCKS` reports `U` (unlocked), `O` (locked by this connection) and `L` (locked by another client). This client never sends a lock command; it reports the letters so a caller can render locked destinations read-only. Routing a destination locked elsewhere returns `NAK`, which is raised as `VideohubError`.
+- **Labels with spaces and empty labels.** Indexed body lines are `<index> <value>`; only the first token is the index and the rest, spaces included, is the value. A line such as `3 ` (index and nothing else) is a cleared label; `state()` substitutes `Input N` / `Output N` (1-based) for display.
+- **Label limits.** The router rejects labels containing newlines because they break the block framing, and caps labels at roughly 64 characters. The client collapses all whitespace runs to single spaces and refuses labels longer than 64 characters before sending.
+- **Port counts.** `video_inputs` / `video_outputs` come from the `VIDEOHUB DEVICE:` block. If those keys are absent the snapshot sizes itself from the highest label index seen. A non-numeric count in that block raises `ValueError` rather than `VideohubError`.
+- **Ignored blocks.** `CONFIGURATION:`, `SERIAL PORT ...`, `MONITORING OUTPUT ...`, `VIDEO INPUT STATUS`, and any other block the client does not model are parsed past and dropped. Only `PROTOCOL PREAMBLE`, `VIDEOHUB DEVICE`, `INPUT LABELS`, `OUTPUT LABELS`, `VIDEO OUTPUT ROUTING` and `VIDEO OUTPUT LOCKS` update state.
+- **Connect retry.** The first TCP connect to a router the host has not spoken to recently is sometimes lost to ARP resolution. `connect()` retries once after 0.3 s on any `OSError`; a second failure propagates unchanged.
+- **Timeouts.** Connect and read timeouts default to 3 s. A read timeout while waiting for a reply raises `VideohubError`; the router closing the connection raises it too, rather than looping.
+- **What the test fixture reflects.** The canned preamble in the tests has the shape of a Smart Videohub 40 x 40 reporting protocol version 2.7 (device block, labels, locks, routing, optional marker). Other models were not exercised.
+
+## License
+
+MIT. See `LICENSE`.

videohubwire-0.1.0.dev0/videohubwire.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+videohubwire/__init__.py
+videohubwire/client.py
+videohubwire.egg-info/PKG-INFO
+videohubwire.egg-info/SOURCES.txt
+videohubwire.egg-info/dependency_links.txt
+videohubwire.egg-info/requires.txt
+videohubwire.egg-info/top_level.txt

videohubwire-0.1.0.dev0/videohubwire.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

videohubwire-0.1.0.dev0/videohubwire.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest

videohubwire-0.1.0.dev0/videohubwire.egg-info/top_level.txt

@@ -0,0 +1 @@
+videohubwire