Python interface for the VBAN RT Packet Service (Sendtext)
Project description
VBAN CMD
This python interface allows you to transmit Voicemeeter parameters over a network.
It may be used standalone or to extend the Voicemeeter Remote Python API
There is no support for audio transfer in this package, only parameters.
For an outline of past/future changes refer to: CHANGELOG
Tested against
- Basic 1.0.8.8
- Banana 2.0.6.8
- Potato 3.0.2.8
Requirements
- Voicemeeter
- Python 3.10 or greater
Installation
pip install vban-cmd
Use
Connection
Load VBAN connection info from toml config. A valid vban.toml
might look like this:
[connection]
ip = "gamepc.local"
port = 6980
streamname = "Command1"
It should be placed in <user home directory> / "Documents" / "Voicemeeter" / "configs"
Alternatively you may pass ip
, port
, streamname
as keyword arguments.
__main__.py
Simplest use case, use a context manager to request a VbanCmd class of a kind.
Login and logout are handled for you in this scenario.
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}) mute has been set to {self.vban.strip[0].mute}"
)
def other_things(self):
self.vban.bus[3].gain = -6.3
self.vban.bus[4].eq.on = True
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.on}",
)
print("\n".join(info))
def main():
KIND_ID = "banana"
with vban_cmd.api(
KIND_ID, ip="gamepc.local", port=6980, streamname="Command1"
) 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, "eq": {"on": True}},
"vban-in-0": {"on": True},
}
)
if __name__ == "__main__":
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
Strip
The following properties are available.
mono
: booleansolo
: booleanmute
: booleanlabel
: stringgain
: float, -60 to 12A1 - A5
,B1 - B3
: booleanlimit
: int, from -40 to 12
example:
vban.strip[3].gain = 3.7
print(vban.strip[0].label)
The following methods are available.
appgain(name, value)
: string, float, from 0.0 to 1.0
Set the gain in db by value for the app matching name.
appmute(name, value)
: string, bool
Set mute state as value for the app matching name.
example:
vban.strip[5].appmute("Spotify", True)
vban.strip[5].appgain("Spotify", 0.5)
Strip.Comp
The following properties are available.
knob
: float, from 0.0 to 10.0gainin
: float, from -24.0 to 24.0ratio
: float, from 1.0 to 8.0threshold
: float, from -40.0 to -3.0attack
: float, from 0.0 to 200.0release
: float, from 0.0 to 5000.0knee
: float, from 0.0 to 1.0gainout
: float, from -24.0 to 24.0makeup
: boolean
example:
print(vban.strip[4].comp.knob)
Strip Comp properties are defined as write only.
knob
defined for all versions, all other parameters potato only.
Strip.Gate
The following properties are available.
knob
: float, from 0.0 to 10.0threshold
: float, from -60.0 to -10.0damping
: float, from -60.0 to -10.0bpsidechain
: int, from 100 to 4000attack
: float, from 0.0 to 1000.0hold
: float, from 0.0 to 5000.0release
: float, from 0.0 to 5000.0
example:
vban.strip[2].gate.attack = 300.8
Strip Gate properties are defined as write only, potato version only.
knob
defined for all versions, all other parameters potato only.
Strip.Denoiser
The following properties are available.
knob
: float, from 0.0 to 10.0
strip.denoiser properties are defined as write only, potato version only.
Strip.EQ
The following properties are available.
on
: booleanab
: boolean
Strip EQ properties are defined as write only, potato version only.
Gainlayers
gain
: float, from -60.0 to 12.0
example:
vban.strip[3].gainlayer[3].gain = 3.7
Gainlayers are defined for potato version only.
Levels
The following properties are available.
prefader
example:
print(vban.strip[3].levels.prefader)
Level properties will return -200.0 if no audio detected.
Bus
The following properties are available.
mono
: booleanmute
: booleanlabel
: stringgain
: float, -60 to 12
example:
print(vban.bus[0].label)
Bus.EQ
The following properties are available.
on
: booleanab
: boolean
vban.bus[4].eq.on = true
Modes
The following properties are available.
normal
: booleanamix
: booleanbmix
: booleancomposite
: booleantvmix
: booleanupmix21
: booleanupmix41
: booleanupmix61
: booleancenteronly
: booleanlfeonly
: booleanrearonly
: boolean
The following methods are available.
get()
: Returns the current bus mode
example:
vban.bus[4].mode.amix = True
print(vban.bus[2].mode.get())
Levels
The following properties are available.
all
example:
print(vban.bus[0].levels.all)
levels.all
will return -200.0 if no audio detected.
Strip | Bus
The following methods are available.
fadeto(amount, time)
: float, intfadeby(amount, time)
: float, int
Modify gain to or by the selected amount in db over a time interval in ms.
example:
vban.strip[0].fadeto(-10.3, 1000)
vban.bus[3].fadeby(-5.6, 500)
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 frontshutdown()
: Shuts down the GUIrestart()
: Restart the audio enginereset()
: Applies thereset
config. (phys strip B1, virt strip A1, gains, comp, gate 0.0, mute, mono, solo, eq false)
The following properties are write only and accept boolean values.
showvbanchat
: booleanlock
: boolean
example:
vban.command.restart()
vban.command.showvbanchat = true
Multiple parameters
apply
Set many strip/bus parameters at once, for example:
vban.apply(
{
"strip-0": {"A1": True, "B1": True, "gain": -6.0},
"bus-1": {"mute": True, "mode": "composite"},
"bus-2": {"eq": {"on": True}},
"vban-in-0": {"on": True},
}
)
Or for each class you may do:
vban.strip[0].apply({"mute": True, "gain": 3.2, "A1": True})
vban.vban.outstream[0].apply({"on": True, "name": "streamname", "bit": 24})
Config Files
vban.apply_config(<configname>)
You may load config files in TOML format. Three example configs have been included with the package. Remember to save current settings before loading a user config. To load one you may do:
import vban_cmd
with vban_cmd.api('banana') as vban:
vban.apply_config('example')
will load a config file at configs/banana/example.toml for Voicemeeter Banana.
Your configs may be located in one of the following paths:
- <current working directory> / "configs" / kind_id
- <user home directory> / ".config" / "vban-cmd" / kind_id
- <user home directory> / "Documents" / "Voicemeeter" / "configs" / kind_id
If a config with the same name is located in multiple locations, only the first one found is loaded into memory, in the above order.
config extends
You may also load a config that extends another config with overrides or additional parameters.
You just need to define a key extends
in the config TOML, that names the config to be extended.
Three example 'extender' configs are included with the repo. You may load them with:
import voicemeeterlib
with voicemeeterlib.api('banana') as vm:
vm.apply_config('extender')
Events
Level updates are considered high volume, by default they are NOT listened for. Use subs
keyword arg to initialize event updates.
example:
import vban_cmd
opts = {
"ip": "<ip address>",
"streamname": "Command1",
"port": 6980,
}
with vban_cmd.api('banana', ldirty=True, **opts) as vban:
...
vban.subject
Use the Subject class to register an app as event observer.
The following methods are available:
add
: registers an app as an event observerremove
: deregisters an app as an event observer
example:
# register an app to receive updates
class App():
def __init__(self, vban):
vban.subject.add(self)
...
vban.event
Use the event class to toggle updates as necessary.
The following properties are available:
pdirty
: booleanldirty
: boolean
example:
vban.event.ldirty = True
vban.event.pdirty = False
Or add, remove a list of events.
The following methods are available:
add()
remove()
get()
example:
vban.event.remove(["pdirty", "ldirty"])
# get a list of currently subscribed
print(vban.event.get())
VbanCmd class
vban_cmd.api(kind_id: str, **opts)
You may pass the following optional keyword arguments:
ip
: str, ip or hostname of remote machinestreamname
: str, name of the stream to connect to.port
: int=6980, vban udp port of remote machine.pdirty
: boolean=False, parameter updatesldirty
: boolean=False, level updatestimeout
: int=5, amount of time (seconds) to wait for an incoming RT data packet (parameter states).outbound
: boolean=False, setTrue
if you are only interested in sending commands. (no rt packets will be received)
vban.pdirty
True iff a parameter has been changed.
vban.ldirty
True iff a level value has been changed.
vban.sendtext(script)
Sends a script block as a string request, for example:
vban.sendtext("Strip[0].Mute=1;Bus[0].Mono=1")
Errors
errors.VBANCMDError
: Base VBANCMD Exception class.errors.VBANCMDConnectionError
: Exception raised when connection/timeout errors occur.
Logging
It's possible to see the messages sent by the interface's setters and getters, may be useful for debugging.
example:
import vban_cmd
logging.basicConfig(level=logging.DEBUG)
opts = {"ip": "ip.local", "port": 6980, "streamname": "Command1"}
with vban_cmd.api('banana', **opts) as vban:
...
Tests
First make sure you installed the development dependencies
Then from tests directory:
pytest -v
Resources
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file vban_cmd-2.4.12.tar.gz
.
File metadata
- Download URL: vban_cmd-2.4.12.tar.gz
- Upload date:
- Size: 27.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.5.1 CPython/3.11.3 Windows/10
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3bc1b0ff584d1c3e611d9f0c29d4a8a1a017ebcb891bf0c8ee458a95e711ec06 |
|
MD5 | e0e036718bbe733f3f2e926f54852026 |
|
BLAKE2b-256 | a9829edeaa7d0598070ab195f6f6c0ee07027f9d7b67fe4202b8a417f67746c7 |
File details
Details for the file vban_cmd-2.4.12-py3-none-any.whl
.
File metadata
- Download URL: vban_cmd-2.4.12-py3-none-any.whl
- Upload date:
- Size: 29.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.5.1 CPython/3.11.3 Windows/10
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 418f97a22b474f97e985149eedcd66756e2a192c92225cdf5c37640f235e46e8 |
|
MD5 | 4773a48cd76ebdb3db6bb39e724b9b49 |
|
BLAKE2b-256 | 468efe3fd60a67566df034449e5f29ec611a1f666265ced63e3d1d80567915e1 |