API reference

Generated from the docstrings in the package. The guides cover how these fit together; this page is the exhaustive list.

Autodoc emits reStructuredText, which the markdown parser does not read, so every directive below sits in an eval-rst block. Without it the page renders the directive source as prose and the build still succeeds.

mx_remote - Python 3 library for interfacing with MX Remote compatible devices.

Provides device discovery, video/audio routing, volume control, remote control key passthrough, OneIP streaming, and multiviewer control over a local network using UDP multicast or broadcast.

Main entry point:

>>> import mx_remote
>>> mx = mx_remote.Remote()
>>> await mx.start_async()

Key classes:

Remote Main component that manages network connections and device registry. DeviceBase A discovered device on the network (matrix, OneIP unit, amplifier). BayBase A single input or output port on a device. MxrCallbacks Subclass to receive notifications on state changes.

See README.md for full usage documentation.

Client

Remote owns the socket, the device registry and the background probe that keeps both in step with the mesh.

Remote device discovery and management over UDP multicast/broadcast.

class mx_remote.remote.Remote.Remote

Bases: DeviceRegistry, ConnectionCallbacks

Main component that handles the network connections and registration of remote devices

__init__(target_ip=None, port=None, http_session=None, open_connection=True, callbacks=None, name='MXR Python', local_ip=None, broadcast=None, addr_filter=None, uid_path=None, logo_port=None)

Initialise the remote controller.

Parameters:

• target_ip (str | None) – multicast/broadcast IP to use, or None for the default

• port (int | None) – UDP port to use, or None for the default

• http_session (ClientSession | None) – shared aiohttp session for API calls, or None to create one

• open_connection (bool) – open the UDP connection immediately when True

• callbacks (MxrCallbacks | None) – event callbacks for device state changes

• name (str) – human-readable name advertised on the network

• local_ip (str | None) – local interface IP to bind to, or None for any

• broadcast (bool | None) – use broadcast instead of multicast when True

• addr_filter (str | None) – only log frames from this IP address when set

• uid_path (str | None) – file holding this client’s uid, or None for ~/.mxr-uid. Give concurrent clients on one host separate paths - see _load_uid

• logo_port (int | None) – TCP port to serve overlay sync logo images on, or None for a free one

Return type:

None

property library_version: str

version of the mx_remote library

property protocol_version: int

protocol version used by this library

property net_protocol_version_max: int

highest protocol version used by devices on the network

property net_protocol_version_min: int

lowest protocol version used by devices on the network

property target_ip: str

target ip address

property local_ip: str | None

local ip address

property broadcast: bool

broadcast or multicast

property uid_raw: bytes | None

uid of this device as bytes

property uid: MxrDeviceUid

uid of this device

property name: str

device name

property callbacks: MxrCallbacks

callbacks to call when the device is updated

property http_session: ClientSession

Active HTTP client session for API commands

async update_config(callbacks=None, name=None, target_ip=None, port=None, local_ip=None, broadcast=None)

Update runtime configuration, reconnecting if network parameters changed.

Parameters:

• callbacks (MxrCallbacks | None)

• name (str | None)

• target_ip (str | None)

• port (int | None)

• local_ip (str | None)

• broadcast (bool | None)

Return type:

None

has_completed_devices()

Return True if at least one registered device has completed configuration.

Return type:

bool

async start_async()

Start the server that listens for mx_remote frames from other devices.

Return type:

None

async stop_async()

Stop the server and close all connections.

Return type:

None

async close()

Close all open connections and cancel background tasks.

Return type:

None

get_by_serial(serial)

Get the cached device matching the given serial number, or None.

Parameters:

serial (str)

Return type:

DeviceBase | None

get_by_uid(remote_id)

Get the cached device matching the given unique id, or None.

Parameters:

remote_id (str | MxrDeviceUid | None)

Return type:

DeviceBase | None

uid_to_user_string(remote_id)

return the serial of the unit if the uid is known, or the uid as string if it isn’t

Parameters:

remote_id (str | MxrDeviceUid | bytes | None)

Return type:

str

get_by_stream_ip(ip, audio=False)

get a bay of a device by its OneIP stream address

Parameters:

• ip (str)

• audio (bool)

Return type:

BayBase | None

get_bay_by_portnum(remote_id, portnum)

Get the cached bay for a device, given the device id and port number.

Parameters:

• remote_id (str | MxrDeviceUid)

• portnum (int)

Return type:

BayBase | None

get_bay_by_portname(remote_id, portname)

get a bay of a device by its unique id and port name

Parameters:

• remote_id (str | MxrDeviceUid)

• portname (str)

Return type:

BayBase | None

property links: BayLinks

linked bay configurations for all devices

transmit(data)

Transmit raw data over the UDP connection. Returns bytes sent.

Parameters:

data (bytes)

Return type:

int

tx_discover()

Transmit a discover frame. All remotes will respond with a hello frame.

Return type:

int

async set_all_oneip_device_settings(settings)

Change settings on every OneIP device of the mesh with one frame.

settings carries the settings behind their bits in valid, as a device reports them. Each device applies those it has and ignores the rest, and none below protocol 0x2A applies any. A setting only a device reports about itself, a profile, PTP mode, PTP domain or power save level out of range, a PTP DSCP above ONEIP_DSCP_MAX, a stream TTL outside 1 to 255, a rotation above ONEIP_SINK_ROTATION_MAX and a power save time that is not a time of day are refused here, since every device would ignore them. Each device takes a rotation only by its own step.

Nothing is cached: each device that applies a change reports its settings, and its oneip_settings reads that.

Parameters:

settings (OneIPDeviceSettings)

Return type:

bool

async set_all_oneip_power_save(enabled)

Switch power save on or off on every OneIP device of the mesh with one frame, written as Device.set_oneip_power_save() writes it. Otherwise as set_all_oneip_device_settings().

Parameters:

enabled (bool)

Return type:

bool

async request_all_oneip_privacy()

Ask every OneIP source unit of the mesh how its streams are encrypted, as Device.request_oneip_privacy() asks one. A unit below protocol 0x30 ignores it.

Return type:

bool

async set_mesh_time_zone(zone, rule)

Set the time zone of every device that hears it.

zone is an IANA name such as Europe/Amsterdam and rule the POSIX TZ rule the devices keep time by, such as CET-1CEST,M3.5.0,M10.5.0/3. A device applies the rule and shows the name. Neither may be empty, hold a NUL, or be longer than its field on the wire leaves room for; clear_mesh_time_zone() sends both empty.

The mesh controller takes it too, and announces it from then on with every periodic broadcast. A device takes it only from a management application or the controller, and this client announces itself as a management application.

Parameters:

• zone (str)

• rule (str)

Return type:

bool

async clear_mesh_time_zone()

Clear the time zone of every device that hears it, which then keeps UTC. Sent, received and announced as set_mesh_time_zone() with an empty name and rule.

Return type:

bool

async set_mesh_time(when=None)

Set the clock of every device that hears it to when, or to now.

A device keeps its own clock where that is within 2s of when. It takes the time only from a management application or the controller; see set_mesh_time_zone(). A time before 1970 or past 2106, which 32 bits of seconds do not hold, is refused.

Parameters:

when (datetime | None)

Return type:

bool

tx_hello()

Transmit a hello frame to announce this device on the network.

Return type:

int

on_connection_made()

Callback invoked after ConnectionAsync has started the server.

Return type:

None

process_frame(timestamp, data, addr)

Decode and process a received mx_remote frame.

A device that may hold state this client missed is left in _state_request rather than asked here, so replaying a capture sends nothing; on_datagram_received does the asking.

Parameters:

• timestamp (float)

• data (bytes)

• addr (tuple[str, int])

Return type:

None

on_datagram_received(data, addr)

Called when a UDP frame was received.

Parameters:

• data (bytes)

• addr (tuple[str, int])

Return type:

None

property osd_sync_held: bool

Whether this client holds an overlay sync, and so announces itself as the mesh’s overlay sync manager.

async send_osd_sync(content)

Have every unit copy content, and keep it in place, returning the sync’s number, or None when it was refused or did not go out.

Units take a sync from the mesh controller or a management application, which this client announces itself as. Each unit fetches the images from a server this client runs, then asks for the settings, which this client answers until the content is replaced or clear_osd_sync(). Meanwhile it announces itself as the mesh’s overlay sync manager, so a unit waking from power save takes this content too, rather than the controller’s. The controller can still send its own over it; the last sync a unit took is what it shows. Each unit’s osd_sync_report says how it went.

Refused for content a unit would refuse: copying nothing, more than OSD_SYNC_RECORDS_MAX settings, a caption font over OSD_SYNC_FONT_MAX or text over OSD_SYNC_TEXT_MAX bytes, a logo other than -1 to 4, or an image that is not a PNG within OSD_SYNC_IMAGE_MAX bytes and OSD_SYNC_IMAGE_WIDTH_MAX by OSD_SYNC_IMAGE_HEIGHT_MAX pixels, shown at over OSD_SYNC_PERCENT_MAX percent. Refused content leaves the held sync as it was; content that fails to go out leaves none held.

Parameters:

content (OsdSyncContent)

Return type:

int | None

async resend_osd_sync(device)

Have one unit copy the held sync again, returning the new sync’s number. As send_osd_sync().

Refused while no sync is held, and for a unit that does not announce DeviceFeature.OSD_SYNC, as one that does not take overlay syncs.

Parameters:

device (DeviceBase)

Return type:

int | None

async clear_osd_sync()

Stop holding the sync this client sent, and hand the overlay sync manager’s part back to the controller. Units keep what they took; one still taking it fails, as its requests go unanswered.

Return type:

None

set_all_v2ip_device_settings

use set_all_oneip_device_settings.

Type:

Deprecated

Devices, bays and callbacks

A client works against these types rather than the classes implementing them: they are what the registry hands out and what a callback receives.

mx_remote.Interface.mxr_valid_addresses()

Get the list of valid local_ip addresses that can be used

Returns:

the IP addresses that can be used for the local_ip parameter

Return type:

list[str]

mx_remote.Interface.mxr_broadcast_address(local_ip=None)

Get the broadcast address for the interface matching local_ip, or the first non-loopback interface.

Parameters:

local_ip (str | None)

Return type:

str | None

class mx_remote.Interface.DeviceStatus

Bases: IntEnum

Status of a device on the network

ONLINE = 0

unit is online

OFFLINE = 1

unit is offline

REBOOTING = 2

unit indicated that it is going to reboot

BOOTING = 3

unit is booting

INACTIVE = 4

bay is inactive (OneIP encoder/decoder idle)

__new__(value)

class mx_remote.Interface.PowerStatus

Bases: IntEnum

__new__(value)

class mx_remote.Interface.HiddenStatus

Bases: IntEnum

__new__(value)

class mx_remote.Interface.FirmwareVersion

Bases: object

One firmware component’s version. timestamp is when the image was built or installed, in seconds since 1970, or 0 when it carries none, and hash the image’s checksum.

__init__(type, timestamp, version, hash)

Parameters:

• type (FirmwareType)

• timestamp (int)

• version (str)

• hash (int)

Return type:

None

class mx_remote.Interface.ConnectStatus

Bases: IntEnum

__new__(value)

class mx_remote.Interface.VideoColourSpace

Bases: IntEnum

Video colour space encoding format.

__new__(value)

class mx_remote.Interface.VideoSignalDetails

Bases: object

Video format of a bay: CTA-861 svd, colour space, bit depth, frame rate kind.

from_report says where it came from, because the two sources do not carry the same currency. A signal status report is the live format and arrives on a signal change. The bay config snapshot is a fallback for a bay no report has been seen for: it refreshes on the bay config broadcast cycle, so it can lag a change by a broadcast interval.

bpp is a bit depth in both cases, not a wire index. None means no format is set; 0 means one is set whose depth is not known, and those are different answers.

__init__(svd, colour, bpp, non_int, from_report)

Parameters:

• svd (int | None)

• colour (VideoColourSpace | None)

• bpp (int | None)

• non_int (bool | None)

• from_report (bool)

Return type:

None

property svd: int | None

CTA-861 short video descriptor, or None when no format is set.

property colour: VideoColourSpace | None

Colour space, or None when no format is set or the value is unknown to this build.

property bpp: int | None

Bit depth, 0 when a format is set whose depth is not known.

property non_int: bool | None

True for a non-integer (1000/1001) frame rate.

property from_report: bool

True when this came from a signal status report rather than the bay config snapshot.

class mx_remote.Interface.AmpDolbySettings

Bases: object

Dolby Digital settings for an amplifier

mode: int

Dolby mode

pcm_upmix: bool

PCM upmixing enabled

dolby_detected: bool

Dolby 5.1 signal detected

pcm_upmix_active: bool

PCM upmixing active

class mx_remote.Interface.AmpZoneSettings

Bases: object

Zone specific settings for an amplifier input/output

gain_left: int

gain level left channel

gain_right: int

gain level right channel

volume_min: int

minimum volume level

volume_max: int

maximum volume level

delay_left: int

audio delay left channel (ms)

delay_right: int

audio delay right channel (ms)

bass: int

bass level

treble: int

treble level

bridged: int

bridging mode setting

power_mode: int

auto power off setting

power_level: int

auto power off level

power_timeout: int

auto power off timeout

eq_left: list[int]

equalizer left channel

eq_right: list[int]

equalizer right channel

class mx_remote.Interface.OneIPAudioFormat

Bases: object

OneIP audio format (sample rate + channels). Zero values mean “use firmware defaults”.

__init__(sample_rate=0, channels=0)

Parameters:

• sample_rate (int)

• channels (int)

Return type:

None

property sample_rate: int

Sample rate in Hz, or 0 to fall back to the firmware default (48000).

property channels: int

Channel count 1..8, or 0 to fall back to the firmware default (2).

class mx_remote.Interface.OneIPStreamSource

Bases: ABC

OneIP multicast IP address and port number

abstract property label: str

user friendly description of this stream

abstract property ip: str

multicast IP address

abstract property port: int

UDP port number

class mx_remote.Interface.OneIPStreamSources

Bases: object

All OneIP multicast IP addresses and port numbers used by a device

abstract property uid: MxrDeviceUid | None

uid of the originating source device, when known

abstract property video: OneIPStreamSource

video stream source

abstract property audio: OneIPStreamSource

audio stream source

abstract property anc: OneIPStreamSource

ancillary stream source

abstract property arc: OneIPStreamSource | None

audio return stream source

property valid: bool

True when this entry carries a usable address.

Video and anc must both be multicast with a non-zero port; audio is optional and rides along. A sender without MXR_FEATURE_CONFIG_INITIALISED can put stack contents in bay 0’s addresses under its own uid, which rarely satisfy both halves of this test.

property cleared: bool

True when every stream is zeroed, which reports that the source is gone.

Distinct from an entry that is neither valid nor cleared, which is malformed. Treating a cleared entry as unusable discards the only signal that a source went away.

class mx_remote.Interface.OneIPStreamSourcesList

Bases: list[OneIPStreamSources]

list of OneIP sources

class mx_remote.Interface.AudioChangeSource

Bases: ABC

class mx_remote.Interface.AudioEndpoint

Bases: ABC

__init__(container)

Parameters:

container (AudioEndpoints)

Return type:

None

property status: AudioFeatures | None

The state this endpoint reports, on the bits of its features: FEATURE_MUTE while it is muted, FEATURE_TRIGGER while its trigger is active, and FEATURE_AUDIO_LOCK while its audio source is locked. None when the device did not report one.

property audio_locked: bool | None

Whether this endpoint keeps its audio source when the video route changes, None when it has reported no status.

is_v2ip

use is_oneip.

Type:

Deprecated

class mx_remote.Interface.AudioLink

Bases: ABC

class mx_remote.Interface.AudioLinks

Bases: ABC

class mx_remote.Interface.DeviceList

Bases: list[MxrDeviceUid]

__init__(data=None)

Parameters:

data (bytes | None)

append(item)

Append object to the end of the list.

Parameters:

item (MxrDeviceUid)

Return type:

None

class mx_remote.Interface.FilteredDevices

Bases: DeviceList

list of filtered devices

class mx_remote.Interface.BayContentField

Bases: object

One thing an input’s source is showing, such as its channel name.

A source reports these as named values in the order they are meant to be shown. The names are open-ended: a driver for a new kind of source adds its own without any other unit changing, so a caller passes on names it does not know.

key: str

What the value is, such as name or number.

value: str

The value, as text.

__init__(key, value)

Parameters:

• key (str)

• value (str)

Return type:

None

class mx_remote.Interface.BayContent

Bases: tuple[BayContentField, …]

What the source on an input is showing, as its unit last reported it: the fields in the order they are meant to be shown, empty when it shows nothing.

The content outlives the signal, so check signal_detected before showing it.

get(key)

The value of the field named key, None when there is none.

Parameters:

key (str)

Return type:

str | None

class mx_remote.Interface.BayBase

Bases: ABC

A bay (input/output) of an mx_remote device

abstract property status: DeviceStatus

bay status

abstract property callbacks: MxrCallbacks

mx_remote callbacks

abstract property device: DeviceBase

device to which this bay belongs

abstract property bay_uid: MxrBayUid

