fqmpeg 手ブレ補正・クリーンアップ: 8動詞で素材を救出

fqmpeg の C7 クラスタは「素材を救うための8動詞」だ。映像の見た目を変えるんじゃなくて、欠陥を直すための動詞群。手ブレを補正する2つ（stabilize、deshake）、ノイズ・フリッカー・圧縮アーティファクトを減らす3つ（denoise、deflicker、deblock）、固定位置のロゴを消す1つ（delogo）、そしてファイルを出力せず stderr に検出結果だけ吐く解析専用の2つ（blackdetect、freeze-detect）。長尺キャプチャを編集に持ち込む前に「どこに事故が起きてるか」を洗い出すのに便利。

この記事は fqmpeg 3.0.3 の src/commands/ を実読して、各動詞が叩いている FFmpeg フィルタ・デフォルト値・出力ファイル名・そして --help だけだと見えない落とし穴を全部洗い出したものだ（stabilize は2パスで .trf 一時ファイルを落とす、denoise --target audio で全く別フィルタに化ける、deflicker --size は奇数必須、blackdetect と freeze-detect は出力ファイルが無い）。

この記事で得られるもの

• 8動詞をタスク別（補正/掃除/除去/検出）に選び分ける早見表
• 各動詞が実際に生成する FFmpeg コマンド（--dry-run で検証済み）
• 全コマンドのデフォルト値・範囲・出力ファイル名
• 「暗所手持ち撮影のブレブレ素材を救う」など実用レシピ3つ

8動詞の全体像

クラスタはタスク別に4グループに分かれる。グループを決めてから動詞を選ぶ流れがラク。

読み進める前に知っておくと得な3点：

1. stabilize は2パスで一時ファイルを落とす。 1パス目で vidstabdetect（動き解析）を走らせ、入力と同じディレクトリに .fqmpeg-transforms-<timestamp>.trf を書き出してから、2パス目で vidstabtransform がそれを読む。プロセス正常終了時に自動削除されるが、kill -9 で殺されると .trf が残骸として残るので手で消す必要がある。一時ファイルを作りたくない時は deshake を使う。
2. denoise --target audio は完全に別フィルタに化ける。 デフォルトの --target video は hqdn3d（空間・時間方向のビデオデノイズ）。--target audio にすると afftdn（FFTベースの音声ノイズ除去）に切り替わり、--strength のマッピングも違う。同じ動詞・2つのフィルタ・2つの意味なので、別行から --target audio がコピペで混入してると気づきにくい。
3. blackdetect と freeze-detect は出力ファイルを作らない。 -f null - で FFmpeg にフレームを処理だけさせて、フィルタの stderr 出力（検出されたイベントのタイムスタンプと長さ）以外を捨てる。grep で結果だけ拾うのが定番。

手ブレ補正

stabilize — vidstab 2パス（最高品質）

スタビライザの本命。1パス目でクリップ全体の動きを解析してから、2パス目で滑らかな逆変換をかける。クリップ全体を見てから判断するので deshake より精度が高い。

• ソース: src/commands/stabilize.js
• フィルタ（1パス目）: vidstabdetect=shakiness=N:result=<tmpfile>
• フィルタ（2パス目）: vidstabtransform=smoothing=M:input=<tmpfile>
• 要件: FFmpeg が --enable-libvidstab 付きでビルドされていること

$ npx fqmpeg stabilize input.mp4 --strength 10 --shakiness 5 --dry-run

  # Pass 1: Analyze motion
  ffmpeg -i input.mp4 -vf vidstabdetect=shakiness=5:result=transforms.trf -f null -
  # Pass 2: Apply stabilization
  ffmpeg -i input.mp4 -vf vidstabtransform=smoothing=10:input=transforms.trf -c:a copy input-stabilized.mp4

実行すると Pass 1/2: Analyzing motion... → Pass 2/2: Applying stabilization... の順で進行する。中間 .trf ファイルは入力と同じディレクトリに .fqmpeg-transforms-<timestamp>.trf という名前で書かれ、プロセス終了時に消える。ビルドに --enable-libvidstab が入ってないと1パス目で Unknown filter 'vidstabdetect' で落ちるので、その時は vidstab 入りの静的ビルド（BtbN's FFmpeg-Builds）に差し替えるか、deshake で代替。

--strength を 15 以上にすると経路を強く平滑化するのでクロップ量が増える（スタビライザはフレームをずらすための余白が必要）。歩きながら撮った素材なら 10 が安定。三脚に当てた程度のブレなら 20 でもまったく問題ない。

deshake — ビルトインの1パス deshake フィルタ

stabilize より速くて品質が落ちる代替案。FFmpeg ビルトインの deshake フィルタを使うのでリアルタイムにフレーム単位で動作する（解析パス不要）。

• ソース: src/commands/deshake.js
• フィルタ: deshake=rx=N:ry=M
• 要件: 特になし（FFmpeg ビルトイン）

$ npx fqmpeg deshake input.mp4 --rx 64 --ry 64 --dry-run

  ffmpeg -i input.mp4 -vf deshake=rx=64:ry=64 -c:a copy input-deshake.mp4

デフォルトの 64 ピクセル幅は手持ち撮影の大半でカバーできる。4K で微振動だけ取りたいような時は --rx 16 --ry 16 まで下げると処理が速くなりクロップ量も減る。stabilize との比較では、deshake は3〜5倍速いが特に長尺・方向性のある動きには弱い。試行錯誤を速く回したい時や最終出力じゃない時は deshake、本気の納品なら stabilize、で使い分ける。

ノイズ・アーティファクト除去

denoise — 動画 or 音声のノイズ除去（デュアルモード）

--target の値で挙動が完全に切り替わる動詞。デフォルトの --target video は hqdn3d フィルタ（空間・時間方向のデノイズ。ディテールを残しつつ輝度・色のノイズを抑える）。--target audio は afftdn（FFTベースのノイズ床下げ）に変わり、--strength のプリセットも別物のマッピングになる。

• ソース: src/commands/denoise.js
• フィルタ（video）: hqdn3d=<luma_spatial>:<chroma_spatial>:<luma_temporal>:<chroma_temporal>
• フィルタ（audio）: afftdn=nf=<noise_floor_dB>

$ npx fqmpeg denoise input.mp4 --target video --strength medium --dry-run

  ffmpeg -i input.mp4 -vf hqdn3d=5:4:5:4 -c:a copy input-denoised.mp4

$ npx fqmpeg denoise input.mp4 --target audio --strength medium --dry-run

  ffmpeg -i input.mp4 -af afftdn=nf=-30 -c:v copy input-denoised.mp4

暗所手持ち動画のノイズ除去なら --strength medium（デフォルト）が一番バランスがいい。--strength strong（7:6:7:6）は「デノイズ」というより「ソフトニング」に近くて、肌・布・葉っぱのテクスチャに違いが出る。音声ノイズ除去なら afftdn はモダンな定番で、-30 dB（medium）でほとんどのヒスは消える。背景の空調・モーター音みたいに低めの定常音なら -40（strong）に上げる。

モード切り替えの落とし穴を念押し：--target audio は動画ストリームをコピー（-c:v copy）し、--target video は音声ストリームをコピー（-c:a copy）する。両方かけたいなら順に2回叩く: denoise input.mp4 --target video -o tmp.mp4 && denoise tmp.mp4 --target audio。

deflicker — タイムラプスの輝度フリッカー均し

絞り優先AEがフレームごとに微妙に揺れて生じる輝度フリッカー（タイムラプスでよく出る）を、N フレームのスライディングウィンドウで平均化して均す。

• ソース: src/commands/deflicker.js
• フィルタ: deflicker=size=N
• 範囲: --size は 2〜129 フレーム（FFmpeg フィルタの制約、fqmpeg が呼び出し前に検証）

$ npx fqmpeg deflicker input.mp4 --size 5 --dry-run

  ffmpeg -i input.mp4 -vf deflicker=size=5 -c:a copy input-deflickered.mp4

--size 5（デフォルト）で5連続フレームを平均する。本物の明るさ遷移は壊さずに絞りハンチングだけ均すちょうどいい設定。夕焼けタイムラプスみたいに激しいフリッカーなら --size 7 or 9 まで上げる。fqmpeg は呼び出し前に --size を FFmpeg フィルタの許容範囲 2〜129 で検証して、範囲外は Error: size must be between 2 and 129 で早期エラーにする。偶数値も通る — 奇数（5, 7, 9, 11）は現在フレームを中心にウィンドウが対称になる移動平均の慣例であって FFmpeg 側の必須要件ではない。短いクリップでウィンドウが尺の大半を覆ってしまうと頭と尻のフレームが不安定になるので、trim で安定区間だけ切り出してから流すのがいい。

deblock — 圧縮ブロックノイズ除去

激しく圧縮された YouTube 再エンコ素材や、古い WhatsApp 動画でよく見るマクロブロック格子を消す動詞。FFmpeg の deblock フィルタを weak モード固定で叩き、強度から alpha/beta を線形マップする。

• ソース: src/commands/deblock.js
• フィルタ: deblock=filter=weak:alpha=A:beta=A（A = strength / 100）

$ npx fqmpeg deblock input.mp4 --strength 50 --dry-run

  ffmpeg -i input.mp4 -vf deblock=filter=weak:alpha=0.50:beta=0.50 -c:a copy input-deblocked.mp4

--strength 50（デフォルト）はほどよい強度。ブロック境界は減らしつつ細かい絵柄は保てる。--strength 80 を超えると「画面全体がソフトフォーカス」みたいになって本来欲しい結果じゃなくなる。軽く圧縮された素材（空のグラデーションと肌だけ気になる程度）なら --strength 20–30 で十分。filter=weak モードは決め打ちで、filter=strong モードは検証中の素材で過剰な平滑化を起こすことが多かったので fqmpeg からは出していない。どうしても strong を使いたい場合は --dry-run の出力を編集して直接 FFmpeg を叩く。

オブジェクト除去

delogo — 固定位置のロゴ消去

矩形領域を、その周囲のピクセルから補間して隠す動詞。動かないロゴ・チャンネルバグ・透かしを消すのに向いている。

• ソース: src/commands/delogo.js
• フィルタ: delogo=x=X:y=Y:w=W:h=H
• 位置引数 — 入力ファイル と x:y:w:h 領域

$ npx fqmpeg delogo input.mp4 10:10:120:60 --dry-run

  ffmpeg -i input.mp4 -vf delogo=x=10:y=10:w=120:h=60 -c:a copy input-delogo.mp4

領域のフォーマットは厳密で、x:y:w:h の4つの正の整数。負数・小数・パーツ抜けはすべて Error: region must be x:y:w:h で落ちる。x/y は箱の左上座標、w/h が幅と高さ。マージンを足したくなる気持ちは分かるが、フィルタは箱のすぐ外側のピクセルから補間するので、ピッタリの箱の方がきれいに仕上がる。ロゴにアンチエイリアスがかかってる場合は各辺2-3ピクセルずつ広げる。

止まってる絵柄に対してはよく効くが、動くロゴ・流れるテロップ・点滅バナーには使えない。トラッキングが必要なら fqmpeg の外でやる仕事になる。また、フレームの大半を覆うような巨大領域に対しては補間で再構成できる範囲を超えるので、delogo の出番は「絵柄全体に対して小さい比率の箱」に限られる。

検出（解析のみ）

ここの2動詞は出力ファイルを作らない。検出フィルタに流して -f null - で破棄し、フィルタが stderr に吐く検出結果（タイムスタンプと長さ）だけを残す。長尺キャプチャの中の事故（90分の画面録画が途中で固まった、テープ起こしの黒コマ区間など）を編集前にざっと洗い出すための動詞だ。

blackdetect — 黒シーン検出

ほぼ真っ黒の区間を検出する。長尺キャプチャの中のフェードアウト位置、テープ録画の「信号が切れた」区間を探すのに使う。

• ソース: src/commands/blackdetect.js
• フィルタ: blackdetect=d=<duration>:pix_th=<threshold>
• 出力: ファイルなし — stderr に [blackdetect @ ...] black_start:N black_end:M black_duration:D の形で出る

$ npx fqmpeg blackdetect input.mp4 --threshold 0.98 --duration 0.5 --dry-run

  ffmpeg -i input.mp4 -vf blackdetect=d=0.5:pix_th=0.98 -f null -

stderr を grep に流して検出行だけ拾うのが定番：

npx fqmpeg blackdetect input.mp4 2>&1 | grep "black_start"
# [blackdetect @ 0x...] black_start:12.345 black_end:14.567 black_duration:2.222
# [blackdetect @ 0x...] black_start:120.0 black_end:121.5 black_duration:1.5

「黒」が実は暗いグレー（圧縮ノイズ・暗所漏れ）の場合は --threshold を 0.95 まで下げる。短いシーン間の黒（0.5秒）まで拾うとうるさいなら --duration 2 以上に上げて「長い間（イントロ/エンディングのフェード）」だけ取る。検出後の動線は、タイムスタンプを trim や split に流して黒位置でクリップを切り出す、が王道。

freeze-detect — フリーズフレーム検出

絵柄が止まっている（フレームが「凍る」）区間を検出する。画面録画が途中でハングした、エンコードのグリッチで同じフレームが数秒繰り返された、みたいな事故を見つけるのに便利。

• ソース: src/commands/freeze-detect.js
• フィルタ: freezedetect=n=<noise>:d=<duration>
• 出力: ファイルなし — stderr に freeze_start, freeze_duration, freeze_end が出る

$ npx fqmpeg freeze-detect input.mp4 --duration 2 --noise 0.001 --dry-run

  ffmpeg -i input.mp4 -vf freezedetect=n=0.001:d=2 -f null -

npx fqmpeg freeze-detect input.mp4 2>&1 | grep "freeze_"
# [freezedetect @ 0x...] lavfi.freezedetect.freeze_start: 45.5
# [freezedetect @ 0x...] lavfi.freezedetect.freeze_duration: 8.3
# [freezedetect @ 0x...] lavfi.freezedetect.freeze_end: 53.8

デフォルトの --noise 0.001 は鋭敏で、完全な複製フレーム（ハング録画の典型）を確実に捕まえる。「ほぼ凍ってる」区間（ウェビナーでスライドが何分も変わらないが、エンコーダは微妙に違うフレームを吐き続けてるケース）まで拾いたいなら 0.01 まで緩める。--duration 2 は短い正常なポーズ（カットの間など）を無視するので、細かく検出したい時は 0.5 まで下げる。

実用レシピ

各レシピは複数動詞を組み合わせた、実際に使うワークフロー。

レシピ1: 暗所手持ち撮影のブレブレ素材を救う

夕暮れに手持ちで撮ったクリップ — 目に見える手ブレ、暗部の目立つノイズ、低ビットレート由来の軽いブロックノイズ。ゴール: まず手ブレを止めてから、汚れを落とす。

# Step 1: 先に手ブレ補正 — denoise は安定した入力じゃないと時間方向の平均が効きにくい
npx fqmpeg stabilize clip.mp4 --strength 10 --shakiness 5
# → clip-stabilized.mp4

# Step 2: 動画デノイズ medium
npx fqmpeg denoise clip-stabilized.mp4 --target video --strength medium
# → clip-stabilized-denoised.mp4

# Step 3 (任意): まだブロックノイズが見えるなら deblock
npx fqmpeg deblock clip-stabilized-denoised.mp4 --strength 30
# → clip-stabilized-denoised-deblocked.mp4

順序が大事。 デノイズより手ブレ補正が先。hqdn3d は時間方向にフレームを平均する処理を含んでいて、カメラが揺れているとフレームごとに微妙に画角がズレているせいで、平均化がずれた画素同士になりノイズ除去が効きにくくなる。安定化済みの入力なら時間方向の平均が設計通りに働く。

