Zenn
Open3

aqua の Demo 作成に asciinema を使ってみたら良かった

Shunsuke SuzukiShunsuke Suzuki

aqua という OSS を開発しています。

https://aquaproj.github.io/

これをより多くの人に使ってもらうにはどうしたらよいかというのを同僚と雑談で話したら
https://asciinema.org/ ( https://github.com/asciinema/asciinema ) でデモ動画作るのを勧められてもらったので、作ってみました。

Demo へのリンクは Demo を作り直すと変わる気がするので、エイリアス的なページを作りました。
https://aquaproj.github.io/docs/demo

簡単に作れるし、公開が簡単なので良かったです。
以前 https://github.com/faressoft/terminalizer で gif をビルドした際は、設定にもよりますがビルドに結構時間がかかったのですが、それがないのが良かったです(尤も、 terminalizer にも同様の機能はありますが)。

今回もまずは terminalizer を使って作ろうかと思いましたが、 terminalizer の将来性に懸念があったので
asciinema を使ってみました。
将来性に懸念があるとは

The installation should be very smooth with Node.js v4-v12.
For newer versions, if the installation is failed, you may need to install the development tools to build the C++ add-ons. Check node-gyp.

  • 新しい Node.js へのサポートが微妙。 v14 ではすんなり動いたが、 v16, v17 では動かなかった(深追いはしていない
  • 最終更新が 1 年以上前

asciinema は割と最近も更新がありそうであり、今の所特にそういった懸念を感じませんでした。

一度録画したものを倍速にして録画

最初普通に録画したら 5 分弱かかってしまい、長過ぎる気がしたので、倍速にして replay して録画し、あとで生成されたファイルをちょっと修正しました。

$ asciinema rec first.cast # 一回録画
$ asciinema rec demo.cast # 二回目録画
> asciinema play -s 2 first.cast # 二回目の録画は一回目に録画したものを倍速で再生して録画。このコマンドを実行している部分は後でカットする

そもそも upload の設定で倍速とかできたらこんなことしなくても良いのですが、そういうオプションはなさそうなのでこんなふうにしました。

demo のメンテに関して

demo のメンテに関して思うところは、多分新しい demo を upload してリンクを修正することになると思うのですが、その場合古い動画はどうするのがいいんでしょうね。
消すべき？それとも description に新しい動画へのリンクを貼るべき？
後者のほうが親切な気はする。ただ、ほんの細かな修正であれば消してしまったほうが良い気もする。

他に試そうと思って断念したこと

Katacoda でのブラウザ操作を Chrome Extention で録画

コンテナで実行

デモは macOS で実行しましたが、 コンテナで実行するのも最初検討しました。
しかし、コンテナ上に環境作るのが面倒だったのでやめました。

とりあえず aqua を一時的に uninstall してしまえばデモ環境の準備としては十分でした。

$ mv ~/.aqua ~/.aqua.bak
$ brew uninstall aqua

doitlive

https://doitlive.readthedocs.io/en/stable/

今回はほぼ手打ちでコマンドを入力しましたが、 doitlive を使って自動化しようかとも思いました。
しかし、 command not found の際に謎の文字列が出力されるので諦めました。
あまり深追いはしていません。

Shunsuke SuzukiShunsuke Suzuki

Youtube への投稿

asciinema に投稿したものをそのまま Youtube にも投稿してみました。

  • Youtube Channel 作成: account ごとに一個作る感じなのかな？
  • asciinema の動画を全画面表示で再生
  • QuickTimePlayer で録画(Cmd + Shit + 5)
    • カーソルは消し方がわからなかった
    • 最初と最後の数秒をトリムで切り取った
    • 書き込み(.mov)
      • 画質は最高にした 4k
      • 画質を最低にしたものを Youtube に upload するとぼやけていた
  • Youtube に upload
    • upload した直後は画質が悪い。 Youtube 側で処理が完了すると画質が良くなった
    • tag はあまり関係ないらしい
    • とりあえず非公開で投稿して、問題なかったら公開する
    • aqua 用の再生チャンネルを作成し、そこに動画を追加する

動画を更新することはできず、新しい動画を upload し直すことになる

Shunsuke SuzukiShunsuke Suzuki

asciinema で録画時の細かな話

  • ターミナルは最大化を解除して小さめにして録画した
    • 最大の状態で録画すると文字が小さくなる
  • 別のターミナルで簡単な流れというかカンペを用意した。ただコマンドは基本手打ちした
    • URL やタイポしても気づきにくい PATH の設定はコピペした
  • これから何をやろうとしているかとかを : 配下に説明書いて補足した
    • ただし、クォートはシェルで解釈されてしまうので使わないようにした isn't を isnt と書くみたいに