asciinema と agg: ターミナルセッションの記録と共有

百聞は一見に一見にしかず?

AWS EC2 のコスト計算 API を Rust で作成した - blog.ayakumo.net で紹介したツールの README を作成するにあたり asciinema と agg*1 を使用しています。ターミナルセッションを GIF にすることで、ツールの動作や実行環境が読み手にわかりやすくなります。もともとは https://github.com/ducaale/xh の README で使用されていたのを見たのがきっかけで、今回、自分のツールでも採用してみました。:-)

基本的な使いかた

  1. asciinema rec で録画用のターミナルセッションを開始すると新たに bash が起動されるので録画したいコマンドを打ちこんでいきます。
➜ asciinema rec
(... snip ...)
  1. exit で録画を終了します。そのまま asciinema.org に .cast ファイルをアップロードするかローカルに保存するかを選択します。保存した .cast ファイルは asciinema play で再生します。ローカルで保存した .cast を後から asciinema upload でアップロードすることも可能です。
➜ exit
asciinema: recording finished
asciinema: press <enter> to upload to asciinema.org, <ctrl-c> to save locally
asciinema: asciicast saved to /var/folders/yr/f0mycbg912b6hjt6tbrkh9j80000gn/T/tmpj433lze8-ascii.cast

➜ asciinema play /var/folders/yr/f0mycbg912b6hjt6tbrkh9j80000gn/T/tmpj433lze8-ascii.cast
➜ asciinema upload /var/folders/yr/f0mycbg912b6hjt6tbrkh9j80000gn/T/tmpj433lze8-ascii.cast
  1. agg を使用して .cast を .gif に変更します。同時に再生速度やターミナルのテーマ、フォントサイズなどを変更します。github の README で使用する場合は読み手のストレスを考えた速度にするとよさそうです。
➜ agg --theme monokai --font-size 20 --speed 2 /var/folders/yr/f0mycbg912b6hjt6tbrkh9j80000gn/T/tmpj433lze8-ascii.cast ~/Desktop/ec5-demo.gif

起動と終了は古のscript コマンドと同じです。打ち込むコマンドをタイピングしている最中にミスしてしまうとちょっと恥ずかしいのでコピペにするか、もしくはゆっくりでもいいので確実に入力していきます。.gif にする場合は agg を使用して再生速度を変更可能なので、確実に入力していったほうが最終的な見栄えはよくなると思います。

ソフトウェア開発の現場でも

ターミナル操作を動画にしておくのはソフトウェア開発のいろいろな場面で有用だと思うので活用していきたいと考えています。プロジェクトで使う場合はプライベートに .cast を保存して共有するのがよいかもしれません。ただ、基本的に 一時停止ができないので複雑な操作をする場合は QuickTime などを利用して .mov のほうがいいでしょうか...

参考情報

*1:agg はもともと asciicast2gif という名前で開発されていたようです