Automatizar capturas de pantalla en Mac desde la línea de comandos

Todos los Mac incluyen screencapture, el comando que hay detrás de los atajos de captura del sistema. Llamado desde un bucle de zsh, toma capturas temporizadas de la pantalla completa o de un área fija sin software adicional. Este artículo construye el bucle paso a paso, añade cambios de página y enumera las soluciones a los fallos que aparecen con más frecuencia.

Comprueba el permiso antes de depurar el comando

screencapture se ejecuta con los permisos de la app que lo inició. En Terminal, eso significa que Terminal necesita el permiso de grabación de pantalla. Sin él, el comando sigue completándose correctamente, pero la imagen muestra solo el fondo de escritorio y la barra de menús.

Abre System Settings, después Privacy and Security, y activa tu app de terminal (Terminal, iTerm u otra) en la lista de grabación de pantalla. El nombre exacto de la opción varía según la versión de macOS. Cierra y vuelve a abrir la app de terminal después del cambio.

Confirma el permiso con una captura de prueba

Una captura de prueba muestra si macOS deja que la terminal lea la pantalla. Haz una captura con varias ventanas abiertas y después abre el archivo. Si la imagen muestra las ventanas, el permiso funciona. Si muestra solo el fondo de escritorio y la barra de menús, falta el permiso o no se reinició la terminal después del cambio.

Borra el archivo de prueba después de la comprobación. Es una imagen de pantalla completa y puede mostrar contenido privado.

Toma una captura desde Terminal

Empieza con una sola captura antes de escribir cualquier bucle:

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

La opción -x desactiva el sonido del obturador. Si la imagen muestra tus ventanas abiertas, el permiso y las rutas funcionan. Ejecuta man screencapture para ver todas las opciones que admite tu versión de macOS.

Opciones usadas en este artículo

Las opciones distinguen mayúsculas de minúsculas. -c copia la imagen al portapapeles, y -C añade el puntero a la imagen. Combina las opciones como argumentos separados, por ejemplo screencapture -x -m -t jpg file.jpg.

El retardo -T se ejecuta antes de cada comando screencapture. Dentro de un bucle, añade el retardo a cada fotograma. Usa sleep en el bucle cuando el retardo solo se aplique una vez.

Captura la pantalla completa cada pocos segundos

Este bucle hace 20 capturas, separadas 3 segundos, en una carpeta nueva con el nombre de la hora de inicio:

#!/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"

Los nombres con ceros a la izquierda (frame-0001.png) mantienen los archivos en orden de captura en el Finder y en cualquier herramienta que ordene por nombre. La opción -m limita la captura a la pantalla principal. Sin ella, un Mac con dos pantallas espera un nombre de archivo por cada pantalla. Usa -D 2 para capturar la pantalla secundaria.

Guarda el script como capture.sh, ejecuta chmod +x capture.sh y después ./capture.sh. Pulsa Control+C para detener antes de tiempo. Los fotogramas ya guardados permanecen en la carpeta.

Calcula la duración de la ejecución

El bucle duerme después de cada captura, incluida la última. Por tanto, una ejecución de 20 fotogramas duerme 60 segundos en total. Cada captura también tarda un poco, así que la ejecución real dura algo más que la suma de los tiempos de espera. La línea de tiempo siguiente no incluye el tiempo de captura.

Para definir una ejecución por duración, divide la duración entre el intervalo. Una ejecución de 10 minutos que toma un fotograma cada 5 segundos necesita 600 dividido entre 5, es decir, 120 fotogramas. Define el recuento del bucle en 120 y la espera en 5:

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

Si una captura tarda 0,2 segundos, las 120 capturas suman 24 segundos, así que la ejecución dura unos 624 segundos. Mide el tiempo de captura en tu Mac con time screencapture -x ~/Desktop/timing.png, y después borra el archivo de prueba.

Nombra los fotogramas para buscarlos después

Un nombre que incluye el paso facilita encontrar los fotogramas después de la ejecución. Recorre una lista de nombres de paso dentro de la misma carpeta $out:

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

Mantén también una carpeta por tarea. La marca de tiempo del nombre de la carpeta indica cuándo empezó una ejecución, y el nombre de la tarea indica lo que cubre. Una carpeta como Captures/onboarding-run-20261103-101500 separa dos ejecuciones del mismo día y permite encontrar una ejecución sin abrir cada archivo.

Los nombres sin espacios evitan problemas de comillas en el shell. Mantén los números con ceros a la izquierda cuando importe el orden de captura y los nombres de paso no.

Detén el bucle de forma limpia

Control+C termina el bucle al instante. Los fotogramas ya guardados permanecen en la carpeta, pero el script no imprime ningún resumen. Añade una trampa antes del bucle para imprimir el recuento cuando llegue la interrupción:

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

INT es la señal que envía Control+C. La trampa lee $i cuando llega la señal, así que informa del último número de fotograma que empezó. Una ejecución detenida durante una captura puede dejar incompleto el archivo más reciente. Borra ese archivo antes de abrir la carpeta en una herramienta de PDF, o compara su tamaño con el de los fotogramas anteriores.

Captura un área fija repetidamente

Añade -R x,y,w,h para capturar un rectángulo. Los valores están en puntos, medidos desde la esquina superior izquierda de la pantalla principal:

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

Para encontrar las coordenadas, pulsa Shift+Command+4 y observa los números junto a la cruz en las esquinas superior izquierda e inferior derecha del área. El ancho es el borde derecho menos el borde izquierdo, y la altura es el borde inferior menos el borde superior. La tabla siguiente enumera las teclas usadas alrededor de este paso.

Un rectángulo fijo no sigue a una ventana. Si la ventana se mueve o cambia la disposición de las pantallas durante la ejecución, los fotogramas posteriores capturan el área equivocada.

Convierte puntos en píxeles en pantallas Retina

Los valores de -R están en puntos, pero el archivo guardado contiene píxeles. En una pantalla Retina, cada punto cubre dos píxeles en cada dirección, así que un rectángulo de 1200 por 800 puntos se guarda como una imagen de 2400 por 1600 píxeles. Los ajustes de escala cambian el factor, así que mide un fotograma guardado en lugar de suponer un valor:

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

La comparación siguiente muestra el tamaño guardado de dos regiones en una pantalla 2x y en una pantalla 1x.

Un recorte basado en píxeles o una especificación de diseño necesita los valores en píxeles. Una captura planificada en puntos necesita valores en puntos en -R. Mezclar las dos unidades produce fotogramas más grandes o más pequeños que la maquetación que planificaste.

Guarda archivos JPG en lugar de PNG

Usa -t jpg y cambia la extensión:

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

PNG mantiene nítidos los bordes del texto y es el valor predeterminado más seguro para interfaces. Los archivos JPG son más pequeños, lo que importa en ejecuciones con cientos de fotogramas. El comando también acepta pdf y tiff.

Elige el formato para una ejecución larga

Una ejecución de 500 fotogramas produce 500 archivos en el formato elegido. Elige JPG cuando el tamaño de la carpeta importe más que los bordes nítidos del texto. Elige PNG cuando un lector deba ampliar etiquetas pequeñas. Pasa -t png explícitamente en los scripts para que el formato se vea en el código.

Mide un fotograma de cada formato antes de una ejecución larga. Ejecuta du -h sobre el archivo, y después multiplica el tamaño por el número de fotogramas para estimar el tamaño de la carpeta.

Pulsa una tecla entre capturas sin pasarse

Pasar diapositivas o páginas de un lector necesita una pulsación de tecla después de cada captura. osascript envía una a través de System Events. El código de tecla 124 corresponde a Right Arrow:

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

Tres detalles evitan páginas perdidas o sobrantes. La captura se ejecuta primero, así que se guarda la página inicial. El if omite la pulsación de tecla después de la última captura, para que el lector no pase más allá de la página final. El sleep después de la tecla da tiempo a que la página siguiente se renderice antes de la siguiente captura.

System Events envía las teclas a la app que está en primer plano, así que haz clic en la ventana del lector antes de que empiece el bucle, o añade un sleep 5 al principio para cambiar de app. Terminal necesita el permiso de Accessibility para los eventos de teclado.

Códigos de tecla para pasar páginas

osascript identifica una tecla por su código de tecla virtual de macOS, no por el carácter que escribe. Estos códigos cubren las teclas que más se usan para pasar páginas y confirmar acciones:

Tecla	Código
Flecha izquierda	123
Flecha derecha	124
Flecha abajo	125
Flecha arriba	126
Espacio	49
Return	36

Algunos lectores solo pasan páginas cuando un control específico tiene el foco. Prueba la tecla en una ejecución de 3 páginas antes de una ejecución larga, y comprueba que cada página cambia.

Ordena la captura y la pulsación de tecla

El orden dentro del bucle decide qué página muestra cada fotograma. El bucle de esta sección captura primero y pulsa la tecla después. El flujo siguiente muestra un ciclo.

Si la tecla fuera primero, cada fotograma mostraría la página posterior a la que está en pantalla, y la primera página nunca se guardaría.

La espera después de la tecla marca el ritmo. Una página que se renderiza desde un archivo local normalmente termina dentro de la espera de 1,5 segundos usada en este artículo. Un lector que carga imágenes por red puede necesitar de 3 a 5 segundos en algunas páginas. Revisa la página más lenta del documento, no la primera, porque una página llena de imágenes fija la espera mínima.

Dos comprobaciones detectan la mayoría de los errores de cambio de página antes de una ejecución larga:

• Ejecuta 3 páginas y abre los 3 fotogramas. Cada fotograma debe mostrar una página distinta, en orden.
• Compara el último fotograma con la última página del documento. Si el último fotograma repite una página, el bucle pulsó la tecla una vez de más o la espera fue demasiado corta.

Mantén despierto un bucle largo

Si la pantalla entra en reposo, los fotogramas salen en negro. Envuelve el script en caffeinate, que mantiene una aserción de reposo mientras el script se ejecuta:

caffeinate -di ./capture.sh

La opción -d mantiene la pantalla encendida e -i impide el reposo por inactividad. caffeinate mantiene el Mac despierto, pero no mantiene la pantalla desbloqueada. Los fotogramas tomados mientras la pantalla está bloqueada muestran la pantalla de bloqueo, no la app. Para un MacBook que sigue despierto con la tapa cerrada conectado a la corriente, añade -s. La página de manual de caffeinate indica que esa opción solo se aplica mientras el Mac funciona con corriente alterna.

Soluciona una ejecución fallida de screencapture

Síntoma	Causa	Solución
Solo fondo de escritorio y barra de menús	Falta el permiso de grabación de pantalla	Activa la app de terminal y vuelve a abrirla
"No such file or directory"	Falta la carpeta de salida	Ejecuta mkdir -p antes del bucle
Dos imágenes o un error por captura	Varias pantallas, un nombre de archivo	Añade -m o -D 1
Fotogramas negros	La pantalla entró en reposo	Ejecuta el script con caffeinate -di
Páginas saltadas	La tecla se envió antes de renderizar la página	Aumenta el sleep después de la tecla
Las pulsaciones de tecla se ignoran	Falta el permiso de Accessibility o hay otra app delante	Activa la app de terminal, haz clic en la ventana de destino

Comprueba la carpeta de salida

Una ejecución terminada deja una carpeta por ejecución, con nombres de fotograma que se ordenan en orden de captura. El árbol siguiente muestra una ejecución que empezó a las 10:15:00 del 3 de noviembre de 2026 con cuatro fotogramas. Los fotogramas del 5 al 20 siguen el mismo patrón.

Diagnostica fotogramas que parecen idénticos

Cuando todos los fotogramas muestran el mismo contenido, comprueba estas causas en orden:

1. El destino no cambió entre capturas. El bucle guarda lo que hay en pantalla, así que una página que nunca pasa, o un diálogo que sigue abierto, produce fotogramas idénticos. Añade una pulsación de tecla o una espera más larga.
2. Otra ventana tapa el destino. -R y -m capturan la región de la pantalla, no la ventana que hay detrás. Lleva la ventana de destino al frente y mantenla allí durante la ejecución.
3. El intervalo es más corto que el cambio. Una barra de progreso que se mueve cada 10 segundos parece estática con un intervalo de 1 segundo. Revisa los fotogramas con un intervalo más amplio antes de cambiar el bucle.

Compara los archivos del primer y del último fotograma con shasum -a 256 si no estás seguro de que dos archivos sean distintos. Los hashes idénticos confirman píxeles idénticos.

Cuenta los archivos después de cada ejecución. Una ejecución de 20 fotogramas debe dejar 20 archivos. Un recuento menor significa que el bucle se detuvo pronto, o que una captura falló con el mensaje que aparece en la terminal.

Cuando un script ya no es la opción fácil

Un bucle de shell encaja con un trabajo fijo que se ejecuta siempre de la misma forma. Cada requisito nuevo añade código: detenerse a una hora del reloj, pausar y reanudar, elegir una ventana por nombre (la opción -l necesita un ID de ventana que macOS no muestra), o producir un PDF buscable.

Auto Capture de Temposhot convierte esos requisitos en ajustes. Eliges Screens, Windows o Custom Area desde miniaturas, defines Screenshots, Duration o End time como condición de parada, y registras cualquier tecla en el campo Key press. Una barra flotante pausa, reanuda y finaliza la ejecución. Las exportaciones cubren PNG, JPG, ZIP, PDF buscable, MP4 y GIF. WebP aparece solo cuando el Mac tiene un codificador WebP.

Relaciona cada decisión del script con un ajuste

Cada decisión del script tiene un ajuste correspondiente en Auto Capture. Los pasos siguientes reconstruyen el bucle de cambio de página en Temposhot:

Antes de cambiar, decide qué parte del script todavía necesitas. Auto Capture cubre los casos habituales: una serie temporizada de una pantalla, una ventana o un rectángulo, con una pulsación de tecla opcional entre fotogramas. No ejecuta comandos de shell arbitrarios entre capturas, así que un script con lógica personalizada, como renombrar archivos desde una hoja de cálculo, se queda en el shell.

La correspondencia para los ejemplos de este artículo:

• El bucle de 20 fotogramas con una espera de 3 segundos se convierte en una condición de parada Screenshots de 20 y un intervalo de 3 segundos.
• La ejecución de 10 minutos con un fotograma cada 5 segundos se convierte en una condición de parada Duration de 10 minutos y un intervalo de 5 segundos. Duration y End time necesitan un intervalo mayor que cero.
• El bucle de cambio de página se convierte en una Key press de Right Arrow con un intervalo de 1,5 segundos. Key press es una función Pro y necesita el permiso de Accessibility.
• El rectángulo fijo se convierte en Custom Area. Arrastra el rectángulo hasta que la superposición muestre el ancho y la altura que necesitas.

El plan gratuito limita el número de capturas por sesión. Una ejecución que necesite más fotogramas requiere Temposhot Pro.

Dos ajustes suelen diferir de los valores predeterminados del script. La cuenta atrás tiene 3 segundos por defecto, lo que da tiempo a llevar la página a su estado inicial. Ponla en 5 o 10 segundos cuando el destino necesite más tiempo para cargarse después de pulsar Start. El intervalo tiene 1 segundo por defecto, así que defínelo de forma explícita en cada ejecución.

Mantén el script para trabajos fijos

Usa el script cuando el trabajo sea fijo y el mismo comando se ejecute en cada equipo, por ejemplo una captura nocturna de un panel local que inicia un cron. Un script también es fácil de poner bajo control de versiones, lo que registra cada cambio en el tiempo o en la región.

Una sesión de Temposhot encaja con una tarea que lleva a cabo una persona que mira la pantalla, se detiene para responder una pregunta y quiere un resultado en la app. Ambos pueden producir los mismos fotogramas. La diferencia es quién mantiene las instrucciones: un script vive en un archivo, y una configuración de Auto Capture vive en la app y sigue los valores predeterminados guardados.

Preguntas frecuentes

¿Dónde guarda screencapture los archivos?

Guarda en la ruta que pasas como último argumento. Con -c, copia la imagen al portapapeles.

¿screencapture puede incluir el cursor?

Sí. Añade -C para incluir el puntero. Funciona solo en capturas no interactivas, que son todos los comandos de este artículo.

¿Cómo añado un retardo antes de la primera captura?

Usa -T 5 para un retardo de 5 segundos en una sola captura, o pon sleep 5 antes del bucle.

¿Puedo convertir los fotogramas en un PDF o un video?

Sí. Image to PDF combina los fotogramas en un solo PDF en orden de nombre, y Images to Video los convierte en un video. Ambas herramientas funcionan en el navegador y mantienen los archivos en tu Mac.

¿screencapture puede capturar una sola ventana?

Sí, con -l y un ID numérico de ventana. Terminal no muestra los ID de ventana, así que el ID debe obtenerse con otra herramienta. La pestaña Windows de Auto Capture selecciona una ventana desde miniaturas.

¿Por qué los fotogramas se desordenan después del fotograma 9999?

El formato %04d imprime al menos cuatro dígitos. A partir del fotograma 10000, nombres como frame-10000.png se ordenan antes que frame-9999.png en orden de nombre. Usa %05d para ejecuciones de más de 9999 fotogramas.

¿Se conservan los fotogramas después de Control+C?

Sí. Los fotogramas guardados antes de la interrupción permanecen en la carpeta. La trampa de la sección anterior imprime el recuento cuando el script se detiene.

Convierte capturas repetibles en trabajo terminado

Cuando el script crezca más allá de una región fija y un recuento fijo, prueba Auto Capture. La guía de captura automatizada cubre todas las opciones, y la página de descarga tiene la versión para Apple Silicon.