documentation changes

python version upper limit increased to support 3.11

README.md

@@ -6,7 +6,7 @@
 
 A remote control app for [Voicemeeter][voicemeeter], designed to be used with the [NVDA screen reader][nvda].
 
-This is still an early release but it should be usable.
+For an outline of this projects goals see the [SPECIFICATION][spec].
 
 <img src="./img/settings.png" width=350 alt="Image of Voicemeeter NVDA app settings tab">
 
@@ -18,11 +18,31 @@ This is still an early release but it should be usable.
 
 ### Installation
 
-First clone the source files from this repository
+#### `From Source`
 
-`git clone https://github.com/onyx-and-iris/nvda-voicemeeter.git`
+First clone the source files from this repository and install the dependencies.
 
-Then download the [Controller Client][controller_client] and place the files into the directory `controllerClient`.
+```
+git clone https://github.com/onyx-and-iris/nvda-voicemeeter.git
+cd nvda-voicemeeter
+pip install .
+```
+
+Then download the [Controller Client][controller_client] and place the dll files into the directory `controllerClient`.
+
+Your directory structure should look like this:
+
+├── `controllerClient/`
+
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;├── `x64/`
+
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;├── nvdaControllerClient64.dll
+
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;├── `x86/`
+
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;├── nvdaControllerClient32.dll
+
+#### `From Releases`
 
 If you want to get started quickly and easily I have uploaded some compiled versions of the app in the [Releases][releases] section.
 
@@ -42,7 +62,7 @@ with voicemeeterlib.api(KIND_ID, sync=True) as vm:
         window.run()
 ```
 
-### `KIND_ID`
+### KIND_ID
 
 May be one of the following:
 
@@ -52,24 +72,38 @@ May be one of the following:
 
 ### Use
 
-The app presents four tabs `Settings`, `Physical Strip`, `Virtual Strip` and `Buses`. Navigate between the tabs with `Control + TAB` and `Control + SHIFT + TAB`.
+#### `Tabs`
+
+The app presents four tabs `Settings`, `Physical Strip`, `Virtual Strip` and `Buses`. Navigate between the tabs with `Control + TAB` and `Control + SHIFT + TAB` or once focused on any tab, `Left` and `Right` arrow keys.
 
 All controls within the tabs may be navigated between using `TAB`.
 
+#### `Settings`
+
 The following controls offer context menus accessed by pressing `SPACE` or `ENTER`:
 
 - Hardware In
 - Hardware Out
 - Patch Composite
 
+Press `ESCAPE` to exit any context menu.
+
 All other buttons can be triggered by pressing `SPACE` or `ENTER`.
 
 To adjust Patch Asio Inputs to Strips and Patch Insert values use `UP` and `DOWN` arrows when in focus.
 
+To access Advanced Settings you may press the Advanced Settings button or use `Control + A` when in the `Settings` tab.
+
+#### `Strip/Bus`
+
 To rename a strip/bus channel navigate to the relevant tab, then press `F2`. This will open a popup window where you can set the channel index (with a spinbox) and set the new label using a text input box.
+
 Pressing the `OK` button with an empty text input will clear the label. In this case the label will be read as a default value for that channel. For example, if the leftmost Strip label were cleared, the screen reader will now read `Hardware Input 1`.
+
 Pressing `Cancel` will close the popup window with no affect on the label.
 
+#### `Menu`
+
 A single menu item `Voicemeeter` can be opened using `Alt` and then `v`. The menu allows you to:
 
 - Restart Voicemeeter audio engine
@@ -84,6 +118,17 @@ The `Save Settings` option opens a popup window with two buttons, `Browse` and `
 
 If you have any questions/suggestions feel free to raise an issue or open a new discussion.
 
+### Special Thanks
+
+[Mario Loreti](https://www.marioloreti.net/en/) for his help in testing and offering feedback during development.
+
+[NVAccess](https://www.nvaccess.org/) for creating the open source NVDA screen reader and its controller client.
+
+[Vincent Burel](https://github.com/vburel2018) for creating Voicemeeter and its SDK.
+
+[PySimpleGUI](https://github.com/PySimpleGUI) team for creating an awesome GUI framework.
+
+[spec]: ./SPECIFICATION.md
 [voicemeeter]: https://voicemeeter.com/
 [nvda]: https://www.nvaccess.org/
 [controller_client]: https://github.com/nvaccess/nvda/tree/master/extras/controllerClient

SPECIFICATION.md

@@ -0,0 +1,30 @@
+# Software Specification
+
+## Description
+
+A remote control utility for Voicemeeter designed to be used with the NVDA screen reader.
+
+## Requirements
+
+#### Functional Goals
+
+- Parameter updates caused by user input should be read back to the user via the screen reader.
+- When focusing a control the current value for that control should be read back to the user.
+- The application should scale correctly according to each kind of Voicemeeter (basic, banana, potato). This means the following:
+  - Correct number of strips/buses.
+  - Correct number of bus assignments for each strip.
+  - Where certain controls are valid for one kind they may not be for another.
+- Where possible set limits on data entry and keep controls appropriate for the type of parameter.
+
+#### Accessibility Goals
+
+- Every control must be usable with a keyboard.
+- Navigation around the application must be doable with a keyboard.
+- Should use standard Windows controls only.
+
+## Limitations
+
+- May not cover 100% of the Voicemeeter GUI, for example the many EQ parameters.
+- Only designed to work with the NVDA screen reader. Other screen readers not supported.
+- Only the main Voicemeeter GUI supported by this application. No support for Matrix or other Voicemeeter products.
+- Runs on Python version 3.10 or greater.

pdm.lock

@@ -6,7 +6,7 @@ groups = ["default", "build", "lint", "test"]
 cross_platform = true
 static_urls = false
 lock_version = "4.3"
-content_hash = "sha256:9051151ac4ac0edefdfaf52faa91dbff89d8bbc942a6ffa61b6ec6fee502aa8a"
+content_hash = "sha256:ba53368b628b713c9cf4eb54e6f5c5c4af207c8e247d473417e4c2a4b47f645d"
 
 [[package]]
 name = "altgraph"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nvda_voicemeeter"
-version = "0.1.2"
+version = "0.2.1"
 description = "A Voicemeeter app compatible with NVDA"
 authors = [
     { name = "onyx-and-iris", email = "code@onyxandiris.online" },
@@ -10,7 +10,7 @@ dependencies = [
     "pyparsing>=3.1.1",
     "voicemeeter-api>=2.4.9",
 ]
-requires-python = ">=3.10,<3.11"
+requires-python = ">=3.10,<3.12"
 readme = "README.md"
 
 [project.license]

src/nvda_voicemeeter/builder.py

@@ -27,6 +27,7 @@ class Builder:
             steps = (
                 self.make_tab0_row0,
                 self.make_tab0_row1,
+                self.make_tab0_row5,
             )
         else:
             steps = (
@@ -102,8 +103,6 @@ class Builder:
         """tab0 row1 represents hardware outs"""
 
         def add_physical_device_opts(layout):
-            devices = get_output_device_list(self.vm)
-            devices.append("- remove device selection -")
             if self.kind.name == "basic":
                 num_outs = self.kind.phys_out + self.kind.virt_out
             else:
@@ -113,7 +112,7 @@ class Builder:
                     psg.ButtonMenu(
                         f"A{i + 1}",
                         size=(6, 3),
-                        menu_def=["", devices],
+                        menu_def=["", get_output_device_list(i, self.vm)],
                         key=f"HARDWARE OUT||A{i + 1}",
                     )
                     for i in range(num_outs)
@@ -228,24 +227,20 @@ class Builder:
         return psg.Frame("PATCH INSERT", asio_checkboxes)
 
     def make_tab0_row5(self) -> psg.Frame:
-        """tab0 row5 represents asio buffer"""
-
-        samples = get_asio_samples_list()
-        samples.append("Default")
+        """tab0 row5 represents advanced settings"""
 
         return psg.Frame(
-            "ASIO BUFFER",
+            "ADVANCED SETTINGS",
             [
                 [
-                    psg.ButtonMenu(
-                        "ASIO BUFFER",
-                        size=(14, 2),
-                        menu_def=["", samples],
-                        key="ASIO BUFFER",
+                    psg.Button(
+                        "ADVANCED SETTINGS",
+                        size=(20, 2),
+                        key="ADVANCED SETTINGS",
                     )
-                ]
                 ],
-            key="ASIO BUFFER FRAME",
+            ],
+            key="ADVANCED SETTINGS FRAME",
         )
 
     def make_tab1_row(self, i) -> psg.Frame:

src/nvda_voicemeeter/util.py

@@ -13,12 +13,32 @@ def get_insert_checkbox_index(kind, channel, num) -> int:
     return (2 * kind.phys_in) + (8 * (num - kind.phys_in - 1)) + channel
 
 
+_rejected_ids = (
+    "VBAudio100VMVAIO3",
+    "{F5735BD4-6EAF-4758-9710-9886E5AD0FF3}",
+    "{0239BE07-CEEF-4236-A900-AA778D432FD4}",
+)
+
+
 def get_input_device_list(vm) -> list:
-    return ["{type}: {name}".format(**vm.device.input(i)) for i in range(vm.device.ins)]
+    devices = []
+    for j in range(vm.device.ins):
+        device = vm.device.input(j)
+        if device["id"] not in _rejected_ids:
+            devices.append("{type}: {name}".format(**device))
+    return devices
 
 
-def get_output_device_list(vm) -> list:
-    return ["{type}: {name}".format(**vm.device.output(i)) for i in range(vm.device.outs)]
+def get_output_device_list(i, vm) -> list:
+    devices = []
+    for j in range(vm.device.outs):
+        device = vm.device.output(j)
+        if device["id"] not in _rejected_ids:
+            devices.append("{type}: {name}".format(**device))
+    if i == 0:
+        return devices
+    devices.append("- remove device selection -")
+    return [device for device in devices if not device.startswith("asio")]
 
 
 def get_patch_composite_list(kind) -> list:
@@ -47,28 +67,20 @@ def get_patch_insert_channels() -> list:
 _patch_insert_channels = get_patch_insert_channels()
 
 
-def get_asio_samples_list() -> list:
-    return [
-        "1024",
-        "768",
-        "704",
-        "640",
-        "576",
-        "512",
-        "480",
-        "448",
-        "441",
-        "416",
-        "384",
-        "352",
-        "320",
-        "288",
-        "256",
-        "224",
-        "192",
-        "160",
-        "128",
+def get_asio_samples_list(driver) -> list:
+    if driver == "MME":
+        samples = ["2048", "1536", "1024", "896", "768", "704", "640", "576", "512", "480", "441"]
+    else:
+        # fmt: off
+        samples = [
+            "2048", "1536", "1024", "768", "704", "640", "576", "512", "480", "448", "441", "416", "384",
+            "352", "320", "288", "256", "224", "192", "160", "128"
         ]
+        # fmt: on
+        if driver == "ASIO":
+            samples = [x for x in samples if x not in ("2048", "1536")]
+    samples.append("Default")
+    return samples
 
 
 def get_tabs_labels() -> list:

src/nvda_voicemeeter/window.py

@@ -18,6 +18,7 @@ from .parser import Parser
 from .util import (
     _patch_insert_channels,
     get_asio_checkbox_index,
+    get_asio_samples_list,
     get_bus_modes,
     get_channel_identifier_list,
     get_insert_checkbox_index,
@@ -62,10 +63,7 @@ class NVDAVMWindow(psg.Window):
             self[f"HARDWARE OUT||A2"].Widget.config(**buttonmenu_opts)
         if self.kind.name != "basic":
             [self[f"PATCH COMPOSITE||PC{i + 1}"].Widget.config(**buttonmenu_opts) for i in range(self.kind.phys_out)]
-            self["ASIO BUFFER"].Widget.config(**buttonmenu_opts)
-        if self.kind.name != "basic":
-            self["ASIO BUFFER FRAME"].update(visible=False)
-            self["ASIO BUFFER FRAME"].hide_row()
+
         self.register_events()
 
     def __enter__(self):
@@ -128,6 +126,7 @@ class NVDAVMWindow(psg.Window):
         self["tabs"].bind("<FocusIn>", "||FOCUS IN")
         self.bind("<Control-KeyPress-Tab>", "CTRL-TAB")
         self.bind("<Control-Shift-KeyPress-Tab>", "CTRL-SHIFT-TAB")
+        self.bind("<Control-a>", "CTRL-A")
 
         # Hardware In
         for i in range(self.vm.kind.phys_in):
@@ -167,6 +166,10 @@ class NVDAVMWindow(psg.Window):
                 else:
                     [self[f"INSERT CHECKBOX||IN{i + 1} {j}"].bind("<FocusIn>", "||FOCUS IN") for j in range(8)]
 
+        # Advanced Settings
+        self["ADVANCED SETTINGS"].bind("<FocusIn>", "||FOCUS IN")
+        self["ADVANCED SETTINGS"].bind("<Return>", "||KEY ENTER")
+
         # Strip Params
         for i in range(self.kind.num_strip):
             for j in range(self.kind.phys_out):
@@ -193,12 +196,6 @@ class NVDAVMWindow(psg.Window):
                 self[f"BUS {i}||{param}"].bind("<FocusIn>", "||FOCUS IN")
                 self[f"BUS {i}||{param}"].bind("<Return>", "||KEY ENTER")
 
-        # ASIO Buffer
-        if self.kind.name != "basic":
-            self["ASIO BUFFER"].bind("<FocusIn>", "||FOCUS IN")
-            self["ASIO BUFFER"].bind("<space>", "||KEY SPACE", propagate=False)
-            self["ASIO BUFFER"].bind("<Return>", "||KEY ENTER", propagate=False)
-
     def popup_save_as(self, message, title=None, initial_folder=None):
         layout = [
             [psg.Text(message)],
@@ -219,27 +216,24 @@ class NVDAVMWindow(psg.Window):
             self.logger.debug(f"values::{values}")
             if event in (psg.WIN_CLOSED, "Cancel"):
                 break
-            elif event.endswith("||FOCUS IN"):
+            match parsed_cmd := self.parser.match.parseString(event):
+                case [[button], ["FOCUS", "IN"]]:
                     if values["Browse"]:
                         filepath = values["Browse"]
                         break
-                label = event.split("||")[0]
-                self.TKroot.after(
-                    200 if label == "Edit" else 1,
-                    self.nvda.speak,
-                    label,
-                )
-            elif event.endswith("||KEY ENTER"):
+                    self.nvda.speak(button)
+                case [[button], ["KEY", "ENTER"]]:
                     window.find_element_with_focus().click()
+            self.logger.debug(f"parsed::{parsed_cmd}")
         window.close()
         if filepath:
             return Path(filepath)
 
     def popup_rename(self, message, title=None, tab=None):
         if tab == "Physical Strip":
-            upper = self.kind.phys_out + 1
+            upper = self.kind.phys_in + 1
         elif tab == "Virtual Strip":
-            upper = self.kind.virt_out + 1
+            upper = self.kind.virt_in + 1
         elif tab == "Buses":
             upper = self.kind.num_bus + 1
 
@@ -269,24 +263,87 @@ class NVDAVMWindow(psg.Window):
             self.logger.debug(f"values::{values}")
             if event in (psg.WIN_CLOSED, "Cancel"):
                 break
-            elif event.endswith("||KEY ENTER"):
-                window.find_element_with_focus().click()
-            elif event == "Index":
+            match parsed_cmd := self.parser.match.parseString(event):
+                case ["Index"]:
                     val = values["Index"]
                     self.nvda.speak(f"Index {val}")
-            elif event.endswith("||FOCUS IN"):
-                if event.startswith("Index"):
+                case [[button], ["FOCUS", "IN"]]:
+                    if button == "Index":
                         val = values["Index"]
                         self.nvda.speak(f"Index {val}")
                     else:
-                    self.nvda.speak(event.split("||")[0])
-            elif event == "Ok":
+                        self.nvda.speak(button)
+                case [[button], ["KEY", "ENTER"]]:
+                    window.find_element_with_focus().click()
+                case ["Ok"]:
                     data = values
                     break
-
+            self.logger.debug(f"parsed::{parsed_cmd}")
         window.close()
         return data
 
+    def popup_advanced_settings(self, title):
+        def _make_buffering_frame() -> psg.Frame:
+            buffer = [
+                [
+                    psg.ButtonMenu(
+                        driver,
+                        size=(14, 2),
+                        menu_def=["", get_asio_samples_list(driver)],
+                        key=f"BUFFER {driver}",
+                    )
+                    for driver in ("MME", "WDM", "KS", "ASIO")
+                ],
+            ]
+            return psg.Frame("BUFFERING", buffer)
+
+        layout = []
+        steps = (_make_buffering_frame,)
+        for step in steps:
+            layout.append([step()])
+        layout.append([psg.Button("Exit", size=(8, 2))])
+
+        window = psg.Window(title, layout, finalize=True)
+        buttonmenu_opts = {"takefocus": 1, "highlightthickness": 1}
+        for driver in ("MME", "WDM", "KS", "ASIO"):
+            window[f"BUFFER {driver}"].Widget.config(**buttonmenu_opts)
+            window[f"BUFFER {driver}"].bind("<FocusIn>", "||FOCUS IN")
+            window[f"BUFFER {driver}"].bind("<space>", "||KEY SPACE", propagate=False)
+            window[f"BUFFER {driver}"].bind("<Return>", "||KEY ENTER", propagate=False)
+        window["Exit"].bind("<FocusIn>", "||FOCUS IN")
+        window["Exit"].bind("<Return>", "||KEY ENTER")
+        while True:
+            event, values = window.read()
+            self.logger.debug(f"event::{event}")
+            self.logger.debug(f"values::{values}")
+            if event in (psg.WIN_CLOSED, "Exit"):
+                break
+            match parsed_cmd := self.parser.match.parseString(event):
+                case ["BUFFER MME" | "BUFFER WDM" | "BUFFER KS" | "BUFFER ASIO"]:
+                    if values[event] == "Default":
+                        if "MME" in event:
+                            val = 1024
+                        elif "WDM" in event or "KS" in event:
+                            val = 512
+                        else:
+                            val = 0
+                    else:
+                        val = int(values[event])
+                    driver = event.split()[1]
+                    self.vm.set(f"option.buffer.{driver.lower()}", val)
+                    self.TKroot.after(200, self.nvda.speak, f"{driver} BUFFER {val if val else 'default'}")
+                case [["BUFFER", driver], ["FOCUS", "IN"]]:
+                    val = int(self.vm.get(f"option.buffer.{driver.lower()}"))
+                    self.nvda.speak(f"{driver} BUFFER {val if val else 'default'}")
+                case [["BUFFER", driver], ["KEY", "SPACE" | "ENTER"]]:
+                    open_context_menu_for_buttonmenu(window, f"BUFFER {driver}")
+                case [[button], ["FOCUS", "IN"]]:
+                    self.nvda.speak(button)
+                case [[button], ["KEY", "ENTER"]]:
+                    window.find_element_with_focus().click()
+            self.logger.debug(f"parsed::{parsed_cmd}")
+        window.close()
+
     def run(self):
         """
         Parses the event string and matches it to events
@@ -323,7 +380,8 @@ class NVDAVMWindow(psg.Window):
                                 self[f"STRIP {index}||LABEL"].update(value=label)
                                 self.cache["labels"][f"STRIP {index}||LABEL"] = label
                             case "Virtual Strip":
-                                label = data.get("Edit") or f"Virtual Input {index + 1}"
+                                index += self.kind.phys_in
+                                label = data.get("Edit") or f"Virtual Input {index - self.kind.phys_in + 1}"
                                 self.vm.strip[index].label = label
                                 self[f"STRIP {index}||LABEL"].update(value=label)
                                 self.cache["labels"][f"STRIP {index}||LABEL"] = label
@@ -409,7 +467,7 @@ class NVDAVMWindow(psg.Window):
                             setattr(self.vm.strip[index].device, "wdm", "")
                             self.TKroot.after(200, self.nvda.speak, f"HARDWARE IN {key} device selection removed")
                         case [driver, device_name]:
-                            setattr(self.vm.strip[index].device, driver, device_name.strip())
+                            setattr(self.vm.strip[index].device, driver, device_name.lstrip())
                             phonetic = {"mme": "em em e"}
                             self.TKroot.after(
                                 200,
@@ -430,7 +488,7 @@ class NVDAVMWindow(psg.Window):
                             setattr(self.vm.bus[index].device, "wdm", "")
                             self.TKroot.after(200, self.nvda.speak, f"HARDWARE OUT {key} device selection removed")
                         case [driver, device_name]:
-                            setattr(self.vm.bus[index].device, driver, device_name.strip())
+                            setattr(self.vm.bus[index].device, driver, device_name.lstrip())
                             phonetic = {"mme": "em em e"}
                             self.TKroot.after(
                                 200,
@@ -494,19 +552,14 @@ class NVDAVMWindow(psg.Window):
                     num = int(in_num[-1])
                     self.nvda.speak(f"Patch INSERT IN#{num} {channel} {'on' if val else 'off'}")
 
-                # ASIO Buffer
-                case ["ASIO BUFFER"]:
-                    if values[event] == "Default":
-                        val = 0
-                    else:
-                        val = values[event]
-                    self.vm.option.buffer("asio", val)
-                    self.TKroot.after(200, self.nvda.speak, f"ASIO BUFFER {val if val else 'default'}")
-                case [["ASIO", "BUFFER"], ["FOCUS", "IN"]]:
-                    val = int(self.vm.get("option.buffer.asio"))
-                    self.nvda.speak(f"ASIO BUFFER {val if val else 'default'}")
-                case [["ASIO", "BUFFER"], ["KEY", "SPACE" | "ENTER"]]:
-                    open_context_menu_for_buttonmenu(self, "ASIO BUFFER")
+                # Advanced Settings
+                case ["ADVANCED SETTINGS"] | ["CTRL-A"]:
+                    if values["tabs"] == "Settings":
+                        self.popup_advanced_settings(title="Advanced Settings")
+                case [["ADVANCED", "SETTINGS"], ["FOCUS", "IN"]]:
+                    self.nvda.speak("ADVANCED SETTINGS")
+                case [["ADVANCED", "SETTINGS"], ["KEY", "ENTER"]]:
+                    self.find_element_with_focus().click()
 
                 # Strip Params
                 case [["STRIP", index], [param]]: