animated-gif

GIF Animado

Três ferramentas, um núcleo de montagem. Escolha a rota que corresponde à entrada.

Entrada	Ferramenta	Movimento
Quadros de texto com cores ANSI	bin/ascii_gif.py	sequência de quadros
Pasta de fotos ou imagens	bin/pics_gif.py	pausa, transição, Ken Burns
Animação SVG ou HTML	bin/svg_gif.py	SMIL, CSS, ou predefinição rotate/pulse/fade

Todas as rotas compartilham bin/gifkit.py: uma paleta para todo o loop, grade de temporização de 10 ms, quadros consecutivos idênticos mesclados em atrasos maiores, escrita atômica, verificação de leitura.

Dependências

Pillow é necessário. SVG e HTML precisam de Node com Playwright e um shell headless Chromium.

python -c "import PIL; print(PIL.__version__)"
node -e "require('playwright')"
npx playwright install chromium --only-shell

Cada ferramenta imprime uma linha FALHA ... no stderr e sai com código 1 quando uma dependência ou entrada está faltando. Não tente novamente com os mesmos argumentos.

Fluxo de Trabalho

1. Escolha a rota da tabela. Leia a seção correspondente abaixo.
2. Execute a ferramenta com um caminho de saída explícito dentro do projeto em que está trabalhando. Não escreva em um diretório temporário do sistema ou na Área de Trabalho.
3. Mantenha o resumo impresso: contagem de quadros, duração, tamanho em pixels. Um caminho impresso é um GIF verificado.
4. Para trabalhos visuais, abra o GIF ou escreva --preview preview.png e inspecione essa imagem estática antes de relatar.
5. Relate o caminho absoluto mais as configurações relevantes: fps, tamanho, duração, modo.

Rota ASCII

A entrada é um arquivo de texto. Os quadros são separados por uma linha contendo apenas ---; um atraso opcional em ms segue o separador: --- 250. As cores ANSI SGR são respeitadas: 30-37, 90-97, 38;5;n e 38;2;r;g;b. Um diretório de arquivos .txt é lido como um quadro por arquivo, ordenado por nome.

python bin/ascii_gif.py frames.txt -o projeto/loader.gif --size 28 --delay 120
python bin/ascii_gif.py frames/ -o projeto/loader.gif --preview projeto/loader.png

• --font deve ser uma TTF ou TTC monoespaçada; fontes monoespaçadas comuns são detectadas automaticamente quando omitido.
• --width e --height fixam a tela e centralizam a grade de texto. Forneça ambos ou nenhum. Use para corresponder a um tamanho em várias amostras.
• --fg e --bg padrão para texto claro em uma tela quase preta.
• --delay é o atraso padrão do quadro; atrasos do separador sobrescrevem por quadro.
• Mantenha os quadros dentro de cerca de 120 colunas e 40 linhas; telas maiores produzem GIFs longos.

Rota de Pasta de Imagens

Os arquivos são ordenados naturalmente (pic-2 antes de pic-10), rotacionados por EXIF e ajustados a uma única tela.

python bin/pics_gif.py fotos/ -o projeto/reel.gif --mode kenburns --fps 12 --hold 1.2 --transition 0.5 --width 800
python bin/pics_gif.py fotos/ -o projeto/reel.gif --mode sequence --fps 10 --hold 0.8 --fit contain --bg "#101010"

• sequence mantém cada imagem; crossfade mescla entre imagens; kenburns aplica zoom lento em cada imagem, alternando direção.
• --width define a tela; --height padrão para a proporção da primeira imagem.
• --fit cover corta para preencher, contain adiciona preenchimento com --bg.
• --hold são segundos por imagem, --transition segundos de mesclagem, --zoom o zoom final do Ken Burns.
• Uma pasta de 100 fotos a 800 px e 12 fps produz um arquivo grande; corte a largura ou o fps primeiro.

Rota SVG e HTML

A ferramenta envolve .svg em uma página na janela de visualização solicitada, ou abre .html diretamente, depois pausa e busca cada animação em tempos explícitos antes de cada captura de tela. Os quadros não dependem do tempo de parede.