unique id of this bay

abstract property port: int

port number

abstract property is_local: bool

local or remote bay

abstract property bay_name: str

bay name for logging (mode / number)

abstract property user_name: str

name set up by the user

abstract property has_default_name: bool

default name not changed by the user

abstract property edid_profile: EdidProfile | None

edid profile used by the source

abstract property bay_label: str

user friendly label for this bay

abstract property features: BayFeaturesMask

List of supported features as strings

abstract property is_oneip_remote: bool

OneIP remote bay

abstract property dolby_input: str | None

Dolby Digital input

property dolby_input_bay: BayBase | None

Dolby Digital input bay used by this audio output bay

abstract property has_volume_control: bool

Volume control supported by this bay

abstract property is_input: bool

Source bay

abstract property is_output: bool

Sink bay

abstract property mode: str

Bay mode name

property other_mode: str

Bay mode name of the opposite side (so Output if this bay is an Input)

abstract property bay: int

Bay number

abstract property available: bool

True if available

abstract property is_hdmi: bool

True if this is an HDMI input or output

abstract property is_hdbaset: bool

True if this is a HDBaseT bay

abstract property is_audio: bool

True if this is audio input or output bay

abstract property video_source: BayBase | None

Current video source (output only)

abstract property video_route_endpoint: str | None

port’ literal when the sink is subscribed to a multicast that does not map to any registered input bay; else None.

Type:

Current video route as ‘ip

abstract property available_video_sources: list[BayBase]

Video sources that can be selected

abstract property audio_source: BayBase | None

Current audio source (output only)

abstract property audio_route_endpoint: str | None

port’ literal when the sink is subscribed to a multicast that does not map to any registered input bay; else None.

Type:

Current audio route as ‘ip

abstract property available_audio_sources: list[BayBase]

Audio sources that can be selected

abstract property powered_on: bool

True the connected device supports CEC and reports that the device is powered on

abstract property powered_off: bool

True the connected device supports CEC and reports that the device is powered off

abstract property power_status: PowerStatus

Power status

abstract property faulty: bool

True if a fault was detected

abstract property hidden: bool

True if flagged as hidden

abstract property zone_powered: bool

True if the amplifier zone the bay drives is powered on. Only a ProAmp8v2 reports it.

property poe_powered: bool

use zone_powered. Bay status bit 2 says an amplifier zone is powered on, not that PoE is.

Type:

Deprecated

abstract property hdbt_connected: bool

HDBaseT receiver connected

abstract property signal_detected: bool

Video signal detected (matrix/oneip) or audio signal detected (proamp)

abstract property signal_type: str

Audio or video signal type

abstract property video_details: VideoSignalDetails | None

Current video format, or None if neither source has carried one.

Prefers the signal status report, which arrives on a signal change, and falls back to the bay config snapshot for a bay no report has been seen for. Read from_report to tell which one this is.

abstract property hpd_detected: bool

Hotplug detected

abstract property cec_detected: bool

Connected device supports HDMI-CEC

abstract property content: BayContent

What the source on this input is showing, as its unit last reported it; empty when it shows nothing or its unit has no source driver.

abstract property mirroring: BayMirrorStatus

Bay mirroring status

abstract property filtered: FilteredDevices

Filtered bays

abstract property arc: str

Audio return channel status

abstract property volume: int | None

Current volume level (percentage)

abstract property muted: bool | None

True if audio has been muted, None if not available

abstract property online: bool

True if online

abstract property rebooting: bool

True if rebooting

abstract property booting: bool

True if booting

abstract property is_primary: bool

True if this bay is the primary bay in a mirroring setup

abstract property primary: BayBase

The primary bay in a mirroring setup

abstract property oneip_source: OneIPStreamSources | None

OneIP source address information

abstract property oneip_uid: MxrDeviceUid | None

Remote OneIP device uid

abstract property oneip_device: DeviceBase | None

Remote OneIP device

abstract property link: BayLink | None

mx-remote virtual link configuration (proamp<->matrix)

abstract property linked_bay: BayBase | None

linked bay if an mx-remote virtual link has been set up

abstract property link_configured: bool

mx-remote virtual link configured (proamp<->matrix)

abstract property link_connected: bool

mx-remote virtual link connected (proamp<->matrix)

abstract property volume_status: VolumeMuteStatus | None

volume and mute status

abstract property amp_settings: AmpZoneSettings | None

proamp zone settings

abstract property encoder_disabled: bool

video/audio encoder disabled

abstract property decoder_disabled: bool

video/audio decoder disabled

abstract property audio_endpoint: AudioEndpoint | None

primary audio endpoint. currently v2ip only

abstractmethod async set_name(name)

change the name of abay

Parameters:

name (str)

Return type:

bool

abstractmethod async select_video_source(port, opt=True)

change the video source of an output bay

Parameters:

• port (int)

• opt (bool)

Return type:

bool

abstractmethod async select_video_source_by_user_name(name, opt=True)

change the video source of an output bay

Parameters:

• name (str)

• opt (bool)

Return type:

bool

abstractmethod async select_audio_source(source, endpoint=None, audio_fmt=None)

change the audio source of an output bay

Parameters:

• source (int | BayBase | str | None)

• endpoint (str | None)

• audio_fmt (OneIPAudioFormat | None)

Return type:

bool

abstractmethod async select_edid_profile(profile)

change the edid profile of an input bay

Parameters:

profile (EdidProfile)

Return type:

bool

abstractmethod async set_hidden(hidden)

change the hidden status of a bay

Parameters:

hidden (bool)

Return type:

bool

abstractmethod async power_on()

power on the remote device if CEC is supported

Return type:

bool

abstractmethod async power_off()

power off the remote device if CEC is supported

Return type:

bool

abstractmethod volume_up()

change the volume if supported

Return type:

bool

abstractmethod volume_down()

change the volume if supported

Return type:

bool

abstractmethod volume_set(volume, muted=None)

change the volume if supported

Parameters:

• volume (int)

• muted (bool | None)

Return type:

bool

abstractmethod mute_set(mute)

change the mute status if supported

Parameters:

mute (bool)

Return type:

bool

abstractmethod async send_key(key)

send a remote control key press to the device

Parameters:

key (int)

Return type:

bool

abstractmethod register_callback(callback)

register a callback, called when the bay state changed

Parameters:

callback (Callable[[BayBase], None])

Return type:

None

abstractmethod unregister_callback(callback)

unregister a callback

Parameters:

callback (Callable[[BayBase], None])

Return type:

None

abstractmethod call_callbacks()

notify callbacks that this bay has changed

Return type:

None

is_v2ip_remote

use is_oneip_remote.

Type:

Deprecated

is_v2ip_sink

use is_oneip_sink.

Type:

Deprecated

is_v2ip_source

use is_oneip_source.

Type:

Deprecated

v2ip_device

use oneip_device.

Type:

Deprecated

v2ip_source

use oneip_source.

Type:

Deprecated

v2ip_uid

use oneip_uid.

Type:

Deprecated

class mx_remote.Interface.SelectedBays

Bases: object

A route a frame reports for an output. video and audio are None where the frame names no bay, and the port of a OneIP unit’s input its mappings have yet to create; clear_video says the output shows nothing, and audio_follows that its audio follows its video again.

__init__(video, audio, clear_video=False, audio_follows=False)

Parameters:

• video (BayBase | int | None)

• audio (BayBase | int | None)

• clear_video (bool)

• audio_follows (bool)

Return type:

None

class mx_remote.Interface.DeviceOneIPScalingSettings

Bases: ABC

abstract property mode: int

Scaling mode, carried only when flags has MXR_SCALING_FLAG_MODE_VALID

abstract property refresh: int

Refresh rate paired with mode, under the same MXR_SCALING_FLAG_MODE_VALID marker

abstract property flags: int

mxr_scaling_config.flags.

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 configured_mode: tuple[MxrSignalType, int] | None

The mode and refresh rate this sink scales to, None when it has none.

The two are distinct on the wire: a sink with no mode configured leaves MXR_SCALING_FLAG_MODE_VALID clear, and never sets it over a zero mode.

Trust it only from a peer whose hello carries CONFIG_INITIALISED (DeviceBase.config_initialised). Firmware without that builds this block over uninitialised stack, where the valid bit itself is noise.

property auto_scaling: bool | None

Whether the output scales automatically, None when the sender did not say.

property match_source: 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.

property skip_420: bool | None

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.

Type:

Whether the output declines 4

Type:

2

mx_remote.Interface.oneip_stream_valid(stream)

True when a stream source carries an address a frame actually meant to send.

Mirrors the firmware’s own test: a multicast ip and a non-zero port. A controller write that offers no addresses leaves the block zeroed, which fails both tests.

Parameters:

stream (OneIPStreamSource | None)

Return type:

bool

mx_remote.Interface.oneip_av_source_valid(video, anc)

True when an av source block carries addresses a frame meant to send.

Mirrors the firmware’s own test: video and anc must both be valid, audio is optional and is carried along with them.

Parameters:

• video (OneIPStreamSource | None)

• anc (OneIPStreamSource | None)

Return type:

bool

mx_remote.Interface.oneip_stream_cleared(stream)

True when a stream source is zeroed, which is how “no source” is spelled.

Parameters:

stream (OneIPStreamSource | None)

Return type:

bool

class mx_remote.Interface.OneIPOutputMode

Bases: object

The output format to scale a OneIP sink to.

Built from a depth and a colour space rather than from a packed mxr_signal_type word, so the word a caller sends cannot carry the unset bpp index a sink reports while it has no mode configured.

__init__(svd, depth, colour, refresh)

Parameters:

• svd (int)

• depth (int)

• colour (VideoColourSpace)

• refresh (int)

Return type:

None

svd

CTA-861 short video descriptor to output.

depth

8, 10 or 12.

Type:

Bit depth

colour

Colour space to output.

refresh

Refresh rate in Hz, ONEIP_SCALING_REFRESH_MIN to ONEIP_SCALING_REFRESH_MAX.

validate()

Why a sink will refuse this mode, or None when it will take it.

Checked here because a sink checks it and then says nothing: every value this rejects is one the receiver decodes cleanly and drops, leaving a caller with a send that succeeded and a setting that did not move.

Passing is not a guarantee. A sink also weighs the format against the EDID of the display attached to it and against what its own clock and output stage can produce, and none of that is knowable from here.

Return type:

str | None

property signal_type: MxrSignalType

The packed signal type a scaling write carries for this mode.

Call validate() first: an unvalidated depth packs as the index for “no depth”, which a receiver drops.

class mx_remote.Interface.OneIPScalingSettings

Bases: DeviceOneIPScalingSettings

Plain holder for a merged mxr_scaling_config.

__init__(mode, refresh, flags)

Parameters:

• mode (int)

• refresh (int)

• flags (int)

Return type:

None

property mode: int

Scaling mode, carried only when flags has MXR_SCALING_FLAG_MODE_VALID

property refresh: int

Refresh rate paired with mode, under the same MXR_SCALING_FLAG_MODE_VALID marker

property flags: int

mxr_scaling_config.flags.

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.

class mx_remote.Interface.OneIPDscpConfig

Bases: object

Per-stream DSCP marking carried in a OneIP device configuration.

DSCP 0 (CS0) is a legal marking, so each wire byte carries a set bit alongside its value and a stream whose byte is unset reads back as None here. A unit treats the marking as all-or-nothing: it keeps a frame’s markings only when all three streams carry a value, and otherwise keeps the ones it had - complete reports which case a frame is in.

__init__(video, audio, anc)

Parameters:

• video (int | None)

• audio (int | None)

• anc (int | None)

Return type:

None

property carried: bool

True when this frame carried a marking for the video stream. A unit takes the markings only when they are complete.

property complete: bool

True when all three streams carry a marking, the only case a unit takes the frame’s markings in.

class mx_remote.Interface.DeviceOneIPDetails

Bases: object

OneIP stream source details for a device

__init__(video, audio, anc, arc, tx_rate, scaling, dscp=None, whole_scaling=False)

whole_scaling says the scaling block is the sink’s whole state rather than a write of one part of it, so a mode it does not carry is a mode the sink no longer has.

Parameters:

• video (OneIPStreamSource | None)

• audio (OneIPStreamSource | None)

• anc (OneIPStreamSource | None)

• arc (OneIPStreamSource | None)

• tx_rate (int | None)

• scaling (DeviceOneIPScalingSettings | None)

• dscp (OneIPDscpConfig | None)

• whole_scaling (bool)

Return type:

None

property tx_rate: int | None

Source rate this device transmits at, or None if none is known.

Only a rate within ONEIP_SOURCE_RATE_MIN..MAX is one a sender meant to send; anything else is an absent offer rather than a rate, and merge() keeps the previously known value instead of caching what was on the wire.

property dscp: OneIPDscpConfig | None

Per-stream DSCP marking, or None from peers that predate it.

merge(previous)

Carry forward every field this frame did not carry.

A controller writing one field of a peer’s config leaves the others zeroed on the wire, so each is applied only behind its own validity marker. See FrameV2IPDeviceConfiguration for the markers.

Parameters:

previous (DeviceOneIPDetails | None)

Return type:

DeviceOneIPDetails

class mx_remote.Interface.DeviceOneIPSink

Bases: object

A OneIP sink’s effective multicast subscriptions and resolved audio format.

Mirrors the sink-side state broadcast alongside v2ip_device_config updates and manual-switch frames. addresses is None when no active route is announced; when present, each stream may still carry an all-zero ip when that stream is inactive. audio_fmt carries the resolved sink audio format (zero fields fall back to firmware defaults of 48kHz / 2 channels).

An address that reads as unset means “no route, or the sink could not work one out”, never “definitely not subscribed”. This block is the one part of a device configuration with no validity marker of its own, so a sink with nothing to say sends zeros and they are stored. A sender leaves it empty whenever its own stream configuration does not resolve, which covers more than having no route: a selected source whose record has not arrived yet, the state after a restart at either end, missing audio bay configuration, or a stream failing its validity check. audio_fmt has a second gate of its own, so it can be absent while the addresses are not.

Expect that reading rather than guarding against it. Any scaling change makes the device rebuild and rebroadcast this block, so an empty reading turns up most often during exactly the no-signal troubleshooting that prompted the change. A device’s periodic report puts a real route back within a minute of it having one, so a reader that needs certainty should wait one out rather than treat the first empty reading as an answer.

An empty reading is cached rather than dropped on purpose. A sink that has genuinely lost its route sends the same zeros, and so does every report after it, so refusing them would hold a route that nothing later could clear.

Only the device’s own report sets this. A controller writing another device’s configuration sends the block zeroed, and that frame is ignored.

__init__(addresses, audio_fmt)

Parameters:

• addresses (OneIPStreamSources | None)

• audio_fmt (OneIPAudioFormat | None)

Return type:

None

class mx_remote.Interface.TimeZone

Bases: object

The time zone a device announces for its mesh.

The mesh controller announces it with every periodic broadcast, and each device of the mesh keeps its clock and its power save windows by it. An empty zone and rule mean the controller has none, and the devices keep UTC.

zone: str

The IANA name, such as Europe/Amsterdam.

rule: str

The POSIX TZ rule the devices keep time by, such as CET-1CEST,M3.5.0,M10.5.0/3.

__init__(zone, rule)

Parameters:

• zone (str)

• rule (str)

Return type:

None

class mx_remote.Interface.DeviceClock

Bases: object

The time a device last announced, and when that arrived here.

utc: int

Seconds since 1970 UTC, as the device announced them.

received: float

When the announcement arrived, as time.time() read it.

now()

The device’s clock as of now: the announced time, advanced by how long ago it arrived.

Return type:

datetime

__init__(utc, received)

Parameters:

• utc (int)

• received (float)

Return type:

None

class mx_remote.Interface.OneIPPowerSaveSchedule

Bases: object

A OneIP device’s daily power save windows, Monday first, in the device’s time zone.

Day d powers down at start[d] and up again at end[d], both in minutes after midnight. A window belongs to the day it starts on and runs past midnight into the next when it ends before it starts; one that ends where it starts means no window that day.

__init__(start=(0, 0, 0, 0, 0, 0, 0), end=(0, 0, 0, 0, 0, 0, 0))

Parameters:

• start (tuple[int, ...])

• end (tuple[int, ...])

Return type:

None

property start: tuple[int, ...]

When each day’s window starts.

property end: tuple[int, ...]

When each day’s window ends.

window(day)

The window of day, Monday being 0, or None for a day without one or past Sunday.

Parameters:

day (int)

Return type:

tuple[int, int] | None

is_valid()

Whether every time is a time of day.

Return type:

bool

class mx_remote.Interface.UnitNetConfig

Bases: object

An IP configuration: the addresses a unit uses, or is told to use.

ip: str = '0.0.0.0'

The address.

netmask: str = '0.0.0.0'

The netmask.

gateway: str = '0.0.0.0'

The gateway.

dns1: str = '0.0.0.0'

The primary DNS server.

dns2: str = '0.0.0.0'

The secondary DNS server.

property addresses: tuple[str, str, str, str, str]

The five addresses, in the order the wire carries them.

is_valid()

Whether every address parses, the address is one a unit can hold, and the netmask is a run of ones from the top.

Return type:

bool

__init__(ip='0.0.0.0', netmask='0.0.0.0', gateway='0.0.0.0', dns1='0.0.0.0', dns2='0.0.0.0')

Parameters:

• ip (str)

• netmask (str)

• gateway (str)

• dns1 (str)

• dns2 (str)

Return type:

None

class mx_remote.Interface.UnitStatus

Bases: object

A unit’s health and IP configuration, as it last reported them.

A unit reports this about itself with its periodic broadcast, and within a few seconds of a change to its flags, its status or its addresses.

flags: UnitFlag = 0

The report’s flags.

uptime: int = 0

Seconds since the unit booted.

boot_count: int | None = None

How often the unit has booted, None while it does not report it.

reboot_count: int = 0

How often the unit has rebooted.

encoder_health: int = 0

The encoder’s health, a mask of the unit’s encoder status bits.

decoder_health: int = 0

The decoder’s health, a mask of the unit’s decoder status and state bits.

network: UnitNetConfig = UnitNetConfig(ip='0.0.0.0', netmask='0.0.0.0', gateway='0.0.0.0', dns1='0.0.0.0', dns2='0.0.0.0')

The IP configuration in use.

fan_rpm: int | None = None

The fan speed in RPM, None while the unit does not report it.

fan_duty: int = 0

The fan duty cycle, in percent.

status: int = 0

The unit’s system status.

net_revert_s: int = 0

Seconds before a pending IP configuration is reverted.

temperatures: tuple[int, ...] = ()

Temperatures in degrees Celsius, at most UNIT_MAX_TEMPERATURES of them.

status_message: str = ''

The message of the current system status.

power_save: tuple[UnitPowerSave, ...] = ()

What the unit offers at each power save level, from OneIPPowerSaveLevel.REDUCED up; empty for a unit that predates the field. A route change or a command wakes the unit at every level it supports.

power_save_level(level)

What the unit offers at a power save level, empty for OneIPPowerSaveLevel.NONE or a level it does not report.

Parameters:

level (OneIPPowerSaveLevel | int)

Return type:

UnitPowerSave

property network_pending: bool

Whether an IP configuration changed through the mesh waits for the mesh controller to confirm it.

__init__(flags=<UnitFlag: 0>, uptime=0, boot_count=None, reboot_count=0, encoder_health=0, decoder_health=0, network=UnitNetConfig(ip='0.0.0.0', netmask='0.0.0.0', gateway='0.0.0.0', dns1='0.0.0.0', dns2='0.0.0.0'), fan_rpm=None, fan_duty=0, status=0, net_revert_s=0, temperatures=(), status_message='', power_save=())

Parameters:

• flags (UnitFlag)

• uptime (int)

• boot_count (int | None)

• reboot_count (int)

• encoder_health (int)

• decoder_health (int)

• network (UnitNetConfig)

• fan_rpm (int | None)

• fan_duty (int)

• status (int)

• net_revert_s (int)

• temperatures (tuple[int, ...])

• status_message (str)

• power_save (tuple[UnitPowerSave, ...])

Return type:

None

class mx_remote.Interface.OneIPPtpState

Bases: object

A OneIP device’s PTP state, as it reports it about itself.

Only the device can read its own video processor, so this is never written to a device, and a controller’s frame about one carries none.

flags: OneIPPtpFlag = 0

The block’s flags.

mode: OneIPPtpMode | int = 0

The mode the video processor runs; a raw int for one this library does not name.

domain: int = 0

The domain the video processor runs in.

port_state: int = 0

The IEEE 1588 portState.

lock: OneIPPtpLock | int = 0

How far the clock has locked; a raw int for a value this library does not name.

clock_identity: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00'

The device’s own clock identity.

grandmaster_identity: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00'

The clock identity of the grandmaster the device runs on, all zero while it runs on none.

property followed: bool

Whether the device locked to a master since its PTP started, so its mesh holds a time.

property grandmaster: bytes | None

The grandmaster the device runs on, None while it runs on none.

__init__(flags=<OneIPPtpFlag: 0>, mode=OneIPPtpMode.OFF, domain=0, port_state=0, lock=OneIPPtpLock.UNLOCKED, clock_identity=b'\x00\x00\x00\x00\x00\x00\x00\x00', grandmaster_identity=b'\x00\x00\x00\x00\x00\x00\x00\x00')

Parameters:

• flags (OneIPPtpFlag)

• mode (OneIPPtpMode | int)

• domain (int)

• port_state (int)

• lock (OneIPPtpLock | int)

• clock_identity (bytes)

• grandmaster_identity (bytes)

Return type:

None

class mx_remote.Interface.OneIPDownmix

Bases: object

How a OneIP output mixes 5.1 and 7.1 PCM down to stereo, and whether it does now.

A device reports it once its video processor has answered for it, so never one whose output cannot mix down.

mode: OneIPDownmixMode | int = 0

When the output mixes down; a raw int for a mode this library does not name.

level: OneIPDownmixLevel | int = 0

How loud the mix is; a raw int for a level this library does not name.

lfe: int = 0

The percent the LFE channel is mixed in at, at most ONEIP_DOWNMIX_LFE_MAX; 0 leaves it out.

state: int = 0

Why the stream is or is not mixed down, as the device’s own code. Only the device reports it.

channels: int = 0

The stream’s channels while it is mixed down, else 0. Only the device reports it.

is_valid()

Whether the settings a write carries are in range.

Return type:

bool

written(write)

The settings of write applied to this report, which keeps what only the device reports.

Parameters:

write (OneIPDownmix)

Return type:

OneIPDownmix

__init__(mode=OneIPDownmixMode.OFF, level=OneIPDownmixLevel.NORMALISED, lfe=0, state=0, channels=0)

Parameters:

• mode (OneIPDownmixMode | int)

• level (OneIPDownmixLevel | int)

• lfe (int)

• state (int)

• channels (int)

Return type:

None

class mx_remote.Interface.OneIPVlan

Bases: object

VLAN tagging on a OneIP device’s uplink.

Only the device knows what it runs, so this is what it reported about itself. A change written to it is applied at once and stays PENDING until the mesh controller confirms it, which proves the device still reaches the mesh and the mesh still reaches it; unconfirmed, the device reverts it.

flags: OneIPVlanFlag = 0

The block’s flags.

device: int = 0

The VLAN id of the device’s own traffic, 0 for untagged.

port: tuple[int, ...] = (0, 0, 0)

The VLAN id each downlink port carries, 0 to share the device’s untagged traffic, indexed as ONEIP_VLAN_PORTS orders them.

uplink: int = 0

The port pinned as the uplink as 1 + its index, 0 to detect it.

active_uplink: int = 0

the port in use as the uplink, as 1 + its index.

Type:

Reported by the device

revert_s: int = 0

the seconds before a pending configuration is reverted.

Type:

Reported by the device

property trunk: bool

Whether untagged frames arriving on the uplink are dropped.

property is_pending: bool

Whether the device reverts this configuration unless the mesh controller confirms it.

property has_sfp: bool

Whether the device has an SFP port.

property pinned_uplink_port: int | None

The index of the port pinned as the uplink, None when the device detects it.

property active_uplink_port: int | None

The index of the port the device uses as its uplink, None for a value that names no port.

is_valid()

Whether every VLAN id is at most ONEIP_VLAN_ID_MAX and the uplink is detected or names a port.

Return type:

bool

__init__(flags=<OneIPVlanFlag: 0>, device=0, port=(0, 0, 0), uplink=0, active_uplink=0, revert_s=0)

Parameters:

• flags (OneIPVlanFlag)

• device (int)

• port (tuple[int, ...])

• uplink (int)

• active_uplink (int)

• revert_s (int)

Return type:

None

class mx_remote.Interface.OneIPPtpMessages

Bases: object

How a OneIP device paces its PTP messages, its SAP timings, its streams’ TTL and its output’s rotation, which a frame carries in the same block. Each value is behind its own bit of OneIPDeviceSettings.valid, one of ONEIP_DEVICE_SETTINGS_BLOCK.

Intervals are base-2 logarithms of seconds, so -3 is 125 ms and 1 is 2 s.

log_announce_interval: int = 0

Between announce messages, behind PTP_ANNOUNCE.

log_sync_interval: int = 0

Between sync messages, behind PTP_SYNC.

log_delay_req_interval: int = 0

Between delay requests, behind PTP_DELAY_REQ.

announce_timeout: int = 0

The announce intervals before a silent master is dropped, behind PTP_ANNOUNCE_TIMEOUT.

dscp: int = 0

The DSCP of the messages, at most ONEIP_DSCP_MAX, behind PTP_DSCP.

sap_expire_min: int = 0

The minutes after which a SAP announcement the device heard is forgotten, behind SAP_EXPIRE.

sap_interval_s: int = 0

The seconds between the device’s SAP announcements, behind SAP_INTERVAL.

stream_ttl: int = 0

The TTL of the device’s streams, 1 to 255, behind STREAM_TTL. A device whose video processor cannot change it keeps the setting and sends ONEIP_STREAM_TTL_DEFAULT.

sink_rotation: int = 0

The degrees the device’s HDMI output is turned by, clockwise, at most ONEIP_SINK_ROTATION_MAX, behind SINK_ROTATION.

sink_rotation_step: int = 0

the device takes only an angle that is a multiple of it, and 0 alone when it is 0. Only the device reports it, behind the same bit.

Type:

The step the output turns by

takes_sink_rotation(degrees)

Whether a device reporting this step takes degrees as its output’s rotation.

Parameters:

degrees (int)

Return type:

bool

merge(other, which)

The values behind the bits of which copied from other, the rest kept.

Parameters:

• other (OneIPPtpMessages)

• which (OneIPDeviceSetting)

Return type:

OneIPPtpMessages

describe(valid)

The values behind the bits of valid, one “name=value” each.

Parameters:

valid (OneIPDeviceSetting)

Return type:

list[str]

__init__(log_announce_interval=0, log_sync_interval=0, log_delay_req_interval=0, announce_timeout=0, dscp=0, sap_expire_min=0, sap_interval_s=0, stream_ttl=0, sink_rotation=0, sink_rotation_step=0)

Parameters:

• log_announce_interval (int)

• log_sync_interval (int)

• log_delay_req_interval (int)

• announce_timeout (int)

• dscp (int)

• sap_expire_min (int)

• sap_interval_s (int)

• stream_ttl (int)

• sink_rotation (int)

• sink_rotation_step (int)

Return type:

None

class mx_remote.Interface.OsdSyncSlot

Bases: object

One logo slot, as an overlay sync describes it.

bytes: int = 0

The PNG’s size in bytes; zero empties the slot.

crc32: int = 0

The PNG’s CRC-32.

percent: int = 0

The size it is shown at, in percent.

__init__(bytes=0, crc32=0, percent=0)

Parameters:

• bytes (int)

• crc32 (int)

• percent (int)

Return type:

None

class mx_remote.Interface.OsdSync

Bases: object

An overlay sync, as its source sent it: a management unit having other units copy its overlay captions, logo choice and place, backgrounds and logo images. A unit takes one only from a management unit: the mesh controller, or one that announces DeviceFeature.MANAGER.

seq: int

The sync’s number at its source.

target: MxrDeviceUid

The unit it is for, or an empty uid for every unit.

what: OsdSyncWhat

What it copies.

http_port: int

The source’s HTTP port, zero meaning 80.

source_ip: str

The source’s address, 0.0.0.0 meaning the sender’s.

records: int

How many settings follow.

slots: tuple[OsdSyncSlot, ...] | None

The logo slots, when it copies them. A unit fetches a slot whose size or CRC differs from its own from http://source_ip:http_port/osd-sync/slotN.png, N being 1 to 4.

__init__(seq, target, what, http_port, source_ip, records, slots)

Parameters:

• seq (int)

• target (MxrDeviceUid)

• what (OsdSyncWhat)

• http_port (int)

• source_ip (str)

• records (int)

• slots (tuple[OsdSyncSlot, ...] | None)

Return type:

None

class mx_remote.Interface.OsdSyncRequest

Bases: object

A unit asking for an overlay sync, or for settings of one it is taking, or management asking for a new sync for a unit.

target: MxrDeviceUid

The unit the sync is for, which sent the request unless management did.

seq: int

The sync whose settings it asks for, or zero asking for a new sync.

what: OsdSyncWhat

What it asks a new sync to copy.

missing: bytes

The settings it lacks, bit i standing for setting i, 16 bytes.

source: MxrDeviceUid

Who sent the sync it asks about. Empty when it asks for a new sync.

is_missing(index)

Whether the unit lacks setting index.

Parameters:

index (int)

Return type:

bool

__init__(target, seq, what, missing, source)

Parameters:

• target (MxrDeviceUid)

• seq (int)

• what (OsdSyncWhat)

• missing (bytes)

• source (MxrDeviceUid)

Return type:

None

class mx_remote.Interface.OsdCaption

Bases: object

A caption, as an overlay setting gives it.

font: str = ''

The font’s name, empty for the layout’s.

size: int = 0

The size, zero for the layout’s.

x: int = -32768

The horizontal position, -32768 for the layout’s.

y: int = -32768

The vertical position, -32768 for the layout’s.

wrap: int = -2

-1 automatic, 0 none, -2 the layout’s.

Type:

The wrap width in pixels

colour: int = 4294967295

The colour as 0xRRGGBB, 0xFFFFFFFF for the layout’s.

__init__(text='', font='', size=0, x=-32768, y=-32768, wrap=-2, align=OsdCaptionAlign.DEFAULT, format=OsdCaptionFormat.DEFAULT, colour=4294967295)

Parameters:

• text (str)

• font (str)

• size (int)

• x (int)

• y (int)

• wrap (int)

• align (OsdCaptionAlign | int)

• format (OsdCaptionFormat | int)

• colour (int)

Return type:

None

class mx_remote.Interface.OsdLogo

Bases: object

A logo choice and place, as an overlay setting gives it.

logo: int = 0

0 the built-in logo, -1 none, 1 to 4 a slot.

x: int = -32768

The horizontal position, -32768 for the layout’s.

y: int = -32768

The vertical position, -32768 for the layout’s.

__init__(logo=0, x=-32768, y=-32768)

Parameters:

• logo (int)

• x (int)

• y (int)

Return type:

None

mx_remote.Interface.OsdSyncValue = mx_remote.Interface.OsdCaption | mx_remote.Interface.OsdLogo | int

a caption, a logo choice and place, or a background colour as 0xRRGGBB, 0xFFFFFFFF for the layout’s.

Type:

What one overlay setting sets

class mx_remote.Interface.OsdSyncSetting

Bases: object

One setting of an overlay sync, which its source sends to one unit.

seq: int

The sync it belongs to.

target: MxrDeviceUid

The unit it is for.

index: int

Its place in the sync, below records.

records: int

How many settings the sync has.

size: OsdSyncSize | int

The output size it applies at.

layers: int

The layers it applies to, a bit per layer.

set: int

OsdCaptionField bits for a caption, OsdLogoField bits for a logo, and bit 0 for a background’s colour.

Type:

The fields it gives

__init__(seq, target, index, records, size, layers, set, value)

Parameters:

• seq (int)

• target (MxrDeviceUid)

• index (int)

• records (int)

• size (OsdSyncSize | int)

• layers (int)

• set (int)

• value (OsdCaption | OsdLogo | int)

Return type:

None

class mx_remote.Interface.OsdSyncReport

Bases: object

How a unit is getting on with an overlay sync. A unit reports taking, then done or failed. One in power save reports deferred, and reports again once it takes the sync on waking.

seq: int

The sync it reports on, numbered by the source that sent it.

written: int

The settings it wrote.

refused: int

The settings it refused.

reason: str

Why it failed or refused any.

__init__(seq, state, written, refused, reason)

Parameters:

• seq (int)

• state (OsdSyncState | int)

• written (int)

• refused (int)

• reason (str)

Return type:

None

class mx_remote.Interface.OsdMessage

Bases: object

The message on a unit’s output, as the unit last reported it. The unit holds it until it restarts.

flags: OsdMessageFlag

Whether a message is set and shown, whether the unit can show one, and whether it refused the write it answers. Without SET the other fields are empty.

logo: int

0 the built-in logo, -1 none, 1 to 5 a slot.

Type:

The logo shown with it

priority: OsdMessagePriority | int

Where it stands against the unit’s own messages.

text: str

Its markup.

__init__(flags, logo, priority, text)

Parameters:

• flags (OsdMessageFlag)

• logo (int)

• priority (OsdMessagePriority | int)

• text (str)

Return type:

None

class mx_remote.Interface.OsdSyncEntry

Bases: object

One setting of an overlay sync this client sends.

value: OsdCaption | OsdLogo | int

What it sets.

set: int

The fields it gives, as in OsdSyncSetting.set. A field given its default value goes back to the layout’s.

size: OsdSyncSize = 1

The output size it applies at.

layers: int = 1

The layers it applies to, a bit per layer. A unit leaves out the layers it does not have, and skips the setting when none is left.

__init__(value, set, size=OsdSyncSize.LARGE, layers=1)

Parameters:

• value (OsdCaption | OsdLogo | int)

• set (int)

• size (OsdSyncSize)

• layers (int)

Return type:

None

class mx_remote.Interface.OsdSyncImage

Bases: object

The logo image for one slot.

png: bytes = b''

The PNG. Empty empties the slot.

percent: int = 0

0 at its own pixels, 1 to 100 its longer side as a percent of the large overlay.

Type:

The size it is shown at

__init__(png=b'', percent=0)

Parameters:

• png (bytes)

• percent (int)

Return type:

None

class mx_remote.Interface.OsdSyncContent

Bases: object

What this client has units copy.

what: OsdSyncWhat

The kinds of setting it copies. OsdSyncWhat.LOGO_SLOTS follows from images.

entries: tuple[OsdSyncEntry, ...] = ()

The settings, which units write in this order.

images: tuple[OsdSyncImage, ...] | None = None

The four logo slots, or None to leave every unit’s own.

__init__(what, entries=(), images=None)

Parameters:

• what (OsdSyncWhat)

• entries (tuple[OsdSyncEntry, ...])

• images (tuple[OsdSyncImage, ...] | None)

Return type:

None

class mx_remote.Interface.OneIPSinkSdp

Bases: object

What a OneIP output plays from a session description, as it last reported it. The stream’s fields are zero while it plays none.

flags: OneIPSdpFlag = 0

The report’s flags.

screen: int = 0

What the output shows while it plays audio alone, as the wire value.

encoding: OneIPSdpEncoding | int = 0

The sample encoding; a raw int for one this library does not name.

payload_type: int = 0

The RTP payload type.

clock_mode: OneIPSdpClockMode | int = 0

What the video processor times the stream by, behind OneIPSdpFlag.CLOCK.

clock_state: OneIPSdpClockState | int = 0

How far the video processor has got with its timing, behind OneIPSdpFlag.CLOCK.

rate_hz: int = 0

The sample rate in Hz.

group: str = '0.0.0.0'

The multicast group.

name: str = ''

The session name.

layout: str = ''

The channel layout.

property active: bool

Whether the output plays a stream from a description.

__init__(flags=<OneIPSdpFlag: 0>, screen=0, encoding=OneIPSdpEncoding.NONE, channels=0, payload_type=0, media_clock=OneIPSdpMediaClock.NONE, ref_clock=OneIPSdpRefClock.NONE, clock_mode=OneIPSdpClockMode.ARRIVAL, clock_state=OneIPSdpClockState.IDLE, port=0, rate_hz=0, media_clock_offset=0, group='0.0.0.0', name='', layout='')

Parameters:

• flags (OneIPSdpFlag)

• screen (int)

• encoding (OneIPSdpEncoding | int)

• channels (int)

• payload_type (int)

• media_clock (OneIPSdpMediaClock | int)

• ref_clock (OneIPSdpRefClock | int)

• clock_mode (OneIPSdpClockMode | int)

• clock_state (OneIPSdpClockState | int)

• port (int)

• rate_hz (int)

• media_clock_offset (int)

• group (str)

• name (str)

• layout (str)

Return type:

None

class mx_remote.Interface.OneIPPrivacyStream

Bases: object

How one of a OneIP source unit’s streams is encrypted, as the unit reports it: the values of the stream’s a=privacy and a=extmap session description attributes.

A receiver needs these to decrypt the stream. The key itself never travels: every unit of a mesh holds the same one. This library holds no key and decrypts nothing.

group: str = '0.0.0.0'

The stream’s destination address.

port: int = 0

The stream’s UDP port.

version: int = 0

Steps whenever the parameters change.

on: bool = False

Whether the stream is encrypted. Without it the stream goes out in the clear, and the fields below mean nothing.

full_id: int = 0

The RTP header extension id of the full IV counter.

short_id: int = 0

The RTP header extension id of the short IV counter.

iv: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00'

The initialisation vector, 8 bytes.

key_generator: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'

The key generator, 16 bytes.

key_id: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00'

Names the mesh’s key, 8 bytes. A receiver holding another drops the stream.

key_version: int = 0

The key version.

__init__(group='0.0.0.0', port=0, version=0, on=False, full_id=0, short_id=0, iv=b'\x00\x00\x00\x00\x00\x00\x00\x00', key_generator=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00', key_id=b'\x00\x00\x00\x00\x00\x00\x00\x00', key_version=0)

Parameters:

• group (str)

• port (int)

• version (int)

• on (bool)

• full_id (int)

• short_id (int)

• iv (bytes)

• key_generator (bytes)

• key_id (bytes)

• key_version (int)

Return type:

None

class mx_remote.Interface.OneIPPrivacy

Bases: object

How a OneIP source unit’s streams are encrypted, as it last reported it. A unit reports this whenever it changes, at least once a minute, and when asked. A unit that is in no mesh sends in the clear.

anc: OneIPPrivacyStream

The ancillary data stream.

__init__(video, audio, anc)

Parameters:

• video (OneIPPrivacyStream)

• audio (OneIPPrivacyStream)

• anc (OneIPPrivacyStream)

Return type:

None

class mx_remote.Interface.OneIPTestTone

Bases: object

A OneIP sink’s test tone.

mode: OneIPToneMode | int = 0

What plays; a raw int for a mode this library does not name.

freq: int = 0

The frequency, in Hz.

level: int = 0

The level, in dBFS.

channels: int = 0

The channels it plays on.

rate: int = 0

The sample rate, in Hz.

is_valid()

Whether a sink plays this tone: a mode it names, and every value in range. A line-up tone needs two channels or more.

Return type:

bool

__init__(mode=OneIPToneMode.OFF, freq=0, level=0, channels=0, rate=0)

Parameters:

• mode (OneIPToneMode | int)

• freq (int)

• level (int)

• channels (int)

• rate (int)

Return type:

None

class mx_remote.Interface.OneIPTestSync

Bases: object

A OneIP sink’s lip-sync flash: a pattern frame is marked every period, the frame lead after a mark flashes white, and a BEEP tone starts offset sample periods after it.

The offset is a calibration: nothing measures the sink’s own delay between a picture and a sample reaching the HDMI link, and a display adds its own.

period: int = 0

Every this many pattern frames is marked, 0 for none.

lead: int = 0

The frame this many after a mark flashes.

offset: int = 0

The sample periods between a mark and the beep.

beep_ms: int = 0

How long the beep lasts, in milliseconds.

is_valid()

Whether a sink takes these settings: the lead is below the period, or 0 without one, and the period, offset and beep are in range.

Return type:

bool

__init__(period=0, lead=0, offset=0, beep_ms=0)

Parameters:

• period (int)

• lead (int)

• offset (int)

• beep_ms (int)

Return type:

None

class mx_remote.Interface.OneIPTestcard

Bases: object

The test card a OneIP sink draws on its output, as it last reported it.

A sink reports it only when asked, with request_oneip_testcard() or in answer to a change. The counters run free and wrap.

flags: OneIPTestcardFlag = 0

What the sink reports about its test card.

pattern: OneIPTestPattern | int = 0

The pattern; a raw int for a pattern this library does not name.

colour: int = 0

The colour of a FLAT pattern, 0xRRGGBB.

tone: OneIPTestTone = OneIPTestTone(mode=<OneIPToneMode.OFF: 0>, freq=0, level=0, channels=0, rate=0)

The tone.

sync: OneIPTestSync = OneIPTestSync(period=0, lead=0, offset=0, beep_ms=0)

The lip-sync flash.

frames: int = 0

Pattern frames sent.

periods: int = 0

Sample periods since the tone started.

marks: int = 0

Lip-sync marks the tone has seen.

property supported: bool

Whether the sink can draw the test card.

__init__(flags=<OneIPTestcardFlag: 0>, pattern=OneIPTestPattern.OFF, colour=0, tone=OneIPTestTone(mode=<OneIPToneMode.OFF: 0>, freq=0, level=0, channels=0, rate=0), sync=OneIPTestSync(period=0, lead=0, offset=0, beep_ms=0), frames=0, periods=0, marks=0)

Parameters:

• flags (OneIPTestcardFlag)

• pattern (OneIPTestPattern | int)

• colour (int)

• tone (OneIPTestTone)

• sync (OneIPTestSync)

• frames (int)

• periods (int)

• marks (int)

Return type:

None

class mx_remote.Interface.OneIPDeviceSettings

Bases: object

The device settings of a OneIP unit, as it reports them and as its controller changes them.

Each setting is carried only behind its bit in valid, so a frame changes one setting without restating the others, and a device reports only the settings it has. Read a setting through get() and the profile properties, which answer None for one the device has not reported.

__init__(valid=<OneIPDeviceSetting: 0>, flags=<OneIPDeviceSetting: 0>, ir_profiles=0, ir_profile=0, ir_profile_sink=0, auto_power_save=0, power_save=None, ptp_mode=OneIPPtpMode.OFF, ptp_domain=0, ptp_priority1=0, power_save_level=OneIPPowerSaveLevel.NONE, ptp_messages=None)

Parameters:

• valid (OneIPDeviceSetting)

• flags (OneIPDeviceSetting)

• ir_profiles (int)

• ir_profile (int)

• ir_profile_sink (int)

• auto_power_save (int)

• power_save (OneIPPowerSaveSchedule | None)

• ptp_mode (OneIPPtpMode | int)

• ptp_domain (int)

• ptp_priority1 (int)

• power_save_level (OneIPPowerSaveLevel | int)

• ptp_messages (OneIPPtpMessages | None)

Return type:

None

classmethod power_save_switch(enabled)

The settings that switch a device’s power save on or off. On is both POWER_SAVE_DISABLED, clear, and POWER_SAVE_LEVEL, at 0.

Parameters:

enabled (bool)

Return type:

OneIPDeviceSettings

property valid: OneIPDeviceSetting

The settings reported so far.

property flags: OneIPDeviceSetting

The values of the on/off settings among valid.

get(setting)

Whether an on/off setting is on, None while the device has not reported it.

Parameters:

setting (OneIPDeviceSetting)

Return type:

bool | None

property ir_profile: int | None

The global infrared port’s profile, None while it is not reported.

property ir_profile_sink: int | None

The output infrared port’s profile, None while it is not reported. ONEIP_IR_PROFILE_NOT_SET means the port follows the global one.

property stored_ir_profiles: int | None

The infrared profiles stored on the device, bit n for profile n, None while it is not reported.

property auto_power_save: int | None

The idle minutes before the device powers down by itself, 0 for never, None while it is not reported.

property power_save_schedule: OneIPPowerSaveSchedule | None

The daily power save windows, None while they are not reported.

property ptp_mode: OneIPPtpMode | int | None

The PTP mode, a raw int for one this library does not name, None while it is not reported.

property ptp_domain: int | None

The PTP domain, up to ONEIP_PTP_DOMAIN_MAX, None while it is not reported.

property ptp_priority1: int | None

The priority1 the device announces as a PTP grandmaster, lower winning, None while it is not reported.

property power_save_level: OneIPPowerSaveLevel | int | None

The level the device powers down to in power save, which it picks itself, a raw int for one this library does not name, None while it is not reported.

property ptp_messages: OneIPPtpMessages | None

The settings carried in the block of their own the device has reported, None while it has reported none of them; each value is meaningful only behind its own bit of valid.

merge(previous)

Fold this received block onto the cached one.

Each bit in this block’s valid replaces its own setting and leaves the others alone, so a write about one setting does not clear what was known about the rest.

Parameters:

previous (OneIPDeviceSettings | None)

Return type:

OneIPDeviceSettings

as_applied_to(reported)

This block limited to what a device that reported reported takes from a write about it.

A device applies a setting only if it has it, a profile, PTP mode, PTP domain or PTP DSCP only within its range, a stream TTL only when it is not 0, a rotation only by its own step, and never what only it can report about itself. The step stays the device’s. It picks its power save level itself, and takes a level it is written, without POWER_SAVE_DISABLED, as switching power save on.

reported may be only the bits the device reported, which says nothing of its step, so a rotation other than 0 is then left out.

Parameters:

reported (OneIPDeviceSettings | OneIPDeviceSetting | None)

Return type:

OneIPDeviceSettings

class mx_remote.Interface.UtpLinkErrorStatus

Bases: ABC

UTP link error status bits

abstract property in_error: bool

rx errors detected

abstract property in_fcs_error: bool

rx FCS errors detected

abstract property in_collision: bool

rx collisions detected

abstract property out_deferred: bool

tx deferred detected

abstract property out_excessive: bool

tx excessive detected

abstract property polarity_error: bool

polarity differences between pairs detected

abstract property skew_warning: bool

clock skew > 8 detected

abstract property length_warning: bool

different pair lengths detected

class mx_remote.Interface.UtpCableStatus

Bases: ABC

‘ UTP cable pair status

abstract property polarity: bool

positive or negative polarity

abstract property pair: int

pair number

abstract property skew: int

detected clock skew

abstract property length: int

detected length in meters

class mx_remote.Interface.NetworkPortStatus

Bases: ABC

detailed status of a network port

property port: int

port number

property errors: UtpLinkErrorStatus | None

link error status

property vct_status: list[str] | None

virtual cable test results

property link_speed: UtpLinkSpeed

link speed

property link_full_duplex: bool

full duplex or half duplex

property name: str

description of the port

property ip: str | None

IP address

property querier: str | None

detected IGMP querier or 0.0.0.0 if not detected

property cable_status: list[UtpCableStatus] | None

utp cable pair status

property mac_address: str | None

mac address of supported devices

class mx_remote.Interface.SystemTemperature

Bases: list[int]

system temperature

class mx_remote.Interface.DeviceBase

Bases: ABC

an mx_remote device on the network

abstract property status: DeviceStatus

device status

abstract property name: str

device name

abstract property registry: DeviceRegistry

local device information registry

abstract property configuration_complete: bool

check whether all configuration info for this device has been received

abstract property model_name: str

Model name

abstract property callbacks: MxrCallbacks

callbacks for this device

abstract property remote_id: MxrDeviceUid

unique id

abstract property version: str

firmware version

abstract property address: str

IP address

abstract property features: DeviceFeature | None

supported features

abstract property serial: str

serial number

abstract property bays: dict[int, BayBase]

device inputs and outputs

abstract property inputs: dict[str, BayBase]

device inputs

abstract property nb_inputs: int

number of inputs

abstract property first_input: BayBase | None

the first local input

abstract property outputs: dict[str, BayBase]

device outputs

abstract property nb_outputs: int

number of outputs

abstract property first_output: BayBase | None

the first local output

abstract property online: bool

True if online

abstract property rebooting: bool

True if rebooting

abstract property booting: bool

True if booting

abstract property is_amp: bool

True if as an audio amplifier

abstract property amp_dolby_channels: int

number of dolby input channels

abstract property nb_hdbt: int

number of HDBaseT inputs and outputs

abstract property is_oneip: bool

True if this a OneIP device

abstract property has_local_source: bool

True if this device has at least 1 local source

abstract property has_local_sink: bool

True if this device has at least 1 local sink

abstract property is_video_matrix: bool

True if this device supports video matrixing

abstract property is_audio_matrix: bool

True if this device supports audio matrixing

abstract property temperatures: dict[str, int]

temperature sensor reports

abstract property oneip_features: OneIPVideoProcessorFeature | 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.

abstract property oneip_sources: OneIPStreamSourcesList | None

OneIP stream source addresses

abstract property oneip_stats: OneIPDeviceStats | None

OneIP encoder/decoder statistics

abstract property oneip_details: DeviceOneIPDetails | None

OneIP encoder/decoder configuration

abstract property oneip_sink: DeviceOneIPSink | None

OneIP sink-side multicast subscriptions and resolved audio format (None until first announced)

abstract property oneip_settings: OneIPDeviceSettings | None

The OneIP device settings, None until the device has reported any.

A device reports only the settings it has, so one missing from valid once the rest have arrived is one the device does not have.

abstract property oneip_vlan: OneIPVlan | None

The VLAN configuration this OneIP device last reported about itself, None until it has reported one.

abstract property unit_status: UnitStatus | None

The health and IP configuration this unit last reported, None until it has reported them.

abstractmethod async clear_unit_status()

clear the unit’s current system status

Return type:

bool

abstractmethod async upgrade_unit_video_processor(force=False)

upgrade the unit’s video processor to the latest image it holds

Parameters:

force (bool)

Return type:

bool

abstractmethod async set_unit_dhcp()

switch the unit to an IP configuration from DHCP

Return type:

bool

abstractmethod async set_unit_network(network)

give the unit a static IP configuration

Parameters:

network (UnitNetConfig)

Return type:

bool

abstractmethod async confirm_unit_network()

keep the unit’s pending IP configuration

Return type:

bool

abstract property oneip_downmix: OneIPDownmix | None

How this OneIP device’s output mixes down to stereo, as it last reported, None while it reports no downmix: until its video processor has answered for it, and always for one whose output cannot mix down.

abstract property oneip_ptp: OneIPPtpState | None

The PTP state this OneIP device last reported about itself, None until it has reported one, and while it has no PTP to report: none on its video processor, or in power save.

abstract property oneip_testcard: OneIPTestcard | None

The test card this OneIP sink last reported, None until it has.

A sink reports it only when asked or in answer to a change.

abstract property time_zone: TimeZone | None

The time zone this device announced for its mesh, None until it has.

The mesh controller announces it with every periodic broadcast, empty when it has none.

abstract property clock: datetime | None

This device’s clock as of now, None until it has announced one.

The time it last announced, advanced by how long ago that arrived. The mesh controller announces its clock with every periodic broadcast, and only once it has been set.

abstract property oneip_source_local: OneIPStreamSources | None

local v2ip source addresses

abstract property mesh_master: DeviceBase | None

The device that is the master device in the OneIP mesh to which this device belongs

abstract property mesh_master_uid: MxrDeviceUid | None

UID of the mesh controller this device reports, None while it has named none.

Distinct from mesh_master, which falls back to the device itself. A device that has named no controller is not a device that follows nobody: a client that has just started knows nothing about anyone for as long as a broadcast period.

abstract property protocol: int

Highest protocol version this device advertises, or 0 if none has been seen.

abstractmethod supports_opcode(opcode)

True when this device can receive opcode.

Each opcode has a minimum protocol version, and a device whose cap is lower drops the frame without answering - there is no NAK at any layer, so an ungated send looks like success. A device that has advertised no version yet returns True: refusing on that would break every send made before the first hello arrives, and the firmware itself only compares against a version it has.

Parameters:

opcode (int)

Return type:

bool

abstract property is_mesh_master: bool

True if this device is the master device of a OneIP mesh

abstract property is_management: bool

True when this device announces itself as a writer of other devices’ configuration: MANAGER, which external management applications set and no device firmware does, or MESH_MASTER, which a controlling device sets.

Whether a unit takes a write from it is the unit’s question, not this device’s. A unit takes one from a MANAGER, or from the controller it follows (its mesh_master_uid), whatever bits that controller announces; MESH_MASTER stands in for that only until the unit has named one.

abstract property is_oneip_sink: bool

True if this device decodes a OneIP stream, which is what carries the scaling settings

abstract property is_mesh_member: bool

True if this device is a member of a OneIP mesh

abstract property is_oneip_multiviewer: bool

True if this device is a OneIP Multiviewer

abstract property supports_video_wall: bool

True if this sink can crop its source to a video wall window (MXR_FEATURE_VIDEO_WALL)

abstract property config_initialised: bool

True if every configuration block this device broadcasts is fully written.

A device without MXR_FEATURE_CONFIG_INITIALISED builds some config payloads from stack locals it never zeroes, so these are unreliable from it: the scaling block in V2IP_DEVICE_CFG, bay 0’s addresses in SYS_BAY_V2IP_SOURCES, and the padding beside the rc target in RC_SETTINGS. None of that is detectable within a frame.

abstract property is_oneip_tz: bool

True if this device is a OneIP Transceiver

abstract property is_oneip_tx: bool

True if this device is a OneIP Transmitter

abstract property is_oneip_rx: bool

True if this device is a OneIP Receiver

abstract property crashed_recently: bool

True if a crash caused this device to reboot

abstract property dolby_settings: AmpDolbySettings | None

Dolby Digital settings (proamp)

abstract property oneip_firmware_versions: dict[FirmwareType, FirmwareVersion] | None

OneIP video processor firmware versions

abstractmethod oneip_source(bay)

Get the OneIP source addresses for the given bay

Parameters:

bay (BayBase)

Return type:

OneIPStreamSources | None

abstractmethod get_by_portnum(portnum)

Get the bay with the given number on this device

Parameters:

portnum (int)

Return type:

BayBase | None

abstractmethod get_by_portname(portname)

Get the bay with the given port name (not user set name) on this device

Parameters:

portname (str)

Return type:

BayBase | None

abstract property network_status: dict[int, NetworkPortStatus]

network status for all ports

abstract property status_message: str

system health status

abstractmethod merge_oneip_sources(first, total, page)

merge one frame of this device’s OneIP source list into the cached list

Parameters:

• first (int)

• total (int)

• page (OneIPStreamSourcesList)

Return type:

None

abstractmethod note_link_config()

internal callback: a page of the link configuration was received

Return type:

None

abstractmethod note_bay_config()

internal callback: the primary bay configuration was received

Return type:

None

abstractmethod async get_api(uri)

call an HTTP API method and return the result

Parameters:

uri (str)

Return type:

dict[str, Any] | None

abstractmethod register_callback(callback)

register a callback, called when the device state changed

Parameters:

callback (Callable[[DeviceBase], None])

Return type:

None

abstractmethod unregister_callback(callback)

unregister a callback

Parameters:

callback (Callable[[DeviceBase], None])

Return type:

None

clear_v2ip_output_mode

use clear_oneip_output_mode.

Type:

Deprecated

is_v2ip

use is_oneip.

Type:

Deprecated

is_v2ip_sink

use is_oneip_sink.

Type:

Deprecated

merge_v2ip_sources

use merge_oneip_sources.

Type:

Deprecated

abstractmethod async reboot()

reboot this device

Return type:

bool

set_v2ip_auto_power_save

use set_oneip_auto_power_save.

Type:

Deprecated

set_v2ip_auto_scaling

use set_oneip_auto_scaling.

Type:

Deprecated

set_v2ip_ir_profile

use set_oneip_ir_profile.

Type:

Deprecated

set_v2ip_output_mode

use set_oneip_output_mode.

Type:

Deprecated

set_v2ip_power_save_schedule

use set_oneip_power_save_schedule.

Type:

Deprecated

set_v2ip_setting

use set_oneip_setting.

Type:

Deprecated

set_v2ip_sink_ir_profile

use set_oneip_sink_ir_profile.

Type:

Deprecated

v2ip_details

use oneip_details.

Type:

Deprecated

v2ip_features

use oneip_features.

Type:

Deprecated

v2ip_firmware_versions

use oneip_firmware_versions.

Type:

Deprecated

v2ip_settings

use oneip_settings.

Type:

Deprecated

v2ip_sink

use oneip_sink.

Type:

Deprecated

v2ip_source

use oneip_source.

Type:

Deprecated

v2ip_source_local

use oneip_source_local.

Type:

Deprecated

v2ip_sources

use oneip_sources.

Type:

Deprecated

v2ip_stats

use oneip_stats.

Type:

Deprecated

abstractmethod async ping()

ask this device to announce itself now

Return type:

bool

abstractmethod async mesh_promote()

promote to mesh master

Return type:

bool

abstractmethod async auto_assign_oneip_source_addresses()

hand this OneIP source’s stream addresses back to automatic assignment

Return type:

bool

abstractmethod async mesh_remove()

remove from mesh

Return type:

bool

abstractmethod async read_stats(enable)

start or stop dumping stats

Parameters:

enable (bool)

Return type:

bool

abstractmethod async set_oneip_auto_scaling(enabled)

turn this sink’s automatic scaling on or off

Parameters:

enabled (bool)

Return type:

bool

abstractmethod async set_oneip_output_mode(mode)

set the output format this sink scales to

Parameters:

mode (OneIPOutputMode)

Return type:

bool

abstractmethod async clear_oneip_output_mode()

clear the output format this sink is configured to scale to

Return type:

bool

abstractmethod async set_oneip_setting(setting, enabled)

switch on/off OneIP device settings, all to the same value

Parameters:

• setting (OneIPDeviceSetting)

• enabled (bool)

Return type:

bool

abstractmethod async set_oneip_ir_profile(profile)

set the infrared profile of the device’s global infrared port

Parameters:

profile (int)

Return type:

bool

abstractmethod async set_oneip_sink_ir_profile(profile)

set the infrared profile of the device’s output infrared port

Parameters:

profile (int)

Return type:

bool

abstractmethod async set_oneip_auto_power_save(minutes)

set the idle minutes before the device powers down by itself, 0 for never

Parameters:

minutes (int)

Return type:

bool

abstractmethod async set_oneip_power_save_schedule(schedule)

set the device’s daily power save windows

Parameters:

schedule (OneIPPowerSaveSchedule)

Return type:

bool

abstractmethod async set_oneip_ptp_mode(mode)

set the PTP mode the device runs

Parameters:

mode (OneIPPtpMode)

Return type:

bool

abstractmethod async set_oneip_ptp_domain(domain)

set the PTP domain the device runs in

Parameters:

domain (int)

Return type:

bool

abstractmethod async set_oneip_ptp_priority1(priority1)

set the priority1 the device announces as a PTP grandmaster

Parameters:

priority1 (int)

Return type:

bool

abstractmethod async set_oneip_power_save(enabled)

switch power save on, so the device powers down by itself to the level it picks, or off

Parameters:

enabled (bool)

Return type:

bool

abstractmethod async set_oneip_power_save_level(level)

write the level the device powers down to in power save, which switches power save on

Parameters:

level (OneIPPowerSaveLevel)

Return type:

bool

abstractmethod async set_oneip_ptp_messages(which, messages)

set how the device paces its PTP messages, its SAP timings and its streams’ TTL: the values of messages behind the bits of which

Parameters:

• which (OneIPDeviceSetting)

• messages (OneIPPtpMessages)

Return type:

bool

abstractmethod async set_oneip_downmix(downmix)

set how the device’s output mixes down to stereo

Parameters:

downmix (OneIPDownmix)

Return type:

bool

abstractmethod async set_oneip_vlan(vlan)

change the device’s VLAN configuration

Parameters:

vlan (OneIPVlan)

Return type:

bool

abstractmethod async set_audio_endpoint_locked(endpoint, locked)

lock or unlock the audio source of one of this device’s audio endpoints

Parameters:

• endpoint (int)

• locked (bool)

Return type:

bool

abstractmethod async request_oneip_testcard()

ask this sink for its test card

Return type:

bool

abstract property osd_sync: OsdSync | None

The last overlay sync this management unit sent, None until it has.

abstract property osd_sync_report: OsdSyncReport | None

This unit’s last report on taking an overlay sync, None until it has.

abstract property osd_message: OsdMessage | None

The message on this unit’s output, as it last reported it to this client, None until it has. A unit reports it only when asked, or when this client writes it.

abstractmethod async request_osd_message()

ask this unit for the message on its output

Return type:

bool

abstractmethod async show_osd_message(text, logo=-1, priority=OsdMessagePriority.NORMAL)

show a message on this unit’s output, in place of any it has

Parameters:

• text (str)

• logo (int)

• priority (OsdMessagePriority)

Return type:

bool

abstractmethod async clear_osd_message()

take the message down from this unit’s output

Return type:

bool

abstract property oneip_sink_sdp: OneIPSinkSdp | None

What this OneIP output plays from a session description, as it last reported it, None until it has. It reports when that changes and at least once a minute.

abstract property oneip_privacy: OneIPPrivacy | None

How this OneIP source unit’s streams are encrypted, as it last reported it, None until it has. It reports when that changes and at least once a minute.

abstractmethod async request_oneip_privacy()

ask this OneIP source unit how its streams are encrypted now

Return type:

bool

abstractmethod async play_oneip_sdp(sdp)

have this OneIP output play the stream a session description describes

Parameters:

sdp (str)

Return type:

bool

abstractmethod async stop_oneip_sdp()

stop the stream this OneIP output plays from a session description

Return type:

bool

abstractmethod async set_oneip_sdp_screen(screen)

set what this OneIP output shows while it plays audio alone, as the wire value

Parameters:

screen (int)

Return type:

bool

abstractmethod async request_oneip_sink_sdp()

ask this OneIP output what it plays from a session description now

Return type:

bool

abstractmethod async set_oneip_test_pattern(pattern, colour=0)

show a test pattern on this sink’s output

Parameters:

• pattern (OneIPTestPattern)

• colour (int)

Return type:

bool

abstractmethod async set_oneip_test_tone(tone)

play a test tone on this sink’s output

Parameters:

tone (OneIPTestTone)

Return type:

bool

abstractmethod async set_oneip_test_sync(sync)

set this sink’s lip-sync flash

Parameters:

sync (OneIPTestSync)

Return type:

bool

abstractmethod async get_log()

read the log from the device and return it as string

Return type:

str | None

class mx_remote.Interface.Multiviewer

Bases: ABC

class mx_remote.Interface.BayLink

Bases: object

a virtual mx_remote link between bays, like an amp output that’s linked to a oneip sink

__init__(registry, bay, linked_serial, linked_bay, features)

Parameters:

• registry (DeviceRegistry)

• bay (BayBase)

• linked_serial (str)

• linked_bay (str)

• features (int)

Return type:

None

property serial: str

serial number of the linked device

property linked_bay_name: str

bay name of the linked bay

property bay: BayBase

origin bay

property linked_bay: BayBase | None

linked bay

property linked: bool

True if a link has been set up

property other_link: BayLink | None

the link instance of the linked bay

property connected: bool

True if both sides have been set up

property online: bool

True if both sides are online

property is_audio: bool

True if this is an audio link

property is_video: bool

True if this is a video link

property features: list[str]

supported link features as list of string

property features_mask: LinkFeature

supported link features as bitmask

class mx_remote.Interface.BayLinks

Bases: object

linked bay configurations for all devices

__init__(registry)

Parameters:

registry (DeviceRegistry)

Return type:

None

class mx_remote.Interface.DeviceRegistry

Bases: ABC

all mx_remote devices on the network

abstract property local_ip: str | None

local ip address

abstract property broadcast: bool

broadcast or multicast

abstract property library_version: str

version of the mx_remote library

abstract property protocol_version: int

protocol version used by this library

abstract property net_protocol_version_max: int

highest protocol version used by devices on the network

abstract property net_protocol_version_min: int

lowest protocol version used by devices on the network

abstract property uid_raw: bytes | None

uid of this device as bytes

property uid: MxrDeviceUid

uid of this device

abstract property name: str

device name

abstract property callbacks: MxrCallbacks

callbacks to call when the device is updated

abstractmethod transmit(data)

transmit data to this device (broadcast/multicast)

Parameters:

data (bytes)

Return type:

int

abstract property links: BayLinks

linked bay configurations for all devices

abstractmethod get_by_serial(serial)

get a device by its serial number

Parameters:

serial (str)

Return type:

DeviceBase | None

abstractmethod get_by_uid(remote_id)

get a device by its unique id

Parameters:

remote_id (str | MxrDeviceUid | None)

Return type:

DeviceBase | None

abstractmethod uid_to_user_string(remote_id)

return the serial of the unit if the uid is known, or the uid as string if it isn’t

Parameters:

remote_id (str | MxrDeviceUid | bytes | None)

Return type:

str

abstractmethod get_bay_by_portnum(remote_id, portnum)

get a bay of a device by its unique id and port number

Parameters:

• remote_id (str | MxrDeviceUid)

• portnum (int)

Return type:

BayBase | None

abstractmethod get_bay_by_portname(remote_id, portname)

get a bay of a device by its unique id and port name

Parameters:

• remote_id (str | MxrDeviceUid)

• portname (str)

Return type:

BayBase | None

abstractmethod get_by_stream_ip(ip, audio=False)

get a bay of a device by its OneIP stream address

Parameters:

• ip (str)

• audio (bool)

Return type:

BayBase | None

class mx_remote.Interface.ConnectionCallbacks

Bases: ABC

property target_ip: str

target ip address

abstractmethod on_connection_made()

called when the socket was opened

Return type:

None

abstractmethod on_datagram_received(data, addr)

called when a datagram was received

Parameters:

• data (bytes)

• addr (tuple[str, int])

Return type:

None

class mx_remote.Interface.MxrCallbacks

Bases: object

callbacks that can be used by an external application to get notified when a status changes

on_device_update(dev)

called when properties of ‘dev’ have been updated

Parameters:

dev (DeviceBase)

Return type:

None

on_bay_update(bay)

called when properties of ‘bay’ have been updated

Parameters:

bay (BayBase)

Return type:

None

on_device_config_changed(dev)

called when device configuration properties of ‘dev’ have been updated

Parameters:

dev (DeviceBase)

Return type:

None

on_device_config_complete(dev)

called when device configuration of ‘dev’ had been received fully

Parameters:

dev (DeviceBase)

Return type:

None

on_device_online_status_changed(dev, online)

called when the online status of ‘dev’ changed

Parameters:

• dev (DeviceBase)

• online (bool)

Return type:

None

on_bay_registered(bay)

called when a new bay was registered by mx_remote

Parameters:

bay (BayBase)

Return type:

None

on_device_temperature_changed(dev)

called when the temperature values of ‘dev’ changed

Parameters:

dev (DeviceBase)

Return type:

None

on_power_changed(bay, power)

called when the power status of ‘bay’ changed

Parameters:

• bay (BayBase)

• power (PowerStatus)

Return type:

None

on_name_changed(bay, user_name)

called when the name that’s set up by the user of ‘bay’ changed

Parameters:

• bay (BayBase)

• user_name (str)

Return type:

None

on_status_signal_detected_changed(bay, val)

called when the signal detect status of ‘bay’ changed

Parameters:

• bay (BayBase)

• val (bool)

Return type:

None

on_status_faulty_changed(bay, val)

called when the fault status of ‘bay’ changed

Parameters:

• bay (BayBase)

• val (bool)

Return type:

None

on_status_hidden_changed(bay, val)

called when the hidden status of ‘bay’ changed

Parameters:

• bay (BayBase)

• val (bool)

Return type:

None

on_status_zone_powered_changed(bay, val)

called when the amplifier zone ‘bay’ drives is powered on or off

Parameters:

• bay (BayBase)

• val (bool)

Return type:

None

on_status_poe_powered_changed(bay, val)

Deprecated: override on_status_zone_powered_changed. A subclass that still overrides this is called in its place.

Parameters:

• bay (BayBase)

• val (bool)

Return type:

None

on_status_hdbt_connected_changed(bay, val)

called when the HDBaseT connection status of ‘bay’ changed

Parameters:

• bay (BayBase)

• val (bool)

Return type:

None

on_osd_sync(dev, sync)

called when management unit ‘dev’ sent an overlay sync

Parameters:

• dev (DeviceBase)

• sync (OsdSync)

Return type:

None

on_osd_sync_report(dev, report)

called when unit ‘dev’ reported on taking an overlay sync

Parameters:

• dev (DeviceBase)

• report (OsdSyncReport)

Return type:

None

on_osd_message_changed(dev, message)

called when unit ‘dev’ reported something different about the message on its output

Parameters:

• dev (DeviceBase)

• message (OsdMessage)

Return type:

None

on_osd_sync_requested(dev, request)

called when ‘dev’ asked for an overlay sync, or for settings of one

Parameters:

• dev (DeviceBase)

• request (OsdSyncRequest)

Return type:

None

on_osd_sync_setting(dev, setting)

called when management unit ‘dev’ sent a unit a setting of an overlay sync

Parameters:

• dev (DeviceBase)

• setting (OsdSyncSetting)

Return type:

None

on_bay_content_changed(bay, content)

called when what the source on input ‘bay’ shows changed

Parameters:

• bay (BayBase)

• content (BayContent)

Return type:

None

on_status_signal_type_changed(bay, val)

called when the detected signal of ‘bay’ changed

Parameters:

• bay (BayBase)

• val (str)

Return type:

None

on_status_hpd_detected_changed(bay, val)

called when the HPD value of ‘bay’ changed

Parameters:

• bay (BayBase)

• val (bool)

Return type:

None

on_status_cec_detected_changed(bay, val)

called when a CEC device was detected on ‘bay’

Parameters:

• bay (BayBase)

• val (bool)

Return type:

None

on_status_arc_changed(bay, val)

called when the audio return channel status of ‘bay’ changed

Parameters:

• bay (BayBase)

• val (str)

Return type:

None

on_volume_changed(bay, volume)

called when the volume/mute status of ‘bay’ changed

Parameters:

• bay (BayBase)

• volume (VolumeMuteStatus | None)

Return type:

None

on_key_pressed(bay, key)

called when a key press was detected on ‘bay’

Parameters:

• bay (BayBase)

• key (RCKey)

Return type:

None

on_action_received(bay, action)

called when a remote control action was detected on ‘bay’

Parameters:

• bay (BayBase)

• action (RCAction)

Return type:

None

on_video_source_changed(bay, video_source)

called when a video source changed was detected on ‘bay’

Parameters:

• bay (BayBase)

• video_source (BayBase | None)

Return type:

None

on_audio_source_changed(bay, audio_source)

called when an audio source changed was detected on ‘bay’

Parameters:

• bay (BayBase)

• audio_source (BayBase | None)

Return type:

None

on_bay_linked(bay, linked_serial, linked_bay, features)

called when a bay link was detected

Parameters:

• bay (BayBase)

• linked_serial (str)

• linked_bay (str)

• features (int)

Return type:

None

on_bay_unlinked(bay, linked_serial, linked_bay)

called when a bay link was removed

Parameters:

• bay (BayBase)

• linked_serial (str)

• linked_bay (str)

Return type:

None

on_mirror_status_changed(bay, mirror)

called when a bay mirroring setup change was detected

Parameters:

• bay (BayBase)

• mirror (BayMirrorStatus)

Return type:

None

on_filter_status_changed(bay, filtered)

called when a bay filtering setup change was detected

Parameters:

• bay (BayBase)

• filtered (list[MxrDeviceUid])

Return type:

None

on_edid_profile_changed(bay, profile)

called when a source EDID profile was changed

Parameters:

• bay (BayBase)

• profile (EdidProfile | None)

Return type:

None

on_rc_type_changed(bay, rc_type)

called when a source remote control type was changed

Parameters:

• bay (BayBase)

• rc_type (RCType | None)

Return type:

None

on_amp_zone_settings_changed(bay, settings)

called when amp zone settings were changed

Parameters:

• bay (BayBase)

• settings (AmpZoneSettings)

Return type:

None

on_amp_dolby_settings_changed(device, settings)

called when amp dolby settings were changed

Parameters:

• device (DeviceBase)

• settings (AmpDolbySettings)

Return type:

None

Bay content

What the source on an input is showing, and how much of it a unit keeps.

mx_remote.proto.Constants.BAY_CONTENT_KEY_MAX = 31

The most bytes in a BayContentField key.

mx_remote.proto.Constants.BAY_CONTENT_VALUE_MAX = 255

The most bytes in a BayContentField value, UTF-8 encoded.

Overlay sync

A management unit having other units copy its overlay captions, logo choice and place, backgrounds and logo images.

class mx_remote.proto.Constants.OsdSyncWhat

Bases: IntFlag

What an overlay sync copies.

LOGO = 2

Which logo is shown, and where.

BACKGROUNDS = 4

Background colours.

LOGO_SLOTS = 8

The logo images in the four slots.

__new__(value)

class mx_remote.proto.Constants.OsdSyncState

Bases: IntEnum

How far a unit has got with taking an overlay sync.

DONE = 1

Every setting written and committed.

FAILED = 2

Failed, for the reason the report gives.

DEFERRED = 3

Kept for later, as the unit’s video processor is off in power save.

__new__(value)

class mx_remote.proto.Constants.OsdSyncSize

Bases: IntEnum

The output size an overlay setting applies at.

LARGE = 1

Large outputs, which every value but SMALL also means.

__new__(value)

class mx_remote.proto.Constants.OsdCaptionAlign

Bases: IntEnum

How a caption’s lines are aligned.

DEFAULT = 255

The layout’s default.

__new__(value)

class mx_remote.proto.Constants.OsdCaptionFormat

Bases: IntEnum

How a caption’s text is read.

DEFAULT = 255

The layout’s default.

__new__(value)

class mx_remote.proto.Constants.OsdCaptionField

Bases: IntFlag

The caption fields an overlay setting gives. A field left out keeps what the unit has.

__new__(value)

class mx_remote.proto.Constants.OsdLogoField

Bases: IntFlag

The logo fields an overlay setting gives. A field left out keeps what the unit has.

__new__(value)

mx_remote.proto.Constants.OSD_SYNC_SLOTS = 4

The logo slots an overlay sync can copy.

mx_remote.proto.Constants.OSD_SYNC_RECORDS_MAX = 128

The most settings one overlay sync carries.

mx_remote.proto.Constants.OSD_SYNC_FONT_MAX = 31

The longest caption font name, in bytes.

mx_remote.proto.Constants.OSD_SYNC_TEXT_MAX = 360

The longest caption text a unit shows, in bytes. It cuts a longer one short.

mx_remote.proto.Constants.OSD_SYNC_IMAGE_MAX = 524288

The largest logo image a unit takes, in bytes.

mx_remote.proto.Constants.OSD_SYNC_IMAGE_WIDTH_MAX = 1920

The widest logo image a unit takes, in pixels.

mx_remote.proto.Constants.OSD_SYNC_IMAGE_HEIGHT_MAX = 1080

The tallest logo image a unit takes, in pixels.

mx_remote.proto.Constants.OSD_SYNC_PERCENT_MAX = 100

The largest size a logo is shown at, in percent.

Overlay messages

The message on a unit’s output, which the overlay sync opcode carries too.

class mx_remote.OsdMessage

Bases: object

The message on a unit’s output, as the unit last reported it. The unit holds it until it restarts.

flags: OsdMessageFlag

Whether a message is set and shown, whether the unit can show one, and whether it refused the write it answers. Without SET the other fields are empty.

logo: int

0 the built-in logo, -1 none, 1 to 5 a slot.

Type:

The logo shown with it

priority: OsdMessagePriority | int

Where it stands against the unit’s own messages.

text: str

Its markup.

__init__(flags, logo, priority, text)

Parameters:

• flags (OsdMessageFlag)

• logo (int)

• priority (OsdMessagePriority | int)

• text (str)

Return type:

None

class mx_remote.proto.Constants.OsdMessageFlag

Bases: IntFlag

What a unit says of the message on its output.

SET = 1

show it, rather than take it down.

Type:

A message is set. In a write

SHOWN = 2

The output shows it, rather than another message ahead of it.

SUPPORTED = 4

The unit’s video processor composes the message layer.

REFUSED = 8

The unit did not take the write it answers, and reports the message it kept.

__new__(value)

class mx_remote.proto.Constants.OsdMessagePriority

Bases: IntEnum

Where a message stands against the unit’s own messages: its upgrade, Locate Device and encrypted source messages.

LOW = 0

After them.

NORMAL = 1

Between them.

TOP = 2

Before them.

__new__(value)

mx_remote.proto.Constants.OSD_MESSAGE_TEXT_MAX = 255

The longest message text a unit takes, in bytes.

Device identity

Unique device and bay identifier types for mx_remote.

class mx_remote.Uid.MxrDeviceUid

Bases: object

Unique ID of an mx_remote device on the network

__init__(value)

Parameters:

value (object)

Return type:

None

property value: str

value as human readable string, formatted once, as every hash and comparison reads it

property empty: bool

True if all 0

property byte_value: bytes

value as bytes

class mx_remote.Uid.MxrBayUidOld

Bases: object

Legacy bay identifier using serial number and port name.

__init__(serial, port_name)

Parameters:

• serial (str)

• port_name (str)

Return type:

None

class mx_remote.Uid.MxrBayUid

Bases: object

Bay identifier using a device UID and port number.

__init__(device, port_number)

Parameters:

• device (MxrDeviceUid)

• port_number (int)

Return type:

None

Remote-control keys and actions

The key and action codes a bay reports, and the target a key was aimed at.

class mx_remote.proto.Constants.RCKey

Bases: IntEnum

Remote control key codes (CEC/IR).

__new__(value)

KEY_0 = 0

KEY_1 = 1

KEY_2 = 2

KEY_3 = 3

KEY_4 = 4

KEY_5 = 5

KEY_6 = 6

KEY_7 = 7

KEY_8 = 8

KEY_9 = 9

KEY_SELECT = 10

KEY_BACK = 11

KEY_UP = 12

KEY_DOWN = 13

KEY_LEFT = 14

KEY_RIGHT = 15

KEY_MENU = 16

KEY_CONTENT_MENU = 17

KEY_CHANNEL_UP = 18

KEY_CHANNEL_DOWN = 19

KEY_PLAY = 20

KEY_PAUSE = 21

KEY_STOP = 22

KEY_RECORD = 23

KEY_FAST_FORWARD = 24

KEY_REWIND = 25

KEY_RED = 26

KEY_GREEN = 27

KEY_YELLOW = 28

KEY_BLUE = 29

KEY_HELP = 30

KEY_INFORMATION = 31

KEY_TEXT = 32

KEY_GUIDE = 33

KEY_VIDEO_ON_DEMAND = 34

KEY_PREVIOUS_CHANNEL = 80

KEY_3D_MODE = 81

KEY_SUBTITLE = 82

KEY_SOUND_SELECT = 83

KEY_INPUT_SELECT = 84

KEY_EJECT = 85

KEY_NEXT_CHAPTER = 86

KEY_PREVIOUS_CHAPTER = 87

KEY_CUSTOM_CEC = 1280

KEY_INTERACTIVE = 128

KEY_SEARCH = 129

KEY_SKY = 130

KEY_CUSTOM_SKY = 2048

class mx_remote.proto.Constants.RCAction

Bases: IntEnum

Remote control actions.

__new__(value)

ACTION_POWER_TOGGLE = 0

ACTION_POWER_ON = 1

ACTION_POWER_OFF = 2

ACTION_VOLUME_UP = 3

ACTION_VOLUME_DOWN = 4

ACTION_VOLUME_MUTE = 5

class mx_remote.proto.Constants.RCType

Bases: IntEnum

Remote control protocol type.

__new__(value)

IR = 0

CEC = 1

SKY_UK = 2

TIVO = 3

KODI = 4

DISH = 5

DIRECTV = 6

MX_REMOTE = 7

INTERNAL = 8

Routed inside the device itself.

static values()

Return type:

dict[int, str]

mx_remote.proto.Constants.MXR_PROTOCOL_VERSION = 48

Highest mx_remote protocol version this library understands.

Mirrors the firmware’s own protocol version. Bump when adding RX support for an opcode revision; transmitters stamp the per-opcode minimum from MXR_OPCODE_VERSIONS so older peers still parse the frame.

This is also a receive ceiling: Remote.process_frame drops any frame stamped above it, unparsed. So it has to reach the stamp of every layout revision decoded below, or that revision goes silent on the mesh rather than noisy - 0x29 is what a MatrixOS 10.12.46 unit stamps on V2IP_STATS.

0x2A is also what MatrixOS reads a hello by: a device on 0x2A or later is given 60s to hello again rather than 15s, and a unit only slows its own hello to one every 20-30s once every device it knows is on 0x2A.

0x2B is the row of V2IP_TESTCARD, so a sink’s test card report arrives stamped 0x2B.

0x2E is the row of V2IP_SINK_SDP, so an output’s session description report arrives stamped 0x2E, 0x2F the row of V2IP_OSD_SYNC and 0x30 the row of V2IP_PRIVACY.

OneIP device settings

The settings a OneIP device reports and a controller writes, each behind its own bit, and the range of the infrared profiles.

class mx_remote.proto.Constants.OneIPDeviceSetting

Bases: IntFlag

The device settings a OneIP configuration can carry, each on its own bit.

The same bits serve as the settings a frame carries and as the values of the on/off ones among them. IR_PROFILE to POWER_SAVE_SCHEDULE and the PTP settings carry a value elsewhere in the block and have no on/off value of their own.

A device reports every setting it has, so one it never reports is one it does not have.

SINK_CHECK_POWER = 1

Disables the decoder while the display is off.

SINK_OFF_NO_SIGNAL = 2

Disables the HDMI output while there is no signal.

IR_TX_MODULATED = 4

Sends infrared modulated.

STATUS_LED = 8

Lights the status LED.

NETWORK_LED = 16

Lights the network port LEDs.

FAN_QUIET = 32

Runs the fan in quiet mode.

CEC_COMBO_KEYS = 64

Accepts CEC combo keys.

CEC_COMBO_INPUT = 128

Accepts CEC combo keys for the device’s own input.

IR_PROFILE = 256

The infrared profile of the device’s global infrared port.

IR_PROFILE_SINK = 512

The infrared profile of the output’s infrared port.

IR_PROFILES = 1024

The infrared profiles stored on the device. Reported by the device itself and never written.

AUTO_POWER_SAVE = 2048

The minutes a device stays idle before it powers down by itself.

POWER_SAVE_SCHEDULE = 4096

The daily windows in which the device powers down.

CLOCK_SET = 8192

The device’s clock has been set, on/off. Reported by the device itself and never written.

PTP_MODE = 16384

The PTP mode the device runs.

PTP_DOMAIN = 32768

The PTP domain the device runs in.

PTP_PRIORITY1 = 65536

The priority1 the device announces as a PTP grandmaster.

AES67 = 131072

Sends the source’s audio as an AES67 flow, where the source allows.

POWER_SAVE_LEVEL = 262144

The level the device powers down to in power save. A device picks it itself: the level that saves the most while its input and display can still wake it. Written without POWER_SAVE_DISABLED, it switches power save on, and the level written is ignored, except by a device whose firmware predates picking it, which takes the level as its setting.

PTP_ANNOUNCE = 524288

The interval between the device’s PTP announce messages.

PTP_SYNC = 1048576

The interval between the device’s PTP sync messages.

PTP_DELAY_REQ = 2097152

The interval between the device’s PTP delay requests.

PTP_ANNOUNCE_TIMEOUT = 4194304

The announce intervals before the device drops a silent PTP master.

PTP_DSCP = 8388608

The DSCP of the device’s PTP messages.

SAP_EXPIRE = 16777216

The minutes after which the device forgets a SAP announcement it heard.

SAP_LISTEN = 33554432

Listens for SAP announcements.

SAP_ANNOUNCE = 67108864

Sends SAP announcements.

SAP_INTERVAL = 134217728

The seconds between the device’s SAP announcements.

POWER_SAVE_DISABLED = 268435456

automatic power save and the power save schedule leave the device running, and switching this on wakes a device either has powered down. A power save request still powers it down. Writing POWER_SAVE_LEVEL switches it off.

Type:

Never powers down by itself

STREAM_TTL = 536870912

The TTL of the device’s streams, video, audio and ancillary alike. Reported only by a device with an encoder.

CLOUD = 1073741824

Connects to the cloud service. A device that does not report it connects regardless.

SINK_ROTATION = 2147483648

The angle the device’s HDMI output is turned by. Reported only by a device with an HDMI output.

__new__(value)

mx_remote.proto.Constants.ONEIP_DEVICE_SETTING_SWITCHES = <OneIPDeviceSetting.SINK_CHECK_POWER|SINK_OFF_NO_SIGNAL|IR_TX_MODULATED|STATUS_LED|NETWORK_LED|FAN_QUIET|CEC_COMBO_KEYS|CEC_COMBO_INPUT|AES67|SAP_LISTEN|SAP_ANNOUNCE|POWER_SAVE_DISABLED|CLOUD: 1442971903>

The settings that are on or off, as opposed to carrying a value, and that can be written.

mx_remote.proto.Constants.ONEIP_IR_PROFILE_NOT_SET = -1

The infrared profile an output’s port reports when it follows the device’s global one.

mx_remote.proto.Constants.ONEIP_IR_PROFILE_MAX = 18

the default profile is 0, the Atlona profile 1, and user-defined profiles 1 to 16 are 2 to 17.

Type:

One past the highest infrared profile

mx_remote.proto.Constants.ONEIP_DEVICE_SETTINGS_REPORTED_ONLY = <OneIPDeviceSetting.IR_PROFILES|CLOCK_SET: 9216>

The settings only a device reports about itself, which no write carries.

mx_remote.proto.Constants.ONEIP_MINUTES_PER_DAY = 1440

every time in a power save schedule is below this.

Type:

Minutes in a day

class mx_remote.OneIPPowerSaveSchedule

Bases: object

A OneIP device’s daily power save windows, Monday first, in the device’s time zone.

Day d powers down at start[d] and up again at end[d], both in minutes after midnight. A window belongs to the day it starts on and runs past midnight into the next when it ends before it starts; one that ends where it starts means no window that day.

__init__(start=(0, 0, 0, 0, 0, 0, 0), end=(0, 0, 0, 0, 0, 0, 0))

Parameters:

• start (tuple[int, ...])

• end (tuple[int, ...])

Return type:

None

property start: tuple[int, ...]

When each day’s window starts.

property end: tuple[int, ...]

When each day’s window ends.

window(day)

The window of day, Monday being 0, or None for a day without one or past Sunday.

Parameters:

day (int)

Return type:

tuple[int, int] | None

is_valid()

Whether every time is a time of day.

Return type:

bool

class mx_remote.proto.Constants.OneIPPowerSaveLevel

Bases: IntEnum

How far a OneIP device powers down in power save, each level saving more than the one before.

NONE = 0

No level.

REDUCED = 1

Part of the video processing powers down.

LOW = 2

All of the video processing powers down.

OFF = 3

Everything but the network powers down.

__new__(value)

class mx_remote.OneIPVlan

Bases: object

VLAN tagging on a OneIP device’s uplink.

Only the device knows what it runs, so this is what it reported about itself. A change written to it is applied at once and stays PENDING until the mesh controller confirms it, which proves the device still reaches the mesh and the mesh still reaches it; unconfirmed, the device reverts it.

flags: OneIPVlanFlag = 0

The block’s flags.

device: int = 0

The VLAN id of the device’s own traffic, 0 for untagged.

port: tuple[int, ...] = (0, 0, 0)

The VLAN id each downlink port carries, 0 to share the device’s untagged traffic, indexed as ONEIP_VLAN_PORTS orders them.

uplink: int = 0

The port pinned as the uplink as 1 + its index, 0 to detect it.

active_uplink: int = 0

the port in use as the uplink, as 1 + its index.

Type:

Reported by the device

revert_s: int = 0

the seconds before a pending configuration is reverted.

Type:

Reported by the device

property trunk: bool

Whether untagged frames arriving on the uplink are dropped.

property is_pending: bool

Whether the device reverts this configuration unless the mesh controller confirms it.

property has_sfp: bool

Whether the device has an SFP port.

property pinned_uplink_port: int | None

The index of the port pinned as the uplink, None when the device detects it.

property active_uplink_port: int | None

The index of the port the device uses as its uplink, None for a value that names no port.

is_valid()

Whether every VLAN id is at most ONEIP_VLAN_ID_MAX and the uplink is detected or names a port.

Return type:

bool

__init__(flags=<OneIPVlanFlag: 0>, device=0, port=(0, 0, 0), uplink=0, active_uplink=0, revert_s=0)

Parameters:

• flags (OneIPVlanFlag)

• device (int)

• port (tuple[int, ...])

• uplink (int)

• active_uplink (int)

• revert_s (int)

Return type:

None

class mx_remote.proto.Constants.OneIPVlanFlag

Bases: IntFlag

The flags of a OneIP device’s VLAN configuration.

VALID = 1

The block carries a configuration. A block without it carries nothing, whatever its other bytes hold.

TRUNK = 2

Untagged frames arriving on the uplink are dropped instead of reaching the device.

PENDING = 4

the configuration is applied, and reverted unless the mesh controller confirms it. Never written.

Type:

Reported by the device

CONFIRM = 8

a pending configuration it heard, which the device then keeps.

Type:

Sent by the mesh controller

HAS_SFP = 16

it has an SFP port. Never written.

Type:

Reported by the device

__new__(value)

mx_remote.proto.Constants.ONEIP_VLAN_PORTS = 3

The external network ports a OneIPVlan covers, in the order of its port field: the SFP port, the UTP port with PoE, then the UTP port.

mx_remote.proto.Constants.ONEIP_VLAN_PORT_SFP = 0

The index of the SFP port in OneIPVlan.port.

mx_remote.proto.Constants.ONEIP_VLAN_ID_MAX = 4094

0 means untagged, and 4095 is reserved by IEEE 802.1Q.

Type:

The highest VLAN id

OneIP stereo downmix

How a device’s output mixes 5.1 and 7.1 PCM down to stereo.

class mx_remote.OneIPDownmix

Bases: object

How a OneIP output mixes 5.1 and 7.1 PCM down to stereo, and whether it does now.

A device reports it once its video processor has answered for it, so never one whose output cannot mix down.

mode: OneIPDownmixMode | int = 0

When the output mixes down; a raw int for a mode this library does not name.

level: OneIPDownmixLevel | int = 0

How loud the mix is; a raw int for a level this library does not name.

lfe: int = 0

The percent the LFE channel is mixed in at, at most ONEIP_DOWNMIX_LFE_MAX; 0 leaves it out.

state: int = 0

Why the stream is or is not mixed down, as the device’s own code. Only the device reports it.

channels: int = 0

The stream’s channels while it is mixed down, else 0. Only the device reports it.

is_valid()

Whether the settings a write carries are in range.

Return type:

bool

written(write)

The settings of write applied to this report, which keeps what only the device reports.

Parameters:

write (OneIPDownmix)

Return type:

OneIPDownmix

__init__(mode=OneIPDownmixMode.OFF, level=OneIPDownmixLevel.NORMALISED, lfe=0, state=0, channels=0)

Parameters:

• mode (OneIPDownmixMode | int)

• level (OneIPDownmixLevel | int)

• lfe (int)

• state (int)

• channels (int)

Return type:

None

class mx_remote.proto.Constants.OneIPDownmixMode

Bases: IntEnum

When a OneIP output mixes 5.1 and 7.1 PCM down to stereo.

OFF = 0

Never.

AUTO = 1

When the display’s EDID lists two PCM channels or fewer.

ALWAYS = 2

Always.

__new__(value)

class mx_remote.proto.Constants.OneIPDownmixLevel

Bases: IntEnum

How loud a OneIP output’s stereo downmix is.

NORMALISED = 0

Scaled so the mix never clips.

UNSCALED = 1

Unscaled, with dialogue at the level it has in stereo.

__new__(value)

mx_remote.proto.Constants.ONEIP_DOWNMIX_LFE_MAX = 100

The largest percent a OneIP output mixes its LFE channel in at.

OneIP PTP

A device’s PTP settings, which it reports and a controller writes, and the PTP state only the device reports.

class mx_remote.OneIPPtpState

Bases: object

A OneIP device’s PTP state, as it reports it about itself.

Only the device can read its own video processor, so this is never written to a device, and a controller’s frame about one carries none.

flags: OneIPPtpFlag = 0

The block’s flags.

mode: OneIPPtpMode | int = 0

The mode the video processor runs; a raw int for one this library does not name.

domain: int = 0

The domain the video processor runs in.

port_state: int = 0

The IEEE 1588 portState.

lock: OneIPPtpLock | int = 0

How far the clock has locked; a raw int for a value this library does not name.

clock_identity: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00'

The device’s own clock identity.

grandmaster_identity: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00'

The clock identity of the grandmaster the device runs on, all zero while it runs on none.

property followed: bool

Whether the device locked to a master since its PTP started, so its mesh holds a time.

property grandmaster: bytes | None

The grandmaster the device runs on, None while it runs on none.

__init__(flags=<OneIPPtpFlag: 0>, mode=OneIPPtpMode.OFF, domain=0, port_state=0, lock=OneIPPtpLock.UNLOCKED, clock_identity=b'\x00\x00\x00\x00\x00\x00\x00\x00', grandmaster_identity=b'\x00\x00\x00\x00\x00\x00\x00\x00')

Parameters:

• flags (OneIPPtpFlag)

• mode (OneIPPtpMode | int)

• domain (int)

• port_state (int)

• lock (OneIPPtpLock | int)

• clock_identity (bytes)

• grandmaster_identity (bytes)

Return type:

None

class mx_remote.proto.Constants.OneIPPtpMode

Bases: IntEnum

How a OneIP device takes part in PTP.

OFF = 0

No PTP.

FOLLOWER = 1

Follows a grandmaster, and never becomes one.

AUTO = 2

Follows a grandmaster, or becomes one when there is none.

__new__(value)

class mx_remote.proto.Constants.OneIPPtpFlag

Bases: IntFlag

The flags of a OneIP device’s PTP state.

VALID = 1

The device runs PTP and the block holds its state. A block without it holds nothing: the device has no PTP, or is in power save.

FOLLOWED = 2

The device locked to a master since its PTP started, so its mesh holds a time.

__new__(value)

class mx_remote.proto.Constants.OneIPPtpLock

Bases: IntEnum

How far a OneIP device’s PTP clock has locked to its master.

UNLOCKED = 0

Not locked.

LOCKING = 1

Locking.

LOCKED = 2

Locked.

__new__(value)

mx_remote.proto.Constants.ONEIP_DEVICE_SETTINGS_PTP = <OneIPDeviceSetting.PTP_MODE|PTP_DOMAIN|PTP_PRIORITY1: 114688>

The PTP settings.

class mx_remote.OneIPPtpMessages

Bases: object

How a OneIP device paces its PTP messages, its SAP timings, its streams’ TTL and its output’s rotation, which a frame carries in the same block. Each value is behind its own bit of OneIPDeviceSettings.valid, one of ONEIP_DEVICE_SETTINGS_BLOCK.

Intervals are base-2 logarithms of seconds, so -3 is 125 ms and 1 is 2 s.

log_announce_interval: int = 0

Between announce messages, behind PTP_ANNOUNCE.

log_sync_interval: int = 0

Between sync messages, behind PTP_SYNC.

log_delay_req_interval: int = 0

Between delay requests, behind PTP_DELAY_REQ.

announce_timeout: int = 0

The announce intervals before a silent master is dropped, behind PTP_ANNOUNCE_TIMEOUT.

dscp: int = 0

The DSCP of the messages, at most ONEIP_DSCP_MAX, behind PTP_DSCP.

sap_expire_min: int = 0

The minutes after which a SAP announcement the device heard is forgotten, behind SAP_EXPIRE.

sap_interval_s: int = 0

The seconds between the device’s SAP announcements, behind SAP_INTERVAL.

stream_ttl: int = 0

The TTL of the device’s streams, 1 to 255, behind STREAM_TTL. A device whose video processor cannot change it keeps the setting and sends ONEIP_STREAM_TTL_DEFAULT.

sink_rotation: int = 0

The degrees the device’s HDMI output is turned by, clockwise, at most ONEIP_SINK_ROTATION_MAX, behind SINK_ROTATION.

sink_rotation_step: int = 0

the device takes only an angle that is a multiple of it, and 0 alone when it is 0. Only the device reports it, behind the same bit.

Type:

The step the output turns by

takes_sink_rotation(degrees)

Whether a device reporting this step takes degrees as its output’s rotation.

Parameters:

degrees (int)

Return type:

bool

merge(other, which)

The values behind the bits of which copied from other, the rest kept.

Parameters:

• other (OneIPPtpMessages)

• which (OneIPDeviceSetting)

Return type:

OneIPPtpMessages

describe(valid)

The values behind the bits of valid, one “name=value” each.

Parameters:

valid (OneIPDeviceSetting)

Return type:

list[str]

__init__(log_announce_interval=0, log_sync_interval=0, log_delay_req_interval=0, announce_timeout=0, dscp=0, sap_expire_min=0, sap_interval_s=0, stream_ttl=0, sink_rotation=0, sink_rotation_step=0)

Parameters:

• log_announce_interval (int)

• log_sync_interval (int)

• log_delay_req_interval (int)

• announce_timeout (int)

• dscp (int)

• sap_expire_min (int)

• sap_interval_s (int)

• stream_ttl (int)

• sink_rotation (int)

• sink_rotation_step (int)

Return type:

None

mx_remote.proto.Constants.ONEIP_DEVICE_SETTINGS_PTP_MESSAGES = <OneIPDeviceSetting.PTP_ANNOUNCE|PTP_SYNC|PTP_DELAY_REQ|PTP_ANNOUNCE_TIMEOUT|PTP_DSCP: 16252928>

The PTP message settings.

mx_remote.proto.Constants.ONEIP_DEVICE_SETTINGS_BLOCK = <OneIPDeviceSetting.PTP_ANNOUNCE|PTP_SYNC|PTP_DELAY_REQ|PTP_ANNOUNCE_TIMEOUT|PTP_DSCP|SAP_EXPIRE|SAP_INTERVAL|STREAM_TTL|SINK_ROTATION: 2851602432>

The settings whose values a frame carries in a block of their own behind the rest, OneIPPtpMessages: the PTP message settings, the two SAP values, the stream TTL and the output’s rotation.

mx_remote.proto.Constants.ONEIP_STREAM_TTL_DEFAULT = 64

The TTL a OneIP device’s streams carry until it is set.

mx_remote.proto.Constants.ONEIP_SINK_ROTATION_MAX = 359

The largest angle a OneIP device’s HDMI output is turned by, in degrees.

mx_remote.proto.Constants.ONEIP_PTP_DOMAIN_MAX = 127

The highest PTP domain a OneIP device runs in.

Unit status and commands

A unit’s health and IP configuration, and the commands sent to one unit.

class mx_remote.UnitStatus

Bases: object

A unit’s health and IP configuration, as it last reported them.

A unit reports this about itself with its periodic broadcast, and within a few seconds of a change to its flags, its status or its addresses.

flags: UnitFlag = 0

The report’s flags.

uptime: int = 0

Seconds since the unit booted.

boot_count: int | None = None

How often the unit has booted, None while it does not report it.

reboot_count: int = 0

How often the unit has rebooted.

encoder_health: int = 0

The encoder’s health, a mask of the unit’s encoder status bits.

decoder_health: int = 0

The decoder’s health, a mask of the unit’s decoder status and state bits.

network: UnitNetConfig = UnitNetConfig(ip='0.0.0.0', netmask='0.0.0.0', gateway='0.0.0.0', dns1='0.0.0.0', dns2='0.0.0.0')

The IP configuration in use.

fan_rpm: int | None = None

The fan speed in RPM, None while the unit does not report it.

fan_duty: int = 0

The fan duty cycle, in percent.

status: int = 0

The unit’s system status.

net_revert_s: int = 0

Seconds before a pending IP configuration is reverted.

temperatures: tuple[int, ...] = ()

Temperatures in degrees Celsius, at most UNIT_MAX_TEMPERATURES of them.

status_message: str = ''

The message of the current system status.

power_save: tuple[UnitPowerSave, ...] = ()

What the unit offers at each power save level, from OneIPPowerSaveLevel.REDUCED up; empty for a unit that predates the field. A route change or a command wakes the unit at every level it supports.

power_save_level(level)

What the unit offers at a power save level, empty for OneIPPowerSaveLevel.NONE or a level it does not report.

Parameters:

level (OneIPPowerSaveLevel | int)

Return type:

UnitPowerSave

property network_pending: bool

Whether an IP configuration changed through the mesh waits for the mesh controller to confirm it.

__init__(flags=<UnitFlag: 0>, uptime=0, boot_count=None, reboot_count=0, encoder_health=0, decoder_health=0, network=UnitNetConfig(ip='0.0.0.0', netmask='0.0.0.0', gateway='0.0.0.0', dns1='0.0.0.0', dns2='0.0.0.0'), fan_rpm=None, fan_duty=0, status=0, net_revert_s=0, temperatures=(), status_message='', power_save=())

Parameters:

• flags (UnitFlag)

• uptime (int)

• boot_count (int | None)

• reboot_count (int)

• encoder_health (int)

• decoder_health (int)

• network (UnitNetConfig)

• fan_rpm (int | None)

• fan_duty (int)

• status (int)

• net_revert_s (int)

• temperatures (tuple[int, ...])

• status_message (str)

• power_save (tuple[UnitPowerSave, ...])

Return type:

None

class mx_remote.UnitNetConfig

Bases: object

An IP configuration: the addresses a unit uses, or is told to use.

ip: str = '0.0.0.0'

The address.

netmask: str = '0.0.0.0'

The netmask.

gateway: str = '0.0.0.0'

The gateway.

dns1: str = '0.0.0.0'

The primary DNS server.

dns2: str = '0.0.0.0'

The secondary DNS server.

property addresses: tuple[str, str, str, str, str]

The five addresses, in the order the wire carries them.

is_valid()

Whether every address parses, the address is one a unit can hold, and the netmask is a run of ones from the top.

Return type:

bool

__init__(ip='0.0.0.0', netmask='0.0.0.0', gateway='0.0.0.0', dns1='0.0.0.0', dns2='0.0.0.0')

Parameters:

• ip (str)

• netmask (str)

• gateway (str)

• dns1 (str)

• dns2 (str)

Return type:

None

class mx_remote.proto.Constants.UnitFlag

Bases: IntFlag

The flags of a unit’s status report.

REBOOT_REQUIRED = 1

A changed setting takes effect after a reboot.

VIDEO_PROCESSOR_UPGRADE = 2

A newer video processor image is available.

DHCP = 4

The IP configuration comes from DHCP.

NET_PENDING = 8

The IP configuration was changed through the mesh, and is reverted unless the mesh controller confirms it in time.

FAN_QUIET = 16

The fan runs in quiet mode.

EXTERNAL_PSU = 32

Powered by an external supply rather than PoE.

VIDEO_PROCESSOR_CONFIGURED = 64

The video processor runs with its IP configured. Without it the encoder and decoder health carry nothing.

ENCODER_ACTIVE = 128

The encoder is enabled.

DECODER_ACTIVE = 256

The decoder is enabled.

AUTO_DISABLE = 512

The decoder disables itself without a display.

AUTO_DISABLE_ACTIVE = 1024

The decoder disabled itself without a display.

OFF_NO_SIGNAL = 2048

The HDMI output switches off without a signal.

OFF_NO_SIGNAL_ACTIVE = 4096

The HDMI output switched off without a signal.

POWER_CHECK = 8192

Display power is checked before the decoder is enabled.

BOOT_COUNT = 16384

The boot count is reported.

FAN_SPEED = 32768

The fan speed is reported.

__new__(value)

class mx_remote.proto.Constants.UnitCommandKind

Bases: IntEnum

What a unit command asks of its unit.

CLEAR_STATUS = 0

Clear the current system status.

VIDEO_PROCESSOR_UPGRADE = 1

Upgrade the video processor to the latest image.

NET_CONFIG = 2

Change the IP configuration.

NET_CONFIRM = 3

Keep a pending IP configuration.

__new__(value)

class mx_remote.proto.Constants.UnitCommandFlag

Bases: IntFlag

The flags of a unit command.

FORCE = 1

flash the image even if it is running already.

Type:

With VIDEO_PROCESSOR_UPGRADE

DHCP = 2

use DHCP, ignoring the addresses.

Type:

With NET_CONFIG

__new__(value)

mx_remote.proto.Constants.UNIT_MAX_TEMPERATURES = 6

The most temperature sensors a unit reports.

class mx_remote.proto.Constants.UnitPowerSave

Bases: IntFlag

What a unit offers at one power save level.

SUPPORTED = 1

The unit can power down to this level.

INPUT_WAKE = 2

A signal on the HDMI input wakes the unit.

OUTPUT_WAKE = 4

The display powering on wakes the unit, and the unit can power it on.

__new__(value)

mx_remote.proto.Constants.UNIT_POWER_SAVE_LEVELS = 4

The power save levels a unit reports what it offers at, from OneIPPowerSaveLevel.REDUCED up.

OneIP session descriptions

What an output plays from a session description, and how it is timed.

class mx_remote.OneIPSinkSdp

Bases: object

What a OneIP output plays from a session description, as it last reported it. The stream’s fields are zero while it plays none.

flags: OneIPSdpFlag = 0

The report’s flags.

screen: int = 0

What the output shows while it plays audio alone, as the wire value.

encoding: OneIPSdpEncoding | int = 0

The sample encoding; a raw int for one this library does not name.

payload_type: int = 0

The RTP payload type.

clock_mode: OneIPSdpClockMode | int = 0

What the video processor times the stream by, behind OneIPSdpFlag.CLOCK.

clock_state: OneIPSdpClockState | int = 0

How far the video processor has got with its timing, behind OneIPSdpFlag.CLOCK.

rate_hz: int = 0

The sample rate in Hz.

group: str = '0.0.0.0'

The multicast group.

name: str = ''

The session name.

layout: str = ''

The channel layout.

property active: bool

Whether the output plays a stream from a description.

__init__(flags=<OneIPSdpFlag: 0>, screen=0, encoding=OneIPSdpEncoding.NONE, channels=0, payload_type=0, media_clock=OneIPSdpMediaClock.NONE, ref_clock=OneIPSdpRefClock.NONE, clock_mode=OneIPSdpClockMode.ARRIVAL, clock_state=OneIPSdpClockState.IDLE, port=0, rate_hz=0, media_clock_offset=0, group='0.0.0.0', name='', layout='')

Parameters:

• flags (OneIPSdpFlag)

• screen (int)

• encoding (OneIPSdpEncoding | int)

• channels (int)

• payload_type (int)

• media_clock (OneIPSdpMediaClock | int)

• ref_clock (OneIPSdpRefClock | int)

• clock_mode (OneIPSdpClockMode | int)

• clock_state (OneIPSdpClockState | int)

• port (int)

• rate_hz (int)

• media_clock_offset (int)

• group (str)

• name (str)

• layout (str)

Return type:

None

class mx_remote.proto.Constants.OneIPSdpFlag

Bases: IntFlag

The flags of a OneIP output’s session description report.

ACTIVE = 1

The output plays a stream from a description.

AUDIO_ONLY = 2

And nothing else, as no video is routed to it.

CLOCK = 4

The clock mode and state hold the video processor’s answer.

__new__(value)

class mx_remote.proto.Constants.OneIPSdpEncoding

Bases: IntEnum

The sample encoding of a stream a OneIP output plays from a description.

L16 = 1

16-bit linear PCM.

L24 = 2

24-bit linear PCM.

__new__(value)

class mx_remote.proto.Constants.OneIPSdpMediaClock

Bases: IntEnum

Where a described stream’s media clock comes from.

DIRECT = 1

Direct, at an offset from the reference clock.

SENDER = 2

The sender’s.

__new__(value)

class mx_remote.proto.Constants.OneIPSdpRefClock

Bases: IntEnum

The reference clock a described stream names.

LOCAL_MAC = 3

The sender’s local MAC.

__new__(value)

class mx_remote.proto.Constants.OneIPSdpClockMode

Bases: IntEnum

What a OneIP output’s video processor times a described stream by.

__new__(value)

class mx_remote.proto.Constants.OneIPSdpClockState

Bases: IntEnum

How far a OneIP output’s video processor has got with a described stream’s timing.

SERVO = 1

Running its servo.

UNTIMED = 5

Playing untimed.

UNSUPPORTED = 6

The timing is not supported.

__new__(value)

mx_remote.proto.Constants.ONEIP_SDP_MAX = 2048

The longest session description a OneIP output takes, in bytes.

OneIP stream encryption

How a source unit encrypts its streams, as it reports it.

class mx_remote.OneIPPrivacy

Bases: object

How a OneIP source unit’s streams are encrypted, as it last reported it. A unit reports this whenever it changes, at least once a minute, and when asked. A unit that is in no mesh sends in the clear.

anc: OneIPPrivacyStream

The ancillary data stream.

__init__(video, audio, anc)

Parameters:

• video (OneIPPrivacyStream)

• audio (OneIPPrivacyStream)

• anc (OneIPPrivacyStream)

Return type:

None

class mx_remote.OneIPPrivacyStream

Bases: object

How one of a OneIP source unit’s streams is encrypted, as the unit reports it: the values of the stream’s a=privacy and a=extmap session description attributes.

A receiver needs these to decrypt the stream. The key itself never travels: every unit of a mesh holds the same one. This library holds no key and decrypts nothing.

group: str = '0.0.0.0'

The stream’s destination address.

port: int = 0

The stream’s UDP port.

version: int = 0

Steps whenever the parameters change.

on: bool = False

Whether the stream is encrypted. Without it the stream goes out in the clear, and the fields below mean nothing.

full_id: int = 0

The RTP header extension id of the full IV counter.

short_id: int = 0

The RTP header extension id of the short IV counter.

iv: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00'

The initialisation vector, 8 bytes.

key_generator: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'

The key generator, 16 bytes.

key_id: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00'

Names the mesh’s key, 8 bytes. A receiver holding another drops the stream.

key_version: int = 0

The key version.

__init__(group='0.0.0.0', port=0, version=0, on=False, full_id=0, short_id=0, iv=b'\x00\x00\x00\x00\x00\x00\x00\x00', key_generator=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00', key_id=b'\x00\x00\x00\x00\x00\x00\x00\x00', key_version=0)

Parameters:

• group (str)

• port (int)

• version (int)

• on (bool)

• full_id (int)

• short_id (int)

• iv (bytes)

• key_generator (bytes)

• key_id (bytes)

• key_version (int)

Return type:

None

OneIP test card

A sink’s test pattern, tone and lip-sync flash, and the ranges it accepts.

class mx_remote.OneIPTestcard

Bases: object

The test card a OneIP sink draws on its output, as it last reported it.

A sink reports it only when asked, with request_oneip_testcard() or in answer to a change. The counters run free and wrap.

flags: OneIPTestcardFlag = 0

What the sink reports about its test card.

pattern: OneIPTestPattern | int = 0

The pattern; a raw int for a pattern this library does not name.

colour: int = 0

The colour of a FLAT pattern, 0xRRGGBB.

tone: OneIPTestTone = OneIPTestTone(mode=<OneIPToneMode.OFF: 0>, freq=0, level=0, channels=0, rate=0)

The tone.

sync: OneIPTestSync = OneIPTestSync(period=0, lead=0, offset=0, beep_ms=0)

The lip-sync flash.

frames: int = 0

Pattern frames sent.

periods: int = 0

Sample periods since the tone started.

marks: int = 0

Lip-sync marks the tone has seen.

property supported: bool

Whether the sink can draw the test card.

__init__(flags=<OneIPTestcardFlag: 0>, pattern=OneIPTestPattern.OFF, colour=0, tone=OneIPTestTone(mode=<OneIPToneMode.OFF: 0>, freq=0, level=0, channels=0, rate=0), sync=OneIPTestSync(period=0, lead=0, offset=0, beep_ms=0), frames=0, periods=0, marks=0)

Parameters:

• flags (OneIPTestcardFlag)

• pattern (OneIPTestPattern | int)

• colour (int)

• tone (OneIPTestTone)

• sync (OneIPTestSync)

• frames (int)

• periods (int)

• marks (int)

Return type:

None

class mx_remote.OneIPTestTone

Bases: object

A OneIP sink’s test tone.

mode: OneIPToneMode | int = 0

What plays; a raw int for a mode this library does not name.

freq: int = 0

The frequency, in Hz.

level: int = 0

The level, in dBFS.

channels: int = 0

The channels it plays on.

rate: int = 0

The sample rate, in Hz.

is_valid()

Whether a sink plays this tone: a mode it names, and every value in range. A line-up tone needs two channels or more.

Return type:

bool

__init__(mode=OneIPToneMode.OFF, freq=0, level=0, channels=0, rate=0)

Parameters:

• mode (OneIPToneMode | int)

• freq (int)

• level (int)

• channels (int)

• rate (int)

Return type:

None

class mx_remote.OneIPTestSync

Bases: object

A OneIP sink’s lip-sync flash: a pattern frame is marked every period, the frame lead after a mark flashes white, and a BEEP tone starts offset sample periods after it.

The offset is a calibration: nothing measures the sink’s own delay between a picture and a sample reaching the HDMI link, and a display adds its own.

period: int = 0

Every this many pattern frames is marked, 0 for none.

lead: int = 0

The frame this many after a mark flashes.

offset: int = 0

The sample periods between a mark and the beep.

beep_ms: int = 0

How long the beep lasts, in milliseconds.

is_valid()

Whether a sink takes these settings: the lead is below the period, or 0 without one, and the period, offset and beep are in range.

Return type:

bool

__init__(period=0, lead=0, offset=0, beep_ms=0)

Parameters:

• period (int)

• lead (int)

• offset (int)

• beep_ms (int)

Return type:

None

class mx_remote.proto.Constants.OneIPTestPattern

Bases: IntEnum

The test pattern a OneIP sink draws on its output.

OFF = 0

No pattern.

BARS = 1

Colour bars.

FLAT = 2

One flat colour, the one the test card carries.

RAMP = 3

A ramp.

GRID = 4

A grid.

STRIP = 5

A strip.

CARD = 6

A test card.

__new__(value)

class mx_remote.proto.Constants.OneIPToneMode

Bases: IntEnum

The test tone a OneIP sink plays on its output.

OFF = 0

No tone.

CONTINUOUS = 1

A continuous tone.

IDENT = 2

A channel ident.

LINEUP = 3

A line-up tone, which needs two channels or more.

BEEP = 4

A beep on each lip-sync mark.

__new__(value)

class mx_remote.proto.Constants.OneIPTestcardFlag

Bases: IntFlag

What a OneIP sink reports about its test card.

SUPPORTED = 1

The sink can draw the test card.

SHOWING = 2

The output shows the pattern.

PLAYING = 4

The tone plays on the output.

PATTERN_PENDING = 8

A pattern change has yet to reach the video processor.

TONE_PENDING = 16

A tone change has yet to reach the video processor.

SYNC_PENDING = 32

A lip-sync change has yet to reach the video processor.

__new__(value)

mx_remote.proto.Constants.ONEIP_TONE_FREQ_MIN = 20

The lowest test tone frequency, in Hz.

mx_remote.proto.Constants.ONEIP_TONE_FREQ_MAX = 20000

The highest test tone frequency, in Hz.

mx_remote.proto.Constants.ONEIP_TONE_LEVEL_MIN = -60

The quietest test tone level, in dBFS; the loudest is 0.

mx_remote.proto.Constants.ONEIP_TONE_CHANNELS_MAX = 8

The most channels a test tone plays on.

mx_remote.proto.Constants.ONEIP_TONE_RATES = (44100, 48000, 96000)

The sample rates a test tone plays at, in Hz.

mx_remote.proto.Constants.ONEIP_SYNC_OFFSET_MAX = 16777215

The largest lip-sync beep offset, in sample periods.

mx_remote.proto.Constants.ONEIP_SYNC_BEEP_MS_MIN = 1

The shortest lip-sync beep, in milliseconds.

mx_remote.proto.Constants.ONEIP_SYNC_BEEP_MS_MAX = 10000

The longest lip-sync beep, in milliseconds.

Mesh time

The time zone and clock a mesh controller announces.

class mx_remote.TimeZone

Bases: object

The time zone a device announces for its mesh.

The mesh controller announces it with every periodic broadcast, and each device of the mesh keeps its clock and its power save windows by it. An empty zone and rule mean the controller has none, and the devices keep UTC.

zone: str

The IANA name, such as Europe/Amsterdam.

rule: str

The POSIX TZ rule the devices keep time by, such as CET-1CEST,M3.5.0,M10.5.0/3.

__init__(zone, rule)

Parameters:

• zone (str)

• rule (str)

Return type:

None

class mx_remote.DeviceClock

Bases: object

The time a device last announced, and when that arrived here.

utc: int

Seconds since 1970 UTC, as the device announced them.

received: float

When the announcement arrived, as time.time() read it.

now()

The device’s clock as of now: the announced time, advanced by how long ago it arrived.

Return type:

datetime

__init__(utc, received)

Parameters:

• utc (int)

• received (float)

Return type:

None

Names from before OneIP

Releases up to 5.11 used the firmware’s internal names in the public API: V2IP for OneIP and FPGA for the video processor. Each old name maps to the new one by spelling alone - V2IP becomes OneIP (ONEIP in a constant, oneip in a member), and Fpga or FPGA becomes VideoProcessor or VIDEO_PROCESSOR: device.v2ip_settings is device.oneip_settings, V2IPFpgaFeature is OneIPVideoProcessorFeature, FirmwareType.FPGA is FirmwareType.VIDEO_PROCESSOR.

The old names still resolve. A module-level name or a class member raises a DeprecationWarning naming its replacement; an enum member and an AudioFeatures bit constant are plain aliases, since those cannot warn. The old names are left out of from mx_remote import * and out of the type stubs, so a type checker reports them, and they will be removed in a future major release.

One rename has no alias: a OneIP device’s temperatures dict reports the video processor’s sensor under 'Video Processor', where it used 'FPGA'.