Explainer Short (idea → video terminado)

¿Qué hace Explainer Short (idea → video terminado)?

Produces UN video terminado por solicitud siguiendo los 7 pasos siguientes en orden, una vez. Cada paso tiene un comando, una salida y una condición de parada. No inventes pasos adicionales.

Rutas: SKILL = la carpeta que contiene este archivo. STUDIO = el espacio de trabajo del video (por defecto: ./explainer-studio en el proyecto actual; reutilízalo si existe). SLUG = id en kebab-case del video, p. ej. como-funciona-https.

Límites estrictos (mantiene la ejecución corta y económica)

• Pregunta al usuario como máximo una pregunta, y solo si no hay ningún tema. En caso contrario, decide tú mismo (duración, formato, marca) usando los valores predeterminados a continuación y declara tus elecciones en la respuesta final.
• check.sh → arreglar → check.sh como máximo 2 rondas de arreglo. Luego renderiza, y enumera cualquier problema restante en la respuesta.
• Regenera la voz como máximo 2 veces (solo por duración o una palabra mal pronunciada).
• No edites src/kit/ (excepto para agregar un ícono). No instales otros paquetes o herramientas.
• Lee template/src/videos/example/ una vez (es la implementación de referencia). No leas el código fuente del kit; references/kit-api.md lo documenta.

"Short", "reel", "explicación corta" = el FORMATO vertical, no el modo de duración. Usa el modo de duración "short" solo si el usuario pide un video rápido/muy corto/menos de un minuto o da segundos.

Valores predeterminados: duración 95–120 s (300–370 palabras; "short" = 55–70 s, "full" = la duración de referencia 160–175 s — consulta references/script-guide.md), voz am_michael velocidad 1.18, marca = el nombre/canal del usuario si se conoce, si no "TuMarca". Las reglas de estilo provienen de medir 23 videos de referencia; la evidencia está en references/style-evidence/ (solo humanos — no necesitas leerlo).

Paso 1 — Configuración (una vez por máquina, ~3 min la primera vez, ~2 s después)

bash SKILL/scripts/setup.sh STUDIO

Condición de parada: última línea READY: …. Si imprime MISSING TOOLS, dile al usuario exactamente qué instalar y detente. (Establece KOKORO_MODELS=<dir> primero si los archivos del modelo de voz ya existen en algún lugar, para saltar una descarga de 340 MB).

Paso 2 — Planificar (aún sin código)

Lee references/script-guide.md. Luego escribe STUDIO/src/videos/SLUG/plan.md (≤ 25 líneas, después de que el Paso 3 cree la carpeta):

1. Título en uno de los formatos (Cómo funciona X · X vs Y · Entrevista: … · Diseño de sistemas: cómo hace X).
2. Ejemplo práctico: una persona nombrada + un producto/entrada/valor concreto utilizado de principio a fin.
3. Secciones con ids, 6–9 de ellas, cada una = una idea.
4. Etapas: lee references/visual-guide.md, luego escribe una línea por sección: sección → agregado / movido / enfoque (ids destacados) / sale (consulta "Etapas de planificación" allí). Elige 3–4 acentos y vincula cada uno a una cosa.

Paso 3 — Guion

bash SKILL/scripts/new_video.sh STUDIO SLUG

Escribe STUDIO/src/videos/SLUG/script.json (formato: consulta el script.json del ejemplo). Reglas que rompen cosas:

• sections[].id único, simple (hook, scenario, mechanism, …). La última sección es la CTA.
• Escribe números/símbolos como quieras que se muestren y asígnalos a cómo se dicen en pronounce ("429": "cuatro veintinueve", "API": "A P I", "SQL": "sequel", "k8s": "kubernetes").
• Oraciones ≤ 18 palabras. Solo . ! ? terminan oraciones (cada oración se sintetiza por separado). Autoverifica con la lista de reglas al final de script-guide.md antes de continuar.

Paso 4 — Voz

bash SKILL/scripts/voice.sh STUDIO SLUG

Imprime el inicio/fin de cada sección y Hecho: <seg>s, <palabras> palabras, <ppm> ppm. Condición de parada: duración dentro del objetivo ±15 %. Demasiado largo → corta oraciones (no velocidad) y ejecuta una vez más.

Paso 5 — Visuales

