Pipeline de Producción de Video ASCII
Cuándo usarlo
Úsalo cuando los usuarios soliciten: video ASCII, video de arte en texto, video estilo terminal, animación de arte de caracteres, visualización de texto retro, visualizador de audio en ASCII, conversión de video a arte ASCII, efectos estilo Matrix o cualquier salida ASCII animada.
Qué contiene
Pipeline de producción para video de arte ASCII — cualquier formato. Convierte entrada de video/audio/imágenes/generativa en video de caracteres ASCII coloreados (MP4, GIF, secuencia de imágenes). Cubre: conversión de video a ASCII, visualizadores de música audio-reactivos, animaciones generativas de arte ASCII, híbrido de video+audio reactivo, superposición de texto/letras y renderizado en terminal en tiempo real.
Estándar Creativo
Esto es arte visual. Los caracteres ASCII son el medio; el cine es el estándar.
Antes de escribir una sola línea de código, articula el concepto creativo. ¿Cuál es el estado de ánimo? ¿Qué historia visual cuenta? ¿Qué hace que ESTE proyecto sea diferente de cualquier otro video ASCII? La indicación del usuario es un punto de partida —interprétala con ambición creativa, no con transcripción literal.
La excelencia en el primer renderizado no es negociable. El resultado debe ser visualmente impactante sin necesidad de rondas de revisión. Si algo parece genérico, plano o como "arte ASCII generado por IA", está mal —replantea el concepto creativo antes de enviarlo.
Ve más allá del vocabulario de referencia. Los catálogos de efectos, preajustes de shaders y bibliotecas de paletas en las referencias son un vocabulario inicial. Para cada proyecto, combina, modifica e inventa nuevos patrones. El catálogo es una paleta de pinturas; tú escribes la pintura.
Sé proactivamente creativo. Amplía el vocabulario del skill cuando el proyecto lo requiera. Si las referencias no tienen lo que la visión exige, constrúyelo. Incluye al menos un momento visual que el usuario no haya pedido pero que apreciará: una transición, un efecto, una elección de color que eleve toda la pieza.
Estética cohesionada sobre corrección técnica. Todas las escenas de un video deben sentirse conectadas por un lenguaje visual unificador: temperatura de color compartida, paletas de caracteres relacionadas, vocabulario de movimiento consistente. Un video técnicamente correcto donde cada escena usa un efecto aleatorio diferente es un fracaso estético.
Denso, en capas, considerado. Cada fotograma debe recompensar la visualización. Nunca fondos negros planos. Siempre composición multicuadrícula. Siempre variación por escena. Siempre color intencional.
Modos
| Modo | Entrada | Salida | Referencia |
|---|---|---|---|
| Video a ASCII | Archivo de video | Recreación ASCII del metraje original | references/inputs.md § Muestreo de Video |
| Audio-reactivo | Archivo de audio | Visuales generativas impulsadas por características de audio | references/inputs.md § Análisis de Audio |
| Generativo | Ninguno (o parámetros semilla) | Animación ASCII procedural | references/effects.md |
| Híbrido | Video + audio | Video ASCII con superposiciones audio-reactivas | Ambas referencias de entrada |
| Letras/texto | Audio + texto/SRT | Texto temporizado con efectos visuales | references/inputs.md § Texto/Letras |
| Narración TTS | Citas de texto + API TTS | Video narrado de testimonio/cita con texto escrito | references/inputs.md § Integración TTS |
Stack
Un único script Python autónomo por proyecto. No se requiere GPU.
| Capa | Herramienta | Propósito |
|---|---|---|
| Núcleo | Python 3.10+, NumPy | Matemáticas, operaciones en arrays, efectos vectorizados |
| Señal | SciPy | FFT, detección de picos (modos de audio) |
| Imágenes | Pillow (PIL) | Rasterización de fuentes, decodificación de fotogramas, E/S de imágenes |
| E/S de video | ffmpeg (CLI) | Decodificar entrada, codificar salida, multiplexar audio |
| Paralelo | concurrent.futures | N trabajadores para renderizado por lotes/clips |
| TTS | API de ElevenLabs (opcional) | Generar clips de narración |
| Opcional | OpenCV | Muestreo de fotogramas de video, detección de bordes |
Arquitectura de la Pipeline
Cada modo sigue la misma pipeline de 6 etapas:
ENTRADA → ANALIZAR → FUNCIÓN_ESCENA → MAPEO_TONAL → SOMBREADO → CODIFICAR
- ENTRADA — Cargar/decodificar material fuente (fotogramas de video, muestras de audio, imágenes o nada)
- ANALIZAR — Extraer características por fotograma (bandas de audio, luminancia/bordes de video, vectores de movimiento)
- FUNCIÓN_ESCENA — La función de escena renderiza en un lienzo de píxeles (
uint8 H,W,3). Compone múltiples cuadrículas de caracteres mediante_render_vf()+ modos de mezcla de píxeles. Verreferences/composition.md - MAPEO_TONAL — Normalización adaptativa de brillo basada en percentiles. Ver
references/composition.md§ Mapeo Tonal Adaptativo - SOMBREADO — Postprocesamiento mediante
ShaderChain+FeedbackBuffer. Verreferences/shaders.md - CODIFICAR — Enviar fotogramas RGB sin procesar a ffmpeg para codificación H.264/GIF
Dirección Creativa
Dimensiones Estéticas
| Dimensión | Opciones | Referencia |
|---|---|---|
| Paleta de caracteres | Rampas de densidad, elementos de bloque, símbolos, scripts (katakana, griego, runas, braille), específicos del proyecto | architecture.md § Paletas |
| Estrategia de color | HSV, OKLAB/OKLCH, paletas RGB discretas, armonía generada automáticamente, monocromático, temperatura | architecture.md § Sistema de Color |
| Textura de fondo | Campos de seno, ruido fBM, deformación de dominio, voronoi, difusión-reactiva, autómatas celulares, video | effects.md |
| Efectos principales | Anillos, espirales, túnel, vórtice, ondas, interferencia, aurora, fuego, SDFs, atractores extraños | effects.md |
| Partículas | Chispas, nieve, lluvia, burbujas, runas, órbitas, bandadas boid, seguidores de campo de flujo, estelas | effects.md § Partículas |
| Estado de ánimo del shader | CRT retro, moderno limpio, arte glitch, cinematográfico, soñador, industrial, psicodélico | shaders.md |
| Densidad de cuadrícula | xs(8px) hasta xxl(40px), mixto por capa | architecture.md § Sistema de Cuadrícula |
| Espacio de coordenadas | Cartesianas, polares, en mosaico, rotadas, ojo de pez, Möbius, deformación de dominio | effects.md § Transformaciones |
| Retroalimentación | Túnel de zoom, estelas de arcoíris, eco fantasmal, mandala giratorio, evolución de color | composition.md § Retroalimentación |
| Enmascaramiento | Círculo, anillo, degradado, plantilla de texto, iris/barrido/disolución animada | composition.md § Enmascaramiento |
| Transiciones | Fundido cruzado, barrido, disolución, corte glitch, iris, revelado basado en máscara | shaders.md § Transiciones |
Variación por Sección
Nunca uses la misma configuración para todo el video. Para cada sección/escena:
- Efecto de fondo diferente (o compón 2-3)
- Paleta de caracteres diferente (que coincida con el estado de ánimo)
- Estrategia de color diferente (o al menos un tono diferente)
- Varía la intensidad del shader (más brillo durante los picos, más grano durante los momentos tranquilos)
- Tipos de partículas diferentes si las partículas están activas
Invención Específica del Proyecto
Para cada proyecto, inventa al menos uno de los siguientes:
- Una paleta de caracteres personalizada que coincida con el tema
- Un efecto de fondo personalizado (combina/modifica bloques de construcción existentes)
- Una paleta de colores personalizada (conjunto RGB discreto que coincida con la marca/estado de ánimo)
- Un conjunto de caracteres de partículas personalizado
- Una transición de escena novedosa o un momento visual
No solo elijas del catálogo. El catálogo es vocabulario; tú escribes el poema.
Flujo de Trabajo
Paso 1: Visión Creativa
Antes de cualquier código, articula el concepto creativo:
- Estado de ánimo/atmósfera: ¿Qué debería sentir el espectador? ¿Energético, meditativo, caótico, elegante, ominoso?
- Historia visual: ¿Qué sucede durante la duración? ¿Construir tensión? ¿Transformar? ¿Disolver?
- Mundo de color: ¿Cálido/frío? ¿Monocromático? ¿Neón? ¿Tonos tierra? ¿Cuál es el tono dominante?
- Textura de caracteres: ¿Datos densos? ¿Estrellas dispersas? ¿Puntos orgánicos? ¿Bloques geométricos?
- ¿Qué hace que ESTO sea diferente?: ¿Cuál es la única cosa que hace único a este proyecto?
- Arco emocional: ¿Cómo progresan las escenas? ¿Abrir con energía, construir hasta el clímax, resolver?
Mapea la indicación del usuario a elecciones estéticas. Un "visualizador lo-fi relajante" exige todo diferente a un "flujo de datos cyberpunk glitch".
Paso 2: Diseño Técnico
- Modo — cuál de los 6 modos anteriores
- Resolución — apaisada 1920x1080 (por defecto), retrato 1080x1920, cuadrada 1080x1080 a 24fps
- Detección de hardware — detectar automáticamente núcleos/RAM, establecer perfil de calidad. Ver
references/optimization.md - Secciones — mapear marcas de tiempo a funciones de escena, cada una con su propia configuración de efecto/paleta/color/shader
- Formato de salida — MP4 (por defecto), GIF (640x360 a 15fps), secuencia PNG
Paso 3: Construir el Script
Un único archivo Python. Componentes (con referencias):
- Detección de hardware + perfil de calidad —
references/optimization.md - Cargador de entrada — dependiente del modo;
references/inputs.md - Analizador de características — FFT de audio, luminancia de video o sintético
- Cuadrícula + renderizador — cuadrículas de densidad múltiple con caché de mapa de bits;
references/architecture.md - Paletas de caracteres — múltiples por proyecto;
references/architecture.md§ Paletas - Sistema de color — HSV + RGB discreto + generación de armonía;
references/architecture.md§ Color - Funciones de escena — cada una devuelve
canvas (uint8 H,W,3);references/scenes.md - Mapeo tonal — normalización adaptativa de brillo;
references/composition.md - Pipeline de shaders —
ShaderChain+FeedbackBuffer;references/shaders.md - Tabla de escenas + despachador — tiempo → función de escena + configuración;
references/scenes.md - Codificador paralelo — renderizado de clips con N trabajadores mediante tuberías ffmpeg
- Principal — orquestar la pipeline completa
Paso 4: Verificación de Calidad
- Primero fotogramas de prueba: renderiza fotogramas individuales en marcas de tiempo clave antes del renderizado completo
- Verificación de brillo:
canvas.mean() > 8para todo el contenido ASCII. Si está oscuro, baja gamma - Coherencia visual: ¿todas las escenas parecen pertenecer al mismo video?
- Verificación de visión creativa: ¿la salida coincide con el concepto del Paso 1? Si parece genérica, vuelve atrás
Notas Críticas de Implementación
Brillo — Usa tonemap(), No Multiplicadores Lineales
Este es el problema visual #1. ASCII sobre negro es inherentemente oscuro. Nunca uses multiplicadores canvas * N — recortan los realces. Usa mapeo tonal 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 escena: por defecto 0.75, solarizar 0.55, posterizar 0.50, escenas brillantes 0.85. Usa mezcla screen (no overlay) para capas oscuras.
Altura de Celda de Fuente
Pillow en macOS: textbbox() devuelve altura incorrecta. Usa font.getmetrics(): cell_height = ascent + descent. Ver references/troubleshooting.md.
Punto Muerto de Tubería ffmpeg
Nunca stderr=subprocess.PIPE con ffmpeg de larga duración — el búfer se llena a 64KB y se bloquea. Redirigir a archivo. Ver references/troubleshooting.md.
Compatibilidad de Fuentes
No todos los caracteres Unicode se renderizan en todas las fuentes. Valida las paletas al inicio — renderiza cada carácter, verifica si la salida está en blanco. Ver references/troubleshooting.md.
Arquitectura por Clip
Para videos segmentados (citas, escenas, capítulos), renderiza cada uno como un archivo de clip separado para renderizado paralelo y re-renderizado selectivo. Ver references/scenes.md.
Objetivos de Rendimiento
| Componente | Presupuesto |
|---|---|
| Extracción de características | 1-5ms |
| Función de efecto | 2-15ms |
| Renderizado de caracteres | 80-150ms (cuello de botella) |
| Pipeline de shaders | 5-25ms |
| Total | ~100-200ms/fotograma |
Referencias
| Archivo | Contenido |
|---|---|
references/architecture.md | Sistema de cuadrícula, preajustes de resolución, selección de fuentes, paletas de caracteres (20+), sistema de color (HSV + OKLAB + RGB discreto + generación de armonía), helper _render_vf(), clase GridLayer |
references/composition.md | Modos de mezcla de píxeles (20 modos), blend_canvas(), composición multicuadrícula, tonemap() adaptativo, FeedbackBuffer, PixelBlendStack, sistema de enmascaramiento/plantilla |
references/effects.md | Bloques de construcción de efectos: generadores de campos de valor, campos de tono, ruido/fBM/deformación de dominio, voronoi, difusión-reactiva, autómatas celulares, SDFs, atractores extraños, sistemas de partículas, transformaciones de coordenadas, coherencia temporal |
references/shaders.md | ShaderChain, despacho _apply_shader_step(), catálogo de 38 shaders, escalado audio-reactivo, transiciones, preajustes de tinte, codificación de formato de salida, renderizado en terminal |
references/scenes.md | Protocolo de escena, clase Renderer, tabla SCENES, render_clip(), corte sincronizado con el ritmo, renderizado paralelo, patrones de diseño (jerarquía de capas, arcos direccionales, metáforas visuales, técnicas de composición), ejemplos completos de escenas en cada nivel de complejidad, lista de verificación de diseño de escenas |
references/inputs.md | Análisis de audio (FFT, bandas, ritmos), muestreo de video, conversión de imágenes, texto/letras, integración TTS (ElevenLabs, asignación de voz, mezcla de audio) |
references/optimization.md | Detección de hardware, perfiles de calidad, patrones vectorizados, renderizado paralelo, gestión de memoria, presupuestos de rendimiento |
references/troubleshooting.md | Errores de transmisión de NumPy, trampas de modos de mezcla, multiprocesamiento/pickling, diagnóstico de brillo, problemas de ffmpeg, problemas de fuentes, errores comunes |
Divergencia Creativa (usar solo cuando el usuario solicite salida experimental/creativa/única)
Si el usuario pide una salida creativa, experimental, sorprendente o poco convencional, selecciona la estrategia que mejor se adapte y razona a través de sus pasos ANTES de generar código.
- Conexiones Forzadas — cuando el usuario quiera inspiración entre dominios ("haz que se vea orgánico", "estética industrial")
- Mezcla Conceptual — cuando el usuario nombre dos cosas para combinar ("océano se encuentra con música", "espacio + caligrafía")
- Estrategias Oblicuas — cuando el usuario esté máximo abierto ("sorpréndeme", "algo que nunca haya visto")
Conexiones Forzadas
- Elige un dominio no relacionado con el objetivo visual (sistemas meteorológicos, microbiología, arquitectura, dinámica de fluidos, tejido textil)
- Enumera sus elementos visuales/estructurales centrales (erosión → revelación gradual; mitosis → división duplicada; tejido → patrones entrelazados)
- Mapea esos elementos en caracteres ASCII y patrones de animación
- Sintetiza — ¿cómo se ve la "erosión" o la "cristalización" en una cuadrícula de caracteres?
Mezcla Conceptual
- Nombra dos distintivos visuales/...