Skip to content

Latest commit

 

History

History
176 lines (147 loc) · 6.58 KB

README.md

File metadata and controls

176 lines (147 loc) · 6.58 KB
Raw

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