Pipeline de Produção de Vídeo ASCII
Quando usar
Use quando os usuários solicitarem: vídeo ASCII, vídeo com arte em texto, vídeo estilo terminal, animação com arte de caracteres, visualização retrô de texto, visualizador de áudio em ASCII, conversão de vídeo para arte ASCII, efeitos estilo Matrix ou qualquer saída ASCII animada.
O que está incluído
Pipeline de produção para vídeo com arte ASCII — qualquer formato. Converte entrada de vídeo/áudio/imagens/generativa em saída de vídeo com caracteres ASCII coloridos (MP4, GIF, sequência de imagens). Abrange: conversão de vídeo para ASCII, visualizadores de música reativos a áudio, animações generativas de arte ASCII, híbrido vídeo+áudio reativo, sobreposição de texto/letras, renderização em terminal em tempo real.
Padrão Criativo
Isto é arte visual. Caracteres ASCII são o meio; o cinema é o padrão.
Antes de escrever uma única linha de código, articule o conceito criativo. Qual é o clima? Que história visual isso conta? O que torna ESTE projeto diferente de todos os outros vídeos ASCII? O prompt do usuário é um ponto de partida — interprete-o com ambição criativa, não transcrição literal.
Excelência no primeiro render é inegociável. A saída deve ser visualmente impressionante sem exigir rodadas de revisão. Se algo parecer genérico, plano ou como "arte ASCII gerada por IA", está errado — repense o conceito criativo antes de entregar.
Vá além do vocabulário de referência. Os catálogos de efeitos, predefinições de shaders e bibliotecas de paletas nas referências são um vocabulário inicial. Para cada projeto, combine, modifique e invente novos padrões. O catálogo é uma paleta de tintas — você escreve a pintura.
Seja proativamente criativo. Expanda o vocabulário do skill quando o projeto exigir. Se as referências não tiverem o que a visão exige, construa-o. Inclua pelo menos um momento visual que o usuário não pediu, mas apreciará — uma transição, um efeito, uma escolha de cor que eleve toda a peça.
Estética coesa acima de correção técnica. Todas as cenas em um vídeo devem parecer conectadas por uma linguagem visual unificada — temperatura de cor compartilhada, paletas de caracteres relacionadas, vocabulário de movimento consistente. Um vídeo tecnicamente correto onde cada cena usa um efeito aleatório diferente é uma falha estética.
Denso, em camadas, considerado. Cada frame deve recompensar a visualização. Nunca fundos pretos planos. Sempre composição multi-grade. Sempre variação por cena. Sempre cor intencional.
Modos
| Modo | Entrada | Saída | Referência |
|---|---|---|---|
| Vídeo-para-ASCII | Arquivo de vídeo | Recriação ASCII da fonte original | references/inputs.md § Amostragem de Vídeo |
| Reativo a Áudio | Arquivo de áudio | Visuais generativos guiados por características de áudio | references/inputs.md § Análise de Áudio |
| Generativo | Nenhum (ou parâmetros de semente) | Animação ASCII procedural | references/effects.md |
| Híbrido | Vídeo + áudio | Vídeo ASCII com sobreposições reativas a áudio | Ambas referências de entrada |
| Letras/Texto | Áudio + texto/SRT | Texto temporizado com efeitos visuais | references/inputs.md § Texto/Letras |
| Narração TTS | Citações de texto + API TTS | Vídeo narrado de depoimento/citação com texto digitado | references/inputs.md § Integração TTS |
Stack
Um único script Python auto-contido por projeto. Nenhuma GPU necessária.
| Camada | Ferramenta | Propósito |
|---|---|---|
| Núcleo | Python 3.10+, NumPy | Matemática, operações em arrays, efeitos vetorizados |
| Sinal | SciPy | FFT, detecção de picos (modos de áudio) |
| Imagem | Pillow (PIL) | Rasterização de fontes, decodificação de frames, E/S de imagem |
| E/S de Vídeo | ffmpeg (CLI) | Decodificar entrada, codificar saída, multiplexar áudio |
| Paralelo | concurrent.futures | N workers para renderização de lote/clipe |
| TTS | ElevenLabs API (opcional) | Gerar clipes de narração |
| Opcional | OpenCV | Amostragem de frames de vídeo, detecção de bordas |
Arquitetura da Pipeline
Todo modo segue a mesma pipeline de 6 estágios:
INPUT → ANALYZE → SCENE_FN → TONEMAP → SHADE → ENCODE
- INPUT — Carregar/decodificar material de origem (frames de vídeo, amostras de áudio, imagens ou nada)
- ANALYZE — Extrair características por frame (bandas de áudio, luminância/bordas de vídeo, vetores de movimento)
- SCENE_FN — Função de cena renderiza para canvas de pixel (
uint8 H,W,3). Compõe múltiplas grades de caracteres via_render_vf()+ modos de blend de pixel. Vejareferences/composition.md - TONEMAP — Normalização adaptativa de brilho baseada em percentil. Veja
references/composition.md§ Tonemap Adaptativo - SHADE — Pós-processamento via
ShaderChain+FeedbackBuffer. Vejareferences/shaders.md - ENCODE — Enviar frames RGB brutos para ffmpeg para codificação H.264/GIF
Direção Criativa
Dimensões Estéticas
| Dimensão | Opções | Referência |
|---|---|---|
| Paleta de caracteres | Rampas de densidade, elementos de bloco, símbolos, scripts (katakana, grego, runas, braile), projeto-específico | architecture.md § Paletas |
| Estratégia de cor | HSV, OKLAB/OKLCH, paletas RGB discretas, harmonia auto-gerada, monocromático, temperatura | architecture.md § Sistema de Cor |
| Textura de fundo | Campos senoidais, ruído fBM, warp de domínio, voronoi, reação-difusão, autômatos celulares, vídeo | effects.md |
| Efeitos principais | Anéis, espirais, túnel, vórtex, ondas, interferência, aurora, fogo, SDFs, atratores estranhos | effects.md |
| Partículas | Faíscas, neve, chuva, bolhas, runas, órbitas, boids em bando, seguidores de campo de fluxo, rastros | effects.md § Partículas |
| Clima do shader | CRT retrô, moderno limpo, arte glitch, cinematográfico, sonhador, industrial, psicodélico | shaders.md |
| Densidade da grade | xs(8px) até xxl(40px), mista por camada | architecture.md § Sistema de Grade |
| Espaço de coordenadas | Cartesiano, polar, ladrilhado, rotacionado, olho de peixe, Möbius, domain-warped | effects.md § Transformações |
| Feedback | Túnel de zoom, rastros de arco-íris, eco fantasmagórico, mandala rotativa, evolução de cor | composition.md § Feedback |
| Mascaramento | Círculo, anel, gradiente, estêncil de texto, íris/wipe/dissolve animados | composition.md § Mascaramento |
| Transições | Crossfade, wipe, dissolve, corte glitch, íris, revelação baseada em máscara | shaders.md § Transições |
Variação por Seção
Nunca use a mesma configuração para o vídeo inteiro. Para cada seção/cena:
- Efeito de fundo diferente (ou componha 2-3)
- Paleta de caracteres diferente (combine com o clima)
- Estratégia de cor diferente (ou no mínimo uma matiz diferente)
- Varie a intensidade do shader (mais bloom durante picos, mais granulado durante silêncio)
- Tipos de partículas diferentes se partículas estiverem ativas
Invenção por Projeto
Para cada projeto, invente pelo menos um de:
- Uma paleta de caracteres personalizada que combine com o tema
- Um efeito de fundo personalizado (combine/modifique blocos de construção existentes)
- Uma paleta de cores personalizada (conjunto RGB discreto que combine com a marca/clima)
- Um conjunto personalizado de caracteres de partículas
- Uma transição de cena ou momento visual inovador
Não apenas escolha do catálogo. O catálogo é vocabulário — você escreve o poema.
Fluxo de Trabalho
Passo 1: Visão Criativa
Antes de qualquer código, articule o conceito criativo:
- Clima/atmosfera: O que o espectador deve sentir? Energético, meditativo, caótico, elegante, ameaçador?
- História visual: O que acontece ao longo da duração? Construir tensão? Transformar? Dissolver?
- Mundo de cor: Quente/frio? Monocromático? Neon? Tons terrosos? Qual é a matiz dominante?
- Textura de caracteres: Dados densos? Estrelas esparsas? Pontos orgânicos? Blocos geométricos?
- O que torna ESTE diferente: Qual é a única coisa que torna este projeto único?
- Arco emocional: Como as cenas progridem? Abrir com energia, construir para o clímax, resolver?
Mapeie o prompt do usuário para escolhas estéticas. Um "visualizador chill lo-fi" exige tudo diferente de um "fluxo de dados cyberpunk glitch".
Passo 2: Design Técnico
- Modo — qual dos 6 modos acima
- Resolução — paisagem 1920x1080 (padrão), retrato 1080x1920, quadrado 1080x1080 @ 24fps
- Detecção de hardware — auto-detectar núcleos/RAM, definir perfil de qualidade. Veja
references/optimization.md - Seções — mapear timestamps para funções de cena, cada uma com sua própria configuração de efeito/paleta/cor/shader
- Formato de saída — MP4 (padrão), GIF (640x360 @ 15fps), sequência PNG
Passo 3: Construir o Script
Arquivo Python único. Componentes (com referências):
- Detecção de hardware + perfil de qualidade —
references/optimization.md - Carregador de entrada — dependente do modo;
references/inputs.md - Analisador de características — FFT de áudio, luminância de vídeo ou sintético
- Grade + renderizador — grades multi-densidade com cache de bitmap;
references/architecture.md - Paletas de caracteres — múltiplas por projeto;
references/architecture.md§ Paletas - Sistema de cor — HSV + RGB discreto + geração de harmonia;
references/architecture.md§ Cor - Funções de cena — cada uma retorna
canvas (uint8 H,W,3);references/scenes.md - Tonemap — normalização adaptativa de brilho;
references/composition.md - Pipeline de shader —
ShaderChain+FeedbackBuffer;references/shaders.md - Tabela de cenas + despachante — tempo → função de cena + configuração;
references/scenes.md - Codificador paralelo — renderização de clipe com N workers e pipes ffmpeg
- Main — orquestrar pipeline completa
Passo 4: Verificação de Qualidade
- Teste frames primeiro: renderize frames únicos em timestamps chave antes do render completo
- Verificação de brilho:
canvas.mean() > 8para todo conteúdo ASCII. Se escuro, abaixe gamma - Coerência visual: todas as cenas parecem pertencer ao mesmo vídeo?
- Verificação de visão criativa: a saída corresponde ao conceito do Passo 1? Se parecer genérica, volte
Notas Críticas de Implementação
Brilho — Use tonemap(), Não Multiplicadores Lineares
Este é o problema visual #1. ASCII sobre preto é inerentemente escuro. Nunca use multiplicadores canvas * N — eles cortam realces. Use tonemap adaptativo:
def tonemap(canvas, gamma=0.75):
f = canvas.astype(np.float32)
lo, hi = np.percentile(f[::4, ::4], [1, 99.5])
if hi - lo < 10: hi = lo + 10
f = np.clip((f - lo) / (hi - lo), 0, 1) ** gamma
return (f * 255).astype(np.uint8)
Pipeline: scene_fn() → tonemap() → FeedbackBuffer → ShaderChain → ffmpeg
Gamma por cena: padrão 0.75, solarizar 0.55, posterizar 0.50, cenas brilhantes 0.85. Use blend screen (não overlay) para camadas escuras.
Altura da Célula da Fonte
macOS Pillow: textbbox() retorna altura errada. Use font.getmetrics(): cell_height = ascent + descent. Veja references/troubleshooting.md.
Deadlock do Pipe do ffmpeg
Nunca stderr=subprocess.PIPE com ffmpeg de longa duração — o buffer enche em 64KB e trava. Redirecione para arquivo. Veja references/troubleshooting.md.
Compatibilidade de Fonte
Nem todos os caracteres Unicode renderizam em todas as fontes. Valide paletas na inicialização — renderize cada caractere, verifique saída em branco. Veja references/troubleshooting.md.
Arquitetura por Clipe
Para vídeos segmentados (citações, cenas, capítulos), renderize cada um como um arquivo de clipe separado para renderização paralela e re-renderização seletiva. Veja references/scenes.md.
Metas de Performance
| Componente | Orçamento |
|---|---|
| Extração de características | 1-5ms |
| Função de efeito | 2-15ms |
| Renderização de caracteres | 80-150ms (gargalo) |
| Pipeline de shader | 5-25ms |
| Total | ~100-200ms/frame |
Referências
| Arquivo | Conteúdo |
|---|---|
references/architecture.md | Sistema de grade, predefinições de resolução, seleção de fonte, paletas de caracteres (20+), sistema de cor (HSV + OKLAB + RGB discreto + geração de harmonia), helper _render_vf(), classe GridLayer |
references/composition.md | Modos de blend de pixel (20 modos), blend_canvas(), composição multi-grade, tonemap() adaptativo, FeedbackBuffer, PixelBlendStack, sistema de mascaramento/estêncil |
references/effects.md | Blocos de construção de efeitos: geradores de campo de valor, campos de matiz, ruído/fBM/warp de domínio, voronoi, reação-difusão, autômatos celulares, SDFs, atratores estranhos, sistemas de partículas, transformações de coordenadas, coerência temporal |
references/shaders.md | ShaderChain, despacho _apply_shader_step(), catálogo de 38 shaders, escalonamento reativo a áudio, transições, predefinições de matiz, codificação de formato de saída, renderização em terminal |
references/scenes.md | Protocolo de cena, classe Renderer, tabela SCENES, render_clip(), corte sincronizado com batida, renderização paralela, padrões de design (hierarquia de camadas, arcos direcionais, metáforas visuais, técnicas de composição), exemplos de cenas completas em todos os níveis de complexidade, lista de verificação de design de cena |
references/inputs.md | Análise de áudio (FFT, bandas, batidas), amostragem de vídeo, conversão de imagem, texto/letras, integração TTS (ElevenLabs, atribuição de voz, mixagem de áudio) |
references/optimization.md | Detecção de hardware, perfis de qualidade, padrões vetorizados, renderização paralela, gerenciamento de memória, orçamentos de performance |
references/troubleshooting.md | Armadilhas de broadcasting NumPy, erros de modo de blend, multiprocessamento/pickling, diagnóstico de brilho, problemas com ffmpeg, problemas de fonte, erros comuns |
Divergência Criativa (use apenas quando o usuário solicitar saída experimental/criativa/única)
Se o usuário pedir saída criativa, experimental, surpreendente ou não convencional, selecione a estratégia que melhor se encaixa e raciocine através de seus passos ANTES de gerar código.
- Conexões Forçadas — quando o usuário deseja inspiração entre domínios ("faça parecer orgânico", "estética industrial")
- Mistura Conceitual — quando o usuário nomeia duas coisas para combinar ("oceano encontra música", "espaço + caligrafia")
- Estratégias Oblíquas — quando o usuário está maximamente aberto ("me surpreenda", "algo que nunca vi")
Conexões Forçadas
- Escolha um domínio não relacionado ao objetivo visual (sistemas climáticos, microbiologia, arquitetura, dinâmica de fluidos, tecelagem têxtil)
- Liste seus elementos visuais/estruturais principais (erosão → revelação gradual; mitose → divisão duplicadora; tecelagem → padrões entrelaçados)
- Mapeie esses elementos para caracteres ASCII e padrões de animação
- Sintetize — como "erosão" ou "cristalização" se parece em uma grade de caracteres?
Mistura Conceitual
- Nomeie duas visuais/... distintas [conteúdo truncado para fins de tradução]