Communitygithub.com

motion-preflight-qa

Garantía de calidad automatizada previa al renderizado y posterior para gráficos en movimiento, videos generados por IA (HyperFrames, Remotion, HTML/GSAP) y anuncios sociales cortos (Reels de Instagram, TikTok, Shorts de YouTube, LinkedIn). Audita códecs, formato de píxel (yuv420p), indicadores de transmisión faststart, sonoridad EBU R128 (-14 LUFS / -1 dBTP), ganchos negros muertos, genera una hoja de contacto de zona segura de 6 fotogramas y produce archivos MP4 listos para entrega. Úselo siempre que verifique, corrija o prepare un video renderizado para entrega al cliente o carga en redes sociales.

¿Qué es motion-preflight-qa?

Motion Preflight QA es una herramienta de automatización diseñada para garantizar la calidad de entregables de video generados mediante código, como animaciones creadas con HyperFrames, Remotion o HTML/GSAP, y anuncios cortos para redes sociales (Instagram Reels, TikTok, YouTube Shorts, LinkedIn). Su función principal es eliminar la necesidad de re-renderizados manuales y corregir problemas comunes como subtítulos recortados, audio silenciado o distorsionado, y errores de reproducción en iOS/QuickTime. La herramienta realiza una auditoría técnica de 8 puntos que verifica el códec y formato de contenedor, el formato de píxel (yuv420p), la presencia del indicador faststart para reproducción progresiva, la relación de aspecto, la consistencia de la frecuencia de cuadros, la integridad de los ganchos negros, la sonoridad según el estándar EBU R128 y el tamaño de archivo. Además, genera una hoja de contacto con zonas de seguridad para la plataforma objetivo y ofrece un comando para corregir automáticamente los problemas detectados. Está diseñada para ser ejecutada en pipelines CI/CD o localmente, requiriendo solo Python 3.9+ y FFmpeg/FFprobe en el PATH.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Shk2005/motion-preflight-qa/tree/HEAD

Preguntar en tu IA favorita

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

Documentación

Motion Preflight QA

Puerta de calidad determinista para transmisión y plataformas sociales, diseñada para gráficos en movimiento renderizados con código y anuncios de video cortos. Creada para eliminar re-renderizados ciegos, subtítulos recortados, audio silenciado o distorsionado, y errores de reproducción en iOS/QuickTime.

Prerrequisitos

  • Python 3.9+ (solo biblioteca estándar — no se requieren paquetes Python de terceros)
  • FFmpeg y FFprobe en PATH

Flujo de trabajo estándar de QA (Ejecutar antes de cada entrega)

Paso 1: Auditar el video renderizado

Ejecute la auditoría técnica de 8 puertas contra la plataforma objetivo (reels, tiktok, shorts, youtube, linkedin, square o auto):

python3 scripts/audit_video.py ruta/al/video.mp4 --platform reels

Use --json para obtener una salida legible por máquina al encadenar en pipelines automatizados.

Lo que verifica:

  1. Contenedor y códec: Compatibilidad con H.264 (libx264) o HEVC MP4.
  2. Formato de píxel (yuv420p): Detecta exportaciones yuv444p / 10 bits que se muestran como pantallas negras en QuickTime, Safari e Instagram iOS.
  3. Faststart web (moov antes de mdat): Verifica la reproducción progresiva instantánea en dispositivos móviles sin demoras de almacenamiento en búfer.
  4. Relación de aspecto y resolución: Comprueba que coincidan con las dimensiones de la plataforma objetivo (por ejemplo, 1080x1920 para vertical 9:16).
  5. Consistencia de la frecuencia de cuadros: Verifica FPS estándar limpio (24, 30, 60 o 120) y marca frecuencias de cuadros variables no estándar.
  6. Integridad del gancho (escaneo de cuadros negros): Marca cualquier introducción negra muerta (> 0.25 s al inicio) o espacios negros inesperados en medio del video.
  7. Sonoridad del audio (EBU R128): Mide la sonoridad integrada (I en LUFS) y el pico verdadero (TP en dBTP) contra el estándar social de -14 LUFS / -1.0 dBTP.
  8. Tamaño de archivo y presupuesto de tasa de bits: Marca exportaciones de grano de película infladas que desencadenan una recompresión agresiva de la plataforma.

Paso 2: Generar la hoja de contacto de zona segura

Genere una hoja de prueba visual de 6 fotogramas con las zonas de peligro de la HUD de la plataforma, precisas a nivel de píxel, enmascaradas en rojo translúcido y el perímetro seguro de título delineado en verde:

python3 scripts/safe_zone_overlay.py ruta/al/video.mp4 --platform reels --out qa_contact_sheet.png

Inspeccione qa_contact_sheet.png (visualmente o con una herramienta de lectura de imágenes):

  • Zonas rojas = áreas de peligro de la interfaz de usuario (encabezado superior, carril derecho de me gusta/comentario/compartir, cajón inferior de subtítulos/audio).
  • Cuadro verde = Zona segura de título. Cualquier titular, estadística, llamada a la acción de producto o CTA que toque el rojo DEBE ser reposicionado antes de la entrega.
  • Para inspeccionar una sola marca de tiempo problemática a máxima resolución, agregue --at <segundos> --out proof_frame.png.

Paso 3: Auto-maestro para entrega (si alguna verificación técnica advierte o falla)

Corrija el formato de píxel, inyecte +faststart, aplique normalización de sonoridad EBU R128 de dos pasos (-14 LUFS, -1.0 dBTP) y optimice la tasa de bits de forma limpia:

python3 scripts/fix_delivery.py ruta/al/video.mp4 --out ruta/al/video_maestro.mp4 --crf 20

Use --crf 23 para fondos con grano de película pesado o ruidosos para reducir el tamaño del archivo sin tipografía borrosa. Luego, vuelva a ejecutar el Paso 1 en el archivo maestro para confirmar un PASE 100/100.

Documentación de referencia

  • references/platform-safe-zones.md — Coordenadas exactas de zona segura y márgenes de píxel para 2026 para Instagram Reels, TikTok, YouTube Shorts, LinkedIn y pantalla ancha 16:9.
  • references/delivery-specs.md — Códec, espacio de color, sonoridad, tasa de bits y correcciones comunes de fallos de código a video.

Skills relacionados