Gitea x Asciicast | Recording and viewing terminal sessions on Gitea

As of 1.19.0, Gitea supports asciicast! Maybe this is the first time you've heard of asciicast. This blog will teach you how to use asciicast, and how it relates to Gitea.

What is asciicast?​

As programmers, we often work with terminals and the command line. Sometimes, we encounter unfamiliar commands. Othertimes, the output of commands is not what we expect. In both these cases, we need to show someone else what we did and what the output is. Most often, we would record this in a text format. But have you ever thought about recording it on video? An asciicast file is exactly that: A text-based recording of a terminal session. It even offers some additional awesome features we'll go over below.

asciicast files typically have the file extension .cast and follow the newline-delimited JSON file specification.

Here is an example of a .cast file:

{"version": 2, "width": 255, "height": 69, "timestamp": 1680420731, "env": {"SHELL": "/bin/zsh", "TERM": "xterm-256color"}}
[0.110535, "o", "\u001b[1m\u001b[7m%\u001b[27m\u001b[1m\u001b[0m                                                                                                                                                                                                                                                              \r \r\u001b]2;gedong@chifangongju:~/Downloads\u0007\u001b]1;~/Downloads\u0007"]
[0.133176, "o", "\r\u001b[0m\u001b[27m\u001b[24m\u001b[J\u001b[01;32m➜  \u001b[36mDownloads\u001b[00m \u001b[K"]
[0.133293, "o", "\u001b[?1h\u001b=\u001b[?2004h"]
[3.419088, "o", "\u001b[?2004l\r\r\n"]

• The first line is usually called the header. It is a JSON-encoded object which contains recording meta-data. In this meta-data, in addition to the required attributes version, width and height, there are also optional attributes such as timestamp, env, theme and so on.
• Each of the remaining lines represents an event. All of the events together form an event stream of the entire recording. An event is a JSON array which has three elements, like below:

  [time, event-type, event-data]
  
  • time: float, the number of seconds since the recording has begun.
  • event-type: string, one of "o" or "i".
    • "o" represents new data printed to stdout (output).
    • "i" represents character(s) typed in by the user (input).
  • event-data: event specific data, described separately for each event type.

Notes​

• The latest version of asciicast files is version 2, which solves several problems that couldn't be easily fixed. This introduction to acsiicast is also based on version 2.
• version 1 should not be used anymore, and is also not supported by Gitea. The reason for that is especially that version 1 didn't specify a file extension, so any file could be an asciicast file.
• For more information on asciicast, see their introduction.

Asciicast on Gitea​

You should have a general understanding of asciicast now. But how do we obtain an asciicast file and how do we use it in conjunction with Gitea? Both questions will be answered below.

Asciinema is an open source software which lets you easily record your terminal and replay the recordings in a terminal as well as in the web browser.

Install Asciinema​

Installing Asciinema is our first step. The asciinema installation docs describe how to install it depending on which platform you are using.

As of the time of this post, asciinema does not support windows terminals.

Prepare your repository​

This is my demo repository that I'm going to use on gitea.com, which I have cloned locally.

Recording a terminal session​

From the root of the project:

asciinema rec $FILENAME.cast

This will start a new recording.

As you can hopefully see, asciinema tells you where the recording will be stored (if you don't specify a file name. Otherwise it will be saved at the specified path) and how to stop the recording (type exit or Ctrl-D).

You can temporarily pause the recording by pressing Ctrl-\.

After exiting:

asciinema tells you that recording has finished and was stored successfully.

The following GIF shows the recording process.

hello_asciicast.cast is generated in the root path of the local repository.

Push asciicast file to remote reposirtory​

git add .
git commit -m "add a cast file"
git push

Now we can see the file in the remote repository:

Asciicast on Gitea​

After uploading an asciicast file to your Gitea repository, you can choose to view the source or you can view the rendered video.

Viewing source:

Viewing render:

Start playing it:

One of the key benefits of asciicast videos is that the text contained in it can be selected. So, you can for example copy and paste the text from it:

Embed in markdown​

At the moment, an asciicast file can only be embedded implicitly into Markdown by adding something like the following construct:

[![session recording](/demos/asciicast/hello_asciicast_pic.png)](/src/branch/main/hello_asciicast.cast)

We highly recommend that you use Markdown and Asciicast on Gitea to build your work and study notes. This is for example what's happening in the README file of the asciicast demo repository. Not only is this more visual than code blocks, but the content is also replicable.

This is a pseudo embedding achieved by displaying an image of the recording that links to the recording when clicked on.

Perhaps it will be possible in the future to embed an asciicast file directly into Markdown. For now, this is as close as it gets. Still, have fun recording and viewing asciicast files! 🎥