Awesome
<div align="center"> <h1><b>TermVisage</b></h1> <p> <img src="https://raw.githubusercontent.com/AnonymouX47/termvisage/23b8b4612e0ac4a167fa92630be63766f7f56e29/docs/source/resources/logo.png" height="200"> </p> <p> <b>Browse and view images in the terminal</b> </p> <p> 📖 <a href='https://termvisage.readthedocs.io'>Manual</a> ║ 🖼 <a href='https://termvisage.readthedocs.io/en/latest/gallery.html'>Gallery</a> </p> <p> <a href='https://pypi.org/project/termvisage/'> <img src='https://img.shields.io/pypi/v/termvisage.svg'/> </a> <a href='https://pepy.tech/project/termvisage'> <img src="https://pepy.tech/badge/termvisage/month"> </a> <a href='https://pypi.org/project/termvisage/'> <img src='https://img.shields.io/pypi/pyversions/termvisage.svg'/> </a> <a href='https://github.com/psf/black'> <img src='https://img.shields.io/badge/code%20style-black-000000.svg'/> </a> <a href='https://termvisage.readthedocs.io/en/latest/?badge=latest'> <img src='https://readthedocs.org/projects/termvisage/badge/?version=latest' alt='Documentation Status'/> </a> <img src="https://img.shields.io/github/last-commit/AnonymouX47/termvisage"/> <a href="https://twitter.com/intent/tweet?text=Browse%20and%20view%20images%20in%20the%20terminal&url=https://github.com/AnonymouX47/termvisage&hashtags=developers,images,terminal,python"> <img src="https://img.shields.io/twitter/url/http/shields.io.svg?style=social"/> </a> </p> </div>Contents
- Installation
- Features
- Demo
- Quick Start
- Usage
- Contribution
- Planned Features
- Known Issues
- FAQs
- Credits
- Sponsor This Project
Installation
Requirements
-
Operating System: Unix / Linux / Mac OS X / Windows (limited support, see the FAQs)
-
Python >= 3.8
-
A terminal emulator with any of the following:
- support for the Kitty graphics protocol
- support for the iTerm2 inline image protocol
- Unicode and direct-color (truecolor) support
Plans to support a wider variety of terminal emulators are in motion (see the library's planned features).
Steps
The latest version can be installed from PyPI using pipx
with:
pipx install termvisage
and upgraded with:
pipx upgrade termvisage
NOTE: pip
can also be used but pipx
is recommended.
See the installation docs for info about optional features and more.
Features
- Almost everything the term-image library supports
- Display individual images
- Browse multiple images and directories (recursively)
- Efficient and configurable thumbnailing
- Adjustable image grids
- Context-based controls
- Customizable controls and configuration options
- Smooth and performant experience
- Shell completion for command-line arguments
- and more... 😁
Demo
Multiple Render Styles
block | iterm2 | kitty |
---|---|---|
High-Resolution Images
Video Demo
Gallery
Check out the Gallery for more.
Quick Start
With a file path:
termvisage path/to/image.png
With a URL:
termvisage https://www.example.com/image.png
With a directory, recursively (not currently supported on Windows):
termvisage -r path/to/dir/
If a single source is given and it's animated (GIF, APNG, Animated WebP), the animation is infinitely looped by default and can be stopped with Ctrl-C
(SIGINT
).
By default, if multiple sources or at least one directory source is given, the TUI (Terminal User Interface) is launched to navigate through the images and/or directories.
Usage
CLI (Command-Line Interface)
Run termvisage --help
to see the basic help message or termvisage --long-help
for the full help message.
See the CLI manual.
TUI (Terminal User Interface)
The controls are context-based and always displayed at the bottom of the screen.
Pressing the F1
key (in most contexts) brings up a help menu describing the available controls (called actions) in that context.
The TUI can be configured using a config file. See the Configuration section of the docs.
Here is a config file with Vim-style key-bindings (majorly navigation).
See the TUI manual.
Contribution
If you've found any bug or want to suggest a new feature, please open a new issue with proper description, after browsing/searching through the existing issues and making sure you won't create a duplicate.
For code contributions, please read through the guidelines.
Also, check out the Planned Features section below. If you wish to work on any of the listed tasks, please click on the linked issue or go through the issues tab and join in on an ongoing discussion about the task or create a new issue if one hasn't been created yet, so that the implementation can be discussed.
Hint: You can filter issues by label or simply search using the task's name or description.
For anything other than the above (such as questions or anything that would fit under the term "discussion"), please open a new discussion instead.
Thanks! 💓
Planned Features
See here.
Known Issues
See here.
FAQs
See the FAQs section of the docs.
Credits
The following projects have been (and are still) crucial to the development of this project:
- term-image by @AnonymouX47
- Pillow by Fredrik Lundh, Jeffrey A. Clark (Alex) and contributors
- Urwid by Ian Ward et al
- argcomplete by Andrey Kislyuk
The logo was composed using resource(s) from the following source(s):
Thanks to @digitallyserviced for the project name and logo concept.
Sponsor This Project
<a href="https://www.buymeacoffee.com/anonymoux47" target="_blank"> <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" > </a>Any amount will go a long way in aiding the progress and development of this project. Thank you! 💓