hyperdeckwire 0.1.0.dev0__py3-none-any.whl

hyperdeckwire/__init__.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+"""hyperdeckwire — Blackmagic HyperDeck Studio control library.
+
+A small client for the HyperDeck Ethernet Protocol (TCP 9993, text /
+line-oriented) plus an FTP file-upload helper. Studio HD Mini-class
+units don't expose the HTTP REST API that the Plus/Pro/HDR SKUs got
+in firmware 8.x, so this library targets the always-on 9993 + FTP
+combination — works across the whole networked HyperDeck product line.
+
+The protocol is documented in BMD's
+``HyperDeckEthernetProtocol.pdf`` (December 2024).
+
+Public surface::
+
+    from hyperdeckwire import Hyperdeck, upload_clip
+
+    # Control:
+    with Hyperdeck('192.0.2.11') as hd:
+        info = hd.device_info()        # dict
+        clips = hd.disk_list()         # List[Clip]
+        hd.stop()
+        hd.clips_clear()
+        hd.clips_add('my-clip.mp4')
+        hd.play(loop=True, single_clip=True)
+
+    # File upload:
+    result = upload_clip('192.0.2.11', '/path/to/clip.mp4')
+    print(result.throughput_mb_s)
+"""
+
+from hyperdeckwire.client import (
+    Clip,
+    Hyperdeck,
+    HyperdeckError,
+    Response,
+)
+from hyperdeckwire.upload import UploadResult, upload_clip
+
+__all__ = [
+    'Clip',
+    'Hyperdeck',
+    'HyperdeckError',
+    'Response',
+    'UploadResult',
+    'upload_clip',
+]

hyperdeckwire/client.py

@@ -0,0 +1,553 @@
+# SPDX-License-Identifier: MIT
+"""hyperdeckwire.client — HyperDeck Ethernet Protocol client.
+
+Text-based, line-oriented protocol over TCP 9993. Documented in
+``HyperDeckEthernetProtocol.pdf`` from Blackmagic (Dec 2024).
+
+Response codes:
+  100-199 : failure (raised as :class:`HyperdeckError`)
+  200     : simple ack
+  201-299 : success with parameters (multi-line, blank-line terminated)
+  500-599 : asynchronous notification (skipped by default during a
+            blocking ``request``; arrives interleaved with normal traffic)
+
+Public surface::
+
+    from hyperdeckwire import Hyperdeck
+
+    with Hyperdeck('192.0.2.11') as hd:
+        info = hd.device_info()
+        for clip in hd.disk_list():
+            print(clip.clip_id, clip.name, clip.duration)
+        hd.stop()
+        hd.clips_clear()
+        hd.clips_add('my-clip.mp4')
+        hd.play(loop=True, single_clip=True)
+        state = hd.transport_info()
+
+Why a single client file (no per-feature split): the protocol vocabulary
+is small (~30 commands), the wire format is uniform (request line in,
+response block out), and there's no switcher-style state event stream
+to fan out. Splitting would add ceremony without payoff.
+If the vocabulary doubles, revisit.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import time
+from dataclasses import dataclass
+from typing import Callable, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_PORT = 9993
+DEFAULT_CONNECT_TIMEOUT = 5.0
+DEFAULT_READ_TIMEOUT = 5.0
+
+
+class HyperdeckError(Exception):
+    """The HyperDeck rejected a command (response code 100-199).
+
+    ``code`` and ``text`` are the raw protocol code + text so callers
+    can distinguish "remote control disabled" (111) from "clip not
+    found" (112) etc. — see the PDF for the full list.
+    """
+
+    def __init__(self, code: int, text: str):
+        self.code = code
+        self.text = text
+        super().__init__(f'[{code}] {text}')
+
+
+@dataclass(frozen=True)
+class Response:
+    """One response block parsed off the wire."""
+
+    code: int
+    text: str
+    lines: List[str]
+
+    def is_ok(self) -> bool:
+        return 200 <= self.code < 300
+
+    def is_error(self) -> bool:
+        return 100 <= self.code < 200
+
+    def is_async(self) -> bool:
+        return 500 <= self.code < 600
+
+    def params(self) -> Dict[str, str]:
+        """Parse the response body as ``key: value`` pairs.
+
+        Multi-line responses (codes 201-299, 500-599) carry an indented
+        block of ``key: value`` lines before the blank terminator. This
+        flattens them to a plain dict.
+        """
+        out: Dict[str, str] = {}
+        for line in self.lines:
+            stripped = line.strip()
+            if not stripped or ':' not in stripped:
+                continue
+            key, _, val = stripped.partition(':')
+            out[key.strip()] = val.strip()
+        return out
+
+
+@dataclass(frozen=True)
+class Clip:
+    """A clip on the timeline or on disk.
+
+    Fields vary by source: ``disk_list`` populates ``file_format`` and
+    ``video_format``; ``clips_get`` (default v1) populates ``start``.
+    The intersection is ``clip_id``, ``name``, ``duration`` — those
+    three are always set.
+    """
+
+    clip_id: int
+    name: str
+    duration: str                      # timecode HH:MM:SS:FF
+    start: Optional[str] = None        # clips_get v1 timeline start
+    file_format: Optional[str] = None  # disk_list, e.g. "H.264"
+    video_format: Optional[str] = None # disk_list, e.g. "1080p25"
+
+
+# ---------------------------------------------------------------------------
+# Hyperdeck client
+# ---------------------------------------------------------------------------
+
+class Hyperdeck:
+    """Client for the HyperDeck Ethernet Protocol over TCP 9993.
+
+    Connection lifecycle is explicit: :meth:`connect` opens the socket
+    and drains the greeting; :meth:`close` shuts down. Use as a context
+    manager to get both for free::
+
+        with Hyperdeck(ip) as hd:
+            ...
+
+    Read-only commands (``device_info``, ``disk_list``, ``clips_get``,
+    ``transport_info``, ``configuration``, ``slot_info``) work without
+    setup. Write commands (``stop``, ``play``, ``clips_clear``,
+    ``clips_add``, ``goto_clip``) need the unit's "remote control"
+    flag enabled. On HD-class units that defaults to True; query with
+    :meth:`remote_info` if unsure.
+
+    ``socket_factory`` is a hook for tests: pass a callable that
+    returns an object with ``sendall``, ``recv``, ``settimeout``,
+    ``close``, ``shutdown``. Default is :func:`socket.create_connection`.
+    """
+
+    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''
+        self._greeting: Optional[Response] = None
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> 'Hyperdeck':
+        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 drain the greeting (500 connection info)."""
+        # connect() over an already-connected
+        # instance must not overwrite _sock and leak the old socket.
+        if self._sock is not None:
+            self.close()
+        self._sock = self._socket_factory((self.host, self.port),
+                                          timeout=self.connect_timeout)
+        self._sock.settimeout(self.read_timeout)
+        self._buf = b''
+        # The unit sends a 500 connection info: block immediately on
+        # accept. It IS a 5xx code, but it's a one-time synchronous
+        # greeting, not the kind of asynchronous notification we
+        # normally want to skip during a request — read it with
+        # skip_async=False so it doesn't get drained into the void.
+        try:
+            self._greeting = self._read_response(skip_async=False)
+        except Exception:
+            # A failed greeting read must not leak
+            # the just-opened socket until GC — close + clear before
+            # re-raising so the instance is cleanly reconnectable.
+            self.close()
+            raise
+
+    def close(self) -> None:
+        """Send ``quit`` (best-effort) and close the socket."""
+        if self._sock is None:
+            return
+        try:
+            self._send_line('quit')
+        except OSError:
+            pass
+        try:
+            self._sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+        try:
+            self._sock.close()
+        except OSError:
+            pass
+        self._sock = None
+
+    # ------------------------------------------------------------------
+    # Greeting accessors
+    # ------------------------------------------------------------------
+
+    @property
+    def model(self) -> str:
+        """Model name from the connection greeting (e.g. 'HyperDeck Studio HD Mini')."""
+        return (self._greeting.params().get('model', '')
+                if self._greeting else '')
+
+    @property
+    def protocol_version(self) -> str:
+        """Protocol version string from the connection greeting (e.g. '1.13')."""
+        return (self._greeting.params().get('protocol version', '')
+                if self._greeting else '')
+
+    # ------------------------------------------------------------------
+    # Low-level I/O
+    # ------------------------------------------------------------------
+
+    def _send_line(self, line: str) -> None:
+        if self._sock is None:
+            raise OSError('not connected')
+        self._sock.sendall((line + '\n').encode('utf-8'))
+
+    def _recv_line(self, deadline: float) -> str:
+        """Read one CRLF-terminated line. Strips trailing \\r\\n."""
+        while b'\n' not in self._buf:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError('no line within deadline')
+            self._sock.settimeout(min(remaining, 0.5))
+            try:
+                chunk = self._sock.recv(4096)
+            except socket.timeout:
+                continue
+            if not chunk:
+                raise ConnectionError('peer closed connection')
+            self._buf += chunk
+        line, _, rest = self._buf.partition(b'\n')
+        self._buf = rest
+        return line.rstrip(b'\r').decode('utf-8', errors='replace')
+
+    def _read_response(self, timeout: Optional[float] = None,
+                       skip_async: bool = True) -> Response:
+        """Read one full response block off the wire.
+
+        Multi-line detection: a response is multi-line iff the headline
+        ends with a colon. Continuation lines are then read until a
+        blank-line terminator.
+
+        Asynchronous 5xx messages can arrive interleaved. By default
+        they're logged and skipped here so a caller waiting on the
+        actual response doesn't see them. Set ``skip_async=False`` to
+        return them through.
+        """
+        timeout = timeout if timeout is not None else self.read_timeout
+        deadline = time.monotonic() + timeout
+        while True:
+            head = self._recv_line(deadline)
+            if not head:
+                continue
+            code, _, text = head.partition(' ')
+            try:
+                code_int = int(code)
+            except ValueError:
+                raise OSError(f'malformed response head: {head!r}')
+
+            lines: List[str] = []
+            if text.endswith(':'):
+                text = text[:-1]
+                while True:
+                    cont = self._recv_line(deadline)
+                    if cont == '':
+                        break
+                    lines.append(cont)
+
+            resp = Response(code=code_int, text=text, lines=lines)
+            if resp.is_async() and skip_async:
+                logger.debug('hyperdeck async: %s', resp)
+                continue
+            return resp
+
+    def request(self, command: str,
+                timeout: Optional[float] = None) -> Response:
+        """Send a command, read one response, return it.
+
+        Does NOT raise on protocol-level error codes (1xx). Use
+        :meth:`_check_ok` (or just inspect the response) for that.
+        """
+        self._send_line(command)
+        return self._read_response(timeout=timeout)
+
+    def _check_ok(self, command: str,
+                  timeout: Optional[float] = None) -> Response:
+        """Like :meth:`request` but raises :class:`HyperdeckError` on 1xx."""
+        resp = self.request(command, timeout=timeout)
+        if resp.is_error():
+            raise HyperdeckError(resp.code, resp.text)
+        return resp
+
+    # ------------------------------------------------------------------
+    # Info commands (read-only)
+    # ------------------------------------------------------------------
+
+    def device_info(self) -> Dict[str, str]:
+        """Return ``model``, ``protocol version``, ``unique id``, etc."""
+        return self._check_ok('device info').params()
+
+    def remote_info(self) -> Dict[str, str]:
+        """Return remote-control state (``enabled``, ``override``)."""
+        return self._check_ok('remote').params()
+
+    def slot_info(self, slot_id: Optional[int] = None) -> Dict[str, str]:
+        """Return info for the active slot (or a specific slot id)."""
+        cmd = 'slot info' if slot_id is None else f'slot info: slot id: {slot_id}'
+        return self._check_ok(cmd).params()
+
+    def transport_info(self) -> Dict[str, str]:
+        """Return current transport state (status, speed, clip id, timecode, loop, …)."""
+        return self._check_ok('transport info').params()
+
+    def configuration(self) -> Dict[str, str]:
+        """Return the unit's current configuration (file format, audio, timecode, …)."""
+        return self._check_ok('configuration').params()
+
+    def set_configuration(self, **params) -> None:
+        """Update one or more configuration parameters in a single command.
+
+        Pass snake_case keyword args; they're translated to the protocol's
+        ``{param}: {value}`` form (underscores -> spaces) and stacked into
+        a single ``configuration:`` line so the deck applies them as a
+        batch. Booleans render as ``true`` / ``false`` strings.
+
+        Examples::
+
+            hd.set_configuration(file_format='H.264High')
+            hd.set_configuration(file_format='QuickTimeProResHQ',
+                                 default_standard='2160p25')
+            hd.set_configuration(record_cache=True)
+
+        Common parameter names (see ``HyperDeckEthernetProtocol.pdf`` for
+        the full enum on each):
+
+        ===================== =========================================
+        snake_case kwarg      Protocol field
+        ===================== =========================================
+        ``file_format``       H.264High, QuickTimeProResHQ, DNxHR_HQX, …
+        ``default_standard``  1080p25, 2160p50, 720p5994, …
+        ``video_input``       SDI, 4xSDI, HDMI, component, composite
+        ``audio_input``       embedded, XLR, RCA
+        ``audio_codec``       PCM, AAC
+        ``record_prefix``     str (UTF-8)
+        ``record_cache``      bool
+        ``append_timestamp``  bool
+        ===================== =========================================
+
+        A no-args call is a no-op; the protocol would reject an empty
+        ``configuration:`` anyway.
+
+        Note: BMD's docs say changing ``file_format`` *may* respond with
+        ``213 deck rebooting`` (a 2xx success code) instead of ``200 ok``
+        and close the connection. Both are treated as success here. In
+        testing, a Studio HD Mini did not reboot on the format changes
+        exercised, so no auto-reconnect logic is wired up; catch
+        ``OSError`` on the next call if you trip the rare case.
+        """
+        if not params:
+            return
+        parts = []
+        for key, value in params.items():
+            proto_key = key.replace('_', ' ')
+            if isinstance(value, bool):
+                proto_value = 'true' if value else 'false'
+            else:
+                proto_value = str(value)
+            parts.append(f'{proto_key}: {proto_value}')
+        self._check_ok('configuration: ' + ' '.join(parts))
+
+    def disk_list(self, slot_id: Optional[int] = None) -> List[Clip]:
+        """List clips on the active disk (or specified slot)."""
+        cmd = 'disk list' if slot_id is None else f'disk list: slot id: {slot_id}'
+        resp = self._check_ok(cmd)
+        return _parse_clip_lines(resp.lines, _parse_disk_line)
+
+    def clips_count(self) -> int:
+        """Return the number of clips on the current timeline."""
+        resp = self._check_ok('clips count')
+        return int(resp.params().get('clip count', '0'))
+
+    def clips_get(self) -> List[Clip]:
+        """Return all clips currently on the timeline (version 1 format)."""
+        resp = self._check_ok('clips get')
+        return _parse_clip_lines(resp.lines, _parse_clips_v1_line)
+
+    # ------------------------------------------------------------------
+    # Action commands (write)
+    # ------------------------------------------------------------------
+
+    def stop(self) -> None:
+        """Stop playback or recording."""
+        self._check_ok('stop')
+
+    def play(self, *,
+             loop: bool = False,
+             single_clip: bool = False,
+             speed: Optional[int] = None,
+             clip_id: Optional[int] = None) -> None:
+        """Start playback. All parameters optional; defaults to a plain ``play``.
+
+        ``speed`` is a percentage between -5000 and 5000 (100 = normal).
+        ``clip_id`` starts playback at the given clip on the timeline.
+        """
+        parts = []
+        if clip_id is not None:
+            parts.append(f'clip id: {clip_id}')
+        if loop:
+            parts.append('loop: true')
+        if single_clip:
+            parts.append('single clip: true')
+        if speed is not None:
+            parts.append(f'speed: {int(speed)}')
+        cmd = 'play' if not parts else 'play: ' + ' '.join(parts)
+        self._check_ok(cmd)
+
+    def pause(self) -> None:
+        """Pause playback, holding the current frame.
+
+        The HyperDeck protocol has no literal ``pause`` verb — pausing is
+        ``play`` at zero speed, which freezes on the current frame (vs ``stop``
+        which ends playback). ``play()`` resumes at normal speed.
+        """
+        self._check_ok('play: speed: 0')
+
+    def clips_clear(self) -> None:
+        """Empty the current timeline (does not delete files on disk)."""
+        self._check_ok('clips clear')
+
+    def clips_add(self, name: str,
+                  *, before_clip_id: Optional[int] = None) -> None:
+        """Append a clip to the timeline (or insert before ``before_clip_id``).
+
+        ``name`` may include subfolders (``folder/clip.mp4``). Names with
+        spaces are passed through verbatim — the protocol parses the
+        parameter value as everything after ``name:`` until end-of-line.
+        """
+        if before_clip_id is not None:
+            cmd = f'clips add: clip id: {before_clip_id} name: {name}'
+        else:
+            cmd = f'clips add: name: {name}'
+        self._check_ok(cmd)
+
+    def clips_remove(self, clip_id: int) -> None:
+        """Remove a clip from the timeline by id (invalidates ids after it)."""
+        self._check_ok(f'clips remove: clip id: {clip_id}')
+
+    def goto_clip(self, clip_id: int) -> None:
+        """Seek the transport to the start of ``clip_id`` (does not play)."""
+        self._check_ok(f'goto: clip id: {clip_id}')
+
+    def remote_enable(self, enable: bool = True) -> None:
+        """Enable or disable remote control."""
+        flag = 'true' if enable else 'false'
+        self._check_ok(f'remote: enable: {flag}')
+
+    def slot_select(self, slot_id: int) -> None:
+        """Switch the active slot."""
+        self._check_ok(f'slot select: slot id: {slot_id}')
+
+    def ping(self) -> None:
+        """Check the unit is responding. Raises on error / disconnect."""
+        self._check_ok('ping')
+
+
+# ---------------------------------------------------------------------------
+# Line parsers
+# ---------------------------------------------------------------------------
+
+def _looks_like_clip_line(line: str) -> bool:
+    """True if the line begins with ``<int>:`` (a clip row) rather than
+    a header like ``slot id: 1`` or ``clip count: 5``."""
+    head, _, _ = line.strip().partition(':')
+    return head.isdigit()
+
+
+def _parse_clip_lines(lines, parser) -> List[Clip]:
+    """Apply ``parser`` to every clip-shaped line, skipping (and logging)
+    any single row the parser rejects.
+
+    One malformed row from the deck must not blow away the whole list;
+    callers need whatever clips parsed cleanly, not an exception. Header/non-clip lines are filtered first as before."""
+    clips: List[Clip] = []
+    for line in lines:
+        if not _looks_like_clip_line(line):
+            continue
+        try:
+            clips.append(parser(line))
+        except (ValueError, IndexError) as e:
+            logger.warning('hyperdeck: skipping unparseable clip line %r: %s',
+                           line, e)
+    return clips
+
+
+def _parse_disk_line(line: str) -> Clip:
+    """Parse a ``disk list`` row (version 1).
+
+    Format: ``{id}: {name} {file format} {video format} {duration}``
+
+    Filenames may contain spaces (verified against real hardware:
+    "Intro Loop animation.mp4"). We pull the three trailing tokens
+    (duration, video_format, file_format) and treat the rest as name.
+    """
+    head, _, rest = line.strip().partition(':')
+    clip_id = int(head.strip())
+    tokens = rest.strip().split(' ')
+    if len(tokens) < 4:
+        raise ValueError(f'malformed disk list line: {line!r}')
+    duration = tokens[-1]
+    video_format = tokens[-2]
+    file_format = tokens[-3]
+    name = ' '.join(tokens[:-3])
+    return Clip(clip_id=clip_id, name=name, duration=duration,
+                file_format=file_format, video_format=video_format)
+
+
+def _parse_clips_v1_line(line: str) -> Clip:
+    """Parse a ``clips get`` row in version 1 format.
+
+    Format: ``{id}: {name} {startT} {duration}``
+
+    Same filename-with-spaces caveat as ``_parse_disk_line``; tokens
+    are parsed from the right.
+    """
+    head, _, rest = line.strip().partition(':')
+    clip_id = int(head.strip())
+    tokens = rest.strip().split(' ')
+    if len(tokens) < 3:
+        raise ValueError(f'malformed clips line: {line!r}')
+    duration = tokens[-1]
+    start = tokens[-2]
+    name = ' '.join(tokens[:-2])
+    return Clip(clip_id=clip_id, name=name, duration=duration, start=start)

