diff options
Diffstat (limited to 'doc/filters.texi')
| -rw-r--r-- | doc/filters.texi | 1339 |
1 files changed, 1197 insertions, 142 deletions
diff --git a/doc/filters.texi b/doc/filters.texi index e022b46531..699e0c1b97 100644 --- a/doc/filters.texi +++ b/doc/filters.texi @@ -17,9 +17,9 @@ output pads is called a "sink". @section Filtergraph syntax A filtergraph can be represented using a textual representation, which -is recognized by the @code{-vf} and @code{-af} options in @command{avconv} -and @command{avplay}, and by the @code{av_parse_graph()} function defined in -@file{libavfilter/avfiltergraph}. +is recognized by the @code{-vf} option of the ff* +tools, and by the @code{avfilter_graph_parse()} 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 @@ -92,17 +92,247 @@ Follows a BNF description for the filtergraph syntax: @chapter Audio Filters @c man begin AUDIO FILTERS -When you configure your Libav build, you can disable any of the +When you configure your FFmpeg build, you can disable any of the existing filters using --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{packing_format}". + +@var{sample_format} specifies the sample format, and can be a string or +the corresponding numeric value defined in @file{libavutil/samplefmt.h}. + +@var{channel_layout} specifies the channel layout, and can be a string +or the corresponding number value defined in @file{libavutil/audioconvert.h}. + +@var{packing_format} specifies the type of packing in output, can be one +of "planar" or "packed", or the corresponding numeric values "0" or "1". + +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 unsigned 8-bit, stereo, packed: +@example +aconvert=u8:stereo:packed +@end example + +@item +Convert input to unsigned 8-bit, automatically select out channel layout +and packing format: +@example +aconvert=u8:auto: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 three lists of formats, separated by ":", in the form: +"@var{sample_formats}:@var{channel_layouts}:@var{packing_formats}". + +Elements in each list are separated by "," which has to be escaped in the +filtergraph specification. + +The special parameter "all", in place of a list of elements, signifies all +supported formats. + +Some examples follow: +@example +aformat=u8\\,s16:mono:packed + +aformat=s16:mono\\,stereo:all +@end example + @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 planar +if the packing format is planar, 0 if packed + +@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 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. + +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. + +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 @file{ffmpeg} integrates a default down-mix (and up-mix) system +that should be preferred (see "-ac" option) unless you have very specific +needs. + +@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, and 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 + @c man end AUDIO FILTERS @chapter Audio Sources @@ -110,31 +340,212 @@ Pass the audio source unchanged to the output. 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}:@var{packing} + +@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} + +@item packing +Either "packed" or "planar", or their integer representation: 0 or 1 +respectively. + +@end table + +For example: +@example +abuffer=44100:s16:stereo:planar +@end example + +will instruct the source to accept planar 16bit signed stereo at 44100Hz. +Since the sample format with name "s16" corresponds to the number +1 and the "stereo" channel layout corresponds to the value 3, this is +equivalent to: +@example +abuffer=44100:1:3:1 +@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. The output channel layout depends on the number of +provided expressions, up to 8 channels are supported. + +@var{options} is an optional sequence of @var{key}=@var{value} pairs, +separated by ":". + +The description of the accepted options follows. + +@table @option + +@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 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, never return audio frames. It is mainly useful as a -template and to be employed in analysis / debugging tools. +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 as optional parameter a string of the form -@var{sample_rate}:@var{channel_layout}. +It accepts an optional sequence of @var{key}=@var{value} pairs, +separated by ":". + +The description of the accepted options follows. -@var{sample_rate} specify the sample rate, and defaults to 44100. +@table @option -@var{channel_layout} 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 3, which corresponds to CH_LAYOUT_STEREO. +@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 CH_LAYOUT_MONO. -anullsrc=48000:4 +# set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. +anullsrc=r=48000:cl=4 # same as -anullsrc=48000:mono +anullsrc=r=48000:cl=mono @end example @c man end AUDIO SOURCES @@ -144,6 +555,17 @@ anullsrc=48000:mono 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 @@ -155,13 +577,29 @@ tools. @chapter Video Filters @c man begin VIDEO FILTERS -When you configure your Libav build, you can disable any of the +When you configure your FFmpeg build, you can disable any of the existing filters using --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 in input the name of the ass file to render. + +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 blackframe Detect frames that are (almost) completely black. Can be useful to @@ -188,7 +626,7 @@ considered black, and defaults to 32. Apply boxblur algorithm to the input video. This filter accepts the parameters: -@var{luma_power}:@var{luma_radius}:@var{chroma_radius}:@var{chroma_power}:@var{alpha_radius}:@var{alpha_power} +@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 @@ -255,10 +693,6 @@ Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}. The parameters are expressions containing the following constants: @table @option -@item E, PI, PHI -the corresponding mathematical approximated values for e -(euler number), pi (greek PI), PHI (golden ratio) - @item x, y the computed values for @var{x} and @var{y}. They are evaluated for each new frame. @@ -275,6 +709,19 @@ 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 @@ -433,6 +880,76 @@ delogo=x=0:y=0:w=100:h=77:band=10 @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. @@ -503,36 +1020,13 @@ parameter @var{text}. If both text and textfile are specified, an error is thrown. @item x, y -The offsets where text will be drawn within the video frame. -Relative to the top/left border of the output image. -They accept expressions similar to the @ref{overlay} filter: -@table @option +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. -@item x, y -the computed values for @var{x} and @var{y}. They are evaluated for -each new frame. +The default value of @var{x} and @var{y} is "0". -@item main_w, main_h -main input width and height - -@item W, H -same as @var{main_w} and @var{main_h} - -@item text_w, text_h -rendered text width and height - -@item w, h -same as @var{text_w} and @var{text_h} - -@item n -the number of frames processed, starting from 0 - -@item t -timestamp expressed in seconds, NAN if the input timestamp is unknown - -@end table - -The default value of @var{x} and @var{y} is 0. +See below for the list of accepted constants. @item fontsize The font size to be used for drawing text. @@ -600,28 +1094,124 @@ The size in number of spaces to use for rendering the tab. Default value is 4. @end table -For example the command: +The parameters for @var{x} and @var{y} are expressions containing the +following constants: + +@table @option +@item W, H +the input width and height + +@item tw, text_w +the width of the rendered text + +@item th, text_h +the height of the rendered text + +@item lh, line_h +the height of each text line + +@item sar +input sample aspect ratio + +@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 max_glyph_w +maximum glyph width, that is the maximum width for all the glyphs +contained in the rendered text + +@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_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 n +the number of input frame, starting from 0 + +@item t +timestamp expressed in seconds, NAN if the input timestamp is unknown + +@item timecode +initial timecode representation in "hh:mm:ss[:;.]ff" format. It can be used +with or without text parameter. @var{rate} option must be specified + +@item r, rate +frame rate (timecode only) +@end table + +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 -will draw "Test Text" with font FreeSerif, using the default values -for the optional parameters. +@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%. -The command: @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 -will 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%. - 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 + +@end itemize + For more information about libfreetype, check: @url{http://www.freetype.org/}. @@ -630,7 +1220,7 @@ For more information about libfreetype, check: Apply fade-in/out effect to input video. It accepts the parameters: -@var{type}:@var{start_frame}:@var{nb_frames} +@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. @@ -643,6 +1233,25 @@ 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 @@ -656,6 +1265,9 @@ 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 @@ -688,7 +1300,7 @@ which is bottom field first. For example: @example -./avconv -i in.vob -vf "fieldorder=bff" out.dv +ffmpeg -i in.vob -vf "fieldorder=bff" out.dv @end example @section fifo @@ -724,7 +1336,7 @@ format=yuv420p:yuv444p:yuv410p Apply a frei0r effect to the input video. To enable compilation of this filter you need to install the frei0r -header and configure Libav with --enable-frei0r. +header and configure FFmpeg with --enable-frei0r. The filter supports the syntax: @example @@ -772,7 +1384,7 @@ For more information see: @section gradfun Fix the banding artifacts that are sometimes introduced into nearly flat -regions by truncation to 8bit colordepth. +regions by truncation to 8bit color depth. Interpolate the gradients that should go where the bands are, and dither them. @@ -806,9 +1418,9 @@ gradfun=1.2 Flip the input video horizontally. -For example to horizontally flip the input video with @command{avconv}: +For example to horizontally flip the input video with @command{ffmpeg}: @example -avconv -i in.avi -vf "hflip" out.avi +ffmpeg -i in.avi -vf "hflip" out.avi @end example @section hqdn3d @@ -853,10 +1465,14 @@ corresponding pixel component values. The @var{lut} filter requires either YUV or RGB pixel formats in input, and accepts the options: @table @option -@var{c0} (first pixel component) -@var{c1} (second pixel component) -@var{c2} (third pixel component) -@var{c3} (fourth pixel component, corresponds to the alpha component) +@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 @@ -865,28 +1481,32 @@ input. The @var{lutrgb} filter requires RGB pixel formats in input, and accepts the options: @table @option -@var{r} (red component) -@var{g} (green component) -@var{b} (blue component) -@var{a} (alpha component) +@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 -@var{y} (Y/luminance component) -@var{u} (U/Cb component) -@var{v} (V/Cr component) -@var{a} (alpha component) +@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 E, PI, PHI -the corresponding mathematical approximated values for e -(euler number), pi (greek PI), PHI (golden ratio) - @item w, h the input width and height @@ -932,7 +1552,7 @@ lutrgb="r=negval:g=negval:b=negval" lutyuv="y=negval:u=negval:v=negval" # negate luminance -lutyuv=negval +lutyuv=y=negval # remove chroma components, turns the video into a graytone image lutyuv="u=128:v=128" @@ -950,6 +1570,97 @@ format=rgba,lutrgb=a="maxval-minval/2" 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 2xsai +@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 mirror +@item noise +@item ow +@item palette +@item perspective +@item phase +@item pp7 +@item pullup +@item qp +@item rectangle +@item remove-logo +@item rotate +@item sab +@item screenshot +@item smartblur +@item softpulldown +@item softskip +@item spp +@item swapuv +@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 +# remove a logo by interpolating the surrounding pixels +mp=delogo=200:200:80:20:1 + +# 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. @@ -957,6 +1668,8 @@ 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. @@ -982,7 +1695,7 @@ Pass the video source unchanged to the output. Apply video transform using libopencv. To enable this filter install libopencv library and headers and -configure Libav with --enable-libopencv. +configure FFmpeg with --enable-libopencv. The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}. @@ -1082,10 +1795,10 @@ 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}. +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. The parameters are expressions containing +@var{y} is the y coordinate. @var{x} and @var{y} are expressions containing the following parameters: @table @option @@ -1102,6 +1815,17 @@ overlay input width and height 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 @@ -1145,10 +1869,6 @@ The parameters @var{width}, @var{height}, @var{x}, and @var{y} are expressions containing the following constants: @table @option -@item E, PI, PHI -the corresponding mathematical approximated values for e -(euler number), pi (greek PI), phi (golden ratio) - @item in_w, in_h the input video width and height @@ -1167,7 +1887,13 @@ x and y offsets as specified by the @var{x} and @var{y} expressions, or NAN if not yet specified @item a -input display aspect ratio, same as @var{iw} / @var{ih} +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 @@ -1227,6 +1953,12 @@ 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" @@ -1246,16 +1978,12 @@ can be used to test the monowhite pixel format descriptor definition. @section scale -Scale the input video to @var{width}:@var{height} and/or convert the image format. +Scale the input video to @var{width}:@var{height}[:@var{interl}=@{1|-1@}] and/or convert the image format. The parameters @var{width} and @var{height} are expressions containing the following constants: @table @option -@item E, PI, PHI -the corresponding mathematical approximated values for e -(euler number), pi (greek PI), phi (golden ratio) - @item in_w, in_h the input width and height @@ -1268,8 +1996,14 @@ the output (cropped) width and height @item ow, oh same as @var{out_w} and @var{out_h} -@item dar, a -input display aspect ratio, same as @var{iw} / @var{ih} +@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 sar input sample aspect ratio @@ -1292,6 +2026,17 @@ 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 + Some examples follow: @example # scale the input video to a size of 200x100. @@ -1332,15 +2077,6 @@ is selected and passed to the output, otherwise it is discarded. The expression can contain the following constants: @table @option -@item PI -Greek PI - -@item PHI -golden ratio - -@item E -Euler number - @item n the sequential number of the filtered frame, starting from 0 @@ -1479,15 +2215,6 @@ can contain the following constants: @item PTS the presentation timestamp in input -@item PI -Greek PI - -@item PHI -golden ratio - -@item E -Euler number - @item N the count of the input frame, starting from 0. @@ -1560,7 +2287,7 @@ 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 "PI", "E", "PHI", "AVTB" (the +The expression can contain the constants "AVTB" (the default timebase), and "intb" (the input timebase). The default value for the input is "intb". @@ -1636,11 +2363,11 @@ the @code{av_get_picture_type_char} function defined in @file{libavutil/avutil.h}. @item checksum -Adler-32 checksum of all the planes of the input frame +Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame @item plane_checksum -Adler-32 checksum of each plane of the input frame, expressed in the form -"[@var{c0} @var{c1} @var{c2} @var{c3}]" +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 @@ -1649,7 +2376,7 @@ Pass the images of input video on to next video filter as multiple slices. @example -./avconv -i in.avi -vf "slicify=32" out.avi +ffmpeg -i in.avi -vf "slicify=32" out.avi @end example The filter accepts the slice height as parameter. If the parameter is @@ -1658,6 +2385,21 @@ 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 + +Pass on the input video to two outputs. Both outputs are identical to +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 transpose Transpose rows with columns in the input video and optionally flip it. @@ -1732,7 +2474,7 @@ and 13, default value is 5. Set the chroma matrix vertical size. It can be an integer between 3 and 13, default value is 5. -@item luma_amount +@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. @@ -1745,8 +2487,8 @@ 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{avconv} -./avconv -i in.avi -vf "unsharp" out.mp4 +# Use the default values with @command{ffmpeg} +ffmpeg -i in.avi -vf "unsharp" out.mp4 @end example @section vflip @@ -1754,7 +2496,7 @@ unsharp=7:7:-2:7:7:-2 Flip the input video vertically. @example -./avconv -i in.avi -vf "vflip" out.avi +ffmpeg -i in.avi -vf "vflip" out.avi @end example @section yadif @@ -1823,9 +2565,10 @@ 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{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 need to be explicitly defined. +All the parameters but @var{scale_params} need to be explicitly +defined. Follows the list of the accepted parameters. @@ -1846,6 +2589,11 @@ 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: @@ -1860,9 +2608,124 @@ 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 +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. @@ -1957,28 +2820,69 @@ movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie]; @end example -@section nullsrc +@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 -Null video source, never return images. It is mainly useful as a -template and to be employed in analysis / debugging tools. +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 -It accepts as optional parameter a string of the form -@var{width}:@var{height}:@var{timebase}. +Default value is "all", which will cycle through the list of all tests. +@end table -@var{width} and @var{height} specify the size of the configured -source. The default values of @var{width} and @var{height} are -respectively 352 and 288 (corresponding to the CIF size format). +For example the following: +@example +testsrc=t=dc_luma +@end example -@var{timebase} specifies an arithmetic expression representing a -timebase. The expression can contain the constants "PI", "E", "PHI", -"AVTB" (the default timebase), and defaults to the value "AVTB". +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 Libav with --enable-frei0r. +header and configure FFmpeg with --enable-frei0r. The source supports the syntax: @example @@ -1995,12 +2899,143 @@ section @ref{frei0r} in the description of the video filters. Some examples follow: @example -# generate a frei0r partik0l source with size 200x200 and framerate 10 +# 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 rgbtestsrc, testsrc +@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 @@ -2010,7 +3045,7 @@ 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. -Both sources accept an optional sequence of @var{key}=@var{value} pairs, +These sources accept an optional sequence of @var{key}=@var{value} pairs, separated by ":". The description of the accepted options follows. @table @option @@ -2048,7 +3083,14 @@ 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 framerate of 10 frames per second. +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 @@ -2057,6 +3099,19 @@ will generate a video with a duration of 5.3 seconds, with size 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 |