Pipeline HyperFrames — Vídeos explicativos de marca multiinquilino
Pipeline de extremo a extremo que toma una URL y produce un MP4 explicativo/promocional de marca terminado. Construido y validado en ColdStart (coldstartb2b.com). Diseñado para escalar a cualquier marca B2B con una configuración mínima por inquilino.
Cuándo invocar
- El usuario dice "Hyper Frames" / "hyperframes" + una URL o nombre de marca
- El usuario solicita un vídeo explicativo/promocional para un negocio específico
- El usuario dice "haz un video para " o similar
- El usuario dice "probemos esto en "
Entorno requerido (en $PIPELINE_ROOT/.env — copia .env.example)
KIE_AI_API_KEY=... # Nano Banana 2 + Seedance 2 vía KIE.AI
HEYGEN_API_KEY=... # Generación de avatar HeyGen
ELEVENLABS_API_KEY=... # Voz + música de 11Labs
ELEVENLABS_VOICE_ID=... # Voz de narrador por defecto
HEYGEN_TALKING_PHOTO_ID=... # Look de avatar por defecto
Estructura del proyecto
$PIPELINE_ROOT/ # raíz de este repositorio
brands/
<marca>/ # un directorio por marca (creado por brand-book)
brand.json
colors.md
typography.md
voice-tone.md
reference.png
template-16x9/ # la composición activa (directorio de trabajo único; intercambiar activos por marca)
index.html
styles/
brand.css # interfaz de marca — único archivo con CSS específico de marca
template.css # movimiento independiente de marca
layouts.css # sistema de 10 diseños
assets/
voice.mp3 # salida de 11Labs (con relleno)
avatar.webm # salida de HeyGen (con clave de croma + relleno)
music.mp3 # Música de fondo de 11Labs
broll-*.png # B-roll de Nano Banana
renders/
Para producción multiinquilino, la futura Etapa 0 debería copiar template-16x9/ por marca. Por ahora, intercambia los activos en su lugar por cada renderización.
Etapas del pipeline
Etapa 1 — Extracción de marca
Invoca el skill brand-book en la URL objetivo. Produce:
brands/<marca>/brand.json— paleta, tipografía, resumen de voz/tonobrands/<marca>/css-variables.json— TODAS las variables CSS del sitio en vivobrands/<marca>/reference.png— captura de pantalla de la página de inicio
Extrae los dos colores fijos que impulsan todas las etapas posteriores:
bg: color de fondo de la marca (típicamente casi negro, ej.#050508)accent: color de señal de la marca (típicamente un tono saturado, ej.#8b9cf7)
Estos se convierten en sustituciones en los prompts de B-roll y en styles/brand.css.
Etapa 2 — Leer el sitio, entender el negocio
Usa WebFetch para leer la página de inicio y las páginas clave (servicios, equipo, precios, acerca de). Sintetiza:
- Qué venden
- A quién se lo venden (ICP)
- Los 1-2 diferenciadores más nítidos
- La CTA deseada (reservar una llamada, iniciar prueba, etc.)
Esto se convierte en la sustancia del guion.
Etapa 3 — Guion
Escribe un guion para la duración solicitada. Regla de ritmo: ~2.7 palabras por segundo de voz (cadencia de multilingual_v2). Así que 22s ≈ 60 palabras; 45s ≈ 120 palabras; 60s ≈ 160 palabras.
Estructura (plantilla de 5 escenas a 22s; escala proporcionalmente para más duración):
- Gancho (10–15% de la duración) — línea contundente de 3–6 palabras
- Cuerpo 1 — Problema (~30%) — qué está roto / el cuello de botella
- Cuerpo 2 — Estadística o prueba (~15%) — la magnitud (usa gráfico de Plantilla 2 para B-roll)
- Cuerpo 3 — Cómo trabajamos (~25%) — el diferenciador
- Final / CTA (~15%) — invitación + marca
Para vídeos más largos (45s+), agrega escenas de Cuerpo adicionales entre Cuerpo 1 y Cuerpo 2 (ej. "Cuerpo 1a — Punto de dolor específico", "Cuerpo 1b — Costo de la inacción").
Prosodia para 11Labs eleven_multilingual_v2: la puntuación impulsa el ritmo (comas = micropausas, puntos = pausas completas, guiones largos = pausa). No te molestes con SSML o etiquetas de emoción — multilingual_v2 no las respeta. Simplemente escribe prosa conversacional con puntuación natural.
Guarda el guion en template-16x9/script.txt para trazabilidad.
Etapa 4 — Voz (11Labs)
Llama a 11Labs TTS con eleven_multilingual_v2. Voz por defecto: $ELEVENLABS_VOICE_ID de .env (o la que el usuario especifique / la marca prefiera — pregunta si no está claro).
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/$ELEVENLABS_VOICE_ID" \
-H "xi-api-key: $ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"<guion>","model_id":"eleven_multilingual_v2"}' \
--output assets/voice_raw.mp3
Post-procesa el volumen al 92% mediante FFmpeg (el estándar del pipeline):
ffmpeg -y -i voice_raw.mp3 -af "volume=0.92" -c:a libmp3lame -b:a 192k voice.mp3
Etapa 5 — Avatar (HeyGen)
Elige un talking_photo_id (ID de Look). El valor por defecto proviene de $HEYGEN_TALKING_PHOTO_ID en .env (cualquier Look de foto parlante en tu cuenta de HeyGen).
Siempre establece use_avatar_v_model: true a nivel de personaje. HeyGen recurrirá silenciosamente a Avatar IV si el Look no está inscrito en V (un Look no inscrito recurre a IV; el renderizado no se ve afectado).
Sube la voz → envía renderizado de foto parlante → consulta → descarga → clave de croma:
# Subir audio
AUDIO_ID=$(curl -s -X POST "https://upload.heygen.com/v1/asset" \
-H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: audio/mpeg" \
--data-binary @assets/voice.mp3 | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['id'])")
# Enviar renderizado
VID=$(curl -s -X POST "https://api.heygen.com/v2/video/generate" \
-H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: application/json" \
--data-binary @- <<EOF | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['video_id'])"
{
"video_inputs": [{
"character": {
"type": "talking_photo",
"talking_photo_id": "$HEYGEN_TALKING_PHOTO_ID",
"use_avatar_v_model": true
},
"voice": { "type": "audio", "audio_asset_id": "$AUDIO_ID" },
"background": { "type": "color", "value": "#00FF00" }
}],
"dimension": { "width": 720, "height": 1280 }
}
EOF
)
# Consultar hasta que se complete (típicamente 60–90s para IV, 5–20min para V en primer renderizado con un nuevo Look)
# GET https://api.heygen.com/v1/video_status.get?video_id=$VID → data.status == "completed"
# Luego descargar data.video_url a assets/avatar_green.mp4
Etapa 6 — Clave de croma + relleno simétrico
Convierte el MP4 de pantalla verde de HeyGen → webm VP9 transparente con relleno de fotograma congelado de 0.5s en ambos extremos:
# Clave de croma + eliminación de color → webm transparente sin procesar
ffmpeg -y -i avatar_green.mp4 \
-vf "chromakey=0x00FF00:0.10:0.05,despill=type=green:mix=0.6:expand=0" \
-c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
avatar.raw.webm
# Rellenar ambos extremos con fotogramas congelados de 0.5s (preserva alfa)
ffmpeg -y -c:v libvpx-vp9 -i avatar.raw.webm \
-vf "tpad=start_duration=0.5:start_mode=clone:stop_duration=0.5:stop_mode=clone" \
-c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
avatar.webm
Rellena simétricamente voice.mp3 con 0.5s de silencio en ambos extremos para que los desplazamientos de audio coincidan con la sincronización del avatar:
ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t 0.5 -c:a libmp3lame -b:a 192k silence.mp3
ffmpeg -y -f concat -safe 0 -i <(printf "file '%s/silence.mp3'\nfile '%s/voice_raw.mp3'\nfile '%s/silence.mp3'\n" "$PWD" "$PWD" "$PWD") \
-c:a libmp3lame -b:a 192k voice.mp3
Esto logra la regla de sincronización: avatar aparece → comienza el discurso → termina el discurso → avatar se desvanece. (La regla es 0.5s de inicio + 0.5s de final, todas las señales de escena GSAP desplazadas +0.5s, el desvanecimiento final comienza 0.1s después del final del discurso).
Etapa 7 — Calibración de object-position
La posición de la cara del avatar en el fotograma depende de la foto de origen, por lo tanto, recalibra por ID de Look:
ffmpeg -y -ss 0.7 -i avatar.webm -vframes 1 avatar-frame-check.png
Lee el fotograma, mide la coordenada y del centro de la cara (en el origen de 1280 de alto). Calcula object-position por diseño:
object_position_y_pct = ( (face_y_px / 1280) * scaled_height_for_layout - layout_slot_height/2 ) / (scaled_height_for_layout - layout_slot_height) * 100
En la práctica: cara en el tercio superior del fotograma (face_y ~380) → usa '50% 30%' para espacios estrechos, '50% 50%' para espacios de fotograma completo. Actualiza LAYOUT_AVATAR_SLOTS en index.html. Nunca adivines — siempre calibra a partir de un fotograma extraído.
Etapa 8 — Imágenes B-roll (Nano Banana 2 vía KIE.AI)
Dos plantillas fijas. Los colores de la marca se intercambian por proyecto (sustituye BG_HEX y ACCENT_HEX de brand.json).
Plantilla 1 — Escultura abstracta pura (atmósfera, estado de ánimo, ritmos narrativos):
Renderizado escultórico 3D abstracto sobre un fondo sólido
[BG_HEX].[DESCRIPCIÓN_FORMA], sugiriendo[INTENCIÓN_MOVIMIENTO]. La luz[ACCENT_HEX]se refracta a través y alrededor de la forma con dispersión subsuperficial, proyectando causticas suaves sobre un suelo oscuro sutilmente reflectante. Iluminación de estudio direccional suave. Renderizado hiperrealista Octane. Estética de keynote tecnológico premium. Enfoque nítido en la forma central, profundidad de campo que se desvanece en las sombras en los bordes. Sin texto, sin logotipos.
Plantilla 2 — Gráfico de vidrio (cualquier línea que haga referencia a una estadística, comparación, crecimiento, proporción, "X×", "Y%"):
Visualización de datos 3D abstracta sobre un fondo sólido
[BG_HEX].[TIPO_GRÁFICO]representado enteramente como formas de vidrio translúcido flotantes que representan[CONCEPTO_DATOS]. Elementos de línea base en vidrio mate gris apagado; elementos focales brillando con dispersión subsuperficial y refracción de color[ACCENT_HEX], proyectando causticas suaves sobre un suelo oscuro sutilmente reflectante. Una delgada línea de eje de color blanco roto. Iluminación de estudio direccional suave. Renderizado hiperrealista Octane. Estética de keynote tecnológico premium. Composición editorial minimalista con amplio espacio negativo. Sin texto, sin números, sin etiquetas, sin logotipos.
Regla de decisión por escena: si la línea del guion cita un número/estadística/comparación → Plantilla 2. En caso contrario → Plantilla 1.
Patrón de envío (aspecto 1:1 por defecto; cualquier aspecto compatible). Siempre captura el código HTTP + el cuerpo para que los fallos 4xx se autodiagnostiquen:
source .env && RESPONSE=$(curl -sS -w "\nHTTP_CODE:%{http_code}" -X POST "https://api.kie.ai/api/v1/playground/createTask" \
-H "Authorization: Bearer $KIE_AI_API_KEY" -H "Content-Type: application/json" \
--data-binary @- <<EOF
{"model":"nano-banana-2","input":{"prompt":"<PLANTILLA CON ESPACIOS RELLENOS>","output_format":"png","image_size":"1:1"}}
EOF
)
echo "$RESPONSE"
[[ "$RESPONSE" == *"HTTP_CODE:200"* ]] || { echo "El envío a KIE falló — ver cuerpo arriba"; exit 1; }
Consulta https://api.kie.ai/api/v1/playground/recordInfo?taskId=<id> cada 4s hasta que data.state == "success", analiza data.resultJson (es una cadena JSON — haz json.loads()), descarga la URL en assets/broll-N.png.
Ejecuta múltiples generaciones de B-roll en paralelo — KIE.AI maneja bien tareas concurrentes.
Causa común de error 400: filtro de seguridad del prompt. Nano Banana 2 rechaza prompts que puedan interpretarse como legales/violencia/conflicto (ej. "tribunal", "batalla legal", "demandantes vs demandados)). Mantente estrictamente dentro de las dos plantillas abstractas — codifica el significado en geometría/color, nunca en el tema literal. Validado 2026-04-28: una sonda abstracta mínima devuelve 200 con la misma autenticación/esquema, por lo que un 400 aquí es casi siempre contenido del prompt.
Etapa 9 — Música de fondo (11Labs Music)
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/music?output_format=mp3_44100_128" \
-H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
-d '{
"prompt": "<PROMPT MÚSICA>",
"music_length_ms": 22000,
"force_instrumental": true,
"model_id": "music_v1"
}' --output assets/music_raw.mp3
Devuelve bytes de audio sincrónicamente. music_length_ms coincide con la duración de la composición (rango 3000–600000ms).
Prompt de música por defecto para fondo de anuncio B2B (validado 2026-04-27):
Subrayado instrumental optimista y alegre para un anuncio de negocio B2B. Piano moderno brillante que toca un patrón rítmico progresivo con notas nítidas staccato, combinado con pads de sintetizador sutiles y edificantes. Pulso ligero suave — agitadores suaves o clics rítmicos apagados que proporcionan un impulso constante hacia adelante. Sin baterías grandes, sin bombos, sin platillos, sin címbalos. Sin voces. Sensación segura, animada, enérgica, optimista. Corporativo moderno, limpio, tecnológico, profesional y contemporáneo. Tempo alrededor de 115 BPM. Tonalidad mayor brillante, soleada pero no empalagosa. Dinámica uniforme durante todo — sin aumentos, sin caídas, sin clímax, sin desvanecimientos — pero con un impulso rítmico constante. Suena como la música de fondo de un video de lanzamiento de producto SaaS moderno.
Antipatrones a evitar en el prompt:
- "Cinematográfico" / "atmosférico" / "ambiental" → produce un arrastre sentimental, incorrecto para anuncios
- Tempo por debajo de 90 BPM → demasiado soñoliento
- Mencionar aumentos, clímax, cambios de dinámica → compite con la voz
- Olvidar "sin voces" → ElevenLabs puede agregar tarareos
Mezcla a -20dB con breves desvanecimientos para que se sitúe invisiblemente bajo la voz:
ffmpeg -y -i music_raw.mp3 \
-af "volume=-20dB,afade=t=in:st=0:d=0.4,afade=t=out:st=<fin-0.6>:d=0.6" \
-c:a libmp3lame -b:a 192k music.mp3
Etapa 10 — Ensamblaje de la composición
El archivo template-16x9/index.html es la composición de trabajo. Para cada renderizado:
- Actualiza
data-durationen los elementos raíz, voz, avatar y música para que coincidan con la duración objetivo - Actualiza los colores de la marca en
styles/brand.css(variables--bg,--accent, etc.) - Actualiza las fuentes en
brand.csssi la marca utiliza familias diferentes - Reajusta las transiciones de escena en la línea de tiempo de GSAP para que coincidan con los ritmos del guion
- Asegúrate de que los 4 elementos sincronizados (video avatar, audio voz, audio música, composición raíz) tengan
data-startydata-durationalineados
Índices de pistas de audio: avatar=1, voice=2, music=3. Todos class="clip". Todos data-start="0".
Etapa 11 — Renderizado
cd "$PIPELINE_ROOT/template-16x9" && \
npx hyperframes lint && \
npx hyperframes render --output renders/<marca>-v<n>.mp4
CRÍTICO: Ejecuta el renderizado en primer plano. Los renderizados en segundo plano se quedan colgados al 0% de CPU después de que comienza la captura de fotogramas. Usa una llamada Bash en primer plano con timeout: 300000. El renderizado toma entre ~1 y 2 minutos para una composición de 22s, entre ~3 y 4 minutos para 45s.
Después de que el renderizado se complete, open -a "QuickTime Player" renders/<marca>-v<n>.mp4 para revisión.
Bucle de iteración
La mayoría de los renderizados necesitan de 1 a 3 pases:
- v1: hacer que la cadena funcione de extremo a extremo con valores predeterminados sensatos
- v2: corregir problemas obvios (recorte de cara, música demasiado alta, transiciones fuera de tiempo, avatar no sincronizado)
- v3: refinar — mejorar prompts de B-roll, ajustar entonación del guion, sincronización de CTA, etc.
Regla de oro: el pipeline puede tomar ~10-15 minutos por video (incluyendo la generación del avatar V de HeyGen, que es lo que más tiempo consume). Muéstrale al usuario un progreso preliminar, no solo un spinner.
Preguntas para el usuario (solo si es necesario)
El pipeline está diseñado para funcionar con las opciones por defecto que se encuentran en .env.example. Sin embargo, si el usuario no ha configurado una variable obligatoria, pregúntale. No preguntes si ya se ha establecido en .env.
HEYGEN_TALKING_PHOTO_ID— "¿Qué Look de avatar te gustaría usar (proporciona el ID de talking_photo de HeyGen)?"ELEVENLABS_VOICE_ID— "¿Qué voz de ElevenLabs debería usar? Proporciona el ID o un nombre de voz popular ('Brian', 'Rachel', etc.)"- Duración del video — "¿Prefieres una duración de video de 22s, 45s o 60s?"
Selecciones de voz comunes:
EXAVITQu4vrCxn3E8Nk— "Brian" (barítono, serio, seguro, el predeterminado más popular)21m00Tcm4TlvDq8ikWAM— "Rachel" (voz femenina clara, amigable pero profesional)ODq5zmih8GrVes37Dizd— "Patrick" (tono grave y cálido)pNInz6obpgDQGcFmaJgB— "Adam" (voz masculina versátil, buena para contenido técnico)
Pregunta solo si el usuario no ha expresado una preferencia o si la variable de entorno no está configurada.