一款能对 Linux 终端的操作步骤进行记录的工具——Asciinema

前面有提及到 TTYREC 这款同样能录制终端操作步骤的工具，但是在将其录制的步骤文件转换成 GIF 动态图片的时候就遇到一些难题。

想着准备在前几篇有关于命令行浏览图片的文章中附上图片的，眼看着无法转成动图为此就在一顿搜索中找到另外一款也能录制操作步骤的软件。这不又给接触到一款唤作 asciinema 的软件亦能同样的实现录制功能，但是在录制好操作之后的转图步骤又是遇到困难，因为其转换用到的 asciicast2gif 安装有些繁杂。当时提及到的新用到的 agg 也短时间之内还不会安装，这不拖延到此刻学会安装 agg 后才提上日程。

Asciinema

Asciinema简介

asciinema （也称为 asciinema CLI 或 asciinema recorder）是一种用于录制和实时流式传输终端会话的命令行工具。

Asciinema支持的系统

  • GNU/Linux
  • macOS
  • FreeBSD

Asciinema的显著特点

  • 将终端会话记录到文件中，可选 键盘输入捕获 和可配置的环境变量捕获，
  • 在终端内回放录音，可调节速度，循环播放，空闲时间限制，逐步导航，在 标记 处暂停 ，以及可选的终端自动调整大小，
  • 当地和远程 直播 将终端会议实时传输给多个观众，包括一个内置的HTTP服务器和一个嵌入式网络播放器，用于局域网/本地主机的观看，
  • 组合会话:在本地和远程同步流媒体的同时记录到文件，
  • 轻量级 asciicast 记录格式 ，高度可压缩（平均占原始大小的 8%）
  • 从asciicast v1/v2/v3转换到asciicast V2/v3，原始终端输出，或纯文本，
  • 将多个录音串联成一个，并自动调整时间，
  • 中期控制：通过 自定义键绑定 ，
  • 会话元数据捕获，包括终端大小、终端主题、命令和标题，
  • 配置文件支持默认设置，如录制命令、捕获选项、播放速度、空闲时间限制、通知和键绑定，
  • 无头模式、可配置终端窗口大小和退出状态传播，用于脚本化和CI友好的录制和流媒体，
  • 支持从本地文件、stdin或HTTP（S）URL转换和播放stdin/stdout，
  • 与 asciinema 服务器 集成，例如 asciinema.org ，用于上传、托管、远程直播、自托管服务器、可见性控制、描述和同步音频 URL。

Asciinema的安装

编译安装

从源代码构建 asciinema 需要 Rust 编译器（1.82或更高版本），以及 Cargo 包管理器 。如果它们无法通过您的系统软件包管理器获取，那么请使用 rustup 。

cargo install --locked --git https://github.com/asciinema/asciinema

然后，确保 $HOME/.cargo/bin 在 shell 的环境变量 $PATH里。

或者在 github 中下载源代码并使用以下方法构建 asciinema 二进制文件：

git clone https://github.com/asciinema/asciinema
cd asciinema
cargo build --release

编译生成的二进制文件保存在target/release/asciinema，将其复制到对应的目录即可。

需要生成帮助页面以及自动补全命令文件，需要设置ASCIINEMA_GEN_DIR参数到工作目录，例如：

ASCIINEMA_GEN_DIR=/foo cargo build --release

生成的帮助页保存在/foo/man/文件夹，自动补全命令文件保存在/foo/completion/文件夹。

二进制

对于大多数系统都可以从 Github 发布页下载已经编译好的二进制文件即可，在下载之时需要针对具体的架构下载安装，例如：

wget https://github.com/asciinema/asciinema/releases/download/v3.2.0/asciinema-x86_64-unknown-linux-musl
cp asciinema-x86_64-unknown-linux-musl /usr/local/bin/asciinema
chmod +x /usr/local/bin/asciinema

查看版本：

root@ChiuYut-VM:~# asciinema --version
asciinema 3.2.0

apt (Debian, Ubuntu)

对于 Debian 12 系统我在安装时直接使用 APT 源直接安装，以节省不少的等待时间。执行下列命令安装：

apt install asciinema

查看版本：

root@ChiuYut-VM:~# asciinema --version
asciinema 2.2.0

pacman (Arch, Manjaro)

pacman -S asciinema

homebrew (macOS)

brew install asciinema

pipx (asciinema 2.4 only)

pipx install asciinema

Asciinema的使用

  1. 录制步骤

    开始录制：

    asciinema rec [fileName]

    asciinema 记录命令，文件名参数是可选的。
    当输入文件名时，退出录制时将保存记录文件至本地，否则，退出录制时会提醒选择上传至asciinema.org或保存至本地。

    2. 退出录制：

    输入exit停止录制：

    asciinema: recording finished
asciinema: asciicast saved to demo.cast
  2. 播放录制记录

    播放本地文件：

    asciinema play demo.cast

    播放远程文件：

    asciinema play https://asciinema.org/a/g1eWSxcE9I9e2dhK
  3. 打印录制记录

    一次性打印整个文件的记录结果至终端。

    asciinema cat demo.cast
  4. 上传记录

    上传录制好的文件至asciinema.org， 然后就可以在asciinema.org上维护录制记录，便于观看和分享。

    asciinema upload [fileName]
  5. 要通过内置HTTP服务器流式传输会话，请运行以下命令: 
    asciinema stream -l
  6. 要通过中继（asciinema服务器）流式传输会话，请运行: 
    asciinema stream -r

Agg

Agg的简介

agg是asciicast2gif的后继者，一个命令行工具，用于从终端会话记录生成动画 GIF 文件。

