Communitygithub.com

tldraw/tldraw

Crea un video narrado que recorre los cambios de un pull request, con diapositivas de código y narración de audio. Úsalo cuando te pidan un video de revisión de PR, video de PR o video guiado.

¿Qué es tldraw?

Esta habilidad genera automáticamente un video de resumen narrado para cualquier pull request de GitHub en el repositorio tldraw/tldraw. El video, similar a un Loom creado por el autor del PR, explica los cambios de código, el razonamiento detrás de ellos y el contexto general, permitiendo a los revisores comprender el PR de forma rápida y profunda. La habilidad soporta la narración mediante TTS de Google Gemini (voz Iapetus), la transcripción local con Whisper para generar subtítulos sincronizados, y la creación de diapositivas de código a partir del diff del PR. El resultado es un video MP4 en 1280×720 con subtítulos amarillos sobre fondo negro, una introducción y un resumen estructurados, y una duración típica de 5 a 7 minutos. El flujo de trabajo incluye: entender el PR, escribir la narración en segmentos, generar el audio, crear el manifiesto con las diapositivas y renderizar el video final mediante un pipeline que usa ffmpeg, Node.js e Hyperframes.

Compatible con✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/tldraw/tldraw/tree/HEAD/skills/pr-walkthrough

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Video de resumen de pull request

Crea un video narrado que recorre los cambios de un pull request. Está diseñado como un artefacto interno, que proporciona el mismo beneficio que un video de Loom creado por el autor del PR: explicar los cambios de código, qué se hizo y por qué, para que cualquier persona que vea el video pueda entender el PR rápidamente.

Entrada: Una URL de pull request de GitHub (por ejemplo, https://github.com/tldraw/tldraw/pull/7924). Si solo se proporciona un número de PR u otra descripción, se asume que el PR está en el repositorio tldraw/tldraw.

Salida: Un video MP4 a 1280×720 (30 fps) con narración de audio, subtítulos amarillos sobre fondo negro sincronizados con Whisper, diapositivas estándar de introducción y conclusión, guardado en out/pr-<numero>-resumen.mp4.

Todos los archivos intermedios (audio, manifiesto, scripts) van en tmp/pr-<numero>/ relativo al directorio de esta habilidad. Este directorio está en gitignore. Solo el .mp4 final reside en out/.

Ejecuta los comandos que hagan referencia a ./scripts o ./video desde este directorio de habilidad.

Filosofía

Este es un resumen desde la perspectiva del autor. El objetivo es el mismo que si el autor del PR se sentara con alguien y le explicara los cambios, mostrando código específico, explicando qué cambió y por qué, en un orden que construya comprensión. El espectador debe terminar entendiendo tanto qué hace el código como cómo pensar sobre los cambios.

Esto significa:

  • La narración lo impulsa todo. Primero escribe la narración del resumen como una explicación continua del PR. Luego determina qué debe mostrarse en pantalla en cada momento para respaldar lo que se dice.
  • Muestra el código. El visual predeterminado es un diff o archivo fuente. Las diapositivas de texto son la excepción (introducción, transiciones breves, conclusión), no la regla. Cuando la narración hable de una función, el espectador debe estar viendo esa función.
  • Recorre los cambios en un orden lógico, no necesariamente en orden de archivo o de confirmación, pero siempre anclado a código concreto, no a descripciones abstractas.
  • Explica el "por qué", no solo el "qué". El código en pantalla muestra qué cambió. La narración añade el razonamiento: por qué este enfoque, qué problema resuelve, qué casos extremos maneja.

Flujo de trabajo

Paso 1: Entiende el PR

Lee las confirmaciones, el diff y la descripción del PR. Entiende el arco narrativo:

  • ¿Qué problema resuelve esto?
  • ¿Cuál es el enfoque?
  • ¿Cuáles son los mecanismos clave?
gh pr view <numero> --json title,body,commits
git log main..HEAD --oneline
git diff main..HEAD --stat

Omite los archivos generados. Al leer el diff, ignora los archivos que se generan automáticamente en lugar de editarse manualmente. Estos añaden ruido sin informar el resumen. Ejemplos comunes en este repositorio:

  • **/api-report.md, **/api-report.api.md: informes de superficie API generados
  • **/*.api.json, **/temp/*.api.json: salida del extractor de API
  • apps/docs/content/reference/**: documentación de referencia generada
  • pnpm-lock.yaml, package-lock.json: archivos de bloqueo
  • **/CHANGELOG.md: registros de cambios generados automáticamente
  • Cualquier archivo que las herramientas del repositorio regeneren (instantáneas, volcados de esquema, assets empaquetados)

Si no estás seguro de si un archivo está generado, busca un comentario de encabezado como "NO EDITAR" o verifica si el repositorio tiene un comando generador que lo produzca. Filtra estos al elegir qué archivos destacar en las diapositivas diff/code.

Paso 2: Escribe la narración

Escribe la narración como texto continuo, dividido en segmentos lógicos. Cada segmento es un paso del resumen: un concepto, un cambio o un grupo de cambios relacionados. Guárdalo como tmp/pr-<numero>/SCRIPT.md.

La narración debe leerse como si el autor explicara el PR a un colega: "Entonces, lo que estamos haciendo aquí es... El problema central era X... El enfoque que tomé fue Y... Si miras esta función aquí..."

Estructura: introducción → contexto/problema → recorrido de código → resumen. Consulta Estructura del guion a continuación.

Si las confirmaciones son simples y están bien organizadas (a menudo en una rama con -clean en su nombre), puedes seguir sus mensajes y descripciones para guiar tu narración. De lo contrario, examina el código y crea tu propia narrativa. Introduce conceptos en un orden que se base en los anteriores.

Evita la redundancia, especialmente entre la introducción y el primer segmento de contenido.

Paso 3: Genera audio y marcas de tiempo

Genera clips de audio por segmento con una llamada TTS por segmento. Esto evita por completo la división, alineación y fragmentación: cada segmento es lo suficientemente corto para una única llamada TTS confiable.

Escribe un archivo narration.json y luego ejecuta la herramienta CLI generate-audio.sh:

./scripts/generate-audio.sh narration.json tmp/pr-<numero>/

Clave API: Se obtiene automáticamente del archivo .env del repositorio (GEMINI_API_KEY).

Formato JSON de narración

{
	"style": "Lee la siguiente narración del resumen en un tono tranquilo, constante y profesional. Habla a un ritmo pausado, como si el autor de un pull request estuviera explicando los cambios de código a un colega.",
	"voice": "Iapetus",
	"slides": [
		"Este pull request añade resolución de enlaces con conciencia de grupo a la herramienta de flecha...",
		"El problema central era que los enlaces de flecha se rompían cuando la forma objetivo...",
		"Si miras el método getBindingTarget en ArrowBindingUtil.ts..."
	]
}
  • style: Persona de voz e instrucciones de ritmo. Mantenlo breve y específico.
  • voice: Nombre de voz de Gemini (predeterminado: Iapetus).
  • slides: Arreglo de texto de narración, una entrada por segmento.

Cómo funciona

  1. Para cada segmento, el script construye un mensaje: preámbulo de estilo + texto del segmento.
  2. Una llamada API a gemini-3.1-flash-tts-preview por segmento genera un clip WAV directamente.
  3. Cada clip se valida (verificación de duración razonable frente al conteo de palabras) y se reintenta automáticamente si la salida es mala.
  4. Se recorta el silencio inicial/final de cada clip.

Salida: Clips de audio por segmento (audio-00.wav, ...) y un archivo durations.json que mapea cada nombre de archivo de audio a su duración en segundos.

Dependencias: ffmpeg / ffprobe. No se requieren paquetes de Python más allá de la biblioteca estándar.

NO uses etiquetas de marcado [pausa larga] o [pausa media] en el texto de la narración; el modelo podría leerlas en voz alta.

Paso 4: Escribe el manifiesto

Lee durations.json del paso 3 para la duración de cada clip, luego escribe manifest.json junto a los archivos de audio. Enumera una entrada por diapositiva, en orden, cada una con su type, audio y durationInSeconds.

Consulta references/manifest.md para conocer los tipos de diapositivas y sus campos.

Paso 5: Renderiza el video

Ejecuta el script render.sh:

./video/render.sh \
  tmp/pr-<numero>/manifest.json \
  out/pr-<numero>-resumen.mp4

El script:

  1. Copia los archivos de audio/imagen referenciados a video/assets/.
  2. Ejecuta la transcripción de Whisper en cada archivo de audio → video/transcripts/audio-NN.json (idempotente: solo retranscribe si el audio es más reciente que la transcripción existente).
  3. Ejecuta build.mjs <manifest> para generar video/index.html: una composición de hyperframes con clips temporizados para cada diapositiva, línea de tiempo GSAP para transiciones y paneos de enfoque de código, y clips de subtítulos amarillos sobre fondo negro con horas de inicio/fin derivadas de las transcripciones de Whisper.
  4. Revisa la composición y renderiza fotogramas de 1920×1080 mediante npx hyperframes render.
  5. Reduce la resolución a 1280×720 / 30 fps y re-comprime con ffmpeg (CRF 26 + AAC 96k) para el MP4 final pequeño pero nítido.

Dependencias: Node.js 22+, ffmpeg, Python 3 (usado por render.sh para analizar el manifiesto). hyperframes se invoca mediante npx --yes, por lo que no hay paso de instalación. Whisper se ejecuta localmente (modelo small.en, ~150 MB en la primera descarga).

Sincronización de subtítulos con Whisper

Los subtítulos aparecen como texto amarillo sobre una píldora negra sólida, anclada a la parte inferior del fotograma. Sus horas de inicio/fin provienen de transcripciones de Whisper a nivel de palabra agrupadas en fragmentos de 5 a 7 palabras, con ruptura temprana en pausas naturales (intervalos >450 ms = límites de oración). Una implicación: Whisper transcribe nombres de marca/código fonéticamente: "tldraw" → "TL Draw", "OverlayUtil" → "overlay util". Esto es aceptable para subtítulos, pero podría normalizarse posteriormente mediante una tabla de sustitución en build.mjs.

Perillas de tamaño de archivo

El renderizado predeterminado apunta a ~30–60 MB para un video de 8 minutos. Para ajustar:

  • --crf <n> en el paso de reducción de escala de ffmpeg dentro de render.sh: 22 es casi sin pérdida, 26 es el predeterminado, 30+ es mucho más pequeño. CRF 28–30 es un buen rango para un resultado de calidad documental.
  • El renderizado de hyperframes a 1080p usa -q draft --crf 30 para mantener el archivo intermedio pequeño (la reducción de escala domina el tamaño final de todos modos).

Organización de archivos

La salida final reside en este directorio de habilidad. Todos los archivos intermedios van en tmp/ (gitignored):

pr-walkthrough/
├── SKILL.md                    # Este archivo
├── scripts/                    # Herramientas CLI (verificadas)
│   └── generate-audio.sh       # narration.json → WAV por diapositiva + durations.json
├── video/                      # Proyecto Hyperframes (verificado)
│   ├── hyperframes.json        # Configuración de hyperframes
│   ├── meta.json               # Metadatos del proyecto
│   ├── build.mjs               # manifest.json → composición index.html
│   ├── render.sh               # manifest.json → MP4 720p (pipeline completo)
│   ├── assets/                 # Poblado automáticamente al renderizar (gitignored)
│   ├── transcripts/            # JSON a nivel de palabra de Whisper (gitignored, en caché)
│   └── renders/                # Renderizados intermedios a 1080p (gitignored)
├── out/                        # Salidas finales (gitignored)
│   └── pr-XXXX-resumen.mp4
└── tmp/                        # Archivos intermedios (gitignored)
    └── pr-XXXX/
        ├── SCRIPT.md           # Guion de narración
        ├── narration.json      # Entrada para generate-audio.sh
        ├── durations.json      # Nombre de archivo de audio → duración en segundos
        ├── manifest.json       # Entrada para render.sh
        └── audio-XX.wav        # Clips de audio por segmento

Configuración de API

  • Clave API de Gemini: Almacenada como GEMINI_API_KEY en el archivo .env raíz del proyecto. Se usa para TTS y alineación de audio.
  • Modelo TTS: gemini-3.1-flash-tts-preview
  • Voz TTS: Iapetus (siempre)

Estructura del guion

El resumen sigue un arco narrativo consistente. No todas las secciones necesitan su propio segmento: combina u omite secciones según la complejidad del PR. El objetivo es 8-12 segmentos en total, con la gran mayoría mostrando código.

Introducción (1 segmento)

La tarjeta de introducción: logotipo de tldraw + título del PR + fecha. La narración debe ser una sola frase que enmarque lo que hace este PR a alto nivel. No entres en detalles todavía.

Tipo de diapositiva del manifiesto: intro.

Contexto (0-1 segmentos)

Breve orientación antes de sumergirse en el código. ¿Cuál era la situación antes de este PR? ¿Qué problema o necesidad motivó el trabajo? Mantenlo corto: solo el marco suficiente para que el recorrido de código tenga sentido.

  • Sé concreto: "Los enlaces de flecha se rompían cuando la forma objetivo estaba dentro de un grupo" no "Había problemas con los enlaces"
  • Nombra el área del código base afectada

Si el contexto puede explicarse mientras se muestra la primera pieza de código relevante, omite el segmento de contexto independiente y fusiónalo en el primer segmento de código.

Tipo de diapositiva del manifiesto: text o diff (si se muestra el código problemático).

Recorrido de código (6-10 segmentos)

El grueso del video. Recorre los cambios de código reales, mostrando diffs y archivos específicos mientras se explica qué se hizo y por qué.

Cada segmento debe mostrar código. Usa diapositivas diff para los cambios y diapositivas code para código de referencia sin cambios.

Pautas:

  • Nombra archivos y funciones. Cada segmento narrado debe hacer referencia a al menos un archivo o función específica.
  • Muestra el diff. El visual para cada segmento debe ser el diff real que se está discutiendo. Usa git diff main..HEAD -- ruta/al/archivo para obtener el diff, luego extrae los fragmentos relevantes.
  • Ordena por comprensión, no por archivo. Presenta los cambios en el orden que construya la comprensión. Si un nuevo tipo se define en un archivo y se consume en otro, muestra la definición primero.
  • Explica el "por qué", no solo el "qué". El diff muestra qué cambió; la narración añade el razonamiento, los casos extremos que maneja, las alternativas que se consideraron.
  • Omite el código repetitivo, pero menciónalo. No dediques un segmento a cada cambio de importación o exportación de tipo, pero menciona de pasada: "También hay algunas exportaciones de tipo añadidas en index.ts — son solo reexportaciones de los nuevos tipos que veremos a continuación."
  • Agrupa cambios pequeños relacionados. Si tres archivos recibieron la misma corrección de una línea, un segmento puede cubrir los tres. Menciona cada archivo por nombre.

Resumen (1 segmento)

Recapitula brevemente lo que logró el PR. Este es un cierre breve: una o dos frases resumiendo el cambio general, mencionando cualquier limitación conocida o trabajo de seguimiento si es relevante.

Tipo de diapositiva del manifiesto: text.

Conclusión (1 segmento, silencioso)

El logotipo de tldraw, 3 segundos de silencio. Incluye siempre esto como diapositiva final.

Tipo de diapositiva del manifiesto: outro con durationInSeconds: 3.

Consejos para escribir la narración

  • Sé específico sobre el código. Di "En BindingUtil.ts, el controlador onAfterChange ahora verifica los ancestros del grupo" — no "El sistema de enlaces se actualizó." Nombra archivos y funciones para que el espectador pueda conectar la narración con lo que está en pantalla.
  • Cada segmento = un cambio o grupo estrechamente relacionado de cambios. Si no puedes señalar un diff específico para el segmento, probablemente sea demasiado abstracto.
  • Escribe como el autor. El tono debe ser explicativo y natural, como explicar tu trabajo a alguien. "Entonces, lo principal aquí es..." o "La parte complicada era..." están bien.
  • Evita la redundancia entre la introducción y el primer segmento de contenido.
  • Menciona archivos que no se muestran. Si un PR toca 15 archivos pero solo 6 son interesantes, reconoce brevemente los otros: "Los cambios restantes son exportaciones de tipo y accesorios de prueba."
  • Apunta a 5-7 minutos de narración total.

Lista de verificación

  • Lee todas las confirmaciones del PR y comprende el diff completo
  • Escribe la narración en SCRIPT.md (8-12 segmentos)
  • Genera audio por segmento (voz Iapetus)
  • Lee durations.json para obtener las duraciones por segmento
  • Escribe manifest.json con tipos de diapositivas, referencias de audio y duraciones

Skills relacionados