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.
Files changed (95) hide show
  1. {bmdwire-1.10.0/bmdwire.egg-info → bmdwire-1.12.0}/PKG-INFO +2 -2
  2. {bmdwire-1.10.0 → bmdwire-1.12.0}/README.md +1 -1
  3. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/__init__.py +2 -0
  4. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/_socketqueue.py +10 -0
  5. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/connection.py +98 -17
  6. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/SURFACE.md +73 -11
  7. bmdwire-1.12.0/atemwire/imaging.py +75 -0
  8. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/pool.py +7 -1
  9. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/probe.py +9 -2
  10. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/protocol.py +168 -28
  11. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/ready.py +21 -2
  12. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/transport.py +191 -23
  13. {bmdwire-1.10.0 → bmdwire-1.12.0/bmdwire.egg-info}/PKG-INFO +2 -2
  14. {bmdwire-1.10.0 → bmdwire-1.12.0}/pyproject.toml +1 -1
  15. bmdwire-1.10.0/atemwire/imaging.py +0 -60
  16. {bmdwire-1.10.0 → bmdwire-1.12.0}/LICENSE +0 -0
  17. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/LICENSE +0 -0
  18. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/LICENSE-gpl3.txt +0 -0
  19. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/NOTICE +0 -0
  20. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/_transfer.py +0 -0
  21. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/atem.py +0 -0
  22. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/MACRO_FORMAT.md +0 -0
  23. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/MEDIA_LOCK.md +0 -0
  24. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/PROFILE_FORMAT.md +0 -0
  25. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/docs/PROFILE_SAVE_RESTORE.md +0 -0
  26. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/helpers.py +0 -0
  27. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/__init__.py +0 -0
  28. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/_helpers.py +0 -0
  29. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/_io.py +0 -0
  30. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/downstream_keyer.py +0 -0
  31. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/fairlight.py +0 -0
  32. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/flow.py +0 -0
  33. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/hyperdeck.py +0 -0
  34. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/media.py +0 -0
  35. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/switching.py +0 -0
  36. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/macrotransfer/upstream_keyer.py +0 -0
  37. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/mediaconvertmodule.c +0 -0
  38. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/__init__.py +0 -0
  39. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/_dsl.py +0 -0
  40. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/audio_legacy.py +0 -0
  41. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/camera_control.py +0 -0
  42. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/color_generator.py +0 -0
  43. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/downstream_keyer.py +0 -0
  44. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/fade_to_black.py +0 -0
  45. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/fairlight.py +0 -0
  46. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/file_transfer.py +0 -0
  47. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/hyperdeck.py +0 -0
  48. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/input_video.py +0 -0
  49. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/lock.py +0 -0
  50. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/macros.py +0 -0
  51. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/manual.py +0 -0
  52. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/media.py +0 -0
  53. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/meters.py +0 -0
  54. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/multiviewer.py +0 -0
  55. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/recording.py +0 -0
  56. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/streaming.py +0 -0
  57. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/supersource.py +0 -0
  58. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/switching.py +0 -0
  59. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/system_info.py +0 -0
  60. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/tally.py +0 -0
  61. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/transition.py +0 -0
  62. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/messages/upstream_keyer.py +0 -0
  63. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/__init__.py +0 -0
  64. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/_common.py +0 -0
  65. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/_enums.py +0 -0
  66. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/_xml.py +0 -0
  67. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/apply.py +0 -0
  68. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/options.py +0 -0
  69. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/profile/save.py +0 -0
  70. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/py.typed +0 -0
  71. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/state.py +0 -0
  72. {bmdwire-1.10.0 → bmdwire-1.12.0}/atemwire/testing.py +0 -0
  73. {bmdwire-1.10.0 → bmdwire-1.12.0}/bmdwire.egg-info/SOURCES.txt +0 -0
  74. {bmdwire-1.10.0 → bmdwire-1.12.0}/bmdwire.egg-info/dependency_links.txt +0 -0
  75. {bmdwire-1.10.0 → bmdwire-1.12.0}/bmdwire.egg-info/requires.txt +0 -0
  76. {bmdwire-1.10.0 → bmdwire-1.12.0}/bmdwire.egg-info/top_level.txt +0 -0
  77. {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/LICENSE +0 -0
  78. {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/__init__.py +0 -0
  79. {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/client.py +0 -0
  80. {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/setup.py +0 -0
  81. {bmdwire-1.10.0 → bmdwire-1.12.0}/hyperdeckwire/upload.py +0 -0
  82. {bmdwire-1.10.0 → bmdwire-1.12.0}/setup.cfg +0 -0
  83. {bmdwire-1.10.0 → bmdwire-1.12.0}/setup.py +0 -0
  84. {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/LICENSE +0 -0
  85. {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/__init__.py +0 -0
  86. {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/_preamble.py +0 -0
  87. {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/_protocol.py +0 -0
  88. {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/network.py +0 -0
  89. {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/profile/__init__.py +0 -0
  90. {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/profile/_ranges.py +0 -0
  91. {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/profile/archive.py +0 -0
  92. {bmdwire-1.10.0 → bmdwire-1.12.0}/ultimattewire/profile/restore.py +0 -0
  93. {bmdwire-1.10.0 → bmdwire-1.12.0}/videohubwire/LICENSE +0 -0
  94. {bmdwire-1.10.0 → bmdwire-1.12.0}/videohubwire/__init__.py +0 -0
  95. {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.10.0
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.10.0`) so a later release cannot change your install under you.
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.10.0`) so a later release cannot change your install under you.
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) -> bytes:
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) -> bytes:
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 (progress_callback is not None
404
- and store_id == store and slot_idx == index):
405
- try:
406
- progress_callback(fraction)
407
- except Exception:
408
- pass
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
- done.wait(timeout)
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=CONNECT_TIMEOUT):
579
- err = self._connect_error or f"timeout after {CONNECT_TIMEOUT}s"
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=CONNECT_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 TimeoutError:
672
- self._connect_error = f"initial state timeout ({CONNECT_TIMEOUT}s)"
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) work on 8-byte
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` (blocks up to `CONNECT_TIMEOUT = 15 s`; 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`. 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 |
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) and the client ACKs it. The session id is then
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
- - Duplicates are dropped. Out-of-order packets are parked (up to 512 ahead). Retransmission is
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
- - `probe.py` / `__init__.py` say a cold connect costs ~6 s; `CONNECT_TIMEOUT` is 15 s.
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
- within the connection's configured timeout. A pooled session that
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 / unreachable: pays ``atemwire.connection
35
- .CONNECT_TIMEOUT`` (~6 s) before returning the failure dict.
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