Como usar script e asciinema para gravar sessões de terminal

1. Introdução às ferramentas de gravação de terminal

Gravar sessões de terminal é uma prática essencial para documentação técnica, criação de tutoriais, depuração de problemas e compartilhamento de conhecimento. Duas ferramentas se destacam nesse cenário: o clássico comando script, presente em praticamente todos os sistemas Unix, e o moderno asciinema, que oferece gravação leve com reprodução web integrada.

O comando script é um utilitário tradicional que captura toda a saída do terminal em um arquivo de texto, incluindo caracteres de controle. Já o asciinema adota uma abordagem mais sofisticada: grava metadados temporais e a sequência de caracteres, permitindo reprodução interativa e incorporação em páginas web.

A principal diferença entre eles está no formato de saída e nas possibilidades de compartilhamento. Enquanto script gera arquivos de texto puro que podem ser lidos diretamente, asciinema produz arquivos .cast (JSON), otimizados para reprodução fiel e distribuição online.

2. Gravando sessões com o comando script

A sintaxe básica do script é simples. Para iniciar uma gravação:

script minha_sessao.txt

Todo o conteúdo exibido no terminal a partir desse momento será registrado. Para encerrar, digite exit ou pressione Ctrl+D.

Opções importantes incluem:

  • -a (append): adiciona nova gravação ao final de um arquivo existente
  • -q (quiet): suprime mensagens de início e fim da gravação
  • -t (timing): gera um arquivo separado com informações de tempo

Para gravar com timing, essencial para reprodução sincronizada:

script -t 2> timing.log sessao_com_tempo.txt

O arquivo timing.log contém pares de valores (atraso em segundos e número de caracteres), permitindo que a reprodução simule o ritmo original.

Para reproduzir uma gravação com timing:

scriptreplay timing.log sessao_com_tempo.txt

Esse comando reexecuta a sessão no terminal atual, respeitando os intervalos de tempo originais.

3. Trabalhando com arquivos gerados pelo script

Os arquivos gerados pelo script são chamados de "typescript" (nome padrão quando nenhum arquivo é especificado). Eles contêm texto puro misturado com caracteres de controle ANSI, como sequências de escape para cores e posicionamento.

Para extrair texto limpo, removendo caracteres especiais:

cat -v tiposcript | sed 's/\^\[\[[0-9;]*m//g' > texto_limpo.txt

Ou usando ferramentas modernas:

cat tiposcript | perl -pe 's/\e\[[\d;]*m//g' > texto_limpo.txt

A conversão para formatos modernos pode ser feita com scripts que transformam o typescript em HTML ou Markdown. No entanto, as limitações são claras: não há suporte nativo a cores avançadas, animações ou reprodução web interativa. O script é ideal para logs e documentação textual, mas não para tutoriais visuais.

4. Introdução ao asciinema: instalação e primeiros passos

O asciinema pode ser instalado facilmente:

# No Ubuntu/Debian
sudo apt install asciinema

# No macOS
brew install asciinema

# Via pip
pip install asciinema

Para iniciar uma gravação básica:

asciinema rec minha_gravacao.cast

A gravação continua até que você pressione Ctrl+D ou digite exit. Para reproduzir localmente:

asciinema play minha_gravacao.cast

Opções úteis na linha de comando:

  • --title "Meu tutorial": define um título para a gravação
  • --max-wait 2: limita pausas longas a 2 segundos durante a reprodução
  • --overwrite: sobrescreve arquivo existente sem confirmação

A diferença crucial é que, por padrão, o asciinema pergunta se você deseja fazer upload para asciinema.org. Para evitar isso, use o modo local com o parâmetro --local ou especifique um arquivo de saída.

5. Recursos avançados do asciinema

O asciinema permite usar o script como backend para gravação de entrada padrão:

asciinema rec --stdin sessao_com_input.cast

Isso captura não apenas a saída, mas também os comandos digitados, útil para tutoriais interativos.

Para controle fino da gravação, é possível pausar manualmente com Ctrl+P (se configurado) ou usar o modo de gravação com tempo máximo por inatividade:

asciinema rec --max-wait 1.5 tutorial.cast

Editando metadados diretamente:

asciinema rec --title "Instalação do Docker" --idle-time-limit 2 instalacao.cast

Para exportar gravações como GIF animado, ferramentas como agg (asciinema gif generator) são recomendadas:

# Instalar agg
pip install agg

# Converter para GIF
agg minha_gravacao.cast animacao.gif

Outra alternativa é o ttygif, que converte gravações do terminal em GIFs.

6. Reprodução e compartilhamento de gravações

A reprodução local é direta:

asciinema play --speed 2 tutorial.cast

Para incorporar em páginas web, o asciinema oferece um player JavaScript. Basta incluir:

<script src="https://asciinema.org/a/12345.js" id="asciicast-12345" async></script>

Ou, para self-hosted, baixar o player do repositório oficial e configurar:

<link rel="stylesheet" type="text/css" href="/asciinema-player.css" />
<div id="player"></div>
<script src="/asciinema-player.js"></script>
<script>
  AsciinemaPlayer.create('/caminho/arquivo.cast', document.getElementById('player'));
</script>

Opções de player incluem speed, loop, autoplay, theme e cols/rows. Exemplo:

AsciinemaPlayer.create('demo.cast', document.getElementById('player'), {
  speed: 1.5,
  loop: true,
  autoplay: true,
  theme: 'monokai'
});

Para compartilhar via asciinema.org, use asciinema rec sem especificar arquivo — ao final, o programa pergunta se deseja fazer upload. Também é possível hospedar em servidor próprio usando o asciinema-server.

7. Automação e integração com scripts

O script pode ser usado dentro de scripts Bash para logging automático:

#!/bin/bash
LOG_DIR="/var/log/sessoes"
mkdir -p "$LOG_DIR"
script -q -t 2>"$LOG_DIR/timing_$(date +%Y%m%d_%H%M).log" \
  "$LOG_DIR/sessao_$(date +%Y%m%d_%H%M).txt"

Para integrar o asciinema com Makefile:

.PHONY: demo
demo:
    asciinema rec --overwrite --title "Demonstração do projeto" demo.cast
    @echo "Gravação concluída. Execute 'make play' para reproduzir."

.PHONY: play
play:
    asciinema play demo.cast

Exemplo de script que grava e faz upload automático:

#!/bin/bash
ARQUIVO="tutorial_$(date +%Y%m%d).cast"
asciinema rec --title "Tutorial Automatizado" "$ARQUIVO"
echo "Gravação salva em $ARQUIVO"
# Upload automático (requer token de API)
asciinema upload "$ARQUIVO"

Para evitar gravação de informações sensíveis, use filtros no shell ou edite o arquivo .cast manualmente (é JSON). Configure ASCIINEMA_REC=1 para que scripts possam detectar se estão sendo gravados e ocultar senhas.

8. Comparação final e boas práticas

Quando usar script:
- Logs de sessão para auditoria
- Documentação textual simples
- Ambientes onde asciinema não está disponível
- Gravação de longa duração (menos overhead)

Quando usar asciinema:
- Tutoriais interativos para web
- Demonstrações de software
- Compartilhamento rápido com equipes
- Conteúdo que exige reprodução fiel de cores e animações

Vantagens do script:
- Simplicidade: não requer instalação adicional
- Disponibilidade universal em sistemas Unix
- Arquivos de texto puro, fáceis de processar

Vantagens do asciinema:
- Reprodução web interativa e leve
- Metadados temporais para ritmo natural
- Compartilhamento via URL ou incorporação
- Edição e personalização do player

Checklist para uma gravação profissional de terminal:
1. Planeje o roteiro da demonstração
2. Limpe o terminal antes de começar
3. Use temas de cores legíveis
4. Defina um título descritivo
5. Evite pausas muito longas (use --max-wait)
6. Revise a gravação antes de compartilhar
7. Remova informações sensíveis manualmente
8. Escolha a ferramenta adequada ao público-alvo

Ambas as ferramentas são complementares e, combinadas, cobrem desde logs simples até tutoriais interativos de alta qualidade.

Referências