clip-builder

Clip builder

Construye un video corto a partir de tres partes: una página HTML que renderiza la imagen (la escena), una lista de líneas de guion en clip.json (las pistas), y una herramienta de línea de comandos que captura la página fotograma a fotograma y codifica un MP4.

La página de la escena define draw(s), que establece el estado de la página en el segundo s, calculado a partir de s únicamente. La captura la llama para cada fotograma (segundo 0, luego 1/30, y así sucesivamente) y toma una captura de pantalla. Como resultado, la salida no depende de la velocidad de la máquina, cualquier fotograma puede renderizarse por separado para su revisión, y un cambio en una parte del clip puede volver a capturarse con --from y --to.

El CLI es scripts/clip.mjs en el directorio de esta habilidad. En este documento clip significa node "<directorio de la habilidad>/scripts/clip.mjs", donde <directorio de la habilidad> es la ruta absoluta del directorio que contiene este archivo. (Claude Code sustituye esa ruta aquí: ${CLAUDE_SKILL_DIR}. En otros agentes, usa el directorio desde el que se leyó este archivo). Ejecuta los comandos desde el directorio del proyecto del clip, que contiene clip.json. clip help lista todos los comandos y opciones.

Requisitos

Node 20 o posterior, ffmpeg y Playwright con Chromium. clip doctor los verifica e imprime comandos de instalación para lo que falte. Instala Playwright en el directorio donde se construyen los clips (npm install --save-dev playwright, luego npx playwright install chromium), no en el directorio de esta habilidad. La narración y la música generada son opcionales. Son los únicos pasos que cuestan dinero o necesitan una clave API.

Comandos en espacio aislado (el predeterminado en Codex): clip stills, clip capture y clip serve inician un servidor HTTP en 127.0.0.1, y los dos primeros también inician Chromium. Un espacio aislado de comandos bloquea ambos. El comando entonces termina con el estado 1 y un mensaje que nombra el espacio aislado. Solicita aprobación para ejecutar estos tres comandos fuera del espacio aislado, y expón el motivo. No sustituyas otro método de captura. Los demás comandos no necesitan ni servidor ni navegador y se ejecutan dentro del espacio aislado; tts --generate y music --generate también necesitan acceso a la red.

Resumen

Establece lo siguiente antes de comenzar. Pregunta solo por lo que falte. Para cualquier cosa que el usuario no haya especificado, usa el valor predeterminado e indícalo en una línea.

• Propósito y audiencia: promoción, demostración de producto, manual para el personal, lección. Esto define el ritmo. Los clips promocionales avanzan rápido; los clips de formación dejan tiempo para seguir cada paso.
• Duración. Valor predeterminado: 20 a 45 segundos para una promoción o demo, 60 a 120 para formación.
• Destino, que determina los fotogramas. Valor predeterminado: wide 1920×1080, más tall 1080×1350 para redes sociales. Consulta references/delivery.md.
• Enfoque visual: gráficos nuevos o una pantalla de app. Para una app: qué pantallas, y si su código fuente o sistema de diseño está disponible como fuente para colores, tipografía y espaciado.
• Sonido. Valor predeterminado: silencioso con subtítulos. Esto es gratuito, y la mayoría de los videos en feeds se reproducen en silencio. La narración y la música son opcionales.
• Guion. Usa el guion del usuario si lo tiene. De lo contrario, redacta uno y obtén su aprobación antes de construir la escena.

Flujo de trabajo

1. Verifica las herramientas: clip doctor.
2. Crea el proyecto: clip init <dir> --template graphics o --template app-ui. Esto escribe clip.json, un directorio scene/ con un ejemplo funcional, y audio/. Ambas plantillas se renderizan sin cambios.
3. Escribe las pistas en clip.json, una por golpe. Un golpe es un segmento del clip con una línea y un estado visual. Escribe primero el guion: la escena se sincroniza con él, y cualquier cambio de redacción después de la grabación es otra solicitud de pago. references/narration.md cubre la escritura para voz.
4. Construye la escena: edita scene/index.html y scene/scene.js. Lee primero references/scenes.md. Enumera las restricciones que mantienen una escena determinista: sin Math.random(), sin relojes ni temporizadores, sin animaciones CSS, todo el estado calculado a partir de s. Para una pantalla de app, lee también references/app-ui.md.
5. Revisa los fotogramas fijos: clip stills escribe fotogramas en segundos seleccionados y una hoja de contacto en out/review/. Abre la hoja de contacto como imagen e inspecciónala. Verifica que el texto sea legible, que nada se superponga y que cada golpe esté en pantalla mientras se muestra su subtítulo. Repite para cada tamaño de fotograma (--frame tall). Haz la mayor parte de la iteración en este paso: los fotogramas fijos son rápidos y no cuestan nada. clip serve sirve una vista previa en vivo para el usuario.
6. Captura un borrador: clip capture --draft renderiza a dos tercios del tamaño para verificar movimiento y ritmo. Dale al usuario la ruta del archivo y pídele que lo vea.
7. Agrega sonido, si se solicita. Narración: references/narration.md. Música y la mezcla: references/sound.md. Ejecuta clip tts sin banderas primero; lista las solicitudes planificadas y los recuentos de caracteres. Obtén la aprobación del usuario, luego ejecuta clip tts --generate. Después de cualquier nueva grabación, ejecuta clip timing, que coloca las pistas y los subtítulos y, si está configurado, estira la escena a la narración. Luego revisa los fotogramas fijos nuevamente.
8. Captura la versión final: clip capture --final para cada fotograma, luego clip mix si hay sonido, luego clip web <archivo> para una copia más pequeña para subir.
9. Verifica e informa: revisa los fotogramas fijos de la versión final, lee el nivel de sonoridad en el informe de mezcla y ejecuta clip scan out. Informa lo que se produjo, las rutas de los archivos, lo que se verificó y lo que no.

Un clip silencioso omite el paso 7. Sus subtítulos provienen de los valores at y until de cada pista, y clip timing los escribe para la página.

Reglas de seguridad

Un trabajo de clip involucra el dinero del usuario, las claves API y la identidad publicada.

• Las solicitudes de pago requieren la aprobación explícita del usuario. El proveedor factura la narración y la música. El CLI no envía nada sin --generate; pasa esa bandera solo después de que el usuario apruebe esa toma específica. La aprobación de una toma no cubre la siguiente. Muestra la salida de prueba (líneas y recuentos de caracteres) al preguntar. Si una solicitud se interrumpe, su recibo permanece como attempted. No reintentes hasta que el usuario haya verificado el historial de uso del proveedor, porque la solicitud puede haber sido facturada.
• Las claves API provienen solo del entorno. El CLI lee ELEVENLABS_API_KEY o OPENAI_API_KEY y ninguna otra fuente. Pasa una clave en línea para un solo comando desde el almacén secreto del usuario (references/keys-and-paid-calls.md tiene los comandos). No le pidas al usuario que pegue una clave en la conversación, no imprimas una (echo, env, cat) y no escribas una en un archivo. Para confirmar que una clave está configurada, verifica su longitud; clip doctor hace esto.
• Entrega archivos; no publiques. Publicar o subir un clip es una acción del usuario a menos que solicite esa acción específica.
• Usa solo material que el usuario tenga derecho a usar. La música, las fuentes, los logotipos y el metraje necesitan una licencia o la propiedad del usuario. Muestra solo una app que el usuario posea o tenga permiso para mostrar, y no diseñes una maqueta como el producto de otra empresa. Los términos de ambos proveedores cubren el uso comercial y la divulgación de voces generadas; señálale al usuario antes de que se publique un clip narrado.
• Mantén los datos privados fuera de la imagen y los archivos. Usa nombres y números ficticios en las pantallas de la app. Las cifras y citas presentadas como reales deben ser reales, y los ejemplos deben ser identificables como ejemplos. Ejecuta clip scan en cualquier cosa antes de que se comparta. Verifica claves API, el nombre de usuario local y rutas, direcciones de correo electrónico, la lista de términos privados del usuario y metadatos incrustados en archivos multimedia.

Directrices editoriales

• Cubre un tema por clip. Divide un guion que cubra dos.
• Comienza la narración o el primer subtítulo dentro de los primeros segundos.
• Usa una pista por golpe, y mantén el visual de un golpe en pantalla mientras se dice su línea.
• Incluye siempre subtítulos. La mayoría de los videos en feeds se reproducen en silencio.
• Revisa los fotogramas verticales al tamaño de un teléfono. La unidad de la escena es más grande en los fotogramas verticales por esta razón.
• Usa movimiento para marcar un cambio de estado o para dirigir la atención. Evita el movimiento continuo.
• Mantén la tarjeta de cierre durante al menos 2,5 segundos.
• Para formación: muestra la acción, luego su resultado, a un ritmo que el espectador pueda seguir mientras la realiza. Numera los pasos en pantalla, y indica al principio qué podrá hacer el espectador.

