asciinema

Aplikace asciinema je utilita, která zaznamenává na pozadí sekvence zobrazované v rámci terminálového okna do souboru. Výsledk 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í termiá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 v ní běží na pozadí.

Nahrávání se spouští tak, že se aplikaci asciinema předá příkaz "rec" a cestu k souboru, do kterého se má záznam ukládat. Nahrávání lze kdykoliv přerušit a to buď ukončením sezení příkazem exit, nebo klávesovou zkratkou Ctrl+D. Ukázkový záznam, který demonstruje použití aplikace asciinema můžete shlédnout na stránce Soubor:zaznam asciinema.json

~$ asciinema rec [cesta k souboru]

Formát souboru se záznamem

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
}

Ú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 ".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:asciicast v1.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' .