mkt-full-video-with-11-hyperframe-heygen

¿Qué hace mkt-full-video-with-11-hyperframe-heygen?

Orquestador de extremo a extremo: script → video final TikTok/Reels MP4 9:16.

El pipeline tiene 2 puntos de control de usuario:

1. Punto de control de MP3 (orquestador) — después de la Fase 1, el usuario revisa la locución.
2. Punto de control de esquema de escenas (subagente de la Fase 3) — el usuario revisa la estructura de escenas + variante antes de que los escritores de contenido se desplieguen. Se puede omitir si el usuario pasa auto_scenes=true.

Cuándo usar

• El usuario tiene un guion en Vietnamita/Inglés de ≤ 5000 caracteres y quiere un video de TikTok completo.
• Tiene imágenes o videos de respaldo (b-roll) opcionales con un propósito definido.
• Quiere ir directamente del guion a la vista previa en Studio.

No uses esta habilidad si:

• El usuario ya tiene un MP3 listo → usa directamente heygen-mp3-to-mp4.
• El usuario ya tiene un MP4 de avatar parlante listo → usa directamente mkt-hyperframe-talking-head-video.
• El usuario necesita que HeyGen lea el texto directamente (sin pasar por ElevenLabs) → usa heygen-script-to-mp4.
• El guion tiene más de 5000 caracteres → divídelo semánticamente y ejecuta el pipeline para cada segmento.

Resumen del pipeline

Script (texto + b-roll opcional + tts_provider)
    │
    ▼
Fase 1 ── TTS (elevenlabs | minimax) ──► voiceover.mp3
    │                                         │
    │                                         ▼
    │                              PUNTO DE CONTROL #1 — el usuario escucha y aprueba el MP3
    │                                         │
    │                                         ▼ (OK)
Fase 2 ── heygen-mp3-to-mp4 ──────────► source.mp4 (9:16 sincronización de labios)
    │
    ▼
Fase 3 ── generar agente mkt-full-video-phase3-packager (contexto aislado)
            │
            ├─ transcribir + limpiar + agrupar subtítulos
            ├─ detectar límites de escenas + clasificar variante de maqueta
            ├─ PUNTO DE CONTROL #2 — el usuario revisa el esquema de escenas
            ├─ DESPLIEGUE de N subagentes de propósito general (1 por escena) en paralelo
            │   → cada subagente construye un JSON de contenido según el esquema de la variante
            ├─ fusionar → scenes.json
            ├─ en paralelo: anda subcomponentes + copiar SFX + inyectar subtítulos
            ├─ generar index.html raíz
            └─ lint + vista previa Studio
    │
    ▼
El usuario revisa la vista previa → "render" → MP4 final

Regla de puntos de control: El orquestador gestiona el punto de control #1 (MP3). Las fases 2 y 3 se ejecutan automáticamente. El punto de control #2 (esquema de escenas) es gestionado por el subagente de la Fase 3. La puerta de renderizado final está en Studio.

Entradas

Entrada	Requerida	Formato / ejemplo
Texto del guion	Sí	Ruta de archivo (.txt/.md) o cadena de texto en línea. ≤ 5000 caracteres.
Proyecto slug	No	Se deriva automáticamente de las primeras 5 palabras del guion. Minúsculas, ASCII, guiones.
Lista de b-roll	No	Array [{path: "...", purpose: "Lección 1 — ilustración X"}, ...].
tts_provider	No	elevenlabs (predeterminado — voz de Hoàng, expresiva) o minimax (speech-2.8-hd, más barato, lectura en vietnamita natural). El usuario dice "usa minimax" / "usa eleven" → se establece según eso.
Anulación de ID de voz	No	Anula el valor predeterminado de .env. ElevenLabs lee ELEVENLABS_VOICE_ID, MiniMax lee MINIMAX_VOICE_ID. Bandera CLI --voice_id para ambos.
Anulación de configuración de voz	No	ElevenLabs: {stability, similarity_boost, style}. MiniMax: {speed, vol, pitch}.
Apariencia del avatar	No	1 ID tomado de la variable de entorno HEYGEN_AVATAR_LOOKS (.env, separado por comas). Aleatorio si no se selecciona.
auto_scenes	No	Predeterminado false. true para omitir el punto de control del esquema de escenas en la Fase 3.

Estructura del espacio de trabajo

workspace/content/YYYY-MM-DD/<slug>/
├── script.txt              # Fase 0
├── voiceover.mp3           # Fase 1
├── source.mp4              # Fase 2
├── broll/                  # B-roll proporcionado por el usuario (copia)
├── transcript.json         # Fase 3
├── caption-groups.json     # Fase 3
├── scenes-outline.json     # Fase 3 — esquema previo al punto de control
├── scenes/                 # Fase 3 — el contenido por escena se escribe aquí
│   ├── scene-1.json
│   └── ...
├── scenes.json             # Fase 3 — fusionado final
├── compositions/           # Fase 3 — subcomponentes HF
├── sfx/                    # Fase 3 — 6 efectos de sonido
└── index.html              # Fase 3 — composición raíz

