Skip to content

eliep/truesay

Repository files navigation

truesay

CI npm

truesay is a command line utility displaying a text alongside an image in your terminal. truesay render the image with UTF-8 character and ANSI escape code.

truesay screenshot

Installation

> npm install -g truesay

Usage

> truesay <path-to-image-or-directory> [options]
> fortune | truesay <path-to-image-or-directory> [options]

Options

Option Description
-t, --text Text to say. If omitted, stdin is used
-b, --box Text box style: round (default), single, double, singleDouble, doubleSingle, classic, none
-bg, --background Background color used to simulate image transparency (#rrggbb format)
-w, --width Width (default: terminal width minus margin left and right)
-pos, --position Text box position: top (default) or right
-r, --resolution Image resolution: high (default, 1 pixel is half a character) or low (1 pixel is 2 characters wide)'
-p, --padding Padding between art and text (default: 0)
-mt, --margin-top Top margin in pixel (default: 1)
-mr, --margin-right Right margin in pixel (default: 1)
-mb, --margin-bottom Bottom margin in pixel (default: 0)
-ml, --margin-left Left margin in pixel (default: 1)

Image format and resolution

truesay has one mandatory parameter which is an image path. This path can be absolute or relative and must point to either an image file (gif, jpg or png) or a directory containing at least one image file.

Image format

There's only three formats accepted for the image: gif, jpg and png.

Random pick in directory

If the image path is a directory, truesay will recursively list all files in that directory, keep only the image files and choose among these one to display at random.

Image resolution

There are two resolutions for the image rendering, available via the -r option:

  • high (default): in high resolution, each image pixel is rendered by half a character.
  • low: in low resolution, each image pixel is rendered by two characters.

In practice, low resolution rendering take twice the space of high resolution for the same image.

Transparency and background option:

Some image formats like png allow pixel to be transparent.

By default:

  • if a pixel is fully transparent, truesay will ignore its rgb value,
  • if a pixel is semi transparent, truesay will ignore its transparency value.

However, to better handle semi transparent pixel, it's possible to use the -bg option to pass the terminal background color (in #rrggbb format). truesay will then use this color to emulate transparency by computing the rendering color of semi transparent pixel.

> fortune | truesay distro/32/tux -bg '#2c3440'

Below a comparison with and without the -bg option:

truesay screenshot

Text input

By default, truesay reads its text input from stdin but this can be overridden by setting the -t option to display a given text:

> echo 'Hello world!' | truesay games/link # diplay 'Hello world!' from stdin
> truesay games/link -t 'Hello world!'     # diplay 'Hello world!' from -t option
> fortune | truesay games/link             # diplay a random fortune

Text position

The -pos option allows to control the text position relative to the image. By default, the text is on top of the image (-pos top), but it can also be displayed next to this image (-pos right)

> truesay games/link -t 'Hello world!' -pos right

Width, margin and padding

Width

By default, truesay uses all the horizontal space available to display it's output. By using the width option -w, it's possible to constrain the output to a given width (expressed in character).

> truesay games/link -t 'Hello world!' -w 80

The given width includes the space available for the box, the text, and the right and left margin (see below).

Margin

truesay has 4 margin options to add extra space around its output, one for each direction: -mt (top), -mr (right), -mb (bottom), -ml (left). For example, the above command will add one blank line before the text box and one blank column to the left of the image and text box:

> truesay games/link -t 'Hello world!' -mt 1 -ml 1

Padding

The padding option -p allows to add some extra space between the text box and the image:

> truesay games/link -t 'Hello world!' -p 1 -pos right

Box style

The box style can be set with the -b option, 6 styles are available to choose from:

╭───────╮
│ round │
╰───────╯
┌────────┐
│ single │
└────────┘
╔════════╗
║ double ║
╚════════╝
╓──────────────╖
║ singleDouble ║
╙──────────────╜
╒══════════════╕
│ doubleSingle │
╘══════════════╛
+---------+
| classic |
+---------+

-b option also accepts two special values:

  • none: disable text boxing,
  • colors: the first 8 terminal colors are printed under the text

truesay screenshot