dotz 0.1

Render images and video previews as Braille art in the terminal with color and animation support.

dotz

Render images and video previews as Braille art in the terminal with xterm-256 color and ncurses dim/normal/bold attributes.

It was written to be used as a terminal image viewer with nnn. Works independently too.

Features

• Braille art rendering for images
• Animated GIF support
• xterm-256 color and grayscale
• Dithering options (ordered, error diffusion)
• Video preview (frame extraction with ffmpeg)
• Keyboard navigation and slideshow mode

Installation

Install the required dependencies and the dotz command:

# Install system dependencies (e.g., ffmpeg)
sudo apt-get install ffmpeg  # or use your OS package manager

# Install Python dependencies and the CLI tool
sudo pip3 install .

After installation, you can run the tool using:

dotz [options] <file-or-directory>

Usage

usage: dotz [-h] [-S] [-C] [-d {ordered,error,none}] [-s [DELAY]] [-k SEEK] [-f {jpeg,png}] [path]

Render an image or all images/videos in a directory as Braille cells using ncurses with optional xterm-256 color.

positional arguments:
  path                  Path to the image/video file or directory (optional)

options:
  -h, --help            show this help message and exit
  -S, --no-sharpen      Disable edge sharpening
  -C, --no-color        Disable color (greyscale only with dim/normal/bold)
  -d {ordered,error,none}, --dither {ordered,error,none}
                        Dithering mode: ordered (default, clean), error (Floyd-Steinberg, smooth gradients), none
  -s [DELAY], --slideshow [DELAY]
                        Enable slideshow mode with optional integer delay in seconds (default: 5).
  -k SEEK, --seek SEEK  Seek position to extract frame from videos in seconds (default: 10)
  -f {jpeg,png}, --format {jpeg,png}
                        Format for extracted video frames: jpeg (default) or png

Examples

• Syntax:

  python -m dotz <file-or-directory>
  

• To render a single image:

  python -m dotz path/to/image.jpg
  

• To render all images and videos in a directory:

  python -m dotz path/to/directory/
  

• To run a slideshow with a custom delay (e.g. 3 seconds):

  python -m dotz -s 3 path/to/directory/
  

Navigation

Key	Action
Right, l, Space	Next
Left, h	Previous
Up	First
Down	Last
s	Toggle slideshow
S	Toggle reverse slideshow
q, Esc	Quit

Dependencies

Package	Version	Usage
python	>=3.7	Required Python version
numpy	>=1.20	Fast array operations for image processing
Pillow	>=8.0	Image loading and manipulation
ffmpeg	>=4.2	Video frame extraction

Formats

Image: PNG, JPG, JPEG, BMP, GIF, TIFF, WEBP

Video: MP4, MKV, AVI, MOV, WEBM, FLV, WMV, MPEG, MPG

License

MIT