Video de PR
Un video explicativo de 40 a 100 segundos sobre un pull request, dirigido a alguien que no lo leerá (a menudo un gerente): qué cambios,
por qué, cómo funciona, qué riesgos tiene, el estado y por dónde debería empezar un revisor. Técnico pero sencillo.
Todo se ejecuta a través de la CLI: node cli/prs.mjs <comando> desde la raíz del repositorio, o
node <ruta a pr-studio>/cli/prs.mjs <comando> desde cualquier lugar (abajo: prs).
Inicio
- Nadie está mirando (un trabajo de GitHub Actions)? Lee primero guides/unattended.md: sin preguntas, un límite de tiempo, una ronda de revisión, dónde va el resultado.
- Iniciado desde Slack (@GitHub, una sesión en la nube)? Lee primero guides/slack.md: triaje, el presupuesto de 59 minutos, publicar cada video en el hilo y qué no hacer allí.
- Una vez por máquina:
prs doctor(navegador, modelo de voz, Whisper, ffmpeg; solo agrega lo que falta). - Luego lee guides/story.md y guides/visuals.md. Hojea catalog.md para conocer los diagramas disponibles.
Flujo de trabajo (apunta a 15-20 minutos)
- Obtener.
prs new <URL del PR>escribevideos/<slug>/:brief.md(léelo completo),pr.diff(búscalo para las líneas que necesites; no lo leas completo),pr.jsony un esqueleto de guion gráfico con el número correcto de viñetas. - Historia. Escribe
videos/<slug>/storyboard.json: una idea por viñeta, unanecesidadpor viñeta, pistas y las afirmaciones con evidencia (guides/story.md). Ejecutaprs checkhasta que diga listo para voz prs. - Voz, en segundo plano. Inicia
prs voice(aproximadamente un minuto; MAI-Voice-2 cuando hay una clave de Azure configurada, de lo contrario la voz local Kokoro) y sigue trabajando mientras se ejecuta. - Dirección.
prs directelige un tratamiento para cada viñeta y el movimiento para el video, escribedirection.jsony genera el esqueleto descenes.jscon esos tratamientos. Completa cada TODO del PR. Mantén las selecciones: se eligen para diferenciarse de videos recientes. Si uno realmente no puede mostrar su viñeta, vuelve a elegirlo conprs direct --use <beat>=<treatment> --reason "..."(la razón se registra y revisa). - Apariencia.
prs stillsrenderiza fotogramas clave ybuild/stills/contact.png. Abre la hoja de contactos y los fotogramas que importan, y arregla lo que veas. Los fotogramas funcionan antes de que la voz esté lista (temporización provisional). - Verificación.
prs lintdebe reportar 0 problemas (diseño, procedencia del texto, banda de subtítulos, novedad, QR). - Renderizar y publicar.
prs render(segundos, los fotogramas están en caché), luegoprs publish: codificar, subtítulos, la puerta de sincronización (audio vs subtítulos), entrega en~/Downloads/pr-videos/<slug>/y la entrada en la galería. - Aprobación. Sigue guides/review.md hasta que el agente
pr-directorrespondaVEREDICTO: APROBADO; vuelve a publicar después de las correcciones. - Entregar. Proporciona la ruta del mp4, su duración, un resumen de una línea por viñeta, el veredicto y lo que no pudiste verificar (no puedes escuchar el audio; la puerta de sincronización lo mide).
Opcional: si el usuario solicita opciones, agrega export const concepts = { beat, options: { a, b, c } } a
scenes.js y ejecuta prs concepts: renderiza la viñeta de tres maneras lado a lado.
Reglas
- Preciso o ausente. Cada afirmación en la narración y en pantalla debe provenir del PR: su cuerpo, commits, diff, pruebas o código en el commit principal. Escribe las afirmaciones no probadas del autor como "según el autor". Sin conjeturas sobre intenciones, sin marketing.
- Procedencia del texto. El texto en pantalla pasa por
label()(tus palabras),fact()(números y nombres depr.json),quote()(texto exacto del PR),ident()(nombres de código en el diff),path()ycode().prepareverifica cada uno contra el PR; los números dentro de unlabel()se marcan. - Un solo aspecto visual. Blanco, paleta de Microsoft, Aptos. No agregues colores, fuentes, fondos o nuevos diseños dentro de un video. El primer fotograma (título) y la tarjeta final son fijos.
- Explicaciones diferentes. Nunca abras ni copies el
scenes.jsde otro video; la galería solo guarda guiones gráficos y hojas de contactos. Si al catálogo le falta un diagrama que el PR necesita, agrega un tratamiento acatalog/(con demo,when, parámetros, un fotograma de catálogo medianteprs catalog --stills, lint limpio) en lugar de colocar píxeles manualmente. - Mira lo que haces. Abre los fotogramas y la hoja de contactos antes de decir que algo funciona.
Comandos
prs new <url> | obtener el PR, escribir brief.md y un esqueleto de guion gráfico |
prs check | guion gráfico: ventana de duración, pistas, marcadores de posición, anclas de evidencia, sugerencias de pronunciación |
prs voice [--provider mai|kokoro|recording|silent] | narración + temporización de palabras (ajustada por pausas) |
prs direct [--use beat=treatment --reason ...] | elegir tratamientos y movimiento; generar el esqueleto de scenes.js |
prs stills [--beat id] [--at 12.3,20] | fotogramas clave + hoja de contactos |
prs lint [--every 0.5] | diseño, procedencia, banda de subtítulos, novedad, QR |
prs render / prs draft | fotogramas finales / un mp4 de vista previa a mitad de tamaño |
prs publish | codificar, subtítulos, puerta de sincronización, entregar, galería |
prs catalog | cada tratamiento con sus parámetros |
prs triage <PRs> | --file f, prs summary, prs budget | qué PRs merecen un video (ejecuciones de Slack); el mensaje de cierre; minutos restantes en una sesión en la nube |
prs history, prs report | videos recientes; dónde se fue el tiempo |
prs smoke | un video de demostración corto de principio a fin, con tiempos: ¿está lista esta máquina? |