\mainmatter
-\include{parts/Instalation}
+\include{parts/Installation}
\include{parts/Windows}
\include{parts/Attributes}
\include{parts/Loadandsave}
\include{parts/Shortcuts}
\include{parts/Configuration}
\include{parts/Stuff}
+\include{parts/Trouble}
+\include{parts/Tips}
\include{parts/Glossary}
--- /dev/null
+\chapter{Installation}
+\label{cha:Instalation}
+\section{How to Build Cinelerra-GG from Developer's Git Repository}%
+\label{sec:How_to_build}
+
+These are generic build instructions for building Cinelerra-GG Infinity.
+Known to work on Ubuntu, Mint, Suse/Leap, Fedora, Debian, Centos, Arch, and Slackware.
+It has not been tested on every single possible distro yet so you might expect to have to make some minor changes.
+Patches have been created to build on FreeBSD through the work of another programmer and a Gentoo version is being maintained elsewhere by another programmer.
+
+Alternatively, there are some pre-built dynamic or static binaries which are updated on a fairly regular basis (as long as code changes have been made) available at the link below.
+
+
+\url{
+https://cinelerra-gg.org/download/
+}
+
+There are 2 kinds of builds, the default system-build and a single-user build.
+A system build has results which are installed to the system.
+The majority of the files are installed in the standard system paths, but some customization is possible.
+The single user build allows for running completely out of a local user directory so it doesn't affect the system.
+
+We recommend the single-user version when possible.
+It makes it very easy to install a new version without having to delete the older version in case you want it for backup - once you are happy with the new version, all you have to do is delete the entire old directory path.
+Also, if you install a new Operating System version and if you have Cinelerra on separate disk space that is preserved, you won't have to reinstall Cinelerra.
+In addition for purposes of having the ability to interrupt or to see any possible error messages, if you start the application from a terminal window command line you will have more control to catch problems.
+However, the system builds can be useful in a university lab setting where there are possibly multiple users, or multiple versions.
+
+There are two notable differences between “standard” views of Cinelerra and this implementation for the system builds.
+Both of these can be configured during installation.
+These differences make it possible to have several different versions installed without having them “walk” on each other.
+
+
+
+
+
+
+
+
+
+
+\begin{enumerate}
+ \item
+ application name can be set during installation and defaults to: “\texttt{cin}”
+ \item
+ the home configuration directory can also be set and defaults to:\\ “\texttt{\$HOME/.bcast5}”
+\end{enumerate}
+
+\paragraph{To do a system build,} you should read the \texttt{README} that is at the top level after you get the source.
+
+
+\begin{enumerate}
+ \item
+ You need about 6.0 \,GB of disk storage to operate a build + you need to have “\texttt{git}” installed.
+ \item Obviously in order to install into the system, you must run as \textbf{root}.
+ \item The "\texttt{git}" step has to download many files (approx 130\,MB) so allow time. When decompressed this will expand to about 530 MB.
+ \item Run the following commands (this takes awhile):
+
+ \begin{lstlisting}[language=bash]
+$ cd /<build_path>/ # this is where you need the 6.0GB of disk space
+$ git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
+$ cd cinelerra5/cinelerra-5.1 # toplevel directory
+ \end{lstlisting}
+
+ NOTE: if your system has never had Cinelerra-GG Infinity installed, you will have to make sure you have all of the compilers and libraries necessary.
+ So on the very first build you should run:
+
+ \begin{lstlisting}[language=bash]
+$ ./blds/bld_prepare.sh <os> # where <os> represents the Operating System of Centos, Fedora, Suse, Leap, Ubuntu, Debian.
+$ ./autogen.sh
+$ ./configure --prefix=/usr # optional parameters can be added here
+$ make 2>&1 | tee log # make and log the build
+ \end{lstlisting}
+ \item Check for obvious build errors:
+ \begin{lstlisting}[language=bash]
+$ grep "\*\*\*.*error" -ai log
+ \end{lstlisting}
+ If this reports errors and you need assistance or you think improvements can be made to the build s,
+ \begin{lstlisting}[language=bash]
+$ /<build_path>/cinelerra5/cinelerra-5.1/log
+ \end{lstlisting}
+ \item If there are no build errors, finally just run:
+ \begin{lstlisting}[language=bash]
+ $ make install
+ \end{lstlisting}
+ \item If it all worked, you are all setup. Just click on the Cinelerra desktop icon.
+\end{enumerate}
+
+\paragraph{To do a single-user build,} read the \texttt{README} that is at the top level after you get the source.
+\begin{enumerate}
+ \item You need at least 6\,GB of disk storage to operate a build + you need to have “\texttt{git}” installed.
+ \item Recommend you build and run as \textbf{root}, just to avoid permission issues initially.
+ \item The "\texttt{git}" step has to download many files (approx 130\,MB) so allow time.
+ \item Run the following commands (this takes awhile):
+ \begin{lstlisting}[language=bash]
+$ cd /<build_path>/ # this is where you need the 6GB of disk space
+$ git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
+$ cd cinelerra5/cinelerra-5.1 # toplevel directory
+ \end{lstlisting}
+\end{enumerate}
+
+NOTE: if your system has never had Cinelerra-GG Infinity installed, you will have to make sure all
+the compilers and libraries necessary are installed. So on the very first build you should run as \textbf{root}:
+
+\begin{lstlisting}[language=bash]
+$ ./blds/bld_prepare.sh <os> # where <os> represents the Operating System of centos, fedora, suse, leap, ubuntu, debian.
+$ ./autogen.sh
+$ ./configure --with-single-user # the “with-single-user” parameter makes it so
+$ make 2>&1 | tee log # make and log build (check for errors before proceeding)
+$ make install
+\end{lstlisting}
+
+Then just start the application by keying in: ./cin in the bin subdirectory OR add a desktop icon by
+using the appropriate directory to copy the files to, run as \textbf{root}, and edit to correct the directory path.
+
+\begin{lstlisting}[language=bash]
+$ cd /cinelerra_directory_path
+$ cp -a image/cin.{svg,xpm} /usr/share/pixmaps/.
+$ cp -a image/cin.desktop /usr/share/applications/cin.desktop
+\end{lstlisting}
+Change the “Exec=cin” line to be “Exec=<your\_directory\_path>/bin/cin”
+
+The preceding directions for doing a single-user build has been meticulously followed to build and run
+on a newly installed ubuntu 15 system WITHOUT BEING ROOT except for the \texttt{bld\_prepare.sh} and creating the desktop icon.
+
+\subsection{Notable Options and Caveats}%
+\label{sub:notable_options_and_caveats}
+
+These procedures and the Cinelerra-GG Infinity software have all been run as “\textbf{root}” on various home laptops and desktops. This provides the best chance to ensure all works correctly and also allows for handling errors, other problems and potential crashes with the most success. Included in this section are some of the build variations easily available for normal builds.
+
+To see the full list of features use:
+
+\begin{lstlisting}[language=bash]
+$ ./configure -help
+\end{lstlisting}
+The default build is a system build which uses:
+
+\begin{lstlisting}[language=bash]
+$ ./configure -without-single-user
+\end{lstlisting}
+
+In the single-user build, the target directory is always “cin”.
+Because this is also the developer build, constant names are used throughout.
+However, you can rename files after the install is complete.
+
+If your operating system has issues with the default install to \texttt{/usr/local}, you might have to change the location to \texttt{/usr} for a system build. Then you will have to use:
+\begin{lstlisting}[language=bash]
+$ ./configure --prefix=/usr
+\end{lstlisting}
+
+If you wish to change the default directory for a system build you will have to add the destination directory path on the “\texttt{make install}” line. For example:
+\begin{lstlisting}[language=bash]
+$ make install DESTDIR=<your selected target directory path>
+\end{lstlisting}
+
+The application name can be set during installation, but defaults to cin so that the GG/Infinity build can coexist with other Cinelerra builds if necessary. To override the default cin name, use:
+\begin{lstlisting}[language=bash]
+$ ./configure --with-exec-name=cinelerra
+\end{lstlisting}
+
+The home configuration directory can also be set, but default location is \texttt{\$HOME/.bcast5}.
+For example:
+
+\begin{lstlisting}[language=bash]
+$ ./configure -with-config-dir=/myusername/.bcast5
+\end{lstlisting}
+
+NOTE: when you specify parameters to the configure program, it will create a make file as a consequence.
+Since in a make file, the \$ is a special character, it must be escaped so in order to represent a \$ as part of an input parameter, it has to be stuttered.
+That is, you will need \$\$ (2 dollar signs) to represent a single dollar sign.
+
+It may be necessary on some distros which have missing or incomplete up-to-date libraries, to build cinelerra without Ladspa.
+To do so, use:
+
+\begin{lstlisting}[language=bash]
+$ ./configure --prefix=/usr --without-ladspa-build
+\end{lstlisting}
+
+Note that the with-ladspa-dir is the ladspa search path, and exists even if the ladspa build is not selected. This gives you the ability to specify an alternate ladspa system path by utilizing the \texttt{LADSPA\_PATH} environment variable (that is, the default ladspa build is deselected).
+
+Note for 32-bit 14.2 Slackware, Debian, Gentoo, Arch, FreeBSD, before running the configure, you will need to set up the following:
+
+\begin{lstlisting}[language=bash]
+$ export ac_cv_header_xmmintrin_h=no
+$ export FFMPEG_EXTRA_CFG=" --disable-vdpau"
+\end{lstlisting}
+
+\subsection{Notes about Building from Git in your Customized Environment}%
+\label{sub:notes_about_building_from_git_in_your_customized_environment}
+
+Getting a build to work in a custom environment is not easy. If you have already installed libraries which are normally in the thirdparty build, getting them to be recognized means you have to install the "devel" version so the header files which match the library interfaces exist. Below is the list of thirdparty builds, but this list may have changed over time.
+% It's list of Table?
+
+\begin{table}[htpb]
+ \centering
+ \caption{List of thirdparty builds}
+ \label{tab:List_of_thirdparty_builds}
+ \small
+ \begin{tabular}{m{8em}c}
+ \toprule
+ a52dec & yes\\
+ djbfft & yes\\
+ fdk & auto\\
+ ffmpeg & yes\\
+ fftw & auto\\
+ flac & auto\\
+ giflib & yes\\
+ ilmbase&auto\\
+ lame & auto\\
+ libavc1394&auto\\
+ libraw1394&auto\\
+ libiec61883&auto\\
+ libdv &auto\\
+ libjpeg &auto\\
+ openjpeg &auto\\
+ libogg &auto\\
+ libsndfile&auto\\
+ libtheora&auto\\
+ libuuid & yes\\
+ libvorbis&auto\\
+ mjpegtools&yes\\
+ openexr &auto\\
+ tiff &auto\\
+ twolame &auto\\
+ x264 &auto\\
+ x265 &auto\\
+ libvpx &auto\\
+ libwebp&auto\\
+ libaom& auto\\
+ \bottomrule
+ \end{tabular}
+\end{table}
+
+
+The "yes" means force build and “auto” means probe and use the system version if the build operation is not static.
+To get your customized build to work, you need to change the probe options for the conflicting libraries from "yes" to "auto", or even rework the \texttt{configure.ac} script.
+There may be several libraries which need special treatment.
+
+An example of a problem you might encounter with your customized installation is with “\texttt{a52dec}” which has probes line \texttt{(CHECK\_LIB/CHECK\_HEADER)} in \texttt{configure.ac}, but \texttt{djbfft} does not.
+In this case, \texttt{djbfft} is only built because \texttt{a52dec} is built, so if your system has \texttt{a52dec}, set \texttt{a52dec} to auto and see if that problem is solved by retrying the build with:
+\begin{lstlisting}[language=bash]
+$ ./confgure --with-single-user -enable-a52dec=auto .
+\end{lstlisting}
+
+With persistence, you can get results, but it may take several tries to stabilize the build.
+If you need help, email the "\texttt{log}" and "\texttt{config.log}", which is usually sufficient to determine why a build failed.
+%\vspace{5ex}
+
+If you have already installed the \texttt{libfdk\_aac} development package on your computer because you prefer this version over the default aac, you will have to do the following to get this alternative operational.
+
+\begin{lstlisting}[language=bash]
+$ export FFMPEG_EXTRA_CFG=" --enable-libfdk-aac --enable-nonfree"
+$ export EXTRA_LIBS=" -lfdk-aac"
+$ for f in `grep -lw aac cinelerra-5.1/ffmpeg/audio/*`; do
+$ sed -e 's/\<aac\>/libfdk_aac/' -i $f
+$ done
+\end{lstlisting}
+
+\subsection{Cloning the Repository for Faster Updates}%
+\label{sub:cloning_the_repository_for_faster_updates}
+
+If you want to avoid downloading the software every time an update is available you need to create a local "repository" or repo.
+The repo is a directory where you first do a “\texttt{git clone}”.
+For the initial git clone, setup a local area for the repository storage, referred to as \texttt{<repo\_path>}.
+The “\texttt{git clone}” creates a repo named "\texttt{cin5}" in the \texttt{/<repo\_path>/} directory.
+This accesses about 530\,MB of repo data, so the device has to have at least that available.
+The repo path is always a perfect clone of the main repo.
+
+\paragraph{Setting up the initial clone}%
+\label{par:setting_up_the_initial_clone}
+add “\texttt{ -\,- depth 1}” before cin5 which is faster/smaller, but has no history.
+
+\begin{lstlisting}
+$ cd /<repo\_path>/
+$ git clone "git://git.cinelerra-gg.org/goodguy/cinelerra" cin5
+
+Cloning into "cin5"...
+remote: Counting objects: 20032, done.
+remote: Compressing objects: 100% (11647/11647), done.
+remote: Total 20032 (delta 11333), reused 16632 (delta 8189)
+Receiving objects: 100% (20032/20032), 395.29 MiB | 3.26 MiB/s, done.
+Resolving deltas: 100% (11333/11333), done.
+Checking connectivity... done.
+\end{lstlisting}
+
+\paragraph{Update an existing repo}%
+\label{par:update_an_existing_repo}
+
+\begin{lstlisting}[language=bash]
+ $ cd /<repo home>/cin5
+ $ git pull
+\end{lstlisting}
+
+\paragraph{Useful git commands}%
+\label{par:useful_git_commands}
+
+
+\begin{lstlisting}[language=bash]
+$ git clone "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cin5
+$ git pull # pull remote changes to the local version
+$ git status # shows changed files
+$ git clean -i # interactive clean, use answer 1 to "clean"
+\end{lstlisting}
+
+
+
+\subsection{How to Build from a Previous GIT Version}%
+\label{sub:how_to_build_from_a_previous_git_version}
+
+
+\begin{lstlisting}[language=bash]
+$ cd /<path>/cin5_repo
+$ git log
+$ git checkout <version>
+\end{lstlisting}
+
+
+The “git log” command produces a log file with hash values for commit keys. The hash ids are the commit names to use when you use git checkout.
+Next is displayed sample output:
+
+
+\begin{lstlisting}
+delete stray line in last checkin
+
+commit 4a90ef3ae46465c0634f81916b79e279e4bd9961
+Date: Thu Feb 22 14:56:45 2018 -0700
+
+nested clips, big rework and cleanup, sams new icons, leaks and tweaks
+
+commit f87479bd556ea7db4afdd02297fc00977412b873
+Date: Sat Feb 17 18:09:22 2018 -0700
+\end{lstlisting}
+
+For the “git checkout <version>, you would then keyin the line below for the following results:
+
+\begin{lstlisting}
+$ git checkout f87479bd556ea7db4afdd02297fc00977412b873
+
+Note: checking out 'f87479bd556ea7db4afdd02297fc00977412b873'.
+
+ You are in 'detached HEAD' state. You can look around, make experimental
+ changes and commit them, and you can discard any commits you make in this
+ state without impacting any branches by performing another checkout.
+
+ If you want to create a new branch to retain commits you create, you may
+ do so (now or later) by using -b with the checkout command again. Example:
+
+ git checkout -b <new-branch-name>
+
+ HEAD is now at f87479bd... more file size icon updates, and more to followend
+\end{lstlisting}
+
+Later to get the repo back to current, use:
+\begin{lstlisting}
+$ git checkout master
+\end{lstlisting}
+
+
+\subsection{Debuggable Single User Build}%
+\label{sub:debuggable_single_user_build}
+
+
+To build from source with full debugging symbols, first build a full static (non\_debug) build as follows but instead /tmp should be substituted with a permanent disk path if you want to keep it.
+
+\begin{lstlisting}
+$ git clone ...
+$ cp -a /path/cinelerra-5.1 /tmp/.
+$ cd /tmp/cinelerra-5.1
+$ ./bld.sh
+\end{lstlisting}
+
+
+Then, to run as a developer in the debugger:
+
+\begin{lstlisting}[language=bash]
+$ CFLAGS="-O2 -ggdb" make -j8 rebuild_all
+$ cd cinelerra
+$ gdb ./ci
+\end{lstlisting}
+
+
+\subsection{Unbundled Builds}%
+\label{sub:unbundled_builds}
+
+There are some generic build scripts included in the Cinelerra-GG GIT repository for users who want to do unbundled builds with ffmpeg already available on their system.
+This has been tested on Arch, Ubuntu 18, FreeBSD, and Leap 15 (rpm) at the time this was documented.
+The names of the build scripts are: arch.bld , bsd.bld , deb.bld , and rpm.bld .
+These scripts are in the “blds” subdirectory.
+The bsd.bld should be used with the bsd.patch file in that same directory.
+
+The reason that Cin Infinity traditionally uses thirdparty builds (bundled builds)\todo{hanging line} is because there are a lot of different distros with varying levels of ffmpeg and other needed thirdparty libraries.
+However, some users prefer using their current system baseline without another/different copy of ffmpeg.
+With different levels of the user’s libraries, uncertainty, potential instability, and unknown issues may come up while running Cinelerra and this will make it, for all practical purposes, impossible to diagnose and debug problems or crashes.
+There may be no help in these cases. You are encouraged to report any errors which potentially originate from Cin Infinity, but if the data indicates alternate library sources, please report the problems to the appropriate maintainers.
+
+With the unbundled builds, some features may not be available and no attempt to comment them out has been made.
+So if you use a pulldown, or pick a render option, or choose something that is not available, it just will not work.
+For example, unless special options were set up by you, the LV2 audio plugins will not be available.
+Nor will the codec libzmpeg, the file codec ac3, or DVD creation.
+The old school file classes will all work, but some of the formats that come with ffmpeg may not because of the way that ffmpeg was installed on your operating system.
+That is because the Cinelerra ffmpeg is a known static build and is usually the latest stable/released version.
+In the current case of Leap 15, libx264 and libx265 are not built in and this can be debilitating; you can always run “ffmpeg -formats” and “ffmpeg -codecs” to see what is available on your system.
+
+
+\section{Download Already Built Cinelerra-GG}%
+\label{sec:download_already_built_cinelerra_gg}
+
+If you prefer to not have to take the time to build Cinelerra-GG Infinity yourself, there are pre-built dynamic or static binaries for various versions of Ubuntu, Mint, Suse, Fedora, Debian, Centos, Arch, and Slackware linux as well as Gentoo and FreeBSD.
+There are also 32-bit i686 Ubuntu, Debian, and Slackware versions available.
+These are updated on a fairly regular basis as long as significant code changes have been made.
+They are in subdirectories of:
+
+\url{https://cinelerra-gg.org/download/tars}
+
+\url{https://cinelerra-gg.org/download/pkgs}
+
+The “\textbf{tars}” directory contains single-user static builds for different distros.
+This is the recommended usage of Cinelerra-GG because all of the files will exist in a single directory.
+To install the single user builds, download the designated tarball from the ./tars subdirectory and unpack as indicated below:
+
+\begin{lstlisting}[language=bash]
+$ cd /path
+$ mkdir cin
+$ cd cin
+$ tar -xJf /src/path/cinelerra-5.1-*.txz # for the *, substitute your distro tarball name
+\end{lstlisting}
+
+Do NOT download the LEAP 10-bit version unless you use h265 (it can't render 8-bit h265).
+
+The “\textbf{pkgs}” directory contains the standard packaged application for various distros.
+This will install a dynamic system version for users who prefer to have the binaries in the system area and for multi-user systems.
+In addition, performing the package install checks the md5sum in the file md5sum.txt to ensure the channel correctly transmits the package.
+There is a README.pkgs file in the “pkgs” directory with instructions so you can “cut and paste” and avoid typos; it is also shown next.
+
+%TODO point to real READ.pkgs
+
+\begin{lstlisting}
+Depending on the distro, use the instructions below and select the appropriate
+setup operations to install, update or remove cinelerr-gg infinity. (03/04/2019)
+To upgrade, refresh repo, then replace "install" with "update", or whatever.
+
+If repository problems, usually you can manually do an install by using:
+ wget https://cinelerra-gg.org/download/pkgs/{substitute_name}/cin_5.1.<sub_name>.deb
+ and install it manually, for example: dpkg -i cin_5.1.{substitute_filename}.deb
+
+# GENTOO - courtesy Dominque Michel
+# There is an ebuild package at this time as of 01/03/2019 at:
+# https://svnweb.tuxfamily.org/listing.php?repname=proaudio%2Fproaudio&path=
+# %2Ftrunk%2Foverlays%2Fproaudio%2Fmedia-video%2Fcinelerra%2F&#ab000caf7024d83112f42a7e8285f2f29
+
+# FREEBSD - courtesy Yuri
+# There is a port available at: https://www.freshports.org/multimedia/cinelerra-gg/
+# To use this port: cd /usr/ports/multimedia/cinelerra-gg && make install clean
+# and then install this precompiled package via: pkg install cinelerra-gg
+
+# FEDORA
+# Replace the XX in fedoraXX in the next line with your current O/S version number
+dnf install cinelerra --nogpgcheck --repofrompath cingg,https://cinelerra-gg.org/download/pkgs/fedoraXX/
+##dnf erase cinelerra
+
+# CENTOS
+# Python 2 has been updated for other distros to Python 3 so you might have to create a soft link
+# first create the file /etc/yum.repos.d/cin_gg, with the following contents:
+[cin_gg]
+name=cingg
+baseurl=https://cinelerra-gg.org/download/pkgs/centos7
+gpgcheck=0
+# end of cin_gg
+yum install cinelerra
+##yum erase cinelerra
+
+# UBUNTU, replace ub14 with your distro id: ub16,ub17,ub18
+# Some ubuntu apt downloads register status as working 0% constantly while running the package
+# download, like ubuntu 14. It may take a few minutes for this step so be patient.
+apt install software-properties-common apt-transport-https
+apt-add-repository https://cinelerra-gg.org/download/pkgs/ub14
+# UBUNTU 16/17/18 note - This has been known to work, but things change quickly:
+# VIP - for the first install, the above line adds cinelerra to /etc/apt/sources.list but...
+# Version 16/17/18 of Ubuntu are more strict for licensing so you will have to edit
+# the file /etc/apt/sources.list to add [trusted=yes] after deb and before https...cin...
+# For example the line should be: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/ub16 xenial main
+# Or for ub17: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/ub17 zesty main
+# Or for ub18: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/ub18 bionic main
+# Also, on the install you will get an error message that you can either ignore as cinelerra
+# will run anyway, or else (the first time only) on the commnand line keyin:
+# echo > /etc/sysctl.d/50-cin.conf "kernel.shmmax=0x7fffffff"
+apt update
+apt install cin
+#to update a previous install (ignore any i386 errors as only 64 bit version available):
+apt update
+apt upgrade cin
+##apt remove cin
+
+# MINT should use the same procedure as Ubuntu, but:
+# Note: apt-add-repository did not work for me, I had to use the gui version:
+# System_OR_Administration->Software Sources->Additional Repositories->Add a new repository
+# For Mint18,add: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/mint18 xenial main
+# For Mint19,add: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/mint19 bionic main
+apt update
+apt install cin
+#to update a previous install
+apt update
+apt upgrade cin
+##apt remove cin
+
+# DEBIAN uses the same basic procedure as Ubuntu.
+# The apt-add-repository varies per system so you will have to use your best judgement
+apt install software-properties-common apt-transport-https
+apt-add-repository https://cinelerra-gg.org/download/pkgs/debian8
+OR apt-add-repository https://cinelerra-gg.org/download/pkgs/debian9
+OR apt-add-repository https://cinelerra-gg.org/download/pkgs/debian10
+# VIP - for the first install, the above line adds cinelerra to /etc/apt/sources.list but...
+# Debian stretch/jessie/buster are more strict for licensing so you will have to edit
+# the file /etc/apt/sources.list to add [trusted=yes] after deb and before https...cin...
+# For example for debian8: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/debian8 jessie main
+# For example for debian9: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/debian9 stretch main
+# For example for debian10: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/debian10 buster main
+apt update
+apt install cin
+#to update a previous install
+apt update
+apt upgrade cin
+##apt remove cin
+
+# SUSE/LEAP
+# (Note: you may have to zypper libavc and libiec versions if not already installed)
+# cinelerra packages are unsigned so you will have to ignore: Package is not signed!
+# openSUSE LEAP 15
+zypper ar -f https://cinelerra-gg.org/download/pkgs/leap15/ cingg
+zypper install -r cingg cinelerra # or cinelerra10bit for 10 bit
+# openSUSE LEAP 42
+zypper ar -f https://cinelerra-gg.org/download/pkgs/leap42/ cingg
+# as of 42.3 SUSE there is a new requirement, so you will need to add:
+zypper mr -G cingg
+zypper install -r cingg cinelerra # or cinelerra10bit for 10 bit
+##zypper remove cinelerra # or cinelerra10bit for 10 bit
+#to update a previous install (assuming you enabled autorefresh as above)
+zypper refresh cingg
+zypper up cinelerra # or cinelerra10bit for 10 bit
+
+# SLACKWARE, substitute slk32 for slk64 and i486-1 for x86_64-1
+wget -P /tmp https://cinelerra-gg.org/download/pkgs/slk64/cin-{date}-slk64-x86_64.txz
+installpkg /tmp/cin... # name you used in the above line
+#to update a previous install
+upgradepkg /tmp/cin... # name you used in the above line
+##removepkg cin
+
+# ARCH linux
+# first edit the file /etc/pacman.conf, to include the following:
+[cingg]
+SigLevel = Optional TrustAll
+Server = https://cinelerra-gg.org/download/pkgs/arch
+# end of cingg
+pacman -Sy
+pacman -S cin
+##pacman -R cin
+\end{lstlisting}
+
+\section{Distribution Systems with Cinelerra Included}%
+\label{sec:distribution_systems_with_cinelerra_included}
+
+There are also some special complete distribution systems available that include Cinelerra-GG for audio and video production capabilities.
+
+AV Linux is a downloadable/installable shared snapshot ISO image based on Debian.
+It provides the user an easy method to get an Audio and Video production workstation without the hassle of trying to find and install all of the usual components themselves.
+Of course, it includes Cinelerra-GG!
+It is at:
+
+\url{http://www.bandshed.net/avlinux/}
+
+Bodhi Linux is a free and open source distribution that comes with a curated list of open source software for digital artists who work with audio, video, includes Cinelerra GG, games, graphics, animations, physical computing, etc.
+It is at:
+
+\url{https://gitlab.com/giuseppetorre/bodhilinuxmedia}
+
+\section{Cinx and a “Bit” of Confusion}%
+\label{sec:cinx_and_a_bit_of_confusion}
+
+Cinx is the exact same program as Cin.
+The X (x) represents the roman numeral 10 for 10-bit as opposed to 8-bit standard.
+The third-party library used for x265 must be specially compiled with \texttt{--bit-depth=10} in order to produce 10-bit rendered output.
+This build will not be able to output 8-bit depth which means you have to retain the Cin version also.
+Whatever build ffmpeg is linked to will determine what bit depth it can output.
+This is why there have to be separate builds.
+If you install both packages, Cin and CinX, you may get “file conflicts of same file name” --- just continue.
+
+Keep in mind that the regular 8-bit version works on 8-bit bytes --- the standard word size for computers, but the 10-bit version has to use 2 words to contain all 10 bits so you can expect rendering to be as much as twice as slow.
+There is also a 12-bit version for consideration but currently the results are simply the same as 10-bit with padding to make 12-bit so it is of no value.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
This plugin is designed to smooth out non-moving areas of a video clip (figure~\ref{fig:staveraging}).
\vspace{2ex}
-\begin{wrapfigure}[22]{O}{0.4\linewidth}
- \vspace{-4ex}
+\begin{wrapfigure}[20]{O}{0.4\linewidth}
+ % \vspace{-4ex}
\includegraphics[width=0.9\linewidth]{images/staveraging.png}
\caption{STA control window}
\label{fig:staveraging}
--- /dev/null
+\chapter{Performance and other Tips}%
+\label{cha:performance_tips}
+
+Performance and usability of Cinelerra are directly related to the software and video format being used in conjunction with your computer system hardware -- the number of CPUs and its speed, I/O bus speed, graphics card, and amount of available memory. A basic, less powerful system will be sufficient for users working with audio only or lower resolution video formats. Higher end computers will be needed when playing and working with higher resolution formats, like 1080p, 1440p and 2160p. Adding effects and several tracks of audio will require more cpu, memory, and various other resources to read, decode and play video.
+
+Perhaps the easiest method for determining if your performance could be improved is to look at the numerical value displayed as \textit{Framerate achieved}. Good performance means that when \texttt{Play every frame} is set in:
+
+\texttt{Settings $\rightarrow$ Preferences, Playback A tab}, the frames/second (frames per second or fps) in playback might be almost always at the maximum rate of your project setting and/or video frame rate. You can check this in \texttt{Settings $\rightarrow$ Preferences, Playback A}, by watching \textit{Framerate achieved} while playing forward. A higher number is better, up to the format frame rate of the video.
+
+Some hardware considerations are listed here:
+\begin{itemize}
+ \item Multi-core and more SMP processors greatly improve Cinelerra speed by making use of threads.
+ \item A large amount of free memory available can help speed up operations by avoiding unnecessary disk
+ swaps and keeping material easily accessible.
+ \item Video editing can be quite I/O intensive. If you are going to produce long pieces in uncompressed or
+ larger resolution formats, you should have plenty of fast access disk space.
+ \item Cinelerra benefits from OpenGL hardware acceleration. A good graphics card is worthwhile to have.
+ \item Multiple monitors really come in handy to increase productivity as you can see more information and
+ in bigger windows so you do not have to keep moving windows around.
+\end{itemize}
+Besides the above hardware recommendations, this section covers tips for performance improvements and tips on how to perform some specific tasks, often for older media.
+
+\section{Hardware video acceleration}%
+\label{sec:hardware_video_acceleration}
+
+With certain newer, more powerful graphics boards and newer device drivers, there is the potential for enhanced \textit{decode} and \textit{encode} performance. Decode refers to loading and playing video in Cinelerra. The GPU, Graphics Processing Unit, on the graphics board is accessed via one of the following libraries: vdpau or vaapi. The hardware acceleration done by the graphics card increases performance by activating certain functions in connection with a few of the FFmpeg decoders. This use makes it possible for the graphics card to decode video, thus offloading the CPU. Decode operations are described here next. Encode refers to rendering video and is described at the end of this section under \textit{GPU hardware encoding} \ref{sub:gpu_hardware_encoding}
+
+VDPAU, Video Decode and Presentation API for Unix, is an open source library to offload portions of the video decoding process and video post-processing to the GPU of graphics boards, such as Nvidia. It may also apply to Nouveau and Amdgpu boards (by wrapper), but that has not been verified.
+
+VA-API, Video Acceleration API, is an open source library which provides both hardware accelerated video encoding and decoding for use mostly with Intel (and AMD) graphics boards.
+
+Currently only the most common codecs, such as MPEG-1, MPEG-2, MPEG-4, and H.264/MPEG-4, are accelerated/optimized by the graphics card to play these particular video formats efficiently. The other formats are not optimized so you will see no performance improvement since the CPU will handle them as before, just as if no hardware acceleration was activated. There are many different graphics cards and computer systems setup, so you will have to test which specific settings work best for you. So far this has been tested at least with Nvidia, Radeon, and Broadwell graphics boards on some AMD and Intel computers; depending on the graphics card, two to ten times higher processing speeds can be achieved. However, most graphic operations are single-threaded and may be slower as opposed to multiple CPUs, which frequently multi-thread many operations simultaneously.
+
+\subsection{GPU hardware decoding}%
+\label{sub:gpu_hardware_decoding}
+
+\begin{enumerate}
+ \item Verify that you have installed \texttt{libva-dev} or \texttt{libva} on your operating system.
+ \item Verify that you also have \texttt{libvdpau-dev} or \texttt{libvdpau} installed.
+ \item Verify \texttt{Settings $\rightarrow$ Preferences, Playback tab, Video Driver} is set to\texttt{ X11} -- or \texttt{X11-OpenGL} if that produces better results for your configuration.
+ \item Before starting CinelerraGG, you can set an environment variable that can be easily reversed and
+ then, to run from the Cinelerra installed directory, key in:
+\end{enumerate}
+
+\begin{lstlisting}[language=bash]
+CIN_HW_DEV=vdpau ./cin # for computers with Nvidia and some other graphics cards
+CIN_HW_DEV=vaapi ./cin # mostly for computers with Intel or AMD specific graphics hardware
+\end{lstlisting}
+
+If you find that the environment variable setting is advantageous for your CinGG usage and you want to always use it, you can add it to your \texttt{\$HOME} directory \texttt{.profile} file which takes effect every time you log in. The line you would add would look something like this:
+
+\begin{lstlisting}[language=bash]
+export CIN_HW_DEV=vdpau
+or
+export CIN_HW_DEV=vaapi
+\end{lstlisting}
+
+It might be more difficult to analyze problems as a result of using the GPU because of the wide variation in hardware. When you do not set the \texttt{CIN\_HW\_DEV} environment variable, the code will work exactly as before since this feature is self-contained.
+
+In addition to the environment variable, there is a \texttt{Settings $\rightarrow$ Preferences, Performance tab, Use HW device} flag with a pulldown to set up \textit{none, vdpau, vaapi,} or \textit{cuda}. To ensure it takes effect, it is best to set it the way you want, quit out of Cinelerra and then restart. Its current purpose is for flexibility, but there is a possibility that it might eventually take the place of \texttt{CIN\_HW\_DEV} -- both are not needed.
+
+-- Precedence of the decode hardware acceleration settings are:
+
+-- \texttt{yourfile.opts} is checked first so is of the highest priority; special .opts usage is described below
+
+-- environment variable \texttt{CIN\_HW\_DEV} is checked next
+
+-- preferences \texttt{Use HW device} settings is of the lowest priority
+
+\subsubsection*{Hardware decoding in Cinelerra GG}%
+\label{ssub:hardware_decoding_cinelerra}
+
+There are 4 phases during Cinelerra’s handling of hardware acceleration. These first 2 steps occur just \textit{before} the first read.
+
+\begin{enumerate}
+ \item Check to see if Hardware Acceleration is enabled, usually indicated by \texttt{CIN\_HW\_DEV} being set to
+ vaapi or vdpau. If enabled, try to activate the decode device, and if that fails revert to software.
+ \item The next step is to send some data to decode to see if that works. If this does not work, you will see
+ an error message of \textit{HW device init failed, using SW decode}.
+\end{enumerate}
+
+\noindent These next 2 steps occur \textit{during} any read. Now there is no turning back to software so if the hardware gets an error, that video will not be handled correctly.
+
+\begin{enumerate} [resume]
+ \item Read the media and send the raw stream data to the device for processing.
+ \item Read the device to receive the decoded data, and convert it to the session color model. If the GPU
+ can not convert the data, you will see the error message of \textit{Error retrieving data from GPU to CPU}.
+\end{enumerate}
+
+Due to variations in user’s computer hardware configuration, it is often suggested that you refer to your startup window to check for error messages. Since your situation is unique, the error may not have been seen by anyone else and is probably unknown/undocumented.
+
+\subsubsection*{Possible improvements or differences}%
+\label{ssub:possible_improvements_differences}
+
+\begin{enumerate}
+ \item The Frames Per Second (FPS) in playback might be mostly at the maximum rate. You can check
+ this in \texttt{Settings $\rightarrow$ Preferences, Playback A}, looking at \texttt{Framerate achieved}; the higher, the better.
+ \item Percent of the CPU used should be less, thus saving more CPU for other operations.
+ \item Some users get the the impression that playing seems smoother.
+ \item The CPU fan noise may go down as the CPU is used less.
+ \item The GPU graphics fan noise may go up as the GPU is used more.
+\end{enumerate}
+
+Using the GPU is going to react differently depending on your hardware, software, and the number of files loaded. A good way to determine how well it is performing, is to watch the CPU load from another window running the command line routine \texttt{top}. Consider the following possibilities:
+
+\begin{itemize}
+ \item If you only use smaller videos occasionally and then use other codecs than the ones mentioned
+ previously as being the optimized set, it is usually a better idea to stay with the default settings
+ without all the hardware tests.
+ \item If you have 4 cores or less, but a really good \textit{gaming card}, using vaapi/vdpau could be a big help.
+ \item If you load only a couple of files, the GPU vaapi/vdpau should be faster depending on your graphics
+ board and how capable it is.
+ \item If you load 10 camera Mixers of H.264 format, it always seems to work a lot better playing them.
+ \item If you have an epyc AMD chip with 128 CPUs and load 50 files, without vaapi/vdpau may be better.
+\end{itemize}
+
+\subsubsection*{Special .opts file}%
+\label{ssub:special_opts_file}
+
+The situation may arise where you have enabled hardware acceleration and after loading several files for a project, you find that a file had some kind of error resulting in a black video instead of an image or you see an error message pop up which states something like \textit{Error retrieving data from GPU to CPU} or \textit{err: Unknown error occurred}. Because the \texttt{CIN\_HW\_DEV} environment variable is either all or none, ordinarily in order to correct the non-working video you would have to turn off hardware acceleration for the entire project/session. However, there is a way to continue working on your project without having to reload all of your files. You still use the environment variable and it will be effective for all of the formats it is able to handle, but you make an exception for any of the files that erred out. To do this you simply create a file in the same directory with the same name as the erring file with the different extension of .opts. The contents of this .opts file would just be the one line of:
+
+\begin{lstlisting}[language=bash]
+cin_hw_dev=none
+\end{lstlisting}
+
+Conversely, if you have a bunch of files in your project, like dnxhd format, that are not hardware accelerated, but you have an accompanying large file of type .mp4 for which you would like the hardware acceleration, you can leave the \texttt{CIN\_HW\_DEV} variable unset (that is, do not use it) and just create an .opts file containing the line:
+
+\begin{lstlisting}[language=bash]
+cin_hw_dev=vdpau
+\end{lstlisting}
+
+For example your file, \texttt{test.mp4}, would have a side-kick called \texttt{test.opts} that will use the GPU for decoding/playing and the other files will just use the software. This is of some advantage because the ones that can not use the GPU if the environment variable is enabled, will not have to even check which saves a minuscule bit of time.
+
+It is important to note that if using the .opts file to override the default \texttt{ffmpeg / decode.opts} file, you will most likely see more warnings (not really errors) in the Cinelerra startup window because the standard \texttt{decode.opts} file has \textit{loglevel = fatal} whereas the default is \textit{loglevel = error}. To avoid seeing all of the extra warnings, you can simply add the line \texttt{loglevel=fatal} to your .opts file.
+
+\subsubsection*{To verify hardware acceleration}%
+\label{ssub:verify_hardware_acceleration}
+
+Probably the easiest way to tell if hardware acceleration is working, is just to look at the messages in the window from where you started Cin (not available if start using the application icon). For example load a png, dnxhd, or some other non-supported format file and you will see messages similar to those below. The line \textit{HW device init failed, using SW decode} indicates that the vdpau/vaapi HW (hardware) decode is not available so will use SW (software) decode instead.
+
+\begin{lstlisting}[language=bash]
+Failed to get HW surface format.
+HW device init failed, using SW decode.
+file:/tmp/media/aer_zypr.mp4
+err: Success
+
+or
+
+Decoder dnxhd does not support device type vdpau.
+HW device init failed, using SW decode.
+File:/tmp/media/test.gxf
+err: Success
+
+or
+
+HEVC with NVIDIA, VDPAU driver is buggy, skipping
+\end{lstlisting}
+
+If you would like to see more information on what is occurring, you can modify in the Cinelerra ffmpeg subdirectory, the file: \texttt{decode.opts} by temporarily changing the line from \texttt{loglevel =fatal} to \texttt{loglevel =verbose} and restarting Cinelerra. Then you will see messages in the startup window like:
+
+\begin{lstlisting}[language=bash]
+[AVHWDeviceContext @ 0x7fc9540be940] Successfully created a VDPAU device
+(NVIDIA VDPAU Driver Shared Library 390.116 Sun Jan 27 06:28:58 PST 2019) on X11 display :0
+[h264 @ 0x7fc950159380] Reinit context to 1920x1088, pix_fmt: vdpau
+[h264 @ 0x7fc92c3dd4c0] Reinit context to 1920x1088, pix_fmt: yuv420p
+\end{lstlisting}
+
+Again, to measure the performance run \texttt{top} from another window to check the CPU usage which will go lower as more work is offloaded to the GPU graphics card instead (it may go down by 2 to 10 times) or check the \textit{Framerate achieved} while playing.
+
+Some mixed preliminary results that have been reported are provided below.
+
+\subsubsection*{Case \#1:}%
+\label{ssub:case_1}
+
+\noindent X11 Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A tab}:
+
+\begin{center}
+ \begin{tabular}{lcr}
+ CIN\_HW\_DEV=off ./cin & &CPU $58\%$ \\
+ CIN\_HW\_DEV=vdpau ./cin & &CPU $32\%$ \\
+ CIN\_HW\_DEV=vaapi ./cin & &CPU $82\%$ \\
+ \end{tabular}
+\end{center}
+
+\noindent X11-OpenGL Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A tab}:
+
+\begin{center}
+ \begin{tabular}{lcr}
+ CIN\_HW\_DEV=off ./cin & &CPU $48\%$ \\
+ CIN\_HW\_DEV=vdpau ./cin & &CPU $12\%$ \\
+ CIN\_HW\_DEV=vaapi ./cin & &CPU $80\%$ \\
+ \end{tabular}
+\end{center}
+
+\noindent Best is the least amount of CPU usage. Note that in this case, using X11-OpenGL is better
+
+\subsubsection*{Case \#2:}%
+\label{ssub:case_2}
+
+\noindent X11 Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A tab}:
+
+\begin{center}
+ \begin{tabular}{lcr}
+ CIN\_HW\_DEV=off ./cin & &CPU $60\%$ \\
+ CIN\_HW\_DEV=vdpau ./cin & &CPU $11\%$ \\
+ CIN\_HW\_DEV=vaapi ./cin & &CPU $60\%$ \\
+ \end{tabular}
+\end{center}
+
+\noindent X11-OpenGL Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A tab}:
+
+\begin{center}
+ \begin{tabular}{lcr}
+ CIN\_HW\_DEV=off ./cin & &CPU $67\%$ \\
+ CIN\_HW\_DEV=vdpau ./cin & &CPU $60\%$ \\
+ CIN\_HW\_DEV=vaapi ./cin & &CPU $67\%$ \\
+ \end{tabular}
+\end{center}
+
+\noindent Best is the least amount of CPU usage. Note that in this case, using X11 is better
+
+Older graphics cards or non-performing graphics cards will probably bring only a small amount of improvement or no speed advantage at all. You can check to see if vdpau is implemented for your specific Nvidia board at:
+
+\url{https://download.nvidia.com/XFree86/Linux-x86_64/304.137/README/supportedchips.html}
+
+And, you can see what your specific hardware and software might support by running either \texttt{vainfo} or \texttt{vdpauinfo} from the command line. Partial examples of each are shown below.
+
+\begin{lstlisting}[language=bash]
+# vainfo
+vainfo: VA-API version: 1.4 (libva 2.4.0)
+vainfo: Driver version: Intel i965 driver for Intel(R) Broadwell - 2.4.0.pre1 (2.3.0-11-g881e67a)
+vainfo: Supported profile and entrypoints
+VAProfileMPEG2Simple
+...
+VAProfileH264Main
+VAProfileH264High
+...
+VAProfileH264MultiviewHigh
+VAProfileH264StereoHigh
+...
+VAProfileVC1Simple
+...
+VAProfileVP8Version0_3
+\end{lstlisting}
+
+\begin{lstlisting}[language=bash]
+# vdpauinfo
+display: :0 screen: 0
+API version: 1
+Information string: G3DVL VDPAU Driver Shared Library version 1.0
+...
+Decoder capabilities:
+
+name level macbs width height
+----------------------------------------------------
+MPEG1 --- not supported ---
+MPEG2_SIMPLE 3 65536 4096 4096
+MPEG2_MAIN 3 65536 4096 4096
+H264_BASELINE 52 65536 4096 4096
+H264_MAIN 52 65536 4096 4096
+H264_HIGH 52 65536 4096 4096
+VC1_SIMPLE 1 65536 4096 4096
+VC1_MAIN 2 65536 4096 4096
+VC1_ADVANCED 4 65536 4096 4096
+\end{lstlisting}
+
+One last item of note, \textit{nvdec} is also enabled in the ffmpeg build, but at this time it is not known how this decode option on Nvidia graphics boards works or does not work in conjunction with vdpau.
+
+\subsection{GPU hardware encoding}%
+\label{sub:gpu_hardware_encoding}
+
+Encoding using hardware acceleration of your graphics board GPU is included in CinelerraGG but it is of limited availability and works only with a specific set of hardware graphics boards, a certain level of graphics driver versions and only with certain ffmpeg formats. The encoding is done via vaapi (libva installed), which is known to work with Intel HD graphics boards and some others or via nvenc as developed by Nvidia for Nvidia graphics boards.
+
+\subsubsection*{Broadcom, Intel HD, AMD}%
+\label{ssub:broadcom_intel_amd}
+
+To use hardware acceleration for rendering (that is, encoding) you do not have to set a preference or an environment variable, as was required for decoding. To use this feature you use an ffmpeg render options file which specifies a vaapi codec, such as h264\_vaapi. You must include this line in that options file to trigger the hardware probe: \qquad \texttt{CIN\_HW\_DEV=vaapi}
+
+There are currently 4 options files available in the Render menu already set up for you that you see when you select the Video wrench and use the down arrow on the first line in the menu. These are:
+
+\begin{description}
+ \item[h264\_vaapi.mp4] known to work on Intel computer with Intel Broadwell graphics driver
+ \item[mpeg2\_vaapi.mp4] known to work on Intel computer with Intel Broadwell graphics driver
+ \item[mjpeg\_vaapi.mp4] error message of \textit{open failed with mjpeg\_vaapi$\dots$} on above computer
+ \item[hevc\_vaapi.mp4] error message of \textit{open failed with hevc\_vaapi$\dots$} on above computer
+\end{description}
+
+Other option files can be added as needed for your specific hardware if it is known to work for you, such as VP8 and VP9. An example of the included Cinelerra’s \texttt{ffmpeg/video/h264\_vaapi.mp4} file (figure~\ref{fig:render-vaapi}):
+
+\begin{lstlisting}[language=bash]
+mp4 h264_vaapi
+cin_hw_dev=vaapi
+profile=high
+\end{lstlisting}
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.8\linewidth]{images/render-vaapi.png}
+ \caption{Render menu setup to encode using GPU with vaapi}
+ \label{fig:render-vaapi}
+\end{figure}
+
+According to an online wiki, hardware encoders usually create output of lower quality than some software encoders like x264, but are much faster and use less CPU. Keep this in mind as you might want to set a higher bitrate to get output of similar visual quality.
+
+Results of a particular test case performed on a Intel, 4-core computer, with Broadwell Graphics using an mp4 input video/audio file with dimensions of
+
+$1440x1080 / 29.97fps$ is shown next (note, filename is \texttt{tutorial.mp4}). This may very well be a \textit{best case} scenario! But clearly, at least on this computer with only 4 cores, the hardware acceleration seems to be quite advantageous. A comparison of the 2 output files using \texttt{ydiff} (as described in Appendix C in the manual) shows no obvious defects.
+
+\begin{center}
+ \begin{tabular}{l|cccc}
+ &CPU usage & Render Time & File Size & File \\
+ \hline
+ none & 388\% &100 secs &36,862,542 & h264.mp4 \\
+ vaapi & 150\% & 19 secs & 74,522,736 & h264\_vaapi.mp4 \\
+ \end{tabular}
+\end{center}
+
+\subsubsection*{Nvidia graphics boards}%
+\label{ssub:nvidia_graphics_card}
+
+To use hardware acceleration for rendering (that is, encoding) you do not have to set a preference or an environment variable, as was required for decoding. To use this feature you use an ffmpeg render options file which specifies the nvenc codec, either \texttt{h264\_nvenc.mp4} or \texttt{nvenc.mp4}. There are several requirements in order for this to work on your computer as listed here:
+
+\begin{enumerate}
+ \item Nvidia graphics board at or above a certain hardware level. For h265, newer boards are required.
+ \item Software drivers for your graphics board must be installed on your computer.
+ \item The driver must support at least API version 9.0 -- minimum required Nvidia driver for nvenc is
+ 390.25 or newer. You will see error messages on the startup window if you are on lower versions.
+\end{enumerate}
+
+If you try to render using\texttt{ h264/h265\_nvenc.mp4} formats and do not have an Nvidia graphics card or this feature was not built in, you will see in the window from where you started Cinelerra, the error message: \qquad \textit{Cannot load libcuda.so.1}
+
+A small test using 2 minutes from the 4k version of Big Buck Bunny shows using nvenc can be about 4 times faster. The test was done on a 4 core Intel laptop with an Nvidia 950M graphics board.
+
+\begin{center}
+ \begin{tabular}{l|cccl}
+ &CPU usage & Render Time & File Size & File \\
+ \hline
+ none & 388\% &20 mins 18 secs & 156,517,069 & h264.mp4 \\
+ nvenc & 252\% & 5 mins 44 secs & 42,052,920 & h264\_nvenc.mp4 \\
+ \end{tabular}
+\end{center}
+
+Of note in this test, 388\% CPU usage with only 4 cores shows that there is probably slow down because there is no more CPU power available. Therefore, using the GPU hardware acceleration with nvenc provides a significant speed-up. Also, note the larger file size without making use of the GPU – this probably indicates that there is a big difference in bitrate or quality parameter settings used in the options file and this should be taken into consideration.
+
+\subsubsection*{Important Tip}%
+\label{ssub:important_tip}
+
+There is one last potentially significant graphics speedup when using the X11-OpenGL driver for users with Nvidia graphics boards who are seeing frames/sec achieved lower than what the video format is set to. You may want to disable \textit{sync to vblank} (an option for OpenGL) in NVIDIA X Server Settings for the proprietary drivers. This could increase your frames per second on playback.
+
+\subsection{effects (OpenCL, Cuda)}%
+\label{sub:effects_opencl_cuda}
+
+CUDA® is a parallel computing platform / programming model developed by Nvidia that provides big increases in computing performance through use of the GPU. It was first introduced in about 2006 for applications in computationally intense fields such as astronomy, biology, chemistry, and physics.
+
+At the time this was written, the use of Cuda is not going to improve the playing and rendering of video in Cinelerra except in the case where you use a specific Cuda-enabled plugin that is computationally intense -- sadly, most of what Cin does, Cuda will not help. Cuda is mostly a \textit{block oriented algorithm} which works well for such things as \textit{a flock of birds all flying next to each other}.
+
+The same as for vaapi and vdpau, you can enable Cuda in the\texttt{ Settings $\rightarrow$ Preferences, Performance tab}, \texttt{Use HW Device} but it will not affect anything unless you have Cuda installed on your system and have built Cinelerra yourself with Cuda build enabled. To install it on your computer, you will need to do the following:
+
+\begin{enumerate}
+ \item Make sure you have the Nvidia proprietary library drivers for your graphics board already installed.
+ \item Go to the Nvidia Cuda development website and choose one of the available operating system’s
+ such as Fedora, OpenSuse, CentOS, Ubuntu, $\dots$ at \url{https://developer.nvidia.com/}
+ \item You will be installing repositories by package -- this will be around 3 GB.
+ \item Also, install the Fusion repo, although it is unknown if necessary or not.
+\end{enumerate}
+
+There is a very good set of directions on the website to just follow. Once you have installed the Cuda software on your computer, you must build Cinelerra yourself -- the default build in the configure script for cuda is \textit{auto}. For Arch, be sure to first key in: \texttt{setenv CUDA\_PATH=/opt/cuda}
+
+There are currently 2 available plugins for \textit{show and tell} that take advantage of the hardware acceleration of Cuda -- N\_Body and Mandelbrot as shown next (figure~\ref{fig:cuda-effects}).
+
+\begin{figure}[htpb]
+ \centering
+ \begin{minipage}[h]{0.99\linewidth}
+ \center{\includegraphics[width=0.99\linewidth]{images/n_body.png}} \\
+ \end{minipage}
+ \vfill
+ \begin{minipage}[h]{0.7\linewidth}
+ \center{\includegraphics[width=0.99\linewidth]{images/mandelbrot.png}} \\
+ \end{minipage}
+ \caption{N\_Body and Mandelbrot effects}
+ \label{fig:cuda-effects}
+\end{figure}
+
+An error you may see on your Cinelerra startup window when you have Cuda installed and try to run one of the 2 plugins is \textit{cudaErrorInsufficientDriver}. This indicates CUDA 10 (the current version at the time of this writing) is not compatible with the driver version on your computer. You can either:
+
+\begin{enumerate}
+ \item Upgrade the driver if your board supports newer nvidia builds.
+ \item downgrade the cuda development package to a version that works for your board.
+\end{enumerate}
+
+\subsection{Final Note}%
+\label{sub:final_note}
+
+In wrapping up this Hardware Acceleration section, you may want to refer to the following to determine the current supported formats:
+
+\noindent \url{https://wiki.archlinux.org/index.php/Hardware_video_acceleration}
+
+\section{Optimized Playback -- X11 Direct}%
+\label{sec:optimized_playback}
+
+Normally, when Cinelerra reads a video frame, it is copied into a \textit{Vframe}. This frame may also need other actions performed on it, such as a color model change. In addition, ffmpeg and libzmpeg \textit{can\_scale\_input}. So the read can be color transformed and scaled just by asking the library to do that. This means that if the compositor is in a \textit{good} state with no zoom, the VFrame read can be done in the fastest render color model, and already scaled to the correct size for the compositor. In reality, this is not what you need for editing, but quite often the \textit{virtualconsole} is not used because the render is media only -- that is \textit{just data}. If no data transforms are needed and the input scaling can be done, the vrender program detects this, and tells the codec to transmit the data in a compatible way to the compositor canvas. This is the \textit{X11 direct} data path.
+
+With the X11 video driver choice, large format files such as 4K, will playback faster than either X11-XV or X11-OpenGL. However, you still have the option to turn off the X11 direct data path if you use
+\texttt{Settings $\rightarrow$ Preferences, tab Playback A}, set video driver to X11 and uncheck \texttt{use direct X11 render if possible}.
+
+
+\section{Proxy Settings}%
+\label{sec:proxy_settings}
+
+Working with videos that have large image geometry can greatly impede editing. Instead you can substitute \textit{proxies} which will create smaller video image files from the original file that can then be edited more quickly. When you are done working on this smaller scale, you will need to bring up the Proxy settings menu again, and change the Scale factor back to the Original size so that all of your edits/work take affect on that original higher quality video on the timeline. You can not nest clips while in a proxied state; you will get the error \textit{Nesting not allowed when proxy scale $\ne$ 1}.
+
+To use this feature, select \texttt{Settings $\rightarrow$ Proxy settings} and change the Scale factor from Original size to your downsized choice. You can choose ffmpeg as the File Format and a choice of various codecs associated with that. A good choice is the default of \texttt{mpeg} which can usually be quite fast. In addition, to modify values for that codec, click on the wrench icon. When you have completed your choices, just click \texttt{OK}, and then the video tracks will be rendered. This may take some time, but previous proxy renders will be reused. The proxy videos will be added to your assets in a separate Proxy folder, and the video track edits will use the proxies. Proxy downsizing renders all loaded tracks, but only work on the $1^{st}$ video layer of any multi-layer media. Rendered proxy media is saved in the same directory as the original media. As usual, you can delete proxy files from the project or disk in the Resources window if you no longer want to retain them.
+
+There are two ways that the proxy files can be used, with or without input scaling. When the proxy is done without rescaling, the Mask, Camera and Projector automations are re-scaled accordingly. In this situation, the entire project will be re-sized so that the session is in the resized geometry. Not all plugins are useful when the project is rescaled, because the keyframe data must be in the original geometry. In this case, you can use the rescaler, by enabling \texttt{Use scaler (FFMPEG only)}. This has the added advantage that the project size does not change and the proxy media is down-scaled as usual and up-scaled on read-in, which means the project editing is done in full scale. Since decoding is done on smaller video, there is a time savings, but all rendering is done full scale. The main reason for using \textit{scaler} is that it does not change the image coordinate data, so that automation and plugin parameters will be in the original project geometry. This is not as fast as the first option, but is a performance gain, and may be needed if you are using plugins that need coordinate data such as the Title plugin. As noted, the scaler only works on ffmpeg video formats.
+
+In the upper right hand corner of the main window, there is a toggle button to easily switch back and forth when you have a proxied file on the timeline. The icon is to the left of the FF icon. It will have the letter “P” as the icon for Proxy or if \textit{Using Scaler}, the letter “S”. \quad \includegraphics[height=\baselineskip]{images/proxy-01.png} \quad This quick switch is especially useful when editing and you need to see a better image temporarily.
+
+Screencast in figure~\ref{fig:proxy-02} shows the Use scaler checked so you can still use plugins and the original project size is kept. The Scale factor pull-down gives you available size options. Note the new media dimensions shown (partially covered). If the size is an odd number, 1 is added to make the dimensions both even numbers.
+
+In the case of the scaler checkbox, it will retain that setting for ease of use.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.8\linewidth]{images/proxy-02.png}
+ \caption{Proxy settings dialog}
+ \label{fig:proxy-02}
+\end{figure}
+
+There is also a convenient \texttt{Beep on done} checkbox included so that you can work on other tasks until there is an audible notify of completion.
+
+A good choice for proxy settings with 1080p source video is:
+
+\begin{lstlisting}[language=bash]
+Scale Factor: 1/4
+Use Scaler: unchecked
+File Format: FFMPEG - mpeg
+Video Preset:
+Compression: mpeg.mpeg
+Bitrate: 1800000
+Quality: -1
+Pixels: yuv420p
+\end{lstlisting}
+
+If you get errors for some videos, such as those with strange variable bit rate or some types of files made on a smartphone, a usually reliable alternative is to change the following parameters:
+
+\begin{lstlisting}[language=bash]
+File Format: FFMPEG - mov
+Video Preset:
+Compression: mov.mov
+\end{lstlisting}
+
+Or if you want small files with high image quality, a File Format of \texttt{m2ts} is optimal. For example a 1 GB file can be reduced to 50 MB with scale $\frac{1}{2}$.
+
+Checking the \texttt{Auto proxy/scale media loads} results in any additional media loads to be automatically proxy scaled. However, single frame media such as PNG or JPEG \textit{stills}, can not be scaled to \textit{stream} media. If this type of media exists, you should \texttt{use scaler}.
+
+If you get error messages when creating proxies, check the Video wrench settings. These usually default to values that are expected to work correctly for the \textit{File Format} and codec you selected but they can be changed and may result in errors. If you get an error message of \textit{check\_frame\_rate failed} followed by \textit{Error making proxy} in the popup Errors window, do just that and check the Frame rate value by going to the Resources window, Media folder, and use the right mouse button for the Info option for that specific media in question. You can change the frame rate in this window to a more codec acceptable value. Different codecs may have different legal values.
+
+More specific information on which plugins need to use scaler is provided here next. If the keyframe data uses coordinate data that is absolute, then the scaler should be used. If the data is normalized (like always $0-100\%$) then the proxy can be done without the scaler. The session geometry format, shown in \texttt{Settings $\rightarrow$ Format} as width x height, is changed if the scaler is not used to cause all of the data to be in the reduced format. If this affects the plugin operation, then scaler should be used. Examples of plugins that need the scaler are: Title, AutoScale, Scale, ScaleRatio, and Translate. Most others are safe to use without scaling.
+
+\section{Some Settings Parameter Values}%
+\label{sec:settings_parameter_values}
+
+\texttt{Cache} in \texttt{Settings $\rightarrow$ Preferences, Performance tab} is used to store images on the timeline. One 1080p frame uses about 10 MB. The default setting is 256 and this is enough for testing and running. However, why not use more memory if it is available. To experiment for testing a good number tuned to the way you use your computer, set the cache to 0, start up Cinelerra, load a typical media file, play it and run \texttt{top} on the command line in another window to see how much memory is being used. In the \textit{top} display, look at \textit{free} memory. Whatever your computer is not using, is a good number to use for cache. If you start other programs, or change the design of the session so that it uses a lot of frame storage, you may need to experiment again later and resize accordingly.
+
+For system \textit{swap}, 1 GB seems to be more than sufficient. If the amount of memory being used by the program is \textit{close}, then swap might save you but often if swapping becomes necessary, it presents more problems and you end up killing the Cinelerra process anyway.
+
+\section{Tips for Improving Smaller Computers Use}%
+\label{sec:tips_improving_smaller_computers}
+
+A list of items to check for smaller computers that will help to use less cpu/memory/resources follows:
+
+\begin{itemize}
+ \item For large media files, use proxy to do your main editing.
+ \item In \texttt{Settings $\rightarrow$ Preferences, Appearance tab}, uncheck \textit{Use thumbnails in resource window}.
+ \item In \texttt{Settings $\rightarrow$ Preferences, Appearance tab}, uncheck \textit{Autocolor assets}.
+ \item Speed-up certain time-consuming FFmpeg plugins through use of a carefully selected \texttt{.opts} file.
+ \item For large media files, in \texttt{Settings $\rightarrow$ Preferences, Playback A}, Video Driver set \textit{use direct X11 render if possible}.
+ \item For the Video Driver in \texttt{Settings $\rightarrow$ Preferences, Playback A}, if using a good graphics card, choose \textit{X11-OpenGL}.
+ \item Set \textit{CIN\_HW\_DEV=vdpau} or \textit{vaapi} to use the graphics GPU for certain ffmpeg media decoding.
+ \item If you have multiple cpus or multiple computers, even if slow, take advantage of using \textit{Render Farm}.
+ \item When editing, \textit{background rendering} causes temporary output to be rendered constantly while the
+ timeline is being modified. The temporary output is displayed during playback whenever possible so
+ it does not have to be recalculated -- very useful for transitions and previewing effects that are slow.
+ \item In \texttt{Settings $\rightarrow$ Preferences, Playback A}, uncheck \textit{Play every frame} which means frames will be skipped as playback of the video falls behind.
+ \item Adjust \textit{Cache size} in \texttt{Settings $\rightarrow$ Preferences, Performance tab}, to not exhaust the memory and yet still provide decent playback.
+\end{itemize}
+
+\section{General Crash Handling Tips}%
+\label{sec:general_crash_tips}
+
+This section is a handy guide for describing various kinds of software computer system failures. Only some of these various lockups or crashes can be dealt with. Hopefully, it will help to have some hints to know what kind of failure it is, or to save your work or to avoid future problems. For most of this, your user name must be root, although you can certainly try to see if it works for you when not root.
+
+\begin{description}
+ \item[System lockups:] When the system locks up, it is usually a system problem. Normally an application program cannot lock up the system. It is a major goal of system design to prevent an application (app) from failing a system interface. This does not mean an app can not cause a system lockup, but it is unusual.
+ \item[Cinelerra crash:] This is covered in \ref{cha:Crash Dumps for Analysis} Crash Dumps for Analysis, chapter 18. Just a reminder that for best results you should be root and by providing a crash dump and as much other information as possible, you will be helping the developer to analyze the problem and fix it so that it can be avoided in the future.
+ \item[X Server crash:] Keyboard does not respond, screen is frozen, caps lock may operate LED light. Sometimes using \texttt{ctrl-alt-F1} $\dots$ \texttt{ctrl-alt-F7} (etc.) will allow you to regain control of a VT console. You can use this to login and check logs: eg. \textit{/var/log/Xorg.0.log}, \textit{dmesg}, \textit{journalctl} $\dots$ etc. If you have another computer, make sure a terminal server is configured (for example: rsh, ssh, or telnet), then remote login via this other computer and check the logs. Most important is to immediately note the current software state, and the very last thing that preceded the crash, i.e. last button click, last keystroke, $\dots$ or whatever.
+ \item[Kernel crash:] The machine goes completely dead. The keyboard caps lock LED will probably be flashing. Most likely the only way to see anything after the kernel crashes is to use a serial port console log and usually kdb, the kernel debugger, and special cabling. This requires a lot of setup, and is normally reserved for experts. Login from another computer will not work. Pinging the ip address will not respond since the network stack is part of the kernel. There are some virtual machine setups that will let you debug a \textit{guest} kernel, but this also requires a lot of setup, and affects which kernel is currently under test. The kdb route is preferable.
+ \item[Keyboard grabs, Server grabs, and Deadlocks:] A grab is an X-server state where all events are forced to just one window event stream. This forces the user to respond to the dialog. Things seems to be working, but no keypresses do anything useful. The system clock and other programs will still be working. The network will work for remote logins. Grabs can be canceled if the \texttt{/etc/X11/xorg.conf} X config contains special setup as shown below:
+\end{description}
+
+\begin{lstlisting}[language=bash]
+Section "ServerFlags"
+ Option "HandleSpecialKeys" "Always"
+ Option "AllowDeactivateGrabs" "True"
+ Option "AllowClosedownGrabs" "True"
+EndSection
+
+Section "InputDevice"
+ Identifier "Keyboard"
+ Driver "evdev"
+ ...
+ Option "XkbOptions" "terminate:ctrl_alt_bksp"
+ Option "XkbOptions" "grab:break_actions"
+EndSection
+\end{lstlisting}
+
+or to \texttt{\$HOME/.xinitrc}, add:
+
+\begin{lstlisting}[language=bash]
+# xkb terminate/grab actions disabled in xorg.conf, use:
+setxkbmap -option "grab:break_actions"
+setxkbmap -option "terminate:ctrl_alt_bksp"
+ctrl-alt-bksp = terminate the X-server, may restart automatically
+\end{lstlisting}
+
+
+Modal forms (always on top, and usually ptr/kbd grab) dialog boxes can lock a system by putting a form over another form holding a grab. This means the form that needs input may never get any because you can not get to it, and the result is a deadlock. Usually you will have to restart X (\texttt{ctrl-alt-bksp}).
+
+\begin{description}
+ \item[Window Manager issues:] The \textit{desktop} window manager can intercept and modify all kinds of user input. Mostly, this is a good thing, but can be a nuisance. If user keypresses can be programmed to trigger actions, then they may be useful to send \texttt{KILL} or \texttt{INTR} to an app that seems to be holding X's attention. For example:
+ \begin{lstlisting}[language=bash]
+ killall -INTR cinelerra,
+ killall -9 cinelerra,
+ killall X,
+ # but you must run as root to be able do this
+ \end{lstlisting}
+ The \texttt{ALT} and \texttt{META} keys may be intercepted by the window manager, and this can cause unexpected interface operations.
+\end{description}
+
+\section{Tips for Specific Operations}%
+\label{sec:tips_specific_operations}
+
+\subsection{Generating a 440 Hz tone}%
+\label{sub:generating_440_tone}
+
+To create a specific 440 Hz tone, follow these steps. You can vary the length, use more channels, or change the frequency to a different desired value (figure~\ref{fig:aeval}).
+
+\begin{enumerate}
+ \item Make sure there is an armed audio track on the timeline, get into Cut and Paste mode, and highlight
+ a selection or define In/Out points where you want to insert the audio tone.
+ \item Go to \texttt{Audio $\rightarrow$ Render effect}. Rendered effect usage is described in Effect Plugins (\ref{sec:rendered_effects}), chapter 10. This brings up a menu where you will select the desired effect which in this case is \textit{F\_aeval}. Also Select a file to render to, a File Format, and Insertion strategy of Paste at insertion point.
+ \item Click on the green \texttt{OK} checkmark which will popup the F\_aeval effect so that you can set the
+ parameters.
+ \item Highlight the \texttt{exprs} option and key in a specific audio filter expression which for 440 Hz would be:
+ $\sin(2\pi t\times440)$. Then hit the \texttt{Apply} button.
+ \item Next when you hit the green \texttt{OK} checkmark on the Cinelerra: Effect Prompt popup, you will have
+ your 440 Hz tone on the timeline plus in the select file that you chose to render it to.
+ \item To use 2 channels instead of 1, in the F\_aeval menu highlight the \texttt{channel\_layout} option and change
+ that to 1C|2C instead of the usual default of 1C.
+\end{enumerate}
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=1.0\linewidth]{images/aeval.png}
+ \caption{Use Audio$\rightarrow$Render effect to set render parameter values and then that effect can be varied.}
+ \label{fig:aeval}
+\end{figure}
+
+\subsection{Camera supplied LUTs}%
+\label{sub:camera_supplied_luts}
+
+A LUT, acronym for Look-Up Table, is a mathematically precise way of taking specific RGB image values from a source image and modifying them to new RGB values by changing the hue, saturation and brightness values of that source image. In other words, LUTs are used to map one color space to another. Some high-end cameras supply a \texttt{.cube} file to use as input. There are several different ffmpeg plugins included with CinGG for using Lut's. These are:
+
+\begin{description}
+ \item[F\_lut:] Compute and apply a lookup table to the RGB/YUV input video.
+ \item[F\_lut1d:] Adjust colors using a 1D LUT.
+ \item[F\_lut3d:] Apply a 3D LUT to an input video.
+ \item[F\_lutrgb:] Compute and apply a lookup table to the RGB input video.
+ \item[F\_lutyuv:] Compute and apply a lookup table to the YUV input video.
+\end{description}
+
+For example, to use a 3dlut simply load your video, drop the F\_lut3d plugin on that track, and bring up the lut3d controls window, highlight the \texttt{file} option, key in your file name (whit path), and hit \texttt{apply} to have the lut take effect. To easily adjust, move the \texttt{fader} slider in the patchbay for that video track.
+
+\subsection{Encoding into Dolby Pro Logic}%
+\label{sub:encoding_dolby_pro_logic}
+
+Dolby pro logic is an easy way to output 6 channel audio from a 2-channel soundcard with degraded but useful results. Rudimentary Dolby pro logic encoding can be achieved with usage of some effects.
+
+\begin{enumerate}
+ \item First, create the front left and right channels. Create 2 audio tracks, each carrying either the left or
+ right channel. Pan the left channel to the left and the right channel to the right with the pan control.
+ \item Now create the rear left and right channels. Create another 2 audio tracks as above -- the left channel
+ panned left and the right channel panned right. Then apply invert audio to both new channels and
+ the signals will come out of the rear speakers.
+ \item Next, create the center channel by creating a single audio track with monaural audio from a
+ different source. Center it with the pan control and the signal will come out of the center speaker.
+\end{enumerate}
+
+\begin{itemize}
+ \item If a copy of the signal in the back speakers is desired in any single front speaker, the signal in the back
+ speakers must be delayed by at least $0.05$ seconds and a single new track should be created. Pan the
+ new track to orient the signal in the front speakers.
+ \item If the same signal is desired in all the speakers except the center speaker, delay the back speakers by
+ $0.5$ seconds and delay either the front left or front right by $0.2$ seconds.
+ \item If you want to hear something from the subwoofer, create a new track, select a range, drop a
+ synthesizer effect, and set the frequency below $60 Hz$. The subwoofer merely plays anything below
+ $60Hz$ or so.
+\end{itemize}
+
+Other tricks you can perform to separate the speakers are parametric equalization to play only selected ranges of frequencies through different speakers and lowpass filtering to play signals through the subwoofer.
+
+\subsection{Improving Analog TV Quality}%
+\label{sub:improving_tv_quality}
+
+The picture quality on analog TV is not always good but you can modify parameters in Cinelerra to make it look more like it did in the studio.
+
+First, when capturing the video, capture it in the highest resolution possible. For Europeans this would be $720\times576$ and for North Americans, $720\times480$. Do not adjust the brightness or contrast in the recording monitor, but you might want to max out the color. Capture the video using MJPEG or uncompressed Component Video if possible; if not possible, then capture it using JPEG preferably or RGB if that is all that will work. Now on the timeline use Settings $\rightarrow$ Format to set a YUV colorspace, drop a \textit{Downsample} effect on the footage and set it as follows:
+
+\begin{lstlisting}[language=bash]
+Horizontal: 2
+Horizontal offset: 0
+Vertical: 2
+Vertical offset: 0
+ red
+x green
+x blue
+ alpha
+\end{lstlisting}
+
+Use the Camera in the compositor to shift the picture up or down a line to remove the most color interference from the image. If you have vertical blanking information or crawls which constantly change in each frame, block them out by using a Mask. This improves compression ratios. More invasive quality improvement techniques involve removing the interlace via deinterlacing.
+
+\subsection{Remove Interlacing}%
+\label{sub:remove_interlacing}
+
+Interlacing often exists on older video sources, such as camcorders, and was previously used in broadcast television. Playing this video results in jagged images on a computer monitor, but with Cinelerra you can use deinterlacing effects to solve this. After some experimentation, it has been determined that the FFmpeg \texttt{F\_kerndeint} plugin seems to produce the best results with the least amount of fiddling. But some of the parameters described next are pertinent to other potential plugin usage.
+
+\begin{description}
+ \item[Line Doubling:] done by the \texttt{Deinterlace} effect when set to \textit{Odd} lines or \textit{Even} lines. When applied to a track it reduces the vertical resolution by $\frac{1}{2}$ and gives you progressive frames with stairstepping. This is only useful when followed by a scale effect which reduces the image to half its size.
+ \item[Line averaging:] the \texttt{Deinterlace} effect when set to \textit{Average even} lines or \textit{Average odd} lines does exactly what line doubling does except instead of making straight copies of the lines, it makes averages of the lines. This is actually useful for all scaling.
+ \item[Inverse Telecine:] this is the most effective deinterlacing tool when the footage is an NTSC TV broadcast of a film. It is described in Effect Plugins (\ref{sub:inverse_telecine}), chapter 10.
+ \item[Time base correction:] the previously discussed three tools either destroy footage irreversibly or do not work at times. Time base correction may be a better tool to use because it leaves the footage intact. It does not reduce resolution, perceptually at least, and does not cause jittery timing.
+ \item[Frames to Fields effect:] converts each frame to two frames, so it must be used on a timeline whose project frame rate is twice the footage's frame rate. In the first frame it puts a line-averaged copy of the even lines. In the second frame it puts a line-averaged copy of the odd lines. When played back at full framerate it gives the illusion of progressive video with no loss of detail. This effect can be reversed with the Fields to Frames effect, which combines two frames of footage back into the one original interlaced frame at half the framerate. However, keep in mind that Frames to Fields inputs frames at half the framerate as the project. Effects before Frames to Fields process at the reduced framerate. The output of Frames to Fields can not be compressed as efficiently as the original because it introduces vertical twitter and a super high framerate. Interlaced $29.97$ fps footage can be made to look like film by applying Frames to Fields and then reducing the project frame rate of the resulting $59.94$ fps footage to $23.97$ fps. This produces no timing jitter and the occasional odd field gives the illusion of more detail than there would be if you just line averaged the original. It is described in Effect Plugins (\ref{sub:frames_to_fields}), chapter 10.
+ \item[HDTV exceptions:] $1920\times1080$ HDTV is encoded in a special way. If it is a broadcast of original HDTV film, an inverse telecine works. But if it is a rebroadcast of a $720\times480$ source, you need to use a time base and line doubling algorithm to deinterlace it.
+\end{description}
+
+\subsection{Making video look like film}%
+\label{sub:making_video_look_film}
+
+With an older camcorder video which has low quality video, you can improve the results by turning it into progressive 24 fps output as close as possible. Only do this for low quality video.
+
+\begin{enumerate}
+ \item Set project framerate to twice the video framerate.
+ \item Apply a \texttt{Sharpen} effect. Set it to sharpness: 25, no interlacing, and horizontal only.
+ \item Drop a \texttt{Frame to Fields} effect on the same track. Set Average Empty Rows to on and play through
+ the video a few times to figure out which field is first. If the wrong field is first, the motion is shaky.
+ Any editing in the doubled frame rate may now damage the field order. It is not clear which is the
+ easiest way to support warnings for field glitches but you should go back to the normal framerate to
+ do editing or play test to make sure the fields are right.
+ \item Render just the video to the highest quality file possible.
+ \item Import the video back to a new track. Set the project framerate to 24. The new track should now
+ look more like a file with sharper images than the original footage.
+\end{enumerate}
+
+This entire procedure could be implemented in one non-realtime effect, but the problem with that is you will most often want to keep the field based output and the 24 fps output for historical purposes. A non-realtime effect would require all that processing just for the 24 fps copy.
+
+\subsection{Clearing out haze}%
+\label{sub:clearing_out_haze}
+
+If you photograph a lot of haze instead of blue sky, these horizon shots will usually need more depth. You can use the \texttt{gradient} effect to improve your video. Drop the gradient effect on hazy tracks and set the following parameters:
+
+\begin{lstlisting}[language=bash]
+Angle: 0
+Inner radius: 0
+Outer radius: 40
+Inner color: blue 100% alpha
+Outer color: blue 0% alpha
+\end{lstlisting}
+
+It is important to set the $0\%$ alpha color to blue even though it is $0\%$ alpha. The color of the outer alpha is still interpolated with the inner color. This is a generally applicable setting for gradient. Some scenes may work better with orange or brown for an evening feel.
+
+\subsection{Making a ringtone for a cell phone}%
+\label{sub:make_ringtone_phone}
+
+\begin{enumerate}
+ \item Go to \texttt{File $\rightarrow$ Load files$\dots$} and load a sound file with Insertion strategy: \textit{Replace current project}.
+ \item Go to \texttt{Settings $\rightarrow$ Format }change \textit{Channels} to 1 and \textit{Samplerate} to 16000 or 22050.
+ \item Highlight a region of the timeline to use for the ringtone. To improve sound quality on the cell
+ phone, you need the maximum amplitude in as many parts of the sound as possible.
+ \item Right click on track Audio 1 and select \texttt{Attach effect}. Highlight the \textit{Compressor} effect and hit
+ \texttt{Attach} in the attachment popup.
+ \item Make sure the insertion point or highlighted area is in the region with the Compressor effect.
+ \item Right click on track Audio 2 and select \texttt{Attach effect}.
+ \item Highlight Audio 1 Compressor and hit \texttt{Attach}.
+ \item Click the Audio 1 Compressor's magnifying glass to bring up the compressor GUI.
+ \item Set the following parameters:
+ \begin{lstlisting}[language=bash]
+ Reaction secs: -0.1
+ Decay secs: 0.1
+ Trigger Type: Total
+ Trigger: 0
+ Smooth only: No
+ \end{lstlisting}
+ \item Click Clear to clear the graph. Click anywhere in the grid area and drag a new point to 0 Output
+ and -50 Input. The graph should look similar to the figure~\ref{fig:ringtone}.
+ \item Go to \texttt{File $\rightarrow$ Render}. Specify the name of an mp3 file to output to. Set the file format to MPEG
+ Audio. Click the wrench for Audio and set Layer to III and Kbits per second to 24 or 32. Check
+ Render audio tracks and uncheck Render video tracks. Hit OK to render the file.
+\end{enumerate}
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.8\linewidth]{images/ringtone.png}
+ \caption{Using the Compressor plugin graph to create a ringtone}
+ \label{fig:ringtone}
+\end{figure}
+
+The resulting .mp3 file can be uploaded to a web server and then the phone's web browser can download the .mp3 file directly from the URL. There may be a size limit on the file.
+
+\subsection{Time stretching audio}%
+\label{sub:time_stretching_audio}
+
+It may appear that time stretching audio is a matter of selecting a region of the audio tracks, enabling recording for the desired tracks, going to\texttt{ Audio $\rightarrow$ Render Effect}, and applying \textit{TimeStretch}. In actuality there are 3 audio effects for time stretching: Time Stretch, Resample, and Asset info dialog.
+
+\textit{Time Stretch} applies a fast Fourier transform to try to change the duration without changing the pitch, but this introduces windowing artifacts to the audio. It is only useful for large changes in time because obvious changes in duration make windowing artifacts less obtrusive.
+
+For smaller changes in duration, in the range of $5\%$, \textit{Resample} should be used. This changes the pitch of the audio but small enough changes are not noticeable. Resample does not introduce any windowing artifacts, so this is most useful for slight duration changes where the listener is not supposed to know what is going on.
+
+Another way to change duration slightly is to go to the Resources window, highlight the media folder, right click on an audio file, click on \textit{Info}. Adjust the sample rate in the Info dialog to adjust the duration. This method also requires left clicking on the right boundary of the audio tracks and dragging left or right to correspond to the length changes.
+
+\subsection{Pan and zoom: still images}%
+\label{sub:pan_zoom_still_image}
+
+Cinelerra's powerful keyframe features allow you to use pan and zoom effects on still pictures.
+
+\begin{enumerate}
+ \item Load and create a clip from a still image. Make the clip 10 seconds long.
+ \item Activate the automatic generation of keyframes.
+ \item Using the transport controls, go to the beginning of the clip.
+ \item Using the compositing camera control set the clip's initial position.
+ \item Using the transport controls, move forward a couple of seconds on the clip.
+ \item Dragging on the compositing camera, move the camera center to a new position further along.
+ \item Next go to the beginning of the clip and play it.
+\end{enumerate}
+
+You can see that the camera smoothly flows from keyframe point to next keyframe point, as Cinelerra automatically adjusts the camera movement in straight lines from point to point.
+
--- /dev/null
+\chapter{Troubleshooting and Help}%
+\label{cha:Troubleshooting and Help}
+
+You can report potential problems, bugs, and crashes to the Cinelerra-GG website at:
+\medskip
+
+\hspace{10mm}\href{https://www.cinelerra-gg.org/}{https://www.cinelerra-gg.org}
+\medskip
+
+Here you can log the problem into the MantisBT bugtracker, or use the forum Q\&A for help from other users, or email the
+helpful if instead of starting Cinelerra from its application icon, start from a window so that if there are error
+messages related to the problem, they can be captured from the screen and emailed or logged. The command to run
+from a window is: {\textless}directory\_path of where you installed cinelerra{\textgreater}/bin/cin -- for example if
+installed in the directory /mnt0/build5/cinelerra-5.1, you would execute the following command to start the program:
+\ \ /mnt0/build5/cinelerra-5.1/bin/cin \ . \ The problem you are experiencing may be as simple as an error due to the
+settings in your \$HOME/.bcast5 subdirectory so you may want to first rename your current .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.
+\medskip
+
+Some other troubleshooting help is also included in other sections of this manual for specific features.
+
+\section{What to Include in Problem Reports}%
+\label{cha:What to Include in Problem Reports}
+For the best help, if you have a reproducible problem and can provide the following list of materials for analysis, it
+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
+a real bug which a programmer would like to fix rather quickly. \ Although it is not always necessary to provide this
+much information, it eliminates the ``try this'' or ``did you do this?'' and a lot of ``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.}
+\medskip
+
+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.
+\medskip
+
+\begin{itemize}[nosep]
+ \item Provide a detailed description of the problem and the last operation performed if you remember it.
+ \item Supply a small representative sample of the original input that exhibits the issue.
+ \item If possible, also provide the rendered output, again using that representative sample.
+ \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 File pulldown of ``Export Project...'' with the Copy option. That way all of the files will be in 1 location and easily loaded onto any other computer.
+ \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.
+ \item Include the Operating System name and version number and version of Cin that you are running. You can find the date and time ``built'' in the Settings$\rightarrow$Preferences, About tab, bottom left corner.
+\end{itemize}
+\medskip
+
+It is better to upload any files to a drop site as some of them can be quite large.
+\medskip
+
+\textbf{How to create a session file:} \ from the menubar pulldown File$\rightarrow $Save\_as{\dots} \ and choose a
+filename, for example /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.
+\medskip
+
+\textbf{How to create a representative small sample:}
+\begin{enumerate}[nosep]
+ \item open the input media, set up the scenario as you normally would to start the project render;
+ \item select 5-15 seconds of media using the edit mode left mouse button drag highlighting on the timeline;
+ \item start the render dialog (Shift R), set the filename path, and set ``Render range'' to ``Selection'';
+ \item recommended ``Insertion strategy'' is ``Replace current project''; then press the checkmark OK. The result will ``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.
+\end{enumerate}
+
+
+\section{Crash Dumps for Analysis}%
+\label{cha:Crash Dumps for Analysis}
+If you get a SEGV crash and can explain what steps you took, a /tmp/cinelerra\_{\textless}pid{\textgreater}.dmp file is
+very useful for analysis. \ You can also use Ctrl-c in the controlling window to force an INTR signal interrupt when
+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
+is best to upload the .dmp, input files and other files to datafilehost or similar temporary site as they may be quite
+large. \ The .dmp filename looks like /tmp/cinelerra\_{\textless}pid{\textgreater}.dmp. \ Log a bug report or email all
+helpful information on the crash, location of uploaded files, and list of setup steps that illustrate the problem to
+\medskip
+
+\begin{enumerate}[nosep]
+ \item Use the latest version of Cinelerra as you want to make sure the problem has not been fixed.
+ \item Be sure gdb is installed (usually installed but if not, it is easy to do so).
+ \item Run as root if at all possible (this enables using gdb to create a full /tmp/cinelerra*.dmp file).
+ \item Be sure Settings-{\textgreater}Preferences-{\textgreater}Interface-{\textgreater}trap SEGV and trap INTR are checked.
+ \item Invoke the error. This should create the file /tmp/cinelerra-{\textless}pid{\textgreater}.dmp .
+\end{enumerate}
+\medskip
+
+For those who can not run as root or can not create the problem while running as root, another method to create a dump
+is available. \ Here are the steps to do so -- you should also have gdb installed.
+\medskip
+
+\begin{enumerate}[nosep]
+ \item Temporarily login as root and key in: \ \ echo 0 {\textgreater} /proc/sys/kernel/yama/ptrace\_scope . This opens up ptrace, used by gdb (the debugger). You will want to reverse this when done.
+ \item Run Cinelerra 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 /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.
+ \item Email the output that shows in the window from where you started up Cinelerra and upload or directly email the /tmp/cinelerra*.dmp file (this file may be too large for the Mailing List).
+ \item After you are finished creating/testing the problem, reverse the previous setting while logged in as root by keying in:\ \ echo 1 {\textgreater} /proc/sys/kernel/yama/ptrace\_scope .
+\end{enumerate}
+
+\textcolor{red}{Even if you are not logged in as root or have ptrace enabled, if you
+have a .dmp file and know what the last thing you did is, please provide the .dmp file for analysis.} There is a low
+probability that the dump will prove useful, but if the problem can be recreated it can usually be fixed!
+
+\section{When things go wrong}%
+\label{cha:When things go wrong}
+Sometimes things go wrong and there are some ways to continue your work without much trouble. Below is a list of items
+to try before abandoning your session.
+
+\begin{enumerate}[nosep]
+ \item If you suddenly get 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 Settings$\rightarrow$Preferences, Interface tab, Index Files section, ``Delete existing indexes''. This will take some time to recreate all of the currently loaded media and subsequent loads, but can be an easy fix.
+ \item On an older computer, if you are playing media and it can not keep up, you can turn off ``Play every frame'' in the Video Out tab of Settings$\rightarrow$Preferences, Playback tab. You will then see the video jump as it skips frames in order to stay caught up.
+ \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 Settings$\rightarrow$Preferences, Performance tab.
+ \item After saving your current session and exiting Cinelerra, you might want to rename your current \$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 current preferences will be lost until you go back to your original .bcast5.
+ \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. Cinelerra needs more keyframes to determine position. You can temporarily use Settings$\rightarrow$Proxy to 1/2 size to put in keyframes. How to use Proxy is explained in Performance Tips and Other Tips, chapter 19.
+ \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 Settings$\rightarrow $Preferences, Recording tab so that the excess frames are dropped instead of buffered.
+ \item If loading files locks up, this might be because Cinelerra 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 Settings$\rightarrow$Preferences, Appearance tab and disable \textit{Use}\textit{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.
+ \item For an older computer with less CPU power, in 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.
+\end{enumerate}
+\medskip
+
+{\bfseries
+Some Helpful User Readable Text Dumps}
+\medskip
+
+On the File pulldown, there is a {\textquotedbl}Dumps{\textquotedbl} option with a submenu of dump EDL, Plugins, Assets, and Undo. \ In all cases, you will have to have started Cinelerra from a window instead of from an application icon and
+the text results will be shown in that window.
+\medskip
+
+\begin{itemize}[nosep]
+\item \textit{Dump EDL} will display your current EDL state on the screen in the window from where you started Cin. This can be useful to see information concerning a specific edit or a file path.
+\item \textit{Dump Plugins} will show the names of the currently loaded plugins.
+\item \textit{Dump Assets} displays the media assets that you have loaded and various pertinent details on each, such as samplerate, width, and height.
+\item \textit{Dump Undo }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.
+\end{itemize}
+\medskip
+
+{\bfseries
+Common Problems}
+
+Some messages you may see in the startup window may or may not be errors. Some examples are:
+\bigskip
+
+\textit{FFMPEG::open\_decoder: some stream times estimated:}\textbf{ \ \ }/your directory/filename
+\medskip
+
+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 Cinelerra uses versus ffmpeg may be counted differently.
+\bigskip
+
+\textit{AudioALSA::write\_buffer err -32(Broken pipe) at sample \#}
+\medskip
+
+This indicates that there is something wrong with the audio. Some reasons for this are:
+\begin{itemize}[nosep]
+ \item You simply stopped playing in Cinelerra while the audio is in progress.
+ \item Running on a computer where there is no sound card.
+ \item Incorrect setup of the audio parameters in the Settings-{\textgreater}Preferences, Playback tab.
+ \item Your sound system is already in use by another program, like when playing {\textquotedbl}tunes{\textquotedbl} outside Cin.
+\end{itemize}
+\bigskip
+
+\textit{Playback does not keep up so you hear the audio ahead of the video.}
+\medskip
+
+When this occurs, it most likely means that there is not enough CPU power to keep up. You can go into Settings$\rightarrow$Preferences, the Playback tab and uncheck ``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 Rendering, chapter 7.
+\bigskip
+
+\textit{Cinelerra will not start and produces error message on the startup window.}
+\medskip
+
+There can be various reasons that Cinelerra does not come up. Some of the recent reasons are listed here. Please notify the \href{http://www.cinelerra-gg.org/}{www.cinelerra-gg.org} website when you have any unknown startup issues.
+\medskip
+
+\begin{itemize}[nosep]
+ \item Cin 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.
+ \item When a library goes from one version to a later version, sometimes a pre-built Cin 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:\newline``cin: error while loading shared libraries: libvpx.so.5: cannot open shared object file: No such file''
+\end{itemize}
+\medskip
+
+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.
+\bigskip
+
+\textit{ Loading a very large number of media files, for example 500 clips, crashes Cinelerra with messages similar to the following that are displayed in the window from where you started Cin:}
+\medskip
+
+\begin{lstlisting}[numbers=none,xleftmargin=10mm]
+
+ BC_DisplayInfo::init_window: cannot open display "".
+ BC_DisplayInfo::init_window: cannot connect to X server.
+ unjoined tids / owner 42
+ 00007feb27fff700 / 00007feb8f496700 9MainError
+ 00007feb267fc700 / 00007feb7affd700 18FFMPEGScanProgress
+ ...
+
+\end{lstlisting}
+
+This usually indicates that you are out of Operating System file descriptors. You can increase the amount easily with the following command line: ulimit -n 4096 where 4096 is a size suggestion but can be increased. You can include this command line in your .bashrc or .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 /etc/security/limits.conf. Alternatively, you can reduce the number of file descriptors needed by going into Settings>Preferences, Appearance tab and unchecking the flag “use thumbnails in resource window”.
+
+\bigskip
+\textit{Masking Feather is not working and produces error messages on the startup window similar to:}
+\medskip
+
+\begin{lstlisting}[numbers=none,xleftmargin=10mm]
+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
+Playback3D::print_error:
+#version 430 // vertex shader
+in vec3 in_pos;
+void main000() \{
+gl_Position = vec4(in_pos-vec3(0.5,0.5,0.), .5);
+}
+void main() \{
+main000();
+}
+\end{lstlisting}
+
+In the mask window, check the box ``Disable OpenGL masking'' to use software instead of OpenGL.
+
+\section{Menu Bar Shell Commands}%
+\label{Menu Bar Shell Commands}
+
+In order to provide some types of help, the Menu Bar Shell Commands are available for customization purposes. \ In the
+main window on the top line containing the File, Edit, {\dots} Window pulldown menus, all the way to the right hand
+side is the ``shell cmds'' icon. \ You might see a small gold-color bordered box with the {\textgreater}\_.\_ inside
+and if you mouse over it, the tooltip says ``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
+Cinelerra.
+\medskip
+
+The Shell Cmds popup menu items are configured in:
+\medskip
+
+\hspace{10mm}Settings$\rightarrow$Preferences$\rightarrow$Interface$\rightarrow$Shell Commands
+\medskip
+
+This runs a dialog that lets you Add/Del/Edit the scripts in the main menu popup. \ Possible options are:\newline
+
+\begin{enumerate}[nosep,]
+ \item \textit{Add} a new menu item/script:\newline
+\ \ \ \ click on the \textit{Add} button\newline
+\ \ \ \ in the Label box, change the word {\textquotedbl}new{\textquotedbl} to the desired menu label (for example:
+Graphics Editor)\newline
+\ \ \ \ in the Commands box, type the command lines to be included in the script (for example: gimp)\newline
+\ \ \ \ click the green checkmark for OK in the Commands window\newline
+\ \ \ \ click the green checkmark for OK in the Shell window\newline
+\ \ \ \ click on OK or Apply in the Preferences window\newline
+ \item \textit{Del} to delete an existing menu item:\newline
+\ \ \ \ \ select to highlight an entry in the Cinelerra: Shell listbox\newline
+\ \ \ \ \ click on the \textit{Del }button\newline
+\ \ \ \ \ click the green checkmark for OK in the Shell window\newline
+\ \ \ \ \ click on OK or Apply in the Preferences window (the entry is now deleted)\newline
+ \item \textit{Edit} an existing menu item:\newline
+\ \ \ \ select to highlight an entry in the Cinelerra: Shell listbox\newline
+\ \ \ \ click on the \textit{Edit} button (the Commands window appears)\newline
+\ \ \ \ set the label and/or commands to the new desired values\newline
+\ \ \ \ click on the green checkmark for OK in the Commands window\newline
+\ \ \ \ click on the green checkmark for OK in the Shell window\newline
+\ \ \ \ click on OK or Apply in the Preferences window
+\end{enumerate}
+\medskip
+
+Next time you click on the ``shell cmds'' icon, you will have the changes you made in effect.\newline
+
+Both the \textit{Add} and \textit{Edit} options have checkboxes in the Commands window for the following:
+\medskip
+
+\begin{itemize}[nosep]
+ \item OnExit notify \ \ \ choose Always, Never, or On error to get a popup window notify
+ \item run path/script.sh + argvs \ \ \ to run a particular script with argvs (\$1, \$2,{\dots} arguments)
+\end{itemize}
+
+
+{\ttfamily
+\textrm{{When modifications to the Shell Cmds are included in a new Cinelerra 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 \$HOME/.bcast5/Cinelerra\_rc file to delete the lines that are all grouped together that begin with the letters: \ SHBTN \ \ (the entire line - these are the SHell BuTtoNs). \ You should first Quit out of Cinelerra, edit the file, and then when you restart Cinelerra, it will create the new default buttons in that same file.}}}
+\medskip
+
+There are 2 specific Cinelerra file names that have unique characteristics that allow for usage from a user-defined
+script. \ The first one is an environment variable, CIN\_RENDER which is used in the RenderMux shell command that is already setup. \ It contains the complete path and filename of the file in your session that you selected as ``Select a file to render to'' when you ran a Render operation.
+\medskip
+
+The second one concerns usage of the Resource window assets to use as argvs in shell scripts. \ The added command line
+can ONLY be a script. \ Then if your script refers to \$1, \$2 and \$3 and you highlight 3 files in the Media folder,
+their full path name will be used as the argvs to your script. \ For example, if you added a shell commands script
+\ /workspace/script.sh \ that contains the following lines:
+
+\begin{lstlisting}[numbers=none,xleftmargin=10mm]
+cp ``\$1'' /tmp/temporary_copy
+cp ``\$2'' /tmp/new_copy
+cp ``\$3'' /tmp/file_to_upload
+\end{lstlisting}
+
+and you highlight 3 files in the Resources window called ABC.mp4, 123.mp4, and 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 /tmp.
+\medskip
+
+There are some Help features currently included in the Shell Cmds menu. \ Those available are:
+\medskip
+
+\begin{enumerate}[nosep]
+ \item \textit{Current Manual} in PDF format from cinelerra-gg.org or automatically downloaded.
+ \item \textit{Setting Shell Commands} ``how to'' which explains how to configure your own commands.
+ \item \textit{Shortcuts} html file for easily looking up a particular shortcut.
+ \item \textit{RenderMux} shell script to use ffmpeg concatenate to copy files such as look.mp4001, look.mp4002, look.mp4005{\dots} that were rendered using ``Create new file at each label'' or with the Render Farm.
+\end{enumerate}
+\clearpage
+
+\begin{figure}[h!]
+ \centering
+ \includegraphics[width=0.8\linewidth]{trouble-img001.png}
+ \caption{Some windows used to manipulate Shell Commands scripts}
+ \label{fig:Shell script manupulation}
+\end{figure}
+
+\section{Cinelerra Command Line -h}%
+\label{cha:Cinelerra Command Line -h}
+
+To see the command line parameters available to use with Cinelerra, key in:
+
+\hspace{10mm}/\{your Cinelerra directory path\}/bin/cin -h
+\medskip
+
+What will be shown in the window where this line was entered is:
+\medskip
+
+Usage:
+
+./cin [-f] [-c configuration] [-d port] [-n nice] [-r batch file] [filenames]
+
+-d = Run in the background as renderfarm client. The port (400) is optional.\\
+-f = Run in the foreground as renderfarm client. Substitute for -d.\\
+-n = Nice value if running as renderfarm client. (19)\\
+-c = Configuration file to use instead of /root/.bcast5/Cinelerra\_rc.\\
+-r = batch render the contents of the batch file (/root/.bcast5/batchrender.rc) with no gui. batch file is optional.\\
+-S = do not reload perpetual session\\
+-x = reload from backup\\
+\\
+filenames = files to load
+
projects / goodguy / cin-manual-latex.git / commitdiff
