doc/ffmpeg: add vstats format documentation

Address issue:
http://trac.ffmpeg.org/ticket/7520

1 files changed, 67 insertions, 10 deletions

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index 7feba8ab70..6baf51bf0a 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -1025,20 +1025,19 @@ factor if negative.
 @item -psnr
 Calculate PSNR of compressed frames. This option is deprecated, pass the
 PSNR flag to the encoder instead, using @code{-flags +psnr}.
-@item -vstats
-Dump video coding statistics to @file{vstats_HHMMSS.log}.
-@item -vstats_file @var{file}
-Dump video coding statistics to @var{file}.
-@item -vstats_version @var{file}
-Specifies which version of the vstats format to use. Default is 2.
 
-version = 1 :
+@item -vstats
+Dump video coding statistics to @file{vstats_HHMMSS.log}. See the
+@ref{vstats_file_format,,vstats file format} section for the format description.
 
-@code{frame= %5d q= %2.1f PSNR= %6.2f f_size= %6d s_size= %8.0fkB time= %0.3f br= %7.1fkbits/s avg_br= %7.1fkbits/s}
+@item -vstats_file @var{file}
+Dump video coding statistics to @var{file}. See the
+@ref{vstats_file_format,,vstats file format} section for the format description.
 
-version > 1:
+@item -vstats_version @var{file}
+Specify which version of the vstats format to use. Default is @code{2}. See the
+@ref{vstats_file_format,,vstats file format} section for the format description.
 
-@code{out= %2d st= %2d frame= %5d q= %2.1f PSNR= %6.2f f_size= %6d s_size= %8.0fkB time= %0.3f br= %7.1fkbits/s avg_br= %7.1fkbits/s}
 @item -top[:@var{stream_specifier}] @var{n} (@emph{output,per-stream})
 top=1/bottom=0/auto=-1 field first
 @item -vtag @var{fourcc/tag} (@emph{output})
@@ -2087,6 +2086,7 @@ encoder/muxer, it does not change the stream to conform to this value. Setting
 values that do not match the stream properties may result in encoding failures
 or invalid output files.
 
+@anchor{stats_enc_options}
 @item -stats_enc_pre[:@var{stream_specifier}] @var{path} (@emph{output,per-stream})
 @item -stats_enc_post[:@var{stream_specifier}] @var{path} (@emph{output,per-stream})
 @item -stats_mux_pre[:@var{stream_specifier}] @var{path} (@emph{output,per-stream})
@@ -2254,6 +2254,63 @@ search for the file @file{libvpx-1080p.avpreset}.
 If no such file is found, then ffmpeg will search for a file named
 @var{arg}.avpreset in the same directories.
 
+@anchor{vstats_file_format}
+@section vstats file format
+The @code{-vstats} and @code{-vstats_file} options enable generation of a file
+containing statistics about the generated video outputs.
+
+The @code{-vstats_version} option controls the format version of the generated
+file.
+
+With version @code{1} the format is:
+@example
+frame= @var{FRAME} q= @var{FRAME_QUALITY} PSNR= @var{PSNR} f_size= @var{FRAME_SIZE} s_size= @var{STREAM_SIZE}kB time= @var{TIMESTAMP} br= @var{BITRATE}kbits/s avg_br= @var{AVERAGE_BITRATE}kbits/s
+@end example
+
+With version @code{2} the format is:
+@example
+out= @var{OUT_FILE_INDEX} st= @var{OUT_FILE_STREAM_INDEX} frame= @var{FRAME_NUMBER} q= @var{FRAME_QUALITY}f PSNR= @var{PSNR} f_size= @var{FRAME_SIZE} s_size= @var{STREAM_SIZE}kB time= @var{TIMESTAMP} br= @var{BITRATE}kbits/s avg_br= @var{AVERAGE_BITRATE}kbits/s
+@end example
+
+The value corresponding to each key is described below:
+@table @option
+@item avg_br
+average bitrate expressed in Kbits/s
+
+@item br
+bitrate expressed in Kbits/s
+
+@item frame
+number of encoded frame
+
+@item out
+out file index
+
+@item PSNR
+Peak Signal to Noise Ratio
+
+@item q
+quality of the frame
+
+@item f_size
+encoded packet size expressed as number of bytes
+
+@item s_size
+stream size expressed in KiB
+
+@item st
+out file stream index
+
+@item time
+time of the packet
+
+@item type
+picture type
+@end table
+
+See also the @ref{stats_enc_options,,-stats_enc options} for an alternative way
+to show encoding statistics.
+
 @c man end OPTIONS
 
 @chapter Examples