Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Ugly is a light-weight language-agnostic 2D graphics library.

Why does this exist?

  • The canvas API is very nice, but Javascript isn't as powerful as low-level languages like C
  • Low level languages like C require lots of hoop-jumping before you can easily draw on the screen

ugly solves both of these problems. Harnassing a simple text-stream interface between programs, ugly takes in commands in real-time and forwards them via WebSockets to a local Javascript client, rendering your drawings on an HTML5 canvas for your viewing pleasure.


Install with npm:

npm install -g ugly

Or clone the repo, and install:

git clone
cd ugly
npm install -g


To use ugly, make sure your application outputs text according to the ugly protocol on standard out.

yourprogram | ugly

Now, head to localhost:3333/viewer/ and enjoy the show!


There are a few command line options available:

  • -p: Change the port used to serve the client (default is 3333). (Make sure this is not set to 4444 as that port is the hard-coded WebSocket port)

  • -l: Change where the log file is written (default is 'ugly.log')

  • -r: The framerate at which the server will try to send frames. (default is 120) Note that the rate at which ugly sends frames has nothing to do with the rate it receives commands. So it can receive all the commands at once and still render them at the right speed. This is helpful if you have a pre-generated ugly script:

      cat uglyScript | ugly -r 60

    If you are generating commands in realtime, as long as the rate is a positive multiple of your actual framerate, ugly will keep up with your program and render in as-close-to-realtime as it can.

  • -v: Set the verbosity (0-3):

    • 0: Nothing logged to file or console
    • 1: Nothing logged to console, everything logged to file
    • 2: Errors logged to console, everything logged to file (default)
    • 3: Everything logged to file and console
  • -s: Set the websocket port. Make sure this is different from the port used to server the viewer (default is 4444)


There's an example included in the examples directory. You can run it in either of the following ways:

If you have python:

python examples/ | ugly

If you don't (or if you do and don't want to use it)

cat examples/midpointDisplacementOutput.txt | ugly -r 1


To learn more about the commands supported by ugly, please refer to the wiki page: Commands


Pull requests are welcome and encouraged! Potential features that aren't yet implemented:

  • Support for directly creating and manipulating imageData
  • Some way to capture input from the viewer and pipe it back to the server so it can be made accessible in real-time to the original application
  • Clever ways of compressing the amount of data sent from the server to the client (even just sending all the commands in one send as opposed to one send per line may help, or it may make things worse)


Please adhere to existing style as much as possible:

  • 4-space tabs for indentation, spaces for alignment
  • <= 80 character lines
  • Spaces before parentheses


Special thanks to those who have helped improve ugly: