a high-tech ttyrec player for Unix


ttyrec is a program for recording a Unix terminal session. It works much like script, but its output file contains timestamp information in addition to the terminal data, so that the session can be played back later in real time. A common use for this program is to record games of NetHack for other people to watch; alt.org, for example, does this routinely.

The simplest application for playing back a ttyrec file is to write the data in the file to a terminal, stopping to wait in between sections as directed by the timestamps in the file. It's easy enough to provide features such as double or half speed, fast forward and pause; but going backwards in time is very difficult, since terminal data cannot be interpreted in reverse to work out what was on the screen before the current time. So if you're watching a ttyrec and something interesting flashes up on the screen and is gone before you can press Pause, it can be very difficult to retrieve it.

IPBT solves this problem. It is a ttyrec player which analyses the entire ttyrec file before beginning the playback, and reorganises it into a form which permits frame-by-frame forward and backward replay. So if something interesting goes past, you just press Pause and then back up by a few frames, and there it is.

The downside is that the initial analysis phase takes time. On a 2GHz Pentium 4, I find it takes of the order of five seconds per megabyte of input. So if you want to watch an 8Mb file, you'll have to wait for something in excess of half a minute before IPBT is ready to show it to you. (This is annoying, but for me at least it's more than made up for by the ability to rewind.)

Technical details

IPBT works by reading the entire input file and running it through an internal terminal emulator. The terminal emulator used is the one from the PuTTY SSH client (simply because that's the one whose API I was most familiar with). Thus, IPBT is a derived work of PuTTY.

While reading the file, IPBT builds up a list of the screen contents changes which take place over the course of the recording. These are stored into an internal data structure which permits efficient random-access retrieval of the screen state in any frame.

After doing this, IPBT is ready for playback. Playback is performed without any reference to the ttyrec file at all: the program simply displays the screen states that came out of the internal terminal emulator, in whatever order the user requests, via curses.

For more details, you can read the man page online.

Status of IPBT

IPBT is currently working but unpolished. I don't have the time and energy to polish it very much myself, so I'm hoping to receive contributions from other people.

For a full list of the things that need doing, you can read the file TODO in the source distribution. The big one, at the moment, is that it could do with an autoconf framework and some portability tweaks to make it work with curses implementations other than ncurses.


IPBT is distributed under the MIT licence, so it is free to copy, redistribute, use and reuse. For more details, see the file called LICENCE in the distribution archive.


A Unix source archive of IPBT is available here:


If you want to see the latest state of development, you can check the development sources out from my git repository:

git clone https://git.tartarus.org/simon/ipbt.git

Alternatively, you can browse the repository on the web, here.


Please report bugs to anakin@pobox.com.

You might find it helpful to read this article before reporting a bug.

Patches are welcome.

(comments to anakin@pobox.com)
(thanks to chiark for hosting this page)
(last modified on Wed May 1 02:10:06 2024)