Communitygithub.com

upload-preflight

Verifica si un video vertical renderizado es aceptado por TikTok, YouTube Shorts, Instagram Reels o Facebook Reels, o explica por qué falló una subida o publicación programada. Ejecuta un verificador publicado con ffprobe y proporciona la corrección FFmpeg para cada fallo.

¿Qué es upload-preflight?

Esta habilidad, "upload-preflight", analiza un archivo de video vertical renderizado o exportado para determinar si cumple con los requisitos técnicos de las principales plataformas de video corto: TikTok, YouTube Shorts, Instagram Reels y Facebook Reels. Es especialmente útil cuando una subida o publicación programada falla, ya que identifica la causa exacta (por ejemplo, frecuencia de cuadros incorrecta, códec de audio rechazado, archivo demasiado grande, duración excesiva) y sugiere una corrección mediante un comando FFmpeg específico. La herramienta se basa en el proyecto de código abierto shortform-preflight, que utiliza ffprobe para leer las propiedades del archivo y las compara con las especificaciones publicadas por cada plataforma. Soporta múltiples modos de verificación: reglas de subida directa (app route), reglas de web, reglas de API de publicación, y ajustes personalizados para TikTok Direct Post. El agente debe guiar al usuario paso a paso: verificar las herramientas necesarias (ffprobe, node, npx), ejecutar el análisis en formato JSON, interpretar cada fallo o advertencia, y proporcionar el comando FFmpeg exacto para solucionar el problema. Está diseñado para evitar errores comunes como la recodificación innecesaria o la alteración de la resolución sin preguntar, y siempre debe citar las filas del verificador, no los límites de memoria.

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

Preguntar en tu IA favorita

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

Documentación

Verificación previa de subida (Upload Preflight)

Un renderizado que se ve bien puede ser rechazado o reprocesado: la frecuencia de cuadros incorrecta para una API, un códec de audio que una herramienta de publicación rechaza, un archivo que supera el límite de tamaño, un clip más largo de lo que la aplicación permite. Esta habilidad ejecuta https://github.com/viewgum/shortform-preflight sobre el archivo, que lo lee con ffprobe y lo compara con las cifras que cada aplicación publica, luego convierte cada fallo en un comando FFmpeg.

No es para: dónde se ubica el texto en el fotograma (usar short-form-specs), ni lo que dice el video.

Flujo de trabajo

  1. Aclarar el alcance solo si es necesario. Valores predeterminados: las cuatro aplicaciones y las reglas para subir en cada aplicación (--route app). Para la subida web de TikTok use --route web. Si el usuario publica a través de un programador o su propio código, use las reglas de la API de publicación (--api), que son más estrictas para Facebook Reels e Instagram. Para Direct Post de TikTok, pase el límite de la cuenta (max_video_post_duration_sec de la información del creador de TikTok) como --tiktok-endpoint direct --tiktok-max-seconds <n>; sin ello, indique que la duración no está verificada.
  2. Verificar las herramientas: ffprobe -version (FFmpeg), node -v (18 o más reciente) y npx --version. La primera ejecución descarga el verificador desde GitHub, por lo que también necesita acceso a la red. Si falta algo, indique qué, cómo instalarlo y deténgase.
  3. Ejecutarlo, en JSON para que pueda leer cada fila: npx -y github:viewgum/shortform-preflight <archivo> --json (añada --api, o --platform tiktok,youtube-shorts, según sea necesario). Código de salida 0 significa que ninguna verificación falló; 1 significa que una verificación falló o no se pudo leer una cifra requerida (la aplicación se muestra como incompleta; indique qué medición falta); 2 significa entrada incorrecta.
  4. Para cada fallo, y cada advertencia que el usuario probablemente encuentre, proporcione la causa en una línea, la fuente que cita la fila y una corrección. Correcciones comunes (ajuste las rutas y mantenga el resto del archivo como está):
    • Frecuencia de cuadros fuera de un rango: ffmpeg -i in.mp4 -r 30 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a copy -movflags +faststart -use_editlist 0 out.mp4
    • Códec, croma o perfil rechazados: ffmpeg -i in.mp4 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart -use_editlist 0 out.mp4
    • Átomo moov al final, o lista de edición (la API de Instagram rechaza ambos): ffmpeg -i in.mp4 -c copy -movflags +faststart -use_editlist 0 out.mp4
    • Frecuencia de muestreo de audio, canales o tasa de bits (la API de Facebook Reels lista 48 kHz estéreo, 128 kbps o más; un codificador configurado exactamente a 128k a menudo promedia un poco menos): ffmpeg -i in.mp4 -c:v copy -c:a aac -b:a 192k -ar 48000 -ac 2 -movflags +faststart -use_editlist 0 out.mp4
    • Demasiado largo: córtelo, ffmpeg -i in.mp4 -t 89.9 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart -use_editlist 0 out.mp4 (configure -t un poco por debajo del límite: el corte puede durar un fotograma de más).
    • Varias filas a la vez: combine las opciones en una sola recodificación en lugar de encadenar pasos, como en el ejemplo de ejecución.
    • Cada recodificación: añada -g 90 a 30 fps (-g 72 a 24) para que los fotogramas clave lleguen cada 3 segundos; la API de Facebook solicita grupos cerrados de imágenes de 2 a 5 segundos de duración, lo cual el verificador no puede probar. Verifique con ffprobe -v error -select_streams v -skip_frame nokey -show_entries frame=pts_time -of csv=p=0 out.mp4.
    • Demasiado grande: baje el ajuste de calidad (un -crf más alto) en lugar de la resolución.
    • No es 9:16: añada relleno o recorte a 1080 x 1920 solo si el usuario lo desea; indique qué se perderá.
  5. Después de una corrección, ejecute el verificador nuevamente sobre el nuevo archivo y muestre que la fila ahora pasa.

Formato de salida

**Archivo:** demo.mp4 · 1080 x 1920 · 95 s · 23.976 fps · H.264 · AAC
**Reglas:** APIs de publicación

| App | Resultado | Filas con fallo o advertencia |
|---|---|---|
| Facebook Reels | fallo | duración 95 s (la API admite de 3 a 90 s); frecuencia de cuadros 23.976 (necesita de 24 a 60); 44.1 kHz y mono (48 kHz estéreo listado, advertencia) |
| Instagram Reels | fallo | lista de edición presente (ninguna permitida); átomo moov después de los medios (debe estar al inicio) |

### Corrección
Una recodificación para todas las filas: `ffmpeg -i demo.mp4 -t 89.9 -r 30 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac -b:a 192k -ar 48000 -ac 2 -g 90 -movflags +faststart -use_editlist 0 fixed.mp4`
(fuentes: Meta for Developers, Reels Publishing API e IG User Media)

**Después de la corrección:** sin fallos.
  • Cite las filas propias del verificador; no repita límites de memoria.
  • Indique qué reglas se usaron: subida de aplicación, subida web o la API de publicación.
  • Las filas informativas (tasas de bits recomendadas, sonoridad medida) no son fallos; menciónelas solo si el usuario lo pide.

Errores comunes

  • No recodifique cuando un remux lo soluciona. -c copy con +faststart mantiene la calidad.
  • No cambie la resolución o relación de aspecto a menos que el usuario lo solicite; pregunte primero, porque recortar pierde imagen.
  • No trate una advertencia como un rechazo. Indique lo que la aplicación puede hacer (reprocesar, rechazar a través de la API) solo como lo establece la fuente.
  • No ejecute FFmpeg sobre el archivo original. Siempre escriba un nuevo archivo.
  • No adivine un límite que el verificador informa como no publicado. Indique que la aplicación no lo publica.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

Skills relacionados