mx-remote 5.7.0__tar.gz → 5.9.0__tar.gz

{mx_remote-5.7.0 → mx_remote-5.9.0}/AGENTS.md

@@ -85,6 +85,21 @@ Version is single-sourced in `mx_remote/const.py` (`VERSION = '...'`); `pyprojec
 reads it via regex, so bump it there only. Release commits follow the convention
 `bump to X.Y.Z`.
 
+### Releases
+`.github/workflows/release.yml` builds and uploads, so a release needs no local
+build and no PyPI credentials:
+
+```sh
+# after the `bump to X.Y.Z` commit is pushed
+git tag -a vX.Y.Z -m 'mx-remote X.Y.Z' && git push origin vX.Y.Z
+gh release create vX.Y.Z --title 'mx-remote X.Y.Z' --verify-tag --notes '...'
+```
+
+Publishing the release runs the suites against the tag, builds the wheel and
+sdist, uploads them to PyPI over Trusted Publishing, and attaches them to the
+release page. Notes stay hand-written: a one-line summary, `##` sections, and a
+closing `**Full Changelog**:` compare link.
+
 ### Build hook
 `hatch_build.py` generates `.pyi` type stubs via `mypy stubgen` at build time and
 force-includes them in the wheel (they are gitignored). `mx_remote` ships as typed
@@ -198,6 +213,24 @@ selector. A payload can widen without its floor moving, and then the stamp says
 nothing about which layout arrived — dispatch on payload length instead.
 `tests/wirefix.py` covers the cases where the two come apart.
 
+A row can also go down, which turns a version test into a silent drop. Rows are
+not monotonic: one is lowered to bring a family back under a product's receive
+cap, with no layout changing. A test added while a row was high then rejects
+every frame on that opcode from every sender at once, and what it guards simply
+stops being reported. So prefer the length, which no stamp change can
+invalidate.
+
+Two decoders read the stamp, and each says in place what it rests on. The mesh
+operation gate: that struct is fixed size and what changed is what its bytes
+mean, so no length distinguishes the forms. The network status layout selector:
+the forms are the same length, so the stamp chooses between them rather than
+admitting one, and getting it wrong yields a complete, plausible, wrong port
+status rather than a lost frame.
+
+A fixture stamped at a version no device sends is a frame that exists nowhere
+else, and every assertion about it says nothing about the network. Stamp what a
+device stamps, which for a report is the opcode's own row.
+
 ## Writing down a deliberate divergence
 
 A note recording *what the firmware does* reads as *what this library should

{mx_remote-5.7.0 → mx_remote-5.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mx_remote
-Version: 5.7.0
+Version: 5.9.0
 Summary: Python 3 library for interfacing with MX Remote compatible devices
 Project-URL: Homepage, https://github.com/opdenkamp/mx-remote/
 Project-URL: Documentation, https://opdenkamp.github.io/mx-remote/

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/Interface.py

@@ -1384,10 +1384,12 @@ class DeviceV2IPScalingSettings(ABC):
     def flags(self) -> int:
         '''mxr_scaling_config.flags.
 
-        MXR_SCALING_FLAG_MODE_VALID and MXR_SCALING_FLAG_OPTIONS_VALID mark
-        which half a sender meant to send, and are separately valid; a sender
-        setting neither is offering no scaling at all. MXR_SCALING_FLAG_AUTO_SCALING
-        is the only option bit with a defined meaning.
+        MXR_SCALING_FLAG_MODE_VALID, MXR_SCALING_FLAG_OPTIONS_VALID and
+        MXR_SCALING_FLAG_OPTIONS2_VALID mark which part a sender meant to send,
+        and are separately valid; a sender setting none of them is offering no
+        scaling at all. MXR_SCALING_FLAG_AUTO_SCALING sits behind the first
+        marker, MXR_SCALING_FLAG_MATCH_SOURCE and MXR_SCALING_FLAG_SKIP_420
+        behind the second.
         '''
 
     @property
@@ -1412,6 +1414,37 @@ class DeviceV2IPScalingSettings(ABC):
             return None
         return ((self.flags & MXR_SCALING_FLAG_AUTO_SCALING) != 0)
 
+    @property
+    def match_source(self) -> bool|None:
+        '''Whether the output follows its source's format, None when the device
+        has never said.
+
+        Firmware with this option announces it on every configuration it sends
+        about itself, so a device that has reported it once is known to have it.
+        The cached block accumulates its validity bit, so a later write carrying
+        only the first options group does not take that back.
+
+        Reported only from a sender announcing DeviceBase.config_initialised,
+        which is why this needs no caveat of its own: no firmware has these
+        options without that announcement, and one that lacks it would be
+        reporting uninitialised stack. That is the difference from
+        configured_mode, which is reported from any sender because a mode can be
+        genuine on one of those.
+        '''
+        if ((self.flags & MXR_SCALING_FLAG_OPTIONS2_VALID) == 0):
+            return None
+        return ((self.flags & MXR_SCALING_FLAG_MATCH_SOURCE) != 0)
+
+    @property
+    def skip_420(self) -> bool|None:
+        '''Whether the output declines 4:2:0 rather than scaling it, None when
+        the device has never said. Reported on the same terms as match_source,
+        which shares its validity bit.
+        '''
+        if ((self.flags & MXR_SCALING_FLAG_OPTIONS2_VALID) == 0):
+            return None
+        return ((self.flags & MXR_SCALING_FLAG_SKIP_420) != 0)
+
 def v2ip_stream_valid(stream:'V2IPStreamSource|None') -> bool:
     """
     True when a stream source carries an address a frame actually meant to send.
@@ -1677,33 +1710,39 @@ class DeviceV2IPDetails:
         """
         Merge a scaling config field by field, the way firmware applies it.
 
-        The mode/refresh pair and the options nibble are separately valid, so a
-        write carrying only one of them must leave the other as it was.
+        The mode/refresh pair and the two options groups are separately valid,
+        so a write carrying one of them must leave the others as they were. Each
+        group is replaced whole behind its own marker, which is what keeps the
+        marker itself - and so the knowledge that the device has those options -
+        from being taken back by a later write that carries another group.
         """
         incoming = self._scaling
         if (incoming is None) or (previous is None):
             return incoming if (incoming is not None) else previous
         mode_valid = ((incoming.flags & MXR_SCALING_FLAG_MODE_VALID) != 0)
         options_valid = ((incoming.flags & MXR_SCALING_FLAG_OPTIONS_VALID) != 0)
-        if not mode_valid and not options_valid:
+        options2_valid = ((incoming.flags & MXR_SCALING_FLAG_OPTIONS2_VALID) != 0)
+        if not mode_valid and not options_valid and not options2_valid:
             # carries no scaling at all
             return previous
-        if mode_valid and options_valid:
-            return incoming
         mode = incoming.mode if mode_valid else previous.mode
         refresh = incoming.refresh if mode_valid else previous.refresh
         flags = previous.flags
         if mode_valid:
             flags |= MXR_SCALING_FLAG_MODE_VALID
-        else:
-            # Options only. Carry AUTO_SCALING alone rather than the whole upper
-            # nibble: bits 4..6 have no defined meaning, and on a receiver-capable
-            # unit running firmware before the scaling-config initialisation fix
-            # they are stack noise - the sender declares mxr_scaling_config
-            # uninitialised and only ever |= flags onto it. Masking to the bit we
-            # mean cannot lose information even on fixed firmware, and stops the
-            # noise at this boundary instead of caching it as a peer's config.
-            flags = (flags & 0x0F) | MXR_SCALING_FLAG_OPTIONS_VALID                     | (incoming.flags & MXR_SCALING_FLAG_AUTO_SCALING)
+        if options_valid:
+            # Replace AUTO_SCALING alone rather than the whole upper nibble: on a
+            # receiver-capable unit running firmware that leaves mxr_scaling_config
+            # uninitialised, every other bit up there is stack noise the sender
+            # only ever |= its flags onto, and the settings behind the second
+            # marker are a group of their own that this write does not speak for.
+            flags = (flags & ~MXR_SCALING_FLAG_AUTO_SCALING) | MXR_SCALING_FLAG_OPTIONS_VALID \
+                    | (incoming.flags & MXR_SCALING_FLAG_AUTO_SCALING)
+        if options2_valid:
+            flags = (flags & ~MXR_SCALING_OPTIONS2_SETTINGS) | MXR_SCALING_FLAG_OPTIONS2_VALID \
+                    | (incoming.flags & MXR_SCALING_OPTIONS2_SETTINGS)
+        if (mode == incoming.mode) and (refresh == incoming.refresh) and (flags == incoming.flags):
+            return incoming
         return V2IPScalingSettings(mode=mode, refresh=refresh, flags=flags)
 
 class DeviceV2IPSink:
@@ -2031,6 +2070,17 @@ class DeviceBase(ABC):
     def temperatures(self) -> dict[str,int]:
         ''' temperature sensor reports '''
 
+    @property
+    @abstractmethod
+    def v2ip_features(self) -> 'V2IPFpgaFeature|None':
+        '''What this device's video processor supports, None until it has said.
+
+        A device reports the mask only on a configuration it sends about itself,
+        and reports nothing at all until its processor has answered - which
+        looks the same on the wire as a processor without any of the optional
+        commands, so neither is read as a capability set.
+        '''
+
     @property
     @abstractmethod
     def v2ip_sources(self) -> V2IPStreamSourcesList|None:
@@ -2221,8 +2271,16 @@ class DeviceBase(ABC):
         '''system health status'''
 
     @abstractmethod
-    def on_link_config_received(self) -> None:
-        '''internal callback'''
+    def merge_v2ip_sources(self, first:int, total:int, page:'V2IPStreamSourcesList') -> None:
+        '''merge one frame of this device's V2IP source list into the cached list'''
+
+    @abstractmethod
+    def note_link_record(self, port:int) -> None:
+        '''internal callback: the bay on this port reported its link record'''
+
+    @abstractmethod
+    def note_bay_config(self) -> None:
+        '''internal callback: the primary bay configuration was received'''
 
     @abstractmethod
     async def get_api(self, uri:str) -> dict[str, Any]|None:

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/Interface.pyi

@@ -586,6 +586,10 @@ class DeviceV2IPScalingSettings(ABC):
     def configured_mode(self) -> tuple[MxrSignalType, int] | None: ...
     @property
     def auto_scaling(self) -> bool | None: ...
+    @property
+    def match_source(self) -> bool | None: ...
+    @property
+    def skip_420(self) -> bool | None: ...
 
 def v2ip_stream_valid(stream: V2IPStreamSource | None) -> bool: ...
 def v2ip_av_source_valid(video: V2IPStreamSource | None, anc: V2IPStreamSource | None) -> bool: ...
@@ -819,6 +823,9 @@ class DeviceBase(ABC):
     def temperatures(self) -> dict[str, int]: ...
     @property
     @abstractmethod
+    def v2ip_features(self) -> V2IPFpgaFeature | None: ...
+    @property
+    @abstractmethod
     def v2ip_sources(self) -> V2IPStreamSourcesList | None: ...
     @property
     @abstractmethod
@@ -907,7 +914,11 @@ class DeviceBase(ABC):
     @abstractmethod
     def status_message(self) -> str: ...
     @abstractmethod
-    def on_link_config_received(self) -> None: ...
+    def merge_v2ip_sources(self, first: int, total: int, page: V2IPStreamSourcesList) -> None: ...
+    @abstractmethod
+    def note_link_record(self, port: int) -> None: ...
+    @abstractmethod
+    def note_bay_config(self) -> None: ...
     @abstractmethod
     async def get_api(self, uri: str) -> dict[str, Any] | None: ...
     @abstractmethod

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/const.py

@@ -14,7 +14,7 @@ Default communication modes:
 """
 import os
 
-VERSION = '5.7.0'
+VERSION = '5.9.0'
 __version__ = VERSION
 
 MX_BCAST_UDP_PORT = 8811

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/proto/Constants.py

@@ -140,11 +140,22 @@ def v2ip_rate_valid(rate:int|None) -> bool:
     '''True when a tx_rate carries an actual rate (firmware v2ip_source_rate_valid()).'''
     return (rate is not None) and (V2IP_SOURCE_RATE_MIN <= rate <= V2IP_SOURCE_RATE_MAX)
 
-MXR_SCALING_FLAG_MODE_VALID    = (1 << 0)
-MXR_SCALING_FLAG_OPTIONS_VALID = (1 << 1)
-MXR_SCALING_FLAG_AUTO_SCALING  = (1 << 7)
-"""mxr_scaling_config.flags. The mode/refresh pair and the options nibble are
-separately valid: a sender carrying neither flag is offering no scaling at all."""
+MXR_SCALING_FLAG_MODE_VALID     = (1 << 0)
+MXR_SCALING_FLAG_OPTIONS_VALID  = (1 << 1)
+MXR_SCALING_FLAG_OPTIONS2_VALID = (1 << 4)
+MXR_SCALING_FLAG_MATCH_SOURCE   = (1 << 5)
+MXR_SCALING_FLAG_SKIP_420       = (1 << 6)
+MXR_SCALING_FLAG_AUTO_SCALING   = (1 << 7)
+"""mxr_scaling_config.flags. The mode/refresh pair and each options group are
+separately valid: a sender carrying none of the three markers is offering no
+scaling at all.
+
+Firmware that has the second group sets its marker on every configuration it
+sends about itself, so that bit doubles as the report that the device has those
+options at all. Bits 2 and 3 have no meaning."""
+
+MXR_SCALING_OPTIONS2_SETTINGS = (MXR_SCALING_FLAG_MATCH_SOURCE | MXR_SCALING_FLAG_SKIP_420)
+"""The settings behind MXR_SCALING_FLAG_OPTIONS2_VALID, which carries both."""
 
 V2IP_SCALING_REFRESH_MIN = 24
 V2IP_SCALING_REFRESH_MAX = 120
@@ -221,6 +232,32 @@ class DeviceFeature(IntFlag):
 	CONFIG_INITIALISED = (1 << 25)
 	BOOT_BIT           = (1 << 31)
 
+class V2IPFpgaFeature(IntFlag):
+	'''What a V2IP device's video processor supports, as the device reports it in
+	its configuration.
+
+	Read-only, and a device's own: it fills the field in only on the frame
+	describing itself, and leaves it zero on one it sends to configure another
+	device. There is no write path.
+
+	Bits are assigned by the video processor and only ever appended, so a bit
+	this library has no name for is a later capability rather than an error. A
+	device reports no features at all until its processor answers, and an older
+	processor answers with none of the optional commands, so an empty mask is
+	never a capability set.'''
+	SOURCE_DSCP        = (1 << 0)
+	'''Applies a DSCP marking to the streams it sources.'''
+	SINK_AUDIO_FORMAT  = (1 << 1)
+	'''Reports the audio format arriving at its sink.'''
+	SINK_TILING_WINDOW = (1 << 2)
+	'''Places a tiling window on its sink.'''
+	SINK_OVERLAY_STATE = (1 << 3)
+	'''Reports the state of its sink's overlay.'''
+	SINK_STATE         = (1 << 4)
+	'''Reports its sink's state.'''
+	SINK_STREAM_INFO   = (1 << 5)
+	'''Reports information about the stream its sink receives.'''
+
 BAY_FEATURE_DOLBY_IN_POS = 24
 
 class BayFeaturesMask(IntFlag):

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/proto/Constants.pyi

@@ -17,7 +17,11 @@ def v2ip_rate_valid(rate: int | None) -> bool: ...
 
 MXR_SCALING_FLAG_MODE_VALID: Incomplete
 MXR_SCALING_FLAG_OPTIONS_VALID: Incomplete
+MXR_SCALING_FLAG_OPTIONS2_VALID: Incomplete
+MXR_SCALING_FLAG_MATCH_SOURCE: Incomplete
+MXR_SCALING_FLAG_SKIP_420: Incomplete
 MXR_SCALING_FLAG_AUTO_SCALING: Incomplete
+MXR_SCALING_OPTIONS2_SETTINGS = MXR_SCALING_FLAG_MATCH_SOURCE | MXR_SCALING_FLAG_SKIP_420
 V2IP_SCALING_REFRESH_MIN: int
 V2IP_SCALING_REFRESH_MAX: int
 MXR_V2IP_DSCP_SET: int
@@ -56,6 +60,14 @@ class DeviceFeature(IntFlag):
     CONFIG_INITIALISED: Incomplete
     BOOT_BIT: Incomplete
 
+class V2IPFpgaFeature(IntFlag):
+    SOURCE_DSCP: Incomplete
+    SINK_AUDIO_FORMAT: Incomplete
+    SINK_TILING_WINDOW: Incomplete
+    SINK_OVERLAY_STATE: Incomplete
+    SINK_STATE: Incomplete
+    SINK_STREAM_INFO: Incomplete
+
 BAY_FEATURE_DOLBY_IN_POS: int
 
 class BayFeaturesMask(IntFlag):

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/proto/FrameBayConfig.py

@@ -49,6 +49,7 @@ class FrameBayConfig(FrameBase):
         for bayconfig in self.bays:
             _LOGGER.debug(f"process {bayconfig}")
             dev.on_mxr_update(bayconfig)
+        dev.note_bay_config()
 
     def __str__(self) -> str:
         return f"{self.remote_device} bay config page: {len(self.bays)} bays"

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/proto/FrameLinks.py

@@ -44,7 +44,11 @@ class FrameLinks(FrameBase):
             return
         for link in self.links:
             link.process()
-        dev.on_link_config_received()
+            # Only a record that landed on a known bay counts. One naming a bay
+            # this client has not seen is dropped rather than held, which is
+            # what a device does with the same frame, and the device re-sends.
+            if (link.remote_bay is not None):
+                dev.note_link_record(link.remote_port)
 
     def __str__(self) -> str:
         return f"{self.remote_device} links config page: {len(self.links)} links"

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/proto/FrameRCIr.py

@@ -27,15 +27,48 @@ _LOGGER = logging.getLogger(__name__)
 _META_OFFSET = 12
 _TIMINGS_OFFSET = 24
 
-# A receiver requires one timing beyond the struct, not just the struct, and it
-# requires this protocol version. Both are the firmware's own gates. The length
-# one reads like an off-by-one and is not: a capture with no timing is a burst
-# nothing blasted, with nothing in it to replay, and it decodes perfectly.
+# A receiver requires one timing beyond the struct, not just the struct, which
+# is the firmware's own gate. It reads like an off-by-one and is not: a capture
+# with no timing is a burst nothing blasted, with nothing in it to replay, and
+# it decodes perfectly.
 _MIN_SIZE = _TIMINGS_OFFSET + 2
-_ACCEPT_PROTOCOL = 0x19
+
+# Two timing widths exist on the wire, and the header counts timings rather than
+# bytes, so what follows the header is what says which arrived: the same count
+# takes twice the room in the wider form, and a narrow list is exactly as long
+# as its count, so it can never be mistaken for a wide one.
+_TIMING_WIDE = 2
+_TIMING_NARROW = 1
 
 class FrameRCIr(FrameBase):
     '''IR key press event received by a bay.'''
+    @cached_property
+    def timing_width(self) -> int|None:
+        '''Bytes per timing as this sender wrote them, None when the frame is
+        not a capture this library will read.
+
+        Tested widest first, which is what separates the two forms: a narrow
+        list is exactly as long as its count, so a wide one is never read as a
+        narrow one carrying twice as many.
+
+        The count is a declaration, not a measurement: nothing on the wire ties
+        it to the number of timings that arrived. A frame short of its own count
+        at either width is refused rather than handed to a caller that would
+        index the timings by it.
+        '''
+        pl = self.payload
+        if (pl is None) or (len(pl) < _MIN_SIZE):
+            return None
+        nb = self.payload_u16(idx=_META_OFFSET + 4)
+        if (nb is None):
+            return None
+        tail = len(pl) - _TIMINGS_OFFSET
+        if (tail >= (nb * _TIMING_WIDE)):
+            return _TIMING_WIDE
+        if (tail >= (nb * _TIMING_NARROW)):
+            return _TIMING_NARROW
+        return None
+
     @cached_property
     def acceptable(self) -> bool:
         '''Whether a receiver would act on this frame at all.
@@ -43,16 +76,7 @@ class FrameRCIr(FrameBase):
         Every field below reads None or empty when this is False, so a frame no
         device blasted cannot be mistaken for a capture with nothing in it.
         '''
-        pl = self.payload
-        if (pl is None) or (len(pl) < _MIN_SIZE):
-            return False
-        # The count is a declaration, not a measurement: nothing on the wire
-        # ties it to the number of timings that arrived. A frame claiming more
-        # than it carries is refused rather than handed to a caller that would
-        # index the timings by it.
-        nb = self.payload_u16(idx=_META_OFFSET + 4)
-        return (nb is not None) and (nb <= ((len(pl) - _TIMINGS_OFFSET) // 2)) \
-            and (self.protocol >= _ACCEPT_PROTOCOL)
+        return (self.timing_width is not None)
 
     @cached_property
     def bay(self) -> BayBase|None:
@@ -112,14 +136,19 @@ class FrameRCIr(FrameBase):
 
     @cached_property
     def timings(self) -> bytes:
-        '''Raw on/off timings appended after the struct.
+        '''On/off timings appended after the struct, two bytes each.
+
+        Always that width, whichever the sender used: the narrower form older
+        devices send is widened here, so the values are the device's and only
+        the encoding is this library's. nb_timings counts the timings, so this
+        is twice that long.
 
         A receiver drops the first timing and blasts from the second, so this
         list is one longer than what is emitted. The first is discarded
         outright, not treated as a leading gap: the interval before the burst
         comes from the sender's timestamp instead.
 
-        The targeted transmit request (0x48) carries its timings the same way,
+        The targeted transmit request (0x48) carries its timings at this width,
         so a capture replays by passing this across byte for byte, with the
         declared count unchanged and the discarded first slot included. Its
         header is a different struct and must be rebuilt, and its timestamp has
@@ -130,11 +159,18 @@ class FrameRCIr(FrameBase):
         receiver applies its own tick length rather than the resolution
         reported beside them.
         '''
-        if not self.acceptable:
+        width = self.timing_width
+        nb = self.nb_timings
+        if (width is None) or (nb is None):
             return bytes()
-        if ((pl := self.payload_idx(_TIMINGS_OFFSET)) is None):
+        # Bounded by the timings the header counts, so a field appended behind
+        # the list does not arrive as extra timings.
+        pl = self.payload_idx(start=_TIMINGS_OFFSET, end=(_TIMINGS_OFFSET + (nb * width)))
+        if (pl is None):
             return bytes()
-        return pl
+        if (width == _TIMING_WIDE):
+            return pl
+        return bytes([b for timing in pl for b in (timing, 0)])
 
     def __str__(self) -> str:
         return f"IR key press bay {self.bay} at {self.ir_timestamp} freq {self.frequency} timings {self.nb_timings}"

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/proto/FrameRCIr.pyi

@@ -3,6 +3,8 @@ from .FrameBase import FrameBase as FrameBase
 from functools import cached_property
 
 class FrameRCIr(FrameBase):
+    @cached_property
+    def timing_width(self) -> int | None: ...
     @cached_property
     def acceptable(self) -> bool: ...
     @cached_property

{mx_remote-5.7.0 → mx_remote-5.9.0}/mx_remote/proto/FrameSignalStatusNew.py

@@ -163,7 +163,25 @@ class FrameSignalStatusNew(FrameBase):
     attributed to a bay and is dropped.
 
     An empty payload requests a report from every device; a 16-byte payload
-    requests one from the unit it addresses. '''
+    requests one from the unit it addresses.
+
+    **On a decoder's output bay the signal description is a snapshot of the
+    routed source, taken when that stream last started.** Nothing refreshes it
+    while the route holds, so a source that changes format in place leaves
+    video, audio, infoframe and vsync all reading the format from before the
+    change - worse than an unfilled field, because the value stays plausible.
+    Re-routing the bay resamples them, unless the newly selected source's record
+    has not arrived yet, which leaves the previous values standing rather than
+    clearing them.
+
+    bay_status and scaling are re-stamped on every scaling change as well, so
+    they can be newer than the description beside them. clock_rate sits with
+    them but is computed from the snapshot and carries its age.
+
+    **For a decoder's current input format, read the input bay it is routed
+    to.** That record is refreshed by the source's own reports, and it is the
+    reason a decoder's own output bay can disagree with the picture on the
+    cable. '''
     @cached_property
     def signal_header_version(self) -> int:
         if ((pl := self.payload_u16(0)) is not None):
@@ -236,7 +254,8 @@ class FrameSignalStatusNew(FrameBase):
 
     @cached_property
     def scaling(self) -> MxrSignalType|None:
-        '''Signal type the bay is scaling to, or None on a short report.'''
+        '''Format the bay is scaling to, unset while it is not scaling, or None
+        on a short report.'''
         details = self.bay_details
         if len(details) < 8:
             return None
@@ -244,7 +263,11 @@ class FrameSignalStatusNew(FrameBase):
 
     @cached_property
     def clock_rate(self) -> int|None:
-        '''Video clock rate in Hz, or None on a short report.'''
+        '''Video clock rate in Hz, or None on a short report.
+
+        Computed rather than measured: the pixel clock of scaling while the bay
+        scales, and otherwise the signal description's own, halved for 4:2:0 and
+        scaled by colour depth.'''
         details = self.bay_details
         if len(details) < 12:
             return None