ffmpeg-skill
Los scripts viven en scripts/ junto a este archivo; ejecútalos con python3 <skill-dir>/scripts/<name>.py, y las plantillas de entrega en templates/. Este archivo es suficiente para hacer un trabajo: la tabla de abajo enruta la solicitud, y --help en el script a punto de ejecutarse es la lista de banderas completa más económica. Un archivo de referencia cuesta lo mismo que este; ábrelo solo para una pregunta que tengas: references/scripts.md (todas las banderas de los 42 scripts), references/devices.md (iPhone HDR, GoPro, DJI, grabaciones de pantalla, Zoom), references/gotchas.md (la versión larga de las reglas de una línea al final). MCP: tools/list muestra solo los 12 principales por defecto; los otros 30 (según esta tabla) se pueden llamar por nombre mediante tools/call, descritos por contract --json; establece FFMPEG_SKILL_MCP_FULL=1 para los 42.
Banderas compartidas, en cada script: --dry-run; --json (ruta de salida, un sondeo de la salida, los comandos ejecutados); --json-brief (estado/salida/verificado más un summary; preferir en pasos de escritura); --fast (calidad de vista previa); --progress; --timeout SEGUNDOS (kind: timeout, por defecto 1800); --overwrite (paso 7); --plan ARCHIVO (la ejecución en seco como un plan que render.py ARCHIVO ejecutará después; se rechaza si una entrada cambió). Las herramientas de recodificación también toman --codec h264|hevc|av1|prores y --quality N: sin configurar, SDR es x264, HDR es x265 Main10; prores necesita -o NOMBRE.mov, h264 rechaza HDR (color.py --to-sdr primero).
Las herramientas de escritura no ejecutan nada bajo --dry-run; las herramientas de medición (probe, check, sync, multicam, scenes, cropdetect, report, silence, loudness, stabilize) pueden ejecutar ffmpeg/ffprobe de todas formas, omitiendo artefactos/archivos secundarios (--edl, --sheet, un .ass generado); verify ignora la bandera. Por herramienta: contract --json dry_run.
Flujo de trabajo (en este orden)
- Entorno, solo en caso de fallo. Nunca empieces un trabajo con
doctor: una máquina rota falla conkind: missing_toolo un error de ffmpeg que nombra el filtro/codificador. Ejecutapython3 <skill-dir>/scripts/_contract.py doctor(onpx ffmpeg-skill doctor) después de tal fallo, o cuando te pregunten qué puede hacer la máquina: leeok/usable, informa de la capacidad faltante. El esquema de herramienta decontract --jsones para un agente planificador, no para este flujo de trabajo. - Sondea lo que necesitas planificar. Ejecuta
probe.pyen cada entrada desde la que planees: duración, fps, resolución, códecs, canales,variable_frame_rate_suspected— y cada vez que el usuario pregunte sobre un archivo. No hay sondeo separado antes de cada edición: el--jsonde cada herramienta de escritura ya lleva su entrada y un sondeo de la salida. Planifica a partir de números reales, nunca suposiciones. - Prefiere sin pérdida. Si la solicitud se puede cumplir sin recodificar (cortes simples en keyframes, remuxing, cambios solo de audio), no recodifiques.
cut.pyyloudness.pycopian el flujo de video por defecto;--accurateencut.pysolo para cortes exactos por fotograma. - Planifica con
--dry-run --json, luego ejecuta. Confía en--json, no en la línea de resumen de una ejecución en seco, para cualquier número en el plan (una dimensión allí puede ser un marcador de posición). Úsalo antes de codificaciones largas, para informar hechos.--fastes calidad de vista previa,--progressimprime porcentaje/ETA en stderr. Nunca apuntes-oa un archivo que no creaste en este trabajo a menos que el usuario haya pedido que se reemplace; pasa--overwritesolo entonces. - Encadena en un orden sensato. Una solicitud de entrega sin otra edición es una ejecución de plantilla (
render.py --template NOMBRE ENTRADA), no una cadena hecha a mano. De lo contrario: color (HDR→SDR / LUT) → corte → unión → silencio → ajuste → subtítulo/superposición → sincronización → audio → volumen → exportación. Cambios de fotograma antes que los subtítulos, para que el texto tenga el tamaño del fotograma final. Recodifica lo menos posible: intermedios a CRF 18,export.pyal final. Tres o más pasos:render.pycon un project.json. - Verifica el entregable. Antes de informar, ejecuta
check.py SALIDA --platform Xpara el destino nombrado (una ejecución de plantilla ya lo hace). Las filas de formato (códec, formato de píxel, tamaño, pico verdadero, etiquetas de color, VFR) son seguras de corregir. Las filas de juicio cambian el contenido: duración (el corte pierde material), aspecto (el recorte pierde bordes), fps (pierde movimiento), volumen (la ambiencia no debe amplificarse) — corrige solo cuando la solicitud implique la respuesta, si no, indica la elección y su costo. Menciona las ADVERTENCIAS; no las persigas. - Verifica la salida. Confirma que la duración, resolución, fps y audio coinciden con la solicitud, a partir del sondeo de
--json/--json-briefde la herramienta de escritura oprobe.py, e informa esos números ("final.mp4: 59.98 s, 1080x1920, 30 fps, AAC estéreo"). Un paso está completo solo cuando el script salió con 0 y la salida sondea según lo esperado: una salida distinta de cero, un archivo faltante o vacío, o un sondeo que contradice la solicitud es un fallo informado con el mensaje de error del script. - Conserva los originales del usuario. Nunca sobrescribas la fuente; escribe archivos nuevos junto a la entrada o donde se pida. Una ruta de salida existente se rechaza (
kind: input);--overwritees la única forma de decir "sí, reemplázalo". - Mira la imagen. Siempre que la imagen cambie (subtítulos, superposiciones, gráficos, recorte/relleno, cambio de tamaño, color, transiciones, un
join.pyescalando un clip al fotograma del primer clip,color.py --to-sdr) ejecutalook.py SALIDA --tiles 3x2(o--at Tpara un fotograma) y visualiza el PNG (4x3 para el diseño completo del clip). No termines hasta queLook:nombre ese PNG — un sondeo no puede ver un subtítulo sobre una cara. Solo audio:Look: not needed. Qué buscar se divide como las filas decheck.pyen el paso 5:- Mecánico (trabajo propio de este skill para verificar e informar): el texto/logotipo especificado está en la posición especificada, los subtítulos aparecen en las marcas de tiempo especificadas, las dimensiones son pares. El letterboxing de
fit.py --fit pades el resultado correcto de ese modo, nunca un defecto que marcar. - Juicio (infórmalo, no lo pases o falles en silencio): si un sujeto o cara está cortado, el texto se superpone a una cara, los colores se ven desteñidos, una transición aterriza. Estos necesitan decidir qué es el sujeto, es decisión del agente que llama — di lo que ves en una línea; ellos juzgan.
Sin capacidad de visión, escribe
Look: RUTA (píxeles no inspeccionados; el agente no tiene vista de imagen)— nunca afirmes que se inspeccionó una imagen cuando no fue así, sin detenerte por una capacidad que no existe.
- Mecánico (trabajo propio de este skill para verificar e informar): el texto/logotipo especificado está en la posición especificada, los subtítulos aparecen en las marcas de tiempo especificadas, las dimensiones son pares. El letterboxing de
Antes de ejecutar nada: qué preguntar, qué asumir
Haz una pregunta corta solo cuando la respuesta cambie materialmente la salida y la solicitud no la implique. Cuando varias cosas estén abiertas a la vez (un vago "hazlo para redes sociales" deja destino, aspecto, duración y subtítulos abiertos), no preguntes una por turno: propón un paquete con tus valores por defecto y deja que el usuario cambie cualquier parte ("Reels: 9:16 con relleno, 60 s, -14 LUFS, sin subtítulos — ¿OK?"). Una pregunta, una respuesta, luego la ejecución. Nunca preguntes por lo que probe.py puede decirte.
- Destino decide aspecto, límite de duración, volumen y códec; "para Reels" responde a las cuatro cosas y nombra una plantilla. Sin destino y un corte/subtítulo simple: mantén el formato de origen y dilo. Si el usuario dice "exportar", "publicar" o "entregar", pregunta dónde.
- Duración ("hazlo de 60 s") sin un método: acelera para cambios ≤1.5×, recorta en caso contrario, di cuál. Pregunta cuando el contenido sea una charla (recortar pierde palabras) y el cambio sea grande.
- Subtítulos sin una fuente de texto:
--transcribesi existe un whisper local, si no pide el texto o un archivo temporizado; nunca inventes diálogo. - Fuentes y marca: si el usuario menciona una marca, colores o "nuestra fuente", pide o crea
brand.jsonuna vez, reutilízalo. - Texto CJK / no latino: deja que la herramienta elija la fuente por escritura (
--fontlo desactiva);--lang ja|kopara texto solo Han.doctor --json.fonts.scriptsdice qué se renderiza aquí. Tofu es un trabajo fallido. - Posición de recorte para
--fit crop: centro por defecto, pero cuando la solicitud o la fuente nombre un sujeto descentrado ("mantén el producto a la derecha", alguien visiblemente descentrado en la hoja) usa--crop-x/--crop-y(0=izquierda/arriba, 1=derecha/abajo) en lugar de adivinar el centro, o pregunta qué borde mantener. - Cualquier otra cosa (tipo de transición, estilo de subtítulo): elige el valor predeterminado convencional, di lo que elegiste, ofrece la alternativa en una línea.
Qué decide y qué no decide este skill
Este skill corta, une, mide, sincroniza, exporta y verifica archivos — ejecuta una edición, no la decide. Lo que pertenece al humano, al agente que llama o a otro skill:
- Qué corte es el correcto, o si un entregable es aprobable — este skill mide e informa (
check.py's PASS/WARN/FAIL,cut.py's error de duración); el usuario o el agente de producción decide si eso se envía. - Qué hace que un momento destacado sea interesante —
scenes.py --highlightsclasifica por una medida proxy (energía de audio, duración): candidatos, no un veredicto. - Composición de miniatura o portada — una decisión de diseño, no una medida.
- Entender de qué trata un video — no hay visión aquí más allá de las hojas de contacto de
look.py, para los ojos del agente que llama, no para que este skill lo interprete. - Juzgar qué se ve bien — "aplicar este LUT", "corregir exposición en +0.3 pasos" (
color.py) es mecánico; "etiquetar esta escena para que se vea cinematográfica" pertenece a un skill de etiquetado de color (color-grading-skill) que decide los parámetros, luego llama acolor.py. - Las palabras en un subtítulo — el texto de la señal se quema tal como está escrito. Demasiado largo para el fotograma significa un tamaño más pequeño,
--max-lines, o la edición del propio usuario; nunca reescribas, acortes o parafrasees, incluso cuando te pidan "hacer que quepa" — dilo, ofrece--max-lines 1a un tamaño más pequeño. - Elegir un sujeto o región que no te fue dada — "recortar a x=200,y=0" es mecánico una vez que se conoce el cuadro; "recortar para mantener al hablante en el encuadre" necesita decidir qué es el hablante, un juicio para el agente que llama (a partir de una hoja de
look.py).
La línea: la misma entrada + los mismos parámetros explícitos que siempre producen la misma salida verificable pertenece aquí; cualquier cosa que dependa del gusto, la comprensión o de lo que se ve o suena bien pertenece a quien hace ese juicio.
Si una solicitud necesita una característica de FFmpeg que ninguno de los 42 scripts expone, dilo y nombra la opción integrada más cercana — nunca adivines una invocación raw de ffmpeg/ffprobe fuera de scripts/*.py. Eso elude todas las garantías que este skill ofrece, así que nunca es un recurso de respaldo cuando la bandera de un script no cubre algo.
Solicitud → script
Esta tabla y la lista tools de doctor --json son la fuente de verdad de lo que existe: nombra solo un script que hayas visto en una de ellas (no hay doctor.py, no hay trim.py, no hay subtitle.py).
Las banderas de marca de tiempo (--start, --end, --at, --from, --duration, --offset, y los tiempos en archivos de señal y capítulo) toman segundos, mm:ss(.fff), hh:mm:ss(.fff) o SMPTE hh:mm:ss:ff con @fps (00:01:02:[email protected]) — pega una hoja de señal NLE tal cual; las banderas de duración (--min-silence, --margin, --fade) son segundos simples.
| El usuario dice | Haz esto |
|---|---|
| "cortar de 1:20 a 2:05", "recortar los primeros 10 s" | cut.py entrada.mp4 --start 1:20 --end 2:05 |
| "conservar solo estas partes", "quitar el medio" | cut.py entrada.mp4 --segments 0-1:00,1:30-2:00 |
| "hazlo exactamente de 60 segundos" | fit.py entrada.mp4 --duration 60 (velocidad) o --method trim |
| "cortar esto y hacerlo HEVC / AV1 / ProRes" (códec de salida nombrado) | cut.py entrada.mp4 --start 0:10 --end 0:40 --codec hevc (--codec/--quality en cualquier herramienta de recodificación; ProRes necesita -o NOMBRE.mov) |
| "quitar las pausas", "cortes rápidos" | silence.py entrada.mp4 [--threshold -40 --min-silence 0.8] |
| "quitar los eeeh y aaaaah", "eliminar las palabras de relleno" | silence.py entrada.mp4 --filler --words words.json (tiempos de palabras medidos; --transcribe los crea) |
| "no cortar dentro de una oración, solo las pausas reales" | silence.py entrada.mp4 --speech-aware — una respiración bajo --min-silence dentro de una oración se conserva, solo se cortan las pausas en los límites de oración; se combina con --filler en una lista |
| "un resumen de 60 s de esta hora" | scenes.py largo.mp4 --highlights 6 --target 60 --edl picks.txt → cut.py --segments |
| "cortar al ritmo", "editarlo con la música" | scenes.py pista.mp4 --beats --json > beats.json, luego cut.py entrada.mp4 --segments ... --snap beats --snap-source beats.json (--snap-source lleva la cuadrícula medida) |
| "acelerar aquí, cámara lenta allí" (segmentos conocidos) | speedramp.py accion.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0 |
| "mantener este fotograma", "congelar el último fotograma" | freeze.py clip.mp4 --hold 2 |
| "cámara lenta suave", "media velocidad pero fluida" | fit.py entrada.mp4 --duration 2x --smooth interpolate (lenta) o --smooth blend |
| "invertir este clip" | reverse.py entrada.mp4 |
| "repetir este clip para llenar 30 segundos" | loop.py bg_loop.mp4 --duration 30 |
| "hacerlo vertical / 9:16 / cuadrado" | fit.py entrada.mp4 --aspect 9:16 --fit pad (o --fit crop; --pad-fill blur para barras borrosas) |
| "redimensionar a una altura/anchura" | fit.py entrada.mp4 --height 1080 (o --width, o ambos para un fotograma exacto) |
| "recortar a este cuadro exacto" (x/y/w/h conocidos) | crop.py entrada.mp4 --x 100 --y 0 --width 1080 --height 1920 |
| "fondo borroso en lugar de barras negras" | fit.py entrada.mp4 --aspect 9:16 --fit blur (imagen completa conservada, bordes una copia borrosa y oscurecida) |
| "rotar 90 grados", "espejarlo" | fit.py entrada.mp4 --rotate 90 / fit.py entrada.mp4 --flip h |
| "el horizonte está inclinado" (grados conocidos) | straighten.py inclinado.mp4 --degrees -2.5 |
| "vista plana de este video 360" (yaw/pitch/fov conocidos) | sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70 |
| "este metraje antiguo está entrelazado" | deinterlace.py entrada.mp4 |
| "es granuloso/ruidoso, límpialo" | denoise.py entrada.mp4 --strength medium |
| "desenfocar/pixelar esta cara/placa" (cuadro conocido) | redact.py entrada.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate |
| "estabilizar este metraje tembloroso" | stabilize.py entrada.mp4 |
| "¿hay barras negras en esto?" | cropdetect.py entrada.mp4 |
| "el clip Dolby Vision de iPhone se ve mal" | color.py clip.mov --to-sdr o --strip-dovi (mantener HDR, eliminar la capa DV) |
| "los colores se ven desteñidos / iPhone HDR" | color.py entrada.mp4 --tonemap hable (o mobius, reinhard; doctor --json .tonemap dice qué acelera aquí) |
| "aplicar este LUT" (un archivo .cube) | color.py entrada.mp4 --lut correction.cube |
| "hacerlo más brillante/oscurito/frío/cálido" (ajuste conocido) | color.py entrada.mp4 --brightness 0.1 / --contrast 1.2 / --saturation 0.8 / --gamma 1.5 / --temperature -500 |
| "parece una película de los 80", "darle un aspecto vintage" | color.py entrada.mp4 --lut retro.cube (no adivines LUTs que no existen) |
| "normalizar el audio", "hacerlo -14 LUFS" | loudness.py entrada.mp4 --lufs -14 |
| "que suene más fuerte" | loudness.py entrada.mp4 --gain 3 |
| "limitar el pico a -1 dB" | loudness.py entrada.mp4 --true-peak -1 |
| "agregar música de fondo, que se atenúe cuando hablen" | audio.py entrada.mp4 --bg bgm.mp3 --duck speech --duck-threshold -24 |
| "mezclar estas pistas de audio" (dos archivos) | audio.py entrada.mp4 --mix narracion.wav --mix-level 0.5 |
| "reemplazar el audio con este archivo" | audio.py entrada.mp4 --replace nueva.wav |
| "agregar una cuenta atrás de 3, 2, 1" (sin un archivo de cuenta atrás) | audio.py entrada.mp4 --countdown (genera los pitidos) |
| "sincronizar con audio de micrófono externo" (archivo de audio separado) | sync.py grabacion.mp4 externo.wav |
| "tengo tres tomas, sincronizarlas" | multicam.py toma1.mp4 toma2.mp4 toma3.mp4 |
| "sincronizar por código de tiempo" (cámaras con código de tiempo) | multicam.py toma1.mp4 toma2.mp4 --method timecode |
| "unir estos clips", "ponerlos juntos" (en orden) | join.py parte1.mp4 parte2.mp4 parte3.mp4 |
| "agregar una transición de fundido entre ellos" | join.py clip1.mp4 clip2.mp4 --transition fade --transition-duration 1 |
| "poner esto encima de otro video", "PIP" (cuadros conocidos) | overlay.py base.mp4 superposicion.mp4 --x 100 --y 100 --scale 0.3 |
| "agregar un logotipo en la esquina" | overlay.py entrada.mp4 logo.png --x left --y top --margin 20 --scale 0.15 --duration full |
| "agregar texto en la parte inferior" | caption.py entrada.mp4 --text "Hola mundo" |
| "agregar un tercio inferior" | caption.py entrada.mp4 --text "Nombre" --subtitle "Título" --lower-third |
| "agregar subtítulos desde un archivo SRT" | subtitle.py entrada.mp4 subtitulos.srt |
| "agregar subtítulos animados / tipo karaoke" | subtitle.py entrada.mp4 subtitulos.ass --anim karaoke |
| "agregar subtítulos con burbujas de estilo TikTok" | subtitle.py entrada.mp4 subtitulos.srt --style tiktok |
| "transcribir y poner subtítulos automáticos" | caption.py entrada.mp4 --transcribe (solo si hay un modelo whisper local; si no, pide el texto) |
| "agregar una barra de progreso" | progress.py entrada.mp4 |
| "hacer un GIF de esta parte" | gif.py entrada.mp4 --start 0:05 --duration 3 |
| "hacer una hoja de contacto" (vista general) | look.py escena.mp4 --tiles 4x3 |
| "¿cuántas escenas tiene?" | scenes.py entrada.mp4 --json (no --edl) |
| "¿cuál es el pico verdadero / LUFS integrado?" | loudness.py entrada.mp4 --json-brief |
| "verificar si esto es correcto para YouTube" | check.py entrada.mp4 --platform youtube |
| "crear un proyecto de render" (edición compleja) | Define todos los pasos en un JSON, luego render.py --project proyecto.json |
| "reparar metadatos", "hacer que funcione en este editor" | report.py entrada.mp4 --fix (corrige marcas de tiempo rotas y banderas que los NLE rechazan) |
| "¿qué puede hacer esta máquina?" / "falta un códec" | Ejecuta python3 <skill-dir>/scripts/_contract.py doctor (o npx ffmpeg-skill doctor), no improvises |
Reglas de una línea (la versión larga en references/gotchas.md)
- Nunca invoques ffmpeg/ffprobe directamente — solo
scripts/*.py. Romper todas las garantías. Sin excusa. --start/--endencut.pyson no inclusivos —--start 30 --end 60da exactamente 30 s.- Nunca pongas la imagen fotograma a fotograma en un plan — un sondeo de dimensiones puede contener
None; el comando real lo sustituirá, el que esté planificando no debe fingir que lo sabe. --overwritesolo cuando el usuario diga "reemplázalo"; rechazar salidas existentes por defecto.- Texto tofu es un trabajo fallido — ejecutar
doctory mencionar la escritura faltante; pedir la fuente. - La salida de
--jsones la verdad, no la salida estándar — analizarla, no la línea de estado legible por humanos. --fastes para vista previa, no para entrega — CRF 18 por defecto en calidad completa.- Nunca prolongues ni acortes el texto de los subtítulos — ofrecer
--max-lineso tamaño más pequeño. - Siempre encadenar en el orden: color → corte → unión → silencio → ajuste → subtítulo → superposición → sincronización → audio → volumen → exportación.
- Tres o más pasos de edición: usar
render.py --project, no una cadena manual. Exportación única:render.py --template.