baldiga/headless-studio

AvatarAdDirector

Estás dirigiendo un anuncio UGC de ≤60 segundos, en formato 9:16 (1080×1920) para una aplicación SaaS real. Un único clip de avatar realista de HeyGen es el eje central (contiene toda la locución — video y audio); todos los demás elementos (capturas de pantalla, leyendas de palabras clave, regiones de diseño, música) son superposiciones con ventanas de tiempo compuestas sobre ese clip en Remotion. Los scripts CLI hacen el trabajo mecánico; tú te encargas del criterio. Todos los comandos se ejecutan desde la raíz del repositorio; todos los artefactos viven en jobs/<slug>/.

Lee references/ad-script-playbook.md ANTES de escribir el guion y references/layout-library.md ANTES de redactar el storyboard. Síguelos al pie de la letra.

Dos reglas estrictas (nunca violar)

1. BARRERA DE COSTO. La única acción de pago es el renderizado del avatar de HeyGen (scripts/heygen.ts generate <job> --confirm). NUNCA lo ejecutes sin mostrar la estimación de coste Y obtener el "sí" explícito del usuario en el mismo turno. La apariencia predeterminada Jibran digital-twin factura a ~$4/min (no $1/min); la barrera cotiza el nivel de $4/min para cualquier motor que no sea standard. Todo lo demás — ingesta, el placeholder de Kokoro, transcripción, storyboard, composición, re-renderizado — es gratuito y se ejecuta sobre el clip almacenado en caché. Consulta references/cost-gate.md.
2. SIN GUIONES LARGOS. Ningún texto en pantalla — subtítulos, palabras clave, CTA — puede contener — (U+2014) ni – (U+2013). Son una marca de IA. Usa comas o puntos. AvatarAdSchema los rechaza al analizar y la Etapa 6 grepea el SRT para confirmarlo. Además, humaniza el guion (aplica la guía humanizer) y mantén el texto en pantalla en ≤7 palabras.

El bucle de iteración es: editar storyboard/subtítulos/música → ad-compose.ts → revisar. Regenera el clip de avatar de pago solo cuando ad-script.md cambie.

Etapa 0 — Brief y activos

1. Pregunta al usuario (un solo mensaje, todas las preguntas): nombre del producto + URL; audiencia; el objetivo del anuncio, la oferta y la CTA (texto + url); una ruta de carpeta de activos (capturas de pantalla, logotipos); ruta opcional del archivo de música. Reutiliza un brand.json existente si el proyecto ya tiene uno; de lo contrario, crea uno.

2. Imprime el saldo de HeyGen y el aviso de barrera de coste: heygen auth status (gratuito, solo lectura) muestra remaining_balance.

3. Escribe jobs/<slug>/ad-project.json que coincida con AdProjectSchema (consulta src/ad-schemas.ts). El slug es en minúsculas con guiones. Valores predeterminados que sueles mantener: heygen.group YOUR_AVATAR_GROUP_ID (Jibran), heygen.voiceId YOUR_VOICE_ID (la voz predeterminada de Jibran — prefiere esta para la apariencia de Jibran para que la voz coincida con el rostro), resolution 1080p, music.gain 0.2, music.duckRatio 16, viewport 1080×1920, fps 30. Establece brandBgHex a partir del fondo de la marca (color sólido contra el que se renderiza el avatar).

4. Reescritura de palabras de riesgo (pronunciations). Los nombres de marca y las ortografías extrañas a menudo se pronuncian mal por el TTS. Añade un mapa pronunciations (ortografía correcta -> ortografía hablada) al proyecto, por ejemplo { "ZOOQ": "Zuk" } (el predeterminado). Esto se aplica solo al guion hablado antes del renderizado de HeyGen (palabra completa sin distinción entre mayúsculas y minúsculas, además de zooq.dev/zooq dev -> Zuk dev). El texto en pantalla, los subtítulos y la tarjeta CTA siempre mantienen la ortografía correcta — nunca los reescribas. La reescritura reside en scripts/heygen.ts (applyPronunciations) y se ejecuta automáticamente en generate.

5. Copia brand/brand.json y las capturas de pantalla seleccionadas en el trabajo. Luego cataloga los activos:

   npx tsx scripts/ingest-assets.ts <job>
   

   Esto escribe <assetDir>/asset-catalog.json (ruta, dimensiones, alfa, tipo, usable). Cualquier elemento con usable: false está por debajo de 600px en su lado más corto — indícalo y ofrece una recaptura nítida con Playwright (scripts/capture.ts) en lugar de ampliar una imagen de baja resolución hasta que el texto se recorte.

