synctake

Habilidad SyncTake para Agentes de Codificación

Esta habilidad instruye a agentes de codificación (Claude Code, Cursor, Antigravity, OpenCode, Codex) sobre cómo producir de forma autónoma videos narrados y pulidos de recorrido por aplicaciones web.

---

🎯 Cuándo Activar Esta Habilidad

Activa este flujo de trabajo siempre que el usuario solicite:

• "Crear un video de demostración / recorrido de este proyecto / funcionalidad"
• "Grabar un video que muestre cómo funciona la aplicación"
• "Haz un video de recorrido de 30s/60s de esta nueva interfaz"
• "Muestra esta funcionalidad en video con narración"

---

🛠️ Paso 0: Verificación del Entorno y Dependencias

Antes de ejecutar el flujo de trabajo, verifica que las herramientas necesarias estén instaladas:

1. Verificar CLI de SyncTake:

   synctake --help || pip install -e /ruta/a/synctake
   

2. Verificar Playwright (para captura headless autónoma):

   python -c "import playwright" 2>/dev/null || (pip install playwright && playwright install chromium)
   

---

📋 El Manual de 5 Pasos para el Agente Autónomo

[1. Inspeccionar UI] ──> [2. Crear synctake.json] ──> [3. Iniciar Servidor Dev] ──> [4. Ejecutar Pipeline Autónomo] ──> [5. Entregar Video]

Paso 1: Inspeccionar el Código Base y los Puntos de Referencia de la UI

1. Busca en el espacio de trabajo rutas, componentes y vistas HTML (ej. src/, pages/, app/, public/index.html).
2. Identifica los puntos de referencia visuales clave para el video:
   • Encabezado, navegación, hero (#hero, header, .brand)
   • Componentes interactivos, formularios, botones (#deploy-btn, button[type='submit'], select)
   • Tarjetas, métricas, gráficos ([data-testid='metrics'], .card, .recommendation-grid)
3. Alternativamente, ejecuta el inspector de UI incorporado:

   synctake plan ./public/index.html --prompt "<guía del usuario>" --duration <segundos>
   

---

Paso 2: Crear la Especificación del Recorrido (synctake.json)

Crea synctake.json en la raíz del proyecto.

Reglas de Ritmo y Guion:

• Palabras Por Minuto: Apunta a 140–150 PPM (~2.4 palabras por segundo). Una escena de 10 segundos debe contener aproximadamente 20–24 palabras.
• Marcas de Tiempo de Escena (at): Deben ser estrictamente crecientes.
• Llamada en Pantalla: Mantén title y callout cortos y contundentes (aparecen como tarjetas flotantes nativas).
• Foco: Usa selectores CSS reales y válidos (#id, .class, [data-testid='...']).
• Narración: Escribe un discurso natural y conversacional. Nunca leas en voz alta símbolos de código, selectores o marcas de tiempo.

{
  "title": "Recorrido de Funcionalidad",
  "duration_seconds": 30.0,
  "voice": {
    "provider": "system"
  },
  "scenes": [
    {
      "id": "01-vista-general",
      "at": 0.0,
      "title": "Vista General del Clúster en Vivo",
      "callout": "Métricas de salud y telemetría en tiempo real entre regiones",
      "focus": "#metrics-card",
      "text": "¡Bienvenido! En este recorrido exploraremos la salud del clúster en tiempo real y la remediación automatizada."
    },
    {
      "id": "02-acciones",
      "at": 12.0,
      "title": "Despliegues con un Solo Clic",
      "callout": "Validación automatizada con aprobación humana",
      "focus": "#deploy-btn",
      "text": "Con un solo clic, nuestra canalización valida los cambios de configuración y aplica actualizaciones progresivas."
    }
  ]
}

---

Paso 3: Asegurarse de que el Servidor de Desarrollo Esté en Ejecución

Verifica si el servidor de desarrollo de la aplicación web ya está escuchando en un puerto local:

lsof -i :3000 -i :5173 -i :8000 || true

Si no está ejecutándose, inícialo en segundo plano:

• Para HTML estático: python3 -m http.server 5173 --bind 127.0.0.1
• Para Vite: npm run dev
• Para Next.js: npm run dev

---

Paso 4: Ejecutar el Pipeline Autónomo

Ejecuta el comando de ejecución autónoma todo en uno:

synctake run \
  --url http://127.0.0.1:5173 \
  --config ./synctake.json \
  --out ./demo.mp4

Si el usuario proporcionó un clip de referencia de voz (ej. voice.wav), pasa --ref-audio ./voice.wav para clonar su voz.

Lo que hace synctake run automáticamente:

1. Captura de Pantalla Headless: Inicia Chromium mediante Playwright, recorre las señales de las escenas, resalta elementos con anillos de enfoque adaptativos al host, muestra insignias de llamadas nativas y guarda WebM calibrado.
2. Síntesis de Voz: Sintetiza inglés hablado claro (o clona la voz del usuario).
3. Validación de Ritmo y Ranuras: Verifica que ningún clip de audio exceda la duración de escena asignada.
4. Ensamblaje del Lienzo Maestro: Coloca los clips en las señales exactas, llena las pausas con silencio digital y genera audio estéreo calibrado a 48 kHz.
5. Multiplexado sin Pérdidas: Normaliza el audio al estándar de transmisión (-16 LUFS) y multiplexa en MP4 H.264 1080p con cero pérdida de video generacional.

---

Paso 5: Entregar el Video Terminado

Una vez que synctake run se complete:

1. Verifica que el video de salida exista y no esté vacío (ls -lh ./demo.mp4).
2. Presenta el video terminado al usuario con su enlace de ruta de archivo absoluta:

   "¡Aquí tienes tu video de recorrido completo: demo.mp4!"