A fast terminal image and video viewer built with Rust and the Kitty graphics protocol. Browse thousands of images in a thumbnail gallery, search by filename, and view fullscreen — all without leaving the terminal. Works great over SSH.
Features
- Thumbnail gallery — grid of image thumbnails with keyboard navigation, automatic layout based on terminal size
- Fullscreen viewer — full-resolution image display with instant transitions via prefetch cache
- Fuzzy search — type
/to filter filenames with nucleo-matcher - Video playback — MP4, MOV, MKV, AVI, WebM at 10fps via PNG-encoded frames (optional, requires ffmpeg)
- Five themes — tokyonight (default), dark, light, catppuccin, nord
- Fast JPEG decode — turbojpeg with downsampled scaling skips up to 93% of DCT work for large images
- SSH-friendly — all rendering uses PNG encoding (~5x less data than raw RGBA)
How It Works
The viewer uses a two-phase rendering approach. Ratatui draws the UI chrome (borders, status bars, search box), then Kitty graphics escape sequences transmit actual image data to the terminal. These are separate concerns — the UI is always fast, and image I/O only happens when something changes.
Five background pipelines run concurrently: directory scanning, fuzzy search filtering, thumbnail decoding, fullscreen image decoding, and neighbor prefetching. All communicate via channels and are polled each frame. A generation counter on thumbnails prevents stale decodes from overwriting fresh ones after a resize.
The prefetcher caches raw decoded images (not resized) for the ±3 neighbors around the current image. SIMD resize via fast_image_resize takes ~5ms, so it happens lazily when the image is actually displayed. This makes fullscreen transitions near-instant for cached images.
Video playback spawns a dedicated decode thread per video. ffmpeg’s swscale handles both pixel format conversion (YUV to RGBA) and resize in a single pass. Frames flow through a bounded channel and display at 10fps max. A fixed Kitty image ID ensures atomic frame replacement — no flicker from delete-then-draw.
Key Bindings
| Key | Action |
|---|---|
h j k l | Navigate gallery grid |
Enter | Open fullscreen / play video |
← → | Previous / next in fullscreen |
Space | Pause / resume video |
/ | Search filenames |
g / G | Jump to first / last |
Ctrl-b / Ctrl-f | Page up / down |
Esc | Back to gallery |
? | Help |
q | Quit |
Usage
1rview # current directory
2rview ~/photos/ # specific directory
3rview image.png # single image
4rview -t catppuccin ~/photos/ # choose theme
Requirements
- A terminal with Kitty graphics protocol support (Kitty, WezTerm, or Ghostty)
- For video: system ffmpeg libraries (7+), build with
--features video