本当に暗い場所で撮った素材なら、このパイプラインの後に color 動詞で輝度・コントラストを補正 するのも組み合わせると効く。デノイズはどうしても中間色のコントラストを少し潰すので、--gamma 1.1 でミッドトーンを持ち上げるとパキッとする。

レシピ2: 長尺画面録画の事故シーンを見つけて切り出す

4時間の画面録画で、途中のどこかでキャプチャがフリーズしている。ゴール: フリーズ位置を見つけて、直前で切る。

# Step 1: 5秒以上のフリーズだけ拾う
npx fqmpeg freeze-detect recording.mp4 --duration 5 2>&1 | grep "freeze_"
# [freezedetect @ ...] freeze_start: 7230.5
# [freezedetect @ ...] freeze_duration: 45.2
# [freezedetect @ ...] freeze_end: 7275.7

# Step 2: フリーズ直前まででトリム
npx fqmpeg trim recording.mp4 --start 0 --end 7230
# → recording-trimmed.mp4

# Step 3 (任意): 黒コマ（信号断）もついでに見ておく
npx fqmpeg blackdetect recording.mp4 --duration 1 2>&1 | grep "black_start"

grep でフィルタ行だけ抜き出すと、FFmpeg の進捗ログに埋もれず検出結果だけ読める。両方を1パスでやりたい時は FFmpeg を直接叩いて2つのフィルタを連結する必要がある（fqmpeg は「1動詞=1フィルタ」が原則）。長尺ならまず npx fqmpeg split recording.mp4 --chunks 4 でチャンクに分けて並列に検出を回す方が早いケースもある。

レシピ3: テレビ録画からチャンネルロゴを消す

右上にステーションバグが入った録画を整理する。ゴール: ロゴを消して、ついでに元素材のブロックノイズも軽く均す。

# Step 1: 1フレーム抜き出してロゴの座標を測る
npx fqmpeg snapshot recording.mp4 --time 5 -o frame.png
# frame.png を画像ビューアで開いてロゴの矩形をピクセル単位で測定。
# 例: x=1750 y=20, 150x80 ピクセル。

# Step 2: ロゴ消去
npx fqmpeg delogo recording.mp4 1750:20:150:80
# → recording-delogo.mp4

# Step 3 (任意): 元素材のブロックノイズを deblock で軽く均す
npx fqmpeg deblock recording-delogo.mp4 --strength 40
# → recording-delogo-deblocked.mp4

ロゴの輪郭が滲んでる時は箱を各辺2-3ピクセルずつ広げる（タイトな 1750:20:150:80 ではなく 1748:18:154:84 のように）。補間はすぐ外側の参照ピクセルが綺麗じゃないと汚れる。動くバグ・回転する局ロゴには delogo は効かないので、動く範囲を全部覆う矩形を切ると目立つパッチが残るのを覚悟して使うことになる。

よくある質問

stabilize と deshake どちらを使うべき？

stabilize は vidstab 2パスで、特に長尺・方向性のあるショット（歩き撮り・車載）で目に見えて滑らかな結果になる。ただし FFmpeg を --enable-libvidstab 付きでビルドしてある必要がある。deshake は1パスで素の FFmpeg に入っていて、3〜5倍速い。試行錯誤や vidstab が無いビルドなら deshake、本気の最終納品なら stabilize、で使い分ける。

stabilize が .fqmpeg-transforms-*.trf を残していくのはバグ？

バグじゃない — プロセスが正常終了する時に削除される登録がある。kill -9 や SIGKILL で強制終了するとクリーンアップフックが走らないので残骸になる。手動で消して大丈夫（rm .fqmpeg-transforms-*.trf を入力と同じディレクトリで）。このファイルは1パス目の動き解析データなので、実行中は消さない。

deflicker --size の有効範囲は？

FFmpeg の deflicker フィルタは size 値 2〜129 フレームを受け付ける（デフォルト 5）— FFmpeg 6.1.1 の ffmpeg -h filter=deflicker で確認済み。fqmpeg はこの範囲を呼び出し前に検証して範囲外は明示的なエラーで落とす。偶数値（例: --size 4）もフィルタ自体は受理する。奇数（5, 7, 9, 11）は現在フレームを中心にウィンドウが対称になる移動平均の慣例で広く使われるが、FFmpeg 側の必須要件ではない。

denoise --target audio と --target video を1コマンドで両方かけられる？

不可。元フィルタ（動画は hqdn3d、音声は afftdn）が違う場所（-vf vs -af）に置く必要があるし、コンパニオン側のコーデックコピー（-c:a copy / -c:v copy）も逆。denoise clip.mp4 --target video -o tmp.mp4 && denoise tmp.mp4 --target audio のように2回叩くか、両方の --dry-run を読んでフィルタ文字列を組み合わせた FFmpeg を手で叩く。

blackdetect が「黒シーンなし」って言うのに目で見ると黒コマがある

--threshold が高すぎ（録画ハードの「黒」が実は暗いグレー）か、--duration が長すぎ（実際の黒区間が下限未満）。--threshold 0.90 --duration 0.2 まで緩めて検出範囲を広げてみる。pix_th は「黒輝度しきい値（デフォルト 0.10 luma）より暗いピクセルの比率がこの値以上ならフレームを黒判定」というロジックなので、0.98 だと「98% のピクセルがほぼ真っ黒」が条件になり、ノイズ混じりの「黒」だと判定されない。

delogo の出力が滲んだパッチに見える — 直せる？

フィルタは周囲ピクセルからの補間で再構成しているので、見えないディテールを復元することはできない。3つの対策: (1) 箱をロゴの輪郭ピッタリまで詰める — マージンが大きいほど補間範囲が広がって粗が目立つ; (2) 背景が高ディテール（葉っぱ・水面・テキスト）の場合は補間でどうにもならない — 受け入れるか、実エディタで領域差し替え; (3) ロゴが平坦な背景（空・壁）の上にあるなら delogo は普通に効くので、ダメ元でまず試す。

これらの動詞は VFR（可変フレームレート）ソースで動く？

stabilize, denoise, deflicker, deblock はすべてフレーム単位の処理なので VFR でも壊れない。ただし出力の VFR パターンが保たれるかは FFmpeg のデフォルト次第。blackdetect と freeze-detect は PTS ベースでタイムスタンプを報告するので VFR でも動くが、報告される時間はフレーム数じゃなく実時間。フレーム精度で検出したいなら先に npx fqmpeg fps input.mp4 --fps 30 で CFR に変換する。

世代劣化を避けるために複数のクリーンアップ動詞を1パスで組み合わせられる？

fqmpeg 経由ではできない — 各動詞が1出力を生成して再エンコードする。H.264 → H.264 を CRF 23 で重ねた時の世代劣化は小さいが3〜4世代重ねれば現れる。回避策2つ: (1) 中間ステップだけ品質を上げる（--dry-run の出力を編集して -crf 18 やロスレス）; (2) fqmpeg をバイパスして、各動詞の --dry-run のフィルタ文字列を集めて1つの FFmpeg コマンド -vf "filter1,filter2,filter3" として実行する。

まとめ

C7 の8動詞は、グレーディングや圧縮の前段で叩く「素材を整える」ための動詞群：

• stabilize, deshake で手ブレ補正（vidstab 2パス vs ビルトイン1パス — 品質と速度で選ぶ）
• denoise, deflicker, deblock でノイズ・輝度フリッカー・ブロックノイズ除去（denoise --target audio で完全に別フィルタに化ける、deflicker --size は奇数必須）
• delogo で固定領域のオブジェクト除去（平坦な背景には効く、ディテール背景には弱い）
• blackdetect, freeze-detect で長尺キャプチャの解析専用スキャン（出力ファイルなし — stderr を grep で拾う）

全動詞で --dry-run を付ければ生成される FFmpeg コマンドが見えるので、デフォルトでは足りない時（deblock を filter=strong で叩きたい、世代劣化を避けるためにフィルタを連結したい、delogo の領域を非矩形にしたい）はコマンドをコピーして FFmpeg を直接叩けばいい。fqmpeg 全体の地図は fqmpeg 完全ガイド を参照。