md fix

patch bump

CHANGELOG.md

@@ -11,6 +11,36 @@ Before any major/minor/patch bump all unit tests will be run to verify they pass
 
 -   [x]
 
+## [2.3.2] - 2023-07-12
+
+### Added
+
+-   vban.{instream,outstream} tuples now contain classes that represent MIDI and TEXT streams.
+
+### Fixed
+
+-   apply_config() now performs a deep merge when extending a config with another.
+
+## [2.3.0] - 2023-07-11
+
+### Added
+
+-   user configs may now extend other user configs. check `config extends` section in README.
+
+## [2.2.0] - 2023-07-10
+
+### Added
+
+-   CAPIError class now stores fn_name, error code and message as class attributes.
+
+### Changed
+
+-   macrobutton capi calls now use error code -9 on AttributeError (using an old version of the API).
+
+### Fixed
+
+-   call to `self.vm_get_midi_message` now wrapped by {CBindings}.call.
+
 ## [2.1.1] - 2023-07-01
 
 ### Added

README.md

@@ -405,7 +405,7 @@ The following methods are available
 The following properties are available
 
 -   `A1 - A5`: boolean
--   `B1 - A3`: boolean
+-   `B1 - B3`: boolean
 -   `samplerate`: int, (22050, 24000, 32000, 44100, 48000, 88200, 96000, 176400, 192000)
 -   `bitresolution`: int, (8, 16, 24, 32)
 -   `channel`: int, from 1 to 8
@@ -691,8 +691,8 @@ vm.apply(
 Or for each class you may do:
 
 ```python
-vm.strip[0].apply(mute: True, gain: 3.2, A1: True)
+vm.strip[0].apply({"mute": True, "gain": 3.2, "A1": True})
-vm.vban.outstream[0].apply(on: True, name: 'streamname', bit: 24)
+vm.vban.outstream[0].apply({"on": True, "name": "streamname", "bit": 24})
 ```
 
 ## Config Files
@@ -701,7 +701,7 @@ vm.vban.outstream[0].apply(on: True, name: 'streamname', bit: 24)
 
 You may load config files in TOML format.
 Three example configs have been included with the package. Remember to save
-current settings before loading a user config. To set one you may do:
+current settings before loading a user config. To load one you may do:
 
 ```python
 import voicemeeterlib
@@ -709,7 +709,26 @@ with voicemeeterlib.api('banana') as vm:
     vm.apply_config('example')
 ```
 
-will load a user config file at configs/banana/example.toml for Voicemeeter Banana.
+Your configs may be located in one of the following paths:
+-   \<current working directory\> / "configs" / kind_id
+-   \<user home directory\> / ".config" / "voicemeeter" / kind_id
+-   \<user home directory\> / "Documents" / "Voicemeeter" / "configs" / kind_id
+
+If a config with the same name is located in multiple locations, only the first one found is loaded into memory, in the above order.
+
+#### `config extends`
+
+You may also load a config that extends another config with overrides or additional parameters.
+
+You just need to define a key `extends` in the config TOML, that names the config to be extended.
+
+Three example 'extender' configs are included with the repo. You may load them with:
+
+```python
+import voicemeeterlib
+with voicemeeterlib.api('banana') as vm:
+    vm.apply_config('extender')
+```
 
 ## Events
 
@@ -721,7 +740,7 @@ example:
 import voicemeeterlib
 # Set event updates to occur every 50ms
 # Listen for level updates only
-with voicemeeterlib.api('banana', ratelimit=0.05, ldirty=True}) as vm:
+with voicemeeterlib.api('banana', ratelimit=0.05, ldirty=True) as vm:
     ...
 ```
 
@@ -808,19 +827,42 @@ vm.set('Strip[0].Gain', -3.6)
 
 Access to lower level polling functions are provided with the following property objects:
 
-#### `vm.pdirty`
+##### `vm.pdirty`
 
 True iff a parameter has been updated.
 
-#### `vm.mdirty`
+##### `vm.mdirty`
 
 True iff a macrobutton has been updated.
 
-#### `vm.ldirty`
+##### `vm.ldirty`
 
 True iff a level has been updated.
 
 
+### Errors
+
+-   `errors.VMError`: Exception raised when general errors occur.
+-   `errors.InstallError`: Exception raised when installation errors occur.
+-   `errors.CAPIError`: Exception raised when the C-API returns error values.
+    -   Error codes are stored in {Exception Class}.code. For a full list of error codes [check the VoicemeeterRemote header file][Voicemeeter Remote Header].
+
+
+### Logging
+
+It's possible to see the messages sent by the interface's setters and getters, may be useful for debugging.
+
+example:
+```python
+import voicemeeterlib
+
+logging.basicConfig(level=logging.DEBUG)
+
+with voicemeeterlib.api("banana") as vm:
+        ...
+```
+
+
 ### Run tests
 
 To run all tests:
@@ -832,3 +874,6 @@ pytest -v
 ### Official Documentation
 
 -   [Voicemeeter Remote C API](https://github.com/onyx-and-iris/Voicemeeter-SDK/blob/update-docs/VoicemeeterRemoteAPI.pdf)
+
+
+[Voicemeeter Remote Header]: https://github.com/onyx-and-iris/Voicemeeter-SDK/blob/update-docs/VoicemeeterRemote.h

configs/banana/extender.toml

@@ -0,0 +1,12 @@
+extends = "example"
+[strip-0]
+label = "strip0_extended"
+A1 = false
+gain = 0.0
+
+[bus-0]
+label = "bus0_extended"
+mute = false
+
+[vban-in-3]
+name = "vban_extended"

configs/basic/extender.toml

@@ -0,0 +1,12 @@
+extends = "example"
+[strip-0]
+label = "strip0_extended"
+A1 = false
+gain = 0.0
+
+[bus-0]
+label = "bus0_extended"
+mute = false
+
+[vban-in-3]
+name = "vban_extended"

configs/potato/extender.toml

@@ -0,0 +1,12 @@
+extends = "example"
+[strip-0]
+label = "strip0_extended"
+A1 = false
+gain = 0.0
+
+[bus-0]
+label = "bus0_extended"
+mute = false
+
+[vban-in-3]
+name = "vban_extended"

examples/dsl/__main__.py

@@ -63,8 +63,6 @@ class Parser:
 
 def interactive_mode(parser):
     while cmd := input("Please enter command (Press <Enter> to exit)\n"):
-        if not cmd:
-            break
         if res := parser.parse((cmd,)):
             print(res)
 

examples/events/__main__.py

@@ -18,6 +18,7 @@ class App:
 
     def __enter__(self):
         self.vm.init_thread()
+        return self
 
     def __exit__(self, exc_type, exc_value, traceback):
         self.vm.end_thread()

pyproject.toml

@@ -1,15 +1,13 @@
 [tool.poetry]
 name = "voicemeeter-api"
-version = "2.1.1"
+version = "2.3.3"
 description = "A Python wrapper for the Voiceemeter API"
 authors = ["onyx-and-iris <code@onyxandiris.online>"]
 license = "MIT"
 readme = "README.md"
 repository = "https://github.com/onyx-and-iris/voicemeeter-api-python"
 
-packages = [
+packages = [{ include = "voicemeeterlib" }]
-    { include = "voicemeeterlib" },
-]
 
 [tool.poetry.dependencies]
 python = "^3.10"

scripts.py

@@ -1,40 +1,41 @@
 import subprocess
+import sys
 from pathlib import Path
 
 
 def ex_dsl():
-    path = Path.cwd() / "examples" / "dsl" / "."
+    scriptpath = Path.cwd() / "examples" / "dsl" / "."
-    subprocess.run(["py", str(path)])
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_events():
-    path = Path.cwd() / "examples" / "events" / "."
+    scriptpath = Path.cwd() / "examples" / "events" / "."
-    subprocess.run(["py", str(path)])
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_gui():
-    path = Path.cwd() / "examples" / "gui" / "."
+    scriptpath = Path.cwd() / "examples" / "gui" / "."
-    subprocess.run(["py", str(path)])
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_levels():
-    path = Path.cwd() / "examples" / "levels" / "."
+    scriptpath = Path.cwd() / "examples" / "levels" / "."
-    subprocess.run(["py", str(path)])
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_midi():
-    path = Path.cwd() / "examples" / "midi" / "."
+    scriptpath = Path.cwd() / "examples" / "midi" / "."
-    subprocess.run(["py", str(path)])
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_obs():
-    path = Path.cwd() / "examples" / "obs" / "."
+    scriptpath = Path.cwd() / "examples" / "obs" / "."
-    subprocess.run(["py", str(path)])
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_observer():
-    path = Path.cwd() / "examples" / "observer" / "."
+    scriptpath = Path.cwd() / "examples" / "observer" / "."
-    subprocess.run(["py", str(path)])
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def test():

tests/test_factory.py

@@ -22,7 +22,7 @@ class TestRemoteFactories:
         assert len(vm.strip) == 3
         assert len(vm.bus) == 2
         assert len(vm.button) == 80
-        assert len(vm.vban.instream) == 4 and len(vm.vban.outstream) == 4
+        assert len(vm.vban.instream) == 6 and len(vm.vban.outstream) == 5
 
     @pytest.mark.skipif(
         data.name != "banana",
@@ -42,7 +42,7 @@ class TestRemoteFactories:
         assert len(vm.strip) == 5
         assert len(vm.bus) == 5
         assert len(vm.button) == 80
-        assert len(vm.vban.instream) == 8 and len(vm.vban.outstream) == 8
+        assert len(vm.vban.instream) == 10 and len(vm.vban.outstream) == 9
 
     @pytest.mark.skipif(
         data.name != "potato",
@@ -63,4 +63,4 @@ class TestRemoteFactories:
         assert len(vm.strip) == 8
         assert len(vm.bus) == 8
         assert len(vm.button) == 80
-        assert len(vm.vban.instream) == 8 and len(vm.vban.outstream) == 8
+        assert len(vm.vban.instream) == 10 and len(vm.vban.outstream) == 9

voicemeeterlib/cbindings.py

@@ -16,7 +16,7 @@ class CBindings(metaclass=ABCMeta):
     Maps expected ctype argument and res types for each binding.
     """
 
-    logger_cbindings = logger.getChild("Cbindings")
+    logger_cbindings = logger.getChild("CBindings")
 
     vm_login = libc.VBVMR_Login
     vm_login.restype = LONG
@@ -116,10 +116,10 @@ class CBindings(metaclass=ABCMeta):
             res = func(*args)
             if ok_exp is None:
                 if res not in ok:
-                    raise CAPIError(f"{func.__name__} returned {res}")
+                    raise CAPIError(func.__name__, res)
-            elif not ok_exp(res):
+            elif not ok_exp(res) and res not in ok:
-                raise CAPIError(f"{func.__name__} returned {res}")
+                raise CAPIError(func.__name__, res)
             return res
         except CAPIError as e:
-            self.logger_cbindings.exception(f"{type(e).__name__}: {e}")
+            self.logger_cbindings.exception(str(e))
             raise

voicemeeterlib/error.py

@@ -5,6 +5,15 @@ class InstallError(Exception):
 class CAPIError(Exception):
     """Exception raised when the C-API returns error values"""
 
+    def __init__(self, fn_name, code, msg=None):
+        self.fn_name = fn_name
+        self.code = code
+        self.message = msg if msg else f"{fn_name} returned {code}"
+        super().__init__(self.message)
+
+    def __str__(self):
+        return f"{type(self).__name__}: {self.message}"
+
 
 class VMError(Exception):
     """Exception raised when general errors occur"""

voicemeeterlib/kinds.py

@@ -64,7 +64,7 @@ class BasicMap(KindMapClass):
     name: str
     ins: tuple = (2, 1)
     outs: tuple = (1, 1)
-    vban: tuple = (4, 4)
+    vban: tuple = (4, 4, 1, 1)
     asio: tuple = (0, 0)
     insert: int = 0
 
@@ -74,7 +74,7 @@ class BananaMap(KindMapClass):
     name: str
     ins: tuple = (3, 2)
     outs: tuple = (3, 2)
-    vban: tuple = (8, 8)
+    vban: tuple = (8, 8, 1, 1)
     asio: tuple = (6, 8)
     insert: int = 22
 
@@ -84,7 +84,7 @@ class PotatoMap(KindMapClass):
     name: str
     ins: tuple = (5, 3)
     outs: tuple = (5, 3)
-    vban: tuple = (8, 8)
+    vban: tuple = (8, 8, 1, 1)
     asio: tuple = (10, 8)
     insert: int = 34
 

voicemeeterlib/remote.py

@@ -1,3 +1,4 @@
+import copy
 import ctypes as ct
 import logging
 import time
@@ -13,7 +14,7 @@ from .kinds import KindId
 from .misc import Midi, VmGui
 from .subject import Subject
 from .updater import Producer, Updater
-from .util import grouper, polling, script
+from .util import deep_merge, grouper, polling, script
 
 logger = logging.getLogger(__name__)
 
@@ -70,7 +71,9 @@ class Remote(CBindings):
                 "Voicemeeter engine running but GUI not launched. Launching the GUI now."
             )
             self.run_voicemeeter(self.kind.name)
-        self.logger.info(f"{type(self).__name__}: Successfully logged into {self}")
+        self.logger.info(
+            f"{type(self).__name__}: Successfully logged into {self} version {self.version}"
+        )
         self.clear_dirty()
 
     def run_voicemeeter(self, kind_id: str) -> NoReturn:
@@ -114,8 +117,12 @@ class Remote(CBindings):
             return self.call(self.vm_mdirty, ok=(0, 1)) == 1
         except AttributeError as e:
             self.logger.exception(f"{type(e).__name__}: {e}")
+            ERR_MSG = (
+                "no bind for VBVMR_MacroButton_IsDirty.",
+                "are you using an old version of the API?",
+            )
             raise CAPIError(
-                "no bind for VBVMR_MacroButton_IsDirty. are you using an old version of the API?"
+                "VBVMR_MacroButton_IsDirty", -9, msg=" ".join(ERR_MSG)
             ) from e
 
     @property
@@ -131,8 +138,10 @@ class Remote(CBindings):
         try:
             while self.pdirty or self.mdirty:
                 pass
-        except CAPIError:
+        except CAPIError as e:
-            self.logger.error("no bind for mdirty, clearing pdirty only")
+            if not (e.fn_name == "VBVMR_MacroButton_IsDirty" and e.code == -9):
+                raise
+            self.logger.error(f"{e} clearing pdirty only.")
             while self.pdirty:
                 pass
 
@@ -172,8 +181,12 @@ class Remote(CBindings):
             )
         except AttributeError as e:
             self.logger.exception(f"{type(e).__name__}: {e}")
+            ERR_MSG = (
+                "no bind for VBVMR_MacroButton_GetStatus.",
+                "are you using an old version of the API?",
+            )
             raise CAPIError(
-                "no bind for VBVMR_MacroButton_GetStatus. are you using an old version of the API?"
+                "VBVMR_MacroButton_GetStatus", -9, msg=" ".join(ERR_MSG)
             ) from e
         return int(state.value)
 
@@ -184,8 +197,12 @@ class Remote(CBindings):
             self.call(self.vm_set_buttonstatus, ct.c_long(id), c_state, ct.c_long(mode))
         except AttributeError as e:
             self.logger.exception(f"{type(e).__name__}: {e}")
+            ERR_MSG = (
+                "no bind for VBVMR_MacroButton_SetStatus.",
+                "are you using an old version of the API?",
+            )
             raise CAPIError(
-                "no bind for VBVMR_MacroButton_SetStatus. are you using an old version of the API?"
+                "VBVMR_MacroButton_SetStatus", -9, msg=" ".join(ERR_MSG)
             ) from e
         self.cache[f"mb_{id}_{mode}"] = int(c_state.value)
 
@@ -238,7 +255,13 @@ class Remote(CBindings):
     def get_midi_message(self):
         n = ct.c_long(1024)
         buf = ct.create_string_buffer(1024)
-        res = self.vm_get_midi_message(ct.byref(buf), n, ok_exp=lambda r: r >= 0)
+        res = self.call(
+            self.vm_get_midi_message,
+            ct.byref(buf),
+            n,
+            ok=(-5, -6),  # no data received from midi device
+            ok_exp=lambda r: r >= 0,
+        )
         if res > 0:
             vals = tuple(
                 grouper(3, (int.from_bytes(buf[i], "little") for i in range(res)))
@@ -279,19 +302,31 @@ class Remote(CBindings):
 
     def apply_config(self, name):
         """applies a config from memory"""
-        error_msg = (
+        ERR_MSG = (
             f"No config with name '{name}' is loaded into memory",
             f"Known configs: {list(self.configs.keys())}",
         )
         try:
-            self.apply(self.configs[name])
+            config = self.configs[name]
-            self.logger.info(f"Profile '{name}' applied!")
+        except KeyError as e:
-        except KeyError:
+            self.logger.error(("\n").join(ERR_MSG))
-            self.logger.error(("\n").join(error_msg))
+            raise VMError(("\n").join(ERR_MSG)) from e
+
+        if "extends" in config:
+            extended = config["extends"]
+            config = {
+                k: v
+                for k, v in deep_merge(self.configs[extended], config)
+                if k not in ("extends")
+            }
+            self.logger.debug(
+                f"profile '{name}' extends '{extended}', profiles merged.."
+            )
+        self.apply(config)
+        self.logger.info(f"Profile '{name}' applied!")
 
     def logout(self) -> NoReturn:
         """Wait for dirty parameters to clear, then logout of the API"""
-        self.clear_dirty()
         time.sleep(0.1)
         self.call(self.vm_logout)
         self.logger.info(f"{type(self).__name__}: Successfully logged out of {self}")

voicemeeterlib/util.py

@@ -1,3 +1,4 @@
+import copy
 import functools
 from itertools import zip_longest
 from typing import Iterator
@@ -70,3 +71,17 @@ def grouper(n, iterable, fillvalue=None):
     """
     args = [iter(iterable)] * n
     return zip_longest(fillvalue=fillvalue, *args)
+
+
+def deep_merge(dict1, dict2):
+    """Generator function for deep merging two dicts"""
+    for k in set(dict1) | set(dict2):
+        if k in dict1 and k in dict2:
+            if isinstance(dict1[k], dict) and isinstance(dict2[k], dict):
+                yield k, dict(deep_merge(dict1[k], dict2[k]))
+            else:
+                yield k, dict2[k]
+        elif k in dict1:
+            yield k, dict1[k]
+        else:
+            yield k, dict2[k]

voicemeeterlib/vban.py

@@ -1,6 +1,7 @@
 from abc import abstractmethod
 
 from .iremote import IRemote
+from .kinds import kinds_all
 
 
 class VbanStream(IRemote):
@@ -133,6 +134,21 @@ class VbanInstream(VbanStream):
         return super(VbanInstream, self).bit
 
 
+class VbanAudioInstream(VbanInstream):
+    def __str__(self):
+        return f"{type(self).__name__}{self._remote.kind}{self.index}"
+
+
+class VbanMidiInstream(VbanInstream):
+    def __str__(self):
+        return f"{type(self).__name__}{self._remote.kind}{self.index}"
+
+
+class VbanTextInstream(VbanInstream):
+    def __str__(self):
+        return f"{type(self).__name__}{self._remote.kind}{self.index}"
+
+
 class VbanOutstream(VbanStream):
     """
     class representing a vban outstream
@@ -148,6 +164,52 @@ class VbanOutstream(VbanStream):
         return "out"
 
 
+class VbanAudioOutstream(VbanOutstream):
+    def __str__(self):
+        return f"{type(self).__name__}{self._remote.kind}{self.index}"
+
+
+class VbanMidiOutstream(VbanOutstream):
+    def __str__(self):
+        return f"{type(self).__name__}{self._remote.kind}{self.index}"
+
+
+def _make_stream_pair(remote, kind):
+    num_instream, num_outstream, num_midi, num_text = kind.vban
+
+    def _generate_streams(i, dir):
+        """generator function for instream/outstream types"""
+        if dir == "in":
+            if i < num_instream:
+                yield VbanAudioInstream
+            elif i < num_instream + num_midi:
+                yield VbanMidiInstream
+            else:
+                yield VbanTextInstream
+        else:
+            if i < num_outstream:
+                yield VbanAudioOutstream
+            else:
+                yield VbanMidiOutstream
+
+    return (
+        tuple(
+            cls(remote, i)
+            for i in range(num_instream + num_midi + num_text)
+            for cls in _generate_streams(i, "in")
+        ),
+        tuple(
+            cls(remote, i)
+            for i in range(num_outstream + num_midi)
+            for cls in _generate_streams(i, "out")
+        ),
+    )
+
+
+def _make_stream_pairs(remote):
+    return {kind.name: _make_stream_pair(remote, kind) for kind in kinds_all}
+
+
 class Vban:
     """
     class representing the vban module
@@ -157,9 +219,7 @@ class Vban:
 
     def __init__(self, remote):
         self.remote = remote
-        num_instream, num_outstream = remote.kind.vban
+        self.instream, self.outstream = _make_stream_pairs(remote)[remote.kind.name]
-        self.instream = tuple(VbanInstream(remote, i) for i in range(num_instream))
-        self.outstream = tuple(VbanOutstream(remote, i) for i in range(num_outstream))
 
     def enable(self):
         self.remote.set("vban.Enable", 1)