pyVBAN

Python CLI for sending and receiving audio over a network using VBAN, VB-Audio's UDP audio protocol. Interoperates with Voicemeeter, VBAN Receptor, and other VBAN apps. Supports PCM 16-bit and Opus.

Features

• Send any input device, receive to any output device
• Opus codec option: ~1550 kbps raw PCM down to ~130 kbps, transparent for music, ~5 ms codec latency
• Silence gating: sender stops transmitting after 60 s of silence, resumes instantly on sound
• Interactive menu when run without arguments (direction + device picker)
• Device selection by index or name substring, defaults to system default
• Live stats line: bitrate, 0-100 volume level, lost frames
• Receiver auto-restarts on crash with leak-safe PortAudio and socket teardown
• Cross-platform audio via sounddevice (PortAudio)

Install

pip install -r requirements.txt
cp sample.env .env   # set SEND_IP to the receiving machine's address

Usage

python vban.py                          # interactive menu
python vban.py recv                     # play incoming stream on default output
python vban.py send                     # stream default input to SEND_IP
python vban.py send -d "CABLE Output" --opus -v

Flag	Description
-d	Device index or name substring (default: system default)
-v	Stats line every 2 s: 1548 kbps vol:57 lost:0
--opus	Send with Opus instead of raw PCM

Volume is average RMS mapped to a 0-100 dBFS scale (100 = full scale, 0 = below -60 dB). lost counts frame counter gaps on the receiver, i.e. packets dropped by the network.

Streaming system audio (Windows)

To send what you hear rather than a microphone, route audio through VB-Cable:

1. Set Windows default playback to CABLE Input
2. python vban.py send -d "CABLE Output"

Naming trap: the cable is named from its own perspective. Apps play into CABLE Input; you record from CABLE Output. Both ends should run at the same sample rate (16 bit, 48000 Hz), and the recording endpoint must not be muted.

As a library

from pyVBAN import VBAN_Recv, VBAN_Send

cl = VBAN_Recv("Stream1", 6980, outDeviceIndex=None, verbose=False)  # None = default output
cl = VBAN_Send("192.168.1.10", 6980, "Stream1", 48000, inDeviceIndex=None, verbose=False)
cl.use_opus_encoder()  # optional, sender only
cl.runforever()
cl.quit()  # releases PortAudio + socket

How it works

VBAN is stateless UDP: each packet carries a 28-byte header (sample rate, channels, format, stream name, frame counter) plus audio payload. The receiver binds port 6980, filters by stream name, and reconfigures its output stream when the incoming format changes. Opus packets use VBAN's user-defined codec slot (0xF1), decoded with PyOgg; the receiver falls back to PCM automatically per packet.

Protocol spec: vb-audio.com

Changes from upstream

• pyaudio replaced with sounddevice, leak-safe teardown on restart
• Opus send and receive support
• Silence gating and sent-only frame counting (no false loss reported during pauses)
• CLI with interactive menu, device-by-name, and periodic stats
• Upstream later rewrote as the pyvban PyPI package (new API, no Opus); this fork is independent of that rewrite

Credits

• TheStaticTurtle/pyVBAN: original Python VBAN implementation this fork extends

License

GPL-3.0, same as upstream.