Guía Completa de fqmpeg: 157 Comandos para Domar FFmpeg

fqmpeg es un wrapper CLI escrito en Node.js que convierte 157 tareas comunes de FFmpeg en comandos de un solo verbo como compress, gif, hls o audio. Se instala con npm install -g fqmpeg, mantiene tu instalación de FFmpeg existente y elimina la necesidad de buscar la sintaxis de filtros en Google cada vez que quieres generar una miniatura. La última versión en npm es 3.0.1 (publicada el 2026-05-10), y trae un único dependency en runtime (Commander) además de un validador de entrada estricto que rechaza flags incorrectas antes de invocar a FFmpeg.

Esta guía es el punto de entrada al cluster fqmpeg de 32blog. Cubre qué es fqmpeg, por qué tiene sentido un wrapper sobre FFmpeg, cómo instalarlo, los cuatro comandos de inspección integrados y un mapa por categorías de los 157 comandos para que encuentres el verbo que necesitas sin escarbar.

Lo que vas a obtener de esta guía

• Un modelo mental claro de cómo fqmpeg organiza 157 comandos
• Instrucciones de instalación (Windows, macOS, Linux vía npm)
• Los cuatro verbos de inspección que se documentan aquí mismo
• Un mapa completo agrupado en 12 clusters temáticos
• Cómo --dry-run funciona como chuleta de FFmpeg

¿Qué es fqmpeg?

fqmpeg es un CLI open source distribuido en npm como fqmpeg (código fuente: github.com/omitsu-dev/fqmpeg, licencia MIT). Es un wrapper fino en Node.js sobre los binarios ffmpeg y ffprobe que ya tienes en tu PATH.

Cada comando se mapea a una tarea concreta que quieres hacer — no a una flag de FFmpeg. Así que en lugar de memorizar esto:

ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -movflags +faststart output.mp4

escribes esto:

npx fqmpeg compress input.mp4

También obtienes:

• Validación estricta de entrada. Los valores incorrectos (CRF fuera de rango, preset desconocido, argumento faltante) se rechazan con un mensaje legible antes de que FFmpeg arranque. Se acabó descifrar errores crípticos de FFmpeg.
• Nombres de salida automáticos. No hace falta flag -o — input.mp4 se convierte en input-compressed.mp4, input-gif.gif o input-tagged.mp4 según el verbo.
• --dry-run en cada comando. Imprime la invocación de FFmpeg sin ejecutarla, así puedes copiarla, aprenderla o pegarla en un script de CI.
• --help en cada comando. Muestra argumentos, opciones, valores por defecto y rangos. No tienes que memorizar 157 comandos — --help te lo cuenta.

No hay sub-módulos, ni plugins, ni archivos de configuración. Instalas un paquete y obtienes 157 verbos.

¿Por qué un wrapper CLI en lugar de FFmpeg directo?

FFmpeg es la herramienta multimedia más potente que existe, pero su superficie CLI es enorme. La documentación oficial ffmpeg-all.html supera los 4 MB de texto plano. Los grafos de filtros usan una micro-sintaxis encadenada. La selección de streams usa otra sintaxis aparte. La mayoría de ingenieros de vídeo en activo no memorizan FFmpeg — mantienen una carpeta de recetas y pestañas de Stack Overflow.

Un wrapper aporta tres ventajas concretas:

1. Descubribilidad. fqmpeg --help lista todos los verbos. Una vez sabes el verbo, fqmpeg <verbo> --help muestra las opciones. Nunca tienes que averiguar qué filtro maneja tu tarea.
2. Validación por adelantado. FFmpeg acepta casi cualquier string para casi cualquier flag y falla en lo profundo del pipeline con mensajes tipo Error initializing filter 'palettegen' with args ''. fqmpeg detecta --crf 999 o --preset turbofast antes de que FFmpeg arranque.
3. Defaults que coinciden con la intención común. compress usa por defecto CRF 23, preset medium, audio AAC y faststart — lo que la mayoría quiere cuando dice "comprime esto". Anula sólo lo que te importe.

El contraargumento clásico es "aprende FFmpeg y ya". Es válido para ingenieros de vídeo a tiempo completo. Para todos los demás (developers que entregan una feature, creadores que procesan uploads en lote, devops que escriben un pipeline) el wrapper ahorra tiempo real sin esconder lo que pasa — --dry-run siempre muestra el comando subyacente, así que puedes graduarte a FFmpeg directo cuando quieras.

Si dudas entre un wrapper CLI, una app GUI tipo HandBrake y escribir FFmpeg a mano, la comparación FFmpeg vs alternativas GUI cubre los trade-offs generales. fqmpeg está en el bando CLI y cambia la clicabilidad del GUI por la facilidad de batch y la reproducibilidad.

Instalación

Necesitas dos cosas: Node.js (≥18) y FFmpeg.

Paso 1 — instala FFmpeg. Sáltate este paso si ya lo tienes (ffmpeg -version muestra el banner). Si no, sigue la guía de instalación de FFmpeg.

Paso 2 — instala fqmpeg. Elige una opción:

# Instalación global
npm install -g fqmpeg

# O ejecuta sobre la marcha sin instalar
npx fqmpeg compress input.mp4

Las dos funcionan. npx es cómodo para uso puntual; la instalación global es más rápida en invocaciones repetidas porque npm no recupera metadatos cada vez.

Paso 3 — verifica.

fqmpeg --version
# 3.0.1

fqmpeg --help
# (lista cada verbo con una descripción de una línea)

Si fqmpeg --version imprime 3.0.1 y ffmpeg -version imprime el banner de FFmpeg, ya está.

El patrón verbo: cómo piensa fqmpeg

Cada comando sigue la misma forma:

fqmpeg <verbo> <input> [opciones]

El verbo es la acción que quieres. El input es tu archivo de medios. Las opciones afinan el comportamiento, y la mayoría tiene defaults razonables. No hay configuración global, ni perfiles, ni encadenamientos — cada comando es una operación.

Tres ejemplos concretos:

# "Hacer un GIF de 3 segundos empezando en el segundo 10"
npx fqmpeg gif input.mp4 -s 10 -d 3

# "Recortar desde el segundo 30 durante 10 segundos"
npx fqmpeg trim input.mp4 -s 30 -d 10

# "Apilar dos vídeos lado a lado"
npx fqmpeg stack izquierdo.mp4 derecho.mp4

Si olvidas las opciones, añade --help:

npx fqmpeg gif --help
# Usage: fqmpeg gif [options] <input>
# Options:
#   -s, --start <seconds>     Tiempo inicial en segundos (default: 0)
#   -d, --duration <seconds>  Duración en segundos (default: 3)
#   --fps <n>                 Frames por segundo (default: 15)
#   --width <px>              Ancho de salida (default: 480)
#   ...

Si pasas un valor incorrecto, te lo dice fqmpeg en lugar de FFmpeg:

npx fqmpeg compress input.mp4 --crf 999
# error: option '--crf' argument: crf must be between 0 and 51, got "999".

Esa es toda la interfaz. No hay un segundo modo, no hay un DSL que aprender.

Comandos de inspección (integrados)

Cuatro verbos son utilidades de inspección / metadatos. No tienen un artículo de profundidad propio porque son pequeños, autocontenidos y conviene documentarlos junto a las instrucciones de instalación.

info — volcado completo de ffprobe en JSON

npx fqmpeg info input.mp4

Envuelve ffprobe -v quiet -print_format json -show_format -show_streams. Úsalo cuando necesites inspeccionar codec, resolución, framerate, bitrate, layout de canales o cualquier otra propiedad multimedia de forma programática.

# Pipea a jq para sacar sólo el stream de vídeo
npx fqmpeg info input.mp4 | jq '.streams[] | select(.codec_type=="video")'

duration — sólo la duración, en HH:MM:SS

npx fqmpeg duration input.mp4
# 0:01:23.456000

Envuelve ffprobe -show_entries format=duration -of csv=p=0 -sexagesimal. Útil dentro de scripts cuando necesitas tomar una decisión basada en la duración sin parsear el JSON completo de info.

metadata — escribe tags en el contenedor

npx fqmpeg metadata input.mp4 \
  --title "Episodio 12" \
  --artist "32blog" \
  --year 2026

