# pyttyplay: a NetHack ttyrec player in Python

If you want to record activity in a terminal, you can store it in a `.ttyrec` format. This is much more efficient than a video, and captures exactly all of the characters and escape events occuring in the terminal. When playing it back, it relies on the ability of your own terminal to recreate the experience.

ttyrec is commonly used to record NetHack games, which may span many hours or days of recording. A more modern alternative is [asciicast], used by asciinema, which although it contains more information, is extremely inefficient due to the storage of everything as UTF-8 encoded JSON strings. ttyrec by itself is very spartan, including nothing but the binary raw terminal characters interspersed with headers denoting the timestamp. Notably missing are things like terminal size, full recording duration, encoding, custom user colourschemes, etc.


=> https://docs.asciinema.org/manual/asciicast/v2/#asciicast-v2 asciicast

There are a number of [existing ttyrec players] out there, but none seem to have all the features I'm looking for, so I wrote another one. Check out the [Github pyttyplay repository] to download and run.


=> https://nethackwiki.com/wiki/Ttyrec existing ttyrec players
=> https://github.com/Moult/pyttyplay Github pyttyplay repository

Here's what it looks like in action:



=> https://thinkmoult.com/assets/pyttyplay-nethack1.png pyttyplay playing a ttyrec of a NetHack game by elenmirie

## Features

* Written in Python. Apparently there's not much out there.
* Is a very small script. Is something broken and you know Python? Look inside.
* Runs in a terminal. While there's a time and a place for a GUI ttyrec player, tiles player (such as customised for DCSS), or web player, it's also really nice to have one in a local terminal.
* Can load from local files or fetch from URLs
* Can load gzipped ttyrec files
* Correctly handles some escape codes such as "repeat last character" and DEC graphics mode toggling that other players don't support. This can result in broken output in other viewers.
* Allows play and pause and shows a graphical timeline of progress.
* Shows stats such as time of recording, elapsed time, and current frame.
* Allows stepping forward and backward frame-by-frame, jump multiple frames, or jump to beginning / end.
* Just to repeat: yes, rewinding is supported!
* Allows toggling of speed multipliers.
* Completely keyboard driven with vi-key bindings.
* Toggle capping of frame durations. Did the person you're watching step out for lunch for an hour? Durations are capped at 1 second.
* Allows frame merging by duration. If each frame includes partially written characters, durations shorter than X can be merged into a single frame.
* Can switch between seeking by frame versus seeking by time.
* Lazy-loading and instant playback. Don't wait for the entire ttyrec to load before playing - start playing immediately and it'll continue to load in the background.
* Allows customisation of terminal size. It automatically fills your current terminal by default, or you can manually specify a size. Smaller sizes will crop.
* Can toggle display of the UI. Want a pure ttyplay experience? You got it.



=> https://thinkmoult.com/assets/pyttyplay-nethack2.png pyttyplay playing a ttyrec of a NetHack game by disperse showing DEC graphics

If you want to try it out on some ttyrecs, you can download NetHack recordings from the [HardFought ttyrec server].


=> https://www.hardfought.org/nethack/ttyrecs/ HardFought ttyrec server

If there are bugs, that's probably because it's something to do with a VT100 command that I don't fully understand. If you want to solve it, you might want to investigate this [list of VT100 escape codes], or [XTerm control sequences] and [ANSI colour codes].


=> https://espterm.github.io/docs/VT100%20escape%20codes.html list of VT100 escape codes
=> https://invisible-island.net/xterm/ctlseqs/ctlseqs.html XTerm control sequences
=> https://en.wikipedia.org/wiki/ANSI_escape_code#Colors ANSI colour codes