minor updates for Timecode by Andrea
[goodguy/cin-manual-latex.git] / parts / Editing.tex
1 \chapter{Editing}%
2 \label{cha:editing}
3
4 Editing comprises both time and track space.  The timeline consists
5 of the time certain media appear on the track going left to right
6 and a set of tracks from the top to the bottom.  There are 2 methods
7 of timeline editing -- drag and drop editing \index{drag and drop}, also called
8 \textit{arrow mode} \index{arrow}, and cut and paste editing \index{cut and paste} or \textit{I-beam
9   mode} \index{i-beam}.  Cut and Paste is the default editing mode.  An additional,
10 but not often considered editing method is called \textit{two-screen
11   editing} \index{two-screen} (or 3 point editing) where the Viewer is used to view media and then the
12 desired clip from the media is transferred to the timeline.
13
14 The timeline \index{timeline} is where all editing decisions are made
15 (figure~\ref{fig:timeline}).  This is a stack of tracks in the
16 center of the main window.  It can be scrolled up, down, left and
17 right with the scrollbars on the right and bottom.  It can also be
18 scrolled up and down with a mouse wheel, or left and right while
19 holding down the Ctrl key and using the mouse wheel.
20
21 \begin{figure}[htpb]
22   \centering
23   \includegraphics[width=1.0\linewidth]{timeline.png}
24   \caption{Timeline editing session}
25   \label{fig:timeline}
26 \end{figure}
27
28 The active region \index{active region} is the range of time which is affected by editing
29 commands on the timeline.  The active region is determined first by
30 the presence of in/out points \index{in/out point} on the timeline.
31 %
32 If those do not exist the highlighted region \index{highlighted region} is used. To reiterate,
33 \emph{highlighting} is done in \emph{cut and paste mode} by moving
34 the insertion point with the mouse in the timeline to where you want
35 to start. Then hold down the LMB\@, drag the mouse to where you want
36 the end point to be and release the LMB\@. In \emph{drag and drop
37   mode}, the method to create a highlighted selection is to hold
38 down the Ctrl key and double click with the LMB with the mouse over
39 that column.
40
41 If no highlighted region exists, the insertion point \index{insertion point} is used as the
42 start of the active region.  Some commands treat all the space to
43 the right of the insertion point as active while others treat the
44 active length as 0 (zero) if no end point for the active region is
45 defined.
46
47 Most importantly, editing decisions never affect source material
48 meaning that it is non-destructive editing.  So not only does your
49 original media stay completely untouched, it is much faster than if
50 you had to copy all the media affected by an edit.  Editing only
51 affects pointers to source material, so if you want to have a new
52 modified media file at the end of your editing session which
53 represents the editing decisions, you need to render it.  Saving and
54 loading your edit decisions is explained in the Load, Save and the
55 EDL \index{EDL} section and rendering is explained in the section on Rendering.
56
57 In the following editing sections, references to common operations
58 are scattered within any of the modes where they seem pertinent.
59 However, many of the editing operations work in different modes.
60
61
62 \section{The Patchbay}%
63 \label{sec:patchbay}
64 \index{patchbay}
65
66 On the left of the timeline is a region known as the patchbay.  The
67 patchbay enables features specific to each track as described next.
68
69
70 \begin{description}
71 \item[Textbox] for naming the track.  The default names will usually
72   be Video \#, Audio \#, or Mixer \# if using the multi-camera/mixer
73   operations.  A \# will be designated for subsequent tracks as in 1,
74   2, 3 and so on.
75 \item[Expander] which is a down arrow on the right side, is for
76   viewing more options on the patchbay and for viewing the effects
77   represented on the track.  You can just click on the expander to
78   expand or collapse the patchbay and the track.  If it is pointing
79   sideways, the track is collapsed.  If it is pointing down, the track
80   is expanded.  Existing effects appear below the media for the track.
81 \end{description}
82
83 Below the textbox name are several toggles referred to as
84 \textit{attributes} for different features (currently there are 7 as
85 shown in figure~\ref{fig:patchbay01}).  If the toggle button is
86 shadowed by a color, the feature is enabled. If the toggle is the
87 background color of most of the window, it is disabled. Click on the
88 toggle to enable/disable the feature.
89
90 \begin{wrapfigure}[13]{O}{0.3\linewidth}
91   %\vspace{-2ex}
92   \centering
93   \includegraphics[width=0.79\linewidth]{patchbay01.png}
94   \caption{Patchbay}
95   \label{fig:patchbay01}
96 \end{wrapfigure}
97
98 Several mouse operations speed up the configuration of several
99 tracks at a time. Click on an attribute and drag the cursor across
100 adjacent tracks to copy the same attribute to those tracks.  Hold
101 down Shift while clicking a track's attribute to enable the
102 attribute in the current track and toggle the attribute in all the
103 other tracks. Or you can:
104
105 \begin{enumerate}
106 \item hold down Shift while clicking an attribute,
107 \item click until all the tracks except the selected one are
108   disabled,
109 \item then drag the cursor over the adjacent track to enable the
110   attribute in the adjacent track.
111 \end{enumerate}
112
113 The 7 \textit{attributes} are described here next followed by the other available feature icons and their description.
114
115 \begin{description}
116 \item[Play Track] \index{play track} determines whether the track is rendered or
117   not. If it is off, the track is not rendered.  For example if you
118   turn it off in all the video tracks, the rendered media file will
119   have only audio tracks.  If the track is chained to any other tracks
120   by a shared track effect, the other tracks perform all the effects
121   in this shared track, regardless of play status of the shared track
122   that in this particular case affects the media output but not fade
123   and effects.
124 \item[Arm Track] \index{arm track} determines whether the track is armed or not.
125   Only the armed tracks are affected by editing operations. Make sure
126   you have enough armed destination tracks when you paste or splice
127   material or some tracks in the material will get left out.  In
128   addition to restricting editing operations, the armed tracks in
129   combination with the active region determine where material is
130   inserted when loading files.  If the files are loaded with one of
131   the insertion strategies which do not delete the existing project,
132   the armed tracks will be used as destination tracks.  Note that disarming
133   a track does not prevent you from dragging or attaching an Effect/Plugin
134   onto a disarmed track - this is not considered an edit in this case.
135 \end{description}
136
137 \begin{description}
138 \item[Draw Media] determines if picons \index{picons} or waveforms \index{waveform} are drawn on
139   the asset in the track.  You may want to disable this if you know
140   that the media/format takes a long time to draw on the timeline.  By
141   default it is set to on in order to see picons on the timeline.
142 \item[Don’t send to output] \index{mute} -- more commonly called
143   \textit{mute} -- causes the output to be thrown away once the track is
144   completely rendered. This happens whether or not \textit{Play track}
145   is on.  For example if you mute all the video tracks, the rendered
146   media file will have a blank video track.  Mute track is represented
147   on the timeline with a line that has the default color of a
148   pinkish-orange.  Use the pulldown \texttt{View $\rightarrow$ Mute} to
149   have the line displayed.  It is a keyframable attribute, but Mute
150   track keyframing is a toggle and it has only the two values of on or
151   off. If a track is part of a shared track effect, the output of the
152   track with the shared track effect is overlaid on the final output
153   even though it is routed back to another track (the shared track).
154   Mute track is used to keep the track with the shared track effect
155   from overlapping the output of the source track (the shared track)
156   where the shared track effect is not present.
157 \item[Gang Fader] \index{gang fader} cause the fader to track the movement of
158   whatever other fader you are adjusting by dragging either the fader
159   or the curve on the track.  It doesn't affect the editing made with
160   menu controls.  A fader is only ganged if the arm track is also on.
161   This is often used to adjust audio levels on all the tracks
162   simultaneously.  Gang also causes Nudge parameters to synchronize
163   across all the ganged tracks.
164 \item[Master Track] Mark a track as \textit{master} serves when using \textit{Gang Channels} or \textit{Gang Media} mode. See \nameref{sub:displaying_tracks_ganged}
165 \item[Track Data Height] \index{track!height} this up/down toggle symbol to the immediate right
166 of the 5 attributes, is used to individually resize each track.  This makes
167 it very easy to temporarily expand or contract the size of that track either
168 by clickin with the left mouse button or using the middle wheel up/down.
169 \item[Fader slider] \index{fader slider} fade values are represented on the timeline
170   with a pink (default color) curve that is keyframable.  All tracks have a fader, but
171   the units of each fader depend on whether it is audio or video.
172   Audio fade values are in dB. They represent relative levels, where 0
173   is the unaltered original sound level, -40 is silence, -80 the
174   minimum value set by default.  You can move fader and keyframes down
175   to -80 but the parameter's curve won't go below -40.  For your
176   convenience you can set a different fade range with the curve zoom.
177   Audio fader’s main purpose is to \textit{fade out} sound or to lower
178   the sound level smoothly to silence, or \textit{fade in} to make
179   sounds appear gradually instead of suddenly.  Video fade values are
180   the percentage of opacity of the image in normal overlay mode, the
181   percentage of the layer that is mixed into the render pipeline in
182   the other overlay modes.  Click and drag the fader to fade the track
183   in and out.  If it is ganged to other tracks of the same media type,
184   with the arm option enabled, the other faders should follow.  Hold
185   down the Shift key and drag a fader to center it on the original
186   source value (0 for audio, 100 for video).
187 \item[Mixer] \index{mixers!toggle} in the expanded patchbay for that track designates
188   the multi-camera mixer mode.
189 \item[Overlay mode] \index{overlay pulldown} in the expanded patchbay is used for
190   porter-duff operations and is full explained in
191   \nameref{cha:overlays} chapter.
192 \item[Nudge] \index{nudge} is in the expanded patchbay.  The nudge value is
193   the amount the track is shifted left or right during playback. The
194   track is not displayed shifted on the timeline, but it is shifted
195   when it is played back. This is useful for synchronizing audio with
196   video, creating fake stereo, or compensating for an effect which
197   shifts time, all without altering any edits
198   (figure~\ref{fig:overlay}).
199
200   \begin{figure}[htpb] \centering
201     \includegraphics[width=0.65\linewidth]{overlay.png}
202     \caption{Video Overlay, audio Pan and Nudge.}
203     \label{fig:overlay}
204   \end{figure}
205
206   Enter the amount of time to shift to instantly shift the
207   track. Negative numbers make the track play later. Positive numbers
208   make the track play sooner. The nudge units are either seconds or
209   the native units for the track (frames or samples). Select the units
210   by right clicking on the nudge textbox and using the context
211   sensitive menu. Nudge settings are ganged with the Gang faders
212   toggle and the Arm track toggle. Use the mouse wheel over the nudge
213   textbox to increment and decrement the value.
214 \item[Pan] \index{panning box} is available in the expanded patchbay for audio
215   tracks via a panning box. Position the pointer in the panning box
216   and click/drag to reposition the audio output among the speaker
217   arrangement. The loudness of each speaker is printed on the relative
218   icon during the dragging operation. The panning box uses a special
219   algorithm to try to allow audio to be focused through one speaker or
220   branched between the nearest speakers when more than 2 speakers are
221   used.
222 \end{description}
223
224 Press the Tab key while the cursor is anywhere over a track to
225 toggle the track arming status. Press Shift-Tab while the cursor is
226 over a track to toggle the arming status of every other track.
227
228 \paragraph{Automatic audio mappings} \index{audio!map} Several convenience functions
229 are provided for automatically setting the panning to several common
230 standards. They are listed in the Audio menu. These functions only
231 affect armed audio tracks. They are:
232
233 \begin{description}
234 \item[Audio~$\rightarrow$~Map 1:1] \index{audio!map 1:1} This maps every track to
235   its own channel and wraps around when all the channels are
236   allocated. It is most useful for making 2 tracks with 2 channels map
237   to stereo and for making 6 tracks with 6 channels map to a 6 channel
238   sound card.
239 \item[Audio~$\rightarrow$~Map 5.1:2] \index{audio!map 5.1:2} This maps 6 tracks to 2
240   channels. The project should have 2 channels when using this
241   function. Go to \texttt{Settings $\rightarrow$ Format} to set the
242   output channels to 2. This is most useful for down-mixing 5.1 audio
243   to stereo (for more information refer to Configuration, Settings and
244   Preferences section~\ref{sub:audio_out_section}).
245 \end{description}
246
247 \paragraph{Standard audio mappings} Although \CGG{} lets you map any
248 audio track to any speaker, there are standard mappings you should
249 use to ensure the media can be played back elsewhere. Also, most
250 audio encoders require the audio tracks to be mapped to standard
251 speaker numbers or they will not work.
252
253 In the channel position widget, the channels are numbered to
254 correspond to the output tracks they are rendered to. For stereo,
255 the source of channel 1 needs to be the left track and the source of
256 channel 2 needs to be the right track.  For 5.1 surround sound, the
257 sources of the 6 channels need to be in the order of center, front
258 left, front right, back left, back right, low frequency effects. If
259 the right tracks are not mapped to the right speakers, most audio
260 encoders will not encode the right information if they encode
261 anything at all. The low frequency effects track specifically can
262 not store high frequencies in most cases.
263
264
265 \section{Manipulating Tracks}%
266 \label{sec:manipulating_tracks}
267 \index{track!pulldown}
268
269 Tracks in \CGG{} either contain audio or video.  There is no special
270 designation for tracks other than the type of media they contain.
271 When you create a new project, it contains three default tracks: one
272 video track and two audio tracks.  You can still add and delete
273 tracks from the menus.  The Tracks menu contains a number of options
274 for dealing with multiple tracks simultaneously.  Each track itself
275 has a popup menu which affects one track.
276
277 Operations in the \textbf{Tracks pulldown} affect only tracks which
278 are armed.
279
280 \begin{description}
281 \item[Move tracks up | Move tracks down] shift all the armed
282   tracks up or down the stack.
283 \item[Roll tracks up | Roll tracks down] wheel motion of the tracks up or down.
284 \item[Delete tracks] deletes the armed tracks.
285 \item[Delete first track] deletes the first track, whether it is armed or not.
286 \item[Delete last track] deletes the last track, whether it is
287   armed or not.
288 \item[Concatenate tracks] operation copies all the assets of
289   every disarmed but playable track and concatenates it by pasting
290   those assets at the end of the first set of armed tracks. They are
291   pasted one after the other, keeping the same order they have on the
292   stack. If there are two armed tracks followed by two disarmed
293   tracks, the concatenate operation copies the assets of the two
294   disarmed tracks and pastes them after the assets of the two armed
295   tracks. If there are three disarmed tracks instead, the assets of
296   two tracks are pasted after the assets of the armed tracks and the
297   assets of the third track are pasted at the end of the first armed
298   track. The destination track wraps around until all the disarmed
299   tracks are concatenated. Disarmed tracks that are not playable are
300   not concatenated.
301 \item[Align timecodes] see \nameref{sub:align_timecodes}
302 \item[Append to project] allows for creating new tracks after
303   any existing tracks.
304 \item[Add subttl] will add a track for subtitles at the top of
305   the other tracks.
306 \end{description}
307
308 The \textbf{Audio} \index{audio!pulldowns} and \textbf{Video pulldowns} \index{video!pulldown} each contain an
309 option to add a track of their specific type. In the case of audio,
310 the new track is put on the bottom of the timeline and the output
311 channel of the audio track is incremented by one. In the case of
312 video, the new track is put on the top of the timeline. This way,
313 video has a natural compositing order. New video tracks are overlaid
314 on top of old tracks.
315
316 \subsection{Displaying tracks: Ganged mode}%
317 \label{sub:displaying_tracks_ganged}
318 \index{track!ganged mode}
319
320 Often users working on media where Audio is the main focus, want all of a media's audio channels, whether stereo or 5:1 channels, to be treated as a single unit. They are more familiar with working with a DAW (Digital Audio Workstation software) and find that it takes extra work and a lot more care to have to individually manage audio tracks rather than have them automatically edited as a ganged group.
321
322 To get this capability, there is a \textit{Gang Tracks} \index{gang tracks toggle} toggle button on the main timeline controls to switch between 3 modes of working with multiple channels so that the tracks are automatically edited as a single unit. Operations affected include edits such as cuts, moving sections, and adding plugins. In addition to letting you work on the tracks of a group as one, you also get a saving of space on the timeline that makes it easier to view and edit the tracks. Group masters are marked by the \textit{Master Track} \index{master track} toggle in the patchbays \index{patchbay}. A track gang group begins on a master track, and extends to, but not including, the next master track. The 3 \textit{Gang Tracks} modes are:
323
324 \begin{enumerate}
325         \item \textbf{Gang None:} this is the default mode and is the traditional way Cinelerra operates. If you never toggle the "Gang Tracks" button, everything operates normally as it always has. In this mode, the button icon looks like 3 tracks with $\dots$ on the end and all tracks are visible on the timeline. See figure~\ref{fig:gang-track-01}
326
327 \begin{figure}[htpb]
328         \centering
329         \includegraphics[width=0.99\linewidth]{gang-track-01.png}
330         \caption{Gang None: only the video track is master. We see all tracks both master and non-master (default)}
331         \label{fig:gang-track-01}
332 \end{figure}
333         \item \textbf{Gang Channels:} in this mode, all \textit{Master Tracks} are shown. The exception is when there is no Master video, no Master audio or no Master subtitle track, in which case for each the first track of video, audio, and subtitle will be shown. For users who routinely switch the track order frequently, the patchbay has the \textit{Master Track} icon to set your own preference. Stereo tracks, or 5:1 channels/any number of audio tracks, are drawn as 1 audio track for the purpose of making changes on that single track which are propagated to all of its other channel tracks automatically. This is the DAW-like mode. The \textit{Gang Tracks} button icon looks like 2 tracks and only the first video and first audio tracks will be shown. See figure~\ref{fig:gang-track-02}
334
335 \begin{figure}[htpb]
336         \centering
337         \includegraphics[width=0.99\linewidth]{gang-track-02.png}
338         \caption{Gang Channels: only the video track is master. Let's see the master tracks and the first of the non master tracks}
339         \label{fig:gang-track-02}
340 \end{figure}
341
342         \item \textbf{Gang Media:} this mode only shows the \textit{Master Tracks} of the media but changes are propagated to the appropriate other related tracks (even if they are not visible). The \textit{Gang Tracks} button icon looks like a single track. See figure~\ref{fig:gang-track-03}
343 \end{enumerate}
344
345 \begin{figure}[htpb]
346         \centering
347         \includegraphics[width=0.99\linewidth]{gang-track-03.png}
348         \caption{Gang Media: only the video track is master. We only see the master tracks}
349         \label{fig:gang-track-03}
350 \end{figure}
351
352 The current \textit{Gang Tracks} mode is saved across sessions and will be saved in your project. Although most likely users will work in the \textit{Gang None} mode, users more familiar with DAW software will tend to use the \textit{Gang Channel}s mode.
353
354 More details are described next about master tracks. Each patchbay has a \textit{Master Track} button on the right of the patchbay. These mark which tracks of the media are master tracks. The span of tracks between the gang group masters are the gang track group. The master track toggles can be disabled/enabled as the user wishes to create the desired track groups. Normal file loads will mark the first stream of each file loaded as a master, if the media is loaded with insertion strategy of\textit{ Replace current project}, \textit{Replace current project and concatenate tracks} or \textit{Append in new tracks}. Frequently, editing is done on video, audio, or audio/video groups to maintain timeline synchronization. By grouping related tracks, this procedure is much more automatic.
355
356 Previously existing projects created before the addition of ganged tracks, will have ALL tracks marked as master tracks and changing the \textit{Gang Tracks} button mode will have no effect. The user will have to properly designate which track is the master track and disabling the others in order to make use of the toggle modes.
357
358 There are no restrictions on how you use this feature and there may be variations for users not concerned about DAW-like workings that are very useful. Several methodologies are possible, but you have to know what you are doing.
359
360 NOTES:
361 \begin{itemize}
362         \item When in \textit{Gang Channels} or \textit{Gang Media} mode, if the first audio track is not disarmed, but         any of its connected channel tracks are, the disarm of those channels are ignored and all channels are treated as being armed. This is to be consistent with the purpose of using this mode; the purpose being that any edits to the first master track are automatically propagated to all other channels. \textit{Warning}: this behavior is contrary to the default of \CGG{} whereby an unarmed track never undergoes any alteration. This exception was made to mimic the behavior of DAWs, where the various channels of an audio track are combined into a single "line", and it makes no sense to talk about armed or unarmed channels.
363         \item It may be better when using the \textit{Gang Channels} or \textit{Gang Media} mode to make any changes
364         to the first audio channel to be automatically duplicated before reverting to the \textit{Gang None} mode to make other changes. Once you start changing individual channels (that is, audio tracks) so that they are no longer coordinated in their edits/plugins, it may be more difficult to switch back to \textit{Gang Channels} mode and get the desired results since the channels may no longer be lined up.
365         \item Gang modes should not be used with Multi-camera/Mixers because they have very specific operational capabilities which are not compatible with the way that Ganging works.
366         \item Gang flags in the patchbay specifically when in \textit{Gang Channels} or \textit{Gang Media} modes will operate as set in the Master Track. For example, if when in \textit{Gang Channels} mode, you turn off “Play track” on the visible audio track, none of the associated channels (i.e. the other stereo or other 5 channels) will play. And if in \textit{Gang Media} mode, if you turn on “Play track” for the Master Track, all associated video and audio tracks will play unless you turned off “Play track” for some of the associated audio/video slave tracks which will not play. 
367         \item When adding a Plugin/Effect in \textit{Gang Channels} or \textit{Gang Media} mode to the track, highlighted selected region, or In/Out pointers area via dragging the plugin from the Resources Window the plugin will be added on the master and all slave tracks.  If using the Audio or Video pulldown, \textit{Attach Effect} option and you want to propagate the effect to all slave tracks, make sure that the checkbox for "Attach single standalone and share others" in the Dialog window is checked.  However, currently when using the right mouse button (RMB) on the master track to \textit{Attach effect}, the effect will only be inserted on that track.
368 \end{itemize}
369
370 \section{Two Screen Editing}%
371 \label{sec:two_screen_editing}
372 \index{two-screen}
373
374 This is a fast way to construct a program out of movie files (in
375 other programs is called \textit{three points editing}). The idea
376 consists of viewing a movie file in one window and viewing the
377 program in another window. Subsections of the movie file are defined
378 in the viewer window and transferred to the end of the program in
379 the program window.  Two screen editing can be done simply by using
380 keyboard shortcuts.  To get familiar with which keys to use, move
381 the mouse pointer over the transport panel and a tooltip appears,
382 showing what key is bound to that button.
383
384 To begin a two screen editing session, load your media resources by
385 using the main menu \textbf{File pulldown} and choose \textit{Load
386   files}  \index{load media files}; make sure the insertion mode is set to \textit{Create new
387   resources only}.  This insertion strategy \index{insertion strategy} is to ensure that the
388 timeline stays unchanged while new resources are brought in. Go to
389 the Resources window \index{resources window} and select the Media folder. The newly loaded
390 resources will appear. Double click on a resource or drag it from
391 the media side of the window over to the Viewer window \index{viewer!window}.
392
393 Check to make sure there are enough armed tracks on the timeline to
394 put the subsections of source material that you want.  Usually this
395 would be one video track and two audio tracks, but if there are not
396 enough, just create new tracks or arm more tracks.
397
398 Now to start your 2 screen editing, in the viewer window, define a
399 clip from the media file:
400
401 \begin{enumerate}
402 \item Set the starting point with the In pointer button.  You
403   will see a left hand bracket on the timebar.
404 \item Move your cursor to the ending point of the clip you want
405   to use.
406 \item Set the ending point with the Out pointer right hand
407   bracket.
408 \item You will see a colored bar inside the brackets for easier
409   viewing.
410 \item Drag the In/Out point \index{in/out point} with the mouse to conveniently
411   change their position.
412 \end{enumerate}
413
414 These In/Out points define a clip \index{clip}.  You can now use this in a couple
415 of different ways.
416
417 \paragraph{Splice} \index{splice} The splice icon, or shortcut letter “\texttt{v}”,
418 inserts the selected area in the timeline after the insertion point.
419 After the splice has taken effect, the insertion point moves to the
420 end of the edit ready to be used as the next splice location. This
421 way you can continuously build up the program by splicing.  If an In
422 point or an Out point exists on the timeline the clip is inserted
423 after the In point or after the Out point. If both In and Out points
424 are set on the timeline, the clip is inserted after the In point. If
425 there are edits after your chosen splice location on the timeline,
426 they will be moved to the right.
427
428 \paragraph{Overwrite} \index{overwrite} The overwrite icon, or shortcut letter
429 “\texttt{b}”, overwrites the region of the timeline after the
430 insertion point with the clip. If an In point or an Out point exists
431 on the timeline the clip is overwritten after the In point or after
432 the Out point. If both In and Out points are set on the timeline,
433 the clip is inserted after the In point. If a region is highlighted
434 or both In and Out points exist they limit the region of the
435 overwriting and the clip may therefore be shortened. Here is a
436 detailed explanation to take advantage of this method.
437
438 To overwrite exactly on a precise region of the timeline:
439
440 \begin{enumerate} [noitemsep]
441 \item Arm only tracks to change.
442 \item Define the destination region on the timeline with [ and
443   ], the In and Out points.
444 \item You can achieve maximum precision by setting the active
445   region in the zoom panel.
446 \item Define the clip you want to use in the viewer with [ and
447   ], the In and Out points.
448 \item Overwrite from Viewer to the timeline.
449 \end{enumerate}
450
451 If the destination region is shorter than the clip defined in the
452 viewer, the portion of the clip longer than the destination region
453 won't be inserted and on the timeline the following edits won't
454 move.  If the destination region is longer than the clip defined in
455 the viewer, the destination region will shrink and on the timeline
456 the following edits will move to the left.
457
458 \paragraph{Clip} The clip icon, or shortcut letter “\texttt{i}”,
459 generates a new clip for the resource window containing the affected
460 region but does not change the timeline.  Every clip has an
461 optional/default title and description.
462
463 \paragraph{Copy} The copy icon, or shortcut letter “\texttt{c}”,
464 copies the selection into the copy buffer.
465
466 \subsection{Use Case – Working with Sequences}
467 \label{sub:use_case_working_sequences}
468 \index{sequences}
469
470 \textit{From the Viewer to the Timeline \index{timeline} with the sequences imported
471   in a Master Project.}
472
473 A convenient methodology for working on a Master project along with
474 1 or more previously saved Sub projects or \textit{sequences} use
475 case is described here.  A sequence is an edited assembly of audio
476 and video clips generally consisting of a series of videos that
477 relate to the same activity. This use case explains how to work this
478 way and some things you need to be aware of.
479
480 \begin{enumerate}
481 \item First load your Master project, which you worked on and
482   saved earlier as an \texttt{.xml} file, using an Insertion strategy
483   of \textit{Replace current project}.  Generally this Master project
484   consists of media with any of the attributes of clips, autos,
485   possibly keyframes, and effects.  You will see your project on the
486   main timeline and the Media files that are part of this Master
487   project will be displayed in the Resources window in the Media
488   folder.
489 \item Previously you may have also saved a Sub project, which
490   will now be referred to as a Sequence, as an \texttt{.xml} file that
491   may contain any of the same such things: media, clips, autos,
492   keyframes, effects.  Second you will want to load the Sequence using
493   an Insertion strategy of \textit{Create new resources only}.  When
494   you do the load, this Sequence will show as a file in the Resources
495   window in the Clips folder.  The actual media will show in the Media
496   folder.
497 \item Now Drag and Drop the Sub project from the Clips folder to
498   the Viewer.
499 \item Set In and Out Pointers in the Viewer to the region of
500   interest in the Sub project and in the Timeline of the Main window
501   of your Master project, move the cursor position to where you would
502   like to insert this In/Out section.
503 \item Click on the \textit{Splice (v)} button in the Viewer to
504   insert this section into the Master project timeline.  All of the
505   attributes of the selected Sub project section will now be inserted
506   in the main timeline to include the autos, keyframes, effects, and
507   labels.
508 \item Alternatively, if you click on the \textit{Overwrite (b)}
509   button in the Viewer, you can see the Sub project In/Out section in
510   the timeline, but without its autos, effects, keyframes, etc.  If in
511   the timeline there were some autos, effects, and keyframes in that
512   Master project, they will be in effect for the new section.
513 \end{enumerate}
514
515 You can see the advantages of using Splice versus Overwrite to
516 either insert (splice) with all of the attributes of a specific
517 section of your Sequence or to overwrite without the attributes to
518 allow for the smooth operation on the timeline by retaining the
519 timeline’s attributes at that point.
520
521 NOTE: for correct operation of this use case, you should have the
522 same (or more) number of tracks in the Master project as you do in
523 the Sequence.  To avoid having to know how many tracks you need, you
524 can use the Nest feature as described in the Nesting section
525 (\ref{sec:nesting_clips_and_assets}).
526
527
528 \section{Cut and Paste Editing}%
529 \label{sec:cut_paste_editing}
530 \index{cut and paste}
531
532 This is the more traditional method of editing in \CGG{} and
533 therefore is the default.  To enable the cut and paste editing mode
534 on the timeline, select the I-beam \index{i-beam} toggle on the control bar at the
535 top of the main program window. You can copy edits in the same
536 track, copy from different tracks in the same instance, start a
537 second instance of \CGG{} and copy from one instance to the other or
538 load a media file into the Viewer and copy from there.
539
540 To start editing, load some files onto the timeline.  Select a
541 region of the timeline by click dragging on it and select the cut
542 button to cut it. Move the insertion point to another point in the
543 timeline and select the paste button.  Assuming no In/Out points are
544 defined on the timeline this performs a cut and paste operation.
545
546 Most editing operations are listed in the \textit{Edit} pulldown \index{edit!pulldown}. Some of
547 them have a button on the program control toolbar as well as a
548 keyboard shortcut.  The keyboard shortcut is in parenthesis here.
549
550 \begin{description}
551 \item [Split | Cut] (x) Delete the selected area and put it in
552   the cut buffer for future pasting.
553 \item[Copy] (c) Copy the selected area and put it in the cut
554   buffer for future pasting.
555 \item[Paste] (v) Paste the material that is in the cut buffer.
556 \item[Clear] (Del) Clear the selected area. If the insertion
557   point is over an edit boundary and the edits on each side of the
558   edit boundary are the same resource, the edits are combined into one
559   edit comprised by the resource. The start of this one edit is the
560   start of the first edit and the end of this one edit is the end of
561   the second edit. This either results in the edit expanding or
562   shrinking.
563 \item[Paste silence] (Shift+Space) Paste blank audio/video for
564   the length of the selected area. Following edits will be pushed to
565   the right.
566 \item[Mute Region] (m) Overwrite blank audio/video on the
567   selected area. Following edits don't move.
568 \item[Trim Selection] Delete everything but the selected region.
569 \item[Select All] (a) Select the whole timeline.
570 \end{description}
571
572 In Cut and Paste editing mode you can \textit{edit labels} \index{label} as
573 well. By enabling Edit labels in the \textbf{Settings pulldown}, or
574 by disabling the Lock labels from moving button on the Program
575 Control Tool Bar, labels will be cut, copied or pasted along with
576 the selected regions of the armed tracks.
577
578 Using labels and In/Out points are useful in editing audio.  You can
579 set In/Out points for the source region of the source waveform and
580 set labels for the destination region of the destination
581 waveform. Perform a cut, clear the In/Out points, select the region
582 between the labels, and perform a paste.
583
584 \paragraph{In / Out Points} \index{in/out point} The In and Out bracket placement is
585 explained here to illustrate their usage.  Because of the shape of
586 the markers [ and ] you may assume that they are inclusive -- that
587 everything placed in between would be included in the clip \index{clip}, such as
588 in the case of being transferred to the timeline from the Viewer.
589 In reality, one of the two markers will not include the frame that
590 was visible at the time the marker was affixed. Depending on whether
591 the \textit{Always show next frame} option is used or not, it is the
592 In or Out marker that will not be inclusive.
593
594 To obtain a clip on the timeline exactly as you saw in the Viewer,
595 you must necessarily move the In mark back from the beginning before
596 the first desired frame or move the Out mark forward after the last
597 desired frame, depending on the \textit{Always show next frame}
598 setting.
599
600 Some of the confusion can be attributed to the fact that the Viewer
601 shows frames, while the markers determine spaces, i.e.\ times, that
602 are not visible between frames. You have to think of each frame as
603 being delimited by two spaces -- one preceding and one following.
604 The In mark is always placed before the displayed frame and the Out
605 mark is always placed after the displayed frame, while taking into
606 account in its calculations whether the \textit{Always show next
607   frame }option is used or not. If you just remember that the
608 reference of the markers is in the middle of the icon, you will
609 avoid confusion.
610
611 \paragraph{Overwrite} \index{overwrite} To perform overwriting within the timeline
612 paste on a selected region (highlighted or between In/Out
613 points). The selected region will be overwritten. If the clip pasted
614 from the clipboard is shorter than the selected region, the selected
615 region will be shrunk. Following edits will move. If the clip pasted
616 from the clipboard is longer than the selected region, the selected
617 region will be overwritten with the first part of the clip and the
618 remaining part of the clip will be written after the
619 overwriting. Following edits will move.
620
621 \paragraph{Tracks $\rightarrow$ Concatenate tracks} This operation
622 copies all the assets of every disarmed but playable track and
623 concatenates it by pasting those assets at the end of the first set
624 of armed tracks. They are pasted one after the other, keeping the
625 same order they have on the stack.
626
627 \paragraph{Split -- blade cut and hard edges:} \index{split} You can cut the
628 tracks into 2 pieces on the timeline by putting the hairline cursor
629 on the place you want to do a cut and then using the character “x”
630 or the scissors tool (figure~\ref{fig:cut}).
631
632 \begin{wrapfigure}[16]{O}{0.3\linewidth}
633   \vspace{-2ex}
634   \centering
635   \includegraphics[width=0.9\linewidth]{cut.png}
636   \caption{Blade cut}
637   \label{fig:cut}
638 \end{wrapfigure}
639
640 A \textit{cut} uses a non-empty selection region, where the
641 \textit{blade cut} or \textit{split} has no duration in the
642 selection, just a hairline.  As usual the use of cut when a
643 selection is set, deletes/cuts the highlighted area.  In the case
644 where an In point or an Out point exists on the timeline, the clip
645 is split at the location of the In/Out point since it has priority
646 over the cursor location.  A blade cut simply splits the edit into
647 two edits.  In order to have the video and audio aligned, it works
648 best to have \texttt{Settings $\rightarrow$ Align cursor on
649   frames} \index{align cursor on frames}.  When a blade cut occurs, the edges are created as
650 \textit{hard edges}. \index{hard edge} These are edges that cannot be deleted by
651 track optimizations \index{timeline!optimization}.
652 %
653 \CGG{} has built-in optimization on the timeline.  So that whenever
654 two parts on the timeline are sequential frames, it automatically
655 optimizes by making them into 1 item.  So if you are cutting,
656 dragging, editing, or whatever and somehow frame \# 40 ends up
657 right next to frame \# 41, it optimizes them together.  This
658 optimization affects many areas throughout the program code.  When
659 you do a blade cut/split, all armed tracks will be included in the
660 cut and green-colored triangles will show on the bottom of the
661 track on both the left and the right side of the cut.  This is a
662 \textit{hard edge} marker toggle, as opposed to the soft edge
663 designation for an ordinary edit.  The \textit{hard edge} marker
664 can be toggled off/on if so desired.  In order to not interfere
665 with the usual drag handles, only a few pixels are used for the
666 toggle so you have to be sure you have the cursor right over the
667 hard edge triangle -- when in position, it will be obvious because
668 you can see an arrow pointing to the corner.  Use Shift-left mouse
669 button 1 to toggle off/on the hard edge marker on all tracks
670 simultaneously.
671
672
673 \section{Drag and Drop Editing}%
674 \label{sec:drag_drop_editing}
675 \index{drag and drop}
676
677 To enable the drag and drop editing mode on the timeline, select the
678 arrow toggle \index{arrow} on the control bar at the top of the main program
679 window.  Drag and drop editing is a quick and simple way of working
680 in \CGG{}, using mostly only the mouse. The basic idea is to create
681 a bunch of clips \index{clip}, then drag them in order into the timeline, thus
682 building prototype media that you can watch in the compositor. If
683 after watching it, you wish to re-arrange your clips, set effects,
684 add transitions or insert/delete material, just drag and drop them
685 on the timeline.
686
687 To simply get started, perform the following operations which are
688 useful for working in a drag and drop editing session.  First load
689 your media by using the main menu \textit{File} pulldown \index{file pulldown} and choose
690 \textit{Load files} \index{load media files}; make sure the insertion mode is set to
691 \textit{Create new resources only} \index{insertion strategy}.  This loads the files into the
692 Resources window \index{resources window}.
693
694 \begin{enumerate}
695 \item Create some video and audio tracks on the timeline using
696   the \textit{Video} \index{video!pulldown} and \textit{Audio} \index{audio!pulldown} pulldowns.
697 \item Open the Media folder in the Resources window.  Make sure
698   the necessary tracks are armed and drag a media file from the
699   Resources window to the timeline \index{timeline}. If the media has video, drag it
700   onto a video track or if just audio, drag it onto an audio
701   track. For a still image, drag it onto a video track.
702 \end{enumerate}
703
704 You can also drag multiple files from the Resources window. When
705 dropped in the timeline they are concatenated. If you have
706 \textit{Display Icons} selected in the Resources window, drawing a
707 box around the files selects contiguous files. If you have
708 \textit{Display Text} selected, Ctrl-clicking on media files selects
709 additional files one at a time; Shift-clicking on media files
710 extends the number of highlighted selections.  In addition to
711 dragging media files, if you create clips and open the clip folder
712 you can drag clips onto the timeline.
713
714 \CGG{} fills out the audio and video tracks below the dragging
715 cursor with data from the file. This affects what tracks you should
716 create initially and which track to drag the media onto. To drag and
717 drop a file on the Program window, you need to create on the
718 timeline the same set of tracks as your media file.
719
720 When you drag your chosen media from the media folder to the
721 timeline, your mouse pointer will drag a thumbnail and, once over
722 the timeline, the outline of a white rectangle, as big as the edit
723 you are going to have appears.  Drag the media to the desired
724 position of an empty track of the timeline and drop it.  If there
725 are other edits on that track, when you move the white outline over
726 an edit, you will see a bow tie symbol $\bowtie$ appearing at edit
727 boundaries. If you drop the media there, the new edit will start
728 from the edit boundary indicated by the center of the bow tie
729 $\bowtie$.
730
731 Since the mouse pointer is in the middle of the white outline, when
732 this rectangle is bigger than the visible part of the timeline, it
733 is quite cumbersome to precisely insert it for long
734 media. Lengthening the duration visible in the timeline by changing
735 the sample zoom in the zoom panel will reduce the size of the white
736 rectangle, making a precise insertion possible.
737
738 When you drag and drop edits within the timeline:
739
740 \begin{itemize}
741 \item If you drop an edit when bow ties $\bowtie$ are shown,
742   that edit will be cut and pasted starting at the edit boundary
743   indicated by the center of the bow tie $\bowtie$.  Following edits
744   on the same track will move.
745 \item If you drop an edit when there are no bow ties $\bowtie$
746   shown, the original edit will be muted and pasted where you dropped
747   it. No edits will move. A silence will appear in place of the
748   original edit.
749 \item If you have more armed tracks on the timeline than in the
750   asset you are dragging, only the following edits of the tracks
751   affected by the drag and drop operation will move to the right. This
752   will cause loss of synchronization \index{sync}. To restore it, disarm the tracks
753   affected by the drag and drop operation, highlight the just dropped
754   edit and paste silence over it using the \textit{Edit} pulldown,
755   \textit{Paste Silence}.
756 \end{itemize}
757
758 Labels sometimes work differently in Drag and Drop editing mode in
759 that you can't drag and drop them. They might be locked to the
760 timebar \index{timebar}, even with the Edit labels option enabled.  Although with
761 the Edit labels option enabled, if a selected area of a resource is
762 spliced from the Viewer to the timeline in a position before labels,
763 these labels will be pushed to the right for the length of the
764 selected area.
765
766 In/Out points can be used to perform Cut and Paste operations in
767 Drag and Drop mode as well as in Cut and Paste mode.  Use the \textit{Edit}
768 pulldown to view the list and their keyboard shortcuts.
769
770
771 \subsection{Copy/Paste Behavior}%
772 \label{sub:copy_paste_behavior}
773 \index{drag and drop!MMB options}
774
775 There are many options for moving, copying, pasting, inserting, and
776 deleting selected \textit{edits}, more commonly referred to by the
777 user as \textit{clips}, when in the Drag and Drop (arrow) editing
778 mode.  This makes it easier to avoid constantly having to disarm/arm
779 tracks.  To create a selection \index{edit!selection} move the cursor over the clip and
780 just click the left mouse button; remove a selection by left mouse
781 button click again.  This will mark your selection with a colored
782 border which contains some red.  The easiest way to initially use
783 the various modes is to click on the middle mouse button when your
784 cursor is over a track and a popup displays the modes and shortcuts.
785 However, for those users who prefer the addition of the Ctrl key to
786 add multiple selections as is commonly done for listbox operations,
787 there is a preference in \texttt{Settings $\rightarrow$ Preferences
788   $\rightarrow$ Appearance} tab, called \textit{Clears before
789   toggle} \index{clears before toggle} that changes the behavior.
790
791 When an edit is marked as selected, it can be cut/copied into the
792 paste clip buffer.  The constructed clip buffer will begin with the
793 leftmost edit and end with the rightmost edit.  The edits may
794 contain media, or be silence, or skipped if they are not selected.
795 The clip tracks are copied from the first track with an active edit
796 selection to the last track with an active edit selection.  A clip
797 track can be completely empty if no selection was made on the track.
798 The word \textit{packed} means that the silent edits and empty
799 tracks are not included in the copy to the clip buffer, and all of
800 the elements are packed together, no gaps.  Packing a clip buffer
801 makes it easier to move \textit{blobs} of data around.  Once the
802 edits have moved and have a relative relationship applied, an
803 unpacked clip buffer allows the media to be copied with the relative
804 positions of the edits preserved.
805
806 The \textit{edits} popup is activated on a track and a red and
807 yellow colored reticle appears to temporarily mark the location when
808 you click on the middle mouse button.  An expanded explanation is
809 provided below.
810
811 \renewcommand{\arraystretch}{1.15}
812 \begin{center}
813   \begin{longtable}{p{0.3\textwidth-2\tabcolsep} p{0.7\textwidth-2\tabcolsep}}
814     \toprule
815     \textbf{Key} & \textbf{Operations}\\
816     \midrule
817     Drag & Hold down the Ctrl key while dragging to move a single
818            edit elsewhere.\\
819     Left mouse button & Selects and highlights the edit under the
820                         cursor with a red selection box. Left mouse
821                         button also will toggle that clip selection
822                         off if it is on.\\
823     \bottomrule
824   \end{longtable}
825 \end{center}
826
827 \begin{center}
828   \begin{longtable}{p{0.2\textwidth-2\tabcolsep}
829     p{0.2\textwidth-2\tabcolsep} p{0.6\textwidth-2\tabcolsep}
830     }
831     \toprule
832     \textbf{Popup Label} & \textbf{Key} & \textbf{Operation}\\ \midrule
833     \endhead
834     Clear Select & Ctrl-Shift-A & Deselect all selected edits --
835                                   ones that have the red lines
836                                   around them.\\
837                                   
838     Select Edits & Ctrl-Alt-' & Select all edits within a highlighted area of the timeline \\
839     
840     Deselect Edits & & Deselect all edits within a highlighted area of the timeline \\
841
842     Copy & Ctrl-c & Copy the selected edits into the copy buffer.\\
843
844     Cut & Ctrl-x & Delete the selected edits after copying them into
845                    the buffer. The edits\\
846
847     Mute & Ctrl-m & Delete the selected edits after copying them
848                     into the buffer. The space previously occupied
849                     by the edits will be replaced with silence.\\
850
851     Copy Pack & Ctrl-Shift-C & Copy the selected edits into the
852                                buffer and remove any silent
853                                sections.\\
854
855     Cut Pack & Ctrl-z & Delete the selected edits after copying them
856                         into the buffer. The edits after the
857                         election will move left to occupy the
858                         vacated space.  The edits in the copy buffer
859                         will be packed together within each track.\\
860
861     Mute Pack & Ctrl-Shift-M & Delete the selected edits after
862                                copying them into the buffer.  The
863                                deleted edits will be replaced with
864                                silence.  The edits in the copy
865                                buffer will be packed together within
866                                each track.\\
867
868     Paste  & Ctrl-v & Paste contents of the copy buffer at the
869                       insertion point marked by the red \& yellow
870                       reticle of the popup menu or the position of
871                       the hairline cursor. This is a splice
872                       operation which creates space for the edits.\\
873
874     Overwrite & Ctrl-b & Paste contents of the copy buffer at the
875                          insertion point marked by the red \& yellow
876                          reticle of the popup menu or the position
877                          of the hairline cursor. This destroys the
878                          current edits in that space.\\
879
880     Overwrite plugins & Ctrl-Shift-P & Pastes plugins that are in the Copy
881                                buffer to current location but no
882                                clip. Plugins.\\
883     \bottomrule
884   \end{longtable}
885 \end{center}
886 \renewcommand{\arraystretch}{1}
887
888 The copy/paste behavior respects the armed/disarmed tracks
889 state.  A paste of audio on a video track will fail and vice versa.
890 In addition if you attempt to paste edits consisting of more tracks
891 than what is available at that location it will not allowed.
892
893 Attaching transitions to multiple selected edits via the \textit{Video} or
894 \textit{Audio} pulldowns is also available.  The new transitions are attached
895 at the start of the edits, and will replace any existing attached
896 transitions.  As a side note, when in drag and drop mode the end
897 transition does not drag.
898
899 \subsection{Snapping while Cutting and Dragging}%
900 \label{syb:snapping_cutting_dragging}
901 \index{snap}
902
903 \paragraph{Cutting/Snapping edits} \index{edit!cut with snap} cuts from an edit handle to the
904 insert point.  There are Edit Panel buttons which normally are used
905 to move to the previous or next edit handle/label.
906
907 \begin{wrapfigure}[3]{r}{0.2\linewidth}
908         \vspace{-2ex}
909         \centering
910         \includegraphics[width=0.7\linewidth]{snap.png}
911 \end{wrapfigure}
912
913 They look like tags and the letter E on the menu bar and are
914 oriented forward/backward.  These same buttons can be used to
915 \textit{cut} from the insert pointer to the previous or next
916 edit/label when the ctrl+alt keys are both pressed when the buttons
917 are used.  They \textit{snap} off the media instead of doing the
918 standard re-positioning.  This is useful to minimize the number of
919 operations necessary to cut between edits/labels.
920
921 Instead of using the edit panel buttons, you can more easily use the
922 following keyboard shortcuts to perform the same functions:
923
924 \begin{center}
925         \begin{tabular}{lll}
926                 \toprule
927                 snap\_right\_edit & ctrl+alt+ '.' &\\
928                 snap\_left\_edit & ctrl+alt+ ',' &\\
929                 snap\_right\_label & ctrl+alt +shift '.' & shift+period is the > sign on US keyboards\\
930                 snap\_left\_label &  ctrl+alt +shift',' & shift+comma is the < sign on US keyboards\\
931                 \bottomrule
932         \end{tabular}
933 \end{center}
934
935 \paragraph{Drag Snapping} \index{edit!drag with snap} if you hold down the Ctrl + Alt keys while
936 dragging using the mouse, once the clip gets near to an edit, a
937 label, an in/out pointer or the start/end of the timeline, the
938 dragged clip will snap next to that marker.  The 2 will now be
939 exactly aligned with no gap and no overlap.  As you drag the clip
940 close to one of the markers, when they are within a short distance
941 they start to stick and stay that way until you move further away
942 from that distance.  Also, the line will turn color from green to
943 yellow while in the sticky phase.  In addition, this works for a
944 plugin while dragging so that it will be the same length as the edit.
945
946 \subsection{Copy/Paste clips/medias across Multiple Instances}%
947 \label{sub:copy_paste_multiple_instances}
948 \index{multiple instances: copy/paste}
949
950 It is easy to copy/paste clips/media within a single instance of
951 \CGG{} or across multiple instances.  The reason this works is
952 because there are hidden X cut buffers and these are used to
953 transmit EDL from 1 instance to another.
954
955 Steps to copy from a source timeline and paste to a target timeline:
956
957 \begin{enumerate}
958         \item highlight a selection on the timeline in 1 instance of \CGG{}
959         \item use the Copy icon (shortcut c) on the main menu bar to copy
960         into a buffer
961         \item move the pointer to another instance of \CGG{} and set an
962         insertion point in its timeline
963         \item use the Paste icon (shortcut v) to paste the clip to that
964         other instance selection target
965 \end{enumerate}
966
967 \subsection{Grouping edits}%
968 \label{sub:grouping_edits}
969 \index{edit!grouping}
970
971 \CGG{} recognizes as a group, the edits of different armed tracks
972 that have aligned beginnings, regardless of whether they have the
973 same source or aligned ends.  You can drag these edits around on the
974 timeline to construct your movie by rearranging scenes. If more than
975 one track is armed, \CGG{} will drag any edits which start on the
976 same positions the edit the mouse pointer is currently over. Another
977 method of Grouping of edits is performed as follows:
978
979 \begin{enumerate}
980 \item Select \index{edit!selection} each of the clips you would like to be part of a
981   group.
982 \item Use the desired Copy mode as described above to get into
983   the buffer.
984 \item Go to the Resources window Clip folder and right click on
985   an empty spot.
986 \item Choose the Paste Clip option.  Now you have a named clip
987   of the current selection.
988 \end{enumerate} A more traditional Grouping of edits which make a
989 Permanent Group works as described next.  A temporary group is just
990 a set of selected clips and works the same as a single selection.
991 \begin{enumerate}
992 \item Create a group:
993   \begin{itemize}[noitemsep]
994   \item Select multiple clips/edits with left mouse button
995     over the clip;
996   \item Hold down shift and left mouse click over any of the
997     selected clips to create a group;
998   \item A Group Id and color are assigned to this group making
999     it easy to distinguish.
1000   \end{itemize}
1001 \item Move a group:
1002   \begin{itemize}[noitemsep]
1003   \item Move your cursor over any of the clips within the
1004     group; click to select the clip group.
1005   \item Click and Hold down the left mouse button to drag.
1006   \end{itemize}
1007 \item Dissolve a permanent group:\\
1008   To ungroup select any of the group edits/clips and shift left
1009   mouse click to ungroup (same as creating).  The edits will be
1010   ungrouped, and the current selection will be replaced with the
1011   ungrouped clips.
1012 \end{enumerate}
1013
1014 The color of the created groups are not muted and are assigned by
1015 Group Id going sequentially through the number of 1 to 64.
1016 Therefore if you dissolve a group and make it again, it will have a
1017 different Group Id and a different color.
1018
1019 \subsection{Dragging Groups}%
1020 \label{sub:dragging_groups}
1021 \index{edit!dragging group}
1022
1023 Dragging while in \textit{Drop and Drag editing mode} (arrow mode)
1024 is really easy.  Just select \index{edit!selection} the clip or clips you want to drag
1025 using the left mouse button, then put your cursor over one of them
1026 and drag while holding down the left mouse button.  Keyframes,
1027 autos, labels, and plugins will also be dragged.  Dragging honors
1028 armed/disarmed tracks.  When you drag there will be some possible
1029 colors as defined; depends on how the edges of edits and groups
1030 interact:
1031
1032 \begin{itemize}
1033 \item Green color means OK to drop in that position as it will
1034   fit.
1035 \item Yellow color means you can drop here and when you do it
1036   will be exactly next to that existing edit.
1037 \item Blue color means it overlaps something and this includes
1038   overlapping itself.
1039 \item Red color means can not drop here because it will not fit
1040   in the space.
1041 \item Orange color means the track types do not match so it can
1042   not be dropped here.
1043 \end{itemize}
1044
1045 Remember: With the \texttt{Shift} key on, it will always
1046 \textit{overwrite}. Without the \texttt{Shift} key enabled, it
1047 always \textit{inserts} only.
1048
1049 The original (older) method of dragging while in Arrow \index{arrow} mode, lets
1050 you just left mouse click on a single clip or aligned clips and just
1051 drag.  This older method of dragging does not move any of its
1052 effects with it at this time.  There will only be a white outline
1053 while dragging and it will let you drop only if it fits.  You can
1054 also perform some dragging and grouping while in the \textit{Cut and
1055   Paste editing mode} (ibeam mode \index{i-beam}) by taking advantage of the Ctrl
1056 button in conjunction with the left mouse button.
1057
1058 \begin{itemize}
1059 \item Double click selects a column so you can move, for
1060   example, the audio and video together by holding down the Ctrl key
1061   and dragging.
1062 \item A single clip can be dragged without any of its aligned
1063   clips, by holding down and Ctrl key and drag.
1064 \end{itemize}
1065
1066 This last section on Dragging, outlines the difference
1067 between \textit{column selection} \index{column selection} and \textit{marking selection} \index{marking selection}.
1068 Column selection is available to make it easy to still be able to do
1069 some dragging in I-beam mode whereas Marking selection makes it easy
1070 to drag clips together that are not columnated.
1071
1072
1073 \subsection{Selection Methods}%
1074 \label{sub:selection_method}
1075 \index{edit!selection}
1076 \index{active region}
1077
1078 Concerning \textit{Selection} methods, the following information is
1079 partially pertinent to all editing, but is most important to keep in
1080 mind when using Drag and Drop Editing.
1081
1082 Originally, there was the column oriented timeline drag selection
1083 which can be seen in 1 of 3 ways:
1084
1085 \begin{enumerate}
1086 \item a highlighted vertical column
1087 \item the colored line region between the [~in and out~] marker
1088   labels
1089 \item a single flashing line
1090 \end{enumerate}
1091
1092 The selection priority works like this. When the highlighted
1093 vertical drag column is in use (1), it has the highest precedence
1094 and is used as the selection.  When the column is a single line (2),
1095 then the fall back selection is the [~in/out~] marker region, if
1096 they are set.  When they are not set, and the cursor is flashing,
1097 then the selection start=end and the selection is empty, but it does
1098 have a position on the timeline which can be used for editing.  This
1099 is input for the vertical style cut/paste drag/drop editing.
1100
1101 More recently, in addition to the column oriented timeline drag
1102 selection, there is now \textit{group} \index{edit!grouping} capabilities which have
1103 various \textit{edit} selections.  These are created in the Drag and
1104 Drop editing mode by clicking edits to toggle
1105 select/deselection.  These groups are input to a different (more
1106 modern) set of cut, paste and overwrite drag/drop editing.  You
1107 can see this set of operations when you click on an edit with the
1108 middle mouse button, and are also available using the shortcuts
1109 shown. They are more like text editor commands to include
1110 \texttt{ctrl+x=cut}, \texttt{ctrl+c=copy}, \texttt{ctrl+v=paste},
1111 and so on \dots The keyboard Delete key is not hooked to these
1112 operations, and is hooked to the original editing methods.
1113
1114 In this \textit{group} mode, if there are In/Out \index{in/out point} markers set, they
1115 enter the selection priority queue between the column selection and
1116 the cursor only. You can see the In/Out markers selected region
1117 colored line across the timebar (slightly underneath where the time,
1118 samples or frames show ) on the main timeline extending between the
1119 [ and ].  This means that when the highlighted cursor selection is
1120 empty, the In/Out selection will be used.
1121
1122 Summarizing: to select multiple edits/clips on the timeline you can simply use LMB on each edit. Or, if in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ appearence tab $\rightarrow$ Flags} we have enabled \textit{Clears before toggle}, use CTRL + LMB on each edit.
1123
1124 There is also a faster way:
1125
1126 \begin{enumerate}
1127         \item Arm the tracks you want to be used.
1128         \item Highlight the area as usually you do with \textit{I-beam} mode (or use \textit{In/Out Points}; or position \textit{Insert Point} over the stack of edits). If you miss an edit that you want included, the same method can be used to add it. It is an additive operation. And, it will include the partial edits in the selected area, thus making it easy to disinclude ones you do not want.
1129         It will include silence also but you can remove that or any other edit with CTRL + LMB.
1130         \item Press MMB on a clip inside the highlight area and the PopUp menu is shown with the \textit{Select edits} option on the top.
1131         \item Choose the \textit{Select or Deselect edits} option and the clips inside the highlight area will be selected or deselected.
1132 \end{enumerate}
1133
1134 And there is a Drag mouse way (this requires that the cursor be on the first
1135 clip and from there you start the drag):
1136 \begin{enumerate}
1137         \item To Drag Select edits, hold down Alt+Left Mouse Button (LMB) and drag over the selection area. Releasing the mouse results in selecting. 
1138         \item To Drag Deselect edits. hold down Alt+Ctrl+LMB and drag over the area to be desected.  Releasing the mouse results in deselecting.
1139 \end{enumerate}
1140
1141 If using certain operating systems (for example Ubuntu and Arch) that might field the Alt key before it gets to \CGG{}, you can use the following for both Select and Deselect instead:
1142 \begin{enumerate}
1143         \item Press and hold down Ctrl+Alt+LMB on an edit
1144         \item Drag on the edits you want to select
1145         \item Release the Ctrl key
1146         \item Release the LMB
1147         \item Release the Alt key
1148 \end{enumerate}
1149
1150 \section{Inter-View Mode -- Identifying Source Targets}%
1151 \label{sec:inter-view_identifying_source_target}
1152 \index{inter-view}
1153
1154 Inter-View mode provides a mapping of a particular media file to its
1155 timeline \index{timeline} usages. It is somewhat similar to Two Screen Editing in
1156 that you make use of the Viewer. It makes it possible to precisely
1157 trace and indicate in the media the origin of a particular segment
1158 of the timeline and visually indicate the use and distribution that
1159 the timeline makes of a particular media.  A good example usage
1160 would be in the case of a 30 minute interview where you use a few
1161 short pieces to make a shorter 10 minute section, find out that you
1162 have made the timeline 12 minutes instead and need to cut out
1163 another 2 minutes. This feature provides the following capabilities:
1164
1165 \begin{itemize}
1166 \item You can see on the timeline all of the places where a
1167   particular piece of media was used.
1168 \item You can see which parts of that particular media are
1169   already used so you do not reuse that same piece again.
1170 \end{itemize} Figure~\ref{fig:inter-view01} shows an example of the
1171 Inter-View mode mapping preview mini-window.
1172 \begin{figure}[ht]
1173   \includegraphics[width=0.8\linewidth]{inter-view01.png}
1174   \caption{Inter-View mode: white bar$\rightarrow$source; red
1175     bar$\rightarrow$timeline}
1176   \label{fig:inter-view01}
1177 \end{figure}
1178
1179 There is a second usage of Inter-View mode that can be helpful if
1180 some tracks have become misaligned, such as in the case of 2 audio
1181 channels no longer being in sync.  You can use this mode to get them
1182 back in alignment.
1183
1184 Explanation of how to use Inter-View mode will be described here
1185 next.
1186
1187 \begin{itemize}
1188 \item Do your editing as usual on the timeline until you are
1189   ready to see what is used or unused.
1190 \item Make sure you are in any of the Preview modes \index{preview mode} in the
1191   Resources window \index{resources window}; you enable the mode using the pulldown to the left
1192   of the word \textit{Search}.  The option looks like this \quad
1193   \includegraphics[height=\baselineskip]{fullplay.png}.
1194 \item Middle mouse click on a thumbnail in the Resources window and
1195   a popup occurs of that media with a white colored bar at the top
1196   and a red colored bar at the bottom with black sections.
1197 \end{itemize}
1198
1199 The red/white bars represent the presence and the black sections
1200 represent the absence of where that media is used on the timeline.
1201 To get to a bigger representation, use the “\texttt{f}” key for a
1202 full screen.  Now you can operate the following buttons to display
1203 what you need to see and to move around.  It is important to note
1204 that \textit{locked tracks} will not be represented.  This makes it
1205 easy to ignore the audio track segments if you want so there is less
1206 confusion in the display.
1207
1208 \begin{itemize}
1209 \item Clicking on the top white or black spaces in the top time
1210   bar loads the Viewer with the source media, and sets the In/Out [
1211   and ] pointers to be the selection of that edit.
1212 \item Click on a location in the bottom red or black bar, and
1213   the main cursor and composer will re-position to the corresponding
1214   location on the session timeline.
1215 \item Dragging on the red/black bar will correspondingly update
1216   the position in the timeline and composer.
1217 \item Ctrl-click on the bottom bar and the timeline and composer
1218   are re-positioned to the beginning of that edit.
1219 \item Shift-click on the bottom bar and a \textit{selection} is
1220   made of that section in the timeline and the compqoser is updated
1221   with that start position.
1222 \end{itemize}
1223
1224 %\pagebreak
1225 Figure~\ref{fig:inter-view02} displays Inter-View window and its
1226 relation to the timeline, viewer, and compositor.
1227 \begin{figure}[ht]
1228   \centering
1229   \includegraphics[width=1.0\linewidth]{inter-view02.png}
1230   \caption{Inter-View mode and the timeline}
1231   \label{fig:inter-view02}
1232 \end{figure}
1233
1234 The Inter-View mode works for Media, Proxy, and User Bins.  When the
1235 preview window has only black bars on the top and bottom, it means
1236 that this particular media is not loaded in the timeline.  So when
1237 you are in Proxy, meaning that the Proxy files are loaded on the
1238 timeline, there will be only black bars for the corresponding Media
1239 file UNLESS there is an audio track associated with the video.
1240 Because audio tracks are not proxied, they will show for Media but
1241 not for Proxy.
1242
1243 \section{Edit Tools}%
1244 \label{sec:edit-tools}
1245 \index{edit tools}
1246
1247 \subsection{Edit Length}%
1248 \label{sub:edit-lenght}
1249 \index{edit!length}
1250
1251 To set the length of an edit in the timeline, select the region
1252 which contains the edit to be modified. Now select the menu bar
1253 \texttt{Edit $\rightarrow$ Edit Length}\dots menu item to activate
1254 the \textit{edit length} popup (figure~\ref{fig:lenght}).  The
1255 duration of the edit can be reset by entering the desired edit
1256 length in seconds.  Pressing OK will change all of the selected
1257 edits (in armed tracks) to the specified length.
1258
1259 \begin{figure}[htpb]
1260     \centering
1261     \includegraphics[width=0.5\linewidth]{lenght.png}
1262     \caption{Edit Length window}
1263     \label{fig:lenght}
1264 \end{figure}
1265
1266 \subsection{Align Edits}%
1267 \label{sub:align_edits}
1268 \index{align edits}
1269
1270 When loading media, a common problem is that the various audio/video
1271 tracks do not always have exactly the same lengths. For example, you
1272 might load audio/video recordings from your camera and be dismayed
1273 to see that the audio for each segment is a half second longer than
1274 the video. If you load a large set of media clips by concatenation,
1275 the audio and video will be more skewed as more media is
1276 loaded. Align Edits makes it possible to adjust the edits so the
1277 audio and/or video align by adjusting
1278 the edits so that the track lengths are consistent. To use this
1279 feature, load all of the desired media and select a region which
1280 contains all of the edits to be aligned in the timeline. Now select
1281 the menu bar \texttt{Edit $\rightarrow$ Align Edits} menu item to
1282 operate the change. The topmost armed track is used as a template
1283 reference, and the rest of the tracks are either cut or padded to
1284 align the edit boundaries.  Besides aligning audio with the video,
1285 you can also align video with the audio if the first armed track is
1286 audio. The code performs the following algorithm:
1287
1288 \begin{itemize}
1289 \item Use the first armed track as the master track (it must
1290   contain data).
1291 \item Collect the \textit{edit project start times} on the
1292   selected master track. Only edits that are 100\% inside the selected
1293   area will be used.
1294 \item Set all other tracks to match the \textit{edit times} of
1295   the template track, either by putting in silence or cutting the
1296   region to align the edits on the \textit{edit times} of the master
1297   track.
1298 \end{itemize}
1299
1300 The start time sequence of media and silence edits
1301 along the master track are collected as the target alignment
1302 boundaries. All armed tracks after the master track are modified so
1303 that if the next edit edge is too soon, it adds silence; if it is
1304 too late, edits are shortened or deleted past the point of the next
1305 target alignment boundary time.  Align Edits works best if there are
1306 an equal number of Video and Audio sections.  Also, it is better to
1307 use cuts instead of adding silence -- if there are silence edits
1308 together, the algorithm will combine the silence edits into a single
1309 edit and results may not be as desired.
1310
1311 The first two screenshots in figure~\ref{fig:align} show the Before,
1312 the Highlighted Edits to be manipulated, and the After results for
1313 the Align Edits. The third screenshot \textit{adds silence} in the
1314 second section as noted in red letters.
1315
1316 \begin{figure}[htpb] \centering
1317   \includegraphics[width=1.0\linewidth]{align.png}
1318   \caption{Align edits}
1319   \label{fig:align}
1320 \end{figure}
1321
1322
1323 \subsection{Reverse Edits}%
1324 \label{sub:reverse_edits}
1325 \index{reverse edits}
1326
1327 The Reverse Edits can be useful to change the order of 2 edits in
1328 the case where you would like to put a \textit{teaser} section that
1329 occurred in the middle of a movie at the beginning instead, that is,
1330 reversed positions.  To operate, highlight completely the edit areas
1331 you would like reversed and then use the pulldown \texttt{Edit
1332   $\rightarrow$ Reverse Edits}.
1333
1334 Figure~\ref{fig:reverse01} shows the selected / highlighted area to
1335 which Edits will be applied.  Note the first edit is 0002, followed
1336 by 0003, 0004, and 0005 in that order.
1337
1338 \begin{figure}[htpb]
1339   \centering
1340   \includegraphics[width=0.9\linewidth]{reverse01.png}
1341   \caption{Selected area for Reverse Edits}
1342   \label{fig:reverse01}
1343 \end{figure}
1344
1345 Figure~\ref{fig:reverse02} shows the results of executing
1346 \textit{Reverse Edits}.  Now you will see the reversed order of
1347 0005, 0004, 0003, and last 0002.
1348
1349 \begin{figure}[htpb]
1350   \centering
1351   \includegraphics[width=0.9\linewidth]{reverse02.png}
1352   \caption{Results of the Reverse Edits}
1353   \label{fig:reverse02}
1354 \end{figure}
1355
1356
1357 \subsection{Shuffle Edits}%
1358 \label{sub:shuffle_edits}
1359 \index{shuffle edits}
1360
1361 The file pulldown \texttt{Edit $\rightarrow$ Shuffle Edits} will
1362 randomly exchange the location of the edits.  This feature can be
1363 used to change the order of the music like you would do from your
1364 MP4 player where you have a playlist of your favorite music.  Or
1365 perhaps you are creating an advertisement background, you can
1366 randomly change it, thus the viewer sees a different order of scenes
1367 each time shown.
1368
1369 Figure~\ref{fig:shuffle} illustrating Shuffle Edits of the
1370 highlighted area of the first screenshot on the page.  Note the
1371 permutation of the fragments resulting in 0002 now being first, then
1372 0004, 0003, and 0005 last.
1373
1374 \begin{figure}[htpb]
1375   \centering
1376   \includegraphics[width=0.9\linewidth]{shuffle.png}
1377   \caption{Shuffle edits: the edits are permutated}
1378   \label{fig:shuffle}
1379 \end{figure}
1380
1381 \section{Multi-Session}%
1382 \label{sec:multi_session}
1383 \index{multi-session}
1384
1385 You can run as many sessions of \CGG{} as your computer resources allow.  However, if you are using the same \texttt{\$HOME/.bcast5}, changes you make for one may impact the others. You can always create and rename a new \texttt{.bcast5} from:\\
1386 \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface $\rightarrow$ Index files:} and press \textit{Index files go here}
1387
1388 \section{Multi-Viewer Window Support}%
1389 \label{sec:multi_viewer_window_support}
1390 \index{multi-viewer window}
1391
1392 You can create as many Viewer windows as you want in \CGG{}.  These are handy for users who are adept at working with a lot of different clips simultaneously.  By bringing up multiple Viewer windows, each clip can be edited in its own area, making it easy to see all of the separate pieces.  After you have loaded some media files, to start another Viewer window, right click on one of the pieces of media in the Resources window.  This brings up a menu of several options, one of which is \textit{view in new window}.  Choose this option and that media will come up in a new Viewer window for you to work (figure~\ref{fig:multi-view01}).
1393
1394 \begin{figure}[htpb]
1395         \centering
1396         \includegraphics[width=1.0\linewidth]{multi-view01.png}
1397         \caption{Shown here are 3 Viewer windows and the \textit{View in new window} popup}
1398         \label{fig:multi-view01}
1399 \end{figure}
1400
1401 \section[ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing]{ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing}%
1402 \label{sec:shuttle_jog_wheels_editing}
1403 \index{shuttle pro v2 and shuttlexpress}
1404
1405 The ShuttlePROv2 and ShuttleXpress are affordable jog wheels\protect\footnote{programmatic specifications from Eric Messick} which
1406 can be useful for working with Cin, especially if you do a lot of
1407 playing forward/backward, fast/slow/normal, and single frames
1408 (figure~\ref{fig:shuttle}).
1409 %
1410 Directions for using the ShuttlePROv2 and the ShuttleXpress with
1411 \CGG{} are described next. These devices work by sending keystrokes
1412 used in Cin, corresponding to the shuttle action, to the keyboard
1413 buffer. The shuttle has been fully integrated into the \CGG{} code
1414 so that after the one initial setup, no further intervention is
1415 required.  The multi-speed outer wheel works the same and has the
1416 same number of S positions on both shuttles but the shuttle Xpress
1417 has only 5 keys.  Since the majority of user operations will most
1418 likely be with the use of the 2 wheels, the slightly smaller Xpress
1419 could be a better choice with its 5 easy to reach keys.  The Pro is
1420 approximately $4\times7$\,inches whereas the Xpress is about
1421 $4\times4$\,inches.
1422
1423 \begin{figure}[htpb]
1424   \centering
1425   \includegraphics[width=0.9\linewidth]{shuttle.png}
1426   \caption{ShuttlePROv2 and ShuttleXpress}
1427   \label{fig:shuttle}
1428 \end{figure}
1429
1430 The vendor supplied \textit{string} device names for the shuttles
1431 are currently:
1432
1433 \texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttlePRO\_v2-event-if00}\\
1434 \texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttleXpress-event-if00}\\
1435 \texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttlePro-event-if00}
1436
1437 Only 1 necessary initial setup is required due to permission
1438 settings for non-root usage. As root, just copy a file that provides
1439 the necessary permissions to use the shuttle, then reboot, Example
1440 copy:
1441
1442 \begin{lstlisting}[style=sh]
1443 sudo cp {cindat_path}/doc/99-ShuttlePRO.rules /etc/udev/rules.d/
1444 \end{lstlisting}
1445
1446 then the next time after you reboot, the permissions should be
1447 correct. This file only needs to contain one of the following lines
1448 depending on which shuttle version you have/use, but all will be in
1449 the file.
1450
1451 \begin{lstlisting}[style=sh]
1452 # for  newer PRO model
1453 ATTRS{name}=="Contour Design ShuttlePro" MODE="0644"
1454 # for older PRO model
1455 ATTRS{name}=="Contour Design ShuttlePRO v2" MODE="0644"
1456 # for the Xpress model
1457 ATTRS{name}=="Contour Design ShuttleXpress" MODE="0644"
1458 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0b33", ATTRS{idProduct}=="0020", MODE="0666"
1459 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0b33", ATTRS{idProduct}=="0030", MODE="0666"
1460 \end{lstlisting}
1461
1462 If you swap your shuttle, for example upgrade from an Xpress to a
1463 PROv2, just stop Cin, unplug the original shuttle, plug in the
1464 replacement shuttle, and restart Cin.  If you start the \CGG{}
1465 program and the shuttle does not function as before, stop \CGG{} and
1466 then simply unplug it and plug it in again.  There are a couple of
1467 reasons why it may stop functioning.  One is because \CGG{} was not
1468 stopped with the usual Quit command and the shuttle was improperly
1469 shut down when there was a crash.  The other possibility is that a
1470 static discharge occurred in the area.
1471
1472 A default shuttlerc file is automatically used when a shuttle device
1473 is plugged in when Cin is started. This file sets up the key
1474 bindings for \CGG{} to use. You can override any default settings by
1475 having a local file in your \texttt{\$HOME} directory, named
1476 \texttt{.shuttlerc} to reflect your personal preferences.
1477
1478
1479 \subsection{How to Modify the Default Key Settings}%
1480 \label{sub:modify_default_key_settings}
1481
1482 Detailed information on how to modify your local \texttt{.shuttlerc}
1483 file is described next, but if you need help you can request more
1484 information in the forum at {\small
1485   \url{https://cinelerra-gg.org}}. In the \texttt{shuttlerc} file, a
1486 \# always represents a comment and blank lines are ignored.  The
1487 first thing you must do is copy the system supplied
1488 \texttt{shuttlerc} file to your \texttt{\$HOME} directory and rename
1489 it as \texttt{.shuttlerc} (with a period).
1490
1491 The \texttt{shuttlerc} file has sections that in the case of \CGG{},
1492 represent different windows allowing you to set the keys, K1-K15 for
1493 the Pro and K5-K9 for the Xpress, the shuttle wheel positions of
1494 S0/S1/S-1 for stop, S2 through S7 for wheeling to the right, and S-7
1495 through S-2 for wheeling to the left for reverse.  Then there is JR
1496 to jog right (clockwise) and JL to jog left (counter-clockwise) for
1497 the inner smaller wheel for single frame movement.  See the key
1498 arrangement on a later page for location of the keys for each of the
1499 two different shuttles.
1500
1501 The sections are surrounded by brackets for windows such as \CGG{}
1502 (the main window), Viewer, Composer, Resources, Load, and Default.
1503 If you want the keys to be defined the same in every window, you can
1504 bracket each window on lines one right after the other and then just
1505 define one set of keys.  The other lines will have the key
1506 name/shuttle position followed by its assigned value.  The values
1507 you use for the keys are usually shortcuts and have to be
1508 operationally defined within \CGG{}. For example, the shortcut “f”
1509 to go fullscreen is defined so can be used; however the shortcut “h”
1510 is not defined so will not do anything.  You can check the file,
1511 shortcuts.html, for some options to use.
1512
1513 Next are a few actual examples from the default
1514 \texttt{{cindat\_path}/shuttlerc} file.
1515
1516 The next brackets represent sections. Default, Resources, Load
1517 windows all use the same key values.
1518
1519 \begin{lstlisting}[style=sh]
1520 [Default]
1521 [Resources]
1522 [Load]
1523 K5 XK_Home
1524 K6 XK_Button_1 # same as mouse button 1
1525 K7 XK_Button_2 # same operation as mouse button 2
1526 K8 XK_Button_3
1527 K9 XK_End
1528 # for example, in the Load menu, use scroll up to get to the next file name
1529 JL XK_Scroll_Up
1530 JR XK_Scroll_Down
1531 \end{lstlisting}
1532
1533 Cinelerra with brackets around it next, is the section with some key
1534 definitions for the main window.
1535
1536 \begin{lstlisting}[style=sh]
1537 [Cinelerra]
1538
1539 # Most useful functions have to be on K5-K9
1540 # because Xpress only has 5 keys
1541 K5 XK_Home      # Beginning
1542 K6 XK_KP_6      # Reverse, or if playing Stop
1543 K7 XK_KP_0      # Stop
1544 K8 XK_KP_3      # Play, or if playing Stop
1545 K9 XK_End       # End
1546 ...
1547 S-7 REV_16      # Next 6 are reverse keys
1548 S-6 REV_8       #  the number on the end represents speed
1549 S-5 REV_4       #  number can be decimal up to 64
1550 S-4 REV_2       #  2 means 2x or double speed
1551 S-3 REV_1
1552 S-2 REV_0.5     #  0.5 represents 1/2 speed
1553 S-1 XK_KP_0     # Because the Shuttle does not generate S0,
1554                 #   have to use S-1
1555 S0  XK_KP_0     # Hardware does not generate S0
1556 S1  XK_KP_0     # Because the Shuttle does not generate S0,
1557                 #   have to use S1
1558 S2  FWD_0.5
1559 S3  FWD_1
1560 ...
1561 \end{lstlisting}
1562
1563 An explanation for the above REV and FWD key symbol values is
1564 necessary to facilitate user preferences.  Obviously REV stands for
1565 reverse and FWD for forward.  You can set any speed up to and
1566 including 64x (that is, 64 times the normal speed) on any of the S
1567 keys.  First in the line is the key name such as S-3 and then the
1568 key direction of FWD or REV followed by the symbol for underscore
1569 (\_) and then the numerical value to use.  For example, if you want
1570 the $5^{th}$ forward position, S5, to play 10$\frac{1}{2}$ times
1571 faster, you would use the statement \texttt{S5 FWD\_10.5}.  Integer
1572 or decimal numbers are legal.
1573
1574 For the Viewer, you may want keys defined to do a Splice or an
1575 Overwrite so define differently.  Note that assignments that contain
1576 single character letters must be enclosed in quotes.
1577
1578 \begin{lstlisting}[style=sh]
1579 [Viewer]
1580 # Splice - Viewer only; may be defined
1581 # differently than Composer or Cinelerra
1582 K2 "v"
1583 K4 "b"          # Overwrite
1584 \end{lstlisting}
1585
1586 To change any key value to an alternative value, just edit the file
1587 and make the changes.  Besides just keys and alphabetic letters of
1588 numbers, you can also use any \CGG{} value that contains the
1589 combination with Shift, Alt, and Ctrl.  For keys that are not
1590 printable characters, you can look up the symbol name to use for a
1591 specific operation in the file called:
1592 \texttt{/usr/include/X11/keysymdef.h}. Some examples:
1593
1594 \begin{lstlisting}[style=sh]
1595 K10 Alt-XK_Left   # Go to previous edit \\
1596 K13 Ctrl-XK_Right # Go to next label
1597 \end{lstlisting}
1598
1599 For sequences of one or more \textit{printable} characters, you can
1600 just enclose them in double quotes.  For example in the
1601 \texttt{[Composer]} section, to go into or out of fullscreen mode,
1602 automatically start playing and put a label there, you could define
1603 a key like this:  K7 “f~l” - that is printable character f, a space,
1604 and printable character l.
1605
1606 After modifying \texttt{.shuttlerc}, the next time you use the
1607 shuttle, your changes will automatically take affect without even
1608 having to stop and restart Cin.  However, the first thing to try if
1609 problems is to stop \CGG{}, unplug the shuttle, wait a few seconds,
1610 plug it in again, and then restart cin.  If for some reason, the
1611 shuttle keys still do not work after that, you may have an incorrect
1612 setup and you will have to correct that first.  For example, if you
1613 define S5 twice within the \CGG{} setup, it will fail.  It is
1614 suggested that if you make changes, you should initially uncomment
1615 DEBUG in the \texttt{.shuttlerc} file and start up \CGG{} from a
1616 terminal window so that you can make sure it is working and has no
1617 output errors.  An error might look like:
1618
1619 \begin{lstlisting}[style=sh]
1620 dupl key name: [Cinelerra]K1
1621 shuttle config err file: /root/.shuttlerc, line:37
1622 \end{lstlisting}
1623
1624 Keep in mind when changing the values, that the ShuttleXpress has
1625 fewer buttons so if you define K1 it will only work for the
1626 ShuttlePro.
1627
1628 Any time you are having trouble with your shuttle, you can copy the
1629 default \texttt{shuttlerc} file from
1630 \texttt{{cindat\_path}/shuttlerc} to your local \texttt{.shuttlerc}
1631 file, and edit that to\ switch to DEBUG mode by removing the \#
1632 comment from the DEBUG line.  But you will have to have started Cin
1633 from a terminal window to see the key values. The first time you use
1634 the shuttle or after you change the file, the current assignments
1635 will show in the terminal window so will look something like:
1636
1637 \begin{lstlisting}[style=sh]
1638 [Cinelerra] # 1
1639 K5[D]: XK_KP_0/U
1640 K5[U]: XK_KP_0/U
1641 \end{lstlisting}
1642
1643 When you are in DEBUG mode and are just working away, what you will
1644 see is something like this:
1645
1646 \begin{lstlisting}[style=sh]
1647 key: 0058 1
1648 key: 0055 0
1649 \end{lstlisting}
1650
1651 or:
1652
1653 \begin{lstlisting}[style=sh]
1654 shuttle:  00 00 00 00 00
1655 key: XK_Home 0
1656 \end{lstlisting}
1657
1658 When you change the focus from one window to another, you will see
1659 something like this:
1660
1661 \begin{lstlisting}[style=sh]
1662 new focus: 04c00137
1663 new translation: Viewer
1664 key: 0059 1
1665 \end{lstlisting}
1666
1667 You can also set an environment variable to temporarily use an
1668 alternative shuttle configuration file for testing as in:
1669
1670 \begin{lstlisting}[style=sh]
1671 export SHUTTLE_CONFIG_FILE=/tmp/shuttlerc_test
1672 \end{lstlisting}
1673
1674 The shuttle wheel occasionally will not \textit{stop} after you have
1675 wheeled it to play forward.  This is a documented known problem from
1676 the original code so you just have to joggle it a little in the
1677 other direction and then it will stop.  S0 does not always generate
1678 a signal to do a stop and that is why S1 and S-1 have to be used to
1679 relay the stop instead.  Also, if you have a fullscreen Composer or
1680 Viewer up and the regular one also, the fullscreen takes precedence.
1681
1682
1683 \subsection{Troubleshooting auxilliary information}%
1684 \label{sub:troubleshooting_auxilliary_information}
1685
1686 In order to see if you hardware was recognized by the operating
1687 system, key in:
1688
1689 \begin{lstlisting}[style=sh]
1690 lsusb -v -d 0b33:0030  # for the Shuttle Pro or PROv2\\
1691 lsusb -v -d 0b33:0020  # for the Shuttle Xpress
1692 \end{lstlisting}
1693
1694 \paragraph{Note 1} Currently, the keys K14 and K15 do not function
1695 on the \textit{Contour Design ShuttlePro} but do on the
1696 \textit{Contour Design ShuttlePRO v2} due to a Report Descriptor
1697 error.  You can workaround this by uncommenting \texttt{USB\_DIRECT}
1698 in your local \texttt{.shuttlerc} file.  This directly uses libusb
1699 rather than the generic Linux hid driver.  \texttt{USB\_DIRECT}
1700 works for any of the currently tested shuttles.
1701
1702 \paragraph{Note 2} If you are not sure if your shuttle is fully
1703 functional, you can verify that the hardware device has been seen by
1704 your operating system with this procedure.
1705 \begin{enumerate}
1706 \item From a terminal window as an ordinary user key in: lsusb (the
1707   first character is a lower case L for list).  You will see
1708   something like the following depending on which usb device you
1709   have the ShuttlePro plugged into:
1710 \begin{lstlisting}[style=sh]
1711 Bus 003 Device 002: ID 0b33:0030 Contour Design, Inc. ShuttlePro v2
1712 \end{lstlisting}
1713 \item To make sure you have usbmon installed key in:
1714 \begin{lstlisting}[style=sh]
1715 sudo modprobe usbmon
1716 \end{lstlisting}
1717 \item Next key in the following:
1718 \begin{lstlisting}[style=sh]
1719 sudo od -tx1 /dev/usbmon3
1720 \end{lstlisting}
1721   where the last 3 is the same \# as the Bus in above.  If it lists
1722   \texttt{Bus 002}, then use \texttt{/dev/usbmon2} instead.
1723 \item Now with focus in that same terminal window, press any shuttle
1724   key just to see what happens and should see about 12 lines similar
1725   to these below -- a new set every time you press a single key or
1726   the wheel.  The lines are usually not important, just the fact
1727   that you get a response is.  However if you have multiple devices
1728   on the same bus, you will get responses from any and all of them.
1729   Attempt to isolate your shuttle by temporarily unplugging
1730   unnecessary devices on the same bus or plug the shuttle into a
1731   different usb port that has fewer devices.
1732     \begin{lstlisting}[style=sh]
1733 0000000 80 70 99 75 53 8c ff ff 43 01 81 02 03 00 2d 00
1734 0000020 4e 61 5c 5c 00 00 00 00 8d 2c 06 00 00 00 00 00
1735 0000040 05 00 00 00 05 00 00 00 00 00 00 00 00 00 00 00
1736 0000060 01 ff 00 00 00 80 70 99 75 53 8c ff ff 53 01 81
1737 0000100 02 03 00 2d 3c 4e 61 5c 5c 00 00 00 00 b1 2c 06
1738 0000120 00 8d ff ff ff 05 00 00 00 00 00 00 00 00 00 00
1739 0000140 00 00 00 00 00 80 70 99 75 53 8c ff ff 43 01 81
1740 0000160 02 03 00 2d 00 4e 61 5c 5c 00 00 00 00 3d d7 09
1741 0000200 00 00 00 00 00 05 00 00 00 05 00 00 00 00 00 00
1742 0000220 00 00 00 00 00 00 ff 00 00 00 80 70 99 75 53 8c
1743 0000240 ff ff 53 01 81 02 03 00 2d 3c 4e 61 5c 5c 00 00
1744 0000260 00 00 64 d7 09 00 8d ff ff ff 05 00 00 00 00 00
1745 \end{lstlisting}
1746 \item Next press the key that you want to verify is functioning --
1747   if no new lines show up, then the key is non-functional so there
1748   is a hardware problem.  If you get output, then perhaps there is a
1749   problem with your software setup.
1750 \item Use Ctrl-C on the terminal window when done to get back to the
1751   prompt.
1752 \end{enumerate}
1753
1754 \paragraph{Note 3} Another method for testing to make sure your
1755 model of the Shuttle does not have different key definitions than
1756 the one that \CGG{} was coded for is to do the following.
1757
1758 \begin{enumerate}
1759 \item Locate the shudmp.C program in your \CGG{} directory.
1760 \item Compile that with the command:  \texttt{c++ shdmp.C -o shudmp}
1761 \item Make the file executable with the command:  \texttt{chmod +x shudmp}
1762 \item Execute:
1763 \begin{lstlisting}[style=sh]
1764 sudo ./shdmp /dev/input/by-id/usb-Contour\_Design\_ShuttlePro-event-if00 # substitute your shuttle
1765 \end{lstlisting}
1766 \end{enumerate}
1767
1768 Then press your shuttle key that is having problems and check the
1769 results.  They should look like:
1770
1771 \begin{lstlisting}[style=sh,caption={Example for K7}]
1772 event: (4, 4, 0x90007)  #The last number, 7, is the expected Key number.
1773 event: (1, 262, 0x1)
1774 event: (0, 0, 0x0)
1775 event: (4, 4, 0x90007)
1776 event: (1, 262, 0x0)
1777 event: (0, 0, 0x0)
1778 \end{lstlisting}
1779
1780 \begin{lstlisting}[style=sh,caption={Example for K15}]
1781 Example for K15:
1782 event: (4, 4, 0x9000f)  #The last number f is 15 in hexadecimal and is the expected Key.
1783 event: (1, 270, 0x1)
1784 event: (0, 0, 0x0)
1785 event: (4, 4, 0x9000f)
1786 event: (1, 270, 0x0)
1787 event: (0, 0, 0x0)
1788 \end{lstlisting}
1789
1790 When done, you will have to Ctrl-C to get out of the program.
1791
1792 \paragraph{Note 4} For developers, if you have a pre-UEFI Secure
1793 Boot kernel it is also possible to do the following for further in
1794 depth testing:
1795
1796 \begin{lstlisting}[style=sh]
1797 ls /sys/kernel/debug/hid   \# to locate numerical value of the shuttle, e.g. 0003:0B33.0030.0006
1798 cat "/sys/kernel/debug/hid/0003:0B33.0030.0006/rdesc"  # substitute your own numerical value
1799 cat "/sys/kernel/debug/hid/0003:0B33.0030.0006/events"  # press keys to see the results
1800 \end{lstlisting}
1801 %\begin{enumerate}
1802     %\item \texttt{ls /sys/kernel/debug/hid   \# to locate numerical value of the shuttle, e.g. 0003:0B33.0030.0006}
1803     %\item \texttt{cat “/sys/kernel/debug/hid/0003:0B33.0030.0006/rdesc”    \# substitute your own numerical value}
1804     %\item \texttt{cat “/sys/kernel/debug/hid/0003:0B33.0030.0006/events”  \# press keys to see the results}
1805 %\end{enumerate}
1806
1807 \subsection{Shuttle key default arrangement for \CGG{} / Composer / Viewer:}%
1808 \label{sub:shuttle_key_default_cinelerra}
1809
1810 The following is the default setting for the ShuttlePROv2 and
1811 ShuttleXpress (table~\ref{tab:shuttleprov2} and
1812 table~\ref{tab:xpress}).  This page can be quickly requested from \CGG{} by
1813 simultaeneously pressing the \texttt{Alt} key on the keyboard and any button on the Shuttle.
1814
1815 \renewcommand{\arraystretch}{1.15}
1816 \begin{table}[ht]
1817   \caption{ShuttlePROv2 key default arrangement for \CGG{} /
1818     Composer / Viewer}
1819   \label{tab:shuttleprov2}
1820   % Tell table to adjust font to fix on the page using \resize
1821   \resizebox{\textwidth}{!}{%
1822     \begin{tabular}{c c c c c c c}
1823       \toprule
1824       K1 & K2 & & K3 & K4 & &\\
1825       Label & Future use & & Future use & Clip & &\\
1826          & Splice (viewer) & & Copy  & Overwrite (viewer) & &\\
1827       \midrule
1828       K5 & K6 & K7 & K8 & K9 & &\\
1829       Home & Reverse & Stop & Play & End & &\\
1830          & & Fullscreen & & & &\\
1831          & & (viewer / compositor) & & & &\\
1832       \midrule
1833       Home(Defaults) & MouseBtn1(D) & MouseBtn2(D) & MouseBtn3(D) & End(Defaults) & &\\
1834       \midrule
1835       \multicolumn{7}{c}{Shuttle Outer Wheel}\\
1836       \multicolumn{7}{c}{Play forward (first row) or Play reverse (second row)}\\
1837       S1=Stop  & S2=1/2 & S3=Normal  & S4=2x & S5=4x & S6=8x & S7=16x\\
1838       S-1=Stop &  S-2=1/2 & S-3=Normal & S-4=2x & S-5=4x & S-6=8x & S-7=16x\\
1839       \midrule
1840       K14 & & Jog Left & (Inner Wheel) & Jog Right & & K15\\
1841       Toggle In & & Frame reverse & & Frame forward & & Toggle Out\\
1842          & & Scroll up(Defaults) & & Scroll down(Defaults) & &\\
1843       \midrule
1844          & & K10  & &  K11 & &\\
1845          & & Previous Edit & & Next Edit & &\\
1846          & & Future Use(Viewer) & & Future Use(Viewer) & &\\
1847       \midrule
1848          & & K12  & &  K13 & &\\
1849          & & Previous Edit & & Next Edit & &\\
1850          & & Previous Label & & Next label & &\\
1851       \bottomrule
1852     \end{tabular}}
1853 \end{table}
1854
1855 \begin{table}[ht]
1856   \caption{ShuttleXpress key default arrangement for \CGG{} / Composer / Viewer}
1857   \label{tab:xpress}
1858   % Tell table to adjust font to fix on the page using \resize
1859   \resizebox{\textwidth}{!}{%
1860     \begin{tabular}{c c c c c c c}
1861       \toprule
1862       K5 & K6 & K7 & K8 & K9 & &\\
1863       Home & Reverse & Stop & Play & End & &\\
1864          &         & Fullscreen & & & &\\
1865          &         & (viewer / compositor) & & & &\\
1866       \midrule
1867       Home(Defaults) & MouseBtn1(D) & MouseBtn2(D) & MouseBtn3(D) & End(Defaults) & &\\
1868       \midrule
1869       \multicolumn{7}{c}{Shuttle Outer Wheel}\\
1870       \multicolumn{7}{c}{Play forward (first row) or Play reverse (second row)}\\
1871       S1=Stop &   S2=1/2 &   S3=Normal  &  S4=2x  &  S5=4x  &  S6=8x &   S7=16x\\
1872       S-1=Stop &  S-2=1/2 &  S-3=Normal &  S-4=2x &  S-5=4x &  S-6=8x  & S-7=16x\\
1873       \midrule
1874          & & Jog Left & (Inner Wheel) & Jog Right & &\\
1875          & & Frame reverse & & Frame forward & &\\
1876          & & Scroll up(Defaults) & & Scroll down(Defaults) & &\\
1877       \bottomrule
1878     \end{tabular}}
1879 \end{table}
1880
1881
1882 %%% Local Variables:
1883 %%% mode: latex
1884 %%% TeX-master: "../CinelerraGG_Manual"
1885 %%% End: