[FFmpeg-devel] [PATCH] doc/filters: expand documentation on libvmaf filter

[Stefano Sabatini]

On date Friday 2023-12-08 18:47:28 +0000, ffmpeg-devel Mailing List wrote:
> Attached.

> From e2b98c2dec1248f5000a9291bd6f1177de2a4d0f Mon Sep 17 00:00:00 2001
> From: nilfm <nilf at netflix.com>
> Date: Fri, 8 Dec 2023 14:28:12 +0000
> Subject: [PATCH] doc/filters: expand documentation on libvmaf filter
> 
> Signed-off-by: nilfm <nilf at netflix.com>
> ---
>  doc/filters.texi | 26 ++++++++++++++++++++------
>  1 file changed, 20 insertions(+), 6 deletions(-)
> 
> diff --git a/doc/filters.texi b/doc/filters.texi
> index 6d00ba2c3f..232bd6405b 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -16929,19 +16929,33 @@ The first input is the distorted video, and the second input is the reference vi
>  
>  The obtained VMAF score is printed through the logging system.
>  
> -It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
> +It requires Netflix's VMAF library (libvmaf) as a pre-requisite.
>  After installing the library it can be enabled using:
>  @code{./configure --enable-libvmaf}.
>  
> -The filter has following options:
> +The filter has the following options:
>  
>  @table @option
>  @item model
> -A `|` delimited list of vmaf models. Each model can be configured with a number of parameters.

> +A `|` delimited list of VMAF models. Each model can be configured with the following parameters:

This is still ambiguous since it is not defining how the parameters
must be specified. IIUC it should be:

Each model can be configured with a sequence of key=value parameters,
separated by @code{:}. Note that the @code{:} characters is special
and needs to be escaped. The following parameters are supported:
[...]

While at it, it might be good to extend the options with a "models"
alias to clarify plurality.

> + at table @option
> + at item version
> +Built-in model version. Example: @code{vmaf_v0.6.1}.
> + at item name
> +Name that will be associated with this model in the output logs.
> + at item path
> +Path to a model in the local filesystem.
> + at item enable_transform
> +If true, a model-defined transform will be applied to the final score. Default value: @code{false}.
> + at item disable_clip
> +If true, model-defined score clipping will be disabled. Default value: @code{false}.
> + at end table
>  Default value: @code{"version=vmaf_v0.6.1"}
>  
>  @item feature
> -A `|` delimited list of features. Each feature can be configured with a number of parameters.
> +A `|` delimited list of features. Each feature can be configured with a number
> +of parameters. The parameter @code{name} should be set to the name of the
> +feature. Other key-value parameter pairs will be passed in to the feature extractor.

ditto

>  
>  @item log_path
>  Set the file path to be used to store log files.
> @@ -16982,9 +16996,9 @@ ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='model=version=vmaf_v0.6
>  @end example
>  
>  @item
> -Example with multiple additional features:
> +Example with multiple additional features and feature options:
>  @example
> -ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='feature=name=psnr|name=ciede' -f null -
> +ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='feature=name=psnr\\:enable_mse=true|name=ciede' -f null -
>  @end example

looks good otherwise