--- /dev/null
+\documentclass[
+a4paper,
+12pt,
+oneside,
+svgnames,
+%draft
+]{memoir} % paper size, font size and other options for document
+\input{common/packages.tex} % common packages
+\input{common/settings.tex}
+
+%\includeonly{common/title,parts/Installation}% ,parts/Introduction,parts/Windows
+
+\begin{document}
+
+\input{parts/Anamorphic_title.tex} % create and use custom title page
+
+\thispagestyle{empty} % no page numbers
+% \newpage
+\setlength{\parskip}{1\baselineskip}
+\frontmatter
+
+\tableofcontents
+
+\pagestyle{ruled}
+
+\mainmatter%
+
+\include{parts/Anamorphic}
+
+\newpage
+
+\pagestyle{ruled}
+
+% \listoftodos
+
+\end{document}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% End:
\include{parts/Tips}
\include{parts/Translations}
\include{parts/Licenses}
+\include{parts/AUTHORS}
\chapter*{Appendices}
\addappheadtotoc
--- /dev/null
+\documentclass[
+a4paper,
+12pt,
+oneside,
+svgnames,
+%draft
+]{memoir} % paper size, font size and other options for document
+\input{common/packages.tex} % common packages
+\input{common/settings.tex}
+
+%\includeonly{common/title,parts/Installation}% ,parts/Introduction,parts/Windows
+
+\begin{document}
+
+\input{parts/Preserving_title.tex} % create and use custom title page
+
+\thispagestyle{empty} % no page numbers
+% \newpage
+\setlength{\parskip}{1\baselineskip}
+\frontmatter
+
+\tableofcontents
+
+\pagestyle{ruled}
+
+\mainmatter%
+
+\include{parts/Preserving}
+
+\newpage
+
+\pagestyle{ruled}
+
+% \listoftodos
+
+\end{document}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% End:
% in the first 128 positions. This is an
% English language document.
\usepackage[utf8]{inputenc} % file encoding
-\usepackage{substitutefont} % so we can use fonts other than those specified in babel
+% \usepackage{substitutefont} % so we can use fonts other than those specified in babel
\usepackage[english]{babel} % default language for document
% Cyrillic - if it is used, no Small Caps are available:
%\usepackage[scaled=0.925]{XCharter} % Подключение русифицированных
% The following is an example that needs to be adapted to the
% respective conditions.
%
-Maintained and published by Phyllis Smith\\[+1.2em]
-Copyright~\copyright{} 2022 The \CGG{} Community\par
+Maintained and published by Phyllis Smith (phylsmith2017@gmail.com)\\[+1.2em]
+Copyright~\copyright{} 2023 The \CGG{} Community\par
Please report errors in the book to our \href{https://www.cinelerra-gg.org/bugtracker/}{bug tracker} or the \href{https://www.cinelerra-gg.org/forum/}{user forum}\par
% Contributing authors: \textsc{Phyllis Smith, Andrea Paz, Andrey}\par
Graphic cover page: \textsc{Sam}, License
--- /dev/null
+\chapter{Authors and Contributors}%
+\label{cha:contributors}
+\index{Authors}
+\index{Contributors}
+
+\textbf{Adam Williams} - wrote the original complete Cinelerra package Copyrighted under GPL and continues to release new versions yearly; this is the HV version <broadcast@earthling.net> .
+
+Sam - designed and engineered the \CGG{} website and continuously maintains and updates the Operating system and applications.
+
+Willam Morrow - was responsible for the current \CGG{} software version which emphasized crash-free stability; he started adding fixes and features in 2007, merged his version based on the HV version with the CV version in 2016, continued to add new features and fixes and incorporate desirable updates from HV and CV until November 2020.
+
+Software developers working on \CGG{} since at least 2021 along with some areas where they have been crucial (in alphabetical order by first name):
+\begin{itemize}
+ \item Andrew Randrianasulu - continuous ongoing support; bug fixes; library upgrades with relevant patches; some nice enhancements; created and debugged builds: NetBSD and the Android tablet using Termux.
+ \item Andras Reuss - created very useful Autosave backup feature in Preferences with Andrew assist.
+ \item Georgy Salnikov - added all of the Help software in the program allowing access to HTML manual pages; major improvement in the Motion plugin; provided scripts and program mods to convert Latex manual to HTML.
+ \item Manuel Virgil - DPX list writer developer; EXR package upgrade to 3.1.4 (not currently in use).
+ \item Mat Nieuwenhoven - creator of the AppImage build procedure; LV2 specific control patch; maintains \CGG{} wikipaedia entry.
+\end{itemize}
+
+Personnel providing current recent testing, examples, demos, and work on the manual or distribution packages for the \CGG{} version (in alphabetical order by first name):
+\begin{itemize}
+ \item Andrea Paz - main person who keeps the Manual updated; does builds for early testing of changes; provides examples and demos.
+ \item Andrey Spitsyn - responsible for the huge task of getting the \CGG{} Manual in LaTex. And for the current build farm at \url{https://github.com/einhander/cin-gg-packages/releases}.
+ \item DeJay - expert user and frequent responder to users in the Forum.
+ \item Glen MacArthur - provides A/V Linux distro which includes \CGG{}.
+ \item Pierre Autourduglobe - designed and thoroughly tested Interview Mode for implementation; major tester of Mixers; provided reason for getting the Shuttle to work; tested other new features.
+ \item Phyllis Smith - facilitator of checking into GIT the developers and contributors changes to the Programs and to the Manual; tester; creates monthly AppImages when needed.
+ \item RafaMar - updated Spanish translations; instrumental in getting friend's help in adding the Help button to the Batch Render menu; provided additional ShapeWipe transitions.
+ \item Terje Hanssen - especially tests Bluray video media creation providing invaluable feedback.
+\item \textbf{+ many others}, some of who wish to remain anonymous.
+\end{itemize}
+
+Software Developers in the earlier years of \CGG{} (alphabetical by last name):
+\begin{itemize}
+\item Balakhnin, Alexander - author of the Descratch plugin.
+\item Messick, Eric - provided the initial Shuttle code (FixedImagePhoto.com/Contact).
+\item Olaf - Cakewalk and Neophyte theme developer - Cakewalk is the default theme due to its being modern; tested and provided much feedback.
+\item Roenitz, Frederic - wrote the VP8/VP9 render formats.
+\end{itemize}
+
+Contributors and Software Developers through the years either on HV or CV, the Community Version. They are listed by last name in
+ alphabetical order, along with some of their specific expert work - often just a single known item listed, and it may not even have been the most important when they obviously did so much more. The CV developers were
+responsible for many improvements based on the HV version to include bugfixing, creating build systems,
+internationalization work, plugins, and IIRC ffmpeg support appeared in one of the CV forks.
+\begin{itemize}
+\item Arendt, David - early tester providing significant feedback.
+\item Basto, EaSergio M. - completely replaced/fixed autogen.sh; removed old outdated fonts.
+\item Baverstock, Richard - assisted with working on the SVG plugin; added tape controls in the capture monitor window; major early tester and contributor.
+\item Bielefeldt, Karl - created gradient wipe plugin; worked on outdated mpeg2enc.
+\item Brosius, Kevin - provided many patches, for example fixed scroll bar resizing in bclistbox.C; major early contributor.
+\item Cornet, Jerome - updated Deinterlace plugin for temporal field swap.
+\item Coulon, Jean-Luc - updated French translation; provided patches for translation gettextization strings.
+\item Delannoy, Florent - C41 plugin to convert a 16 bit C41 digital intermediate negative file to positive image.
+\item Diniz, Rafael - worked on the Brazillian Portuguese translation; created Slackware packages.
+\item Dumuid, Pierre - assisted in merge efforts; added column in File Load dialog box for sorting by extension; wrote Selective Temporal Averaging plugin.
+\item Erdelyi, Georgely - early on provided patches for libsndfile, titler, and other programs to compile on Suse.
+\item Ferralis, Nicola - updated Ubuntu PPA over many years; along with Slock Ruddy, responsible for GreyCStoration plugin (currently inactive in \CGG{}), worked on Italian translation.
+\item Ferrer, Alex - originally put up a Cinelerra manual TWiki; maintained the wiki.
+\item Flaming, Benjamin - created the Diffkey plugin.
+\item Geddes, Tyler - contributed to CV Version.
+\item Harang, Camille - worked on fixing guicast programs for big Endian; part of small team of 3 that used Cinelerra to make short documentaries/interviews.
+\item Heen, Tollef Fog - contributed to CV Version.
+\item Iniguez, Gustavo - contributed to HV version.
+\item Joyeux, Sylvain - worked on the UI; worked on configuration/build scripts.
+\item Kielb, Andreas - created Firewire I/O patches.
+\item Konink, Stefan de - added patch for playing without sound.
+\item Kurz, Nathan - added a YUV4MPEG pipe output dialog to the user interface; yuvstream.C program developer; early contributor.
+\item Maufrais, Nicolas - collaborated on the Cinelerra-CV manual.
+\item Mekkes, Greg - added patch to Motion Blur plugin.
+\item Menk, Michael Eric - contributed to CV Version.
+\item Montgomery, Monty - Blue Banana color modification plugin; fileffmpeg developer in CV fork.
+\item Mueller, Johannes - author of keyboard tracks up/down shortcut and horizontal scrolling with the mouse wheel.
+\item Muylkens, Koen - created the Blue Dot theme.
+\item Olson, Eric - added YUV411 plugin to improve chroma upsampling results for DV source.
+\item Pesegov, Valentin - added Russian translation.
+\item Poure, Jean-Michel - provided fixes in build procedures for Debian; first entry in Mailing List September 2004.
+\item Rampino, Paolo - aka Akirad, created several colorful/artistic themes; developer of the cinecutie fork (now inactive); worked on Italian translation.
+\item Reinholdtsen, Petter - assisted in early hardware upgrade; core developer; moved over new features from HV to CV; fixed many, many bugs.
+\item Robak, Herman - created initial draft repositories; major early contributor.
+\item Runkaru, Einar - numerous bug fixes; for a long time maintaned a separate branch and currently has his own personal CVE fork; noted first entry in Mailing List in January 2010.
+\item Schmarsel, Danny - past website designer and administrator for Cinelerra-CV website; created Cinelerra LiveDVD for Slackware (now inactive); provided German translation.
+\item Seigne, Eric - initial French translation.
+\item Setti, Riccardo - contributed to CV Version.
+\item \textbf{Sixt, Johannes - long time contributor from early on and continuous}; notable for merging into Cinelerra-CV the new releases of HV.
+\item Stewart, Joe - worked on Inkscape for Cinelerra; created Motion Blur plugin.
+\item Streetman, Dan - developed patch to correct text\_to\_seconds; added patch to Titler for timecode functionality; patches to ReframeRT.
+\item Taraba, Mark - provided support for all types of PNGs; first Mailing List entry in August 2004.
+\item Thaeter, Christian - maintained server to host Cinelerra-CV website.
+\item Tori, Andraz - responsible for Cinelerra x86 Debian packages; worked on an SVG plugin; added overlaying speedup patch; major early contributor and lots of debugging.
+\item Traniello, Raffaella - best known for "Cinelerra for Grandma" still active at \url{http://g-raffa.eu/Cinelerra/HOWTO/basics.html} .
+\item Vladimirsky, Igor - was igor\_ubuntu at one time; developer of the Russian po file; currently supports the Cinelerra-CV site; and much, much more work; noted first entry in Mailing List 2014.
+\item Vosseler, Hermann - developer of the Reroute plugin used to transfer the Alpha
+channel and/or the RGB/YUV Components from source track to target track; significant
+Bezier automation patch for fades, camera and projector.
+\item Wulff, Jonas - patched Histogram plugin to provide a split output screen.
+\newline
+\item \textbf{+ many others}.
+\end{itemize}
\label{sec:proxy}
\index{proxy}
-Proxies was introduced to allow for a smoother timeline experience. Full HD and everything from 4K size up are usually very large in file size. In addition, some commonly used codecs (e.g. h264/5) are very compressed and interframe type, so they are more stressful for timeline playback. These files cause performance problems on weaker PCs. As a solution the developers have introduced proxies to reduce the file size. Reduced means to minimize the resolution/dimension, as usually not the full resolution is needed, because the compositor usually takes only a fraction of the computer screen. Therefore the scaling factor, which indicates how much the original resolution should be reduced.
-There is also the \textit{proxy 1:1} \index{proxy!1:1} that maintains the original resolution but still allows you to act on the codec (lowering the bit rate, for example). See also next section: \ref{sec:transcode}.
-When we want to render the project, remember to remove the proxy to return to the original settings with the highest quality.
+Proxies were introduced to allow for a smoother timeline experience. Full HD and everything from 4K size up are usually very large in file size. In addition, some commonly used codecs (for example h264/5) are very compressed and interframe type, so they are more CPU intensive for timeline playback. These files cause performance problems on smaller computers. As a solution, proxies were introduced to reduce the file size. Reduced means to minimize the resolution/dimension, as usually not the full resolution is needed because the compositor generally occupies only a fraction of the computer screen. The proxy provides a scaling factor which indicates how much the original resolution should be reduced.
+There is also the \textit{proxy 1:1} \index{proxy!1:1} option that maintains the original resolution but still allows you to modify codec parameters (lowering the bit rate, for example). This is explained in the next section, \ref{sec:transcode}.
+Always remember when getting ready to render the project, disable Proxy to return to the original settings with the highest quality.
-To use the proxy in a classic way, i.e. as a scaling, 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 \index{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.
+To use proxy select \texttt{Settings $\rightarrow$ Proxy settings} on the main window. You can choose ffmpeg as the \textit{File Format} \index{file format} and for the \textit{File Type} a choice of various codecs associated with that. A good choice for \textit{File Type} is the default of mpeg or mov which can usually be quite fast. In addition you can modify values for that codec by clicking on the wrench icon. Once you have created a
+proxy file, it will be reused and does not have to be created again as long as you
+do not change certain parameters. This saves a lot of CPU time.
-We can use the \textit{Proxy 1:1} in two ways: setting "1" as \textit{Scale factor}, or check the \textit{Rescaled to project size (FFMPEG only)} button. In this mode we don't have scaling, i.e. downsize, but only variations of the codec parameters that allow to maintain the original resolution. The advantage is that you can use filters that require the original size to work well. NB: if we set any scaling, by activating the \textit{Rescaled to project size (FFMPEG only)} button we automatically lose scaling and enter Proxy 1:1 mode.
+There are two main ways to use Proxy, with or without \textit{Rescaled to project size} option checked. The options of the \textit{Scale factor} may be different if \textit{Rescaled to project size} is checked versus unchecked. It is a special case when the \textit{Scale facto}r is set to "1" and it does not matter if \textit{Rescaled to project size} is checked or unchecked.
-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 usual steps to use Proxy are:
+\begin{enumerate}
+ \item Check that \textit{File Format} is set to \texttt{FFMPEG}.
+ \item Check or uncheck the \textit{Rescaled to project size} (FFMPEG only). The difference with this option will be explained here \ref{sub:rescaled_project_size_works}. But for old computers checking \textit{Rescaled to project size} is not recommended; again due to requiring more CPU. You need to know that when \textit{Rescaled to project size} is unchecked some Effects/Plugins do not work as expected because they use pixel values instead of percentage values as is used in the Project Format. For example \textit{Title}, \textit{Blur}, \textit{Sketcher} plugins do not work right if unchecked, while \textit{Perspective} and \textit{Crop\&Position} plugins work correctly for both checked and unchecked.
+ \item Choose the \textit{Scale factor}. The options may be different if \textit{Rescaled to project size} is checked or unchecked. The smaller the \textit{Scale factor} is, the smoother playing on the Timeline will be ($\frac{1}{8}$ is smaller than $\frac{1}{4}$), but on the Viewer/Compositor the image will be degraded/pixelated more.
+ \item Set the \textit{File Type} in the \textit{File Format} for FFMPEG, such as mp4, mpeg, or mov. Still images like jpg, tiff, and png will be converted to PNG files with alpha channel if it had an alpha channel.
+ \item Click on the wrench icon to configure video compression; just use the default values if you are unsure and prefer not to experiment.
+ \begin{enumerate}
+ \item Select the Compressor type (codec).
+ \item Change Bitrate, or Quality, and Pixels. Because not all codecs use the alpha channel for transparency, check that the letter "\textbf{a}" is in the Pixels name (such as yuv\textbf{a}420p or rgb\textbf{a}) to retain the alpha channel.
+ \item Click on the OK button to close the Compressor window.
+ \end{enumerate}
+ \item Now click on the \texttt{OK} button to start the rendering for the proxy.
+ \item Look in the lower right corner of the main window where there is a progress bar and a percentage value showing the progress of the creation of proxies, and in the lower left corner there is the \textit{Creating proxy files... ETA: hh:mm:ss} text with the "Estimated Time of Arrival (completion)" in hours, minutes, seconds. Depending on how many files your project uses, the file size, which codec is used, the scale factor, and cpu performance, creating proxies may take some time.
+\end{enumerate}
+
+You will know that Proxy mode is enabled because:
+\begin{itemize}
+ \item A white colored \textbf{P} meaning \textit{\textbf{P}roxy}, or a white colored \textbf{S} meaning \textit{Proxy \textbf{S}caled} icon is shown in the upper right corner of the main window to the left of the FF icon. If using the Cakewalk or Neophyte theme it will be a \textbf{Ps} icon.
+ \item The Proxy folder in the Resources window has been populated with the names and/or icons of the proxy media.
+ \item The edit title bar in the timeline will have the name of the proxy file instead of the original name. So if the video filename is \texttt{VID\_20221012.mp4}, the Proxy Scale Factor is $\frac{1}{4}$, and the Proxy container is mov, then the proxy name will be \texttt{VID\_20221012.proxy4-mp4.mov}.
+\end{itemize}
+
+The Proxy icon is a toggle button so that you just click on the icon to change modes. Or it can be toggled using the \texttt{Ctrl+R} shortcut.
+
+\begin{table}[ht]
+ \centering
+ \begin{tabular}{|p{2.5cm}|p{3.2cm}|p{3.2cm}|p{3.2cm}|}
+ \hline
+ {\footnotesize\textbf{Proxy State}} & {\footnotesize\textbf{Rescaled to project size (FFMPEG only)}} & {\footnotesize\textbf{Proxy icon for themes:
+ Cakewalk/ Neophyte}} & {\footnotesize\textbf{Proxy icon for themes: the Others}}\\
+ \hline
+ {\footnotesize{Off}} & {\footnotesize{checked/ unchecked}} & {\footnotesize{no icon}}
+ & {\footnotesize{no icon}}\\
+ \hline
+ {\footnotesize{Active (Enable)}} & {\footnotesize{checked}} & {\footnotesize{Ps: P(green) s(white)}}
+ & {\footnotesize{S (white)}}\\
+ \hline
+ {\footnotesize{Disable}} & {\footnotesize{checked}} & {\footnotesize{Ps: P(red) s(white)}} & {\footnotesize{S (gray)}}\\
+ \hline
+ {\footnotesize{Active (Enable)}} & {\footnotesize{unchecked}} & {\footnotesize{Ps: P(green) s(red)}} & {\footnotesize{P (white)}}\\
+ \hline
+ {\footnotesize{Disable}} & {\footnotesize{unchecked}} & {\footnotesize{Ps: P(red) s(red)}} & {\footnotesize{P (gray)}}\\
+ \hline
+ \end{tabular}
+ \caption{list States of the Proxy icon}
+\end{table}
+
+When you disable Proxy using the toggle button for Proxy, or its shortcut (\texttt{Ctrl+R}), in the Proxy Settings window you will see the \textit{Scale Factor = 1}, but if you look at the Active Scale and the State, you can understand what your setting is.
+Proxy can have three possible States: Off, Active, Disabled. The difference between Off and Disabled is that Disabled means you have set the Proxy and it is temporarily switched off (and you can see the icon in the upper right corner of the main window); you can enable proxy by just clicking on the icon, so the State will then be changed from Disabled to Active.
+
+\subsection{How Rescaled to project size (FFMPEG only) works}%
+\label{sub:rescaled_project_size_works}
+
+\begin{itemize}
+ \item When \textit{Rescaled to project size (FFMPEG only)} is checked, the size of the video data to be computed will always be the same as the Project Format. The size of your video is scaled down to the \textit{Scale factor} BUT then it is rescaled up to the Project Format. For example, your Project Format is 1920x1080 and Proxy's Scale factor is $\frac{1}{4}$, then your videos ($1920x1080$) will be scaled down to 480x270 and then up-scaled to $1920x1080$. All the Effects/Plugins work correctly because the original resolution/geometry/size is not changed. For an old computer, this option is not recommended.
+ \item When \textit{Rescaled to project size (FFMPEG only)} is UNchecked, the size of the video data to be computed will be reduced to the \textit{Scale factor}. The size of your video is scaled down to the \textit{Scale factor}. For example, your Project Format is 1920x1080 and Proxy's Scale factor is $\frac{1}{4}$, then your videos ($1920x1080$) will be scaled down to $480x270$. It works as if the Project Format were $480x270$ (and really it works). If you take a look at \texttt{Settings $\rightarrow$ Format...} when Proxy is enabled (Active), you can see that the Width and Height are changed according to the \textit{Scale factor}; you absolutely must NOT change these values! The good thing is that your computer will be faster. The bad thing is that some Effects/Plugins do not work as expected because they use pixel units. Examples are \textit{Title} and \textit{Blur} plugins. A workaround is needed for that, such as using Inkscape to create a title and export it to PNG that you load instead of using the \textit{Title} plugin.
+
+\end{itemize}
+
+Note: the dimensions of the frame/image are downscaled to the Scale factor; so if the Scale factor is $\frac{1}{4}$ and the dimension of the image is $4288x2848$ pixels, that image will be downscaled to $1072x712$. It doesn't matter what the Project Format is.
+
+\subsection{Using proxy}%
+\label{sub:using_proxy}
-The proxy videos will be added to your assets in a separate Proxy folder \index{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.
-However, if you proxy your session, the clips do not get proxied to the Proxy folder, but if you Drag and Drop the clip from the Clip folder to the Viewer or the Timeline, you will see that it too is proxied.
-As usual, you can delete proxy files from the project or disk in the Resources window if you no longer want to retain them.
-And you can save your project either as proxied or not.
+To insert a clip/video from Resources window to the Timeline when Proxy is enabled (Active) you MUST Drag \& Drop that clip/video from the Proxy folder instead of the Media folder, as well as for Nested clips. And also if you want to load the clip in the Viewer or Compositor. You can use clips in the Clips folder in any State of the Proxy - it does not matter if Proxy is enabled or disabled.
-Because Proxy works on the original media in all circumstances, when you resize the
-media in the Resources window, it does not actually resize the media but puts it in
-a \textit{buffer} in that format. This might lead to some confusion for the user who
-expects this resizing to be maintained when disabling Proxy for that media. However,
-that does not happen because the resize is only in a buffer and not in the original
-media. This result is different than in the case of media \textit{edits}, like cuts or adding plugins because this information is not in a buffer but rather part of the
-copy \textit{Editing Decision List} (EDL).
+Rendered proxy media is saved in the same directory as the original media. As usual, you can delete proxy files from the project or disk in the Resources window if you no longer want to retain them. You should \textbf{always save your project with the Proxy disabled}.
-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 \texttt{\$HOME/Videos} unless you modify that in
-\texttt{Settings $\rightarrow$ Preferences, Interface} tab, \textit{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}, \texttt{Interface tab}, \textit{Nested Proxy Path}. If you change anything in a Nested clip using the \textit{Open EDL} feature, you must first delete its old proxy file from disk because it is not updated automatically, and then enable Proxy again so that a new one is created.
-Let's examine in detail how Proxy and Proxy 1:1 modes work: when the proxy is done with downsize, the Mask, Camera and Projector automations are 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 scaled, because the keyframe data must be in the original geometry. In this case, you can use the il Proxy 1:1, by enabling \textit{Scale factor}=1. This has the added advantage that the project size does not change. The main reason for using \textit{Proxy 1:1} is that it does not change the image coordinate data, so that automation and plugin parameters will be in the original project geometry (e.g. Title plugin).
+Not all the settings for Proxy are saved in the project: the values of Active Scale and the \textit{Rescaled to project size} are saved but not the \textit{File Format}, \textit{File Type} and all video compression data. A good idea is to record this information in a README file about your project where you make a note of your Proxy settings for that project.
+This is especially important because some Projects may use different Proxy settings and
+if you load a project where the Proxy is set and disabled, it could use a different
+setting because you changed the Proxy settings in a project you were working on before.
+If in that Project its proxy files were not deleted and you want to reuse them to save
+time, unfortunately they will be created again because the proxy settings have changed.
-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 “Ps” as the icon for Proxy. \quad \includegraphics[height=\baselineskip]{proxy-01.png} \quad This quick switch is especially useful when editing and you need to see a better image temporarily.
-The "P" is green when the proxy is active and red when it is disabled. The "s" is white when in \textit{Proxy 1:1} mode and red when downsize.
+If the \textit{Creation of proxy on media loading} option has been checked, then when you load other media later, proxies will be created for them automatically, or else you can change the Proxy's State from disabled to enabled (Active) using the Proxy icon. Previous proxy renders will be reused unless you change one of the following proxy parameters: \textit{Scale factor}, \textit{File Format}, or \textit{File Type}. If proxies have been created and then you decide to change only the Compression type (Codec, Bitrate, Quality, Pixels), without changing the \textit{Scale factor} or Container, you must delete proxy files from the disk beforehand. That is because \CGG{} does not read the compression type; it does read the filename and if the filename does
+not change, \CGG{} thinks the proxy was already created.
+
+\subsection{Scale factor set to 1, a special case}%
+\label{sub:scale_factor_special_case}
+
+This special case is used to temporarily change the codec parameters of your video while maintaining the original resolution - for example maybe your videos use long-GOP or the video codec is too hard to handle due to a strong compression. It does not matter if \textit{Rescaled to project size} is checked or unchecked. For old computers, or underpowered computers, this option is not recommended.
+
+\subsection{Setting the proxy}%
+\label{sub:setting_proxy}
\begin{figure}[htpb]
\centering
\label{fig:proxy-02}
\end{figure}
-Screencast in figure~\ref{fig:proxy-02} shows the use scaled checked so you can still use plugins and the original project size is kept. The Scale factor pull-down gives you available size options. Note the new media dimensions shown (partially covered). If the size is an odd number, 1 is added to make the dimensions both even numbers.
+Screencast in figure~\ref{fig:proxy-02} shows the \textit{Rescaled to project size} checked so you can still use plugins correctly and the original project size is kept. The \textit{Scale factor} pull-down gives you available size options. Note the new media dimensions shown (partially covered). If the size is an odd number, 1 is added to make the dimensions both even numbers.
-To go back to the original media for good, simply take the Scale factor to Off. However, if we decide to reuse the proxies, these, which have not been deleted from the Hard Disk but only from the project, will still be used without making new rendering. To completely cancel the created proxies we will have to delete them manually from the Hard Disk.
+To go back to the original media permanently, simply set the \textit{Scale factor} to Off or disable the Proxy by clicking on its toggle button. However, if you decide to reuse the proxies, those which have not been deleted from the Hard Disk (but have been removed from the project) will be used without re-rendering - this saves a lot of time. To completely remove the created proxies you will have to delete them manually from the Hard Disk.
+There is also a convenient \textit{Beep on done volume} slider 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} bar 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 classic proxy settings with 1080p source video is:
+A good choice for classic proxy settings with a 1080p source video is:
\begin{lstlisting}[numbers=none]
Scale Factor: 1/4
Pixels: yuv420p
\end{lstlisting}
-If you get errors for some videos, such as those with strange variable bit rate or some types of files made on a smartphone, an usually reliable alternative is to change the following parameters:
+If you get errors for some videos, such as those with strange variable bit rate or some types of files made on a smartphone, a usually reliable alternative is to change the following parameters:
\begin{lstlisting}[numbers=none]
File Format: FFMPEG - mov
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 \textit{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 \textit{Creation of proxy on media loading} 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{Proxy 1:1}.
+If you get error messages \index{proxy!error} 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 \textit{Info} option for the 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.
-If you get error messages \index{proxy!error} 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.
+A faster method of creating the proxy file outiside of \CGG{} for users who have
+vaapi hardware acceleration capability on their graphics board is via a script. Speed
+up could potentially be 10 to 30 times faster depending on the parameter values you choose
+and the size of your video file. This script is included in the doc subdirectory as
+\texttt{vaapi\_proxy.sh} for users not using an AppImage version and is shown below. You will
+have to tune it to your specific needs for the vaapi\_device name (currently set to
+\texttt{/dev/dri/renderr128}), file type (currently set to h264 and mp4), and proxy size (now is 6).
+Once you have created the proxy file, you then start \CGG{}, load the original un-proxied
+video, use the Settings pulldown and choose the Proxy settings options as you would normally,
+but because you already have created the existing proxy file with the correct name, it will
+be automatically loaded and will not have to create it. The filename of the proxy file
+must be in the same location as the original video and have the exact required naming
+conventions and scale factor.
-More specific information on which plugins need to use \textit{Proxy 1:1}. is provided here next. If the keyframe data uses coordinate data that is absolute, then the Factor scale = 1 should be used. If the data is normalized (like always $0-100\%$) then the proxy can be done with downsize (i.e. classic \textit{Proxy}). The session geometry format, shown in \texttt{Settings $\rightarrow$ Format} as $width \times height$, is changed if scale factor $\neq$ 1 is used to cause all of the data to be in the reduced format. If this affects the plugin operation, then \textit{Proxy 1:1} should be used. Examples of plugins that need the \textit{Proxy 1:1} are: Title, AutoScale, Scale, ScaleRatio, and Translate. Most others are safe to use with downsize.
+\begin{lstlisting}[numbers=none]
+#!/bin/bash
+filename="$1"
+fileout="${filename%.*}"
+proxy="6"
+# Hardware encode AMD
+ffmpeg -threads 2 -hwaccel vaapi -vaapi_device /dev/dri/renderD128 \
+ -i "$1" -c:v h264_vaapi -vf "format=nv12,hwupload,scale_vaapi=iw/'$proxy':ih/'$proxy'" \
+ -vcodec h264_vaapi -preset fast -c:a copy \
+ -bf 0 -profile:v 66 "$fileout".proxy"$proxy"-mp4.mp4
+\end{lstlisting}
\subsection{Proxies with Alpha channel}%
\label{sub:proxies_alpha_channel}
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 \index{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.
+The settings of the project have an effect on the outcome, 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 \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
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 \textit{seekable} \index{seek}, 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. This is particularly useful for the \texttt{mkv} container, which often has seek problems.
+The BIGGEST gain from using this is if you have media that is not \textit{seekable} \index{seek}, 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. This is particularly useful for the \texttt{mkv} container, which often has seek problems. For more details on mkv container see \ref{ssub:note_mkv_container}
Another important function of Transcode is being able to convert the project's media into a high-quality \textit{mezzanine} codec \index{mezzanine codec} (sometimes also called \textit{intermediate} codec \index{digital intermediate}), which makes timeline work lighter and more efficient. In fact such codecs (ffv1, ProRes, DNxHD, OpenEXR, huffyuv, etc) are generally little or not at all compressed; the type of compression is intraframe --more suitable for editing, and the image quality (4:2:2 up; 10-bit color up; floating point; etc) is suitable for \textit{Color Correction}, \textit{Chroma Key} and \textit{Rotoscoping}. The use of mezzanine codecs leads to very large files, so you need to make sure you have enough storage space.
+\paragraph{NOTE:} \CGG{} cannot do \textit{remuxing} without transcoding. For remuxing only, use \textit{ffmpeg} as shown in the following script. First move to the folder containing the files to be remuxed; the script takes all video files of a certain extension (in the following example \texttt{avi}) from the folder and its subfolders and makes a remux in a new container (in this example \texttt{mkv}) inside the new folder \texttt{remux}. The internal codec will remain the original one. Here is an example script:
+
+\begin{lstlisting}[numbers=none]
+ for f in $(find . -name '*.avi'); do ffmpeg -i "$f" -c:v copy -c:a copy "remux/{f%.*}.mkv "; done
+\end{lstlisting}
\section{OpenEDL}%
\label{sec:openedl}
parameter values. Previously to make any changes to these types of
EDL you had to remake the whole clip from scratch. The program is
actually "opening" the file as it currently exists for that particular
-media so that it can be edited separately from the project EDL. In other NLEs the term \textit{sub-timeline} is used.
+media so that it can be edited separately from the project EDL. In other NLEs the term \textit{sub-timeline} or \textit{sub-project} is used.
+It is important to know that all media used with Open EDL must be loaded on the timeline Main Program window and created from there in that project.
Here is how this works. In the Clip \index{clip !older} or Media folder \index{media folder} or on a timeline
EDL edit, the option \textit{Open EDL} for the highlighted clip or
timeline and you will see the AgingTV effect.
\end{enumerate}
+\paragraph{NOTE:} \textit{Open EDL} was not designed to work from the Viewer window. It needs clips to have been created from the timeline Main Program window Project in order to keep track of levels. Clips created in the Viewer have different min and max X/Y dimensions and zoom values.
+
You can follow the same steps as above by first using the option
\textit{Nest to media} in the Clip folder which nests the clip and
moves it out of the Clip folder to the Media folder. Then use
Media folder of Resources window & Open EDL for Nested or Referenced EDLs\\
Clip folder of Resources window & Open EDL for clips\\
Track timeline & Open EDL for Nested or Referenced EDLs\\
- \bottomrule
+ \hline
\end{tabular}
\end{center}
\begin{figure}[htpb]
\centering
\includegraphics[width=0.5\linewidth]{trim.png}
- \caption{Default choices for mouse: Ripple for button 1; Roll
- for button 2; Slip for button 3}
+ \caption{Default choices for mouse: Ripple for LMB; Roll
+ for MMB; Slip for RMB}
\label{fig:trim}
\end{figure}
this choice to prevent accidental movements.
\end{description}
+\paragraph{NOTE:} you cannot do Trim operations on \textit{Hard Edges}, which are produced by a cut operation ("\texttt{x}"). To create a cut useful for trimming you must select an interval (at the limit of one frame) to be muted ("\texttt{m}"); now the edges of the edits will be trimmable because they are not \textit{Hard Edges}. See \ref{sec:cut_paste_editing}, \textit{Split - blade cut and hard edges}.
+
The next table displays the options and results
with the Key Table here first.
\end{lstlisting}
\renewcommand{\arraystretch}{1.15}
-\begin{center}
- %\caption{}
- %\label{tab:}
- % Tell table to adjust font to fix on the page using \resize
- \begin{longtable}{lllll}
- \toprule
- & & \textbf{Drag Left} & \textbf{Drag Right} &\\
- \midrule
- \multicolumn{2}{l}{\textit{curr s += c, l -= c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
- abc12345xyz & \textbf{Ripple} left edge 11 $\rightarrow$ & abc012345xyz & abc2345xyz &\\
- \midrule
- \multicolumn{2}{l}{\textit{curr l += c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
- abc12345xyz & \textbf{Ripple} right edge 01 $\rightarrow$ & abc1234xyz & abc123456xyz &\\
- \midrule
- \multicolumn{2}{l}{\textit{prev l += c; curr ps+= c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
- abc12345xyz & \textbf{Roll} left edge 00 $\rightarrow$ & ab012345xyz & abcd2345xyz &\\
- \midrule
- \multicolumn{2}{l}{\textit{curr l += c; next ps+= c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
- abc12345xyz & \textbf{Roll} right edge 00 $\rightarrow$ & abc1234wxyz & abc123456yz &\\
- \midrule
- \multicolumn{2}{l}{\textit{s -= c}} & $\leftarrow$ & $\rightarrow$ &\\
- abc12345xyz & \textbf{Slip} left edge 10 $\rightarrow$ & abc23456xyz & abc01234xyz &\\
- \midrule
- \multicolumn{2}{l}{\textit{s -= c}} & $\leftarrow$ & $\rightarrow$ &\\
- abc12345xyz & \textbf{Slip} right edge 10 $\rightarrow$ & abc23456xyz & abc01234xyz &\\
- \midrule
- \multicolumn{2}{l}{\textit{prev l += c; curr p+= c; next ps += c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
- abc12345xyz & \textbf{Slide} left edge 10 $\rightarrow$ & ab012345wxyz & abcd12345yz &\\
- \midrule
- \multicolumn{2}{l}{\textit{prev l += c; curr p+= c; next ps += c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
- abc12345xyz & \textbf{Slide} right edge 10 $\rightarrow$ & ab12345wxyz & abcd12345yz &\\
- \midrule
- \multicolumn{2}{l}{\textit{curr s -+= c, l += c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
- abc12345xyz & \textbf{Edge} left edge 11 $\rightarrow$ & abc2345xyz & abc0123456xyz &\\
- \midrule
- \multicolumn{2}{l}{\textit{curr l -+= c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
- abc12345xyz & \textbf{Edge} right edge 01 $\rightarrow$ & abc1234xyz & abc123456xyz &\\
- \bottomrule
- \end{longtable}
-\end{center}
+
+\begin{longtable}{lllll}
+ \toprule
+ & & \textbf{Drag Left} & \textbf{Drag Right} &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{curr s += c, l -= c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
+ abc12345xyz & \textbf{Ripple} left edge 11 $\rightarrow$ & abc012345xyz & abc2345xyz &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{curr l += c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
+ abc12345xyz & \textbf{Ripple} right edge 01 $\rightarrow$ & abc1234xyz & abc123456xyz &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{prev l += c; curr ps+= c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
+ abc12345xyz & \textbf{Roll} left edge 00 $\rightarrow$ & ab012345xyz & abcd2345xyz &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{curr l += c; next ps+= c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
+ abc12345xyz & \textbf{Roll} right edge 00 $\rightarrow$ & abc1234wxyz & abc123456yz &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{s -= c}} & $\leftarrow$ & $\rightarrow$ &\\
+ abc12345xyz & \textbf{Slip} left edge 10 $\rightarrow$ & abc23456xyz & abc01234xyz &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{s -= c}} & $\leftarrow$ & $\rightarrow$ &\\
+ abc12345xyz & \textbf{Slip} right edge 10 $\rightarrow$ & abc23456xyz & abc01234xyz &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{prev l += c; curr p+= c; next ps += c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
+ abc12345xyz & \textbf{Slide} left edge 10 $\rightarrow$ & ab012345wxyz & abcd12345yz &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{prev l += c; curr p+= c; next ps += c, l -= c}} & $\leftarrow$ & $\rightarrow$ &\\
+ abc12345xyz & \textbf{Slide} right edge 10 $\rightarrow$ & ab12345wxyz & abcd12345yz &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{curr s -+= c, l += c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
+ abc12345xyz & \textbf{Edge} left edge 11 $\rightarrow$ & abc2345xyz & abc0123456xyz &\\
+ \midrule
+ \multicolumn{2}{l}{\textit{curr l -+= c; + rest}} & $\leftarrow$ & $\rightarrow$ & \textit{rest}\\
+ abc12345xyz & \textbf{Edge} right edge 01 $\rightarrow$ & abc1234xyz & abc123456xyz &\\
+ \bottomrule
+\end{longtable}
\renewcommand{\arraystretch}{1}
Next, a more immediate and colorful view shows these trimming
First familiarize yourself with button operation; check your setup
by executing the following step. In the \texttt{Settings
$\rightarrow$ Preferences $\rightarrow$ Interface} tab, Editing
-section, clicking on the edit boundaries can be set for Button 1, 2,
-3 as one of the following:
+section, clicking on the edit boundaries can be set for LMB (Button 1), MMB (Button 2), RMB (Button 3) as one of the following:
\textit{Ripple}; \textit{Roll}; \textit{Slip}; \textit{Slide};
\textit{Edge} or \textit{No effect}
\subsubsection*{But, I want to use only the first set of audio tracks\dots}%
\label{ssub:but_use_only_first_audio}
-There are many cases where you may want to compose using media from several different tracks while using the the same audio tracks as associated from a specific viewer. Since mixer source tracks can be updated any time by using a mixer toggle \index{mixers!toggle}, this makes it possible to do this.
+There are many cases where you may want to compose using media from several different tracks while using the the same audio tracks as associated from a specific viewer. Since mixer source tracks can be updated any time by using a mixer toggle\index{mixers!toggle}, this makes it possible to do this.
Procedure to update the mixer audio source track list:
--- /dev/null
+\chapter{Overview}%\r
+\label{cha:anamorphic}\r
+\r
+\section{\textbf{HDV, anamorphic and non-square pixels}}%\r
+\label{sec:hdv}\r
+\r
+A guide on how to handle anamorphic formats in \CGG{}.\r
+For a detailed discussion see: {\small \url{https://lurkertech.com/lg/pixelaspect/}}\r
+\r
+\subsection{\textbf{Theory}}%\r
+\label{sub:theory}\r
+\r
+There are two aspect ratios: the \textit{Pixel Aspect Ratio} and the \textit{Frame Aspect Ratio}. See Figure~\ref{fig:DAR} (from {\small \url{https://stackoverflow.com/questions/18877243/why-ffmpeg-print-sar-instead-of-par}}):\r
+\r
+\begin{figure}[htpb]\r
+ \centering\r
+ \includegraphics[width=0.85\linewidth]{DAR.png}\r
+ \caption{DAR and SAR compared}\r
+ \label{fig:DAR}\r
+\end{figure}\r
+\r
+Unfortunately, there are two opposing schools of thought in describing various aspect ratios:\r
+\r
+\begin{enumerate}\r
+ \item PAR = Pixel (\textit{pixel}) aspect ratio and SAR = Storage (\textit{frame}) aspect ratio.\r
+ \item PAR = Picture (\textit{frame}) aspect ratio and SAR = Sample (\textit{pixel}) aspect ratio.\r
+\end{enumerate}\r
+\r
+Ffmpeg follows this second way, and in addition the total absence of PAR replaced by W/H of the input frame. \CGG{} uses ffmpeg to show the results in the Resources window, Media Folder, \texttt{Asset/RMB $\rightarrow$ Info $\rightarrow$ Detail}, which indicates S(ample)AR.\r
+\r
+For practical purposes the concepts are the same and only the definitions change. The important thing is to understand that the pixel aspect ratio, whether called PAR or SAR, is the conversion factor that, in the case of non-squared pixels, brings the aspect ratio of the input frame to that of the output frame. The basic formula for understanding the various aspect ratios is as follows:\r
+\r
+\qquad $DAR = SAR \times PAR(=W/H)$\r
+\r
+with:\r
+\r
+\textbf{DAR} = Display Aspect Ratio. It is the aspect ratio of the frame on the screen. In \CGG{} is the shape of canvas (or project or output). It is a \textit{frame} aspect ratio.\r
+\r
+\textbf{PAR} = \textbf{W/H} = Picture Aspect Ratio. It is the initial aspect ratio (input), for example of the source media file. It is also, the number of pixel (Width and Height) used to memorize the asset. It is a \textit{frame} aspect ratio. To avoid confusion with the other definition of PAR (that is: Pixel aspect ratio) we will use W/H ratio more.\r
+\r
+\textbf{SAR} = Sample Aspect Ratio. It is the ratio of the sides of the single pixel. It is a correction factor for the recordered frame format resolution, to get the desired output display resolution at a given DAR. It is a \textit{pixel} aspect ratio.\r
+\r
+Monitors and modern HD+ TVs have square pixels. Since most formats, sensors, digital video signals and displays have square pixels, then the reproduction will always be correct.\r
+Older NTSC and PAL TVs do not have pixels but scan frequencies that support both anamorphic and non-anamorphic signals. For an overview on older PAL/NTSC TVs, see wikipedia: {\small \url{https://en.wikipedia.org/wiki/Pixel_aspect_ratio#Pixel_aspect_ratios_of_common_video_formats}}.\r
+\r
+SAR being the ratio of single pixel sizes, is 1 (or 1:1) for square pixels while it is different from 1 for rectangular pixels. We have the following values for the formats DV and HDV (from: {\small \url{https://www.mail-archive.com/ffmpeg-user@ffmpeg.org/msg27522.html}}, with further variations):\r
+\r
+\begin{center}\r
+\renewcommand\arraystretch{1.3}\r
+\begin{tabular}{|c||c|c||c|c||c|}\r
+ \hline\r
+ \multirow{2}{*}{\textbf{DV; HDV}} & \textbf{Display} & \textbf{DAR} & \textbf{Picture} & \textbf{PAR} & \textbf{SAR =} \\\r
+ & \textbf{(Output)} & \textbf{(W/H)} & \textbf{(Input)} & \textbf{(W/H)} & \textbf{DAR $\times$ W/H} \\\r
+ \hline\r
+ 16:9-2160 & 3840 x 2160 & 16:9 & 3840 x 2160 & 16:9 & 1:1 \\\r
+ 4:3-2160 & 2880 x 2160 & 4:3 & 2880 x 2160 & 4:3 & 1:1 \\\r
+ 16:9-1080 & 1920 x 1080 & 16:9 & 1920 x 1080 & 16:9 & 1:1 \\\r
+ 16:9-1080 & 1920 X 1080 & 16:9 & 1440 x 1080 & 4:3 & 1:1 \\\r
+ 16:9-720 & 1280 x 720 & 16:9 & 1280 x 720 & 16:9 & 1:1 \\\r
+ 16:9-1080 & 1920 X 1080 & 16:9 & 1440 x 1080 & 4:3 & 4:3 \\\r
+ 16:9-576 & 1024 x 576 & 16:9 & 720 x 576 & 5:4& 64:45 \\\r
+ 4:3-576 & 768 x 576 & 4:3 & 720 x 576 & 5:4& 16:15 \\\r
+ 16:9-480 & 853 x 480 & 16:9 & 720 x 480 & 3:2& 32:27 \\\r
+ 4:3-480 & 640 x 480 & 4:3 & 720 x 480 & 3:2 & 8:9 \\\r
+\hline\r
+\end{tabular}\r
+\end{center}\r
+\r
+To summarize: in the digital domain, one can use the concept of SAR (\textit{pixel} aspect ratio) when dealing with anamorphic digital formats (for example, when transcoding to a format that has a different WxH). Similarly, in the context of \textit{Standard-definition television} or with \textit{DV}, \textit{HDV} and a few other formats, SAR uses the formula DAR = SAR x (W/H), where SAR is the conversion factor between Input and the Output aspect ratio.\r
+\r
+\subsection{\textbf{How \CGG{} works}}%\r
+\label{sub:how_cgg_works}\r
+\r
+What has been said so far is to clarify the theoretical framework; if users want to go deeper into the subject, they will certainly be dealing with these formulas and definitions. However, \CGG{} does not require knowledge of the formula or the definitions of PAR and SAR. The \texttt{Format} window in the \texttt{Settings} pulldown, is used to set the Width/Height and DAR; PAR and SAR are used in a hidden way.\r
+\r
+So:\r
+\r
+\begin{itemize}\r
+ \item SAR\textit{source} is shown in \texttt{Asset/RMB $\rightarrow$ Info $\rightarrow$ Detail}; The SAR\textit{project} is not shown in the \texttt{Settings $\rightarrow$ Format} window and cannot be set directly. It can be calculated from: SAR\textit{project}=DAR/(W/H).\r
+ \item DAR is shown in \texttt{Display Aspect Ratio}. It determines the shape of the frame. It is the factor that adapts the WxH\textit{source} to the WxH\textit{project}. Its value allows you to vary the frame aspect ratio by involving the shape of the pixels as well. \texttt{Auto} changes the DAR to always have square pixels. If the asset has rectangular pixels the Auto setting will result in a distorted (vertically stretched) frame.\r
+ \item W/H is calculated from the \texttt{Width} and \texttt{Height} values of the canvas. \texttt{W/H Ratio} can also be used to automate calculations. We have:\r
+ \r
+ WxH\textit{source} = WxH\textit{project} $\rightarrowtail$ Correct display.\r
+ \r
+ WxH\textit{source} < WxH\textit{project} $\rightarrowtail$ pad (letterbox, pillarbox).\r
+ \r
+ WxH\textit{source} > WxH\textit{project} $\rightarrowtail$ crop.\r
+ \r
+ To avoid cropping/padding we can use a scaling step via \texttt{Asset/RMB $\rightarrow$ Info $\rightarrow$ Resize} or with the \texttt{Scale} plugin. The scaling process does not alter the image because it maintains the pixel form factor by simply varying the resolution.\r
+\end{itemize}\r
+\r
+From \texttt{Settings --> Format} window you set the format (Width, Height and DAR) or you apply a preset, at this point the sources will have to adapt to this format.\r
+\r
+To see some useful examples, see Raffaella Traniello: {\small \url{http://www.g-raffa.eu/Cinelerra/HOWTO/anamorphic.html}}\r
+\r
+\subsection{\textbf{Use Case}}%\r
+\label{sub:use_case}\r
+\r
+For a video tutorial, see \href{https://youtu.be/JyIkdX3q_Ho}{HDV, anamorphic and non-square pixels}.\r
+\r
+How to downconvert/scale between two standard 16:9 anamorphic video formats. From \textbf{HDV 1080i} (called \textit{16:9-1080}, PAR 4:3, in the table) to \textbf{DV 16:9}, preset\textit{ PAL 576i (16:9) -DV(D)} (called \textit{16:9-576} in the table).\r
+\r
+Source: HDV (mpegts); WxH=1440x1080; SAR=4:3; DAR=16:9. The format is anamorphic with rectangular pixels stretched horizontally. For the formula seen above we have:\r
+\r
+$DAR (16:9) = 1440/1080 \times SAR (4:3) = 1.3333 \times 1.3333 = 1.777$\r
+\r
+\paragraph{Step 1:} As we go from a project size of 1440x1080 to a size of 720x576, we have to choose whether we want to crop or downscale the source. In the first case we continue with \textit{step 2}; in the second case we must first downscale, for example, using the \texttt{Resize} command found in the \texttt{Resource} window; \texttt{RMB} on source \texttt{$\rightarrow$ Info $\rightarrow$ Resize}. This way we vary the initial W/H preparing it for the preset we will use in \textit{step 2}.\r
+\r
+\paragraph{Step 2:} We change the project from the initial one (of the source) to the preset \textit{PAL 576i (16:9) -DV(D)}.\r
+\r
+Now we have:\r
+\r
+720$\times$576; W Ratio=0.5000; H Ratio=0.5333; DAR 16:9\r
+\r
+from which:\r
+\r
+SAR = DAR / (720/576) = 1.7778 / 1.25 = 1.4222 = 64:45\r
+\r
+Note that the video is cropped if we did not downscale in \textit{step1}.\r
+\r
+\paragraph{Step3:} Render with \textit{dv\_pal.avi} or \textit{dv\_pal.qt} preset. Now we have:\r
+\r
+720$\times$576; SAR = 64:45 (=1.4222); DAR = 16:9\r
+\r
+The difference between the new SAR (1.4222) versus the initial SAR (1.3333) of the source can be explained by taking into account that when Height=576 pixels, the width needs to be displayed horizontal (unsqeezed) with W=576$\times$16/9=1024 pixels (square). But the width needs to be stored (compressed, squeezed) within SD-DV(D)'s format W=720 pixels; therefore:\r
+\r
+SAR=(576$\times$16/9)/720=64/45=1.4222 \\\r
+PAR = W/H = 720/576 = 1.25 \\\r
+DAR = 16:9 (unchanged) \\\r
+\r
+\paragraph{NOTE:} the \textit{dv\_pal-avi} render preset provides interlaced video, consistent with the chosen project preset (576i). However, the avi format used does not provide this information in \texttt{RMB $\rightarrow$ Info $\rightarrow$ Asset Interlacing} or even in ffprobe. If the \textit{dv\_pal.qt} render preset is used, it provides the correct information (\textit{Top Fields First}, the standard for SD PAL).\r
+\r
--- /dev/null
+% ================================================================
+% Page 1 -- Title page definition
+%
+\thispagestyle{empty}
+%\providecommand{\HUGE}{\Huge}% if not using memoir
+\newlength{\drop}% for my convenience
+
+%% specify the Webomints family
+%\newcommand*{\wb}[1]{\fontsize{#1}{#2}\usefont{U}{webo}{xl}{n}}
+%% select a (FontSite) font by its font family ID
+\newcommand*{\FSfont}[1]{\fontencoding{T1}\fontfamily{#1}\selectfont}
+%% if you don’t have the FontSite fonts either \renewcommand*{\FSfont}[1]{}
+%% or use your own choice of family.
+%% select a (TeX Font) font by its font family ID
+\newcommand*{\TXfont}[1]{\fontencoding{T1}\fontfamily{#1}\selectfont}
+%% Generic publisher’s logo
+\newcommand*{\plogo}{\fbox{$\mathcal{PL}$}}
+
+%% Some shades
+\definecolor{Dark}{gray}{0.2}
+\definecolor{MedDark}{gray}{0.4}
+\definecolor{Medium}{gray}{0.6}
+\definecolor{Light}{gray}{0.8}
+%%%% Additional font series macros
+
+\newcommand*{\titleLL}{\begingroup% Lost Languages
+\drop=0.085\textheight
+\fboxsep0.5\baselineskip\sffamily
+\vspace*{\drop}
+\begingroup
+\centering
+\HUGE\textbf{Personal Video Archiving - Anamorphic, Sar, Dar, and Par}\par
+%
+\endgroup
+\vspace*{2\baselineskip}
+\vspace*{0.3\baselineskip}
+{\textcolor{Dark}{\large\textbf{%
+ Aspect Ratio and Anamorphic with Sar, Dar, and Par infromation and uses.}}}\par
+%
+\centering
+\vspace{8\baselineskip}
+{\textcolor{Dark}{\large\textbf{{%
+ Author - Andrea Paz}}}}\par
+%
+{\textcolor{Dark}{\large\today}}\par
+\endgroup}
+\titleLL % use cutom title
+\clearpage
+
+\bigskip%
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "../Anamorphic and Aspect Ratio"
+%%% End:
\end{figure}
In addition to the standard settings for sample rate, frame rate,
-and frame size, \CGG{} uses some less traditional settings like
+and frame size (canvas size), \CGG{} uses some less traditional settings like
channel positions, color model, and aspect ratio. The aspect ratio
-refers to the screen aspect ratio (SAR).
+refers to the display aspect ratio (DAR).
Edit decision lists , the EDL \index{EDL} stored in XML, save the project
settings. Formats which contain media but no edit decisions just
frame rate that you load. Media is reframed to match the project
framerate.
-\item[Canvas size:] \index{canvas size} sets the size of the video output \index{output size}. In addition,
-each track also has its own frame size. Initially, the New Project
-dialog creates video tracks whose size match the video output. The
-video track sizes can be changed later without changing the video
-output.
-
-\item[Aspect ratio:] \index{aspect ratio} sets the aspect ratio; this aspect ratio refers
-to the screen aspect ratio. The aspect ratio is applied to the
-video output. The aspect ratio can be different than the ratio that
-results from the formula: $\dfrac{h}{v}$ (the number of horizontal
-pixels divided into the number of vertical pixels). If the aspect
-ratio differs from the results of the formula above, your output
-will be in non-square pixels.
-
-\item[Auto aspect ratio:] if this option is checked, the Set Format
+\item[Canvas size:] \index{canvas size} sets the size of the video output \index{output size}. In addition,
+each track also has its own frame size. Initially, the New Project dialog creates video tracks whose size matches the video output. The video track sizes can be changed later without changing the video output. We have: Project size = $Width \times Height$, pixels = canvas size = output size .
+
+\item[W/H Ratio] Sets the ratio of the new canvas size (Width, Height) from the old (previous) canvas size (Width, Height).
+
+\qquad W Ratio = $\frac{W_f}{W_i}$ \qquad H Ratio = $\frac{H_f}{H_i}$
+
+with $W_f$/$H_f$: final Width and Height; $W_i$/$H_i$: initial Width and Height.
+
+The new canvas size is recalculated based upon a certain factor in the \texttt{W Ratio}, \texttt{H Ratio} fields. A practical use-case: the current resolution is $640 \times 480$, and for some reason you want Width to be 1.33 times bigger. You don't have to calculate what $640 \times1.33$ is; you type 1.33 into the \texttt{Width} input instead, and \CGG{} calculates it for you. W/H Ratio works as a local calculator. Warning: if you vary W/H Ratio without adjusting Display aspect ratio, we may get non-square pixels resulting in anamorphic frame distortion.
+
+\item[Display aspect ratio:] \index{aspect ratio} sets the aspect ratio; this aspect ratio refers to the display aspect ratio (DAR). The aspect ratio is applied to the video output (canvas). It can be convenient to vary the size of the canvas in percentage terms, instead of having to calculate the number of Width x Height pixels. The aspect ratio can be different than the ratio that results from the formula: $\dfrac{h}{v}$ (the number of horizontal pixels divided into the number of vertical pixels). If the aspect ratio differs from the results of the formula above, your output will be in non-square pixels.
+
+\item[Auto aspect ratio:] if this option is checked, the \texttt{Set Format}
dialog always recalculates the Aspect ratio setting based upon the
given Canvas size. This ensures pixels are always square.
RGB-Float. It is used for high dynamic range processing with
transparency. Or when we don't want to lose data during workflow,
for example in color correction, key extraction and motion
-tracking.
+tracking. Note: even if \CGG{} outputs fp32, exr/tiff values there are normalized to 0-1.0f.
\item[YUV-8 bit] Allocates 8\,bits for Y, U, and V. This is used
for low dynamic range operations in which the media is compressed in
the YUV color space. Most compressed media is in YUV and this
slow for the amount of improvement. RGB float does not destroy
information when used with YUV source footage and also supports
brightness above 100\,\%. Be aware that some effects, like
-Histogram, still clip above 100\,\% when in floating point. See also \ref{sec:color_space_range_playback} and \ref{sec:conform_the_project}.
+Histogram, still clip above 100\,\% when in floating point. See also \ref{sec:color_space_range_playback}, \ref{sec:conform_the_project} and \ref{sec:overview_color_management}.
\item[Interlace mode:] \index{interlacing} this is mostly obsolete in the modern digital
age, but may be needed for older media such as that from broadcast
lines of interlaced source footage. The alternating lines missing on
each output frame are interpolated.
\end{description}
+A tip on how to eliminate Letterbox/Pillarbox black bands in the Set
+Format window can be found here: \nameref{sub:remove_letterbox}.
\section{Best practice in pre-editing}%
\label{sec:best_practice_pre_editing}
Generally, best practice is to perform the following sequence of preparations for video editing.
\begin{enumerate}
- \item Motion stabilization, and maybe some other preparations, to improve the quality of the source video is best done under the properties identical to the properties of the original video; it may be different codec, but same frame size and same frame rate.
- \item If you need to alter the frame rate, for example because different source clips have different frame rates, then recode all the necessary clips to the same future project frame rate. Here frame sizes can still have different sizes, but frame rates should be all the same.
- \item Whole editing: if you need to change frame rate of some restricted part, particularly when smooth acceleration/deceleration is needed, it can be done here. But if frame rate has to be changed only due to different source fps, it is better to do it during the preparation stage.
+ \item Motion stabilization, and maybe some other preparations, to improve the quality of the source video is best done under the properties identical to the properties of the original video; it may be different codec, but same frame size and same frame rate. For stabilization you can use ffmpeg command line plugins called \textit{vidstabdetect} and \textit{vidstabtransform}.
+ \item To have a workflow at the highest quality it may be convenient to convert the sources into image sequences (e.g. OpenEXR). Especially if we want to exchange files with other Color or Compositimg programs that preferably use image sequences.
+ \item Uniform the color models. It is convenient to unify the color models of the sources because they would give different and inconsistent results with each other once displayed in the Compositor window.
+ \item If we intend to do some color correction or compositing with VFX, it is convenient to do some de-noising on the sources to make their pixels more homogeneous and suitable for post processing. De-noising is a heavy operation for the system so it may be convenient to do it in pre-editing.
+ \item If you need to alter the frame rate, for example because different source clips have different frame rates, then recode all the necessary clips to the same future project frame rate. Here frame sizes can still have different sizes, but frame rates should be all the same. If you need to change frame rate of some restricted part, particularly when smooth acceleration/deceleration is needed, it can be done in timeline. But if frame rate has to be changed only due to different source fps, it is better to do it during the preparation stage.
\end{enumerate}
\CGG{} does not have color management \index{color management}, but we can still give some general advice on how to set color spaces:
source: \textit{rec709} $\rightarrow$ monitor: \textit{sRGB} (we get slightly faded colors) \\
source: \textit{rec709} $\rightarrow$ monitor: \textit{DCI-P3} (we get over-saturated colors)
\item It would be better to set the project as RGB(A)-FLOAT, allowing system performance, because it collects all available data and does not make rounding errors. If we can't afford it, starting from YUV type media it is better to set the project as YUV(A)8, so as not to have a darker rendering in the timeline. On the contrary, if we start from RGB signals, it is better to use RGB(A)8. If we don't display correctly on the timeline, we'll make adjustments from the wrong base (metamerism) and get false results.
+ \item Having correct color representation in the Compositor can be complicated. You can convert the imput \textit{YUV color range} to a new YUV color range that provides more correct results (i.e. MPEG to JPEG). The \texttt{Colorspace} plugin can be used for this conversion.
\item Among the rendering options always set the values \\
\texttt{color\_trc=...} (gamma correction) \\
\texttt{color\_primaries=...} (gamut) \\
These are only metadata that do not affect rendering but when the file is read by a player later they are used to reproduce the colors without errors.
\end{enumerate}
-For more tips on how \CGG{} processes colors on the timeline see \nameref{sec:color_space_range_playback} and \nameref{sec:conform_the_project}.
+For more tips on how \CGG{} processes colors on the timeline see \nameref{sec:color_space_range_playback}, \nameref{sec:conform_the_project} and \nameref{sec:overview_color_management}.
%%% Local Variables:
%%% mode: latex
In addition, there are currently 2 settings that can only be manually changed in your \$Home/.bcast5/Cinelerra\_rc file and then done so by very careful editing. These include FAST\_SPEED and SLOW\_SPEED which allow you to modify the default 2X speed of \textit{Fast forwward} and the .5X speed of the \#2 keypad for \textit{Slow speed forward play}.
For example, adding the 2 lines FAST\_SPEED 4 and SLOW\_SPEED .2 to the end of the Cinelerra\_rc wile will result in playing at 4X faster and 5X slower.
+Another example of user modifiable settings involving the plugins menu in the Resources window, can be found in \nameref{sub:expanders_plugin_subtrees}.
+
\section{Playback A / Playback B}%
\label{sec:playback_a_b}
\index{preferences!playback\_a\_b}
shutting down and the next time you start up \CGG{} you will be right back where you left off. You
will retain all of your undo's and redo's.
\item[Timeline Rectify Audio] \index{timeline rectify audio} for displaying rectified audio on the timeline instead of a standard audio waveform, check this flag. The waveform is cut on the zero line, thus making the silent areas more visible and the waveform is stretched more over the entire height of the audio track, which improves the visibility of certain areas. This only affects the timeline and not any other audio waveform displays.
+Once you check or uncheck this flag, you must reload any media on the timeline
+in order to see the changed waveform.
\item[Clears before toggle] \index{clears before toggle} when using copy/paste in drag and drop mode some users prefer to resort to the addition of the Ctrl key for adding multiple selections. By checking this flag, the user retains usage as is commonly done for listbox operations.
\item[Always show next frame] \index{always show next frame} in this mode the insertion pointer reflects the same as the Compositor so that for playing forward, the result is what looks like 1 was added to the frame displayed in the Compositor window. This is fully explained in another section (\nameref{sub:playing_seeking}).
\item[Show tip of the day] if checked, a tip will be displayed in a popup box when start up \CGG{}.
- \item[Use thumbnails in resource window] \index{use thumbnails in resources window} the Resource Window displays thumbnails of assets by default, but drawing asset thumbnails can take more time and CPU so you may want to uncheck this.
+ \item[Use thumbnails in resource window] \index{use thumbnails in resources window} the Resource Window displays thumbnails of assets by default, but drawing asset thumbnails can take more time and CPU as well as other system resources so you may want to uncheck this.
\item[Popups activate on button up] \index{popups activate on button up} this is the default but if unchecked, popups activate on button down.
\item[Set Input Focus when window entered] \index{set input focus} this is checked on by default because on some operating system distros, when you move your mouse to a different window, nothing happens and you are left wondering why you can not enter information. When checked this causes the input focus to shift to any \CGG{} window when the cursor enters an exposed region of the window which eliminates the need to switch input focus by tabbing.
\item[Click to activate text focus] \index{click to activate text focus} Click to activate text focus
\index{BluRay}
This section describes how to create a blu-ray DVD, or \textcolor{red}{BD} referring to a \textcolor{red}{B}lu-ray \textcolor{red}{D}VD, and a regular DVD, or \textcolor{red}{SD} referring to a \textcolor{red}{S}tandard \textcolor{red}{D}VD. The DVDs (plural usage of DVD means either BD or SD) created are unencrypted, unlike commercially available movie DVDs. This \CGG{} version conceivably can create different variations of DVD/Blu-ray media but for the casual user the most standard usages are readily usable and will be described here.
+In \CGG{} DVD and Bluray creation is a convenience for users who want to edit and then just make basic media without having to work too hard, therefore
+all features will not be available.
Some preliminary information follows. For NTSC, SD media is almost always $720\times480$ interlaced (the format in the United States, US). For PAL, SD media is almost always $720\times576$ interlaced (Europe, EU, and most of the world). An SD can conceivably be created with a lower resolution – for example $352\times240$ MPEG-1 -- but it is not useful. Aspect ratio for either NTSC or PAL can be $4:3$ or $16:9$.
Frames per seconds is usually $29.97$ for NTSC and $25$ fps for PAL. The standard SD dvd generally uses the MPEG-2 program stream with a filename extension of \texttt{m2v}. BD blu-ray media is not normally interlaced, but you can leave it interlaced. Blu-ray uses the MPEG transport stream which contains 1 or more program streams with a default filename extension of \texttt{m2ts}.
Requirements for creating DVDs is the hardware device to write the media on and, obviously, the blank media for either BD or SD. When generating SD media, you will have to install \textit{dvdauthor} and for BD media, install \textit{udftools} if they are not on your system. Also, keep in mind that to mount filesystems for creating files and to burn DVDs, you will have to be root since you have to have privileges, unless special permissions have been provided for a non-root user. It is also highly recommended to
-run the \CGG{} startup from a terminal window, instead of the icon, in order to see informative messages of how to actually write the output (at prompt: keyin \texttt{<install\_directory\_path/bin/cin}).
+run the \CGG{} startup from a terminal window, instead of the icon, in order to see informative messages of how to actually write the output (at prompt: keyin \texttt{<install\_directory\_path/bin/cin} or
+ \texttt{<install\_directory\_path/<your\_version>.AppImage}).
A warning here -- writing blu-ray BDs and regular SDs can take a large amount of clock time. Keep in mind that a blu-ray can contain 25 hours of viewing, so would take multiple hours to just write one.
\item If not logged in as root, you will get an error message in order to avoid doing a lot of work and then failing out because root is required for automount and to write on DVD hardware.
\item Load your input source media via: \texttt{File $\rightarrow$ Load files}.
\item Choose PAL or NTSC for SD/dvd or 1080P/24 for blu-ray in \texttt{Settings $\rightarrow$ Format}.
+ \item If DVD "Interlace Mode" of Bottom Field First is wanted, you MUST set that in \texttt{Settings $\rightarrow$ Format}. If you do, then also remember to change it when you no longer want BFF.
\item For blu-ray, choose BD Render or for PAL/NTSC, choose DVD \textit{Render} in \textit{File} menu.
\item Designate a \textit{work path} with sufficient disk space and then Chk-OK.
\item When the Batch Render window comes up, click on \textit{Start} and the batch jobs will run.
The general design of the DVD/blu-ray generation operations is to first render media using batch rendering and then terminate \CGG{} to start a script which creates the target device filesystem data. These scripts are the \texttt{dvd.sh} and \texttt{bd.sh} scripts written into the target directory. For DVD, the general plan is to write a directory \texttt{<target>/iso} with the dvd filesystem via \textit{dvdauthor} and then generate an iso9660 filesystem and write it to a dvd via \textit{growisofs}.
-For blu-ray, the filesystem generation is slightly harder. First, it creates an empty filesystem image \texttt{<target>/bd.udfs} using \textit{mkudffs} which makes a big hole for the filesystem data. The hole is made just a little bigger than the data written by \textit{bdwrite} so that you don't have to write an entire $25GB$ or $50GB$ disc even if no data exists. This empty filesystem is loopback mounted to make it writable, and the linux kernel manages the filesystem image. The bdwrite program applies the blu-ray structure to the UDF filesystem by creating the needed BDMV blu-ray filesystem, which the kernel stores onto the image file \texttt{bd.udfs}. When udfs is unmounted, the kernel finalizes the disk image on bd.udfs. The bd.udfs image can be written directly to a blu-ray disk via \textit{dd} or \textit{growisofs}.
+For blu-ray, the filesystem generation is slightly harder. First, it creates an empty filesystem image \texttt{<target>/bd.udfs} using \textit{mkudffs} which makes a big hole for the filesystem data. The hole is made just a little bigger than the data written by \textit{bdwrite} so that you don't have to write an entire $25GB$ or $50GB$ disc even if no data exists.
+The actual calculation for the mkudffs size is yourfile.m2ts size-in-bytes/2048 + 4096.
+This empty filesystem is loopback mounted to make it writable, and the linux kernel manages the filesystem image. The bdwrite program applies the blu-ray structure to the UDF filesystem by creating the needed BDMV blu-ray filesystem, which the kernel stores onto the image file \texttt{bd.udfs}. When udfs is unmounted, the kernel finalizes the disk image on bd.udfs. The bd.udfs image can be written directly to a blu-ray disk via \textit{dd} or \textit{growisofs}.
NOTE of IMPORTANCE: there is a serious situation with the interaction between the Operating System (OS) and bdwrite when creating blu-ray, that requires automount to be turned off. The blu-ray automatic script unmounts the blu-ray/UDF filesystem but the system has not finalized the directories so the OS creates a new loop file device and the data is loaded and cached for use by the new loop but it is stale. Consequences is that not all of the data is written where it should be. The solution is for the OS not to mount this second mount so we have to make sure it doesn't. There are 2 methods to fix this. The first and easiest is by using the following command to disable automount:
\begin{description}
\item[Deinterlace] remove the interlace. Interlacing is a video scanning system in which alternating lines are transmitted so that half a picture is displayed each time the scanning beam moves down the screen. You lose a lot and the quality is bad when you view interlacing on a progressive TV. You might not really want to use deinterlace, because if you deinterlace non-interlaced media, it will look awful.
+In the case of DVD only, for interlaced media when you do not check the Deinterlace option, it will always be done as Top Field First.
+To get DVD media to be Bottom Field First, you MUST set the "Interlace Mode" in \texttt{Settings $\rightarrow$ Format}.
\item[Scale] alter the spatial mapping of an image to increase or reduce the size; modifies the picture. When some programs scale from $4:3$ to $16:9$ they will automatically cut off the appropriate section of the image for you. It is necessary to keep in mind, that \textit{square pixels} is the true end goal of scaling, not the aspect ratio which could result in squished or stretched output. More information about scaling will be provided on a subsequent page with usage of the \textit{Scale Ratio} plugin.
\item[Profile] for bluray only, use the default bluray.m2ts or choose bluray\_lpcm.m2ts for linear pulse code modulation for digitally encoding uncompressed audio information.
\item[use tsmuxer] for bluray only, to use tsMuxer as a transport stream muxer for remuxing/muxing elementary streams, check this box. Usage of tsmuxer requires that your computer have the tsmuxer software installed along with any of its prerequisites. The default is do not use tsmuxer.
Editing DV or HDV and rendering it back to the same format does not require any special handling.
In order to perform colorspace conversions correctly in \CGG{} and avoid Chroma errors for interlaced 4:2:0 video, check the box as follows:
-\texttt{Settings $\rightarrow$ Performance $\rightarrow$ YUV420P DVD Interlace Mode}
+\texttt{Settings $\rightarrow$ Preferences, Interface tab, Operation section, Use yuv420p dvd interlace format}
This option maintains the interlacing in Chroma sample addressing, which ordinarily would be deleted
because the upsampling of interlaced chroma fields is normally done using a progressive algorithm.
With this mode enabled, the MPEG decoder uses a different algorithm for interlaced frames so that the
4:2:0 format chroma interlacing is preserved.
+\section{DVD with LPCM or MP2 audio}%
+\label{sec:dvd_lpcm_audio}
+
+By default, the audio when creating a DVD is always \textit{AC3}. However you can switch to \textit{PCM} (Pulse Code Modulator) or MP2 with just a few additional steps as outlined below.
+Note that Audio must be $48Khz$ or $96Khz$, nothing else is supported, even by ffmpeg's dvd pcm encoder.
+
+\begin{enumerate}
+ \item Start \CGG{} from a terminal window so you will be able to see what is happening. Only the final step when you actually want to write to a
+DVD media writer, requires privileges of either root or the system has
+granted the user this privilege.
+ \item Make sure you have your video with audio loaded and edited to your satisfaction and you are positioned at the start of the video.
+ \item Use the \texttt{File} pulldown and select the \textit{DVD Render} option.
+ \item In the\textit{Create DVD} window, accept the defaults or select different values and then click \texttt{OK}. Do not check "Use FFMPEG" as that may not work.
+ \item When the \textit{Batch Render} window pops up, in the big box towards the bottom will be 2 lines with the first line for \textit{Video} already highlighted. Instead, click on the second line, which is for \textit{Audio}, so that it is highlighted.
+ \item On the top left, you will see the \textit{File Format} set as AC3. Use the down arrow next to the box and change it to \textit{Raw PCM} or \textit{MPEG Audio} by clicking on it.
+ \item When you switch to Raw PCM or MPEG Audio, you see the extension in the \texttt{Output path} above change to pcm or mp3
+ instead of ac3. Now just reset the extension from pcm to lpcm or mp2 as that is required. In most cases if you click on the \texttt{Audio} wrench to see the settings, you will find that the standard settings of 16 bit Linear / Signed / Hi Lo work for Raw PCM. For mp2, you will have to click
+on the Audio wrench and change the default Layer III to Layer II.
+ \item Now click on the \texttt{Start} box in the bottom left hand corner and \CGG{} will process what it can of the job and put you back at your terminal startup window.
+ \item You will see a few lines of output, some of which are shown below, to include the ERROR:
+ \begin{lstlisting}[style=sh]
+ running /dev/shm//dvd_20240116-182336/dvd.sh
+ INFO: [mplex] mplex version 2.1.0 (2.2.7 $Date: 2012/11/17 01:55:16 $)
+ **ERROR: [mplex] Unable to open file
+ /dev/shm/dvd_20240116-182336/dvd.ac3 for reading.
+ \end{lstlisting}
+ \item Change directory to the location as shown on the terminal window of \texttt{dvd.sh}.
+ \item Using an editor, modify the line in dvd.sh to change \texttt{dvd.ac3} to \texttt{dvd.lpcm} or to \texttt{dvd.mp2} for mp2. In addition ONLY for Raw PCM you have to change the mplex parameter to include:
+ \begin{lstlisting}[style=sh]
+ -L 48000:2:16
+ \end{lstlisting}
+ The full line will look like this:
+ \begin{lstlisting}[style=sh]
+ mplex -f 8 -L 48000:2:16 -o $dir/dvd.mpg $dir/dvd.m2v $dir/dvd.lpcm
+ \end{lstlisting}
+ \item Now the script is ready to run in the same manner it would have had it been ac3. That is just run via:
+ \begin{lstlisting}[style=sh]
+ ./dvd.sh
+ \end{lstlisting}
+ \item Check to make sure there are no errors in the output shown on the window and proceed as usual.
+\end{enumerate}
+
+
\section{MPEG utility programs}%
\label{sec:mpeg_utility_programs}
For some time, DVD manufacturers have been employing a variety of measures to make reading a DVD difficult on a computer. One technique which is widely deployed is to add a bunch of extra program data, so that correct playback is only likely if you can read the DVD virtual machine data and decode a maze of program data to find the undamaged stream definitions. Only a few streams are created which are machine usable, and dozens are created as decoy streams. The decoy streams fail or introduce errors. This program scans the IFO (info file) playlists and verifies the contents of the stream that does not contain obvious damage. The result is a list of program ids which can be entered into the playback preferences to select a program which qualifies.
-\section{HDV on a Blu-ray Disc Without Re-encoding}%
-\label{sec:hdv_bd_without_reencoding}
-\index{BluRay!HDV without re-encoding}
+\section{Creating Blu-ray Without Re-encoding}%
+\label{sec:bluray_without_reencoding}
+\index{BluRay!without re-encoding}
+\index{BluRay!camcorders}
+\index{BluRay!AVCHD}
+
+If you have video that is already in Blu-ray format AND you do not want to use \CGG{} to do
+any editing, you can create blu-ray video media using Cinelerra's \textit{bdwrite} program. This
+could be the case if you are working with media from a modern Digital Camcorder. Camcorders
+usually record in a legacy tape-based format or the current file-based format. The most common
+digital camcorder formats and whether or not they need to be re-encoded are:
-An MTS file is a video file saved in the high-definition (HD) MPEG Transport Stream video format, commonly called \textit{AVCHD}. It contains HD video compatible with Blu-ray disc format and is based on the MPEG-2 transport stream. MTS files are often used by Sony, Panasonic, Canon and other HD camcorders. Legal input for Video -- MPEG1VIDEO, MPEG2VIDEO, H264; Audio -- MP1, MP2, AC3, AC3PLUS, DTS, TRUHD.
+\begin{itemize}
+ \item DV (1995) to SD-blu-ray video - process in \CGG{} using the File pulldown of
+BD Render as previously described or use programs documented in their manuals to re-encode
+video to mpeg2 and then re-encode DV LPCM audio to Blu-ray LPCM.
+ \item HDV (2004) to blu-ray video - process in \CGG{} using the File pulldown of
+BD Render as previously described or use programs documented in their manuals to
+ copy mpeg2
+video and then re-encode MP2 audio to Blu-ray LPCM or AC3.
+ \item AVCHD (2006-current) to blu-ray video; these are the types of videos that do
+not have to be re-encoded if you do not want to edit anything.
+\end{itemize}
+For an explanation of the differences between HDV vs AVCHD see:
+ {\small \url{http://www.differencebetween.net/technology/difference-between-hdv-and-avchd}}
-For creating a blu-ray disc, if you have HDV MPEG-2 media that is in blu-ray format, you can save the original quality of your work, rather than rendering it to another format. Follow the steps below directly instead of going through \CGG{}. It has been tested on 10 different MTS files.
+Besides digital camcorder file-based format of AVCHD, there are video files in MTS format
+that are also candidates for burning to blu-ray video media without re-encoding.
+An MTS file is a video file saved in the high-definition (HD) MPEG Transport Stream video format/H264, commonly called \textit{AVCHD}. It contains HD video compatible with Blu-ray video disc format and is based on the MPEG-2 transport stream. MTS files are often used by Sony, Panasonic, Canon and other HD camcorders. Legal input for Video -- MPEG1VIDEO, MPEG2VIDEO, H264; Audio -- MP1, MP2, AC3, AC3PLUS, DTS, TRUHD.
+For creating a blu-ray video disc, if you have these HD MPEG-2 media types that are in blu-ray video format, you can save the original quality of your work, rather than rendering it to another format.
+Note that for older media or media which used MP1 or MP2 audio codecs which will not work on
+blu-ray video discs, it may be necessary to first transcode the audio while leaving video intact.
+An example of the transcode line to use if using ffmpeg version 5.1 or higher is shown next.
+If using a lower ffmpeg version substitute ac3 for pcm\_bluray:
+
+\begin{lstlisting}[numbers=none]
+ffmpeg -i hdv -c:v copy -c:a pcm_bluray -mpegts_m2ts_mode 1 new_hdv.mts
+\end{lstlisting}
+
+Follow the next 2 sets of steps to create the blu-ray video disc.
\begin{lstlisting}[style=sh]
-du -sb /yourHDVfile.MTS # Determine the size of your file in bytes.
-blocks=((size-in-bytes/2048 + 4096)) # Convert bytes into blocks + a little more.
-mkudffs /tmp/newfilename.udfs blocks # Create a file with that \# of blocks + some extra.
+du -sb /yourHDVfile.MTS # Determine the size of your file in bytes.
+blocks=((size-in-bytes/2048 + 4096)) # Convert bytes into blocks + a little more.
+mkudffs -b 2048 /tmp/newfilename.udfs blocks # Create a file with that \# of blocks + some extra.
mount -o loop /tmp/newfilename.udfs /mntX # Use a mount point like mntX that is not in use.
+\end{lstlisting}
+In order to create the udfs file, you will need access to Cinelerra's \textit{bdwrite} program.
+If you do not do your own build and compile, but use the AppImage instead, you will have to first
+extract \textit{bdwrite} from the AppImage as described in the NOTE at \ref{sub:managing_appimage}.
+\begin{lstlisting}[style=sh]
/<cinelerra_installed_path>/bin/bdwrite /mntX /tmp/yourHDVfile.MTS # Substitute \CGG{} path.
-umount /mntX # You must unmount the udfs filesystem
+umount /mntX # You must unmount the udfs filesystem
growisofs -Z /dev/bd=/tmp/newfilename.udfs # Replace /dev/bd with your bluray hardware device.
OR dd if=/tmp/newfilename.udfs of=/dev/bd bs=2048000 # if using rewritable blu-ray; replace bd.
\end{lstlisting}
\label{sec:bluray_multiple_cinelerra_output}
\index{BluRay!multiple output}
-Writing prepared multiple \CGG{} output files, \texttt{bd.m2ts}, to a single bluray disc is relatively easy to do but is not done automatically. You can render all of the desired files via the Create BD menu, save each individual \texttt{bd.m2ts} file with a unique name, construct a Menu Title that reflects the contents of each of these files, then manually use a few commands to create a udfs file to be written to BD.
+Writing prepared multiple \CGG{} output files, \texttt{bd.m2ts}, to a single bluray video disc is relatively easy to do but is not done automatically. You can render all of the desired files via the Create BD menu, save each individual \texttt{bd.m2ts} file with a unique name, construct a Menu Title that reflects the contents of each of these files, then manually use a few commands to create a udfs file to be written to blu-ray video media. If using AppImage, you will have to first extract the \textit{bdwrite} program as explained in the NOTE at \ref{sub:managing_appimage}. You can
+use any other software program that works instead.
Usage of the final preparation taken from the bdwrite program comments:
\begin{enumerate}[nosep]
\item unpack/patch source code: \\
- \texttt{git clone --depth 1 ``git:/{\dots}/target'' cinelerra5} \\
+ \texttt{git clone -{}-depth 1 ``git:/{\dots}/target'' cinelerra5} \\
\texttt{./autogen.sh}
\item configure build:\\
\texttt{./configure --with-single-user}
\item \texttt{./configure} {\dots}
\end{itemize}
-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:
+\section{Experimental Builds}
+\label{sec:experimental_builds}
+\index{build!experimental}
+
+The main compilation we have seen leads to building \CGG{} with its own internal ffmpeg, which includes its stability and feature patches. Normally ffmpeg is updated to version x.1 of each release. The reasons why it is best to use thirdparty with their static versions of the libraries and ffmpeg are explained in detail in \nameref{sec:latest_libraries} and in \nameref{sub:unbundled_builds}.
+
+You can still compile \CGG{} with ffmpeg-git to enjoy the latest version. This build may lead to feature variation and less stability, but in most cases will work perfectly fine.
+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
-() ./autogen.sh\newline
-./configure --with-single-user --with-booby --with-git-ffmpeg=https://git.ffmpeg.org/ffmpeg.git
-make && make install ) 2>1 | tee log
-mv Makefile Makefile.cfg
-cp Makefile.devel Makefile
+ #!/bin/bash
+ ./autogen.sh
+ ./configure --with-single-user --with-booby --with-git-ffmpeg=https://git.ffmpeg.org/ffmpeg.git
+ make && make install ) 2>1 | tee log
+ 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 \CGG{} 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 some 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 \CGG{} build. FFmpeg is constantly changing and many times the git version is not as stable as desired.
+
+Finally, it is possible to compile \CGG{} so that it uses ffmpeg which is already installed on the system. This build takes less time to compile and may increase performance in both rendering and timeline manipulation. Again, there may be variations in functionality and less stability.
+Getting a build to work in a system environment is not easy. If you have already installed libraries which are normally in the thirdparty build, getting them to be recognized means you have to install the devel version
+so the header files which match the library interfaces exist. If you want to build using only the thirdparty libraries installed in your system, just include \texttt{-–without-thirdparty} to your configure script. For example:
+
+\begin{lstlisting}[numbers=none]
+./confgure --with-single-user --disable-static-build --without-thirdparty --without-libdpx
+\end{lstlisting}
+
+The library, libdpx, is just such an example of lost functionality: this build of \CGG{} will not be able to use the DPX format.
\section{Configuration Features}
\label{sec:configuration_features}
--enable-openjpeg build openjpeg (auto)
--enable-libogg build libogg (auto)
--enable-libsndfile build libsndfile (auto)
+ --enable-libsvtav1 build libsvtav1 (no)
--enable-libtheora build libtheora (auto)
--enable-libuuid build libuuid (yes)
--enable-libvorbis build libvorbis (auto)
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 \CGG{}):
-\hspace{2em}
-\begin{tabular}{@{}rcr}
- 1 cpu & = & 61 mins\\
- 12 cpus & = & 7.5 mins\\
- 24 cpus & = & 2 mins\\
-\end{tabular}
+\begin{center}
+ \begin{tabular}{@{}lcr}
+ 1 cpu & = & 61 mins\\
+ 12 cpus & = & 7.5 mins\\
+ 24 cpus & = & 2 mins\\
+ \end{tabular}
+\end{center}
\section{Using the very latest Libraries}
\label{sec:latest_libraries}
Look into opencv4/opencv2/core/types.hpp:711;27
\end{description}
-\textbf{webp}
-\begin{description}[noitemsep]
- \item Status - currently at version 1.1.0
- \item Problem - requires cmake 3.5
- \item Workaround already in use by \CGG{} - leaving out of Ubuntu14, Ubuntu, Centos7
- \item Your workaround - upgrade on those systems to cmake 3.5
-\end{description}
-
\textbf{libaom}
\begin{description}[noitemsep]
\item Status - currently at version 3.0.0 for older O/S and 3.1.1 for newer O/S
\label{sec:valgrind_support_level}
\index{build!valgrind}
-Valgrind is a memory mis-management detector. It shows you memory leaks, deallocation errors, mismanaged threads, rogue reads/writes, etc. \CGG{} 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 \CGG{} shuts down, it deallocates memory instead of just stopping, thus making memory leak detection possible.
+Valgrind is a memory mis-management detector. It shows you memory leaks, deallocation errors, mismanaged threads, rogue reads/writes, etc. \CGG{} 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 \CGG{} shuts down, it deallocates memory instead of just stopping, thus making memory leak detection possible. An alternative to Valgrind is
+\textit{heaptrack} which has good documentation and for large programs can run
+faster. You can find the source and information about it at {\small\url{https://github.com/KDE/heaptrack}}.
+\index{valgrind!heaptrack}
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:
deadly. The listing of the memory leaks can be quite voluminous so locating the \textit{LEAK SUMMARY} section
towards the end of the report is most useful.
+Another very useful valgrind run to locate unitialized variables while executing is:
+
+\hspace{2em}\texttt{valgrind -{}-log-file=/tmp/log -{}-tool=memcheck\\
+ -{}-num-callers=32 ./ci}
\section{CFLAGS has -Wall}
\label{sec:cflags_has_-wall}
\section{Working on AppImage}
\label{sec:working_on_appimage}
-You can work on the appimage file to make changes and fix errors, or you can create a new appimage from scratch containing customizations. For example, you can add new rendering presets; update the Context-Help; change libraries that are no longer supported by the current distro; or make other modifications.
+You can work on the appimage file to make changes and fix errors, or you can create a new appimage from scratch containing customizations. For example, you can add new rendering presets, update the Context-Help, change libraries that are no longer supported by the current distro, or make other modifications.
\subsection{Managing AppImage}
\label{sub:managing_appimage}
Because the appimage file is nothing more than a compressed file containing the same structure as the installed program plus other libraries that allow the program to run independently from the system, the content can be extracted so that you can work on it as you would have on the normally installed program. To do this you will need the appimage management program.
Many Linux distros come with this managment program by default, but others may not. For instance in the case of Arch Linux the \texttt{appimagetool-bin} package from AUR needs to be installed.
-To work on the appimage, first unpack it using the command\protect\footnote{Example provided by Glitterball3}:
+To work on the appimage, first unpack it using the command\protect\footnote{Example provided by Glitterball3} (note that you do not have to be root to do any of the following):
\begin{lstlisting}[numbers=none]
/{path to appimage}/CinGG-yyyymmdd.AppImage --appimage-extract
\end{lstlisting}
-You will now have a \texttt{squashfs-root} folder containing \texttt{/usr/bin/} as well as other files and directories such as \texttt{/usr/lib} and \texttt{/usr/share}. \texttt{Bin} is the folder similar to the one installed with \CGG{} and contains the files that you can work on. Now it is possible to make changes like adding a custom preset in \texttt{/ffmpeg/video} or replacing a library that no longer works with a more recent version by working in \texttt{/squashfs-root/usr/lib}.
+You will now have a \texttt{squashfs-root} folder in your current directory containing \texttt{/usr/bin/} as well as other files and directories such as \texttt{/usr/lib} and \texttt{/usr/share}. \texttt{Bin} is the folder similar to the one installed with \CGG{} and contains the files that you can work on. Now it is possible to make changes like adding a custom preset in \texttt{/ffmpeg/video} or replacing a library that no longer works with a more recent version by working in \texttt{/squashfs-root/usr/lib}.
To start the unpacked program from the bin folder use the command:
Now there will be an appimage called \textit{CinGG-yyyymmdd.AppImage} with the changes that were made.
+NOTE: for the \textbf{bdwrite} program which is used to create the udfs image to burn Blu-ray
+media (or any other standalone program), you will find it in the squashfs-root/usr/bin
+subdirectory. You only need to do the initial unpacking extract step and then just copy
+bdwrite and the entire squashfs-root/usr/lib directory to a convenient permanent place for
+usage. Then when running bdwrite, you will have to first export the libary path by typing
+this command in the window first:
+\begin{lstlisting}[numbers=none]
+export LD_LIBRARY_PATH=/{put your copied usr/lib path here}:$LD_LIBRARY_PATH
+\end{lstlisting}
+
\subsection{Build the CinGG.AppImage from scratch}
\label{sub:built_appimage_scratch}
\index{appimage!creating}
editing} \index{two-screen} (or 3 point editing) where the Viewer is used to view media and then the
desired clip from the media is transferred to the timeline.
+In the timeline, Audio tracks are different from Video tracks so a media including both audio and video will be split into 2 or more independent tracks. There is no \textit{Link/Unlink}-like function present in other programs, although there are workarounds.
+
The timeline \index{timeline} is where all editing decisions are made
(figure~\ref{fig:timeline}). This is a stack of tracks in the
center of the main window. It can be scrolled up, down, left and
loading your edit decisions is explained in the Load, Save and the
EDL \index{EDL} section and rendering is explained in the section on Rendering.
+\textbf{Nomenclature:} media loaded in the timeline, in whole or in part, are called \textit{edits}, unlike other programs that call them \textit{clips}. Clips in \CGG{} are those that are created in the Viewer window or in the timeline via the \texttt{to clip} command and brought into the Resources window, inside the \texttt{Clips folder}, where they can be renamed and a description added. These, once brought into the timeline, are renamed edits. In \CGG{} the difference edits/clips is not important and you can use them as synonyms; however, the difference of clips as it is intended in other NLEs is important. These are media (or parts of it) complete in themselves and indipendent from other clips and the timeline. Edits in \CGG{} on the other hand, can be a media (or part of it) but can also be any region of the timeline between In/Out Points or from a highlighted, on which we can do editing operations. This leads to some advantages (e.g. putting an effect only in a part of the active region) but one must always keep in mind that the edit remains dependent on the track and the entire timeline.
+
In the following editing sections, references to common operations
are scattered within any of the modes where they seem pertinent.
However, many of the editing operations work in different modes.
\begin{description}
\item [Split | Cut] (x) Delete the selected area and put it in
- the cut buffer for future pasting.
+ the cut buffer for future pasting. If a cut is made on the \textit{Insertion Point} only, without selecting a region, \textit{hard edges} are created.
\item[Copy] (c) Copy the selected area and put it in the cut
buffer for future pasting.
\item[Paste] (v) Paste the material that is in the cut buffer.
button 1 to toggle off/on the hard edge marker on all tracks
simultaneously.
+\paragraph{NOTE:} Hard Edges do not allow trim operations. For more details see: \nameref{sec:trimming}.
\section{Drag and Drop Editing}%
\label{sec:drag_drop_editing}
To simply get started, perform the following operations which are
useful for working in a drag and drop editing session. First load
your media by using the main menu \textit{File} pulldown \index{file pulldown} and choose
-\textit{Load files} \index{load media files}; make sure the insertion mode is set to
+\textit{Load files}\index{load media files}; make sure the insertion mode is set to
\textit{Create new resources only} \index{insertion strategy}. This loads the files into the
Resources window \index{resources window}.
provided below.
\renewcommand{\arraystretch}{1.15}
-\begin{center}
\begin{longtable}{p{0.3\textwidth-2\tabcolsep} p{0.7\textwidth-2\tabcolsep}}
\toprule
\textbf{Key} & \textbf{Operations}\\
off if it is on.\\
\bottomrule
\end{longtable}
-\end{center}
-\begin{center}
\begin{longtable}{p{0.2\textwidth-2\tabcolsep}
- p{0.2\textwidth-2\tabcolsep} p{0.6\textwidth-2\tabcolsep}
- }
+ p{0.2\textwidth-2\tabcolsep} p{0.6\textwidth-2\tabcolsep}}
\toprule
\textbf{Popup Label} & \textbf{Key} & \textbf{Operation}\\ \midrule
+ %begin{latexonly}
\endhead
+ %end{latexonly}
Clear Select & Ctrl-Shift-A & Deselect all selected edits --
ones that have the red lines
around them.\\
- Select Edits & Ctrl-Alt-' & Select all edits within a highlighted area of the timeline \\
+ Select Edits & Ctrl-Alt-' & Select all edits within a highlighted area of the timeline * (see note below) \\
- Deselect Edits & & Deselect all edits within a highlighted area of the timeline \\
+ Deselect Edits & & Deselect all edits within a highlighted area of the timeline * (see note below) \\
Copy & Ctrl-c & Copy the selected edits into the copy buffer.\\
clip. Plugins.\\
\bottomrule
\end{longtable}
-\end{center}
\renewcommand{\arraystretch}{1}
+* \textit{If the selection area created is larger than the edits we want to act on and includes additional edits, those edits will be involved if "Select Edits" or "Deselect Edits" is used. Indeed, these options act on both the selected edits and those that are not selected but are included in the selection area created. In practice, edits that were selected are deselected, while unselected edits are selected}.
+
The copy/paste behavior respects the armed/disarmed tracks
state. A paste of audio on a video track will fail and vice versa.
In addition if you attempt to paste edits consisting of more tracks
\begin{center}
\begin{tabular}{lll}
- \toprule
+ \hline
snap\_right\_edit & ctrl+alt+ '.' &\\
snap\_left\_edit & ctrl+alt+ ',' &\\
snap\_right\_label & ctrl+alt +shift '.' & shift+period is the > sign on US keyboards\\
snap\_left\_label & ctrl+alt +shift',' & shift+comma is the < sign on US keyboards\\
- \bottomrule
+ \hline
\end{tabular}
\end{center}
\item Choose the \textit{Select or Deselect edits} option and the clips inside the highlight area will be selected or deselected.
\end{enumerate}
-And there is a Drag mouse way (this requires that the cursor be on the first
+NOTE: \textit{Select Edits/Deselect Edits} option toggle between select and deselect edits. If you have selected an edit and you want to deselect it but select the edits near to it, you can highlight the area and using \textit{Deselect Edits} (or \textit{Select Edits}) the edits near to it will be selected while the edit selected before will be deselected. Of course it works for more edits selected before too. In practice, edits that were selected are deselected, while unselected edits (included in the selection area we created) are selected. If you want to deselect all the selected edits you must use \textit{Clear Select} option by MMB.
+
+There is a Drag mouse way (this requires that the cursor be on the first
clip and from there you start the drag):
\begin{enumerate}
\item To Drag Select edits, hold down Alt+Left Mouse Button (LMB) and drag over the selection area. Releasing the mouse results in selecting.
\end{itemize} Figure~\ref{fig:inter-view01} shows an example of the
Inter-View mode mapping preview mini-window.
\begin{figure}[ht]
+ \centering
\includegraphics[width=0.8\linewidth]{inter-view01.png}
\caption{Inter-View mode: white bar$\rightarrow$source; red
bar$\rightarrow$timeline}
\end{figure}
The vendor supplied \textit{string} device names for the shuttles
-are currently:
+are currently (with the mouse duplication for in at least 1 case:
\texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttlePRO\_v2-event-if00}\\
\texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttleXpress-event-if00}\\
-\texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttlePro-event-if00}
+\texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttlePro-event-if00} \\
+\texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttlePRO\_v2-event-mouse}\\
+\texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttleXpress-event-mouse}\\
+\texttt{/dev/input/by-id/usb-Contour\_Design\_ShuttlePro-event-mouse}
Only 1 necessary initial setup is required due to permission
settings for non-root usage. As root, just copy a file that provides
\begin{center}
\small
- \begin{tabular}{l m{25em}}
- \toprule
+ \begin{tabular}{lm{25em}}
+ \hline
ffmpeg/ffmpeg.opts & global ffmpeg options, always used \\
ffmpeg/decode.opts & global decoder options, used when opening existing files for decoding \\
ffmpeg/encode.opts & global encoder options, used when creating new files for encoding \\
ffmpeg/audio/audio.opts & audio encoder options, used when creating audio streams \\
ffmpeg/video/video.opts & video encoder options, used when creating video streams \\
ffmpeg/plugin.opts & parameters for ffmpeg filters as audio/video plugins \\
- \bottomrule
+ \hline
\end{tabular}
\end{center}
(or) muxer codec | bitstream filter [ bitstream filter options ]
\end{lstlisting}
-where the | represents piping the codec data through the bitstream filter (the bitstream option is is currently not working). The rest of the lines in the file should look as follows:
+where the | represents piping the codec data through the bitstream filter. The rest of the lines in the file should look as follows:
\begin{lstlisting}[style=sh]
# in column one is a comment
\label{cha:faq_problems_workarounds}
\index{workarounds}
-Some workarounds for issues and a few known problems that have not yet been fixed, are described here.
+Some workarounds for issues and a few known problems that have not yet been fixed, are described here. More workarounds can be found \href{https://cinelerra-gg.org/download/Workflow.pdf}{here}.
\paragraph{Workaround for access to modifiable text files when using AppImage.} This includes
such files as FFmpeg video or audio files, fonts that you want to add for usage in the Title
-plugin, icons that you wish to modify, and any other text file for customization.
+plugin, icons that you wish to modify, standalone programs, and any other text file for customization.
To get access, first extract the files from the AppImage, find the files to add, edit, or modify, and then run the extracted binary following the steps shown here.
\begin{itemize}
\item /path-to-appimage/CinGG-20220131-x86\_64.AppImage -{}-appimage-extract
And the Transition effect works fine when there is a transition between two clips/images without
an alpha channel.
+\paragraph{Do not change Color Model Format in session just before loading backup.}
+Under certain circumstance if you change the Color Model in Settings->Format, quit the session,
+and then "Load backup" when you start again, it will crash. Workaround is to avoid this scenario.
+
\paragraph{Audio tracks align with no video track, and in working with Mixers.}
The use of \texttt{Open Mixers} always requires the existence of a video track. See \nameref{ssub:but_use_only_first_audio} We cannot act on audio tracks only, for example to align them. A workaround to get the audio tracks aligned would be:
\item Open/Create a Mixer Viewer from \texttt{Menu $\rightarrow$ Window $\rightarrow$ Mixer\dots $\rightarrow$ Mixer Viewer} (\texttt{Shift+M}).
\item Assign that Mixer Viewer (a white frame is shown when selected) to the one Video tracks (empty) and two Audio tracks, of the \#2 point, pressing the arrow icons (\texttt{Mixer}) you find on the Patchbay on the left of the Main window. When assigned, you must to see the 3 arrow (for 1video + 2Audio) are pointing up.
\item Now, you can use \texttt{Align Mixers} feature as usual. See \nameref{sec:audio_video_sync}
+ \item If you use the Viewer to make a clip and then try to "Open EDL" on that clip in the Resources
+Clip folder window, it will crash. Always use Open EDL with media on the timeline Main Program window.
\end{enumerate}
A big advantage of using the AppImage format is that it is only 1/3 the size of the normal install,
and since each release is named differently, you can keep a number of versions in a directory,
and when testing from a terminal you just have to type CinGG, then hit tab, and complete it to
-the desired date release.
-For 64-bit systems you can choose between an image with up-to-date libraries or one that supports older libraries, which you should use only if the first image gives you problems with unsupported libs. There is also a 32-bit older distro available that has \textit{i686} as part of the filename that currently works on older distros but may not work on the newest distros
+the desired date release. A small disadvantage of using the AppImage format is that some
+of the options to make minor text type changes are not available and any graphics board
+speedups most likely will not work.
+For 64-bit systems you can choose between an image with up-to-date libraries or one that supports older libraries, which you should use only if the first image gives you problems with unsupported libs.
+
+There is also a 32-bit older distro available that has \textit{i686} as part of the filename that currently works on older distros but may not work on the newest distros
(most of the popular Linux distributions such as Arch, Ubuntu, and Fedora have dropped support for this older architecture). In any case, if you are using a 32-bit Linux distro, you should compile your sources from git or use a precompiled binary\protect\footnote{Remember that a 32-bit distro does not address more than 4GB of memory, so you may have stability and performance problems with large, high-resolution mediafiles.}. And there is a 8/10/12 bit newer distro that handles 8 or 10 or 12 bits that has \textit{multibit} as part of the filename. Installing the appimage is simple:
Download the file from:
Some example file names are as follows - where 8 digits represent yyyymmdd:
\begin{lstlisting}[style=sh]
- CinGG-20220131-x86_64.AppImage
+ CinGG-20230131-x86_64.AppImage
(currently based on Fedora 32, linux kernel 5.8.15, libc version 2.31)
- CinGG-20220131-x86_64-older-distros.AppImage
+ CinGG-20230131-x86_64-older-distros.AppImage
(currently based on Ubuntu 16.04, libc version 2.23)
- CinGG-20220131-i686.AppImage
+ CinGG-20230131-i686.AppImage
(currently based on Debian 9, linux kernel 4.9, use "newer" for Debian 11.0)
- CinGG-20220131-i686-newer-distros.AppImage
+ CinGG-20230131-i686-newer-distros.AppImage
(currently based on Debian 11, linux kernel 5.10)
- CinGG-20220131-x86_64-multibit.AppImage
+ CinGG-20230131-x86_64-multibit.AppImage
(currently based on Fedora 32, libc version 2.31)
- CinGG-20220131-x86_64-older-distros-multibit.AppImage
+ CinGG-20230131-x86_64-older-distros-multibit.AppImage
(currently based on Fedora 29 - runs on RHEL8 - linux kernel 4.19.9, libc version 2.28)
+ CinGG-20230930-alternative_shortcuts.AppImage
+ (currently based on Ubuntu 16.04, libc version 2.23)
\end{lstlisting}
Make the file executable with the proper execute permissions either from the GUI of the Desktop Environment used (link to the file) or from a terminal window. Make sure you are already in the directory containing the appimage:
Using AppImage means you can't have the installation folder and work on the files. To unpack the AppImage and get its structure in folders and files see \nameref{sub:managing_appimage} To create, edit and manage appimages see \nameref{sub:built_appimage_scratch}.
+\subsection{AppImage with Standard Shortcuts}
+\label{sec:appimage_standard_shortcuts}
+
+In video editing it is important to learn how to use shortcuts to speed up your work. \CGG{} uses shortcuts different from those considered standard in both the Linux world and video editing. For example, \texttt{"s"} is used instead of \texttt{Ctrl+S}, \texttt{"q"} instead of \texttt{Ctrl+Q}, and even the classic editing keys \texttt{J, K, L} are different.
+In addition, in \CGG{} the keys are fixed and not customizable. A new user may have a hard time getting used to a new combination of shortcuts. To make it a little easier, an appimage containing a patch that makes use of some of the more frequently used classic key combinations is available. It can be downloaded \href{https://cinelerra-gg.org/download/images/CinGG-20230930-alternative_shortcuts.AppImage}{here} (note that the file contains the month and last day of the month, but you will want to go up a directory and download the latest date instead to include the current changes). A table showing the changes from \CGG{} mode to standard mode can be found here: \nameref{sec:alternative_shortcuts}.
+
\section{Download Already Built \CGG{}}%
\label{sec:download_already_built_cinelerra_gg}
\item You need about 6.0 \,GB of disk storage to operate a build and
you need to have \textit{git} installed.
-\item Obviously in order to install into the system, you must run as
- \textbf{root}.
+\item You do not need to be \textbf{root} (or \textit{sudo} ...) to install, except to run \texttt{bld\_prepare.sh} which calls in the distro's package manager. However if there are problems with permissions you can try to compile as root.
\item The \textit{git:} step has to download many files (approx
130\,MB) so allow time. When decompressed this will expand to
\begin{lstlisting}[style=sh]
./blds/bld_prepare.sh <os> # where <os> represents the
# Operating System of
- # centos, fedora, suse, ubuntu, mint, debian, arch, debian-testing, ubuntu-testing.
+ # centos, fedora, suse, ubuntu, mint, debian, arch, debian-older, ubuntu-older.
./autogen.sh
./configure --prefix=/usr # optional parameters can be added here
make 2>&1 | tee log # make and log the build
\end{lstlisting}
- \texttt{bld\_prepare.sh} for Arch Linux may require other packages,
- so you may have to install the dependencies
- manually as you will have to do for gentoo. \texttt{README.arch} or \texttt{README.gentoo}, which
- contain the list of dependencies, can be found at:
- \begin{list}{}{}
+\texttt{bld\_prepare.sh} works for Arch and Gentoo with some additional information. For Arch linux, a README file containing many more dependencies is maintained. For Gentoo, a README file lists other dependencies that have to be installed manually.
+\begin{list}{}{}
\item \href{https://cinelerra-gg.org/download/README.arch}{https://cinelerra-gg.org/download/README.arch}
\item \href{https://cinelerra-gg.org/download/README.gentoo}{https://cinelerra-gg.org/download/README.gentoo}
- \end{list}
-
- \texttt{bld\_prepare.sh} option of debian-testing and ubuntu-testing is currently for future distros and
- will be changed to more relevant names when they are released.
+\end{list}
+
+ \texttt{bld\_prepare.sh} option of debian-older and ubuntu-older is currently for older operating system versions since before about 06/2022.
\item Check for obvious build errors:
\begin{lstlisting}[style=sh]
make install
\end{lstlisting}
Where <os> represents the Operating System supported by \CGG{}, such
-as centos, fedora, suse, ubuntu, mint, debian.
+as centos, fedora, suse, ubuntu, mint, or debian.
The ``with-single-user'' parameter makes it so.
% Make and log build (
Check for errors before proceeding.
\item You need at least 6\,GB of disk storage to operate a build +
you need to have “\texttt{git}” installed.
-\item Recommend you build and run as \textbf{root}, just to avoid
- permission issues initially.
+\item You can install it without being \textbf{root} or without using \textit{sudo}. In case of problems you can use \textit{sudo} to avoid permission issues.
\item The \textit{git} step has to download many files (approx
130\,MB) so allow time.
NOTE: if your system has never had \CGG{} Infinity installed, you
will have to make sure all the compilers and libraries necessary are
-installed. So on the very first build you should run as
-\textbf{root}:
+installed. Thus, for the execution part of \texttt{bld\_prepare.sh} you must use sudo, but the other steps can be done as a normal user.
% FIXME No novels in the listings.
\begin{lstlisting}[style=sh]
make install
\end{lstlisting}
Where <os> represents the Operating System supported by \CGG{}, such
-as centos, fedora, suse, ubuntu, mint, debian.
+as centos, fedora, suse, ubuntu, mint, debian and arch.
The ``with-single-user'' parameter makes it so.
% Make and log build (
Check for errors before proceeding.
Then just start the application by keying in: \texttt{./cin} in the
bin subdirectory OR add a desktop icon by using the appropriate
-directory to copy the files to, run as \textbf{root}, and edit to
+directory to copy the files to and edit to
correct the directory path. Below are generic directions of how to
do this.
Then just start the application by keying in: \texttt{./cin} in the
bin subdirectory OR add a desktop icon by using the appropriate
-directory to copy the files to, run as \textbf{root}, and edit to
-correct the directory path. Below are generic directions of how to
+directory to copy the files to, run as root, and edit to correct the directory path. Below are generic directions of how to
do this.
\begin{lstlisting}[style=sh]
the \texttt{Exec=cin} line to be
\texttt{Exec=<your\_directory\_path>/bin/cin}.
-The preceding directions for doing a single-user build may work
-without being root on some distros except for the \texttt{bld\_prepare.sh}
-and creating the desktop icon. For example in Arch Linux installing without being root
-works using the following steps:
+A working example of how to build in Arch as a normal user:
\begin{lstlisting}[style=sh]
$ git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
$ cd /home/USER/cinelerra5/cinelerra-5.1
$ ./autogen.sh
-$ ./configure --prefix=/usr --with-single-user --with-booby
+$ ./configure --with-single-user --with-booby
$ make 2>&1 | tee /tmp/cin5.log && make install
+$ mv Makefile Makefile.cfg
+$ cp Makefile.devel Makefile
\end{lstlisting}
-
\subsection{Notable Options and Caveats}%
\label{sub:notable_options_and_caveats}
\index{./configure}
success. Included in this section are some of the build variations
easily available for normal builds.
+You can, during compilation, use a patch that changes the main non-standard shortcuts of \CGG{} to standard ones (\texttt{Ctrl+S} and \texttt{J, K, L}, etc.).
+A table showing the changes from \CGG{} mode to standard mode can be found here: \nameref{sec:alternative_shortcuts}.
+The instructions for the build with the patch are as follows. After downloading the sources from the git repository in the usual way, you apply the patch:
+
+\begin{lstlisting}[style=sh]
+ cd cinelerra-5.1
+ patch -p1 -i alt_shortcuts.patch
+ ./bld.sh
+\end{lstlisting}
+
To see the full list of features use:
\begin{lstlisting}[style=sh]
have already installed libraries which are normally in the
thirdparty build, getting them to be recognized means you have to
install the \textit{devel} version so the header files which match
-the library interfaces exist. Below is the list of thirdparty
+the library interfaces exist. If you want to build using only the
+thirdparty libraries installed in your system, just include
+"--without-thirdparty" to your configure script. For example:
+\begin{lstlisting}[style=sh]
+./confgure --with-single-user --disable-static-build --without-thirdparty
+\end{lstlisting}
+Below is the list of thirdparty
builds, but this list may have changed over time.
% It's list of Table?
If you have a problem with the current GIT version, you can revert
to a previous working version easily. The commands to use will be
similar to these next lines which are then explained in more detail.
+You need "history" to do this, so should not have used the "depth 1"
+parameter on your GIT.
\strut
\begin{lstlisting}[style=sh]
gdb ./ci
\end{lstlisting}
+When you get the gdb prompt, type the letter "r", for run, and the windows will come up.
+If there is a crash, the windows will freeze and typing "bt" for backtrace in the startup window
+after the gdb prompt, provides useful information.
+
\subsection{Unbundled Builds}%
\label{sub:unbundled_builds}
\url{https://wiki.termux.com/wiki/Package\_Management}
\newline \url{https://wiki.termux.com/wiki/Building\_packages}
-\section{Distro with \CGG{} Included}%
+\section{Pre-built Packages and Distros with \CGG{} Included}%
\label{sec:distro_with_cinelerra_included}
\index{linux distro}
There are also some special complete distribution systems
available that include \CGG{} for audio and video production
-capabilities.
+capabilities as well as some pre-built packages in a build farm.
+
+\subsection{Build Farm pre-built Deb and RPM packages}
+\label{sec:packages}
+Especially advantageous to the way some users prefer to keep CinelerraGG updated
+is the build farm for \CGG{} deb and rpm packages that is maintained regularly
+at this location \url{https://github.com/einhander/cin-gg-packages/releases}.
+It will build packages on every git change in the main repo with
+releases corresponding to a build date, not a git commit date.
+Current build hosts are \textbf{Debian 12}, \textbf{Debian 11},
+\textbf{Suse Leap 15.5}, \textbf{Fedora 38}, and \textbf{Ubuntu 22.04}.
+This build farm creates packages for the latest current versions of these
+distros with the potential for additional distros to be added in the future.
+In addition, packages for some previously built dates will still be available
+in case you want to revert to a specific package date.
\subsection{AV Linux}
\label{sec:AV_Linux}
Click \href{https://www.elivecd.org/}{Elive} for more information. The \CGG{} packages for the program
and the manual are in the direcotry at
+\href{https://repo.bookworm.elive.elivecd.org/pool/multimedia/c/} {Bookworm version 12} and
\href{https://repo.bullseye.elive.elivecd.org/pool/multimedia/c/} {Bullseye version 11} and
\href{http://repo.buster.elive.elivecd.org/pool/multimedia/c/}{Buster version 10} - just download
the .deb files inside that directory and install via “dpkg -i “.
\end{itemize}
\end{description}
+\paragraph{NOTE:} In \CGG{} the editing workflow is different from the workflow used by other NLEs. It is less intuitive and requires us to think first about what we want to achieve. In fact, it is a workflow based on the tracks in their entirety and not on individual clips. See \href{https://cinelerra-gg.org/download/Workflow.pdf}{workflow is different!} for a comparison with the Adobe Premiere Pro workflow.
+
\section*{Chapters Overview}%
\label{sec:chapters_overview}
$\leftarrow$ Keyframe $\rightarrow$ Plugin
\includegraphics[height=\baselineskip]{plugin.png}
+It is important to understand the fundamental difference between \CGG{} \textit{Autos} (zoom,
+pan, etc.) is that \textit{Autos} are interpolable in any way (linear, bezier, etc.) while
+\textit{Plugin keyframes} may be interpolable in various ways or not be interpolable at all.
+
\section{Automation Keyframes /\,Autos}%
\label{sec:automation_keyframes_autos}
\index{keyframes!autos}
Curve smoothing is called \textit{interpolation} and it uses keyframe point values and control values that determine how the curve will react at the time the media is played or rendered. Interpolation uses 2 keyframes to create a set of intermediates which are used as active values between the \textit{previous} and \textit{next} keyframe anchors on the timeline. The way the intermediate data is generated depends on the type of curve used to invent these values. \CGG{} interpolates the intermediate values making the change happen smoothly and gradually over time. The simple linear mathematical formula for interpolation is: $a\times(1-t) + b\times t$ where $0\le t\le 1$ uniformly.
+Autos are handled inside the main executable. Therefore \CGG{} knows exactly what a particular Auto does, how to interpret it, and how it can be interpolated.
+
\section{Using Autos}%
\label{sec:using_autos}
\end{enumerate}
\end{itemize}
-You can click mouse button 3 on a keyframe box \index{keyframes!MMB options} and a menu pops up with the first menu item showing the keyframe type. The top menu item can be activated for immediate access to update the automation keyframe value. Some keyframe types, which have values that can be manipulated in another way than by dragging the color coded line, now show up with a different colored background to make them more visible. Keep in mind that Zoombar \index{zoom!panel} ranges/values must be set to appropriate values when working with specific keyframe types, such as Fade or Speed. If you do not see the auto line in the visible area of the video track, try the key combination Alt-f or select the speed in the \textit{Automation Type} drop-down menu at the bottom of the main window. To the right of this field is \textit{Automation Range} where you can set the display ratio of these lines. Simply change the values until the lines are visible again.
+You can click mouse button 3 (RMB) on a keyframe box \index{keyframes!MMB options} and a menu pops up with the first menu item showing the keyframe type. The top menu item can be activated for immediate access to update the automation keyframe value. Some keyframe types, which have values that can be manipulated in another way than by dragging the color coded line, now show up with a different colored background to make them more visible. Keep in mind that Zoombar \index{zoom!panel} ranges/values must be set to appropriate values when working with specific keyframe types, such as Fade or Speed. If you do not see the auto line in the visible area of the video track, try the key combination Alt-f or select the speed in the \textit{Automation Type} drop-down menu at the bottom of the main window. To the right of this field is \textit{Automation Range} where you can set the display ratio of these lines. Simply change the values until the lines are visible again.
Figure~\ref{fig:overlays1} and figure~\ref{fig:fade} shows several color coded lines for different key\-fra\-mes and specifically the slider bar for the Fade keyframe. It is in the same color as the color coded keyframe type line which is the same color which would be shown in the \textit{Show overlays} window figure~\ref{fig:overlays_window}.
you just right mouse it and change to either Tangent or Disjoint edit.
In the screencast to the right, the Fade Auto has pink colored curves and control points are seen as dashed lines next to the keyframe box with black filled circles on each end of the line. Use the Ctrl key with the left mouse button to modify the control point lines.
+See \ref{sec:workflow_keyframes_plugins} for a pratical example.
+
\section{Speed\,/\,Fade Automation Usage and Auto Gang}%
\label{sec:speed_fade_automation_gang}
\index{keyframes!auto gang}
\begin{enumerate}
\item Use the pulldown menu \textit{View} on the main canvas and ensure that there is a checkmark left of the Speed or Fade selection.
- \item Double click and hold button 1 on any point of the Speed line on any track of the main track canvas and drag the handle where you want it, then release button 1.
+ \item Double click and hold button 1 (LMB) on any point of the Speed line on any track of the main track canvas and drag the handle where you want it, then release button 1 (LMB).
\item Note how all video and audio boxes move together simultaneously for synchronization.
\item You can adjust the sampling rate (speed/fade) at any time by doing the same single/double
click on a keyframe.
- \item To move the location left or right, hold down button 1 while moving it back and forth.
+ \item To move the location left or right, hold down button 1 (LMB) while moving it back and forth.
\item Use the status bar in the lower left hand corner to see position and playback rate.
\end{enumerate}
-Releasing button 1 ends the current dragging operation, but single clicking on a speed/fade keyframe handle again will restart the drag operation on tracks of the same type. Double clicking will select all armed tracks which have handles in the exact same cursor position. It is sometimes difficult to get the desired value for the speed and it may take a few tries to get to the desired endpoint, but you can use an auto slider bar to get better control for more precision. This is not ganged so you will have to do this on each track to achieve the same value.
+Releasing button 1 (LMB) ends the current dragging operation, but single clicking on a speed/fade keyframe handle again will restart the drag operation on tracks of the same type. Double clicking will select all armed tracks which have handles in the exact same cursor position. It is sometimes difficult to get the desired value for the speed and it may take a few tries to get to the desired endpoint, but you can use an auto slider bar to get better control for more precision. This is not ganged so you will have to do this on each track to achieve the same value.
An easy way to get an exact position is to set the \textit{Automation range} in the bottom bar of the main
window to the low and high ends of the desired range. For example, 1.000 to 50.000, which makes it
so you can drag the speed/fade handle all the way to the left for 1.000 or all the way to the right for 50.
-Figure~\ref{fig:always} shows orange keyframes and lines for the ganged speed automation on all video/audio tracks. The figure shows the orange speed slider bar triangle with the current value displayed via the tooltip. Note the status bar numbers in the lower lefthand corner displaying 01:08 seconds as the location and 2.05 as the playback rate.
+Figure~\ref{fig:speed} shows orange keyframes and lines for the ganged speed automation on all video/audio tracks. The figure shows the orange speed slider bar triangle with the current value displayed via the tooltip. Note the status bar numbers in the lower lefthand corner displaying 01:08 seconds as the location and 2.05 as the playback rate.
\begin{figure}[htpb]
\centering
Plugins also may use interpolation to smooth the data between the keyframe paramaters on the timeline. Just exactly how this is done varies with the plugin and is not always easy to predict, but this
is usually due to the nature of the keyframe parameter data. For example, it does not make sense to interpolate which font is in use.
+Plugin keyframes are handled inside its own plugin. \CGG{} knows nothing about internal functionalities inside plugins, either external (such as ffmpeg) or native plugins. And has no chance to do
+any interpolation. Only the plugin can interpolate its own keyframes. And if you succeed to add plugin keyframe interpolation in some particular plugin, all the other (even similar in functionality) plugins will know nothing about it. So, each one out of dozen of plugin keyframes has to be implemented individually.
+
\section{Default Keyframe}%
\label{sec:default_keyframe}
\index{keyframes!default keyframe}
\label{sec:keyframe_edit_params_plugin}
\index{plugins!preset edit}
-Keyframe values can be set using the various plugin \textit{plugins: show controls} \index{plugins!show controls} (magnifying glass) icon on the plugin track (figure~\ref{fig:parameters}). It is possible to see all of the keyframe data in a raw format using the \textit{Edit Params} popup menu item which you will see when you right mouse click the keyframe icon on the timeline. The keyframe data is stored in xml format, and the \textit{edit params} feature allows you to view and modify the xml data directly. This normally should not be necessary since the plugin's control gui displays the intended parameters, but this will let you view and specify just about anything that can be specified in xml. There is no validation checking of the modified data.
+Keyframe values can be set using the various plugin \textit{plugins: show controls} \index{plugins!show controls} (magnifying glass) icon on the plugin track (figure~\ref{fig:parameters}).
\begin{figure}[htpb]
- \centering
- \includegraphics[width=0.7\linewidth]{parameters.png}
- \caption{Keyframe Parameters window for a Color 3 Way plugin added to the video track}
- \label{fig:parameters}
+ \centering
+ \includegraphics[width=0.7\linewidth]{parameters.png}
+ \caption{Keyframe Parameters window for a Color 3 Way plugin added to the video track}
+ \label{fig:parameters}
\end{figure}
+It is possible to see all of the keyframe data in a raw format using the \textit{Edit Params} popup menu item which you will see when you right mouse click the keyframe icon on the timeline. The keyframe data is stored in xml format, and the \textit{edit params} feature allows you to view and modify the xml data directly. This normally should not be necessary since the plugin's control gui displays the intended parameters, but this will let you view and specify just about anything that can be specified in xml. There is no validation checking of the modified data.
+
\section{Generate Keyframes while Tweaking / Automatic Keyframe Mode}%
\label{sec:generate_keyframe_tweaking}
\index{keyframes!automatic mode}
-Tweaking is defined as changing a parameter while playing -- it can be small changes or small motion increments performed in a series. These changes are recorded as a series of new keyframes on the timeline. Enable automatic keyframe mode by enabling the automatic keyframe toggle, that is \textit{Generate keyframes while tweaking}. In automatic keyframe mode, every time you tweak a key-framable parameter it creates a keyframe on the timeline. Since keyframes affect playback, you should enable generate keyframes just before you need a keyframe and disable when your parameter changes are complete. So turn on when ready to make changes and turn off when done!
+Tweaking is defined as changing a parameter while playing -- it can be small changes or small motion increments performed in a series. These changes are recorded as a series of new keyframes on the timeline. Enable automatic keyframe mode by enabling the automatic keyframe toggle, that is \textit{Generate keyframes while tweaking}. In automatic keyframe mode, every time you tweak a key-framable parameter it creates a keyframe on the timeline (visible by activating the respective \textit{Camera x, y, z} and \textit{Projector x, y, z} curves). Since keyframes affect playback, you should enable generate keyframes just before you need a keyframe and disable when your parameter changes are complete. So turn on when ready to make changes and turn off when done!
Also, before making a change, be sure to check the \textit{View} pulldown and make the desired parameter visible with the enable checkmark. The location where the automatic keyframe is generated is under the insertion point. If the timeline is playing back during a tweak, several automatic keyframes may be generated as you change the parameter. When automatic keyframe mode is disabled, adjusting a parameter adjusts the keyframe immediately preceding the insertion point. For example, if two fade keyframes exist and the insertion point is between them, changing the fader changes the first keyframe.
\label{sec:compositor_keyframes}
\index{keyframes!compositor}
-Camera and projector translation is represented by two parameters: \textit{x} and \textit{y}, making it difficult to adjust with curves. \CGG{} solves this problem by relying on automatic keyframes. With a video track loaded, move the insertion point to the beginning of the track and enable automatic keyframe mode. Move the projector slightly in the compositor window to create a keyframe. Then go forward several seconds. Move the projector a long distance to create another keyframe and emphasize motion. This creates a second projector box in the compositor, with a line joining the two boxes. The joining line is the motion path. If you create more keyframes, more boxes are created. Once all the desired keyframes are created, disable automatic keyframe mode.
+Camera and projector translation is represented by two parameters: \textit{x} and \textit{y}, making it difficult to adjust with curves. \CGG{} solves this problem by relying on automatic keyframes. With a video track loaded, move the insertion point to the beginning of the track and enable automatic keyframe mode. Move the projector slightly in the compositor window to create a keyframe (visible by activating the \textit{Projector x, y, z} curves). Then go forward several seconds. Move the projector a long distance to create another keyframe and emphasize motion. This moves the projector box to its new position. If you create more keyframes, we can move the box several times. Once all the desired keyframes are created, disable automatic keyframe mode.
-Dragging the auto curve with tweaking off, adjusts the previous keyframe. With tweaking on, if no keyframe is at the timeline position, then a new one is created at that position and the modification value is applied. If you are halfway between two keyframes, the first projector box is adjusted while the second one stays the same. The video does not appear to move in step with the first keyframe. This is because halfway between two keyframes, the projector translation is interpolated. In order to set the second keyframe you will need to move after the second keyframe.
+Dragging the auto curve with tweaking off, adjusts the previous keyframe. With tweaking on, if no keyframe is at the timeline position, then a new one is created at that position and the modification value is applied. If you are halfway between two keyframes, the value from the previous box position will be altered, while the second is not changed. The video does not appear to move in step with the first keyframe. This is because halfway between two keyframes, the projector translation is interpolated. In order to set the second keyframe you will need to move after the second keyframe.
Image translation, motion direction, and speed determine the results. Motion varies based on the interpolation type that is set, for example, if set to Linear, the result will be uniform straight line motion. Smooth is the default so that interpolation will generate curved lines with control points. Ctrl-drag the endpoint of the control handle to adjust the curved slope.
\index{save media files}
\index{EDL}
+The media files loaded into the Resources window are called \textit{assets} and are virtual references to the real media files on disk. The original sources are not changed and so we have non-destructive editing.
+
There are many supported file formats that can be loaded and rendered to, that is to say, imported and exported.
The format of the file affects what \CGG{} does with it.
Some file formats are very slow to display on the timeline, especially video which is highly compressed.
Raw DV and PCM,
MPEG Audio and Video.
-\paragraph{Still Images:} JPEG/EXR/GIF/PNG/PPM/TGA/TIFF
+\paragraph{Still Images:} JPEG/EXR/GIF/PNG/PPM/TGA/TIFF. Note: even if \CGG{} outputs fp32, exr/tiff values there are normalized to 0-1.0f.
\paragraph{MPEG Files:}
What is an MPEG file? A very common file format is MPEG because it works with many cameras and televisions. Mpeg2 video, an elementary codec stream for mpeg files, is the most common format. To read this format you need to decode the mpeg stream. You can read and write mpeg natively. Mpeg video encoding is done separately from mpeg audio encoding when using the native file format, meaning that 2 passes are required and then they have to be muxed together. However, if using ffmpeg it is rendered in only 1 pass. DVD uses MPEG as does NTSC and Pal.
./DSC04998.jpg
\end{lstlisting}
+Another advantage of using image sequences of exr, jpeg, png, ppm tiff, and tga is that if you
+then render to anoher of the same sequence type, a direct copy speed up can be used for any
+of the unmodified frames.
+
\subsubsection{Image2ffmpeg}%
\label{ssub:image2ffmpeg}
\index{image sequence}
When blending source and destination shapes (Dst and Src), the shape boundaries can be changed with the alpha blending effects. There are a total of 10 standard Porter-Duff operators, but there are 30 possible overlay modes used in \CGG{}. Each is characterized by its value in the four regions: source, destination and both, with the \textit{neither} region always being blank. The source and destination regions can either be blank or filled with the source or destination colors. A specific compositing math formula is used to calculate effect. This is only applicable to RGB; some effort has been made to accommodate YUV, but the effects are not as predictable, and may not be useful.
Below, in figure~\ref{fig:normal}, are the results of utilizing the 30 available operations within \CGG{} as listed on a following page. Src is the solid green rectangle and Dst is the solid red rectangle. There are better illustrations of what alpha blending can do, however for consistency sake, these are the results when using standards.
+For an alternative set of source video illustrations, see \nameref{sec:altviews}.
\begin{figure}[htpb]
\centering
The previous math forms are the only truly accurate description of each blending operation, but short descriptions are below where \textit{Source} is the output from the next track and \textit{Destination} is the output from the lower track stacking. Blending starts with new Source and combines it with the previous render stack output, which is referred to as Destination. The new output becomes the next Destination and the next up stack level becomes the new Source. Source is above; Destination is below.
-Note: the Graphic Art group operates principally on color, and the others operate principally on alpha.
+Some notable items that affect the results are listed here.
+\begin{enumerate}
+ \item So as not to be surprised by the results, set your Video Driver to X11, not X11-OpenGL, because when rendering your video no graphics library is used. Rendering is handled in software and there is sometimes anomaly differences when using the OpenGL driver.
+ \item The Graphic Art group operates principally on color, and the others operate principally on alpha.
+ \item When using the Title plugin with text, blending or changes in the text will only take affect in Subtract, Divide, and Difference. This matches the implmentation of the original Cinelerra version.
+ \item If comparing results with the original Cinelerra version for Subtract and Divide, you may have to switch the order of the source and destination tracks to see the same output. If you do not want to switch tracks, you can use the \textit{overlay} plugin as shared and change the Layer order and/or Output layer. The reason for having to switch tracks to get equivalent output is because of differences in the math formulas used. Subtract exactly matches the original Cinelerra version if you switch the 2 tracks; Divide matches in one order only.
+ \item Instead of using the patchbay overlays, you may prefer to use the \textit{overlay} plugin instead.
+ \item If you see undesirable results, always check under Settings->Format and check your Color Model as that will vary or interfere with the look.
+\end{enumerate}
% Leave the word Group in due to latex2html dual name conflict
\subsection*{Normal Group}%
Standard numerical operations.
\begin{description}
- \item[Addition:] The source is added to the destination and replaces the destination. Addition mode is very simple - the pixel values of the upper and lower layers are added to each other. The resulting image is normally brighter. The equation can result in color values greater than $255$, so some of the light colors may be clipped to the maximum value of $255$. Math formula is the same as that used by SVG but different than Gimp.
- \item[Subtract:] Subtract mode reduces the pixel values of the upper layer by the pixel values of the lower layer. The resulting image is normally darker. You might get a lot of black or near-black in the resulting image. The equation can result in negative color values, so some of the dark colors may be clipped to the minimum value of $0$. Math formula used is different than that used by Gimp; there is no SVG equivalent.
+ \item[Addition:] The source is added to the destination and replaces the destination. Addition mode is very simple - the pixel values of the upper and lower layers are added to each other. The resulting image is normally brighter. The equation can result in color values greater than $255$, so some of the light colors may be clipped to the maximum value of $255$. Math formula is the same as that used by SVG but slightly different than Gimp.
+ \item[Subtract:] Subtract mode reduces the pixel values of the upper layer by the pixel values of the lower layer. The resulting image is normally darker. You might get a lot of black or near-black in the resulting image. The equation can result in negative color values, so some of the dark colors may be clipped to the minimum value of $0$. Math formula used is different than that used by the Gimp "Default" version, but you can get the same as the "Legacy" version if you switch the 2 tracks or use the \textit{overlay} plugin and switch to Top first. There is no SVG equivalent.
\item[Multiply:] The source color is multiplied by the destination color and replaces the destination. The resulting color is always at least as dark as either the source or destination color. Multiplying any color with black results in black. Multiplying any color with white preserves the original color. Math formula is the same as used by SVG and Gimp.
- \item[Divide:] Divides source color by destination color. If the source color is white, the result color is the underlying color. The resulting image is often lighter. Math formula used is different than that used by Gimp; there is no SVG equivalent.
- \item[Replace:] Replace mode will cause any existing destination to be replaced by the source media. Mathematical formula used is the same as used by Gimp; there is no SVG equivalent.
+ \item[Divide:] Divides source color by destination color. If the source color is white, the result color is the underlying color. The resulting image is often lighter. Math forumula is different than that of Gimp, but by changing the order of the Source and Destination tracks you can get the same results in some cases (this is true for the original Cinelerra version also). There is no SVG equivalent.
+ \item[Replace:] Replace mode will cause any existing destination to be replaced by the source media. Math formula used is the same as used by Gimp; there is no SVG equivalent.
\end{description}
\subsection*{Porter-Duff Group}%
\item[Softlight:] Darkens or lightens the colors, dependent on the source color value. If the source color is lighter than 0.5, the destination is lightened. If the source color is darker than $0.5$, the destination is darkened, as if it were burned in. The degree of darkening or lightening is proportional to the difference between the source color and $0.5$. If it is equal to $0.5$, the destination is unchanged. Using pure black or white produces a distinctly darker or lighter area, but does not result in pure black or white. The effect is similar to shining a diffused spotlight on the destination. A layer with pure black or white becomes markedly darker or lighter, but does not become pure black or white. Soft light is not related to “Hard light” in anything but the name, but it does tend to make the edges softer and the colors not so bright. Math formula is the same as used by Gimp; SVG formula differs.
\end{description}
+\section{Alternative Views of Overlay Modes}%
+\label{sec:altviews}
+
+An alternative set of source videos used to provide a different real world view is shown here to help illustrate alpha blending. They use a landscape photo as one and the other is half of a color and half of a black and white gradient photo. First is shown the Aritmetic, Logical, and Graphic-Art views.
+After that the Porter Duff overlays are shown using the same source videos but
+with each of the Source videos offset in a different direction so that the
+generated output is more obvious.
+
+\begin{figure}[ht]
+ \centering
+ \includegraphics[width=1.0\linewidth]{normal2.png}
+ \caption{Normal and Arithmetic overlays}
+\end{figure}
+
+\begin{figure}[ht]
+ \centering
+ \includegraphics[width=1.0\linewidth]{logical2.png}
+ \caption{Logical overlays}
+\end{figure}
+
+\begin{figure}[ht]
+ \centering
+ \includegraphics[width=1.0\linewidth]{graphic-art2.png}
+ \caption{Graphic Art overlays}
+\end{figure}
+
+\begin{figure}[ht]
+ \centering
+ \includegraphics[width=1.0\linewidth]{porter-duff2.png}
+ \caption{Offset source videos to illustrate Porter Duff overlays}
+\end{figure}
+
+\begin{figure}[ht]
+ \centering
+ \includegraphics[width=1.0\linewidth]{porter-duff3.png}
+ \caption{Porter Duff overlays}
+\end{figure}
+
+
%%% Local Variables:
%%% mode: latex
There are realtime effects -- these are the most useful and probably all you will ever need -- and rendered effects.
The rendered effects are discussed separately in the \nameref{sec:rendered_effects} section.
+Effects that begin with the characters F\_ are effects that are part of the FFmpeg software
+as opposed to those coded within the \CGG{} program. These are discussed separately in
+\nameref{sec:ffmpeg_audio_video_plugins}.
Effect plugins modify the track when played, according to how they are set, with no permanent storage of the output except when the project is rendered. There are many Plugins in \CGG{} Infinity which are actually quite easy to use just by experimenting with them. The plugins are shown and selected from the \textit{Resources window} (figure~\ref{fig:video-plugins}). They are described in more detail later.
\begin{figure}[htpb]
\CGG{}’s default setup is in the file \texttt{\$CIN\_DAT/expan\-ders.txt} but if the user wants their own specific setup and if the file in \texttt{\$HOME/.\\bcast5/expanders.txt} exists, it will take precedence.
If there are recommendations for other relevant categories, they can be added. The subtree structure is applicable to any of the \textit{Video Effects/Transitions} or \textit{Audio Effects/Transitions}. You can not sort once an expansion is in effect (figure~\ref{fig:expander}).
-The \texttt{expanders.txt} file has very specific requirements. The most specific is that there are no blanks -- you must use tabs only. A \# (pound sign) can be used in column 1 to indicate a comment. Here is a short example:
+The \texttt{expanders.txt} file has very specific requirements. The most specific is that there are no blanks -- you must use tabs only. A \# (pound sign) can be used in column 1 to indicate a comment. A short example of what the txt file looks like is shown below.
\begin{figure}[htpb]
\centering
\begin{lstlisting}[style=sh]
Video Effects
+ -Favorites
+ Brightness/Contrast
+ Title
+ VideoScope
- Color_Correction
Blue Banana
Color 3 Way
L2_Calf Fluidsynth
\end{lstlisting}
+NOTE: The capability to put the expanders.txt file in \texttt{./bcast5} (see \nameref{sec:bcast5}) allows for customizations such as grouping favorite plugins in one section so that they can be recalled more quickly. For this purpose, the \textit{Favorites} section has been included at the top of Video Effects, the contents can be changed as desired. Once your modified file is saved to hard disk as \$HOME/.bcast5/expanders.txt it will remain in use on every update as long as you do not delete it or remove the .bcast subdirectory.
+For users running \CGG{} using the AppImage, to make an initial copy of expanders.txt, execute the
+following lines on /tmp:
+\begin{lstlisting}[numbers=none]
+ git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
+ cp /tmp/cinelerra5/cinelerra-5.1/expanders.txt $HOME/.bcast5/expanders.txt
+\end{lstlisting}
+
\subsection{Speed-up of Ffmpeg plugin usage with OPTS files}%
\label{sub:speedup_ffmpeg_plugin_opts}
\index{plugins!speed-up via options}
\index{delay audio}
In the Delay Audio effect you can specify the number of seconds you want to delay the video track.
+An alternative ffmpeg plugin is F\_adelay.
\subsection{DeNoise}%
\label{sub:denoise}
\item[Damp:] echo envelope decay factor used to smooth the cepstrum/correlation data.
\item[Peaks:] number of maximal envelope values used in the echo gain calculation.
\item[Cutoff Hz:] low frequency cutoff value to prevent beat frequency (\textit{heterodyne}) echo canceling.
- \item[Mode:] \textit{MAN}, \textit{Off}, or \textit{On}. When Off is selected, the plugin is not active. When MAN is used, the only one peak is used for the echo gain envelope. It is set by pressing mouse button $1$ in the ceptstrum graphical output. The Gain and Offset are updated as the pointer drag operation resets the indicated gain and offset values. When On is selected, the echo gain envelope is automatically calculated by cepstrum and auto-correlation of the input audio in the last window size audio samples.
+ \item[Mode:] \textit{MAN}, \textit{Off}, or \textit{On}. When Off is selected, the plugin is not active. When MAN is used, the only one peak is used for the echo gain envelope. It is set by pressing mouse button $1$ (LMB) in the ceptstrum graphical output. The Gain and Offset are updated as the pointer drag operation resets the indicated gain and offset values. When On is selected, the echo gain envelope is automatically calculated by cepstrum and auto-correlation of the input audio in the last window size audio samples.
\item[Windows size:] parameter can be set to \textit{Default}, $1024$, $2048$, \dots \textit{doubled values\dots} up to $262144$.
\item[Amplitude:] the cepstrum value at the drag point during manual envelope selection.
\item[Gain:] echo gain setting determined by manual selection.
Allows you to convert an audio file from one sample rate to another. This effect works similarly to ReframeRT in videos.
\begin{center}
- \begin{tabular}{l l}
+ \begin{tabular}{ll}
\toprule
Input / output > 1 & fast rate \\
Input / output < 1 & slow rate \\
LV2\protect\footnote{Optional Feature - OS dependent} is an open standard for audio plugins using a simple interface with extensions which add functionality to support audio software. These plugins were written by external developers and provide additional audio effects to \CGG{} audio without having to change \CGG{} every time. Because the LV2 plugins are separate from \CGG{} Infinity, if one fails or does not perform as expected, \CGG{} should stay running and you will have to contact the programmers responsible for that plugin for a fix.
-Typically, a user OS has specialized package groups installed. It is difficult to create one build of \CGG{} to accommodate all potential LV2 plugins. Specifically for the \textit{Calf-Studio LV2 plugins}, you should install the \textit{Calf Plugins} package. The user’s computer must have \textit{gtk-2-runtime} installed, which seems to be automatically done already for most distros. For users doing their own builds, you can build \CGG{} without LV2 support by including \texttt{-{}-without-lv2} in the configure step. The default build is \texttt{-{}-with-lv2=yes} and requires that \textit{GTK-2-devel} must be installed or the build will fail and notify you. In addition for some newer distros, you will need to install
+Typically, a user OS has specialized package groups installed. It is difficult to create one build of \CGG{} to accommodate all potential LV2 plugins. Specifically for the \textit{Calf-Studio LV2 plugins}, you should install the \textit{Calf Plugins} package. Note that because the Calf Plugins have a graphics UI interface which is dependent on specific hardware, they will not work with AppImage. The user’s computer must have \textit{gtk-2-runtime} installed, which seems to be automatically done already for most distros. For users doing their own builds, you can build \CGG{} without LV2 support by including \texttt{-{}-without-lv2} in the configure step. The default build is \texttt{-{}-with-lv2=yes} and requires that \textit{GTK-2-devel} must be installed or the build will fail and notify you. In addition for some newer distros, you will need to install
\textit{lv2-calf-plugins-gui}; for example Fedora version 32.
LV2 plugins have their own category in the \textit{Audio Plugins Visibility} as lv2. There is a simple text interface which is available via the usual \textit{Show controls} button when the plugin is attached to the audio track. This window has a Reset button to get back to the default settings. To change a value of one of the parameters, highlight that parameter and type in the new value in the topmost text box and then hit Apply to take effect -- the reason for requiring hitting apply is so that the audio is not moving all over the place while you are still typing a value. More easily, you can just move the \textit{pot dial} or the \textit{slider} bar which take effect automatically.
\label{sub:blue_banana}
\index{blue banana}
-Blue Banana\protect\footnote{credit to Monty Montgomery programmer} is an \textit{HSL Qualifier} \index{HSL Qualifier} (HSL= hue, saturation, lightness), one of the basic tools of any grading software that are based on circumscribing a zone of the frame by extracting a chromatic key and producing a \textit{matte} in the alpha channel (Secondary Color Correction). Blue Banana differs not by creating a real matte, but by creating a \textit{selection mask} exclusively for use within the plugin. The BlueBanana plugin has a couple of useful purposes. It can be used for color transformation or remapping -- by isolating a specific color and then performing color change/correction on only that color (or color ranges). Another useful purpose is for chroma-key filtering, using multiple BlueBanana plugins on the same track. Also, it can be used in conjunction with the mask operation of the Compositor. Usage of BlueBanana may seem complicated at first, but it is necessarily so in order to get enough control to produce the desired effect simply and quickly. Just changing a single color is actually quite easy. BlueBanana is keyframable (figure~\ref{fig:bluebanana}).
+Blue Banana\protect\footnote{credit to Monty Montgomery programmer} is an \textit{HSL Qualifier} \index{HSL Qualifier} (HSL= Hue, Saturation, Luminance; HSV in our plugin, with V = Value), one of the basic tools of any grading software that are based on circumscribing a zone of the frame by extracting a chromatic key and producing a \textit{matte} in the alpha channel (Secondary Color Correction). Blue Banana differs not by creating a real matte, but by creating a \textit{selection mask} exclusively for use within the plugin. The three H, S and V sliders are called \textit{qualifiers}. The BlueBanana plugin has a couple of useful purposes. It can be used for color transformation or remapping -- by isolating a specific color and then performing color change/correction on only that color (or color ranges). Another useful purpose is for chroma-key filtering, using multiple BlueBanana plugins on the same track. Also, it can be used in conjunction with the mask operation of the Compositor. Usage of BlueBanana may seem complicated at first, but it is necessarily so in order to get enough control to produce the desired effect simply and quickly. Just changing a single color is actually quite easy. BlueBanana is keyframable (figure~\ref{fig:bluebanana}).
The basic strategy for BlueBanana is to:
\begin{itemize}
- \item Select a specific target color.
+ \item Select a specific target color with the eyedropper tool.
\item Create a selection region by expanding color ranges around that color.
\item Optionally reduce or expand the alpha plane as a regional selection mask.
\item Optionally apply a color remapping or transformation to the selection.
\begin{enumerate}
\item There are color strips under color Adjustment which will show color changes as you modify values.
\item Uncheck Mark Selected Areas and check the Filter Active box to the right of Color Adjustment.
- \item As needed, you can individually check and uncheck all the various parameters using the boxes to the left of each line. Again, these are intuitive and broadly similar to the above. The arrows at the bottom widen the range, the circle at the bottom moves the range, and the top slider, which is an arrow this time, affects distribution. It provides a little histogram effect to give you an idea of what you're changing. The fade adjusts the level of color blending. The alpha is basically the opacity of your changes.
+ \item As needed, you can individually check and uncheck all the various parameters using the boxes to the left of each line. Again, these are intuitive and broadly similar to the above. The arrows at the bottom widen the range, the circle at the bottom moves the range, and the top slider, which is an arrow this time, affects distribution. It provides a little histogram effect to give you an idea of what you are changing. The fade adjusts the level of color blending. The alpha is basically the opacity of your changes.
\end{enumerate}
\end{description}
Definition of Wording/Checkboxes/Buttons/Operators are being described next. Some of the commentary was adopted from information provided by \textit{Monty Montgomery} and from questions and answers from email by \textit{Igor Ubuntu}, who did extensive testing.
-\subsubsection*{Operational characteristics for the \textbf{color-related adjusters}:}
+\subsubsection*{Operational characteristics for the color-related adjusters:}
\label{ssub:operational_characteristic_color}
\begin{description}
- \item[left arrow slider] operates the range minimum; the numerical value shows in the left-most textbox.
- \item[right arrow slider] operates the range maximum; resulting numerical value is in the middle textbox.
+ \item[left arrow slider] operates the range minimum (left edge); the numerical value shows in the left-most textbox.
+ \item[right arrow slider] operates the range maximum (right edge); resulting numerical value is in the middle textbox.
\item[middle circle slider below] can move the current range up or down and the numerical results will show in the left and middle textbox. Move the dot and you move the range.
- \item[top pad slider] operates the edge slopes (selection attack/decay) and the value will be displayed in the
- rightmost textbox. Sharp edges are represented by 0; 100 represents smooth edges.
- \item[top arrow] affects the distribution skew.
+ \item[top pad slider] operates the edge slopes (selection attack/decay) and the value will be displayed in the rightmost textbox. Sharp edges are represented by 0; 100 represents smooth edges. It is only for "Mask Selection" (Pane 1). It applies simultaneously to the left and right edges (symmetric).
+ \item[top arrow] affects the distribution skew. It is the equivalent of Top Pad Slider for Pane 2 ("Color Adjusting").
\end{description}
-\subsubsection*{Operational characteristics for \textbf{Fill}:}
+\textit{Left/Right Arrow} determine the edges of the color range. They are precise edges independent of each other, so we can get asymmetrical ranges with respect to the center of the interval indicated by \textit{middle circle slider below}.
+
+\subsubsection*{Operational characteristics for Fill:}
\label{ssub:operational_characteristic_fill}
\begin{description}
RGBA = red/green/blue color planes, alpha data plane.
YUVA = luma/Cb/Cr color values, alpha data plane.
-The alpha data normally is input to the blending operations in the patchbay overlay mode. The alpha data usually creates the appearance of stacking order, and determines which color planes are visible in the rendered result. When BlueBanana is used, the meaning of the alpha data is changed to the selection. It is useful to think of the alpha data as more solid when it is transparency in blending, and more selected when it is used in BlueBanana. In both cases, the greater the alpha value, the more the effect is expressed.
+The alpha data normally is input to the blending operations in the patchbay overlay mode. The alpha data usually creates the appearance of stacking order, and determines which color planes are visible in the rendered result. When BlueBanana is used, the meaning of the alpha data is changed to the selection. It is useful to think of the alpha data as more solid then it is transparency in blending, and more selected when it is used in BlueBanana. In both cases, the greater the alpha value, the more the effect is expressed.
-Usually, alpha is normalized to a range from $0$ to $1$, zero = no effect, $1$ = total effect, $0.5$ = partial effect. In both cases, alpha is what math people call an auxiliary variable. It is needed, but is not part of the answer. In this case, the answer is the visible rendered result. Alpha is like meta-data.
+Usually, alpha is normalized to a range from $0$ to $1$, zero = no effect, $1$ = total effect, $0.5$ = partial effect. In both cases, alpha is what math people call an auxiliary variable. It is needed, but is not part of the answer. In this case, the answer is the visible rendered result. Alpha is like meta-data. Note that the "alpha" slider works with both "Filter Active" and "Mask Selection" checkboxes
+checked. The "Filter Active" checkbox enables the options: red, green, blue, hue, saturation, value, fade, alpha. If "Mask Selection" is not checked "alpha" will not work.
Let us now examine the instruments in \textbf{pane 1}:
\item[Hue] select a hue domain; click on the Pick button to select or check the box to the left of hue or uncheck to ignore.
\item[Saturation] select a saturation domain; click on the Pick button to select or check the box to the left.
\item[Value] select a value domain; click on the Pick button to select or check the box to the left.
- \item[Fill] will fill more area or less area of your selected region. This describes how it works. Fill control is an automated way of doing grow and shrink on the selected area, to fill in small holes, or get rid of scattered speckles. If none of the Hue, Saturation, or Value sliders are active -- meaning that the whole frame is selected -- the Fill slider will have no effect even when enabled. The word fill will appear ghosted to indicate this.
+ \item[Fill] will fill more area or less area of your selected region. This describes how it works. Fill control is an automated way of doing grow and shrink on the selected area, to fill in small holes in the middle of the selection, or to eliminate spurious pixels that are on the outer or inner edge of the selection. Be careful how much you shrink, because it can lead to edge segmentation with visible and annoying blocks of pixels. This is where Blur plugin can help. Blur should not be overdone so as not to create unsightly halos.
+
+ If none of the Hue, Saturation, or Value sliders are active -- meaning that the whole frame is selected -- the Fill slider will have no effect even when enabled. The word Fill will appear ghosted to indicate this.
The three lower handles in the fill slider correspond to \textit{Shrink} (the left hand slider), \textit{Final} (the middle slider), and \textit{Grow} (the right hand slider). These are used in combination to alter the selection by first growing it by the amount specified by the right hand Grow slider, shrinking it to the amount specified by the left hand Shrink slider, and then growing it again to the final size specified by the middle Final slider. The top slider then feathers the resulting selection.
- Growing the selection and then shrinking it has the effect of filling small holes in the selected area. Similarly, shrinking and then growing tends to remove small flecks of unwanted selection. The Final slider specifies the overall desired shrinkage or growth of the selection when finished. To specify a pure Grow or Shrink operation, set the Final slider and the Grow/Shrink slider to the same value and leave the other slider at zero.
+ Growing the selection it has the effect of filling small holes in the selected area. Similarly, shrinking and then growing tends to remove small flecks of unwanted selection. The Final slider specifies the overall desired shrinkage or growth of the selection when finished. To specify a pure Grow or Shrink operation, set the Final slider and the Grow/Shrink slider to the same value and leave the other slider at zero.
\item[Pre-erode] this control reverses the order of operation to Shrink, then Grow, then Final. The change is subtle on most images, but overall removes more small features because it first removes flecks before filling in holes.
\end{description}
\item[Alpha] controls the output alpha (this is not available when End Mask is set); click the Reset button to revert to default. Result is reflected in the numerical textboxes on the right-hand side.
\end{description}
-Let's see two examples of HowTo:
+\subsubsection*{Tips}
+\begin{enumerate}
+ \item In Pane 1, for mask selection creation, you can also use only one or two (checked or Pick button) of the three qualifiers Hue/Saturation/Value. With Hue alone you get a precise range of hues. With Saturation you select those saturation values for all hues, and with Value you do a "Luma Key," that is, you isolate only certain gray values. It may be useful to start with only one qualifier, and then gradually activate the others; but there are important cases that require all three bars. For example, skin tones, which are always characterized by a mixture of shadows, highlights, and different levels of saturation.
+ \item Hue and Saturation Qualifiers can be inaccurate if the file is highly compressed and with Subsampling type $4:2:0$. There are indeed blocks and macroblocks of pixels, visible especially along the edges, that disturb the creation of the selection mask. Better to use high quality files at least $4:2:2$, better still $4:4:4$. The brightness Y channel, on the other hand, is always at the highest quality (4). The presence of color noise can also be a problem because it creates spurious pixels. A tip may be to work on and enhance the clip before applying Blue Banana.
+ \item If there are unwanted (spurious) selections in the frame that are small and far from the main selection, they can be eliminated or minimized with some Blur. Larger spurious selections can be eliminated by masking them (with the \texttt{Mask selection} option enabled in Blue Banana and with the \texttt{Apply mask before plugins} option in Mask tool). This is an action analogous to \textit{garbage matte} in Chroma Key. If there are many spurious areas, perhaps with complex motions, it is best to mask only the selection we are interested in and then bring the \texttt{Fade} slider to $-100$ to reverse the mask.
+ \item To select multiple colors in the same clip we can use multiple instances of Blue Banana.
+ \item Once a satisfactory selection mask has been created, scroll through the entire clip to see the presence of artifacts, defects, or spurious areas in the other frames.
+ \item It is known that primary Color Correction precedes secondary CC. However, if we use primary CC tools that cause the highlights and deep blacks to clip, for example the histogram, we will get clipped areas that then, in secondary CC, cannot be recovered. We can then first do a secondary CC for the areas near the white point and the black point using Blue Banana which works at 32bit Float. For example, we can turn down the highlights so as to reveal details and the same can be done in the shadows. Once we have worked in these details without causing clipping (that is, reported within the standard range) we can switch to primary CC.
+\end{enumerate}
+
+Let's see two examples of HowTo:
\subsubsection*{BlueBanana Use Case \#1: (Color Transform/Remapping)}
\label{ssub:bb_use_case_1}
\item[Alpha determines radius] use alpha to define the amount of blur to apply. (radius=gray value of alpha)
\item[Blur alpha, red, green, blue] specifies which color channels is to be blurred.
\end{description}
+If you are getting confusing results with old projects it may be a
+result of the discontinued parameter \textit{alpha determines radius}.
+For compatibility reasons and for possible future development it
+has been left in the code but hidden in the plugin's GUI.
+The parameter for \textit{alpha determines radius} is
+\texttt{A\_KEY}, which can be 0 or 1. When you press the
+\texttt{Reset} button in the Blur plugin window \texttt{A\_KEY=0}.
+
+Old projects may have saved that parameter (A\_KEY) to 1 instead
+of 0 and that may present a problem so you should do one of
+the following workarounds to change it to 0. Then be sure to save
+your project with these changes applied.
+\begin{enumerate}
+ \item Click on the \textit{Reset} button in the dialogue/controls popup box and re-enter any of your other parameter desired values.
+ \item OR in the \CGG{} program, open the project. Click on the cog icon
+(\textit{Preset edit}) of the Blur effect bar and the \textit{Keyframe
+parameters} window is open. There, you can see the A\_KEY parameter
+and change it: select the \texttt{A\_KEY} parameter and in the
+\texttt{Edit value} box, change it from 1 to 0, then press the \texttt{OK}
+button.
+\end{enumerate}
\subsection{BoxBlur}%
\label{sub:boxblur}
\label{fig:chroma-key}
\end{figure}
-Chroma key uses either the \textit{lightness} or the \textit{hue} to determine what is erased. Use value singles out only the lightness to determine transparency.
+Chroma key uses either the \textit{lightness} or the \textit{hue} to determine what is erased. Use value singles out only the lightness to determine transparency (Luma Key).
Select a center color to erase using the \textit{Color} button. Alternatively a color can be picked directly from the output frame by first using the \textit{color picker} in the compositor window and then selecting the \textit{Use color picker} button. This sets the chroma key color to the current color picker color.
Be aware that the output of the chroma key is fed back to the compositor, so selecting a color again from the compositor will use the output of the chroma key effect. The chroma key should be disabled when selecting colors with the color picker.
\subsubsection*{Requirements}
\label{ssub:requirements}
-The subject in the movie should have a good background. The lighting is crucial and good lighting during production will save you time with much less effort than in post-production.
+The subject in the movie should have a good background. The lighting is crucial and good lighting during production will save you time with much less effort than in post-production. Another tip is to use a low-compressed, intraframe codec with as high a color depth as possible. In case of YUV-type source signal, it is better to have subsampling $4:4.4$ or $4:2:2$.
Here we assume that we have a good video, filmed on green (or blue) screen that we want to use. Important: Make sure you are using a color model that has an alpha channel, such as \textit{RGBA8}, \textit{RGBAFloat}, \textit{YUVA8}. To change color model, go to \texttt{Settings $\rightarrow$ Format $\rightarrow$ Color Model}.
\subsubsection*{Usage}
\item Allows you to automate the \textit{white balance} by simply choosing a neutral color in the output of the Compositing window using the Color Picker and pressing the corresponding button in the plugin.
\item Allows you to vary the \textit{Saturation} with sliders in the same manner as contrast was varied by the Value slider. For istance, to decrease the incidence of color dominants present in the shadows or in the highlights, vary the Saturation.
\item With the \textit{color wheels} you can make very sophisticated adjustments to the shades of the images, in each of the three main areas of shadows, midtones and highlights.
- \item Allows you to copy exactly the setting of one zone to the other two zones using \textit{Copy to all} button.
+ \item Allows you to copy exactly the setting of one zone to the other two zones using \textit{Copy to all} button. With this option, it is like using a fourth wheel called \textit{OffSet} in other programs.
\item In addition to the three reset buttons, each slider and each wheel has its own Clear button, to return it to the default value without affecting the others.
\end{itemize}
\item Create a Stylized look.
\end{itemize}
+When using the X11 graphics driver and RGBA-FLOAT color model, this plugin allows for greater than (0 - 1.0f) values (HDR). This does not work when using X11-OpenGL because it is an 8-bit limited driver. HDR values will only work for the color wheel, while the Value and Saturation sliders are always clipped to 1.0.
+
\subsection{Color Balance}%
\label{sub:color_balance}
\index{color balance}
Mathematically, the gamma function is exponential
($output = input^{\gamma}$) and therefore the inverse of the
-logarithmic function [$output = \log(input)$]. Actually the formula
+logarithmic function [$\gamma = \log_{input}{(output)}$]. Actually the formula
used by the \CGG{} plugin is: $output = input^{\frac{1}{\gamma}}$
which allows for a range of values $0 \div 1.0$. The gamma effect
converts the logarithmic colors to linear colors through a
determines how steep the output curve is (i.e.\ the value of the
gamma parameter; for color space Rec709 is $2.4$
($\frac{1}{\gamma} =0.41\dots$), for sRGB is $2.2$
-($\frac{1}{\gamma} =0.45\dots$), etc.). The maximum value is where
+($\frac{1}{\gamma} =0.45\dots$), etc.). We use $ \dfrac{1}{\gamma}$ because with $\gamma < 1$ there is gamma compression of the curve, increasing the output values relative to the linear (see figure~\ref{fig:gamma02}.). With $\gamma > 1$ we have gamma expansion, typically used to linearize a compressed gamma curve (\textit{Log}). The maximum value is where
$1.0$ in the output corresponds to maximum brightness in the
input. It serves to avoid clipped values because it allows you to
set the maximum value of the output, $1.0$, whenever range
\begin{figure}[htpb]
\centering
- \includegraphics[width=1.0\linewidth]{gamma01.png}
+ \includegraphics[width=0.8\linewidth]{gamma01.png}
\caption{settting \textit{Maximun} to $0.6900$}
\label{fig:gamma01}
\end{figure}
\begin{itemize}
\item Look at the highest peak on the \textit{waveform} and measure it with the crosshair observing the numerical value at the top left.
- \item Set this value with the \textit{maximum} slider.
+ \item Set this value with the \textit{maximum} slider or \textit{textbox}.
\item Then adjust the slider of the \textit{gamma} to our liking, always checking the result on the waveform so to be sure never to exceed the values of clipping, $0 \div 1.0$.
\end{itemize}
\begin{figure}[htpb]
\centering
- \includegraphics[width=1.0\linewidth]{gamma02.png}
+ \includegraphics[width=0.8\linewidth]{gamma02.png}
\caption{Setting \textit{Maximun} to $0.6100$ and \textit{Gamma} to $0.3300$}
\label{fig:gamma02}
\end{figure}
\label{fig:histeq}
\end{figure}
-Histeq equalizes the colorspace through use of a \textit{histogram equalization algorithm} -- a technique for adjusting image intensities to enhance contrast. Parameters are:
+If the histogram is as wide as the entire range ($0 - 1.0$), the image is high contrast. If the range is small (i.e., the values are close together) the contrast is small. In this case HistEQ is used to distribute the few clustered values across the entire range ($0 - 1.0$), increasing the contrast of the frame.
+In order to do this HistEQ equalizes the colorspace through use of a \textit{histogram equalization algorithm}. Parameters are:
\begin{description}
\item[Gain:] when set to $1$, the colorspace is best effort. If the gain is set to $0$, the result is the entire regression line of the color map.
\label{sub:histogram}
\index{histogram}
-The histogram allows an immediate view of the contrast amplitude of an image with its distribution of \textit{luma} and \textit{colors} values. If the columns of values occupy the whole range $0-100\%$ then we have maximum contrast; if the range is smaller the contrast is smaller. If most of the values are on the right of the histogram you have an image with highlights at the limit with values clamped to $1.0$. This is called \textit{overexposure}. However, if most of the values are moved to the left, with the limit of the values clamped to $0$, we have a lowlight image and we talk about \textit{underexposure}. Histogram is keyframble (figure~\ref{fig:histogram}).
+The histogram allows an immediate view of the contrast amplitude of an image with its distribution of \textit{luma} and \textit{colors} values. If the columns of values occupy the whole range $0-1.0$ (also expressed as a percentage above the graph) then we have maximum contrast; if the range is smaller the contrast is smaller. In fact, contrast is mathematically given by the highest value of the abscissa minus the lowest value. If the values are similar and close together, the difference is smaller and the lower the contrast. If most of the values are on the right of the histogram you have an image with highlights at the limit with values clamped to $1.0$. This is called \textit{overexposure}. However, if most of the values are moved to the left, with the limit of the values clamped to $0$, we have a lowlight image and we talk about \textit{underexposure}. This plugin is a tool for Primary Color Correction, that is, affecting the entire frame. Histogram is keyframable (figure~\ref{fig:histogram}).
\begin{figure}[htpb]
\centering
\label{fig:histogram}
\end{figure}
-The Histogram is always performed in floating point RGB regardless of the project color space. The histogram has two sets of transfer parameters: the \textit{input transfer} and the \textit{output transfer}. The input transfer has value on the horizontal axis of $x$; it is a scale of values ranging from 0 to 255 in the case of an $8\,bit$ image, or it can have normalized values in the range ($0-1.0$) or even be a scale in percentage ($0-100\%$). In the output transfer (the $y\,axis$) is represented the number of times (that is, $y$) a given value $x$ appears. A higher column ($y$ greater) indicates that many pixels have the corresponding value $x$; a lower column indicates that fewer pixels have that value. On the left we have the minimum value $0$, which is the black point. On the right we have the maximum value $1.0$ which is the white point. The intermediate values pass smoothly from one extreme to the other. The three important points (including the midtones, i.e.\ the Master Offset) are indicated by cursors (small triangles) at the base of the histogram. You can adjust them to change the values of the three points if you want.
+The Histogram is always performed in floating point RGB regardless of
+the project color space, but with clipping at 1.0. When using the X11
+graphics driver and RGBA-FLOAT color model, Histogram allows you to
+display greater than (0 - 1.0f) values to accomodate HDR. This does
+not work when using X11-OpenGL because it is an 8-bit limited driver.
+The display will stop at +110\%, but there is no clipping. By lowering
+the brightness all out-of-range values become visible, even those
+initially above 110\%.
+
+The histogram has two sets of transfer parameters: the \textit{input transfer} and the \textit{output transfer}. The input transfer has value on the horizontal axis of $x$; it is a normalized scale of values ranging from 0 - 1.0 (which for a depth color of 8 bits corresponds to the range 0 - 255, for 10 bits corresponds to 0 - 65536, etc). The output transfer (the $y axis$) represents the height of the column where a given value $x$ appears. A higher column ($y$ greater) indicates that many pixels have the corresponding value $x$; a lower column indicates that fewer pixels have that value. On the left we have the minimum value $0$, which is the black point. On the right we have the maximum value $1.0$ which is the white point. The intermediate values pass smoothly from one extreme to the other. The three important points (including the midtones) are indicated by cursors (small triangles) at the base of the histogram. You can adjust them to change the values of the three points if you want. Acting on the white or black point involves horizontal shifts only; acting on the midtones triangle also involves vertical movements leading to a "gamma" correction of the curve (Linear to Log or Reverse Log or vice versa). Further down is an additional bar with related cursors and textboxes. It is used to adjust input and output values (on the vertical).
-There are 4 possible histograms in the histogram viewer. The red, green, blue histograms show the input histograms for red, green, blue and multiply them by an input transfer to get the output red, green, blue. Then the output red, green, blue is scaled by an output transfer. The scaled red, green, blue is converted into a value and plotted on the value histogram. The value histogram thus changes depending on the settings for red, green, blue. The value transfers are applied uniformly to R, G, B after their color transfers are applied. Mathematically, it is said that the values of $x$ are linked to the values of $y$ by a transfer function. This function is represented by a line that leaves the values of $x$ and $y$ unchanged, but we can intervene by modifying this line with the cursors.
+There are 4 possible histograms in the histogram viewer. The red, green, blue histograms show the input histograms for red, green, blue and multiply them by an input transfer to get the output red, green, blue. Then the output red, green, blue is scaled by an output transfer. The scaled red, green, blue is converted into a value and plotted on the value histogram. The value histogram thus changes depending on the settings for red, green, blue. The value transfers are applied uniformly to R, G, B after their color transfers are applied. Mathematically, it is said that the values of $x$ are linked to the values of $y$ by a transfer function. This function, by default, is represented by a line that leaves the values of $x$ and $y$ unchanged, but we can intervene by modifying this line with the cursors or the textboxes.
You need to select which transfer to view by selecting one of the channels on the top of the histogram. You can also choose whether to display the master, i.e.\ only the values of the \textit{luma}, or show the \textit{Parade}, i.e.\ the three RGB channels. You can switch from one to the other with the two buttons in the upper right corner. The input transfer is defined by a graph overlaid on the histogram; this is a straight line. Video entering the histogram is first plotted on the histogram plot, then it is translated so output values now equal the output values for each input value on the input graph.
-After the input transfer, the image is processed by the output transfer. The output transfer is simply a minimum and maximum to scale the input colors to. Input values of $100\%$ are scaled down to the output's maximum. Input values of $0\%$ are scaled up to the output minimum. Input values below $0$ are always clamped to $0$ and input values above $100\%$ are always clamped to $100\%$. Click and drag on the output gradient's triangles to change it. It also has textboxes to enter values into.
+After the input transfer, the image is processed by the output transfer. The output transfer is simply a minimum and maximum to scale the input colors to. Input values of $1.0$ are scaled down to the output's maximum. Input values of $0$ are scaled up to the output minimum. Input values below $0$ are always clamped to $0$ and input values above $1.0$ are always clamped to $1.0$. Click and drag on the output gradient's triangles to change it. It also has textboxes to enter values into.
-Enable the \textit{Automatic} toggle to have the histogram calculate an automatic input transfer for the red, green, and blue but not the value. It does this by scaling the middle $99\%$ of the pixels to take $100\%$ of the histogram width. The number of pixels permitted to pass through is set by the \textit{Threshold} textbox. A threshold of $0.99$ scales the input so $99\%$ of the pixels pass through. Smaller thresholds permit fewer pixels to pass through and make the output look more contrasty.
-\textit{Plot histogram} is a checkbox that enables plotting the histogram.
-\textit{Split output} is a checkbox that enables a diagonal split showing in the compositor.
+Enable the \textbf{Automatic} toggle to have the histogram calculate an automatic input transfer for the red, green, and blue but not the value. It does this by scaling the middle $99\%$ of the pixels to take $100\%$ of the histogram width. The number of pixels permitted to pass through is set by the Threshold \textbf{textbox}. A threshold of $0.99$ scales the input so $99\%$ of the pixels pass through. Smaller thresholds permit fewer pixels to pass through and make the output look more contrasty.
+\textit{Plot histogram} is a checkbox that enables plotting the histogram. It can be useful because having a histogram that changes in real-time can use a lot of system resources for computation. In this case it is enabled only at times when it is needed.
+\textit{Split output} is a checkbox that enables a diagonal split showing in the compositor, so we can see the effects of the changes from the original frame.
\textit{Reset} returns the four curves to their initial state (neutral) as well as the Value/RGB histogram buttons.
+\textbf{Linear to Log} slider: frequency in Linear range to Log range; default is 50\%, but if you want it to be the same as the Videoscope or Histogram Bezier, which are of type Log, set the slider all the way to Log. The variation is by 10\% steps. Linear generally represents what the eye sees in the real world. Log is an exponential look where the small numbers are represented more - that is, the leading digit.
+
The histogram plugin ordinarily applies a value for a single frame. A
new feature modifies histogram to show values for a selection of frames.
You use several frames in a video that you want to use the \textit{average}
there is a large light or color variation within a range of a few frames,
you spend a lot of time correcting each frame when it would be better to
just get an average value to use. If you want, then you can make a LUT for
-that set of frames instead of each frame.
-
+that set of frames instead of each frame.\\
It works by selecting the area on the timeline for
which you would like to see the Histogram averaged and then click on the
-\textit{Frames} button in the Histogram plugin.
-The parameters are:
-\textit{Linear to Log} slider: frequency in Linear range to Log range; default is 50\%, but if you want it to be the same as the Videoscope or Histogram Bezier, set the slider all the way to Log. The variation is by 10\% steps. Linear generally represents what the eye sees in the real world. Log is an exponential look where the small numbers are represented more - that is, the leading digit.
-\textit{Frames} button: if a Selection is set on the timeline, the number of frames
-will be calculated and shown in the box next to it.
-\textit{Frame Count box}: type in the number of frames you want to be looked at
-starting at the insert marker or use the up/down counter.
-\textit{Clear Frames} icon: reset the frame count to the default value of 0.
+\textbf{sum frames} button in the Histogram plugin. If a Selection is set on the timeline, the number of frames will be calculated and equalized to the mean value.
A side note: by using a number of frames, you can get a \textit{dissolve-like
transition effect}.
\paragraph{Theory:}
-A histogram is a bunch of \textit{bins} (accumulators) that count the number of times a particular pixel channel intensity occurs in an image. Dim are on the left, bright on the right.
+For more on the mathematical aspect see here:
+
+{\small \url{https://thirdspacelearning.com/gcse-maths/statistics/histogram/}}
+
+For our discussion, it is enough to understand a few concepts. Each vertical line we see in the histogram is not a simple line, but a rectangle having a certain base. This base is given by the values of $x_i$ present at the edges of the rectangle \textit{i} (pixel range, $x_{max_i} - x_{min_i}$). Rectangles are called \textit{Bins} or Accumulators. The bin's number is of fixed and known size because it depends on the color depth. The bin height is our output $y$ and the bin area ($A_i = f(x_i)$) is known because it represents the \textit{number of occurrences} that are read in bin, also called \textit{frequency ($f_x$)}. The plugin scans the entire range of $x_i$, from 0 to 1.0, and records all the occurrences within each bin. The value of $f_x$ for each bin is the \textit{max} value. At this point knowing base and area, we can obtain the value of $y$ axis that is reported in the histogram.
+
+$width = b_i = x_{max_i} - x_{min_i}$
+
+Having established the depth color, the bin width is always the same (b) for every $bin_i$:
+
+$b_i = b = \dfrac{range(1.0-0)}{\# bins}$
+
+$A_i = f(x_i) = max_i = Base \times High = b \times y_i$
+
+Hence:
-The number of bins used depends on the color model bit depth:
+$y_i = \dfrac{f(x_i)}{b}$
+
+Dim bins are on the left, bright bins on the right.
+You can have discordance of results, looking in the scopes, either by switching from Histogram to Histogram Bezier or after a conversion between color spaces (with associated change in depth color). The number of bins used depends on the color model bit depth:
\begin{description}
- \item[Histogram:] 256 for rgb8 and 65536 for all others.
- \item[Bezier:] 256 for rgb8/yuv8 and 65536 for all others.
+ \item[Histogram:] 256 for rgb8 and 65536 for all others
+ \item[Bezier:] 256 for rgb8/yuv8 and 65536 for all others
\item[Scopes:] always uses 65536
\end{description}
-All of the bins are scanned when the graph is plotted. What is shown
-depends on which plugin is used:
+All of the bins are scanned when the graph is plotted. What is shown on the graph, in the Compositor window, and finally on the scopes, depends on which plugin is used:
\begin{description}
- \item[Histogram:] was max of the bins in the pixel range, now is the sum
+ \item[Histogram:] was max of the bins in the pixel range, now is the sum (to make it congruent with Bezier and the Scopes)
\item[Bezier:] is the max of the bins in the pixel range
\item[Scopes:] is the max of the bins in the pixel range
\end{description}
-When the color space and the bin size are the same, all of the values
-increment the indexed bins. When the color is the result of yuv $\rightarrow$ rgb conversion, the results \textit{spread} if there are more bins than colors. This is the same effect you see when you turn on \textit{smoothing} in the vectorscope histogram.
+Another difference in behavior is regarding the type of curve, whether Linear or Log:
+
+\begin{description}
+ \item[Histogram:] the curve is Linear, but it is editable with the Linear/Log slider
+ \item[Bezier:] the curve is Log
+ \item[Scopes:] the curve is Log
+\end{description}
-The \textit{total} pixels for each value is approximately the same, but the \textit{max} value depends on the color quantization. More colors increment more bins. Fewer colors increment fewer bins. In both cases, the image size has the same
-number of pixels. The fewer color case increments the used bins, and skips the
-unused bins. This sums all of the pixels into fewer bins, and the bins have
-higher values. That is the \textit{rgb} vs \textit{yuv} case, fewer vs more bins are used.
+This diversity also leads to different visual results from Histogram Bezier or Videoscope.
-To report something more consistent, has been changed the reported value to
-the \textit{sum} of the accumulated counts for the bins reporting a pixel bar on the
-graph. The effect of this is to do this:
+When the color space and the bin size are the same, all of the values increment the indexed bins. But if we start from YUV type edits, the plugin will automatically do the conversion to RGB. When the color is the result of yuv $\rightarrow$ rgb float conversion, we go from 256 bins of YUV to 65536 bins of RGB Float and the results \textit{spread} if there are more bins than colors. This is the same effect you see when you turn on \textit{smoothing} in the vectorscope histogram.
+
+The \textit{total} pixels for each value is approximately the same, but the \textit{max} value depends on the color quantization. More colors increment more bins. Fewer colors increment fewer bins. In both cases, the image size has the same number of pixels. So the pixels will distribute into more bins if you go to a higher depth color; those bins will have a lower count. The fewer color case increments the used bins, and skips the unused bins. This sums all of the pixels into fewer bins, and the bins have higher values. That is the \textit{rgb} vs \textit{yuv} case, fewer vs more bins are used. To get more consistent visual feedback (and on scopes), the concept of \textit{sum} was used instead of the maximum number of occurrences (max).
+
+To report something more consistent, the reported value has been changed from the original code to be the \textit{sum} of the accumulated counts for the bins reporting a pixel bar on the
\begin{center}
- \begin{tabular}{ l l c r r }
+ \begin{tabular}{clccr}
\hline
1 & & & & \\
1 & & & 1 & \\
- 000100 & 3 pixels & vs & 001000& 3 pixels \\
+ 000100 & 3 pixels & vs & 0011000& 3 pixels \\
\hline
\end{tabular}
\end{center}
-On the left, the course color model piles all 3 pixels into one bin. max
-value 3
-
-On the right, the fine color model puts the counts into 2 bins, max 2, sum 3
-
-So, by reporting the sum the shape of the results are more similar.
+On the left, the course color model piles all 3 pixels into one bin, max
+value 3.
+On the right, the fine color model puts the counts into 2 bins, max 2, sum 3.
+So, by reporting the sum the shape of the results are more similar to Bezier.
\subsection{Histogram Bezier / Curves}%
\label{sub:histogram_bezier_curves}
\index{histogram Bezier}
-Histogram Bézier allows an immediate view of the contrast amplitude of an image with its distribution of luma and colors values using a piecewise linear method. In addition it uses a Bézier curve (parametric) on the histogram plot. When mapping color spaces, it has a variety of presentations to get smoother transitions and more pleasing output. It uses more general remapping, not just straight lines but more contour lines. Curves are perhaps the most powerful and sophisticated tool for color correction. For some repetitive details, see the previous description of the Histogram plugin. Histogram Bézier is keyframable.
+Histogram Bézier allows an immediate view of the contrast amplitude of an image with its distribution of luma and colors values using a piecewise linear method (bins). In addition it uses a Bézier curve (parametric) on the histogram plot. When mapping color spaces, it has a variety of presentations to get smoother transitions and more pleasing output. It uses more general remapping, not just straight lines but more contour lines. Curves are perhaps the most powerful and sophisticated tool for color correction. For some repetitive details, see the previous description of the Histogram plugin. Histogram Bézier is keyframable. The scale is given in percent ($0 - 100\% \pm 10\%$). The default curve is Log type and can use either RGB or YUV sources without implementing conversions.
+
+NOTE: Histogram Bezier may give results that are not congruent with Histogram plugin. To understand the difference in behavior see the Theory section in Histogram plugin.
The input graph is edited by adding and removing any number of points. Click and drag anywhere in the input graph to create a point and move it. Click on an existing point to make it active and move it. The active point is always indicated by being filled in. The active point's input X and output Y values are given in textboxes on top of the window. The input and output color of the point can be changed through these textboxes. Points can be deleted by first selecting a point and then dragging it to the other side of an adjacent point. They can also be deleted by selecting them and hitting delete (figure~\ref{fig:bezier}).
\label{sub:holographictv}
\index{holographicTV}
-Incoming objects are projected like holovision seen in the movie Stars Wars as in R2-D2's video message projector of the Princess Leia. You need a movie or background image and above it a track containing the figure on which to apply the effect. This must have a transparent background. There are no configuration parameters; it only has to be applied to the upper track (figure~\ref{fig:holographictv}).
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.55\linewidth]{holographictv.png}
+ \caption{Holographic messages in CinGG!}
+ \label{fig:holographictv}
+\end{figure}
+
+Incoming objects are projected like holovision seen in the movie Stars Wars as in R2-D2's video message projector of the Princess Leia (figure~\ref{fig:holographictv}). You need a movie or background image and above it a track containing the figure on which to apply the effect. This must have a transparent background. There are no configuration parameters; it only has to be applied to the upper track.
This effect originated from {\small \url{https://effectv.com}}.
-\begin{figure}[htpb]
- \centering
- \includegraphics[width=0.8\linewidth]{holographictv.png}
- \caption{Holographic messages in CinGG!}
- \label{fig:holographictv}
-\end{figure}
\subsection{Hue saturation}%
\label{sub:hue_saturation}
Every time a keyframe is set in a loop effect, the keyframe becomes the beginning of the region to loop. Setting several keyframes in succession causes several regions to loop. Setting a single keyframe causes the region after the keyframe to be looped throughout the effect, no matter where the keyframe is. The end of an effect can be looped from the beginning by setting the keyframe near the end.
+\subsection{Mirror}%
+\label{sub:mirror}
+\index{Mirror}
+
+The Mirror plugin splits the image along a line, an axis, and reflects one side onto the other.
+When the \texttt{Enable Reflection Center} option is checked you can move the position of this axis, using $X\%$ and/or $Y\%$ slider and/or textbox: $X\%$ for the horizontal position and $Y\%$ for the vertical position. Mainly in the Mirror effect there are 2 cases: with or without the \textit{Enable Reflection Center} checked.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.7\linewidth]{mirror.png}
+ \caption{Possible combinations with both Horizontal and Vertical checked}
+ \label{fig:mirror}
+\end{figure}
+
+When the \textit{Enable Reflection Center} option is UNCHECKED, the used reflection is on the center of the image (i.e. $X=50\%$, $Y=50\%$) and the options about \textit{Reflection Center}, $X\%$ and $Y\%$, are disabled (grayed).
+The Horizontal option reflects the left side of the image on the right. If the \texttt{Swap LEFT-RIGHT side} option is checked then the right side to the left will be reflected.
+The Vertical option reflects the top on the bottom. If the \texttt{Swap TOP-BOTTOM side} option is checked then the bottom to the top will be reflected.
+There are special combinations when both Horizontal and Vertical checkboxes are enabled (and\textit{ Enable Reflection Center} is always UNchecked, of course). You can see those combinations in the figure~\ref{fig:mirror}.
+
+When the \textit{Enable Reflection Center} option is CHECKED the options about \textit{Reflection Center}, i.e. $X\%$ and $Y\%$, are enabled, and the two "Swap ... side" options are disabled and hidden. These two "Swap ... side" are disabled because the $X\%$ and $Y\%$ allow the swap side feature automatically. The $X\%$ and $Y\%$ positions move the center of the reflection to fit to the user's need.
+
\subsection{Motion51}%
\label{sub:motion51}
\index{Motion51}
+Note: Motion and Motion51 plugins are complex and slow to use for video stabilization. If you are stabilizing an entire video, you may want to preprocess by using ffmpeg's \textit{vidstabdetect} and \textit{vidstabtransform} plugins before importing the video into \CGG{}.
+
This plugin compensates for unwanted motion and stabilizes the picture. The \textit{Motion51} Plugin simplifies motion stabilization so that without a lot of tweaking you can easily achieve reasonable results, either by using the defaults or varying a single parameter. Since the motion in every clip is specific, there are some additional parameters useful to adjust the settings accordingly.
The Motion51 plugin uses different methods for tracking than the other motion plugins. Motion Stabilization is very useful if you have jittery video, for example when taken from a car window, or while walking.
\label{sub:motion}
\index{Motion}
+Note: Motion and Motion51 plugins are complex and slow to use for video stabilization. If you are stabilizing an entire video, you may want to preprocess by using ffmpeg's \textit{vidstabdetect} and \textit{vidstabtransform} plugins before importing the video into \CGG{}.
+
The \textit{motion tracker} is almost a complete application in itself. The motion tracker tracks two types of motion: \textit{translation} and \textit{rotation}. It can track both simultaneously or one only. It can do $\frac{1}{4}$ pixel tracking or single pixel tracking. It can stabilize motion or cause one track to follow the motion of another track. Although the motion tracker is applied as a realtime effect, it usually must be rendered to see useful results. The effect takes a long time to precisely detect motion so it is very slow.
Motion tracker works by using one region of the frame as the region to track (Match Box). It compares this region between $2$ frames to calculate the motion. This region can be defined anywhere on the screen. Once the motion between $2$ frames has been calculated, a number of things can be done with that \textit{motion vector}. It can be scaled by a user value and clamped to a maximum range. It can be thrown away or accumulated with all the motion vectors leading up to the current position.
\begin{figure}[ht]
\centering
- \includegraphics[width=0.9\linewidth]{motion.png}
+ \includegraphics[width=0.99\linewidth]{motion.png}
\caption{Motion plugin GUI}
\label{fig:motion}
\end{figure}
\label{ssub:tips}
\begin{enumerate}
+ \item Motion plugin\protect\footnote{Thanks to Georgy} algorithm in \CGG{} is rather difficult to understand (the most efficient way to understand it is to look inside its C++ code:). Moreover, it has some tricks that, although can be derived knowing the details of the algorithm, are absolutely non-intuitive by themselves. Moreover, it is rather slow, and the results cannot be visible immediately while altering the settings.
+ \item The Motion plugin \textit{cache} (or\textit{ motion vector} or \textit{tracking file}) sometimes allows to play with very sophisticated techniques. For example, by editing the cache, perhaps with some custom script, you can induce some kind of motion which would be difficult to make in other way. But in the same time the existence of the cache file can trigger user's mistakes. So you must always pay attention, which cache file may be used in the moment. //
+ Motion's cache data are absolute-frame-number based. If you insert some small piece of video before that where the plugin was attached, the frame numbers get displaced relative to the cached numbers, and the result may become incorrectly stabilized.
\item The motion vector is a text file located in \texttt{/tmp}. We can open it with a plain editor and modify the wrong $X\,Y$ coordinates, i.e.\ those that deviate from the linearity, to correct the errors that always happen when we perform a motion tracking (jumps). It can be a long and tedious job, but it leads to good results.
+ \item It is not possible to switch Motion cache off. While working, \textit{Motion} always looks in its cache. If it contains some data assigned to the current frame numbers, that cached data will be used unconditionally. If not, that data will be calculated, stored in the cache, and later reused, also unconditionally.
+ \item In the Motion plugin dialog there is a button \texttt{Clear tracking file contents}. When in doubt, you can press this button, the cached data will be erased and fresh recalculated on the next pass.
+ \item It is quite usual to wish independent caches for different parts of video. It is possible to set such distinct cache file names (either manually, or let software generate them with \texttt{Generate tracking file name}). When you generate new names, the plugin automatically switches Calculation off, just for security. You switch it on again when needed.
+ \item If \texttt{play track} is switched off for the track where the Motion plugin was attached, the plugin will calculate nothing. Also, if \texttt{Play every frame} was not active in \texttt{Preferences}, some video frames can get skipped from processing.
\item You can try tracking using reverse playback of the track. Sometimes it may lead to a better calculation.
\end{enumerate}
\label{sub:overlay}
\index{overlay video}
-This effect can combine several tracks by using the so called Overlayer. This is a basic internal device normally used by \CGGI{} to create the dissolve transitions and for compositing the final output of every track onto the output bitmap. The Overlayer has the ability to combine one or several image layers on top of a bottom layer. It can do this combining of images in several different (and switchable) output modes such as \textit{Normal}, \textit{Additive}, \textit{Subtractive}, \textit{Multiply} (Filter), \textit{Divide}, \textit{Max} and \textit{Replace}. For a detailed list refer to the on \hyperref[cha:overlays]{Overlays} chapter -- PorterDuff.
+This effect can combine several tracks by using the Overlayer. This is a basic internal device normally used by \CGGI{} to create the dissolve transitions and for compositing the final output of every track onto the output bitmap. The Overlayer has the ability to combine one or several image layers on top of a "bottom layer". It can do this combining of images in several different (and switchable) output modes such as \textit{Normal}, \textit{Addition}, \textit{Subtract}, \textit{Multiply} (Filter), \textit{Divide}, \textit{Max} and \textit{Replace}. For a detailed list and some differences in output expectations, refer to the \hyperref[cha:overlays]{Overlays} chapter -- PorterDuff.
+
The \textit{overlay} plugin enables the use of this Overlayer device in the middle of any plugin stack, opening endless filtering and processing possibilities. It is only useful as a \textit{shared plugin} (i.e.\ a multitrack plugin). To use the overlay plugin:
\item Manipulate the plugin parameters in Track A.
\end{enumerate}
+In the Overlay plugin's parameter window you can choose the overlay "Layer order"
+to select which track plays the role of the "bottom layer" and which plays the
+role of the "top layer". For some overlay modes this can make quite a
+difference, for example the bottom layer is subtracted from the top layer for
+"Subtract" mode. Also in the parameter window, you can choose on which of the tracks
+to overlay the combined output by changing the "Output layer" and it too can make
+quite a difference.
+(Hint: in most cases, you will want to mute the other track so you only see the
+combined output).
+
\subsection{Perspective}%
\label{sub:perspective}
\index{perspective}
Key Presses for using the Perspective plugin:
-\begin{tabular}{l l}
- \toprule
+\begin{tabular}{ll}
+ \hline
Left mouse button & drags the corner that is closest to current location \\
Alt key + left mouse & translates the perspective; drags the whole image \\
Shift key + left mouse & zooms the perspective \\
Alt+Shift + left mouse & translates view but does not change output \\
- \bottomrule
+ \hline
\end{tabular}
Note that the red color lines in the box show the composer boundary.
There is no \textit{undo} recorded between gui updates. It is recommended that you use the option "b" to save a backup if you get to a place where you want to make sure you do not lose your sketch.
-\begin{center}
- \small
\begin{longtable}{{m{12em}m{13em}m{12em}}}
\caption{Sketcher controls}
\label{tabular:sketcher_controls} \\ % note that double backslash is mandatory here
Del button in Curve section \\
\bottomrule
\end{longtable}
-\end{center}
\subsubsection*{Other Button and Label Descriptions}%
\label{ssub:other_button_label_description}
To include graphical elements like \textit{logos}, you may want to import your title as a PNG image (alpha channel transparency is possible), move it with camera and projector or add effects.
-\subsubsection*{Adding fonts to the titler}%
-\label{ssub:adding_fonts_to_titler}
-
-The X Window system originally did not have a suitable font renderer for video. It also is restricted to the current bit depth. It does not have a convenient way to know which fonts work with the suitable font renderer in the desired bit depth. The easiest way we have found to support fonts in the titler is to have a directory for them at \texttt{/usr/lib/cinelerra/fonts}.
-
-The titler supports mainly \textit{TTF}, true type fonts. It supports others but TTF are the most reliable. AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
-
- To add true type fonts, copy the \texttt{.TTF} files to the fonts directory. In that directory run
-\vspace{1ex}
-\begin{lstlisting}[style=sh]
- # /usr/lib/cinelerra/fonts
- ttmkfdir && mv fonts.scale fonts.dir
-\end{lstlisting}
-and restart \CGG{}. The new fonts should appear. The usage of ttmkfdir changes frequently so this technique might not work. It is
-important to note that because there are checkboxes for both Bold and Italic, the pulldown will not include these specific fonts
-as an addition to a Regular font. They will be used via the checkboxes but not viewed in the pulldown.
-
-If the video is displayed on a consumer TV, the outer border is going to be cropped by $5\%$ on each side. To avoid text which is too close to the edge looking bad, you may want to enable the \textit{title-safe} tool in the compositor window. The text should not cross the inner rectangle.
-
\subsubsection*{Some recently added options}%
\label{ssub:some_recently_added_options}
\item[Attributes] in the Text box where you type your Title information, you can now change several attributes to give you plenty of flexibility (figure~\ref{fig:title02}). Each of these special attributes begin with an open angle bracket < and ends with a closing angle bracket >. Until the closing angle bracket is keyed in, the actual characters you type, will be seen in the compositor window. In addition, if you do not use the exact syntax or you keyin a filename that is not available, all of the characters will continue to show up. This helps to see what needs to be fixed or is missing. The attributes usage is described in the table below.
\end{description}
-\begin{center}
- \small
\begin{longtable}{{m{6em}m{14em}m{14em}}}
\caption{Titler attributes}
\label{tabular:titler_attributes} \\ % note that double backslash is mandatory here
color name such as RED from \textit{<cin\_path>/guicast/colors.h} &
Or use the hex value like \textit{\#a000a0}; color-hex.com shows examples \\\midrule
font &
- exact name from \textit{Font} pulldow &
+ exact name from \textit{Font} pulldown &
When you set font, bold/size and italic will be as currently set up \\\midrule
alpha &
floating-point number between 0 and 1&
Turn off smooth for chroma key
\\\bottomrule
\end{longtable}
-\end{center}
These attributes stay in effect until you change them or reset them. Additional cpu time is needed for the \textit{blink} attribute because it requires redrawing every frame and for the background option described below. Note that some Title window controls can not be set, such as Justify and Outline color. The lines below are examples for testing purposes. The accompanying screenshot displays the corresponding \CGG{} output.
\begin{description}
\item[Background] in this box you can keyin the name of a file of the type that \CGG{} accepts and use that file as a background for your Title characters (media video or image). This will be seen in the compositor window on top of the video that is loaded in the main track canvas. Besides typing in the filename, you must also check the checkbox. This makes it easy to turn it \textit{On} and \textit{Off} to see what it looks like. Next to the background box is a \textit{Loop} checkbox. If the background file takes less time than the main track canvas video to run, you can turn on the loop checkbox so that it runs over and over again to match the time size of your video. By default the background image will occupy the whole frame, but if we activate \textit{drag} mode and create a box of the desired size, the image will occupy only the box leaving the rest of the frame visible.
\item[Stroker] to add \textit{pen strokes} to the text letters, adjust the stroke width numerically. This looks particularly nice on certain fonts and with a negative adjustment of the \textit{Drop shadow}.
+ \item[Text: chars:] to output and update the number of characters already used. The only limit to the number of characters based on a count of single $8\, bit$ characters is the available resources on the user computer available for \CGG{} use. Keep in mind that unicode or other special characters may consist of $2$ to $4$ $8\,bit$ bytes. Also, newlines are a character and any of the attributes you use count in the total. There is now a horizontal scroll bar as well as the vertical one in the textbox and they only appear when there are more lines or characters than can fit in the original sized textbox.
\item[Unicode Insertion] if you want to enter a special character like the mathematical \textit{summation} symbol, you can use the unicode equivalent to do so. Press Ctrl-Shift-U followed by $2022$ and a carriage return is an example of the bullet. Refer to section \hyperref[sec:textbox_non_std_character_unicode]{17.5} for details.
\item[Popup Helper] put your cursor where you want to add an attribute, then right mouse will bring up a list of the available attributes for you to choose, along with a submenu to choose from. The program will insert that attribute for you and all you have to add is a value when required! (see figure~\ref{fig:title02}).
\end{description}
\subsubsection*{Font Choice}%
\label{ssub:font_choice}
+The X Window system originally did not have a suitable font renderer for video. It also is restricted to the current bit depth. It does not have a convenient way to know which fonts work with the suitable font renderer in the desired bit depth. The easiest way we have found to support fonts in the titler is to have a directory for them at \texttt{/usr/lib/cinelerra/fonts}.
+Or if not system installed, at \texttt{<cinelerra\_install\_path>/bin/plug\-ins/fonts}.
In order to choose a font faster, you can keyin the first few characters of the font name, being sure to use capital characters if used since it is case-sensitive. The steps to follow are:
\item keyin the first character(s) of the desired font and you will see the first match become highlighted;
\item you can see the characters you keyed in the upper right corner of the fonts.
\end{enumerate}
+It is important to note that because there are checkboxes for both Bold and Italic, the pulldown will not include these specific fonts
+as an addition to a Regular font. They will be used via the checkboxes but not viewed in the pulldown.
+
+One last item of information about fonts that may lead to some confusion. The checkbox for Bold and Italic will occasionally be ghosted out if no bold or italic version of the selected font is available. This is no guarantee, but currently as good as it can get due to inconsistency in the creation of fonts. It is mostly just a hint. If boxes are checkmarked, but ghosted, you can not uncheck until you change to a font that does not ghost out the boxes. If you use the popup helper with the boxes checked, and attempt to keyin a font that does not have the bold/italic attribute as checked, the font will be considered illegal.
+
+Also of note, if the video is displayed on a consumer TV, the outer border is going to be cropped by $5\%$ on each side. To avoid text which is too close to the edge looking bad, you may want to enable the \textit{title-safe} tool in the compositor window. The text should not cross the inner rectangle.
\subsubsection*{Font Addition / Font Subtraction}%
\label{ssub:font_addition_subtraction}
-Some of the system fonts are automatically included in the set of fonts being used by \CGG{}. The easiest way to add additional fonts for the Title plugin's set, is to use ones available in specific directories on your computer as long as they have a \texttt{fonts.scale} file already set up. You can run \texttt{mkfontscale} to create this file within that directory. In order to include a specific directory you set an environment variable before starting \CGG{} which stays in effect until it is unset or until the next reboot. Below is the method and an example.
+If using a compiled build (that is, NOT an AppImage) to add true type fonts, copy the \texttt{.TTF} files to the fonts directory at \texttt{/usr/lib/cinelerra/fonts}
+or if not system installed, at \texttt{<cinelerra\_install\_path>/bin/plug\-ins/fonts}. In that directory run
+\vspace{1ex}
+\begin{lstlisting}[style=sh]
+ # /usr/lib/cinelerra/fonts
+ ttmkfdir && mv fonts.scale fonts.dir
+\end{lstlisting}
+and restart \CGG{}. The new fonts should appear. However, keep in mind that the next
+time you install a new version of CINELERRA-GG, your changes will be written over so
+you will have to make sure to save them elsewhere and then re-establish.
+The usage of ttmkfdir changes frequently so this technique might not work. The titler supports mainly \textit{TTF}, true type fonts. It supports others such as OTF, but TTF are the most reliable.
+
+AppImage does not provide this specific method unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
+However, if you use Ubuntu Studio 2304 with AppImage, you can easily add font files directly to ~/.fonts and you will have all of these available in the Title fonts list. And, there may be other operating systems with specific implementations that also allow for this easier methodology to add additional fonts.
+
+Some of the system fonts are automatically included in the set of fonts being used by \CGG{}. The easiest way to add additional system or other application available fonts for the Title plugin's set, is to use ones available in specific directories on your computer as long as they have a \texttt{fonts.scale} file already set up. You can run \texttt{mkfontscale} to create this file within that directory. In order to include a specific directory you set an environment variable before starting \CGG{} which stays in effect until it is unset or until the next reboot. Below is the method and an example.
\vspace{1ex}
\begin{lstlisting}[style=sh]
The current set of fonts in \CGG{}'s directory will be automatically included and will be the default set if this environment variable is not set. Keep in mind that if you add a lot of fonts, it will considerably slow down the startup every time you bring up the Title plugin.
-If you want to only have a limited number of fonts set up, you can manipulate the \CGG{} directory directly at \texttt{<cinelerra\_install\_path> /bin/plug\-ins/fonts}.
+If you want to only have a limited number of fonts set up, you can manipulate the \CGG{} directory directly at \texttt{<cinelerra\_install\_path>/bin/plug\-ins/fonts}.
Here you will find the default set of fonts that come with the install. Copy any other fonts you would like to include here with read permission, delete any fonts you do not want to have, then execute \texttt{mkfontscale} which creates the file \texttt{fonts.scale} that \CGG{} will read. However, the next time you install a new version of \CGG{}, your changes will be written over so you will have to make sure to save them elsewhere and then re-establish.
If you have problems with a specific font or set of fonts, there is a debug option available to determine which font is an issue. When starting \CGG{}, you should set up the variable:
export BC_FONT_PATH=:/usr/share/fonts #(remove all fonts and then add /usr/shar/fonts)
\end{lstlisting}
-One last item of information about fonts that may lead to some confusion. The checkbox for Bold and Italic will occasionally be ghosted out if no bold or italic version of the selected font is available. This is no guarantee, but currently as good as it can get due to inconsistency in the creation of fonts. It is mostly just a hint. If boxes are checkmarked, but ghosted, you can not uncheck until you change to a font that does not ghost out the boxes. If you use the popup helper with the boxes checked, and attempt to keyin a font that does not have the bold/italic attribute as checked, the font will be considered illegal.
-Text: chars is output and updated to indicate the number of characters already used. The only limit to the number of characters based on a count of single $8\, bit$ characters is the available resources on the user computer available for \CGG{} use. Keep in mind that unicode or other special characters may consist of $2$ to $4$ $8\,bit$ bytes. Also, newlines are a character and any of the attributes you use count in the total. There is now a horizontal scroll bar as well as the vertical one in the textbox and they only appear when there are more lines or characters that can fit in the original sized textbox.
-
\subsubsection*{Kerning}%
\label{ssub:kerning}
\label{fig:tracer-01}
\end{figure}
-\begin{figure}[hbtp]
- \centering
- \includegraphics[width=0.7\linewidth]{tracer-02.png}
- \caption{Rug in the top picture is traced in order to black it out or replace later}
- \label{fig:tracer-02}
-\end{figure}
-
\begin{description}
\item[New] to create a new point.
\item[Up/Dn] to move highlighted point up or down.
\item[Mouse wheel + shift] scale the outline, centered on cursor.
\end{description}
+\begin{figure}[hbtp]
+ \centering
+ \includegraphics[width=0.7\linewidth]{tracer-02.png}
+ \caption{Rug in the top picture is traced in order to black it out or replace later}
+ \label{fig:tracer-02}
+\end{figure}
+
Be sure to uncheck \textit{Draw} and \textit{Drag} before rendering so that the lines do not show in the video output.
Videoscope summarizes intensity and color on a calibrated display. The Videoscope can be used in conjunction with other \CGG{} plugins such as \textit{Color 3 Way}, \textit{YUV}, \textit{Brightness}, \textit{Color Balance} or \textit{Histogram} to accurately correct video for contrast, clarity, conformance (to normalize various videos shot under different light settings), or for cinematic purposes. The human eye is not specialized to match precise level of light and color, but Videoscope is. Videoscope contains three displays: the waveform scope and the vectorscope, plus the histograms (figure~\ref{fig:videoscope01}). Instead of applying the plugin to the tracks/edits we want to examine, we can use the Videoscope buttons in the Composer and Viewer windows. \includegraphics[height=\baselineskip]{scope.png} In this way the monitors act on the frame indicated by the insertion point, without taking into account the stack of tracks or on which edits to apply the plugin.
+\begin{figure}[hbtp]
+ \centering
+ \includegraphics[width=1.0\linewidth]{videoscope01.png}
+ \caption{GUI of the Videoscope. You see Histogram, RGB Parade and Vectorscope}
+ \label{fig:videoscope01}
+\end{figure}
+
+When using the X11 graphics driver and RGBA-FLOAT color model, Videoscope allows you to display greater than (0 - 1.0f) values to accomodate HDR. This does not work when using X11-OpenGL because it is an 8-bit limited driver. The display will stop at -10\% or +110\%, but there is no clipping. For example, by varying the brightness all out-of-range values become visible on Waveform, even over 110\%. However you must disable the "smooth" option which always causes clipping.
+
The Videoscope menu window has many options.
\paragraph*{Scopes:} we can choose between two histograms:
\item \textit{VectorWheel}
\end{itemize}
-\begin{figure}[hbtp]
- \centering
- \includegraphics[width=1.0\linewidth]{videoscope01.png}
- \caption{GUI of the Videoscope. You see Histogram, RGB Parade and Vectorscope}
- \label{fig:videoscope01}
-\end{figure}
-
\paragraph*{Settings:} It is divided into two sections. The upper section contains two items:
\begin{description}
- \item[Smooth:] serves to make the graph more homogeneous, improving its visualization.
+ \item[Smooth:] serves to make the graph more homogeneous, improving its visualization. However, it has a side effect: in case of frames that have data in the range of 100-110\% (i.e., outside the normal range of 0-100\%, also called super-white), it causes a clip by cutting off this data and reporting only of normal data. If we don't want this clip disable Smooth.
\item[Refresh on Stop ON:] [checked -- only for Transport buttons] scopes are updated when you stop playback at a given location. Instead, they are locked at the start position while you playback. This saves system resources and makes playback smoother. By dragging the cursor the scopes are updated in realtime.
\item[Refresh on Stop OFF:] [unchecked -- for Transport buttons and dragging cursor] the display of the scopes is synchronized with the playback. Every variation of the graphs is in realtime. There may be some decrease in fps during playback.
\item[Refresh on Release:] This works for the Viewer and Compositor windows. Scopes are not updated during playback. The update occurs only when you stop playback, that is at the final position (either by dragging the cursor or using the Transport buttons). When in the timeline, if you drag on the TimeBar or reposition in the TimeBar in either Drag and Drop or Cut and Paste mode, the release of the button also will update the Scopes. This saves system resources and makes playback smoother. Because there is no update when playing in the main window, you can still easily get a videoscope update simply by moving the mouse to the Compositor and a single click there will update the scopes without changing the frame (as long as Click to Play is not enabled).
If we left-click on the graph with the mouse, we will see a crosshair that we can place exactly where we want to measure. We can read the precise values of X and Luminance (Value) in the pop-up box that appears at the bottom right (figure~\ref{fig:videoscope03}).
-The Waveform scope helps correct image light levels for contrast range or for conforming light levels on various scenes originally shot on different light settings. The same can be done with Waveform RGB or the convenient overlapping representation (Waveform Ply).
-
\begin{figure}[hbtp]
- \centering
- \includegraphics[width=1.0\linewidth]{videoscope03.png}
- \caption{Examples of waveform (with crosshair and the coordinates' box), waveform RGB and waveform Ply}
- \label{fig:videoscope03}
+ \centering
+ \includegraphics[width=1.0\linewidth]{videoscope03.png}
+ \caption{Examples of waveform (with crosshair and the coordinates' box), waveform RGB and waveform Ply}
+ \label{fig:videoscope03}
\end{figure}
+The Waveform scope helps correct image light levels for contrast range or for conforming light levels on various scenes originally shot on different light settings. The same can be done with Waveform RGB or the convenient overlapping representation (Waveform Ply).
+
\subsubsection*{Adjusting luminance}%
\label{ssub:adjusting_luminance}
\label{sub:yuv411}
\index{yuv411}
-Modify the 411 yuv to look like 420 color space instead. If the edit to which the effect is applied is not YUV type, a red warning message will appear.
+YUV411 plugin\protect\footnote{credit Eric Olson}
+modifies the 411 yuv to look like 420 color space instead. If the edit to which the effect is applied is not YUV type, a red warning message will appear.
\subsection{YUVShift}%
\label{sub:yuvshift}
To build findobject and the other plugins using OpenCV, access the src using git:
\begin{lstlisting}[style=sh]
-git clone -depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
+git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
\end{lstlisting}
To use the latest version, the method for creating a tarball is:
compression/expansion filter.
\item [F\_acrusher]~\\Reduces audio bit resolution.
\item [F\_acue]~\\Delay filtering to match a cue.
+\item [F\_adecorrelate]~\\Apply decorrelation to input audio stream.
\item [F\_adelay]~\\Delays one or more audio channels.
-\item [F\_adenorm]~\\Remedy denormals by adding extremely
- low-level noise.
+\item [F\_adenorm]~\\Remedy denormals by adding extremely low-level noise.
+\item [F\_adynamicequalizer]~\\Apply dynamic equalization to input audio stream.
+\item [F\_adynamicsmooth]~\\Apply dynamic smoothing to input audio stream.
\item [F\_aderivative]~\\Compute derivative of input audio.
\item [F\_aecho]~\\Adds echoing to the audio.
\item [F\_aemphasis]~\\Audio emphasis.
\item [F\_aformat]~\\Convert the input audio to one of he
specified formats.
\item [F\_afreqshift]~\\Apply frequency shifting to input audio.
+\item [F\_afwtdn]~\\Reduce broadband noise from input samples using Wavelets.
\item [F\_agate]~\\Audio gate.
-\item [F\_aintegral]~\\Compute integral of input audio.
+\item [F\_alatency]~\\Measure filtering latency.
\item [F\_allpass]~\\Applies a two-pole all-pass filter.
\item [F\_aloop]~\\Loops audio samples.
\item [F\_anoisesrc]~\\Generates a noise audio signal.
frame.
\item [F\_aphaser]~\\Adds a phasing effect to the audio.
\item [F\_aphaseshift]~\\Apply phase shifting to input audio.
+\item [F\_apsyclip]~\\Apply Psychoacoustic clipper to input audio stream.
\item [F\_arealtime]~\\Slows down filtering to match realtime.
\item [F\_aresample]~\\Resamples audio data.
-\item [F\_asetrate]~\\Change the sample rate without altering
- the data.
-\item [F\_astats]~\\Shows time domain statistics about audio
- frames.
+\item [F\_asetrate]~\\Change the sample rate without altering the data.
+\item [F\_aspectralstats]~\\Display frequency domain statistical information about the audio channels. Statistics are calculated and stored as metadata for each audio channel and for each audio frame.
+\item [F\_astats]~\\Shows time domain statistics about audio frames.
\item [F\_asubboost]~\\Boost subwoofer frequencies.
\item [F\_asubcut]~\\Cut subwoofer frequencies.
\item [F\_asupercut]~\\Cut super frequencies.
\item [F\_asuperpass]~\\Apply high order Butterworth band-pass filter.
\item [F\_asuperstop]~\\Apply high order Butterworth band-stop filter.
-\item [F\_atempo]~\\Adjusts audio tempo so that when you speed up audio, it will
-adjust the pitch accordingly to make audio sounds more normal, but faster without
-being badly distorted. Its behavior is similar to what can be seen when you watch
-a youtube video, click the gear icon, and select a speed greater or less than 1.
+\item [F\_atempo]~\\Adjusts audio tempo so that when you speed up audio, it will adjust the pitch accordingly to make audio sounds more normal, but faster without being badly distorted. Its behavior is similar to what can be seen when you watch a youtube video, click the gear icon, and select a speed greater or less than 1.
+\item [F\_atilt]~\\Apply spectral tilt filter to audio stream.
\item [F\_atrim]~\\Pick one continuous section from the input,
drop the rest.
\item [F\_bandpass]~\\Applies a two-pole Butterworth band-pass
audio channels. When using this plugin, be sure to \textit{attach
effect} to all audio tracks by dragging the plugin to the $1^{st}$
audio track and then right mouse clicking all subsequent audio
- tracks which brings up an menu. Highlight the effect shown in the
+ tracks which brings up a menu. Highlight the effect shown in the
middle section and click OK.
\item [F\_flanger]~\\Applies a flanging effect to the audio.
\item [F\_haas]~\\Apply Haas Stereo Enhancer for a more
tracks by dragging the plugin to the $1^{st}$ audio track and then
right mouse clicking all subsequent audio tracks which brings up an
menu. Highlight the effect shown in the middle section and click OK.
+\item [F\_tiltshelf]~\\Boost or cut the lower frequencies and cut or boost higher frequencies of the audio using a two-pole shelving filter with a response similar to that of a standard hi-fi’s tone-controls. This is also known as shelving equalization (EQ).
\item [F\_treble]~\\Boosts or cuts upper frequencies.
\item [F\_tremolo]~\\Applies tremolo effect.
\item [F\_vibrato]~\\Applies vibrato effect.
+\item [F\_virtualbass]~\\Apply audio Virtual Bass filter.
\item [F\_volume]~\\Change input volume.
\item [F\_volumedetect]~\\Detect audio volume.
\end{description}
\item [F\_blackdetect]~\\Detect video intervals that are
(almost) black.
\item [F\_blackframe]~\\Detect frames that are (almost) black.
-\item [F\_boxblur]~\\Blurs the input video. Through the
- settings you are able to change the power and the radius of the
- boxblur applied to luma, chroma and alpha.
+\item [F\_blockdetect]~\\Determines blockiness of frames without altering the input frames.
+\item [F\_blurdetect]~\\Determines blurriness of frames without altering the input frames.
+\item [F\_boxblur]~\\Blurs the input video. Through the settings you are able to change the power and the radius of the boxblur applied to luma, chroma and alpha.
\item [F\_bwdif]~\\Deinterlaces the input image.
\item [F\_cas]~\\Apply Contrast Adaptive Sharpen filter to video.
\item [F\_chromakey]~\\Turns a certain color into
\item [F\_colorbalance]~\\Adjusts the color balance.
\item [F\_colorchannelmixer]~\\Adjusts colors by mixing color
channels.
+\item [F\_colorchart]~\\The colorchart source provides a colors checker chart.
\item [F\_colorcontrast]~\\Adjust color contrast between RGB
components.
\item [F\_colorcorrect]~\\Adjust color white balance selectivity
\item [F\_colormatrix]~\\Converts color matrix.
\item [F\_colorize]~\\Overlay a solid color on the video stream.
\item [F\_colorspace]~\\Converts color space.
+\item [F\_colorspectrum]~\\Provides a color spectrum input.
\item [F\_colortemperature]~\\Adjust color temperature of video.
\item [F\_cover\_rect]~\\Find and cover a user specified
object.
\item [F\_gradfun]~\\Debands video quickly using gradients.
\item [F\_gradients]~\\Draws a transparent gradient.
\item [F\_graphmonitor]~\\Show various filtergraph stats.
+\item [F\_grayworld]~\\A color constancy filter that applies color correction based on the grayworld assumption.
\item [F\_greyedge]~\\Estimates scene illumination by grey
edge assumption.
\item [F\_haldclutsrc]~\\Provide an identity Hald CLUT\@.
equalization.
\item [F\_histogram]~\\Computes and draws a histogram.
\item [F\_hqdn3d]~\\Applies a High Quality 3D Denoiser.
-\item [F\_hqx]~\\Scales the input by 2, 3 or 4 using the
- $hq*x$ magnification algorithm.
-\item [F\_hue]~\\Adjust the hue and saturation of the input
- video.
+\item [F\_hqx]~\\Scales the input by 2, 3 or 4 using the $hq*x$ magnification algorithm.
+\item [F\_hsvhold]~\\Turns a certain HSV range into gray values.
+\item [F\_hsvkey]~\\Turns a certain HSV range into transparency.
+\item [F\_hue]~\\Adjust the hue and saturation of the input video.
+\item [F\_huesaturation]~\\Apply hue-saturation-intensity adjustments to input video stream.
\item [F\_idet]~\\Interlace detect Filter.
\item [F\_il]~\\Deinterleaves or interleaves fields.
\item [F\_inflate]~\\Applies inflate effect.
\item [F\_kerndeint]~\\Applies kernel deinterlacing to the
input.
\item [F\_kirsch]~\\Apply kirsch operator.
-\item [F\_lenscorrection]~\\Rectifies the image by correcting
- for lens distortion.
+\item [F\_latency]~\\Measure filtering latency.
+\item [F\_lenscorrection]~\\Rectifies the image by correcting for lens distortion.
\item [F\_life]~\\Generate a life pattern.
\item [F\_limiter]~\\Limit pixels components to the specified
range.
\item [F\_perspective]~\\Corrects the perspective of video.
\item [F\_phase]~\\Phases shift fields.
\item [F\_photosensitivity]~\\Filter out photosensitive epilepsy seizure-inducing flashes.
-\item [F\_pixscope]~\\Pixel data analysis for checking color
- and levels. It will display sample values of color channels.
+\item [F\_pixscope]~\\Pixel data analysis for checking color and levels. It will display sample values of color channels.
+\item [F\_pixelize]~\\Apply pixelization to video stream.
\item [F\_pp]~\\Filters video using libpostproc.
\item [F\_pp7]~\\Applies Postprocessing 7 filter.
\item [F\_prewitt]~\\Apply prewitt operator.
\item [F\_rotate]~\\Rotates the input image by an arbitrary angle expressed in radians. If you want to rotate
by degrees, you can use the \textit{rotate} plugin instead.
\item [F\_sab]~\\Applies shape adaptive blur.
-\item [F\_scale]~\\Scale the input video size and/or convert
- the image format.
+\item [F\_scale]~\\Scale the input video size and/or convert the image format.
\item [F\_scdet]~\\Detect video scene change.
+\item [F\_scharr]~\\Apply scharr operator to input video stream.
\item [F\_scroll]~\\Scroll input video horizontally and/or vertically by constant speed.
\item [F\_separatefields]~\\Split input video frames into
fields.
\item [F\_shufflepixels]~\\Shuffles video pixels.
\item [F\_shuffleplanes]~\\Shuffles video planes.
\item [F\_sierpinski]~\\Generate a Sierpinski carpet/triangle fractal, and randomly pan around.
-\item [F\_signalstats]~\\Separates statistics from video
- analysis.
+\item [F\_signalstats]~\\Separates statistics from video analysis.
\index{over sharpened footage}
+\item [F\_siti]~\\Calculate Spatial Info (SI) and Temporal Info (TI) scores for a video, as defined in ITU-T P.910: Subjective video quality assessment methods for multimedia applications.
\item [F\_smartblur]~\\Blurs the input video without impacting
the outlines. Through the settings you can select the radius, the
strength and the threshold of luma and chroma. This plugin can be used to correct
--- /dev/null
+\chapter{Overview}%\r
+\label{cha:camcorders}\r
+\r
+This document describes the methods used to achieve a "backup type" or intermediate codec\r
+for non-edited source video camcorder formats, compatible with and viewable on Bluray hardware players. After you have\r
+moved your camcorder media onto a computer disk, you can with some extra effort, transfer them for safekeeping and\r
+longer term storage on simple viewable Blu-ray video discs. \r
+\r
+Transferring camcorder media to digital files on a computer, and next to optical Blu-ray video media is especially\r
+important for legacy tape-based camcorders, because tape will degrade over time. You can do this using a combination of\r
+free tools on Linux, generic and independent of any NLE. \r
+\r
+In this case we use and keep interlaced video as on the source or digitized video (PAL 50i, 25 fps) for both DV and HDV\r
+formats. As confirmed by the ffmpeg output below, DV uses 25 Mbps data rate (DV25), is Standard Definition (SD),\r
+resolution 720{\texttimes}576, 8 bits color depth 4:2:0, display aspect ratio (DAR) 4:3 while HDV is High Definition HD video,\r
+resolution 1440{\texttimes}1080, DAR 16:9, 8 bits color depth 4:2:0. \r
+\r
+We utilize or keep relative low MPEG-2 video compression at the same bit-rate 25 Mbps as the original video recorded\r
+onto the source tapes. That is about 13 GB per hour video and audio in total, and about 3 hours playtime with 40 GB\r
+BD-video size (of max 46.5 GB) on each 50 GB BD-R DL Blu-ray disc. Audio is transcoded to uncompressed LPCM compatible\r
+with BD-video. \r
+\r
+In this how-to we combine \textbf{ffmpeg}, \textbf{tsMuxeR} and \textbf{xorriso} to create the MTS-video stream, to\r
+create the Blu-ray ISO image, and to burn the image to Blu-ray video disc. The benefit of using tsMuxer here, is its\r
+support of UDF version 2.50 as required by the Blu-ray video standard. Listed next are the possible camcorder video formats on Blu-ray video discs.\r
+\r
+\begin{itemize}\r
+\item \textbf{DV} (1995) transfer to SD-blu-ray video (re-encoding video to mpeg2, re-encoding DV LPCM audio to Blu-ray LPCM) \r
+\item \textbf{HDV} (2004) transfer to blu-ray video (copying mpeg2 video, re-encoding MP2 audio to Blu-ray LPCM or AC3) \r
+\item \textbf{AVCHD} (2006-current) transfer to Blu-ray video (copying H.264 video and AC3 audio)\r
+\end{itemize}\r
+\r
+An alternative method as described in the CinGG manual, is to use \textit{mkudffs} and \textit{bdwrite} packaged with CinGG, to create the udfs image and burn it to Blu-ray disc using \textit{growisofs} or \textit{dd}. \\\r
+{\small \url{https://cinelerra-gg.org/download/CinelerraGG\_Manual/Creating\_Blu\_ray\_Without\_Re.html}}\r
+\r
+There are other methods described on the internet and there are alternatives to the software programs used here that work as well. \r
+\r
+\chapter{Video recording formats}%\r
+\label{cha:recording}\r
+\r
+A description of the most common video recording formats for consumer and prosumer equipment; camcorders, analog video\r
+cassette recorders (VCR decks), digital video hard disc recorders, and optical disc recorders (DVD, Blu-ray).\r
+\r
+\section{\textbf{Analog video} (legacy) onto magnetic tape cassettes}%\r
+\label{sec:analog}\r
+\settocdepth{subsection}\r
+\r
+\subsection{\textbf{VHS (1976), VHS-C (1982), and Video8 (1984)}}%\r
+\label{sub:vhs1976}\r
+\r
+%\r
+% WARNING - the next line will change it for every list for rest of document\r
+%\r
+%\setlist{noitemsep}\r
+\begin{itemize}[noitemsep]\r
+\item Composite Audio/Video is encoded on one channel with maximum horizontal resolution 240 (250) dots (or visually\r
+resolvable vertical picture lines) for VHS/VHS-C and 280 dots for Video8 (2.7MHz video bandwidth).\r
+\item In comparision, horizontal resolution bandwidth for PAL broadcast: 5.0-5.5 MHz, NTSC: 4.2 MHz.\r
+\item It is the horizontal resolution that makes the big difference in picture quality since all video formats have the\r
+same number of vertical resolution (or visible horizontal scan lines); always 576 for PAL/SECAM and 486 for NTSC.\r
+\item RCA (phono) connectors: yellow for composite video, red and white for left and right audio signals.\r
+\item 21-pin SCART Euro connector with optional RCA adapter.\r
+\item Magnetic tape media in full size VHS (1/2") cassettes, VHS-C (1/4") compact and 8\ mm cassettes.\r
+\item Cassette adapters to playback compact VHS-C cassettes on full size VHS decks/players.\r
+\end{itemize}\r
+\r
+\subsection{SVHS (Super VHS, 1987), SVHS-C (-Compact, 1987) and Hi8 (1989)}%\r
+\label{sub:svhs1987}\r
+\r
+\begin{itemize}[noitemsep]\r
+\item S-Video (separate video, Y/C) encodes video \href{https://en.wikipedia.org/wiki/Luma\_(video)}{luma}\r
+(brightness/contrast/black\&white) and\r
+\href{https://en.wikipedia.org/wiki/Chrominance}{chrom}\href{https://en.wikipedia.org/wiki/Chrominance}{a} (color) on\r
+two separate channels, achieving higher image quality and amount of picture details over composite video.\r
+\item Max visible horizontal resolution is 400 dots for SVHS/SVHS-C and 440 dots for Hi8 systems on high-end VCR\r
+machines (4.5 MHz decks). In practice consumer/prosumer camcorder recordings quality vary from about 330-350 dots\r
+horizontal resolution (3.5MHz), which is equivalent to analog TV set quality.\r
+\item 4-pin mini-DIN S-video connector for Y/C video, red and white RCA line connectors for left and right audio;\r
+optional SCART Euro adapter with 4-pin video and RCA audio connectors.\r
+\item In comparision, analog Component video (three component YPbPr) has the highest color resolution and is encoded\r
+over three channels with green, blue and red RCA connectors (consumer) or with BNC connectors (prosumer), additional red\r
+and white phono line connectors for audio.\r
+\end{itemize}\r
+\r
+\section{\textbf{Digital video}}%\r
+\label{sec:digital}\r
+\r
+\subsection{\textbf{DV (1995), Digital8 (1999)}}%\r
+\label{sub:dv1995}\r
+\r
+\begin{itemize}[noitemsep]\r
+\item DV refers to a family of codecs and tape formats used for storing digital video, especially on MiniDV cassettes, the most popular tape format, or on Digital8 cassettes using a DV codec. \r
+\item DV codecs are still sometimes used when dealing with legacy standard definition SD video:\r
+ \newline\hspace*{.5cm}PAL: 625i50, 720 {\texttimes} 576 frame size, 25 fps, 8 bit 4:2:0 subsampling\r
+ \newline\hspace*{.5cm}NTSC: 525i60, 720 {\texttimes} 480 frame size, 30 fps, 8-bit 4:1:1 subsampling\r
+\item The same frame size is used for 4:3 and 16:9 frame aspect ratios, resulting in different pixel aspect ratios for\r
+fullscreen and anamorphic widescreen video.\r
+\item DV uses lossy, DCT algorithm intraframe video compression 5:1 on a frame-by-frame basis.\r
+\item Audio almost exclusively is stored as 16-bit LPCM at 48 kHz sampling rate, 1.5 Mbit/s stereo.\r
+\item Data rate is about 25 Mbit/s for video, thus DV25, and an additional 1.5 Mbit/s for PCM audio. \r
+\item Total stream is 29 Mbps, or 3.6 MiB/s. The information output is approximately 200 MiB per minute, 12 GiB or 13 GB\r
+per hour playtime.\r
+\item DV camcorders and decks have IEEE 1394 (FireWire, i.LINK) ports for digital video transfer. \r
+\item \textbf{DV50} (Digital-S or D-9 and DVCPRO50) is a 50 Mbit/s variant of DV with improved 4:2:2 chroma subsampling and 3.3:1 compression. This in effect cuts total record time of any given storage medium in half compared to DV25. \r
+\item DV was strongly associated with the transition from analog to digital desktop video production.\r
+\item Digital8 equipment recorded in DV format only, but usually could playback Video8 and Hi8 tapes as well, and were\r
+also capable to do analog to digital video conversion during playback. \r
+\item Most (but not all) modern digital camcorders provided an analog-to-digital\r
+"passthrough" capability. This feature fed an analog input signal (usually via S-Video,\r
+sometimes RCA) into the camcorder and output a standard DV signal. The camcorder converts the analog signal on-the-fly\r
+using a hardware encoder. The input device could be your old analog camcorder (playing 8\ mm or Hi8 tapes), a VHS/VHS-C\r
+video player, to convert analog to digital output via Firewire \textbf{dv} file extension.\r
+\end{itemize}\r
+\r
+\subsection{\textbf{DVD-Video} (1996)}%\r
+\label{sub:DVD-Video}\r
+\r
+DVD-Video discs are intended for full-length movies and offer a range of features including the following:\r
+\begin{itemize}[noitemsep]\r
+\item Playing time: a nominal 133 minutes playing time for DVD-5 or each side of a DVD-10 and 240 minutes for DVD-9 using opposite track path format. In practice playing times are often reduced in favour of improved quality.\r
+\item Video encoding: MPEG-2 (\href{mailto:MP@ML}{MP@ML}) or MPEG-1.\r
+\item Audio Quality and Languages: Dolby Digital, DTS, MPEG-2 or Linear PCM audio for up to 5.1 channel surround sound.\r
+\end{itemize}\r
+\r
+\begin{itemize}\r
+\item To record digital video, DVD-Video uses \href{https://en.wikipedia.org/wiki/H.262/MPEG-2\_Part\_2}{H.262/MPEG-2 Part\r
+2} compression at up to 9.8~Mbit/s, maximum of 10.08 Mbit/s can be split amongst audio and video. DVD-Video supports\r
+video with a \href{https://en.wikipedia.org/wiki/Color\_depth}{bit depth} of 8 bits per color, encoded as\r
+\href{https://en.wikipedia.org/wiki/YCbCr}{YCbCr} with 4:2:0\r
+\href{https://en.wikipedia.org/wiki/Chroma\_subsampling}{chroma subsampling}. The H.262/MPEG-2 Part 2 format supports\r
+both interlaced and progressive scan content.\r
+\item As for lines of horizontal resolution, DVD has about 500. In analog output signal terms, typical luma frequency\r
+response maintains 53/145 full amplitude to between 5.0 - 5.5 MHz. This is below the 6.75 MHz native frequency of the\r
+MPEG-2 digital signal. Chroma frequency response is one-half that of luma.\r
+\end{itemize}\r
+\r
+The following formats are allowed for H.262/MPEG-2 Part 2 video:\r
+\begin{itemize}\r
+\item At a display rate of 25 frames per second, interlaced or progressive scan (commonly used in regions with 50 Hz\r
+image scanning frequency, compatible with analog 625-line PAL/SECAM):\r
+ \begin{adjustwidth}{.5cm}{0cm}\r
+ 720 {\texttimes} 576 pixels (D-1 resolution, 4:3 fullscreen or 16:9 anamorphic widescreen aspect ratio)\r
+ \end{adjustwidth}\r
+\item At a display rate of 29.97 frames per second, interlaced or progressive scan (commonly used in regions with 60 Hz\r
+image scanning frequency, compatible with analog 525-line NTSC):\r
+ \begin{adjustwidth}{.5cm}{0cm}\r
+ 720 {\texttimes} 480 pixels (D-1 resolution, 4:3 or 16:9)\r
+ \end{adjustwidth}\r
+\end{itemize}\r
+\r
+The official allowed formats for the audio tracks on a DVD-Video are:\r
+ \begin{itemize}\r
+ \item PCM: 48 kHz or 96 kHz sampling rate, 16 bit or 24 bit Linear PCM, 2 to 6 channels, up to 6,144 kbit/s; N. B.\r
+16-bit 48 kHz 8 channel PCM is allowed by the DVD-Video specification but is not well supported by authoring\r
+applications or players.\r
+ \item AC-3: 48 kHz sampling rate, 1 to 5.1 (6) channels, up to 448 kbit/s.\r
+ \item MP2: 48 kHz sampling rate, 1 to 7.1 channels, up to 912 kbit/s.\r
+ \item DTS: 48 kHz or 96 kHz sampling rate; channel layouts = 2.0, 2.1, 5.0, 5.1, 6.1; bitrates for 2.0 and 2.1 =\r
+377.25 and 503.25 kbit/s, bitrates for 5.x and 6.1 = 754.5 and 1509.75 kbit/s.\r
+\item File system:\r
+\begin{itemize}[noitemsep]\r
+\item Almost all DVD-Video discs use the UDF bridge format, which is a combination of the DVD MicroUDF (a subset of UDF 1.02) and ISO 9660 file systems.\r
+\item The UDF bridge format provides backwards compatibility for operating systems that\r
+support only ISO 9660. \r
+\item Most DVD players read the UDF filesystem from a DVD-Video disc and ignore the ISO9660 filesystem. \r
+\end{itemize}\r
+\end{itemize}\r
+\r
+\subsection{\textbf{HDV (2003)}}%\r
+\label{sub:HDV2003}\r
+\r
+\begin{itemize}[noitemsep]\r
+\item HDV was a successor format to DV with an updated video codec, and used the same MiniDV cassette format, optional\r
+specifically for HDV recording on tape with reduced drop-out rate.\r
+\item Some manufacturers offered on (larger) camera hard disk recording units capable of recording HDV both onto tape\r
+and/or onto file-based media via FireWire connection. \r
+\item HDV camcorders can typically switch between HDV/MP2 and SD-DV/PCM recording modes.\r
+\item HDV 1080i with horizontal resolution 1440 is twice the 720 resolution of DV and DVD, and the perceived\r
+sharpness with HDV is much higher when scaled up to full HD (TV) resolution.\r
+\end{itemize}\r
+\r
+\begin{tabular}{ll}\r
+------------------- \\\r
+{\textbullet}\textbf{HDV 1080i} specification (HD2): & \textbf{HDV 720p} specification (HD1): \\\r
+{\textbullet} 1080/ 50i (PAL), 1080/ 60i (NTSC) & 720/25p, 720/50p,720/30p, and 720/60p \\\r
+{\textbullet} 1440 {\texttimes} 1080, anamorphic pixels 4:3=1.33 & 1280 x 720, Pixel aspect ratio 1.0 \\ \r
+{\textbullet} 16:9 Display aspect ratio & 16:9 Display aspect ratio \\\r
+\hspace*{.5cm} - 720{\texttimes}480/ 60i (SD-DV 4:3 og 16:9) \\\r
+\hspace*{.5cm} - 720{\texttimes}576/ 50i (SD-DV 4:3 og 16:9) \\\r
+{\textbullet} MPEG-2 interframe GOP (\href{mailto:MP@H-14}{MP@H-14}) & MPEG-2 (\href{mailto:MP@H-14/HL}{MP@H-14/HL}) \\\r
+{\textbullet} 8 bit color depth 4:2:0 subsampling & 8 bit color depth 4:2:0 subsampling \\\r
+{\textbullet} 25 Mbps data rate after compression (20:1) & 19.4 Mbps data rate after compression \\\r
+{\textbullet} MP2/MPEG-1 Audio Layer II & MP2/MPEG-1 Audio Layer II \\ \r
+{\textbullet} Stereo (2-ch), 384 kbps & Stereo (2-ch), 384 kbps \\\r
+{\textbullet} A/V out: HDMI, Component, S-video/RCA\ & A/V out: HDMI, Component, S-video/RCA \\\r
+{\textbullet} IEEE 1394 (MPEG-2-TS) stream interface & IEEE 1394 (MPEG-2-TS) stream interface \\\r
+{\textbullet} M2T file extension & M2T file extension\r
+\end{tabular}\r
+\r
+\subsection{\textbf{AVCHD (2006-current)}}%\r
+\label{sub:AVCHD}\r
+\r
+\begin{itemize}\r
+\item AVCHD stands for \textit{Advanced Video Coding High Definition}, in particular, \textit{MPEG-4 Part 10:\r
+AVC/H.264}. The intent of the H.264/AVC project was to create a standard capable of providing good video quality at\r
+substantially lower bit rates than previous standards (i.e., half or less the bit rate of MPEG-2, H.263, or MPEG-4 Part\r
+2). \\ \r
+\item AVCHD is a file based format for digital camcorders to record and playback 1080i and 720p HD-video onto certain\r
+random access media. Memory cards, thumb drives, and HDDs use the FAT file system. This highly compressed video allows for\r
+recording long videos in high definition.\\\r
+\item AVCHD was originally a simplified version of the Blu-ray standard to enable DVD and BD-based camcorders.\r
+Recordable optical discs use UDF or ISO9660 derived from the Blu-ray disc specification. For example, it utilizes a\r
+legacy 8.3 file naming system while Blu-ray disc uses long filenames. \\\r
+\item MTS file extension changes to M2TS when MTS recorded data is transferred to the computer for storing the video in\r
+a Blu-ray disc. \\\r
+\item Playback is possible on an AVCHD-compatible Blu-ray Disc player/recorder, DVD player/recorder, or PlayStation 3, \r
+the 8 cm DVDs (discs recorded in AVCHD) you have recorded or DVDs (discs recorded in AVCHD) and Blu-ray Discs created\r
+by importing videos to a PC or Blu-ray Disc player. \\\r
+\item Today AVCHD is the most popular camcorder format for consumers and prosumers, and is also available as AVCHD\r
+Progressive/PCM models for professional use.\\\r
+\item AVCHD supports both \textit{AVCHD-SD Standard Definition} and \textit{AVCHD 1080i High Definition} interlaced\r
+video, while AVCHD 1080i is available with most AVCHD camcorders. AVCHD supports 720-line progressive recording mode at\r
+frame rates of 24 and 60 frames/s for 60 Hz models and 50 frames/s for 50 Hz models.\\\r
+\item Also, 3D (MVC format) and 1080/60p(1080/50p) video formats were added as an extension to the AVCHD format to\r
+create the \textit{AVCHD Ver. 2.0, 2011} (AVCHD 3D, AVCHD Progressive) format. Compatibility in AVCHD Ver. 2.0 format compliant devices is secured by being standardized as the AVCHD format.\\\r
+\end{itemize}\r
+--------------------------------------\r
+\r
+\begin{tabular}{ll}\r
+ \textbf{8\ cm DVD/Built-in/SD Memory/M-Stick: } & \textbf{Built-in media/SD Memory/Memory Stick:} \\\r
+\r
+ {\textbullet} 1920{\texttimes}1080/ 60i, 50i, 24p & 1920{\texttimes}1080/ 60p, 50p \\ \r
+ {\textbullet} 1440{\texttimes}1080/ 60i, 50i, 24p & 1440{\texttimes}1080/ 60p, 50p \\\r
+ {\textbullet} 1280{\texttimes}720/ 60i, 50i, 24p & 1280{\texttimes}720/ 60p, 50p \\\r
+ {\textbullet} 720{\texttimes}480/ 60i (SD 4:3 og 16:9) \\\r
+ {\textbullet} 720{\texttimes}576/ 50i (SD 4:3 og 16:9) \\ \r
+ {\textbullet} 16:9 Display aspect ratio & 16:9 Display aspect ratio \\\r
+ {\textbullet} MPEG-4 Part 10: AVC / H.264 & MPEG-4 Part 10: AVC / H.264 \\\r
+ {\textbullet} 8 bit color depth 4:2:0 subsampling & 8 bit color depth 4:2:0 subsampling \\\r
+ {\textbullet} {\textless}= 24 Mbps data rate & {\textless}= 28 Mbps data rate \\\r
+ {\textbullet} {\textless}= 18 Mbps data rate for DVD \\\r
+ {\textbullet} Dolby Digital AC-3\ \ , 64-640 kbps & Dolby Digital AC-3, 64-640 kbps \\ \r
+ \hspace*{.3cm} 2 ch stereo and 5.1 (5-ch + subw.) surround & \hspace*{.3cm} 1$\sim$ 5.1 channels \\\r
+ {\textbullet} Linear PCM, 1.5 Mbps (2 ch) & Linear PCM, 1.5 Mbps (2 ch) \\\r
+ \hspace*{.3cm}1$\sim$ 7.1 channels & \hspace*{.3cm} 1$\sim$ 7.1 channels \\\r
+ {\textbullet} A/V out: HDMI, Component, S-video/RCA & A/V out: HDMI, Component, S-video/RCA \\\r
+ {\textbullet} MPEG-2 Transport Stream & MPEG-2 Transport Stream \\\r
+ {\textbullet} MTS file extension\ \ (recorded) & MTS file extension (recorded) \\\r
+\end{tabular}\r
+\r
+\subsection{\textbf{Blu-ray BD-Video (2006), UHD-video (2016)}}%\r
+\label{sub:Blu-ray}\r
+\r
+All standard DVDs will play on existing Blu-ray players, making the switch to Blu-ray much easier than the switch\r
+from VHS to DVD. Ultra HD Blu-ray is the latest version available, supporting 4K resolution content. Historically,\r
+Blu-ray Disc allows video with a color (bit) depth of 8-bits per color YCbCr with 4:2:0 chroma subsampling (colors\r
+compressed to 25\% of uncompressed), which means 256 possible values for red, green and blue; 16.7 million colors in\r
+total. Ultra-HD Blu Ray is 10-bit 4:2:0 to reduce color banding, giving 1024 values for RGB, 1.0 billion colors in\r
+total, or 64x more than 8-bit.\r
+\r
+BDMV Video encoding: \r
+\begin{itemize}[noitemsep]\r
+\item UDF2.5 as file system (BD-R/RE, 2005)\r
+\item M2TS file extension\r
+\item H.262/MPEG-2 Part 2 (\href{mailto:MP@HL}{MP@HL}, \href{mailto:MP@ML}{MP@ML})\r
+\item H.264/MPEG-4 AVC (\href{mailto:HP@L4.1}{HP@4.1}, \href{mailto:MP@L4.1}{MP@4.1})\r
+\item SMPTE VC-1 (\href{mailto:AP@L3}{AP@L3})\r
+\item H.265/H.265/MPEG-H Part 2 (HEVC) (only Ultra HD Blu-ray on High-density optical disc)\r
+\end{itemize}\r
+\r
+BD Video movies have a maximum data transfer rate of 54 Mbit/s, a maximum AV bitrate of 48 Mbit/s (for both audio\r
+and video data), and a maximum video bit rate of 40 Mbit/s., BD disc capacities, each with its own data rate: \r
+\begin{itemize}[noitemsep]\r
+\item 25 GB (BD-R SL)\r
+\item 50, 66 GB (BD-R DL) at 72 or 92 Mbit/s (50 GB BD-R DL 4x read speed supports UHD-video)\r
+\item 100 GB (TL), 128 GB (QL) at 92, 123, or 144 Mbit/s (BD-R XL)\r
+\end{itemize}\r
+\r
+Supported video formats (shortened):\r
+\r
+\begin{tabular}{ l c c}\r
+\textbf{Format} & \textbf{Resolution and frame rate} & \textbf{Display aspect ratio }\\\r
+\r
+4K UHD & 3840x2160 60p, 50p & 16:9 \\\r
+ & 3840x2160 25p, 24p & 16:9 \\\r
+\\\r
+HD & 1920x1080 60p, 50p & 16:9 \\\r
+ & 1920x1080 25p, 24p & 16:9 \\\r
+ & 1920x1080 29.97i, 25i & 16:9 \\\r
+ & 1440x1080 29.97i, 25i & 16:9\\\r
+\\\r
+HD & 1440x1080 24p & 16:9\\\r
+ & 1280x720 59.94p, 50p 1 & 16:9 \\\r
+ & 1280x720 24p & 16:9 \\\r
+\\\r
+SD & 720x480 29.97i, 25i & 4:3 or 16:9\\\r
+\end{tabular}\r
+\r
+\chapter{How to digitize and capture analog video to digital SD video format with A/D video conversion}%\r
+\label{cha:how_to}\r
+\r
+\section{Methods and workflow}%\r
+\label{sec:methods}\r
+\r
+There are a number of ways to get analog source recorded video digitized and captured into the computer. \r
+\begin{itemize}\r
+\item One way is to use the passthrough feature of an available miniDV camcorder or the digital output of a Sony Digital 8\r
+camcorder to convert the Hi8 source to DV, which is then sent via firewire to the computer.\r
+\item Another alternative might be a Linux supported external capture card to USB3 (often MPEG-4), or find a higher-end\r
+internal PCIe analog video capture card to store uncompressed, 422 or DV video. \r
+\item A third way is to use a standalone analog to digital A/D converter and capture device. This might be to DV HDD recorder\r
+or optional to a high-end analog/SDI and a SSD 422 codec (i.e ProRes) recorder.\r
+\end{itemize}\r
+\hspace*{.9cm} An example workflow and setup for this third way:\r
+\r
+\small{Analog Hi8 \hspace*{.15cm} S-Video \hspace*{.8cm} S-Video} \\\r
+ tape player ----------> TBC --------------> A/D-conv. \\\r
+\hspace*{8cm} $\backslash$ \_ DV/HDV HDD \hspace*{.5cm} Firewire \hspace*{.5cm} PC \\\r
+\hspace*{8.3cm} \_ rec/player ------------------------> DV/M2T \\\r
+\hspace*{6.4cm} Firewire \hspace*{.1cm}/ \\\r
+\hspace*{3.5cm} HDV tape player ----------->\r
+\r
+\begin{itemize}\r
+\item A fourth, interesting way as discussed on the CinGG mailing list (yet to be tested), is to combine a HDMI-USB3 capture dongle with an Analog Video to Digital HDMI miniConverter (ADC). The analog video player output (via TBC) connects to the actual input connectors (S-video/RCA or possibly Component) of the adapter. Reference the following from/to: \\\r
+{\small \url{https://lists.cinelerra-gg.org/pipermail/cin/2021-October/003960.html}} \\\r
+{\small \url{https://lists.cinelerra-gg.org/pipermail/cin/2021-October/003970.html}}\r
+\r
+\end{itemize}\r
+\r
+{\small \texttt{S-Video Out -> A/D video converter -> HDMI/USB3 capture card}}\r
+\r
+\section{Equipment and setup}%\r
+\label{sec:equipment}\r
+\r
+\begin{itemize}\r
+\item The first required is a tape player device (VCR deck or camcorder) to playback the analog video tape cassette formats,\r
+either VHS/ SVHS, VHS-C/ SVHS-C or Video8/ Hi8. Use a video head cleaning tape before use. Wind and rewind the tape\r
+cassette before playback in Edit mode "ON" to minimize picture deterioration. \\\r
+\item A second recommended device for all capture methods is a Time Base Corrector (TBC). Connected to the analog output of\r
+a VCR, a good TBC can make wonder and remove most or all of the flagging, shaky pictures, wavy lines, and other time\r
+base problems from a videotape, to get a clearer and more steady picture. The best is a standalone, fullframe\r
+high-resolution TBC of broadcast quality; minimum is a line-based TBC built in high-end VCR decks. \\\r
+\item A third, optional feature before digitizing is a noise filter to reduce/soften noise and grain (snow) from bad VHS tape\r
+recordings, or also when video that is over-processed using sharpness controls and enhancers. Noise filter adjustment\r
+may be part of the TBC setup and preview, or fixed built in the playback VCR. Optional a standalone Video\r
+corrector/processor if available can be used, where also optional brightness, contrast and color saturation/correction\r
+can be adjusted.\r
+\end{itemize}\r
+\r
+\section{Example articles and references}%\r
+\label{sec:example}\r
+\r
+\begin{itemize}\r
+\item Digitizing Analog Video through a Digital Camcorder (Michael Steil, 2022) \\\r
+{\small \url{https://www.pagetable.com/?p=1697}} \\\r
+\item How to Get the Best Images Digitizing SD Video (TBC/ProRes, Larry Jordan, 2021) \\\r
+{\small \url{https://larryjordan.com/articles/how-to-get-the-best-images-digitizing-sd-video/}} \\\r
+\item Digitize analog cassettes (VHS or 8\ mm) with Linux (USB/H.264, Corinne HENIN, 2021) \\\r
+{\small \url{https://www.arsouyes.org/en/blog/2021/2021-05-17\_Numerisation\_VHS}} \\\r
+\item The Digitization of VHS Videotapes -- Technical Bulletin 31 -- Canada.ca (Joe Iraci, 2020) \\\r
+{\small \url{https://www.canada.ca/en/conservation-institute/services/conservation-preservation-publications/technical-bulletins/digitization-vhs-video-tapes.html}} \\\r
+\item Hi8 to DVD Workflow in Linux (Eric Olson, Renomath (2012) \\\r
+{\small \url{https://renomath.org/video/linux/hi8/}} \\\r
+\item Transfer VHS/DVD Media or Video8/Hi8 Tapes into CINELERRA-GG (chpt. 13.4 manual) \\\r
+{\small \url{https://cinelerra-gg.org/download/CinelerraGG\_Manual/Transfer\_VHS\_DVD\_Media\_or\_V.html}}\r
+\end{itemize}\r
+\r
+\chapter{\textbf{DV files converted to Blu-ray compliant MPEG-2/LPCM and authored to SD BD-Video}}%\r
+\label{cha:dv_files}\r
+\r
+\textbf{Step 1}\r
+\r
+\begin{itemize}\r
+\item Prepare a 40 GB continuously DV input file by joining and concatenating the actual dv clips in order. Each\r
+digitized Hi8 video tape was automatically split and recorded as a numbered series of 2.0 GB dv files each. \\\r
+\item Naming convention used, for example, for Tape \#1 with clips in order: \texttt{dv01, dv01-01, dv01\_02, dv01\_03},\r
+etc. For the full example at the end of this article, the concatenated \texttt{DV41\_02+DV42+DV43\_02} contains the clips from on\r
+ \texttt{dv41\_02+all dv42} up to and including \texttt{dv43\_02}.\r
+\end{itemize}\r
+\r
+\textbf{Step 2}\r
+\r
+\begin{itemize}\r
+\item Encode DV to MPEG-2 video and "re-encode" uncompressed PCM to Blu-ray PCM audio and\r
+remux to interlaced SD-BD-video.mts: \r
+\begin{lstlisting}[style=sh]\r
+ffmpeg -i DV41_02+DV42+DV43_02.dv -c:v mpeg2video -refs 1 -bf 2 -b:v 25M -maxrate 25M -minrate 25M -bufsize 28M -muxrate 28M -dc 10 -c:a pcm_bluray -mpegts_m2ts_mode 1 -flags +ilme+ildct SD-BD_DV41_02+DV42+DV43_02.mts\r
+\end{lstlisting}\r
+\end{itemize}\r
+\r
+\textbf{Step 3}\r
+\r
+\begin{itemize}\r
+\item Run \textbf{tsMuxer} (screenshot of tsMuxer usage is displayed at the end of this article). The following\r
+parameters are shown for tsMuxer\_SD\_M2TS: \\\r
+\newline\hspace*{.5cm} Input file: \texttt{SD-BD\_DV41\_02+DV42+DV43\_02.mts} \r
+\newline\hspace*{.5cm} Tracs:\hspace*{.63cm}\ MPEG-2 video stream and LPCM audio stream \r
+\newline\hspace*{.5cm} Output:\hspace*{.37cm} \texttt{SD-BD\_DV41\_02+DV42+DV43\_02.iso}\r
+\end{itemize}\r
+\r
+\textbf{Step 4}\r
+\begin{itemize}\r
+\item Burn the iso SD-BD-Video image with \textbf{xorriso} on a BD-R DL 50 GB disc:\r
+\begin{lstlisting}[style=sh]\r
+xorriso -as cdrecord -v -sao dev=/dev/sr1 SD-BD_DV41_02+DV42+DV43_02.iso\r
+\end{lstlisting}\r
+\end{itemize}\r
+\r
+\chapter{\textbf{HDV.m2t files converted and authored to HD BD-Video}}%\r
+\label{cha:hdvm2t}\r
+\r
+\textbf{Step 1}\r
+\begin{itemize}\r
+\item Prepare the source HDV.m2t file using hdv clips as for DV above.\r
+\end{itemize}\r
+\r
+\textbf{Step 2}\r
+\begin{itemize}\r
+\item Copying the mpeg2 video, re-encoding MP2 audio to Blu-ray LPCM. If using an ffmpeg version lower than 5.1,\r
+substitute ac3 for pcm\_bluray and add -b:a 384 to override lower default. \r
+\r
+\begin{lstlisting}[style=sh]\r
+ffmpeg -i HDV.m2t -c:v copy -c:a pcm_bluray -mpegts_m2ts_mode 1 HDV.mts \r
+\end{lstlisting}\r
+\end{itemize}\r
+\r
+\textbf{Step 3}\r
+\begin{itemize}\r
+\item Run \textbf{tsMuxer} (screenshot of tsMuxer usage is displayed at the end of this article). \r
+\newline\hspace*{.5cm} Input file: \texttt{HD-BD\_HDV.mts} \r
+\newline\hspace*{.5cm} Tracs: \hspace*{.5cm} MPEG-2 video stream and LPCM audio stream \r
+\newline\hspace*{.5cm} Output: \hspace*{.25cm} \texttt{HD-BD\_HDV.iso}\r
+\end{itemize}\r
+\r
+\textbf{Step 4}\r
+\begin{itemize}\r
+\item Burn the iso HD-BD-Video image with \textbf{xorriso} on a BD-R DL 50 GB disc:\r
+\begin{lstlisting}[style=sh]\r
+ xorriso -as cdrecord -v -sao dev=/dev/sr1 HD-BD_HDV.iso\r
+\end{lstlisting}\r
+\end{itemize}\r
+\r
+\chapter{\textbf{Full example output}}%\r
+\label{cha:full}\r
+\r
+\section{DV files converted to Blu-ray compliant MPEG-2 video and LPCM audio, authored to SD BD-Video and burned to a BD-R\r
+DL}%\r
+\label{sec:DVFILES}\r
+\r
+17/01-2023 \\\r
+SD-BD\_DV41\_02+DV42+DV43\_02 \\\r
+-----------------------------------------------\r
+\r
+\textbf{Step 1}\r
+\begin{lstlisting}[style=sh]\r
+cd /run/media/terje/Seagate_8TB_back/video/DV\r
+\r
+cat dv41_02.dv dv41_03.dv dv41_04.dv dv41_05.dv dv41_06.dv dv41_07.dv dv41_08.dv dv41_09.dv dv42.dv dv42_01.dv dv42_02.dv dv42_03.dv dv42_04.dv dv42_05.dv dv42_06.dv dv42_07.dv dv42_08.dv dv42_09.dv dv43.dv dv43_01.dv dv43_02.dv > /home/terje/Videoklipp/SD-BD-DV-iso/DV41_02+DV42+DV43_02.dv\r
+\end{lstlisting}\r
+\r
+--------------------------------------\r
+\begin{lstlisting}[style=sh]\r
+cd /home/terje/Videoklipp/SD-BD-DV-iso\r
+\r
+du -sh DV*\r
+40G DV41_02+DV42+DV43_02.dv\r
+\end{lstlisting}\r
+------------------------------------------------\r
+\r
+\textbf{Step 2}\r
+\begin{lstlisting}[style=sh]\r
+cd /home_lp154/terje/Videoklipp/SD-BD-DV-iso\r
+\r
+ffmpeg -i DV41_02+DV42+DV43_02.dv -c:v mpeg2video -refs 1 -bf 2 -b:v 25M -maxrate 25M -minrate 25M -bufsize 28M -muxrate 28M -dc 10 -c:a pcm_bluray -mpegts_m2ts_mode 1 -flags +ilme+ildct SD-BD_DV41_02+DV42+DV43_02.mts\r
+\r
+ffmpeg version 5.1.2 Copyright (c) 2000-2022 the FFmpeg developers\r
+ built with gcc 12 (SUSE Linux)\r
+.............................\r
+\r
+(NOTE: the @ sign represents the pound sign in the next 21 lines)\r
+\r
+Input @0, dv, from 'DV41_02+DV42+DV43_02.dv':\r
+ Metadata:\r
+ timecode : 00:19:52:24\r
+ Duration: 03:15:53.28, start: 0.000000, bitrate: 28800 kb/s\r
+ Stream @0:0: Video: dvvideo, yuv420p, 720x576 [SAR 16:15 DAR 4:3], 25000 kb/s, 25 fps, 25 tbr, 25 tbn\r
+ Stream @0:1: Audio: pcm_s16le, 48000 Hz, stereo, s16, 1536 kb/s\r
+Stream mapping:\r
+ Stream @0:0 -> @0:0 (dvvideo (native) -> mpeg2video (native))\r
+ Stream @0:1 -> @0:1 (pcm_s16le (native) -> pcm_bluray (native))\r
+Press [q] to stop, [?] for help\r
+[mpeg2video @ 0x558bb9453ac0] Warning vbv_delay will be set to 0xFFFF (=VBR) as the specified vbv buffer is too large for the given bitrate!\r
+Output @0, mpegts, to 'SD-BD_DV41_02+DV42+DV43_02.mts':\r
+ Metadata:\r
+ timecode : 00:19:52:24\r
+ encoder : Lavf59.27.100\r
+ Stream @0:0: Video: mpeg2video (Main), yuv420p(bottom coded first (swapped)), 720x576 [SAR 16:15 DAR 4:3], q=2-31,25000 kb/s, 25 fps, 90k tbn\r
+ Metadata:\r
+ encoder : Lavc59.37.100 mpeg2video\r
+ Side data:\r
+ cpb: bitrate max/min/avg: 25000000/25000000/25000000 buffer size: 28000000 vbv_delay: N/A\r
+ Stream @0:1: Audio: pcm_bluray, 48000 Hz, stereo, s16, 128 kb/s\r
+ Metadata:\r
+ encoder : Lavc59.37.100 pcm_bluray\r
+frame=293832 fps=373 q=2.5 Lsize=41027202kB time=03:15:53.28 bitrate=28595.8kbits/s speed=14.9x \r
+video:35867310kB audio:2212922kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 7.738845%\r
+\r
+--------------------------------------\r
+du -sh *.mts\r
+40G SD-BD_DV41_02+DV42+DV43_02.mts\r
+\end{lstlisting}\r
+--------------------------------------\r
+\r
+\textbf{Step 3}\r
+\begin{itemize}\r
+\item Run \textbf{tsMuxer} (screenshots of tsMuxer usage are displayed at the end of this article). \r
+\newline\hspace*{.5cm} Input file: \texttt{HD-BD\_HDV.mts} \r
+\newline\hspace*{.5cm} Tracs: \hspace*{.5cm} MPEG-2 video stream and LPCM audio stream \r
+\newline\hspace*{.5cm} Output: \hspace*{.2cm} \texttt{HD-BD\_HDV.iso}\r
+\end{itemize}\r
+\r
+-------------------------------- \r
+\begin{lstlisting}[style=sh]\r
+du -sh *.iso\r
+39G SD-BD_DV41_02+DV42+DV43_02.iso\r
+\end{lstlisting}\r
+--------------------------------------\r
+\r
+\textbf{Step 4}\r
+\begin{lstlisting}[style=sh,escapechar=\^]\r
+MediaRange BD-R DL\r
+\r
+eject /dev/sr1\r
+eject -t /dev/sr1\r
+\r
+umount /dev/sr1\r
+umount: /dev/sr1: not mounted.\r
+--------------------------------------\r
+ \r
+xorriso -devices\r
+xorriso 1.5.4 : RockRidge filesystem manipulator, libburnia project.\r
+\r
+Beginning to scan for devices ...\r
+Full drive scan done\r
+--------------------------------------\r
+0 -dev '/dev/sr0' rwrw-- : 'HL-DT-ST' 'BD-RE BH10LS30'\r
+1 -dev '/dev/sr1' rwrw-- : 'ASUS ' 'BW-16D1X-U'\r
+--------------------------------------\r
+\r
+Device og media info for a new BD-R DL (MediaRange):\r
+--------------------------------------\r
+xorrecord -dev=/dev/sr1 -atip\r
+xorriso 1.5.4 : RockRidge filesystem manipulator, libburnia project.\r
+\r
+Drive current: -outdev '/dev/sr1'\r
+Media current: BD-R sequential recording\r
+Media status : is blank\r
+Media summary: 0 sessions, 0 data blocks, 0 data, 46.6g free\r
+Device type : Removable CD-ROM\r
+Vendor_info : 'ASUS'\r
+Identifikation : 'BW-16D1X-U'\r
+Revision : 'A105'\r
+Driver flags : BURNFREE\r
+Supported modes: SAO TAO\r
+Current: BD-R sequential recording\r
+Profile: 0x0043 (BD-RE)\r
+Profile: 0x0042 (BD-R random recording)\r
+Profile: 0x0041 (BD-R sequential recording) (current)\r
+Profile: 0x0040 (BD-ROM)\r
+Profile: 0x002B (DVD+R/DL)\r
+Profile: 0x001B (DVD+R)\r
+Profile: 0x001A (DVD+RW)\r
+Profile: 0x0016 (DVD-R/DL layer jump recording)\r
+Profile: 0x0015 (DVD-R/DL sequential recording)\r
+Profile: 0x0014 (DVD-RW sequential recording)\r
+Profile: 0x0013 (DVD-RW restricted overwrite)\r
+Profile: 0x0012 (DVD-RAM)\r
+Profile: 0x0011 (DVD-R sequential recording)\r
+Profile: 0x0010 (DVD-ROM)\r
+Profile: 0x000A (CD-RW)\r
+Profile: 0x0009 (CD-R)\r
+Profile: 0x0008 (CD-ROM)\r
+Profile: 0x0002 (Removable disk)\r
+Mounted Media: 41h, BD-R sequential recording\r
+Product Id: CMCMAG/DI6/0\r
+Producer: CMC Magnetics Corporation\r
+Manufacturer: 'CMCMAG'\r
+Media type: 'DI6'\r
+-------------------------------------- \r
+\end{lstlisting}\r
+\r
+\underline{Burning the 40 GB SD-BD-Video iso image to a BD-R DL disc:}\r
+\r
+\begin{lstlisting}[style=sh]\r
+27 min\r
+\r
+xorriso -as cdrecord -v -sao dev=/dev/sr1 SD-BD_DV41_02+DV42+DV43_02.iso\r
+\r
+xorriso 1.5.4 : RockRidge filesystem manipulator, libburnia project.\r
+Drive current: -outdev '/dev/sr1'\r
+Media current: BD-R sequential recording\r
+Media status : is blank\r
+Media summary: 0 sessions, 0 data blocks, 0 data, 46.6g free\r
+Beginning to write data track.\r
+...........\r
+xorriso : UPDATE : 39219 of 39251 MB written (fifo 71%) [buf 100%] 6.1x.\r
+xorriso : UPDATE : 39245 of 39251 MB written (fifo 80%) [buf 100%] 6.1x.\r
+xorriso : UPDATE : 39251 of 39251 MB written (fifo 0%) [buf 100%] 1.5x.\r
+xorriso : UPDATE : 39251 of 39251 MB written (fifo 0%) [buf 100%] 0.0x.\r
+xorriso : UPDATE : Closing track/session. Working since 1587 seconds\r
+xorriso : UPDATE : Closing track/session. Working since 1588 seconds\r
+..........\r
+xorriso : UPDATE : Closing track/session. Working since 1627 seconds\r
+Writing to '/dev/sr1' completed successfully.\r
+\r
+xorriso : NOTE : Re-assessing -outdev '/dev/sr1'\r
+xorriso : NOTE : Disc status unsuitable for writing\r
+Drive current: -outdev '/dev/sr1'\r
+Media current: BD-ROM\r
+Media status : is written , is closed\r
+Media summary: 1 session, 20096864 data blocks, 38.3g data, 0 free\r
+\end{lstlisting}\r
+\r
+\begin{figure}[htpb]\r
+\centering\r
+\includegraphics[width=15.132cm,height=9.823cm]{Preserving.png}\r
+\end{figure}\r
--- /dev/null
+% ================================================================
+% Page 1 -- Title page definition
+%
+\thispagestyle{empty}
+%\providecommand{\HUGE}{\Huge}% if not using memoir
+\newlength{\drop}% for my convenience
+
+%% specify the Webomints family
+%\newcommand*{\wb}[1]{\fontsize{#1}{#2}\usefont{U}{webo}{xl}{n}}
+%% select a (FontSite) font by its font family ID
+\newcommand*{\FSfont}[1]{\fontencoding{T1}\fontfamily{#1}\selectfont}
+%% if you don’t have the FontSite fonts either \renewcommand*{\FSfont}[1]{}
+%% or use your own choice of family.
+%% select a (TeX Font) font by its font family ID
+\newcommand*{\TXfont}[1]{\fontencoding{T1}\fontfamily{#1}\selectfont}
+%% Generic publisher’s logo
+\newcommand*{\plogo}{\fbox{$\mathcal{PL}$}}
+
+%% Some shades
+\definecolor{Dark}{gray}{0.2}
+\definecolor{MedDark}{gray}{0.4}
+\definecolor{Medium}{gray}{0.6}
+\definecolor{Light}{gray}{0.8}
+%%%% Additional font series macros
+
+\newcommand*{\titleLL}{\begingroup% Lost Languages
+\drop=0.085\textheight
+\fboxsep0.5\baselineskip\sffamily
+\vspace*{\drop}
+\begingroup
+\centering
+\HUGE\textbf{Personal Video Archiving - Preserving Your Analog and Digital Memories}\par
+%
+\endgroup
+\vspace*{2\baselineskip}
+\vspace*{0.3\baselineskip}
+{\textcolor{Dark}{\large\textbf{%
+ Convert DV and HDV camcorder video formats to Blu-ray Video and burn it on Blu-ray disc using Linux tools. }}}\par
+%
+\centering
+\vspace{8\baselineskip}
+{\textcolor{Dark}{\large\textbf{{%
+ Author - Terje Hanssen}}}}\par
+%
+{\textcolor{Dark}{\large\today}}\par
+\endgroup}
+\titleLL % use cutom title
+\clearpage
+
+\bigskip%
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "../Preserving_camcorder_to_bluray"
+%%% End:
\newline Presets: \textit{DNxHR, ffv1, AVC\_Intra\_100}
\item[MOV] Created by Apple. It is a suitable format for editing because it organizes the files within the container into hierarchically structured \textit{atoms} described in a header. This brings simplicity and compatibility with various software and does not require continuous encoding/decoding in the timeline.
\newline Presets: \textit{DNxHR, ffv1, CineformHD, huffyuv}
- \item[PRO] Different extension, but it is still mov. Prores is proprietary and there are no official encoders except the original Adobe one. The engine used by ffmpeg is the result of reverse engineering and, according to Adobe, does not guarantee the same quality and performance of the original\protect\footnote{https://support.apple.com/en-us/HT200321}.
- \newline Presets: \textit{ProRes}
+ \item[PRO] Different extension, but it is still mov. Prores is proprietary and there are no official encoders except the original Apple one. The engine used by ffmpeg is the result of reverse engineering and, according to Apple, does not guarantee the same quality and performance of the original\protect\footnote{https://support.apple.com/en-us/HT200321}. Option \textit{vendor=apl0} is used to make it appear that the original Apple engine was used.
+ \newline Presets: \textit{ProRes; ProRes\_ks}
\item[QT] Different extension, but it is always mov.
\newline Presets: \textit{DNxHD, magicyuv, raw, utvideo}
\item[MP4] mostly used for General Purpose. It belongs to the large MPEG family.
\newline Presets: \textit{mpeg, mpeg2}
\end{description}
+\subsubsection{Note on Matroska (mkv) container}
+\label{ssub:note_mkv_container}
+\index{mkv}
+
+Matroska is a modern universal container that is Open Source so there is lots of ongoing development with community input along with excellent documentation. Also derived from this format is the \textit{Webm} container used by Google and YouTube, which use the VP8-9 and AV1 codecs. Although using in \CGG{} is highly recommended, you may have seeking problems during playback. The internal structure of matroskas is sophisticated but requires exact use of internal keyframes (I-frame; B-frame and P-frame) otherwise playback on the timeline may be subject to freeze and drop frames. The mkv format can be problematic if the source encoding is not done well by the program (for example, OBS Studio). For an easy but accurate introduction of codecs and how they work see: {\small\url{https://ottverse.com/i-p-b-frames-idr-keyframes-differences-usecases/}}.
+
+To find out the keyframe type (I, P, B) of your media you can use ffprobe:
+
+\begin{lstlisting}[numbers=none]
+ $ ffprobe -v error -hide_banner-of default=noprint_wrappers=0 -print_format flat -select_streams v:0 -show_entries frame=pict_type input.mkv
+\end{lstlisting}
+
+\textbf{-v error -hide\_banner:} serves to hide a blob of information that is useless for our purposes.
+
+\textbf{-of:} is an alias for \textit{-print\_format} and is used to be able to use \textit{default=noprint\_wrappers =0}.
+
+\textbf{-default=noprint\_wrappers=0:} is used to be able to show the information from the parsed stream that we need.
+
+\textbf{-print\_format flat:} is used to display the result of ffprobe according to a \textit{flat} format (you can choose CSV, Json, xml, etc).
+
+\textbf{-select\_streams v:0:} is used to choose the first stream (0) in case there are multiple audio and video streams (tracks, in \CGG{}).
+
+\textbf{-show\_entries:} shows the type of data collected by ffprobe that we want to display (there are also types: \texttt{\_streams}, \texttt{\_formats}, \texttt{\_packets}, and \texttt{\_frames}. They are called \textit{specifiers}).
+
+\textbf{-frame=pict\_type:} within the chosen specifier indicates the data to be displayed; in this case \textit{pict\_type}, that is, the keyframe type (I, P, B) of the frame under consideration.
+
+\textbf{input.mkv:} is the media to be analyzed (it can be any container and codec).
+
+(see {\small\url{https://ffmpeg.org/ffprobe.html}} for more details)
+
+We thus obtain a list of all frames in the analyzed media and their type. For example:
+
+\begin{lstlisting}[numbers=none]
+ frames.frame.0.pict_type="I"
+ frames.frame.1.pict_type="P"
+ frames.frame.2.pict_type="B"
+ frames.frame.3.pict_type="B"
+ frames.frame.4.pict_type="B"
+ ...
+\end{lstlisting}
+
+There are also 2 useful scripts that not only show the keyframe type but also show the GOP length of the media. They are zipped tars with readme's at: \newline
+{\small\url{https://cinelerra-gg.org/download/testing/getgop_byDanDennedy.tar.gz}} \newline
+{\small\url{https://cinelerra-gg.org/download/testing/iframe-probe_byUseSparingly.tar.gz}}
+
+We can now look at the timeline of \CGG{} to see the frames that give problems in playback. Using a codec of type Long GOP, it is probably the rare I-frames that give the freezes.
+To find a solution you can use MKVToolNix ({\small\url{https://mkvtoolnix.download/}}) to correct and insert new keyframes into the mkv file (matroska talks about \textit{cues data}). It can be done even without new encoding. Or you can use the \texttt{Transcode} tool within \CGG{} because during transcoding new keyframes are created that should correct errors.
+
\subsubsection{Image Sequences}
\label{ssub:ffmpeg_image_sequences}
-The image sequences can be uncompressed, with lossy or lossless compression but always Intraframe. They are suitable for post-processing that is compositing (VFX) and color correction.
+The image sequences can be uncompressed, with lossy or lossless compression but always Intraframe. They are suitable for post-processing that is compositing (VFX) and color correction. Note: even if \CGG{} outputs fp32, exr/tiff values there are normalized to 0-1.0f.
\begin{description}
\item[DPX] Film standard; uncompressed; high quality. \textit{Log} type.
\newline Presets: \textit{s16le, s24le, s32le}
\item[MKA] Open, highly configurable and documented. It belongs to the Matroska family. Uncompressed pcm type.
\newline Presets: \textit{s16le, s24le, s32le}
+ \item[ALAC] Apple's codec, free to use but not open source. It is lossless and of high quality but is slower than other similar codecs.
+ \newline Presets: \textit{m4a, mkv, qt}
\end{description}
\subsubsection{General Purpose}
\subsubsection{Image Sequences}
\label{sub:internal_image_sequences}
-There are quite a few formats available.
+There are quite a few formats available. Note: even if \CGG{} outputs fp32, exr/tiff values there are normalized to 0-1.0f.
\begin{description}
\item[EXR Sequence] OpenEXR (Open Standard) is a competing film standard to DPX, but \textit{Linear} type.
\item[MPEG Audio] Very widespread standard. Extension \texttt{.mp3}.
\newline Presets: \textit{mp3}
\end{description}
+
+\section{Overview on Color Management}%
+\label{sec:overview_color_management}
+\index{color!management}
+
+\CGG{} does not have support for ICC color profiles or global color management to standardize and facilitate the management of the various files with which it works. But it has its own way of managing color spaces and conversions; let's see how.
+
+\subsection{Color Space}%
+\label{sub:the_color_spaces}
+
+A color space is a subspace of the absolute CIE XYZ color space that includes all possible, human-visible color coordinates (therefore makes human visual perception mathematically tractable). CIE XYZ is based on the RGB color model and consists of an infinite three-dimensional space but characterized (and limited) by the xyz coordinates of five particular points: the Black Point (pure black); the White Point (pure white); Reddest red color (pure red); Greenest green color (pure green); and Bluest blue color (pure blue). All these coordinates define an XYZ matrix. The color spaces are submatrices (minors) of the XYZ matrix. The absolute color space is device independent while the color subspaces are mapped to each individual device. For a more detailed introduction see: \small\href{https://peteroupc.github.io/colorgen.html}{https://peteroupc.github.io/colorgen.html}
+\normalsize A color space consists of primaries (\textit{gamut}), transfer function (\textit{gamma}), and matrix coefficients (\textit{scaler}).
+
+\begin{description}
+ \item[Color primaries]: the gamut of the color space associated with the media, sensor, or device (display, for example).
+ \item[Transfer characteristic function]: converts linear values to non-linear values (e.g. logarithmic). It is also called Gamma correction.
+ \item[Color matrix function] (scaler): converts from one color model to another. $RGB \leftrightarrow YUV$; $RGB \leftrightarrow Y'CbCr$; etc.
+\end{description}
+
+The camera sensors are always RGB and linear. Generally, those values get converted to YUV in the files that are produced, because it is a more efficient format thanks to chroma subsampling, and produces smaller files (even if of lower quality, i.e. you lose part of the colors data). The conversion is nonlinear and so it concerns the "transfer characteristic" or gamma. The encoder gets input YUV and compresses that. It stores the transfer function as metadata if provided.
+
+\subsection{CMS}%
+\label{sub:cms}
+
+A color management system (CMS) describes how it translates the colors of images/videos from their current color space to the color space of the other devices, i.e. monitors. The basic problem is to be able to display the same colors in every device we use for editing and every device on which our work will be viewed. Calibrating and keeping our hardware under control is feasible, but when viewed on the internet or DVD, etc. it will be impossible to maintain the same colors. The most we can hope for is that
+there are not too many or too bad alterations. But if the basis that we have set up is consistent, the alterations should be acceptable because they do not result from the sum of more issues at each step. There are two types of color management: \textit{Display referred} (DRC) and \textit{Scene referred} (SRC).
+
+\begin{itemize}
+ \item \textbf{DRC} is based on having a calibrated monitor. What it displays is considered correct and becomes the basis of our color grading. The goal is that the colors of the final render will not change too much when displayed in other hardware/contexts. Be careful to make sure there is a color profile for each type of color space you choose for your monitor. If the work is to be viewed on the internet, be sure to set the monitor in \textit{sRGB} with its color profile. If for HDTV we have to set the monitor in \textit{rec.709} with its color profile; for 4k in \textit{Rec 2020}; for Cinema in \textit{DCP-P3}; etc.
+ \item \textbf{SRC} instead uses three steps:
+ \begin{enumerate}
+ \item The input color space: whatever it is, it can be converted manually or automatically to a color space of your choice.
+ \item The color space of the timeline: we can choose and set the color space on which to work.
+ \item The color space of the output: we can choose the color space of the output (on other monitors or of the final rendering).
+ \end{enumerate}
+ \textit{ACES} and \textit{OpenColorIO} have an SRC workflow. Please note that the monitor must still be calibrated to avoid unwanted color shifts.
+ \item There is also a third type of CMS: the one through the \textbf{LUTs}. In practice, the SRC workflow is followed through the appropriate 3D LUTs, instead of relying on the internal (automatic) management of the program. The LUT combined with the camera used to display it correctly in the timeline and the LUT for the final output. Using LUTs, however, always involves preparation, selection of the appropriate LUT and post-correction. Also, as they are fixed conversion tables, they can always result in clipping and banding.
+\end{itemize}
+
+\subsection{Display}%
+\label{sub:display}
+
+Not having \CGG{} a CMS, it becomes essential to have a monitor calibrated and set in sRGB that is just the output displayed on the timeline of the program. You have these cases:
+
+\begin{center}
+ \begin{tabular}{|l|l|p{8cm}|}
+ \hline
+ \textbf{Timeline} & \textbf{Display} & \textbf{Description} \\
+ \hline
+ sRGB & sRGB & we get a correct color reproduction \\
+ sRGB & Rec.709 & we get slightly dark colors, because gamma \\
+ sRGB & DCI-P3 & we get over-saturated dark colors, because gamma and bigger gamut \\
+ \hline
+ \end{tabular}
+\end{center}
+
+\subsection{Pipeline CMS}%
+\label{sub:pipeline_cms}
+
+INPUT $\rightarrow$ DECODING/PROCESSING $\rightarrow$ OUTPUT/PLAYBACK $\rightarrow$ DISPLAY $\rightarrow$ ENCODING
+
+\begin{description}
+ \item[Input] color space and color depth of the source file; better if combined with an ICC profile.
+ \item[Decoding] how \CGG{} transforms and uses the input file (it is a temporary transformation, for usage of the internal/ffmpeg engine and plugins).
+ \item[Output] our setting of the project for the output. In \CGG{} such a signal is \texttt{8-bit sRGB}, but it can also be 8-bit YUV in \textit{continuous playback}.
+ \item[Display] as the monitor equipped with its color space (and profiled with ICC or LUT) displays the signal that reaches the user and what we see. The signal reaching the display is also mediated by the graphics card and the operating system CMS, if any.
+ \item[Encoding] the final rendering stage where we set not only formats and codecs but also color space, color depth, and color range.
+\end{description}
+
+\subsection{How \CGG{} works}%
+\label{sub:how_cingg_works}
+
+\begin{description}
+ \item[Decoding/playback:] Video is decoded to internal representation (look at \texttt{Settings /Format/Color model}). Internal format is unpacked as 3 color values + one alpha value every pixel. \CGG{} has 6 internal pixel formats (RGB(A) 8-bit; YUV(A) 8-bit and RGB(A)\_FLOAT 32-bit (see Color Model in \nameref{sec:video_attributes}). The program will configure the frame buffer for your resulting video to be able to hold data in that color model. Then, for each plugin, it will pick the variant of the algorithm coded for that model.
+ \CGG{} automatically converts the source file to the set color model (in a buffer, the original is not touched!). Even if the input color model matches what we set in \texttt{Settings/Format/Color model}, there will always be a first conversion because \CGG{} works internally (in the buffer) at 32-bit in RGB. For playback \CGG{} has to convert each frame to the format acceptable by the output device, i.e. sRGB 8-bit. In practice, the decoded file follows two separate paths: conversion to FLOAT for all internal calculations in the temporary (including other conversions for plugins, etc.) and simultaneously the result in the temporary is converted to 8-bit sRGB for on-screen display. See also \nameref{sec:conform_the_project}. To review, a \textit{temporary} is a single frame of
+video in memory where graphics processing takes place.
+\CGG{} use X11 and X11 is RGB only and it is used to draw the \textit{refresh frame}. So single step is always drawn in RGB. Continuous playback on the other hand can also be YUV for efficiency reasons.
+ \item[Color range:] One problem with the YUV color model is the \texttt{YUV color range}. This can create a visible effect of a switch in color in the Compositor, usually shown as grayish versus over-bright. The cause of the issue is that X11 is RGB only and it is used to draw the \textit{refresh frame}. So single step is always drawn in RGB. To make a YUV frame into RGB, a color model transfer function is used. The math equations are based on Color\_space and Color\_range. In this case, color\_range is the cause of the \textit{grayish} offset. The \textit{YUV MPEG color range} (limited or TV) is 16..235 for \textbf{Y}, 16..240 for \textbf{UV}, and the color range used by \textit{YUV JPEG color range} (full or HDTV) is 0 to 255. The cause is that 16-16-16 is seen as pure black in MPEG, but as gray in JPEG and all playback will come out brighter and more grayish. This can be fixed by forcing appropriate conversions via the ColorSpace plugin. See \nameref{sec:color_space_range_playback}
+ \item[Plugins:] On the timeline all plugins see the frames only in internal pixel format and modify this as needed (\textit{temporary}). Some effects work differently depending on colorspace: sometimes pixel values are converted to float, sometimes to 8-bit for an effect. In addition \textit{playback single step} and \textit{plugins} cause the render to be in the session color model, while \textit{continuous playback} with no plugins tries to use the file’s best color model for the display (for speed). As mentioned, each plugin we add converts and uses the color information in its own way. Some limit the gamut and depth of color by clipping (i.e. \texttt{Histogram}); others convert and reconvert color spaces for their convenience; others introduce artifacts and posterization; etc. For example, the \texttt{Chroma Key (HSV)} plugin converts any signal to HSV for its operation.
+ If we want to better control and target this color management in \CGG{}, we can take advantage of its internal ffmpeg engine: there is an optional feature that can be used via \texttt{.opts} lines from the ffmpeg decoded files. This is via the \texttt{video\_filter=colormatrix=...}ffmpeg plugin. There may be other good plugins (lut3d...) that can also accomplish a desired color transform. This \texttt{.opts} feature affects the file colorspace on a file by file basis, although in principle it should be possible to setup a \texttt{histogram} plugin or any of the \texttt{F\_lut*} plugins to remap the colortable, either by table or interpolation.
+ \item[Conversion:] Any conversion is done with approximate mathematical calculations and always involves a loss of data, more or less visible, because you always have to interpolate an exact value when mapping it into the other color space. Obviously, when we use floating point numbers to represent values, these losses become small and close to negligible. So the choice comes down to either keeping the source color model even while processing or else converting to FLOAT, which in addition to leading to fewer errors should also minimize the number of conversions, being congruous with the program's internal one. The use of FLOAT, however, takes more system resources than the streamlined YUV. Color conversions are mathematical operations; for example to make a YUV frame into RGB, a color model matrix function is used. The math equations are based on color\_space and color\_range. Since the majority of sources are YUV, this conversion is very common and it is important to set these parameters to optimize playback speed and correct color representation.
+ \item[Encoding:] Finally, the encoding converts to colorspace required by the codec.
+\end{description}
+
+\subsection{Workflow}%
+\label{sub:workflow}
+
+Let us give an example of color workflow in \CGG{}. We start with a source of type YUV (probably: YCbCr); this is decoded and converted to the chosen color model for the project, resulting in a \textit{temporary}. Various jobs and conversions are done in FLOAT math and the result remains in the chosen color model until further action. In addition, the temporary is always converted to sRGB 8-bit for monitor display only. If we apply the \texttt{ChromaKey (HSV)} plugin, the temporary is converted to HSV (in FLOAT math) and the result in the temporary becomes HSV. If we do other jobs the temporary is again converted to the set color model (or others if there is demand) to perform the other actions. At the end of all jobs, the obtained temporary will be the basis of the rendering that will be implemented according to the choice of codecs in the render window (\textit{Wrench}), regardless of the color model set in the project. If we have worked well the final temporary will retain as much of the source color data as possible and will be a good basis for encoding of whatever type it is.
+
+For practical guidelines, one can imagine starting with a quality file, for example, \textit{10-bit YUV 4.2.2}. You set the project to \texttt{RGBA-FLOAT}; the \texttt{YUV color space} to your choice of Rec709 (for a FullHD) or BT 2020NCL (for UHD) and finally the \texttt{YUV color range} to JPEG. If the original file has the MPEG type color range then you convert to JPEG with the \texttt{ColorSpace} plugin. If you want to transcode to a quality intermediate you can use \textit{DNxHR 422}, or even \textit{444}, and maybe do the editing step with a \textit{proxy}. For rendering you choose the codec appropriate for the file destination, but you can still generate a high-quality master, for example \textit{ffv1 .mov} with lossless compression.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=1.0\linewidth]{color_01.png}
+ \caption{Color settings (Settings $\rightarrow$ Format / Settings $\rightarrow$ Preferences)}
+ \label{fig:color_01}
+\end{figure}
You can find the files to test the workflow that is described next at the following address:
%begin{latexonly}
-\small{\url{https://cinelerra-gg.org/download/testing/cinelerra-forum.zip}}
+\url{https://cinelerra-gg.org/download/testing/cinelerra-Manual-reference.zip}
%end{latexonly}
\begin{htmlonly}
\url{https://cinelerra-gg.org/download/testing/cinelerra-forum.zip}
\item In the align mixer dialog select first \textit{adjust}. Wait for the program do its work. You can see the progress bar at the bottom right of the main window.
\item Check the correctness of the alignment from column \textit{R}; the values of the various tracks must be close to 1. Then click on the \textit{apply} button. The tracks will move to the right and align.
\item In the main timeline in the audio 9 track, click on the \textit{Play Track} button that is beside the \textit{Arm track} button to enable it (if it is not already). Then enable audio and you can hear the audio while editing.
- \item Position the windows mixers in a position you are comfortable with and next in the main window move the cursor to the beginning of the timeline. We can also resize the Mixers windows to your liking.
+ \item Position the windows mixers in a position you are comfortable with and next in the main window move the cursor to the beginning of the timeline. You can also resize the Mixers windows to your liking.
\item Click on play (space bar) and stop when you want to insert the portion of the track you want in the main track. You do this by double clicking in the mixer.
\item Go on starting, stopping and double clicking to insert new portions of the clips in the main track.
\item When you finish, arm only the main video track and your main audio 9 track.
\paragraph{Note:} If our files have Jam-syncing timecodes, we can speed up the workflow (steps 4 - 15) with the simple command : \texttt{Tracks $\rightarrow$ Align Timecodes}.
More info can be found in \nameref{sub:align_timecodes}.
+
+\section{Workflow with Keyframes and Plugins}%
+\label{sec:workflow_keyframes_plugins}
+
+One of the most powerful functions of \CGG{} is the use of keyframes, which can be managed and applied for virtually anything you can do in the timeline, for example using them with plugins. See \nameref{cha:Keyframes} for their in-depth description. Since they can be used in many ways, including very sophisticated ones, we present a workflow that can serve as an approach to the basic operation of keyframes applied to plugins\protect\footnote{credit to DeJay.}.
+
+Effects keyframing only works on the effect you are using, they are independently set for each effect you have added.
+
+\begin{enumerate}
+ \item Put a multi-edits movie segment on the timeline, hit the \texttt{Ctrl-End} keys to get to the end and drag the effect(s) on to the whole timeline from the Resources window, then hit the \texttt{Ctrl-Home} keys to go to the beginning.
+ \item Enable keyframes autos button (\texttt{Generate keyframes while tweeking}) or hit \texttt{"j"}, make an adjustment to the effect and a keyframe will be generated automatically.
+ \item Move the cursor until it becomes an arrow at the junction with the next clip and left click to put the play cursor there.
+ \item Backspace one frame to the end of the first clip (hit \texttt{"4"} or \texttt{Alt-u} or click the \texttt{left frame reverse} transport button).
+ \item Adjust one parameter minutely and return it to its setting, one click on the mouse wheel rotation in each direction will do it, to set another keyframe which will hold the settings for the length of the clip. If you don't the settings will change as you adjust to set the next keyframe.
+ \item Go forward to the first frame of the next clip, reset the effect to set another keyframe, make any necessary adjustments.
+ \item Repeat as for the first clip and do that all the way down the segment. Remember to disable keyframes afterwards or you might inadvertently change settings while continuing to work.
+\end{enumerate}
+
+It is always best to use the File pulldown and the option \textit{Save As} after each operation e.g. Color Correction using (for instance) \texttt{Histogram}, \texttt{Saturation} and \texttt{Unsharp} plugins, then there is a point to return to if the next operation fails, or you want to make changes.
+
+The final result is to have the first clip with a given plugin setting; the next edit with other settings; and so on throughout the timeline. The advantage is that you have only used the plugin once instead of adding a plugin to each edit.
+
+It is preferable to put all the effects on the whole timeline and adjust them for each clip together, so you can see the overall result before moving on to the next clip. Effects are read from the top to the bottom of the stack and it is usually necessary to disable the effects lower down the stack while making adjustments. Using the example of Histogram, Saturation and Sharpen, disable Saturation and Sharpen while adjusting Histogram, or the Videoscope readings will be incorrect and so will the resulting settings, then enable Saturation and adjust that before moving to the next clip. Usually Sharpen is used as a \textit{track effect}, meaning you don't keyframe it for each clip, keeping it disabled until the rest is complete.
+
+\section{Create a frame for a PiP}%
+\label{sec:create_frame_pip}
+
+In \CGG{} it is quick and easy to create \textit{Picture-in-Picture} (PiP) using the Camera and Projector tools. You can read about how to use these at \nameref{sub:camera_and_projector}.
+
+PiPs created with Camera and Projector, however, do not have a frame. You can add it with the \textit{Sketcher} plugin that allows for drawing on the canvas of the Compositor window. Such a frame remains fixed in the position where it was created and can only be moved manually, with a movement that must be in accordance with the movement of the PiP. Unfortunately, this is very complicated and imprecise work.
+A convenient workaround is to use the \textit{Sketcher} plugin together with the \textit{Crop\&Position} plugin. Here is a description of how to do this.
+
+Consider an example of a main video (\texttt{bbb\_sunflower\_1080p\_30fps\_ normal.mp4}) and a still image example (\texttt{Rodents.png}). You want to insert a crop of the image surrounded by a colored frame inside the video. Later you can move the PiP with its frame by using keyframes.
+
+\begin{enumerate}
+ \item First, create a project with 3 video tracks. From top to bottom name them: \texttt{V3\_Frame 4Picture}, \texttt{V2\_Picture}, \texttt{V1\_Video}.
+ \item In V1\_Video put the video file. In V2\_Picture put the image (extending it to the length of the video by simply dragging the right edge) - or you can put another video instead of a still image. The V3\_Frame4Picture track is left empty.
+ \item In V2\_Picture, if needed put the \textit{Scale} plugin, and then 2 separate \textit{Crop\&Position} plugins. The \textit{Scale} plugin may be needed to scale the image - maybe to use it with the Camera tool, however it is not needed for the creation of the frame and PiP. Depending on its use, you can put it in the first or second position in the plugin stack. The first \textit{Crop\&Position} plugin (the topmost one, which is processed first in \textit{Temporary} and whose output becomes the input to the next plugin) will be used only to make the desired crop for our image (Crop Only). The second \textit{Crop\&Position} plugin will be used to place the PiP in the desired position (Position Only).
+ \item In V3\_Frame4Picture, select the length of the video track and apply the \textit{Sketcher} plugin. Either highlight the region in which to apply the plugin or assign \textit{In/Out Points}, because you can not add plugins to an empty track. Now add the \textit{Shared Effects} of the \textit{Crop\&Position} plugin, taking care to choose the second plugin (Position Only) which is further down the stack (for shared effects see: \nameref{sec:shared_effect_tracks}).
+\end{enumerate}
+
+This is what the timeline should look like:
+
+\begin{lstlisting}[numbers=none]
+ - V3_Frame4Picture
+ -> Sketcher
+ -> Shared V2_Picture:Crop&Position (Position ONLY)
+ - V2_Picture
+ -> Rodents.png
+ -> Crop&Position (Crop ONLY)
+ -> Scale
+ -> Crop&Position (Position ONLY)
+ - V1_Video
+ -> bbb_sunflower_1080p_30fps_normal.mp4
+\end{lstlisting}
+
+
+as you can see in figure~\ref{fig:Frame_on_PiP}.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=1.0\linewidth]{Frame_on_PiP.png}
+ \caption{Setting effects}
+ \label{fig:Frame_on_PiP}
+\end{figure}
+
+All that remains is to create the frame on the image that has already been cropped to the desired size. Drawing the frame with the \textit{Sketcher} plugin is not difficult but requires precision. You can draw the 4 corner points imprecisely (\texttt{Shift + LMB}) and then arrange the created points by dragging them to exactly the right coordinates (\texttt{Ctrl+LMB}), or you can impose the coordinates on the 4 corner points by entering the exact numbers in the \texttt{X} and \texttt{Y Input} windows. You can also adjust the thickness of the frame and the color (see \nameref{sub:Sketcher}).
+
+If you want to move the PiP to another position you have to go back to \textit{Crop\&Position} (Position Only) and change the coordinates. Now you can see that the frame also moves along with the image thanks to the Shared effect present in the V3\_Frame4Picture track, which returns the same coordinates to the \textit{Sketcher} plugin.
+
+Finally, you can animate the position of the PiP as well as the thickness and color of the frame throughout the video using the keyframes (see \nameref{cha:keyframes}).
+
+\section{Using Screen Capture on slower CPUs}%
+\label{sec:using_screencapture}
+
+Some results with different settings when working on slower CPUs follow:
+\begin{itemize}
+\item You can enable "loopback mode" in alsamixer, set xmms (with ALSA output) to play
+(any alsa-enabled app should work), and then you can record both video and audio. If
+your motherboard has no loopback switch for its integrated audio, you can use a
+specialized .asoundrc file set up as an alsa loopback instead -- reference
+{\small \url{https://bbs.archlinux.org/viewtopic.php?id=147852}} for usage.
+\item If you leave recording settings to their default value of input frequency = 48000, you
+may get strange one-core cpu overload in kernel space. This will show up in the color
+orange if using the system monitor software, gkrellm (GNU Krell Monitors). So you most
+likley will want to set the input frequency to 44100 and then everything should work
+smoothly.
+\item Attempting to record 1440*900*24bit*30fps with cpu (AMD FX 430) set to its lowest
+frequency of 1.4Ghz, usually results in video being shorter than audio, so try slowing
+video down to different values, such as 0.68 or so via speed curve, and then just clip
+the few last silent frames.
+\item If you set the CPU up for performance and if you can rev it up to 4Ghz, then audio and
+video tend to be much more aligned in terms of their length. In one particular case with
+generally good results, the codec was mjpeg444 / s16le into a mov container on tmpfs.
+\item Specifically for screencapture on slow CPU, running short pre-session capture will be
+useful to see if you can get same length tracks with given resolution/fps/codec. And if
+not, either drop down recording fps or try to speed up encoder settings.
+\item In trying other positioning methods, apart from software timings, such as check/uncheck
+add/drop frames checkboxes and setting different number of audio samples ... , there seems
+to be no algorithm/code to intellectually duplicate frames that are too late in their
+encoding. And setting buffered frames in the device to absurdly high value like 50, was
+also not working for screencapture driver and short recordings like 20-25 seconds long.
+In conclusion, no amount of buffering will save you if you are chronically late.
+\end{itemize}
\vspace{2ex}
\begin{tabular}{lll}
+ \hline
Path: & output media file path & \\
Start time: & weekday/time of day & to begin capture\\
\multirow{2}*{Mode:} & timed & use start time/duration \\
- & untimed & use transport controls\\
+ & untimed & use transport controls\\
+ \hline
\end{tabular}
\vspace{2ex}
\label{sec:record_web_media_rt}
\index{recording!web media in real time}
-Below describes the necessary steps for recording freely available media from the internet for your own personal use. You have to be on a system using pulseaudio, such as ubuntu, fedora, centos.
+Below describes the necessary steps for recording freely available media from the internet for your own personal use. You have to be on a system using pulseaudio, such as ubuntu, fedora, or centos.
\begin{enumerate}
\item Start \CGG{} and select \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Recording} From a terminal (with a wide text window) run: \texttt{pactl list}. You will see all of the audio sources and sinks on your system. Identify the source associated with the normal output your system uses. Example: \textit{Source $\#1$}. Locate the source which monitors your normal audio output. For example: \textit{front stereo}.
\paragraph{Transport controls} these control buttons mimic the functions of tape recorders from the old days.
\begin{itemize}
- \item \textit{Reverse button/left arrow} --remnant from the past; does the same as the Start button really.
- \item \textit{Red round button} --this is the Start button to start recording.
- \item \textit{White square} --this is the Stop button to stop recording.
- \item \textit{Red round button with white line} --start recording in single frame mode. The way this works is to just \textit{take a picture now, take a picture now\dots} The reason to use this mode is to get a still shot like you would with a camera. Sometimes input is continuous, for example looking at stars with a telescope -- surveillance goes on for hours, but you just want to take a picture now when something of significance interest comes up
+ \item \textit{Reverse button/left arrow} -- remnant from the past; does the same as the Start button really.
+ \item \textit{Red round button} -- this is the Start button to start recording.
+ \item \textit{White square} -- this is the Stop button to stop recording.
+ \item \textit{Red round button with white line} -- start recording in single frame mode. The way this works is to just \textit{take a picture now, take a picture now\dots} The reason to use this mode is to get a still shot like you would with a camera. Sometimes input is continuous, for example looking at stars with a telescope -- surveillance goes on for hours, but you just want to take a picture now when something of significance interest comes up
\end{itemize}
\paragraph{Cron} The batch recording watcher, cron, is either \textit{Idle} or \textit{Active}. When you start or stop batch recording at specific times, there is a cron thread watching timers to perform the timed action. Idle/Active indicates whether the timers are running.
\paragraph{Position} this is a timebase which tracks frames/samples when obeying frame/sample rate. When a recording starts, it resets to 0. Timing is against audio (when available). Audio time and video time are based on position.
\noindent Possible choices for time base are:
\begin{itemize}
- \item \textit{Presentation Timestamps} --use time code which is in both the audio and video media input stream. Uses these timestamps to sync the 2 streams.
- \item \textit{Device Position} --this is the device hardware position of where you are. It is usually only on the audio side.
- \item \textit{Sample Position} --Sample $\#$ or frame $\#$ divided by frame rate tells you where you are.
- \item \textit{Software Timing} --usually used for things like YouTube; it just will \textit{take a picture now} \dots \textit{take a picture now} \dots over and over again until you tell it to stop.
+ \item \textit{Presentation Timestamps} -- use time code which is in both the audio and video media input stream. Uses these timestamps to sync the 2 streams.
+ \item \textit{Device Position} -- this is the device hardware position of where you are. It is usually only on the audio side.
+ \item \textit{Sample Position} -- Sample $\#$ or frame $\#$ divided by frame rate tells you where you are.
+ \item \textit{Software Timing} -- usually used for things like YouTube; it just will \textit{take a picture now} \dots \textit{take a picture now} \dots over and over again until you tell it to stop.
\end{itemize}
Positioning \& Timing needs more detailed explanation for complete understanding and application. The overall goal is to maintain media stream timeline synchronization. The reason for providing different \textit{Positioning} options is that different input media may have different timebase standards. Additionally, the input may be damaged. Damaged data can skew the timeline during presentation. The timebase standards make it possible to correctly resynchronize the media presentation to the original time position. For example, the transport layer may have timestamps provided in it. These timestamps record \textit{audio time} and \textit{video time} and are called \textit{presentation timestamps}.
\label{fig:recording02}
\end{figure}
+Some notes for usage on slower CPUs are outlined at appendix \nameref{sec:using_screencapture}
+as discovered in actual usage.
+
\section{Digital Video Broadcasting (DVB)}%
\label{sec:digital_video_broadcasting}
\index{capture!digital broadcasting}
Remote Control Keys (Application/Menu key toggle for ati-x10 remote)
% Should find something so that the last column width automatically adapts to margin/font/pagesize.
-\begin{tabular}{lc p{12cm}}
- \toprule
+\begin{tabular}{lcp{12cm}}
+ \hline
up arrow&=&forward 1 minute\\
down arrow&=&forward single frame\\
book key&=&toggles channel scan (always available)\\
hand key&=&terminates \CGG{} (always available)\\
- \bottomrule
+ \hline
\end{tabular}
\noindent Plus usual Transport keys:
\begin{tabular}{lcl}
- \toprule
+ \hline
e&=&??\\
f&=&toggle full screen\\
square&=&stop\\
2 lines&=&fast reverse\\
- \bottomrule
+ \hline
\end{tabular}
The Application/Menu key \quad
[ 4007.420828] hid-generic 0003:534D:0021.0009: hiddev97,hidraw0: USB HID v1.10 Device [MACROSILICON AV TO USB2.0] on usb-0000:16:00.3-1.2/input4
\end{lstlisting}
-\newpage
-
\subsection{Use Case \#2 – Hauppauge WinTV-HVR}
\label{sub:use_case_wintv}
\index{capture!Hauppage WinTV}
region is highlighted, everything after the insertion point is
rendered. By positioning the insertion point at the beginning of a
track and unsetting all in/out points, the entire track is rendered.
-But you also have the choice to render \textit{one frame}.
+But you also have the choice to render \textit{one frame}. Reminder,
+\CGG{} does not do remuxing without rendering - see \nameref{sec:transcode}.
\section{Single File Rendering}%
\label{sec:single_file_rendering}
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.
\begin{center}
- \begin{tabular}{l p{8cm}}
+ \begin{tabular}{lp{8cm}}
+ \hline
sd.youtube & Standard Definition use with default audio/Opus stereo.youtube \\
hd.youtube & High Definition “ “ \\
uhd.youtube & Ultra High Definition “ “ \\
+ \hline
\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 .mp4 instead of .youtube before uploading.
\begin{center}
- \begin{tabular}{l p{8cm}}
+ \begin{tabular}{lp{8cm}}
+ \hline
sd\_h264.youtube & Standard Definition – must change to audio stereo\_with\_h264.youtube \\
hd\_h264.youtube & High Definition - “ “ \\
uhd\_u264.youtube & Ultra High Definition - “ “ \\
+ \hline
\end{tabular}
\end{center}
\textit{mode:}
-\begin{tabular}{p{6cm} p{10cm}}
+\begin{tabular}{p{6cm}p{10cm}}
+ \hline
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\\
+ \hline
\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}}}
+ \begin{tabular}{p{4cm}p{10cm}}
+ \hline
-b:v <arg> & Sets target bitrate (e.g. 500k)\\
-minrate <arg> & Sets minimum bitrate.\\
-maxrate <arg> & Sets maximum bitrate.\\
-crf <arg> & sets maximum quality level. Valid values are 0-63, lower numbers are higher quality.\\
+ \hline
\end{tabular}
\end{center}
sets the point where background rendering starts up to the position
of the insertion point. If any video exists, a red bar appears in
the time ruler showing what has been background rendered
-(figure~\ref{fig:back-ren02}).
+(figure~\ref{fig:back-ren02}). Because this creates a very large number
+of files, a Shell Command script is available to delete them if in the
+default location.
\begin{figure}[htpb] \centering
\includegraphics[width=1.0\linewidth]{back-ren02.png}
created, ls commands will not work in the background rendering
directory. The browse button for this option normally will not work
either, but the configuration button for this option works. The
- default value will be /tmp/brender .
+ default value will be /tmp/brender . Because using background
+ rendering creates a voluminous number of brender numbered files,
+ a Shell Command script is available to delete them if they are
+ in the default /tmp/brender format.
\item[File format] The file format for background rendering has to
be a sequence of images. The format of the image sequences
determines the quality and speed of playback. JPEG generally works
can use privileged ports) or $10650...$ for non-root and click on \textit{Add Nodes}. To find a range of free ports to use you can look at the file \texttt{/etc/services};
\item you will see something like the following in the Nodes
listbox to the right:\newline
- \begin{tabular}{lllc} On & Hostname & Port & Framerate
- \\\midrule
- X & 192.168.1.12 & 10650 & 0.0 \\
- X & 192.168.1.12 & 10651 & 0.0 \\
- X & 192.168.1.12 & 10652 & 0.0 \\
- X & 192.168.1.12 & 10653 & 0.0 \\
- X & 192.168.1.12 & 10654 & 0.0 \\
- X & localhost & 10655 & 0.0 \\
- X & localhost & 10656 & 0.0 \\
+ \begin{tabular}{lllc}
+ \hline
+ On & Hostname & Port & Framerate\\
+ \hline
+ X & 192.168.1.12 & 10650 & 0.0 \\
+ X & 192.168.1.12 & 10651 & 0.0 \\
+ X & 192.168.1.12 & 10652 & 0.0 \\
+ X & 192.168.1.12 & 10653 & 0.0 \\
+ X & 192.168.1.12 & 10654 & 0.0 \\
+ X & localhost & 10655 & 0.0 \\
+ X & localhost & 10656 & 0.0 \\
+ \hline
\end{tabular}
\item set the Total number of jobs to create. This number only pertains to client nodes, so we do not need to consider the master node;
\item click OK on the bottom of the Preferences window.
\end{longtable}
-\section{Compositor window}%
+\section{Compositor window shortcuts}%
\label{sec:compositor_window_shortcuts}
\index{shortcuts!compositor window}
\end{longtable}
-\section{Viewer window }%
+\section{Viewer window shortcuts }%
\label{sec:viewer_window_shortcuts}
\index{shortcuts!viewer window}
\bottomrule
\end{longtable}
+\section{Alternative Shortcuts }%
+\label{sec:alternative_shortcuts}
+\index{shortcuts!alternative}
+
+The alternative shortcuts are changed from \CGGI{} default to what most other NLEs use as standard.
+For example:
+
+\texttt{J, K, L} (Play Normal Reverse, Stop, Play Normal Forward) and when pressed twice J and L will Play Fast and then if playing fast and pressed again, will go back to playing normal.
+
+\texttt{I, O} (set/unset InPoint, set/unset OutPoint)
+
+\texttt{A, S} (Jump backward next cut, Jump forward next cut)
+
+To use these alternative shortcuts you must use the appimage found \href{https://cinelerra-gg.org/download/images/CinGG-20230930-alternative_shortcuts.AppImage}{here} -- you may want to go up 1 directory level to get a more recent dated version -- or compile your own \CGG{} with the the patch and the instructions found here: \nameref{sub:notable_options_and_caveats}.
+
+These shortcuts will only display in the English version for the caption/hints and the
+included shortcuts.html file in the "Shell Cmds" of the program does not include them.
+The texts in the menu and the captions of the icons,
+written with the '-' character between the Special key and the key in the default set, for
+example \texttt{Shift-s}, have been replaced by the '+' character. And the
+letters are always in capital letters although \textit{Shift} is not pressed. This notation is
+more consistent in what many, if not all, the other NLE programs use. Some of the original default shortcuts like
+\texttt{BD Render... (Ctrl+Shift+d)} and \texttt{DVD Render... (Alt+d)} have been deleted
+because they are not used frequently. If a shortcut in the After column as shown in the following table has a '+' symbol (for example: \texttt{+ 'I'}),
+it means that it is an additional shortcut added to the old shortcut/s in the Before column
+and also that that shortcut was confiscated from a default \CGGI{} shortcut where it had a different function.
+
+These shortcuts are very useful because the keys more frequently used have
+priority in editing, and are easy to use with the left hand on the keyboard and the right hand on the mouse.
+
+\begin{longtable}[h] {|p{6.4cm}|p{3.3cm}|p{3.3cm}|}
+ \toprule
+ \multicolumn{3}{|c|} {\textcolor{CinRed}{\textbf{Alternative Shortcuts}}} \\
+ \midrule
+ \textbf{Description} & \textbf{Before} & \textbf{After} \\
+ \midrule
+%begin{latexonly}
+ \endhead
+%end{latexonly}
+
+ To clip & 'i' & Ctrl+I \\
+ \hline
+ Scroll window timeline... left & LeftArrow, ',' & LeftArrow \\
+ \hline
+ Scroll window timeline... right & RightArrow, '.' & RightArrow \\
+ \hline
+ Label & 'l', ',' & ''' (single quote) \\
+ \hline
+ Go To & 'g' & Ctrl+G \\
+ \hline
+ Generate keyframes... tweeking & 'j' & 'G' \\
+ \hline
+ Jump forward... next Keyframe & 'k' & Shift+Right Arrow \\
+ \hline
+ Jump backward... next Keyframe & Shift+K & Shift+Left Arrow \\
+ \hline
+ New Project... & 'n' & Ctrl+N \\
+ \hline
+ Load files... &'o' & Ctrl+O \\
+ \hline
+ Save &'s' & Ctrl+S \\
+ \hline
+ Save as... & Shift+s & Ctrl+Shift+S \\
+ \hline
+ Save Session & Ctrl+S & no shortcut \\
+ \hline
+ Select All & 'a'& Ctrl+A \\
+ \hline
+ Deselect All & 'a' or cursor move & Ctrl+A, Ctrl+Shift+A \\
+ \hline
+ Select Edits & Ctrl+Alt+' & Ctrl+Alt+A \\
+ \hline
+ Undo & 'z', Ctrl+Z & Ctrl+Z \\
+ \hline
+ Redo & Shift+Z & Shift+Z \\
+ \hline
+ InPoint & '[', '<' & + 'I' \\
+ \hline
+ OutPoint & ']', '>' & + 'O' \\
+ \hline
+ Play Normal reverse & NumKP 6, Alt+O & + 'J' Normal\&Fast \\
+ \hline
+ Play Stop & NumKP 0, Alt+M & + 'K' \\
+ \hline
+ Play Normal forward & NumKP 3, Alt+L & + 'L' Normal\&Fast \\
+ \hline
+ One Frame back & NumKP 4, Alt+U & + ',' (comma) \\
+ \hline
+ One Frame forward & NumKP 1, Alt+J & + '.' (period) \\
+ \hline
+ Jump backward to the next cut & Alt+Left Arrow & + 'A' \\
+ \hline
+ Jump forward to the next cut & Alt+Right Arrow & + 'S' \\
+ \hline
+ Load window: Select All files & Ctrl+A & Ctrl+A \\
+ \hline
+ Load window: Deselect All files & Ctrl+Z & Ctrl+Shift+A \\
+ \hline
+ BD Render... & Ctrl+Shift+d & no shortcut \\
+ \hline
+ DVD Render... & Alt+d & no shortcut \\
+ \hline
+ Delete last track & 'd' & Ctrl+D \\
+ \hline
+ Quit & 'q' & Ctrl+Q \\
+ \hline
+ Settings $\rightarrow$ Save settings now & Ctrl+Shift+S & Shift+S \\
+ \hline
+ Settings $\rightarrow$ Align cursor on frames & Ctrl+A & Ctrl+F \\
+
+ \hline
+\end{longtable}
+
+A common practice in video editing is the ability to jump from one part of the timeline to another: jumping from one \textit{cut} to another or from one \textit{label} to another or even from one \textit{keyframe} to another. Using shortcuts in these cases is even more advantageous. In the next table we summarize these alternative shortcuts of the main jumps.
+
+\begin{longtable}[h] {|p{7cm}|p{6.5cm}|}
+ \toprule
+ \multicolumn{2}{|c|} {\textcolor{CinRed}{\textbf{Alternatives - Some jumps backward and forward}}} \\
+ \midrule
+%begin{latexonly}
+ \endhead
+%end{latexonly}
+
+ Jump backward to the next cut & Alt+Left Arrow, 'A' \\
+ \hline
+ Jump forward to the next cut & Alt+RightArrow, 'S' \\
+ \hline
+ Jump backward to the next label & Ctrl+Left Arrow \\
+ \hline
+ Jump selecting forward label & Ctrl+Shift+Right Arrow \\
+ \hline
+ Jump selecting backward label & Ctrl+Shift+Left Arrow \\
+ \hline
+ Jump forward to the next label & Ctrl+Right Arrow \\
+ \hline
+ Jump backward... next Keyframes & Shift+Left Arrow \\
+ \hline
+ Jump forward... next Keyframes & Shift+Right Arrow \\
+ \hline
+ Jump backward to the next Auto & Ctrl+Shift+Alt+Left Arrow (only works on UbuntuStudio) \\
+ \hline
+ Jump forward to the next Auto & Ctrl+Shift+Alt+Right Arrow (only works on UbuntuStudio) \\
+
+ \hline
+\end{longtable}
\item[YUV color range] default choice is JPEG, alternate is MPEG
\end{description}
-Some general tips (See also \ref{sec:video_attributes} \textit{Color model}):
+Some general tips (See also \ref{sec:video_attributes} \textit{Color model} and \nameref{sec:overview_color_management}):
\begin{itemize}
\item If your hardware allows it use RGB-Float (in \texttt{Settings $\rightarrow$ Format}); this format does not lead to transfer errors from one model to another, but it uses more cpu.
\item Use RGB-8 if the source is RGB and YUV-8 if the source is YUV (most commonly used).
- \item If you notice alterations in color/brightness representation, try playing with color models in \texttt{Settings $\rightarrow$ Format} and with \textit{YUV color space} and \textit{YUV color range} in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab. Another possibility is to check if the display color model conforms to the project color model.
+ \item If you notice alterations in color/brightness representation, try playing with color models in \texttt{Settings $\rightarrow$ Format} and with \textit{YUV color space} and \textit{YUV color range} in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab. Another possibility is to check if the display color model conforms to the project color model. A practical case that may arise is as follows\protect\footnote{thanks to DeJay}: YUV source with limited color range (MPEG or TV); \CGG{} set with the color range to extended (JPEG or PC); the colors on the compositor will be flattened. If we set the color range to MPEG the colors will be correct but hard clipping will occur. In this case the best result is presented by setting the color range to JPEG but then doing a conversion of the source to JPEG color range via the \texttt{ColorSpace} plugin. Summary table:
\end{itemize}
+\begin{center}
+ \begin{tabular}{|c|c|c|}
+ \hline
+ \textbf{Source} & \textbf{YUV Color Range} & \textbf{Colors} \\
+ \hline
+ MPEG & JPEG & Flat colors \\
+ MPEG & MPEG & Hard clipping \\
+ MPEG + conversion to JPEG & JPEG & Colors OK \\
+ \hline
+ \end{tabular}
+\end{center}
\section{Automatic "Best Model" Media Load}%
\label{sec:conform_the_project}
AppImage will probably not allow for either VDPAU or VA-API hardware acceleration because the
computer where AppImage is created will not have the same graphics card and/or vaapi/vdpau
-libraries as yours. In other words:
+libraries as yours.
+It is recommended for best results that you build \CGG{} on your specific computer as described in \ref{sec:single-user-build}.
+So in summary:
\begin{itemize}
\item Hardware acceleration, vaapi or vdpau, works the same running either the created binary or the created AppImage from that binary on that same computer.
\item Hardware acceleration using an AppImage created on another computer running a different Operating System or even just a different level of Operating System, most likely will not work unless the user's computer just happens to have the same characteristics with respect to vaapi/vdpau as the computer where the AppImage was created.
export CIN_HW_DEV=vaapi
\end{lstlisting}
+In addition for a computer with dual graphics cards, you can select your specific device with an environment variable
+to decode and encode. For example:
+\begin{lstlisting}[numbers=none]
+CIN_DRM_DEC=/dev/dri/renderD129 CIN_DRM_ENC=/dev/dri/renderD128 ./cin
+\end{lstlisting}
+and substituting your specific location instead of /dev/dri/renderD129 or D128.
+
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, \textit{Use HW device} flag
\item downgrade the cuda development package to a version that works for your board.
\end{enumerate}
-\subsection{Final Note}%
+\subsection{Additional topics on hardware acceleration}%
\label{sub:final_note_on_acceleration}
In wrapping up this Hardware Acceleration section, you may want to refer to the following to determine the current supported formats:
\begin{description}
\item[F\_lut:] Compute and apply a lookup table to the RGB/YUV input video.
- \item[F\_lut1d:] Adjust colors using a 1D LUT.
- \item[F\_lut3d:] Apply a 3D LUT to an input video.
+ \item[F\_lut1d:] Adjust colors using a 1D LUT "file" input.
+ \item[F\_lut3d:] Apply a 3D LUT "file" to an input video.
\item[F\_lutrgb:] Compute and apply a lookup table to the RGB input video.
\item[F\_lutyuv:] Compute and apply a lookup table to the YUV input video.
\end{description}
-For example, to use a 3dlut simply load your video, drop the F\_lut3d plugin on that track, and bring up the lut3d controls window, highlight the \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.
+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 (with 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. Only F\_lut1d and F\_lut3d allow for a file input and these usually are files with the .cube extension.
\subsection{Encoding into Dolby Pro Logic}%
\label{sub:encoding_dolby_pro_logic}
the original media, you can alleviate the lag between the Audio and Video by disabling
\textit{Play every frame} in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab. Now frames
will be skipped in order to keep the audio/video in synch.
+
+\subsection{How to remove letterbox/pillarbox bands}%
+\label{sub:remove_letterbox}
+
+To remove the horizontal black bands of the letterbox or the vertical
+black bands of the pillarbox we need to change the \textit{size} and
+\textit{aspect ratio} of the source by cropping.
+For example, if we want to remove the letterbox from a $4:3$ frame to
+leave only the content with aspect ratio $3:2$, We have to change the
+project format by doing the following steps:
+
+\begin{enumerate}
+ \item Check the size of the base W of the original frame in pixels:
+
+ \texttt{Resource} window $\rightarrow$ \texttt{RMB} on Asset
+$\rightarrow$ \texttt{Info} $\rightarrow$ \texttt{Detail}; e.g. W =
+768 px
+ \item Obtain the height of the figure in $3:2$, i.e., without the
+black bands; H can be obtained from the formula:
+
+ $\frac{3}{2} = \frac{W}{H}$ \quad from which $H = \frac{768 \times
+2}{3}$ \qquad e.g., H = 512 px
+ \item Note that $W \times H = 768 \times 512$ is just the crop we
+are looking for to switch from $4:3$ frame to $3:2$ frame without
+letterbox.
+ \item Open \textit{Set Format} window: \texttt{Settings
+$\rightarrow$ Format}
+ \item Change $H = 512$ and set \textit{Display Aspect Ratio} to
+$3:2$; press \texttt{Apply} and \texttt{OK}. Note that we leave W
+unchanged, since the frame width does not change.
+ \item If needed, use the \textit{Camera} tool to get the
+desired viewport.
+\end{enumerate}
+
+\paragraph{Note:} in complex situations, with multiple sources of
+different sizes, it may be appropriate to perform an additional
+step first: change the size of the track on the Timeline via
+\texttt{RMB $\rightarrow$ Resize track}.
+In this way we crop the track to match it to the project format that
+we will change in the next step. Thus we avoid possible unwanted
+distortions.
+
+In the case of the pillarbox, we will leave H unchanged while
+calculating the new value of W. The formula $\frac{x}{y} =
+\frac{W}{H}$ is valid for any aspect ratio ($4:3; 16:9; 2.35:1$; etc).
+
Wipe a specific shape across the video. Currently available 63 shapes are:
-\begin{center}
\begin{longtable}{p{4cm}p{4cm}p{4cm}}
- \label{tabular:transitions}
+ \label{tabular:transitions}\\
+ \hline
\textit{asimetric\_clocks} & \textit{asimetric\_clocks\_2} & \textit{audio} \\
\textit{burst} & \textit{Butterfly} & \textit{Circle-h\_01} \\
\textit{Circle-h\_02} & \textit{Circle-v\_01} & \textit{Circle-v\_02} \\
\textit{squares} & \textit{star} & \textit{tile2x2h} \\
\textit{tile2x2v} & \textit{Venetian-Blinds-h-x05} & \textit{Venetian-Blinds-h-x10} \\
\textit{Venetian-Blinds-v-x05} & \textit{Venetian-Blinds-v-x10} & \textit{water} \\
-\\
- \textit{Cinelerra16-9-Heavy} & \textit{Cinelerra16-9-Light} & \textit{CinelerraGG} \\
- \textit{16-9\_boart} & \textit{16-9\_boxes} & \textit{16-9\_cat\_eyes} \\
- \textit{16-9\_film\_bands} & \textit{16-9\_multi\_circle} & \textit{16-9\_multi\_spiral} \\
- \textit{16-9\_multi\_square} & \textit{16-9\_rare\_spiral} & \textit{16-9\_rectangles} \\
- \textit{16-9\_star} & \textit{16-9\_stars} & \textit{16-9\_wood} \\
-
- \bottomrule
+ \hline
+ \textit{Cinelerra16-9-Heavy} & \textit{Cinelerra16-9-Light} & \textit{CinelerraGG} \\
+ \textit{16-9\_boart} & \textit{16-9\_boxes} & \textit{16-9\_cat\_eyes} \\
+ \textit{16-9\_film\_bands} & \textit{16-9\_multi\_circle} & \textit{16-9\_multi\_spiral} \\
+ \textit{16-9\_multi\_square} & \textit{16-9\_rare\_spiral} & \textit{16-9\_rectangles} \\
+ \textit{16-9\_star} & \textit{16-9\_stars} & \textit{16-9\_wood} \\
+ \hline
\end{longtable}
-\end{center}
+
The menu for Shape Wipe that popups when you click on \textit{Show} has several possible choices. First, the \textit{Shape} allows for choosing from the list of shapes as outlined previously either by typing in the textbox, using the down arrow, or clicking on the tumbler down/up arrows.
Next, there is a \textit{Feather} textbox with tumbler arrows or a slider bar to easily change the blending amount. A reset button is conveniently located to the right of the slider bar. There is a checkbox to \textit{Preserve shape aspect ratio} and a \textit{Direction} of \textit{White to Black} or \textit{Black to White} (figure~\ref{fig:star}).
\chapter{Troubleshooting and Help}%
\label{cha:troubleshooting_help}
+To help new users, a pdf has been created comparing the editing workflow of \CGG{} with the more usual editing workflow of Adobe Premiere Pro. See \href{https://cinelerra-gg.org/download/Workflow.pdf}{here}.
+
\section{Help and Context Help}%
\label{sec:help_context_help}
\index{context help}
Context help can be requested from almost any \CGG{} window or subwindow by pointing with the mouse cursor on the GUI element of interest and pressing \texttt{Alt/h}. That HTML manual page will be shown via the configured web browser, which is assumed as most relevant to the GUI element currently under the mouse pointer.
\subsection{How Context Help works}%
-\label{sub:how_it_works}
+\label{sub:how_context_help_works}
The hotkey to request context help is \texttt{Alt/h}. What particular help page is shown, depends on the mouse cursor location while \texttt{Alt/h} is pressed. Usually, when the mouse is located in some window or dialog, the help page related to the functionality of this window or dialog is shown. In this case the mouse can point either on some widget, or on an empty area in the window. In \CGG{} GUI there are several rich loaded windows, \textit{Timeline} and \textit{Compositor} for example. In such a case different help pages can be requested depending on the particular GUI element under the mouse. For example, pressing \texttt{Alt/h} while pointing on the \textit{Autos curve} in a track would show help on \textit{automation keyframes} section, pointing on the \textit{Overlay} mode button in the \textit{patchbay} would show help on \textit{overlays}, pointing on the \textit{camera control} in \textit{Compositor} would show help on \textit{camera and projector}.
\end{center}
Here you can log the problem into the MantisBT bugtracker, or use the forum Q\&A for help from other users, or email the
-problem using the address:{\small \href{mailto:cin@lists.cinelerra-gg.org}{cin@lists.cinelerra-gg.org}} It is usually more
+problem to the Mailing List using the address:{\small \href{mailto:cin@lists.cinelerra-gg.org}{cin@lists.cinelerra-gg.org}}. It is usually more
helpful if instead of starting \CGG{} from its application icon, start from a window so that if there are error
messages related to the problem, they can be captured from the screen and emailed or logged. The command to run
from a window is: \texttt{<directory\_path of where you installed cinelerra>/bin/cin} -- for example if
-installed in \texttt{/mnt0/build5/cinelerra-5.1}, you would execute the following command to start the program:\\
-\texttt{/mnt0/build5/cinelerra-5.1/bin/cin} \\
+installed in \texttt{/mnt0/build5/cinelerra-5.1}, you would execute the following command to start the program:
+\newline \hspace*{1cm} \texttt{/mnt0/build5/cinelerra-5.1/bin/cin} \\
The problem you are experiencing may be as simple as an error due to the settings in your \texttt{\$HOME/.bcast5} subdirectory so you may want to first rename your current \texttt{.bcast5} in order to start with default settings. By renaming the directory instead of deleting it, you will be able to put it back and not lose all of your preferences.
-However, there are some easy things to do to fix errors that may have resulted from media problems,
+A note about using the Mailing List {\small \href{mailto:cin@lists.cinelerra-gg.org}{cin@lists.cinelerra-gg.org}}
+is that to avoid receiving spam, it will require you to subscribe. But it is also easy to unsubscribe once you have
+the information you need. The Mailing List, although routinely used by developers or contributors to discuss
+changes, can provide more technical answers in some cases and the email goes directly to individuals who are quite
+likely sitting at their computers depending on the timezone.
+
+There are some easy things to do to fix errors that may have resulted from media problems,
computer problems, or operational missteps so you can proceed without having to wait for help. These
are outlined in \ref{cha:when_things_go_wrong} - be sure to read down through
\textit{Common Problems} where some exact error messages are mentioned along with their cause or solution. Other
bottom of the main window (figure~\ref{fig:automation}).
\item If the rate at which frames are captured during Recording is much lower than the framerate of the source, the video will accumulate in the recording buffers over time and the audio and video will become out of sync. Decrease the number of frames to buffer in the device in \texttt{Settings $\rightarrow $ Preferences, Recording} tab so that the excess frames are dropped instead of buffered.
\item If loading files locks up, this might be because \CGG{} is building picons/vicons for the Resources window. If you load a large number of images it needs to decompress every single image to build a picon/vicon. Go into \texttt{Settings $\rightarrow$ Preferences, Appearance} tab and disable \textit{Use thumbnails in resource window} to skip this process. Keep in mind though, that it only has to create these thumbnails the first time a new piece of media is loaded or the values are changed.
+ \item After a crash, look on the window where you started running \CGG{} to see if there is a line towards the end of the output that reads something like a bunch of numbers followed by the word "AssetVIconThread". Frequently this indicates that some system resouce has been exhaused in creating/running the Vicon images in the Resources window. You can disable \textit{Use thumbnails in resource window} in Settings/Preferences, Appearace tab to see if this resolves the crashing. In most cases when this is the cause, it will be the second to last line shown in the window.
+In addition, you might want to \textit{Delete clip thumbnails} in the Interface
+tab section of Settings/Preferences.
\item For an older computer with less CPU power, in \texttt{Settings $\rightarrow$ Preferences, Appearance} tab, be sure that \textit{Autocolor assets }is disabled; set \textit{View thumbnail size} \& \textit{Vicon quality}\& \textit{Vicon color mode} to lower values or switch to \textit{No Play} instead of \textit{Full Play} in the Resources window (this is to the right of the word \textit{Visibility} in the left hand side of that window). You will then have more CPU and more memory available to do actual editing.
\item When using AppImage to run with the OpenGL video driver, you must have the OpenGL drivers
for your Operating System graphics board installed as it is not included in the AppImage library set. The
\item BugTracker - sometimes there is a problem creating a new report issue in the website's Mantis Bugtracker
using the Chrome web browser and you lose what you just typed in. Generally when logging into the bugtracker, the
option "only allow with this IP address" needs to be disabled, then the bug tracker will work fine.
- \item Forum - if you can not register your username in the website's Forum, it could be
-because the protection measures against spammers also is in effect with real users, so sometimes the website blocks the registration for the forum. This often affects email addresses of well-known email providers. Send email to the mailing list (({\small \url{https://lists.cinelerra-gg.org/mailman/listinfo/cin}}) so that you can be added to the forum manually as long as
+ \item Forum -
+
+ \begin{enumerate}
+ \item If you can not register your username in the website's Forum, it could be
+because the protection measures against spammers also is in effect with real users, so sometimes the website blocks the registration for the forum. This often affects email addresses of well-known email providers. Send email to the mailing list which requires you to subscribe (({\small \url{https://lists.cinelerra-gg.org/mailman/listinfo/cin}}) so that you can be added to the forum manually as long as
you confirm that you agree with the terms of use of this website and the forum.
- \item Forum - in the website's Forum, use of unacceptable characters or strings can result in the error
+ \item In the website's Forum, use of unacceptable characters or strings can result in the error
message "A potentially unsafe operation has been detected in your request to this site". You lose what
you had typed in and you will have to check what you remember typing in for a non-converational set of
characters. This can be as simple as ../../ (dot dot slash dot dot slash) or some types of C++ code.
+
+ \item Entries not showing up for several hours could be due to taking a long time
+to propagate around the world on some time basis.
+ \item Not seeing a comment or reply section could be because you are not logged in
+or recognized as logged in. If you seem to be logged in, logout and then login again to
+see if that resolves the problem. Another potential solution is the switch the language
+being used to English, even if you think it is already English. Sometimes it is left in
+a different language and needs to be reset.
+ \item Until you have made a few entries in the Forum, you will have to wait a few
+hours for your entry to be approved. This is because there are people who spam the
+forum so attempts to alleviate this by requiring moderation for new users until validated.
+ \end{enumerate}
+
\end{enumerate}
\textbf{Some Helpful User Readable Text Dumps}
In order to provide some types of help, the Menu Bar Shell Commands are available for customization purposes (figure~\ref{fig:trouble-img001}).
-\begin{figure}[h!]
+\begin{figure}[ht]
\centering
\includegraphics[width=1.0\linewidth]{trouble-img001.png}
\caption{Some windows used to manipulate Shell Commands scripts}
\item \textit{Setting Shell Commands} \textit{how to} which explains how to configure your own commands.
\item \textit{Shortcuts} html file for easily looking up a particular shortcut.
\item \textit{RenderMux} shell script to use ffmpeg concatenate to copy files such as \textit{look.mp4001}, \textit{look.mp4002}, \textit{look.mp4005}{\dots} that were rendered using \textit{Create new file at each label} or with the Render Farm.
+ \item \textit{Delete brender files in tmp} shell script to delete the many brenderX files in /tmp when using the default location.
\end{enumerate}
\section{\CGG{} Command Line -h}%
\label{sec:program_window}
\index{program window}
-The main window is called the \textit{Program} window and is often just referred to as the \textit{timeline} \index{timeline}. Here is where you enter the main menu operations.
+The main window is called the \textit{Program} window and is often just referred to as the \textit{timeline}\index{timeline}. Here is where you enter the main menu operations.
This timeline consists of a vertical stack of tracks with time represented horizontally on the track.
It is the output of the rendering operations and this is what is saved when you run the \textit{File} pulldown, Save command.
-Immediately to the left of the timeline is the patchbay \index{patchbay}. The patchbay contains options that affect each track.
+Immediately to the left of the timeline is the patchbay\index{patchbay}. The patchbay contains options that affect each track.
These options are described in great detail in \nameref{sec:patchbay}.
The \textit{Window} pulldown on the main window contains options
several is described in a little more detail in other areas of this manual.
\vspace{2ex}
-\begin{tabular}{ll}
+\begin{longtable}{ll}
\hline
First set of 3 symbols & Move in the reverse direction on the timeline \\
4th symbol & Stop play \\
Set Timecode & Explained in \ref{sub:align_timecodes} \\
Gang Modes & Explained in \ref{sub:displaying_tracks_ganged} \\
\hline
-\end{tabular}
+\end{longtable}
The \textit{Manual Go To} \index{goto} menu is quite versatile as you can see in figure~\ref{fig:goto_menu}. The
options of \textit{=} represents goto the position indicated in the textbox; \textit{+} indicates
Use the pulldown \texttt{Settings$\rightarrow$Align cursor on frames} to change the alignment by
checking the box on for video and off for audio.
-\begin{figure}[htpb]
- \centering
- %\includegraphics[width=0.8\linewidth]{name.ext}
- \begin{tikzpicture}[scale=1, transform shape]
- \node (img1) [yshift=0cm, xshift=0cm, rotate=0]
- {\includegraphics[width=0.6\linewidth]{insertion-point.png}};
- \node [yshift=-5mm, xshift=-1cm,anchor=east] at (img1.north west) (Pulldowns) {Pulldowns};
- \node [yshift=-10mm, xshift=-1cm,anchor=east] at (img1.north west) (Transport) {Transport \& Buttons Bar};
- \node [yshift=-15mm, xshift=-1cm,anchor=east] at (img1.north west) (Timebar) {Timebar};
- \node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Title) {Media Title };
- \node [yshift=-28mm, xshift=-1cm,anchor=east] at (img1.north west) (Video) {Video Track};
- \node [yshift=-46mm, xshift=-1cm,anchor=east] at (img1.north west) (Audio) {Audio Track};
- \draw [->, line width=1mm] (Pulldowns) edge ([yshift=-5mm] img1.north west);
- \draw [->, line width=1mm] (Transport) edge ([yshift=-10mm] img1.north west);
- \draw [->, line width=1mm] (Timebar) edge ([yshift=-15mm] img1.north west);
- \draw [->, line width=1mm] (Title) edge ([yshift=-20mm] img1.north west);
- \draw [->, line width=1mm] (Video) edge ([yshift=-28mm] img1.north west);
- \draw [->, line width=1mm] (Audio) edge ([yshift=-46mm] img1.north west);
- \end{tikzpicture}
-
- \caption{Insertion point is at 0:00:25:10 in Hr:Mn:Sec:Frames}
- \label{fig:insertion-points}
-\end{figure}
-
\subsection{Editing Modes}%
\label{sub:editing_modes}
on the timeline operate.
There is: \emph{drag and drop mode} and \emph{cut and paste mode}.
The editing mode is determined by selecting the \texttt{arrow} \index{arrow}, or immediately to the right of the arrow,
-the \texttt{I-beam} \index{i-beam} in the Transport and Buttons bar. In figure~\ref{fig:insertion-points} you can see
-the green colored highlight \protect\footnote{green is used in the default Cakewalk theme, but the highlight color will be different in other themes} on the arrow icon indicating that you are currently in
-\emph{drag and drop mode}.
+the \texttt{I-beam} \index{i-beam} in the Transport and Buttons bar. In figure~\ref{fig:insertion-points} you can see the green colored highlight \protect\footnote{green is used in the default Cakewalk theme, but the highlight color will be different in other themes} on the arrow icon indicating that you are currently in \emph{drag and drop mode}.
+
+\begin{figure}[htpb]
+ \centering
+ %\includegraphics[width=0.8\linewidth]{name.ext}
+ \begin{tikzpicture}[scale=1, transform shape]
+ \node (img1) [yshift=0cm, xshift=0cm, rotate=0]
+ {\includegraphics[width=0.6\linewidth]{insertion-point.png}};
+ \node [yshift=-5mm, xshift=-1cm,anchor=east] at (img1.north west) (Pulldowns) {Pulldowns};
+ \node [yshift=-10mm, xshift=-1cm,anchor=east] at (img1.north west) (Transport) {Transport \& Buttons Bar};
+ \node [yshift=-15mm, xshift=-1cm,anchor=east] at (img1.north west) (Timebar) {Timebar};
+ \node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Title) {Media Title };
+ \node [yshift=-28mm, xshift=-1cm,anchor=east] at (img1.north west) (Video) {Video Track};
+ \node [yshift=-46mm, xshift=-1cm,anchor=east] at (img1.north west) (Audio) {Audio Track};
+ \draw [->, line width=1mm] (Pulldowns) edge ([yshift=-5mm] img1.north west);
+ \draw [->, line width=1mm] (Transport) edge ([yshift=-10mm] img1.north west);
+ \draw [->, line width=1mm] (Timebar) edge ([yshift=-15mm] img1.north west);
+ \draw [->, line width=1mm] (Title) edge ([yshift=-20mm] img1.north west);
+ \draw [->, line width=1mm] (Video) edge ([yshift=-28mm] img1.north west);
+ \draw [->, line width=1mm] (Audio) edge ([yshift=-46mm] img1.north west);
+ \end{tikzpicture}
+
+ \caption{Insertion point is at 0:00:25:10 in Hr:Mn:Sec:Frames}
+ \label{fig:insertion-points}
+\end{figure}
With the arrow highlighted for \emph{drag and drop mode}, a double click with the left mouse button in the timeline selects the edit the mouse pointer is over.
Then dragging in the timeline repositions that edit and this can be used for moving effects,
The main window pulldowns as pointed out in figure~\ref{fig:insertion-points} are quite obvious in their meaning and usage, so here is only a summary.
-%TODO Figure 3 shows an example of the pulldowns as displayed in the main window.Appearance
-
-
\begin{description}
\item[File] \index{file} options for loading, saving, and rendering as described in other sections (\ref{cha:load_save_and_the_EDL}).
\item[Edit] \index{edit} edit functions; most of which have shortcuts that you will quickly learn (\ref{cha:editing}).
\label{fig:compositor_window}
\end{figure}
-The Compositor window (figure~\ref{fig:compositor_window}) is used to display the timeline
-output. Playing and moving along the timeline video in the Program window shows in the
-Compositor window what the current image is. Here is where many compositing operations are
-performed that can change
-what the timeline will look like. When enabled, you can simply click the LMB in the Compositor
-window to start and stop play.
- You can zoom in and out to
-see small details, pan with the scrollbars, lock the window to prevent changes, add masks,
-and make changes with the Projector and Camera function operators. These will be explained
-in more detail in the following sections.
+The Compositor window (figure~\ref{fig:compositor_window}) is used to display the timeline output. Playing and moving along the timeline video in the Program window shows in the Compositor window what the current image is. Here is where many compositing operations are performed that can change what the timeline will look like and that is why it is called \textit{canvas}. The canvas dimesions correspond, by default, to the W/H values set in the project (\textit{Set Format} window). Canvas size = output size = project size.
+
+When enabled, you can simply click the LMB in the Compositor window to start and stop play. You can zoom in and out to see small details, pan with the scrollbars, lock the window to prevent changes, add masks, and make changes with the Projector and Camera function operators. These will be explained in more detail in the following sections.
\subsection{Compositor Controls}%
\label{sub:compositor_controls}
Much of the editing in \CGG{} involves \textit{compositing} which is the combining of visual
elements from different sources into single images. This includes such things as
speeding up and slowing down the video, changing the resolution, creating a split screen, and fading in and out.
-Compositing operations are done on the timeline and in the Compositor window using various
+Compositing operations are done on the timeline and in the Compositor window (canvas) using various
operations and other compositing attributes that are available in the Resources window.
When \CGG{} is performing a compositing operation it plays back through the
compositing engine, but when not, it uses the fastest decoder that it has.
\label{ssub:output_size}
\index{temporary}
-\CGG{}'s compositing routines use a \textit{temporary} which is a single frame of video in
-memory where graphics processing takes place. The size of the temporary and of the output in
-the compositing pipeline are different and vary for any particular frame. Effects are processed in
-the temporary and as such are affected by the temporary size. In the case of the camera, its
-viewport is the temporary size. However, projectors are rendered to the output and so are affected
-by the output size. When the temporary is smaller than the output, the temporary will have blank
-borders around the region in the output. When the temporary is larger than the output, it will be
-cropped.
+\CGG{}'s compositing routines use a \textit{temporary} which is a single frame of video in memory where graphics processing takes place. By default the size of the temporary is that of the project ($W \times H$); i.e., the output size; i.e, the canvas size. But if the tracks on the timeline have various sizes different from those of the project, then the temporary will take the size of the active track (viewport = green border). We can also change the size of the viewport using the Camera tool, as well as pans and zooms the temporary displayed in it. Effects are processed in the temporary and as such are affected by the temporary size. In the case of the camera, its viewport is the temporary size. The size of the temporary and of the output in the compositing pipeline can be different and vary for any particular frame. However, projectors are rendered to the output and so are affected by the output size. The temporary is the basis on which the Projector tool acts to display the canvas on the Compositor window. The canvas always has the size of the project, although with the projector we can make pans and resizes of the red border inside it. When the temporary is smaller than the output, the temporary will have blank borders around the region in the output. When the temporary is larger than the output, it will be cropped.
\subsubsection*{Track and Output size}%
\label{ssub:track_size}
a video asset and choosing \texttt{Match $\rightarrow$ Match project size}. When you \emph{Match project size}, you
are conforming the output to the asset. To change the size and aspect ratio of the output (Projector) we have to change the whole project, which will alter all the tracks in the timeline. Once you have set the output size in 1 of these 3 ways,
any newly created tracks will conform to the specified output size. When rendering, the project's
-output size is the final video track size where the temporary pipeline is rendered into.
+output size is the final video track size where the temporary pipeline is rendered into.
+
+To clarify, let's take an example.
+
+If we load a media (M) into Resources and adjust the size of the project to the size of M, we will get the canvas size of the media $W_{M} \times H_{M}$). We can see in the Set Format window that the project's default values ($W \times H$) have changed to those of M ($W_{M} \times H_{M}$). The tracks on the timeline can have different sizes, but what we will see on the canvas, that is, in the Compositor window, is always the output size i.e. the size of the project. Tracks with smaller sizes will be seen with black bands; tracks with larger sizes will be cropped. Each track has its own size but we will see it inserted in the output size. If we change the output size the tracks will not change, remaining in their original size. We can only change the size of the tracks by manually acting on each one in the ways seen before. Finally, if we create a new track in a project of size $W \times H$, it will assume the size of the project automatically.
\subsubsection*{Aspect Ratio (Theory)}%
\label{ssub:aspect_ratio_theory}
\index{aspect ratio}
\index{PAR, DAR, SAR}
-The aspect ratio is the ratio of the sides of the frame (\textit{Width} and \textit{Height}). For example, classically broadcast TV was 4:3 (= 1.33), whereas today it has changed to 16:9 (= 1.85); in cinema we use the 35 mm aspect ratio of 1.37 (Academic aperture), but even more so the super 35 mm (2.35). There are also anamorphic formats, i.e. that have no square pixels, like Cinemascope (2.35). The projection must be \textit{normalized} to have an undistorted view.
+The aspect ratio is the ratio of the sides of the frame (\textit{Width} and \textit{Height}). For example, classically broadcast TV was 4:3 (= 1.33), whereas today it has changed to 16:9 (= 1.78); in cinema we use the 35 mm aspect ratio of 1.375 (Academy aperture), academy flat (1.85 or widescreen) but even more so the super 35 mm (from 1.33 to 2.39). There are also anamorphic formats, i.e. that have no square pixels, like Cinemascope (2.39). The projection must be normalized to have an undistorted view.
+From the film or digital sensors of the cameras, we can extract any frame size we want. We are talking about \textit{viewports}, which we will examine shortly. Also important is the output of the video that will be rendered, because it is what we will see at the cinema, or on TV, or on the monitor of the PC, tablet or smartphone. Referring to figure~\ref{fig:temporary-01}, you can see these two possibilities: with the \textit{Camera} tool you choose the size and aspect ratio of the source file (regardless of the original size); while with the \textit{Projector} tool you choose the size and aspect ratio of the output. Other ways of changing the aspect ratio of assets or tracks we have seen previously (\texttt{Resize track}; \texttt{Match Output Size}; \texttt{Resize asset}). A method of changing the size of the entire project (canvas) is via the \texttt{Set Format} window. The following formula is used to vary the aspect ratio:
-From the film or digital sensors of the cameras, we can extract any frame size we want. We are talking about \textit{viewports}, which we will examine shortly. Also important is the output of the film that will be rendered, because it is what we will see at the cinema, or on TV, or on the monitor of the PC, tablet or smartphone. Referring to figure~\ref{fig:temporary-01}, you can see these two possibilities: with the Camera you choose the size and aspect ratio of the source file (regardless of the original size); while with the Projector you choose the size and aspect ratio of the output.
+\qquad $\frac{W}{H} =$ frame aspect ratio ($\frac{pixels}{pixels}$)
-The following formula is used to vary the aspect ratio:
-
-\qquad $\frac{W}{H} =$ aspect ratio ($\frac{pixels}{pixels}$)
-
-For example to obtain an aspect ratio of Super 35 mmm (2.35) starting from a FullHD file (1920x1080) whose base extension (1920) we want to keep:
+For example to obtain an aspect ratio of Super 35 mm (2.35) starting from a FullHD file (1920x1080) whose base extension (1920) we want to keep:
\qquad $\frac{1920}{H} = 2.35$
-from which: $H = 817$ pixels
-
-\CGG{} allows you to vary the input and output aspect ratio in the ways indicated in the previous section: by varying the pixels of the sides or by setting a multiplication coefficient.
-
-In \texttt{Settings $\rightarrow$ Format} there is the additional possibility to vary the shape of the pixels from 1:1 (square) to handle anamorphic formats. In such cases we use:
-
-\qquad $PAR=\frac{DAR}{SAR}$
+from which: $H = 816$ pixels
-where:
-
-\textit{DAR}= Display Aspect Ratio
-
-\textit{PAR}= Pixel Aspect Ratio (1 or 1:1 is square)
-
-\textit{SAR}= Storage Aspect Ratio (i.e media file aspect ratio)
+At the same time as changing the \textit{Height} parameter we also need to set \texttt{Display Aspect rati}o to 2.35. In fact, the parameters in Canvas Size are not related to those in Display Aspect ratio, unless we keep the \texttt{Auto} option checked, and we need to set both before we click on the \texttt{Apply} button. To set the aspect ratio to 2.35:1 we can choose from the drop-down menu the value 2.35 or set the value directly in the two input fields. Or again, it can be done automatically via the Auto option. Finally we can click on the Apply button to complete the calculations. Now we have arrived at the desired result: typical Super 35 mm dimensions and aspect ratio, although starting from a 16:9 FullHD. The new canvas, however, lost the pixels of a part of the initial video (crop), to be precise $1080 - 816 = 264$ lines of pixels from top and bottom.
+\CGG{} allows you to vary the input and output aspect ratio in the ways indicated in the previous section: by varying the pixels of the sides (Width/Height) or by setting a multiplication coefficient (W/H Ratio; in this example: placing $H Ratio = 816 : 1080 = 0.7556$) which performs the calculation automatically. If you set \textit{W Ratio} and \textit{H Ratio} at the same time with the same values, they work as multipliers and you get a resizing of the canvas, without altering the initial aspect ratio. If you change them to two different values or change only one of the two parameters, leaving the other at 1, you get an anamorphic video, with the pixels no longer being square (1:1) but becoming rectangular, deforming the image. If you use a non-standard aspect ratio, this has impact on other areas like titles, included stills and included non-anamorphotic footage. To avoid anamorphosis, the \texttt{Display Aspect ratio} must also be adjusted at the same time, for example, with the Auto option. \textit{Anamorphic} format is a complex field that is discussed
+in Andrea's paper: {\small \url{https://cinelerra-gg.org/download/Anamorphic.pdf}}.
+as well as in the Raffaella Traniello's guide: {\small \url{http://www.g-raffa.eu/Cinelerra/HOWTO/anamorphic.html}}.
\subsection{Camera and Projector}%
\label{sub:camera_and_projector}
Select the camera button to enable camera editing mode.
In this mode, the guide box shows where the camera position is in relation to past and future camera positions but not where it is in relation to the source video.
-The green box is the Viewport; at the beginning it coincides with the size of the source frame. If we move the viewport by dragging it with LMB (moving it in $x/y$), the green box remains fixed to the original size but the frame is moved to the new position. A yellow frame will appear along the edges of the frame to indicate the displacement with respect to the green box; this behavior differs from that seen for the Projector. Even if we act on the $z-axis$ (SHIFT + Drag, equivalent to the zoom), the frame narrows or widens, moving behind the yellow frame.
+The green box is the Viewport; at the beginning it coincides with the size of the source frame. If we move the viewport by dragging it with LMB (moving it in $x/y$), the green box remains fixed to the original size but the frame is moved to the new position. A yellow frame will appear along the edges of the frame to indicate the displacement with respect to the green box; this behavior differs from that seen for the Projector. Even if we click on the $z-axis$ (SHIFT + Drag, equivalent to the zoom), the frame narrows or widens, moving behind the yellow frame.
\subsubsection*{Camera and Projector Menu}%
\label{ssub:camera_and_projector_menu}
\label{fig:camera_tool}
\end{figure}
-In the \textit{Position} section you can act on the $X$, $Y$ and $Z$ coordinates. By either tumbling or entering text directly or by using the slider, the camera and projector can be precisely positioned. There is also a reference to the color of the curve as we see it on the timeline. You can also define the \textit{range} of action which by default is [-100 to 100]. By pressing the Reset button for each coordinate, or the global Reset button, the range is automatically brought to the project size value (HD; 4k; etc), which are usually the most useful limits. Note that the range can also be changed in the \textit{Program} window, in the \textit{zoom bar}, where there are similar input fields to enter the chosen limits.
+In the \textit{Position} section you can change the $X$, $Y$ and $Z$ coordinates. By either tumbling or entering text directly or by using the slider, the camera and projector can be precisely positioned. There is also a reference to the color of the curve as we see it on the timeline. You can also define the \textit{range} of action which by default is [-100 to 100]. By pressing the Reset button for each coordinate, or the global Reset button, the range is automatically brought to the project size value (HD; 4k; etc), which are usually the most useful limits. Note that the range can also be changed in the \textit{Program} window, in the \textit{zoom bar}, where there are similar input fields to enter the chosen limits.
In the \textit{Justify} section we can use automatic positioning in the 6 standard coordinates: Left, Horizontal, Right, Top, Center and Bottom.
\textit{Reset Projector}: causes the projector to return to the center.
-\subsubsection*{Use Case: Interaction Between Camera And Projector \protect\footnote{Example provided by Sam. The relative video is located at: \url{https://streamable.com/iq08i}}}%
+\subsubsection*{Use Case: Interaction Between Camera And Projector \protect\footnote{Example provided by Sam. The relative video is located at: \url{https://youtu.be/ZQaLZiYY1lg}}}%
\label{ssub:use_case_interaction_camera_projector}
\index{camera}
\index{projector}
Other options you will see if you \textit{right mouse click in the folder} which brings up the menu are described next \index{folders!RMB options}.
\begin{description}
- \item[ Load files ] for convenience to load files same as from the main window so you do not have to move the mouse so far in case you have multiple monitors.
+ \item[Load files ] for convenience to load files same as from the main window so you do not have to move the mouse so far in case you have multiple monitors.
\item[Display text/icons] as described previously for format variations preference.
\item[Select] options are All, Used, Unused, and None. This gives you the capability to have a set of the
contents highlighted for ease of use so you can see what is or is not loaded, or unset the highlight.
\index{folder add filter/search}
Creating folders that are more specific to a particular project is helpful in better organizing your work.
-This can be done by utilizing the files already loaded to the \textit{master} Media or Clips folders in the Resources window. The general rule is you can only drag clips to a ClipUserBin and you can only drag media to a MediaUserBin.
+This can be done by utilizing the files already loaded to the \textit{master} Media or Clips folders in the Resources window. The general rule is you can only drag clips to a ClipUserBin and you can only drag media to a MediaUserBin. No subfolders can be created within the new folders. Further below, after we populate the new folder, we will see how to use logical operators or other filters to automatically sort the media.
-Below are steps illustrating an easy way to set up a folder.
+Below are steps illustrating an easy way to set up a new folder.
-%TODO Below part need to be rewriten
\begin{enumerate}
- \item In the Resources window (figure~\ref{fig:folder_resources}), in the location of the Video/Audio effects and Media folders, bring up the \textit{Folder}$\dots$ popup by clicking the right mouse button.
- Highlight, then click \textit{New Media or Clips}.
- \begin{figure}[htpb]
- \begin{minipage}{.6\linewidth}
- \centering
- \includegraphics[width=0.9\linewidth]{folder_resources.png}
- \caption{Highlight, then click “New Media or Clips”.
- “Modify folder” can be used to change the name of a folder.
- “Delete folder” in the popup can be used to delete a folder.
- }
- \label{fig:folder_resources}
- \end{minipage}
- \hfill
- \begin{minipage}{.37\linewidth}
- \centering
-%begin{latexonly}
- \vspace{18ex}
-%end{latexonly}
-
- \includegraphics[width=0.9\linewidth]{folder_new.png}
- \caption{Type in your folder name in the textbox. Click OK.}
- \label{fig:folder_new}
- \end{minipage}
- \end{figure}
+ \item In the Resources window (figure~\ref{fig:folder_resources}), in the location of the Video/Audio effects and Media folders, bring up the \textit{Folder...} popup by clicking the right mouse button. Highlight, then click \textit{New Media} or \textit{New Clips}. \textit{Modify folder} can be used to change the name of a folder. \textit{Delete folder} can be used to delete a folder.
\item In the \textit{New folder} popup as shown below (figure~\ref{fig:folder_new}), type in your folder name in the textbox. Click OK.
- \begin{figure}[htbp]
- \centering
- \includegraphics[width=0.9\linewidth]{folder_master.png}
- \caption{The “master” Media folder}
- \label{fig:folder_master}
- \end{figure}
- \item Select the \textit{master} Media folder to see which files are currently loaded, figure~\ref{fig:folder_master}.
- Highlight the files there that you want to copy to your new folder (named Photos of Garden).
- Drag the files to the left and when you see the Photos of Garden folder become highlighted, then drop there.
- You can drag and drop any of the media from the \textit{master} Media at any time.
- It flashes when the drop is successful.
+ \item Select the \textit{master} Media folder to see which files are currently loaded, figure~\ref{fig:folder_master}. Highlight the files there that you want to copy to your new folder (named \textit{Photos of Garden}). Drag the files to the left and when you see the \textit{Photos of Garden} folder become highlighted, then drop there. You can drag and drop any of the media from the \textit{master} Media at any time. It flashes when the drop is successful.
\end{enumerate}
-Adding the Shift key before the actual drop, will allow for relative path filenames instead of full path.
-But you might want to include or eliminate some of the media that exists in one of the folders that you have set up already.
-In this case you will want to click on the \textit{Modify folder} in the popup.
-When you bring up the Modify folder window, if you already have files in that folder, you will see filters that were generated automatically when you did a Drag and Drop.
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.5\linewidth]{folder_resources.png}
+ \caption{New folder menu}
+ \label{fig:folder_resources}
+\end{figure}
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.4\linewidth]{folder_new.png}
+ \caption{Folder name}
+ \label{fig:folder_new}
+\end{figure}
+
+ \begin{figure}[htbp]
+ \centering
+ \includegraphics[width=0.8\linewidth]{folder_master.png}
+ \caption{The “master” Media folder}
+ \label{fig:folder_master}
+\end{figure}
+
+\subsection{Modify Folder: sorting the media}%
+\label{sub:sorting_media}
+\index{folder modify}
+
+In \CGG{} all the virtual mediafiles loaded in the \textit{Resources} window are collected in the \texttt{Media} folder without any kind of organization and sorting other than alphabetical. The Media folder is considered a \textit{master} folder because it is the basis for every other new folder we create. Another \textit{master} folder is \texttt{Clips}, and in fact we can create new clips folders as well. If we do editing of large projects containing numerous mediafiles, a rational and selective organization of the source material becomes necessary. In fact, having the sources organized in folders, where they can be found and used easily, makes subsequent editing much faster, as well as minimizing confusion and the possibility of errors. This step, which is fundamental in the pro environment, is called \textit{Logging} and also includes \textit{screening} individual mediafiles in the Viewer window; \textit{renaming} them rationally; and adding labels and descriptions in the \textit{metadata}.
+
+We start by creating one or more new folders (MediaUserBin). These will be empty and we should populate them with the mediafiles contained in the master Media folder. There are two options: manual \textit{Drag and Drop} or automatic populating by setting \textit{filters} (Smart Bins).
+
+\paragraph{Drag and Drop:} you drag mediafiles into the new folder one by one or in selected groups. The starting master folder can only be \texttt{Media} (or \texttt{Clips}, if we have created a new clip folder). Dragging is done by preserving the absolute path of the sources. If you open Modify Folder window you will notice that each imported mediafile occupies a different row characterized by its own path and name. See figure~\ref{fig:modify-target}. The \texttt{Value} field containing paths can contain only 63 characters, and it may happen to find the names cut off. The full path and name can be found by right-clicking on the row, but this is inconvenient and time-consuming. The best solution is to drag the mediafiles while holding down the \texttt{Shift} key; this will return the relative path instead of the absolute path, with space gain.
\begin{figure}[htpb]
- \centering
- %\includegraphics[width=0.8\linewidth]{name.ext}
- \begin{tikzpicture}[scale=1, transform shape]
- \node (img1) [yshift=0cm, xshift=0cm, rotate=0] {\includegraphics[width=0.7\linewidth]{folder_modify.png}};
- \node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Arrow1) {\parbox{8em}{Here is the filter that was generated with the original drop }};
- \node [yshift=-65mm, xshift=0cm,anchor=east] at (img1.north west) (Arrow2) {\parbox{10em}{When you click on the Value portion of that filter, the entire set of files that are covered by the filter rules pops up. Now you can highlight a target filename that you would like to remove, and just erase that line and check the green checkmark for OK.}};
- \draw [->, line width=1mm] (Arrow1) edge ([yshift=-20mm] img1.north west);
- \end{tikzpicture}
-
- \caption{Modify target}
- \label{fig:modify-target}
+ \centering
+ %\includegraphics[width=0.8\linewidth]{name.ext}
+ \begin{tikzpicture}[scale=1, transform shape]
+ \node (img1) [yshift=0cm, xshift=0cm, rotate=0] {\includegraphics[width=0.7\linewidth]{folder_modify.png}};
+ \node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Arrow1) {\parbox{8em}{Here is the filter that was generated with the original drop }};
+ \draw [->, line width=1mm] (Arrow1) edge ([yshift=-20mm] img1.north west);
+ \end{tikzpicture}
+
+ \caption{Modify Folder}
+ \label{fig:modify-target}
\end{figure}
-To delete the entire set of files listed on the filter rule, highlight the rule line and hit the \textit{Del} button.
+\paragraph{Filters:} you do automatic populating using filters (Smart Bins mode). You set the values of the \texttt{Enabled}; \texttt{Target}; \texttt{Op} and \texttt{Value} fields to make up the required filtering. The folder will populate automatically by pulling from the \texttt{Media} master folder. The filter is the result of one row, but we can do more sophisticated filtering by adding more rows. The process will start from the first row propagating to subsequent rows always following the pattern from top to bottom. See figure~\ref{fig:modify_folder}.
+
+\begin{figure}[htpb]
+ \centering
+ %\includegraphics[width=0.8\linewidth]{name.ext}
+ \begin{tikzpicture}[scale=1, transform shape]
+ \node (img1) [yshift=0cm, xshift=0cm, rotate=0] {\includegraphics[width=0.8\linewidth]{modify_folder1.png}};
+ \node (img2) [yshift=-1cm, xshift=3.5cm, rotate=0] at (img1) {\includegraphics[width=0.8\linewidth]{modify_folder2.png}};
+ \node (img3) [yshift=-1cm, xshift=3cm, rotate=0] at (img2){\includegraphics[width=0.5\linewidth]{modify_folder3.png}};
+ \end{tikzpicture}
+ \caption{The available choices for each field. Value field missing.}
+ \label{fig:modify_folder}
+\end{figure}
+
+Let's look in detail at all the options of Modify Folder.
+
+When you bring up the Modify folder window, if you already have files in that folder, you will see filters that were generated automatically when you did a Drag and Drop. See figure~\ref{fig:modify-target}.
+
+When you click on the \textit{Value} portion of that filter, the entire set of files that are covered by the filter rules pops up. Now you can highlight a target filename that you would like to remove, and just erase that line and check the green checkmark for OK.
+
+To delete the entire set of files listed on the filter rule, highlight the rule line and hit the \textit{Del} button.
+
To add a new filter rule, click on the \textit{Add} button which will automatically add a default line after any current lines.
-The default line will be a line that matches everything in the \textit{master} Media folder which is \textit{Or Patterns Matches *}.
+The default line will be a line that matches everything in the master Media folder which is \textit{Or Patterns Matches *}.
Click the right mouse button on the current field underneath the column header to see the choices available for each column.
-Modifications will not be in effect until you click on the green arrow OK button or click on the Apply button.
+Modifications will not be in effect until you click on the green arrow \textit{OK} button or click on the \textit{Apply} button.
But once you hit Apply, clicking on the red X button will not undo your changes.
The filter/search rules are applied in the order listed in the Modify folder window.
You can change the order of the filter rules by highlighting the rule you want to move and then drag and drop to a new location.
-The figure~\ref{fig:modify_folder} below displays the available choices for each field.
-
-\begin{figure}[htpb]
- \centering
- %\includegraphics[width=0.8\linewidth]{name.ext}
- \begin{tikzpicture}[scale=1, transform shape]
- \node (img1) [yshift=0cm, xshift=0cm, rotate=0] {\includegraphics[width=0.8\linewidth]{modify_folder1.png}};
- \node (img2) [yshift=-1cm, xshift=3.5cm, rotate=0] at (img1) {\includegraphics[width=0.8\linewidth]{modify_folder2.png}};
- \node (img3) [yshift=-1cm, xshift=3cm, rotate=0] at (img2){\includegraphics[width=0.5\linewidth]{modify_folder3.png}};
- \end{tikzpicture}
- \caption{The available choices for each field}
- \label{fig:modify_folder}
-\end{figure}
-
Information about the columns and rules for the search filters in the Modify folder window follows \index{folder add filter/search}.
Column headers:
\begin{description}
-\item[ Enable] this column is used to designate the state of that filter rule
+\item[\textcolor{CinBlueText}{Enable}] – this column is used to designate the state of that filter rule
\begin{description}
- \item[ Off] disable the filter
+ \item[Off] disable the filter
\item[And] narrow your search; all of your search terms must be present
\item[Or] broaden your search to include more values
\item[And Not] exclude terms that do not contain the given value from your search results
\item[Or Not] include terms that do not contain the given value from your search results
\end{description}
-\item [Target] – this column designates which media asset attribute to look at
+\item [\textcolor{CinBlueText}{Target}] – this column designates which media asset attribute to look at
\begin{description}
- \item[ Patterns] each line contains a filename filter, matches the file path
+ \item[Patterns] each line contains a filename filter, matches the file path
\item[Filesize] number of bytes in a file
\item[Time] date file was created
\item[Track Type] track type of video, audio, or audio video (for both)
\item[Channels] Number of audio channels
\item[Duration] Playback time in seconds -- it uses the largest of audio or video if contains both
\end{description}
-\item[Op] – boolean operators used to narrow or broaden the relationship between your search terms
+\item[\textcolor{CinBlueText}{Op}] – boolean operators used to narrow or broaden the relationship between your search terms
\begin{description}
\item[Around] about this value; use \textit{+radius} for a search range: [target–radius$\dots$ target+radius]
\item[Eq ] equal to
\end{description}
\end{description}
-\textbf{Value} --- the characteristic you are looking for with expressions that can be written with the following:
+\textbf{\textcolor{CinBlueText}{Value}} --- the characteristic you are looking for with expressions that can be written with the following:
-\begin{description}
-\item[Number] (decimal points are allowed and will be converted to a standard form):
- \begin{description}
- \item[inf] representing infinity
- \item[\#[TtGgMmKk]] --- where \# represents a number and the characters mean:
- \end{description}
+ \begin{description}
+ \item[Number] (decimal points are allowed and will be converted to a standard form):
+ \begin{description}
+ \item[inf] representing infinity
+ \item[\#[TtGgMmKk]] --- where \# represents a number and the characters mean:
+ \end{description}
\begin{tabular}{rcl}
inf&=& infinity\\
Table showing the allowed usage:
-%TODO create table for below code
\begin{lstlisting}[numbers=none]
target: | eq ge gt ne le lt matches around
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\item Sort is by filename base name (directory path not included automatically) except when the \textit{Around} operation is used and then it is sorted by that Target distance first and then filename.
\end{enumerate}
-\begin{table}[htpb]
- \centering
- \caption{Examples}
- \label{tab:label}
- \small
- \begin{tabular}{lllm{10em}m{10em}} \toprule
- Enable& Target& Op& Value& meaning\\\midrule
-Or &Patterns &Matches &*& all files from the Media folder are included\\
-And Not&Filesize&Lt &160000000& no files that are less than 160MB in size \\
-Or Not& Time &Ge &2018/07/30 06:13:00 & files not greater than or equal date\\
-And &Duration&Eq &01:00 & files included must have 60 secs. Duration\\
-Off &Samplerate&Ne &44000 & off for now, but may want to include later\\
-And &Framerate&Around&24+1 & files included all have 24 to 25 framerate\\
-Or &Patterns&Matches&[*.mp4] & all files with the extension of mp4\\
-Or &Time& Around&2018/08/02 06:00:00 + 02:00:00 & files at 4AM to 8 AM\\\bottomrule
- \end{tabular}
-\end{table}
-
+\begin{longtable}{lllm{10em}m{10em}}
+ \caption{Examples}
+ \label{tab:label}\\
+ \toprule
+ \textbf{Enable} & \textbf{Target} & \textbf{OP} & \textbf{Value} & \textbf{meaning} \\
+ \hline
+ %begin{latexonly}
+ \endhead
+ %end{latexonly}
+ Or & Patterns & Matches & * & all files from the Media Folder are included \\
+ And Not & Filesize & Lt & 160000000 & no files that are less than 160MB in size \\
+ Or Not & Time & Ge & 2018/07/30 06:13:00 & files not greater than or equal date \\
+ And & Duration & Eq & 01:00 & files included must have 60 secs. Duration \\
+ Off & Samplerate & Ne & 44000 & off for now, but may want to include later \\
+ And & Framerate & Around & 24+1 & files included all have 24 to 25 framerate \\
+ Or & Patterns & Matches & [*.mp4] & all files with the extension of mp4 \\
+ Or & Time & Around & 2018/08/02 06:00:00 + 02:00:00 & files at 4 AM to 8 AM \\
+ \bottomrule
+\end{longtable}
\subsection{Vicons \& Aicons – aka Video Icons / Audio Icons}%
\label{sub:vicons_aicons_aka_video_icons_audio_icons}
In other words, a lot of media does not begin at the \textit{beginning} point and will not be properly rendered until enough data has been read to assemble a picture.
You can increase the thumbnail size, clarity of pixels (memory size) and color mode but it takes a lot more memory.
Change these values in \texttt{Settings $\rightarrow$ Preferences}, Appearance tab, right hand side of the Layout section -- be aware that when you click OK, your session will re-initialize.
-You can also temporarily increase the preview mini-window by use of the mouse wheel up or down.
+You can also temporarily increase the preview mini-window by use of the mouse wheel up or down for media but not for clips.
There are 4 options for the preview mode.
projects / goodguy / cin-manual-latex.git / commitdiff
