README.md

✨ STIV - Simple Terminal Image Viewer ✨

A minimal & fast terminal image viewer written in Rust with sxiv-like keybindings

Features • Requirements • Installation • Usage • Keybindings • Configuration

📽️ Demo

🚀 Features

Feature	Description
⚡ Fast	Zlib compression, prefetch, and render cache for instant navigation
⌨️ Keyboard-driven	sxiv/vim-like keybindings with count support
📋 Clipboard	Copy path (OSC 52, works over SSH) or image to clipboard (local/X11 only)
🔄 Flexible	Fit/Normal display modes, works over SSH with Tmux
🖼️ KGP	Kitty Graphics Protocol for high-quality image rendering
🗂️ Tile Mode	Grid view with thumbnail navigation

🖼️ View Modes

Normal Mode Original size (shrink-only)	Fit Mode Scale to fill viewport	Tile Mode Grid thumbnail view

📋 Requirements

🖥️ Supported Terminals

STIV uses Kitty Graphics Protocol with Unicode Placeholders for image rendering.

Terminal	Status
Ghostty	✅ Tested
Kitty	✅ Supported
Other terminals with KGP + Unicode Placeholder support	✅ Supported

💡 tmux: Works with tmux. Passthrough is enabled automatically.

🔧 Building from source: Rust 1.75+ required.

📦 Installation

📥 From Release

Download the latest binary from Releases:

🍎 macOS (Apple Silicon)

curl -L https://github.com/kan-bayashi/stiv/releases/latest/download/stiv-aarch64-apple-darwin.tar.gz | tar xz
sudo mv stiv /usr/local/bin/

🐧 Linux (x86_64)

curl -L https://github.com/kan-bayashi/stiv/releases/latest/download/stiv-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv stiv /usr/local/bin/

🔨 From Source

cargo install --path .

🎯 Usage

stiv image.png           # Single image
stiv ~/photos/           # Directory
stiv *.png               # Glob pattern
stiv ~/photos/*.jpg      # Combined

⌨️ Keybindings

Key	Action	Description
j / Space / l	➡️ Next	Next image / move cursor down-right
k / Backspace / h	⬅️ Previous	Previous image / move cursor up-left
g	⏮️ First	Jump to first image
G	⏭️ Last	Jump to last image
f	🔄 Toggle	Toggle fit mode
t	🗂️ Tile	Toggle tile/single view
Enter	✅ Select	Select tile (Tile mode)
H/J/K/L	📄 Page	Page navigation (Tile mode)
r	🔃 Reload	Reload and clear cache
y	📋 Copy Path	Copy path to clipboard (OSC 52)
Y	🖼️ Copy Image	Copy image to clipboard (Local or X11)
q	🚪 Quit	Exit the viewer

💡 Pro tip: Vim-like counts are supported (e.g. 5j, 10G)

⚙️ Configuration

Settings can be configured via config file or environment variables.

📌 Priority: Environment variables > Config file > Defaults

📝 Config File

Create ~/.config/stiv/config.toml:

nav_latch_ms = 150
render_cache_size = 100
prefetch_count = 5
prefetch_threads = 2
compress_level = 6
cell_aspect_ratio = 2.0
resize_filter = "triangle"
tile_filter = "nearest"
tile_threads = 4

📊 Options

Config Key	Env	Default	Description
nav_latch_ms	STIV_NAV_LATCH_MS	150	Navigation latch (ms)
render_cache_size	STIV_RENDER_CACHE_SIZE	100	Render cache entries
prefetch_count	STIV_PREFETCH_COUNT	5	Prefetch count
prefetch_threads	STIV_PREFETCH_THREADS	2	Prefetch thread count (1-8)
compress_level	STIV_COMPRESS_LEVEL	6	Zlib compression (0-9)
kgp_no_compress	STIV_KGP_NO_COMPRESS	false	Disable compression
tmux_kitty_max_pixels	STIV_TMUX_KITTY_MAX_PIXELS	1500000	Max pixels (tmux+kitty)
force_alt_screen	STIV_FORCE_ALT_SCREEN	false	Force alt screen
no_alt_screen	STIV_NO_ALT_SCREEN	false	Disable alt screen
debug	STIV_DEBUG	false	Debug mode
trace_worker	STIV_TRACE_WORKER	false	Worker tracing
cell_aspect_ratio	STIV_CELL_ASPECT_RATIO	2.0	Cell aspect ratio (tile grid)
resize_filter	STIV_RESIZE_FILTER	triangle	Resize filter for single mode (nearest, triangle, lanczos3)
tile_filter	STIV_TILE_FILTER	nearest	Resize filter for tile mode (fastest for thumbnails)
tile_threads	STIV_TILE_THREADS	4	Tile processing thread count (1-8)

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

📚 References

• 🦀 yazi - Kitty Graphics Protocol implementation reference
• 📖 Kitty Graphics Protocol

📄 License

MIT License - Feel free to use, modify, and distribute! 🎉