add more enums so we can remove some of the constants

rename some of the packet classes

patch bump

README.md

@@ -41,14 +41,14 @@ Load VBAN connection info from toml config. A valid `vban.toml` might look like
 
 ```toml
 [connection]
-ip = "gamepc.local"
+host = "localhost"
 port = 6980
 streamname = "Command1"
 ```
 
 It should be placed in \<user home directory\> / "Documents" / "Voicemeeter" / "configs"
 
-Alternatively you may pass `ip`, `port`, `streamname` as keyword arguments.
+Alternatively you may pass `host`, `port`, `streamname` as keyword arguments.
 
 #### `__main__.py`
 
@@ -85,7 +85,7 @@ def main():
     KIND_ID = 'banana'
 
     with vban_cmd.api(
-        KIND_ID, ip='gamepc.local', port=6980, streamname='Command1'
+        KIND_ID, host='localhost', port=6980, streamname='Command1'
     ) as vban:
         do = ManyThings(vban)
         do.things()
@@ -474,7 +474,7 @@ example:
 import vban_cmd
 
 opts = {
-    'ip': '<ip address>',
+    'host': '<ip address>',
     'streamname': 'Command1',
     'port': 6980,
 }
@@ -541,14 +541,15 @@ print(vban.event.get())
 
 You may pass the following optional keyword arguments:
 
--   `ip`: str='localhost', ip or hostname of remote machine
+-   `host`: str='localhost', ip or hostname of remote machine
 -   `port`: int=6980, vban udp port of remote machine.
 -   `streamname`: str='Command1', name of the stream to connect to.
 -   `bps`: int=256000, bps rate of the stream.
 -   `channel`: int=0, channel on which to send the UDP requests.
 -   `pdirty`: boolean=False, parameter updates
 -   `ldirty`: boolean=False, level updates
--   `timeout`: int=5, amount of time (seconds) to wait for an incoming RT data packet (parameter states).
+-   `script_ratelimit`: float=0.05, default to 20 script requests per second. This affects vban.sendtext() specifically.
+-   `timeout`: int=5, timeout for socket operations.
 -   `disable_rt_listeners`: boolean=False, set `True` if you don't wish to receive RT packets.
     -   You can still send Matrix string requests ending with `?` and receive a response.
 
@@ -591,7 +592,7 @@ import vban_cmd
 
 logging.basicConfig(level=logging.DEBUG)
 
-opts = {'ip': 'ip.local', 'port': 6980, 'streamname': 'Command1'}
+opts = {'host': 'localhost', 'port': 6980, 'streamname': 'Command1'}
 with vban_cmd.api('banana', **opts) as vban:
     ...
 ```

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vban-cmd"
-version = "2.9.0"
+version = "2.9.7"
 description = "Python interface for the VBAN RT Packet Service (Sendtext)"
 authors = [{ name = "Onyx and Iris", email = "code@onyxandiris.online" }]
 license = { text = "MIT" }

tests/__init__.py

@@ -11,7 +11,7 @@ from vban_cmd.kinds import request_kind_map as kindmap
 KIND_ID = os.environ.get('KIND', 'potato')
 
 opts = {
-    'ip': os.getenv('VBANCMD_IP', 'localhost'),
+    'host': os.getenv('VBANCMD_HOST', 'localhost'),
     'streamname': os.getenv('VBANCMD_STREAMNAME', 'Command1'),
     'port': int(os.getenv('VBANCMD_PORT', 6980)),
 }

vban_cmd/factory.py

@@ -84,18 +84,20 @@ class FactoryBase(VbanCmd):
 
     def __init__(self, kind_id: str, **kwargs):
         defaultkwargs = {
-            'ip': 'localhost',
+            'host': 'localhost',
             'port': 6980,
             'streamname': 'Command1',
             'bps': 256000,
             'channel': 0,
-            'ratelimit': 0.01,
-            'timeout': 5,
+            'script_ratelimit': 0.05,  # 20 commands per second, to avoid overloading Voicemeeter
+            'timeout': 5,  # timeout on socket operations, in seconds
             'disable_rt_listeners': False,
             'sync': False,
             'pdirty': False,
             'ldirty': False,
         }
+        if 'ip' in kwargs:
+            defaultkwargs['host'] = kwargs.pop('ip')  # for backwards compatibility
         if 'subs' in kwargs:
             defaultkwargs |= kwargs.pop('subs')  # for backwards compatibility
         kwargs = defaultkwargs | kwargs

vban_cmd/iremote.py

@@ -1,83 +1,9 @@
 import abc
 import logging
-import time
-from dataclasses import dataclass
 
 logger = logging.getLogger(__name__)
 
 
-@dataclass
-class Modes:
-    """Channel Modes"""
-
-    _mute: hex = 0x00000001
-    _solo: hex = 0x00000002
-    _mono: hex = 0x00000004
-    _mc: hex = 0x00000008
-
-    _amix: hex = 0x00000010
-    _repeat: hex = 0x00000020
-    _bmix: hex = 0x00000030
-    _composite: hex = 0x00000040
-    _tvmix: hex = 0x00000050
-    _upmix21: hex = 0x00000060
-    _upmix41: hex = 0x00000070
-    _upmix61: hex = 0x00000080
-    _centeronly: hex = 0x00000090
-    _lfeonly: hex = 0x000000A0
-    _rearonly: hex = 0x000000B0
-
-    _mask: hex = 0x000000F0
-
-    _on: hex = 0x00000100  # eq.on
-    _cross: hex = 0x00000200
-    _ab: hex = 0x00000800  # eq.ab
-
-    _busa: hex = 0x00001000
-    _busa1: hex = 0x00001000
-    _busa2: hex = 0x00002000
-    _busa3: hex = 0x00004000
-    _busa4: hex = 0x00008000
-    _busa5: hex = 0x00080000
-
-    _busb: hex = 0x00010000
-    _busb1: hex = 0x00010000
-    _busb2: hex = 0x00020000
-    _busb3: hex = 0x00040000
-
-    _pan0: hex = 0x00000000
-    _pancolor: hex = 0x00100000
-    _panmod: hex = 0x00200000
-    _panmask: hex = 0x00F00000
-
-    _postfx_r: hex = 0x01000000
-    _postfx_d: hex = 0x02000000
-    _postfx1: hex = 0x04000000
-    _postfx2: hex = 0x08000000
-
-    _sel: hex = 0x10000000
-    _monitor: hex = 0x20000000
-
-    @property
-    def modevals(self):
-        return (
-            val
-            for val in [
-                self._amix,
-                self._repeat,
-                self._bmix,
-                self._composite,
-                self._tvmix,
-                self._upmix21,
-                self._upmix41,
-                self._upmix61,
-                self._centeronly,
-                self._lfeonly,
-                self._rearonly,
-            ]
-        )
-
-
 class IRemote(abc.ABC):
     """
     Common interface between base class and extended (higher) classes
@@ -89,7 +15,6 @@ class IRemote(abc.ABC):
         self._remote = remote
         self.index = index
         self.logger = logger.getChild(self.__class__.__name__)
-        self._modes = Modes()
 
     def getter(self, param):
         cmd = self._cmd(param)
@@ -123,6 +48,8 @@ class IRemote(abc.ABC):
     def apply(self, data):
         """Sets all parameters of a dict for the channel."""
 
+        script = ''
+
         def fget(attr, val):
             if attr == 'mode':
                 return (f'mode.{val}', 1)
@@ -138,14 +65,9 @@ class IRemote(abc.ABC):
                         val = 1 if val else 0
 
                     self._remote.cache[self._cmd(attr)] = val
-                    self._remote._script += f'{self._cmd(attr)}={val};'
+                    script += f'{self._cmd(attr)}={val};'
             else:
                 target = getattr(self, attr)
                 target.apply(val)
 
-        self._remote.sendtext(self._remote._script)
-        return self
-
-    def then_wait(self):
-        self._remote._script = str()
-        time.sleep(self._remote.DELAY)
+        self._remote.sendtext(script)

vban_cmd/meta.py

@@ -1,6 +1,7 @@
 from functools import partial
 
 from .enums import NBS, BusModes
+from .packet.enums import ChannelModes
 from .util import cache_bool, cache_float, cache_int, cache_string
 
 
@@ -27,7 +28,7 @@ def channel_bool_prop(param):
         elif param.lower() == 'mc':
             return channel_state.mc
         else:
-            return channel_state.get_mode(getattr(self._modes, f'_{param.lower()}'))
+            return channel_state.get_mode(getattr(ChannelModes, param.upper()).value)
 
     def fset(self, val):
         self.setter(param, 1 if val else 0)
@@ -55,7 +56,9 @@ def channel_int_prop(param):
             bit_9 = (channel_state._state >> 9) & 1
             return (bit_9 << 1) | bit_2
         else:
-            return channel_state.get_mode_int(getattr(self._modes, f'_{param.lower()}'))
+            return channel_state.get_mode_int(
+                getattr(ChannelModes, param.upper()).value
+            )
 
     def fset(self, val):
         self.setter(param, val)
@@ -89,7 +92,7 @@ def strip_output_prop(param):
 
         strip_state = self.public_packets[NBS.zero].states.strip[self.index]
 
-        return strip_state.get_mode(getattr(self._modes, f'_bus{param.lower()}'))
+        return strip_state.get_mode(getattr(ChannelModes, f'BUS{param.upper()}').value)
 
     def fset(self, val):
         self.setter(param, 1 if val else 0)

vban_cmd/packet/enums.py

@@ -0,0 +1,83 @@
+from enum import Flag
+
+
+class SubProtocols(Flag):
+    """Sub Protocols - Bit flags that can be combined"""
+
+    AUDIO = 0x00
+    SERIAL = 0x20
+    TEXT = 0x40
+    SERVICE = 0x60
+    MASK = 0xE0
+
+
+class ServiceTypes(Flag):
+    """Service Types - Bit flags that can be combined"""
+
+    PING = 0
+    PONG = 0
+    CHATUTF8 = 1
+    RTPACKETREGISTER = 32
+    RTPACKET = 33
+    REQUESTREPLY = 0x02  # A Matrix reply
+    FNCT_REPLY = 0x80  # An RTPacket reply
+
+
+class StreamTypes(Flag):
+    """Stream Types - Bit flags that can be combined"""
+
+    ASCII = 0x00
+    UTF8 = 0x10
+    WCHAR = 0x20
+
+
+class ChannelModes(Flag):
+    """Channel Modes - Bit flags that can be combined"""
+
+    MUTE = 0x00000001
+    SOLO = 0x00000002
+    MONO = 0x00000004
+    MC = 0x00000008
+
+    AMIX = 0x00000010
+    REPEAT = 0x00000020
+    BMIX = 0x00000030
+    COMPOSITE = 0x00000040
+    TVMIX = 0x00000050
+    UPMIX21 = 0x00000060
+    UPMIX41 = 0x00000070
+    UPMIX61 = 0x00000080
+    CENTERONLY = 0x00000090
+    LFEONLY = 0x000000A0
+    REARONLY = 0x000000B0
+
+    MASK = 0x000000F0
+
+    ON = 0x00000100  # eq.on
+    CROSS = 0x00000200
+    AB = 0x00000800  # eq.ab
+
+    BUSA = 0x00001000
+    BUSA1 = 0x00001000
+    BUSA2 = 0x00002000
+    BUSA3 = 0x00004000
+    BUSA4 = 0x00008000
+    BUSA5 = 0x00080000
+
+    BUSB = 0x00010000
+    BUSB1 = 0x00010000
+    BUSB2 = 0x00020000
+    BUSB3 = 0x00040000
+
+    PAN0 = 0x00000000
+    PANCOLOR = 0x00100000
+    PANMOD = 0x00200000
+    PANMASK = 0x00F00000
+
+    POSTFX_R = 0x01000000
+    POSTFX_D = 0x02000000
+    POSTFX1 = 0x04000000
+    POSTFX2 = 0x08000000
+
+    SEL = 0x10000000
+    MONITOR = 0x20000000

vban_cmd/packet/headers.py

@@ -3,222 +3,21 @@ from dataclasses import dataclass
 from vban_cmd.enums import NBS
 from vban_cmd.kinds import KindMapClass
 
-VBAN_PROTOCOL_TXT = 0x40
-VBAN_PROTOCOL_SERVICE = 0x60
-
-VBAN_SERVICE_RTPACKETREGISTER = 32
-VBAN_SERVICE_RTPACKET = 33
-VBAN_SERVICE_PING = 0
-VBAN_SERVICE_PONG = 0  # PONG uses same service type as PING
-VBAN_SERVICE_MASK = 0xE0
-VBAN_PROTOCOL_MASK = 0xE0
-VBAN_SERVICE_REQUESTREPLY = 0x02
-VBAN_SERVICE_FNCT_REPLY = 0x02
+from .enums import ServiceTypes, StreamTypes, SubProtocols
 
 PINGPONG_PACKET_SIZE = 704  # Size of the PING/PONG header + payload in bytes
-
 MAX_PACKET_SIZE = 1436
 HEADER_SIZE = 4 + 1 + 1 + 1 + 1 + 16
 
 
-@dataclass
-class VbanPacket:
-    """Represents the header of an incoming VBAN data packet"""
-
-    nbs: NBS
-    _kind: KindMapClass
-    _voicemeeterType: bytes
-    _reserved: bytes
-    _buffersize: bytes
-    _voicemeeterVersion: bytes
-    _optionBits: bytes
-    _samplerate: bytes
-
-    @property
-    def voicemeetertype(self) -> str:
-        """returns voicemeeter type as a string"""
-        return ['', 'basic', 'banana', 'potato'][
-            int.from_bytes(self._voicemeeterType, 'little')
-        ]
-
-    @property
-    def voicemeeterversion(self) -> tuple:
-        """returns voicemeeter version as a tuple"""
-        return tuple(self._voicemeeterVersion[i] for i in range(3, -1, -1))
-
-    @property
-    def samplerate(self) -> int:
-        """returns samplerate as an int"""
-        return int.from_bytes(self._samplerate, 'little')
-
-
-@dataclass
-class VbanSubscribeHeader:
-    """Represents the header of a subscription packet"""
-
-    nbs: NBS = NBS.zero
-    name: str = 'Register-RTP'
-    timeout: int = 15
-
-    @property
-    def vban(self) -> bytes:
-        return b'VBAN'
-
-    @property
-    def format_sr(self) -> bytes:
-        return VBAN_PROTOCOL_SERVICE.to_bytes(1, 'little')
-
-    @property
-    def format_nbs(self) -> bytes:
-        return (self.nbs.value & 0xFF).to_bytes(1, 'little')
-
-    @property
-    def format_nbc(self) -> bytes:
-        return VBAN_SERVICE_RTPACKETREGISTER.to_bytes(1, 'little')
-
-    @property
-    def format_bit(self) -> bytes:
-        return (self.timeout & 0xFF).to_bytes(1, 'little')
-
-    @property
-    def streamname(self) -> bytes:
-        return self.name.encode('ascii') + bytes(16 - len(self.name))
-
-    @classmethod
-    def to_bytes(cls, nbs: NBS, framecounter: int) -> bytes:
-        header = cls(nbs=nbs)
-
-        data = bytearray()
-        data.extend(header.vban)
-        data.extend(header.format_sr)
-        data.extend(header.format_nbs)
-        data.extend(header.format_nbc)
-        data.extend(header.format_bit)
-        data.extend(header.streamname)
-        data.extend(framecounter.to_bytes(4, 'little'))
-        return bytes(data)
-
-
-def _parse_vban_service_header(data: bytes) -> dict:
-    """Common parsing and validation for VBAN service protocol headers."""
-    if len(data) < HEADER_SIZE:
-        raise ValueError('Data is too short to be a valid VBAN header')
-
-    if data[:4] != b'VBAN':
-        raise ValueError('Invalid VBAN magic bytes')
-
-    format_sr = data[4]
-    format_nbs = data[5]
-    format_nbc = data[6]
-    format_bit = data[7]
-
-    # Verify this is a service protocol packet
-    protocol = format_sr & VBAN_PROTOCOL_MASK
-    if protocol != VBAN_PROTOCOL_SERVICE:
-        raise ValueError(f'Not a service protocol packet: {protocol:02x}')
-
-    # Extract stream name and frame counter
-    name = data[8:24].rstrip(b'\x00').decode('utf-8', errors='ignore')
-    framecounter = int.from_bytes(data[24:28], 'little')
-
-    return {
-        'format_sr': format_sr,
-        'format_nbs': format_nbs,
-        'format_nbc': format_nbc,
-        'format_bit': format_bit,
-        'name': name,
-        'framecounter': framecounter,
-    }
-
-
-@dataclass
-class VbanResponseHeader:
-    """Represents the header of a response packet"""
-
-    name: str = 'Voicemeeter-RTP'
-    format_sr: int = VBAN_PROTOCOL_SERVICE
-    format_nbs: int = 0
-    format_nbc: int = VBAN_SERVICE_RTPACKET
-    format_bit: int = 0
-    framecounter: int = 0
-
-    @property
-    def vban(self) -> bytes:
-        return b'VBAN'
-
-    @property
-    def streamname(self) -> bytes:
-        return self.name.encode('ascii') + bytes(16 - len(self.name))
-
-    @classmethod
-    def from_bytes(cls, data: bytes):
-        """Parse a VbanResponseHeader from bytes."""
-        parsed = _parse_vban_service_header(data)
-
-        # Validate this is an RTPacket response
-        if parsed['format_nbc'] != VBAN_SERVICE_RTPACKET:
-            raise ValueError(
-                f'Not an RTPacket response packet: {parsed["format_nbc"]:02x}'
-            )
-
-        return cls(**parsed)
-
-
-@dataclass
-class VbanMatrixResponseHeader:
-    """Represents the header of a matrix response packet"""
-
-    name: str = 'Request Reply'
-    format_sr: int = VBAN_PROTOCOL_SERVICE
-    format_nbs: int = VBAN_SERVICE_FNCT_REPLY
-    format_nbc: int = VBAN_SERVICE_REQUESTREPLY
-    format_bit: int = 0
-    framecounter: int = 0
-
-    @property
-    def vban(self) -> bytes:
-        return b'VBAN'
-
-    @property
-    def streamname(self) -> bytes:
-        return self.name.encode('ascii')[:16].ljust(16, b'\x00')
-
-    @classmethod
-    def from_bytes(cls, data: bytes):
-        """Parse a matrix response packet from bytes."""
-        parsed = _parse_vban_service_header(data)
-
-        # Validate this is a service reply packet
-        if parsed['format_nbs'] != VBAN_SERVICE_FNCT_REPLY:
-            raise ValueError(f'Not a service reply packet: {parsed["format_nbs"]:02x}')
-
-        return cls(**parsed)
-
-    @classmethod
-    def extract_payload(cls, data: bytes) -> str:
-        """Extract the text payload from a matrix response packet."""
-        if len(data) <= HEADER_SIZE:
-            return ''
-
-        payload_bytes = data[HEADER_SIZE:]
-        return payload_bytes.rstrip(b'\x00').decode('utf-8', errors='ignore')
-
-    @classmethod
-    def parse_response(cls, data: bytes) -> tuple['VbanMatrixResponseHeader', str]:
-        """Parse a complete matrix response packet returning header and payload."""
-        header = cls.from_bytes(data)
-        payload = cls.extract_payload(data)
-        return header, payload
-
-
 @dataclass
 class VbanPingHeader:
     """Represents the header of a PING packet"""
 
     name: str = 'PING0'
-    format_sr: int = VBAN_PROTOCOL_SERVICE
+    format_sr: int = SubProtocols.SERVICE.value
     format_nbs: int = 0
-    format_nbc: int = VBAN_SERVICE_PING
+    format_nbc: int = ServiceTypes.PING.value
     format_bit: int = 0
     framecounter: int = 0
 
@@ -251,9 +50,9 @@ class VbanPongHeader:
     """Represents the header of a PONG response packet"""
 
     name: str = 'PING0'
-    format_sr: int = VBAN_PROTOCOL_SERVICE
+    format_sr: int = SubProtocols.SERVICE.value
     format_nbs: int = 0
-    format_nbc: int = VBAN_SERVICE_PONG
+    format_nbc: int = ServiceTypes.PONG.value
     format_bit: int = 0
     framecounter: int = 0
 
@@ -272,7 +71,7 @@ class VbanPongHeader:
 
         # PONG responses use the same service type as PING (0x00)
         # and are identified by having payload data
-        if parsed['format_nbc'] != VBAN_SERVICE_PONG:
+        if parsed['format_nbc'] != ServiceTypes.PONG.value:
             raise ValueError(f'Not a PONG response packet: {parsed["format_nbc"]:02x}')
 
         return cls(**parsed)
@@ -284,7 +83,7 @@ class VbanPongHeader:
             parsed = _parse_vban_service_header(data)
 
             # Validate this is a service protocol packet with PING/PONG service type
-            if parsed['format_nbc'] != VBAN_SERVICE_PONG:
+            if parsed['format_nbc'] != ServiceTypes.PONG.value:
                 return False
 
             if parsed['name'] not in ['PING0', 'VBAN Service']:
@@ -298,8 +97,86 @@ class VbanPongHeader:
 
 
 @dataclass
-class VbanRequestHeader:
-    """Represents the header of a request packet"""
+class VbanRTPacket:
+    """Represents the header of an incoming RTPacket"""
+
+    nbs: NBS
+    _kind: KindMapClass
+    _voicemeeterType: bytes
+    _reserved: bytes
+    _buffersize: bytes
+    _voicemeeterVersion: bytes
+    _optionBits: bytes
+    _samplerate: bytes
+
+    @property
+    def voicemeetertype(self) -> str:
+        """returns voicemeeter type as a string"""
+        return ['', 'basic', 'banana', 'potato'][
+            int.from_bytes(self._voicemeeterType, 'little')
+        ]
+
+    @property
+    def voicemeeterversion(self) -> tuple:
+        """returns voicemeeter version as a tuple"""
+        return tuple(self._voicemeeterVersion[i] for i in range(3, -1, -1))
+
+    @property
+    def samplerate(self) -> int:
+        """returns samplerate as an int"""
+        return int.from_bytes(self._samplerate, 'little')
+
+
+@dataclass
+class VbanRTSubscribeHeader:
+    """Represents the header of an RT subscription packet"""
+
+    nbs: NBS = NBS.zero
+    name: str = 'Register-RTP'
+    timeout: int = 15
+
+    @property
+    def vban(self) -> bytes:
+        return b'VBAN'
+
+    @property
+    def format_sr(self) -> bytes:
+        return SubProtocols.SERVICE.value.to_bytes(1, 'little')
+
+    @property
+    def format_nbs(self) -> bytes:
+        return (self.nbs.value & 0xFF).to_bytes(1, 'little')
+
+    @property
+    def format_nbc(self) -> bytes:
+        return ServiceTypes.RTPACKETREGISTER.value.to_bytes(1, 'little')
+
+    @property
+    def format_bit(self) -> bytes:
+        return (self.timeout & 0xFF).to_bytes(1, 'little')
+
+    @property
+    def streamname(self) -> bytes:
+        return self.name.encode('ascii') + bytes(16 - len(self.name))
+
+    @classmethod
+    def to_bytes(cls, nbs: NBS, framecounter: int) -> bytes:
+        header = cls(nbs=nbs)
+
+        data = bytearray()
+        data.extend(header.vban)
+        data.extend(header.format_sr)
+        data.extend(header.format_nbs)
+        data.extend(header.format_nbc)
+        data.extend(header.format_bit)
+        data.extend(header.streamname)
+        data.extend(framecounter.to_bytes(4, 'little'))
+        return bytes(data)
+
+
+@dataclass
+class VbanRTRequestHeader:
+    """Represents the header of an RT request packet"""
 
     name: str
     bps_index: int
@@ -312,7 +189,7 @@ class VbanRequestHeader:
 
     @property
     def sr(self) -> bytes:
-        return (VBAN_PROTOCOL_TXT + self.bps_index).to_bytes(1, 'little')
+        return (self.bps_index | SubProtocols.TEXT.value).to_bytes(1, 'little')
 
     @property
     def nbs(self) -> bytes:
@@ -324,7 +201,7 @@ class VbanRequestHeader:
 
     @property
     def bit(self) -> bytes:
-        return (0x10).to_bytes(1, 'little')
+        return (StreamTypes.UTF8.value).to_bytes(1, 'little')
 
     @property
     def streamname(self) -> bytes:
@@ -354,3 +231,115 @@ class VbanRequestHeader:
     ) -> bytes:
         """Creates the complete packet with header and payload."""
         return cls.to_bytes(name, bps_index, channel, framecounter) + payload.encode()
+
+
+def _parse_vban_service_header(data: bytes) -> dict:
+    """Common parsing and validation for VBAN service protocol headers."""
+    if len(data) < HEADER_SIZE:
+        raise ValueError('Data is too short to be a valid VBAN header')
+
+    if data[:4] != b'VBAN':
+        raise ValueError('Invalid VBAN magic bytes')
+
+    format_sr = data[4]
+    format_nbs = data[5]
+    format_nbc = data[6]
+    format_bit = data[7]
+
+    # Verify this is a service protocol packet
+    protocol = format_sr & SubProtocols.MASK.value
+    if protocol != SubProtocols.SERVICE.value:
+        raise ValueError(f'Not a service protocol packet: {protocol:02x}')
+
+    # Extract stream name and frame counter
+    name = data[8:24].rstrip(b'\x00').decode('utf-8', errors='ignore')
+    framecounter = int.from_bytes(data[24:28], 'little')
+
+    return {
+        'format_sr': format_sr,
+        'format_nbs': format_nbs,
+        'format_nbc': format_nbc,
+        'format_bit': format_bit,
+        'name': name,
+        'framecounter': framecounter,
+    }
+
+
+@dataclass
+class VbanRTResponseHeader:
+    """Represents the header of an RT response packet"""
+
+    name: str = 'Voicemeeter-RTP'
+    format_sr: int = SubProtocols.SERVICE.value
+    format_nbs: int = 0
+    format_nbc: int = ServiceTypes.RTPACKET.value
+    format_bit: int = 0
+    framecounter: int = 0
+
+    @property
+    def vban(self) -> bytes:
+        return b'VBAN'
+
+    @property
+    def streamname(self) -> bytes:
+        return self.name.encode('ascii') + bytes(16 - len(self.name))
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        """Parse a VbanResponseHeader from bytes."""
+        parsed = _parse_vban_service_header(data)
+
+        # Validate this is an RTPacket response
+        if parsed['format_nbc'] != ServiceTypes.RTPACKET.value:
+            raise ValueError(
+                f'Not an RTPacket response packet: {parsed["format_nbc"]:02x}'
+            )
+
+        return cls(**parsed)
+
+
+@dataclass
+class VbanMatrixResponseHeader:
+    """Represents the header of a matrix response packet"""
+
+    name: str = 'Request Reply'
+    format_sr: int = SubProtocols.SERVICE.value
+    format_nbs: int = ServiceTypes.FNCT_REPLY.value
+    format_nbc: int = ServiceTypes.REQUESTREPLY.value
+    format_bit: int = 0
+    framecounter: int = 0
+
+    @property
+    def vban(self) -> bytes:
+        return b'VBAN'
+
+    @property
+    def streamname(self) -> bytes:
+        return self.name.encode('ascii')[:16].ljust(16, b'\x00')
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        """Parse a matrix response packet from bytes."""
+        parsed = _parse_vban_service_header(data)
+
+        # Validate this is a service reply packet
+        if parsed['format_nbs'] != ServiceTypes.FNCT_REPLY.value:
+            raise ValueError(f'Not a service reply packet: {parsed["format_nbs"]:02x}')
+
+        return cls(**parsed)
+
+    @classmethod
+    def extract_payload(cls, data: bytes) -> str:
+        """Extract the text payload from a matrix response packet."""
+        if len(data) <= HEADER_SIZE:
+            return ''
+
+        payload_bytes = data[HEADER_SIZE:]
+        return payload_bytes.rstrip(b'\x00').decode('utf-8', errors='ignore')
+
+    @classmethod
+    def parse_response(cls, data: bytes) -> tuple['VbanMatrixResponseHeader', str]:
+        """Parse a complete matrix response packet returning header and payload."""
+        header = cls.from_bytes(data)
+        payload = cls.extract_payload(data)
+        return header, payload

vban_cmd/packet/nbs0.py

@@ -5,7 +5,8 @@ from vban_cmd.enums import NBS
 from vban_cmd.kinds import KindMapClass
 from vban_cmd.util import comp
 
-from .headers import VbanPacket
+from .enums import ChannelModes
+from .headers import VbanRTPacket
 
 
 class Levels(NamedTuple):
@@ -31,57 +32,57 @@ class ChannelState:
     # Common boolean modes
     @property
     def mute(self) -> bool:
-        return (self._state & 0x00000001) != 0
+        return (self._state & ChannelModes.MUTE.value) != 0
 
     @property
     def solo(self) -> bool:
-        return (self._state & 0x00000002) != 0
+        return (self._state & ChannelModes.SOLO.value) != 0
 
     @property
     def mono(self) -> bool:
-        return (self._state & 0x00000004) != 0
+        return (self._state & ChannelModes.MONO.value) != 0
 
     @property
     def mc(self) -> bool:
-        return (self._state & 0x00000008) != 0
+        return (self._state & ChannelModes.MC.value) != 0
 
     # EQ modes
     @property
     def eq_on(self) -> bool:
-        return (self._state & 0x00000100) != 0
+        return (self._state & ChannelModes.ON.value) != 0
 
     @property
     def eq_ab(self) -> bool:
-        return (self._state & 0x00000800) != 0
+        return (self._state & ChannelModes.AB.value) != 0
 
     # Bus assignments (strip to bus routing)
     @property
     def busa1(self) -> bool:
-        return (self._state & 0x00001000) != 0
+        return (self._state & ChannelModes.BUSA1.value) != 0
 
     @property
     def busa2(self) -> bool:
-        return (self._state & 0x00002000) != 0
+        return (self._state & ChannelModes.BUSA2.value) != 0
 
     @property
     def busa3(self) -> bool:
-        return (self._state & 0x00004000) != 0
+        return (self._state & ChannelModes.BUSA3.value) != 0
 
     @property
     def busa4(self) -> bool:
-        return (self._state & 0x00008000) != 0
+        return (self._state & ChannelModes.BUSA4.value) != 0
 
     @property
     def busb1(self) -> bool:
-        return (self._state & 0x00010000) != 0
+        return (self._state & ChannelModes.BUSB1.value) != 0
 
     @property
     def busb2(self) -> bool:
-        return (self._state & 0x00020000) != 0
+        return (self._state & ChannelModes.BUSB2.value) != 0
 
     @property
     def busb3(self) -> bool:
-        return (self._state & 0x00040000) != 0
+        return (self._state & ChannelModes.BUSB3.value) != 0
 
 
 class States(NamedTuple):
@@ -95,8 +96,8 @@ class Labels(NamedTuple):
 
 
 @dataclass
-class VbanPacketNBS0(VbanPacket):
-    """Represents the body of a VBAN data packet with ident:0"""
+class VbanRTPacketNBS0(VbanRTPacket):
+    """Represents the body of a VBAN RTPacket with ident:0"""
 
     _inputLeveldB100: bytes
     _outputLeveldB100: bytes

vban_cmd/packet/nbs1.py

@@ -5,7 +5,7 @@ from typing import NamedTuple
 from vban_cmd.enums import NBS
 from vban_cmd.kinds import KindMapClass
 
-from .headers import VbanPacket
+from .headers import VbanRTPacket
 
 VMPARAMSTRIP_SIZE = 174
 
@@ -327,8 +327,8 @@ class VbanVMParamStrip:
 
 
 @dataclass
-class VbanPacketNBS1(VbanPacket):
-    """Represents the body of a VBAN data packet with ident:1"""
+class VbanRTPacketNBS1(VbanRTPacket):
+    """Represents the body of a VBAN RTPacket with ident:1"""
 
     strips: tuple[VbanVMParamStrip, ...]
 

vban_cmd/util.py

@@ -1,5 +1,62 @@
+import socket
+import time
 from typing import Iterator
 
+from .error import VBANCMDConnectionError
+
+
+def ratelimit(func):
+    """ratelimit decorator for {VbanCmd}.sendtext, to prevent flooding the network with script requests."""
+
+    def wrapper(*args, **kwargs):
+        self, *rem = args
+        if self.script_ratelimit > 0:
+            now = time.time()
+            elapsed = now - self._last_script_request_time
+            if elapsed < self.script_ratelimit:
+                time.sleep(self.script_ratelimit - elapsed)
+            self._last_script_request_time = time.time()
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def pong_timeout(func):
+    """pong_timeout decorator for {VbanCmd}._handle_pong, to handle timeout logic and socket management."""
+
+    def wrapper(self, timeout: float = None):
+        if timeout is None:
+            timeout = min(self.timeout, 3.0)
+
+        original_timeout = self.sock.gettimeout()
+        self.sock.settimeout(0.5)
+
+        try:
+            start_time = time.time()
+            response_count = 0
+
+            while time.time() - start_time < timeout:
+                try:
+                    response_count += 1
+
+                    if func(self):
+                        return
+
+                except socket.timeout:
+                    continue
+
+            self.logger.debug(
+                f'PING timeout after {timeout}s, received {response_count} non-PONG packets'
+            )
+            raise VBANCMDConnectionError(
+                f'PING timeout: No response from {self.host}:{self.port} after {timeout}s'
+            )
+
+        finally:
+            self.sock.settimeout(original_timeout)
+
+    return wrapper
+
 
 def cache_bool(func, param):
     """Check cache for a bool prop"""

vban_cmd/vbancmd.py

@@ -5,7 +5,7 @@ import threading
 import time
 from pathlib import Path
 from queue import Queue
-from typing import Union
+from typing import Mapping, Union
 
 from .enums import NBS
 from .error import VBANCMDConnectionError, VBANCMDError
@@ -13,11 +13,11 @@ from .event import Event
 from .packet.headers import (
     VbanMatrixResponseHeader,
     VbanPongHeader,
-    VbanRequestHeader,
+    VbanRTRequestHeader,
 )
 from .packet.ping0 import VbanPing0Payload, VbanServerType
 from .subject import Subject
-from .util import bump_framecounter, deep_merge
+from .util import bump_framecounter, deep_merge, pong_timeout, ratelimit
 from .worker import Producer, Subscriber, Updater
 
 logger = logging.getLogger(__name__)
@@ -38,7 +38,7 @@ class VbanCmd(abc.ABC):
     def __init__(self, **kwargs):
         self.logger = logger.getChild(self.__class__.__name__)
         self.event = Event({k: kwargs.pop(k) for k in ('pdirty', 'ldirty')})
-        if not kwargs['ip']:
+        if not kwargs['host']:
             kwargs |= self._conn_from_toml()
         for attr, val in kwargs.items():
             setattr(self, attr, val)
@@ -52,14 +52,13 @@ class VbanCmd(abc.ABC):
         self.cache = {}
         self._pdirty = False
         self._ldirty = False
-        self._script = str()
         self.stop_event = None
         self.producer = None
+        self._last_script_request_time = 0
 
     @abc.abstractmethod
     def __str__(self):
         """Ensure subclasses override str magic method"""
-        pass
 
     def _conn_from_toml(self) -> dict:
         try:
@@ -97,6 +96,7 @@ class VbanCmd(abc.ABC):
         If the server is detected as Matrix, RT listeners will be disabled for compatibility.
         """
         self._ping()
+        self._handle_pong()
 
         if not self.disable_rt_listeners:
             self.event.info()
@@ -113,7 +113,7 @@ class VbanCmd(abc.ABC):
             self.producer.start()
 
         self.logger.info(
-            "Successfully logged into VBANCMD {kind} with ip='{ip}', port={port}, streamname='{streamname}'".format(
+            "Successfully logged into VBANCMD {kind} with host='{host}', port={port}, streamname='{streamname}'".format(
                 **self.__dict__
             )
         )
@@ -138,43 +138,36 @@ class VbanCmd(abc.ABC):
             self._framecounter = bump_framecounter(self._framecounter)
             return current
 
-    def _ping(self, timeout: float = None) -> None:
-        """Send a PING packet and wait for PONG response to verify connectivity."""
-        if timeout is None:
-            timeout = min(self.timeout, 3.0)
-
-        ping_packet = VbanPing0Payload.create_packet(self._get_next_framecounter())
-
-        original_timeout = self.sock.gettimeout()
-        self.sock.settimeout(0.5)
-
+    def _ping(self):
+        """Initiates the PING/PONG handshake with the VBAN server."""
         try:
-            self.sock.sendto(ping_packet, (socket.gethostbyname(self.ip), self.port))
-            self.logger.debug(f'PING sent to {self.ip}:{self.port}')
+            self.sock.sendto(
+                VbanPing0Payload.create_packet(self._get_next_framecounter()),
+                (socket.gethostbyname(self.host), self.port),
+            )
+            self.logger.debug(f'PING sent to {self.host}:{self.port}')
 
-            start_time = time.time()
-            response_count = 0
-            while time.time() - start_time < timeout:
-                try:
+        except socket.gaierror as e:
+            raise VBANCMDConnectionError(
+                f'Unable to resolve hostname {self.host}'
+            ) from e
+        except Exception as e:
+            raise VBANCMDConnectionError(f'PING failed: {e}') from e
+
+    @pong_timeout
+    def _handle_pong(self) -> bool:
+        """Handles incoming packets during the PING/PONG handshake, looking for a valid PONG response to confirm connectivity and detect server type.
+
+        Returns True if a valid PONG is received, False otherwise."""
         data, addr = self.sock.recvfrom(2048)
-                    response_count += 1
-
-                    self.logger.debug(
-                        f'Received packet #{response_count} from {addr}: {len(data)} bytes'
-                    )
-                    self.logger.debug(
-                        f'Response header: {data[: min(32, len(data))].hex()}'
-                    )
 
         if VbanPongHeader.is_pong_response(data):
-                        self.logger.debug(
-                            f'PONG received from {addr}, connectivity confirmed'
-                        )
+            self.logger.debug(f'PONG received from {addr}, connectivity confirmed')
 
             server_type = VbanPing0Payload.detect_server_type(data)
             self._handle_server_type(server_type)
 
-                        return  # Exit after successful PONG response
+            return True
         else:
             if len(data) >= 8:
                 if data[:4] == b'VBAN':
@@ -186,22 +179,7 @@ class VbanCmd(abc.ABC):
                 else:
                     self.logger.debug('Non-VBAN packet received')
 
-                except socket.timeout:
-                    continue
-
-            self.logger.debug(
-                f'PING timeout after {timeout}s, received {response_count} non-PONG packets'
-            )
-            raise VBANCMDConnectionError(
-                f'PING timeout: No response from {self.ip}:{self.port} after {timeout}s'
-            )
-
-        except socket.gaierror as e:
-            raise VBANCMDConnectionError(f'Unable to resolve hostname {self.ip}') from e
-        except Exception as e:
-            raise VBANCMDConnectionError(f'PING failed: {e}') from e
-        finally:
-            self.sock.settimeout(original_timeout)
+            return False
 
     def _handle_server_type(self, server_type: VbanServerType) -> None:
         """Handle the detected server type by adjusting settings accordingly."""
@@ -223,14 +201,14 @@ class VbanCmd(abc.ABC):
     def _send_request(self, payload: str) -> None:
         """Sends a request packet over the network and bumps the framecounter."""
         self.sock.sendto(
-            VbanRequestHeader.encode_with_payload(
+            VbanRTRequestHeader.encode_with_payload(
                 name=self.streamname,
                 bps_index=self.BPS_OPTS.index(self.bps),
                 channel=self.channel,
                 framecounter=self._get_next_framecounter(),
                 payload=payload,
             ),
-            (socket.gethostbyname(self.ip), self.port),
+            (socket.gethostbyname(self.host), self.port),
         )
 
     def _set_rt(self, cmd: str, val: Union[str, float]):
@@ -238,6 +216,7 @@ class VbanCmd(abc.ABC):
         self._send_request(f'{cmd}={val};')
         self.cache[cmd] = val
 
+    @ratelimit
     def sendtext(self, script) -> str | None:
         """Sends a multiple parameter string over a network."""
         self._send_request(script)
@@ -246,17 +225,14 @@ class VbanCmd(abc.ABC):
         if self.disable_rt_listeners and script.endswith(('?', '?;')):
             try:
                 data, _ = self.sock.recvfrom(2048)
-                payload = VbanMatrixResponseHeader.extract_payload(data)
+                return VbanMatrixResponseHeader.extract_payload(data)
             except ValueError as e:
                 self.logger.warning(f'Error extracting matrix response: {e}')
             except TimeoutError as e:
                 self.logger.exception(f'Timeout waiting for matrix response: {e}')
                 raise VBANCMDConnectionError(
-                    f'Timeout waiting for response from {self.ip}:{self.port}'
+                    f'Timeout waiting for response from {self.host}:{self.port}'
                 ) from e
-            return payload
-
-        time.sleep(self.DELAY)
 
     @property
     def type(self) -> str:
@@ -288,12 +264,8 @@ class VbanCmd(abc.ABC):
         while self.pdirty:
             time.sleep(self.DELAY)
 
-    def apply(self, data: dict):
-        """
-        Sets all parameters of a dict
-
-        minor delay between each recursion
-        """
+    def apply(self, data: Mapping):
+        """Set all parameters of a dict"""
 
         def target(key):
             match key.split('-'):
@@ -313,7 +285,8 @@ class VbanCmd(abc.ABC):
                     raise ValueError(ERR_MSG)
             return target[int(index)]
 
-        [target(key).apply(di).then_wait() for key, di in data.items()]
+        for key, di in data.items():
+            target(key).apply(di)
 
     def apply_config(self, name):
         """applies a config from memory"""

vban_cmd/worker.py

@@ -6,12 +6,12 @@ from .enums import NBS
 from .error import VBANCMDConnectionError
 from .packet.headers import (
     HEADER_SIZE,
-    VbanPacket,
-    VbanResponseHeader,
-    VbanSubscribeHeader,
+    VbanRTPacket,
+    VbanRTResponseHeader,
+    VbanRTSubscribeHeader,
 )
-from .packet.nbs0 import VbanPacketNBS0
-from .packet.nbs1 import VbanPacketNBS1
+from .packet.nbs0 import VbanRTPacketNBS0
+from .packet.nbs1 import VbanRTPacketNBS1
 
 logger = logging.getLogger(__name__)
 
@@ -27,19 +27,13 @@ class Subscriber(threading.Thread):
 
     def run(self):
         while not self.stopped():
-            try:
             for nbs in NBS:
-                    sub_packet = VbanSubscribeHeader().to_bytes(
+                sub_packet = VbanRTSubscribeHeader().to_bytes(
                     nbs, self._remote._get_next_framecounter()
                 )
                 self._remote.sock.sendto(
-                        sub_packet, (self._remote.ip, self._remote.port)
+                    sub_packet, (self._remote.host, self._remote.port)
                 )
-            except TimeoutError as e:
-                self.logger.exception(f'{type(e).__name__}: {e}')
-                raise VBANCMDConnectionError(
-                    f'timeout sending subscription to {self._remote.ip}:{self._remote.port}'
-                ) from e
 
             self.wait_until_stopped(10)
         self.logger.debug(f'terminating {self.name} thread')
@@ -72,7 +66,7 @@ class Producer(threading.Thread):
             self._remote.cache['bus_level'],
         ) = self._remote.public_packets[NBS.zero].levels
 
-    def _get_rt(self) -> VbanPacket:
+    def _get_rt(self) -> VbanRTPacket:
         """Attempt to fetch data packet until a valid one found"""
         while True:
             try:
@@ -82,23 +76,23 @@ class Producer(threading.Thread):
             except TimeoutError as e:
                 self.logger.exception(f'{type(e).__name__}: {e}')
                 raise VBANCMDConnectionError(
-                    f'timeout waiting for response from {self._remote.ip}:{self._remote.port}'
+                    f'timeout waiting for response from {self._remote.host}:{self._remote.port}'
                 ) from e
 
             try:
-                header = VbanResponseHeader.from_bytes(data[:HEADER_SIZE])
+                header = VbanRTResponseHeader.from_bytes(data[:HEADER_SIZE])
             except ValueError as e:
                 self.logger.debug(f'Error parsing response packet: {e}')
                 continue
 
             match header.format_nbs:
                 case NBS.zero:
-                    return VbanPacketNBS0.from_bytes(
+                    return VbanRTPacketNBS0.from_bytes(
                         nbs=NBS.zero, kind=self._remote.kind, data=data
                     )
 
                 case NBS.one:
-                    return VbanPacketNBS1.from_bytes(
+                    return VbanRTPacketNBS1.from_bytes(
                         nbs=NBS.one, kind=self._remote.kind, data=data
                     )
 
@@ -128,7 +122,6 @@ class Producer(threading.Thread):
                 self.queue.put('pdirty')
             if self._remote.event.ldirty:
                 self.queue.put('ldirty')
-            # time.sleep(self._remote.ratelimit)
         self.logger.debug(f'terminating {self.name} thread')
         self.queue.put(None)