asciinema

Aplikace asciinema je utilita, která zaznamenává na pozadí sekvence zobrazované v rámci terminálového okna do souboru. Výsledkem není reprodukovatelný záznam operací (makro), jako u aplikace skript), ale čistě vizuální záznam, který si můžeme kdykoliv znovu přehrát a využít buď při výuce, nebo k dodatečné analýze realizovaných operací.

Systém MediaWiki na TheWoodcraft.org má k dispozici Widget:Ascii, který umožňuje tyhle záznamy přehrávat. Je použitý i na stránce Soubor:zaznam asciinema.json, kde přehrává tento záznam, na kterém můžete vidět jak to vypadá v prostředí terminálu, když se použije asciinema.

Možnosti přehrávání prořízeného záznamu aplikací asciinema jsou omezené možnostmi terminálu. Webový přehrávač asciinema-player, který je použit zde, umožňuje přehrávání kdykoliv pozastavit a využít kromě dolní lišty také funkční klávesy:

• Mezerník – pozastaví/spustí přehrávání
• Šipky < a > – umožňují záznam posouvat kupředu i nazpátek
• Klávesa f – přepíná mezi fullscreen zobrazením

Přehráváme-li záznam v okně terminálu přes aplikaci asciinema, je možné mezerníkem přehrávání pozastavit/spustit, klávesou, kde je znak tečka krokovat a kombinací "Ctrl-c" přerušit. Ale vrátit se o krok zpět nebo přeskočit na konkrétní značku a přehrát jen vybraný úsek, který mne zajímá, bohužel nejde.

Instalace

Aplikace asciinema je pouze unixová záležitost, ale umožňuje nahrávat i dění terminálu MS Windows, jsme-li k němu připojeni vzdáleně přes SSH. Je k dispozici v repozitáři Debianu (a většiny derivátů Ubuntu), takže pokud vaše distribuce používá APT, je instalace jednoduchá.:

root@stroj~# apt-get install asciinema

Záznam

Asciinema využívá, podobně jako aplikace screen nebo tmux, specifické vlastnosti pseudoterminálové konzole (PTY), která umožnuje přes klávesovovou zkratku odeslat příkaz aplikaci co běží na pozadí.

Tak běží asciinema když se jí předá příkaz "rec" a průběžně ukládá dění v okně terminálu do souboru typu asciicast.

~$ asciinema rec [cesta k souboru]

Nahrávání lze přerušit buď tak, že ukončíme sezení příkazem exit, nebo klávesovou zkratkou Ctrl+D. Ukázkový záznam, který demonstruje co se zobrazí na terminálu, když se spustí nahrávání, můžete shlédnout na stránce Soubor:zaznam asciinema.json

Soubor se záznamem – asciicast

Velkou výhodou aplikace asciinema je to, že záznam ukládá do JSON formátu, který lze kdykoliv dodatečně upravit v běžném textovém editoru.

Původně, až do verze 1.4 ukládala tehdejší události do formátu, který byl má kromě zaznamenaného obsahu standardního výstupu uloženy také metadata s doplňkovými informacemi o použitém terminálu, rozměru terminálového okna, aj. Na konci záznamu je uložena informace o délce jejího trvání (duration).

Může také obsahovat informace o rozměrech terminálového okna, název nahrávky aj.

Samotný záznam tvoří jednotlivé snímky, které jsou součástí pole "stdout". Každý snímek tvoří seznam se dvěma položkami:

1. interval zobrazení snímku
2. a zobrazovaná znaková sekvence

Ukázkový záznam v asciicast formátu verze 1, který používala asciinema do verze 1.4, demonstruje jak se spouští nahrávání záznamu.

{
  "env": {
    "SHELL": "/bin/bash",
    "TERM": "xterm"
  },
  "duration": 12.909403,
  "version": 1,
  "stdout": [
    [
      0.065076,
      "\u001b]0;user@stroj: ~\u0007user@stroj:~$ "
    ],
    [
      1.599755,
      "e"
    ],
    [
      0.209485,
      "c"
    ],
    [
      0.170751,
      "h"
    ],
    [
      0.133149,
      "o"
    ],
    [
      0.212579,
      " "
    ],
    [
      0.521397,
      "a"
    ],
    [
      0.358403,
      "h"
    ],
    [
      0.100292,
      "o"
    ],
    [
      0.291969,
      "j"
    ],
    [
      1.084788,
      "\r\nahoj\r\n\u001b]0;user@stroj: ~\u0007user@stroj:~$ "
    ],
    [
      4.869861,
      "echo ahoj"
    ],
    [
      0.887171,
      "\r\n"
    ],
    [
      0.000165,
      "ahoj\r\n"
    ],
    [
      0.000174,
      "\u001b]0;user@stroj: ~\u0007user@stroj:~$ "
    ],
    [
      2.404212,
      "exit\r\nexit\r\n"
    ]
  ],
  "width": 80,
  "title": null,
  "command": null,
  "height": 24
}

Konverze do asciicast formátu verze 2 s využitím novější verze aplikace asciinema de facto znamená novou nahrávku. Proto se liší nejenom délka záznamu, ale také časové razítko (timestamp) i časy událostí. Ale u většiny záznamů jde o pouhý detail, na kterém nezáleží. Ke konverzi byl použit následující příkaz:

~$ asciinema rec -t 'asciicast_v2' \
   -c 'asciinema play asciicast_v1.json' \
   asciicast_v2.cast

{"version": 2, "width": 80, "height": 24, "timestamp": 1732634806, "env": {"SHELL": "/bin/bash", "TERM": "xterm"}, "title": "asciicast_v2"}
[0.248066, "o", "\u001b]0;user@stroj: ~\u0007user@stroj:~$ "]
[1.849355, "o", "e"]
[2.057444, "o", "c"]
[2.228162, "o", "h"]
[2.361273, "o", "o"]
[2.573945, "o", " "]
[3.095633, "o", "a"]
[3.453752, "o", "h"]
[3.553911, "o", "o"]
[3.846064, "o", "j"]
[4.931653, "o", "\r\nahoj\r\n\u001b]0;user@stroj: ~\u0007user@stroj:~$ "]
[9.804429, "o", "echo ahoj"]
[10.688411, "o", "\r\nahoj\r\n\u001b]0;user@stroj: ~\u0007user@stroj:~$ "]
[13.094556, "o", "exit\r\nexit\r\n"]

Nicméně skript asciiframe umožňuje skutečnou konverzi asciicastu verze 1 na verzi 2, kdy se časy událostí postupně sčítají a délka záznamu tak zůstane víceméně stejná. Všimněte si, že se čas posledních událostí liší cca o 0.2 sekundy, což odpovídá zhruba tomu, jak dlouho trvá spuštění aplikace asciinema. Konverzi lze provést následujícím příkazem:

~$ asciiframe clip tests/asciicast_v1.json -- 1 0.0 \
   2>/dev/null | grep -v '\[0.0,' > asciicast_v1_to_v2.cast

Než skript asciiframe použije akci clip, zpracuje původní formát a protože jsou místo klipu předány jen dvě pomlčky za sebou, nic neimportuje, jenom koriguje časový interval první události o 0.0 sekund. Tzn. že „vyzvrací” obsah původního souboru na stdout jako asciicast verze 2.

{"version": 2, "width": 80, "height": 24, "timestamp": 1732635383, "duration": 12.909227, "env": {"SHELL": "/bin/bash", "TERM": "xterm"}}
[0.065075, "o", "\u001b]0;user@stroj: ~\u0007user@stroj:~$ "]
[1.664831, "o", "e"]
[1.874316, "o", "c"]
[2.045067, "o", "h"]
[2.178216, "o", "o"]
[2.390795, "o", " "]
[2.912192, "o", "a"]
[3.270595, "o", "h"]
[3.370887, "o", "o"]
[3.662856, "o", "j"]
[4.747644, "o", "\r\nahoj\r\n\u001b]0;user@stroj: ~\u0007user@stroj:~$ "]
[9.617505, "o", "echo ahoj"]
[10.504676, "o", "\r\n"]
[10.504841, "o", "ahoj\r\n"]
[10.505015, "o", "\u001b]0;user@stroj: ~\u0007user@stroj:~$ "]
[12.909227, "o", "exit\r\nexit\r\n"]

Úprava záznamu

Aplikace zaznamenává průběžně a v reálném čase všechno, co je součástí standardního výstupu – nikoliv vstupu(!). Do záznamu se tedy neukládá nic z toho co nebylo vidět ani v terminálovém okně (kupř. heslo, atp.).

Povšimněte si u předchozího ukázkovém záznamu, že se při psaní uložil snímek pro každý jednotlivý znak. Pokud budete chtít svoje záznamy dodatečně upravit tak, aby se objevil celý text najednou, budete muset v takových případech upravit celou sekvenci snímků. Dodatečná editace záznamu je ale žádoucí i z jiných hledisek:

• odstraněním "hluchých" snímků a zkrácením časových intervalů zredukujete celkovou délku záznamu, a…
• doplněním komentářů a zvýrazněním podstatných míst můžete umocnnit jeho edukační efekt

Při ladění úprav záznamu pro přehrávání přes asciinema-player, mějte na paměti, že vám mohou vaše počínání komplikovat keše webových prohlížečů. Proto je vždy lepší časování snímků nepjprve odladit při přehrávání na konzoli.

Ostranění nadbytečných snímků

Zaznamenané snímky, které by při následném přehrávání mohly působit rušivě a nemají přímou souvislost s cílem záznamu – typicky, opravy překlepů – je lepší preventivně odstranit.

Každý snímek je uložen jako seznam dvou hodnot, uzavřených v hranaté závorce. Tou první je délka prodlevy – více o ní budu hovořit níže, u časování snímků. A za ní je v uvozovkách zaznamenaný textový řetězec.

Pro odstranění snímku je tedy zapotřebí smazat vše, včetně hranatých závorek a čárky, která za nimi následuje.

Slučování snímků

Jak už bylo zmíněno, při nahrávání se ukládají snímky postupně tak, jak se objevuje text na standardním výstupu terminálového okna.

V ukázkovém záznamu tak hravě rozpoznáte text, který byl zadáván přes klávesnici, kdy se každý znak uložil jako samostatný snímek, kdežto text zkopírovaný kolečkem myši, byl zaznamenaný jako snímek jeden.

Podobně by tomu bylo i v případě, že by byl vytažen z historie, nebo vypsán skriptem.

Z hlediska přehrávání záznamu na tom sice nezáleží, ale pokud chceme záznam dále zpracovat pomocí funkce vyhledat/nahradit, je výhodné takové snímky sloučit. To platí, například když chceme dodatečně anonymizovat v záznamu textové řetězce (IP adresy, uživatelská jména, aj.). Tam, kde byl textový obsah psaný postupně (a tím pádem rozdělen do více snímků) bez sloučení znaků z jednotlivých snímků do jednoho textového řetězce k nahrazení nedojde.

K rozdělení na více snímků dojde také v případě, že se výstup příkazu vypisoval na standardní výstup postupně. I v této situaci je výhodnější takové snímky sloučit.

Zvýraznění obsahu

Pokud má záznam sloužit k výuce, může se hodit zvýraznění určitého obsahu terminálového okna pomocí vložení ANSI kódů, které pozmění zobrazovaný text tak, aby upoutal pozornost pozorovatele. V případě, že zaznamenaný text obsahuje obarvený, či jinak zvýrazněný text, je optimální ke zvýraznění použít:

• podtržení
• podbarvení pozadí

Každé sekvenci musí v záznamu předcházet speciální unicode znak, zapsaný následujícím řetězcem: \u00b1

\u001b[0,1m … \u001b[m

zobrazí vytučněný řetězec.

\u001b[0;1;31m … \u001b[m

zobrazí vytučněný řetězec, v červené barvě.

\u001b[0;31m\u001b[1m\u001b[5m … \u001b[m

zobrazí blikající, vytučněný a navíc červeně zbarvený řetězec

Pozice se zpracovávají zprava, proto

třetí číslo určuje barvu textu

druhé způsob zvýraznění textu: 1 - tučný; 2 - tmavě šedý; 3 - kurzívní; 4 - podtržený ; 5 a 6 - blikající, protože se invertují barvy popředí a pozadí; 7 - ivertovaný (barvy pozadí a textu zůstanou prohozené); 8 - průhledný (využívá se např. ke skrytí hesla při zadávání); 9 - výchozí hodnota)

a první barvu pozadí (1 - červená; 2 - zelená; 3 - žlutá; 4 - modrá; 5 - fialová; 6 - svítivě modrá (cyan); 7 - světle šedá ; 8 - průhledná ; 9 - výchozí hodnota)

Je-li uvedeno pouze jedno číslo, následované písmenem m:

0 – vrací vše na výchozí hodnotu

2x – signalizuje změnu parametru na druhé pozici (text)

3x – signalizuje změnu parametru na třetí pozici (pozadí)

4x – nastavuje barvu pozadí

9x – zesvětluje barvu textu, takže při hodnotě 97 bude text bílý

10x – zesvětluje barvu pozadí, takže při hodnotě 107 bude bílý text (je-li bílá výchozí barvou) na bílém pozadí.

Více viz http://misc.flogisoft.com/bash/tip_colors_and_formatting

Blikání lze využít pouze tehdy, pokud se chystáme záznam přehrávat pouze na terminálové konzoli. Javaskriptový přehrávač asciinema-player tento efekt zobrazit neumí.

Časování

Pamatujte, že při nahrávání záznamu není prioritou čas, ale správnost realizovaných kroků. Je mnohem snazší dodatečně korigovat časování snímků, než mazat a slučovat snímky, které zaznamenaly překlepy a chyby, způsobené zbytečným spěchem a nepozorností!

Časování snímků je důležitým prvkem, kterým lze ovlivnit pozornost při sledování přehrávaného záznamu. U většiny záznamů, je nutné zaznamenané intervaly zkrátit. Řešit prodlevy mezi operacemi zrychleným přehráváním není vhodné, protože by při tom mohly snadno ujít pozornosti krátké, leč důležité operace.

Zaznamenané časy (v sekundách) se v záznamu vyskytují jako čísla s plovoucí čárkou, které vypadají asi takto:

• U velmi krátkých intervalů – 5.9e-05 (v podstatě hodnota 0.000059)
• U krátkých intervalů – 0.011384
• U dlouhých intervalů – 39.174503

Součástí záznamu je i celkový čas (duration), který ale nemá na přehrávání vliv. Čas záznamu (ať již odehraný, nebo zbývající), který udává asciinema-player, se totiž vždy vypočítává jako součet intervalů všech snímků v záznamu.

Stejně tak není nutné zachovávat přesné časy. Důležité je, aby byl záznam snadno srozumitelný a přehledný. Proto není od věci u některých operací interval prodloužit o jednu dvě sekundy, abychom měli jistotu, že neunikne pozornosti. V situaci kdy je vhodné doplnit kontext realizované operace se mohou hodit i dodatečné komentáře.

Vložení dodatečných komentářů

Doplňující komentáře, lze vložit jako další snímky. Díky tomu, že je časování snímků relativní a nemá žádný pevný vztah k časové ose, je nejsnazší komentáře kopírovat jako hotové snímky z jiného záznamu.

Příprava komentářů

K vytvoření komentářů lze s výhodou využít aplikace asciio. Optimální je, ukládat jednotlivé komentáře do samostatných textových souborů, které si pak přehrajeme jednoduchým skriptem printcomments.sh…

Obsah spustitelného souboru printcomments.sh

#!/bin/bash
for i in $@
do echo $(<$i)
   sleep 1
done

…kterému při nahrávání záznamu předhodíme seznam souborů s komentáři. Např.:

./printcomments.sh message1.txt message2.txt …

"Nahrávka" komentářů

Nahrávku komentářů pak uděláme opět přes aplikaci asciinema. Zapneme nahrávání a spustíme připravený skript, který postupně každou sekundu vytiskne na standardní výstup obsah příslušného textového souboru s komentářem.

Kopírování hotových komentářů

Po přehrání všech komentářů ukončíme nahrávání a z uloženého záznamu s komentáři potom nakopírujeme uložené snímky do příslušných míst finálního záznamu a případně upravíme intervaly jejich zobrazení.

Meta informace

Meta informace obsahují data důležitá především pro přehrávání prostřednictvím javaskriptového přehrávače asciinema-player

Rozměry okna

Celkový čas (duration )

Rozhoduje o tom, za jak dlouho dojde k novému spuštění přehrávání záznamu, je-li aktivována smyčka (loop). Výchozí hodnota odpovídá celkovému času trvání sezení. Tuto hodnotu je třeba příslušným způsobem upravit (zpravidla zkrátit), tak aby zhruba odpovídala délce záznamu po všech úpravách.

Šířka terminálového okna (width)

Výška terminálového okna (height)

Rozhoduje o tom, kolik řádků bude viditelných při rolování obsahu okna. Mějte na paměti, že na rozdíl od přehrávání v okně terminálu asciinema-player neumožňuje rolování. Pokud se tedy budete chtít během přehrávání vrátit k předchozímu obsahu, musíte využívat skoků v rámci časové osy (klávesové šipky)

Rychlost přehrávání

Výchozí rychlost přehrávání není nutné měnit, pokud jste upravili prodlevy snímů tak, aby záznam nebyl příliš zdlouhavý.

Titulek záznamu

použitý terminál a titulek záznamu

Přehrávání

Přehrávání záznamu pořízeného pomocí aplikace asciinema v rámci konzole je vcelku nezajímavé.

Pro přehrávání záznamu na webových stránkách existuje javascriptový přehrávač asciinema-player, který je ke stažení na adrese https://github.com/asciinema/asciinema-player.git jeho instalace na straně webového serveru ale vyžaduje spolupráci ze strany správce tohoto serveru.

Publikování záznamu v rámci wiki TheWoodcraft.org

K publikaci záznamu v rámci wiki je nutné:

1. nainstalovat rozšíření Widgets, které umožňuje interpretovat na wiki stránkách obsah stránky Widgets:Ascii jako šablonu;
2. a v souboru LocalSettings.php povolit upload souborů s příponou ".cast", resp. ".json"

Kdo chce, ten si může javascriptový kód přehrávače sestavit v aktuální verzi ze zdrojových kódů v git repozitáři. Ale není to nutné, protože je ve stejném repozitáři k dispozici již sestavený soubor asciinema-player.min.js i CSS soubor asciinema-player.css, který si může každý upravit dle svých představ.

Obsah stránky Widget:Ascii vypadá takto:

…

V kódu wiki stránky se tento widget aplikuje takto:

{{#widget:Ascii
|url=https://www.thewoodcraft.org/wiki/images/a/a4/asciicast_v1.json
|theme=solarized-light
}}

URL použité v tomto ukázkovém widgetu vede na asciicastový soubor Soubor:asciicast v1.json, jehož obsah demonstruje také rozdíl mezi asciicasten verze 1 (JSON) a verze 2. Interpretace widgetu pak vypadá takto:

Parametry

Rozměry terminálu přehrávaného okna nejsou rozměry okna přehrávače, ale terminálové konzole. Při přehrávání se používá font typu monotype:

rows

udává počet zobrazených řádků konzole (default 24)

cels

udává počet sloupců konzole (default 80)

url

Je základní parametr, kterým se odkazuje na přehrávaný .json soubor. URL může být absolutní (včetně http://…, nebo absolutní vůči kořeni webu. V našem případě, je záznam uploadován do wiki, proto je cesta /wiki/images/a/a4/asciicast v1.json, ale mohl by být umístěn i do lokálního úložiště wiki, do kterého je cesta /pub/wiki/…

Ostatní parametry již tak důležité nejsou, kromě…

title

Při implementace přehrávače asciinema-player přes rozšíření Widget, lze totiž na jedné wiki stránce umístit pouze v jednu instanci přehrávače. Ve většině případů to nepředstavuje omezení, ovšem pokud chceme přehrávat na jedné stránce záznamů více, je potřeba element, ve kterém widget přehrává záznam pojmenovat jinak. A k tomu slouží právě tento parametr.

size

umožňuje upravit velikost zobrazovaného písma – výchozí je small (medium, big)

speed

mění rychlost přehrávání (výchozí 1)

theme

nastavuje barevné schéma terminálového oknav. Výchozí je asciinema (tango, solarized-dark, solarized-light, monokai)

start

umožňuje posunout začátek přehrávání (výchozí je 0)

autoplay

0/1

preload

0/1 automatický start přehrávání

loop

Udává počet přehrání, pokud chceme záznam pustit ve smyčce. Výchozí hodnota je 1. Pokud chceme nekonečnou smyčku, lze nastavit 0.

Ovládání přehrávače:

• Pro posun tam i zpět fungují, kromě klávesových zkratek (Ctrl+H Ctrl+L), také šipky
• Přehrávání lze zapauzovat mezerníkem. Jinak lze použít klávesovou zkratku (Ctrl+P), nebo myš.
• Fullscreen – klávesou f
• Číslice 0, 1, 2 … 9 pro skok na 0%, 10%, 20% … 90%

Publikování záznamu na asciinema.org

Upravený záznam lze přehrávat nejenom v okně terminálu, ale také prostřednictvím javaskriptového přehrávače. Nejjednodušší z hlediska implementace je využít služeb serveru https://asciinema.org Uložený záznam si pak můžete vkládat do webových stránek prostřednictvím odkazu, který bude vypadat asi takto:

<script type="text/javascript" src="https://asciinema.org/a/14.js" id="zaznam-1" async></script>

Místo identifikátoru zaznam-1 uvedete identifikátor vašeho záznamu na webu https://asciinema.org

Jak zjistit aktuální velikost terminálového okna?

~$ tput cols; tput lines

SVG screenshot terminálového okna

Jsou i jiné aplikace, které umí, stejně jako asciinema, zaznamenat terminálové události do asciicastu verze 2

V květnu 2018 začal vyvíjet pro Python3.6 Nicolas Bedos termtosvg a verzi 1.0 dokončil v listopadu 2019. Od té doby už žádný další vývoj téhle aplikace neprobíhá a poslední Nicolasem commitovanou změnou z roku 2020, je funkce, která zobrazuje verzi a informaci, že Nicolas s vývojem končí, protože už na to nemá čas. Ovšem tenhle kód byl začleněn až po vydání verze 1.1.0, kterou můžete najít i v repozitáři Debianu, proto u ní volba --version chybí.

Funguje podobně jako asciinema – zachytává příkazy terminálu, které při akci record zapisuje do asciicastu verze 2, ale jenom proto, aby z něj při akci render vyrobila animované SVG – neumí ho přehrát na konzoli.

Není to nutné, protože ho umí přehrát asciinema a liší se jen v detailech:

• V záhlaví má jen základní informace o rozměru okna terminálu.
• Neukládá časové razítko kdy bylo spuštěno nahrávání (timestamp), ani informace o použitém shellu a terminálu.
• Záznam první události začíná časem 0.0
• A nepodporuje „události” typu marker a resize.

Bohužel se již několik let nevyvíjí, takže přestává být použitelná, protože na neznámé terminálové příkazy či události v asciicastu reaguje tím, že se zhroutí – stačí spustit vim. Je to škoda, protože se dala využít k vygerování statického SVG i z jiného asciicastu, neboť podporuje rovněž volbu --command:

~$ termtosvg --still-frames --screen-geometry 80x39 --command 'asciinema play zaznam.json'

Naštěstí existuje náhrada – termsvg, kterou začal v jazyce Go programovat Alvaro Tinoco, který zřejmě jako první narazil v srpnu 2020 na výše uvedený problém. Bohužel stále není v distribuci Debianu, přestože je poslední stabilní verze 0.9.2 dostupná již od května 2024. Ale není to zas takový problém, protože Alvaro nabízí ve svém git repozitáři i zkompilovanou, binární verzi.

https://github.com/MrMarble/termsvg

Podporuje akci play, ale má jednu chybu – umí renderovat jen animované SVG a nenabízí žádnou volbu, jak vyrenderovat pouze jeden snímek.

Animované SVG je totiž stejná prasečina jako PDF, protože má mnoho způsobů jakým způsobem se dá taková animace udělat. Bohužel díky tomu se univerzální nástroj, přes který by se dal vyexportovat z animovaného SVG pouze jeden „frame” v SVG formátu neexistuje.

Nezbylo mi nic jiného, než to animované SVG prozkoumat a zjistit co a jak se s tím dá udělat. A nakonec, když víte co a jak, je to relativně jednoduché.