bmdwire 1.11.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 (94) hide show
  1. {bmdwire-1.11.0/bmdwire.egg-info → bmdwire-1.12.0}/PKG-INFO +2 -2
  2. {bmdwire-1.11.0 → bmdwire-1.12.0}/README.md +1 -1
  3. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/__init__.py +2 -0
  4. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/connection.py +47 -6
  5. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/docs/SURFACE.md +17 -3
  6. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/pool.py +7 -1
  7. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/probe.py +9 -2
  8. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/ready.py +21 -2
  9. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/transport.py +36 -0
  10. {bmdwire-1.11.0 → bmdwire-1.12.0/bmdwire.egg-info}/PKG-INFO +2 -2
  11. {bmdwire-1.11.0 → bmdwire-1.12.0}/pyproject.toml +1 -1
  12. {bmdwire-1.11.0 → bmdwire-1.12.0}/LICENSE +0 -0
  13. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/LICENSE +0 -0
  14. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/LICENSE-gpl3.txt +0 -0
  15. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/NOTICE +0 -0
  16. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/_socketqueue.py +0 -0
  17. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/_transfer.py +0 -0
  18. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/atem.py +0 -0
  19. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/docs/MACRO_FORMAT.md +0 -0
  20. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/docs/MEDIA_LOCK.md +0 -0
  21. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/docs/PROFILE_FORMAT.md +0 -0
  22. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/docs/PROFILE_SAVE_RESTORE.md +0 -0
  23. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/helpers.py +0 -0
  24. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/imaging.py +0 -0
  25. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/__init__.py +0 -0
  26. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/_helpers.py +0 -0
  27. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/_io.py +0 -0
  28. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/downstream_keyer.py +0 -0
  29. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/fairlight.py +0 -0
  30. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/flow.py +0 -0
  31. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/hyperdeck.py +0 -0
  32. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/media.py +0 -0
  33. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/switching.py +0 -0
  34. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/macrotransfer/upstream_keyer.py +0 -0
  35. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/mediaconvertmodule.c +0 -0
  36. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/__init__.py +0 -0
  37. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/_dsl.py +0 -0
  38. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/audio_legacy.py +0 -0
  39. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/camera_control.py +0 -0
  40. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/color_generator.py +0 -0
  41. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/downstream_keyer.py +0 -0
  42. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/fade_to_black.py +0 -0
  43. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/fairlight.py +0 -0
  44. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/file_transfer.py +0 -0
  45. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/hyperdeck.py +0 -0
  46. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/input_video.py +0 -0
  47. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/lock.py +0 -0
  48. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/macros.py +0 -0
  49. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/manual.py +0 -0
  50. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/media.py +0 -0
  51. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/meters.py +0 -0
  52. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/multiviewer.py +0 -0
  53. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/recording.py +0 -0
  54. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/streaming.py +0 -0
  55. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/supersource.py +0 -0
  56. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/switching.py +0 -0
  57. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/system_info.py +0 -0
  58. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/tally.py +0 -0
  59. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/transition.py +0 -0
  60. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/messages/upstream_keyer.py +0 -0
  61. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/profile/__init__.py +0 -0
  62. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/profile/_common.py +0 -0
  63. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/profile/_enums.py +0 -0
  64. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/profile/_xml.py +0 -0
  65. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/profile/apply.py +0 -0
  66. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/profile/options.py +0 -0
  67. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/profile/save.py +0 -0
  68. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/protocol.py +0 -0
  69. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/py.typed +0 -0
  70. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/state.py +0 -0
  71. {bmdwire-1.11.0 → bmdwire-1.12.0}/atemwire/testing.py +0 -0
  72. {bmdwire-1.11.0 → bmdwire-1.12.0}/bmdwire.egg-info/SOURCES.txt +0 -0
  73. {bmdwire-1.11.0 → bmdwire-1.12.0}/bmdwire.egg-info/dependency_links.txt +0 -0
  74. {bmdwire-1.11.0 → bmdwire-1.12.0}/bmdwire.egg-info/requires.txt +0 -0
  75. {bmdwire-1.11.0 → bmdwire-1.12.0}/bmdwire.egg-info/top_level.txt +0 -0
  76. {bmdwire-1.11.0 → bmdwire-1.12.0}/hyperdeckwire/LICENSE +0 -0
  77. {bmdwire-1.11.0 → bmdwire-1.12.0}/hyperdeckwire/__init__.py +0 -0
  78. {bmdwire-1.11.0 → bmdwire-1.12.0}/hyperdeckwire/client.py +0 -0
  79. {bmdwire-1.11.0 → bmdwire-1.12.0}/hyperdeckwire/setup.py +0 -0
  80. {bmdwire-1.11.0 → bmdwire-1.12.0}/hyperdeckwire/upload.py +0 -0
  81. {bmdwire-1.11.0 → bmdwire-1.12.0}/setup.cfg +0 -0
  82. {bmdwire-1.11.0 → bmdwire-1.12.0}/setup.py +0 -0
  83. {bmdwire-1.11.0 → bmdwire-1.12.0}/ultimattewire/LICENSE +0 -0
  84. {bmdwire-1.11.0 → bmdwire-1.12.0}/ultimattewire/__init__.py +0 -0
  85. {bmdwire-1.11.0 → bmdwire-1.12.0}/ultimattewire/_preamble.py +0 -0
  86. {bmdwire-1.11.0 → bmdwire-1.12.0}/ultimattewire/_protocol.py +0 -0
  87. {bmdwire-1.11.0 → bmdwire-1.12.0}/ultimattewire/network.py +0 -0
  88. {bmdwire-1.11.0 → bmdwire-1.12.0}/ultimattewire/profile/__init__.py +0 -0
  89. {bmdwire-1.11.0 → bmdwire-1.12.0}/ultimattewire/profile/_ranges.py +0 -0
  90. {bmdwire-1.11.0 → bmdwire-1.12.0}/ultimattewire/profile/archive.py +0 -0
  91. {bmdwire-1.11.0 → bmdwire-1.12.0}/ultimattewire/profile/restore.py +0 -0
  92. {bmdwire-1.11.0 → bmdwire-1.12.0}/videohubwire/LICENSE +0 -0
  93. {bmdwire-1.11.0 → bmdwire-1.12.0}/videohubwire/__init__.py +0 -0
  94. {bmdwire-1.11.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.11.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.11.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.11.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
  ]
@@ -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.
@@ -595,6 +627,7 @@ class ATEMConnection:
595
627
  self._stop_event.clear()
596
628
  self._ready_event.clear()
597
629
  self._connect_error = None
630
+ self._connect_refused = False
598
631
  self._handshake_done = False
599
632
  self._session_ready = False
600
633
  self._died_signalled = False
@@ -615,8 +648,8 @@ class ATEMConnection:
615
648
  )
616
649
  self._worker.start()
617
650
 
618
- if not self._ready_event.wait(timeout=CONNECT_TIMEOUT):
619
- 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"
620
653
  logger.warning(f"Instance {self.instance_id}: connect failed ({err})")
621
654
  self._disconnect_locked()
622
655
  return False
@@ -704,12 +737,20 @@ class ATEMConnection:
704
737
  try:
705
738
  wait_ready(
706
739
  self._protocol,
707
- timeout=CONNECT_TIMEOUT,
740
+ timeout=CONNECT_MAX,
741
+ stall_timeout=CONNECT_STALL_TIMEOUT,
708
742
  pump_interval=PUMP_INTERVAL,
709
743
  stop_event=self._stop_event,
710
744
  )
711
- except TimeoutError:
712
- 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})"
713
754
  logger.warning(f"Instance {self.instance_id}: {self._connect_error}")
714
755
  self._close_protocol()
715
756
  self._ready_event.set()
@@ -765,7 +765,7 @@ Profile enum tables (`profile/_enums.py`):
765
765
  |---|---|---|
766
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` |
767
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 |
768
- | 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 |
769
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` |
770
770
 
771
771
  Readiness and identity:
@@ -780,7 +780,10 @@ Readiness and identity:
780
780
  ### 4.2 Transport (UDP, `transport.py`)
781
781
 
782
782
  - The switcher is on UDP **9910**. The handshake is a SYN with `0x01` and session id `0x1337`; the
783
- 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
784
787
  adopted from the switcher. The handshake ACK is sent from `loop()`, so it needs pumping. Since
785
788
  `7e42caa`, a re-handshake drops packets carrying the replaced session's id, and while the SYN
786
789
  is out, anything but its reply (§5.4 item 16).
@@ -959,7 +962,8 @@ simulated switcher state beyond a 1080p50 `video-mode`.
959
962
  - `set_fairlight_eq_band` says `frequency_range` takes "0..3"; the wire values are the bitfield
960
963
  1/2/4/8.
961
964
  - `system_info` calls `TiRq` a keepalive; it is sent once.
962
- - `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).
963
967
  - `connection.py:726-734` says an abandoned lock lasts ~5 min; `MEDIA_LOCK.md` measured ~5 s.
964
968
  - `_io.py:123` lists an inbound `FTUA` in the upload flow; none is waited for or parsed.
965
969
  - The `upstream_keyer` DVE comment calls `rotation` "u16"; the field is i32.
@@ -1350,6 +1354,16 @@ fixed after 1.9.0 and still apply to it.
1350
1354
  *Fixed in `588a389`:* the conversion runs in pieces (the longest stall 6.9 ms) and
1351
1355
  `rle_decode` copies the literal runs whole (a 12 MB 4K test frame: 133 ms before, 18 ms
1352
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.
1353
1367
 
1354
1368
  ## Counts
1355
1369
 
@@ -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
@@ -18,6 +18,8 @@ import threading
18
18
  import time
19
19
  from typing import Optional
20
20
 
21
+ from atemwire.transport import NoFreeConnection
22
+
21
23
  logger = logging.getLogger(__name__)
22
24
 
23
25
 
@@ -33,6 +35,7 @@ def wait_ready(
33
35
  pump_interval: float = 0.01,
34
36
  extra_settle: float = 0.0,
35
37
  stop_event: Optional[threading.Event] = None,
38
+ stall_timeout: Optional[float] = None,
36
39
  ) -> dict:
37
40
  """Block until ``protocol`` has completed the ATEM's initial state dump.
38
41
 
@@ -50,9 +53,16 @@ def wait_ready(
50
53
  to busy-loop (the media pool watcher does this during connect).
51
54
  :param extra_settle: additional pumping seconds AFTER ready.
52
55
  :param stop_event: optional cancellation signal.
56
+ :param stall_timeout: give up once nothing has arrived from the switcher
57
+ for this long (no progress), however much of ``timeout`` is left. A
58
+ big state dump over a slow link keeps arriving and is waited for; a
59
+ switcher that went quiet is not. None: ``timeout`` alone.
53
60
 
54
61
  :returns: ``protocol.mixerstate`` on success.
55
- :raises TimeoutError: if not ready within ``timeout`` seconds.
62
+ :raises TimeoutError: if not ready within ``timeout`` seconds, or with
63
+ nothing from the switcher for ``stall_timeout``.
64
+ :raises NoFreeConnection: at once, if the switcher answered the hello
65
+ "no room" (0x03: its session table is full).
56
66
  :raises WaitAborted: if ``stop_event`` is set before ready.
57
67
  """
58
68
  # Fast path: initial state already dumped. ``protocol.connected`` is
@@ -75,7 +85,9 @@ def wait_ready(
75
85
  # connect attempt, and a leaked closure per attempt accumulates on
76
86
  # long-lived protocols (2026-07-06).
77
87
  try:
78
- deadline = time.monotonic() + timeout
88
+ started = time.monotonic()
89
+ deadline = started + timeout
90
+ transport = getattr(protocol, 'transport', None)
79
91
  while time.monotonic() < deadline:
80
92
  if stop_event is not None and stop_event.is_set():
81
93
  raise WaitAborted("stop_event set before ready")
@@ -83,6 +95,13 @@ def wait_ready(
83
95
  protocol.loop()
84
96
  except Exception as e:
85
97
  logger.debug("wait_ready: protocol.loop() error: %s", e)
98
+ if getattr(transport, 'refused', False) is True:
99
+ raise NoFreeConnection(getattr(transport, 'ip', None))
100
+ if stall_timeout is not None:
101
+ heard = max(started, getattr(transport, 'last_rx_monotonic', 0.0) or 0.0)
102
+ if time.monotonic() - heard > stall_timeout:
103
+ raise TimeoutError(
104
+ f"wait_ready: nothing from the switcher for {stall_timeout}s")
86
105
  if (
87
106
  (connected['flag'] or getattr(protocol, 'initialized', False))
88
107
  and 'video-mode' in protocol.mixerstate
@@ -280,6 +280,22 @@ class BaseProtocol:
280
280
  self.queue_callback(len(self.send_queue), len(p.data) - 4)
281
281
 
282
282
 
283
+ class NoFreeConnection(RuntimeError):
284
+ """The switcher answered our hello with 0x03 ("no room") instead of 0x02:
285
+ every client slot it has is taken (ATEM Software Control, panels, other
286
+ clients, or sessions abandoned without a goodbye). Raised at once by a
287
+ connect, instead of waiting out the connect timeout: retrying straight
288
+ away gets the same answer. A ``RuntimeError``, so callers that catch a
289
+ failed connect keep catching it."""
290
+
291
+ MESSAGE = ('no free connection on this switcher (ATEM Software Control, '
292
+ 'panels or other clients are using all its slots)')
293
+
294
+ def __init__(self, ip=None):
295
+ self.ip = ip
296
+ super().__init__(f'ATEM {ip}: {self.MESSAGE}' if ip else self.MESSAGE)
297
+
298
+
283
299
  class UdpProtocol(BaseProtocol):
284
300
  STATE_CLOSED = 0
285
301
  STATE_SYN_SENT = 1
@@ -426,6 +442,8 @@ class UdpProtocol(BaseProtocol):
426
442
 
427
443
  self.enable_ack = False
428
444
  self.had_traffic = False
445
+ # The switcher answered the hello 0x03, "no room" (NoFreeConnection).
446
+ self.refused = False
429
447
 
430
448
  self.received_packets = _SeenWindow(1024)
431
449
  # While the UDP thread drains a burst (_drain_socket), the ACK the
@@ -1105,6 +1123,14 @@ class UdpProtocol(BaseProtocol):
1105
1123
 
1106
1124
  self.log.debug('Got response 0x{:02X} to handshake'.format(response_code))
1107
1125
 
1126
+ if response_code == 0x03:
1127
+ # "No room": the switcher's session table is full. Nothing to
1128
+ # ACK; whoever waits on this connect sees ``refused`` and stops
1129
+ # (NoFreeConnection) instead of re-SYNing until its timeout.
1130
+ self.refused = True
1131
+ self.log.warning(f'{self.ip}: {NoFreeConnection.MESSAGE}')
1132
+ return
1133
+
1108
1134
  if response_code == 0x02:
1109
1135
  self.state = UdpProtocol.STATE_ESTABLISHED
1110
1136
 
@@ -1163,6 +1189,7 @@ class UdpProtocol(BaseProtocol):
1163
1189
  # the next full reconnect. Clear it and the traffic flag.
1164
1190
  self.received_packets.clear()
1165
1191
  self.had_traffic = False
1192
+ self.refused = False
1166
1193
  # A fresh SYN gets a full silence window.
1167
1194
  self._last_heard = time.monotonic()
1168
1195
 
@@ -1200,6 +1227,10 @@ class UdpProtocol(BaseProtocol):
1200
1227
  # hung upload processes + orphaned worker threads
1201
1228
  # (2026-07-06).
1202
1229
  return None
1230
+ if packet is None and self.state == UdpProtocol.STATE_SYN_SENT and self.refused:
1231
+ # Answered "no room": asking again straight away gets the
1232
+ # same answer. The caller decides (NoFreeConnection).
1233
+ return None
1203
1234
  if packet is None and self.state == UdpProtocol.STATE_SYN_SENT:
1204
1235
  # No response in connect, retry connection
1205
1236
  self.state = UdpProtocol.STATE_CLOSED
@@ -1240,6 +1271,11 @@ class UdpProtocol(BaseProtocol):
1240
1271
  # Got response for the first handshake packet
1241
1272
  self.had_traffic = True
1242
1273
  self._handshake(packet)
1274
+ if self.refused:
1275
+ # Return now, so whoever pumps sees ``refused`` (it
1276
+ # would otherwise wait for the next 5 s tick, which
1277
+ # re-SYNs and forgets the answer).
1278
+ return None
1243
1279
  elif self.state == UdpProtocol.STATE_ESTABLISHED:
1244
1280
  if packet.length == 12:
1245
1281
  # This is a control packet, deal with it in the transport layer
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: bmdwire
3
- Version: 1.11.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.11.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
 
@@ -13,7 +13,7 @@ build-backend = "setuptools.build_meta"
13
13
 
14
14
  [project]
15
15
  name = "bmdwire"
16
- version = "1.11.0"
16
+ version = "1.12.0"
17
17
  description = "Python libraries for Blackmagic Design broadcast devices: ATEM switchers, HyperDeck recorders, Ultimatte keyers and Videohub routers"
18
18
  readme = "README.md"
19
19
  # atemwire is a fork of pyatem and stays LGPL-3.0-only; the other three were
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes