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

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í

Ukázkovém příklad využití aplikace asciinema, uvedený v záhlaví této stránky, demonstruje i jakým způsobem lze záznam přehrávat v okně terminálu. Pro použití na webových stránkách existuje přehrávač asciinema-player, který lze (jak vidíte na této stránce) implementovat prostřednictvím rozšíření Extension:Widget i do stránek MediaWiki.

Pro tento účel ovšem bylo zapotřebí nejprve vytvořit stránku Widget:Ascii ve jmenném prostoru Widget, která se podobá šabloně, s následujícím obsahem:

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

{{#widget:Ascii
|url=https://www.thewoodcraft.org/wiki/images/7/75/zaznam.json
|rows=24
|cols=80
}}

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:

Při implementace přehrávače asciinema-player přes rozšíření Widget, lze 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 v tomto případě bylo nutné widget, který přehrává záznam Soubor:zaznam asciinema.json, umístit na stránku k souboru.

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

Publikování záznamu v rámci wiki

Přehrávání záznamu v rámci wiki stránky vyžaduje spolupráci ze strany správce.

Nejprve je nutné někam do adresářové struktury webu umístit javaskriptový přehrávač, který je ke stažení na adrese https://github.com/asciinema/asciinema-player.git Ten si může, pokud chce, sestavit i v aktuální verzi ze zdrojových kódů v git repozitáři. Pro sestavení si musíte stáhnout …

Sestavený soubor asciinema-player.js najdete v adresáři … a CSS soubor asciinema-player.css

Potom je třeba nainstalovat rozšíření Widgets, které umožní udělat šablonu co pak budete používat na wiki stránkách, a v souboru LocalSettings.php povolit upload souborů s příponou ".json"

Obsah stránky Widgets:Ascii …

Příklad kódu umístěného na stránce… …

Co je potřeba vědět

Přehrávání záznamu přes asciinema-player má svá specifika. Kupř. nelze pro zvýraznění obsahu využít všechny ascii sekvence.

Rozměr přehrávaného okna

"rows x cels" versus "height x width"

Rychlost

"speed" versus "duration"

Úprava přehrávání

speed

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

size

velikost zobrazovaného písma - výchozí je small (medium, big)

theme

výchozí asciinema (tango, solarized-dark, solarized-light, monokai)

t

počátek přehrávání

autoplay

0/1

preload

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

loop

0/1 přehrávání ve smyčce

• Fungují šipky pro posun tam i zpět (Ctrl+H Ctrl+L)
• Mezerník funguje pro pauzu (Ctrl+P)
• Fullscreen - klávesou f
• Číslice 0, 1, 2 … 9 pro skok na 0%, 10%, 20% … 90%