SkelegonDK/code-explainer-video

Video explicador de código

Recorridos narrados y animados del código para desarrolladores. El espectador es un ingeniero: muestra código real, nombra archivos y funciones reales, explica por qué y cómo, nunca simplifiques con analogías para no desarrolladores.

Stack: el template Code Hike de Remotion (código resaltado que se transforma entre pasos), Mermaid para diagramas de arquitectura, ElevenLabs para la narración (el conector de ElevenLabs, o la API con una clave) y subtítulos quemados. Carga la skill remotion-best-practices cuando modifiques el código de Remotion en template/.

Archivos junto a este SKILL.md ("el directorio de la skill"):

• template/: los archivos fuente de Remotion copiados en cada proyecto de video.
• references/voice.md: léelo en el paso 8, antes de generar la narración.
• references/long-form.md: léelo primero cuando el video dure 15-30 minutos; divide el trabajo en capítulos que cada uno sigue los pasos 2-9.

1. Toma de requisitos: tres preguntas, en este orden, antes de cualquier trabajo

Pregunta una a la vez (usa AskUserQuestion si está disponible). No las saltes ni las fusiones.

1. ¿Qué necesitas entender? Obtén el objetivo (una línea, bloque, función, archivo, flujo o arquitectura completa) y el motivo (corregir un error, añadir una funcionalidad, revisar un PR, onboardear). Si la respuesta es vaga ("lo de autenticación"), lee el código primero, luego ofrece 2-4 opciones concretas para elegir, p. ej., "cómo se autentica una solicitud de extremo a extremo" vs. "cómo se almacenan y expiran las sesiones".
2. ¿Cuánto tiempo debería durar? Ofrece: ~30 s (una línea o bloque), 1-2 min (una función o módulo), ~5 min (un subsistema o flujo), 15-30 min (onboarding del código base, construido como capítulos por agentes paralelos). Si no lo saben, recomienda uno basado en lo que encontraste en el paso 1.
3. ¿Mi entendimiento es correcto? Después de leer el código, envía:
   • la pregunta que responde el video, en una frase;
   • la duración y el número de beats;
   • el esquema: una línea por beat (qué hay en pantalla + el punto que explica);
   • cualquier cosa que estés omitiendo a propósito. Construye solo después de un sí. Revisa y reconfirma en un no. Este paso existe porque la narración cuesta créditos de ElevenLabs y los renderizados toman minutos.

Cuando se ejecute sin supervisión (sin nadie que responda), elige la lectura más razonable, menciónala al inicio de tu respuesta y continúa.

2. Investiga el código antes de escribir una palabra

• Lee el código real. Rastrea las llamadas hasta sus definiciones; no infieras el comportamiento a partir de los nombres. Para un código base grande, distribuye con un subagente de solo lectura por área, si tu agente admite subagentes, y conserva solo sus conclusiones.
• Cada afirmación en la narración debe asignarse a un archivo y línea que hayas leído. Mantén un notes.md de afirmación → ruta:línea mientras investigas; lo usarás al corregir problemas encontrados en el paso 7.
• Anota con qué tropezaría un desarrollador: efectos secundarios ocultos, suposiciones de orden, caminos de error, configuración que cambia el comportamiento, nombres que engañan.

3. Planifica los beats según el presupuesto de tiempo

Un beat es un visual más 1-3 frases de narración. La narración va a unas 150 palabras por minuto (2.5 palabras/s); cada beat tiene una pausa final de 0.6 s.

Presupuesto	Beats	Palabras
30 s	3-4	~70
1-2 min	6-12	150-280
5 min	20-30	~700
15-30 min	capítulos de 3-5 min, consulta references/long-form.md

Reglas de los beats:

• Abre con la pregunta que se responde y cierra con un resumen de una línea. Sin relleno de introducción, sin "en este video".
• Primero la arquitectura, luego acércate: diagrama, luego el código del punto de entrada, luego la línea interesante.
• Explica el propósito, no las líneas. Cada beat de código dice para qué sirve el código y cómo se conecta con el beat anterior, luego señala la o las dos líneas que importan. Nunca recorras un bloque línea por línea.
• Beats de código: máximo 16 líneas (la parte inferior del marco está reservada para los subtítulos) y 80 caracteres por línea. Elimina líneas irrelevantes y reemplázalas con un comentario // .... Los beats consecutivos que muestren el mismo fragmento con un resaltado diferente se animan suavemente, así que reutiliza fragmentos y mueve el resaltado.
• Resalta de qué habla la narración con un comentario de Code Hike directamente encima: // !mark (siguiente línea) o // !mark(1:4) (las siguientes cuatro líneas). Usa la sintaxis de comentario del lenguaje (# !mark en Python).
• Beats de diagrama: flowchart de Mermaid con un máximo de 8 nodos. Usa TD para cadenas de más de cuatro nodos. Mantén los nodos idénticos entre beats de diagrama consecutivos y solo mueve la línea class X hot, para que el diseño no salte.
• La narración está escrita para el oído: frases cortas, di los identificadores como los dicen los desarrolladores ("la función handle-request"), no leas código en voz alta símbolo por símbolo, no digas números de línea.

4. Configuración del proyecto (una vez por video)

Establece SKILL_DIR en el directorio de la skill, luego:

npx create-video@latest --yes --code-hike explainer && cd explainer
npx remotion add @remotion/media && npm rm twoslash-cdn && rm public/code*
rm src/calculate-metadata/process-snippet.ts src/annotations/Callout.tsx src/annotations/Error.tsx src/ProgressBar.tsx src/ReloadOnCodeChange.tsx
cp -R "$SKILL_DIR/template/." .
command -v mmdc || npm i -g @mermaid-js/mermaid-cli