hyperdeckwire/upload.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: MIT
+"""hyperdeckwire.upload — FTP file upload to a HyperDeck Studio HD-class unit.
+
+The HTTP REST API for clip upload landed in firmware 8.x but only on
+the Plus/Pro/HDR/Shuttle SKUs — the Studio HD Mini doesn't have it
+(verified against firmware 8.1.1, port 80 closed). Every networked
+HyperDeck has FTP though, so that's the path this module takes.
+
+Wire details:
+  - Anonymous FTP (no auth required on stock firmware).
+  - Top-level dirs are storage volumes. Studio HD Mini names them
+    numerically per slot id (``/1/``, ``/2/``, ``/3/``); other models
+    (Studio HD, 4K) name them by medium (``sd1``, ``ssd1``, ``usb``).
+    Default behaviour: auto-detect a storage volume at root (numeric
+    first, else a known media prefix, SD preferred) and CWD into it.
+  - STOR at root is rejected (550 file unavailable); STOR inside a
+    slot dir works. The auto-detect handles that automatically.
+  - The Hyperdeck filesystem index updates live: after a successful
+    STOR the new clip is immediately visible via the 9993 ``disk list``
+    command, no rescan or slot-reselect required.
+"""
+
+from __future__ import annotations
+
+import ftplib
+import logging
+import os
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_FTP_TIMEOUT = 120.0   # large clips can take a minute+
+
+
+@dataclass(frozen=True)
+class UploadResult:
+    """Successful upload outcome — returned by :func:`upload_clip`."""
+
+    name: str               # the remote filename as written (basename of source)
+    size: int               # bytes written
+    duration_seconds: float # wall-clock duration of the STOR
+    slot_dir: str           # FTP working directory used (e.g. "1")
+
+    @property
+    def throughput_mb_s(self) -> float:
+        return self.size / max(self.duration_seconds, 0.001) / 1e6
+
+
+def upload_clip(host: str,
+                local_path: str,
+                *,
+                slot: Optional[int] = None,
+                login_user: str = '',
+                login_pass: str = '',
+                timeout: float = DEFAULT_FTP_TIMEOUT,
+                progress_callback=None) -> UploadResult:
+    """Upload ``local_path`` to a HyperDeck at ``host`` over FTP.
+
+    :param host: HyperDeck IP or hostname.
+    :param local_path: absolute path to the source file. Basename
+        becomes the remote name (preserved as-is, spaces and all —
+        the Hyperdeck handles those fine on both FTP and 9993 sides).
+    :param slot: numeric slot id to upload into. ``None`` (default)
+        auto-detects the first numeric subdirectory at the FTP root.
+    :param login_user / login_pass: FTP credentials. Empty defaults
+        attempt anonymous login (works on stock firmware); the
+        anonymous-with-empty-fields retry handles servers that reject
+        the bare ``USER`` form.
+    :param timeout: FTP socket timeout in seconds.
+    :param progress_callback: optional callable taking the running
+        byte count; called after each chunk for big-file UX.
+
+    :raises FileNotFoundError: ``local_path`` doesn't exist.
+    :raises ftplib.all_errors: anything FTP-level (login, CWD, STOR).
+    """
+    if not os.path.exists(local_path):
+        raise FileNotFoundError(local_path)
+
+    size = os.path.getsize(local_path)
+    name = os.path.basename(local_path)
+    logger.info('hyperdeckwire: starting upload %s -> %s:21 (%d bytes)',
+                local_path, host, size)
+
+    t0 = time.monotonic()
+    with ftplib.FTP(host, timeout=timeout) as ftp:
+        try:
+            ftp.login(login_user, login_pass)
+        except ftplib.error_perm:
+            # Some FTP servers reject the bare anonymous form; retry
+            # with the canonical ``anonymous`` user.
+            ftp.login('anonymous', '')
+
+        slot_dir = _resolve_slot_dir(ftp, slot)
+        ftp.cwd(slot_dir)
+
+        bytes_sent = [0]
+
+        def _on_chunk(chunk: bytes) -> None:
+            bytes_sent[0] += len(chunk)
+            if progress_callback is not None:
+                try:
+                    progress_callback(bytes_sent[0])
+                except Exception:
+                    logger.exception('upload progress_callback raised')
+
+        with open(local_path, 'rb') as f:
+            ftp.storbinary(f'STOR {name}', f, callback=_on_chunk)
+
+    dt = time.monotonic() - t0
+    result = UploadResult(name=name, size=size,
+                          duration_seconds=dt, slot_dir=slot_dir)
+    logger.info('hyperdeckwire: upload OK %s (%.1fs, %.1f MB/s)',
+                name, dt, result.throughput_mb_s)
+    return result
+
+
+# Storage-volume name prefixes HyperDeck firmware presents at FTP root, in
+# preference order. Studio HD Mini exposes numeric dirs (``/1/``, ``/2/``);
+# other models (e.g. Studio HD, 4K) expose named mounts like ``sd1`` /
+# ``ssd1`` / ``usb``. SD is preferred since that's the usual record/playback
+# medium. ``System Volume Information`` / ``.Trashes`` are never matched.
+_MEDIA_DIR_PREFIXES = ('sd', 'ssd', 'usb', 'nas')
+
+
+def _resolve_slot_dir(ftp: ftplib.FTP, slot=None) -> str:
+    """Return the slot dir to CWD into. A caller-supplied ``slot`` wins
+    (an int slot id like ``2`` or a literal dir name like ``'sd1'``);
+    otherwise list root and pick a storage volume.
+
+    Numeric slot dirs win when present (legacy firmware). Otherwise the
+    first directory matching a known media prefix (sd/ssd/usb/nas) is
+    used, so newer models that name their mounts (``['sd1', 'usb']``)
+    work too."""
+    if slot is not None:
+        return str(slot)
+    entries = ftp.nlst()
+    numeric = sorted([e for e in entries if e.isdigit()], key=int)
+    if numeric:
+        return numeric[0]
+    for prefix in _MEDIA_DIR_PREFIXES:
+        named = sorted([e for e in entries if e.lower().startswith(prefix)])
+        if named:
+            return named[0]
+    raise OSError(
+        f'no slot dir found at FTP root (entries: {entries!r})')

