Automatize capturas de tela no Mac pela linha de comando

Todo Mac inclui o screencapture, o comando por trás dos atalhos de captura de tela do sistema. Chamado a partir de um loop no zsh, ele tira capturas cronometradas da tela inteira ou de uma área fixa, sem software adicional. Este post monta o loop uma peça por vez, acrescenta viradas de página e lista as correções para as falhas mais comuns.

Verifique a permissão antes de depurar o comando

screencapture roda com as permissões do app que o iniciou. No Terminal, isso significa que o Terminal precisa da permissão de gravação de tela. Sem ela, o comando continua funcionando, mas a imagem mostra apenas o papel de parede e a barra de menus.

Abra System Settings, depois Privacy and Security, e ative o app de terminal (Terminal, iTerm ou outro) na lista Screen recording. O nome exato varia conforme a versão do macOS. Feche e reabra o app de terminal após a alteração.

Confirme a permissão com uma captura de teste

Uma captura de teste mostra se o macOS permite que o terminal leia a tela. Capture com várias janelas abertas e depois abra o arquivo. Se a imagem mostrar as janelas, a permissão está funcionando. Se mostrar apenas o papel de parede e a barra de menus, a permissão está ausente ou o terminal não foi reiniciado após a alteração.

Apague o arquivo de teste após a verificação. Ele é uma imagem da tela inteira e pode mostrar conteúdo privado.

Tire uma captura de tela pelo Terminal

Comece com uma única captura antes de escrever qualquer loop:

screencapture -x ~/Desktop/test.png
open ~/Desktop/test.png

A flag -x desativa o som do obturador. Se a imagem mostrar suas janelas abertas, a permissão e os caminhos estão funcionando. Execute man screencapture para ver todas as flags que a sua versão do macOS suporta.

Flags usadas neste post

As flags diferenciam maiúsculas de minúsculas. -c copia a imagem para a área de transferência, e -C adiciona o ponteiro à imagem. Combine flags como argumentos separados, por exemplo screencapture -x -m -t jpg arquivo.jpg.

O atraso -T roda antes de cada comando screencapture. Dentro de um loop, ele soma o atraso a cada quadro. Use sleep no loop quando o atraso for necessário apenas uma vez.

Capture a tela inteira a cada poucos segundos

Este loop faz 20 capturas, com 3 segundos de intervalo, em uma nova pasta com o nome do horário de início:

#!/bin/zsh
out=~/Captures/run-$(date +%Y%m%d-%H%M%S)
mkdir -p "$out"

for i in {1..20}; do
  screencapture -x -m "$out/frame-$(printf %04d $i).png"
  sleep 3
done
echo "Saved 20 frames to $out"

Nomes com zeros à esquerda (frame-0001.png) mantêm os arquivos na ordem de captura no Finder e em qualquer ferramenta que ordene por nome. A flag -m limita a captura à tela principal. Sem ela, um Mac com duas telas exige um nome de arquivo para cada tela. Use -D 2 para capturar a tela secundária.

Salve o script como capture.sh, execute chmod +x capture.sh e depois ./capture.sh. Pressione Control+C para parar antes do fim. Os quadros já salvos permanecem na pasta.

Calcule a duração da execução

O loop dorme após cada captura, inclusive a última. Assim, uma execução de 20 quadros dorme 60 segundos no total. Cada captura também leva um pouco de tempo, então a execução real dura um pouco mais do que a soma das pausas. A linha do tempo abaixo não inclui o tempo de captura.

Para definir uma execução pela duração, divida a duração pelo intervalo. Uma execução de 10 minutos que captura um quadro a cada 5 segundos precisa de 600 dividido por 5, o que resulta em 120 quadros. Defina a contagem do loop como 120 e a pausa como 5:

for i in {1..120}; do
  screencapture -x -m "$out/frame-$(printf %04d $i).png"
  sleep 5
done

Se uma captura levar 0,2 segundo, as 120 capturas somam 24 segundos, e a execução dura cerca de 624 segundos. Meça o tempo de captura no seu Mac com time screencapture -x ~/Desktop/timing.png e depois apague o arquivo de teste.

Nomeie os quadros para facilitar a busca depois

Um nome que inclui a etapa facilita encontrar os quadros após a execução. Faça o loop sobre uma lista de nomes de etapas dentro da mesma pasta $out:

steps=(login dashboard export)
for s in $steps; do
  screencapture -x -m "$out/$s.png"
  sleep 2
done

Use também uma pasta por tarefa. O carimbo de data e hora no nome da pasta mostra quando a execução começou, e o nome da tarefa mostra o que ela cobre. Uma pasta como Captures/onboarding-run-20261103-101500 separa duas execuções do mesmo dia e permite encontrar uma execução sem abrir cada arquivo.

Nomes sem espaços evitam problemas de aspas no shell. Mantenha os números com zeros à esquerda quando a ordem de captura importar e os nomes das etapas não.

Encerre o loop corretamente

Control+C encerra o loop imediatamente. Os quadros já salvos permanecem na pasta, mas o script não imprime nenhum resumo. Adicione um trap acima do loop para imprimir a contagem quando a interrupção chegar:

trap 'echo "Stopped after $i frames"; exit 0' INT

INT é o sinal que o Control+C envia. O trap lê $i no momento em que o sinal chega, então informa o número do último quadro iniciado. Uma execução interrompida durante uma captura pode deixar o arquivo mais recente incompleto. Apague esse arquivo antes de abrir a pasta em uma ferramenta de PDF, ou compare o tamanho dele com o dos quadros anteriores.

Capture repetidamente uma área fixa

Acrescente -R x,y,w,h para capturar um retângulo. Os valores são em pontos, medidos a partir do canto superior esquerdo da tela principal:

screencapture -x -R 200,120,1200,800 "$out/frame-$(printf %04d $i).png"

Para encontrar as coordenadas, pressione Shift+Command+4 e observe os números ao lado da mira nos cantos superior esquerdo e inferior direito da área. A largura é a borda direita menos a borda esquerda, e a altura é a borda inferior menos a borda superior. A tabela abaixo lista as teclas usadas nesta etapa.

Um retângulo fixo não acompanha uma janela. Se a janela se mover ou a disposição das telas mudar durante a execução, os quadros seguintes capturarão a área errada.

Converta pontos em pixels em telas Retina

Os valores de -R estão em pontos, mas o arquivo salvo contém pixels. Em uma tela Retina, cada ponto corresponde a dois pixels em cada direção, então um retângulo de 1200 por 800 pontos é salvo como uma imagem de 2400 por 1600 pixels. As configurações de escala alteram o fator, então meça um quadro salvo em vez de presumir um valor:

sips -g pixelWidth -g pixelHeight "$out/frame-0001.png"

A comparação abaixo mostra o tamanho salvo de duas regiões em uma tela 2x e em uma tela 1x.

Um recorte baseado em pixels ou uma especificação de design precisa dos valores em pixels. Uma captura planejada em pontos precisa de valores em pontos no -R. Misturar as duas unidades produz quadros maiores ou menores que o layout planejado.

Salve arquivos JPG em vez de PNG

Use -t jpg e altere a extensão:

screencapture -x -t jpg "$out/frame-$(printf %04d $i).jpg"

PNG mantém as bordas do texto nítidas e é o padrão mais seguro para interfaces. Arquivos JPG são menores, o que importa em execuções com centenas de quadros. O comando também aceita pdf e tiff.

Escolha o formato para uma execução longa

Uma execução de 500 quadros gera 500 arquivos no formato escolhido. Escolha JPG quando o tamanho da pasta for mais importante do que bordas de texto nítidas. Escolha PNG quando o leitor precisar ampliar rótulos pequenos. Passe -t png explicitamente nos scripts para que o formato fique visível no código.

Meça um quadro de cada formato antes de uma execução longa. Execute du -h no arquivo e depois multiplique o tamanho pelo número de quadros para estimar o tamanho da pasta.

Pressione uma tecla entre as capturas sem pular páginas

Passar slides ou páginas em um leitor exige uma tecla pressionada após cada captura. O osascript envia a tecla pelo System Events. O código de tecla 124 é a seta para a direita:

pages=30
for i in {1..$pages}; do
  screencapture -x -m "$out/page-$(printf %04d $i).png"
  if (( i < pages )); then
    osascript -e 'tell application "System Events" to key code 124'
    sleep 1.5
  fi
done

Três detalhes evitam páginas perdidas ou extras. A captura roda primeiro, então a página inicial é salva. O if pula o pressionamento de tecla após a última captura, para que o leitor não avance além da última página. O sleep após a tecla dá tempo para a próxima página renderizar antes da próxima captura.

O System Events envia teclas para o app em primeiro plano, então clique na janela do leitor antes de o loop começar, ou adicione um sleep 5 no início para trocar de app. O Terminal precisa da permissão de Acessibilidade para enviar eventos de tecla.

Códigos de tecla para viradas de página

O osascript identifica uma tecla pelo código de tecla virtual do macOS, não pelo caractere que ela digita. Estes códigos cobrem as teclas mais usadas para virar páginas e confirmar ações:

