X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Ffilters.texi;h=54c14174ea7a24294ac0721a3f1fbfdce4612514;hb=af52e6b6dd3486fea04c73c404ed2764d8e012fb;hp=ce7d064b004d717854cbc328a03d84d7df122267;hpb=ada49f936eaafe12365c7b962355d6dcfbfc4029;p=ffmpeg diff --git a/doc/filters.texi b/doc/filters.texi index ce7d064b004..54c14174ea7 100644 --- a/doc/filters.texi +++ b/doc/filters.texi @@ -99,6 +99,42 @@ 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 @@ -137,6 +173,56 @@ For example, to resample the input audio to 44100Hz: 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 of all the planes of the input frame + +@item plane_checksum +Adler-32 checksum 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 @@ -144,31 +230,122 @@ aresample=44100 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 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. + +@table @option + +@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 @@ -183,11 +360,11 @@ Below is a description of the currently available audio sinks. 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/asink_abuffer.h}. +through the interface defined in @file{libavfilter/buffersink.h}. -It requires a pointer to a ABufferSinkContext structure, which defines the -incoming buffers' format, to be passed as the opaque parameter to -@code{avfilter_init_filter} for initialization. +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 @@ -233,7 +410,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 @@ -309,13 +486,13 @@ 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 heigth +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 heigth +the output (cropped) width and height @item ow, oh same as @var{out_w} and @var{out_h} @@ -561,10 +738,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. @@ -632,28 +812,121 @@ 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 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 + +@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/}. @@ -886,10 +1159,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 @@ -898,19 +1175,27 @@ 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: @@ -965,7 +1250,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" @@ -1275,13 +1560,13 @@ 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 heigth +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 heigth, that is the size of the padded area as +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 @@ -1394,13 +1679,13 @@ the corresponding mathematical approximated values for e (euler number), pi (greek PI), phi (golden ratio) @item in_w, in_h -the input width and heigth +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 heigth +the output (cropped) width and height @item ow, oh same as @var{out_w} and @var{out_h} @@ -1414,6 +1699,9 @@ 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 + @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. @@ -1517,26 +1805,26 @@ the PTS of the first video frame in the video, NAN if undefined the time of the first video frame in the video, NAN if undefined @item pict_type -the picture type of the filtered frame, can assume one of the following +the type of the filtered frame, can assume one of the following values: @table @option -@item PICT_TYPE_I -@item PICT_TYPE_P -@item PICT_TYPE_B -@item PICT_TYPE_S -@item PICT_TYPE_SI -@item PICT_TYPE_SP -@item PICT_TYPE_BI +@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 INTERLACE_TYPE_P +@item PROGRESSIVE the frame is progressive (not interlaced) -@item INTERLACE_TYPE_T +@item TOPFIRST the frame is top-field-first -@item INTERLACE_TYPE_B +@item BOTTOMFIRST the frame is bottom-field-first @end table @@ -1563,7 +1851,7 @@ select=1 select=0 # select only I-frames -select='eq(pict_type\,PICT_TYPE_I)' +select='eq(pict_type\,I)' # select one frame every 100 select='not(mod(n\,100))' @@ -1572,7 +1860,7 @@ select='not(mod(n\,100))' 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\,PICT_TYPE_I)' +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)' @@ -2042,7 +2330,7 @@ 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{heigth}, or the name of a size abbreviation. The +@var{width}x@var{height}, or the name of a size abbreviation. The default value is "320x240". @item frame_rate @@ -2245,6 +2533,9 @@ generated per second. It has to be a string in the format 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 Set the video duration of the sourced video. The accepted syntax is: @example @@ -2278,7 +2569,7 @@ 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/vsink_buffer.h}. +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