Communitygithub.com

top110341/ffmpeg

Edita vídeo y audio con FFmpeg local desde peticiones en lenguaje natural: cortar, recortar, unir, redimensionar/reencuadrar (9:16, 1:1), cambio de velocidad, subtítulos y leyendas (SRT/ASS, animados, karaoke), superposiciones de logotipos y texto, tercios inferiores y títulos, eliminación de silencios, sincronización multicámara y micrófono externo, normalización de volumen, HDR/Dolby Vision a SDR, LUTs, música de fondo con ducking, exportaciones para plataformas (YouTube, Reels, TikTok, X), verificaciones de cumplimiento, detección de escenas y resúmenes destacados, hojas de contacto para inspeccionar resultados y archivos de proyecto completos.

¿Qué es ffmpeg?

Este skill proporciona un conjunto completo de 42 scripts Python que envuelven FFmpeg, permitiendo a un agente de IA (como Claude Code) realizar edición profesional de video y audio exclusivamente a través de scripts verificados, sin invocar FFmpeg directamente. Cubre todo el flujo de trabajo: desde sondear archivos (probe.py), cortar y unir (cut.py, join.py), hasta corrección de color (color.py), subtitulado (caption.py, subtitle.py), eliminación de silencios (silence.py), ajuste de aspecto (fit.py), sincronización de audio externo (sync.py), detección de escenas (scenes.py), y generación de resúmenes. Cada script acepta argumentos compartidos como --dry-run, --json (para salida estructurada) y --fast para vista previa. El skill está diseñado para ser invocado por un agente de planificación que decide qué script ejecutar basándose en una tabla de decisiones; el agente no debe improvisar comandos raw ffmpeg. Todo el procesamiento es local (Python 3.9, sin dependencias externas ni API keys) y los archivos originales nunca se sobrescriben. Incluye herramientas de verificación (check.py, look.py) que validan que el resultado cumple con la solicitud y generan hojas de contacto visuales cuando la imagen cambia. El skill prioriza la edición sin pérdida (stream copy) cuando es posible, y recomienda cadenas de múltiples pasos mediante render.py con un archivo project.json para evitar recodificaciones innecesarias. Está pensado para flujos de trabajo de producción de video social (Reels, TikTok, YouTube Shorts) con control total sobre codecs (h264, hevc, av1, prores), calidad y cumplimiento de normas de plataforma (LUFS, tamaño, relación de aspecto).

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/top110341/ffmpeg/tree/HEAD/.claude/skills/ffmpeg-skill

Preguntar en tu IA favorita

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

Documentación

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)

  1. Entorno, solo en caso de fallo. Nunca empieces un trabajo con doctor: una máquina rota falla con kind: missing_tool o un error de ffmpeg que nombra el filtro/codificador. Ejecuta python3 <skill-dir>/scripts/_contract.py doctor (o npx ffmpeg-skill doctor) después de tal fallo, o cuando te pregunten qué puede hacer la máquina: lee ok/usable, informa de la capacidad faltante. El esquema de herramienta de contract --json es para un agente planificador, no para este flujo de trabajo.
  2. Sondea lo que necesitas planificar. Ejecuta probe.py en 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 --json de cada herramienta de escritura ya lleva su entrada y un sondeo de la salida. Planifica a partir de números reales, nunca suposiciones.
  3. Prefiere sin pérdida. Si la solicitud se puede cumplir sin recodificar (cortes simples en keyframes, remuxing, cambios solo de audio), no recodifiques. cut.py y loudness.py copian el flujo de video por defecto; --accurate en cut.py solo para cortes exactos por fotograma.
  4. 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. --fast es calidad de vista previa, --progress imprime porcentaje/ETA en stderr. Nunca apuntes -o a un archivo que no creaste en este trabajo a menos que el usuario haya pedido que se reemplace; pasa --overwrite solo entonces.
  5. 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.py al final. Tres o más pasos: render.py con un project.json.
  6. Verifica el entregable. Antes de informar, ejecuta check.py SALIDA --platform X para 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.
  7. Verifica la salida. Confirma que la duración, resolución, fps y audio coinciden con la solicitud, a partir del sondeo de --json/--json-brief de la herramienta de escritura o probe.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.
  8. 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); --overwrite es la única forma de decir "sí, reemplázalo".
  9. Mira la imagen. Siempre que la imagen cambie (subtítulos, superposiciones, gráficos, recorte/relleno, cambio de tamaño, color, transiciones, un join.py escalando un clip al fotograma del primer clip, color.py --to-sdr) ejecuta look.py SALIDA --tiles 3x2 (o --at T para un fotograma) y visualiza el PNG (4x3 para el diseño completo del clip). No termines hasta que Look: 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 de check.py en 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 pad es 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.

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: --transcribe si 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.json una vez, reutilízalo.
  • Texto CJK / no latino: deja que la herramienta elija la fuente por escritura (--font lo desactiva); --lang ja|ko para texto solo Han. doctor --json .fonts.scripts dice 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 --highlights clasifica 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 a color.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 1 a 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 diceHaz 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)

  1. Nunca invoques ffmpeg/ffprobe directamente — solo scripts/*.py. Romper todas las garantías. Sin excusa.
  2. --start/--end en cut.py son no inclusivos — --start 30 --end 60 da exactamente 30 s.
  3. 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.
  4. --overwrite solo cuando el usuario diga "reemplázalo"; rechazar salidas existentes por defecto.
  5. Texto tofu es un trabajo fallido — ejecutar doctor y mencionar la escritura faltante; pedir la fuente.
  6. La salida de --json es la verdad, no la salida estándar — analizarla, no la línea de estado legible por humanos.
  7. --fast es para vista previa, no para entrega — CRF 18 por defecto en calidad completa.
  8. Nunca prolongues ni acortes el texto de los subtítulos — ofrecer --max-lines o tamaño más pequeño.
  9. Siempre encadenar en el orden: color → corte → unión → silencio → ajuste → subtítulo → superposición → sincronización → audio → volumen → exportación.
  10. Tres o más pasos de edición: usar render.py --project, no una cadena manual. Exportación única: render.py --template.

Skills relacionados