Establece metadatos a nivel de contenedor (title, artist, album, year, comment, genre) usando -c copy para que no haya re-codificación. La salida por defecto es input-tagged.mp4. Funciona también con audio — útil para etiquetar lotes de MP3 antes de subirlos a un host de podcast.

embed-thumbnail — adjunta una imagen de portada

npx fqmpeg embed-thumbnail input.mp3 cover.jpg

Embebe un JPG/PNG como imagen adjunta (disposition: attached_pic). La mayoría de reproductores de música y el Finder de macOS la mostrarán como carátula. El stream de vídeo se copia sin recodificar, así que es una operación rápida incluso en archivos largos.

Para los 153 comandos restantes, salta al cluster relevante de abajo.

Los 12 clusters temáticos (157 comandos de un vistazo)

Los 157 comandos se ordenan limpiamente en 12 clusters orientados a tareas. Cada cluster tendrá eventualmente su propio artículo de profundidad en 32blog — pero todos los comandos listados abajo ya están en fqmpeg@3.0.1 y fqmpeg <comando> --help documenta las opciones de cada uno.

C1 — Compresión y codificación (7)

compress, encode-av1, encode-h265, encode-vp9, encode-prores, encode-dnxhd, bitrate

Elección de códec y control de bitrate. compress es el default de H.264; la familia encode-* apunta a códecs específicos (AV1 para streaming, H.265 para archivo, ProRes/DNxHR para edición). Para profundizar en códecs, ver AV1 vs H.265 vs H.264 y la guía de compresión de vídeo. Leer más — guía completa de compresión y codificación con fqmpeg →

C2 — Conversión de formato y streaming (7)

convert, gif, gif-to-video, hls, dash, segment, extract-stream

Cambios de contenedor (mp4 ↔ mov ↔ webm), entrada/salida de GIF, segmentación HLS / DASH para streaming adaptativo y extracción de streams por índice. Para un pipeline HLS de extremo a extremo incluyendo CDN, ver la guía de streaming HLS con CDN. Leer más — guía completa de conversión de formato y streaming con fqmpeg →

C3 — Subtítulos (4)

subtitle, subtitle-burn, extract-subtitle, sidecar

Subtítulos blandos, quemados (hardcoded), extracción como .srt o sidecar como pista seleccionable. Si necesitas generar subtítulos automáticamente primero, ver FFmpeg + Whisper subtítulos automáticos. Leer más — guía completa de subtítulos con fqmpeg →

C4 — Edición: trim, velocidad, concat, frames (15)

trim, split, concat, loop, reverse, speed, boomerang, crossfade, fade, fade-between, freeze, repeat-frame, frame-step, interpolate, fps

Operaciones en el eje temporal. concat se salta el baile del archivo temporal. speed se encarga de las matemáticas con setpts / atempo (incluyendo el encadenamiento de atempo para >2x). Para el equivalente lossless de trim, ver corte sin pérdida con FFmpeg. Leer más — fqmpeg edición en profundidad →

C5 — Redimensionar, recortar y rotar (14)

resize, scale2x, crop, crop-detect, pad, rotate, transpose, mirror, aspect, zoom, field-order, interlace, deinterlace, backdrop

Geometría. backdrop añade un fondo difuminado a un vídeo vertical para que llene 16:9 — útil al subir grabaciones de móvil a YouTube sin barras negras feas. crop-detect corre una pasada de detección y muestra el recorte óptimo. Leer más — profundización en geometría fqmpeg →

C6 — Color y efectos visuales (23)

color, color-balance, equalize, lut, chroma, chromakey, color-key, alpha, cinematic, vintage, sepia, grayscale, negative, posterize, edge, glitch, pixelate, motion-blur, sharpen, blur, vignette, hdr-to-sdr, noise

El cluster más grande — color grading, looks estilizados y efectos. lut acepta archivos .cube estándar. hdr-to-sdr hace tone-mapping correcto (la teoría está en tonemapping de HDR a SDR). chroma ajusta tono / temperatura; chromakey es el verbo de pantalla verde. Leer más — deep dive fqmpeg color y efectos →

C7 — Estabilización y limpieza (8)

