A fast, terminal-based image and experimental video player written in Rust that displays media with proper aspect ratios using Unicode half-block characters.
Example usage:
cargo run pic_milkmaid.jpgScreenshot:
Core Features Implemented:
- 🖼️ Image Display: JPEG, PNG, GIF (static + animated), BMP, TIFF support
- 🎞️ Animated GIFs: Smooth looping playback with ESC/q to exit
- 📹 Experimental Video Playback: MP4, MOV, AVI, MKV, WebM, M4V with adaptive FPS and controls
- 🎨 True Color: RGB color support with automatic terminal capability detection
- 📐 Perfect Aspect Ratios: Uses half-block characters (▄) for 2x vertical resolution
- ⚡ Fast Performance: Efficient scaling and rendering with intelligent frame dropping
- 🖥️ Cross-Platform: Works on Linux, macOS, and Windows terminals
git clone <repository-url>
cd implay
cargo build --release# Display static images
cargo run image.jpg
cargo run photo.png
# Display animated GIFs (loops continuously)
cargo run animation.gif # Press ESC or 'q' to exit
# Play videos (experimental)
cargo run video.mp4 # SPACE = pause/play, ESC/Q = quit
cargo run movie.mov
# Or after building
./target/release/implay image.jpg
./target/release/implay animation.gif
./target/release/implay video.mp4- SPACE: Pause/Play toggle
- ESC or Q: Quit video playback
- Progress bar: Shows elapsed/remaining time and percentage
implay --help # Show help
implay --version # Show versionImPlay uses Unicode half-block characters (▄) to achieve high-resolution terminal graphics:
- Each terminal character displays 2 pixels vertically
- Foreground color: Bottom pixel
- Background color: Top pixel
- 2x resolution: Doubles the effective terminal resolution
- Perfect aspect ratios: Accounts for terminal character dimensions
Square Image (100x100):
Terminal: 142x52 | Original: 100x100 | Resized: 100x100
Effective height: 104 | Scale X: 1.420 Y: 1.040 Final: 1.000
Rectangular Image (200x150):
Terminal: 142x52 | Original: 200x150 | Resized: 138x103
Effective height: 104 | Scale X: 0.710 Y: 0.693 Final: 0.693
- JPEG (.jpg, .jpeg)
- PNG (.png)
- GIF (.gif) - static and animated
- BMP (.bmp)
- TIFF (.tiff, .tif)
- MP4 (.mp4)
- MOV (.mov)
- AVI (.avi)
- MKV (.mkv)
- WebM (.webm)
- M4V (.m4v)
Dependencies:
image- Image format support and processingratatui- Terminal user interface frameworkcrossterm- Cross-platform terminal capabilitiesclap- Command line argument parsingffmpeg-next- Video decoding and processing
Performance:
- Automatic scaling to fit terminal dimensions
- Preserves aspect ratios using proper character dimensions
- Memory-efficient image processing
- Adaptive FPS adjustment based on terminal rendering speed
- Intelligent frame dropping for smooth video playback
- Clean exit without clearing terminal
src/
├── main.rs # CLI entry point
├── image_loader.rs # Image and video file handling
├── terminal.rs # Half-block rendering engine
├── video.rs # Video decoding and streaming
├── color.rs # Color quantization
└── lib.rs # Module exports
✅ Stages 1-3 Complete (95% Functionality):
- Basic image loading and display
- Half-block character rendering
- Perfect aspect ratio preservation
- Color support with terminal detection
- Cross-platform compatibility
- Experimental video playback with adaptive FPS
🔄 Future Stages:
- Advanced CLI options (fitting modes, color modes)
- Interactive controls and window resize handling
- Additional optimizations and formats
- Comprehensive test coverage
- Audio support for video playback
This project follows a staged development approach. See IMPLEMENTATION_PLAN.md for detailed roadmap and PRODUCT_SPECS.md for complete specifications.
MIT License - see LICENSE file for details.