vplay

vplay is a macOS terminal video player for controlling local videos, playlists, clips, downloads, and multiple displays from one TUI.

Use it as a multi-monitor mpv controller, a terminal playlist manager, or a lightweight way to play different videos on different screens at the same time.

Website · Latest release · Discussions

brew tap rztrace/vplay https://github.com/rztrace/vplay
brew install vplay
vplay

Features

• Browse local video collections from a terminal UI.
• Queue videos into playlists and control playback from one interface.
• Save display names and replay selected portions of files.
• Route playback to available macOS displays.
• Play multiple videos or playlists on different screens at the same time.
• Control per-screen playback, volume, mute, loop mode, play-next behavior, and position.
• Extend behavior with system modules or user modules.
• Run optional downloads through yt-dlp.

Good Fit

• You use a Mac with more than one display.
• You want mpv control without switching out of the terminal.
• You need playlists, renamed files, clipped playback portions, or download queues.
• You want a scriptable TUI that can grow through modules instead of a full media-center app.

Requirements

• macOS
• mpv
• yt-dlp for download features
• Python 3.9+ only when installing from source

Install With Homebrew

brew tap rztrace/vplay https://github.com/rztrace/vplay
brew install vplay

Homebrew installs are managed by Homebrew. Update with:

brew update && brew upgrade vplay

Portable macOS Binary

Download the latest vplay-macos-arm64.tar.gz from:

https://github.com/rztrace/vplay/releases/latest

Then unpack and run it:

tar -xzf vplay-macos-arm64.tar.gz
chmod +x vplay
./vplay

The archive unpacks vplay plus its _internal runtime folder. Keep them together. The portable binary uses the folder it is stored in as its default video folder, so it can be unpacked into a media directory and run without setup.

Install From Source

git clone https://github.com/rztrace/vplay.git
cd vplay
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/vplay

Optional shell setup:

# zsh or bash
export PATH="$PWD/.venv/bin:$PATH"
vplay

# fish
fish_add_path "$PWD/.venv/bin"
vplay

You can also source the fish helper if you use fish:

source fish/vplay.fish
vplay

Video Folder

Source and Homebrew installs default to ~/movs. If that folder does not exist on first run, vplay asks whether to create it, use another folder, or switch to the terminal working folder.

The folder can later be changed from Settings. Source and Homebrew installs can also opt into using the current terminal folder at launch; portable builds use the binary folder by default.

Modules

Modules live in vplay/modules.

• vplay/modules/system contains modules that integrate with core playback, settings, layout, or mpv behavior.
• vplay/modules/user is for lightweight add-ons that can be added as simple Python files.

Add-ons can provide panes, settings, or behavior enhancements. See docs/modules.md for the module shape and keybinding conventions.