doc/ffmpeg: extend documentation for the -filter options and -af/vf aliases

2 files changed, 24 insertions, 15 deletions

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index d0fe327c15..0f862c1136 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -334,13 +334,21 @@ Stop writing to the stream after @var{framecount} frames.
 Use fixed quality scale (VBR). The meaning of @var{q} is
 codec-dependent.
 
+@anchor{filter_option}
 @item -filter[:@var{stream_specifier}] @var{filter_graph} (@emph{output,per-stream})
+Create the filter graph specified by @var{filter_graph} and use it to
+filter the stream.
+
 @var{filter_graph} is a description of the filter graph to apply to
-the stream. Use @code{-filters} to show all the available filters
-(including also sources and sinks).
+the stream, and must have a single input and a single output of the
+same type of the stream. In the filter graph, the input is associated
+to the label @code{in}, and the output to the label @code{out}. See
+the ffmpeg-filters manual for more information about the filtergraph
+syntax.
+
+See the @ref{filter_complex_option,,-filter_complex option} if you
+want to create filter graphs with multiple inputs and/or outputs.
 
-See also the @option{-filter_complex} option if you want to create filter graphs
-with multiple inputs and/or outputs.
 @item -pre[:@var{stream_specifier}] @var{preset_name} (@emph{output,per-stream})
 Specify the preset for matching stream(s).
 
@@ -487,11 +495,10 @@ stream
 Set the ISO 639 language code (3 letters) of the current video stream.
 
 @item -vf @var{filter_graph} (@emph{output})
-@var{filter_graph} is a description of the filter graph to apply to
-the input video.
-Use the option "-filters" to show all the available filters (including
-also sources and sinks).  This is an alias for @code{-filter:v}.
+Create the filter graph specified by @var{filter_graph} and use it to
+filter the stream.
 
+This is an alias for @code{-filter:v}, see the @ref{filter_option,,-filter option}.
 @end table
 
 @section Advanced Video Options
@@ -581,11 +588,12 @@ Set the audio codec. This is an alias for @code{-codec:a}.
 @item -sample_fmt[:@var{stream_specifier}] @var{sample_fmt} (@emph{output,per-stream})
 Set the audio sample format. Use @code{-sample_fmts} to get a list
 of supported sample formats.
+
 @item -af @var{filter_graph} (@emph{output})
-@var{filter_graph} is a description of the filter graph to apply to
-the input audio.
-Use the option "-filters" to show all the available filters (including
-also sources and sinks).  This is an alias for @code{-filter:a}.
+Create the filter graph specified by @var{filter_graph} and use it to
+filter the stream.
+
+This is an alias for @code{-filter:a}, see the @ref{filter_option,,-filter option}.
 @end table
 
 @section Advanced Audio options:
@@ -928,6 +936,7 @@ Specify Timecode for writing. @var{SEP} is ':' for non drop timecode and ';'
 ffmpeg -i input.mpg -timecode 01:02:03.04 -r 30000/1001 -s ntsc output.mpg
 @end example
 
+@anchor{filter_complex_option}
 @item -filter_complex @var{filtergraph} (@emph{global})
 Define a complex filter graph, i.e. one with arbitrary number of inputs and/or
 outputs. For simple graphs -- those with one input and one output of the same
diff --git a/ffmpeg_opt.c b/ffmpeg_opt.c
index 38ffd420b4..c98e03063b 100644
--- a/ffmpeg_opt.c
+++ b/ffmpeg_opt.c
@@ -2463,7 +2463,7 @@ const OptionDef options[] = {
     { "profile",        HAS_ARG | OPT_EXPERT | OPT_PERFILE,          { .func_arg = opt_profile },
         "set profile", "profile" },
     { "filter",         HAS_ARG | OPT_STRING | OPT_SPEC,             { .off = OFFSET(filters) },
-        "set stream filterchain", "filter_list" },
+        "set stream filtergraph", "filter_graph" },
     { "reinit_filter",  HAS_ARG | OPT_INT | OPT_SPEC,                { .off = OFFSET(reinit_filters) },
         "reinit filtergraph on input parameter changes", "" },
     { "filter_complex", HAS_ARG | OPT_EXPERT,                        { .func_arg = opt_filter_complex },
@@ -2537,7 +2537,7 @@ const OptionDef options[] = {
     { "vstats_file",  OPT_VIDEO | HAS_ARG | OPT_EXPERT ,                         { opt_vstats_file },
         "dump video coding statistics to file", "file" },
     { "vf",           OPT_VIDEO | HAS_ARG  | OPT_PERFILE,                        { .func_arg = opt_video_filters },
-        "video filters", "filter list" },
+        "set video filters", "filter_graph" },
     { "intra_matrix", OPT_VIDEO | HAS_ARG | OPT_EXPERT  | OPT_STRING | OPT_SPEC, { .off = OFFSET(intra_matrices) },
         "specify intra matrix coeffs", "matrix" },
     { "inter_matrix", OPT_VIDEO | HAS_ARG | OPT_EXPERT  | OPT_STRING | OPT_SPEC, { .off = OFFSET(inter_matrices) },
@@ -2582,7 +2582,7 @@ const OptionDef options[] = {
     { "channel_layout", OPT_AUDIO | HAS_ARG  | OPT_EXPERT | OPT_PERFILE,           { .func_arg = opt_channel_layout },
         "set channel layout", "layout" },
     { "af",             OPT_AUDIO | HAS_ARG  | OPT_PERFILE,                        { .func_arg = opt_audio_filters },
-        "audio filters", "filter list" },
+        "set audio filters", "filter_graph" },
 
     /* subtitle options */
     { "sn",     OPT_SUBTITLE | OPT_BOOL | OPT_OFFSET, { .off = OFFSET(subtitle_disable) },