stabilize, deshake, denoise, deflicker, deblock, delogo, blackdetect, freeze-detect

Verbos de restauración. stabilize corre el flujo de 2 pasadas vidstabdetect → vidstabtransform como un solo comando y limpia el archivo .trf después. deshake es la alternativa más barata de una sola pasada.

C8 — Overlays, marcas de agua y composición (13)

watermark, text, drawbox, timecode, picture, pip, pip-grid, blend, stack, border, video-info-overlay, histogram-overlay, progress

Composición. pip hace picture-in-picture sin escribir filter_complex a mano. pip-grid ordena N vídeos en una rejilla 2×2 / 3×3 (útil para revisiones multicámara). progress quema una barra de progreso en movimiento dentro del vídeo.

C9 — Procesamiento de audio: niveles, EQ, dinámica (26)

audio, strip-audio, mute, normalize, volume, audio-fade, audio-bass-boost, audio-treble-boost, audio-eq, audio-bandpass, audio-highpass, audio-lowpass, audio-compressor, limiter, audio-gate, loudness-meter, audio-normalize-peak, audio-pitch, audio-speed, audio-reverse, audio-delay, audio-noise-reduce, censor, detect-silence, trim-silence, silence-insert

Loudness, EQ y dinámica. normalize usa loudnorm (EBU R128) — ver normalización de audio con loudnorm. censor es un bleep de audio, no un mosaico de vídeo (para mosaicos visuales, usa blur).

C10 — Efectos creativos de audio (9)

reverb, echo-effect, chorus, phaser, flanger, tremolo, vibrato, audio-karaoke, audio-stereo-widen

Verbos tipo pedales de efectos para audio. audio-karaoke quita las voces del canal central usando el truco estándar pan=stereo|c0=c0-c1|c1=c1-c0.

C11 — Routing de audio, canales y visualización (15)

stereo, surround, sample-rate, channel-split, extract-audio-channel, multi-audio, mix-audio, replace-audio, pan-audio, concat-audio, audio-visualize, oscilloscope, waveform, spectrum, bit-depth

Routing de canales, conversión de sample-rate / bit-depth y visualización (PNG de waveform, espectrograma, visualizador animado). Nota: bit-depth es de audio (16/24/32), no de vídeo.

C12 — Miniaturas, frames y slideshows (12)

thumbnail, thumbnail-grid, thumbnail-strip, snapshot, video-to-frames, frames-to-video, count-frames, scenes, slideshow, preview, compare, tile

Extracción de frames y conversión imagen-a-vídeo. Tanto thumbnail-grid como tile producen contact sheets. compare hace un vídeo de comparación lado a lado antes/después — útil para mostrar el efecto de un filtro. Para extracción rápida del último frame (más barato que hacer seek), ver extraer el último frame con FFmpeg.

Total: 4 inspección + 153 en clusters = 157 comandos.

--dry-run como chuleta

Cada comando acepta --dry-run. Imprime la invocación de FFmpeg que se ejecutaría y sale sin hacer el trabajo:

$ npx fqmpeg gif --dry-run input.mp4 -s 10 -d 3

ffmpeg -ss 10 -t 3 -i input.mp4 \
  -vf fps=15,scale=480:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse \
  -loop 0 input-gif.gif

Esto es más útil de lo que parece. Tres usos reales:

1. Aprender FFmpeg. Ejecuta --dry-run con el verbo que quieras, lee la salida y ya tienes el comando canónico de FFmpeg para esa tarea. Se acabó filtrar respuestas de Stack Overflow de 2014 con flags ya deprecadas.
2. Embeber en CI / scripts. Captura el comando impreso y mételo en un Makefile, un paso de CI o un Dockerfile cuando no quieras llevar Node.js a producción.
3. Auditar. Antes de correr un batch destructivo sobre 1000 archivos, --dry-run el primero y verifica que las flags coinciden con lo esperado.

fqmpeg vs otros wrappers de FFmpeg

El registro de npm tiene varios wrappers de FFmpeg con objetivos distintos. Comparativa rápida para elegir la herramienta correcta:

