Metadata-Version: 2.4
Name: dotz
Version: 0.1
Summary: Render images and video previews as Braille art in the terminal with color and animation support.
Home-page: https://github.com/jarun/dotz
Author: Arun Prakash Jana
License: MIT
Project-URL: Homepage, https://github.com/jarun/dotz
Project-URL: Repository, https://github.com/jarun/dotz
Project-URL: Issues, https://github.com/jarun/dotz/issues
Keywords: terminal image-viewer braille curses gif video ffmpeg
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Terminals
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: Pillow>=8.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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`](https://github.com/jarun/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

<br>
<img width="1323" height="826" alt="image_01" src="https://github.com/user-attachments/assets/f2becbbc-cfeb-42b3-bd92-3882ff3fb570" />
<br><br>
<img width="1333" height="827" alt="image_02" src="https://github.com/user-attachments/assets/62bc16a8-246b-4b5a-a11e-fd0faa5c8066" />
<br><br>
<img width="1301" height="954" alt="image_03" src="https://github.com/user-attachments/assets/609805be-c0c5-4815-bb33-3bc70d69c152" />


## Installation

Install the required dependencies and the dotz command:

```sh
# 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:

```sh
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:
    ```sh
    python -m dotz <file-or-directory>
    ```
- To render a single image:
    ```sh
    python -m dotz path/to/image.jpg
    ```
- To render all images and videos in a directory:
    ```sh
    python -m dotz path/to/directory/
    ```
- To run a slideshow with a custom delay (e.g. 3 seconds):
    ```sh
    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
