fqmpeg Complete Guide: 157 FFmpeg Commands as Verbs

fqmpeg is a Node.js CLI wrapper that turns 157 common FFmpeg tasks into single-verb commands like compress, gif, hls, and audio. You install it with npm install -g fqmpeg, you keep your existing FFmpeg install, and you stop Googling filter syntax every time you need to make a thumbnail. The latest version on npm is 3.0.1 (published 2026-05-10), and it ships with one runtime dependency (Commander) plus a strict input validator that rejects bad flags before FFmpeg ever runs.

This guide is the entry point for the fqmpeg cluster on 32blog. It covers what fqmpeg is, why a wrapper is worth using on top of FFmpeg, how to install it, the four built-in inspection commands, and a categorized map of every one of the 157 commands so you can find the verb you need without digging.

What you'll get out of this guide

• A clear mental model of how fqmpeg organizes 157 commands
• Install instructions (works on Windows, macOS, Linux via npm)
• The four inspection verbs that ship without needing a separate article
• A complete command map grouped into 12 topic clusters
• How --dry-run doubles as an FFmpeg cheat sheet

What Is fqmpeg?

fqmpeg is an open-source CLI distributed on npm as the package fqmpeg (source: github.com/omitsu-dev/fqmpeg, MIT license). It's a thin Node.js wrapper around the ffmpeg and ffprobe binaries that already live on your PATH.

Every command maps to one task you actually want to do — not one FFmpeg flag. So instead of remembering this:

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

you write:

npx fqmpeg compress input.mp4

You also get:

• Strict input validation. Bad values (out-of-range CRF, unknown preset, missing argument) are rejected with a readable error message before FFmpeg is invoked. No more decoding cryptic FFmpeg errors.
• Auto output names. No output flag needed — input.mp4 becomes input-compressed.mp4, input-gif.gif, input-tagged.mp4 based on the verb.
• --dry-run on every command. Prints the full FFmpeg invocation without running it, so you can copy it, learn from it, or paste it into a CI script.
• --help on every command. Shows arguments, options, defaults, and ranges. You don't need to memorize 157 commands — --help tells you.

There are no sub-modules, no plugins, no config files. You install one package and get 157 verbs.

Why a CLI Wrapper Instead of Plain FFmpeg?

FFmpeg is the most powerful media tool in existence, but its CLI surface is enormous. The official ffmpeg-all.html documentation is over 4 MB of plain text. Filter graphs use a chained micro-syntax. Stream selection uses a separate map syntax. Most working video engineers don't memorize FFmpeg — they keep a folder of recipes and Stack Overflow tabs.

A wrapper helps in three concrete ways:

1. Discoverability. fqmpeg --help lists every verb. Once you know the verb, fqmpeg <verb> --help shows the options. You never need to know which filter handles your task.
2. Validation up front. FFmpeg accepts almost any string for almost any flag and fails deep inside the encoding pipeline with messages like Error initializing filter 'palettegen' with args ''. fqmpeg catches --crf 999 or --preset turbofast before FFmpeg starts.
3. Defaults that match common intent. compress defaults to CRF 23, preset medium, AAC audio, faststart — what most people actually want when they say "compress this." Override only what you care about.

The classic counterargument is "just learn FFmpeg." That's valid for full-time video engineers. For everyone else (developers shipping a feature, content creators batching uploads, devops scripting a pipeline) the wrapper saves real time without hiding what's happening — --dry-run always shows the underlying command, so you can graduate to raw FFmpeg whenever you want.

If you're choosing between a CLI wrapper, a GUI app like HandBrake, and writing FFmpeg yourself, the FFmpeg vs GUI alternatives comparison covers the broader trade-offs. fqmpeg sits in the CLI camp and trades GUI's clickability for batch-friendliness and reproducibility.

Install

You need two things: Node.js (≥18) and FFmpeg.

Step 1 — install FFmpeg. Skip this if you already have it (ffmpeg -version prints a banner). Otherwise see the FFmpeg install guide.

Step 2 — install fqmpeg. Pick one:

# Global install
npm install -g fqmpeg

# Or run on demand without installing
npx fqmpeg compress input.mp4

Both work. npx is convenient for one-off use; the global install is faster on repeat invocations because npm doesn't re-fetch metadata each time.

Step 3 — verify.

fqmpeg --version
# 3.0.1

fqmpeg --help
# (lists every verb with a one-line description)

If fqmpeg --version prints 3.0.1 and ffmpeg -version prints an FFmpeg banner, you're done.

The Verb Pattern: How fqmpeg Thinks

Every command follows the same shape:

fqmpeg <verb> <input> [options]

The verb is the action you want. The input is your media file. Options refine the behavior, and most have sensible defaults. There's no global config, no profiles, no chaining — each command is one operation.

Three concrete examples:

# "Make a 3-second GIF starting at 10s"
npx fqmpeg gif input.mp4 -s 10 -d 3

# "Trim from 30s for 10 seconds"
npx fqmpeg trim input.mp4 -s 30 -d 10

