\cfg{man-identity}{ipbt-dump}{1}{2024-04-30}{Simon Tatham}{Simon Tatham}

\H{man-ipbt-dump} Man page for \c{ipbt-dump}

\S{man-ipbt-name} NAME

\c{ipbt-dump} - dump contents of tty recording files

\S{man-ipbt-synopsis} SYNOPSIS

\c ipbt-dump [ options ] file
\e bbbb        iiiiiii   iiii

\S{man-ipbt-description} DESCRIPTION

\c{ipbt-dump} reads a recording of a terminal session in either
\c{ttyrec} or \c{nh-recorder} format, and writes an interpretation of
its contents.

\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.

\c{ipbt-dump} can output the following forms of data:

\b A summary of each \q{frame} in the file (sequence of terminal data
with a particular timestamp), stating its timestamp, location in the
file, and the length of its data.

\b That summary, but also including a hex dump of the terminal data
itself.

\b The raw terminal data on its own, with the timestamps removed, as
if the original terminal session had been recorded by the simpler tool
\cw{script}(\e{1}).

\b An interpretation of what the terminal screen would look like after
each frame. This is generated by processing the terminal data through
PuTTY's terminal emulation code, and outputs in an XML-based format.

\S{man-ipbt-input} INPUT FORMAT

By default, \c{ipbt-dump} will attempt to analyse the input file and
automatically guess whether it is 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-dump} 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-dump} what type of file it is dealing with
using the following options:

\dt \c{-T}

\dd Specify that the input file should be assumed to be in \c{ttyrec}
format.

\dt \c{-N}

\dd Specify that the input file should be assumed to be in
\c{nh-recorder} format.

\dt \c{-R}

\dd Specify that the input file 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.

\S{man-ipbt-output} OUTPUT FORMAT

By default, \c{ipbt-dump} will output a summary format in which each
line contains a colon-separated list of fields:

\b input file name

\b the index of the frame in the file (starting from 0)

\b the timestamp of the frame in seconds, relative to the start of the
recording

\b a description of the location in the file where the terminal data
from that frame can be found, in the form
\q{\cw{offset 0x}\e{NNN}\cw{ len 0x}\e{NNN}}.

You can select different formats using the following options:

\dt \cw{-H} or \cw{--hex-dump}

\dd This format displays the same summary lines as above, but also
includes a hex dump of the terminal data from each frame.

\dt \cw{-x} or \cw{--screen-xml}

\dd This format outputs an XML file describing the appearance of the
terminal screen after each frame's terminal input data has been
processed.

\dt \cw{-S}, or \cw{--script} or \cw{--typescript}

\dd This format outputs just the raw terminal data, with timestamps
removed. The resulting file is identical to the \c{typescript} file
you would have obtained by recording the original session using
\cw{script}(\e{1}).

\S{man-ipbt-options} OPTIONS

This option applies in all modes:

\dt \c{-o} \e{filename}

\dd Write the output to the specified file name. By default the output
is written to \cw{ipbt-dump}'s standard output.

These options configure the terminal emulator used in the XML output mode:

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

\dd Set the width of the emulated terminal to \e{width} columns. By
default it is 80.

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

\dd Set the height of the emulated terminal to \e{height} rows. By
default it is 24.

\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-dump} 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 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.

}

\S{man-ipbt-licence} LICENCE

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