Fix references for Installation.
[goodguy/cin-manual-latex.git] / parts / Rendering.tex
1 \chapter{Rendering}%
2 \label{cha:rendering}
3
4 Rendering takes a section of the timeline, performs all the editing, effects and compositing, and creates a new media file.  You can then delete all the source assets, play the rendered file, or bring it back into Cinelerra for more editing.   All rendering operations are based on a region of the timeline to be rendered.  You need to define this region on the timeline.  The rendering functions define the region based on a set of rules.  When a region is highlighted or in/out points are set, the affected region is rendered.  When no region is highlighted, everything after the insertion point is rendered.  By
5 positioning the insertion point at the beginning of a track and unsetting all in/out points, the entire track is rendered.  But you also have the choice to render \textit{one frame}.
6
7 \section{Single File Rendering}%
8 \label{sec:single_file_rendering}
9
10 Use the File pulldown and select Render to start the render dialog (figure~\ref{fig:render}).  Then choose the desired parameters.
11
12 \begin{figure}[htpb]
13     \centering
14     \includegraphics[width=0.7\linewidth]{images/render.png}
15     \caption{Example of the Render menu}
16     \label{fig:render}
17 \end{figure}
18
19 \begin{description}
20     \item[Select a file to render to:] enter the path and filename to write the rendered file to in the textbox below.
21     \item[File Format:] use the down arrow to see file format options.  For ffmpeg, which has its own set of options, you will then have to select an ffmpeg file type from the down arrow choices. The format of the file determines whether you can render audio or video or both.
22     \item[Render audio tracks:] check this toggle to generate audio tracks
23     \item[Render video tracks:] check this toggle to generate video tracks. The Render window will sometimes automatically update the Render Audio Tracks or Render Video Tracks checkbox as allowed by the chosen file format, but you should always check (figure~\ref{fig:render01}).  For example, if the PNG file format is selected, only the \textit{Render Video Tracks} will be checked.  Or if an ffmpeg format is chosen and the file format does not render audio, the \textit{Render Audio Tracks} will be unchecked. The invalid choices will be ghosted out.
24 \end{description}
25
26 \begin{figure}[htpb]
27     \centering
28     \includegraphics[width=0.7\linewidth]{images/render01.png}
29     \caption{Audio and Video tracks automatically checked for Pro file type}
30     \label{fig:render01}
31 \end{figure}
32
33 \begin{description}
34     \item[Wrench:] select the \textit{wrench} next to each toggle to set compression parameters.  If the file format can not store audio or video the compression parameters will be blank.  If \textit{Render audio tracks} or \textit{Render video tracks} is selected and the file format does not support it, trying to render will result in an error message.
35     \item[Create new file at each label] the option causes a new file to be created when every label in the timeline is encountered – a separate file for each.  This is useful for dividing long audio recordings into individual tracks.  When using the Render Farm (described later), \textit{Create new file at each label} causes one render farm job to be created at every label instead of using the internal load balancing algorithm to space jobs.   If the filename given in the render dialog has a 2 digit number in it, the 2 digit number is overwritten with a different incremental number for every output file. If no 2 digit number is given, Cinelerra automatically concatenates a number to the end of the given filename for every output file.
36     For example, in the filename \texttt{/movies/track01.wav} the $01$ would be overwritten for every output file. 
37     The filename \texttt{/movies/track.wav}; however, eventually would become \texttt{/movies/track.wav001} and so on.  
38     Filename regeneration is only used when either render farm mode is active or creating new files for every label is active.
39     \item[Render range:] choices are \textit{Project}, \textit{Selection}, \textit{In/Out points}, and \textit{One Frame} for single images like Tiff.  For these images, Render range will have \textit{One Frame} automatically checked and all of the others ghosted since nothing else makes sense (figure~\ref{fig:render02}).  This makes it easy to set the insertion point where you want the 1 frame to be rendered rather than having to precisely zoom in to set the in/out pointers.  Note that whichever Render range is checked, remains checked so that if \textit{One Frame} gets automatically checked, the next time you render it will still be checked and you will have to select a different one if desired.  That is why you should always check the settings.
40 \end{description}
41
42 \begin{figure}[htpb]
43     \centering
44     \includegraphics[width=0.7\linewidth]{images/render02.png}
45     \caption{Render menu displaying a PNG \textit{one frame} option}
46     \label{fig:render02}
47 \end{figure}
48
49 \begin{description}
50     \item[Beep on done:] as a convenience when a render is complete, check this box.  It gives you the chance to work on something else while waiting and still be immediately notified when the render is complete.
51     \item[Render Profile:] another convenience feature to take advantage of if you use specific render formats
52     frequently, is to save that profile for future usage without having to set it up again.
53     \item[Save Profile:] after setting up your render preference formats, use the save profile button to save it.
54     \item[Delete Profile:] if you want to delete a saved profile, highlight the one you no longer want and delete.
55     \item[Insertion strategy:] select an insertion mode from the available choices as seen when you click on the down arrow on the right hand side of the option. The insertion modes are the same as with loading files.  In the case if you select “insert nothing” the file will be written out to disk without changing the current project. For other insertion strategies be sure to prepare the timeline to have the output inserted at the right position before the rendering operation is finished. 
56     
57     Even if you only have audio or only have video rendered, a paste insertion strategy will behave like a normal paste operation, erasing any selected region of the timeline and pasting just the data that was rendered.  If you render only audio and have some video tracks armed, the video tracks will get truncated while the audio output is pasted into the audio tracks.
58 \end{description}
59
60 \section{Batch Rendering}%
61 \label{sec:batch_rendering}
62
63 Batch Rendering automates the rendering of audio/video files in that you can establish a set of job parameters, save them, and use them repeatedly.  It also allows for Cinelerra to be run by external programs, with no need for the user to manually interact with the user interface (figure~\ref{fig:batch01}).
64
65 If you want to render many projects to media files without having to constantly set up the render dialog for each one, batch rendering is a more efficient method of rendering.  In the Batch Render menu, you specify one or more Cinelerra project XML files, the EDL, to render and unique output files for each. (The EDL is the Edit Decision List or the set of changes to be applied to the project and media files.) Then Cinelerra loads each project file and renders it automatically. The project XML files, combined with the settings for rendering an output file, are called a batch.  This allows a large amount of media to be processed without user intervention.
66
67 \begin{figure}[htpb]
68     \centering
69     \includegraphics[width=0.8\linewidth]{images/batch01.png}
70     \caption{Example of the Batch Render menu}
71     \label{fig:batch01}
72 \end{figure}
73
74 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.
75
76 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.
77
78 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.
79
80 Set the \textit{Output path}, \textit{File format}, \textit{Audio}, \textit{Video}, and \textit{Create new file at each label} parameters as if you were rendering a single file.  These parameters apply to only one batch.  In addition to the standard rendering parameters, you must select the \textit{EDL Path} to be the project file (such as \texttt{ProjectA.xml}) that will be used in the batch job.  In this case, \textit{EDL Path} is not related in anyway with the EDL files as created by \texttt{File/Export EDL}.  In batch render mode the program will not overwrite an existing output file and will simply fail, so make sure that no files with the same name as the output files exist before starting.
81
82 If the batches to render list is empty or nothing is highlighted, click \texttt{New} to create a new batch. The new batch will contain all the parameters you just set.  Repeatedly press the \texttt{New} button to create more batches with the same parameters.  When you highlight any batch, you can edit the configuration on the top of the batch render window. The highlighted batch is always synchronized to the information displayed.  You can easily change the order in which the batch jobs are rendered, by clicking and dragging a batch to a different position.  Hit \texttt{Delete} to permanently remove a highlighted batch. In the list box is a column which enables or disables the batch with an \texttt{X} meaning the batch job is enabled and will be run.  This way batches can be skipped without being deleted.  Click on the \texttt{Enabled} column in the list box to enable or disable a batch.
83
84 The description of each of the columns in the batch list are as follows:
85
86 \begin{description}
87     \item[Enabled:] an X in this column means the batch job will be run.
88     \item[Labeled:] an \texttt{X} in this column goes hand in hand with create new file at each label.
89     \item[Output:] path and filename for the generated output.
90     \item[EDL:] the path and filename of the source EDL for the batch job.
91     \item[Elapsed:] the amount of time taken to render the batch if finished.  If field is empty, it did not run.
92 \end{description}
93 To start rendering from the first enabled batch, hit \texttt{Start}.  Once rendering, the main window shows the progress of the batch. After each batch finishes, the elapsed column in the batch list is updated and the next batch is rendered until all the enabled batches are finished.  The currently rendering batch is always highlighted red.  To stop rendering before the batches are finished without closing the batch render dialog, hit \texttt{Stop}.  To stop rendering before the batches are finished and close the batch render dialog, hit \texttt{Close}.  Or you can exit the batch render dialog whether or not anything is being rendered, by hitting \texttt{Close}.
94
95 You can automate Cinelerra batch renders from other programs.  In the batch render dialog, once you have created your list of batch render jobs, you can click the button \texttt{Save Jobs} and choose a file to save your batch render list to.  Once you have created this file, you can start up a batch render without needing to interact with the Cinelerra user interface.  From a shell prompt, from a script, or other program, execute:
96
97 \begin{lstlisting}[language=bash]
98     {path_to_cinelerra} -r batchjob.xml
99 \end{lstlisting}
100 substituting  your actual filename for \texttt{batchjob.xml}.  When invoked with these parameters, Cinelerra will start up and perform the rendering jobs in that list, without creating its usual windows.
101
102 \subsection{Command Line Rendering}%
103 \label{sub:command_line_rendering}
104
105 The command line rendering method consists of a way to load the current set of batch rendering jobs and process them without a GUI. This is useful if you want to do rendering on the other side of a low bandwidth network and you have access to a high powered computer located elsewhere. Setting up all the parameters for this operation is somewhat difficult. That is why the command line aborts if any output files already exist.
106
107 To perform rendering from the command line, first run Cinelerra in graphical mode. Go to \texttt{File $\rightarrow$ Batch Render}. Create the batches you intend to render in the batch window and close the window. This saves the batches in a file. Set up the desired render farm attributes in \texttt{Settings $\rightarrow$ Preferences} and quit out of Cinelerra if you want to use the Render Farm capability.  These settings are used the next time command line rendering is used to process the current set of batch jobs without a GUI.
108
109 On the command line run:
110
111 \begin{lstlisting}[language=bash]
112 cinelerra -r
113 \end{lstlisting}
114
115 \subsection{More about Save/Use EDL and Save/Load Jobs}%
116 \label{sub:more_save_use_edl_jobs}
117
118 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.
119
120 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.
121
122 \begin{description}
123     \item[Save to EDL Path] if you have made a change to the EDL, use this button to save the changes so
124     that they will be used in the render operation.  Although you can get the same results by using
125     \texttt{File  $\rightarrow$  Save\dots}, this capability was initially added to assist developers in testing the batch jobs needed
126     to create dvd/bluray media as it keeps the work focused in a single window and retains the original
127     job name.  An example ---you have everything all set up with a new job in the Batch Render window 
128     using \texttt{generic.xml} for the EDL path and with a job name of \texttt{original\_name.xml}.  Then you realize
129     that you forgot to cut out a section in the media that is not wanted in the final product.  You can cut 
130     that out and then \textit{Save to EDL Path} so your change will be in effect for the rendering.  Without this
131     button, you would be using the EDL you started with and the cut would be ignored.  Alternatively, if 
132     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 
133     replaced with \texttt{new.xml}.  However, it is important to note that the result will be saved with the name
134     \texttt{original\_name} – that is, the new content from \texttt{new.xml} but with the old name of \texttt{original\_name.xml}.
135     \item[Use Current EDL] if you are working on media and still testing out the results, you can take
136     advantage of this click-box to quickly get results.  Basically, you change the media, save that change 
137     with another name (in order to preserve the original name in case you don't like the changes), and
138     press \textit{Use Current EDL}.  As an example, a user creates a new job in the Batch Render window
139     using the current media, previously defined in generic.xml, with the EDL path of \texttt{generic.xml}.  The
140     user then changes the media on the timeline, saves the changes via \texttt{File $\rightarrow$ Save as\dots} with a new 
141     name, such as \texttt{new\_name.xml}, and then clicks on \textit{Use Current EDL}.  In this case, the EDL path
142     listbox will be automatically updated to the \texttt{new\_name.xml} and the current existing highlighted job will be replaced with the \texttt{new\_name.xml} in the EDL column.
143     \item[Save Jobs] when you have set up the batch jobs the way you want and you think you may have to
144     run them more than once, it is beneficial to save the jobs for later use so you easily run them again.
145     \item[Load Jobs] reload a previous set of saved jobs.  This can come in handy if you did not have the
146     time to render them when you originally set them up, if you need to rerun, or if you got interrupted.
147     \item[Warn if Jobs/Session mismatched] After you set up your render and press Start, the program checks to see if the current EDL session matches your Batch Render job.  If the EDL has
148     been changed since the batch job was created, it warns you so that you have the opportunity to \textit{Save to EDL} path to record those changes.  Otherwise, you can dismiss that warning box, disable the warning message by unchecking the box and use the original values.  If you never want to be warned about the mismatches, leave the box unchecked (figure~\ref{fig:batch02}).
149 \end{description}
150
151 \begin{figure}[htpb]
152     \centering
153     \includegraphics[width=0.8\linewidth]{images/batch02.png}
154     \caption{Batch render with the 4 ghosted buttons on the right side + the Warning message below}
155     \label{fig:batch02}
156 \end{figure}
157
158 \section{Background Rendering}%
159 \label{sec:background_rendering}
160
161 Background rendering causes temporary output to be rendered constantly while the timeline is being modified. The temporary output is displayed during playback whenever possible. This is useful for transitions and previewing effects that are too slow to display in real time. If a Render Farm is enabled, the render farm is used for background rendering. This gives you the potential for real-time effects if enough network bandwidth and CPU nodes exist.
162
163 Background rendering is enabled in the \texttt{Performance} tab of the \texttt{Preferences} window. It has one interactive function \texttt{Settings $\rightarrow$ Toggle background rendering}. This sets the point where background rendering starts up to the position of the insertion point. If any video exists, a red bar appears in the time ruler showing what has been background rendered (figure~\ref{fig:back-ren02}).
164
165 \begin{figure}[htpb]
166     \centering
167     \includegraphics[width=0.8\linewidth]{images/back-ren02.png}
168     \caption{Settings Background Rendering}
169     \label{fig:back-ren02}
170 \end{figure}
171
172 It is often useful to insert an effect or a transition and then select \texttt{Settings $\rightarrow$ Toggle background rendering} right before the effect to preview it in real time and full frame rates (figure~\ref{fig:back-ren}).
173
174 \begin{figure}[htpb]
175     \centering
176     \includegraphics[width=0.8\linewidth]{images/back-ren.png}
177     \caption{Timeline with the top red bar}
178     \label{fig:back-ren}
179 \end{figure}
180
181 \begin{description}
182     \item[Frames per background rendering job] This only works if a Render Farm is being used; otherwise, background rendering creates a single job for the entire timeline. The number of frames specified here is scaled to the relative CPU speed of rendering nodes and used in a single render farm job. The optimum number is 10 - 30 since network bandwidth is used to initialize each job.
183     \item[Frames to preroll background] This is the number of frames to render ahead of each background rendering job. Background rendering is degraded when preroll is used since the jobs are small. When using background rendering, this number is ideally 0. Some effects may require 3 frames of preroll.
184     \item[Output for background rendering] Background rendering generates a sequence of image files in a certain directory. This parameter determines the filename prefix of the image files. It should be accessible to every node in the render farm by the same path. Since hundreds of thousands of image files are usually created, ls commands will not work in the background rendering directory. The browse button for this option normally will not work either, but the configuration button for this option works.
185     \item[File format] The file format for background rendering has to be a sequence of images. The format of the image sequences determines the quality and speed of playback. JPEG generally works well.
186 \end{description}
187
188 \section{Render Farm Usage}%
189 \label{sec:render_farm_usage}
190
191 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. 
192
193 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.
194
195 \subsection{Basic Steps to Start a Render Farm}%
196 \label{sub:basic_steps_start_render_farm}
197
198 The following steps are just a guideline to start your render farm.  It is assumed that you already have the master and client nodes communication, shared filesystem, permissions and usernames synched.
199
200 \begin{enumerate}
201     \item On the master computer, use \texttt{Settings} $\rightarrow$ \texttt{Preferences} $\rightarrow$ \texttt{Performance} \texttt{tab} to set up a Render Farm:
202     \begin{itemize}
203         \item check the \texttt{Use render farm} box;
204         \item in the \texttt{Hostname} box, keyin your hostname or ip address such as \\
205             192.168.1.12 or \texttt{localhost};
206         \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};
207         \item you will see something like the following in the Nodes listbox to the right:
208             \begin{tabular}{lllc}
209                 On & Hostname     & Port & Framerate \\\midrule
210                 X  & 192.168.1.12 & 401  & 0.0       \\
211                 X  & 192.168.1.12 & 402  & 0.0       \\
212                 X  & 192.168.1.12 & 403  & 0.0       \\
213                 X  & 192.168.1.12 & 404  & 0.0       \\
214                 X  & 192.168.1.12 & 405  & 0.0       \\
215                 X  & localhost    & 406  & 0.0       \\
216                 X  & localhost    & 407  & 0.0       \\
217             \end{tabular}
218         \item set the Total number of jobs to create;
219         \item click OK on the bottom of the Preferences window.
220     \end{itemize}
221     \item On the client computers ($192.168.1.12$), start 5 background cinelerra tasks via:
222     \begin{lstlisting}[language=bash]
223 $ cd /{path_to_cinelerra}
224 $ cin -d 401
225 $ cin -d 402 
226 ...
227 $ cin -d 405
228     \end{lstlisting}
229     \item On the master node (localhost), start the 2 background cinelerra tasks via:
230     \begin{lstlisting}[language=bash]
231 $ cd /{path_to_cinelerra}
232 $ cin -d 406
233 $ cin -d 407
234     \end{lstlisting}
235     \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}.
236     \item The results will be in the shared file path / filename that you selected in the render menu with the
237     additional numbered job section on the end as  $001, 002, 003, \dots 099$ (example, \texttt{video.webm001}).
238     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.
239     \item If you plan on doing more rendering, you can just leave the master/client jobs running to use again
240     and avoid having to restart them.  Or you can kill them when you no longer are using them.
241 \end{enumerate}
242
243 \subsection{Render Farm Menu and Parameter Description}%
244 \label{sub:render_farm_parameter_description}
245
246 Below we describe the Performance tab for configuring a render farm (figure~\ref{fig:farm}).
247
248 \begin{figure}[htpb]
249     \centering
250     \includegraphics[width=0.8\linewidth]{images/farm.png}
251     \caption{Settings $\rightarrow$ Preferences, Performance tab, menu to set up your Render Farm}
252     \label{fig:farm}
253 \end{figure}
254
255 \begin{description}
256     \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.
257     \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.
258     \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.
259     \item[Hostname] this field is used to edit the hostname of an existing node or enter a new node.
260     \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.
261     \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.
262     \item[Add Nodes] Create a new node with the hostname and port settings.
263     \item[Sort nodes] sorts the nodes list based on the hostname.
264     \item[Delete Nodes] deletes whatever node is highlighted in the nodes list.  You can highlight several at once to have them all deleted.
265     \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.
266     \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.  
267     
268     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.
269     \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.
270     \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.
271 \end{description}
272
273 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.
274 Initially, when the framerate scaling values are zero, the program just uses package length --- render size 
275 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.
276
277 \begin{lstlisting}[language=bash]
278     {cinelerra pathname} -h     #displays some of the options.
279 \end{lstlisting}
280
281 \subsection{Detailed Setup Description}%
282 \label{sub:detailed_setup_description}
283
284 {\color{red} CAUTION }, any exact command lines worked as of $01/2018$ on a Fedora system.  These can change over time and on different operating systems/levels.  Always check/verify any command line before using.
285
286 \begin{description}
287     \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.  
288     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. 
289     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.
290     \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.
291     \begin{enumerate}
292         \item On each of the computers, install the nfs software if not already installed.  For example, on Debian 9
293         you will need to run: (be sure to check/verify before using any command line):
294         \begin{lstlisting}[language=bash]
295 $ apt-get install nfs-kernel-server
296         \end{lstlisting}
297         \item On the computer that contains the disk storage to be shared, define the network filesystem.  For
298         example to export \texttt{/tmp}, edit the \texttt{/etc/exports} file to add the following line:
299         \begin{lstlisting}[language=bash]
300 192.168.1.0/24(rw,fsid=1,no_root_squash,sync,no_subtree_check)
301         \end{lstlisting}
302         \item Next reset the exported nfs directories using: 
303         \begin{lstlisting}[language=bash]
304 $ exportfs -ra
305         \end{lstlisting} 
306         and you may have to start or restart nfs: 
307         \begin{lstlisting}[language=bash]
308 $ systemctl restart nfs
309         \end{lstlisting}
310         \item Each of the render farm computers must mount the exported nfs target path.  To see the exports
311         which are visible from a client, login as root to the client machine and keyin:
312         \begin{lstlisting}[language=bash]
313 $ showmount -e <ip-addr>  #using the ip address of the storage host
314         \end{lstlisting}
315         \item to access the host disk storage from the other computers in the render farm, mount the nfs export on
316         the corresponding target path: (be sure to check/verify before using any command line):
317         \begin{lstlisting}[language=bash]
318 $ mount -t nfs <ip-addr>:/<path>  <path>
319         \end{lstlisting}
320         where \texttt{<path>} is the storage host directory, and \texttt{<ip-addr>} is the network address of the storage host.        
321         Because all of the computers must have the same directory path, create that same directory path with the same uid/gid/permissions on each storage client computer ahead of time.
322         \item To make this permanent across reboots on the client nodes, add the following line to \texttt{/etc/fstab}: 
323         \begin{lstlisting}[language=bash]
324 {masternode}:/nfsshare /mnt nfs defaults 0 0
325         \end{lstlisting}
326         You can make this permanent on the disk storage host BUT the command lines shown, which were
327         correct in January 2018 on Fedora, may be different for your operating system or in the future.  In
328         addition if your network is not up, there may be numerous problems.  If you make a mistake, your
329         system may not boot.  To make permanent, add the following line to \texttt{/etc/fstab}:
330         \begin{lstlisting}[language=bash]
331 192.168.1.12:/tmp /tmp nfs rw,async,hard,intr,noexec,noauto 0 0
332         \end{lstlisting}
333         You will still have to mount the above manually because of the \textit{noauto} parameter but you won’t
334         have to remember all of the other necessary parameters.  Depending on your expertise level, you can
335         change that.
336         
337         Later, to remove access to the storage host filesystem:        
338         \begin{lstlisting}[language=bash]
339 $ umount <path>
340         \end{lstlisting}
341         
342         Be aware that you may have to adjust any security or firewalls you have in place.  \textit{Most firewalls will require extra rules to allow nfs access}.  Many have built-in configurations for this. 
343     \end{enumerate}
344     \item[Configure Rendering on Master Node] There is 1 master node which is running the Cinelerra gui and where the video will be edited and the command given to start up the rendering.  Any number of client computers can be run from the command line only, so they can be headless since no X or any graphical libraries are needed.  Of course, the cinelerra software must be installed on each of the client computers.
345     \begin{enumerate}
346         \item Assuming you already have Cinelerra installed on the master node, start Cinelerra by clicking on the
347         icon or by typing the following command on the terminal screen:  \texttt{/{cinelerra\_path}/cin}.
348         \item Use the file pulldown \texttt{Settings $\rightarrow$ Preferences}, the Performance tab, to set up your Render Farm
349         options in the Render Farm pane.
350         \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.
351         \item Add the hostname or the IP address of each of the client nodes in the Hostname textbox and the port
352         number that you want to use in the Port textbox.  You can make sure a port number is not already in
353         use by keying in on the command line:
354         \begin{lstlisting}[language=bash]
355 $ netstat -n -l -4 --protocol inet
356         \end{lstlisting}
357         Next, click on the \texttt{Add Nodes}
358         button and then you will see that host appear in the Nodes list box to the right.  The \texttt{X} in the first
359         column of the nodes box denotes that the node is active.  To review the \textit{standard} port allocations,
360         check the \texttt{/etc/services} file.
361         \item Enter the total jobs that you would like to be used in the \texttt{Total job} textbox.
362         \item The default watchdog timer initial state is usually just fine but can be adjusted later if needed.
363         \item Click \texttt{OK} on the Preferences window when done.
364     \end{enumerate}
365     \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.
366     \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:
367     \begin{lstlisting}[language=bash]
368 /{cinelerra_pathname}/cin -d [port #]   ;   \#for example /mnt1/bin/cinelerra -d 401
369     \end{lstlisting}
370     This starts cinelerra in command prompt mode so that it listens to the specified port number for commands from the master node for rendering.  When you start each of the clients up, you will see some messages scroll by as each client is created on that computer, such as:
371     \begin{lstlisting}[language=bash]
372 RenderFarmClient::main_loop: client started
373 RenderFarmClient::main_loop: Session started from 127.0.0.1
374     \end{lstlisting}
375     As it completes its jobs, you will should see:
376     \begin{lstlisting}[language=bash]
377 RenderFarmClientThread::run: Session finished
378     \end{lstlisting}
379     A quick way to start a sequence of clients is to use:
380     \begin{lstlisting}[language=bash]
381 or n in `seq 1501 1505`; do cin -d $n; done
382     \end{lstlisting}
383     \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).
384     
385     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.
386     \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.
387 \end{description}
388
389 \subsection{Quick and Easy Render Farm Setup – The Buddy System Way}%
390 \label{sub:buddy_system_way}
391
392 These steps are for quickly setting up render farm with the least amount of additional system work, but it is non-optimal.  It is useful in situations where a few people all show up with their laptops to work together on the same video/audio file and you don’t want to bother setting up NFS for a shared disk.
393
394 \begin{enumerate}
395     \item Make sure the Cinelerra program is installed on all of the computers and the network between the
396     main computer and the client computers is working.  Use the same version if possible.
397     \item Load your video file on the master node and use \texttt{File $\rightarrow$ Save as\dots}  to save it to \texttt{/tmp}.
398     \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
399     laptops that show up!
400     \item Edit your video/audio file to get it the way you want it and add the plugins, such as a Title, etc.
401     \item Check for a set of unused ports in \texttt{/etc/services} file, if username is root usually $401-425$ are
402     available; if non-root, then $1024-1079$.
403     \item On the master computer, in Settings $\rightarrow$ Preferences, the Performance tab:
404     \begin{itemize}
405         \item check the box \texttt{Use render farm}
406         \item keyin localhost for the hostname or an ip address of the buddy client node
407         \item keyin the desired port number for each client; and use \texttt{Add Node} for each host
408         \item set total jobs to the number of client computers $+1$ multiplied by $3$ (or proportion to client speeds)
409         \item check \texttt{OK}
410     \end{itemize}
411     \item On each buddy client, create a job for each port:    
412     \begin{lstlisting}[language=bash]
413 /{cinelerra_pathname}/cin -d port#
414     \end{lstlisting}
415     \item On the master, bring up the render menu and name the output files, for example \texttt{/tmp/myoutput.mp4}.
416     \item The client nodes output results will be on their local \texttt{/tmp} filesystems so you will have to again use
417     \texttt{rsh/ftp} or \texttt{usb sneaker net} to move them over to the main computer.  File names will be the render
418     job output file name with port number tacked on (e.g. \texttt{/tmp/hb.mp4001...mp4005}).
419     \item Load the files by concatenate to existing track on the master node or use RenderMux shell script.
420 \end{enumerate}
421
422 \subsection{Multi-core Computers Render Farm Setup\protect\footnote{the 'Epyc' method}}%
423 \label{sub:multi_core_render_farm_setup}
424
425 Because index files speed up displaying the video you may want to share these files with the clients on a shared filesystem.  There is a configuration option available in \texttt{Settings $\rightarrow$ Preferences}, the Interface tab, that sets up in your preferences the location of the index files which you can put on a shared disk.
426 Screencast below shows part of the Preferences menu where you can change the index files setup (figure~\ref{fig:index}).
427 \begin{figure}[htpb]
428     \centering
429     \includegraphics[width=0.8\linewidth]{images/index.png}
430     \caption{Index file setup for your preferred configuration for Render Farm sharing or anything}
431     \label{fig:index}
432 \end{figure}
433  Or, one of the convenient features of cin5 is the redirection of the path via \texttt{CIN\_CONFIG} as in:
434 \begin{lstlisting}[language=bash]
435 CIN_CONFIG=/<shared_file_pathname>/<filename_such_as_.bcast5> /<cinelerra_pathname>/cin
436 \end{lstlisting}
437 This means that you can make project related configurations that do not impact the default \texttt{\$HOME} config.  You can either export your default \texttt{\$HOME} config or the \texttt{CIN\_CONFIG} config to use on the render farm.
438
439 \subsection{Troubleshooting Tips and Warnings}%
440 \label{sub:troubleshhoting_tips_warnings}
441
442 \noindent If you have problems running the Render Farm.  Here is a list of items to check.
443
444 \begin{itemize}
445     \item Cinelerra must be installed on the master node and all client machines.
446     \item It is best to have the same username available on all nodes to avoid problems with access rights.
447     \item Check file permissions and ownership to ensure that the clients all have access.
448     \item If a node does not have access to an input asset it will not die, but just display error messages.
449     \item If a node can not access an output asset, the rendering will abort.
450     \item A port in use when stopped may take up to $30$ seconds to time out before you can restart the jobs.
451     \item Each of the port combinations have to be unique across clients, and not already in use in the network.
452     \item Cinelerra load balances on a first come, first serve basis.  If the last section of the video is sent to the
453     slowest node, the render job will have to wait for the slowest node to finish.  It would be better to 
454     start on the slowest node with the earlier section of the video so keep that in mind when designating
455     port numbers.
456     \item If not running as root, a port number in the higher range of $1024$ and above must be used instead of
457     the $400+$ range.
458     \item The master and client jobs on the ports do not go away so if you want to stop them, you will have to
459     kill them via: \texttt{kill PID\#}.
460     \item Check to see if there are services listening on the ports to use:  \texttt{netstat -n -l -4 --protocol inet}
461     \item There is a watchdog timer in Cinelerra and if there is no response from a client in the designated
462     number of seconds, it will kill the render job.
463     \item The \textit{localhost} should exist as $127.0.0.1$ in \texttt{/etc/hosts} and as the \texttt{lo} network device in ifconfig.
464     \item If the job loads become unbalanced, you may want to \textit{reset rates} to start over for new framerates.
465     \item If jobs are split in a key section on the timeline, you may wish to \textit{use labels} to prevent this.
466     \item For testing purposes, you may want to start a client in the foreground using \texttt{-f} instead of \texttt{-d}.
467     \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}
468     in the Nodes listbox.  Check the \texttt{X} to disable it which sets \texttt{On} to \texttt{Off}.
469     \item A red message in the lower left hand corner of the main timeline that reads \textit{Failed to start render
470     farm} often means that the client cinelerra programs were not started up.
471     \item A message of \texttt{RenderFarmWatchdog::run 1 killing server thread \\ \#address\#} means that the client did
472     not respond in time.  You can adjust the timer in Settings $\rightarrow$ Preferences, Performance tab.
473     \item When you get the message \texttt{RenderFarmClient::main\_loop: bind port 400: Address already in use}, use a different port.
474     \item A message of \texttt{RenderFarmServerThread::open\_client: unknown host abcompany} means that the
475     hostname of abcompany is not in \texttt{/etc/hosts} so you will have to add it or use the ip address instead.
476     \item There are numerous error messages associated with file \texttt{open/close/status} or problems with the file
477     that should be dealt with according to what is printed out.
478     \item Other illustrative messages may be shown such as: \texttt{RenderFarmClientThread:: run: Session finished}.
479 \end{itemize}
480
481 \paragraph{Warnings}
482
483 If one of the render farm computers is connected to the internet, you should use a firewall to maintain the safety of all of the computers.  The ports have to be reachable for the intranet but you do not want the ports to be open to the outside.
484
485 \section{Some Specific Rendering}%
486 \label{sec:some_specific_rendering}
487
488 \noindent The next few pages relate to rendering for specific common cases.
489
490 \subsection{FFmpeg Common H.264 Rendering}%
491 \label{sub:ffmpeg_h264_rendering}
492
493 Because H.264 is so widely used, the method in Cinelerra-GG Infinity is outlined below.  These setup steps make it easy to just get started.
494
495 \begin{itemize}
496     \item File $\rightarrow$ Render
497     \item File Format $\rightarrow$ FFMPEG + mp4
498     \item Video Wrench $\rightarrow$ Preset $\rightarrow$ h264.mp4 + bitrate: 6000000 (or whatever) + OK
499     \item Audio Wrench $\rightarrow$ Preset $\rightarrow$ h265.mp4 + bitrate: 224000 (or whatever) + OK
500     \item Set your target path in: Render $\rightarrow$ Select a file to render to
501     \item Set your timeline in: Render $\rightarrow$ Render range + click Project
502     \item Set your insertion strategy: Replace project (or whatever)
503     \item Press OK to start rendering.
504 \end{itemize}
505
506 \subsection{Lossless Rendering}%
507 \label{sub:loseeless_rendering}
508
509 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.
510
511 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.
512
513 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.
514
515 \subsection{Extra “cin\_” Options for Render with FFmpeg}%
516 \label{sub:extra_cin_option_ffmpeg}
517
518 There are several special parameters that can be used in the ffmpeg options file to pass values to the codecs that are not normally available.  These are explained below.
519
520 \paragraph{cin\_pix\_fmt} The Render menus allows you to choose the codec input pixel format (figure~\ref{fig:yuv420}).  The Pixels selection provides the available pixel format options for the chosen codec type; valid choices vary for the different file types.  This list represents the formats that the codec advertises.  It is not always complete, and it may include options that are not legal with all parameter configurations.
521
522 \begin{figure}[htpb]
523     \centering
524     \includegraphics[width=0.6\linewidth]{images/yuv420.png}
525     \caption{Render \& Video Preset menus displaying Pixel choices}
526     \label{fig:yuv420}
527 \end{figure}
528
529 \begin{itemize}
530     \item The \textit{Bitrate}, \textit{Quality}, and \textit{Pixels} fields are only updated when the Video Options are reloaded.  This
531     occurs when you either change the ffmpeg file format, or video presets compression fields.
532     \item If the video options preset has \texttt{cin\_pix\_fmt} defined, its value will be loaded as the default.  If you
533     override the default, the value you specify will be used.
534     \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
535     \textit{best} is usually the format which is most similar in color and depth.
536     \item If no choices are available, \texttt{yuv420p} for video will be used.
537     \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.
538 \end{itemize}
539
540 \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}.
541
542 \paragraph{cin\_bitrate} If you specify the bitrate, you can not specify the quality.
543 Example: \texttt{cin\_bitrate=2000000}
544
545 \paragraph{cin\_quality} If you specify the quality, you can not specify the bitrate.
546 Example: \texttt{cin\_quality=7}
547
548 \paragraph{cin\_stats\_filename} This parameter is useful for 2 pass operations.
549 Example: \texttt{cin\_stats\_filename /tmp/cin\_video\_vp9\_webm}
550
551 \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.
552 Example: \texttt{cin\_sample\_fmt=s16}
553
554 \begin{figure}[htpb]
555     \centering
556     \includegraphics[width=0.6\linewidth]{images/audio.png}
557     \caption{Render menu showing where Samples is}
558     \label{fig:audio}
559 \end{figure}
560
561 \subsection{Two-pass Encoding with FFmpeg}%
562 \label{sub:two_pass_encoding_ffmpeg}
563
564 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.
565
566 This 2 line ffmpeg 2-pass operation can be functionally duplicated in Cinelerra in the steps below them:
567
568 \begin{lstlisting}[language=bash]
569 ffmpeg -y -i input -c:v libx264 -b:v 2600k -pass 1 -c:a aac -b:a 128k -f mp4 /dev/null && \
570 ffmpeg -i input -c:v libx264 -b:v 2600k -pass 2 -c:a aac -b:a 128k output.mp4
571 \end{lstlisting}
572
573 \begin{enumerate}
574     \item After you have completed your editing, do a Save Session with \texttt{File $\rightarrow$ Save as\dots}
575     Before starting, be sure your session is ready for batch render. That is, positioned at the beginning and nothing selected.
576     \item Bring up \texttt{File $\rightarrow$ Batch Render\dots} where you will do the setup.
577     \item Click on the \textit{Delete} box  to remove old jobs highlighted in the bottom listbox.
578     \begin{itemize}
579         \item For the \texttt{File Format} choose ffmpeg and mp4 for the type.
580         \item Set \texttt{Output path} to the path and filename for the render output file.
581         \item Click on \texttt{Use Current EDL} to use the designated EDL Path file.
582         \item Click on \texttt{New} and you will see a new highlighted job show up in the listbox at the bottom.
583         \item Use the Audio wrench to set bitrate to $128000$ ($128k$ as in ffmpeg example above).
584         \item Click checkmark \texttt{OK}.  Open the video tools with the video wrench.
585         \item Set the Video Compression to h264.mp4 (as seen in the example).
586         \item Set the bitrate to $2600000$ ($2600k$ as in ffmpeg example above).
587         \item Add the following 2 lines after the first line:
588         \begin{lstlisting}[language=bash]
589 flags +pass1
590 passlogfile /tmp/{temporary log file name}.log
591         \end{lstlisting}
592         Click checkmark \texttt{OK}.
593     \end{itemize}    
594     \item Click on \texttt{New} to create the second pass job.  You will see this second job in the listbox below.
595      Use the Video wrench and change pass1 to pass2 as follows.
596         \begin{lstlisting}[language=bash]
597 flags +pass2
598         \end{lstlisting}
599     \item Click checkmark \texttt{OK}.
600     \item Click on the \texttt{Start} box and watch it go!
601     \item You can now check the output file for results.  At the time this was documented, \texttt{rc=2pass} will be
602         in the output.    
603 \end{enumerate}
604
605 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.
606
607 \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; 
608 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.
609
610 \paragraph{Requirements for some other libraries} ~\\ (used instead of \texttt{flags +pass1} \& \texttt{passlogfile}):
611
612 \begin{description}
613     \item[x265:] add this line:
614     \begin{lstlisting}[language=bash]
615 x265-params=pass=1:stats=/tmp/{temporary log file name}.log
616     \end{lstlisting}      
617     at the time this document was written, you should see in the output: \\  \texttt{stats-read=2}
618     
619     \item[libvpx-vp9, xvid, and huffyuv:]~
620
621     \begin{lstlisting}[language=bash]
622     cin_stats_filename /tmp/{temporary log file name}.log
623     flags +pass1 (or flags +pass2 for the second pass)
624     \end{lstlisting}    
625 \end{description}
626
627 \noindent \textit{NOTE:} for vp9, the best Pixels is \texttt{gbrp}
628
629 \subsection{Use case: High Efficiency Video Coding (HEVC)}%
630 \label{sub:use_case_hevc}
631
632 An example of video profile based on CRF, a quality-controlled
633 variable bitrate, instead of fixed quality scale (ABR).
634 HEVC (H.265) was developed as a successor to AVC (H.264) to more
635 efficiently compress the future large amounts of data from 2/4/8k
636 videos.
637 In comparison to AVC, an average saving of around 30 percent can be
638 assumed for the same quality.
639 Because HEVC is not bound to any size format, it is suitable for
640 virtually any image size.
641
642 The following example is HD and FullHD oriented and produces a
643 picture quality similar to the Blu-ray with some limitations.
644 As container Matroska (.mkv) is used, but also mp4 and others are
645 possible.
646
647 \vspace{2ex} \begin{lstlisting}[language=Bash]
648 matroska libx265
649
650 # CRF 16 creates a balanced compromise
651 # between quality and file size. 
652 crf=16
653
654 # Preset changes encoding speed and generally
655 # degrades the overall result. Medium (default)
656 # always fits.
657 preset=medium
658
659 # Additional parameters that are passed on to the codec.
660 # me=star improves the search for very fast
661 # movements, but slows down the encoding.
662 #x265-params=me=star
663
664 # Keyint does FFmpeg automatically, otherwise
665 # the setting must match the frame rate.
666 #keyint\_min=25
667
668 # Profile does FFmpeg automatically.
669 #profile=high
670
671 # Source sRBG and retention of color space.
672 # 720/1080=bt709 if no profile set. Useful
673 # for formats smaller than 720 if no lossy
674 # conversion is desired.
675 colorspace=bt709
676 color_trc=bt709
677 color_primaries=bt709
678
679 # Output in 10 bit, prevents 8-bit step formation
680 pixel_format=yuv420p
681 \end{lstlisting}
682
683 \noindent \textit{NOTE:}
684
685 A CRF of 16 delivers satisfactory results in most cases. However, if
686 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.
687
688 The color space information must be used explicitly so that it can
689 be included in the video. Cinelerra\,GG or FFmpeg does not write it
690 by itself. Without this information the players (e.\,g.\ \href{https://mpv.io/}{mpv}) stick to the dimensions of the video and take the assumed color model from a table. With videos in the dimensions from 720 to 1080 this is bt709. For smaller dimensions, e.\,g.\ DVD, bt601 is assumed and for 4k and above it is bt2020. Normally this is not a problem, but if you want to export a FullHD without color loss to a smaller size like 576 for example, you have to inform the encoder as well as the decoder of the player. This also applies if the videos are to be loaded on video platforms, where they are then converted into videos of different sizes. It is a security measure to prevent false colors, such as the color profiles in digital photos and the copies made from them.
691
692 The HEVC tuning has not been considered here, because it is is
693 rarely used and requires background knowledge.
694
695 Further links:
696 \begin{itemize}
697     \item \href{http://x265.readthedocs.org/en/default/}{x265
698         Documentation}
699     \item \href{http://x265.readthedocs.org/en/latest/cli.html}{x265
700         Command Line Options}
701     \item \href{http://x265.readthedocs.org/en/latest/presets.html}{x265
702         Presets/Tuning}
703 \end{itemize}
704
705 \subsection{Piping Video to a Command Line}%
706 \label{sub:piping_video_command_line}
707
708 You can pipe a video to any command line on the computer, such as ffmpeg.  This can be especially useful with raw video files.  Next is an example usage.
709
710 \begin{enumerate}
711     \item on a terminal window create a named pipe file, for example:
712     \begin{lstlisting}[language=bash]
713 mknod /tmp/piper.yuv p
714     \end{lstlisting}
715     load your video and do your editing
716     \item set up your Render (\texttt{Shift-R}), you can choose a raw format such as \textit{yuv} or \textit{rgb}
717     \item for the filename \texttt{Select a file to render to}, use the named pipe as created in step 1 (\texttt{/tmp/piper.yuv})
718     \item for \texttt{Insertion Strategy}, you will want to make sure to select \textit{insert nothing}
719     \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.)
720     \item on the terminal window, keyin your command, for example:
721     \begin{lstlisting}[language=bash]
722 /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
723     \end{lstlisting}
724 \end{enumerate}
725
726 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}):
727 \begin{lstlisting}[language=bash]
728 ffmpeg -f yuv4mpegpipe -i /tmp/piper.y4m -vcodec libx264 /tmp/test.mp4
729 \end{lstlisting}
730
731 \subsection{Faststart Option for MOV type files}%
732 \label{sub:faststart_option_mov0}
733
734 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.
735
736 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.
737