python bin/svg_gif.py logo.svg -o projeto/logo.gif --duration 3 --fps 15
python bin/svg_gif.py logo.svg -o projeto/logo.gif --animate rotate --selector "#mark" --duration 2 --background "#0b0d12"
python bin/svg_gif.py pagina.html -o projeto/pagina.gif --width 960 --height 540 --duration 4 --fps 12

• Sem --animate, o SVG ou página já deve animar via SMIL ou CSS. Desenhos estáticos precisam de uma predefinição.
• Predefinições: rotate, pulse, fade, aplicadas à raiz do svg ou a --selector.
• --width e --height padrão para a width/height ou viewBox do SVG.
• --dpr 2 captura no dobro da janela de visualização, para texto mais nítido; o GIF então tem o dobro do tamanho em pixels.
• Páginas com canvas JS ou WebGL não são suportadas por esta ferramenta. Use uma página que exponha um hook de quadro, ou pré-renderize quadros e monte com gifkit.

Opções Compartilhadas

• --colors até 255. Reduza apenas quando a paleta for simples ou o arquivo precisar encolher.
• --dither none é correto para arte plana e texto; floyd ajuda gradientes e fotos.
• --loop 0 faz loop infinito; qualquer outro valor repete esse número de vezes.
• --preview CAMINHO escreve um PNG estático do primeiro quadro.
• A saída é determinística para a mesma entrada, configurações e cadeia de ferramentas.

Quadros Personalizados

Qualquer sequência de quadros pode usar o mesmo núcleo. Os quadros devem ser RGB e do mesmo tamanho; os atrasos estão em ms na grade de 10 ms.

import sys
sys.path.insert(0, "bin")
import gifkit
from PIL import Image

quadros = [Image.new("RGB", (320, 180), (n * 20, 40, 90)) for n in range(12)]
gifkit.write_gif(quadros, "projeto/gradiente.gif", [100] * 12)

write_gif constrói uma paleta, mescla quadros consecutivos idênticos, escreve atomicamente e verifica o resultado. Use esta rota para animações de dados, diagramas gerados ou quaisquer quadros que essas rotas não cobrem.

Contrato

• A ferramenta escreve em <nome>.tmp.gif no diretório de saída, verifica a contagem de quadros, soma da duração e tamanho em pixels lendo o arquivo de volta, depois o renomeia. Uma falha remove o arquivo temporário e não deixa alvo parcial.
• O GIF usa uma paleta para cada quadro, portanto as cores não podem piscar.
• Quadros consecutivos idênticos são mesclados em um quadro com um atraso maior; a contagem de quadros impressa é a contagem armazenada.
• Os atrasos ficam na grade de 10 ms do GIF e têm pelo menos 20 ms.

Verificação

As verificações de rota estão no repositório de origem. Da raiz do repositório:

python tools/check.py

Cada verificação imprime uma linha PASSOU, PULOU ou FALHA. Dependências opcionais ausentes pulam por padrão; --strict requer cada rota. As verificações geram fixtures sob scratch/checks e também escaneiam o repositório por segredos, caminhos absolutos, texto não-ASCII e terminações CRLF.

Limitações

• GIF é indexado em 8 bits e tem um limite de 256 cores; fotos mostram bandeamento sem pontilhamento.
• Visualizadores limitam atrasos curtos; mantenha atrasos de quadro em 20 ms ou mais.
• Sequências longas, de alta fps e truecolor são melhores como APNG ou WebM. Diga isso quando for solicitada qualidade.
• A memória cresce com o número de quadros e tamanho da tela; as ferramentas mantêm todos os quadros enquanto constroem uma paleta.
• A cobertura de glifos ASCII depende da fonte escolhida; glifos de caixa ou bloco ausentes caem para caixas vazias.

Consulte references/animated-gif-considerations.md para restrições de formato e a lógica por trás desses padrões.

Arquivos

• bin/gifkit.py - paleta, temporização, mesclagem, escrita atômica, verificação.
• bin/ascii_gif.py - quadros de texto ANSI para GIF.
• bin/pics_gif.py - pasta de imagens para GIF.
• bin/svg_gif.py - animação SVG/HTML para GIF.
• bin/render_frames.cjs - auxiliar de captura de quadros do Playwright.
• references/animated-gif-considerations.md - notas de formato.

As verificações do repositório e a geração de amostras estão em tools/, fora do payload do skill instalado.