parts/Advanced.tex

   1 \chapter{Advanced Editing}%
   2 \label{cha:advanced_editing}
   3
   4 \section{Proxy}%
   5 \label{sec:proxy}
   6 \index{proxy}
   7
   8 Proxies were introduced to allow for a smoother timeline experience. Full HD and everything from 4K size up are usually very large in file size. In addition, some commonly used codecs (for example h264/5) are very compressed and interframe type, so they are more CPU intensive for timeline playback. These files cause performance problems on smaller computers. As a solution, proxies were introduced to reduce the file size. Reduced means to minimize the resolution/dimension, as usually not the full resolution is needed because the compositor generally occupies only a fraction of the computer screen. The proxy provides a scaling factor which indicates how much the original resolution should be reduced.
   9 There is also the \textit{proxy 1:1} \index{proxy!1:1} option that maintains the original resolution but still allows you to modify codec parameters (lowering the bit rate, for example). This is explained in the next section, \ref{sec:transcode}.
  10 Always remember when getting ready to render the project, disable Proxy to return to the original settings with the highest quality.
  11
  12 To use proxy select \texttt{Settings $\rightarrow$ Proxy settings} on the main window.  You can choose ffmpeg as the \textit{File Format} \index{file format} and for the \textit{File Type} a choice of various codecs associated with that.  A good choice for \textit{File Type} is the default of mpeg or mov which can usually be quite fast.  In addition you can modify values for that codec by clicking on the wrench icon. Once you have created a
  13 proxy file, it will be reused and does not have to be created again as long as you
  14 do not change certain parameters.  This saves a lot of CPU time.
  15
  16 There are two main ways to use Proxy, with or without \textit{Rescaled to project size} option checked. The options of the \textit{Scale factor} may be different if \textit{Rescaled to project size} is checked versus unchecked. It is a special case when the \textit{Scale facto}r is set to "1" and it does not  matter if \textit{Rescaled to project size} is checked or unchecked.
  17
  18 The usual steps to use Proxy are:
  19 \begin{enumerate}
  20         \item Check that \textit{File Format} is set to \texttt{FFMPEG}.
  21         \item Check or uncheck the \textit{Rescaled to project size} (FFMPEG only). The difference with this option will be explained here \ref{sub:rescaled_project_size_works}. But for old computers checking \textit{Rescaled to project size} is not recommended; again due to requiring more CPU. You need to know that when \textit{Rescaled to project size} is unchecked some Effects/Plugins do not work as expected because they use pixel values instead of percentage values as is used in the Project Format. For example \textit{Title}, \textit{Blur}, \textit{Sketcher} plugins do not work right if unchecked, while \textit{Perspective} and \textit{Crop\&Position} plugins work correctly for both checked and unchecked.
  22         \item Choose the \textit{Scale factor}. The options may be different if \textit{Rescaled to project size} is checked or unchecked. The smaller the \textit{Scale factor} is, the smoother playing on the Timeline will be ($\frac{1}{8}$ is smaller than $\frac{1}{4}$), but on the Viewer/Compositor the image will be degraded/pixelated more.
  23         \item Set the \textit{File Type} in the \textit{File Format} for FFMPEG, such as mp4, mpeg, or mov. Still images like jpg, tiff, and png will be converted to PNG files with alpha channel if it had an alpha channel.
  24         \item Click on the wrench icon to configure video compression; just use the default values if you are unsure and prefer not to experiment.
  25         \begin{enumerate}
  26                 \item Select the Compressor type (codec).
  27                 \item Change Bitrate, or Quality, and Pixels. Because not all codecs use the alpha channel for transparency, check that the letter "\textbf{a}" is in the Pixels name (such as yuv\textbf{a}420p or rgb\textbf{a}) to retain the alpha channel.
  28                 \item Click on the OK button to close the Compressor window.
  29         \end{enumerate}
  30         \item Now click on the \texttt{OK} button to start the rendering for the proxy.
  31         \item Look in the lower right corner of the main window where there is a progress bar and a percentage value showing the progress of the creation of proxies, and in the lower left corner there is the \textit{Creating proxy files... ETA: hh:mm:ss} text with the "Estimated Time of Arrival (completion)" in hours, minutes, seconds. Depending on how many files your project uses, the file size, which codec is used, the scale factor, and cpu performance, creating proxies may take some time.
  32 \end{enumerate}
  33
  34 You will know that Proxy mode is enabled because:
  35 \begin{itemize}
  36         \item A white colored \textbf{P} meaning \textit{\textbf{P}roxy}, or a white colored \textbf{S} meaning \textit{Proxy \textbf{S}caled} icon is shown in the upper right corner of the main window to the left of the FF icon.  If using the Cakewalk or Neophyte theme it will be a \textbf{Ps} icon.
  37         \item  The Proxy folder in the Resources window has been populated with the names and/or icons of the proxy media.
  38         \item The edit title bar in the timeline will have the name of the proxy file instead of the original name. So if the video filename is \texttt{VID\_20221012.mp4}, the Proxy Scale Factor is $\frac{1}{4}$, and the Proxy container is mov, then the proxy name will be \texttt{VID\_20221012.proxy4-mp4.mov}.
  39 \end{itemize}
  40
  41 The Proxy icon is a toggle button so that you just click on the icon to change modes.  Or it can be toggled using the \texttt{Ctrl+R} shortcut.
  42
  43 \begin{table}[ht]
  44         \centering
  45         \begin{tabular}{|p{2.5cm}|p{3.2cm}|p{3.2cm}|p{3.2cm}|}
  46                 \hline
  47                 {\footnotesize\textbf{Proxy State}} &   {\footnotesize\textbf{Rescaled to project size (FFMPEG only)}} &        {\footnotesize\textbf{Proxy icon for themes:
  48                 Cakewalk/ Neophyte}} &  {\footnotesize\textbf{Proxy icon for themes: the Others}}\\
  49                 \hline
  50                 {\footnotesize{Off}} & {\footnotesize{checked/ unchecked}} & {\footnotesize{no icon}}
  51                  & {\footnotesize{no icon}}\\
  52                 \hline
  53                 {\footnotesize{Active (Enable)}} & {\footnotesize{checked}} & {\footnotesize{Ps: P(green)  s(white)}}
  54                  & {\footnotesize{S (white)}}\\
  55                 \hline
  56                 {\footnotesize{Disable}} & {\footnotesize{checked}} & {\footnotesize{Ps: P(red)  s(white)}} & {\footnotesize{S (gray)}}\\
  57                 \hline
  58                 {\footnotesize{Active (Enable)}} & {\footnotesize{unchecked}} & {\footnotesize{Ps: P(green) s(red)}} & {\footnotesize{P (white)}}\\
  59                 \hline
  60                 {\footnotesize{Disable}} & {\footnotesize{unchecked}} & {\footnotesize{Ps: P(red) s(red)}} & {\footnotesize{P (gray)}}\\
  61                 \hline
  62         \end{tabular}
  63         \caption{list States of the Proxy icon}
  64 \end{table}
  65
  66 When you disable Proxy using the toggle button for Proxy, or its shortcut (\texttt{Ctrl+R}), in the Proxy Settings window you will see the \textit{Scale Factor = 1}, but if you look at the Active Scale and the State, you can understand what your setting is.
  67 Proxy can have three possible States: Off, Active, Disabled. The difference between Off and Disabled is that Disabled means you have set the Proxy and it is temporarily switched off (and you can see the icon in the upper right corner of the main window); you can enable proxy by just clicking on the icon, so the State will then be changed from Disabled to Active.
  68
  69 \subsection{How Rescaled to project size (FFMPEG only) works}%
  70 \label{sub:rescaled_project_size_works}
  71
  72 \begin{itemize}
  73         \item When \textit{Rescaled to project size (FFMPEG only)} is checked, the size of the video data to be computed will always be the same as the Project Format. The size of your video is scaled down to the \textit{Scale factor} BUT then it is rescaled up to the Project Format. For example, your Project Format is 1920x1080 and Proxy's Scale factor is $\frac{1}{4}$, then your videos ($1920x1080$) will be scaled down to 480x270 and then up-scaled to $1920x1080$. All the Effects/Plugins work correctly because the original resolution/geometry/size is not changed. For an old computer, this option is not recommended.
  74         \item When \textit{Rescaled to project size (FFMPEG only)} is UNchecked, the size of the video data to be computed will be reduced to the \textit{Scale factor}. The size of your video is scaled down to the \textit{Scale factor}. For example, your Project Format is 1920x1080 and Proxy's Scale factor is $\frac{1}{4}$, then your videos ($1920x1080$) will be scaled down to $480x270$. It works as if the Project Format were $480x270$ (and really it works). If you take a look at \texttt{Settings $\rightarrow$ Format...} when Proxy is enabled (Active), you can see that the Width and Height are changed according to the \textit{Scale factor}; you absolutely must NOT change these values! The good thing is that your computer will be faster. The bad thing is that some Effects/Plugins do not work as expected because they use pixel units. Examples are \textit{Title} and \textit{Blur} plugins. A workaround is needed for that, such as using Inkscape to create a title and export it to PNG that you load instead of using the \textit{Title} plugin.
  75
  76 \end{itemize}
  77
  78 Note: the dimensions of the frame/image are downscaled to the Scale factor; so if the Scale factor is $\frac{1}{4}$ and the dimension of the image is $4288x2848$ pixels, that image will be downscaled to $1072x712$. It doesn't matter what the Project Format is.
  79
  80 \subsection{Using proxy}%
  81 \label{sub:using_proxy}
  82
  83 To insert a clip/video from Resources window to the Timeline when Proxy is enabled (Active) you MUST Drag \& Drop that clip/video from the Proxy folder instead of the Media folder, as well as for Nested clips. And also if you want to load the clip in the Viewer or Compositor. You can use clips in the Clips folder in any State of the Proxy - it does not matter if Proxy is enabled or disabled.
  84
  85 Rendered proxy media is saved in the same directory as the original media. As usual, you can delete proxy files from the project or disk in the Resources window if you no longer want to retain them. You should \textbf{always save your project with the Proxy disabled}.
  86
  87 If you create proxies for Nested clips they will be saved in \texttt{\$HOME/Videos} unless you modify that in \texttt{Settings $\rightarrow$ Preferences}, \texttt{Interface tab}, \textit{Nested Proxy Path}. If you change anything in a Nested clip using the \textit{Open EDL} feature, you must first delete its old proxy file from disk because it is not updated automatically, and then enable Proxy again so that a new one is created.
  88
  89 Not all the settings for Proxy are saved in the project: the values of Active Scale and the \textit{Rescaled to project size} are saved but not the \textit{File Format}, \textit{File Type} and all video compression data. A good idea is to record this information in a README file about your project where you make a note of your Proxy settings for that project.
  90 This is especially important because some Projects may use different Proxy settings and
  91 if you load a project where the Proxy is set and disabled, it could use a different
  92 setting because you changed the Proxy settings in a project you were working on before.
  93 If in that Project its proxy files were not deleted and you want to reuse them to save
  94 time, unfortunately they will be created again because the proxy settings have changed.
  95
  96 If the \textit{Creation of proxy on media loading} option has been checked, then when you load other media later, proxies will be created for them automatically, or else you can change the Proxy's State from disabled to enabled (Active) using the Proxy icon. Previous proxy renders will be reused unless you change one of the following proxy parameters: \textit{Scale factor}, \textit{File Format}, or \textit{File Type}. If proxies have been created and then you decide to change only the Compression type (Codec, Bitrate, Quality, Pixels), without changing the \textit{Scale factor} or Container, you must delete proxy files from the disk beforehand. That is because \CGG{} does not read the compression type; it does read the filename and if the filename does
  97 not change, \CGG{} thinks the proxy was already created.
  98
  99 \subsection{Scale factor set to 1, a special case}%
 100 \label{sub:scale_factor_special_case}
 101
 102 This special case is used to temporarily change the codec parameters of your video while maintaining the original resolution - for example maybe your videos use long-GOP or the video codec is too hard to handle due to a strong compression. It does not matter if \textit{Rescaled to project size} is checked or unchecked. For old computers, or underpowered computers, this option is not recommended.
 103
 104 \subsection{Setting the proxy}%
 105 \label{sub:setting_proxy}
 106
 107 \begin{figure}[htpb]
 108         \centering
 109         \includegraphics[width=0.8\linewidth]{proxy-02.png}
 110         \caption{Proxy settings dialog}
 111         \label{fig:proxy-02}
 112 \end{figure}
 113
 114 Screencast in figure~\ref{fig:proxy-02} shows the \textit{Rescaled to project size} checked so you can still use plugins correctly and the original project size is kept.  The \textit{Scale factor} pull-down gives you available size options.  Note the new media dimensions shown (partially covered).  If the size is an odd number, 1 is added to make the dimensions both even numbers.
 115
 116 To go back to the original media permanently, simply set the \textit{Scale factor} to Off or disable the Proxy by clicking on its toggle button. However, if you decide to reuse the proxies, those which have not been deleted from the Hard Disk (but have been removed from the project) will be used without re-rendering - this saves a lot of time. To completely remove the created proxies you will have to delete them manually from the Hard Disk.
 117 There is also a convenient \textit{Beep on done volume} slider included so that you can work on other tasks until there is an audible notify of completion.  The default volume is set to 0 for no audible notify.
 118
 119 A good choice for classic proxy settings with a 1080p source video is:
 120
 121 \begin{lstlisting}[numbers=none]
 122 Scale Factor:   1/4
 123 File Format:    FFMPEG - mpeg
 124 Video Preset:
 125 Compression:    mpeg.mpeg
 126 Bitrate:        2000000
 127 Quality:        -1
 128 Pixels:         yuv420p
 129 \end{lstlisting}
 130
 131 If you get errors for some videos, such as those with strange variable bit rate or some types of files made on a smartphone, a usually reliable alternative is to change the following parameters:
 132
 133 \begin{lstlisting}[numbers=none]
 134 File Format:    FFMPEG - mov
 135 Video Preset:
 136 Compression:    mov.mov
 137 \end{lstlisting}
 138
 139 Or if you want small files with high image quality, a \textit{File Format} of m2ts is optimal.  For example a 1 GB file can be reduced to 50 MB with scale $\frac{1}{2}$.
 140
 141 If you get error messages \index{proxy!error} when creating proxies, check the Video wrench settings.  These usually default to values that are expected to work correctly for the \textit{File Format} and codec you selected but they can be changed and may result in errors.  If you get an error message of \textit{check\_frame\_rate failed} followed by \textit{Error making proxy} in the popup Errors window, do just that and check the Frame rate value by going to the Resources window, Media folder, and use the right mouse button for the \textit{Info} option for the specific media in question.  You can change the frame rate in this window to a more codec acceptable value.  Different codecs may have different legal values.
 142
 143 A faster method of creating the proxy file outiside of \CGG{} for users who have
 144 vaapi hardware acceleration capability on their graphics board is via a script.  Speed
 145 up could potentially be 10 to 30 times faster depending on the parameter values you choose
 146 and the size of your video file.  This script is included in the doc subdirectory as
 147 \texttt{vaapi\_proxy.sh} for users not using an AppImage version and is shown below.  You will
 148 have to tune it to your specific needs for the vaapi\_device name (currently set to
 149 \texttt{/dev/dri/renderr128}), file type (currently set to h264 and mp4), and proxy size (now is 6).
 150 Once you have created the proxy file, you then start \CGG{}, load the original un-proxied
 151 video, use the Settings pulldown and choose the Proxy settings options as you would normally,
 152 but because you already have created the existing proxy file with the correct name, it will
 153 be automatically loaded and will not have to create it.  The filename of the proxy file
 154 must be in the same location as the original video and have the exact required naming
 155 conventions and scale factor.
 156
 157 \begin{lstlisting}[numbers=none]
 158 #!/bin/bash
 159 filename="$1"
 160 fileout="${filename%.*}"
 161 proxy="6"
 162 # Hardware encode AMD
 163 ffmpeg -threads 2 -hwaccel vaapi  -vaapi_device /dev/dri/renderD128 \
 164  -i  "$1" -c:v h264_vaapi -vf "format=nv12,hwupload,scale_vaapi=iw/'$proxy':ih/'$proxy'" \
 165  -vcodec h264_vaapi  -preset fast -c:a copy \
 166  -bf 0 -profile:v 66 "$fileout".proxy"$proxy"-mp4.mp4
 167 \end{lstlisting}
 168
 169 \subsection{Proxies with Alpha channel}%
 170 \label{sub:proxies_alpha_channel}
 171
 172 Next are some examples of tested and working configurations that maintain the alpha channel:
 173
 174 \begin{lstlisting}[numbers=none]
 175 Proxy #1
 176         Scale factor: 1/4
 177         Rescaled to project size (FFMPEG only) = unchecked
 178         File Format: FFMPEG | qt
 179         Video Preset-->
 180                 Compression: png.qt
 181                 Bitrate: 0
 182                 Quality: -1
 183                 Pixels: rgba (or rgba64be)
 184
 185
 186 Proxy #2
 187         Scale factor: 1/4
 188         Rescaled to project size (FFMPEG only) = unchecked
 189         File Format: FFMPEG | qt
 190         Video Preset-->
 191                 Compression: magicyuv.qt
 192                 Bitrate: 0
 193                 Quality: -1
 194                 Pixels: yuva444p
 195
 196
 197 Proxy #3
 198         Scale factor: 1/4
 199         Rescaled to project size (FFMPEG only) = unchecked
 200         File Format: FFMPEG | qt
 201         Video Preset-->
 202                 Compression: openjpeg.qt
 203                 Bitrate: 0
 204                 Quality: -1
 205                 Pixels: yuva420p
 206
 207
 208 Proxy #4
 209         Scale factor: 1/4
 210         Rescaled to project size (FFMPEG only) = unchecked
 211         File Format: FFMPEG | pro
 212         Video Preset-->
 213                 Compression: prores_4444.pro
 214                 prores_4444xq.pro
 215                 Bitrate: 0
 216                 Quality: -1
 217                 Pixels: yuva444p10le
 218
 219
 220 Proxy #5
 221         Scale factor: 1/4
 222         Rescaled to project size (FFMPEG only) = unchecked
 223         File Format: FFMPEG | mkv
 224         Video Preset-->
 225                 Compression: user_ffvhuff.mkv
 226                 Bitrate: 0
 227                 Quality: -1
 228                 Pixels: yuva4--p
 229                                    yuva4--p--le
 230 \end{lstlisting}
 231
 232 \section{Transcode}%
 233 \label{sec:transcode}
 234 \index{transcode}
 235
 236 Transcode, an option under the \textit{Settings} pulldown right next to the Proxy settings option, is a type of full resolution \textbf{1:1 Proxy} \index{proxy!1:1}.
 237 The process of transcoding works directly from the resource; it is independent of the timeline.
 238 All of the loaded asset media will be converted, that is, rendered in the selected format and loaded onto the timeline.
 239 Menu choices besides the usual File Format \index{file format} and File Type include: \textit{Tag suffix} (to add to media filename), \textit{Remove originals from project}, \textit{Into Nested Proxy directory} (an option to have the file saved here instead of the location of the original media), and \textit{Beep on done} volume.
 240
 241 The settings of the project have an effect on the outcome, for example the dimensions are taken into account. The resulting files are also larger than if they were created directly with ffmpeg.
 242 Transcode works for videos with or without audio and even single frame files, like png's.
 243 If you have a video file that also contains audio, and you convert only the video, the original audio will stay on the timeline if do not check \textit{Remove originals from project}. Or vice versa if audio converted and not video.
 244 Multiple stream media will only transcode the first stream (this would be like the TV channel recordings in the United States).
 245 You will get an error message if you already have a transcoded file in the selected format with the same suffix name and try to transcode it again with a different selection made -- you will have to delete that file first. An example would be
 246 an already converted file that has both video and audio and now you request video only.
 247
 248 The BIGGEST gain from using this is if you have media that is not \textit{seekable} \index{seek}, that is, you can play it from the beginning but can not move to another spot and have the audio or video play correctly. A video file with no keyframes makes seeking next to impossible, but then a Transcode generally adds these keyframes. This is particularly useful for the \texttt{mkv} container, which often has seek problems. For more details on mkv container see \ref{ssub:note_mkv_container}
 249
 250 Another important function of Transcode is being able to convert the project's media into a high-quality \textit{mezzanine} codec \index{mezzanine codec} (sometimes also called \textit{intermediate} codec \index{digital intermediate}), which makes timeline work lighter and more efficient. In fact such codecs (ffv1, ProRes, DNxHD, OpenEXR, huffyuv, etc) are generally little or not at all compressed; the type of compression is intraframe --more suitable for editing, and the image quality (4:2:2 up; 10-bit color up; floating point; etc) is suitable for \textit{Color Correction}, \textit{Chroma Key} and \textit{Rotoscoping}. The use of mezzanine codecs leads to very large files, so you need to make sure you have enough storage space.
 251
 252 \paragraph{NOTE:} \CGG{} cannot do \textit{remuxing} without transcoding. For remuxing only, use \textit{ffmpeg} as shown in the following script. First move to the folder containing the files to be remuxed; the script takes all video files of a certain extension (in the following example \texttt{avi}) from the folder and its subfolders and makes a remux in a new container (in this example \texttt{mkv}) inside the new folder \texttt{remux}. The internal codec will remain the original one.  Here is an example script:
 253
 254 \begin{lstlisting}[numbers=none]
 255         for f in $(find . -name '*.avi'); do ffmpeg -i "$f" -c:v copy -c:a copy "remux/{f%.*}.mkv "; done
 256 \end{lstlisting}
 257
 258 \section{OpenEDL}%
 259 \label{sec:openedl}
 260 \index{openEDL}
 261
 262 To edit EDL \index{EDL} that is included with your project as Clips, Nested
 263 Clips, Referenced File, or Xml you can use the option \textit{Open
 264         EDL} in the Resources window for the highlighted media.  Then
 265 with a simple button click you can return to your main timeline project.
 266 For example, if you have a nested clip that originally had several
 267 plugins added to it before it was nested, you can edit those plugin
 268 parameter values. Previously to make any changes to these types of
 269 EDL you had to remake the whole clip from scratch.  The program is
 270 actually "opening" the file as it currently exists for that particular
 271 media so that it can be edited separately from the project EDL. In other NLEs the term \textit{sub-timeline} or \textit{sub-project} is used.
 272 It is important to know that all media used with Open EDL must be loaded on the timeline Main Program window and created from there in that project.
 273
 274 Here is how this works. In the Clip \index{clip !older} or Media folder \index{media folder} or on a timeline
 275 EDL edit, the option \textit{Open EDL} for the highlighted clip or
 276 nested clip is available so that when you choose this option, that
 277 EDL will be brought up on the timeline superseding the current EDL
 278 that exists on the timeline \index{timeline}.  Now, once the clip is open on the
 279 timeline, you can edit it however you want. The previous timeline
 280 EDL is \textit{pushed onto a stack} so it can be recalled by
 281 \textit{popping the stack} with a click of the left mouse button in
 282 the upper right hand corner of the timeline to the left of the
 283 \textit{shell cmds} icon.  Initially this button displays a 0 to
 284 indicate your initial timeline/project.  Then this button will read
 285 1 if you choose \textit{Open EDL} and then back to 0 and your
 286 original timeline with the left mouse click.  You can go several
 287 levels deep so instead of 1, it could be 2, 3, $\dots$ but this
 288 requires some thought to avoid potential confusion.
 289
 290 An example of a typical set of steps to follow is:
 291 \begin{enumerate}
 292         \item Load your media using insertion strategy of \textit{Replace
 293                 current project}.  There will be number 0 in the upper right hand corner
 294         of the main menu with the tooltip of \textit{Close EDL}.
 295         \item Highlight a selection on the timeline and press the
 296         \textit{To clip} icon and click the green checkmark OK.
 297         \item In the Resources window, open the Clip folder and you will
 298         see that Clip 1 is present.
 299         \item Highlight Clip1 and right mouse the item to bring up
 300         available options and select \textit{Open EDL}.
 301         \item Now you will see the timeline change from the original
 302         media to just the clip content and the number in the upper right hand
 303         corner will change from 0 to 1.
 304         \item Add a visible effect, like AgingTV to the timeline.
 305         \item Click on the number 1 in the main menu bar to see the timeline
 306         restored to the original media.
 307         \item Drag the clip from the Resources Clip folder to the
 308         timeline and you will see the AgingTV effect.
 309 \end{enumerate}
 310
 311 \paragraph{NOTE:} \textit{Open EDL} was not designed to work from the Viewer window. It needs clips to have been created from the timeline Main Program window Project in order to keep track of levels. Clips created in the Viewer have different min and max X/Y dimensions and zoom values.
 312
 313 You can follow the same steps as above by first using the option
 314 \textit{Nest to media} in the Clip folder which nests the clip and
 315 moves it out of the Clip folder to the Media folder.  Then use
 316 \textit{Open EDL} on the Nested EDL \index{nested EDL} in the media folder.  When you
 317 Open EDL and edit the changes, those changes will take affect on any
 318 and all occurrences of that nested clip on the current and/or
 319 original timeline. The option to unnest that clip and put that back
 320 into the Clip folder is the option \textit{EDL to clip}.  The nested
 321 clip is still in the Media folder.  It will now have a name of the
 322 next available Clip number but the comment contains the previous name so
 323 you can tell where it came from.
 324
 325 Instead of using the number on the main menu to close the current
 326 EDL, both the Media and Clip folders have \textit{Close EDL} options
 327 with the left mouse button. Clicking on the number button is quick and
 328 easy but for infrequent usage it is not obvious, whereas if you use
 329 \textit{Open EDL} you see \textit{Close EDL} right below that and so
 330 it is very obvious.  In addition in the case of where you have
 331 opened a EDL, and you no longer see that clip in the folder, the
 332 right mouse button where no media is highlighted will also display
 333 the Close EDL option.
 334
 335 %\pagebreak
 336 \begin{figure}[h]
 337         \centering
 338         \includegraphics[width=1\linewidth]{editing-img001.png}
 339         \caption{Once you have an Open EDL, the easiest way to close it.}
 340         \label{fig:open_edl}
 341 \end{figure}
 342 \relax
 343
 344 In addition to the \textit{Open EDL} option in the Resources menu,
 345 this option is available on the timeline when the cursor is on an
 346 EDL-type edit. To get to this option, click on the middle mouse
 347 button on that edit.  If it is not EDL, the option will not be
 348 shown.  In summary:
 349
 350 \begin{center}
 351         \begin{tabular}{ll}
 352                 \toprule
 353                 Media folder of Resources window & Open EDL for Nested or Referenced EDLs\\
 354                 Clip folder of Resources window & Open EDL for clips\\
 355                 Track timeline & Open EDL for Nested or Referenced EDLs\\
 356                 \hline
 357         \end{tabular}
 358 \end{center}
 359
 360 An aside -- when nesting and unnesting clips to take advantage of
 361 this feature, names of the media can lead to some confusion.  For
 362 example, if you nest a clip, the new name in the Media folder is the
 363 word \textit{Nested} followed by an underscore with the date and
 364 timestamp, another underscore, and then the clip name.  Then when
 365 you unnest this Media folder clip via the \textit{EDL to clip}
 366 option, the name will be changed in the Clip folder to the next
 367 available Clip number.  However the comment field will reflect the
 368 nested clip name from which it was derived.  To avoid confusion you
 369 can easily change the name for these clips in either the Clip or
 370 Media folder because they are not real files at this point. To do
 371 so, highlight the clip name in Resources, click on Info and type in
 372 a new name.
 373
 374 For additional safety, the \textit{Open EDL} feature includes
 375 additional backup capabilities. Automatically \CGG{} saves a backup \index{backup}
 376 when certain changes are made or you can always use the shortcut `b'
 377 to do one yourself, although keep in mind it will be overwritten
 378 whenever \CGG{} wants to do another backup.  Now there is a shortcut
 379 for the backup shortcut `b' so you can keep your hand on the mouse
 380 instead of the keyboard.  Just click on the number button in the upper right
 381 hand corner of the main window.  If number is at 0, it backs up to
 382 backup.xml, if at 1, it backs up to \texttt{backup1.xml} and so on
 383 \dots up to \texttt{backup9.xml}.
 384
 385 When \textit{Open EDL} is invoked, the current EDL and current undo
 386 stack are both \textit{pushed}, and the active session EDL is
 387 replaced with the target clip/nested edl.  A new undo stack is
 388 created, and the active \texttt{backup.xml} file name is decorated
 389 with the stack level.  So, \texttt{backup.xml} is
 390 \texttt{backup1.xml} when your edits are at stack level 1,
 391 \texttt{back\-up2\-.xml} at stack level 2, and so on.  This means
 392 that if you \textit{load backup} at stack level 1, the session will
 393 reload from history at stack level 1, not the main session.
 394
 395 See a real-world workflow at appendix \nameref{sec:workflow_openedl_nested_clips}
 396
 397 \section{File by Reference}%
 398 \label{sec:file_by_reference}
 399 \index{file by reference}
 400
 401 It is sometimes handy to have EDL \index{EDL} assets not as a copy, but as a
 402 reference that is automatically updated into your project.  Suppose
 403 you have several short videos that at the end have the same credits
 404 which include the current year such as 2021.  But now it is 2022 and
 405 all of the videos would have to be individually updated with the new
 406 date.  By including a \textit{Referenced File} as the EDL file type
 407 when you create each of the videos, you can just change the one
 408 credits xml file and the next time you load one of the videos and
 409 render it, it will now automatically have the updated information.
 410
 411 The purpose of this feature is to be able to rework a smaller
 412 section of a global master project at any time, which can be done by
 413 an "assistant" (i.e. external software like GIMP or Inkscape, $\dots$) and then this work is automatically reflected in the
 414 global master project.  It is for \textbf{advanced usage only}.
 415
 416 Up until the addition of this feature, \CGG{} has always used copies
 417 and no direct reference in order to ensure original data is never
 418 compromised (No Destructive editing).  In the usual case, subprojects as xmls are copied into
 419 a master project where subprojects had been inserted, so that if you
 420 change something in a subproject or delete a subproject, it would
 421 have no affect on the master project.  But now with \textit{File by
 422         Reference}, any project that uses a referenced file will
 423 automatically include any changes made to the referenced file when
 424 loaded.  At the same time, if you use the EDL file NOT as a
 425 referenced file in a project since it is then just a copy, it will
 426 not be updated.  Because of this difference, the user needs to be
 427 very aware of what using this feature could do.
 428
 429 \textbf{Use with extreme caution}.  However, there are several
 430 built-in safety features and a warning that should never be turned
 431 off even though it gives you the option to do so.  These include:
 432
 433 \begin{enumerate}
 434         \item When the \texttt{File, Load files} menu is opened, the EDL
 435         strategy will always be set to just EDL as default.  Although, if
 436         you use Apply and leave the Load Menu open, it will stay changed to
 437         what you selected until it is re-opened.
 438         \item When an EDL is opened as \textit{Reference}, the color of
 439         that file name in the Resources Media folder is different in order
 440         to serve as a reminder that it is special.
 441         \item A warning message is displayed in a popup window when you
 442         load a \textit{File by Reference} that reads \texttt{Other projects can
 443         change this project and this can become a broken link}.  Although
 444         you can check the warning box to never see this warning again, you
 445         would be well advised to not do so.  It is a great reminder of
 446         consequences and you will not want to be cavalier about the warning.
 447         Instead just use the X to dismiss the warning.
 448 \end{enumerate}
 449
 450 Here is a step by step example of how you can use \textit{File by
 451         Reference}:
 452 \begin{enumerate}
 453         \item Start up \CGG{} and use the Title plugin to create a new
 454         credits file.  Save as credits.xml.
 455         \item Start a New project and then load an existing master
 456         project to the timeline.
 457         \item Load the credits file you created in step 1 with a Load
 458         Strategy of Create Resources Only and with EDL Strategy as
 459         \textit{Reference}.
 460         \item Note the color change in the credits.xml filename and the
 461         reference comment in the Resources Media folder.
 462         \item Drag the credits file to an empty spot on the timeline.
 463         Save this new master project and quit.
 464         \item Start \CGG{} up again.  Load credits.xml and make a change
 465         to the Title and save again.
 466         \item Exit \CGG{}; restart \CGG{}; load your master project and
 467         now you will automatically see on the timeline the changes you just
 468         made in the previous step.
 469 \end{enumerate}
 470
 471 \section{Trimming}%
 472 \label{sec:trimming}
 473 \index{trim}
 474
 475 With some edits on the timeline it is possible to do trimming. By
 476 trimming you shrink or grow the edit boundaries (\textit{head} or \textit{tail}) by dragging them. In
 477 drag and drop mode or cut and paste mode, move the cursor over an
 478 edit boundary until it changes shape. The drag handle \index{drag handles} shows as a
 479 left or right facing fat arrow when you cursor near the clip start
 480 or end.  If the cursor faces left, the dragging operation affects
 481 the beginning of the edit. If the cursor faces right, the dragging
 482 operation affects the end of the edit.
 483
 484 The effect of each drag operation not only depends on the behavior
 485 button but whether the beginning or end of the edit is being
 486 dragged. When you release the mouse button, the trimming operation
 487 is performed.
 488
 489 For all file formats, other than still images, the extent of the
 490 trimming operation is limited to the source file length. Attempting
 491 to drag the start of the edit beyond the start of the source, limits
 492 it to the source start. In all trimming operations, all edits which
 493 start on the same position as the cursor when the drag operation
 494 begins are affected. You have to disarm tracks in order to prevent
 495 edits from being affected.
 496
 497 You have 6 different choices of which mouse button to use for
 498 specific types of editing while using the drag handle.  You change
 499 the drag handle mouse effects by using the \texttt{Settings
 500         $\rightarrow$ Preferences  $\rightarrow$ Interface} tab and
 501 modifying the Editing section as shown in the next
 502 figure~\ref{fig:trim}. The drag handle affects not only the clip you
 503 are working on but also frequently the entire duration of all clips
 504 on the timeline.
 505
 506 \begin{figure}[htpb]
 507         \centering
 508         \includegraphics[width=0.5\linewidth]{trim.png}
 509         \caption{Default choices for mouse: Ripple for LMB; Roll
 510                 for MMB; Slip for RMB}
 511         \label{fig:trim}
 512 \end{figure}
 513
 514 A description of the fundamental/common terminology for choices
 515 follows.
 516
 517 \begin{description}
 518         \item[All Edits (ripple)] \index{trim!ripple} shorten or lengthen the start or end
 519         of a single piece of media while moving all media to the right of
 520         that clip up or down on the timeline correspondingly.  Timeline
 521         duration is modified.  In a drag \textit{All Edits} operation, the
 522         beginning of the edit either cuts data from the edit if you move it
 523         forward or pastes new data from before the edit if you move it
 524         backward. The end of the edit pastes data into the edit if you move
 525         it forward or cuts data from the end of the edit if you move it
 526         backward. All the following edits shift. If you drag the end of the
 527         edit past the start of the edit, the edit is deleted.
 528         \item[One Edit (roll)] \index{trim!roll} move the in and out point of a single
 529         clip without changing the timeline duration. In a drag \textit{One
 530                 Edit} operation, nothing is cut or pasted. If you move the beginning
 531         or end of the edit forward, the source reference in the edit shifts
 532         forward. If you move the beginning or end of the edit backward, the
 533         source reference shifts backward. The edit remains in the same spot
 534         in the timeline but the source shifts.
 535         \item[Src Only (slip)] \index{trim!slip} move the in and out point of a single
 536         clip without changing the timeline duration. In a drag \textit{Src
 537                 Only} operation, nothing is cut or pasted. If you move the beginning
 538         or end of the edit forward, the source reference in the edit shifts
 539         forward. If you move the beginning or end of the edit backward, the
 540         source reference shifts backward. The edit remains in the same spot
 541         in the timeline but the source shifts.
 542         \item[Slide] \index{trim!slide} a single clip is moved but retains its current in
 543         and out point; however the out point of the clip to the left changes
 544         and the in point of the clip to the right also changes.  Timeline
 545         duration remains the same.
 546         \item[Edge Left/Right] \index{trim!edge} moves the edge of the clips.
 547         \item[No effect] no changes are made.  You might want to use
 548         this choice to prevent accidental movements.
 549 \end{description}
 550
 551 \paragraph{NOTE:} you cannot do Trim operations on \textit{Hard Edges}, which are produced by a cut operation ("\texttt{x}"). To create a cut useful for trimming you must select an interval (at the limit of one frame) to be muted ("\texttt{m}"); now the edges of the edits will be trimmable because they are not \textit{Hard Edges}. See \ref{sec:cut_paste_editing}, \textit{Split - blade cut and hard edges}.
 552
 553 The next table displays the options and results
 554 with the Key Table here first.
 555
 556 \begin{lstlisting}[style=sh]
 557 s = src media start
 558 p = proj position
 559 l = length
 560 c = cut distance
 561 rest == p+=c: for rest of clips
 562 01 = flags edits_moved, rest_moved
 563 \end{lstlisting}
 564
 565 \renewcommand{\arraystretch}{1.15}
 566
 567 \begin{longtable}{lllll}
 568                 \toprule
 569                 &  & \textbf{Drag Left} & \textbf{Drag Right} &\\
 570                 \midrule
 571                 \multicolumn{2}{l}{\textit{curr s += c, l -= c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
 572                 abc12345xyz & \textbf{Ripple} left edge 11 $\rightarrow$ & abc012345xyz & abc2345xyz &\\
 573                 \midrule
 574                 \multicolumn{2}{l}{\textit{curr l += c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
 575                 abc12345xyz & \textbf{Ripple} right edge 01 $\rightarrow$ & abc1234xyz & abc123456xyz &\\
 576                 \midrule
 577                 \multicolumn{2}{l}{\textit{prev l += c; curr ps+= c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
 578                 abc12345xyz & \textbf{Roll} left edge 00 $\rightarrow$ & ab012345xyz & abcd2345xyz &\\
 579                 \midrule
 580                 \multicolumn{2}{l}{\textit{curr l += c; next ps+= c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
 581                 abc12345xyz & \textbf{Roll} right edge 00 $\rightarrow$ & abc1234wxyz & abc123456yz &\\
 582                 \midrule
 583                 \multicolumn{2}{l}{\textit{s -= c}} & $\leftarrow$ & $\rightarrow$ &\\
 584                 abc12345xyz & \textbf{Slip} left edge 10 $\rightarrow$ & abc23456xyz & abc01234xyz &\\
 585                 \midrule
 586                 \multicolumn{2}{l}{\textit{s -= c}} & $\leftarrow$ & $\rightarrow$ &\\
 587                 abc12345xyz & \textbf{Slip} right edge 10 $\rightarrow$ & abc23456xyz & abc01234xyz &\\
 588                 \midrule
 589                 \multicolumn{2}{l}{\textit{prev l += c; curr p+= c; next ps += c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
 590                 abc12345xyz & \textbf{Slide} left edge 10 $\rightarrow$ & ab012345wxyz & abcd12345yz &\\
 591                 \midrule
 592                 \multicolumn{2}{l}{\textit{prev l += c; curr p+= c; next ps += c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
 593                 abc12345xyz & \textbf{Slide} right edge 10 $\rightarrow$ & ab12345wxyz & abcd12345yz &\\
 594                 \midrule
 595                 \multicolumn{2}{l}{\textit{curr s -+= c, l += c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
 596                 abc12345xyz & \textbf{Edge} left edge 11 $\rightarrow$ & abc2345xyz & abc0123456xyz &\\
 597                 \midrule
 598                 \multicolumn{2}{l}{\textit{curr l -+= c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
 599                 abc12345xyz & \textbf{Edge} right edge 01 $\rightarrow$ & abc1234xyz & abc123456xyz &\\
 600                 \bottomrule
 601 \end{longtable}
 602 \renewcommand{\arraystretch}{1}
 603
 604 Next, a more immediate and colorful view shows these trimming
 605 options (figure~\ref{fig:trim-color}).
 606
 607 \begin{figure}[htpb]
 608         \centering
 609         \includegraphics[width=0.8\linewidth]{trim-color.png}
 610         \caption{The 5 types of Trim: note the different lengths of the results.}
 611         \label{fig:trim-color}
 612 \end{figure}
 613
 614 \paragraph{How to do a J-cut or L-cut} A J-cut \index{J-cut/L-cut} is a split edit film
 615 editing technique in which the audio from a following scene overlaps
 616 the picture from the preceding scene, so that the audio portion of
 617 the later scene starts playing before its picture as a lead-in to
 618 the visual cut.  An L-cut is a different split edit film editing
 619 technique in which the audio from preceding scene overlaps the
 620 picture from the following scene, so that the audio cuts after the
 621 picture, and continues playing over the beginning of the next scene
 622 (figure~\ref{fig:j-cut}). To do either a J-cut or an L-cut, you
 623 first shorten the first or second video a little.  Then you block
 624 the audio tracks from changing by disarming the appropriate tracks.
 625 Finally use \textit{One Edit (roll)} the cutting edge off the
 626 videos.  Moving to the right creates a J-cut and moving to the left
 627 creates an L-cut.
 628
 629 \begin{figure}[htpb]
 630         \centering
 631         \includegraphics[width=0.8\linewidth]{j-cut.png}
 632         \caption{J-cut to left and L-cut to right}
 633         \label{fig:j-cut}
 634 \end{figure}
 635
 636
 637 \subsection{Split View in Compositor Using the Drag Handle with Trim}%
 638 \label{sub:split_view_compositor_using_drag_trim}
 639 \index{trim!split view}
 640 The Trim Feature using the drag handle provides some good ways to
 641 view your video while editing.  The playback position in the
 642 compositor is updated live and the view in the compositor can be
 643 split so that in the left half of the compositor you can see the
 644 last frame of the left clip and in the right half the first frame of
 645 the right clip.  Dragging edits can not be extended past the
 646 beginning or the end.
 647
 648 First familiarize yourself with button operation; check your setup
 649 by executing the following step.  In the \texttt{Settings
 650         $\rightarrow$ Preferences $\rightarrow$ Interface} tab, Editing
 651 section, clicking on the edit boundaries can be set for LMB (Button 1), MMB (Button 2), RMB (Button 3) as one of the following:
 652
 653 \textit{Ripple}; \textit{Roll}; \textit{Slip}; \textit{Slide};
 654 \textit{Edge} or \textit{No effect}
 655
 656 Now to use this feature, create a track with edits that have trims
 657 on the left and/or the right. The edit boundary can be modified
 658 using \textit{drag handles} at the boundary between the edits
 659 (figure~\ref{fig:trim-display}).
 660
 661 \begin{figure}[htpb]
 662         \centering
 663         \includegraphics[width=1\linewidth]{trim-display.png}
 664         \caption{Split compositor screen showing the result of the Trim feature}
 665         \label{fig:trim-display}
 666 \end{figure}
 667
 668 \begin{description}
 669         \item[Left Mouse Button (LMB) usage:] If you grab the edit
 670         handle from the right side, you will see a left arrow and dragging
 671         the boundary will modify the right edit playback starting time. If
 672         you grab the edit handle from the left side, you will see a right
 673         arrow and dragging the boundary will modify the left edit playback
 674         ending time. In both cases, the composer will show the edit endpoint
 675         of the changed edit.
 676         \item[Shift LMB usage:] The effect on the edits is the same as
 677         described above, but the composer will show a split screen of the
 678         left and right edits as they appear at the drag handle
 679         boundary. Dragging will only change one of the two images, since
 680         only one edit is being changed.
 681         \item[Middle Mouse Button (MMB) usage:] Both the left and the
 682         right edit ending/starting times are updated.  The image shown in
 683         the compositor will be drawn from the side of the drag grab, that is
 684         the left if it is grabbed from the left, and the right if it is
 685         grabbed from the right.
 686         \item[Shift MMB usage:] The effect on the edits is the same as
 687         described above, but the composer will show a split screen of the
 688         left and right edits as they appear at the drag handle boundary.
 689         Dragging will change both of the two images, since both edits are
 690         being changed.
 691         \item[Right Mouse Button (RMB) usage:] The start/end point of
 692         the current edit is moved, but the edit length is unchanged only one
 693         image changes since only one edit endpoint is view is updated.
 694         \item[Shift RMB usage:] The effect on the edits is the same as
 695         described above, but the composer will show a split screen of the
 696         left and right edits as they appear at the drag handle boundary.
 697         Dragging will only change one of the two images, since only one edit
 698         is being changed.
 699 \end{description}
 700
 701
 702
 703
 704 \section{Nesting clips and assets}%
 705 \label{sec:nesting_clips_and_assets}
 706 \index{nested EDL}
 707
 708 \subsection{Nested Assets}%
 709 \label{sub:nested_assets}
 710 \index{nested assets}
 711
 712 A nested asset is an EDL session that
 713 embeds an existing EDL session, all tracks, all plugins, editing,
 714 and effects into a media object that appears as one audio/video
 715 media object, no plugins, editing, or effects.  It is as if the
 716 existing EDL was rendered, and loaded in its place.  This has
 717 several interesting side effects.  First, you don’t have to render
 718 the entire media file to see any portion.  Second, it requires no
 719 rendering compute time or storage.  Third, it changes the precedence
 720 of the composer so that you get more control over the projection and
 721 automation, so that the results can be sent into another rendering
 722 step, not simply part of the current stack.  It groups the plugin
 723 stack in much the same way that an arithmetic expression is grouped
 724 by parenthesis.
 725
 726 The EDL session and the rendered output are visually equivalent.
 727 Nested assets allow for complex grouping and stacking of effects,
 728 and makes media access much more flexible.  This feature can be used
 729 recursively, that is, any number of sessions may be stacked and
 730 referenced as an asset, as long as all of the rendering resources
 731 are available.  Nested assets are added to the timeline by using the
 732 pulldown \texttt{File $\rightarrow$ Load files}\dots on the main
 733 menu and selecting the \textit{Insertion strategy} of \textit{Nest
 734         asset}. The file will be pasted into the timeline over the current
 735 selection or at the insertion point.
 736
 737 It is somewhat important to note that nested assets and nested clips
 738 will have index files automatically created.  These index files can
 739 start to clutter up your \texttt{\$HOME/.bcast5} directory with
 740 files named \texttt{Nested\_\#\#\#.idx} and you may want to
 741 periodically delete any index files which are no longer in use.
 742
 743 \subsection{Nested Clips}%
 744 \label{sub:nested_clips}
 745 \index{nested clips}
 746
 747  It is also possible to create
 748 \textit{clips} and convert them to \textit{nested edl}.  This is
 749 done by first creating a clip using the standard cut, clipboard,
 750 paste, and/or edit panel buttons.  Now, using the resources
 751 \textit{clip} folder, select a clip to be nested, and use the right
 752 mouse button to select a clip.  This activates the clip popup menu.
 753 Select the \textit{Nest to media} menu item, and the clip will be
 754 converted to a \textit{Nested: Clip} and put in Media
 755 folder. Conversely, you can select a \textit{Nested: Clip}, use the
 756 \textit{EDL to clip} menu item, and the clip will be reverted to a
 757 \textit{Clip}.  This works similarly to the group / un-group editing
 758 features of many graphic design editing programs, but in this case
 759 the groups are rendered compositions (figure~\ref{fig:nesting}).
 760
 761 Nested clips can be proxied and when they are, the resulting files
 762 are placed in the user's \texttt{\$HOME/Videos} directory by default.  This
 763 can be modified by changing
 764
 765 \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface}
 766 tab, Nested Proxy Path.
 767
 768 \begin{figure}[htpb]
 769         \centering
 770         \includegraphics[width=1.0\linewidth]{nesting.png}
 771         \caption{Nested clips in Timeline and Resources window}
 772         \label{fig:nesting}
 773 \end{figure}
 774
 775 \paragraph{Notes:} creating nested clips is a complicated internal process for \CGG{}, especially for managing audio tracks. Therefore you need to make sure you have your project set up as you expect before you start nesting with the \texttt{Nest to Media} command.  Below are several things to remember.
 776
 777 \begin{itemize}
 778         \item The creation of the nested clip is based on the settings in \texttt{Settings $\rightarrow$ Format}. Be sure that the number of audio tracks and channels is the same as we want to have in the nested clip. In addition, it is better to make each audio track independent from the others (which could be linked in more than one channel) using the option: \texttt{Audio $\rightarrow$ Map 1:1}
 779         \item You can do any editing on the nested clip once it is loaded to the timeline. For example we can start an OpenEDL \index{openEDL} session to make the changes. Once out of the OpenEDL session it may be that the changes made are not visible in the original nested clip. You can fix this by doing RMB on the nested clip in the \textit{Resources/Media} window and choosing \texttt{Rebuild index}. This process may take some time depending on the size of
 780 the media; because of the additional time required to do this, it is not done automatically in order to allow the user to make the decision as to when they are done editing enough and need to see the exact results
 781 in order to save time.
 782         \item Because of the way the timeline thumbnails are displayed, after editing using OpenEDL of a
 783 nested clip, the thumbnails of the video track may be redrawn and may look different and out of sync with the
 784 way they did originally with respect to the audio waveforms. This is simply a result of the redrawing of the
 785 video track which is independent from the redrawing of the audio tracks. The playback is still synchronized.
 786 \end{itemize}
 787
 788 \paragraph{Usage Examples of Nested Clips}
 789
 790 \begin{description}
 791         \item[Example 1:] You want to make a flashback/rewind at the end
 792         of your video that represents a quick summary of the entire video in
 793         black and white. On he timeline, you have 60 seconds of edits with
 794         clips, cuts, zoom in, zoom out and any other edits. Now you want to
 795         get this 60 seconds \textit{compressed} to 10 seconds, play in
 796         reverse, and in black and white at the end of your video.  You would
 797         copy the 60 seconds in a clip, nest the clip in the Clip folder of
 798         the Resources window and drag it to the timeline. You will see only
 799         a clean clip without all of the edits that were used to create it
 800         because nesting display a clip without having to actually use the
 801         Render menu.  Now you can add a Reverse effect, Color3way plugin for
 802         black and white, and use the Speed auto to get the 60 seconds down
 803         to only 10 seconds.
 804         \item[Example 2:] You are working on a complex project with a
 805         team in a separate location. You create some sub projects, i.e.\
 806         sequences, that you or the team will use in the Master project to
 807         merge the sequences in the right order and to make the final color
 808         correction steps.
 809 \end{description}
 810
 811 In each of the examples you can see the benefit of nesting to create
 812 clean looking timelines because of the automatic rendering
 813 capability of nesting.
 814
 815 \section{Multi-Camera / Mixer}%
 816 \label{sec:multicamera_mixer}
 817 \index{multi-camera}
 818 \index{mixers}
 819
 820 Use the Mixer Viewer to see multiple media playing simultaneously in re-sizable mini-viewers.  This can be used in various ways and is useful to edit videos shot by multiple cameras from different viewpoints that were simultaneously recorded in order to create a single good video.  Everything will have to be initially synced so you can decide which one of the camera angles is best suited at any time. Mixer mode does not support audio only tracks but there is a workaround described at \nameref{cha:faq_problems_workarounds}.
 821
 822 The number of cameras/mixers you can have is generally limited to the available resources on your computer.  Currently, the number of File Descriptors available in the OS limits cameras to about 50.  If you have many \textit{mixer viewers} you will probably want to use proxy mode whenever possible.  Also, in the \texttt{Settings $\rightarrow$ Playback A} tab \textit{Video Out} section, uncheck \textit{play every frame} and choosing a Video Driver of \textit{X11} with \textit{use direct X11 render if possible} checked, will provide better performance.
 823
 824 Figure~\ref{fig:multicam01} shows 9 media sources in the left corner, the composed video in the right corner, the timeline with the top video track with pieces of the 9 overwrites, and the choice in Resources of Mixed.
 825
 826 \begin{figure}[htpb]
 827         \centering
 828         \includegraphics[width=1.0\linewidth]{multicam01.png}
 829         \caption{Using Mixer capability in Cin for multiple cameras}
 830         \label{fig:multicam01}
 831 \end{figure}
 832
 833 \subsubsection*{Easiest Method to Getting Started}%
 834 \label{ssub:easiest_method_started}
 835
 836 \begin{enumerate}
 837         \item This method assumes all of your media or cameras are aligned the way you want them already.
 838         \item From the \textit{File} pulldown, create a \textit{New project} with the desired format for Audio and Video output (or you can just use the default).
 839         \item \texttt{File $\rightarrow$ Load} the media files you want to work with using \textit{Create new resources only}.
 840         \item In the Resources window, with  the Media folder, highlight the list of media you want to \textit{Mix}. This is done using a ctrl or shift mouse button press as you would in a standard listbox selection.
 841         \item Right click the mouse on the media selection and choose \textit{open mixers} \index{mixers!open mixers}. This opens multiple mixer viewer \index{mixers!viewer} windows, one for each media item that was highlighted.  You can
 842         do them 1 at a time instead.  This also adds the source media tracks to the main window.
 843         \item Now use the timeline \index{timeline} to play and you will see all viewers/cameras playing.  Stop when you get to the
 844         end of the \textit{good} camera playback.
 845         \item Simply double click the \textit{good} mixer viewer and from where you first started playing to the playback insertion pointer is the source section, which will be pasted in the destination video/audio tracks at the top of the new project.
 846         \item Repeat steps 6-7.  Start playing again, stop when you want, double click the desired mini-viewer!
 847 \end{enumerate}
 848
 849 \subsubsection*{Some Hints and Caveats}%
 850 \label{ssub:hints_caveats}
 851
 852 \begin{itemize}
 853         \item You can easily overwrite a section of the new track by \textit{selecting} a section on the timeline, then double click on one of the mini-viewers to overwrite/replace that section.
 854         \item If you edit the output tracks, it only edits output tracks, and the input tracks may no longer be lined up.
 855         \item You can add a silent section by selecting past a section and start overwriting that section from then on.
 856         \item If you use the cursor hairline to create the selection endpoint, it must be past the end of the destination.
 857         \item The compositor shows composed media.  This is the media that will be rendered.
 858         \item The program always uses overwrite as the paste operation.
 859         \item Use the timeline edit handles to move the start and end points of that section.
 860         \item Only middle mouse drag handle operations should be used normally.
 861         \item Other drags will displace the media source/destination timeline correspondence.
 862         \item To re-tile the mixer windows after you have resized and moved them around, you can use the Window
 863         pulldown of \textit{Tile mixers} or the shortcut of Alt-t.
 864 \end{itemize}
 865
 866 \subsubsection*{But, I want to use only the first set of audio tracks\dots}%
 867 \label{ssub:but_use_only_first_audio}
 868
 869 There are many cases where you may want to compose using media from several different tracks while using the the same audio tracks as associated from a specific viewer.  Since mixer source tracks can be updated any time by using a mixer toggle\index{mixers!toggle}, this makes it possible to do this.
 870
 871 Procedure to update the mixer audio source track list:
 872
 873 \begin{enumerate}
 874         \item Single click to highlight the mixer window you want to re-associate to the audio track.
 875         \item In that audio track’s patchbay click the expand toggle, the arrow on the right side.
 876         \item In the expanded pane that appears, there is another arrow on the left side.  This icon has the tooltip \textit{Mixer}.  Click this and because in step \#1 you highlighted the mixer window, it will now be toggled on.  Once you click the mixer icon it will then point up.
 877         \item Now, disassociate any audio that is unwanted by expanding its patchbay and toggling off the mixer.
 878 \end{enumerate}
 879
 880 \subsubsection*{Expert Usage}%
 881 \label{ssub:expert_usage}
 882
 883 When you double click a mixer viewer window, it operates an \textit{overwrite} paste operation.  This moves \textit{src} (source) track edits to \textit{dst} (destination) track edits over the same selected timeline region.
 884
 885 \begin{itemize}[noitemsep]
 886         \item \textit{Src tracks} should be not playable and not armed in the main window patchbay gui.
 887         \item \textit{Dst tracks} should be playable and armed in the main window patchbay gui.
 888 \end{itemize}
 889
 890 Each mixer viewer maintains a list of the tracks which will be used as src. This list is made visible selecting the window with the left mouse button.  When the mixer viewer is selected, a highlight is drawn around the media image.  All track patchbay \textit{mixer} toggles are updated to reflect the src tracks included in the selected viewer src track list. The \textit{play track} patchbay toggles can be used to manage the list.
 891
 892 \begin{itemize}[noitemsep]
 893         \item \textit{Turning on} a toggle (pointing up) includes the track in the src track list.
 894         \item \textit{Turning off} a toggle (pointing right) removes the track from the src track list.
 895 \end{itemize}
 896
 897 New Mixer viewers can be created using the main menu \texttt{Window $\rightarrow$ Mixer Viewer}, or with a shortcut of \texttt{Shift-M}.  When a new viewer is created, the currently enabled patchbay \textit{mixer} toggles are used to create the viewer source track list.  The toggles are cleared after the window is created.  This is to improve the work flow.  Use the following list of steps to create individual mixer viewers.
 898
 899 To create a list of mixer viewers:
 900
 901 \begin{enumerate}
 902         \item Setup the session \texttt{settings $\rightarrow$ format}, width, height, frame rate, color model, aspect ratio.
 903         \item Create dst tracks using the a/v track pulldowns (or use shortcuts "t" / "T"),  armed and playable.
 904         \item Append src tracks using \texttt{file $\rightarrow$ open $\rightarrow$ append tracks}, or the resource window using pasting.
 905         \item Using the track patchbay, disarm editing and disable playback of the audio/video src tracks.
 906         \item Using the track patchbay, mark the new tracks as \textit{mixer} source to be added to the viewer.
 907         \item Create a mixer viewer using the main menu pulldown, or the shift "M” shortcut.
 908         \item Repeat steps $3-6$ for each mixer viewer needed for the session editing.
 909 \end{enumerate}
 910
 911 When you single click a mixer window, it becomes selected and highlighted and all of the patchbay mixer toggles are updated to reflect the state of the viewer’s src tracks.  Tracks that will be src are shown as enabled.  If you change a toggle, the src tracks for the selected window will be modified.  This means you can associate or dis-associate any media track to any mixer window.
 912
 913 When you double click a mixer window, an overwrite paste is invoked.  The mixer viewer’s src tracks are overwritten to the dst tracks.  The timeline region for both the source and destination are the same for the overwrite paste function.  The selection region is used if it is active.  If the selection is empty, that is it is a hairline, the selection region is from the end of the destination playable edits to the selection cursor hairline.  The hairline must be past the end of the playable edits on the destination tracks.
 914
 915 The mixer viewer configuration is saved with the session data.  When a saved session is loaded in \textit{replace project} or \textit{replace project and concatenate tracks}, the mixer viewer will be reopened.
 916
 917 \subsubsection*{Using Proxy with \textit{Open Mixers}}%
 918 \label{ssub:using_proxy_open_mixers}
 919
 920 The best way to use proxy \index{proxy} with your multiple cameras is to follow the steps below:
 921
 922 \begin{enumerate}
 923         \item Load media with insertion strategy of \textit{create resources only}.
 924         \item Highlight the media in the Resources window and right click on this to choose \textit{open mixers}.
 925         \item Use the \texttt{Settings $\rightarrow$ Proxy settings}\dots to bring up the proxy menu.
 926         \item Choose the size and other options you want and click the checkmark OK. If you choose the option \textit{Beep when done} you will hear a short beep if all media is already proxied or a longer beep when all proxies have been created.
 927         \item When your editing is complete, use \textit{Settings} pulldown and proxy to \textit{original size}.
 928 \end{enumerate}
 929 Instead of Open Mixers, you can Insert Mixers \index{mixers!insert mixers} with new tracks at the timeline insertion point.
 930
 931 \subsubsection*{Options available in the \textit{Mixer Windows}}%
 932 \label{ssub:options_available_with_mixers}
 933 \index{mixers!viewer RMB options}
 934
 935 There are several options you will see in each Mixer viewer \index{mixers!viewer} that help with using them. These
 936 are shown in figure~\ref{fig:mixer-playable}. To use these, RMB in the desired mixer window,
 937 and choose one of the options as described here.
 938
 939 \begin{figure}[htpb]
 940         \centering
 941         \includegraphics[width=1.0\linewidth]{mixer-playable.png}
 942         \caption{A Mixer window showing available options with the white X designating no playing}
 943         \label{fig:mixer-playable}
 944 \end{figure}
 945
 946 \begin{enumerate}
 947         \item Fullscreen / Windowed - will bring up a fullscreen display of that window or revert to the original size.
 948         \item Resize Window - allows for resizing the window to a choice of different sizes.
 949         \item Tile Mixers \index{mixers!tile mixers} - makes it easy to get all of the mixers nicely tiled to a standard size.
 950         This is also available in the \textit{Window} pulldown.
 951         \item Playable - enabled by default so that you will see a checkmark next to it in the
 952         popup.  The benefit of making a mixer window not playable is to save cpu time. When a specific
 953         mixer window is unchecked, so not Playable, a white cross appears in the upper left hand corner
 954         of the mixer.  To switch back to playing again, RMB and choose Playable and this will turn
 955         playing back on. The program automatically updates the mixer image when the timeline cursor
 956         stops or when it is moved to a different spot even when play is disabled. You can see the
 957         white cross designating not playable in figure~\ref{fig:mixer-playable}. Statistics that show
 958         the savings are as follows on a 16 cpu laptop:
 959         \begin{verbatim}
 960         5 Mixers all playing -- cpu usage = 1275
 961         1 only playing       -- cpu usage =  405
 962         2 only playing       -- cpu usage =  800
 963         \end{verbatim}
 964 \end{enumerate}
 965
 966 \subsubsection*{Mixers pulldown}%
 967 \label{ssub:mixers_pulldown}
 968
 969 From Program windows menu we can access the \texttt{windows $\rightarrow$ mixers...} there are several entries available (see figure~\ref{fig:mixers-pulldown}):
 970
 971 \begin{figure}[htpb]
 972         \centering
 973         \includegraphics[width=0.5\linewidth]{mixers-pulldown.png}
 974         \caption{Mixers...  pulldown}
 975         \label{fig:mixers-pulldown}
 976 \end{figure}
 977
 978 \begin{description}
 979         \item[Mixer Viewer:] \index{mixers!viewer} (Shift-M) opens a new empty \textit{Mixer 1} window, which will then be associated with a track. We can open as many Mixers as we like.
 980         \item[Drag Tile mixers:] \index{mixers!drag tile mixers} (Alt-t) the default size of a mixer window is related to the std size of the \textit{Viewer} window. If we want to modify it at our convenience, we can build a window of the desired size with the \textit{Drag Tile mixers} function and then automatically order our mixers within it with the right click of the mouse.
 981         \item[Align mixers:] \index{mixers!align mixers} see \nameref{sub:audio_video_sync_waveform}
 982         \item[Mix masters:] \index{mixers!mix masters} this feature makes it very easy to get into the multi-camera mixer mode after tracks have already been set up and edited. Before this addition, you could only \textit{Open Mixers} from original media assets in the \textit{Resources} window.
 983         \item[Entries:] If the mixers of several sources have been opened, the entries of each assets will appear, useful for recalling a specific mixer window.
 984 \end{description}
 985
 986 \subsection{Recover Mixer Windows}%
 987 \label{sub:recover_mixer_windows}
 988 \index{mixers!recover mixer window}
 989
 990 It is a hazard that you might accidentally \textit{undo} (\texttt{z or Ctrl-z}) too far and lose your mixer windows.  Here are the steps to recover.  It is recommended that you make a backup of your project before performing the recovery steps just in case there are other problems.
 991
 992 In the patchbay box to the left of the main timeline, there is a right pointing arrow on the right side.  This is called the \textit{Expander} (figure~\ref{fig:mixer-patchbay01}).  When you click on each expander, another line appears below that expander arrow and the timeline track height is slightly increased.  If you Shift-click on a single expander, the patchbay will expand for all of the tracks.
 993
 994 \begin{figure}[htpb]
 995         \centering
 996         \includegraphics[width=0.35\linewidth]{mixer-patchbay01.png}
 997         \caption{Mixer  patchbay}
 998         \label{fig:mixer-patchbay01}
 999 \end{figure}
1000
1001 \begin{enumerate}
1002         \item Expand all of the patchbay lines, either one by one, or Shift-click on one to do them all. This is so you can see the \textit{mixer} right pointing arrow on the second expanded line.
1003         \item Use the \textit{Window} pulldown and choose \textit{Mixer Viewer} to bring up a new mixer window.  Now you will be making an association between the mixer viewer and the track’s video.
1004         \item Click on the new mixer window to make sure it is highlighted with a white border. This designates it as the \textit{in use} mixer viewer.
1005         \item Set your play to the beginning of the video using the \textit{Home} key or \textit{Home} transport button.
1006         \item In the patchbay for a video track click on the \textit{mixer} arrow on the expanded $2^{nd}$ line which is a right facing arrow.  Now the arrow will point up.  If there are audio tracks with that video, click on each of its audio tracks \textit{mixer} arrow until they point up also.
1007         \item Next move your insertion pointer on the timeline where there is video.  Some of the time this just helps so that the new mixer viewer window gets redrawn and you can see that the images appear; but the image may not appear until the program does a redraw later.  Now the mixer viewer should be
1008         correctly associated.  Note if you have large video, give it some time to update.  You may have to click on the mixer viewer window if the image does not show.  You can always start over with that mixer if you encountered any problems.
1009         \item Click the arrows that are pointing up in that video and its audio so they go back to pointing right. That mixer viewer is complete so you need to do this to make sure the \textit{mixer} arrows are off.
1010 \end{enumerate}
1011
1012 Repeat steps 2 through 7 for each of the mixer viewers you need going down the patchbay starting on step 2 first with Mixer 1, then 2 to 7 steps for Mixer 2, then again run 2 to 7 for Mixer 3 and so on.
1013
1014 Sometimes the association does not stick initially.  If not, highlight the mixer viewer with the problem, change the mixer arrows to point up, and reassociate.
1015
1016 % For html, make sure using below is different from via in subsection
1017 \section{Audio/Video sync using Waveforms/Timecodes}%
1018 \label{sec:audio_video_sync}
1019 \index{audio/video sync}
1020
1021 \subsection{Audio/Video sync via Waveform}%
1022 \label{sub:audio_video_sync_waveform}
1023 \index{audio/video sync via waveform}
1024
1025 Multi-camera \index{multi-camera} footage of a single event can have various shots starting and ending at different times. So when the footage start times are different, you can use the mixer audio to synchronize the clips on the timeline. The program algorithm attempts to find and align automatically the waveforms of the media.
1026
1027 Synchronizing multiple camera videos based on audio tracks can be done with \CGG{} easily enough with the \texttt{Window $\rightarrow$ Mixers$\dots$ $\rightarrow$  Align mixers} option.  Align mixers brings up a window displaying your mixers, the currently selected Master Track, and a list of all of the Audio Tracks (figure~\ref{fig:mixer-align01}).  There is a limit of 32 audio tracks per each mixer (that should be enough!)
1028
1029 \begin{figure}[htpb]
1030         \centering
1031         \includegraphics[width=0.9\linewidth]{mixer-align01.png}
1032         \caption{Align Mixers window}
1033         \label{fig:mixer-align01}
1034 \end{figure}
1035
1036 Two different methods of aligning the audio for mixers are available. They are most easily referred to by the button that is pressed -- \textit{Match} and \textit{Match All}. There are also 2 methods of activating the alignment -- \textit{Apply} and \textit{Move}.
1037
1038 \textit{Match} consists usually of the next set of steps to take advantage of this feature:
1039
1040 \begin{enumerate}
1041         \item Load your camera media with insertion strategy of \textit{resources only}
1042         \item Highlight in the Resources window, all of the media you want to mix.
1043         \item Right mouse button on one of the media and click on Open Mixers; all mixer windows come up.
1044         \item To arm the created mixer tracks and related audio tracks. They are automatically placed on the timeline disarmed. This is right for multi-cam but not for audio sync.
1045         \item Provide a small target audio pattern on the Master Track for syncing by marking with the In/Out points ([ and ]). NOTE: When choosing between the audio tracks to align the one that will have to work as Master, we must rigorously use the one with the right-most synchronization peak. This is because the Master track will be started at the beginning of the timeline. If during alignment the other tracks should move further to the left than the Master, they will be truncated at 00:00:00:000, finding no more space available, and will be shortened with loss of footage for the next multi-cam
1046         \item Make a selection on the timeline in which to look for the pattern. Left mouse click, then drag select and highlight a search time domain.
1047         \item Use the \texttt{Window $\rightarrow$ Mixers$\dots$ $\rightarrow$  Align mixers} to bring up its dialog window.
1048         \item Highlight in the first listbox, the Mixer number you want to align. Click on \textit{Match}. This will take a few seconds so watch the rendering time percentage on the lower right hand side zoom panel. The buttons will be ghosted out until finished. Now note the changed values in the Audio Tracks listbox.
1049         \item If you are satisfied with the calculated Nudge values -- that is they are very close to $1.0$ -- in the Audio Tracks listbox and the audio track selected as the Master Track in the Master Track listbox, hit the \textit{Apply} button.
1050         \item If you plan on performing more alignment tasks, click on Checkpoint so you can go back to a previous step in case you make a mistake.
1051         \item Last, click on the OK green checkmark or to cancel click on the red X.  Or just close the gui.
1052         \item To disarm the mixer tracks and related audio tracks for the next multi-cam operations.
1053 \end{enumerate}
1054
1055 \paragraph{Reset} is used to start over with the current session data, not an undo.  This means you can use the match repeatedly to refine alignments.  All of the Audio Tracks listbox values will be reset.
1056
1057 \paragraph{Checkpoint} provides a method to create checkpoints that save the current state.  This is especially helpful while learning or doing more complicated operations where you might make a mistake or do not like the results and need to get back to a previous state.
1058
1059 \paragraph{Undo} is used to put the media back to a previous state on the timeline.  If you choose \textit{start over} the session will reload with the original, before any changes were applied.  You can also go back to any of your previous checkpoints that you created earlier which are listed there, such as \textit{chkpt 1}.
1060
1061 \paragraph{Match All}is used when you have several mixers, instead of only picking 1 to match, it picks the best match for EACH of the mixer tracks based on a single master track. So when you hit Apply, each track might move differently. You do not set In/Out points but you have to make a selection within which to match.
1062
1063 \paragraph{Apply} button will apply the nudges that were generated during the Match or Match All execution (figure~\ref{fig:mixer-align02}).
1064
1065 \begin{figure}[htpb]
1066         \centering
1067         \includegraphics[width=0.9\linewidth]{mixer-align02.png}
1068         \caption{Aligned mixer window after "Match". Note the Nudge amounts above.}
1069         \label{fig:mixer-align02}
1070 \end{figure}
1071
1072 \paragraph{Move} is very handy when you are using mixers, if you have an edit somewhere that you need to fix specifically without moving any of the other track pieces. In this case you have to select a section (like you do a group, but do not make a group), generate a match, and then you can just \textit{Move} that set only -- everything else stays where it is at its current location (figure~\ref{fig:mixer-align03}).
1073
1074 \begin{figure}[htpb]
1075         \centering
1076         \includegraphics[width=1.0\linewidth]{mixer-align03.png}
1077         \caption{Match setup for aligning by audio.  Note that [ ] are set over a sample waveform highlighted selection that includes that.}
1078         \label{fig:mixer-align03}
1079 \end{figure}
1080
1081 More detailed information follows about how this all works and the information in the dialog window.  It is important to know that the result of the calculation is \textit{best match} but you can still override the selections if you decide there is a better one.  The dialog window is split into 3 sections:
1082
1083 \begin{enumerate}
1084         \item \textit{Mixers} lists the mixers that are active by highlighting them all initially. You can decide that you do
1085         not want 1 or more mixers to be used in the correlation calculation by un-highlighting the one(s) that should not be used. In some cases you have to have at least 2 in order to align audio.
1086         \item \textit{Master Track} lists each of the audio tracks currently loaded for all of the mixers. You can decide to highlight a different audio track to be used as the master for correlation, but only 1 can be used. Remember to use the track with the right-most synchronization peak as the Master.
1087         \item \textit{Audio Tracks} lists each of the mixer audio tracks.  Again, you can highlight a different set of which
1088         mixer audio tracks that you want to use for the waveform correlation.  Any audio tracks that are not
1089         highlighted, that is \textit{turned off}, will not be considered in the correlation calculation.
1090 \end{enumerate}
1091
1092 The corresponding input position is determined by track input correlation.
1093
1094 The letter "R" in the Audio Tracks listbox represents the correlation value.  $R=1.0$ designates that if both the pattern and the matching section were in the highlighted area, they are completely correlated -- this is a good self-test to check.
1095 $Nudge=0.0$ means just that.
1096
1097 The header \textit{pos} stands for the timeline position. When the \textit{Apply} button is pressed, only the Mixers listbox is relevant at that time.
1098
1099 The Mixer with the master track generally does not move, everything else will be lined up (figure~\ref{fig:mixer-align04}).
1100
1101 \begin{figure}[htpb]
1102         \centering
1103         \includegraphics[width=1.0\linewidth]{mixer-align04.png}
1104         \caption{An audio Match is complete. Note the waveform is aligned.}
1105         \label{fig:mixer-align04}
1106 \end{figure}
1107
1108 \textit{Match All} option basically consists of the following steps:
1109
1110 \begin{enumerate}
1111         \item Highlight the Mixer to use in the Mixer listbox.
1112         \item Highlight the Master Track you want to use in the Master Track listbox.
1113         \item On the timeline, mark your selection on the Master Track.
1114         \item Click on the \textit{Match All} button.
1115         \item Note the nudge values to see if they make sense, and if so, press \textit{Apply}.
1116 \end{enumerate}
1117
1118 \textit{Match} option basic steps (just for comparison with Match All):
1119
1120 \begin{enumerate}
1121         \item Set the In/Out points [ ] of the target.
1122         \item On the timeline, mark your selection.
1123         \item Click on the \texttt{Match} button.
1124         \item Note the nudge values to see if they make sense, then press \textit{Apply} (or \textit{Move} when doing a group).
1125 \end{enumerate}
1126
1127 \subsection{Align Timecodes}%
1128 \label{sub:align_timecodes}
1129 \index{audio/video sync via timecodes}
1130 \index{align timecodes}
1131
1132 Align Timecodes is especially useful in the case where you create video with multiple cameras capable of recording a timecode in the metadata of each file.  Let’s say we have recorded three videos at the same time at a concert with each camera set up at unique positions and at different angles.   All of the cameras start recording at various times but were synchronized with the same master clock (\textit{Timecode Sync Generator} or \textit{Jam Sync timecode}) so that the recordings are timestamped with that synchronized time.  For example, the 3 cameras have embedded metadata as follows: \quad \textbf{camera 1} = 00:00:00:01 \quad \textbf{camera 2} = 00:00:10:07 \quad \textbf{camera 3} = 00:00:17:22
1133
1134 \begin{figure}[ht]
1135         \centering
1136         \includegraphics[width=1.0\linewidth]{timecode-01.png}
1137         \caption{Before sync}
1138         \label{fig:timecode-01}
1139 \end{figure}
1140
1141 Timecode synchronization is performed by the program when you choose the option \textit{Align Timecodes} and works in 2 steps. The first automatic step is to locate the earliest timecode \index{timecode} and the second step is to align the edits on the armed tracks using that time on the timeline.
1142
1143 When you load in the three files to different tracks, they'll be placed on a timeline that starts from $00:00:00:00$ as usual. But, by middle mouse clicking (MMB) on any of the video tracks, you can view the timecode embedded at that point in that file.
1144
1145 To make it easy to align the videos onto the timeline manually, set the \textit{origin point}, that is the leftmost time index, of the timebar to the timecode of the earliest video.  For the 3 aforementioned cameras this would be camera 1 with a timeecode of $00:00:00:01$.  By using the \textit{clapboard} button on the main timeline, you can set $00:00:00:01$ as the start timecode. Then positioning the camera 1 video at the start of the timeline will line its frames up with the times on the timebar.
1146
1147 \begin{figure}[ht]
1148         \centering
1149         \includegraphics[width=1.0\linewidth]{timecode-02.png}
1150         \caption{Clapperboard button}
1151         \label{fig:timecode-02}
1152 \end{figure}
1153
1154 Similarly, using the middle mouse button to view the other 2 camera’s timecodes, you can position them  so their timecodes line up and now all three tracks will be in sync.  You can do this manually or simply do it automatically with the option under: \texttt{Tracks  $\rightarrow$  Align Timecodes}. See figure~\ref{fig:timecode-03}
1155
1156 \begin{figure}[ht]
1157         \centering
1158         \includegraphics[width=1.0\linewidth]{timecode-03.png}
1159         \caption{After sync}
1160         \label{fig:timecode-03}
1161 \end{figure}
1162
1163 Timecode synchronization in \CGG{} is based on the inclusion of an actual \textit{timecode} saved in
1164 the media as can be seen using the \texttt{ffprobe} or \texttt{mediainfo} command line. Examples are shown here:
1165
1166 \begin{lstlisting}[style=sh]
1167 # ffprobe tut1.mov
1168 Metadata:
1169 handler_name:   VideoHandler
1170 timecode:               00:00:20:01
1171
1172 # mediainfo mtb.mp4
1173 Time code of first frame:       11:05:49:41
1174 Time code, striped:             Yes
1175 Title:                          GoPro AVC
1176 \end{lstlisting}
1177
1178 Many newer cameras and media in a MOV container have valid timecodes often with SMPTE
1179 compliant start Timecode in Quicktime format, whereas others do not. Most low end cameras do not.
1180 When no timecode is present, various clock time values may be used to synchronize instead.
1181
1182 There are various types of timecodes and they are written in metadata in various ways. Because it is not clear which timecode in the file is the one to use or there is none, the precedence as described next is followed. The contexts, packets, streams, and data refer to the corresponding ffmpeg data or metadata objects:
1183
1184 \begin{enumerate}
1185         \item if the format context has a timecode use: \texttt{fmt\_ctx $\rightarrow$ timecode - 0}
1186         \item if the layer/channel has a timecode use: \texttt{st $\rightarrow$ timecode - (start\_time -nudge)}
1187         \item find the first program stream with video stream, and if the video stream has a timecode use:
1188         \texttt{st $\rightarrow$ timecode - (start\_time-nudge)}
1189         \item find timecode in any stream use: \texttt{st $\rightarrow$ timecode}
1190         \item read 100 packets, save \texttt{ofs=pkt.pts*st $\rightarrow$ time\_base - st $\rightarrow$ nudge}:
1191         \begin{itemize}
1192                 \item decode frame for video stream of the first program
1193                 \item if \texttt{frame $\rightarrow$ timecode} has a timecode use:\texttt{ frame $\rightarrow$ timecode - ofs}
1194                 \item if side\_data has gop (group of pictures) timecode use: \texttt{gop $\rightarrow$ timecode - ofs}
1195                 \item if side\_data has smpte timecode use: \texttt{smpte $\rightarrow$ timecode - ofs}
1196         \end{itemize}
1197         \item if the \texttt{filename/url} scans \texttt{*date\_time.ext} use: \texttt{date\_time} (yr, month, day, hr, min, sec, nanosecond)
1198         \item if stat (display file status) works on the \texttt{filename/url} use: \texttt{mtime} (modification time)
1199         \item finally, if none of the above are usable, then return \texttt{failure}
1200 \end{enumerate}
1201
1202 Operation of Align Timecodes includes the following options to help in your setup and review (figure~\ref{fig:timecode-04}):
1203
1204 \begin{figure}[ht]
1205         \centering
1206         \includegraphics[width=1.0\linewidth]{timecode-04.png}
1207         \caption{Timecode via MMB on track and via Resources windows/Info}
1208         \label{fig:timecode-04}
1209 \end{figure}
1210
1211 \begin{itemize}
1212         \item \textit{Align Timecodes} under the \textit{Tracks} pulldown
1213         \item \textit{Clapperboard} icon on the main timeline to set a timecode.
1214         \item Timecode option added to timebar choices (in timecode $hh:mm:ss:ff$) with use of the session frame
1215         rate as a time standard.
1216         \item Time Code Start in the Resources window on the bottom of \textit{Info} for the media if the timecode for that
1217         asset has been scanned and is known. You can scan the asset’s Timecode by using the middle mouse
1218         button on its track which then displays the timecode for that on the timebar (\texttt{MMB $\rightarrow$ Timecode}). Or you can use the shortcut \texttt{Ctrl+!}, after selecting the edit/track on the timeline.
1219 \end{itemize}
1220
1221 \paragraph*{Notes}
1222
1223 \begin{itemize}
1224         \item \textit{Align Timecodes} is a good first step to quickly sync media up either perfectly or roughly.
1225         \item Currently this is not known to function for syncing audio recorded on a separate audio device,
1226         because no test material was provided to ensure that this works.
1227         \item Disarmed tracks will not be affected by using \textit{Align Timecodes}.
1228         \item No edits or sections will get cut off on the left or elsewhere, unless the moved edits overlap.
1229         \item You can add a timecode to video using an \texttt{ffmpeg} command if you want to align a particular video
1230         which has no timecode to ones that do. For example:
1231 \end{itemize}
1232
1233 \begin{lstlisting}[style=sh]
1234 ffmpeg -i originalfile.mp4 -metadata timecode="14:36:08:29" -c copy newfile.mp4
1235
1236 # where "-i" is followed by the input filename
1237 # where "-metadata timecode" is followed by the timecode key
1238 # where "-c copy" just copies the video/audio to the following output filename
1239 \end{lstlisting}
1240
1241 \section{Subtitles}%
1242 \label{sec:subtitles}
1243 \index{subtitles}
1244
1245 \CGG{} can create subtitles directly in the timeline with the Subtitle tool. Subtitles are added by using the main window pulldown   \texttt{File $\rightarrow$ Subtitle} (Alt-y)  which brings up a window allowing you to type the filename of a previously generated text file containing the desired words/lines, the script.  After entering the filename, click \texttt{Load} to read in your script.  By creating a script file ahead of time, it lets you easily add dialog that was already written out and carefully edited for spelling and proper grammar.
1246
1247 The file must be plain text; a .srt or .sub can also be used, but only the text lines will be used and not the timecodes or comments. The format of the script/text input file has specific requirements as listed below:
1248
1249 \begin{itemize}
1250         \item Lines can be any length but they will be broken up to fit according to some criteria below.
1251         \begin{itemize}
1252                 \item Running text used as script lines will be broken into multiple lines.
1253                 \item The target line length is 60 characters.
1254                 \item Punctuation may be flagged to create an early break.
1255                 \item Single carriage return ends an individual script line.
1256                 \item Double carriage return indicates the end of a entry and helps to keep track of where you are.
1257         \end{itemize}
1258         \item The "\textit{=}" sign in column 1 indicates a comment seen in the script text to assist you in location.
1259         \item An "\textit{*}" at the beginning of the line is a comment and not a script line.
1260         \item \textit{Whitespace} at either the beginning of a script line or the end will be removed.
1261 \end{itemize}
1262
1263 Figure~\ref{fig:subtitle01} shows the Subtitle window you will see.
1264
1265 \begin{figure}[htpb]
1266         \centering
1267         \includegraphics[width=0.8\linewidth]{subtitle01.png}
1268         \caption{Subtitle window}
1269         \label{fig:subtitle01}
1270 \end{figure}
1271
1272 To put the subtitles onto your media, first add a subtitle track via the pulldown  \texttt{Tracks $\rightarrow$ Add subttl} (Shit-Y). In the Subtitle window, note that there are 2 major textboxes.  There is the \textit{Script Text} textbox showing the current entry of text from your input file and there is the \textit{Line Text} textbox showing the currently active text.  In your subtitle track, select a timeline region (in/out or drag select with hairline cursor/highlight or via labels or the \textit{selection start/length/end time} textboxes in the Zoom Panel) to indicate the region where you want the active Line Text to be pasted.  Then click the \texttt{Paste} button in the Subtitle window to paste the line onto the subtitle track.  Silence will be added to the subtitle track in the places in the media where there are gaps.
1273
1274 Editing in the Line Text box can be used to change the active script line. By double clicking the timeline over the subtitle track, you can reselect the active script line.  The subtitle text will be reloaded into the Line Text box and can be edited and re-pasted as the new active subtitle text.  You can also highlight multiple lines in the Script Text box and paste them (using the usual window paste methodology) into the Line Text box.  After pasting to the timeline, the Line Text box will be updated with the next script line.  In addition, if you triple click a line in the \textit{Script Text} box, it will automatically become the current line in the \textit{Line Text} box.
1275
1276 When you are finished, before clicking on \textit{Save}, you can specify the output format using the \textit{Format} drop-down button. You can choose between the classic \texttt{.udvd} (micro DVD) and the more universally supported \texttt{.srt} (subrip) and \texttt{.sub} (subviewer). The next step is to provide a legitimate filname in the \textit{Path} box; your current directory will be used if only a filename but no directory path is supplied.  The filename used will automatically have a "--" after it followed by the \textit{track label} and then \textit{udvd/srt/sub} extension added; any extension in the filename will be removed..  If you click OK before saving, the subtitle script position is saved with the session.  This is convenient for continuing where you left off.
1277
1278 To reposition the script, use the slider or tumbler buttons:
1279
1280 \textit{Slider} bar to move through the text entries quickly. \\
1281 \textit{Prev} or \textit{Next} buttons to go to the previous or next script line.
1282
1283 Figure~\ref{fig:subtitle02} shows what the pasted subtitle script looks like in a portion of the main window.
1284
1285 \begin{figure}[htpb]
1286         \centering
1287         \includegraphics[width=1.0\linewidth]{subtitle02.png}
1288         \caption{Subtitles on timeline}
1289         \label{fig:subtitle02}
1290 \end{figure}
1291
1292
1293