fqmpeg完全ガイド：FFmpegを動詞で操る157コマンド

Q: Q1: fqmpeg は FFmpeg を同梱する？

しない。`PATH` 上の `ffmpeg` / `ffprobe` をそのまま呼び出す。これにより npm パッケージは 100 KB 未満に収まり、FFmpeg のバージョンは自分で管理できる。FFmpeg 8.x で動作確認している。

Q: Q2: npm の `ffmpeg-quick` はどうなった？

fqmpeg の旧名が `ffmpeg-quick` だ。`3.0.0` のタイミングでパッケージ名を `fqmpeg` に変更し、`ffmpeg-quick@*` は全バージョン npm 上で deprecate された。古い `npx ffmpeg-quick ...` は警告を出すだけで動くが、`npx fqmpeg ...` に切り替えるべき。

Q: Q5: 必要なコマンドが 157 個に入っていなかったら？

選択肢は 2 つ。(1) `npx fqmpeg --help` で動詞名を確認する——想定と違う名前で存在する可能性がある。(2) 本当に欠けているなら [github.com/omitsu-dev/fqmpeg](https://github.com/omitsu-dev/fqmpeg/issues) で issue を立てる。それまでは素の FFmpeg を叩けばよく、近い動詞に `--dry-run` を付けて出力を出発点にすると書きやすい。

Q: Q6: 入力値の検証はどう動く？

各オプションには `src/utils.js` にパーサーが登録されている（数値レンジ、列挙、`HH:MM:SS` 形式の時間、dB / 倍率記法など）。不正な値はオプション名・与えられた値・許容範囲を含むメッセージで弾かれる。CI には FFmpeg 起動前に拒否されることを確認する 77 件の negative テストが入っている。

fqmpeg は FFmpeg の代表的な 157 タスクを compress gif hls audio といった動詞 1 つで実行できる Node.js 製 CLI ラッパーだ。npm install -g fqmpeg で導入でき、既存の FFmpeg 環境はそのまま流用できる。サムネイル 1 枚作るためにフィルタ構文をググる作業から解放される。npm の最新バージョンは 3.0.1（2026-05-10 公開）。依存は Commander 1 つだけで、不正なフラグは FFmpeg を呼ぶ前に弾く厳格なバリデータが組み込まれている。

この記事は 32blog の fqmpeg クラスタの入り口だ。fqmpeg とは何か、FFmpeg を素で使う代わりにラッパーを使う理由、インストール手順、組み込みの 4 つの検査コマンド、そして 157 コマンドを 12 のカテゴリに整理した一覧まで一通り把握できる。

この記事を読むとわかること

157 コマンドが fqmpeg でどう整理されているか
インストール手順（Windows / macOS / Linux 共通、npm 経由）
子記事不要で完結する 4 つの検査用動詞
12 カテゴリに整理されたコマンド一覧
--dry-run を FFmpeg のチートシートとして使う方法

fqmpeg とは

fqmpeg は npm に fqmpeg として公開されているオープンソースの CLI だ（ソースは github.com/omitsu-dev/fqmpeg、MIT ライセンス）。PATH にある ffmpeg / ffprobe バイナリを呼び出す薄いラッパーになっている。

各コマンドは「やりたいこと」に対応する動詞であって、FFmpeg のフラグに対応するわけではない。だから次のような呪文を覚える代わりに、

bash

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

こう書ける。

bash

npx fqmpeg compress input.mp4

加えてこういう仕組みも入っている。

入力値の厳密検証: --crf 999 のような範囲外の値や、未定義のプリセット、引数不足は FFmpeg を起動する前に弾かれる。FFmpeg の難解なエラーメッセージを読み解く時間が消える
出力ファイル名の自動生成: -o を書かなくても input.mp4 → input-compressed.mp4 / input-gif.gif / input-tagged.mp4 と動詞ごとに付与される
--dry-run が全コマンドで使える: 実行せずに FFmpeg コマンドだけを表示するため、コピーしてもいいし学習教材にもできる
--help が全コマンドで使える: 引数・オプション・デフォルト・許容範囲がすべて出る。157 コマンドを暗記する必要はない

サブモジュールもプラグインも設定ファイルもない。1 つのパッケージで 157 動詞が手に入る。

なぜ FFmpeg を直接叩かずラッパーを使うのか

FFmpeg は世界最強の動画処理ツールだが、CLI のサーフェスが広すぎる。公式ドキュメントの ffmpeg-all.html は 4 MB を超えるプレーンテキストだし、フィルタグラフは独自の連結マイクロ記法を使う。ストリーム選択にはまた別の map 記法が要る。実際のところ、現役のビデオエンジニアでも FFmpeg を暗記している人はほとんどいない。みんな自分用のレシピフォルダと Stack Overflow のタブで仕事をしている。

ラッパーはここに 3 つの具体的なメリットを持ち込む。

発見可能性: fqmpeg --help で全動詞が一覧できる。動詞さえ分かれば fqmpeg <verb> --help でオプションが見える。「このタスクはどのフィルタを使うんだっけ」という調査が消える
入力値検証が前段にある: FFmpeg は大抵の文字列をどのフラグにも受け入れて、エンコード処理の奥で Error initializing filter 'palettegen' with args '' のようなメッセージで落ちる。fqmpeg は --crf 999 や --preset turbofast を起動前にエラーにする
デフォルトが普段の意図に合っている: compress のデフォルトは CRF 23・preset medium・AAC 音声・faststart で、「とりあえず圧縮して」と言うときに大抵の人が望む値そのもの。気になる部分だけ上書きすればいい

「FFmpeg を覚えればいいだけ」という反論は妥当だが、それはフルタイムのビデオエンジニアの話だ。機能を出す側のエンジニア、配信ルーチンをバッチ化したい配信者、パイプラインを書く DevOps にとっては、ラッパーが時間を節約してくれる。しかも --dry-run で常に裏側のコマンドを覗けるので、隠蔽されたブラックボックスにはならない。学んでから素の FFmpeg に移行するのも自由だ。

CLI ラッパー、HandBrake のような GUI、素の FFmpeg を書く——この 3 択で迷っているなら FFmpeg vs GUI 代替ツール比較で全体像を整理している。fqmpeg は CLI 派の選択肢で、GUI のクリック性を捨てる代わりにバッチ性と再現性を取りに行く設計だ。

インストール

必要なのは Node.js（≥18）と FFmpeg の 2 つだけ。

ステップ 1 — FFmpeg を入れる。 ffmpeg -version でバナーが出るならスキップ。出ないなら FFmpeg インストールガイドを参照。

ステップ 2 — fqmpeg を入れる。 どちらかを選ぶ。

bash

# グローバルインストール
npm install -g fqmpeg

# またはインストールせずその場で実行
npx fqmpeg compress input.mp4

どちらでも動く。単発利用なら npx が手軽で、繰り返し叩くならグローバルの方が npm のメタデータ取得が走らないぶん速い。

ステップ 3 — 確認。

bash

fqmpeg --version
# 3.0.1

fqmpeg --help
# (全動詞と説明が一覧表示される)

fqmpeg --version が 3.0.1 を返し、ffmpeg -version も FFmpeg のバナーを出すなら準備完了だ。

fqmpeg の動詞パターン

すべてのコマンドが同じ形を取る。

fqmpeg <verb> <input> [options]

動詞はやりたい操作、入力はメディアファイル、オプションは挙動の調整で大抵デフォルトが効いている。グローバル設定もプロファイルもチェーンもない。1 コマンド = 1 操作。

具体例を 3 つ。

bash

# "10 秒地点から 3 秒の GIF を作る"
npx fqmpeg gif input.mp4 -s 10 -d 3

# "30 秒から 10 秒切り出す"
npx fqmpeg trim input.mp4 -s 30 -d 10

# "2 つの動画を左右に並べる"
npx fqmpeg stack left.mp4 right.mp4

オプションを忘れたら --help を付ければいい。

bash

npx fqmpeg gif --help
# Usage: fqmpeg gif [options] <input>
# Options:
#   -s, --start <seconds>     開始秒数（既定: 0）
#   -d, --duration <seconds>  長さ秒数（既定: 3）
#   --fps <n>                 フレームレート（既定: 15）
#   --width <px>              出力幅（既定: 480）
#   ...

不正な値を渡すと FFmpeg ではなく fqmpeg が止めてくれる。

bash

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

これがインターフェースの全部だ。第 2 のモードも独自 DSL もない。

検査用コマンド（組み込み）

4 つの動詞は検査・メタデータ用のユーティリティだ。専用の子記事を作るほどの分量がないので、インストール手順の隣でここに収めておく。

`info` — ffprobe の全情報を JSON で出力

bash

npx fqmpeg info input.mp4

中身は ffprobe -v quiet -print_format json -show_format -show_streams のラップ。コーデック・解像度・フレームレート・ビットレート・チャネルレイアウトをスクリプトで扱いたいときに使う。

bash

# jq で動画ストリームだけ取り出す
npx fqmpeg info input.mp4 | jq '.streams[] | select(.codec_type=="video")'

`duration` — 長さだけを HH:MM:SS で出力

bash

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

ffprobe -show_entries format=duration -of csv=p=0 -sexagesimal のラップ。シェルスクリプトで動画の長さで分岐したいけれど info の JSON をパースするのは大袈裟、というときの軽量版だ。

`metadata` — コンテナにタグを書き込む

bash

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

コンテナレベルのメタデータ（title artist album year comment genre）を -c copy で書き換える——再エンコードは走らない。出力は既定で input-tagged.mp4。音声ファイルにも使えるので、ポッドキャストホストに上げる前の MP3 一括タグ付けにも便利。

`embed-thumbnail` — カバー画像を埋め込む

bash

npx fqmpeg embed-thumbnail input.mp3 cover.jpg

JPG / PNG を attached_pic として埋め込む。多くの音楽プレーヤーや macOS の Finder がカバーアートとして表示してくれる。動画ストリームは無加工コピーなので、長尺ファイルでも一瞬で終わる。

残りの 153 コマンドは下のクラスタを参照してほしい。

12 のカテゴリ（157 コマンドの全体像）

157 コマンドはタスク指向で 12 のクラスタに整理してある。各クラスタは順次 32blog で深堀り記事を公開予定だが、下に挙げたコマンドはすべて fqmpeg@3.0.1 ですでに動いていて、fqmpeg <command> --help ですぐにオプションを確認できる。

C1 — 圧縮・エンコード（7）

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

コーデック選択とビットレート制御。compress が H.264 のデフォルトで、encode-* 系は特定コーデック（配信用 AV1、アーカイブ用 H.265、編集用 ProRes / DNxHR）に振り分ける。コーデックの取捨選択は AV1 vs H.265 vs H.264 比較と動画圧縮ガイドが詳しい。詳細記事 — fqmpeg 圧縮・エンコード徹底解説 →

C2 — フォーマット変換・配信（7）

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

コンテナ変換（mp4 ↔ mov ↔ webm）、GIF の入出力、アダプティブ配信用の HLS / DASH セグメント生成、インデックス指定でのストリーム抽出。HLS を CDN まで通す全体像は FFmpeg HLS CDN ストリーミングガイドを参照。詳細記事 — fqmpeg フォーマット変換・配信徹底解説 →

C3 — 字幕（4）

subtitle, subtitle-burn, extract-subtitle, sidecar

ソフト埋め込み、焼き付け（ハードコード）、.srt 抽出、選択可能トラックとしてのサイドカー添付。字幕を自動生成したいなら先に FFmpeg + Whisper 自動字幕で作るのが筋。詳細記事 — fqmpeg 字幕クラスタ徹底解説 →

C4 — 編集：トリム・速度・連結・フレーム（15）

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

時間軸の操作。concat は一時ファイルリストを作る手間を省く。speed は setpts / atempo の計算（2x 超のときの atempo チェーンを含む）を内部で処理してくれる。ロスレスなカットなら FFmpeg ロスレスカットを参照。詳細記事 — fqmpeg 編集系の深掘り →

C5 — リサイズ・クロップ・回転（14）

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

ジオメトリ系。backdrop は縦動画にぼかし背景を合成して 16:9 に仕立てるコマンドで、スマホ素材を YouTube に上げるときの黒帯対策に効く。crop-detect は最適なクロップ領域を検出して印字する。詳細記事 — fqmpeg ジオメトリの深掘り →

C6 — カラー・ビジュアルエフェクト（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

最大規模のクラスタ。カラーグレーディング、スタイライズ、エフェクト全般。lut は標準的な .cube ファイルを受ける。hdr-to-sdr は適切なトーンマッピングを行う（理屈は HDR → SDR トーンマッピングで解説している）。chroma は色相・色温度の調整、chromakey がいわゆるグリーンバック合成。詳細記事 — fqmpeg 色とエフェクトの深掘り →

C7 — 安定化・クリーンアップ（8）

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

修復系。stabilize は 2 パスの vidstabdetect → vidstabtransform を 1 コマンドにまとめ、.trf の中間ファイルも自動で片付ける。deshake は安価な 1 パス版。

C8 — オーバーレイ・透かし・合成（13）

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

合成系。pip はピクチャインピクチャを filter_complex 手書きなしで実現する。pip-grid は複数動画を 2×2 / 3×3 のグリッドに並べる（マルチカメラの確認に重宝）。progress は動画にプログレスバーを焼き込む。

C9 — 音声処理：レベル・EQ・ダイナミクス（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

ラウドネス・EQ・ダイナミクス。normalize は loudnorm（EBU R128）を使う——詳しくは loudnorm を使った音声ノーマライズ。censor は音声の bleep であって映像のモザイクではない（映像のモザイクは blur を使う）。

C10 — 創造的な音声エフェクト（9）

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

エフェクトペダル系の動詞。audio-karaoke は pan=stereo|c0=c0-c1|c1=c1-c0 の定番手法でセンターチャンネル（ボーカル）を抜く。

C11 — 音声ルーティング・チャネル・可視化（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

チャネルルーティング、サンプリングレート / ビット深度の変換、可視化（波形 PNG、スペクトログラム、アニメ可視化）。注意：bit-depth は音声のビット深度（16 / 24 / 32）であって動画ではない。

C12 — サムネイル・フレーム・スライドショー（12）

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

フレーム抽出と画像 → 動画。thumbnail-grid と tile はどちらもコンタクトシートを作る。compare は前後比較の左右並べ動画を作るのでフィルタの効果検証に便利。最終フレームだけ素早く取りたいときは FFmpeg 最終フレーム高速抽出を参照。

合計：検査 4 + クラスタ 153 = 157 コマンド。

--dry-run をチートシートとして使う

すべてのコマンドが --dry-run を受け付ける。本来実行される FFmpeg コマンドだけを表示して終了する。

bash

$ 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

これは見た目以上に便利だ。実用例を 3 つ挙げる。

FFmpeg の学習: 使いたい動詞に --dry-run を付けて実行すれば、そのタスクの正規 FFmpeg コマンドが出てくる。2014 年の Stack Overflow 回答（deprecated フラグ満載）を読み解く時間が消える
CI / スクリプト埋め込み: 出力されたコマンドを Makefile・CI ステップ・Dockerfile に転記すれば、本番から Node.js 依存を外せる
監査: 1000 ファイルの破壊的バッチを走らせる前に最初の 1 件で --dry-run してフラグを確認できる

fqmpeg と他の FFmpeg ラッパーの違い

npm レジストリにはいくつか FFmpeg ラッパーがあるが、目的が違う。選定の早見表として：

ツール	インターフェース	用途
fqmpeg	CLI（動詞）	端末やシェルスクリプトから動画タスクを実行したい
fluent-ffmpeg	JS API（チェーン）	Node.js プログラムから FFmpeg を呼び出したい。なお同パッケージは活発にメンテナンスされていないと広く報告されているため、新規採用前にステータス確認推奨
ffmpeg-static	npm 同梱 FFmpeg バイナリ	Node.js アプリの `node_modules` に FFmpeg を同梱したい
ffmpeg-cli / ffmpeg-wrap	JS API	低レベルにプログラム的に FFmpeg を叩きたい

要約すると fqmpeg は端末でタイプする人間のためのツール、JS API ラッパー群は Node.js プログラム内部から FFmpeg を呼ぶためのツール。競合関係ではないので、同じプロジェクトで両方使うのは普通だ（アプリ内では fluent-ffmpeg、開発シェルでは fqmpeg、という具合）。

Python から叩きたい場合は FFmpeg + Python バッチ自動化ガイドを参照。

よくある質問

Q1: fqmpeg は FFmpeg を同梱する？

しない。PATH 上の ffmpeg / ffprobe をそのまま呼び出す。これにより npm パッケージは 100 KB 未満に収まり、FFmpeg のバージョンは自分で管理できる。FFmpeg 8.x で動作確認している。

Q2: npm の `ffmpeg-quick` はどうなった？

fqmpeg の旧名が ffmpeg-quick だ。3.0.0 のタイミングでパッケージ名を fqmpeg に変更し、ffmpeg-quick@* は全バージョン npm 上で deprecate された。古い npx ffmpeg-quick ... は警告を出すだけで動くが、npx fqmpeg ... に切り替えるべき。

Q3: Windows でも動く？

動く。CLI は Node.js + FFmpeg バイナリだけのプラットフォーム非依存構成だ。Windows の場合は winget install -e --id Gyan.FFmpeg で FFmpeg を入れたあと npm install -g fqmpeg でいい。パスのクオートは他の Node CLI と同じで問題ない。

Q4: シェルスクリプトや CI パイプラインで使える？

使える。各コマンドは成功で 0、失敗で非 0 を返す（FFmpeg の終了コードと整合）。バッチ用途では毎回の npm レジストリ照会を省くためにグローバルインストールを推奨。

Q5: 必要なコマンドが 157 個に入っていなかったら？

選択肢は 2 つ。(1) npx fqmpeg --help で動詞名を確認する——想定と違う名前で存在する可能性がある。(2) 本当に欠けているなら github.com/omitsu-dev/fqmpeg で issue を立てる。それまでは素の FFmpeg を叩けばよく、近い動詞に --dry-run を付けて出力を出発点にすると書きやすい。

Q6: 入力値の検証はどう動く？

各オプションには src/utils.js にパーサーが登録されている（数値レンジ、列挙、HH:MM:SS 形式の時間、dB / 倍率記法など）。不正な値はオプション名・与えられた値・許容範囲を含むメッセージで弾かれる。CI には FFmpeg 起動前に拒否されることを確認する 77 件の negative テストが入っている。

Q7: HandBrake や DaVinci Resolve の代わりになる？

ならない。それらは対話的ワークフローに最適化された GUI ツール（HandBrake はリッピング/トランスコードプリセット、DaVinci は編集/カラーグレーディング）。fqmpeg は CLI が向いている領域——バッチ・スクリプト・CI・ヘッドレスサーバー——のためのツールだ。トレードオフは FFmpeg vs GUI 代替ツール比較で整理している。

Q8: ハードウェアアクセラレーション（NVENC、QSV）は使える？

裏の FFmpeg 自体は対応しているが、fqmpeg の動詞は移植性のためソフトウェアエンコーダをデフォルトにしている。NVENC / QSV を使うなら動詞に --dry-run を付けてコマンドを得てから手動でフラグを足すのが現実的。具体的なフラグは GPU エンコードガイドにまとめている。

まとめ

fqmpeg の価値は 1 つの発想に集約される——ほとんどの場面で FFmpeg のフラグを考えたいわけじゃない、タスクを終わらせたいだけだ。157 動詞が一般的なタスクのロングテールをカバーし、バリデーションが入力ミスを早期に止め、--dry-run が裏側の FFmpeg を完全に可視のまま保ってくれる。学びたいときも、カスタマイズしたいときも、見えなくなる場所はない。

最初の一歩はこれだけ。

bash

npm install -g fqmpeg
fqmpeg --help            # 動詞一覧
fqmpeg compress --help   # 個別動詞のオプション
fqmpeg compress input.mp4

12 クラスタ各々の深堀り記事は順次 32blog で公開していく。それまでは fqmpeg <command> --help がオプションを網羅的に教えてくれるし、GitHub のソースも最後まで読める分量だ。

fqmpeg とは

なぜ FFmpeg を直接叩かずラッパーを使うのか

インストール

fqmpeg の動詞パターン

検査用コマンド（組み込み）

info — ffprobe の全情報を JSON で出力

duration — 長さだけを HH:MM:SS で出力

metadata — コンテナにタグを書き込む

embed-thumbnail — カバー画像を埋め込む

12 のカテゴリ（157 コマンドの全体像）

C1 — 圧縮・エンコード（7）

C2 — フォーマット変換・配信（7）

C3 — 字幕（4）

C4 — 編集：トリム・速度・連結・フレーム（15）

C5 — リサイズ・クロップ・回転（14）

C6 — カラー・ビジュアルエフェクト（23）

C7 — 安定化・クリーンアップ（8）

C8 — オーバーレイ・透かし・合成（13）

C9 — 音声処理：レベル・EQ・ダイナミクス（26）

C10 — 創造的な音声エフェクト（9）

C11 — 音声ルーティング・チャネル・可視化（15）

C12 — サムネイル・フレーム・スライドショー（12）

--dry-run をチートシートとして使う

fqmpeg と他の FFmpeg ラッパーの違い

よくある質問

Q1: fqmpeg は FFmpeg を同梱する？

Q2: npm の ffmpeg-quick はどうなった？

Q3: Windows でも動く？

Q4: シェルスクリプトや CI パイプラインで使える？

Q5: 必要なコマンドが 157 個に入っていなかったら？

Q6: 入力値の検証はどう動く？

Q7: HandBrake や DaVinci Resolve の代わりになる？

Q8: ハードウェアアクセラレーション（NVENC、QSV）は使える？

まとめ

`info` — ffprobe の全情報を JSON で出力

`duration` — 長さだけを HH:MM:SS で出力

`metadata` — コンテナにタグを書き込む

`embed-thumbnail` — カバー画像を埋め込む

Q2: npm の `ffmpeg-quick` はどうなった？