¿Qué hace fullgrade?
Corrección de color automática y suave para video. Todo se ejecuta localmente con ffmpeg + Python; no requiere GPU, API en la nube ni casi tokens (el análisis lo realiza el script, no mirando fotogramas).
Idioma: responde en el idioma del usuario. Si el usuario escribe en chino, usa --lang zh para que el informe y las imágenes de comparación estén en chino; de lo contrario, usa --lang en.
1. Entorno (primera ejecución o cuando algo falla)
python3 <skill_dir>/scripts/fullgrade.py --check
Si falta algo, indícale al usuario el comando necesario:
| Falta | macOS | Windows | Linux |
|---|---|---|---|
| ffmpeg | brew install ffmpeg | winget install ffmpeg | sudo apt install ffmpeg |
| numpy / Pillow | python3 -m pip install numpy pillow (añade --break-system-packages si pip se niega) | ||
| face-aware crop (opcional) | python3 -m pip install opencv-python-headless |
Ejecuta el script en la máquina donde están los videos. Si los archivos se subieron a un entorno aislado (sandbox), ejecútalo allí y envía los resultados de vuelta.
En Windows usa python en lugar de python3 si python3 no se encuentra.
Opcional: python3 <skill_dir>/scripts/fullgrade.py --selftest genera metraje sintético y prueba cada función (unos 2-3 minutos). Úsalo si el usuario pregunta "¿funciona en mi computadora?".
2. Convierte la solicitud en un solo comando
python3 <skill_dir>/scripts/fullgrade.py <archivos-o-carpetas> [opciones] --lang <en|zh>
| El usuario dice… | Opción |
|---|---|
| nada sobre estilo / "solo arréglalo" / 自然 | --preset natural (predeterminado) |
| inmobiliario, interior, brillante y aireado / 房产, 明亮通透 | --preset real-estate |
| cálido, acogedor, atardecer / 温暖, 温馨 | --preset warm |
| vívido, comida, producto / 鲜艳, 美食 | --preset vivid |
| limpio, frío, moderno, tecnología / 清冷, 现代 | --preset cool-modern |
| cinematográfico, look de cine, vlog / 电影感 | --preset cinematic |
| vertical, TikTok, Reels, Shorts, 抖音, 小红书 | --ratio 9:16 |
| YouTube, apaisado / 横屏 | --ratio 16:9 |
| cuadrado / Instagram feed | --ratio 1:1 o --ratio 4:5 |
| llenar el encuadre, sin barras / 裁切 | --fit crop |
| mantener toda la imagen / 不要裁, 补边 | --fit blur |
| barras negras / blancas | --fit color --pad-color black (o white) |
| drone / DJI D-Log | --log dlog |
| Sony S-Log3 · Panasonic V-Log · iPhone Apple Log | --log slog3 · --log vlog · --log applelog |
| hacer que todo coincida con este clip / foto | --match <archivo> (--match-method mkl predeterminado; reinhard, hist) |
| hacer que todos los clips coincidan estrechamente | --match hero |
| toque más suave / no te pases / 轻一点 | --strength 0.6 |
| exportación más rápida | --fast (codificador hardware Apple / NVIDIA / Intel, con fallback automático) |
| mejor calidad | --quality best |
| incluir subcarpetas | --recursive |
| solo revisar, sin exportar | --analyze-only |
| una sola corrección para todo el archivo | --no-split |
| archivos LUT para Premiere / DaVinci / Final Cut / CapCut | apunta a <skill_dir>/luts/ (o --export-luts <carpeta>) |
Valores predeterminados que ya funcionan bien para la mayoría: --fit auto (recorta si mantiene ≥60% de la imagen, de lo contrario fondo borroso — así que 16:9 ↔ 9:16 usa fondo borroso a menos que el usuario pida recortar), --dynamic auto, --denoise auto.
No preguntes sobre la relación de aspecto a menos que el usuario la mencione — mantén la original. Pregunta solo cuando la solicitud sea realmente confusa (por ejemplo, dicen "LOG" pero no especifican la cámara).
3. Qué sucede (explícalo brevemente solo si te lo piden)
- iPhone HDR → SDR automáticamente; LOG decodificado cuando se proporciona
--log(el script advierte cuando un clip parece LOG). - Una edición terminada se divide en tomas (detección de escenas); cada toma se corrige por separado.
- Por toma: balance de blancos → niveles de negro/blanco (altas luces protegidas) → exposición dentro de una banda cómoda → contraste → saturación → aspecto preestablecido → emparejamiento opcional. Todo se hornea en una LUT 3D por toma con límites de seguridad, para que nunca se exceda.
- El brillo que varía dentro de una toma (caminar de un pasillo oscuro a una habitación iluminada) se suaviza (exposición dinámica). Las tomas muy iluminadas reciben una ligera reducción de ruido.
- El reencuadre nunca estira; el recorte inteligente sigue los rostros (si OpenCV está instalado) o el área con más detalle.
- Un clip que ya se ve bien se copia sin recodificar.
Velocidad: el procesamiento toma aproximadamente 1-3 veces la duración del video en 1080p (4K lleva más tiempo). Para archivos largos o muchos, indícale al usuario que se está ejecutando y espera; no canceles. Usa --fast si tiene prisa.
Código de salida: 0 = todo listo · 2 = algunos archivos fallaron (otros están bien — el final de la salida muestra Done: X OK, Y failed y el informe explica por qué) · 1 = no se pudo procesar nada. Siempre dile al usuario qué archivos fallaron y por qué (causas comunes: no es un video, archivo dañado, archivo solo de audio).
4. Salidas
- Videos:
<carpeta de entrada>/_graded/<nombre>_<preestablecido>[_9x16].mp4— nunca sobrescribe (añade_v2), originales intactos. _graded/compare/*_compare.jpg— imágenes de antes/después. Muéstrale al menos una al usuario._graded/fullgrade_report.html— controles deslizantes de antes/después, números y curvas para cada toma. Ofrécelo._graded/fullgrade_report.md— los mismos números en texto; léelo para escribir tu resumen.
5. Respuesta
Resumen breve en el idioma del usuario: cuántos videos, qué preestablecido/relación de aspecto, dónde están los archivos, una o dos frases sobre lo que cambió (del informe, ej. "la toma 2 estaba muy amarilla y ahora es neutra; las altas luces de la ventana se protegieron"), la(s) imagen(es) de comparación y un paso útil siguiente (otro preestablecido, una versión en 9:16, --strength si quiere un toque más suave).
Límites honestos
- Los cielos/ventanas sobreexpuestos en blanco puro no pueden recuperarse; el resto de la imagen sigue mejorando.
- El metraje muy oscuro muestra ruido al aclararse (la reducción de ruido ligera ayuda, pero no es mágica).
- La luz mezclada en una misma toma (lámpara naranja + luz diurna azul) se equilibra como un compromiso.
- Las transiciones entre dos tomas muy diferentes pueden mostrar un pequeño salto en el corte.
- D-Log M de DJI y otras curvas LOG no listadas no son compatibles en V1 — ajústalas sin
--logy usa--strength.