mirror of
https://github.com/onyx-and-iris/vban-cmd-python.git
synced 2024-11-16 01:10:48 +00:00
b9db01c8f4
now packaged with poetry. added to pypi. major version bump due to dependency change. interface reworked to match the remote-api interface. readme updated with changes to installation pre-commit hook temporarily removed
211 lines
5.2 KiB
Markdown
211 lines
5.2 KiB
Markdown
[](https://github.com/onyx-and-iris/vban-cmd-python/blob/dev/LICENSE)
|
|
[](https://github.com/psf/black)
|
|
[](https://pycqa.github.io/isort/)
|
|
|
|
|
|
|
|
|
|
# VBAN CMD
|
|
|
|
This package offers a Python interface for the Voicemeeter RT Packet Service as well as Voicemeeter VBAN-TEXT.
|
|
|
|
This allows a user to get (rt packets) and set (vban-text) parameters over a local network. Consider the Streamer View app over VBAN, for example.
|
|
|
|
It may be used standalone or to extend the [Voicemeeter Remote Python API](https://github.com/onyx-and-iris/voicemeeter-api-python)
|
|
|
|
For sending audio across a network with VBAN you will need to look elsewhere.
|
|
|
|
For an outline of past/future changes refer to: [CHANGELOG](CHANGELOG.md)
|
|
|
|
## Tested against
|
|
|
|
- Basic 1.0.8.2
|
|
- Banana 2.0.6.2
|
|
- Potato 3.0.2.2
|
|
|
|
## Requirements
|
|
|
|
- [Voicemeeter](https://voicemeeter.com/)
|
|
- Python 3.11 or greater
|
|
|
|
## Installation
|
|
|
|
### `Pip`
|
|
|
|
Install voicemeeter-api package from your console
|
|
|
|
`pip install vban-cmd`
|
|
|
|
|
|
## `Use`
|
|
|
|
Simplest use case, use a context manager to request a VbanCmdvban_cmd class of a kind.
|
|
|
|
Login and logout are handled for you in this scenario.
|
|
|
|
#### `__main__.py`
|
|
|
|
```python
|
|
import vban_cmd
|
|
|
|
|
|
class ManyThings:
|
|
def __init__(self, vban):
|
|
self.vban = vban
|
|
|
|
def things(self):
|
|
self.vban.strip[0].label = "podmic"
|
|
self.vban.strip[0].mute = True
|
|
print(
|
|
f"strip 0 ({self.vban.strip[0].label}) has been set to {self.vban.strip[0].mute}"
|
|
)
|
|
|
|
def other_things(self):
|
|
info = (
|
|
f"bus 3 gain has been set to {self.vban.bus[3].gain}",
|
|
f"bus 4 eq has been set to {self.vban.bus[4].eq}",
|
|
)
|
|
self.vban.bus[3].gain = -6.3
|
|
self.vban.bus[4].eq = True
|
|
print("\n".join(info))
|
|
|
|
|
|
def main():
|
|
with vban_cmd.api(kind_id) as vban:
|
|
do = ManyThings(vban)
|
|
do.things()
|
|
do.other_things()
|
|
|
|
# set many parameters at once
|
|
vban.apply(
|
|
{
|
|
"strip-2": {"A1": True, "B1": True, "gain": -6.0},
|
|
"bus-2": {"mute": True},
|
|
"button-0": {"state": True},
|
|
"vban-in-0": {"on": True},
|
|
"vban-out-1": {"name": "streamname"},
|
|
}
|
|
)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
kind_id = "banana"
|
|
ip = "<ip address>"
|
|
|
|
main()
|
|
```
|
|
|
|
Otherwise you must remember to call `vban.login()`, `vban.logout()` at the start/end of your code.
|
|
|
|
## `kind_id`
|
|
|
|
Pass the kind of Voicemeeter as an argument. kind_id may be:
|
|
|
|
- `basic`
|
|
- `banana`
|
|
- `potato`
|
|
|
|
## `Available commands`
|
|
|
|
### Channels (strip/bus)
|
|
|
|
The following properties exist for audio channels.
|
|
|
|
- `mono`: boolean
|
|
- `solo`: boolean
|
|
- `mute`: boolean
|
|
- `label`: string
|
|
- `gain`: float, -60 to 12
|
|
- `A1 - A5`, `B1 - B3`: boolean
|
|
- `comp`: float, from 0.0 to 10.0
|
|
- `gate`: float, from 0.0 to 10.0
|
|
- `limit`: int, from -40 to 12
|
|
|
|
example:
|
|
|
|
```python
|
|
vban.strip[3].gain = 3.7
|
|
print(strip[0].label)
|
|
|
|
vban.bus[4].mono = true
|
|
```
|
|
|
|
### Command
|
|
|
|
Certain 'special' commands are defined by the API as performing actions rather than setting values. The following methods are available:
|
|
|
|
- `show()` : Bring Voiceemeter GUI to the front
|
|
- `shutdown()` : Shuts down the GUI
|
|
- `restart()` : Restart the audio engine
|
|
|
|
The following properties are write only and accept boolean values.
|
|
|
|
- `showvbanchat`: boolean
|
|
- `lock`: boolean
|
|
|
|
example:
|
|
|
|
```python
|
|
vban.command.restart()
|
|
vban.command.showvbanchat = true
|
|
```
|
|
|
|
### Multiple parameters
|
|
|
|
- `apply`
|
|
Set many strip/bus parameters at once, for example:
|
|
|
|
```python
|
|
vban.apply(
|
|
{
|
|
"strip-2": {"A1": True, "B1": True, "gain": -6.0},
|
|
"bus-2": {"mute": True},
|
|
}
|
|
)
|
|
```
|
|
|
|
Or for each class you may do:
|
|
|
|
```python
|
|
vban.strip[0].apply(mute: true, gain: 3.2, A1: true)
|
|
vban.vban.outstream[0].apply(on: true, name: 'streamname', bit: 24)
|
|
```
|
|
|
|
## `Base Module`
|
|
|
|
### VbanCmd class
|
|
|
|
#### `vban.pdirty`
|
|
|
|
True iff a parameter has been changed. Typically this is checked periodically to update states.
|
|
|
|
#### `vban.set_rt(id_, param, val)`
|
|
|
|
Sends a string request RT Packet where the command would take the form:
|
|
|
|
```python
|
|
f'{id_}.{param}={val}'
|
|
```
|
|
|
|
#### `vban.public_packet`
|
|
|
|
Returns a Voicemeeter rt data packet. Designed to be used internally by the interface but available for parsing through this read only property object. States may or may not be current, use the polling parameter pdirty to be sure.
|
|
|
|
### `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)
|
|
|
|
Then from tests directory:
|
|
|
|
`pytest -v`
|
|
|
|
## Resources
|
|
|
|
- [Voicemeeter VBAN TEXT](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf#page=19)
|
|
|
|
- [Voicemeeter RT Packet Service](https://vb-audio.com/Voicemeeter/VBANProtocol_Specifications.pdf#page=27)
|