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).

5. Musica / SFX (HeyGen MCP) — CONTEXTUAL POR VIDEO

La gracia: elegir SFX que peguen con el contenido de CADA video, no siempre los mismos.

• Musica: search_audio_sounds (type=music) con music_query → assets/music.*.
• SFX base: whoosh de transicion → assets/sfx/whoosh.mp3.
• SFX contextuales: leer el guion y, por cada momento que lo pida, buscar el efecto adecuado en

HeyGen (type=sound_effects) y descargarlo a assets/sfx/. Ej.: "riser" en la intro,

"coins/cash register" al hablar de dinero/Stripe, "single chime/notification" cuando aparece un

chat, "achievement" al completar algo (factura conciliada, 303 listo).

• Escribir el manifiesto work/<slug>/sfx_manifest.json:

[{ "scene": <id>, "offset": <seg desde inicio de la escena>, "file": "assets/sfx/x.mp3", "gain_db": -12 }]

(tambien admite {"at": <seg en timeline final>}).

• HeyGen es la fuente de SFX; no hay otro CLI para esto (HyperFrames tts/beats es voz/musica).

6. Montaje (FFmpeg)

• python3 scripts/composite.py --slug <slug> --aspect 16:9|9:16 [--music ...] [--whoosh assets/sfx/whoosh.mp3] [--sfx-manifest work/<slug>/sfx_manifest.json]
• Produce output/<slug>{_9x16}.mp4, con los 4 modos, transiciones (xfade/acrossfade),

musica con ducking (sidechaincompress) y SFX (con alimiter final).

La salida YA sale sin metadata (composite.py llama a strip_meta al final). Un solo archivo limpio.

• Pases de realismo automáticos (todos activos por defecto, con flag para desactivar):
• Punch-in en escenas fullscreen: zoom lento continuo 1.00→1.05 (1.04 en 9:16) durante

toda la escena, la cámara nunca está quieta. SIN cortes de encuadre (directriz del

usuario: el corte "multicam" no gusta; el zoom sí). Desactivar: --no-punch.

• Grading unificado: eq (contraste/saturación) + viñeta suave sobre todas las escenas

(avatar y fondos comparten look). El grano fino va SOLO sobre el avatar (frame completo

en fullscreen, píxeles del PiP en corner) — nunca sobre los gráficos de HyperFrames

(directriz del usuario: en gráficos no tiene sentido). Ajustable en config/avatar.json →

"grade": {contrast, saturation, vignette_angle, grain, enabled}. Desactivar: --no-grade.

• Loudnorm final a -14 LUFS / -1.5 dBTP (target YouTube/TikTok), sobre la mezcla completa.

Desactivar: --no-loudnorm.

• Doble formato sin gastar avatar: los mismos clips sirven para 16:9 y 9:16. Atajo:

bash scripts/run.sh <slug> <musica> <card|hyperframes> both genera las dos versiones (ya limpias).

6.5 Subtítulos estilo Hormozi (recomendado para 9:16 — Reels/TikTok)

Palabras grandes en MAYÚSCULAS, palabra activa resaltada en acento, animadas. Flujo:

• Timing por palabra, dos fuentes (guardar en work/<slug>/captions_src.json,

[{id, tts_dur, words:[{t,start,end}]}]):

• mcp__heygen__create_speech (voz starfish) → word_timestamps (gasta créditos API; escalar

t_real = t_tts × dur_clip/dur_tts).

• whisper.cpp local (PREFERIDO, validado 2026-07-10, gratis y sin escalado): transcribir el

clip final → ffmpeg -ar 16000 -ac 1 + `~/Documents/whisper.cpp/build/bin/main -m

models/ggml-small.bin -l es -ml 1 -sow -oj` → timestamps exactos del audio real (f=1);

también sirve para los triggers de las animaciones. CORREGIR marcas mal transcritas

