asciinema
Aplikace asciinema je utilita, která zaznamenává do souboru formátu asciicast obsah terminálového okna vypisovaný během sezení na jeho standardní výstup. Výsledkem tedy není reprodukovatelný záznam operací (makro), jako u aplikace skript), ale čistě vizuální záznam, který lze dodatečně přehrávat a využívat buď při výuce, nebo k dodatečné analýze realizovaných operací.
- 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
Instalace
Aplikace asciinema je v repozitáři Debianu. Pokud používáte tuto distribuci, je instalace jednoduchá.:
root@stroj~# apt-get install asciinema
:set syntax=json
Záznam
Podobně jako screen využívá asciinema vlastností pseudoterminálové konzole (PTY), kdy lze pomocí klávesové zkratky vyslat příkaz aplikaci, která v něm běží na pozadí.
Spuštění záznamu lze spustit jednoduše tím, že aplikaci předáme příkaz "rec" a cestu k souboru, do kterého se má záznam ukládat. Nahrávání lze kdykoliv přerušit buď ukončením sezení příkazem exit, nebo klávesovou zkratkou Ctrl+D. Ukázkový záznam, který demonstruje právě použití aplikace asciinema si můžete shlédnout na stránce Soubor:zaznam asciinema.json
~$ asciinema rec [cesta k souboru]
|
Pokud spustíme nový záznam aniž bychom změnili cestu k souboru, přepíšeme jeho původní obsah. |
Formát souboru se záznamem
Uložený záznam je textový soubor v JSON formátu, který 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:
- interval zobrazení snímku
- a zobrazovaná znaková sekvence
Ukázkový záznam, který demonstruje, jak vypadá záznam aplikace asciinema – Soubor:zaznam.json{
"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
}
Ú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
Jaké kódy lze využít, 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é:
- nainstalovat rozšíření Widgets, které umožňuje interpretovat na wiki stránkách obsah stránky Widgets:Ascii jako šablonu;
- a v souboru
LocalSettings.phppovolit upload souborů s příponou ".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 tam k dispozici již sestavený soubor asciinema-player.min.js a také CSS soubor asciinema-player.css, který si může rovněž kdo chce 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/7/75/zaznam.json
|theme=solarized-light
}}
URL použité v tomto ukázkovém widgetu vede na soubor Soubor:zaznam.json, jehož obsah je uveden výše (v ukázce JSON formátu záznamu z aplikace asciinema). 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/7/75/zaznam.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
termtosvg
Jak zjistit aktuální velikost terminálového okna?
~$ tput cols; tput lines
Generujeme screenshoty
~$ termtosvg --still-frames --screen-geometry 80x39 --command 'asciinema play zaznam.json' .