Tecla	Código
Seta para a esquerda	123
Seta para a direita	124
Seta para baixo	125
Seta para cima	126
Espaço	49
Return	36

Alguns leitores só viram páginas quando um controle específico tem o foco. Teste a tecla em uma execução de 3 páginas antes de uma execução longa e confirme que cada página muda.

Ordene a captura e o pressionamento de tecla

A ordem dentro do loop define qual página cada quadro mostra. O loop desta seção captura primeiro e pressiona a tecla em seguida. O fluxo abaixo mostra um ciclo.

Se a tecla viesse primeiro, cada quadro mostraria a página seguinte à que está na tela, e a primeira página nunca seria salva.

A pausa após a tecla define o ritmo. Uma página renderizada a partir de um arquivo local geralmente termina dentro da pausa de 1,5 segundo usada neste post. Um leitor que carrega imagens pela rede pode precisar de 3 a 5 segundos em algumas páginas. Verifique a página mais lenta do documento, não a primeira, porque uma página cheia de imagens define a espera mínima.

Duas verificações pegam a maioria dos erros de virada de página antes de uma execução longa:

• Execute 3 páginas e abra os 3 quadros. Cada quadro deve mostrar uma página diferente, na ordem certa.
• Compare o último quadro com a última página do documento. Se o último quadro repetir uma página, o loop pressionou a tecla uma vez a mais ou a pausa foi curta demais.

Mantenha uma execução longa acordada

Se a tela entrar em suspensão, os quadros saem pretos. Envolva o script com caffeinate, que mantém uma asserção de suspensão enquanto o script estiver em execução:

caffeinate -di ./capture.sh

A flag -d mantém a tela ativa e -i impede a suspensão por inatividade. O caffeinate mantém o Mac acordado, mas não mantém a tela desbloqueada. Quadros capturados com a tela bloqueada mostram a tela de bloqueio, não o app. Para um MacBook que continue ativo com a tampa fechada na energia, adicione -s. A página de manual do caffeinate informa que essa flag se aplica apenas enquanto o Mac estiver conectado à tomada.

Solucione uma execução do screencapture que falhou

Sintoma	Causa	Correção
Apenas papel de parede e barra de menus	Sem permissão de gravação de tela	Permita o app de terminal e reabra-o
"No such file or directory"	Pasta de saída ausente	Execute mkdir -p antes do loop
Duas imagens ou um erro por captura	Várias telas, um nome de arquivo	Adicione -m ou -D 1
Quadros pretos	A tela entrou em suspensão	Execute o script com caffeinate -di
Páginas puladas	Tecla enviada antes de a página renderizar	Aumente o sleep após a tecla
Pressionamentos de tecla ignorados	Permissão de Acessibilidade ausente ou app errado em primeiro plano	Permita o app de terminal e clique na janela de destino

Verifique a pasta de saída

Uma execução concluída deixa uma pasta por execução, com nomes de quadros que ordenam na ordem de captura. A árvore abaixo mostra uma execução que começou às 10:15:00 de 3 de novembro de 2026, com quatro quadros. Os quadros de 5 a 20 seguem o mesmo padrão.

Diagnostique quadros que parecem idênticos

Quando todos os quadros mostram o mesmo conteúdo, verifique estas causas nesta ordem:

1. O alvo não mudou entre as capturas. O loop salva o que está na tela, então uma página que não vira ou um diálogo que permanece aberto gera quadros idênticos. Adicione um pressionamento de tecla ou uma espera maior.
2. Outra janela cobre o alvo. -R e -m capturam a região da tela, não a janela que está por trás. Traga a janela de destino para a frente e mantenha-a ali durante toda a execução.
3. O intervalo é menor do que a mudança. Uma barra de progresso que se move a cada 10 segundos parece estática com intervalo de 1 segundo. Verifique os quadros com um intervalo maior antes de alterar o loop.

Compare os arquivos do primeiro e do último quadro com shasum -a 256 se não tiver certeza de que dois arquivos são diferentes. Hashes idênticos confirmam pixels idênticos.

Conte os arquivos após cada execução. Uma execução de 20 quadros deve deixar 20 arquivos. Uma contagem menor significa que o loop parou cedo ou que uma captura falhou com a mensagem mostrada no terminal.

Quando um script deixa de ser a opção mais simples

Um loop de shell serve para uma tarefa fixa que roda sempre do mesmo jeito. Cada novo requisito acrescenta código: parar em um horário, pausar e retomar, escolher uma janela pelo nome (a flag -l exige um ID de janela que o macOS não lista para você) ou gerar um PDF pesquisável.

O Auto Capture do Temposhot transforma esses itens em configurações. Você escolhe Screens, Windows ou Custom Area a partir de miniaturas, define Screenshots, Duration ou End time como condição de parada e registra qualquer tecla no campo Key press. Uma barra flutuante pausa, retoma e finaliza a execução. As exportações incluem PNG, JPG, ZIP, PDF pesquisável, MP4 e GIF. O WebP aparece somente quando o Mac tem um codificador WebP.

Relacione cada escolha do script a uma configuração

Cada decisão do script tem uma configuração correspondente no Auto Capture. As etapas abaixo recriam o loop de virada de página no Temposhot:

Antes de trocar, decida qual parte do script ainda é necessária. O Auto Capture cobre os casos comuns: uma série cronometrada de uma tela, uma janela ou um retângulo, com uma tecla opcional entre os quadros. Ele não executa comandos de shell arbitrários entre as capturas, então um script com lógica personalizada, como renomear arquivos a partir de uma planilha, continua no shell.

O mapeamento dos exemplos deste post:

• O loop de 20 quadros com pausa de 3 segundos vira uma condição de parada Screenshots de 20 e um intervalo de 3 segundos.
• A execução de 10 minutos com um quadro a cada 5 segundos vira uma condição de parada Duration de 10 minutos e um intervalo de 5 segundos. Duration e End time exigem um intervalo maior que zero.
• O loop de virada de página vira um Key press com Right Arrow e um intervalo de 1,5 segundo. Key press é um recurso do Pro e exige a permissão de Acessibilidade.
• O retângulo fixo vira Custom Area. Arraste o retângulo até que a sobreposição mostre a largura e a altura que você precisa.

O plano gratuito limita o número de capturas por sessão. Uma execução que precisa de mais quadros exige o Temposhot Pro.

Duas configurações costumam diferir dos padrões do script. A contagem regressiva tem 3 segundos por padrão, o que dá tempo para colocar a página no estado inicial. Defina 5 ou 10 segundos quando o alvo precisar de mais tempo para carregar depois que você pressiona Start. O intervalo tem 1 segundo por padrão, então defina-o explicitamente em cada execução.

Mantenha o script para tarefas fixas

Use o script quando a tarefa for fixa e o mesmo comando rodar em todas as máquinas, por exemplo uma captura noturna de um painel local iniciada por um cron job. Um script também é fácil de manter sob controle de versão, o que registra cada mudança no tempo ou na região.

Uma sessão do Temposhot serve para uma tarefa executada por uma pessoa que acompanha a tela, pausa para uma pergunta e quer o resultado no app. As duas abordagens podem gerar os mesmos quadros. A diferença está em quem mantém as instruções: um script fica em um arquivo, e uma configuração do Auto Capture fica no app e segue os padrões salvos.

FAQ

Para onde o screencapture salva os arquivos?

Ele salva no caminho passado como último argumento. Com -c, copia a imagem para a área de transferência.

O screencapture pode incluir o cursor?

Sim. Adicione -C para incluir o ponteiro. Isso funciona apenas em capturas não interativas, que cobrem todos os comandos deste post.

Como adiciono um atraso antes da primeira captura?

Use -T 5 para um atraso de 5 segundos em uma única captura, ou coloque sleep 5 antes do loop.

Posso transformar os quadros em um PDF ou vídeo?

Sim. Image to PDF combina os quadros em um único PDF na ordem dos nomes, e Images to Video os transforma em um vídeo. Ambos rodam no navegador e mantêm os arquivos no seu Mac.

O screencapture pode capturar uma janela só?

Sim, com -l e um ID numérico de janela. O Terminal não lista IDs de janela, então o ID precisa vir de outra ferramenta. A aba Windows do Auto Capture seleciona uma janela a partir de miniaturas.

Por que os quadros ficam fora de ordem depois do quadro 9999?

O formato %04d imprime pelo menos quatro dígitos. A partir do quadro 10000, nomes como frame-10000.png são ordenados antes de frame-9999.png na ordem por nome. Use %05d para execuções com mais de 9999 quadros.

Os quadros são mantidos depois do Control+C?

Sim. Os quadros salvos antes da interrupção permanecem na pasta. O trap da seção acima imprime a contagem quando o script para.

Transforme capturas repetíveis em trabalho concluído

Quando o script passar de uma região fixa e de uma contagem fixa, experimente o Auto Capture. O guia de captura automatizada cobre todas as opções, e a página de download tem a versão para Apple Silicon.