Libavfilter Documentation


Table of Contents


1 導入

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

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

2 チュートリアル

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 を予定している。

3 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 で記述される 図を表す画像を作成し表示することができる。

4 フィルターグラフの説明

フィルターグラフは結びつけられたフィルターの有向グラフです。サイクルを含んで いてもよく、フィルターの対の間で複数のリンクがあってもかまいません。 それぞれのリンクは、入力を受け取るフィルター側に結びつけられた1つの 入力パッドと、出力を受け取るフィルターに関係付けられた1つの出力パッドを 持ちます。

フィルターグラフの各フィルターはアプリケーションに登録されたフィルタークラスの インスタンスであり、このクラスはその機能とそのフィルターの入力および出力の パッドの数を定義します。

入力パッドを持たないフィルターは"ソース"と呼ばれ、出力パッドを持たないフィルターは "シンク"と呼ばれます。

4.1 フィルターグラフの構文

フィルターグラフはテキストでの表記を使って表現することができます。 この表記は avconv の ‘-filter’/‘-vf’ および ‘-filter_complex’ オプションや、avplay-vf オプションで認識され、 ‘libavfilter/avfiltergraph’ 内の avfilter_graph_parse()/avfilter_graph_parse2() 関数で定義されています。

フィルターチェーンは関係するフィルターの列からなり、それぞれ その列での直前のものに関係しています。フィルターチェーンは","で区切られた フィルター記述のリストで表現されます。

フィルターグラフはフィルターチェーンの列からなります。 フィルターチェーンの列は";"で区切られたフィルターチェーン記述のリストで 表現されます。

フィルターは次の形の文字列で表現されます: [in_link_1]...[in_link_N]filter_name=arguments[out_link_1]...[out_link_M]

filter_name は記述されるフィルターがインスタンスとなるフィルター クラスの名前で、プログラムに登録されているフィルタークラスの名前でなければ なりません。 フィルタークラスの名前には省略可能な文字列"=arguments"が 続きます。

arguments はフィルターのインスタンスを初期化するために 用いられるパラメータを含む文字列で、以下のフィルターの説明の中で 説明されています。

引数のリストは最初と最後を示す文字"’"を使ってクォートすることができ、 文字’\’でクォートされたテキスト内でこの文字をエスケープするために 使えます; さもなくば、引数の文字列は次の(集合"[]=;,"に属する)特殊文字 が出てくるところで終了するものと見なされます。

フィルターの名前と引数には省略可能なリンクラベルのリストが前や後ろに つきます。 リンクラベルによってフィルターの出力および入力パッドに関連付けられたリンクに 名前をつけることができます。前につくラベルが in_link_1 ... in_link_N ならフィルターの入力パッドに関連付けられ、後ろにつくラベル out_link_1 ... out_link_M は出力パッドに関連付けられます。

フィルターグラフに同じ名前の2つのリンクラベルが見つかる場合、 対応する入力および出力パッドの間のリンクが作成されます。

出力パッドにラベルがない場合、それは既定ではそのフィルターチェーンの 次のフィルターのラベルがない入力パッドにリンクされます。 例えばフィルターチェーンで:

nullsrc, split[L1], [L2]overlay, nullsink

となっていたら、split フィルターのインスタンスは2つの出力パッドを 持たなければならず、overlay フィルターのインスタンスは2つの入力パッドを 持ちます。split の最初の出力パッドは"L1"とラベルがついています。 2つ目の出力パッドは overlay の2つ目の入力パッドにリンクされます。 これらはどちらもラベルがついていません。

完全なフィルターチェーンでは全てのラベルのないフィルター入力および出力 パッドは結びついていなければなりません。フィルターグラフは、その全ての フィルターチェーンで全ての入力および出力パッドが結びついているときに 妥当と見なされます。

Libavfilter はフォーマット変換が必要な場合にスケールフィルターを自動的に 入れます。filtergraph の説明に sws_flags=flags; を先頭につけることで、これらの自動で挿入されるスケーラーに対する swscale フラグを指定できます。

以下はフィルターグラフの構文の BNF 記述です:

NAME             ::= 英数文字および '_' の列。
LINKLABEL        ::= "[" NAME "]"
NAME             ::= 英数文字および '_' の列
LINKLABEL        ::= "[" NAME "]"
LINKLABELS       ::= LINKLABEL [LINKLABELS]
FILTER_ARGUMENTS ::= 文字の列(最終的にクォートされる)
FILTER           ::= [LINKNAMES] NAME ["=" ARGUMENTS] [LINKNAMES]
FILTERCHAIN      ::= FILTER [,FILTERCHAIN]
FILTERGRAPH      ::= [sws_flags=flags;] FILTERCHAIN [;FILTERGRAPH]

5 音声フィルター

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

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

5.1 aformat

入力音声を指定されたフォーマットの1つに変換する。このフレームワークは 変換を最小限にするような最適な形式を折衝します。

このフィルターは次の名前のついたパラメーターを受け取ります:

sample_fmts

要求するサンプルフォーマットのカンマで区切られたリスト

sample_rates

要求するサンプルレートのカンマで区切られたリスト

channel_layouts

要求するチャンネルレイアウトのカンマで区切られたリスト

パラメーターが省略された場合、全ての値が許されます。

出力に符号無し8ビットあるいは符号付き16ビットステレオを強制する例:

aformat=sample_fmts\=u8\,s16:channel_layouts\=stereo

5.2 amix

複数の音声入力を単一の出力にまとめる。

例えば

avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT

は3つの入力音声ストリームを、最初の入力と同じ時間長になるように1つの出力にまとめ、 3秒間のドロップアウト遷移時間を加える。

このフィルターは以下の名前のついたパラメーターを受け取る:

inputs

入力の数。指定されていなければ、既定では2。

duration

ストリームの末尾を決めるやり方。

longest

最長の入力の長さに揃える。(既定値)

shortest

最短の入力の長さに揃える。

first

最初の入力の長さに揃える。

dropout_transition

遷移時間、秒単位。入力ストリームが終わった際に音量を再正規化する。 既定値は2秒。

5.3 anull

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

5.4 asplit

入力音声をいくつかの同一の出力に分割する。

このフィルターは出力の数を指定する1つのパラメーターを受け取る。 指定されていなければ、既定では2になる。

例えば

avconv -i INPUT -filter_complex asplit=5 OUTPUT

は入力音声の5つのコピーを作成する。

5.5 asyncts

必要なら、縮める/伸ばす/サンプルを落とす/無音サンプルを追加することによって、 音声データをタイムスタンプと同期する。

このフィルターは次の名前のついたパラメーターを受け取る:

compensate

タイムスタンプに合わせるようにデータの伸縮を有効にする。 既定では無効。無効の場合、時間ギャップは無音で埋められる。

min_delta

サンプルの追加/削除をうながすタイムスタンプと音声データの(秒単位の)最小差。 既定値は0.1。このフィルターによって完全でない同期になっていたら、このパラメーターを 0に設定して試すとよい。

max_comp

秒間のサンプルの伸縮の最大値。compensate=1のときのみ関係する。 既定値は500。

first_pts

