\drop=0.1\textheight
\fboxsep 0.5\baselineskip
\sffamily
-\vspace*{\drop}
+%\vspace*{\drop}
\centering
{\textcolor{Dark}{\HUGE Cinelerra-GG Version Infinity}}\par
\vspace{0.5\drop}
\chapter{Editing}%
\label{cha:editing}
-Editing comprises both time and track space. The timeline consists of the time certain media appear on the track going left to right and a set of tracks from the top to the bottom. There are 2 methods of timeline editing --- drag and drop editing, also called \textit{arrow mode}, and cut and paste editing or \textit{I-beam mode}. Cut and Paste is the default editing mode. An additional, but not often considered editing method is called \textit{two-screen editing} where the Viewer is used to view media and then the desired clip from the media is transferred to the timeline.
+Editing comprises both time and track space. The timeline consists of the time certain media appear on the track going left to right and a set of tracks from the top to the bottom. There are 2 methods of timeline editing -- drag and drop editing, also called \textit{arrow mode}, and cut and paste editing or \textit{I-beam mode}. Cut and Paste is the default editing mode. An additional, but not often considered editing method is called \textit{two-screen editing} where the Viewer is used to view media and then the desired clip from the media is transferred to the timeline.
The timeline is where all editing decisions are made (figure~\ref{fig:timeline}). This is a stack of tracks in the center of the main window. It can be scrolled up, down, left and right with the scrollbars on the right and bottom. It can also be scrolled up and down with a mouse wheel, or left and right while holding down the Ctrl key and using the mouse wheel.
\begin{description}
\item[Gang Fader] cause the fader to track the movement of whatever other fader you are adjusting by dragging either the fader or the curve on the track. It doesn't affect the editing made with menu controls. A fader is only ganged if the arm track is also on. This is often used to adjust audio levels on all the tracks simultaneously. Gang also causes Nudge parameters to synchronize across all the ganged tracks.
\item[Draw Media] determines if picons or waveforms are drawn on the asset in the track. You may want to disable this if you know that the media/format takes a long time to draw on the timeline. By default it is set to on in order to see picons on the timeline.
- \item[Don’t send to output] , more commonly called \textit{mute}, causes the output to be thrown away once the track is completely rendered. This happens whether or not \textit{Play track} is on. For example if you mute all the video tracks, the rendered media file will have a blank video track. Mute track is represented on the timeline with a line that has the default color of pink/orange. Use the pulldown View $\rightarrow$ Mute to have the line displayed. It is a keyframable attribute, but Mute track keyframing is a toggle and it has only the two values of on or off. If a track is part of a shared track effect, the output of the track with the shared track effect is overlaid on the final output even though it is routed back to another track (the shared track). Mute track is used to keep the track with the shared track effect from overlapping the output of the source track (the shared track) where the shared track effect is not present.
+ \item[Don’t send to output] , more commonly called \textit{mute}, causes the output to be thrown away once the track is completely rendered. This happens whether or not \textit{Play track} is on. For example if you mute all the video tracks, the rendered media file will have a blank video track. Mute track is represented on the timeline with a line that has the default color of pink/orange. Use the pulldown \texttt{View $\rightarrow$ Mute} to have the line displayed. It is a keyframable attribute, but Mute track keyframing is a toggle and it has only the two values of on or off. If a track is part of a shared track effect, the output of the track with the shared track effect is overlaid on the final output even though it is routed back to another track (the shared track). Mute track is used to keep the track with the shared track effect from overlapping the output of the source track (the shared track) where the shared track effect is not present.
\item[Fader slider] fade values are represented on the timeline with a pink curve that is keyframable. All tracks have a fader, but the units of each fader depend on whether it is audio or video. Audio fade values are in dB. They represent relative levels, where 0 is the unaltered original sound level, -40 is silence, -80 the minimum value set by default. You can move fader and keyframes down to -80 but the parameter's curve won't go below -40. For your convenience you can set a different fade range with the curve zoom. Audio fader’s main purpose is to \textit{fade out} sound or to lower the sound level smoothly to silence, or \textit{fade in} to make sounds appear gradually instead of suddenly. Video fade values are the percentage of opacity of the image in normal overlay mode, the percentage of the layer that is mixed into the render pipeline in the other overlay modes.
Click and drag the fader to fade the track in and out. If it is ganged to other tracks of the same media type, with the arm option enabled, the other faders should follow. Hold down the Shift key and drag a fader to center it on the original source value (0 for audio, 100 for video).
\item[mixer] in the expanded patchbay for that track designate the multi-camera mixer mode.
\begin{description}
\item[Audio$\rightarrow$Map 1:1] This maps every track to its own channel and wraps around when all the channels are allocated. It is most useful for making 2 tracks with 2 channels map to stereo and for making 6 tracks with 6 channels map to a 6 channel sound card.
- \item[Audio$\rightarrow$Map 5.1:2] This maps 6 tracks to 2 channels. The project should have 2 channels when using this function. Go to Settings $\rightarrow$ Format to set the output channels to 2. This is most useful for down-mixing 5.1 audio to to stereo (for more information refer to Configuration, Settings and Preferences chapter 15.1).
+ \item[Audio$\rightarrow$Map 5.1:2] This maps 6 tracks to 2 channels. The project should have 2 channels when using this function. Go to \texttt{Settings $\rightarrow$ Format} to set the output channels to 2. This is most useful for down-mixing 5.1 audio to to stereo (for more information refer to Configuration, Settings and Preferences section \ref{sub:audio_out_section}).
\end{description}
\paragraph{Standard audio mappings} Although Cinelerra lets you map any audio track to any speaker, there are standard mappings you should use to ensure the media can be played back elsewhere. Also, most audio encoders require the audio tracks to be mapped to standard speaker numbers or they will not work.
\noindent These In/Out points define a clip. You can now use this in a couple of different ways.
-\paragraph{Splice} The splice icon, or shortcut letter “v”, inserts the selected area in the timeline after the insertion point. After the splice has taken effect, the insertion point moves to the end of the edit ready to be used as the next splice location. This way you can continuously build up the program by splicing.
+\paragraph{Splice} The splice icon, or shortcut letter “\texttt{v}”, inserts the selected area in the timeline after the insertion point. After the splice has taken effect, the insertion point moves to the end of the edit ready to be used as the next splice location. This way you can continuously build up the program by splicing.
If an In point or an Out point exists on the timeline the clip is inserted after the In point or after the Out point. If both In and Out points are set on the timeline, the clip is inserted after the In point. If there are edits after your chosen splice location on the timeline, they will be moved to the right.
-\paragraph{Overwrite} The overwrite icon, or shortcut letter “b”, overwrites the region of the timeline after the insertion point with the clip. If an In point or an Out point exists on the timeline the clip is overwritten after the In point or after the Out point. If both In and Out points are set on the timeline, the clip is inserted after the In point. If a region is highlighted or both In and Out points exist they limit the region of the overwriting and the clip may therefore be shortened. Here is a detailed explanation to take advantage of this method.
+\paragraph{Overwrite} The overwrite icon, or shortcut letter “\texttt{b}”, overwrites the region of the timeline after the insertion point with the clip. If an In point or an Out point exists on the timeline the clip is overwritten after the In point or after the Out point. If both In and Out points are set on the timeline, the clip is inserted after the In point. If a region is highlighted or both In and Out points exist they limit the region of the overwriting and the clip may therefore be shortened. Here is a detailed explanation to take advantage of this method.
To overwrite exactly on a precise region of the timeline:
If the destination region is shorter than the clip defined in the viewer, the portion of the clip longer than the destination region won't be inserted and on the timeline the following edits won't move.
If the destination region is longer than the clip defined in the viewer, the destination region will shrink and on the timeline the following edits will move to the left.
-\paragraph{Clip} The clip icon, or shortcut letter “i”, generates a new clip for the resource window containing the affected region but does not change the timeline. Every clip has an optional/default title and description.
+\paragraph{Clip} The clip icon, or shortcut letter “\texttt{i}”, generates a new clip for the resource window containing the affected region but does not change the timeline. Every clip has an optional/default title and description.
-\paragraph{Copy} The copy icon, or shortcut letter “c”, copies the selection into the copy buffer.
+\paragraph{Copy} The copy icon, or shortcut letter “\texttt{c}”, copies the selection into the copy buffer.
\subsection{Use Case – Working with Sequences}
\label{sub:use_case_working_sequences}
Using labels and In/Out points are useful in editing audio. You can set In/Out points for the source region of the source waveform and set labels for the destination region of the destination waveform. Perform a cut, clear the In/Out points, select the region between the labels, and perform a paste.
-\paragraph{In / Out Points} The In and Out bracket placement is explained here to illustrate their usage. Because of the shape of the markers"[" and "]" you may assume that they are inclusive --- that everything placed in between would be included in the clip, such as in the case of being transferred to the timeline from the Viewer. In reality, one of the two markers will not include the frame that was visible at the time the marker was affixed. Depending on whether the \textit{Always show next frame} option is used or not, it is the In or Out marker that will not be inclusive.
+\paragraph{In / Out Points} The In and Out bracket placement is explained here to illustrate their usage. Because of the shape of the markers [ and ] you may assume that they are inclusive -- that everything placed in between would be included in the clip, such as in the case of being transferred to the timeline from the Viewer. In reality, one of the two markers will not include the frame that was visible at the time the marker was affixed. Depending on whether the \textit{Always show next frame} option is used or not, it is the In or Out marker that will not be inclusive.
To obtain a clip on the timeline exactly as you saw in the Viewer, you must necessarily move the In mark back from the beginning before the first desired frame or move the Out mark forward after the last desired frame, depending on the \textit{Always show next frame} setting.
-Some of the confusion can be attributed to the fact that the Viewer shows frames, while the markers determine spaces, i.e. times, that are not visible between frames. You have to think of each frame as being delimited by two spaces - one preceding and one following. The In mark is always placed before the displayed frame and the Out mark is always placed after the displayed frame, while taking into account in its calculations whether the \textit{Always show next frame }option is used or not. If you just remember that the reference of the markers is in the middle of the icon, you will avoid confusion.
+Some of the confusion can be attributed to the fact that the Viewer shows frames, while the markers determine spaces, i.e. times, that are not visible between frames. You have to think of each frame as being delimited by two spaces -- one preceding and one following. The In mark is always placed before the displayed frame and the Out mark is always placed after the displayed frame, while taking into account in its calculations whether the \textit{Always show next frame }option is used or not. If you just remember that the reference of the markers is in the middle of the icon, you will avoid confusion.
\paragraph{Overwrite} To perform overwriting within the timeline paste on a selected region (highlighted or
between In/Out points). The selected region will be overwritten. If the clip pasted from the clipboard
\label{fig:cut}
\end{wrapfigure}
- A \textit{cut} uses a non-empty selection region, where the \textit{blade cut} or \textit{split} has no duration in the selection, just a hairline. As usual the use of cut when a selection is set, deletes/cuts the highlighted area. In the case where an In point or an Out point exists on the timeline, the clip is split at the location of the In/Out point since it has priority over the cursor location. A blade cut simply splits the edit into two edits. In order to have the video and audio aligned, it works best to have Settings $\rightarrow$ Align cursor on frames. When a blade cut occurs, the edges are created as \textit{hard edges}. These are edges that cannot be deleted by track optimizations.
+ A \textit{cut} uses a non-empty selection region, where the \textit{blade cut} or \textit{split} has no duration in the selection, just a hairline. As usual the use of cut when a selection is set, deletes/cuts the highlighted area. In the case where an In point or an Out point exists on the timeline, the clip is split at the location of the In/Out point since it has priority over the cursor location. A blade cut simply splits the edit into two edits. In order to have the video and audio aligned, it works best to have \texttt{Settings $\rightarrow$ Align cursor on frames}. When a blade cut occurs, the edges are created as \textit{hard edges}. These are edges that cannot be deleted by track optimizations.
Cinelerra has built-in optimization on the timeline. So that whenever two parts on the timeline are sequential frames, it automatically optimizes by making them into 1 item. So if you are cutting, dragging, editing, or whatever and somehow frame \# 40 ends up right next to frame \# 41, it optimizes them together. This optimization affects many areas throughout the program code.
-When you do a blade cut/split, all armed tracks will be included in the cut and green-colored triangles will show on the bottom of the track on both the left and the right side of the cut. This is a \textit{hard edge} marker toggle, as opposed to the soft edge designation for an ordinary edit. The \textit{hard edge} marker can be toggled off/on if so desired. In order to not interfere with the usual drag handles, only a few pixels are used for the toggle so you have to be sure you have the cursor right over the hard edge triangle --- when in position, it will be obvious because you can see an arrow pointing to the corner. Use Shift-left mouse button 1 to toggle off/on the hard edge marker on all tracks simultaneously.
+When you do a blade cut/split, all armed tracks will be included in the cut and green-colored triangles will show on the bottom of the track on both the left and the right side of the cut. This is a \textit{hard edge} marker toggle, as opposed to the soft edge designation for an ordinary edit. The \textit{hard edge} marker can be toggled off/on if so desired. In order to not interfere with the usual drag handles, only a few pixels are used for the toggle so you have to be sure you have the cursor right over the hard edge triangle -- when in position, it will be obvious because you can see an arrow pointing to the corner. Use Shift-left mouse button 1 to toggle off/on the hard edge marker on all tracks simultaneously.
\section{Drag and Drop Editing}%
\label{sec:drag_drop_editing}
\subsection{Copy/Paste Behavior}%
\label{sub:copy_paste_behavior}
-There are many options for moving, copying, pasting, inserting, and deleting selected \textit{edits}, more commonly referred to by the user as \textit{clips}, when in the Drag and Drop (arrow) editing mode. This makes it easier to avoid constantly having to disarm/arm tracks. To create a selection move the cursor over the clip and just click the left mouse button; remove a selection by left mouse button click again. This will mark your selection with a colored border which contains some red. The easiest way to initially use the various modes is to click on the middle mouse button when your cursor is over a track and a popup displays the modes and shortcuts. However, for those users who prefer the addition of the Ctrl key to add multiple selections as is commonly done for listbox operations, there is a preference in Settings $\rightarrow$ Preferences $\rightarrow$ Appearance tab, called \textit{Clears before toggle} that changes the behavior.
+There are many options for moving, copying, pasting, inserting, and deleting selected \textit{edits}, more commonly referred to by the user as \textit{clips}, when in the Drag and Drop (arrow) editing mode. This makes it easier to avoid constantly having to disarm/arm tracks. To create a selection move the cursor over the clip and just click the left mouse button; remove a selection by left mouse button click again. This will mark your selection with a colored border which contains some red. The easiest way to initially use the various modes is to click on the middle mouse button when your cursor is over a track and a popup displays the modes and shortcuts. However, for those users who prefer the addition of the Ctrl key to add multiple selections as is commonly done for listbox operations, there is a preference in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab, called \textit{Clears before toggle} that changes the behavior.
When an edit is marked as selected, it can be cut/copied into the paste clip buffer. The constructed clip buffer will begin with the leftmost edit and end with the rightmost edit. The edits may contain media, or be silence, or skipped if they are not selected. The clip tracks are copied from the first track with an active edit selection to the last track with an active edit selection. A clip track can be completely empty if no selection was made on the track. The word \textit{packed} means that the silent edits and empty tracks are not included in the copy to the clip buffer, and all of the elements are packed together, no gaps. Packing a clip buffer makes it easier to move \textit{blobs} of data around. Once the edits have moved and have a relative relationship applied, an unpacked clip buffer allows the media to be copied with the relative positions of the edits preserved.
\subsection{Dragging Groups}%
\label{sub:dragging_groups}
-Dragging while in \textit{Drop and Drag editing mode} (arrow mode) is really easy. Just select the clip or clips you want to drag using the left mouse button, then put your cursor over one of them and drag while holding down the left mouse button. Keyframes, autos, labels, and plugins will also be dragged. Dragging honors armed/disarmed tracks. When you drag there will be 3 possible colors as defined:
+Dragging while in \textit{Drop and Drag editing mode} (arrow mode) is really easy. Just select the clip or clips you want to drag using the left mouse button, then put your cursor over one of them and drag while holding down the left mouse button. Keyframes, autos, labels, and plugins will also be dragged. Dragging honors armed/disarmed tracks. When you drag there will be some possible colors as defined; depends on how the edges of edits and groups interact:
\begin{itemize}
- \item Red color means can not drop here because it will not fit in the space.
- \item Green color means OK to drop in that position.
+ \item Green color means OK to drop in that position as it will fit.
\item Yellow color means you can drop here and when you do it will be exactly next to that existing edit.
+ \item Blue color means it overlaps something and this includes overlapping itself.
+ \item Red color means can not drop here because it will not fit in the space.
+ \item Orange color means the track types do not match so it can not be dropped here.
\end{itemize}
+
+Remember: With the SHIFT key on, it will always \textit{overwrite}. Without the SHIFT key enabled, it always \textit{inserts} only.
+
The original (older) method of dragging while in Arrow mode, lets you just left mouse click on a single clip or aligned clips and just drag. This older method of dragging does not move any of its effects with it at this time. There will only be a white outline while dragging and it will let you drop only if it fits. You can also perform some dragging and grouping while in the \textit{Cut and Paste editing mode} (ibeam mode) by taking advantage of the Ctrl button in conjunction with the left mouse button.
\begin{itemize}
\item Double click selects a column so you can move, for example, the audio and video together by holding
The keyboard Delete key is not hooked to these operations, and is hooked to the
original editing methods.
-In this "group" mode, if there are In/Out markers set, they enter the selection priority queue
+In this \textit{group} mode, if there are In/Out markers set, they enter the selection priority queue
between the column selection and the cursor only. You can see the In/Out markers selected
region colored line across the timebar (slightly underneath where the time, samples or frames show
) on the main timeline
white colored bar at the top and a red colored bar at the bottom with black sections.
\end{itemize}
-The red/white bars represent the presence and the black sections represent the absence of where that media is used on the timeline. To get to a bigger representation, use the “f” key for a full screen. Now
+The red/white bars represent the presence and the black sections represent the absence of where that media is used on the timeline. To get to a bigger representation, use the “\texttt{f}” key for a full screen. Now
you can operate the following buttons to display what you need to see and to move around. It is important to note that \textit{locked tracks} will not be represented. This makes it easy to ignore the audio track segments if you want so there is less confusion in the display.
\begin{itemize}
\item Clicking on the top white or black spaces in the top time bar loads the Viewer with the source media,
- and sets the In/Out "[" and "]" pointers to be the selection of that edit.
+ and sets the In/Out [ and ] pointers to be the selection of that edit.
\item Click on a location in the bottom red or black bar, and the main cursor and composer will re-position
to the corresponding location on the session timeline.
\item Dragging on the red/black bar will correspondingly update the position in the timeline and composer.
\subsection{Editing EDLs within a Project}%
\label{sub:edit-edls}
-To edit EDL that is included with your project as Clips, Nested Clips, Referenced File, or Xml you can use the option "Open EDL"
-in the Resources window for the highlighted media. Then with a simple button click you can return to your main
-timeline project. For example, if you have a nested clip that originally had several plugins added to it before
+To edit EDL that is included with your project as Clips, Nested Clips, Referenced File, or Xml you can use the option \textit{Open EDL} in the Resources window for the highlighted media. Then with a simple button click you can return to your main timeline project. For example, if you have a nested clip that originally had several plugins added to it before
it was nested, you can edit those plugin parameter values. Previously to make any changes to these types of EDL
you had to remake the whole clip from scratch.
-Here is how this works. In the Clip or Media folder or on a timeline EDL edit, the option "Open EDL" for the highlighted clip or nested clip is available so that when you choose this option, that EDL will be brought up on the timeline superseding the current EDL that exists on the timeline. Now, once the clip is open on the timeline, you can edit it however you want. The previous timeline EDL is "pushed onto a stack" so it can be recalled by "popping the stack" with a click of the left mouse button in the upper right hand corner of the timeline to the left of the "shell cmds" icon. Initially this button displays a 0 to indicate your initial timeline/project. Then this button will read 1 if you choose "Open EDL" and then back to 0 and your original timeline with the left mouse click. You can go several levels deep so instead of 1, it could be 2, 3, ... but this requires some thought to avoid potential confusion.
+Here is how this works. In the Clip or Media folder or on a timeline EDL edit, the option \textit{Open EDL} for the highlighted clip or nested clip is available so that when you choose this option, that EDL will be brought up on the timeline superseding the current EDL that exists on the timeline. Now, once the clip is open on the timeline, you can edit it however you want. The previous timeline EDL is \textit{pushed onto a stack} so it can be recalled by \textit{popping the stack} with a click of the left mouse button in the upper right hand corner of the timeline to the left of the \textit{shell cmds} icon. Initially this button displays a 0 to indicate your initial timeline/project. Then this button will read 1 if you choose \textit{Open EDL} and then back to 0 and your original timeline with the left mouse click. You can go several levels deep so instead of 1, it could be 2, 3, $\dots$ but this requires some thought to avoid potential confusion.
\\
An example of a typical set of steps to follow is:
\begin{enumerate}
- \item Load your media using insertion strategy of "Replace current project". There will be \# 0 in the
- upper right hand corner of the main menu with the tooltip of "Close EDL".
- \item Highlight a selection on the timeline and press the "To clip" icon and click the green checkmark OK.
+ \item Load your media using insertion strategy of \textit{Replace current project}. There will be \# 0 in the
+ upper right hand corner of the main menu with the tooltip of \textit{Close EDL}.
+ \item Highlight a selection on the timeline and press the \textit{To clip} icon and click the green checkmark OK.
\item In the Resources window, open the Clip folder and you will see that Clip 1 is present.
- \item Highlight Clip1 and right mouse the item to bring up available options and select "Open EDL".
+ \item Highlight Clip1 and right mouse the item to bring up available options and select \textit{Open EDL}.
\item Now you will see the timeline change from the original media to just the clip content and the \# in the
upper right hand corner will change from 0 to 1.
\item Add a visible effect, like AgingTV to the timeline.
\item Drag the clip from the Resources Clip folder to the timeline and you will see the AgingTV effect.
\end{enumerate}
-You can follow the same steps as above by first using the option "Nest to media" in the Clip folder which nests the clip and moves it out of the Clip folder to the Media folder. Then use "Open EDL" on the Nested EDL in the media folder. When you Open EDL and edit the changes, those changes will take affect on any and all occurrences of that nested clip on the current and/or original timeline. The option to unnest that clip and put that back into the Clip folder is the option "EDL to clip". The nested clip is still in the Media folder. It will now have a name of the next available Clip \# but the comment contains the previous name so you can tell where it came from.
+You can follow the same steps as above by first using the option \textit{Nest to media} in the Clip folder which nests the clip and moves it out of the Clip folder to the Media folder. Then use \textit{Open EDL} on the Nested EDL in the media folder. When you Open EDL and edit the changes, those changes will take affect on any and all occurrences of that nested clip on the current and/or original timeline. The option to unnest that clip and put that back into the Clip folder is the option \textit{EDL to clip}. The nested clip is still in the Media folder. It will now have a name of the next available Clip \# but the comment contains the previous name so you can tell where it came from.
-Instead of using the \# number on the main menu to close the current EDL, both the Media and Clip folders have "Close EDL" options with the left mouse button. Clicking on the \# number is quick and easy but for infrequent usage it is not obvious, whereas if you use "Open EDL" you see "Close EDL" right below that and so it is very obvious. In addition in the case of where you have opened a EDL, and you no longer see that clip in the folder, the right mouse button where no media is highlighted will also display the Close EDL option.
+Instead of using the \# number on the main menu to close the current EDL, both the Media and Clip folders have \textit{Close EDL} options with the left mouse button. Clicking on the \# number is quick and easy but for infrequent usage it is not obvious, whereas if you use \textit{Open EDL} you see \textit{Close EDL} right below that and so it is very obvious. In addition in the case of where you have opened a EDL, and you no longer see that clip in the folder, the right mouse button where no media is highlighted will also display the Close EDL option.
\pagebreak
\begin{figure}[h]
\end{figure}
\relax
-In addition to the "Open EDL" option in the Resources menu, this option is available on the timeline when the cursor is on an EDL-type edit.
-To get to this option, click on the middle mouse button on that edit. If it is not EDL, the option will not be shown. In summary:
+In addition to the \textit{Open EDL} option in the Resources menu, this option is available on the timeline when the cursor is on an EDL-type edit. To get to this option, click on the middle mouse button on that edit. If it is not EDL, the option will not be shown. In summary:
\begin{center}
\small
\end{tabular}
\end{center}
-An aside - when nesting and unnesting clips to take advantage of this feature, names of the media can lead to some confusion. For example, if you nest a clip, the new name in the Media folder is the word "Nested" followed by an underscore with the date and timestamp, another underscore, and then the clip name. Then when you unnest this Media folder clip via the "EDL to clip" option, the name will be changed in the Clip folder to the next available Clip \#. However the comment field will reflect the nested clip name from which it was derived. To avoid confusion you can easily change the name for these clips in either the Clip or Media folder because they are not real files at this point. To do so, highlight the clip name in Resources, click on Info and type in a new name.
+An aside -- when nesting and unnesting clips to take advantage of this feature, names of the media can lead to some confusion. For example, if you nest a clip, the new name in the Media folder is the word \textit{Nested} followed by an underscore with the date and timestamp, another underscore, and then the clip name. Then when you unnest this Media folder clip via the \textit{EDL to clip} option, the name will be changed in the Clip folder to the next available Clip \#. However the comment field will reflect the nested clip name from which it was derived. To avoid confusion you can easily change the name for these clips in either the Clip or Media folder because they are not real files at this point. To do so, highlight the clip name in Resources, click on Info and type in a new name.
-For additional safety, the "Open EDL" feature includes additional backup capabilities. Automatically Cinelerra saves a backup when certain changes are made or you can always use the shortcut "b" to do one yourself, although keep in mind it will be overwritten whenever Cinelerra wants to do another backup. Now there is a shortcut for the backup shortcut "b" so you can keep your hand on the mouse instead of the keyboard. Just click on the \# in the upper right hand corner of the main window. If \# is at 0, it backs up to backup.xml, if at 1, it backs up to backup1.xml and so on ... up to backup9.xml.
+For additional safety, the \textit{Open EDL} feature includes additional backup capabilities. Automatically Cinelerra saves a backup when certain changes are made or you can always use the shortcut "b" to do one yourself, although keep in mind it will be overwritten whenever Cinelerra wants to do another backup. Now there is a shortcut for the backup shortcut "b" so you can keep your hand on the mouse instead of the keyboard. Just click on the \# in the upper right hand corner of the main window. If \# is at 0, it backs up to backup.xml, if at 1, it backs up to \texttt{backup1.xml} and so on $\dots$ up to \texttt{backup9.xml}.
-When "Open EDL" is invoked, the current EDL and current undo stack are both "pushed", and the active session EDL is replaced with the target clip/nested edl. A new undo stack is created, and the active backup.xml file name is decorated with the stack level. So, backup.xml is backup1.xml when your edits are at stack level 1, backup2.xml at stack level 2, and so on. This means that if you "load backup" at stack level 1, the session will reload from history at stack level 1, not the main session.
+When \textit{Open EDL} is invoked, the current EDL and current undo stack are both \textit{pushed}, and the active session EDL is replaced with the target clip/nested edl. A new undo stack is created, and the active \texttt{backup.xml} file name is decorated with the stack level. So, \texttt{backup.xml} is \texttt{backup1.xml} when your edits are at stack level 1, \texttt{backup2.xml} at stack level 2, and so on. This means that if you \textit{load backup} at stack level 1, the session will reload from history at stack level 1, not the main session.
\begin{comment}
\begin{figure}[htpb]
\subsection{Edit Length}%
\label{sub:edit-lenght}
-To set the length of an edit in the timeline, select the region which contains the edit to be modified. Now select the menu bar Edit $\rightarrow$ Edit Length\dots menu item to activate the \textit{edit length} popup (figure~\ref{fig:lenght}). The duration of the edit can be reset by entering the desired edit length in seconds. Pressing OK will change all of the selected edits (in armed tracks) to the specified length.
+To set the length of an edit in the timeline, select the region which contains the edit to be modified. Now select the menu bar \texttt{Edit $\rightarrow$ Edit Length}\dots menu item to activate the \textit{edit length} popup (figure~\ref{fig:lenght}). The duration of the edit can be reset by entering the desired edit length in seconds. Pressing OK will change all of the selected edits (in armed tracks) to the specified length.
\begin{figure}[htpb]
\centering
\includegraphics[width=0.6\linewidth]{images/lenght.png}
\label{sub:align_edits}
When loading media, a common problem is that the various audio/video tracks do not always have exactly the same lengths. For example, you might load audio/video recordings from your camera and be dismayed to see that the audio for each segment is a half second longer than the video. If you load a large set of media clips by concatenation, the audio and video will be more skewed as more media is loaded. Align Edits makes it possible to adjust the edits so the audio and/or video align by adjusting
-the edits so that the track lengths are consistent. To use this feature, load all of the desired media and select a region which contains all of the edits to be aligned in the timeline. Now select the menu bar Edit $\rightarrow$ Align Edits menu item to operate the change. The topmost armed track is used as a template reference, and the rest of the tracks are either cut or padded to align the edit boundaries. Besides aligning audio with the video, you can also align video with the audio if the first armed track is audio. \\
+the edits so that the track lengths are consistent. To use this feature, load all of the desired media and select a region which contains all of the edits to be aligned in the timeline. Now select the menu bar \texttt{Edit $\rightarrow$ Align Edits} menu item to operate the change. The topmost armed track is used as a template reference, and the rest of the tracks are either cut or padded to align the edit boundaries. Besides aligning audio with the video, you can also align video with the audio if the first armed track is audio. \\
The code performs the following algorithm:
\begin{itemize}
\item Use the first armed track as the master track (it must contain data).
The start time sequence of media and silence edits along the master track are collected as the target
alignment boundaries. All armed tracks after the master track are modified so that if the next edit edge
is too soon, it adds silence; if it is too late, edits are shortened or deleted past the point of the next target
-alignment boundary time. Align Edits works best if there are an equal number of Video and Audio sections. Also, it is better to use cuts instead of adding silence ---if there are silence edits together, the algorithm will combine the silence edits into a single edit and results may not be as desired.
+alignment boundary time. Align Edits works best if there are an equal number of Video and Audio sections. Also, it is better to use cuts instead of adding silence -- if there are silence edits together, the algorithm will combine the silence edits into a single edit and results may not be as desired.
The first two screenshots in figure~\ref{fig:align} show the Before, the Highlighted Edits to be manipulated, and the After results for the Align Edits. The third screenshot \textit{adds silence} in the second section as noted in red letters.
\begin{figure}[htpb]
\subsection{Reverse Edits}%
\label{sub:reverse_edits}
-The Reverse Edits can be useful to change the order of 2 edits in the case where you would like to put a \textit{teaser} section that occurred in the middle of a movie at the beginning instead, that is, reversed positions. To operate, highlight completely the edit areas you would like reversed and then use the pulldown Edit $\rightarrow$ Reverse Edits.
+The Reverse Edits can be useful to change the order of 2 edits in the case where you would like to put a \textit{teaser} section that occurred in the middle of a movie at the beginning instead, that is, reversed positions. To operate, highlight completely the edit areas you would like reversed and then use the pulldown \texttt{Edit $\rightarrow$ Reverse Edits}.
Figure~\ref{fig:reverse01} shows the selected / highlighted area to which Edits will be applied. Note the first edit is 00002, followed by 00003, 00004, and 00005 in that order.
\begin{figure}[htpb]
\subsection{Shuffle Edits}%
\label{sub:shuffle_edits}
-The file pulldown Edit $\rightarrow$ Shuffle Edits will randomly exchange the location of the edits. This feature can be used to change the order of the music like you would do from your MP4 player where you have a playlist of your favorite music. Or perhaps you are creating an advertisement background, you can randomly change it, thus the viewer sees a different order of scenes each time shown.
+The file pulldown \texttt{Edit $\rightarrow$ Shuffle Edits} will randomly exchange the location of the edits. This feature can be used to change the order of the music like you would do from your MP4 player where you have a playlist of your favorite music. Or perhaps you are creating an advertisement background, you can randomly change it, thus the viewer sees a different order of scenes each time shown.
Figure~\ref{fig:shuffle} illustrating Shuffle Edits of the highlighted area of the first screenshot on the page. Note the permutation of the fragments resulting in 00003 now being first, then 00005, 00002, and 00004 last.
\begin{figure}[htpb]
For all file formats, other than still images, the extent of the trimming operation is limited to the source file length. Attempting to drag the start of the edit beyond the start of the source, limits it to the source start. In all trimming operations, all edits which start on the same position as the cursor when the drag operation begins are affected. You have to disarm tracks in order to prevent edits from being affected.
-You have 6 different choices of which mouse button to use for specific types of editing while using the drag handle. You change the drag handle mouse effects by using the Settings $\rightarrow$ Preferences $\rightarrow$ Interface tab and modifying the Editing section as shown in the next figure~\ref{fig:trim}. The drag handle affects not only the clip you are working on but also frequently the entire duration of all clips on the timeline.\\
+You have 6 different choices of which mouse button to use for specific types of editing while using the drag handle. You change the drag handle mouse effects by using the \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface} tab and modifying the Editing section as shown in the next figure~\ref{fig:trim}. The drag handle affects not only the clip you are working on but also frequently the entire duration of all clips on the timeline.\\
\begin{figure}[htpb]
\centering
\includegraphics[width=0.6\linewidth]{images/trim.png}
\bottomrule
\end{longtable}
-Next, a more immediate and colorful view shows these trimming options ((figure~\ref{fig:trim-color})).
+Next, a more immediate and colorful view shows these trimming options (figure~\ref{fig:trim-color}).
\begin{figure}[htpb]
\centering
The Trim Feature using the drag handle provides some good ways to view your video while editing. The playback position in the compositor is updated live and the view in the compositor can be split so that in the left half of the compositor you can see the last frame of the left clip and in the right half the first frame of the right clip. Dragging edits can not be extended past the beginning or the end.
-First familiarize yourself with button operation; check your setup by executing the following step. In the Settings $\rightarrow$ Preferences $\rightarrow$ Interface tab, Editing section, clicking on the edit boundaries can be set for Button 1, 2, 3 as one of the following:
+First familiarize yourself with button operation; check your setup by executing the following step. In the \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface} tab, Editing section, clicking on the edit boundaries can be set for Button 1, 2, 3 as one of the following:
\textit{Ripple}; \textit{Roll}; \textit{Slip}; \textit{Slide}; \textit{Edge} or \textit{No effect}
\centering
\includegraphics[width=0.7\linewidth]{images/snap.png}
\end{wrapfigure}
-They look like tags and the letter E on the menu bar and are oriented forward/backward. These same buttons can be used to \textit{cut} from the insert pointer to the previous or next edit/label when the \texttt{ctrl+alt} keys are both pressed when the buttons are used. They \textit{snap} off the media instead of doing the standard re-positioning. This is useful to minimize the number of operations necessary to cut between edits/labels.
+They look like tags and the letter E on the menu bar and are oriented forward/backward. These same buttons can be used to \textit{cut} from the insert pointer to the previous or next edit/label when the ctrl+alt keys are both pressed when the buttons are used. They \textit{snap} off the media instead of doing the standard re-positioning. This is useful to minimize the number of operations necessary to cut between edits/labels.
Instead of using the edit panel buttons, you can more easily use the following keyboard shortcuts to perform the same functions:
\begin{center}
\end{tabular}
\end{center}
-\paragraph{Drag Snapping} if you hold down the \texttt{Ctrl + Alt} keys while dragging using the mouse, once the clip gets near to an edit, a label, an in/out pointer or the start/end of the timeline, the dragged clip will snap next to that marker. The 2 will now be exactly aligned with no gap and no overlap. As you drag the clip close to one of the markers, when they are within a short distance they start to stick and stay that way until you move further away from that distance. Also, the line will turn color from green to yellow while in the sticky phase.
+\paragraph{Drag Snapping} if you hold down the Ctrl + Alt keys while dragging using the mouse, once the clip gets near to an edit, a label, an in/out pointer or the start/end of the timeline, the dragged clip will snap next to that marker. The 2 will now be exactly aligned with no gap and no overlap. As you drag the clip close to one of the markers, when they are within a short distance they start to stick and stay that way until you move further away from that distance. Also, the line will turn color from green to yellow while in the sticky phase.
\subsection{Nesting}%
\label{sub:nesting}
\paragraph{Nested Assets} A nested asset is an EDL session that embeds an existing EDL session, all tracks, all plugins, editing, and effects into a media object that appears as one audio/video media object, no plugins, editing, or effects. It is as if the existing EDL was rendered, and loaded in its place. This has several interesting side effects. First, you don’t have to render the entire media file to see any portion. Second, it requires no rendering compute time or storage. Third, it changes the precedence of the composer so that you get more control over the projection and automation, so that the results can be sent into another rendering step, not simply part of the current stack. It groups the plugin stack in much the same way that an arithmetic expression is grouped by parenthesis.
-The EDL session and the rendered output are visually equivalent. Nested assets allow for complex grouping and stacking of effects, and makes media access much more flexible. This feature can be used recursively, that is, any number of sessions may be stacked and referenced as an asset, as long as all of the rendering resources are available. Nested assets are added to the timeline by using the pulldown File $\rightarrow$ Load files\dots on the main menu and selecting the \textit{Insertion strategy} of \textit{Nest asset}. The file will be pasted into the timeline over the current selection or at the insertion point.
+The EDL session and the rendered output are visually equivalent. Nested assets allow for complex grouping and stacking of effects, and makes media access much more flexible. This feature can be used recursively, that is, any number of sessions may be stacked and referenced as an asset, as long as all of the rendering resources are available. Nested assets are added to the timeline by using the pulldown \texttt{File $\rightarrow$ Load files}\dots on the main menu and selecting the \textit{Insertion strategy} of \textit{Nest asset}. The file will be pasted into the timeline over the current selection or at the insertion point.
It is somewhat important to note that nested assets and nested clips will have index files automatically created. These index files can start to clutter up your \texttt{\$HOME/.bcast5} directory with files named \texttt{Nested\_\#\#\#.idx} and you may want to periodically delete any index files which are no longer in use.
Nested clips can be proxied and when they are, the resulting files
are placed in the user's \$HOME/Videos directory by default. This can be modified by changing
-Settings $\rightarrow$ Preferences $\rightarrow$ Interface tab, Nested Proxy Path.
+\texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface} tab, Nested Proxy Path.
\begin{figure}[htpb]
\centering
\includegraphics[width=0.9\linewidth]{images/nesting.png}
\item[Example 1:] You want to make a flashback/rewind at the end of your video
that represents a quick summary of the entire video in black and white. On
he timeline, you have 60 seconds of edits with clips, cuts, zoom in, zoom
-out and any other edits. Now you want to get this 60 seconds "compressed"
+out and any other edits. Now you want to get this 60 seconds \textit{compressed}
to 10 seconds, play in reverse, and in black and white at the end of your
video.
You would copy the 60 seconds in a clip, nest the clip in the Clip folder
\item use the Paste icon (shortcut v) to paste the clip to that other instance selection target
\end{enumerate}
-\section[ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing]{ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing\protect\footnote{credit Eric Messick --- \url{FixedImagePhoto.com/contact}}}%
+\section[ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing]{ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing\protect\footnote{credit Eric Messick}}%
\label{sec:shuttle_jog_wheels_editing}
The ShuttlePROv2 and ShuttleXpress are affordable jog wheels which can be useful for working with Cin, especially if you do a lot of playing forward/backward, fast/slow/normal, and single frames (figure~\ref{fig:shuttle}).
-Directions for using the ShuttlePROv2 and the ShuttleXpress with Cinelerra are described next. These devices work by sending keystrokes used in Cin, corresponding to the shuttle action, to the keyboard buffer. The shuttle has been fully integrated into the Cinelerra code so that after the one initial setup, no further intervention is required. The multi-speed outer wheel works the same and has the same number of S positions on both shuttles but the shuttle Xpress has only 5 keys. Since the majority of user operations will most likely be with the use of the 2 wheels, the slightly smaller Xpress could be a better choice with its 5 easy to reach keys. The Pro is approximately $4x7$\,inches whereas the Xpress is about $4x4$\,inches.
+Directions for using the ShuttlePROv2 and the ShuttleXpress with Cinelerra are described next. These devices work by sending keystrokes used in Cin, corresponding to the shuttle action, to the keyboard buffer. The shuttle has been fully integrated into the Cinelerra code so that after the one initial setup, no further intervention is required. The multi-speed outer wheel works the same and has the same number of S positions on both shuttles but the shuttle Xpress has only 5 keys. Since the majority of user operations will most likely be with the use of the 2 wheels, the slightly smaller Xpress could be a better choice with its 5 easy to reach keys. The Pro is approximately $4\times7$\,inches whereas the Xpress is about $4\times4$\,inches.
\begin{figure}[htpb]
\centering
\subsection{How to Modify the Default Key Settings}%
\label{sub:modify_default_key_settings}
-Detailed information on how to modify your local .shuttlerc file is described next, but if you need help you can request more information in the forum at \url{https://cinelerra-gg.org}. In the \texttt{shuttlerc} file, a \# always represents a comment and blank lines are ignored. The first thing you must do is copy the system supplied \texttt{shuttlerc} file to your \texttt{\$HOME} directory and rename it as \texttt{.shuttlerc} (with a period).
+Detailed information on how to modify your local .shuttlerc file is described next, but if you need help you can request more information in the forum at {\small \url{https://cinelerra-gg.org}}. In the \texttt{shuttlerc} file, a \# always represents a comment and blank lines are ignored. The first thing you must do is copy the system supplied \texttt{shuttlerc} file to your \texttt{\$HOME} directory and rename it as \texttt{.shuttlerc} (with a period).
The \texttt{shuttlerc} file has sections that in the case of Cinelerra, represent different windows allowing you to set the keys, K1-K15 for the Pro and K5-K9 for the Xpress, the shuttle wheel positions of S0/S1/S-1 for stop, S2 through S7 for wheeling to the right, and S-7 through S-2 for wheeling to the left for reverse. Then there is JR to jog right (clockwise) and JL to jog left (counter-clockwise) for the inner smaller wheel for single frame movement. See the key arrangement on a later page for location of the keys for each of the two different shuttles.
...
\end{lstlisting}
-\noindent An explanation for the above REV and FWD key symbol values is necessary to facilitate user preferences. Obviously REV stands for reverse and FWD for forward. You can set any speed up to and including 64x (that is, 64 times the normal speed) on any of the S keys. First in the line is the key name such as S-3 and then the key direction of FWD or REV followed by the symbol for underscore (\_) and then the numerical value to use. For example, if you want the 5\textsuperscript{th} forward position, S5, to play 10$ \frac{1}{2}$ times faster, you would use the statement \texttt{S5 FWD\_10.5}. Integer or decimal numbers are legal.
+\noindent An explanation for the above REV and FWD key symbol values is necessary to facilitate user preferences. Obviously REV stands for reverse and FWD for forward. You can set any speed up to and including 64x (that is, 64 times the normal speed) on any of the S keys. First in the line is the key name such as S-3 and then the key direction of FWD or REV followed by the symbol for underscore (\_) and then the numerical value to use. For example, if you want the $5^{th}$ forward position, S5, to play 10$\frac{1}{2}$ times faster, you would use the statement \texttt{S5 FWD\_10.5}. Integer or decimal numbers are legal.
For the Viewer, you may want keys defined to do a Splice or an Overwrite so define differently. Note that assignments that contain single character letters must be enclosed in quotes.
\section{FFmpeg Early Probe Explanation}%
\label{sec:ffmpeg_early_probe_explanation}
-When you open media, a series of libraries and codec functions are used to \textit{probe} the data, to see if it can determine the type of file format and codec parameters needed to correctly decode the file. If ffmpeg probes early --- \texttt{Try FFMpeg first} is in effect for the FF button --- it will usually find some way to try to decode just about any contemporary media file. But there are some times that the built in codecs are actually a better choice. A lot of this may fall into the category of personal preference. For example, some may prefer the mpeg library in the Cinelerra code over the ffmpeg code because it has more decoding capability and seems to be more robust when the media is damaged. In that case you will want the FF button to read \texttt{Try FFMpeg last}.
+When you open media, a series of libraries and codec functions are used to \textit{probe} the data, to see if it can determine the type of file format and codec parameters needed to correctly decode the file. If ffmpeg probes early -- \textit{Try FFMpeg first} is in effect for the FF button -- it will usually find some way to try to decode just about any contemporary media file. But there are some times that the built in codecs are actually a better choice. A lot of this may fall into the category of personal preference. For example, some may prefer the mpeg library in the Cinelerra code over the ffmpeg code because it has more decoding capability and seems to be more robust when the media is damaged. In that case you will want the FF button to read \textit{Try FFMpeg last}.
To summarize, if ffmpeg probes early, you will never get to use the built in libraries, and if you want to skip over buggy old libraries, use ffmpeg early probe enabled so that the newest code will be tried first.
The FF button is located in the upper right hand corner of the main window.
the icon is on, that is, ffmpeg probes first. Suggestion is to leave it on except in a few special
cases where it may be better to have early probes disabled. When you mouse over the main menu FF
toggle button, the text displays ffmpeg's \textit{Currently} set position. Just left mouse click to change to the other setting.
-The ffmpeg early probe state is saved between sessions and is also affected by choices made in Probe Order (refer to section 4 - Probe Order when Loading Media). It is important to note that the various file indexes may need to be rebuilt if you change which codec is being used to decode the file. There is a warning popup to remind you when you change the default ffmpeg early probe state (unless you have checked the box to no longer show the warning). You can easily rebuild the index for a specific media file by going to the Resources window, right mouse click on that media, and choose \texttt{Rebuild Index} from the popup choices.
+The ffmpeg early probe state is saved between sessions and is also affected by choices made in Probe Order (refer to section \ref{sub:probe_order_loading_media}). It is important to note that the various file indexes may need to be rebuilt if you change which codec is being used to decode the file. There is a warning popup to remind you when you change the default ffmpeg early probe state (unless you have checked the box to no longer show the warning). You can easily rebuild the index for a specific media file by going to the Resources window, right mouse click on that media, and choose \texttt{Rebuild Index} from the popup choices.
Figure~\ref{fig:ff} shows (1) reddish colored FF in upper right hand corner of main window indicating
that ffmpeg early probes is enabled; (2) \textit{Try FFMpeg last} indicator message for ffmpeg early probes enabled (note that the color is different because you highlighted the icon); and (3) black colored FF indicates ffmpeg will be used last and you are changing the behavior so that Cinelerra warns you accordingly.
This section describes how the FFmpeg options files work for decoding and encoding and goes into great detail. It will make more sense if you look at Cinelerra's ffmpeg config directory and the Cinelerra menus at the same time.
It is meant to include everything necessary for complete understanding. You will be able to personalize your own options files without knowing all of the information included below if you know the basics. The word encoding is used interchangeably with the word rendering.
-The possible combinations for ffmpeg options files are literally combinatorial --- that is a lot (factorial!). The allowed media file format / codec choices are much more flexible than you might realize. When the ffmpeg design was initially added, some parameter files which describe the choices which the program uses had to be created. There are way too many to enumerate in the deliverable Cinelerra package. Some quite detailed information for how ffmpeg options work is given here and hopefully, enough basics for simple understanding. It may all seem complicated at first, but will become obvious.
+The possible combinations for ffmpeg options files are literally combinatorial -- that is a lot (factorial!). The allowed media file format / codec choices are much more flexible than you might realize. When the ffmpeg design was initially added, some parameter files which describe the choices which the program uses had to be created. There are way too many to enumerate in the deliverable Cinelerra package. Some quite detailed information for how ffmpeg options work is given here and hopefully, enough basics for simple understanding. It may all seem complicated at first, but will become obvious.
\subsection{File naming convention}%
\label{sub:file_naming_convention}
-In Cinelerra's ffmpeg configuration directory you will see files as listed and described below. File type and extension names are the key for Cinelerra's use of ffmpeg. Basically the \texttt{.opts} file extension represents options; \texttt{.dfl} represents defaults; and all the rest are media types. For example one media type is quicktime so that \texttt{*.qt} file names would be the \textit{quicktime} choices. In the file names below, \texttt{ext} refers to a set of files with file names matching the \texttt{*.ext} file extension. And \texttt{typ} refers to a type of format / codec combination used, that is, the media type.
+In Cinelerra's ffmpeg configuration directory you will see files as listed and described below. File type and extension names are the key for Cinelerra's use of ffmpeg. Basically the \texttt{.opts} file extension represents options; \texttt{.dfl} represents defaults; and all the rest are media types. For example one media type is quicktime so that \texttt{*.qt} file names would be the \textit{quicktime} choices. In the file names below, \textit{ext} refers to a set of files with file names matching the \texttt{*.ext} file extension. And \textit{typ} refers to a type of format / codec combination used, that is, the media type.
In the ffmpeg configuration directory there are a series of options files used when encoding or decoding audio or video. They are read in the order from top to bottom and only the files needed for the current operation are added to the active configuration.
\end{tabular}
\end{center}
-\paragraph{Decoder options:} Normally, only \texttt{ffmpeg.opts} and \texttt{decode.opts} are used when reading/decoding files, but may be specialized if a \texttt{<path>/media.opts} exists for a given \texttt{<path>/media.ext} file. For example, if you want to only fail on fatal errors and to always use the video filter, edgedetect, when working with your media file \texttt{dreaming.y4m}, then create a file \texttt{dreaming.opts} in the same directory with the contents of \texttt{loglevel=fatal} on the first line and \texttt{video\_filter=edgedetect} on the next. These specialized settings will override the defaults. The fatal loglevel is especially handy for lesser quality media.
+\paragraph{Decoder options:} Normally, only \texttt{ffmpeg.opts} and \texttt{decode.opts} are used when reading/decoding files, but may be specialized if a \texttt{<path>/media.opts} exists for a given \texttt{<path>/media.ext} file. For example, if you want to only fail on fatal errors and to always use the video filter, edgedetect, when working with your media file \texttt{dreaming.y4m}, then create a file \texttt{dreaming.opts} in the same directory with the contents of \textit{loglevel=fatal} on the first line and \textit{video\_filter=edgedetect} on the next. These specialized settings will override the defaults. The fatal loglevel is especially handy for lesser quality media.
\paragraph{Encoder Options:} Within the audio/video subdirectories of the first level ffmpeg directory, the \texttt{typ.ext} files are for encoder (rendering) setups.
(or) id2 = value2
\end{lstlisting}
-Only one equals sign is allowed and it is just for readability. There may be any number of id / value pair lines in a media definition, including zero. A typical line might be:
+Only one equals sign is allowed and it is just for readability. There may be any number of id/value pair lines in a media definition, including zero. A typical line might be:
\begin{lstlisting}[language=bash,numbers=none]]
bitrate 4000000
All other id's should be in the ffmpeg documentation, and correspond to the global, muxer, and codec option names and values used by ffmpeg. For example to set the aspect ratio to 4:3, use:
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
aspect 4:3
\end{lstlisting}
Below shows an example: \texttt{decode.opts} which is used when the ffmpeg decoder is initialized.
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
# apply at init decode
loglevel=fatal
formatprobesize=5000000
The encoder options you see in the Cinelerra menus depend on the files in these directories, \textsc{NOT THE CODE}. If you add files, you will get to use more variety.
-In the \textit{cinelerra} directory, which contains the ffmpeg configuration folder, there are the choices the program uses. When you open an ffmpeg format popup dialog, the listbox contains all of the codec types which are identified by the file.ext extensions. Decoding has only a few options, since the ffmpeg file probes determine most of the options by looking at the media being opened, but encoding media requires a lot of setup. Below are some of the folders and files used to determine the configurations used by ffmpeg to decode and encode files.
+In the \textit{cinelerra} directory, which contains the ffmpeg configuration folder, there are the choices the program uses. When you open an ffmpeg format popup dialog, the listbox contains all of the codec types which are identified by the \texttt{file.ext} extensions. Decoding has only a few options, since the ffmpeg file probes determine most of the options by looking at the media being opened, but encoding media requires a lot of setup. Below are some of the folders and files used to determine the configurations used by ffmpeg to decode and encode files.
These extensions create audio / video media classes:
Now you will see this as what you can choose in the rendering choices for ffmpeg.
Inside the file you will see that the first line is special. It is the muxer and codec. For example:
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
h264 libx265
\end{lstlisting}
The contents may be something like:
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
# <path>/video/vid.mov
mp4 libx265
bitrate 4000000
\end{lstlisting}
-This will code an \texttt{mp4} formatted file using the \texttt{lib264} codec encoder.
+This will code an mp4 formatted file using the \textit{lib264} codec encoder.
For audio and video together, the mux format must agree between the aud.mov and vid.mov files when they are to be used together. The stream muxer must be the same for all the streams in the file being written.
-for example:
+For example:
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
# <path>/audio/aud.mov
mp4 pcm_mulaw
\end{lstlisting}
-This will create \textit{mp4} media using audio format \texttt{pcm\_mulaw} coding.
+This will create mp4 media using audio format \textit{pcm\_mulaw} coding.
-Both the audio and the video are using \textit{mp4} mux format, and so there will be 2 streams:
+Both the audio and the video are using mp4 mux format, and so there will be 2 streams:
\begin{enumerate}
\item x265 video
\item pcm\_mulaw audio
\texttt{audio/<class>.dfl} and \texttt{video/<class>.dfl}
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
# audio/mov.dft
aud.mov
\end{lstlisting}
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
# video/mov.dft =
vid.mov
\end{lstlisting}
When you see problems in using the new options files you have created and put into place, add the following line to \texttt{ffmpeg/encoder.opts}:
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
loglevel=verbose
\end{lstlisting}
sometimes that will be enough to see what has caused a failure, or even catch unexpected results.
-There is an \textsc{EXCEPTION} to all of the above because of a conflict between ffmpeg and the x264 person making the detection of default ffmpeg settings terminate with an error. If you get this error, you must workaround this termination by including parameters that don't match $5$ or more of the normal expected values. So you just have to change a few parameters to avoid the probe detection. Here is an example where you will notice the \texttt{x264-params} line tweaking values to throw off the detection/error termination code.
+There is an \textsc{EXCEPTION} to all of the above because of a conflict between ffmpeg and the x264 person making the detection of default ffmpeg settings terminate with an error. If you get this error, you must workaround this termination by including parameters that don't match $5$ or more of the normal expected values. So you just have to change a few parameters to avoid the probe detection. Here is an example where you will notice the \textit{x264-params} line tweaking values to throw off the detection/error termination code.
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
# <path>/ffmpegvideo/test.mp4
mp4 libx264
preset=slow
This is quite complicated, but that is because ffmpeg has a lot of parameters and history. Good results are not that hard to create. Initially you should mostly use the defaults.
If you send any new options files to \href{mailto:cin@lists.cinelerra-gg.org}{cin@lists.cinelerra-gg.org}, it will be given consideration to being added to the baseline for future deliverables.
-To get a listing of the current ffmpeg supported formats and codecs that can be made to work with Cinelerra, provided there are option files added, run the following commands. This should be done from the <build>directory substituting the location of <build> where you have installed Cinelerra on your system and the ffmpeg may be a different version than $4.2$ as used below. Then look at the output created in \texttt{/tmp/ff-formats.txt} and \texttt{codecs.txt}.
+To get a listing of the current ffmpeg supported formats and codecs that can be made to work with Cinelerra, provided there are option files added, run the following commands. This should be done from the \texttt{<build>} directory substituting the location of \texttt{<build>} where you have installed Cinelerra on your system and the ffmpeg may be a different version than $4.2$ as used below. Then look at the output created in \texttt{/tmp/ff-formats.txt} and \texttt{codecs.txt}.
\begin{lstlisting}[language=bash,numbers=none]]
/<build>/cinelerra-5.1/thirdparty/ffmpeg-4.2/ffmpeg -formats > /tmp/ff-formats.txt
\begin{enumerate}
\item load media
- \item use settings$\rightarrow$format to set the frame rate, sample rate/channels, aspect ratio,
+ \item use \texttt{settings $\rightarrow$ format} to set the frame rate, sample rate/channels, aspect ratio,
color model = rgb\_float or rgba\_float if blending
- \item press \texttt{Shift-R} and select FFmpeg format type \texttt{pro}
+ \item press Shift-R and select FFmpeg format type \textit{pro}
\item select target path
- \item check \texttt{OK}, and watch for messages in the terminal window
+ \item check OK, and watch for messages in the terminal window
\end{enumerate}
\subsection{Viewing \& Modifying FFmpeg Format Options inside Cinelerra}%
\label{sub:viewing_modifying_ffmpeg_cinelerra}
-There are thousands of options for using ffmpeg. Now it is possible to \textit{view} the available options for a particular video and audio choice by using the \textit{wrench icon} and then clicking on the \textit{view} box. FFmpeg has to be the selected file format for this feature to be visible. It makes it a lot easier since only the applicable options show up as opposed to everything that ffmpeg can do. These options are just \textit{Hints} and some may be missing due to the way that ffmpeg options are coded --- Cinelerra shows the option data ffmpeg has exposed.
+There are thousands of options for using ffmpeg. Now it is possible to \textit{view} the available options for a particular video and audio choice by using the \textit{wrench icon} and then clicking on the \textit{view} box. FFmpeg has to be the selected file format for this feature to be visible. It makes it a lot easier since only the applicable options show up as opposed to everything that ffmpeg can do. These options are just \textit{Hints} and some may be missing due to the way that ffmpeg options are coded -- Cinelerra shows the option data ffmpeg has exposed.
-As an example, instead of reading the entire 264 library information, you only have to look at the shown available options. Both the video and the audio are browsable. The options visible in the \textit{Audio/Video Preset} textbox are the final values which are used when rendering once you have checked \texttt{OK}. For assistance in choosing the options you want, use the view popup to see the objects that go with the selected format tool, highlight the option, modify the parameter value in the box at the top of the \textit{Options} window based on what you want, and then click apply. Updated parameter values or new parameters will be appended at the bottom. Note that when you highlight an option, a tooltip will show up when available in the lower right hand corner which describes the option. Also note that the Format and Codec types are shown on the top line of the Options window.
+As an example, instead of reading the entire 264 library information, you only have to look at the shown available options. Both the video and the audio are browsable. The options visible in the \textit{Audio/Video Preset} textbox are the final values which are used when rendering once you have checked OK. For assistance in choosing the options you want, use the view popup to see the objects that go with the selected format tool, highlight the option, modify the parameter value in the box at the top of the \textit{Options} window based on what you want, and then click apply. Updated parameter values or new parameters will be appended at the bottom. Note that when you highlight an option, a tooltip will show up when available in the lower right hand corner which describes the option. Also note that the Format and Codec types are shown on the top line of the Options window.
-Parameters exist in 3 layers: ffmpeg, codec, and an interface layer. You can apply parameters to each layer. The top 2 layers are accessed with the Kind popup menu. The ffmpeg layer is topmost, and is selected as Kind: ffmpeg. It can specify many of the more common parameters, such as the bitrate, quality, and so on. The middle layer is selected as Kind: codec. These options can specialize your choices, and frequently includes presets and profiles useful for coding well known parameter sets, like \texttt{profile=high422}, \texttt{preset=medium}, or \texttt{tune=film}, etc. The interface layer may or may not be available. It is usually accessible only by an \textit{opts} parameter, like \texttt{x264-params key=value:key=value:\dots} These options are passed directly to the low level codec library.
+Parameters exist in 3 layers: ffmpeg, codec, and an interface layer. You can apply parameters to each layer. The top 2 layers are accessed with the Kind popup menu. The ffmpeg layer is topmost, and is selected as Kind: ffmpeg. It can specify many of the more common parameters, such as the bitrate, quality, and so on. The middle layer is selected as Kind: codec. These options can specialize your choices, and frequently includes presets and profiles useful for coding well known parameter sets, like \textit{profile=high422}, \textit{preset=medium}, or \textit{tune=film}, etc. The interface layer may or may not be available. It is usually accessible only by an \textit{opts} parameter, like \texttt{x264-params key=value:key=value}:\dots These options are passed directly to the low level codec library.
Figure~\ref{fig:video-preset} shows \textit{ffmpeg} video as the Kind. Note the x264opts (should actually be x264-params now) in the Video Preset window immediately below.
Another feature gained from using ffmpeg in Cinelerra takes advantage of what is being referred to as the \textit{\%d trick}. This trick uses the ffmpeg muxer image2 and a filename template to create a series of image files of a given type. A specific example is described below.
-To encode a series of $48$ bit tiff output image files, add a file to the cinelerra data ffmpeg/video subdirectory as in:
+To encode a series of $48$\,bit tiff output image files, add a file to the cinelerra data ffmpeg/video subdirectory as in:
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
# \dots/ffmpeg/video/tiff.dfl
tiff48.tif
\end{lstlisting}
Then create an ffmpeg video encoder parameters file in the same directory:
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
# \dots/ffmpeg/video/tiff48.tiff
image2 tiff
pixel_format=rgb48
\end{lstlisting}
-This will define a new ffmpeg encoder format which is a video image file format that uses the tiff codec for encoding, and a pixel\_format of \texttt{rgb48} (or a similar equivalent such as rgb48le). Next load up your project and set up for a Render using File$\rightarrow$Render in the usual way. Now the tricky part; the output file name should contain a \texttt{\%d} which will be the frame number used in the image output filename as in: Select a file to render to \texttt{/tmp/tiff\_images/img\%03d.tiff}. You will get multiple files as output --- one for each frame!
+This will define a new ffmpeg encoder format which is a video image file format that uses the tiff codec for encoding, and a pixel\_format of \textit{rgb48} (or a similar equivalent such as rgb48le). Next load up your project and set up for a Render using \texttt{File $\rightarrow$ Render} in the usual way. Now the tricky part; the output file name should contain a \texttt{\%d} which will be the frame number used in the image output filename as in: Select a file to render to \texttt{/tmp/tiff\_images/img\%03d.tiff}. You will get multiple files as output -- one for each frame!
-The resulting directory of images can be opened for reading by simply opening the template path. As in: File$\rightarrow$Load Files \texttt{/tmp/tiff\_images/img\%03d.tiff}. You will notice a file named the same as the template, which has been automatically created, is empty, is needed, and has to remain with the set.
+The resulting directory of images can be opened for reading by simply opening the template path. As in: \texttt{File $\rightarrow$ Load Files} \texttt{/tmp/tiff\_images/img\%03d.tiff}. You will notice a file named the same as the template, which has been automatically created, is empty, is needed, and has to remain with the set.
\section{Raw Input Opts File for Video/Audio}%
\label{sec:raw_input_opts_video_audio}
-Raw video is not affected by decoding on read in. This makes it very attractive to provide raw image data for editing and rendering media. A wide variety of raw formats are available via the ffmpeg file interface. To load media in a raw format, select \texttt{try ffmpeg first} and create an accompanying \textit{opts} file. The opts files must be in the same directory as your media, with the same base name, and the \texttt{.opts} extension. The opts file contents should reflect your video setup. An example follows:
+Raw video is not affected by decoding on read in. This makes it very attractive to provide raw image data for editing and rendering media. A wide variety of raw formats are available via the ffmpeg file interface. To load media in a raw format, select \textit{try ffmpeg first} and create an accompanying \textit{opts} file. The opts files must be in the same directory as your media, with the same base name, and the \texttt{.opts} extension. The opts file contents should reflect your video setup. An example follows:
-\begin{lstlisting}[language=bash,numbers=none]]
+\begin{lstlisting}[language=bash,numbers=none]
# Video file name: /tmp/buddy.mov
# Opts file name: /tmp/buddy.opts
# Contents of opts file:
\emph{current state} of Linux software, enhanced with additional \emph{basic features}, and enriched with \emph{new features} imagined by dedicated users and then implemented by professional programmers.
\begin{description}
- \item[Website] \url{https://www.cinelerra-gg.org}\\
+ \item[Website] \small \url{https://www.cinelerra-gg.org}\\
The website for the cinelerra-gg software is a good place to start for information, help, and documentation.
It is professionally maintained and continuously updated with more language
translations ongoing.
The \textit{autos} are created by clicking on an \textit{automation curve} to establish the time position for the new keyframe anchor point. The basic nature of these simple auto values make them primitive operations that are easy to apply when needed.
-There are many automation curve types, and most are not normally visible or clickable. To make them visible, use the \textit{View} pulldown, or open the \textit{Show Overlays} window in the \textit{Window} menu pulldown. This window allows toggling of the parameters in the View pulldown but is more convenient because you can leave the window up to change values quickly. If all of the automation curves are turned on, the timeline will be quite cluttered, and so usually only the parameters of interest are enabled during use. When keyframes are selected, they are drawn on the timeline over the tracks to which they apply. The keyframe is represented on the timeline as a little square on the curve, for example as in fade, or as a symbol as in a mask. This square, timeline attachment point, can be used for positioning by clicking on a keyframe anchor and using drag and drop to set the new position.
+There are many automation curve types, and most are not normally visible or clickable. To make them visible, use the \texttt{View} pulldown, or open the \texttt{Window $\rightarrow$ Show Overlays}. This window allows toggling of the parameters in the View pulldown but is more convenient because you can leave the window up to change values quickly. If all of the automation curves are turned on, the timeline will be quite cluttered, and so usually only the parameters of interest are enabled during use. When keyframes are selected, they are drawn on the timeline over the tracks to which they apply. The keyframe is represented on the timeline as a little square on the curve, for example as in fade, or as a symbol as in a mask. This square, timeline attachment point, can be used for positioning by clicking on a keyframe anchor and using drag and drop to set the new position.
The automation keyframes include:
-\texttt{mute/play audio}, \texttt{camera translation x,y and zoom}, \texttt{projector\\
- translation x,y and zoom}, \texttt{fade blending}, \texttt{audio panning}, \texttt{overlay mode}, \texttt{mask point sets}, and \texttt{sampling speed}
+mute/play audio; camera translation x,y and zoom; projector translation x,y and zoom; fade blending; audio panning; overlay mode; mask point sets and sampling speed.
Except for the mask auto, the values are all simple numbers. Mute is different from the other autos in that it is simply a toggle of either on or off. Mute keyframes determine where the track is processed but not rendered to the output. An example usage would be to use auto keyframes to fade in a clip by setting the transparency to $100\%$ at the first keyframe and adding another keyframe 5 seconds later in the timeline with a transparency of $0\%$.
\section{Using Autos}%
\label{sec:using_autos}
-The first click on the curve, creates a keyframe which you can \texttt{click drag} on to reposition. The second click at a later position, generates the smoothing by creating a smooth ramp. \texttt{Ctrl-dragging} on a keyframe round control point handle changes the value of either the input control or the output control. This affects the sharpness of the curve. While the input control and the output control can be moved horizontally as well as vertically, the horizontal movement is only for legibility and is not used in the curve value. When you \texttt{Shift-drag} on a timeline curve, the keyframe snaps to the value of either the next or previous keyframe, depending on which exists. It will snap up or down depending on direction of movement. This lets you set a constant curve value without having to copy the next or previous keyframe.
+The first click on the curve, creates a keyframe which you can click drag on to reposition. The second click at a later position, generates the smoothing by creating a smooth ramp. Ctrl-dragging on a keyframe round control point handle changes the value of either the input control or the output control. This affects the sharpness of the curve. While the input control and the output control can be moved horizontally as well as vertically, the horizontal movement is only for legibility and is not used in the curve value. When you Shift-drag on a timeline curve, the keyframe snaps to the value of either the next or previous keyframe, depending on which exists. It will snap up or down depending on direction of movement. This lets you set a constant curve value without having to copy the next or previous keyframe.
-To make it easier to navigate curve keyframes, since there is not much room on the timeline for a wide range of curve values, you need to zoom the curves in and out vertically to have any variability. This is done by 2 tools: the automation fit button, \texttt{Alt-f}, and automation zoom menu which is seen at the bottom of the main window (figure~\ref{fig:automation}). The automation fit button scales and offsets the vertical range so the selected curve area appears in the timeline. If a region of the timeline is highlighted by the cursor, only that region is scaled. In/out points do not affect the zoomed region. The automation zoom menu manually changes the vertical scaling of the curves in multiples of 2. Click on its tumbler to change the zoom. \texttt{Alt-up arrow} and \texttt{Alt-down arrow} change the automation zoom from the keyboard.
+To make it easier to navigate curve keyframes, since there is not much room on the timeline for a wide range of curve values, you need to zoom the curves in and out vertically to have any variability. This is done by 2 tools: the automation fit button, Alt-f, and automation zoom menu which is seen at the bottom of the main window (figure~\ref{fig:automation}). The automation fit button scales and offsets the vertical range so the selected curve area appears in the timeline. If a region of the timeline is highlighted by the cursor, only that region is scaled. In/out points do not affect the zoomed region. The automation zoom menu manually changes the vertical scaling of the curves in multiples of 2. Click on its tumbler to change the zoom. Alt$-\uparrow$ and Alt$-\downarrow$ change the automation zoom from the keyboard.
\begin{figure}[htpb]
\centering
\begin{enumerate}
\item click using the right mouse button on one of the auto speed keyframes on the timeline;
\item a popup menu comes up with speed or fade auto type as the first menu item;
- \item click on speed or fade and a colored slider bar will appear (default speed=orange; fade=pink);
+ \item click on speed or fade and a colored slider bar will appear (default speed = orange; fade = pink);
\item click the slider, press and hold the left mouse button and move the slider to update the value or
simply type in a value in the textbox followed by pressing the Enter key or click the checkmark;
\item a tooltip shows the keyframe value;
\end{enumerate}
\end{itemize}
-You can click mouse button 3 on a keyframe box and a menu pops up with the first menu item showing the keyframe type. The top menu item can be activated for immediate access to update the automation keyframe value. Some keyframe types, which have values that can be manipulated in another way than by dragging the color coded line, now show up with a different colored background to make them more visible. Keep in mind that Zoombar ranges/values must be set to appropriate values when working with specific keyframe types, such as Fade or Speed. If you do not see the auto line in the visible area of the video track, try the key combination \texttt{Alt-f} or select the speed in the \textit{Automation Type} drop-down menu at the bottom of the main window. To the right of this field is \textit{Automation Range} where you can set the display ratio of these lines. Simply change the values until the lines are visible again.
+You can click mouse button 3 on a keyframe box and a menu pops up with the first menu item showing the keyframe type. The top menu item can be activated for immediate access to update the automation keyframe value. Some keyframe types, which have values that can be manipulated in another way than by dragging the color coded line, now show up with a different colored background to make them more visible. Keep in mind that Zoombar ranges/values must be set to appropriate values when working with specific keyframe types, such as Fade or Speed. If you do not see the auto line in the visible area of the video track, try the key combination Alt-f or select the speed in the \textit{Automation Type} drop-down menu at the bottom of the main window. To the right of this field is \textit{Automation Range} where you can set the display ratio of these lines. Simply change the values until the lines are visible again.
Figure~\ref{fig:overlays1} and figure~\ref{fig:fade} shows several color coded lines for different key\-fra\-mes and specifically the slider bar for the Fade keyframe. It is in the same color as the color coded keyframe type line which is the same color which would be shown in the \textit{Show overlays} window figure~\ref{fig:overlays_window}.
\label{fig:fade}
\end{figure}
-In the \textit{Editing} section of \texttt{Settings $\rightarrow$ Preferences}, the Interface tab there is \textit{Keyframe reticle} with options of Never, Dragging, or Always. This is used to help in checking edit alignment across tracks. (A reticle is a sighting line used to line up visual items, like cross hairs in a eyepiece.) The appearance and function of sighting lines can be changed when dragging auto keyframes. To see the effect, create some fader autos and drag a few to see the reticles drawn --- you will see something similar to the next screencast (figure~\ref{fig:always}). \textit{Always} renders a line over all plugins, and \textit{dragging} only over the drag icon. \textit{Never} draws nothing. The default is \textit{dragging}.
+In the \textit{Editing} section of \texttt{Settings $\rightarrow$ Preferences, Interface} tab there is \textit{Keyframe reticle} with options of Never, Dragging, or Always. This is used to help in checking edit alignment across tracks. (A reticle is a sighting line used to line up visual items, like cross hairs in a eyepiece.) The appearance and function of sighting lines can be changed when dragging auto keyframes. To see the effect, create some fader autos and drag a few to see the reticles drawn --- you will see something similar to the next screencast (figure~\ref{fig:always}). \textit{Always} renders a line over all plugins, and \textit{dragging} only over the drag icon. \textit{Never} draws nothing. The default is \textit{dragging}.
\begin{figure}[htpb]
\centering
Releasing button 1 ends the current dragging operation, but single clicking on a speed/fade keyframe handle again will restart the drag operation on tracks of the same type. Double clicking will select all armed tracks which have handles in the exact same cursor position. It is sometimes difficult to get the desired value for the speed and it may take a few tries to get to the desired endpoint, but you can use an auto slider bar to get better control for more precision. This is not ganged so you will have to do this on each track to achieve the same value.
-An easy way to get an exact position is to set the "Automation range" in the bottom bar of the main
+An easy way to get an exact position is to set the \textit{Automation range} in the bottom bar of the main
window to the low and high ends of the desired range. For example, 1.000 to 50.000, which makes it
so you can drag the speed/fade handle all the way to the left for 1.000 or all the way to the right for 50.
For plugins, there is a special hidden keyframe, called the \textit{default keyframe}, that is used when no previous keyframe exists. It is like keyframe zero on the timeline, and it is persistent and shared on
all sessions. The intent is to make a parameter set that is likely to be reused on all initial instances of the plugin. An example may be to color correct a set of media that was taken in low light, or needs resampling to be played correctly. The default keyframe is \textit{off the bar on the left side} of the plugin title bar and can not be seen. It is used when there is no \textit{previous} keyframe for its default values.
-It may be useful to create a default keyframe which has specific desirable values for later use. To do this, set the timeline to position 0 and be sure to disable \textit{generate keyframes while tweaking}. This will create a default keyframe at the beginning of the timeline which contains global parameters for the entire duration. Or if you have copied a non-default keyframe via Keyframes pulldown \textit{copy default keyframe}, it can be stored as the default keyframe by calling \texttt{keyframes$\rightarrow$paste default keyframe}. After using paste default keyframe to convert a non-default keyframe into a default keyframe, you will not see the value of the default keyframe reflected until all the non-default keyframes are removed.
+It may be useful to create a default keyframe which has specific desirable values for later use. To do this, set the timeline to position 0 and be sure to disable \textit{generate keyframes while tweaking}. This will create a default keyframe at the beginning of the timeline which contains global parameters for the entire duration. Or if you have copied a non-default keyframe via Keyframes pulldown \textit{copy default keyframe}, it can be stored as the default keyframe by calling \texttt{keyframes $\rightarrow$ paste default keyframe}. After using paste default keyframe to convert a non-default keyframe into a default keyframe, you will not see the value of the default keyframe reflected until all the non-default keyframes are removed.
-The \texttt{keyframes$\rightarrow$copy default keyframe} and \texttt{keyframes} $\rightarrow$ \texttt{paste} {\texttt{de\-fault keyframe} allow conversion of the default keyframe to a non-default key\-fra\-me.
+The \texttt{keyframes $\rightarrow$ copy default keyframe} and \texttt{keyframes} $\rightarrow$ \texttt{paste} {\texttt{de\-fault keyframe} allow conversion of the default keyframe to a non-default keyframe.
-\texttt{Keyframes$\rightarrow$copy default keyframe} copies the default keyframe to the clipboard, no matter what region of the timeline is selected.
-The \texttt{keyframes}$\rightarrow$ \texttt{pas\-te} \texttt{keyframes} function may then be used to paste the clipboard as a non-default keyframe.
+\texttt{Keyframes $\rightarrow$ copy default keyframe} copies the default keyframe to the clipboard, no matter what region of the timeline is selected.
+The \texttt{keyframes $\rightarrow$ paste} \texttt{keyframes} function may then be used to paste the clipboard as a non-default keyframe.
\textit{Typeless keyframes} enabled under the Settings pulldown allow keyframes from any track to be pasted on either audio or video tracks. Ordinarily audio keyframes can only be pasted to another audio track and video keyframes can only be pasted to another video track.
\section{Keyframe \textit{Edit Params} for Plugins}%
\label{sec:keyframe_edit_params_plugin}
-Keyframe values can be set using the various plugin \textit{show controls} (magnifying glass) icon on the plugin track (figure~\ref{fig:parameters}). It is possible to see all of the keyframe data in a raw format using the \textit{Edit Params} popup menu item which you will see when you right mouse click the keyframe icon on the timeline. The keyframe data is stored in \texttt{xml} format, and the \textit{edit params} feature allows you to view and modify the xml data directly. This normally should not be necessary since the plugin's control gui displays the intended parameters, but this will let you view and specify just about anything that can be specified in xml. There is no validation checking of the modified data.
+Keyframe values can be set using the various plugin \textit{show controls} (magnifying glass) icon on the plugin track (figure~\ref{fig:parameters}). It is possible to see all of the keyframe data in a raw format using the \textit{Edit Params} popup menu item which you will see when you right mouse click the keyframe icon on the timeline. The keyframe data is stored in xml format, and the \textit{edit params} feature allows you to view and modify the xml data directly. This normally should not be necessary since the plugin's control gui displays the intended parameters, but this will let you view and specify just about anything that can be specified in xml. There is no validation checking of the modified data.
\begin{figure}[htpb]
\centering
\section{Generate Keyframes while Tweaking / Automatic Keyframe Mode}%
\label{sec:generate_keyframe_tweaking}
-Tweaking is defined as changing a parameter while playing --- it can be small changes or small motion increments performed in a series. These changes are recorded as a series of new keyframes on the timeline. Enable automatic keyframe mode by enabling the automatic keyframe toggle, that is \textit{Generate keyframes while tweaking}. In automatic keyframe mode, every time you tweak a key-framable parameter it creates a keyframe on the timeline. Since keyframes affect playback, you should enable generate keyframes just before you need a keyframe and disable when your parameter changes are complete. So turn on when ready to make changes and turn off when done!
+Tweaking is defined as changing a parameter while playing -- it can be small changes or small motion increments performed in a series. These changes are recorded as a series of new keyframes on the timeline. Enable automatic keyframe mode by enabling the automatic keyframe toggle, that is \textit{Generate keyframes while tweaking}. In automatic keyframe mode, every time you tweak a key-framable parameter it creates a keyframe on the timeline. Since keyframes affect playback, you should enable generate keyframes just before you need a keyframe and disable when your parameter changes are complete. So turn on when ready to make changes and turn off when done!
Also, before making a change, be sure to check the View pulldown and make the desired parameter visible with the enable checkmark. The location where the automatic keyframe is generated is under the insertion point. If the timeline is playing back during a tweak, several automatic keyframes may be generated as you change the parameter. When automatic keyframe mode is disabled, adjusting a parameter adjusts the keyframe immediately preceding the insertion point. For example, if two fade keyframes exist and the insertion point is between them, changing the fader changes the first keyframe.
\section{Compositor Keyframes}%
\label{sec:compositor_keyframes}
-Camera and projector translation is represented by two parameters: x and y, making it difficult to adjust with curves. Cinelerra solves this problem by relying on automatic keyframes. With a video track loaded, move the insertion point to the beginning of the track and enable automatic keyframe mode. Move the projector slightly in the compositor window to create a keyframe. Then go forward several seconds. Move the projector a long distance to create another keyframe and emphasize motion. This creates a second projector box in the compositor, with a line joining the two boxes. The joining line is the motion path. If you create more keyframes, more boxes are created. Once all the desired keyframes are created, disable automatic keyframe mode.
+Camera and projector translation is represented by two parameters: \textit{x} and \textit{y}, making it difficult to adjust with curves. Cinelerra solves this problem by relying on automatic keyframes. With a video track loaded, move the insertion point to the beginning of the track and enable automatic keyframe mode. Move the projector slightly in the compositor window to create a keyframe. Then go forward several seconds. Move the projector a long distance to create another keyframe and emphasize motion. This creates a second projector box in the compositor, with a line joining the two boxes. The joining line is the motion path. If you create more keyframes, more boxes are created. Once all the desired keyframes are created, disable automatic keyframe mode.
Dragging the auto curve with tweaking off, adjusts the previous keyframe. With tweaking on, if no keyframe is at the timeline position, then a new one is created at that position and the modification value is applied. If you are halfway between two keyframes, the first projector box is adjusted while the second one stays the same. The video does not appear to move in step with the first keyframe. This is because halfway between two keyframes, the projector translation is interpolated. In order to set the second keyframe you will need to move after the second keyframe.
Keyframes can be shifted around and moved between tracks on the timeline using similar cut and paste operations to editing media. Only the keyframes selected in the View menu are affected by keyframe editing operations.
-An often used, keyframe editing operation is replication of some curve from one track to the other to make a stereo pair. The first step is to solo the source track's record patch by \texttt{Shift-clicking} on the \textit{arm track} icon in the patchbay. Then either set In/Out points or highlight the desired region of keyframes. Go to \texttt{keyframes$\rightarrow$copy keyframes} to copy them to the clipboard. Solo the destination track's record patch by \texttt{Shift-clicking} on it and go to \texttt{keyframes$\rightarrow$paste keyframes} to paste the clipboard. Another common application for keyframe modification is to highlight a region on the timeline which contains multiple keyframes that you want to modify. Then when you adjust a parameter or set of parameters, the change will be applied to all keyframes within the selection instead of a new keyframe being created. This only works when the keyframe stores multiple parameters and only for mask and effect keyframes. Other types of keyframes are generated as usual.
+An often used, keyframe editing operation is replication of some curve from one track to the other to make a stereo pair. The first step is to solo the source track's record patch by Shift-clicking on the \textit{arm track} icon in the patchbay. Then either set In/Out points or highlight the desired region of keyframes. Go to \texttt{keyframes $\rightarrow$ copy keyframes} to copy them to the clipboard. Solo the destination track's record patch by Shift-clicking on it and go to \texttt{keyframes $\rightarrow$ paste keyframes} to paste the clipboard. Another common application for keyframe modification is to highlight a region on the timeline which contains multiple keyframes that you want to modify. Then when you adjust a parameter or set of parameters, the change will be applied to all keyframes within the selection instead of a new keyframe being created. This only works when the keyframe stores multiple parameters and only for mask and effect keyframes. Other types of keyframes are generated as usual.
-And there is an easy way to delete keyframes besides selecting a region and using \texttt{keyframes$\rightarrow$clear keyframes}. \texttt{Click-drag} a keyframe before its preceding keyframe or after its following keyframe on the track. This is the only way you can simultaneously delete keyframes on ganged tracks.
+And there is an easy way to delete keyframes besides selecting a region and using \texttt{keyframes $\rightarrow$ clear keyframes}. Click-drag a keyframe before its preceding keyframe or after its following keyframe on the track. This is the only way you can simultaneously delete keyframes on ganged tracks.
\subsection{Working with Still Images}%
\label{sub:working_with_still_images}
-Still images are played from 1 to any number of times, over and over; they have no duration. You can load still images on video tracks just like you do for any video file. When loaded on the track, use the down arrow on the timeline so you can see the single frame. To extend the length of the image, drag its boundaries just as you would do with regular video media. You can drag the boundaries of a still image as much as you want. Images in Cinelerra have the ability to be dragged to an infinite length. Alternatively, you can define the initial length of the loaded images. The parameter is set in the Images section of the Settings $\rightarrow$ ~Preferences $\rightarrow$ ~Recording window.
+Still images are played from 1 to any number of times, over and over; they have no duration. You can load still images on video tracks just like you do for any video file. When loaded on the track, use the down arrow on the timeline so you can see the single frame. To extend the length of the image, drag its boundaries just as you would do with regular video media. You can drag the boundaries of a still image as much as you want. Images in Cinelerra have the ability to be dragged to an infinite length. Alternatively, you can define the initial length of the loaded images. The parameter is set in the Images section of the \texttt{Settings $\rightarrow$ ~Preferences $\rightarrow$ ~Recording} window.
Unless your original material comes from a digital source using its best resolution (like a digital camera), the first thing you might have to do before you can use it is to somehow capture the assets into a usable digital medium. For old photos, paper maps, drawings or diagrams, you can scan them into a file format like PNG, TIF, TGA or JPG files by using a digital scanner.
\end{center}
%\vspace*{1ex}
-Using the example of jpeg’s, the jpeg list sequence file type is the easiest and fastest way to access a sequence of jpg images as a single asset. First build a jpeglist sequence file and name it something like jpeglist.sh. There is an example script of how to do this in the Auxiliary Programs section of the Appendix. Once the jpeglist.sh file is built you can then run it similar to this line:
+Using the example of jpeg’s, the jpeg list sequence file type is the easiest and fastest way to access a sequence of jpg images as a single asset. First build a jpeglist sequence file and name it something like jpeglist.sh. There is an example script of how to do this in the Auxiliary Programs section of the Appendix (\ref{sec:Image Sequence Creation}). Once the jpeglist.sh file is built you can then run it similar to this line:
\begin{lstlisting}[language=bash,numbers=none]
$ jpeglist.sh /<path>/file.jpg /<path>/DSC*.jpg
\end{lstlisting}
-\vspace*{1ex} \noindent If <path> is the same on both outfile and infiles, then file.jpg is created in the same directory as infiles, the directory contains the entire asset, and the file list uses relative paths; otherwise the file list contains absolute paths. Since this creates outfile list as a single asset, the memory demand and access time is much lower. When you load the outfile in cinelerra, you will need to set \textit{Try ffmpeg last} since ffmpeg does not work with jpeglist sequence files.
+\vspace*{1ex} \noindent If <\texttt{path}> is the same on both outfile and infiles, then file.jpg is created in the same directory as infiles, the directory contains the entire asset, and the file list uses relative paths; otherwise the file list contains absolute paths. Since this creates outfile list as a single asset, the memory demand and access time is much lower. When you load the outfile in cinelerra, you will need to set \textit{Try ffmpeg last} since ffmpeg does not work with jpeglist sequence files.
-An example output file from running this script residing in the directory where \texttt{DSC*.jpg} files exist is shown below. To use this, turn off ffmpeg probes first, and open \texttt{timelapse.jpg} using File ~$\rightarrow$ ~Load files.
+An example output file from running this script residing in the directory where \texttt{DSC*.jpg} files exist is shown below.
+
+To use this, turn off ffmpeg probes first, and open \texttt{timelapse.jpg} using File ~$\rightarrow$ ~Load files.
\begin{lstlisting}[language=bash,numbers=none,caption={Example: timelapse.jpg},captionpos=t]
JPEGLIST
\textit{Warning: Expert Usage only.} Raw digital camera images are a special kind of image file that Cinelerra can load. Dcraw, as used by Cinelerra, is Dave Coffin’s open-source computer program which reads many raw-image formats typically produced by high-end digital cameras. Currently almost 700 of the types of cameras it recognizes are listed at:
-\vspace*{1ex} \url{https://www.cybercom.net/~dcoffin/dcraw/}
+\hspace{4em} {\small \url{https://www.cybercom.net/~dcoffin/dcraw/}}
-\vspace*{1ex} \noindent For example, included is the Canon Powershot SX60 (newly available in August, 2014). Because ffmpeg tries to load \textit{any and every} file if \textit{Try Ffmpeg first} is enabled. it will make an attempt to load Raw Camera files first before any other file driver gets the chance. In addition, there is the possibility that dcraw could conflict with the standard TIFF format, since it might be seen as format type \textit{tiff-pipe}. Therefore it is necessary to specifically enable CR2 and either move it to the top or disable \textit{FFMPEG\_Early} and enable \textit{FFMPEG\_late} in the \textit{Probe Order} as described in another section. These changed settings will be retained across cinelerra sessions in .bcast5. Raw Camera mode is most likely going to be used by expert camera users.
+For example, included is the Canon Powershot SX60 (newly available in August, 2014). Because ffmpeg tries to load \textit{any and every} file if \textit{Try Ffmpeg first} is enabled. it will make an attempt to load Raw Camera files first before any other file driver gets the chance. In addition, there is the possibility that dcraw could conflict with the standard TIFF format, since it might be seen as format type \textit{tiff-pipe}. Therefore it is necessary to specifically enable CR2 and either move it to the top or disable \textit{FFMPEG\_Early} and enable \textit{FFMPEG\_late} in the \textit{Probe Order} as described in another sections (\ref{sub:probe_order_loading_media} and \ref{sec:ffmpeg_early_probe_explanation}). These changed settings will be retained across cinelerra sessions in .\texttt{bcast5}. Raw Camera mode is most likely going to be used by expert camera users.
-The first screenshot in figure~\ref{fig:raw} as in ~Settings $\rightarrow$ ~Preferences $\rightarrow$ ~Playback A Tab, shows the default checked settings of \textit{Interpolate CR2 images} and \textit{White balance CR2 images} which display the raw images in a way that you expect. However, you may want to uncheck them to ensure that no program manipulation has modified your images so that you can add plugins or make your own modifications. Unchecked indicates that the images are as closest as possible to unadulterated raw.
+The first screenshot in figure~\ref{fig:raw} as in \texttt{Settings $\rightarrow$ ~Preferences $\rightarrow$ ~Playback A} Tab, shows the default checked settings of \textit{Interpolate CR2 images} and \textit{White balance CR2 images} which display the raw images in a way that you expect. However, you may want to uncheck them to ensure that no program manipulation has modified your images so that you can add plugins or make your own modifications. Unchecked indicates that the images are as closest as possible to unadulterated raw.
The second screenshot showing CR2 for Raw Camera highlighed/enabled in the Preferences Probes’ screen.
\item [Replace current project:] all tracks in the current project are deleted and a set of new tracks are created to match the source file. Project attributes are only changed when loading XML. If multiple files are selected for loading, Cinelerra adds a set of new tracks for each file. New resources are created in the Resources Window, replacing the current ones.
\item [Replace current project and concatenate tracks: ] same as replace current project, except that if multiple files are selected, Cinelerra will concatenate the tracks of each file, inserting different source files in the same set of tracks, one after another, in alphanumeric order, starting at 0. New resources are created in the Resources Window, replacing the current ones. Files go across the timeline.
\end{description}
- For ffmpeg and mpeg files, when the Insertion strategy methodology in the File $\rightarrow$ Load files pulldown is chosen to be either \textit{Replace current project} or \textit{Replace current project and concatenate tracks}, the basic session format parameters are reinitialized to match new media. This selects the default asset and determines its width, height, and video length, frame rate, calculates the colormodel, and assumes square pixels to make an intelligent guess about aspect ratio for video. For audio, the sample rate, audio length, and channel count (mono, stereo, or 5.1) are reinitialized. In addition the \textit{Track Size} will be computed and is reinitialized to match the new loaded media. When using \textit{replace} type insertion strategy, the new asset list is the only media in use so that this update saves the user from immediately needing to change the session format to match the only possibility.
+ For ffmpeg and mpeg files, when the Insertion strategy methodology in the \texttt{File $\rightarrow$ Load files} pulldown is chosen to be either \textit{Replace current project} or \textit{Replace current project and concatenate tracks}, the basic session format parameters are reinitialized to match new media. This selects the default asset and determines its width, height, and video length, frame rate, calculates the colormodel, and assumes square pixels to make an intelligent guess about aspect ratio for video. For audio, the sample rate, audio length, and channel count (mono, stereo, or 5.1) are reinitialized. In addition the \textit{Track Size} will be computed and is reinitialized to match the new loaded media. When using \textit{replace} type insertion strategy, the new asset list is the only media in use so that this update saves the user from immediately needing to change the session format to match the only possibility.
\begin{description}
\item[Append in new tracks:] the current project is not deleted and new tracks are created for the source, one set of tracks for each file. New resources are created in the Resources Window. Files go down tracks.
\item[Concatenate to existing tracks:] the current project is not deleted and new files are concatenated to the existing armed tracks, inserted in the same set of tracks of the current project, one after another, in alphanumeric order, starting at the end of the tracks. If the current project has more tracks than the source, the source file will be inserted in the first set of armed tracks. If no tracks are armed, no files will be inserted. New resources are created in the Resources Window.
\item[Loading the backup] There is one special XML file on disk at all times.
After every editing operation, Cinelerra saves the current project to a backup in \texttt{\$HOME/.bcast/backup.xml}.
- In the event of a crash, the first thing you should do after restarting Cinelerra is select File $\rightarrow$ Load backup in order to load the backup.
+ In the event of a crash, the first thing you should do after restarting Cinelerra is select \texttt{File $\rightarrow$ Load backup} in order to load the backup.
This will start Cinelerra at the point in your editing operations directly before the program crashed.
It is important after a crash to restart Cinelerra without performing any editing operations as you will overwrite the backup.
Note that the backup.xml file is always a single file which means that when you are working with two instances of Cinelerra open at the same time, they use the same backup file.
\subsection{Size Numeric Format Displayed in File Load}%
\label{sub:size_numeric_format_displayed_file_load}
-There are several icon buttons at the top on the right hand side of the Load window. Each has a tooltip to explain what it is for. You can see these in the previous figure. One is for File size format. There are 4 numerical representation variations for reporting the file size in the File $\rightarrow$ Load pulldown. You can see the options in the Load window to the right of the top line that read \textit{Select files to loads} (figure~\ref{fig:load-size}):
+There are several icon buttons at the top on the right hand side of the Load window. Each has a tooltip to explain what it is for. You can see these in the previous figure. One is for File size format. There are 4 numerical representation variations for reporting the file size in the \texttt{File $\rightarrow$ Load} pulldown. You can see the options in the Load window to the right of the top line that read \textit{Select files to loads} (figure~\ref{fig:load-size}):
\begin{description}
\item[0] this is the default and current behavior and shows bytes the same as the \textit{ls -l} command.
\subsection{Probe Order when Loading Media}%
\label{sub:probe_order_loading_media}
-Why is this mentioned here? So many programs have been written whose functionalities overlap and you may want to ensure that the one you wish to use is actually used. Over time which one matches first may vary. Ffmpeg is so generic that if your setting is \textit{Try ffmpeg first} it will almost certainly get used and it leaves little chance that other methods will even get a chance. Some of the codec file drivers can open a variety of media, and some of the more common methods may have more than one file driver which could be useful to decode your media file, for example Tiff. For expert specialized usage, when you want to guarantee that a certain method is used, you can change the \textit{probe order}. Use the pulldown Settings $\rightarrow$ Preferences to get to the Interface tab where you will see a box in the Operation section on the left side called \textit{Probe Order}. Click on the box and use the up/down/enabled boxes to change the order of the item you have highlighted (figure~\ref{fig:probe}).
+Why is this mentioned here? So many programs have been written whose functionalities overlap and you may want to ensure that the one you wish to use is actually used. Over time which one matches first may vary. Ffmpeg is so generic that if your setting is \textit{Try ffmpeg first} it will almost certainly get used and it leaves little chance that other methods will even get a chance. Some of the codec file drivers can open a variety of media, and some of the more common methods may have more than one file driver which could be useful to decode your media file, for example Tiff. For expert specialized usage, when you want to guarantee that a certain method is used, you can change the \textit{probe order}. Use the pulldown \texttt{Settings $\rightarrow$ Preferences} to get to the Interface tab where you will see a box in the Operation section on the left side called \textit{Probe Order}. Click on the box and use the up/down/enabled boxes to change the order of the item you have highlighted (figure~\ref{fig:probe}).
\begin{description} [noitemsep]
\item[Up] move the item up 1 (if the item is currently on the top, it will be moved to the bottom)
Screencast show the first few probe items. Note that the up arrow on the left, signifies \textit{enabled}.
Scrolling down shows the next 2 pages of possible drivers for a total of 18.
-The order change will not take effect until you click on the checkmark in both the Probes window and the Preferences window. When you click on the FF button, which is in the upper right-hand corner of the main page to change \textit{Try FFMpeg first/last}, enabling of FFMPEG\_Late or FFMPEG\_Early will be toggled automatically in Probes to match that choice but does NOT change its position in the table. Be sure to only click on the FF button without the Preference/Probes window up to avoid unexpected results. It is also recommended to leave FFMPEG\_Early/FFMPEG\_Late close to the top/bottom positions. There is one case where you may want to disable all of the probes if you want to force PCM --- Pulse Code Modulator. This code is always run when all other probes fail.
+The order change will not take effect until you click on the checkmark in both the Probes window and the Preferences window. When you click on the FF button, which is in the upper right-hand corner of the main page to change \textit{Try FFMpeg first/last}, enabling of FFMPEG\_Late or FFMPEG\_Early will be toggled automatically in Probes to match that choice but does NOT change its position in the table. Be sure to only click on the FF button without the Preference/Probes window up to avoid unexpected results. It is also recommended to leave FFMPEG\_Early/FFMPEG\_Late close to the top/bottom positions. There is one case where you may want to disable all of the probes if you want to force PCM -- Pulse Code Modulator. This code is always run when all other probes fail.
\subsection{Program Selection Support after Load}%
\label{sub:program_selection_support_load}
\subsection{Saving Project Files}%
\label{sub:saving_project_files}
-Saving XML files is useful to save the current state of Cinelerra before quitting an editing session. Cinelerra saves projects as XML files. There are a few options you can use to save your work via the File pulldown menu: Save, Save as\dots, Export project, Save backup. You can either overwrite an existing file or enter a new filename. Cinelerra automatically concatenates .xml to the filename if no .xml extension is given.
+Saving XML files is useful to save the current state of Cinelerra before quitting an editing session. Cinelerra saves projects as XML files. There are a few options you can use to save your work via the File pulldown menu: \textit{Save}, \textit{Save as\dots}, \textit{Export project}, \textit{Save backup}. You can either overwrite an existing file or enter a new filename. Cinelerra automatically concatenates .xml to the filename if no .xml extension is given.
When Cinelerra saves a file, it saves the EDL of the current project but does not save any media, instead just pointers to the original media files. For each media file, the XML file stores either an absolute path or just the relative path. If the media is in the same directory as the XML file, a relative path is saved. If it is in a different directory, an absolute path is saved.
You have to be careful when moving files around to avoid breaking the media linkages. You can keep the media and the XML file in the same directory forever and freely move the whole directory, since relative paths are saved. Alternatively you can save the XML file in a different directory than the media but then you can't move the media. In this case you can freely move your XML file around, since absolute paths are saved. If you saved your XML file in the same directory as your media but you would like to move location, you can change the paths from relative to absolute by going
-to File $\rightarrow$ Save as... and entering the new location. Similarly if you saved your project outside your media directory but you would like to move your media to another location, you can change the paths from absolute to relative by going to File $\rightarrow$ Save as\dots and saving your XML file in the same directory as the media.
+to \texttt{File $\rightarrow$ Save as}$\dots$ and entering the new location. Similarly if you saved your project outside your media directory but you would like to move your media to another location, you can change the paths from absolute to relative by going to File $\rightarrow$ Save as\dots and saving your XML file in the same directory as the media.
You can also repair broken media linkage by editing the XML file in a text editor. For every media you moved, search for the old path and replace it with the new one. You should make a backup copy of your XML file before editing. You can also replace the path of every asset whose source file you moved also within the program, by entering the new location in the Asset info window. To open this window, right click on the asset in the Resources window and choose Info\dots in the popup menu. Directly type the path in the first field of the dialog or click on the magnifier on the right to browse your files. Operating
from the GUI is convenient only when a very small number of changes is needed.
In an effort to minimize loss of work due to user, hardware, or software issues, cinelerra has some automatic backup capabilities.
-Cinelerra automatically saves every \textit{editing operation} to the current project on disk continuously to a file named \texttt{\$HOME/.bcast5/backup.xml}. In the unlikely event of a crash, when you restart cinelerra, you should select File $\rightarrow$ Load backup in order to continue with the operations that were recorded before the crash. If you have more than 1 instance of Cinelerra running, only the last editing operation made in whichever instance it was last made, will overwrite the backup.
+Cinelerra automatically saves every \textit{editing operation} to the current project on disk continuously to a file named \texttt{\$HOME/.bcast5/backup.xml}. In the unlikely event of a crash, when you restart cinelerra, you should select \texttt{File $\rightarrow$ Load backup} in order to continue with the operations that were recorded before the crash. If you have more than 1 instance of Cinelerra running, only the last editing operation made in whichever instance it was last made, will overwrite the backup.
-There is still 1 more backup that may save you. If for some reason you forgot to use \textit{Load backup} immediately when restarting, you have a second chance to use File $\rightarrow$ Load and select \texttt{\$HOME/.bcast5/backup.prev} as long as you only loaded a different file and have performed no editing operations. This same file is also used by multiple instances of cinelerra.
+There is still 1 more backup that may save you. If for some reason you forgot to use \textit{Load backup} immediately when restarting, you have a second chance to use \texttt{File $\rightarrow$ Load} and select \texttt{\$HOME/.bcast5/backup.prev} as long as you only loaded a different file and have performed no editing operations. This same file is also used by multiple instances of cinelerra.
\textbf{Perpetual session} is very useful for working on a project over many days so you can just quit before shutting down and the next time you start up Cinelerra you will be right back where you left off.
You will retain all of your undo’s and redo’s.
-The binary file name is \texttt{\$HOME/.bcast5/perpetual.dat} and as long as Settings $\rightarrow$ Preferences, the Appearance tab has the Flag \textit{Perpetual session} set this capability takes effect.
-It is very important to understand that this is not the same as the continuously editing- operation-updated backup.xml file.
+The binary file name is \texttt{\$HOME/.bcast5/perpetual.dat} and as long as \texttt{Settings $\rightarrow$ Preferences}, the Appearance tab has the Flag \textit{Perpetual session} set this capability takes effect.
+It is very important to understand that this is not the same as the continuously editing- operation-updated \texttt{backup.xml} file.
The perpetual.dat file is \textit{only} updated when you Quit cinelerra in the normal manner.
-Which means if you interrupt the program, or kill it, or there is a segv or system crash, the perpetual.dat file will only reflect the state of your project from when you last started cinelerra and none of the editing/undo’s/redo’s you executed during the current session which was not ended normally.
+Which means if you interrupt the program, or kill it, or there is a segv or system crash, the \texttt{perpetual.dat} file will only reflect the state of your project from when you last started cinelerra and none of the editing/undo’s/redo’s you executed during the current session which was not ended normally.
\vspace{1ex}
Some notes to keep in mind about Perpetual session are:
\item takes disk space in \texttt{.bcast5} area and this could get really big
\item after you complete a project, it is advisable to turn off the Perpetual session flag before quitting so
that when you start a new project, you can start with a fresh perpetual.dat by turning the flag on or
- after stopping cinelerra, delete the current \$HOME/.bcast5/perpetual.dat file
+ after stopping cinelerra, delete the current \texttt{\$HOME/.bcast5/perpetual.dat} file
\item only session data is backed up (not program feature setup)
\item the files backup.xml and backup.prev will operate the same as before so that if there is a crash, you
- will want to use File $\rightarrow$ Load backup in order to continue where you were interrupted.
+ will want to use \texttt{File $\rightarrow$ Load backup} in order to continue where you were interrupted.
\end{itemize}
The first thing to do when preparing to do batch rendering is to create one or more Cinelerra projects to be rendered and save them as a normal project, such as \texttt{ProjectA.xml}. The batch renderer requires a separate project file for every batch to be rendered. You can use the same Cinelerra project file if you are rendering to different output files, as in an example where you might be creating the same output video in different file formats.
-To create a project file which can be used in batch render, set up your project and define the region to be rendered either by highlighting it, setting in/out points around it, or positioning the insertion point before it. Then save the project as usual to your project.xml file. Define as many projects as needed this way. The batch renderer takes the active region from the EDL file for rendering. If we have not set active regions, it is better to bring the insertion point to the beginning of the timeline to avoid possible problems with the rendering.
+To create a project file which can be used in batch render, set up your project and define the region to be rendered either by highlighting it, setting in/out points around it, or positioning the insertion point before it. Then save the project as usual to your \texttt{project.xm}l file. Define as many projects as needed this way. The batch renderer takes the active region from the EDL file for rendering. If we have not set active regions, it is better to bring the insertion point to the beginning of the timeline to avoid possible problems with the rendering.
With all the Cinelerra xml project files prepared with active regions, go to \texttt{File $\rightarrow$ Batch Render}. This brings up the batch render dialog. The interface for batch rendering is more complex than for single file rendering. A list of batches must be defined before starting a batch rendering operation. The table of batches appears on the bottom of the batch render dialog and is called \textit{Batches to render}. Above this are the configuration parameters for a single batch; a batch is simply a pairing of a project file with a choice of output file and render settings.
The \texttt{File $\rightarrow$ Batch Render} pulldown brings up the Batch Render window to be used for batch rendering as well as DVD/BD creation. There are some additional buttons that can save time and mistakes. These are described next.
-The \texttt{Save to EDL Path} and \texttt{Use Current EDL} buttons can be valuable tools for advanced usage or for developers doing testing. Description of how you can expect them to work will help to illustrate how to take advantage of their capabilities.
+The \textit{Save to EDL Path} and \textit{Use Current EDL} buttons can be valuable tools for advanced usage or for developers doing testing. Description of how you can expect them to work will help to illustrate how to take advantage of their capabilities.
\begin{description}
\item[Save to EDL Path] if you have made a change to the EDL, use this button to save the changes so
that they will be used in the render operation. Although you can get the same results by using
- \texttt{File $\rightarrow$ Save\dots}, this capability was initially added to assist developers in testing the batch jobs needed
- to create dvd/bluray media as it keeps the work focused in a single window and retains the original
- job name. An example ---you have everything all set up with a new job in the Batch Render window
+ \texttt{File $\rightarrow$ Save\dots}, this capability was initially added to assist developers in testing the batch jobs needed to create dvd/bluray media as it keeps the work focused in a single window and retains the original
+ job name. An example --you have everything all set up with a new job in the Batch Render window
using \texttt{generic.xml} for the EDL path and with a job name of \texttt{original\_name.xml}. Then you realize
that you forgot to cut out a section in the media that is not wanted in the final product. You can cut
that out and then \textit{Save to EDL Path} so your change will be in effect for the rendering. Without this
button, you would be using the EDL you started with and the cut would be ignored. Alternatively, if
- the cut changes are saved via File $\rightarrow$ Save as\dots with a filename of \texttt{new.xml} and then you use \textit{Save to EDL Path}, the current highlighted job displayed in the window as \texttt{original\_name.xml} will be
+ the cut changes are saved via \texttt{File $\rightarrow$ Save as}\dots with a filename of \texttt{new.xml} and then you use \textit{Save to EDL Path}, the current highlighted job displayed in the window as \texttt{original\_name.xml} will be
replaced with \texttt{new.xml}. However, it is important to note that the result will be saved with the name
\texttt{original\_name} – that is, the new content from \texttt{new.xml} but with the old name of \texttt{original\_name.xml}.
\item[Use Current EDL] if you are working on media and still testing out the results, you can take
Render Farm uses background rendering, a feature of Cinelerra where the video is rendered in the background, to speed up rendering significantly. Because rendering is memory and cpu intensive, using multiple computers on a network via a render farm is a significant gain. With Cinelerra installed on all nodes, the master node and the clients communicate via a network port that you specify.
-Cinelerra can distribute the rendering tasks over the network to the other computers of the Render Farm. The render farm software tries to process all of the rendering in parallel so that several computers can be used to render the results. The \texttt{Total jobs to create} in the setup or labels on the timeline are used to divide a render job into that specified number of tasks. Each background job is assigned a timeline segment to process and the jobs are sent to the various computer nodes depending upon the load balance. The jobs are processed by the nodes separately and written to individual files. You will have to put the files back together via a load with concatenation, or typically by using a command line tool from a script.
+Cinelerra can distribute the rendering tasks over the network to the other computers of the Render Farm. The render farm software tries to process all of the rendering in parallel so that several computers can be used to render the results. The \textit{Total jobs to create} in the setup or labels on the timeline are used to divide a render job into that specified number of tasks. Each background job is assigned a timeline segment to process and the jobs are sent to the various computer nodes depending upon the load balance. The jobs are processed by the nodes separately and written to individual files. You will have to put the files back together via a load with concatenation, or typically by using a command line tool from a script.
\subsection{Basic Steps to Start a Render Farm}%
\label{sub:basic_steps_start_render_farm}
\begin{enumerate}
\item On the master computer, use \texttt{Settings} $\rightarrow$ \texttt{Preferences} $\rightarrow$ \texttt{Performance} \texttt{tab} to set up a Render Farm:
\begin{itemize}
- \item check the \texttt{Use render farm} box;
- \item in the \texttt{Hostname} box, keyin your hostname or ip address such as 192.168.1.12 or \texttt{localhost};
- \item enter in a port number such as 401--405 (only a root user can use privileged ports) or $1025$ and click on \texttt{Add Nodes};
+ \item check the \textit{Use render farm} box;
+ \item in the \textit{Hostname} box, keyin your hostname or ip address such as 192.168.1.12 or \textit{localhost};
+ \item enter in a port number such as 401--405 (only a root user can use privileged ports) or $1025$ and click on \textit{Add Nodes};
\item you will see something like the following in the Nodes listbox to the right:\newline
\begin{tabular}{lllc}
On & Hostname & Port & Framerate \\\midrule
$ cin -d 406
$ cin -d 407
\end{lstlisting}
- \item When your video is ready, setup a render job via \texttt{File $\rightarrow$ Render} or \texttt{File $\rightarrow$ Batch Render} and check \texttt{OK}.
- \item The results will be in the shared file path / filename that you selected in the render menu with the
+ \item When your video is ready, setup a render job via \texttt{File $\rightarrow$ Render} or \texttt{File $\rightarrow$ Batch Render} and check OK.
+ \item The results will be in the shared file \texttt{path/filename} that you selected in the render menu with the
additional numbered job section on the end as $001, 002, 003, \dots 099$ (example, \texttt{video.webm001}).
- 6) When finished, load your new files on new tracks via \texttt{File $\rightarrow$ Load} \textit{concatenate to existing tracks} or if you used ffmpeg, run \texttt{RenderMux} from the Shell Scripts icon.
+ \item When finished, load your new files on new tracks via \texttt{File $\rightarrow$ Load} \textit{concatenate to existing tracks} or if you used ffmpeg, run \textit{RenderMux} from the Shell Scripts icon.
\item If you plan on doing more rendering, you can just leave the master/client jobs running to use again
and avoid having to restart them. Or you can kill them when you no longer are using them.
\end{enumerate}
\begin{description}
\item[Project SMP cpus] although this field is not Render Farm specific, it is useful for Cinelerra to have the CPU count and for using multiple threads.
\item[Use render farm] check this to turn on the render farm option. Once checked ALL rendering will be done via the farm including the usual Render (\texttt{Shift-R}). You may want to turn if off for small jobs.
- \item[Nodes listbox] displays all the nodes on the render farm and shows which ones are currently enabled. The Nodes listbox has 4 columns --- \texttt{On}, \texttt{Hostname}, \texttt{Port}, \texttt{Framerate} --- which show the current values. An \texttt{X} in the \texttt{On} designates that that host is currently enabled; \texttt{Hostname} shows the name of the host; \texttt{Port} shows the port number that host uses; and \texttt{Framerate} will either be zero initially or the current framerate value.
+ \item[Nodes listbox] displays all the nodes on the render farm and shows which ones are currently enabled. The Nodes listbox has 4 columns -- On, Hostname, Port, Framerate -- which show the current values. An \textit{X} in the \textit{On} designates that that host is currently enabled; \textit{Hostname} shows the name of the host; \textit{Port} shows the port number that host uses; and \textit{Framerate} will either be zero initially or the current framerate value.
\item[Hostname] this field is used to edit the hostname of an existing node or enter a new node.
\item[Port] keyin the port number of an existing or new node here. You can also type in a range of port numbers using a hyphen, for example $1501-1505$ when you need to add many.
- \item[Apply Changes] this will allow you to edit an existing node and to then commit the changes to hostname and port. The changes will not be committed if you do not click the \texttt{OK} button.
+ \item[Apply Changes] this will allow you to edit an existing node and to then commit the changes to hostname and port. The changes will not be committed if you do not click the OK button.
\item[Add Nodes] Create a new node with the hostname and port settings.
\item[Sort nodes] sorts the nodes list based on the hostname.
\item[Delete Nodes] deletes whatever node is highlighted in the nodes list. You can highlight several at once to have them all deleted.
\item[Client Watchdog Timeout] a default value of $15$ seconds is used here and the tumbler increments by $15$ seconds. A value of $0$ (zero) disables the watchdog so that if you have a slow client, it will not kill the render job while waiting for that client to respond.
\item[Total jobs to create] determines the number of jobs to dispatch to the render farm. Total jobs is used to divide a render job into that specified number of tasks. Each background job is assigned a timeline segment to process. The render farm software tries to process all of the rendering in parallel so that several computers can be used to render the results.
- To start, if you have computers of similar speed, a good number for \texttt{Total jobs to create} is the number of computers multiplied by $3$. You will want to adjust this according to the capabilities of your computers and after viewing the framerates. Multiply them by $1$ to have one job dispatched for every node. If you have $10$ client nodes and one master node, specify $33$ to have a well balanced render farm.
- \item[(overridden if new file at each label is checked)] instead of the number of jobs being set to \texttt{Total jobs to create}, there will be a job created for each labeled section. If in the render menu, the option \texttt{Create new file at each label} is selected when no labels exist, only one job will be created. It may be quite advantageous to set labels at certain points in the video to ensure that a key portion of the video will not be split into two different jobs.
+ To start, if you have computers of similar speed, a good number for \textit{Total jobs to create} is the number of computers multiplied by $3$. You will want to adjust this according to the capabilities of your computers and after viewing the framerates. Multiply them by $1$ to have one job dispatched for every node. If you have $10$ client nodes and one master node, specify $33$ to have a well balanced render farm.
+ \item[(overridden if new file at each label is checked)] instead of the number of jobs being set to \textit{Total jobs to create}, there will be a job created for each labeled section. If in the render menu, the option \textit{Create new file at each label} is selected when no labels exist, only one job will be created. It may be quite advantageous to set labels at certain points in the video to ensure that a key portion of the video will not be split into two different jobs.
\item[Reset rates] sets the framerate for all the nodes to $0$. Frame rates are used to scale job sizes based on CPU speed of the node. Frame rates are calculated only when render farm is enabled.
\end{description}
-Framerates can really affect how the Render Farm works. The first time you use the render farm all of the rates are displayed as $0$ in the \texttt{Settings $\rightarrow$ Prefe\-rences}, Performance tab in the Nodes box. As rendering occurs, all of the nodes send back framerate values to the master node and the preferences page is updated with these values. A rate accumulates based on speed. Once all nodes have a rate of non-zero, the program gives out less work to lower rated nodes in an effort to make the total time for the render to be almost constant.
-Initially, when the framerate scaling values are zero, the program just uses package length --- render size
-divided by the number of packages to portion out the work (if not labels). If something goes wrong or the rates become suspect, then all of the rest of the work will be dumped into the last job. When this happens, you really should \texttt{reset rates} for the next render farm session to restart with a good balance.
+Framerates can really affect how the Render Farm works. The first time you use the render farm all of the rates are displayed as $0$ in the \texttt{Settings $\rightarrow$ Preferences}, Performance tab in the Nodes box. As rendering occurs, all of the nodes send back framerate values to the master node and the preferences page is updated with these values. A rate accumulates based on speed. Once all nodes have a rate of non-zero, the program gives out less work to lower rated nodes in an effort to make the total time for the render to be almost constant.
+Initially, when the framerate scaling values are zero, the program just uses package length -- render size
+divided by the number of packages to portion out the work (if not labels). If something goes wrong or the rates become suspect, then all of the rest of the work will be dumped into the last job. When this happens, you really should \textit{reset rates} for the next render farm session to restart with a good balance.
\begin{lstlisting}[language=bash,numbers=none]
{cinelerra pathname} -h #displays some of the options.
\begin{description}
\item[Set up Cinelerra] A Cinelerra render farm is organized into a master node and any number of client nodes. The master node is the computer which is running the gui. The client nodes are anywhere else on the network with Cinelerra installed and are run from the command line. Before you start the master node for Cinelerra, you need to set up a shared filesystem on the disk storage node as this is the node that will have the common volume where all the data will be stored.
The location of the project and its files should be the same in the client computers as in the master computer and to avoid problems of permissions, it is better to use the same user in master and clients.
- For example, if you have the project in \texttt{/home /<user>/project-video} you must create the same directory path on the clients, but empty. Sharing the directory of the location of your project on the master computer can be done with NFS as described next. Alternatively, you can look up on the internet how to use Samba to share a directory.
+ For example, if you have the project in \texttt{/home/<user>/project-video} you must create the same directory path on the clients, but empty. Sharing the directory of the location of your project on the master computer can be done with NFS as described next. Alternatively, you can look up on the internet how to use Samba to share a directory.
\item[Create a shared filesystem and mount using NFS] All nodes in the render farm should use the same filesystem with the same paths to the project files on all of the master and client nodes. This is easiest to do by setting up an NFS shared disk system.
\begin{enumerate}
\item On each of the computers, install the nfs software if not already installed. For example, on Debian 9
icon or by typing the following command on the terminal screen: \texttt{/{cinelerra\_path}/cin}.
\item Use the file pulldown \texttt{Settings $\rightarrow$ Preferences}, the Performance tab, to set up your Render Farm
options in the Render Farm pane.
- \item Check the \texttt{Use render farm} option. By default, once you enable the option of Render Farm, rendering is usually done using the render farm. Batch rendering can be done locally, or farmed.
+ \item Check the \textit{Use render farm} option. By default, once you enable the option of Render Farm, rendering is usually done using the render farm. Batch rendering can be done locally, or farmed.
\item Add the hostname or the IP address of each of the client nodes in the Hostname textbox and the port
number that you want to use in the Port textbox. You can make sure a port number is not already in
use by keying in on the command line:
\begin{lstlisting}[language=bash,numbers=none]
$ netstat -n -l -4 --protocol inet
\end{lstlisting}
- Next, click on the \texttt{Add Nodes}
+ Next, click on the \textit{Add Nodes}
button and then you will see that host appear in the Nodes list box to the right. The \texttt{X} in the first
column of the nodes box denotes that the node is active. To review the \textit{standard} port allocations,
check the \texttt{/etc/services} file.
- \item Enter the total jobs that you would like to be used in the \texttt{Total job} textbox.
+ \item Enter the total jobs that you would like to be used in the \textit{Total job} textbox.
\item The default watchdog timer initial state is usually just fine but can be adjusted later if needed.
- \item Click \texttt{OK} on the Preferences window when done.
+ \item Click OK on the Preferences window when done.
\end{enumerate}
\item[Create Workflow] While working on the master computer, it is recommended that you keep all the resources being used on the same shared disk. Load your video/audio piece and do your editing and preparation. Add any desired plugins, such as a Title, to fine-tune your work. You want to make sure your video is ready to be rendered into the final product.
\item[Start the Client Nodes] To start up the client nodes run Cinelerra from the command line on each of the client computers using the following command:
\begin{lstlisting}[language=bash,numbers=none]
or n in `seq 1501 1505`; do cin -d $n; done
\end{lstlisting}
- \item[Render Using Render Farm] After you have followed the preceding steps, you are ready to use the render farm. Click on File $\rightarrow$ Render\dots which opens the render dialog. The most important point here is to use for \texttt{the Output path / Select a file to render to} a path/file name that is on the shared volume that is also mounted on the clients. Click on \texttt{OK} to render. The cinelerra program divides the timeline into the number of jobs specified by the user. These jobs are then dispatched to the various nodes depending upon the load balance. The first segment will always render on the master node and the other segments will be farmed out to the render nodes. Batch Rendering, as well as BD/DVD rendering, may use the render farm. Each line in the batchbay can enable/disable the render farm. Typically, video can be rendered into many file segments and concatenated, but normally audio is rendered as one monolithic file (not farmed).
+ \item[Render Using Render Farm] After you have followed the preceding steps, you are ready to use the render farm. Click on \texttt{File $\rightarrow$ Render}\dots which opens the render dialog. The most important point here is to use for \textit{the Output path / Select a file to render to} a path/file name that is on the shared volume that is also mounted on the clients. Click on OK to render. The cinelerra program divides the timeline into the number of jobs specified by the user. These jobs are then dispatched to the various nodes depending upon the load balance. The first segment will always render on the master node and the other segments will be farmed out to the render nodes. Batch Rendering, as well as BD/DVD rendering, may use the render farm. Each line in the batchbay can enable/disable the render farm. Typically, video can be rendered into many file segments and concatenated, but normally audio is rendered as one monolithic file (not farmed).
- Another performance feature which can use the Render Farm is \textit{Background Rendering}. This is also enabled on the Performance preferences tab. The background render function generates a set of image files by pre-rendering the timeline data on the fly. As the timeline is update by editing, the image data is re-rendered to a \texttt{background render} storage path. The Render Farm will be used for this operation if it is enabled at the same time as the \texttt{background render} feature.
- \item[Assemble the Output Files] Once all of the computer jobs are complete, you can put the output files together by using the shell script, RenderMux (from the menubar \texttt{scripts} button just above FF), if the files were rendered using ffmpeg, or you can load these by creating a new track and specifying concatenate to existing tracks in the load dialog in the correct numerical order. File types which support direct copy can be concatenated into a single file by rendering to the same file format with render farm disabled as long as the track dimensions, output dimensions, and asset dimensions are equal.
+ Another performance feature which can use the Render Farm is \textit{Background Rendering}. This is also enabled on the \texttt{Preferences $\rightarrow$ Performances} tab. The background render function generates a set of image files by pre-rendering the timeline data on the fly. As the timeline is update by editing, the image data is re-rendered to a \textit{background render} storage path. The Render Farm will be used for this operation if it is enabled at the same time as the \textit{background render} feature.
+ \item[Assemble the Output Files] Once all of the computer jobs are complete, you can put the output files together by using the shell script, \textit{RenderMux} (from the menubar \textit{scripts} button just above FF), if the files were rendered using ffmpeg, or you can load these by creating a new track and specifying concatenate to existing tracks in the load dialog in the correct numerical order. File types which support direct copy can be concatenated into a single file by rendering to the same file format with render farm disabled as long as the track dimensions, output dimensions, and asset dimensions are equal.
\end{description}
\subsection{Quick and Easy Render Farm Setup – The Buddy System Way}%
\begin{enumerate}
\item Make sure the Cinelerra program is installed on all of the computers and the network between the
main computer and the client computers is working. Use the same version if possible.
- \item Load your video file on the master node and use \texttt{File $\rightarrow$ Save as\dots} to save it to \texttt{/tmp}.
- \item Move that same file with the same name to \texttt{/tmp} on all of the client computers via rsh or sneaker net --- the ONLY reason you are doing this is to avoid having to set up NFS or Samba on the buddy client
+ \item Load your video file on the master node and use \texttt{File $\rightarrow$ Save as}\dots to save it to \texttt{/tmp}.
+ \item Move that same file with the same name to \texttt{/tmp} on all of the client computers via rsh or sneaker net -- the ONLY reason you are doing this is to avoid having to set up NFS or Samba on the buddy client
laptops that show up!
\item Edit your video/audio file to get it the way you want it and add the plugins, such as a Title, etc.
\item Check for a set of unused ports in \texttt{/etc/services} file, if username is root usually $401-425$ are
available; if non-root, then $1024-1079$.
- \item On the master computer, in Settings $\rightarrow$ Preferences, the Performance tab:
+ \item On the master computer, in \texttt{Settings $\rightarrow$ Preferences, Performance} tab:
\begin{itemize}
- \item check the box \texttt{Use render farm}
+ \item check the box \textit{Use render farm}
\item keyin localhost for the hostname or an ip address of the buddy client node
- \item keyin the desired port number for each client; and use \texttt{Add Node} for each host
+ \item keyin the desired port number for each client; and use \textit{Add Node} for each host
\item set total jobs to the number of client computers $+1$ multiplied by $3$ (or proportion to client speeds)
- \item check \texttt{OK}
+ \item check OK
\end{itemize}
\item On each buddy client, create a job for each port:
\begin{lstlisting}[language=bash,numbers=none]
\end{lstlisting}
\item On the master, bring up the render menu and name the output files, for example \texttt{/tmp/myoutput.mp4}.
\item The client nodes output results will be on their local \texttt{/tmp} filesystems so you will have to again use
- \texttt{rsh/ftp} or \texttt{usb sneaker net} to move them over to the main computer. File names will be the render
+ \textit{rsh/ftp} or \textit{usb sneaker net} to move them over to the main computer. File names will be the render
job output file name with port number tacked on (e.g. \texttt{/tmp/hb.mp4001...mp4005}).
\item Load the files by concatenate to existing track on the master node or use RenderMux shell script.
\end{enumerate}
\item If jobs are split in a key section on the timeline, you may wish to \textit{use labels} to prevent this.
\item For testing purposes, you may want to start a client in the foreground using \texttt{-f} instead of \texttt{-d}.
\item If one of the client computers is unavailable, check to see if there is an \texttt{X} to the left of the \texttt{nodename}
- in the Nodes listbox. Check the \texttt{X} to disable it which sets \texttt{On} to \texttt{Off}.
+ in the Nodes listbox. Check the \texttt{X} to disable it which sets ON to OFF.
\item A red message in the lower left hand corner of the main timeline that reads \textit{Failed to start render
farm} often means that the client cinelerra programs were not started up.
\item A message of \texttt{RenderFarmWatchdog::run 1 killing server thread \\ \#address\#} means that the client did
- not respond in time. You can adjust the timer in Settings $\rightarrow$ Preferences, Performance tab.
+ not respond in time. You can adjust the timer in \texttt{Settings $\rightarrow$ Preferences, Performance} tab.
\item When you get the message \texttt{RenderFarmClient::main\_loop: bind port 400: Address already in use}, use a different port.
\item A message of \texttt{RenderFarmServerThread::open\_client: unknown host abcompany} means that the
hostname of abcompany is not in \texttt{/etc/hosts} so you will have to add it or use the ip address instead.
- \item There are numerous error messages associated with file \texttt{open/close/status} or problems with the file
+ \item There are numerous error messages associated with file \textit{open/close/status} or problems with the file
that should be dealt with according to what is printed out.
\item Other illustrative messages may be shown such as: \texttt{RenderFarmClientThread:: run: Session finished}.
\end{itemize}
\subsection{Lossless Rendering}%
\label{sub:loseeless_rendering}
-Lossless means that in the compression of a file, all of the original data, every single bit, can be recovered when the file is uncompressed. This is different than \textit{lossy compression} where some data is permanently deleted so that when uncompressed, all of the original data can not be exactly recovered. Lossy is generally used for video and sound, where a certain amount of information loss will not be detected by most users or the playback hardware does not reproduce it anyway --- it is a trade-off between file size and image/sound quality. The files created will be more than 10 times larger than usual. Most players will not be able to decode lossless as the bitrate will overwhelm the device.
+Lossless means that in the compression of a file, all of the original data, every single bit, can be recovered when the file is uncompressed. This is different than \textit{lossy compression} where some data is permanently deleted so that when uncompressed, all of the original data can not be exactly recovered. Lossy is generally used for video and sound, where a certain amount of information loss will not be detected by most users or the playback hardware does not reproduce it anyway -- it is a trade-off between file size and image/sound quality. The files created will be more than 10 times larger than usual. Most players will not be able to decode lossless as the bitrate will overwhelm the device.
For x264 lossless compression to work, the only color model allowed here is yuv420p. Any other specification will be converted to yuv420p and the data will be modified. Also, keep in mind that the YUV color model has to be converted to RGB, which also modifies the data.
-To use x264 lossless rendering --- choose File format of \texttt{ffmpeg}, \texttt{m2ts} in the Render window. Click on the Video wrench, which brings up the Video Preset window and scroll down in the Compression filebox and choose \texttt{lossless.m2ts}. \textit{Preset=medium} is the default, but can be varied from \textit{ultrafast} (least amount of compression, but biggest file size) to \textit{veryslow} (most amount of compression, but still HUGE) in the parameter box where you see $qp=0$. This option is also available for bluray creation.
+To use x264 lossless rendering -- choose File format of ffmpeg, m2ts in the Render window. Click on the Video wrench, which brings up the Video Preset window and scroll down in the Compression filebox and choose \texttt{lossless.m2ts}. \textit{Preset=medium} is the default, but can be varied from \textit{ultrafast} (least amount of compression, but biggest file size) to \textit{veryslow} (most amount of compression, but still HUGE) in the parameter box where you see $qp=0$. This option is also available for bluray creation.
\subsection{Extra “cin\_” Options for Render with FFmpeg}%
\label{sub:extra_cin_option_ffmpeg}
\begin{itemize}
\item The \textit{Bitrate}, \textit{Quality}, and \textit{Pixels} fields are only updated when the Video Options are reloaded. This
occurs when you either change the ffmpeg file format, or video presets compression fields.
- \item If the video options preset has \texttt{cin\_pix\_fmt} defined, its value will be loaded as the default. If you
+ \item If the video options preset has \textit{cin\_pix\_fmt} defined, its value will be loaded as the default. If you
override the default, the value you specify will be used.
- \item If the video options preset does not have \texttt{cin\_pix\_fmt}, the default pixel format will be computed by ffmpeg (\texttt{avcodec\_find\_best\_pix\_fmt\_of\_list}), using the session format as the source choice. The
+ \item If the video options preset does not have \textit{cin\_pix\_fmt}, the default pixel format will be computed by ffmpeg (\textit{avcodec\_find\_best\_pix\_fmt\_of\_list}), using the session format as the source choice. The
\textit{best} is usually the format which is most similar in color and depth.
- \item If no choices are available, \texttt{yuv420p} for video will be used.
+ \item If no choices are available, yuv420p for video will be used.
\item You can also specify ffmpeg pixel formats which are not in the list. The list is provided by ffmpeg as input selection, but is more like suggestions than fact. For example, the raw formats can take almost any format, but the rawvideo codec actually specifies no legal formats.
\end{itemize}
-\noindent Some option files provide \texttt{cin\_pix\_fmt} to suggest a choice for good quality output or to prevent parameter errors when the other provided parameters conflict with the \textit{best} pixel format. This is the case in \texttt{faststart\_h264.mp4} where the \textit{profile=high} parameter dictates pixel format must be \texttt{yuv420p}.
+\noindent Some option files provide \textit{cin\_pix\_fmt} to suggest a choice for good quality output or to prevent parameter errors when the other provided parameters conflict with the \textit{best} pixel format. This is the case in \texttt{faststart\_h264.mp4} where the \textit{profile=high} parameter dictates pixel format must be \texttt{yuv420p}.
-\paragraph{cin\_bitrate} If you specify the bitrate, you can not specify the quality.
-Example: \texttt{cin\_bitrate=2000000}
+\paragraph{cin\_bitrate} If you specify the bitrate, you can not specify the quality.\\
+Example: \textit{cin\_bitrate=2000000}
-\paragraph{cin\_quality} If you specify the quality, you can not specify the bitrate.
-Example: \texttt{cin\_quality=7}
+\paragraph{cin\_quality} If you specify the quality, you can not specify the bitrate.\\
+Example: \textit{cin\_quality=7}
-\paragraph{cin\_stats\_filename} This parameter is useful for 2 pass operations.
+\paragraph{cin\_stats\_filename} This parameter is useful for 2 pass operations.\\
Example: \texttt{cin\_stats\_filename /tmp/cin\_video\_vp9\_webm}
-\paragraph{cin\_sample\_fmt} For audio the preset sample format default is computed in a similar way as stated above for video or can be set with the \texttt{cin\_sample\_fmt} parameter (figure~\ref{fig:audio}). If no choices are provided, s16 will be used.
-Example: \texttt{cin\_sample\_fmt=s16}
+\paragraph{cin\_sample\_fmt} For audio the preset sample format default is computed in a similar way as stated above for video or can be set with the \textit{cin\_sample\_fmt} parameter (figure~\ref{fig:audio}). If no choices are provided, s16 will be used.\\
+Example: \textit{cin\_sample\_fmt=s16}
\begin{figure}[htpb]
\centering
- \includegraphics[width=0.6\linewidth]{images/audio.png}
+ \includegraphics[width=0.55\linewidth]{images/audio.png}
\caption{Render menu showing where Samples is}
\label{fig:audio}
\end{figure}
\subsection{Two-pass Encoding with FFmpeg}%
\label{sub:two_pass_encoding_ffmpeg}
-In Cinelerra for two-pass, you need to run ffmpeg twice, with the same settings, except for designating the options of pass 1 for the first pass and then pass 2. In pass 1, a logfile that ffmpeg needs for the second pass is created. In pass 1 the audio codec should be specified that will be used in pass 2. For more information on ffmpeg 2-pass, check \url{https://trac.ffmpeg.org/wiki/Encode/H.264}. Different libraries may have different requirements and you will probably have to determine this by looking online at ffmpeg or looking directly at that code.
+In Cinelerra for two-pass, you need to run ffmpeg twice, with the same settings, except for designating the options of pass 1 for the first pass and then pass 2. In pass 1, a logfile that ffmpeg needs for the second pass is created. In pass 1 the audio codec should be specified that will be used in pass 2. For more information on ffmpeg 2-pass, check {\small \url{https://trac.ffmpeg.org/wiki/Encode/H.264}}. Different libraries may have different requirements and you will probably have to determine this by looking online at ffmpeg or looking directly at that code.
This 2 line ffmpeg 2-pass operation can be functionally duplicated in Cinelerra in the steps below them:
\end{lstlisting}
\begin{enumerate}
- \item After you have completed your editing, do a Save Session with \texttt{File $\rightarrow$ Save as\dots}
+ \item After you have completed your editing, do a Save Session with \texttt{File $\rightarrow$ Save as}\dots
Before starting, be sure your session is ready for batch render. That is, positioned at the beginning and nothing selected.
- \item Bring up \texttt{File $\rightarrow$ Batch Render\dots} where you will do the setup.
+ \item Bring up \texttt{File $\rightarrow$ Batch Render}\dots where you will do the setup.
\item Click on the \textit{Delete} box to remove old jobs highlighted in the bottom listbox.
\begin{itemize}
- \item For the \texttt{File Format} choose ffmpeg and mp4 for the type.
- \item Set \texttt{Output path} to the path and filename for the render output file.
- \item Click on \texttt{Use Current EDL} to use the designated EDL Path file.
- \item Click on \texttt{New} and you will see a new highlighted job show up in the listbox at the bottom.
+ \item For the \textit{File Format} choose ffmpeg and mp4 for the type.
+ \item Set \textit{Output path} to the path and filename for the render output file.
+ \item Click on \textit{Use Current EDL} to use the designated EDL Path file.
+ \item Click on \textit{New} and you will see a new highlighted job show up in the listbox at the bottom.
\item Use the Audio wrench to set bitrate to $128000$ ($128k$ as in ffmpeg example above).
- \item Click checkmark \texttt{OK}. Open the video tools with the video wrench.
- \item Set the Video Compression to h264.mp4 (as seen in the example).
+ \item Click checkmark OK. Open the video tools with the video wrench.
+ \item Set the Video Compression to \textit{h264.mp4} (as seen in the example).
\item Set the bitrate to $2600000$ ($2600k$ as in ffmpeg example above).
\item Add the following 2 lines after the first line:
\begin{lstlisting}[language=bash,numbers=none]
flags +pass1
passlogfile /tmp/{temporary log file name}.log
\end{lstlisting}
- Click checkmark \texttt{OK}.
+ Click checkmark OK.
\end{itemize}
- \item Click on \texttt{New} to create the second pass job. You will see this second job in the listbox below.
+ \item Click on \textit{New} to create the second pass job. You will see this second job in the listbox below.
Use the Video wrench and change pass1 to pass2 as follows.
\begin{lstlisting}[language=bash,numbers=none]
flags +pass2
\end{lstlisting}
- \item Click checkmark \texttt{OK}.
- \item Click on the \texttt{Start} box and watch it go!
- \item You can now check the output file for results. At the time this was documented, \texttt{rc=2pass} will be
+ \item Click checkmark OK.
+ \item Click on the \textit{Start} box and watch it go!
+ \item You can now check the output file for results. At the time this was documented, \textit{rc=2pass} will be
in the output.
\end{enumerate}
-If you need to re-render this, the Batch Render will still be set up but you have to click on the \texttt{Enabled} column in the listbox to re-enable the jobs to run which puts an X there. Click Start again. You can reuse batch job using the \texttt{save jobs} and \texttt{load jobs} buttons in the batch render dialog.
+If you need to re-render this, the Batch Render will still be set up but you have to click on the \textit{Enabled} column in the listbox to re-enable the jobs to run which puts an X there. Click Start again. You can reuse batch job using the \textit{save jobs} and \textit{load jobs} buttons in the batch render dialog.
-\paragraph{Render shortcuts for webm, h264, h265} are available by using the option files that are already set up for this purpose. Use the render menu as usual, with ffmpeg/mp4, choose h264 or h265 \texttt{pass1of2\_h26x} for the video and \texttt{passes1and\-2\_h26x} for the audio;
-with ffmpeg/webm, choose \texttt{pass1of2\_vp9}. When that is finished, you will have to use the render menu again and this time for video, choose \texttt{pass2of2\_h26x} or \texttt{pass2of2\_vp9}. The logfile is hard coded in the options file so will write over any currently existing logfile if you do not change it before you start the render.
+\paragraph{Render shortcuts for webm, h264, h265} are available by using the option files that are already set up for this purpose. Use the render menu as usual, with ffmpeg/mp4, choose h264 or h265 \textit{pass1of2\_h26x} for the video and \textit{passes1and\-2\_h26x} for the audio;
+with ffmpeg/webm, choose \textit{pass1of2\_vp9}. When that is finished, you will have to use the render menu again and this time for video, choose \textit{pass2of2\_h26x} or \textit{pass2of2\_vp9}. The logfile is hard coded in the options file so will write over any currently existing logfile if you do not change it before you start the render.
-\paragraph{Requirements for some other libraries} ~\\ (used instead of \texttt{flags +pass1} \& \texttt{passlogfile}):
+\paragraph{Requirements for some other libraries} ~\\ (used instead of \textit{flags +pass1} \& \textit{passlogfile}):
\begin{description}
\item[x265:] add this line:
\begin{lstlisting}[language=bash,numbers=none]
x265-params=pass=1:stats=/tmp/{temporary log file name}.log
\end{lstlisting}
- at the time this document was written, you should see in the output: \\ \texttt{stats-read=2}
+ at the time this document was written, you should see in the output: \\ \textit{stats-read=2}
\item[libvpx-vp9, xvid, and huffyuv:]~
\end{lstlisting}
\end{description}
-\noindent \textit{NOTE:} for vp9, the best Pixels is \texttt{gbrp}
+\textit{NOTE:} for vp9, the best Pixels is \textit{gbrp}
\subsection{Use case: High Efficiency Video Coding (HEVC)}%
\label{sub:use_case_hevc}
The following example is HD and FullHD oriented and produces a
picture quality similar to the Blu-ray with some limitations.
-As container Matroska (.mkv) is used, but also mp4 and others are
+As container Matroska (\texttt{.mkv}) is used, but also mp4 and others are
possible.
\vspace{2ex} \begin{lstlisting}[language=bash,numbers=none]
\noindent \textit{NOTE:}
A CRF of 16 delivers satisfactory results in most cases. However, if
-the video material is really \emph{grainy}, a CRF~16 can lead to unwanted large files. In this case, a trial export of perhaps one minute should be performed. The resulting bit rate can be used to correct the CRF to 17,\,18,\,19\ldots --- remember, a CRF of 0 means lossless, the higher the number the stronger the lossy compression. The approximate calculation of the final file size can be extrapolated from the sample export.
+the video material is really \emph{grainy}, a CRF~16 can lead to unwanted large files. In this case, a trial export of perhaps one minute should be performed. The resulting bit rate can be used to correct the CRF to 17,\,18,\,19\ldots -- remember, a CRF of 0 means lossless, the higher the number the stronger the lossy compression. The approximate calculation of the final file size can be extrapolated from the sample export.
The color space information must be used explicitly so that it can
be included in the video. Cinelerra\,GG or FFmpeg does not write it
\end{lstlisting}
load your video and do your editing
\item set up your Render (\texttt{Shift-R}), you can choose a raw format such as \textit{yuv} or \textit{rgb}
- \item for the filename \texttt{Select a file to render to}, use the named pipe as created in step 1 (\texttt{/tmp/piper.yuv})
- \item for \texttt{Insertion Strategy}, you will want to make sure to select \textit{insert nothing}
- \item click for \texttt{OK} on the green checkmark.(the cinelerra gui will look like it is hanging while waiting for a command line to use the pipe.)
+ \item for the filename \textit{Select a file to render to}, use the named pipe as created in step 1 (\texttt{/tmp/piper.yuv})
+ \item for \textit{Insertion Strategy}, you will want to make sure to select \textit{insert nothing}
+ \item click for OK on the green checkmark.(the cinelerra gui will look like it is hanging while waiting for a command line to use the pipe.)
\item on the terminal window, keyin your command, for example:
\begin{lstlisting}[language=bash,numbers=none]
/mnt0/build5/cinelerra-5.1/thirdparty/ffmpeg-3.4.1/ffmpeg -f rawvideo -pixel_format yuv420p \ -video_size 1280x720 -framerate 30000/1001 -i /tmp/piper.yuv /tmp/pys.mov
\end{lstlisting}
\end{enumerate}
-A slightly different option can be used instead that may be more familiar to some. In the render menu after choosing the File Format of \textit{ffmpeg}, use the pulldown to choose \textit{y4m} as the file type. This choice results in putting a header on the rendered output with some pertinent information that can be used for ffmpeg processing thus alleviating the requirement for \textit{pixel\_format}, \textit{video\_size}, and \textit{framerate} on the ffmpeg command line. In this case the format is \texttt{yuv4mpegpipe} instead of \texttt{rawvideo}. An example command line would look as follows (assuming the created pipe is called \texttt{piper.y4m}):
+A slightly different option can be used instead that may be more familiar to some. In the render menu after choosing the File Format of \textit{ffmpeg}, use the pulldown to choose \textit{y4m} as the file type. This choice results in putting a header on the rendered output with some pertinent information that can be used for ffmpeg processing thus alleviating the requirement for \textit{pixel\_format}, \textit{video\_size}, and \textit{framerate} on the ffmpeg command line. In this case the format is \textit{yuv4mpegpipe} instead of \textit{rawvideo}. An example command line would look as follows (assuming the created pipe is called \texttt{piper.y4m}):
\begin{lstlisting}[language=bash,numbers=none]
ffmpeg -f yuv4mpegpipe -i /tmp/piper.y4m -vcodec libx264 /tmp/test.mp4
\end{lstlisting}
\subsection{Faststart Option for MOV type files}%
\label{sub:faststart_option_mov0}
-If you have mov video and want to be able to start playing without having to first load the entire video, \texttt{-movflags=+faststart} is needed for ffmpeg to put the meta-data, known as the \textit{moov atom}, at the beginning of the file. Otherwise, ffmpeg puts this atom at the end of the video file which means you have to wait to play until the whole video is loaded. Or worse yet, if the file becomes damaged in the middle and you can not get to the end, you won’t be able to play anything.
+If you have mov video and want to be able to start playing without having to first load the entire video, \textit{-movflags=+faststart} is needed for ffmpeg to put the meta-data, known as the \textit{moov atom}, at the beginning of the file. Otherwise, ffmpeg puts this atom at the end of the video file which means you have to wait to play until the whole video is loaded. Or worse yet, if the file becomes damaged in the middle and you can not get to the end, you won’t be able to play anything.
-Now you can have the \textit{moov atom} put on the front of the file (automatically via a second pass). To do this, when rendering using ffmpeg \& either the mp4 or qt format/container, click on the video/audio wrenches and choose \texttt{faststart\_h264}. With the \texttt{qt} format, settings will just be the default whereas the \texttt{mp4} format uses the highest quality and lowest file size as possible, but you can easily modify these options in the associated Video Preset textbox.
+Now you can have the \textit{moov atom} put on the front of the file (automatically via a second pass). To do this, when rendering using ffmpeg \& either the mp4 or qt format/container, click on the video/audio wrenches and choose \textit{faststart\_h264}. With the \textit{qt} format, settings will just be the default whereas the \textit{mp4} format uses the highest quality and lowest file size as possible, but you can easily modify these options in the associated Video Preset textbox.
\chapter{Performance and other Tips}%
\label{cha:performance_tips}
-Performance and usability of Cinelerra are directly related to the software and video format being used in conjunction with your computer system hardware -- the number of CPUs and its speed, I/O bus speed, graphics card, and amount of available memory. A basic, less powerful system will be sufficient for users working with audio only or lower resolution video formats. Higher end computers will be needed when playing and working with higher resolution formats, like 1080p, 1440p and 2160p. Adding effects and several tracks of audio will require more cpu, memory, and various other resources to read, decode and play video.
+Performance of Cinelerra is related to the software and video format being used in conjunction with your computer system hardware -- the number of CPUs and its speed, I/O bus speed, graphics card, and amount of available memory. A basic, less powerful system will be sufficient for users working with audio only or lower resolution video formats. Higher end computers will be needed when playing and working with higher resolution formats, like 1080p or 4k. Adding effects and multiple tracks will require more cpu, memory, and various other resources to
+perform at an acceptable level.
-Perhaps the easiest method for determining if your performance could be improved is to look at the numerical value displayed as \textit{Framerate achieved}. Good performance means that when \texttt{Play every frame} is set in:
+Perhaps the easiest method for determining if your performance could be improved is to look at the numerical value displayed as \textit{Framerate achieved}. Good performance means that when \texttt{Play every frame} is set
+in \texttt{Settings $\rightarrow$ Preferences, Playback A tab}, the frames/second (frames per second or fps) in playback might be almost always at the maximum rate of your project setting and/or video frame rate. You can check this in \texttt{Settings $\rightarrow$ Preferences, Playback A}, by watching \textit{Framerate achieved} while playing forward. A higher number is better, up to the format frame rate of the video.
-\texttt{Settings $\rightarrow$ Preferences, Playback A tab}, the frames/second (frames per second or fps) in playback might be almost always at the maximum rate of your project setting and/or video frame rate. You can check this in \texttt{Settings $\rightarrow$ Preferences, Playback A}, by watching \textit{Framerate achieved} while playing forward. A higher number is better, up to the format frame rate of the video.
-
-Some hardware considerations are listed here:
+Some computer hardware factors to consider for better performance are listed here:
\begin{itemize}
\item Multi-core and more SMP processors greatly improve Cinelerra speed by making use of threads.
\item A large amount of free memory available can help speed up operations by avoiding unnecessary disk
- swaps and keeping material easily accessible.
- \item Video editing can be quite I/O intensive. If you are going to produce long pieces in uncompressed or
- larger resolution formats, you should have plenty of fast access disk space.
+ swaps and keeping videos easily accessible in memory.
+ \item Video editing is almost always I/O intensive. To create longer running videos at high resolution
+ you will want to have a lot of disk space available on fast access disks.
\item Cinelerra benefits from OpenGL hardware acceleration. A good graphics card is worthwhile to have.
\item Multiple monitors really come in handy to increase productivity as you can see more information and
in bigger windows so you do not have to keep moving windows around.
VA-API, Video Acceleration API, is an open source library which provides both hardware accelerated video encoding and decoding for use mostly with Intel (and AMD) graphics boards.
-Currently only the most common codecs, such as MPEG-1, MPEG-2, MPEG-4, and H.264/MPEG-4, are accelerated/optimized by the graphics card to play these particular video formats efficiently. The other formats are not optimized so you will see no performance improvement since the CPU will handle them as before, just as if no hardware acceleration was activated. There are many different graphics cards and computer systems setup, so you will have to test which specific settings work best for you. So far this has been tested at least with Nvidia, Radeon, and Broadwell graphics boards on some AMD and Intel computers; depending on the graphics card, two to ten times higher processing speeds can be achieved. However, most graphic operations are single-threaded and may be slower as opposed to multiple CPUs, which frequently multi-thread many operations simultaneously.
+Currently only the most common codecs, such as MPEG-1, MPEG-2, MPEG-4, and H.264 /MPEG-4, are accelerated/optimized by the graphics card to play these particular video formats efficiently. The other formats are not optimized so you will see no performance improvement since the CPU will handle them as before, just as if no hardware acceleration was activated. There are many different graphics cards and computer systems setup, so you will have to test which specific settings work best for you. So far this has been tested at least with Nvidia, Radeon, and Broadwell graphics boards on some AMD and Intel computers; depending on the graphics card, two to ten times higher processing speeds can be achieved. However, most graphic operations are single-threaded so that
+performing the operations in the hardware may actually be slower than in software making use of multiple CPUs, which frequently multi-thread many operations simultaneously.
\subsection{GPU hardware decoding}%
\label{sub:gpu_hardware_decoding}
CIN_HW_DEV=vaapi ./cin # mostly for computers with Intel or AMD specific graphics hardware
\end{lstlisting}
-If you find that the environment variable setting is advantageous for your CinGG usage and you want to always use it, you can add it to your \texttt{\$HOME} directory \texttt{.profile} file which takes effect every time you log in. The line you would add would look something like this:
+If you find that the environment variable setting is advantageous for your CinGG usage and you want to always use it, you can add it in your \texttt{\$HOME} directory \texttt{.profile} file which takes effect every time you log in. The line you would add would look something like this:
\begin{lstlisting}[language=bash,numbers=none]
export CIN_HW_DEV=vdpau
It might be more difficult to analyze problems as a result of using the GPU because of the wide variation in hardware. When you do not set the \texttt{CIN\_HW\_DEV} environment variable, the code will work exactly as before since this feature is self-contained.
-In addition to the environment variable, there is a \texttt{Settings $\rightarrow$ Preferences, Performance tab, Use HW device} flag with a pulldown to set up \textit{none, vdpau, vaapi,} or \textit{cuda}. To ensure it takes effect, it is best to set it the way you want, quit out of Cinelerra and then restart. Its current purpose is for flexibility, but there is a possibility that it might eventually take the place of \texttt{CIN\_HW\_DEV} -- both are not needed.
+There is also a \texttt{Settings $\rightarrow$ Preferences, Performance tab, Use HW device} flag
+with a pulldown to set up \textit{none, vdpau, vaapi,} or \textit{cuda}. To ensure it takes effect, it is best to set it the way you want, quit out of Cinelerra and then restart. Its current purpose is for flexibility, but there is a possibility that it might eventually take the place of \texttt{CIN\_HW\_DEV} -- both are not needed.
--- Precedence of the decode hardware acceleration settings are:
+Precedence of the decode hardware acceleration settings are:
-- \texttt{yourfile.opts} is checked first so is of the highest priority; special .opts usage is described below
\label{ssub:possible_improvements_differences}
\begin{enumerate}
- \item The Frames Per Second (FPS) in playback might be mostly at the maximum rate. You can check
+ \item The Frames Per Second (FPS) in playback might usually be at the maximum rate. You can check
this in \texttt{Settings $\rightarrow$ Preferences, Playback A}, looking at \texttt{Framerate achieved}; the higher, the better.
\item Percent of the CPU used should be less, thus saving more CPU for other operations.
\item Some users get the the impression that playing seems smoother.
\begin{lstlisting}[language=bash,numbers=none]
cin_hw_dev=none
\end{lstlisting}
-
Conversely, if you have a bunch of files in your project, like dnxhd format, that are not hardware accelerated, but you have an accompanying large file of type .mp4 for which you would like the hardware acceleration, you can leave the \texttt{CIN\_HW\_DEV} variable unset (that is, do not use it) and just create an .opts file containing the line:
+
\begin{lstlisting}[language=bash,numbers=none]
cin_hw_dev=vdpau
\end{lstlisting}
\end{tabular}
\end{center}
-\noindent Best is the least amount of CPU usage. Note that in this case, using X11-OpenGL is better
+\noindent Best is the least amount of CPU usage. Note that in this Case 1, using the X11-OpenGL video driver is
+better than using the X11 video driver.
\subsubsection*{Case 2:}%
\label{ssub:case_2}
\end{tabular}
\end{center}
-\noindent Best is the least amount of CPU usage. Note that in this case, using X11 is better
+\noindent Best is the least amount of CPU usage. Note that in this Case 2, using the X11 video driver is better
+than using the X11-OpenGL video driver.
Older graphics cards or non-performing graphics cards will probably bring only a small amount of improvement or no speed advantage at all. You can check to see if vdpau is implemented for your specific Nvidia board at:
-\url{https://download.nvidia.com/XFree86/Linux-x86_64/304.137/README/supportedchips.html}
+\small \url{https://download.nvidia.com/XFree86/Linux-x86_64/304.137/README/supportedchips.html}
And, you can see what your specific hardware and software might support by running either \texttt{vainfo} or \texttt{vdpauinfo} from the command line. Partial examples of each are shown below.
\item[mjpeg\_vaapi.mp4] error message of \textit{open failed with mjpeg\_vaapi$\dots$} on above computer
\item[hevc\_vaapi.mp4] error message of \textit{open failed with hevc\_vaapi$\dots$} on above computer
\end{description}
-
Other option files can be added as needed for your specific hardware if it is known to work for you, such as VP8 and VP9. An example of the included Cinelerra’s \texttt{ffmpeg/video/h264\_vaapi.mp4} file (figure~\ref{fig:render-vaapi}):
+
\begin{lstlisting}[language=bash,numbers=none]
mp4 h264_vaapi
cin_hw_dev=vaapi
According to an online wiki, hardware encoders usually create output of lower quality than some software encoders like x264, but are much faster and use less CPU. Keep this in mind as you might want to set a higher bitrate to get output of similar visual quality.
Results of a particular test case performed on a Intel, 4-core computer, with Broadwell Graphics using an mp4 input video/audio file with dimensions of
-
-$1440x1080 / 29.97fps$ is shown next (note, filename is \texttt{tutorial.mp4}). This may very well be a \textit{best case} scenario! But clearly, at least on this computer with only 4 cores, the hardware acceleration seems to be quite advantageous. A comparison of the 2 output files using \texttt{ydiff} (as described in Appendix C in the manual) shows no obvious defects.
+$1440x1080 / 29.97fps$ is shown next (note, filename is \texttt{tutorial.mp4}). This may very well be a \textit{best case} scenario! But clearly, at least on this computer with only 4 cores, the hardware acceleration seems to be quite advantageous. A comparison of the 2 output files using \texttt{ydiff} shows no obvious defects.
\begin{center}
\begin{tabular}{l|cccc}
\texttt{Settings $\rightarrow$ Preferences, tab Playback A}, set video driver to X11 and uncheck \texttt{use direct X11 render if possible}.
-\section{Proxy Settings}%
+\section{Proxy Settings and Transcode}%
\label{sec:proxy_settings}
-Working with videos that have large image geometry can greatly impede editing. Instead you can substitute \textit{proxies} which will create smaller video image files from the original file that can then be edited more quickly. When you are done working on this smaller scale, you will need to bring up the Proxy settings menu again, and change the Scale factor back to the Original size so that all of your edits/work take affect on that original higher quality video on the timeline. You can not nest clips while in a proxied state; you will get the error \textit{Nesting not allowed when proxy scale $\ne$ 1}.
+Working with videos that have large image geometry can greatly impede editing. Instead you can substitute \textit{proxies} which will create smaller video image files from the original file that can then be edited more quickly. When you are done working on this smaller scale, you will need to bring up the Proxy settings menu again, and change the Scale factor back to the Original size so that all of your edits/work take affect on that original higher quality video on the timeline.
-To use this feature, select \texttt{Settings $\rightarrow$ Proxy settings} and change the Scale factor from Original size to your downsized choice. You can choose ffmpeg as the File Format and a choice of various codecs associated with that. A good choice is the default of \texttt{mpeg} which can usually be quite fast. In addition, to modify values for that codec, click on the wrench icon. When you have completed your choices, just click \texttt{OK}, and then the video tracks will be rendered. This may take some time, but previous proxy renders will be reused. The proxy videos will be added to your assets in a separate Proxy folder, and the video track edits will use the proxies. Proxy downsizing renders all loaded tracks, but only work on the $1^{st}$ video layer of any multi-layer media. Rendered proxy media is saved in the same directory as the original media. As usual, you can delete proxy files from the project or disk in the Resources window if you no longer want to retain them.
+To use this feature, select \texttt{Settings $\rightarrow$ Proxy settings} and change the Scale factor from Original size to your downsized choice. You can choose ffmpeg as the File Format and a choice of various codecs associated with that. A good choice is the default of \texttt{mpeg} which can usually be quite fast. In addition, to modify values for that codec, click on the wrench icon. When you have completed your choices, just click \texttt{OK}, and then the video tracks will be rendered. This may take some time, but previous proxy renders will be reused.
+The proxy videos will be added to your assets in a separate Proxy folder, and the video track edits will use the proxies.
+The assets in both the Media folder and Proxy folder will look proxied when dragged to the Viewer although the scale may be different.
+Proxy downsizing renders all loaded tracks, but only work on the $1^{st}$ video layer of any multi-layer media. Rendered proxy media is saved in the same directory as the original media.
+However, if you proxy your session, the clips do not get proxied to the Proxy folder, but if you Drag and Drop the clip from the Clip folder to the Viewer or the Timeline, you will see that it too is proxied.
+As usual, you can delete proxy files from the project or disk in the Resources window if you no longer want to retain them.
+And you can save your project either as proxied or not.
+
+You can also nest clips while in a proxied state, but you can not drag the proxied nested clips
+to the viewer or the timeline.
+If you create proxies for Nested clips they will be saved in \$HOME/Videos unless you modify that in
+\texttt{Settings $\rightarrow$ Preferences, Interface tab}, Nested Proxy Path.
There are two ways that the proxy files can be used, with or without input scaling. When the proxy is done without rescaling, the Mask, Camera and Projector automations are re-scaled accordingly. In this situation, the entire project will be re-sized so that the session is in the resized geometry. Not all plugins are useful when the project is rescaled, because the keyframe data must be in the original geometry. In this case, you can use the rescaler, by enabling \texttt{Use scaler (FFMPEG only)}. This has the added advantage that the project size does not change and the proxy media is down-scaled as usual and up-scaled on read-in, which means the project editing is done in full scale. Since decoding is done on smaller video, there is a time savings, but all rendering is done full scale. The main reason for using \textit{scaler} is that it does not change the image coordinate data, so that automation and plugin parameters will be in the original project geometry. This is not as fast as the first option, but is a performance gain, and may be needed if you are using plugins that need coordinate data such as the Title plugin. As noted, the scaler only works on ffmpeg video formats.
\label{fig:proxy-02}
\end{figure}
-There is also a convenient \texttt{Beep on done} checkbox included so that you can work on other tasks until there is an audible notify of completion.
+There is also a convenient \texttt{Beep on done volume} dial included so that you can work on other tasks until there is an audible notify of completion. The default volume is set to 0 for no audible notify.
A good choice for proxy settings with 1080p source video is:
More specific information on which plugins need to use scaler is provided here next. If the keyframe data uses coordinate data that is absolute, then the scaler should be used. If the data is normalized (like always $0-100\%$) then the proxy can be done without the scaler. The session geometry format, shown in \texttt{Settings $\rightarrow$ Format} as width x height, is changed if the scaler is not used to cause all of the data to be in the reduced format. If this affects the plugin operation, then scaler should be used. Examples of plugins that need the scaler are: Title, AutoScale, Scale, ScaleRatio, and Translate. Most others are safe to use without scaling.
+ This makes its so that you can save your project
+either as proxied or not.
+
+\textbf{Transcode}, an option under the Settings pulldown right next to the Proxy settings option, is a type of full resolution \textbf{1:1 Proxy}.
+The process of transcoding works directly from the resource; it is independent of the timeline.
+All of the loaded asset media will be converted, that is, rendered in the selected format and loaded onto the timeline.
+Menu choices besides the usual File Format and File Type include: Tag suffix (to add to media filename), Remove originals from project, Into Nested Proxy directory
+ (an option to have the file saved here instead of the location of the original media), and Beep on done volume.
+
+The settings of the project have an effect, for example the dimensions are taken into account. The resulting files are also larger than if they were created directly with ffmpeg.
+Transcode works for videos with or without audio and even single frame files, like png's.
+If you have a video file that also contains audio, and you convert only the video, the original audio will stay on the timeline if do not check "Remove originals from project". Or vice versa if audio converted and not video.
+Multiple stream media will only transcode the first stream (this would be like the TV channel recordings in the United States).
+You will get an error message if you already have a transcoded file in the selected format with the same suffix name and try to transcode it again with a different selection made - you will have to delete that file first. An example would be
+an already converted file that has both video and audio and now you request video only.
+
+The BIGGEST gain from using this is if you have media that is not "seekable", that is, you can play it from the beginning
+but can not move to another spot and have the audio or video play correctly. A video file with no keyframes makes seeking
+next to impossible, but then a Transcode generally adds these keyframes.
+
\section{Some Settings Parameter Values}%
\label{sec:settings_parameter_values}
There are several \textit{po} files for various languages to make Cinelerra more usable for non-English countries. A program, \texttt{xlat.C}, assists in providing several variations of text files that can be used in order to allow anyone to help make meaningful translations. All of the \textit{po} files are located in Cinelerra’s \texttt{/po} subdirectory. There are 3 different ways to proceed described below.
-Because Cinelerra frequently is changin, it is a good idea to start by building a new \texttt{cin.po} file which contains the latest messages/words in English to be translated, along with a comment line of the routine name and line number. To create this, run the following line from a window:
+Because Cinelerra frequently is changing, it is a good idea to start by building a new \texttt{cin.po} file which contains the latest messages/words in English to be translated, along with a comment line of the routine name and line number. To create this, run the following line from a window:
\begin{lstlisting}[language=bash,numbers=none]
/{your cinelerra directory}/po/xlat.sh > /tmp/cin.po
\end{lstlisting}
\begin{description}
- \item[Method 1] use the freely-available \textit{poedit} program to provide translations to the current \texttt{x.po} where x is your language such as fr.po, de.po, ru.po, etc. The drawback to this is that x.po files are not recreated monthly so they do not have all of the newest phrases included.
+ \item[Method 1] use the freely-available \textit{poedit} program to provide translations to the current \texttt{xx.po} where xx is your language such as fr.po, de.po, ru.po, etc. The drawback to this is that xx.po files are not recreated monthly so they do not have all of the newest phrases included.
\item[Method 2] using \textit{msgmerge} is probably the simplest method for user translation.
\end{description}
\begin{lstlisting}[language=bash,numbers=none]
/{your cinelerra directory}/po/xlat.sh > /tmp/cin.po # use /tmp as a temporary place
-cp /{your cinelerra directory}/po/x.po /tmp/x.po # substitute your language for x
-msgmerge -U /tmp/x.po /tmp/cin.po # x.po will be overwritten to include updates
+cp /{your cinelerra directory}/po/xx.po /tmp/xx.po # substitute your language for x
+msgmerge -U /tmp/xx.po /tmp/cin.po # xx.po will be overwritten to include updates
\end{lstlisting}
-Then use any editor or poedit to provide messages/words translations in the new x.po file.
+Then use any editor or poedit to provide messages/words translations in the new xx.po file.
\begin{description}
\item[Method 3 ] using \textit{xlat.C} program is the most versatile with a variety of features. When a non-existent language translation is first set up, you would want to use this methodology to get started.
\item \textit{xlat} = overlay translation. This is the most important use and is described next.
\end{enumerate}
-The xlat command line parameters specify a new cin.po template, usually created with xlat.sh, and a list of key/value files which are used to build a mapping for the desired translation. The mapping files are added to the mapping in the order they appear on the command line, and any existing key is replaced with the newest definition; so typically the newest key/value data is last in the command parameters. Once the mapping is built the first parameter, the new po template, is scanned and the keys it contains are used to find the latest mapping in the key/value files. The new value replaces the existing value in the template. For example, to overlay a new map onto an existing po:
+The xlat command line parameters specify a new cin.po template, usually created with xlat.sh, and a list of key/value files which are used to build a mapping for the desired translation. The mapping files are added to the mapping in the order they appear on the command line, and any existing key is replaced with the newest definition; so typically the newest key/value data is last in the command parameters.
+Once the mapping is built, the first parameter which is the new po template is scanned and the keys it contains are used to find the latest mapping in the key/value files. The new value replaces the existing value in the template. For example, to overlay a new map onto an existing po using the Spanish es.po file and where cin.po represents the latest english words:
\begin{lstlisting}[language=bash,numbers=none]
c++ xlat.C
-./a.out po < xx.po > /tmp/xx.csv
-./a.out po < new.po > /tnp/new.csv
-./a.out xlat xx.po /tmp/xx.csv /tmp/new.csv > /tmp/new.po
+./a.out po < es.po > /tmp/es.csv
+./a.out po < cin.po > /tmp/cin.csv
+./a.out xlat cin.po /tmp/es.csv > /tmp/new_es.po
\end{lstlisting}
-The first run preserves the existing mapping of xx.po, the second creates new mappings from new.po, and the third merges the original and new mappings to create a po with new included/overriding xx.po.
+The first run preserves the existing mapping of es.po, the second creates new mappings from cin.po, and the third merges the original and new mappings to create a po with new included/overriding es.po.
\paragraph{NOTE:} some words and abbreviations can lead to ambiguous language translations. Therefore, the usage of C\_ and D\_ in the program code was added to represent Contextual and Definitional exceptions to the usual \_ and N\_ . You will see the following:
projects / goodguy / cin-manual-latex.git / commitdiff