Credit Andrea - correct HDR references
[goodguy/cin-manual-latex.git] / parts / Rendering.tex
1 \chapter{Rendering}%
2 \label{cha:rendering}
3 \index{rendering}
4
5 To configure the render according to your needs and to obtain the desired output, you will need to check on what your settings are for these three items:
6
7 \begin{enumerate}
8         \item \textbf{Timeline:} is the main starting point because, in addition to determining the range of frames that will be rendered, it is on the timeline that plugins and other editing features are applied, which will then be included in the rendered file. 
9         \item \textbf{Set Format:} is used to configure the fps, aspect ratio and frame size of the project     (= output). This can be found in the pulldown: \texttt{Settings $\rightarrow$ Format... (Shift + F)}.
10         See: \nameref{cha:project_and_media_attributes}.
11         \item \textbf{Render dialog:} this is under: \texttt{File $\rightarrow$ Render... (Shift + R)}. It contains all the rendering options that are documented in this chapter.
12 \end{enumerate}
13
14 Rendering takes a section of the timeline, \index{active region} performs all the editing,
15 effects and compositing, and creates a new media file.  You can then
16 delete all the source assets, play the rendered file, or bring it
17 back into \CGG{} for more editing.  All rendering operations are
18 based on a region of the timeline to be rendered.  You need to
19 define this region on the timeline.  The rendering functions define
20 the region based on a set of rules.  When a region is highlighted or
21 in/out points are set, the affected region is rendered.  When no
22 region is highlighted, everything after the insertion point is
23 rendered.  By positioning the insertion point at the beginning of a
24 track and unsetting all in/out points, the entire track is rendered.
25 But you also have the choice to render \textit{one frame}. Reminder,
26 \CGG{} does not do remuxing without rendering - see \nameref{sec:transcode}.
27
28 \section{Single File Rendering}%
29 \label{sec:single_file_rendering}
30 \index{rendering!single file}
31
32 Use the \textit{File} pulldown and select Render to start the render dialog
33 (figure~\ref{fig:render}).  Then choose the desired parameters.
34
35 \begin{figure}[htpb] \centering
36   \includegraphics[width=0.5\linewidth]{render.png}
37   \caption{Example of the Render menu}
38   \label{fig:render}
39 \end{figure}
40
41 \begin{description}
42 \item[Select a file to render to:] enter the path and filename to
43   write the rendered file to in the textbox below.
44 \item[File Format:] \index{file format} use the down arrow to see file format options.
45   For ffmpeg, which has its own set of options, you will then have to
46   select an ffmpeg file type from the down arrow choices. The format
47   of the file determines whether you can render audio or video or
48   both.
49 \item[Render audio tracks:] check this toggle to generate audio
50   tracks
51 \item[Render video tracks:] check this toggle to generate video
52   tracks. The Render window will sometimes automatically update the
53   Render Audio Tracks or Render Video Tracks checkbox as allowed by
54   the chosen file format, but you should always check
55   (figure~\ref{fig:render01}).  For example, if the PNG file format is
56   selected, only the \textit{Render Video Tracks} will be checked.  Or
57   if an ffmpeg format is chosen and the file format does not render
58   audio, the \textit{Render Audio Tracks} will be unchecked. The
59   invalid choices will be ghosted out.
60 \end{description}
61
62 \begin{figure}[htpb] \centering
63   \includegraphics[width=0.7\linewidth]{render01.png}
64   \caption{Audio and Video tracks automatically checked for Pro file
65     type}
66   \label{fig:render01}
67 \end{figure}
68
69 \begin{description}
70 \item[Wrench:] \index{wrench} select the \textit{wrench} next to each toggle to set
71   compression parameters.  If the file format can not store audio or
72   video the compression parameters will be blank.  If \textit{Render
73     audio tracks} or \textit{Render video tracks} is selected and the
74   file format does not support it, trying to render will result in an
75   error message. There are several hardware related formats that will
76   only work on specific computers that support that hardware/software
77   implementation and will result in an error message if not available.
78   Pick a different one.  This is especially relevant if using an AppImage
79   which is generated on a computer with few extra hardware implemented
80   features.
81 More details on differing parameters of the format in the section:
82   \nameref{sub:extra_cin_option_ffmpeg}.
83 \item[Create new file at each label] the option causes a new file to
84   be created when every label in the timeline is encountered – a
85   separate file for each.  This is useful for dividing long audio
86   recordings into individual tracks.  When using the Render Farm
87   (described later), \textit{Create new file at each label} causes one
88   render farm job to be created at every label instead of using the
89   internal load balancing algorithm to space jobs.  If the filename
90   given in the render dialog has a 2 digit number in it, the 2 digit
91   number is overwritten with a different incremental number for every
92   output file. If no 2 digit number is given, \CGG{} automatically
93   concatenates a number to the end of the given filename for every
94   output file.  For example, in the filename
95   \texttt{/movies/track01.wav} the $01$ would be overwritten for every
96   output file.  The filename \texttt{/movies/track.wav}; however,
97   eventually would become \texttt{/movies/track.wav001} and so on.
98   Filename regeneration is only used when either render farm mode is
99   active or creating new files for every label is active.
100 \item[Render range:] \index{active region} choices are \textit{Project} \index{project},
101   \textit{Selection}, \textit{In/Out points}, and \textit{One Frame}
102   for single images like Tiff.  For these images, Render range will
103   have \textit{One Frame} automatically checked and all of the others
104   ghosted since nothing else makes sense (figure~\ref{fig:render02}).
105   This makes it easy to set the insertion point where you want the 1
106   frame to be rendered rather than having to precisely zoom in to set
107   the in/out pointers.  Note that whichever Render range is checked,
108   remains checked so that if \textit{One Frame} gets automatically
109   checked, the next time you render it will still be checked and you
110   will have to select a different one if desired.  That is why you
111   should always check the settings.
112 \end{description}
113
114 \begin{figure}[htpb] \centering
115   \includegraphics[width=0.7\linewidth]{render02.png}
116   \caption{Render menu displaying a PNG \textit{one frame} option}
117   \label{fig:render02}
118 \end{figure}
119
120 \begin{description}
121 \item[Beep on done:] as a convenience when a render is complete,
122   check this box.  It gives you the chance to work on something else
123   while waiting and still be immediately notified when the render is
124   complete.
125 \item[Render Profile:] \index{rendering!profile} another convenience feature to take advantage
126   of if you use specific render formats frequently, is to save that
127   profile for future usage without having to set it up again.
128 \item[Save Profile:] after setting up your render preference
129   formats, do not forget to type in a format name and then use the save profile
130 button to save it.  The named/saved Profiles will be saved in your
131 \$HOME/.bcast5/Cinelerra\_rc file where it can be carefully modified.
132 \item[Delete Profile:] if you want to delete a saved profile,
133   highlight the one you no longer want and delete.
134 \item[Insertion strategy:] \index{insertion strategy} select an insertion mode from the
135   available choices as seen when you click on the down arrow on the
136   right hand side of the option. The insertion modes are the same as
137   with loading files.  In the case if you select “insert nothing” the
138   file will be written out to disk without changing the current
139   project. For other insertion strategies be sure to prepare the
140   timeline to have the output inserted at the right position before
141   the rendering operation is finished.
142
143   Even if you only have audio or only have video rendered, a paste
144   insertion strategy will behave like a normal paste operation,
145   erasing any selected region of the timeline and pasting just the
146   data that was rendered.  If you render only audio and have some
147   video tracks armed, the video tracks will get truncated while the
148   audio output is pasted into the audio tracks.
149 \end{description}
150
151
152 \subsection{Extra “cin\_” Options for Render with FFmpeg}%
153 \label{sub:extra_cin_option_ffmpeg}
154 \index{rendering!ffmpeg options}
155
156 There are several special parameters that can be used in the ffmpeg
157 options file to pass values to the codecs that are not normally
158 available.  They're called Global Options. These are explained
159 below.
160
161 \paragraph{cin\_pix\_fmt} The Render menus allows you to choose the
162 codec input pixel format (figure~\ref{fig:yuv420}).  The Pixels
163 selection provides the available pixel format options for the chosen
164 codec type; valid choices vary for the different file types.  This
165 list represents the formats that the codec advertises.  It is not
166 always complete, and it may include options that are not legal with
167 all parameter configurations.
168
169 \begin{figure}[htpb] \centering
170         \includegraphics[width=1.0\linewidth]{yuv420.png}
171         \caption{Render \& Video Preset menus displaying Pixel choices}
172         \label{fig:yuv420}
173 \end{figure}
174
175 \begin{itemize}
176         \item The \textit{Bitrate}, \textit{Quality}, and \textit{Pixels}
177         fields are only updated when the Video Options are reloaded.  This
178         occurs when you either change the ffmpeg file format, or video
179         presets compression fields.
180         \item If the video options preset has \textit{cin\_pix\_fmt}
181         defined, its value will be loaded as the default.  If you override
182         the default, the value you specify will be used.
183         \item If the video options preset does not have
184         \textit{cin\_pix\_fmt}, the default pixel format will be computed by
185         ffmpeg (\textit{avcodec\_find\_best\_pix\_fmt\_of\_list}), using the
186         session format as the source choice.  The \textit{best} is usually
187         the format which is most similar in color and depth.
188         \item If no choices are available, yuv420p for video will be used.
189         \item You can also specify ffmpeg pixel formats which are not in the
190         list.  The list is provided by ffmpeg as input selection, but is
191         more like suggestions than fact.  For example, the raw formats can
192         take almost any format, but the rawvideo codec actually specifies no
193         legal formats.  Note that if you want a very specific Bitrate you must
194         make sure there is not conflicting parameter values set such as Quality
195         or CRF.
196 \end{itemize}
197
198 \noindent Some option files provide \textit{cin\_pix\_fmt} to
199 suggest a choice for good quality output or to prevent parameter
200 errors when the other provided parameters conflict with the
201 \textit{best} pixel format.  This is the case in
202 \texttt{faststart\_h264.mp4} where the \textit{profile=high}
203 parameter dictates pixel format must be \texttt{yuv420p}.
204
205 \paragraph{cin\_bitrate} If you specify the bitrate, you can not
206 specify the quality or CRF.\\ Example: \textit{cin\_bitrate=2000000}
207
208 \paragraph{cin\_quality} If you specify the quality, you can not
209 specify the bitrate.\\ Example: \textit{cin\_quality=7}
210
211 \paragraph{cin\_stats\_filename} This parameter is useful for 2 pass
212 operations.\\ Example: \texttt{cin\_stats\_filename
213         /tmp/cin\_video\_vp9\_webm}
214
215 \paragraph{cin\_sample\_fmt} For audio the preset sample format
216 default is computed in a similar way as stated above for video or
217 can be set with the \textit{cin\_sample\_fmt} parameter
218 (figure~\ref{fig:audio}).  If no choices are provided, s16 will be
219 used.\\ Example: \textit{cin\_sample\_fmt=s16}
220
221 \begin{figure}[htpb] \centering
222         \includegraphics[width=0.7\linewidth]{audio.png}
223         \caption{Render menu showing where Samples is}
224         \label{fig:audio}
225 \end{figure}
226
227 \paragraph{Private Options} (muxers). In the window of the
228 \textit{wrench} in addition to the \textit{View} button, which
229 allows more global options and changes to the formats, there is an
230 additional \textit{Format} button that allows you to modify the
231 Private Options, i.e.\ relating to specific muxing formats. You can list private options available in a encoder with:
232
233 \begin{lstlisting}[style=sh]
234         $ /path/to/cin/thirdparty/ffmpeg-X.Y/ffmpeg -h encoder='libcodec' (i.e. libx265)
235 \end{lstlisting}
236
237 More information on all these options can be found at
238 \href{https://ffmpeg.org/ffmpeg-all.html#Format-Options}{ffmpeg.org}
239 sections 19 and 21. See also \nameref{sub:modifying_ffmpeg_cinelerra}.
240
241 Render presets in \CGG{} should work Out Of the Box. You can still configure the \textit{Global Options} and \textit{Private Options} manually. Finding the combination of parameters that best suits your needs, or simply finding working (\textit{legal}) combinations, requires studying each codec in depth. You can start by looking in Wikipedia until you get to download and study the \textit{white papers} of the codecs of interest. In any case, you must then start a long experimental phase, trying presets with different configurations or creating new ones, until you get satisfactory results. If you create new presets it is a good idea to make them known on the mailing list ({\small \url{https://lists.cinelerra-gg.org/mailman/listinfo/cin}}) or on the MantisBT Bug Tracker ({\small \url{https://www.cinelerra-gg.org/bugtracker/my_view_page.php}}) so that they can be integrated into subsequent versions of \CGG{}. For an introduction see \nameref{sec:overview_formats}.
242
243 \section{Some Specific Rendering}%
244 \label{sec:some_specific_rendering}
245
246 \noindent The next few pages relate to rendering for specific common
247 cases. Also see: \small\url{https://gist.github.com/dexeonify/ed31c7d85fcf7297719e2ec4740fafda})
248
249 \subsection{FFmpeg Common H.264 Rendering}%
250 \label{sub:ffmpeg_h264_rendering}
251
252 Because H.264 is so widely used, the method in \CGG{} Infinity is
253 outlined below.  These setup steps make it easy to just get started.
254
255 \begin{itemize}
256         \item File $\rightarrow$ Render
257         \item File Format $\rightarrow$ FFMPEG + mp4
258         \item Video Wrench $\rightarrow$ Preset $\rightarrow$ h264.mp4 +
259         bitrate: 6000000 (or whatever) + OK
260         \item Audio Wrench $\rightarrow$ Preset $\rightarrow$ h265.mp4 +
261         bitrate: 224000 (or whatever) + OK
262         \item Set your target path in: Render $\rightarrow$ Select a file to
263         render to
264         \item Set your timeline in: Render $\rightarrow$ Render range +
265         click Project
266         \item Set your insertion strategy: Replace project (or whatever)
267         \item Press OK to start rendering.
268 \end{itemize}
269
270 \subsection{Lossless Rendering}%
271 \label{sub:loseeless_rendering}
272 \index{rendering!lossless}
273
274 Lossless means that in the compression of a file, all of the
275 original data, every single bit, can be recovered when the file is
276 uncompressed.  This is different than \textit{lossy compression}
277 where some data is permanently deleted so that when uncompressed,
278 all of the original data can not be exactly recovered.  Lossy is
279 generally used for video and sound, where a certain amount of
280 information loss will not be detected by most users or the playback
281 hardware does not reproduce it anyway -- it is a trade-off between
282 file size and image/sound quality.  The files created will be more
283 than 10 times larger than usual.  Most players will not be able to
284 decode lossless as the bitrate will overwhelm the device.
285
286 For x264 lossless compression to work, the only color model allowed
287 here is yuv420p.  Any other specification will be converted to
288 yuv420p and the data will be modified.  Also, keep in mind that the
289 YUV color model has to be converted to RGB, which also modifies the
290 data.
291
292 To use x264 lossless rendering -- choose File format of ffmpeg, m2ts
293 in the Render window.  Click on the Video wrench, which brings up
294 the Video Preset window and scroll down in the Compression filebox
295 and choose \texttt{lossless.m2ts}.  \textit{Preset=medium} is the
296 default, but can be varied from \textit{ultrafast} (least amount of
297 compression, but biggest file size) to \textit{veryslow} (most
298 amount of compression, but still HUGE) in the parameter box where
299 you see $qp=0$.  This option is also available for bluray creation.
300
301 \subsection{Two-pass Encoding with FFmpeg}%
302 \label{sub:two_pass_encoding_ffmpeg}
303 \index{rendering!ffmpeg two-pass encoding}
304
305 In \CGG{} for two-pass, you need to run ffmpeg twice, with the same
306 settings, except for designating the options of pass~1 for the first
307 pass and then pass~2.  In pass~1, a logfile that ffmpeg needs for
308 the second pass is created.  In pass~1 the audio codec should be
309 specified that will be used in pass~2.  For more information on
310 ffmpeg 2-pass, check
311 \href{https://trac.ffmpeg.org/wiki/Encode/H.264}{ffmpeg.org}.
312 Different libraries may have different requirements and you will
313 probably have to determine this by looking online at ffmpeg or
314 looking directly at that code.
315
316 This 2 line ffmpeg 2-pass operation can be functionally duplicated
317 in \CGG{} in the steps below them:
318
319 \begin{lstlisting}[style=sh]
320         ffmpeg -y -i $INPUT \
321         -c:v libx264 -b:v 2600k -pass 1 \
322         -c:a aac -b:a 128k -f mp4 /dev/null && \
323         ffmpeg -i $INPUT \
324         -c:v libx264 -b:v 2600k -pass 2 \
325         -c:a aac -b:a 128k $OUTPUT.mp4
326 \end{lstlisting}
327
328 \begin{enumerate}
329         \item After you have completed your editing, do a Save Session with
330         \texttt{File $\rightarrow$ Save as}\dots Before starting, be sure
331         your session is ready for batch render. That is, positioned at the
332         beginning and nothing selected.
333         \item Bring up \texttt{File $\rightarrow$ Batch Render}\dots where
334         you will do the setup.
335         \item Click on the \textit{Delete} box to remove old jobs
336         highlighted in the bottom listbox.
337         \begin{itemize}
338                 \item For the \textit{File Format} choose ffmpeg and mp4 for the
339                 type.
340                 \item Set \textit{Output path} to the path and filename for the
341                 render output file.
342                 \item Click on \textit{Use Current EDL} to use the designated EDL
343                 Path file.
344                 \item Click on \textit{New} and you will see a new highlighted job
345                 show up in the listbox at the bottom.
346                 \item Use the Audio wrench to set bitrate to $128000$ ($128k$ as
347                 in ffmpeg example above).
348                 \item Click checkmark OK\@.  Open the video tools with the video
349                 wrench.
350                 \item Set the Video Compression to \textit{h264.mp4} (as seen in
351                 the example).
352                 \item Set the bitrate to $2600000$ ($2600k$ as in ffmpeg example
353                 above).
354                 \item Add the following 2 lines after the first line:
355                 \begin{lstlisting}[style=sh]
356                         flags +pass1
357                         passlogfile /tmp/"{temporary log file name}.log"
358                 \end{lstlisting} Click checkmark OK.
359         \end{itemize}
360         \item Click on \textit{New} to create the second pass job.  You will
361         see this second job in the listbox below.  Use the Video wrench and
362         change pass1 to pass2 as follows.
363         \begin{lstlisting}[style=sh]
364                 flags +pass2
365         \end{lstlisting}
366         \item Click checkmark OK.
367         \item Click on the \textit{Start} box and watch it go!
368         \item You can now check the output file for results.  At the time
369         this was documented, \textit{rc=2pass} will be in the output.
370 \end{enumerate}
371
372 If you need to re-render this, the Batch Render will still be set up
373 but you have to click on the \textit{Enabled} column in the listbox
374 to re-enable the jobs to run which puts an X there.  Click Start
375 again. You can reuse batch job using the \textit{save jobs} and
376 \textit{load jobs} buttons in the batch render dialog.
377
378 \paragraph{Render shortcuts for webm, h264, h265} are available by
379 using the option files that are already set up for this purpose.
380 Use the render menu as usual, with ffmpeg/mp4, choose h264 or h265
381 \textit{pass1of2\_h26x} for the video and
382 \textit{passes1and\-2\_h26x} for the audio; with ffmpeg/webm, choose
383 \textit{pass1of2\_vp9}.  When that is finished, you will have to use
384 the render menu again and this time for video, choose
385 \textit{pass2of2\_h26x} or \textit{pass2of2\_vp9}.  The logfile is
386 hard coded in the options file so will write over any currently
387 existing logfile if you do not change it before you start the
388 render.
389
390 \paragraph{Requirements for some other libraries} (used instead
391 of \textit{flags +pass1} \& \textit{passlogfile}):
392 \begin{description}
393         \item[x265:] add this line:
394         \begin{lstlisting}[style=sh]
395                 x265-params=pass=1:stats=/tmp/{temporary-log-file-name}.log
396         \end{lstlisting} at the time this document was written, you should
397         see in the output: \textit{stats-read=2}
398         \item[libvpx-vp9, xvid, and huffyuv:]~
399         \begin{lstlisting}[style=sh]
400                 cin_stats_filename /tmp/{temporary-log-file-name}.log
401                 flags +pass1 (or flags +pass2 for the second pass)
402         \end{lstlisting}
403 \end{description}
404
405 \textit{NOTE:} for vp9, the best Pixels is \textit{gbrp}
406
407 \subsection{Use case: High Efficiency Video Coding (HEVC)}%
408 \label{sub:use_case_hevc}
409
410 An example of video profile based on CRF, a quality-controlled
411 variable bitrate, instead of fixed quality scale (ABR).  HEVC
412 (H.265) was developed as a successor to AVC (H.264) to more
413 efficiently compress the future large amounts of data from 2/4/8k
414 videos.  In comparison to AVC, an average saving of around 30
415 percent can be assumed for the same quality.  Because HEVC is not
416 bound to any size format, it is suitable for virtually any image
417 size.
418
419 The following example is HD and FullHD oriented and produces a
420 picture quality similar to the Blu-ray with some limitations.  As
421 container Matroska (\texttt{.mkv}) is used, but also mp4 and others
422 are possible.
423
424 \begin{lstlisting}[style=sh]
425         matroska libx265
426         
427         # CRF 16 creates a balanced compromise
428         # between quality and file size.
429         crf=16
430         
431         # Preset changes encoding speed and generally
432         # degrades the overall result. Medium (default)
433         # always fits.
434         preset=medium
435         
436         # Additional parameters that are passed on to the codec.
437         # me=star improves the search for very fast
438         # movements, but slows down the encoding.
439         #x265-params=me=star
440         
441         # Keyint does FFmpeg automatically, otherwise
442         # the setting must match the frame rate.
443         #keyint_min=25
444         
445         # Profile does FFmpeg automatically.
446         #profile=high
447         
448         # Source sRBG and retention of color space.
449         # 720/1080=bt709 if no profile set. Useful
450         # for formats smaller than 720 if no lossy
451         # conversion is desired.
452         colorspace=bt709
453         color_trc=bt709
454         color_primaries=bt709
455         
456         # Output in 10 bit, prevents 8-bit step formation
457         pixel_format=yuv420p
458 \end{lstlisting}
459
460 \noindent \textit{NOTE:}
461
462 A CRF of 16 delivers satisfactory results in most cases. However, if
463 the video material is really \emph{grainy}, a CRF~16 can lead to
464 unwanted large files.  In this case, a trial export of perhaps one
465 minute should be performed. The resulting bit rate can be used to
466 correct the CRF to 17,\,18,\,19\ldots -- remember, a CRF of $0$ (zero)
467 means lossless, the higher the number the stronger the lossy
468 compression. The approximate calculation of the final file size can
469 be extrapolated from the sample export.
470
471 The color space information must be used explicitly so that it can
472 be included in the video. \CGG{} or FFmpeg does not write it by
473 itself. Without this information the players (e.\,g.\
474 \href{https://mpv.io/}{mpv}) stick to the dimensions of the video
475 and take the assumed color model from a table. With videos in the
476 dimensions from 720 to 1080 this is bt709. For smaller dimensions,
477 e.\,g.\ DVD, bt601 is assumed and for 4k and above it is
478 bt2020. Normally this is not a problem, but if you want to export a
479 FullHD without color loss to a smaller size like 576 for example,
480 you have to inform the encoder as well as the decoder of the
481 player. This also applies if the videos are to be loaded on video
482 platforms, where they are then converted into videos of different
483 sizes. It is a security measure to prevent false colors, such as the
484 color profiles in digital photos and the copies made from them.
485
486 The HEVC tuning has not been considered here, because it is is
487 rarely used and requires background knowledge.
488
489 Further links:
490 \begin{itemize}
491         \item \href{http://x265.readthedocs.org/en/default/}{x265
492                 Documentation}
493         \item \href{http://x265.readthedocs.org/en/latest/cli.html}{x265
494                 Command Line Options}
495         \item \href{http://x265.readthedocs.org/en/latest/presets.html}{x265
496                 Presets/Tuning}
497 \end{itemize}
498
499
500 \subsection{YouTube with \CGG{}}%
501 \label{sub:youtube_with_cinelerra}
502 \index{rendering!youtube preset}
503
504 To create a youtube or dailymotion video, you can easily follow the steps below.  You will have to learn a lot more about \CGG{} to take full advantage of its capabilities and make some really special videos, but this is just to get a start and to see the possibilities.
505
506 \begin{enumerate}
507         \item Start \CGG{}; usually you can do this by clicking on \CGG{} icon or key in \texttt{{cin\_path}/bin/cin}.
508         \item In the Program window on the lower left side of your screen, left mouse click the \textit{File} pulldown.
509         \item You will see \textit{Load files} as the second choice so left mouse click this and find your video file to
510         load, highlight it, and check the green checkmark in the lower left hand corner to get it loaded.
511         \item Edit your video in the Program window using the basic commands of:
512         \begin{itemize}
513                 \item play and then stop using the space bar
514                 \item move the mouse and then left click to move the insertion (location) pointer
515                 \item cut a section out by holding down the left mouse and drag, then key in “x” to cut or “c” to copy
516                 \item paste a copy or cut section by moving the insertion pointer, then key in “v”
517         \end{itemize}
518         \item Add a title by highlighting the \textit{Video Effects} in the right hand side Resources window; then
519         highlighting the \textit{Title} icon and dragging it to the Program window video track and dropping.
520         \item Click on the middle icon button (looks like a magnifying glass) on the brown colored Title bar to
521         bring up the Title window bottom text box and key in a title.
522         \item Use the \textit{File} pulldown to select \textit{Render} to create the desired video.  In the \textit{Render} window just next to the empty box to the right of the \textit{ffmpeg} file format, click on the down arrow shown there
523         to see the choices and pick \textit{youtube}.  Then move back up to key in the path and filename to render
524         to.  It will pick all of the defaults automatically for you so then just click on the green checkmark to
525         have it start.  There is a progress bar in the main window, very bottom of the right hand side.
526         \item Key in “q” in the main window to get out of \CGG{} and yes or no to save your edit session.
527 \end{enumerate}
528
529 Youtube will allow the upload of the resulting rendered file as named.  However, Dailymotion requires that the file be named with an acceptable extension so you must rename the output file to have the extension of .webm instead of .youtube
530
531 There are currently 6 specific variations within the ffmpeg (file format) / youtube (file type) for different video options.  You see these when you click on the wrench to the right of the word Video and then the Compression down arrow in the Video Preset window.  The first 3 are based on Webm/Vp9\protect\footnote{credit by Frederic Roenitz} and contain basic comments of usage and where to find more information.
532
533 The first 3 below, plus any of the VP9 files under the file type of \textit{webm} are the recommended options to use because they are freely usable in any circumstance.
534
535 \begin{center}
536         \begin{tabular}{lp{8cm}}
537                 \hline
538                 sd.youtube & Standard Definition use with default audio/Opus stereo.youtube \\
539                 hd.youtube & High Definition “ “ \\
540                 uhd.youtube & Ultra High Definition “ “ \\
541                 \hline
542         \end{tabular}
543 \end{center}
544
545 For more details and options on VP9, see: {\small\url{https://developers.google.com/media/vp9}}
546
547 Alternatives based on h264 and for non-commercial use are listed below.  For Dailymotion, these must be renamed to have a different extension of .mp4 instead of .youtube before uploading.
548
549 \begin{center}
550         \begin{tabular}{lp{8cm}}
551                 \hline
552                 sd\_h264.youtube & Standard Definition – must change to audio stereo\_with\_h264.youtube \\
553                 hd\_h264.youtube & High Definition -          “ “ \\
554                 uhd\_u264.youtube & Ultra High Definition - “ “ \\
555                 \hline
556         \end{tabular}
557 \end{center}
558
559 These same steps have been verified to work for creating Dailymotion videos -- however, the created files must be renamed before uploading to change the youtube extension to webm instead for Dailymotion.
560
561 \subsection{VP9 parameters}%
562 \label{sub:vp9_parameters}
563 \index{rendering!VP9 parameters}
564
565 \textsc{VP9}\protect\footnote{credit Frederic Roenitz} is a video codec licensed under the BSD license and is
566 considered open source,
567 % Sisvel Announces AV1 Patent Pool, March 10, 2020
568 % https://www.streamingmedia.com/Articles/ReadArticle.aspx?ArticleID=139636
569 %  Webm / VP9 is a media file format which is free to use under the
570 %  BSD license and is open-source; thus there are no licensing
571 %  issues to be concerned about.
572 the \textsc{Webm} container is based on \textsc{Matroska} for video
573 and \textsc{Opus} for audio. There are some common \textsc{VP9} rendering
574 options files that support creation of video for YouTube,
575 Dailymotion, and other online video services. YouTube easy startup steps are documented above.
576
577 Note: For VP9 and AV1 presets, two pass rendering is recommended, which provides higher quality.
578
579 Below is one of the \textsc{VP9} rendering options file with documentation for specifics:
580
581 \textbf{webm libvpx-vp9}
582
583 from {\small \url{https://developers.google.com/media/vp9/settings/vod/}}
584
585 1280x720 (24, 25 or 30 frames per second)
586
587 Bitrate (bit rate)
588
589 \textsc{VP9} supports several different bitrate modes:
590
591 \textit{mode:}
592
593 \begin{tabular}{p{6cm}p{10cm}}
594         \hline
595         Constant Quantizer (Q) & Allows you to specify a fixed quantizer value; bitrate will vary \\
596         Constrained Quality (CQ) & Allows you to set a maximum quality level. Quality may vary within bitrate parameters\\
597         Variable Bitrate (VBR) & Balances quality and bitrate over time within constraints on bitrate\\
598         Constant Bitrate (CBR) & Attempts to keep the bitrate fairly constant while quality varies\\
599         \hline
600 \end{tabular}
601
602 CQ mode is recommended for file-based video (as opposed to streaming). The following FFMpeg command-line parameters are used for CQ mode:
603
604 \textit{FFMpeg}:
605
606 \begin{center}
607         \begin{tabular}{p{4cm}p{10cm}}
608                 \hline
609                 -b:v <arg> & Sets target bitrate (e.g. 500k)\\
610                 -minrate <arg> & Sets minimum bitrate.\\
611                 -maxrate <arg> & Sets maximum bitrate.\\
612                 -crf <arg> & sets maximum quality level. Valid values are 0-63, lower numbers are higher quality.\\
613                 \hline
614         \end{tabular}
615 \end{center}
616
617 \textit{Note 1}: Bitrate is specified in kbps, or kilobits per second. In video compression a kilobit is generally assumed to be 1000 bits (not 1024).
618
619 \textit{Note 2:} Other codecs in FFMpeg accept the \textit{-crf} parameter but may interpret the value differently. If you are using \textit{-crf} with other codecs you will likely use different values for VP9.
620
621 \texttt{bitrate=1024k}\\
622 \texttt{minrate=512k}\\
623 \texttt{maxrate=1485k}\\
624 \texttt{crf=32}
625
626 \textit{Tiling} splits the video into rectangular regions, which allows multi-threading for encoding and decoding. The number of tiles is always a power of two. 0=1 tile; 1=2; 2=4; 3=8; 4=16; 5=32\\
627 \texttt{tile-columns=2}
628
629 (modified from {\small \url{https://trac.ffmpeg.org/wiki/EncodingForStreamingSites}})
630
631 To use a 2 second \textit{GOP} (Group of Pictures), simply multiply your output frame rate $\times$ 2. For example, if your input is \textit{-framerate 30}, then use \textit{-g 60}.\\
632 \texttt{g=240}
633
634 number of \textit{threads} to use during encoding\\
635 \texttt{threads=8}
636
637 \textit{Quality} may be set to good, best, or realtime\\
638 \texttt{quality=good}
639
640 \textit{Speed}: this parameter has different meanings depending upon whether quality is set to good or realtime. Speed settings 0-4 apply for VoD in good and best, with 0 being the highest quality and 4 being the lowest. Realtime valid values are 5-8; lower numbers mean higher quality\\
641 \texttt{speed=4}
642
643 \subsection{Piping Video to a Command Line}%
644 \label{sub:piping_video_command_line}
645 \index{rendering!command line}
646
647 You can pipe a video to any command line on the computer, such as
648 ffmpeg.  This can be especially useful with raw video files.  Next
649 is an example usage.
650
651 \begin{enumerate}
652         \item on a terminal window create a named pipe file, for example:
653         \begin{lstlisting}[style=sh]
654                 mknod /tmp/piper.yuv p
655         \end{lstlisting} load your video and do your editing
656         \item set up your Render (\texttt{Shift-R}), you can choose a raw
657         format such as \textit{yuv} or \textit{rgb}
658         \item for the filename \textit{Select a file to render to}, use the
659         named pipe as created in step 1 (\texttt{/tmp/piper.yuv})
660         \item for \textit{Insertion Strategy}, you will want to make sure to
661         select \textit{insert nothing}
662         \item click for OK on the green checkmark.(the \CGG{} gui will look
663         like it is hanging while waiting for a command line to use the
664         pipe.)
665         \item on the terminal window, keyin your command, for example:
666         \begin{lstlisting}[style=sh]
667                 /mnt0/build5/cinelerra-5.1/thirdparty/ffmpeg-3.4.1/ffmpeg -f \
668                 rawvideo -pixel_format yuv420p -video_size 1280x720 \
669                 -framerate 30000/1001 -i /tmp/piper.yuv /tmp/pys.mov
670         \end{lstlisting}
671 \end{enumerate}
672
673 A slightly different option can be used instead that may be more
674 familiar to some.  In the render menu after choosing the File Format
675 of \textit{ffmpeg}, use the pulldown to choose \textit{y4m} as the
676 file type.  This choice results in putting a header on the rendered
677 output with some pertinent information that can be used for ffmpeg
678 processing thus alleviating the requirement for
679 \textit{pixel\_format}, \textit{video\_size}, and \textit{framerate}
680 on the ffmpeg command line.  In this case the format is
681 \textit{yuv4mpegpipe} instead of \textit{rawvideo}.  An example
682 command line would look as follows (assuming the created pipe is
683 called \texttt{piper.y4m}):
684 \begin{lstlisting}[style=sh]
685         ffmpeg -f yuv4mpegpipe -i /tmp/piper.y4m -vcodec libx264 /tmp/test.mp4
686 \end{lstlisting}
687
688 \subsection{Faststart Option for MOV type files}%
689 \label{sub:faststart_option_mov0}
690
691 If you have mov video and want to be able to start playing without
692 having to first load the entire video, \textit{-movflags=+faststart}
693 is needed for ffmpeg to put the meta-data, known as the \textit{moov
694         atom}, at the beginning of the file.  Otherwise, ffmpeg puts this
695 atom at the end of the video file which means you have to wait to
696 play until the whole video is loaded.  Or worse yet, if the file
697 becomes damaged in the middle and you can not get to the end, you
698 won’t be able to play anything.
699
700 Now you can have the \textit{moov atom} put on the front of the file
701 (automatically via a second pass).  To do this, when rendering using
702 ffmpeg \& either the mp4 or qt format/container, click on the
703 video/audio wrenches and choose \textit{faststart\_h264}.  With the
704 \textit{qt} format, settings will just be the default whereas the
705 \textit{mp4} format uses the highest quality and lowest file size as
706 possible, but you can easily modify these options in the associated
707 Video Preset textbox.
708
709 \section{About Image Sequences}%
710 \label{sec:about_image_sequences}
711 \index{image sequence}
712
713 \CGG{} supports image sequences with both decoding and encoding.
714
715 \CGG{} by default uses ffmpeg as encoding/decoding engine but we can disable it to have the specific internal engine available. See \nameref{sec:ffmpeg_early_probe_explanation} on how to switch between engines. With the internal engine we can create and load sequences of OpenEXR; PNG; TIFF; TGA; GIF; PPM and JPEG. There is also support for DPX sequences, but only in read and without rendering presets. With ffmpeg we can create and load DPX sequences or create a custom preset for any kind of image. Using these formats results in great timeline efficiency and high video quality at the cost of taking up a lot of space because they are uncompressed (or with lossless compression).
716 By rendering, you will get as many still images as there are frames in the project, plus a \textit{file-list} (or \textit{TOC}) that indexes the images. A good practice is to create a folder to contain the images (for example \texttt{/tmp/img\_seq/}) and then open the rendering window in \CGG{} and set a serial and increasing number as the name (for example: \texttt{/tmp/img\_seq/image \%05d.png}). \textit{image} is a generic name chosen at will; $\%$ creates a progressive sequence of distinct images; $05d$ indicates how many digits the image number will be, in this case 5 digits to go from $00000$ to $99999$.
717 Once we have our folder of images, if we want to import it in a project just load the file-list, which includes the link to all the files of the sequence.
718 To learn more about using and creating a preset with ffmpeg of an image sequence, see \nameref{sec:ffmpeg_image2_streams} and/or \nameref{sec:image_sequence_creation}.
719
720 \section{Data storage formulas}%
721 \label{sec:data_storage_formulas}
722 \index{data storage}
723
724 If we are dealing with large projects and poorly compressed formats, we will get large files that are difficult to manage and take up a lot of space on the HDD. We present some simple formulas to be able to calculate the space that will be occupied and the data rates we have to deal with:
725
726 \begin{description}
727         \item[Frame size] 
728         
729         \[ \dfrac{Width \times Height [pixels] \times BitDepth [bits/pixel] \times Color}{8 [bit/Byte]} \]      
730         \[= ... [MB/frame] \]
731         \item[File size] 
732         
733         \[ Frame size [MB/frame] \times frames [frame] = ... [MB] \]
734         \item[Data Rate] 
735         
736         \[ Frame size [MB/frame] \times fps [frame/sec] = ... [MB/sec] \]
737         \item[Data in 1 Hour] 
738         
739         \[ \dfrac{Data Rate [MB/sec] \times 3600 [sec]}{1024MB/GB}  = ... [GB] \]       
740 \end{description}
741
742 \section{Batch Rendering}%
743 \label{sec:batch_rendering}
744 \index{batch rendering}
745
746 Batch Rendering as implemented in \CGG{} is considered to be more of
747 an advanced feature and careful usage is advised.  It automates the
748 rendering of audio/video files in that
749 you can establish a set of job parameters, save them, and use them
750 repeatedly (figure~\ref{fig:batch01}).  It also allows for \CGG{} to
751 be run by external programs, with no need for the user to manually
752 interact with the user interface.
753
754 \begin{figure}[htpb] \centering
755         \includegraphics[width=1.0\linewidth]{batch01.png}
756         \caption{Example of the Batch Render menu}
757         \label{fig:batch01}
758 \end{figure}
759
760 If you want to render many projects \index{project} to media files without having to
761 constantly set up the render dialog for each one, batch rendering is
762 a more efficient method of rendering. To use this feature you need to 
763 understand certain concepts.
764
765 \begin{enumerate}
766         \item  You must define a list of Batches (\textit{Job} \index{job}) before starting the rendering. This is created using the \textit{New} button and displayed in \textit{Batches to Render} dialog.
767         \item Each batch consists of a source project already created in \CGG{}, e.g. \texttt{aaa.xml}, to which we assign the rendering parameters.
768         \begin{itemize}
769                 \item to associate \texttt{aaa.xml} to the batch we use the \textit{EDL Path} input field.
770                 \item we decide a name and path for the output file.
771                 \item let's set the \textit{File Format} of the output file.
772                 \item We configure the file with the Audio/Video \textit{wrench}.
773                 \item we decide whether to create different files for each \textit{label} and whether to use a \textit{Render farm}.
774         \end{itemize}
775         \item Created the first batch, we will see it appear in the dialog \textit{Batches to Render}.
776         \item Using the \textit{New} button again we create a second batch for another source project (\texttt{bbb.xml}) and configure it at will.
777         \item We continue with the source projects \texttt{ccc.xml}, \texttt{ddd.xml}, etc. until we run out of projects that we want to render in batch.
778         \item Note that each batch has its own name, path and rendering parameters.
779         \item Now we have our \textit{Job}, a list of batches. We can still configure it or modify it if we want to change something. In addition we can delete a batch from the list or we can disable it in the \textit{Enabled} field so that it is not taken into account during rendering, but without deleting it.
780         \item Finally we start batch rendering with the \textit{Start} button.
781 \end{enumerate}
782
783 Let's see in detail how to set the Batch Rendering.
784
785 The first thing to do when preparing to do batch rendering is to
786 create one or more \CGG{} projects to be rendered and save them as a
787 normal project, such as \texttt{aaa.xml}.  The batch renderer
788 requires a separate project file for every batch to be rendered.
789 You can use the same \CGG{} project file if you are rendering to
790 different output files, as in an example where you might be creating
791 the same output video in different file formats.
792
793 You do not have to render an entire projects. We can limit ourselves to an \textit{active region} \index{active region} that we can set through a selection in Cut and Paste mode, with labels or In/Out Points. Or the rendering will start from the Insert Point position until the end of the project. Remember: if we want to render the entire project (and not just one active region) it is important to bring the Insertion Point to the beginning of the timeline. This is the only way we are sure to include the whole project.
794
795 With all the \CGG{} xml project files prepared with active regions,
796 go to \texttt{File $\rightarrow$ Batch Render}. This brings up the
797 batch render dialog. The interface for batch rendering is more
798 complex than for single file rendering.  A list of batches must be
799 defined before starting a batch rendering operation.  The table of
800 batches appears on the bottom of the batch render dialog and is
801 called \textit{Batches to render}.  Above this are the configuration
802 parameters for a single batch; a batch is simply a pairing of a
803 project file with a choice of output file and render settings.
804
805 It may be advisable to start with a \textit{Delete} so you don't have any problems. Set the \textit{Output path}, \textit{File format}, \textit{Audio},
806 \textit{Video}, and \textit{Create new file at each label}
807 parameters as if you were rendering a single file.  These parameters
808 apply to only one batch.  In addition to the standard rendering
809 parameters, you must select the \textit{EDL Path} to be the project
810 file (such as \texttt{aaa.xml}) that will be used in the batch
811 job.  In this case, \textit{EDL Path} is not related in anyway with
812 the EDL files as created by \texttt{File/Export EDL}.  In batch
813 render mode the program will not overwrite an existing output file
814 and will simply fail, so make sure that no files with the same name
815 as the output files exist before starting.
816
817 If the batches to render list is empty or nothing is highlighted,
818 click \textit{New} to create a new batch. The new batch will contain
819 all the parameters you just set.  Repeatedly press the \textit{New}
820 button to create more batches with the same parameters.  When you
821 highlight any batch, you can edit the configuration on the top of
822 the batch render window. The highlighted batch is always
823 synchronized to the information displayed.  You can easily change
824 the order in which the batch jobs are rendered, by clicking and
825 dragging a batch to a different position.  Hit \textit{Delete} to
826 permanently remove a highlighted batch. In the list box is a column
827 which enables or disables the batch with an \texttt{X} meaning the
828 batch job is enabled and will be run.  This way batches can be
829 skipped without being deleted.  Click on the \textit{Enabled} column
830 in the list box to enable or disable a batch.
831
832 The description of each of the columns in the batch list are as
833 follows:
834
835 \begin{description}
836 \item[Enabled:] an X in this column means the batch job will be run.
837 \item[Labeled:] an \texttt{X} in this column goes hand in hand with
838   create new file at each label.
839 \item[Farmed:] to use or not the render farm.
840 \item[Output:] path and filename for the generated output.
841 \item[EDL:] the path and filename of the source EDL for the batch
842   job.
843 \item[Elapsed:] the amount of time taken to render the batch if
844   finished.  If field is empty, it did not run.
845 \end{description} 
846
847 The \texttt{File $\rightarrow$ Batch Render} pulldown brings up the
848 Batch Render window to be used for batch rendering as well as DVD/BD
849 creation.  There are some additional buttons that can save time and
850 mistakes.  These are described next.
851
852 \begin{description}
853         \item[Save Jobs] when you have set up the batch jobs the way you
854         want and you think you may have to run them more than once, it is
855         beneficial to save the jobs for later use so you easily run them
856         again.  It is recommended to use a filename with .rc as the extension
857         so that it is obvious that it is a list of batch jobs to be run.
858         \item[Load Jobs] reload a previous set of saved jobs.  This can come
859         in handy if you did not have the time to render them when you
860         originally set them up, if you need to rerun, or if you got
861         interrupted.
862 \end{description}
863
864 To start rendering from the first enabled batch,
865 hit \textit{Start}.  Once rendering, the main window shows the
866 progress of the batch. After each batch finishes, the elapsed column
867 in the batch list is updated and the next batch is rendered until
868 all the enabled batches are finished.  The currently rendering batch
869 is always highlighted red.  To stop rendering before the batches are
870 finished without closing the batch render dialog, hit \textit{Stop}.
871 To stop rendering before the batches are finished and close the
872 batch render dialog, hit \textit{Close}.  Or you can exit the batch
873 render dialog whether or not anything is being rendered, by hitting
874 \textit{Close}.
875
876 You can automate \CGG{} batch renders from other programs.  In the
877 batch render dialog, once you have created your list of batch render
878 jobs, you can click the button \textit{Save Jobs} and choose a file
879 to save your batch render list to.  It is recommended that you use
880 a filename with the extension of .rc in order to make it obvious that
881 this is a list of batch jobs to render. Once you have created this file,
882 you can start up a batch render without needing to interact with the
883 \CGG{} user interface.  From a shell prompt, from a script, or other
884 program, execute:
885
886 \begin{lstlisting}[style=sh]
887 {path_to_cinelerra}/cin -r batchjob.rc
888 \end{lstlisting} substituting your actual filename for
889 \texttt{batchjob.rc}. \textbf{Warning} this file will be modified
890 so if you use any filename that is not a legitimate list of batch jobs to
891 render, that file will be overwritten and its previous contents destroyed.
892 When invoked with these parameters, \CGG{} will start up and run the
893 rendering jobs in the list contained in that file starting at the defined
894 \textit{active region}, without creating its usual windows. If you do not
895 specify a filename, the default will be \$HOME/.bcast5/batchrender.rc.
896 Possible messages you might see where you started up the job are as follows.
897 \begin{description}
898 \item[The following files exist: - filename - Won't overwrite existing files] that batch job will not run in order to prevent writing over previous run.
899 \item["filename" No such file or directory] the specified batch job file does not exist.
900 \item["filename": Permission denied] the specified batch job file does not have write permission so can not be updated.
901 \item[Render::run: filename] the batch job with the name of filename will be processed.
902 \item[** rendered 0 frames in 0.000 secs, 0.000 fps] either you used a file that is not a list of batch jobs or the batch jobs within the file were not enabled.
903 \end{description}
904
905 \subsection{Advanced features}%
906 \label{sub:advanced_features}
907 \index{batch rendering!more options}
908
909 \textbf{Warning}: \textit{Save to EDL path} overwrites the current EDL thus destroying the original contents.
910
911 Although the operation of Batch Rendering in \CGG{} is similar to that of other NLEs, there is one big difference that we need to take into account. The render setup is not done on a project-by-project basis, which are then brought into the Batch window to be rendered automatically. The setup must be done in the Batch rendering window, where various projects are loaded and set up. In the case of similar projects, derived from a single EDL with some variation, this mode offers the possibility of altering the projects without having to open each individual project, make the changes, set up the rendering, save and import into the Batch window. The procedure is to select the batch we want to modify in the Batches to render window; operate on the currently open timeline (even if it does not correspond to the one we want to modify) making the desired changes and then press the \textit{Save to EDL path} button. Thus the chosen batch, while retaining its original name, will now contain the modified project. Since this possibility destroys the original EDL overwriting it with the modified one, you must be very careful. This procedure is convenient in case the batches are similar, i.e. they are variations of the same EDL, where we want to experiment with other effects, other output formats or when trying out various cuts of a DVD/BD before the final production. It might also be useful to use an \textit{active region} of the timeline, so as to speed up rendering times but still have an indicative result for comparison. Instead operating on different projects, we can do a \textit{save as...} of the project on the timeline to have a new EDL with a new name and then replace it with the batch selected in the joblist using the \textit{Use Current EDL} button. The new project (with its name) overwrites the original project.
912
913 The \textit{Save to EDL Path} and \textit{Use Current EDL} buttons
914 can be valuable tools for advanced usage or for developers doing
915 testing.  Description of how you can expect them to work will help
916 to illustrate how to take advantage of their capabilities (figure~\ref{fig:batch-advanced}):
917
918 \begin{figure}[htpb] \centering
919         \includegraphics[width=0.7\linewidth]{batch-advanced.png}
920         \caption{New Buttons with Unsafe GUI in batchrender}
921         \label{fig:batch-advanced}
922 \end{figure}
923
924
925 \begin{description}
926 \item[Save to EDL Path] Warning: this function overwrites the contents of the original EDL with new data, keeping the name of the original. If we don't know exactly what we're doing we may lose the original project. If you have made a change to the EDL, use
927   this button to save the changes so that they will be used in the
928   render operation.  Although you can get the same results by using
929   \texttt{File $\rightarrow$ Save\dots}, this capability was initially
930   added to assist developers in testing the batch jobs needed to
931   create dvd/bluray media as it keeps the work focused in a single
932   window and retains the original job name.  An example --you have
933   everything all set up with a new job in the Batch Render window
934   using \texttt{generic.xml} for the EDL path and with a job name of
935   \texttt{original\_name.xml}.  Then you realize that you forgot to
936   cut out a section in the media that is not wanted in the final
937   product.  You can cut that out and then \textit{Save to EDL Path} so
938   your change will be in effect for the rendering.  Without this
939   button, you would be using the EDL you started with and the cut
940   would be ignored.  Alternatively, if the cut changes are saved via
941   \texttt{File $\rightarrow$ Save as}\dots with a filename of
942   \texttt{new.xml} and then you use \textit{Save to EDL Path}, the
943   current highlighted job displayed in the window as
944   \texttt{original\_name.xml} will be replaced with \texttt{new.xml}.
945   However, it is important to note that the result will be saved with
946   the name \texttt{original\_name} – that is, the new content from
947   \texttt{new.xml} but with the old name of
948   \texttt{original\_name.xml}. To have this functionality we have to enable the checkbox in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab; section \textit{Dangerous:} and unchecked (default) \textit{Unsafe GUI in batchrender}.
949 \item[Use Current EDL] Warning: this function overwrites the contents of the original EDL with new project. If we don't know exactly what we're doing we may lose the original project. if you are working on media and still testing
950   out the results, you can take advantage of this click-box to quickly
951   get results.  Basically, you change the media, save that change with
952   another name (in order to preserve the original name in case you
953   don't like the changes), and press \textit{Use Current EDL}.  As an
954   example, a user creates a new job in the Batch Render window using
955   the current media, previously defined in generic.xml, with the EDL
956   path of \texttt{generic.xml}.  The user then changes the media on
957   the timeline, saves the changes via \texttt{File $\rightarrow$ Save
958     as\dots} with a new name, such as \texttt{new\_name.xml}, and then
959   clicks on \textit{Use Current EDL}.  In this case, the EDL path
960   listbox will be automatically updated to the \texttt{new\_name.xml}
961   and the current existing highlighted job will be replaced with the
962   \texttt{new\_name.xml} in the EDL column.
963 \item[Warn if Jobs/Session mismatched] Warning: It is better to keep this function unchecked because it is only needed in case of changes on the original EDL. By default it is hidden and is shown only if we enable the checkbox in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab; section \textit{Dangerous:} and checked \textit{Unsafe GUI in batchrender}. After you set up your render
964   and press Start, the program checks to see if the current EDL
965   session matches your Batch Render job.  If the EDL has been changed
966   since the batch job was created, it warns you so that you have the
967   opportunity to \textit{Save to EDL} path to record those changes.
968   Otherwise, you can dismiss that warning box, disable the warning
969   message by unchecking the box and use the original values.  If you
970   never want to be warned about the mismatches, leave the box
971   unchecked (figure~\ref{fig:batch02}). It is advisable to keep it unchecked because it can cause problems.
972 \end{description}
973
974 \begin{figure}[htpb] \centering
975         \includegraphics[width=0.9\linewidth]{batch02.png}
976         \caption{Batch render with the 4 ghosted buttons on the right side
977                 + the Warning message below}
978         \label{fig:batch02}
979 \end{figure}
980
981 A very clear tutorial on these features can be found \href{https://linuxvideoediting.blogspot.com/2021/01/save-edl-path-use-current-edl-in-cinelerra-gg.html}{here}\protect\footnote{credit Igor Vladimirsky}; in Russian but easily translatable with DeepL or similar.
982
983 \subsection{Command Line Rendering}%
984 \label{sub:command_line_rendering}
985 \index{rendering!command line}
986
987 The command line rendering method consists of a way to load the
988 current set of batch rendering jobs and process them without a
989 GUI\@. This is useful if you want to do rendering on the other side
990 of a low bandwidth network and you have access to a high powered
991 computer located elsewhere. Setting up all the parameters for this
992 operation is somewhat difficult. That is why the command line aborts
993 if any output files already exist.
994
995 To perform rendering from the command line, first run \CGG{} in
996 graphical mode. Go to \texttt{File $\rightarrow$ Batch Render}.
997 Create the batches you intend to render in the batch window and
998 close the window.  This automatically saves the batches in a file 
999 with the name of \$HOME/.bcast5/batchrender.rc. Set up the
1000 desired render farm attributes in \texttt{Settings $\rightarrow$
1001   Preferences} and quit out of \CGG{} if you want to use the Render
1002 Farm capability.  These settings are used the next time command line
1003 rendering is used to process the current set of batch jobs without a
1004 GUI\@.  It is important to remember that the rendering will begin at
1005 the defined \textit{active region} saved when the project was saved. 
1006
1007 On the command line run:
1008
1009 \begin{lstlisting}[style=sh]
1010 cin -r
1011 \end{lstlisting}
1012
1013 \section{Background Rendering}%
1014 \label{sec:background_rendering}
1015 \index{background rendering}
1016
1017 Background rendering causes temporary output to be rendered
1018 constantly while the timeline is being modified. The temporary
1019 output is displayed during playback whenever possible. This is
1020 useful for transitions and previewing effects that are too slow to
1021 display in real time. If a Render Farm \index{render farm} is enabled, the render farm
1022 is used for background rendering. This gives you the potential for
1023 real-time effects if enough network bandwidth and CPU nodes exist.
1024
1025 Background rendering is enabled in the \texttt{Performance} tab of
1026 the \texttt{Preferences} window. It has one interactive function
1027 \texttt{Settings $\rightarrow$ Toggle background rendering} \index{background rendering!toggle}. This
1028 sets the point where background rendering starts up to the position
1029 of the insertion point. If any video exists, a red bar appears in
1030 the time ruler showing what has been background rendered
1031 (figure~\ref{fig:back-ren02}).  Because this creates a very large number 
1032 of files, a Shell Command script is available to delete them if in the
1033 default location.
1034
1035 \begin{figure}[htpb] \centering
1036   \includegraphics[width=1.0\linewidth]{back-ren02.png}
1037   \caption{Settings Background Rendering}
1038   \label{fig:back-ren02}
1039 \end{figure}
1040
1041 It is often useful to insert an effect or a transition and then
1042 select \texttt{Settings $\rightarrow$ Toggle background rendering}
1043 right before the effect to preview it in real time and full frame
1044 rates (figure~\ref{fig:back-ren}).
1045
1046 \begin{figure}[htpb] \centering
1047   \includegraphics[width=1.0\linewidth]{back-ren.png}
1048   \caption{Timeline with the top red bar}
1049   \label{fig:back-ren}
1050 \end{figure}
1051
1052 \begin{description}
1053 \item[Frames per background rendering job] This only works if a
1054   Render Farm is being used; otherwise, background rendering creates a
1055   single job for the entire timeline. The number of frames specified
1056   here is scaled to the relative CPU speed of rendering nodes and used
1057   in a single render farm job. The optimum number is 10 - 30 since
1058   network bandwidth is used to initialize each job.
1059 \item[Frames to preroll background] This is the number of frames to
1060   render ahead of each background rendering job. Background rendering
1061   is degraded when preroll is used since the jobs are small. When
1062   using background rendering, this number is ideally 0. Some effects
1063   may require 3 frames of preroll.
1064 \item[Output for background rendering] Background rendering
1065   generates a sequence of image files in a certain directory. This
1066   parameter determines the filename prefix of the image files. It
1067   should be accessible to every node in the render farm by the same
1068   path. Since hundreds of thousands of image files are usually
1069   created, ls commands will not work in the background rendering
1070   directory. The browse button for this option normally will not work
1071   either, but the configuration button for this option works. The
1072   default value will be /tmp/brender .  Because using background
1073   rendering creates a voluminous number of brender numbered files,
1074   a Shell Command script is available to delete them if they are
1075   in the default /tmp/brender format.
1076 \item[File format] The file format for background rendering has to
1077   be a sequence of images. The format of the image sequences
1078   determines the quality and speed of playback. JPEG generally works
1079   well and is the default.
1080 \end{description}
1081 Tip: If you have rendered your whole project with \textit{File format}
1082 set to JPEG and there are no missing numbers in the sequence, you can
1083 create a video from that sequence outside of \CGG{}.
1084 For example, if using the default output so that your files are named
1085 /tmp/brender000000, /tmp/brender000001, ... in a window, you would type:
1086
1087 \begin{lstlisting}[style=sh]
1088 ffmpeg -f image2 -i /tmp/brender0%5d -c:v copy brender.mov
1089 \end{lstlisting}
1090 which would create the video file brender.mov -  be sure to delete
1091 existing brender files before creating a new sequence to ensure there
1092 are no missing numerical values in the sequence.
1093
1094 \section{Render Farm Usage}%
1095 \label{sec:render_farm_usage}
1096 \index{render farm}
1097
1098 Render Farm uses background rendering, a feature of \CGG{} where the
1099 video is rendered in the background, to speed up rendering
1100 significantly.  Because rendering is memory and cpu intensive, using
1101 multiple computers on a network via a render farm is a significant
1102 gain. With \CGG{} installed on all nodes, the master node and the clients communicate via a network port that you specify.
1103 The Master node is the one of the instance of \CGG{} that we normally start with its gui; the other nodes are the instances of \CGG{} that we decide to start in parallel from the terminal to create the Render farm (clients).
1104 \CGG{} can distribute the rendering tasks over the network to the
1105 other computers of the Render Farm; or among all threads of a multicore CPU.  The render farm software tries
1106 to process all of the rendering in parallel so that several
1107 computers can be used to render the results.  The \textit{Total jobs
1108 to create} in the setup or labels on the timeline are used to divide
1109 a render job into that specified number of tasks.  Each background
1110 job is assigned a timeline segment to process and the jobs are sent
1111 to the various computer nodes depending upon the load balance.  The
1112 jobs are processed by the nodes separately and written to individual
1113 files.  You will have to put the files back together via a load with
1114 concatenation, or typically by using a command line tool from a
1115 script.
1116
1117 \subsection{Basic Steps to Start a Render Farm}%
1118 \label{sub:basic_steps_start_render_farm}
1119
1120 The following steps are just a guideline to start your render farm.
1121 It is assumed that you already have the master and client nodes
1122 communication, shared filesystem, permissions and usernames synched.
1123 Let's take the example of a network with 2 PCs: the master and the client. On the client we set 5 tasks; on the master we set 2 tasks.
1124
1125 \begin{enumerate}
1126 \item On the master computer, use \texttt{Settings} $\rightarrow$
1127   \texttt{Preferences} $\rightarrow$ \texttt{Performance} \texttt{tab}
1128   to set up a Render Farm:
1129   \begin{itemize}
1130   \item check the \textit{Use render farm} box;
1131   \item in the \textit{Hostname} box, keyin your hostname or ip
1132     address such as 192.168.1.12 or \textit{localhost} when using a single computer with a multicore CPU;
1133   \item enter in a port number such as 401--405 (only a root user
1134     can use privileged ports) or $10650...$ for non-root and click on \textit{Add Nodes}. To find a range of free ports to use you can look at the file \texttt{/etc/services};
1135   \item you will see something like the following in the Nodes
1136     listbox to the right:\newline
1137     \begin{tabular}{lllc}
1138         \hline
1139         On & Hostname & Port & Framerate\\
1140         \hline
1141         X & 192.168.1.12 & 10650 & 0.0 \\
1142         X & 192.168.1.12 & 10651 & 0.0 \\
1143         X & 192.168.1.12 & 10652 & 0.0 \\
1144         X & 192.168.1.12 & 10653 & 0.0 \\
1145         X & 192.168.1.12 & 10654 & 0.0 \\
1146         X & localhost & 10655 & 0.0 \\
1147         X & localhost & 10656 & 0.0 \\
1148         \hline
1149     \end{tabular}
1150   \item set the Total number of jobs to create. This number only pertains to client nodes, so we do not need to consider the master node;
1151   \item click OK on the bottom of the Preferences window.
1152   \end{itemize}
1153 \item For external network nodes, now we must join the nodes created to instances of \CGG{}. On the client computers ($192.168.1.12$), on the terminal, start 5 background  \CGG{} tasks via:
1154 \begin{lstlisting}[style=sh]
1155 cd {path_to_cinelerra}
1156 cin -d 10650 
1157 cin -d 10651
1158 ...
1159 cin -d 10654
1160 \end{lstlisting}
1161 In practice, at each instance that we start, the cursor will be positioned in a new line ready to enter the next command, without exiting the task. If we have several PCs on the network, repeat these steps for each new client (with its own ip address).
1162 \item Similarly, on the terminal, we must join the local nodes (internal to the Master node) created to instances of \CGG{}. On the Master node (localhost), start the 2 background \CGG{}  tasks via:
1163 \begin{lstlisting}[style=sh]
1164 cd {path_to_cinelerra}
1165 cin -d 10655
1166 cin -d 10656
1167 \end{lstlisting}
1168 Similar to the previous point, the cursor positions itself in a new line ready to enter the next command, without exiting the task.
1169 \item When your video is ready, setup a render job via \texttt{File
1170     $\rightarrow$ Render} or \texttt{File $\rightarrow$ Batch Render}
1171   and check OK.
1172 \item The results will be in the shared file \texttt{path/filename}
1173   that you selected in the render menu with the additional numbered
1174   job section on the end as $001, 002, 003, \dots 099$ (example,
1175   \texttt{video.webm001}).
1176 \item When finished, load your new files on new tracks via
1177   \texttt{File $\rightarrow$ Load} \textit{concatenate to existing
1178     tracks} or if you used ffmpeg, run \textit{RenderMux} from the Shell
1179   Scripts icon.
1180 \item If you plan on doing more rendering, you can just leave the
1181   master/client jobs running to use again and avoid having to restart
1182   them. You can also close the terminal, but the jobs will remain active until you turn off the PC. Or you can kill them when you no longer are using them.
1183 \end{enumerate}
1184
1185 \subsection{Render Farm Menu and Parameter Description}%
1186 \label{sub:render_farm_parameter_description}
1187 \index{render farm!parameters}
1188
1189 Below we describe the Performance tab for configuring a render farm
1190 (figure~\ref{fig:farm}).
1191
1192 \begin{figure}[htpb] \centering
1193   \includegraphics[width=1.0\linewidth]{farm.png}
1194   \caption{Settings: Preferences: Performance tab, menu
1195     to set up your Render Farm}
1196   \label{fig:farm}
1197 \end{figure}
1198
1199 \begin{description}
1200 \item[Project SMP cpus] although this field is not Render Farm
1201   specific, it is useful for \CGG{} to have the CPU count and for
1202   using multiple threads.
1203 \item[Use render farm] check this to turn on the render farm option.
1204   Once checked ALL rendering will be done via the farm including the
1205   usual Render (\texttt{Shift-R}).  You may want to turn if off for
1206   small jobs.
1207 \item[Nodes listbox] displays all the nodes on the render farm and
1208   shows which ones are currently enabled. The Nodes listbox has 4
1209   columns -- On, Hostname, Port, Framerate -- which show the current
1210   values.  An \textit{X} in the \textit{On} designates that that host
1211   is currently enabled; \textit{Hostname} shows the name of the host;
1212   \textit{Port} shows the port number that host uses; and
1213   \textit{Framerate} will either be zero initially or the current
1214   framerate value.
1215 \item[Hostname] this field is used to edit the hostname of an
1216   existing node or enter a new node.
1217 \item[Port] keyin the port number of an existing or new node here.
1218   You can also type in a range of port numbers using a hyphen, for
1219   example $10650-10799$ when you need to add many.
1220 \item[Apply Changes] this will allow you to edit an existing node
1221   and to then commit the changes to hostname and port. The changes
1222   will not be committed if you do not click the OK button.
1223 \item[Add Nodes] Create a new node with the hostname and port
1224   settings.
1225 \item[Sort nodes] sorts the nodes list based on the hostname.
1226 \item[Delete Nodes] deletes whatever node is highlighted in the
1227   nodes list.  You can highlight several at once to have them all
1228   deleted.
1229 \item[Client Watchdog Timeout] a default value of $15$ seconds is
1230   used here and the tumbler increments by $15$ seconds.  A value of
1231   $0$ (zero) disables the watchdog so that if you have a slow client,
1232   it will not kill the render job while waiting for that client to
1233   respond.
1234 \item[Total jobs to create] determines the number of jobs to
1235   dispatch to the render farm.  Total jobs is used to divide a render
1236   job into that specified number of tasks.  Each background job is
1237   assigned a timeline segment to process.  The render farm software
1238   tries to process all of the rendering in parallel so that several
1239   computers can be used to render the results.  You should adjust
1240   this for each different video if your work varies considerably in
1241   time so that each task time is not too small.
1242
1243   To start, if you have computers of similar speed, a good number
1244   for \textit{Total jobs to create} is the number of computers
1245   multiplied by $3$.  You will want to adjust this according to the
1246   capabilities of your computers and after viewing the framerates.
1247   Multiply them by $1$ to have one job dispatched for every node.  If
1248   you have $10$ client nodes and one master node, specify $33$ to have
1249   a well balanced render farm.
1250 \item[(overridden if new file at each label is checked)] instead of
1251   the number of jobs being set to \textit{Total jobs to create}, there
1252   will be a job created for each labeled section.  If in the render
1253   menu, the option \textit{Create new file at each label} is selected
1254   when no labels exist, only one job will be created.  It may be quite
1255   advantageous to set labels at certain points in the video to ensure
1256   that a key portion of the video will not be split into two different
1257   jobs.
1258 \item[Reset rates] sets the framerate for all the nodes to $0$.
1259   Frame rates are used to scale job sizes based on CPU speed of the
1260   node.  Frame rates are calculated only when render farm is enabled.
1261 \end{description}
1262
1263 Framerates can really affect how the Render Farm works.  The first
1264 time you use the render farm all of the rates are displayed as $0$
1265 in the \texttt{Settings $\rightarrow$ Preferences}, Performance tab
1266 in the Nodes box.  As rendering occurs, all of the nodes send back
1267 framerate values to the master node and the preferences page is
1268 updated with these values.  A rate accumulates based on speed.  Once
1269 all nodes have a rate of non-zero, the program gives out less work
1270 to lower rated nodes in an effort to make the total time for the
1271 render to be almost constant.  Initially, when the framerate scaling
1272 values are zero, the program just uses package length -- render size
1273 divided by the number of packages to portion out the work (if not
1274 labels).  If something goes wrong or the rates become suspect, then
1275 all of the rest of the work will be dumped into the last job.  When
1276 this happens, you really should \textit{reset rates} for the next
1277 render farm session to restart with a good balance.
1278
1279 \begin{lstlisting}[style=sh]
1280 {path_to_cinelerra}/cin -h  # displays some of the options.
1281 \end{lstlisting}
1282
1283 \subsection{Multi-core CPU Setup (Localhost)}%
1284 \label{sub:multi_core_render_farm_setup}
1285 \index{render farm!multi core CPU}
1286
1287 If you are lucky enough to have a computer with a large cpu core
1288 count, setting up a render farm can really take advantage of using
1289 all of the cores at 100\%. This is much faster than the default automatic
1290 threading capability. Since you don’t need to communicate with other
1291 computers, you will not have to be concerned about TCP communication
1292 or shared disks/files; only localhost nodes. On the terminal you will need to open many instances of \CGG{} by connecting them to the jobs created. The number of such jobs can be the total number of CPU threads (-1) or not. When you are going to be doing other work
1293 simultaneously while rendering a large job, you will want to leave
1294 some of the cpus available for that.  Be sure to set \textit{Project SMP cpus} in the \texttt{Settings $\rightarrow$ Preferences, Performance} tab to your CPU
1295 count.  Follow the steps outlined in ~\ref{sub:basic_steps_start_render_farm}
1296 but skip the step "For external network nodes".
1297
1298 \subsection{Detailed Setup Description}%
1299 \label{sub:detailed_setup_description}
1300 \index{render farm!setup}
1301
1302 {\color{red} CAUTION }, any exact command lines worked as of
1303 $01/2018$ on a Fedora system.  These can change over time and on
1304 different operating systems/levels.  Always check/verify any command
1305 line before using.
1306
1307 \begin{description}
1308 \item[Set up \CGG{}] A \CGG{} render farm is organized into a master
1309   node and any number of client nodes.  The master node is the
1310   computer which is running the gui.  The client nodes are anywhere
1311   else on the network with \CGG{} installed and are run from the
1312   command line.  Before you start the master node for \CGG{}, you need
1313   to set up a shared filesystem on the disk storage node as this is
1314   the node that will have the common volume where all the data will be
1315   stored.  The location of the project and its files should be the
1316   same in the client computers as in the master computer and to avoid
1317   problems of permissions, it is better to use the same user in master
1318   and clients.  For example, if you have the project in
1319   \texttt{/home/<user>/project-video} you must create the same
1320   directory path on the clients, but empty.  Sharing the directory of
1321   the location of your project on the master computer can be done with
1322   NFS as described next.  Alternatively, you can look up on the
1323   internet how to use Samba to share a directory.
1324 \item[Create a shared filesystem and mount using NFS] (only for Network) All nodes in
1325   the render farm should use the same filesystem with the same paths
1326   to the project files on all of the master and client nodes.  This is
1327   easiest to do by setting up an NFS shared disk system.
1328   \begin{enumerate}
1329   \item On each of the computers, install the nfs software if not
1330     already installed.  For example, on Debian 9 you will need to run:
1331     (be sure to check/verify before using any command line):
1332 \begin{lstlisting}[style=sh]
1333 apt-get install nfs-kernel-server
1334 \end{lstlisting}
1335   \item On the computer that contains the disk storage to be shared,
1336     define the network filesystem.  For example to export \texttt{/tmp},
1337     edit the \texttt{/etc/exports} file to add the following line:
1338 \begin{lstlisting}[style=sh]
1339  192.168.1.0/24(rw,fsid=1,no_root_squash,sync,no_subtree_check)
1340 \end{lstlisting}
1341   \item Next reset the exported nfs directories using:
1342 \begin{lstlisting}[style=sh]
1343 exportfs -ra
1344 \end{lstlisting} and you may have to start or restart nfs:
1345 \begin{lstlisting}[style=sh]
1346 systemctl restart nfs
1347 \end{lstlisting}
1348   \item Each of the render farm computers must mount the exported
1349     nfs target path.  To see the exports which are visible from a
1350     client, login as root to the client machine and keyin:
1351 \begin{lstlisting}[style=sh]
1352 showmount -e <ip-addr> #using the ip address of the storage host
1353 \end{lstlisting}
1354   \item to access the host disk storage from the other computers in
1355     the render farm, mount the nfs export on the corresponding target
1356     path: (be sure to check/verify before using any command line):
1357 \begin{lstlisting}[style=sh]
1358 mount -t nfs <ip-addr>:/<path> <path>
1359 \end{lstlisting} where \texttt{<path>} is the storage host
1360     directory, and \texttt{<ip-addr>} is the network address of the
1361     storage host.  Because all of the computers must have the same
1362     directory path, create that same directory path with the same
1363     uid/gid/permissions on each storage client computer ahead of time.
1364   \item To make this permanent across reboots on the client nodes,
1365     add the following line to \texttt{/etc/fstab}:
1366 \begin{lstlisting}[style=sh]
1367 {masternode}:/nfsshare /mnt nfs defaults 0 0
1368 \end{lstlisting} You can make this permanent on the disk storage
1369     host BUT the command lines shown, which were correct in January 2018
1370     on Fedora, may be different for your operating system or in the
1371     future.  In addition if your network is not up, there may be
1372     numerous problems.  If you make a mistake, your system may not boot.
1373     To make permanent, add the following line to \texttt{/etc/fstab}:
1374 \begin{lstlisting}[style=sh]
1375 192.168.1.12:/tmp /tmp nfs rw,async,hard,intr,noexec,noauto 0 0
1376 \end{lstlisting} You will still have to mount the above manually
1377     because of the \textit{noauto} parameter but you won’t have to
1378     remember all of the other necessary parameters.  Depending on your
1379     expertise level, you can change that.
1380
1381     Later, to remove access to the storage host filesystem:
1382 \begin{lstlisting}[style=sh]
1383 umount <path>
1384 \end{lstlisting}
1385
1386     Be aware that you may have to adjust any security or firewalls
1387     you have in place.  \textit{Most firewalls will require extra rules
1388       to allow nfs access}.  Many have built-in configurations for this.
1389   \end{enumerate}
1390 \item[Configure Rendering on Master Node] There is 1 master node
1391   which is running the \CGG{} gui and where the video will be edited
1392   and the command given to start up the rendering.  Any number of
1393   client computers can be run from the command line only, so they can
1394   be headless since no X or any graphical libraries are needed.  Of
1395   course, the \CGG{} software must be installed on each of the client
1396   computers.
1397   \begin{enumerate}
1398   \item Assuming you already have \CGG{} installed on the master
1399     node, start \CGG{} by clicking on the icon or by typing the
1400     following command on the terminal screen:
1401     \texttt{/{cinelerra\_path}/cin}.
1402   \item Use the \textit{File} pulldown \texttt{Settings $\rightarrow$
1403       Preferences}, the Performance tab, to set up your Render Farm
1404     options in the Render Farm pane.
1405   \item Check the \textit{Use render farm} option.  By default, once
1406     you enable the option of Render Farm, rendering is usually done
1407     using the render farm.  Batch rendering can be done locally, or
1408     farmed.
1409   \item Add the hostname or the IP address of each of the client
1410     nodes in the Hostname textbox and the port number that you want to
1411     use in the Port textbox.  You can make sure a port number is not
1412     already in use by keying in on the command line:
1413 \begin{lstlisting}[style=sh]
1414 netstat -n -l -4 --protocol inet
1415 \end{lstlisting} Next, click on the \textit{Add Nodes} button and
1416     then you will see that host appear in the Nodes list box to the
1417     right.  The \texttt{X} in the first column of the nodes box denotes
1418     that the node is active.  To review the \textit{standard} port
1419     allocations, check the \texttt{/etc/services} file.
1420   \item Enter the total jobs that you would like to be used in the
1421     \textit{Total job} textbox.
1422   \item The default watchdog timer initial state is usually just
1423     fine but can be adjusted later if needed.
1424   \item Click OK on the Preferences window when done.
1425   \end{enumerate}
1426 \item[Create Workflow] While working on the master computer, it is
1427   recommended that you keep all the resources being used on the same
1428   shared disk.  Load your video/audio piece and do your editing and
1429   preparation.  Add any desired plugins, such as a Title, to fine-tune
1430   your work.  You want to make sure your video is ready to be rendered
1431   into the final product.
1432 \item[Start the Client Nodes] To start up the client nodes run
1433   \CGG{} from the command line on each of the client computers using
1434   the following command:
1435 \begin{lstlisting}[style=sh]
1436 /{cinelerra_pathname}/cin -d [port number]
1437 # for example:
1438 /mnt1/bin/cinelerra -d 401
1439 \end{lstlisting} This starts \CGG{} in command prompt mode so that
1440   it listens to the specified port number for commands from the master
1441   node for rendering.  When you start each of the clients up, you will
1442   see some messages scroll by as each client is created on that
1443   computer, such as:
1444 \begin{lstlisting}[style=sh]
1445 RenderFarmClient::main_loop: client started
1446 RenderFarmClient::main_loop: Session started from 127.0.0.1
1447 \end{lstlisting} As it completes its jobs, you will should see:
1448 \begin{lstlisting}[style=sh]
1449 RenderFarmClientThread::run: Session finished
1450 \end{lstlisting}
1451 \item[Render Using Render Farm] After you have followed the
1452   preceding steps, you are ready to use the render farm.  Click on
1453   \texttt{File $\rightarrow$ Render}\dots which opens the render
1454   dialog.  The most important point here is to use for \textit{the
1455     Output path / Select a file to render to} a path/file name that is
1456   on the shared volume that is also mounted on the clients.  Click on
1457   OK to render. The \CGG{} program divides the timeline into the
1458   number of jobs specified by the user.  These jobs are then
1459   dispatched to the various nodes depending upon the load balance. The
1460   first segment will always render on the master node and the other
1461   segments will be farmed out to the render nodes.  Batch Rendering,
1462   as well as BD/DVD rendering, may use the render farm.  Each line in
1463   the batchbay can enable/disable the render farm.  Typically, video
1464   can be rendered into many file segments and concatenated, but
1465   normally audio is rendered as one monolithic file (not farmed).
1466
1467   Another performance feature which can use the Render Farm is
1468   \textit{Background Rendering}.  This is also enabled on the
1469   \texttt{Preferences $\rightarrow$ Performances} tab.  The background
1470   render function generates a set of image files by pre-rendering the
1471   timeline data on the fly.  As the timeline is update by editing, the
1472   image data is re-rendered to a \textit{background render} storage
1473   path.  The Render Farm will be used for this operation if it is
1474   enabled at the same time as the \textit{background render} feature.
1475 \item[Assemble the Output Files] Once all of the computer jobs are
1476   complete, you can put the output files together by using the shell
1477   script, \textit{RenderMux} (from the menubar \textit{scripts} button
1478   just above FF), if the files were rendered using ffmpeg (see \nameref{sec:menu_bar_shell_commands}).
1479   
1480   If you want to remain within the open project in \CGG{}, you can load these files by creating a new track and specifying concatenate to
1481   existing tracks in the load dialog in the correct numerical order.
1482   File types which support direct copy can be concatenated into a
1483   single file by rendering to the same file format with render farm
1484   disabled as long as the track dimensions, output dimensions, and
1485   asset dimensions are equal.
1486   
1487   Finally if you want to use ffmpeg from terminal externally to \CGG{} you can go to the directory where the rendered files are, it creates a text file \texttt{list.txt} containing the list of all our files:
1488   \begin{lstlisting}[style=sh]
1489         file 'name.webm001'
1490         file 'name.webm002'
1491         ...
1492         file 'name.webm00n'
1493   \end{lstlisting}
1494   and finally give the command
1495   \begin{lstlisting}[style=sh]
1496         ffmpeg -f concat -i list.txt -c copy output.webm
1497   \end{lstlisting}
1498 \end{description}
1499
1500 \subsection{Quick and Easy Render Farm Setup – The Buddy System
1501   Way}%
1502 \label{sub:buddy_system_way}
1503
1504 These steps are for quickly setting up render farm with the least
1505 amount of additional system work, but it is non-optimal.  It is
1506 useful in situations where a few people all show up with their
1507 laptops to work together on the same video/audio file and you don’t
1508 want to bother setting up NFS for a shared disk.
1509
1510 \begin{enumerate}
1511 \item Make sure the \CGG{} program is installed on all of the
1512   computers and the network between the main computer and the client
1513   computers is working.  Use the same version if possible.
1514 \item Load your video file on the master node and use \texttt{File
1515     $\rightarrow$ Save as}\dots to save it to \texttt{/tmp}.
1516 \item Move that same file with the same name to \texttt{/tmp} on all
1517   of the client computers via rsh or sneaker net -- the ONLY reason
1518   you are doing this is to avoid having to set up NFS or Samba on the
1519   buddy client laptops that show up!
1520 \item Edit your video/audio file to get it the way you want it and
1521   add the plugins, such as a Title, etc.
1522 \item Check for a set of unused ports in \texttt{/etc/services}
1523   file, if username is root usually $401-425$ are available; if
1524   non-root, then $10650-10799$.
1525 \item On the master computer, in \texttt{Settings $\rightarrow$
1526     Preferences, Performance} tab:
1527   \begin{itemize}
1528   \item check the box \textit{Use render farm}
1529   \item keyin localhost for the hostname or an ip address of the
1530     buddy client node
1531   \item keyin the desired port number for each client; and use
1532     \textit{Add Node} for each host
1533   \item set total jobs to the number of client computers $+1$
1534     multiplied by $3$ (or proportion to client speeds)
1535   \item check OK
1536   \end{itemize}
1537 \item On each buddy client, create a job for each port:
1538 \begin{lstlisting}[style=sh]
1539 /{cinelerra_pathname}/cin -d port#
1540 \end{lstlisting}
1541 \item On the master, bring up the render menu and name the output
1542   files, for example \texttt{/tmp/myoutput.webm}.
1543 \item The client nodes output results will be on their local
1544   \texttt{/tmp} filesystems so you will have to again use
1545   \textit{rsh/ftp} or \textit{usb sneaker net} to move them over to
1546   the main computer.  File names will be the render job output file
1547   name with port number tacked on
1548   (e.g. \texttt{/tmp/hb.webm001...webm005}).
1549 \item Load the files by concatenate to existing track on the master
1550   node or use RenderMux shell script.
1551 \end{enumerate}
1552
1553
1554 \subsection{Troubleshooting Tips and Warnings}%
1555 \label{sub:troubleshhoting_tips_warnings}
1556 \index{render farm!troubleshooting}
1557
1558 \noindent If you have problems running the Render Farm.  Here is a
1559 list of items to check.
1560
1561 \begin{itemize}
1562 \item \CGG{} must be installed on the master node and all client
1563   machines.
1564 \item It is best to have the same username available on all nodes to
1565   avoid problems with access rights.
1566 \item Check file permissions and ownership to ensure that the
1567   clients all have access.
1568 \item If a node does not have access to an input asset it will not
1569   die, but just display error messages.
1570 \item If a node can not access an output asset, the rendering will
1571   abort.
1572 \item A port in use when stopped may take up to $30$ seconds to time
1573   out before you can restart the jobs.
1574 \item Each of the port combinations have to be unique across
1575   clients, and not already in use in the network.
1576 \item \CGG{} load balances on a first come, first serve basis.  If
1577   the last section of the video is sent to the slowest node, the
1578   render job will have to wait for the slowest node to finish.  It
1579   would be better to start on the slowest node with the earlier
1580   section of the video so keep that in mind when designating port
1581   numbers.
1582 \item If not running as root, a port number in the higher range of
1583   $10650$ and above must be used instead of the $401+$ range.
1584 \item The master and client jobs on the ports do not go away so if
1585   you want to stop them, you will have to kill them via: \texttt{kill
1586     PID\#}.
1587 \item Check to see if there are services listening on the ports to
1588   use: \texttt{netstat -n -l -4 --protocol inet}
1589 \item There is a watchdog timer in \CGG{} and if there is no
1590   response from a client in the designated number of seconds, it will
1591   kill the render job.
1592 \item The \textit{localhost} should exist as $127.0.0.1$ in
1593   \texttt{/etc/hosts} and as the \texttt{lo} network device in
1594   ifconfig.
1595 \item If the job loads become unbalanced, you may want to
1596   \textit{reset rates} to start over for new framerates.
1597 \item If jobs are split in a key section on the timeline, you may
1598   wish to \textit{use labels} to prevent this.
1599 \item Adjust the \textit{Total jobs to create} for different videos that
1600   are considerably different in size.  You should not create so 
1601   many jobs that each one is very small.
1602 \item For testing purposes, you may want to start a client in the
1603   foreground using \texttt{-f} instead of \texttt{-d}.
1604 \item If one of the client computers is unavailable, check to see if
1605   there is an \texttt{X} to the left of the \texttt{nodename} in the
1606   Nodes listbox.  Check the \texttt{X} to disable it which sets ON to
1607   OFF.
1608 \item A red message in the lower left hand corner of the main
1609   timeline that reads \textit{Failed to start render farm} often means
1610   that the client \CGG{} programs were not started up.
1611 \item A message of \texttt{RenderFarmWatchdog::run 1 killing server
1612     thread \\ \#address\#} means that the client did not respond in
1613   time.  You can adjust the timer in \texttt{Settings $\rightarrow$
1614     Preferences, Performance} tab.
1615 \item When you get the message \texttt{RenderFarmClient::main\_loop:
1616     bind port 400: Address already in use}, use a different port. See \texttt{/etc/services} for free ports.
1617 \item A message of \texttt{RenderFarmServerThread::open\_client:
1618     unknown host abcompany} means that the hostname of abcompany is not
1619   in \texttt{/etc/hosts} so you will have to add it or use the ip
1620   address instead.
1621 \item There are numerous error messages associated with file
1622   \textit{open/close/status} or problems with the file that should be
1623   dealt with according to what is printed out.
1624 \item Other illustrative messages may be shown such as:
1625   \texttt{RenderFarmClientThread:: run: Session finished}.
1626 \end{itemize}
1627
1628 And here are a couple of more tips for making Render Farm specific
1629 for your setup.
1630 \begin{itemize}
1631 \item Because \textit{index files} speed up displaying the video you
1632   may want to share these files with the clients on a shared
1633   filesystem. More information on index files configuration is
1634   outlined in~\ref{sub:index_file_section}.
1635 \item Or, one of the convenient features of \CGG{} is the
1636   redirection of the path via \texttt{CIN\_CONFIG} as in:
1637 \begin{lstlisting}[style=sh]
1638 CIN_CONFIG="/<shared_file_pathname>/<filename_such_as_.bcast5>" cin
1639 \end{lstlisting} This means that you can make project related
1640   configurations that do not impact the default \texttt{\$HOME}
1641   config.  You can either export your default \texttt{\$HOME} config
1642   or the \texttt{CIN\_CONFIG} config to use on the render farm.
1643 \end{itemize}
1644
1645 \paragraph{Warnings}
1646
1647 If one of the render farm computers is connected to the internet,
1648 you should use a firewall to maintain the safety of all of the
1649 computers.  The ports have to be reachable for the intranet but you
1650 do not want the ports to be open to the outside.
1651
1652 %%% Local Variables:
1653 %%% mode: latex
1654 %%% TeX-master: "../CinelerraGG_Manual"
1655 %%% End: