fix weird code?

apply_config() checks for 'extends' in TOML config

2.3.0 section added to README

three example extender.toml configs added

CHANGELOG.md

@@ -11,7 +11,27 @@ Before any major/minor/patch bump all unit tests will be run to verify they pass
 
 -   [x]
 
-## [2.1.0] - 2023-07-01
+## [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
 
@@ -24,6 +44,10 @@ Before any major/minor/patch bump all unit tests will be run to verify they pass
 
 -   Recorder.loop removed from documentation
 
+### Changed
+
+-   When out of bounds values are passed, log warnings instead of raising Errors. See [Issue #6][Issue 6].
+
 ## [2.0.0] - 2023-06-25
 
 Where possible I've attempted to make the changes backwards compatible. The breaking changes affect two higher classes, Strip and Bus, as well as the behaviour of events. All other changes are additive or QOL aimed at giving more options to the developer. For example, every low-level CAPI call is now logged and error raised on Exception, you can now register callback functions as well as observer classes, extra examples to demonstrate different use cases etc.
@@ -376,3 +400,4 @@ I will move this commit to a separate branch in preparation for version 2.0.
 -   project packaged with poetry and added to pypi.
 
 [issue 4]: https://github.com/onyx-and-iris/voicemeeter-api-python/issues/4
+[Issue 6]: https://github.com/onyx-and-iris/voicemeeter-api-python/issues/6

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
@@ -629,7 +629,9 @@ vm.option.sr = 48000
 
 The following methods are available:
 
--   `buffer(driver, buffer)` : Set buffer size for particular audio driver.
+-   `buffer(driver, buf)` : Set buffer size for particular audio driver.
+    -   buf: int, from 128 to 2048
+    -   driver:str, ("mme", "wdm", "ks", "asio")
 
 example:
 
@@ -637,10 +639,6 @@ example:
 vm.option.buffer("wdm", 512)
 ```
 
-driver defined as one of ("mme", "wdm", "ks", "asio")
-
-buffer, from 128 to 2048
-
 ##### delay[i]
 
 -   `get()`: int
@@ -693,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.vban.outstream[0].apply(on: True, name: 'streamname', bit: 24)
+vm.strip[0].apply({"mute": True, "gain": 3.2, "A1": True})
+vm.vban.outstream[0].apply({"on": True, "name": "streamname", "bit": 24})
 ```
 
 ## Config Files
@@ -703,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
@@ -711,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
 

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.0.2"
+version = "2.3.0"
 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 = [
-    { include = "voicemeeterlib" },
-]
+packages = [{ 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" / "."
-    subprocess.run(["py", str(path)])
+    scriptpath = Path.cwd() / "examples" / "dsl" / "."
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_events():
-    path = Path.cwd() / "examples" / "events" / "."
-    subprocess.run(["py", str(path)])
+    scriptpath = Path.cwd() / "examples" / "events" / "."
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_gui():
-    path = Path.cwd() / "examples" / "gui" / "."
-    subprocess.run(["py", str(path)])
+    scriptpath = Path.cwd() / "examples" / "gui" / "."
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_levels():
-    path = Path.cwd() / "examples" / "levels" / "."
-    subprocess.run(["py", str(path)])
+    scriptpath = Path.cwd() / "examples" / "levels" / "."
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_midi():
-    path = Path.cwd() / "examples" / "midi" / "."
-    subprocess.run(["py", str(path)])
+    scriptpath = Path.cwd() / "examples" / "midi" / "."
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_obs():
-    path = Path.cwd() / "examples" / "obs" / "."
-    subprocess.run(["py", str(path)])
+    scriptpath = Path.cwd() / "examples" / "obs" / "."
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def ex_observer():
-    path = Path.cwd() / "examples" / "observer" / "."
-    subprocess.run(["py", str(path)])
+    scriptpath = Path.cwd() / "examples" / "observer" / "."
+    subprocess.run([sys.executable, str(scriptpath)])
 
 
 def test():

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}")
-            elif not ok_exp(res):
-                raise CAPIError(f"{func.__name__} returned {res}")
+                    raise CAPIError(func.__name__, res)
+            elif not ok_exp(res) and res not in ok:
+                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/misc.py

@@ -1,6 +1,5 @@
 from typing import Optional
 
-from .error import VMError
 from .iremote import IRemote
 from .kinds import kinds_all
 
@@ -196,7 +195,7 @@ class Option(IRemote):
     def sr(self, val: int):
         opts = (44100, 48000, 88200, 96000, 176400, 192000)
         if val not in opts:
-            raise VMError(f"Expected one of: {opts}")
+            self.logger.warning(f"sr got: {val} but expected a value in {opts}")
         self.setter("sr", val)
 
     @property

voicemeeterlib/remote.py

@@ -70,7 +70,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 +116,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 +137,10 @@ class Remote(CBindings):
         try:
             while self.pdirty or self.mdirty:
                 pass
-        except CAPIError:
-            self.logger.error("no bind for mdirty, clearing pdirty only")
+        except CAPIError as e:
+            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 +180,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 +196,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 +254,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,15 +301,24 @@ 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])
-            self.logger.info(f"Profile '{name}' applied!")
-        except KeyError:
-            self.logger.error(("\n").join(error_msg))
+            config = self.configs[name].copy()
+        except KeyError as e:
+            self.logger.error(("\n").join(ERR_MSG))
+            raise VMError(("\n").join(ERR_MSG)) from e
+
+        if "extends" in config:
+            extended = config.pop("extends")
+            config = self.configs[extended] | config
+            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"""

voicemeeterlib/vban.py

@@ -1,6 +1,5 @@
 from abc import abstractmethod
 
-from .error import VMError
 from .iremote import IRemote
 
 
@@ -50,7 +49,9 @@ class VbanStream(IRemote):
     @port.setter
     def port(self, val: int):
         if not 1024 <= val <= 65535:
-            raise VMError("Expected value from 1024 to 65535")
+            self.logger.warning(
+                f"port got: {val} but expected a value from 1024 to 65535"
+            )
         self.setter("port", val)
 
     @property
@@ -61,7 +62,7 @@ class VbanStream(IRemote):
     def sr(self, val: int):
         opts = (11025, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000)
         if val not in opts:
-            raise VMError(f"Expected one of: {opts}")
+            self.logger.warning(f"sr got: {val} but expected a value in {opts}")
         self.setter("sr", val)
 
     @property
@@ -71,7 +72,7 @@ class VbanStream(IRemote):
     @channel.setter
     def channel(self, val: int):
         if not 1 <= val <= 8:
-            raise VMError("Expected value from 1 to 8")
+            self.logger.warning(f"channel got: {val} but expected a value from 1 to 8")
         self.setter("channel", val)
 
     @property
@@ -81,7 +82,7 @@ class VbanStream(IRemote):
     @bit.setter
     def bit(self, val: int):
         if val not in (16, 24):
-            raise VMError("Expected value 16 or 24")
+            self.logger.warning(f"bit got: {val} but expected value 16 or 24")
         self.setter("bit", 1 if (val == 16) else 2)
 
     @property
@@ -91,7 +92,7 @@ class VbanStream(IRemote):
     @quality.setter
     def quality(self, val: int):
         if not 0 <= val <= 4:
-            raise VMError("Expected value from 0 to 4")
+            self.logger.warning(f"quality got: {val} but expected a value from 0 to 4")
         self.setter("quality", val)
 
     @property
@@ -101,7 +102,7 @@ class VbanStream(IRemote):
     @route.setter
     def route(self, val: int):
         if not 0 <= val <= 8:
-            raise VMError("Expected value from 0 to 8")
+            self.logger.warning(f"route got: {val} but expected a value from 0 to 8")
         self.setter("route", val)