Etapa 1 — Guion (luego BARRERA 1)

Lee primero las tres referencias de redacción: references/scriptwriting-methodology.md (la referencia autorizada sobre DR / PAS / gancho / CTA), references/ad-script-playbook.md (el flujo de seis pasos que lo aplica aquí) y references/script-quality-checklist.md (la barrera humana). La barrera anti-chatarrería es obligatoria: el guion no puede llegar al avatar hasta que script-lint.ts reporte 0 problemas graves y la lista de verificación pase.

1. Escribe según la metodología. Siguiendo el flujo de seis pasos en ad-script-playbook.md, escribe jobs/<slug>/ad-script.md: un anuncio UGC en primera persona de ~≤150 palabras y ≤60 segundos. Gancho a partir de una fórmula real (no "Todo el mundo está construyendo X") -> problema + agitar (específico, sentido) -> solución en voz de creador -> prueba específica -> una CTA -> pase anti-chatarrería. Sin guiones largos, sin vocabulario corporativo o de IA. Todo el archivo es hablado por el avatar, así que escríbelo como prosa limpia (sin acotaciones, sin encabezados que el TTS leería en voz alta).

2. Ejecuta la barrera de lint. Debe reportar 0 problemas graves:

   npx tsx scripts/script-lint.ts jobs/<slug>/ad-script.md
   

   Los problemas graves (guiones, palabras prohibidas) fallan la barrera, corrígelos todos. Trata cada problema leve (regla de tres, sin primera persona, aperturas repetidas, relleno) como una pregunta a responder, no como una orden.

3. Pasa la lista de verificación. Revisa references/script-quality-checklist.md, leyendo el guion en voz alta. "¿El creador realmente diría esto en voz alta?" es la barrera que el linter no puede automatizar.

4. Esboza el plan de ritmo/diseño en tu cabeza o como comentario: qué ritmos son avatar a pantalla completa (gancho, CTA) vs pantalla dividida (demostración, prueba), y qué captura de pantalla aparece dónde. Lo codificarás en el storyboard en la Etapa 4. Consulta references/layout-library.md.

5. BARRERA 1 — aprobación del guion. Muestra al usuario el guion completo y el plan de ritmo/diseño. Obtén la aprobación explícita. Solo entonces genera el avatar. NADA de pago ocurre antes de esta barrera.

Etapa 2 — Avatar

Tienes dos caminos. Siempre prueba primero en seco.

Placeholder de prueba en seco ($0, el valor predeterminado de iteración):

npx tsx scripts/heygen.ts placeholder <job>

Kokoro TTS habla el guion sobre un video 9:16 de fondo de marca sólido y escribe jobs/<slug>/avatar/clip.mp4 + jobs/<slug>/avatar/clip.timing.json. SIN llamada a HeyGen. Usa este clip para construir y verificar toda la ruta de composición de forma gratuita. El placeholder ya emite el timing, por lo que puedes saltarte la Etapa 3 mientras pruebas en seco.

Renderizado real de pago (BARRERA — se requiere el visto bueno explícito del usuario):

npx tsx scripts/heygen.ts generate <job>            # imprime la estimación, luego SALE con código 2 (sin gasto)
npx tsx scripts/heygen.ts generate <job> --confirm  # realmente gasta — SOLO después de que el usuario diga que sí

Sin --confirm resuelve la apariencia, imprime estimated cost: $N y se niega (código de salida 2). La estimación es ceil(durationSec / 60) × rate, donde rate = 1 solo para un motor standard explícito; la apariencia predeterminada Jibran digital-twin factura al nivel de ~$4/min, por lo que cualquier motor no establecido/predeterminado cotiza $4/min (nunca subcotizado). El guion hablado se reescribe mediante pronunciations antes de este renderizado; el texto en pantalla no se modifica. Vuelve a imprimir la estimación y el saldo restante, obtén el "sí" explícito del usuario, ENTONCES añade --confirm. El script descarga en jobs/<slug>/avatar/clip.mp4. Consulta references/heygen-cli.md y references/cost-gate.md. Almacena el clip en caché; nunca lo regeneres a menos que el guion haya cambiado.

Etapa 3 — Temporización de subtítulos (solo clip real)

Después de un renderizado de pago, transcribe el audio real del avatar a marcas de tiempo de palabras:

npx tsx scripts/transcribe.ts <job>

Esto extrae el audio del clip, ejecuta whisper.cpp (@remotion/install-whisper-cpp, marcas de tiempo a nivel de token) y escribe jobs/<slug>/avatar/clip.timing.json (TimingSchema, sceneId: "avatar"). El placeholder de Kokoro ya escribió este archivo, así que omite la transcripción cuando estés probando en seco.

