Pipeline de Produção de Vídeo ASCII
Quando usar
Use quando os usuários solicitarem: vídeo ASCII, vídeo de arte em texto, vídeo estilo terminal, animação de arte em 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 animada em ASCII.
O que está dentro
Pipeline de produção para vídeo em arte ASCII — qualquer formato. Converte entrada de vídeo/áudio/imagens/gerativa 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 ASCII gerativas, híbrido vídeo+áudio reativo, sobreposições de texto/letras, renderização de terminal em tempo real.
Padrão Criativo
Isso é 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 com transcrição literal.
A excelência na primeira renderização é inegociável. A saída deve ser visualmente marcante 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 enviar.
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. Estenda o vocabulário da skill quando o projeto exigir. Se as referências não tiverem o que a visão demanda, construa. 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 unificadora — 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 quadro 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 do material de origem | references/inputs.md § Amostragem de Vídeo |
| Reativo a áudio | Arquivo de áudio | Visuais gerativos impulsionados 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 as refs de entrada |
| Letras/texto | Áudio + texto/SRT | Texto cronometrado com efeitos visuais | references/inputs.md § Texto/Letras |
| Narração TTS | Citações de texto + API TTS | Vídeo de depoimento/citação narrado com texto digitado | references/inputs.md § Integração TTS |
Stack
Script Python único autocontido por projeto. Nenhuma GPU necessária.
| Camada | Ferramenta | Propósito |
|---|---|---|
| Núcleo | Python 3.10+, NumPy | Matemática, operações de array, efeitos vetorizados |
| Sinal | SciPy | FFT, detecção de picos (modos de áudio) |
| Imagem | Pillow (PIL) | Rasterização de fontes, decodificação de quadros, 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 | API ElevenLabs (opcional) | Gerar clipes de narração |
| Opcional | OpenCV | Amostragem de quadros de vídeo, detecção de bordas |
Arquitetura do Pipeline
Cada modo segue o mesmo pipeline de 6 estágios:
ENTRADA → ANALISAR → FUNÇÃO_CENA → MAPEAR_TONS → SOMBREAR → CODIFICAR
- ENTRADA — Carregar/decodificar material de origem (quadros de vídeo, amostras de áudio, imagens ou nada)
- ANALISAR — Extrair características por quadro (bandas de áudio, luminância/bordas de vídeo, vetores de movimento)
- FUNÇÃO_CENA — A função de cena renderiza para um canvas de pixel (
uint8 H,W,3). Compõe múltiplas grades de caracteres via_render_vf()+ modos de mesclagem de pixel. Vejareferences/composition.md - MAPEAR_TONS — Normalização adaptativa de brilho baseada em percentil. Veja
references/composition.md§ Mapeamento de Tons Adaptativo - SOMBREAR — Pós-processamento via
ShaderChain+FeedbackBuffer. Vejareferences/shaders.md - CODIFICAR — Enviar quadros 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, braille), específico do projeto | architecture.md § Paletas |
| Estratégia de cor | HSV, OKLAB/OKLCH, paletas RGB discretas, harmonia gerada automaticamente, monocromático, temperatura | architecture.md § Sistema de Cores |
| Textura de fundo | Campos senoidais, ruído fBM, deformação de domínio, voronoi, reação-difusão, autômatos celulares, vídeo | effects.md |
| Efeitos primários | Anéis, espirais, túnel, vórtice, ondas, interferência, aurora, fogo, SDFs, atratores estranhos | effects.md |
| Partículas | Faíscas, neve, chuva, bolhas, runas, órbitas, boids agrupados, seguidores de campo de fluxo, rastros | effects.md § Partículas |
| Clima do shader | CRT retrô, moderno limpo, glitch art, 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, lado a lado, rotacionado, olho de peixe, Möbius, deformado por domínio | 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/dissolução animados | composition.md § Mascaramento |
| Transições | Crossfade, wipe, dissolução, 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 o clima)
- Estratégia de cor diferente (ou no mínimo um matiz diferente)
- Varie a intensidade do shader (mais bloom durante picos, mais granulação durante o silêncio)
- Tipos de partículas diferentes se partículas estiverem ativas
Invenção Específica do Projeto
Para cada projeto, invente pelo menos um de:
- Uma paleta de caracteres personalizada combinando com o tema
- Um efeito de fundo personalizado (combine/modifique blocos de construção existentes)
- Uma paleta de cores personalizada (conjunto RGB discreto combinando com a marca/clima)
- Um conjunto de caracteres de partículas personalizado
- 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 é o matiz dominante?
- Textura de caracteres: Dados densos? Estrelas esparsas? Pontos orgânicos? Blocos geométricos?
- O que torna ISTO 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 lo-fi chill" 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 — detectar automaticamente núcleos/RAM, definir perfil de qualidade. Veja
references/optimization.md - Seções — mapear timestamps para funções de cena, cada uma com seu próprio efeito/paleta/cor/config de 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 cores — 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 - Mapeamento de tons — normalização adaptativa de brilho;
references/composition.md - Pipeline de shaders —
ShaderChain+FeedbackBuffer;references/shaders.md - Tabela de cenas + despachante — tempo → função de cena + config;
references/scenes.md - Codificador paralelo — renderização de clipe com N workers via pipes ffmpeg
- Principal — orquestrar pipeline completo
Passo 4: Verificação de Qualidade
- Testar quadros primeiro: renderizar quadros únicos em timestamps chave antes da renderização completa
- Verificação de brilho:
canvas.mean() > 8para todo o conteúdo ASCII. Se escuro, reduzir gama - 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érico, volte
Notas Críticas de Implementação
Brilho — Use tonemap(), Não Multiplicadores Lineares
Este é o problema visual nº 1. ASCII sobre preto é inerentemente escuro. Nunca use multiplicadores canvas * N — eles recortam realces. Use mapeamento de tons 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: função_cena() → mapeamento_tons() → FeedbackBuffer → ShaderChain → ffmpeg
Gama por cena: padrão 0.75, solarizar 0.55, posterizar 0.50, cenas claras 0.85. Use mesclagem screen (não overlay) para camadas escuras.
Altura da Célula da Fonte
macOS Pillow: textbbox() retorna altura errada. Use font.getmetrics(): altura_celula = ascent + descent. Veja references/troubleshooting.md.
Deadlock do Pipe ffmpeg
Nunca stderr=subprocess.PIPE com ffmpeg de longa execução — o buffer enche em 64KB e causa deadlock. 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 Desempenho
| Componente | Orçamento |
|---|---|
| Extração de características | 1-5ms |
| Função de efeito | 2-15ms |
| Renderização de caractere | 80-150ms (gargalo) |
| Pipeline de shader | 5-25ms |
| Total | ~100-200ms/quadro |
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 cores (HSV + OKLAB + RGB discreto + geração de harmonia), auxiliar _render_vf(), classe GridLayer |
references/composition.md | Modos de mesclagem 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/deformação 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, dimensionamento reativo a áudio, transições, predefinições de matiz, codificação de formato de saída, renderização de 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 composicionais), exemplos completos de cena em todos os níveis de complexidade, checklist 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 desempenho |
references/troubleshooting.md | Armadilhas de broadcasting NumPy, armadilhas de modo de mesclagem, multiprocessamento/pickling, diagnósticos 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 quer 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)
- Liste seus elementos visuais/estruturais principais (erosão → revelação gradual; mitose → duplicação por divisão; 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 dois domínios visual/...
[...truncado para tradução]