mirror of
https://github.com/onyx-and-iris/vban-cmd-python.git
synced 2025-01-18 18:40:47 +00:00
Update README.md
This commit is contained in:
parent
79abec7531
commit
f55d86514c
138
README.md
138
README.md
@ -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)
|
||||||
|
Loading…
Reference in New Issue
Block a user