Etapa 4 — Ensamblar el storyboard (gratuito)

Para el sistema visual V2 más rico — metraje B-roll de palabras clave, grandes tarjetas de título, revelaciones con efecto papel y los llamativos pops de palabras en 3D ad-3d bold — lee references/v2-assets-layer.md y construye con scripts/build-v2-storyboard.ts (mapea los ritmos a los tipos V2 y obtiene metraje B-roll mediante scripts/media.ts). V2 es aditivo: los storyboards que usan solo tipos V1 se renderizan sin cambios.

1. Vuelve a leer references/layout-library.md. Escribe jobs/<slug>/ad-storyboard.json que coincida con AvatarAdSchema: segmentos de layout ordenados sobre la línea de tiempo del avatar más el array captions.
2. Arco típico: avatarFull (gancho) → split (demostración: captura + palabra clave) → split (prueba) → outro (tarjeta CTA limpia). Los segmentos deben ser ascendentes y no superponerse; el toMs del último segmento debe aterrizar aproximadamente en la duración del clip.
3. Redacta subtítulos de palabras clave por frase a partir de las marcas de tiempo startMs de las palabras en clip.timing.json: frases de 1 a 4 palabras, una palabra acentuada cada una, sin superposición, sin guiones largos. No inventes atMs — léelo del archivo de temporización. Los subtítulos se superponen en todos los segmentos.

Etapa 5 — Composición (vista previa, luego final)

npx tsx scripts/ad-compose.ts <job>           # vista previa rápida a media escala, sin música
npx tsx scripts/ad-compose.ts <job> --final   # renderizado completo + música atenuada + variante limpia + SRT

--final renderiza a 1080×1920, multiplexa la banda musical (music.gain ≈ 0.2, ducking por sidechain a music.duckRatio, loudnorm I=-14:TP=-1) y emite:

• jobs/<slug>/render/ad-captioned.mp4 — subtítulos quemados
• jobs/<slug>/render/ad-clean.mp4 — sin subtítulos (archivo SRT adjunto), música al mismo nivel
• jobs/<slug>/render/ad-captions.srt

Itera libremente aquí: editar el storyboard, los subtítulos o la música y volver a ejecutar la composición cuesta $0.

Etapa 6 — Entrega y verificación

Ejecuta las comprobaciones de aceptación antes de informar:

ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 jobs/<job>/render/ad-captioned.mp4   # 1080,1920
ffmpeg -i jobs/<job>/render/ad-captioned.mp4 -af volumedetect -f null - 2>&1 | grep mean_volume                          # no silencioso
grep -P "[\x{2013}\x{2014}]" jobs/<job>/render/ad-captions.srt && echo "GUION LARGO ENCONTRADO (FALLO)" || echo "sin guión largo OK"

Extrae algunos fotogramas y revísalos: pantalla dividida presente, capturas de pantalla sin recortar el texto de los subtítulos, subtítulos alineados con el habla, outro limpio. Informa los dos MP4, el SRT, el clip de avatar en caché (para reutilizar) y el gasto total.

Archivos de referencia

• references/scriptwriting-methodology.md — la referencia autorizada sobre DR / PAS / AIDA / gancho / CTA.
• references/ad-script-playbook.md — el flujo anti-chatarrería de seis pasos + reglas estrictas + la prohibición del guión largo.
• references/script-quality-checklist.md — la barrera humana ("¿el creador diría esto en voz alta?").
• references/layout-library.md — la gramática de segmentos de mezcla dinámica + zonas seguras verticales.
• references/v2-assets-layer.md — los tipos de enriquecimiento V2 (metraje B-roll, tarjetas de título, efectos de papel, pops de palabras en 3D), las reglas de edición aprendidas, la dirección de énfasis de gráficos en movimiento (píldoras/sellos/outro) y el vocabulario de efectos GSAP.
• references/zooq-video-runbook.md — para videos de ZOOQ, comienza aquí. El flujo de extremo a extremo reforzado con cada decisión bloqueada: andamio (npx tsx scripts/new-zooq-job.ts <slug>) → guion + BARRERA 1 → renderizado de pago de Terry → base de Remotion con metraje B-roll de escenas de marca (assets/zooq/manifest.json) → superposición de HyperFrames + efectos GSAP → revisión + entrega.
• references/heygen-cli.md — comandos exactos de creación/consulta/descarga/solo lectura de HeyGen.
• references/cost-gate.md — la regla de costo estricta, la fórmula de estimación, la comprobación de saldo.