ASCII art library in JavaScript

View on GitHub


This library converts images and movies to ASCII art.

It is written entirely in JavaScript and is intended to use in web browsers.


Interactive demo

Click here


Converting to ASCII art is performed by reading an image (or a video) then processing it by a series of processors and finally rendering the output.

In general it has the following form:

Reader » Pre-Filter » AA » Post-Filter » Renderer

This means what follows:

  1. Reader reads image (static or moving) and converts it to internal representation.
  2. (Optional) Pre-Filter (e.g. brightness or contrast) can be applied to the image from the 1st step.
  3. AA transforms image from the 2nd step to ASCII art.
  4. (Optional) Another Post-Filter can be applied but in this step it is applied to ASCII art image.
  5. Renderer renders image from the 4th step to a given output.

That is how it looks expressed in a code:

    .map(aalib.aa({ width: 530, height: 160 }))
    .map(aalib.render.html({ el: document.querySelector(".aa-image") }))

See API section for more details on how the processors work.

The library is using RxJS under the hood. Every reader actually returns an Observable so processing is not started until subscribe method is called. Data emitted by observables may be transformed by map operator, or you are allowed to perform any operation (like logging or side-effects) by using do operator.

The library is distributed as:

<script type="text/javascript" src="dist/aalib.js"></script>
const aalib = require("aalib.js");

// or

import aalib from "aalib.js";

You may also want to load separate files by importing/requiring directly from aalib.js/lib:



These are objects which read from various sources and write to a processing stream.


Exposed in aalib.read.image and as a default export in aalib.js/lib/readers/ImageReader.

Factory methods:


Exposed in aalib.read.video and as a default export in aalib.js/lib/readers/VideoReader.

Factory methods:

options accepts the following options:


Exposed as aalib.read.imageData or as a default export in aalib.js/lib/readers/ImageDataReader.

Use the fromImageData factory method to create observable from an image data object. An image data object contains three mandatory fields; width, height, and data. The first two describe the dimensions of the image data, while the third is an array of width * height * 4 elements, where each pixels is represented as r, g, b, alpha. ImageData object are returned for example when getting pixel data from a canvas, or when rendering to an offscreen buffer using WebGL.


Filters are processors changing each component of an image. When a filter is applied to a regular image it changes a RGB value. When a filter is applied to ASCII art image it changes the only component the image has - intensity. Intensity is a value which tells whether part of an image should be rendered as a “dark” or “light” character.


Exposed as aalib.filter.inverse or as a default export in aalib.js/lib/filters/inverse.


This filter inverses each component of an image. By inversion I mean the function: f(x) = 255 - x


Exposed as aalib.filter.linear or as a default export in aalib.js/lib/filters/linear.

aalib.filter.linear(a:number, b:number)

It applies the linear transformation: f(x) = ax + b


Exposed as aalib.filter.brightness or as a default export in aalib.js/lib/filters/brightness.


It changes the brightness of an image. This is the special case of the linear filter where a = 1.


Exposed as aalib.filter.contrast or as a default export in aalib.js/lib/filters/contrast.


It changes the contrast of an image. This is the special case of the linear filter where b = 0.


Exposed as aalib.filter.desaturate or as a default export in aalib.js/lib/filters/desaturate.


It desaturates (converts to a grayscale) an image.


This processor handles actual conversion to ASCII art image.

Exposed as aalib.aa or as a default export in lib/aa.


It accepts the following options:


Renderers outputs ASCII art image. They can render using different characters set. By default two charsets are defined are defined:

They are exposed in each renderer as named export:

import { ASCII_CHARSET, SIMPLE_CHARSET } from "lib/renderers/HTMLRenderer";

or as



Exposed as aalib.render.html or as a default export in aalib.js/lib/renderers/HTMLRenderer.


Renders ASCII art image as HTML element.



Exposed as aalib.render.canvas or as a default export in aalib.js/lib/renderers/CanvasRenderer.


Renders ASCII art image as Canvas element.



The MIT License (MIT). Copyright (c) 2017 mirz (that.mirz@gmail.com)