Resumen: fqmpeg es para humanos tecleando en una terminal; los wrappers con API JS son para programas Node.js que invocan FFmpeg internamente. No compiten — puedes usar ambos en el mismo proyecto (un pipeline fluent-ffmpeg en tu app, más fqmpeg en tu shell de desarrollo para conversiones puntuales).

Si scripteas desde Python en lugar de Node, ver la guía de automatización por lotes con Python para un enfoque desde Python.

Preguntas Frecuentes

¿fqmpeg empaqueta FFmpeg?

No. fqmpeg delega en el ffmpeg y ffprobe que tengas en el PATH. Esto mantiene el paquete npm pequeño (menos de 100 KB) y significa que controlas tú la versión de FFmpeg. Probado contra FFmpeg 8.x.

¿Qué pasó con ffmpeg-quick en npm?

ffmpeg-quick era el nombre original del paquete. En la versión 3.0.0 de fqmpeg el paquete se renombró a fqmpeg y todas las versiones ffmpeg-quick@* se deprecaron en npm. Los comandos antiguos (npx ffmpeg-quick ...) imprimen un aviso de deprecación — cambia a npx fqmpeg ....

¿Funciona en Windows?

Sí. El CLI es agnóstico a la plataforma (es sólo Node.js + el binario de FFmpeg). En Windows lo más fácil es instalar FFmpeg con winget install -e --id Gyan.FFmpeg y luego npm install -g fqmpeg. El escapado de rutas funciona como en cualquier otro CLI de Node.

¿Lo puedo usar en un script de shell o un pipeline de CI?

Sí. Cada comando termina con código 0 si éxito y no-cero si falla (igual que los códigos de salida de FFmpeg). Para jobs por lotes, prefiere la instalación global a npx para evitar la consulta al registro npm en cada invocación.

¿Y si un comando que necesito no está entre los 157?

Dos opciones. (1) Ejecuta npx fqmpeg --help para confirmar — el verbo que quieres puede estar bajo un nombre que no adivinaste. (2) Si realmente falta, abre un issue en github.com/omitsu-dev/fqmpeg. Hasta entonces, siempre puedes ejecutar FFmpeg directo — --dry-run sobre un verbo similar es un buen punto de partida para la sintaxis.

¿Cómo valida fqmpeg la entrada?

Cada opción tiene un parser registrado en src/utils.js (rangos numéricos, valores enum, formatos de tiempo tipo HH:MM:SS, sintaxis de dB / multiplicador, etc.). Los valores incorrectos se rechazan con un mensaje que nombra la opción, el valor incorrecto y el rango permitido. La suite de CI incluye 77 casos de test negativos que confirman que el rechazo ocurre antes de invocar a FFmpeg.

¿fqmpeg sustituye a HandBrake o DaVinci Resolve?

No. Esas son herramientas GUI optimizadas para flujos interactivos (HandBrake para presets de ripping/transcodificación, DaVinci para edición/grading). fqmpeg es para los casos donde un CLI tiene la forma correcta — batch, scripting, CI, servidores headless. Los trade-offs están en la comparación FFmpeg vs alternativas GUI.

¿Soporta aceleración por hardware (NVENC, QSV)?

El FFmpeg subyacente sí, pero la mayoría de verbos de fqmpeg usan por defecto encoders software por portabilidad. Si necesitas NVENC/QSV, ejecuta --dry-run sobre el verbo para ver el comando y añade las flags relevantes a mano. La guía de codificación por GPU cubre qué añadir.

Conclusión

El valor de fqmpeg está concentrado en una idea: la mayoría del tiempo no quieres pensar en flags de FFmpeg, sólo quieres hacer la tarea. 157 verbos cubren la cola larga de tareas comunes, la validación detecta entradas incorrectas pronto y --dry-run deja FFmpeg completamente visible para cuando quieras aprender o personalizar.

Para empezar:

npm install -g fqmpeg
fqmpeg --help            # ver todos los verbos
fqmpeg compress --help   # opciones de un verbo
fqmpeg compress input.mp4

Los artículos de profundidad para cada uno de los 12 clusters se publicarán como guías separadas en 32blog. Hasta que aterricen, fqmpeg <comando> --help documenta cada opción de cada comando y el código en GitHub es lo bastante corto para leerlo de cabo a rabo.