vid

Play video in your terminal.

vid is a small video player for macOS and Linux. It renders real pixels with the kitty graphics protocol, plays audio in sync, seeks, and shows subtitles — inline in your shell's scrollback, so your prompt and history stay where they were. It works inside tmux.

Install

You need Ghostty or kitty, a C compiler, and ffmpeg's libraries.

macOS:

xcode-select --install
brew install ffmpeg

Debian or Ubuntu:

sudo apt install build-essential libasound2-dev \
    libavformat-dev libavcodec-dev libavutil-dev libswscale-dev libswresample-dev

Then:

make
./vid movie.mkv

Optionally:

make install PREFIX="$HOME/.local"

Usage

vid [options] <file>

Anything ffmpeg can open works, including URLs. Give it a directory instead of a file and it opens a list.

Option	Description
--fullscreen	Take over the screen instead of drawing inline
--scale <1-10>	Height of the inline block, in tenths of the terminal
--max-width <n>	Upper bound on the transmitted frame width in pixels
--no-audio	Disable audio
--volume <0-100>	Initial volume
--loop	Restart at the end instead of exiting
--sub <file>	Load subtitles from a file
--no-subs	Do not render subtitles
--test	Play a generated test pattern, no file needed
--stats	Show decode and transmission counters instead of the progress bar
--no-status	Start with the status line hidden
--mouse / --no-mouse	Take the pointer, or leave it alone
--tmux-keys	Take the keyboard past tmux (breaks its prefix)
--force	Skip terminal graphics detection

Keys

Key	Action
space / p	Pause
← / →	Seek ∓5s / ±5s
↓ / ↑	Seek ∓60s / ±60s
, / .	Previous / next frame (pauses first)
[ / ]	Shrink / grow the inline block
- / =	Volume down / up
m	Mute
s	Subtitles on/off
l	Loop on/off
F9	Toggle terminal scaling
b / F2	Show or hide the status line
F1	Toggle the statistics line
esc	Back to the list
q or Ctrl+C	Quit

Click anywhere on the progress bar to jump there, or press and drag to scrub.

Browsing

vid /some/directory opens a list of what it can play there. esc during playback returns to it, even when the file was named on the command line.

Key	Action
↑ / ↓	Move
PgUp / PgDn, Home / End	Move faster
enter or →	Play the file, or open the directory
← or backspace	Up a directory
esc or q	Quit

tmux

Enable passthrough once, or every graphics escape is swallowed:

tmux set -g allow-passthrough all      # add to ~/.tmux.conf to keep it

Expect a lower frame rate than a bare terminal — every frame is copied through tmux on its way out. The pointer and the keyboard are left to tmux by default, since taking either one takes it from the whole window; --mouse and --tmux-keys override that.

Notes

The block size, the volume and whether the status line is showing are remembered in ~/.config/vid/state.

vid picks the transmitted frame size from a bandwidth budget and then adapts it to what the terminal can actually take, so the picture settles after a second or two and stops moving. Growing the block with ] costs nothing on the wire — the terminal does the stretching.

NOTES.md has the longer version: sizing, the tmux placeholder scheme, audio sync and the rest.

Limitations

• Text subtitles only; no bitmap (DVD, Blu-ray PGS) tracks.
• No playlist: one file per invocation.
• Software decoding only. VideoToolbox is available but not used: at terminal resolutions the readback from GPU memory costs more than it saves.

License

MIT — see LICENSE.