bmdwire 1.10.0__tar.gz → 1.12.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {bmdwire-1.10.0/bmdwire.egg-info → bmdwire-1.12.0}/PKG-INFO +2 -2
- {bmdwire-1.10.0 → bmdwire-1.12.0}/README.md +1 -1
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/__init__.py +2 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/_socketqueue.py +10 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/connection.py +98 -17
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/SURFACE.md +73 -11
- bmdwire-1.12.0/atemwire/imaging.py +75 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/pool.py +7 -1
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/probe.py +9 -2
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/protocol.py +168 -28
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/ready.py +21 -2
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/transport.py +191 -23
- {bmdwire-1.10.0 → bmdwire-1.12.0/bmdwire.egg-info}/PKG-INFO +2 -2
- {bmdwire-1.10.0 → bmdwire-1.12.0}/pyproject.toml +1 -1
- bmdwire-1.10.0/atemwire/imaging.py +0 -60
- {bmdwire-1.10.0 → bmdwire-1.12.0}/LICENSE +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/LICENSE +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/LICENSE-gpl3.txt +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/NOTICE +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/_transfer.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/atem.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/MACRO_FORMAT.md +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/MEDIA_LOCK.md +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/PROFILE_FORMAT.md +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/PROFILE_SAVE_RESTORE.md +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/helpers.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/__init__.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/_helpers.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/_io.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/downstream_keyer.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/fairlight.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/flow.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/hyperdeck.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/media.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/switching.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/upstream_keyer.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/mediaconvertmodule.c +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/__init__.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/_dsl.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/audio_legacy.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/camera_control.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/color_generator.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/downstream_keyer.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/fade_to_black.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/fairlight.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/file_transfer.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/hyperdeck.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/input_video.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/lock.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/macros.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/manual.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/media.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/meters.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/multiviewer.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/recording.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/streaming.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/supersource.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/switching.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/system_info.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/tally.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/transition.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/upstream_keyer.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/__init__.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/_common.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/_enums.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/_xml.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/apply.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/options.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/save.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/py.typed +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/state.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/testing.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/bmdwire.egg-info/SOURCES.txt +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/bmdwire.egg-info/dependency_links.txt +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/bmdwire.egg-info/requires.txt +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/bmdwire.egg-info/top_level.txt +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/LICENSE +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/__init__.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/client.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/setup.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/upload.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/setup.cfg +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/setup.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/LICENSE +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/__init__.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/_preamble.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/_protocol.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/network.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/profile/__init__.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/profile/_ranges.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/profile/archive.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/profile/restore.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/videohubwire/LICENSE +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/videohubwire/__init__.py +0 -0
- {bmdwire-1.10.0 → bmdwire-1.12.0}/videohubwire/client.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: bmdwire
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.12.0
|
|
4
4
|
Summary: Python libraries for Blackmagic Design broadcast devices: ATEM switchers, HyperDeck recorders, Ultimatte keyers and Videohub routers
|
|
5
5
|
Author: Lucas Romanenko, Martijn Braam and the OpenAtem contributors
|
|
6
6
|
License-Expression: LGPL-3.0-only AND MIT
|
|
@@ -49,7 +49,7 @@ pip install bmdwire
|
|
|
49
49
|
| **`ultimattewire`** | Ultimatte 12 keyers: archive and restore over the native TCP protocol, Smart Remote 4 compatible zips | MIT | [ultimattewire/README.md](ultimattewire/README.md) |
|
|
50
50
|
| **`videohubwire`** | Videohub routers: state snapshot, crosspoint routing, labels over TCP 9990 | MIT | [videohubwire/README.md](videohubwire/README.md) |
|
|
51
51
|
|
|
52
|
-
All four are pure standard library except atemwire, whose small C extension ships prebuilt for Linux, macOS and Windows on CPython 3.10 to 3.14, so installing needs no compiler. Pin the version in a requirements file (`bmdwire==1.
|
|
52
|
+
All four are pure standard library except atemwire, whose small C extension ships prebuilt for Linux, macOS and Windows on CPython 3.10 to 3.14, so installing needs no compiler. Pin the version in a requirements file (`bmdwire==1.12.0`) so a later release cannot change your install under you.
|
|
53
53
|
|
|
54
54
|
## atemwire stands on pyatem
|
|
55
55
|
|
|
@@ -15,7 +15,7 @@ pip install bmdwire
|
|
|
15
15
|
| **`ultimattewire`** | Ultimatte 12 keyers: archive and restore over the native TCP protocol, Smart Remote 4 compatible zips | MIT | [ultimattewire/README.md](ultimattewire/README.md) |
|
|
16
16
|
| **`videohubwire`** | Videohub routers: state snapshot, crosspoint routing, labels over TCP 9990 | MIT | [videohubwire/README.md](videohubwire/README.md) |
|
|
17
17
|
|
|
18
|
-
All four are pure standard library except atemwire, whose small C extension ships prebuilt for Linux, macOS and Windows on CPython 3.10 to 3.14, so installing needs no compiler. Pin the version in a requirements file (`bmdwire==1.
|
|
18
|
+
All four are pure standard library except atemwire, whose small C extension ships prebuilt for Linux, macOS and Windows on CPython 3.10 to 3.14, so installing needs no compiler. Pin the version in a requirements file (`bmdwire==1.12.0`) so a later release cannot change your install under you.
|
|
19
19
|
|
|
20
20
|
## atemwire stands on pyatem
|
|
21
21
|
|
|
@@ -43,11 +43,13 @@ change in a minor release.
|
|
|
43
43
|
from atemwire.atem import ATEM
|
|
44
44
|
from atemwire.probe import probe
|
|
45
45
|
from atemwire.profile import ApplyOptions, ApplyResult, Profile
|
|
46
|
+
from atemwire.transport import NoFreeConnection
|
|
46
47
|
|
|
47
48
|
__all__ = [
|
|
48
49
|
'ATEM',
|
|
49
50
|
'ApplyOptions',
|
|
50
51
|
'ApplyResult',
|
|
52
|
+
'NoFreeConnection',
|
|
51
53
|
'Profile',
|
|
52
54
|
'probe',
|
|
53
55
|
]
|
|
@@ -37,6 +37,16 @@ class SocketQueue(queue.Queue):
|
|
|
37
37
|
self._getsocket.recv(1)
|
|
38
38
|
return super().get(**kwargs)
|
|
39
39
|
|
|
40
|
+
def get_waiting(self):
|
|
41
|
+
"""Every item put so far, without blocking: one read of the wakeup
|
|
42
|
+
bytes, then that many items. For a reader woken by select() that
|
|
43
|
+
should empty the queue in one go instead of one item per wakeup."""
|
|
44
|
+
try:
|
|
45
|
+
marks = self._getsocket.recv(4096, socket.MSG_DONTWAIT)
|
|
46
|
+
except (BlockingIOError, InterruptedError):
|
|
47
|
+
return []
|
|
48
|
+
return [super(SocketQueue, self).get() for _ in range(len(marks))]
|
|
49
|
+
|
|
40
50
|
def close(self):
|
|
41
51
|
"""Free the socketpair FDs. Idempotent. Without this the pair was
|
|
42
52
|
GC-only — every leaked protocol pinned 2 FDs (2026-07-06)."""
|
|
@@ -61,7 +61,7 @@ from typing import Any, Callable, Optional
|
|
|
61
61
|
|
|
62
62
|
from atemwire.protocol import AtemProtocol
|
|
63
63
|
from atemwire.ready import WaitAborted, wait_ready
|
|
64
|
-
from atemwire.transport import TRACE_ENABLED, Wakeup, drain_log
|
|
64
|
+
from atemwire.transport import TRACE_ENABLED, NoFreeConnection, Wakeup, drain_log
|
|
65
65
|
|
|
66
66
|
logger = logging.getLogger(__name__)
|
|
67
67
|
|
|
@@ -74,6 +74,14 @@ logger = logging.getLogger(__name__)
|
|
|
74
74
|
# eight seconds.
|
|
75
75
|
CONNECT_TIMEOUT = 15.0
|
|
76
76
|
|
|
77
|
+
# A cold connect waits for the handshake and the state dump for as long as
|
|
78
|
+
# they keep arriving, and gives up once nothing has come from the switcher
|
|
79
|
+
# for CONNECT_STALL_TIMEOUT (no progress), within a hard cap of CONNECT_MAX.
|
|
80
|
+
# A switcher that answers "no room" (0x03) fails at once (NoFreeConnection).
|
|
81
|
+
# CONNECT_TIMEOUT stays the wait for a pooled session that is re-handshaking.
|
|
82
|
+
CONNECT_STALL_TIMEOUT = 5.0
|
|
83
|
+
CONNECT_MAX = 60.0
|
|
84
|
+
|
|
77
85
|
# Cadence at which the worker pumps protocol.loop() while idle.
|
|
78
86
|
PUMP_INTERVAL = 0.01
|
|
79
87
|
|
|
@@ -135,6 +143,7 @@ class ATEMConnection:
|
|
|
135
143
|
self._stop_event = threading.Event()
|
|
136
144
|
self._ready_event = threading.Event() # set by worker once mixerstate is populated
|
|
137
145
|
self._connect_error: Optional[str] = None
|
|
146
|
+
self._connect_refused = False
|
|
138
147
|
|
|
139
148
|
# ``_handshake_done`` is True once the initial handshake + state
|
|
140
149
|
# dump succeeded for the CURRENT worker. Cleared on disconnect so
|
|
@@ -186,6 +195,29 @@ class ATEMConnection:
|
|
|
186
195
|
worker = self._worker
|
|
187
196
|
return worker is not None and worker.is_alive()
|
|
188
197
|
|
|
198
|
+
@property
|
|
199
|
+
def connect_refused(self) -> bool:
|
|
200
|
+
"""True when the last ``connect()`` failed because the switcher
|
|
201
|
+
answered "no room" (``NoFreeConnection``: every slot taken)."""
|
|
202
|
+
return self._connect_refused
|
|
203
|
+
|
|
204
|
+
def connect_progress(self) -> dict:
|
|
205
|
+
"""How far a connect has got, for a page to show while it waits:
|
|
206
|
+
``stage`` is ``'hello'`` (no answer yet), ``'state'`` (receiving the
|
|
207
|
+
switcher's state), ``'ready'``, or ``'no room'``; ``packets`` is how
|
|
208
|
+
many arrived. Cheap; safe from any thread."""
|
|
209
|
+
tr = getattr(getattr(self, '_protocol', None), 'transport', None)
|
|
210
|
+
packets = getattr(tr, 'rx_packet_count', 0) if tr is not None else 0
|
|
211
|
+
if self._connect_refused or getattr(tr, 'refused', False):
|
|
212
|
+
stage = 'no room'
|
|
213
|
+
elif self.is_ready:
|
|
214
|
+
stage = 'ready'
|
|
215
|
+
elif packets:
|
|
216
|
+
stage = 'state'
|
|
217
|
+
else:
|
|
218
|
+
stage = 'hello'
|
|
219
|
+
return {'stage': stage, 'packets': packets}
|
|
220
|
+
|
|
189
221
|
@property
|
|
190
222
|
def is_ready(self) -> bool:
|
|
191
223
|
"""True iff ``is_connected`` AND the switcher's state is current.
|
|
@@ -257,12 +289,20 @@ class ATEMConnection:
|
|
|
257
289
|
return self._protocol
|
|
258
290
|
|
|
259
291
|
def download_still(self, slot: int, *, timeout: float = 30.0,
|
|
260
|
-
progress_callback: Optional[Callable[[float], None]] = None
|
|
292
|
+
progress_callback: Optional[Callable[[float], None]] = None,
|
|
293
|
+
stall_timeout: Optional[float] = None) -> bytes:
|
|
261
294
|
"""Blocking native download of a STILL slot over this connection's
|
|
262
295
|
normal packet loop. Returns RLE-decoded frame bytes ready for
|
|
263
|
-
``atemwire.imaging.atem_to_rgb``. See ``_download_transfer``.
|
|
296
|
+
``atemwire.imaging.atem_to_rgb``. See ``_download_transfer``.
|
|
297
|
+
|
|
298
|
+
``stall_timeout``: give up once this long passes with no data
|
|
299
|
+
arriving (waiting for the lock counts as no data), while ``timeout``
|
|
300
|
+
caps the whole download. A 4K still is 12 MB or more on the wire and
|
|
301
|
+
an 8K one four times that, so one fixed timeout is either too short
|
|
302
|
+
for them or far too long to notice a transfer that stopped."""
|
|
264
303
|
return self._download_transfer(
|
|
265
|
-
0, slot, timeout=timeout, progress_callback=progress_callback
|
|
304
|
+
0, slot, timeout=timeout, progress_callback=progress_callback,
|
|
305
|
+
stall_timeout=stall_timeout)
|
|
266
306
|
|
|
267
307
|
def clear_still(self, slot: int, *, timeout: float = 5.0) -> None:
|
|
268
308
|
"""Blocking LOCKED clear of a STILL slot.
|
|
@@ -360,7 +400,8 @@ class ATEMConnection:
|
|
|
360
400
|
return self._download_transfer(0xFFFF, slot, timeout=timeout)
|
|
361
401
|
|
|
362
402
|
def _download_transfer(self, store: int, index: int, *, timeout: float,
|
|
363
|
-
progress_callback: Optional[Callable[[float], None]] = None
|
|
403
|
+
progress_callback: Optional[Callable[[float], None]] = None,
|
|
404
|
+
stall_timeout: Optional[float] = None) -> bytes:
|
|
364
405
|
"""Shared blocking native-transfer wait (ASC-style shared-session
|
|
365
406
|
path, 2026-07-02).
|
|
366
407
|
|
|
@@ -399,13 +440,16 @@ class ATEMConnection:
|
|
|
399
440
|
result['data'] = data
|
|
400
441
|
done.set()
|
|
401
442
|
|
|
443
|
+
last_data = [time.monotonic()]
|
|
444
|
+
|
|
402
445
|
def _on_progress(store_id, slot_idx, fraction):
|
|
403
|
-
if
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
446
|
+
if store_id == store and slot_idx == index:
|
|
447
|
+
last_data[0] = time.monotonic()
|
|
448
|
+
if progress_callback is not None:
|
|
449
|
+
try:
|
|
450
|
+
progress_callback(fraction)
|
|
451
|
+
except Exception:
|
|
452
|
+
pass
|
|
409
453
|
|
|
410
454
|
def _on_error(contents):
|
|
411
455
|
# The protocol raises this ONLY for a fatal status (the
|
|
@@ -433,7 +477,31 @@ class ATEMConnection:
|
|
|
433
477
|
lost_id = protocol.on('disconnected', _on_lost)
|
|
434
478
|
try:
|
|
435
479
|
protocol.download(store, index)
|
|
436
|
-
|
|
480
|
+
deadline = time.monotonic() + timeout
|
|
481
|
+
stalled = False
|
|
482
|
+
def _heard():
|
|
483
|
+
# The protocol's own clock as well: progress events need
|
|
484
|
+
# a known video mode, chunks don't.
|
|
485
|
+
lane = getattr(protocol, '_transfer_last_data', None)
|
|
486
|
+
if isinstance(lane, (int, float)) and lane > last_data[0]:
|
|
487
|
+
last_data[0] = lane
|
|
488
|
+
return last_data[0]
|
|
489
|
+
|
|
490
|
+
while True:
|
|
491
|
+
now = time.monotonic()
|
|
492
|
+
_heard()
|
|
493
|
+
wait_until = deadline
|
|
494
|
+
if stall_timeout is not None:
|
|
495
|
+
wait_until = min(deadline, last_data[0] + stall_timeout)
|
|
496
|
+
if done.wait(max(0.0, wait_until - now)):
|
|
497
|
+
break
|
|
498
|
+
now = time.monotonic()
|
|
499
|
+
if now >= deadline:
|
|
500
|
+
break
|
|
501
|
+
if (stall_timeout is not None
|
|
502
|
+
and now - _heard() >= stall_timeout):
|
|
503
|
+
stalled = True
|
|
504
|
+
break
|
|
437
505
|
if 'data' in result:
|
|
438
506
|
return result['data']
|
|
439
507
|
if result.get('lost'):
|
|
@@ -466,6 +534,10 @@ class ATEMConnection:
|
|
|
466
534
|
hint = (" — media store lock never granted; another "
|
|
467
535
|
"client is holding it" if lock_never_granted
|
|
468
536
|
else "")
|
|
537
|
+
if stalled:
|
|
538
|
+
raise TimeoutError(
|
|
539
|
+
f"download: store {store} slot {index} on "
|
|
540
|
+
f"{ip} stalled (no data for {stall_timeout}s){hint}")
|
|
469
541
|
raise TimeoutError(
|
|
470
542
|
f"download: store {store} slot {index} on "
|
|
471
543
|
f"{ip} timed out ({timeout}s){hint}")
|
|
@@ -555,6 +627,7 @@ class ATEMConnection:
|
|
|
555
627
|
self._stop_event.clear()
|
|
556
628
|
self._ready_event.clear()
|
|
557
629
|
self._connect_error = None
|
|
630
|
+
self._connect_refused = False
|
|
558
631
|
self._handshake_done = False
|
|
559
632
|
self._session_ready = False
|
|
560
633
|
self._died_signalled = False
|
|
@@ -575,8 +648,8 @@ class ATEMConnection:
|
|
|
575
648
|
)
|
|
576
649
|
self._worker.start()
|
|
577
650
|
|
|
578
|
-
if not self._ready_event.wait(timeout=
|
|
579
|
-
err = self._connect_error or f"timeout after {
|
|
651
|
+
if not self._ready_event.wait(timeout=CONNECT_MAX + 1.0):
|
|
652
|
+
err = self._connect_error or f"timeout after {CONNECT_MAX}s"
|
|
580
653
|
logger.warning(f"Instance {self.instance_id}: connect failed ({err})")
|
|
581
654
|
self._disconnect_locked()
|
|
582
655
|
return False
|
|
@@ -664,12 +737,20 @@ class ATEMConnection:
|
|
|
664
737
|
try:
|
|
665
738
|
wait_ready(
|
|
666
739
|
self._protocol,
|
|
667
|
-
timeout=
|
|
740
|
+
timeout=CONNECT_MAX,
|
|
741
|
+
stall_timeout=CONNECT_STALL_TIMEOUT,
|
|
668
742
|
pump_interval=PUMP_INTERVAL,
|
|
669
743
|
stop_event=self._stop_event,
|
|
670
744
|
)
|
|
671
|
-
except
|
|
672
|
-
self._connect_error =
|
|
745
|
+
except NoFreeConnection as e:
|
|
746
|
+
self._connect_error = str(e)
|
|
747
|
+
self._connect_refused = True
|
|
748
|
+
logger.warning(f"Instance {self.instance_id}: {self._connect_error}")
|
|
749
|
+
self._close_protocol()
|
|
750
|
+
self._ready_event.set()
|
|
751
|
+
return
|
|
752
|
+
except TimeoutError as e:
|
|
753
|
+
self._connect_error = f"initial state timeout ({e})"
|
|
673
754
|
logger.warning(f"Instance {self.instance_id}: {self._connect_error}")
|
|
674
755
|
self._close_protocol()
|
|
675
756
|
self._ready_event.set()
|
|
@@ -556,13 +556,15 @@ in the transfer flow. At field level, the `CKDV`/`CTDv` fields are all echoed, b
|
|
|
556
556
|
`FTDC` for it goes to every session with that id. Every session used to start at 43; since
|
|
557
557
|
`6876ba2` each starts at a random id in 1..0xFFFF, wrapping without 0 (§5.4 item 36).
|
|
558
558
|
- **`FTDE` status handling:**
|
|
559
|
-
- 1 (try again): re-send the request with the same tid.
|
|
559
|
+
- 1 (try again): re-send the request with the same tid. Since `588a389` after a pause that doubles
|
|
560
|
+
from `TRY_AGAIN_FIRST` (0.05 s) to `TRY_AGAIN_MAX` (1 s); after `TRY_AGAIN_ATTEMPTS` (20)
|
|
561
|
+
refusals the task fails like a fatal status, raised as `file-transfer-error` (§5.4 item 43).
|
|
560
562
|
- 5 (no lock): re-request the lock.
|
|
561
563
|
- 6 (another session collided): release, keep the task, re-request on the next release.
|
|
562
564
|
- Any other status: fatal for that task. The task is dropped, the lock released, and
|
|
563
565
|
`file-transfer-error` raised.
|
|
564
566
|
|
|
565
|
-
Statuses 1, 5 and 6 never reach callers.
|
|
567
|
+
Statuses 1, 5 and 6 never reach callers (since `588a389`, 1 does after 20 refusals in a row).
|
|
566
568
|
- **Upload pacing:** the switcher grants budgets with `FTCD(size, count)`. Chunks go out as `FTDa`
|
|
567
569
|
(an RLE header word is never split), then `FTFD(name, description, md5)` once the send queue
|
|
568
570
|
drains. Download chunks are acked one by one with `FTUA(tid, 0)`. Since `d050c10` `FTFD` goes
|
|
@@ -571,12 +573,16 @@ in the transfer flow. At field level, the `CKDV`/`CTDv` fields are all echoed, b
|
|
|
571
573
|
`abort_transfers()`. Timeouts live in the callers below.
|
|
572
574
|
- Lane control: `AtemProtocol.abort_transfers()` clears the lane and releases held locks;
|
|
573
575
|
`release_locks_now()` writes the unlocks straight to the socket and is meant for teardown.
|
|
576
|
+
Since `588a389` a still download that had a chunk within `DRAIN_STALL` (5 s) is not cut off: its
|
|
577
|
+
chunks are FTUA'd and dropped, the lock is released at its `FTDC` (or `FTDE`, or after
|
|
578
|
+
`DRAIN_STALL` with nothing, or `DRAIN_MAX`, 120 s, in all), and the next transfer waits for
|
|
579
|
+
that (§5.4 item 44).
|
|
574
580
|
|
|
575
581
|
### 3.1 Stills
|
|
576
582
|
|
|
577
583
|
| operation | entry point | parameters | behaviour |
|
|
578
584
|
|---|---|---|---|
|
|
579
|
-
| **download** | `ATEMConnection.download_still` (`connection.py:188`); on the facade, `atem.raw.download_still` | `(slot:int, *, timeout:float=30.0, progress_callback:Callable[[float],None]=None) -> bytes` | Blocking and serialised per connection. Flow: `PLCK(0,slot)` → `LKOB` → `FTSU` → `FTDa`×N/`FTUA` → `FTDC` → unlock. Returns the **RLE-decoded YCbCrA 4:2:2 frame** (w×h×4 bytes; actually a `bytearray`). Convert it with `imaging.atem_to_rgb`. Raises `ConnectionDeadError` (since `1572508` also while `is_ready` is False, §5.4 item 20; since `2b540db` also when the session goes while it waits, item 34), `RuntimeError` (fatal `FTDE`) or `TimeoutError` (after `abort_transfers`) |
|
|
585
|
+
| **download** | `ATEMConnection.download_still` (`connection.py:188`); on the facade, `atem.raw.download_still` | `(slot:int, *, timeout:float=30.0, progress_callback:Callable[[float],None]=None, stall_timeout:float=None) -> bytes` | Blocking and serialised per connection. With `stall_timeout` (since `588a389`) it gives up once that long passes with no chunk arriving (lock wait included) and `timeout` caps the whole download (§5.4 item 45). Flow: `PLCK(0,slot)` → `LKOB` → `FTSU` → `FTDa`×N/`FTUA` → `FTDC` → unlock. Returns the **RLE-decoded YCbCrA 4:2:2 frame** (w×h×4 bytes; actually a `bytearray`). Convert it with `imaging.atem_to_rgb`. Raises `ConnectionDeadError` (since `1572508` also while `is_ready` is False, §5.4 item 20; since `2b540db` also when the session goes while it waits, item 34), `RuntimeError` (fatal `FTDE`) or `TimeoutError` (after `abort_transfers`) |
|
|
580
586
|
| **upload** | **no high-level entry point**. Only `AtemProtocol.upload` (`protocol.py:682`) | `(store, index, data, compress=True, compressed=False, name=None, description=None, size=None, task=None) -> None` | Non-blocking: it only queues, and someone must pump `loop()`. `data` is a YCbCrA frame from `imaging.rgb_to_atem`. The MD5 is taken over the uncompressed frame. Flow: `PLCK` → `LKOB` → `FTSD(mode 1 = RLE)` → `FTCD` → `FTDa`… → `FTFD` → `FTDC` → `upload-done(store, slot)`. Progress arrives as `upload-progress(store, slot, percent, done, total)`. `size` is unused. `compressed=True` needs `compress=False`. `aggressive_drain=True` (constructor only, so not reachable through the pool) drains 10 packets per trigger instead of 5; since `d050c10` each budget is sent whole on any connection and it changes nothing (§5.4 item 22). The working reference caller is in WebATEM: `atem_control/uploader.py` (its own `AtemProtocol(ip, aggressive_drain=True)`, pumps until `upload-done`, then checks the `MPfe` hash) |
|
|
581
587
|
| **clear (locked)** | `ATEM.clear_still` / `ATEMConnection.clear_still` (`connection.py:196`); underneath, `AtemProtocol.queue_clear(store, index)` / `dequeue_clear(task)` | `(slot:int, *, timeout:float=5.0) -> None` | `LOCK(0,True)` → `LKOB` → `CSTL` → `clear-dispatched` → unlock. Returns once the clear has been **dispatched**, not confirmed; watch `MPfe.is_used` to confirm. Use this, not the bare `media.clear_still` op (§1.8). Raises `ConnectionDeadError` when not connected (since `1572508`, when not `is_ready`; since `2b540db`, also when the session goes before the clear is sent, §5.4 item 34) or `TimeoutError` |
|
|
582
588
|
| capture | `media.capture_still(conn)` | — | single packet `Capt`, listed for completeness |
|
|
@@ -590,10 +596,12 @@ in the transfer flow. At field level, the `CKDV`/`CTDv` fields are all echoed, b
|
|
|
590
596
|
- Chroma is taken from the **second pixel of each pair only**, not averaged.
|
|
591
597
|
- `premultiply` multiplies RGB by alpha first.
|
|
592
598
|
- `atem_to_rgb(data, width, height) -> bytes`: the inverse, returning RGBA8888. Alpha 0 round-trips
|
|
593
|
-
to 12.
|
|
599
|
+
to 12. Since `588a389` the Python wrapper converts in `CONVERT_PIECE` (1 MB) pieces, so the GIL is
|
|
600
|
+
free between them (§5.4 item 46).
|
|
594
601
|
- **Both converters parse `width`/`height` and never use them.** They walk the byte length, which
|
|
595
602
|
must be a multiple of 8 (`ValueError` otherwise). Output length equals input length.
|
|
596
|
-
- `rle_encode(data) -> bytes` (C) and `rle_decode(data) -> bytearray` (pure Python
|
|
603
|
+
- `rle_encode(data) -> bytes` (C) and `rle_decode(data) -> bytearray` (pure Python; since `588a389` it
|
|
604
|
+
finds the headers with `bytes.find` and copies the literal runs whole) work on 8-byte
|
|
597
605
|
words. The first word of a run is written literally. If it then repeats at least 3 more times, the
|
|
598
606
|
repeats become `FE×8` + a big-endian u64 count + the word (`mediaconvertmodule.c:266-298`). Input that
|
|
599
607
|
contains the word `FEFEFEFEFEFEFEFE` raises.
|
|
@@ -757,7 +765,7 @@ Profile enum tables (`profile/_enums.py`):
|
|
|
757
765
|
|---|---|---|
|
|
758
766
|
| facade | `atemwire.ATEM(ip)` (`atem.py`), context manager; `close()` is idempotent | A pooled session. Blocks up to 15 s on a cold connect (`RuntimeError` on failure); a warm connect joins at once (since `2b540db`, once the session is ready, §5.4 item 35). **Operations:** `atem.<op>(*args)` forwards to the `messages.<module>.<op>(conn, *args)` functions of 17 modules (`atem.py:72-89`). The `hyperdeck`, `lock`, `file_transfer`, `tally` and `meters` modules are not forwarded, so `set_hyperdeck_settings` is not on the facade. **Reads:** properties `connected`, `video_mode`, `product_name`, `program_source`, `preview_source`, `in_transition`, `transition_style`, `transition_rate`, `ftb_active`; methods `get_program_source(me)`, `get_preview_source(me)`, `get_in_transition(me)`, `get_transition_style(me)`, `get_transition_rate(me)`, `get_ftb_active(me)`; `snapshot()` (= `build_full_state`); `clear_still(slot, timeout=5.0)` (locked); `raw` → the `ATEMConnection` |
|
|
759
767
|
| pool | `atemwire.pool.acquire_connection(ip)` (context manager → `ATEMConnection`; since `2b540db`, `acquire_connection(ip, *, ready_timeout=None)`); `ATEMInstanceManager.peek_connection / get_instance / release_instance / list_instances` | One session per switcher per process, ref-counted. When the last ref goes, a 2 s grace timer disconnects. Nothing reaps a session whose ref is still held. A dead worker is evicted. `close_all_sessions_at_exit()` is registered with atexit. Single-process only. Since `2b540db` `acquire_connection` yields only a ready session, waiting for a re-handshake on a pool hit (§5.4 item 35); `get_instance` and `peek_connection` promise nothing about readiness |
|
|
760
|
-
| connection | `atemwire.connection.ATEMConnection(instance_id)` | `connect(ip) -> bool` (
|
|
768
|
+
| connection | `atemwire.connection.ATEMConnection(instance_id)` | `connect(ip) -> bool` (a cold connect waits while the switcher keeps sending and gives up after `CONNECT_STALL_TIMEOUT = 5 s` with nothing from it, at most `CONNECT_MAX = 60 s`, and at once on a "no room" answer, §5.4 item 47; up to 1.11.0 a fixed `CONNECT_TIMEOUT = 15 s`, which now only bounds the wait for a re-handshaking pooled session; since `2b540db` a connect that joins a session in a re-handshake waits for it too, §5.4 item 35), `disconnect()`, `is_connected`, `mixerstate`, `protocol`, `send(command)`, `download_still`, `download_macro`, `clear_still`, `set_on_died(cb)`, `last_run_macro_index`; since `2b540db`, `wait_until_ready(timeout) -> bool`; since 1.12.0 `connect_refused` and `connect_progress() -> {stage, packets}`. It has its own worker thread `AtemConn-<id>`, which pumps `protocol.loop()` every 10 ms and sends queued commands in batches of up to 1200 bytes per packet. A command that fails to render or is over-size is **dropped with a log line**, not raised |
|
|
761
769
|
| bare protocol | `atemwire.protocol.AtemProtocol(ip, port=9910, *, aggressive_drain=False)` | `connect()` sends SYN without blocking. **You** pump `loop()` (one packet per call). Also `send_commands([cmds])` (≤1300 bytes, else `ValueError`), `send_raw`, `on(event, cb) -> id`, `off(event, id)`, `mixerstate`, `connected`, `initialized`, plus the transfer methods (§3). It is **not thread-safe**. **It has no close method**; teardown is `release_locks_now()` → `transport.close_session()` → `transport.sock.close()` → `transport.thread_queue.close()` (`connection.py:723-755`). Passing a `tcp://` ip or `usb=` raises `NotImplementedError` |
|
|
762
770
|
|
|
763
771
|
Readiness and identity:
|
|
@@ -772,13 +780,20 @@ Readiness and identity:
|
|
|
772
780
|
### 4.2 Transport (UDP, `transport.py`)
|
|
773
781
|
|
|
774
782
|
- The switcher is on UDP **9910**. The handshake is a SYN with `0x01` and session id `0x1337`; the
|
|
775
|
-
switcher answers with a SYN (`0x02` = accepted
|
|
783
|
+
switcher answers with a SYN (`0x02` = accepted, `0x03` = no room: every client slot is taken)
|
|
784
|
+
and the client ACKs an acceptance. A `0x03` sets `transport.refused`, is not ACKed, and is not
|
|
785
|
+
asked again by the 5 s re-SYN; `wait_ready`, `ATEMConnection.connect` and `acquire_connection`
|
|
786
|
+
raise `atemwire.NoFreeConnection` (a `RuntimeError`) at once (§5.4 item 47). The session id is then
|
|
776
787
|
adopted from the switcher. The handshake ACK is sent from `loop()`, so it needs pumping. Since
|
|
777
788
|
`7e42caa`, a re-handshake drops packets carrying the replaced session's id, and while the SYN
|
|
778
789
|
is out, anything but its reply (§5.4 item 16).
|
|
779
790
|
- Every reliable packet is ACKed with the contiguous high-water mark, by the transport's **own
|
|
780
|
-
UDP thread**. A session therefore survives an unpumped loop; events only wait.
|
|
781
|
-
|
|
791
|
+
UDP thread**. A session therefore survives an unpumped loop; events only wait. Since `588a389` the
|
|
792
|
+
thread reads every datagram waiting when it wakes (up to `DRAIN_MAX`, 512) and ACKs them once,
|
|
793
|
+
cumulatively, after them (and every `ACK_EVERY`, 32, of a long run); outside a drain the ACK
|
|
794
|
+
goes at once. It sends everything queued for it per wake, too (§5.4 item 42).
|
|
795
|
+
- Duplicates are dropped. Since `588a389` a resend of a packet already received is ACKed again, and the
|
|
796
|
+
duplicate check is an O(1) window of the last 1024 sequences. Out-of-order packets are parked (up to 512 ahead). Retransmission is
|
|
782
797
|
**only on the switcher's request** (go-back-N, max 128). There is no client-side retransmit
|
|
783
798
|
timer, and the switcher's ACK number is never read. Since `d050c10` it is read, and what it
|
|
784
799
|
hasn't acknowledged in 250 ms is resent; a reliable packet the kernel refuses keeps its
|
|
@@ -947,7 +962,8 @@ simulated switcher state beyond a 1080p50 `video-mode`.
|
|
|
947
962
|
- `set_fairlight_eq_band` says `frequency_range` takes "0..3"; the wire values are the bitfield
|
|
948
963
|
1/2/4/8.
|
|
949
964
|
- `system_info` calls `TiRq` a keepalive; it is sent once.
|
|
950
|
-
- `
|
|
965
|
+
- `__init__.py` says a cold connect costs ~6 s; it is the handshake and the dump, and an
|
|
966
|
+
unreachable switcher costs `CONNECT_STALL_TIMEOUT` (5 s) since 1.12.0 (`probe.py` says so).
|
|
951
967
|
- `connection.py:726-734` says an abandoned lock lasts ~5 min; `MEDIA_LOCK.md` measured ~5 s.
|
|
952
968
|
- `_io.py:123` lists an inbound `FTUA` in the upload flow; none is waited for or parsed.
|
|
953
969
|
- The `upstream_keyer` DVE comment calls `rotation` "u16"; the field is i32.
|
|
@@ -1180,7 +1196,10 @@ fixed after 1.9.0 and still apply to it.
|
|
|
1180
1196
|
takes it, but macOS 12 refuses anything above `kern.ipc.maxsockbuf` with errno 55
|
|
1181
1197
|
(`ENOBUFS`): the constructor raised, and no switcher could be connected from that system.
|
|
1182
1198
|
*Fixed in `968798e`:* the request steps down 16, 8, 4, 1 MB and keeps the first size taken,
|
|
1183
|
-
or the system's default if it takes none.
|
|
1199
|
+
or the system's default if it takes none. Since `588a389` the size granted is read back
|
|
1200
|
+
(`UdpProtocol.rcvbuf`; Linux reports double, halved) and, when it is less than asked, logged
|
|
1201
|
+
once per process with the cap to raise (`net.core.rmem_max`): on Ubuntu's default of 208 KB
|
|
1202
|
+
a 4K still overflowed it (39,258 receive buffer errors in 220,040 datagrams, 2026-11-04).
|
|
1184
1203
|
31. **A caller's timeout hands the store back early** (1.5.1). `abort_transfers()` cleared the wait
|
|
1185
1204
|
for another client's turn with the queue. A caller that times out and retries (WebATEM's media
|
|
1186
1205
|
pool: 15 s, then again) asked at once, though the switcher may have handed the store over
|
|
@@ -1303,6 +1322,49 @@ fixed after 1.9.0 and still apply to it.
|
|
|
1303
1322
|
ASC's `4KHDp30`, `4KHDp60`, `8KHDp30` and `8KHDp60` have no wire number in any source this
|
|
1304
1323
|
library follows, so they stay unknown modes (item 3).
|
|
1305
1324
|
|
|
1325
|
+
42. **The UDP thread falls behind a still download** (1.10.0). A 4K Plus sends a still's chunks
|
|
1326
|
+
back to back, ~150 before it waits for their `FTUA`s, and resends all it has not had ACKed
|
|
1327
|
+
every ~80 ms. The thread woke, read one datagram and sent one ACK per packet, scanned a
|
|
1328
|
+
1024-entry deque twice per packet, sent one queued packet (each `FTUA`) per wake, and dropped
|
|
1329
|
+
a resend of something it had without ACKing again. Beside any other busy thread it fell
|
|
1330
|
+
behind the wire and the resends kept it there: captures from a 4K Plus (2026-11-04) show ACK
|
|
1331
|
+
p50 ~110 ms, p90 300–800 ms, 59–76% of inbound a resend, and a 12 MB still that never
|
|
1332
|
+
finished. *Fixed in `588a389`:* the drain and cumulative ACK of §4.2, ACKs for resends, an O(1)
|
|
1333
|
+
duplicate window, and every queued packet sent per wake. Offline, against a fake switcher
|
|
1334
|
+
modelled on the captures with one busy thread beside the client, a 4K still went from not
|
|
1335
|
+
finishing in 30 s (140–280× resends) to 2.3–3.6 s with none. A thread spinning in pure Python
|
|
1336
|
+
still slows it to ~12 s and needs a GIL switch interval of 1 ms (WebATEM sets one).
|
|
1337
|
+
43. **`FTDE 1` is asked again every ~10 ms, for ever** (1.10.0). While the switcher's transfer
|
|
1338
|
+
engine was held (item 44), a session sent ~900 requests in 13 s. *Fixed in `588a389`:* the pause
|
|
1339
|
+
and the cap of §3.0.
|
|
1340
|
+
44. **A caller's timeout cuts a download off mid-stream** (1.10.0). `abort_transfers()` released
|
|
1341
|
+
the store lock while the switcher was still sending; its transfer engine stayed with that
|
|
1342
|
+
transfer, unacknowledged, and refused every later request from every session with `FTDE 1`
|
|
1343
|
+
(WebATEM's 15 s against a 4K still, a 4K Plus capture, 2026-11-04; the state of bmdwire#64).
|
|
1344
|
+
*Fixed in `588a389`:* the abandoned download is drained to its end (§3.0). How ATEM Software
|
|
1345
|
+
Control ends a download early is not known (no capture of it); draining needs nothing the
|
|
1346
|
+
switcher doesn't already do.
|
|
1347
|
+
45. **One timeout for every still** (1.10.0). `download_still(timeout=...)` was the whole
|
|
1348
|
+
download, so a timeout that suits 1080p (~2 s) cuts a 4K or 8K still off, and one long
|
|
1349
|
+
enough for them hides a stalled transfer. *Fixed in `588a389`:* `stall_timeout` (§3.1).
|
|
1350
|
+
46. **A still's conversion stops every other thread** (1.10.0). `atem_to_rgb` is one C call that
|
|
1351
|
+
holds the GIL: 33 ms for a 1080p frame, 128 ms for a 4K one (measured), longer than the
|
|
1352
|
+
switcher's ~80 ms resend timer, so every connection's UDP thread in the process stood still;
|
|
1353
|
+
and `rle_decode` walked the frame 8 bytes at a time in Python on the connection's worker.
|
|
1354
|
+
*Fixed in `588a389`:* the conversion runs in pieces (the longest stall 6.9 ms) and
|
|
1355
|
+
`rle_decode` copies the literal runs whole (a 12 MB 4K test frame: 133 ms before, 18 ms
|
|
1356
|
+
after, same bytes).
|
|
1357
|
+
47. **A full switcher reads as offline, after 15 s** (1.11.0). A switcher whose session table is
|
|
1358
|
+
full answers the hello `0x03` within a millisecond. The transport left the state at SYN_SENT,
|
|
1359
|
+
ACKed the answer, re-sent the hello every 5 s, and the connect failed after `CONNECT_TIMEOUT`
|
|
1360
|
+
(15 s) as "initial state timeout", the same as a switcher that is off. A cold connect also
|
|
1361
|
+
failed at 15 s even while a big state dump was still arriving over a slow link. *Fixed in
|
|
1362
|
+
1.12.0:* the `0x03` raises `NoFreeConnection` at once (`wait_ready`, `ATEMConnection.connect`,
|
|
1363
|
+
whose `connect_refused` is then True, `acquire_connection`; `probe()` returns
|
|
1364
|
+
`no_free_connection: True`); a cold connect waits while the switcher keeps sending and gives
|
|
1365
|
+
up after `CONNECT_STALL_TIMEOUT` (5 s) with nothing from it, within `CONNECT_MAX` (60 s);
|
|
1366
|
+
`wait_ready(stall_timeout=...)` does the same for a bare protocol.
|
|
1367
|
+
|
|
1306
1368
|
## Counts
|
|
1307
1369
|
|
|
1308
1370
|
Measured by importing the package, not tallied by hand.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Copyright 2021 - 2022, Martijn Braam and the OpenAtem contributors
|
|
2
|
+
# SPDX-License-Identifier: LGPL-3.0-only
|
|
3
|
+
import struct
|
|
4
|
+
import atemwire.mediaconvert as mc
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
# atem_to_rgb converts in pieces of this many input bytes. The native
|
|
8
|
+
# conversion holds the GIL for the whole call: 33 ms for a 1080p still and
|
|
9
|
+
# 130 ms for a 4K one, measured 2026-11-04, longer than the ~80 ms after
|
|
10
|
+
# which a switcher resends what it hasn't had ACKed. Every connection's UDP
|
|
11
|
+
# thread in the process stood still for it, mid-download, and the
|
|
12
|
+
# resends it came back to buried the next still. Each 8-byte group (two
|
|
13
|
+
# pixels) converts on its own, so the pieces join to the same bytes.
|
|
14
|
+
CONVERT_PIECE = 1024 * 1024
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def atem_to_rgb(data, width, height):
|
|
18
|
+
"""Wrapper for the native function, run in CONVERT_PIECE pieces so
|
|
19
|
+
other threads get the GIL between them."""
|
|
20
|
+
if len(data) <= CONVERT_PIECE or len(data) % 8:
|
|
21
|
+
return mc.atem_to_rgb(data, width, height)
|
|
22
|
+
view = memoryview(data)
|
|
23
|
+
pieces = [mc.atem_to_rgb(view[i:i + CONVERT_PIECE], width, height)
|
|
24
|
+
for i in range(0, len(view), CONVERT_PIECE)]
|
|
25
|
+
return b''.join(pieces)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def rgb_to_atem(data, width, height, premultiply=False):
|
|
29
|
+
"""Wrapper for the native function"""
|
|
30
|
+
return mc.rgb_to_atem(data, width, height, premultiply)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def rle_encode(data):
|
|
34
|
+
return mc.rle_encode(data)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
_RLE_HEADER = b'\xfe' * 8
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def rle_decode(data):
|
|
41
|
+
"""
|
|
42
|
+
ATEM frames are compressed with a custom RLE encoding. Data in the frame is grouped in 8 byte chunks since
|
|
43
|
+
that is exactly 2 pixels in the 10-bit YCbCr 4:2:2 data. Most of the data is sent without compression but
|
|
44
|
+
if a 8 byte chunk is fully 0xfe then the following chunk is RLE compressed.
|
|
45
|
+
|
|
46
|
+
An RLE compressed part is an 64 bit integer setting the repeat count following the 8-byte block of data
|
|
47
|
+
to be repeated. This seems mainly useful to compress solid colors.
|
|
48
|
+
|
|
49
|
+
The literal runs between headers are copied whole, found with
|
|
50
|
+
``bytes.find``. Walking the frame 8 bytes at a time in Python ran on
|
|
51
|
+
the connection's own worker thread, which handled none of that
|
|
52
|
+
switcher's packets meanwhile: 133 ms for a 12 MB 4K test frame, 18 ms
|
|
53
|
+
now (2026-11-04).
|
|
54
|
+
|
|
55
|
+
:param data:
|
|
56
|
+
:return:
|
|
57
|
+
"""
|
|
58
|
+
result = bytearray()
|
|
59
|
+
offset = 0
|
|
60
|
+
in_size = len(data)
|
|
61
|
+
find = data.find
|
|
62
|
+
while offset < in_size:
|
|
63
|
+
header = find(_RLE_HEADER, offset)
|
|
64
|
+
# Headers sit on the 8-byte grid (literals are 8 bytes, a header
|
|
65
|
+
# group 24); 0xfe bytes spanning two words are pixel data.
|
|
66
|
+
while header != -1 and (header - offset) % 8:
|
|
67
|
+
header = find(_RLE_HEADER, header + 8 - (header - offset) % 8)
|
|
68
|
+
if header == -1:
|
|
69
|
+
result += data[offset:]
|
|
70
|
+
break
|
|
71
|
+
result += data[offset:header]
|
|
72
|
+
count, = struct.unpack_from('>Q', data, header + 8)
|
|
73
|
+
result += data[header + 16:header + 24] * count
|
|
74
|
+
offset = header + 24
|
|
75
|
+
return result
|
|
@@ -91,6 +91,7 @@ from contextlib import contextmanager
|
|
|
91
91
|
|
|
92
92
|
from atemwire import connection as _connection
|
|
93
93
|
from atemwire.connection import ATEMConnection, ConnectionDeadError # noqa: F401
|
|
94
|
+
from atemwire.transport import NoFreeConnection
|
|
94
95
|
|
|
95
96
|
logger = logging.getLogger(__name__)
|
|
96
97
|
|
|
@@ -417,8 +418,11 @@ def acquire_connection(ip_address: str, *, ready_timeout=None):
|
|
|
417
418
|
watcher should ride THIS pooled connection via ``get_instance`` rather
|
|
418
419
|
than open a second socket; every extra session costs the switcher a slot.)
|
|
419
420
|
|
|
421
|
+
:raises NoFreeConnection: at once, when the switcher answers "no room"
|
|
422
|
+
(every slot taken); a ``RuntimeError``.
|
|
420
423
|
:raises RuntimeError: if the underlying connection fails to become ready
|
|
421
|
-
|
|
424
|
+
(nothing from the switcher for ``CONNECT_STALL_TIMEOUT``, or
|
|
425
|
+
``CONNECT_MAX`` in all). A pooled session that
|
|
422
426
|
doesn't become ready in ``ready_timeout`` raises
|
|
423
427
|
``ConnectionDeadError``, a ``RuntimeError``.
|
|
424
428
|
"""
|
|
@@ -433,6 +437,8 @@ def acquire_connection(ip_address: str, *, ready_timeout=None):
|
|
|
433
437
|
if not (conn.is_connected and conn.ip_address == ip_address):
|
|
434
438
|
ok = conn.connect(ip_address)
|
|
435
439
|
if not ok:
|
|
440
|
+
if getattr(conn, 'connect_refused', False):
|
|
441
|
+
raise NoFreeConnection(ip_address)
|
|
436
442
|
err = getattr(conn, '_connect_error', None) or 'connect failed'
|
|
437
443
|
raise RuntimeError(f"ATEM {ip_address}: {err}")
|
|
438
444
|
# A cold connect returns ready; a pool hit may be mid re-handshake,
|
|
@@ -15,6 +15,7 @@ Returned dict shape:
|
|
|
15
15
|
'video_format': '1080p50' (str) or None,
|
|
16
16
|
'atem_model': 'ATEM 1 M/E Production Studio 4K' (str) or None,
|
|
17
17
|
'connection_status': bool,
|
|
18
|
+
'no_free_connection': True # only when the switcher answered "no room"
|
|
18
19
|
'error': str # only present on exception
|
|
19
20
|
}
|
|
20
21
|
"""
|
|
@@ -23,6 +24,7 @@ import logging
|
|
|
23
24
|
|
|
24
25
|
from atemwire.messages.system_info import product_name, video_mode
|
|
25
26
|
from atemwire.pool import acquire_connection
|
|
27
|
+
from atemwire.transport import NoFreeConnection
|
|
26
28
|
|
|
27
29
|
logger = logging.getLogger(__name__)
|
|
28
30
|
|
|
@@ -31,8 +33,10 @@ def probe(ip_address: str) -> dict:
|
|
|
31
33
|
"""Acquire a connection to an ATEM, read product-name + video-mode,
|
|
32
34
|
release.
|
|
33
35
|
|
|
34
|
-
Warm pool: ~0 ms. Cold
|
|
35
|
-
.
|
|
36
|
+
Warm pool: ~0 ms. Cold: the handshake and the state dump. Unreachable:
|
|
37
|
+
``atemwire.connection.CONNECT_STALL_TIMEOUT`` (5 s with nothing from the
|
|
38
|
+
switcher) before returning the failure dict. A switcher with every slot
|
|
39
|
+
taken answers "no room" at once: ``no_free_connection`` is True.
|
|
36
40
|
|
|
37
41
|
On timeout, and while a warm session is re-handshaking (its state is
|
|
38
42
|
empty until the new dump completes), the returned dict has
|
|
@@ -61,6 +65,9 @@ def probe(ip_address: str) -> dict:
|
|
|
61
65
|
result["video_format"] = vm.get('format') or None
|
|
62
66
|
return result
|
|
63
67
|
|
|
68
|
+
except NoFreeConnection:
|
|
69
|
+
# The switcher answered "no room": it is there, with every slot taken.
|
|
70
|
+
return {**result, "no_free_connection": True}
|
|
64
71
|
except RuntimeError:
|
|
65
72
|
# acquire_connection raises on connect timeout; return the standard
|
|
66
73
|
# failure dict (not the error-populated one — timeout is expected for
|