parts/Tips.tex

   1 \chapter{Performance and other Tips}%
   2 \label{cha:performance_tips}
   3
   4 Performance of \CGG{} is related to the software and video format being used in conjunction with your computer system hardware -- the number of CPUs and its speed, I/O bus speed, graphics card, and amount of available memory. A basic, less powerful system will be sufficient for users working with audio only or lower resolution video formats.  Higher end computers will be needed when playing and working with higher resolution formats, like 1080p or 4k. Adding effects and multiple tracks will require more cpu, memory, and various other resources to
   5 perform at an acceptable level.
   6
   7 Perhaps the easiest method for determining if your performance could be improved is to look at the numerical value displayed as \textit{Framerate achieved}.  Good performance means that when \textit{Play every frame} is set
   8 in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab, the frames/second (frames per second or fps) in playback might be almost always at the maximum rate of your project setting and/or video frame rate. You can check this in \texttt{Settings $\rightarrow$ Preferences, Playback A}, by watching \textit{Framerate achieved} while playing forward.  A higher number is better, up to the format frame rate of the video.
   9
  10 Some computer hardware factors to consider for better performance are listed here:
  11 \begin{itemize}
  12         \item Multi-core and more SMP processors greatly improve speed by making use of threads. \CGG{} automatically uses the available threads, but some processes are single-threaded anyway and these become the weak link in the chain. The \textit{Project SMP cpus} parameter is used to limit the use of threads in the deconding (playback) stage only. It is better to lower the number of threads to leave some for the system and for the plugins in use.
  13         \item RAM: In video editing in general, the more RAM the better. A large amount of free memory available can help speed up operations by avoiding unnecessary disk swaps and keeping videos easily accessible in memory.
  14 You can optimize RAM utilization with \textit{Cache size} and \textit{Seconds to preroll render} parameters. See section \ref{sec:cache_and_preroll}. If there is limited RAM you must necessarily have a large swap partition. For system swap, (2 x RAM) GB seems to be more than sufficient. If the amount of memory being used by the program is close, then swap might save you but often if swapping becomes necessary, it presents more problems and you end up killing the \CGG{} process anyway.
  15         \item Video editing is almost always I/O intensive. To create longer running videos at high resolution
  16         you will want to have a lot of disk space available on fast access disks. The higher the transfer rate, the less slowdowns and problems. So a modern SSD is better than an old HDD.
  17         \item \CGG{} benefits from OpenGL hardware acceleration. A good graphics card is worthwhile to have.
  18         \item Multiple monitors really come in handy to increase productivity as you can see more information and
  19         in bigger windows so you do not have to keep moving windows around.
  20 \end{itemize}
  21 Besides the above hardware recommendations, this section covers tips for performance improvements and tips on how to perform some specific tasks, often for older media.
  22
  23 \section{Hardware video acceleration}%
  24 \label{sec:hardware_video_acceleration}
  25 \index{hardware!acceleration}
  26
  27 With certain newer, more powerful graphics boards and newer device drivers, there is the potential for enhanced \textit{decode} and \textit{encode} performance.   Decode refers to loading and playing video in \CGG{}. The GPU, Graphics Processing Unit, on the graphics board is accessed via one of the following libraries: vdpau or vaapi. The hardware acceleration done by the graphics card increases performance by activating certain functions in connection with a few of the FFmpeg decoders. This use makes it possible for the graphics card to decode video, thus offloading the CPU.  Decode operations are described here next.
  28 Encode refers to rendering video and is described at the end of this section
  29 under \hyperref[sub:gpu_hardware_encoding]{GPU hardware encoding}.
  30
  31 VDPAU, Video Decode and Presentation API for Unix, is an open source library to offload portions of the video decoding process and video post-processing to the GPU of graphics boards, such as Nvidia.  It may also apply to Nouveau and Amdgpu boards (by wrapper), but that has not been verified.
  32
  33 VA-API, Video Acceleration API, is an open source library which provides both hardware accelerated video encoding and decoding for use mostly with Intel (and AMD) graphics boards.
  34
  35 AppImage will probably not allow for either VDPAU or VA-API hardware acceleration because the
  36 computer where AppImage is created will not have the same graphics card and/or vaapi/vdpau
  37 libraries as yours.
  38 It is recommended for best results that you build \CGG{} on your specific computer as described in \ref{sec:single-user-build}.
  39 So in summary:
  40 \begin{itemize}
  41         \item Hardware acceleration, vaapi or vdpau, works the same running either the created binary or the created AppImage from that binary on that same computer.
  42         \item Hardware acceleration using an AppImage created on another computer running a different Operating System or even just a different level of Operating System, most likely will not work unless the user's computer just happens to have the same characteristics with respect to vaapi/vdpau as the computer where the AppImage was created.
  43 \end{itemize}
  44
  45 Currently only the most common codecs, such as MPEG-1, MPEG-2, MPEG-4, H.264 /MPEG-4 and h265 (hevc), are accelerated/optimized by the graphics card to play these particular video formats efficiently. The other formats are not optimized so you will see no performance improvement since the CPU will handle them as before, just as if no hardware acceleration was activated. There are many different graphics cards and computer systems setup, so you will have to test which specific settings work best for you.  So far this has been tested at least with Nvidia, Radeon, and Broadwell graphics boards on some AMD and Intel computers; depending on the graphics card, two to ten times higher processing speeds can be achieved.  However, most graphic operations are single-threaded so that performing the operations in the hardware may actually be slower than in software making use of multiple CPUs, which frequently multi-thread many operations simultaneously.
  46
  47 \subsection{GPU hardware decoding}%
  48 \label{sub:gpu_hardware_decoding}
  49 \index{hardware!decoding}
  50
  51 \begin{enumerate}
  52         \item Verify that you have installed \textit{libva-dev} or \textit{libva} on your operating system.
  53         \item Verify that you have installed \textit{libva-intel-driver} on your operating system
  54         \item Verify that you also have \textit{libvdpau-dev} or \textit{libvdpau} installed.
  55         \item Verify \texttt{Settings $\rightarrow$ Preferences, Playback} tab, Video Driver is set to\textit{ X11} -- or \textit{X11-OpenGL} if that   produces better results for your configuration.
  56         \item Before starting \CGG{}, you can set an environment variable that can be easily reversed and
  57         then, to run from the \CGG{} installed directory, key in:
  58 \end{enumerate}
  59
  60 \begin{lstlisting}[numbers=none]
  61 CIN_HW_DEV=vdpau ./cin  # for computers with Nvidia and some other graphics cards
  62 CIN_HW_DEV=vaapi ./cin  # mostly for computers with Intel or AMD specific graphics hardware
  63 \end{lstlisting}
  64
  65 If you find that the environment variable setting is advantageous for your CinGG usage and you want to always use it, you can add it in your \texttt{\$HOME} directory \texttt{.profile} file which takes effect every time you log in.  The line you would add would look something like this:
  66
  67 \begin{lstlisting}[numbers=none]
  68 export CIN_HW_DEV=vdpau
  69 or
  70 export CIN_HW_DEV=vaapi
  71 \end{lstlisting}
  72
  73 In addition for a computer with dual graphics cards, you can select your specific device with an environment variable
  74 to decode and encode.  For example:
  75 \begin{lstlisting}[numbers=none]
  76 CIN_DRM_DEC=/dev/dri/renderD129  CIN_DRM_ENC=/dev/dri/renderD128   ./cin
  77 \end{lstlisting}
  78 and substituting your specific location instead of /dev/dri/renderD129 or D128.
  79
  80 It might be more difficult to analyze problems as a result of using the GPU because of the wide variation in hardware.  When you do not set the \texttt{CIN\_HW\_DEV} environment variable, the code will work exactly as before since this feature is self-contained.
  81
  82 There is also a \texttt{Settings $\rightarrow$ Preferences, Performance} tab, \textit{Use HW device} flag
  83 with a pulldown to set up \textit{none, vdpau, vaapi,} or \textit{cuda}.  To ensure it takes effect, it is best to set it the way you want, quit out of \CGG{} and then restart.  Its current purpose is for flexibility, but there is a possibility that it might eventually take the place of \texttt{CIN\_HW\_DEV} -- both are not needed.
  84
  85 Precedence of the decode hardware acceleration settings are:
  86
  87 -- \texttt{yourfile.opts} is checked first so is of the highest priority; special .opts usage is described below
  88
  89 -- environment variable \texttt{CIN\_HW\_DEV} is checked next
  90
  91 -- preferences \textit{Use HW device} settings is of the lowest priority
  92
  93 \subsubsection*{Hardware decoding in \CGG{}}%
  94 \label{ssub:hardware_decoding_cinelerra}
  95 \index{appimage!vaapi/vdpau}
  96 There are 4 phases during \CGG{}’s handling of hardware acceleration. These first 2 steps occur just \textit{before} the first read.
  97
  98 \begin{enumerate}
  99         \item Check to see if Hardware Acceleration is enabled, usually indicated by \texttt{CIN\_HW\_ \_DEV} being set to
 100         vaapi or vdpau.  If enabled, try to activate the decode device, and if that fails revert to software.
 101         \item The next step is to send some data to decode to see if that works. If this does not work, you will see
 102         an error message of \textit{HW device init failed, using SW decode}.
 103 \end{enumerate}
 104
 105 \noindent These next 2 steps occur \textit{during} any read.  Now there is no turning back to software so if the hardware gets an error, that video will not be handled correctly.
 106
 107 \begin{enumerate} [resume]
 108         \item Read the media and send the raw stream data to the device for processing.
 109         \item Read the device to receive the decoded data, and convert it to the session color model.  If the GPU
 110         can not convert the data, you will see the error message of \textit{Error retrieving data from GPU to CPU}.
 111 \end{enumerate}
 112
 113 AppImage will probably not allow for either VDPAU or VA-API hardware acceler-
 114 ation because the computer where AppImage is created will not have the same
 115 graphics card and/or vaapi/vdpau libraries as yours. In other words:
 116
 117 \begin{itemize}
 118         \item Hardware acceleration, vaapi or vdpau, works the same running either the  created binary or the created AppImage from that binary on that same computer. See \nameref{sub:built_appimage_scratch}.
 119         \item Hardware acceleration using an AppImage created on another computer running a different Operating System or even just a different level of Operating System, most likely will not work unless the user’s computer just happens to have the same characteristics with respect to vaapi/vdpau as the computer where the AppImage was created.
 120 \end{itemize}
 121
 122 Due to these variations in user’s computer hardware configuration, it is often suggested that you refer to your startup window to check for error messages.   Since your situation is unique, the error may not have been seen by anyone else and is probably unknown/undocumented.
 123 \textcolor{red}{For debugging problems, modify in the \CGG{} ffmpeg subdirectory, the file:  \texttt{decode.opts}   by temporarily changing the line from \textit{loglevel =fatal} to \textit{loglevel =verbose} and restarting \CGG{}}.
 124
 125 \subsubsection*{Possible improvements or differences}%
 126 \label{ssub:possible_improvements_differences}
 127
 128 \begin{enumerate}
 129         \item The Frames Per Second (FPS) in playback might usually be at the maximum rate.  You can check
 130         this in \texttt{Settings $\rightarrow$ Preferences, Playback A}, looking at \textit{Framerate achieved}; the higher, the better.
 131         \item Percent of the CPU used should be less, thus saving more CPU for other operations.
 132         \item Some users get the the impression that playing seems smoother.
 133         \item The CPU fan noise may go down as the CPU is used less.
 134         \item The GPU graphics fan noise may go up as the GPU is used more.
 135 \end{enumerate}
 136
 137 Using the GPU is going to react differently depending on your hardware, software, and the number of files loaded. A good way to determine how well it is performing, is to watch the CPU load from another window running the command line routine \texttt{top}. Consider the following possibilities:
 138
 139 \begin{itemize}
 140         \item If you only use smaller videos occasionally and then use other codecs than the ones mentioned
 141         previously as being the optimized set, it is usually a better idea to stay with the default settings
 142         without all the hardware tests.
 143         \item If you have 4 cores or less, but a really good \textit{gaming card}, using vaapi/vdpau could be a big help.
 144         \item If you load only a couple of files, the GPU vaapi/vdpau should be faster depending on your graphics
 145         board and how capable it is.
 146         \item If you load 10 camera Mixers of H.264 format, it always seems to work a lot better playing them.
 147         \item If you have an epyc AMD chip with 128 CPUs and load 50 files, without vaapi/vdpau may be better.
 148 \end{itemize}
 149
 150 \subsubsection*{Special .opts file}%
 151 \label{ssub:special_opts_file}
 152 \index{hardware!special opts files}
 153
 154 The situation may arise where you have enabled hardware acceleration and after loading several files for a project, you find that a file had some kind of error resulting in a black video instead of an image or you see an error message pop up which states something like \textit{Error retrieving data from GPU to CPU} or \textit{err: Unknown error occurred}. Because the \texttt{CIN\_HW\_DEV} environment variable is either all or none, ordinarily in order to correct the non-working video you would have to turn off hardware acceleration for the entire project/session.  However, there is a way to continue working on your project without having to reload all of your files. You still use the environment variable and it will be effective for all of the formats it is able to handle, but you make an exception for any of the files that erred out. To do this you simply create a file in the same directory with the same name as the erring file with the different extension of .opts. The contents of this .opts file would just be the one line of:
 155
 156 \begin{lstlisting}[numbers=none]
 157 cin_hw_dev=none
 158 \end{lstlisting}
 159 Conversely, if you have a bunch of files in your project, like dnxhd format, that are not hardware accelerated, but you have an accompanying large file of type .mp4 for which you would like the hardware acceleration, you can leave the \texttt{CIN\_HW\_DEV} variable unset (that is, do not use it) and just create an .opts file containing the line:
 160
 161
 162 \begin{lstlisting}[numbers=none]
 163 cin_hw_dev=vdpau
 164 \end{lstlisting}
 165
 166 For example your file, \texttt{test.mp4}, would have a side-kick called \texttt{test.opts} that will use the GPU for decoding/playing and the other files will just use the software. This is of some advantage because the ones that can not use the GPU if the environment variable is enabled, will not have to even check which saves a minuscule bit of time.
 167
 168 It is important to note that if using the .opts file to override the default \texttt{ffmpeg / decode.opts} file, you will most likely see more warnings (not really errors) in the \CGG{} startup window because the standard \texttt{decode.opts} file has \textit{loglevel = fatal} whereas the default is \textit{loglevel = error}.  To avoid seeing all of the extra warnings, you can simply add the line   \textit{loglevel=fatal}   to your .opts file.
 169
 170 \subsubsection*{To verify hardware acceleration}%
 171 \label{ssub:verify_hardware_acceleration}
 172
 173 Probably the easiest way to tell if hardware acceleration is working, is just to look at the messages in the window from where you started Cin (not available if start using the application icon).  For example load a png, dnxhd, or some other non-supported format file and you will see messages similar to those below.  The line \textit{HW device init failed, using SW decode} indicates that the vdpau/vaapi HW (hardware) decode is not available so will use SW (software) decode instead.
 174
 175 \begin{lstlisting}[numbers=none]
 176 Failed to get HW surface format.
 177 HW device init failed, using SW decode.
 178 file:/tmp/media/aer_zypr.mp4
 179 err: Success
 180
 181 or
 182
 183 Decoder dnxhd does not support device type vdpau.
 184 HW device init failed, using SW decode.
 185 File:/tmp/media/test.gxf
 186 err: Success
 187
 188 or
 189
 190 HEVC with NVIDIA, VDPAU driver is buggy, skipping
 191 \end{lstlisting}
 192
 193 AppImage does not provide this capability. If you would like to see more information on what is occurring, you can modify in the \CGG{} ffmpeg subdirectory, the file:  \texttt{decode.opts}   by temporarily changing the line from \textit{loglevel =fatal} to \textit{loglevel =verbose} and restarting \CGG{}.  Then you will see messages in the startup window like:
 194
 195 \begin{lstlisting}[numbers=none]
 196 [AVHWDeviceContext @ 0x7fc9540be940] Successfully created a VDPAU device
 197 (NVIDIA VDPAU Driver Shared Library 390.116 Sun Jan 27 06:28:58 PST 2019) on X11 display :0
 198 [h264 @ 0x7fc950159380] Reinit context to 1920x1088, pix_fmt: vdpau
 199 [h264 @ 0x7fc92c3dd4c0] Reinit context to 1920x1088, pix_fmt: yuv420p
 200 \end{lstlisting}
 201
 202 Again, to measure the performance run \texttt{top} from another window to check the CPU usage which will go lower as more work is offloaded to the GPU graphics card instead (it may go down by 2 to 10 times) or check the \textit{Framerate achieved} while playing.
 203
 204 Some mixed preliminary results that have been reported are provided below.
 205
 206 \subsubsection*{Case 1:}%
 207 \label{ssub:case_1}
 208
 209 \noindent X11 Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab:
 210
 211 \begin{center}
 212         \begin{tabular}{lcr}
 213                 CIN\_HW\_DEV=off ./cin & &CPU $58\%$ \\
 214                 CIN\_HW\_DEV=vdpau ./cin & &CPU $32\%$ \\
 215                 CIN\_HW\_DEV=vaapi ./cin & &CPU $82\%$ \\
 216         \end{tabular}
 217 \end{center}
 218
 219 \noindent X11-OpenGL Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab:
 220
 221 \begin{center}
 222         \begin{tabular}{lcr}
 223                 CIN\_HW\_DEV=off ./cin & &CPU $48\%$ \\
 224                 CIN\_HW\_DEV=vdpau ./cin & &CPU $12\%$ \\
 225                 CIN\_HW\_DEV=vaapi ./cin & &CPU $80\%$ \\
 226         \end{tabular}
 227 \end{center}
 228
 229 \noindent Best is the least amount of CPU usage. Note that in this Case 1, using the X11-OpenGL video driver is
 230 better than using the X11 video driver.
 231
 232 \subsubsection*{Case 2:}%
 233 \label{ssub:case_2}
 234
 235 \noindent X11 Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab:
 236
 237 \begin{center}
 238         \begin{tabular}{lcr}
 239                 CIN\_HW\_DEV=off ./cin & &CPU $60\%$ \\
 240                 CIN\_HW\_DEV=vdpau ./cin & &CPU $11\%$ \\
 241                 CIN\_HW\_DEV=vaapi ./cin & &CPU $60\%$ \\
 242         \end{tabular}
 243 \end{center}
 244
 245 \noindent X11-OpenGL Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab:
 246
 247 \begin{center}
 248         \begin{tabular}{lcr}
 249                 CIN\_HW\_DEV=off ./cin & &CPU $67\%$ \\
 250                 CIN\_HW\_DEV=vdpau ./cin & &CPU $60\%$ \\
 251                 CIN\_HW\_DEV=vaapi ./cin & &CPU $67\%$ \\
 252         \end{tabular}
 253 \end{center}
 254
 255 \noindent Best is the least amount of CPU usage. Note that in this Case 2, using the X11 video driver is better
 256 than using the X11-OpenGL video driver.
 257
 258 Older graphics cards or non-performing graphics cards will probably bring only a small amount of improvement or no speed advantage at all.  You can check to see if vdpau is implemented for your specific Nvidia board at:
 259
 260 {\small \url{https://download.nvidia.com/XFree86/Linux-x86_64/304.137/README/supportedchips.html}}
 261
 262 And, you can see what your specific hardware and software might support by running either \texttt{vainfo}
 263 (available in the libva-utils package) or \texttt{vdpauinfo} (available in the vdpauinfo package) from the
 264 command line.  For example which "Profiles" your hardware can handle is listed in the output such as Main
 265 and High.  Partial examples of each are shown below.
 266
 267 \begin{lstlisting}[numbers=none]
 268 # vainfo
 269 vainfo: VA-API version: 1.4 (libva 2.4.0)
 270 vainfo: Driver version: Intel i965 driver for Intel(R) Broadwell - 2.4.0.pre1 (2.3.0-11-g881e67a)
 271 vainfo: Supported profile and entrypoints
 272 VAProfileMPEG2Simple
 273 ...
 274 VAProfileH264Main
 275 VAProfileH264High
 276 ...
 277 VAProfileH264MultiviewHigh
 278 VAProfileH264StereoHigh
 279 ...
 280 VAProfileVC1Simple
 281 ...
 282 VAProfileVP8Version0_3
 283 \end{lstlisting}
 284
 285 \begin{lstlisting}[numbers=none]
 286 # vdpauinfo
 287 display: :0   screen: 0
 288 API version: 1
 289 Information string: G3DVL VDPAU Driver Shared Library version 1.0
 290 ...
 291 Decoder capabilities:
 292
 293 name                        level macbs width height
 294 ----------------------------------------------------
 295 MPEG1                          --- not supported ---
 296 MPEG2_SIMPLE           3 65536  4096  4096
 297 MPEG2_MAIN               3 65536  4096  4096
 298 H264_BASELINE         52 65536  4096  4096
 299 H264_MAIN                  52 65536  4096  4096
 300 H264_HIGH                  52 65536  4096  4096
 301 VC1_SIMPLE                 1 65536  4096  4096
 302 VC1_MAIN                     2 65536  4096  4096
 303 VC1_ADVANCED         4   65536  4096  4096
 304 \end{lstlisting}
 305
 306 One last item of note, \textit{nvdec} is also enabled in the ffmpeg build, but at this time it is not known how this decode option on Nvidia graphics boards works or does not work in conjunction with vdpau.
 307
 308 \subsection{GPU hardware encoding}%
 309 \label{sub:gpu_hardware_encoding}
 310 \index{hardware!encoding}
 311
 312 Encoding using hardware acceleration of your graphics board GPU is
 313 included in \CGG{} but it is of limited availability and works only
 314 with a specific set of hardware graphics boards, a certain level of
 315 graphics driver versions and only with certain ffmpeg formats.  The
 316 encoding is done via vaapi (libva installed), which is known to work
 317 with Intel HD graphics boards and some others or via nvenc as
 318 developed by Nvidia for Nvidia graphics boards.
 319
 320 \subsubsection*{Broadcom, Intel HD, AMD}%
 321 \label{ssub:broadcom_intel_amd}
 322 \index{hardware!vaapi}
 323
 324 To use hardware acceleration for rendering (that is, encoding) you do not have to set a preference or an environment variable, as was required for decoding.  To use this feature you use an ffmpeg render options file which specifies a vaapi codec, such as h264\_vaapi.  You must include this line in that options file to trigger the hardware probe: \qquad      \texttt{CIN\_HW\_DEV=vaapi}
 325
 326 There are currently 4 options files available in the Render menu already set up for you that you see when you select the Video wrench and use the down arrow on the first line in the menu.  These are:
 327
 328 \begin{description}
 329         \item[h264\_vaapi.mp4] known to work on Intel computer with Intel Broadwell graphics driver
 330         \item[mpeg2\_vaapi.mp4] known to work on Intel computer with Intel Broadwell graphics driver
 331         \item[mjpeg\_vaapi.mp4] error message of \textit{open failed with mjpeg\_vaapi$\dots$} on above computer
 332         \item[hevc\_vaapi.mp4] error message of \textit{open failed with hevc\_vaapi$\dots$} on above computer
 333 \end{description}
 334 Other option files can be added as needed for your specific hardware if it is known to work for you, such as VP8 and VP9.  An example of the included \CGG{}’s \texttt{ffmpeg/video/h264\_vaapi.mp4} file (figure~\ref{fig:render-vaapi}):
 335
 336 \begin{figure}[htpb]
 337         \centering
 338         \includegraphics[width=1.0\linewidth]{render-vaapi.png}
 339         \caption{Render menu setup to encode using GPU with vaapi}
 340         \label{fig:render-vaapi}
 341 \end{figure}
 342
 343 \begin{lstlisting}[numbers=none]
 344 mp4 h264_vaapi
 345 cin_hw_dev=vaapi
 346 profile=high
 347 \end{lstlisting}
 348
 349 According to an online wiki, hardware encoders usually create output of lower quality than some software encoders like x264, but are much faster and use less CPU. Keep this in mind as you might want to set a higher bitrate to get output of similar visual quality.
 350
 351 Results of a particular test case performed on a Intel, 4-core computer, with Broadwell Graphics using an mp4 input video/audio file with dimensions of
 352 $1440x1080 / 29.97fps$ is shown next (note, filename is \texttt{tutorial.mp4}).  This may very well be a \textit{best case} scenario!  But clearly, at least on this computer with only 4 cores, the hardware acceleration seems to be quite advantageous.  A comparison of the 2 output files
 353 using \texttt{ydiff} as described in the Appendix (\ref{sec:ydiff_check_results}) shows no obvious defects.
 354
 355 \begin{center}
 356         \begin{tabular}{l|cccc}
 357                 &CPU usage & Render Time & File Size & File \\
 358                 \hline
 359                 none & 388\% &100 secs &36,862,542 & h264.mp4 \\
 360                 vaapi & 150\% & 19 secs & 74,522,736 & h264\_vaapi.mp4 \\
 361         \end{tabular}
 362 \end{center}
 363
 364 \subsubsection*{Nvidia graphics boards}%
 365 \label{ssub:nvidia_graphics_card}
 366 \index{hardware!nvenc}
 367
 368 To use hardware acceleration for rendering (that is, encoding) you do not have to set a preference or an environment variable, as was required for decoding.  To use this feature you use an ffmpeg render options file which specifies the nvenc codec, either \texttt{h264\_nvenc.mp4} or \texttt{nvenc.mp4}.  There are several requirements in order for this to work on your computer as listed here:
 369
 370 \begin{enumerate}
 371         \item Nvidia graphics board at or above a certain hardware level.  For h265, newer boards are required.
 372         \item Software drivers for your graphics board must be installed on your computer.
 373         \item The driver must support at least API version 9.0 -- minimum required Nvidia driver for nvenc is
 374         390.25 or newer.  You will see error messages on the startup window if you are on lower versions.
 375 \end{enumerate}
 376
 377 If you try to render using\texttt{ h264/h265\_nvenc.mp4} formats and do not have an Nvidia graphics card or this feature was not built in, you will see in the window from where you started \CGG{}, the error message: \qquad \textit{Cannot load libcuda.so.1}
 378
 379 A small test using 2 minutes from the 4k version of Big Buck Bunny shows using nvenc can be about 4 times faster.  The test was done on a 4 core Intel laptop with an Nvidia 950M graphics board.
 380
 381 \begin{center}
 382         \begin{tabular}{l|cccl}
 383                 &CPU usage & Render Time & File Size & File \\
 384                 \hline
 385                 none & 388\% &20 mins 18 secs & 156,517,069 & h264.mp4 \\
 386                 nvenc & 252\% & 5 mins 44 secs & 42,052,920 & h264\_nvenc.mp4 \\
 387         \end{tabular}
 388 \end{center}
 389
 390 Of note in this test, 388\% CPU usage with only 4 cores shows that there is probably slow down because there is no more CPU power available. Therefore, using the GPU hardware acceleration with nvenc provides a significant speed-up.  Also, note the larger file size without making use of the GPU – this probably indicates that there is a big difference in bitrate or quality parameter settings used in the options file and this should be taken into consideration.
 391
 392 \subsubsection*{Important Tip}%
 393 \label{ssub:important_tip}
 394
 395 There is one last potentially significant graphics speedup when using the X11-OpenGL driver for users with Nvidia graphics boards who are seeing frames/sec achieved lower than what the video format is set to.  You may want to disable \textit{sync to vblank} (an option for OpenGL) in NVIDIA X Server Settings for the proprietary drivers.  This could increase your frames per second on playback.
 396
 397 \subsection{Effects (OpenCL, Cuda)}%
 398 \label{sub:effects_opencl_cuda}
 399 \index{openCL}
 400 \index{CUDA}
 401
 402 CUDA® is a parallel computing platform / programming model developed by Nvidia that provides big increases in computing performance through use of the GPU. It was first introduced in about 2006 for applications in computationally intense fields such as astronomy, biology, chemistry, and physics.
 403
 404 At the time this was written, the use of Cuda is not going to improve the playing and rendering of video in \CGG{} except in the case where you use a specific Cuda-enabled plugin that is computationally intense -- sadly, most of what Cin does, Cuda will not help.  Cuda is mostly a \textit{block oriented algorithm} which works well for such things as \textit{a flock of birds all flying next to each other}.
 405
 406 The same as for vaapi and vdpau, you can enable Cuda in the:\\
 407 \texttt{ Settings $\rightarrow$ Preferences, Performance} tab, \textit{Use HW Device}\\
 408 but it will not affect anything unless you have Cuda installed on your system and have built \CGG{} yourself with Cuda build enabled.  To install it on your computer, you will need to do the following:
 409
 410 \begin{enumerate}
 411         \item Make sure you have the Nvidia proprietary library drivers for your graphics board already installed and up to date.
 412         \item Go to the Nvidia Cuda development website and choose one of the available operating system’s
 413         such as Fedora, OpenSuse, CentOS, Ubuntu, $\dots$ at   {\small \url{https://developer.nvidia.com/}}
 414         \item You will be installing repositories by package -- this will be around 3 GB.
 415         \item Also, install the Fusion repo, although it is unknown if necessary or not.
 416 \end{enumerate}
 417
 418 There is a very good set of directions on the website to just follow.  Once you have installed the Cuda software on your computer, you must build \CGG{} yourself -- the default flag for a build in the configure script for cuda is \textit{auto}.  For Arch, and possibly other distros, you may have to supply the CUDA\_PATH if it is not in the standard place.  This would be
 419 something like:
 420
 421
 422 \begin{lstlisting}[numbers=none]
 423         env CUDA_PATH=/opt/cuda
 424 OR if using the bash shell:
 425         export CUDA_PATH=/opt/cuda
 426 \end{lstlisting}
 427 For all distros you will need to add to the ./configure line in your build script, the following:
 428
 429
 430 \begin{lstlisting}[numbers=none]
 431         --with-cuda
 432 so your configure line will look something like this:
 433         ./configure --with-single-user --with-booby --with-cuda
 434 \end{lstlisting}
 435
 436 There are currently 2 available plugins for \textit{show and tell} that take advantage of the hardware acceleration of Cuda -- \textit{N\_Body} and \textit{Mandelbrot} (see \nameref{sec:cuda_plugins}).
 437
 438 An error you may see on your \CGG{} startup window when you have Cuda installed and try to run one of the 2 plugins is \textit{cudaErrorInsufficientDriver}.  This indicates CUDA 10 (the current version at the time of this writing) is not compatible with the driver version on your computer.  You can either:
 439
 440 \begin{enumerate}
 441         \item Upgrade the driver if your board supports newer nvidia builds.
 442         \item downgrade the cuda development package to a version that works for your board.
 443 \end{enumerate}
 444
 445 \subsection{Additional topics on hardware acceleration}%
 446 \label{sub:final_note_on_acceleration}
 447
 448 In wrapping up this Hardware Acceleration section, you may want to refer to the following to determine the current supported formats:
 449
 450 {\small \url{https://wiki.archlinux.org/index.php/Hardware_video_acceleration}}
 451
 452 \section{Optimized Playback -- X11 Direct}%
 453 \label{sec:optimized_playback}
 454 \index{playback -X11 direct}
 455
 456 Normally, when \CGG{} reads a video frame, it is copied into a \textit{Vframe}.  This frame may also need other actions performed on it, such as a color model change.  In addition, ffmpeg and libzmpeg \textit{can\_scale\_input}.  So the read can be color transformed and scaled just by asking the library to do that.  This means that if the compositor is in a \textit{good} state with no zoom, the VFrame read can be done in the fastest render color model, and already scaled to the correct size for the compositor.  In reality, this is not what you need for editing, but quite often the \textit{virtualconsole} is not used because the render is media only -- that is \textit{just data}.  If no data transforms are needed and the input scaling can be done, the vrender program detects this, and tells the codec to transmit the data in a compatible way to the compositor canvas. This is the \textit{X11 direct} data path.
 457
 458 With the X11 video driver choice, large format files such as 4K, will playback faster than either X11-XV or X11-OpenGL.  However, you still have the option to turn off the X11 direct data path if you use
 459 \texttt{Settings $\rightarrow$ Preferences, Playback A} tab set video driver to X11 and uncheck \textit{use direct X11 render if possible}.
 460
 461
 462 \section{Proxy Settings and Transcode}%
 463 \label{sec:proxy_settings}
 464
 465 Information on proxies to reduce required CPU for less powerful computers is in the section \nameref{sec:proxy}.
 466
 467 Information on transcode which is used to provide keyframes to make the video seekable is in the section \nameref{sec:transcode}.
 468
 469
 470
 471 \section{Cache size and Seconds to preroll render}%
 472 \label{sec:cache_and_preroll}
 473 \index{cache}
 474
 475 \textit{Cache size} in \texttt{Settings $\rightarrow$ Preferences, Performance} tab is used to store images on the timeline.  One 1080p frame uses about 10 MB.  The default setting is 256 and this is enough for testing and running.  However, why not use more memory if it is available.   To experiment for testing a good number tuned to the way you use your computer, set the cache to 0, start up \CGG{}, load a typical media file, play it and run \textit{top} on the command line in another window to see how much memory is being used.  In the \textit{top} display, look at \textit{free} memory.  Whatever your computer is not using, is a good number to use for cache.  If you start other programs, or change the design of the session so that it uses a lot of frame storage, you may need to experiment again later and resize accordingly. The system keeps all requested data cached until it is replaced by other data or you reboot your PC. Reboot if you want to clear the cache.
 476
 477 \textit{Seconds to preroll render} in \texttt{Settings $\rightarrow$ Preferences, Performance} tab are used to increase the amount of frames (which are calculated in advance) at the time of their use. The default setting is 0.5 sec but you can increase it to 1.0 sec to improve smoothness in the timeline. Higher values are always less effective.
 478
 479 \section{Tips for Improving Smaller Computers Use}%
 480 \label{sec:tips_improving_smaller_computers}
 481
 482 A list of items to check for smaller computers that will help to use less cpu/memory/resources follows:
 483
 484 \begin{itemize}
 485         \item For large media files, use proxy to do your main editing.
 486         \item In \texttt{Settings $\rightarrow$ Preferences, Appearance} tab, uncheck \textit{Use thumbnails in resource window}.
 487         \item In \texttt{Settings $\rightarrow$ Preferences, Appearance} tab, uncheck \textit{Autocolor assets}.
 488         \item  Speed-up certain time-consuming FFmpeg plugins through use of a carefully selected \texttt{.opts} file. See \nameref{sub:speedup_ffmpeg_plugin_opts}
 489         \item For large media files, in \texttt{Settings $\rightarrow$ Preferences, Playback A}, Video Driver set \textit{use direct X11 render if possible}.
 490         \item For the Video Driver in \texttt{Settings $\rightarrow$ Preferences, Playback A}, if using a good graphics card, choose \textit{X11-OpenGL}.
 491         \item Set \textit{CIN\_HW\_DEV=vdpau} or \textit{vaapi} to use the graphics GPU for certain ffmpeg media decoding.
 492         \item If you have multiple cpus or multiple computers, even if slow, take advantage of using \textit{Render Farm}.
 493         \item When editing, \textit{background rendering} causes temporary output to be rendered constantly while the
 494         timeline is being modified. The temporary output is displayed during playback whenever possible so
 495         it does not have to be recalculated -- very useful for transitions and previewing effects that are slow.
 496         \item In  \texttt{Settings $\rightarrow$ Preferences, Playback A}, uncheck \textit{Play every frame} which means frames will be skipped as playback of the video falls behind.
 497         \item Adjust \textit{Cache size} in \texttt{Settings $\rightarrow$ Preferences, Performance} tab, to not exhaust the memory and yet still provide decent playback.
 498 \end{itemize}
 499
 500 \section{General Crash Handling Tips}%
 501 \label{sec:general_crash_tips}
 502 \index{crash handling tips}
 503
 504 This section is a handy guide for describing various kinds of software computer system failures.  Only some of these various lockups or crashes can be dealt with.  Hopefully, it will help to have some hints to know what kind of failure it is, or to save your work or to avoid future problems.  For most of this, your user name must be root, although you can certainly try to see if it works for you when not root.
 505
 506 \begin{description}
 507         \item[System lockups:] When the system locks up, it is usually a system problem.  Normally an application program cannot lock up the system.  It is a major goal of system design to prevent an application (app) from failing a system interface.  This does not mean an app can not cause a system lockup, but it is unusual.
 508         \item[\CGG{} crash:] This is covered in  \hyperref[cha:crash_dumps_analysis]{Crash Dumps for Analysis}.  Just a reminder that for best results you should be root and by providing a crash dump and as much other information as possible, you will be helping the developer to analyze the problem and fix it so that it can be avoided in the future.
 509         \item[X Server crash:] Keyboard does not respond, screen is frozen, caps lock may operate LED light.  Sometimes using Ctrl-Alt-F1 $\dots$ Ctrl-Alt-F7 (etc.) will allow you to regain control of a VT console.  You can use this to login and check logs: eg. \texttt{/var/log/Xorg.0.log}, \textit{dmesg}, \textit{journalctl} $\dots$ etc.  If you have another computer, make sure a terminal server is configured (for example: rsh, ssh, or telnet), then remote login via this other computer and check the logs.  Most important is to immediately note the current software state, and the very last thing that preceded the crash, i.e. last button click, last keystroke, $\dots$ or whatever.
 510         \item[Kernel crash:] The machine goes completely dead.  The keyboard caps lock LED will probably be flashing.  Most likely the only way to see anything after the kernel crashes is to use a serial port console log and usually kdb, the kernel debugger, and special cabling.  This requires a lot of setup, and is normally reserved for experts.  Login from another computer will not work.  Pinging the ip address will not respond since the network stack is part of the kernel.  There are some virtual machine setups that will let you debug a \textit{guest} kernel, but this also requires a lot of setup, and affects which kernel is currently under test.  The kdb route is preferable.
 511         \item[Keyboard grabs, Server grabs, and Deadlocks:] A grab is an X-server state where all events are forced to just one window event stream.  This forces the user to respond to the dialog.  Things seems to be working, but no keypresses do anything useful. The system clock and other programs will still be working.  The network will work for remote logins. Grabs can be canceled if the \texttt{/etc/X11/xorg.conf} X config contains special setup as shown below:
 512 \end{description}
 513
 514 \begin{lstlisting}[numbers=none]
 515 Section "ServerFlags"
 516         Option      "HandleSpecialKeys" "Always"
 517         Option      "AllowDeactivateGrabs" "True"
 518         Option      "AllowClosedownGrabs" "True"
 519 EndSection
 520
 521 Section "InputDevice"
 522         Identifier  "Keyboard"
 523         Driver      "evdev"
 524         ...
 525         Option "XkbOptions" "terminate:ctrl_alt_bksp"
 526         Option "XkbOptions" "grab:break_actions"
 527 EndSection
 528 \end{lstlisting}
 529
 530 or to \texttt{\$HOME/.xinitrc}, add:
 531
 532 \begin{lstlisting}[numbers=none]
 533 #  xkb terminate/grab actions disabled in xorg.conf, use:
 534 setxkbmap -option "grab:break_actions"
 535 setxkbmap -option "terminate:ctrl_alt_bksp"
 536 ctrl-alt-bksp = terminate the X-server, may restart automatically
 537 \end{lstlisting}
 538
 539
 540 Modal forms (always on top, and usually ptr/kbd grab) dialog boxes can lock a system by putting a form over another form holding a grab.  This means the form that needs input may never get any because you can not get to it, and the result is a deadlock.  Usually you will have to restart X (Ctrl-Alt-Bksp).
 541
 542 \begin{description}
 543         \item[Window Manager issues:] The \textit{desktop} window manager can intercept and modify all kinds of user input.  Mostly, this is a good thing, but can be a nuisance.  If user keypresses can be programmed to trigger actions, then they may be useful to send \texttt{KILL} or \texttt{INTR} to an app that seems to be holding X's attention.  For example:
 544         \begin{lstlisting}[numbers=none]
 545         killall -INTR cinelerra,
 546         killall -9 cinelerra,
 547         killall X,
 548         # but you must run as root to be able do this
 549         \end{lstlisting}
 550         The ALT and META keys may be intercepted by the window manager, and this can cause unexpected interface operations.
 551 \end{description}
 552
 553 \section{Tips for Specific Operations}%
 554 \label{sec:tips_specific_operations}
 555
 556 \subsection{Generating a 440 Hz tone}%
 557 \label{sub:generating_440_tone}
 558
 559 To create a specific 440 Hz tone, follow these steps.  You can vary the length, use more channels, or change the frequency to a different desired value (figure~\ref{fig:aeval}).
 560
 561 \begin{figure}[htpb]
 562         \centering
 563         \includegraphics[width=1.0\linewidth]{aeval.png}
 564         \caption{Use Audio$\rightarrow$Render effect to set render parameter values and then that effect can be varied.}
 565         \label{fig:aeval}
 566 \end{figure}
 567
 568 \begin{enumerate}
 569         \item Make sure there is an armed audio track on the timeline, get into Cut and Paste mode, and highlight
 570         a selection or define In/Out points where you want to insert the audio tone.
 571         \item Go to \texttt{Audio $\rightarrow$ Render effect}.  Rendered effect usage is described in \hyperref[sec:rendered_effects]{Effect Plugins}. This brings up a menu where you will select the desired effect which in this case is \textit{F\_aeval}.  Also Select a file to render to, a File Format, and Insertion strategy of Paste at insertion point.
 572         \item Click on the green OK checkmark which will popup the F\_aeval effect so that you can set the
 573         parameters.
 574         \item Highlight the \textit{exprs} option and key in a specific audio filter expression which for 440 Hz would be:
 575         $\sin(2\pi t\times440)$.  Then hit the Apply button.
 576         \item Next when you hit the green OK checkmark on the \CGG{}: Effect Prompt popup, you will have
 577         your 440 Hz tone on the timeline plus in the select file that you chose to render it to.
 578         \item To use 2 channels instead of 1, in the F\_aeval menu highlight the \textit{channel\_layout} option and change
 579         that to 1C|2C instead of the usual default of 1C.
 580 \end{enumerate}
 581
 582 \subsection{Camera supplied LUTs}%
 583 \label{sub:camera_supplied_luts}
 584 \index{LUT}
 585
 586 A LUT, acronym for Look-Up Table, is a mathematically precise way of taking specific RGB image values from a source image and modifying them to new RGB values by changing the hue, saturation and brightness values of that source image. In other words, LUTs are used to map one color space to another.  Some high-end cameras supply a .cube file to use as input. There are several different ffmpeg plugins included with CinGG for using Lut's.  These are:
 587
 588 \begin{description}
 589         \item[F\_lut:] Compute and apply a lookup table to the RGB/YUV input video.
 590         \item[F\_lut1d:] Adjust colors using a 1D LUT "file" input.
 591         \item[F\_lut3d:] Apply a 3D LUT "file" to an input video.
 592         \item[F\_lutrgb:] Compute and apply a lookup table to the RGB input video.
 593         \item[F\_lutyuv:] Compute and apply a lookup table to the YUV input video.
 594 \end{description}
 595
 596 For example, to use a 3dlut simply load your video, drop the F\_lut3d plugin on that track, and bring up the lut3d controls window, highlight the \textit{file} option, key in your file name (with path), and hit Apply to have the lut take effect.  To easily adjust, move the \textit{fader} slider in the patchbay for that video track. Only F\_lut1d and F\_lut3d allow for a file input and these usually are files with the .cube extension.
 597
 598 \subsection{Encoding into Dolby Pro Logic}%
 599 \label{sub:encoding_dolby_pro_logic}
 600 \index{dolby pro logic}
 601
 602 Dolby pro logic is an easy way to output 6 channel audio from a 2-channel soundcard with degraded but useful results. Rudimentary Dolby pro logic encoding can be achieved with usage of some effects.
 603
 604 \begin{enumerate}
 605         \item First, create the front left and right channels. Create 2 audio tracks, each carrying either the left or
 606         right channel. Pan the left channel to the left and the right channel to the right with the pan control.
 607         \item Now create the rear left and right channels. Create another 2 audio tracks as above -- the left channel
 608         panned left and the right channel panned right. Then apply invert audio to both new channels and
 609         the signals will come out of the rear speakers.
 610         \item Next, create the center channel by creating a single audio track with monaural audio from a
 611         different source. Center it with the pan control and the signal will come out of the center speaker.
 612 \end{enumerate}
 613
 614 \begin{itemize}
 615         \item If a copy of the signal in the back speakers is desired in any single front speaker, the signal in the back
 616         speakers must be delayed by at least $0.05$ seconds and a single new track should be created. Pan the
 617         new track to orient the signal in the front speakers.
 618         \item If the same signal is desired in all the speakers except the center speaker, delay the back speakers by
 619         $0.5$ seconds and delay either the front left or front right by $0.2$ seconds.
 620         \item If you want to hear something from the subwoofer, create a new track, select a range, drop a
 621         synthesizer effect, and set the frequency below $60 Hz$. The subwoofer merely plays anything below
 622         $60Hz$ or so.
 623 \end{itemize}
 624
 625 Other tricks you can perform to separate the speakers are parametric equalization to play only selected ranges of frequencies through different speakers and lowpass filtering to play signals through the subwoofer.
 626
 627 \subsection{Improving Analog TV Quality}%
 628 \label{sub:improving_tv_quality}
 629
 630 The picture quality on analog TV is not always good but you can modify parameters in \CGG{} to make it look more like it did in the studio.
 631
 632 First, when capturing the video, capture it in the highest resolution possible. For Europeans this would be $720\times576$ and for North Americans, $720\times480$. Do not adjust the brightness or contrast in the recording monitor, but you might want to max out the color. Capture the video using MJPEG or uncompressed Component Video if possible; if not possible, then capture it using JPEG preferably or RGB if that is all that will work.  Now on the timeline use \texttt{Settings $\rightarrow$ Format} to set a YUV colorspace, drop a \textit{Downsample} effect on the footage and set it as follows:
 633
 634 \begin{lstlisting}[numbers=none]
 635 Horizontal:                                     2
 636 Horizontal offset:      0
 637 Vertical:                                               2
 638 Vertical offset:                0
 639          red
 640 x  green
 641 x  blue
 642          alpha
 643 \end{lstlisting}
 644
 645 Use the Camera in the compositor to shift the picture up or down a line to remove the most color interference from the image. If you have vertical blanking information or crawls which constantly change in each frame, block them out by using a Mask. This improves compression ratios.   More invasive quality improvement techniques involve removing the interlace via deinterlacing.
 646
 647 \subsection{Remove Interlacing}%
 648 \label{sub:remove_interlacing}
 649 \index{interlacing}
 650
 651 Interlacing often exists on older video sources, such as camcorders, and was previously used in broadcast television. Playing this video results in jagged images on a computer monitor, but with \CGG{} you can use deinterlacing effects to solve this.  After some experimentation, it has been determined that the FFmpeg \textit{F\_kerndeint} plugin seems to produce the best results with the least amount of fiddling.  But some of the parameters described next are pertinent to other potential plugin usage.
 652
 653 \begin{description}
 654         \item[Line Doubling:] done by the \textit{Deinterlace} effect when set to \textit{Odd} lines or \textit{Even} lines.  When applied to a track it reduces the vertical resolution by $\frac{1}{2}$ and gives you progressive frames with stairstepping. This is only useful when followed by a scale effect which reduces the image to half its size.
 655         \item[Line averaging:] the \textit{Deinterlace} effect when set to \textit{Average even} lines or \textit{Average odd} lines does exactly what line doubling does except instead of making straight copies of the lines, it makes averages of the lines. This is actually useful for all scaling.
 656         \item[Inverse Telecine:] this is the most effective deinterlacing tool when the footage is an NTSC TV broadcast of a film. It is described in Effect Plugins (\ref{sub:inverse_telecine}).
 657         \item[Time base correction:] the previously discussed three tools either destroy footage irreversibly or do not work at times. Time base correction may be a better tool to use because it leaves the footage intact. It does not reduce resolution, perceptually at least, and does not cause jittery timing.
 658         \item[Frames to Fields effect:] converts each frame to two frames, so it must be used on a timeline whose project frame rate is twice the footage's frame rate. In the first frame it puts a line-averaged copy of the even lines. In the second frame it puts a line-averaged copy of the odd lines. When played back at full framerate it gives the illusion of progressive video with no loss of detail. This effect can be reversed with the \textit{Fields to Frames} effect, which combines two frames of footage back into the one original interlaced frame at half the framerate. However, keep in mind that Frames to Fields inputs frames at half the framerate as the project. Effects before Frames to Fields process at the reduced framerate.  The output of Frames to Fields can not be compressed as efficiently as the original because it introduces vertical twitter and a super high framerate. Interlaced $29.97$ fps footage can be made to look like film by applying Frames to Fields and then reducing the project frame rate of the resulting $59.94$ fps footage to $23.97$ fps. This produces no timing jitter and the occasional odd field gives the illusion of more detail than there would be if you just line averaged the original. It is described in Effect Plugins (\ref{sub:frames_to_fields}).
 659         \item[HDTV exceptions:] $1920\times1080$ HDTV is encoded in a special way. If it is a broadcast of original HDTV film, an inverse telecine works.  But if it is a rebroadcast of a $720\times480$ source, you need to use a time base and line doubling algorithm to deinterlace it.
 660 \end{description}
 661
 662 \subsection{Making video look like film}%
 663 \label{sub:making_video_look_film}
 664
 665 With an older camcorder video which has low quality video, you can improve the results by turning it into progressive 24 fps output as close as possible.  Only do this for low quality video.
 666
 667 \begin{enumerate}
 668         \item Set project framerate to twice the video framerate.
 669         \item Apply a \textit{Sharpen} effect. Set it to sharpness: 25, no interlacing, and horizontal only.
 670         \item Drop a \textit{Frame to Fields} effect on the same track. Set Average Empty Rows to on and play through
 671         the video a few times to figure out which field is first. If the wrong field is first, the motion is shaky.
 672         Any editing in the doubled frame rate may now damage the field order. It is not clear which is the
 673         easiest way to support warnings for field glitches but you should go back to the normal framerate to
 674         do editing or play test to make sure the fields are right.
 675         \item Render just the video to the highest quality file possible.
 676         \item Import the video back to a new track. Set the project framerate to 24. The new track should now
 677         look more like a file with sharper images than the original footage.
 678 \end{enumerate}
 679
 680 This entire procedure could be implemented in one non-realtime effect, but the problem with that is you will most often want to keep the field based output and the 24 fps output for historical purposes. A non-realtime effect would require all that processing just for the 24 fps copy.
 681
 682 \subsection{Clearing out haze}%
 683 \label{sub:clearing_out_haze}
 684
 685 If you photograph a lot of haze instead of blue sky, these horizon shots will usually need more depth. You can use the \texttt{gradient} effect to improve your video. Drop the gradient effect on hazy tracks and set the following parameters:
 686
 687 \begin{lstlisting}[numbers=none]
 688 Angle:                          0
 689 Inner radius: 0
 690 Outer radius: 40
 691 Inner color:  blue 100% alpha
 692 Outer color:  blue 0% alpha
 693 \end{lstlisting}
 694
 695 It is important to set the $0\%$ alpha color to blue even though it is $0\%$ alpha. The color of the outer alpha is still interpolated with the inner color. This is a generally applicable setting for gradient. Some scenes may work better with orange or brown for an evening feel.
 696
 697 \subsection{Making a ringtone for a cell phone}%
 698 \label{sub:make_ringtone_phone}
 699
 700 \begin{enumerate}
 701         \item Go to \texttt{File $\rightarrow$ Load files$\dots$} and load a sound file with Insertion strategy: \textit{Replace current project}.
 702         \item Go to \texttt{Settings $\rightarrow$ Format }change \textit{Channels} to 1 and \textit{Samplerate} to 16000 or 22050.
 703         \item Highlight a region of the timeline to use for the ringtone. To improve sound quality on the cell
 704         phone, you need the maximum amplitude in as many parts of the sound as possible.
 705         \item Right click on track Audio 1 and select \textit{Attach effect}. Highlight the \textit{Compressor} effect and hit
 706         Attach in the attachment popup.
 707         \item Make sure the insertion point or highlighted area is in the region with the Compressor effect.
 708         \item Right click on track Audio 2 and select \textit{Attach effect}.
 709         \item Highlight Audio 1 Compressor and hit Attach.
 710         \item Click the Audio 1 Compressor's magnifying glass to bring up the compressor GUI.
 711         \item Set the following parameters:
 712         \begin{lstlisting}[numbers=none]
 713         Reaction secs: -0.1
 714         Decay secs: 0.1
 715         Trigger Type: Total
 716         Trigger: 0
 717         Smooth only: No
 718         \end{lstlisting}
 719         \item Click Clear to clear the graph. Click anywhere in the grid area and drag a new point to 0 Output
 720         and -50 Input. The graph should look similar to the figure~\ref{fig:ringtone}.
 721         \item Go to \texttt{File $\rightarrow$ Render}. Specify the name of an mp3 file to output to. Set the file format to MPEG
 722         Audio. Click the wrench for Audio and set Layer to III and Kbits per second to 24 or 32. Check
 723         Render audio tracks and uncheck Render video tracks. Hit OK to render the file.
 724 \end{enumerate}
 725
 726 \begin{figure}[htpb]
 727         \centering
 728         \includegraphics[width=0.8\linewidth]{ringtone.png}
 729         \caption{Using the Compressor plugin graph to create a ringtone}
 730         \label{fig:ringtone}
 731 \end{figure}
 732
 733 The resulting .mp3 file can be uploaded to a web server and then the phone's web browser can download the .mp3 file directly from the URL. There may be a size limit on the file.
 734
 735 \subsection{Time stretching audio}%
 736 \label{sub:time_stretching_audio}
 737 \index{audio!time stretching}
 738
 739 It may appear that time stretching audio is a matter of selecting a region of the audio tracks, enabling recording for the desired tracks, going to\texttt{ Audio $\rightarrow$ Render Effect}, and applying \textit{TimeStretch}. In actuality there are 3 audio effects for time stretching: Time Stretch, Resample, and Asset info dialog.
 740
 741 \textit{Time Stretch} applies a fast Fourier transform to try to change the duration without changing the pitch, but this introduces windowing artifacts to the audio. It is only useful for large changes in time because obvious changes in duration make windowing artifacts less obtrusive.
 742
 743 For smaller changes in duration, in the range of $5\%$, \textit{Resample} should be used. This changes the pitch of the audio but small enough changes are not noticeable. Resample does not introduce any windowing artifacts, so this is most useful for slight duration changes where the listener is not supposed to know what is going on.
 744
 745 Another way to change duration slightly is to go to the Resources window, highlight the media folder, right click on an audio file, click on \textit{Info}. Adjust the sample rate in the Info dialog to adjust the duration. This method also requires left clicking on the right boundary of the audio tracks and dragging left or right to correspond to the length changes.
 746
 747 \subsection{Pan and zoom: still images}%
 748 \label{sub:pan_zoom_still_image}
 749
 750 \CGG{}'s powerful keyframe features allow you to use pan and zoom effects on still pictures.
 751
 752 \begin{enumerate}
 753         \item Load and create a clip from a still image. Make the clip 10 seconds long.
 754         \item Activate the automatic generation of keyframes.
 755         \item Using the transport controls, go to the beginning of the clip.
 756         \item Using the compositing camera control set the clip's initial position.
 757         \item Using the transport controls, move forward a couple of seconds on the clip.
 758         \item Dragging on the compositing camera, move the camera center to a new position further along.
 759         \item Next go to the beginning of the clip and play it.
 760 \end{enumerate}
 761
 762 You can see that the camera smoothly flows from keyframe point to next keyframe point, as \CGG{} automatically adjusts the camera movement in straight lines from point to point.
 763
 764 \subsection{Video lagging behind Audio}%
 765 \label{sub:video_lagging}
 766
 767 When there is a lag between the Audio and the Video, it can be because there are a lot of video frames
 768 and the computer can not display them as fast as the Audio can play the samples.  However, this does
 769 not affect the rendered media in that the Audio and Video will be correctly synchronized. When playing
 770 the original media, you can alleviate the lag between the Audio and Video by disabling
 771 \textit{Play every frame} in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab.  Now frames
 772 will be skipped in order to keep the audio/video in synch.
 773
 774 \subsection{How to remove letterbox/pillarbox bands}%
 775 \label{sub:remove_letterbox}
 776
 777 To remove the horizontal black bands of the letterbox or the vertical
 778 black bands of the pillarbox we need to change the \textit{size} and
 779 \textit{aspect ratio} of the source by cropping.
 780 For example, if we want to remove the letterbox from a $4:3$ frame to
 781 leave only the content with aspect ratio $3:2$, We have to change the
 782 project format by doing the following steps:
 783
 784 \begin{enumerate}
 785     \item Check the size of the base W of the original frame in pixels:
 786
 787     \texttt{Resource} window $\rightarrow$ \texttt{RMB} on Asset
 788 $\rightarrow$ \texttt{Info} $\rightarrow$ \texttt{Detail}; e.g. W =
 789 768 px
 790     \item Obtain the height of the figure in $3:2$, i.e., without the
 791 black bands; H can be obtained from the formula:
 792
 793     $\frac{3}{2} = \frac{W}{H}$ \quad from which $H = \frac{768 \times
 794 2}{3}$ \qquad e.g., H = 512 px
 795     \item Note that $W \times H = 768 \times 512$ is just the crop we
 796 are looking for to switch from $4:3$ frame to $3:2$ frame without
 797 letterbox.
 798     \item Open \textit{Set Format} window: \texttt{Settings
 799 $\rightarrow$ Format}
 800     \item Change $H = 512$ and set \textit{Display Aspect Ratio} to
 801 $3:2$; press \texttt{Apply} and \texttt{OK}. Note that we leave W
 802 unchanged, since the frame width does not change.
 803     \item If needed, use the \textit{Camera} tool to get the
 804 desired viewport.
 805 \end{enumerate}
 806
 807 \paragraph{Note:} in complex situations, with multiple sources of
 808 different sizes, it may be appropriate to perform an additional
 809 step first: change the size of the track on the Timeline via
 810 \texttt{RMB $\rightarrow$ Resize track}.
 811 In this way we crop the track to match it to the project format that
 812 we will change in the next step. Thus we avoid possible unwanted
 813 distortions.
 814
 815 In the case of the pillarbox, we will leave H unchanged while
 816 calculating the new value of W. The formula $\frac{x}{y} =
 817 \frac{W}{H}$ is valid for any aspect ratio ($4:3; 16:9; 2.35:1$; etc).
 818