Skip to content

yyxxryrx/image_to_console

BranchesTags

Repository files navigation

image_to_console

License: MIT Last Version Mirror

A high-performance terminal image viewer written in Rust.

English | 简体中文

Features

  • 🖼️ Multiple Sources: Load images from files, URLs, Base64 strings and standard input
  • 📁 Directory Processing: Batch process entire directories of image files
  • 🎨 True Color Support: Display colored images in supported terminals
  • ⚫ Grayscale Mode: Convert color images to grayscale character art
  • ⚫ Black Background: Black background display option in grayscale mode
  • ⚡ Parallel Processing: Fast conversion using Rayon library for parallel computation
  • 📏 Adaptive Sizing: Automatically scale images to fit terminal window
  • ⌨️ Interactive Pause: Optional pause after display for convenient viewing
  • 🖥️ Multiple Display Modes: Support for full-resolution (default) and half-resolution display modes
  • 🖥️ Multiple Terminal Protocol Support: Support for WezTerm, Kitty, iTerm2 and Sixel image protocols
  • 🎞️ GIF Animation Support: Play GIF animations in terminal
  • 🎥 Video Playback Support: Play video files in terminal (requires video_player feature and FFmpeg)
  • 🔊 Audio Support: Add audio tracks to GIF animations (requires audio_support feature)
  • 🗜️ Compression Support: Compress output in normal protocol mode
  • 📄 TOML Configuration Support: Run complex tasks via TOML configuration files (requires dot_file feature)

Supported Protocols

  • WezTerm
  • Kitty
  • iTerm2
  • Sixel

Features

Feature Dependencies Description Is Default
reqwest reqwest HTTP client library ✓
audio_support rodio Play audio support ✗
use_crossterm crossterm Cross-platform terminal library ✓
gif_player gif, crossbeam-channel Play GIF animations in terminal ✓
video_player ffmpeg-next, video-rs, crossbeam-channel, FFmpeg Play video files in terminal (requires video feature and FFmpeg) ✗
sixel_support quantette, nohash-hasher Display images using Sixel protocol ✓
dot_file toml, serde TOML configuration file support ✗

Installation

Download from Release

  1. Visit the GitHub Release page
  2. Download the pre-compiled binary for your operating system
  3. Extract and add the binary to your system PATH

Build from Source

git clone https://github.com/yyxxryrx/image_to_console.git
cd image_to_console

# Build basic version (without video support)
# No FFmpeg required for this version
cargo build --release

# Build version with video support
# FFmpeg libraries required for this version
cargo build --release --features video_player

The compiled binary will be located at target/release/image_to_console.

If you want to build with video support, you need to install FFmpeg libraries first:

  • Ubuntu/Debian: sudo apt-get install libavcodec-dev libavformat-dev libavutil-dev libavfilter-dev libavdevice-dev
  • macOS: brew install ffmpeg
  • Windows: Install FFmpeg and ensure DLL files are in your PATH

With Nix

git clone https://github.com/yyxxryrx/image_to_console.git
cd image_to_console

# Build basic version
nix build

# Build full version
nix build .#full

# Build lite version
nix build .#lite

The compiled binary will be located at result/bin/image_to_console

Usage

Basic Usage

# Load image from file
image_to_console file path/to/image.jpg

# Load all images from directory
image_to_console directory path/to/directory

# Load animation from GIF file
image_to_console gif path/to/animation.gif

# Load image from URL
image_to_console url https://example.com/image.png

# Load image from Base64 string
image_to_console base64 <base64-encoded-image-data>

# Load image from standard input bytes
cat image.jpg | image_to_console bytes

# Load video from file (requires video feature)
image_to_console video path/to/video.mp4

# Load and run from TOML configuration file (requires dot_file feature)
image_to_console dot-file config.toml

Command Line Options

# Show help information
image_to_console --help

# Center display image
image_to_console -c file image.jpg

# Pause and wait for user input after display
image_to_console --pause file image.jpg

# Show processing time
image_to_console -t file image.jpg

# Half resolution display
image_to_console --half-resolution file image.jpg

# Grayscale mode display
image_to_console --no-color file image.jpg

# Use black background in grayscale mode
image_to_console --no-color -b file image.jpg

# Disable width scaling
image_to_console --without-resize-width file image.jpg

# Disable height scaling
image_to_console --without-resize-height file image.jpg

# Save output to file
image_to_console -o output.txt file image.jpg

# Disable image printing (show info only)
image_to_console --disable-print file image.jpg

# Disable info display
image_to_console --disable-info file image.jpg

# Read all images at once in directory mode
image_to_console --read-all directory path/to/directory

# Display image using WezTerm image protocol
image_to_console --protocol wezterm file image.jpg

# Display image using Kitty image protocol
image_to_console --protocol kitty file image.jpg

# Display image using iTerm2 image protocol
image_to_console --protocol iterm2 file image.jpg

# Display image using Sixel protocol
image_to_console --protocol sixel file image.jpg

# Display image using Sixel protocol with custom max colors
image_to_console --protocol sixel --max-colors 128 file image.jpg

# Enable compression (only in normal protocol)
image_to_console --enable-compression file image.jpg

# Auto detect terminal protocol (default)
image_to_console --protocol auto file image.jpg

File Subcommand Options

# Hide filename display
image_to_console file --hide-filename image.jpg

# Show filename (default)
image_to_console file image.jpg

Directory Subcommand Options

# Process all images in directory
image_to_console directory path/to/directory

