Gravação de Tela

Crie demonstrações animadas em GIF que mostram um recurso ou fluxo de trabalho em ação — com anotações, tempo variável e ritmo adequado. Útil para descrições de PR, documentação e notas de lançamento.

Quando Usar Esta Habilidade

Use esta habilidade quando precisar:

• Gravar uma interação de UI com várias etapas como um GIF animado
• Criar uma demonstração mostrando o comportamento antes/depois
• Construir tutoriais anotados para documentação ou notas de lançamento
• Mostrar a reprodução ou correção de um bug em ação

Pré-requisitos

pip install playwright Pillow imageio numpy scipy mss -q
playwright install chromium

Fluxo de Trabalho Principal

1. Capturar quadros

Use o Playwright para percorrer a interação e capturar cada quadro:

from playwright.async_api import async_playwright

async def record_frames(url, steps, width=1400, height=900):
    """
    steps: list of dicts with 'action' (async callable taking page)
           and 'name' (frame filename)
    """
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page(viewport={"width": width, "height": height})
        await page.goto(url, wait_until="networkidle")

        for step in steps:
            if step.get("action"):
                await step["action"](page)
                await page.wait_for_timeout(step.get("wait", 500))
            await page.screenshot(path=step["name"])

        await browser.close()

2. Montar GIF com imageio

Use imageio, não PIL, para gravação de GIF — o codificador GIF do PIL mescla quadros visualmente semelhantes, o que prejudica as animações.

import imageio.v3 as iio
from PIL import Image
import numpy as np

frames = []
durations = []

for frame_path, duration_ms in frame_list:
    img = Image.open(frame_path)
    frames.append(np.array(img))
    durations.append(duration_ms)

iio.imwrite("demo.gif", frames, duration=durations, loop=0)

3. Tempo de quadro variável

O tempo uniforme faz tudo parecer muito rápido ou muito lento. Use durações variáveis:

4. Anotar quadros

Aplique anotações a quadros específicos usando a habilidade image-annotations:

from PIL import Image, ImageDraw, ImageFont

def annotate_frame(frame_path, annotations, out_path):
    img = Image.open(frame_path)
    draw = ImageDraw.Draw(img)

    for ann in annotations:
        # Apply annotation (rect, arrow, label, etc.)
        pass

    img.save(out_path)

5. Anotações com fade-in

Para uma aparência suave das anotações:

def apply_fade(base_frame, annotation_layer, alpha):
    """Blend annotation onto frame at given alpha (0.0 to 1.0)"""
    blended = Image.blend(
        base_frame.convert("RGBA"),
        annotation_layer.convert("RGBA"),
        alpha
    )
    return blended.convert("RGB")

# 2-frame pop-in at 10fps: 50% then 100%
faded_frames = [
    apply_fade(base, annotations, 0.5),  # frame 1: half opacity
    apply_fade(base, annotations, 1.0),  # frame 2: full opacity
]

A 10fps, use 2 quadros de fade (0,2s no total). A 30fps, use 3-4 quadros. Curvas de aceleração ficam ruins em FPS baixo — um simples aparecimento é mais rápido e legível.

Construir como um Script

A lógica de anotação fica complexa para qualquer coisa além de demonstrações triviais. Escreva um script dedicado (por exemplo, annotate_gif.py) com funções em vez de código inline. Você iterará no tempo e no posicionamento.

Testar Animações

Sempre teste isoladamente primeiro — não reconstrua a demonstração completa para testar um ajuste de fade:

# Small test GIF: 10 bare frames → fade frames → 15 hold frames
# Add a frame counter overlay for debugging:
draw.text((10, height - 30), f"F{i}/{total} a={alpha:.0%} FADE",
          fill="white", font=small_font)

Gravação de Tela do Desktop (mss)

Para gravar aplicativos de desktop, terminais ou qualquer coisa fora de um navegador. Usa mss para captura de tela rápida.

import mss
from PIL import Image
import time

def record_gif(output_path, region=None, duration=5, fps=8):
    """Grava uma região da tela para GIF. region = {left, top, width, height} ou None para tela cheia."""
    with mss.mss() as sct:
        if region is None:
            region = sct.monitors[1]  # monitor principal

        frames = []
        t_end = time.time() + duration

…