Lee references/kit-api.md y el ejemplo (STUDIO/src/videos/example/Video.tsx + stages/*.tsx). Escribe STUDIO/src/videos/SLUG/Video.tsx + un archivo por etapa en stages/. No negociable:

• El at de cada elemento proviene de cue(sección, palabra) o sec(sección).from — nunca segundos codificados.
• Un lienzo continuo: las cosas persisten, se mueven, se atenúan y se reutilizan. Sin limpiezas de pantalla completa excepto entre etapas.
• Algo cambia visiblemente al menos cada ~3 s de narración (nuevo elemento, resaltado, cambio de estado, movimiento).
• Enfoque = plan de Spotlight en <Canvas focus> (atenuar el resto) — el dispositivo principal del estilo.
• Sin subtítulos. Leyendas (Takeaway) ≤ 7 palabras, 2–6 por video.
• Mantén el contenido en la zona segura (x 60–1020, y 280–1480; título ≈150; leyenda justo debajo del diagrama).
• Llena el ancho: paneles principales con w 960 (o 2 × 465). Nada más pequeño que 26 px.

Paso 6 — Verificar (máximo 2 rondas de arreglo)

check.sh y render.sh inician un servidor local + Chrome sin interfaz gráfica. En un agente en caja de arena, ejecuta ambos comandos fuera de la caja de arena. Si tu entorno no puede hacerlo en absoluto (No available ports found, Chrome no se inicia, se rechazan llamadas fuera de la caja de arena): detente después del Paso 5, y dile al usuario que ejecute check.sh y luego render.sh él mismo (dale ambos comandos completos). No intentes soluciones alternativas.

bash SKILL/scripts/check.sh STUDIO SLUG          # 3er argumento opcional: "12.5,30,41" = segundos extra a inspeccionar

Verifica cada cue() contra la sincronización de voz (instantánea), comprueba tipos, renderiza ~3 fotogramas por sección + tarjeta final, y escribe out/SLUG/check/sheet.jpg (+ NN.jpg fotogramas individuales). Mira la imagen de la hoja (y 2–3 fotogramas individuales a tamaño completo). Arregla solo lo que falla:

Verificación	Fallo cuando
superposición	los textos/cajas chocan o son cortados por el borde de la pantalla
escala	el diagrama usa < 80 % del ancho o deja y 900–1400 vacío en una sección ocupada; texto que tienes que entrecerrar los ojos para ver en un fotograma de 540 px de ancho
legibilidad	cualquier etiqueta más pequeña que ~28 px, o texto sobre un área ocupada
sincronización	un elemento aparece antes de su palabra, o un fotograma muestra un lienzo vacío/desactualizado mientras la narración habla de algo
continuidad	una etapa parece no relacionada con la anterior (todo reemplazado) cuando la historia continúa
enfoque	la cosa de la que se habla no está resaltada (Enfoque / ámbar / atenuar otros)
densidad	un fotograma con > 9 elementos visibles, o > 2 líneas de texto de leyenda

Errores de tipo / cue not found imprimen la solución (la lista de palabras válidas). Arregla y vuelve a ejecutar.

Paso 7 — Renderizar + entregar

bash SKILL/scripts/render.sh STUDIO SLUG

(Si Chrome sin interfaz gráfica está bloqueado por una caja de arena, vuelve a ejecutar este comando fuera de la caja de arena). Luego escribe STUDIO/out/SLUG/upload.md: título (= el título del video, ≤ 60 caracteres, 1 emoji al final permitido), descripción de 2 oraciones, 5 hashtags, y una lista de "Datos a verificar" (cada número/afirmación que hayas dicho de memoria).

Respuesta final (breve): la ruta del MP4, duración, las rutas del SRT/portada/upload.md, las elecciones que hiciste (formato, duración, ejemplo práctico), y cualquier problema conocido restante. Luego detente.

Solución de problemas

Síntoma	Solución
cue not found: "x" #1 in section "y". Words: …	usa una palabra de la lista impresa, o la sección correcta
una palabra se pronuncia mal	agrégala a pronounce y vuelve a ejecutar el paso 4
Cannot find module './timing.json'	no se ejecutó el paso 4 para este SLUG
composition SLUG not found	ejecuta voice.sh (registra el video)
Chrome / SIGABRT / ENOTFOUND remotion.media / No available ports found	la caja de arena bloquea el navegador/puerto: ejecuta el comando sin caja de arena (consulta el Paso 6)
failed to canonicalize path …/voice/.venv/bin/python3 u otros errores de uv/venv	elimina STUDIO/voice/.venv y vuelve a ejecutar setup.sh
un fotograma muestra texto desbordando un panel	dale al <El> un h más grande, menos líneas, o una fuente más pequeña (≥ 26 px)
video demasiado largo/corto	edita el guion (~3.1 palabras por segundo a velocidad 1.18), vuelve a ejecutar el paso 4