Python interface for the VBAN RT Packet Service (Sendtext)
Go to file
onyx-and-iris 8436634371 bit shift bus modes.
make modelist a BusMixin attr

remove vban.public_packet from README. It should be used only internally.

patch bump
2024-07-05 17:43:28 +01:00
configs Adds ability to extend one config with another 2023-07-11 20:27:52 +01:00
examples add double click event for slider 2023-08-04 21:14:33 +01:00
tests fixes error with escape character in regex 2023-08-13 18:16:49 +01:00
vban_cmd bit shift bus modes. 2024-07-05 17:43:28 +01:00
__main__.py check vban direction 2023-08-10 21:24:59 +01:00
.gitattributes Initial commit 2022-02-25 14:35:32 +00:00
.gitignore .python-version added to .gitignore 2023-06-30 17:56:54 +01:00
CHANGELOG.md 2.4.9 section added to CHANGELOG 2023-08-13 18:20:28 +01:00
LICENSE Create LICENSE 2022-03-09 06:29:59 +00:00
poetry.lock Bump black from 22.8.0 to 24.3.0 2024-04-05 02:36:56 +00:00
pyproject.toml bit shift bus modes. 2024-07-05 17:43:28 +01:00
README.md bit shift bus modes. 2024-07-05 17:43:28 +01:00
scripts.py add poetry test scripts for each kind 2023-08-10 19:13:34 +01:00

PyPI version License: MIT Poetry Code style: black Imports: isort Tests Status Tests Status Tests Status

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

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: boolean
  • solo: boolean
  • mute: boolean
  • label: string
  • gain: float, -60 to 12
  • A1 - A5, B1 - B3: boolean
  • limit: 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.0
  • gainin: float, from -24.0 to 24.0
  • ratio: float, from 1.0 to 8.0
  • threshold: float, from -40.0 to -3.0
  • attack: float, from 0.0 to 200.0
  • release: float, from 0.0 to 5000.0
  • knee: float, from 0.0 to 1.0
  • gainout: float, from -24.0 to 24.0
  • makeup: 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.0
  • threshold: float, from -60.0 to -10.0
  • damping: float, from -60.0 to -10.0
  • bpsidechain: int, from 100 to 4000
  • attack: float, from 0.0 to 1000.0
  • hold: float, from 0.0 to 5000.0
  • release: 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: boolean
  • ab: 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: boolean
  • mute: boolean
  • label: string
  • gain: float, -60 to 12

example:

print(vban.bus[0].label)
Bus.EQ

The following properties are available.

  • on: boolean
  • ab: boolean
vban.bus[4].eq.on = true
Modes

The following properties are available.

  • normal: boolean
  • amix: boolean
  • bmix: boolean
  • composite: boolean
  • tvmix: boolean
  • upmix21: boolean
  • upmix41: boolean
  • upmix61: boolean
  • centeronly: boolean
  • lfeonly: boolean
  • rearonly: 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, int
  • fadeby(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 front
  • shutdown() : Shuts down the GUI
  • restart() : Restart the audio engine
  • reset(): Applies the reset 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: boolean
  • lock: 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 observer
  • remove: 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: boolean
  • ldirty: 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 machine
  • streamname: str, name of the stream to connect to.
  • port: int=6980, vban udp port of remote machine.
  • pdirty: boolean=False, parameter updates
  • ldirty: boolean=False, level updates
  • timeout: int=5, amount of time (seconds) to wait for an incoming RT data packet (parameter states).
  • outbound: boolean=False, set True 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