diff options
Diffstat (limited to 'doc/filters.texi')
| -rw-r--r-- | doc/filters.texi | 887 |
1 files changed, 781 insertions, 106 deletions
diff --git a/doc/filters.texi b/doc/filters.texi index 520a6cb..0da5702 100644 --- a/doc/filters.texi +++ b/doc/filters.texi @@ -18,8 +18,8 @@ output pads is called a "sink". A filtergraph can be represented using a textual representation, which is recognized by the @code{-vf} and @code{-af} options of the ff* -tools, and by the @code{av_parse_graph()} function defined in -@file{libavfilter/avfiltergraph}. +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,138 @@ 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/chlayout.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 meanigless (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 + @c man end AUDIO FILTERS @chapter Audio Sources @@ -110,31 +231,202 @@ 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 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 frequence 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 an optional sequence of @var{key}=@var{value} pairs, +separated by ":". + +The description of the accepted options follows. + +@table @option -It accepts as optional parameter a string of the form -@var{sample_rate}:@var{channel_layout}. +@item sample_rate, s +Specify the sample rate, and defaults to 44100. -@var{sample_rate} specify the sample rate, and defaults to 44100. +@item channel_layout, cl -@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. +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 +436,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,7 +458,7 @@ 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. @@ -188,7 +491,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 +558,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 +574,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 +745,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 sarch 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,10 +885,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. +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. +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. @@ -574,28 +959,117 @@ 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 heigth + +@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 +@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/}. @@ -698,7 +1172,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 @@ -828,10 +1302,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 @@ -840,28 +1318,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 heigth @@ -907,7 +1389,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" @@ -925,6 +1407,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. @@ -932,6 +1505,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. @@ -957,7 +1532,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}. @@ -1056,10 +1631,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 @@ -1076,6 +1651,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 +colorspace. 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 @@ -1119,10 +1705,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 @@ -1141,7 +1723,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 @@ -1201,6 +1789,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" @@ -1220,16 +1814,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 @@ -1242,8 +1832,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 @@ -1266,6 +1862,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. @@ -1306,15 +1913,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 @@ -1453,15 +2051,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. @@ -1534,7 +2123,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". @@ -1610,11 +2199,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 @@ -1632,6 +2221,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. @@ -1706,7 +2310,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. @@ -1770,7 +2374,7 @@ 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 +@var{auto} specifies if deinterlacer should trust the interlaced flag and only deinterlace frames marked as interlaced @table @option @@ -1797,9 +2401,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 explicitely defined. +All the parameters but @var{scale_params} need to be explicitely +defined. Follows the list of the accepted parameters. @@ -1820,6 +2425,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: @@ -1834,7 +2444,7 @@ 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 color @@ -1931,28 +2541,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. -Null video source, never return images. It is mainly useful as a -template and to be employed in analysis / debugging tools. +@item test, t -It accepts as optional parameter a string of the form -@var{width}:@var{height}:@var{timebase}. +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 -@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). +Default value is "all", which will cycle through the list of all tests. +@end table -@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". +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 Libav with --enable-frei0r. +header and configure FFmpeg with --enable-frei0r. The source supports the syntax: @example @@ -1974,7 +2625,11 @@ Some examples follow: frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay @end example -@section rgbtestsrc, testsrc +@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 @@ -1984,7 +2639,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 @@ -2024,6 +2679,13 @@ testsrc=duration=5.3:size=qcif:rate=10 will generate a video with a duration of 5.3 seconds, with size 176x144 and a framerate 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 @@ -2031,6 +2693,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 |
