\cfg{man-identity}{ipbt}{1}{2007-04-19}{Simon Tatham}{Simon Tatham}

\H{ipbt-manpage} Man page for \c{ipbt}

\S{ipbt-manpage-name} NAME

\c{ipbt} - play back tty recording files with random access

\S{ipbt-manpage-synopsis} SYNOPSIS

\c ipbt [ options ] file [ file ... ]
\e bbbb   iiiiiii   iiii   iiii

\S{ipbt-manpage-description} DESCRIPTION

\c{ipbt} is a \c{curses}-based playback utility for recordings of
terminal sessions in either \c{ttyrec} or \c{nh-recorder} format,
or raw terminal recordings.

\c{ttyrec} and \c{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. \c{ttyrec} and
\c{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
\c{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.

\c{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, \c{ipbt} can play forwards and backwards, or jump to an
arbitrary point in the recording, with equal ease.

This flexibility comes with two disadvantages:

\b \c{ipbt} takes 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 \c{ttyplay}
can begin playing instantly.

\b Since \c{ipbt} does its terminal emulation internally, it can
support only one type of terminal, namely that provided by PuTTY (of
which \c{ipbt} is a derived work). Any tty recording which is not
compatible with that terminal type will not come out looking right.
Simpler programs such as \c{ttyplay} rely 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 \c{ipbt}.

\S{ipbt-manpage-options} OPTIONS

By default, \c{ipbt} interprets tty recordings as if they were
intended to be replayed on an 80\u00D7{x}24 screen. You can alter
this using the following options:

\dt \c{-w} \e{width}

\dd Set the width of the emulated terminal to \e{width} columns.

\dt \c{-h} \e{height}

\dd Set the height of the emulated terminal to \e{height} rows.

\dt \c{-u}

\dd Set the width and height of the emulated terminal to be the same
as that of the real terminal in which you are running \c{ipbt}.

By default, \c{ipbt} will attempt to analyse the input files and
automatically guess whether they are in \c{ttyrec} or
\c{nh-recorder} format. On rare occasions this automatic guessing
may fail: for example, a \c{ttyrec} made on a system whose clock
occasionally jumps backwards may contain timestamps in
non-increasing order, in which case \c{ipbt} may consider the file
not to be a valid \c{ttyrec} and either try to interpret it as
\c{nh-recorder} format or (more likely) refuse to load it at all. If
this happens, you will need to explicitly tell \c{ipbt} what type of
file it is dealing with using the following options:

\dt \c{-T}

\dd Specify that all files appearing on the command line after this
point (until a subsequent format-specifying option) should be
assumed to be in \c{ttyrec} format.

\dt \c{-N}

\dd Specify that all files appearing on the command line after this
point (until a subsequent format-specifying option) should be
assumed to be in \c{nh-recorder} format.

\dt \c{-R}

\dd Specify that all files appearing on the command line after this
point (until a subsequent format-specifying option) should be
assumed to be raw terminal sessions without timestamps.
These are assigned a fixed nominal playback speed of 10ms per byte.
Raw files are not ever autodetected: you must specify -R.

\c{ipbt} also provides the following miscellaneous options:

\dt \c{-f} \e{frame}

\dd After loading the tty recordings, jump to the specified frame
number. Frame numbers are allocated starting from zero, as if all
the input files were concatenated; so if you provided two input
files, one with 100 frames and one with 50, then frame numbers 0-99
would indicate positions in the first file and frame numbers 100-149
would indicate positions in the second.

\dt \c{-A}

\dd Automatically begin playback after loading the tty recordings,
at the specified frame if specified with \c{-f}.

\dt \c{-p} \e{frame}

\dd Pause upon reaching the specified frame. Frame numbering uses
the same convention as \c{-f}.

\dt \c{-q} \e{frame}

\dd Quit upon reaching or passing the specified frame. Frame numbering
uses the same convention as \c{-f}.

\dt \c{-P}

\dd After loading the tty recordings, terminate immediately. This
option is unlikely to be very useful at present, although it might
have specialist uses for people wanting to measure \c{ipbt}'s
loading speed or test its automatic format detection.

\dt \c{-U}

\dd Treat the input terminal data as being encoded in UTF-8.

\lcont{

If \c{ipbt} has been compiled against the \c{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.

}

\dt \c{--utf8-linedraw}

\dd Permit line drawing using the old ISO 2022 / VT100-style escape
sequences which work by switching the terminal temporarily into a mode
where lower-case Latin letters render as line drawing.

\lcont{

In common with PuTTY, \c{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:

\c lqqqqqk
\c x     x
\c x     x
\c mqqqqqj

then this option might turn them into proper line-drawing boxes.

Applications based on \c{ncurses} can be persuaded not to emit these
sequences in the first place by setting \cq{NCURSES_NO_UTF8_ACS=1} in
the environment.

}

\S{ipbt-manpage-playing} PLAYING

Once \c{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 \cq{q}, or Control-C.

Press \cq{p} or \cq{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 \cq{b} or \cq{<}. To go back by many
frames, type a number followed by \cq{b} or \cq{<}.

To go forward by one frame, press the space bar or \cq{>}. To go
back by many frames, type a number followed by the space bar or
\cq{>}.

To jump to a particular frame number, type the number followed by
\cq{g}. Pressing \cq{g} on its own will jump to the start of the
recording.

Pressing \e{capital} \cq{G} will jump to the \e{end} of the
recording. If you type a number followed by \cq{G}, it will jump to
that many frames \e{before} the end.

To play back the recording at higher speed, type a number followed
by \cq{x}. For example, typing \cq{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 \cq{p} or \cq{s} for that.)

To play back at a \e{lower} speed, type a number followed by
\e{capital} \cq{X}; for example, \cq{3X} will set the player to
one-third normal speed.

To return to normal speed, you can type \cq{1x} or \cq{1X}, or just
\cq{x} or \cq{X}.

If you press \cq{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
\e{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 \cq{x}/\cq{X} scaling feature.

If you press \cq{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 \cq{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 \cq{/} to search forwards
from the current position, or \cq{\\} or \cq{?} to search backwards.
Each of these commands will cause \cw{ipbt} to prompt for a piece of
text to find, and will then search for a frame that contains that
text. Press \cq{n} to search for the same piece of text again in the
same direction.

\S{ipbt-manpage-bugs} BUGS

\c{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 \c{ipbt}

For example, \c{xterm} 256-colour mode is not supported at all.

Also, \c{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 \c{ncursesw} to
do any or all of those things would be welcome!)

\S{ipbt-manpage-licence} LICENCE

\cw{ipbt} is free software, distributed under the MIT licence. Type
\cw{ipbt --licence} to see the full licence text.