最初の pts がこの値になるべきということを仮定する。 これによってストリームの開始時点でパディング/トリミングができる。既定では、 最初のフレームで pts がどのくらいかについてどのような仮定もなされないので、 パディングもトリミングもなされない。例えば、もし音声ストリームが映像ストリームの 後に開始するなら、これを0に設定することで無音状態で開始するようパッドできる。

5.6 channelsplit

入力音声ストリームの各チャンネルをを別々の出力ストリームに分割する。

このフィルターは以下の名前のついたパラメーターを受け取る:

channel_layout

入力ストリームのチャンネルレイアウト。既定では"stereo"。

例えば、ステレオの入力 MP3 ファイルを仮定すると

avconv -i in.mp3 -filter_complex channelsplit out.mkv

によって2つの音声ストリームを含む出力 Matroska ファイルを作成し、 1つは左チャンネルだけ含み、もう1つは右チャンネルだけ含む。

5.1 WAV ファイルをチャンネルごとのファイルに分割するには

avconv -i in.wav -filter_complex
'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
side_right.wav

5.7 channelmap

入力チャンネルを新しい場所にマップし直す。

このフィルターは以下の名前のついたパラメーターを受け取る:

channel_layout

出力ストリームのチャンネルレイアウト

map

入力から出力へのチャンネルをマップする。引数はカンマで区切られたマッピングのリストで、 それぞれが in_channel-out_channel または in_channel の 形をしている。in_channel は入力チャンネルの名前(例えば前方左なら FL)か、 入力チャンネルレイアウトでのインデックス。out_channel は出力チャンネルの 名前、または出力チャンネルレイアウトでのインデックス。out_channel が与え られていなければ、暗黙にゼロから始まりマッピングごとに1つずつ増えていくインデックス になる。

マッピングがあれば、このフィルターは入力チャンネルから出力チャンネルへ インデックスを保存するように暗黙にマッピングする。

例えば、5.1+downmix 入力 MOV ファイルを仮定すると

avconv -i in.mov -filter 'channelmap=map=DL-FL\,DR-FR' out.wav

で入力の downmix チャンネルからステレオとしてタグづけされた出力 WAV ファイルを 作成する。

AAC のネイティブチャンネルオーダーで誤ってエンコードされた 5.1 WAV を修正するには

avconv -i in.wav -filter 'channelmap=1\,2\,0\,5\,3\,4:channel_layout=5.1' out.wav

5.8 join

複数の入力ストリームを1つのマルチチャンネルストリームにまとめる

このフィルターは以下の名前のついたパラメーターを受け取る:

inputs

入力ストリームの数。既定では2。

channel_layout

希望する出力チャンネルレイアウト。既定ではステレオ。

map

入力から出力へのチャンネルをマップする。引数はカンマで区切られたマッピングのリストで、 それぞれが input_idx.in_channel-out_channel の形をしている。 input_idx は0から始まる入力ストリームのインデックス。in_channel は 入力チャンネルの名前(例えば前方左なら FL)、または指定された入力ストリームでのインデックス。 out_channel は出力チャンネルの名前。

このフィルターはマッピングが明示的に指定されていなければ推定しようとする。 まず利用されていない対応する入力チャンネルを探そうとし、それに失敗したら最初の 利用されていない入力チャンネルを選ぶ。

例えば、(適切にチャンネルレイアウトを設定して)3つの入力をまとめるには

avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT

6つの単一チャンネルのストリームから 5.1 出力を作るには:

avconv -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
'join=inputs=6:channel_layout=5.1:map=0.0-FL\,1.0-FR\,2.0-FC\,3.0-SL\,4.0-SR\,5.0-LFE'
out

5.9 resample

音声サンプルフォーマット、サンプルレート、およびチャンネルレイアウトをを変換する。 このフィルターは直接利用することを意図したものではなく、libavfilter によって 変換が必要になったときに常に自動的に挿入される。特定の変換を強制するには aformat フィルターを使うこと。

6 音声ソース

以下は現在利用可能な音声ソースの説明である。

6.1 anullsrc

Null 音声ソース、音声フレームを一切返さない。これは主にテンプレートとして 有用であり、分析/デバッギングツールの中で用いるためのものである。

これは次の形をした文字列を省略可能なパラメータとして受け取る: sample_rate:channel_layout

sample_rate はサンプルレートを指定し、既定では 44100 とされる。

channel_layout チャンネルレイアウトを指定し、整数値または チャンネルレイアウトを表す文字列をとれる。channel_layout の既定の 値は3であり、CH_LAYOUT_STEREO に対応する。

文字列とチャンネルレイアウトの値との間のマッピングについては ‘libavcodec/audioconvert.c’ にある channel_layout_map の定義を 確認すること。

いくつかの例は以下の通り:

# サンプルレートを48000 Hz に、チャンネルレイアウトを CH_LAYOUT_MONO に設定する。
anullsrc=48000:4

# 同じく
anullsrc=48000:mono

6.2 abuffer

音声フレームをバッファし、フィルターチェーンで利用できるようにする。

このソースはユーザーが提供するグラフの表現の一部にすることを意図したものではなく、 ‘libavfilter/buffersrc.h’ で定義されたインターフェイスを通じてプログラムを 呼ぶことによって挿入される。

これは次の名前のついたパラメーターを受け取る:

time_base

提出されたフレームのタイムスタンプのために使われる時刻ベース。これは浮動小数点数か numerator/denominator の形でなければならない。

sample_rate

音声サンプルレート。

sample_fmt

サンプルフォーマットの名前、av_get_sample_fmt_name() で返されるもの。

channel_layout

音声データのチャンネルレイアウト、av_get_channel_layout() で受け取ることの できる形。

全てのパラメーターは明示的に定義されている必要がある。

7 音声シンク

以下は現在利用可能な音声シンクの説明である。

7.1 anullsink

Null 音声シンク、入力音声に対し全く何もしない。これは主にテンプレートとして 有用であり、分析/デバッギングツールで用いるためのものである。

7.2 abuffersink

このシンクはプログラムでの使用のためのものである。このシンクに逹っしたフレーム は ‘libavfilter/buffersink.h’ で定義されているインターフェイスを使った プログラムを呼び出すことによって取得できる。

このフィルターはパラメーターを受け取らない。

8 映像フィルター

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

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

8.1 blackframe

(ほぼ)真っ黒なフレームを検出する。章の変わり目やコマーシャルを検出 するのに有用となりうる。出力される行は検出されたフレームのフレーム数、 黒のパーセンテージ、(分かるなら)ファイルでの位置もしくは-1、および 秒単位でのタイムスタンプからなる。

出力される行を表示するには、ログレベルを少なくとも AV_LOG_INFO に 設定する必要がある。

このフィルターは次の構文を受け取る:

blackframe[=amount:[threshold]]

amount は閾値以下にならなくてはならないピクセルのパーセンテージであり、 既定では98になる。

threshold はピクセルの値がこれを下回ると黒と見なされる閾値であり、 既定では32になる。

8.2 boxblur

入力映像に boxblur アルゴリズムを適用する。

このフィルターは次のパラメーターを受け取る: luma_power:luma_radius:chroma_radius:chroma_power:alpha_radius:alpha_power

Chroma および alpha パラメーターは省略可能であり、指定されていない場合 luma_radius および luma_power で設定されている既定値になる。

luma_radiuschroma_radius、および alpha_radius は 対応する入力平面にブラーをかけるために使うボックスのピクセルでの半径を 表す。これらは式であり、以下の定数を含むことができる:

