Record terminal sessions and replay them on Gitea

content/post/record-terminal-sessions-and-replay-them-on-gitea.md

@@ -0,0 +1,176 @@
+---
+date: "2023-04-03T10:00:00+08:00"
+author: "sillyguodong"
+title: "Record terminal sessions and replay them on Gitea"
+tags: []
+draft: false
+---
+Gitea 1.19.0 includes a new feature called Asciicast support.
+Maybe this is the first time you've heared of `Asciicast`.
+This blog will explain some details about Asciicast, including how to use it on Gitea.
+
+## What is asciicast
+
+As programmers, we works with terminals and command lines day by day. 
+Sometimes we encounter unfamilar command lines.
+And sometimes wo need to organize the valuable command lines to share with our partners.
+In general, we record it in text. But have you ever thought about or tired to record them on video?
+Asciicast format file can help us do it. It even offers other awesome features.
+
+
+Asciicast is a kind of file format which help us to record terminal session.
+Asciicast files follow the [newline-delimited JSON](https://jsonlines.org/) file specification.
+Suggested file extension is `.cast`.
+
+There is a example of the `.cast` source file:
+
+```json
+{"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 **header**. It is a JSON-encoded object which contains recording meta-data.
+  In meta-data, in addition to the required attributes which contains `version`, `width` and `height`, there are also optional attributes such as `timestamp`, `env`, `theme` and so on.
+- Each of the remaining lines represents an evnt. All of events form an event stream. 
+  An event is a JSON array which has three elements, like below:
+  ```json
+  [time, evnt-type, event-data]
+  ```
+  - `time`: float type, represented as the number of seconds since the beginning of the recording session.
+  - `event-type`: string type, one of: `"o"`, `"i"`. `"o"` represents printing new data to terminal's stdout. And `"i"` represents prints character(s) typed in by the user.
+  - `event-data`: event specific data, described separately for each event type.
+
+### Notes
+- The latest version of asciicast file is version 2 which sloves several problems that couldn't be easily fixed in the old verison.
+  The introduction to acsiicast above is also based on version 2.
+- For more on asciicast, see the [introduction](https://github.com/asciinema/asciinema/blob/develop/doc/asciicast-v2.md).
+
+## Welcome to asciinema
+
+After reading this, I believe you already have a general understanding of asciicast.
+Then here comes the question again, how do we obtain a asciicast file?
+
+[![asciicast](https://asciinema.org/a/335480.png)](https://asciinema.org/a/335480?autoplay=1)
+
+Look, when we click on the image above, we are redirected to a website where we automatically play a video of a terminal session!
+
+Welcome to asciinema!
+
+[Asciiema](https://github.com/asciinema/asciinema) is a open source software which lets you easily record terminal and replay them in a terminal as well as in a web browser.
+The video is stored in asciicast format.
+
+In short, a quote from Github:
+> Terminal session recorder and the best companion of asciinema.org.
+
+### Features
+- Simple recording
+- Copy & paste
+- Embedding
+
+## How to install
+
+### Install on macOS
+**Homebrew**
+```shell
+brew install asciinema
+```
+
+**MacPorts**
+```shell
+sudo port selfupdate && sudo port install asciinema
+```
+
+### Install on Linux
+**Ubuntu**
+```shell
+sudo apt-add-repository ppa:zanchey/asciinema
+sudo apt-get update
+sudo apt-get install asciinema
+```
+
+**Debian**
+```shell
+sudo apt-get install asciinema
+```
+
+If you use other operating system, you can refer to this [document](https://asciinema.org/docs/installation).
+
+However, as far as I know, asciinema does not currently support windows and has no plans to support windows.
+If you are a windows user, you can refer to this [article](https://www.windowscentral.com/how-install-wsl2-windows-10), but I haven't actually tested it, hope it helps.
+
+## How to use
+### Record terminal session
+ ```shell
+ asciinema rec [filename]
+ ```
+By running `asciinema rec [filename]` you start a new recording session. 
+
+![run asciinema](/demos/asciicast/rec-start.jpg)
+
+It tells you where the asciicast is going to be stored (If you don't specify a file name. Otherwise it will be saved in the current path with the file name you specified
+) and how do you exit (type `exit` or `Ctrl + D`).
+
+You can temporarily pause the capture of your terminal by pressing `Ctrl + \`.
+
+After exit:
+
+![run asciinema](/demos/asciicast/rec-end.jpg)
+
+It will let you choose whether to upload asciicast to asciinema.org or save it locally.
+If you choose upload to asciinema.org when exiting. 
+It will return a URL:
+
+![run asciinema](/demos/asciicast/rec-upload.jpg)
+
+View in a browser：
+
+![run asciinema](/demos/asciicast/rec-upload-url.jpg)
+
+Asciinema terminal recorder uses asciinema.org as its default host for the recordings. It's free, public service (all uploaded recordings are private by default though).
+
+If you're not comfortable with uploading your terminal sessions to asciinema.org, or your company's policy prevents you from doing that, you can set up your own instance for private use. See the server install [guide](https://github.com/asciinema/asciinema-server/wiki/Installation-guide).
+
+### Replay recorded asciicast in a terminal.
+
+Playing from a local file:
+
+```shell
+asciinema play <path/to/asciicast.cat>
+```
+
+If you choose upload to asciinema.org when exiting, it also can play from a HTTP(s) URL:
+
+```shell
+asciinema play https://asciinema.org/a/335480.cast
+```
+
+Since we have the way of recording and replaying, let’s generate our fisrt asciicast file!
+
+
+[![asciicast](https://asciinema.org/a/573225.png)](https://asciinema.org/a/573225?autoplay=1)
+
+## Asciicast on Gitea
+[@wolfogre](https://github.com/wolfogre) make it possibile to view uploaded Asciicast (`.cast`) files on Gitea by using asciinema's standalone web player - [`asciinema-player`](https://github.com/asciinema/asciinema-player#asciinema-player).
+
+After uploading a asciicast file to your gitea repository, you can choose view `source` or view `render`.
+
+If view `source`:
+
+![view source](/demos/asciicast/view-source.jpg)
+
+if View `render`:
+
+![view render](/demos/asciicast/view-render.jpg)
+
+Start playing it:
+
+![play video](/demos/asciicast/play.gif)
+
+One of the key features of asciicast videos is that the text contained in it can be selected.
+So you can copy and paste the text from it:
+
+![copy and paste](/demos/asciicast/copy-and-paste.gif)
+