Agg的显著特点

  • 将 asciicast 记录（v1、v2、v3）转换为动画GIF文件，
  • 来自本地文件、标准输入或HTTP（S）URL（例如 asciinema.org 录制链接）的输入，
  • 通过gifski编码器，
  • 多个内置颜色主题（asciinema, dracula, monokai, github-dark, github-light, kanagawa, nord, solarized-dark, solarized-light, gruvbox-dark等）
  • 自定义临时主题指定为十六进制颜色三叉戟，
  • 在存在时自动使用录音的嵌入式主题，
  • 可配置字体家族具有合理的跨平台默认值和符号的隐式后备，
  • 可配置字体大小和线条高度，
  • 通过以下方式支持额外的字体目录--font-dir对于标准系统位置之外的字体，
  • 彩色表情渲染，支持Apple Color Emoji、Noto Color Emoji和其他常见表情字体，
  • 两个可选择的渲染后端:swash（默认）和resvg,
  • 可调播放速度，
  • 闲置时间限制跳过不活动的时间段，
  • 循环或单通道播放，
  • 可配置FPS上限和最后帧持续时间，
  • 终端尺寸覆盖（col/rows），用于在不同的几何图形上重新渲染。

Agg的安装

源码安装

从源代码构建需要 Rust 编译器（1.85.0或更高版本）和 Cargo 软件包管理器，可以使用 rustup 安装.

要下载源代码，构建AGG二进制并将其安装在$HOME/.cargo/bin运行:

cargo install --git https://github.com/asciinema/agg

需要确保$HOME/.cargo/bin在 shell 的环境变量$PATH里。

或者，手动从 Github 下载源代码并使用以下方法构建AGG二进制：

git clone https://github.com/asciinema/agg
cd agg
cargo build --release

生成一个可执行文件 （--release）在target/release/agg里， 将二进制复制到对应目录即可。

二进制

对于大多数系统都可以从 Github 发布页下载已经编译好的二进制文件即可，在下载之时需要针对具体的架构下载安装，例如：

wget https://github.com/asciinema/agg/releases/download/v1.8.1/agg-x86_64-unknown-linux-musl
mv agg-x86_64-unknown-linux-musl /usr/local/bin/agg
chmod +x /usr/local/bin/agg

查看版本：

root@ChiuYut-VM:~# agg --version
agg 1.8.1

Agg的使用

转换就简单许多了，简单的只需执行：

agg <INPUT_FILENAME_OR_URL> <OUTPUT_FILENAME>

至于特殊需求就需要通过不同的配置参数实现了。

root@ChiuYut-VM:~# agg --help
asciinema gif generator

Usage: agg [OPTIONS] <INPUT_FILENAME_OR_URL> <OUTPUT_FILENAME>

Arguments:
  <INPUT_FILENAME_OR_URL>  asciicast path/filename or URL
  <OUTPUT_FILENAME>        GIF path/filename

Options:
      --text-font-family <TEXT_FONT_FAMILY>
          Specify regular text font families [default: "JetBrains Mono,Fira Code,SF Mono,Menlo,Consolas,DejaVu Sans Mono,Liberation Mono"]
      --emoji-font-family <EMOJI_FONT_FAMILY>
          Specify emoji font families [default: "Apple Color Emoji,Segoe UI Emoji,Noto Color Emoji,JoyPixels,Twemoji,Noto Emoji"]
      --font-family <FONT_FAMILY>
          Specify the complete font family list, bypassing automatic fallbacks; must start with a monospace text font
      --font-size <FONT_SIZE>
          Specify font size (in pixels) [default: 16]
      --font-dir <FONT_DIR>
          Use additional font directory; may be specified multiple times
      --line-height <LINE_HEIGHT>
          Specify line height [default: 1.4]
      --theme <THEME>
          Select color theme [possible values: asciinema, dracula, github-dark, github-light, kanagawa, kanagawa-dragon, kanagawa-light, monokai, nord, solarized-dark, solarized-light, gruvbox-dark, custom]
      --bold-is-bright
          Render bold text with bright colors (ANSI 0..7 → 8..15)
      --speed <SPEED>
          Adjust playback speed [default: 1]
      --no-loop
          Disable animation loop
      --idle-time-limit <IDLE_TIME_LIMIT>
          Limit idle time to max number of seconds [default: 5]
      --fps-cap <FPS_CAP>
          Set FPS cap [default: 30]
      --last-frame-duration <LAST_FRAME_DURATION>
          Set last frame duration [default: 3]
      --cols <COLS>
          Override terminal width (number of columns)
      --rows <ROWS>
          Override terminal height (number of rows)
      --renderer <RENDERER>
          Select frame rendering backend [default: swash] [possible values: swash, resvg]
  -v, --verbose...
          Enable verbose logging
  -q, --quiet
          Quiet mode - suppress diagnostic messages and progress bars
  -h, --help
          Print help
  -V, --version
          Print version

agg的使用

参考

  • asciinemahttps://asciinema.org/
  • Terminal session recorder, streamer and player 📹https://github.com/asciinema/asciinema
  • asciinema gif generatorhttps://github.com/asciinema/agg
  • asciinema docshttps://docs.asciinema.org/getting-started/
  • agg – asciinema gif generator¶https://docs.asciinema.org/manual/agg/
  • https://asciinema.org/a/g1eWSxcE9I9e2dhK

ChiuYut

2026年05月10日

发布者

ChiuYut

咦？我是谁？这是什么地方？ Ya ha！我是ChiuYut！这里是我的小破站！