hyperdeckwire-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: hyperdeckwire
+Version: 0.1.0.dev0
+Summary: Blackmagic HyperDeck control over the Ethernet Protocol (TCP 9993) plus FTP clip upload
+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
+
+# hyperdeckwire
+
+hyperdeckwire is a small, dependency-free Python library for driving
+Blackmagic **HyperDeck Studio** recorders over the network. It speaks the
+HyperDeck Ethernet Protocol (line-oriented text over TCP 9993) for transport
+control, clip listing and timeline editing, and uses the deck's built-in FTP
+server (port 21) to push new clips onto its storage. It targets the
+`9993 + FTP` combination on purpose: the HTTP REST API that arrived in
+firmware 8.x is only available on the Plus/Pro/HDR/Shuttle models, while every
+networked HyperDeck, including the Studio HD Mini, offers these two.
+
+## Features
+
+- Blocking, single-socket `Hyperdeck` client with an explicit connect/close lifecycle and context-manager support.
+- Read commands: `device_info`, `remote_info`, `slot_info`, `transport_info`, `configuration`, `disk_list`, `clips_get`, `clips_count`.
+- Write commands: `play` (loop, single clip, speed, clip id), `pause`, `stop`, `goto_clip`, `clips_add`, `clips_remove`, `clips_clear`, `slot_select`, `remote_enable`, `set_configuration`, `ping`.
+- Typed `Clip` and `Response` dataclasses; protocol errors raise `HyperdeckError` with the deck's code and text.
+- Asynchronous 5xx notifications are filtered out of blocking requests and can be read explicitly.
+- `upload_clip` FTP helper with storage-volume auto-detection, anonymous-login fallback, progress callback and throughput reporting.
+- Pure standard library; a `socket_factory` hook and `ftplib` monkeypatching make the whole suite runnable without hardware.
+
+## Install
+
+```sh
+pip install "git+https://github.com/lucas-romanenko/hyperdeckwire.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 hyperdeckwire import Hyperdeck, HyperdeckError, upload_clip
+
+# Push a clip onto the deck's active storage volume.
+result = upload_clip('192.0.2.11', '/local/path/intro.mp4')
+print(f'{result.name}: {result.throughput_mb_s:.1f} MB/s into slot {result.slot_dir}')
+
+# Cue it and loop it.
+with Hyperdeck('192.0.2.11') as hd:
+    print(hd.model, hd.protocol_version)
+    for clip in hd.disk_list():
+        print(clip.clip_id, clip.name, clip.duration)
+    hd.stop()
+    hd.clips_clear()
+    try:
+        hd.clips_add('intro.mp4')
+    except HyperdeckError as e:
+        raise SystemExit(f'deck refused the clip: {e}')
+    hd.play(loop=True, single_clip=True)
+```
+
+The full command reference, dataclass fields and error-code table are in
+[docs/API.md](docs/API.md).
+
+## Protocol notes
+
+The Ethernet Protocol itself is documented by Blackmagic in
+`HyperDeckEthernetProtocol.pdf` (December 2024 revision). The points below
+are behaviour the library relies on that the document does not spell out, or
+that was established on hardware.
+
+- **No REST API on the Studio HD Mini.** Port 80 is closed on firmware 8.1.1, so the library never depends on HTTP.
+- **The greeting is a 5xx.** On connect the deck sends `500 connection info:` as a multi-line block. It shares the code range of asynchronous notifications but is synchronous and arrives once; the client reads it eagerly and caches `model` and `protocol version` from it.
+- **Multi-line framing.** A response is multi-line if and only if its head line ends with a colon; the body is then read until a blank line. Async notifications can interleave with a pending response and are skipped inside `request()` by default.
+- **There is no pause verb.** `pause()` sends `play: speed: 0`, which freezes on the current frame. `stop` also holds the last frame under the factory `stop mode: lastframe` setting; the transport reports `stopped` in both cases.
+- **`213 deck rebooting` is a success.** A `file format` change may answer with 213 instead of `200 ok` and drop the connection. The client treats both as success and leaves reconnecting to the caller.
+- **FTP volume layout.** Storage volumes are top-level directories. The Studio HD Mini names them by slot number (`/1/`, `/2/`); other models name them by medium (`sd1`, `ssd1`, `usb`, `nas`). `STOR` at the root is refused with `550`, so `upload_clip` lists the root, picks a volume (numeric first, then SD, SSD, USB, NAS) and changes into it. `System Volume Information` and `.Trashes` are never selected.
+- **FTP login.** Stock firmware accepts an empty anonymous login; some servers reject the bare `USER` form, so the helper retries as `anonymous` before failing.
+- **The disk index updates live.** A clip is visible to `disk list` immediately after its `STOR` completes; no rescan or slot reselect is needed.
+- **Clip names contain spaces.** `disk list` and `clips get` rows are tokenised from the right (duration, format fields) and everything left over is the name, which is why a name such as `Intro Loop animation.mp4` round-trips.
+- **Client limit.** Beyond a small number of simultaneous 9993 clients the deck answers `120 connection failed` and closes the socket.
+- **Verified hardware.** HyperDeck Studio HD Mini, firmware 8.1.1, full probe / clear / upload / cue-and-loop cycle. Other Studio HD models speak the same protocol but were not on the bench.
+
+## License
+
+MIT. See `LICENSE`.

