Avatar Mix

avatar-mix

Pipeline para producir un video 16:9 (1920x1080) donde el avatar HeyGen del usuario presenta contenido sobre fondos generados, con un montaje que va alternando 3 modos.

Motores

• HeyGen MCP (https://mcp.heygen.com/mcp/v1/, OAuth) → avatar hablando + audio/SFX.
• HyperFrames (npx hyperframes) o tarjetas PIL → video de fondo.
• FFmpeg (scripts/composite.py) → montaje, chroma-key, transiciones, mezcla de audio.

Identidad del avatar (config por usuario)

• Copia config/avatar.example.json a config/avatar.json y rellena avatar_id + voice_id (descúbrelos con list_avatar_looks / list_voices del MCP; get_current_user para la cuenta).
• config/avatar.json está en .gitignore (es personal). Engine por defecto: Avatar V.
• Plan HeyGen recomendado: Creator (600 créditos). El free no permite varias escenas ni TTS.

Set multicámara (looks del avatar)

config/avatar.json → multicam.looks: varios looks del MISMO avatar y fondo con encuadres distintos (plano medio / primer plano, en horizontal y vertical). Intercalarlos por escena = multicámara real (mucho mejor que cualquier zoom fake). Cada look lleva aspect y framing.

Plan de cámaras (obligatorio al escribir el guion): asignar a cada escena un look del set:

• Nunca dos escenas seguidas con el mismo look (si el avatar es visible en ambas).
• fullscreen en proyectos 16:9 o doble formato → SOLO looks 16:9, alternando wide/close entre escenas fullscreen consecutivas (los verticales recortarían fatal a pantalla completa en 16:9).
• side y corner → cualquier look (el recuadro recorta); los verticales encajan de lujo aquí y así se intercalan también en videos horizontales. En corner favorece un close.
• Videos SOLO 9:16 (reels) → looks verticales en fullscreen (encuadre nativo, más real).
• El patrón debe cambiar en cada video (qué modo sigue a cuál, qué look abre, dónde va el side, cuántos enter…). Nunca repetir el plan del video anterior.

Los 4 modos de escena

• fullscreen → avatar a pantalla completa (arranque siempre en este modo).
• corner → fondo a pantalla completa + avatar en recuadro PiP (webcam). NO se borra el fondo (borde + esquinas redondeadas). En 16:9 va abajo-derecha (corner en config, ~28%). En 9:16 va centrado abajo y más grande (corner_9x16 en config: ~58%, position: bottom-center).
• side → split-screen: fondo full + avatar en panel lateral a toda altura (~42%, side en config, derecha por defecto). El bg_visual de estas escenas debe componer su contenido en la mitad IZQUIERDA (el panel tapa la derecha). En 9:16 cae automáticamente a corner.
• bg_only → solo el fondo; la voz del avatar sigue como locucion.
• enter: "slide" (opcional, en corner/side): el avatar entra deslizándose desde su borde (0.6s ease-out). Usar 1–2 veces por video, idealmente tras una escena fullscreen y con transition: "cut" en la escena anterior (con fade el avatar se ve doblado durante el cruce).

Flujo (orden estricto por dependencias)

0. Config (una vez)

• config/avatar.json: rellenar avatar_id y voice_id. Obtenerlos con las tools MCP list_avatar_looks y list_voices (o get_current_user).
• Verificar entorno: ffmpeg -version, node -v (>=22), MCP conectado (get_current_user).

1. Entrada → guion por escenas

• Si la fuente es URL → WebFetch para extraer el contenido. Si es guion, usarlo tal cual.
• El guion se escribe COMO SE HABLA, no como se escribe (directriz de realismo: el TTS plano delata al avatar más que la cara). Reglas: frases cortas; preguntas retóricas ("¿Y esto qué significa?"); coletillas naturales ("ojo con esto", "y aquí viene lo bueno"); puntos suspensivos para forzar pausas; números redondeados como se dicen ("casi nueve mil euros", no "8.412,55"). Nada de sintaxis "de blog" (subordinadas largas, conectores formales tipo "asimismo").
• Máximo realismo (opcional): create_video_from_avatar acepta audio en vez de script. Se puede generar la locución fuera (TTS más expresivo, o el usuario grabándose) y HeyGen solo hace el lipsync — respiraciones y énfasis reales. Ofrecerlo cuando el video sea importante.
• Redactar el guion hablado y segmentarlo en escenas. Crear work/<slug>/script.json (ver templates/script.example.json). Reglas:
  • Escena 1 = fullscreen.
  • Alternar corner / side / bg_only / fullscreen segun el ritmo del contenido, siguiendo el plan de cámaras (ver sección multicámara): patrón distinto en cada video.
  • Cada escena: id, mode, narration, look (id del look del set multicam), enter (opcional: "slide" en corner/side), bg_visual (headline, subline/bullets, style), transition (fade|slide|cut), transition_after_sec.
  • style de bg_visual: title_card | bullets | fullbleed | screenshot (con image).

2. Avatar (HeyGen MCP) — un clip por escena

Para cada escena, igual en todos los modos (no se toca el fondo del avatar):

• mcp__heygen__create_video_from_avatar con avatarId = el look de la escena (plan de cámaras; fallback: avatar_id de config), voiceId, script = narration, aspectRatio = el aspect del look (16:9 para looks horizontales, 9:16 para verticales), resolution: "1080p" (usar 720p en pruebas), y SIEMPRE engine: {"type": "avatar_v"} (mejor calidad; ver config). Devuelve video_id y status: waiting.
• SIEMPRE pasar motionPrompt (photo_avatar + Avatar V lo admite; NO usar expressiveness, que es solo Avatar IV y lo rechaza con avatar_v). Variar el motionPrompt POR ESCENA según su función, no usar el mismo en todo el video (rompe la sensación de "misma persona en bucle"). Guía:
  • Hook / intro (escena 1): "High energy, leans slightly toward the camera; expressive eyebrows; quick confident hand gestures; direct eye contact, as if hooking the viewer in the first seconds."
  • Explicación / desarrollo: "Calm, measured delivery; occasional thoughtful pauses; subtle nods; natural hand gestures that emphasize key points; gestures a bit more when mentioning numbers or results."
  • CTA / cierre: "Direct and confident; a small warm smile; slower deliberate gestures; steady eye contact with the camera, as if closing a deal." Coste extra: 0 (solo un parámetro). Afinar los textos al tono de cada video.
• Plan free: cuota mensual de avatar muy limitada (~3 videos) y SIN TTS. Para varias escenas hace falta plan Creator ($29/mes, 600 creditos). ~20 creditos por video de 1 min.
• Poll con mcp__heygen__get_video (o REST GET /v1/video_status.get?video_id=... con X-Api-Key del .env) hasta completed; coger video_url.
• Descargar a work/<slug>/clips/avatar_<id>.mp4 (curl).
• En bg_only el clip se genera igual; en el montaje solo se usa su audio.

3. Medir duraciones → completar script.json

• Para cada clip: ffprobe -v error -show_entries format=duration -of default=nk=1:nw=1 clip.
• Escribir duration (segundos) en cada escena de script.json. Obligatorio antes del paso 4.

4. Fondos (uno por escena → work/<slug>/<bgdir>/<id>.mp4)

REGLA DE ORO (directriz del usuario): los fondos deben ser gráficos animados PROPIOS, explicativos y visuales, NO capturas de la web casi nunca. Generar nosotros con HyperFrames mock-ups y data-viz que EXPLIQUEN el producto. Usar hyperframes capture <url> solo de forma puntual (1 escena como mucho) cuando una prueba real aporte; no como recurso por defecto.

Componentes custom que funcionan muy bien (autorízalos en work/<slug>/hf/index.html):

• Chat del agente: burbujas usuario/agente que entran en secuencia, con checks (✓ Conciliada…), adjuntos (📎 factura.pdf) y chips de preguntas. Comunica "todo desde un chat".
• Tarjeta de datos / conciliación: card con número que cuenta (GSAP onUpdate → fmtEur con miles "8.412,55 €"), filas (cobros/comisiones/reembolsos) y sello "Conciliado". Para cifras/dinero.
• Hub de integraciones: pill central "tu-app · API + MCP" → chips Claude/Cursor/ChatGPT + nota.
• Title cards (intro/outro) y flujos (icono→agente→hecho).
• Badge de marca SIEMPRE (directriz del usuario, 2026-07-09): logo + tagline arriba-izquierda en toda escena con gráficos (corner/side/bg_only), salvo reveals/title cards donde el wordmark grande ya es la firma, o videos marcados "sin marca". Ref: .badge en work/launch2/hf/index.html.
• Estética de marca: bg #0b0f1a, accent #3ddc97, glows en deriva, entradas animadas, paneo/zoom suave.

Modo rápido sin gráficos ricos: --mode card (tarjetas PIL responsivas).

Capturas reales de navegador como fondo (validado en claude-aikount, 2026-07-10): para tutoriales, grabar el flujo real con las tools de claude-in-chrome (gif_creator, sin watermark ni labels) → GIF→MP4 (ffmpeg -vf fps=30) en work/<slug>/captures/. El index.html dibuja solo la .capzone (marco vacío) y python3 scripts/overlay_captures.py --slug <slug> --aspect ... incrusta cada captura en su zona tras make_bg (lee bg_visual.capture + zone_16x9/zone_9x16 del script.json; congela el último frame con tpad; entra en t=1.2s). OJO: revisar que en las capturas no salgan tokens/API keys (revocar antes de publicar) ni contenido no deseado (recortar con -t si hace falta).

Registro siempre al día: en cada render de HyperFrames el skill sincroniza las animaciones nuevas del registro (scripts/sync_animations.py, lo llama make_bg.py una vez por proyecto vía marcador .animations_synced). Así las animaciones que vaya publicando HeyGen (p. ej. las 9 de código: code-typing, code-diff, code-highlight, code-morph, code-particle-assemble…) aparecen disponibles en compositions/ sin tocar nada. Manual: python3 scripts/sync_animations.py --hf work/<slug>/hf (o --all para todo el registro; HF_NO_SYNC=1 lo desactiva). Úsalas vía data-composition-src="compositions/<nombre>.html". Ideal para vídeos code/dev explainer (avatar en corner + animación de código de fondo).

Animaciones al ritmo de la voz (directriz del usuario — validado en mejor-ia-contabilidad): los elementos NO se pintan del tirón con staggers fijos; cada tile/burbuja/fila/sello aparece cuando la narración dice exactamente eso. Flujo:

1. Por cada escena con gráficos, mcp__heygen__create_speech con la MISMA voz+speed+locale del avatar y el texto exacto de narration → devuelve word_timestamps (start/end por palabra).
2. Escalar cada timestamp a la duración real del clip: t_real = t_tts × (dur_clip / dur_tts) (el clip de avatar trae lead-in/tail; el escalado lineal es suficiente, ±0.5s es aceptable y mejor que llegue un pelín antes que después).
3. Elegir la palabra-gatillo de cada elemento (ej.: tile "conciliar el banco" → palabra "conciliar"; sello "Conciliado" → la palabra final "conciliado"; chip Claude → "Claude"; contador de dinero → "el dinero llega"). Poner esos tiempos como offsets absolutos en las animaciones GSAP del index.html (arrays tipo const T2=[7.0,9.66,...] por escena, comentando la palabra-gatillo de cada uno).
4. Actualizar sfx_manifest.json con los MISMOS tiempos (pop al aparecer el elemento, chime en los checks, achievement en el sello final, coins al hablar de dinero). Nota: los timestamps del TTS starfish con la voz habitual clavan el pacing del clip Avatar V (misma fuente); si cambian los clips (regeneración), re-medir duraciones y re-escalar.

Flujo HyperFrames (v0.6.98, requiere Chrome — validado):

1. Dos proyectos por formato: work/<slug>/hf/ (16:9, root 1920x1080) y work/<slug>/hf_9x16/ (vertical, root 1080x1920). make_bg.py elige por --aspect. Scaffold: npx hyperframes init hf (copiar package/hyperframes/meta.json al hf_9x16).
2. Autorizar index.html con los componentes custom: cada escena = elementos class="clip" + data-start(acumulado)/data-duration(real)/data-track-index; timeline maestra paused en window.__timelines["main"]; data-duration del root = total. Solo lógica determinista.
3. python3 scripts/make_bg.py --slug <slug> --mode hyperframes --aspect 16:9|9:16 (renderiza el proyecto y trocea renders/ en <bgdir>/<id>.mp4). Para máxima calidad se pueden instalar las skills oficiales (npx skills add heygen-com/hyperframes → /hyperframes-read-first).