Metadata-Version: 2.4
Name: ascii_art_python
Version: 3.0.0b0
Summary: A Python library and CLI tool for converting images and videos into ASCII art.
Author-email: Guillem Prieur <prieurguillem38@gmail.com>
Project-URL: Homepage, https://gitlab.pprriieeuurr.fr/guill_prieur/ascii-art-python-3
Project-URL: Bug Tracker, https://gitlab.pprriieeuurr.fr/guill_prieur/ascii-art-python-3/-/issues
Project-URL: Source Code, https://gitlab.pprriieeuurr.fr/guill_prieur/ascii-art-python-3
Project-URL: Documentation, https://guill_prieur.site-prieur.fr/ascii-art-python-3
Keywords: ascii,ascii-art,image-to-ascii,video-to-ascii,cli,terminal,terminal-graphics,generator,converter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Terminals
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow>=10.0.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: opencv-python-headless>=4.8.0
Requires-Dist: moviepy>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: click>=8.0.0
Requires-Dist: importlib_resources; python_version < "3.10"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# ascii\_art\_python

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/ascii-art-python)](https://pypi.org/project/ascii-art-python/)
[![Python versions](https://img.shields.io/pypi/pyversions/ascii-art-python)](https://pypi.org/project/ascii-art-python/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/ascii-art-python)](https://pypi.org/project/ascii-art-python/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](https://opensource.org/licenses/MIT)

</div>

A powerful and flexible Python library and Command Line Interface (CLI) to convert your images and videos into stunning ASCII art.

`ascii_art_python` uses advanced edge detection (via OpenCV) and luminosity mapping to generate high-quality ASCII representations. It supports multiprocessing for fast video conversion and even transfers original audio tracks to your ASCII videos!


## Preview

Below is an example of an image featuring the Python logo:

```
              ||=*|{||#&&&&||||||              
              /##--\&&&&&&&&&&$$&\\            
            |&&|  |{&&&&&&&&&$$$$\             
            |&&\--/&&&&&&&&&$$$$$|             
            :\-#####---\&&$$$$$$$|             
      ------/;;;;;;;===|$$$$$$$$$|  -----      
    /--##&&&&&----------/$$$$$$$$@| .:::::-\\  
  //#####&&&&&&&&&&&&$$$$$$$$$$$@| .:::::::\\  
  //&####&&&&&&&&&&&$$$$$$$$$$$$$@| .::::::::\ 
  |####&&&&&&&&&&$$$$$$$$$@@@@@@@//.:::::::::| 
  |&#&&&&&&&&&$$-----------------..:::::::::::|
  |&&&&&&&&&&//-.................:::::::::::::|
  |&&&&&&&&&// ..::::::::::::::::::::::::::;;| 
  |&&&&&&&$| ::::::::::::::::::::::::::;;;;;/  
  \\&&&&&$$| :::::::::::::::::::::::;;;;;;;//  
    \\$$$$$@| ::::::::::::::::::;;;;;;;;;;;//  
      ------/ ::::::::::...........--------    
              ::::::::::\---::::--|/           
            |::::::::::::;;/--\;;|             
            |\::::::::;;;;;|  |;;|             
              \\::::;;;;;;;;\--:;//            
              \---:;;;;;;;;;::--/              
                  ------------                 
```

And below, an example of a video featuring Nyan Cat:

![Example with the Nyan Cat video played.](https://gitlab.pprriieeuurr.fr/guill_prieur/ascii-art-python-3/-/raw/main/docs/example.gif)


## Features

- **Image to ASCII:** Convert standard images (JPG, PNG, etc.) to ASCII strings or export them as PNG files.

- **Video to ASCII:** Convert entire video files to ASCII animations (MP4 format) with original audio preserved.

- **Command Line Interface:** Quickly convert files directly from your terminal.

- **Three Rendering Modes:**

  - `full_mode`: Combines edge detection and background luminosity for highly detailed art.

  - `old_skool`: Uses directional characters based on edge detection (perfect for a "Matrix" look).

  - `new_skool`: Uses background characters mapped by luminosity.

- **Terminal Playback:** Play ASCII videos or display images directly within your console.


## Installation

Install the package easily via pip:

```bash
pip install ascii_art_python
```


## Command Line Interface (CLI) Usage

The library provides convenient commands to process your media right from the terminal.


### Display directly in the terminal

Automatically resizes the output to fit your current terminal window.

```bash
# Display an image (default full_mode)
aap-echo my_image.jpg

# Play a video with the 'old_skool' edges-only style
aap-echo my_video.mp4 -m old_skool
```


### Export to a file

Saves the ASCII output to your disk (`.png` for images, `.mp4` for videos).

```bash
# Export an image with a specific width and 'new_skool' mode
aap-export landscape.jpg landscape_ascii -w 150 -m new_skool

# Export a complete video and keep the original audio track
aap-export music_video.mp4 ascii_clip --sound -f 10
```


## Python API Usage

You can also integrate `ascii_art_python` directly into your own Python scripts.

```python
import ascii_art_python as aap

# --- 1. Image Conversion ---
# Load an image and set a target width
img = aap.Image.from_path("my_image.jpg", width=120)

# Print it to the console
print(img.to_string(old_skool=True, new_skool=True, one_on_two=True))

# Or export it as a PNG file
img.export(filename="my_ascii_image", font_size=15, old_skool=True, new_skool=True)

# --- 2. Video Conversion ---
# Load a video (processing at 15 FPS)
video = aap.Video("my_video.mp4", width=80, wanted_fps=15)

# Export the video with sound (uses multiprocessing for speed)
video.export(filename="my_ascii_video", sound=True, old_skool=True, new_skool=True)
```


## Requirements

- Python 3.9+

- `opencv-python`

- `numpy`

- `Pillow`

- `moviepy`

- `click`

- `tqdm`


## Full Documentation

To check the complete API, class details, and advanced export options, visit: [the doc](https://guill_prieur.site-prieur.fr/ascii-art-python-3/).


## License

This project is licensed under the MIT License - see the LICENSE file for details.
