image_to_console

A high-performance terminal image viewer written in Rust.

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

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	ez-ffmpeg, 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	✓

Installation

Download from Release

Visit the GitHub Release page
Download the pre-compiled binary for your operating system
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

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

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

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)
reqwest	0.12.9	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)
ez-ffmpeg	0.5.3	MIT	Video processing (optional)
video-rs	0.10.3	MIT	Video processing (optional)
ndarray	0.16.1	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.

Name		Name	Last commit message	Last commit date
Latest commit History 249 Commits
.github/workflows		.github/workflows
build-options		build-options
image-to-console-colored		image-to-console-colored
image-to-console-core-python		image-to-console-core-python
image-to-console-core		image-to-console-core
image-to-console-renderer		image-to-console-renderer
image-to-console		image-to-console
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
README_zh-CN.md		README_zh-CN.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

image_to_console

Features

Supported Protocols

Features

Installation

Download from Release

Build from Source

Usage

Basic Usage

Command Line Options

File Subcommand Options

Directory Subcommand Options

GIF Subcommand Options

Video Subcommand Options

Display Mode Description

Color Modes

Grayscale Modes

Supported Image Formats

Dependencies

License

About

Uh oh!

Releases 16

Packages

Languages

License

yyxxryrx/image_to_console

Folders and files

Latest commit

History

Repository files navigation

image_to_console

Features

Supported Protocols

Features

Installation

Download from Release

Build from Source

Usage

Basic Usage

Command Line Options

File Subcommand Options

Directory Subcommand Options

GIF Subcommand Options

Video Subcommand Options

Display Mode Description

Color Modes

Grayscale Modes

Supported Image Formats

Dependencies

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 16

Packages 0

Languages

Packages