Asciiator

A CLI tool to turn images and videos into ASCII art.

• Examples
• Installation
• Usage and Options
  • Usage
  • Supported formats:
  • Optional flags
• Local development
  • Requirements/Dependencies
  • Running
• Contributing and issues

Examples

Input	Output
example_2_input.mp4	example_2_output.mp4

Installation

The binaries for Asciiator can be found under releases. The only requirement is FFmpeg which needs to be installed & in your PATH in order to convert videos.

Usage and Options

Usage

Simply execute with the path to your input files

asciiator "./your_image.jpg" "./your_image_2.jpg"

and asciiator will transform the content/pixels to ASCII and save to a new file.

Supported formats:

• Image:
  • JPEG
  • PNG
  • WEBP
  • BMP
  • TIFF
  • GIF
• Video:
  • MP4
  • AVI
  • FLV
  • MOV
  • WEBM
  • WMV
  • MKV
  • MPEG

Optional flags

Flag	Description
--inplace	Modify the file inplace. The original file will be transformed to ASCII and no new media/output file will be generated.
--help	Display the help documentation
--inverted	Invert the colors for the background and text. By default, the background color is black (0) and the text color is white (255). If --inverted is present, the background will be white and the text color will be black.
--text_file	Save the transformed ASCII art to a .txt file as well (only applicable when the input is a image)
--reduction x	Reduce the output by a factor of x (int). Default value: 4. Example: --reduction 2 to convert half of the pixels to ASCII
‑‑output_path x	Specify the output path where all new files will be created. By default it's the current directory. Warning: if the --inplace flag is present, then this flag will be ignored, so the original absolute path will be used.
--version	Display the version of Asciiator

Local development

This project uses Poetry as its package/dependency manager & FFmpeg for converting videos. Once both are installed, install the project's dependencies & dev dependencies via:

poetry install

You should now be able to run the project locally.

Requirements/Dependencies

• Python 3.10+
• FFmpeg 4.4.1+
• Poetry 1.0.0+

Running

python -m src.main "path_to_your_image"

Or if you want to run via Docker:

docker build . -t asciiator

docker run -it --entrypoint=bash asciiator

Inside the container:

python -m src.main "path_to_your_image"

Contributing and issues

See CONTRIBUTING.md