YYYY-MM-DD = hoy (UTC+7).

Flujo de trabajo

Paso 0 — Configuración

1. Validar len(script_text) <= 5000. Si excede → detenerse, solicitar al usuario que divida semánticamente.
2. Derivar slug si falta: primeras 5 palabras → minúsculas → quitar tildes → espacios a guiones.
3. Resolver proveedor de TTS — leer tts_provider de la entrada del usuario (predeterminado elevenlabs). Si el usuario dice "usa minimax" / "cambiar a minimax" → minimax. Si el usuario dice "usa eleven" / "elevenlabs" → elevenlabs. Validar que la clave de API correspondiente exista en .env:
   • elevenlabs → necesita ELEVENLABS_API_KEY (ELEVENLABS_VOICE_ID opcional para anular el predeterminado K7ewtjKRNtwwt3lKQ6M0).
   • minimax → necesita MINIMAX_API_KEY (MINIMAX_VOICE_ID opcional para anular el predeterminado moss_audio_c56d6120-ef9c-11f0-9649-8ee40147f116). Si falta la clave → detenerse, informar al usuario que la agregue a .env.
4. Crear workspace/content/YYYY-MM-DD/<slug>/. Guardar script.txt.
5. Si el usuario tiene b-roll: crear <folder>/broll/, copiar los archivos manteniendo el nombre original.
6. Informar al usuario: "Espacio de trabajo creado en <folder>. Proveedor de TTS: <elevenlabs|minimax>. Comenzando Fase 1."

Paso 1 — Fase 1: Script → MP3 (TTS)

Ejecutar exactamente 1 de las 2 ramas según tts_provider:

Rama A — ElevenLabs (predeterminado):

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

ID de voz: lee automáticamente ELEVENLABS_VOICE_ID de .env (fallback a la voz de marca predeterminada de Hoàng). Anulación CLI: --voice_id <id>. Configuración de voz: añadir --stability / --similarity_boost / --style si el usuario solicita ajustes.

Rama B — MiniMax:

uv run .claude/skills/mkt-video-script-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

ID de voz: lee automáticamente MINIMAX_VOICE_ID de .env (fallback a moss_audio_...). Anulación CLI: --voice_id <id>. Configuración de voz: --speed (predeterminado 1.08), --vol, --pitch, --language_boost Vietnamese.

El nombre del archivo de salida es inviolable en ambas ramas: voiceover.mp3 para que la Fase 2 (HeyGen) encuentre la ruta correcta.

Después de terminar, verificar la duración (común para ambos proveedores):

uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py \
  workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

TOO_LONG → detenerse, informar al usuario que el MP3 supera los 5 minutos de HeyGen, solicitar que acorte el guion.

Paso 2 — PUNTO DE CONTROL #1: el usuario escucha el MP3

Único punto de parada gestionado por el orquestador. Informar al usuario con el formato exacto:

## Locución lista — revísala

**Archivo:** `workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3`
**Duración:** <X.X>s
**Tamaño:** <Y.Y> MB
**Proveedor:** `<`elevenlabs` | `minimax`>`
**Voz:** `<`ElevenLabs Brand Voice de Hoàng (K7ewtjKRNtwwt3lKQ6M0)`> o `<`MiniMax speech-2.8-hd (moss_audio_...)`> (tomado del ID de voz en `.env` si el usuario lo anuló)

Abre el archivo y escúchalo. Responde 1 de:
- **`OK`** / **`continuar`** → ejecuto la Fase 2 (avatar HeyGen sincronización de labios)
- **`regen`** + (opcional) motivo → ajusto la configuración de voz y regenero el MP3
- **`editar guion`** + nuevo contenido → guardo el nuevo guion y vuelvo a ejecutar la Fase 1

Detener las llamadas a herramientas. Esperar una respuesta clara del usuario.

Cuando el usuario diga OK → Fase 2. Cuando el usuario diga regen → volver a ejecutar el script de TTS del proveedor actual con la nueva configuración, volver al punto de control. Si el usuario dice "cambiar a minimax" / "probar eleven" → intercambiar tts_provider, volver a ejecutar la Fase 1. Cuando el usuario edite el guion → sobrescribir script.txt, volver a ejecutar la Fase 1 desde el principio (mismo proveedor).

Paso 3 — Fase 2: MP3 → MP4 HeyGen (automático)

Según la sub-habilidad heygen-mp3-to-mp4:

1. Elegir ID de avatar — leer HEYGEN_AVATAR_LOOKS de .env (separado por comas), elegir aleatoriamente si el usuario no lo especifica:

   HEYGEN_AVATAR_LOOKS=$(grep '^HEYGEN_AVATAR_LOOKS=' .env | cut -d'=' -f2- | tr -d '"' | tr -d "'")
   echo "$HEYGEN_AVATAR_LOOKS" | tr ',' '\n' | awk 'BEGIN{srand()} {a[NR]=$0} END{print a[int(rand()*NR)+1]}'
   

   Si la variable de entorno falta/está vacía → detenerse e informar al usuario que agregue HEYGEN_AVATAR_LOOKS=<id1>,<id2> a .env. Informar al usuario de la selección antes de llamar al MCP.

2. Subir MP3 a HeyGen a través de MCP (upload_asset, asset type audio). NO usar curl https://upload.heygen.com/....

3. Crear video de avatar a través de MCP (generate_avatar_video):

   character: { type: avatar, avatar_id: <elegido>, scale: 1.0 }
   voice:     { type: audio, audio_asset_id: <de la subida> }
   dimension: { width: 720, height: 1280 }   # 9:16
   title:     "<slug>-<timestamp>"
   

4. Consultar estado cada ~10s → completed (máx. 10 min). failed → detenerse, mostrar error.

5. Descargar MP4 → workspace/content/YYYY-MM-DD/<slug>/source.mp4 (nombre de archivo inviolable):

   uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py \
     "<video_url>" "workspace/content/YYYY-MM-DD/<slug>/source.mp4"
   

6. Informar al usuario en una línea: "Fase 2 completada — <path> (avatar <id>, s, MB). Generando empaquetador de la Fase 3…"

No detenerse aquí. Flujo automático a la Fase 3.

Paso 4 — Fase 3: Generar subagente empaquetador

Usar la herramienta Task con subagent_type: "mkt-full-video-phase3-packager". Pasar un mensaje autocontenido con las entradas que el agente necesita. Ejemplo:

Workspace: workspace/content/2026-05-03/hom-nay-minh-chia-se/
Slug: hom-nay-minh-chia-se
Script: <texto completo del guion>
B-roll: [
  {"path": "workspace/content/2026-05-03/hom-nay-minh-chia-se/broll/alphabet.png", "purpose": "Lección 1"},
  ...
]
auto_scenes: false
header_label: "3 LECCIONES IA"
footer_handle: "@tranvanhoang.com"

Ejecuta el pipeline completo de empaquetado de la Fase 3 según la definición de tu agente. Devuelve la URL de Studio cuando la vista previa esté abierta.

El subagente:

• Transcribe source.mp4, construye el esquema de escenas
• Se detiene para pedir al usuario que apruebe el esquema (PUNTO DE CONTROL #2) a menos que auto_scenes: true
• Despliega N escritores de contenido de escenas en paralelo
• Fusiona + anda + lint + abre vista previa
• Devuelve la URL de Studio

Mientras el subagente se ejecuta, el único trabajo del orquestador es reenviar las respuestas del usuario al subagente (la respuesta del usuario en el punto de control del esquema de escenas llegará a esta conversación; enrutarla al subagente si todavía está activo, de lo contrario, tratarla como una instrucción de seguimiento).

Paso 5 — Transferencia

Cuando el subagente devuelva la URL de Studio, formatear el informe final:

## Pipeline de video completo COMPLETADO — vista previa lista

**Espacio de trabajo:** `workspace/content/YYYY-MM-DD/<slug>/`

**Fase 1 (`<elevenlabs|minimax>`):** voiceover.mp3 — <D1>s, <S1>MB (ID de voz `<id>`)
**Fase 2 (HeyGen):** source.mp4 — avatar `<avatar_id>`, <D2>s, <S2>MB
**Fase 3 (HyperFrames):** <N> escenas (<lista de variantes>), <K> grupos de subtítulos, 6 SFX

**URL de Studio:** http://localhost:3002

Abre el navegador y revisa la línea de tiempo. Di **`render`** cuando esté bien → ejecuto `npx hyperframes render` para exportar MP4 1080×1920 30fps.

Detenerse aquí. No auto-renderizar. Solo después de que el usuario confirme, llamar a npx hyperframes render.

Reglas críticas de orquestación

1. 2 puntos de control de usuario, 1 puerta de orquestador — El orquestador solo se detiene en el MP3 (Paso 2). El punto de control del esquema de escenas es gestionado por el subagente de la Fase 3. La puerta de renderizado en Studio la gestiona el usuario.

2. Convenciones de ruta inviolables — la locución debe ser voiceover.mp3, el video de avatar parlante debe ser source.mp4. La sub-habilidad HF espera el nombre source.mp4.

3. HeyGen MCP solamente — nunca usar curl https://api.heygen.com/.... Restricción estricta de heygen-mp3-to-mp4.

4. ID de voz guardado en .env, no hardcodeado en la habilidad. ElevenLabs lee ELEVENLABS_VOICE_ID (fallback K7ewtjKRNtwwt3lKQ6M0). MiniMax lee MINIMAX_VOICE_ID (fallback moss_audio_...). Anulación por llamada mediante --voice_id. El pipeline informa claramente el proveedor + ID de voz elegido en el Paso 0 y el punto de control #1.

5. Límite estricto de longitud del guion de 5000 caracteres — fallar rápidamente en el Paso 0.1.

6. Duración del MP3 ≤ 300s — límite de video único de HeyGen. Verificar inmediatamente después de la Fase 1.

7. Primero la vista previa — La Fase 3 NO auto-renderiza. Memoria feedback_hyperframes_workflow.md.

8. Aislamiento de la Fase 3 — La Fase 3 se ejecuta en un contexto de subagente separado. El cuerpo de la habilidad HF + 4 documentos de referencia (~40KB) se cargan en el subagente en lugar del orquestador principal.

Modos de fallo y alternativas

Síntoma	Acción
Guion > 5000 caracteres	Detenerse, solicitar al usuario que divida semánticamente
Fallo de API de ElevenLabs	Informar del error, sugerir verificar ELEVENLABS_API_KEY en .env (ELEVENLABS_VOICE_ID opcional). O cambiar a tts_provider=minimax y volver a ejecutar la Fase 1
Fallo de API de MiniMax	Informar del error, sugerir verificar MINIMAX_API_KEY en .env (MINIMAX_VOICE_ID opcional). O cambiar a tts_provider=elevenlabs y volver a ejecutar la Fase 1
MP3 > 300s después de la Fase 1	Detener el pipeline, sugerir heygen-short-video (fragmentación)
MCP de HeyGen no conectado	Detenerse, informar claude mcp list para verificar
Error de renderizado de HeyGen	Mostrar error, sugerir verificar créditos mediante mcp__heygen__get_current_user
Fallo del subagente de la Fase 3	Leer el seguimiento del error, sugerir al usuario que vuelva a ejecutar la Fase 3 de forma independiente usando la habilidad mkt-hyperframe-talking-head-video
El escritor de escenas devuelve JSON mal formado	El subagente se regenera automáticamente para esa escena (no es responsabilidad del orquestador)
El usuario rechaza la voz del MP3	Volver a la Fase 1 con ajustes de configuración de voz

Ejemplo de extremo a extremo

Usuario:

Tengo el guion aquí, ejecuta el pipeline completo para un video de TikTok. Incluye 2 imágenes de b-roll para la lección 1 y la lección 2. Guion: "Hoy comparto 3 lecciones de Anthropic. La primera lección es Alphabet ship beta. La segunda lección es 24h…" B-roll: alphabet.png (lección 1), clock.png (lección 2)

Pipeline:

1. Paso 0 — slug hom-nay-minh-chia-se. Carpeta workspace/content/2026-05-03/hom-nay-minh-chia-se/. Guardar script.txt, copiar b-roll.
2. Paso 1 — text_to_mp3.py → voiceover.mp3 (45s, 0.7MB).
3. Paso 2 — PUNTO DE CONTROL #1 — informar al usuario de la ruta + duración. Esperar respuesta.
4. Usuario: OK.
5. Paso 3 — Elegir avatar (aleatorio de HEYGEN_AVATAR_LOOKS, por ejemplo 66e75e22…). Subir MP3 → asset_id. Generar video → consultar → descargar source.mp4 (45s, 7.5MB).
6. Paso 4 — Generar subagente mkt-full-video-phase3-packager.
7. El subagente transcribe (35s), construye el esquema (3 lecciones + resumen + cta), muestra el esquema → PUNTO DE CONTROL #2.
8. Usuario: OK.
9. El subagente despliega 5 escritores de escenas en paralelo (~8s de tiempo real vs ~40s en serie).
10. El subagente fusiona → scenes.json → anda + SFX + subtítulos en paralelo.
11. El subagente abre Studio y devuelve la URL.
12. Paso 5 — El orquestador muestra el informe final. El usuario dice "render" → el orquestador ejecuta npx hyperframes render.

Notas de implementación

• Los scripts de TTS de ElevenLabs y MiniMax son habilidades independientes invocadas desde el orquestador.
• La sub-habilidad heygen-mp3-to-mp4 se usa para la Fase 2.
• La Fase 3 se ejecuta en un contexto de subagente aislado para mantener la modularidad.
• Los nombres de archivo voiceover.mp3 y source.mp4 son inviolables y esperados por los componentes posteriores del pipeline.