Skip to main content

Gitea x Asciicast | Recording and viewing terminal sessions on Gitea

· 5 min read
sillyguodong
Gitea maintainer
delvh
Gitea maintainer
jolheiser
Gitea maintainer

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.

run asciinema

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:

recording end

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

The following GIF shows the recording process.

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:

push remote

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:

view source code of the video

Viewing render:

view rendered asciicast video

Start playing it:

play asciicast video

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:

copy and paste

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! 🎥

An icon showing wave propagation

Join our community

Gitea is open source. Star our GitHub repo, and join our community on Discord!

An icon showing a paper plane

Subscribe to our newsletter

Stay up to date with all things Gitea