Comandos

Comando	Función
clip doctor	Verifica Node, ffmpeg y Playwright, e informa qué claves están configuradas (solo longitud)
clip init <dir> --template graphics|app-ui	Crea un proyecto a partir de un ejemplo funcional
clip serve	Sirve una vista previa en vivo; ?t=5 en la URL mantiene en 5 s
clip stills [--at 2,5,9] [--frame tall] [--final]	Renderiza fotogramas fijos de revisión y una hoja de contacto
clip capture [--frame wide] [--draft] [--final] [--from s --to s] [--web]	Renderiza cada fotograma y codifica un MP4
clip capture --mode clock --url … --seconds N [--actions file.mjs]	Captura una app en ejecución (experimental; consulta references/app-ui.md)
clip tts [--generate]	Lista la narración aún por grabar; con --generate, la graba (de pago)
clip music [--generate]	Lo mismo para una banda sonora generada (de pago)
clip timing	Calcula los tiempos de pistas y subtítulos; escribe scene/timing.json y un .srt
clip mix	Construye la banda sonora con un nivel de sonoridad estándar y la multiplexa en cada video capturado
clip web <video>	Escribe una copia más pequeña para subir
clip scan <dir> [--terms-file words.txt]	Informa datos privados antes de compartir archivos
clip strip <archivo multimedia>	Escribe una copia con todos los metadatos incrustados eliminados

La salida va a out/, nombrada <nombre>-<toma>-<fotograma>.mp4, con los sufijos -draft, -part (un rango capturado con --from/--to), -sound y -web agregados según corresponda. Para mantener una versión anterior junto a una nueva, incrementa "take" en clip.json (a, b, c, …).

Archivos de referencia

Lee el archivo que necesite el paso actual.

Archivo	Léelo cuando
references/scenes.md	Escribas o cambies una escena: el contrato de la página, la biblioteca auxiliar, unidades, fotogramas verticales, fuentes y las restricciones que mantienen una captura determinista
references/app-ui.md	El clip muestre una pantalla de app: reconstruirla a partir de tokens de diseño, el puntero, la escritura, movimientos de cámara y capturar una app en ejecución
references/narration.md	Escribas líneas, elijas un proveedor y una voz, pronunciación, regrabar una línea, ajustar la escena a la narración, subtítulos
references/sound.md	Música y la mezcla: niveles, ducking, ajustar una pista al clip, sonoridad, corregir una mezcla
references/keys-and-paid-calls.md	Antes de cualquier solicitud de pago: pasar una clave de forma segura, qué se envía, recibos, solicitudes interrumpidas
references/project-file.md	Cualquier campo de clip.json
references/delivery.md	Tamaños de fotograma, renderizado final, verificaciones antes de la entrega, qué informar
references/cookbook.md	La solicitud coincida con un trabajo común. Doce recetas prácticas: un clip silencioso, una pantalla de app a partir de tokens de diseño, varias relaciones de aspecto, un clip de formación paso a paso, un gráfico de barras desde JSON, narración con cada proveedor, regrabar una línea, música de fondo, una fuente y un logotipo personalizados, una app en ejecución, verificaciones finales. También fragmentos de draw()

Solución de problemas

Síntoma	Causa probable
"This looks like a command sandbox", listen EPERM o el navegador no se inicia	El espacio aislado del agente está bloqueando el servidor HTTP o el navegador. Ejecuta stills, capture y serve fuera de él, con la aprobación del usuario
"The page never set window.ready"	Un error de script en la escena (el mensaje lista los errores de la página), o la página no llama al clip() del kit
Dos capturas de la misma escena difieren	Algún estado en la escena no se calcula a partir de s: Math.random(), Date, una animación o transición CSS, un <video>, un temporizador
El texto se renderiza con una fuente diferente en otra máquina	La escena usa fuentes del sistema. Coloca los archivos de fuente en el directorio de la escena (references/scenes.md)
La imagen va por delante o por detrás de la narración	No se ejecutó clip timing después de una nueva grabación, o el video se capturó antes. clip mix se niega a ejecutarse en el primer caso y advierte en el segundo
attempted en la lista de tts	Una solicitud anterior no se completó. Verifica el historial de uso del proveedor antes de usar --retry-attempted
El nivel de música sube y baja entre palabras	Establece "mix": { "master": "limit" } (references/sound.md)