Twoslash se elimina a propósito: marca cada importación no resuelta en un fragmento de código como un error rojo. Los archivos copiados reemplazan la composición de la plantilla por una impulsada por beats/:

• scripts/build.mjs convierte beats/ en public/beats/ (audio, diagramas renderizados, manifest.json) y mide la duración del audio de cada beat.
• src/Main.tsx reproduce los beats en secuencia: título, código o diagrama, audio, subtítulos.
• src/annotations/Mark.tsx implementa el resaltado !mark. src/Captions.tsx temporiza los fragmentos de subtítulos a lo largo del audio de cada beat.

5. Escribe los beats

Un par de archivos por beat en beats/, numerados para que se ordenen (01, 02, … 10):

• NN.txt: primera línea opcional # <título en pantalla> (usa ruta/al/archivo.ts:42-60 para beats de código, un encabezado corto para diagramas), luego la narración.
• Un visual: NN.<ext> con el fragmento de código (la extensión define el lenguaje de resaltado: .ts, .py, .go, …) o NN.mmd con un diagrama Mermaid. Resalta un nodo del diagrama con classDef hot fill:#facc15,color:#000,stroke:#facc15 y class NodeId hot.

Ejemplo de par:

beats/04.txt
# src/auth/session.ts:31-44
Las sesiones se renuevan de forma diferida. La comprobación de caducidad solo se ejecuta cuando llega una solicitud, por lo que una sesión inactiva nunca se limpia aquí.

beats/04.ts
export async function getSession(id: string) {
  const s = await store.get(id);
  // !mark(1:3)
  if (s && s.expiresAt < Date.now()) {
    return renew(s);
  }
  return s;
}

6. Borrador (sin créditos)

1. node scripts/build.mjs sin beats/*.mp3 y sin clave genera un audio de marcador de posición silencioso con la duración estimada e imprime el total. Si supera o está por debajo del presupuesto en más del 15%, recorta o añade beats ahora.
2. Renderiza fotogramas de los momentos con más contenido en pantalla y del momento en que aparece cada resaltado (aproximadamente 1.5 s después de iniciar un beat): npx remotion still Main out/check.png --frame=<n> --scale=0.5. Obsérvalos. Corrige líneas que se desbordan, diagramas ilegibles y resaltados en la línea incorrecta.

7. Verificación independiente de hechos (antes de generar cualquier narración)

El autor de un guion es la peor persona para revisarlo. Haz que un revisor que no lo haya escrito verifique cada afirmación contra el código. Haz esto incluso cuando se ejecute sin supervisión.

• Si tu agente admite subagentes, inicia uno nuevo. Dale la ruta del repositorio, cada beats/NN.txt y su visual, y estas instrucciones, pero no notes.md ni tu esquema, para que forme su propia lectura del código:

  Revisa este guion explicativo contra el código. Enumera cada afirmación factual en la narración y en los títulos en pantalla. Para cada una, encuentra el código que la confirma o contradice, rastreando las llamadas hasta sus definiciones. Devuelve una fila por afirmación: beat | afirmación | correcta / incorrecta / no verificable | ruta:línea | por qué. También marca fragmentos de código que difieran de la fuente (aparte de los cortes // ... y los comentarios !mark), títulos cuyo rango ruta:línea sea incorrecto, cualquier cosa importante sobre este código que el guion presente de manera engañosa, y beats de código cuya narración recorra las líneas sin decir para qué sirve el código.

• De lo contrario, haz una segunda pasada tú mismo: para cada afirmación, vuelve a abrir el código citado y verifícalo allí, no contra notes.md.

Corrige cada afirmación incorrecta, elimina o suaviza cada una no verificable, y reescribe los beats marcados como línea por línea en torno a su propósito. Vuelve a ejecutar la compilación del borrador y envía solo los beats modificados para una segunda verificación.

8. Voz y renderizado

1. Lee references/voice.md y genera un archivo de narración por beat con la primera opción disponible: el conector de ElevenLabs, una clave de API de ElevenLabs, otro proveedor de texto a voz, o ninguno (video silencioso con subtítulos). Usa una sola voz para todo el video.
2. node scripts/build.mjs de nuevo. Usa beats/NN.mp3 cuando esté presente, por lo que cambiar un beat significa reemplazar solo ese archivo.
3. Renderiza una vez: npx remotion render Main out/explainer.mp4. Comprueba que las duraciones de video y audio coincidan (ffprobe -v error -show_entries stream=codec_type,duration -of csv=p=0 out/explainer.mp4) y, a menos que el video deba ser silencioso, que el audio no lo sea (ffmpeg -i out/explainer.mp4 -af volumedetect -vn -f null - 2>&1 | grep mean_volume; el audio de marcador se lee como aproximadamente -91 dB).

9. Antes de entregar

• Mira, o al menos escucha, el primer y último beat y uno del medio. Si un identificador se pronuncia mal, vuelve a escribirlo fonéticamente en NN.txt y vuelve a vocalizar solo ese beat. Los subtítulos muestran el texto de la narración, por lo que una reescritura fonética también aparece allí; mantén las reescrituras legibles.
• Cualquier narración que haya cambiado después del paso 7 vuelve a pasar por él.
• Entrega el mp4 con un resumen de una línea de la pregunta que responde. Nunca lo subas ni publiques en ningún lugar sin permiso explícito.