Skip to content

ANSI graphics parser for node.js. Output to plain text, HTML, binary, animated GIF, PNG, video, or whatever you want.

Notifications You must be signed in to change notification settings

echicken/node-ansi

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

65 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

node-ansi

ANSI graphics parser for node.js. Output to plain text, HTML, binary, animated GIF, PNG, video, or whatever you want.

####Installation

npm install ansi-graphics

GIF, PNG, and video output functionality uses gifencoder and node-canvas, which in turn rely on Cairo. Ensure that Cairo and its dependencies are installed before proceeding. On Ubuntu I've also needed to install libjpeg-dev and libgif-dev in order to install these modules.

ffmpeg is not required for installation, however you'll need a recent build of ffmpeg in your PATH in order to use the output-to-video functionality.

####Usage

var ANSI = require('ansi-graphics'),
	fs = require('fs');

// Create a new ANSI object
var a = new ANSI();

// Load an ANSI graphic from a file
a.fromFile("./gnome.ans");

// Write the plain-text version of the graphic to a file
fs.writeFileSync("gnome.txt", a.plainText, { 'encoding' : 'binary' });

// Write the HTML version of the graphic to a file
fs.writeFileSync(
	"gnome.html",
	"<html><body>" + a.HTML + "</body></html>",
	{ 'encoding' : 'binary' }
);

// Write the binary version of the graphic to a file
fs.writeFileSync("gnome.bin", a.binary);

// Save the looping, animated GIF version of the graphic to a file
fs.writeFileSync("gnome.gif", a.toGIF({ 'loop' : true }));

// Save the PNG version of the graphic to a file
fs.writeFileSync("gnome.png", a.toPNG());

// Save an MP4 video of the scrolling graphic to a file
a.toVideo(
	{ speed : .13 },
	function(video) {
		fs.writeFileSync("gnome.mp4", video);
	}
);

The ANSI object

#####Methods

  • fromFile("/path/to/file.ans")
    • Loads and parses an ANSI graphic from a file
  • fromString(ansiString)
    • Loads and parses an ANSI graphic from a string
  • toGIF(options) (Buffer)
    • Converts the loaded ANSI graphic to an animated GIF
    • options is an optional object with the following properties:
      • loop (boolean) (default: false)
        • Whether or not the GIF should loop infinitely
      • delay (number) (default: 40)
        • Time between frames, in milliseconds
      • charactersPerFrame (number) (default: 20)
        • How many new characters appear in each frame of the GIF
          • If you set this to 1, the GIF will show the ANSI being drawn one character at a time, which is nice, however ...
          • If you set this to 1, it will take a long time to generate the GIF
          • Adjusting this number has a noticeable impact on filesize
          • You'll probably want to adjust delay along with this value
      • quality (number) (default: 20)
        • The image quality, on a scale of 1 to 20, where 1 is best and 20 is worst
          • I haven't noticed a visible difference between 1 and 20
          • GIFs generate a lot faster when the quality is set to the lowest (yet highest-numbered) value
      • scale (number) (default: 1)
        • Scale the image to this many times its actual size (.25 would be 25%, 2 would be 200%, etc.)
    • Returns a Buffer object
  • toPNG(options) (Buffer)
    • Converts the loaded ANSI graphic to a PNG
    • options is an optional object with the following properties:
      • quality (number) (default: 5)
        • The image quality, on a scale of 1 - 5, where 1 is best and 5 is worst
      • scale (number) (default: 1)
        • Scale the image to this many times its actual size (.25 would be 25%, 2 would be 200%, etc.)
    • Returns a Buffer object
  • toVideo(options, callback)
    • Converts the loaded ANSI graphic to a video
    • options is an optional object with the following properties:
      • format (string) (default: matroska)
        • See ffmpeg's documentation re: output formats for possibilities
      • speed (number) (default: 1)
        • Adjust the playback speed of the video
          • 0.25 would cause the video to play back four times faster
          • 2.5 would cause the video to play back two and a half times more slowly
      • charactersPerFrame (number) (default: 20)
        • As in toGIF() above, how many new characters appear in each frame of the video
        • Ultimately this is another way to adjust the "speed" of the video
        • Adjusting this value instead of 'speed' usually results in videos being generated more quickly
      • scale (number) (default: 1)
        • Scale the video to this many times the size of the original image (.25 would be 25%, 2 would be 200%, etc.)
    • callback is a required function that will be called with one argument, a Buffer object containing the video

#####Properties

  • width (Number)

    • The width of the graphic, in characters
  • height (Number)

    • The height of the graphic, in characters
  • pixelWidth (Number)

    • The width of the graphic, in pixels, when output as PNG/GIF/Video
  • pixelHeight (Number)

    • The height of the graphic, in pixels, when output as PNG/GIF/Video
  • data (Array)

    • An array of objects representing each explicitly drawn character in the graphic
    • Elements in this array appear in the sequence that they were parsed from the file
      • The parser handles cursor-positioning sequences
      • The parser handles clear-screen and clear-to-EOL sequences
      • Characters will not necessarily be in left-to-right, top-to-bottom sequence
        • This is useful for handling animated ANSIs
    • The elements in this array are objects of the following format:
{	cursor : {
		x : *number*,			// X-coordinate of character
		y : *number*			// Y-coordinate of character
	},
	graphics : {
		bright : *boolean*,		// Bold/bright foreground colour
		blink : *boolean*,		// Blinking
		foreground : *number*,	// Foreground colour (30 - 47)
		background : *number*	// Background colour (40 - 47)
	},
	chr : *string*				// The character itself
}
  • matrix (Object)
    • An object representing every character-cell in the graphic, from top to bottom, left to right
    • The object takes the following format:
{	0 : { 		// Line 0 of the graphic
		0 : {	// Column 1 of line 0
			graphics : {
				bright : *boolean*,
				blink : *boolean*,
				foreground : *number*,
				background : *number*
			},
			chr : *string*
		}
		...
	}
	...
}
  • plainText (String)

    • A string representation of the graphic with all colour/bright/blink attributes removed, with line-endings in place
      • (ie. the ANSI graphic converted to boring text.)
  • binary (Buffer)

    • A buffer of [ chr, attr, chr, attr, ... ] uint8s
  • HTML (String)

    • An HTML <pre> block containing the graphic, with colorized regions in styled <span> elements, and characters encoded as HTML entities as required
      • Opening and closing <html> <head> and <body> tags are not included in this string

About

ANSI graphics parser for node.js. Output to plain text, HTML, binary, animated GIF, PNG, video, or whatever you want.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published