(Cloud/Clout→Claude, iCount→aikount) antes de quemar subs. El whisper de Anaconda (Python)

sigue roto (NumPy/Numba) — usar SIEMPRE el binario de whisper.cpp.

• python3 scripts/make_captions.py --slug <slug> --aspect 9:16 → genera work/<slug>/hf_captions/

(proyecto HyperFrames transparente; escala cada escena a la duración real del clip y evita solapes).

• python3 scripts/burn_captions.py --slug <slug> --aspect 9:16 → renderiza el MOV con alfa

(ProRes 4444), hace el overlay, deja la salida sin metadata y borra el MOV. Produce

output/<slug>_9x16_subs.mp4 (un solo archivo limpio).

• Detalles internos: MOV (no WebM; el VP9-alpha no overlaya bien con este FFmpeg). capY (~60% alto)

coloca los subs por encima del avatar (bottom-center).

7. Entregar

• Mostrar la ruta de output/<slug>.mp4 y un resumen de escenas/duracion.
• Los MP4 de output/ ya salen sin metadata (encoder/fecha/handler) — no hay doble versión.

scripts/strip_meta.sh queda disponible por si hay que limpiar un fichero externo.

8. Publicar en redes (Upload-Post API — subida directa del fichero local)

Sube los DOS formatos a todas las redes con scripts/publish.sh (API REST de Upload-Post via curl;

sube el MP4 local directamente, sin staging ni URL pública). Genérico: cada persona usa su

UPLOAD_POST_API_KEY (.env) y su propio perfil.

• Perfil: cada cuenta tiene uno o varios "user profiles" con sus redes conectadas. Listar con

curl -H "Authorization: Apikey $KEY" https://api.upload-post.com/api/uploadposts/users.

• Vertical (con subs) → short-form:

bash scripts/publish.sh output/<slug>_9x16_subs.mp4 <perfil> tiktok,instagram,youtube,threads "<titulo>" "<desc>" "#hashtags" REELS

• Horizontal → long-form:

bash scripts/publish.sh output/<slug>.mp4 <perfil> youtube,linkedin,facebook,x "<titulo>" "<desc>"

• El script es asincrono (request_id) y hace poll a /uploadposts/status. Confirmar SIEMPRE antes.
• Regla: vertical → TikTok/Reels/Shorts/Threads · horizontal → YouTube/LinkedIn/Facebook/X.
• Declaración de IA obligatoria (directriz del usuario, 2026-07-08): en YouTube SIEMPRE

youtubeContainsSyntheticMedia: true (y en TikTok tiktokIsAigc: true). El avatar realista

con voz clonada lo exige la política de la plataforma; la nota es discreta y no declarar

expone el canal a strikes/retirada.

• Alternativa: el MCP Upload-Post (tools upload_video/get_status), pero al ser remoto NO lee

rutas locales (requiere open_upload_studio o URL publica) — por eso el script con la API es mejor aqui.

Atajo determinista

Pasos 3-6 (cuando ya existen clips/avatar_<id>.mp4): bash scripts/run.sh <slug> [musica].

Estructura por proyecto (work/<slug>/)

• script.json (guion+duraciones), clips/avatar_<id>.mp4 (HeyGen Avatar V),
• hf/ (proyecto HyperFrames 16:9) y hf_9x16/ (proyecto HyperFrames vertical),
• hf/captured/ (solo si se usó hyperframes capture puntual),
• bg/ y bg_9x16/ (fondos troceados por escena), sfx_manifest.json.

Notas

• config/avatar.json: marca, corner (PiP 16:9) y corner_9x16 (PiP vertical: bottom-center, ~58%).
• Si make_bg --mode card no encuentra fuente TTF, instalar fuentes o usar --mode hyperframes.
• El FFmpeg de Homebrew de esta maquina no trae drawtext (sin libfreetype): las tarjetas PIL

se renderizan con Pillow. Los gráficos ricos van por HyperFrames (Chrome headless).