導入
**

Libavfilter は Libav のフィルタリング API である。これは非推奨になった 'vhooks' の代わりとなるものであり、Google Summer of Code プロジェクトとして始まった。

ただ、コードにはいまだ深刻なバグがあるかもしれず、また API や ABI はまだ安定しているとみなすべきではないことに注意すること!

チュートリアル
*******

libavfilter では、フィルターに複数の入力と複数の出力を持つことができる。可能なことを図で説明するため、ある複雑なフィルタのグラフを用いることができる。例えば、次のようなものである:

     input --> split --> fifo -----------------------> overlay --> output
                 |                                        ^
                 |                                        |
                 +------> fifo --> crop --> vflip --------+

これはストリームを2つのストリームに分割し、1つを crop フィルターと vflip フィルターを通じて送り、上にオーバーレイしてもう一方のストリームに合併し戻す。これを成し遂げるために次のようなコマンドを用いることができる:

     ./avconv -i input -vf "[in] split [T1], fifo, [T2] overlay=0:H/2 [out]; [T1] fifo, crop=iw:ih/2:0:ih/2, vflip [T2]" output

結果として出力中で映像の上半分は鏡像として下半分に映るだろう。

映像フィルターは avconv または avplay に渡される -VF オプションを用いて読み込まれる。同じ線形な連鎖に含まれるフィルターはコンマによって区切られる。我々の例では、 SPLIT, FIFO, OVERLAY は1つの線形な連鎖に含まれ、FIFO, CROP, VFLIP はもう1つに含まれる。線形の連鎖が結合するポイントは角カッコで囲まれた名前によってラベルづけされる。我々の例では、それは [T1] と [T2] である。特別な (マジック)ラベル [IN] および [OUT] は映像が入力または出力するポイントである。

フィルターによっては入力にパラメータのリストをとるものがある: それらはフィルター名の後に1つの等号、およびそれぞれセミコロンで区切られて指定される。

映像入力を持たない、いわゆる SOURCE FILTERS が存在し、将来的には映像出力を持たない SINK FILTERS を予定している。

graph2dot
*********

graph2dot プログラムは Libav の tools ディレクトリに含まれており、フィルターの図の記述をパースして対応する dot 言語のテキスト表現を出すために使うことができる。

コマンド:

     graph2dot -h

を実行すると graph2dot の使い方が分かる。

そして dot での表現を(graphviz のプログラムにある)dot プログラムに渡して、フィルター図のグラフィカルな表現が得られる。

例えばコマンドの列:

     echo GRAPH_DESCRIPTION | \
     tools/graph2dot -o graph.tmp && \
     dot -Tpng graph.tmp -o graph.png && \
     display graph.png

によって文字列 GRAPH_DESCRIPTION で記述される図を表す画像を作成し表示することができる。

     [file filters.texi not included]

利用可能な映像フィルター
************

Libav ビルドを構成(configure)する際に、既存の映像フィルターをいずれも無効にすることができる。構成の出力(configure output)にはそのビルドに含まれる映像フィルターが表示されている。

以下は現時点で利用できる映像フィルターの説明である。

crop
====

入力映像を X:Y:WIDTH:HEIGHT に切り取る。

     ./ffmpeg -i in.avi -vf "crop=0:0:0:240" out.avi

X と Y は出力(切り取られない)範囲の左上角の位置を指定する。

X と Y の既定の値は0。

パラメータ WIDTH と HEIGHT は出力(切り取られない)範囲の幅と高さを指定する。

0という値は左上角を位置 x:y にして定まる範囲で可能な最大のサイズと解釈される。

例えば、パラメータ:

     "crop=100:100:0:0"

は左上角を位置 100:100 とし、右下角を入力画像の右下角に合わせるような矩形に範囲を定める。

WIDTH と HEIGHT の既定の値は0。

format
======

入力映像を指定されたピクセル形式の1つに変換する。 Libavfilter は次のフィルターの入力にサポートされているうちの1つを選択しようと試みる。

このフィルターは、例えば ``yuv420p:monow:rgb24'' のように、``:'' によって区切られたピクセル形式名のリストを引数として受け取る。

次のコマンド:

     ./ffmpeg -i in.avi -vf "format=yuv420p" out.avi

は入力映像を形式 ``yuv420p'' に変換する。

noformat
========

次のフィルターの入力に指定されたピクセル形式のいずれも使わないように libavfilter に強制する。