w, h

ピクセルでの入力幅と高さ

cw, ch

ピクセルでの chroma 入力幅と高さ

hsub, vsub

水平および垂直 chroma サブサンプル値。例えばピクセルフォーマット "yuv422p" なら hsub は2、vsub は1である。

半径は非負の数でなくてはならず、luma および alpha については 式 min(w,h)/2 を越えてはならず、chroma 平面の場合は min(cw,ch)/2 を越えてはならない。

luma_powerchroma_power、および alpha_power は 対応する平面に適用される boxblur フィルターを何回適用するかを 表す。

以下はいくつかの例:

8.3 copy

入力ソースを変更せずに出力にコピーする。 主にテストの目的のために有用である。

8.4 crop

入力映像を out_w:out_h:x:y に切り取る。

このパラメータは以下の定数を含む表現である:

E, PI, PHI

e(オイラー数)、pi(ギリシャ文字のパイ)、PHI(黄金比)それぞれ対応する数学的近似値

x, y

x および y についての計算された値。これらは各新しいフレームで 評価される。

in_w, in_h

入力の幅および高さ

iw, ih

in_w および in_h と同じ

out_w, out_h

出力の(切り取られた)幅および高さ

ow, oh

out_w および out_h と同じ

n

0から始まる入力フレームの数

pos

入力フレームのファイルの中での位置、不明なら NAN

t

秒で表されたタイムスタンプ、入力タイムスタンプが不明なら NAN

パラメータ out_w および out_h は出力の(切り取られた)映像の 幅および高さのための表現を指定する。これらはフィルターのコンフィグレーション の時点で評価される。

out_w の既定値は "in_w" であり、out_h の既定値は "in_h" である。

out_w のための表現は out_h の値に依存することがあり、 out_h のための表現は out_w に依存することがあるが、 x および y の値には依存しないはずである。なぜなら x および yout_w および out_h の後で 評価からである。

パラメータ x および y は出力の(切り取られていない)領域 の左上隅の位置のための表現を指定する。これらは各フレームについて 評価される。評価された値が妥当でなければ、最も近い妥当な値に近似 される。

x の既定の値は "(in_w-out_w)/2" であり、y の既定の値は "(in_h-out_h)/2" である。これは入力画像の中央に切り取られた領域を 設定することになる。

x のための表現は y に依存することがあり、y の ための表現は x に依存することがある。

いくつかの例は以下の通り:

# サイズ 100x100 で入力領域の中央を切り取る
crop=100:100

# 入力映像の 2/3 のサイズで入力領域の中央を切り取る
"crop=2/3*in_w:2/3*in_h"

# 入力映像の中央を正方形に切り取る
crop=in_h

# 左上隅の位置を 100:100、右下隅を入力映像の右下隅に合わせて
# 矩形の範囲を定める
crop=in_w-100:in_h-100:100:100

# 左右のボーダーから10ピクセルを切り取り、上下のボーダーから20ピクセルを
# 切り取る
"crop=in_w-2*10:in_h-2*20"

# 入力画像の右下4分の1のみを残す
"crop=in_w/2:in_h/2:in_w/2:in_h/2"

# 黄金分割になるように縦を切り取る
"crop=in_w:1/PHI*in_w"

# 震動効果
"crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(n/10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(n/7)"

# タイムスタンプに依存した不規則なカメラ効果
"crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)"

# y の値に依存した x を設定する
"crop=in_w/2:in_h/2:y:10+10*sin(n/10)"

8.5 cropdetect

切り取るサイズを自動検出する。

切り取りに必要となるパラメータを計算し、ロギングのシステムを通じて推奨される パラメータを表示する。検出された寸法は入力映像の黒でない領域に対応する。

これは次の構文を受け取る:

cropdetect[=limit[:round[:reset]]]
limit

閾値、何もない(0)から全て(255)までを自由に選択することができる。 既定では24。

round

幅/高さが分割されるべき値、既定では16。 オフセットは自動的に映像の中心に調節される。 偶数の寸法のみ(4:2:2 の映像で必要となる)を得るには2を用いること。 たいていの映像コーデックでエンコーディングする際には16が最良。

reset

以前に検出された最大の映像領域をリセットし、現在の最適な 切り取り領域を検出し始めるのにどれだけのフレームを 過ぎてからにするかを決めるカウンター。 既定では0。

これはチャンネルのロゴが映像領域を歪ませる際に有用である。 0はリセットせず再生中に出てきた最大の領域を返すように 指示する。

8.6 drawbox

入力イメージに色付けされた箱を描く。

これは次の構文を受け取る:

drawbox=x:y:width:height:color
x, y

箱の左上隅を指定する。既定では0。

width, height

箱の幅および高さを指定する。0なら入力の幅および高さとして解釈される。 既定では0。

color

描く箱の色を指定する。(大文字小文字を区別しない)色の名前もしくは 列 0xRRGGBB[AA] をとりうる。

いくつかの例は以下の通り:

# 入力画像の縁に沿って黒い箱を描く
drawbox

# 50%の透明度の赤で箱を描く
drawbox=10:20:200:60:red@0.5"

8.7 drawtext

文字列のテキストまたは指定のファイルのテキストを libfreetype ライブラリ を使って映像の上に描画します。

このフィルターのコンパイルを有効にするには Libav を configure するときに --enable-libfreetype をつける必要があります。

またこのフィルターは strftime() 文字列を理解し、それに従って展開します。 strftime() のドキュメンテーションを確認してください。

このフィルターはf":" で区切られた key=value のペアのリストを パラメーターとして受け取ります。

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

fontfile

テキストを描画するのに使うフォントファイルです。パスを含めなければ なりません。このパラメーターは必須です。

text

描画されるテキストの文字列です。テキストは UTF-8 でエンコードされた 文字の列でなければなりません。 パラメーター textfile でファイルが指定されていない場合、 このパラメーターは必須です。

textfile

描画されるテキストを含むテキストファイルです。テキストは UTF-8 で エンコードされた文字の列でなければなりません。

パラメーター text でテキストの文字列が指定されていない場合、 このパラメーターは必須です。

text と textfile が両方指定されている場合はエラーになります。

x, y

映像フレーム内でテキストが描画される場所の位置です。 出力画像の左上隅からの相対位置です。 これらは overlay フィルターに似た式を受け取ります:

x, y

x および y の計算された値です。これらは新しい各フレームで 評価されます。

main_w, main_h

主要な入力幅および高さ

W, H

main_w および main_h と同じ

text_w, text_h

レンダリングされる幅および高さ

w, h

text_w および text_h と同じ

n

処理されるフレームの番号、0から始まる

t

秒単位でのタイムスタンプ、入力タイムスタンプが分からなければ NAN

x および y の既定値は0です。

fontsize

テキストを描画するためのフォントサイズです。 fontsize の既定値は16です。

fontcolor

フォントを描画するための色です。 文字列(例えば "red")か 0xRRGGBB[AA] の形式(例えば"0xff000033") で省略可能なアルファ値つきの形です。 fontcolor の既定値は "black" です。

boxcolor

テキストの周囲にボックスを描画するための色です。 文字列(例えば "red")か 0xRRGGBB[AA] の形式(例えば"0xff000033") で省略可能なアルファ値つきの形です。 fontcolor の既定値は "white" です。

box

背景色を使ってテキストの周囲を描画するために用いられます。 値は 1 (有効) または 0 (無効)です。 box の既定値は 0 です。

shadowx, shadowy

テキストの影のためのテキストの位置からの x および y の相対位置です。 これらは正または負の値をとれます。 既定値はどちらも "0" です。

shadowcolor

描画されるテキストの後ろの影を描画するために用いられる色です。 文字列(例えば "red")か 0xRRGGBB[AA] の形式(例えば"0xff000033") で省略可能なアルファ値つきの形です。 shadowcolor の既定値は "black" です。

ft_load_flags

フォントを読み込むために用いられるフラグです。

これらのフラグは libfreetype でサポートされているフラグに対応し、 以下の値の組み合わせです:

default
no_scale
no_hinting
render
no_bitmap
vertical_layout
force_autohint
crop_bitmap
pedantic
ignore_global_advance_width
no_recurse
ignore_transform
monochrome
linear_design
no_autohint
end table

既定値は "render" です。

詳しくは libfreetype の FT_LOAD_* フラグについてのドキュメンテーションに あたってください。

tabsize

タブを描画するためのスペースの数の大きさです。 既定値は 4 です。

fix_bounds

true なら、クリッピングを避けるようテキストの座標を確認し固定します。

例えば、コマンド:

drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"

は "Test Text" を FreeSerif フォントで、省略可能なパラメーターは既定値を 使って描画します。

コマンド:

drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
          x=100: y=50: fontsize=24: fontcolor=yellow@0.2: box=1: boxcolor=red@0.2"

は ’Test Text’ をサイズ 24 の FreeSerif フォントで(スクリーンの左上隅から) x=100 および y=50 の位置に、テキストを黄色、周囲のボックスを赤にして 描画します。テキストもボックスもどちらも 20% の透明度を持ちます。

パラメーターリストの中でスペースを使っていなければ、二重引用符はいらないという ことに注意してください。

libfreetype についてより詳しくは、以下を確認してください: http://www.freetype.org/.

8.8 fade

入力映像にフェードイン/フェードアウト効果を適用します。

これは次のパラメータを受け取ります: type:start_frame:nb_frames

type は効果の種類がフェードインなら "in"、フェードアウトなら "out" を指定します。

start_frame はフェード効果が適用される開始フレームの番号を指定 します。

nb_frames はフェード効果が持続しなくてはならないフレームの個数 を指定します。フェードイン効果の最後には出力映像は入力映像と同じ 度合いになり、フェードアウト遷移の最後には出力映像は完全に黒く なります。

以下はいくつかの使用例で、テストシナリオとしても有用です。

# 映像の最初の30フレームをフェードインします
fade=in:0:30

# 200フレームの映像で最後の45フレームをフェードアウトします
fade=out:155:45

# 1000フレームの映像で最初の25フレームをフェードインし、最後の25フレームをフェードアウトします
fade=in:0:25, fade=out:975:25

# 最初の5フレームを黒くし、5から24番フレームでフェードインします
fade=in:5:20

8.9 fieldorder

入力映像のフィールドオーダーを変換します。

このフィルターは、入力のインターレースされた映像を変換するために要求される フィールドオーダーを指定する単一のパラメーターを受け取ります。このパラメーターは 次の値のいずれかを取れます:

0 または bff

出力下部フィールドが先頭

1 または tff

出力上部フィールドが先頭

既定の値は "tff" です。

変換は1ラインずつ上もしくは下に画像内容をシフトし、かつ残りのラインに 適切な画像内容を充てることによって実現されます。 この手法は大抵のブロードキャストフィールドオーダー変換器と合っています。

入力映像にインターレースであるというフラグがない場合、または要求される 出力フィールドオーダーが与えられていれば、このフィルターはやってくる映像を 変更しません。

このフィルターは、下部フィールド先頭の PAL DV マテリアルを/へ変換する際に とても便利です。

例えば:

./avconv -i in.vob -vf "fieldorder=bff" out.dv

8.10 fifo

入力イメージをバッファし、かつ要求された時にそれらを送る。

このフィルターは主に libavfilter フレームワークによって自動的に 挿入される際に有用である。

このフィルターはパラメータを受け取らない。

8.11 format

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

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

以下にいくつかの例:

# 入力映像を形式 "yuv420p" に変換する
format=yuv420p

# 入力映像をリストにあるいずれかの形式に変換する
format=yuv420p:yuv444p:yuv410p

8.12 fps

フレームを必要に応じて重複させたり削除したりすることにより、映像を特定の コンスタントフレームレートに変換する。

このフィルターは以下の名前のついたパラメーターを受け取る:

fps

希望する出力フレームレート

8.13 frei0r

入力映像に frei0r 効果を適用する。

このフィルターのコンパイルを有効にするには、frei0r ヘッダをインストール し、–enable-frei0r とともに Libav を configure すること。

このフィルターは次の構文をサポートする:

filter_name[{:|=}param1:param2:...:paramN]

filter_name はロードする frei0r 効果の名前である。環境変数 FREI0R_PATH が定義されていれば、FREIOR_PATH の中のコロンで 区切られたリストで指定されたディレクトリのいずれかから frei0r 効果が 探索され、さもなくば次の順番で標準的な frei0r のパスから探索される: ‘HOME/.frei0r-1/lib/’、‘/usr/local/lib/frei0r-1/’、 ‘/usr/lib/frei0r-1/’。

param1param2、...、paramN はその frei0r 効果に対する パラメータを指定する。

frei0r 効果のパラメータはブール値(その値は "y" および "n" で指定される)、 倍精度浮動小数点数、色(R/G/B という構文で指定される、ただし RG、および B は 0.0 から 1.0 までの浮動小数点数、または av_parse_color() の色の記述によって指定される)、位置(X/Y という構文で指定される、ただし XY は浮動小数点数)、および 文字列を取ることができる。

パラメータの数と種類はロードされる効果に依存する。効果のパラメータが 指定されていなければ、既定値が設定される。

以下はいくつかの例:

# distort0r 効果を適用、最初の2つの倍精度浮動小数点数パラメータを設定
frei0r=distort0r:0.5:0.01

# colordistance 効果を適用、最初のパラメータとして色をとる
frei0r=colordistance:0.2/0.3/0.4
frei0r=colordistance:violet
frei0r=colordistance:0x112233

# perspective 効果を適用、画像位置の左上と右上を指定
frei0r=perspective:0.2/0.2:0.8/0.2

さらなる情報については以下を見ること: http://piksel.org/frei0r

8.14 gradfun

フラットに近い領域を8ビット色深度に切り捨てたときにときどき生じる帯状の アーティファクトを修正します。 帯があるところにあるべき変化を補間し、それらをぼやかします。

このフィルターは再生のためのみに設計されています。ロスのある圧縮より前に これを使わないでください。圧縮はぼやかしを失くし帯を取り戻していまいがち だからです。

このフィルターは’:’で区切られた2つの省略可能なパラメータを受け取ります: strength:radius

strength はこのフィルターが1つのピクセルで変更できる最大の量です。 またフラットに近い領域を検出する閾値でもあります。 .51から255までの値をとることができ、既定では1.2で、範囲外の値は妥当な値に 切り詰められます。

radius は変化が適用される近傍です。より大きな半径にするとより スムーズな変化になりますが、同時にこのフィルターがより詳細な領域の近くにある ピクセルを変更するのを妨げます。取れる値は8-32で、既定では16です。 範囲外の値は妥当な値に切り詰められます。

# 既定のパラメータ
gradfun=1.2:16

# 半径を省略
gradfun=1.2

8.15 hflip

入力映像を水平方向に反転させる。

例えば avconv で入力の映像を水平方向に反転させるには:

avconv -i in.avi -vf "hflip" out.avi

8.16 hqdn3d

高精度/品質 3d ノイズ除去フィルター。このフィルターは画像ノイズを減らすことで 滑らかな画像を生成し静止画像を本当に静止させることを目指している。 それによって圧縮可能性が高まるはずである。

以下の省略可能なパラメータを受け取る: luma_spatial:chroma_spatial:luma_tmp:chroma_tmp

luma_spatial

空間 luma 強度を指定する非負の浮動小数点数、 既定では4.0

chroma_spatial

空間 chroma 強度を指定する非負の浮動小数点数、 既定では3.0*luma_spatial/4.0

luma_tmp

luma 時間強度を指定する浮動小数点数、既定では 6.0*luma_spatial/4.0

chroma_tmp

chroma 時間強度を指定する浮動小数点数、既定では luma_tmp*chroma_spatial/luma_spatial

8.17 noformat

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

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

以下はいくつかの例:

# "yuv420p" と異なる形式のどれかを使って vflip フィルターに
# 入力するように libavfilter に強制する
noformat=yuv420p,vflip

# 入力映像をリストにある形式以外の形式に変換する
noformat=yuv420p:yuv444p:yuv410p

8.18 null

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

8.19 ocv

libopencv を使って映像変換をほどこす。

このフィルターを有効にするには libopencv ライブラリとヘッダをインストールし Libav を –enable-libopencv で configure すること。

このフィルターは次のパラメータを受け取る: filter_name{:=}filter_params.

filter_name は適用する libopencv フィルターの名前である。

filter_params は libopencv フィルターに渡すパラメータを指定する。 指定されていなければ既定の値が仮定される。

より正確な情報については公式の libopencv の文書を参照すること: http://opencv.willowgarage.com/documentation/c/image_filtering.html

以下に対応している libopencv フィルターのリストが続く。

8.19.1 dilate

特定の構成要素を使ってイメージを膨らませる。 このフィルターは libopencv 関数 cvDilate に対応する。

これはパラメータを受け取る: struct_el:nb_iterations

struct_el は構成要素を表し、次の構文をとる: colsxrows+anchor_xxanchor_y/shape

cols および rows は構成要素の列と行の数を表し、 anchor_x および anchor_y はアンカーポイント、そして shape は構成要素の形状を表し、値として "rect"、"cross"、"ellipse"、"custom" のうちの1つをとる。

shape の値が "custom" なら、"=filename"の形の文字列が 続かなくてはならない。名前 filename を持つファイルはバイナリイメージを 表すと仮定され、各印字可能な文字は明るいピクセルに対応する。custom shape が使われる際、colsrows は無視され、代わりに 列と行の数は読み込まれるファイルにあるものと仮定される。

struct_el の既定値は"3x3+0x0/rect"である。

nb_iterations はイメージに適用される変換の回数を指定し、 既定では1である。

以下にいくつかの例:

# 既定値を使う
ocv=dilate

# 構成要素を使って 5x5 クロスに膨らませ、2回繰り返す
ocv=dilate=5x5+2x2/cross:2

# 形状をファイル diamond.shape から読み、2回繰り返す
# このファイル diamond.shapeには次のような文字のパターンが含まれている:
#   *
#  ***
# *****
#  ***
#   *
# 指定されている cols と rows は無視される(しかしアンカーポイント座標は無視されない)
ocv=0x0+2x2/custom=diamond.shape:2

8.19.2 erode

特定の構成要素を使ってイメージを侵食する。 このフィルターは libopencv 関数 cvErode に対応する。

このフィルターはパラメータを受け取る: struct_el:nb_iterations、 これは dilate フィルターと同じ意味を持ち同じように使われる。

8.19.3 smooth

入力映像をスムーズにする。

このフィルターは次のパラメータをとる: type:param1:param2:param3:param4.

type はほどこすスムーズフィルターの種類で、次の値のいずれかをとる: "blur"、"blur_no_scale"、"median"、"gaussian"、"bilateral"。 既定値は "gaussian"。

param1param2param3、および param4 は スムーズの種類に応じてその意味が変わるパラメータである。 param1param2 は正の整数値または0を受け取り、param3param4 は浮動小数点数値を受け取る。

param1 に対する既定値は3で、その他のパラメータについての既定値は 0である。

これらのパラメータは libopencv 関数 cvSmooth に割り当てられている パラメータに対応する。

8.20 overlay

映像を別の映像の上に重ねる。

これは2つの入力と1つの出力をとる。最初の入力は"主な"映像で、その上に 2番目の入力が重ねられる。

受け取るパラメータは: x:y

x は主な映像の上に重ねられる映像の x 座標。 y は y 座標。これらのパラメータは下記のパラメータを含むような 式である:

main_w, main_h

主な入力の幅と高さ

W, H

main_w および main_h と同じ

overlay_w, overlay_h

重ねる入力の幅と高さ

w, h

overlay_w および overlay_h と同じ

各入力映像から取られるフレームはタイムスタンプの順であることを意識すること。 したがって、それらの初期タイムスタンプが異なるなら、setpts=PTS-STARTPTS フィルターに通し、それらが同じゼロタイムスタンプから始まるようにして (movie フィルターの例で行っているように )2つの入力を渡すことは 良い考えである。

いくつかの例:

# 主な映像の右下隅から10ピクセルのところに
# 重ねて描画する
overlay=main_w-overlay_w-10:main_h-overlay_h-10

# 入力の左下隅に透過 PNG ロゴを挿入する
avconv -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output

# 2つの異なる透過 PNG ロゴを挿入する(2番目のロゴは
# 右下隅):
avconv -i input -i logo1 -i logo2 -filter_complex
'overlay=10:H-h-10,overlay=W-w-10:H-h-10' output

# 主な映像の上部に透過色レイヤーを加える、
# WxH は overlay フィルターに主な入力のサイズを指定する
color=red.3:WxH [over]; [in][over] overlay [out]

さらに多くの重ねを繋げることは可能だが、そういったアプローチの 効率は試験中である。

8.21 pad

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

次のようなパラメータを受け取る: width:height:x:y:color

パラメータ widthheightx、および y は以下の 定数を含んだ式です:

E, PI, PHI

e (自然対数の底)、pi (円周率)、phi (黄金比)に対応する数学的近似値

in_w, in_h

入力映像の幅および高さ

iw, ih

in_w および in_h と同じ

out_w, out_h

出力の幅および高さ、width および height 式によって指定されたパディングされた 領域の大きさ

ow, oh

out_w および out_h と同じ

x, y

x および y 式によって指定された x および y オフセット、 指定されていなければ NAN

a

入力画像アスペクト比、iw / ih と同じ

hsub, vsub

