MikeFishbeinAtherial/infinite-headcount

Auto-Loom

Convierte cualquier aplicación web en un MP4 narrado y autoguiado. La página se desplaza, resalta elementos y navega entre rutas mientras una voz de IA narra, sincronizada al milisegundo. Sin grabación manual de pantalla, sin tomas torpes de Loom. Edita una línea de narración y vuelve a renderizar en minutos.

Cómo funciona: ElevenLabs genera un clip de audio por cada 'beat' del guion gráfico. ffprobe mide la duración exacta de cada clip. Playwright conduce el navegador durante ese tiempo exacto por cada beat mientras graba la ventana. ffmpeg multiplexa el MP4 final con una pista de subtítulos. La duración del audio es la referencia principal: los visuales se ajustan a ella, por lo que la sincronización es exacta.

Esta carpeta contiene todo el motor. Las habilidades hermanas son puntos de entrada simplificados sobre estos mismos scripts:

• auto-loom-proof — Video de prueba de Software Factory: realiza los criterios de aceptación de una compilación frente a la cámara, un criterio por beat

Este SKILL.md cubre el motor más el modo desarrollador: tienes el código fuente, la aplicación se ejecuta en localhost y puedes añadir selectores estables al JSX.

---

Configuración (una vez, ~3 minutos)

cd <carpeta-de-esta-habilidad>
bash scripts/setup.sh        # instala Playwright + Chromium, crea .env.local
# edita .env.local → agrega tu clave API de ElevenLabs
node scripts/doctor.mjs      # verifica node, ffmpeg, playwright, clave, voz

¿Aún no tienes cuenta de ElevenLabs? Regístrate con el enlace de referencia del mantenedor: https://try.elevenlabs.io/atherial.

doctor.mjs muestra la corrección exacta para cualquier cosa que falte. Requisitos: Node 18+, ffmpeg (brew install ffmpeg), una clave API de ElevenLabs. Opciones de voz: references/voices.md.

Prueba de humo (30 segundos, graba example.com):

node scripts/run.mjs --beats examples/smoke-beats.json

---

Paso 0 — Entrevista primero al usuario

No empieces a construir. Pregunta:

1. ¿Qué URL o aplicación estamos grabando? ¿Se ejecuta localmente?
2. ¿Quién es el destinatario? Nombre y contexto.
3. ¿Cuál es la historia? ¿Qué cambió o qué estamos mostrando por primera vez?
4. ¿Qué características, métricas o secciones específicas debemos resaltar?
5. ¿Cuál es el tono? (actualización para cliente, demo interna, presentación para prospecto)
6. ¿La aplicación requiere inicio de sesión? (ver references/auth.md — nunca pidas contraseñas en el chat)
7. Duración objetivo: ¿30 s, 60 s o 75 s?

Si tienes prisa: pregunta 1 a 3 y deduce el resto de la aplicación.

Paso 1 — Escribe el guion gráfico (beats.json)

Escribe la narración antes de tocar cualquier código y consigue que sea aprobada textualmente. Reglas del guion y estructura de beats que funciona: references/tts-rules.md.

{
  "meta": {
    "title": "Recorrido por el panel de Acme",
    "slug": "recorrido-acme",
    "cta": "Envíame tus comentarios y pasamos a la siguiente fase.",
    "targetLengthSec": 70
  },
  "baseUrl": "http://localhost:3000",
  "viewport": { "width": 1920, "height": 1080 },
  "beats": [
    {
      "id": 1,
      "page": "/dashboard/insights",
      "text": "Hola Jim. Hemos lanzado algunas actualizaciones a tu rastreador de visibilidad de I-A.",
      "actions": [
        { "fn": "waitFor",    "sel": "[data-vn=fila-kpi]" },
        { "fn": "scrollToEl", "sel": "[data-vn=fila-kpi]", "opts": { "instant": true } },
        { "fn": "hl",         "sel": "[data-vn=fila-kpi]" }
      ]
    }
  ]
}

Esquema completo: schema/beats.schema.json. Tabla de acciones y guía de selectores: references/actions.md. Opciones de inicio de sesión (pasos escritos o sesión guardada): references/auth.md.

Verifica antes de gastar algo:

node scripts/validate.mjs --beats <archivo>       # estructura + TTS + lint de ritmo
node scripts/run.mjs --beats <archivo> --script-only   # imprime la narración y se detiene

El validador detecta acciones desconocidas, selectores faltantes, problemas de TTS (guiones largos, siglas sin desarrollar, frases muy largas) y ritmo que no se ajusta a la duración esperada.

--script-only es la puerta de revisión que ahorra dinero: imprime la narración de cada beat con estimaciones de tiempo por beat y sale antes de cualquier llamada a ElevenLabs o grabación. Obtén la aprobación del guion aquí, luego vuelve a ejecutar sin la bandera para gastar créditos.

Paso 2 — Instrumenta la página (modo desarrollador)

Playwright necesita selectores estables. Con acceso al código fuente, agrega atributos data-vn al JSX del componente:

<div data-vn="fila-kpi" className="grid grid-cols-4 gap-4">
<Card data-vn="grafico-competencia" ...>

Luego haz referencia a ellos: { "fn": "hl", "sel": "[data-vn=fila-kpi]" }.

Suprime las interacciones desplegables mientras grabas. Las tarjetas cliqueables con role="button" / tabIndex={0} pueden recibir enfoque automático durante los resaltados y abrir un cajón a mitad del video. Ciérralas con tu bandera de modo demo: {!isDemoMode() && <MetricBreakdownSheet ... />}.

Si la aplicación requiere autenticación en local, configura un modo demo (salta la autenticación, datos de prueba que coincidan exactamente con los números de la narración) o usa una ruta de autenticación de references/auth.md.

Nota sobre CSP: el grabador inicia Chromium con bypassCSP: true para poder inyectar presenter.js en páginas con CSP estricta. Si lo apuntas a una aplicación en producción con una sesión activa, ten en cuenta que la Política de Seguridad de Contenido está deshabilitada dentro de ese contexto de navegador automatizado.

Paso 3 — Un solo comando

node scripts/run.mjs --beats <archivo>

Esto ejecuta: validar → audio (almacenado en caché por hash de texto) → vuelo previo (pase headless resolviendo cada selector antes de grabar cualquier cosa) → grabar → subtítulos → multiplexar → verificar. El resultado se guarda en demo-video-out/<slug>/:

• <slug>-demo.mp4 — video final (H.264/AAC, pista de subtítulos suave)
• <slug>-demo-contact-sheet.png — fotogramas de muestra para revisión visual
• qa/beat-NN.png — captura exacta en el punto de pausa de cada beat
• captions.srt, audio/, video/recording.webm

Todas las banderas: --script-only (imprime el guion de narración y sale antes de cualquier llamada a ElevenLabs o grabación — la puerta de revisión del Paso 1), --preflight-only (verifica selectores, no gasta nada), --skip-audio (cambios solo visuales — el audio se reutiliza), --skip-preflight (salta la verificación headless de selectores — solo si el vuelo previo acaba de pasar y nada cambió), --burn-captions (incrusta subtítulos en los píxeles para plataformas que eliminan pistas), --no-captions, --out <dir> y --env <archivoenv>.

Paso 4 — Verifica antes de enviar

run.mjs comprueba duración (MP4 = suma de audio dentro de 0.5 s), nivel de audio (detección de pista silenciosa) y guarda capturas de control de calidad. Aún así debes revisar visualmente:

• Hoja de contacto + qa/beat-NN.png: cada fotograma muestra lo que su beat narra — sin páginas de inicio de sesión, estados de error ni modales sorpresa.
• El primer beat nombra al destinatario; el último beat entrega el CTA textualmente.

Iteración

• Edición de narración → vuelve a ejecutar; solo se regenera el audio del beat modificado.
• Edición visual/de ritmo → --skip-audio.
• Selector roto → --preflight-only muestra exactamente qué beat y selector.

---

Problemas conocidos

• La recarga en caliente elimina el presentador inyectado. Ya está solucionado: el presentador se reinyecta antes de cada beat. Pero evita editar la aplicación mientras se graba.
• Deriva de puerto. yarn dev toma el puerto 3001 si el 3000 está ocupado — actualiza baseUrl.
• Voces gratuitas vs. de pago. Las voces clonadas/de biblioteca lanzan payment_required en el plan gratuito. doctor.mjs lo detecta antes del renderizado.
• Redirecciones i18n. /en/dashboard → /dashboard las redirecciones se siguen correctamente; los beats en la misma página no vuelven a navegar.
• Entrega. El MP4 es autónomo: correo electrónico, Slack, DM de LinkedIn, inserción en Notion o importación a Descript para una introducción personal al inicio.