Update README.md

This commit is contained in:
onyx-and-iris 2022-04-27 20:00:30 +01:00
parent 79abec7531
commit f55d86514c

138
README.md
View File

@ -1,6 +1,8 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/onyx-and-iris/vban-cmd-python/blob/dev/LICENSE) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/onyx-and-iris/vban-cmd-python/blob/dev/LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
# VBAN CMD # VBAN CMD
This package offers a Python interface for [Voicemeeter VBAN TEXT](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf#page=19) as well as the [Voicemeeter RT Packet Service](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf#page=27) which allows a client to send and receive parameter values over a local network. This package offers a Python interface for [Voicemeeter VBAN TEXT](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf#page=19) as well as the [Voicemeeter RT Packet Service](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf#page=27) which allows a client to send and receive parameter values over a local network.
It may be used standalone or to extend the [Voicemeeter Remote Python API](https://github.com/onyx-and-iris/voicemeeter-api-python) It may be used standalone or to extend the [Voicemeeter Remote Python API](https://github.com/onyx-and-iris/voicemeeter-api-python)
@ -8,35 +10,43 @@ It may be used standalone or to extend the [Voicemeeter Remote Python API](https
For sending audio across a network with VBAN you will need to look elsewhere. For sending audio across a network with VBAN you will need to look elsewhere.
## Tested against ## Tested against
- Basic 1.0.8.1
- Banana 2.0.6.1 - Basic 1.0.8.1
- Potato 3.0.2.1 - Banana 2.0.6.1
- Potato 3.0.2.1
## Prerequisites ## Prerequisites
- Voicemeeter 1 (Basic), 2 (Banana) or 3 (Potato)
- Python 3.9+ - Voicemeeter 1 (Basic), 2 (Banana) or 3 (Potato)
- Python 3.9+
## Installation ## Installation
``` ```
git clone https://github.com/onyx-and-iris/vban-cmd-python git clone https://github.com/onyx-and-iris/vban-cmd-python
cd vban-cmd-python cd vban-cmd-python
``` ```
Just the interface: Just the interface:
``` ```
pip install . pip install .
``` ```
With development dependencies: With development dependencies:
``` ```
pip install -e .['development'] pip install -e .['development']
``` ```
## Usage ## Usage
#### Use with a context manager: #### Use with a context manager:
Parameter coverage is not as extensive for the RT Packet Service as with the Remote API. Parameter coverage is not as extensive for the RT Packet Service as with the Remote API.
### Example 1 ### Example 1
```python ```python
import vbancmd import vbancmd
@ -68,9 +78,11 @@ if __name__ == '__main__':
``` ```
#### Or perform setup/teardown independently: #### Or perform setup/teardown independently:
for example: for example:
### Example 2 ### Example 2
```python ```python
import vbancmd import vbancmd
@ -93,20 +105,23 @@ vban.logout()
``` ```
## Profiles ## Profiles
Profiles through config files are supported. Profiles through config files are supported.
Three example profiles are provided with the package, one for each kind of Voicemeeter. Three example profiles are provided with the package, one for each kind of Voicemeeter.
To test one first rename _profiles directory to profiles. To test one first rename \_profiles directory to profiles.
They will be loaded into memory but not applied. To apply one you may do: They will be loaded into memory but not applied. To apply one you may do:
`vmr.apply_profile('config')`, but remember to save your current settings first. `vmr.apply_profile('config')`, but remember to save your current settings first.
profiles directory can be safely deleted if you don't wish to load them each time. profiles directory can be safely deleted if you don't wish to load them each time.
A config can contain any key that `connect.apply()` would accept. Additionally, `extends` can be provided to inherit from another profile. Two profiles are available by default: A config can contain any key that `connect.apply()` would accept. Additionally, `extends` can be provided to inherit from another profile. Two profiles are available by default:
- `blank`, all strip off and all sliders to `0.0`. mono, solo, mute, eq all disabled.
- `base`, all physical strip to `A1`, all virtual strip to `B1`, all sliders to `0.0`. - `blank`, all strip off and all sliders to `0.0`. mono, solo, mute, eq all disabled.
- `base`, all physical strip to `A1`, all virtual strip to `B1`, all sliders to `0.0`.
Sample `mySetup.toml` Sample `mySetup.toml`
```toml ```toml
extends = 'base' extends = 'base'
[strip-0] [strip-0]
@ -126,45 +141,64 @@ gain = 0.0
``` ```
## API ## API
### Kinds ### Kinds
A *kind* specifies a major Voicemeeter version. Currently this encompasses
- `basic` A _kind_ specifies a major Voicemeeter version. Currently this encompasses
- `banana`
- `potato` - `basic`
- `banana`
- `potato`
#### `vbancmd.connect(kind_id, **kwargs) -> '(VbanCmd)'` #### `vbancmd.connect(kind_id, **kwargs) -> '(VbanCmd)'`
Factory function for remotes. Keyword arguments include:
- `ip`: remote pc you wish to send requests to.
- `streamname`: default 'Command1'
- `port`: default 6990
- `channel`: from 0 to 255
- `bps`: bitrate of stream, default 0 should be safe for most cases.
Factory function for remotes. Keyword arguments include:
- `ip`: remote pc you wish to send requests to.
- `streamname`: default 'Command1'
- `port`: default 6990
- `channel`: from 0 to 255
- `bps`: bitrate of stream, default 0 should be safe for most cases.
### `VbanCmd` (higher level) ### `VbanCmd` (higher level)
#### `vban.type` #### `vban.type`
The kind of the Voicemeeter instance. The kind of the Voicemeeter instance.
#### `vban.version` #### `vban.version`
A tuple of the form `(v1, v2, v3, v4)`. A tuple of the form `(v1, v2, v3, v4)`.
#### `vban.strip` #### `vban.strip`
An `InputStrip` tuple, containing both physical and virtual. An `InputStrip` tuple, containing both physical and virtual.
#### `vban.bus` #### `vban.bus`
An `OutputBus` tuple, containing both physical and virtual. An `OutputBus` tuple, containing both physical and virtual.
#### `vban.show()` #### `vban.show()`
Shows Voicemeeter if it's hidden. No effect otherwise. Shows Voicemeeter if it's hidden. No effect otherwise.
#### `vban.hide()` #### `vban.hide()`
Hides Voicemeeter if it's shown. No effect otherwise. Hides Voicemeeter if it's shown. No effect otherwise.
#### `vban.shutdown()` #### `vban.shutdown()`
Closes Voicemeeter. Closes Voicemeeter.
#### `vban.restart()` #### `vban.restart()`
Restarts Voicemeeter's audio engine. Restarts Voicemeeter's audio engine.
#### `vban.apply(mapping)` #### `vban.apply(mapping)`
Updates values through a dict. Updates values through a dict.
Example: Example:
```python ```python
vban.apply({ vban.apply({
'strip-2': dict(A1=True, B1=True, gain=-6.0), 'strip-2': dict(A1=True, B1=True, gain=-6.0),
@ -173,80 +207,100 @@ vban.apply({
``` ```
### `Strip` ### `Strip`
The following properties are gettable and settable:
- `mono`: boolean
- `solo`: boolean
- `mute`: boolean
- `label`: string
- `gain`: float, -60 to 12
- Output mapping (e.g. `A1`, `B3`, etc.): boolean, depends on the Voicemeeter kind
The following properties are gettable and settable:
- `mono`: boolean
- `solo`: boolean
- `mute`: boolean
- `label`: string
- `gain`: float, -60 to 12
- Output mapping (e.g. `A1`, `B3`, etc.): boolean, depends on the Voicemeeter kind
The following properties are settable: The following properties are settable:
- `comp`: float, from 0.0 to 10.0
- `gate`: float, from 0.0 to 10.0 - `comp`: float, from 0.0 to 10.0
- `limit`: int, from -40 to 12 - `gate`: float, from 0.0 to 10.0
- `limit`: int, from -40 to 12
#### `gainlayer` #### `gainlayer`
- `gainlayer[j].gain`: float, -60 to 12
- `gainlayer[j].gain`: float, -60 to 12
for example: for example:
```python ```python
# set and get the value of the second input strip, fourth gainlayer # set and get the value of the second input strip, fourth gainlayer
vban.strip[1].gainlayer[3].gain = -6.3 vban.strip[1].gainlayer[3].gain = -6.3
print(vban.strip[1].gainlayer[3].gain) print(vban.strip[1].gainlayer[3].gain)
``` ```
Gainlayers defined for Potato version only. Gainlayers defined for Potato version only.
### `Bus` ### `Bus`
The following properties are gettable and settable: The following properties are gettable and settable:
- `mute`: boolean
- `mono`: boolean - `mute`: boolean
- `eq`: boolean - `mono`: boolean
- `eq_ab`: boolean - `eq`: boolean
- `label`: string - `eq_ab`: boolean
- `gain`: float, -60 to 12 - `label`: string
- `gain`: float, -60 to 12
#### `mode` #### `mode`
Bus modes are gettable and settable Bus modes are gettable and settable
- `normal`, `amix`, `bmix`, `repeat`, `composite`, `tvmix`, `upmix21`,
- `upmix41`, `upmix61`, `centeronly`, `lfeonly`, `rearonly` - `normal`, `amix`, `bmix`, `repeat`, `composite`, `tvmix`, `upmix21`,
- `upmix41`, `upmix61`, `centeronly`, `lfeonly`, `rearonly`
for example: for example:
```python ```python
# set leftmost bus mode to tvmix # set leftmost bus mode to tvmix
vban.bus[0].mode.tvmix = True vban.bus[0].mode.tvmix = True
``` ```
### `VbanCmd` (lower level) ### `VbanCmd` (lower level)
#### `vban.set_rt(id_, param, val)` #### `vban.set_rt(id_, param, val)`
Sends a string request RT Packet where the command would take the form: Sends a string request RT Packet where the command would take the form:
```python ```python
f'{id_}.{param}={val}' f'{id_}.{param}={val}'
``` ```
#### `vban._get_rt()` #### `vban._get_rt()`
Used for updating the RT data packet, used internally by the Interface. Used for updating the RT data packet, used internally by the Interface.
```python ```python
vban.public_packet = vban._get_rt() vban.public_packet = vban._get_rt()
``` ```
#### `vban.sendtext(cmd)` #### `vban.sendtext(cmd)`
Sends a multi parameter TEXT string command, for example: Sends a multi parameter TEXT string command, for example:
```python ```python
# Use ';' or ',' for delimiters. # Use ';' or ',' for delimiters.
vban.sendtext('Strip[0].Mute=1;Strip[3].A3=0;Bus[2].Mute=0;Bus[3].Eq.On=1') vban.sendtext('Strip[0].Mute=1;Strip[3].A3=0;Bus[2].Mute=0;Bus[3].Eq.On=1')
``` ```
### `Errors` ### `Errors`
- `errors.VMCMDErrors`: Base VMCMD error class.
- `errors.VMCMDErrors`: Base VMCMD error class.
### `Tests` ### `Tests`
First make sure you installed the [development dependencies](https://github.com/onyx-and-iris/vban-cmd-python#installation) 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: Then from tests directory:
`nosetests --r test -v` `pytest -v`
## Resources ## Resources
- [Voicemeeter RT Packet Service](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf)
- [Voicemeeter RT Packet Service](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf)