Ttyrec Explained

ttyrec is a program or its file format capable of recording the TTY output of a text-mode program together with timestamps and then replaying it.

It is widely used for example in the NetHack community for storing game replays.

It is similar to the script command, but also allows for pausing, slowing down or speeding up playback. It can also stream the recording on the network and be used to transfer files with uudecode.^[1]

Recorders and players

original ttyrec (Unix)
Term::TtyRec^[2] (Perl)
Term::TtyRec::Plus^[3] (Perl)
Tie::Handle::TtyRec^[4] (Perl)
termrec^[5] (Win32, Unix)

Playback only

TTYPLAYER^[6] (Java)
IPBT^[7] (Unix)

Technical file format specification

Each chunk consists of a header using 32bit unsigned little-endian numbers:

sec - seconds, either since the beginning of the recording (0-based) or since the Unix epoch
usec - 0..999999 microseconds
len - length of the payload

and the actual payload written as text with vt100 control codes.

The format does not contain any information about the character set used nor about the terminal size needed to play back the file. termrec will inject this information as \e for UTF-8 or \e for not UTF-8 and as \eYX for size, but not all players will understand these codes.

Related formats

nh-recorder^[8]
Joey Hess's modifications of script^[9]
RealLogs

References

Web site: Ttyrec: A tty recorder . 2006-07-06 . 2007-07-30 . https://web.archive.org/web/20070730220612/http://0xcc.net/ttyrec/ . live .
Web site: Term::TtyRec - handles ttyrec data - metacpan.org . 2013-09-16 . 2021-10-27 . https://web.archive.org/web/20211027223951/https://metacpan.org/_assets/03eb0fea601652f70afab5bc8dc6054e819eea72.js . live .
Web site: Term::TtyRec::Plus - read a ttyrec - metacpan.org . 2013-09-16 . 2021-10-27 . https://web.archive.org/web/20211027223955/https://metacpan.org/_assets/d2affd95a4470800aa6d3ca419c87cded6b533a7.css . live .
Web site: Tie::Handle::TtyRec - write a ttyrec - metacpan.org . 2013-09-16 . 2021-10-27 . https://web.archive.org/web/20211027223956/https://metacpan.org/_assets/03eb0fea601652f70afab5bc8dc6054e819eea72.js . live .
Web site: 1KB: Software/Termrec . 2006-07-06 . 2006-07-15 . https://web.archive.org/web/20060715002805/http://angband.pl/termrec.html . live .
Web site: Ttyplayer . 2008-04-09 . 2012-02-11 . https://web.archive.org/web/20120211130519/http://www-masu.ist.osaka-u.ac.jp/~kakugawa/misc/ttyplayer/index-en.shtml . live .
Web site: IPBT: A high-tech ttyrec player for Unix . 2006-07-06 . 2006-06-30 . https://web.archive.org/web/20060630122002/http://www.chiark.greenend.org.uk/%7Esgtatham/ipbt/ . live .
Web site: Nethack Recorder/Player Version 1.0 . 2006-07-06 . dead . https://web.archive.org/web/20060621172635/http://nh-recorder.sourceforge.net/ . 2006-06-21 .
Web site: #68556 - [patch] adding timings to script - Debian Bug report logs . 2014-06-13 . 2019-04-10 . https://web.archive.org/web/20190410212747/https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=68556 . live .