水平および垂直クローマサブサンプル値。例えばピクセル形式 "yuv422p" なら hsub は2で vsub は1。

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

width, height

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

width 式は height 式によって設定された値を参照すること ができ、逆も可能です。

width および height の既定値は0。

x, y

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

x 式は y 式によって設定された値を参照すること ができ、逆も可能です。

x および y の既定値は0。

color

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

color の既定値は "black"。

いくつかの例:

# パディングを色 "violet" にして入力映像に追加する。
# 出力映像のサイズは640x480で、
# 列0、行40に入力映像の左上隅が配置される。
pad=640:480:0:40:violet

# 入力を出力の大きさが 3/2 に増えるようにパディングし
# パディング領域の中央に入力映像を配置する
pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"

# 入力をその幅と高さのうち大きい方のサイズの正方形になるよう
# 出力し、# パディング領域の中央に入力映像を配置する
pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"

# 最終的な w/h 比が16:9になるように入力をパディングする
pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"

# 出力サイズを2倍にし、入力映像を出力パディング領域の右下隅に
# 配置する
pad="2*iw:2*ih:ow-iw:oh-ih"

8.22 pixdesctest

ピクセル形式記述子テストフィルター、主に内部的なテストに有用。 出力映像は入力映像に等しくなるはずである。

例えば:

format=monow, pixdesctest

として monowhite ピクセル形式記述子定義をテストするために用いることができる。

8.23 scale

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

パラメータ width および height は以下の定数を含む式:

E, PI, PHI

e (自然対数の底)、pi (円周率)、phi (黄金比)に対応する数学的 近似値

in_w, in_h

入力の幅および高さ

iw, ih

in_w および in_h と同じ

out_w, out_h

(切り取られた)出力の幅および高さ

ow, oh

out_w および out_h と同じ

dar, a

入力画面アスペクト比、iw / ih と同じ

sar

入力のサンプルアスペクト比

hsub, vsub

水平および垂直クローマサブサンプル値。例えばピクセル形式 "yuv422p" なら hsub は2で vsub は1。

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

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

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

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

widthheight の既定の値は0。

いくつかの例:

# 入力映像をサイズ 200x100 に拡大縮小します
scale=200:100

# 入力を2倍に拡大します
scale=2*iw:2*ih
# 上は以下と同じです
scale=2*in_w:2*in_h

# 入力を半分のサイズに縮小します
scale=iw/2:ih/2

# 幅を増やし、高さを同じサイズに設定します
scale=3/2*iw:ow

# 黄金比で調和させます
scale=iw:1/PHI*iw
scale=ih*PHI:ih

# 高さを増やし、幅を高さの3/2に設定します
scale=3/2*oh:3/5*ih

# 大きさを増やしますが、クローマの倍数の大きさにします
scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"

# 500ピクセルを上限に幅を増やし、入力アスペクト比は保ちます
scale='min(500\, iw*3/2):-1'

8.24 select

出力で渡すフレームを選択します

入力として1つの式を受け取り、この式は各入力フレームで評価されます。 もし式が評価された結果0以外の値になると、そのフレームは選択され 出力に渡ります。そうでなければそのフレームは捨てられます。

式には以下の定数を含めることができます:

PI

円周率

PHI

黄金律

E

自然対数の底

n

フィルターされるフレームの番号、0から始まる

selected_n

選択されたフレームの番号、0から始まる

prev_selected_n

最後に選択されたフレームの番号、未定義なら NAN

TB

入力タイムスタンプの時間単位

pts

フィルターされる映像フレームの PTS (プレゼンテーションタイムスタンプ)、 TB の単位で表現される。未定義なら NAN

t

フィルターされる映像フレームの PTS (プレゼンテーションタイムスタンプ)、 秒単位で表現される。未定義なら NAN

prev_pts

1つ前のフィルターされた映像フレームの PTS、未定義なら NAN

prev_selected_pts

1つ前に選択された映像フレームの PTS、未定義なら NAN

prev_selected_t

1つ前に選択された映像フレームの PTS、未定義なら NAN

start_pts

その映像のうち最初の映像フレームの PTS、未定義なら NAN

start_t

その映像のうち最初の映像フレームの時刻、未定義なら NAN

pict_type

フィルターされるフレームの種類、以下の値のうちの1つであると 考えてよい:

I
P
B
S
SI
SP
BI
interlace_type

フレームのインターフェイスの種類、以下の値のうちの1つであると 考えてよい:

PROGRESSIVE

フレームが(インターレースでなく)プログレッシブ

TOPFIRST

フレームがトップフィールド先頭

BOTTOMFIRST

フレームがボトムフィールド先頭

key

フィルターされるフレームがキーフレームなら1、さもなくば0

pos

フィルターされるフレームのファイルでの位置、その情報が利用できなければ (例えば、統合されている映像)-1

select 式の既定値は"1"です。

以下はいくつかの例です:

# 入力された全てのフレームを選択する
select

# 同上:
select=1

# 全てのフレームをスキップする:
select=0

# I-フレームだけを選択する
select='eq(pict_type\,I)'

# 100ごとに1つフレームを選択する
select='not(mod(n\,100))'

# 10から20までの時間内に含まれるフレームだけを選択する
select='gte(t\,10)*lte(t\,20)'

# 10から20までの時間内に含まれるIフレームだけを選択する
select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)'

# 10秒以上間隔を空けてフレームを選択する
select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'

8.25 setdar

フィルター出力映像に画面アスペクト比を設定する。

これは指定されたサンプル(ピクセル)アスペクト比を変更することによって実現され、 以下の等式による: DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR

このフィルターがビデオフレームのピクセルのディメンションを変更しないこと に注意すること。またこのフィルターによって設定された画面アスペクト比は フィルターチェーンのより後の方にあるフィルターによって変更されるかもしれない、 例えば、スケーリングされたり、他の "setdar" や "setsar" フィルターが適用 されている場合など。

このフィルターは望みの画面アスペクト比を表すパラメータの文字列を 受け取る。 このパラメータは浮動小数点数の文字列か、num:den の形をした式を 取り得る。ただし numden はアスペクト比の分子と分母 である。 パラメータが指定されていなければ、値 "0:1" が仮定される。

例えば、画面アスペクト比を 16:9 に変えるには、以下を指定する:

setdar=16:9
# 上は以下と同等:
setdar=1.77777

setsar フィルターのドキュメンテーションも参照すること。

8.26 setpts

入力映像フレームの PTS (プレゼンテーションタイムスタンプ)を変更する。

eval API を通じて評価される式を入力として受け取ります。以下の定数を 含めることができる。

PTS

入力のプレゼンテーションタイムスタンプ

PI

ギリシャ文字のパイ

PHI

黄金比

E

自然対数の底

N

0から始まる入力フレームのカウント

STARTPTS

最初の映像フレームの PTS

INTERLACED

現在のフレームがインターレースされているかどうか

POS

フレームのファイルでの本来の位置、現在のフレームについて定義されていなければ 不定。

PREV_INPTS

直前の入力 PTS

PREV_OUTPTS

直前の出力 PTS

いくつかの例:

# 0から PTS を数え始める
setpts=PTS-STARTPTS

# ファーストモーション
setpts=0.5*PTS

# スローモーション
setpts=2.0*PTS

# 固定レート 25 fps
setpts=N/(25*TB)

# 固定レート 25 fps および多少の揺れ
setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'

8.27 setsar

フィルター出力映像のサンプル(ピクセル)アスペクト比を設定する。

このフィルターを適用する結果として、出力の画面アスペクト比も以下の 等式にしたがって変更される: DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR

このフィルターで設定されたサンプルアスペクト比は、フィルターチェーンの より後の方にあるフィルターによって変更されるかもしれない、例えば 他の "setsar" や "setdar" が適用されることによって。

このフィルターは望みのサンプルアスペクト比を表すパラメータの文字列を 受け取る。 このパラメータは浮動小数点数の文字列か、num:den の形をした 文字列である。ただし num および den はアスペクト比の 分子と分母である。 このパラメータが指定されていなければ、値 "0:1" が仮定される。

例えば、サンプルアスペクト比を 10:11 に変更するには、以下を指定すること:

setsar=10:11

8.28 settb

出力フレームのタイムスタンプに用いる timebase を設定する。 主に timebase の構成をテストするために便利である。

入力に有理数を表す算術表現をとる。この表現には定数 "PI"、"E"、"PHI"、"AVTB"(既定の timebase)および "intb"(入力の timebase) を含めることができる。

入力のための既定の値は "intb"。

以下にいくつか例を挙げる。

# timebase を1/25にする
settb=1/25

# timebase を1/10にする
settb=0.1

# timebase を1001/1000にする
settb=1+0.001

# timebase を intb の2倍にする
settb=2*intb

# 既定の timebase の値にする
settb=AVTB

8.29 showinfo

各入力映像フレームについてのいろいろな情報を含む行を表示する。 入力映像は変更されない。

表示される行は key:value の形をしたキー/値の組の列を 含む。

表示される各パラメーターの説明は以下のとおり:

n

その入力フレームの番号、0から始まる

pts

その入力フレームのプレゼンテーションタイムスタンプ、時刻の基本単位の 数字として表現される。時刻の基本単位はフィルター入力パッドに依存する。

pts_time

その入力フレームのプレゼンテーションタイムスタンプ、秒単位の数字として 表現される

pos

入力ストリームでのそのフレームの位置、この情報が得られない、もしくは 意味がない(例えば合成映像の)場合は-1

fmt

ピクセルフォーマットの名前

sar

その入力フレームのサンプルアスペクト比、num/den の形で 表現される

s

その入力フレームのサイズ、widthxheight の形で 表現される

i

インターレースのモード("プログレッシブ" なら "P"、トップフィールドが先頭なら "T"、ボトムフィールドが先頭なら "B")

iskey

そのフレームがキーフレームなら1、さもなくば0

type

その入力フレームの画像の種類(I-フレーム なら "I"、P-フレームなら "P"、 B-フレームなら "B"、不明な種類なら "?")。 AVPictureType の enum、および ‘libavutil/avutil.h’ で 定義されている av_get_picture_type_char 関数のドキュメンテーションも 確認すること。

checksum

その入力フレームの全ての平面の Adler-32 チェックサム

plane_checksum

その入力フレームの各平面の Adler-32 チェックサム、"[c0 c1 c2 c3]" の形で表現される

8.30 slicify

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

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

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

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

8.31 split

入力映像をいくつかの同一の出力に分けます。

このフィルターは出力の数を指定するための1つのパラメーターを受け取ります。 指定されていなければ、既定では2です。

例えば

avconv -i INPUT -filter_complex split=5 OUTPUT

は入力映像の5つのコピーを作成します。

8.32 transpose

入力映像で行を列で置き換え、場合によっては反転させる。

これは整数値を表す1つのパラメータを受け取り、それは以下の値を 仮定します:

0

90°反時計回りに回転し、かつ垂直に反転する(既定値)、つまり:

L.R     L.l
. . ->  . .
l.r     R.r
1

90°時計回りに回転する、つまり:

L.R     l.L
. . ->  . .
l.r     r.R
2

90°反時計回りに回転する、つまり:

L.R     R.r
. . ->  . .
l.r     L.l
3

90°時計回りに回転し、かつ垂直に反転する、つまり:

L.R     r.R
. . ->  . .
l.r     l.L

8.33 unsharp

入力映像をシャープにする、またはぼやけさせる。

次のパラメータを受けつける: luma_msize_x:luma_msize_y:luma_amount:chroma_msize_x:chroma_msize_y:chroma_amount

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

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までの整数で、 既定値は5。

chroma_msize_y

chroma matrix 垂直サイズを設定する。3から13までの整数で、 既定値は5。

chroma_amount

chroma effect 強度を設定する。-2.0から5.0までの浮動小数点数で、 既定値は0.0。

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

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

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

8.34 vflip

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

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

8.35 yadif

入力映像のインターレースを外す(yadif は "yet another deinterlacing filter" である)。

これは省略可能なパラメータを受け取る: mode:parity:auto

mode は採用するインターレースのモードを指定する、以下の値の1つを 受け取る:

0

各フレームについて1フレームを出力

1

各フィールドについて1フレームを出力

2

0と同じだが空間的インターレースチェックをスキップする

3

1と同じだが空間的インターレースチェックをスキップする

既定値は0。

parity は入力のインターレースされる映像に対して仮定される ピクチャーフィールドパリティを指定する:

0

上部フィールドが最初と仮定

1

下部フィールドが最初と仮定

-1

自動検出を有効にする

既定値は-1。 インターレースが不明だったりデコーダがこの情報をエクスポートしていない場合、 「上部フィールドが先頭」を仮定する。

auto はデインターレーサーがインターレーストフラグを信用し、インターレース されているとマークされているフレームだけをデインターレースするかどうかを指定する

0

全てのフレームをデインターレースする

1

インターレーストとマークされているフレームだけをデインターレースする

既定値は0。

9 映像ソース

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

9.1 buffer

映像フレームをバッファし、かつそれらをフィルターチェーンで利用できるようにします。

このソースは主にプログラミング用に、特に ‘libavfilter/vsrc_buffer.h’ で定義されているインターフェイスを通じて使うことを意図されています。

これは次のパラメータを受け取ります: width:height:pix_fmt_string:timebase_num:timebase_den:sample_aspect_ratio_num:sample_aspect_ratio.den

全てのパラメータが明示的に定義される必要があります。

以下が受け取るパラメータのリストです。

width, height

バッファされる映像フレームの幅と高さを指定します。

pix_fmt_string

バッファされる映像フレームのピクセルフォーマットを表す文字列です。 あるピクセルフォーマットの対応する数字、もしくはピクセルフォーマットの 名前になります。

timebase_num, timebase_den

バッファされたフレームのタイムスタンプによって仮定される timebase の分子と分母を指定します。

sample_aspect_ratio.num, sample_aspect_ratio.den

映像フレームに仮定されるサンプルアスペクト比の分子および分母を 指定します。

例えば:

buffer=320:240:yuv410p:1:24:1:1

とすると、サイズが320x240で、フォーマットが"yuv410p"、タイムスタンプの timebase として1/24を仮定し、正方形のピクセル(1:1 のサンプルアスペクト比)の映像フレーム を受け取るソースを指示します。 名前"yuv410p"をもつピクセルフォーマットは数字6に対応する (‘libavutil/pixfmt.h’ にある enum AVPixelFormat の定義を確認してください) ので、この例は次と同じです:

buffer=320:240:6:1:24

9.2 color

一様に色付けされた入力を提供します。

これは次のようなパラメータを受け取ります: color:frame_size:frame_rate

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

color

ソースの色を指定します。色の名前(大文字小文字を区別しないマッチ)か アルファ値の指定を最後につけることができる 0xRRGGBB[AA] の形の列です。 既定の値は"black"です。

frame_size

ソースとなる映像のサイズを指定します。widthxheight という 形の文字列か、サイズの略称となる名前になります。 既定の値は"320x240"です。

frame_rate

ソースとなる映像のフレームレートを指定します。秒間に生成されるフレーム数 です。frame_rate_num/frame_rate_denという形の文字列か、 整数、浮動点数小数、または適切な映像フレームレートの略称です。 既定の値は"25"です。

例えば、以下のグラフ描写は透明度0.2をもつ赤のソースで、サイズ"qcif"、 フレームレートを10パーセカンドを生成します。そして識別子"in"をもつ 詰めものに結び付けられたソースの上にそれがオーバーレイされます。

"color=red@0.2:qcif:10 [color]; [in][color] overlay [out]"

9.3 movie

動画コンテナから映像ストリームを読み取ります。

このソースは標準入力のパスをバイパスするハックであることに注意してください。 任意のフィルターグラフをサポートしていないアプリケーションで有用になりますが、 サポートしているアプリケーションでは推奨されません。特に avconv では このフィルターは使うべきでなく、‘-filter_complex’ オプションが完全に これを置き換えます。

次の構文を受け取ります: movie_name[:options]、 ただし movie_name は読み取るリソースの名前(必ずしもファイルで なくてもよく、デバイスや何らかのプロトコルでアクセスできるストリーム もあり得ます)で、options は省略可能で、":"で区切られた key=value というペアの列です。

以下は受け取れるオプションの説明です。

format_name, f

読み取る動画がもっているはずの形式を指定します。コンテナまたは 入力デバイスの名前になります。指定されていなければ、その形式は movie_name または中身を調べることで推測されます。

seek_point, sp

秒単位でのシークポイントを指定します。フレームはこのシークポイント から出力が開始され、パラメータは av_strtod によって評価 されるので数値のあとに IS 接尾辞をつけることができます。 既定の値は"0"です。

stream_index, si

読み取る映像ストリームのインデックスを指定します。この値が-1なら、 最適な映像ストリームが自動的に選択されます。既定の値は"-1"です。

このフィルターによって、以下に示すフィルターグラフの主な入力の上に第2の 映像を重ねることができます:

input -----------> deltapts0 --> overlay --> output
                                    ^
                                    |
movie --> scale--> deltapts1 -------+

以下はいくつかの例です:

# avi ファイル in.avi の最初から3.2秒スキップし、それを
# "in"とラベルがついた入力の上に重ねます。
movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]

# video4linux2 デバイスから読み取り、それを"in"とラベルがついた
# 入力の上に重ねます。
movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]

9.4 nullsrc

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

省略可能なパラメータとして width:height:timebase という形の文字列を受け取ります。

widthheight は設定されるソースの大きさを指定します。 widthheight の既定値は(CIF サイズ形式に対応して) それぞれ352と288です。

timebase は timebase を表す算術表現を指定します。この表現には 定数 "PI"、"E"、"PHI"、"AVTB"(既定の timebase)を含めることができ、 既定では値 "AVTB" になります。

9.5 frei0r_src

frei0r ソースを提供します。

このフィルターのコンパイルを有効にするには、frei0r ヘッダをインストールし Libav を –enable-frei0r つきで configure する必要があります。

このソースは次の構文をサポートします:

size:rate:src_name[{=|:}param1:param2:...:paramN]

size は生成される映像のサイズで、widthxheight の形の 文字列か、フレームサイズの略語です。 rate は生成される映像のレートで、num/den の形の 文字列か、フレームレートの略語です。 src_name はロードされる frei0r ソースの名前です。frei0r に関する 更なる情報やどのようにパラメータを設定するかについては、映像フィルターの説明にある セクション frei0r を読んでください。

いくつかの例:

# frei0r partik0l ソースをサイズ 200x200 およびフレームレート10で生成し、
# overlay フィルターの主な入力の上に重ねる。
frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay

9.6 rgbtestsrc, testsrc

rgbtestsrc ソースは RGB 対 BGR の問題を検出するのに便利な RGB テストパターンを生成します。上から下へ赤、緑、青の縞模様が 見えるはずです。

testsrc はテスト映像パターンを生成し、それは色のパターン、 スクロールするグラデーション、およびタイムスタンプを表示します。 これは主にテストの目的としているものです。

どちらのソースも省略可能な ":" で区切られた key=value の組の列を 受け取ります。受け取るオプションの説明は以下のとおりです。

size, s

ソースになる映像のサイズを指定します。widthxheight の形をした文字列、 またはサイズの略称です。既定値は "320x240" です。

rate, r

ソースになる映像のフレームレートを、毎秒生成されるフレーム数で指定します。 frame_rate_num/frame_rate_den の形をした文字列か、整数値、 浮動小数点数、あるいは有効な映像のフレームレートの略称です。 既定値は "25" です。

sar

ソースになる映像のサンプルアスペクト比を設定します。

duration

ソースになる映像の時間を設定します。受け取る構文は次のとおりです:

[-]HH[:MM[:SS[.m...]]]
[-]S+[.m...]

av_parse_time() 関数も参照してください。

指定されていない、もしくは表現された時間が負の値なら、映像は際限なく生成される ものとします。

例えば、以下の

testsrc=duration=5.3:size=qcif:rate=10

は、サイズが176x144で、毎秒10フレームのフレームレートで5.3秒間持続する映像を 生成します。

10 映像シンク

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

10.1 buffersink

映像フレームをバッファリングし、フィルターグラフの末尾でそれらを利用できる ようにします。

このシンクは ‘libavfilter/buffersink.h’ で定義されているインターフェイス を通じてプログラム的に使うためのものです。

10.2 nullsink

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

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

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

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

11.1 crop

入力映像を x:y:width:height に切り取る。

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

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

xy の既定の値は0。

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

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

例えば、パラメータ:

"crop=100:100:0:0"

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

widthheight の既定の値は0。

11.2 format

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

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

次のコマンド:

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

は入力映像を形式 “yuv420p” に変換する。

11.3 noformat

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

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

次のコマンド:

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

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

11.4 null

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

11.5 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”。

11.6 scale

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

例えば次のコマンド:

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

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

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

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

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

widthheight の既定の値は0。

11.7 slicify

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

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

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

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

11.8 unsharp

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

名前説明最小値最大値既定値
luma_msize_xLuma matrix 水平サイズ3135
luma_msize_yLuma matrix 垂直サイズ3135
luma_amountLuma effect 強度-2.05.01.0
chroma_msize_xChroma matrix 水平サイズ3130
chroma_msize_yChroma matrix 垂直サイズ3130
chroma_amountChroma effect 強度-2.05.00.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

11.9 vflip

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

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

12 利用可能な映像ソース

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

12.1 nullsrc

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

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

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

13 利用可能な映像シンク

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

13.1 nullsink

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