Termvas

A terminal display backend for Ruby graphics.

Features · Installation · Quick Start · Terminal Notes

Termvas presents RGBA frames in terminals through half blocks, Kitty, iTerm2, or Sixel output. It also parses keyboard and mouse input for interactive applications.

• Automatic protocol detection with a manual override.
• Half-block output that works in ordinary ANSI terminals.
• Kitty, iTerm2, and Sixel image protocols.
• Image viewing and frame-sequence playback commands.
• Split-safe CSI, keyboard, wheel, and SGR mouse input parsing.
• Nearest-neighbor fitting for frames larger than the terminal.
• Idempotent alternate-screen and cursor restoration.

Add Termvas to your Gemfile:

gem "termvas"

# For Termvas::Backend and the `termvas view` / `play` commands:
gem "rbgl"
gem "tessel", ">= 0.2.0"

Then run:

bundle install

Or install the released gem:

gem install termvas

• Ruby 3.1 or newer.
• Half-block output works in ANSI terminals; Kitty, iTerm2, and Sixel output require matching terminal support.
• require "termvas" and termvas doctor need no extra gems. The RBGL backend needs rbgl; view / play, iTerm2 output, and median-cut Sixel quantization also need tessel.

Inspect the current terminal and display an image:

termvas doctor
termvas view image.png
termvas play frames/*.png --fps 10

Use the backend from Ruby:

require "termvas/rbgl"

backend = Termvas::Backend.new(320, 180, protocol: :blocks)
backend.set_pixels(rgba_bytes, 320, 180)
backend.close

The backend expects top-down RGBA8 bytes. Set TERMVAS_PROTOCOL to force a protocol. For Sixel output, pass quantize: :median_cut to the backend to use Tessel's shared quantizer; the default uses the fixed palette.

The encoders, protocol detection, input parser, and terminal sizing utilities load with require "termvas" alone. The optional RBGL backend is available from require "termvas/rbgl".

Termvas::Terminal#size returns [columns, rows]. #cell_size returns estimated pixel dimensions as [width, height] (8 × 16 by default). Set TERMVAS_CELL_WIDTH and TERMVAS_CELL_HEIGHT to tune the estimate; sizing does not query the terminal.

fit: :contain is the default and reduces oversized frames to the terminal cell area. Use fit: :none to keep the source size.

Inside tmux, Kitty and Sixel output uses DCS passthrough and requires allow-passthrough on in tmux.

Remote environment variables may not identify the local terminal. Select a protocol supported by that terminal explicitly, and lower the frame rate on slow links:

termvas play frames/*.png --protocol blocks --fps 5

For the Ruby backend, set protocol: :blocks and a lower max_fps value.

bundle install
bundle exec rake verify

See docs/keys.md for the input event mapping.

Bug reports and pull requests are welcome at rbgfx/termvas.

MIT