Replay a Recorded Terminal Session with scriptreplay

You will finish with a repeatable way to replay a terminal transcript at its recorded pace, speed it up for a quick review, and inspect the metadata in an advanced log. The examples use the Debian or Ubuntu bsdutils package installed here as util-linux 2.39.3. The command found first in this shell's PATH is a separate util-linux 2.42.4 build, so the reproducible package examples use /usr/bin/scriptreplay.

Allow about fifteen minutes. You need script and scriptreplay, a timing file, and the corresponding terminal-output file. The workflow is read-only after recording: replaying a transcript does not run the commands it contains. Do not replay untrusted terminal output in a terminal where escape sequences could change state or trigger an action.

1. Confirm the binary and version

Check which executable you will use before interpreting its options. This is an ordinary, read-only check and does not need elevated privileges:

$ command -v scriptreplay
/home/linuxbrew/.linuxbrew/bin/scriptreplay
$ /usr/bin/scriptreplay --version
scriptreplay from util-linux 2.39.3
$ dpkg-query -W -f='${Package} ${Version}\n' bsdutils
bsdutils 1:2.39.3-9ubuntu6.6

Checkpoint: if command -v points somewhere other than /usr/bin/scriptreplay, use the absolute path in this guide or check that other build's version and manual. Do not combine the timing format from one installation with assumptions about another.

2. Record a small transcript

script creates the two files that the replay needs: a terminal-output log and a timing log. Use a fresh directory so an old transcript cannot be mistaken for the new one:

$ workdir="$(mktemp -d)"
$ /usr/bin/script --quiet --return --command '/usr/bin/printf "replay-me\n"' \
    --log-out "$workdir/session.out" \
    --log-timing "$workdir/session.tm"
replay-me
$ ls -l "$workdir/session.out" "$workdir/session.tm"
-rw------- 1 you you ... session.out
-rw------- 1 you you ... session.tm

The exact owner, permissions and file sizes vary. The timing file contains delays and byte counts; the output file contains what the terminal session wrote. Keep the pair together. Renaming or editing only one of them can produce a misleading replay.

This example uses --command to make the recording short and deterministic. In an interactive recording, run script --log-timing session.tm --log-out session.out, use the shell normally, then type exit. Recording a command can change state, so use a disposable directory and inspect the command before pressing Return. No sudo is needed for files in a directory you own.

3. Replay the output at its recorded pace

Pass the timing file first and the output file second. Redirect the replay to a new file when you want to inspect it without sending control characters to your terminal:

$ /usr/bin/scriptreplay --timing "$workdir/session.tm" \
    --log-out "$workdir/session.out" > "$workdir/replayed.txt"
$ grep -a -F 'replay-me' "$workdir/replayed.txt"
replay-me

The second argument is the recorded output. If you omit it, scriptreplay looks for a file named typescript. That default is easy to miss when a recording used a descriptive name, so use --log-out explicitly in scripts and notes.

Checkpoint: a successful replay displays the saved bytes and exits successfully; it does not start a shell, repeat printf, or re-run any command that appeared in the transcript. Treat the output as data. A transcript that contains shell escape sequences can still be interpreted by your terminal, which is why redirecting to a file is the safer first test.

4. Change the playback speed

Use --divisor when the original delays are inconvenient. A divisor of 2 halves the waits and plays at twice the recorded speed. A divisor of 0.1 makes the replay ten times slower:

$ /usr/bin/scriptreplay --timing "$workdir/session.tm" \
    --log-out "$workdir/session.out" --divisor 2 > "$workdir/fast.txt"
$ cmp "$workdir/replayed.txt" "$workdir/fast.txt"
$ echo "output bytes are identical"
output bytes are identical

cmp checks the content, not the elapsed time. It should report no differences. The timing changes only when bytes are displayed. If a recording contains a long pause, --maxdelay caps the delay between updates without changing the saved output:

$ /usr/bin/scriptreplay --timing "$workdir/session.tm" \
    --log-out "$workdir/session.out" --maxdelay 1 > "$workdir/capped.txt"

The value for --maxdelay is a floating-point number of seconds. Choose a cap deliberately: removing pauses can hide the rhythm or ordering that the recording was meant to demonstrate.

5. Inspect an advanced multi-stream recording

For recordings made with script --logging-format advanced, use --summary to view session details and exit without replaying the transcript:

$ /usr/bin/script --quiet --return --logging-format advanced \
    --command '/usr/bin/printf "replay-me\n"' \
    --log-out "$workdir/session.io" \
    --log-timing "$workdir/advanced.tm"
replay-me
$ /usr/bin/scriptreplay --summary --timing "$workdir/advanced.tm"
START_TIME:  ...
     SHELL:  /bin/bash
   COMMAND:  /usr/bin/printf "replay-me\n"
TIMING_LOG:  .../advanced.tm
OUTPUT_LOG:  .../session.io
  DURATION:  ...
 EXIT_CODE:  0

The timestamp, duration and paths are host-specific. A classic timing file does not contain the advanced metadata required by --summary, so an empty or unhelpful summary is not evidence that the ordinary replay is broken.

Advanced logs can contain several streams. Select one explicitly when you need only terminal output:

$ /usr/bin/scriptreplay --timing "$workdir/advanced.tm" \
    --log-io "$workdir/session.io" --stream out > "$workdir/output-only.txt"
$ grep -a -F 'replay-me' "$workdir/output-only.txt"
replay-me

The supported stream names are in, out, signal and info. The out stream is the normal choice for terminal output; selecting a stream is particularly useful with a combined input-and-output log.

6. Diagnose the common mistakes

If the command says it cannot open a file, check both paths without changing anything:

$ test -r "$workdir/session.tm" && echo timing-readable
timing-readable
$ test -r "$workdir/session.out" && echo output-readable
output-readable

A missing timing file, a missing output file, or a pair from different recordings is a file-selection problem. Recreate the pair or correct the paths before trying elevated privileges. sudo does not repair mismatched logs and can make the resulting files harder to inspect as your normal user.

If the replay looks visually wrong, remember the manual's terminal boundary: the recording is only guaranteed to behave properly on the same type of terminal that recorded it. Terminal control sequences may be interpreted differently elsewhere. Redirect to a file, inspect it with tools such as od or grep -a, and only then replay it interactively.

There is no undo operation for scriptreplay. It does not alter the original logs or persistent configuration. The commands above create new files; if they are disposable, remove only the directory named by workdir after checking its value, and do not use a broad wildcard.