Create README.md

first version of readme

README.md

@@ -0,0 +1,138 @@
+# VBAN CMD
+This package offers a Python interface for the [Voicemeeter RT Packet Service](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf).
+
+Tested against
+- Basic 1.0.8.1
+- Banana 2.0.6.1
+- Potato 3.0.2.1
+
+## Prerequisites
+- Voicemeeter 1 (Basic), 2 (Banana) or 3 (Potato)
+- Python 3.9+
+
+## Installation
+```
+git clone https://github.com/onyx-and-iris/vban-cmd-python
+cd vban-cmd-python
+```
+
+Just the wrapper:
+```
+pip install .
+```
+
+With development dependencies:
+```
+pip install -e .['development']
+```
+
+#### Use with a context manager:
+Unlike the Remote API the VBAN RT Packet service has no login limitations since receiving data requires
+a client to simply register to the service. It is therefore advised to use this code only with a context manager.
+Parameter coverage is not as extensive for the RT Packet Service as with the Remote API so defined below are the
+classes/methods available through this package.
+
+### Example 1
+```python
+import vban_cmd
+
+class ManyThings:
+    def __init__(self, vban):
+        self.vban = vban
+
+    def things(self):
+        # Set the mapping of the second input strip
+        self.vban.strip[1].A3 = True
+        print(f'Output A3 of Strip {self.vban.strip[1].label}: {self.vban.strip[1].A3}')
+
+    def other_things(self):
+        # Toggle mute for the leftmost output bus
+        self.vban.bus[0].mute = not self.vban.bus[0].mute
+
+
+def main():
+    with vban_cmd.connect(kind_id, ip=ip) as vban:
+        do = ManyThings(vban)
+        do.things()
+        do.other_things()
+
+if __name__ == '__main__':
+    kind_id = 'potato'
+    ip = '<ip address>'
+
+    main()
+```
+
+## API
+### Kinds
+A *kind* specifies a major Voicemeeter version. Currently this encompasses
+- `basic`
+- `banana`
+- `potato`
+
+#### `vban_cmd.connect(kind_id, ip=ip) -> '(VMRemote)'`
+Factory function for remotes.
+- `ip`: remote pc you wish to send requests to.
+
+
+### `VbanCmd` (higher level)
+#### `vban.type`
+The kind of the Voicemeeter instance.
+
+#### `vban.version`
+A tuple of the form `(v1, v2, v3, v4)`.
+
+#### `vban.strip`
+An `InputStrip` tuple, containing both physical and virtual.
+#### `vban.bus`
+An `OutputBus` tuple, containing both physical and virtual.
+
+#### `vban.show()`
+Shows Voicemeeter if it's hide. No effect otherwise.
+#### `vban.hide()`
+Hides Voicemeeter if it's shown. No effect otherwise.
+#### `vban.shutdown()`
+Closes Voicemeeter.
+#### `vban.restart()`
+Restarts Voicemeeter's audio engine.
+
+### `Strip`
+The following properties are gettable and settable:
+- `mono`: boolean
+- `solo`: boolean
+- `mute`: boolean
+- `label`: string
+- Output mapping (e.g. `A1`, `B3`, etc.): boolean, depends on the Voicemeeter kind
+
+The following properties are settable:
+- `label`: string
+- `gain`: float, from -60.0 to 12.0
+- `comp`: float, from 0.0 to 10.0
+- `gate`: float, from 0.0 to 10.0
+- `limit`: int, from -40 to 12
+- `gainlayer`: float
+
+### `Bus`
+The following properties are gettable and settable:
+- `mute`: boolean
+- `mono`: boolean
+- `eq`: boolean
+- `eq_ab`: boolean
+- `label`: string
+
+The following properties are settable:
+- `gain`: float
+
+
+### `Errors`
+- `errors.VMCMDErrors`: Base VMCMD error class.
+
+### `Tests`
+First make sure you installed the [development dependencies](https://github.com/onyx-and-iris/vban-cmd-python#installation)
+
+To run the tests from tests directory:
+
+`nosetests --r test -v`
+
+## Resources
+- [Voicemeeter RT Packet Service](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf)