API reference

Converters

BaseConverter

Attributes
Methods
class asciipy.BaseConverter(config=None, background=None)

base class for all converters.

Parameters:

  • config (Optional[ConverterConfig]) – configuration for the converter. by default ConverterConfig()

  • background (Optional[BackgroundConfig]) – configuration for the converters background. by default BackgroundConfig(enabled=False)

width

width of the converters output in characters.

Type:

int

palette

the converters color palette.

Type:

List[Tuple[int, int, int]]

chars

the converters character set (darkest -> lightest).

Type:

Union[List[str], str]

font

the converters font.

Type:

Union[os.PathLike | io.IOBase | str]

transparent

if the converter copies the inputs alpha channel.

Type:

bool

convert(_input, output)

method to convert media, implemented by subclasses.

Parameters:
Raises:

NotImplementedError – method is only implemented in subclasses.

on_image(frame)

method called after an image or frame is converted and saved, implemented by subclasses or with image().

Parameters:

frame (Union[os.PathLike, io.IOBase, str]) – path to the saved image

Raises:

NotImplementedError – method is only implemented in subclasses.

image(func)

A decorator that sets the decorated function to be called after an image or frame is converted and saved. see on_image() for more details.

ImageConverter

Attributes
Methods
class asciipy.ImageConverter(config=None, background=None)

converts images to ascii-images.

Parameters:

  • config (Optional[ConverterConfig]) – configuration for the converter. by default ConverterConfig()

  • background (Optional[BackgroundConfig]) – configuration for the converters background. by default BackgroundConfig(enabled=False)

width

width of the converters output in characters.

Type:

int

palette

the converters color palette.

Type:

List[Tuple[int, int, int]]

chars

the converters character set (darkest -> lightest).

Type:

Union[List[str], str]

font

the converters font.

Type:

Union[os.PathLike | io.IOBase | str]

transparent

if the converter copies the inputs alpha channel.

Type:

bool

on_image(frame)

method called after an image or frame is converted and saved, implemented with image().

Parameters:

frame (Union[os.PathLike, io.IOBase, str]) – path to the saved image

convert(_input, output)

method to convert images to ascii-images.

Parameters:
Return type:

None

GifConverter

Attributes
Methods
class asciipy.GifConverter(config=None, background=None, *, gif=True)

converts gifs to ascii-gifs (or images).

Parameters:

  • config (Optional[ConverterConfig]) – configuration for the converter. by default ConverterConfig()

  • background (Optional[BackgroundConfig]) – configuration for the converters background. by default BackgroundConfig(enabled=False)

  • gif (Optional[bool]) – when true, output all frames converted to ascii, otherwise output only the first frame. by default True

width

width of the converters output in characters.

Type:

int

palette

the converters color palette.

Type:

List[Tuple[int, int, int]]

chars

the converters character set (darkest -> lightest).

Type:

Union[List[str], str]

font

the converters font.

Type:

Union[os.PathLike | io.IOBase | str]

transparent

if the converter copies the inputs alpha channel.

Type:

bool

on_image(frame)

method called after a gif or image is converted and saved, implemented with image().

Parameters:

frame (Union[os.PathLike, io.IOBase, str]) – path to the saved gif/image

convert(_input, output)

method to convert gifs to ascii-gifs (or images).

Parameters:
Return type:

None

VideoConverter

Attributes
Methods
class asciipy.VideoConverter(config=None, background=None, *, progress=True, converters=1)

converts videos to ascii-videos.

Parameters:

  • config (Optional[ConverterConfig]) – configuration for the converter. by default ConverterConfig()

  • background (Optional[BackgroundConfig]) – configuration for the converters background. by default BackgroundConfig(enabled=False)

  • progress (Optional[bool]) – when true, print the percentage completion after each frame. by default True

  • converters (Optional[int]) – number of converter processes to spawn. by default 1

width

width of the converters output in characters.

Type:

int

palette

the converters color palette.

Type:

List[Tuple[int, int, int]]

chars

the converters character set (darkest -> lightest).

Type:

Union[List[str], str]

font

the converters font.

Type:

Union[os.PathLike | io.IOBase | str]

transparent

if the converter copies the inputs alpha channel.

Type:

bool

converters

number of converter processes what will be spawned when convert() is called.

Type:

int

image(func)

A decorator that calls the decorated function after a frame is converted and saved. see on_image() for more details.

Raises:

Exception – raised when self.converters > 1 due to not being able to pickle objects with overridden methods.

on_image(frame)

method called after a frame is converted and saved, implemented with image().

Parameters:

frame (Union[os.PathLike, io.IOBase, str]) – path to the saved frame

convert(_input, output)

method to convert videos to ascii-videos.

Parameters:
Return type:

None

Configs

ConverterConfig

class asciipy.ConverterConfig(*, width=80, palette=None, char_list=None, font=None, font_size=None, transparent=False)

class contaning configuration for BaseConverter, and its subclasses.

Parameters:

  • width (Optional[int]) – width (in characters) of the output media. by default 80

  • palette (Optional[List[Tuple[int, int, int]]]) – custom color palette, list of RGB tuples. by default None

  • char_list (Optional[str]) – custom character list (darkest -> brightest). by default gS#%@

  • font (Optional[os.PathLike | io.IOBase | str]) – font used for characters in the output media. supports TrueType and OpenType fonts. by default None

  • font_size (Optional[int]) – size of the font in points (font must support requested size). by default None

  • transparent (Optional[bool]) – when true, the alpha channel from the input is preserved and applied to the output. otherwise the alpha channel is discarded. by default False

BackgroundConfig

class asciipy.BackgroundConfig(*, enabled=True, color=None, alpha=True, palette=None, back_layer=None, back_threshold=0, darken=0.9)

class contanining configuration information for a converters background.

Parameters:

  • enabled (Optional[int]) – enable the background system when true; note: when no config is passed to a converter, background is disabled. by default True

  • color (Optional[Tuple[int, int, int]]) – color for the text background. by default None

  • alpha (Optional[bool]) – when true, copy the alpha channel from the source media. by default True

  • palette (Optional[List[Tuple[int. int, int]]]) – optional color palette for the text background (R,G,B) 0-255 (overrides color). by default None

  • back_layer (Optional[Tuple[int, int, int]]) – color of the “true” background (R,G,B) 0-255. by default None

  • back_threshold (Optional[int]) – any pixel with an alpha less than or equal to this threshold is condisdered part of the “true” background. by default 0

  • darken (Optional[float]) – all luma values are multiplied by this number. by default 0.9

Palettes

C64

asciipy.palettes.c64 = [(0, 0, 0), (0, 0, 170), (0, 136, 255), (0, 204, 85), (51, 51, 51), (102, 68, 0), (119, 119, 119), (136, 0, 0), (170, 255, 102), (170, 255, 238), (187, 187, 187), (204, 68, 204), (221, 136, 85), (238, 238, 119), (255, 119, 119), (255, 255, 255)]

color palette of the commodore 64.

NES

asciipy.palettes.nes = [(0, 0, 0), (0, 0, 219), (0, 36, 146), (0, 73, 73), (0, 73, 255), (0, 109, 36), (0, 109, 219), (0, 146, 0), (0, 146, 146), (0, 182, 109), (0, 255, 0), (0, 255, 255), (36, 36, 36), (36, 73, 0), (36, 146, 0), (73, 73, 73), (73, 255, 219), (109, 73, 0), (109, 73, 219), (109, 109, 109), (109, 182, 255), (109, 219, 0), (146, 0, 109), (146, 0, 255), (146, 73, 0), (146, 109, 0), (146, 146, 146), (146, 146, 255), (146, 219, 255), (146, 255, 109), (182, 0, 109), (182, 0, 255), (182, 36, 0), (182, 182, 182), (182, 219, 255), (182, 255, 73), (219, 109, 0), (219, 109, 255), (219, 182, 255), (219, 219, 0), (255, 0, 0), (255, 0, 146), (255, 0, 255), (255, 109, 255), (255, 146, 0), (255, 146, 255), (255, 182, 0), (255, 182, 182), (255, 182, 255), (255, 219, 146), (255, 255, 73), (255, 255, 109), (255, 255, 255)]

color palette of the Nintendo Entertainment System (aka Nintendo Famicom).

CMD

asciipy.palettes.cmd = [(0, 55, 218), (12, 12, 12), (19, 161, 14), (22, 198, 12), (58, 150, 221), (59, 120, 255), (97, 214, 214), (118, 118, 118), (136, 23, 152), (180, 0, 158), (193, 156, 0), (197, 15, 31), (204, 204, 204), (231, 72, 86), (242, 242, 242), (249, 241, 165)]

color palette of the Windows command line.

grayscale

asciipy.palettes.grayscale = [(0, 0, 0), (47, 79, 79), (105, 105, 105), (112, 128, 144), (119, 136, 153), (128, 128, 128), (169, 169, 169), (192, 192, 192), (211, 211, 211), (220, 220, 220), (255, 255, 255)]

gray scale color palette (contains some off-grays).