From: Good Guy Date: Sun, 2 Feb 2020 18:56:04 +0000 (-0700) Subject: final revision for uniformity by Andrea X-Git-Tag: 2021-05~130 X-Git-Url: https://cinelerra-gg.org/git/?a=commitdiff_plain;h=a4e4d7cf91d52ed3c02b80bec3596520c23402d9;p=goodguy%2Fcin-manual-latex.git final revision for uniformity by Andrea --- diff --git a/parts/AuxilaryPrograms.tex b/parts/AuxilaryPrograms.tex index 9989769..9059fda 100644 --- a/parts/AuxilaryPrograms.tex +++ b/parts/AuxilaryPrograms.tex @@ -1,22 +1,20 @@ \chapter{Auxiliary Programs}% -\label{cha:Auxiliary_Programs} +\label{cha:auxiliary_programs} + \section{Using Ydiff to check results} -\label{sec:Ydiff to check results} +\label{sec:ydiff_check_results} -Delivered with Infinity Cinelerra and in the Cinelerra path, there is a file \ {}``ydiff.C''. \ This program compares the output from 2 files to see the differences . \ Do: cd cin\_path and key in ``make ydiff''. -\medskip +Delivered with Infinity Cinelerra and in the Cinelerra path, there is a file \texttt{ydiff.C} This program compares the output from 2 files to see the differences . Do: \texttt{cd cin\_path} and key in \texttt{make ydiff}. You can now use this to check the quality differences of various outputs. \ For example, in this same directory key in: -\hspace{2em}./ydiff /tmp/yourfile.mp4 /tmp/yourfile.mp4 -\medskip + +\hspace{2em}\texttt{./ydiff /tmp/yourfile.mp4 /tmp/yourfile.mp4} Since you are comparing a file to itself, you will see a clean looking white window in the left-hand corner and columns 2,3,4 will be all zeros. \ Run this same command with a 3rd spacing parameter of {}-1 as shown below, and you will see artifacts of comparing 2 files starting in a different position. -\medskip -\hspace{2em}./ydiff /tmp/yourfile.mp4 /tmp/yourfile.mp4 -1 -\medskip +\hspace{2em}\texttt{./ydiff /tmp/yourfile.mp4 /tmp/yourfile.mp4 -1} -Now render yourfile using different quality levels and run ydiff to compare the 2 results. \ You will see only noise difference which accounts for the quality level. \ Columns 2,3,4 might no longer be exactly zero but will represent only noise differences. \ The ydiff output is debug data with lines that show frame size in bytes, sum of error, and sum of absolute value of error. \ The frames size is sort of useless, the sum of error shows frame gray point drift and the abs error is the total linear color error between the images. \ At the very end is the total gray point drift and total absolute error on the last line. +Now render yourfile using different quality levels and run ydiff to compare the 2 results. You will see only noise difference which accounts for the quality level. Columns 2,3,4 might no longer be exactly zero but will represent only noise differences. The ydiff output is debug data with lines that show frame size in bytes, sum of error, and sum of absolute value of error. The frames size is sort of useless, the sum of error shows frame gray point drift and the abs error is the total linear color error between the images. At the very end is the total gray point drift and total absolute error on the last line. { % uses braces to localize caption alignment changes. \begin{figure} @@ -27,15 +25,14 @@ Now render yourfile using different quality levels and run ydiff to compare the \hspace{0.4\linewidth} \captionsetup{justification=raggedleft,singlelinecheck=false} \includegraphics[width=0.4\linewidth]{ydiff_change.png} - \caption{{\textquotedbl}giraffe{\textquotedbl} artifacts on 2 files spaced differently} + \caption{"giraffe" artifacts on 2 files spaced differently} \end{figure} } -\clearpage \section{Image Sequence Creation} -\label{sec:Image Sequence Creation} +\label{sec:image_sequence_creation} + Example script to create a jpeglist sequence file is next: -\medskip \begin{lstlisting}[numbers=none] #!/bin/bash @@ -61,117 +58,92 @@ echo "$f" shift done \end{lstlisting} -\medskip Example usage of this script follows: -\medskip -\ \ \ \ \ jpeglist.sh outfile infiles*.jpg -\medskip +\qquad \texttt{jpeglist.sh outfile infiles*.jpg} \section{Webm / Vp9 Usage and Example File\protect\footnote{credit Frederic Roenitz}} -\label{sec:Webm / Vp9 Usage and Example File} +\label{sec:webm/vp9_usage_example} -There are some common VP9 rendering options files that support creation of video for YouTube, Dailymotion, and other online video services. \ Webm / VP9 \ is a media file format which is free to use under the BSD license and is open-source; thus there are no licensing issues to be concerned about. \ The Webm container is based on Matroska for video and Opus for audio. -\medskip +There are some common VP9 rendering options files that support creation of video for YouTube, Dailymotion, and other online video services. Webm / VP9 is a media file format which is free to use under the BSD license and is open-source; thus there are no licensing issues to be concerned about. The Webm container is based on Matroska for video and Opus for audio. -Youtube easy startup steps are documented in the Appendix (\ref{sec:youtube_with_cinelerra}). \ These same steps have been verified to work for creating Dailymotion videos -- however, the created files must be renamed before uploading to change the youtube extension to webm instead for Dailymotion. - -{}- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\medskip +Youtube easy startup steps are documented in the Appendix (\ref{sec:youtube_with_cinelerra}). These same steps have been verified to work for creating Dailymotion videos -- however, the created files must be renamed before uploading to change the youtube extension to webm instead for Dailymotion. Below is one of the VP9 rendering options file with documentation for specifics: -\medskip - -webm libvpx-vp9 -\medskip - -\# 20171114-2203 -\# from https://developers.google.com/media/vp9/settings/vod/ -\# 1280x720 (24, 25 or 30 frames per second) -\# -\# -\# Bitrate (bit rate) -\# - -\# VP9 supports several different bitrate modes: -\# mode -\# Constant Quantizer (Q) \ \ Allows you to specify a fixed quantizer value; bitrate will vary -\# Constrained Quality (CQ) Allows you to set a maximum quality level. Quality may vary within bitrate parameters -\# Variable Bitrate (VBR) \ \ Balances quality and bitrate over time within constraints on bitrate -\# Constant Bitrate (CBR) \ \ Attempts to keep the bitrate fairly constant while quality varies - -\# -\# CQ mode is recommended for file-based video (as opposed to live -\# streaming). The following FFMpeg command-line parameters are used -\# for CQ mode: -\# -\# FFMpeg -\# -b:v {\textless}arg{\textgreater} \ \ \ \ \ Sets target bitrate (e.g. 500k) -\# -minrate {\textless}arg{\textgreater} Sets minimum bitrate. -\# -maxrate {\textless}arg{\textgreater} Sets maximum bitrate. -\# -crf {\textless}arg{\textgreater} Sets maximum quality level. Valid values are 0-63, lower numbers are higher quality. -\# -\# Note: Bitrate is specified in kbps, or kilobits per second. In video -\# compression a kilobit is generally assumed to be 1000 bits (not -\# 1024). -\# -\# Note: Other codecs in FFMpeg accept the -crf parameter but may -\# interpret the value differently. If you are using -crf with other -\# codecs you will likely use different values for VP9. - -bitrate=1024k - -minrate=512k - -maxrate=1485k - -crf=32 -\medskip - -\# Tiling splits the video into rectangular regions, which allows -\# multi-threading for encoding and decoding. The number of tiles is -\# always a power of two. 0=1 tile, 1=2, 2=4, 3=8, 4=16, 5=32. -tile-columns=2 -\medskip - -\# modified from https://trac.ffmpeg.org/wiki/EncodingForStreamingSites -\# To use a 2 second GOP (Group of Pictures), simply multiply your output -\# frame rate * 2. For example, if your input is -framerate 30, then use -\# -g 60. -g=240 -\medskip - -\# number of threads to use during encoding. -threads=8 -\medskip - -\# May be set to good, best, or realtime -quality=good -\medskip - -\# This parameter has different meanings depending upon whether quality -\# is set to good or realtime. Speed settings 0-4 apply for VoD in good -\# and best, with 0 being the highest quality and 4 being the -\# lowest. Realtime valid values are 5-8; lower numbers mean higher -\# quality -\medskip - -speed=4 + +\textbf{webm libvpx-vp9} + +(20171114-2203) + +from {\small \url{https://developers.google.com/media/vp9/settings/vod/}} + +1280x720 (24, 25 or 30 frames per second) + +Bitrate (bit rate) + +VP9 supports several different bitrate modes: + +\textit{mode:} + +\begin{tabular}{p{6cm} p{10cm}} + Constant Quantizer (Q) & Allows you to specify a fixed quantizer value; bitrate will vary \\ + Constrained Quality (CQ) & Allows you to set a maximum quality level. Quality may vary within bitrate parameters\\ + Variable Bitrate (VBR) & Balances quality and bitrate over time within constraints on bitrate\\ + Constant Bitrate (CBR) & Attempts to keep the bitrate fairly constant while quality varies\\ +\end{tabular} + +CQ mode is recommended for file-based video (as opposed to streaming). The following FFMpeg command-line parameters are used for CQ mode: + +\textit{FFMpeg}: + +\begin{center} + \begin{tabular}{{p{4cm} p{10cm}}} + -b:v & Sets target bitrate (e.g. 500k)\\ + -minrate & Sets minimum bitrate.\\ + -maxrate & Sets maximum bitrate.\\ + -crf & sets maximum quality level. Valid values are 0-63, lower numbers are higher quality.\\ +\end{tabular} +\end{center} + +\textit{Note 1}: Bitrate is specified in kbps, or kilobits per second. In video compression a kilobit is generally assumed to be 1000 bits (not 1024). + +\textit{Note 2:} Other codecs in FFMpeg accept the \textit{-crf} parameter but may interpret the value differently. If you are using \textit{-crf} with other codecs you will likely use different values for VP9. + +\texttt{bitrate=1024k}\\ +\texttt{minrate=512k}\\ +\texttt{maxrate=1485k}\\ +\texttt{crf=32} + +\textit{Tiling} splits the video into rectangular regions, which allows multi-threading for encoding and decoding. The number of tiles is always a power of two. 0=1 tile; 1=2; 2=4; 3=8; 4=16; 5=32\\ +\texttt{tile-columns=2} + +(modified from {\small \url{https://trac.ffmpeg.org/wiki/EncodingForStreamingSites}}) + +To use a 2 second \textit{GOP} (Group of Pictures), simply multiply your output frame rate $\times$ 2. For example, if your input is \textit{-framerate 30}, then use \textit{-g 60}.\\ +\texttt{g=240} + +number of \textit{threads} to use during encoding\\ +\texttt{threads=8} + +\textit{Quality} may be set to good, best, or realtime\\ +\texttt{quality=good} + +\textit{Speed}: this parameter has different meanings depending upon whether quality is set to good or realtime. Speed settings 0-4 apply for VoD in good and best, with 0 being the highest quality and 4 being the lowest. Realtime valid values are 5-8; lower numbers mean higher quality\\ +\texttt{speed=4} \section{Details about .bcast5 Files} -\label{sec:Details about .bcast5 Files} -\medskip +\label{sec:details_.bcast5_files} -The following extensions of files in Cinelerra's .bcast5 directory are explained below. +The following extensions of files in Cinelerra's \texttt{.bcast5} directory are explained below. % Labeling requires a parameter with the longest word of the labels. \begin{labeling}{ladspa\_plugins{\dots}} - \item [.dat] represent saved ``data'' for perpertual sessions and color palettes; maybe others - \item [.idx] original ``index'' files that were created for loaded video to speed up seeking - \item [.mkr] ffmpeg specific ``marker'' index file that is created for each video to aid seeks - \item [.rc] rc stands for ``run commands'' so basically represents a script - \item [.toc] toc is ``table of contents'' file for MPEG video files (a type of index) + \item [.dat] represent saved \textit{data} for perpertual sessions and color palettes; maybe others + \item [.idx] original \textit{index} files that were created for loaded video to speed up seeking + \item [.mkr] ffmpeg specific \textit{marker} index file that is created for each video to aid seeks + \item [.rc] rc stands for \textit{run commands} so basically represents a script + \item [.toc] toc is \textit{table of contents} file for MPEG video files (a type of index) \item [Cinelerra\_plugins] a list of the currently loaded plugins available in your Cinelerra session \item [Cinelerra\_rc] the user's preferences and settings are saved in this file to be used on startup \item [ladspa\_plugins{\dots}] list of currently loaded ladspa plugins for each version of Cinelerra being used diff --git a/parts/Developer.tex b/parts/Developer.tex index b168154..8f1a581 100644 --- a/parts/Developer.tex +++ b/parts/Developer.tex @@ -1,14 +1,13 @@ \chapter{Developer's Section}% -\label{cha:Developer's_Section} +\label{cha:developer's_section} \section{How Builds Really Work and Even More Options} -\label{sec:How Builds Really Work and Even More Options} +\label{sec:builds_really_work_more_options} This section describes how builds really work if you want to know more about making changes or understanding the process; probably only for a developer or system administrator. -\medskip Builds occur in 4 basic steps: -\smallskip + \begin{enumerate}[nosep] \item unpack/patch source code \item configure build @@ -17,32 +16,26 @@ Builds occur in 4 basic steps: \end{enumerate} So, an example of what happens in 4 steps for a single-user build would be as follows: -\smallskip \begin{enumerate}[nosep] - \item unpack/patch source code\newline - git clone --depth 1 ``git:/{\dots}/target'' cinelerra5\newline - ./autogen.sh - \item configure build\newline - ./configure --with-single-user - \item make build targets\newline - make 2{\textgreater}\&1 {\textbar} tee log - \item installation\newline - make install + \item unpack/patch source code: \\ + \texttt{git clone --depth 1 ``git:/{\dots}/target'' cinelerra5} \\ + \texttt{./autogen.sh} + \item configure build:\\ + \texttt{./configure --with-single-user} + \item make build targets:\\ + \texttt{make 2 > \&1 | tee log} + \item installation:\\ + \texttt{make install} \end{enumerate} -\medskip -A lot of things can be tweaked to change the results. \ Mostly these changes are parameters to the configure step, which can change important build related items, like the application name, or where and what the target system directories should be. \ This makes it possible to have several versions at the same time on the same computer if needed. \ To see what it is that the makefiles use to build Cinelerra, look at the resulting top-level global\_config file which is created by the ./configure step. -\medskip +A lot of things can be tweaked to change the results. Mostly these changes are parameters to the configure step, which can change important build related items, like the application name, or where and what the target system directories should be. This makes it possible to have several versions at the same time on the same computer if needed. To see what it is that the makefiles use to build Cinelerra, look at the resulting top-level global\_config file which is created by the ./configure step. -Building Cinelerra requires many thirdparty libraries, and it is recommended that you use the static build version included in the git repo. \ Some of them are patched, and fix significant bugs. \ It is important to note that because system installation historically has been with as many shared objects as possible, the defaults are that any system library detected during configuration setup will be used, when the package is built ``-{}-without-single-user'', which is the default build. \ To build with static thirdparty libraries for system install to the system /usr area, use: -\smallskip +Building Cinelerra requires many thirdparty libraries, and it is recommended that you use the static build version included in the git repo. Some of them are patched, and fix significant bugs. It is important to note that because system installation historically has been with as many shared objects as possible, the defaults are that any system library detected during configuration setup will be used, when the package is built \textit{-{}-without-single-user}, which is the default build. To build with static thirdparty libraries for system install to the system /usr area, use: -\hspace{2em}.configure -{}-enable-static-build --prefix=/usr -\medskip +\hspace{2em}\texttt{.configure -{}-enable-static-build --prefix=/usr} -Sometimes, additional package parameters and variables are needed during thirdparty builds. \ These optional values occur before and after the ``configure'' and ``make'' commands during a build. \ A presentation of the format of the package qualified variable names and how they appear in the build procedure are: -\medskip +Sometimes, additional package parameters and variables are needed during thirdparty builds. These optional values occur before and after the \textit{configure} and \textit{make} commands during a build. A presentation of the format of the package qualified variable names and how they appear in the build procedure are: \hspace{2em} \begin{tabular}{@{}ll} @@ -53,77 +46,58 @@ Sometimes, additional package parameters and variables are needed during thirdpa pkg.cflags & added as CFLAGS+=\$(cflags) to pkg.vars\\ pkg.cppflags & added as CPPFLAGS+=\$(cppflags) to pkg.vars\\ \end{tabular} -\bigskip These steps are done for EACH of the packages in the thirdparty build: -\smallskip -\hspace{2em}{\textless}pkg.cfg\_vars{\textgreater} ./configure {\textless}pkg.cfg\_params{\textgreater} +\hspace{2em}\texttt{ ./configure } -\hspace{2em}{\textless}pkg.mak\_vars{\textgreater} make {\textless}pkg.mak\_params{\textgreater} -\bigskip +\hspace{2em}\texttt{ make } -The thirdparty Makefile has a set of default vars and params used to build each of the needed thirdparty packages, but you can specify new or overriding values for these Makefile substitutions. \ These thirdparty build config changes are specified in the top-level file: cin\_config. \ By using this file, you can save the configuration changes made for the current build to use the next time you do a new build. \ For example, to add an include file path to the giflib build, add this line to cin\_config: -\medskip +The thirdparty Makefile has a set of default vars and params used to build each of the needed thirdparty packages, but you can specify new or overriding values for these Makefile substitutions. These thirdparty build config changes are specified in the top-level file: \textit{cin\_config}. By using this file, you can save the configuration changes made for the current build to use the next time you do a new build. For example, to add an include file path to the giflib build, add this line to \textit{cin\_config}: -\hspace{2em}giflib.cflags := -I/usr/local/include/giflib5 -\medskip +\hspace{2em}\texttt{giflib.cflags := -I/usr/local/include/giflib5} To have a param/var change apply to all thirdparty builds, use: -\medskip -\hspace{2em}CFG\_VARS, CFG\_PARAMS, MAK\_VARS, MAK\_PARAMS -\medskip +\hspace{2em}\texttt{CFG\_VARS, CFG\_PARAMS, MAK\_VARS, MAK\_PARAMS} CFLAGS, CXXFLAGS and LDFLAGS are forwarded to the thirdparty build environment via: -\medskip -\hspace{2em}CFLAGS=-ggdb ./configure -{}-with-single-user -\medskip +\hspace{2em}\texttt{CFLAGS=-ggdb ./configure -{}-with-single-user} However, there is no guarantee that the thirdparty build will honor the environmental flags. Finally, there are build controls, which enable/disable and set build features. -\bigskip A few of the more useful ./configure -{}-parameters are: -\smallskip -\hspace{2em} -\begin{tabular}{@{}ll} - {}-{}-with-jobs=n & where n=number of build jobs; defaults to 1.5*cpus+2\\ - {}-{}-enable-static-build & build all 3rd party libs; defaults to yes if single-user, else no\\ - {}-{}-with-single-user& build installs to {\textless}build\_path{\textgreater}/bin; \ no system installation\\ +\begin{tabular}{ll} + -{}-with-jobs=n & where n=number of build jobs; defaults to 1.5*cpus+2\\ + -{}-enable-static-build & build all 3rd party libs; defaults to yes if single-user, else no\\ + -{}-with-single-user& build installs to /bin; no system installation\\ \end{tabular} -\medskip -The ./configure command builds ``global\_config''. \ The global\_config is read by the thirdparty/Makefile to create the recipes and definitions used by the thirdparty build. -\medskip +The ./configure command builds \textit{global\_config}. The global\_config is read by the thirdparty/Makefile to create the recipes and definitions used by the thirdparty build. There are a lot of different options. Thirdparty library build control is available in the configure step of the build. Thirdparty libraries are built on a demand basis. So if you use: -\medskip -\hspace{2em} -\begin{tabular}{@{}ll} - --enable-libname=auto & \# the static-build enable, or the lack of a system library causes a build\\ - --enable-libname=yes & \# this forces the thirdparty build\\ - --enable-libname=no & \# this forces no thirdparty build\\ +\begin{tabular}{l p{11cm}} + -{}-enable-libname=auto & the static-build enable, or the lack of a system library causes a build\\ + -{}-enable-libname=yes & this forces the thirdparty build\\ + -{}-enable-libname=no & this forces no thirdparty build\\ \end{tabular} -\medskip -FFmpeg is a ``strongly connected component''in the build linkage and widely influences the Cinelerra library demands. It is possible to make small additions to the ffmpeg configuration step using the environment variable FFMPEG\_EXTRA\_CFG. For example, to eliminate the use of libvdpau (an nvidia support library) in the ffmpeg configuration step after you have determined that it is causing an error, use: +FFmpeg is a \textit{strongly connected} component in the build linkage and widely influences the Cinelerra library demands. It is possible to make small additions to the ffmpeg configuration step using the environment variable \texttt{FFMPEG\_EXTRA\_CFG}. For example, to eliminate the use of libvdpau (an nvidia support library) in the ffmpeg configuration step after you have determined that it is causing an error, use: \begin{itemize}[label={},nosep] - \item make clean - \item autogen.sh - \item export FFMPEG\_EXTRA\_CFG={\textquotedbl} -{}-disable-vdpau{\textquotedbl} - \item ./configure {\dots} + \item \texttt{make clean} + \item \texttt{autogen.sh} + \item \texttt{export FFMPEG\_EXTRA\_CFG=" -{}-disable-vdpau"} + \item \texttt{./configure} {\dots} \end{itemize} -\medskip -Specific information on using the current ffmpeg GIT repository follows. You have to supply the actual URL location of the ffmpeg git as you can see in this example ?bld.sh? script: -\medskip +Specific information on using the current ffmpeg GIT repository follows. You have to supply the actual URL location of the ffmpeg git as you can see in this example \texttt{?bld.sh?} script: \begin{lstlisting}[numbers=none] #!/bin/bash\newline @@ -134,10 +108,10 @@ mv Makefile Makefile.cfg cp Makefile.devel Makefile \end{lstlisting} -Since the procedure for obtaining the latest ffmpeg version is not always kept up-to-date and the line numbers will always change, you may have to create that patch first. \ Generally those line numbers are only updated by a developer when a new stable version with worthwhile features is actually included in the Cinelerra build. FFmpeg is constantly changing and many times the git version is not as stable as desired. +Since the procedure for obtaining the latest ffmpeg version is not always kept up-to-date and the line numbers will always change, you may have to create that patch first. Generally those line numbers are only updated by a developer when a new stable version with worthwhile features is actually included in the Cinelerra build. FFmpeg is constantly changing and many times the git version is not as stable as desired. \section{Configuration Features} -\label{sec:Configuration Features} +\label{sec:configuration_features} A listing of the current configuration features as of January 11, 2020: @@ -328,21 +302,17 @@ Report bugs to . \endgroup \section{Thirdparty Parallel Build} -\label{sec:Thirdparty Parallel Build} +\label{sec:thirdparty_parallel_build} The Makefile in the thirdparty build directory employs a set of macros used to create a build rule set of thirdparty library build dependencies. The standard build sequence of [source, config, build] is used to prepare thirdparty products as static libraries. Build package dependency can be specified in the Makefile std-build macro call. These Makefile macro calls define the rules used for each thirdparty build. The expanded rule definitions may be viewed by using: -\smallskip -\hspace{2em}make -C thirdparty rules -\medskip +\hspace{2em}\texttt{make -C thirdparty rules} Individual package libraries can be rebuilt, via: -\smallskip -\hspace{2em}make -C thirdparty -clean; make -C thirdparty -\medskip + +\hspace{2em}\texttt{make -C thirdparty -clean; make -C thirdparty } The rule targets create the set of thirdparty packages which are built from local source archive copies of thirdparty source code and patches, if needed. The build rule set of dependencies allows for compiling multiple thirdparty programs simultaneously using maximum computer resources. This parallel build speeds up the process considerably. For example, these are full static build timings on the production build machine (full build includes building all thirdparty programs as well as all of Cinelerra): -\medskip \hspace{2em} \begin{tabular}{@{}rcr} @@ -352,26 +322,22 @@ The rule targets create the set of thirdparty packages which are built from loca \end{tabular} \section{Find Lock Problems with Booby Trap} -\label{sec:Find Lock Problems with Booby Trap} +\label{sec:find_lock_problems_booby_trap} -A Booby Trap is used in CinGG for setting a trap to catch lock problems that might have been missed. \ It will trap boobies only if compile by adding ``-{}-with-booby'' on the configuration command line. \ \ This is the default if you compile using ./bld.sh from the GIT repository. \ It should not interfere with normal execution. -\medskip +A Booby Trap is used in CinGG for setting a trap to catch lock problems that might have been missed. It will trap boobies only if compile by adding \textit{-{}-with-booby} on the configuration command line. This is the default if you compile using \texttt{./bld.sh} from the GIT repository. It should not interfere with normal execution. -If you have the time and inclination, enable -{}-with-booby and send any trap output that you find. \ Maybe you will catch some boobies and if you do, send a snapshot of any boobies you find. -\medskip +If you have the time and inclination, enable \textit{-{}-with-booby} and send any trap output that you find. Maybe you will catch some boobies and if you do, send a snapshot of any boobies you find. There are 2 potential traps: + \begin{itemize}[nosep] \item If you try to unlock a lock when it is not locked \item If you execute a drawing operation without holding the window lock \end{itemize} -\medskip The trap prints the following in the controlling terminal window: -\medskip -\hspace{2em}BOOBY!hspace{2em}{\textless}backtrace{\textgreater} -\medskip +\hspace{2em} \textit{BOOBY! \qquad } An example backtrace is below along with a hint below on how to analyze: @@ -389,67 +355,55 @@ An example backtrace is below along with a hint below on how to analyze: \end{lstlisting} To see which routine is reporting the booby key in: -\smallskip -\hspace{2em}c++filt -\smallskip +\hspace{2em} \texttt{c++filt} -And then the 2nd line in the backtrace above: -\smallskip +And then the $2^{nd}$ line in the backtrace above: -\hspace{2em}\_ZN13BC\_WindowBase9draw\_lineEiiiiP9BC\_Pixmap -\smallskip +\hspace{2em}\texttt{\_ZN13BC\_WindowBase9draw\_lineEiiiiP9BC\_Pixmap} It comes back with the routine as: -\smallskip -\hspace{2em}BC\_WindowBase::draw\_line(int, int, int, int, BC\_Pixmap*) -\medskip +\hspace{2em}\texttt{BC\_WindowBase::draw\_line(int, int, int, int, BC\_Pixmap*)} \section{Valgrind Support Level} -\label{sec:Valgrind Support Level} +\label{sec:valgrind_support_level} Valgrind is a memory mis-management detector. It shows you memory leaks, deallocation errors, mismanaged threads, rogue reads/writes, etc. Cinelerra-GG memory management is designed to work with Valgrind detection methods. This assists in developing reliable code. Use of Valgrind points out problems so that they can be fixed. For example, when this version of Cinelerra shuts down, it deallocates memory instead of just stopping, thus making memory leak detection possible. -\medskip The best way to compile and run valgrind is to run the developer static build. This takes 2 steps and you must already have gdb and valgrind installed: -\medskip \begin{enumerate}[nosep] - \item The standard static build:\newline - cd /path/cinelerra-5.1\newline - make clean\newline - ./bld.sh - \item run the incremental rebuild for debug objs\newline - CFLAGS=-ggdb make -j8 rebuild\_all + \item The standard static build:\\ + \texttt{cd /path/cinelerra-5.1}\\ + \texttt{make clean}\\ + \texttt{./bld.sh} + \item run the incremental rebuild for debug objs:\\ + \texttt{CFLAGS=-ggdb make -j8 rebuild\_all} \end{enumerate} -\medskip Now your Cinelerra obj has all of the debug stuff. Next run valgrind as root for the most useful results: -\smallskip -\hspace{2em}cd /path/cinelerra-5.1/cinelerra +\hspace{2em}\texttt{cd /path/cinelerra-5.1/cinelerra} -\hspace{2em}valgrind -{}-log-file=/tmp/log -{}-leak-check=full -{}-num-callers=32 ./ci -\medskip +\hspace{2em}\texttt{valgrind -{}-log-file=/tmp/log -{}-leak-check=full\\ + -{}-num-callers=32 ./ci} -This runs Cinelerra under the control of valgrind, and produces a log file in /tmp which will list information about any leaks, usually clearly identifiable. \ Be sure to Quit out of Cinelerra normally instead of Ctrl-C or a SEGV otherwise the program does not have a chance to cleanup and there will be some false alarms. But it runs very slowly, and is basically single threaded, which means that race conditions may be impossible to catch... like one thread deletes memory that another thread is currently using. But overall it is a big help and if you test any new features, please email the log output. \ A lot of effort when writing the code was put into trying to be sure that all of the object constructors have matching destructors so that the leaks can be identified. There are already several libraries that create predictable memory leaks and valgrind does a good job for most of these. -\medskip +This runs Cinelerra under the control of valgrind, and produces a log file in /tmp which will list information about any leaks, usually clearly identifiable. Be sure to Quit out of Cinelerra normally instead of Ctrl-C or a SEGV otherwise the program does not have a chance to cleanup and there will be some false alarms. But it runs very slowly, and is basically single threaded, which means that race conditions may be impossible to catch$\dots$ like one thread deletes memory that another thread is currently using. But overall it is a big help and if you test any new features, please email the log output. A lot of effort when writing the code was put into trying to be sure that all of the object constructors have matching destructors so that the leaks can be identified. There are already several libraries that create predictable memory leaks and valgrind does a good job for most of these. -It is impossible to test everything with valgrind because some things are just too big and slow for a practical test. \ Occasionally you can find a leak or an illegal memory access. There are several false alarms that are difficult to avoid {\textquotedbl}Conditional jump{\textquotedbl} messages, and {\textquotedbl}unhandled DW\_OP\_{\textquotedbl}, but anything with the word {\textquotedbl}illegal{\textquotedbl} in the message is important. Memory leaks that originate in Cinelerra are good to find and fix, but are usually not deadly. +It is impossible to test everything with valgrind because some things are just too big and slow for a practical test. Occasionally you can find a leak or an illegal memory access. There are several false alarms that are difficult to avoid \textit{Conditional jump} messages, and \textit{unhandled DW\_OP\_}, but anything with the word \textit{illegal} in the message is important. Memory leaks that originate in Cinelerra are good to find and fix, but are usually not deadly. \section{CFLAGS has -Wall} -\label{sec:CFLAGS has -Wall} -When compiling Cinelerra-GG Infinity a CFLAGS option used is "Wall" where the "W" represents warnings and "all" means all. This causes the compile to check for simple mistakes that can be detected automatically and issue warnings when the code is questionable. It can also detect situations where the compiler will generate incorrect code, like type-punned pointer. By turning on this flag, when new code is vetted for predictable mistakes, the code can be corrected before becoming manifested in the application. +\label{sec:cflags_has_-wall} +When compiling Cinelerra-GG Infinity a CFLAGS option used is \textit{Wall} where the "W" represents warnings and "all" means all. This causes the compile to check for simple mistakes that can be detected automatically and issue warnings when the code is questionable. It can also detect situations where the compiler will generate incorrect code, like type-punned pointer. By turning on this flag, when new code is vetted for predictable mistakes, the code can be corrected before becoming manifested in the application. \section{Prof2 -- A Profiler} -\label{sec:Prof2 -- A Profiler} +\label{sec:prof2_profiler} + +Frequently there is a problem with a program running slow and you do not know why. You need a thumbnail analysis of where the program is spending most of its time without all of the overwhelming details. This is when a Profiler comes in handy. -Frequently there is a problem with a program running slow and you do not know why. \ You need a thumbnail analysis of where the program is spending most of its time without all of the overwhelming details. \ This is when a Profiler comes in handy. -\medskip +There are many different profilers available -- this particular one does not do anything special and is fairly ordinary in that it just characterizes frequency of execution of various regions in the program. However, it has some pretty good strengths as listed next. -There are many different profilers available -- this particular one does not do anything special and is fairly ordinary in that it just characterizes frequency of execution of various regions in the program. \ However, it has some pretty good strengths as listed next. -\medskip \begin{enumerate}[nosep] \item It takes very little or no preconditioning, i.e. setup \item The effect it has on the running program is minimal @@ -457,25 +411,28 @@ There are many different profilers available -- this particular one does not do \item It is not particularly thread aware \item Reports where it is executing at intervals of 100 times a second \end{enumerate} + \subsection{Setup} +\label{sub:setup} -This profiler works on x86\_64 systems and you must be root to compile and run it. \ Also, you must install your operating system's ``iberty'' -- for example, which would be binutils-devel for Fedora or libiberty-dev for Ubuntu 18. -\medskip +This profiler works on x86\_64 systems and you must be root to compile and run it. Also, you must install your operating system's \textit{iberty} -- for example, which would be binutils-devel for Fedora or libiberty-dev for Ubuntu 18. Go to the top level Cinelerra directory. -Key in: \ \ \ \ cd prof2 +Key in: \qquad \texttt{prof2} + +Key in: \qquad \texttt{make clean all install} -Key in: \ \ \ \ make clean all install +Later, if you wanttitle to remove this from the system, + +key in: \qquad \texttt{make uninstall} -Later, if you wanttitle to remove this from the system, key in: \ \ \ \ make uninstall \subsection{How to use} +\label{sub:how_to_use} The program you are profiling should be compiled debuggable with stack frame and symbols enabled. -\medskip -To see help, key in: \ \ prof -h -\smallskip +To see help, key in: \qquad \texttt{prof -h} usage: -h [-o path] [-d] [-e] [-p libpath] [-012] [-u \#] cmd args... @@ -490,46 +447,36 @@ usage: -h [-o path] [-d] [-e] [-p libpath] [-012] [-u \#] cmd args... -2 & real time timer intervals (sigalrm)\\ -u & profile timer interval in usecs\\ \end{tabular} -\medskip -To execute the profiler, key in: \ \ -\medskip +To execute the profiler, key in: -\hspace{2em}prof -o /tmp/prof\_list.txt ./cin -\medskip +\hspace{2em}\texttt{prof -o /tmp/prof\_list.txt ./cin} -where /tmp/prof\_list.txt is the output file and in this case ``cin'' is the Cinelerra binary file. \ The pid of this command will be displayed on the startup window. \ This comes in handy in the use case where there is a lot of initial load and possible configuration setup inside of Cinelerra and you want to profile plugins and not necessarily all of the setup steps. \ Then you can use the following command in another window to continue running Cinelerra and obtain the more useful information: -\medskip +where \texttt{/tmp/prof\_list.txt} is the output file and in this case \texttt{cin} is the Cinelerra binary file. The pid of this command will be displayed on the startup window. This comes in handy in the use case where there is a lot of initial load and possible configuration setup inside of Cinelerra and you want to profile plugins and not necessarily all of the setup steps. Then you can use the following command in another window to continue running Cinelerra and obtain the more useful information: -\hspace{2em}kill -USR1 pid -\medskip +\hspace{2em}\texttt{kill -USR1 pid} -Running this command refreshes the memory maps used for profiling. \ When you are profiling a plugin, you want to run this AFTER the plugin loads. -\medskip +Running this command refreshes the memory maps used for profiling. When you are profiling a plugin, you want to run this AFTER the plugin loads. \subsection{Results} +\label{sub:results} There are 3 sections in the resulting output file of this stochastic quick analysis. -\medskip \begin{enumerate}[nosep] - \item The first section is a histogram of the timer intervals of that sample set. \ Each function occupies a region of addresses. \ One hundred times a second, the profiler samples the program address in the region of execution. - \item In the second section, there is another histogram of the cumulative frequency of all things in the call stack and this should point out who is the culprit. \ For example, a codec calls a bunch of subroutines, the cost of the subroutines is accumulated to the codec parent caller. \ This makes the actual cpu user much more apparent. - \item The last section is for the library spaces. \ Each library occupies a region and the profiler adds up the time spent in each of the libraries by frequency. + \item The first section is a histogram of the timer intervals of that sample set. Each function occupies a region of addresses. One hundred times a second, the profiler samples the program address in the region of execution. + \item In the second section, there is another histogram of the cumulative frequency of all things in the call stack and this should point out who is the culprit. For example, a codec calls a bunch of subroutines, the cost of the subroutines is accumulated to the codec parent caller. This makes the actual cpu user much more apparent. + \item The last section is for the library spaces. Each library occupies a region and the profiler adds up the time spent in each of the libraries by frequency. \end{enumerate} -\smallskip On the very bottom is a 1 line summary which shows you if there is a bad guy and who it is. -\medskip \subsection{Sample output} +\label{sub:sample_output} -\medskip - -%\begin{lstlisting}[numbers=none] %\textwidth +\textit{--- profile start ---} ----- profile start ----\\ -1020 ticks 43 modules 81412 syms\\ +\textbf{1020 ticks 43 modules 81412 syms}\\ \begin{tabular}{@{}rrp{\linewidth-6em}} 0.010s & 0.1\% & Autos::copy(long, long, FileXML*, int, int) /mnt0/build5/cinelerra-5.1/bin/cin\\ 0.010s & 0.1\% & BinFolders::copy\_from(BinFolders*) /mnt0/build5/cinelerra-5.1/bin/cin\\ @@ -543,9 +490,10 @@ On the very bottom is a 1 line summary which shows you if there is a bad guy and 0.010s & 0.1\% & BC\_Bitmap::cur\_bfr() /mnt0/build5/cinelerra-5.1/bin/cin\\ 0.010s & 0.1\% & YUV::init\_tables(int, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*, int*) /mnt0/build5/cinelerra-5.1/bin/cin\\ \end{tabular}\\ -...\\ -...\\ ----- profile calls ----\\ +$\dots$\\ +$\dots$\\ +\textit{--- profile calls ---} + \begin{tabular}{@{}rrl} 0.010s & 0.1\% & AutoConf::save\_xml(FileXML*) 1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\ 0.010s & 0.1\% & Automation::copy(long, long, FileXML*, int, int) 1.0 /mnt0/.../cin\\ @@ -558,8 +506,8 @@ On the very bottom is a 1 line summary which shows you if there is a bad guy and 0.010s & 0.1\% & CWindowGUI::draw\_status(int) 1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\ 0.010s & \textbf{0.1\%} & CWindowCanvas::status\_event() 1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\ \end{tabular}\\ -...\\ -...\\ +$\dots$\\ +$\dots$\\ \begin{tabular}{@{}rrl} 0.990s & \textbf{9.7\%} & BC\_Xfer::xfer\_slices(int) 1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\ 1.880s & \textbf{18.4\%} & DirectUnit::process\_package(LoadPackage*) 1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\ @@ -569,8 +517,8 @@ On the very bottom is a 1 line summary which shows you if there is a bad guy and 7.890s & \textbf{77.4\%} & Thread::entrypoint(void*) 1.0 /mnt0/build5/cinelerra-5.1/bin/cin\\ 7.890s & \textbf{77.4\%} & start\_thread 1.0 /lib64/libpthread-2.28.so\\ \end{tabular}\\ -----\\ -----\\ +---\\ +---\\ \begin{tabular}{@{}rrl} 0.010s & 0.1\%/ 0.0\% & /lib64/libm-2.28.so\\ 0.010s & 0.1\%/ 0.0\% & /lib64/libexpat.so.1.6.8\\ @@ -585,15 +533,10 @@ On the very bottom is a 1 line summary which shows you if there is a bad guy and 0.380s & 3.7\%/ 1.8\% & /lib64/libpthread-2.28.so\\ 1.660s & 16.3\%/ 7.7\% & /lib64/libc-2.28.so\\ 7.480s & 73.3\%/34.7\% & /mnt0/build5/cinelerra-5.1/bin/cin\\ -\end{tabular}\\ - -\textbf{10.200t 0.001u+0.000s 21.566r 47.3\%} -\\ ----- profile end ---- -%\end{lstlisting} -\medskip +\end{tabular} -The summary line above in Bold represents the User time, System time, Real time and the percentage is how much Timer time elapsed over Real time so in this case the measurement covers 47.3\% of time. -\medskip +\textbf{10.200t 0.001u+0.000s 21.566r 47.3\%}\\ +\textit{--- profile end ---} -So why use a Profiler? \ Because it is the ``ls'' for executable functions!! +The summary line above in Bold represents the User time, System time, Real time and the percentage is how much Timer time elapsed over Real time so in this case the measurement covers 47.3\% of time.\\ +So why use a Profiler? Because it is the ``ls'' for executable functions!! diff --git a/parts/Installation.tex b/parts/Installation.tex index 0695aa0..b35e81b 100644 --- a/parts/Installation.tex +++ b/parts/Installation.tex @@ -592,7 +592,7 @@ use alternative anti-virus software (the standard default already included with is Defender). Below are the steps for installation: \begin{enumerate} - \item Download cygwin for your 64-bit computer at: \url{https://www.cygwin.com/} + \item Download cygwin for your 64-bit computer at: {\small \url{https://www.cygwin.com/}} \item Generally just take the defaults as they show up, but the next steps show what comes up. \item When a warning window pops up, click \textit{Yes}. \item Click \textit{Next}. @@ -615,36 +615,36 @@ is Defender). Below are the steps for installation: \end{enumerate} Then to install the Cinelerra tar files, you will need to start a cygwin console terminal from the startup menu as shown here: - Start $\rightarrow$ Cygwin $\rightarrow$ Cygwin64 Terminal + \texttt{Start $\rightarrow$ Cygwin $\rightarrow$ Cygwin64} Terminal \underline{Installing Cinelerra:} \begin{enumerate} - \item Download the tar file at: - https://cinelerra-gg.org/download/testing/libxcb-bld.tar.bz2 - \item Install libxbc from the tar file -- installs into /usr/local and requires approximately 21MB storage. + \item Download the tar file at:\\ + {\small \url{https://cinelerra-gg.org/download/testing/libxcb-bld.tar.bz2}} + \item Install libxbc from the tar file -- installs into \texttt{/usr/local} and requires approximately 21MB storage. \begin{lstlisting}[language=bash,numbers=none] $ tar -C /usr/local -xJf /path/libxcb-bld.tar.bz2 \end{lstlisting} The libxcb path repairs an error (XIOError), which stops the program. - \item Download the tar file at: - https://cinelerra-gg.org/download/testing/cygcin-bld.tar.bz2 + \item Download the tar file at:\\ + {\small \url{https://cinelerra-gg.org/download/testing/cygcin-bld.tar.bz2}} \item Install cygcin from the tar file - this installs into home directory. Note this is cygcin NOT cygwin. \begin{lstlisting}[language=bash,numbers=none] $ cd $ tar -xJf /path/cygcin-bld.tar.bz2 \end{lstlisting} \end{enumerate} -This creates \~{}/cygcin , a user build installation of Cinelerra and requires approximately 400MB storage. +This creates \texttt{\~{}/cygcin} , a user build installation of Cinelerra and requires approximately 400MB storage. \underline{Running Cinelerra:} You will need to start a cygwin desktop from the startup menu: \begin{enumerate} - \item Start$\rightarrow$ Cygwin-X $\rightarrow$ Openbox + \item \texttt{Start$\rightarrow$ Cygwin-X $\rightarrow$ Openbox} You should start a console controlling terminal so that you can see program logging. - \item Start$\rightarrow$ Cygwin $\rightarrow$ Cygwin64 Terminal + \item \texttt{Start$\rightarrow$ Cygwin $\rightarrow$ Cygwin64} Terminal This opens a separate window that can survive a cygwin hang and bugs. Without these logs, it is much more difficult to use. @@ -713,7 +713,7 @@ omissions are applied to this build. \end{lstlisting} \end{enumerate} -This produces a directory: $/build\_path$/cinelerra-gg$/cinelerra-5.1$/bin \newline +This produces a directory: $/build\_path$/cinelerra-gg$/cinelerra$-5.1/bin \newline which is used to create the cygcin archive. Currently, the targets are not stripped and can be run from gdb. diff --git a/parts/Introduction.tex b/parts/Introduction.tex index 27301ec..4407c04 100644 --- a/parts/Introduction.tex +++ b/parts/Introduction.tex @@ -245,11 +245,11 @@ And which chapters are important for beginning to learn to use Cinelerra-GG. At Here you go! If you hate to read, just go over the quick start guide or the youtube video creation and simply be on your way. - \item[Appendix \ref{cha:Developer's_Section}] \nameref{cha:Developer's_Section}. + \item[Appendix \ref{cha:developer's_section}] \nameref{cha:developer's_section}. Some extra information that developers may or may not find useful. - \item[Appendix \ref{cha:Auxiliary_Programs}] \nameref{cha:Auxiliary_Programs}. + \item[Appendix \ref{cha:auxiliary_programs}] \nameref{cha:auxiliary_programs}. This is a catch-all for any useful programs that may need to be included, mostly for analysis. diff --git a/parts/Licenses.tex b/parts/Licenses.tex index bee4bb1..2a8385e 100644 --- a/parts/Licenses.tex +++ b/parts/Licenses.tex @@ -21,14 +21,14 @@ License: GPLv2+ and CeCILL and BSD and CC-BY and Public Domain Cinelerra-GG codebase is licensed GPLv2+ -\noindent See: {\small \url{https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html }} +See: {\small \url{https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html }} \vspace{2ex} \textbf{Creative Commons Attribution 4.0 International License} -Cinfinity icons (c) by "Sam" and Neophyte theme by "Olaf" are licensed under a +Cinfinity icons (c) by "Sam"; Neophyte and Cakewalk themes by "Olaf" are licensed under a Creative Commons Attribution 4.0 International License. -\noindent see: {\small \url{http://creativecommons.org/licenses/by/4.0/}} +see: {\small \url{http://creativecommons.org/licenses/by/4.0/}} \vspace{2ex} \textbf{License Agreement for OpenCV} @@ -46,4 +46,4 @@ Redistribution and use in source and binary forms, with or without modification, \item Neither the names of the copyright holders nor the names of the contributors may be used to endorse or promote products derived from this software without specific prior written permission. \end{itemize} -This software is provided by the copyright holders and contributors “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall copyright holders or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. \ No newline at end of file +This software is provided by the copyright holders and contributors \textit{as is} and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall copyright holders or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. \ No newline at end of file diff --git a/parts/Loadandsave.tex b/parts/Loadandsave.tex index 72589b6..2685641 100644 --- a/parts/Loadandsave.tex +++ b/parts/Loadandsave.tex @@ -73,7 +73,7 @@ File lists formats can be utilized in some way for the following list of types o \end{center} %\vspace*{1ex} -Using the example of jpeg’s, the jpeg list sequence file type is the easiest and fastest way to access a sequence of jpg images as a single asset. First build a jpeglist sequence file and name it something like jpeglist.sh. There is an example script of how to do this in the Auxiliary Programs section of the Appendix (\ref{sec:Image Sequence Creation}). Once the jpeglist.sh file is built you can then run it similar to this line: +Using the example of jpeg’s, the jpeg list sequence file type is the easiest and fastest way to access a sequence of jpg images as a single asset. First build a jpeglist sequence file and name it something like jpeglist.sh. There is an example script of how to do this in the Auxiliary Programs section of the Appendix (\ref{sec:image_sequence_creation}). Once the jpeglist.sh file is built you can then run it similar to this line: \begin{lstlisting}[language=bash,numbers=none] $ jpeglist.sh //file.jpg //DSC*.jpg diff --git a/parts/Quickstart.tex b/parts/Quickstart.tex index 93f04f7..4c1a15e 100644 --- a/parts/Quickstart.tex +++ b/parts/Quickstart.tex @@ -9,7 +9,10 @@ Cinelerra is a software program NLE, Non-Linear Editor, that provides a way to e \subsection{Install the Software}% \label{sub:install_software} -On the internet, click on the Download page at: \quad {\small \url{https://cinelerra-gg.org/downloads/}} +On the internet, click on the Download page at: +\begin{center} + {\small \url{https://cinelerra-gg.org/downloads/}} +\end{center} Here you will see several Operating System distro packages that are already built for you to download. Click on your preference and read the specific instructions for usage. \begin{figure}[htpb] @@ -61,17 +64,17 @@ On the main timeline program window are many pulldowns, the first of which is \t \end{figure} \begin{enumerate} - \item Click on \texttt{File} for a list of available options and note that in the right hand column are shortcuts for + \item Click on \textit{File} for a list of available options and note that in the right hand column are shortcuts for many of the options that will come in handy if you use Cinelerra often. - \item Next click on the second one down -- \texttt{Load files$\dots$} -- which brings up the Load menu. - \item Below \texttt{Select files to load} on the top left side is a textbox and if you look all the way to the right + \item Next click on the second one down -- \textit{Load files$\dots$} -- which brings up the Load menu. + \item Below \textit{Select files to load} on the top left side is a textbox and if you look all the way to the right side of the textbox, there is a down arrow which you use to navigate your file system. Highlight the desired file system and you will see that directory name appear in the textbox and the files below. \item Scroll to the media file you would like to work on and highlight that file. When you do, you will see that filename also appear in the textbox below the listing of files. You could have directly keyed in that file in that textbox instead. \item On the bottom of the Load menu, is a box called \textit{Insertion strategy}. For getting started the - default of \texttt{Replace current project} is sufficient. But you can click on the down arrow to see what + default of \textit{Replace current project} is sufficient. But you can click on the down arrow to see what is available for future use. \item Now click on the green colored checkmark on the bottom left hand side to actually load the file and see it appear on the timeline in Cinelerra’s main window and a single frame in the Compositor. @@ -89,24 +92,24 @@ You can skip this step if you want the format of your output to be the same as y \begin{enumerate} \item On the main timeline, use the \textit{Settings} pulldown (about the $7^{th}$ pulldown from the left side top) and - click on \texttt{Format} which is the first option in that list. + click on \textit{Format} which is the first option in that list. \item A \textit{Set Format} menu will appear that shows what the current format is for your loaded media in an Audio and a Video tab. In the United States, the Video Frame rate is usually expected to be 29.970 and usually the Color model is only changed if you have a personal preference. - \item The \texttt{Canvas size} is probably the only thing you will want to change here in order to get to the + \item The \textit{Canvas size} is probably the only thing you will want to change here in order to get to the most commonly viewable settings. On the right hand side of the Width parameter is a down arrow. Left click the down arrow to see your options. + \item Highlight $1280\times720$ HD for a good common option. + \item Click OK to have this option take effect. When you do, the Compositor window may change to fit + this option and may look wrong sized. \end{enumerate} \begin{figure}[htpb] \centering - \includegraphics[width=0.8\linewidth]{images/format_setting.png} + \includegraphics[width=0.7\linewidth]{images/format_setting.png} \caption{Format menu to change settings} \end{figure} -\begin{enumerate}[resume] - \item Highlight $1280\times720$ HD for a good common option. - \item Click \texttt{OK} to have this option take effect. When you do, the Compositor window may change to fit - this option and may look wrong sized. +\begin{enumerate}[resume] \item If the video now looks too small or too large in the Compositor, you will want to \textit{autoscale} it to look correct when the new media is created. To do this, mouse over to the Resources window in the lower right hand corner and under the word Visibility, highlight \textit{Video Effects} to see some @@ -117,18 +120,15 @@ You can skip this step if you want the format of your output to be the same as y new value. Click on the magnifying glass icon on the brown colored line beneath the main timeline video which opens a new window. In that window, again use the down arrow to choose $1280\times720$ HD, then dismiss this window. + \item If not needed, to remove the Auto Scale plugin, right mouse on the brown line and choose \textit{Detach}. \end{enumerate} \begin{figure}[htpb] \centering - \includegraphics[width=0.6\linewidth]{images/magnifier.png} + \includegraphics[width=0.5\linewidth]{images/magnifier.png} \caption{Effect brown bar with magnifier} \end{figure} -\begin{enumerate}[resume] - \item If not needed, to remove the Auto Scale plugin, right mouse on the brown line and choose \texttt{Detach}. -\end{enumerate} - \subsection{View and Listen}% \label{sub:view_listen} @@ -170,18 +170,18 @@ There may be sections of your media that you want to delete, or audio that is ha easiest is to move your mouse and left click at the beginning of the section you want to delete on the timeline and while holding down the left mouse button, drag to the end of the section to be deleted. When you do this, a white colored highlighted section becomes visible. Use the edit pulldown and - choose the \texttt{split/cut} option to cut out the highlighted area (note the shortcut of \texttt{x}). Remember if you + choose the \textit{split/cut} option to cut out the highlighted area (note the shortcut of "x"). Remember if you cut the wrong thing out you can always use the Edit pulldown to Undo that. \item To add a transition where there is deleted section which may make your video look disjointed, do the following. Go back to the Resources window in the bottom right hand corner. Change to \textit{Video Transitions} by highlighting that underneath the word \textit{Visibility}. Highlight a transition like - \texttt{BandSlide} with the left button mouse click, hold down and drag to the video track and when you see + \textit{BandSlide} with the left button mouse click, hold down and drag to the video track and when you see a white colored box around the area that you deleted above, drop the icon. Right mouse click the icon on the track to vary some parameters like length. \item To insert another clip from a different video, first you have to load the other video on another track. - Go to \textit{File} pulldown again and choose the \texttt{Load files} option. Type in a directory at the top again and + Go to \textit{File} pulldown again and choose the \textit{Load files} option. Type in a directory at the top again and erase any specific file that you may have chosen previously in the bottom 2 textboxes. It is very - important to now change the Insertion strategy to \texttt{Append in new tracks} or you will write over + important to now change the Insertion strategy to \textit{Append in new tracks} or you will write over your current work. But if you make this mistake, you can use the Edit pulldown and Undo that! \begin{enumerate} \item Once the new video is on the track below your current work, you want to work with only this new @@ -194,11 +194,11 @@ There may be sections of your media that you want to delete, or audio that is ha window to the right of the transport buttons, are action buttons and as you mouse over them a yellow colored tooltip explains its purpose. Find the one that says \textit{To clip} which is on the right hand side of the right bracket symbol. - \item Click on \texttt{To clip} and a small window comes up which you can comment in, but you do not have + \item Click on \textit{To clip} and a small window comes up which you can comment in, but you do not have to, so just click on the green checkmark and now you will have a clip. \item Disarm that new track and re-arm your original tracks so you can go back to working on them \item Move your cursor to the spot in your original video where you want to insert the clip. Make a - \textit{Split} with the \texttt{Split | Cut} option. + \textit{Split} with the \textit{Split | Cut} option. \item Go to the Resources window and under the word Visibility, highlight \textit{Clips} so you can see your recently created clip in the box to the right. Highlight that clip and drag it to where you did the blade cut and drop it in. @@ -221,11 +221,11 @@ There may be sections of your media that you want to delete, or audio that is ha usual with left mouse click on the timeline and drag to the end of the desired area. \begin{enumerate} \item Right click on the brown colored bar that appeared below your video track to get to options and - then left click on \texttt{Show} to get the Title window to appear. + then left click on \textit{Show} to get the Title window to appear. \item Now for the fun part. First type in some words in the bottom large text box just to see what it does. There are so many variable parameters here and they are a lot of fun to play around with. \item You can dismiss the Title window when finished BUT be sure to leave the brown colored Title bar - on the track. And if you enabled the “drag” feature, you should disable it so you do not forget. + on the track. And if you enabled the \textit{drag} feature, you should disable it so you do not forget. \item Right mouse click on the bottom Text box to see many more interesting parameters. \end{enumerate} \end{enumerate} @@ -233,7 +233,7 @@ There may be sections of your media that you want to delete, or audio that is ha \subsection{Back up your work}% \label{sub:backup_your_work} -At this time, or even earlier if you think you might make a mistake or if you are concerned about computer crashes, you should save your work. Use the \textit{File} pulldown, and you can use \texttt{Save as} to designate a directory and filename. Then click the green checkmark. You are saving the EDL which is the set of changes that you have made -- this file is separate from your original media. +At this time, or even earlier if you think you might make a mistake or if you are concerned about computer crashes, you should save your work. Use the \textit{File} pulldown, and you can use \textit{Save as} to designate a directory and filename. Then click the green checkmark. You are saving the EDL which is the set of changes that you have made -- this file is separate from your original media. \subsection{Create your new media}% \label{sub:create_new_media} @@ -254,7 +254,7 @@ At this time, or even earlier if you think you might make a mistake or if you ar the menu. Then click on the wrench for Video and check Pixels by using the down arrow to the right to be yuv420p -- this is most commonly usable option. And click on the green checkmark. \item Check the Insertion Strategy in the Render Menu window. You might want to change that to - a different strategy than the default of \texttt{Append in new tracks}. If not, then when the Render is done, + a different strategy than the default of \textit{Append in new tracks}. If not, then when the Render is done, your new video will automatically be loaded in another set of tracks below your work tracks. Click on the green checkmark in the lower left corner to start the render. \item As the render is running, you will see the video play by in the Compositor. Rendering is usually @@ -287,16 +287,16 @@ To create a youtube or dailymotion video, you can easily follow the steps below. highlighting the \textit{Title} icon and dragging it to the Program window video track and dropping. \item Click on the middle icon button (looks like a magnifying glass) on the brown colored Title bar to bring up the Title window bottom text box and key in a title. - \item Use the \textit{File} pulldown to select \texttt{Render} to create the desired video. In the \textit{Render} window just next to the empty box to the right of the \texttt{ffmpeg} file format, click on the down arrow shown there - to see the choices and pick \texttt{youtube}. Then move back up to key in the path and filename to render + \item Use the \textit{File} pulldown to select \textit{Render} to create the desired video. In the \textit{Render} window just next to the empty box to the right of the \textit{ffmpeg} file format, click on the down arrow shown there + to see the choices and pick \textit{youtube}. Then move back up to key in the path and filename to render to. It will pick all of the defaults automatically for you so then just click on the green checkmark to have it start. There is a progress bar in the main window, very bottom of the right hand side. \item Key in “q” in the main window to get out of Cinelerra and yes or no to save your edit session. \end{enumerate} -Youtube will allow the upload of the resulting rendered file as named. However, Dailymotion requires that the file be named with an acceptable extension so you must rename the output file to have the extension of \texttt{.webm} instead of \texttt{.youtube}. +Youtube will allow the upload of the resulting rendered file as named. However, Dailymotion requires that the file be named with an acceptable extension so you must rename the output file to have the extension of .webm instead of .youtube -There are currently 6 specific variations within the ffmpeg (file format) / youtube (file type) for different video options. You see these when you click on the wrench to the right of the word Video and then the Compression down arrow in the Video Preset window. The first 3 are based on Webm/Vp9 (credit Frederic Roenitz) and contain basic comments of usage and where to find more information. +There are currently 6 specific variations within the ffmpeg (file format) / youtube (file type) for different video options. You see these when you click on the wrench to the right of the word Video and then the Compression down arrow in the Video Preset window. The first 3 are based on Webm/Vp9\protect\footnote{credit by Frederic Roenitz} and contain basic comments of usage and where to find more information. The first 3 below, plus any of the VP9 files under the file type of \textit{webm} are the recommended options to use because they are freely usable in any circumstance. @@ -308,7 +308,7 @@ The first 3 below, plus any of the VP9 files under the file type of \textit{webm \end{tabular} \end{center} -Alternatives based on h264 and for non-commercial use are listed below. For Dailymotion, these must be renamed to have a different extension of \texttt{.mp4} instead of \texttt{.youtube} before uploading. +Alternatives based on h264 and for non-commercial use are listed below. For Dailymotion, these must be renamed to have a different extension of .mp4 instead of .youtube before uploading. \begin{center} \begin{tabular}{l p{8cm}} diff --git a/parts/Tips.tex b/parts/Tips.tex index 6fe12f2..2d97a2b 100644 --- a/parts/Tips.tex +++ b/parts/Tips.tex @@ -4,8 +4,8 @@ Performance of Cinelerra is 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 or 4k. Adding effects and multiple tracks will require more cpu, memory, and various other resources to perform at an acceptable level. -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. +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 \textit{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 computer hardware factors to consider for better performance are listed here: \begin{itemize} @@ -23,7 +23,7 @@ Besides the above hardware recommendations, this section covers tips for perform \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} +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 \href{sub:gpu_hardware_encoding}{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. @@ -36,9 +36,9 @@ performing the operations in the hardware may actually be slower than in softwar \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 Verify that you have installed \textit{libva-dev} or \textit{libva} on your operating system. + \item Verify that you also have \textit{libvdpau-dev} or \textit{libvdpau} installed. + \item Verify \texttt{Settings $\rightarrow$ Preferences, Playback} tab, Video Driver is set to\textit{ X11} -- or \textit{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} @@ -58,7 +58,7 @@ export CIN_HW_DEV=vaapi 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. -There is also a \texttt{Settings $\rightarrow$ Preferences, Performance tab, Use HW device} flag +There is also a \texttt{Settings $\rightarrow$ Preferences, Performance} tab, \textit{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: @@ -67,7 +67,7 @@ Precedence of the decode hardware acceleration settings are: -- environment variable \texttt{CIN\_HW\_DEV} is checked next --- preferences \texttt{Use HW device} settings is of the lowest priority +-- preferences \textit{Use HW device} settings is of the lowest priority \subsubsection*{Hardware decoding in Cinelerra GG}% \label{ssub:hardware_decoding_cinelerra} @@ -75,7 +75,7 @@ Precedence of the decode hardware acceleration settings are: 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 + \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}. @@ -96,7 +96,7 @@ Due to variations in user’s computer hardware configuration, it is often sugge \begin{enumerate} \item The Frames Per Second (FPS) in playback might usually be at the maximum rate. You can check - this in \texttt{Settings $\rightarrow$ Preferences, Playback A}, looking at \texttt{Framerate achieved}; the higher, the better. + this in \texttt{Settings $\rightarrow$ Preferences, Playback A}, looking at \textit{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. @@ -133,7 +133,7 @@ cin_hw_dev=vdpau 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. +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 \textit{loglevel=fatal} to your .opts file. \subsubsection*{To verify hardware acceleration}% \label{ssub:verify_hardware_acceleration} @@ -158,7 +158,7 @@ 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: +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 \textit{loglevel =fatal} to \textit{loglevel =verbose} and restarting Cinelerra. Then you will see messages in the startup window like: \begin{lstlisting}[language=bash,numbers=none] [AVHWDeviceContext @ 0x7fc9540be940] Successfully created a VDPAU device @@ -174,7 +174,7 @@ 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}: +\noindent X11 Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab: \begin{center} \begin{tabular}{lcr} @@ -184,7 +184,7 @@ Some mixed preliminary results that have been reported are provided below. \end{tabular} \end{center} -\noindent X11-OpenGL Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A tab}: +\noindent X11-OpenGL Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab: \begin{center} \begin{tabular}{lcr} @@ -200,7 +200,7 @@ better than using the X11 video driver. \subsubsection*{Case 2:}% \label{ssub:case_2} -\noindent X11 Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A tab}: +\noindent X11 Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab: \begin{center} \begin{tabular}{lcr} @@ -210,7 +210,7 @@ better than using the X11 video driver. \end{tabular} \end{center} -\noindent X11-OpenGL Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A tab}: +\noindent X11-OpenGL Video Driver set in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab: \begin{center} \begin{tabular}{lcr} @@ -225,7 +225,7 @@ than using the X11-OpenGL video driver. 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: -\small \url{https://download.nvidia.com/XFree86/Linux-x86_64/304.137/README/supportedchips.html} +{\small \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. @@ -299,7 +299,7 @@ profile=high \begin{figure}[htpb] \centering - \includegraphics[width=0.8\linewidth]{images/render-vaapi.png} + \includegraphics[width=0.7\linewidth]{images/render-vaapi.png} \caption{Render menu setup to encode using GPU with vaapi} \label{fig:render-vaapi} \end{figure} @@ -308,7 +308,7 @@ According to an online wiki, hardware encoders usually create output of lower qu 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 the Appendix (\ref{sec:Ydiff to check results}) shows no obvious defects. +using \texttt{ydiff} as described in the Appendix (\ref{sec:ydiff_check_results}) shows no obvious defects. \begin{center} \begin{tabular}{l|cccc} @@ -358,19 +358,21 @@ CUDA® is a parallel computing platform / programming model developed by Nvidia 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: +The same as for vaapi and vdpau, you can enable Cuda in the:\\ +\texttt{ Settings $\rightarrow$ Preferences, Performance} tab, \textit{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/} + such as Fedora, OpenSuse, CentOS, Ubuntu, $\dots$ at {\small \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}). +There are currently 4 available plugins for \textit{show and tell} that take advantage of the hardware acceleration of Cuda -- \textit{N\_Body} and \textit{Mandelbrot} as shown next (figure~\ref{fig:cuda-effects}), \textit{F\_scale\_cuda} and \textit{F\_yadiff\_cuda}. \begin{figure}[htpb] \centering @@ -397,7 +399,7 @@ An error you may see on your Cinelerra startup window when you have Cuda install 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} +{\small \url{https://wiki.archlinux.org/index.php/Hardware_video_acceleration}} \section{Optimized Playback -- X11 Direct}% \label{sec:optimized_playback} @@ -405,7 +407,7 @@ In wrapping up this Hardware Acceleration section, you may want to refer to the 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}. +\texttt{Settings $\rightarrow$ Preferences, Playback A} tab set video driver to X11 and uncheck \textit{use direct X11 render if possible}. \section{Proxy Settings and Transcode}% @@ -413,7 +415,7 @@ With the X11 video driver choice, large format files such as 4K, will playback f 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. -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. +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 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 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. The assets in both the Media folder and Proxy folder will look proxied when dragged to the Viewer although the scale may be different. 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. @@ -423,10 +425,10 @@ And you can save your project either as proxied or not. You can also nest clips while in a proxied state, but you can not drag the proxied nested clips to the viewer or the timeline. -If you create proxies for Nested clips they will be saved in \$HOME/Videos unless you modify that in -\texttt{Settings $\rightarrow$ Preferences, Interface tab}, Nested Proxy Path. +If you create proxies for Nested clips they will be saved in \texttt{\$HOME/Videos} unless you modify that in +\texttt{Settings $\rightarrow$ Preferences, Interface} tab, \textit{Nested Proxy Path}. -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. +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 \textit{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. @@ -436,12 +438,12 @@ 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} + \includegraphics[width=0.6\linewidth]{images/proxy-02.png} \caption{Proxy settings dialog} \label{fig:proxy-02} \end{figure} -There is also a convenient \texttt{Beep on done volume} dial included so that you can work on other tasks until there is an audible notify of completion. The default volume is set to 0 for no audible notify. +There is also a convenient \textit{Beep on done volume} dial included so that you can work on other tasks until there is an audible notify of completion. The default volume is set to 0 for no audible notify. A good choice for proxy settings with 1080p source video is: @@ -464,13 +466,13 @@ 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}$. +Or if you want small files with high image quality, a File Format of 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}. +Checking the \textit{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 \textit{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. +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 \times 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. This makes its so that you can save your project either as proxied or not. @@ -478,24 +480,21 @@ either as proxied or not. \textbf{Transcode}, an option under the Settings pulldown right next to the Proxy settings option, is a type of full resolution \textbf{1:1 Proxy}. The process of transcoding works directly from the resource; it is independent of the timeline. All of the loaded asset media will be converted, that is, rendered in the selected format and loaded onto the timeline. -Menu choices besides the usual File Format and File Type include: Tag suffix (to add to media filename), Remove originals from project, Into Nested Proxy directory - (an option to have the file saved here instead of the location of the original media), and Beep on done volume. +Menu choices besides the usual File Format and File Type include: \textit{Tag suffix} (to add to media filename), \textit{Remove originals from project}, \textit{Into Nested Proxy directory} (an option to have the file saved here instead of the location of the original media), and \textit{Beep on done} volume. The settings of the project have an effect, for example the dimensions are taken into account. The resulting files are also larger than if they were created directly with ffmpeg. Transcode works for videos with or without audio and even single frame files, like png's. -If you have a video file that also contains audio, and you convert only the video, the original audio will stay on the timeline if do not check "Remove originals from project". Or vice versa if audio converted and not video. +If you have a video file that also contains audio, and you convert only the video, the original audio will stay on the timeline if do not check \textit{Remove originals from project}. Or vice versa if audio converted and not video. Multiple stream media will only transcode the first stream (this would be like the TV channel recordings in the United States). -You will get an error message if you already have a transcoded file in the selected format with the same suffix name and try to transcode it again with a different selection made - you will have to delete that file first. An example would be +You will get an error message if you already have a transcoded file in the selected format with the same suffix name and try to transcode it again with a different selection made -- you will have to delete that file first. An example would be an already converted file that has both video and audio and now you request video only. -The BIGGEST gain from using this is if you have media that is not "seekable", that is, you can play it from the beginning -but can not move to another spot and have the audio or video play correctly. A video file with no keyframes makes seeking -next to impossible, but then a Transcode generally adds these keyframes. +The BIGGEST gain from using this is if you have media that is not \textit{seekable}, that is, you can play it from the beginning but can not move to another spot and have the audio or video play correctly. A video file with no keyframes makes seeking next to impossible, but then a Transcode generally adds these keyframes. \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. +\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. @@ -506,8 +505,8 @@ A list of items to check for smaller computers that will help to use less cpu/me \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 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}. @@ -517,7 +516,7 @@ A list of items to check for smaller computers that will help to use less cpu/me 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. + \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}% @@ -527,8 +526,8 @@ This section is a handy guide for describing various kinds of software computer \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_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[Cinelerra crash:] This is covered in \href{cha:crash_dumps_analysis}{Crash Dumps for Analysis}. 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 Ctrl-Alt-F1 $\dots$ Ctrl-Alt-F7 (etc.) will allow you to regain control of a VT console. You can use this to login and check logs: eg. \texttt{/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} @@ -559,7 +558,7 @@ 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}). +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 (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: @@ -569,7 +568,7 @@ Modal forms (always on top, and usually ptr/kbd grab) dialog boxes can lock a sy 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. + The ALT and META keys may be intercepted by the window manager, and this can cause unexpected interface operations. \end{description} \section{Tips for Specific Operations}% @@ -583,14 +582,14 @@ To create a specific 440 Hz tone, follow these steps. You can vary the length, \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 + \item Go to \texttt{Audio $\rightarrow$ Render effect}. Rendered effect usage is described in \href{sec:rendered_effects}{Effect Plugins}. 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 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 + \item Highlight the \textit{exprs} option and key in a specific audio filter expression which for 440 Hz would be: + $\sin(2\pi t\times440)$. Then hit the Apply button. + \item Next when you hit the green 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 + \item To use 2 channels instead of 1, in the F\_aeval menu highlight the \textit{channel\_layout} option and change that to 1C|2C instead of the usual default of 1C. \end{enumerate} @@ -604,7 +603,7 @@ To create a specific 440 Hz tone, follow these steps. You can vary the length, \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: +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 .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. @@ -614,7 +613,7 @@ A LUT, acronym for Look-Up Table, is a mathematically precise way of taking spec \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. +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 \textit{file} option, key in your file name (whit path), and hit apply to have the lut take effect. To easily adjust, move the \textit{fader} slider in the patchbay for that video track. \subsection{Encoding into Dolby Pro Logic}% \label{sub:encoding_dolby_pro_logic} @@ -649,7 +648,7 @@ Other tricks you can perform to separate the speakers are parametric equalizatio 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: +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 \texttt{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,numbers=none] Horizontal: 2 @@ -667,14 +666,14 @@ Use the Camera in the compositor to shift the picture up or down a line to remov \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. +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 \textit{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[Line Doubling:] done by the \textit{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 \textit{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[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 \textit{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} @@ -685,8 +684,8 @@ With an older camcorder video which has low quality video, you can improve the r \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 + \item Apply a \textit{Sharpen} effect. Set it to sharpness: 25, no interlacing, and horizontal only. + \item Drop a \textit{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 @@ -721,11 +720,11 @@ It is important to set the $0\%$ alpha color to blue even though it is $0\%$ alp \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 Right click on track Audio 1 and select \textit{Attach effect}. Highlight the \textit{Compressor} effect and hit + 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 Right click on track Audio 2 and select \textit{Attach effect}. + \item Highlight Audio 1 Compressor and hit 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,numbers=none] diff --git a/parts/Translations.tex b/parts/Translations.tex index d2f5705..ded6a2b 100644 --- a/parts/Translations.tex +++ b/parts/Translations.tex @@ -1,7 +1,7 @@ \chapter{Translations}% \label{cha:translations} -There are several \textit{po} files for various languages to make Cinelerra more usable for non-English countries. A program, \texttt{xlat.C}, assists in providing several variations of text files that can be used in order to allow anyone to help make meaningful translations. All of the \textit{po} files are located in Cinelerra’s \texttt{/po} subdirectory. There are 3 different ways to proceed described below. +There are several \textit{po} files for various languages to make Cinelerra more usable for non-English countries. A program, \textit{xlat.C}, assists in providing several variations of text files that can be used in order to allow anyone to help make meaningful translations. All of the \textit{po} files are located in Cinelerra’s \texttt{/po} subdirectory. There are 3 different ways to proceed described below. Because Cinelerra frequently is changing, it is a good idea to start by building a new \texttt{cin.po} file which contains the latest messages/words in English to be translated, along with a comment line of the routine name and line number. To create this, run the following lines from a window: @@ -11,7 +11,7 @@ cd /{your top level cinelerra directory} \end{lstlisting} \begin{description} - \item[Method 1] use the freely-available \textit{poedit} program to provide translations to the current \texttt{xx.po} where xx is your language such as fr.po, de.po, ru.po, etc. The drawback to this is that xx.po files are not recreated monthly so they do not have all of the newest phrases included. + \item[Method 1] use the freely-available \textit{poedit} program to provide translations to the current \textit{xx.po} where xx is your language such as \texttt{fr.po}, \texttt{de.po}, \texttt{ru.po}, etc. The drawback to this is that \textit{xx.po} files are not recreated monthly so they do not have all of the newest phrases included. \item[Method 2] using \textit{msgmerge} is probably the simplest method for user translation. \end{description} @@ -30,7 +30,7 @@ Then use any editor or poedit to provide messages/words translations in the new \item[Method 3 ] using \textit{xlat.C} program is the most versatile with a variety of features. When a non-existent language translation is first set up, you would want to use this methodology to get started. \end{description} -To use the xlat.C program, first compile it with “c++ xlat.C”. You can see the usage help here: +To use the \textit{xlat.C} program, first compile it with \texttt{c++ xlat.C}. You can see the usage help here: \begin{lstlisting}[language=bash,numbers=none] ./a.out @@ -50,7 +50,7 @@ This program has 6 commands where the desired command is the first parameter to \item \textit{po} = convert po to csv data; for example, what you need to convert ru.po to ru.csv. You can even open the resulting *.csv in LibrOffice and update the \textit{key $\rightarrow$ value} replacements (fields separated by "," only and check quoted fields as text during import). These results can - be \textit{Saved As} a csv file, and then used by xlat.C to reformulate a \texttt{po}. + be \textit{Saved As} a csv file, and then used by xlat.C to reformulate a \textit{po}. \item \textit{dups} = list only key/value items where either the \textit{key=value} or \textit{value=" "}. \item \textit{nodups} = list only key/value items where \textit{key$\ne$value} and \textit{value$\ne$" "}. \item \textit{key} = list cin.po key set. @@ -67,7 +67,7 @@ c++ xlat.C ./a.out xlat cin.po /tmp/es.csv > /tmp/new_es.po \end{lstlisting} -The first run preserves the existing mapping of es.po, the second creates new mappings from cin.po, and the third merges the original and new mappings to create a po with new included/overriding es.po. +The first run preserves the existing mapping of \texttt{es.po}, the second creates new mappings from \texttt{cin.po}, and the third merges the original and new mappings to create a po with new included/overriding \texttt{es.po}. \paragraph{NOTE:} some words and abbreviations can lead to ambiguous language translations. Therefore, the usage of C\_ and D\_ in the program code was added to represent Contextual and Definitional exceptions to the usual \_ and N\_ . You will see the following: