2 \label{cha:Installation}
5 \section{\CGG{} AppImage}%
6 \label{sec:cin_gg_appimage}
9 The main way to install \CGG{} is to use the AppImage. This is updated regularly and works for every distro, since it already contains the necessary dependencies.
10 A big advantage of using the AppImage format is that it is only 1/3 the size of the normal install,
11 and since each release is named differently, you can keep a number of versions in a directory,
12 and when testing from a terminal you just have to type CinGG, then hit tab, and complete it to
13 the desired date release.
14 For 64-bit systems you can choose between an image with up-to-date libraries or one that supports older libraries, which you should use only if the first image gives you problems with unsupported libs. There is also a 32-bit older distro available that has \textit{i686} as part of the filename that currently works on older distros but may not work on the newest distros
15 (most of the popular Linux distributions such as Arch, Ubuntu, and Fedora have dropped support for this older architecture). In any case, if you are using a 32-bit Linux distro, you should compile your sources from git or use a precompiled binary\protect\footnote{Remember that a 32-bit distro does not address more than 4GB of memory, so you may have stability and performance problems with large, high-resolution mediafiles.}. And there is a 8/10/12 bit newer distro that handles 8 or 10 or 12 bits that has \textit{multibit} as part of the filename. Installing the appimage is simple:
17 Download the file from:
19 \url{https://cinelerra-gg.org/download/images/}
21 Some example file names are as follows - where 8 digits represent yyyymmdd:
23 \begin{lstlisting}[style=sh]
24 CinGG-20230131-x86_64.AppImage
25 (currently based on Fedora 32, linux kernel 5.8.15, libc version 2.31)
26 CinGG-20230131-x86_64-older-distros.AppImage
27 (currently based on Ubuntu 16.04, libc version 2.23)
28 CinGG-20230131-i686.AppImage
29 (currently based on Debian 9, linux kernel 4.9, use "newer" for Debian 11.0)
30 CinGG-20230131-i686-newer-distros.AppImage
31 (currently based on Debian 11, linux kernel 5.10)
32 CinGG-20230131-x86_64-multibit.AppImage
33 (currently based on Fedora 32, libc version 2.31)
34 CinGG-20230131-x86_64-older-distros-multibit.AppImage
35 (currently based on Fedora 29 - runs on RHEL8 - linux kernel 4.19.9, libc version 2.28)
36 CinGG-20230930-alternative_shortcuts.AppImage
37 (currently based on Ubuntu 16.04, libc version 2.23)
40 Make the file executable with the proper execute permissions either from the GUI of the Desktop Environment used (link to the file) or from a terminal window. Make sure you are already in the directory containing the appimage:
42 \begin{lstlisting}[style=sh]
43 $ chmod u+x CinGG-yyyymmdd.AppImage
46 Finally start the program from a window in the directory where the image is stored:
48 \begin{lstlisting}[style=sh]
49 $ ./CinGG-yyyymmdd.AppImpage
52 or create a convenient desktop icon with a link to the run action, or do a \textit{Desktop Integration} manually or with external programs. There is a
53 description of a GUI methodology for doing so in this file on the webiste:
55 \url{https://cinelerra-gg.org/download/images/README\_appimage.txt}
57 Most distros already have the libraries to run the appimage, but if not you may need an additional installation. For example Arch Linux needs the \texttt{libappimage} package.
59 \begin{lstlisting}[style=sh]
60 sudo pacman -S libappimage
63 And Leap 15.3 (OpenSUSE) requires installation of the \textit{appimage} package.
65 \begin{lstlisting}[style=sh]
66 sudo zypper se -is appimage
69 In addition, if you are using the OpenGL video driver, you will need to install the appropriate OpenGL
70 drivers for your Operating System graphics board because libGLU.so and other OpenGL libraries are
71 not included in the AppImage.
73 Using AppImage means you can't have the installation folder and work on the files. To unpack the AppImage and get its structure in folders and files see \nameref{sub:managing_appimage} To create, edit and manage appimages see \nameref{sub:built_appimage_scratch}.
75 \subsection{AppImage with Standard Shortcuts}
76 \label{sec:appimage_standard_shortcuts}
78 In video editing it is important to learn how to use shortcuts to speed up your work. \CGG{} uses shortcuts different from those considered standard in both the Linux world and video editing. For example, \texttt{"s"} is used instead of \texttt{Ctrl+S}, \texttt{"q"} instead of \texttt{Ctrl+Q}, and even the classic editing keys \texttt{J, K, L} are different.
79 In addition, in \CGG{} the keys are fixed and not customizable. A new user may have a hard time getting used to a new combination of shortcuts. To make it a little easier, an appimage containing a patch that makes use of some of the more frequently used classic key combinations is available. It can be downloaded \href{https://cinelerra-gg.org/download/images/CinGG-20230930-alternative_shortcuts.AppImage}{here} (note that the file contains the month and last day of the month, but you will want to go up a directory and download the latest date instead to include the current changes). A table showing the changes from \CGG{} mode to standard mode can be found here: \nameref{sec:alternative_shortcuts}.
81 \section{Download Already Built \CGG{}}%
82 \label{sec:download_already_built_cinelerra_gg}
86 \includegraphics[width=1.0\linewidth]{download-distros.png}
87 \caption{Screencast of the website Download page for installing \CGG{} for various O/S.}
88 \label{fig:download-distros}
91 All of these images are dated 10/31/2020 and are no longer being maintained. They
92 will still work on the version of the O/S in use at that time but will have none of
93 the latest features. You should use the simpler AppImage instead as described previously.
95 If you prefer to not have to take the time to build \CGG{} Infinity
96 yourself, there are pre-built dynamic or static binaries for various
97 versions of Ubuntu, Mint, Suse, Fedora, Debian, Centos, Arch, and
98 Slackware linux as well as Gentoo and FreeBSD. If you do want to build it yourself so that
99 you get the added benefit of the latest checked in changes, please reference
100 ~\ref{sec:How_to_build}.
102 A Windows 10 version installation is described in~\ref{sec:ms_windows10}. There are also 32-bit i686 Ubuntu, Debian,
103 and Slackware versions available\protect\footnote{Remember that a 32-bit distro does not address more than 4GB of memory, so you may have stability and performance problems with large, high-resolution mediafiles.}. \textbf{These binaries are no longer being updated; they are stable and working but without future functionality}.
104 They are in subdirectories of:
107 \item \href{https://cinelerra-gg.org/download/tars}{https://cinelerra-gg.org/download/tars}
108 \item \href{https://cinelerra-gg.org/download/pkgs}{https://cinelerra-gg.org/download/pkgs}
111 The \textbf{tars} \index{tars} directory contains single-user static builds for
114 This is the recommended usage of \CGG{} because all of the files
115 will exist in a single directory. Generally all of the necessary
116 libraries are built into the static build, but in some cases you may
117 have to install another library that is being called for.
119 To install the single user builds, download the designated tarball
120 from the \texttt{./tars} subdirectory and unpack as indicated below:
122 \begin{lstlisting}[style=sh]
126 tar -xJf /src/path/cinelerra-5.1-*.txz # for the *, substitute your distro tarball name
129 \emph{Do not download the LEAP 10-bit version unless you specifically want to
130 use h265 rendering to 10-bit instead of the more standard 8-bit.} For more
131 information see ~\ref{sec:cinx_and_a_bit_of_confusion}.
133 The \textbf{pkgs} \index{pkgs} directory contains the standard packaged
134 application for various distros. This will install a dynamic
135 system version for users who prefer to have the binaries in the
136 system area and for multi-user systems.
138 In addition, performing the package install checks the md5sum in
139 the file \texttt{md5sum.txt} to ensure the channel correctly
140 transmits the package. There is a
141 \href{https://cinelerra-gg.org/download/README.pkgs}{README.pkgs}
142 file in the \texttt{download} directory with instructions so you
143 can \textit{cut and paste} and avoid typos; it is also shown
146 \lstset{inputpath=extra/}
149 basicstyle=\footnotesize,
150 caption={README.pkgs}
153 \section{How to Build \CGG{} from Developer's Git Repository}%
154 \label{sec:How_to_build}
158 These are generic build instructions for building \CGG{} Infinity.
159 Known to work on Ubuntu, Mint, OpenSuse, Fedora, Debian, Centos,
160 Arch, Slackware, and Gentoo. Compiling from git is perhaps the best way to get \CGG{} on 32-bit systems\protect\footnote{Remember that a 32-bit distro does not address more than 4GB of memory, so you may have stability and performance problems with large, high-resolution mediafiles.}. It has not been tested on every
161 single possible distro yet so you might expect to have to make
162 some minor changes. Also works on a somewhat limited basis on
163 FreeBSD and Windows 10 with the bsd.patch for FreeBSD and the
164 cygwin.patch for Windows 10. As of 10/31/2020, FreeBSD and Windows
165 10 builds and patches are no longer being maintained so that they
166 will work using the GIT version in use at that time but you will
167 have to create new patches for arising problems on later GITs.
169 NOTE: as of May 31, 2021 when Context Help was added, to include
170 this Context Help you will need to download the corresponding
171 tgz file containing the HTML manual sections referenced for the
172 Help pages. The file to download is:
173 \url{https://cinelerra-gg.org/download/images/HTML_Manual-20220131.tgz}
174 substituting for "20220131" the "yyyymmdd" representing latest release date.
175 Then unpack to your Cinelerra/bin/doc directory so it is included in
179 Alternatively, there are some pre-built dynamic or static binaries
180 which are updated on a fairly regular basis (as long as code changes
181 have been made) available at the link below.
183 \href{https://cinelerra-gg.org/download/}{https://cinelerra-gg.org/download/}
186 There are 2 kinds of builds, the default system-build and a
187 single-user build. A system build has results which are installed
188 to the system. The majority of the files are installed in the
189 standard system paths, but some customization is possible. The
190 single user build allows for running completely out of a local
191 user directory so it doesn't affect the system.
193 We recommend the single-user version when possible. It makes it
194 very easy to install a new version without having to delete the
195 older version in case you want it for backup -- once you are happy
196 with the new version, all you have to do is delete the entire old
197 directory path. Another reason for using single-user is that if
198 you install a new Operating System version and if you have \CGG{}
199 on separate disk space that is preserved, you won't have to
200 reinstall \CGG{}. It is also convenient for the purpose of having
201 the ability to interrupt or to see any possible error messages, if
202 you start the application from a terminal window command line
203 where you will have more control to catch problems. All that
204 said, the system builds can be useful in a university lab setting
205 where there are possibly multiple users, or multiple versions.
207 There are two notable differences between standard views
208 of \CGG{} and this implementation for the system builds. Both of
209 these can be configured during installation. The differences make
210 it possible to have several different versions installed without
211 having them interfere with each other.
214 \item application name can be set during a build but defaults
216 \item the home configuration directory can also be set and
217 traditionally defaults to: \texttt{\$HOME/.bcast5}
221 \subsection{The system build}
222 \label{sec:system-build}
225 To do a system build \index{build} , you should read the file
226 \texttt{README} that is at the top level after you get the source.
229 \item You need about 6.0 \,GB of disk storage to operate a build and
230 you need to have \textit{git} installed.
232 \item You do not need to be \textbf{root} (or \textit{sudo} ...) to install, except to run \texttt{bld\_prepare.sh} which calls in the distro's package manager. However if there are problems with permissions you can try to compile as root.
234 \item The \textit{git:} step has to download many files (approx
235 130\,MB) so allow time. When decompressed this will expand to
238 \item Run the following commands (this takes awhile):
240 \begin{lstlisting}[style=sh]
241 # This is where you need the 6.0GB of disk space:
243 git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
244 # Change to the cloned directory:
245 cd cinelerra5/cinelerra-5.1
247 NOTE: if your system has never had \CGG{} Infinity installed, you
248 will have to make sure you have all of the compilers and libraries
249 necessary. So on the very first build you should run:
251 \begin{lstlisting}[style=sh]
252 ./blds/bld_prepare.sh <os> # where <os> represents the
253 # Operating System of
254 # centos, fedora, suse, ubuntu, mint, debian, arch, debian-older, ubuntu-older.
256 ./configure --prefix=/usr # optional parameters can be added here
257 make 2>&1 | tee log # make and log the build
260 \texttt{bld\_prepare.sh} works for Arch and Gentoo with some additional information. For Arch linux, a README file containing many more dependencies is maintained. For Gentoo, a README file lists other dependencies that have to be installed manually.
262 \item \href{https://cinelerra-gg.org/download/README.arch}{https://cinelerra-gg.org/download/README.arch}
263 \item \href{https://cinelerra-gg.org/download/README.gentoo}{https://cinelerra-gg.org/download/README.gentoo}
266 \texttt{bld\_prepare.sh} option of debian-older and ubuntu-older is currently for older operating system versions since before about 06/2022.
268 \item Check for obvious build errors:
269 \begin{lstlisting}[style=sh]
270 grep "\*\*\*.*error" -ai log
272 If this reports errors and you need assistance or you think
273 improvements can be made to the builds, email the log which is
275 \href{mailto:cin@lists.cinelerra-gg.org}{cin@lists.cinelerra-gg.org}
276 \begin{lstlisting}[style=sh]
277 /<build_path>/cinelerra5/cinelerra-5.1/log
280 \item If there are no build errors, finally just run:
281 \begin{lstlisting}[style=sh]
284 Where <os> represents the Operating System supported by \CGG{}, such
285 as centos, fedora, suse, ubuntu, mint, or debian.
286 The ``with-single-user'' parameter makes it so.
287 % Make and log build (
288 Check for errors before proceeding.
291 \item If it all worked, you are all setup. Just click on the \CGG{}
296 \subsection{The single-user build}
297 \label{sec:single-user-build}
298 \index{single-user build}
301 To do a single-user build, read the file \texttt{README} that is at
302 the top level after you get the source.
305 \item You need at least 6\,GB of disk storage to operate a build +
306 you need to have “\texttt{git}” installed.
308 \item You can install it without being \textbf{root} or without using \textit{sudo}. In case of problems you can use \textit{sudo} to avoid permission issues.
309 \item The \textit{git} step has to download many files (approx
310 130\,MB) so allow time.
312 \item Run the following commands (this takes awhile):
313 \begin{lstlisting}[style=sh]
314 # This is where you need the 6GB of disk space
316 git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
317 # Toplevel directory:
318 cd cinelerra5/cinelerra-5.1
322 NOTE: if your system has never had \CGG{} Infinity installed, you
323 will have to make sure all the compilers and libraries necessary are
324 installed. Thus, for the execution part of \texttt{bld\_prepare.sh} you must use sudo, but the other steps can be done as a normal user.
326 % FIXME No novels in the listings.
327 \begin{lstlisting}[style=sh]
328 ./blds/bld_prepare.sh <os>
330 ./configure --with-single-user
334 Where <os> represents the Operating System supported by \CGG{}, such
335 as centos, fedora, suse, ubuntu, mint, debian and arch.
336 The ``with-single-user'' parameter makes it so.
337 % Make and log build (
338 Check for errors before proceeding.
341 Then just start the application by keying in: \texttt{./cin} in the
342 bin subdirectory OR add a desktop icon by using the appropriate
343 directory to copy the files to and edit to
344 correct the directory path. Below are generic directions of how to
347 Then just start the application by keying in: \texttt{./cin} in the
348 bin subdirectory OR add a desktop icon by using the appropriate
349 directory to copy the files to, run as root, and edit to correct the directory path. Below are generic directions of how to
352 \begin{lstlisting}[style=sh]
353 cd /cinelerra_directory_path
354 cp -a image/cin.{svg,xpm} /usr/share/pixmaps/
355 cp -a image/cin.desktop /usr/share/applications/cin.desktop
358 After you have followed the above, in the cin.desktop file, change
359 the \texttt{Exec=cin} line to be
360 \texttt{Exec=<your\_directory\_path>/bin/cin}.
362 A working example of how to build in Arch as a normal user:
364 \begin{lstlisting}[style=sh]
365 $ git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
366 $ cd /home/USER/cinelerra5/cinelerra-5.1
368 $ ./configure --with-single-user --with-booby
369 $ make 2>&1 | tee /tmp/cin5.log && make install
370 $ mv Makefile Makefile.cfg
371 $ cp Makefile.devel Makefile
374 \subsection{Notable Options and Caveats}%
375 \label{sub:notable_options_and_caveats}
378 These procedures and the \CGG{} Infinity software have all been run
379 as \textbf{root} on various home laptops and desktops. This provides
380 the best chance to ensure all works correctly and also allows for
381 handling errors, other problems and potential crashes with the most
382 success. Included in this section are some of the build variations
383 easily available for normal builds.
385 You can, during compilation, use a patch that changes the main non-standard shortcuts of \CGG{} to standard ones (\texttt{Ctrl+S} and \texttt{J, K, L}, etc.).
386 A table showing the changes from \CGG{} mode to standard mode can be found here: \nameref{sec:alternative_shortcuts}.
387 The instructions for the build with the patch are as follows. After downloading the sources from the git repository in the usual way, you apply the patch:
389 \begin{lstlisting}[style=sh]
391 patch -p1 -i alt_shortcuts.patch
395 To see the full list of features use:
397 \begin{lstlisting}[style=sh]
400 The default build \index{build} is a system build which uses:
402 \begin{lstlisting}[style=sh]
403 ./configure --without-single-user
406 In the single-user build \index{single-user build}, the target directory is always
407 \texttt{cin}. Because this is also the developer build, constant
408 names are used throughout. However, you can rename files after the
411 If your operating system has issues with the default install to
412 \texttt{/usr/local}, you might have to change the location to
413 \texttt{/usr} for a system build. Then you will have to use:
414 \begin{lstlisting}[style=sh]
415 ./configure --prefix=/usr
418 If you wish to change the default directory for a system build you
419 will have to add the destination directory path on the \texttt{make
420 install} line. For example:
421 \begin{lstlisting}[style=sh]
422 make install DESTDIR=<your selected target directory path>
425 The application name can be set during installation, but defaults to
426 \texttt{cin} so that the GG/Infinity build can coexist with other
427 \CGG{} builds if necessary. To override the default \texttt{cin}
429 \begin{lstlisting}[style=sh]
430 ./configure --with-exec-name=cinelerra
433 The home configuration directory can also be set, but default
434 location is traditionally \texttt{\$HOME/.bcast5}. For example:
436 \begin{lstlisting}[style=sh]
437 ./configure -with-config-dir=/myusername/.bcast5
440 NOTE: when you specify parameters to the configure program, it will
441 create a \texttt{make} file as a consequence. Since in a
442 \texttt{make} file, the \$ is a special character, it must be
443 escaped so in order to represent a \$ as part of an input parameter,
444 it has to be stuttered. That is, you will need \$\$ (2 dollar
445 signs) to represent a single dollar sign.
447 It may be necessary on some distros which have missing or incomplete
448 up-to-date libraries, to build \CGG{} without Ladspa. To do so,
451 \begin{lstlisting}[style=sh]
452 ./configure --prefix=/usr --without-ladspa-build
455 Note that the with-ladspa-dir is the ladspa search path, and
456 exists even if the ladspa build is not selected. This gives you
457 the ability to specify an alternate ladspa system path by
458 utilizing the \texttt{LADSPA\_PATH} environment variable (that is,
459 the default ladspa build is deselected).
461 Note for 32-bit 14.2 Slackware, Debian, Gentoo, Arch, FreeBSD,
462 before running the configure, you will need to set up the following:
464 \begin{lstlisting}[style=sh]
465 export ac_cv_header_xmmintrin_h=no
466 export FFMPEG_EXTRA_CFG=" --disable-vdpau"
469 Note for building 32-bit packages on hybrid 32/64 x86 systems, you may
470 need to add the following:
472 \begin{lstlisting}[style=sh]
473 setarch i686 (befire configure and package build)
476 NOTE: as of May 31, 2021 when Context Help was added, to include
477 this Context Help you will need to download the corresponding
478 tgz file containing the HTML manual sections referenced for the
479 Help pages. The file to download is:
480 \url{https://cinelerra-gg.org/download/images/HTML_Manual-20220131.tgz}
481 substituting for "20220131" the "yyyymmdd" representing latest release date.
482 Then unpack to your Cinelerra/bin/doc directory so it is included in
483 your built system. The reason for not including the HTML manual in
484 the source code so that it would already be there, is because it is
485 very large and has its own GIT base.
487 \subsection{Notes about Building from Git in your Customized Environment}%
488 \label{sub:notes_about_building_from_git_in_your_customized_environment}
493 Getting a build to work in a custom environment is not easy. If you
494 have already installed libraries which are normally in the
495 thirdparty build, getting them to be recognized means you have to
496 install the \textit{devel} version so the header files which match
497 the library interfaces exist. If you want to build using only the
498 thirdparty libraries installed in your system, just include
499 "--without-thirdparty" to your configure script. For example:
500 \begin{lstlisting}[style=sh]
501 ./confgure --with-single-user --disable-static-build --without-thirdparty
503 Below is the list of thirdparty
504 builds, but this list may have changed over time.
505 % It's list of Table?
509 \begin{longtable}{m{8em} c}
510 \caption{List of thirdparty builds}
511 \label{tab:List_of_thirdparty_builds}\\
554 The \textit{yes} means force build and \textit{auto} means probe and
555 use the system version if the build operation is not static. To get
556 your customized build to work, you need to change the probe options
557 for the conflicting libraries from \textit{yes} to \textit{auto}, or
558 even rework the \texttt{configure.ac} script. There may be several
559 libraries which need special treatment.
561 An example of a problem you might encounter with your customized
562 installation is with \texttt{a52dec} which has probes line
563 \texttt{(CHECK\_LIB/CHECK\_HEADERS)} in \texttt{configure.ac}, but
564 \texttt{djbfft} does not. In this case, \texttt{djbfft} is only
565 built because \texttt{a52dec} is built, so if your system has
566 \texttt{a52dec}, set \texttt{a52dec} to auto and see if that
567 problem is solved by retrying the build with:
568 \begin{lstlisting}[style=sh]
569 ./confgure --with-single-user -enable-a52dec=auto .
572 With persistence, you can get results, but it may take several tries
573 to stabilize the build. If you need help, email the \texttt{log}
574 and \texttt{config.log}, which is usually sufficient to determine
577 If you have already installed the \texttt{libfdk\_aac} development
578 package on your computer because you prefer this version over the
579 default aac, you will have to do the following to get this
580 alternative operational. The libfdk\_aac library is not a part of
581 \CGG{} by default because it is not license free.
583 \begin{lstlisting}[style=sh]
584 export FFMPEG_EXTRA_CFG=" --enable-libfdk-aac --enable-nonfree"
585 export EXTRA_LIBS=" -lfdk-aac"
586 for f in `grep -lw aac cinelerra-5.1/ffmpeg/audio/*`; do
587 sed -e 's/\<aac\>/libfdk_aac/' -i $f
592 \subsection{Cloning the Repository for Faster Updates}%
593 \label{sub:cloning_the_repository_for_faster_updates}
597 If you want to avoid downloading the software every time an update
598 is available you need to create a local ``repository'' or repo. The
599 repo is a directory where you first do a \texttt{git clone}. For
600 the initial git clone, set up a local area for the repository
601 storage, referred to as \texttt{<repo\_path>}. The \texttt{git
602 clone} creates a repo named \texttt{cin5} in the
603 \texttt{/<repo\_path>/} directory. This accesses about 530\,MB of
604 repo data, so the device has to have at least that available. The
605 repo path is always a perfect clone of the main repo.
608 \paragraph{Setting up the initial clone}%
609 \label{par:setting_up_the_initial_clone}
611 You may want to add ``\verb|--depth 1|'' before \texttt{cin5}
612 because this will clone faster and is smaller, but has no history.
614 \begin{lstlisting}[style=sh]
616 git clone "git://git.cinelerra-gg.org/goodguy/cinelerra" cin5
618 Cloning into "cin5"...
619 remote: Counting objects: 20032, done.
620 remote: Compressing objects: 100% (11647/11647), done.
621 remote: Total 20032 (delta 11333), reused 16632 (delta 8189)
622 Receiving objects: 100% (20032/20032), 395.29 MiB | 3.26 MiB/s, done.
623 Resolving deltas: 100% (11333/11333), done.
624 Checking connectivity... done.
628 \paragraph{Update an existing repo}%
629 \label{par:update_an_existing_repo}
630 The below shows how you can get updates.
632 \begin{lstlisting}[style=sh]
638 \paragraph{Useful git commands}%
639 \label{par:useful_git_commands}
640 Some other commands that are useful.
642 \begin{lstlisting}[style=sh]
643 git clone "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cin5
644 git pull # pull remote changes to the local version
645 git status # shows changed files
646 git clean -i # interactive clean, use answer 1 to "clean"
650 \subsection{How to Build from a Previous GIT Version}%
651 \label{sub:how_to_build_from_a_previous_git_version}
656 If you have a problem with the current GIT version, you can revert
657 to a previous working version easily. The commands to use will be
658 similar to these next lines which are then explained in more detail.
659 You need "history" to do this, so should not have used the "depth 1"
660 parameter on your GIT.
663 \begin{lstlisting}[style=sh]
664 cd /<path>/cin5 # substitute your repo path name for cin5
665 git log # shows a list of versions depending on history depth specification
666 git checkout <version> # choose a version number as listed
669 The \texttt{git log} command produces a log file with hash values
670 for commit keys to the level specifed if the the depth paramter
672 The hash ids are the commit names to use when you
673 use git checkout. Next is displayed sample output:
675 \begin{lstlisting}[style=nil]
676 delete stray line in last checkin
678 commit 4a90ef3ae46465c0634f81916b79e279e4bd9961
679 Author: Good Guy <good1.2guy@gmail.com>
680 Date: Thu Feb 22 14:56:45 2018 -0700
682 nested clips, big rework and cleanup, sams new icons,
685 commit f87479bd556ea7db4afdd02297fc00977412b873
686 Author: Good Guy <good1.2guy@gmail.com>
687 Date: Sat Feb 17 18:09:22 2018 -0700
690 For the \texttt{git checkout <version>}, you would then keyin the
691 line below for the following results:
693 \begin{lstlisting}[style=nil]
694 git checkout f87479bd556ea7db4afdd02297fc00977412b873
696 Note: checking out 'f87479bd556ea7db4afdd02297fc00977412b873'.
698 You are in 'detached HEAD' state. You can look around, make
699 experimental changes and commit them, and you can discard any
700 commits you make in this state without impacting any branches by
701 performing another checkout.
703 If you want to create a new branch to retain commits you create,
704 you may do so (now or later) by using -b with the checkout command
707 git checkout -b <new-branch-name>
709 HEAD is now at f87479bd... more file size icon updates,
710 and more to followend
713 Later to get the repo back to current, use:
714 \begin{lstlisting}[style=sh]
719 \subsection{Debuggable Single User Build}%
720 \label{sub:debuggable_single_user_build}
721 \index{single-user build}
724 To build from source with full debugging symbols, first build a full
725 static (non\_debug) build as follows but instead of using
726 \texttt{/tmp} substitute your permanent disk path if you want to
729 \begin{lstlisting}[style=sh]
731 git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
732 cp -a /<repo_path>/cinelerra-5.1 /tmp/
733 cd /tmp/cinelerra-5.1
737 Then, to run as a developer in the debugger:
739 \begin{lstlisting}[style=sh]
740 CFLAGS="-O2 -ggdb" make -j8 rebuild_all
745 When you get the gdb prompt, type the letter "r", for run, and the windows will come up.
746 If there is a crash, the windows will freeze and typing "bt" for backtrace in the startup window
747 after the gdb prompt, provides useful information.
750 \subsection{Unbundled Builds}%
751 \label{sub:unbundled_builds}
756 There are some generic build scripts included in the \CGG{} GIT
757 repository for users who want to do unbundled builds with ffmpeg
758 already available on their system. This has been tested on Arch,
759 Ubuntu 18, FreeBSD, Windows10 and Leap 15 (rpm) at the time this
762 The names of the build scripts are: \texttt{arch.bld},
763 \texttt{bsd.bld}, \texttt{deb.bld}, \texttt{rpm.bld}, and
764 \texttt{cygwin.bld}. These scripts are in the \texttt{blds}
765 subdirectory. The \texttt{bsd.bld} should be used with the
766 \texttt{bsd.patch} file in that same directory. The
767 \texttt{cygwin.bld} should be used with the \texttt{cygwin.patch}
768 file in that same directory.
770 The reason that Cin Infinity traditionally uses its own thirdparty builds
771 (bundled builds) is because there are a lot of different distros
772 with varying levels of ffmpeg and other needed thirdparty
773 libraries. However, some users prefer using their current system
774 baseline without another/different copy of ffmpeg.
776 With different levels of the user’s libraries, uncertainty,
777 potential instability, and unknown issues may come up while
778 running \CGG{} and this will make it, for all practical purposes,
779 impossible to diagnose and debug problems or crashes.
781 There may be no help in these cases. You are encouraged to report
782 any errors which potentially originate from Cin Infinity, but if
783 the data indicates alternate library sources, please report the
784 problems to the appropriate maintainers.
786 With the unbundled builds, some features may not be available and
787 no attempt to comment them out has been made. So if you use a
788 pulldown, or pick a render option, or choose something that is not
789 available, it just will not work. For example, unless special
790 options were set up by you, the LV2 audio plugins will not be
791 available. Nor will the codec libzmpeg, the file codec ac3, or
792 DVD creation. The old school file classes will all work, but some
793 of the formats that come with ffmpeg may not because of the way
794 that ffmpeg was installed on your operating system. That is
795 because the \CGG{} included ffmpeg is a known static build and is
796 usually the latest stable/released version. For example, in the
797 current case of Leap 15, libx264 and libx265 are not built in and
798 this can be debilitating; you can always run \texttt{ffmpeg
799 -formats} and \texttt{ffmpeg -codecs} to see what is available
802 \section{Building the HTML Manual for Context Help}%
803 \label{sec:building_the_manual}
806 In addition to compiling your own \CGG{}, you should also build an html version of the manual that is needed for Context Help in the program. The main version of the manual is in latex to produce a pdf version of the manual and this is required to be built first as the basis for the html version. This means that you need a full latex environment, git, and the latex2html program in order to eventually create the html version. Texlive is about 1 GB; Latex2html itself has many requirements and missing any will result in failure: some requirments include Netpbm, GhostScript, dvips, etc. Latex2html must be at least version \textit{2021.2} in order to create the html manual version from the latex.
808 The steps are as follows:
810 \item Download the manual in LaTeX:
812 \begin{lstlisting}[style=sh]
813 git clone "git://git.cinelerra-gg.org/goodguy/cin-manual-latex.git" master
816 \item Included in the download is the \texttt{translate\_manual} script. After modifying this file to have execute permission, run this script from a terminal window in the \textit{master} directory where it was downloaded (be aware that this script includes several \textit{rm} commands):
817 \begin{lstlisting}[style=sh]
821 The steps that this script performs are as follows:
823 \item PDF production. The PDF document will be produced from the latex source in the \textit{master} directory. Since the glossary and index are also present, it has to run the pdf build several times. The following commands in the \texttt{translate\_manual} script produce the PDF document from latex source which includes invoking makeindex for the Index and Glossary.
825 \begin{lstlisting}[style=sh]
826 pdflatex CinelerraGG_Manual.tex
827 makeindex CinelerraGG_Manual.idx
828 pdflatex CinelerraGG_Manual.tex
829 makeindex CinelerraGG_Manual.nlo -s nomencl.ist -o CinelerraGG_Manual.nls
830 pdflatex CinelerraGG_Manual.tex
833 After these commands are executed you will have the manual only in PDF format. So if you only want a PDF version, you only need to run these previous 5 lines but Context Help from the program will not be available with the PDF version.
834 \item Next, to produce HTML output the script then moves (renames) \texttt{latex 2html-init} to \texttt{.latex2html-init} (starting with dot).
836 \item Then the script uses latex2html: latex2html is run with a unique set of parameters and some cleanup is performed. It creates the directory CinelerraGG\_Manual containing all the files of the manual in html: tables, references, index, glossary, and various images.
839 \item After installation of the \CGG{} program, place the complete unchanged directory \texttt{CinelerraGG\_Manual}, as it was produced by latex2html from the manual package, into the \textit{doc} directory of the installed Cinelerra package. This will be the directory \textit{bin/doc/CinelerraGG\_Manual} if \CGG{} was built \texttt{--with-single-user}. The script ContextManual.pl will automatically be in bin/doc after the successful build of the program. It is this perl script that allows the program to access CinelerraGG\_Manual to offer Context Help.
841 \item Optionally you can make some adjustments to the latex2html command line in the \texttt{translate\_manual} script. Some variants are shown in the comments inside the script but changes may impact the usability of Alt/h hotkey from the program.
844 \section{Windows 10 with Cygwin for \CGG{} Limited}%
845 \label{sec:ms_windows10}
848 As of 10/31/2020, this is no longer being maintained. It should
849 still work using an older GIT version with Windows 10 but it is
850 possible with some effort to modify the patch file to work with the
853 To run \CGG{} on a Windows 10 computer, you will need to have
854 Cygwin installed on your system, along with the \CGG{} static tar
855 and a patched library: libxcb. This setup has been tested with
856 Windows 10, version 1909, on an HP EliteBook 820 at 2.3 GHz.
858 This limited version provides \textit{core} functionality at this
859 time with the standard Windows FFmpeg executable, meaning that
860 specific modifications in FFmpeg needed for \CGG{} are not
861 available. Limited capabilities include only a few render output
862 formats available - for example \textit{mov}, \textit{qt} as
863 \textit{mjpeg}, and \textit{mpeg} for videos and \textit{avi} and
864 \textit{qt} as \textit{s16le} for audio, but not \textit{mkv} or
865 \textit{mp4}. This is due to the fact that several codec and
866 utility libraries are not currently compiled to work with Windows.
868 \subsection*{Installing Cygwin}
869 \label{sec:installing_cygwin}
872 Cygwin is an environment that runs natively on Windows which
873 allows Unix programs to be compiled and run on Windows. With
874 cygwin installed on your Windows 10 computer, you will be able to
875 run \CGG{}. Before installing cygwin, you need to be warned that
876 the Avast anti-virus software kills files necessary for cygwin
877 installation and execution, so you will have to remove it and use
878 alternative anti-virus software (the standard default already
879 included with Windows 10 is Defender). Below are the steps for
883 \item Download cygwin for your 64-bit computer at:
884 \href{https://www.cygwin.com/}{https://www.cygwin.com/}
886 \item Generally just take the defaults as they show up, but the
887 next steps show what comes up.
889 \item When a warning window pops up, click \textit{Yes}.
891 \item Click \textit{Next}.
893 \item Choose \textit{Install from Internet} option and then click
896 \item Choose your desired directory by clicking on Browse
897 button. Choose \textit{All Users (Recommended)} and then click
900 \item Choose the local package directory where you would like your
901 installation files to be placed. Click \textit{Next}.
903 \item Choose \textit{Direct Connection} if you are using Internet
904 with plug and play device. Click \textit{Next}.
906 \item Choose any download site preferably
907 ``cygwin.mirror.constant.com'' and then click \textit{Next}.
909 \item For list of things to install, leave all set to
910 \textit{Default} except these to \textit{Install} instead:
919 This install takes a long time; approximately 2 hours on an
920 EliteBook and requires approximately 20GB storage.
922 \item Finally you will want to have the icons on your desktop
923 (already default) and then click \textit{Finish}.
926 Then to install the \CGG{} tar files, you will need to start a
927 cygwin console terminal from the startup menu as shown here:
928 \texttt{Start $\rightarrow$ Cygwin $\rightarrow$ Cygwin64}
931 \subsection*{Installing \CGG{}}
932 \label{sec:installing_cinelerra}
935 \item Download the tar file
936 \href{https://cinelerra-gg.org/download/testing/libxcb-bld.tar.bz2}{libxcb-bld.tar.bz2}.
938 \item Install libxcb from the tar file -- installs into
939 \texttt{/usr/local} and requires approximately 21MB storage.
940 \begin{lstlisting}[style=sh]
941 tar -C /usr/local -xJf /path/libxcb-bld.tar.bz2
943 The libxcb patch repairs an error (XIOError), which stops
946 \item Download the tar file
947 \href{https://cinelerra-gg.org/download/testing/cygcin-bld.tar.bz2}{cygcin-bld.tar.bz2}.
949 \item Install cygcin from the tar file - this installs into home
950 directory. Note this is cygcin \emph{not} cygwin. You must change the
951 \texttt{path} below to the name of the path where you downloaded
953 \begin{lstlisting}[style=sh]
955 tar -xJf /path/cygcin-bld.tar.bz2
959 This creates \texttt{\~{}/cygcin}, a user build installation of
960 \CGG{} and requires approximately 400MB storage.
962 \paragraph{Running \CGG{}:}
963 You will need to start a cygwin desktop from the startup menu:
965 \item \texttt{Start$\rightarrow$ Cygwin-X $\rightarrow$ Openbox}
967 You should start a console controlling terminal so that you can
970 \item \texttt{Start$\rightarrow$ Cygwin $\rightarrow$ Cygwin64} Terminal
972 This opens a separate window that can survive a cygwin hang and
973 bugs. Without these logs, it is much more difficult to use.
975 \item Type into that console controlling window, the following:
976 \begin{lstlisting}[style=sh]
980 \item Change directories to where \CGG{} is installed:
981 \begin{lstlisting}[style=sh]
982 cd /path/cygcin (NOT cygwin)
986 \begin{lstlisting}[style=sh]
989 which starts up your 4 \CGG{} windows.
992 The most noticeable difference from the Linux versions is that
993 \CGG{} seems to run very slowly on Windows 10. You must be very
994 tolerant and patient to see this work. It can however exhibit
995 astonishing speed when encoding. \CGG{} has to be downgraded
996 significantly due to lack of supported interfaces, codecs (for
997 example h264/h265), and utilities. The only graphics driver is
998 X11 and the only sound driver is pulseaudio. Almost all
999 configurable omissions are applied to this build.
1001 \paragraph{\CGG{} build on cygwin from source code:}
1004 \item Download and install ffmpeg into /usr/local :
1006 download ffmpeg (currently 4.2.2)
1007 \begin{lstlisting}[style=sh]
1009 tar -xJf /path/ffmpeg-4.2.2.tar.bz2
1016 \item Download and install a patched libxcb:
1017 \begin{lstlisting}[style=sh]
1020 tar -xf /path/libxcb-1.13.tar.bz2
1022 patch -p1 < /path/cinelerra-5.1/thirdparty/src/libxcb.patch1
1023 patching file configure.ac
1024 patching file src/xcb_in.c
1030 \item Download cinelerra-gg:
1031 \begin{lstlisting}[style=sh]
1033 git clone "git://git.cinelerra-gg.org/goodguy/cinelerra.git"
1034 cd cinelerra-gg/cinelerra-5.1
1036 \item Apply cygwin patch:
1037 \begin{lstlisting}[style=sh]
1038 patch -p2 < blds/cygwin.patch
1040 \item Run the build with:
1041 \begin{lstlisting}[style=sh]
1046 This produces a directory: /build\_path/cinelerra-gg/cinelerra-5.1/bin
1047 which is used to create the cygcin archive.
1049 Currently, the targets are not stripped and can be run from gdb.
1050 There is only very limited signal handler dmp file support.
1051 Running gdb from inside a desktop resident console (not a cygwin64
1052 window) will hang cygwin (and cin) when it hits a breakpoint. You
1053 must run from an external console window to avoid this issue.
1055 \section{Android Tablet or Phone with TERMUX}%
1056 \label{sec:android_termux}
1059 \CGG{} can be run on Android (without audio), a non-x86 mostly posix system,
1060 tablet or phone after installing TERMUX, the \textit{terminal emulator}.
1061 You will have to do your own build using the file in Cinelerra's
1062 \texttt{blds} subdirectory, \texttt{termux.bld}.
1063 Because this is a relatively new capability and of lesser use, some
1064 additional effort may have to be exerted on your part to get it going
1065 but it is easy to get help by contacting the mailing list.
1066 In addition, there is currently no known procedure for hearing audio.
1068 \begin{figure}[htpb]
1070 \includegraphics[width=1.0\linewidth]{android.png}
1071 \caption{Screencast of an Android tablet running \CGG{} using TERMUX.}
1075 Some requirements include;
1077 \item Termux runs with X on Android 7+.
1078 \item Install takes 5 GB of internal storage. In addition you can download videos,
1079 and other files with wget to one specific location at sdcard after running termux-setup-storage
1080 inside termux (it will prompt you to give access to sdcard graphically the first time used).
1081 \item If you have empty versions of \texttt{locale.alias}, \texttt{locale.dir},
1083 \newline \texttt{\$PREFIX/share/X11/locale/en\_US.UTF-8/XLC\_LOCALE}
1084 \newline you will have to request non-empty versions via the mailing list.
1085 \item Some helpful information on installing the X environment is at:
1086 \url{https://wiki.termux.com/wiki/Graphical\_Environment}
1087 \item To prevent crashing when loading a video file that has audio, use the guide
1088 \url{https://www.reddit.com/r/termux/comments/bpa8jz/pulseaudio\_streaming\_client/}
1089 which explains vnc/pulseaudio setup.
1092 A little more about Audio is presented next because you will need to have this running
1093 in order to prevent a crash (even though you still will not be able to hear audio) -- there does not seem to be a simple PA client in termux itself.
1094 Some information is available at:
1095 \url{https://android.stackexchange.com/questions/205576/how-to-play-sound-from-termux-when-using-linux} .
1097 The next few lines show a successful setup/usage.
1098 \begin{lstlisting}[style=sh]
1099 $ pulseaudio --start
1101 PID TTY STAT TIME MAJFL TRS DRS RSS %MEM COMMAND
1102 7003 pts/28 S<s 0:00 637 532 9039 1716 0.0 /data/data/com
1103 13684 ? S<l 0:00 0 49 123898 16616 0.8 pulseaudio --
1104 13692 pts/28 R<+ 0:00 0 63 7500 1420 0.0 ps axv
1106 \begin{lstlisting}[style=sh]
1107 $ pactl load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1 auth-anonymous=116
1108 $ PULSE_SERVER=127.0.0.1 pactl info
1109 Server String: 127.0.0.1
1110 Library Protocol Version: 34
1111 Server Protocol Version: 34
1116 Host Name: localhost
1117 Server Name: pulseaudio
1118 Server Version: 14.2
1119 Default Sample Specification: s16le 2ch 44100Hz
1120 Default Channel Map: front-left,front-right
1121 Default Sink: OpenSL_ES_sink
1122 Default Source: OpenSL_ES_sink.monitor
1126 Now to start up \CGG{}, type in:
1127 \begin{lstlisting}[style=sh]
1128 $ cd (your cinelerra directory)/cinelerra/cinelerra-5.1/
1129 $ PULSE_SERVER=127.0.0.1 ./cin.sh
1132 You can even build a package version similiar to Debian, just with "\texttt{pkg search} pkg\_name / \texttt{pkg install}
1133 pkg\_name" instead of "\texttt{apt search/install} pkg\_name" and with "\texttt{*-static}" instead of "\texttt{*-dev/-devel} packages".
1134 For more information on this, see:
1136 \url{https://wiki.termux.com/wiki/Package\_Management}
1137 \newline \url{https://wiki.termux.com/wiki/Building\_packages}
1139 \section{Pre-built Packages and Distros with \CGG{} Included}%
1140 \label{sec:distro_with_cinelerra_included}
1141 \index{linux distro}
1143 There are also some special complete distribution systems
1144 available that include \CGG{} for audio and video production
1145 capabilities as well as some pre-built packages in a build farm.
1147 \subsection{Build Farm pre-built Deb and RPM packages}
1148 \label{sec:packages}
1149 A build farm for \CGG{} deb and rpm packages that is in development is at this location \url{https://github.com/einhander/cin-gg-packages/releases}.
1150 It can build packages on every git change in the main repo with
1151 releases corresponding to a build date, not a git commit date.
1152 Current build hosts are \textbf{debian 12} and \textbf{alma linux 8}.
1154 \subsection{AV Linux}
1155 \label{sec:AV_Linux}
1157 \textbf{AV Linux} is a downloadable/installable shared snapshot
1158 ISO image based on MX Linux. It provides the user an easy method to
1159 get an Audio and Video production workstation without the hassle
1160 of trying to find and install all of the usual components
1161 themselves. Of course, it includes \CGG{}!
1164 \href{http://www.bandshed.net/avlinux/}{homepage of AV Linux}.
1166 \subsection{Bodhi Linux Media}
1167 \label{sec:Bodhi_Linux}
1169 \textbf{Bodhi Linux Media} is a free and open source distribution that
1170 comes with a curated list of open source software for digital
1171 artists who work with audio, video, includes \CGG{}, games,
1172 graphics, animations, physical computing, etc.
1175 \href{https://gitlab.com/giuseppetorre/bodhilinuxmedia}{homepage of Bodhi Linux}.
1177 \subsection{DeLinuxCo}
1178 \label{sec:delinuxco}
1180 \textbf{DeLinuxCo} is a distro derived from Manjaro (so Arch based) with DE Cinammon. It is a professional workstation, mainly oriented to the multimedia field but not only. It contains many specialized programs already configured, including \CGG{}.
1182 You can read all about DeLinuxCo \href{https://www.delinuxco.com/}{here} and download \href{https://www.delinuxco.com/download/}{here}.
1187 \textbf{Elive}, or Enlightenment live CD, is a non-commercial, cost-free operating system based on Debian, and it can be used either as a live CD or an Installed system. Elive uses a customized Enlightenment desktop. It is fast, user-friendly and feature-rich and \CGG{} is included in the both the 64 bit and 32 bit versions.
1189 Click \href{https://www.elivecd.org/}{Elive} for more information. The \CGG{} packages for the program
1190 and the manual are in the direcotry at
1191 \href{https://repo.bookworm.elive.elivecd.org/pool/multimedia/c/} {Bookworm version 12} and
1192 \href{https://repo.bullseye.elive.elivecd.org/pool/multimedia/c/} {Bullseye version 11} and
1193 \href{http://repo.buster.elive.elivecd.org/pool/multimedia/c/}{Buster version 10} - just download
1194 the .deb files inside that directory and install via “dpkg -i “.
1196 \section{Cinx and a “Bit” of Confusion}%
1197 \label{sec:cinx_and_a_bit_of_confusion}
1200 Cinx is the exact same program as Cin. The X (x) represents the
1201 roman numeral 10 for 10-bit as opposed to 8-bit standard. The
1202 third-party library used for x265 must be specially compiled with
1203 \texttt{--bit-depth=10} in order to produce 10-bit rendered
1204 output. A cinx version can be built for most other distros if
1205 rendering at 10-bit is desirable instead of 8-bit.
1207 This build will not be able to output 8-bit depth which means you
1208 have to retain the Cin version also.
1210 Whatever build ffmpeg is linked to will determine what bit depth
1211 it can output. This is why there have to be separate builds. If
1212 you install both packages, Cin and CinX, you may get \textit{file
1213 conflicts of same file name} --- just continue.
1215 Keep in mind that the regular 8-bit version works on 8-bit bytes
1216 --- the standard word size for computers, but the 10-bit version
1217 has to use 2 words to contain all 10 bits so you can expect
1218 rendering to be as much as twice as slow.
1220 There is also a 12-bit version for consideration but currently the
1221 results are simply the same as 10-bit with padding to make 12-bit
1222 so it is of no value.
1224 \section{Multibit build for x265-8/10/12-bit}%
1225 \label{sec:multibit_build}
1228 To build a version that can handle 8 bit, or 10 bit, or 12 bit videos, a patch is provided in the \texttt{thirdparty} subdirectory that needs to be applied to do so. Be aware that the compile may take more time and seems to be about twice as long. To apply the required patch:
1230 \begin{lstlisting}[style=sh]
1231 cd /path/to/cinelerra-5.1/thirdparty
1232 patch < compile_multibit_X265.txt
1233 mv x265_3.5.patch* src/.
1235 Render formats \textit{h265-10bit} and \textit{h265-12bit} have been provided and will
1236 be operational after the applied patch is compiled in.
1238 %%% Local Variables:
1240 %%% TeX-master: "../CinelerraGG_Manual"