ipbt - play back tty recording files with random access
ipbt [ options ] file [ file ... ]
ipbt is a
curses-based playback utility for recordings of terminal sessions in either
nh-recorder format, or raw terminal recordings.
nh-recorder are both programs which record the output of a terminal session, interspersed with timestamps. This allows the session to be replayed on another terminal at the original speed, so that the replaying terminal screen looks identical to the original, provided the recording and replaying terminals are sufficiently compatible.
nh-recorder produce differently formatted files, but the principle is very similar.
To replay a tty recording in a forward direction, a program such as
ttyplay will simply write the contents of the file to the output terminal, stopping to wait for the appropriate period every time it encounters a timestamp. Speeding up, slowing down and pausing the replay are easy. Rewinding, however, is almost impossible with this replay architecture.
ipbt solves this by running the entire tty recording through an internal terminal emulator and storing the resulting screen contents in a manner that permits random access. Once this loading process is complete,
ipbt can play forwards and backwards, or jump to an arbitrary point in the recording, with equal ease.
This flexibility comes with two disadvantages:
ipbttakes noticeable time to load a tty recording in the first place. At the time of writing this, it typically takes a few seconds per megabyte of input. Simpler programs such as
ttyplaycan begin playing instantly.
ipbtdoes its terminal emulation internally, it can support only one type of terminal, namely that provided by PuTTY (of which
ipbtis a derived work). Any tty recording which is not compatible with that terminal type will not come out looking right. Simpler programs such as
ttyplayrely on the terminal they are running in to interpret the terminal control sequences, so they can be made to support any terminal type simply by running them in that type of terminal.
If either of these is a serious problem, you probably don't want to be using
ipbt interprets tty recordings as if they were intended to be replayed on an 80×24 screen. You can alter this using the following options:
ipbt will attempt to analyse the input files and automatically guess whether they are in
nh-recorder format. On rare occasions this automatic guessing may fail: for example, a
ttyrec made on a system whose clock occasionally jumps backwards may contain timestamps in non-increasing order, in which case
ipbt may consider the file not to be a valid
ttyrec and either try to interpret it as
nh-recorder format or (more likely) refuse to load it at all. If this happens, you will need to explicitly tell
ipbt what type of file it is dealing with using the following options:
ipbt also provides the following miscellaneous options:
ipbt's loading speed or test its automatic format detection.
ipbt has been compiled against the
ncursesw library and is running in a UTF-8 terminal, it will reproduce the Unicode characters in the input file as faithfully as it can. If not, it will at least try to reproduce as many of the characters as it can on whatever terminal it does have.
In common with PuTTY,
ipbt takes the default position that a UTF-8 terminal stream is expected never to switch character-set modes in this way, and should display all graphic characters by sending their UTF-8 control sequences. However, some applications insist on doing line drawing in the old-fashioned way even in UTF-8 mode. If your playback displays boxes on the screen looking like this:
lqqqqqk x x x x mqqqqqj
then this option might turn them into proper line-drawing boxes.
Applications based on
ncurses can be persuaded not to emit these sequences in the first place by setting ‘
NCURSES_NO_UTF8_ACS=1’ in the environment.
ipbt has loaded a set of tty recordings, it enters a full-screen playing mode. This section describes the keypresses which control the player.
To terminate the player, press ‘
q’, or Control-C.
p’ or ‘
s’ to toggle between pause and play mode. The player starts up in pause mode, so you may well want to press this immediately to begin playing.
To go back by one frame, press ‘
b’ or ‘
<’. To go back by many frames, type a number followed by ‘
b’ or ‘
To go forward by one frame, press the space bar or ‘
>’. To go back by many frames, type a number followed by the space bar or ‘
To jump to a particular frame number, type the number followed by ‘
g’. Pressing ‘
g’ on its own will jump to the start of the recording.
Pressing capital ‘
G’ will jump to the end of the recording. If you type a number followed by ‘
G’, it will jump to that many frames before the end.
To play back the recording at higher speed, type a number followed by ‘
x’. For example, typing ‘
3x’ will set the player to three times normal speed. (This will not automatically bring you out of pause mode; you still need to press ‘
p’ or ‘
s’ for that.)
To play back at a lower speed, type a number followed by capital ‘
X’; for example, ‘
3X’ will set the player to one-third normal speed.
To return to normal speed, you can type ‘
1x’ or ‘
1X’, or just ‘
x’ or ‘
If you press ‘
l’, the player will toggle logarithmic time compression. This is a mode in which the delay between frames is scaled in a non-linear fashion: small delays are changed very little, but extremely large delays are made significantly less large, so that an hour between frames in the original recording becomes only about eight seconds, a day becomes eleven, and even a year between frames would become around seventeen seconds. This is helpful if the person who made the recording left the terminal for a long time in the middle of their session. Logarithmic mode can be used in conjunction with the ‘
X’ scaling feature.
If you press ‘
o’, the player will show an on-screen display near the top left of the screen, showing the current frame number and playback settings. Press ‘
o’ again to make the display go away.
You can also search the recording for a frame in which a particular piece of text appears on the screen. Press ‘
/’ to search forwards from the current position, or ‘
\’ or ‘
?’ to search backwards. Each of these commands will cause
ipbt to prompt for a piece of text to find, and will then search for a frame that contains that text. Press ‘
n’ to search for the same piece of text again in the same direction.
ipbt's internal terminal emulation is that of PuTTY, but its display of the resulting data is rather more simplistic. Some output features supported by PuTTY are therefore not supported by
xterm 256-colour mode is not supported at all.
ipbt's Unicode support does not currently handle various Unicode complications such as characters outside the Basic Multilingual Plane, double-width CJK characters, right-to-left scripts, or combining characters.
(Patches or help from people who know how to persuade
ncursesw to do any or all of those things would be welcome!)
ipbt is free software, distributed under the MIT licence. Type
ipbt --licence to see the full licence text.