asciinema - Запись и воспроизведение терминальных сессий в Linux

Asciinema - инструмент для записи терминальных сессий и их воспроизведения с максимальной точностью. Он идеален для документирования процессов, создания обучающих материалов, сохранения истории или отладки.

Немного про Asciinema

Asciinema - это ПО с открытым исходным кодом для записи и воспроизведения терминальных сессий: в отличие от видео, она сохраняет ввод/вывод терминала как текстовые данные (JSON-формат), благодаря чему запись занимает мало места, остаётся чёткой при любом масштабе, а записанный текст можно копировать; готовые записи можно воспроизводить локально в терминале или встраивать/делиться через веб (asciinema.org или свой сервер).

Когда я впервые узнал про этот софт, я, честно сказать, был поражён. Магия простого текста в чистом виде.

Вводные данные

В статье использовались следующие версии ПО:

Демо

Чтобы вы сразу поняли, о чём речь - ниже пара демонстрационных записей терминала, выполненных с помощью Asciinema.

Установка Asciinema

Самый быстрый способ - скачать готовый бинарник последней версии:

mkdir -vp ~/.local/bin

curl -Lo ~/.local/bin/asciinema \
  https://github.com/asciinema/asciinema/releases/latest/download/asciinema-x86_64-unknown-linux-gnu

chmod +x ~/.local/bin/asciinema

Проверяем версию:

asciinema --version

Запись сессии

Базовая запись сессии выглядит так:

asciinema rec ./demo.cast

После выполнения команды терминал переходит в режим записи. Вы видите приглашение системы, печатаете команды, смотрите результаты - всё это записывается. Когда вы закончили, нажимаете Ctrl+D или вводите exit, и запись сохраняется в файл demo.cast.

Если вы хотите дополнить запись или начать её заново - используйте параметры --append и --overwrite (или просто удалите файл).

asciinema rec ./demo.cast --overwrite

Воспроизведение

Для просмотра записи прямо в терминале используйте команду:

asciinema play ./demo.cast

Запись будет воспроизведена с теми же временными интервалами, что и при записи. Это удобно для проверки, что всё записалось корректно, или для просмотра на машине без браузера.

Если вам нужно ускорить воспроизведение (например, если запись заняла 10 минут, но вы хотите посмотреть за минуту), используйте флаг --speed:

asciinema play --speed 2 ./demo.cast

Здесь 2 означает двойную скорость. Можно использовать значения вроде 0.5, 1.5, 3.

Полезные опции

Когда вы записываете сессию, доступны флаги, которые могут быть полезны:

• --title "Название" - устанавливает название сессии, которое потом видно при воспроизведении;
• --cols 100 --rows 30 - задаёт размер терминала для записи;
• --command /bin/bash - явно указывает, какой shell использовать для записи;
• --env TERM=xterm-256color - используется для указания, какие переменные окружения сохранить в метаданные записи;
• --stdin - включает запись ввода с клавиатуры (по умолчанию записывается только вывод).

Пример полноценной записи с параметрами:

asciinema rec --title "Nginx setup" --cols 120 --rows 30 ./nginx.cast

Работа с временем

Иногда в записи есть моменты, где вы долго печатали или ждали ответа сервера, и это удлиняет демонстрацию для зрителя. Asciinema позволяет редактировать эти задержки.

Файл .cast - это простой текстовый JSON-подобный формат. Каждая строка содержит информацию о временной метке, типе события и данных. Если вы откроете файл в редакторе, вы увидите что-то вроде:

[0.0, "o", "$ "]
[0.5, "o", "echo hello"]
[0.1, "o", "\r\n"]
[1.2, "o", "hello\r\n"]

Первое число - это временной интервал в секундах от предыдущего события. Если вы видите [5.0, ...] и знаете, что это задержка, которую можно сократить, вы можете отредактировать это число вручную.

Но правильнее всего использовать параметр --idle-time-limit. Его можно использовать как при проигрывании (play), так и при записи (rec). Смысл его в том, чтобы длительные “паузы” во время сессии - длительные простои терминала - не записывать и не воспроизводить. Например, если в записанной сессии есть момент ожидания завершения длительного процесса без вывода в терминал, допустим, в течение 2 минут, то при указании --idle-time-limit 2 этот момент сократится до 2 секунд. Очень удобно на мой взгляд.

Конвертирование cast-файлов в GIF и MP4

Asciinema хороша для встраивания в веб-сайты, но иногда может потребоваться более универсальный формат - например, GIF или MP4. Тут ребята из Asciinema уже позаботились об этом, написав консольную утилиту agg (asciinema gif/mp4 generator).

Установка agg

agg написана на Rust, и самый простой способ установки - аналогично Asciinema:

curl -Lo ~/.local/bin/agg \
  https://github.com/asciinema/agg/releases/latest/download/agg-x86_64-unknown-linux-gnu

chmod +x ~/.local/bin/agg

После установки agg проверяем:

agg --version

Создание GIF

Самое частое применение agg - конвертирование .cast-файла в анимированный GIF:

agg ./demo.cast ./demo.gif

Готово. Размер GIF обычно больше, чем .cast-файл, но намного меньше видео того же качества.

Если запись слишком долгая и GIF получился громоздким, можно ускорить воспроизведение:

agg --speed 2 ./demo.cast ./demo.gif

Флаг --speed 2 означает двойную скорость, как мы видели в Asciinema.

Создание MP4

Если вам нужно видео в формате MP4, agg тоже справляется:

agg ./demo.cast ./demo.mp4

Полезные опции agg

agg поддерживает множество параметров для управления выводом:

• --speed N - множитель скорости воспроизведения (по умолчанию 1);
• --theme "solarized-dark" - выбор цветовой схемы терминала (доступны asciinema, dracula, monokai, solarized-dark, solarized-light);
• --font-size N - размер шрифта в пикселях (по умолчанию 14);
• --cols N --rows N - размер окна (обычно совпадает с размером при записи);
• --idle-time-limit N - максимальная задержка между действиями в секундах (если пауза больше - она сокращается до этого значения);
• --last-frame-duration N - как долго показывать последний кадр (в секундах).

Пример с несколькими параметрами:

agg --speed 1.5 --theme dracula --font-size 16 --idle-time-limit 2 ./demo.cast ./demo.gif

Эта команда создаст GIF с полуторной скоростью, тёмной темой Dracula, с крупным шрифтом, и максимальная пауза между действиями будет 2 секунды (если пауза была дольше, она сократится).

Встраивание в веб-страницу

Если вы хотите показать запись на веб-сайте, как в начале этой статьи, Asciinema предоставляет простой способ встраивания - скрипт на JavaScript. Браузер автоматически подгружает интерактивный плеер, и читатель может нажать Play, посмотреть запись, перемотать её манипулятором типа мышь. Ну а файлы записей сессий обычно занимают пару килобайт.

Подробности установки, в т.ч. для разных CMS, смотрите в оф. документации: https://docs.asciinema.org/manual/asciicast/v3/ или в репозитории на GitHub: https://github.com/asciinema/asciinema-player.

Если вы встраиваете в статическую HTML-страницу, загрузите файл .cast на ваш хостинг (или используйте URL), и вставьте код:

<asciinema-player src="path/to/demo.cast"></asciinema-player>
<script src="https://js.asciinema.org/v3/bundle.js"></script>

В этом случае даже скрипт возьмётся из удалённого источника. Но для меня такой способ менее приемлем.

Параметры плеера, которыми можно управлять:

• src - путь к .cast файлу или прямая ссылка;
• id - id записи на asciinema.org (альтернатива src);
• title - подпись над плеером (необязательно);
• cols, rows - размер терминала;
• autoplay - автовоспроизведение (true/false);
• loop - зациклить воспроизведение (true/false);
• speed - скорость воспроизведения (1/2);
• idle-time-limit - сжимать паузы длиннее N секунд;
• start-at - с какой секунды начать;
• poster - кадр-превью, например “npt:0:03”;
• fit - “width”, “height”, “both” или “none”;
• theme - тема плеера: asciinema, dracula, monokai, seti, solarized-dark, solarized-light, tango, gruvbox-dark;
• font - шрифт терминала, любое валидное значение CSS font-family;
• font-size - размер шрифта терминала: “small”, “medium”, “big” или произвольное значение CSS, например “20px”.

Пример такого встраивания вы и видите на этой странице в разделе “Демо”. Работает со всеми браузерами.

Облачное хранилище и обмен

Если вы хотите поделиться записью с коллегой или загрузить её на публичный сервер, Asciinema предоставляет интеграцию со своим облачным хранилищем на asciinema.org.

Загрузить запись туда просто:

asciinema upload ./demo.cast

Вы получите URL вида https://asciinema.org/a/ABC123, который можно дать кому угодно. Зритель сможет посмотреть запись прямо на сайте разработчика, без необходимости скачивания.

Однако если вы работаете в приватной сети или как я, предпочитаете не доверять третьим сторонам, просто держите файл .cast на вашем собственном сервере и встраивайте его через HTML-код, о котором мы говорили выше.

Автоматизация записей

Если нужно запустить несколько команд без интерактивного ввода и сразу записать результат:

asciinema rec -c "bash -c 'ls -la; df -h; docker ps'" ./demo.cast

Флаг -c говорит asciinema сразу выполнить эту команду как записываемый процесс.

Послесловие

Asciinema - инструмент с очень узкой специализацией, но в этой специализации он почти идеален! Если вы пишете техническую документацию, создаёте обучающие материалы или просто фиксируете свой терминальный вывод, то это лучший способ для этого.

В следующей статье я расскажу как удобно и просто записывать все свои сессии терминала. При этом не занимая много места, с удобной индексацией сессий и шифрованием файлов. Подписывайтесь на телегу, чтобы не пропустить.

Спасибо, что читаете. Успехов! 🐧

Используемые материалы

• Официальный репозиторий asciinema на GitHub
• Репозиторий утилиты agg на GitHub
• Документация asciinema
• Облачное хранилище asciinema.org
• HTML5-плеер asciinema

👨‍💻Ну и…

Не забывайте про нашу телегу📱и чат 💬

Или может хотите стать соавтором? Тогда клик сюда🔗

Всех благ✌️

That should be it. If not, check the logs 🙂