Replay Terminal Transcripts with scriptreplay

scriptreplay plays a recorded terminal session back at its original pace, or faster, without ever running the commands inside it. 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 examples use /usr/bin/scriptreplay directly.

Allow about fifteen minutes. You need script and scriptreplay, a timing file, and the matching terminal-output file. The whole workflow is read-only after recording. Do not replay untrusted terminal output in a terminal where escape sequences could change its state or trigger an action.

1. Confirm the binary and version

Check which executable you will use before you trust its options. This is an ordinary, read-only check and needs no 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

2. Record a small transcript

script creates the two files 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

Exact owner, permissions and sizes vary. The timing file holds delays and byte counts; the output file holds what the session actually wrote. Keep the pair together: renaming or editing only one of them produces a misleading replay.

This example uses --command to make the recording short and deterministic. For an interactive recording, run script --log-timing session.tm --log-out session.out, use the shell normally, then type exit. Recording a real command can change state, so use a disposable directory and read 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, the output file second. Redirect the replay to a new file when you want to inspect it without sending control characters to your own 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. Omit it and scriptreplay looks for a file literally named typescript, which is easy to miss when a recording used a descriptive name instead: use --log-out explicitly in scripts and notes.

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 it 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 content, not elapsed time, and should report no differences: only the timing changes, never the bytes. A long pause in the recording? --maxdelay caps the gap between updates without touching 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 the recording was meant to demonstrate.

5. Inspect an advanced multi-stream recording

For a recording made with script --logging-format advanced, use --summary to view session details and exit without replaying anything:

$ /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

Timestamp, duration and paths are host-specific. A classic timing file does not carry the advanced metadata that --summary needs, so an empty or unhelpful summary there is not evidence that an ordinary replay is broken elsewhere.

Advanced logs can hold several streams. Select one explicitly when you want terminal output only:

$ /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. out is the normal choice for terminal output, and picking a stream matters most with a combined input-and-output log.

6. Diagnose the common mistakes

A cannot-open-file error means checking 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 two different recordings is a file-selection problem: recreate the pair or correct the paths before reaching for elevated privileges. sudo does not repair mismatched logs, and it can make the resulting files harder to inspect as your normal user afterwards.

If the replay looks visually wrong, remember the manual's terminal boundary: a recording is only guaranteed to behave properly on the same type of terminal that recorded it. Control sequences can 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 for scriptreplay. It does not alter the original logs or any persistent configuration. The commands above only create new files; if they are disposable, remove just the directory named by workdir after checking its value, and avoid a broad wildcard.