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í.

Na stránce Soubor:zaznam asciinema.json si můžete přehrát ukázkový záznam, který demonstruje, jak se asciinema používá v terminálovém okně. Hlavní rozdíl, mezi přehráváním záznamu přes aplikaci asciinema v okně terminálu a přehráváním prostřednictvím webového přehrávače asciinema-player, který je použit zde, je v tom, že v terminálu lze přehrávání pouze přerušit (přes "Ctrl-c"). Webový přehrávač umožňuje používat při přehrávání kromě dolní lišty také 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

Instalace

Aplikace asciinema je v repozitáři Debianu. Pokud používáte tuto distribuci, je instalace jednoduchá.:

root@stroj~# apt-get install asciinema

K dodatečné editaci záznamu sezení lze používat libovolný textový editor – ideální je takový, který umí zvýraznit syntaxi JSON souborů. Protože jde o aplikaci, která je určena pro textovou konzoli, lze k úpravám doporučit kupř. textový editor vim, u kterého lze zapnout zvýrazňování syntaxe následujícím způsobem:

:set syntax=json

Pro generování komentářů či ASCII artů se může hodit aplikace, které se věnuje předchozí blogpost – asciio.

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:

1. interval zobrazení snímku
2. 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

\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: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' .