このフィルターは、例えば ``yuv420p:monow:rgb24'' のように、``:'' で区切られたピクセル形式名のリストを引数として受け取る。

次のコマンド:

     ./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi

は、``yuv420p'' と異なる形式のどれかを使って vflip フィルターに入力するように libavfilter に強制する。

null
====

ソースを変更せずに出力に渡す。

pad
===

入力画像に対してパディングを加え、元の入力を与えられた座標 X, Y に配置する。

次のようなパラメータを受け取る: WIDTH:HEIGHT:X:Y:COLOR。

受け取るパラメータの説明は以下の通り。

width, height

     パディングを加えた出力画像のサイズを指定する。WIDTH または HEIGHT としての値が0の場合、対応する入力サイズが出力として用いられる。

     WIDTH および HEIGHT の既定値は0。

x, y

     出力画像の左上隅を基準にして、パディング領域における入力画像を配置するのオフセットを指定する。

     X および Y の既定値は0。

color

     パディング領域の色を指定する。色の名前もしくは 0xRRGGBB[AA] 数列をとりうる。

     COLOR の既定値は ``black''。

scale
=====

入力映像を WIDTH:HEIGHT に拡縮し、かつ/または画像形式を変換する。

例えば次のコマンド:

     ./ffmpeg -i in.avi -vf "scale=200:100" out.avi

は入力映像を200x100のサイズに拡縮する。

入力画像形式が次のフィルターが要求しているものと異なるなら、この scale フィルターは入力を要求されている形式に変換する。

WIDTH または HEIGHT の値が0なら、出力には対応する入力サイズが用いられる。

WIDTH または HEIGHT の値が-1なら、それぞれの出力サイズについて、この scale フィルターは入力画像の縦横比を維持する値を用いる。

WIDTH と HEIGHT の既定の値は0。

slicify
=======

入力映像のイメージを複数のスライスとして次の映像フィルターに渡す。

     ./ffmpeg -i in.avi -vf "slicify=32" out.avi

このフィルターはスライスの高さをパラメーターとして受け取る。このパラメーターが指定されていなければ、16という既定値を使う。

フィルターの連鎖の最初にこれを追加すると、メモリーキャッシュをより良く使ってフィルタリングがより速くなる。

unsharp
=======

入力映像をシャープにする、またはぼやけさせる。次のパラメータを受けつける:

名前   説明   最小値   最大値   既定値
LUMA_MSIZE_X
Luma matrix 水平サイズ
3
13
5
LUMA_MSIZE_Y
Luma matrix 垂直サイズ
3
13
5
LUMA_AMOUNT
Luma effect 強度
-2.0
5.0
1.0
CHROMA_MSIZE_X
Chroma matrix 水平サイズ
3
13
0
CHROMA_MSIZE_Y
Chroma matrix 垂直サイズ
3
13
0
CHROMA_AMOUNT
Chroma effect 強度
-2.0
5.0
0.0

量を負の値にすると入力映像をぼやけさせ、正の値にするとシャープにする。全てのパラメータは省略可能であり、既定の値は文字列 '5:5:1.0:0:0:0.0' と同等である。

     # luma sharpen effect パラメータを強くする
     unsharp=7:7:2.5

     # luma および chroma パラメータを両方強くぼやけさせる
     unsharp=7:7:-2:7:7:-2

     # ffmpeg とともに既定値を使う
     ./ffmpeg -i in.avi -vf "unsharp" out.mp4

vflip
=====

入力映像を垂直に反転する。

     ./ffmpeg -i in.avi -vf "vflip" out.avi

利用可能な映像ソース
**********

以下が現在利用できる映像ソースの説明です。

nullsrc
=======

Null 映像ソースは画像を一切返しません。主にテンプレートとして有用で、分析やデバッギングのツールで使われるものです。

省略可能なパラメータとして WIDTH:HEIGHT という形の文字列を受け取ります。ここで WIDTH と HEIGHT は設定されるソースの大きさを指定します。

WIDTH と HEIGHT の既定値は(CIF サイズ形式に対応して)それぞれ 352 と 288 です。

利用可能な映像シンク
**********

以下が現在利用可能な映像シンクの説明です。

nullsink
========

Null 映像シンクは、入力映像について全く何もしません。主にテンプレートとして有用であり、分析やデバッギングのツールで使われるものです。