parts/AuxilaryPrograms.tex

   1 \chapter{Auxiliary Programs}%
   2 \label{cha:auxiliary_programs}
   3
   4 \section{Using Ydiff to check results}
   5 \label{sec:ydiff_check_results}
   6
   7 Delivered with Infinity \CGG{} and in the \CGG{} path, there is a file \texttt{ydiff.C} This program compares the output from 2 files to see the differences . Do: \texttt{cd cin\_path} and key in \texttt{make ydiff}.
   8
   9 % The following does not work like this.
  10 % {                                      % uses braces to localize caption alignment changes.
  11 % \begin{figure}[h]
  12 %        \captionsetup{justification=raggedright,singlelinecheck=false}
  13 %        \includegraphics[width=0.4\linewidth]{ydiff_same.png}
  14 %        \caption{Exact match}
  15 %        \vspace{-9cm}
  16 %        \hspace{0.4\linewidth}
  17 %        \captionsetup{justification=raggedleft,singlelinecheck=false}
  18 %        \includegraphics[width=0.4\linewidth]{ydiff_change.png}
  19 %        \caption{"giraffe" artifacts on 2 files spaced differently}
  20 % \end{figure}
  21 % }
  22
  23 % We pack two pictures of unequal height next to each other and
  24 % align them flush at
  25 % a) the first line of the caption.
  26 % b) or tricks with strut, it's flush at the top.
  27 \begin{figure}[h]
  28   \begin{minipage}[t]{0.49\textwidth}
  29     \strut\\[-1em]
  30     \includegraphics[width=\linewidth]{ydiff_same.png}
  31     \caption{Exact match}
  32   \end{minipage}
  33   \hfill
  34   \begin{minipage}[t]{0.49\textwidth}
  35     \strut\\[-1em]
  36     \includegraphics[width=\linewidth]{ydiff_change.png}
  37     \caption{"Giraffe" artifacts on 2 files spaced differently}
  38   \end{minipage}
  39 \end{figure}
  40
  41 You can now use this to check the quality differences of various
  42 outputs. For example, in this same directory key in:
  43 % The indentation of an environment matches the type area.
  44 \begin{list}{}{}
  45 \item \texttt{./ydiff /tmp/yourfile.mp4 /tmp/yourfile.mp4}
  46 \end{list}
  47 %\hspace{2em}\texttt{./ydiff /tmp/yourfile.mp4 /tmp/yourfile.mp4}
  48
  49 Since you are comparing a file to itself, you will see a clean looking white window in the left-hand corner and columns 2,3,4 will be all zeros. Run this same command with a 3rd spacing parameter of {}-1 as shown below, and you will see artifacts of comparing 2 files starting in a different position.
  50 \begin{list}{}{}
  51 \item \texttt{./ydiff /tmp/yourfile.mp4 /tmp/yourfile.mp4 -1}
  52 \end{list}
  53 % \hspace{2em}\texttt{./ydiff /tmp/yourfile.mp4 /tmp/yourfile.mp4 -1}
  54
  55 Now render yourfile using different quality levels and run ydiff to compare the 2 results. You will see only noise difference which accounts for the quality level. Columns 2,3,4 might no longer be exactly zero but will represent only noise differences. The ydiff output is debug data with lines that show frame size in bytes, sum of error, and sum of absolute value of error. The frames size is sort of useless, the sum of error shows frame gray point drift and the abs error is the total linear color error between the images. At the very end is the total gray point drift and total absolute error on the last line.
  56
  57
  58 \section{Image Sequence Creation}
  59 \label{sec:image_sequence_creation}
  60
  61 Example script to create a jpeglist sequence file is next:
  62 \begin{lstlisting}[numbers=none]
  63 #!/bin/bash
  64 out="$1"
  65 dir=`dirname "$out"`
  66 shift
  67 geom=`jpegtopnm "$1" | head -2 | tail -1`
  68 w=`(set - $geom; echo $1)`
  69 h=`(set - $geom; echo $2)`
  70 exec > $out
  71 echo "JPEGLIST"
  72 echo "# First line is always JPEGLIST"
  73 echo "# Frame rate:"
  74 echo "29.970030"
  75 echo "# Width:"
  76 echo "$w"
  77 echo "# Height:"
  78 echo "$h"
  79 echo "# List of image files follows"
  80 while [ $# -gt 0 ]; do
  81   if [ x`dirname "$1"` = x"$dir" ]; then
  82         f=./`basename "$1"`;
  83   else
  84         f="$1";
  85   fi
  86   echo "$f"
  87   shift
  88 done
  89 \end{lstlisting}
  90 Example usage of this script follows:
  91
  92 \qquad \texttt{jpeglist.sh outfile infiles*.jpg}
  93
  94 \section{Webm\,/\,Vp9 Usage and Example File}
  95 \label{sec:webm/vp9_usage_example}
  96 % FIXME No footnotes with expressions of thanks in the title.
  97 % \protect\footnote{credit Frederic Roenitz}}
  98
  99 \textsc{VP9} is a video codec licensed under the BSD license and is
 100 considered open source,
 101 % Sisvel Announces AV1 Patent Pool, March 10, 2020
 102 % https://www.streamingmedia.com/Articles/ReadArticle.aspx?ArticleID=139636
 103 %  Webm / VP9 is a media file format which is free to use under the
 104 %  BSD license and is open-source; thus there are no licensing
 105 %  issues to be concerned about.
 106 the \textsc{Webm} container is based on \textsc{Matroska} for video
 107 and \textsc{Opus} for audio. There are some common \textsc{VP9} rendering
 108 options files that support creation of video for YouTube,
 109 Dailymotion, and other online video services.
 110
 111 YouTube easy startup steps are documented in the Appendix (\ref{sec:youtube_with_cinelerra}). These same steps have been verified to work for creating Dailymotion videos -- however, the created files must be renamed before uploading to change the youtube extension to webm instead for Dailymotion.
 112
 113 Below is one of the \textsc{VP9} rendering options file with documentation for specifics:
 114
 115 \textbf{webm libvpx-vp9}
 116
 117 (20171114-2203)
 118
 119 from {\small \url{https://developers.google.com/media/vp9/settings/vod/}}
 120
 121 1280x720 (24, 25 or 30 frames per second)
 122
 123 Bitrate (bit rate)
 124
 125 \textsc{VP9} supports several different bitrate modes:
 126
 127 \textit{mode:}
 128
 129 \begin{tabular}{p{6cm} p{10cm}}
 130         Constant Quantizer (Q) & Allows you to specify a fixed quantizer value; bitrate will vary \\
 131         Constrained Quality (CQ) & Allows you to set a maximum quality level. Quality may vary within bitrate parameters\\
 132         Variable Bitrate (VBR) & Balances quality and bitrate over time within constraints on bitrate\\
 133         Constant Bitrate (CBR) & Attempts to keep the bitrate fairly constant while quality varies\\
 134 \end{tabular}
 135
 136 CQ mode is recommended for file-based video (as opposed to streaming). The following FFMpeg command-line parameters are used for CQ mode:
 137
 138 \textit{FFMpeg}:
 139
 140 \begin{center}
 141         \begin{tabular}{{p{4cm} p{10cm}}}
 142         -b:v <arg> & Sets target bitrate (e.g. 500k)\\
 143         -minrate <arg> & Sets minimum bitrate.\\
 144         -maxrate <arg> & Sets maximum bitrate.\\
 145         -crf <arg> & sets maximum quality level. Valid values are 0-63, lower numbers are higher quality.\\
 146 \end{tabular}
 147 \end{center}
 148
 149 \textit{Note 1}: Bitrate is specified in kbps, or kilobits per second. In video compression a kilobit is generally assumed to be 1000 bits (not 1024).
 150
 151 \textit{Note 2:} Other codecs in FFMpeg accept the \textit{-crf} parameter but may interpret the value differently. If you are using \textit{-crf} with other codecs you will likely use different values for VP9.
 152
 153 \texttt{bitrate=1024k}\\
 154 \texttt{minrate=512k}\\
 155 \texttt{maxrate=1485k}\\
 156 \texttt{crf=32}
 157
 158 \textit{Tiling} splits the video into rectangular regions, which allows multi-threading for encoding and decoding. The number of tiles is always a power of two. 0=1 tile; 1=2; 2=4; 3=8; 4=16; 5=32\\
 159 \texttt{tile-columns=2}
 160
 161 (modified from {\small \url{https://trac.ffmpeg.org/wiki/EncodingForStreamingSites}})
 162
 163 To use a 2 second \textit{GOP} (Group of Pictures), simply multiply your output frame rate $\times$ 2. For example, if your input is \textit{-framerate 30}, then use \textit{-g 60}.\\
 164 \texttt{g=240}
 165
 166 number of \textit{threads} to use during encoding\\
 167 \texttt{threads=8}
 168
 169 \textit{Quality} may be set to good, best, or realtime\\
 170 \texttt{quality=good}
 171
 172 \textit{Speed}: this parameter has different meanings depending upon whether quality is set to good or realtime. Speed settings 0-4 apply for VoD in good and best, with 0 being the highest quality and 4 being the lowest. Realtime valid values are 5-8; lower numbers mean higher quality\\
 173 \texttt{speed=4}
 174
 175 \section{Details about .bcast5 Files}
 176 \label{sec:details_.bcast5_files}
 177
 178 The following extensions of files in \CGG{}'s \texttt{.bcast5} directory are explained below.
 179
 180 % Labeling requires a parameter with the longest word of the labels.
 181 \begin{labeling}{ladspa\_plugins{\dots}}
 182         \item [.dat] represent saved \textit{data} for perpertual sessions and color palettes; maybe others
 183         \item [.idx] original \textit{index} files that were created for loaded video to speed up seeking
 184         \item [.mkr] ffmpeg specific \textit{marker} index file that is created for each video to aid seeks
 185         \item [.rc] rc stands for \textit{run commands} so basically represents a script
 186         \item [.toc] toc is \textit{table of contents} file for MPEG video files (a type of index)
 187         \item [Cinelerra\_plugins] a list of the currently loaded plugins available in your \CGG{} session
 188         \item [Cinelerra{}\_rc] the user's preferences and settings are saved in this file to be used on startup
 189         \item [ladspa\_plugins{\dots}] list of currently loaded ladspa plugins for each version of \CGG{} being used
 190         \item [layout\#...\_rc] user-defined window layout setup with the layout name as part of the file name
 191         \item [.xml] used for various backups or for the current settings of plugins that you have used
 192         \item [.png] thumbnails of files in Resources so they do not have to be created over and over
 193 \end{labeling}
 194
 195
 196 %%% Local Variables:
 197 %%% mode: latex
 198 %%% TeX-master: "../CinelerraGG_Manual"
 199 %%% End: