[FFmpeg-cvslog] doc/ffmpeg: add vstats format documentation

[Stefano Sabatini]

ffmpeg | branch: master | Stefano Sabatini <stefasab at gmail.com> | Tue Jan 24 23:56:54 2023 +0100| [261fb55e393a16ebebd0e0a4b16b2f84e6b2f43d] | committer: Stefano Sabatini

doc/ffmpeg: add vstats format documentation

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

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=261fb55e393a16ebebd0e0a4b16b2f84e6b2f43d
---

 doc/ffmpeg.texi | 77 +++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file 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}.
- at item -vstats
-Dump video coding statistics to @file{vstats_HHMMSS.log}.
- at item -vstats_file @var{file}
-Dump video coding statistics to @var{file}.
- at item -vstats_version @var{file}
-Specifies which version of the vstats format to use. Default is 2.
 
-version = 1 :
+ at item -vstats
+Dump video coding statistics to @file{vstats_HHMMSS.log}. See the
+ at ref{vstats_file_format,,vstats file format} section for the format description.
 
- at 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}
+ at item -vstats_file @var{file}
+Dump video coding statistics to @var{file}. See the
+ at ref{vstats_file_format,,vstats file format} section for the format description.
 
-version > 1:
+ at item -vstats_version @var{file}
+Specify which version of the vstats format to use. Default is @code{2}. See the
+ at ref{vstats_file_format,,vstats file format} section for the format description.
 
- at 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.
 
+ at 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.
 
+ at anchor{vstats_file_format}
+ at 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:
+ at 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
+ at end example
+
+With version @code{2} the format is:
+ at 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
+ at end example
+
+The value corresponding to each key is described below:
+ at table @option
+ at item avg_br
+average bitrate expressed in Kbits/s
+
+ at item br
+bitrate expressed in Kbits/s
+
+ at item frame
+number of encoded frame
+
+ at item out
+out file index
+
+ at item PSNR
+Peak Signal to Noise Ratio
+
+ at item q
+quality of the frame
+
+ at item f_size
+encoded packet size expressed as number of bytes
+
+ at item s_size
+stream size expressed in KiB
+
+ at item st
+out file stream index
+
+ at item time
+time of the packet
+
+ at item type
+picture type
+ at 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