| @chapter Filtergraph description |
| @c man begin FILTERGRAPH DESCRIPTION |
| |
| A filtergraph is a directed graph of connected filters. It can contain |
| cycles, and there can be multiple links between a pair of |
| filters. Each link has one input pad on one side connecting it to one |
| filter from which it takes its input, and one output pad on the other |
| side connecting it to the one filter accepting its output. |
| |
| Each filter in a filtergraph is an instance of a filter class |
| registered in the application, which defines the features and the |
| number of input and output pads of the filter. |
| |
| A filter with no input pads is called a "source", a filter with no |
| output pads is called a "sink". |
| |
| @anchor{Filtergraph syntax} |
| @section Filtergraph syntax |
| |
| A filtergraph can be represented using a textual representation, which is |
| recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex} |
| options in @command{ffmpeg} and @option{-vf} in @command{ffplay}, and by the |
| @code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} function defined in |
| @file{libavfilter/avfiltergraph.h}. |
| |
| A filterchain consists of a sequence of connected filters, each one |
| connected to the previous one in the sequence. A filterchain is |
| represented by a list of ","-separated filter descriptions. |
| |
| A filtergraph consists of a sequence of filterchains. A sequence of |
| filterchains is represented by a list of ";"-separated filterchain |
| descriptions. |
| |
| A filter is represented by a string of the form: |
| [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}] |
| |
| @var{filter_name} is the name of the filter class of which the |
| described filter is an instance of, and has to be the name of one of |
| the filter classes registered in the program. |
| The name of the filter class is optionally followed by a string |
| "=@var{arguments}". |
| |
| @var{arguments} is a string which contains the parameters used to |
| initialize the filter instance, and are described in the filter |
| descriptions below. |
| |
| The list of arguments can be quoted using the character "'" as initial |
| and ending mark, and the character '\' for escaping the characters |
| within the quoted text; otherwise the argument string is considered |
| terminated when the next special character (belonging to the set |
| "[]=;,") is encountered. |
| |
| The name and arguments of the filter are optionally preceded and |
| followed by a list of link labels. |
| A link label allows to name a link and associate it to a filter output |
| or input pad. The preceding labels @var{in_link_1} |
| ... @var{in_link_N}, are associated to the filter input pads, |
| the following labels @var{out_link_1} ... @var{out_link_M}, are |
| associated to the output pads. |
| |
| When two link labels with the same name are found in the |
| filtergraph, a link between the corresponding input and output pad is |
| created. |
| |
| If an output pad is not labelled, it is linked by default to the first |
| unlabelled input pad of the next filter in the filterchain. |
| For example in the filterchain: |
| @example |
| nullsrc, split[L1], [L2]overlay, nullsink |
| @end example |
| the split filter instance has two output pads, and the overlay filter |
| instance two input pads. The first output pad of split is labelled |
| "L1", the first input pad of overlay is labelled "L2", and the second |
| output pad of split is linked to the second input pad of overlay, |
| which are both unlabelled. |
| |
| In a complete filterchain all the unlabelled filter input and output |
| pads must be connected. A filtergraph is considered valid if all the |
| filter input and output pads of all the filterchains are connected. |
| |
| Libavfilter will automatically insert scale filters where format |
| conversion is required. It is possible to specify swscale flags |
| for those automatically inserted scalers by prepending |
| @code{sws_flags=@var{flags};} |
| to the filtergraph description. |
| |
| Follows a BNF description for the filtergraph syntax: |
| @example |
| @var{NAME} ::= sequence of alphanumeric characters and '_' |
| @var{LINKLABEL} ::= "[" @var{NAME} "]" |
| @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}] |
| @var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted) |
| @var{FILTER} ::= [@var{LINKNAMES}] @var{NAME} ["=" @var{ARGUMENTS}] [@var{LINKNAMES}] |
| @var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}] |
| @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}] |
| @end example |
| |
| @c man end FILTERGRAPH DESCRIPTION |
| |
| @chapter Audio Filters |
| @c man begin AUDIO FILTERS |
| |
| When you configure your FFmpeg build, you can disable any of the |
| existing filters using @code{--disable-filters}. |
| The configure output will show the audio filters included in your |
| build. |
| |
| Below is a description of the currently available audio filters. |
| |
| @section aconvert |
| |
| Convert the input audio format to the specified formats. |
| |
| The filter accepts a string of the form: |
| "@var{sample_format}:@var{channel_layout}". |
| |
| @var{sample_format} specifies the sample format, and can be a string or the |
| corresponding numeric value defined in @file{libavutil/samplefmt.h}. Use 'p' |
| suffix for a planar sample format. |
| |
| @var{channel_layout} specifies the channel layout, and can be a string |
| or the corresponding number value defined in @file{libavutil/audioconvert.h}. |
| |
| The special parameter "auto", signifies that the filter will |
| automatically select the output format depending on the output filter. |
| |
| Some examples follow. |
| |
| @itemize |
| @item |
| Convert input to float, planar, stereo: |
| @example |
| aconvert=fltp:stereo |
| @end example |
| |
| @item |
| Convert input to unsigned 8-bit, automatically select out channel layout: |
| @example |
| aconvert=u8:auto |
| @end example |
| @end itemize |
| |
| @section aformat |
| |
| Convert the input audio to one of the specified formats. The framework will |
| negotiate the most appropriate format to minimize conversions. |
| |
| The filter accepts the following named parameters: |
| @table @option |
| |
| @item sample_fmts |
| A comma-separated list of requested sample formats. |
| |
| @item sample_rates |
| A comma-separated list of requested sample rates. |
| |
| @item channel_layouts |
| A comma-separated list of requested channel layouts. |
| |
| @end table |
| |
| If a parameter is omitted, all values are allowed. |
| |
| For example to force the output to either unsigned 8-bit or signed 16-bit stereo: |
| @example |
| aformat=sample_fmts\=u8\,s16:channel_layouts\=stereo |
| @end example |
| |
| @section amerge |
| |
| Merge two audio streams into a single multi-channel stream. |
| |
| This filter does not need any argument. |
| |
| If the channel layouts of the inputs are disjoint, and therefore compatible, |
| the channel layout of the output will be set accordingly and the channels |
| will be reordered as necessary. If the channel layouts of the inputs are not |
| disjoint, the output will have all the channels of the first input then all |
| the channels of the second input, in that order, and the channel layout of |
| the output will be the default value corresponding to the total number of |
| channels. |
| |
| For example, if the first input is in 2.1 (FL+FR+LF) and the second input |
| is FC+BL+BR, then the output will be in 5.1, with the channels in the |
| following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the |
| first input, b1 is the first channel of the second input). |
| |
| On the other hand, if both input are in stereo, the output channels will be |
| in the default order: a1, a2, b1, b2, and the channel layout will be |
| arbitrarily set to 4.0, which may or may not be the expected value. |
| |
| Both inputs must have the same sample rate, and format. |
| |
| If inputs do not have the same duration, the output will stop with the |
| shortest. |
| |
| Example: merge two mono files into a stereo stream: |
| @example |
| amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge |
| @end example |
| |
| If you need to do multiple merges (for instance multiple mono audio streams in |
| a single video media), you can do: |
| @example |
| ffmpeg -f lavfi -i " |
| amovie=input.mkv:si=0 [a0]; |
| amovie=input.mkv:si=1 [a1]; |
| amovie=input.mkv:si=2 [a2]; |
| amovie=input.mkv:si=3 [a3]; |
| amovie=input.mkv:si=4 [a4]; |
| amovie=input.mkv:si=5 [a5]; |
| [a0][a1] amerge [x0]; |
| [x0][a2] amerge [x1]; |
| [x1][a3] amerge [x2]; |
| [x2][a4] amerge [x3]; |
| [x3][a5] amerge" -c:a pcm_s16le output.mkv |
| @end example |
| |
| @section amix |
| |
| Mixes multiple audio inputs into a single output. |
| |
| For example |
| @example |
| ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT |
| @end example |
| will mix 3 input audio streams to a single output with the same duration as the |
| first input and a dropout transition time of 3 seconds. |
| |
| The filter accepts the following named parameters: |
| @table @option |
| |
| @item inputs |
| Number of inputs. If unspecified, it defaults to 2. |
| |
| @item duration |
| How to determine the end-of-stream. |
| @table @option |
| |
| @item longest |
| Duration of longest input. (default) |
| |
| @item shortest |
| Duration of shortest input. |
| |
| @item first |
| Duration of first input. |
| |
| @end table |
| |
| @item dropout_transition |
| Transition time, in seconds, for volume renormalization when an input |
| stream ends. The default value is 2 seconds. |
| |
| @end table |
| |
| @section anull |
| |
| Pass the audio source unchanged to the output. |
| |
| @section aresample |
| |
| Resample the input audio to the specified sample rate. |
| |
| The filter accepts exactly one parameter, the output sample rate. If not |
| specified then the filter will automatically convert between its input |
| and output sample rates. |
| |
| For example, to resample the input audio to 44100Hz: |
| @example |
| aresample=44100 |
| @end example |
| |
| @section ashowinfo |
| |
| Show a line containing various information for each input audio frame. |
| The input audio is not modified. |
| |
| The shown line contains a sequence of key/value pairs of the form |
| @var{key}:@var{value}. |
| |
| A description of each shown parameter follows: |
| |
| @table @option |
| @item n |
| sequential number of the input frame, starting from 0 |
| |
| @item pts |
| presentation TimeStamp of the input frame, expressed as a number of |
| time base units. The time base unit depends on the filter input pad, and |
| is usually 1/@var{sample_rate}. |
| |
| @item pts_time |
| presentation TimeStamp of the input frame, expressed as a number of |
| seconds |
| |
| @item pos |
| position of the frame in the input stream, -1 if this information in |
| unavailable and/or meaningless (for example in case of synthetic audio) |
| |
| @item fmt |
| sample format name |
| |
| @item chlayout |
| channel layout description |
| |
| @item nb_samples |
| number of samples (per each channel) contained in the filtered frame |
| |
| @item rate |
| sample rate for the audio frame |
| |
| @item checksum |
| Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame |
| |
| @item plane_checksum |
| Adler-32 checksum (printed in hexadecimal) for each input frame plane, |
| expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3} @var{c4} @var{c5} |
| @var{c6} @var{c7}]" |
| @end table |
| |
| @section asplit |
| |
| Split input audio into several identical outputs. |
| |
| The filter accepts a single parameter which specifies the number of outputs. If |
| unspecified, it defaults to 2. |
| |
| For example: |
| @example |
| [in] asplit [out0][out1] |
| @end example |
| |
| will create two separate outputs from the same input. |
| |
| To create 3 or more outputs, you need to specify the number of |
| outputs, like in: |
| @example |
| [in] asplit=3 [out0][out1][out2] |
| @end example |
| |
| @example |
| ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT |
| @end example |
| will create 5 copies of the input audio. |
| |
| |
| @section astreamsync |
| |
| Forward two audio streams and control the order the buffers are forwarded. |
| |
| The argument to the filter is an expression deciding which stream should be |
| forwarded next: if the result is negative, the first stream is forwarded; if |
| the result is positive or zero, the second stream is forwarded. It can use |
| the following variables: |
| |
| @table @var |
| @item b1 b2 |
| number of buffers forwarded so far on each stream |
| @item s1 s2 |
| number of samples forwarded so far on each stream |
| @item t1 t2 |
| current timestamp of each stream |
| @end table |
| |
| The default value is @code{t1-t2}, which means to always forward the stream |
| that has a smaller timestamp. |
| |
| Example: stress-test @code{amerge} by randomly sending buffers on the wrong |
| input, while avoiding too much of a desynchronization: |
| @example |
| amovie=file.ogg [a] ; amovie=file.mp3 [b] ; |
| [a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ; |
| [a2] [b2] amerge |
| @end example |
| |
| @section earwax |
| |
| Make audio easier to listen to on headphones. |
| |
| This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio |
| so that when listened to on headphones the stereo image is moved from |
| inside your head (standard for headphones) to outside and in front of |
| the listener (standard for speakers). |
| |
| Ported from SoX. |
| |
| @section pan |
| |
| Mix channels with specific gain levels. The filter accepts the output |
| channel layout followed by a set of channels definitions. |
| |
| This filter is also designed to remap efficiently the channels of an audio |
| stream. |
| |
| The filter accepts parameters of the form: |
| "@var{l}:@var{outdef}:@var{outdef}:..." |
| |
| @table @option |
| @item l |
| output channel layout or number of channels |
| |
| @item outdef |
| output channel specification, of the form: |
| "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]" |
| |
| @item out_name |
| output channel to define, either a channel name (FL, FR, etc.) or a channel |
| number (c0, c1, etc.) |
| |
| @item gain |
| multiplicative coefficient for the channel, 1 leaving the volume unchanged |
| |
| @item in_name |
| input channel to use, see out_name for details; it is not possible to mix |
| named and numbered input channels |
| @end table |
| |
| If the `=' in a channel specification is replaced by `<', then the gains for |
| that specification will be renormalized so that the total is 1, thus |
| avoiding clipping noise. |
| |
| @subsection Mixing examples |
| |
| For example, if you want to down-mix from stereo to mono, but with a bigger |
| factor for the left channel: |
| @example |
| pan=1:c0=0.9*c0+0.1*c1 |
| @end example |
| |
| A customized down-mix to stereo that works automatically for 3-, 4-, 5- and |
| 7-channels surround: |
| @example |
| pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR |
| @end example |
| |
| Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system |
| that should be preferred (see "-ac" option) unless you have very specific |
| needs. |
| |
| @subsection Remapping examples |
| |
| The channel remapping will be effective if, and only if: |
| |
| @itemize |
| @item gain coefficients are zeroes or ones, |
| @item only one input per channel output, |
| @end itemize |
| |
| If all these conditions are satisfied, the filter will notify the user ("Pure |
| channel mapping detected"), and use an optimized and lossless method to do the |
| remapping. |
| |
| For example, if you have a 5.1 source and want a stereo audio stream by |
| dropping the extra channels: |
| @example |
| pan="stereo: c0=FL : c1=FR" |
| @end example |
| |
| Given the same source, you can also switch front left and front right channels |
| and keep the input channel layout: |
| @example |
| pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5" |
| @end example |
| |
| If the input is a stereo audio stream, you can mute the front left channel (and |
| still keep the stereo channel layout) with: |
| @example |
| pan="stereo:c1=c1" |
| @end example |
| |
| Still with a stereo audio stream input, you can copy the right channel in both |
| front left and right: |
| @example |
| pan="stereo: c0=FR : c1=FR" |
| @end example |
| |
| @section silencedetect |
| |
| Detect silence in an audio stream. |
| |
| This filter logs a message when it detects that the input audio volume is less |
| or equal to a noise tolerance value for a duration greater or equal to the |
| minimum detected noise duration. |
| |
| The printed times and duration are expressed in seconds. |
| |
| @table @option |
| @item duration, d |
| Set silence duration until notification (default is 2 seconds). |
| |
| @item noise, n |
| Set noise tolerance. Can be specified in dB (in case "dB" is appended to the |
| specified value) or amplitude ratio. Default is -60dB, or 0.001. |
| @end table |
| |
| Detect 5 seconds of silence with -50dB noise tolerance: |
| @example |
| silencedetect=n=-50dB:d=5 |
| @end example |
| |
| Complete example with @command{ffmpeg} to detect silence with 0.0001 noise |
| tolerance in @file{silence.mp3}: |
| @example |
| ffmpeg -f lavfi -i amovie=silence.mp3,silencedetect=noise=0.0001 -f null - |
| @end example |
| |
| @section volume |
| |
| Adjust the input audio volume. |
| |
| The filter accepts exactly one parameter @var{vol}, which expresses |
| how the audio volume will be increased or decreased. |
| |
| Output values are clipped to the maximum value. |
| |
| If @var{vol} is expressed as a decimal number, the output audio |
| volume is given by the relation: |
| @example |
| @var{output_volume} = @var{vol} * @var{input_volume} |
| @end example |
| |
| If @var{vol} is expressed as a decimal number followed by the string |
| "dB", the value represents the requested change in decibels of the |
| input audio power, and the output audio volume is given by the |
| relation: |
| @example |
| @var{output_volume} = 10^(@var{vol}/20) * @var{input_volume} |
| @end example |
| |
| Otherwise @var{vol} is considered an expression and its evaluated |
| value is used for computing the output audio volume according to the |
| first relation. |
| |
| Default value for @var{vol} is 1.0. |
| |
| @subsection Examples |
| |
| @itemize |
| @item |
| Half the input audio volume: |
| @example |
| volume=0.5 |
| @end example |
| |
| The above example is equivalent to: |
| @example |
| volume=1/2 |
| @end example |
| |
| @item |
| Decrease input audio power by 12 decibels: |
| @example |
| volume=-12dB |
| @end example |
| @end itemize |
| |
| @section asyncts |
| Synchronize audio data with timestamps by squeezing/stretching it and/or |
| dropping samples/adding silence when needed. |
| |
| The filter accepts the following named parameters: |
| @table @option |
| |
| @item compensate |
| Enable stretching/squeezing the data to make it match the timestamps. |
| |
| @item min_delta |
| Minimum difference between timestamps and audio data (in seconds) to trigger |
| adding/dropping samples. |
| |
| @item max_comp |
| Maximum compensation in samples per second. |
| |
| @end table |
| |
| @section resample |
| Convert the audio sample format, sample rate and channel layout. This filter is |
| not meant to be used directly. |
| |
| @c man end AUDIO FILTERS |
| |
| @chapter Audio Sources |
| @c man begin AUDIO SOURCES |
| |
| Below is a description of the currently available audio sources. |
| |
| @section abuffer |
| |
| Buffer audio frames, and make them available to the filter chain. |
| |
| This source is mainly intended for a programmatic use, in particular |
| through the interface defined in @file{libavfilter/asrc_abuffer.h}. |
| |
| It accepts the following mandatory parameters: |
| @var{sample_rate}:@var{sample_fmt}:@var{channel_layout} |
| |
| @table @option |
| |
| @item sample_rate |
| The sample rate of the incoming audio buffers. |
| |
| @item sample_fmt |
| The sample format of the incoming audio buffers. |
| Either a sample format name or its corresponging integer representation from |
| the enum AVSampleFormat in @file{libavutil/samplefmt.h} |
| |
| @item channel_layout |
| The channel layout of the incoming audio buffers. |
| Either a channel layout name from channel_layout_map in |
| @file{libavutil/audioconvert.c} or its corresponding integer representation |
| from the AV_CH_LAYOUT_* macros in @file{libavutil/audioconvert.h} |
| |
| @end table |
| |
| For example: |
| @example |
| abuffer=44100:s16p:stereo |
| @end example |
| |
| will instruct the source to accept planar 16bit signed stereo at 44100Hz. |
| Since the sample format with name "s16p" corresponds to the number |
| 6 and the "stereo" channel layout corresponds to the value 0x3, this is |
| equivalent to: |
| @example |
| abuffer=44100:6:0x3 |
| @end example |
| |
| @section aevalsrc |
| |
| Generate an audio signal specified by an expression. |
| |
| This source accepts in input one or more expressions (one for each |
| channel), which are evaluated and used to generate a corresponding |
| audio signal. |
| |
| It accepts the syntax: @var{exprs}[::@var{options}]. |
| @var{exprs} is a list of expressions separated by ":", one for each |
| separate channel. In case the @var{channel_layout} is not |
| specified, the selected channel layout depends on the number of |
| provided expressions. |
| |
| @var{options} is an optional sequence of @var{key}=@var{value} pairs, |
| separated by ":". |
| |
| The description of the accepted options follows. |
| |
| @table @option |
| |
| @item channel_layout, c |
| Set the channel layout. The number of channels in the specified layout |
| must be equal to the number of specified expressions. |
| |
| @item duration, d |
| Set the minimum duration of the sourced audio. See the function |
| @code{av_parse_time()} for the accepted format. |
| Note that the resulting duration may be greater than the specified |
| duration, as the generated audio is always cut at the end of a |
| complete frame. |
| |
| If not specified, or the expressed duration is negative, the audio is |
| supposed to be generated forever. |
| |
| @item nb_samples, n |
| Set the number of samples per channel per each output frame, |
| default to 1024. |
| |
| @item sample_rate, s |
| Specify the sample rate, default to 44100. |
| @end table |
| |
| Each expression in @var{exprs} can contain the following constants: |
| |
| @table @option |
| @item n |
| number of the evaluated sample, starting from 0 |
| |
| @item t |
| time of the evaluated sample expressed in seconds, starting from 0 |
| |
| @item s |
| sample rate |
| |
| @end table |
| |
| @subsection Examples |
| |
| @itemize |
| |
| @item |
| Generate silence: |
| @example |
| aevalsrc=0 |
| @end example |
| |
| @item |
| |
| Generate a sin signal with frequency of 440 Hz, set sample rate to |
| 8000 Hz: |
| @example |
| aevalsrc="sin(440*2*PI*t)::s=8000" |
| @end example |
| |
| @item |
| Generate a two channels signal, specify the channel layout (Front |
| Center + Back Center) explicitly: |
| @example |
| aevalsrc="sin(420*2*PI*t):cos(430*2*PI*t)::c=FC|BC" |
| @end example |
| |
| @item |
| Generate white noise: |
| @example |
| aevalsrc="-2+random(0)" |
| @end example |
| |
| @item |
| Generate an amplitude modulated signal: |
| @example |
| aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)" |
| @end example |
| |
| @item |
| Generate 2.5 Hz binaural beats on a 360 Hz carrier: |
| @example |
| aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) : 0.1*sin(2*PI*(360+2.5/2)*t)" |
| @end example |
| |
| @end itemize |
| |
| @section amovie |
| |
| Read an audio stream from a movie container. |
| |
| It accepts the syntax: @var{movie_name}[:@var{options}] where |
| @var{movie_name} is the name of the resource to read (not necessarily |
| a file but also a device or a stream accessed through some protocol), |
| and @var{options} is an optional sequence of @var{key}=@var{value} |
| pairs, separated by ":". |
| |
| The description of the accepted options follows. |
| |
| @table @option |
| |
| @item format_name, f |
| Specify the format assumed for the movie to read, and can be either |
| the name of a container or an input device. If not specified the |
| format is guessed from @var{movie_name} or by probing. |
| |
| @item seek_point, sp |
| Specify the seek point in seconds, the frames will be output |
| starting from this seek point, the parameter is evaluated with |
| @code{av_strtod} so the numerical value may be suffixed by an IS |
| postfix. Default value is "0". |
| |
| @item stream_index, si |
| Specify the index of the audio stream to read. If the value is -1, |
| the best suited audio stream will be automatically selected. Default |
| value is "-1". |
| |
| @end table |
| |
| @section anullsrc |
| |
| Null audio source, return unprocessed audio frames. It is mainly useful |
| as a template and to be employed in analysis / debugging tools, or as |
| the source for filters which ignore the input data (for example the sox |
| synth filter). |
| |
| It accepts an optional sequence of @var{key}=@var{value} pairs, |
| separated by ":". |
| |
| The description of the accepted options follows. |
| |
| @table @option |
| |
| @item sample_rate, s |
| Specify the sample rate, and defaults to 44100. |
| |
| @item channel_layout, cl |
| |
| Specify the channel layout, and can be either an integer or a string |
| representing a channel layout. The default value of @var{channel_layout} |
| is "stereo". |
| |
| Check the channel_layout_map definition in |
| @file{libavcodec/audioconvert.c} for the mapping between strings and |
| channel layout values. |
| |
| @item nb_samples, n |
| Set the number of samples per requested frames. |
| |
| @end table |
| |
| Follow some examples: |
| @example |
| # set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. |
| anullsrc=r=48000:cl=4 |
| |
| # same as |
| anullsrc=r=48000:cl=mono |
| @end example |
| |
| @section abuffer |
| Buffer audio frames, and make them available to the filter chain. |
| |
| This source is not intended to be part of user-supplied graph descriptions but |
| for insertion by calling programs through the interface defined in |
| @file{libavfilter/buffersrc.h}. |
| |
| It accepts the following named parameters: |
| @table @option |
| |
| @item time_base |
| Timebase which will be used for timestamps of submitted frames. It must be |
| either a floating-point number or in @var{numerator}/@var{denominator} form. |
| |
| @item sample_rate |
| Audio sample rate. |
| |
| @item sample_fmt |
| Name of the sample format, as returned by @code{av_get_sample_fmt_name()}. |
| |
| @item channel_layout |
| Channel layout of the audio data, in the form that can be accepted by |
| @code{av_get_channel_layout()}. |
| @end table |
| |
| All the parameters need to be explicitly defined. |
| |
| @c man end AUDIO SOURCES |
| |
| @chapter Audio Sinks |
| @c man begin AUDIO SINKS |
| |
| Below is a description of the currently available audio sinks. |
| |
| @section abuffersink |
| |
| Buffer audio frames, and make them available to the end of filter chain. |
| |
| This sink is mainly intended for programmatic use, in particular |
| through the interface defined in @file{libavfilter/buffersink.h}. |
| |
| It requires a pointer to an AVABufferSinkContext structure, which |
| defines the incoming buffers' formats, to be passed as the opaque |
| parameter to @code{avfilter_init_filter} for initialization. |
| |
| @section anullsink |
| |
| Null audio sink, do absolutely nothing with the input audio. It is |
| mainly useful as a template and to be employed in analysis / debugging |
| tools. |
| |
| @section abuffersink |
| This sink is intended for programmatic use. Frames that arrive on this sink can |
| be retrieved by the calling program using the interface defined in |
| @file{libavfilter/buffersink.h}. |
| |
| This filter accepts no parameters. |
| |
| @c man end AUDIO SINKS |
| |
| @chapter Video Filters |
| @c man begin VIDEO FILTERS |
| |
| When you configure your FFmpeg build, you can disable any of the |
| existing filters using @code{--disable-filters}. |
| The configure output will show the video filters included in your |
| build. |
| |
| Below is a description of the currently available video filters. |
| |
| @section ass |
| |
| Draw ASS (Advanced Substation Alpha) subtitles on top of input video |
| using the libass library. |
| |
| To enable compilation of this filter you need to configure FFmpeg with |
| @code{--enable-libass}. |
| |
| This filter accepts the syntax: @var{ass_filename}[:@var{options}], |
| where @var{ass_filename} is the filename of the ASS file to read, and |
| @var{options} is an optional sequence of @var{key}=@var{value} pairs, |
| separated by ":". |
| |
| A description of the accepted options follows. |
| |
| @table @option |
| @item original_size |
| Specifies the size of the original video, the video for which the ASS file |
| was composed. Due to a misdesign in ASS aspect ratio arithmetic, this is |
| necessary to correctly scale the fonts if the aspect ratio has been changed. |
| @end table |
| |
| For example, to render the file @file{sub.ass} on top of the input |
| video, use the command: |
| @example |
| ass=sub.ass |
| @end example |
| |
| @section bbox |
| |
| Compute the bounding box for the non-black pixels in the input frame |
| luminance plane. |
| |
| This filter computes the bounding box containing all the pixels with a |
| luminance value greater than the minimum allowed value. |
| The parameters describing the bounding box are printed on the filter |
| log. |
| |
| @section blackdetect |
| |
| Detect video intervals that are (almost) completely black. Can be |
| useful to detect chapter transitions, commercials, or invalid |
| recordings. Output lines contains the time for the start, end and |
| duration of the detected black interval expressed in seconds. |
| |
| In order to display the output lines, you need to set the loglevel at |
| least to the AV_LOG_INFO value. |
| |
| This filter accepts a list of options in the form of |
| @var{key}=@var{value} pairs separated by ":". A description of the |
| accepted options follows. |
| |
| @table @option |
| @item black_min_duration, d |
| Set the minimum detected black duration expressed in seconds. It must |
| be a non-negative floating point number. |
| |
| Default value is 2.0. |
| |
| @item picture_black_ratio_th, pic_th |
| Set the threshold for considering a picture "black". |
| Express the minimum value for the ratio: |
| @example |
| @var{nb_black_pixels} / @var{nb_pixels} |
| @end example |
| |
| for which a picture is considered black. |
| Default value is 0.98. |
| |
| @item pixel_black_th, pix_th |
| Set the threshold for considering a pixel "black". |
| |
| The threshold expresses the maximum pixel luminance value for which a |
| pixel is considered "black". The provided value is scaled according to |
| the following equation: |
| @example |
| @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size} |
| @end example |
| |
| @var{luminance_range_size} and @var{luminance_minimum_value} depend on |
| the input video format, the range is [0-255] for YUV full-range |
| formats and [16-235] for YUV non full-range formats. |
| |
| Default value is 0.10. |
| @end table |
| |
| The following example sets the maximum pixel threshold to the minimum |
| value, and detects only black intervals of 2 or more seconds: |
| @example |
| blackdetect=d=2:pix_th=0.00 |
| @end example |
| |
| @section blackframe |
| |
| Detect frames that are (almost) completely black. Can be useful to |
| detect chapter transitions or commercials. Output lines consist of |
| the frame number of the detected frame, the percentage of blackness, |
| the position in the file if known or -1 and the timestamp in seconds. |
| |
| In order to display the output lines, you need to set the loglevel at |
| least to the AV_LOG_INFO value. |
| |
| The filter accepts the syntax: |
| @example |
| blackframe[=@var{amount}:[@var{threshold}]] |
| @end example |
| |
| @var{amount} is the percentage of the pixels that have to be below the |
| threshold, and defaults to 98. |
| |
| @var{threshold} is the threshold below which a pixel value is |
| considered black, and defaults to 32. |
| |
| @section boxblur |
| |
| Apply boxblur algorithm to the input video. |
| |
| This filter accepts the parameters: |
| @var{luma_radius}:@var{luma_power}:@var{chroma_radius}:@var{chroma_power}:@var{alpha_radius}:@var{alpha_power} |
| |
| Chroma and alpha parameters are optional, if not specified they default |
| to the corresponding values set for @var{luma_radius} and |
| @var{luma_power}. |
| |
| @var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent |
| the radius in pixels of the box used for blurring the corresponding |
| input plane. They are expressions, and can contain the following |
| constants: |
| @table @option |
| @item w, h |
| the input width and height in pixels |
| |
| @item cw, ch |
| the input chroma image width and height in pixels |
| |
| @item hsub, vsub |
| horizontal and vertical chroma subsample values. For example for the |
| pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| @end table |
| |
| The radius must be a non-negative number, and must not be greater than |
| the value of the expression @code{min(w,h)/2} for the luma and alpha planes, |
| and of @code{min(cw,ch)/2} for the chroma planes. |
| |
| @var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent |
| how many times the boxblur filter is applied to the corresponding |
| plane. |
| |
| Some examples follow: |
| |
| @itemize |
| |
| @item |
| Apply a boxblur filter with luma, chroma, and alpha radius |
| set to 2: |
| @example |
| boxblur=2:1 |
| @end example |
| |
| @item |
| Set luma radius to 2, alpha and chroma radius to 0 |
| @example |
| boxblur=2:1:0:0:0:0 |
| @end example |
| |
| @item |
| Set luma and chroma radius to a fraction of the video dimension |
| @example |
| boxblur=min(h\,w)/10:1:min(cw\,ch)/10:1 |
| @end example |
| |
| @end itemize |
| |
| @section colormatrix |
| |
| The colormatrix filter allows conversion between any of the following color |
| space: BT.709 (@var{bt709}), BT.601 (@var{bt601}), SMPTE-240M (@var{smpte240m}) |
| and FCC (@var{fcc}). |
| |
| The syntax of the parameters is @var{source}:@var{destination}: |
| |
| @example |
| colormatrix=bt601:smpte240m |
| @end example |
| |
| @section copy |
| |
| Copy the input source unchanged to the output. Mainly useful for |
| testing purposes. |
| |
| @section crop |
| |
| Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}:@var{keep_aspect} |
| |
| The @var{keep_aspect} parameter is optional, if specified and set to a |
| non-zero value will force the output display aspect ratio to be the |
| same of the input, by changing the output sample aspect ratio. |
| |
| The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are |
| expressions containing the following constants: |
| |
| @table @option |
| @item x, y |
| the computed values for @var{x} and @var{y}. They are evaluated for |
| each new frame. |
| |
| @item in_w, in_h |
| the input width and height |
| |
| @item iw, ih |
| same as @var{in_w} and @var{in_h} |
| |
| @item out_w, out_h |
| the output (cropped) width and height |
| |
| @item ow, oh |
| same as @var{out_w} and @var{out_h} |
| |
| @item a |
| same as @var{iw} / @var{ih} |
| |
| @item sar |
| input sample aspect ratio |
| |
| @item dar |
| input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} |
| |
| @item hsub, vsub |
| horizontal and vertical chroma subsample values. For example for the |
| pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| |
| @item n |
| the number of input frame, starting from 0 |
| |
| @item pos |
| the position in the file of the input frame, NAN if unknown |
| |
| @item t |
| timestamp expressed in seconds, NAN if the input timestamp is unknown |
| |
| @end table |
| |
| The @var{out_w} and @var{out_h} parameters specify the expressions for |
| the width and height of the output (cropped) video. They are |
| evaluated just at the configuration of the filter. |
| |
| The default value of @var{out_w} is "in_w", and the default value of |
| @var{out_h} is "in_h". |
| |
| The expression for @var{out_w} may depend on the value of @var{out_h}, |
| and the expression for @var{out_h} may depend on @var{out_w}, but they |
| cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are |
| evaluated after @var{out_w} and @var{out_h}. |
| |
| The @var{x} and @var{y} parameters specify the expressions for the |
| position of the top-left corner of the output (non-cropped) area. They |
| are evaluated for each frame. If the evaluated value is not valid, it |
| is approximated to the nearest valid value. |
| |
| The default value of @var{x} is "(in_w-out_w)/2", and the default |
| value for @var{y} is "(in_h-out_h)/2", which set the cropped area at |
| the center of the input image. |
| |
| The expression for @var{x} may depend on @var{y}, and the expression |
| for @var{y} may depend on @var{x}. |
| |
| Follow some examples: |
| @example |
| # crop the central input area with size 100x100 |
| crop=100:100 |
| |
| # crop the central input area with size 2/3 of the input video |
| "crop=2/3*in_w:2/3*in_h" |
| |
| # crop the input video central square |
| crop=in_h |
| |
| # delimit the rectangle with the top-left corner placed at position |
| # 100:100 and the right-bottom corner corresponding to the right-bottom |
| # corner of the input image. |
| crop=in_w-100:in_h-100:100:100 |
| |
| # crop 10 pixels from the left and right borders, and 20 pixels from |
| # the top and bottom borders |
| "crop=in_w-2*10:in_h-2*20" |
| |
| # keep only the bottom right quarter of the input image |
| "crop=in_w/2:in_h/2:in_w/2:in_h/2" |
| |
| # crop height for getting Greek harmony |
| "crop=in_w:1/PHI*in_w" |
| |
| # trembling effect |
| "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)" |
| |
| # erratic camera effect depending on timestamp |
| "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)" |
| |
| # set x depending on the value of y |
| "crop=in_w/2:in_h/2:y:10+10*sin(n/10)" |
| @end example |
| |
| @section cropdetect |
| |
| Auto-detect crop size. |
| |
| Calculate necessary cropping parameters and prints the recommended |
| parameters through the logging system. The detected dimensions |
| correspond to the non-black area of the input video. |
| |
| It accepts the syntax: |
| @example |
| cropdetect[=@var{limit}[:@var{round}[:@var{reset}]]] |
| @end example |
| |
| @table @option |
| |
| @item limit |
| Threshold, which can be optionally specified from nothing (0) to |
| everything (255), defaults to 24. |
| |
| @item round |
| Value which the width/height should be divisible by, defaults to |
| 16. The offset is automatically adjusted to center the video. Use 2 to |
| get only even dimensions (needed for 4:2:2 video). 16 is best when |
| encoding to most video codecs. |
| |
| @item reset |
| Counter that determines after how many frames cropdetect will reset |
| the previously detected largest video area and start over to detect |
| the current optimal crop area. Defaults to 0. |
| |
| This can be useful when channel logos distort the video area. 0 |
| indicates never reset and return the largest area encountered during |
| playback. |
| @end table |
| |
| @section delogo |
| |
| Suppress a TV station logo by a simple interpolation of the surrounding |
| pixels. Just set a rectangle covering the logo and watch it disappear |
| (and sometimes something even uglier appear - your mileage may vary). |
| |
| The filter accepts parameters as a string of the form |
| "@var{x}:@var{y}:@var{w}:@var{h}:@var{band}", or as a list of |
| @var{key}=@var{value} pairs, separated by ":". |
| |
| The description of the accepted parameters follows. |
| |
| @table @option |
| |
| @item x, y |
| Specify the top left corner coordinates of the logo. They must be |
| specified. |
| |
| @item w, h |
| Specify the width and height of the logo to clear. They must be |
| specified. |
| |
| @item band, t |
| Specify the thickness of the fuzzy edge of the rectangle (added to |
| @var{w} and @var{h}). The default value is 4. |
| |
| @item show |
| When set to 1, a green rectangle is drawn on the screen to simplify |
| finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and |
| @var{band} is set to 4. The default value is 0. |
| |
| @end table |
| |
| Some examples follow. |
| |
| @itemize |
| |
| @item |
| Set a rectangle covering the area with top left corner coordinates 0,0 |
| and size 100x77, setting a band of size 10: |
| @example |
| delogo=0:0:100:77:10 |
| @end example |
| |
| @item |
| As the previous example, but use named options: |
| @example |
| delogo=x=0:y=0:w=100:h=77:band=10 |
| @end example |
| |
| @end itemize |
| |
| @section deshake |
| |
| Attempt to fix small changes in horizontal and/or vertical shift. This |
| filter helps remove camera shake from hand-holding a camera, bumping a |
| tripod, moving on a vehicle, etc. |
| |
| The filter accepts parameters as a string of the form |
| "@var{x}:@var{y}:@var{w}:@var{h}:@var{rx}:@var{ry}:@var{edge}:@var{blocksize}:@var{contrast}:@var{search}:@var{filename}" |
| |
| A description of the accepted parameters follows. |
| |
| @table @option |
| |
| @item x, y, w, h |
| Specify a rectangular area where to limit the search for motion |
| vectors. |
| If desired the search for motion vectors can be limited to a |
| rectangular area of the frame defined by its top left corner, width |
| and height. These parameters have the same meaning as the drawbox |
| filter which can be used to visualise the position of the bounding |
| box. |
| |
| This is useful when simultaneous movement of subjects within the frame |
| might be confused for camera motion by the motion vector search. |
| |
| If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1 |
| then the full frame is used. This allows later options to be set |
| without specifying the bounding box for the motion vector search. |
| |
| Default - search the whole frame. |
| |
| @item rx, ry |
| Specify the maximum extent of movement in x and y directions in the |
| range 0-64 pixels. Default 16. |
| |
| @item edge |
| Specify how to generate pixels to fill blanks at the edge of the |
| frame. An integer from 0 to 3 as follows: |
| @table @option |
| @item 0 |
| Fill zeroes at blank locations |
| @item 1 |
| Original image at blank locations |
| @item 2 |
| Extruded edge value at blank locations |
| @item 3 |
| Mirrored edge at blank locations |
| @end table |
| |
| The default setting is mirror edge at blank locations. |
| |
| @item blocksize |
| Specify the blocksize to use for motion search. Range 4-128 pixels, |
| default 8. |
| |
| @item contrast |
| Specify the contrast threshold for blocks. Only blocks with more than |
| the specified contrast (difference between darkest and lightest |
| pixels) will be considered. Range 1-255, default 125. |
| |
| @item search |
| Specify the search strategy 0 = exhaustive search, 1 = less exhaustive |
| search. Default - exhaustive search. |
| |
| @item filename |
| If set then a detailed log of the motion search is written to the |
| specified file. |
| |
| @end table |
| |
| @section drawbox |
| |
| Draw a colored box on the input image. |
| |
| It accepts the syntax: |
| @example |
| drawbox=@var{x}:@var{y}:@var{width}:@var{height}:@var{color} |
| @end example |
| |
| @table @option |
| |
| @item x, y |
| Specify the top left corner coordinates of the box. Default to 0. |
| |
| @item width, height |
| Specify the width and height of the box, if 0 they are interpreted as |
| the input width and height. Default to 0. |
| |
| @item color |
| Specify the color of the box to write, it can be the name of a color |
| (case insensitive match) or a 0xRRGGBB[AA] sequence. |
| @end table |
| |
| Follow some examples: |
| @example |
| # draw a black box around the edge of the input image |
| drawbox |
| |
| # draw a box with color red and an opacity of 50% |
| drawbox=10:20:200:60:red@@0.5" |
| @end example |
| |
| @section drawtext |
| |
| Draw text string or text from specified file on top of video using the |
| libfreetype library. |
| |
| To enable compilation of this filter you need to configure FFmpeg with |
| @code{--enable-libfreetype}. |
| |
| The filter also recognizes strftime() sequences in the provided text |
| and expands them accordingly. Check the documentation of strftime(). |
| |
| The filter accepts parameters as a list of @var{key}=@var{value} pairs, |
| separated by ":". |
| |
| The description of the accepted parameters follows. |
| |
| @table @option |
| |
| @item box |
| Used to draw a box around text using background color. |
| Value should be either 1 (enable) or 0 (disable). |
| The default value of @var{box} is 0. |
| |
| @item boxcolor |
| The color to be used for drawing box around text. |
| Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format |
| (e.g. "0xff00ff"), possibly followed by an alpha specifier. |
| The default value of @var{boxcolor} is "white". |
| |
| @item draw |
| Set an expression which specifies if the text should be drawn. If the |
| expression evaluates to 0, the text is not drawn. This is useful for |
| specifying that the text should be drawn only when specific conditions |
| are met. |
| |
| Default value is "1". |
| |
| See below for the list of accepted constants and functions. |
| |
| @item fix_bounds |
| If true, check and fix text coords to avoid clipping. |
| |
| @item fontcolor |
| The color to be used for drawing fonts. |
| Either a string (e.g. "red") or in 0xRRGGBB[AA] format |
| (e.g. "0xff000033"), possibly followed by an alpha specifier. |
| The default value of @var{fontcolor} is "black". |
| |
| @item fontfile |
| The font file to be used for drawing text. Path must be included. |
| This parameter is mandatory. |
| |
| @item fontsize |
| The font size to be used for drawing text. |
| The default value of @var{fontsize} is 16. |
| |
| @item ft_load_flags |
| Flags to be used for loading the fonts. |
| |
| The flags map the corresponding flags supported by libfreetype, and are |
| a combination of the following values: |
| @table @var |
| @item default |
| @item no_scale |
| @item no_hinting |
| @item render |
| @item no_bitmap |
| @item vertical_layout |
| @item force_autohint |
| @item crop_bitmap |
| @item pedantic |
| @item ignore_global_advance_width |
| @item no_recurse |
| @item ignore_transform |
| @item monochrome |
| @item linear_design |
| @item no_autohint |
| @item end table |
| @end table |
| |
| Default value is "render". |
| |
| For more information consult the documentation for the FT_LOAD_* |
| libfreetype flags. |
| |
| @item shadowcolor |
| The color to be used for drawing a shadow behind the drawn text. It |
| can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA] |
| form (e.g. "0xff00ff"), possibly followed by an alpha specifier. |
| The default value of @var{shadowcolor} is "black". |
| |
| @item shadowx, shadowy |
| The x and y offsets for the text shadow position with respect to the |
| position of the text. They can be either positive or negative |
| values. Default value for both is "0". |
| |
| @item tabsize |
| The size in number of spaces to use for rendering the tab. |
| Default value is 4. |
| |
| @item timecode |
| Set the initial timecode representation in "hh:mm:ss[:;.]ff" |
| format. It can be used with or without text parameter. @var{timecode_rate} |
| option must be specified. |
| |
| @item timecode_rate, rate, r |
| Set the timecode frame rate (timecode only). |
| |
| @item text |
| The text string to be drawn. The text must be a sequence of UTF-8 |
| encoded characters. |
| This parameter is mandatory if no file is specified with the parameter |
| @var{textfile}. |
| |
| @item textfile |
| A text file containing text to be drawn. The text must be a sequence |
| of UTF-8 encoded characters. |
| |
| This parameter is mandatory if no text string is specified with the |
| parameter @var{text}. |
| |
| If both @var{text} and @var{textfile} are specified, an error is thrown. |
| |
| @item x, y |
| The expressions which specify the offsets where text will be drawn |
| within the video frame. They are relative to the top/left border of the |
| output image. |
| |
| The default value of @var{x} and @var{y} is "0". |
| |
| See below for the list of accepted constants and functions. |
| @end table |
| |
| The parameters for @var{x} and @var{y} are expressions containing the |
| following constants and functions: |
| |
| @table @option |
| @item dar |
| input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} |
| |
| @item hsub, vsub |
| horizontal and vertical chroma subsample values. For example for the |
| pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| |
| @item line_h, lh |
| the height of each text line |
| |
| @item main_h, h, H |
| the input height |
| |
| @item main_w, w, W |
| the input width |
| |
| @item max_glyph_a, ascent |
| the maximum distance from the baseline to the highest/upper grid |
| coordinate used to place a glyph outline point, for all the rendered |
| glyphs. |
| It is a positive value, due to the grid's orientation with the Y axis |
| upwards. |
| |
| @item max_glyph_d, descent |
| the maximum distance from the baseline to the lowest grid coordinate |
| used to place a glyph outline point, for all the rendered glyphs. |
| This is a negative value, due to the grid's orientation, with the Y axis |
| upwards. |
| |
| @item max_glyph_h |
| maximum glyph height, that is the maximum height for all the glyphs |
| contained in the rendered text, it is equivalent to @var{ascent} - |
| @var{descent}. |
| |
| @item max_glyph_w |
| maximum glyph width, that is the maximum width for all the glyphs |
| contained in the rendered text |
| |
| @item n |
| the number of input frame, starting from 0 |
| |
| @item rand(min, max) |
| return a random number included between @var{min} and @var{max} |
| |
| @item sar |
| input sample aspect ratio |
| |
| @item t |
| timestamp expressed in seconds, NAN if the input timestamp is unknown |
| |
| @item text_h, th |
| the height of the rendered text |
| |
| @item text_w, tw |
| the width of the rendered text |
| |
| @item x, y |
| the x and y offset coordinates where the text is drawn. |
| |
| These parameters allow the @var{x} and @var{y} expressions to refer |
| each other, so you can for example specify @code{y=x/dar}. |
| @end table |
| |
| If libavfilter was built with @code{--enable-fontconfig}, then |
| @option{fontfile} can be a fontconfig pattern or omitted. |
| |
| Some examples follow. |
| |
| @itemize |
| |
| @item |
| Draw "Test Text" with font FreeSerif, using the default values for the |
| optional parameters. |
| |
| @example |
| drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'" |
| @end example |
| |
| @item |
| Draw 'Test Text' with font FreeSerif of size 24 at position x=100 |
| and y=50 (counting from the top-left corner of the screen), text is |
| yellow with a red box around it. Both the text and the box have an |
| opacity of 20%. |
| |
| @example |
| 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" |
| @end example |
| |
| Note that the double quotes are not necessary if spaces are not used |
| within the parameter list. |
| |
| @item |
| Show the text at the center of the video frame: |
| @example |
| drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2" |
| @end example |
| |
| @item |
| Show a text line sliding from right to left in the last row of the video |
| frame. The file @file{LONG_LINE} is assumed to contain a single line |
| with no newlines. |
| @example |
| drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t" |
| @end example |
| |
| @item |
| Show the content of file @file{CREDITS} off the bottom of the frame and scroll up. |
| @example |
| drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t" |
| @end example |
| |
| @item |
| Draw a single green letter "g", at the center of the input video. |
| The glyph baseline is placed at half screen height. |
| @example |
| drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent" |
| @end example |
| |
| @item |
| Show text for 1 second every 3 seconds: |
| @example |
| drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:draw=lt(mod(t\\,3)\\,1):text='blink'" |
| @end example |
| |
| @item |
| Use fontconfig to set the font. Note that the colons need to be escaped. |
| @example |
| drawtext='fontfile=Linux Libertine O-40\\:style=Semibold:text=FFmpeg' |
| @end example |
| |
| @end itemize |
| |
| For more information about libfreetype, check: |
| @url{http://www.freetype.org/}. |
| |
| For more information about fontconfig, check: |
| @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}. |
| |
| @section fade |
| |
| Apply fade-in/out effect to input video. |
| |
| It accepts the parameters: |
| @var{type}:@var{start_frame}:@var{nb_frames}[:@var{options}] |
| |
| @var{type} specifies if the effect type, can be either "in" for |
| fade-in, or "out" for a fade-out effect. |
| |
| @var{start_frame} specifies the number of the start frame for starting |
| to apply the fade effect. |
| |
| @var{nb_frames} specifies the number of frames for which the fade |
| effect has to last. At the end of the fade-in effect the output video |
| will have the same intensity as the input video, at the end of the |
| fade-out transition the output video will be completely black. |
| |
| @var{options} is an optional sequence of @var{key}=@var{value} pairs, |
| separated by ":". The description of the accepted options follows. |
| |
| @table @option |
| |
| @item type, t |
| See @var{type}. |
| |
| @item start_frame, s |
| See @var{start_frame}. |
| |
| @item nb_frames, n |
| See @var{nb_frames}. |
| |
| @item alpha |
| If set to 1, fade only alpha channel, if one exists on the input. |
| Default value is 0. |
| @end table |
| |
| A few usage examples follow, usable too as test scenarios. |
| @example |
| # fade in first 30 frames of video |
| fade=in:0:30 |
| |
| # fade out last 45 frames of a 200-frame video |
| fade=out:155:45 |
| |
| # fade in first 25 frames and fade out last 25 frames of a 1000-frame video |
| fade=in:0:25, fade=out:975:25 |
| |
| # make first 5 frames black, then fade in from frame 5-24 |
| fade=in:5:20 |
| |
| # fade in alpha over first 25 frames of video |
| fade=in:0:25:alpha=1 |
| @end example |
| |
| @section fieldorder |
| |
| Transform the field order of the input video. |
| |
| It accepts one parameter which specifies the required field order that |
| the input interlaced video will be transformed to. The parameter can |
| assume one of the following values: |
| |
| @table @option |
| @item 0 or bff |
| output bottom field first |
| @item 1 or tff |
| output top field first |
| @end table |
| |
| Default value is "tff". |
| |
| Transformation is achieved by shifting the picture content up or down |
| by one line, and filling the remaining line with appropriate picture content. |
| This method is consistent with most broadcast field order converters. |
| |
| If the input video is not flagged as being interlaced, or it is already |
| flagged as being of the required output field order then this filter does |
| not alter the incoming video. |
| |
| This filter is very useful when converting to or from PAL DV material, |
| which is bottom field first. |
| |
| For example: |
| @example |
| ffmpeg -i in.vob -vf "fieldorder=bff" out.dv |
| @end example |
| |
| @section fifo |
| |
| Buffer input images and send them when they are requested. |
| |
| This filter is mainly useful when auto-inserted by the libavfilter |
| framework. |
| |
| The filter does not take parameters. |
| |
| @section format |
| |
| Convert the input video to one of the specified pixel formats. |
| Libavfilter will try to pick one that is supported for the input to |
| the next filter. |
| |
| The filter accepts a list of pixel format names, separated by ":", |
| for example "yuv420p:monow:rgb24". |
| |
| Some examples follow: |
| @example |
| # convert the input video to the format "yuv420p" |
| format=yuv420p |
| |
| # convert the input video to any of the formats in the list |
| format=yuv420p:yuv444p:yuv410p |
| @end example |
| |
| @section fps |
| |
| Convert the video to specified constant framerate by duplicating or dropping |
| frames as necessary. |
| |
| This filter accepts the following named parameters: |
| @table @option |
| |
| @item fps |
| Desired output framerate. |
| |
| @end table |
| |
| @anchor{frei0r} |
| @section frei0r |
| |
| Apply a frei0r effect to the input video. |
| |
| To enable compilation of this filter you need to install the frei0r |
| header and configure FFmpeg with @code{--enable-frei0r}. |
| |
| The filter supports the syntax: |
| @example |
| @var{filter_name}[@{:|=@}@var{param1}:@var{param2}:...:@var{paramN}] |
| @end example |
| |
| @var{filter_name} is the name to the frei0r effect to load. If the |
| environment variable @env{FREI0R_PATH} is defined, the frei0r effect |
| is searched in each one of the directories specified by the colon |
| separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r |
| paths, which are in this order: @file{HOME/.frei0r-1/lib/}, |
| @file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}. |
| |
| @var{param1}, @var{param2}, ... , @var{paramN} specify the parameters |
| for the frei0r effect. |
| |
| A frei0r effect parameter can be a boolean (whose values are specified |
| with "y" and "n"), a double, a color (specified by the syntax |
| @var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float |
| numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color |
| description), a position (specified by the syntax @var{X}/@var{Y}, |
| @var{X} and @var{Y} being float numbers) and a string. |
| |
| The number and kind of parameters depend on the loaded effect. If an |
| effect parameter is not specified the default value is set. |
| |
| Some examples follow: |
| @example |
| # apply the distort0r effect, set the first two double parameters |
| frei0r=distort0r:0.5:0.01 |
| |
| # apply the colordistance effect, takes a color as first parameter |
| frei0r=colordistance:0.2/0.3/0.4 |
| frei0r=colordistance:violet |
| frei0r=colordistance:0x112233 |
| |
| # apply the perspective effect, specify the top left and top right |
| # image positions |
| frei0r=perspective:0.2/0.2:0.8/0.2 |
| @end example |
| |
| For more information see: |
| @url{http://piksel.org/frei0r} |
| |
| @section gradfun |
| |
| Fix the banding artifacts that are sometimes introduced into nearly flat |
| regions by truncation to 8bit color depth. |
| Interpolate the gradients that should go where the bands are, and |
| dither them. |
| |
| This filter is designed for playback only. Do not use it prior to |
| lossy compression, because compression tends to lose the dither and |
| bring back the bands. |
| |
| The filter takes two optional parameters, separated by ':': |
| @var{strength}:@var{radius} |
| |
| @var{strength} is the maximum amount by which the filter will change |
| any one pixel. Also the threshold for detecting nearly flat |
| regions. Acceptable values range from .51 to 255, default value is |
| 1.2, out-of-range values will be clipped to the valid range. |
| |
| @var{radius} is the neighborhood to fit the gradient to. A larger |
| radius makes for smoother gradients, but also prevents the filter from |
| modifying the pixels near detailed regions. Acceptable values are |
| 8-32, default value is 16, out-of-range values will be clipped to the |
| valid range. |
| |
| @example |
| # default parameters |
| gradfun=1.2:16 |
| |
| # omitting radius |
| gradfun=1.2 |
| @end example |
| |
| @section hflip |
| |
| Flip the input video horizontally. |
| |
| For example to horizontally flip the input video with @command{ffmpeg}: |
| @example |
| ffmpeg -i in.avi -vf "hflip" out.avi |
| @end example |
| |
| @section hqdn3d |
| |
| High precision/quality 3d denoise filter. This filter aims to reduce |
| image noise producing smooth images and making still images really |
| still. It should enhance compressibility. |
| |
| It accepts the following optional parameters: |
| @var{luma_spatial}:@var{chroma_spatial}:@var{luma_tmp}:@var{chroma_tmp} |
| |
| @table @option |
| @item luma_spatial |
| a non-negative float number which specifies spatial luma strength, |
| defaults to 4.0 |
| |
| @item chroma_spatial |
| a non-negative float number which specifies spatial chroma strength, |
| defaults to 3.0*@var{luma_spatial}/4.0 |
| |
| @item luma_tmp |
| a float number which specifies luma temporal strength, defaults to |
| 6.0*@var{luma_spatial}/4.0 |
| |
| @item chroma_tmp |
| a float number which specifies chroma temporal strength, defaults to |
| @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial} |
| @end table |
| |
| @section idet |
| |
| Interlaceing detect filter. This filter tries to detect if the input is |
| interlaced or progressive. Top or bottom field first. |
| |
| @section lut, lutrgb, lutyuv |
| |
| Compute a look-up table for binding each pixel component input value |
| to an output value, and apply it to input video. |
| |
| @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb} |
| to an RGB input video. |
| |
| These filters accept in input a ":"-separated list of options, which |
| specify the expressions used for computing the lookup table for the |
| corresponding pixel component values. |
| |
| The @var{lut} filter requires either YUV or RGB pixel formats in |
| input, and accepts the options: |
| @table @option |
| @item c0 |
| first pixel component |
| @item c1 |
| second pixel component |
| @item c2 |
| third pixel component |
| @item c3 |
| fourth pixel component, corresponds to the alpha component |
| @end table |
| |
| The exact component associated to each option depends on the format in |
| input. |
| |
| The @var{lutrgb} filter requires RGB pixel formats in input, and |
| accepts the options: |
| @table @option |
| @item r |
| red component |
| @item g |
| green component |
| @item b |
| blue component |
| @item a |
| alpha component |
| @end table |
| |
| The @var{lutyuv} filter requires YUV pixel formats in input, and |
| accepts the options: |
| @table @option |
| @item y |
| Y/luminance component |
| @item u |
| U/Cb component |
| @item v |
| V/Cr component |
| @item a |
| alpha component |
| @end table |
| |
| The expressions can contain the following constants and functions: |
| |
| @table @option |
| @item w, h |
| the input width and height |
| |
| @item val |
| input value for the pixel component |
| |
| @item clipval |
| the input value clipped in the @var{minval}-@var{maxval} range |
| |
| @item maxval |
| maximum value for the pixel component |
| |
| @item minval |
| minimum value for the pixel component |
| |
| @item negval |
| the negated value for the pixel component value clipped in the |
| @var{minval}-@var{maxval} range , it corresponds to the expression |
| "maxval-clipval+minval" |
| |
| @item clip(val) |
| the computed value in @var{val} clipped in the |
| @var{minval}-@var{maxval} range |
| |
| @item gammaval(gamma) |
| the computed gamma correction value of the pixel component value |
| clipped in the @var{minval}-@var{maxval} range, corresponds to the |
| expression |
| "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval" |
| |
| @end table |
| |
| All expressions default to "val". |
| |
| Some examples follow: |
| @example |
| # negate input video |
| lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val" |
| lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val" |
| |
| # the above is the same as |
| lutrgb="r=negval:g=negval:b=negval" |
| lutyuv="y=negval:u=negval:v=negval" |
| |
| # negate luminance |
| lutyuv=y=negval |
| |
| # remove chroma components, turns the video into a graytone image |
| lutyuv="u=128:v=128" |
| |
| # apply a luma burning effect |
| lutyuv="y=2*val" |
| |
| # remove green and blue components |
| lutrgb="g=0:b=0" |
| |
| # set a constant alpha channel value on input |
| format=rgba,lutrgb=a="maxval-minval/2" |
| |
| # correct luminance gamma by a 0.5 factor |
| lutyuv=y=gammaval(0.5) |
| @end example |
| |
| @section mp |
| |
| Apply an MPlayer filter to the input video. |
| |
| This filter provides a wrapper around most of the filters of |
| MPlayer/MEncoder. |
| |
| This wrapper is considered experimental. Some of the wrapped filters |
| may not work properly and we may drop support for them, as they will |
| be implemented natively into FFmpeg. Thus you should avoid |
| depending on them when writing portable scripts. |
| |
| The filters accepts the parameters: |
| @var{filter_name}[:=]@var{filter_params} |
| |
| @var{filter_name} is the name of a supported MPlayer filter, |
| @var{filter_params} is a string containing the parameters accepted by |
| the named filter. |
| |
| The list of the currently supported filters follows: |
| @table @var |
| @item decimate |
| @item denoise3d |
| @item detc |
| @item dint |
| @item divtc |
| @item down3dright |
| @item dsize |
| @item eq2 |
| @item eq |
| @item field |
| @item fil |
| @item fixpts |
| @item framestep |
| @item fspp |
| @item geq |
| @item harddup |
| @item hqdn3d |
| @item hue |
| @item il |
| @item ilpack |
| @item ivtc |
| @item kerndeint |
| @item mcdeint |
| @item noise |
| @item ow |
| @item palette |
| @item perspective |
| @item phase |
| @item pp7 |
| @item pullup |
| @item qp |
| @item rectangle |
| @item rotate |
| @item sab |
| @item smartblur |
| @item softpulldown |
| @item softskip |
| @item spp |
| @item telecine |
| @item tile |
| @item tinterlace |
| @item unsharp |
| @item uspp |
| @item yuvcsp |
| @item yvu9 |
| @end table |
| |
| The parameter syntax and behavior for the listed filters are the same |
| of the corresponding MPlayer filters. For detailed instructions check |
| the "VIDEO FILTERS" section in the MPlayer manual. |
| |
| Some examples follow: |
| @example |
| # adjust gamma, brightness, contrast |
| mp=eq2=1.0:2:0.5 |
| |
| # tweak hue and saturation |
| mp=hue=100:-10 |
| @end example |
| |
| See also mplayer(1), @url{http://www.mplayerhq.hu/}. |
| |
| @section negate |
| |
| Negate input video. |
| |
| This filter accepts an integer in input, if non-zero it negates the |
| alpha component (if available). The default value in input is 0. |
| |
| @section noformat |
| |
| Force libavfilter not to use any of the specified pixel formats for the |
| input to the next filter. |
| |
| The filter accepts a list of pixel format names, separated by ":", |
| for example "yuv420p:monow:rgb24". |
| |
| Some examples follow: |
| @example |
| # force libavfilter to use a format different from "yuv420p" for the |
| # input to the vflip filter |
| noformat=yuv420p,vflip |
| |
| # convert the input video to any of the formats not contained in the list |
| noformat=yuv420p:yuv444p:yuv410p |
| @end example |
| |
| @section null |
| |
| Pass the video source unchanged to the output. |
| |
| @section ocv |
| |
| Apply video transform using libopencv. |
| |
| To enable this filter install libopencv library and headers and |
| configure FFmpeg with @code{--enable-libopencv}. |
| |
| The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}. |
| |
| @var{filter_name} is the name of the libopencv filter to apply. |
| |
| @var{filter_params} specifies the parameters to pass to the libopencv |
| filter. If not specified the default values are assumed. |
| |
| Refer to the official libopencv documentation for more precise |
| information: |
| @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html} |
| |
| Follows the list of supported libopencv filters. |
| |
| @anchor{dilate} |
| @subsection dilate |
| |
| Dilate an image by using a specific structuring element. |
| This filter corresponds to the libopencv function @code{cvDilate}. |
| |
| It accepts the parameters: @var{struct_el}:@var{nb_iterations}. |
| |
| @var{struct_el} represents a structuring element, and has the syntax: |
| @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape} |
| |
| @var{cols} and @var{rows} represent the number of columns and rows of |
| the structuring element, @var{anchor_x} and @var{anchor_y} the anchor |
| point, and @var{shape} the shape for the structuring element, and |
| can be one of the values "rect", "cross", "ellipse", "custom". |
| |
| If the value for @var{shape} is "custom", it must be followed by a |
| string of the form "=@var{filename}". The file with name |
| @var{filename} is assumed to represent a binary image, with each |
| printable character corresponding to a bright pixel. When a custom |
| @var{shape} is used, @var{cols} and @var{rows} are ignored, the number |
| or columns and rows of the read file are assumed instead. |
| |
| The default value for @var{struct_el} is "3x3+0x0/rect". |
| |
| @var{nb_iterations} specifies the number of times the transform is |
| applied to the image, and defaults to 1. |
| |
| Follow some example: |
| @example |
| # use the default values |
| ocv=dilate |
| |
| # dilate using a structuring element with a 5x5 cross, iterate two times |
| ocv=dilate=5x5+2x2/cross:2 |
| |
| # read the shape from the file diamond.shape, iterate two times |
| # the file diamond.shape may contain a pattern of characters like this: |
| # * |
| # *** |
| # ***** |
| # *** |
| # * |
| # the specified cols and rows are ignored (but not the anchor point coordinates) |
| ocv=0x0+2x2/custom=diamond.shape:2 |
| @end example |
| |
| @subsection erode |
| |
| Erode an image by using a specific structuring element. |
| This filter corresponds to the libopencv function @code{cvErode}. |
| |
| The filter accepts the parameters: @var{struct_el}:@var{nb_iterations}, |
| with the same syntax and semantics as the @ref{dilate} filter. |
| |
| @subsection smooth |
| |
| Smooth the input video. |
| |
| The filter takes the following parameters: |
| @var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}. |
| |
| @var{type} is the type of smooth filter to apply, and can be one of |
| the following values: "blur", "blur_no_scale", "median", "gaussian", |
| "bilateral". The default value is "gaussian". |
| |
| @var{param1}, @var{param2}, @var{param3}, and @var{param4} are |
| parameters whose meanings depend on smooth type. @var{param1} and |
| @var{param2} accept integer positive values or 0, @var{param3} and |
| @var{param4} accept float values. |
| |
| The default value for @var{param1} is 3, the default value for the |
| other parameters is 0. |
| |
| These parameters correspond to the parameters assigned to the |
| libopencv function @code{cvSmooth}. |
| |
| @anchor{overlay} |
| @section overlay |
| |
| Overlay one video on top of another. |
| |
| It takes two inputs and one output, the first input is the "main" |
| video on which the second input is overlayed. |
| |
| It accepts the parameters: @var{x}:@var{y}[:@var{options}]. |
| |
| @var{x} is the x coordinate of the overlayed video on the main video, |
| @var{y} is the y coordinate. @var{x} and @var{y} are expressions containing |
| the following parameters: |
| |
| @table @option |
| @item main_w, main_h |
| main input width and height |
| |
| @item W, H |
| same as @var{main_w} and @var{main_h} |
| |
| @item overlay_w, overlay_h |
| overlay input width and height |
| |
| @item w, h |
| same as @var{overlay_w} and @var{overlay_h} |
| @end table |
| |
| @var{options} is an optional list of @var{key}=@var{value} pairs, |
| separated by ":". |
| |
| The description of the accepted options follows. |
| |
| @table @option |
| @item rgb |
| If set to 1, force the filter to accept inputs in the RGB |
| color space. Default value is 0. |
| @end table |
| |
| Be aware that frames are taken from each input video in timestamp |
| order, hence, if their initial timestamps differ, it is a a good idea |
| to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to |
| have them begin in the same zero timestamp, as it does the example for |
| the @var{movie} filter. |
| |
| Follow some examples: |
| @example |
| # draw the overlay at 10 pixels from the bottom right |
| # corner of the main video. |
| overlay=main_w-overlay_w-10:main_h-overlay_h-10 |
| |
| # insert a transparent PNG logo in the bottom left corner of the input |
| ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output |
| |
| # insert 2 different transparent PNG logos (second logo on bottom |
| # right corner): |
| ffmpeg -i input -i logo1 -i logo2 -filter_complex |
| 'overlay=10:H-h-10,overlay=W-w-10:H-h-10' output |
| |
| # add a transparent color layer on top of the main video, |
| # WxH specifies the size of the main input to the overlay filter |
| color=red@.3:WxH [over]; [in][over] overlay [out] |
| @end example |
| |
| You can chain together more overlays but the efficiency of such |
| approach is yet to be tested. |
| |
| @section pad |
| |
| Add paddings to the input image, and places the original input at the |
| given coordinates @var{x}, @var{y}. |
| |
| It accepts the following parameters: |
| @var{width}:@var{height}:@var{x}:@var{y}:@var{color}. |
| |
| The parameters @var{width}, @var{height}, @var{x}, and @var{y} are |
| expressions containing the following constants: |
| |
| @table @option |
| @item in_w, in_h |
| the input video width and height |
| |
| @item iw, ih |
| same as @var{in_w} and @var{in_h} |
| |
| @item out_w, out_h |
| the output width and height, that is the size of the padded area as |
| specified by the @var{width} and @var{height} expressions |
| |
| @item ow, oh |
| same as @var{out_w} and @var{out_h} |
| |
| @item x, y |
| x and y offsets as specified by the @var{x} and @var{y} |
| expressions, or NAN if not yet specified |
| |
| @item a |
| same as @var{iw} / @var{ih} |
| |
| @item sar |
| input sample aspect ratio |
| |
| @item dar |
| input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} |
| |
| @item hsub, vsub |
| horizontal and vertical chroma subsample values. For example for the |
| pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| @end table |
| |
| Follows the description of the accepted parameters. |
| |
| @table @option |
| @item width, height |
| |
| Specify the size of the output image with the paddings added. If the |
| value for @var{width} or @var{height} is 0, the corresponding input size |
| is used for the output. |
| |
| The @var{width} expression can reference the value set by the |
| @var{height} expression, and vice versa. |
| |
| The default value of @var{width} and @var{height} is 0. |
| |
| @item x, y |
| |
| Specify the offsets where to place the input image in the padded area |
| with respect to the top/left border of the output image. |
| |
| The @var{x} expression can reference the value set by the @var{y} |
| expression, and vice versa. |
| |
| The default value of @var{x} and @var{y} is 0. |
| |
| @item color |
| |
| Specify the color of the padded area, it can be the name of a color |
| (case insensitive match) or a 0xRRGGBB[AA] sequence. |
| |
| The default value of @var{color} is "black". |
| |
| @end table |
| |
| Some examples follow: |
| |
| @example |
| # Add paddings with color "violet" to the input video. Output video |
| # size is 640x480, the top-left corner of the input video is placed at |
| # column 0, row 40. |
| pad=640:480:0:40:violet |
| |
| # pad the input to get an output with dimensions increased bt 3/2, |
| # and put the input video at the center of the padded area |
| pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2" |
| |
| # pad the input to get a squared output with size equal to the maximum |
| # value between the input width and height, and put the input video at |
| # the center of the padded area |
| pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2" |
| |
| # pad the input to get a final w/h ratio of 16:9 |
| pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2" |
| |
| # for anamorphic video, in order to set the output display aspect ratio, |
| # it is necessary to use sar in the expression, according to the relation: |
| # (ih * X / ih) * sar = output_dar |
| # X = output_dar / sar |
| pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2" |
| |
| # double output size and put the input video in the bottom-right |
| # corner of the output padded area |
| pad="2*iw:2*ih:ow-iw:oh-ih" |
| @end example |
| |
| @section pixdesctest |
| |
| Pixel format descriptor test filter, mainly useful for internal |
| testing. The output video should be equal to the input video. |
| |
| For example: |
| @example |
| format=monow, pixdesctest |
| @end example |
| |
| can be used to test the monowhite pixel format descriptor definition. |
| |
| @section removelogo |
| |
| Suppress a TV station logo, using an image file to determine which |
| pixels comprise the logo. It works by filling in the pixels that |
| comprise the logo with neighboring pixels. |
| |
| This filter requires one argument which specifies the filter bitmap |
| file, which can be any image format supported by libavformat. The |
| width and height of the image file must match those of the video |
| stream being processed. |
| |
| Pixels in the provided bitmap image with a value of zero are not |
| considered part of the logo, non-zero pixels are considered part of |
| the logo. If you use white (255) for the logo and black (0) for the |
| rest, you will be safe. For making the filter bitmap, it is |
| recommended to take a screen capture of a black frame with the logo |
| visible, and then using a threshold filter followed by the erode |
| filter once or twice. |
| |
| If needed, little splotches can be fixed manually. Remember that if |
| logo pixels are not covered, the filter quality will be much |
| reduced. Marking too many pixels as part of the logo does not hurt as |
| much, but it will increase the amount of blurring needed to cover over |
| the image and will destroy more information than necessary, and extra |
| pixels will slow things down on a large logo. |
| |
| @section scale |
| |
| Scale the input video to @var{width}:@var{height}[:@var{interl}=@{1|-1@}] and/or convert the image format. |
| |
| The scale filter forces the output display aspect ratio to be the same |
| of the input, by changing the output sample aspect ratio. |
| |
| The parameters @var{width} and @var{height} are expressions containing |
| the following constants: |
| |
| @table @option |
| @item in_w, in_h |
| the input width and height |
| |
| @item iw, ih |
| same as @var{in_w} and @var{in_h} |
| |
| @item out_w, out_h |
| the output (cropped) width and height |
| |
| @item ow, oh |
| same as @var{out_w} and @var{out_h} |
| |
| @item a |
| same as @var{iw} / @var{ih} |
| |
| @item sar |
| input sample aspect ratio |
| |
| @item dar |
| input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} |
| |
| @item hsub, vsub |
| horizontal and vertical chroma subsample values. For example for the |
| pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| @end table |
| |
| If the input image format is different from the format requested by |
| the next filter, the scale filter will convert the input to the |
| requested format. |
| |
| If the value for @var{width} or @var{height} is 0, the respective input |
| size is used for the output. |
| |
| If the value for @var{width} or @var{height} is -1, the scale filter will |
| use, for the respective output size, a value that maintains the aspect |
| ratio of the input image. |
| |
| The default value of @var{width} and @var{height} is 0. |
| |
| Valid values for the optional parameter @var{interl} are: |
| |
| @table @option |
| @item 1 |
| force interlaced aware scaling |
| |
| @item -1 |
| select interlaced aware scaling depending on whether the source frames |
| are flagged as interlaced or not |
| @end table |
| |
| Unless @var{interl} is set to one of the above options, interlaced scaling will not be used. |
| |
| Some examples follow: |
| @example |
| # scale the input video to a size of 200x100. |
| scale=200:100 |
| |
| # scale the input to 2x |
| scale=2*iw:2*ih |
| # the above is the same as |
| scale=2*in_w:2*in_h |
| |
| # scale the input to 2x with forced interlaced scaling |
| scale=2*iw:2*ih:interl=1 |
| |
| # scale the input to half size |
| scale=iw/2:ih/2 |
| |
| # increase the width, and set the height to the same size |
| scale=3/2*iw:ow |
| |
| # seek for Greek harmony |
| scale=iw:1/PHI*iw |
| scale=ih*PHI:ih |
| |
| # increase the height, and set the width to 3/2 of the height |
| scale=3/2*oh:3/5*ih |
| |
| # increase the size, but make the size a multiple of the chroma |
| scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" |
| |
| # increase the width to a maximum of 500 pixels, keep the same input aspect ratio |
| scale='min(500\, iw*3/2):-1' |
| @end example |
| |
| @section select |
| Select frames to pass in output. |
| |
| It accepts in input an expression, which is evaluated for each input |
| frame. If the expression is evaluated to a non-zero value, the frame |
| is selected and passed to the output, otherwise it is discarded. |
| |
| The expression can contain the following constants: |
| |
| @table @option |
| @item n |
| the sequential number of the filtered frame, starting from 0 |
| |
| @item selected_n |
| the sequential number of the selected frame, starting from 0 |
| |
| @item prev_selected_n |
| the sequential number of the last selected frame, NAN if undefined |
| |
| @item TB |
| timebase of the input timestamps |
| |
| @item pts |
| the PTS (Presentation TimeStamp) of the filtered video frame, |
| expressed in @var{TB} units, NAN if undefined |
| |
| @item t |
| the PTS (Presentation TimeStamp) of the filtered video frame, |
| expressed in seconds, NAN if undefined |
| |
| @item prev_pts |
| the PTS of the previously filtered video frame, NAN if undefined |
| |
| @item prev_selected_pts |
| the PTS of the last previously filtered video frame, NAN if undefined |
| |
| @item prev_selected_t |
| the PTS of the last previously selected video frame, NAN if undefined |
| |
| @item start_pts |
| the PTS of the first video frame in the video, NAN if undefined |
| |
| @item start_t |
| the time of the first video frame in the video, NAN if undefined |
| |
| @item pict_type |
| the type of the filtered frame, can assume one of the following |
| values: |
| @table @option |
| @item I |
| @item P |
| @item B |
| @item S |
| @item SI |
| @item SP |
| @item BI |
| @end table |
| |
| @item interlace_type |
| the frame interlace type, can assume one of the following values: |
| @table @option |
| @item PROGRESSIVE |
| the frame is progressive (not interlaced) |
| @item TOPFIRST |
| the frame is top-field-first |
| @item BOTTOMFIRST |
| the frame is bottom-field-first |
| @end table |
| |
| @item key |
| 1 if the filtered frame is a key-frame, 0 otherwise |
| |
| @item pos |
| the position in the file of the filtered frame, -1 if the information |
| is not available (e.g. for synthetic video) |
| @end table |
| |
| The default value of the select expression is "1". |
| |
| Some examples follow: |
| |
| @example |
| # select all frames in input |
| select |
| |
| # the above is the same as: |
| select=1 |
| |
| # skip all frames: |
| select=0 |
| |
| # select only I-frames |
| select='eq(pict_type\,I)' |
| |
| # select one frame every 100 |
| select='not(mod(n\,100))' |
| |
| # select only frames contained in the 10-20 time interval |
| select='gte(t\,10)*lte(t\,20)' |
| |
| # select only I frames contained in the 10-20 time interval |
| select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)' |
| |
| # select frames with a minimum distance of 10 seconds |
| select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' |
| @end example |
| |
| @section setdar, setsar |
| |
| The @code{setdar} filter sets the Display Aspect Ratio for the filter |
| output video. |
| |
| This is done by changing the specified Sample (aka Pixel) Aspect |
| Ratio, according to the following equation: |
| @example |
| @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR} |
| @end example |
| |
| Keep in mind that the @code{setdar} filter does not modify the pixel |
| dimensions of the video frame. Also the display aspect ratio set by |
| this filter may be changed by later filters in the filterchain, |
| e.g. in case of scaling or if another "setdar" or a "setsar" filter is |
| applied. |
| |
| The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for |
| the filter output video. |
| |
| Note that as a consequence of the application of this filter, the |
| output display aspect ratio will change according to the equation |
| above. |
| |
| Keep in mind that the sample aspect ratio set by the @code{setsar} |
| filter may be changed by later filters in the filterchain, e.g. if |
| another "setsar" or a "setdar" filter is applied. |
| |
| The @code{setdar} and @code{setsar} filters accept a parameter string |
| which represents the wanted aspect ratio. The parameter can |
| be a floating point number string, an expression, or a string of the form |
| @var{num}:@var{den}, where @var{num} and @var{den} are the numerator |
| and denominator of the aspect ratio. If the parameter is not |
| specified, it is assumed the value "0:1". |
| |
| For example to change the display aspect ratio to 16:9, specify: |
| @example |
| setdar=16:9 |
| @end example |
| |
| The example above is equivalent to: |
| @example |
| setdar=1.77777 |
| @end example |
| |
| To change the sample aspect ratio to 10:11, specify: |
| @example |
| setsar=10:11 |
| @end example |
| |
| @section setfield |
| |
| Force field for the output video frame. |
| |
| The @code{setfield} filter marks the interlace type field for the |
| output frames. It does not change the input frame, but only sets the |
| corresponding property, which affects how the frame is treated by |
| following filters (e.g. @code{fieldorder} or @code{yadif}). |
| |
| It accepts a string parameter, which can assume the following values: |
| @table @samp |
| @item auto |
| Keep the same field property. |
| |
| @item bff |
| Mark the frame as bottom-field-first. |
| |
| @item tff |
| Mark the frame as top-field-first. |
| |
| @item prog |
| Mark the frame as progressive. |
| @end table |
| |
| @section setpts |
| |
| Change the PTS (presentation timestamp) of the input video frames. |
| |
| Accept in input an expression evaluated through the eval API, which |
| can contain the following constants: |
| |
| @table @option |
| @item PTS |
| the presentation timestamp in input |
| |
| @item N |
| the count of the input frame, starting from 0. |
| |
| @item STARTPTS |
| the PTS of the first video frame |
| |
| @item INTERLACED |
| tell if the current frame is interlaced |
| |
| @item POS |
| original position in the file of the frame, or undefined if undefined |
| for the current frame |
| |
| @item PREV_INPTS |
| previous input PTS |
| |
| @item PREV_OUTPTS |
| previous output PTS |
| |
| @end table |
| |
| Some examples follow: |
| |
| @example |
| # start counting PTS from zero |
| setpts=PTS-STARTPTS |
| |
| # fast motion |
| setpts=0.5*PTS |
| |
| # slow motion |
| setpts=2.0*PTS |
| |
| # fixed rate 25 fps |
| setpts=N/(25*TB) |
| |
| # fixed rate 25 fps with some jitter |
| setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))' |
| @end example |
| |
| @section settb |
| |
| Set the timebase to use for the output frames timestamps. |
| It is mainly useful for testing timebase configuration. |
| |
| It accepts in input an arithmetic expression representing a rational. |
| The expression can contain the constants "AVTB" (the |
| default timebase), and "intb" (the input timebase). |
| |
| The default value for the input is "intb". |
| |
| Follow some examples. |
| |
| @example |
| # set the timebase to 1/25 |
| settb=1/25 |
| |
| # set the timebase to 1/10 |
| settb=0.1 |
| |
| #set the timebase to 1001/1000 |
| settb=1+0.001 |
| |
| #set the timebase to 2*intb |
| settb=2*intb |
| |
| #set the default timebase value |
| settb=AVTB |
| @end example |
| |
| @section showinfo |
| |
| Show a line containing various information for each input video frame. |
| The input video is not modified. |
| |
| The shown line contains a sequence of key/value pairs of the form |
| @var{key}:@var{value}. |
| |
| A description of each shown parameter follows: |
| |
| @table @option |
| @item n |
| sequential number of the input frame, starting from 0 |
| |
| @item pts |
| Presentation TimeStamp of the input frame, expressed as a number of |
| time base units. The time base unit depends on the filter input pad. |
| |
| @item pts_time |
| Presentation TimeStamp of the input frame, expressed as a number of |
| seconds |
| |
| @item pos |
| position of the frame in the input stream, -1 if this information in |
| unavailable and/or meaningless (for example in case of synthetic video) |
| |
| @item fmt |
| pixel format name |
| |
| @item sar |
| sample aspect ratio of the input frame, expressed in the form |
| @var{num}/@var{den} |
| |
| @item s |
| size of the input frame, expressed in the form |
| @var{width}x@var{height} |
| |
| @item i |
| interlaced mode ("P" for "progressive", "T" for top field first, "B" |
| for bottom field first) |
| |
| @item iskey |
| 1 if the frame is a key frame, 0 otherwise |
| |
| @item type |
| picture type of the input frame ("I" for an I-frame, "P" for a |
| P-frame, "B" for a B-frame, "?" for unknown type). |
| Check also the documentation of the @code{AVPictureType} enum and of |
| the @code{av_get_picture_type_char} function defined in |
| @file{libavutil/avutil.h}. |
| |
| @item checksum |
| Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame |
| |
| @item plane_checksum |
| Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, |
| expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]" |
| @end table |
| |
| @section slicify |
| |
| Pass the images of input video on to next video filter as multiple |
| slices. |
| |
| @example |
| ffmpeg -i in.avi -vf "slicify=32" out.avi |
| @end example |
| |
| The filter accepts the slice height as parameter. If the parameter is |
| not specified it will use the default value of 16. |
| |
| Adding this in the beginning of filter chains should make filtering |
| faster due to better use of the memory cache. |
| |
| @section split |
| |
| Split input video into several identical outputs. |
| |
| The filter accepts a single parameter which specifies the number of outputs. If |
| unspecified, it defaults to 2. |
| |
| For example |
| @example |
| ffmpeg -i INPUT -filter_complex split=5 OUTPUT |
| @end example |
| will create 5 copies of the input video. |
| |
| For example: |
| @example |
| [in] split [splitout1][splitout2]; |
| [splitout1] crop=100:100:0:0 [cropout]; |
| [splitout2] pad=200:200:100:100 [padout]; |
| @end example |
| |
| will create two separate outputs from the same input, one cropped and |
| one padded. |
| |
| @section super2xsai |
| |
| Scale the input by 2x and smooth using the Super2xSaI (Scale and |
| Interpolate) pixel art scaling algorithm. |
| |
| Useful for enlarging pixel art images without reducing sharpness. |
| |
| @section swapuv |
| Swap U & V plane. |
| |
| @section thumbnail |
| Select the most representative frame in a given sequence of consecutive frames. |
| |
| It accepts as argument the frames batch size to analyze (default @var{N}=100); |
| in a set of @var{N} frames, the filter will pick one of them, and then handle |
| the next batch of @var{N} frames until the end. |
| |
| Since the filter keeps track of the whole frames sequence, a bigger @var{N} |
| value will result in a higher memory usage, so a high value is not recommended. |
| |
| The following example extract one picture each 50 frames: |
| @example |
| thumbnail=50 |
| @end example |
| |
| Complete example of a thumbnail creation with @command{ffmpeg}: |
| @example |
| ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png |
| @end example |
| |
| @section tile |
| |
| Tile several successive frames together. |
| |
| It accepts as argument the tile size (i.e. the number of lines and columns) |
| in the form "@var{w}x@var{h}". |
| |
| For example, produce 8×8 PNG tiles of all keyframes (@option{-skip_frame |
| nokey}) in a movie: |
| @example |
| ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png |
| @end example |
| The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from |
| duplicating each output frame to accomodate the originally detected frame |
| rate. |
| |
| @section tinterlace |
| |
| Perform various types of temporal field interlacing. |
| |
| Frames are counted starting from 1, so the first input frame is |
| considered odd. |
| |
| This filter accepts a single parameter specifying the mode. Available |
| modes are: |
| |
| @table @samp |
| @item merge, 0 |
| Move odd frames into the upper field, even into the lower field, |
| generating a double height frame at half framerate. |
| |
| @item drop_odd, 1 |
| Only output even frames, odd frames are dropped, generating a frame with |
| unchanged height at half framerate. |
| |
| @item drop_even, 2 |
| Only output odd frames, even frames are dropped, generating a frame with |
| unchanged height at half framerate. |
| |
| @item pad, 3 |
| Expand each frame to full height, but pad alternate lines with black, |
| generating a frame with double height at the same input framerate. |
| |
| @item interleave_top, 4 |
| Interleave the upper field from odd frames with the lower field from |
| even frames, generating a frame with unchanged height at half framerate. |
| |
| @item interleave_bottom, 5 |
| Interleave the lower field from odd frames with the upper field from |
| even frames, generating a frame with unchanged height at half framerate. |
| |
| @item interlacex2, 6 |
| Double frame rate with unchanged height. Frames are inserted each |
| containing the second temporal field from the previous input frame and |
| the first temporal field from the next input frame. This mode relies on |
| the top_field_first flag. Useful for interlaced video displays with no |
| field synchronisation. |
| @end table |
| |
| Numeric values are deprecated but are accepted for backward |
| compatibility reasons. |
| |
| Default mode is @code{merge}. |
| |
| @section transpose |
| |
| Transpose rows with columns in the input video and optionally flip it. |
| |
| It accepts a parameter representing an integer, which can assume the |
| values: |
| |
| @table @samp |
| @item 0 |
| Rotate by 90 degrees counterclockwise and vertically flip (default), that is: |
| @example |
| L.R L.l |
| . . -> . . |
| l.r R.r |
| @end example |
| |
| @item 1 |
| Rotate by 90 degrees clockwise, that is: |
| @example |
| L.R l.L |
| . . -> . . |
| l.r r.R |
| @end example |
| |
| @item 2 |
| Rotate by 90 degrees counterclockwise, that is: |
| @example |
| L.R R.r |
| . . -> . . |
| l.r L.l |
| @end example |
| |
| @item 3 |
| Rotate by 90 degrees clockwise and vertically flip, that is: |
| @example |
| L.R r.R |
| . . -> . . |
| l.r l.L |
| @end example |
| @end table |
| |
| @section unsharp |
| |
| Sharpen or blur the input video. |
| |
| It accepts the following parameters: |
| @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount} |
| |
| Negative values for the amount will blur the input video, while positive |
| values will sharpen. All parameters are optional and default to the |
| equivalent of the string '5:5:1.0:5:5:0.0'. |
| |
| @table @option |
| |
| @item luma_msize_x |
| Set the luma matrix horizontal size. It can be an integer between 3 |
| and 13, default value is 5. |
| |
| @item luma_msize_y |
| Set the luma matrix vertical size. It can be an integer between 3 |
| and 13, default value is 5. |
| |
| @item luma_amount |
| Set the luma effect strength. It can be a float number between -2.0 |
| and 5.0, default value is 1.0. |
| |
| @item chroma_msize_x |
| Set the chroma matrix horizontal size. It can be an integer between 3 |
| and 13, default value is 5. |
| |
| @item chroma_msize_y |
| Set the chroma matrix vertical size. It can be an integer between 3 |
| and 13, default value is 5. |
| |
| @item chroma_amount |
| Set the chroma effect strength. It can be a float number between -2.0 |
| and 5.0, default value is 0.0. |
| |
| @end table |
| |
| @example |
| # Strong luma sharpen effect parameters |
| unsharp=7:7:2.5 |
| |
| # Strong blur of both luma and chroma parameters |
| unsharp=7:7:-2:7:7:-2 |
| |
| # Use the default values with @command{ffmpeg} |
| ffmpeg -i in.avi -vf "unsharp" out.mp4 |
| @end example |
| |
| @section vflip |
| |
| Flip the input video vertically. |
| |
| @example |
| ffmpeg -i in.avi -vf "vflip" out.avi |
| @end example |
| |
| @section yadif |
| |
| Deinterlace the input video ("yadif" means "yet another deinterlacing |
| filter"). |
| |
| It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}. |
| |
| @var{mode} specifies the interlacing mode to adopt, accepts one of the |
| following values: |
| |
| @table @option |
| @item 0 |
| output 1 frame for each frame |
| @item 1 |
| output 1 frame for each field |
| @item 2 |
| like 0 but skips spatial interlacing check |
| @item 3 |
| like 1 but skips spatial interlacing check |
| @end table |
| |
| Default value is 0. |
| |
| @var{parity} specifies the picture field parity assumed for the input |
| interlaced video, accepts one of the following values: |
| |
| @table @option |
| @item 0 |
| assume top field first |
| @item 1 |
| assume bottom field first |
| @item -1 |
| enable automatic detection |
| @end table |
| |
| Default value is -1. |
| If interlacing is unknown or decoder does not export this information, |
| top field first will be assumed. |
| |
| @var{auto} specifies if deinterlacer should trust the interlaced flag |
| and only deinterlace frames marked as interlaced |
| |
| @table @option |
| @item 0 |
| deinterlace all frames |
| @item 1 |
| only deinterlace frames marked as interlaced |
| @end table |
| |
| Default value is 0. |
| |
| @c man end VIDEO FILTERS |
| |
| @chapter Video Sources |
| @c man begin VIDEO SOURCES |
| |
| Below is a description of the currently available video sources. |
| |
| @section buffer |
| |
| Buffer video frames, and make them available to the filter chain. |
| |
| This source is mainly intended for a programmatic use, in particular |
| through the interface defined in @file{libavfilter/vsrc_buffer.h}. |
| |
| It accepts the following parameters: |
| @var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}:@var{sample_aspect_ratio_num}:@var{sample_aspect_ratio.den}:@var{scale_params} |
| |
| All the parameters but @var{scale_params} need to be explicitly |
| defined. |
| |
| Follows the list of the accepted parameters. |
| |
| @table @option |
| |
| @item width, height |
| Specify the width and height of the buffered video frames. |
| |
| @item pix_fmt_string |
| A string representing the pixel format of the buffered video frames. |
| It may be a number corresponding to a pixel format, or a pixel format |
| name. |
| |
| @item timebase_num, timebase_den |
| Specify numerator and denomitor of the timebase assumed by the |
| timestamps of the buffered frames. |
| |
| @item sample_aspect_ratio.num, sample_aspect_ratio.den |
| Specify numerator and denominator of the sample aspect ratio assumed |
| by the video frames. |
| |
| @item scale_params |
| Specify the optional parameters to be used for the scale filter which |
| is automatically inserted when an input change is detected in the |
| input size or format. |
| @end table |
| |
| For example: |
| @example |
| buffer=320:240:yuv410p:1:24:1:1 |
| @end example |
| |
| will instruct the source to accept video frames with size 320x240 and |
| with format "yuv410p", assuming 1/24 as the timestamps timebase and |
| square pixels (1:1 sample aspect ratio). |
| Since the pixel format with name "yuv410p" corresponds to the number 6 |
| (check the enum PixelFormat definition in @file{libavutil/pixfmt.h}), |
| this example corresponds to: |
| @example |
| buffer=320:240:6:1:24:1:1 |
| @end example |
| |
| @section cellauto |
| |
| Create a pattern generated by an elementary cellular automaton. |
| |
| The initial state of the cellular automaton can be defined through the |
| @option{filename}, and @option{pattern} options. If such options are |
| not specified an initial state is created randomly. |
| |
| At each new frame a new row in the video is filled with the result of |
| the cellular automaton next generation. The behavior when the whole |
| frame is filled is defined by the @option{scroll} option. |
| |
| This source accepts a list of options in the form of |
| @var{key}=@var{value} pairs separated by ":". A description of the |
| accepted options follows. |
| |
| @table @option |
| @item filename, f |
| Read the initial cellular automaton state, i.e. the starting row, from |
| the specified file. |
| In the file, each non-whitespace character is considered an alive |
| cell, a newline will terminate the row, and further characters in the |
| file will be ignored. |
| |
| @item pattern, p |
| Read the initial cellular automaton state, i.e. the starting row, from |
| the specified string. |
| |
| Each non-whitespace character in the string is considered an alive |
| cell, a newline will terminate the row, and further characters in the |
| string will be ignored. |
| |
| @item rate, r |
| Set the video rate, that is the number of frames generated per second. |
| Default is 25. |
| |
| @item random_fill_ratio, ratio |
| Set the random fill ratio for the initial cellular automaton row. It |
| is a floating point number value ranging from 0 to 1, defaults to |
| 1/PHI. |
| |
| This option is ignored when a file or a pattern is specified. |
| |
| @item random_seed, seed |
| Set the seed for filling randomly the initial row, must be an integer |
| included between 0 and UINT32_MAX. If not specified, or if explicitly |
| set to -1, the filter will try to use a good random seed on a best |
| effort basis. |
| |
| @item rule |
| Set the cellular automaton rule, it is a number ranging from 0 to 255. |
| Default value is 110. |
| |
| @item size, s |
| Set the size of the output video. |
| |
| If @option{filename} or @option{pattern} is specified, the size is set |
| by default to the width of the specified initial state row, and the |
| height is set to @var{width} * PHI. |
| |
| If @option{size} is set, it must contain the width of the specified |
| pattern string, and the specified pattern will be centered in the |
| larger row. |
| |
| If a filename or a pattern string is not specified, the size value |
| defaults to "320x518" (used for a randomly generated initial state). |
| |
| @item scroll |
| If set to 1, scroll the output upward when all the rows in the output |
| have been already filled. If set to 0, the new generated row will be |
| written over the top row just after the bottom row is filled. |
| Defaults to 1. |
| |
| @item start_full, full |
| If set to 1, completely fill the output with generated rows before |
| outputting the first frame. |
| This is the default behavior, for disabling set the value to 0. |
| |
| @item stitch |
| If set to 1, stitch the left and right row edges together. |
| This is the default behavior, for disabling set the value to 0. |
| @end table |
| |
| @subsection Examples |
| |
| @itemize |
| @item |
| Read the initial state from @file{pattern}, and specify an output of |
| size 200x400. |
| @example |
| cellauto=f=pattern:s=200x400 |
| @end example |
| |
| @item |
| Generate a random initial row with a width of 200 cells, with a fill |
| ratio of 2/3: |
| @example |
| cellauto=ratio=2/3:s=200x200 |
| @end example |
| |
| @item |
| Create a pattern generated by rule 18 starting by a single alive cell |
| centered on an initial row with width 100: |
| @example |
| cellauto=p=@@:s=100x400:full=0:rule=18 |
| @end example |
| |
| @item |
| Specify a more elaborated initial pattern: |
| @example |
| cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18 |
| @end example |
| |
| @end itemize |
| |
| @section color |
| |
| Provide an uniformly colored input. |
| |
| It accepts the following parameters: |
| @var{color}:@var{frame_size}:@var{frame_rate} |
| |
| Follows the description of the accepted parameters. |
| |
| @table @option |
| |
| @item color |
| Specify the color of the source. It can be the name of a color (case |
| insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an |
| alpha specifier. The default value is "black". |
| |
| @item frame_size |
| Specify the size of the sourced video, it may be a string of the form |
| @var{width}x@var{height}, or the name of a size abbreviation. The |
| default value is "320x240". |
| |
| @item frame_rate |
| Specify the frame rate of the sourced video, as the number of frames |
| generated per second. It has to be a string in the format |
| @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float |
| number or a valid video frame rate abbreviation. The default value is |
| "25". |
| |
| @end table |
| |
| For example the following graph description will generate a red source |
| with an opacity of 0.2, with size "qcif" and a frame rate of 10 |
| frames per second, which will be overlayed over the source connected |
| to the pad with identifier "in". |
| |
| @example |
| "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]" |
| @end example |
| |
| @section movie |
| |
| Read a video stream from a movie container. |
| |
| It accepts the syntax: @var{movie_name}[:@var{options}] where |
| @var{movie_name} is the name of the resource to read (not necessarily |
| a file but also a device or a stream accessed through some protocol), |
| and @var{options} is an optional sequence of @var{key}=@var{value} |
| pairs, separated by ":". |
| |
| The description of the accepted options follows. |
| |
| @table @option |
| |
| @item format_name, f |
| Specifies the format assumed for the movie to read, and can be either |
| the name of a container or an input device. If not specified the |
| format is guessed from @var{movie_name} or by probing. |
| |
| @item seek_point, sp |
| Specifies the seek point in seconds, the frames will be output |
| starting from this seek point, the parameter is evaluated with |
| @code{av_strtod} so the numerical value may be suffixed by an IS |
| postfix. Default value is "0". |
| |
| @item stream_index, si |
| Specifies the index of the video stream to read. If the value is -1, |
| the best suited video stream will be automatically selected. Default |
| value is "-1". |
| |
| @item loop |
| Specifies how many times to read the video stream in sequence. |
| If the value is less than 1, the stream will be read again and again. |
| Default value is "1". |
| |
| Note that when the movie is looped the source timestamps are not |
| changed, so it will generate non monotonically increasing timestamps. |
| @end table |
| |
| This filter allows to overlay a second video on top of main input of |
| a filtergraph as shown in this graph: |
| @example |
| input -----------> deltapts0 --> overlay --> output |
| ^ |
| | |
| movie --> scale--> deltapts1 -------+ |
| @end example |
| |
| Some examples follow: |
| @example |
| # skip 3.2 seconds from the start of the avi file in.avi, and overlay it |
| # on top of the input labelled as "in". |
| movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie]; |
| [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out] |
| |
| # read from a video4linux2 device, and overlay it on top of the input |
| # labelled as "in" |
| movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie]; |
| [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out] |
| |
| @end example |
| |
| @section mptestsrc |
| |
| Generate various test patterns, as generated by the MPlayer test filter. |
| |
| The size of the generated video is fixed, and is 256x256. |
| This source is useful in particular for testing encoding features. |
| |
| This source accepts an optional sequence of @var{key}=@var{value} pairs, |
| separated by ":". The description of the accepted options follows. |
| |
| @table @option |
| |
| @item rate, r |
| Specify the frame rate of the sourced video, as the number of frames |
| generated per second. It has to be a string in the format |
| @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float |
| number or a valid video frame rate abbreviation. The default value is |
| "25". |
| |
| @item duration, d |
| Set the video duration of the sourced video. The accepted syntax is: |
| @example |
| [-]HH:MM:SS[.m...] |
| [-]S+[.m...] |
| @end example |
| See also the function @code{av_parse_time()}. |
| |
| If not specified, or the expressed duration is negative, the video is |
| supposed to be generated forever. |
| |
| @item test, t |
| |
| Set the number or the name of the test to perform. Supported tests are: |
| @table @option |
| @item dc_luma |
| @item dc_chroma |
| @item freq_luma |
| @item freq_chroma |
| @item amp_luma |
| @item amp_chroma |
| @item cbp |
| @item mv |
| @item ring1 |
| @item ring2 |
| @item all |
| @end table |
| |
| Default value is "all", which will cycle through the list of all tests. |
| @end table |
| |
| For example the following: |
| @example |
| testsrc=t=dc_luma |
| @end example |
| |
| will generate a "dc_luma" test pattern. |
| |
| @section frei0r_src |
| |
| Provide a frei0r source. |
| |
| To enable compilation of this filter you need to install the frei0r |
| header and configure FFmpeg with @code{--enable-frei0r}. |
| |
| The source supports the syntax: |
| @example |
| @var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}] |
| @end example |
| |
| @var{size} is the size of the video to generate, may be a string of the |
| form @var{width}x@var{height} or a frame size abbreviation. |
| @var{rate} is the rate of the video to generate, may be a string of |
| the form @var{num}/@var{den} or a frame rate abbreviation. |
| @var{src_name} is the name to the frei0r source to load. For more |
| information regarding frei0r and how to set the parameters read the |
| section @ref{frei0r} in the description of the video filters. |
| |
| Some examples follow: |
| @example |
| # generate a frei0r partik0l source with size 200x200 and frame rate 10 |
| # which is overlayed on the overlay filter main input |
| frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay |
| @end example |
| |
| @section life |
| |
| Generate a life pattern. |
| |
| This source is based on a generalization of John Conway's life game. |
| |
| The sourced input represents a life grid, each pixel represents a cell |
| which can be in one of two possible states, alive or dead. Every cell |
| interacts with its eight neighbours, which are the cells that are |
| horizontally, vertically, or diagonally adjacent. |
| |
| At each interaction the grid evolves according to the adopted rule, |
| which specifies the number of neighbor alive cells which will make a |
| cell stay alive or born. The @option{rule} option allows to specify |
| the rule to adopt. |
| |
| This source accepts a list of options in the form of |
| @var{key}=@var{value} pairs separated by ":". A description of the |
| accepted options follows. |
| |
| @table @option |
| @item filename, f |
| Set the file from which to read the initial grid state. In the file, |
| each non-whitespace character is considered an alive cell, and newline |
| is used to delimit the end of each row. |
| |
| If this option is not specified, the initial grid is generated |
| randomly. |
| |
| @item rate, r |
| Set the video rate, that is the number of frames generated per second. |
| Default is 25. |
| |
| @item random_fill_ratio, ratio |
| Set the random fill ratio for the initial random grid. It is a |
| floating point number value ranging from 0 to 1, defaults to 1/PHI. |
| It is ignored when a file is specified. |
| |
| @item random_seed, seed |
| Set the seed for filling the initial random grid, must be an integer |
| included between 0 and UINT32_MAX. If not specified, or if explicitly |
| set to -1, the filter will try to use a good random seed on a best |
| effort basis. |
| |
| @item rule |
| Set the life rule. |
| |
| A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}", |
| where @var{NS} and @var{NB} are sequences of numbers in the range 0-8, |
| @var{NS} specifies the number of alive neighbor cells which make a |
| live cell stay alive, and @var{NB} the number of alive neighbor cells |
| which make a dead cell to become alive (i.e. to "born"). |
| "s" and "b" can be used in place of "S" and "B", respectively. |
| |
| Alternatively a rule can be specified by an 18-bits integer. The 9 |
| high order bits are used to encode the next cell state if it is alive |
| for each number of neighbor alive cells, the low order bits specify |
| the rule for "borning" new cells. Higher order bits encode for an |
| higher number of neighbor cells. |
| For example the number 6153 = @code{(12<<9)+9} specifies a stay alive |
| rule of 12 and a born rule of 9, which corresponds to "S23/B03". |
| |
| Default value is "S23/B3", which is the original Conway's game of life |
| rule, and will keep a cell alive if it has 2 or 3 neighbor alive |
| cells, and will born a new cell if there are three alive cells around |
| a dead cell. |
| |
| @item size, s |
| Set the size of the output video. |
| |
| If @option{filename} is specified, the size is set by default to the |
| same size of the input file. If @option{size} is set, it must contain |
| the size specified in the input file, and the initial grid defined in |
| that file is centered in the larger resulting area. |
| |
| If a filename is not specified, the size value defaults to "320x240" |
| (used for a randomly generated initial grid). |
| |
| @item stitch |
| If set to 1, stitch the left and right grid edges together, and the |
| top and bottom edges also. Defaults to 1. |
| |
| @item mold |
| Set cell mold speed. If set, a dead cell will go from @option{death_color} to |
| @option{mold_color} with a step of @option{mold}. @option{mold} can have a |
| value from 0 to 255. |
| |
| @item life_color |
| Set the color of living (or new born) cells. |
| |
| @item death_color |
| Set the color of dead cells. If @option{mold} is set, this is the first color |
| used to represent a dead cell. |
| |
| @item mold_color |
| Set mold color, for definitely dead and moldy cells. |
| @end table |
| |
| @subsection Examples |
| |
| @itemize |
| @item |
| Read a grid from @file{pattern}, and center it on a grid of size |
| 300x300 pixels: |
| @example |
| life=f=pattern:s=300x300 |
| @end example |
| |
| @item |
| Generate a random grid of size 200x200, with a fill ratio of 2/3: |
| @example |
| life=ratio=2/3:s=200x200 |
| @end example |
| |
| @item |
| Specify a custom rule for evolving a randomly generated grid: |
| @example |
| life=rule=S14/B34 |
| @end example |
| |
| @item |
| Full example with slow death effect (mold) using @command{ffplay}: |
| @example |
| ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16 |
| @end example |
| @end itemize |
| |
| @section nullsrc, rgbtestsrc, testsrc |
| |
| The @code{nullsrc} source returns unprocessed video frames. It is |
| mainly useful to be employed in analysis / debugging tools, or as the |
| source for filters which ignore the input data. |
| |
| The @code{rgbtestsrc} source generates an RGB test pattern useful for |
| detecting RGB vs BGR issues. You should see a red, green and blue |
| stripe from top to bottom. |
| |
| The @code{testsrc} source generates a test video pattern, showing a |
| color pattern, a scrolling gradient and a timestamp. This is mainly |
| intended for testing purposes. |
| |
| These sources accept an optional sequence of @var{key}=@var{value} pairs, |
| separated by ":". The description of the accepted options follows. |
| |
| @table @option |
| |
| @item size, s |
| Specify the size of the sourced video, it may be a string of the form |
| @var{width}x@var{height}, or the name of a size abbreviation. The |
| default value is "320x240". |
| |
| @item rate, r |
| Specify the frame rate of the sourced video, as the number of frames |
| generated per second. It has to be a string in the format |
| @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float |
| number or a valid video frame rate abbreviation. The default value is |
| "25". |
| |
| @item sar |
| Set the sample aspect ratio of the sourced video. |
| |
| @item duration, d |
| Set the video duration of the sourced video. The accepted syntax is: |
| @example |
| [-]HH[:MM[:SS[.m...]]] |
| [-]S+[.m...] |
| @end example |
| See also the function @code{av_parse_time()}. |
| |
| If not specified, or the expressed duration is negative, the video is |
| supposed to be generated forever. |
| |
| @item decimals, n |
| Set the number of decimals to show in the timestamp, only used in the |
| @code{testsrc} source. |
| |
| The displayed timestamp value will correspond to the original |
| timestamp value multiplied by the power of 10 of the specified |
| value. Default value is 0. |
| @end table |
| |
| For example the following: |
| @example |
| testsrc=duration=5.3:size=qcif:rate=10 |
| @end example |
| |
| will generate a video with a duration of 5.3 seconds, with size |
| 176x144 and a frame rate of 10 frames per second. |
| |
| If the input content is to be ignored, @code{nullsrc} can be used. The |
| following command generates noise in the luminance plane by employing |
| the @code{mp=geq} filter: |
| @example |
| nullsrc=s=256x256, mp=geq=random(1)*255:128:128 |
| @end example |
| |
| @c man end VIDEO SOURCES |
| |
| @chapter Video Sinks |
| @c man begin VIDEO SINKS |
| |
| Below is a description of the currently available video sinks. |
| |
| @section buffersink |
| |
| Buffer video frames, and make them available to the end of the filter |
| graph. |
| |
| This sink is mainly intended for a programmatic use, in particular |
| through the interface defined in @file{libavfilter/buffersink.h}. |
| |
| It does not require a string parameter in input, but you need to |
| specify a pointer to a list of supported pixel formats terminated by |
| -1 in the opaque parameter provided to @code{avfilter_init_filter} |
| when initializing this sink. |
| |
| @section nullsink |
| |
| Null video sink, do absolutely nothing with the input video. It is |
| mainly useful as a template and to be employed in analysis / debugging |
| tools. |
| |
| @c man end VIDEO SINKS |