Vaux CLI

A terminal client for Vaux listening rooms. Listen to YouTube audio in sync with friends directly from your terminal.

Built with Textual and powered by mpv.

Features

• Synchronized playback — everyone hears the same timestamp
• Shared queue — search YouTube and add tracks from the terminal
• Live voting — vote tracks up or down to re-sort the queue
• Live chat — talk with friends alongside the music
• Private rooms — invite-only with end-to-end encrypted chat (XSalsa20-Poly1305, Argon2id key derivation). Room burns when the host leaves.
• Host controls — play, pause, skip, remove tracks, transfer host
• No YouTube API key — search and stream URLs come from the Vaux server (with local yt-dlp fallback)
• Faster track starts — background stream preloading + cache-aware resolution paths

Requirements

• mpv — plays audio. On Windows, the CLI can download a portable build on first run. On Linux/macOS, install via your package manager (apt install mpv, brew install mpv, etc.).
• Node.js (recommended) — modern yt-dlp needs a JS runtime for YouTube extraction. Node is auto-detected when using the local yt-dlp fallback. The hosted server already runs Node.
• yt-dlp — included as a package dependency; keep it updated with pip install -U yt-dlp.

Installation

pipx install vaux-cli

Or:

pip install vaux-cli

Upgrade to latest release

pip install --upgrade vaux-cli

Usage

Launch the interactive lobby:

vaux

Join a public room directly:

vaux <room-id> -u <your-name>

Join a private room from an invite link or 22-character code:

vaux "https://vaux.app/#<22-char-code>" -u <your-name>
vaux <22-char-code> -u <your-name>

Or paste the invite from the lobby's 🔒 private → paste invite tab.

Point at a local server when developing:

vaux --server http://localhost:4000
vaux --server http://localhost:4000 my-room -u yourname

Keyboard shortcuts

In a room

Type /host <username> in chat to transfer host to another listener.

Private rooms

• Chat messages and member names are end-to-end encrypted with a key derived locally from the invite code (Argon2id). The server only sees ciphertext.
• The room ID, queue, and playback events are NOT encrypted — only chat. Don't share private-room codes through untrusted channels.
• The invite code stays in memory only. Closing the CLI loses it. Share before joining.
• When the host quits, the room is destroyed immediately. Other members are disconnected.
• Wrong codes lock the room for 60 s after 10 failed attempts.

Lobby

Modal overlays

Streaming notes

Audio stream URLs are resolved through a low-latency pipeline:

• Server attempts yt-dlp extraction with client-chain fallbacks.
• Server caches stream URLs for a short TTL and pre-resolves on queue:add.
• CLI races server and local yt-dlp in parallel, then uses the first success.
• CLI preloads upcoming tracks and keeps an in-memory per-session stream cache.

During playback startup, the system log shows:

• ⚡ stream source: cache (local)
• ⚡ stream source: cache (server)
• ⚡ stream source: server live
• ⚡ stream source: local yt-dlp

Override VAUX_API_KEY only if the server uses a custom API_KEY. If playback fails, update yt-dlp and keep Node.js on PATH:

pip install -U yt-dlp
yt-dlp --js-runtimes node --remote-components ejs:github "https://youtu.be/VIDEO_ID"

If that command works locally, the CLI fallback should work too.

Reporting bugs

Found something broken? You have three ways to report it:

• Inside the app — press Ctrl+B from the lobby or any room. An overlay opens with two choices:
  • Google Form — anonymous, no GitHub account needed.
  • GitHub Issues — opens a pre-filled issue with your vaux-cli version, Python version, and OS already in the body.
• From the shell — vaux bug opens the GitHub Issues page in your browser with the same pre-filled template.
• Attaching a screenshot — press Ctrl+P inside vaux to open Textual's command palette, then choose Save screenshot. vaux writes an SVG of the current terminal screen to your working directory; attach it to the form or drop it into the GitHub issue. Close the bug-report overlay before capturing so the screenshot shows the underlying screen.

Development

cd cli
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # macOS/Linux
pip install -e .
python main.py --server http://localhost:4000

Links

• Repository: github.com/itsvee0120/vaux
• PyPI: pypi.org/project/vaux-cli
• Issues: github.com/itsvee0120/vaux/issues

Why this project

I'm too lazy to switch tabs and need my full screen while coding ... That's it, that's why. 😺

Okay, not entirely.

This project was created because I wanted to learn how to use Socket.IO across a CLI application and a web app. It started as a fun hobby project and a learning exercise, and I decided to publish it so others can play around with it, learn from it, or build their own ideas based on what I've made.

Disclaimer: This is a personal hobby project created for learning and experimentation. It is free, open source, non-commercial, and released under the MIT License. No donations, sponsorships, subscriptions, or other forms of compensation are requested or expected. If you find it useful, that's more than enough.

Author

Violet Nguyen — nviolet0120@gmail.com

License

MIT — see LICENSE.