ipbt-dump(1)

NAME

ipbt-dump - dump contents of tty recording files

SYNOPSIS

ipbt-dump [ options ] file

DESCRIPTION

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

ttyrec and 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. ttyrec and nh-recorder produce differently formatted files, but the principle is very similar.

ipbt-dump can output the following forms of data:

•   A summary of each `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.

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

•   The raw terminal data on its own, with the timestamps removed, as if the original terminal session had been recorded by the simpler tool script(1).

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

INPUT FORMAT

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

-T  Specify that the input file should be assumed to be in ttyrec format.

-N  Specify that the input file should be assumed to be in nh-recorder format.

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

OUTPUT FORMAT

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

•   input file name

•   the index of the frame in the file (starting from 0)

•   the timestamp of the frame in seconds, relative to the start of the recording

•   a description of the location in the file where the terminal data from that frame can be found, in the form `offset 0xNNN len 0xNNN'.

You can select different formats using the following options:

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

-x or --screen-xml
    This format outputs an XML file describing the appearance of the terminal screen after each frame's terminal input data has been processed.

-S, or --script or --typescript
    This format outputs just the raw terminal data, with timestamps removed. The resulting file is identical to the typescript file you would have obtained by recording the original session using script(1).

OPTIONS

This option applies in all modes:

-o filename
    Write the output to the specified file name. By default the output is written to ipbt-dump's standard output.

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

-w width
    Set the width of the emulated terminal to width columns. By default it is 80.

-h height
    Set the height of the emulated terminal to height rows. By default it is 24.

--utf8-linedraw
    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.

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

    lqqqqqk
    x     x
    x     x
    mqqqqqj

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

LICENCE

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