e3aedbcff84d542b7f98452a812f3a4a07e84761
[goodguy/cin-manual-latex.git] / parts / Trouble.tex
1 \chapter{Troubleshooting and Help}%
2 \label{cha:troubleshooting_help}
3
4 \section{Help and Context Help}%
5 \label{sec:help_context_help}
6 \index{context help}
7
8 \CGG{} is a complex and feature-rich program. Using a guide is indispensable. The official manual (in English) can be found in PDF and HTML format:
9
10 \url{https://cinelerra-gg.org/download/CinelerraGG_Manual.pdf}
11
12 \url{https://cinelerra-gg.org/download/CinelerraGG_Manual/}
13
14 From within the program, you can invoke \textit{Context Help}, which references sections of the HTML manual\protect\footnote{credit Georgy(sge) for full implementation}.
15
16 Context help can be requested from almost any \CGG{} window or subwindow by pointing with the mouse cursor on the GUI element of interest and pressing \texttt{Alt/h}. That HTML manual page will be shown via the configured web browser, which is assumed as most relevant to the GUI element currently under the mouse pointer.
17
18 \subsection{How Context Help works}%
19 \label{sub:how_it_works}
20
21 The hotkey to request context help is \texttt{Alt/h}. What particular help page is shown, depends on the mouse cursor location while \texttt{Alt/h} is pressed. Usually, when the mouse is located in some window or dialog, the help page related to the functionality of this window or dialog is shown. In this case the mouse can point either on some widget, or on an empty area in the window. In \CGG{} GUI there are several rich loaded windows, \textit{Timeline} and \textit{Compositor} for example. In such a case different help pages can be requested depending on the particular GUI element under the mouse. For example, pressing \texttt{Alt/h} while pointing on the \textit{Autos curve} in a track would show help on \textit{automation keyframes} section, pointing on the \textit{Overlay} mode button in the \textit{patchbay} would show help on \textit{overlays}, pointing on the \textit{camera control} in \textit{Compositor} would show help on \textit{camera and projector}.
22
23 If no context dependent help page is found, the manual page of Contents itself is shown.
24
25 \subsection{Requesting context help for plugins}%
26 \label{sub:context_help_plugins}
27 \index{context help!plugins}
28
29 There are several possibilities to request the help page for a particular plugin of interest.
30
31 \begin{enumerate}
32         \item Pressing \texttt{Alt/h} with the mouse in the dialog window of that plugin's settings menu.
33         \item Pressing \texttt{Alt/h} while pointing with the mouse on the plugin bar in a track, transition bar, or transition icon.
34         \item Pressing \texttt{Alt/h} while pointing on the plugin name (icon) in the Resources window. If plugin tooltips are on, help for the highlighted plugin under the mouse is shown. If plugin tooltips are off, help for the selected plugin is shown.
35         \item Pressing \texttt{Alt/h} while pointing on the plugin name in the \textit{Attach Effect} dialog menu.
36 \end{enumerate}
37
38 \subsection{Requesting context help on Contour Shuttle}%
39 \label{sub:context_help_contour_shuttle}
40 \index{context help!contour shuttle}
41
42 Contour Shuttle has no \texttt{Alt/h}. Nevertheless, its help page can be requested by simultaneously pressing both \texttt{Alt} keys (left and right) on the keyboard followed by pressing any button on the Contour Shuttle. Here, pressing both Alt keys is necessary due to the way X11 tracks the status of modifiers. To cancel this mode, press any single modifier key (\texttt{Alt, \texttt{Ctrl}} or Shift) once.  Note that the manual Shuttle Configuration will be the default one, rather than the one that you may have redefined.
43
44 \subsection{Alternative web browser configuration}%
45 \label{sub:alt_browser}
46 \index{context help}
47
48 If you prefer to get \textit{Context Help} pages displayed in the same tab
49 in your browser instead of each help request displayed in a different tab,
50 choose an alternative method as outlined here that works for you.
51
52 \begin{enumerate}
53         \item Use another browser which has such a configurable mode. Here is an example for Seamonkey:
54 \begin{lstlisting}[style=sh]
55         export CIN_BROWSER=seamonkey
56 \end{lstlisting}
57 In the seamonkey browser go to Edit -> Preferences... -> Browser -> Link
58 Behavior -> Links from other applications .
59 Set the option "Open links passed from other applications in:" to the value
60 "The current tab/window".
61
62         \item Hack a default browser if you know how to hack it. Here is an example for Firefox.
63 Start Firefox and open the pseudo-URL:
64 \begin{lstlisting}[style=sh]
65         about:config
66 \end{lstlisting}
67 There will be a warning like "I'll be careful, I promise!", acknowledge it.
68 Then there is a very long list with lots of undecipherable variable names.
69 Scroll down to the variable: browser.link.open\_newwindow.override.external .
70 By default it has value of -1, which means "use value of the more general
71 variable: browser.link.open\_newwindow .
72 Next, place the mouse cursor over: browser.link.open\_newwindow.override.external ,
73 press the right mouse button, and select from the popup menu "Modify".
74 You can now edit the value. Set it to 1, and you get new links from external
75 apps opened in the same tab.
76
77 If you set the variable "browser.link.open\_newwindow" instead, you get this
78 behavior not only for external, but also for all links which otherwise would
79 be opened in new tabs or new windows. The possible values of both variables
80 are:
81 \newline \hspace*{1cm} Value = 1: open in the current window and tab
82 \newline \hspace*{1cm} Value = 2: open in the new window
83 \newline \hspace*{1cm} Value = 3: (default): open in the new tab, current window
84 \end{enumerate}
85
86 \section{Troubleshooting}%
87 \label{sec:troubleshooting}
88
89 You can report potential problems, bugs, and crashes to the \CGG{} website at:
90
91 \begin{center}
92         \href{https://www.cinelerra-gg.org/}{https://www.cinelerra-gg.org}
93 \end{center}
94
95 Here you can log the problem into the MantisBT bugtracker, or use the forum Q\&A for help from other users, or email the
96 problem using the address:{\small \href{mailto:cin@lists.cinelerra-gg.org}{cin@lists.cinelerra-gg.org}} It is usually more
97 helpful if instead of starting \CGG{} from its application icon, start from a window so that if there are error
98 messages related to the problem, they can be captured from the screen and emailed or logged. The command to run
99 from a window is: \texttt{<directory\_path of where you installed cinelerra>/bin/cin} -- for example if
100 installed in \texttt{/mnt0/build5/cinelerra-5.1}, you would execute the following command to start the program:\\
101 \texttt{/mnt0/build5/cinelerra-5.1/bin/cin} \\
102 The problem you are experiencing may be as simple as an error due to the settings in your \texttt{\$HOME/.bcast5} subdirectory so you may want to first rename your current \texttt{.bcast5} in order to start with default settings. By renaming the directory instead of deleting it, you will be able to put it back and not lose all of your preferences.
103
104 However, there are some easy things to do to fix errors that may have resulted from media problems,
105 computer problems, or operational missteps so you can proceed without having to wait for help.  These
106 are outlined in \ref{cha:when_things_go_wrong} - be sure to read down through
107 \textit{Common Problems} where some exact error messages are mentioned along with their cause or solution.  Other 
108 troubleshooting help is included in other sections of this manual for specific features.
109
110 \section{What to Include in Problem Reports}%
111 \label{sub:include_in_problem_reports}
112 \index{report problem}
113 For the best help, if you have a reproducible problem and can provide the following list of materials for analysis, it
114 is usually possible to figure out what the problem is and how to fix it. It may be a simple usage or setup mistake or
115 a real bug which a programmer would like to fix rather quickly. Although it is not always necessary to provide this
116 much information, it eliminates the \textit{try this} or \textit{did you do this?} and a lot of \textit{guessing} rather than heading straight for a solution. \textcolor{red}{Even if you can not provide all of this information, please report the problem in case other users are having the same issue.}
117
118 Basically we\textbf{ need to see what you see }with the input, output, and session file. Here is a list of the items that will most likely help to resolve the problem, but all of them will not necessarily be needed.
119
120 \begin{itemize}[nosep]
121         \item Provide a detailed description of the problem and the last operation performed if you remember it.
122         \item Supply a small representative sample of the original input that exhibits the issue.
123         \item If possible, also provide the rendered output, again using that representative sample.
124         \item Save a session file used with that same sample which will contain a lot of setup parameters; the best method to do this is to use the \texttt{File $\rightarrow$ Export Project}$\dots$ with the Copy option. That way all of the files will be in 1 location and easily loaded onto any other computer.
125         \item To make sure that the same rendering setup is used, it may be necessary to send an additional session file at the definition point just before rendering starts.
126         \item Include the Operating System name and version number and version of \CGG{} that you are running. You can find the date and time \textit{built} in the \texttt{Settings $\rightarrow$ Preferences, About} tab, bottom left corner.
127 \end{itemize} 
128
129 It is better to upload any files to a drop site as some of them can be quite large.
130
131 \textbf{How to create a session file:} \quad from the menubar pulldown \texttt{File $\rightarrow $ Save\_as}{\dots} \quad and choose a filename, for example \texttt{/tmp/beforerender.xml} Do this after you have the situation setup so can see values in use. As just stated, \textit{Export Project} option provides the most inclusive session information, but size could make it very large and cumbersome to upload or download.
132
133 \textbf{How to create a representative small sample:}
134
135 \begin{enumerate}[nosep]
136         \item open the input media, set up the scenario as you normally would to start the project render;
137         \item select 5-15 seconds of media using the edit mode left mouse button drag highlighting on the timeline;
138         \item start the render dialog (Shift-R), set the filename path, and set \textit{Render range} to \textit{Selection};
139         \item recommended \textit{Insertion strategy} is \textit{Replace current project}; then press the checkmark OK. The result will \textit{load replace} the current project for you to review to ensure the error still occurs. If this small sample does not create the error, try a different section or upload the entire input media.
140 \end{enumerate}
141
142
143 \section{Crash Dumps for Analysis}%
144 \label{cha:crash_dumps_analysis}
145 \index{crash dumps}
146 If you get a SEGV crash and can explain what steps you took, a \texttt{/tmp/cinelerra\_<pid> .dmp} file is
147 very useful for analysis. You can also use Ctrl-c in the controlling window to force an INTR signal interrupt when
148 you think the program is hung up. You can only perform one Ctrl-c as the second Ctrl-c quits out of the program. It
149 is best to upload the \texttt{.dmp}, input files and other files to datafilehost or similar temporary site as they may be quite large. The \texttt{.dmp} filename looks like \texttt{/tmp/cinelerra\_<pid> .dmp} Log a bug report or email all
150 helpful information on the crash, location of uploaded files, and list of setup steps that illustrate the problem to
151 {\small \href{mailto:cin@lists.cinelerra-gg.org}{cin@lists.cinelerra-gg.org}}
152
153 \begin{enumerate}[nosep]
154         \item Use the latest version of \CGG{} as you want to make sure the problem has not been fixed.
155         \item Be sure \textit{gdb} is installed (usually installed but if not, it is easy to do so).
156     \item Run as root if at all possible (this enables using gdb to create a full \texttt{/tmp/cinelerra* .dmp} file).
157     \item Be sure \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface $\rightarrow$ trap SEGV} and \texttt{trap INTR} are checked.
158         \item Invoke the error. This should create the file \texttt{/tmp/cinelerra-<pid>.dmp}
159 \end{enumerate}
160 \medskip
161
162 For those who can not run as root or can not create the problem while running as root, another method to create a dump
163 is available. Here are the steps to do so -- you should also have gdb installed.
164 \medskip
165
166 \begin{enumerate}[nosep]
167         \item Temporarily login as root and key in:\\
168         \texttt{echo 0 > /proc/sys/kernel/yama/ptrace\_scope} \\
169         This opens up \textit{ptrace}, used by gdb (the debugger). You will want to reverse this when done.
170         \item Run \CGG{} as an ordinary user from a window using the command line and try to create the problem. If the program crashes, this should produce a file named \texttt{/tmp/cinelerra*.dmp} where * is a number. The dump usually takes about 30 seconds or so to complete after the failure invokes the crash handler, so be patient. 
171         \item Email the output that shows in the window from where you started up \CGG{} and upload or directly email the \texttt{/tmp/cinelerra*.dmp} file (this file may be too large for the Mailing List).
172         \item After you are finished creating/testing the problem, reverse the previous setting while logged in as root by keying in:\\
173         \texttt{echo 1 > /proc/sys/kernel/yama/ptrace\_scope}
174 \end{enumerate}
175
176 \textcolor{red}{Even if you are not logged in as root or have ptrace enabled, if you
177 have a .dmp file and know what the last thing you did is, please provide the .dmp file for analysis.} There is a low
178 probability that the dump will prove useful, but if the problem can be recreated it can usually be fixed!
179
180 \section{When things go wrong}%
181 \label{cha:when_things_go_wrong}
182 \index{problem FAQ}
183
184 Sometimes things go wrong and there are some ways to continue your work without much trouble. Below is a list of items
185 to try before abandoning your session.
186
187 \begin{enumerate}
188         \item If your computer or the program crashed, you can use the \textit{File} pulldown choice
189 of \textit{Load backup} to get back to the last automatically saved session. It will most
190 likely not include the last few operations that were done though.  But if you forgot to 
191 Load backup when you restarted ,\CGG{} you have a second chance to use \texttt{File $\rightarrow$ Load} and
192 select \texttt{\$HOME/.bcast5/backup .prev} as long as you only loaded a different file and have
193 performed no editing operations.
194          \item If you accidentally destroyed your current project by a Load with 
195 \textit{Replace current project} when you should have changed the Insertion strategy, and 
196 you had not saved a recent backup, this is another time when it is useful to use
197 \texttt{File $\rightarrow$ Load} and
198 select \texttt{\$HOME/.bcast5/backup.prev} as long as you only loaded a different
199 file and had performed no editing operations.
200         \item If you suddenly get errors or hangs on media or strange looking tracks, you might want to rebuild indexes. You can do this in the Resources window with a right mouse click on the media to get a pulldown with the \textit{Rebuild index} option. For an easy way to rebuild for all of your media use \texttt{Settings $\rightarrow$ Preferences, Interface} tab, Index Files section, \textit{Delete existing indexes}. Over time, as you
201 load media, the indexes will automatically be recreated so each load takes a little longer, but this quite often
202 is all that is needed to repair a media problem.
203         \item On an older computer, if you are playing media and it can not keep up, you can turn off \textit{Play every frame} in the \textit{Video Out} tab of \texttt{Settings $\rightarrow$ Preferences, Playback} tab. You will then see the video jump as it skips frames in order to stay caught up.
204         \item The \textit{Cache size} can be lowered to 1048 if playback seems choppy or if you have problems with lv2 plugins, or you can increase the \textit{Cache size} for better flow. This can be changed in \texttt{Settings $\rightarrow$ Preferences, Performance} tab.
205         \item After saving your session and settings and exiting \CGG{}, you might want to rename your current \texttt{\$HOME/.bcast5} directory and start with the default setup. This will eliminate your settings as the potential cause of a problem; however, all of your preferences will be lost until you go back to your original \texttt{.bcast5}.
206         \item You can also temporarily rename just \CGG{}\_rc in your \$HOME/.bcast5 directory, so
207 that a new file with the original name will be created with original defaults.  You will lose your preferences,
208 but it is just for testing and you can move back the renamed \CGG{}\_rc over the new one if that is not the
209 cause of the problem.  Be sure to stop and restart \CGG{} whenever you rename this file.
210         \item Some media has only a single keyframe at the beginning of the file so that moving anywhere on the timeline results in just a black image in the compositor. \CGG{} needs more keyframes to determine position. You can temporarily use \texttt{Settings $\rightarrow$ Proxy} to $\frac{1}{2}$ size to put in keyframes. How to use Proxy is explained in \ref{sec:proxy_settings} {Proxy Settings and Transcode}.
211         \item If you have enabled an \textit{Automation Curve} such as Fade or Speed on your track but it
212 does not show, it could simply be because the range minimum and maximum are incorrectly set in the zoom bar.
213 Set them to more reasonable values until you see the lines appear. Just as a reminder, the zoom bar is on the
214 bottom of the main window (figure~\ref{fig:automation}). 
215         \item If the rate at which frames are captured during Recording is much lower than the framerate of the source, the video will accumulate in the recording buffers over time and the audio and video will become out of sync. Decrease the number of frames to buffer in the device in \texttt{Settings $\rightarrow $ Preferences, Recording} tab so that the excess frames are dropped instead of buffered.
216         \item If loading files locks up, this might be because \CGG{} is building picons/vicons for the Resources window. If you load a large number of images it needs to decompress every single image to build a picon/vicon. Go into \texttt{Settings $\rightarrow$ Preferences, Appearance} tab and disable \textit{Use thumbnails in resource window} to skip this process. Keep in mind though, that it only has to create these thumbnails the first time a new piece of media is loaded or the values are changed.
217         \item For an older computer with less CPU power, in \texttt{Settings $\rightarrow$ Preferences, Appearance} tab, be sure that \textit{Autocolor assets }is disabled; set \textit{View thumbnail size} \& \textit{Vicon quality}\& \textit{Vicon color mode} to lower values or switch to \textit{No Play} instead of \textit{Full Play} in the Resources window (this is to the right of the word \textit{Visibility} in the left hand side of that window). You will then have more CPU and more memory available to do actual editing.
218         \item If you have updated your Operating System or newly installed some applications, it is
219 possible that your LV2 plugin path may have been modified and be in disagreement with what you have set
220 for \CGG{}.  This could result in a crash upon startup.  Look at the messages in the window from where
221 you started \CGG{} to see if they look similiar to the following:
222 \begin{lstlisting}[numbers=none,xleftmargin=10mm]
223 LOAD: http://eq10q.sourceforge.net/matrix\_lr2ms
224 LOAD: http://eq10q.sourceforge.net/matrix\_ms2lr
225 LOAD: https://community.ardour.org/node/7596
226 LOAD: urna-comp
227 ** segv at 0x7f2cd80813c4 in pid 4540, tid 4540
228 \end{lstlisting}
229 The last line before the \textit{segv} indicates the name of the LV2 plugin that is causing problems.
230 Please refer to the section on LV2 plugins \ref{sec:audio_lv2_calf_plugins} to resolve the issue.
231 \end{enumerate}
232
233 \textbf{Some Helpful User Readable Text Dumps}
234
235 On the \textit{File} pulldown, there is a \textit{Dumps} option with a submenu of dump EDL, Plugins, Assets, and Undo. In all cases, you will have to have started \CGG{} from a window instead of from an application icon and
236 the text results will be shown in that window.
237
238 \begin{itemize}[nosep]
239 \item \textit{Dump EDL} \index{EDL dump} will display your current EDL state on the screen in the window from where you started .\CGG{} This can be useful to see information concerning a specific edit or a file path.
240 \item \textit{Dump Plugins} \index{plugins!dumps} will show the names of the currently loaded plugins.
241 \item \textit{Dump Assets} \index{asset!dump} displays the media assets that you have loaded and various pertinent details on each, such as samplerate, width, and height.
242 \item \textit{Dump Undo} \index{undo dump} will dump the last 32 edits on the undo stack exactly as kept, which can be useful if you are looking to see how far back in the undo to go to get to a specific spot.
243 \end{itemize}
244
245 \textbf{Common Problems}
246
247 Some messages you may see in the startup window may or may not be errors. Some examples are:
248 \bigskip
249
250 \textit{FFMPEG::open\_decoder: some stream times estimated:}  \texttt{/your directory/filename}
251
252 This is not a problem. Basically, when you open a file if a stream has a known duration, there is no message. If the duration is unknown, it is estimated by using the File Size and Bitrate to estimate the duration. This may just indicate that the stream number \CGG{} uses versus ffmpeg may be counted differently.
253 \bigskip
254
255 \textit{FFMPEG::scan: codec open failed} followed by
256 \newline 
257 \textit{FFMPEG::scan:file=} \quad \texttt{your directory/filename}
258
259 This is not a problem. \CGG{} is building an index for your file in order to better seek.  In that process, different methods are tried until a successful scan is complete.
260 \bigskip
261
262 \textit{AudioALSA::write\_buffer err -32(Broken pipe) at sample \#}
263
264 This indicates that there is something wrong with the audio. Some reasons for this are:
265 \begin{itemize}[nosep]
266         \item You simply stopped playing in \CGG{} while the audio is in progress.
267         \item Running on a computer where there is no sound card.
268         \item Incorrect setup of the audio parameters in the \texttt{Settings $\rightarrow$ Preferences, Playback} tab.
269         \item Your sound system is already in use by another program, like when playing \textit{tunes} outside \CGG{}.
270 \end{itemize}
271 \bigskip
272
273 \textit{Playback does not keep up so you hear the audio ahead of the video.}
274
275 When this occurs, it most likely means that there is not enough CPU power to keep up. You can go into \texttt{Settings $\rightarrow$ Preferences, Playback} tab and uncheck \textit{Play every frame}. Not playing every frame means that as it plays, if it can not keep up with doing all it has to do to change the frame into a vframe and then draw it, the program just notes that it is falling behind so skips frames to catch back up. This does not affect rendering. A different solution is to use Background Rendering as described in section \ref{sec:background_rendering}.
276 \bigskip
277
278 \textit{\CGG{} will not start and produces error message on the startup window.}
279
280 There can be various reasons that \CGG{} does not come up. Some of the recent reasons are listed here. Please notify the {\small \href{http://www.cinelerra-gg.org/}{www.cinelerra-gg.org}} website when you have any unknown startup issues.
281 \medskip
282
283 \begin{itemize}[nosep]
284         \item \CGG{} doesn't come up in Debian with compiz window manager running. Workaround is to use a different window manager or bring up cin first and then compiz. There is also a report that Compiz leads to single frame problems after a certain amount of time in the case where you switch to fullscreen mode and than back to normal node -- cin stops working and so you will have to restart cin.
285         \item When a library goes from one version to a later version, sometimes a pre-built \CGG{} binary will fail because it was created at a different version than the one the user has on their computer. This seems to happen more frequently on Arch distros because Arch has continuous releases and is usually kept up to date. An example of the error message you might see in your startup window would be:\\
286         \texttt{cin: error while loading shared libraries: libvpx.so.5: \\
287         cannot open shared object file: No such file}
288 \end{itemize}
289 \medskip
290
291 You can usually install the required library to fix the problem. A temporary fix may be to create a symlink but this must be done with extreme caution as it may create an unstable condition. A better workaround is to use a tarball to install the software instead of the package build until the libraries are in sync between the build and your Operating System install.
292 \bigskip
293
294 \textit{ Loading a very large number of media files, for example 500 clips, crashes \CGG{} with messages similar to the following that are displayed in the window from where you started \CGG{}:}
295
296 \begin{lstlisting}[numbers=none,xleftmargin=10mm]
297
298    BC_DisplayInfo::init_window: cannot open display "".
299    BC_DisplayInfo::init_window: cannot connect to X server.
300    unjoined tids / owner 42
301      00007feb27fff700 / 00007feb8f496700 9MainError
302      00007feb267fc700 / 00007feb7affd700 18FFMPEGScanProgress
303      ... 
304
305 \end{lstlisting}
306
307 This usually indicates that you are out of Operating System file descriptors.  You can increase the amount easily with the following command line:  \texttt{ulimit -n 4096}   where 4096 is a size suggestion but can be increased.  You can include this command line in your \texttt{.bashrc} or \texttt{.profile} file for the user login which gets run every time you login, or modify the Operating System limit for everyone in the system file, which for Fedora is \texttt{/etc/security/limits.conf}.  Alternatively, you can reduce the number of file descriptors needed by going into \texttt{Settings $\rightarrow$ Preferences, Appearance} tab and unchecking the flag \textit{use thumbnails in resource window}.
308
309 \bigskip
310
311 \textit{Using a non-supported locale could cause a failure in starting \CGG{} with the following error.}
312
313 \begin{lstlisting}[numbers=none,xleftmargin=10mm]
314
315    BC_WindowBase::init_im: Could not open input method.
316    unjoined tids / owner 1
317      00007f543dffb700 / 00007f54989d5840 12BC_Clipboard
318
319 \end{lstlisting}
320
321 This is caused by LC\_CTYPE setting you are using, and maybe other Locale settings too. 
322 For example, using the following will cause the \textit{unjoined tids} error.
323
324 \begin{lstlisting}[numbers=none,xleftmargin=10mm]
325    LC_CTYPE="en_IL" /mnt0/build5/cinelerra-5.1/bin/cin # set LC_CTYPE and start cin 
326 \end{lstlisting}
327
328 This is an operating system error which is resolved by using the following startup instead:
329
330 \begin{lstlisting}[numbers=none,xleftmargin=10mm]
331
332    LC_CTYPE="en_GB.utf8" /mnt0/build5/cinelerra-5.1/bin/cin # set LC_CTYPE and start cin 
333 \end{lstlisting}
334
335 You can either export the LC\_CTYPE variable before starting \CGG{} or
336 add this in your bash startup file or simply run from the command line as shown above.
337
338 \bigskip
339 \textit{Masking Feather is not working and produces error messages on the startup window similar to:}
340
341 \begin{lstlisting}[numbers=none,xleftmargin=10mm]
342 0:1(10): error: GLSL 4.30 is not supported. Supported versions are: 1.10, 1.20, 1.30, 1.40, 1.00 ES, and 3.00 ES
343 Playback3D::print_error:
344 #version 430 // vertex shader
345 in vec3 in_pos;
346 void main000() \{
347 gl_Position = vec4(in_pos-vec3(0.5,0.5,0.), .5);
348 }
349 void main() \{
350 main000();
351 }
352 \end{lstlisting}
353
354 In the mask window, check the box \textit{Disable OpenGL masking} to use software instead of OpenGL.
355
356 \section{Menu Bar Shell Commands}%
357 \label{sec:menu_bar_shell_commands}
358 \index{shell commands}
359
360 In order to provide some types of help, the Menu Bar Shell Commands are available for customization purposes (figure~\ref{fig:trouble-img001}).
361
362 \begin{figure}[h!]
363         \centering
364         \includegraphics[width=1.0\linewidth]{trouble-img001.png} 
365         \caption{Some windows used to manipulate Shell Commands scripts}
366         \label{fig:trouble-img001}
367 \end{figure}
368
369 In the main window on the top line containing the \textit{File}, \textit{Edit}, {\dots} \textit{Window} pulldown menus, all the way to the right hand side is the \textit{shell cmds} icon. You might see a small white-color bordered box with the "\texttt{i}" inside and if you mouse over it, the tooltip says \textit{shell cmds}. This is a configurable popup which gives you the ability to see a table of Shortcuts in html format, refer to the reference manual or execute a pre-defined script to perform a specific task, such as some type of post processing which you plan on performing on a repeat basis. Unless redirected elsewhere, the output from executing any script-type commands will be displayed in the window from where you started \CGG{}.
370
371 The Shell Cmds popup menu items are configured in:
372
373 \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface $\rightarrow$ Shell Commands}
374
375 This runs a dialog that lets you Add/Del/Edit the scripts in the main menu popup. \ Possible options are:\newline
376
377 \begin{enumerate}
378         \item \textit{Add} a new menu item/script:
379         \begin{itemize}[noitemsep]
380                 \item click on the \textit{Add} button
381                 \item in the Label box, change the word \textit{new} to the desired menu label (for example: Graphics Editor)
382                 \item in the Commands box, type the command lines to be included in the script (for example: gimp)
383                 \item click the green checkmark for OK in the Commands window
384                 \item click the green checkmark for OK in the Shell window
385                 \item click on OK or Apply in the Preferences window
386         \end{itemize}
387         \item \textit{Del} to delete an existing menu item
388         \begin{itemize}[noitemsep]
389                 \item select to highlight an entry in the \CGG{}: Shell listbox
390                 \item click on the \textit{Del }button
391                 \item click the green checkmark for OK in the Shell window
392                 \item click on OK or Apply in the Preferences window (the entry is now deleted)
393         \end{itemize}
394         \item \textit{Edit} an existing menu item:
395         \begin{itemize}[noitemsep]
396                 \item select to highlight an entry in the \CGG{}: Shell listbox
397                 \item click on the \textit{Edit} button (the Commands window appears)
398                 \item set the label and/or commands to the new desired values
399                 \item click on the green checkmark for OK in the Commands window
400                 \item click on the green checkmark for OK in the Shell window
401                 \item click on OK or Apply in the Preferences window
402         \end{itemize} 
403 \end{enumerate}
404         
405 Next time you click on the \textit{shell cmds} icon, you will have the changes you made in effect.
406
407 Both the \textit{Add} and \textit{Edit} options have checkboxes in the Commands window for the following:
408
409 \begin{itemize}[nosep]
410         \item \textit{OnExit notify} \quad  choose Always, Never, or On error to get a popup window notify
411         \item run \texttt{path/script.sh + argvs} \quad to run a particular script with argvs (\$1, \$2,{\dots} arguments)
412 \end{itemize}
413
414
415 When modifications to the Shell Cmds are included in a new \CGG{} release, they are not added to your Preferences file automatically unless you create a new one. But if you have added no custom scripts, you can update your currently existing \texttt{\$HOME/.bcast5/ \CGG{}\_rc} file to delete the lines that are all grouped together that begin with the letters: \texttt{SHBTN} (the entire line -- these are the \textbf{SH}ell \textbf{B}u\textbf{T}to\textbf{N}s). \ You should first Quit out of \CGG{}, edit the file, and then when you restart \CGG{}, it will create the new default buttons in that same file.
416
417 There are 2 specific \CGG{} file names that have unique characteristics that allow for usage from a user-defined
418 script. The first one is an environment variable, \texttt{CIN\_RENDER} which is used in the \textit{RenderMux} shell command that is already setup. It contains the complete path and filename of the file in your session that you selected as \textit{Select a file to render to} when you ran a Render operation.
419
420 The second one concerns usage of the Resource window assets to use as argvs in shell scripts. The added command line
421 can ONLY be a script. Then if your script refers to \$1, \$2 and \$3 and you highlight 3 files in the Media folder,
422 their full path name will be used as the argvs to your script. For example, if you added a shell commands script
423 \texttt{/workspace/script.sh} that contains the following lines:
424
425 \begin{lstlisting}[numbers=none,xleftmargin=10mm]
426 cp ``\$1'' /tmp/temporary_copy
427 cp ``\$2'' /tmp/new_copy
428 cp ``\$3'' /tmp/file_to_upload
429 \end{lstlisting}
430
431 and you highlight 3 files in the Resources window called\textit{ ABC.mp4}, \textit{123.mp4}, and \textit{Final.mp4} and execute your added script from the Shell Cmds icon, you will be copying those 3 highlighted files to the new names on \texttt{/tmp}.
432
433 There are some Help features currently included in the Shell Cmds menu. Those available are:
434
435 \begin{enumerate}
436         \item \textit{Current Manual} in PDF format from cinelerra-gg.org or automatically downloaded.
437         \item \textit{Setting Shell Commands} \textit{how to} which explains how to configure your own commands.
438         \item \textit{Shortcuts} html file for easily looking up a particular shortcut.
439         \item \textit{RenderMux} shell script to use ffmpeg concatenate to copy files such as \textit{look.mp4001}, \textit{look.mp4002}, \textit{look.mp4005}{\dots} that were rendered using \textit{Create new file at each label} or with the Render Farm.
440 \end{enumerate}
441
442 \section{\CGG{} Command Line -h}%
443 \label{cha:cinelerra_command_line_-h}
444 \index{command line}
445
446 To see the command line parameters available to use with \CGG{}, key in:
447
448 \qquad \texttt{<your \CGG{} directory path>/bin/cin -h}
449
450 What will be shown in the window where this line was entered is:
451
452 Usage:
453
454 \texttt{./cin [-f] [-c configuration] [-d port] [-n nice] [-r batch file] [filenames]}
455
456 -d = Run in the background as renderfarm client.  The port (400) is optional.\\
457 -f = Run in the foreground as renderfarm client. Substitute for -d.\\
458 -n = Nice value if running as renderfarm client. (19)\\
459 -c = Configuration file to use instead of /root/.bcast5/Cinelerra\_rc.\\
460 -r = batch render the contents of the batch file (/root/.bcast5/batchrender.rc) with no gui. batch file is optional.\\
461 -S = do not reload perpetual session\\
462 -x = reload from backup\\
463 filenames = files to load
464