# "Stack two videos side by side"
npx fqmpeg stack left.mp4 right.mp4

If you forget the options, append --help:

npx fqmpeg gif --help
# Usage: fqmpeg gif [options] <input>
# Options:
#   -s, --start <seconds>     Start time in seconds (default: 0)
#   -d, --duration <seconds>  Duration in seconds (default: 3)
#   --fps <n>                 Frames per second (default: 15)
#   --width <px>              Output width (default: 480)
#   ...

If you pass a bad value, fqmpeg tells you instead of FFmpeg:

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

That's the whole interface. There's no second mode, no DSL to learn.

Inspection Commands (Built In)

Four verbs are inspection / metadata utilities. They don't have a dedicated deep-dive article because they're small, self-contained, and you'll want them documented next to the install instructions.

info — full ffprobe dump as JSON

npx fqmpeg info input.mp4

Wraps ffprobe -v quiet -print_format json -show_format -show_streams. Use it when you need to inspect codec, resolution, frame rate, bitrate, channel layout, or any other media property programmatically.

# Pipe into jq to grab just the video stream
npx fqmpeg info input.mp4 | jq '.streams[] | select(.codec_type=="video")'

duration — just the duration, in HH:MM:SS

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

Wraps ffprobe -show_entries format=duration -of csv=p=0 -sexagesimal. Useful inside shell scripts when you need to gate logic on length without parsing the full info JSON.

metadata — write tags into the container

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

Sets container-level metadata (title, artist, album, year, comment, genre) using -c copy so no re-encode happens. Output defaults to input-tagged.mp4. Works with audio files too — useful for tagging MP3 batches before uploading to a podcast host.

embed-thumbnail — attach a cover image

npx fqmpeg embed-thumbnail input.mp3 cover.jpg

Embeds a JPG/PNG as the attached picture (disposition: attached_pic). Most music players and macOS Finder will surface it as the cover art. The video stream is copied without re-encoding, so this is a fast operation even on long files.

For the rest of the 153 commands, jump to the relevant cluster below.

The 12 Topic Clusters (157 Commands at a Glance)

The 157 commands sort cleanly into 12 task-oriented clusters. Each cluster will eventually have its own deep-dive article on 32blog — but every command listed below is already shipping in fqmpeg@3.0.1 today, and fqmpeg <command> --help documents the options for each one.

C1 — Compression & Encoding (7)

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

Codec choice and bitrate control. compress is the H.264 default; the encode-* family targets specific codecs (AV1 for streaming, H.265 for archive, ProRes/DNxHR for editing). For a deep dive on codec trade-offs, see AV1 vs H.265 vs H.264 and the video compression guide. Read more — fqmpeg compression & encoding deep dive →

C2 — Format Conversion & Streaming (7)

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

Container changes (mp4 ↔ mov ↔ webm), GIF I/O, HLS / DASH segmentation for adaptive streaming, and stream extraction by index. For an end-to-end HLS pipeline including CDN setup, see the HLS CDN streaming guide. Read more — fqmpeg format & streaming deep dive →

C3 — Subtitles (4)

subtitle, subtitle-burn, extract-subtitle, sidecar

Soft-embed subtitles, hardcode (burn) them into the picture, extract them as .srt, or sidecar them as a selectable track. If you need to generate captions automatically first, see FFmpeg + Whisper auto-subtitles. Read more — fqmpeg subtitles deep dive →

C4 — Editing: Trim, Speed, Concat, Frames (15)

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

Time-axis operations. concat skips the temp-file-list dance. speed handles the setpts / atempo math (including atempo chaining for >2x). For the lossless equivalent of trim, see FFmpeg lossless cut. Read more — fqmpeg editing deep dive →

C5 — Resize, Crop & Rotate (14)

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

Geometry. backdrop adds a blurred background to a vertical video so it fills 16:9 — handy when uploading phone footage to YouTube without ugly black bars. crop-detect runs a detection pass first and prints the optimal crop. Read more — fqmpeg geometry deep dive →

C6 — Color & Visual Effects (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

The biggest cluster — color grading, stylized looks, and effects. lut accepts standard .cube files. hdr-to-sdr does proper tone-mapping (see HDR to SDR tonemapping for the underlying theory). chroma adjusts hue / temperature; chromakey is the green-screen verb. Read more — fqmpeg color & effects deep dive →

C7 — Stabilization & Cleanup (8)

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

Restoration verbs. stabilize runs the 2-pass vidstabdetect → vidstabtransform flow as one command and cleans up the .trf file after. deshake is the cheaper one-pass alternative.

C8 — Overlays, Watermarks & Composition (13)

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

Compositing. pip does picture-in-picture without writing filter_complex by hand. pip-grid arranges N videos in a 2×2 / 3×3 grid (handy for multi-camera reviews). progress burns a moving progress bar into the video.

C9 — Audio Processing: Levels, EQ, Dynamics (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, and dynamics. normalize uses loudnorm (EBU R128) — see audio normalization with loudnorm. censor is an audio bleep, not a video mosaic (use blur for visual censoring).

C10 — Creative Audio Effects (9)

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

Effects-pedal verbs for audio. audio-karaoke removes the center-channel vocals using the standard pan=stereo|c0=c0-c1|c1=c1-c0 trick.

C11 — Audio Routing, Channels & Visualization (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

Channel routing, sample-rate / bit-depth conversion, and visualization (waveform PNG, spectrogram, animated visualizer). Note: bit-depth is audio bit depth (16/24/32), not video.

C12 — Thumbnails, Frames & Slideshows (12)

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

Frame extraction and image-to-video. thumbnail-grid and tile both produce contact sheets. compare makes a side-by-side before/after video — useful for showing the effect of a filter pass. For a fast last-frame extraction (cheaper than seeking), see extracting the last frame.

Total: 4 inspection + 153 in clusters = 157 commands.

--dry-run as a Cheat Sheet

Every command accepts --dry-run. It prints the FFmpeg invocation that would run and exits without doing the work:

$ 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

This is more useful than it looks. Three real uses:

1. Learning FFmpeg. Run --dry-run on the verb you want, read the output, and you've got the canonical FFmpeg command for that task. No more sifting through Stack Overflow answers from 2014 that use deprecated flags.
2. Embedding in CI / scripts. Capture the printed command and put it in a Makefile, a CI step, or a Dockerfile when you don't want a Node.js dependency in production.
3. Auditing. Before running a destructive batch on 1000 files, --dry-run the first one and verify the flags match expectations.

fqmpeg vs Other FFmpeg Wrappers

The npm registry has several FFmpeg wrappers with different goals. A quick comparison so you can pick the right tool:

The shorthand: fqmpeg is for humans typing in a terminal; the JS-API wrappers are for Node.js programs invoking FFmpeg internally. They don't compete — you can use both in the same project (a fluent-ffmpeg pipeline in your app, plus fqmpeg in your dev shell for one-off conversions).

If you're scripting from Python instead of Node, see the FFmpeg + Python batch automation guide for a Python-side approach.

Frequently Asked Questions

Does fqmpeg bundle FFmpeg?

No. fqmpeg shells out to whatever ffmpeg and ffprobe are on your PATH. This keeps the npm package small (under 100 KB) and means you control the FFmpeg version yourself. Tested against FFmpeg 8.x.

What happened to ffmpeg-quick on npm?

ffmpeg-quick was the original package name. As of fqmpeg 3.0.0 the package was renamed to fqmpeg and all ffmpeg-quick@* versions were deprecated on npm. Old install commands (npx ffmpeg-quick ...) will print a deprecation notice — switch to npx fqmpeg ....

Does it work on Windows?

Yes. The CLI is platform-agnostic (it's just Node.js + the FFmpeg binary). On Windows the easiest setup is to install FFmpeg with winget install -e --id Gyan.FFmpeg, then npm install -g fqmpeg. Path quoting works the same as any other Node CLI.

Can I use it in a shell script / CI pipeline?

Yes. Each command exits 0 on success and non-zero on failure (matching FFmpeg's exit code). For batch jobs, prefer the global install over npx to avoid the per-invocation npm-registry lookup.

What if a command I need isn't in the 157?

Two options. (1) Run npx fqmpeg --help to confirm — the verb you want might be there under a name you didn't guess. (2) If it's genuinely missing, file an issue at github.com/omitsu-dev/fqmpeg. Until then, you can always run plain FFmpeg — --dry-run on a similar verb is a good starting point for the syntax.

How does fqmpeg validate input?

Each option has a parser registered in src/utils.js (numeric ranges, enum values, time formats like HH:MM:SS, dB / multiplier syntax, etc.). Bad values are rejected with a message naming the option, the bad value, and the allowed range. The CI suite includes 77 negative test cases that confirm rejection happens before FFmpeg is invoked.

Is fqmpeg a replacement for HandBrake or DaVinci Resolve?

No. Those are GUI tools optimized for interactive workflows (HandBrake for ripping/transcoding presets, DaVinci for editing/grading). fqmpeg is for the cases where a CLI is the right shape — batching, scripting, CI, headless servers. The trade-offs are covered in the FFmpeg vs GUI alternatives comparison.

Does it support hardware acceleration (NVENC, QSV)?

The underlying FFmpeg supports it, but most fqmpeg verbs default to software encoders for portability. If you need NVENC/QSV, run --dry-run on the verb to see the command, then add the relevant flags manually. The GPU encoding guide covers what to add.

Wrapping Up

fqmpeg's value is concentrated in one idea: most of the time you don't want to think about FFmpeg flags, you just want to do the task. 157 verbs cover the long tail of common tasks, validation catches bad input early, and --dry-run keeps the underlying FFmpeg fully visible for when you do want to learn or customize.

To get started:

npm install -g fqmpeg
fqmpeg --help            # see all verbs
fqmpeg compress --help   # options for one verb
fqmpeg compress input.mp4

The deep-dive articles for each of the 12 clusters are being published as separate guides on 32blog. Until those land, fqmpeg <command> --help documents every option for every command, and the source on GitHub is short enough to read end-to-end.