# Process all images in directory and read all at once
image_to_console --read-all directory path/to/directory

GIF Subcommand Options

requires gif_player feature

audio support requires audio_support feature

# Play GIF animation (default 10 FPS)
image_to_console gif animation.gif

# Play GIF animation with custom frame rate
image_to_console gif --fps 24 animation.gif

# Loop GIF animation
image_to_console gif --loop animation.gif

# Set frame rate and loop GIF animation
image_to_console gif --fps 30 --loop animation.gif

# Play GIF animation with audio (requires audio_support feature)
image_to_console gif --audio audio.mp3 animation.gif

Video Subcommand Options

requires video_player feature

# Play video file (requires video_player feature)
image_to_console video path/to/video.mp4

# Play video file with custom audio track (requires video_player feature)
image_to_console video --audio path/to/audio.mp3 path/to/video.mp4

Dot File Subcommand Options

Note: This feature requires dot_file feature.

Usage

Tips: schema command is not implementation

Usage: image_to_console.exe dot-file <COMMAND>

Commands:
  schema  taplo schema about
  run     run dot-file
  check   check dot-file
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Examples

# Check dot-file
image_to_console dot-file check path/to/config.toml

# Run with dot-file
image_to_console dot-file run path/to/config.toml

Example TOML configuration file:

# type is the name of each subcommand, e.g., file | url | bytes, etc
type = "file"
# input for each subcommand, leaving blank if type = "bytes"
input = "path/to/image.jpg"

# The following are optional
center = false
clear = false
pause = false
show-time = false
half-resolution = false
disable-print = false
disable-info = false
no-color = false
black-background = false
no-resize = false
protocol = "auto"
resize-mode = "auto"
enable-compression = false

# Sixel protocol specific options
max-colors = 256
disable-dither = false
color-space = "srgb"

# File specific options (optional)
[file]
hide_filename = false

# Directory specific options (optional)
[directory]
read_all = false

# GIF specific options (optional)
[gif]
fps = 24
loop-play = true
audio = "path/to/audio.mp3"

# Video specific options (optional)
[video]
flush-interval = "1s"
audio = "path/to/audio.mp3"

Display Mode Description

Color Modes

  • Full-resolution color mode (default): Display using upper/lower half-blocks, each character represents two pixels
  • Half-resolution color mode (--half-resolution): Display using background color blocks, each character represents one pixel
  • WezTerm mode (--protocol wezterm): Use WezTerm's inline image protocol to display original image directly
  • Kitty mode (--protocol kitty): Use Kitty's inline image protocol to display original image directly
  • iTerm2 mode (--protocol iterm2): Use iTerm2's inline image protocol to display original image directly
  • Sixel mode (--protocol sixel): Use Sixel protocol to display images in supported terminals
  • Auto-detect mode (--protocol auto): Automatically detect and use the best available terminal protocol (default)

Grayscale Modes

  • Grayscale mode (--no-color): Convert image to grayscale character art display
  • Use different Unicode characters (such as █, ▀, ▄, ., , etc.) to represent different grayscale levels
  • Black background (-b): Use black background to display image in grayscale mode
  • WezTerm grayscale mode (--protocol wezterm --no-color): Display grayscale image in WezTerm
  • Kitty grayscale mode (--protocol kitty --no-color): Display grayscale image in Kitty
  • iTerm2 grayscale mode (--protocol iterm2 --no-color): Display grayscale image in iTerm2
  • Auto-detect grayscale mode (--protocol auto --no-color): Automatically detect and use the best available terminal protocol in grayscale mode

Supported Image Formats

Supports most common image formats, including but not limited to:

  • JPEG
  • PNG
  • GIF
  • BMP
  • ICO
  • TIFF
  • WebP

Dependencies

Crate Version License Purpose
clap 4.5.20 MIT / Apache-2.0 Command line argument parsing
rayon 1.11.0 MIT / Apache-2.0 Data parallel computing
num_cpus 1.17.0 MIT Get logical CPU core count
image 0.25.4 MIT Image encoding/decoding and processing
base64 0.22.1 MIT / Apache-2.0 Base64 encoding/decoding
indicatif 0.17.8 MIT Terminal progress bars
terminal_size 0.4.0 MIT Detect terminal size
crossterm 0.29.0 MIT Terminal control and input (optional)
ureq 3.2.0 MIT / Apache-2.0 Blocking HTTP client (optional)
gif 0.13.3 MIT GIF animation decoding (optional)
crossbeam-channel 0.5.15 MIT / Apache-2.0 Cross-thread communication (optional)
rodio 0.21.1 MIT / Apache-2.0 Audio playback (optional)
ffmpeg-next 8.0.0 WTFPL Audio processing (optional)
video-rs 0.11.0 MIT Video processing (optional)
ndarray 0.17.2 MIT N-dimensional array (optional)
quantette 0.3.0 MIT Sixel image quantization (optional)
nohash-hasher 0.2.0 MIT Sixel Fast Hash (Optional)
pyo3 0.27.1 MIT / Apache-2.0 Python bindings (optional)

License

This project is licensed under the MIT License - see the LICENSE file for details.

About

High-performance Rust tool for rendering images in the terminal | 高性能的图像终端渲染工具

Topics

rust cli terminal video-player image-viewer multi-protocol gif-player

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 17

Release v0.2.0 Latest
Mar 22, 2026
+ 16 releases

Packages

 
 
 

Contributors

Languages