Merge remote-tracking branch 'origin/master' into combined

7 files changed, 763 insertions, 243 deletions

diff --git a/doc/developer.texi b/doc/developer.texi
index a108da7adc..eaf5980145 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -217,8 +217,13 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
 
 @enumerate
 @item
-   Contributions should be licensed under the LGPL 2.1, including an
-   "or any later version" clause, or the MIT license.  GPL 2 including
+   Contributions should be licensed under the
+   @uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1},
+   including an "or any later version" clause, or, if you prefer
+   a gift-style license, the
+   @uref{http://www.isc.org/software/license/, ISC} or
+   @uref{http://mit-license.org/, MIT} license.
+   @uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} including
    an "or any later version" clause is also acceptable, but LGPL is
    preferred.
 @item
@@ -341,8 +346,6 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
 
 We think our rules are not too hard. If you have comments, contact us.
 
-Note, these rules are mostly borrowed from the MPlayer project.
-
 @anchor{Submitting patches}
 @section Submitting patches
 
diff --git a/doc/eval.texi b/doc/eval.texi
index f77b87deac..9b98c18cdf 100644
--- a/doc/eval.texi
+++ b/doc/eval.texi
@@ -20,111 +20,102 @@ The following unary operators are available: @code{+}, @code{-}.
 
 The following functions are available:
 @table @option
-@item sinh(x)
-Compute hyperbolic sine of @var{x}.
+@item abs(x)
+Compute absolute value of @var{x}.
 
-@item cosh(x)
-Compute hyperbolic cosine of @var{x}.
+@item acos(x)
+Compute arccosine of @var{x}.
 
-@item tanh(x)
-Compute hyperbolic tangent of @var{x}.
+@item asin(x)
+Compute arcsine of @var{x}.
 
-@item sin(x)
-Compute sine of @var{x}.
+@item atan(x)
+Compute arctangent of @var{x}.
+
+@item ceil(expr)
+Round the value of expression @var{expr} upwards to the nearest
+integer. For example, "ceil(1.5)" is "2.0".
 
 @item cos(x)
 Compute cosine of @var{x}.
 
-@item tan(x)
-Compute tangent of @var{x}.
-
-@item atan(x)
-Compute arctangent of @var{x}.
-
-@item asin(x)
-Compute arcsine of @var{x}.
+@item cosh(x)
+Compute hyperbolic cosine of @var{x}.
 
-@item acos(x)
-Compute arccosine of @var{x}.
+@item eq(x, y)
+Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
 
 @item exp(x)
 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
 
-@item log(x)
-Compute natural logarithm of @var{x}.
-
-@item abs(x)
-Compute absolute value of @var{x}.
-
-@item squish(x)
-Compute expression @code{1/(1 + exp(4*x))}.
+@item floor(expr)
+Round the value of expression @var{expr} downwards to the nearest
+integer. For example, "floor(-1.5)" is "-2.0".
 
 @item gauss(x)
 Compute Gauss function of @var{x}, corresponding to
 @code{exp(-x*x/2) / sqrt(2*PI)}.
 
-@item isinf(x)
-Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
-
-@item isnan(x)
-Return 1.0 if @var{x} is NAN, 0.0 otherwise.
+@item gcd(x, y)
+Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
+@var{y} are 0 or either or both are less than zero then behavior is undefined.
 
-@item mod(x, y)
-Compute the remainder of division of @var{x} by @var{y}.
+@item gt(x, y)
+Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
 
-@item max(x, y)
-Return the maximum between @var{x} and @var{y}.
+@item gte(x, y)
+Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
 
-@item min(x, y)
-Return the maximum between @var{x} and @var{y}.
+@item hypot(x, y)
+This function is similar to the C function with the same name; it returns
+"sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
+right triangle with sides of length @var{x} and @var{y}, or the distance of the
+point (@var{x}, @var{y}) from the origin.
 
-@item eq(x, y)
-Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
+@item if(x, y)
+Evaluate @var{x}, and if the result is non-zero return the result of
+the evaluation of @var{y}, return 0 otherwise.
 
-@item gte(x, y)
-Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
+@item if(x, y, z)
+Evaluate @var{x}, and if the result is non-zero return the evaluation
+result of @var{y}, otherwise the evaluation result of @var{z}.
 
-@item gt(x, y)
-Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
+@item ifnot(x, y)
+Evaluate @var{x}, and if the result is zero return the result of the
+evaluation of @var{y}, return 0 otherwise.
 
-@item lte(x, y)
-Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
+@item ifnot(x, y, z)
+Evaluate @var{x}, and if the result is zero return the evaluation
+result of @var{y}, otherwise the evaluation result of @var{z}.
 
-@item lt(x, y)
-Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
+@item isinf(x)
+Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
 
-@item st(var, expr)
-Allow to store the value of the expression @var{expr} in an internal
-variable. @var{var} specifies the number of the variable where to
-store the value, and it is a value ranging from 0 to 9. The function
-returns the value stored in the internal variable.
-Note, Variables are currently not shared between expressions.
+@item isnan(x)
+Return 1.0 if @var{x} is NAN, 0.0 otherwise.
 
 @item ld(var)
 Allow to load the value of the internal variable with number
 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
 The function returns the loaded value.
 
-@item while(cond, expr)
-Evaluate expression @var{expr} while the expression @var{cond} is
-non-zero, and returns the value of the last @var{expr} evaluation, or
-NAN if @var{cond} was always false.
+@item log(x)
+Compute natural logarithm of @var{x}.
 
-@item ceil(expr)
-Round the value of expression @var{expr} upwards to the nearest
-integer. For example, "ceil(1.5)" is "2.0".
+@item lt(x, y)
+Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
 
-@item floor(expr)
-Round the value of expression @var{expr} downwards to the nearest
-integer. For example, "floor(-1.5)" is "-2.0".
+@item lte(x, y)
+Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
 
-@item trunc(expr)
-Round the value of expression @var{expr} towards zero to the nearest
-integer. For example, "trunc(-1.5)" is "-1.0".
+@item max(x, y)
+Return the maximum between @var{x} and @var{y}.
 
-@item sqrt(expr)
-Compute the square root of @var{expr}. This is equivalent to
-"(@var{expr})^.5".
+@item min(x, y)
+Return the maximum between @var{x} and @var{y}.
+
+@item mod(x, y)
+Compute the remainder of division of @var{x} by @var{y}.
 
 @item not(expr)
 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
@@ -137,46 +128,71 @@ Compute the power of @var{x} elevated @var{y}, it is equivalent to
 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
 internal variable which will be used to save the seed/state.
 
-@item hypot(x, y)
-This function is similar to the C function with the same name; it returns
-"sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
-right triangle with sides of length @var{x} and @var{y}, or the distance of the
-point (@var{x}, @var{y}) from the origin.
+@item root(expr, max)
+Find an input value for which the function represented by @var{expr}
+with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
 
-@item gcd(x, y)
-Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
-@var{y} are 0 or either or both are less than zero then behavior is undefined.
+The expression in @var{expr} must denote a continuous function or the
+result is undefined.
 
-@item if(x, y)
-Evaluate @var{x}, and if the result is non-zero return the result of
-the evaluation of @var{y}, return 0 otherwise.
+@var{ld(0)} is used to represent the function input value, which means
+that the given expression will be evaluated multiple times with
+various input values that the expression can access through
+@code{ld(0)}. When the expression evaluates to 0 then the
+corresponding input value will be returned.
 
-@item if(x, y, z)
-Evaluate @var{x}, and if the result is non-zero return the evaluation
-result of @var{y}, otherwise the evaluation result of @var{z}.
+@item sin(x)
+Compute sine of @var{x}.
 
-@item ifnot(x, y)
-Evaluate @var{x}, and if the result is zero return the result of the
-evaluation of @var{y}, return 0 otherwise.
+@item sinh(x)
+Compute hyperbolic sine of @var{x}.
 
-@item ifnot(x, y, z)
-Evaluate @var{x}, and if the result is zero return the evaluation
-result of @var{y}, otherwise the evaluation result of @var{z}.
+@item sqrt(expr)
+Compute the square root of @var{expr}. This is equivalent to
+"(@var{expr})^.5".
+
+@item squish(x)
+Compute expression @code{1/(1 + exp(4*x))}.
+
+@item st(var, expr)
+Allow to store the value of the expression @var{expr} in an internal
+variable. @var{var} specifies the number of the variable where to
+store the value, and it is a value ranging from 0 to 9. The function
+returns the value stored in the internal variable.
+Note, Variables are currently not shared between expressions.
+
+@item tan(x)
+Compute tangent of @var{x}.
+
+@item tanh(x)
+Compute hyperbolic tangent of @var{x}.
+
+@item taylor(expr, x)
+@item taylor(expr, x, id)
+Evaluate a Taylor series at @var{x}, given an expression representing
+the @code{ld(id)}-th derivative of a function at 0.
 
-@item taylor(expr, x) taylor(expr, x, id)
-Evaluate a taylor series at x.
-expr represents the LD(id)-th derivates of f(x) at 0. If id is not specified
-then 0 is assumed.
-note, when you have the derivatives at y instead of 0
-taylor(expr, x-y) can be used
-When the series does not converge the results are undefined.
+When the series does not converge the result is undefined.
+
+@var{ld(id)} is used to represent the derivative order in @var{expr},
+which means that the given expression will be evaluated multiple times
+with various input values that the expression can access through
+@code{ld(id)}. If @var{id} is not specified then 0 is assumed.
+
+Note, when you have the derivatives at y instead of 0,
+@code{taylor(expr, x-y)} can be used.
 
 @item time(0)
 Return the current (wallclock) time in seconds.
 
-@item root(expr, max)
-Finds x where f(x)=0 in the interval 0..max.
-f() must be continuous or the result is undefined.
+@item trunc(expr)
+Round the value of expression @var{expr} towards zero to the nearest
+integer. For example, "trunc(-1.5)" is "-1.0".
+
+@item while(cond, expr)
+Evaluate expression @var{expr} while the expression @var{cond} is
+non-zero, and returns the value of the last @var{expr} evaluation, or
+NAN if @var{cond} was always false.
 @end table
 
 The following constants are available:
diff --git a/doc/filter_design.txt b/doc/filter_design.txt
index 362fce4146..772ca9dfb0 100644
--- a/doc/filter_design.txt
+++ b/doc/filter_design.txt
@@ -15,13 +15,13 @@ Format negotiation
   the list of supported formats.
 
   For video links, that means pixel format. For audio links, that means
-  channel layout, and sample format (the sample packing is implied by the
-  sample format).
+  channel layout, sample format (the sample packing is implied by the sample
+  format) and sample rate.
 
   The lists are not just lists, they are references to shared objects. When
   the negotiation mechanism computes the intersection of the formats
-  supported at each ends of a link, all references to both lists are
-  replaced with a reference to the intersection. And when a single format is
+  supported at each end of a link, all references to both lists are replaced
+  with a reference to the intersection. And when a single format is
   eventually chosen for a link amongst the remaining list, again, all
   references to the list are updated.
 
@@ -68,15 +68,15 @@ Buffer references ownership and permissions
 
     Here are the (fairly obvious) rules for reference ownership:
 
-    * A reference received by the start_frame or filter_frame method
-      belong to the corresponding filter.
+    * A reference received by the filter_frame method (or its start_frame
+      deprecated version) belongs to the corresponding filter.
 
       Special exception: for video references: the reference may be used
       internally for automatic copying and must not be destroyed before
       end_frame; it can be given away to ff_start_frame.
 
-    * A reference passed to ff_start_frame or ff_filter_frame is given
-      away and must no longer be used.
+    * A reference passed to ff_filter_frame (or the deprecated
+      ff_start_frame) is given away and must no longer be used.
 
     * A reference created with avfilter_ref_buffer belongs to the code that
       created it.
@@ -90,27 +90,11 @@ Buffer references ownership and permissions
   Link reference fields
   ---------------------
 
-    The AVFilterLink structure has a few AVFilterBufferRef fields. Here are
-    the rules to handle them:
-
-    * cur_buf is set before the start_frame and filter_frame methods to
-      the same reference given as argument to the methods and belongs to the
-      destination filter of the link. If it has not been cleared after
-      end_frame or filter_frame, libavfilter will automatically destroy
-      the reference; therefore, any filter that needs to keep the reference
-      for longer must set cur_buf to NULL.
-
-    * out_buf belongs to the source filter of the link and can be used to
-      store a reference to the buffer that has been sent to the destination.
-      If it is not NULL after end_frame or filter_frame, libavfilter will
-      automatically destroy the reference.
-
-      If a video input pad does not have a start_frame method, the default
-      method will request a buffer on the first output of the filter, store
-      the reference in out_buf and push a second reference to the output.
-
-    * src_buf, cur_buf_copy and partial_buf are used by libavfilter
-      internally and must not be accessed by filters.
+    The AVFilterLink structure has a few AVFilterBufferRef fields. The
+    cur_buf and out_buf were used with the deprecated
+    start_frame/draw_slice/end_frame API and should no longer be used.
+    src_buf, cur_buf_copy and partial_buf are used by libavfilter internally
+    and must not be accessed by filters.
 
   Reference permissions
   ---------------------
@@ -119,8 +103,10 @@ Buffer references ownership and permissions
     the code that owns the reference is allowed to do to the buffer data.
     Different references for the same buffer can have different permissions.
 
-    For video filters, the permissions only apply to the parts of the buffer
-    that have already been covered by the draw_slice method.
+    For video filters that implement the deprecated
+    start_frame/draw_slice/end_frame API, the permissions only apply to the
+    parts of the buffer that have already been covered by the draw_slice
+    method.
 
     The value is a binary OR of the following constants:
 
@@ -179,9 +165,9 @@ Buffer references ownership and permissions
       with the WRITE permission.
 
     * Filters that intend to keep a reference after the filtering process
-      is finished (after end_frame or filter_frame returns) must have the
-      PRESERVE permission on it and remove the WRITE permission if they
-      create a new reference to give it away.
+      is finished (after filter_frame returns) must have the PRESERVE
+      permission on it and remove the WRITE permission if they create a new
+      reference to give it away.
 
     * Filters that intend to modify a reference they have kept after the end
       of the filtering process need the REUSE2 permission and must remove
@@ -198,11 +184,11 @@ Frame scheduling
   Simple filters that output one frame for each input frame should not have
   to worry about it.
 
-  start_frame / filter_frame
-  ----------------------------
+  filter_frame
+  ------------
 
-    These methods are called when a frame is pushed to the filter's input.
-    They can be called at any time except in a reentrant way.
+    This method is called when a frame is pushed to the filter's input. It
+    can be called at any time except in a reentrant way.
 
     If the input frame is enough to produce output, then the filter should
     push the output frames on the output link immediately.
@@ -213,7 +199,7 @@ Frame scheduling
     filter; these buffered frames must be flushed immediately if a new input
     produces new output.
 
-    (Example: framerate-doubling filter: start_frame must (1) flush the
+    (Example: framerate-doubling filter: filter_frame must (1) flush the
     second copy of the previous frame, if it is still there, (2) push the
     first copy of the incoming frame, (3) keep the second copy for later.)
 
@@ -233,8 +219,8 @@ Frame scheduling
 
     This method is called when a frame is wanted on an output.
 
-    For an input, it should directly call start_frame or filter_frame on
-    the corresponding output.
+    For an input, it should directly call filter_frame on the corresponding
+    output.
 
     For a filter, if there are queued frames already ready, one of these
     frames should be pushed. If not, the filter should request a frame on
@@ -255,7 +241,7 @@ Frame scheduling
         }
         while (!frame_pushed) {
             input = input_where_a_frame_is_most_needed();
-            ret = avfilter_request_frame(input);
+            ret = ff_request_frame(input);
             if (ret == AVERROR_EOF) {
                 process_eof_on_input();
             } else if (ret < 0) {
@@ -266,4 +252,14 @@ Frame scheduling
 
     Note that, except for filters that can have queued frames, request_frame
     does not push frames: it requests them to its input, and as a reaction,
-    the start_frame / filter_frame method will be called and do the work.
+    the filter_frame method will be called and do the work.
+
+Legacy API
+==========
+
+  Until libavfilter 3.23, the filter_frame method was split:
+
+  - for video filters, it was made of start_frame, draw_slice (that could be
+    called several times on distinct parts of the frame) and end_frame;
+
+  - for audio filters, it was called filter_samples.
diff --git a/doc/filters.texi b/doc/filters.texi
index 21e2cff680..76a73e6dad 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -282,6 +282,306 @@ aconvert=u8:auto
 @end example
 @end itemize
 
+@section allpass
+
+Apply a two-pole all-pass filter with central frequency (in Hz)
+@var{frequency}, and filter-width @var{width}.
+An all-pass filter changes the audio's frequency to phase relationship
+without changing its frequency to amplitude relationship.
+
+The filter accepts parameters as a list of @var{key}=@var{value}
+pairs, separated by ":".
+
+A description of the accepted parameters follows.
+
+@table @option
+@item frequency, f
+Set frequency in Hz.
+
+@item width_type
+Set method to specify band-width of filter.
+@table @option
+@item h
+Hz
+@item q
+Q-Factor
+@item o
+octave
+@item s
+slope
+@end table
+
+@item width, w
+Specify the band-width of a filter in width_type units.
+@end table
+
+@section highpass
+
+Apply a high-pass filter with 3dB point frequency.
+The filter can be either single-pole, or double-pole (the default).
+The filter roll off at 6dB per pole per octave (20dB per pole per decade).
+
+The filter accepts parameters as a list of @var{key}=@var{value}
+pairs, separated by ":".
+
+A description of the accepted parameters follows.
+
+@table @option
+@item frequency, f
+Set frequency in Hz. Default is 3000.
+
+@item poles, p
+Set number of poles. Default is 2.
+
+@item width_type
+Set method to specify band-width of filter.
+@table @option
+@item h
+Hz
+@item q
+Q-Factor
+@item o
+octave
+@item s
+slope
+@end table
+
+@item width, w
+Specify the band-width of a filter in width_type units.
+Applies only to double-pole filter.
+The default is 0.707q and gives a Butterworth response.
+@end table
+
+@section lowpass
+
+Apply a low-pass filter with 3dB point frequency.
+The filter can be either single-pole or double-pole (the default).
+The filter roll off at 6dB per pole per octave (20dB per pole per decade).
+
+The filter accepts parameters as a list of @var{key}=@var{value}
+pairs, separated by ":".
+
+A description of the accepted parameters follows.
+
+@table @option
+@item frequency, f
+Set frequency in Hz. Default is 500.
+
+@item poles, p
+Set number of poles. Default is 2.
+
+@item width_type
+Set method to specify band-width of filter.
+@table @option
+@item h
+Hz
+@item q
+Q-Factor
+@item o
+octave
+@item s
+slope
+@end table
+
+@item width, w
+Specify the band-width of a filter in width_type units.
+Applies only to double-pole filter.
+The default is 0.707q and gives a Butterworth response.
+@end table
+
+@section bass
+
+Boost or cut the bass (lower) frequencies of the audio using a two-pole
+shelving filter with a response similar to that of a standard
+hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
+
+The filter accepts parameters as a list of @var{key}=@var{value}
+pairs, separated by ":".
+
+A description of the accepted parameters follows.
+
+@table @option
+@item gain, g
+Give the gain at 0 Hz. Its useful range is about -20
+(for a large cut) to +20 (for a large boost).
+Beware of clipping when using a positive gain.
+
+@item frequency, f
+Set the filter's central frequency and so can be used
+to extend or reduce the frequency range to be boosted or cut.
+The default value is @code{100} Hz.
+
+@item width_type
+Set method to specify band-width of filter.
+@table @option
+@item h
+Hz
+@item q
+Q-Factor
+@item o
+octave
+@item s
+slope
+@end table
+
+@item width, w
+Determine how steep is the filter's shelf transition.
+@end table
+
+@section treble
+
+Boost or cut treble (upper) frequencies of the audio using a two-pole
+shelving filter with a response similar to that of a standard
+hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
+
+The filter accepts parameters as a list of @var{key}=@var{value}
+pairs, separated by ":".
+
+A description of the accepted parameters follows.
+
+@table @option
+@item gain, g
+Give the gain at whichever is the lower of ~22 kHz and the
+Nyquist frequency. Its useful range is about -20 (for a large cut)
+to +20 (for a large boost). Beware of clipping when using a positive gain.
+
+@item frequency, f
+Set the filter's central frequency and so can be used
+to extend or reduce the frequency range to be boosted or cut.
+The default value is @code{3000} Hz.
+
+@item width_type
+Set method to specify band-width of filter.
+@table @option
+@item h
+Hz
+@item q
+Q-Factor
+@item o
+octave
+@item s
+slope
+@end table
+
+@item width, w
+Determine how steep is the filter's shelf transition.
+@end table
+
+@section bandpass
+
+Apply a two-pole Butterworth band-pass filter with central
+frequency @var{frequency}, and (3dB-point) band-width width.
+The @var{csg} option selects a constant skirt gain (peak gain = Q)
+instead of the default: constant 0dB peak gain.
+The filter roll off at 6dB per octave (20dB per decade).
+
+The filter accepts parameters as a list of @var{key}=@var{value}
+pairs, separated by ":".
+
+A description of the accepted parameters follows.
+
+@table @option
+@item frequency, f
+Set the filter's central frequency. Default is @code{3000}.
+
+@item csg
+Constant skirt gain if set to 1. Defaults to 0.
+
+@item width_type
+Set method to specify band-width of filter.
+@table @option
+@item h
+Hz
+@item q
+Q-Factor
+@item o
+octave
+@item s
+slope
+@end table
+
+@item width, w
+Specify the band-width of a filter in width_type units.
+@end table
+
+@section bandreject
+
+Apply a two-pole Butterworth band-reject filter with central
+frequency @var{frequency}, and (3dB-point) band-width @var{width}.
+The filter roll off at 6dB per octave (20dB per decade).
+
+The filter accepts parameters as a list of @var{key}=@var{value}
+pairs, separated by ":".
+
+A description of the accepted parameters follows.
+
+@table @option
+@item frequency, f
+Set the filter's central frequency. Default is @code{3000}.
+
+@item width_type
+Set method to specify band-width of filter.
+@table @option
+@item h
+Hz
+@item q
+Q-Factor
+@item o
+octave
+@item s
+slope
+@end table
+
+@item width, w
+Specify the band-width of a filter in width_type units.
+@end table
+
+@section biquad
+
+Apply a biquad IIR filter with the given coefficients.
+Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
+are the numerator and denominator coefficients respectively.
+
+@section equalizer
+
+Apply a two-pole peaking equalisation (EQ) filter. With this
+filter, the signal-level at and around a selected frequency can
+be increased or decreased, whilst (unlike bandpass and bandreject
+filters) that at all other frequencies is unchanged.
+
+In order to produce complex equalisation curves, this filter can
+be given several times, each with a different central frequency.
+
+The filter accepts parameters as a list of @var{key}=@var{value}
+pairs, separated by ":".
+
+A description of the accepted parameters follows.
+
+@table @option
+@item frequency, f
+Set the filter's central frequency in Hz.
+
+@item width_type
+Set method to specify band-width of filter.
+@table @option
+@item h
+Hz
+@item q
+Q-Factor
+@item o
+octave
+@item s
+slope
+@end table
+
+@item width, w
+Specify the band-width of a filter in width_type units.
+
+@item gain, g
+Set the required gain or attenuation in dB.
+Beware of clipping when using a positive gain.
+@end table
+
 @section afade
 
 Apply fade-in/out effect to input audio.
@@ -319,28 +619,30 @@ the output audio will be silence. Default is 0.
 If set this option is used instead of @var{nb_samples} one.
 
 @item curve
-Set cuve for fade transition.
+Set curve for fade transition.
+
+It accepts the following values:
 @table @option
-@item @var{triangular, linear slope (default)}
-@code{tri}
-@item @var{quarter of sine wave}
-@code{qsin}
-@item @var{half of sine wave}
-@code{esin}
-@item @var{exponential sine wave}
-@code{hsin}
-@item @var{logarithmic}
-@code{log}
-@item @var{inverted parabola}
-@code{par}
-@item @var{quadratic}
-@code{qua}
-@item @var{cubic}
-@code{cub}
-@item @var{square root}
-@code{squ}
-@item @var{cubic root}
-@code{cbr}
+@item tri
+select triangular, linear slope (default)
+@item qsin
+select quarter of sine wave
+@item hsin
+select half of sine wave
+@item esin
+select exponential sine wave
+@item log
+select logarithmic
+@item par
+select inverted parabola
+@item qua
+select quadratic
+@item cub
+select cubic
+@item squ
+select square root
+@item cbr
+select cubic root
 @end table
 @end table
 
@@ -3014,10 +3316,14 @@ corresponding pixel component values.
 The @var{lut} filter requires either YUV or RGB pixel formats in
 input, and accepts the options:
 @table @option
-@item @var{c0} (first  pixel component)
-@item @var{c1} (second pixel component)
-@item @var{c2} (third  pixel component)
-@item @var{c3} (fourth pixel component, corresponds to the alpha component)
+@item c0
+set first pixel component expression
+@item c1
+set second pixel component expression
+@item c2
+set third pixel component expression
+@item c3
+set fourth pixel component expression, corresponds to the alpha component
 @end table
 
 The exact component associated to each option depends on the format in
@@ -3026,19 +3332,27 @@ input.
 The @var{lutrgb} filter requires RGB pixel formats in input, and
 accepts the options:
 @table @option
-@item @var{r} (red component)
-@item @var{g} (green component)
-@item @var{b} (blue component)
-@item @var{a} (alpha component)
+@item r
+set red component expression
+@item g
+set green component expression
+@item b
+set blue component expression
+@item a
+alpha component expression
 @end table
 
 The @var{lutyuv} filter requires YUV pixel formats in input, and
 accepts the options:
 @table @option
-@item @var{y} (Y/luminance component)
-@item @var{u} (U/Cb component)
-@item @var{v} (V/Cr component)
-@item @var{a} (alpha component)
+@item y
+set Y/luminance component expression
+@item u
+set U/Cb component expression
+@item v
+set V/Cr component expression
+@item a
+set alpha component expression
 @end table
 
 The expressions can contain the following constants and functions:
@@ -3078,34 +3392,58 @@ expression
 
 All expressions default to "val".
 
-Some examples follow:
+@subsection Examples
+
+@itemize
+@item
+Negate input video:
 @example
-# negate input video
 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
+@end example
 
-# the above is the same as
+The above is the same as:
+@example
 lutrgb="r=negval:g=negval:b=negval"
 lutyuv="y=negval:u=negval:v=negval"
+@end example
 
-# negate luminance
+@item
+Negate luminance:
+@example
 lutyuv=y=negval
+@end example
 
-# remove chroma components, turns the video into a graytone image
+@item
+Remove chroma components, turns the video into a graytone image:
+@example
 lutyuv="u=128:v=128"
+@end example
 
-# apply a luma burning effect
+@item
+Apply a luma burning effect:
+@example
 lutyuv="y=2*val"
+@end example
 
-# remove green and blue components
+@item
+Remove green and blue components:
+@example
 lutrgb="g=0:b=0"
+@end example
 
-# set a constant alpha channel value on input
+@item
+Set a constant alpha channel value on input:
+@example
 format=rgba,lutrgb=a="maxval-minval/2"
+@end example
 
-# correct luminance gamma by a 0.5 factor
+@item
+Correct luminance gamma by a 0.5 factor:
+@example
 lutyuv=y=gammaval(0.5)
 @end example
+@end itemize
 
 @section mp
 
@@ -3419,14 +3757,50 @@ testsrc=s=100x100, split=4 [in0][in1][in2][in3];
 
 @section pad
 
-Add paddings to the input image, and places the original input at the
+Add paddings to the input image, and place the original input at the
 given coordinates @var{x}, @var{y}.
 
-It accepts the following parameters:
+The filter accepts parameters as a list of @var{key}=@var{value} pairs,
+separated by ":".
+
+If the key of the first options is omitted, the arguments are
+interpreted according to the syntax
 @var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
 
-The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
-expressions containing the following constants:
+A description of the accepted options follows.
+
+@table @option
+@item width, w
+@item height, h
+Specify an expression for the size of the output image with the
+paddings added. If the value for @var{width} or @var{height} is 0, the
+corresponding input size is used for the output.
+
+The @var{width} expression can reference the value set by the
+@var{height} expression, and vice versa.
+
+The default value of @var{width} and @var{height} is 0.
+
+@item x
+@item y
+Specify an expression for the offsets where to place the input image
+in the padded area with respect to the top/left border of the output
+image.
+
+The @var{x} expression can reference the value set by the @var{y}
+expression, and vice versa.
+
+The default value of @var{x} and @var{y} is 0.
+
+@item color
+Specify the color of the padded area, it can be the name of a color
+(case insensitive match) or a 0xRRGGBB[AA] sequence.
+
+The default value of @var{color} is "black".
+@end table
+
+The value for the @var{width}, @var{height}, @var{x}, and @var{y}
+options are expressions containing the following constants:
 
 @table @option
 @item in_w, in_h
@@ -3460,39 +3834,6 @@ horizontal and vertical chroma subsample values. For example for the
 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
 @end table
 
-Follows the description of the accepted parameters.
-
-@table @option
-@item width, height
-
-Specify the size of the output image with the paddings added. If the
-value for @var{width} or @var{height} is 0, the corresponding input size
-is used for the output.
-
-The @var{width} expression can reference the value set by the
-@var{height} expression, and vice versa.
-
-The default value of @var{width} and @var{height} is 0.
-
-@item x, y
-
-Specify the offsets where to place the input image in the padded area
-with respect to the top/left border of the output image.
-
-The @var{x} expression can reference the value set by the @var{y}
-expression, and vice versa.
-
-The default value of @var{x} and @var{y} is 0.
-
-@item color
-
-Specify the color of the padded area, it can be the name of a color
-(case insensitive match) or a 0xRRGGBB[AA] sequence.
-
-The default value of @var{color} is "black".
-
-@end table
-
 @subsection Examples
 
 @itemize
@@ -3504,6 +3845,11 @@ column 0, row 40:
 pad=640:480:0:40:violet
 @end example
 
+The example above is equivalent to the following command:
+@example
+pad=width=640:height=480:x=0:y=40:color=violet
+@end example
+
 @item
 Pad the input to get an output with dimensions increased by 3/2,
 and put the input video at the center of the padded area:
@@ -5705,10 +6051,60 @@ spectrum.
 The filter accepts the following named parameters:
 @table @option
 @item size, s
-Specify the video size for the output. Default value is @code{640x480}.
+Specify the video size for the output. Default value is @code{640x512}.
+
 @item slide
 Specify if the spectrum should slide along the window. Default value is
 @code{0}.
+
+@item mode
+Specify display mode.
+
+It accepts the following values:
+@table @samp
+@item combined
+all channels are displayed in the same row
+@item separate
+all channels are displayed in separate rows
+@end table
+
+Default value is @samp{combined}.
+
+@item color
+Specify display color mode.
+
+It accepts the following values:
+@table @samp
+@item channel
+each channel is displayed in a separate color
+@item intensity
+each channel is is displayed using the same color scheme
+@end table
+
+Default value is @samp{channel}.
+
+@item scale
+Specify scale used for calculating intensity color values.
+
+It accepts the following values:
+@table @samp
+@item lin
+linear
+@item sqrt
+square root, default
+@item cbrt
+cubic root
+@item log
+logarithmic
+@end table
+
+Default value is @samp{sqrt}.
+
+@item saturation
+Set saturation modifier for displayed colors. Negative values provide
+alternative color scheme. @code{0} is no saturation at all.
+Saturation must be in [-10.0, 10.0] range.
+Default value is @code{1}.
 @end table
 
 The usage is very similar to the showwaves filter; see the examples in that
diff --git a/doc/indevs.texi b/doc/indevs.texi
index 621e1de978..cc5d66622c 100644
--- a/doc/indevs.texi
+++ b/doc/indevs.texi
@@ -583,10 +583,16 @@ command:
 ffmpeg -f sndio -i /dev/audio0 /tmp/oss.wav
 @end example
 
-@section video4linux2
+@section video4linux2, v4l2
 
 Video4Linux2 input video device.
 
+"v4l2" can be used as alias for "video4linux2".
+
+If FFmpeg is built with v4l-utils support (by using the
+@code{--enable-libv4l2} configure option), the device will always rely
+on libv4l2.
+
 The name of the device to grab is a file device node, usually Linux
 systems tend to automatically create such nodes when the device
 (e.g. an USB webcam) is plugged into the system, and has a name of the
@@ -596,8 +602,8 @@ the device.
 Video4Linux2 devices usually support a limited set of
 @var{width}x@var{height} sizes and framerates. You can check which are
 supported using @command{-list_formats all} for Video4Linux2 devices.
-
-Some usage examples of the video4linux2 devices with ffmpeg and ffplay:
+Some devices, like TV cards, support one or more standards. It is possible
+to list all the supported standards using @command{-list_standards all}.
 
 The time base for the timestamps is 1 microsecond. Depending on the kernel
 version and configuration, the timestamps may be derived from the real time
@@ -606,19 +612,93 @@ boot time, unaffected by NTP or manual changes to the clock). The
 @option{-timestamps abs} or @option{-ts abs} option can be used to force
 conversion into the real time clock.
 
-Note that if FFmpeg is build with v4l-utils support ("--enable-libv4l2"
-option), it will always be used.
+Some usage examples of the video4linux2 device with @command{ffmpeg}
+and @command{ffplay}:
+@itemize
+@item
+Grab and show the input of a video4linux2 device:
 @example
-# Grab and show the input of a video4linux2 device.
 ffplay -f video4linux2 -framerate 30 -video_size hd720 /dev/video0
+@end example
 
-# Grab and record the input of a video4linux2 device, leave the
-framerate and size as previously set.
+@item
+Grab and record the input of a video4linux2 device, leave the
+framerate and size as previously set:
+@example
 ffmpeg -f video4linux2 -input_format mjpeg -i /dev/video0 out.mpeg
 @end example
+@end itemize
+
+For more information about Video4Linux, check @url{http://linuxtv.org/}.
+
+@subsection Options
+
+@table @option
+@item standard
+Set the standard. Must be the name of a supported standard. To get a
+list of the supported standards, use the @option{list_standards}
+option.
+
+@item channel
+Set the input channel number. Default to 0.
+
+@item video_size
+Set the video frame size. The argument must be a string in the form
+@var{WIDTH}x@var{HEIGHT} or a valid size abbreviation.
+
+@item pixel_format
+Select the pixel format (only valid for raw video input).
+
+@item input_format
+Set the preferred pixel format (for raw video) or a codec name.
+This option allows to select the input format, when several are
+available.
+
+@item framerate
+Set the preferred video framerate.
+
+@item list_formats
+List available formats (supported pixel formats, codecs, and frame
+sizes) and exit.
+
+Available values are:
+@table @samp
+@item all
+Show all available (compressed and non-compressed) formats.
+
+@item raw
+Show only raw video (non-compressed) formats.
+
+@item compressed
+Show only compressed formats.
+@end table
 
-"v4l" and "v4l2" can be used as aliases for the respective "video4linux" and
-"video4linux2".
+@item list_standards
+List supported standards and exit.
+
+Available values are:
+@table @samp
+@item all
+Show all supported standards.
+@end table
+
+@item timestamps, ts
+Set type of timestamps for grabbed frames.
+
+Available values are:
+@table @samp
+@item default
+Use timestamps from the kernel.
+
+@item abs
+Use absolute timestamps (wall clock).
+
+@item mono2abs
+Force conversion from monotonic to absolute timestamps.
+@end table
+
+Default value is @code{default}.
+@end table
 
 @section vfwcap
 
diff --git a/doc/muxers.texi b/doc/muxers.texi
index 965a4bb124..0aea87b4e7 100644
--- a/doc/muxers.texi
+++ b/doc/muxers.texi
@@ -645,7 +645,7 @@ of the generated segments. May not work with some combinations of
 muxers/codecs. It is set to @code{0} by default.
 @end table
 
-@section Examples
+@subsection Examples
 
 @itemize
 @item
@@ -727,10 +727,11 @@ Write an mp3 with an ID3v2.3 header and an ID3v1 footer:
 ffmpeg -i INPUT -id3v2_version 3 -write_id3v1 1 out.mp3
 @end example
 
-Attach a picture to an mp3:
+To attach a picture to an mp3 file select both the audio and the picture stream
+with @code{map}:
 @example
-ffmpeg -i input.mp3 -i cover.png -c copy -metadata:s:v title="Album cover"
--metadata:s:v comment="Cover (Front)" out.mp3
+ffmpeg -i input.mp3 -i cover.png -c copy -map 0 -map 1
+-metadata:s:v title="Album cover" -metadata:s:v comment="Cover (Front)" out.mp3
 @end example
 
 @section ogg
diff --git a/doc/syntax.texi b/doc/syntax.texi
index a3aabce1e9..4dddc3cbc2 100644
--- a/doc/syntax.texi
+++ b/doc/syntax.texi
@@ -112,6 +112,22 @@ Specify the size of the sourced video, it may be a string of the form
 
 The following abbreviations are recognized:
 @table @samp
+@item ntsc
+720x480
+@item pal
+720x576
+@item qntsc
+352x240
+@item qpal
+352x288
+@item sntsc
+640x480
+@item spal
+768x576
+@item film
+352x240
+@item ntsc-film
+352x240
 @item sqcif
 128x96
 @item qcif
@@ -170,6 +186,18 @@ The following abbreviations are recognized:
 1280x720
 @item hd1080
 1920x1080
+@item 2k
+2048x1080
+@item 2kflat
+1998x1080
+@item 2kscope
+2048x858
+@item 4k
+4096x2160
+@item 4kflat
+3996x2160
+@item 4kscope
+4096x1716
 @end table
 
 @anchor{video rate syntax}
@@ -187,17 +215,17 @@ The following abbreviations are recognized:
 @item pal
 25/1
 @item qntsc
-30000/1
+30000/1001
 @item qpal
 25/1
 @item sntsc
-30000/1
+30000/1001
 @item spal
 25/1
 @item film
 24/1
 @item ntsc-film
-24000/1
+24000/1001
 @end table
 
 @anchor{ratio syntax}