hyperdeckwire-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,8 @@
+hyperdeckwire/__init__.py,sha256=5e9xA895FNwzqj03z-WbZhrM5o7blSEaJmeZb_4qeq8,1275
+hyperdeckwire/client.py,sha256=QNAj2Sr3oAYGqLeIPFAQBhL05QGrZ-461J0W6CKZH0Q,21160
+hyperdeckwire/upload.py,sha256=CPUT5gYtz_Dfnp-lYqHO4STSEKc3YfMsUXZMx0JHEXw,5937
+hyperdeckwire-0.1.0.dev0.dist-info/licenses/LICENSE,sha256=Mzt4-lP7NpZGbjxKnwYliRFTN_K-BJhL4CBIMWJO_jM,1072
+hyperdeckwire-0.1.0.dev0.dist-info/METADATA,sha256=0dvvWH5mDVSJEP37yMLMwJVOy6nCrCRRjibIwTdl7DA,5677
+hyperdeckwire-0.1.0.dev0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+hyperdeckwire-0.1.0.dev0.dist-info/top_level.txt,sha256=0lB6e9ShXX_UoU8a5Yd1dXOhcgmM7PsB-GApPuVDVsY,14
+hyperdeckwire-0.1.0.dev0.dist-info/RECORD,,

hyperdeckwire-0.1.0.dev0.dist-info/WHEEL

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

hyperdeckwire-0.1.0.dev0.dist-info/licenses/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.

hyperdeckwire-0.1.0.dev0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hyperdeckwire