--- /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
\include{parts/Developer}
\include{parts/AuxilaryPrograms}
\include{parts/Real-World}
+\include{parts/Faq}
\end{appendices}
\pagestyle{plain}
\listoffigures
\newpage
+\printindex
+
% \listoftodos
\end{document}
--- /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} % Подключение русифицированных
%\usepackage{tocvsec2}
\usepackage[intoc]{nomencl} % glossary package
\makenomenclature% make glossary
+\usepackage{makeidx}
+\makeindex
% eso-pic makes it easy to add some picture commands to every page
% at absolute positions:
% Switch to sans serif (usually these do not contain SC):
% \renewcommand*\familydefault{\sfdefault}
+% The necessary package for LaTeX2HTML
+\usepackage{html}
+% html.sty declares its own \hyperref - redefinition hack required
+\renewcommand{\hyperref}[2][]{\hyperrefhyper[#1]{#2}}
%%% Local Variables:
%%% mode: latex
%\renewcommand{\@pnumwidth}{3em} % memoir class, more space between chapter number and text.
\setlength{\cftfigurenumwidth}{4em} % memoir class, more space between figure number and text.
\setlength{\cftsectionnumwidth}{2.7em} % memoir class, more space between section number and text
-\setlength{\cftsubsectionnumwidth}{3.6em} % memoir class, more space between subsection number and text
+\setlength{\cftsubsectionnumwidth}{4.2em} % memoir class, more space between subsection number and text
\renewcommand{\nomname}{Glossary} % glossary name
% realized with eso-pic as background image.
%
\thispagestyle{empty}
+%begin{latexonly}
\newcommand\CinBackgroundLogo{%
\put(0,0){%
\parbox[b][\paperheight]{\paperwidth}{%
% Use the logo
\AddToShipoutPicture{\CinBackgroundLogo}
+%end{latexonly}
+\htmladdimg{cin-big.png}
% Place the title over the "black hole".
% The position must be set appropriately.
+%begin{latexonly}
\vspace*{14.5cm}
+%end{latexonly}
\begin{minipage}[t]{80mm}
\textcolor{CinBlue}{\textsf{\Huge{The Comprehensive}}}\\[1em]
\textcolor{CinBlue}{\textsf{\Huge{\textbf{User Manual}}}}
% The following is an example that needs to be adapted to the
% respective conditions.
%
-Maintained and published by Phyllis Smith\\[+1.2em]
-Copyright~\copyright{} 2020 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
% Translation: Translator
\bigskip%
+%begin{latexonly}
\footnotesize
+%end{latexonly}
\subsubsection*{\sffamily{}Legal information}
\label{sec:Legal-information}
This manual adheres to the GNU FDL (GFDL) copyleft license for free documentation,
--- /dev/null
+%
+% $Id: html.sty,v 1.39 2001/10/01 22:47:06 RRM Exp $
+% LaTeX2HTML Version 2K.1 : html.sty
+%
+% This file contains definitions of LaTeX commands which are
+% processed in a special way by the translator.
+% For example, there are commands for embedding external hypertext links,
+% for cross-references between documents or for including raw HTML.
+% This file includes the comments.sty file v2.0 by Victor Eijkhout
+% In most cases these commands do nothing when processed by LaTeX.
+%
+% Place this file in a directory accessible to LaTeX (i.e., somewhere
+% in the TEXINPUTS path.)
+%
+% NOTE: This file works with LaTeX 2.09 or (the newer) LaTeX2e.
+% If you only have LaTeX 2.09, some complex LaTeX2HTML features
+% like support for segmented documents are not available.
+
+% Changes:
+% See the change log at end of file.
+
+
+% Exit if the style file is already loaded
+% (suggested by Lee Shombert <las@potomac.wash.inmet.com>
+\ifx \htmlstyloaded\relax \endinput\else\let\htmlstyloaded\relax\fi
+\makeatletter
+
+% allow for the hyperref package to be cleanly loaded
+% either before or after this package,
+% and ensure it is already loaded, when using pdf-TeX
+
+\ifx\undefined\hyperref
+ \ifx\pdfoutput\undefined \let\pdfunknown\relax
+ \let\html@new=\newcommand
+ \else
+ \ifx\pdfoutput\relax \let\pdfunknown\relax
+ \RequirePackage{hyperref}\let\html@new=\renewcommand
+ \else
+ \ifcase\pdfoutput
+ \let\pdfunknown\relax \let\html@new=\newcommand
+ \else
+ \RequirePackage[pdftex]{hyperref}\let\html@new=\newcommand
+ \fi
+
+ \fi
+ \fi
+\else
+ \let\html@new=\renewcommand
+\fi
+
+\providecommand{\latextohtml}{\LaTeX2\texttt{HTML}}
+
+%%% LINKS TO EXTERNAL DOCUMENTS
+%
+% This can be used to provide links to arbitrary documents.
+% The first argumment should be the text that is going to be
+% highlighted and the second argument a URL.
+% The hyperlink will appear as a hyperlink in the HTML
+% document and as a footnote in the dvi or ps files.
+%
+\ifx\pdfunknown\relax
+ \html@new{\htmladdnormallinkfoot}[2]{#1\footnote{#2}}
+\else
+ \def\htmladdnormallinkfoot#1#2{\footnote{\href{#2}{#1}}}
+\fi
+
+% This is an alternative definition of the command above which
+% will ignore the URL in the dvi or ps files.
+\ifx\pdfunknown\relax
+ \html@new{\htmladdnormallink}[2]{#1}
+\else
+ \def\htmladdnormallink#1#2{\href{#2}{#1}}
+\fi
+
+% This command takes as argument a URL pointing to an image.
+% The image will be embedded in the HTML document but will
+% be ignored in the dvi and ps files.
+%
+\ifx\pdfunknown\relax
+ \html@new{\htmladdimg}[1]{}
+\else
+ \def\htmladdimg#1{\hyperimage{#1}}
+\fi
+
+
+%%% CROSS-REFERENCES BETWEEN (LOCAL OR REMOTE) DOCUMENTS
+%
+% This can be used to refer to symbolic labels in other Latex
+% documents that have already been processed by the translator.
+% The arguments should be:
+% #1 : the URL to the directory containing the external document
+% #2 : the path to the labels.pl file of the external document.
+% If the external document lives on a remote machine then labels.pl
+% must be copied on the local machine.
+%
+%e.g. \externallabels{http://cbl.leeds.ac.uk/nikos/WWW/doc/tex2html/latex2html}
+% {/usr/cblelca/nikos/tmp/labels.pl}
+% The arguments are ignored in the dvi and ps files.
+%
+\newcommand{\externallabels}[2]{}
+
+
+% This complements the \externallabels command above. The argument
+% should be a label defined in another latex document and will be
+% ignored in the dvi and ps files.
+%
+\newcommand{\externalref}[1]{}
+
+
+% Suggested by Uffe Engberg (http://www.brics.dk/~engberg/)
+% This allows the same effect for citations in external bibliographies.
+% An \externallabels command must be given, locating a labels.pl file
+% which defines the location and keys used in the external .html file.
+%
+\newcommand{\externalcite}{\nocite}
+
+% This allows a section-heading in the TOC or mini-TOC to be just
+% a hyperlink to an external document.
+%
+% \htmladdTOClink[<path_to_labels>]{<section-level>}{<title>}{<URL>}
+% where <section-level> is 'chapter' , 'section' , 'subsection' etc.
+% and <path_to_labels> is the path to find a labels.pl file,
+% so that external cross-referencing may work, as with \externallabels
+%
+%\ifx\pdfunknown\relax
+ \newcommand{\htmladdTOClink}[4][]{}
+%
+% can do something here, using the \pdfoutline primitive
+%\else
+% \def\htmladdTOClink#1#2#3#4{\pdfoutline user {/S /URI /URI #4}
+% name{#2} count{#1}{#3}}
+%\fi
+
+
+%%% HTMLRULE
+% This command adds a horizontal rule and is valid even within
+% a figure caption.
+% Here we introduce a stub for compatibility.
+\newcommand{\htmlrule}{\protect\HTMLrule}
+\newcommand{\HTMLrule}{\@ifstar\htmlrulestar\htmlrulestar}
+\newcommand{\htmlrulestar}[1]{}
+
+%%% HTMLCLEAR
+% This command puts in a <BR> tag, with CLEAR="ALL"
+\newcommand{\htmlclear}{}
+
+% This command adds information within the <BODY> ... </BODY> tag
+%
+\newcommand{\bodytext}[1]{}
+\newcommand{\htmlbody}{}
+
+
+%%% HYPERREF
+% Suggested by Eric M. Carol <eric@ca.utoronto.utcc.enfm>
+% Similar to \ref but accepts conditional text.
+% The first argument is HTML text which will become ``hyperized''
+% (underlined).
+% The second and third arguments are text which will appear only in the paper
+% version (DVI file), enclosing the fourth argument which is a reference to a label.
+%
+%e.g. \hyperref{using the tracer}{using the tracer (see Section}{)}{trace}
+% where there is a corresponding \label{trace}
+%
+% avoid possible confict with hyperref package
+\ifx\undefined\hyperref
+ \newcommand{\hyperrefhyper}[4]{#4}%
+ \def\next{\newcommand}%
+\else
+ \let\hyperrefhyper\hyperref
+ \def\next{\renewcommand}%
+\fi
+\next{\hyperref}{\hyperrefi[]}\let\next=\relax
+
+\def\hyperrefi[#1]{{\def\next{#1}\def\tmp{}%
+ \ifx\next\tmp\aftergroup\hyperrefdef
+ \else\def\tmp{ref}\ifx\next\tmp\aftergroup\hyperrefref
+ \else\def\tmp{pageref}\ifx\next\tmp\aftergroup\hyperrefpageref
+ \else\def\tmp{page}\ifx\next\tmp\aftergroup\hyperrefpage
+ \else\def\tmp{noref}\ifx\next\tmp\aftergroup\hyperrefnoref
+ \else\def\tmp{no}\ifx\next\tmp\aftergroup\hyperrefno
+ \else\def\tmp{hyper}\ifx\next\tmp\aftergroup\hyperrefhyper
+ \else\def\tmp{html}\ifx\next\tmp\aftergroup\hyperrefhtml
+ \else\typeout{*** unknown option \next\space to hyperref ***}%
+ \fi\fi\fi\fi\fi\fi\fi\fi}}
+\newcommand{\hyperrefdef}[4]{#2\ref{#4}#3}
+\newcommand{\hyperrefpageref}[4]{#2\pageref{#4}#3}
+\newcommand{\hyperrefnoref}[3]{#2}
+\let\hyperrefref=\hyperrefdef
+\let\hyperrefpage=\hyperrefpageref
+\let\hyperrefno=\hyperrefnoref
+\ifx\undefined\hyperrefhyper\newcommand{\hyperrefhyper}[4]{#4}\fi
+\let\hyperrefhtml=\hyperrefdef
+
+%%% HYPERCITE --- added by RRM
+% Suggested by Stephen Simpson <simpson@math.psu.edu>
+% effects the same ideas as in \hyperref, but for citations.
+% It does not allow an optional argument to the \cite, in LaTeX.
+%
+% \hypercite{<html-text>}{<LaTeX-text>}{<opt-text>}{<key>}
+%
+% uses the pre/post-texts in LaTeX, with a \cite{<key>}
+%
+% \hypercite[ext]{<html-text>}{<LaTeX-text>}{<key>}
+% \hypercite[ext]{<html-text>}{<LaTeX-text>}[<prefix>]{<key>}
+%
+% uses the pre/post-texts in LaTeX, with a \nocite{<key>}
+% the actual reference comes from an \externallabels file.
+%
+\newcommand{\hypercite}{\hypercitei[]}
+\def\hypercitei[#1]{{\def\next{#1}\def\tmp{}%
+ \ifx\next\tmp\aftergroup\hypercitedef
+ \else\def\tmp{int}\ifx\next\tmp\aftergroup\hyperciteint
+ \else\def\tmp{cite}\ifx\next\tmp\aftergroup\hypercitecite
+ \else\def\tmp{ext}\ifx\next\tmp\aftergroup\hyperciteext
+ \else\def\tmp{nocite}\ifx\next\tmp\aftergroup\hypercitenocite
+ \else\def\tmp{no}\ifx\next\tmp\aftergroup\hyperciteno
+ \else\typeout{*** unknown option \next\space to hypercite ***}%
+ \fi\fi\fi\fi\fi\fi}}
+\newcommand{\hypercitedef}[4]{#2{\def\tmp{#3}\def\emptyopt{}%
+ \ifx\tmp\emptyopt\cite{#4}\else\cite[#3]{#4}\fi}}
+\newcommand{\hypercitenocite}[2]{#2\hypercitenocitex[]}
+\def\hypercitenocitex[#1]#2{\nocite{#2}}
+\let\hypercitecite=\hypercitedef
+\let\hyperciteint=\hypercitedef
+\let\hyperciteext=\hypercitenocite
+\let\hyperciteno=\hypercitenocite
+
+%%% HTMLREF
+% Reference in HTML version only.
+% Mix between \htmladdnormallink and \hyperref.
+% First arg is text for in both versions, second is label for use in HTML
+% version.
+\ifx\pdfunknown\relax
+ \html@new{\htmlref}[2]{#1}
+\else
+ \def\htmlref#1#2{\hyperefhyper[#2]{#1}}
+\fi
+
+%%% HTMLCITE
+% Reference in HTML version only.
+% Mix between \htmladdnormallink and \hypercite.
+% First arg is text for both versions, second is citation for use in HTML
+% version.
+\newcommand{\htmlcite}[2]{#1}
+
+
+%%% HTMLIMAGE
+% This command can be used inside any environment that is converted
+% into an inlined image (eg a "figure" environment) in order to change
+% the way the image will be translated. The argument of \htmlimage
+% is really a string of options separated by commas ie
+% [scale=<scale factor>],[external],[thumbnail=<reduction factor>
+% The scale option allows control over the size of the final image.
+% The ``external'' option will cause the image not to be inlined
+% (images are inlined by default). External images will be accessible
+% via a hypertext link.
+% The ``thumbnail'' option will cause a small inlined image to be
+% placed in the caption. The size of the thumbnail depends on the
+% reduction factor. The use of the ``thumbnail'' option implies
+% the ``external'' option.
+%
+% Example:
+% \htmlimage{scale=1.5,external,thumbnail=0.2}
+% will cause a small thumbnail image 1/5th of the original size to be
+% placed in the final document, pointing to an external image 1.5
+% times bigger than the original.
+%
+\newcommand{\htmlimage}[1]{}
+
+
+% \htmlborder causes a border to be placed around an image or table
+% when the image is placed within a <TABLE> cell.
+\newcommand{\htmlborder}[1]{}
+
+% Put \begin{makeimage}, \end{makeimage} around LaTeX to ensure its
+% translation into an image.
+% This shields sensitive text from being translated.
+\newenvironment{makeimage}{}{}
+
+
+% A dummy environment that can be useful to alter the order
+% in which commands are processed, in LaTeX2HTML
+\newenvironment{tex2html_deferred}{}{}
+
+
+%%% HTMLADDTONAVIGATION
+% This command appends its argument to the buttons in the navigation
+% panel. It is ignored by LaTeX.
+%
+% Example:
+% \htmladdtonavigation{\htmladdnormallink
+% {\htmladdimg{http://server/path/to/gif}}
+% {http://server/path}}
+\newcommand{\htmladdtonavigation}[1]{}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% based upon Eijkhout's comment.sty v2.0
+% with modifications to avoid conflicts with later versions
+% of this package, should a user be requiring it.
+% Ross Moore, 10 March 1999
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Comment.sty version 2.0, 19 June 1992
+% selectively in/exclude pieces of text: the user can define new
+% comment versions, and each is controlled separately.
+% This style can be used with plain TeX or LaTeX, and probably
+% most other packages too.
+%
+% Examples of use in LaTeX and TeX follow \endinput
+%
+% Author
+% Victor Eijkhout
+% Department of Computer Science
+% University Tennessee at Knoxville
+% 104 Ayres Hall
+% Knoxville, TN 37996
+% USA
+%
+% eijkhout@cs.utk.edu
+%
+% Usage: all text included in between
+% \comment ... \endcomment
+% or \begin{comment} ... \end{comment}
+% is discarded. The closing command should appear on a line
+% of its own. No starting spaces, nothing after it.
+% This environment should work with arbitrary amounts
+% of comment.
+%
+% Other 'comment' environments are defined by
+% and are selected/deselected with
+% \includecomment{versiona}
+% \excludecoment{versionb}
+%
+% These environments are used as
+% \versiona ... \endversiona
+% or \begin{versiona} ... \end{versiona}
+% with the closing command again on a line of its own.
+%
+% Basic approach:
+% to comment something out, scoop up every line in verbatim mode
+% as macro argument, then throw it away.
+% For inclusions, both the opening and closing comands
+% are defined as noop
+%
+% Changed \next to \html@next to prevent clashes with other sty files
+% (mike@emn.fr)
+% Changed \html@next to \htmlnext so the \makeatletter and
+% \makeatother commands could be removed (they were causing other
+% style files - changebar.sty - to crash) (nikos@cbl.leeds.ac.uk)
+% Changed \htmlnext back to \html@next...
+
+\def\makeinnocent#1{\catcode`#1=12 }
+\def\csarg#1#2{\expandafter#1\csname#2\endcsname}
+
+\def\ThrowAwayComment#1{\begingroup
+ \def\CurrentComment{#1}%
+ \let\do\makeinnocent \dospecials
+ \makeinnocent\^^L% and whatever other special cases
+%%RRM
+%% use \xhtmlComment for \xComment
+%% use \html@next for \next
+ \endlinechar`\^^M \catcode`\^^M=12 \xhtmlComment}
+{\catcode`\^^M=12 \endlinechar=-1 %
+ \gdef\xhtmlComment#1^^M{\def\test{#1}\edef\test{\meaning\test}
+ \csarg\ifx{PlainEnd\CurrentComment Test}\test
+ \let\html@next\endgroup
+ \else \csarg\ifx{LaLaEnd\CurrentComment Test}\test
+ \edef\html@next{\endgroup\noexpand\end{\CurrentComment}}
+ \else \csarg\ifx{LaInnEnd\CurrentComment Test}\test
+ \edef\html@next{\endgroup\noexpand\end{\CurrentComment}}
+ \else \let\html@next\xhtmlComment
+ \fi \fi \fi \html@next}
+}
+
+%%\def\includecomment %%RRM
+\def\htmlincludecomment
+ #1{\expandafter\def\csname#1\endcsname{}%
+ \expandafter\def\csname end#1\endcsname{}}
+%%\def\excludecomment %%RRM
+\def\htmlexcludecomment
+ #1{\expandafter\def\csname#1\endcsname{\ThrowAwayComment{#1}}%
+ {\escapechar=-1\relax
+ \edef\tmp{\string\\end#1}%
+ \csarg\xdef{PlainEnd#1Test}{\meaning\tmp}%
+ \edef\tmp{\string\\end\string\{#1\string\}}%
+ \csarg\xdef{LaLaEnd#1Test}{\meaning\tmp}%
+ \edef\tmp{\string\\end \string\{#1\string\}}%
+ \csarg\xdef{LaInnEnd#1Test}{\meaning\tmp}%
+ }}
+
+%%\excludecomment{comment} %%RRM
+\htmlexcludecomment{comment}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% end Comment.sty
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\let\includecomment=\htmlincludecomment
+\let\excludecomment=\htmlexcludecomment
+
+%
+% Alternative code by Robin Fairbairns, 22 September 1997
+% revised to cope with % and unnested { }, by Ross Moore, 4 July 1998
+% further revised to cope with & and # in tables, 10 March 1999
+%
+\def\raw@catcodes{\catcode`\%=12 \catcode`\{=12 \catcode`\}=12
+ \catcode`\&=12 \catcode`\#=12 }
+\newcommand\@gobbleenv{\bgroup\raw@catcodes
+ \let\reserved@a\@currenvir\@gobble@nv}
+\bgroup
+ \def\expansionhead{\gdef\@gobble@nv@i##1}
+ \def\expansiontail{{\def\reserved@b{##1}\@gobble@nv@ii}}
+ \def\expansionheadii{\long\gdef\@gobble@nv##1\end}
+ \def\expansiontailii{{\@gobble@nv@i}}
+ \def\expansionmidii{##2}
+ \raw@catcodes\relax
+ \expandafter\expansionhead\expandafter}\expansiontail
+\egroup
+\long\gdef\@gobble@nv#1\end#2{\@gobble@nv@i}
+%\long\def\@gobble@nv#1\end#2{\def\reserved@b{#2}%
+\def\@gobble@nv@ii{%
+ \ifx\reserved@a\reserved@b
+ \edef\reserved@a{\egroup\noexpand\end{\reserved@a}}%
+ \expandafter\reserved@a
+ \else
+ \expandafter\@gobble@nv
+ \fi}
+
+\renewcommand{\htmlexcludecomment}[1]{%
+ \csname newenvironment\endcsname{#1}{\@gobbleenv}{}}
+\newcommand{\htmlreexcludecomment}[1]{%
+ \csname renewenvironment\endcsname{#1}{\@gobbleenv}{}}
+
+%%% RAW HTML
+%
+% Enclose raw HTML between a \begin{rawhtml} and \end{rawhtml}.
+% The html environment ignores its body
+%
+\htmlexcludecomment{rawhtml}
+
+
+%%% HTML ONLY
+%
+% Enclose LaTeX constructs which will only appear in the
+% HTML output and will be ignored by LaTeX with
+% \begin{htmlonly} and \end{htmlonly}
+%
+\htmlexcludecomment{htmlonly}
+% Shorter version
+\newcommand{\html}[1]{}
+
+% for images.tex only
+\htmlexcludecomment{imagesonly}
+
+%%% LaTeX ONLY
+% Enclose LaTeX constructs which will only appear in the
+% DVI output and will be ignored by latex2html with
+%\begin{latexonly} and \end{latexonly}
+%
+\newenvironment{latexonly}{}{}
+% Shorter version
+\newcommand{\latex}[1]{#1}
+
+
+%%% LaTeX or HTML
+% Combination of \latex and \html.
+% Say \latexhtml{this should be latex text}{this html text}
+%
+%\newcommand{\latexhtml}[2]{#1}
+\long\def\latexhtml#1#2{#1}
+
+
+%%% tracing the HTML conversions
+% This alters the tracing-level within the processing
+% performed by latex2html by adjusting $VERBOSITY
+% (see latex2html.config for the appropriate values)
+%
+\newcommand{\htmltracing}[1]{}
+\newcommand{\htmltracenv}[1]{}
+
+
+%%% \strikeout for HTML only
+% uses <STRIKE>...</STRIKE> tags on the argument
+% LaTeX just gobbles it up.
+\newcommand{\strikeout}[1]{}
+
+%%% \htmlurl and \url
+% implement \url as the simplest thing, if not already defined
+% let \htmlurl#1 be equivalent to it
+%
+\def\htmlurlx#1{\begin{small}\texttt{#1}\end{small}}%
+\expandafter\ifx\csname url\endcsname\relax
+ \let\htmlurl=\htmlurlx \else \let\htmlurl=\url \fi
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% JCL - stop input here if LaTeX2e is not present
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\ifx\if@compatibility\undefined
+ %LaTeX209
+ \makeatother\relax\expandafter\endinput
+\fi
+\if@compatibility
+ %LaTeX2e in LaTeX209 compatibility mode
+ \makeatother\relax\expandafter\endinput
+\fi
+
+%\let\real@TeXlogo = \TeX
+%\DeclareRobustCommand{\TeX}{\relax\real@TeXlogo}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% Start providing LaTeX2e extension:
+% This is currently:
+% - additional optional argument for \htmladdimg
+% - support for segmented documents
+%
+
+\ProvidesPackage{html}
+ [1999/07/19 v1.38 hypertext commands for latex2html (nd, hws, rrm)]
+
+%
+% Ensure that \includecomment and \excludecomment are bound
+% to the version defined here.
+%
+\AtBeginDocument{%
+ \let\includecomment=\htmlincludecomment
+ \let\excludecomment=\htmlexcludecomment
+ \htmlreexcludecomment{comment}}
+
+%%% bind \htmlurl to \url if that is later loaded
+%
+\expandafter\ifx\csname url\endcsname\relax
+ \AtBeginDocument{\@ifundefined{url}{}{\let\htmlurl=\url}}\fi
+
+%%%%MG
+
+% This command takes as argument a URL pointing to an image.
+% The image will be embedded in the HTML document but will
+% be ignored in the dvi and ps files. The optional argument
+% denotes additional HTML tags.
+%
+% Example: \htmladdimg[ALT="portrait" ALIGN=CENTER]{portrait.gif}
+%
+\ifx\pdfunknown\relax
+ \renewcommand{\htmladdimg}[2][]{}
+\else
+ \renewcommand{\htmladdimg}[2][]{\hyperimage{#2}}
+\fi
+
+%%% HTMLRULE for LaTeX2e
+% This command adds a horizontal rule and is valid even within
+% a figure caption.
+%
+% This command is best used with LaTeX2e and HTML 3.2 support.
+% It is like \hrule, but allows for options via key--value pairs
+% as follows: \htmlrule[key1=value1, key2=value2, ...] .
+% Use \htmlrule* to suppress the <BR> tag.
+% Eg. \htmlrule[left, 15, 5pt, "none", NOSHADE] produces
+% <BR CLEAR="left"><HR NOSHADE SIZE="15">.
+% Renew the necessary part.
+\renewcommand{\htmlrulestar}[1][all]{}
+
+%%% HTMLCLEAR for LaTeX2e
+% This command puts in a <BR> tag, with optional CLEAR="<attrib>"
+%
+\renewcommand{\htmlclear}[1][all]{}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% renew some definitions to allow optional arguments
+%
+% The description of the options is missing, as yet.
+%
+\renewcommand{\latextohtml}{\textup{\LaTeX2\texttt{HTML}}}
+\ifx\pdfunknown\relax
+ \renewcommand{\htmladdnormallinkfoot}[3][]{#2\footnote{#3}}
+ \renewcommand{\htmladdnormallink}[3][]{#2}
+\else
+ \renewcommand{\htmladdnormallinkfoot}[1][]{\def\next{#1}%
+ \ifx\next\@empty\def\next{\htmladdnonamedlinkfoot}%
+ \else\def\next{\htmladdnamedlinkfoot{#1}}\fi \next}
+ \newcommand{\htmladdnonamedlinkfoot}[2]{%
+ #1\footnote{\href{#2}{#2}}}
+ \newcommand{\htmladdnamedlinkfoot}[3]{%
+ \hypertarget{#1}{#2}\footnote{\href{#3}{#3}}}
+ \renewcommand{\htmladdnormallink}[1][]{\def\next{#1}%
+ \ifx\next\@empty\def\next{\htmladdnonamedlink}%
+ \else\def\next{\htmladdnamedlink{#1}}\fi \next}
+ \newcommand{\htmladdnonamedlink}[2]{\href{#2}{#1}}
+ \newcommand{\htmladdnamedlink}[3]{%
+ \hypertarget{#1}{\hskip2bp}\href{#3}{#2}}
+\fi
+
+\renewcommand{\htmlbody}[1][]{}
+\renewcommand{\htmlborder}[2][]{}
+\renewcommand{\externallabels}[3][]{}
+\renewcommand{\externalref}[2][]{}
+\renewcommand{\externalcite}[1][]{\nocite}
+\renewcommand{\hyperref}[1][]{\hyperrefi[#1]}
+\renewcommand{\hypercite}[1][]{\hypercitei[#1]}
+\renewcommand{\hypercitenocite}[2]{#2\hypercitenocitex}
+\renewcommand{\hypercitenocitex}[2][]{\nocite{#2}}
+\let\hyperciteno=\hypercitenocite
+\let\hyperciteext=\hypercitenocite
+
+\ifx\pdfunknown\relax
+ \renewcommand{\htmlimage}[2][]{}
+ \renewcommand{\htmlref}[2][]{#2{\def\tmp{#1}\ifx\tmp\@empty
+ \aftergroup\htmlrefdef\else\aftergroup\htmlrefext\fi}}
+ \newcommand{\htmlrefdef}[1]{}
+ \newcommand{\htmlrefext}[2][]{}
+ \renewcommand{\htmlcite}[2][]{#2{\def\tmp{#1}\ifx\tmp\@empty
+ \aftergroup\htmlcitedef\else\aftergroup\htmlciteext\fi}}
+ \newcommand{\htmlciteext}[2][]{}
+\else
+ \renewcommand{\htmlimage}[2][]{\hyperimage{#2}}
+ \renewcommand{\htmlref}[1][]{\def\htmp@{#1}\ifx\htmp@\@empty
+ \def\htmp@{\htmlrefdef}\else\def\htmp@{\htmlrefext{#1}}\fi\htmp@}
+ \newcommand{\htmlrefdef}[2]{\hyperref[hyper][#2]{#1}}
+ \newcommand{\htmlrefext}[3]{%
+ \hypertarget{#1}{\hskip2bp}\hyperref[hyper][#3]{#2}}
+ \renewcommand{\htmlcite}[2][]{#2{\def\htmp@{#1}\ifx\htmp@\@empty
+ \aftergroup\htmlcitedef\else\aftergroup\htmlciteext\fi}}
+ \newcommand{\htmlciteext}[1][]{\cite}
+\fi
+\newcommand{\htmlcitedef}[1]{ \nocite{#1}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% HTML HTMLset HTMLsetenv
+%
+% These commands do nothing in LaTeX, but can be used to place
+% HTML tags or set Perl variables during the LaTeX2HTML processing;
+% They are intended for expert use only.
+
+\newcommand{\HTMLcode}[2][]{}
+\ifx\undefined\HTML\newcommand{\HTML}[2][]{}\else
+\typeout{*** Warning: \string\HTML\space had an incompatible definition ***}%
+\typeout{*** instead use \string\HTMLcode\space for raw HTML code ***}%
+\fi
+\newcommand{\HTMLset}[3][]{}
+\newcommand{\HTMLsetenv}[3][]{}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% The following commands pertain to document segmentation, and
+% were added by Herbert Swan <dprhws@edp.Arco.com> (with help from
+% Michel Goossens <goossens@cern.ch>):
+%
+%
+% This command inputs internal latex2html tables so that large
+% documents can to partitioned into smaller (more manageable)
+% segments.
+%
+\newcommand{\internal}[2][internals]{}
+
+%
+% Define a dummy stub \htmlhead{}. This command causes latex2html
+% to define the title of the start of a new segment. It is not
+% normally placed in the user's document. Rather, it is passed to
+% latex2html via a .ptr file written by \segment.
+%
+\newcommand{\htmlhead}[3][]{}
+
+% In the LaTeX2HTML version this will eliminate the title line
+% generated by a \segment command, but retains the title string
+% for use in other places.
+%
+\newcommand{\htmlnohead}{}
+
+
+% In the LaTeX2HTML version this put a URL into a <BASE> tag
+% within the <HEAD>...</HEAD> portion of a document.
+%
+\ifx\pdfunknown\relax
+ \newcommand{\htmlbase}[1]{}
+\else
+ \let\htmlbase=\hyperbaseurl
+\fi
+
+
+% Include style information into the stylesheet; e.g. CSS
+%
+\newcommand{\htmlsetstyle}[3][]{}
+\newcommand{\htmladdtostyle}[3][]{}
+
+% Define a style-class for information in a particular language
+%
+\newcommand{\htmllanguagestyle}[2][]{}
+
+
+%
+% The dummy command \endpreamble is needed by latex2html to
+% mark the end of the preamble in document segments that do
+% not contain a \begin{document}
+%
+\newcommand{\startdocument}{}
+
+
+% \tableofchildlinks, \htmlinfo
+% by Ross Moore --- extensions dated 27 September 1997
+%
+% These do nothing in LaTeX but for LaTeX2HTML they mark
+% where the table of child-links and info-page should be placed,
+% when the user wants other than the default.
+% \tableofchildlinks % put mini-TOC at this location
+% \tableofchildlinks[off] % not on current page
+% \tableofchildlinks[none] % not on current and subsequent pages
+% \tableofchildlinks[on] % selectively on current page
+% \tableofchildlinks[all] % on current and all subsequent pages
+% \htmlinfo % put info-page at this location
+% \htmlinfo[off] % no info-page in current document
+% \htmlinfo[none] % no info-page in current document
+% *-versions omit the preceding <BR> tag.
+%
+\newcommand{\tableofchildlinks}{%
+ \@ifstar\tableofchildlinksstar\tableofchildlinksstar}
+\newcommand{\tableofchildlinksstar}[1][]{}
+
+\newcommand{\htmlinfo}{\@ifstar\htmlinfostar\htmlinfostar}
+\newcommand{\htmlinfostar}[1][]{}
+
+
+% This redefines \begin to allow for an optional argument
+% which is used by LaTeX2HTML to specify `style-sheet' information
+
+\let\realLaTeX@begin=\begin
+\renewcommand{\begin}[1][]{\realLaTeX@begin}
+
+
+%
+% Allocate a new set of section counters, which will get incremented
+% for "*" forms of sectioning commands, and for a few miscellaneous
+% commands.
+%
+
+\@ifundefined{c@part}{\newcounter{part}}{}%
+\newcounter{lpart}
+\newcounter{lchapter}[part]
+\@ifundefined{c@chapter}%
+ {\let\Hchapter\relax \newcounter{chapter}\let\thechapter\relax
+ \newcounter{lsection}[part]}%
+ {\let\Hchapter=\chapter \newcounter{lsection}[chapter]}
+\newcounter{lsubsection}[section]
+\newcounter{lsubsubsection}[subsection]
+\newcounter{lparagraph}[subsubsection]
+\newcounter{lsubparagraph}[paragraph]
+%\newcounter{lequation}
+
+%
+% Redefine "*" forms of sectioning commands to increment their
+% respective counters.
+%
+\let\Hpart=\part
+%\let\Hchapter=\chapter
+\let\Hsection=\section
+\let\Hsubsection=\subsection
+\let\Hsubsubsection=\subsubsection
+\let\Hparagraph=\paragraph
+\let\Hsubparagraph=\subparagraph
+\let\Hsubsubparagraph=\subsubparagraph
+
+\ifx\c@subparagraph\undefined
+ \newcounter{lsubsubparagraph}[lsubparagraph]
+\else
+ \newcounter{lsubsubparagraph}[subparagraph]
+\fi
+
+%
+% The following definitions are specific to LaTeX2e:
+% (They must be commented out for LaTeX 2.09)
+%
+\expandafter\ifx\csname part\endcsname\relax\else
+\renewcommand{\part}{\@ifstar{\stepcounter{lpart}%
+ \bgroup\def\tmp{*}\H@part}{\bgroup\def\tmp{}\H@part}}\fi
+\newcommand{\H@part}[1][]{\def\tmp@a{#1}\check@align
+ \expandafter\egroup\expandafter\Hpart\tmp}
+
+\ifx\Hchapter\relax\else
+ \def\chapter{\resetsections \@ifstar{\stepcounter{lchapter}%
+ \bgroup\def\tmp{*}\H@chapter}{\bgroup\def\tmp{}\H@chapter}}\fi
+\newcommand{\H@chapter}[1][]{\def\tmp@a{#1}\check@align
+ \expandafter\egroup\expandafter\Hchapter\tmp}
+
+\renewcommand{\section}{\resetsubsections
+ \@ifstar{\stepcounter{lsection}\bgroup\def\tmp{*}%
+ \H@section}{\bgroup\def\tmp{}\H@section}}
+\newcommand{\H@section}[1][]{\def\tmp@a{#1}\check@align
+ \expandafter\egroup\expandafter\Hsection\tmp}
+
+\renewcommand{\subsection}{\resetsubsubsections
+ \@ifstar{\stepcounter{lsubsection}\bgroup\def\tmp{*}%
+ \H@subsection}{\bgroup\def\tmp{}\H@subsection}}
+\newcommand{\H@subsection}[1][]{\def\tmp@a{#1}\check@align
+ \expandafter\egroup\expandafter\Hsubsection\tmp}
+
+\renewcommand{\subsubsection}{\resetparagraphs
+ \@ifstar{\stepcounter{lsubsubsection}\bgroup\def\tmp{*}%
+ \H@subsubsection}{\bgroup\def\tmp{}\H@subsubsection}}
+\newcommand{\H@subsubsection}[1][]{\def\tmp@a{#1}\check@align
+ \expandafter\egroup\expandafter\Hsubsubsection\tmp}
+
+\renewcommand{\paragraph}{\resetsubparagraphs
+ \@ifstar{\stepcounter{lparagraph}\bgroup\def\tmp{*}%
+ \H@paragraph}{\bgroup\def\tmp{}\H@paragraph}}
+\newcommand\H@paragraph[1][]{\def\tmp@a{#1}\check@align
+ \expandafter\egroup\expandafter\Hparagraph\tmp}
+
+\ifx\Hsubparagraph\relax\else\@ifundefined{subparagraph}{}{%
+\renewcommand{\subparagraph}{\resetsubsubparagraphs
+ \@ifstar{\stepcounter{lsubparagraph}\bgroup\def\tmp{*}%
+ \H@subparagraph}{\bgroup\def\tmp{}\H@subparagraph}}}\fi
+\newcommand\H@subparagraph[1][]{\def\tmp@a{#1}\check@align
+ \expandafter\egroup\expandafter\Hsubparagraph\tmp}
+
+\ifx\Hsubsubparagraph\relax\else\@ifundefined{subsubparagraph}{}{%
+\def\subsubparagraph{%
+ \@ifstar{\stepcounter{lsubsubparagraph}\bgroup\def\tmp{*}%
+ \H@subsubparagraph}{\bgroup\def\tmp{}\H@subsubparagraph}}}\fi
+\newcommand\H@subsubparagraph[1][]{\def\tmp@a{#1}\check@align
+ \expandafter\egroup\expandafter\Hsubsubparagraph\tmp}
+
+\def\check@align{\def\empty{}\ifx\tmp@a\empty
+ \else\def\tmp@b{center}\ifx\tmp@a\tmp@b\let\tmp@a\empty
+ \else\def\tmp@b{left}\ifx\tmp@a\tmp@b\let\tmp@a\empty
+ \else\def\tmp@b{right}\ifx\tmp@a\tmp@b\let\tmp@a\empty
+ \else\expandafter\def\expandafter\tmp@a\expandafter{\expandafter[\tmp@a]}%
+ \fi\fi\fi \def\empty{}\ifx\tmp\empty\let\tmp=\tmp@a \else
+ \expandafter\def\expandafter\tmp\expandafter{\expandafter*\tmp@a}%
+ \fi\fi}
+%
+\def\resetsections{\setcounter{section}{0}\setcounter{lsection}{0}%
+ \reset@dependents{section}\resetsubsections }
+\def\resetsubsections{\setcounter{subsection}{0}\setcounter{lsubsection}{0}%
+ \reset@dependents{subsection}\resetsubsubsections }
+\def\resetsubsubsections{\setcounter{subsubsection}{0}\setcounter{lsubsubsection}{0}%
+ \reset@dependents{subsubsection}\resetparagraphs }
+%
+\def\resetparagraphs{\setcounter{lparagraph}{0}\setcounter{lparagraph}{0}%
+ \reset@dependents{paragraph}\resetsubparagraphs }
+\def\resetsubparagraphs{\ifx\c@subparagraph\undefined\else
+ \setcounter{subparagraph}{0}\fi \setcounter{lsubparagraph}{0}%
+ \reset@dependents{subparagraph}\resetsubsubparagraphs }
+\def\resetsubsubparagraphs{\ifx\c@subsubparagraph\undefined\else
+ \setcounter{subsubparagraph}{0}\fi \setcounter{lsubsubparagraph}{0}}
+%
+\def\reset@dependents#1{\begingroup\let \@elt \@stpelt
+ \csname cl@#1\endcsname\endgroup}
+
+% ignore optional *-version of \tableofcontents
+\let\ltx@tableofcontents\tableofcontents
+\renewcommand{\tableofcontents}{%
+ \@ifstar\ltx@tableofcontents\ltx@tableofcontents}
+%
+%
+% Define a helper macro to dump a single \secounter command to a file.
+%
+\newcommand{\DumpPtr}[2]{%
+\count255=\csname c@#1\endcsname\relax\def\dummy{dummy}\def\tmp{#2}%
+\ifx\tmp\dummy\def\ctr{#1}\else
+ \def\ctr{#2}\advance\count255 by \csname c@#2\endcsname\relax\fi
+\immediate\write\ptrfile{%
+\noexpand\setcounter{\ctr}{\number\count255}}}
+%\expandafter\noexpand\expandafter\setcounter\expandafter{\ctr}{\number\count255}}}
+
+%
+% Define a helper macro to dump all counters to the file.
+% The value for each counter will be the sum of the l-counter
+% actual LaTeX section counter.
+% Also dump an \htmlhead{section-command}{section title} command
+% to the file.
+%
+\newwrite\ptrfile
+\def\DumpCounters#1#2#3#4{%
+\begingroup\let\protect=\noexpand
+\immediate\openout\ptrfile = #1.ptr
+\DumpPtr{part}{lpart}%
+\ifx\Hchapter\relax\else\DumpPtr{chapter}{lchapter}\fi
+\DumpPtr{section}{lsection}%
+\DumpPtr{subsection}{lsubsection}%
+\DumpPtr{subsubsection}{lsubsubsection}%
+\DumpPtr{paragraph}{lparagraph}%
+\DumpPtr{subparagraph}{lsubparagraph}%
+\DumpPtr{equation}{dummy}%
+\DumpPtr{footnote}{dummy}%
+\def\tmp{#4}\ifx\tmp\@empty
+\immediate\write\ptrfile{\noexpand\htmlhead{#2}{#3}}\else
+\immediate\write\ptrfile{\noexpand\htmlhead[#4]{#2}{#3}}\fi
+\dumpcitestatus \dumpcurrentcolor
+\immediate\closeout\ptrfile
+\endgroup }
+
+
+%% interface to natbib.sty
+
+\def\dumpcitestatus{}
+\def\loadcitestatus{\def\dumpcitestatus{%
+ \ifciteindex\immediate\write\ptrfile{\noexpand\citeindextrue}%
+ \else\immediate\write\ptrfile{\noexpand\citeindexfalse}\fi }%
+}
+\@ifpackageloaded{natbib}{\loadcitestatus}{%
+ \AtBeginDocument{\@ifpackageloaded{natbib}{\loadcitestatus}{}}}
+
+
+%% interface to color.sty
+
+\def\dumpcurrentcolor{}
+\def\loadsegmentcolors{%
+ \let\real@pagecolor=\pagecolor
+ \let\pagecolor\segmentpagecolor
+ \let\segmentcolor\color
+ \ifx\current@page@color\undefined \def\current@page@color{{}}\fi
+ \def\dumpcurrentcolor{\bgroup\def\@empty@{{}}%
+ \expandafter\def\expandafter\tmp\space####1@{\def\thiscol{####1}}%
+ \ifx\current@color\@empty@\def\thiscol{}\else
+ \expandafter\tmp\current@color @\fi
+ \immediate\write\ptrfile{\noexpand\segmentcolor{\thiscol}}%
+ \ifx\current@page@color\@empty@\def\thiscol{}\else
+ \expandafter\tmp\current@page@color @\fi
+ \immediate\write\ptrfile{\noexpand\segmentpagecolor{\thiscol}}%
+ \egroup}%
+ \global\let\loadsegmentcolors=\relax
+}
+
+% These macros are needed within images.tex since this inputs
+% the <segment>.ptr files for a segment, so that counters are
+% colors are synchronised.
+%
+\newcommand{\segmentpagecolor}[1][]{%
+ \@ifpackageloaded{color}{\loadsegmentcolors\bgroup
+ \def\tmp{#1}\ifx\@empty\tmp\def\next{[]}\else\def\next{[#1]}\fi
+ \expandafter\segmentpagecolor@\next}%
+ {\@gobble}}
+\def\segmentpagecolor@[#1]#2{\def\tmp{#1}\def\tmpB{#2}%
+ \ifx\tmpB\@empty\let\next=\egroup
+ \else
+ \let\realendgroup=\endgroup
+ \def\endgroup{\edef\next{\noexpand\realendgroup
+ \def\noexpand\current@page@color{\current@color}}\next}%
+ \ifx\tmp\@empty\real@pagecolor{#2}\def\model{}%
+ \else\real@pagecolor[#1]{#2}\def\model{[#1]}%
+ \fi
+ \edef\next{\egroup\def\noexpand\current@page@color{\current@page@color}%
+ \noexpand\real@pagecolor\model{#2}}%
+ \fi\next}
+%
+\newcommand{\segmentcolor}[2][named]{\@ifpackageloaded{color}%
+ {\loadsegmentcolors\segmentcolor[#1]{#2}}{}}
+
+\@ifpackageloaded{color}{\loadsegmentcolors}{\let\real@pagecolor=\@gobble
+ \AtBeginDocument{\@ifpackageloaded{color}{\loadsegmentcolors}{}}}
+
+
+% Define the \segment[align]{file}{section-command}{section-title} command,
+% and its helper macros. This command does four things:
+% 1) Begins a new LaTeX section;
+% 2) Writes a list of section counters to file.ptr, each
+% of which represents the sum of the LaTeX section
+% counters, and the l-counters, defined above;
+% 3) Write an \htmlhead{section-title} command to file.ptr;
+% 4) Inputs file.tex.
+
+\newcommand{\segment}{\@ifstar{\@@htmls}{\@@html}}
+%\tracingall
+\newcommand{\@endsegment}[1][]{}
+\let\endsegment\@endsegment
+\newcommand{\@@htmls}[1][]{\@@htmlsx{#1}}
+\newcommand{\@@html}[1][]{\@@htmlx{#1}}
+\def\@@htmlsx#1#2#3#4{\csname #3\endcsname* {#4}%
+ \DumpCounters{#2}{#3*}{#4}{#1}\input{#2}}
+\def\@@htmlx#1#2#3#4{\csname #3\endcsname {#4}%
+ \DumpCounters{#2}{#3}{#4}{#1}\input{#2}}
+
+\makeatother
+\endinput
+
+
+% Modifications:
+%
+% (The listing of Initiales see Changes)
+
+% $Log: html.sty,v $
+% Revision 1.39 2001/10/01 22:47:06 RRM
+% -- somehow revision 1.39 was not committed earlier
+% -- it allows a * version of \tableofcontents (used with frames) to be
+% treated as un-starred by LaTeX
+%
+% Revision 1.39 2000/09/10 12:23:20 RRM
+% -- added *-argument for \tableofcontents in frames.perl
+% LaTeX should just ignore it
+%
+% Revision 1.38 1999/07/19 13:23:20 RRM
+% -- compatibility with pdflatex and hyperref.sty
+% citations are not complete yet, I think
+% -- ensure that \thechapter remains undefined; some packages use it
+% as a test for the type of documentclass being used.
+%
+% Revision 1.37 1999/03/12 07:02:38 RRM
+% -- change macro name from \addTOCsection to \htmladdTOClink
+% -- it has 3 + 1 optional argument, to allow a local path to a labels.pl
+% file for the external document, for cross-references
+%
+% Revision 1.36 1999/03/10 05:46:00 RRM
+% -- extended the code for compatibilty with comment.sty
+% -- allow excluded environments to work within tables,
+% with the excluded material spanning headers and several cells
+% thanks Avinash Chopde for recognising the need for this.
+% -- added LaTeX support (ignores it) for \htmladdTOCsection
+% thanks to Steffen Klupsch and Uli Wortmann for this idea.
+%
+% Revision 1.35 1999/03/08 11:16:16 RRM
+% html.sty for LaTeX2HTML V99.1
+%
+% -- ensure that html.sty can be loaded *after* hyperref.sty
+% -- support new command \htmlclear for <BR> in HTML, ignored by LaTeX
+% -- ensure {part} and {chapter} counters are defined, even if not used
+%
+% Revision 1.34 1998/09/19 10:37:29 RRM
+% -- fixed typo with \next{\hyperref}{....}
+%
+% Revision 1.33 1998/09/08 12:47:51 RRM
+% -- changed macro-names for the \hyperref and \hypercite options
+% allows easier compatibility with other packages
+%
+% Revision 1.32 1998/08/24 12:15:14 RRM
+% -- new command \htmllanguagestyle to associate a style class
+% with text declared as a particular language
+%
+% Revision 1.31 1998/07/07 14:15:41 RRM
+% -- new commands \htmlsetstyle and \htmladdtostyle
+%
+% Revision 1.30 1998/07/04 02:42:22 RRM
+% -- cope with catcodes of % { } in rawhtml/comment/htmlonly environments
+%
+% Revision 1.29 1998/06/23 13:33:23 RRM
+% -- use \begin{small} with the default for URLs
+%
+% Revision 1.28 1998/06/21 09:38:39 RRM
+% -- implement \htmlurl to agree with \url if already defined
+% or loaded subsequently (LaTeX-2e only)
+% -- get LaTeX to print the revision number when loading
+%
+% Revision 1.27 1998/06/20 15:13:10 RRM
+% -- \TeX is already protected in recent versions of LaTeX
+% so \DeclareRobust doesn't work --- causes looping
+% -- \part and \subparagraph need not be defined in some styles
+%
+% Revision 1.26 1998/06/01 08:36:49 latex2html
+% -- implement optional argument for \endsegment
+% -- made the counter value output from \DumpPtr more robust
+%
+% Revision 1.25 1998/05/09 05:43:35 latex2html
+% -- conditionals for avoiding undefined counters
+%
+% Revision 1.23 1998/02/26 10:32:24 latex2html
+% -- use \providecommand for \latextohtml
+% -- implemented \HTMLcode to do what \HTML did previously
+% \HTML still works, unless already defined by another package
+% -- fixed problems remaining with undefined \chapter
+% -- defined \endsegment
+%
+% Revision 1.22 1997/12/05 11:38:18 RRM
+% -- implemented an optional argument to \begin for style-sheet info.
+% -- modified use of an optional argument with sectioning-commands
+%
+% Revision 1.21 1997/11/05 10:28:56 RRM
+% -- replaced redefinition of \@htmlrule with \htmlrulestar
+%
+% Revision 1.20 1997/10/28 02:15:58 RRM
+% -- altered the way some special html-macros are defined, so that
+% star-variants are explicitly defined for LaTeX
+% -- it is possible for these to occur within images.tex
+% e.g. \htmlinfostar \htmlrulestar \tableofchildlinksstar
+%
+% Revision 1.19 1997/10/11 05:47:48 RRM
+% -- allow the dummy {tex2html_nowrap} environment in LaTeX
+% use it to make its contents be evaluated in environment order
+%
+% Revision 1.18 1997/10/04 06:56:50 RRM
+% -- uses Robin Fairbairns' code for ignored environments,
+% replacing the previous comment.sty stuff.
+% -- extensions to the \tableofchildlinks command
+% -- extensions to the \htmlinfo command
+%
+% Revision 1.17 1997/07/08 11:23:39 RRM
+% include value of footnote counter in .ptr files for segments
+%
+% Revision 1.16 1997/07/03 08:56:34 RRM
+% use \textup within the \latextohtml macro
+%
+% Revision 1.15 1997/06/15 10:24:58 RRM
+% new command \htmltracenv as environment-ordered \htmltracing
+%
+% Revision 1.14 1997/06/06 10:30:37 RRM
+% - new command: \htmlborder puts environment into a <TABLE> cell
+% with a border of specified width, + other attributes.
+% - new commands: \HTML for setting arbitrary HTML tags, with attributes
+% \HTMLset for setting Perl variables, while processing
+% \HTMLsetenv same as \HTMLset , but it gets processed
+% as if it were an environment.
+% - new command: \latextohtml --- to set the LaTeX2HTML name/logo
+% - fixed some remaining problems with \segmentcolor & \segmentpagecolor
+%
+% Revision 1.13 1997/05/19 13:55:46 RRM
+% alterations and extra options to \hypercite
+%
+% Revision 1.12 1997/05/09 12:28:39 RRM
+% - Added the optional argument to \htmlhead, also in \DumpCounters
+% - Implemented \HTMLset as a no-op in LaTeX.
+% - Fixed a bug in accessing the page@color settings.
+%
+% Revision 1.11 1997/03/26 09:32:40 RRM
+% - Implements LaTeX versions of \externalcite and \hypercite commands.
+% Thanks to Uffe Engberg and Stephen Simpson for the suggestions.
+%
+% Revision 1.10 1997/03/06 07:37:58 RRM
+% Added the \htmltracing command, for altering $VERBOSITY .
+%
+% Revision 1.9 1997/02/17 02:26:26 RRM
+% - changes to counter handling (RRM)
+% - shuffled around some definitions
+% - changed \htmlrule of 209 mode
+%
+% Revision 1.8 1997/01/26 09:04:12 RRM
+% RRM: added optional argument to sectioning commands
+% \htmlbase sets the <BASE HREF=...> tag
+% \htmlinfo and \htmlinfo* allow the document info to be positioned
+%
+% Revision 1.7 1997/01/03 12:15:44 L2HADMIN
+% % - fixes to the color and natbib interfaces
+% % - extended usage of \hyperref, via an optional argument.
+% % - extended use comment environments to allow shifting expansions
+% % e.g. within \multicolumn (`bug' reported by Luc De Coninck).
+% % - allow optional argument to: \htmlimage, \htmlhead,
+% % \htmladdimg, \htmladdnormallink, \htmladdnormallinkfoot
+% % - added new commands: \htmlbody, \htmlnohead
+% % - added new command: \tableofchildlinks
+%
+% Revision 1.6 1996/12/25 03:04:54 JCL
+% added patches to segment feature from Martin Wilck
+%
+% Revision 1.5 1996/12/23 01:48:06 JCL
+% o introduced the environment makeimage, which may be used to force
+% LaTeX2HTML to generate an image from the contents.
+% There's no magic, all what we have now is a defined empty environment
+% which LaTeX2HTML will not recognize and thus pass it to images.tex.
+% o provided \protect to the \htmlrule commands to allow for usage
+% within captions.
+%
+% Revision 1.4 1996/12/21 19:59:22 JCL
+% - shuffled some entries
+% - added \latexhtml command
+%
+% Revision 1.3 1996/12/21 12:22:59 JCL
+% removed duplicate \htmlrule, changed \htmlrule back not to create a \hrule
+% to allow occurrence in caption
+%
+% Revision 1.2 1996/12/20 04:03:41 JCL
+% changed occurrence of \makeatletter, \makeatother
+% added new \htmlrule command both for the LaTeX2.09 and LaTeX2e
+% sections
+%
+%
+% jcl 30-SEP-96
+% - Stuck the commands commonly used by both LaTeX versions to the top,
+% added a check which stops input or reads further if the document
+% makes use of LaTeX2e.
+% - Introduced rrm's \dumpcurrentcolor and \bodytext
+% hws 31-JAN-96 - Added support for document segmentation
+% hws 10-OCT-95 - Added \htmlrule command
+% jz 22-APR-94 - Added support for htmlref
+% nd - Created
--- /dev/null
+#LaTeX2HTML Version 96.1 : dot.latex2html-init
+#
+### Command Line Argument Defaults #######################################
+
+$MAX_SPLIT_DEPTH = 3; # Stop making separate files at this depth
+
+$MAX_LINK_DEPTH = 3; # Stop showing child nodes at this depth
+
+$NOLATEX = 0; # 1 = do not pass unknown environments to Latex
+
+$EXTERNAL_IMAGES = 0; # 1 = leave the images outside the document
+
+$ASCII_MODE = 0; # 1 = do not use any icons or internal images
+
+# 1 = use links to external postscript images rather than inlined bitmap
+# images.
+$PS_IMAGES = 0;
+
+$TITLE = 'Cinelerra-GG Infinity'; # The default is "No Title"
+
+$DESTDIR = ''; # Put the result in this directory
+
+# When this is set, the generated HTML files will be placed in the
+# current directory. If set to 0 the default behaviour is to create (or reuse)
+# another file directory.
+$NO_SUBDIR = 0;
+
+
+# Supply your own string if you don't like the default <Name> <Date>
+#$ADDRESS = "<I>$address_data[0] <BR>\n$address_data[1]</I>";
+$ADDRESS = "<I>The CINELERRA-GG Community, 2021<BR><A HREF=\"https://www.cinelerra-gg.org\">https://www.cinelerra-gg.org</A></I>";
+
+$NO_NAVIGATION = 0; # 1 = do not put a navigation panel at the top of each page
+
+# Put navigation links at the top of each page. If the page exceeds
+# $WORDS_IN_PAGE number of words then put one at the bottom of the page.
+$AUTO_NAVIGATION = 1;
+
+# Put a link to the index page in the navigation panel
+$INDEX_IN_NAVIGATION = 1;
+
+# Put a link to the table of contents in the navigation panel
+$CONTENTS_IN_NAVIGATION = 1;
+
+# Put a link to the next logical page in the navigation panel
+$NEXT_PAGE_IN_NAVIGATION = 1;
+
+# Put a link to the previous logical page in the navigation panel
+$PREVIOUS_PAGE_IN_NAVIGATION = 1;
+
+$INFO = 1; # 0 = do not make a "About this document..." section
+
+# Reuse images generated during previous runs
+$REUSE = 2;
+
+# When this is 1, the section numbers are shown. The section numbers should
+# then match those that would have bee produced by LaTeX.
+# The correct section numbers are obtained from the $FILE.aux file generated
+# by LaTeX.
+# Hiding the seciton numbers encourages use of particular sections
+# as standalone documents. In this case the cross reference to a section
+# is shown using the default symbol rather than the section number.
+$SHOW_SECTION_NUMBERS = 0;
+
+### Other global variables ###############################################
+$CHILDLINE = "<BR> <HR>\n";
+
+# This is the line width measured in pixels and it is used to right justify
+# equations and equation arrays;
+$LINE_WIDTH = 500;
+
+# Used in conjunction with AUTO_NAVIGATION
+$WORDS_IN_PAGE = 300;
+
+# Affects ONLY the way accents are processed
+$default_language = 'english';
+
+# The value of this variable determines how many words to use in each
+# title that is added to the navigation panel, see below (-1 is no limit).
+# If $SHOW_SECTION_NUMBERS == 1, then one additional word counts
+# for the section number.
+#
+$WORDS_IN_NAVIGATION_PANEL_TITLES = 4;
+
+# The value of this variable determines how many words to use in each
+# Index entry (analogous to $WORDS_IN_NAVIGATION_PANEL_TITLES).
+# If not set, it equals to $WORDS_IN_NAVIGATION_PANEL_TITLES by default.
+#
+#$WORDS_IN_INDEX = 4;
+
+# This number will determine the size of the equations, special characters,
+# and anything which will be converted into an inlined image
+# *except* "image generating environments" such as "figure", "table"
+# or "minipage".
+# Effective values are those greater than 0.
+# Sensible values are between 0.1 - 4.
+$MATH_SCALE_FACTOR = 1.6;
+
+# This number will determine the size of
+# image generating environments such as "figure", "table" or "minipage".
+# Effective values are those greater than 0.
+# Sensible values are between 0.1 - 4.
+$FIGURE_SCALE_FACTOR = 1.6;
+
+
+# If this is set then intermediate files are left for later inspection.
+# This includes $$_images.tex and $$_images.log created during image
+# conversion.
+# Caution: Intermediate files can be *enormous*.
+$DEBUG = 0;
+
+# If both of the following two variables are set then the "Up" button
+# of the navigation panel in the first node/page of a converted document
+# will point to $EXTERNAL_UP_LINK. $EXTERNAL_UP_TITLE should be set
+# to some text which describes this external link.
+$EXTERNAL_UP_LINK = "";
+$EXTERNAL_UP_TITLE = "";
+
+# If this is set then the resulting HTML will look marginally better if viewed
+# with Netscape.
+$NETSCAPE_HTML = 0;
+
+# Valid paper sizes are "letter", "legal", "a4","a3","a2" and "a0"
+# Paper sizes has no effect other than in the time it takes to create inlined
+# images and in whether large images can be created at all ie
+# - larger paper sizes *MAY* help with large image problems
+# - smaller paper sizes are quicker to handle
+$PAPERSIZE = "a4";
+
+# Replace "english" with another language in order to tell LaTeX2HTML that you
+# want some generated section titles (eg "Table of Contents" or "References")
+# to appear in a different language. Currently only "english" and "french"
+# is supported but it is very easy to add your own. See the example in the
+# file "latex2html.config"
+$TITLES_LANGUAGE = "english";
+
+### Navigation Panel ##########################################################
+#
+# The navigation panel is constructed out of buttons and section titles.
+# These can be configured in any combination with arbitrary text and
+# HTML tags interspersed between them.
+# The buttons available are:
+# $PREVIOUS - points to the previous section
+# $UP - points up to the "parent" section
+# $NEXT - points to the next section
+# $NEXT_GROUP - points to the next "group" section
+# $PREVIOUS_GROUP - points to the previous "group" section
+# $CONTENTS - points to the contents page if there is one
+# $INDEX - points to the index page if there is one
+#
+# If the corresponding section exists the button will contain an
+# active link to that section. If the corresponding section does
+# not exist the button will be inactive.
+#
+# Also for each of the $PREVIOUS $UP $NEXT $NEXT_GROUP and $PREVIOUS_GROUP
+# buttons there are equivalent $PREVIOUS_TITLE, $UP_TITLE, etc variables
+# which contain the titles of their corresponding sections.
+# Each title is empty if there is no corresponding section.
+#
+# The subroutine below constructs the navigation panels in each page.
+# Feel free to mix and match buttons, titles, your own text, your logos,
+# and arbitrary HTML (the "." is the Perl concatenation operator).
+sub top_navigation_panel {
+ "<!--Navigation Panel-->"
+
+ # Start with a horizontal rule (3-d dividing line)
+ . "\n<HR>"
+
+ # Now add a few buttons with a space between them
+ . "$NEXT $UP $PREVIOUS $CONTENTS $INDEX $CUSTOM_BUTTONS"
+
+ . "\n<BR>" # Line break
+
+ # If ``next'' section exists, add its title to the navigation panel
+ . ($NEXT_TITLE ? "\n<B> $next_name:</B> $NEXT_TITLE" : undef)
+
+ # Similarly with the ``up'' title ...
+ . ($UP_TITLE ? "\n<B> $up_name:</B> $UP_TITLE" : undef)
+
+ # ... and the ``previous'' title
+ . ($PREVIOUS_TITLE ? "\n<B> $prev_name:</B> $PREVIOUS_TITLE" : undef)
+
+ # ... and the ``contents'' title
+ . ($CONTENTS_LINK ? "\n <B> $CONTENTS_LINK</B> " : undef)
+
+ # ... and the ``index'' title
+ . ($INDEX_LINK ? "\n <B> $INDEX_LINK</B> " : undef)
+
+ # These <BR>s separate it from the text body.
+ . "\n<BR><HR>"
+}
+
+sub bot_navigation_panel {
+
+ # Start with a horizontal rule (3-d dividing line)
+ "<HR>\n" . "<!--Navigation Panel-->"
+
+ # Now add a few buttons with a space between them
+ . "$NEXT $UP $PREVIOUS $CONTENTS $INDEX $CUSTOM_BUTTONS"
+
+ . "\n<BR>" # Line break
+
+ # If ``next'' section exists, add its title to the navigation panel
+ . ($NEXT_TITLE ? "\n<B> $next_name:</B> $NEXT_TITLE" : undef)
+
+ # Similarly with the ``up'' title ...
+ . ($UP_TITLE ? "\n<B> $up_name:</B> $UP_TITLE" : undef)
+
+ # ... and the ``previous'' title
+ . ($PREVIOUS_TITLE ? "\n<B> $prev_name:</B> $PREVIOUS_TITLE" : undef)
+
+ # ... and the ``contents'' title
+ . ($CONTENTS_LINK ? "\n <B> $CONTENTS_LINK</B> " : undef)
+
+ # ... and the ``index'' title
+ . ($INDEX_LINK ? "\n <B> $INDEX_LINK</B> " : undef)
+
+ # Horizontal rule (3-d dividing line)
+ . "\n<HR>"
+}
+
+&ignore_commands( <<_IGNORED_CMDS_);
+captionsetup # {}
+fboxsep # &ignore_numeric_argument
+drop # &ignore_numeric_argument
+AddToShipoutPicture # {}
+ClearShipoutPicture
+_IGNORED_CMDS_
+
+1; # This must be the last line
--- /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}
\section{Proxy}%
\label{sec:proxy}
+\index{proxy}
-Working with videos that have large image geometry can greatly impede editing. Instead you can substitute \textit{proxies} which will create smaller video image files from the original file that can then be edited more quickly. When you are done working on this smaller scale, you will need to bring up the Proxy settings menu again, and change the Scale factor back to the Original size so that all of your edits/work take affect on that original higher quality video on the timeline.
+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 this feature, select \texttt{Settings $\rightarrow$ Proxy settings} and change the Scale factor from Original size to your downsized choice. You can choose ffmpeg as the File Format and a choice of various codecs associated with that. A good choice is the default of mpeg which can usually be quite fast. In addition, to modify values for that codec, click on the wrench icon. When you have completed your choices, just click OK, and then the video tracks will be rendered. This may take some time, but previous proxy renders will be reused.
-The proxy videos will be added to your assets in a separate Proxy folder, and the video track edits will use the proxies.
-The assets in both the Media folder and Proxy folder will look proxied when dragged to the Viewer although the scale may be different.
-Proxy downsizing renders all loaded tracks, but only work on the $1^{st}$ video layer of any multi-layer media. Rendered proxy media is saved in the same directory as the original media.
-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 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.
-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 "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 "edits", like cuts or
-adding plugins because this information is not in a buffer but rather part of the
-copy "Editing Decision List" (EDL).
+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.
-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}.
+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}
+
+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.
+
+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}.
+
+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.
+
+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.
+
+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}
-There are two ways that the proxy files can be used, with or without input scaling. When the proxy is done without rescaling, the Mask, Camera and Projector automations are re-scaled accordingly. In this situation, the entire project will be re-sized so that the session is in the resized geometry. Not all plugins are useful when the project is rescaled, because the keyframe data must be in the original geometry. In this case, you can use the rescaler, by enabling \textit{Use scaler (FFMPEG only)}. This has the added advantage that the project size does not change and the proxy media is down-scaled as usual and up-scaled on read-in, which means the project editing is done in full scale. Since decoding is done on smaller video, there is a time savings, but all rendering is done full scale. The main reason for using \textit{scaler} is that it does not change the image coordinate data, so that automation and plugin parameters will be in the original project geometry. This is not as fast as the first option, but is a performance gain, and may be needed if you are using plugins that need coordinate data such as the Title plugin. As noted, the scaler only works on ffmpeg video formats.
+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.
-In the upper right hand corner of the main window, there is a toggle button to easily switch back and forth when you have a proxied file on the timeline. The icon is to the left of the FF icon. It will have the letter “P” as the icon for Proxy or if \textit{Using Scaler}, the letter “S”. \quad \includegraphics[height=\baselineskip]{proxy-01.png} \quad This quick switch is especially useful when editing and you need to see a better image temporarily.
+\subsection{Setting the proxy}%
+\label{sub:setting_proxy}
\begin{figure}[htpb]
\centering
- \includegraphics[width=0.5\linewidth]{proxy-02.png}
+ \includegraphics[width=0.8\linewidth]{proxy-02.png}
\caption{Proxy settings dialog}
\label{fig:proxy-02}
\end{figure}
-Screencast in figure~\ref{fig:proxy-02} shows the Use scaler checked so you can still use plugins and the original project size is kept. The Scale factor pull-down gives you available size options. Note the new media dimensions shown (partially covered). If the size is an odd number, 1 is added to make the dimensions both even numbers.
+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.
-In the case of the scaler checkbox, it will retain that setting for ease of use.
+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} dial included so that you can work on other tasks until there is an audible notify of completion. The default volume is set to 0 for no audible notify.
-
-A good choice for proxy settings with 1080p source video is:
+A good choice for classic proxy settings with a 1080p source video is:
\begin{lstlisting}[numbers=none]
Scale Factor: 1/4
-Use Scaler: unchecked
File Format: FFMPEG - mpeg
Video Preset:
Compression: mpeg.mpeg
-Bitrate: 1800000
+Bitrate: 2000000
Quality: -1
Pixels: yuv420p
\end{lstlisting}
Compression: mov.mov
\end{lstlisting}
-Or if you want small files with high image quality, a File Format of m2ts is optimal. For example a 1 GB file can be reduced to 50 MB with scale $\frac{1}{2}$.
+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}$.
+
+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.
+
+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.
-Checking the \textit{Auto proxy/scale media loads} results in any additional media loads to be automatically proxy scaled. However, single frame media such as PNG or JPEG \textit{stills}, can not be scaled to \textit{stream} media. If this type of media exists, you should \textit{use scaler}.
+\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}
-If you get error messages when creating proxies, check the Video wrench settings. These usually default to values that are expected to work correctly for the \textit{File Format} and codec you selected but they can be changed and may result in errors. If you get an error message of \textit{check\_frame\_rate failed} followed by \textit{Error making proxy} in the popup Errors window, do just that and check the Frame rate value by going to the Resources window, Media folder, and use the right mouse button for the Info option for that specific media in question. You can change the frame rate in this window to a more codec acceptable value. Different codecs may have different legal values.
+\subsection{Proxies with Alpha channel}%
+\label{sub:proxies_alpha_channel}
-More specific information on which plugins need to use scaler is provided here next. If the keyframe data uses coordinate data that is absolute, then the scaler should be used. If the data is normalized (like always $0-100\%$) then the proxy can be done without the scaler. The session geometry format, shown in \texttt{Settings $\rightarrow$ Format} as $width \times height$, is changed if the scaler is not used to cause all of the data to be in the reduced format. If this affects the plugin operation, then scaler should be used. Examples of plugins that need the scaler are: Title, AutoScale, Scale, ScaleRatio, and Translate. Most others are safe to use without scaling.
+Next are some examples of tested and working configurations that maintain the alpha channel:
+
+\begin{lstlisting}[numbers=none]
+Proxy #1
+ Scale factor: 1/4
+ Rescaled to project size (FFMPEG only) = unchecked
+ File Format: FFMPEG | qt
+ Video Preset-->
+ Compression: png.qt
+ Bitrate: 0
+ Quality: -1
+ Pixels: rgba (or rgba64be)
+
+
+Proxy #2
+ Scale factor: 1/4
+ Rescaled to project size (FFMPEG only) = unchecked
+ File Format: FFMPEG | qt
+ Video Preset-->
+ Compression: magicyuv.qt
+ Bitrate: 0
+ Quality: -1
+ Pixels: yuva444p
+
+
+Proxy #3
+ Scale factor: 1/4
+ Rescaled to project size (FFMPEG only) = unchecked
+ File Format: FFMPEG | qt
+ Video Preset-->
+ Compression: openjpeg.qt
+ Bitrate: 0
+ Quality: -1
+ Pixels: yuva420p
+
+
+Proxy #4
+ Scale factor: 1/4
+ Rescaled to project size (FFMPEG only) = unchecked
+ File Format: FFMPEG | pro
+ Video Preset-->
+ Compression: prores_4444.pro
+ prores_4444xq.pro
+ Bitrate: 0
+ Quality: -1
+ Pixels: yuva444p10le
+
+
+Proxy #5
+ Scale factor: 1/4
+ Rescaled to project size (FFMPEG only) = unchecked
+ File Format: FFMPEG | mkv
+ Video Preset-->
+ Compression: user_ffvhuff.mkv
+ Bitrate: 0
+ Quality: -1
+ Pixels: yuva4--p
+ yuva4--p--le
+\end{lstlisting}
\section{Transcode}%
\label{sec:transcode}
+\index{transcode}
-Transcode, an option under the \textit{Settings} pulldown right next to the Proxy settings option, is a type of full resolution \textbf{1:1 Proxy}.
+Transcode, an option under the \textit{Settings} pulldown right next to the Proxy settings option, is a type of full resolution \textbf{1:1 Proxy} \index{proxy!1:1}.
The process of transcoding works directly from the resource; it is independent of the timeline.
All of the loaded asset media will be converted, that is, rendered in the selected format and loaded onto the timeline.
-Menu choices besides the usual File Format and File Type include: \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.
+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}, that is, you can play it from the beginning but can not move to another spot and have the audio or video play correctly. A video file with no keyframes makes seeking next to impossible, but then a Transcode generally adds these keyframes.
+The BIGGEST gain from using this is if you have media that is not \textit{seekable} \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}
+\index{openEDL}
-To edit EDL that is included with your project as Clips, Nested
+To edit EDL \index{EDL} that is included with your project as Clips, Nested
Clips, Referenced File, or Xml you can use the option \textit{Open
EDL} in the Resources window for the highlighted media. Then
with a simple button click you can return to your main timeline project.
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.
+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 or Media folder or on a timeline
+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
nested clip is available so that when you choose this option, that
EDL will be brought up on the timeline superseding the current EDL
-that exists on the timeline. Now, once the clip is open on the
+that exists on the timeline \index{timeline}. Now, once the clip is open on the
timeline, you can edit it however you want. The previous timeline
EDL is \textit{pushed onto a stack} so it can be recalled by
\textit{popping the stack} with a click of the left mouse button in
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
-\textit{Open EDL} on the Nested EDL in the media folder. When you
+\textit{Open EDL} on the Nested EDL \index{nested EDL} in the media folder. When you
Open EDL and edit the changes, those changes will take affect on any
and all occurrences of that nested clip on the current and/or
original timeline. The option to unnest that clip and put that back
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}
a new name.
For additional safety, the \textit{Open EDL} feature includes
-additional backup capabilities. Automatically \CGG{} saves a backup
+additional backup capabilities. Automatically \CGG{} saves a backup \index{backup}
when certain changes are made or you can always use the shortcut `b'
to do one yourself, although keep in mind it will be overwritten
whenever \CGG{} wants to do another backup. Now there is a shortcut
\section{File by Reference}%
\label{sec:file_by_reference}
+\index{file by reference}
-It is sometimes handy to have EDL assets not as a copy, but as a
+It is sometimes handy to have EDL \index{EDL} assets not as a copy, but as a
reference that is automatically updated into your project. Suppose
you have several short videos that at the end have the same credits
-which include the current year such as 2019. But now it is 2020 and
+which include the current year such as 2021. But now it is 2022 and
all of the videos would have to be individually updated with the new
date. By including a \textit{Referenced File} as the EDL file type
when you create each of the videos, you can just change the one
Up until the addition of this feature, \CGG{} has always used copies
and no direct reference in order to ensure original data is never
-compromised. In the usual case, subprojects as xmls are copied into
+compromised (No Destructive editing). In the usual case, subprojects as xmls are copied into
a master project where subprojects had been inserted, so that if you
change something in a subproject or delete a subproject, it would
have no affect on the master project. But now with \textit{File by
\section{Trimming}%
\label{sec:trimming}
+\index{trim}
With some edits on the timeline it is possible to do trimming. By
-trimming you shrink or grow the edit boundaries by dragging them. In
+trimming you shrink or grow the edit boundaries (\textit{head} or \textit{tail}) by dragging them. In
drag and drop mode or cut and paste mode, move the cursor over an
-edit boundary until it changes shape. The drag handle shows as a
+edit boundary until it changes shape. The drag handle \index{drag handles} shows as a
left or right facing fat arrow when you cursor near the clip start
or end. If the cursor faces left, the dragging operation affects
the beginning of the edit. If the cursor faces right, the dragging
\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}
follows.
\begin{description}
- \item[All Edits (ripple)] shorten or lengthen the start or end
+ \item[All Edits (ripple)] \index{trim!ripple} shorten or lengthen the start or end
of a single piece of media while moving all media to the right of
that clip up or down on the timeline correspondingly. Timeline
duration is modified. In a drag \textit{All Edits} operation, the
it forward or cuts data from the end of the edit if you move it
backward. All the following edits shift. If you drag the end of the
edit past the start of the edit, the edit is deleted.
- \item[One Edit (roll)] move the in and out point of a single
+ \item[One Edit (roll)] \index{trim!roll} move the in and out point of a single
clip without changing the timeline duration. In a drag \textit{One
Edit} operation, nothing is cut or pasted. If you move the beginning
or end of the edit forward, the source reference in the edit shifts
forward. If you move the beginning or end of the edit backward, the
source reference shifts backward. The edit remains in the same spot
in the timeline but the source shifts.
- \item[Src Only (slip)] move the in and out point of a single
+ \item[Src Only (slip)] \index{trim!slip} move the in and out point of a single
clip without changing the timeline duration. In a drag \textit{Src
Only} operation, nothing is cut or pasted. If you move the beginning
or end of the edit forward, the source reference in the edit shifts
forward. If you move the beginning or end of the edit backward, the
source reference shifts backward. The edit remains in the same spot
in the timeline but the source shifts.
- \item[Slide] a single clip is moved but retains its current in
+ \item[Slide] \index{trim!slide} a single clip is moved but retains its current in
and out point; however the out point of the clip to the left changes
and the in point of the clip to the right also changes. Timeline
duration remains the same.
- \item[Edge Left/Right] moves the edge of the clips.
+ \item[Edge Left/Right] \index{trim!edge} moves the edge of the clips.
\item[No effect] no changes are made. You might want to use
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
\label{fig:trim-color}
\end{figure}
-\paragraph{How to do a J-cut or L-cut} A J-cut is a split edit film
+\paragraph{How to do a J-cut or L-cut} A J-cut \index{J-cut/L-cut} is a split edit film
editing technique in which the audio from a following scene overlaps
the picture from the preceding scene, so that the audio portion of
the later scene starts playing before its picture as a lead-in to
\subsection{Split View in Compositor Using the Drag Handle with Trim}%
\label{sub:split_view_compositor_using_drag_trim}
-
+\index{trim!split view}
The Trim Feature using the drag handle provides some good ways to
view your video while editing. The playback position in the
compositor is updated live and the view in the compositor can be
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}
\section{Nesting clips and assets}%
\label{sec:nesting_clips_and_assets}
+\index{nested EDL}
\subsection{Nested Assets}%
\label{sub:nested_assets}
+\index{nested assets}
A nested asset is an EDL session that
embeds an existing EDL session, all tracks, all plugins, editing,
\subsection{Nested Clips}%
\label{sub:nested_clips}
+\index{nested clips}
It is also possible to create
\textit{clips} and convert them to \textit{nested edl}. This is
\begin{itemize}
\item The creation of the nested clip is based on the settings in \texttt{Settings $\rightarrow$ Format}. Be sure that the number of audio tracks and channels is the same as we want to have in the nested clip. In addition, it is better to make each audio track independent from the others (which could be linked in more than one channel) using the option: \texttt{Audio $\rightarrow$ Map 1:1}
- \item You can do any editing on the nested clip once it is loaded to the timeline. For example we can start an OpenEDL session to make the changes. Once out of the OpenEDL session it may be that the changes made are not visible in the original nested clip. You can fix this by doing RMB on the nested clip in the \textit{Resources/Media} window and choosing \texttt{Rebuild index}. This process may take some time depending on the size of
+ \item You can do any editing on the nested clip once it is loaded to the timeline. For example we can start an OpenEDL \index{openEDL} session to make the changes. Once out of the OpenEDL session it may be that the changes made are not visible in the original nested clip. You can fix this by doing RMB on the nested clip in the \textit{Resources/Media} window and choosing \texttt{Rebuild index}. This process may take some time depending on the size of
the media; because of the additional time required to do this, it is not done automatically in order to allow the user to make the decision as to when they are done editing enough and need to see the exact results
in order to save time.
\item Because of the way the timeline thumbnails are displayed, after editing using OpenEDL of a
\section{Multi-Camera / Mixer}%
\label{sec:multicamera_mixer}
+\index{multi-camera}
+\index{mixers}
-Use the Mixer Viewer to see multiple media playing simultaneously in re-sizable mini-viewers. This can be used in various ways and is useful to edit videos shot by multiple cameras from different viewpoints that were simultaneously recorded in order to create a single good video. Everything will have to be initially synced so you can decide which one of the camera angles is best suited at any time.
+Use the Mixer Viewer to see multiple media playing simultaneously in re-sizable mini-viewers. This can be used in various ways and is useful to edit videos shot by multiple cameras from different viewpoints that were simultaneously recorded in order to create a single good video. Everything will have to be initially synced so you can decide which one of the camera angles is best suited at any time. Mixer mode does not support audio only tracks but there is a workaround described at \nameref{cha:faq_problems_workarounds}.
The number of cameras/mixers you can have is generally limited to the available resources on your computer. Currently, the number of File Descriptors available in the OS limits cameras to about 50. If you have many \textit{mixer viewers} you will probably want to use proxy mode whenever possible. Also, in the \texttt{Settings $\rightarrow$ Playback A} tab \textit{Video Out} section, uncheck \textit{play every frame} and choosing a Video Driver of \textit{X11} with \textit{use direct X11 render if possible} checked, will provide better performance.
\item From the \textit{File} pulldown, create a \textit{New project} with the desired format for Audio and Video output (or you can just use the default).
\item \texttt{File $\rightarrow$ Load} the media files you want to work with using \textit{Create new resources only}.
\item In the Resources window, with the Media folder, highlight the list of media you want to \textit{Mix}. This is done using a ctrl or shift mouse button press as you would in a standard listbox selection.
- \item Right click the mouse on the media selection and choose \textit{open mixers}. This opens multiple mixer viewer windows, one for each media item that was highlighted. You can
+ \item Right click the mouse on the media selection and choose \textit{open mixers} \index{mixers!open mixers}. This opens multiple mixer viewer \index{mixers!viewer} windows, one for each media item that was highlighted. You can
do them 1 at a time instead. This also adds the source media tracks to the main window.
- \item Now use the timeline to play and you will see all viewers/cameras playing. Stop when you get to the
+ \item Now use the timeline \index{timeline} to play and you will see all viewers/cameras playing. Stop when you get to the
end of the \textit{good} camera playback.
\item Simply double click the \textit{good} mixer viewer and from where you first started playing to the playback insertion pointer is the source section, which will be pasted in the destination video/audio tracks at the top of the new project.
\item Repeat steps 6-7. Start playing again, stop when you want, double click the desired mini-viewer!
\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, 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:
\item \textit{Dst tracks} should be playable and armed in the main window patchbay gui.
\end{itemize}
-Each mixer viewer maintains a list of the tracks which will be used as src. This list is made visible selecting the window with the left mouse button. When the mixer viewer is selected, a highlight is drawn around the media image. All track patchbay \textit{mixer} toggles are updated to reflect the src tracks included in the selected viewer src track list. The track patchbay toggles can be used to manage the list.
+Each mixer viewer maintains a list of the tracks which will be used as src. This list is made visible selecting the window with the left mouse button. When the mixer viewer is selected, a highlight is drawn around the media image. All track patchbay \textit{mixer} toggles are updated to reflect the src tracks included in the selected viewer src track list. The \textit{play track} patchbay toggles can be used to manage the list.
\begin{itemize}[noitemsep]
\item \textit{Turning on} a toggle (pointing up) includes the track in the src track list.
\subsubsection*{Using Proxy with \textit{Open Mixers}}%
\label{ssub:using_proxy_open_mixers}
-The best way to use proxy with your multiple cameras is to follow the steps below:
+The best way to use proxy \index{proxy} with your multiple cameras is to follow the steps below:
\begin{enumerate}
\item Load media with insertion strategy of \textit{create resources only}.
\item Choose the size and other options you want and click the checkmark OK. If you choose the option \textit{Beep when done} you will hear a short beep if all media is already proxied or a longer beep when all proxies have been created.
\item When your editing is complete, use \textit{Settings} pulldown and proxy to \textit{original size}.
\end{enumerate}
-Instead of Open Mixers, you can Insert Mixers with new tracks at the timeline insertion point.
+Instead of Open Mixers, you can Insert Mixers \index{mixers!insert mixers} with new tracks at the timeline insertion point.
+
+\subsubsection*{Options available in the \textit{Mixer Windows}}%
+\label{ssub:options_available_with_mixers}
+\index{mixers!viewer RMB options}
+
+There are several options you will see in each Mixer viewer \index{mixers!viewer} that help with using them. These
+are shown in figure~\ref{fig:mixer-playable}. To use these, RMB in the desired mixer window,
+and choose one of the options as described here.
\begin{figure}[htpb]
\centering
\label{fig:mixer-playable}
\end{figure}
-\subsubsection*{Options available in the \textit{Mixer Windows}}%
-\label{ssub:options_available_with_mixers}
-
-There are several options you will see in each Mixer window that help with using them. These
-are shown in figure~\ref{fig:mixer-playable}. To use these, RMB in the desired mixer window,
-and choose one of the options as described here.
-
\begin{enumerate}
\item Fullscreen / Windowed - will bring up a fullscreen display of that window or revert to the original size.
\item Resize Window - allows for resizing the window to a choice of different sizes.
- \item Tile Mixers - makes it easy to get all of the mixers nicely tiled to a standard size.
+ \item Tile Mixers \index{mixers!tile mixers} - makes it easy to get all of the mixers nicely tiled to a standard size.
This is also available in the \textit{Window} pulldown.
\item Playable - enabled by default so that you will see a checkmark next to it in the
popup. The benefit of making a mixer window not playable is to save cpu time. When a specific
\end{verbatim}
\end{enumerate}
+\subsubsection*{Mixers pulldown}%
+\label{ssub:mixers_pulldown}
+
+From Program windows menu we can access the \texttt{windows $\rightarrow$ mixers...} there are several entries available (see figure~\ref{fig:mixers-pulldown}):
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.5\linewidth]{mixers-pulldown.png}
+ \caption{Mixers... pulldown}
+ \label{fig:mixers-pulldown}
+\end{figure}
+
+\begin{description}
+ \item[Mixer Viewer:] \index{mixers!viewer} (Shift-M) opens a new empty \textit{Mixer 1} window, which will then be associated with a track. We can open as many Mixers as we like.
+ \item[Drag Tile mixers:] \index{mixers!drag tile mixers} (Alt-t) the default size of a mixer window is related to the std size of the \textit{Viewer} window. If we want to modify it at our convenience, we can build a window of the desired size with the \textit{Drag Tile mixers} function and then automatically order our mixers within it with the right click of the mouse.
+ \item[Align mixers:] \index{mixers!align mixers} see \nameref{sub:audio_video_sync_waveform}
+ \item[Mix masters:] \index{mixers!mix masters} this feature makes it very easy to get into the multi-camera mixer mode after tracks have already been set up and edited. Before this addition, you could only \textit{Open Mixers} from original media assets in the \textit{Resources} window.
+ \item[Entries:] If the mixers of several sources have been opened, the entries of each assets will appear, useful for recalling a specific mixer window.
+\end{description}
\subsection{Recover Mixer Windows}%
\label{sub:recover_mixer_windows}
+\index{mixers!recover mixer window}
It is a hazard that you might accidentally \textit{undo} (\texttt{z or Ctrl-z}) too far and lose your mixer windows. Here are the steps to recover. It is recommended that you make a backup of your project before performing the recovery steps just in case there are other problems.
Sometimes the association does not stick initially. If not, highlight the mixer viewer with the problem, change the mixer arrows to point up, and reassociate.
-\section{Audio/Video sync via Waveforms/Timecodes}%
+% For html, make sure using below is different from via in subsection
+\section{Audio/Video sync using Waveforms/Timecodes}%
\label{sec:audio_video_sync}
+\index{audio/video sync}
\subsection{Audio/Video sync via Waveform}%
\label{sub:audio_video_sync_waveform}
+\index{audio/video sync via waveform}
-Multi-camera footage of a single event can have various shots starting and ending at different times. So when the footage start times are different, you can use the mixer audio to synchronize the clips on the timeline. The program algorithm attempts to find and align automatically the waveforms of the media.
+Multi-camera \index{multi-camera} footage of a single event can have various shots starting and ending at different times. So when the footage start times are different, you can use the mixer audio to synchronize the clips on the timeline. The program algorithm attempts to find and align automatically the waveforms of the media.
Synchronizing multiple camera videos based on audio tracks can be done with \CGG{} easily enough with the \texttt{Window $\rightarrow$ Mixers$\dots$ $\rightarrow$ Align mixers} option. Align mixers brings up a window displaying your mixers, the currently selected Master Track, and a list of all of the Audio Tracks (figure~\ref{fig:mixer-align01}). There is a limit of 32 audio tracks per each mixer (that should be enough!)
\subsection{Align Timecodes}%
\label{sub:align_timecodes}
+\index{audio/video sync via timecodes}
+\index{align timecodes}
Align Timecodes is especially useful in the case where you create video with multiple cameras capable of recording a timecode in the metadata of each file. Let’s say we have recorded three videos at the same time at a concert with each camera set up at unique positions and at different angles. All of the cameras start recording at various times but were synchronized with the same master clock (\textit{Timecode Sync Generator} or \textit{Jam Sync timecode}) so that the recordings are timestamped with that synchronized time. For example, the 3 cameras have embedded metadata as follows: \quad \textbf{camera 1} = 00:00:00:01 \quad \textbf{camera 2} = 00:00:10:07 \quad \textbf{camera 3} = 00:00:17:22
\label{fig:timecode-01}
\end{figure}
-Timecode synchronization is performed by the program when you choose the option \textit{Align Timecodes} and works in 2 steps. The first automatic step is to locate the earliest timecode and the second step is to align the edits on the armed tracks using that time on the timeline.
+Timecode synchronization is performed by the program when you choose the option \textit{Align Timecodes} and works in 2 steps. The first automatic step is to locate the earliest timecode \index{timecode} and the second step is to align the edits on the armed tracks using that time on the timeline.
When you load in the three files to different tracks, they'll be placed on a timeline that starts from $00:00:00:00$ as usual. But, by middle mouse clicking (MMB) on any of the video tracks, you can view the timecode embedded at that point in that file.
rate as a time standard.
\item Time Code Start in the Resources window on the bottom of \textit{Info} for the media if the timecode for that
asset has been scanned and is known. You can scan the asset’s Timecode by using the middle mouse
- button on its track which then displays the timecode for that on the timebar.
+ button on its track which then displays the timecode for that on the timebar (\texttt{MMB $\rightarrow$ Timecode}). Or you can use the shortcut \texttt{Ctrl+!}, after selecting the edit/track on the timeline.
\end{itemize}
\paragraph*{Notes}
# where "-c copy" just copies the video/audio to the following output filename
\end{lstlisting}
+\section{Subtitles}%
+\label{sec:subtitles}
+\index{subtitles}
+
+\CGG{} can create subtitles directly in the timeline with the Subtitle tool. Subtitles are added by using the main window pulldown \texttt{File $\rightarrow$ Subtitle} (Alt-y) which brings up a window allowing you to type the filename of a previously generated text file containing the desired words/lines, the script. After entering the filename, click \texttt{Load} to read in your script. By creating a script file ahead of time, it lets you easily add dialog that was already written out and carefully edited for spelling and proper grammar.
+
+The file must be plain text; a .srt or .sub can also be used, but only the text lines will be used and not the timecodes or comments. The format of the script/text input file has specific requirements as listed below:
+
+\begin{itemize}
+ \item Lines can be any length but they will be broken up to fit according to some criteria below.
+ \begin{itemize}
+ \item Running text used as script lines will be broken into multiple lines.
+ \item The target line length is 60 characters.
+ \item Punctuation may be flagged to create an early break.
+ \item Single carriage return ends an individual script line.
+ \item Double carriage return indicates the end of a entry and helps to keep track of where you are.
+ \end{itemize}
+ \item The "\textit{=}" sign in column 1 indicates a comment seen in the script text to assist you in location.
+ \item An "\textit{*}" at the beginning of the line is a comment and not a script line.
+ \item \textit{Whitespace} at either the beginning of a script line or the end will be removed.
+\end{itemize}
+
+Figure~\ref{fig:subtitle01} shows the Subtitle window you will see.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.8\linewidth]{subtitle01.png}
+ \caption{Subtitle window}
+ \label{fig:subtitle01}
+\end{figure}
+
+To put the subtitles onto your media, first add a subtitle track via the pulldown \texttt{Tracks $\rightarrow$ Add subttl} (Shit-Y). In the Subtitle window, note that there are 2 major textboxes. There is the \textit{Script Text} textbox showing the current entry of text from your input file and there is the \textit{Line Text} textbox showing the currently active text. In your subtitle track, select a timeline region (in/out or drag select with hairline cursor/highlight or via labels or the \textit{selection start/length/end time} textboxes in the Zoom Panel) to indicate the region where you want the active Line Text to be pasted. Then click the \texttt{Paste} button in the Subtitle window to paste the line onto the subtitle track. Silence will be added to the subtitle track in the places in the media where there are gaps.
+
+Editing in the Line Text box can be used to change the active script line. By double clicking the timeline over the subtitle track, you can reselect the active script line. The subtitle text will be reloaded into the Line Text box and can be edited and re-pasted as the new active subtitle text. You can also highlight multiple lines in the Script Text box and paste them (using the usual window paste methodology) into the Line Text box. After pasting to the timeline, the Line Text box will be updated with the next script line. In addition, if you triple click a line in the \textit{Script Text} box, it will automatically become the current line in the \textit{Line Text} box.
+
+When you are finished, before clicking on \textit{Save}, you can specify the output format using the \textit{Format} drop-down button. You can choose between the classic \texttt{.udvd} (micro DVD) and the more universally supported \texttt{.srt} (subrip) and \texttt{.sub} (subviewer). The next step is to provide a legitimate filname in the \textit{Path} box; your current directory will be used if only a filename but no directory path is supplied. The filename used will automatically have a "--" after it followed by the \textit{track label} and then \textit{udvd/srt/sub} extension added; any extension in the filename will be removed.. If you click OK before saving, the subtitle script position is saved with the session. This is convenient for continuing where you left off.
+
+To reposition the script, use the slider or tumbler buttons:
+
+\textit{Slider} bar to move through the text entries quickly. \\
+\textit{Prev} or \textit{Next} buttons to go to the previous or next script line.
+
+Figure~\ref{fig:subtitle02} shows what the pasted subtitle script looks like in a portion of the main window.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=1.0\linewidth]{subtitle02.png}
+ \caption{Subtitles on timeline}
+ \label{fig:subtitle02}
+\end{figure}
+
+
+
--- /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:
\chapter{Project and Media Attributes}%
\label{cha:project_and_media_attributes}
+\index{project attributes}
+\index{format}
+\index{settings}
When you play media files in \CGG{}, the media files have a certain
number of tracks, frame size, sample size, and so on. No matter
attributes, the video is composited on a black frame, either cropped
or bordered with black.
-The project attributes are adjusted in \texttt{file $\rightarrow$
-Set Format} (figure~\ref{fig:set-format}) or can be created in
+The project attributes are adjusted in \texttt{Settings $\rightarrow$
+Format} (figure~\ref{fig:set-format}) or can be created in
\texttt{File $\rightarrow$ New}. When you adjust project settings
in \texttt{File $\rightarrow$ New}, a new empty timeline is created.
Every timeline created from this point on uses the same settings.
\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.
+refers to the display aspect ratio (DAR).
-Edit decision lists , the EDL stored in XML, save the project
+Edit decision lists , the EDL \index{EDL} stored in XML, save the project
settings. Formats which contain media but no edit decisions just
add data to the tracks. Keep in mind details such as if your
project sample rate is 48\,kHz and you load a sound file with
\section{Audio attributes}%
\label{sec:audio_attributes}
+\index{audio!attributes}
\begin{description}
tracks for the new project. Tracks can be added or deleted later,
but this option is on the New Project menu for convenience.
-\item[Samplerate:] sets the samplerate of the audio. The project
+\item[Samplerate:] \index{sample rate} sets the samplerate of the audio. The project
samplerate does not have to be the same as the media sample rate
that you load. Media is resampled to match the project sample rate.
-\item[Channels:] sets the number of audio channels for the new
+\item[Channels:] \index{audio!channels} sets the number of audio channels for the new
project. The number of audio channels does not have to be the same
as the number of tracks.
\section{Video attributes}%
\label{sec:video_attributes}
+\index{video!attributes}
\begin{description}
\item[Tracks:] (in New Project menu only) sets the number of video
tracks the new project is assigned. Tracks can be added or deleted
later, but options are provided here for convenience.
-\item[Framerate:] sets the framerate of the video. The project
+\item[Framerate:] \index{framerate} sets the framerate of the video. The project
framerate does not have to be the same as an individual media file
frame rate that you load. Media is reframed to match the project
framerate.
-\item[Canvas size:] sets the size of the video output. 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:] 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.
-\item[Color model:] the internal color space of \CGG{} is X11 sRGB
+\item[Color model:] \index{color!model} the internal color space of \CGG{} is X11 sRGB
without color profile. \CGG{} always switches to sRGB when applying
filters or using the compositing engine. Different case for
decoding/playback or encoding/output; the project will be stored in
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
degradation.
\item[YUVA-8 bit] Allocates an alpha channel to the 8\,bit YUV
colormodel for transparency.
- \end{description} In order to do effects which involve alpha
-channels, a colormodel with an alpha channel must be selected.
+ \end{description}
+
+In order to do effects which involve alpha
+channels \index{alpha channel}, a colormodel with an alpha channel must be selected.
These are RGBA-8 bit, YUVA-8 bit, and RGBA-Float. The 4 channel
colormodels are slower than 3\,channel colormodels, with the slowest
being RGBA-Float. Some effects, like fade, work around the need for
channels to see if it works before settling on an alpha channel and
slowing it down.
- When using compressed footage, YUV colormodels are usually faster
-than RGB colormodels. They also destroy fewer colors than RGB
+ When using compressed footage, YUV colormodels \index{yuv} are usually faster
+than RGB colormodels \index{RGB}. They also destroy fewer colors than RGB
colormodels. If footage stored as JPEG or MPEG is processed many
times in RGB, the colors will fade whereas they will not fade if
processed in YUV\@. Years of working with high dynamic range footage
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.
+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:] this is mostly obsolete in the modern digital
+\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
TV\@. Interlacing uses two fields to create a frame. One field
contains all odd-numbered lines in the image; the other contains all
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}
+
+\CGG{} supports the simultaneous presence in the Timeline of sources with different frame sizes and frame rates. However, audio/video synchronization problems may occur due to their different timing.\protect\footnote{credit to sge and Andrew Randrianasulu}
+Plugins that rely on the timing of each frame, for example \textit{Motion} and \textit{Interpolate} plugins, may have problems when used at the same time with engines which increase frame rate. Frame rate per definition cannot be increased without either duplicating some frames or generating them in some intelligent way. But to work reliably, the \textit{Motion} plugin requires access to all actual frames. These kinds of plugins (and also the rare cases of audio/video desync) explicitly require the \textit{Play every frame} option.
+
+There is no problem as long as the source fps, project fps, and destination fps are identical. In most cases, high frame rates such as 120 or 144 or any fps, will be just fine for \textit{Motion} provided that source footage all has the same frame rate.
+
+But when \textit{project} and \textit{source} frame rates are different (or \textit{project} and
+\textit{rendered} fps), then the \CGG{} engine has to either duplicate (interpolate) some frames or throw some away. Because of this, the audio tracks and the timeline get out of sync with such accelerated (or slowed down) video. And to make \textit{Motion} plugins reliably calculate interframe changes, you have to ensure the consistent frame numbers and frame properties.
+
+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. 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:
+
+\begin{enumerate}
+ \item Profiling and setting the monitor: \\
+ source: \textit{sRGB} $\rightarrow$ monitor: \textit{sRGB} (we get a correct color reproduction) \\
+ source: \textit{sRGB} $\rightarrow$ monitor: \textit{rec709} (we get slightly dark colors) \\
+ source: \textit{sRGB} $\rightarrow$ monitor: \textit{DCI-P3} (we get over-saturated colors) \\
+
+ source: \textit{rec709} $\rightarrow$ monitor: \textit{rec709} (we get a correct color reproduction) \\
+ 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) \\
+ \texttt{colorspace=...} (color spaces conversion, more depth-color); \\
+ or \\
+ \texttt{colormatrix=...} (color spaces conversion, faster).
+
+ 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}, \nameref{sec:conform_the_project} and \nameref{sec:overview_color_management}.
%%% Local Variables:
%%% mode: latex
\section{Using Ydiff to check results}
\label{sec:ydiff_check_results}
+\index{Ydiff}
Delivered with Infinity \CGG{} and in the \CGG{} path, there is a file \texttt{ydiff.C} This program compares the output from 2 files to see the differences . Do: \texttt{cd cin\_path} and key in \texttt{make ydiff}.
\section{Image Sequence Creation}
\label{sec:image_sequence_creation}
+\index{image sequence}
-Example script to create a jpeglist sequence file is next:
+Example script to create a jpeg list sequence file is next. It can be modified to
+create a list for \textit{exr}, \textit{gif}, \textit{ppm}, \textit{png}, \textit{tga}, or \textit{tiff}
+sequences instead by changing JPEGLIST
+to be EXRLIST, GIFLIST, PPMLIST, PNGLIST, TGALIST, or TIFFLIST.
\begin{lstlisting}[numbers=none]
#!/bin/bash
out="$1"
dir=$(dirname "$out")
shift
-geom=$(jpegtopnm "$1" | head -2 | tail -1)
+geom=$(anytopnm "$1" | head -2 | tail -1)
w="$(echo $geom | cut -d " " -f1)"
h="$(echo $geom | cut -d " " -f2)"
exec > $out
echo "JPEGLIST"
-echo "# First line is always JPEGLIST"
+echo "# First line is always format_typeLIST"
echo "# Frame rate:"
echo "29.970030"
echo "# Width:"
echo "$h"
echo "# List of image files follows"
while [ $# -gt 0 ]; do
- if [ x$(dirname "$1") = x"$dir" ]; then
- f=./`basename "$1"`;
- else
- f="$1";
- fi
+ f=./`basename "$1"`
echo "$f"
shift
done
\end{lstlisting}
To use this script, you will have to install the package on your operating system that
-includes \textit{jpegtopnm} which is ususally \textit{netpbm}.
+includes \textit{anytopnm} which is ususally \textit{netpbm}.
Example usage of this script follows:
-\qquad \texttt{jpeglist.sh outfile infiles*.jpg}
+\qquad \texttt{./imagelist.sh outfile infiles*.jpg}
-\section{Webm\,/\,Vp9 Usage and Example File\protect\footnote{credit Frederic Roenitz}}%
-\label{sec:webm/vp9_usage_example}
-
-\textsc{VP9} is a video codec licensed under the BSD license and is
-considered open source,
-% Sisvel Announces AV1 Patent Pool, March 10, 2020
-% https://www.streamingmedia.com/Articles/ReadArticle.aspx?ArticleID=139636
-% Webm / VP9 is a media file format which is free to use under the
-% BSD license and is open-source; thus there are no licensing
-% issues to be concerned about.
-the \textsc{Webm} container is based on \textsc{Matroska} for video
-and \textsc{Opus} for audio. There are some common \textsc{VP9} rendering
-options files that support creation of video for YouTube,
-Dailymotion, and other online video services.
-
-YouTube easy startup steps are documented in the Appendix (\ref{sec:youtube_with_cinelerra}). These same steps have been verified to work for creating Dailymotion videos -- however, the created files must be renamed before uploading to change the youtube extension to webm instead for Dailymotion.
-
-Below is one of the \textsc{VP9} rendering options file with documentation for specifics:
-
-\textbf{webm libvpx-vp9}
-
-(20171114-2203)
-
-from {\small \url{https://developers.google.com/media/vp9/settings/vod/}}
-
-1280x720 (24, 25 or 30 frames per second)
-
-Bitrate (bit rate)
-
-\textsc{VP9} supports several different bitrate modes:
-
-\textit{mode:}
-
-\begin{tabular}{p{6cm} p{10cm}}
- Constant Quantizer (Q) & Allows you to specify a fixed quantizer value; bitrate will vary \\
- Constrained Quality (CQ) & Allows you to set a maximum quality level. Quality may vary within bitrate parameters\\
- Variable Bitrate (VBR) & Balances quality and bitrate over time within constraints on bitrate\\
- Constant Bitrate (CBR) & Attempts to keep the bitrate fairly constant while quality varies\\
-\end{tabular}
-
-CQ mode is recommended for file-based video (as opposed to streaming). The following FFMpeg command-line parameters are used for CQ mode:
-
-\textit{FFMpeg}:
-
-\begin{center}
- \begin{tabular}{{p{4cm} p{10cm}}}
- -b:v <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.\\
-\end{tabular}
-\end{center}
-
-\textit{Note 1}: Bitrate is specified in kbps, or kilobits per second. In video compression a kilobit is generally assumed to be 1000 bits (not 1024).
-
-\textit{Note 2:} Other codecs in FFMpeg accept the \textit{-crf} parameter but may interpret the value differently. If you are using \textit{-crf} with other codecs you will likely use different values for VP9.
-
-\texttt{bitrate=1024k}\\
-\texttt{minrate=512k}\\
-\texttt{maxrate=1485k}\\
-\texttt{crf=32}
-
-\textit{Tiling} splits the video into rectangular regions, which allows multi-threading for encoding and decoding. The number of tiles is always a power of two. 0=1 tile; 1=2; 2=4; 3=8; 4=16; 5=32\\
-\texttt{tile-columns=2}
-
-(modified from {\small \url{https://trac.ffmpeg.org/wiki/EncodingForStreamingSites}})
-
-To use a 2 second \textit{GOP} (Group of Pictures), simply multiply your output frame rate $\times$ 2. For example, if your input is \textit{-framerate 30}, then use \textit{-g 60}.\\
-\texttt{g=240}
-
-number of \textit{threads} to use during encoding\\
-\texttt{threads=8}
-
-\textit{Quality} may be set to good, best, or realtime\\
-\texttt{quality=good}
-
-\textit{Speed}: this parameter has different meanings depending upon whether quality is set to good or realtime. Speed settings 0-4 apply for VoD in good and best, with 0 being the highest quality and 4 being the lowest. Realtime valid values are 5-8; lower numbers mean higher quality\\
-\texttt{speed=4}
+where \textit{imagelist.sh} is just the name chosen for this script which could
+be anything but has to be executable, \textit{outfile} is the sequence list
+that is created, \textit{infiles*.jpg} are the
+format\_type files such as \textit{jpg} in this example. The xxxtopnm
+messages that show up can just be ignored such as: \texttt{jpegtopnm: WRITING PPM FILE and jpegtopnm: Error writing row.}
+You may have to edit this script to suit your needs or to include specific directory locations. See also \nameref{ssub:filelist_format}.
\section{Details about .bcast5 Files}
\label{sec:details_.bcast5_files}
+\index{.bcast5}
The following extensions of files in \CGG{}'s \texttt{.bcast5} directory are explained below.
\item [.rc] rc stands for \textit{run commands} so basically represents a script
\item [.toc] toc is \textit{table of contents} file for MPEG video files (a type of index)
\item [Cinelerra\_plugins] a list of the currently loaded plugins available in your \CGG{} session
- \item [Cinelerra{}\_rc] the user's preferences and settings are saved in this file to be used on startup
+ \item [Cinelerra{}\_rc] the user's preferences and settings are saved in this file to be used on startup. This file can be carefully edited to change startup values for certain parameters, but if you inadvertently set up something incorrectly, you may end up crashing the program.
+ \item [ContextManual.pl] the user's configurable version of the Perl script which drives the Context Help feature
\item [ladspa\_plugins{\dots}] list of currently loaded ladspa plugins for each version of \CGG{} being used
\item [layout\#...\_rc] user-defined window layout setup with the layout name as part of the file name
\item [.xml] used for various backups or for the current settings of plugins that you have used
\item [.png] thumbnails of files in Resources so they do not have to be created over and over
\end{labeling}
+\section{Focusing the 4 main windows as a group}
+\label{sec:focus_group}
+
+When working with multiple programs it is often the case where a set of windows needs to be minimized
+or maximized temporarily while working with a different program. This can be a little awkward with
+\CGG{} because there are 4 distinct windows that are treated individually. To improve the workflow
+so that the 4 are minimized or maximized together as a group, you can use a routine called \textit{xdotool}.
+This will help to automatically focus all 4 of the windows as one window while still letting the user
+reposition the 4 screens. The "focusing windows as a group" option makes it so that you can quickly
+move back and forth between this program and other programs. Here is how to do this.
+
+\begin{description}
+ \item Install xdotool \url{https://www.semicomplete.com/projects/xdotool/}
+
+ \item Iconifying all Cinelerra windows at once:
+\newline xdotool search --name Cinelerra windowminimize \%@
+ \item Reactivating all Cinelerra windows at once:
+\newline xdotool search --name Cinelerra windowactivate \%@
+\end{description}
+
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../CinelerraGG_Manual"
\chapter{Configuration, Settings and Preferences}%
\label{cha:configuration_settings_preferences}
+\index{configuration}
+\index{settings}
+\index{preferences}
\begin{figure}[htpb]
\centering \includegraphics[width=0.9\linewidth]{settings.png}
\label{fig:settings}
\end{figure}
-The user's default settings, preferences, and other helpful files are retained across sessions in a hidden file, called .bcast5, in the user’s \texttt{\$HOME} directory. Initially when \CGG{} is launched there is an empty project and there are program default settings, and from then on the \texttt{.bcast5} directory will contain the settings that were set when quitting. If you need to revert to the default settings, delete the \texttt{.bcast5} directory contents and restart \CGG{}. Or you may want to rename it temporarily if you think you might want it back later.
-Although the location defaults to \texttt{\$HOME/.bcast5}, you can use the \texttt{CIN\_CONFIG} variable to override this location. For example: \texttt{export CIN\_CONFIG=/tmp/.bcast5} will use a temporary setup for testing purposes. It is also useful for multiple users sharing the same home directory who would like to have different configuration/preferences settings data. And if you are experiencing inexplicable errors or crashes in \CGG{}, they may be due to a problem with \texttt{.bcast5} in which case taking it out of the picture can at least eliminate this as the cause.
+\section{.bcast5}%
+\label{sec:bcast5}
+\index{bcast5}
-Several ways exist to change \CGG{}’s operational characteristics. A lot of variations can be made to settings and preferences by using the \textit{Settings} pulldown from the main window and choosing \textit{Preferences}.
+The user's default settings, preferences, and other helpful files are retained across sessions in a hidden file, called \texttt{.bcast5}, in the user’s \texttt{\$HOME} directory. Initially when \CGG{} is launched there is an empty project and there are program default settings, and from then on the \texttt{.bcast5} directory will contain the settings that were set when quitting. If you need to revert to the default settings, delete the \texttt{.bcast5} directory contents and restart \CGG{}. Or you may want to rename it temporarily if you think you might want it back later.
+Although the location defaults to \texttt{\$HOME/.bcast5}, you can use the \texttt{CIN\_CONFIG} variable to override this location. For example: \texttt{export CIN\_CONFIG=/tmp/.bcast5} will use a temporary setup for testing purposes. It is also useful for multiple users sharing the same home directory who would like to have different configuration/preferences settings data. And if you are experiencing inexplicable errors or crashes in \CGG{}, they may be due to a problem with \texttt{.bcast5} in which case taking it out of the picture can at least eliminate this as the cause. Another use case is if we want multiple installations of \CGG{}, for example one stable and one experimental, we can create the \texttt{.bcastX} folder externally and then set it as default with the option \textit{Index files go here} in \nameref{sub:index_file_section}.
+
+Several ways exist to change \CGG{}’s operational characteristics. A lot of variations can be made to settings and preferences by using the \textit{Settings} pulldown from the main window and choosing \textit{Preferences}.
+
+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}
\CGG{} supports 2 separate preferences for the playback configuration. \CGG{} can be operated in a single or dual screen configuration, both by using Xinerama or dual screen configuration of X windows. It will take some setup using Xconfig to make this work.
\begin{figure}[htpb]
\centering
- \includegraphics[width=0.75\linewidth]{multi-screen01.png}
+ \includegraphics[width=0.9\linewidth]{multi-screen01.png}
\caption{Multi-screen Playback example useful for watching \CGG{} run on the \textit{big screen}}
\label{fig:multi-screen01}
\end{figure}
-Figure~\ref{fig:multi-screen01} shows partial window of \textit{*Playback A} selected and the second tab for \textit{Playback B}. Note that on the bottom right of the window, \textit{Default B Display:} is set to $:0.1$, representing the setting for Screen 1. On the unseen \textit{Playback A} window, the \textit{Default A Display:} will be set to $:0.0$ meaning for Screen 0. Otherwise, the default would be nothing there or just <empty>.
+Figure~\ref{fig:multi-screen01} shows partial window of \textit{*Playback A} selected and the second tab for \textit{Playback B}. Note that on the bottom right of the window, \textit{Default B Display:} \index{default A/B display} is set to $:0.1$, representing the setting for Screen 1. On the unseen \textit{Playback A} window, the \textit{Default A Display:} will be set to $:0.0$ meaning for Screen 0. Otherwise, the default would be nothing there or just <empty>.
\subsection{Audio Out section}%
\label{sub:audio_out_section}
The audio drivers are used for both recording and playback. The Audio Out settings affect the outcome when you play sound on the timeline.
\begin{description}
- \item[Playback buffer samples] for playing audio, small fragments of sound are read from disk and processed sequentially. A larger value here causes more latency when you change mixing parameters but yields more reliable playback. Some sound drivers do not allow changing of the fragment, so latency is unchanged no matter what the value. Since different stages of the rendering pipeline can change the rate of the incoming data, it would be difficult to disconnect the size of the console fragments from the size of the fragments read from disk.
- \item[Audio offset (sec)] the ability to tell the exact playback position on Linux sound drivers is poor. The audio offset allows users to adjust the position returned by the sound driver in order to reflect reality. The audio offset does not affect the audio playback or rendering at all. It merely changes the synchronization of video playback. The easiest way to set the audio offset is to create a timeline with one video track and one audio track. Expand the audio track and center the audio pan. The frame rate should be larger than $24 fps$ and the sampling rate should be greater than $32000$. The frame size should be small enough for your computer to render it at the full framerate. Highlight a region of the timeline starting at 10 seconds and ending at 20 seconds. Drop a gradient effect on the video track and configure it to be clearly visible. Drop a synthesizer effect on the audio and configure it to be clearly audible. Play the timeline from 0 and watch to see if the gradient effect starts exactly when the audio starts. If it does not, expand the audio track and adjust the nudge. If the audio starts ahead of the video, decrease the nudge value. If the audio starts after the video, increase the nudge value. Once the tracks play back synchronized, copy the nudge value to the audio offset value in preferences. Note: if you change sound drivers or Disable hardware synchronization, you will need to change the audio offset because different sound drivers are unequally inaccurate.
- \item[View follows playback] this causes the timeline window to scroll when the playback cursor moves. This can slow down the X Server or cause the timeline window to lock up for long periods of time while drawing the assets.
- \item[Disable hardware synchronization] most sound cards and sound drivers do not give reliable information on the number of samples the card has played. You need this information for synchronization when playing back video. This option causes the sound driver to be ignored and a software timer to be used for synchronization.
+ \item[Playback buffer samples] \index{playback buffer samples} for playing audio, small fragments of sound are read from disk and processed sequentially. A larger value here causes more latency when you change mixing parameters but yields more reliable playback. Some sound drivers do not allow changing of the fragment, so latency is unchanged no matter what the value. Since different stages of the rendering pipeline can change the rate of the incoming data, it would be difficult to disconnect the size of the console fragments from the size of the fragments read from disk.
+ \item[Audio offset (sec)] \index{audio offset} the ability to tell the exact playback position on Linux sound drivers is poor. The audio offset allows users to adjust the position returned by the sound driver in order to reflect reality. The audio offset does not affect the audio playback or rendering at all. It merely changes the synchronization of video playback. The easiest way to set the audio offset is to create a timeline with one video track and one audio track. Expand the audio track and center the audio pan. The frame rate should be larger than $24 fps$ and the sampling rate should be greater than $32000$. The frame size should be small enough for your computer to render it at the full framerate. Highlight a region of the timeline starting at 10 seconds and ending at 20 seconds. Drop a gradient effect on the video track and configure it to be clearly visible. Drop a synthesizer effect on the audio and configure it to be clearly audible. Play the timeline from 0 and watch to see if the gradient effect starts exactly when the audio starts. If it does not, expand the audio track and adjust the nudge. If the audio starts ahead of the video, decrease the nudge value. If the audio starts after the video, increase the nudge value. Once the tracks play back synchronized, copy the nudge value to the audio offset value in preferences. Note: if you change sound drivers or Disable hardware synchronization, you will need to change the audio offset because different sound drivers are unequally inaccurate.
+ \item[View follows playback] \index{view follows playback} this causes the timeline window to scroll when the playback cursor moves. This can slow down the X Server or cause the timeline window to lock up for long periods of time while drawing the assets.
+ \item[Disable hardware synchronization] \index{disable hardware synchronization} most sound cards and sound drivers do not give reliable information on the number of samples the card has played. You need this information for synchronization when playing back video. This option causes the sound driver to be ignored and a software timer to be used for synchronization.
\item[Audio playback in realtime priority (root only)] for really old computers, this setting allows uninterrupted playback during periods of heavy load. It forces the audio playback to the highest priority in the kernel. Today, it is most useful for achieving very low latency between console tweaks and sound card output. You must be root to get real-time priority. Only experts might want to use this because it interferes with ordinary time-share scheduling and can lock up the system. When this is enabled, audio gets the first shot and burns audio until audio lets go. To explain, there are 2 kinds of scheduling, \textit{time-sharing} which is the default, and \textit{real time} where the scheduled task must explicitly request scheduling to allow other tasks to execute. Time-share interrupts when you use up your allocated time slice. Realtime priority audio will execute audio decode until it finishes, which may slow down other types of processing like video decoding. Most decoders use a policy that video may be downsampled to accommodate scheduling, but will never skip audio because it creates a much more obvious defect. This feature helps to make sure audio gets priority over video during decode. Be sure to check apply in order for this feature to take effect.
- \item[Map 5.1$\rightarrow$2] playback 5.1 $\rightarrow$ 2 driver downmix maps 6 tracks to 2 channels when checked, that is mixes $5.1$ down to stereo on the output device side. This is different from the patchbay and menubar functions which reset the pan/mix levels of the input channels. In this way, you can render $5.1$ media, and use stereo speakers to listen in the same session setup. This downmix only occurs if the playback is $5.1$ (6 channels) and the device config is stereo (2 channels).
- \item[Gain] set audio gain to a different value than the default of $1.0$ This feature, device level gain, corrects for hardware conditions which some devices may need to be useful. For example, you may need to increase the gain for a weak microphone or a noisy speaker, since it affects rendering when you crank up or down the audio via use of the patchbay. With the audio H/W gain support, you have the ability to fine tune the audio volume by some numerical value for the scale. You are adjusting the scaling of data into the audio driver -- H/W scaling is done before it goes into or out of the driver. This is a one time linear multiplication of the sample values, and may offer better control than the logarithmic DB gain controls of the application.
- \item[Audio driver] there are many sound drivers for Linux. This allows selecting one sound driver and setting parameters specific to it. The currently available possibilities are listed next.
+ \item[Map 5.1$\rightarrow$2] \index{audio!map 5.1:2} playback 5.1 $\rightarrow$ 2 driver downmix maps 6 tracks to 2 channels when checked, that is mixes $5.1$ down to stereo on the output device side. This is different from the patchbay and menubar functions which reset the pan/mix levels of the input channels. In this way, you can render $5.1$ media, and use stereo speakers to listen in the same session setup. This downmix only occurs if the playback is $5.1$ (6 channels) and the device config is stereo (2 channels).
+ \item[Gain] \index{audio!gain} set audio gain to a different value than the default of $1.0$ This feature, device level gain, corrects for hardware conditions which some devices may need to be useful. For example, you may need to increase the gain for a weak microphone or a noisy speaker, since it affects rendering when you crank up or down the audio via use of the patchbay. With the audio H/W gain support, you have the ability to fine tune the audio volume by some numerical value for the scale. You are adjusting the scaling of data into the audio driver -- H/W scaling is done before it goes into or out of the driver. This is a one time linear multiplication of the sample values, and may offer better control than the logarithmic DB gain controls of the application.
+ \item[Audio driver] \index{audio!driver} there are many sound drivers for Linux. This allows selecting one sound driver and setting parameters specific to it. The currently available possibilities are listed next.
\begin{description}
\item[\textit{ALSA}] is the most common sound driver these days and supports almost all sound cards. ALSA
is frequently updated but is very stable.
\item[\textit{Raw 1394, DV 1394, IEC 61883}] are older audio drivers used by camcorders and not much else.
\item[Pulseaudio] Extends the functionality of ALSA. It is a more modern and highly supported driver.
\end{description}
- \item[Device] with the down arrow, you can see the device choices on your computer.
+ \item[Device] \index{audio!device} with the down arrow, you can see the device choices on your computer.
\item[Bits] 8, 16 or 24 Bit Linear are the current choices for the number of bits of precision \CGG{} should set the device for. The meaning of the number of bits can be misleading. Some sound drivers need to be set to 32 bits to perform 24 bit playback and will not play anything when set to 24 bits. Other sound drivers need to be set to 24 bits for 24 bit playback.
\item[Stop playback locks up] this ALSA only checkbox is needed if stopping playback causes the software to lock up. This has worked some time ago, but may no longer work as expected
\end{description}
The video drivers are used for video playback in the compositor and the viewer. These determine how you will see video on the timeline.
\begin{description}
- \item[Play every frame] this causes every frame of video to be displayed even if it means that the playback of the video tracks fall behind. Most likely you will want this enabled because, after all, in order to edit you want to see each frame. However, if you are just watching a big video, you can switch to not play every frame so that you can at least not be distracted by slowness.
- \item[Framerate achieved] the number of frames per second being displayed during playback. This is updated during playback only. The goal is to get as close to the frame rate as possible, even if Play every frame is not enabled.
- \item[Scaling equation] Enlarge / Reduce -- this algorithm is used when video playback involves scaling or translation (only X11 video driver). This does not affect $1:1$ playback. Choices available are:
+ \item[Play every frame] \index{play every frame} this causes every frame of video to be displayed even if it means that the playback of the video tracks fall behind. Most likely you will want this enabled because, after all, in order to edit you want to see each frame. However, if you are just watching a big video, you can switch to not play every frame so that you can at least not be distracted by slowness.
+ \item[Framerate achieved] \index{framerate achivied} the number of frames per second being displayed during playback. This is updated during playback only. The goal is to get as close to the frame rate as possible, even if Play every frame is not enabled.
+ \item[Scaling equation] \index{scaling equation} Enlarge / Reduce -- this algorithm is used when video playback involves scaling or translation (only X11 video driver). This does not affect $1:1$ playback. Choices available are:
\begin{description}
\item[\textit{Nearest Neighbor / Nearest Neighbor}] low quality output with fast playback. Often produces jagged edges and uneven motion.
\item[\textit{Bicubic / Bicubic}] Bicubic interpolation is used for both enlarging and reducing, enlarging blurs slightly but does not show stair step artifacts.
\item[TOC Program No] Table of Contents program number used in DVB ??
\item[Interpolate CR2 images] enables interpolation of CR2 images. Interpolation is required since the raw image in a CR2 file is a Bayer pattern. The interpolation uses dcraw's built-in interpolation and is very slow. This operation can be disabled and the Interpolate Pixels effect used instead for faster previewing
\item[White balance CR2 images] this enables white balancing for CR2 images if interpolation is also enabled. This is because proper white balancing needs a blending of all 3 primary colors. White balance uses the camera's matrix which is contained in the CR2 file. Disabling white balancing is useful for operations involving dark frame subtraction. The dark frame and the long exposure need to have the same color matrix. If you disable Interpolate CR2 Images and use the Interpolate Pixels effect, be aware the Interpolate Pixels effect always does both interpolation and white balancing using the camera's matrix, regardless of the settings in Preferences. Dark frame subtraction needs to be performed before Interpolate Pixels.
- \item[Video driver] normally video on the timeline goes to the compositor window during both continuous playback and when the insertion point is repositioned. Instead of sending video to the Compositor window, the video driver can be set to send video to another output device during continuous playback. However, this does not affect where video is routed when the insertion point is repositioned. Options are listed next.
+ \item[Video driver] \index{video!driver} normally video on the timeline goes to the compositor window during both continuous playback and when the insertion point is repositioned. Instead of sending video to the Compositor window, the video driver can be set to send video to another output device during continuous playback. However, this does not affect where video is routed when the insertion point is repositioned. Options are listed next.
\begin{description}
- \item[\textit{X11}] this was the first method of graphical display on Unix systems. It just writes the RGB triplet for each pixel directly to the window. It is useful when graphics hardware can not handle very large frames. And when X11 is usled with the associated checkbox enabled of \textit{use direct x11 render if possible} it can be a really good playback method to speed up playback for large frames.
+ \item[\textit{X11}] this was the first method of graphical display on Unix systems. It just writes the RGB triplet for each pixel directly to the window. It is useful when graphics hardware can not handle very large frames. And when X11 is used with the associated checkbox enabled of \textit{use direct x11 render if possible} it can be a really good playback method to speed up playback for large frames.
\item[\textit{X11-XV}] this was an enhancement to X11 in 1999. It converts YUV to RGB in hardware with scaling. In some cases it may be the preferred playback method, but it can not handle large frame sizes. Maximum video size for XV is usually $1920\times1080$.
\item[\textit{X11-OpenGL}] the most powerful video playback method is OpenGL. With this driver, most effects are done in hardware with the graphics board installed in the computer. OpenGL allows video sizes up to the maximum texture size, which is usually larger than what XV supports, depending on the graphics driver. OpenGL relies on PBuffers and shaders to do video rendering. Plugins or transitions that do not have \textit{handle OpenGL} in the code will use software instead of hardware and this will slow down playback.
OpenGL does not affect rendering. It just accelerates playback. X11-OpenGL processes everything in 8 bit color models, although the difference between YUV and RGB is retained. The scaling equation set in the preferences window is ignored by OpenGL -- it always uses linear scaling. Camera and projector operations use OpenGL, but some of the effects may not support OpenGL acceleration.
\section{Recording}%
\label{sec:recording}
+\index{preferences!recording}
The parameters here expedite the \texttt{File $\rightarrow$ Record}\dots function by allowing the user to pre-configure the file format and the hardware used for recording, since the hardware generally determines the supported file format. Once set, the file format is applied to all recordings.
\label{sub:file_format_section}
\begin{description}
- \item[File Format] this determines the output file format for recordings. It depends heavily on the type of driver used. The menu selections are the same as those of the rendering interface.
- \item[Record audio tracks] toggle must be enabled to record audio.
- \item[Record video tracks] toggle must be enabled to record video. The wrench button left of both the audio and video tracks toggle, opens a configuration dialog in order to set the compression scheme (codec) for each audio and video output stream. The audio and video is wrapped in a container format defined by the \textit{File Format} menu. Different wrappers may record audio only, video only, or both. Some video drivers can only record to a certain container. If the video driver is changed, the file format may be updated to give the supported output. If you change the file format to an unsupported format, it may not work with the video driver.
+ \item[File Format] \index{file format} this determines the output file format for recordings. It depends heavily on the type of driver used. The menu selections are the same as those of the rendering interface.
+ \item[Record audio tracks] \index{record audio tracks} toggle must be enabled to record audio.
+ \item[Record video tracks]\index{record video tracks} toggle must be enabled to record video. The wrench \index{wrench} button left of both the audio and video tracks toggle, opens a configuration dialog in order to set the compression scheme (codec) for each audio and video output stream. The audio and video is wrapped in a container format defined by the \textit{File Format} menu. Different wrappers may record audio only, video only, or both. Some video drivers can only record to a certain container. If the video driver is changed, the file format may be updated to give the supported output. If you change the file format to an unsupported format, it may not work with the video driver.
\item[Realtime TOC] setup for DVB recording to automatically generate a Table of Contents. This will scan the stream data \textit{on the fly} on its way to being written while the asset is being captured. ??
\end{description}
\label{sub:audio_in_section}
\begin{description}
- \item[Record Driver] is used for recording audio in the Record window. It may be configured the same as the Record Driver for video if the audio and video are wrapped in the same stream. Available parameters vary depending on the driver. The drivers are the same as described in Playback A/B with the addition of DVB and V4L2 MPEG but no Raw 1394.
+ \item[Record Driver] \index{audio!record driver} is used for recording audio in the Record window. It may be configured the same as the Record Driver for video if the audio and video are wrapped in the same stream. Available parameters vary depending on the driver. The drivers are the same as described in Playback A/B with the addition of DVB and V4L2 MPEG but no Raw 1394.
\item[DVB Adapter] name of a suitable DVB adapter for linux that is usb connected to your computer and has a connected broadcast TV antenna.??
\item[dev] your DVB adapter device number, which is usually 0.
\item[Bits] same as described in Playback A/B audio section.
\item[Follow audio config] ??
- \item[Samples read from device] a good value is $2048$ or approximate dev buffer size ($2k-16k$ probably).
+ \item[Samples read from device] \index{sample read from device} a good value is $2048$ or approximate dev buffer size ($2k-16k$ probably).
Samples to write to disk -- at a time. First, audio is read in small fragments from the device. Then, many small fragments are combined into a large fragment before writing to disk. The disk writing process is done in a different thread. The value here determines how large the combination of fragments is for each disk write. A good starting value is $48000$ but this will will most likely automatically change, probably to $44100$ if necessary.
- \item[Sample rate for recording] regardless of what the project settings are, the value set here will be the sample rate used for recording. The sample rate should be set to the highest value the audio device supports.
+ \item[Sample rate for recording] \index{samples read from recording} regardless of what the project settings are, the value set here will be the sample rate used for recording. The sample rate should be set to the highest value the audio device supports.
\item[Channels to record] usually set to 2.
- \item[Map 5.1$\rightarrow$2] eave unchecked to record all possible channels.
- \item[Gain] usually leave at default of $1.0$, but this device level gain corrects for hardware conditions on some devices which need help. This gives you the ability to fine tune the audio volume by some numerical value for the scale. It is useful as better explained for the Gain in the Playback A/B Audio section discussed previously.
+ \item[Map 5.1$\rightarrow$2] \index{audio!map 5.1:2} eave unchecked to record all possible channels.
+ \item[Gain] \index{audio!gain} usually leave at default of $1.0$, but this device level gain corrects for hardware conditions on some devices which need help. This gives you the ability to fine tune the audio volume by some numerical value for the scale. It is useful as better explained for the Gain in the Playback A/B Audio section discussed previously.
\item[Record in realtime priority] (root only) -- only experts might want to use this because it interferes with ordinary time-share scheduling and can lock up the system. When this is enabled, audio gets the first shot and burns audio until audio lets go.
\end{description}
\label{sub:video_in_section}
\begin{description}
- \item[Record driver] used for recording video in the Record window. It may be configured the same as the Record Driver for video if the audio and video are wrapped in the same container. Available parameters vary depending on the driver. The drivers available are as follows.
+ \item[Record driver] \index{video!record driver} used for recording video in the Record window. It may be configured the same as the Record Driver for video if the audio and video are wrapped in the same container. Available parameters vary depending on the driver. The drivers available are as follows.
\begin{itemize}
\item Video4Linux2
\item JPEG webcam
\section{Performance}%
\label{sec:performance}
+\index{preferences!performance}
\subsection{Performance section}%
\label{sub:performance_section}
-The main focus of the performance section is rendering parameters not available in the rendering dialog with the obvious gain of perhaps better performance.
+The main focus of the performance section is rendering parameters not available in the rendering dialog with the obvious gain of perhaps better performance. For more details about using GPU hardware acceleration for both decoding and encoding see \nameref{sec:hardware_video_acceleration}.
\begin{description}
- \item[Cache size] to speed up rendering, several assets are kept open simultaneously. This determines how many are kept open. A number too large may exhaust your memory rapidly. A number too small may result in slow playback as assets need to be reopened more frequently.
- \item[Seconds to preroll renders] some effects need a certain amount of time to settle in. Checking this option sets a number of seconds to render without writing to disk before the selected region is rendered. When using the render farm, you will sometimes need to preroll to get seamless transitions between the jobs. Every job in a render farm is prerolled by this value. This does not affect background rendering because background rendering uses a different preroll value.
- \item[Force single processor use] \CGG{} tries to use all processors on the system by default, but sometimes you will only want to use one processor, like in a render farm client. This forces only one processor to be used. The operating system usually uses the second processor for disk access. The value of this parameter is used in render farm clients.
- \item[Project SMP cpus ] to restrict the number of processors utilized, change the count number. This number will be used for the plugin per load balance operation cpu limit, which uses smp-cpus to stripe your data. It does not affect the number of cpus used in any other \CGG{} operation besides plugins. On large cpu systems, it can come in handy to downgrade the number of cpus used for some plugins; otherwise it uses all of the processors and splits up the program into too many pieces which may add
- considerable overhead in high cpu count systems.
+ \item[Cache size] \index{cache size} to speed up rendering, several assets are kept open simultaneously. This determines how many are kept open. A number too large may exhaust your memory rapidly. A number too small may result in slow playback as assets need to be reopened more frequently.
+ \item[Cache Transition] transitions can be slow on timeline playback. With this parameter (active by default) a cache is used to smooth the transition. You might see a slight hesitation at the beginning of a transition when memory is being loaded then quite often it will play at full speed.
+ \item[Seconds to preroll renders] \index{pre-roll} some effects need a certain amount of time to settle in. Checking this option sets a number of seconds to render without writing to disk before the selected region is rendered. When using the render farm, you will sometimes need to preroll to get seamless transitions between the jobs. Every job in a render farm is prerolled by this value. This does not affect background rendering because background rendering uses a different preroll value.
+ \item[Force single processor use] \index{force single processor} \CGG{} tries to use all processors on the system by default, but sometimes you will only want to use one processor, like in a render farm client. This forces only one processor to be used. The operating system usually uses the second processor for disk access. The value of this parameter is used in render farm clients.
+ \item[Project SMP cpus] \index{SMP cpus} to restrict the number of processors utilized, change the count number. This number will be used for the plugin per load balance operation cpu limit, which uses smp-cpus to stripe your data. It does not affect the number of cpus used in any other \CGG{} operation besides plugins. On large cpu systems, it can come in handy to downgrade the number of cpus used for some plugins; otherwise it uses all of the processors and splits up the program into too many pieces which may add considerable overhead in high cpu count systems.
+ \item[Use HW Device] \index{HW Device} \CGG{} can use hardware timeline acceleration (decoding) via GPUs thanks to the \textit{OpenGL} video driver. By default the \textit{X11} video driver is used, which works only with the CPU. See \nameref{sub:video_out_section}. For h264, h265 (HEVC) and VP9 codecs you can use libraries specific to AMD, Nvidia and Intel graphics cards. For AMD and Intel set \textbf{vaapi}; for Nvidia set \textbf{vdpau} (also works with AMD thanks to a wrapper). \textbf{Cuda} does not accelerate decoding with Nvidia, but it does allow some plugins to run that are not available otherwise. \textbf{None} (default) uses the video driver set in the \texttt{Playback A/B} tab.
\end{description}
\subsection{Background Rendering section}%
\label{sub:background_rendering_section}
\begin{description}
- \item[Use background rendering] checking this box, enables automatic background rendering. This works in conjunction with the interactive function \texttt{Settings menu $\rightarrow$ Toggle background rendering} which sets the point where background rendering starts up to the position of the insertion point.
- \item[Frames per background rendering job] his only works if a render farm is being used; otherwise, background rendering creates a single job for the entire timeline. The number of frames specified here is scaled to the relative CPU speed of rendering nodes and used in a single render farm job.
- \item[Frames to preroll background] the number of frames to render ahead of each background rendering job. Background rendering is degraded when preroll is used since the jobs are small. When using background rendering, this number is ideally 0. Some effects may require 3 frames of preroll.
- \item[Output for background rendering] background rendering generates a sequence of image files in a certain directory. This parameter determines the filename prefix of the image files. It should be on a disk, accessible to every node in the render farm by the same path.
- \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 is a good choice usually.
- \item[Video wrench] this has the single option of \textit{use alpha}. It is by default unchecked.
+ \item[Use background rendering] \index{background rendering!use} checking this box, enables automatic background rendering. This works in conjunction with the interactive function \texttt{Settings menu $\rightarrow$ Toggle background rendering} which sets the point where background rendering starts up to the position of the insertion point.
+ \item[Frames per background rendering job] \index{frame per job} his only works if a render farm is being used; otherwise, background rendering creates a single job for the entire timeline. The number of frames specified here is scaled to the relative CPU speed of rendering nodes and used in a single render farm job.
+ \item[Frames to preroll background] \index{frame per pre-roll} the number of frames to render ahead of each background rendering job. Background rendering is degraded when preroll is used since the jobs are small. When using background rendering, this number is ideally 0. Some effects may require 3 frames of preroll.
+ \item[Output for background rendering] \index{background rendering!output} background rendering generates a sequence of image files in a certain directory. This parameter determines the filename prefix of the image files. It should be on a disk, accessible to every node in the render farm by the same path.
+ \item[File format] \index{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 is a good choice usually.
+ \item[Video wrench] \index{wrench} this has the single option of \textit{use alpha}. It is by default unchecked.
\end{description}
\subsection{Render Farm section}%
\section{Interface}%
\label{sec:interface}
+\index{preferences!interface}
\subsection{Editing section}%
\label{sub:editing_section}
\begin{description}
- \item[Clicking on edit boundaries] (trimming) \CGG{} not only allows you to perform editing by dragging edit boundaries, but also defines five separate operations that occur when you drag an edit boundary. Here you can select the behavior of each mouse button. The usage of each editing mode is described in great detail in the \hyperref[sub:split_view_compositor_using_drag_trim]{Editing} chapter.
- \item[Keyframe reticle] the options are \textit{Newer}, \textit{Dragging}, or \textit{Always}. This is used to help in checking edit alignment across tracks. Always renders a line over all plugins, and dragging only over the drag icon. Never draws nothing.
- \item[Snapshot path] designates the default directory path for snapshot and grabshot generated output.
+ \item[Clicking on edit boundaries] \index{trim} (trimming) \CGG{} not only allows you to perform editing by dragging edit boundaries, but also defines five separate operations that occur when you drag an edit boundary. Here you can select the behavior of each mouse button. The usage of each editing mode is described in great detail in the \hyperref[sub:split_view_compositor_using_drag_trim]{Advanced Editing} chapter.
+ \item[Keyframe reticle] \index{keyframe reticle} the options are \textit{Newer}, \textit{Dragging}, or \textit{Always}. This is used to help in checking edit alignment across tracks. Always renders a line over all plugins, and dragging only over the drag icon. Never draws nothing.
+ \item[Snapshot path] \index{snapshot!path} designates the default directory path for snapshot and grabshot generated output.
\end{description}
\subsection{Operation section}%
\label{sub:operation_section}
\begin{description}
- \item[Probe Order] clicking on this box brings up a popup allowing you to change the probe order usually for media that is raw camera output but it is also helpful if you want to ensure that a specific driver is used for certain media; for example you may want \textit{tiff} files to be read natively instead of by ffmpeg.
+ \item[Probe Order] \index{probe order} clicking on this box brings up a popup allowing you to change the probe order usually for media that is raw camera output but it is also helpful if you want to ensure that a specific driver is used for certain media; for example you may want \textit{tiff} files to be read natively instead of by ffmpeg.
\item[trap sigSEGV] always enable this so that if \CGG{} crashes, a dump will be generated for analysis.
\item[trap sigINT] always enable this so that you can use Ctrl-c to interrupt the program if it appears to be hanging. This will often generate some useful information for analysis.
- \item[Use yuv420p dvd interlace format] for DVD media 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.
+ \item[Use yuv420p dvd interlace format] \index{DVD!yuv420p interlace mode} for DVD media 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.
\item[Min / Max DB for meter] \textit{Min DB} is useful because some sound sources have a lower noise threshold than others. Everything below the noise threshold is meaningless. This option sets the meters to clip below a certain level. \textit{Max DB} sets the maximum sound level represented by the sound meters. This value is presented merely to show how far over the limit a sound wave is. No matter what this value is, no sound card can play sound over 0 dB.
\item[Import images with a duration of \# seconds] when you load single images, like \textit{png} or \textit{jpeg}, automatically load for \# number of seconds. This makes it easier to see an image on the timeline. If you just want the single frames, uncheck this option.
- \item[Auto start lv2 gui] some lv2 plugins display a \textit{glitzy} UI (User Interface); for example the Calf plugins. For these LV2 plugins, if you want that to automatically come up without having to click on the UI button on the simplified ui interface, this is the flag to enable that.
+ \item[Auto start lv2 gui] \index{LV2 gui} some lv2 plugins display a \textit{glitzy} UI (User Interface); for example the Calf plugins. For these LV2 plugins, if you want that to automatically come up without having to click on the UI button on the simplified ui interface, this is the flag to enable that.
\item[Android Remote Control] check this to enable using an android device as a remote control for broradcast TV.
\item[Port] default port 23432 is used for the android remote control.
\item[Pin] default PIN Cinelerra is used for the android remote control.
- \item[Shell Commands] this button brings up the controls for setting up your own shell commands or editing previously set up commands. See the section on Menu Bar Shell Commands for information.
- \item[Reload plugin index] execute this reload command when you have modified plugins and want to make sure your changes take effect.
- \item[Nested Proxy Path] designates the default directory path for Nested Proxy files.
- \item[Default LV2\_Path] when there is no system \texttt{LV2\_PATH} set, if you want lv2 plugins loaded, you must set the correct directory path name here. When you change this field, cin will automatically restart and load the newly specified lv2 plugins.
+ \item[Shell Commands] \index{shell commands} this button brings up the controls for setting up your own shell commands or editing previously set up commands. See the section on Menu Bar Shell Commands for information.
+ \item[Reload plugin index] \index{plugins!reload index} execute this reload command when you have modified plugins and want to make sure your changes take effect.
+ \item[Nested Proxy Path] \index{nested proxy path} designates the default directory path for Nested Proxy files.
+ \item[Default LV2\_Path] \index{default lv2 path} when there is no system \texttt{LV2\_PATH} set, if you want lv2 plugins loaded, you must set the correct directory path name here. When you change this field, cin will automatically restart and load the newly specified lv2 plugins.
\end{description}
\subsection{Index Files section}%
Screencast below shows part of the Preferences menu where you can change the index files setup (figure~\ref{fig:index}).
\begin{figure}[htpb]
\centering
- \includegraphics[width=1.0\linewidth]{images/index.png}
+ \includegraphics[width=1.0\linewidth]{images/index-01.png}
\caption{Index file setup for your preferred configuration for Render Farm sharing or anything}
\label{fig:index}
\end{figure}
\begin{description}
- \item[Index files go here] index files exist in order to speed up drawing the audio/video tracks. This option determines where index files are placed on the disk.
- \item[Size of index file] determines the size of an index file. Larger index sizes allow smaller files to be drawn faster, while slowing down the drawing of large files. Smaller index sizes allow large files to be drawn faster, while slowing down small files. The default is currently 4kB for average size files.
- \item[Number of index files to keep] to keep the index directory from becoming very large, old index files are deleted. This determines the maximum number of index files to keep in the directory.
- \item[build ffmpeg marker indexes] improves ffmpeg seeks in certain cases although not clear which ones.
+ \item[Index files go here] \index{index file!path} index files exist in order to speed up drawing the audio/video tracks. This option determines where index files are placed on the disk
+ \item[Size of index file] \index{index file!size} determines the size of an index file. Larger index sizes allow smaller files to be drawn faster, while slowing down the drawing of large files. Smaller index sizes allow large files to be drawn faster, while slowing down small files. The default is currently 4kB for average size files.
+ \item[Number of index files to keep] \index{index file!number} to keep the index directory from becoming very large, old index files are deleted. This determines the maximum number of index files to keep in the directory.
+ \item[build ffmpeg marker indexes] \index{ffmpeg!build index} improves ffmpeg seeks in certain cases although not clear which ones.
\item[Scan for commercial during toc build] used for working with broadcast TV commercial removal.
- \item[Delete existing indexes] when you change the index size or you want to clean out excess index files, this deletes all the index files.
- \item[Delete clip thumbnails] as clip thumbnails accumulate over time, you may want to delete them to get the disk space back.
+ \item[Delete existing indexes] \index{index file!delete} when you change the index size or you want to clean out excess index files, this deletes all the index files.
+ \item[Delete clip thumbnails] \index{delete clip thumbnails} as clip thumbnails accumulate over time, you may want to delete them to get the disk space back.
\end{description}
\section{Appearance}%
\label{sec:appearance}
+\index{preferences!appearance}
\subsection{Layout section}%
\label{sub:layout_section}
-\paragraph{Theme} \CGG{} supports 11 different themes to suit the preferences of different
+\paragraph{Theme} \index{theme} \CGG{} supports 11 different themes to suit the preferences of different
users (figure~\ref{fig:theme}). When you change the theme, \CGG{} automatically saves your
session and restarts exactly where you were. The \textit{Themes User Interface} are described
in more detail next. \textit{Akirad} themes are all available in Cin-GG as designed by the
To create a personal theme see \hyperref[sec:how_create_theme]{How to create your own theme}.
-\paragraph{Plugin Icons} here are currently 4 choices for different plugin icons to include the old original.
-\paragraph{Locale} The default is \textit{sys} so that the system language is active. With the pulldown menu we can choose among the other languages present in ... This language will be saved in
+\paragraph{Plugin Icons} \index{plugins!icons} There are currently 4 choices for different plugin icons to include the old original.
+\paragraph{Locale} \index{locale/language} The default is \textit{sys} so that the system language is active. With the pulldown menu we can choose among the other languages present in ... This language will be saved in
your Configuration and used each time you start up CinGG. In order to change the environment variable, LANGUAGE, the setting must be \textit{sys} because that is the best way we could get it working.
-\paragraph{Layout Scale} allows for setting up scaling for your 4K monitors or any monitor where you would like the text and icons to be just a little bigger or a lot bigger. This scale setting is automatically saved across sessions.
+\paragraph{Layout Scale} \index{layout scale} Allows for setting up scaling for your 4K monitors or any monitor where you would like the text and icons to be just a little bigger or a lot bigger. This scale setting is automatically saved across sessions.
When first using \CGG{}, or if \textit{Layout Scale} has never been set, the initial value is 0.0.
This means an automatic probe of the biggest monitor in use will be used for the setting. The advantage of this is that "new users" with a 4K monitor will not immediately be discouraged with too small text/icons.
Leaving it at 0 instead of 1 is what most people will do and is probably preferable so that if you move to a different monitor with different dimensions/resolution, it will automatically probe.
\begin{lstlisting}[numbers=none]
BC_SCALE=1.0 {your Cinelerra path}/bin/cin
\end{lstlisting}
-\paragraph{View thumbnail size} you can increase or decrease the thumbnail size -- larger size uses more cpu.
-\paragraph{Vicon quality} increase the quality used for thumbnails to get more clarity of pixels -- this will use more memory.
-\paragraph{Vicon color mode} modify the color mode to Low, Medium, or High for the thumbnails -- High will look the best but takes more memory.
+\paragraph{View thumbnail size} \index{view thumbnais size} You can increase or decrease the thumbnail size -- larger size uses more cpu.
+\paragraph{Vicon quality} \index{vicon!quality} Increase the quality used for thumbnails to get more clarity of pixels -- this will use more memory.
+\paragraph{Vicon color mode} \index{vicon!color mode} Modify the color mode to Low, Medium, or High for the thumbnails -- High will look the best but takes more memory.
\subsection{Time Format section}%
\label{sub:time_format_section}
+\index{timebar}
Various representations of time are given so that you can select the most convenient one for you. The time representation can also be changed by Ctrl-clicking on the timebar in the main window.
\label{sub:color_section}
-\paragraph{Highlighting Inversion color} modify the selection area color; default is \textit{ffffff} which is white. When you make a selection, that area becomes an inverse image which by default becomes a whitish color. You can set it to a different color by modifying the hex value in the box next to \textit{Highlight inversion color}. Keep in mind that if you set the value to a low value, you will not be able to see the outlined selected area (for example the hex value "f" is not readily visible and leads to confusion). A leading 0 or blank is not allowed and will be automatically changed to \textit{ffffff}.
-\paragraph{YUV color space} default is \textit{BT601}; others \textit{BT709} (high definition), \textit{BT2020} (ultra high definition).
-\paragraph{YUV color range} JPEG [$0-255$] and MPEG [$16-235$]
+\paragraph{Highlighting Inversion color} \index{inverted colors} Modify the selection area color; default is \textit{ffffff} which is white. When you make a selection, that area becomes an inverse image which by default becomes a whitish color. You can set it to a different color by modifying the hex value in the box next to \textit{Highlight inversion color}. Keep in mind that if you set the value to a low value, you will not be able to see the outlined selected area (for example the hex value "f" is not readily visible and leads to confusion). A leading 0 or blank is not allowed and will be automatically changed to \textit{ffffff}.
+\paragraph{Composer BG Color} \index{background color} You can choose the background color of the viewer window.
+\paragraph{YUV color space} \index{yuv color space} Default is \textit{BT601}; others \textit{BT709} (high definition), \textit{BT2020} (ultra high definition). PAL and NTSC have different color primaries, so $BT 601\_NTSC$ = SMPTE 170M = BT 601\_525 and $BT 601\_PAL$ = BT 470 BG = BT 601\_625. BT 2020 can be $BT 2020\_NCL$ (non-constant luminance) or $BT 2020\_CL$ (constant luminance). NCL is the standard.
+\paragraph{YUV color range} \index{yuv color range} JPEG [$0-255$] and MPEG [$16-235$]
\subsection{Warnings section}%
\label{sub:warnings_section}
\begin{description}
- \item[ffmpeg probe warns rebuild indexes] this warning is very important for switching from using ffmpeg to using native formats, such as in the case of MPEG, so that you are reminded to \textit{rebuild indexes}. If you do not rebuild the indexes, seeking on the timeline back and forth could very well be problematic, meaning it might not go to the right place. Notification about rebuilding the indexes will appear by default as shown in the figure~\ref{fig:ff_probe} when you click on the FF icon in the main timeline in the upper right hand corner. Once you click on \textit{Don’t show this warning again} you will no longer be warned and this flag will no longer be enabled.
+ \item[ffmpeg probe warns rebuild indexes] \index{warnings!ffmpeg probe} this warning is very important for switching from using ffmpeg to using native formats, such as in the case of MPEG, so that you are reminded to \textit{rebuild indexes}. If you do not rebuild the indexes, seeking on the timeline back and forth could very well be problematic, meaning it might not go to the right place. Notification about rebuilding the indexes will appear by default as shown in the figure~\ref{fig:ff_probe} when you click on the FF icon in the main timeline in the upper right hand corner. Once you click on \textit{Don’t show this warning again} you will no longer be warned and this flag will no longer be enabled.
\begin{figure}[htpb]
\centering \includegraphics[width=0.9\linewidth]{ff_probe.png}
\caption{Default warning when you click on FF icon in main window}
\label{fig:ff_probe}
\end{figure}
- \item[EDL version warns if mismatched] in the case of a Batch Render, it is often helpful to be warned if the EDL has been changed so that you are aware that what is going to be rendered is different than your current EDL session.
- \item[Create Bluray warns if not root] if checked and you are 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[Warn on creating file references] if checked, you will always be warned when using "File by
+ \item[EDL version warns if mismatched] \index{warnings!EDL version} in the case of a Batch Render, it is often helpful to be warned if the EDL has been changed so that you are aware that what is going to be rendered is different than your current EDL session.
+ \item[Create Bluray warns if not root] \index{warnings! bluray no root} if checked and you are 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[Warn on creating file references] \index{warnings! file by reference} if checked, you will always be warned when using "File by
Reference", that is when an EDL is opened as \textit{Reference}. This is best left checked to ensure that you are aware of the fact that when changes are made to this file and rendered, any other uses of the same file will be affected and modified also.
\end{description}
+\subsection{Dangerous section}%
+\label{sub:dangerous_section}
+
+\begin{description}
+ \item[Unsafe GUI in batchrender] It serves to hide the button \textit{Save to EDL Path} present in the Batch Render window. In fact if used accidentally, it could lead to the loss of the original EDL content, which is overwritten without changing the project name. See Batch Rendering, section \nameref{sub:advanced_features}.
+ \item[Autosave continuous backups] For each editing action \CGG{} creates an automatic backup. To avoid excessive creation, this option limits their number to 50 when quitting out of the program.
+\end{description}
+
\subsection{Flags section}%
\label{sub:flags_section}
This section contains many useful options to cater to the various preferences of individual users.
\begin{description}
- \item[Autocolor assets] to make it visually easier to see your clips on the timeline that are from the same media file, you can have them automatically colored. Use of this feature requires additional memory and cpu on every timeline redraw, therefore smaller computers may not want this checked on.
- \item[Perpetual session] is very useful for working on a project over many days so you can just quit before
+ \item[Autocolor assets] \index{autocolor assets} to make it visually easier to see your clips on the timeline that are from the same media file, you can have them automatically colored. Use of this feature requires additional memory and cpu on every timeline redraw, therefore smaller computers may not want this checked on.
+ \item[Perpetual session] \index{perpetual session} is very useful for working on a project over many days so you can just quit before
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] 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.
- \item[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] 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[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] 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[Popups activate on button up] this is the default but if unchecked, popups activate on button down.
- \item[Set Input Focus when window entered] 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] Click to activate text focus
- \item [Click to deactivate text focus] if checked, you will have to click to deactivate text focus.
- \item [Auto rotate ffmpeg media] this is the default setting so that your media will automatically be rotated when there is metadata in the file with a rotation value. Especially useful for cell phone.
+ \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
+ \item [Click to deactivate text focus] \index{click to deactivate text focus} if checked, you will have to click to deactivate text focus.
+ \item [Auto rotate ffmpeg media] \index{auto rotate ffmpeg media} this is the default setting so that your media will automatically be rotated when there is metadata in the file with a rotation value. Especially useful for cell phone.
\end{description}
\section{About}%
\label{sec:about}
+\index{preferences!about}
This section gives you information about the \CGG{} program and version you are running. The original author’s copyright and name are first and foremost. Next is a textbox with additional information and a summary of the monthly new features of note. Below that is a summary of the GPL License and the fact that it is provided without any warranty. Then the licensing verbage is the item that you may need to refer to most often -- the \textit{built} date and time in case you need to know which version you are currently running.
\section{Environment Variables for Customization}%
\label{sec:environment_variables_customization}
+\index{configuration!environment variables}
Environment variables are global variables in the shell which all applications can read. They are set with a command like \texttt{set VARIABLE=value} or \texttt{export VARIABLE=value}. Environment variables can be viewed with a command like \texttt{env}. The values set can be removed with \texttt{unset VARIABLE}.
\begin{description}
\item[{\small CIN\_BROWSER}] name of browser to use by \textit{Shell Cmds} options
- \item[{\small CIN\_BROWSER}] configuration data; defaults to \texttt{\$HOME/.bcast5}
+ \item[{\small CIN\_CONFIG}] configuration data; defaults to \texttt{\$HOME/.bcast5}
\item[{\small CIN\_DAT}] location of data files, such as documentation, models, tip of the day
\item[{\small CIN\_LADSPA}] LADSPA directory path; use colons to separate multiple paths; this is convenient to define an alternate directory if you share the same executable directory among computers via NFS.
\item[{\small CIN\_LIB}] location of library programs, such as bdwrite
\chapter{DVD and Bluray Creation}%
\label{cha:dvd_bluray_creation}
+\index{DVD}
+\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.
+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.
-The max disk space needed is a little over $100GB$ for $50GB$ Double Layer (DL) media or $50GB$ for a single layer BD blu-ray. A standard SD of $4.7GB$ needs about $10GB$ disk space. You probably can get by with much less if the render for blu-ray is less than 25 hours of media. You will need twice as much disk space as the media holds to ensure you have sufficient space for working and copying.
+The amount of data you have to render determines the amount of disk space you will need for working. The max disk space needed for a completely full media disc is a little over $100GB$ for $50GB$ Double Layer (DL) media or $50GB$ for a single layer BD blu-ray. A standard SD of $4.7GB$ needs about $10GB$ disk space. You will need much less if the render for blu-ray is less than 25 hours of media. Generally you will need twice as much disk space as will be written on the media to ensure you have sufficient space for working and copying.
The most important thing you need to know about in order to get started is \textit{Format} and \textit{Scale} in the \textit{Create dvd or bd} window. Format settings shown in the \texttt{Set Format} window are set accordingly to an algorithm. Basically, it will take whatever you say in the asset format. It matches that against the known Presets available so that is what will be shown. If the asset format doesn't match any of the Presets default formats, then that will be shown as the \textit{User Defined} format. In addition when you load media, the format is initially set to \textit{same as source} so matches the source input and if that matches a known preset, then that is what is shown. The PAL versus NTSC only comes into play when there is no known correct matching format when you attempt to create a DVD Render batch job. It is applied when you click OK. For example, if you load up a YouTube video, it will not match any known format and will choose PAL or NTSC based on time zone.
\label{fig:preset01}
\end{figure}
-A quick set of basic steps to create DVDs is immediately below and usually just using the defaults will get you something. However there is a serious issue with interaction between the Operating System and bdwrite when creating a BD/blu-ray that requires automount to be turned off. Refer to the details and more specific explanations below the following steps for how to do this.
+A quick set of basic steps to create DVDs is immediately below and usually just using the defaults will get you something. However there is a serious issue with interaction between the Operating System and bdwrite when creating a BD/blu-ray that requires automount to be turned off. For more details on using automount see: ~\ref{sec:bluray_workaround_mount_umount}.
\begin{enumerate}
\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.
\item Load your media, format if needed, note device name to substitute for \textit{<bd>} or \textit{<dvd>}
\begin{itemize}
\item If rewritable blu-ray, use \\
- \texttt{dd if=./bd.udfs of=/dev/<bd> bs=2048000}
+ \texttt{dd if=./bd.udfs of=/dev/<bd> bs=2048000} \\
+ Note: unwritten media must be quickly formatted one time using: \\
+ \texttt{dvd+rw-format /dev/bd}
\item If write-once blu-ray, use \\
\texttt{growisofs -dvd-compat -Z /dev/<bd>=./bd.udfs}
\item If any DVD media, use \\
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{itemize}
\item Format frame rates choices are $29.97$ or $25$ for SD, based on the user's timezone, with NTSC 29.97/US or PAL 25 /EU. For BD, the media input will be analyzed to automatically pick the default format or if unknown, the user's timezone will be used to default to $1920/29.97i$ for US or $1920/25i$ for EU. Be sure to set the rendering parameters in the \texttt{settings $\rightarrow$ format} menu.
\item Choose audio stereo or 5.1, again depending on your media.
- \item Target Geometry will be $720\times480$ (US) or $720\time576$ (EU) for SD.
+ \item Target Geometry will be $720\times480$ (US) or $720\times576$ (EU) for SD.
\end{itemize}
\textit{Step 2}: From the main window, select \texttt{file $\rightarrow$ BD Render} or select \texttt{file $\rightarrow$ DVD Render} (figure~\ref{fig:bluray_dvd}). Then:
\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.
\item[Histogram] remaps the color space. The color space ranges from $0-255$ for 8-bit color values. You can use this tool to remap the color space to use the entire space or for stretching the contrast. Also, it lets you perform global color-correction on the image. You can use this to correct for color screens that are \textit{too blue}, or for color Televisions that produce \textit{brownish} output, or whatever. In addition to color-correction, you can use the RGB modification tool to add color to images that didn't have color to begin with. For instance, you can \textit{pseudo-color} greyscale media.
\item[Inverse Telecine] the reverse of $3:2$ pulldown where frames, which were duplicated to create 60-fields/second video from 24-frames/second film, are removed. MPEG-2 video encoders usually apply an inverse Telecine process to convert 60-fields/second video into 24-frames/second encoded video. The encoder adds information enabling the decoder to recreate the 60-fields/second display rate. \textit{Telecine}, i.e. $3:2$ pulldown, is used to transfer film to video. That's where the $3:2$ ratio comes in. To ensure that there will consistently be 60 frames per second, the first frame is displayed on the TV screen 3 times and the second frame is displayed 2 times. The following frame is repeated 3 times, the next one 2 times, etc. throughout the film. For inverse telecine, you show 2 of the film frames for 3 of output frames. Only check \textit{Inverse Telecine} if you have film or something that is $24fps$ and want to project to $30fps$ (most likely this will never be necessary).
\item[Audio 5.1] 6 channel surround sound. For most home systems, uses five full bandwidth channels and one low-frequency effects channel. Could automatically get set as explained previously.
\item[Aspect Ratio] aspect ratio may be automatically set to $4:3$ or $16:9$. Aspect ratio would better be defined as the size of the display, monitor, or TV which will be used to view the output. If you measure your old TV, which supposedly is $4:3$ and your latest digital TV, which is supposedly $16:9$, you will see that those ratios aren't always correct anyway. Then measure your laptop monitor, your desktop monitor, and your neighbor's, and lo and behold, the ratios don't fit either of the purported \textit{standard} aspect ratio. Maintaining square pixels via scaling is more important in the long run.
\item[Use FFMPEG] this is user's choice; it is recommended and faster but more difficult to modify due to numerous options. For blu-ray, ffmpeg must be used and is not an available option.
\item[Resize Tracks] change track width and height as explained previously. The size is adjusted to the largest frame size needed.
- \item[Chapters at Labels] without this checked, chapters markers are automatically inserted every 5 minutes. The chapter labels can then be \textit{skipped to} when playing the DVD. If instead, you want to put labels in at opportune times, you will have to run dvdauthor outside of \CGG{} and mark the chapter labels yourself by hand. In that case, you should checkbox \textit{Chapters at Labels} so that the automatic 10-minute labels are not created. This checkbox is not currently available for blu-ray.
+ \item[Chapters at Labels] for DVDs without this checked, chapter markers are automatically inserted every 5 minutes. The chapter labels can then be \textit{skipped to} when playing the DVD. If instead, you want to put labels in at opportune times, you will have to run dvdauthor outside of \CGG{} and mark the chapter labels yourself by hand. In that case, you should check the box \textit{Chapters at Labels} so that the automatic 5-minute labels are not created. This checkbox is not currently available for blu-ray, but you can easily create
+chapters on blu-ray by adding '-c timeinterval in ticks' as the first argument to bdwrite in the bd.sh job
+generated by “BD Render” and then executing that job manually. On 1 test computer 100 ticks equalled 20 seconds. When "use tsmuxer" option is included, there is by default a chapter every 5 minutes. This
+can be customized by modifying the bd.meta file associated with your current
+job, changing the '--auto-chapters=5' to your choice in minutes instead of 5, and then rerunning the
+pertinent lines seen in your window.
\end{description}
\begin{figure}[htpb]
\item Click OK check button.
\end{itemize}
-The default bitrate is the largest value possible. The actual \textit{target} bitrate is calculated based on a formula from the blu-ray/DVD code. It divides the media size (in bits) by the video time (in seconds) to find the bitrate that will \textit{just fit} on the target media. This could create a weird bitrate if the media is large, and the video time is small, so the default/target bitrate is limited to $10Mb/s$.Batch jobs are then built and appended to the job list. Once these batch jobs are built, if you make any changes, you have to start over. You will see listed the batch jobs that are created to perform the rendering/tasks -- 2 jobs for blu-ray, one for audio/video processing and one for the scripts. There will be 3 batch jobs created for DVD when not using ffmpeg to include one each for audio and video and then one more for the scripts. When you click on \texttt{start}, it fires off those jobs and you will see the rendering main window progress bar in the bottom corner reflecting the fact that it is currently processing. Be aware that the \CGG{} program will be totally shutdown AFTER the batch jobs finish. Screenshot below shows BD blu-ray creation with 2 batch jobs queued up and ready to go.
+The default bitrate is the largest value possible. The actual \textit{target} bitrate is calculated based on a formula from the blu-ray/DVD code. It divides the media size (in bits) by the video time (in seconds) to find the bitrate that will \textit{just fit} on the target media. This could create a weird bitrate if the media is large, and the video time is small, so the default/target bitrate is limited to $10Mb/s$.Batch jobs are then built and appended to the job list. Once these batch jobs are built, if you make any changes, you have to start over. You will see listed the batch jobs that are created to perform the rendering/tasks -- 2 jobs for blu-ray, one for audio/video processing and one for the scripts. There will be 3 batch jobs created for DVD when not using ffmpeg to include one each for audio and video and then one more for the scripts. When you click on \texttt{start}, it fires off those jobs and you will see the rendering main window progress bar in the bottom corner reflecting the fact that it is currently processing. Be aware that the \CGG{} program will be totally shutdown AFTER the batch jobs finish.
-Figure~\ref{fig:dvd-batch01} for DVD and Figure~\ref{fig:dvd-batch02} for BD shows a creation render ready to be started. Note that because it is not ffmpeg, the processing of video is done separately from audio. If you need to modify the video tracks, which you can see is ghosted out, you need to highlight the first batch job listed. Be sure to highlight the first batch job before pressing Start so it runs all of the jobs and be sure the X for job enabled is set.
+Figure~\ref{fig:dvd-batch01} for DVD and Figure~\ref{fig:dvd-batch02} for BD show creation renders with batch jobs queued up and ready to be started. Note that because it is not ffmpeg, the processing of video is done separately from audio. If you need to modify the video tracks, which you can see is ghosted out, you need to highlight the first batch job listed. Be sure to highlight the first batch job before pressing Start so it runs all of the jobs and be sure the X for job enabled is set.
\begin{figure}[htpb]
\centering
This will produce a new directory in your target path which contains a filesystem image file.
For example: \\
-\texttt{/TargetDirectory/bd\_20150820-093747} \\
+\texttt{/<target directory>/bd\_(or dvd\_)<date-time>/} \\
Directory and file names should not be changed at this time because the scripts and programs rely on the given names in order to proceed. You can change them later for your own purposes.
If bluray to test the filesystem you just created, use the command line interface; loopback mount the filesystem image which was generated in the target directory. For example if blu-ray:
\begin{lstlisting}[style=sh]
-cd /TargetDirectory/bd_20150820-093747/
+cd /<target directory>/bd_(or dvd_)<date-time>/
mount -o loop,ro ./bd.udfs ./udfs
#check the media using a compatible media rendering tool like ffplay
umount ./udfs...
\subsubsection*{Blu-ray Media}
\label{ssub:bluray_media}
+\index{BluRay}
For rewritable blu-ray (recommended) (BD-RE):
-Note: unwritten (virgin) media must be formatted first using:
+Note: new or previously unwritten media must be formatted first using:
\begin{lstlisting}[style=sh]
dvd+rw-format /dev/bd #only done once and does not take very long
To write or rewrite rewritable blu-ray media:
\begin{lstlisting}[style=sh]
-cd /TargetDirectory/bd_20150820-093747/
+cd /<target directory>/bd_(or dvd_)<date-time>/
dd if=./bd.udfs of=/dev/bd bs=2048000 #the growisofs command below also works
\end{lstlisting}
To write blu-ray write-once media: (BD-R) (no pre-formatting needed):
\begin{lstlisting}[style=sh]
-cd /TargetDirectory/bd_20150820-093747/
+cd /<target directory>/bd_(or dvd_)<date-time>/
growisofs -dvd-compat -Z /dev/bd=./bd.udfs
\end{lstlisting}
\subsubsection*{DVD Media}
\label{ssub:dvd_media}
+\index{DVD}
For rewritable DVD (DVD+RW):
-Note: unwritten (virgin) media must be formatted first using:
+Note: unwritten media must be formatted first using:
\begin{lstlisting}[style=sh]
dvd+rw-format /dev/dvd #only done once and does not take very long
To write a DVD, load blank media and run the following from the command line (requires dvdauthor):
\begin{lstlisting}[style=sh]
-cd /TargetDirector/dvd_20160404-175416
+cd /<target directory>/bd_(or dvd_)<date-time>/
growisofs -dvd-compat -Z /dev/dvd -dvd-video ./iso
\end{lstlisting}
\subsubsection*{SD Example: Partial Output during \CGG{} run}
\label{ssub:sd_example_partial_output}
+\index{DVD!partial output messages run}
\begin{lstlisting}[style=sh]
...
\subsubsection*{BD Example: Partial Output during \CGG{} run}
\label{ssub:bd_example_partial_output}
+\index{BluRay!partial output messages run}
\begin{lstlisting}[style=sh]
...
\subsubsection*{SD Example – Partial Output during writing disc media}
\label{ssub:sd_example_partial_output_writing}
+\index{DVD!partial output messages writing}
\begin{lstlisting}[style=sh]
growisofs -dvd-compat -Z /dev/sr0 -dvd-video /tmp/dvd_20161224-160756/iso
\subsubsection*{BD Example – Partial Output during writing disc media}
\label{ssub:bd_example_partial_output_writing}
+\index{BluRay!partial output messages writing}
\begin{lstlisting}[style=sh]
growisofs -dvd-compat -Z /dev/sr0=/tmp/bd_20161224-155658/bd.udfs
\section{Debugging DVDs Creation}%
\label{sec:debugging_dvd_creation}
+\index{DVD!debugging}
+\index{BluRay!debugging}
This section contains helpful hints, how to initially check the results, and some information on determining what might have gone wrong and how to address it.
\subsubsection*{Checklist for Troubleshooting}
\label{ssub:checklist_troubleshooting}
+\index{DVD!troubleshooting}
+\index{BluRay!troubleshooting}
\begin{itemize}
\item Are you logged in as root? This is required in order to loopback mount files for bluray and to write media on \texttt{/dev/hardware}. See section \hyperref[sec:bluray_workaround_mount_umount]{13.7} for a workaround for normal user mode.
\item Did you correctly interpret the frame rate if using interlaced format to be $\frac{1}{2}$ due to interlacing?
\end{itemize}
-\section{Subtitles}%
-\label{sec:subtitles}
+\section{DVD-Subtitles}%
+\label{sec:dvd_subtitles}
+\index{DVD!subtitles}
-DVD (not blu-ray... yet) subtitles are added by using the main window pulldown \texttt{File $\rightarrow$ Subtitle} which brings up a window allowing you to type the filename of a previously generated text file containing the desired words/lines, the script. After entering the filename, click \texttt{Load} to read in your script. By creating a script file ahead of time, it lets you easily add dialog that was already written out and carefully edited for spelling and proper grammar.
-
-The format of the script/text input file has specific requirements as listed below:
-
-\begin{itemize}
- \item Lines can be any length but they will be broken up to fit according to some criteria below.
- \begin{itemize}
- \item Running text used as script lines will be broken into multiple lines.
- \item The target line length is 60 characters.
- \item Punctuation may be flagged to create an early break.
- \item Single carriage return ends an individual script line.
- \item Double carriage return indicates the end of a entry and helps to keep track of where you are.
- \end{itemize}
- \item The "\textit{=}" sign in column 1 indicates a comment seen in the script text to assist you in location.
- \item An "\textit{*}" at the beginning of the line is a comment and not a script line.
- \item \textit{Whitespace} at either the beginning of a script line or the end will be removed.
-\end{itemize}
-
-Figure~\ref{fig:subtitle01} shows the Subtitle window you will see.
-
-\begin{figure}[htpb]
- \centering
- \includegraphics[width=0.8\linewidth]{subtitle01.png}
- \caption{Subtitle window}
- \label{fig:subtitle01}
-\end{figure}
-
-To put the subtitles onto your media, first add a subtitle track via the pulldown \texttt{Track $\rightarrow$ Add Subttl}. In the Subtitle window, note that there are 2 major textboxes. There is the \textit{Script Text} textbox showing the current entry of text from your input file and there is the \textit{Line Text} textbox showing the currently active text. In your subtitle track, select a timeline region (in/out or drag select with hairline cursor/highlight) to indicate the region where you want the active Line Text to be pasted. Then click the \texttt{Paste} button in the Subtitle window to paste the line onto the subtitle track. Silence will be added to the subtitle track in the places in the media where there are gaps.
-
-Editing in the Line Text box can be used to change the active script line. By double clicking the timeline over the subtitle track, you can reselect the active script line. The subtitle text will be reloaded into the Line Text box and can be edited and re-pasted as the new active subtitle text. You can also highlight multiple lines in the Script Text box and paste them (using the usual window paste methodology) into the Line Text box. After pasting to the timeline, the Line Text box will be updated with the next script line. In addition, if you triple click a line in the \textit{Script Text} box, it will automatically become the current line in the \textit{Line Text} box.
-
-When you are finished, before clicking \textit{Save}, you must supply a legitimate filename in the \textit{Path} box; your current directory will be used if only a filename but no directory path is supplied. The filename used will automatically have a "--" after it followed by the \textit{track label} and then \textit{udvd} extension added; any extension in the filename will be removed.. If you click OK before saving, the subtitle script position is saved with the session. This is convenient for continuing where you left off.
-
-\noindent To reposition the script, use the slider or tumbler buttons:
-
-\textit{Slider} bar to move through the text entries quickly. \\
-\textit{Prev} or \textit{Next} buttons to go to the previous or next script line.
-
-\begin{figure}[htpb]
- \centering
- \includegraphics[width=1.0\linewidth]{subtitle02.png}
- \caption{Subtitles on timeline}
- \label{fig:subtitle02}
-\end{figure}
-
-\noindent Figure~\ref{fig:subtitle02} shows what the pasted subtitle script looks like in a portion of the main window.
+\CGG{} supports the .udvd format of DVDs, so you can create subtitles on the timeline and then save them as .udvd files.
+For how the subtitle tool works see: \nameref{sec:subtitles}
+The subtitle format for Blu-Ray is PGS with a .sup extension which CinGG does not support. It is an image format (also 3D) so it can be created, converted and extracted only via specific OCR. You can use external programs like ffmpeg; SubTitle Editor; MKVToolNix; etc.
\section{Dvd Interlaced Chroma}%
\label{sec:dvd_interlaced_chroma}
+\index{DVD!yuv420p interlace mode}
\CGG{} uses 4:4:4 colorspace to edit, so it is necessary to convert interlaced 4:2:0 video to 4:4:4.
But you can run into problems, referred to as the \textit{chroma bug}, which you see in DVD media displayed on higher resolution monitors -- streaks or spiky horizontal lines are visible in the chroma channel, especially on diagonal edges. The Chroma Bug is specific to MPEG and 4:2:0 encoding.
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}
+\section{Creating Blu-ray Without Re-encoding}%
+\label{sec:bluray_without_reencoding}
+\index{BluRay!without re-encoding}
+\index{BluRay!camcorders}
+\index{BluRay!AVCHD}
-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.
+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:
-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.
+\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}}
+
+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}
\section{Blu-ray from Multiple \CGG{} Output}%
\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:
\section{How Builds Really Work and Even More Options}
\label{sec:builds_really_work_more_options}
+\index{build!more options}
This section describes how builds really work if you want to know more about making changes or understanding the process; probably only for a developer or system administrator.
\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
+ ./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 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]
-#!/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
+./confgure --with-single-user --disable-static-build --without-thirdparty --without-libdpx
\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.
+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}
+\index{build!configuration}
A listing of the current configuration features as of January 11, 2020:
--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)
\section{Thirdparty Parallel Build}
\label{sec:thirdparty_parallel_build}
+\index{build!thirdparty}
The Makefile in the thirdparty build directory employs a set of macros used to create a build rule set of thirdparty library build dependencies. The standard build sequence of [source, config, build] is used to prepare thirdparty products as static libraries. Build package dependency can be specified in the Makefile std-build macro call. These Makefile macro calls define the rules used for each thirdparty build. The expanded rule definitions may be viewed by using:
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}
+\index{build!use latest library}
Using the most current libraries can be a challenge for some of the Operating System distros that use
stable compilers, assemblers, and their own libraries. Because they are stable, they frequently do
\begin{description}[noitemsep]
\item Status - currently \CGG{} is staying at 0.5. This is disappointing because there
may be speed gains in version 0.6 that would be beneficial. However, it is usable for decoding
-whereas libaom is just too slow. Unfortunately, it has no effective encoder.
+whereas libaom is a lot slower. Unfortunately, it has no effective encoder.
\item Problem - 0.6 dav1d requires NASM 2.14 and uses instructions like vgf2p8affineqb,
not exactly an "add" instruction. It also uses meson which is not widely available on all
distros. The only distros that are built for \CGG{} that are at 2.14 are the latest version
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 1.0.0
- \item Problem - requires cmake 3.5
+ \item Status - currently at version 3.0.0 for older O/S and 3.1.1 for newer O/S
+ \item Problem - requires cmake 3.5 at 3.0.0 and 3.6 for 3.1.1
\item Workaround already in use by \CGG{} - leaving out of Ubuntu14, Ubuntu, Centos7
- \item Your workaround - upgrade on those systems to cmake 3.5
+ \item Your workaround - upgrade on those systems to cmake 3.6
\end{description}
\textbf{x10tv}
\section{Find Lock Problems with Booby Trap}
\label{sec:find_lock_problems_booby_trap}
+\index{build!booby trap}
A Booby Trap is used in \CGG{} for setting a trap to catch lock problems that might have been missed. It will trap boobies only if compile by adding \textit{-{}-with-booby} on the configuration command line. This is the default if you compile using \texttt{./bld.sh} from the GIT repository. It should not interfere with normal execution.
\section{Valgrind Support Level}
\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:
\texttt{CFLAGS=-ggdb make -j8 rebuild\_all}
\end{enumerate}
+If you frequently make mods and changes in \CGG{} or the thirdparty libraries, do not depend on those
+compiled versions to have the headers updated; so be sure to fully rebuild as shown in the previous 2
+steps before running valgrind or you will get false errors.
+
Now your \CGG{} obj has all of the debug stuff. Next run valgrind as root for the most useful results:
\hspace{2em}\texttt{cd /path/cinelerra-5.1/cinelerra}
This runs \CGG{} under the control of valgrind, and produces a log file in /tmp which will list information about any leaks, usually clearly identifiable. Be sure to Quit out of \CGG{} normally instead of Ctrl-C or a SEGV otherwise the program does not have a chance to cleanup and there will be some false alarms. But it runs very slowly, and is basically single threaded, which means that race conditions may be impossible to catch$\dots$ like one thread deletes memory that another thread is currently using. But overall it is a big help and if you test any new features, please email the log output. A lot of effort when writing the code was put into trying to be sure that all of the object constructors have matching destructors so that the leaks can be identified. There are already several libraries that create predictable memory leaks and valgrind does a good job for most of these.
-It is impossible to test everything with valgrind because some things are just too big and slow for a practical test. Occasionally you can find a leak or an illegal memory access. There are several false alarms that are difficult to avoid \textit{Conditional jump} messages, and \textit{unhandled DW\_OP\_}, but anything with the word \textit{illegal} in the message is important. Memory leaks that originate in \CGG{} are good to find and fix, but are usually not deadly.
+It is impossible to test everything with valgrind because some things are just too big and slow for a practical test. Occasionally you can find a leak or an illegal memory access. There are several false alarms that are difficult to avoid \textit{Conditional jump} messages, and \textit{unhandled DW\_OP\_}, but anything with the word \textit{illegal} in the message is important. Memory leaks that originate in \CGG{} are good to find and fix, but are usually not
+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{Prof2 -- A Profiler}
\label{sec:prof2_profiler}
+\index{build!prof2}
Frequently there is a problem with a program running slow and you do not know why. You need a thumbnail analysis of where the program is spending most of its time without all of the overwhelming details. This is when a Profiler comes in handy.
So why use a Profiler? Because it is the ``ls'' for executable functions!!
-\section{How to create your own theme}
+\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.
+
+\subsection{Managing AppImage}
+\label{sub:managing_appimage}
+\index{appimage!management}
+
+A limitation of using AppImage instead of installing the binary or compiling from git, is that there is only a single file without the ability to browse the directory structure or to look for files to edit or check. So if using \CGG{} leads to some errors, it is not possible to investigate and fix the problem. Which means if you want to add the most up-to-date Context-Help or want to introduce some custom presets, that can not be done.
+
+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} (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 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:
+
+\begin{lstlisting}[numbers=none]
+ /{path to appimage}/squashfs-root/usr/bin/./cin
+\end{lstlisting}
+
+After making your changes, to get back to having an appimage file instead of having to run the program from the bin folder, you can take the extra step of recompressing the squashfs-root folder.
+To do so use linuxdeploy's appimage, a program that can also be useful for creating appimages from scratch (\url{https://github.com/linuxdeploy/linuxdeploy/releases/continuous}).
+
+The steps to recreate the appimage are:
+
+\begin{enumerate}
+ \item Copy the linuxdeploy appimage to \texttt{/\{path to appimage\}} and make sure it is executable.
+ \item Then use the command:
+ \begin{lstlisting}[numbers=none]
+ ./linuxdeploy-x86_64.AppImage --appdir squashfs-root --output appimage
+ \end{lstlisting}
+\end{enumerate}
+
+A new appimage will be created like the original but containing the changes.
+
+Alternatively, download the \texttt{appimagetool} version from \url{https://github.com/AppImage/AppImageKit/releases} if available for your distro and use the command:
+
+\begin{lstlisting}[numbers=none]
+ ./appimagetool --comp /{path to appimage}/squashfs-root /tmpCinGG-yyyymmdd.AppImage
+\end{lstlisting}
+
+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}
+
+If a developer wants to create an appimage from git, follow these next few steps. An existing automated script is available, \texttt{bld\_appimage.sh}, in the directory \texttt{/\{path to cinelerra-5.1\}}.
+
+This follows four steps:
+
+\begin{itemize}
+ \item Build static version of \CGG{}.
+ \item If desired and needed, build the HTML manual for context-sensitive help.
+ \item Organize code and if present, the manual, in a AppImage specific format \textit{AppDir}. Do this with tool makeappimage, which is built if needed.
+ \item Call an external tool to make the AppDir into an AppImage
+\end{itemize}
+
+Start by downloading the \CGG{} source from Cinelerra's git. The last parameter is a directory name of your choice, the directory must not exist. As example, the name \textit{cinelerra5} is used.
+
+\begin{lstlisting}[numbers=none]
+ git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5
+\end{lstlisting}
+
+The source will be in a subdirectory \texttt{cinelerra-5.1} of the directory created by the \textit{git clone} operation.
+
+If context-sensitive help is needed, download the manual sources too, with a different destination directory.
+
+\begin{lstlisting}[numbers=none]
+ git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cin-manual-latex.git" cin-manual-latex
+\end{lstlisting}
+
+Then move to the \texttt{/\{path to cinelerra-5.1}/\} directory.
+
+
+There are two preliminaries to do before running the script:
+
+1- If context sensitive help in the appimage version is required, the source of the manual and the tools (packages) to build it must be on the system. In the bld\_appimage.sh script, set the variable \texttt{MANUAL\_DIRECTORY=\$(pwd)/../../ cin-manual-latex} to the path of the source of the manual. If the variable is empty, or the specified directory does not exist, \CGG{} will be built without built-in help. The path to the manual source can be an absolute or relative one.
+
+2- The script bld\_appimage.sh uses a platform specific version of appimagetool so that it can create appimages for \textit{x86\_64}, \textit{i686}, \textit{aarch64}, or \textit{armv7l} architecture. We need to add appimagetool-(platform).AppImage to the \texttt{/\{path to cinelerra- 5.1\}/tools} directory, or somewhere in your path. You can download the tool for your system (e.g. appimagetool-x86\_64.AppImage) from git: {\small\url{https://github.com/AppImage/AppImageKit/releases}}
+
+Always remember to make it executable. The four supported platforms are:
+
+\begin{itemize}
+ \item appimagetool-aarch64.AppImage
+ \item appimagetool-armhf.AppImage
+ \item appimagetool-i686.AppImage
+ \item appimagetool-x86\_64.AppImage
+\end{itemize}
+
+With the preparations done, let's go back to the bld\_appimage.sh script.
+
+Make the script executable if it isn't already:
+
+\begin{lstlisting}[numbers=none]
+chmod x+u bld_appimage.sh
+\end{lstlisting}
+
+Start the script with:
+
+\begin{lstlisting}[numbers=none]
+./bld_appimage.sh
+\end{lstlisting}
+
+The first part of the script customizes \texttt{configure}, depending on the architecture of our system. The next step compiles and installs \CGG{} in the \texttt{bin} subdirectory. The third part creates the manual in HTML; It will be the basis for the context help (see \nameref{sec:help_context_help}). The fourth part creates the directory \texttt{/AppDir/usr}, which is the basic structure of an appimage, and then populates it with the contents of \texttt{/\{path to cinelerra-5.1\}/bin}. Finally, the fifth step starts a script, called \texttt{makeappimage}, which points to \textit{bld.sh} contained in \texttt{/tools/makeappimagetool/}.
+
+The script specifies all executables that are part of \CGG{}, so makeappimage can pick up dependencies. Any executable code in other places is not picked up. makeappimage will populate the AppDir directory, and then call the platform dependent appimagetool found in \texttt{/\{path to cinelerra-5.1\}/tools}.
+
+At the end of the compilation there will be an appimage in the \texttt{cinelerra-5.1} directory, which we can move and use.
+
+\section{How to Create a new Theme}
\label{sec:how_create_theme}
+\index{theme!create new theme}
-A Theme is a base class object that is created and customized as \textit{ThemeName}.
+A \textit{Theme} is a base class object that is created and customized as \textit{ThemeName}.
It is constructed during program initialization in a theme plugin
\texttt{PluginTClient},
-defined in a \texttt{plugins/theme\_name} source directory.
+defined in \texttt{plugins/theme\_name} source directory.
\texttt{theme\_name.C} and \texttt{theme\_name.h} are derived \textit{Theme} class object constructors.
-A Theme is constructed during initialization in \texttt{init\_theme} (\texttt{mwindow.C}). The theme plugin is accessed using the \textit{name} from preferences, and that theme plugin is loaded, and it contains the code to construct that theme. A Theme object has functions and data that \CGG{} uses to do a variety of customizations, such as \texttt{default\_window\_positions}, and it can modify GUI defaults, like \\
-\texttt{default\_text\_color}, when it is initialized.
+A \textit{Theme} is constructed during initialization in \texttt{init\_theme} (\texttt{mwindow.C}). The theme plugin is accessed using the \textit{name} from preferences and then the theme plugin is loaded which contains the code to construct the theme. A \textit{Theme} object has functions and data that \CGG{} uses to do a variety of customizations, such as \texttt{default\_window\_positions}, and it can modify GUI defaults like \\
+\texttt{default\_text\_color} when it is initialized.
-The theme plugin contains a \textit{new\_theme} function, that allocates and constructs a
-\textit{ThemeName} object, with a base classes of \textit{BC\_Theme} (gui setup), \textit{Theme} (\CGG{} defaults), and \textit{ThemeName}, with definitions and overrides that create the custom theme. To create a new theme, a new plugin is needed:
+The theme plugin contains a \textit{new\_theme} function that allocates and constructs a
+\textit{ThemeName} object with base classes of \textit{BC\_Theme} (gui setup), \textit{Theme} (\CGG{} defaults), and \textit{ThemeName}, with definitions and overrides that create the custom theme. To create a new theme, a new plugin is needed:
\begin{lstlisting}[numbers=none]
#include "header files.h"
When a theme is constructed by \texttt{NameMain::new\_theme()}, it sets a pointer to a
block of data created in the plugin build that contains all of the png data
-files in the \texttt{plugins/theme\_name/data} directory. These images may define or override the appearance of gui images, such as \textit{ok.png} (the ok button). There are usually a large number of images that need to be defined. The theme plugin adds them to the theme image data in the \texttt{theme $\rightarrow$ initialize()} function. The best list of theme image setup is probably in SUV (\texttt{plugins/theme\_suv/suv.})
+files in the \texttt{plugins/theme\_name/data} directory. These images may define or override the appearance of gui images, such as \textit{ok.png} (the ok button). There are usually a large number of images that need to be defined. The theme plugin adds them to the theme image data in the \texttt{theme $\rightarrow$ initialize()} function. The best list of theme image setup is probably in SUV (\texttt{plugins/theme\_suv/suv}).
The easy way to create a new theme is to copy an existing theme and change
-its name to \textit{ThemeName}, and be sure to \texttt{change plugin\_title()} to the new name, then tweak the definitions until you are happy with the results. The file
-names and Makefile also need to be updated to the new theme \textit{name}. The source
-can by manually rebuilt by invoking make in the \texttt{plugins/theme\_name}
+its name to \textit{ThemeName}, change \texttt{plugin\_title()} to the new name, and then tweak the definitions until you are happy with the results. The file
+names and Makefile also need to be updated to the new theme name. The source
+can by manually rebuilt by invoking \textit{make} in the \texttt{plugins/theme\_name}
directory.
-Once it is built into the plugin library, it will be discovered by the plugin probe,
-and it will become an available theme in the \textit{Preferences}.
+Once the new theme is built into the plugin library, it will automatically be discovered by the plugin probe
+and it will become an available theme in \textit{Preferences}.
If you are ready to add it to the main build, then \textit{theme\_name} should be
-included in the DIRS targets of the \texttt{plugins/Makefile}, and the \texttt{plugin\_defs} needs \textit{theme\_name} in the themes list.
+included in the DIRS targets of the \texttt{plugins/Makefile}, and \texttt{plugin\_defs} needs \textit{theme\_name} in the themes list.
Themes usually require considerable time to create from scratch. For
example, the SUV theme has over 800 lines in the initialize function, and has over
500 png images in the data directory. Most of these images and data values are
required to be initialized by the custom theme constructor; very tedious and
time consuming work. Creating a new theme is usually a lot of work.
+
+\section{How Context Help works in the Program Code}
+\label{sec:context_help_coding}
+\index{context help}
+
+All class methods related to context help start with the common pattern \texttt{context \_help} in their names. It is easy to get all occurences in the code with the following command (example):
+
+\begin{lstlisting}[style=sh]
+ grep -F context_help `find . -name '*.[Ch]' -print`
+\end{lstlisting}
+
+The base functionality is defined in several \textit{BC\_WindowBase} class methods in \\ \texttt{guicast/bcwindowbase.C} (search on \texttt{context\_help}). All BC\_Window's and BC\_SubWindow's inherit these methods.
+
+For the simplest case of context help definition, it is sufficient to add the call to \texttt{context\_help\_set\_keyword()} in the most inclusive widget constructor. If \texttt{Alt/h} is pressed with the mouse over this widget's window, its \texttt{keypress\_event()} method (inherited from BC\_WindowBase) will catch this hotkey, fetch the keyphrase defined by \texttt{context\_help\_set\_keyword()} and call the \texttt{doc/ContextManual.pl} script with this keyphrase. Then ContextManual.pl script does the whole processing of the keyphrase given and calls web browser to display the found HTML manual page. The browser is called in the background to prevent from blocking the calling \CGG{} thread.
+
+An example from \textit{cinelerra/zoombar.C}:
+
+\begin{lstlisting}[style=sh]
+ ZoomBar::ZoomBar(MWindow *mwindow, MWindowGUI *gui)
+ : BC_SubWindow(...)
+ {
+ this->gui = gui;
+ this->mwindow = mwindow;
+ context_help_set_keyword("Zoom Panel");
+ }
+\end{lstlisting}
+
+If \texttt{Alt/h} is pressed with the mouse over some subwindow (arbitrary depth) of the \texttt{context\_help\_set\_keyword()} caller, the \texttt{keypress\_event()} method of that subwindow catches the hotkey. Its own context help keyword, probably, will be empty. In this case the whole widget hierarchy is traced up to \textit{top\_level} widget, their context help keywords are checked, and the first nonempty keyword is used for context help.
+
+This approach allows us to define the help keyword common to the whole dialog window with a bunch of diverse buttons with a single call to \texttt{context\_help\_set \_keyword()}, without placing such a call into each button constructor. And at the same time, this approach allows to assign different help keywords to GUI elements belonging to the same window but documented in different manual pages.
+
+\subsubsection{An example with several different help keywords from cinelerra/mwindowgui.C:}%
+\label{ssub:exemple_different_help_keywords}
+
+\begin{lstlisting}[style=sh]
+ MWindowGUI::MWindowGUI(MWindow *mwindow)
+ : BC_Window(_(PROGRAM_NAME ": Program"), ...)
+ {
+ this->mwindow = mwindow;
+ ...
+ context_help_set_keyword("Program Window");
+ }
+ ...
+ FFMpegToggle::FFMpegToggle(MWindow *mwindow, MButtons *mbuttons, int x, int y)
+ : BC_Toggle(...)
+ {
+ this->mwindow = mwindow;
+ this->mbuttons = mbuttons;
+ set_tooltip(get_value() ? FFMPEG_EARLY_TIP : FFMPEG_LATE_TIP);
+ context_help_set_keyword("FFmpeg Early Probe Explanation");
+ }
+ ...
+ StackButton::StackButton(MWindow *mwindow, int x, int y)
+ : BC_GenericButton(x, y, mwindow->theme->stack_button_w, "0")
+ {
+ this->mwindow = mwindow;
+ set_tooltip(_("Close EDL"));
+ context_help_set_keyword("OpenEDL");
+ }
+ ...
+ ProxyToggle::ProxyToggle(MWindow *mwindow, MButtons *mbuttons, int x, int y)
+ : BC_Toggle(...)
+ {
+ this->mwindow = mwindow;
+ this->mbuttons = mbuttons;
+ ...
+ context_help_set_keyword("Proxy");
+ }
+ \end{lstlisting}
+If the widget we wish to add context help to, overloads keypress\_event() of the base class with its own method, then it is necessary to introduce a small addition to its keypress\_event() handler: the call to \texttt{context\_help\_check\_and\_show()} has to be added in a suitable place in the handler.
+
+An example with \texttt{context\_help\_check\_and\_show()} from \textit{cinelerra/mbuttons.C}:
+\begin{lstlisting}[style=sh]
+ int MButtons::keypress_event()
+ {
+ int result = 0;
+ if(!result) {
+ result = transport->keypress_event();
+ }
+ if(!result) {
+ result = context_help_check_and_show();
+ }
+ return result;
+ }
+\end{lstlisting}
+
+All the keypress handlers are not equal, therefore we provide different variants of the methods context\_help\_check\_and\_show() and context\_help\_show() (the latter for explicit checking on hotkey).
+
+An example with context\_help\_show() from cinelerra/editpanel.C:
+\begin{lstlisting}[style=sh]
+ int EditPanelTcInt::keypress_event()
+ {
+ if( get_keypress() == 'h' && alt_down() ) {
+ context_help_show("Align Timecodes");
+ return 1;
+ }
+ ...further processing...
+ return 1;
+ }
+\end{lstlisting}
+
+A single example of much more sophisticated keypress\_event() handler can be found in \texttt{cinelerra/trackcanvas.C} (search on context\_help). The problem here was to track the particular object drawn on the canvas to figure out whose context help is to be requested. Another rare example of difficulty may appear when context help is desired for some GUI object which is not subclassed from BC\_WindowBase.
+
+\textit{ContextManual.pl} looks for occurence of keyphrases in the following order:
+
+\begin{enumerate}
+ \item In \textit{Contents.html}
+ \item In \textit{Index.html}
+ \item In all the \textit{CinelerraGG\_Manual/*.html} files via grep
+\end{enumerate}
+
+Keyphrase matching is tried first exact and case sensitive, then partially and case insensitive. The special keyword \texttt{TOC} shows Contents, \texttt{IDX} shows Index. If the keyword starts with \texttt{FILE:}, the filename after \textit{FILE:} is extracted and that file is shown. You can look in the ContextManual.pl script text.
+
+For debugging purposes the script can be called from command line. For this to work, the environment variable \texttt{\$CIN\_DAT} has to be set to the parent directory of doc.
+
+
+\subsubsection{Providing context help for plugins}%
+\label{ssub:providing_context_help_plugins}
+
+In the simplest case, nothing has to be done at all. The plugin context help functionality introduced in \texttt{cinelerra/pluginclient.C} automatically assigns context help keyword from the plugin's title for all plugins subclassed from \textit{PluginClient}. For this to work, the manual page documenting the plugin must be entitled identically to the programmatic title of the plugin. A special treatment can be necessary in the following cases:
+
+\begin{enumerate}
+ \item \textit{Rendered effects} are not subclasses of PluginClient and require an explicit context help definition via \texttt{context\_help\_set\_keyword().}
+ \item Only the main plugin dialog inherits context help functionality from the parent class. If a plugin opens additional dialog windows, they probably require explicit context help definitions.
+ \item If the plugin title differs from its subsection title in the documentation, either its help keyword or the corresponding title in the manual should be renamed. Another possibility can be an addition to the \textit{\%rewrite table} in \texttt{doc/ContextManual.pl}.
+ \item If the plugin title contains some characters special for HTML and/or Perl regular expression syntax, the special characters have to be escaped. For example, the keyphrase corresponding to the title \textit{Crop \& Position (X/Y)} should be converted to:
+
+ \begin{lstlisting}[style=sh]
+ Crop & Position \\(X\\/Y\\)
+ \end{lstlisting}
+
+ Such a rewriting can be done either in the C++ code or in ContextManual.pl.
+\end{enumerate}
+
+One additional explanation about previous user information when plugin tooltips are off. Help for the \textit {selected plugin} is shown because in this case it would be difficult to figure out, without a visual feedback, which particular item is currently under the mouse.
+
+\subsection{Manual Maintenance is now Tightly Coupled with the Program Code}
+\label{sub:manmaintain}
+
+If some section of the \CGG{} manual gets renamed and is used for Context Help, the corresponding help keywords should be adjusted too. All the keywords used can be listed via the following example command:
+
+\begin{lstlisting}[style=sh]
+ grep -F context_help `find . -name '*.C' -print` | grep -F '"'
+\end{lstlisting}
+----------------
+
+Note that the keyword does not have to exactly match the section title; it can also be a case insensitive substring of the section title.
+
+If some new \CGG{} window or dialog is created and documented, the inclusion of context\_help\_set\_keyword() calls and/or adaptation of keypress\_event() handler (if any) should be included in the program code.
+
+If some new \CGG{} plugin is created, it is best to document it in the section entitled exactly equal to that plugin's title. Then probably its context help will work out of the box. Otherwise, some adaptation to its keypress\_event() (if any) or to the %rewrite table in ContextManual.pl may be necessary.
+
+Why the local copy of \CGG{} manual should be used?
+
+\begin{enumerate}
+ \item For context help keyphrases matching, the local copy of \textit{Contents.html} and \textit{Index.html} is necessary anyway.
+ \item Grepping \textit{CinelerraGG\_Manual/*.html} files of the remote manual from the website cannot work per definition.
+ \item The local copy usage ensures exact matching of the version of the manual to the version of \CGG{}. Otherwise, if one uses for some reason an older version of \CGG{} with the help fetched from the newer version of the website manual, various incompatibilities can be expected.
+ \item Packing the manual into AppImage, the current method of \CGG{} packaging, should be much easier than merging two different git branches when building from source packages, as was done earlier.
+\end{enumerate}
+
+What about Localization?
+
+For now, \CGG{} context help is not localized at all. There is no complete \CGG{} manual in any language except English. But even should the manual be translated to other languages, the context help keywords must remain unlocalized literal string constants. First, because the set of languages known to \CGG{} itself is not the same as the set of languages the manual will be translated to. If some "translated keyword" is fed to the help system, while the manual in this language does not exist, keyword matching cannot succeed. Second, such a help localization with the translation of all keywords can be done and then maintained much easier and much more reliably inside the ContextManual.pl script rather than in the \CGG{} binary.
+
+More about ContextManual.pl file?
+
+The bin/doc/ContextManual.pl script can be configured further. Look in the script text. You can define your preferable web browser, or redefine it to 'echo' for debug purposes. There are also some predefined HTML pages for Contents and Index, and several explicitly rewritten keyphrases.
+
+After the first invocation of context help the system-wide script, bin/doc/ContextManual.pl, copies itself into
+the user's config directory, \$HOME/.bcast5. If the user needs to modify ContextManual.pl, it should be done
+on that copy from .bcast5 rather than the system-wide one. On all subsequent context help requests this
+(possibly modified) .bcast5 version of the script will be called. If later the \CGG{} package gets
+upgraded containing a newer, not 100\% compatible version of ContextManual.pl script, and/or not compatible
+structure of the HTML manual itself, the new system-wide version of the script will be copied into .bcast5
+again to ensure context help functionality. The older version of the script will be backed up (with the .bak
+suffix) as a reference of the modifications done by the user.
Editing comprises both time and track space. The timeline consists
of the time certain media appear on the track going left to right
and a set of tracks from the top to the bottom. There are 2 methods
-of timeline editing -- drag and drop editing, also called
-\textit{arrow mode}, and cut and paste editing or \textit{I-beam
- mode}. Cut and Paste is the default editing mode. An additional,
+of timeline editing -- drag and drop editing \index{drag and drop}, also called
+\textit{arrow mode} \index{arrow}, and cut and paste editing \index{cut and paste} or \textit{I-beam
+ mode} \index{i-beam}. Cut and Paste is the default editing mode. An additional,
but not often considered editing method is called \textit{two-screen
- editing} where the Viewer is used to view media and then the
+ 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.
-The timeline is where all editing decisions are made
+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
right with the scrollbars on the right and bottom. It can also be
\label{fig:timeline}
\end{figure}
-The active region is the range of time which is affected by editing
+The active region \index{active region} is the range of time which is affected by editing
commands on the timeline. The active region is determined first by
-the presence of in/out points on the timeline.
+the presence of in/out points \index{in/out point} on the timeline.
%
-If those do not exist the highlighted region is used. To reiterate,
+If those do not exist the highlighted region \index{highlighted region} is used. To reiterate,
\emph{highlighting} is done in \emph{cut and paste mode} by moving
the insertion point with the mouse in the timeline to where you want
to start. Then hold down the LMB\@, drag the mouse to where you want
down the Ctrl key and double click with the LMB with the mouse over
that column.
-If no highlighted region exists, the insertion point is used as the
+If no highlighted region exists, the insertion point \index{insertion point} is used as the
start of the active region. Some commands treat all the space to
the right of the insertion point as active while others treat the
active length as 0 (zero) if no end point for the active region is
modified media file at the end of your editing session which
represents the editing decisions, you need to render it. Saving and
loading your edit decisions is explained in the Load, Save and the
-EDL section and rendering is explained in the section on Rendering.
+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.
\section{The Patchbay}%
\label{sec:patchbay}
+\index{patchbay}
On the left of the timeline is a region known as the patchbay. The
patchbay enables features specific to each track as described next.
The 7 \textit{attributes} are described here next followed by the other available feature icons and their description.
\begin{description}
-\item[Play Track] determines whether the track is rendered or
+\item[Play Track] \index{play track} determines whether the track is rendered or
not. If it is off, the track is not rendered. For example if you
turn it off in all the video tracks, the rendered media file will
have only audio tracks. If the track is chained to any other tracks
in this shared track, regardless of play status of the shared track
that in this particular case affects the media output but not fade
and effects.
-\item[Arm Track] determines whether the track is armed or not.
+\item[Arm Track] \index{arm track} determines whether the track is armed or not.
Only the armed tracks are affected by editing operations. Make sure
you have enough armed destination tracks when you paste or splice
material or some tracks in the material will get left out. In
combination with the active region determine where material is
inserted when loading files. If the files are loaded with one of
the insertion strategies which do not delete the existing project,
- the armed tracks will be used as destination tracks.
+ the armed tracks will be used as destination tracks. Note that disarming
+ a track does not prevent you from dragging or attaching an Effect/Plugin
+ onto a disarmed track - this is not considered an edit in this case.
\end{description}
\begin{description}
-\item[Draw Media] determines if picons or waveforms are drawn on
+\item[Draw Media] determines if picons \index{picons} or waveforms \index{waveform} are drawn on
the asset in the track. You may want to disable this if you know
that the media/format takes a long time to draw on the timeline. By
default it is set to on in order to see picons on the timeline.
-\item[Don’t send to output] -- more commonly called
+\item[Don’t send to output] \index{mute} -- more commonly called
\textit{mute} -- causes the output to be thrown away once the track is
completely rendered. This happens whether or not \textit{Play track}
is on. For example if you mute all the video tracks, the rendered
Mute track is used to keep the track with the shared track effect
from overlapping the output of the source track (the shared track)
where the shared track effect is not present.
-\item[Gang Fader] cause the fader to track the movement of
+\item[Gang Fader] \index{gang fader} cause the fader to track the movement of
whatever other fader you are adjusting by dragging either the fader
or the curve on the track. It doesn't affect the editing made with
menu controls. A fader is only ganged if the arm track is also on.
simultaneously. Gang also causes Nudge parameters to synchronize
across all the ganged tracks.
\item[Master Track] Mark a track as \textit{master} serves when using \textit{Gang Channels} or \textit{Gang Media} mode. See \nameref{sub:displaying_tracks_ganged}
-\item[Track Data Height] this up/down toggle symbol to the immediate right
+\item[Track Data Height] \index{track!height} this up/down toggle symbol to the immediate right
of the 5 attributes, is used to individually resize each track. This makes
it very easy to temporarily expand or contract the size of that track either
by clickin with the left mouse button or using the middle wheel up/down.
-\item[Fader slider] fade values are represented on the timeline
+\item[Fader slider] \index{fader slider} fade values are represented on the timeline
with a pink (default color) curve that is keyframable. All tracks have a fader, but
the units of each fader depend on whether it is audio or video.
Audio fade values are in dB. They represent relative levels, where 0
with the arm option enabled, the other faders should follow. Hold
down the Shift key and drag a fader to center it on the original
source value (0 for audio, 100 for video).
-\item[Mixer] in the expanded patchbay for that track designates
+\item[Mixer] \index{mixers!toggle} in the expanded patchbay for that track designates
the multi-camera mixer mode.
-\item[Overlay mode] in the expanded patchbay is used for
+\item[Overlay mode] \index{overlay pulldown} in the expanded patchbay is used for
porter-duff operations and is full explained in
\nameref{cha:overlays} chapter.
-\item[Nudge] is in the expanded patchbay. The nudge value is
+\item[Nudge] \index{nudge} is in the expanded patchbay. The nudge value is
the amount the track is shifted left or right during playback. The
track is not displayed shifted on the timeline, but it is shifted
when it is played back. This is useful for synchronizing audio with
sensitive menu. Nudge settings are ganged with the Gang faders
toggle and the Arm track toggle. Use the mouse wheel over the nudge
textbox to increment and decrement the value.
-\item[Pan] is available in the expanded patchbay for audio
+\item[Pan] \index{panning box} is available in the expanded patchbay for audio
tracks via a panning box. Position the pointer in the panning box
and click/drag to reposition the audio output among the speaker
arrangement. The loudness of each speaker is printed on the relative
toggle the track arming status. Press Shift-Tab while the cursor is
over a track to toggle the arming status of every other track.
-\paragraph{Automatic audio mappings} Several convenience functions
+\paragraph{Automatic audio mappings} \index{audio!map} Several convenience functions
are provided for automatically setting the panning to several common
standards. They are listed in the Audio menu. These functions only
affect armed audio tracks. They are:
\begin{description}
-\item[Audio~$\rightarrow$~Map 1:1] This maps every track to
+\item[Audio~$\rightarrow$~Map 1:1] \index{audio!map 1:1} This maps every track to
its own channel and wraps around when all the channels are
allocated. It is most useful for making 2 tracks with 2 channels map
to stereo and for making 6 tracks with 6 channels map to a 6 channel
sound card.
-\item[Audio~$\rightarrow$~Map 5.1:2] This maps 6 tracks to 2
+\item[Audio~$\rightarrow$~Map 5.1:2] \index{audio!map 5.1:2} This maps 6 tracks to 2
channels. The project should have 2 channels when using this
function. Go to \texttt{Settings $\rightarrow$ Format} to set the
output channels to 2. This is most useful for down-mixing 5.1 audio
\section{Manipulating Tracks}%
\label{sec:manipulating_tracks}
+\index{track!pulldown}
Tracks in \CGG{} either contain audio or video. There is no special
designation for tracks other than the type of media they contain.
\begin{description}
\item[Move tracks up | Move tracks down] shift all the armed
tracks up or down the stack.
+\item[Roll tracks up | Roll tracks down] wheel motion of the tracks up or down.
\item[Delete tracks] deletes the armed tracks.
+\item[Delete first track] deletes the first track, whether it is armed or not.
\item[Delete last track] deletes the last track, whether it is
armed or not.
\item[Concatenate tracks] operation copies all the assets of
track. The destination track wraps around until all the disarmed
tracks are concatenated. Disarmed tracks that are not playable are
not concatenated.
+\item[Align timecodes] see \nameref{sub:align_timecodes}
\item[Append to project] allows for creating new tracks after
any existing tracks.
\item[Add subttl] will add a track for subtitles at the top of
the other tracks.
\end{description}
-The \textbf{Audio} and \textbf{Video pulldowns} each contain an
+The \textbf{Audio} \index{audio!pulldowns} and \textbf{Video pulldowns} \index{video!pulldown} each contain an
option to add a track of their specific type. In the case of audio,
the new track is put on the bottom of the timeline and the output
channel of the audio track is incremented by one. In the case of
\subsection{Displaying tracks: Ganged mode}%
\label{sub:displaying_tracks_ganged}
+\index{track!ganged mode}
Often users working on media where Audio is the main focus, want all of a media's audio channels, whether stereo or 5:1 channels, to be treated as a single unit. They are more familiar with working with a DAW (Digital Audio Workstation software) and find that it takes extra work and a lot more care to have to individually manage audio tracks rather than have them automatically edited as a ganged group.
-To get this capability, there is a \textit{Gang Tracks} toggle button on the main timeline controls to switch between 3 modes of working with multiple channels so that the tracks are automatically edited as a single unit. Operations affected include edits such as cuts, moving sections, and adding plugins. Group masters are marked by the \textit{Master Track} toggle in the patchbays. A track gang group begins on a master track, and extends to, but not including, the next master track. The 3 \textit{Gang Tracks} modes are:
+To get this capability, there is a \textit{Gang Tracks} \index{gang tracks toggle} toggle button on the main timeline controls to switch between 3 modes of working with multiple channels so that the tracks are automatically edited as a single unit. Operations affected include edits such as cuts, moving sections, and adding plugins. In addition to letting you work on the tracks of a group as one, you also get a saving of space on the timeline that makes it easier to view and edit the tracks. Group masters are marked by the \textit{Master Track} \index{master track} toggle in the patchbays \index{patchbay}. A track gang group begins on a master track, and extends to, but not including, the next master track. The 3 \textit{Gang Tracks} modes are:
\begin{enumerate}
\item \textbf{Gang None:} this is the default mode and is the traditional way Cinelerra operates. If you never toggle the "Gang Tracks" button, everything operates normally as it always has. In this mode, the button icon looks like 3 tracks with $\dots$ on the end and all tracks are visible on the timeline. See figure~\ref{fig:gang-track-01}
-\end{enumerate}
\begin{figure}[htpb]
\centering
\caption{Gang None: only the video track is master. We see all tracks both master and non-master (default)}
\label{fig:gang-track-01}
\end{figure}
-
-\begin{enumerate}[start=2]
- \item \textbf{Gang Channels:} in this mode, only the \textit{Master Tracks} and the first track of video, audio, or subtitles not master will are shown. Stereo tracks, or 5:1 channels/any number of audio tracks, are drawn as 1 audio track for the purpose of making changes on that single track which are propagated to all of its other channel tracks automatically. This is the DAW-like mode. The \textit{Gang Tracks} button icon looks like 2 tracks and only the first video and first audio tracks will be shown. See figure~\ref{fig:gang-track-02}
-\end{enumerate}
+ \item \textbf{Gang Channels:} in this mode, all \textit{Master Tracks} are shown. The exception is when there is no Master video, no Master audio or no Master subtitle track, in which case for each the first track of video, audio, and subtitle will be shown. For users who routinely switch the track order frequently, the patchbay has the \textit{Master Track} icon to set your own preference. Stereo tracks, or 5:1 channels/any number of audio tracks, are drawn as 1 audio track for the purpose of making changes on that single track which are propagated to all of its other channel tracks automatically. This is the DAW-like mode. The \textit{Gang Tracks} button icon looks like 2 tracks and only the first video and first audio tracks will be shown. See figure~\ref{fig:gang-track-02}
\begin{figure}[htpb]
\centering
\label{fig:gang-track-02}
\end{figure}
-\begin{enumerate}[start=3]
\item \textbf{Gang Media:} this mode only shows the \textit{Master Tracks} of the media but changes are propagated to the appropriate other related tracks (even if they are not visible). The \textit{Gang Tracks} button icon looks like a single track. See figure~\ref{fig:gang-track-03}
\end{enumerate}
The current \textit{Gang Tracks} mode is saved across sessions and will be saved in your project. Although most likely users will work in the \textit{Gang None} mode, users more familiar with DAW software will tend to use the \textit{Gang Channel}s mode.
-More details ares described next about master tracks. Each patchbay has a \textit{Master Track} button on the extreme right of the patchbay. These mark which tracks of the media are master tracks. The span of tracks between the gang group masters are the gang track group. The master track toggles can be disabled/enabled as the user wishes to create the desired track groups. Normal file loads will mark the first stream of each file loaded as a master, if the media is loaded with insertion strategy of\textit{ Replace current project}, \textit{Replace current project and concatenate tracks} or \textit{Append in new tracks}. Frequently, editing is done on video, audio, or audio/video groups to maintain timeline synchronization. By grouping related tracks, this procedure is much more automatic.
+More details are described next about master tracks. Each patchbay has a \textit{Master Track} button on the right of the patchbay. These mark which tracks of the media are master tracks. The span of tracks between the gang group masters are the gang track group. The master track toggles can be disabled/enabled as the user wishes to create the desired track groups. Normal file loads will mark the first stream of each file loaded as a master, if the media is loaded with insertion strategy of\textit{ Replace current project}, \textit{Replace current project and concatenate tracks} or \textit{Append in new tracks}. Frequently, editing is done on video, audio, or audio/video groups to maintain timeline synchronization. By grouping related tracks, this procedure is much more automatic.
Previously existing projects created before the addition of ganged tracks, will have ALL tracks marked as master tracks and changing the \textit{Gang Tracks} button mode will have no effect. The user will have to properly designate which track is the master track and disabling the others in order to make use of the toggle modes.
NOTES:
\begin{itemize}
- \item When in \textit{Gang Channels} or \textit{Gang Media} mode, if the first audio track is not disarmed, but any of its connected channel tracks are, the disarm of those channels are ignored and all channels are treated as being armed. This is to be consistent with the purpose of using this mode; the purpose being that any edits to the first master track are automatically propagated to all other channels.
+ \item When in \textit{Gang Channels} or \textit{Gang Media} mode, if the first audio track is not disarmed, but any of its connected channel tracks are, the disarm of those channels are ignored and all channels are treated as being armed. This is to be consistent with the purpose of using this mode; the purpose being that any edits to the first master track are automatically propagated to all other channels. \textit{Warning}: this behavior is contrary to the default of \CGG{} whereby an unarmed track never undergoes any alteration. This exception was made to mimic the behavior of DAWs, where the various channels of an audio track are combined into a single "line", and it makes no sense to talk about armed or unarmed channels.
\item It may be better when using the \textit{Gang Channels} or \textit{Gang Media} mode to make any changes
to the first audio channel to be automatically duplicated before reverting to the \textit{Gang None} mode to make other changes. Once you start changing individual channels (that is, audio tracks) so that they are no longer coordinated in their edits/plugins, it may be more difficult to switch back to \textit{Gang Channels} mode and get the desired results since the channels may no longer be lined up.
+ \item Gang modes should not be used with Multi-camera/Mixers because they have very specific operational capabilities which are not compatible with the way that Ganging works.
+ \item Gang flags in the patchbay specifically when in \textit{Gang Channels} or \textit{Gang Media} modes will operate as set in the Master Track. For example, if when in \textit{Gang Channels} mode, you turn off “Play track” on the visible audio track, none of the associated channels (i.e. the other stereo or other 5 channels) will play. And if in \textit{Gang Media} mode, if you turn on “Play track” for the Master Track, all associated video and audio tracks will play unless you turned off “Play track” for some of the associated audio/video slave tracks which will not play.
+ \item When adding a Plugin/Effect in \textit{Gang Channels} or \textit{Gang Media} mode to the track, highlighted selected region, or In/Out pointers area via dragging the plugin from the Resources Window the plugin will be added on the master and all slave tracks. If using the Audio or Video pulldown, \textit{Attach Effect} option and you want to propagate the effect to all slave tracks, make sure that the checkbox for "Attach single standalone and share others" in the Dialog window is checked. However, currently when using the right mouse button (RMB) on the master track to \textit{Attach effect}, the effect will only be inserted on that track.
\end{itemize}
\section{Two Screen Editing}%
\label{sec:two_screen_editing}
+\index{two-screen}
This is a fast way to construct a program out of movie files (in
other programs is called \textit{three points editing}). The idea
To begin a two screen editing session, load your media resources by
using the main menu \textbf{File pulldown} and choose \textit{Load
- files}; make sure the insertion mode is set to \textit{Create new
- resources only}. This insertion strategy is to ensure that the
+ files} \index{load media files}; make sure the insertion mode is set to \textit{Create new
+ resources only}. This insertion strategy \index{insertion strategy} is to ensure that the
timeline stays unchanged while new resources are brought in. Go to
-the Resources window and select the Media folder. The newly loaded
+the Resources window \index{resources window} and select the Media folder. The newly loaded
resources will appear. Double click on a resource or drag it from
-the media side of the window over to the Viewer window.
+the media side of the window over to the Viewer window \index{viewer!window}.
Check to make sure there are enough armed tracks on the timeline to
put the subsections of source material that you want. Usually this
bracket.
\item You will see a colored bar inside the brackets for easier
viewing.
-\item Drag the In/Out point with the mouse to conveniently
+\item Drag the In/Out point \index{in/out point} with the mouse to conveniently
change their position.
\end{enumerate}
-These In/Out points define a clip. You can now use this in a couple
+These In/Out points define a clip \index{clip}. You can now use this in a couple
of different ways.
-\paragraph{Splice} The splice icon, or shortcut letter “\texttt{v}”,
+\paragraph{Splice} \index{splice} The splice icon, or shortcut letter “\texttt{v}”,
inserts the selected area in the timeline after the insertion point.
After the splice has taken effect, the insertion point moves to the
end of the edit ready to be used as the next splice location. This
there are edits after your chosen splice location on the timeline,
they will be moved to the right.
-\paragraph{Overwrite} The overwrite icon, or shortcut letter
+\paragraph{Overwrite} \index{overwrite} The overwrite icon, or shortcut letter
“\texttt{b}”, overwrites the region of the timeline after the
insertion point with the clip. If an In point or an Out point exists
on the timeline the clip is overwritten after the In point or after
\subsection{Use Case – Working with Sequences}
\label{sub:use_case_working_sequences}
+\index{sequences}
-\textit{From the Viewer to the Timeline with the sequences imported
+\textit{From the Viewer to the Timeline \index{timeline} with the sequences imported
in a Master Project.}
A convenient methodology for working on a Master project along with
\section{Cut and Paste Editing}%
\label{sec:cut_paste_editing}
+\index{cut and paste}
This is the more traditional method of editing in \CGG{} and
therefore is the default. To enable the cut and paste editing mode
-on the timeline, select the I-beam toggle on the control bar at the
+on the timeline, select the I-beam \index{i-beam} toggle on the control bar at the
top of the main program window. You can copy edits in the same
track, copy from different tracks in the same instance, start a
second instance of \CGG{} and copy from one instance to the other or
timeline and select the paste button. Assuming no In/Out points are
defined on the timeline this performs a cut and paste operation.
-Most editing operations are listed in the \textit{Edit} pulldown. Some of
+Most editing operations are listed in the \textit{Edit} pulldown \index{edit!pulldown}. Some of
them have a button on the program control toolbar as well as a
keyboard shortcut. The keyboard shortcut is in parenthesis here.
\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.
\item[Select All] (a) Select the whole timeline.
\end{description}
-In Cut and Paste editing mode you can \textit{edit labels} as
+In Cut and Paste editing mode you can \textit{edit labels} \index{label} as
well. By enabling Edit labels in the \textbf{Settings pulldown}, or
by disabling the Lock labels from moving button on the Program
Control Tool Bar, labels will be cut, copied or pasted along with
waveform. Perform a cut, clear the In/Out points, select the region
between the labels, and perform a paste.
-\paragraph{In / Out Points} The In and Out bracket placement is
+\paragraph{In / Out Points} \index{in/out point} The In and Out bracket placement is
explained here to illustrate their usage. Because of the shape of
the markers [ and ] you may assume that they are inclusive -- that
-everything placed in between would be included in the clip, such as
+everything placed in between would be included in the clip \index{clip}, such as
in the case of being transferred to the timeline from the Viewer.
In reality, one of the two markers will not include the frame that
was visible at the time the marker was affixed. Depending on whether
reference of the markers is in the middle of the icon, you will
avoid confusion.
-\paragraph{Overwrite} To perform overwriting within the timeline
+\paragraph{Overwrite} \index{overwrite} To perform overwriting within the timeline
paste on a selected region (highlighted or between In/Out
points). The selected region will be overwritten. If the clip pasted
from the clipboard is shorter than the selected region, the selected
of armed tracks. They are pasted one after the other, keeping the
same order they have on the stack.
-\paragraph{Split -- blade cut and hard edges:} You can cut the
+\paragraph{Split -- blade cut and hard edges:} \index{split} You can cut the
tracks into 2 pieces on the timeline by putting the hairline cursor
on the place you want to do a cut and then using the character “x”
or the scissors tool (figure~\ref{fig:cut}).
over the cursor location. A blade cut simply splits the edit into
two edits. In order to have the video and audio aligned, it works
best to have \texttt{Settings $\rightarrow$ Align cursor on
- frames}. When a blade cut occurs, the edges are created as
-\textit{hard edges}. These are edges that cannot be deleted by
-track optimizations.
+ frames} \index{align cursor on frames}. When a blade cut occurs, the edges are created as
+\textit{hard edges}. \index{hard edge} These are edges that cannot be deleted by
+track optimizations \index{timeline!optimization}.
%
\CGG{} has built-in optimization on the timeline. So that whenever
two parts on the timeline are sequential frames, it automatically
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}
+\index{drag and drop}
To enable the drag and drop editing mode on the timeline, select the
-arrow toggle on the control bar at the top of the main program
+arrow toggle \index{arrow} on the control bar at the top of the main program
window. Drag and drop editing is a quick and simple way of working
in \CGG{}, using mostly only the mouse. The basic idea is to create
-a bunch of clips, then drag them in order into the timeline, thus
+a bunch of clips \index{clip}, then drag them in order into the timeline, thus
building prototype media that you can watch in the compositor. If
after watching it, you wish to re-arrange your clips, set effects,
add transitions or insert/delete material, just drag and drop them
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 and choose
-\textit{Load files}; make sure the insertion mode is set to
-\textit{Create new resources only}. This loads the files into the
-Resources window.
+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{Create new resources only} \index{insertion strategy}. This loads the files into the
+Resources window \index{resources window}.
\begin{enumerate}
\item Create some video and audio tracks on the timeline using
- the \textit{Video} and \textit{Audio} pulldowns.
+ the \textit{Video} \index{video!pulldown} and \textit{Audio} \index{audio!pulldown} pulldowns.
\item Open the Media folder in the Resources window. Make sure
the necessary tracks are armed and drag a media file from the
- Resources window to the timeline. If the media has video, drag it
+ Resources window to the timeline \index{timeline}. If the media has video, drag it
onto a video track or if just audio, drag it onto an audio
track. For a still image, drag it onto a video track.
\end{enumerate}
\item If you have more armed tracks on the timeline than in the
asset you are dragging, only the following edits of the tracks
affected by the drag and drop operation will move to the right. This
- will cause loss of synchronization. To restore it, disarm the tracks
+ will cause loss of synchronization \index{sync}. To restore it, disarm the tracks
affected by the drag and drop operation, highlight the just dropped
edit and paste silence over it using the \textit{Edit} pulldown,
\textit{Paste Silence}.
Labels sometimes work differently in Drag and Drop editing mode in
that you can't drag and drop them. They might be locked to the
-timebar, even with the Edit labels option enabled. Although with
+timebar \index{timebar}, even with the Edit labels option enabled. Although with
the Edit labels option enabled, if a selected area of a resource is
spliced from the Viewer to the timeline in a position before labels,
these labels will be pushed to the right for the length of the
\subsection{Copy/Paste Behavior}%
\label{sub:copy_paste_behavior}
+\index{drag and drop!MMB options}
There are many options for moving, copying, pasting, inserting, and
deleting selected \textit{edits}, more commonly referred to by the
user as \textit{clips}, when in the Drag and Drop (arrow) editing
mode. This makes it easier to avoid constantly having to disarm/arm
-tracks. To create a selection move the cursor over the clip and
+tracks. To create a selection \index{edit!selection} move the cursor over the clip and
just click the left mouse button; remove a selection by left mouse
button click again. This will mark your selection with a colored
border which contains some red. The easiest way to initially use
add multiple selections as is commonly done for listbox operations,
there is a preference in \texttt{Settings $\rightarrow$ Preferences
$\rightarrow$ Appearance} tab, called \textit{Clears before
- toggle} that changes the behavior.
+ toggle} \index{clears before toggle} that changes the behavior.
When an edit is marked as selected, it can be cut/copied into the
paste clip buffer. The constructed clip buffer will begin with the
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-a & Select all edits within an 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 * (see note below) \\
Copy & Ctrl-c & Copy the selected edits into the copy buffer.\\
of the hairline cursor. This destroys the
current edits in that space.\\
- Overwrite & Ctrl-Shift-P & Pastes plugins that are in the Copy
+ Overwrite plugins & Ctrl-Shift-P & Pastes plugins that are in the Copy
buffer to current location but no
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
\subsection{Snapping while Cutting and Dragging}%
\label{syb:snapping_cutting_dragging}
+\index{snap}
-\paragraph{Cutting/Snapping edits} cuts from an edit handle to the
+\paragraph{Cutting/Snapping edits} \index{edit!cut with snap} cuts from an edit handle to the
insert point. There are Edit Panel buttons which normally are used
to move to the previous or next edit handle/label.
\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}
-\paragraph{Drag Snapping} if you hold down the Ctrl + Alt keys while
+\paragraph{Drag Snapping} \index{edit!drag with snap} if you hold down the Ctrl + Alt keys while
dragging using the mouse, once the clip gets near to an edit, a
label, an in/out pointer or the start/end of the timeline, the
dragged clip will snap next to that marker. The 2 will now be
\subsection{Copy/Paste clips/medias across Multiple Instances}%
\label{sub:copy_paste_multiple_instances}
+\index{multiple instances: copy/paste}
It is easy to copy/paste clips/media within a single instance of
\CGG{} or across multiple instances. The reason this works is
\subsection{Grouping edits}%
\label{sub:grouping_edits}
+\index{edit!grouping}
\CGG{} recognizes as a group, the edits of different armed tracks
that have aligned beginnings, regardless of whether they have the
method of Grouping of edits is performed as follows:
\begin{enumerate}
-\item Select each of the clips you would like to be part of a
+\item Select \index{edit!selection} each of the clips you would like to be part of a
group.
\item Use the desired Copy mode as described above to get into
the buffer.
\subsection{Dragging Groups}%
\label{sub:dragging_groups}
+\index{edit!dragging group}
Dragging while in \textit{Drop and Drag editing mode} (arrow mode)
-is really easy. Just select the clip or clips you want to drag
+is really easy. Just select \index{edit!selection} the clip or clips you want to drag
using the left mouse button, then put your cursor over one of them
and drag while holding down the left mouse button. Keyframes,
autos, labels, and plugins will also be dragged. Dragging honors
\textit{overwrite}. Without the \texttt{Shift} key enabled, it
always \textit{inserts} only.
-The original (older) method of dragging while in Arrow mode, lets
+The original (older) method of dragging while in Arrow \index{arrow} mode, lets
you just left mouse click on a single clip or aligned clips and just
drag. This older method of dragging does not move any of its
effects with it at this time. There will only be a white outline
while dragging and it will let you drop only if it fits. You can
also perform some dragging and grouping while in the \textit{Cut and
- Paste editing mode} (ibeam mode) by taking advantage of the Ctrl
+ Paste editing mode} (ibeam mode \index{i-beam}) by taking advantage of the Ctrl
button in conjunction with the left mouse button.
\begin{itemize}
\end{itemize}
This last section on Dragging, outlines the difference
-between \textit{column selection} and \textit{marking selection}.
+between \textit{column selection} \index{column selection} and \textit{marking selection} \index{marking selection}.
Column selection is available to make it easy to still be able to do
some dragging in I-beam mode whereas Marking selection makes it easy
to drag clips together that are not columnated.
\subsection{Selection Methods}%
\label{sub:selection_method}
+\index{edit!selection}
+\index{active region}
Concerning \textit{Selection} methods, the following information is
partially pertinent to all editing, but is most important to keep in
is input for the vertical style cut/paste drag/drop editing.
More recently, in addition to the column oriented timeline drag
-selection, there is now \textit{group} capabilities which have
+selection, there is now \textit{group} \index{edit!grouping} capabilities which have
various \textit{edit} selections. These are created in the Drag and
Drop editing mode by clicking edits to toggle
select/deselection. These groups are input to a different (more
and so on \dots The keyboard Delete key is not hooked to these
operations, and is hooked to the original editing methods.
-In this \textit{group} mode, if there are In/Out markers set, they
+In this \textit{group} mode, if there are In/Out \index{in/out point} markers set, they
enter the selection priority queue between the column selection and
the cursor only. You can see the In/Out markers selected region
colored line across the timebar (slightly underneath where the time,
There is also a faster way:
\begin{enumerate}
- \item Arm the tracks you want to be used
+ \item Arm the tracks you want to be used.
\item Highlight the area as usually you do with \textit{I-beam} mode (or use \textit{In/Out Points}; or position \textit{Insert Point} over the stack of edits). If you miss an edit that you want included, the same method can be used to add it. It is an additive operation. And, it will include the partial edits in the selected area, thus making it easy to disinclude ones you do not want.
It will include silence also but you can remove that or any other edit with CTRL + LMB.
\item Press MMB on a clip inside the highlight area and the PopUp menu is shown with the \textit{Select edits} option on the top.
- \item Choose the \textit{Select edits} option and the clips inside the highlight area will be selected.
+ \item Choose the \textit{Select or Deselect edits} option and the clips inside the highlight area will be selected or deselected.
\end{enumerate}
-\section{Inter-View Mode\;/\;Identifying Source Targets}%
+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.
+ \item To Drag Deselect edits. hold down Alt+Ctrl+LMB and drag over the area to be desected. Releasing the mouse results in deselecting.
+\end{enumerate}
+
+If using certain operating systems (for example Ubuntu and Arch) that might field the Alt key before it gets to \CGG{}, you can use the following for both Select and Deselect instead:
+\begin{enumerate}
+ \item Press and hold down Ctrl+Alt+LMB on an edit
+ \item Drag on the edits you want to select
+ \item Release the Ctrl key
+ \item Release the LMB
+ \item Release the Alt key
+\end{enumerate}
+
+\section{Inter-View Mode -- Identifying Source Targets}%
\label{sec:inter-view_identifying_source_target}
+\index{inter-view}
Inter-View mode provides a mapping of a particular media file to its
-timeline usages. It is somewhat similar to Two Screen Editing in
+timeline \index{timeline} usages. It is somewhat similar to Two Screen Editing in
that you make use of the Viewer. It makes it possible to precisely
trace and indicate in the media the origin of a particular segment
of the timeline and visually indicate the use and distribution that
\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}
\label{fig:inter-view01}
\end{figure}
+There is a second usage of Inter-View mode that can be helpful if
+some tracks have become misaligned, such as in the case of 2 audio
+channels no longer being in sync. You can use this mode to get them
+back in alignment.
+
Explanation of how to use Inter-View mode will be described here
next.
\begin{itemize}
\item Do your editing as usual on the timeline until you are
ready to see what is used or unused.
-\item Make sure you are in any of the Preview modes in the
- Resources window; you enable the mode using the pulldown to the left
+\item Make sure you are in any of the Preview modes \index{preview mode} in the
+ Resources window \index{resources window}; you enable the mode using the pulldown to the left
of the word \textit{Search}. The option looks like this \quad
\includegraphics[height=\baselineskip]{fullplay.png}.
\item Middle mouse click on a thumbnail in the Resources window and
\item Ctrl-click on the bottom bar and the timeline and composer
are re-positioned to the beginning of that edit.
\item Shift-click on the bottom bar and a \textit{selection} is
- made of that section in the timeline and the composer is updated
+ made of that section in the timeline and the compqoser is updated
with that start position.
\end{itemize}
\section{Edit Tools}%
\label{sec:edit-tools}
+\index{edit tools}
\subsection{Edit Length}%
\label{sub:edit-lenght}
+\index{edit!length}
To set the length of an edit in the timeline, select the region
which contains the edit to be modified. Now select the menu bar
\subsection{Align Edits}%
\label{sub:align_edits}
+\index{align edits}
When loading media, a common problem is that the various audio/video
tracks do not always have exactly the same lengths. For example, you
\subsection{Reverse Edits}%
\label{sub:reverse_edits}
+\index{reverse edits}
The Reverse Edits can be useful to change the order of 2 edits in
the case where you would like to put a \textit{teaser} section that
\subsection{Shuffle Edits}%
\label{sub:shuffle_edits}
+\index{shuffle edits}
The file pulldown \texttt{Edit $\rightarrow$ Shuffle Edits} will
randomly exchange the location of the edits. This feature can be
\section{Multi-Session}%
\label{sec:multi_session}
+\index{multi-session}
You can run as many sessions of \CGG{} as your computer resources allow. However, if you are using the same \texttt{\$HOME/.bcast5}, changes you make for one may impact the others. You can always create and rename a new \texttt{.bcast5} from:\\
\texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface $\rightarrow$ Index files:} and press \textit{Index files go here}
\section{Multi-Viewer Window Support}%
\label{sec:multi_viewer_window_support}
+\index{multi-viewer window}
You can create as many Viewer windows as you want in \CGG{}. These are handy for users who are adept at working with a lot of different clips simultaneously. By bringing up multiple Viewer windows, each clip can be edited in its own area, making it easy to see all of the separate pieces. After you have loaded some media files, to start another Viewer window, right click on one of the pieces of media in the Resources window. This brings up a menu of several options, one of which is \textit{view in new window}. Choose this option and that media will come up in a new Viewer window for you to work (figure~\ref{fig:multi-view01}).
\label{fig:multi-view01}
\end{figure}
-\section[ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing]{ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing\protect\footnote{programmatic specifications from Eric Messick}}%
+\section[ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing]{ShuttlePROv2 and ShuttleXpress Jog Wheels for Editing}%
\label{sec:shuttle_jog_wheels_editing}
+\index{shuttle pro v2 and shuttlexpress}
-The ShuttlePROv2 and ShuttleXpress are affordable jog wheels which
+The ShuttlePROv2 and ShuttleXpress are affordable jog wheels\protect\footnote{programmatic specifications from Eric Messick} which
can be useful for working with Cin, especially if you do a lot of
playing forward/backward, fast/slow/normal, and single frames
(figure~\ref{fig:shuttle}).
\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
The following is the default setting for the ShuttlePROv2 and
ShuttleXpress (table~\ref{tab:shuttleprov2} and
-table~\ref{tab:xpress}):
+table~\ref{tab:xpress}). This page can be quickly requested from \CGG{} by
+simultaeneously pressing the \texttt{Alt} key on the keyboard and any button on the Shuttle.
\renewcommand{\arraystretch}{1.15}
\begin{table}[ht]
\chapter{FFmpeg Interactions}%
\label{cha:ffmpeg_interactions}
+\index{ffmpeg}
\CGG{} uses ffmpeg for decoding and encoding media, thus there are many opportunities available to manipulate options.
\section{FFmpeg Early Probe Explanation}%
\label{sec:ffmpeg_early_probe_explanation}
+\index{ffmpeg!early probe}
+\index{ffmpeg!try first}
+\index{ffmpeg!try last}
When you open media, a series of libraries and codec functions are used to \textit{probe} the data, to see if it can determine the type of file format and codec parameters needed to correctly decode the file. If ffmpeg probes early -- \textit{Try FFMpeg first} is in effect for the FF button (green icon) -- it will usually find some way to try to decode just about any contemporary media file. But there are some times that the built in codecs are actually a better choice. A lot of this may fall into the category of personal preference. For example, some may prefer the mpeg library in the \CGG{} code over the ffmpeg code because it has more decoding capability and seems to be more robust when the media is damaged. In that case you will want the FF button to read \textit{Try FFMpeg last}.
\section{How to Create FFmpeg Options Files}%
\label{sec:create_ffmpeg_options_files}
+\index{ffmpeg!options files}
This section describes how the FFmpeg options files work for decoding and encoding and goes into great detail. It will make more sense if you look at \CGG{}'s ffmpeg config directory and the \CGG{} menus at the same time.
It is meant to include everything necessary for complete understanding. You will be able to personalize your own options files without knowing all of the information included below if you know the basics. The word encoding is used interchangeably with the word rendering.
The possible combinations for ffmpeg options files are literally combinatorial -- that is a lot (factorial!). The allowed media file format / codec choices are much more flexible than you might realize. When the ffmpeg design was initially added, some parameter files which describe the choices which the program uses had to be created. There are way too many to enumerate in the deliverable \CGG{} package. Some quite detailed information for how ffmpeg options work is given here and hopefully, enough basics for simple understanding. It may all seem complicated at first, but will become obvious.
+AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
\subsection{File naming convention}%
\label{sub:file_naming_convention}
In \CGG{}'s ffmpeg configuration directory you will see files as listed and described below. File type and extension names are the key for \CGG{}'s use of ffmpeg. Basically the \texttt{.opts} file extension represents options; \texttt{.dfl} represents defaults; and all the rest are media types. For example one media type is quicktime so that \texttt{*.qt} file names would be the \textit{quicktime} choices. In the file names below, \textit{ext} refers to a set of files with file names matching the \texttt{*.ext} file extension. And \textit{typ} refers to a type of format / codec combination used, that is, the media type.
+AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
In the ffmpeg configuration directory there are a series of options files used when encoding or decoding audio or video. They are read in the order from top to bottom and only the files needed for the current operation are added to the active configuration.
\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}
-\paragraph{Decoder options:} Normally, only \texttt{ffmpeg.opts} and \texttt{decode.opts} are used when reading/decoding files, but may be specialized if a \texttt{<path>/media.opts} exists for a given \texttt{<path>/media.ext} file. For example, if you want to only fail on fatal errors and to always use the video filter, edgedetect, when working with your media file \texttt{dreaming.y4m}, then create a file \texttt{dreaming.opts} in the same directory with the contents of \textit{loglevel=fatal} on the first line and \textit{video\_filter=edgedetect} on the next. These specialized settings will override the defaults. The fatal loglevel is especially handy for lesser quality media.
+\paragraph{Decoder options:}
\index{ffmpeg!decoder options} Normally, only \texttt{ffmpeg.opts} and \texttt{decode.opts} are used when reading/decoding files, but may be specialized if a \texttt{<path>/media.opts} exists for a given \texttt{<path>/media.ext} file. For example, if you want to only fail on fatal errors and to always use the video filter, edgedetect, when working with your media file \texttt{dreaming.y4m}, then create a file \texttt{dreaming.opts} in the same directory with the contents of \textit{loglevel=fatal} on the first line and \textit{video\_filter=edgedetect} on the next. These specialized settings will override the defaults. The fatal loglevel is especially handy for lesser quality media.
-\paragraph{Encoder Options:} Within the audio/video subdirectories of the first level ffmpeg directory, the \texttt{typ.ext} files are for encoder (rendering) setups.
+\paragraph{Encoder Options:} \index{ffmpeg!encoder options} Within the audio/video subdirectories of the first level ffmpeg directory, the \texttt{typ.ext} files are for encoder (rendering) setups.
\begin{center}
\begin{longtable}{l p{23em}}
\subsection{Option File Format / Content}%
\label{sub:option_file_format_content}
+\index{ffmpeg!option file format}
For the option files a specific format must be followed in creating the file content.
+AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
In \texttt{typ.ext} encoder parameter files, the first line is defined as:
\begin{lstlisting}[style=sh]
For illustrative purposes, here is an example of the options files that need to be added for using the ffmpeg \textit{ProRes 422} format. This makes it possible to transcode to \texttt{h264.mov} with FFmpeg retaining \textit{10-bit yuv422p} from the source to the target output video.
-Add the file named \texttt{./ffmpeg/audio/acc256k.pro} which contains the following lines:
+Add the file named \texttt{./ffmpeg/audio/aac256k.pro} which contains the following lines:
\begin{lstlisting}[style=sh]
mov aac
Add the file named \texttt{./ffmpeg/audio/pro.dfl} which contains the following lines:
\begin{lstlisting}[style=sh]
-acc256k.pro
+aac256k.pro
\end{lstlisting}
Add the file named \texttt{./ffmpeg/video/prores.pro} which contains the following lines:
\subsection{Modifying FFmpeg Format Options inside \CGG{}}%
\label{sub:modifying_ffmpeg_cinelerra}
+\index{ffmpeg!option file format}
+\index{ffmpeg!wrench}
+\index{ffmpeg!private options}
There are thousands of options for using ffmpeg. Now it is possible to \textit{view} the available options for a particular video and audio choice by using the \textit{wrench icon} and then clicking on the \textit{view} box. FFmpeg has to be the selected file format for this feature to be visible. It makes it a lot easier since only the applicable options show up as opposed to everything that ffmpeg can do. These options are just \textit{Hints} and some may be missing due to the way that ffmpeg options are coded -- \CGG{} shows the option data ffmpeg has exposed.
\label{fig:video-preset}
\end{figure}
-Figure~\ref{fig:audio-preset02} shows \textit{ffmpeg} video for the Kind. Note the yellow tooltip in the lower right hand corner describing the highlighted option. Also note the allowed \textit{Range} values above the box provided for keyins. There is also the \textit{format} window with private options.
+Figure~\ref{fig:audio-preset02} shows \textit{ffmpeg} video for the Kind. Note the colored tooltip in the lower right hand corner describing the highlighted option. Also note the allowed \textit{Range} values above the box provided for keyins. There is also the \textit{format} window with private options.
\begin{figure}[htpb]
\centering
\section{The FFmpeg Image2 Streams}%
\label{sec:ffmpeg_image2_streams}
+\index{ffmpeg!image2 streams}
Another feature gained from using ffmpeg in \CGG{} takes advantage of what is being referred to as the \textit{\%d trick}. This trick uses the ffmpeg muxer image2 and a filename template to create a series of image files of a given type. A specific example is described below.
+AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
To encode a series of $48$\,bit tiff output image files, add a file to the \CGG{} data ffmpeg/video subdirectory as in:
\begin{lstlisting}[style=sh]
-# \dots/ffmpeg/video/tiff.dfl
+# {path_to_cinelerra}/bin/ffmpeg/video/tiff.dfl
tiff48.tif
\end{lstlisting}
Then create an ffmpeg video encoder parameters file in the same directory:
\begin{lstlisting}[style=sh]
-# \dots/ffmpeg/video/tiff48.tiff
+# {path_to_cinelerra}/bin/ffmpeg/video/tiff48.tiff
image2 tiff
pixel_format=rgb48
\end{lstlisting}
\section{Raw Input Opts File for Video/Audio}%
\label{sec:raw_input_opts_video_audio}
+\index{ffmpeg!raw input options}
Raw video is not affected by decoding on read in. This makes it very attractive to provide raw image data for editing and rendering media. A wide variety of raw formats are available via the ffmpeg file interface. To load media in a raw format, select \textit{try ffmpeg first} and create an accompanying \textit{opts} file. The opts files must be in the same directory as your media, with the same base name, and the \texttt{.opts} extension. The opts file contents should reflect your video setup. An example follows:
\section{FFmpeg Items of Note}%
\label{sec:ffmpeg_items_note}
+\index{ffmpeg!notes}
\begin{description}
\item[Quality Option when rendering:] FFmpeg responds variably to the quality option in the render option but seems to respond well to bitrate. The subranges used by quality even seem to vary somewhat depending on how old the codec is. Some use $0$ to $35$, some use $0$ to $500$ or so. The quality is supposed to cause the codec to output data until the noise level is below a limit determined by the quality setting. Your specific results may vary.
--- /dev/null
+\chapter{FAQ, Known Problems and Workarounds}%
+\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. 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, 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
+ \item edit or add the files you want to modify in the \textit{bin} or \textit{lib} subdirecctory
+ \item /path-to-appimage/squashfs-root/usr/bin/cin
+\end{itemize}
+For more detailed information on working with AppImages, see \ref{sub:managing_appimage}.
+
+\paragraph{Workaround for the \textit{alpha channel not working as intended when using an EDL} inserted as a reference or when an EDL is nested.}
+Using the Projector on the EDL within a Master Project follow these next steps.
+\begin{itemize}
+ \item Open your EDL with \textit{Open EDL} by using the MMB (Middle Mouse Button) on the Nested edit on its track.
+ \item In this nested EDL, insert a new Video track below the last video track.
+ \item Add the Alpha plugin to the new Video track for the entire length of the nested EDL.
+ \item Change the value of the Alpha to 0.00. The Alpha Plugin may be disabled or left enabled.
+ \item Close the EDL.
+\end{itemize} This solves the alpha channel not working as expected and the Master Project now looks correct.
+
+\paragraph{Workaround for using a transition, like Dissolve, between 2 edits with the plugin Motion51.}
+In this case, the Motion51 plugin and the Dissolve transition are not seen during the transition phase
+and is stopped at the cut point between 2 edits.
+The left edit's plugin should be in effect until the end of that clip and should include the
+dissolve. Instead, there is a jump inside the dissolve, as if the plugin does not exist. There are
+2 possible workarounds. For example, extend the Motion51 plugin to cover both clips rather than
+having a separate plugin for each clip. Or another workaround is to use two tracks and have the
+plugin cover the cut point and use a Fade auto instead of the Dissolve transition.
+
+\paragraph{The Fade auto in certain circumstances produces an unwanted black flash.}
+When you insert an effect on an empty track the fade fades as if it were on a black background;
+it interprets the alpha as black where there is transparency, which is what produces the fade.
+So the problem in the case of text is that the letters appear as a black flash briefly in the first
+few frames, then goes back to transparent, then the fade starts normally with the white color.
+To avoid the unwanted effect produced by the fade over black (because there is no content) leave
+the fade in/out of the effect at 0 and use the fade line to perform the intended results to
+avoid the problem with the alpha channel. The same problem occurs when using transparent PNG
+images with fade video transitions and can be resolved in the same manner.
+However this workaround can be quite tedious and complicated if you want to fade many snippets of text
+and transparent PNGs on the same track, with always the same video transition filter set to the same
+duration.
+
+Just a side note here. Fade in/out in the Title plugin works fine if there is a clip/image above
+the plugin in the same track without an alpha channel but not if there is no clip/image.
+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:
+
+\begin{enumerate}
+ \item You create/open the \textit{Mixer Viewer} with \texttt{Open Mixers} in Resources window for the Videos with Audio. It will create, in the timeline, one Video track and two Audio tracks for each Media (Video/Audio), and its Mixer Viewer.
+ \item Add a new Video track (\texttt{Shift+T} shortcut) and two Audio tracks (\texttt{t} shortcut) for your audio (Left+Right channels?) without video: you are adding an empty Video track because \texttt{Align Mixers} feature needed a video track.
+ \item Move the Video track down until it is on the top of the two Audio
+ tracks.
+ \item Insert your Audio into the two Audio tracks in the usual way.
+ \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}
+
-\nomenclature{\textbf{Alpha channel}}{an extra channel in color models for storing information about transparency. If a pixel has a value of 0\% as its alpha channel, it is completely transparent or invisible; a value of 100\% as its alpha channel provides a fully opaque pixel.}
+\nomenclature{\color{CinBlueText}{Alpha channel}}{an extra channel in color models for storing information about transparency. If a pixel has a value of 0\% as its alpha channel, it is completely transparent or invisible; a value of 100\% as its alpha channel provides a fully opaque pixel.}
-\nomenclature{\textbf{Arm}}{when you \textit{arm} a track, it is enabled so fully affected by editing operations. Tracks are armed with an \texttt{Arm Track} button in the patchbay of the timeline.}
+\nomenclature{\color{CinBlueText}{Arm}}{when you \textit{arm} a track, it is enabled so fully affected by editing operations. Tracks are armed with an \texttt{Arm Track} button in the patchbay of the timeline.}
-\nomenclature{\textbf{Arrow mode}}{formally known as Drag and Drop editing mode. Drag and drop editing is a quick and simple way of working in \CGG{}, using mainly the mouse. In this mode, you move \textit{things} by dragging and dropping these resources or objects.}
+\nomenclature{\color{CinBlueText}{Arrow mode}}{formally known as Drag and Drop editing mode. Drag and drop editing is a quick and simple way of working in \CGG{}, using mainly the mouse. In this mode, you move \textit{things} by dragging and dropping these resources or objects.}
-\nomenclature{\textbf{Aspect ratio}}{in reference to an image, this is the geometry of the data as in the ratio of its width to its height. There is the display aspect ratio which is the physical display and may not always be square. Then there is the pixel aspect ratio or geometry of the picture.}
+\nomenclature{\color{CinBlueText}{Aspect ratio}}{in reference to an image, this is the geometry of the data as in the ratio of its width to its height. There is the display aspect ratio which is the physical display and may not always be square. Then there is the pixel aspect ratio or geometry of the picture.}
-\nomenclature{\textbf{Assets}}{the representation of media loaded in the Resources Window and on the timeline. These assets are the objects of the editing. You can think of an asset as the original file that was loaded from your operating system’s disk but it also represents clips and nested clips. These are data objects in the program that contains all the parameters it takes to read or write that media.}
+\nomenclature{\color{CinBlueText}{Assets}}{the representation of media loaded in the Resources Window and on the timeline. These assets are the objects of the editing. You can think of an asset as the original file that was loaded from your operating system’s disk but it also represents clips and nested clips. These are data objects in the program that contains all the parameters it takes to read or write that media.}
-\nomenclature{\textbf{Audio offset}}{audio displacement applied to the playback position to synchronize playback with other tracks.}
+\nomenclature{\color{CinBlueText}{Audio offset}}{audio displacement applied to the playback position to synchronize playback with other tracks.}
-\nomenclature{\textbf{Automatic keyframes}}{every time you tweak a key-framable parameter it “automatically” creates a keyframe on the timeline. Since automatic keyframes affect many parameters, it is best enabled just before you need a keyframe and disabled immediately after. Effects are only keyframable in automatic mode because of the number of parameters in each individual effect. Enable automatic keyframe mode by enabling the automatic keyframe toggle on the timeline editpanel.}
+\nomenclature{\color{CinBlueText}{Automatic keyframes}}{every time you tweak a key-framable parameter it “automatically” creates a keyframe on the timeline. Since automatic keyframes affect many parameters, it is best enabled just before you need a keyframe and disabled immediately after. Effects are only keyframable in automatic mode because of the number of parameters in each individual effect. Enable automatic keyframe mode by enabling the automatic keyframe toggle on the timeline editpanel.}
-\nomenclature{\textbf{Autos}}{short term for automation keyframes. Autos are created by clicking on an "automation curve" represented by a colored line, to establish the time position for the new keyframe anchor point. They are usually drawn as a colored square or a symbol on a media track.}
+\nomenclature{\color{CinBlueText}{Autos}}{short term for automation keyframes. Autos are created by clicking on an "automation curve" represented by a colored line, to establish the time position for the new keyframe anchor point. They are usually drawn as a colored square or a symbol on a media track.}
-\nomenclature{\textbf{Bezier curve}}{a parametric curve used in computer graphics. In image manipulation programs, bezier curves are used to model smooth curves.}
+\nomenclature{\color{CinBlueText}{Bezier curve}}{a parametric curve used in computer graphics. In image manipulation programs, bezier curves are used to model smooth curves.}
-\nomenclature{\textbf{Bitrate}}{represents the amount of information that is stored per unit of time of a recording. The higher the bitrate, the higher the quality.}
+\nomenclature{\color{CinBlueText}{Bitrate}}{represents the amount of information that is stored per unit of time of a recording. The higher the bitrate, the higher the quality. When setting Bitrate in rendering, be sure to not set any Quality or CRF values because they take precdence.}
-\nomenclature{\textbf{Brightness}}{human perception of the amount of light emitted by a source; overall lightness or darkness of an image. In video signals it is represented by luma. The measure of brightness is value.}
+\nomenclature{\color{CinBlueText}{Brightness}}{human perception of the amount of light emitted by a source; overall lightness or darkness of an image. In video signals it is represented by luma. The measure of brightness is value.}
-\nomenclature{\textbf{Buffer}}{a region of memory used to temporarily hold output or input data, used when there is a difference between the rate at which data is received and the rate at which it can be processed, or in the case that these rates are variable. Buffers are allocated by various processes to use as input queues, etc. A simplistic explanation of buffers is that they allow processes to temporarily store input in memory until the process can deal with it.}
+\nomenclature{\color{CinBlueText}{Buffer}}{a region of memory used to temporarily hold output or input data, used when there is a difference between the rate at which data is received and the rate at which it can be processed, or in the case that these rates are variable. Buffers are allocated by various processes to use as input queues, etc. A simplistic explanation of buffers is that they allow processes to temporarily store input in memory until the process can deal with it.}
-\nomenclature{\textbf{Bug}}{a defect in the program that causes it to not function correctly thus creating some kind of error. There are basically 2 kinds of bugs – doing something it should not or not doing something it should.}
+\nomenclature{\color{CinBlueText}{Bug}}{a defect in the program that causes it to not function correctly thus creating some kind of error. There are basically 2 kinds of bugs – doing something it should not or not doing something it should.}
-\nomenclature{\textbf{Canvas}}{the place on the compositor where the final video is displayed. It can be imagined as the canvas of a painter or as the screen of a movie theater.}
+\nomenclature{\color{CinBlueText}{Canvas}}{the place on the compositor where the final video is displayed. It can be imagined as the canvas of a painter or as the screen of a movie theater.}
-\nomenclature{\textbf{Chroma}}{the signal used in many video systems to carry the color information of the picture separately from the accompanying luma signal. Luma represents the achromatic image without any color (like a black and white picture), while the chroma components represent the color information.}
+\nomenclature{\color{CinBlueText}{Chroma}}{the signal used in many video systems to carry the color information of the picture separately from the accompanying luma signal. Luma represents the achromatic image without any color (like a black and white picture), while the chroma components represent the color information.}
-\nomenclature{\textbf{Clip}}{a short segment of media which was usually part of a longer recording. A section of a project consisting of a set of timeline selected edits treated as an independent object.}
+\nomenclature{\color{CinBlueText}{Clip}}{a short segment of media which was usually part of a longer recording. A section of a project consisting of a set of timeline selected edits treated as an independent object.}
-\nomenclature{\textbf{Clipping}}{to set a data value above an threshold to be equal to that threshold.}
+\nomenclature{\color{CinBlueText}{Clipping}}{to set a data value above an threshold to be equal to that threshold.}
-\nomenclature{\textbf{Codec}}{contraction of \textbf{co}der and \textbf{dec}oder; used to generally compress media and decompress to reproduce it. Results are a trade-off between bitrate and quality.}
+\nomenclature{\color{CinBlueText}{Codec}}{contraction of \textbf{co}der and \textbf{dec}oder; used to generally compress media and decompress to reproduce it. Results are a trade-off between bitrate and quality.}
-\nomenclature{\textbf{Color correction}}{Same as color grading. Some people use it with slightly different meanings: minimizing error between the image and the original object. Corrects exposure and color dominants. There is the primary CC, which covers the entire frame; and the secondary CC, which isolates and intervenes only on specific parts of the frame.}
+\nomenclature{\color{CinBlueText}{Color correction}}{Same as color grading. Some people use it with slightly different meanings: minimizing error between the image and the original object. Corrects exposure and color dominants. There is the primary CC, which covers the entire frame; and the secondary CC, which isolates and intervenes only on specific parts of the frame.}
-\nomenclature{\textbf{Color grading}}{Same as color correction. Some people use it with slightly different meanings: Correct the color and contrast of a shot to personalize it and make it more nicer or communicative. An example is the Teal \& Orange, which is widely used in Hollywood movies.}
+\nomenclature{\color{CinBlueText}{Color grading}}{Same as color correction. Some people use it with slightly different meanings: Correct the color and contrast of a shot to personalize it and make it more nicer or communicative. An example is the Teal \& Orange, which is widely used in Hollywood movies.}
-\nomenclature{\textbf{Color model}}{an abstract mathematical model describing the way colors can be represented as an ordered list of numbers, typically as three values or color components (for example, RGB).}
+\nomenclature{\color{CinBlueText}{Color model}}{an abstract mathematical model describing the way colors can be represented as an ordered list of numbers, typically as three values or color components (for example, RGB).}
-\nomenclature{\textbf{Concatenate}}{in File$\rightarrow$Load insertion strategy, means to load from disk or copy from the timeline edits belonging to different media onto the same set of tracks, one right after the other.}
+\nomenclature{\color{CinBlueText}{Concatenate}}{in File$\rightarrow$Load insertion strategy, means to load from disk or copy from the timeline edits belonging to different media onto the same set of tracks, one right after the other.}
-\nomenclature{\textbf{Compression}}{in \CGG{}’s dialogs means compression format. See Codec.}
+\nomenclature{\color{CinBlueText}{Compression}}{in \CGG{}’s dialogs means compression format. See Codec. In a media video the compression can be Intraframe (within each frame) or it can be about Groups Of Pictures (GOP and Long GOP) between frames, i.e. Interframe. Also, the compression algorithm can be lossy or lossless. Lossy and Interframe are also fine for editing, but for Color Correction, Chroma-Key and Rotoscoping, lossless and Intraframe compression is required.}
-\nomenclature{\textbf{Context menu}}{a pop-up menu.}
+\nomenclature{\color{CinBlueText}{Context menu}}{a pop-up menu.}
-\nomenclature{\textbf{Control point}}{as applied to Bezier curves, either the \textit{end} points or \textit{way points}. Controls the derivative at that end or way point of that curve. Vector of the curve point derivative.}
+\nomenclature{\color{CinBlueText}{Control point}}{as applied to Bezier curves, either the \textit{end} points or \textit{way points}. Controls the derivative at that end or way point of that curve. Vector of the curve point derivative.}
-\nomenclature{\textbf{CR2}}{the RAW image format of Canon’s digital cameras. In \CGG{}, it is used loosely to refer to any brand of camera raw images or still pictures, as handled by Dave Coffin’s included code.}
+\nomenclature{\color{CinBlueText}{CR2}}{the RAW image format of Canon’s digital cameras. In \CGG{}, it is used loosely to refer to any brand of camera raw images or still pictures, as handled by Dave Coffin’s included code.}
-\nomenclature{\textbf{Crop}}{rectangularly trim edges to remove unwanted material.}
+\nomenclature{\color{CinBlueText}{Crop}}{rectangularly trim edges to remove unwanted material.}
-\nomenclature{\textbf{Cut}}{delete or trim to remove material or insert a break so that the media on the timeline is separated into 2 pieces. Cut, when used as a noun can mean the same as an edit.}
+\nomenclature{\color{CinBlueText}{Cut}}{delete or trim to remove material or insert a break so that the media on the timeline is separated into 2 pieces. Cut, when used as a noun can mean the same as an edit.}
-\nomenclature{\textbf{Cut and Paste editing}}{an editing mode on the timeline. You select the cut and paste editing mode by enabling the I-beam toggle on the control bar at the top of the main program window. The I-beam cursor pointer on the timeline is why this mode has the nickname of I-beam. In this mode you can copy edits in the same track, copy from different tracks in the same instance, start a second instance of \CGG{} and copy from one instance to the other or load a media file into the Viewer and copy from there. There are many other operations that can be done.}
+\nomenclature{\color{CinBlueText}{Cut and Paste editing}}{an editing mode on the timeline. You select the cut and paste editing mode by enabling the I-beam toggle on the control bar at the top of the main program window. The I-beam cursor pointer on the timeline is why this mode has the nickname of I-beam. In this mode you can copy edits in the same track, copy from different tracks in the same instance, start a second instance of \CGG{} and copy from one instance to the other or load a media file into the Viewer and copy from there. There are many other operations that can be done.}
-\nomenclature{\textbf{Deinterlace}}{the process of converting interlaced video (a sequence of fields) into a non-interlaced form (a sequence of frames). Deinterlacing downsamples/blends the refreshes that reconstruct images with the least motion damage. See the definition of Interlace for an explanation of interlacing.}
+\nomenclature{\color{CinBlueText}{Deinterlace}}{the process of converting interlaced video (a sequence of fields) into a non-interlaced form (a sequence of frames). Deinterlacing downsamples/blends the refreshes that reconstruct images with the least motion damage. See the definition of Interlace for an explanation of interlacing.}
-\nomenclature{\textbf{Disarm}}{when you “disarm” a track, it is disabled so not affected by editing operations. Disarming a track protects it from most changes and operations. Tracks are disarmed with an "Arm Track" button in the patchbay of the timeline.}
+\nomenclature{\color{CinBlueText}{Disarm}}{when you “disarm” a track, it is disabled so not affected by editing operations. Disarming a track protects it from most changes and operations. Tracks are disarmed with an "Arm Track" button in the patchbay of the timeline.}
-\nomenclature{\textbf{Drag and Drop editing}}{drag and drop editing is a quick and simple way of working in \CGG{} using mainly the mouse. In this mode, you move “things” by dragging and dropping these resources or objects. To enable, click on the arrow icon in the timeline editpanel. This arrow is why this mode has the nickname of arrow mode.}
+\nomenclature{\color{CinBlueText}{Drag and Drop editing}}{drag and drop editing is a quick and simple way of working in \CGG{} using mainly the mouse. In this mode, you move “things” by dragging and dropping these resources or objects. To enable, click on the arrow icon in the timeline editpanel. This arrow is why this mode has the nickname of arrow mode.}
-\nomenclature{\textbf{Edit(s)}}{is a fragment of media on a single track of the timeline.}
+\nomenclature{\color{CinBlueText}{Edit(s)}}{is a fragment of media on a single track of the timeline.}
-\nomenclature{\textbf{Edit Decision List (EDL)}}{an XML text file that contains all the project settings and locations of every edit. Instead of media, it contains pointers to the original media files on disk. If you open your .xml project file with a text editor, you will see some of the terminology used in \CGG{} in reference to the editing you perform.}
+\nomenclature{\color{CinBlueText}{Edit Decision List (EDL)}}{an XML text file that contains all the project settings and locations of every edit. Instead of media, it contains pointers to the original media files on disk. If you open your .xml project file with a text editor, you will see some of the terminology used in \CGG{} in reference to the editing you perform.}
-\nomenclature{\textbf{Edit panel}}{the second line on the timeline which shows icons that represent transport controls and editing functions. It is sometimes called the Control Bar.}
+\nomenclature{\color{CinBlueText}{Edit panel}}{the second line on the timeline which shows icons that represent transport controls and editing functions. It is sometimes called the Control Bar.}
-\nomenclature{\textbf{Field}}{in interlace, the scan of every second line. An interlaced video frame consists of two sub-fields taken in sequence, each sequentially scanned at odd and then even lines of the image sensor.}
+\nomenclature{\color{CinBlueText}{Field}}{in interlace, the scan of every second line. An interlaced video frame consists of two sub-fields taken in sequence, each sequentially scanned at odd and then even lines of the image sensor.}
-\nomenclature{\textbf{File format}}{generally refers to a block network stream format that multiplexes multiple audio/video streams to create presentation output.}
+\nomenclature{\color{CinBlueText}{File format}}{generally refers to a block network stream format that multiplexes multiple audio/video streams to create presentation output.}
-\nomenclature{\textbf{Filter}}{a program to process a data stream, often it is used in referring to effects or plugins. Many people use this in referencing the included FFmpeg plugins since that is what it is called in ffmpeg.}
+\nomenclature{\color{CinBlueText}{Filter}}{a program to process a data stream, often it is used in referring to effects or plugins. Many people use this in referencing the included FFmpeg plugins since that is what it is called in ffmpeg.}
-\nomenclature{\textbf{Footage}}{in filmmaking and video production, footage is the raw, unedited material as it had been originally filmed by a movie camera or recorded by a video camera, which usually must be edited to create a motion picture, video clip, television show or similar completed work.}
+\nomenclature{\color{CinBlueText}{Footage}}{in filmmaking and video production, footage is the raw, unedited material as it had been originally filmed by a movie camera or recorded by a video camera, which usually must be edited to create a motion picture, video clip, television show or similar completed work.}
-\nomenclature{\textbf{Frame}}{any image in a sequence of images that form an animated video.}
+\nomenclature{\color{CinBlueText}{Frame}}{any image in a sequence of images that form an animated video.}
-\nomenclature{\textbf{Gadget}}{a composition of widgets. See widget definition.}
+\nomenclature{\color{CinBlueText}{Gadget}}{a composition of widgets. See widget definition.}
-\nomenclature{\textbf{Gamma}}{color and contrast shaping using an exponential math function to enhance or retard color contrast, either color or brightness.}
+\nomenclature{\color{CinBlueText}{Gamma}}{color and contrast shaping using an exponential math function to enhance or retard color contrast, either color or brightness.}
-\nomenclature{\textbf{GDB}}{Gnu DeBugger, a Linux program for testing and some help in finding the errors in another program.}
+\nomenclature{\color{CinBlueText}{GDB}}{Gnu DeBugger, a Linux program for testing and some help in finding the errors in another program.}
-\nomenclature{\textbf{Git}}{is a distributed version control system for tracking changes in source code during software development. It is fast and easy to work with git repositories for collaboration among several developers on the same software project.}
+\nomenclature{\color{CinBlueText}{Git}}{is a distributed version control system for tracking changes in source code during software development. It is fast and easy to work with git repositories for collaboration among several developers on the same software project.}
-\nomenclature{\textbf{GPU}}{stands for the Graphics Processor Unit of a computer graphics board. For \CGG{}, direct decoding or encoding using the GPU via hardware acceleration often reduces CPU usage.}
+\nomenclature{\color{CinBlueText}{GPU}}{stands for the Graphics Processor Unit of a computer graphics board. For \CGG{}, direct decoding or encoding using the GPU via hardware acceleration often reduces CPU usage.}
-\nomenclature{\textbf{GUI}}{Graphical User Interface allows people to interact with the computer by manipulating graphical icons, visual indicators or widgets, along with text labels or text navigation to represent the information and actions available to a user. This is in contrast to Command Line Interface (CLI).}
+\nomenclature{\color{CinBlueText}{GUI}}{Graphical User Interface allows people to interact with the computer by manipulating graphical icons, visual indicators or widgets, along with text labels or text navigation to represent the information and actions available to a user. This is in contrast to Command Line Interface (CLI).}
-\nomenclature{\textbf{GUICAST}}{\CGG{}’s GUI library, made from scratch by Heroine Virtual Ltd.}
+\nomenclature{\color{CinBlueText}{GUICAST}}{\CGG{}’s GUI library, made from scratch by Heroine Virtual Ltd.}
-\nomenclature{\textbf{Handle}}{is a graphical grab point to adjust any number of different graphical parameters, such as an edit position or a mask curvature. The handle becomes active when approached within a certain range, then you will generally see a modified cursor indicator. This is the hot point to grab and click to use it.}
+\nomenclature{\color{CinBlueText}{Handle}}{is a graphical grab point to adjust any number of different graphical parameters, such as an edit position or a mask curvature. The handle becomes active when approached within a certain range, then you will generally see a modified cursor indicator. This is the hot point to grab and click to use it.}
-\nomenclature{\textbf{HSV}}{Hue, Saturation, and Value is a color model that is often used in place of the RGB color model. In using this color model, a color is specified, then white or black is added to easily make adjustments.}
+\nomenclature{\color{CinBlueText}{HSV}}{Hue, Saturation, and Value is a color model that is often used in place of the RGB color model. In using this color model, a color is specified, then white or black is added to easily make adjustments.}
-\nomenclature{\textbf{Hue}}{that aspect of a color described with names such as yellow, red, blue. Hue also defines mixtures of two pure colors like "red-yellow" or "yellow-green".}
+\nomenclature{\color{CinBlueText}{Hue}}{that aspect of a color described with names such as yellow, red, blue. Hue also defines mixtures of two pure colors like "red-yellow" or "yellow-green".}
-\nomenclature{\textbf{Image list}}{a text file with a specific format containing a list of absolute paths for the still images of a sequence plus additional information like file format, framerate and image resolution. Image lists are human readable and editable. Once loaded in the timeline, image lists behave like a video clip. In \CGG{} they can be used to load multiple images belonging to the same scene as a single video asset. \CGG{} can render video clips to image lists (a text file + multiple still images).}
+\nomenclature{\color{CinBlueText}{Image list}}{a text file with a specific format containing a list of absolute paths for the still images of a sequence plus additional information like file format, framerate and image resolution. Image lists are human readable and editable. Once loaded in the timeline, image lists behave like a video clip. In \CGG{} they can be used to load multiple images belonging to the same scene as a single video asset. \CGG{} can render video clips to image lists (a text file + multiple still images).}
-\nomenclature{\textbf{I-beam mode}}{formally known as Cut and Paste editing mode where a lot of the operations performed on your video are with various copy commands. See Cut and Paste editing definition.}
+\nomenclature{\color{CinBlueText}{I-beam mode}}{formally known as Cut and Paste editing mode where a lot of the operations performed on your video are with various copy commands. See Cut and Paste editing definition.}
-\nomenclature{\textbf{Index file}}{an .idx, .mkr or .toc file built by \CGG{} in the .bcast5 directory of your home folder in order to quickly, and with less cpu involved, seek into big media files, for skipping, faster playback and drawing waveforms and picons. Index files are not human readable. If an index file for an asset is already built, it is not recreated – this saves a lot of time. However if you switch from a native format to using ffmpeg, or vice versa, you should always rebuild the index. The number of index files to keep can be set by the user and you can easily delete all of them at once from the Settings$\rightarrow$Preferences, Interface menu.}
+\nomenclature{\color{CinBlueText}{Index file}}{an .idx, .mkr or .toc file built by \CGG{} in the .bcast5 directory of your home folder in order to quickly, and with less cpu involved, seek into big media files, for skipping, faster playback and drawing waveforms and picons. Index files are not human readable. If an index file for an asset is already built, it is not recreated – this saves a lot of time. However if you switch from a native format to using ffmpeg, or vice versa, you should always rebuild the index. The number of index files to keep can be set by the user and you can easily delete all of them at once from the Settings$\rightarrow$Preferences, Interface menu.}
-\nomenclature{\textbf{Insertion point}}{a flashing hairline mark that vertically spans the timeline. It marks the starting place of the next operation to be performed.}
+\nomenclature{\color{CinBlueText}{Insertion point}}{a flashing hairline mark that vertically spans the timeline. It marks the starting place of the next operation to be performed.}
-\nomenclature{\textbf{Interlace}}{(extended definition included here because it is no longer a commonly used technique). Originally media was conditioned for presentation on a cathode ray tube (CRT), like an old-fashioned television set. The image sample was scanned using an image orthicon tube and vacuum tube oscillators. The result is very imprecise and too slow for the human eye. Interlacing, which is scanning the image by fields, first all the even and then all the odd lines, uses phosphor persistence to create a smooth presentation effect and reduce the required signal bandwidth. Today we use a progressive scan at a higher framerate to avoid these issues.}
+\nomenclature{\color{CinBlueText}{Interlace}}{(extended definition included here because it is no longer a commonly used technique). Originally media was conditioned for presentation on a cathode ray tube (CRT), like an old-fashioned television set. The image sample was scanned using an image orthicon tube and vacuum tube oscillators. The result is very imprecise and too slow for the human eye. Interlacing, which is scanning the image by fields, first all the even and then all the odd lines, uses phosphor persistence to create a smooth presentation effect and reduce the required signal bandwidth. Today we use a progressive scan at a higher framerate to avoid these issues.}
-\nomenclature{\textbf{Interpolation}}{a method of inventing data using keyframe way points on a curve. The shape of the curve represents the type of the interpolation, for example piecewise linear or bezier. In \CGG{} interpolation is the process that inserts many new values in between the user defined keyframes to give a smoother result.}
+\nomenclature{\color{CinBlueText}{Interpolation}}{a method of inventing data using keyframe way points on a curve. The shape of the curve represents the type of the interpolation, for example piecewise linear or bezier. In \CGG{} interpolation is the process that inserts many new values in between the user defined keyframes to give a smoother result.}
-\nomenclature{\textbf{Jitter}}{broken sound or video, frequently due to quantimization encoding, resulting in data loss.}
+\nomenclature{\color{CinBlueText}{Jitter}}{broken sound or video, frequently due to quantimization encoding, resulting in data loss.}
-\nomenclature{\textbf{Keyframe}}{a blob of parameter data associated to a position on the timeline. It represents a certain value set by the user at a certain point in the timeline and is used as input to some edit functions such as a fade, an effect, or a compositing parameter. Keyframes are described in detail in the Keyframes section, chapter 8.}
+\nomenclature{\color{CinBlueText}{Keyframe}}{a blob of parameter data associated to a position on the timeline. It represents a certain value set by the user at a certain point in the timeline and is used as input to some edit functions such as a fade, an effect, or a compositing parameter. Keyframes are described in detail in the Keyframes section, chapter 8.}
-\nomenclature{\textbf{Keyframing}}{a very convenient technique for creating smooth dynamic changes by assigning values to parameters at specific moments in time and letting \CGG{} interpolate the values in between.}
+\nomenclature{\color{CinBlueText}{Keyframing}}{a very convenient technique for creating smooth dynamic changes by assigning values to parameters at specific moments in time and letting \CGG{} interpolate the values in between.}
-\nomenclature{\textbf{Latency}}{refers to a short period of delay, usually measured in milliseconds, between when an audio signal enters a system and when it emerges.}
+\nomenclature{\color{CinBlueText}{Latency}}{refers to a short period of delay, usually measured in milliseconds, between when an audio signal enters a system and when it emerges.}
-\nomenclature{\textbf{Locale}}{a set of parameters that defines your language, country and other location related preferences that you want to see in your GUI. Usually a locale identifier consists of at least a language identifier and a region identifier. Example: “[language[\_territory][.codeset][@modifier]]”. It affects the language in which \CGG{} will display menus and messages. To check your locale type locale in your terminal window. To see your available locales type locale -a.}
+\nomenclature{\color{CinBlueText}{Locale}}{a set of parameters that defines your language, country and other location related preferences that you want to see in your GUI. Usually a locale identifier consists of at least a language identifier and a region identifier. Example: “[language[\_territory][.codeset][@modifier]]”. It affects the language in which \CGG{} will display menus and messages. To check your locale type locale in your terminal window. To see your available locales type locale -a.}
-\nomenclature{\textbf{Lossless}}{term describing a compression method that allows the exact original data to be reconstructed from the compressed data, without any changes. Lossless compression is used for text and data files, but also for multimedia when quality is more important than file size.}
+\nomenclature{\color{CinBlueText}{Lossless}}{term describing a compression method that allows the exact original data to be reconstructed from the compressed data, without any changes. Lossless compression is used for text and data files, but also for multimedia when quality is more important than file size.}
-\nomenclature{\textbf{Lossy}}{term describing a compression method where compressing and then decompressing retrieves data that may well be different from the original, but is close enough to be useful in some way. Lossy compression is most commonly used to compress multimedia (audio, video, still images), especially for streaming. Repeatedly compressing and decompressing the file will cause, for most lossy compression formats, to progressively lose quality. MP3 is an example.}
+\nomenclature{\color{CinBlueText}{Lossy}}{term describing a compression method where compressing and then decompressing retrieves data that may well be different from the original, but is close enough to be useful in some way. Lossy compression is most commonly used to compress multimedia (audio, video, still images), especially for streaming. Repeatedly compressing and decompressing the file will cause, for most lossy compression formats, to progressively lose quality. MP3 is an example.}
-\nomenclature{\textbf{Luma/Luminance}}{Luma represents the achromatic image without any color (like a black and white picture), the part of a video signal that includes information about its brightness. Luma is typically paired with chroma - luma represents the image without any color, while the chroma components represent the color information. Luma is designated with the letter Y.}
+\nomenclature{\color{CinBlueText}{Luma/Luminance}}{Luma represents the achromatic image without any color (like a black and white picture), the part of a video signal that includes information about its brightness. Luma is typically paired with chroma - luma represents the image without any color, while the chroma components represent the color information. Luma is designated with the letter Y.}
-\nomenclature{\textbf{Media}}{generic term for audio, videos and images on some kind of storage. This can include items as a short movie recorded on your phone, photos from your camera, MP3 songs, or a movie trailer.}
+\nomenclature{\color{CinBlueText}{Media}}{generic term for audio, videos and images on some kind of storage. This can include items as a short movie recorded on your phone, photos from your camera, MP3 songs, or a movie trailer.}
-\nomenclature{\textbf{NLE}}{Non Linear Editing. A modern editing method used by \CGG{} that records the decisions of the editor in an edit decision list (EDL) without modifying the original source files.}
+\nomenclature{\color{CinBlueText}{NLE}}{Non Linear Editing. A modern editing method used by \CGG{} that records the decisions of the editor in an edit decision list (EDL) without modifying the original source files.}
-\nomenclature{\textbf{NTSC}}{stands for National Television System Committee; a standard that defines a video with canvas size of 720x480 and a framerate of 29.97 fps. This was originally based on United States broadcast television.}
+\nomenclature{\color{CinBlueText}{NTSC}}{stands for National Television System Committee; a standard that defines a video with canvas size of 720x480 and a framerate of 29.97 fps. This was originally based on United States broadcast television.}
-\nomenclature{\textbf{On the fly}}{consumed as produced in real time.}
+\nomenclature{\color{CinBlueText}{On the fly}}{consumed as produced in real time.}
-\nomenclature{\textbf{PAL}}{stands for Phase Alternating Line; a standard that defines a video with canvas size of 720x576 and a framerate of 25 fps. This is based on a European standard for broadcast television.}
+\nomenclature{\color{CinBlueText}{PAL}}{stands for Phase Alternating Line; a standard that defines a video with canvas size of 720x576 and a framerate of 25 fps. This is based on a European standard for broadcast television.}
-\nomenclature{\textbf{Patch}}{an incremental change of any kind of program source.}
+\nomenclature{\color{CinBlueText}{Patch}}{an incremental change of any kind of program source.}
-\nomenclature{\textbf{Patchbay}}{the area on the left of the timeline that contains the controls to enable features specific to each track.}
+\nomenclature{\color{CinBlueText}{Patchbay}}{the area on the left of the timeline that contains the controls to enable features specific to each track.}
-\nomenclature{\textbf{Picons}}{miniature images, also called thumbnails, of the video. In the Resources Window they represent the first frame of the asset. On the Timeline they imitate a physical film and are derived from the video data in the media file.}
+\nomenclature{\color{CinBlueText}{Picons}}{miniature images, also called thumbnails, of the video. In the Resources Window they represent the first frame of the asset. On the Timeline they imitate a physical film and are derived from the video data in the media file.}
-\nomenclature{\textbf{Pillarbox}}{blacks bars on the top and bottom and/or left and right side of the frame. They are due to a smaller frame size than the one set in the project.}
+\nomenclature{\color{CinBlueText}{Pillarbox}}{blacks bars on the top and bottom and/or left and right side of the frame. They are due to a smaller frame size than the one set in the project.}
-\nomenclature{\textbf{Pixel}}{the smallest independent unit of a digital image; a minute area of illumination on a display screen, one of many from which an image is composed. Word was invented from picture element. In the 3D world, this is call a voxel.}
+\nomenclature{\color{CinBlueText}{Pixel}}{the smallest independent unit of a digital image; a minute area of illumination on a display screen, one of many from which an image is composed. Word was invented from picture element. In the 3D world, this is call a voxel.}
-\nomenclature{\textbf{Plugin}}{program fragment that is loaded on demand as in “plugged in”. In \CGG{}, these are often called “effects” and are used to provide a specific function on demand.}
+\nomenclature{\color{CinBlueText}{Plugin}}{program fragment that is loaded on demand as in “plugged in”. In \CGG{}, these are often called “effects” and are used to provide a specific function on demand.}
-\nomenclature{\textbf{Pop-up menu}}{a menu that pops up by clicking the right mouse button. Also called a context menu.}
+\nomenclature{\color{CinBlueText}{Pop-up menu}}{a menu that pops up by clicking the right mouse button. Also called a context menu.}
-\nomenclature{\textbf{Progressive scan}}{a method for capturing, storing, displaying or transmitting moving images in which the lines of each frame are drawn in sequence, in a path similar to text on a page - line by line, from top to bottom. It is in contrast to the “interlace” used in traditional television systems.}
+\nomenclature{\color{CinBlueText}{Progressive scan}}{a method for capturing, storing, displaying or transmitting moving images in which the lines of each frame are drawn in sequence, in a path similar to text on a page - line by line, from top to bottom. It is in contrast to the “interlace” used in traditional television systems.}
-\nomenclature{\textbf{Project}}{consists of the EDL, media, and other associated data objects to comprise the entire session for the purpose of rendering/creating the final result.}
+\nomenclature{\color{CinBlueText}{Project}}{consists of the EDL, media, and other associated data objects to comprise the entire session for the purpose of rendering/creating the final result.}
-\nomenclature{\textbf{Proxy file}}{a copy of an original media file but with low resolution or quality, used as temporary media for editing with lower CPU load or I/O. Rendering is then done with the high quality original.}
+\nomenclature{\color{CinBlueText}{Proxy file}}{a copy of an original media file but with low resolution or quality, used as temporary media for editing with lower CPU load or I/O. Rendering is then done with the high quality original.}
-\nomenclature{\textbf{Raw image}}{an image file containing the unprocessed data from the image sensor of a digital camera or a scanner. Raw images from many different cameras can be loaded in \CGG{}. There are quite a wide-range variety of raw formats in existence.}
+\nomenclature{\color{CinBlueText}{Raw image}}{an image file containing the unprocessed data from the image sensor of a digital camera or a scanner. Raw images from many different cameras can be loaded in \CGG{}. There are quite a wide-range variety of raw formats in existence.}
-\nomenclature{\textbf{Record}}{the acquisition and storage of some media}
+\nomenclature{\color{CinBlueText}{Record}}{the acquisition and storage of some media}
-\nomenclature{\textbf{Render farm}}{a set of computers that work closely together for rendering.}
+\nomenclature{\color{CinBlueText}{Render farm}}{a set of computers that work closely together for rendering.}
-\nomenclature{\textbf{Rendering}}{the process of applying the instructions contained in the edit decision list (EDL) to produce an audio and/or video file. Also any processing of video, such as in rendering effects to the compositor.}
+\nomenclature{\color{CinBlueText}{Rendering}}{the process of applying the instructions contained in the edit decision list (EDL) to produce an audio and/or video file. Also any processing of video, such as in rendering effects to the compositor.}
-\nomenclature{\textbf{Resize}}{to reduce, enlarge or reshape the outline of an image, thus preserving the relative measures of the distances inside it.}
+\nomenclature{\color{CinBlueText}{Resize}}{to reduce, enlarge or reshape the outline of an image, thus preserving the relative measures of the distances inside it.}
-\nomenclature{\textbf{Resolution}}{the size of a digital image, width and height, measured in pixels.}
+\nomenclature{\color{CinBlueText}{Resolution}}{the size of a digital image, width and height, measured in pixels.}
-\nomenclature{\textbf{Resource(s)}}{the actual media and support items available for your projects which includes assets, clips, transitions and effects. These are available in the Resources window when needed.}
+\nomenclature{\color{CinBlueText}{Resource(s)}}{the actual media and support items available for your projects which includes assets, clips, transitions and effects. These are available in the Resources window when needed.}
-\nomenclature{\textbf{RGB}}{(Red, Green, Blue) a color model in which red, green and blue lights are added together in various combinations to reproduce all the colors. RGBA is the same color model with extra information for transparency in the Alpha channel. This mimics the receptors in the human eye – that is why we use it!}
+\nomenclature{\color{CinBlueText}{RGB}}{(Red, Green, Blue) a color model in which red, green and blue lights are added together in various combinations to reproduce all the colors. RGBA is the same color model with extra information for transparency in the Alpha channel. This mimics the receptors in the human eye – that is why we use it!}
-\nomenclature{\textbf{Saturation}}{the intensity of a specific color. It measures the distance of a color from a neutral gray.}
+\nomenclature{\color{CinBlueText}{Saturation}}{the intensity of a specific color. It measures the distance of a color from a neutral gray.}
-\nomenclature{\textbf{Scale}}{to reduce or enlarge an image proportionally, preserving the ratio of the distances inside it. See resize.}
+\nomenclature{\color{CinBlueText}{Scale}}{to reduce or enlarge an image proportionally, preserving the ratio of the distances inside it. See resize.}
-\nomenclature{\textbf{SEGV}}{Segmentation Fault Violation - a page fault that fails to read or write memory. For example, attempting to write to a read-only location, or to overwrite part of the operating system.}
+\nomenclature{\color{CinBlueText}{SEGV}}{Segmentation Fault Violation - a page fault that fails to read or write memory. For example, attempting to write to a read-only location, or to overwrite part of the operating system.}
-\nomenclature{\textbf{Shell}}{a file containing a series of commands that provides an interface for users. In everyday use it indicates the Command Line. \CGG{} has a “shell cmds” icon on the upper right corner of the main timeline where user written shell scripts can be added and easily accessed without exiting.}
+\nomenclature{\color{CinBlueText}{Shell}}{a file containing a series of commands that provides an interface for users. In everyday use it indicates the Command Line. \CGG{} has a “shell cmds” icon on the upper right corner of the main timeline where user written shell scripts can be added and easily accessed without exiting.}
-\nomenclature{\textbf{Shot}}{in filmmaking and video production, a shot is a series of frames, that runs for an uninterrupted period of time. In film editing, a shot is the continuous footage or sequence between two edits or cuts. Loosely used to refer to a single camera image, i.e. a shot.}
+\nomenclature{\color{CinBlueText}{Shot}}{in filmmaking and video production, a shot is a series of frames, that runs for an uninterrupted period of time. In film editing, a shot is the continuous footage or sequence between two edits or cuts. Loosely used to refer to a single camera image, i.e. a shot.}
-\nomenclature{\textbf{Solo}}{to activate only one function of a functional set.}
+\nomenclature{\color{CinBlueText}{Solo}}{to activate only one function of a functional set.}
-\nomenclature{\textbf{Source}}{a file containing media that has been saved on your operating system disk in a file. Anything that provides data; origin of data.}
+\nomenclature{\color{CinBlueText}{Source}}{a file containing media that has been saved on your operating system disk in a file. Anything that provides data; origin of data.}
-\nomenclature{\textbf{Splice}}{to unite edits by lapping the two ends together or by inserting an edit between two edits or in the middle of an edit.}
+\nomenclature{\color{CinBlueText}{Splice}}{to unite edits by lapping the two ends together or by inserting an edit between two edits or in the middle of an edit.}
-\nomenclature{\textbf{Split}}{to divide or break up an edit into two parts.}
+\nomenclature{\color{CinBlueText}{Split}}{to divide or break up an edit into two parts.}
-\nomenclature{\textbf{Stream}}{a source of data that is usually accessed only sequentially, as in audio or video.}
+\nomenclature{\color{CinBlueText}{Stream}}{a source of data that is usually accessed only sequentially, as in audio or video.}
-\nomenclature{\textbf{Streaming}}{a method of receiving audio or video media while they are still being delivered, so that it is possible to watch video or listen to audio without waiting for an entire file to download. Streaming can be live or on-demand.}
+\nomenclature{\color{CinBlueText}{Streaming}}{a method of receiving audio or video media while they are still being delivered, so that it is possible to watch video or listen to audio without waiting for an entire file to download. Streaming can be live or on-demand.}
-\nomenclature{\textbf{Subtitle}}{the text of a video displayed on the bottom of the screen, often used for language translations. Subtitles are also the graphics displayed on top of video content, stored in a separate stream such as done for DVD menus.}
+\nomenclature{\color{CinBlueText}{Subtitle}}{the text of a video displayed on the bottom of the screen, often used for language translations. Subtitles are also the graphics displayed on top of video content, stored in a separate stream such as done for DVD menus.}
-\nomenclature{\textbf{TOC}}{acronym for Table of Contents; this is one of several kinds of an index file used to accelerate media access. It may contain compressed audio waveform data to accelerate timeline update.}
+\nomenclature{\color{CinBlueText}{TOC}}{acronym for Table of Contents; this is one of several kinds of an index file used to accelerate media access. It may contain compressed audio waveform data to accelerate timeline update.}
-\nomenclature{\textbf{Telecine}}{a method of sampling media for both color and sample rate in order to prepare for presentation on a broadcast signal. In the United States video is broadcast at 29.97 frames per second but film uses 24 frames per second. For the film's motion to be accurately rendered on the video signal, a telecine must use a technique called the 2:3 pulldown, to convert from film’s 24 frames per second to 29.97 frames per second.}
+\nomenclature{\color{CinBlueText}{Telecine}}{a method of sampling media for both color and sample rate in order to prepare for presentation on a broadcast signal. In the United States video is broadcast at 29.97 frames per second but film uses 24 frames per second. For the film's motion to be accurately rendered on the video signal, a telecine must use a technique called the 2:3 pulldown, to convert from film’s 24 frames per second to 29.97 frames per second.}
-\nomenclature{\textbf{Thread}}{a single stream of program instruction fragments that may or may not be executed in parallel.}
+\nomenclature{\color{CinBlueText}{Thread}}{a single stream of program instruction fragments that may or may not be executed in parallel.}
-\nomenclature{\textbf{Two screen editing}}{this refers to an editing method where you mark a portion of your source material with In and Out points and insert or overlay at a specific and marked point in your timeline, called the insertion point.}
+\nomenclature{\color{CinBlueText}{Two screen editing}}{this refers to an editing method where you mark a portion of your source material with In and Out points and insert or overlay at a specific and marked point in your timeline, called the insertion point.}
-\nomenclature{\textbf{Thumbnails}}{miniature images of the video. In the Resources Window they represent the first frame of the asset. When drawn on the timeline they imitate a physical film. See picons.}
+\nomenclature{\color{CinBlueText}{Thumbnails}}{miniature images of the video. In the Resources Window they represent the first frame of the asset. When drawn on the timeline they imitate a physical film. See picons.}
-\nomenclature{\textbf{Timebar}}{the part of the timeline that marks the time passing in selectable time units.}
+\nomenclature{\color{CinBlueText}{Timebar}}{the part of the timeline that marks the time passing in selectable time units.}
-\nomenclature{\textbf{Timeline}}{the part of the program window that contains video and audio tracks and displays the edits as they occur in time.}
+\nomenclature{\color{CinBlueText}{Timeline}}{the part of the program window that contains video and audio tracks and displays the edits as they occur in time.}
-\nomenclature{\textbf{Title}}{identifier applied to a data object; it is used to refer to the bar in the upper part of an asset that contains the name of the source file. It can be shown/hidden using the View menu. In the XML project file, TITLE is the name of the track, for example "Video 1".}
+\nomenclature{\color{CinBlueText}{Title}}{identifier applied to a data object; it is used to refer to the bar in the upper part of an asset that contains the name of the source file. It can be shown/hidden using the View menu. In the XML project file, TITLE is the name of the track, for example "Video 1".}
-\nomenclature{\textbf{Title bar}}{presentation of a title for a given data object.}
+\nomenclature{\color{CinBlueText}{Title bar}}{presentation of a title for a given data object.}
-\nomenclature{\textbf{Toggle}}{a program switch.}
+\nomenclature{\color{CinBlueText}{Toggle}}{a program switch.}
-\nomenclature{\textbf{Transitions}}{rendered output.}
+\nomenclature{\color{CinBlueText}{Transitions}}{rendered output.}
-\nomenclature{\textbf{Trimming}}{edit boundaries to lengthen or to shorten the duration of the edit in the timeline. Over the edit boundary and during the trimming operation the mouse pointer changes shape.}
+\nomenclature{\color{CinBlueText}{Trimming}}{edit boundaries to lengthen or to shorten the duration of the edit in the timeline. Over the edit boundary and during the trimming operation the mouse pointer changes shape.}
-\nomenclature{\textbf{Tumblers}}{a diamond shaped button composed of two arrows - one arrow upward and one arrow downward. It is used to set values in text boxes using the mouse either by clicking on the up/down arrow or using the wheel with the pointer over the tumbler.}
+\nomenclature{\color{CinBlueText}{Tumblers}}{a diamond shaped button composed of two arrows - one arrow upward and one arrow downward. It is used to set values in text boxes using the mouse either by clicking on the up/down arrow or using the wheel with the pointer over the tumbler.}
-\nomenclature{\textbf{Tweaking}}{to make minor adjustments to. Also, a general term from when automatic generation keyframes are armed.}
+\nomenclature{\color{CinBlueText}{Tweaking}}{to make minor adjustments to. Also, a general term from when automatic generation keyframes are armed.}
-\nomenclature{\textbf{Underrun}}{a state occurring when a buffer used to communicate between two devices or processes is fed with data at a lower speed than the data is being read from it. This requires the program or device reading from the buffer to pause its processing while the buffer refills.}
+\nomenclature{\color{CinBlueText}{Underrun}}{a state occurring when a buffer used to communicate between two devices or processes is fed with data at a lower speed than the data is being read from it. This requires the program or device reading from the buffer to pause its processing while the buffer refills.}
-\nomenclature{\textbf{Value}}{the measure of the brightness of a color. In video signals it is represented by luma.}
+\nomenclature{\color{CinBlueText}{Value}}{the measure of the brightness of a color. In video signals it is represented by luma.}
-\nomenclature{\textbf{Vicons}}{stands for Video Icons, which are animated thumbnail presentations of video media.}
+\nomenclature{\color{CinBlueText}{Vicons}}{stands for Video Icons, which are animated thumbnail presentations of video media.}
-\nomenclature{\textbf{Waveform}}{the visual image of the form of the audio signal.}
+\nomenclature{\color{CinBlueText}{Waveform}}{the visual image of the form of the audio signal.}
-\nomenclature{\textbf{Widget}}{a unitary graphical object that performs a specific set. It is usually a single subwindow.}
+\nomenclature{\color{CinBlueText}{Widget}}{a unitary graphical object that performs a specific set. It is usually a single subwindow.}
-\nomenclature{\textbf{XML}}{the language \CGG{} EDLs are written in. Extensible Markup Language (XML) is a general-purpose language that combines text and extra information about the text and allows users to make modifications. It creates a text representation of a data object that is designed to be relatively human-legible.}
+\nomenclature{\color{CinBlueText}{XML}}{the language \CGG{} EDLs are written in. Extensible Markup Language (XML) is a general-purpose language that combines text and extra information about the text and allows users to make modifications. It creates a text representation of a data object that is designed to be relatively human-legible.}
-\nomenclature{\textbf{YUV}}{is a color model which splits luma from chroma, similarly to human sight.. Colors are stored as absolute luma representation and the difference signal between luma and chroma complement components. This color model is used by PAL and NTSC standards. Y stands for the luma component and U and V are the chroma components. U and V are actually color difference components (respectively R-Y and B-Y). In fact YUV signals are created from an original RGB source. The weighted values of R, G, and B are added together to produce a single Y signal, representing the overall luma. The U signal is then created by subtracting the Y from the blue signal of the original RGB, and then scaling; V is created by subtracting the Y from the red, and then scaling by a different factor. Previous black-and-white systems used only luma (Y) information and color information (U and V) was added so that a black-and-white receiver would still be able to display a color picture as a normal black and white picture.}
+\nomenclature{\color{CinBlueText}{YUV}}{is a color model which splits luma from chroma, similarly to human sight.. Colors are stored as absolute luma representation and the difference signal between luma and chroma complement components. This color model is used by PAL and NTSC standards. Y stands for the luma component and U and V are the chroma components. U and V are actually color difference components (respectively R-Y and B-Y). In fact YUV signals are created from an original RGB source. The weighted values of R, G, and B are added together to produce a single Y signal, representing the overall luma. The U signal is then created by subtracting the Y from the blue signal of the original RGB, and then scaling; V is created by subtracting the Y from the red, and then scaling by a different factor. Previous black-and-white systems used only luma (Y) information and color information (U and V) was added so that a black-and-white receiver would still be able to display a color picture as a normal black and white picture.}
-\nomenclature{\textbf{8 / 10-bit images}}{images that were sampled at 8 or 10 bits per channel. The tone range for each channel is from 0 to 255 for 8-bit and from 0 to 1023 for 10-bit.}
+\nomenclature{\color{CinBlueText}{8 / 10-bit images}}{images that were quantizated at 8 or 10 bits per channel. The tone range for each channel is from 0 to 255 for 8-bit and from 0 to 1023 for 10-bit.}
-\nomenclature{\textbf{Algorithm}}{set of instructions, typically to solve a class of problems or perform a computation.}
+\nomenclature{\color{CinBlueText}{Algorithm}}{set of instructions, typically to solve a class of problems or perform a computation.}
-\nomenclature{\textbf{Aliasing}}{incorrect sampling of a video or audio signal that leads to unwanted artifacts because it cannot distinguish values too close. There is Temporal Aliasing (audio) and Spatial Aliasing (video).}
+\nomenclature{\color{CinBlueText}{Aliasing}}{incorrect sampling of a video or audio signal that leads to unwanted artifacts because it cannot distinguish values too close. There is Temporal Aliasing (audio) and Spatial Aliasing (video).}
-\nomenclature{\textbf{B-spline}}{(basis spline) polynomial curves characterized by nodes and control points to obtain smooth curves.}
+\nomenclature{\color{CinBlueText}{B-spline}}{(basis spline) polynomial curves characterized by nodes and control points to obtain smooth curves.}
-\nomenclature{\textbf{Banding}}{Incorrect display of a color gradient, due to a narrow tonal range, which leads to the appearance of color bands instead of fading tones.}
+\nomenclature{\color{CinBlueText}{Banding}}{Incorrect display of a color gradient, due to a narrow tonal range, which leads to the appearance of color bands instead of fading tones.}
-\nomenclature{\textbf{Bayer array}}{is a color filter array upon a sensor to get an RGB image. The filter pattern is 50\% green, 25\% red and 25\% blue.}
+\nomenclature{\color{CinBlueText}{Bayer array}}{is a color filter array upon a sensor to get an RGB image. The filter pattern is 50\% green, 25\% red and 25\% blue.}
-\nomenclature{\textbf{Bicubic filter}}{is a mathematical interpolation to resample an image. It produces a smoother result than the nearest-neighbor or the bilinear filter.}
+\nomenclature{\color{CinBlueText}{Bicubic filter}}{is a mathematical interpolation to resample an image. It produces a smoother result than the nearest-neighbor or the bilinear filter.}
-\nomenclature{\textbf{Bilinear filter}}{is a mathematical interpolation to resample an image. It produces a smoother result than the nearest-neighbor.}
+\nomenclature{\color{CinBlueText}{Bilinear filter}}{is a mathematical interpolation to resample an image. It produces a smoother result than the nearest-neighbor.}
-\nomenclature{\textbf{Bit depth}}{Quantization of an audio or video signal. Color depth is the number of bits used for each color component of a single pixel. Audio bit depth is the number of bits of information in each sample.}
+\nomenclature{\color{CinBlueText}{Bit depth}}{Quantization of an audio or video signal. Color depth is the number of bits used for each color component of a single pixel. Audio bit depth is the number of bits of information in each sample.}
-\nomenclature{\textbf{Black point}}{the part of the image with the darkest value that can be displayed on a device. At the limit is 0 (pure black).}
+\nomenclature{\color{CinBlueText}{Black point}}{the part of the image with the darkest value that can be displayed on a device. At the limit is 0 (pure black).}
-\nomenclature{\textbf{Color space}}{organization of the colors of a color model, limited to the gamut of a particular device. Examples are sRGB and rec 709.}
+\nomenclature{\color{CinBlueText}{Color space}}{organization of the colors of a color model, limited to the gamut of a particular device. Examples are sRGB and rec 709.}
-\nomenclature{\textbf{Color timing}}{the process of adjusting color balance making it consistent in every scene. We also talk about color matching scene to scene or shot matching.}
+\nomenclature{\color{CinBlueText}{Color timing}}{the process of adjusting color balance making it consistent in every scene. We also talk about color matching scene to scene or shot matching.}
-\nomenclature{\textbf{Composite}}{the combination of two or more video layers to obtain a single composition.}
+\nomenclature{\color{CinBlueText}{Composite}}{the combination of two or more video layers to obtain a single composition.}
-\nomenclature{\textbf{Contrast}}{is the difference in luminance of parts or elements of an image that makes them distinguishable. The greater the difference, the greater the contrast. It is the horizontal range shown by the histogram or the vertical range shown by the waveform.}
+\nomenclature{\color{CinBlueText}{Contrast}}{is the difference in luminance of parts or elements of an image that makes them distinguishable. The greater the difference, the greater the contrast. It is the horizontal range shown by the histogram or the vertical range shown by the waveform.}
-\nomenclature{\textbf{Denoise}}{is the process of removing digital noise from a video. The three main types are based on statistical methods, transform wavelets and temporal averaging.}
+\nomenclature{\color{CinBlueText}{Denoise}}{is the process of removing digital noise from a video. The three main types are based on statistical methods, transform wavelets and temporal averaging.}
-\nomenclature{\textbf{DeSpill}}{process to remove background color contamination from the edges of the subject in foreground, during a chroma key.}
+\nomenclature{\color{CinBlueText}{DeSpill}}{process to remove background color contamination from the edges of the subject in foreground, during a chroma key.}
-\nomenclature{\textbf{Digital Intermediate (DI)}}{Over time it has taken on different meanings. For \CGG{} is meant as the creation of a high quality file that during the various stages of editing and color correction keeps as much information as possible. Being little or uncompressed its manipulation is also faster and more efficient.}
+\nomenclature{\color{CinBlueText}{Dynamic range}}{is the ratio between the largest and smallest values (luminance) that an image can assume. The larger the size, the better we can distinguish details in the dark and light parts.}
-\nomenclature{\textbf{Dynamic range}}{is the ratio between the largest and smallest values (luminance) that an image can assume. The larger the size, the better we can distinguish details in the dark and light parts.}
+\nomenclature{\color{CinBlueText}{Exposure}}{the exposure is the amount of light per unit area reaching an image sensor, as determined by shutter speed, lens aperture and scene luminance.}
-\nomenclature{\textbf{Exposure}}{the exposure is the amount of light per unit area reaching an image sensor, as determined by shutter speed, lens aperture and scene luminance.}
+\nomenclature{\color{CinBlueText}{Floating point}}{real numbers with decimals. They allow for greater precision in calculations than integers, but they require more processing power.}
-\nomenclature{\textbf{Floating point}}{real numbers with decimals. They allow for greater precision in calculations than integers, but they require more processing power.}
+\nomenclature{\color{CinBlueText}{Gamut}}{In color reproduction, the gamut is a certain complete subset of colors. The larger the gamut of a device (associated with a color space) the more colors can be displayed.}
-\nomenclature{\textbf{Gamut}}{In color reproduction, the gamut is a certain complete subset of colors. The larger the gamut of a device (associated with a color space) the more colors can be displayed.}
+\nomenclature{\color{CinBlueText}{HDTV}}{(high definition TV) standard characterized by a 16:9 aspect ratio, various frames rates and scan modes and with a resolution of at least 1080.}
-\nomenclature{\textbf{HDTV}}{(high definition TV) standard characterized by a 16:9 aspect ratio, various frames rates and scan modes and with a resolution of at least 1080.}
+\nomenclature{\color{CinBlueText}{Intermediate}}{The production process of a movie in which you switch from film to a digital intermediate for the various stages of processing and then return to the film. (ADA = Analog, Digital, Analog). The most used formats are Cineon/DPX and OpenEXR. We also talk about DI= Digital Intermediate. Nowadays it is often used as a synonym for Mezzanine codec (see).}
-\nomenclature{\textbf{Lanczos}}{algorithm for high quality resampling video signal. It is also used in case of upsampling, weak point of other similar filters.}
+\nomenclature{\color{CinBlueText}{Lanczos}}{algorithm for high quality resampling video signal. It is also used in case of upsampling, weak point of other similar filters.}
-\nomenclature{\textbf{Letterbox}}{blacks bars on the top and bottom side of the frame. They are due to a smaller frame size than the one set in the project (see also Pillarbox).}
+\nomenclature{\color{CinBlueText}{Letterbox}}{blacks bars on the top and bottom side of the frame. They are due to a smaller frame size than the one set in the project (see also Pillarbox).}
-\nomenclature{\textbf{LUT, 3D LUT}}{(LookUp Table) used to map one color space to another. \CGG{} uses them through ffmpeg filters. There are downloadable collections or there are specific ones provided by hardware manufacturers.}
+\nomenclature{\color{CinBlueText}{LUT, 3D LUT}}{(LookUp Table) used to map one color space to another. \CGG{} uses them through ffmpeg filters. There are downloadable collections or there are specific ones provided by hardware manufacturers.}
-\nomenclature{\textbf{Nearest neighbor}}{is the simplest method of resampling an image. It is fast and resources saving, but produces less smooth results.}
+\nomenclature{\color{CinBlueText}{Mezzanine codec}}{Transcode digital footage files into a high quality codec that is more efficient on the timeline and retains all initial information (is a DDD process, i.e. Digital, Digital, Digital). Generally such codecs are little or nothing compressed; if compressed they are lossless and intraframe and the chrominance is not less than 4:2:2. Very used codecs are DNxHD; ProRes; ffv1; HuffYUV; etc.}
-\nomenclature{\textbf{Panning}}{in video technology, panning refers to the horizontal scrolling of an image wider than the display. In \CGG{} it is done (together with other camera movements) with the camera tool.}
+\nomenclature{\color{CinBlueText}{Nearest neighbor}}{is the simplest method of resampling an image. It is fast and resources saving, but produces less smooth results.}
-\nomenclature{\textbf{Pillarbox}}{blacks bars on the left and right side of the frame. They are due to a smaller frame size than the one set in the project (see also Letterbox).}
+\nomenclature{\color{CinBlueText}{Panning}}{in video technology, panning refers to the horizontal scrolling of an image wider than the display. In \CGG{} it is done (together with other camera movements) with the camera tool.}
-\nomenclature{\textbf{Rec 709}}{(BT.709 or ITU 709) is the standard color space of high-definition television, having 16:9 aspect ratio, scan modes and frame rate of HDTV. It can decode at 8 or 10 bits per channel. The gamut is the same as for sRGB from which it differs for the 2.4 gamma.}
+\nomenclature{\color{CinBlueText}{Pillarbox}}{blacks bars on the left and right side of the frame. They are due to a smaller frame size than the one set in the project (see also Letterbox).}
-\nomenclature{\textbf{Retiming}}{is the change of the speed of a edit by interpolating the original frames to a new in between frame.}
+\nomenclature{\color{CinBlueText}{Rec 709}}{(BT.709 or ITU 709) is the standard color space of high-definition television, having 16:9 aspect ratio, scan modes and frame rate of HDTV. It can decode at 8 or 10 bits per channel. The gamut is the same as for sRGB from which it differs for the 2.4 gamma.}
-\nomenclature{\textbf{sRGB}}{is an RGB color space used on monitors, printers, and the Internet. It can decode at 8 or 10 bits per channel. The gamut is the same as for Rec 709 from which it differs for the 2.2 gamma.}
+\nomenclature{\color{CinBlueText}{Retiming}}{is the change of the speed of a edit by interpolating the original frames to a new in between frame.}
-\nomenclature{\textbf{Subsampling}}{is the practice of encoding Y’CbCr images by implementing less resolution for chroma information than for luma information. Depending on the amount of information deleted we have: 4:4:4 (lossless); 4:2:2 (HDTV); 4:2:0 (DVD, smartphone) or 4:1:1.}
+\nomenclature{\color{CinBlueText}{sRGB}}{is an RGB color space used on monitors, printers, and the Internet. It can decode at 8 or 10 bits per channel. The gamut is the same as for Rec 709 from which it differs for the 2.2 gamma.}
-\nomenclature{\textbf{Timecode}}{is a sequence of numeric codes generated at regular intervals by a timing synchronization system and recorded into audio and/or video tracks. It is used for synchronization audio and video clips.}
+\nomenclature{\color{CinBlueText}{Subsampling}}{is the practice of encoding Y’CbCr images by implementing less resolution for chroma information than for luma information. Depending on the amount of information deleted we have: 4:4:4 (lossless); 4:2:2 (HDTV); 4:2:0 (DVD, smartphone) or 4:1:1.}
-\nomenclature{\textbf{White point}}{is the clearest part of an image that can be displayed on a device; at the limit is 1.0 value (pure white).}
+\nomenclature{\color{CinBlueText}{Timecode}}{is a sequence of numeric codes generated at regular intervals by a timing synchronization system and recorded into audio and/or video tracks. It is used for synchronization audio and video clips.}
-\nomenclature{\textbf{YCbCr}}{is a color space based on the YUV color model, widely used in broadcast productions. It separates the luma part (Y) from the chroma part (Cb and Cr).}
+\nomenclature{\color{CinBlueText}{White point}}{is the clearest part of an image that can be displayed on a device; at the limit is 1.0 value (pure white).}
+
+\nomenclature{\color{CinBlueText}{YCbCr}}{is a color space based on the YUV color model, widely used in broadcast productions. It separates the luma part (Y) from the chroma part (Cb and Cr).}
\chapter{Installation}
\label{cha:Installation}
+\index{installation}
+
+\section{\CGG{} AppImage}%
+\label{sec:cin_gg_appimage}
+\index{appimage}
+
+The main way to install \CGG{} is to use the AppImage. This is updated regularly and works for every distro, since it already contains the necessary dependencies.
+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. 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:
+
+\url{https://cinelerra-gg.org/download/images/}
+
+Some example file names are as follows - where 8 digits represent yyyymmdd:
+
+\begin{lstlisting}[style=sh]
+ CinGG-20230131-x86_64.AppImage
+ (currently based on Fedora 32, linux kernel 5.8.15, libc version 2.31)
+ CinGG-20230131-x86_64-older-distros.AppImage
+ (currently based on Ubuntu 16.04, libc version 2.23)
+ CinGG-20230131-i686.AppImage
+ (currently based on Debian 9, linux kernel 4.9, use "newer" for Debian 11.0)
+ CinGG-20230131-i686-newer-distros.AppImage
+ (currently based on Debian 11, linux kernel 5.10)
+ CinGG-20230131-x86_64-multibit.AppImage
+ (currently based on Fedora 32, libc version 2.31)
+ 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:
+
+\begin{lstlisting}[style=sh]
+ $ chmod u+x CinGG-yyyymmdd.AppImage
+\end{lstlisting}
+
+Finally start the program from a window in the directory where the image is stored:
+
+\begin{lstlisting}[style=sh]
+ $ ./CinGG-yyyymmdd.AppImpage
+\end{lstlisting}
+
+or create a convenient desktop icon with a link to the run action, or do a \textit{Desktop Integration} manually or with external programs. There is a
+description of a GUI methodology for doing so in this file on the webiste:
+
+\url{https://cinelerra-gg.org/download/images/README\_appimage.txt}
+
+Most distros already have the libraries to run the appimage, but if not you may need an additional installation. For example Arch Linux needs the \texttt{libappimage} package.
+
+\begin{lstlisting}[style=sh]
+ sudo pacman -S libappimage
+\end{lstlisting}
+
+And Leap 15.3 (OpenSUSE) requires installation of the \textit{appimage} package.
+
+\begin{lstlisting}[style=sh]
+ sudo zypper se -is appimage
+\end{lstlisting}
+
+In addition, if you are using the OpenGL video driver, you will need to install the appropriate OpenGL
+drivers for your Operating System graphics board because libGLU.so and other OpenGL libraries are
+not included in 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}
\label{fig:download-distros}
\end{figure}
+All of these images are dated 10/31/2020 and are no longer being maintained. They
+will still work on the version of the O/S in use at that time but will have none of
+the latest features. You should use the simpler AppImage instead as described previously.
+
If you prefer to not have to take the time to build \CGG{} Infinity
yourself, there are pre-built dynamic or static binaries for various
versions of Ubuntu, Mint, Suse, Fedora, Debian, Centos, Arch, and
~\ref{sec:How_to_build}.
%
A Windows 10 version installation is described in~\ref{sec:ms_windows10}. There are also 32-bit i686 Ubuntu, Debian,
-and Slackware versions available. These are updated on a fairly
-regular basis as long as significant code changes have been made.
+and Slackware versions available\protect\footnote{Remember that a 32-bit distro does not address more than 4GB of memory, so you may have stability and performance problems with large, high-resolution mediafiles.}. \textbf{These binaries are no longer being updated; they are stable and working but without future functionality}.
They are in subdirectories of:
\begin{list}{}{}
\item \href{https://cinelerra-gg.org/download/pkgs}{https://cinelerra-gg.org/download/pkgs}
\end{list}
-The \textbf{tars} directory contains single-user static builds for
+The \textbf{tars} \index{tars} directory contains single-user static builds for
different distros.
%
This is the recommended usage of \CGG{} because all of the files
use h265 rendering to 10-bit instead of the more standard 8-bit.} For more
information see ~\ref{sec:cinx_and_a_bit_of_confusion}.
-The \textbf{pkgs} directory contains the standard packaged
+The \textbf{pkgs} \index{pkgs} directory contains the standard packaged
application for various distros. This will install a dynamic
system version for users who prefer to have the binaries in the
system area and for multi-user systems.
\section{How to Build \CGG{} from Developer's Git Repository}%
\label{sec:How_to_build}
+\index{build}
+\index{git}
These are generic build instructions for building \CGG{} Infinity.
Known to work on Ubuntu, Mint, OpenSuse, Fedora, Debian, Centos,
-Arch, Slackware, and Gentoo. It has not been tested on every
+Arch, Slackware, and Gentoo. Compiling from git is perhaps the best way to get \CGG{} on 32-bit systems\protect\footnote{Remember that a 32-bit distro does not address more than 4GB of memory, so you may have stability and performance problems with large, high-resolution mediafiles.}. It has not been tested on every
single possible distro yet so you might expect to have to make
some minor changes. Also works on a somewhat limited basis on
FreeBSD and Windows 10 with the bsd.patch for FreeBSD and the
-cygwin.patch for Windows 10.
+cygwin.patch for Windows 10. As of 10/31/2020, FreeBSD and Windows
+10 builds and patches are no longer being maintained so that they
+will work using the GIT version in use at that time but you will
+have to create new patches for arising problems on later GITs.
+
+NOTE: as of May 31, 2021 when Context Help was added, to include
+this Context Help you will need to download the corresponding
+tgz file containing the HTML manual sections referenced for the
+Help pages. The file to download is:
+\url{https://cinelerra-gg.org/download/images/HTML_Manual-20220131.tgz}
+substituting for "20220131" the "yyyymmdd" representing latest release date.
+Then unpack to your Cinelerra/bin/doc directory so it is included in
+your built system.
+NOTE End
Alternatively, there are some pre-built dynamic or static binaries
which are updated on a fairly regular basis (as long as code changes
\subsection{The system build}
\label{sec:system-build}
+\index{git}
-To do a system build, you should read the file
+To do a system build \index{build} , you should read the file
\texttt{README} that is at the top level after you get the source.
\begin{itemize}
\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.
+ # 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} does not work for Arch Linux or Gentoo,
- so we have to install the dependencies
- manually. \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}
+\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.
\subsection{The single-user build}
\label{sec:single-user-build}
+\index{single-user build}
+\index{git}
To do a single-user build, read the file \texttt{README} that is at
the top level after you get the source.
\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}
These procedures and the \CGG{} Infinity software have all been run
as \textbf{root} on various home laptops and desktops. This provides
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]
./configure --help
\end{lstlisting}
-The default build is a system build which uses:
+The default build \index{build} is a system build which uses:
\begin{lstlisting}[style=sh]
./configure --without-single-user
\end{lstlisting}
-In the single-user build, the target directory is always
+In the single-user build \index{single-user build}, the target directory is always
\texttt{cin}. Because this is also the developer build, constant
names are used throughout. However, you can rename files after the
install is complete.
export FFMPEG_EXTRA_CFG=" --disable-vdpau"
\end{lstlisting}
+Note for building 32-bit packages on hybrid 32/64 x86 systems, you may
+need to add the following:
+
+\begin{lstlisting}[style=sh]
+setarch i686 (befire configure and package build)
+\end{lstlisting}
+
+NOTE: as of May 31, 2021 when Context Help was added, to include
+this Context Help you will need to download the corresponding
+tgz file containing the HTML manual sections referenced for the
+Help pages. The file to download is:
+\url{https://cinelerra-gg.org/download/images/HTML_Manual-20220131.tgz}
+substituting for "20220131" the "yyyymmdd" representing latest release date.
+Then unpack to your Cinelerra/bin/doc directory so it is included in
+your built system. The reason for not including the HTML manual in
+the source code so that it would already be there, is because it is
+very large and has its own GIT base.
\subsection{Notes about Building from Git in your Customized Environment}%
\label{sub:notes_about_building_from_git_in_your_customized_environment}
+\index{build}
+\index{./configure}
+\index{git}
Getting a build to work in a custom environment is not easy. If you
have already installed libraries which are normally in the
thirdparty build, getting them to be recognized means you have to
install the \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?
-\begin{table}[htpb]
- \centering
- \caption{List of thirdparty builds}
- \label{tab:List_of_thirdparty_builds}
- \small
- \begin{tabular}{m{8em}c}
- \toprule
- a52dec & yes\\
- djbfft & yes\\
- ffmpeg & yes\\
- fftw & auto\\
- flac & auto\\
- giflib & yes\\
- ilmbase & auto\\
- lame & auto\\
- libavc1394&auto\\
- libraw1394&auto\\
- libiec61883&auto\\
- libdv &auto\\
- libjpeg &auto\\
- opus &auto\\
- openjpeg &auto\\
- libogg &auto\\
- libsndfile&auto\\
- libtheora&auto\\
- libuuid & yes\\
- libvorbis&auto\\
- mjpegtools&yes\\
- openexr &auto\\
- tiff &auto\\
- twolame &auto\\
- x264 &auto\\
- x265 &auto\\
- libvpx &auto\\
- lv2 &auto\\
- sratom &auto\\
- serd &auto\\
- sord &auto\\
- lilv &auto\\
- suil &auto\\
- libaom &auto\\
- dav1d &auto\\
- libwebp &auto\\
- ffnvcodec &auto\\
- \bottomrule
- \end{tabular}
-\end{table}
-
+\begin{center}
+ \small
+ \begin{longtable}{m{8em} c}
+ \caption{List of thirdparty builds}
+ \label{tab:List_of_thirdparty_builds}\\
+ \toprule
+ a52dec & yes\\
+ djbfft & yes\\
+ ffmpeg & yes\\
+ fftw & auto\\
+ flac & auto\\
+ giflib & yes\\
+ ilmbase & auto\\
+ lame & auto\\
+ libavc1394&auto\\
+ libraw1394&auto\\
+ libiec61883&auto\\
+ libdv &auto\\
+ libjpeg &auto\\
+ opus &auto\\
+ openjpeg &auto\\
+ libogg &auto\\
+ libsndfile&auto\\
+ libtheora&auto\\
+ libuuid & yes\\
+ libvorbis&auto\\
+ mjpegtools&yes\\
+ openexr &auto\\
+ tiff &auto\\
+ twolame &auto\\
+ x264 &auto\\
+ x265 &auto\\
+ libvpx &auto\\
+ lv2 &auto\\
+ sratom &auto\\
+ serd &auto\\
+ sord &auto\\
+ lilv &auto\\
+ suil &auto\\
+ libaom &auto\\
+ dav1d &auto\\
+ libwebp &auto\\
+ ffnvcodec &auto\\
+ \bottomrule
+ \end{longtable}
+\end{center}
The \textit{yes} means force build and \textit{auto} means probe and
use the system version if the build operation is not static. To get
\subsection{Cloning the Repository for Faster Updates}%
\label{sub:cloning_the_repository_for_faster_updates}
+\index{repository}
+\index{git}
If you want to avoid downloading the software every time an update
is available you need to create a local ``repository'' or repo. The
\subsection{How to Build from a Previous GIT Version}%
\label{sub:how_to_build_from_a_previous_git_version}
+\index{build}
+\index{repository}
+\index{git}
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]
\subsection{Debuggable Single User Build}%
\label{sub:debuggable_single_user_build}
+\index{single-user build}
+\index{git}
To build from source with full debugging symbols, first build a full
static (non\_debug) build as follows but instead of using
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}
+\index{build}
+\index{repository}
+\index{git}
There are some generic build scripts included in the \CGG{} GIT
repository for users who want to do unbundled builds with ffmpeg
-formats} and \texttt{ffmpeg -codecs} to see what is available
on your system.
+\section{Building the HTML Manual for Context Help}%
+\label{sec:building_the_manual}
+\index{context help}
+
+In addition to compiling your own \CGG{}, you should also build an html version of the manual that is needed for Context Help in the program. The main version of the manual is in latex to produce a pdf version of the manual and this is required to be built first as the basis for the html version. This means that you need a full latex environment, git, and the latex2html program in order to eventually create the html version. Texlive is about 1 GB; Latex2html itself has many requirements and missing any will result in failure: some requirments include Netpbm, GhostScript, dvips, etc. Latex2html must be at least version \textit{2021.2} in order to create the html manual version from the latex.
+
+The steps are as follows:
+\begin{enumerate}
+ \item Download the manual in LaTeX:
+
+\begin{lstlisting}[style=sh]
+git clone "git://git.cinelerra-gg.org/goodguy/cin-manual-latex.git" master
+\end{lstlisting}
+
+ \item Included in the download is the \texttt{translate\_manual} script. After modifying this file to have execute permission, run this script from a terminal window in the \textit{master} directory where it was downloaded (be aware that this script includes several \textit{rm} commands):
+\begin{lstlisting}[style=sh]
+./translate_manual
+\end{lstlisting}
+
+ The steps that this script performs are as follows:
+ \begin{itemize}
+ \item PDF production. The PDF document will be produced from the latex source in the \textit{master} directory. Since the glossary and index are also present, it has to run the pdf build several times. The following commands in the \texttt{translate\_manual} script produce the PDF document from latex source which includes invoking makeindex for the Index and Glossary.
+
+ \begin{lstlisting}[style=sh]
+ pdflatex CinelerraGG_Manual.tex
+ makeindex CinelerraGG_Manual.idx
+ pdflatex CinelerraGG_Manual.tex
+ makeindex CinelerraGG_Manual.nlo -s nomencl.ist -o CinelerraGG_Manual.nls
+ pdflatex CinelerraGG_Manual.tex
+ \end{lstlisting}
+
+ After these commands are executed you will have the manual only in PDF format. So if you only want a PDF version, you only need to run these previous 5 lines but Context Help from the program will not be available with the PDF version.
+ \item Next, to produce HTML output the script then moves (renames) \texttt{latex 2html-init} to \texttt{.latex2html-init} (starting with dot).
+
+ \item Then the script uses latex2html: latex2html is run with a unique set of parameters and some cleanup is performed. It creates the directory CinelerraGG\_Manual containing all the files of the manual in html: tables, references, index, glossary, and various images.
+ \end{itemize}
+
+ \item After installation of the \CGG{} program, place the complete unchanged directory \texttt{CinelerraGG\_Manual}, as it was produced by latex2html from the manual package, into the \textit{doc} directory of the installed Cinelerra package. This will be the directory \textit{bin/doc/CinelerraGG\_Manual} if \CGG{} was built \texttt{--with-single-user}. The script ContextManual.pl will automatically be in bin/doc after the successful build of the program. It is this perl script that allows the program to access CinelerraGG\_Manual to offer Context Help.
+
+ \item Optionally you can make some adjustments to the latex2html command line in the \texttt{translate\_manual} script. Some variants are shown in the comments inside the script but changes may impact the usability of Alt/h hotkey from the program.
+\end{enumerate}
+
\section{Windows 10 with Cygwin for \CGG{} Limited}%
\label{sec:ms_windows10}
+\index{windows 10}
+
+As of 10/31/2020, this is no longer being maintained. It should
+still work using an older GIT version with Windows 10 but it is
+possible with some effort to modify the patch file to work with the
+latest updated GIT.
To run \CGG{} on a Windows 10 computer, you will need to have
Cygwin installed on your system, along with the \CGG{} static tar
-and a patched library: libxbc. This setup has been tested with
+and a patched library: libxcb. This setup has been tested with
Windows 10, version 1909, on an HP EliteBook 820 at 2.3 GHz.
This limited version provides \textit{core} functionality at this
\subsection*{Installing Cygwin}
\label{sec:installing_cygwin}
+\index{cygwin}
Cygwin is an environment that runs natively on Windows which
allows Unix programs to be compiled and run on Windows. With
\item Download the tar file
\href{https://cinelerra-gg.org/download/testing/libxcb-bld.tar.bz2}{libxcb-bld.tar.bz2}.
-\item Install libxbc from the tar file -- installs into
+\item Install libxcb from the tar file -- installs into
\texttt{/usr/local} and requires approximately 21MB storage.
\begin{lstlisting}[style=sh]
tar -C /usr/local -xJf /path/libxcb-bld.tar.bz2
\end{lstlisting}
- The libxcb path repairs an error (XIOError), which stops
+ The libxcb patch repairs an error (XIOError), which stops
Cinelerra.
\item Download the tar file
window) will hang cygwin (and cin) when it hits a breakpoint. You
must run from an external console window to avoid this issue.
+\section{Android Tablet or Phone with TERMUX}%
+\label{sec:android_termux}
+\index{Android}
+
+\CGG{} can be run on Android (without audio), a non-x86 mostly posix system,
+tablet or phone after installing TERMUX, the \textit{terminal emulator}.
+You will have to do your own build using the file in Cinelerra's
+\texttt{blds} subdirectory, \texttt{termux.bld}.
+Because this is a relatively new capability and of lesser use, some
+additional effort may have to be exerted on your part to get it going
+but it is easy to get help by contacting the mailing list.
+In addition, there is currently no known procedure for hearing audio.
-\section{Distribution Systems with \CGG{} Included}%
-\label{sec:distribution_systems_with_cinelerra_included}
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=1.0\linewidth]{android.png}
+ \caption{Screencast of an Android tablet running \CGG{} using TERMUX.}
+ \label{fig:android}
+\end{figure}
+
+Some requirements include;
+\begin{enumerate}
+\item Termux runs with X on Android 7+.
+\item Install takes 5 GB of internal storage. In addition you can download videos,
+and other files with wget to one specific location at sdcard after running termux-setup-storage
+inside termux (it will prompt you to give access to sdcard graphically the first time used).
+\item If you have empty versions of \texttt{locale.alias}, \texttt{locale.dir},
+ and
+\newline \texttt{\$PREFIX/share/X11/locale/en\_US.UTF-8/XLC\_LOCALE}
+\newline you will have to request non-empty versions via the mailing list.
+\item Some helpful information on installing the X environment is at:
+ \url{https://wiki.termux.com/wiki/Graphical\_Environment}
+\item To prevent crashing when loading a video file that has audio, use the guide
+ \url{https://www.reddit.com/r/termux/comments/bpa8jz/pulseaudio\_streaming\_client/}
+ which explains vnc/pulseaudio setup.
+\end{enumerate}
+
+A little more about Audio is presented next because you will need to have this running
+in order to prevent a crash (even though you still will not be able to hear audio) -- there does not seem to be a simple PA client in termux itself.
+Some information is available at:
+ \url{https://android.stackexchange.com/questions/205576/how-to-play-sound-from-termux-when-using-linux} .
+
+The next few lines show a successful setup/usage.
+\begin{lstlisting}[style=sh]
+$ pulseaudio --start
+$ ps axv
+ PID TTY STAT TIME MAJFL TRS DRS RSS %MEM COMMAND
+ 7003 pts/28 S<s 0:00 637 532 9039 1716 0.0 /data/data/com
+13684 ? S<l 0:00 0 49 123898 16616 0.8 pulseaudio --
+13692 pts/28 R<+ 0:00 0 63 7500 1420 0.0 ps axv
+\end{lstlisting}
+\begin{lstlisting}[style=sh]
+$ pactl load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1 auth-anonymous=116
+$ PULSE_SERVER=127.0.0.1 pactl info
+Server String: 127.0.0.1
+Library Protocol Version: 34
+Server Protocol Version: 34
+Is Local: no
+Client Index: 2
+Tile Size: 65496
+User Name: u0_a116
+Host Name: localhost
+Server Name: pulseaudio
+Server Version: 14.2
+Default Sample Specification: s16le 2ch 44100Hz
+Default Channel Map: front-left,front-right
+Default Sink: OpenSL_ES_sink
+Default Source: OpenSL_ES_sink.monitor
+Cookie: c659:c1b7
+\end{lstlisting}
+
+Now to start up \CGG{}, type in:
+\begin{lstlisting}[style=sh]
+ $ cd (your cinelerra directory)/cinelerra/cinelerra-5.1/
+ $ PULSE_SERVER=127.0.0.1 ./cin.sh
+\end{lstlisting}
+
+You can even build a package version similiar to Debian, just with "\texttt{pkg search} pkg\_name / \texttt{pkg install}
+ pkg\_name" instead of "\texttt{apt search/install} pkg\_name" and with "\texttt{*-static}" instead of "\texttt{*-dev/-devel} packages".
+For more information on this, see:
+
+\url{https://wiki.termux.com/wiki/Package\_Management}
+\newline \url{https://wiki.termux.com/wiki/Building\_packages}
+
+\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}
\textbf{AV Linux} is a downloadable/installable shared snapshot
-ISO image based on Debian. It provides the user an easy method to
+ISO image based on MX Linux. It provides the user an easy method to
get an Audio and Video production workstation without the hassle
of trying to find and install all of the usual components
themselves. Of course, it includes \CGG{}!
Click here for the
\href{https://gitlab.com/giuseppetorre/bodhilinuxmedia}{homepage of Bodhi Linux}.
+\subsection{DeLinuxCo}
+\label{sec:delinuxco}
+
+\textbf{DeLinuxCo} is a distro derived from Manjaro (so Arch based) with DE Cinammon. It is a professional workstation, mainly oriented to the multimedia field but not only. It contains many specialized programs already configured, including \CGG{}.
+
+You can read all about DeLinuxCo \href{https://www.delinuxco.com/}{here} and download \href{https://www.delinuxco.com/download/}{here}.
+
\subsection{Elive}
\label{sec:elive}
-\textbf{Elive}, or Enlightenment live CD, is a non-commercial, cost-free operating system based on Debian, for the daily use and it can be used both as live CD or Installed system. Elive uses a customized Enlightenment desktop. It is fast, user-friendly and feature-rich and \CGG{} is included in the 64 bit version.
+\textbf{Elive}, or Enlightenment live CD, is a non-commercial, cost-free operating system based on Debian, and it can be used either as a live CD or an Installed system. Elive uses a customized Enlightenment desktop. It is fast, user-friendly and feature-rich and \CGG{} is included in the both the 64 bit and 32 bit versions.
-Click \href{https://www.elivecd.org/}{Elive} for more information.
+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 “.
\section{Cinx and a “Bit” of Confusion}%
\label{sec:cinx_and_a_bit_of_confusion}
+\index{cinx}
Cinx is the exact same program as Cin. The X (x) represents the
roman numeral 10 for 10-bit as opposed to 8-bit standard. The
results are simply the same as 10-bit with padding to make 12-bit
so it is of no value.
+\section{Multibit build for x265-8/10/12-bit}%
+\label{sec:multibit_build}
+\index{multibit}
+
+To build a version that can handle 8 bit, or 10 bit, or 12 bit videos, a patch is provided in the \texttt{thirdparty} subdirectory that needs to be applied to do so. Be aware that the compile may take more time and seems to be about twice as long. To apply the required patch:
+
+\begin{lstlisting}[style=sh]
+cd /path/to/cinelerra-5.1/thirdparty
+patch < compile_multibit_X265.txt
+mv x265_3.5.patch* src/.
+\end{lstlisting}
+Render formats \textit{h265-10bit} and \textit{h265-12bit} have been provided and will
+be operational after the applied patch is compiled in.
%%% Local Variables:
%%% mode: latex
possible, into this \CGG{} version and has been adding numerous
features, updates, and fixes.
+{\small \textbf{NOTE1:} This manual is a Work in Progress: monthly parts are added to cover the new features introduced in \CGG{}. The texts are continuously revised to make them clearer and more complete. In order to have a better and better product we rely on the suggestions and criticisms of our readers. Do not hesitate to let us know your opinions. For this continuous variability, we recommend that you download the manual at least once a month, during the release of \CGG{}, so that its content is always up to date.
+
+\textbf{NOTE2}: this manual, in the HTML version present on the website, is the base of the \textit{Context Help} that can be called inside the program. For each window, button and plugins we can open the relative web page of the manual with \texttt{ALT/h} keys. More details in \nameref{sec:help_context_help}.}
+
The \CGG{} software is under
\href{https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html}{GPLv2+}
license. A notice of this is included in the software and shown here.
and recently released AV1 and WebP
\item raw image format for over 700 supported cameras, courtesy Dave Coffin's DCraw
\end{itemize}
+
\item[Standard Features]~\\
\begin{itemize}
\item Program window for video and audio tracks, navigation, popups, playing and seeking functions.
\item Numerous pre-defined output formats automatically available and allowance for user-defined formats.
\item Capture and Recording capability to include Broadcast TV recording, editing, and viewing.
\item Hundreds of Shortcuts are defined which are easily viewed using the shell commands pulldown.
+ \item Context Help in the program for numerous window, menu, GUI elements, buttons, and other items via the user's configured web browser.
\item PorterDuff operations are available in the patchbay of the main timeline window for alpha blending.
\item Color correction + 8-bit and 10-bit color space.
\item Up to 8K video supported.
\item[Innovative New Features]~\\
\begin{itemize}
\item Inter-View mode as invented through a collaborative effort by a user and the developer.
- \item Proxy settings for large formatted media with the coveted Scalar option and proxy quick switch.
+ \item Proxy settings for large formatted media with the coveted Scalar option and proxy quick switch. Includes a 1:1 proxy setting used to save CPU time with a reduced bitrate.
\item Multiple cameras / Mixer Viewer with the number of cameras only limited by the resources on the user’s computer (on a large system, 50 are known to work).
\item Audio/Video sync via waveforms, or timecodes to include syncing with externally recorded audio.
\item DVD/bluray creation, editing, and copying for non-commercial media greatly enhanced for usability.
\item Title plugin virtually unlimited script size with many changeable attributes such as size, blink, color.
\item Motion Graphics using the Sketcher plugin to create elements such as ellipses, rectangles and shapes for simpler motion graphics.
\item Open EDL for editing clips, nested clips, and xml files while working on a Project.
- \item File by Reference; To be able to modify the original source during editing (which, in this case, becomes destructive).
+ \item File by Reference; To be able to modify the original source during editing (which in this case, becomes destructive).
\item The Vectorscope option in the Videoscope plugin allows for the use of any number of user-supplied grid patterns as an Overlay.
\item Hardware acceleration with vaapi and vdpau for computers with graphics hardware meeting certain criteria.
\item Bump Autos is a new type of keyframe automation that allows you to easily create and manage keyframes intervals in Speed, Fade and Camera/Projector-XYZ curves.
+ \item One of the only Linux NLEs that handles and renders RGB, 444, 422 and 420 at 8, 10 and more-bit footage as opposed to working in only 8-bit (which introduces some artifacts like banding); both in Full Range Color and limited Broadcast Range Color.
\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}
\item[Chapter~\ref{cha:load_save_and_the_EDL}] \nameref{cha:load_save_and_the_EDL}.
+ The EDL is the list of changes that \CGG{} would make to the original media in order to produce the desired output
Since this is important to not losing your work, you should read this chapter for some basic usage concepts and for some lesser used functions that may come in handy.
Besides how to Load and Save files, there is also information on using raw camera formats.
- Helpful hints on working with image sequences, such as a bunch of pictures from your camera all loaded at once, is a time saver. Understanding that the EDL is the list of changes that
-would be made to the original media in order to produce the desired output is key to ensuring
-that that media remains intact.
-
+ Helpful hints on working with image sequences, such as a bunch of pictures from your camera all loaded at once, is a time saver. Understanding that the EDL is the list of changes that would be made to the original media in order to produce the desired output is key to ensuring that that media remains intact.
+
\item[Chapter~\ref{cha:editing}] \nameref{cha:editing}.
New and occasional users will find it necessary to read this chapter. However, you can decide which editing mode you prefer and concentrate on reading that section.
\item[Chapter~\ref{cha:troubleshooting_help}] \nameref{cha:troubleshooting_help}.
- Use this chapter for diagnosing a problem and find out what to report to get the best resolution or help.
+ Use this chapter for diagnosing a problem and find out what to report to get the best resolution or help. Context Help, using Alt/h, is explained here.
\item[Chapter~\ref{cha:performance_tips}] \nameref{cha:performance_tips}.
\chapter{Keyframes}%
\label{cha:keyframes}
+\index{keyframes}
-The word \textit{keyframe} has at least 3 contextual meanings in the NLE environment. First, the oldest meaning, is the \textit{I-Frame} definition used in codecs algorithms. These are \textit{key} frames that begin a new sequence of pictures, and are anchor points for repositioning (seeks). Next are the automation parameter data points. These are usually input to primitive math forms, like translation and zoom. And last are blobs of data that are chunks of parameters to plugins that can do almost anything. The data can be a simple value, like a fader value, or more complex like a group of points and colors in a sketcher plugin keyframe. The word keyframe has changed a lot in meaning. In the context of \CGG{}, keyframes are data values that have been associated to media on the timeline which affect the media presentation. So a keyframe no longer refers to a frame, but to a position on the timeline.
+The word \textit{keyframe} has at least 3 contextual meanings in the NLE environment. First, the oldest meaning, is the \textit{I-Frame} definition used in codecs algorithms. These are \textit{key} frames that begin a new sequence of pictures (GOP= Group Of Pictures), and are anchor points for repositioning (seeks) \index{seek}. Next are the automation parameter data points. These are usually input to primitive math forms, like translation and zoom. And last are blobs of data that are chunks of parameters to plugins that can do almost anything. The data can be a simple value, like a fader value, or more complex like a group of points and colors in a sketcher plugin keyframe. The word keyframe has changed a lot in meaning. In the context of \CGG{}, keyframes are data values that have been associated to media on the timeline which affect the media presentation. So a keyframe no longer refers to a frame, but to a position on the timeline (timecode).
In \CGG{}, there are two general types of keyframe data,
\textit{automation keyframes} (autos) which are drawn as colored
$\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}
The \textit{autos} are created by clicking on an \textit{automation curve} to establish the time position for the new keyframe anchor point. The basic nature of these simple auto values make them primitive operations that are easy to apply when needed.
-There are many automation curve types, and most are not normally visible or clickable. To make them visible, use the \texttt{View} pulldown, or open the \texttt{Window $\rightarrow$ Show Overlays}. This window allows toggling of the parameters in the \textit{View} pulldown but is more convenient because you can leave the window up to change values quickly. If all of the automation curves are turned on, the timeline will be quite cluttered, and so usually only the parameters of interest are enabled during use. When keyframes are selected, they are drawn on the timeline over the tracks to which they apply. The keyframe is represented on the timeline as a little square on the curve, for example as in fade, or as a symbol as in a mask. This square, timeline attachment point, can be used for positioning by clicking on a keyframe anchor and using drag and drop to set the new position.
+There are many automation curve types, and most are not normally visible or clickable. To make them visible, use the \texttt{View} pulldown, or open the \texttt{Window $\rightarrow$ Show Overlays} \index{show ovelays window}. This window allows toggling of the parameters in the \textit{View} pulldown but is more convenient because you can leave the window up to change values quickly. If all of the automation curves are turned on, the timeline will be quite cluttered, and so usually only the parameters of interest are enabled during use. When keyframes are selected, they are drawn on the timeline over the tracks to which they apply. The keyframe is represented on the timeline as a little square on the curve, for example as in fade, or as a symbol as in a mask. This square, timeline attachment point, can be used for positioning by clicking on a keyframe anchor and using drag and drop to set the new position.
The automation keyframes include:
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}
-The first click on the curve, creates a keyframe which you can click drag on to reposition. The second click at a later position, generates the smoothing by creating a smooth ramp. Ctrl-dragging on a keyframe round control point handle changes the value of either the input control or the output control. This affects the sharpness of the curve. While the input control and the output control can be moved horizontally as well as vertically, the horizontal movement is only for legibility and is not used in the curve value. When you Shift-drag on a timeline curve, the keyframe snaps to the value of either the next or previous keyframe, depending on which exists. It will snap up or down depending on direction of movement. This lets you set a constant curve value without having to copy the next or previous keyframe.
+The first click on the curve, creates a keyframe which you can click drag on to reposition. The second click at a later position, generates the smoothing by creating a smooth ramp. Ctrl-dragging on a keyframe round control point handle \index{control point handle} changes the value of either the input control or the output control. This affects the sharpness of the curve. While the input control and the output control can be moved horizontally as well as vertically, the horizontal movement is only for legibility and is not used in the curve value. When you Shift-drag on a timeline curve, the keyframe snaps to the value of either the next or previous keyframe, depending on which exists. It will snap up or down depending on direction of movement. This lets you set a constant curve value without having to copy the next or previous keyframe.
-To make it easier to navigate curve keyframes, since there is not much room on the timeline for a wide range of curve values, you need to zoom the curves in and out vertically to have any variability. This is done by 2 tools: the automation fit button, Alt-f, and automation zoom menu which is seen at the bottom of the main window (figure~\ref{fig:automation}). The automation fit button scales and offsets the vertical range so the selected curve area appears in the timeline. If a region of the timeline is highlighted by the cursor, only that region is scaled. In/out points do not affect the zoomed region. The automation zoom menu manually changes the vertical scaling of the curves in multiples of 2. Click on its tumbler to change the zoom. Alt$-\uparrow$ and Alt$-\downarrow$ change the automation zoom from the keyboard.
+To make it easier to navigate curve keyframes, since there is not much room on the timeline for a wide range of curve values, you need to zoom the curves in and out vertically to have any variability. This is done by 2 tools: the automation fit button, Alt-f, and automation zoom \index{zoom!panel} menu which is seen at the bottom of the main window (figure~\ref{fig:automation}). The automation fit button scales and offsets the vertical range so the selected curve area appears in the timeline. If a region of the timeline is highlighted by the cursor, only that region is scaled. In/out points do not affect the zoomed region. The automation zoom menu manually changes the vertical scaling of the curves in multiples of 2. Click on its tumbler to change the zoom. Alt$-\uparrow$ and Alt$-\downarrow$ change the automation zoom from the keyboard.
\begin{figure}[htpb]
\centering
\label{fig:automation}
\end{figure}
-\noindent Other mouse actions have the following effects:
+Other mouse actions have the following effects:
\begin{itemize}
\item Double left mouse click on a curve Fade or Speed line will create ganged keyframes so that there is a
keyframe on each of the tracks in the exact same position.
- \item Left mouse click on a keyframe position will show the numerical value in a yellow tooltip-like box.
+ \item Left mouse click on a keyframe position will show the numerical value in a colored tooltip-like box.
\item Right mouse click on the curve type line will bring up the option of \textit{Hide keyframe type}. This
provides the same functionality as disabling the keyframe type in the \textit{View} pulldown menu. Often it
helps to use this in order to be able to see other things on the timeline once it gets cluttered.
\end{enumerate}
\end{itemize}
-You can click mouse button 3 on a keyframe box 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 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}.
\label{fig:fade}
\end{figure}
-In the \textit{Editing} section of \texttt{Settings $\rightarrow$ Preferences, Interface} tab there is \textit{Keyframe reticle} with options of Never, Dragging, or Always. This is used to help in checking edit alignment across tracks. (A reticle is a sighting line used to line up visual items, like cross hairs in a eyepiece.) The appearance and function of sighting lines can be changed when dragging auto keyframes. To see the effect, create some fader autos and drag a few to see the reticles drawn --- you will see something similar to the next screencast (figure~\ref{fig:always}). \textit{Always} renders a line over all plugins, and \textit{dragging} only over the drag icon. \textit{Never} draws nothing. The default is \textit{dragging}.
+In the \textit{Editing} section of \texttt{Settings $\rightarrow$ Preferences, Interface} tab there is \textit{Keyframe reticle} \index{keyframes!reticle} with options of Never, Dragging, or Always. This is used to help in checking edit alignment across tracks. (A reticle is a sighting line used to line up visual items, like cross hairs in a eyepiece.) The appearance and function of sighting lines can be changed when dragging auto keyframes. To see the effect, create some fader autos and drag a few to see the reticles drawn --- you will see something similar to the next screencast (figure~\ref{fig:always}). \textit{Always} renders a line over all plugins, and \textit{dragging} only over the drag icon. \textit{Never} draws nothing. The default is \textit{dragging}.
\begin{figure}[htpb]
\centering
\end{wrapfigure}
Control points allow for setting the slope of auto curves and then
-subsequently adjusting that slope (figure~\ref{fig:controls}). To modify a current keyframe
+subsequently adjusting that slope (figure~\ref{fig:controls}) \index{control point handle}. To modify a current keyframe
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}
Speed automation resamples the data at a higher or lower playback rate. Speed automation can operate
on all tracks of the same type, either video or audio, with a single click; or all tracks, both video and
\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
\section{Bump autos}%
\label{sec:bump_autos}
+\index{keyframes!bump autos}
Bump autos are a kind of floating point keyframe that differs from the rest
of the floating autos, like smooth and linear, in that they have two values:
- a left edge and a right edge value.
+\qquad a left edge and a right edge value.
The presence of a \textit{bump} creates boundaries
to regions on the timeline. The region begins at that bump, and extends to
\item switch to \textit{gang media} mode. Now only the Master track is visible, but every change made on its keyframes is also applied to the other tracks. (see \nameref{sub:displaying_tracks_ganged})
\end{itemize}
-In the Camera and Projector tools configuration window you will find the \textit{Bump curve}, \textit{Span} and \textit{Rigth/Left Edge} buttons. The Camera-XYZ and Projector-XYZ curves can also create and use Bump autos. (see \nameref{ssub:camera_and_projector_menu})
+In the Camera and Projector tools configuration window \index{tool info} you will find the \textit{Bump curve}, \textit{Span} and \textit{Rigth/Left Edge} buttons. The Camera-XYZ and Projector-XYZ curves can also create and use Bump autos. (see \nameref{ssub:camera_and_projector_menu})
\paragraph{Note:} do not confuse the autos bump span button with the keyframes span button of the plugins (on MenuBar); they are different and work differently (see \nameref{sec:allow_keyframes_spanning}). With the plugin keyframes, the update is done by first creating a textual \texttt{diff} on the xml values of the plugin keyframes, then applying that diff to all of the keyframes selected in the \textit{span} range. The bump FloatAuto \texttt{bump\_update} subtracts the old and new values to create a \texttt{diff} that is added to all of the values in the [\textit{right\_edge $\dots$ auto values $\dots$ left\_edge}] region created by bump autos and media endpts.
\section{Plugin Keyframes}%
\label{sec:plugin_keyframe}
+\index{keyframes!plugin}
The Plugin keyframes are structured. The individual data values are named parameters to the keyframe function. For example, the hue plugin has keyframe parameters of hue, saturation, and value. Each plugin has its own parameters, and what they do depends on the plugin. Most of the time, it is pretty obvious what the value controls, like the audio gain plugin with the level parameter. Some of the plugins have a wide variety of controls, like the titler which can setup a wide number of controls, like formats, fonts, styles, placement, and so on.
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}
+\index{keyframes!pulldown}
For plugins, there is a special hidden keyframe, called the \textit{default keyframe}, that is used when no previous keyframe exists. It is like keyframe zero on the timeline, and it is persistent and shared on
all sessions. The intent is to make a parameter set that is likely to be reused on all initial instances of the plugin. An example may be to color correct a set of media that was taken in low light, or needs resampling to be played correctly. The default keyframe is \textit{off the bar on the left side} of the plugin title bar and can not be seen. It is used when there is no \textit{previous} keyframe for its default values.
\section{Keyframe \textit{Edit Params} for Plugins}%
\label{sec:keyframe_edit_params_plugin}
+\index{plugins!preset edit}
-Keyframe values can be set using the various plugin \textit{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.
\section{Compositor Keyframes}%
\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.
\section{More about Editing Keyframes}%
\label{sec:more_about_editing_keyframes}
+\index{keyframes!editing operations}
Keyframes can be shifted around and moved between tracks on the timeline using similar cut and paste operations to editing media. Only the keyframes selected in the View menu are affected by keyframe editing operations.
\section{Allow Keyframe Spanning}%
\label{sec:allow_keyframes_spanning}
+\index{keyframes!spanning}
\textit{Allow keyframe spanning} is enabled on the timeline by clicking on the icon that
is on the right side of the \textit{Generate keyframes while tweaking}. With this enabled,
\vspace{2ex} \textbf{Creative Commons Attribution 4.0 International License}
-Cinfinity icons (c) by "Sam"; Neophyte and Cakewalk themes by "Olaf" are licensed under a
+Cinfinity icons (c) by "Sam"; Neophyte and Cakewalk themes by "Olaf"; Media for Real Work multi-cam workflow by "Armandux" are licensed under a
Creative Commons Attribution 4.0 International License.
see: {\small \url{http://creativecommons.org/licenses/by/4.0/}}
\item Neither the names of the copyright holders nor the names of the contributors may be used to endorse or promote products derived from this software without specific prior written permission.
\end{itemize}
-This software is provided by the copyright holders and contributors \textit{as is} and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall copyright holders or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.
\ No newline at end of file
+This software is provided by the copyright holders and contributors \textit{as is} and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall copyright holders or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.
\chapter{Load, Save, and the EDL}%
\label{cha:load_save_and_the_EDL}
+\index{load media files}
+\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.
\section{EDL --- Edit Decision List}%
\label{sec:edl_edit_decision_list}
-When \CGG{} saves a file, it saves the EDL, Edit Decision List, of the current project but does not save any media.
+When \CGG{} saves a file, it saves the EDL, Edit Decision List, of the current project but does not save any media (Non-Destructive Editing).
Edit decision lists, more commonly referred to as the EDL, are generated by \CGG{} for storing projects.
The EDL contains all the project settings and locations of every edit.
Instead of media, the file contains pointers to the original media files on disk.
\section{Supported File Formats}%
\label{sec:supported_file_formats}
+\index{file format}
There are basically 2 kinds of supported file formats, native and ffmpeg. With the addition of ffmpeg, the majority of the supported file formats you will be using comes via this thirdparty package. There are hundreds of ffmpeg file format and codec combinations. This set of possibilities includes qt (quicktime), avi (audio-video interleave), mp4, mp3, mov, mpeg, m2ts, ts, wmv, mts, mpg, flv, mkv, webm, webp, ProRes and many more.
Raw DV and PCM,
MPEG Audio and Video.
-\paragraph{Still Images:} JPEG/EXR/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.
\subsection{Working with Still Images}%
\label{sub:working_with_still_images}
+\index{still image}
Still images are played from 1 to any number of times, over and over; they have no duration. You can load still images on video tracks just like you do for any video file. When loaded on the track, use the down arrow on the timeline so you can see the single frame. To extend the length of the image, drag its boundaries just as you would do with regular video media. You can drag the boundaries of a still image as much as you want. Images in \CGG{} have the ability to be dragged to an infinite length. Alternatively, you can define the initial length of the loaded images. The parameter is set in the Images section of the \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Recording} window.
\subsection{Timelapse Sequence of Images, and Animation}%
\label{sub:timelaps_sequence_images_animation}
+\index{image sequence}
The next areas covered in this section are the following:
\nameref{ssub:filelist_format} such as jpeglist and \nameref{ssub:image2ffmpeg}.
\begin{center}
\begin{tabular}{l l l l}
PNGLIST = *.png & PPMLIST = *.ppm & TGALIST = *.tga & TIFFLIST = *.tiff \\
- EXALIST = *.exa & CR2LIST = *.cr2 & JPEGLIST = *.jpg & GIFLIST = *.gif
+ EXRLIST = *.exr & CR2LIST = *.cr2 & JPEGLIST = *.jpg & GIFLIST = *.gif
\end{tabular}
\end{center}
%\vspace*{1ex}
-Using the example of jpeg’s, the jpeg list sequence file type is the easiest and fastest way to access a sequence of jpg images as a single asset. First build a jpeglist sequence file and name it something like jpeglist.sh. There is an example script of how to do this in the Auxiliary Programs section of the Appendix (\ref{sec:image_sequence_creation}). Once the jpeglist.sh file is built you can then run it similar to this line:
+Using the example of jpeg’s, the jpeg list sequence file type is the easiest and fastest way to access a sequence of jpg images as a single asset. First build a jpeglist sequence file and name it something like jpeglist.sh. There is an example script of how to do this in the Auxiliary Programs section of the Appendix (\ref{sec:image_sequence_creation}). Once the jpeglist.sh file is built and made executable you can then run it similar to this line:
\begin{lstlisting}[style=sh]
-jpeglist.sh /<path>/file.jpg /<path>/DSC*.jpg
+./jpeglist.sh /<same_path>/outputfile.jpgs /<same_path>/inputfilesDSC*.jpg
\end{lstlisting}
-\vspace*{1ex} \noindent If <\texttt{path}> is the same on both outfile and infiles, then file.jpg is created in the same directory as infiles, the directory contains the entire asset, and the file list uses relative paths; otherwise the file list contains absolute paths. Since this creates outfile list as a single asset, the memory demand and access time is much lower. When you load the outfile in \CGG{}, you will need to set \textit{Try ffmpeg last} since ffmpeg does not work with jpeglist sequence files.
-
-An example output file from running this script residing in the directory where \texttt{DSC*.jpg} files exist is shown below.
+\vspace*{1ex} \noindent The <\texttt{path}> must be the same on both outputfile and inputfiles so that they can be successfully loaded in \CGG{}. Since this creates outputfile list as a single asset, the memory demand and access time is much lower. When you load the outputfile in \CGG{}, you might need to set \textit{Try ffmpeg last} if ffmpeg does not work with that particular type of sequence files.
-To use this, turn off ffmpeg probes first, and open \texttt{timelapse.jpg} using File $\rightarrow$ Load files.
+An example output file from running this script residing in the directory where \texttt{DSC*.jpg} files exist is shown below. To use this, turn off ffmpeg probes first, and open \texttt{outputfile.jpgs} using File $\rightarrow$ Load files. Of course, you can edit this file to change frame rate or names of files to include.
+The width and height should always be the same size for each included file and the file type must be the same. For example, if you include a JPEG file in a GIF list, you will get undesirable results.
-\begin{lstlisting}[style=sh,caption={Example: timelapse.jpg},captionpos=t]
+\begin{lstlisting}[style=sh,caption={Example: outputfile.jpgs},captionpos=t]
JPEGLIST
-# First line is always JPEGLIST
+# First line is always JPEGLIST and all files must be JPEGs
# Frame rate:
29.970030
-# Width:
+# Width - all files must be the same size in width:
6016
-# Height:
+# Height - all files must be the same size in height:
4016
# List of image files follows
./DSC04948.jpg
./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}
Image2file format is an alternative method to open an image sequence via ffmpeg. To do this, create 2 files in the same directory as the \texttt{DSC*.jpg} files named: \texttt{DSC0\%04d.opts}, and \texttt{DSC0\%04d.jpg}.
\texttt{DSC0\%04d.opts} should contain the following lines which have to be modified to fit your exact requirements for duration, start\_number, and frame\_rate.
\subsection{Raw Image Format of Some Digital Cameras \& Probe Order}%
\label{sub:raw_image_format_digital_camera_probe_order}
+\index{raw image}
\textit{Note: requires some expert knowledge.} Raw digital camera images are a special kind of image file that \CGG{} can load. Dcraw, as used by \CGG{}, is Dave Coffin’s open-source computer program which reads many raw-image formats typically produced by many earlier and current digital cameras. Currently over 700 of the types of cameras it recognizes are listed at:
\section{Loading Files}%
\label{sec:loading_files}
+\index{load media files}
All data that you work with in \CGG{} is acquired either by loading from disk or recording from a device. This section describes loading. To bring up the Load window go to the \textit{File} pulldown and choose Load Files (figure~\ref{fig:load}). Next \textit{Select files to load}, and click ok (the green checkmark) or \textit{Apply}. When you use the Apply button, the Load window remains active for easily loading more files later. Depending on the setting of the Insertion Strategy list box, your file will be either loaded directly on the Program window or in the Resources Media window. If the file is a still image, the project's attributes are not changed and the first frame of the track becomes the image. \CGG{} usually builds an index file if one does not already exist, in order to speed up drawing. You can edit and play the file while the index is being built.
\item The new file's tracks are created in the timeline.
\end{itemize}
-\noindent Let's now see in detail the options of loading files.
+NOTE: \CGG{} supports paths of up to 255 characters, which is sufficient for most situations. In the case of long folders, subfolders and filenames, be careful not to exceed this limit to avoid errors.
+
+Let's now see in detail the options of loading files.
\begin{description}
- \item[Insertion Strategy]
+ \item[Insertion Strategy] \index{insertion strategy}
\CGG{} lets you change what happens when you load a file. In the Load dialog window go to the Insertion strategy box and select one of the options in the drop down menu. Each of these options loads the file a different way.
\begin{description}
\item[Append in new tracks:] the current project is not deleted and new tracks are created for the source, one set of tracks for each file. New resources are created in the Resources Window. Files go down tracks.
\item[Concatenate to existing tracks:] the current project is not deleted and new files are concatenated to the existing armed tracks, inserted in the same set of tracks of the current project, one after another, in alphanumeric order, starting at the end of the tracks. If the current project has more tracks than the source, the source file will be inserted in the first set of armed tracks. If no tracks are armed, no files will be inserted. New resources are created in the Resources Window.
\item[Paste at insertion point:] the file is pasted into the timeline at the insertion point, on the first set of armed tracks. If multiple files are selected for loading, they will be inserted on the same set of tracks, one after the other. New resources are created in the Resources Window.
- \item[Create new resources only:] the timeline is unchanged and new resources are created in the Resources Window only.
+ \item[Create new resources only:] the timeline is unchanged and new resources are created in the Resources Window only. This is default.
\item[Nest sequence:] nested assets are added to the timeline by using the Nest sequence insertion strategy.
The file will be pasted into the timeline over the current selection or at the insertion point. A nested sequence is media that had already been saved as an EDL earlier. Nesting is described more fully in section \ref{sec:nesting_clips_and_assets}.
\end{description}
\item[Loading files from the command prompt] Another way to load files is to pass the filenames as arguments on the command line. This starts the program with all the arguments loaded and creates new tracks for every file. For example:
\texttt{\{your\_cinelerra\_program\_path\} video1.mp4 video2.mp4}
- \item[Finding Files by Extension, Sub-list, or with Search] If there are too many files in your media directory, it can be difficult to find the file you want. For this reason, the Load window allows you to filter which files are displayed in the list box by extension name. Click the dropdown box on the right side of the \textit{Specify filter} list box below the file name text box, and select the file extension of your media (for example: mp4, mov, mp3, avi, jpg, etc). The file list now shows only files with the selected extension. Perhaps even easier is to use the Search box on the top underneath the \textit{Select files to load} listbox. Here you can keyin a character or string to look for. \\
+ \item[Finding Files by Extension, Sub-list, or with Search] \index{media files filter/search} If there are too many files in your media directory, it can be difficult to find the file you want. For this reason, the Load window allows you to filter which files are displayed in the list box by extension name. Click the dropdown box on the right side of the \textit{Specify filter} list box below the file name text box, and select the file extension of your media (for example: mp4, mov, mp3, avi, jpg, etc). The file list now shows only files with the selected extension. Perhaps even easier is to use the Search box on the top underneath the \textit{Select files to load} listbox. Here you can keyin a character or string to look for. \\
You can also get a sub-list of potential files to choose from. For example, you know that the file you are looking for begins with the capital letter "C". If you keyin "C" into the selection box immediately below the list of files, and then click the left mouse button, a sub-list of files beginning with the "C" shows up under the selection box. Clicking the right mouse button cancels this sub-list.
- \item[Loading the backup] There is one special XML file on disk at all times.
+ \item[Loading the backup] \index{backup} There is one special XML file on disk at all times.
After every editing operation, \CGG{} saves the current project to a backup in \texttt{\$HOME/.bcast/backup.xml}.
In the event of a crash, the first thing you should do after restarting \CGG{} is select \texttt{File $\rightarrow$ Load backup} in order to load the backup.
\subsection{Sort within Sort in File Load Dialog}%
\label{sub:sort_within_sort_file_load_dialog}
+\index{sort media files}
When you use the \textit{File} pulldown to load files, you can do a sort within a sort when you click on the labeled header box (figure~\ref{fig:load-sort}). This is useful, for example, when you want to find the smallest file for a specific extension. In the screenshots below, the first illustrates the default \textit{File} sorted alphabetically; the second shows the \textit{Size} is now sorted; the third shows how after sorting on Size, you sort on Ext. The size sort is maintained within the extension sort so that \textit{c.d} comes before \textit{a.d} in the File header box because the size is smaller.
\subsection{Probe Order when Loading Media}%
\label{sub:probe_order_loading_media}
+\index{probe order}
Why is this mentioned here? So many programs have been written whose functionalities overlap and you may want to ensure that the one you wish to use is actually used. Over time which one matches first may vary. Ffmpeg is so generic that if your setting is \textit{Try ffmpeg first} it will almost certainly get used and it leaves little chance that other methods will even get a chance. Some of the codec file drivers can open a variety of media, and some of the more common methods may have more than one file driver which could be useful to decode your media file, for example Tiff. For expert specialized usage, when you want to guarantee that a certain method is used, you can change the \textit{probe order}. Use the pulldown \texttt{Settings $\rightarrow$ Preferences} to get to the \textit{Interface tab} where you will see a box in the \textit{Operation} section on the left side called \textit{Probe Order}. Click on the box and use the up/down/enabled boxes to change the order of the item you have highlighted (figure~\ref{fig:probe}).
\subsection{Program Selection Support after Load}%
\label{sub:program_selection_support_load}
+\index{program streams selection}
Some kinds of media have \textit{program} streams, like captured mpeg broadcast stream data. For example, you may be able to \textit{tune} to channel 9, but be able to see 9-1, 9-2, and 9-3 on your TV\@. If you open a capture of this kind of media, all of the channels are present in the timeline. To select and view just one program, you can use Alt-1 to select program 1, or Alt-2 to select program 2, etc.\ up to Alt-8. This will remove all of the other unrelated tracks and reset the format. This feature can be used even if there is only one program, by pressing Alt-1, and the effect will be to reset the session format to the parameters from the media probe. Note that there may be several audio \textit{programs} associated to a video stream;
for example, there may be dialog in another language or some kind of descriptive dialog. Since the first associated audio is always selected, this may not produce the intended results.
\section{Saving Your Work}%
\label{sec:saving_your_work}
+\index{save media files}
You can save your work as a project, which is what is loaded in \CGG{} now, or as an export, which is all the media it takes to reproduce your project space.
\subsection{Saving Project Files}%
\label{sub:saving_project_files}
+\index{project save}
Saving XML files is useful to save the current state of \CGG{} before quitting an editing session. \CGG{} saves projects as XML files. There are a few options you can use to save your work via the \textit{File} pulldown menu: \textit{Save}, \textit{Save as\dots}, \textit{Export project}, \textit{Save backup}. You can either overwrite an existing file or enter a new filename. \CGG{} automatically concatenates \texttt{.xml} to the filename if no \texttt{.xml} extension is given.
-When \CGG{} saves a file, it saves the EDL of the current project but does not save any media, instead just pointers to the original media files. For each media file, the XML file stores either an absolute path or just the relative path. If the media is in the same directory as the XML file, a relative path is saved. If it is in a different directory, an absolute path is saved.
+When \CGG{} saves a file, it saves the EDL \index{EDL} of the current project but does not save any media, instead just pointers to the original media files. For each media file, the XML file stores either an absolute path or just the relative path \index{absolute/relative path}. If the media is in the same directory as the XML file, a relative path is saved. If it is in a different directory, an absolute path is saved.
You have to be careful when moving files around to avoid breaking the media linkages. You can keep the media and the XML file in the same directory forever and freely move the whole directory, since relative paths are saved. Alternatively you can save the XML file in a different directory than the media but then you can't move the media. In this case you can freely move your XML file around, since absolute paths are saved. If you saved your XML file in the same directory as your media but you would like to move location, you can change the paths from relative to absolute by going
to \texttt{File $\rightarrow$ Save as}$\dots$ and entering the new location. Similarly if you saved your project outside your media directory but you would like to move your media to another location, you can change the paths from absolute to relative by going to \texttt{File $\rightarrow$ Save as}\dots and saving your XML file in the same directory as the media.
\subsection{Export Project – Save or Moving Project to another Computer}%
\label{sub:export_project}
+\index{project export}
\begin{figure}[htpb]
\centering
\noindent Keep in mind that to maintain the integrity of your project xml file for easy moving to another computer, do not delete the symbolic links. You will want to use \texttt{cp\,-a} to maintain the links for moving to a USB key or another computer.
-\subsection{Information about Backups and Perpetual Session}%
-\label{sub:information_backups_perpetual_session}
+\subsection{Export to EDL}%
+\label{sub:export_to_edl}
+
+CMX3600 is an outdated and limited format for EDL. For example it only goes up to 999 edits per project, supports only 4 audio tracks per video track and supports only Cuts, Fades and Keys. But it has the advantage of being a standard format supported by many NLEs. \CGG{} uses a rich XML format that is not compatible with other NLEs. You can use the \textit{Export to EDL} option to try to produce EDL files of type CMX3600 in \textit{strict mode} and thus be able to bring them into other NLEs. Given the limitation of this format, however, it is difficult to get a working EDL file that exactly reproduces the original xml. This feature also produces files that each contain a video track or an audio track and does not embed video with audio or audio with audio. Manual intervention with a plain text editor on the produced EDL files may be necessary. For example, if the program in which you want to open the EDL reports the message of not being able to find the source files, then we can manually add the path to each line that reports the source file.
+
+\subsection{Backup and Perpetual Session}%
+\label{sub:backup_perpetual_session}
+\index{backup}
+\index{perpetual session}
-In an effort to minimize loss of work due to user, hardware, or software issues, \CGG{} has some automatic backup capabilities.
+\textbf{Default behavior:}\\
+In an effort to minimize loss of work due to user, hardware, or software issues, \CGG{} has some automatic backup capabilities. \CGG{} automatically saves every editing operation to the current project on disk continuously to a file named \texttt{\$HOME/.bcast5/backup.xml}. We can also make a manual backup via \texttt{File $\rightarrow$ Save backup} ("b") or we can load the chosen backup via \texttt{File $\rightarrow$ Load backup}. Before a new backup is rewritten to \texttt{backup.xml} by an editing operation, the content is automatically copied to \texttt{backup.prev} which becomes a second backup file. In total we have 2 levels of backups: the previous one, called \texttt{backup.prev}, and the current one, called \texttt{backup.xml}.
-\CGG{} automatically saves every \textit{editing operation} to the current project on disk continuously to a file named \texttt{\$HOME/.bcast5/backup.xml}. In the unlikely event of a crash, when you restart \CGG{}, you should select \texttt{File $\rightarrow$ Load backup} in order to continue with the operations that were recorded before the crash. If you have more than 1 instance of \CGG{} running, only the last editing operation made in whichever instance it was last made, will overwrite the backup.
+In the un-likely event of a crash, when you restart \CGG{}, you should select \texttt{File $\rightarrow$ Load backup} in order to continue with the operations that were recorded before the crash. If you have more than 1 instance of \CGG{} running, only the last editing operation made in whichever instance it was last made, will overwrite the \texttt{backup.xml}.
+If for some reason you forgot to use \textit{Load backup} immediately when restarting or you did a Load with \textit{Replace current project} in your current session (not default behavior!), you have a second chance to use \texttt{File $\rightarrow$ Load backup} and select \texttt{\$HOME/.bcast5/backup.prev} as long as you only loaded a different file and have performed no editing operations. This same file is also used by multiple instances of \CGG{}.
-There is still 1 more backup that may save you. If for some reason you forgot to use \textit{Load backup}
-immediately when restarting or you did a Load with \textit{Replace current project} in your current session,
-you have a second chance to use \texttt{File $\rightarrow$ Load} and select \texttt{\$HOME/.bcast5/backup.prev}
-as long as you only loaded a different file and have performed no editing operations. This same file is also used by multiple instances of \CGG{}.
+\textbf{Use of \textit{Autosaves continuous backups:}}\protect\footnote{credits to Andrew Randrianasulu and Reuss Andràs} \\
+\textit{Autosaves continuous backups} can be enabled in (see \nameref{sub:dangerous_section}): \\
+\texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance Tab $\rightarrow$ Dangerous} \\
+In this modality the formation of \texttt{backup.xml} and \texttt{backup.prev} remains the same. In addition there is a simultaneous formation of a third copy with a timestamp, called \texttt{backup\_prev.xxxxxxxx.xxxx} (with \textit{Date} and \textit{Clock time}). So at each editing operation a backup will be created with its own timestamp. The user can thus go back to the moment when he wants to restart an editing, because of an error, or to experiment with different choices from a certain moment on.
-\textbf{Perpetual session} is very useful for working on a project over many days so you can just quit before shutting down and the next time you start up \CGG{} you will be right back where you left off.
+We can load the backup file of our choice via \texttt{File $\rightarrow$ Load backup}. For long editing sessions it is easy to have lots of backups but when you exit from \CGG{}, all files with timestamps will be deleted except the last 50, which will still be available at the next restart.
+
+\textbf{Perpetual session:} \\
+is very useful for working on a project over many days so you can just quit before 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.
-The binary file name is \texttt{\$HOME/.bcast5/perpetual.dat} and as long as \texttt{Settings $\rightarrow$ Preferences}, the Appearance tab has the Flag \textit{Perpetual session} set this capability takes effect.
-It is very important to understand that this is not the same as the continuously editing- operation-updated \texttt{backup.xml} file.
-The perpetual.dat file is \textit{only} updated when you Quit \CGG{} in the normal manner.
-Which means if you interrupt the program, or kill it, or there is a segv or system crash, the \texttt{perpetual.dat} file will only reflect the state of your project from when you last started \CGG{}, and none of the editing/undo’s/redo’s you executed during the current session which was not ended normally.
-\vspace{1ex}
+The binary file name is \texttt{\$HOME/.bcast5/perpetual.dat} and as long as \texttt{Settings $\rightarrow$ Preferences}, the \textit{Appearance} tab has the Flag \textit{Perpetual session} set this capability takes effect.
+It is very important to understand that this is not the same as the continuously editing- operation-updated \texttt{backup.xml} file which is still operating as usual.
+The \texttt{perpetual.dat} file is updated so that when you Quit \CGG{} in the normal manner,
+interrupt the program, kill the program, or there is a segv or system crash, the \texttt{perpetual.dat} file still reflects the state of your project. This means the editing/undo’s/redo’s you executed during the current session should still be available on a restart with the exception of any edit
+that may not have had a chance to be written on disk before an abnormal stoppage.
Some notes to keep in mind about Perpetual session are:
\item when you Quit in the normal manner, it does not have to ask whether or not to save a backup
\item takes disk space in \texttt{.bcast5} area and this could get really big
\item after you complete a project, it is advisable to turn off the Perpetual session flag before quitting so
- that when you start a new project, you can start with a fresh perpetual.dat by turning the flag on or
+ that when you start a new project, you can start with a fresh \texttt{perpetual.dat} by turning the flag on or
after stopping \CGG{}, delete the current \texttt{\$HOME/.bcast5/perpetual.dat} file
\item only session data is backed up (not program feature setup)
- \item the files backup.xml and backup.prev will operate the same as before so that if there is a crash, you
- will want to use \texttt{File $\rightarrow$ Load backup} in order to continue where you were interrupted.
- \item to start \CGG{} without using your Perpetual session data even if enabled, keyin: /your\_cinelerra\_path\texttt{/bin/cin -S}
+ \item the files \texttt{backup.xml} and \texttt{backup.prev} will operate the same as before so that if there is a crash, you
+ can still use \texttt{File $\rightarrow$ Load backup} in order to continue where you were interrupted.
+ \item to start \CGG{} without using your Perpetual session data even if enabled, keyin: \texttt{/your\_cinelerra\_path/bin/cin -S}
+\end{itemize}
+
+\textbf{For developers:} \\
+We report the list of editing events that lead to the automatic formation of a backup file:
+
+\begin{itemize}
+ \item cinelerra/cwindowgui.C
+ \item cinelerra/swindow.C
+ \item cinelerra/keyframepopup.C
+ \item cinelerra/pluginpopup.C
+ \item cinelerra/mwindowedit.C
+ \item cinelerra/presetsgui.C.sav1
+ \item cinelerra/assetpopup.C
+ \item cinelerra/cwindowtool.C
+ \item cinelerra/render.C
+ \item cinelerra/setformat.C
+ \item cinelerra/mwindow.C
+ \item cinelerra/keyframegui.C
+ \item cinelerra/mwindowgui.C
+ \item cinelerra/mainmenu.C
+ \item cinelerra/loadfile.C
+ \item cinelerra/savefile.C
+ \item cinelerra/menueffects.C
+ \item cinelerra/main.C
+ \item cinelerra/presetsgui.C.sav
+ \item cinelerra/record.C
+ \item cinelerra/plugindialog.C
\end{itemize}
\chapter{Overlays}%
\label{cha:overlays}
+\index{overlays}
The purpose of the Overlay Modes is to control the foreground and background stacking and use blending to reshape image object boundaries. It normally makes use of a binary type alpha blending system for all in or all out. To use the available operations in \CGG{}, follow these steps:
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}
-\subsection*{Normal}%
+% Leave the word Group in due to latex2html dual name conflict
+\subsection*{Normal Group}%
\label{sub:normal2}
+\index{overlays!normal}
\begin{description}
\item[Normal:] Normal mode is the default layer mode. The result color is the source color. The layer on top covers the layers below it. If you want to see anything below the top layer when you use this mode, the layer must have some transparent areas. It is \textit{stacked on top}. Math formula used is different than that used by Gimp; there is no SVG equivalent.
\subsection*{Arithmetic Group:}%
\label{sub:arithmetic_group}
+\index{overlays!arithmetic}
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}%
\label{sub:porter-duff_group}
+\index{overlays!Porter-Duff}
Industry standard compositing operators.
\subsection*{Logical Group}%
\label{sub:logical_group}
+\index{overlays!logical}
\begin{description}
\item[Min:] The output color is the component-wise minimum value of the source and destination colors. There is no SVG or Gimp equivalent math formula.
\subsection*{Graphical Art Group}%
\label{sub:graphical_art_group}
+\index{overlays!graphical art}
Typical operations from popular \textit{paint} packages.
\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
\chapter{Plugins}%
\label{cha:plugins}
+\index{plugins}
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]
\label{fig:video-plugins}
\end{figure}
-There is a choice of plugin icons which can be displayed.
+There is a choice of plugin icons \index{plugins!icons} which can be displayed.
In \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Appearance} tab, there is a pulldown for \textit{Plugin icons} where the user can choose between the \textit{original} icons, \textit{regular} or \textit{smoother}, \textit{cinfinity}\protect\footnote{Cinfinity /2 icon set is credited to Sam - Creative Common By -- \url{https://creativhecommons.org/licenses/by/3.0/}} -- the default modernized set, or \textit{cinfinity2} (figure~\ref{fig:audio-plugins}).
\section{How to Use Plugins}%
\label{sec:how_use_plugins}
-\textit{Realtime} effect plugins are listed in the Resources window as \textit{Audio} Effects and \textit{Video} Effects. Effect plugins are used by dragging them from the Resources window onto an audio track if it is an audio effect or video track if it is a video effect. You will see a colored bar appear beneath the track with the plugin name on it. If there is data on the destination track, the effect is applied to the entire track, unless a region of the track is selected in which case the effect is pasted into that region only. If there is no data on the track the effect is not added.
+\textit{Realtime} effect plugins are listed in the Resources window as \textit{Audio} Effects and \textit{Video} Effects. Effect plugins are used by dragging them from the Resources window onto an audio track if it is an audio effect or video track if it is a video effect. You will see a colored bar \index{plugins!toolbar} appear beneath the track with the plugin name on it. If there is data on the destination track, the effect is applied to the entire track, unless a edit or a region of the track is selected (wipe selection or In/Out points) in which case the effect is pasted into that region only. If there is no data on the track or no selected region set, the effect is not added.
-Plugins are layered under the track they apply to. When dragging more than one effect onto a track, you will see the effects layering from \textit{top to bottom}, on the bottom of that track. When the track is played back, effects are processed from \textit{top to bottom}. The output of the top effect becomes the input of the bottom effect and so on.
+Plugins are layered under the track they apply to. When dragging more than one effect onto an armed track, you will see the effects layering from \textit{top to bottom}, on the bottom of that track. When the track is played back, effects are processed from \textit{top to bottom}. The output of the top effect becomes the input of the bottom effect and so on. "The pipeline in Cinelerra's\protect\footnote{credit to Original Creator} plugin design is the \textit{pull} method. The rendering pipeline starts at the final output and the final steps in the rendering pipeline are reading the data from disk. Every step in the rendering chain involves requesting data from the previous step. When the rendering pipeline eventually requests data from a plugin chain, each plugin requests data from the plugin before it. This is less intuitive than the push method but is much more powerful. Realtime plugins written using the pull method can change the rate data is presented to the viewer and the direction of playback. The pull method allows plugins to take in data at a higher rate than they send it out." Side note: if you want to avoid the automatic \textit{top to bottom} application of plugins, you can take advantage of \textit{nested assets} to manipulate the order the plugins are applied (see \ref{sec:nesting_clips_and_assets}).
-Instead of dragging from the Resources window, effects may be applied to a track via a popup menu. Right click on a track and select \textit{Attach effect} from the popup. The attach effect dialog gives you more capability than just dragging and dropping. For example, the attach effect dialog lets you attach two more types of effects: \textit{shared effects} and \textit{shared tracks} which are explained in a later section. Select a plugin from the Plugins column and hit the green colored checkmark under the plugins column to attach it. The result is the same as if the effect was dragged from the Resources window.
+Instead of dragging from the Resources window, effects may be applied to a single armed track or a region via a popup menu. On the entire track or on a region determined by a selection wipe or by the In/Out points, right click and select \textit{Attach effect} \index{plugins!attch effect} from the popup. The attach effect dialog gives you more capability than just dragging and dropping. For example, the attach effect dialog lets you attach two more types of effects: \textit{shared effects} and \textit{shared tracks} which are explained in a later section. Select a plugin from the Plugins column and hit the green colored checkmark under the plugins column to attach it. The result is the same as if the effect was dragged from the Resources window.
+
+One more method to apply an effect on all armed tracks of the same type (video or audio) is to use the \textit{Video} or \textit{Audio} pulldown \textit{Attach Effect} option. This brings up a menu which has a useful checkbox to \textit{Attach single standalone and share others} (see \ref{sec:shared_effect_tracks}). The default setting is checked on.
-After attaching an effect to a track, it often needs to be configured. There are two ways to get to the configuration controls. Click on the magnifying glass symbol on the right side of the effect bar -- this is the middle symbol on the bar as you can see in the picture below. Alternatively, you can right click on the effect bar to bring up the effect popup which has a \textit{Show} option. Either method causes the GUI for the effect to appear in a separate window. There will not be a popup if the plugin has no GUI.
+After attaching an effect to a track, it often needs to be configured. There are two ways to get to the configuration controls. Click on the magnifying glass \index{plugins!show controls} symbol on the right side of the effect bar -- this is the middle symbol on the bar as you can see in the picture below. Alternatively, you can right click on the effect bar to bring up the effect popup which has a \textit{Show} option. Either method causes the GUI for the effect to appear in a separate window. There will not be a popup if the plugin has no GUI.
Besides the magnifying glass, for Show Controls, on the effect colored bar beneath the track, there are two more symbols.
\includegraphics[width=0.7\linewidth]{button-options.png}
\end{wrapfigure}
-The rightmost knob is used to Turn Off/Turn On the effect where the default is On. This is useful to easily see that the plugin is doing what you expect. The leftmost symbol that looks like a gear is for \textit{Preset Edit} and its usage is described in the section \nameref{sec:saved_plugin_preset}.
+The rightmost knob is used to Turn Off/Turn \index{plugins!turn on/off} On the effect where the default is On. This is useful to easily see that the plugin is doing what you expect. The leftmost symbol that looks like a gear is for \textit{Preset Edit} \index{plugins!preset edit} and its usage is described in the section \nameref{sec:saved_plugin_preset}.
\section{Editing Effects}%
\label{sec:editing_effects}
+\index{plugins!editing}
Many operations exist for manipulating effects once they are on the timeline. Because mixing effects and media is quite complex, the methods used in editing effects are not as concise as cutting and pasting. Some of the editing happens by dragging in/out points, some of the editing happens through popup menus, and some of it happens by dragging effects.
-When enabled, which is the default, and you edit tracks, the effects follow the editing decisions. If you cut from a track, the effect shrinks. If you drag edit in/out points, the effect changes length. This behavior can be disabled by selecting \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Interface tab$\rightarrow$ Editing section}, see figure~\ref{fig:editing-effects}.
+When enabled, which is the default, and you edit tracks, the effects follow the editing decisions. If you cut from a track, the effect shrinks. If you drag edit in/out points, the effect changes length. This behavior can be disabled by selecting \texttt{Settings$\rightarrow$ Preferences$\rightarrow$ Interface tab$\rightarrow$ Editing section}, see figure~\ref{fig:editing-effects} \index{keyframes reticle}.
\begin{figure}[htpb]
\centering
\label{fig:editing-effects}
\end{figure}
-To edit effects, you can move the timeline cursor over the effect borders until it changes to a resize left or resize right icon. In this state, if you drag the end of the effect, it performs an edit just like dragging an edit edge. The five editing behaviors of track trimming apply to effect trimming and they are bound to the mouse buttons that you set in interface preferences as shown in the previous screencast. \textit{Trimming} simply means changes the duration dragging the edges.
+To edit effects, you can move the timeline cursor over the effect borders until it changes to a resize left or resize right icon. In this state, if you drag the end of the effect, it performs an edit just like dragging an edit edge. The five editing behaviors of track trimming \index{trim} apply to effect trimming and they are bound to the mouse buttons that you set in interface preferences as shown in the previous screencast. \textit{Trimming} simply means changes the duration dragging the edges.
When you perform a trim edit on an effect, the effect boundary is moved by dragging it. Unlike track editing, the effect has no source length. You can extend the end of an effect as much as you want. Also unlike track editing, the starting position of the drag operation does not bind the edit decision to media. The media the effect is bound to does not follow effect edits. Other effects, however, do follow editing decisions made on an effect. You can disable effects from being subject to the edit decisions by using the pulldown \textit{Settings} and toggling off Edit effects. If you drag the end of an effect which is lined up to effects on other tracks, the effects on the other tracks will be edited while the media stays the same. When you drag an effect in from the Resources window you can insert the effect in the portion of the row unoccupied by the trimming operation. In some cases you will want a trimming operation to change only one row of effects. This can be achieved by first positioning the insertion point on the start or end of the effect. Then press the shift key while beginning the trimming operation. This causes the operation to change only one row of effects.
-You can move effects up or down. Every track can have a stack of effects under it. By moving an effect up or down you change the order in which effects are processed in the stack. Go to an effect and right click to bring up the effect menu. The \textit{Move up} and \textit{Move down} options move the effect up or down. When you are moving effects up or down, be aware that if they are shared as shared effects, any references will be pointing to a different effect after the move operation.
+You can move effects up or down. Every track can have a stack of effects under it. By moving an effect up or down you change the order in which effects are processed in the stack. Go to an effect and right click \index{plugins!RMB on toolbar} to bring up the effect menu. The \textit{Move up} and \textit{Move down} options move the effect up or down. When you are moving effects up or down, be aware that if they are shared as shared effects, any references will be pointing to a different effect after the move operation.
-Finally, there is dragging of effects. Dragging effects works just like dragging edits. You must select the arrow in the main window transport buttons line to enter drag and drop mode before dragging effects. Dragging a plugin causes a highlight outline to be drawn over a targetable timeline region, and the plugin can be re-positioned into any plugin track. The effects snap to media boundaries, effect boundaries, and tracks. If you drag a reference to a shared effect, the reference may point to the wrong effect afterwards. It is recommended that you re-construct shared effect track references.
+Finally, there is dragging of effects \index{plugins!dragging}. Dragging effects works just like dragging edits. You must select the arrow in the main window transport buttons line to enter drag and drop mode before dragging effects. Dragging a plugin causes a highlight outline to be drawn over a targetable timeline region, and the plugin can be re-positioned into any plugin track. The effects snap to media boundaries, effect boundaries, and tracks. If you drag a reference to a shared effect, the reference may point to the wrong effect afterwards. It is recommended that you re-construct shared effect track references.
-Figure~\ref{fig:drag-effect} showing 5 plugins, two still plugin, two have already been dragged and the \textit{Color 3 Way} in the process of being dragged. Note the gold-colored arrow which enables allow \textit{drag and drop} editing mode.
+Figure~\ref{fig:drag-effect} showing 3 plugins, two still plugin, two have already been dragged and the \textit{Color 3 Way} in the process of being dragged. Note the gold-colored frame which enables allow \textit{drag and drop} editing mode.
\begin{figure}[htpb]
\centering
\label{fig:drag-effect}
\end{figure}
+\section{Copy/Paste Effects}%
+\label{sec:copy_paste_effects}
+\index{plugins!copy paste effects}
+
+In \textit{Drag and Drop} mode we can copy and paste edits containing plugins (see also \nameref{sub:copy_paste_behavior}). Start by selecting an edit (that contains plugins) with LMB and open the context menu with MMB. The possibilities offered are:
+
+\begin{description}
+ \item[Ctrl - c]: copy edits and plugins to buffer.
+ \item[Ctrl - v]: paste edits and plugins into the timeline (splice) at the Insertion point.
+ \item[Ctrl - b]: paste edits and plugins into the timeline (overwrite) at the Insertion point.
+ \item[Ctrl - Shift - p]: paste only the plugins into the timeline, at the Insertion point, keeping the original length (overwrite).
+ \item[Collect Effects]: copy only plugins into buffer.
+ \item[Paste Effects]: pastes the plugins into a selected target edit. The length of the plugins adapts to the length of the edit.
+\end{description}
+
\section{Shared Effects and Shared Tracks}%
\label{sec:shared_effect_tracks}
+\index{plugins!shared effect}
+\index{plugins!shared tracks}
Two other effect types available in the Attach Effect dialog are \textit{Shared effects} and \textit{Shared tracks}. In the case of a shared effect, the following conditions must be true:
Before going into further detail about how to use \textit{Shared effects}, an easier
alternative method of application which is especially useful for Audio tracks is
available. In this method, all you have to do is use the \textit{Audio} pulldown and
-choose \textit{Attach effect}, highlight the effect you would like and make sure the
+choose \textit{Attach effect} \index{plugins!attach effect}, highlight the effect you would like and make sure the
default of \textit{Attach single standalone and share others} is checked on. It will
automatically be a "Shared Effect" on all audio tracks (be sure to disarm any audio
tracks that you do not want to have the effect shared on). This method also works for
When an original track has a shared track as one of its effects, the shared track itself is used as a \textit{realtime} effect. This is more commonly known as \textit{bouncing tracks} but \CGG{} achieves the same operation by attaching shared tracks. The fade and any effects in the shared track are applied to the original track. Once the shared track has processed the data, the original track performs any effects which come below the shared track and then composites it on the output.
-In order to prevent the shared track from mixing the same data as the original track on the output, enable the output \texttt{mute} toggle in the patchbay next to each track for which you do not want to mix on the output. If you are making a video and you do want the shared track to composite the original track's data on the output a second time, the video from the shared track would always appear under the video from the original track, regardless of whether it was on top of the original track. This is because shared tracks are composited in order of their attachment. Since it is part of the original track it has to be composited before the original track is.
+In order to prevent the shared track from mixing the same data as the original track on the output, enable the output \texttt{mute} \index{mute} toggle in the patchbay next to each track for which you do not want to mix on the output. If you are making a video and you do want the shared track to composite the original track's data on the output a second time, the video from the shared track would always appear under the video from the original track, regardless of whether it was on top of the original track. This is because shared tracks are composited in order of their attachment. Since it is part of the original track it has to be composited before the original track is.
\section{Saved Plugin Presets}%
\label{sec:saved_plugin_preset}
+\index{plugins!preset edit}
\textit{Presets} and \textit{Factory Presets} for Plugin settings are now combined with the Preset Keyframe Parameters allowing you to choose, apply, delete, and edit your own Presets which can then be easily saved in the file \texttt{\$HOME/.bcast5/Cinelerra\_presets}. In addition to your own saved presets, there are automatically available Factory presets for some plugins, for example the Lens video plugin. The Factory presets are preceded by an asterisk (*) and can not be modified permanently.
\subsection{How to see short Description of a Plugin}%
\label{sub:short_description_plugin}
+\index{plugins!short description}
To get a short one or a few lines description of a plugin, mouse over that plugin in the Resources window and a popup appears. You can disable the popup by right-clicking and choosing \textit{Info Off} (shortcut "i"). And again enable it with \textit{Info On}. Some of the plugins may not have any description included. An example screenshot is next (figure~\ref{fig:info-effect}).
\label{fig:info-effect}
\end{figure}
+\textit{Context Help} provides more detailed information about the plugin in 4 possible
+ways using the Alt/h hotkey combination.
+\begin{enumerate}
+ \item Pressing \texttt{Alt/h} with the mouse in the dialog window of that plugin's settings menu.
+ \item Pressing \texttt{Alt/h} while pointing with the mouse on the plugin bar in a track, transition bar, or transition icon.
+ \item Pressing \texttt{Alt/h} while pointing on the plugin name (icon) in the Resources window. If plugin tooltips are on, help for the highlighted plugin under the mouse is shown. If plugin tooltips are off, help for the selected plugin is shown.
+ \item Pressing \texttt{Alt/h} while pointing on the plugin name in the \textit{Attach Effect} dialog menu.
+\end{enumerate}
+
\subsection{Delete Plugins to save Resources Space or make them Unavailable}%
\label{sub:delete_plugin_resouces_unavaible}
-Maybe you just don't ever use certain plugins or would prefer to only find the ones that are useful to you. To save space in the Resources Window so you don't have to scroll to find the plugins you want as much, a feature to delete others is available. If you have a System install, you will have to be root for this function to be usable. The plugins will be permanently deleted, but only until you rebuild or download a new set of \CGG{} binaries. To delete a plugin, highlight the plugin you no longer want in the Resources window then press Ctrl-Shift-delete. A small window will come up allowing you to change your mind and red-X out or check-OK to remove plugin. This feature may come in handy if you have personnel working on media for you and you only want them to exercise certain functions. Or maybe you can't remember which is the good \textit{deinterlace} plugin out of the available five or so and want to delete the extras so as not to be confused. The ffmpeg, \textit{ladspa}, and \textit{lv2} plugins can not be deleted in this manner but, of course, you can always turn them off from view by clicking on \textit{Visibility} and unchecking them (figure~\ref{fig:remove-effect}).
+Maybe you just don't ever use certain plugins or would prefer to only find the ones that are useful to you. To save space in the Resources Window so you don't have to scroll to find the plugins you want as much, a feature to delete others is available. If you have a System install, you will have to be root for this function to be usable. The plugins will be permanently deleted, but only until you rebuild or download a new set of \CGG{} binaries. To delete a plugin, highlight the plugin you no longer want in the Resources window then press Ctrl-Shift-delete. A small window will come up allowing you to change your mind and red-X out or check-OK to remove plugin.
+AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
+
+This feature may come in handy if you have personnel working on media for you and you only want them to exercise certain functions. Or maybe you can't remember which is the good \textit{deinterlace} plugin out of the available five or so and want to delete the extras so as not to be confused. The ffmpeg, \textit{ladspa}, and \textit{lv2} plugins can not be deleted in this manner but, of course, you can always turn them off from view by clicking on \textit{Visibility} and unchecking them (figure~\ref{fig:remove-effect}).
\begin{figure}[htpb]
\centering
\subsection{Updatable Icon Image Support}%
\label{sub:updatable_icon_image_support}
+\index{plugins!change icons}
When running \CGG{} Infinity builtin icons are loaded before the
program starts. Png files in the path:\\
(or cinfinity2, original or smoother -- Leap distro)
+AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
+
\subsection{Details on where to put your own Plugin Icons}%
\label{sub:details_put_plugin_icons}
\label{sub:example_plugin_icon_testing}
For a simple test just copy an existing \texttt{<plugin\_name>.png} file into the cinfinity directory with the name \texttt{bluebanana.png} to write over the existing file. This icon will now show up in \CGG{} and still execute the Blue Banana function.
+AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
For an ffmpeg plugin, create \texttt{ff\_loop.png} and copy it to: \\
\texttt{<cinlib\_path>/plugins/picon/original}. This icon will show up in \CGG{} if original is selected and execute the \textit{F\_loop} function.
\subsection{Plugins/Effects Visibility}%
\label{sub:plugins_effects_visibility}
+\index{plugins!visibility}
\CGG{} contains many plugins, especially with the addition of ffmpeg, and it is somewhat difficult to find the one you are looking for in the Resources window. In \CGG{} Infinity, the plugins have been categorized into the following subsets in the \textit{Visibility} section of the Resources window to make it easier to locate a particular one:
\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
\includegraphics[width=0.8\linewidth]{expander.png}
- \caption{$\triangledown$,$\triangleright$ = expander; "-" = options}
+ \caption{Down facing triangle, Right facing triangle = expander; "-" = options}
+% the next line causes problems for the HTML version so do not use
+% \caption{$\triangledown$,$\triangleright$ = expander; "-" = options}
\label{fig:expander}
\end{figure}
\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}
You can speed up some ffmpeg plugins that are quite time-consuming and use a lot of CPU\@. For a specific color-based example, \CGG{} uses 6 primary rendering color models. All of them have 3 components at full scale. Direct usage of a particular ffmpeg plugin from the ffmpeg command line might handle the planar at less than full scale chroma (yuv420), which means there is less data to manipulate. But when cinelerra loads a video it uses full scale color models. In other words:
\section{Audio Effects - Native}%
\label{sec:audio_effects_native}
\settocdepth{subsection}
+\index{audio!plugins}
\subsection{AudioScope}%
\label{sub:audioscope}
+\index{audioscope}
Effect rewritten and improved. Convert input audio to video output representing the audio power spectrum. Shows
% Yes
\subsection{Chorus}%
\label{sub:chorus}
+\index{chorus}
It is a multitrack effect, where each track is a channel. For example if you have 4 voices per channel and 2 channels, you will have a total of 8 tracks.
It is an effect that modulates the signal, varies the pitch up and down (instead of modulating the phases as for example in the \textit{Flanger} plugin) and creates voices from the original signal and adds them to the Output. You then get a chorus effect, with multiple voices \textit{singing} the same song but with slightly different modulations. Voices not only modulate the original signal but also start with a certain delay. There are two components of delay, \textit{constant delay} and \textit{oscillating delay} (figure~\ref{fig:chorus}).
\subsection{Compressor (Single Band)}%
\label{sub:compressor}
+\index{compressor}
The audio compressor reduces the dynamic range of the audio, not the amount of data required to store the audio. In \CGG{} the compressor actually performs the function of an expander and compressor of the signal's dynamic range. A third and more sophisticated use serves to highlight the voice with respect to the sound background. It is a multitrack effect and can also be applied as a Shared Effect. (figure~\ref{fig:compressor}).
\subsection{Compressor Multi (Multi Band)}%
\label{sub:compressor_multi}
+\index{compressor multi band}
Refer to Compressor (Single Band) for common theory and options.
The normal compressor acts over the entire frequency spectrum. The multi-band allows us to distinguish three frequency ranges (low, med and high) on which to intervene separately and in a more sophisticated way. In other plugins there are four bands instead of three, but we can make very precise adjustments so the three present are enough because they are not fixed. Finally the value of the three corrections are added together in the Output.
\subsection{DC Offset}%
\label{sub:dc_offset}
+\index{dc offset}
Use this to remove \textit{DC Offset}, which is usually an undesirable characteristic of a recording normally caused by defective equipment. This effect works like a \textit{high pass filter} and has no controls. DC stands for \textit{Direct Current} which is the average amplitude of the waveform. It sounds best when it is absent, represented by zero, so that there is no imbalance in the audio.
\subsection{Delay Audio}%
\label{sub:delay_audio}
+\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}
+\index{denoise}
Reduce audio background noise. There is only 1 parameter which is used to regulate the level dial with a range of 0 to 1.
\subsection{DenoiseFFT}%
\label{sub:denoisefft}
+\index{denoisefft}
+
+Audio sampling (time data) is converted to a frequency spectrum using FFT (\textit{Fast Fourier Transform}). Since the \textit{reference} contains only the background noise while the rest of the clip contains noise + audio to clean up, you get separate frequencies so you can subtract them to get the clean audio only. Set the Denoise Power dial in dB and choose the number of reference samples.
-Noise removal from audio using FFT editing. Set the Denoise Power dial in dB and choose the number of reference samples.
+For example, if you record a voice with a microphone\protect\footnote{credit fary54}:
+\begin{enumerate}
+ \item You record 15 seconds of background (without talking). This is represent the background noise that the filter uses as a reference.
+ \item After 15 seconds, start the voice. This is represents the recording whose filter should remove the background noise.
+ \item You stop recording.
+ \item You place the FFT effect on the whole length of the recording (including the 15 seconds of background noise).
+ \item Then place your cursor at the beginning of the 15 seconds. Enter the number of samples in the effect presets, e.g. 65536.
+\end{enumerate}
+
+This has the effect of creating a keyframe that marks the beginning of the reference range, mentioned in point 1, which in our example ends at 65536 samples later.
+
+During playback, the background noise is then automatically removed along the entire length of the effect.
\subsection{Despike}%
\label{sub:despike}
+\index{despike}
Detect and eliminate out of range impulse values.
\subsection{EQ Graphic}%
\label{sub:eq_graphic}
+\index{EQ graphic}
Graphic equalizer sets the output levels for specified frequency bands. This effect works by setting control points when you click the left mouse button and drag to the desired value. In the textboxes at the bottom can be seen the frequency of the active control point, the level of the signal to be set by entering the numerical value or by dragging the control point, and the number of samples to act on (figure~\ref{fig:equalizer}).
\subsection{EQ Parametric}%
\label{sub:eq_parametric}
+\index{EQ parametric}
Parametric equalizer shows and outputs levels for \textit{frequency}, \textit{quality}, \textit{level}, \textit{mode}, and \textit{wetness} (figure~\ref{fig:eq_param}).
\subsection{Echo}%
\label{sub:echo}
+\index{echo}
Echo is reflection of sound. This plugin could be used to add echoing to video of your canyon hike (figure~\ref{fig:echo}).
\subsection{EchoCancel}%
\label{sub:echocancel}
+\index{echo cancel}
EchoCancel is the process of removing echos from audio in order to improve the quality. Echo cancel may be needed because an audio recording was done in a room that led to echo generation or there was some kind of unwanted feedback. There are many controls for the EchoCancel plugin which are defined here. However, the first thing you will see when you bring up the plugin, is the top portion that is black which will show a + in the middle when you mouse over it. Once you start playing audio, you will see the cepstrum spectral data inside the window. A cepstrum results from taking the inverse Fourier transform (IFT) of the logarithm of the estimated spectrum of a signal. It is used to identify the period of the echo in the audio. It is recommended to just set the \textit{Mode} to On but the below defined parameters can be utilized by professionals (figure~\ref{fig:echo-cancel}).
\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.
\subsection{Flanger}%
\label{sub:flanger}
+\index{flanger}
It's a single-track effect. If you apply it to multiple tracks each will work on its own track independently of the others.
It consists of making a copy of the original sound wave and then playing it over the original one with a certain delay. The resulting signal (Output) will then be the sum of the two waves and will have peaks where the two values add up and gaps where the two values compensate each other. The result is a more \textit{evanescent} and \textit{metallic} sound. Much, however, depends on the intensity of the effect.
\subsection{Freeverb}%
\label{sub:freeverb}
+\index{freeverb}
Adds effect of multiple decaying echoes to audio signals based on a specific algorithm. Common use of reverb is to simulate music played in a closed room.
\subsection{Gain}%
\label{sub:gain}
+\index{gain}
Add gain, input level, to increase/decrease loudness.
\subsection{Interpolate}%
\label{sub:interpolate}
+\index{interpolate}
Generate a smooth curve based on sound creating a certain softness. There are no controls.
\subsection{Invert Audio}%
\label{sub:invert_audio}
+\index{invert audio}
Reverses the numerical sign of the digital audio. There are no controls.
\subsection{Live Audio}%
\label{sub:live_audio}
+\index{live audio}
The Live Audio effect reads audio directly from the sound card input. It replaces any audio on the track so it is normally applied to an empty track. To use Live Audio, highlight a horizontal region of an audio track or define In and Out points. Then drop the Live Audio effect into it. Create extra tracks and attach shared copies of the first Live Audio effect to the other tracks to have extra channels recorded. Live Audio uses the sound driver selected in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Playback A $\rightarrow$ Audio Out for recording}, but unlike recording it uses the playback buffer size as the recording buffer size and it uses the project sample rate as the sampling rate. These settings are critical since some sound drivers can not record in the same sized buffer they play back in.
\subsection{Loop Audio}%
\label{sub:loop_audio}
+\index{loop audio}
Loop some number of samples of audio over and over.
-\subsection{Overlay}%
-\label{sub:overlay}
+\subsection{Overlay (Audio)}%
+\label{sub: overlay}
+\index{overlay audio}
Overlay has parameter settings of top or bottom for the track and add or multiply for the operation.
\subsection{Pitch Shift}%
\label{sub:pitch_shift}
+\index{pitch shift}
Like the time stretching methods, there are three pitch shifting methods: \textit{Pitch shift}, \textit{Resample}, and \textit{Asset info} dialog. Pitch shift is a realtime effect which can be dragged and dropped onto recordable audio tracks. Pitch shift uses a fast Fourier transform (FFT) to try to change the pitch without changing the duration, but this introduces windowing artifacts. Because the windowing artifacts are less obtrusive in audio which is obviously pitch shifted, Pitch Shift is mainly useful for extreme pitch changes. For mild pitch changes, use Resample instead. Another way to change pitch slightly is to go to the Resources window, highlight the media folder, right click on an audio file, click on \textit{Info}, then adjust the sample rate in the Info dialog to adjust the pitch. This method also requires left clicking on the right boundary of the audio tracks and dragging left or right to correspond to the length changes.
\subsection{Remove Gaps}%
\label{sub:remove_gaps}
+\index{remove gaps}
Remove silent gap (below $DB$ threshold) which persist for more than the time limit.
\subsection{ResampleRT}%
\label{sub:resamplert}
+\index{resampleRT}
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 \\
\subsection{Reverb}%
\label{sub:reverb}
+\index{reverb}
Reverb uses reflections of sound to add depth and fullness; the sound will seem to come from a space that can go from a small bare room to large natural valleys, cathedrals, etc. The reverb is made up of a group of echoes that occur at the same time making it feel like a single effect.
Basically simulates creation of a large number of reflections, like lots of walls, which build up and then decay. You can use the reverb plugin to mix tracks together to simulate ambiance because it is a multitrack effect.
\subsection{Reverse Audio}%
\label{sub:reverse_audio}
+\index{reverse audio}
Apply reverse audio to an audio track and play it backwards. The sound plays forward. Be aware when reversing audio that the waveform on the timeline does not reflect the actual reversed output.
\subsection{SoundLevel}%
\label{sub:soundlevel}
+\index{sound level}
Effect rewritten and improved to handle fragments. Displays the Max/RMS sound level in decibels.
\subsection{Spectrogram}%
\label{sub:Spectrogram}
+\index{spectrogram}
Effect rewritten and improved. Visual representation of the sound levels at specified frequencies as they vary with time.
\subsection{Synthesizer}%
\label{sub:Synthesizer}
+\index{synthesizer}
Generate synthesizer sounds; to set key data, turn on Generate keyframes while tweaking (figure~\ref{fig:synthesizer}).
\subsection{Time Stretch RT}%
\label{sub:time_stretch_rt}
+\index{time stretch RT}
Change the speed of an audio signal without affecting its pitch.
\subsection{Tremolo}%
\label{sub:tremolo}
+\index{tremolo}
It serves to give various vibes and vitality to the sound by modulating the amplitude of the sound signal and the delay (figure~\ref{fig:tremolo}).
\section{Audio Ladspa Effects}%
\label{sec:audio_ladspa_effects}
\settocdepth{section}
+\index{ladspa}
Ladspa effects are supported in realtime and rendered mode for audio. These audio effects are supported since \CGG{} implements the LADSPA interface as accurately as possible. Besides the supplied LADSPA effects\protect\footnote{credit Steve Harris}, additional LADSPA effects can be enabled by setting the \texttt{LADSPA\_PATH} environment variable to the location of your LADSPA plugins:
export LADSPA_PATH=/usr/lib/ladspa
\end{lstlisting}
-\section[Audio LV2 / Calf Plugins]{Audio LV2 / Calf Plugins\protect\footnote{Optional Feature - OS dependent}}%
+\section[Audio LV2 / Calf Plugins]{Audio LV2 / Calf Plugins}%
\label{sec:audio_lv2_calf_plugins}
+\index{LV2 - Calf}
-LV2 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.
+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.
\texttt{Settings $\rightarrow$ Preferences $\rightarrow$ tab Playback A $\rightarrow$ section Audio Out $\rightarrow$ variable Playback buffer samples}
However, be forewarned that due to variability in the lv2 plugin programming code, some of the plugins only work with the minimum buffer size of $1024$. In these cases, what you will see is the main track canvas cursor just bounces back and forth over a very small area in the timeline. This does not crash \CGG{} but you will have to remove the plugin to continue working.
-You can specify a certain set of LV2 plugins to use by setting \texttt{LV2\_PATH} as shown below before starting \CGG{} -- include a colon ($:$) separator for multiple paths. The default path for most operating systems is \texttt{/usr/lib64/lv2}. To list the system installed lv2 plugins key in: \texttt{lv2ls}.
+You can specify a certain set of LV2 plugins to use by setting \texttt{LV2\_PATH} \index{LV2 path} as shown below before starting \CGG{} -- include a colon ($:$) separator for multiple paths. The default path for most operating systems is \texttt{/usr/lib64/lv2}. To list the system installed lv2 plugins key in: \texttt{lv2ls}.
\begin{lstlisting}[numbers=none]
export LV2_PATH=/tmp/j/balance.lv2/usr/local/lib/lv2/:/usr/local/lv2
When you change this field, cin will automatically restart and load the newly specified lv2 plugins. If when switching \texttt{LV2\_PATH} or if the lv2 audio plugins are not displayed/usable in the Resources window, you can execute a reload via:
-\texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface tab $\rightarrow$ Reload plugin in\-dex}
+\texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Interface tab $\rightarrow$ Reload plugin index} \index{plugins!reload index}
or else before you bring up \CGG{}, delete \texttt{\$HOME/.bcast5/\CGG{}\_\\plugins} so that the plugins get properly reloaded.
There are some lv2 plugins that display a \textit{glitzy} UI (User Interface); for example the \textit{Calf plugins}. For these LV2 plugins, if you want that to automatically come up without having to click on the UI button on the simplified UI interface, there is a flag to enable that. It is at:
\section[Video Effects --- Native]{Video Effects -- Native}%
\label{sec:video_effects_native}
\settocdepth{subsection}
+\index{video!plugins}
\subsection{1080 to 480}%
\label{sub:1080_to_480}
+\index{1080 to 480}
Most TV broadcasts are received with a $1920\times1080$ resolution but originate from a $720\times480$ source at the studio. It is a waste of space to compress the entire $1920\times1080$ if the only resolvable details are $720\times480$. Unfortunately resizing $1920\times1080$ video to $720\times480$ is not as simple as shrinking it.
\subsection{1080 to 540}%
\label{sub:1080_to_540}
+\index{1080 to 540}
Extracts two $1920\times540$ fields from $1920\times1080$ image, resizes them separately, and combines them to $1920\times540$ interlaced image.
\subsection{Aging TV}%
\label{sub:aging_tv}
+\index{Aging TV}
This effect is the one to use if you want to achieve an old movie or TV show look. It will put moving lines up and down the movie as well as putting snow on the video. Use it along with \textit{Brightness/Contrast} and \textit{Color Balance} to make your movie look like a really old black and white movie. This came from \url{https://effectv.com}.
\subsection{Alpha}%
\label{sub:alpha}
+\index{Alpha}
-Allows you to apply an alpha value (transparency) to one or more tracks or one or more edits. Being also keyframable, it allows an excellent variety and possibility of use in the most disparate occasions.
+Allows you to apply an alpha value (transparency) to one or more tracks or one or more edits. You can use the slider or have maximum precision by entering numbers in the input box. You can use the \textit{Clear} button to reset to the default value. Being also keyframable, it allows an excellent variety and possibility of use in the most disparate ways.
\subsection{Auto Scale}%
\label{sub:auto_scale}
+\index{auto scale}
Automatically scale to a specified size.
\subsection{Blue Banana}%
\label{sub:blue_banana}
+\index{blue banana}
-Blue Banana\protect\footnote{credit to Monty Montgomery programmer} is an \textit{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}
\subsection{Blur}%
\label{sub:blur}
+\index{blur}
This is a Gaussian type blur. Other blur plugins -- \textit{Linear}, \textit{Motion}, \textit{Radial}, and \textit{Zoom} --are described later. This plugin is keyframable. Blur is used to blur a video track via the following parameters:
\begin{description}
\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}
+\index{boxblur}
+
Based on ffmpeg’s boxblur, this is a very fast algorithm which can be used to blur horizontal,
vertical, and at a power level. Simplest usage is to just blur the entire image but with
the following parameters, you can create a specific rectangular section to blur instead.
\subsection{Brightness/Contrast}%
\label{sub:brightness_contrast}
+\index{brightness contrast}
\begin{figure}[htpb]
\centering
To brighten a dark shot, or add light, use this plugin. Do not overuse the effect or you risk degrading your video quality.
The \textit{Brightness} slider moves up or down the values of the entire channel and corresponds to the \textit{Master Offset} of the various grading programs.
-The \textit{Contrast} slider expands or narrows the brightness values of the entire channel; corresponds to the use of the \textit{cursors} (small triangles) in the \textit{Histogram} plugin. Clear icons are present to reset its slider to default without affecting others.
+The \textit{Contrast} slider expands or narrows the brightness values of the entire channel; corresponds to the use of the \textit{cursors} (small triangles) in the \textit{Histogram} plugin. For maximum precision you can use the input box. \textit{Clear} icons are present to reset its slider to default without affecting others.
Use the effect along with keyframing to brighten a long shot that is dark at the beginning but bright at the end. Generally you will want to change the brightness and contrast about the same amount (for example -- brightness $28$, contrast $26$) so that your original colors are kept intact. This effect is also keyframable (figure~\ref{fig:brightness}).
\subsection{BurningTV}%
\label{sub:burningtv}
+\index{burning TV}
Makes your video burn where there are small light colored patches of video. This came from \url{https://effectv.com}.
-\subsection[C41]{C41\protect\footnote{credit Florent Delannoy, original program code author, and Edouard Chalaron}}%
+\subsection[C41]{C41}%
\label{sub:c41}
+\index{C41}
-The C41 plugin takes a $16\,bit C41$ digital intermediate negative film as input and outputs a positive image. It became necessary because $C-41$ negatives can fade or color-shift over time which was a problem early on. It is still important today because there is a large amount of documentaries, video clips, and other media out there that was shot on super $16$ film. This works for RGB-float, RGB, and also YUV variations.
+The C41\protect\footnote{credit Florent Delannoy, original program code author, and Edouard Chalaron} plugin takes a $16\,bit C41$ digital intermediate negative film as input and outputs a positive image. It became necessary because $C-41$ negatives can fade or color-shift over time which was a problem early on. It is still important today because there is a large amount of documentaries, video clips, and other media out there that was shot on super $16$ film. This works for RGB-float, RGB, and also YUV variations.
There are two sets of data -- the scanned input values and your corrected values. Simple functionality of the plugin is to compute the data, transform to get corrected values, then apply that.
\subsection{Chroma Key}%
\label{sub:chroma_key}
+\index{chroma key}
This effect erases pixels which match the selected color. They are replaced with black if there is no alpha channel and transparency if there is an alpha channel. In this case, you create a matte in the alpha channel, which is not visible to us. The selection of color model is important to determine the behavior (figure~\ref{fig:chroma-key}).
\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.
Normally threshold is very low when using a high slope. The two parameters tend to be exclusive because slope fills in extra threshold. The slope tries to soften the edges of the chroma key but it does not work well for compressed sources. A popular softening technique is to use a maximum slope and chain a blur effect below the chroma key effect to blur just the alpha.
-\subsection[Chroma Key (HSV)]{Chroma Key (HSV)\protect\footnote{Credit for Plugin by Jerome Cornet \url{http://jcornet.free.fr/linux/chromakey.html}}}%
+\subsection[Chroma Key (HSV)]{Chroma Key (HSV)}%
\label{sub:chroma_key_hsv}
+\index{chroma key HSV}
-Chroma Key (HSV) (figure~\ref{fig:chroma-key-hsv}) replaces a color with another color or transparency using HSV variables; it is frequently used to remove a color from a video to composite with another image. This process is generally referred to as green screen or blue screen process (because of the color that is keyed out). More information: {\small \url{http://en.wikipedia.org/wiki/Chromakey}}
+Chroma Key (HSV)\protect\footnote{Credit for Plugin by Jerome Cornet \url{http://jcornet.free.fr/linux/chromakey.html}} (figure~\ref{fig:chroma-key-hsv}) replaces a color with another color or transparency using HSV variables; it is frequently used to remove a color from a video to composite with another image. This process is generally referred to as green screen or blue screen process (because of the color that is keyed out). More information: {\small \url{http://en.wikipedia.org/wiki/Chromakey}}
\begin{figure}[htpb]
\centering
\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}
\subsection{Color 3 Way}%
\label{sub:color_3_way}
+\index{color 3 way}
Together with \textit{Histogram Bezier / Curves} Color 3 Way is the main tool of Color Grading because you can modify the colors of \textit{Shadows}, \textit{Midtones}, and \textit{Highlights} as desired. Color 3 Way is keyframable (figure~\ref{fig:color3way}).
\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}
Video Color Balance is a great effect to use along with Brightness/Contrast and Hue/saturation to try to compensate for possible errors in filming (low lighting, for example). It can do so much without greatly lowering the quality of the video. With it you can change the colors being sent to output \textit{CMY} (Cyan, Magenta, Yellow) or \textit{RGB} (Red, Green, Blue). Color Balance is also keyframable.
\subsection{ColorSpace}%
\label{sub:color_space}
+\index{color space}
This plugin is a tool that can be used to convert your input media, such as a recording from your camera,
from one color space/range to another. It works for both RGB and YUV as set by your project format.
\subsection{CriKey}%
\label{sub:crikey}
+\index{CriKey}
The Chroma Interpolation Key plugin, CriKey, is a regionally based chroma key with interpolation (figure~\ref{fig:crikey}). This is useful when you only want 1 or some specific zones to be defined by the chroma key as opposed to the entire image. Its most significant feature is that you can select several regions of interests and of different colors as opposed to only $1$.
\subsection{Crop \& Position}%
\label{sub:crop_position}
+\index{crop \& position}
It allows you to obtain a rectangle from the frame, whose dimensions are fully adjustable by four sliders for the four sides of the frame. You can also place this rectangle in the canvas using two other sliders for right/left and up/down scrolling. With the Clear buttons we can bring the slider to default values without affecting the other parameters. Unlike the \textit{Crop} tool, the original frame size is not altered and being keyframable allows a wide variety of uses. In figure~\ref{fig:crop_position} the Crop \& Position plugin is compared with the \textit{Crop} tool.
\subsection{DeScratch}%
\label{sub:descratch}
+\index{descratch}
The descratch video plugin can be used to remove vertical scratches
from film. It can also be used, after image rotation, to remove
\subsection{Decimate}%
\label{sub:decimate}
+\index{decimate}
This is used to decrease the frame rate of a video. Changing the frame rate means eliminating a frame for any given number of frames ($1 in N$); but if frames that are important for visual continuity are deleted, temporal artifacts arise: flickering, slowdowns, accelerations, etc. The Decimate filter maintains a higher quality because it first eliminates duplicate frames or frames that are most similar, thus limiting the appearance of artifacts. It is often used after the \textit{Invert Telecine} plugin to make the video more smooth.
\subsection{Deinterlace}%
\label{sub:deinterlace}
+\index{deinterlace}
The deinterlace effect has evolved over the years to deinterlacing and a whole lot more. In fact two of the deinterlacing methods, \textit{Inverse Telecine} and \textit{Frames to Fields}, are separate effects. The deinterlace effect offers several variations of line replication to eliminate comb artifacts in interlaced video. It also has some line swapping tools to fix improperly captured video or make the result of a reverse effect display fields in the right order.
\subsection{Deinterlace-CV}%
\label{sub:deinterlace_cv}
+\index{deinterlace-cv}
Selection of deinterlacing mode for your video to eliminate comb artifacts (figure~\ref{fig:deinterlace}).
\subsection{Delay Video}%
\label{sub:delay_video}
+\index{delay video}
Delay the video by some number of seconds.
\subsection{Denoise Video}%
\label{sub:denoise_video}
+\index{denoise video}
Denoise video (figure~\ref{fig:denoise}).
\subsection{Difference key}%
\label{sub:difference_key}
+\index{difference key}
The difference key creates transparency in areas which are similar between two frames. The Difference key effect must be applied to two tracks. One track contains the action in front of a constant background and another track contains the background with nothing in front of it. Apply the difference key to the track with the action and apply a \textit{shared effect} of it to the track with the background. The track with the background should be muted and underneath the track with the action and the color model should have an alpha channel. It’s hard to get good results.
\subsection{DotTV}%
\label{sub:dottv}
+\index{dotTV}
Puts various size dots over the picture to simulate TV effect. This came from: {\small \url{https://effectv.com}}.
\subsection{Downsample}%
\label{sub:downsample}
+\index{downsample}
Downsampling is the process of reducing the size of an image by throwing out data, reducing sampling rate.
\subsection{Edge}%
\label{sub:edge}
+\index{edge}
Display only the edges of the video throughout the image.
\subsection{Fields to frames}%
\label{sub:fields_to_frames}
+\index{fields to frame}
See the theory description in the \textit{Frames to Fields} plugin. This effect reads frames at twice the project framerate, combining two input frames into a single interlaced output frame. Effects preceding fields to frames process frames at twice the project frame rate. Each input frame is called a field.
\subsection{Flip}%
\label{sub:flip}
+\index{flip}
This effect flips a video track either vertically or horizontally.
\subsection{Foreground}%
\label{sub:foreground}
+\index{foreground}
-Whatever the visual content of the frame, the Foreground plugin application applies a uniform color that can be chosen by color picker; color wheel; color presets; the various HSV, RGB, YUV sliders or by entering the hexadecimal value. The alpha slider is not missing either.
+Whatever the visual content of the frame, the Foreground plugin application applies a uniform color that can be chosen by color picker, color wheel, color presets, or by entering the hexadecimal value.
+In addition there are HSV, RGB, YUV, and alpha sliders to vary the color accordingly.
\subsection{Frames to fields}%
\label{sub:frames_to_fields}
+\index{frames to fields}
\subsubsection*{Theory behind the Frames to Fields and Fields to Frames plugins}
\label{ssub:theory_frames_fields}
\subsection{Freeze Frame}%
\label{sub:freeze_frame}
+\index{freeze frame}
In its simplest form, highlight a region of the track to freeze, drop the \texttt{freeze frame} effect on the highlighted region, and the lowest numbered frame in the affected area will play throughout the entire region. Freeze Frame has an enabled option which can be keyframed. Regions of a freeze frame effect which are enabled, repeat the lowest numbered frame since the last keyframe. This has unique possibilities.
\subsection{Gamma}%
\label{sub:gamma}
+\index{gamma}
\textit{Log} camera images store colors in a $logarithmic$ scale. The blacks in these images are nearly $0$ and the whites are supposed to be infinity. The graphics card and most video codecs store colors in a $linear$ scale but \CGG{} keeps log camera images in their original logarithmic scale when it renders them. This is necessary because the raw image parser can not always decode the proper gamma ($\gamma$) values for the images. It also does its processing in $16\,bit$ integers, which takes away a lot of information.
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}
\subsection{Gradient}%
\label{sub:gradient}
+\index{gradient}
The \textit{gradient} effect overlays a smooth color gradient on top of every video frame. It is useful for all sorts of background fills, for partially filtering, adding depth to the image, or for adding moving highlights. The Gradient effect can generate linear or circular color fills / shape. For linear fills, you can choose the \textit{angle}, for circular fills the \textit{center $(X,Y)$} of the created gradient pattern. You can control the \textit{slope} of the color transition by selecting a transition function ($linear$, $logarithmic$, $squared$) and by changing the start (\textit{inner}) and stop (\textit{outer}) radius. Note that both colors used in this color transition can contain an arbitrary \textit{Alpha} value (transparency). All parameters can be keyed and will be interpolated between keyframes.
\textit{Note:} The inner and outer colors are visibly mixed in the gradient area. If you want to make a vignetting of only black, you must set the two colors to black and then make the inner one transparent so that it does not cover the figure.
-\subsection{HistEq}%
+\subsection{HistEQ}%
\label{sub:histeq}
+\index{histEQ}
Remap colors using blended histogram weights. Figure~\ref{fig:histeq} shows the GUI and the results in a split screen.
\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.
\subsection{Histogram}%
\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. A practical case may be the shooting of a room illuminated by a lamp and then with the light off. We can choose only the range of illuminated frames and then we will have the whole shot illuminated. Or we can choose only the dark frames and so we will have all the dark shot.
-
+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:}
+
+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:
+
+$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[Scopes:] always uses 65536
+\end{description}
+
+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 (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}
+
+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}
+
+This diversity also leads to different visual results from Histogram Bezier or Videoscope.
+
+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}{clccr}
+ \hline
+ 1 & & & & \\
+ 1 & & & 1 & \\
+ 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 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}).
Curves are generally adjusted by introducing several control points, some to be kept fixed (as anchors) to prevent curve modification beyond them, and others to be dragged to make the desired correction. The power of the curves lies in being able to circumscribe a small interval at will and intervene only on this without involving the remaining parts of the frame. The precision with which you can work is such that you can almost arrive at a secondary color correction.
-\begin{figure}[htpb]
- \centering
- \includegraphics[width=0.8\linewidth]{ex-bezier.png}
- \caption{Gain Up/Down; clamp; S-Shaped curve and Luma Key}
- \label{fig:ex-bezier}
-\end{figure}
-
-
The most used type of modification is to create a \textit{S curve}. There can be a lot of shapes that use the S curve; the simplest is to create a control point in the shadows, one in the midtones (anchors) and one in the highlights. Moving the highlight point upwards and the shadow point downwards increases the contrast, making the image sharper and improving the color rendering. With the type of \textit{linear} curve you can make hard adjustments, similar to the result of the use of \textit{Color 3 Way}, even if this acts on the color wheel (Hue) while the curves act on individual RGB channels.
-The \textit{Polynomial} and \textit{Bézier} types introduce \textit{control handles} that allow for more sophisticated and smoother adjustments. The quality of the result is much better, but they require more experience for their optimal use. Extending the handles away from the control point increases the \textit{radius} of the curve at that point. By varying the angle of the handles we change the \textit{tangent} and thus the curvature of the curve below. The difference between Polynomial and Bézier lies in the underlying mathematics, but for practical purposes the use is similar.
+The \textit{Polynomial} and \textit{Bézier} types introduce \textit{control handles} that allow for more sophisticated and smoother adjustments. The quality of the result is much better, but they require more experience for their optimal use. By varying the angle of the handles we change the \textit{tangent} and thus the slope of the curve below. Unlike true Bezier curves, there is no effect in extending the handles: there is no change in the radius of the curve. The difference between Polynomial and Bézier lies in the underlying mathematics, but for practical purposes the use is similar. By default Bézier starts with a slight S-curve, as opposed to Polynomial.
Some examples of the use of curves to demonstrate the variety of possible interventions (figure~\ref{fig:ex-bezier}):
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.8\linewidth]{ex-bezier.png}
+ \caption{Gain Up/Down; clamp; S-Shaped curve and Luma Key}
+ \label{fig:ex-bezier}
+\end{figure}
+
\begin{itemize}
\item Scale the image values by increasing the white point or decreasing the white point (gain up and gain down).
You can decide the scaling value with the formula: $(Input \div Output) = Scale Factor$
\subsection{HolographicTV}%
\label{sub:holographictv}
+\index{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. 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}).
+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}
+\index{hue saturation}
-With this effect you can change hue, saturation and value. The parameters are modified using 3 simple sliders. The \textit{hue} control shifts the colors circularly in the color plane, normally resulting in false colors. The \textit{saturation} control can be used to reduce color footage to black and white. The \textit{value} control makes any given colors more bright or more subdued. Clear buttons are present to reset its slider to default without affecting others.
+With this effect you can change hue, saturation and value. The parameters are modified using 3 simple sliders. For maximum precision you can use the input box. The \textit{hue} control shifts the colors circularly in the color plane, normally resulting in false colors. The \textit{saturation} control can be used to reduce color footage to black and white. The \textit{value} control makes any given colors more bright or more subdued. \textit{Clear} buttons are present to reset its slider to default without affecting others.
\subsection{Interpolate Bayer}%
\label{sub:interpolate_bayer}
+\index{interpolate bayer}
Uses a Bayer filter algorithm to interpolate (estimate) missing color information. This is needed for some cameras where each pixel location only has an R or G or B value instead of all R, G, and B values for each location. The algorithm creates values for each of the three colors at every location by smearing (interpolating) each set of partial R, G and B values to create values at every pixel location.
\subsection{Interpolate Video}%
\label{sub:interpolate_video}
+\index{interpolate video}
\subsubsection*{Theory}
\label{ssub:theory}
\subsection{Inverse Telecine}%
\label{sub:inverse_telecine}
+\index{inverse telecine}
This is the most effective deinterlacing tool when the footage is a video transfer of a film. This can be used to solve the problem, i.e., undo the damage caused by making film into a TV broadcast.
That process came about because film is at 24\,\emph{fps} while TV is at 29.97\,\emph{fps} and fields are at 60.
\subsection{Invert Video}%
\label{sub:invert_video}
+\index{invert video}
Invert video is a method of reversing the colors of a video track. The four parameters refer to channels -- \textit{Red}, \textit{Blue}, \textit{Green}, \textit{Alpha}. A very common use is to invert the alpha channel to change transparency.
\subsection{Lens}%
\label{sub:lens}
+\index{lens}
Create the effect of looking through a lens.
\subsection{Linear Blur}%
\label{sub:linear_blur}
+\index{linear blur}
This effect acts only in one direction which can vary up to an angle of $180\degree$ with these parameters:
\end{figure}
\begin{description}
- \item[Lenght:] distance between original image and final blur step; corresponds to the distance of the fields.
+ \item[Length:] distance between original image and final blur step; corresponds to the distance of the fields.
\item[Angle:] angle of motion in one direction for linear blur
\item[Steps:] number of blur steps to be used in the calculation. Increasing the number takes more CPU.
\item[Channels:] R,G,B,A.
\item[Clear] With the Clear buttons we can bring the slider to default values without affecting the other parameters.
\end{description}
+For maximum precision you can use the input box.
Figure~\ref{fig:linear} shown here has the parameters: $Length=19$, $Angle=25$, and $Steps=2$.
\subsection{Live Video}%
\label{sub:live_video}
+\index{live video}
This effect reads video directly from the capture card input. It replaces any video on the track so it is normally applied to an empty track. Only one \textit{Live Video} effect can exist at any time on the timeline. It can not be shared by more than one track. The configuration for the capture card is taken from the recording preferences. Go to \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Recording} to set up the capture card.
\subsection{Loop video}%
\label{sub:loop_video}
+\index{loop video}
Sections of video can be looped by dropping a loop effect on them. Contrary to the \texttt{settings $\rightarrow$ loop playback} option, the loop effects can be rendered where the \texttt{settings $\rightarrow$ loop playback} option can not be. The loop effects are also convenient for short regions.
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.
\subsection{Motion}%
\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.
To save time the motion result can be saved in a file for later reuse, recalled from a previous calculation, or discarded. The motion tracker has a notion of $2$ tracks, the \textit{master} layer and the \textit{target} layer. The \textit{master} layer is where the comparison between $2$ frames takes place. The \textit{target} layer is where motion is applied either to track or compensate for the motion in the \textit{master} layer (figure~\ref{fig:motion}).
\begin{figure}[ht]
- \centering
- \includegraphics[width=0.9\linewidth]{motion.png}
+ \centering
+ \includegraphics[width=0.99\linewidth]{motion.png}
\caption{Motion plugin GUI}
\label{fig:motion}
\end{figure}
-Motion tracking parameters:
+Motion tracking parameters\protect\footnote{credit Georgy (sge)}:
\begin{description}
\item[Track translation] Enables translation operations. The motion tracker tracks $X$ and $Y$ motion in the \textit{master} layer and adjusts $X$ and $Y$ motion in the \textit{target} layer.
\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}
\subsection{Motion 2 Point}%
\label{sub:motion_2_point}
+\index{Motion 2 Point}
-Motion stabilization using 2 pass tracking. For theory and explanations refer to the \hyperref[sub:motion]{Motion} plugin.
+Motion plugin using 2 \textit{Match box} for tracking. For theory and explanations refer to the \hyperref[sub:motion]{Motion} plugin.
\subsection{Motion Blur}%
\label{sub:motion_blur}
+\index{Motion Blur}
Uses X/Y camera automation vectors to apply a linear blur trailing camera direction due to movement.
\begin{description}
\subsection{Oil painting}%
\label{sub:oil_painting}
+\index{oil painting}
This effect makes video tracks appears as a painting. It can be controlled by \textit{Radius} slider and \textit{intensity of colors} can be chosen as an option.
-\subsection{Overlay}%
+% Leave the Video and Audio parenthesis due to latex2html dual conflict
+\subsection{Overlay (Video)}%
\label{sub:overlay}
+\index{overlay video}
+
+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.
-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.
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}
The \textit{perspective} plugin (aka Corner Pinning) allows you to change the perspective of an object and is used to make objects appear as if they are fading into the distance. Basically, you can get a different view. A transformation is used which preserves points, lines, and planes as well as ratios of distances between points lying on a straight line.
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.
\subsection{Polar}%
\label{sub:polar}
+\index{polar}
+
+The \textit{Polar} effect bends and warps your video in weird ways. Mathematically, it converts your video from either \textit{polar} coordinates to \textit{rectangular} coordinates, or the reverse. For maximum precision you can use the input box. With the \textit{Clear} buttons we can bring the slider to default values without affecting the other parameters.
-The \textit{Polar} effect bends and warps your video in weird ways. Mathematically, it converts your video from either \textit{polar} coordinates to \textit{rectangular} coordinates, or the reverse. With the Clear buttons we can bring the slider to default values without affecting the other parameters.
+\subsection{Posterize}%
+\label{sub:posterize}
+\index{posterize}
+
+Reduces the color depth so as to decrease the displayed color gradients, up to the bands typical of posterization. It is used by setting the number of \textit{steps} from 0 to 255.
\subsection{RGB-601}%
\label{sub:rgb-601}
+\index{rgb-601}
For analog video or MPEG (including DVD) output, the maximum range for R,G,B is $[16,235]$ ($8\,bit$). For YUV, the maximum range for intensity (\textit{Y}) is $[16, 235]$ ($8\,bit$). This range corresponds to gray levels from $6\%$ to $92\%$. When rendering, values outside of these ranges will be clipped to these limits.
\subsection{RGBShift}%
\label{sub:rgb-shift}
+\index{rgb shift}
-Most cameras take the light coming into the lens, and convert that into $3$ sets of numbers, one for Red (R), one for Green (G), and one for Blue (B). Some of the older cameras were composed of $3$ sensors and originally the RGB sensors were on $3$ separate planes and had to be aligned. If they were misaligned in the video, you can use \textit{RGBShift} to get them realigned. To move a specific color up/down, modify the \textit{dy} value using the slider bar in the RGBShift window. To move a color left/right, modify the corresponding \textit{dx} value. Clear buttons are present to reset its slider to default without affecting others. Note that the current values of the RGBShift are maintained in the \texttt{.bcast5} defaults file and will be retained across sessions. If using the YUV color space, you will want to use \textit{YUVShift} instead. Figure~\ref{fig:rgbshift} showing RGB shift before and after.
+Most cameras take the light coming into the lens, and convert that into $3$ sets of numbers, one for Red (R), one for Green (G), and one for Blue (B). Figure~\ref{fig:rgbshift} showing RGB shift before and after.
\begin{figure}[hbtp]
- \centering
- \includegraphics[width=0.8\linewidth]{rgbshift.png}
- \caption{Bad Misaligned color and after color aligned}
- \label{fig:rgbshift}
+ \centering
+ \includegraphics[width=0.8\linewidth]{rgbshift.png}
+ \caption{Bad Misaligned color and after color aligned}
+ \label{fig:rgbshift}
\end{figure}
+Some of the older cameras were composed of $3$ sensors and originally the RGB sensors were on $3$ separate planes and had to be aligned. If they were misaligned in the video, you can use \textit{RGBShift} to get them realigned. To move a specific color up/down, modify the \textit{dy} value using the slider bar in the RGBShift window. To move a color left/right, modify the corresponding \textit{dx} value. For maximum precision you can use the input box. \textit{Clear} buttons are present to reset its slider to default without affecting others. Note that the current values of the RGBShift are maintained in the \texttt{.bcast5} defaults file and will be retained across sessions. If using the YUV color space, you will want to use \textit{YUVShift} instead.
+
+
\subsection{Radial Blur}%
\label{sub:radial_blur}
+\index{radial blur}
Radial blur is a \textit{Bokeh} effect that creates a whirlpool which simulates a swirling camera. You can vary the location, type, and quality of the blur.
\item[Clear] to reset its slider to default without affecting others.
\end{description}
+For maximum precision you can use the input box.
Figure~\ref{fig:radial} has the parameters: $Angle=-35$ and $Steps=2$.
\subsection{ReframeRT}%
\label{sub:reframert}
+\index{reframeRT}
ReframeRT changes the number of frames in a sequence of video
directly from the timeline. The faster method for getting the same
varying the framerate. It is important to understand that the
plugin works by varying the frames, the possible change of
\textit{fps} is only a side effect of the creation of new frames due
-to interpolation.
+to interpolation. The interpolation algorithm is simply the slope of a linear curve. This plugin is keyframable and the \textit{Interpolate} option works between keyframes. A simpler and more handy version is the \textit{Speed PerCent} plugin.
\subsubsection*{Stretch}%
\label{ssub:stretch}
+\index{stretch}
Stretch mode multiplies the current frame number of its output by the \textit{scale factor} to arrive at the frame to read from its input. The scaling factor is not entered directly but using a number of \textit{input} frames to be divided by the number of \textit{output} frames.
\textit{Example:} you have a clip that you want to put in slow motion. The clip starts at $33.792\, seconds$ and ends at $39.765$. The clip is $5.973\, seconds$ long. You want to play it at $\frac{4}{10}^{ths}$ normal speed. You divide the clip length by the playback speed ($5.973\div0.4$) to get a final clip length of $14.9325\,seconds$. You create an in point at the start of your clip: $33.792\,seconds$. You put an out point $14.9325\,seconds$ later, at $48.7245\,seconds$ ($33.792 + 14.9325$). You attach a \texttt{ReframeRT} effect, set it to $0.4$ and stretch. You change the out point at $48.7245$ to an in point. You start your next clip after the slow motion effect at the $48.7245$ out point. You can do this without making any calculations by first applying the effect and then lengthening or shortening the bar to where the stretched movie ends.
-Now in the timeline we have the affected part of the plugin where we see the slow/fast effect, and the continuation of the timeline from where the plugin ends. We then have to select the interval on which the plugin acts and render it or transform it into a nested clip or nested asset. In this way we can replace or overlap it with the part of the timeline that originally included all of the part we wanted to slow down/speed up.
+Now in the timeline we have the affected part of the plugin where we see the slow/fast effect, and the continuation of the timeline from where the plugin ends. We then have to select the interval on which the plugin acts and render it or transform it into a nested clip or nested asset. In this way we can replace or overlap it with the part of the timeline that originally included all of the part we wanted to slow down/speed up. See also the \textit{Reframe} render effect for direct rendering.
\subsubsection*{Downsample}%
\label{ssub:downsample}
+\index{downsample}
Downsample mode does not change the length of the output sequence. It multiplies the frame rate of the output by the scale factor to arrive at a frame rate to read the input. This has the effect of replicating the input frames so that they only change at the scaled frame rate when sent to the output. It does not change the length of the sequence. If the scale factor is $0.5$ and the output frame rate is $30 \,fps$, only $15$ frames will be shown per second and the input will be read at $15 \,fps$. Downsample is only useful for scalefactors below $1$, hence the name downsample.
\begin{itemize}
\item ReframeRT uses the fps indicated in \texttt{Settings $\rightarrow$ Format $\rightarrow$ fps} project and not the \texttt{fps} of the assets.
\item It can be associated with Nested Clips.
- \item As an alternative to ReframeRT you can use the \textit{speed curve}, or change the framerate in \texttt{Resources $\rightarrow$ info} and in the \texttt{Project}.
+ \item As an alternative to ReframeRT you can use the \textit{speed curve}, or change the framerate in \texttt{Resources $\rightarrow$ info} and in the \texttt{Project}; or using \textit{Reframe} render effect, or using \textit{Speed PerCent} plugin.
\item It is keyframmable.
\item ResampleRT with the same settings is used to act on audio tracks.
\end{itemize}
\subsection{Reroute}%
\label{sub:reroute}
+\index{reroute}
-The \textit{Reroute} plugin enables you to selectively transfer the Alpha channel or the Components (RGB or YUV) or both from a \textit{source} track to a \textit{target} track, partially overwriting the target's contents. It works as a \textit{shared plugin}. The typical usage scenario is to build up a possibly animated Mask in one track and then to transfer the Alpha channel to another content track.
+The \textit{Reroute} plugin\protect\footnote{By Hermann Vosseler} enables you to selectively transfer the Alpha channel or the Components (RGB or YUV) or both from a \textit{source} track to a \textit{target} track, partially overwriting the target's contents.
+
+\begin{description}
+ \item[Target Track:] you can choose between \textit{Top} and \textit{Bottom}.
+ \item[Operation:] you can choose between \textit{Replace Target} (component + alpha channels); \textit{Components Only} (color channels only) and \textit{Alpha Replace} (alpha channel only)
+\end{description}
+
+It works as a shared plugin. The typical usage scenario is to build up a possibly animated Mask in one track and then to transfer the Alpha channel to another target track.
\subsection{Reverse video}%
\label{sub:reverse_video}
+\index{reverse video}
Media can be reversed on the timeline in realtime. This is not to be confused with using the reverse playback on the transport panel. The \texttt{reverse} effects reverse the region covered by the effect regardless of the transport direction. The region to be reversed is first determined by what part of the track the effect is under and second by the locations of keyframes in the effect. The reverse effects have an enabled option which allows you to set keyframes. This allows many possibilities.
\subsection{Rotate}%
\label{sub:rotate}
+\index{rotate}
The \textit{Rotate} filter can rotate the video in $90$ degree increments or by any number of degrees through use of the \textit{wheel} and about any \textit{pivot point}. It can also reverse and flip the video.
\subsection{Rumbler}%
\label{sub:rumbler}
+\index{rumbler}
The \textit{Rumbler} plugin can be used to create dream-like or earthquake-like noise in the video. It creates noise by jiggling the corners through use of perspective transformation at the corners. The algorithm used is:
\subsection{SVG via Inkscape}%
\label{sub:svg_via_inkscape}
+\index{SVG via Inkscape}
This plugin allows the user to manipulate an SVG (scalable vector graphics) image with \textit{Inkscape} without having to leave the program. The associated \CGG{} window provides the ability to change the DPI, the Out $x/y$ coordinates, and the Out w/h values. For more information on use of inkscape, refer to: {\small \url{https://inkscape.org/develop/about-svg/}}
\subsection{Scale}%
\label{sub:scale}
+\index{scale}
Reduce or expand the image size depending on the ratio.
\subsection{Scale Ratio}%
\label{sub:scale_ratio}
+\index{acale ratio}
With the Scale Ratio plugin you can manipulate your video to maintain the pixel aspect ratio (proportional geometry), possibly for a different output Display device (figure~\ref{fig:scaleratio}).
\subsection{Selective Temporal Averaging}%
\label{sub:selective_temporal_averaging}
+\index{selective temporal averaging}
This plugin is designed to smooth out non-moving areas of a video clip (figure~\ref{fig:staveraging}).
\vspace{2ex}
\subsection{Sharpen}%
\label{sub:Sharpen}
+\index{sharpen}
-Sharpen the video, either the \textit{luminance}, \textit{horizontal}, or \textit{interlace}. With the Clear buttons we can bring the slider to default values without affecting the other parameters.
+Sharpen the video, either the \textit{luminance}, \textit{horizontal}, or \textit{interlace}. You can use sliders or, for maximum precision, you can use the input box. With the \textit{Clear} buttons we can bring the slider to default values without affecting the other parameters.
\subsection{Shift Interlace}%
\label{sub:shift_interlace}
+\index{shift interlace}
Shift the interlace lines using \textit{odd} or \textit{even}. With the Clear buttons we can bring the slider to default values without affecting the other parameters.
\subsection{Sketcher}%
\label{sub:Sketcher}
+\index{sketcher}
Now you can sketch \textit{lines}, \textit{curves} or \textit{shapes}, on your video in different colors using various pen widths and pen type with the \texttt{sketcher} plugin. You can even fill them. You can do rotations and scaling and apply two anti-aliasing modes; single and double. Getting started is fairly easy -- simply hold down the \textit{shift key} while using the \textit{left mouse button} to create a bunch of points in the compositor window. However, to do more than that you will need to understand the buttons and options or you may end up with unexpected results.
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}
The \textit{fill} point is a marker point, and not really part of the curve. That point identifies the inside of the loop. It can also be used to identify the outside of the loop in order to fill that. The loop is created by drawing a line from the last point to the first point in the curve. The line of this last segment is from the last point of the curve. If there are isolated loops in the curve (it is self intersecting) then you will be able to use multiple fill points to fill these regions.
+\subsection{Speed PerCent}%
+\label{sub:speed_per_cent}
+\index{speed percent}
+
+It works like the \texttt{ReframeRT} plugin in \textit{Stretch} mode. The interpolation algorithm is simply the slope of a linear curve. It allows you to change the speed of the video track, or an edit, or a region of the track quickly and intuitively. There are presets to set the speed to 100\% (default) or 25\%; 50\%; 200\% and 400\%. Or we can enter the value directly in the text box or use the slider until the desired value is reached. \textit{Interpolate} option works between keyframes. It requires setting the right limits for applying the effect and then rendering that region, or turning it into a nested clip, which will replace the original one.
+
\subsection{Sphere Cam}%
\label{sub:sphere_cam}
+\index{sphere cam}
Converts multiple fisheye images into a panoramic projection.
\subsection{Swap Frames}%
\label{sub:swap_frames}
+\index{swap frames}
Swap the position of two consecutive frames. There are two modes of exchange:
\subsection{Swap channels}%
\label{sub:swap_channels}
+\index{swap channels}
Swap R G, B, Alpha with another color channel.
\subsection{Threshold}%
\label{sub:threshold}
+\index{thresold}
\textit{Threshold} converts the image to pure luminance, and replaces pixels with one of three colors based on the luminance. Pixels with luminance values in the low range are replaced with black, pixels in the middle range are replaced with white, and pixels in the high range are replaced with black. \textit{Color} and \textit{alpha} (transparency) for each range are configurable with the buttons and interpolate according to keyframes.
\subsection{Time average}%
\label{sub:time_average}
-
-\begin{wrapfigure}[18]{O}{0.35\linewidth}
- \vspace{-2ex}
- \includegraphics[width=0.9\linewidth]{timeaverage.png}
- \caption{GUI for Time Average}
- \label{fig:timeaverage}
-\end{wrapfigure}
+\index{time average}
Time average is one effect which has many uses besides creating trail patterns of moving objects (figure~\ref{fig:timeaverage}).
The main use is reducing noise in still images (or in the motionless parts of a video). Merely point a video camera at a stationary subject for $30$ frames, capture the frames, and average them using time average and you will have a high quality print. In floating point color models, time average can increase the dynamic range of low quality cameras.
Inside the time average effect is an accumulation buffer and a divisor. A number of frames are accumulated in the \textit{accumulation} buffer and divided by the divisor to get the average (for $10$ accumulated frames the divisor is $10$). Because the time average can consume large amounts of memory, it is best applied by first disabling playback for the track, dropping the time average in it, configuring time average for the desired number of frames, and re-enabling playback for the track.
+\begin{figure}[hbtp]
+ \centering
+ \includegraphics[width=0.3\linewidth]{timeaverage.png}
+ \caption{GUI for Time Average}
+ \label{fig:timeaverage}
+\end{figure}
+
\begin{description}
\item[Frames count] this determines the number of frames to be accumulated in the accumulation buffer. Ranges from $1 to 1024$ frames.
\item[Accumulate] this outputs the accumulation buffer without dividing it.
\item[Don’t buffer frames] in order to represent the accumulation of only the specified number of frames, the time average retains all the previous frames in memory and subtracts them out as it plays forward. It would run out of memory if it had to accumulate thousands of frames. By disabling subtraction the previous frames are not stored in memory and only the average function is affected by the frame count.
\end{description}
+\subsection{TimeBlur}%
+\label{sub:timeblur}
+\index{timeblur}
+
+The TimeBlur plugin provides a way to blur a number of \textit{Frames}.
+
\subsection{Timefront}%
\label{sub:timefront}
+\index{timefront}
Space-temporal warping enables time to flow differently at different locations in the video (figure~\ref{fig:timefront}).
\begin{wrapfigure}[13]{O}{0.3\linewidth}
\textit{Rate} allows you to choose the type of algorithm to use when switching between the start and end bands. You can reverse the direction with the \textit{Invers} button. The three modes are: \textit{Linear}, \textit{Log} or \textit{Quadratic} (exponential). This is a warping framework plugin based on this article: {\small \url{http://www.vision.huji.ac.il/videowarping/HUJI-CSE-LTR-2005-10_etf-tr.pdf}}
+\subsection{Timelapse Helper}%
+\label{sub:timelapse_helper}
+\index{timelapse helper}
+
+It is used to get a timelapse quickly and easily. It sets the number of frames to be skipped during playback. The default value of \textit{Number of Frames x block} is 10; playback (and rendering) displays frames 1 - 10 - 20 - ... and not the intermediate ones.
+
\subsection{Title}%
\label{sub:title}
+\index{title}
+
+The \textit{Titler} allows you to add text from within \CGG{}. It has many configuration capabilities. Often it is convenient to apply the plugin on a separate track (shared or not), in order to make it independent from the video track and have more freedom in editing and configuration. For example, you can apply the \textit{Rotation} plugin to rotate the title without rotating the underlying video. Another thing to keep in mind when using the Titler plugin is that it works on the \textit{temporary} and therefore it is not affected by Camera movements (curves), but only by Projector movements.
+
+The titler has standard options for font, size, and style plus many options as described next (figure~\ref{fig:title01})
+
+\begin{figure}[hbtp]
+ \centering
+ \includegraphics[width=1.0\linewidth]{title01.png}
+ \caption{GUI of the Title plugin}
+ \label{fig:title01}
+\end{figure}
-The \textit{Titler} allows you to add text from within \CGG{}. The titler has standard options for font, size, and style plus many options as described next (figure~\ref{fig:title01}).
\begin{description}
\item[Justify] justifies the text relative to the entire frame. Once justified, the $X$ and $Y\, offset$ is applied. This allows text to be justified while at the same time letting you push it within the title safe region.
\item[Stamp timecode] replaces text with the current position on the timeline in seconds, frames or samples.
\end{description}
-\begin{figure}[hbtp]
- \centering
- \includegraphics[width=0.9\linewidth]{title01.png}
- \caption{GUI of the Title plugin}
- \label{fig:title01}
-\end{figure}
-
To create special effects for your title you can place it on a dedicated track and insert other realtime video effects just under the title effect and/or use camera and projector. With keyframing you can animate your title and make it change position, size, color, transparency, texture, or shape over time.
For improving playback performances of titles with effects, you can reduce the size of the dedicated track. Right click on the track and select \textit{Resize track\dots} Enter the smallest resolution that still keeps the title visible.
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. 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.
-
-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}
\begin{description}
- \item[Drag] initial default checkbox is \textit{off} so that the Title plugin will work as it always has.
+ \item[Drag] initial default checkbox is \textit{off} so that the Title plugin will work as it always has. With Drag active, we can create a box that works as a region to the title; we can resize and translate it as we wish, and we can add a background image (or video) to it. See later how to use the background image.
\begin{description}
- \item[Anchors] When you turn on the Drag feature, nine different anchors/handles will appear on compositor window. The \textit{middle anchor} allows you to drag your title wherever you want in the compositor window ($X, Y$ coordinates). The other 8 handles, drawn as arrows in each corner and in the middle of each side, let you change the size of the drag area box so that your title is within that area if it fits and as it is directed. If you need to clear the Drag enabled, you can easily do this with \textit{Allow keyframe spanning} whose use is described in \nameref{sec:allow_keyframes_spanning}.
+ \item[Anchors] When you turn on the Drag feature, nine different anchors/handles will appear on compositor window. The \textit{middle anchor} allows you to drag your title wherever you want in the compositor window ($X, Y$ coordinates). The other 8 handles, drawn as arrows in each corner and in the middle of each side, let you change the size of the drag area box so that your title is within that area if it fits and as it is directed. If you need to clear the Drag enabled, you can easily do this with \textit{Allow keyframe spanning} whose use is described in \nameref{sec:allow_keyframes_spanning}. Another way to reset the box to default, i.e. the entire frame, is to set X and Y to 0 and W and H to the frame resolution (e.g. 1920x1080 for FullHD).
\item[W/H] the values in these 2 boxes specify the size of the drag area box measured in pixels as shown in the compositor window. You can set these manually and if you can't see the location of your box or find your handles, set them to zero because $0$ sets it to the same as the width/height of the media.
The Drag effect ignores all boundaries, including the \textit{Title Safe Region} of the Compositor so that if you drag your titles off the screen, it will look like they disappeared completely. Reset X and Y to reasonable values to have it reappear. The Title \textit{text}, \textit{background}, and \textit{pngs} are applied on a single layer so that they will drag together as an entity. All of the Title capabilities work in conjunction with dragging so if you want to justify the title, you can still use the \textit{Left/Center/Right/Top/Mid/Bottom} within the drag area. Be sure to turn off Drag when rendering or the box will show in the video; keep in mind that drag bars do not appear until there is some text in the text box and you can not actually drag until the Title window controls are available.
\end{description}
+
+
+ \begin{figure}[hbtp]
+ \centering
+ \includegraphics[width=0.3\linewidth]{title02.png}
+ \caption{Pulldown Attributes}
+ \label{fig:title02}
+ \end{figure}
+
\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{figure}[hbtp]
- \centering
- \includegraphics[width=0.3\linewidth]{title02.png}
- \caption{Pulldown Attributes}
- \label{fig:title02}
-\end{figure}
-
-\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.
\paragraph{Special Characters (< > / \textbackslash \#)} Besides the previously described <, >, and / characters, there are two special characters: backslash “\textbackslash”, and the pound sign “\#”. The backslash character is used for two things. With the advent of the attribute name and value, your line may become quite long so you can use “\textbackslash” followed by the carriage return to continue on the next line as if it is just a single line. It also can be used to designate that the following character does not represent the beginning of an attribute. For example, if you want to use the opening angle character “<“ as a title character, precede it with the backslash character. The pound sign, “\#”, designates the whole line as a comment or if in the middle of the line, then the rest of the line is a comment (this includes the carriage return).
\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. 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.
+ \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}
The Text Color window has several enhanced features as listed here and seen in figure~\ref{fig:title04}.
+\begin{figure}[hbtp]
+ \centering
+ \includegraphics[width=0.7\linewidth]{title04.png}
+ \caption{Screencast showing the Color Picker menu.}
+ \label{fig:title04}
+\end{figure}
+
+
\begin{enumerate}
\item The hex value of the color you choose shows in the textbox and you can also keyin a value there.
- \item A small square next to the hex text box, is a green \textit{eyedropper} color picker. Use the left mouse button to click on the square to enable picking and you will see it turn red to designate that it is enabled. Your cursor will switch to a two-colored reticle. You can now move the mouse around to choose a color anywhere on the screen and then click there to have it picked. If you hold down the right or left mouse button while moving, you can see the color changing in the vertical bar in the color palette area as you move to give you a bigger view of the actual color. The eyedropper square is seen in figure~\ref{fig:title04}.
+ \item A small square next to the hex text box, is a green \textit{eyedropper} color picker. Use the left mouse button to click on the square to enable picking and you will see it turn red to designate that it is enabled. Your cursor will switch to a two-colored reticle. You can now move the mouse around to choose a color anywhere on the screen and then click there to have it picked. If you hold down the right or left mouse button while moving, you can see the color changing in the vertical bar in the color palette area as you move to give you a bigger view of the actual color.
\item A history of $16$ of your last chosen colors is available to easily use again. Any time you choose a new color in any methodology, it will become the latest choice in the history either immediately or after checking OK/and leaving. History shows latest color starting left to right.
\item Besides HSV, RGB, there is also a YUV color model to choose from.
\item Several of these items may have associated \textit{Tool Tips}.
\end{enumerate}
-\begin{figure}[hbtp]
- \centering
- \includegraphics[width=0.7\linewidth]{title04.png}
- \caption{Screencast showing the Color Picker menu.}
- \label{fig:title04}
-\end{figure}
-
\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:
unset BC_FONT_DEBUG (to remove debug messages)
\end{lstlisting}
-Then start \CGG{} from a terminal window to see the fonts being loaded and previewed in the Titler. This should point out any issues. Another debug methodology is to remove all fonts from being used and subsequently add in the ones that you want. For example:
+Then start \CGG{} from a terminal window to see the fonts being loaded and previewed in the Titler. This should point out any issues. Another debug methodology is to remove all fonts from being used and subsequently add in the ones that you want.
+This not only speeds the load up, it ensures that the fonts you actually are using are the ones you expect because the order that
+\CGG{} finds various fonts makes a difference in which one of potential duplicates shows up in the
+pulldown. So you might not see the one you expect if it was written over by a system font.
\vspace{1ex}
\begin{lstlisting}[style=sh]
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}
+
+When using the Titler, kerning is applied in order to allow parts of a letter to go outside the standard sized letter box. Kerning is the process of adjusting the space between individual letters. It is not the same as proportional spacing. In kerning, a bounding box is allowed to overlay another bounding box. The philosophy here is to aim at the ability to have boxes overlap in order to make the letters look more visually appealing. Bounding box and escapement are tracked separately. In addition to adjusting individual letter spacing, the program will also expand the render box in order to have any parts of the letter extend outside the standard letter box. Kerning is applied to any and all fonts (figure~\ref{fig:title05}).
\begin{figure}[hbtp]
\centering
\label{fig:title05}
\end{figure}
-\subsubsection*{Kerning}%
-\label{ssub:kerning}
-
-When using the Titler, kerning is applied in order to allow parts of a letter to go outside the standard sized letter box. Kerning is the process of adjusting the space between individual letters. It is not the same as proportional spacing. In kerning, a bounding box is allowed to overlay another bounding box. The philosophy here is to aim at the ability to have boxes overlap in order to make the letters look more visually appealing. Bounding box and escapement are tracked separately. In addition to adjusting individual letter spacing, the program will also expand the render box in order to have any parts of the letter extend outside the standard letter box. Kerning is applied to any and all fonts (figure~\ref{fig:title05}).
-
\subsection{Tracer}%
\label{sub:tracer}
+\index{tracer}
Tracer creates an outline around an object after a few points are designated, so it traces the object. Its operates in a similar manner to that of Gimp's \textit{magic wand}. You can then Fill the alpha channel with a mask, like with a gradient or another object on another track or Invert that fill. Although it works best for still images or objects that stay in the same place on a video like a logo, you can also add keyframes. To limit the mis-tracking that occurs when working on a moving object, we can increase the number of points so that the tracking is more accurate and relies on a solid foundation. Rather than \textit{points} as in a mask, tracer is based on \textit{edges} to form an outline (figure~\ref{fig:tracer-01}). Frequently it will be desirable to use either RGB or YUV as the color model without the -A for Alpha.
\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.
\subsection{Translate}%
\label{sub:translate}
+\index{translate}
This effect allows displacing, cropping, and/or scaling the source video horizontally and/or vertically. The \textit{In} and \textit{Out} parameters operate similar to the \textit{camera} and \textit{projector} functions in the Compositor:
\subsection{Unsharp}%
\label{sub:Unsharp}
+\index{unsharp}
-This effect applies a traditional \textit{darkroom} technique, the so called \textit{unsharp mask} to every video frame. With different parameter values, this can be used to soften or to sharpen the image. Its parameters are:
+This effect applies a traditional \textit{darkroom} technique, the so called \textit{unsharp mask} to every video frame. With different parameter values, this can be used to soften or to sharpen the image. You can use sliders or, for maximum precision, you can use the input box. Its parameters are:
\begin{description}
\item[Amount] moving the slider to the right makes dark areas get darker and light areas get lighter.
\subsection{Videoscope}%
\label{sub:videoscope}
+\index{videoscope}
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).
\subsubsection*{Waveform/RGB Parade/Waveform Ply}%
\label{ssub:waveform_rgb_parade_ply}
+\index{videoscope!waveforms}
The \textit{Waveform Scope} displays image intensity (luminance) versus image $X$ position. The \textit{Waveform RGB} displays image RGB intensity versus image $X$ position (one graph per channel). The \textit{Waveform Ply} shows the three channels in a single graph. The Waveform Scope appears on the left side or in the middle of the Videoscope window. The display is calibrated vertically from $0\%$ intensity (black) at the bottom up to $100\%$ intensity (white) at the top. Each column of pixels in the image corresponds to one column of pixels in the Waveform Scope (figure~\ref{fig:videoscope02}). Note that the height of the values of a waveform/waveform RGB corresponds exactly to the values on the $x\, axis$ in the \textit{histogram}. A vertical/horizontal correspondence is therefore obtained.
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}
\subsubsection*{Vectorscope}%
\label{ssub:Vectorscope}
+\index{videoscope!vectorscope}
The Vectorscope displays \textit{hue} (angle on the color wheel) and \textit{saturation} (radius). Each pixel in the source image is drawn as a point on the color wheel. The distance from the center is the color saturation. Gray values are close to the center, and high saturation values are near the perimeter ($100\%$). In the center there is pure white ($0\%$). By clicking with the mouse on the color wheel a radius and circle will appear whose values of hue and saturation are shown in the pop-up box at the bottom right of the window, similar to the values of $X$ and luminance of the Waveform and RGB Parade (figure~\ref{fig:videoscope05}).
\subsubsection*{Histogram}%
\label{ssub:histogram}
+\index{videoscope!histogram}
You can also display the 4 histograms (master or RGB) on the left of the window. (see figure~\ref{fig:videoscope01}).
\subsection{Wave}%
\label{sub:wave}
+\index{wave}
-The \textit{wave} effect adds waves on the image. \textit{Amplitude}, \textit{Phase}, and \textit{Wavelength} parameters can be adjusted. With the Clear buttons we can bring the slider to default values without affecting the other parameters.
+The \textit{wave} effect adds waves on the image. \textit{Amplitude}, \textit{Phase}, and \textit{Wavelength} parameters can be adjusted. You can use sliders or, for maximum precision, you can use the input box. With the \textit{Clear} buttons we can bring the slider to default values without affecting the other parameters.
\subsection{Whirl}%
\label{sub:whirl}
+\index{whirl}
-Creates a whirl (spiral) of the video around the center. With the Clear buttons we can bring the slider to default values without affecting the other parameters.
+Creates a whirl (spiral) of the video around the center. You can use sliders or, for maximum precision, you can use the input box. With the \textit{Clear} buttons we can bring the slider to default values without affecting the other parameters.
\subsection{YUV}%
\label{sub:yuv}
+\index{yuv}
-Modify the Y, U, V settings. With the Clear buttons we can bring the slider to default values without affecting the other parameters.
+Modify the Y, U, V settings. You can use sliders or, for maximum precision, you can use the input box. With the \textit{Clear} buttons we can bring the slider to default values without affecting the other parameters.
\subsection{YUV411}%
\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}
+\index{yuv shift}
\begin{figure}[hbtp]
\centering
\label{fig:yuvshift}
\end{figure}
-This effect is used for YUV input video from older cameras using $3$ sensors. It is possible to have misalignment of the $3$ sets of numbers: \textit{Y}, which represents the luminance or brightness component, and for \textit{U} and \textit{V} representing the chrominance (color) components. If they were misaligned in the video, you can use \textit{YUVShift} to realign. To move a specific component up/down, modify the \textit{dy} value using the slider bar in the RGBShift window. To move a component left/right, modify the corresponding \textit{dx} value. With the Clear buttons we can bring the slider to default values without affecting the other parameters. If you are using an RGB color space, you will want to use the \textit{RGBShift} effect instead.
+This effect is used for YUV input video from older cameras using $3$ sensors. It is possible to have misalignment of the $3$ sets of numbers: \textit{Y}, which represents the luminance or brightness component, and for \textit{U} and \textit{V} representing the chrominance (color) components. If they were misaligned in the video, you can use \textit{YUVShift} to realign. To move a specific component up/down, modify the \textit{dy} value using the slider bar in the RGBShift window. To move a component left/right, modify the corresponding \textit{dx} value. For maximum precision you can use the input box. With the \textit{Clear} buttons we can bring the slider to default values without affecting the other parameters. If you are using an RGB color space, you will want to use the \textit{RGBShift} effect instead.
-Figure~\ref{fig:yuvshift} (top) shows the blue \textit{U} component aligned too far to the left. And the red \textit{V} component is misaligned too far to the right. Note the \textit{U\_dx} current slider bar set to $0$ as shown by the yellow box value in the YUVShift plugin window. All components are currently at zero.
-A corrected video image is shown in the bottom. Now the red and blue colors are correctly aligned. Note how \textit{U\_dx} is now at $+20$ and \textit{V\_dx} is now negative to realign the image.
+Figure~\ref{fig:yuvshift} (top) shows the blue \textit{U} component aligned too far to the right/down. And the red \textit{V} component is misaligned too far to the right/down. Note the \textit{U\_dx} current slider bar set to $0$ as shown by the input box value in the YUVShift plugin window. All components are currently at zero.
+A corrected video image is shown in the bottom. Now the red and blue colors are correctly aligned. Note how \textit{U\_dx} is now at $+26$ and \textit{V\_dx} is now $+41$ to realign the image.
\subsection{Zoom Blur}%
\label{sub:zoom_blur}
+\index{zoom blur}
Blurs the video from the center outwards, like the sun’s rays, and uses a zoom effect.
+\begin{figure}[hbtp]
+ \centering
+ \includegraphics[width=0.8\linewidth]{zoom.png}
+ \caption{For clarity of presentation only 3 fields are shown}
+ \label{fig:zoom}
+\end{figure}
+
\begin{description}
\item[X,Y] center of the origin field.
\item[Radius] Zoom on the fields.
\item[Steps] number of blur steps to be used in the calculation. Increasing the number takes more CPU.
\item[Clear] With the Clear buttons we can bring the slider to default values without affecting the other parameters.
+ \item[Reset] To reset all parameters to default at the same time.
\end{description}
+You can use sliders or, for maximum precision, you can use the input box.
Figure~\ref{fig:zoom} shows the parameters: Radius=21 and Steps=3.
-\begin{figure}[hbtp]
- \centering
- \includegraphics[width=0.8\linewidth]{zoom.png}
- \caption{For clarity of presentation only 3 fields are shown}
- \label{fig:zoom}
-\end{figure}
-
\section{CUDA plugins}%
\label{sec:cuda_plugins}
\settocdepth{section}
+\index{CUDA!plugin}
Only for Nvidia GPU and Cuda SDK
\subsection{Mandelbrot}%
\label{sub:mandelbrot}
+\index{CUDA!mandelbrot}
Produce fractal figures (figure~\ref{fig:mandelbrot}). Use case:
\subsection{N\_Body}%
\label{sub:n_body}
+\index{CUDA!n\_body}
Produce animated particles (figure~\ref{fig:n_body}).
\section{OpenCV plugins}%
\label{sec:opencv_plugins}
\settocdepth{section}
+\index{openCV}
There are currently 6 OpenCV plugins hooked into Cinelerra static and dynamic tars with the most
widely known being FindObj. The \textit{Find Object} plugin searches a Scene for an Object and
The OpenCV plugins are built only in the 64-bit tarball builds, both static and dynamic, but due
to size these plugins are not included with pkgs, i.e. the System builds. However it is relatively
easy to add the current plugins for your distro via a simple procedure of copying the plugins
-from the static tarball to the cin5 install plugin path. They are:
+from the static tarball to the cin5 install plugin path (AppImage does not provide this capability). They are:
\begin{lstlisting}[style=sh]
cin/plugins/opencv/findobj.plugin
The location for most User installs is:
-\hspace{4em}\texttt{<cinlib\_path>/plugins/}
+\hspace{4em}\texttt{<cinlib\_path>/plugins/video}
Location for some System installs is:
-\hspace{4em}\texttt{/usr/lib/cin/plugins/} (most ubuntu distros)
+\hspace{4em}\texttt{/usr/lib/cin/plugins/video} (most ubuntu distros)
-\hspace{4em}\texttt{/usr/lib64/cin/plugins/} (Leap distro)
+\hspace{4em}\texttt{/usr/lib64/cin/plugins/video} (Leap distro)
\subsection{How to Build OpenCV Plugins}%
\label{sub:how_build_opencv_plugins}
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:
\subsection{Description of Find Object Plugin}%
\label{sub:description_findobj_plugin}
+\index{openCV!find object}
As in the standard OpenCV FindObj program, there are $5$ \textit{detector} methods and $2$ \textit{matcher} methods which can be selected. They detect features and match them as a rectangular projection. The matched region will be overlayed with a replacement image if replace object is enabled. This is done using a variety of feature detectors and region matches. The match works by creating sets of Feature points. These points are generated for both the source and reference object frames. Then the two sets are matched for \textit{Homography} (a regional similarity).
\label{fig:opencv}
\end{figure}
-The \textit{StylizeObj} plugin can be used to create some interesting edge effects using various options (figure~\ref{fig:stylizeobj01}).
+The \textit{StylizeObj} \index{openCV!stylizeobj} plugin can be used to create some interesting edge effects using various options (figure~\ref{fig:stylizeobj01}).
We can apply 6 different styles:
\section[FFmpeg Audio and Video Plugins]{FFmpeg Audio and Video Plugins}%
\label{sec:ffmpeg_audio_video_plugins}
+\index{ffmpeg!plugins}
\CGGI{} currently comes with more than $140$ of the video plugins and $55$ of the audio plugins developed by the FFmpeg project {\small \url{www.ffmpeg.org}}. These plugins do not have a GUI with buttons like the rest of plugins, therefore to change settings it is necessary to change the variables by hand by highlighting the \textit{option}, typing a value in the \textit{Range} box, and then hitting the \textit{Apply} button. Many of these plugins provide tooltips at the bottom right corner of the window when the option is highlighted. A \textit{slider} bar and a \textit{dial} for numerical values can be used to easily vary the values which take effect immediately.
FFmpeg’s plugin guide is at the link:
\href{https://ffmpeg.org/ffmpeg-filters.html}{ffmpeg-filters}.
-\subsection{FFmpeg Audio Plugins\protect\footnote{credit to WPfilmmaker}}%
+\subsection{FFmpeg Audio Plugins}%
\label{sub:ffmpeg_audio_plugins}
+\index{ffmpeg!audio plugin}
-The following is a list of the integrated audio plug-ins.
+The following is a list of the integrated audio plug-ins\protect\footnote{credit to WPfilmmaker} .
\begin{description}
\item [F\_abench]~\\Benchmark part of a filtergraph.
\item [F\_acompressor]~\\Audio compressor.
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\_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\_aeval]~\\Filters audio signal according to a
specific expression.
+\item [F\_aeexciter]~\\Enhance high frequency part of audio.
\item [F\_afade]~\\Fades in/out input audio.
\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.
\item [F\_aperms]~\\Set permissions for the output audio
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\_atempo]~\\Adjusts audio tempo.
+\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\_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}
-\subsection{FFmpeg Video Plugins\protect\footnote{credit to WPfilmmaker}}%
+\subsection{FFmpeg Video Plugins}%
\label{sub:ffmpeg_video_plugins}
+\index{ffmpeg!video plugins}
-The following is a list of the integrated video plug-ins.
+The following is a list of the integrated video plug-ins \protect\footnote{credit to WPfilmmaker} .
\begin{description}
\item [F\_addroi]~\\Mark a region of interest in a video frame.
\item [F\_amplify]~\\Amplify changes between successive video
\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
transparency. Operates on YUV colors.
+\item [F\_chromanr]~\\Reduce chrominance noise.
\item [F\_ciescope]~\\Video CIE scope.
\item [F\_color]~\\Provide an uniformly colored input.
\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
+ for blacks and whites.
\item [F\_colorkey]~\\Turns a certain color into
transparency. Operates on RGB colors.
\item [F\_colorlevels]~\\Adjusts the color levels.
\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\_crop]~\\Crops the input video.
\item [F\_elbg]~\\Apply posterize effect, using the ELBG
algorithm.
\item [F\_entropy]~\\Measure video frames entropy.
+\item [F\_epx]~\\Scale the input using EPX algorithm.
\item [F\_eq]~\\Adjusts brightness, contrast, gamma and
saturation.
\item [F\_erosion]~\\Applies erosion effect.
+\item [F\_estdif]~\\Apply Edge Slope Tracing deinterlace.
+\item [F\_exposure]~\\Adjust exposure of the video stream.
\item [F\_fade]~\\Fade in/out input video.
\item [F\_fftdnoiz]~\\Denoise frames using $3D FFT$.
\item [F\_fftfilt]~\\Apply arbitrary expressions to pixels in
\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.
interlaced.
\item [F\_kerndeint]~\\Applies kernel deinterlacing to the
input.
-\item [F\_lenscorrection]~\\Rectifies the image by correcting
- for lens distortion.
+\item [F\_kirsch]~\\Apply kirsch operator.
+\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.
deinterlacing.
\item [F\_median]~\\Pick median pixel from rectangle defined by radius.
\item [F\_mestimate]~\\Generate motion vectors.
+\item [F\_monochrome]~\\Convert video to gray using custom color filter.
\item [F\_mpdecimate]~\\Remove near-duplicate frames.
\item [F\_mptestsrc]~\\Generate various test pattern.
\item [F\_negate]~\\Negates input video.
\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.
performs a simple/quick $2D$ spatial gradient measurement on the
video (usually a grayscale image). It highlights regions of high
spatial frequency which most ikely correspond to edges.
-\item [F\_rotate]~\\Rotates the input image.
+\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.
output video frame.
\item [F\_setrange]~\\Force color range for the output video
frame.
+\item [F\_shear]~\\Shear transform the input image.
\item [F\_showpalette]~\\Display frame palette.
\item [F\_shuffleframes]~\\Shuffles video frames.
+\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.
+ strength and the threshold of luma and chroma. This plugin can be used to correct
+ over sharpened footage. For example, on a DJI 3840x2160 D-cinelike footage using
+ these settings:
+\begin{itemize}
+ \item luma radius: 3.247993
+ \item luma strength: 0.360153
+ \item luma threshold: -2
+\end{itemize}
+ the over-sharpened edges will be smoothed. All other settings are at default values.
\item [F\_smptebars]~\\Generate SMPTE color bars.
\item [F\_smptehdbars]~\\Generate SMPTE HD color bars.
\item [F\_sobel]~\\Applies sobel operator.
\item [F\_tlut2]~\\Compute and apply a lookup table from 2
successive frames.
\item [F\_tmedian]~\\Pick median pixels from successive frames.
+\item [F\_tmidequalizer]~\\Apply Temporal Midway Equalization.
\item [F\_tmix]~\\Mix successive video frames.
\item [F\_transpose]~\\Transposes input video.
\item [F\_unsharp]~\\Sharpen or blur the input videlo.
\section[Rendered Effects]{Rendered Effects}%
\label{sec:rendered_effects}
+\index{plugins!rendered effects}
Besides the \textit{Realtime} effects, as has been described in the previous sections, another type of effect is performed on a section of the track and the result stored somewhere before it is played back. The result is usually pasted into the track to replace the original data. The rendered effects are not listed in the resources window but instead are accessed through the \texttt{Audio $\rightarrow$ Render effect and Video $\rightarrow$ Render effect} menu options. Each of these menu options brings up a dialog for the rendered effect. In the Select an effect dialog is a list of all the realtime and all the rendered effects. The difference here is that the realtime effects are rendered to disk and not applied under the track. Rendered effects apply to only one type of track, either audio or video. If no tracks of the type exist, an error pops up.
\subsubsection*{Time Stretch}%
\label{ssub:time_stretch}
+\subsubsection*{CD Ripper}%
+\label{ssub:cd_ripper}
+
+
\subsection{Rendered Video Effects}%
\label{sub:renederd_video_effets}
\item At the popup menu, enter the \textit{scale factor} $2$ to run twice as fast, and $0.5$ to run at half speed.
\end{itemize}
-\subsubsection*{CD Ripper}%
-\label{ssub:cd_ripper}
-
\subsubsection*{720 to 480}%
\label{ssub:720_to_480}
--- /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:
\section{\CGG{} Quick Start Guide}%
\label{sec:cin_quick_start_guide}
+\index{quickstart guide}
\CGG{} is a software program NLE, Non-Linear Editor, that provides a way to edit, record, and play audio or video media on Linux. It can also be used to color correction, retouch photos, motion tracking, watch TV, and create DVDs.
\item Or if you installed using the pkg method, click on the \textit{Cin icon}.
\end{itemize}
-You will now see 4 separate windows appear. The top 2 windows from left to right are the Viewer which is most useful for previewing clips and media and the Compositor which displays the current working frame at the timeline position. The bottom 2 windows are the \CGG{} Program, also called the timeline, which is where the real work gets done and the Resources window showing a selection of media or effects.
-
\begin{figure}[htpb]
\centering
- \includegraphics[width=1.0\linewidth]{4windows.png}
+ \includegraphics[width=1.0\linewidth]{Fenstergrundposition-en.png}
\caption{Clockwise: Viewer; Compositor; Resources and Main/Program/Timeline}
\end{figure}
+You will now see 4 separate windows appear. The top 2 windows from left to right are the Viewer which is most useful for previewing clips and media and the Compositor which displays the current working frame at the timeline position. The bottom 2 windows are the \CGG{} Program, also called the timeline, which is where the real work gets done and the Resources window showing a selection of media or effects.
+
Any of these windows can be resized to better suit your needs. Note that if your system’s native language is not English, some of the words you see on the screen will be correctly translated for you, others will be in english, and some will have not very good translations.
It is important to know that \CGG{} does not directly change your media. It writes all changes to what is called the EDL, Edit Decision List. This way you original media remains completely intact.
+Before you get startedi here is a note about \textit{Context Help}. If you need more
+detailed information on a window, menu, button or other particular GUI element than
+is shown in the tooltip, press Alt/h hotkey and the HTML page in your configured web
+browser will display the documentation for the item currently under the mouse.
+
\subsection{Load Media}%
\label{sub:load_media}
\begin{figure}[htpb]
\centering
- \includegraphics[width=1.0\linewidth]{load_files.png}
+ \includegraphics[width=1.0\linewidth]{load.png}
\caption{Load media window -- note the icons top right for more options}
\end{figure}
\begin{figure}[htpb]
\centering
- \includegraphics[width=0.7\linewidth]{format_setting.png}
+ \includegraphics[width=0.7\linewidth]{set-format.png}
\caption{Format menu to change settings}
\end{figure}
\begin{figure}[htpb]
\centering
- \includegraphics[width=0.5\linewidth]{magnifier.png}
- \caption{Effect brown bar with magnifier}
+ \includegraphics[width=0.8\linewidth]{magnifier.png}
+ \caption{Effect blue bar with magnifier}
\end{figure}
\subsection{View and Listen}%
\begin{figure}[htpb]
\centering
\includegraphics[width=1.0\linewidth]{pulldown_button.png}
- \caption{Menu pulldowns at the top with Transport buttons below. Note the yellow tooltips too.}
+ \caption{Menu pulldowns at the top with Transport buttons below. Note the colored tooltips too.}
\end{figure}
\begin{enumerate}
\item On the second line, below the pulldowns, are transport buttons to move back and forth on the
timeline and play forward or reverse, fast or slow, or a single frame. When you mouse over one of
- these buttons, a yellow colored tooltip appears to tell you its function along with a key shortcut
+ these buttons, a colored tooltip appears to tell you its function along with a key shortcut
inside of parenthesis. When you left click the mouse on the transport button it starts the play and
click again to stop it. As you use these buttons, watch the Compositor to watch your video.
\item On the timeline, you only see thumbnails and not every single picture. You may want to
large video can be time-consuming.
\end{enumerate}
+If you need more detailed information on a button or other particular GUI
+element than is shown in the tooltip, press Alt/h hotkey and the HTML page
+in your configured web browser will display the documentation for the item
+currently under the mouse.
+
\subsection{Edit/Compose}%
\label{sub:edit_compose}
\begin{figure}[htpb]
\centering
\includegraphics[width=1.0\linewidth]{some_editing.png}
- \caption{From left to right:\textit{ Audio 1} is disarmed -- BandSlide transition in \textit{Video 1} -- A highlighted section.}
+ \caption{From left to right: Audio 1 is disarmed -- BandSlide transition in Video 1 -- A highlighted section.}
\end{figure}
\begin{enumerate}
button and drag the area to be made into a clip which will turn the color white. Remember, you
disarmed the other tracks so only this track is relevant at this time. On the second line of the main
window to the right of the transport buttons, are action buttons and as you mouse over them a
- yellow colored tooltip explains its purpose. Find the one that says \textit{To clip} which is on the right
+ colored tooltip explains its purpose. Find the one that says \textit{To clip} which is on the right
hand side of the right bracket symbol.
\item Click on \textit{To clip} and a small window comes up which you can comment in, but you do not have
to, so just click on the green checkmark and now you will have a clip.
The file you created in the Render step should now be playable. You can test this in \CGG{} most easily by going to the Resource window in the lower right corner, clicking on the Media folder, and dragging and dropping the last video to the Viewer window. There is a separate set of transport buttons on the bottom on that screen to use for playing.
-\section{YouTube with \CGG{}}%
-\label{sec:youtube_with_cinelerra}
+\section{Overview on Formats and Codecs}%
+\label{sec:overview_formats}
+\index{format}
+\index{codec}
-To create a youtube or dailymotion video, you can easily follow the steps below. You will have to learn a lot more about \CGG{} to take full advantage of its capabilities and make some really special videos, but this is just to get a start and to see the possibilities.
+Here is an overview of the formats (also called containers) and codecs that are used in \CGG{}, by ffmpeg and the internal engine. Roughly speaking these are divided into uncompressed codecs (or codecs with \textit{Intraframe} compression, which can be lossy or lossless) and compressed codecs of \textit{Interframe} type (LongGOP, almost always with lossy compression). The All-I (intraframe) codecs are suitable for editing because a cut or other operation on the timeline corresponds to the exact frame on which you are operating. The interframe types use Groups of Pictures (GOP) and a cut or other operation is accurate (and requires no further calculation) only if it coincides with the beginning of the GOP, and not with an internal frame. There is also color compression: Color Space \textit{bit-depth} and \textit{Chroma-Subsampling} for YUV models. In addition, heavy compression requires the system to do more encoding/decoding work on the timeline. High quality codecs have high bit rates and bit depths but this also affects the performance of the system, not to mention the increased disk space usage. Some formats implement both audio and video streams, others audio only or video only.
-\begin{enumerate}
- \item Start \CGG{}; usually you can do this by clicking on \CGG{} icon or key in \texttt{{cin\_path}/bin/cin}.
- \item In the Program window on the lower left side of your screen, left mouse click the \textit{File} pulldown.
- \item You will see \textit{Load files} as the second choice so left mouse click this and find your video file to
- load, highlight it, and check the green checkmark in the lower left hand corner to get it loaded.
- \item Edit your video in the Program window using the basic commands of:
- \begin{itemize}
- \item play and then stop using the space bar
- \item move the mouse and then left click to move the insertion (location) pointer
- \item cut a section out by holding down the left mouse and drag, then key in “x” to cut or “c” to copy
- \item paste a copy or cut section by moving the insertion pointer, then key in “v”
- \end{itemize}
- \item Add a title by highlighting the \textit{Video Effects} in the right hand side Resources window; then
- highlighting the \textit{Title} icon and dragging it to the Program window video track and dropping.
- \item Click on the middle icon button (looks like a magnifying glass) on the brown colored Title bar to
- bring up the Title window bottom text box and key in a title.
- \item Use the \textit{File} pulldown to select \textit{Render} to create the desired video. In the \textit{Render} window just next to the empty box to the right of the \textit{ffmpeg} file format, click on the down arrow shown there
- to see the choices and pick \textit{youtube}. Then move back up to key in the path and filename to render
- to. It will pick all of the defaults automatically for you so then just click on the green checkmark to
- have it start. There is a progress bar in the main window, very bottom of the right hand side.
- \item Key in “q” in the main window to get out of \CGG{} and yes or no to save your edit session.
-\end{enumerate}
+\subsection{Video FFmpeg Formats}%
+\label{sec:FFmpeg_video}
-Youtube will allow the upload of the resulting rendered file as named. However, Dailymotion requires that the file be named with an acceptable extension so you must rename the output file to have the extension of .webm instead of .youtube
+FFmpeg supports hundreds of codecs and formats. Some are proprietary and cannot be implemented in FFmpeg or can be voluntarily compiled as non-free; others are proprietary but their use is free; finally there are the Open formats/codecs, fully supported and well documented. We are only describing here a selection of the most well-known and most frequently used ones.
-There are currently 6 specific variations within the ffmpeg (file format) / youtube (file type) for different video options. You see these when you click on the wrench to the right of the word Video and then the Compression down arrow in the Video Preset window. The first 3 are based on Webm/Vp9\protect\footnote{credit by Frederic Roenitz} and contain basic comments of usage and where to find more information.
+\subsubsection{High Quality}
+\label{ssub:ffmpeg_video_high_quality}
-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.
+High quality formats are also called Mezzanine codecs, Digital Intermediate, Preservation codecs or Editing codecs. These have no compression or intraframe lossless or near-lossless compression and are suitable for editing, post-processing, mastering and archiving. They are also used for the interchange of files between different programs. They take up a lot of disk space and require a powerful system.
-\begin{center}
- \begin{tabular}{l p{8cm}}
- sd.youtube & Standard Definition use with default audio/Opus stereo.youtube \\
- hd.youtube & High Definition “ “ \\
- uhd.youtube & Ultra High Definition “ “ \\
- \end{tabular}
-\end{center}
+\begin{description}
+ \item[MKV] Open, highly configurable and extensively documented. Can have seeking problems. Belongs to the Matroska family.
+ \newline Presets: \textit{ffv1, ffvyuv}
+ \item[MXF] Created by Avid. It is probably the best and most advanced container for editing.
+ \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 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{AVC\_Intra\_100}
+ \item[RGB] Raw format.
+ \newline Presets: \textit{raw}
+ \item[YUV] Raw format.
+ \newline Presets: \textit{raw}
+ \item[AVI] Old and limited format (no multi streams, no subtitles, limited metadata) but with high compatibility.
+ \newline Presets: \textit{ffv1}
+\end{description}
+
+\subsubsection{General Purpose}
+\label{ssub:ffmpeg_video_general_purpose}
+
+These are also called Delivery codecs. They are the most used and widespread being suitable for streaming, video sharing, watching TV, smartphones, plus more. Because of lossy compression type Interframe, they produce smaller files with variable quality. They are not suitable for editing, compositing and color correction. Further rendering of these formats worsens the quality exponentially. The most used codecs have hardware support (vaapi, vdpau, nvenc) that make them more efficient.
+
+\begin{description}
+ \item[MOV] Created by Apple. It is a suitable format for editing because it organizes the files within the container into hierarchically structured "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{Presets: mov}
+ \item[QT] Different exstension, but it is always mov.
+ \newline Presets: \textit{mjpeg, DV, Div, CinePack}
+ \item[MP4] The most popular. Many other formats belong to this family (MPEG);
+ \newline h264 is actually x264, open, highly configurable and documented; h265/HEVC is actually x265, open, highly configurable and documented. x264-5 is for encoding only.
+ \newline Presets: \textit{h265, h265, mjpeg, mpeg2, obs2youtube}
+ \item[WEBM] Open; similar to mp4 but not as widespread (it is used by YouTube). It belongs to the Matroska family. In \CGG{} there are specific Presets with \texttt{.youtube} extension, but they are still webm.
+ \newline Presets: \textit{VP8, VP9, AV1}
+ \item[MKV] Open, highly configurable and widely documented. It might have seeking problems. It belongs to the Matroska family.
+ \newline Presets: \textit{Theora, VP8, VP9}
+ \item[AVI] Old and limited format (no multistreams, no subtitles, limited metadata) but with high compatibility.
+ \newline Presets: \textit{asv, DV, mjpeg, xvid}
+ \item[MPG] Parent of the MPEG family, to which MP4 also belongs. Mpeg is used by \CGG{} as default for proxies and mpeg-2 is the standard for Video DVDs.
+ \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. 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.
+ \item[PNG] Uncompressed or lossless compression. Supports alpha channel.
+ \item[WEBP, TIFF, GIF, JPEG, ...] Variable compression, size and quality.
+\end{description}
+
+\subsubsection{Old Pro Formats}
+\label{ssub:ffmpeg_old_pro_formats}
+
+Some formats, though used in the past in the pro field, are disappearing with the evolution of technologies. DVD is becoming more and more niche, while Bluray is still widespread (also as a backup); DV/HDV remains only as a support for old Camcorders with magnetic tapes. DV is still a quality format, with intraframe compression; HDV is mpeg-2 compressed.
+
+\begin{description}
+ \item[AVI] old and limited format but with high compatibility.
+ \newline Presets: \textit{DV\_pal, DV\_ntsc, mjpeg}
+ \item[QT] belongs to the Apple mov family.
+ \newline Presets: \textit{DV, mjpeg}
+ \item[M2TS] format for Bluray (mpeg4). Bluray player devices need a standard Bluray disc structure (bdwrite) for playback\protect\footnote{\CGG{} offers specific functionality for creating DVDs/Blurays}.
+ \newline Presets: \textit{AVC422, Lossless, Bluray, hevc}
+ \item[MP4] Belongs to the MPEG family. Motionjpeg has jpeg compression, then Intraframe, so it maintains good quality and fluidity in editing. It is now an old and limited codec.
+ \newline Presets: \textit{mjpeg}
+\end{description}
+
+\subsection{Audio FFmpeg Formats}%
+\label{sub:FFmpeg_audio}
+
+Audio formats and codecs take much less resources and space than video ones, so they are often used without compression for maximum quality. However these are compressed formats and codecs widely used in streaming and sharing.
+
+\subsubsection{High Quality}
+\label{ssub:ffmpeg_audio_high_quality}
+
+\begin{description}
+ \item[FLAC] Open; used for storing music. It has lossless compression.
+ \newline preset: \textit{flac}
+ \item[PCM] Raw format that encodes the signal with \textit{modified pulse modulation} (pcm). FFmpeg does not support pcm audio if you use mp4 as a container.
+ \newline Presets: \textit{s8, s16, s24, s32}
+ \item[WAV] Raw format created by Microsoft. 32-bit addressing leading to the 4 GB recording limit. It is a widely used standard.
+ \newline Presets: \textit{s24le, s32le}
+ \item[W64] Wave format created by Sony to override the 4GB recording limit. Poorly supported.
+ \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}
+\label{ssub:ffmpeg_audio_general_purpose}
+
+\begin{description}
+ \item[MP3] Belongs to the MPEG family. The most widely used in streaming and sharing.
+ \newline preset: \textit{mp3}
+ \item[OGG] Open, highly configurable and documented. It belongs to the Matroska family. Flac has lossless compression; opus is compressed but modern and of good quality, superior to mp3. Vorbis is compressed and dated, but lightweight and compatible.
+ \newline Presets: \textit{flac, opus, vorbis}
+ \item[PRO] Created by Apple; compressed audio codec, competing with mp3.
+ \newline Presets: \textit{aac256k}
+\end{description}
+
+\subsection{\CGG{} Internal Engine}%
+\label{sub:internal_engine}
+
+FFmpeg is the default engine, but you can also use its internal engine, which is limited in supported formats but efficient and of high quality.
+
+\subsubsection{Video general purpose}
+\label{ssub:internal_general_purpose}
+
+\begin{description}
+ \item[RAW DV] supports the DV standard.
+ \newline Presets: \textit{dv}
+ \item[MPEG Video] highly configurable. Extension \texttt{.m2v}.
+ \newline Presets: \textit{mpeg1, mpeg2}
+ \item[OGG Theora/Vorbis] Open, easily configurable. Theora for video, Vorbis for audio.
+ \newline Presets: \textit{theora, vorbis}
+\end{description}
+
+\subsubsection{Image Sequences}
+\label{sub:internal_image_sequences}
+
+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[Ppm Sequence] is RGB Raw.
+ \item[Tga Sequence] is RGB(A) compressed or uncompressed.
+ \item[Tiff Sequence] is RGB(A) or RGB(A)-Float with various compression types.
+ \item[Jpg, gif Sequences] lossy compressed and limited formats.
+\end{description}
+
+\subsubsection{Audio general purpose}
+\label{sub:internal_audio_general_purpose}
+
+\begin{description}
+ \item[AC3] widely used multichannel standard (Dolby Digital). Format with lossy compression.
+ \newline Presets: \textit{ac3}
+ \item[Apple/SGI AIFF] Created by Apple; is an uncompressed format (pcm type) or with 32/64-bit floating point compression.
+ \newline Presets: \textit{aif}
+ \item[Sun/Next AU] created by Sun and used in Unix environment, now in disuse. It can be of pcm type or with lossy compression.
+ \newline Presets: \textit{au}
+ \item[Flac] Open, lossless compression, very good quality.
+ \newline preset: \textit{flac}
+ \item[Microsoft WAV] created by Microsoft. It can have 16-24-32-bit linear or float compression.
+ \newline Presets: \textit{wav}
+ \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}
-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.
+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 p{8cm}}
- sd\_h264.youtube & Standard Definition – must change to audio stereo\_with\_h264.youtube \\
- hd\_h264.youtube & High Definition - “ “ \\
- uhd\_u264.youtube & Ultra High Definition - “ “ \\
+ \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}
This appendix includes descriptions of various real life workflows used by \CGG{} users. There may be links to some video explanations in various languages.
You can only follow these links from the online pdf version.
-\section{Workflow with OpenEDL and Nested Clips\protect\footnote{credit fary54}}%
+\section{Workflow with OpenEDL and Nested Clips}%
\label{sec:workflow_openedl_nested_clips}
-This is a real world usage case that provides an excellent example of how OpenEDL has been a
+This is a real world usage case\protect\footnote{credit fary54} that provides an excellent example of how OpenEDL has been a
revolution for \CGG{}. Advantages include: editing speed, clarity, ease of finding a specific item,
and movement of a subject block via \textit{Nest to media}.
The main concept of editing using OpenEDL in this real world case is to
See \href{https://youtu.be/bfYaBqVbdCo}{Video 4} (using French locale).
-\section{Workflow with multi-cam and external audio\protect\footnote{credit Armandux.}}%
+\section{Workflow with multi-cam and external audio}%
\label{sec:workflow_multicam_external_audio}
More on the multi-cam can be found in section \nameref{sec:multicamera_mixer}
-Let's take the case of a professional magician filmed in multicam while performing. Camera 1 records the magician's face; camera 2 the whole person and camera 3 the detail of the hands. There is also an external audio recorder to record the artist's voice in mono. So we will have three video tracks with their respective embedded audio tracks, plus an external audio track of good quality.
+Let's take the case of a professional magician filmed in multicam while performing\protect\footnote{credit Armandux.}. Camera 1 records the magician's face; camera 2 the whole person and camera 3 the detail of the hands. There is also an external audio recorder to record the artist's voice in mono. So we will have three video tracks with their respective embedded audio tracks, plus an external audio track of good quality.
-You can find the files to test the workflow that is described next at the following address: \small{\url{https://cinelerra-gg.org/download/testing/cinelerra-forum.zip}}
+You can find the files to test the workflow that is described next at the following address:
+%begin{latexonly}
+\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}
+
+\end{htmlonly}
[Media files are licensed under a \href{https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode}{CC 4.0 BY, NC, SA license}.]
\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}
\chapter{Capturing and Recording Media}%
\label{cha:capturing_recording_media}
+\index{capture}
+\index{recording}
\begin{figure}[htpb]
\centering
\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}
\section{Record Web Media in real-time}%
\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}
You can do real-time capture of a full transport stream of Broadcast TV. Record television programs using \CGG{} by setting up ahead of time to start recording later at the specified time. Then you can use \CGG{} to watch later and easily fast forward through the commercials or edit the program, deleting the commercials, to watch uninterrupted. Some details may be slightly different than what it is in the United States. There are 3 requirements you must have to take advantage of this capability.
\begin{figure}[htpb]
\centering
\includegraphics[width=0.99\linewidth]{channels02.png}
- \caption{Scanning in progress ($6\%$)}
+ \caption{Scanning in progress ($31\%$)}
\label{fig:channels02}
\end{figure}
\item Or press \textit{X-cancel} to terminate and dismiss the \textit{Recording} application.
\end{itemize}
-Figure~\ref{fig:recording04} shows the recording of a currently running broadcast TV program weather report.
+Figure~\ref{fig:recording04} shows the recording of a currently running broadcast TV program news report.
\begin{figure}[htpb]
\centering
\includegraphics[width=0.95\linewidth]{recording04.png}
- \caption{Recording in real-time a tv weather report}
+ \caption{Recording in real-time a TV news report}
\label{fig:recording04}
\end{figure}
The main menu pulldown, \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Playback A} and \texttt{B} Tabs, must be properly configured in order to take advantage of the Dual Screen Mode capability.
-In the main menu \textit{Window} pulldown there are \textit{Tile left} and \textit{Tile right} options for the 2 monitors. If you have only 1 monitor, you will see no change upon activating these options. Tiling is possible due to the existence of one long horizontal screen display buffer. Tile left takes \CGG{} and moves all of its windows to the $2^{nd}$ monitor/TV and Tile right puts it back to the $1^{st}$ monitor. The left and right monitors are the left part or right part of a Playback A/B Xwindow host referenced in the Video Config Playback A/B for separate X screens. Shortcuts for Tile left and Tile rights are the letters \texttt{a} and \texttt{b} on the keyboard once you have set \textit{Remote Control mode}. Below is a summary of the configuration letters:
+In the main menu \textit{Window} pulldown there are \textit{Tile left} and \textit{Tile right} options for the 2 monitors. If you have only 1 monitor, you will see no change upon activating these options. Tiling is possible due to the existence of one long horizontal screen display buffer. Tile left takes \CGG{} and moves all of its windows to the $2^{nd}$ monitor/TV and Tile right puts it back to the $1^{st}$ monitor. The left and right monitors are the left part or right part of a Playback A/B Xwindow host referenced in the Video Config Playback A/B for separate X screens. Shortcuts for Tile left and Tile rights are the letters \texttt{a} and \texttt{b} on the keyboard once you have set \textit{Remote Control mode}. Below is a summary of the configuration letters (only when in Remote Control mode):
\begin{description}
\item[a] select \textit{playback a} and tile windows left (all on monitor or laptop)
\item[c] select \textit{playback c} and tile windows left, but composer right (TV mode) This option has the effect of taking the Compositor window and moving it to the $2^{nd}$ monitor/TV without the surrounding borders interfering with the video.
\end{description}
-Since Dual Screen Mode is most widely used for either a demonstration or watching TV, you will want to take advantage of Remote Control mode as described in a following section. In the camera shots below, note the square red box that shows up in the upper left hand corner of the Viewer window (arrow pointing to it but it looks more orange than red) which denotes that the Application/Menu key was used to get into Remote Control mode.
+Since Dual Screen Mode is most widely used for either a demonstration or watching TV, you will want to take advantage of Remote Control mode as described in a following section. In the camera shots below, note the square red box that shows up in the upper left hand corner above the Viewer window, when visible, which denotes that the Application/Menu key was used to get into Remote Control mode.
-Figure~\ref{fig:two-monitors01} shows 2 monitors (could just as well be a big-screen TV for the second monitor) with Tile left where all of the \CGG{} windows are on the left most monitor. The big red arrow points to the little red square box indicating that Remote Control mode is in effect.
+Figure~\ref{fig:two-monitors01} shows 2 monitors (could just as well be a big screen TV for the second monitor) with Tile left where all of the \CGG{} windows are on the left most monitor. Note the little red square box in the far upper left corner indicating that Remote Control mode is in effect.
\begin{figure}[htpb]
\centering
\includegraphics[width=0.85\linewidth]{two-monitors01.png}
- \caption{Dual screen - initial}
+ \caption{Dual screen - initial view on the left monitor and showing part of the right monitor with 2 terminal windows}
\label{fig:two-monitors01}
\end{figure}
-Figure~\ref{fig:two-monitors02} shows 2 monitors with Tile right (b key) where all of the \CGG{} windows are on the right monitor. The left monitor shows the Suse distro logo and a couple of xterm type windows.
+Figure~\ref{fig:two-monitors02} shows 2 monitors with Tile right (b key) where all of the \CGG{} windows are on the right monitor. The partial view of the left monitor shows 2 xterm windows with landscape wallpaper background.
\begin{figure}[htpb]
\centering
\begin{figure}[htpb]
\centering
\includegraphics[width=0.85\linewidth]{two-monitors03.png}
- \caption{Dual screen - \CGG{} compositor on own screen windowed}
+ \caption{Dual screen - \CGG{} compositor on second monitor}
\label{fig:two-monitors03}
\end{figure}
-Figure~\ref{fig:two-monitors04} shows 2 monitors with Compositor window on the 2nd monitor in Fullscreen mode so that no \CGG{} borders are visible to distract from the picture. The big red arrow points to the little red square box indicating that Remote Control mode is in effect.
+Figure~\ref{fig:two-monitors04} shows 2 monitors with Compositor window on the 2nd monitor in Fullscreen mode so that no \CGG{} borders are visible to distract from the picture.
\begin{figure}[htpb]
\centering
\includegraphics[width=0.85\linewidth]{two-monitors04.png}
- \caption{Dual screen - \CGG{} compositor on own screen full screen}
+ \caption{Dual screen - \CGG{} compositor on second monitor in full screen mode}
\label{fig:two-monitors04}
\end{figure}
\subsection{Remote Control for DVB}%
\label{sub:remote_control_dvb}
+\index{capture!remote control for DVB}
-\CGG{} DVB recording/playback can now easily be done in \textit{couch potato} mode using a remote control. This comes in handy when you want to playback on a big TV screen for multiple person viewing. You can use the Application/Menu key on the keyboard to toggle between standard \CGG{} usage or a Dispatcher methodology through use of a remote control, an Android programmed device such as a tablet, or keyboard. The Application/Menu key on most keyboards is between the Alt and Ctrl keys on the right hand side bottom and depicts a menu on it either with or without a pointer (see image below). An ati-x10 Remote Control device (figure~\ref{fig:remote01}) is currently working with \CGG{} and other remote controls may work but have never been tried. The red/orange box on the top left main screen of \CGG{} indicates Dispatcher Method access is activated which allows for keyboard grab which routes all key strokes until toggled off. Below are the currently defined operations.
+\CGG{} DVB recording/playback can now easily be done in \textit{couch potato} mode using a remote control. This comes in handy when you want to playback on a big TV screen for multiple person viewing. You can use the Application/Menu key on the keyboard to toggle between standard \CGG{} usage or a Dispatcher methodology through use of a remote control, an Android programmed device such as a tablet, or keyboard. The Application/Menu key on most keyboards is between the Alt and Ctrl keys on the right hand side bottom and depicts a menu on it either with or without a pointer (see image below). THe Menu key is keycode 135. An ati-x10 Remote Control device (figure~\ref{fig:remote01}) is currently working with \CGG{} and other remote controls may work but have never been tried. The red box on the top left main screen of \CGG{} indicates Dispatcher Method access is activated which allows for keyboard grab which routes all key strokes until toggled off. Below are the currently defined operations.
\begin{figure}[htpb]
\centering
- \includegraphics[width=0.1\linewidth]{remote01.png}
+ \includegraphics[width=0.9\linewidth]{remote01.png}
\caption{Ati-x10 Remote}
\label{fig:remote01}
\end{figure}
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
\subsection{Android Remote Control for DVB}%
\label{sub:android_remote_control_dvb}
-\CGGI{} has Android remote interface code (figure~\ref{fig:remote02}). Any device, such as a tablet or a phone, can be used as long as it is running the Android operating system. Programming an Android Remote Control for DVB is a bit complicated at first, but becomes pretty simple after a bit.
+\CGGI{} has Android remote interface code (figure~\ref{fig:remote02}). Any device, such as a tablet or a smart phone, can be used as long as it is running the Android operating system. Programming an Android Remote Control for DVB is a bit complicated at first, but becomes pretty simple after a bit.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.9\linewidth]{remote02.png}
+ \caption{Interface tab shows Android Remote Control}
+ \label{fig:remote02}
+\end{figure}
\begin{enumerate}
\item The Android Remote Control requires you to download and install the Android \textit{CineRmt} app package (apk). To install it simply download it (any way you can) to your phone or tablet and click it to install, if it doesn't run automatically.
\item After you install the new phone/tablet app in step 1, start it up from your apps menu.
\end{enumerate}
-\begin{figure}[htpb]
- \centering
- \includegraphics[width=0.9\linewidth]{remote02.png}
- \caption{Interface tab shows Android Remote Control}
- \label{fig:remote02}
-\end{figure}
-
-Before you can use it, the Android device must have the ip address of your computer entered into the configuration menu. The PC you are running \CGG{} on and the Android device have to be on the same network. You can tell it is in communication by tapping the \texttt{Power} (menu) button. When the remote is operated with the \textit{Power} (menu) button, there is a little orange box on the upper left corner of the display to indicate the remote state is active. If you do not see the little orange box when the menu key is tapped, the communication is broken and must be fixed before proceeding. Follow the directions in the paragraph below.
+Before you can use it, the Android device must have the ip address of your computer entered into the configuration menu. The PC you are running \CGG{} on and the Android device have to be on the same network. You can tell it is in communication by tapping the \texttt{Power} (menu) button. When the remote is operated with the \textit{Power} (menu) button, there is a little red box on the upper left corner of the display to indicate the remote state is active. If you do not see the little red box when the menu key is tapped, the communication is broken and must be fixed before proceeding. Follow the directions in the paragraph below.
BIG NOTICE: the firewalls in your computer and wifi router can stop this thing dead. Re-configuring a firewall is tricky and varies from distro to distro. If possible, during setup it is suggested that you disable the firewall temporarily. For those with advanced skills, use tcpdump or wireshark to look for udp messages from the IP address of the device.
SECTION NOT COMPLETE – (manualandroid)
-Figure~\ref{fig:remote03} shows an Android Tablet that can be used as a Remote Control for \CGG{} Recording and Playback.
+Figure~\ref{fig:remote03} shows an Android Smartphone that can be used as a Remote Control for \CGG{} Recording and Playback.
\begin{figure}[htpb]
\centering
- \includegraphics[width=0.5\linewidth]{remote03.png}
- \caption{A Tablet with Android Remote Control}
+ \includegraphics[width=0.7\linewidth]{remote03.png}
+ \caption{A Smart Phone with Android Remote Control}
\label{fig:remote03}
\end{figure}
\section{The commercial DB}%
\label{sec:commercial_db}
+\index{capture! commercials database}
While watching broadcast television, it is possible to use \CGG{} to automatically mute commercials being aired during a broadcast capture. Visual muting as well as sound muting is done! You can NOT use ffmpeg for the format when working with the \textit{commercial DB}. This database that was added is a \textit{novel architecture} shared memory database, a \textit{Traveling Data Base} (TDB). With TDB you have direct access to the shared database presence (instead of having to go to the server).
\section{Transfer VHS/DVD Media or Video8/Hi8 Tapes into \CGG{}}%
\label{sec:transfer_vhs_dvd_tapes_into_cinelerra}
+\index{recording!transfer VHS/DVD media}
If you want to transfer the data on a VHS tape, DVD disc, or Video8/Hi8 Tapes into \CGG{}, you
can do so by playing the media and recording while playing. This captures the media, which you
\subsection{Use Case \#1 – EasyCap Model \# DC60}
\label{sub:use_case_easycap_model_dc60}
+\index{capture!EasyCap model}
A very specific case using an Easy CAPture USB 2.0 Video Adapter with Audio, Model \#DC60 (supports
NTSC and PAL) is shown here next. The setup for this device is seen in figure~\ref{fig:recording-05}.
[ 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}
In the case of the Hauppauge 9500 WinTV-HVR Hybrid TV stick, the setup is similar as in case
\#1 with the major exception being that the Video In, Record Driver should be Video4Linux2 MPEG.
\chapter{Rendering}%
\label{cha:rendering}
+\index{rendering}
-Rendering takes a section of the timeline, performs all the editing,
+Rendering takes a section of the timeline, \index{active region} performs all the editing,
effects and compositing, and creates a new media file. You can then
delete all the source assets, play the rendered file, or bring it
back into \CGG{} for more editing. All rendering operations are
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}
+\index{rendering!single file}
Use the \textit{File} pulldown and select Render to start the render dialog
(figure~\ref{fig:render}). Then choose the desired parameters.
\begin{figure}[htpb] \centering
- \includegraphics[width=0.7\linewidth]{render.png}
+ \includegraphics[width=0.5\linewidth]{render.png}
\caption{Example of the Render menu}
\label{fig:render}
\end{figure}
\begin{description}
\item[Select a file to render to:] enter the path and filename to
write the rendered file to in the textbox below.
-\item[File Format:] use the down arrow to see file format options.
+\item[File Format:] \index{file format} use the down arrow to see file format options.
For ffmpeg, which has its own set of options, you will then have to
select an ffmpeg file type from the down arrow choices. The format
of the file determines whether you can render audio or video or
\end{figure}
\begin{description}
-\item[Wrench:] select the \textit{wrench} next to each toggle to set
+\item[Wrench:] \index{wrench} select the \textit{wrench} next to each toggle to set
compression parameters. If the file format can not store audio or
video the compression parameters will be blank. If \textit{Render
audio tracks} or \textit{Render video tracks} is selected and the
eventually would become \texttt{/movies/track.wav001} and so on.
Filename regeneration is only used when either render farm mode is
active or creating new files for every label is active.
-\item[Render range:] choices are \textit{Project},
+\item[Render range:] \index{active region} choices are \textit{Project} \index{project},
\textit{Selection}, \textit{In/Out points}, and \textit{One Frame}
for single images like Tiff. For these images, Render range will
have \textit{One Frame} automatically checked and all of the others
check this box. It gives you the chance to work on something else
while waiting and still be immediately notified when the render is
complete.
-\item[Render Profile:] another convenience feature to take advantage
+\item[Render Profile:] \index{rendering!profile} another convenience feature to take advantage
of if you use specific render formats frequently, is to save that
profile for future usage without having to set it up again.
\item[Save Profile:] after setting up your render preference
- formats, use the save profile button to save it.
+ formats, do not forget to type in a format name and then use the save profile
+button to save it. The named/saved Profiles will be saved in your
+\$HOME/.bcast5/Cinelerra\_rc file where it can be carefully modified.
\item[Delete Profile:] if you want to delete a saved profile,
highlight the one you no longer want and delete.
-\item[Insertion strategy:] select an insertion mode from the
+\item[Insertion strategy:] \index{insertion strategy} select an insertion mode from the
available choices as seen when you click on the down arrow on the
right hand side of the option. The insertion modes are the same as
with loading files. In the case if you select “insert nothing” the
audio output is pasted into the audio tracks.
\end{description}
+
+\subsection{Extra “cin\_” Options for Render with FFmpeg}%
+\label{sub:extra_cin_option_ffmpeg}
+\index{rendering!ffmpeg options}
+
+There are several special parameters that can be used in the ffmpeg
+options file to pass values to the codecs that are not normally
+available. They're called Global Options. These are explained
+below.
+
+\paragraph{cin\_pix\_fmt} The Render menus allows you to choose the
+codec input pixel format (figure~\ref{fig:yuv420}). The Pixels
+selection provides the available pixel format options for the chosen
+codec type; valid choices vary for the different file types. This
+list represents the formats that the codec advertises. It is not
+always complete, and it may include options that are not legal with
+all parameter configurations.
+
+\begin{figure}[htpb] \centering
+ \includegraphics[width=1.0\linewidth]{yuv420.png}
+ \caption{Render \& Video Preset menus displaying Pixel choices}
+ \label{fig:yuv420}
+\end{figure}
+
+\begin{itemize}
+ \item The \textit{Bitrate}, \textit{Quality}, and \textit{Pixels}
+ fields are only updated when the Video Options are reloaded. This
+ occurs when you either change the ffmpeg file format, or video
+ presets compression fields.
+ \item If the video options preset has \textit{cin\_pix\_fmt}
+ defined, its value will be loaded as the default. If you override
+ the default, the value you specify will be used.
+ \item If the video options preset does not have
+ \textit{cin\_pix\_fmt}, the default pixel format will be computed by
+ ffmpeg (\textit{avcodec\_find\_best\_pix\_fmt\_of\_list}), using the
+ session format as the source choice. The \textit{best} is usually
+ the format which is most similar in color and depth.
+ \item If no choices are available, yuv420p for video will be used.
+ \item You can also specify ffmpeg pixel formats which are not in the
+ list. The list is provided by ffmpeg as input selection, but is
+ more like suggestions than fact. For example, the raw formats can
+ take almost any format, but the rawvideo codec actually specifies no
+ legal formats. Note that if you want a very specific Bitrate you must
+ make sure there is not conflicting parameter values set such as Quality
+ or CRF.
+\end{itemize}
+
+\noindent Some option files provide \textit{cin\_pix\_fmt} to
+suggest a choice for good quality output or to prevent parameter
+errors when the other provided parameters conflict with the
+\textit{best} pixel format. This is the case in
+\texttt{faststart\_h264.mp4} where the \textit{profile=high}
+parameter dictates pixel format must be \texttt{yuv420p}.
+
+\paragraph{cin\_bitrate} If you specify the bitrate, you can not
+specify the quality or CRF.\\ Example: \textit{cin\_bitrate=2000000}
+
+\paragraph{cin\_quality} If you specify the quality, you can not
+specify the bitrate.\\ Example: \textit{cin\_quality=7}
+
+\paragraph{cin\_stats\_filename} This parameter is useful for 2 pass
+operations.\\ Example: \texttt{cin\_stats\_filename
+ /tmp/cin\_video\_vp9\_webm}
+
+\paragraph{cin\_sample\_fmt} For audio the preset sample format
+default is computed in a similar way as stated above for video or
+can be set with the \textit{cin\_sample\_fmt} parameter
+(figure~\ref{fig:audio}). If no choices are provided, s16 will be
+used.\\ Example: \textit{cin\_sample\_fmt=s16}
+
+\begin{figure}[htpb] \centering
+ \includegraphics[width=0.7\linewidth]{audio.png}
+ \caption{Render menu showing where Samples is}
+ \label{fig:audio}
+\end{figure}
+
+\paragraph{Private Options} (muxers). In the window of the
+\textit{wrench} in addition to the \textit{View} button, which
+allows more global options and changes to the formats, there is an
+additional \textit{Format} button that allows you to modify the
+Private Options, i.e.\ relating to specific muxing formats. More
+information on all these options can be found at
+\href{https://ffmpeg.org/ffmpeg-all.html#Format-Options}{ffmpeg.org}
+sections 19 and 21. See also \nameref{sub:modifying_ffmpeg_cinelerra}.
+
+Render presets in \CGG{} should work Out Of the Box. You can still configure the \textit{Global Options} and \textit{Private Options} manually. Finding the combination of parameters that best suits your needs, or simply finding working (\textit{legal}) combinations, requires studying each codec in depth. You can start by looking in Wikipedia until you get to download and study the \textit{white papers} of the codecs of interest. In any case, you must then start a long experimental phase, trying presets with different configurations or creating new ones, until you get satisfactory results. If you create new presets it is a good idea to make them known on the mailing list ({\small \url{https://lists.cinelerra-gg.org/mailman/listinfo/cin}}) or on the MantisBT Bug Tracker ({\small \url{https://www.cinelerra-gg.org/bugtracker/my_view_page.php}}) so that they can be integrated into subsequent versions of \CGG{}. For an introduction see \nameref{sec:overview_formats}.
+
+\section{Some Specific Rendering}%
+\label{sec:some_specific_rendering}
+
+\noindent The next few pages relate to rendering for specific common
+cases.
+
+\subsection{FFmpeg Common H.264 Rendering}%
+\label{sub:ffmpeg_h264_rendering}
+
+Because H.264 is so widely used, the method in \CGG{} Infinity is
+outlined below. These setup steps make it easy to just get started.
+
+\begin{itemize}
+ \item File $\rightarrow$ Render
+ \item File Format $\rightarrow$ FFMPEG + mp4
+ \item Video Wrench $\rightarrow$ Preset $\rightarrow$ h264.mp4 +
+ bitrate: 6000000 (or whatever) + OK
+ \item Audio Wrench $\rightarrow$ Preset $\rightarrow$ h265.mp4 +
+ bitrate: 224000 (or whatever) + OK
+ \item Set your target path in: Render $\rightarrow$ Select a file to
+ render to
+ \item Set your timeline in: Render $\rightarrow$ Render range +
+ click Project
+ \item Set your insertion strategy: Replace project (or whatever)
+ \item Press OK to start rendering.
+\end{itemize}
+
+\subsection{Lossless Rendering}%
+\label{sub:loseeless_rendering}
+\index{rendering!lossless}
+
+Lossless means that in the compression of a file, all of the
+original data, every single bit, can be recovered when the file is
+uncompressed. This is different than \textit{lossy compression}
+where some data is permanently deleted so that when uncompressed,
+all of the original data can not be exactly recovered. Lossy is
+generally used for video and sound, where a certain amount of
+information loss will not be detected by most users or the playback
+hardware does not reproduce it anyway -- it is a trade-off between
+file size and image/sound quality. The files created will be more
+than 10 times larger than usual. Most players will not be able to
+decode lossless as the bitrate will overwhelm the device.
+
+For x264 lossless compression to work, the only color model allowed
+here is yuv420p. Any other specification will be converted to
+yuv420p and the data will be modified. Also, keep in mind that the
+YUV color model has to be converted to RGB, which also modifies the
+data.
+
+To use x264 lossless rendering -- choose File format of ffmpeg, m2ts
+in the Render window. Click on the Video wrench, which brings up
+the Video Preset window and scroll down in the Compression filebox
+and choose \texttt{lossless.m2ts}. \textit{Preset=medium} is the
+default, but can be varied from \textit{ultrafast} (least amount of
+compression, but biggest file size) to \textit{veryslow} (most
+amount of compression, but still HUGE) in the parameter box where
+you see $qp=0$. This option is also available for bluray creation.
+
+\subsection{Two-pass Encoding with FFmpeg}%
+\label{sub:two_pass_encoding_ffmpeg}
+\index{rendering!ffmpeg two-pass encoding}
+
+In \CGG{} for two-pass, you need to run ffmpeg twice, with the same
+settings, except for designating the options of pass~1 for the first
+pass and then pass~2. In pass~1, a logfile that ffmpeg needs for
+the second pass is created. In pass~1 the audio codec should be
+specified that will be used in pass~2. For more information on
+ffmpeg 2-pass, check
+\href{https://trac.ffmpeg.org/wiki/Encode/H.264}{ffmpeg.org}.
+Different libraries may have different requirements and you will
+probably have to determine this by looking online at ffmpeg or
+looking directly at that code.
+
+This 2 line ffmpeg 2-pass operation can be functionally duplicated
+in \CGG{} in the steps below them:
+
+\begin{lstlisting}[style=sh]
+ ffmpeg -y -i $INPUT \
+ -c:v libx264 -b:v 2600k -pass 1 \
+ -c:a aac -b:a 128k -f mp4 /dev/null && \
+ ffmpeg -i $INPUT \
+ -c:v libx264 -b:v 2600k -pass 2 \
+ -c:a aac -b:a 128k $OUTPUT.mp4
+\end{lstlisting}
+
+\begin{enumerate}
+ \item After you have completed your editing, do a Save Session with
+ \texttt{File $\rightarrow$ Save as}\dots Before starting, be sure
+ your session is ready for batch render. That is, positioned at the
+ beginning and nothing selected.
+ \item Bring up \texttt{File $\rightarrow$ Batch Render}\dots where
+ you will do the setup.
+ \item Click on the \textit{Delete} box to remove old jobs
+ highlighted in the bottom listbox.
+ \begin{itemize}
+ \item For the \textit{File Format} choose ffmpeg and mp4 for the
+ type.
+ \item Set \textit{Output path} to the path and filename for the
+ render output file.
+ \item Click on \textit{Use Current EDL} to use the designated EDL
+ Path file.
+ \item Click on \textit{New} and you will see a new highlighted job
+ show up in the listbox at the bottom.
+ \item Use the Audio wrench to set bitrate to $128000$ ($128k$ as
+ in ffmpeg example above).
+ \item Click checkmark OK\@. Open the video tools with the video
+ wrench.
+ \item Set the Video Compression to \textit{h264.mp4} (as seen in
+ the example).
+ \item Set the bitrate to $2600000$ ($2600k$ as in ffmpeg example
+ above).
+ \item Add the following 2 lines after the first line:
+ \begin{lstlisting}[style=sh]
+ flags +pass1
+ passlogfile /tmp/"{temporary log file name}.log"
+ \end{lstlisting} Click checkmark OK.
+ \end{itemize}
+ \item Click on \textit{New} to create the second pass job. You will
+ see this second job in the listbox below. Use the Video wrench and
+ change pass1 to pass2 as follows.
+ \begin{lstlisting}[style=sh]
+ flags +pass2
+ \end{lstlisting}
+ \item Click checkmark OK.
+ \item Click on the \textit{Start} box and watch it go!
+ \item You can now check the output file for results. At the time
+ this was documented, \textit{rc=2pass} will be in the output.
+\end{enumerate}
+
+If you need to re-render this, the Batch Render will still be set up
+but you have to click on the \textit{Enabled} column in the listbox
+to re-enable the jobs to run which puts an X there. Click Start
+again. You can reuse batch job using the \textit{save jobs} and
+\textit{load jobs} buttons in the batch render dialog.
+
+\paragraph{Render shortcuts for webm, h264, h265} are available by
+using the option files that are already set up for this purpose.
+Use the render menu as usual, with ffmpeg/mp4, choose h264 or h265
+\textit{pass1of2\_h26x} for the video and
+\textit{passes1and\-2\_h26x} for the audio; with ffmpeg/webm, choose
+\textit{pass1of2\_vp9}. When that is finished, you will have to use
+the render menu again and this time for video, choose
+\textit{pass2of2\_h26x} or \textit{pass2of2\_vp9}. The logfile is
+hard coded in the options file so will write over any currently
+existing logfile if you do not change it before you start the
+render.
+
+\paragraph{Requirements for some other libraries} (used instead
+of \textit{flags +pass1} \& \textit{passlogfile}):
+\begin{description}
+ \item[x265:] add this line:
+ \begin{lstlisting}[style=sh]
+ x265-params=pass=1:stats=/tmp/{temporary-log-file-name}.log
+ \end{lstlisting} at the time this document was written, you should
+ see in the output: \textit{stats-read=2}
+ \item[libvpx-vp9, xvid, and huffyuv:]~
+ \begin{lstlisting}[style=sh]
+ cin_stats_filename /tmp/{temporary-log-file-name}.log
+ flags +pass1 (or flags +pass2 for the second pass)
+ \end{lstlisting}
+\end{description}
+
+\textit{NOTE:} for vp9, the best Pixels is \textit{gbrp}
+
+\subsection{Use case: High Efficiency Video Coding (HEVC)}%
+\label{sub:use_case_hevc}
+
+An example of video profile based on CRF, a quality-controlled
+variable bitrate, instead of fixed quality scale (ABR). HEVC
+(H.265) was developed as a successor to AVC (H.264) to more
+efficiently compress the future large amounts of data from 2/4/8k
+videos. In comparison to AVC, an average saving of around 30
+percent can be assumed for the same quality. Because HEVC is not
+bound to any size format, it is suitable for virtually any image
+size.
+
+The following example is HD and FullHD oriented and produces a
+picture quality similar to the Blu-ray with some limitations. As
+container Matroska (\texttt{.mkv}) is used, but also mp4 and others
+are possible.
+
+\begin{lstlisting}[style=sh]
+ matroska libx265
+
+ # CRF 16 creates a balanced compromise
+ # between quality and file size.
+ crf=16
+
+ # Preset changes encoding speed and generally
+ # degrades the overall result. Medium (default)
+ # always fits.
+ preset=medium
+
+ # Additional parameters that are passed on to the codec.
+ # me=star improves the search for very fast
+ # movements, but slows down the encoding.
+ #x265-params=me=star
+
+ # Keyint does FFmpeg automatically, otherwise
+ # the setting must match the frame rate.
+ #keyint_min=25
+
+ # Profile does FFmpeg automatically.
+ #profile=high
+
+ # Source sRBG and retention of color space.
+ # 720/1080=bt709 if no profile set. Useful
+ # for formats smaller than 720 if no lossy
+ # conversion is desired.
+ colorspace=bt709
+ color_trc=bt709
+ color_primaries=bt709
+
+ # Output in 10 bit, prevents 8-bit step formation
+ pixel_format=yuv420p
+\end{lstlisting}
+
+\noindent \textit{NOTE:}
+
+A CRF of 16 delivers satisfactory results in most cases. However, if
+the video material is really \emph{grainy}, a CRF~16 can lead to
+unwanted large files. In this case, a trial export of perhaps one
+minute should be performed. The resulting bit rate can be used to
+correct the CRF to 17,\,18,\,19\ldots -- remember, a CRF of $0$ (zero)
+means lossless, the higher the number the stronger the lossy
+compression. The approximate calculation of the final file size can
+be extrapolated from the sample export.
+
+The color space information must be used explicitly so that it can
+be included in the video. \CGG{} or FFmpeg does not write it by
+itself. Without this information the players (e.\,g.\
+\href{https://mpv.io/}{mpv}) stick to the dimensions of the video
+and take the assumed color model from a table. With videos in the
+dimensions from 720 to 1080 this is bt709. For smaller dimensions,
+e.\,g.\ DVD, bt601 is assumed and for 4k and above it is
+bt2020. Normally this is not a problem, but if you want to export a
+FullHD without color loss to a smaller size like 576 for example,
+you have to inform the encoder as well as the decoder of the
+player. This also applies if the videos are to be loaded on video
+platforms, where they are then converted into videos of different
+sizes. It is a security measure to prevent false colors, such as the
+color profiles in digital photos and the copies made from them.
+
+The HEVC tuning has not been considered here, because it is is
+rarely used and requires background knowledge.
+
+Further links:
+\begin{itemize}
+ \item \href{http://x265.readthedocs.org/en/default/}{x265
+ Documentation}
+ \item \href{http://x265.readthedocs.org/en/latest/cli.html}{x265
+ Command Line Options}
+ \item \href{http://x265.readthedocs.org/en/latest/presets.html}{x265
+ Presets/Tuning}
+\end{itemize}
+
+
+\subsection{YouTube with \CGG{}}%
+\label{sub:youtube_with_cinelerra}
+\index{rendering!youtube preset}
+
+To create a youtube or dailymotion video, you can easily follow the steps below. You will have to learn a lot more about \CGG{} to take full advantage of its capabilities and make some really special videos, but this is just to get a start and to see the possibilities.
+
+\begin{enumerate}
+ \item Start \CGG{}; usually you can do this by clicking on \CGG{} icon or key in \texttt{{cin\_path}/bin/cin}.
+ \item In the Program window on the lower left side of your screen, left mouse click the \textit{File} pulldown.
+ \item You will see \textit{Load files} as the second choice so left mouse click this and find your video file to
+ load, highlight it, and check the green checkmark in the lower left hand corner to get it loaded.
+ \item Edit your video in the Program window using the basic commands of:
+ \begin{itemize}
+ \item play and then stop using the space bar
+ \item move the mouse and then left click to move the insertion (location) pointer
+ \item cut a section out by holding down the left mouse and drag, then key in “x” to cut or “c” to copy
+ \item paste a copy or cut section by moving the insertion pointer, then key in “v”
+ \end{itemize}
+ \item Add a title by highlighting the \textit{Video Effects} in the right hand side Resources window; then
+ highlighting the \textit{Title} icon and dragging it to the Program window video track and dropping.
+ \item Click on the middle icon button (looks like a magnifying glass) on the brown colored Title bar to
+ bring up the Title window bottom text box and key in a title.
+ \item Use the \textit{File} pulldown to select \textit{Render} to create the desired video. In the \textit{Render} window just next to the empty box to the right of the \textit{ffmpeg} file format, click on the down arrow shown there
+ to see the choices and pick \textit{youtube}. Then move back up to key in the path and filename to render
+ to. It will pick all of the defaults automatically for you so then just click on the green checkmark to
+ have it start. There is a progress bar in the main window, very bottom of the right hand side.
+ \item Key in “q” in the main window to get out of \CGG{} and yes or no to save your edit session.
+\end{enumerate}
+
+Youtube will allow the upload of the resulting rendered file as named. However, Dailymotion requires that the file be named with an acceptable extension so you must rename the output file to have the extension of .webm instead of .youtube
+
+There are currently 6 specific variations within the ffmpeg (file format) / youtube (file type) for different video options. You see these when you click on the wrench to the right of the word Video and then the Compression down arrow in the Video Preset window. The first 3 are based on Webm/Vp9\protect\footnote{credit by Frederic Roenitz} and contain basic comments of usage and where to find more information.
+
+The first 3 below, plus any of the VP9 files under the file type of \textit{webm} are the recommended options to use because they are freely usable in any circumstance.
+
+\begin{center}
+ \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}
+
+For more details and options on VP9, see: {\small\url{https://developers.google.com/media/vp9}}
+
+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}{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}
+
+These same steps have been verified to work for creating Dailymotion videos -- however, the created files must be renamed before uploading to change the youtube extension to webm instead for Dailymotion.
+
+\subsection{VP9 parameters}%
+\label{sub:vp9_parameters}
+\index{rendering!VP9 parameters}
+
+\textsc{VP9}\protect\footnote{credit Frederic Roenitz} is a video codec licensed under the BSD license and is
+considered open source,
+% Sisvel Announces AV1 Patent Pool, March 10, 2020
+% https://www.streamingmedia.com/Articles/ReadArticle.aspx?ArticleID=139636
+% Webm / VP9 is a media file format which is free to use under the
+% BSD license and is open-source; thus there are no licensing
+% issues to be concerned about.
+the \textsc{Webm} container is based on \textsc{Matroska} for video
+and \textsc{Opus} for audio. There are some common \textsc{VP9} rendering
+options files that support creation of video for YouTube,
+Dailymotion, and other online video services.
+
+YouTube easy startup steps are documented above.
+
+Below is one of the \textsc{VP9} rendering options file with documentation for specifics:
+
+\textbf{webm libvpx-vp9}
+
+from {\small \url{https://developers.google.com/media/vp9/settings/vod/}}
+
+1280x720 (24, 25 or 30 frames per second)
+
+Bitrate (bit rate)
+
+\textsc{VP9} supports several different bitrate modes:
+
+\textit{mode:}
+
+\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}}
+ \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}
+
+\textit{Note 1}: Bitrate is specified in kbps, or kilobits per second. In video compression a kilobit is generally assumed to be 1000 bits (not 1024).
+
+\textit{Note 2:} Other codecs in FFMpeg accept the \textit{-crf} parameter but may interpret the value differently. If you are using \textit{-crf} with other codecs you will likely use different values for VP9.
+
+\texttt{bitrate=1024k}\\
+\texttt{minrate=512k}\\
+\texttt{maxrate=1485k}\\
+\texttt{crf=32}
+
+\textit{Tiling} splits the video into rectangular regions, which allows multi-threading for encoding and decoding. The number of tiles is always a power of two. 0=1 tile; 1=2; 2=4; 3=8; 4=16; 5=32\\
+\texttt{tile-columns=2}
+
+(modified from {\small \url{https://trac.ffmpeg.org/wiki/EncodingForStreamingSites}})
+
+To use a 2 second \textit{GOP} (Group of Pictures), simply multiply your output frame rate $\times$ 2. For example, if your input is \textit{-framerate 30}, then use \textit{-g 60}.\\
+\texttt{g=240}
+
+number of \textit{threads} to use during encoding\\
+\texttt{threads=8}
+
+\textit{Quality} may be set to good, best, or realtime\\
+\texttt{quality=good}
+
+\textit{Speed}: this parameter has different meanings depending upon whether quality is set to good or realtime. Speed settings 0-4 apply for VoD in good and best, with 0 being the highest quality and 4 being the lowest. Realtime valid values are 5-8; lower numbers mean higher quality\\
+\texttt{speed=4}
+
+\subsection{Piping Video to a Command Line}%
+\label{sub:piping_video_command_line}
+\index{rendering!command line}
+
+You can pipe a video to any command line on the computer, such as
+ffmpeg. This can be especially useful with raw video files. Next
+is an example usage.
+
+\begin{enumerate}
+ \item on a terminal window create a named pipe file, for example:
+ \begin{lstlisting}[style=sh]
+ mknod /tmp/piper.yuv p
+ \end{lstlisting} load your video and do your editing
+ \item set up your Render (\texttt{Shift-R}), you can choose a raw
+ format such as \textit{yuv} or \textit{rgb}
+ \item for the filename \textit{Select a file to render to}, use the
+ named pipe as created in step 1 (\texttt{/tmp/piper.yuv})
+ \item for \textit{Insertion Strategy}, you will want to make sure to
+ select \textit{insert nothing}
+ \item click for OK on the green checkmark.(the \CGG{} gui will look
+ like it is hanging while waiting for a command line to use the
+ pipe.)
+ \item on the terminal window, keyin your command, for example:
+ \begin{lstlisting}[style=sh]
+ /mnt0/build5/cinelerra-5.1/thirdparty/ffmpeg-3.4.1/ffmpeg -f \
+ rawvideo -pixel_format yuv420p -video_size 1280x720 \
+ -framerate 30000/1001 -i /tmp/piper.yuv /tmp/pys.mov
+ \end{lstlisting}
+\end{enumerate}
+
+A slightly different option can be used instead that may be more
+familiar to some. In the render menu after choosing the File Format
+of \textit{ffmpeg}, use the pulldown to choose \textit{y4m} as the
+file type. This choice results in putting a header on the rendered
+output with some pertinent information that can be used for ffmpeg
+processing thus alleviating the requirement for
+\textit{pixel\_format}, \textit{video\_size}, and \textit{framerate}
+on the ffmpeg command line. In this case the format is
+\textit{yuv4mpegpipe} instead of \textit{rawvideo}. An example
+command line would look as follows (assuming the created pipe is
+called \texttt{piper.y4m}):
+\begin{lstlisting}[style=sh]
+ ffmpeg -f yuv4mpegpipe -i /tmp/piper.y4m -vcodec libx264 /tmp/test.mp4
+\end{lstlisting}
+
+\subsection{Faststart Option for MOV type files}%
+\label{sub:faststart_option_mov0}
+
+If you have mov video and want to be able to start playing without
+having to first load the entire video, \textit{-movflags=+faststart}
+is needed for ffmpeg to put the meta-data, known as the \textit{moov
+ atom}, at the beginning of the file. Otherwise, ffmpeg puts this
+atom at the end of the video file which means you have to wait to
+play until the whole video is loaded. Or worse yet, if the file
+becomes damaged in the middle and you can not get to the end, you
+won’t be able to play anything.
+
+Now you can have the \textit{moov atom} put on the front of the file
+(automatically via a second pass). To do this, when rendering using
+ffmpeg \& either the mp4 or qt format/container, click on the
+video/audio wrenches and choose \textit{faststart\_h264}. With the
+\textit{qt} format, settings will just be the default whereas the
+\textit{mp4} format uses the highest quality and lowest file size as
+possible, but you can easily modify these options in the associated
+Video Preset textbox.
+
+\section{About Image Sequences}%
+\label{sec:about_image_sequences}
+\index{image sequence}
+
+\CGG{} supports image sequences with both decoding and encoding.
+
+\CGG{} by default uses ffmpeg as encoding/decoding engine but we can disable it to have the specific internal engine available. See \nameref{sec:ffmpeg_early_probe_explanation} on how to switch between engines. With the internal engine we can create and load sequences of OpenEXR; PNG; TIFF; TGA; GIF; PPM and JPEG. There is also support for DPX sequences, but only in read and without rendering presets. With ffmpeg we can create and load DPX sequences or create a custom preset for any kind of image. Using these formats results in great timeline efficiency and high video quality at the cost of taking up a lot of space because they are uncompressed (or with lossless compression).
+By rendering, you will get as many still images as there are frames in the project, plus a \textit{file-list} (or \textit{TOC}) that indexes the images. A good practice is to create a folder to contain the images (for example \texttt{/tmp/img\_seq/}) and then open the rendering window in \CGG{} and set a serial and increasing number as the name (for example: \texttt{/tmp/img\_seq/image \%05d.png}). \textit{image} is a generic name chosen at will; $\%$ creates a progressive sequence of distinct images; $05d$ indicates how many digits the image number will be, in this case 5 digits to go from $00000$ to $99999$.
+Once we have our folder of images, if we want to import it in a project just load the file-list, which includes the link to all the files of the sequence.
+To learn more about using and creating a preset with ffmpeg of an image sequence, see \nameref{sec:ffmpeg_image2_streams} and/or \nameref{sec:image_sequence_creation}.
+
+\section{Data storage formulas}%
+\label{sec:data_storage_formulas}
+\index{data storage}
+
+If we are dealing with large projects and poorly compressed formats, we will get large files that are difficult to manage and take up a lot of space on the HDD. We present some simple formulas to be able to calculate the space that will be occupied and the data rates we have to deal with:
+
+\begin{description}
+ \item[Frame size]
+
+ \[ \dfrac{Width \times Height [pixels] \times BitDepth [bits/pixel] \times Color}{8 [bit/Byte]} \]
+ \[= ... [MB/frame] \]
+ \item[File size]
+
+ \[ Frame size [MB/frame] \times frames [frame] = ... [MB] \]
+ \item[Data Rate]
+
+ \[ Frame size [MB/frame] \times fps [frame/sec] = ... [MB/sec] \]
+ \item[Data in 1 Hour]
+
+ \[ \dfrac{Data Rate [MB/sec] \times 3600 [sec]}{1024MB/GB} = ... [GB] \]
+\end{description}
+
\section{Batch Rendering}%
\label{sec:batch_rendering}
+\index{batch rendering}
-Batch Rendering automates the rendering of audio/video files in that
+Batch Rendering as implemented in \CGG{} is considered to be more of
+an advanced feature and careful usage is advised. It automates the
+rendering of audio/video files in that
you can establish a set of job parameters, save them, and use them
-repeatedly. It also allows for \CGG{} to be run by external
-programs, with no need for the user to manually interact with the
-user interface (figure~\ref{fig:batch01}).
-
-If you want to render many projects to media files without having to
-constantly set up the render dialog for each one, batch rendering is
-a more efficient method of rendering. In the Batch Render menu, you
-specify one or more \CGG{} project XML files, the EDL, to render and
-unique output files for each. (The EDL is the Edit Decision List or
-the set of changes to be applied to the project and media files.)
-Then \CGG{} loads each project file and renders it
-automatically. The project XML files, combined with the settings for
-rendering an output file, are called a batch. This allows a large
-amount of media to be processed without user intervention.
+repeatedly (figure~\ref{fig:batch01}). It also allows for \CGG{} to
+be run by external programs, with no need for the user to manually
+interact with the user interface.
\begin{figure}[htpb] \centering
- \includegraphics[width=1.0\linewidth]{batch01.png}
- \caption{Example of the Batch Render menu}
- \label{fig:batch01}
+ \includegraphics[width=1.0\linewidth]{batch01.png}
+ \caption{Example of the Batch Render menu}
+ \label{fig:batch01}
\end{figure}
+If you want to render many projects \index{project} to media files without having to
+constantly set up the render dialog for each one, batch rendering is
+a more efficient method of rendering. To use this feature you need to
+understand certain concepts.
+
+\begin{enumerate}
+ \item You must define a list of Batches (\textit{Job} \index{job}) before starting the rendering. This is created using the \textit{New} button and displayed in \textit{Batches to Render} dialog.
+ \item Each batch consists of a source project already created in \CGG{}, e.g. \texttt{aaa.xml}, to which we assign the rendering parameters.
+ \begin{itemize}
+ \item to associate \texttt{aaa.xml} to the batch we use the \textit{EDL Path} input field.
+ \item we decide a name and path for the output file.
+ \item let's set the \textit{File Format} of the output file.
+ \item We configure the file with the Audio/Video \textit{wrench}.
+ \item we decide whether to create different files for each \textit{label} and whether to use a \textit{Render farm}.
+ \end{itemize}
+ \item Created the first batch, we will see it appear in the dialog \textit{Batches to Render}.
+ \item Using the \textit{New} button again we create a second batch for another source project (\texttt{bbb.xml}) and configure it at will.
+ \item We continue with the source projects \texttt{ccc.xml}, \texttt{ddd.xml}, etc. until we run out of projects that we want to render in batch.
+ \item Note that each batch has its own name, path and rendering parameters.
+ \item Now we have our \textit{Job}, a list of batches. We can still configure it or modify it if we want to change something. In addition we can delete a batch from the list or we can disable it in the \textit{Enabled} field so that it is not taken into account during rendering, but without deleting it.
+ \item Finally we start batch rendering with the \textit{Start} button.
+\end{enumerate}
+
+Let's see in detail how to set the Batch Rendering.
+
The first thing to do when preparing to do batch rendering is to
create one or more \CGG{} projects to be rendered and save them as a
-normal project, such as \texttt{ProjectA.xml}. The batch renderer
+normal project, such as \texttt{aaa.xml}. The batch renderer
requires a separate project file for every batch to be rendered.
You can use the same \CGG{} project file if you are rendering to
different output files, as in an example where you might be creating
the same output video in different file formats.
-To create a project file which can be used in batch render, set up
-your project and define the region to be rendered either by
-highlighting it, setting in/out points around it, or positioning the
-insertion point before it. Then save the project as usual to your
-\texttt{project.xm}l file. Define as many projects as needed this
-way. The batch renderer takes the active region from the EDL file
-for rendering. If we have not set active regions, it is better to
-bring the insertion point to the beginning of the timeline to avoid
-possible problems with the rendering.
+You do not have to render an entire projects. We can limit ourselves to an \textit{active region} \index{active region} that we can set through a selection in Cut and Paste mode, with labels or In/Out Points. Or the rendering will start from the Insert Point position until the end of the project. Remember: if we want to render the entire project (and not just one active region) it is important to bring the Insertion Point to the beginning of the timeline. This is the only way we are sure to include the whole project.
With all the \CGG{} xml project files prepared with active regions,
go to \texttt{File $\rightarrow$ Batch Render}. This brings up the
parameters for a single batch; a batch is simply a pairing of a
project file with a choice of output file and render settings.
-Set the \textit{Output path}, \textit{File format}, \textit{Audio},
+It may be advisable to start with a \textit{Delete} so you don't have any problems. Set the \textit{Output path}, \textit{File format}, \textit{Audio},
\textit{Video}, and \textit{Create new file at each label}
parameters as if you were rendering a single file. These parameters
apply to only one batch. In addition to the standard rendering
parameters, you must select the \textit{EDL Path} to be the project
-file (such as \texttt{ProjectA.xml}) that will be used in the batch
+file (such as \texttt{aaa.xml}) that will be used in the batch
job. In this case, \textit{EDL Path} is not related in anyway with
the EDL files as created by \texttt{File/Export EDL}. In batch
render mode the program will not overwrite an existing output file
as the output files exist before starting.
If the batches to render list is empty or nothing is highlighted,
-click \texttt{New} to create a new batch. The new batch will contain
-all the parameters you just set. Repeatedly press the \texttt{New}
+click \textit{New} to create a new batch. The new batch will contain
+all the parameters you just set. Repeatedly press the \textit{New}
button to create more batches with the same parameters. When you
highlight any batch, you can edit the configuration on the top of
the batch render window. The highlighted batch is always
synchronized to the information displayed. You can easily change
the order in which the batch jobs are rendered, by clicking and
-dragging a batch to a different position. Hit \texttt{Delete} to
+dragging a batch to a different position. Hit \textit{Delete} to
permanently remove a highlighted batch. In the list box is a column
which enables or disables the batch with an \texttt{X} meaning the
batch job is enabled and will be run. This way batches can be
-skipped without being deleted. Click on the \texttt{Enabled} column
+skipped without being deleted. Click on the \textit{Enabled} column
in the list box to enable or disable a batch.
The description of each of the columns in the batch list are as
\item[Enabled:] an X in this column means the batch job will be run.
\item[Labeled:] an \texttt{X} in this column goes hand in hand with
create new file at each label.
+\item[Farmed:] to use or not the render farm.
\item[Output:] path and filename for the generated output.
\item[EDL:] the path and filename of the source EDL for the batch
job.
\item[Elapsed:] the amount of time taken to render the batch if
finished. If field is empty, it did not run.
-\end{description} To start rendering from the first enabled batch,
-hit \texttt{Start}. Once rendering, the main window shows the
+\end{description}
+
+The \texttt{File $\rightarrow$ Batch Render} pulldown brings up the
+Batch Render window to be used for batch rendering as well as DVD/BD
+creation. There are some additional buttons that can save time and
+mistakes. These are described next.
+
+\begin{description}
+ \item[Save Jobs] when you have set up the batch jobs the way you
+ want and you think you may have to run them more than once, it is
+ beneficial to save the jobs for later use so you easily run them
+ again. It is recommended to use a filename with .rc as the extension
+ so that it is obvious that it is a list of batch jobs to be run.
+ \item[Load Jobs] reload a previous set of saved jobs. This can come
+ in handy if you did not have the time to render them when you
+ originally set them up, if you need to rerun, or if you got
+ interrupted.
+\end{description}
+
+To start rendering from the first enabled batch,
+hit \textit{Start}. Once rendering, the main window shows the
progress of the batch. After each batch finishes, the elapsed column
in the batch list is updated and the next batch is rendered until
all the enabled batches are finished. The currently rendering batch
is always highlighted red. To stop rendering before the batches are
-finished without closing the batch render dialog, hit \texttt{Stop}.
+finished without closing the batch render dialog, hit \textit{Stop}.
To stop rendering before the batches are finished and close the
-batch render dialog, hit \texttt{Close}. Or you can exit the batch
+batch render dialog, hit \textit{Close}. Or you can exit the batch
render dialog whether or not anything is being rendered, by hitting
-\texttt{Close}.
+\textit{Close}.
You can automate \CGG{} batch renders from other programs. In the
batch render dialog, once you have created your list of batch render
-jobs, you can click the button \texttt{Save Jobs} and choose a file
-to save your batch render list to. Once you have created this file,
+jobs, you can click the button \textit{Save Jobs} and choose a file
+to save your batch render list to. It is recommended that you use
+a filename with the extension of .rc in order to make it obvious that
+this is a list of batch jobs to render. Once you have created this file,
you can start up a batch render without needing to interact with the
\CGG{} user interface. From a shell prompt, from a script, or other
program, execute:
\begin{lstlisting}[style=sh]
-{path_to_cinelerra}/cin -r batchjob.xml
+{path_to_cinelerra}/cin -r batchjob.rc
\end{lstlisting} substituting your actual filename for
-\texttt{batchjob.xml}. When invoked with these parameters, \CGG{}
-will start up and perform the rendering jobs in that list, without
-creating its usual windows.
-
-\subsection{Command Line Rendering}%
-\label{sub:command_line_rendering}
-
-The command line rendering method consists of a way to load the
-current set of batch rendering jobs and process them without a
-GUI\@. This is useful if you want to do rendering on the other side
-of a low bandwidth network and you have access to a high powered
-computer located elsewhere. Setting up all the parameters for this
-operation is somewhat difficult. That is why the command line aborts
-if any output files already exist.
-
-To perform rendering from the command line, first run \CGG{} in
-graphical mode. Go to \texttt{File $\rightarrow$ Batch
- Render}. Create the batches you intend to render in the batch window
-and close the window. This saves the batches in a file. Set up the
-desired render farm attributes in \texttt{Settings $\rightarrow$
- Preferences} and quit out of \CGG{} if you want to use the Render
-Farm capability. These settings are used the next time command line
-rendering is used to process the current set of batch jobs without a
-GUI\@.
+\texttt{batchjob.rc}. \textbf{Warning} this file will be modified
+so if you use any filename that is not a legitimate list of batch jobs to
+render, that file will be overwritten and its previous contents destroyed.
+When invoked with these parameters, \CGG{} will start up and run the
+rendering jobs in the list contained in that file starting at the defined
+\textit{active region}, without creating its usual windows. If you do not
+specify a filename, the default will be \$HOME/.bcast5/batchrender.rc.
+Possible messages you might see where you started up the job are as follows.
+\begin{description}
+\item[The following files exist: - filename - Won't overwrite existing files] that batch job will not run in order to prevent writing over previous run.
+\item["filename" No such file or directory] the specified batch job file does not exist.
+\item["filename": Permission denied] the specified batch job file does not have write permission so can not be updated.
+\item[Render::run: filename] the batch job with the name of filename will be processed.
+\item[** rendered 0 frames in 0.000 secs, 0.000 fps] either you used a file that is not a list of batch jobs or the batch jobs within the file were not enabled.
+\end{description}
-On the command line run:
+\subsection{Advanced features}%
+\label{sub:advanced_features}
+\index{batch rendering!more options}
-\begin{lstlisting}[style=sh]
-cin -r
-\end{lstlisting}
+\textbf{Warning}: \textit{Save to EDL path} overwrites the current EDL thus destroying the original contents.
-\subsection{More about Save/Use EDL and Save/Load Jobs}%
-\label{sub:more_save_use_edl_jobs}
-
-The \texttt{File $\rightarrow$ Batch Render} pulldown brings up the
-Batch Render window to be used for batch rendering as well as DVD/BD
-creation. There are some additional buttons that can save time and
-mistakes. These are described next.
+Although the operation of Batch Rendering in \CGG{} is similar to that of other NLEs, there is one big difference that we need to take into account. The render setup is not done on a project-by-project basis, which are then brought into the Batch window to be rendered automatically. The setup must be done in the Batch rendering window, where various projects are loaded and set up. In the case of similar projects, derived from a single EDL with some variation, this mode offers the possibility of altering the projects without having to open each individual project, make the changes, set up the rendering, save and import into the Batch window. The procedure is to select the batch we want to modify in the Batches to render window; operate on the currently open timeline (even if it does not correspond to the one we want to modify) making the desired changes and then press the \textit{Save to EDL path} button. Thus the chosen batch, while retaining its original name, will now contain the modified project. Since this possibility destroys the original EDL overwriting it with the modified one, you must be very careful. This procedure is convenient in case the batches are similar, i.e. they are variations of the same EDL, where we want to experiment with other effects, other output formats or when trying out various cuts of a DVD/BD before the final production. It might also be useful to use an \textit{active region} of the timeline, so as to speed up rendering times but still have an indicative result for comparison. Instead operating on different projects, we can do a \textit{save as...} of the project on the timeline to have a new EDL with a new name and then replace it with the batch selected in the joblist using the \textit{Use Current EDL} button. The new project (with its name) overwrites the original project.
The \textit{Save to EDL Path} and \textit{Use Current EDL} buttons
can be valuable tools for advanced usage or for developers doing
testing. Description of how you can expect them to work will help
-to illustrate how to take advantage of their capabilities.
+to illustrate how to take advantage of their capabilities (figure~\ref{fig:batch-advanced}):
+
+\begin{figure}[htpb] \centering
+ \includegraphics[width=0.7\linewidth]{batch-advanced.png}
+ \caption{New Buttons with Unsafe GUI in batchrender}
+ \label{fig:batch-advanced}
+\end{figure}
+
\begin{description}
-\item[Save to EDL Path] if you have made a change to the EDL, use
+\item[Save to EDL Path] Warning: this function overwrites the contents of the original EDL with new data, keeping the name of the original. If we don't know exactly what we're doing we may lose the original project. If you have made a change to the EDL, use
this button to save the changes so that they will be used in the
render operation. Although you can get the same results by using
\texttt{File $\rightarrow$ Save\dots}, this capability was initially
However, it is important to note that the result will be saved with
the name \texttt{original\_name} – that is, the new content from
\texttt{new.xml} but with the old name of
- \texttt{original\_name.xml}.
-\item[Use Current EDL] if you are working on media and still testing
+ \texttt{original\_name.xml}. To have this functionality we have to enable the checkbox in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab; section \textit{Dangerous:} and unchecked (default) \textit{Unsafe GUI in batchrender}.
+\item[Use Current EDL] Warning: this function overwrites the contents of the original EDL with new project. If we don't know exactly what we're doing we may lose the original project. if you are working on media and still testing
out the results, you can take advantage of this click-box to quickly
get results. Basically, you change the media, save that change with
another name (in order to preserve the original name in case you
listbox will be automatically updated to the \texttt{new\_name.xml}
and the current existing highlighted job will be replaced with the
\texttt{new\_name.xml} in the EDL column.
-\item[Save Jobs] when you have set up the batch jobs the way you
- want and you think you may have to run them more than once, it is
- beneficial to save the jobs for later use so you easily run them
- again.
-\item[Load Jobs] reload a previous set of saved jobs. This can come
- in handy if you did not have the time to render them when you
- originally set them up, if you need to rerun, or if you got
- interrupted.
-\item[Warn if Jobs/Session mismatched] After you set up your render
+\item[Warn if Jobs/Session mismatched] Warning: It is better to keep this function unchecked because it is only needed in case of changes on the original EDL. By default it is hidden and is shown only if we enable the checkbox in \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab; section \textit{Dangerous:} and checked \textit{Unsafe GUI in batchrender}. After you set up your render
and press Start, the program checks to see if the current EDL
session matches your Batch Render job. If the EDL has been changed
since the batch job was created, it warns you so that you have the
Otherwise, you can dismiss that warning box, disable the warning
message by unchecking the box and use the original values. If you
never want to be warned about the mismatches, leave the box
- unchecked (figure~\ref{fig:batch02}).
+ unchecked (figure~\ref{fig:batch02}). It is advisable to keep it unchecked because it can cause problems.
\end{description}
\begin{figure}[htpb] \centering
- \includegraphics[width=1.0\linewidth]{batch02.png}
- \caption{Batch render with the 4 ghosted buttons on the right side
- + the Warning message below}
- \label{fig:batch02}
+ \includegraphics[width=0.9\linewidth]{batch02.png}
+ \caption{Batch render with the 4 ghosted buttons on the right side
+ + the Warning message below}
+ \label{fig:batch02}
\end{figure}
+A very clear tutorial on these features can be found \href{https://linuxvideoediting.blogspot.com/2021/01/save-edl-path-use-current-edl-in-cinelerra-gg.html}{here}\protect\footnote{credit Igor Vladimirsky}; in Russian but easily translatable with DeepL or similar.
+
+\subsection{Command Line Rendering}%
+\label{sub:command_line_rendering}
+\index{rendering!command line}
+
+The command line rendering method consists of a way to load the
+current set of batch rendering jobs and process them without a
+GUI\@. This is useful if you want to do rendering on the other side
+of a low bandwidth network and you have access to a high powered
+computer located elsewhere. Setting up all the parameters for this
+operation is somewhat difficult. That is why the command line aborts
+if any output files already exist.
+
+To perform rendering from the command line, first run \CGG{} in
+graphical mode. Go to \texttt{File $\rightarrow$ Batch Render}.
+Create the batches you intend to render in the batch window and
+close the window. This automatically saves the batches in a file
+with the name of \$HOME/.bcast5/batchrender.rc. Set up the
+desired render farm attributes in \texttt{Settings $\rightarrow$
+ Preferences} and quit out of \CGG{} if you want to use the Render
+Farm capability. These settings are used the next time command line
+rendering is used to process the current set of batch jobs without a
+GUI\@. It is important to remember that the rendering will begin at
+the defined \textit{active region} saved when the project was saved.
+
+On the command line run:
+
+\begin{lstlisting}[style=sh]
+cin -r
+\end{lstlisting}
+
\section{Background Rendering}%
\label{sec:background_rendering}
+\index{background rendering}
Background rendering causes temporary output to be rendered
constantly while the timeline is being modified. The temporary
output is displayed during playback whenever possible. This is
useful for transitions and previewing effects that are too slow to
-display in real time. If a Render Farm is enabled, the render farm
+display in real time. If a Render Farm \index{render farm} is enabled, the render farm
is used for background rendering. This gives you the potential for
real-time effects if enough network bandwidth and CPU nodes exist.
Background rendering is enabled in the \texttt{Performance} tab of
the \texttt{Preferences} window. It has one interactive function
-\texttt{Settings $\rightarrow$ Toggle background rendering}. This
+\texttt{Settings $\rightarrow$ Toggle background rendering} \index{background rendering!toggle}. This
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}
path. Since hundreds of thousands of image files are usually
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.
+ either, but the configuration button for this option works. The
+ 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
- well.
+ well and is the default.
\end{description}
+Tip: If you have rendered your whole project with \textit{File format}
+set to JPEG and there are no missing numbers in the sequence, you can
+create a video from that sequence outside of \CGG{}.
+For example, if using the default output so that your files are named
+/tmp/brender000000, /tmp/brender000001, ... in a window, you would type:
+
+\begin{lstlisting}[style=sh]
+ffmpeg -f image2 -i /tmp/brender0%5d -c:v copy brender.mov
+\end{lstlisting}
+which would create the video file brender.mov - be sure to delete
+existing brender files before creating a new sequence to ensure there
+are no missing numerical values in the sequence.
\section{Render Farm Usage}%
\label{sec:render_farm_usage}
+\index{render farm}
Render Farm uses background rendering, a feature of \CGG{} where the
video is rendered in the background, to speed up rendering
significantly. Because rendering is memory and cpu intensive, using
multiple computers on a network via a render farm is a significant
-gain. With \CGG{} installed on all nodes, the master node and the
-clients communicate via a network port that you specify.
-
+gain. With \CGG{} installed on all nodes, the master node and the clients communicate via a network port that you specify.
+The Master node is the one of the instance of \CGG{} that we normally start with its gui; the other nodes are the instances of \CGG{} that we decide to start in parallel from the terminal to create the Render farm (clients).
\CGG{} can distribute the rendering tasks over the network to the
-other computers of the Render Farm. The render farm software tries
+other computers of the Render Farm; or among all threads of a multicore CPU. The render farm software tries
to process all of the rendering in parallel so that several
computers can be used to render the results. The \textit{Total jobs
- to create} in the setup or labels on the timeline are used to divide
+to create} in the setup or labels on the timeline are used to divide
a render job into that specified number of tasks. Each background
job is assigned a timeline segment to process and the jobs are sent
to the various computer nodes depending upon the load balance. The
The following steps are just a guideline to start your render farm.
It is assumed that you already have the master and client nodes
communication, shared filesystem, permissions and usernames synched.
+Let's take the example of a network with 2 PCs: the master and the client. On the client we set 5 tasks; on the master we set 2 tasks.
\begin{enumerate}
\item On the master computer, use \texttt{Settings} $\rightarrow$
\item in the \textit{Hostname} box, keyin your hostname or ip
address such as 192.168.1.12 or \textit{localhost};
\item enter in a port number such as 401--405 (only a root user
- can use privileged ports) or $1025$ and click on \textit{Add Nodes};
+ 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 & 401 & 0.0 \\
- X & 192.168.1.12 & 402 & 0.0 \\
- X & 192.168.1.12 & 403 & 0.0 \\
- X & 192.168.1.12 & 404 & 0.0 \\
- X & 192.168.1.12 & 405 & 0.0 \\
- X & localhost & 406 & 0.0 \\
- X & localhost & 407 & 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;
+ \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{itemize}
-\item Now we must join the nodes created to instances of \CGG{}. On the client computers ($192.168.1.12$), on the terminal, start 5 background \CGG{} tasks via:
+\item For external network nodes, now we must join the nodes created to instances of \CGG{}. On the client computers ($192.168.1.12$), on the terminal, start 5 background \CGG{} tasks via:
\begin{lstlisting}[style=sh]
cd {path_to_cinelerra}
-cin -d 401 cin -d 402
+cin -d 10650 cin -d 10651
...
-cin -d 405
+cin -d 10654
\end{lstlisting}
-\item Similarly, on the terminal, we must join the local nodes created to instances of \CGG{}. On the master node (localhost), start the 2 background \CGG{} tasks via:
+In practice, at each instance that we start, the cursor will be positioned in a new line ready to enter the next command, without exiting the task. If we have several PCs on the network, repeat these steps for each new client (with its own ip address).
+\item Similarly, on the terminal, we must join the local nodes (internal to the Master node) created to instances of \CGG{}. On the Master node (localhost), start the 2 background \CGG{} tasks via:
\begin{lstlisting}[style=sh]
cd {path_to_cinelerra}
-cin -d 406
-cin -d 407
+cin -d 10655
+cin -d 10656
\end{lstlisting}
+Similar to the previous point, the cursor positions itself in a new line ready to enter the next command, without exiting the task.
\item When your video is ready, setup a render job via \texttt{File
$\rightarrow$ Render} or \texttt{File $\rightarrow$ Batch Render}
and check OK.
Scripts icon.
\item If you plan on doing more rendering, you can just leave the
master/client jobs running to use again and avoid having to restart
- them. Or you can kill them when you no longer are using them.
+ them. You can also close the terminal, but the jobs will remain active until you turn off the PC. Or you can kill them when you no longer are using them.
\end{enumerate}
\subsection{Render Farm Menu and Parameter Description}%
\label{sub:render_farm_parameter_description}
+\index{render farm!parameters}
Below we describe the Performance tab for configuring a render farm
(figure~\ref{fig:farm}).
existing node or enter a new node.
\item[Port] keyin the port number of an existing or new node here.
You can also type in a range of port numbers using a hyphen, for
- example $1501-1505$ when you need to add many.
+ example $10650-10799$ when you need to add many.
\item[Apply Changes] this will allow you to edit an existing node
and to then commit the changes to hostname and port. The changes
will not be committed if you do not click the OK button.
\subsection{Detailed Setup Description}%
\label{sub:detailed_setup_description}
+\index{render farm!setup}
{\color{red} CAUTION }, any exact command lines worked as of
$01/2018$ on a Fedora system. These can change over time and on
\end{lstlisting} As it completes its jobs, you will should see:
\begin{lstlisting}[style=sh]
RenderFarmClientThread::run: Session finished
-\end{lstlisting} A quick way to start a sequence of clients is to
- use:
-\begin{lstlisting}[style=sh,mathescape]
-for n in `seq 1501 1505`; do
- cin -d $\$$n
-done
\end{lstlisting}
\item[Render Using Render Farm] After you have followed the
preceding steps, you are ready to use the render farm. Click on
\item[Assemble the Output Files] Once all of the computer jobs are
complete, you can put the output files together by using the shell
script, \textit{RenderMux} (from the menubar \textit{scripts} button
- just above FF), if the files were rendered using ffmpeg, or you can
- load these by creating a new track and specifying concatenate to
+ just above FF), if the files were rendered using ffmpeg (see \nameref{sec:menu_bar_shell_commands}).
+
+ If you want to remain within the open project in \CGG{}, you can load these files by creating a new track and specifying concatenate to
existing tracks in the load dialog in the correct numerical order.
File types which support direct copy can be concatenated into a
single file by rendering to the same file format with render farm
disabled as long as the track dimensions, output dimensions, and
asset dimensions are equal.
+
+ Finally if you want to use ffmpeg from terminal externally to \CGG{} you can go to the directory where the rendered files are, it creates a text file \texttt{list.txt} containing the list of all our files:
+ \begin{lstlisting}[style=sh]
+ file 'name.webm001'
+ file 'name.webm002'
+ ...
+ file 'name.webm00n'
+ \end{lstlisting}
+ and finally give the command
+ \begin{lstlisting}[style=sh]
+ ffmpeg -f concat -i list.txt -c copy output.webm
+ \end{lstlisting}
\end{description}
\subsection{Quick and Easy Render Farm Setup – The Buddy System
add the plugins, such as a Title, etc.
\item Check for a set of unused ports in \texttt{/etc/services}
file, if username is root usually $401-425$ are available; if
- non-root, then $1024-1079$.
+ non-root, then $10650-10799$.
\item On the master computer, in \texttt{Settings $\rightarrow$
Preferences, Performance} tab:
\begin{itemize}
/{cinelerra_pathname}/cin -d port#
\end{lstlisting}
\item On the master, bring up the render menu and name the output
- files, for example \texttt{/tmp/myoutput.mp4}.
+ files, for example \texttt{/tmp/myoutput.webm}.
\item The client nodes output results will be on their local
\texttt{/tmp} filesystems so you will have to again use
\textit{rsh/ftp} or \textit{usb sneaker net} to move them over to
the main computer. File names will be the render job output file
name with port number tacked on
- (e.g. \texttt{/tmp/hb.mp4001...mp4005}).
+ (e.g. \texttt{/tmp/hb.webm001...webm005}).
\item Load the files by concatenate to existing track on the master
node or use RenderMux shell script.
\end{enumerate}
\subsection{Multi-core Computers Render Farm Setup}%
\label{sub:multi_core_render_farm_setup}
+\index{render farm!multi core CPU}
If you are lucky enough to have a computer with a large cpu core
count, setting up a render farm can really take advantage of using
-all of the cpus. This is much faster than the default automatic
+all of the cores at 100\%. This is much faster than the default automatic
threading capability. Since you don’t need to communicate with other
computers, you will not have to be concerned about TCP communication
-or shared disks/files; only localhost nodes. On the terminal, we will open many instances of \CGG{} by connecting them to the jobs created. The number of such jobs can be the total number of CPU threads or not. When you are going to be doing other work
+or shared disks/files; only localhost nodes. On the terminal we will open many instances of \CGG{} by connecting them to the jobs created. The number of such jobs can be the total number of CPU threads (-1) or not. When you are going to be doing other work
simultaneously while rendering a large job, you will want to leave
some of the cpus available for that. Be sure to set \textit{Project SMP
cpus} in the \texttt{Settings $\rightarrow$ Preferences, Performance} tab to your CPU
\subsection{Troubleshooting Tips and Warnings}%
\label{sub:troubleshhoting_tips_warnings}
+\index{render farm!troubleshooting}
\noindent If you have problems running the Render Farm. Here is a
list of items to check.
section of the video so keep that in mind when designating port
numbers.
\item If not running as root, a port number in the higher range of
- $1024$ and above must be used instead of the $400+$ range.
+ $10650$ and above must be used instead of the $401+$ range.
\item The master and client jobs on the ports do not go away so if
you want to stop them, you will have to kill them via: \texttt{kill
PID\#}.
time. You can adjust the timer in \texttt{Settings $\rightarrow$
Preferences, Performance} tab.
\item When you get the message \texttt{RenderFarmClient::main\_loop:
- bind port 400: Address already in use}, use a different port.
+ bind port 400: Address already in use}, use a different port. See \texttt{/etc/services} for free ports.
\item A message of \texttt{RenderFarmServerThread::open\_client:
unknown host abcompany} means that the hostname of abcompany is not
in \texttt{/etc/hosts} so you will have to add it or use the ip
computers. The ports have to be reachable for the intranet but you
do not want the ports to be open to the outside.
-\section{Some Specific Rendering}%
-\label{sec:some_specific_rendering}
-
-\noindent The next few pages relate to rendering for specific common
-cases.
-
-\subsection{FFmpeg Common H.264 Rendering}%
-\label{sub:ffmpeg_h264_rendering}
-
-Because H.264 is so widely used, the method in \CGG{} Infinity is
-outlined below. These setup steps make it easy to just get started.
-
-\begin{itemize}
-\item File $\rightarrow$ Render
-\item File Format $\rightarrow$ FFMPEG + mp4
-\item Video Wrench $\rightarrow$ Preset $\rightarrow$ h264.mp4 +
- bitrate: 6000000 (or whatever) + OK
-\item Audio Wrench $\rightarrow$ Preset $\rightarrow$ h265.mp4 +
- bitrate: 224000 (or whatever) + OK
-\item Set your target path in: Render $\rightarrow$ Select a file to
- render to
-\item Set your timeline in: Render $\rightarrow$ Render range +
- click Project
-\item Set your insertion strategy: Replace project (or whatever)
-\item Press OK to start rendering.
-\end{itemize}
-
-\subsection{Lossless Rendering}%
-\label{sub:loseeless_rendering}
-
-Lossless means that in the compression of a file, all of the
-original data, every single bit, can be recovered when the file is
-uncompressed. This is different than \textit{lossy compression}
-where some data is permanently deleted so that when uncompressed,
-all of the original data can not be exactly recovered. Lossy is
-generally used for video and sound, where a certain amount of
-information loss will not be detected by most users or the playback
-hardware does not reproduce it anyway -- it is a trade-off between
-file size and image/sound quality. The files created will be more
-than 10 times larger than usual. Most players will not be able to
-decode lossless as the bitrate will overwhelm the device.
-
-For x264 lossless compression to work, the only color model allowed
-here is yuv420p. Any other specification will be converted to
-yuv420p and the data will be modified. Also, keep in mind that the
-YUV color model has to be converted to RGB, which also modifies the
-data.
-
-To use x264 lossless rendering -- choose File format of ffmpeg, m2ts
-in the Render window. Click on the Video wrench, which brings up
-the Video Preset window and scroll down in the Compression filebox
-and choose \texttt{lossless.m2ts}. \textit{Preset=medium} is the
-default, but can be varied from \textit{ultrafast} (least amount of
-compression, but biggest file size) to \textit{veryslow} (most
-amount of compression, but still HUGE) in the parameter box where
-you see $qp=0$. This option is also available for bluray creation.
-
-\subsection{Extra “cin\_” Options for Render with FFmpeg}%
-\label{sub:extra_cin_option_ffmpeg}
-
-There are several special parameters that can be used in the ffmpeg
-options file to pass values to the codecs that are not normally
-available. They're called Global Options. These are explained
-below.
-
-\paragraph{cin\_pix\_fmt} The Render menus allows you to choose the
-codec input pixel format (figure~\ref{fig:yuv420}). The Pixels
-selection provides the available pixel format options for the chosen
-codec type; valid choices vary for the different file types. This
-list represents the formats that the codec advertises. It is not
-always complete, and it may include options that are not legal with
-all parameter configurations.
-
-\begin{figure}[htpb] \centering
- \includegraphics[width=1.0\linewidth]{yuv420.png}
- \caption{Render \& Video Preset menus displaying Pixel choices}
- \label{fig:yuv420}
-\end{figure}
-
-\begin{itemize}
-\item The \textit{Bitrate}, \textit{Quality}, and \textit{Pixels}
- fields are only updated when the Video Options are reloaded. This
- occurs when you either change the ffmpeg file format, or video
- presets compression fields.
-\item If the video options preset has \textit{cin\_pix\_fmt}
- defined, its value will be loaded as the default. If you override
- the default, the value you specify will be used.
-\item If the video options preset does not have
- \textit{cin\_pix\_fmt}, the default pixel format will be computed by
- ffmpeg (\textit{avcodec\_find\_best\_pix\_fmt\_of\_list}), using the
- session format as the source choice. The \textit{best} is usually
- the format which is most similar in color and depth.
-\item If no choices are available, yuv420p for video will be used.
-\item You can also specify ffmpeg pixel formats which are not in the
- list. The list is provided by ffmpeg as input selection, but is
- more like suggestions than fact. For example, the raw formats can
- take almost any format, but the rawvideo codec actually specifies no
- legal formats.
-\end{itemize}
-
-\noindent Some option files provide \textit{cin\_pix\_fmt} to
-suggest a choice for good quality output or to prevent parameter
-errors when the other provided parameters conflict with the
-\textit{best} pixel format. This is the case in
-\texttt{faststart\_h264.mp4} where the \textit{profile=high}
-parameter dictates pixel format must be \texttt{yuv420p}.
-
-\paragraph{cin\_bitrate} If you specify the bitrate, you can not
-specify the quality.\\ Example: \textit{cin\_bitrate=2000000}
-
-\paragraph{cin\_quality} If you specify the quality, you can not
-specify the bitrate.\\ Example: \textit{cin\_quality=7}
-
-\paragraph{cin\_stats\_filename} This parameter is useful for 2 pass
-operations.\\ Example: \texttt{cin\_stats\_filename
- /tmp/cin\_video\_vp9\_webm}
-
-\paragraph{cin\_sample\_fmt} For audio the preset sample format
-default is computed in a similar way as stated above for video or
-can be set with the \textit{cin\_sample\_fmt} parameter
-(figure~\ref{fig:audio}). If no choices are provided, s16 will be
-used.\\ Example: \textit{cin\_sample\_fmt=s16}
-
-\begin{figure}[htpb] \centering
- \includegraphics[width=0.7\linewidth]{audio.png}
- \caption{Render menu showing where Samples is}
- \label{fig:audio}
-\end{figure}
-
-\paragraph{Private Options} (muxers). In the window of the
-\textit{wrench} in addition to the \textit{View} button, which
-allows more global options and changes to the formats, there is an
-additional \textit{Format} button that allows you to modify the
-Private Options, i.e.\ relating to specific muxing formats. More
-information on all these options can be found at
-\href{https://ffmpeg.org/ffmpeg-all.html#Format-Options}{ffmpeg.org}
-sections 19 and 21.
-
-\subsection{Two-pass Encoding with FFmpeg}%
-\label{sub:two_pass_encoding_ffmpeg}
-
-In \CGG{} for two-pass, you need to run ffmpeg twice, with the same
-settings, except for designating the options of pass~1 for the first
-pass and then pass~2. In pass~1, a logfile that ffmpeg needs for
-the second pass is created. In pass~1 the audio codec should be
-specified that will be used in pass~2. For more information on
-ffmpeg 2-pass, check
-\href{https://trac.ffmpeg.org/wiki/Encode/H.264}{ffmpeg.org}.
-Different libraries may have different requirements and you will
-probably have to determine this by looking online at ffmpeg or
-looking directly at that code.
-
-This 2 line ffmpeg 2-pass operation can be functionally duplicated
-in \CGG{} in the steps below them:
-
-\begin{lstlisting}[style=sh]
-ffmpeg -y -i $INPUT \
- -c:v libx264 -b:v 2600k -pass 1 \
- -c:a aac -b:a 128k -f mp4 /dev/null && \
- ffmpeg -i $INPUT \
- -c:v libx264 -b:v 2600k -pass 2 \
- -c:a aac -b:a 128k $OUTPUT.mp4
-\end{lstlisting}
-
-\begin{enumerate}
-\item After you have completed your editing, do a Save Session with
- \texttt{File $\rightarrow$ Save as}\dots Before starting, be sure
- your session is ready for batch render. That is, positioned at the
- beginning and nothing selected.
-\item Bring up \texttt{File $\rightarrow$ Batch Render}\dots where
- you will do the setup.
-\item Click on the \textit{Delete} box to remove old jobs
- highlighted in the bottom listbox.
- \begin{itemize}
- \item For the \textit{File Format} choose ffmpeg and mp4 for the
- type.
- \item Set \textit{Output path} to the path and filename for the
- render output file.
- \item Click on \textit{Use Current EDL} to use the designated EDL
- Path file.
- \item Click on \textit{New} and you will see a new highlighted job
- show up in the listbox at the bottom.
- \item Use the Audio wrench to set bitrate to $128000$ ($128k$ as
- in ffmpeg example above).
- \item Click checkmark OK\@. Open the video tools with the video
- wrench.
- \item Set the Video Compression to \textit{h264.mp4} (as seen in
- the example).
- \item Set the bitrate to $2600000$ ($2600k$ as in ffmpeg example
- above).
- \item Add the following 2 lines after the first line:
-\begin{lstlisting}[style=sh]
-flags +pass1
-passlogfile /tmp/"{temporary log file name}.log"
-\end{lstlisting} Click checkmark OK.
- \end{itemize}
-\item Click on \textit{New} to create the second pass job. You will
- see this second job in the listbox below. Use the Video wrench and
- change pass1 to pass2 as follows.
-\begin{lstlisting}[style=sh]
-flags +pass2
-\end{lstlisting}
-\item Click checkmark OK.
-\item Click on the \textit{Start} box and watch it go!
-\item You can now check the output file for results. At the time
- this was documented, \textit{rc=2pass} will be in the output.
-\end{enumerate}
-
-If you need to re-render this, the Batch Render will still be set up
-but you have to click on the \textit{Enabled} column in the listbox
-to re-enable the jobs to run which puts an X there. Click Start
-again. You can reuse batch job using the \textit{save jobs} and
-\textit{load jobs} buttons in the batch render dialog.
-
-\paragraph{Render shortcuts for webm, h264, h265} are available by
-using the option files that are already set up for this purpose.
-Use the render menu as usual, with ffmpeg/mp4, choose h264 or h265
-\textit{pass1of2\_h26x} for the video and
-\textit{passes1and\-2\_h26x} for the audio; with ffmpeg/webm, choose
-\textit{pass1of2\_vp9}. When that is finished, you will have to use
-the render menu again and this time for video, choose
-\textit{pass2of2\_h26x} or \textit{pass2of2\_vp9}. The logfile is
-hard coded in the options file so will write over any currently
-existing logfile if you do not change it before you start the
-render.
-
-\paragraph{Requirements for some other libraries} (used instead
-of \textit{flags +pass1} \& \textit{passlogfile}):
-\begin{description}
-\item[x265:] add this line:
-\begin{lstlisting}[style=sh]
-x265-params=pass=1:stats=/tmp/{temporary-log-file-name}.log
-\end{lstlisting} at the time this document was written, you should
- see in the output: \textit{stats-read=2}
-\item[libvpx-vp9, xvid, and huffyuv:]~
-\begin{lstlisting}[style=sh]
-cin_stats_filename /tmp/{temporary-log-file-name}.log
-flags +pass1 (or flags +pass2 for the second pass)
-\end{lstlisting}
-\end{description}
-
-\textit{NOTE:} for vp9, the best Pixels is \textit{gbrp}
-
-\subsection{Use case: High Efficiency Video Coding (HEVC)}%
-\label{sub:use_case_hevc}
-
-An example of video profile based on CRF, a quality-controlled
-variable bitrate, instead of fixed quality scale (ABR). HEVC
-(H.265) was developed as a successor to AVC (H.264) to more
-efficiently compress the future large amounts of data from 2/4/8k
-videos. In comparison to AVC, an average saving of around 30
-percent can be assumed for the same quality. Because HEVC is not
-bound to any size format, it is suitable for virtually any image
-size.
-
-The following example is HD and FullHD oriented and produces a
-picture quality similar to the Blu-ray with some limitations. As
-container Matroska (\texttt{.mkv}) is used, but also mp4 and others
-are possible.
-
-\begin{lstlisting}[style=sh]
-matroska libx265
-
-# CRF 16 creates a balanced compromise
-# between quality and file size.
-crf=16
-
-# Preset changes encoding speed and generally
-# degrades the overall result. Medium (default)
-# always fits.
-preset=medium
-
-# Additional parameters that are passed on to the codec.
-# me=star improves the search for very fast
-# movements, but slows down the encoding.
-#x265-params=me=star
-
-# Keyint does FFmpeg automatically, otherwise
-# the setting must match the frame rate.
-#keyint_min=25
-
-# Profile does FFmpeg automatically.
-#profile=high
-
-# Source sRBG and retention of color space.
-# 720/1080=bt709 if no profile set. Useful
-# for formats smaller than 720 if no lossy
-# conversion is desired.
-colorspace=bt709
-color_trc=bt709
-color_primaries=bt709
-
-# Output in 10 bit, prevents 8-bit step formation
-pixel_format=yuv420p
-\end{lstlisting}
-
-\noindent \textit{NOTE:}
-
-A CRF of 16 delivers satisfactory results in most cases. However, if
-the video material is really \emph{grainy}, a CRF~16 can lead to
-unwanted large files. In this case, a trial export of perhaps one
-minute should be performed. The resulting bit rate can be used to
-correct the CRF to 17,\,18,\,19\ldots -- remember, a CRF of $0$ (zero)
-means lossless, the higher the number the stronger the lossy
-compression. The approximate calculation of the final file size can
-be extrapolated from the sample export.
-
-The color space information must be used explicitly so that it can
-be included in the video. \CGG{} or FFmpeg does not write it by
-itself. Without this information the players (e.\,g.\
-\href{https://mpv.io/}{mpv}) stick to the dimensions of the video
-and take the assumed color model from a table. With videos in the
-dimensions from 720 to 1080 this is bt709. For smaller dimensions,
-e.\,g.\ DVD, bt601 is assumed and for 4k and above it is
-bt2020. Normally this is not a problem, but if you want to export a
-FullHD without color loss to a smaller size like 576 for example,
-you have to inform the encoder as well as the decoder of the
-player. This also applies if the videos are to be loaded on video
-platforms, where they are then converted into videos of different
-sizes. It is a security measure to prevent false colors, such as the
-color profiles in digital photos and the copies made from them.
-
-The HEVC tuning has not been considered here, because it is is
-rarely used and requires background knowledge.
-
-Further links:
-\begin{itemize}
-\item \href{http://x265.readthedocs.org/en/default/}{x265
- Documentation}
-\item \href{http://x265.readthedocs.org/en/latest/cli.html}{x265
- Command Line Options}
-\item \href{http://x265.readthedocs.org/en/latest/presets.html}{x265
- Presets/Tuning}
-\end{itemize}
-
-\subsection{Piping Video to a Command Line}%
-\label{sub:piping_video_command_line}
-
-You can pipe a video to any command line on the computer, such as
-ffmpeg. This can be especially useful with raw video files. Next
-is an example usage.
-
-\begin{enumerate}
-\item on a terminal window create a named pipe file, for example:
-\begin{lstlisting}[style=sh]
-mknod /tmp/piper.yuv p
-\end{lstlisting} load your video and do your editing
-\item set up your Render (\texttt{Shift-R}), you can choose a raw
- format such as \textit{yuv} or \textit{rgb}
-\item for the filename \textit{Select a file to render to}, use the
- named pipe as created in step 1 (\texttt{/tmp/piper.yuv})
-\item for \textit{Insertion Strategy}, you will want to make sure to
- select \textit{insert nothing}
-\item click for OK on the green checkmark.(the \CGG{} gui will look
- like it is hanging while waiting for a command line to use the
- pipe.)
-\item on the terminal window, keyin your command, for example:
-\begin{lstlisting}[style=sh]
-/mnt0/build5/cinelerra-5.1/thirdparty/ffmpeg-3.4.1/ffmpeg -f \
- rawvideo -pixel_format yuv420p -video_size 1280x720 \
- -framerate 30000/1001 -i /tmp/piper.yuv /tmp/pys.mov
-\end{lstlisting}
-\end{enumerate}
-
-A slightly different option can be used instead that may be more
-familiar to some. In the render menu after choosing the File Format
-of \textit{ffmpeg}, use the pulldown to choose \textit{y4m} as the
-file type. This choice results in putting a header on the rendered
-output with some pertinent information that can be used for ffmpeg
-processing thus alleviating the requirement for
-\textit{pixel\_format}, \textit{video\_size}, and \textit{framerate}
-on the ffmpeg command line. In this case the format is
-\textit{yuv4mpegpipe} instead of \textit{rawvideo}. An example
-command line would look as follows (assuming the created pipe is
-called \texttt{piper.y4m}):
-\begin{lstlisting}[style=sh]
-ffmpeg -f yuv4mpegpipe -i /tmp/piper.y4m -vcodec libx264 /tmp/test.mp4
-\end{lstlisting}
-
-\subsection{Faststart Option for MOV type files}%
-\label{sub:faststart_option_mov0}
-
-If you have mov video and want to be able to start playing without
-having to first load the entire video, \textit{-movflags=+faststart}
-is needed for ffmpeg to put the meta-data, known as the \textit{moov
- atom}, at the beginning of the file. Otherwise, ffmpeg puts this
-atom at the end of the video file which means you have to wait to
-play until the whole video is loaded. Or worse yet, if the file
-becomes damaged in the middle and you can not get to the end, you
-won’t be able to play anything.
-
-Now you can have the \textit{moov atom} put on the front of the file
-(automatically via a second pass). To do this, when rendering using
-ffmpeg \& either the mp4 or qt format/container, click on the
-video/audio wrenches and choose \textit{faststart\_h264}. With the
-\textit{qt} format, settings will just be the default whereas the
-\textit{mp4} format uses the highest quality and lowest file size as
-possible, but you can easily modify these options in the associated
-Video Preset textbox.
-
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../CinelerraGG_Manual"
\chapter{Shortcuts}%
\label{cha:shortcuts}
+\index{shortcuts}
+
+In \CGGI{} a lot of shortcuts are defined for various operations.
+Although it is quite possible to do everything with the mouse, the extensive
+use of shortcuts can make the editing process much more convenient and
+efficient. However, with so large a variety of shortcuts it is not uncommon
+that some of them may interfere with assignments of the same shortcuts in
+the user's desktop environment, keyboard language switcher, etc. For
+example in KDE, the Alt-Tab and Shift-Alt-Tab shortcuts are commonly assigned to
+switch between different desktop applications, and if so, these keystrokes
+would not be available to \CGGI{}. Another example, in Arch linux KDE: the combination Alt+LMB does not translate the mask, but the entire Compositor window. To translate the mask we must use Ctrl+Alt+LMB.
+
+When having problems with some shortcut in \CGGI{}, it is recommended
+first to examine which set of shortcuts is assigned to the desktop
+environment and, if necessary, resolve the conflict. A special X11 application
+\texttt{xev} (or \texttt{xorg-xev}) can also help to test the keystrokes functionality (see \texttt{man xev}).
+Otherwise, \CGGI{} is completely desktop-neutral and has no
+requirements of some special window manager's support.
+
+Here the shortcuts are listed organized by window and type. Some specific alternatives are listed in~\ref{ssub:key_alternatives} in the "Key Alternatives" paragraph. Any reference to
+Alt or Ctrl always refers to the left one on the keyboard. In addition to this
+manual, you can view the shortcuts in html format via the \textit{shell cmds} icon
+on the top, right corner of the main program window. There is also a \textbf{hotkey
+Alt/h}, that can be used just about anywhere to get help on a specific window, menu,
+item, tooltip, button, and other elements (see \ref{sec:help_context_help}).
+
-Almost every \CGGI{} command has its own keyboard and mouse shortcuts. Here
-they are listed organized by window and type. If a desktop window manager and operating
-system is already using a specific key for its own purpose then that key will not be available
-for use as a shortcut in \CGG{}. An example might be the Alt key. Some specific alternatives
-are listed in~\ref{ssub:key_alternatives} in the "Key Alternatives" paragraph.
\section{Main window }%
\label{sec:main_window}
+\index{shortcuts!main window}
The Main window (also called the program window) consists of pulldown menus, buttons and keys.
\subsection*{Main menu pulldowns}% Without numbering.
\label{sub:main_menu_pulldowns}
+\index{shortcuts!main window pulldowns}
\renewcommand{\arraystretch}{1.15}% Increase line spacing slightly.
& Scan\dots & Ctrl-Alt-s & Open dvb scan window. \\
& SubTitle\dots & Alt-y & Open subtitle script window. \\
& Render\dots & Shift-R & Open render window. \\
- & Export EDL\dots & Shift-E & Open export EDL window. \\
+ & Export EDL\dots & Shift-E & Export to CMX3600 format. \\
& Batch Render\dots & Shift-B & Open batch render window. \\
& BD Render\dots & Ctrl-Shift-D & Open create bluray disk window. \\
& DVD Render\dots & Alt-D & Open create dvd disk window. \\
& Attach Effect\dots & & Open video effect selection for insert at edit boundary. \\
& Render Effect\dots & & Open video render select to render from select as pcm. \\
\midrule
- \textcolor{CinBlueText}{Tracks} & Move tracks up & Shift-Up & Circulate tracks up. \\
- & Move trks down & Shift-Down & Circulate tracks down. \\
+ \textcolor{CinBlueText}{Tracks} & Move tracks up & Shift-Up & Swap tracks up. \\
+ & Move trks down & Shift-Down & Swap tracks down. \\
+ & Roll tracks up & Ctrl-Shift-Up & Circulate tracks up. \\
+ & Roll trks down & Ctrl-Shift-Down & Circulate tracks down. \\
& Delete tracks & & Delete all tracks. \\
& Delete last track & Ctrl-d & Delete last track. \\
& Delete first track & Shift-D & Delete first track. \\
& -- Typeless keyfrs & & Toggle typeless keyframes mode. \\
& Save settings now & Ctrl-Shift-S & Save \CGG{}\_rc. \\
& Loop Playback & Shift-L & Set loop playback region to selection/all. \\
+ & Guide on timeline & Shift-L & Create a guide on timeline. \\
& Set bkg render & Shift-G & Toggle background rendering. \\
\midrule
\textcolor{CinBlueText}{View} & -- Show assets & 0 & Toggle show asset data. \\
& -- Split X pane & Ctrl-1 & Toggle $\frac{1}{2}$ horiz track timeline window panes. \\
& -- Split Y pane & Ctrl-2 & Toggle $\frac{1}{2}$ vert track timeline window panes. \\
& Mixer Viewer & Shift-M & Bring up a Mixer Viewer window. \\
- & Tile mixers & Alt-t & Tile mixer windows to original position/size. \\
+ & Drag Tile mixers & Alt-t & Create a drag box to be used to tile mixers. \\
& Default Positions & Ctrl-p & Reset window positions/size to defaults. \\
& Tile Left & & Set window positions/sizes to tile left screen. \\
& Tile Right & & Set window positions/size to tile right screen. \\
\subsection*{Main menu buttons}%
\label{sub:main_menu_buttons}
+\index{shortcuts!main window buttons}
\begin{longtable}[h]{>{\bfseries}p{0.15\textwidth-2\tabcolsep}p{0.25\textwidth-2\tabcolsep}p{0.2\textwidth-2\tabcolsep}p{0.4\textwidth-2\tabcolsep}}
\toprule
& Manual Goto & g & Jump to time selected by popup. \\
\midrule
\textcolor{CinBlueText}{Drag/Drop Edits} & Clear Select & Ctrl-Shift-A & Deselect all selected edits. \\
- & Select Edits & Ctrl-Alt-a & Add highlight to selected edits. \\
+ & Select Edits & Ctrl-Alt-' & Add highlight to selected edits. \\
+ & LMB & Alt + Drag & Drag select. \\
+ & LMB & Ctrl+Alt + Drag & Drag deselect. \\
& Copy & Ctrl-c & Copy selected edits into copy buffer. \\
& Cut & Ctrl-x & Delete selected edits/put in buffer/collapse. \\
& Mute & Ctrl-m & Delete selected edits/put in buffer/insert space. \\
\subsection*{Main menu Keys}%
\label{sub:main_menu_keys}
+\index{shortcuts!main window keys}
\begin{longtable}[h]{>{\bfseries}p{0.15\textwidth-2\tabcolsep}p{0.25\textwidth-2\tabcolsep}p{0.2\textwidth-2\tabcolsep}p{0.4\textwidth-2\tabcolsep}}
\toprule
& & Shift+click & Over edit causes highlight section to extend to cursor. \\
& & Shift+click & Over boundary of effect, trims only that effect. \\
& & Shift+click & Over Hard Edge of Blade Cut, toggles marker. \\
+ & & Shift+click & Between labels, highlights selection. \\
+ & & Shift+click & Over Automation Range values, changes value. \\
& Toggle single trk & Tab & Toggle single track arming status. \\
& Toggle other trks & Shift-tab & Toggle all of the other tracks arming status. \\
& & Double click & On plugin title bar, selects that area. \\
& U & & Paste the last Video transition. \\
& u & & Paste the last Audio transition. \\
& r & Ctrl & Proxy quick switch. \\
+ & & Ctrl +! & Assigns the timecode of the asset to the timebar. \\
& F1 & Shift & Toggle on/off all XYZ of camera. \\
& F2 & Shift & Toggle on/off all XYZ of projector. \\
& F1 & Ctrl+Shift & Use window layout \#1. \\
\end{longtable}
-\section{Compositor window}%
+\section{Compositor window shortcuts}%
\label{sec:compositor_window_shortcuts}
+\index{shortcuts!compositor window}
\subsection*{Compositor buttons}%
\label{ssec:compositor_buttons}
+\index{shortcuts!compositor buttons}
\begin{longtable}[h]{>{\bfseries}p{0.15\textwidth-2\tabcolsep}p{0.25\textwidth-2\tabcolsep}p{0.2\textwidth-2\tabcolsep}p{0.4\textwidth-2\tabcolsep}}
\toprule
\subsection*{Compositor keys }%
\label{ssec:compositor_keys}
+\index{shortcuts!compositor keys}
\begin{longtable}[h]{>{\bfseries}p{0.15\textwidth-2\tabcolsep}p{0.25\textwidth-2\tabcolsep}p{0.2\textwidth-2\tabcolsep}p{0.4\textwidth-2\tabcolsep}}
\toprule
\end{longtable}
-\section{Viewer window }%
+\section{Viewer window shortcuts }%
\label{sec:viewer_window_shortcuts}
+\index{shortcuts!viewer window}
\subsection*{Viewer buttons }%
\label{ssec:viewer_buttons}
+\index{shortcuts!viewer window buttons}
\begin{longtable}[h]{>{\bfseries}p{0.15\textwidth-2\tabcolsep}p{0.25\textwidth-2\tabcolsep}p{0.2\textwidth-2\tabcolsep}p{0.4\textwidth-2\tabcolsep}}
\toprule
\subsection*{Viewer Keys }%
\label{ssec:viewer_keys}
+\index{shortcuts!viewer keys}
\begin{longtable}[h]{>{\bfseries}p{0.15\textwidth-2\tabcolsep}p{0.25\textwidth-2\tabcolsep}p{0.2\textwidth-2\tabcolsep}p{0.4\textwidth-2\tabcolsep}}
\toprule
\section{Resources window Keys }%
\label{sec:resources_window_keys}
+\index{shortcuts!resources window}
\begin{longtable}[h]{>{\bfseries}p{0.15\textwidth-2\tabcolsep}p{0.25\textwidth-2\tabcolsep}p{0.2\textwidth-2\tabcolsep}p{0.4\textwidth-2\tabcolsep}}
\toprule
& F2 & Ctrl+Shift & Use window layout \#2. \\
& F3 & Ctrl+Shift & Use window layout \#3. \\
& F4 & Ctrl+Shift & Use window layout \#4. \\
+ & In Labels folder & Double click & On a Label, timeline cursor moves to label. \\
\bottomrule
\end{longtable}
\section{Other windows }%
\label{sec:other_windows}
+\index{shortcuts!other windows}
\subsection*{Other Buttons }%
\label{ssec:other_buttons}
+\index{shortcuts!other windows buttons}
\begin{longtable}[h]{>{\bfseries}p{0.15\textwidth-2\tabcolsep}p{0.25\textwidth-2\tabcolsep}p{0.2\textwidth-2\tabcolsep}p{0.4\textwidth-2\tabcolsep}}
\toprule
\subsection*{Other Keys }%
\label{ssec:other_keys}
+\index{shortcuts!other windows keys}
\begin{longtable}[h]{>{\bfseries}p{0.15\textwidth-2\tabcolsep}p{0.25\textwidth-2\tabcolsep}p{0.2\textwidth-2\tabcolsep}p{0.4\textwidth-2\tabcolsep}}
\toprule
\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}
\section{Copy/Paste and Highlight Usage}%
\label{sec:copy_paste_highlight_usage}
+\index{copy/paste}
There are 3 types of copy/cut and paste methods which exist in X windows, and most modern programs use 2 of them. The 3 cases are:
\item[copy and paste] called secondary (or clipboard) selection. Some more modern programs use Ctrl-C/Ctrl-X and Ctrl-V for this (some use other keys or qualifiers, like Shift).
\end{description}
-\subsection*{How it works:}%
-\label{sub:how_it_works}
+\subsection*{How Copy/Paste works:}%
+\label{sub:how_copy_paste_works}
All of the methods use window \textit{properties} to attach data, called a selection, to a source window. The program advertises the selection by using the X server. The window property used determines which selection type is set/advertised by the new selection.
\subsection{Playing/Seeking}%
\label{sub:playing_seeking}
+\index{seek!playing}
\textit{Seeking} targets and displays the next frame. The next frame is targeted because frame zero has no previous. When you seek, you reposition to just before the target frame, and since the play direction has not been established (there is no direction when seeking) it shows you the next frame. This produces the expected behavior when you seek to frame zero; you see the first frame. Seeking displays in the compositor what you are getting ready to work with/edit/etc; always showing the next frame in relation to the cursor. Technically, since seeking just resets the position, it would be correct not to update the compositor, but it is best to seek and show the next frame to confirm that it is the frame you expected to see.
\subsection{Always Show Next Frame}%
\label{sub:always_show_next_frame}
+\index{always show next frame}
Since some users prefer the insertion pointer to reflect the same as the Compositor a choice is available. For playing forward, there is a preference option which results in what looks like 1 was added to the frame displayed in the Compositor window. To enable this mode, check the box \texttt{Always show next frame}, and this will be saved to \texttt{.bcast5}. The option checkbox is in the \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab and when checked, any forward \textit{plays} in the Compositor window show the same frame as you would with a seek. Reverse plays and plays using a selection or In/Out pointers (with Ctrl) work the same as without this preference set. But you will no longer see the odd behavior where if you frame advance forward and then frame advance backward, the displayed frame does not change -- instead it will change and look more natural.
A color indicator that shows in the main track canvas timeline and the compositor timeline reminds the user which mode is currently active. The cursor in the compositor turns \textit{red} for default mode and \textit{white} for \textit{Always show next frame} mode. The top portion of the insertion cursor in the track canvas mirrors this, with red for default and white otherwise.
\subsection{Seeking Issues}%
\label{sub:seeking_issue}
+\index{seek!issue}
If you have an issue playing a video and not seeing it in the Compositor (just see a black screen), it is most likely due to the media not being designed to be \textit{editable}. It is most likely not damaged. Generally it just does not have keyframes which are needed for seeking which is what is done when you move around the media and start playing in the middle. The media plays just fine in the compositor if you always play from the beginning because then you don’t need keyframes to seek. You can get around this problem if you proxy the media. A good choice to use for the proxy would be \textit{use scalar}, \textit{ffmpeg/mp4} and size of $\frac{1}{2}$. The proxied media can then seek and you will see it play in the compositor because keyframes exist.
\section{Color Space and Color Range Affecting Playback}%
\label{sec:color_space_range_playback}
+\index{color!space}
+\index{color!range}
Playback \textit{single step} and \textit{plugins} cause the render to be in the session color model, while continuous playback with no plugins tries to use the file’s best color model for the display (for speed).
This can create a visible effect of a switch in color in the Compositor, usually shown as grayish versus over-bright.
\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} 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. 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}
+\index{color!model}
When you load media with the insertion strategy of \textit{replace current project}, the program code will
automatically use the "best model" for the render based on the media's codec. The best model is pretty
much going to be what works well for television. This automation was added to facilitate easy use of
This is \textit{simple} animation so you can expect speech synthesis not to be that good. And you will have to adjust punctuation and spelling based on the sound. Since the dialog is rendered on-demand, there is a delay when each character starts to speak but you can split dialog into shorter blocks to reduce the delay.
+You can see a step by step example in the website \url{http://www.g-raffa.eu/Cinelerra/HOWTO/animations.html}
+
\section{Textbox Non-std Character / Unicode Insertion}%
\label{sec:textbox_non_std_character_unicode}
+\index{unicode insertion}
If you want to enter a special character -- like a bullet, an accent grave character, or a mathematical summation symbol -- you can use the unicode equivalent in a textbox to do so. In the textbox, keyin Ctrl-Shift-U which puts you into single character unicode mode, then keyin the numerical value for the intended single character followed by the carriage return. For a voluminous list of possible special characters, you can go to {\small \url{https://unicode-table.com/en/}} on the internet to choose by highlighting a character to get its numerical equivalence. For example, $U+2022$ is a bullet. If you make a mistake, you can use the \textit{backspace} key or if you want to exit unicode-insert-mode, use the \textit{ESC} key. This feature is especially useful with the \textit{Title} plugin and for naming Tracks in the main window.
Some computer hardware factors to consider for better performance are listed here:
\begin{itemize}
- \item Multi-core and more SMP processors greatly improve \CGG{} speed by making use of threads.
- \item A large amount of free memory available can help speed up operations by avoiding unnecessary disk
- swaps and keeping videos easily accessible in memory.
+ \item Multi-core and more SMP processors greatly improve speed by making use of threads. \CGG{} automatically uses the available threads, but some processes are single-threaded anyway and these become the weak link in the chain. The \textit{Project SMP cpus} parameter is used to limit the use of threads in the deconding (playback) stage only. It is better to lower the number of threads to leave some for the system and for the plugins in use.
+ \item RAM: In video editing in general, the more RAM the better. A large amount of free memory available can help speed up operations by avoiding unnecessary disk swaps and keeping videos easily accessible in memory.
+You can optimize RAM utilization with \textit{Cache size} and \textit{Seconds to preroll render} parameters. See section \ref{sec:cache_and_preroll}. If there is limited RAM you must necessarily have a large swap partition. For system swap, (2 x RAM) GB seems to be more than sufficient. If the amount of memory being used by the program is close, then swap might save you but often if swapping becomes necessary, it presents more problems and you end up killing the \CGG{} process anyway.
\item Video editing is almost always I/O intensive. To create longer running videos at high resolution
- you will want to have a lot of disk space available on fast access disks.
+ you will want to have a lot of disk space available on fast access disks. The higher the transfer rate, the less slowdowns and problems. So a modern SSD is better than an old HDD.
\item \CGG{} benefits from OpenGL hardware acceleration. A good graphics card is worthwhile to have.
\item Multiple monitors really come in handy to increase productivity as you can see more information and
in bigger windows so you do not have to keep moving windows around.
\section{Hardware video acceleration}%
\label{sec:hardware_video_acceleration}
+\index{hardware!acceleration}
With certain newer, more powerful graphics boards and newer device drivers, there is the potential for enhanced \textit{decode} and \textit{encode} performance. Decode refers to loading and playing video in \CGG{}. The GPU, Graphics Processing Unit, on the graphics board is accessed via one of the following libraries: vdpau or vaapi. The hardware acceleration done by the graphics card increases performance by activating certain functions in connection with a few of the FFmpeg decoders. This use makes it possible for the graphics card to decode video, thus offloading the CPU. Decode operations are described here next.
Encode refers to rendering video and is described at the end of this section
VA-API, Video Acceleration API, is an open source library which provides both hardware accelerated video encoding and decoding for use mostly with Intel (and AMD) graphics boards.
+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.
+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.
+\end{itemize}
Currently only the most common codecs, such as MPEG-1, MPEG-2, MPEG-4, H.264 /MPEG-4 and h265 (hevc), are accelerated/optimized by the graphics card to play these particular video formats efficiently. The other formats are not optimized so you will see no performance improvement since the CPU will handle them as before, just as if no hardware acceleration was activated. There are many different graphics cards and computer systems setup, so you will have to test which specific settings work best for you. So far this has been tested at least with Nvidia, Radeon, and Broadwell graphics boards on some AMD and Intel computers; depending on the graphics card, two to ten times higher processing speeds can be achieved. However, most graphic operations are single-threaded so that performing the operations in the hardware may actually be slower than in software making use of multiple CPUs, which frequently multi-thread many operations simultaneously.
\subsection{GPU hardware decoding}%
\label{sub:gpu_hardware_decoding}
+\index{hardware!decoding}
\begin{enumerate}
\item Verify that you have installed \textit{libva-dev} or \textit{libva} on your operating system.
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
\subsubsection*{Hardware decoding in \CGG{}}%
\label{ssub:hardware_decoding_cinelerra}
-
+\index{appimage!vaapi/vdpau}
There are 4 phases during \CGG{}’s handling of hardware acceleration. These first 2 steps occur just \textit{before} the first read.
\begin{enumerate}
can not convert the data, you will see the error message of \textit{Error retrieving data from GPU to CPU}.
\end{enumerate}
-Due to variations in user’s computer hardware configuration, it is often suggested that you refer to your startup window to check for error messages. Since your situation is unique, the error may not have been seen by anyone else and is probably unknown/undocumented.
+AppImage will probably not allow for either VDPAU or VA-API hardware acceler-
+ation because the computer where AppImage is created will not have the same
+graphics card and/or vaapi/vdpau libraries as yours. In other words:
+
+\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. See \nameref{sub:built_appimage_scratch}.
+ \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.
+\end{itemize}
+
+Due to these variations in user’s computer hardware configuration, it is often suggested that you refer to your startup window to check for error messages. Since your situation is unique, the error may not have been seen by anyone else and is probably unknown/undocumented.
\textcolor{red}{For debugging problems, modify in the \CGG{} ffmpeg subdirectory, the file: \texttt{decode.opts} by temporarily changing the line from \textit{loglevel =fatal} to \textit{loglevel =verbose} and restarting \CGG{}}.
\subsubsection*{Possible improvements or differences}%
\subsubsection*{Special .opts file}%
\label{ssub:special_opts_file}
+\index{hardware!special opts files}
The situation may arise where you have enabled hardware acceleration and after loading several files for a project, you find that a file had some kind of error resulting in a black video instead of an image or you see an error message pop up which states something like \textit{Error retrieving data from GPU to CPU} or \textit{err: Unknown error occurred}. Because the \texttt{CIN\_HW\_DEV} environment variable is either all or none, ordinarily in order to correct the non-working video you would have to turn off hardware acceleration for the entire project/session. However, there is a way to continue working on your project without having to reload all of your files. You still use the environment variable and it will be effective for all of the formats it is able to handle, but you make an exception for any of the files that erred out. To do this you simply create a file in the same directory with the same name as the erring file with the different extension of .opts. The contents of this .opts file would just be the one line of:
HEVC with NVIDIA, VDPAU driver is buggy, skipping
\end{lstlisting}
-If you would like to see more information on what is occurring, you can modify in the \CGG{} ffmpeg subdirectory, the file: \texttt{decode.opts} by temporarily changing the line from \textit{loglevel =fatal} to \textit{loglevel =verbose} and restarting \CGG{}. Then you will see messages in the startup window like:
+AppImage does not provide this capability. If you would like to see more information on what is occurring, you can modify in the \CGG{} ffmpeg subdirectory, the file: \texttt{decode.opts} by temporarily changing the line from \textit{loglevel =fatal} to \textit{loglevel =verbose} and restarting \CGG{}. Then you will see messages in the startup window like:
\begin{lstlisting}[numbers=none]
[AVHWDeviceContext @ 0x7fc9540be940] Successfully created a VDPAU device
\subsection{GPU hardware encoding}%
\label{sub:gpu_hardware_encoding}
+\index{hardware!encoding}
Encoding using hardware acceleration of your graphics board GPU is
included in \CGG{} but it is of limited availability and works only
\subsubsection*{Broadcom, Intel HD, AMD}%
\label{ssub:broadcom_intel_amd}
+\index{hardware!vaapi}
To use hardware acceleration for rendering (that is, encoding) you do not have to set a preference or an environment variable, as was required for decoding. To use this feature you use an ffmpeg render options file which specifies a vaapi codec, such as h264\_vaapi. You must include this line in that options file to trigger the hardware probe: \qquad \texttt{CIN\_HW\_DEV=vaapi}
\subsubsection*{Nvidia graphics boards}%
\label{ssub:nvidia_graphics_card}
+\index{hardware!nvenc}
To use hardware acceleration for rendering (that is, encoding) you do not have to set a preference or an environment variable, as was required for decoding. To use this feature you use an ffmpeg render options file which specifies the nvenc codec, either \texttt{h264\_nvenc.mp4} or \texttt{nvenc.mp4}. There are several requirements in order for this to work on your computer as listed here:
\subsection{Effects (OpenCL, Cuda)}%
\label{sub:effects_opencl_cuda}
+\index{openCL}
+\index{CUDA}
CUDA® is a parallel computing platform / programming model developed by Nvidia that provides big increases in computing performance through use of the GPU. It was first introduced in about 2006 for applications in computationally intense fields such as astronomy, biology, chemistry, and physics.
\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:
\section{Optimized Playback -- X11 Direct}%
\label{sec:optimized_playback}
+\index{playback -X11 direct}
Normally, when \CGG{} reads a video frame, it is copied into a \textit{Vframe}. This frame may also need other actions performed on it, such as a color model change. In addition, ffmpeg and libzmpeg \textit{can\_scale\_input}. So the read can be color transformed and scaled just by asking the library to do that. This means that if the compositor is in a \textit{good} state with no zoom, the VFrame read can be done in the fastest render color model, and already scaled to the correct size for the compositor. In reality, this is not what you need for editing, but quite often the \textit{virtualconsole} is not used because the render is media only -- that is \textit{just data}. If no data transforms are needed and the input scaling can be done, the vrender program detects this, and tells the codec to transmit the data in a compatible way to the compositor canvas. This is the \textit{X11 direct} data path.
\section{Proxy Settings and Transcode}%
\label{sec:proxy_settings}
-Info on proxies in \nameref{sec:proxy}
+Information on proxies to reduce required CPU for less powerful computers is in the section \nameref{sec:proxy}.
-Info on transcode in \nameref{sec:transcode}
+Information on transcode which is used to provide keyframes to make the video seekable is in the section \nameref{sec:transcode}.
-\section{Some Settings Parameter Values}%
-\label{sec:settings_parameter_values}
+\section{Cache size and Seconds to preroll render}%
+\label{sec:cache_and_preroll}
+\index{cache}
-\texttt{Cache} in \texttt{Settings $\rightarrow$ Preferences, Performance} tab is used to store images on the timeline. One 1080p frame uses about 10 MB. The default setting is 256 and this is enough for testing and running. However, why not use more memory if it is available. To experiment for testing a good number tuned to the way you use your computer, set the cache to 0, start up \CGG{}, load a typical media file, play it and run \texttt{top} on the command line in another window to see how much memory is being used. In the \textit{top} display, look at \textit{free} memory. Whatever your computer is not using, is a good number to use for cache. If you start other programs, or change the design of the session so that it uses a lot of frame storage, you may need to experiment again later and resize accordingly.
+\textit{Cache size} in \texttt{Settings $\rightarrow$ Preferences, Performance} tab is used to store images on the timeline. One 1080p frame uses about 10 MB. The default setting is 256 and this is enough for testing and running. However, why not use more memory if it is available. To experiment for testing a good number tuned to the way you use your computer, set the cache to 0, start up \CGG{}, load a typical media file, play it and run \textit{top} on the command line in another window to see how much memory is being used. In the \textit{top} display, look at \textit{free} memory. Whatever your computer is not using, is a good number to use for cache. If you start other programs, or change the design of the session so that it uses a lot of frame storage, you may need to experiment again later and resize accordingly. The system keeps all requested data cached until it is replaced by other data or you reboot your PC. Reboot if you want to clear the cache.
-For system \textit{swap}, 1 GB seems to be more than sufficient. If the amount of memory being used by the program is \textit{close}, then swap might save you but often if swapping becomes necessary, it presents more problems and you end up killing the \CGG{} process anyway.
+\textit{Seconds to preroll render} in \texttt{Settings $\rightarrow$ Preferences, Performance} tab are used to increase the amount of frames (which are calculated in advance) at the time of their use. The default setting is 0.5 sec but you can increase it to 1.0 sec to improve smoothness in the timeline. Higher values are always less effective.
\section{Tips for Improving Smaller Computers Use}%
\label{sec:tips_improving_smaller_computers}
\item For large media files, use proxy to do your main editing.
\item In \texttt{Settings $\rightarrow$ Preferences, Appearance} tab, uncheck \textit{Use thumbnails in resource window}.
\item In \texttt{Settings $\rightarrow$ Preferences, Appearance} tab, uncheck \textit{Autocolor assets}.
- \item Speed-up certain time-consuming FFmpeg plugins through use of a carefully selected \texttt{.opts} file.
+ \item Speed-up certain time-consuming FFmpeg plugins through use of a carefully selected \texttt{.opts} file. See \nameref{sub:speedup_ffmpeg_plugin_opts}
\item For large media files, in \texttt{Settings $\rightarrow$ Preferences, Playback A}, Video Driver set \textit{use direct X11 render if possible}.
\item For the Video Driver in \texttt{Settings $\rightarrow$ Preferences, Playback A}, if using a good graphics card, choose \textit{X11-OpenGL}.
\item Set \textit{CIN\_HW\_DEV=vdpau} or \textit{vaapi} to use the graphics GPU for certain ffmpeg media decoding.
\section{General Crash Handling Tips}%
\label{sec:general_crash_tips}
+\index{crash handling tips}
This section is a handy guide for describing various kinds of software computer system failures. Only some of these various lockups or crashes can be dealt with. Hopefully, it will help to have some hints to know what kind of failure it is, or to save your work or to avoid future problems. For most of this, your user name must be root, although you can certainly try to see if it works for you when not root.
\subsection{Camera supplied LUTs}%
\label{sub:camera_supplied_luts}
+\index{LUT}
A LUT, acronym for Look-Up Table, is a mathematically precise way of taking specific RGB image values from a source image and modifying them to new RGB values by changing the hue, saturation and brightness values of that source image. In other words, LUTs are used to map one color space to another. Some high-end cameras supply a .cube file to use as input. There are several different ffmpeg plugins included with CinGG for using Lut's. These are:
\begin{description}
\item[F\_lut:] Compute and apply a lookup table to the RGB/YUV input video.
- \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}
+\index{dolby pro logic}
Dolby pro logic is an easy way to output 6 channel audio from a 2-channel soundcard with degraded but useful results. Rudimentary Dolby pro logic encoding can be achieved with usage of some effects.
\subsection{Remove Interlacing}%
\label{sub:remove_interlacing}
+\index{interlacing}
Interlacing often exists on older video sources, such as camcorders, and was previously used in broadcast television. Playing this video results in jagged images on a computer monitor, but with \CGG{} you can use deinterlacing effects to solve this. After some experimentation, it has been determined that the FFmpeg \textit{F\_kerndeint} plugin seems to produce the best results with the least amount of fiddling. But some of the parameters described next are pertinent to other potential plugin usage.
\begin{description}
\item[Line Doubling:] done by the \textit{Deinterlace} effect when set to \textit{Odd} lines or \textit{Even} lines. When applied to a track it reduces the vertical resolution by $\frac{1}{2}$ and gives you progressive frames with stairstepping. This is only useful when followed by a scale effect which reduces the image to half its size.
\item[Line averaging:] the \textit{Deinterlace} effect when set to \textit{Average even} lines or \textit{Average odd} lines does exactly what line doubling does except instead of making straight copies of the lines, it makes averages of the lines. This is actually useful for all scaling.
- \item[Inverse Telecine:] this is the most effective deinterlacing tool when the footage is an NTSC TV broadcast of a film. It is described in Effect Plugins (\ref{sub:inverse_telecine}), chapter 10.
+ \item[Inverse Telecine:] this is the most effective deinterlacing tool when the footage is an NTSC TV broadcast of a film. It is described in Effect Plugins (\ref{sub:inverse_telecine}).
\item[Time base correction:] the previously discussed three tools either destroy footage irreversibly or do not work at times. Time base correction may be a better tool to use because it leaves the footage intact. It does not reduce resolution, perceptually at least, and does not cause jittery timing.
- \item[Frames to Fields effect:] converts each frame to two frames, so it must be used on a timeline whose project frame rate is twice the footage's frame rate. In the first frame it puts a line-averaged copy of the even lines. In the second frame it puts a line-averaged copy of the odd lines. When played back at full framerate it gives the illusion of progressive video with no loss of detail. This effect can be reversed with the \textit{Fields to Frames} effect, which combines two frames of footage back into the one original interlaced frame at half the framerate. However, keep in mind that Frames to Fields inputs frames at half the framerate as the project. Effects before Frames to Fields process at the reduced framerate. The output of Frames to Fields can not be compressed as efficiently as the original because it introduces vertical twitter and a super high framerate. Interlaced $29.97$ fps footage can be made to look like film by applying Frames to Fields and then reducing the project frame rate of the resulting $59.94$ fps footage to $23.97$ fps. This produces no timing jitter and the occasional odd field gives the illusion of more detail than there would be if you just line averaged the original. It is described in Effect Plugins (\ref{sub:frames_to_fields}), chapter 10.
+ \item[Frames to Fields effect:] converts each frame to two frames, so it must be used on a timeline whose project frame rate is twice the footage's frame rate. In the first frame it puts a line-averaged copy of the even lines. In the second frame it puts a line-averaged copy of the odd lines. When played back at full framerate it gives the illusion of progressive video with no loss of detail. This effect can be reversed with the \textit{Fields to Frames} effect, which combines two frames of footage back into the one original interlaced frame at half the framerate. However, keep in mind that Frames to Fields inputs frames at half the framerate as the project. Effects before Frames to Fields process at the reduced framerate. The output of Frames to Fields can not be compressed as efficiently as the original because it introduces vertical twitter and a super high framerate. Interlaced $29.97$ fps footage can be made to look like film by applying Frames to Fields and then reducing the project frame rate of the resulting $59.94$ fps footage to $23.97$ fps. This produces no timing jitter and the occasional odd field gives the illusion of more detail than there would be if you just line averaged the original. It is described in Effect Plugins (\ref{sub:frames_to_fields}).
\item[HDTV exceptions:] $1920\times1080$ HDTV is encoded in a special way. If it is a broadcast of original HDTV film, an inverse telecine works. But if it is a rebroadcast of a $720\times480$ source, you need to use a time base and line doubling algorithm to deinterlace it.
\end{description}
\subsection{Time stretching audio}%
\label{sub:time_stretching_audio}
+\index{audio!time stretching}
It may appear that time stretching audio is a matter of selecting a region of the audio tracks, enabling recording for the desired tracks, going to\texttt{ Audio $\rightarrow$ Render Effect}, and applying \textit{TimeStretch}. In actuality there are 3 audio effects for time stretching: Time Stretch, Resample, and Asset info dialog.
You can see that the camera smoothly flows from keyframe point to next keyframe point, as \CGG{} automatically adjusts the camera movement in straight lines from point to point.
+\subsection{Video lagging behind Audio}%
+\label{sub:video_lagging}
+
+When there is a lag between the Audio and the Video, it can be because there are a lot of video frames
+and the computer can not display them as fast as the Audio can play the samples. However, this does
+not affect the rendered media in that the Audio and Video will be correctly synchronized. When playing
+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).
+
\chapter{Transition Plugins}%
\label{cha:transition_plugin}
+\index{transitions}
When playing a section of media where one edit ends and another edit begins on the timeline,
the usual result is that the first edit's output immediately is followed by the second edit. Transitions provide a better method whereby the first edit’s output becomes the second edit’s output. There are several different audio and video transitions listed in the Resources window as figure~\ref{fig:transition}.
\label{fig:transition}
\end{figure}
-Note the colored bar above the \textit{Shape Wipe} transition.
-This bar near the transition symbol shows the position and the length of the transition.
+Note the bluish colored bar above the \textit{Shape Wipe} transition.
+This bar near the transition symbol shows the position and the length of the transition. We can extend or reduce the length of the bar (and therefore the duration of the transition) by simply dragging the right edge of the bar to the desired position. In the \textit{zoom bar}, at the bottom left where the words \texttt{Welcome to Cinelerra} appears, this is replaced by the real time length of the bluish bar. The unit of measure adopted is that of the timebar --the default is \textit{hh:mm:ss:frame}; we can change it as we like (RMB on timebar).
-Transitions only apply to the matching track type; that is audio transitions only apply to audio tracks
-and video transitions only apply to video tracks.
+Transitions only apply to the matching track type; that is audio transitions only apply to audio tracks and video transitions only apply to video tracks.
An example usage of a transition follows:
\begin{enumerate}
Some Transitions have parameters that can be modified. To see these, move the pointer over the transition and right click which brings up a menu. A \texttt{Show} option will pop up a window if there are parameters that you can change to different values.
An \textit{On} option makes it possible to turn off the transition so that it will not be in effect in case you want to only enable it under certain conditions. The default value for this will be checked On.
A \textit{Length} option lets you adjust the length in seconds of the time that the transition will be in play. Values modified in the Show or Length will be saved for use the next time that transition is used until changed again.
-The \textit{Detach} option deletes the transition from the timeline. When you drag and drop a different transition on top of an existing transition on the timeline, it replaces the previous one.
+The \textit{Detach} option deletes the transition from the timeline. When you drag and drop a different transition on top of an existing transition on the timeline, it replaces the previous one (see figure~\ref{fig:transition01}).
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.8\linewidth]{transition01.png}
+ \caption{GUI for Wipe transition}
+ \label{fig:transition01}
+\end{figure}
There are some shortcuts to alleviate the dragging and dropping of transitions when you want to do a lot of them in various places on the timeline. After you have established the parameter values for a transition that you have dragged from the Resources window, you can use "U" and "u" keys to paste the same transition;
the "U" key pastes the last video transition while the "u" key pastes the last audio transition on all recordable tracks.
When \textit{Info on} is enabled via the right mouse button over an empty space in the Resources window (or the shortcut of the letter “i” is used), a short description will be provided in the lower right hand corner of that window for the current transition that the mouse is on.
-Once you have dragged and dropped a transition to the timeline, right mouse click on the transition and a pop-up menu will appear which provides an opportunity to make some changes. These are described next for all video and audio transitions.
+Once you have dragged and dropped a transition to the timeline, right mouse click on the transition and a pop-up menu will appear which provides an opportunity to make some changes. These are described next for all video and audio transitions (see figure~\ref{fig:transition01}).
\begin{description}
\item[Show] If available, clicking on this will pop up a transition specific menu.
\section{Audio Transitions}%
\label{sec:audio_transition}
+\index{transitions!audio}
\subsection*{Crossfade}%
\label{sub:crossfade}
+\index{crossfade}
Creates a smooth transition from one audio source edit to another. The crossfade has the first source \textit{fade out} while the second \textit{fades in}.
\section{Video Transitions}%
\label{sec:video_transition}
+\index{transitions!video}
\subsection*{BandSlide}%
\label{sub:bandslide}
+\index{band slide}
Bands slide across video and you see the image slide.
\subsection*{BandWipe}%
\label{sub:bandwipe}
+\index{band wipe}
Bands wipe across the video and you see the mask slides.
\subsection*{Dissolve}%
\label{sub:dissolve}
+\index{dissolve}
A soft dissolve where the In segment becomes more transparent while the Out segment begins to gradually show in its place until fully there.
\subsection*{Flash}%
\label{sub:flash}
+\index{flash}
The video flashes when transitioning between segments.
\subsection*{IrisSquare}%
\label{sub:irissquare}
+\index{iris square}
Video switches segments via a small rectangular view that gradually grows to full size.
\subsection*{Shape Wipe}%
\label{sub:shape_wipe}
+\index{shape wipe}
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}).
\begin{figure}[htpb] \centering
\includegraphics[width=0.9\linewidth]{star.png}
- \caption{Example of the Shape Wipe $\rightarrow$ Star}
+ \caption{Example of the Shape Wipe -> Star}
+% do not use rightarrow in a figure as HTML version does not like it
+% \caption{Example of the Shape Wipe $\rightarrow$ Star}
\label{fig:star}
\end{figure}
-You can add your own images to the Shape Wipe transition and there are some free ones available to download such as under the \texttt{Video $\rightarrow$ Transitions} pulldown at {\small \url{http://assistcg.com}}.
+You can add your own images to the Shape Wipe transition and there are some free ones available to download
+at {\small \url{http://assistcg.com}} - click on the \textit{Transitions} option under the \textit{Video} pulldown on that site. AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}.
To include new images in the Shape Wipe Transition, simply copy the file \textit{shape.jpg} or
\textit{shape.png} to the subdirectory \texttt{plugins/shapes} in your \CGG{} directory path. If
you prefer to have a better quality png used instead of the included 90\% jpg version, you can download
-the equivalent png versions at {\small \url{https://cinelerra-gg.org/download/ShapeWipe\_pngs.txz}}.
+the equivalent png versions at {\small \url{https://cinelerra-gg.org/download/testing/ShapeWipe\_pngs.txz}}.
You will then need to untar this file, choose the ones you want, and add them to your directory path.
-After an update of \CGG{}, they will have to be restored each time.
+And if that is not enough, you can download another 32 different transitions at {\small \url{https://cinelerra-gg.org/download/testing/ShapeWipe\_additional.txz}}. One particularly interesting ShapeWipe
+in this set is \textit{Fleur-de-lis-of-Florence}. After an update of \CGG{}, they will have to be restored each time.
\subsection*{Slide}%
\label{sub:slide}
+\index{slide}
Image slides into view; you can set Left/Right/In/Out.
\subsection*{Wipe}%
\label{sub:wipe}
+\index{wipe}
Wipe the image across screen starting left or right.
\subsection*{Zoom}%
\label{sub:zoom}
+\index{zoom}
Zoom out video at $\frac{X}{Y}$ magnification for some seconds.
French& fr.po& Updated often& Last update 2019 May\\
German& de.po& Updated often& Last update 2019 December\\
Russian& ru.po& Updated often& Last update 2019 October\\
- Spanish& es.po& Updated often& Last update 2020 February\\
+ Spanish& es.po& Updated often& Last update 2021 July\\
\\
Basque& eu.po& From CV with Google Translate & Last update 2016 October\\
Italian&it.po& From CV with Google Translate & Last update 2016 October\\
\\
Chinese& zh.po& Only Google Translate & 2016 October\\
Greek& el.po& Only Google Translate & 2016 October\\
- Hindi& hi,po& Only Google Translate & 2016 October\\
+ Hindi& hi.po& Only Google Translate & 2016 October\\
+ Hungarian& hu.po& Only Google Translate & 2021 October\\
Japanese& ja.po& Only Google Translate & 2016 October \\
Korean& ko.po& Only Google Translate & 2016 October \\
Ukrainian& uk.po & Only Google Translate & 2016 October \\
\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}
+
+\CGG{} is a complex and feature-rich program. Using a guide is indispensable. The official manual (in English) can be found in PDF and HTML format:
+
+\url{https://cinelerra-gg.org/download/CinelerraGG_Manual.pdf}
+
+\url{https://cinelerra-gg.org/download/CinelerraGG_Manual/}
+
+From within the program, you can invoke \textit{Context Help}, which references sections of the HTML manual\protect\footnote{credit Georgy(sge) for full implementation}.
+
+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_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}.
+
+If no context dependent help page is found, the manual page of Contents itself is shown.
+
+\subsection{Requesting context help for plugins}%
+\label{sub:context_help_plugins}
+\index{context help!plugins}
+
+There are several possibilities to request the help page for a particular plugin of interest.
+
+\begin{enumerate}
+ \item Pressing \texttt{Alt/h} with the mouse in the dialog window of that plugin's settings menu.
+ \item Pressing \texttt{Alt/h} while pointing with the mouse on the plugin bar in a track, transition bar, or transition icon.
+ \item Pressing \texttt{Alt/h} while pointing on the plugin name (icon) in the Resources window. If plugin tooltips are on, help for the highlighted plugin under the mouse is shown. If plugin tooltips are off, help for the selected plugin is shown.
+ \item Pressing \texttt{Alt/h} while pointing on the plugin name in the \textit{Attach Effect} dialog menu.
+\end{enumerate}
+
+\subsection{Requesting context help on Contour Shuttle}%
+\label{sub:context_help_contour_shuttle}
+\index{context help!contour shuttle}
+
+Contour Shuttle has no \texttt{Alt/h}. Nevertheless, its help page can be requested by simultaneously pressing the \texttt{Alt} key on the keyboard and any button on the Contour Shuttle. Note that the default Shuttle Configuration will be shown, rather than the one that you may have redefined.
+
+\subsection{Alternative web browser configuration}%
+\label{sub:alt_browser}
+\index{context help}
+
+If you prefer to get \textit{Context Help} pages displayed in the same tab
+in your browser instead of each help request displayed in a different tab,
+choose an alternative method as outlined here that works for you.
+
+\begin{enumerate}
+ \item Use another browser which has such a configurable mode. Here is an example for Seamonkey:
+\begin{lstlisting}[style=sh]
+ export CIN_BROWSER=seamonkey
+\end{lstlisting}
+In the seamonkey browser go to Edit -> Preferences... -> Browser -> Link
+Behavior -> Links from other applications .
+Set the option "Open links passed from other applications in:" to the value
+"The current tab/window".
+
+ \item Hack a default browser if you know how to hack it. Here is an example for Firefox.
+Start Firefox and open the pseudo-URL:
+\begin{lstlisting}[style=sh]
+ about:config
+\end{lstlisting}
+There will be a warning like "I'll be careful, I promise!", acknowledge it.
+Then there is a very long list with lots of undecipherable variable names.
+Scroll down to the variable: browser.link.open\_newwindow.override.external .
+By default it has value of -1, which means "use value of the more general
+variable: browser.link.open\_newwindow .
+Next, place the mouse cursor over: browser.link.open\_newwindow.override.external ,
+press the right mouse button, and select from the popup menu "Modify".
+You can now edit the value. Set it to 1, and you get new links from external
+apps opened in the same tab.
+
+If you set the variable "browser.link.open\_newwindow" instead, you get this
+behavior not only for external, but also for all links which otherwise would
+be opened in new tabs or new windows. The possible values of both variables
+are:
+\newline \hspace*{1cm} Value = 1: open in the current window and tab
+\newline \hspace*{1cm} Value = 2: open in the new window
+\newline \hspace*{1cm} Value = 3: (default): open in the new tab, current window
+\end{enumerate}
+
+\section{Troubleshooting}%
+\label{sec:troubleshooting}
+
You can report potential problems, bugs, and crashes to the \CGG{} website at:
\begin{center}
\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
troubleshooting help is included in other sections of this manual for specific features.
\section{What to Include in Problem Reports}%
-\label{cha:include_in_problem_reports}
+\label{sub:include_in_problem_reports}
+\index{report problem}
For the best help, if you have a reproducible problem and can provide the following list of materials for analysis, it
is usually possible to figure out what the problem is and how to fix it. It may be a simple usage or setup mistake or
a real bug which a programmer would like to fix rather quickly. Although it is not always necessary to provide this
\item If possible, also provide the rendered output, again using that representative sample.
\item Save a session file used with that same sample which will contain a lot of setup parameters; the best method to do this is to use the \texttt{File $\rightarrow$ Export Project}$\dots$ with the Copy option. That way all of the files will be in 1 location and easily loaded onto any other computer.
\item To make sure that the same rendering setup is used, it may be necessary to send an additional session file at the definition point just before rendering starts.
- \item Include the Operating System name and version number and version of Cin that you are running. You can find the date and time \textit{built} in the \texttt{Settings $\rightarrow$ Preferences, About} tab, bottom left corner.
+ \item Include the Operating System name and version number and version of \CGG{} that you are running. You can find the date and time \textit{built} in the \texttt{Settings $\rightarrow$ Preferences, About} tab, bottom left corner.
\end{itemize}
It is better to upload any files to a drop site as some of them can be quite large.
\section{Crash Dumps for Analysis}%
\label{cha:crash_dumps_analysis}
+\index{crash dumps}
If you get a SEGV crash and can explain what steps you took, a \texttt{/tmp/cinelerra\_<pid> .dmp} file is
very useful for analysis. You can also use Ctrl-c in the controlling window to force an INTR signal interrupt when
you think the program is hung up. You can only perform one Ctrl-c as the second Ctrl-c quits out of the program. It
\section{When things go wrong}%
\label{cha:when_things_go_wrong}
+\index{problem FAQ}
+
Sometimes things go wrong and there are some ways to continue your work without much trouble. Below is a list of items
to try before abandoning your session.
\item If your computer or the program crashed, you can use the \textit{File} pulldown choice
of \textit{Load backup} to get back to the last automatically saved session. It will most
likely not include the last few operations that were done though. But if you forgot to
-Load backup when you restarted Cinelerra, you have a second chance to use \texttt{File $\rightarrow$ Load} and
+Load backup when you restarted ,\CGG{} you have a second chance to use \texttt{File $\rightarrow$ Load} and
select \texttt{\$HOME/.bcast5/backup .prev} as long as you only loaded a different file and have
performed no editing operations.
\item If you accidentally destroyed your current project by a Load with
\item On an older computer, if you are playing media and it can not keep up, you can turn off \textit{Play every frame} in the \textit{Video Out} tab of \texttt{Settings $\rightarrow$ Preferences, Playback} tab. You will then see the video jump as it skips frames in order to stay caught up.
\item The \textit{Cache size} can be lowered to 1048 if playback seems choppy or if you have problems with lv2 plugins, or you can increase the \textit{Cache size} for better flow. This can be changed in \texttt{Settings $\rightarrow$ Preferences, Performance} tab.
\item After saving your session and settings and exiting \CGG{}, you might want to rename your current \texttt{\$HOME/.bcast5} directory and start with the default setup. This will eliminate your settings as the potential cause of a problem; however, all of your preferences will be lost until you go back to your original \texttt{.bcast5}.
- \item You can also temporarily rename just \CGG{}\_rc in your \$HOME/.bcast5 directory, so
+ \item You can also temporarily rename just Cinelerra\_rc in your \$HOME/.bcast5 directory, so
that a new file with the original name will be created with original defaults. You will lose your preferences,
but it is just for testing and you can move back the renamed \CGG{}\_rc over the new one if that is not the
cause of the problem. Be sure to stop and restart \CGG{} whenever you rename this file.
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
+error message you might see if this is not installed is: \textit{error while loading shared libraries: libGLU.so.1: cannot open shared object: No such file or directory}.
+ \item If you have updated your Operating System or newly installed some applications, it is
+possible that your LV2 plugin path may have been modified and be in disagreement with what you have set
+for \CGG{}. This could result in a crash upon startup. Look at the messages in the window from where
+you started \CGG{} to see if they look similiar to the following:
+\begin{lstlisting}[numbers=none,xleftmargin=10mm]
+LOAD: http://eq10q.sourceforge.net/matrix\_lr2ms
+LOAD: http://eq10q.sourceforge.net/matrix\_ms2lr
+LOAD: https://community.ardour.org/node/7596
+LOAD: urna-comp
+** segv at 0x7f2cd80813c4 in pid 4540, tid 4540
+\end{lstlisting}
+The last line before the \textit{segv} indicates the name of the LV2 plugin that is causing problems.
+Please refer to the section on LV2 plugins \ref{sec:audio_lv2_calf_plugins} to resolve the issue.
+ \item Check your \textit{Overlays} window if you do not see your Assets, Titles, Transitions, Plugin Keyframes, or other lines such as Fade, Cameras, etc. on your timeline.
+These items will still be functional, but you may be confused when you do not actually see their physical presence if you inadvertently unchecked them in the \textit{Overlays} window. Use the \textit{Window} pulldown to enable/disable the \textit{Show Overlays} window.
+ \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 -
+
+ \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 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}
the text results will be shown in that window.
\begin{itemize}[nosep]
-\item \textit{Dump EDL} will display your current EDL state on the screen in the window from where you started Cin. This can be useful to see information concerning a specific edit or a file path.
-\item \textit{Dump Plugins} will show the names of the currently loaded plugins.
-\item \textit{Dump Assets} displays the media assets that you have loaded and various pertinent details on each, such as samplerate, width, and height.
-\item \textit{Dump Undo }will dump the last 32 edits on the undo stack exactly as kept, which can be useful if you are looking to see how far back in the undo to go to get to a specific spot.
+\item \textit{Dump EDL} \index{EDL dump} will display your current EDL state on the screen in the window from where you started .\CGG{} This can be useful to see information concerning a specific edit or a file path.
+\item \textit{Dump Plugins} \index{plugins!dumps} will show the names of the currently loaded plugins.
+\item \textit{Dump Assets} \index{asset!dump} displays the media assets that you have loaded and various pertinent details on each, such as samplerate, width, and height.
+\item \textit{Dump Undo} \index{undo dump} will dump the last 32 edits on the undo stack exactly as kept, which can be useful if you are looking to see how far back in the undo to go to get to a specific spot.
\end{itemize}
\textbf{Common Problems}
This is not a problem. \CGG{} is building an index for your file in order to better seek. In that process, different methods are tried until a successful scan is complete.
\bigskip
+\textit{int FFMPEG::init\_encoder(const char*);} followed by
+\newline
+\textit{bad file format:} \quad \texttt{your directory/filename}
+
+This error occurs when you are rendering, or possibly capturing media via recording, when the
+file format/type are set to an incompatible option. To fix this in the Render window, check
+the Video and Audio wrenches configure compression settings and choose a compatible Compression
+as shown when clicking on the down arrow in the Preset window.
+\bigskip
+
\textit{AudioALSA::write\_buffer err -32(Broken pipe) at sample \#}
This indicates that there is something wrong with the audio. Some reasons for this are:
\item You simply stopped playing in \CGG{} while the audio is in progress.
\item Running on a computer where there is no sound card.
\item Incorrect setup of the audio parameters in the \texttt{Settings $\rightarrow$ Preferences, Playback} tab.
- \item Your sound system is already in use by another program, like when playing \textit{tunes} outside Cin.
+ \item Your sound system is already in use by another program, like when playing \textit{tunes} outside \CGG{}.
\end{itemize}
\bigskip
\medskip
\begin{itemize}[nosep]
- \item Cin doesn't come up in Debian with compiz window manager running. Workaround is to use a different window manager or bring up cin first and then compiz. There is also a report that Compiz leads to single frame problems after a certain amount of time in the case where you switch to fullscreen mode and than back to normal node -- cin stops working and so you will have to restart cin.
- \item When a library goes from one version to a later version, sometimes a pre-built Cin binary will fail because it was created at a different version than the one the user has on their computer. This seems to happen more frequently on Arch distros because Arch has continuous releases and is usually kept up to date. An example of the error message you might see in your startup window would be:\\
+ \item \CGG{} doesn't come up in Debian with compiz window manager running. Workaround is to use a different window manager or bring up cin first and then compiz. There is also a report that Compiz leads to single frame problems after a certain amount of time in the case where you switch to fullscreen mode and than back to normal node -- cin stops working and so you will have to restart cin.
+ \item When a library goes from one version to a later version, sometimes a pre-built \CGG{} binary will fail because it was created at a different version than the one the user has on their computer. This seems to happen more frequently on Arch distros because Arch has continuous releases and is usually kept up to date. An example of the error message you might see in your startup window would be:\\
\texttt{cin: error while loading shared libraries: libvpx.so.5: \\
cannot open shared object file: No such file}
\end{itemize}
You can usually install the required library to fix the problem. A temporary fix may be to create a symlink but this must be done with extreme caution as it may create an unstable condition. A better workaround is to use a tarball to install the software instead of the package build until the libraries are in sync between the build and your Operating System install.
\bigskip
-\textit{ Loading a very large number of media files, for example 500 clips, crashes \CGG{} with messages similar to the following that are displayed in the window from where you started Cin:}
+\textit{ Loading a very large number of media files, for example 500 clips, crashes \CGG{} with messages similar to the following that are displayed in the window from where you started \CGG{}:}
\begin{lstlisting}[numbers=none,xleftmargin=10mm]
This usually indicates that you are out of Operating System file descriptors. You can increase the amount easily with the following command line: \texttt{ulimit -n 4096} where 4096 is a size suggestion but can be increased. You can include this command line in your \texttt{.bashrc} or \texttt{.profile} file for the user login which gets run every time you login, or modify the Operating System limit for everyone in the system file, which for Fedora is \texttt{/etc/security/limits.conf}. Alternatively, you can reduce the number of file descriptors needed by going into \texttt{Settings $\rightarrow$ Preferences, Appearance} tab and unchecking the flag \textit{use thumbnails in resource window}.
+\bigskip
+
+\textit{Using a non-supported locale could cause a failure in starting \CGG{} with the following error.}
+
+\begin{lstlisting}[numbers=none,xleftmargin=10mm]
+
+ BC_WindowBase::init_im: Could not open input method.
+ unjoined tids / owner 1
+ 00007f543dffb700 / 00007f54989d5840 12BC_Clipboard
+
+\end{lstlisting}
+
+This is caused by LC\_CTYPE setting you are using, and maybe other Locale settings too.
+For example, using the following will cause the \textit{unjoined tids} error.
+
+\begin{lstlisting}[numbers=none,xleftmargin=10mm]
+ LC_CTYPE="en_IL" /mnt0/build5/cinelerra-5.1/bin/cin # set LC_CTYPE and start cin
+\end{lstlisting}
+
+This is an operating system error which is resolved by using the following startup instead:
+
+\begin{lstlisting}[numbers=none,xleftmargin=10mm]
+
+ LC_CTYPE="en_GB.utf8" /mnt0/build5/cinelerra-5.1/bin/cin # set LC_CTYPE and start cin
+\end{lstlisting}
+
+You can either export the LC\_CTYPE variable before starting \CGG{} or
+add this in your bash startup file or simply run from the command line as shown above.
+
\bigskip
\textit{Masking Feather is not working and produces error messages on the startup window similar to:}
In the mask window, check the box \textit{Disable OpenGL masking} to use software instead of OpenGL.
\section{Menu Bar Shell Commands}%
-\label{menu_bar_shell_commands}
+\label{sec:menu_bar_shell_commands}
+\index{shell commands}
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{cha:cinelerra_command_line_-h}
+\index{command line}
To see the command line parameters available to use with \CGG{}, key in:
\chapter{Interface (the 4+ Windows)}%
\label{cha:the_4_windows}
+\index{interface}
\begin{figure}[htpb]
\centering
\label{fig:Fenstergrundposition-en}
\end{figure}
-First it is important to know what an EDL is. When \CGG{} saves a file, it saves the EDL,
+First, it is important to know what an EDL is. When \CGG{} saves a file, it saves the EDL,
Edit Decision List, of your project which contains all the settings and locations of edits
-and pointers to the media so that the media is not modified. The EDL is described in \nameref{sec:edl_edit_decision_list}.
+and pointers to the media so that the media is not modified. The EDL is described
+in \nameref{sec:edl_edit_decision_list}.
+
+Second, for those users who would like to keep all 4 windows together for a better workflow,
+see \nameref{sec:focus_group}.
\section{Program Window}%
\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}. 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. 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
navigation (\nameref{cha:shortcuts}). This includes, for example, shortcuts like the \texttt{Home} and \texttt{End} keys to go to the beginning or end of the timeline.
Another example is in the default cut and paste mode, hold down \texttt{Shift} while pressing \texttt{Home} or \texttt{End} in order to select the region of the timeline between the insertion point and the key pressed.
+\subsection{Transport and Buttons Bar}%
+\label{sub:transport_buttons}
+\index{transport buttons}
+
+This is a short description of what is contained on the \textit{Transport and Buttons Bar} as seen in
+figure~\ref{fig:insertion-points}.
+Each of the symbols has an associated tooltip as an easy reminder of its function. The usage of
+several is described in a little more detail in other areas of this manual.
+
+\vspace{2ex}
+\begin{longtable}{ll}
+ \hline
+ First set of 3 symbols & Move in the reverse direction on the timeline \\
+ 4th symbol & Stop play \\
+ Third set of 3 symbols & Move in the forward direction on the timeline \\
+ Next 2 symbols & Set editing mode \\
+ Generate keyframes while tweaking & Explained in \ref{sec:generate_keyframe_tweaking}\\
+ Allow keyframe spanning & Explained in \ref{sec:allow_keyframes_spanning}\\
+ Lock labels from moving with edits & Toggle to lock or not lock labels from moving \\
+ Next 2 are In and Out pointers & Set or unset In and Out to define an area \\
+ To Clip & Create a clip of the designated area \\
+ Split / Cut & Split/Cut at insertion or selected area \\
+ Next 2 symbols & Usual Copy and Paste functions \\
+ Next 3 symbols & Label manipulation functions \\
+ Next 2 symbols & Used to move to other edits \\
+ Next 2 symbols & Fitting video to the display \\
+ Next 2 symbols & Undo and Redo last operation \\
+ Manual Go To & Explanation after this table \\
+ Set Timecode & Explained in \ref{sub:align_timecodes} \\
+ Gang Modes & Explained in \ref{sub:displaying_tracks_ganged} \\
+ \hline
+\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
+to goto forward the additional number in the textbox; and \textit{-} means to go in the reverse
+direction the number in the textbox. If you use \textit{Enter} in the textbox, the menu will stay
+up so that you can use it without having to continuously pop it up. If you use the OK check instead,
+the menu will be taken down. The pulldown arrow to the right of the textbox sets the
+\textit{Time Format} \index{time format} for the units to be used for position changing. This lets you change the units
+without having to modify your Preference.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.4\linewidth]{goto.png}
+ \caption{Goto position menu}
+ \label{fig:goto_menu}
+\end{figure}
+
+\textit{Time Format} options are:
+
+\begin{tabular}{ll}
+ \hline
+ h:mm:ss.sss & hours minutes seconds milliseconds \\
+ h:mm:ss:ff & hours minutes seconds frames \\
+ timecode \\
+ video frames \\
+ audio samples \\
+ audio samples (hex) \\
+ ssss.sss & milliseconds.xx \\
+ video frames (feet) \\
+ \hline
+\end{tabular}
+
\subsection{Zoom Panel}%
\label{sub:zoom_panel}
+\index{zoom!panel}
Below the displayed tracks in the timeline, you will find the zoom panel as seen in figure~\ref{fig:patchbay}.
In addition to the scrollbars, these options and their values are another set of tools for positioning the timeline.
You can either use the $\uparrow$ and $\downarrow$ arrows to change the sample zoom by a power of two, or use the mouse wheel on the tumblers to zoom in and out.
-The next option is \emph{amplitude} and it only affects the audio waveform size. \texttt{Ctrl-$\uparrow$} and \texttt{Ctrl-$\downarrow$} are shortcuts used to change the amplitude zoom as an alternative to the down arrow to the right of the numerical size.
+The next option is \emph{amplitude} and it only affects the audio waveform \index{waveform} size. \texttt{Ctrl-$\uparrow$} and \texttt{Ctrl-$\downarrow$} are shortcuts used to change the amplitude zoom as an alternative to the down arrow to the right of the numerical size.
The \emph{track audio and video zoom} affects all tracks of that type and determines the height of each track.
If you change the audio track zoom, the amplitude zoom will be changed also so that the audio waveforms
are proportionally sized.
Shortcuts, \texttt{Ctrl-Pgup} and \texttt{Ctrl-Pgdown}, change the track zoom to the next level simultaneously for all of the audio and video tracks.
-\emph{Automation type} is used for selecting one of the following: Audio Fade, Video Fade, Zoom, Speed, X, or Y (X and Y are for the compositor's Camera and Projector). When an auto line is present on
+\emph{Automation type} \index{autos} is used for selecting one of the following: Audio Fade, Video Fade, Zoom, Speed, X, or Y (X and Y are for the compositor's Camera and Projector). When an auto line is present on
the timeline and is being manipulated, a small square the same color as the line will be shown to
the left of the Automation type when the left mouse button (LMB) is pressed. This is just an indicator to make it easy to see what is being worked.
-The \emph{curve zoom} affects the curves for the selected \emph{automation type} in all the tracks of that type and determines the value range for those curves.
+The \emph{curve zoom} \index{autos!zoom} affects the curves for the selected \emph{automation type} in all the tracks of that type and determines the value range for those curves.
Use the tumbler arrows to the left of the numbers for the minimum value and the tumblers to the right for the maximum value, or manually enter the values in the text box.
Good default values for audio fade are -40.0 to 6.0 and for video fade are 0.0 to 100.0.
The tumbler arrows change curve amplitude, but the only way to curve offset is to use the fit curves button on the curve itself.
-The \emph{selection start time}, \emph{selection length}, and \emph{selection end time} display the current selected timeline values. When there is no selection, both the start and end time are the current
+The \emph{selection start time}, \emph{selection length}, and \emph{selection end time} \index{timeline!selection} display the current selected timeline values. When there is no selection, both the start and end time are the current
position of the timeline and the selection length is 0.
-The \emph{alpha slider} allows for varying the alpha value when using colors on the tracks as set in your \texttt{Preferences $\rightarrow$ Appearance} for \texttt{Autocolor assets}.
+The \emph{alpha slider} \index{alpha slider} allows for varying the alpha value when using colors on the tracks as set in your \texttt{Preferences $\rightarrow$ Appearance} for \texttt{Autocolor assets}.
It has no function without that flag set.
There are 3 additional pieces of information in the line immediately below the \textit{zoom panel}.
present along with its keyframe type, location on the timeline, and its current value. This is simply
for easy recognition of what is being worked. The second piece of helpful information is all the way to
the right which is a long rectangular box indicating the percentage completion of a render. Finally
-there is an X with the tooltip of "Cancel operation" used to stop an ongoing render
+there is an X with the tooltip of "Cancel operation" \index{cancel operation} used to stop an ongoing render
(the cancel operation may seem slow due to the amount of data still in the buffer upon cancellation).
\subsection{Track Popup Menu}%
\label{sub:track_popup_menu}
+\index{track!popup menu}
Each Track has a popup menu.
To activate the track popup menu, Right mouse click (RMB) on the track.
The Track Menu contains a number of options:
\begin{description}
- \item[Attach Effect] opens a dialog box of effects applicable to the type of track of audio or video.
- \item[Move up] moves the tracks one step up in the stack with the top track going to the bottom. This is applicable to all armed and disarmed tracks.
- \item[Move down] moves the tracks one step down in the stack with the
+ \item[Attach Effect] \index{attach effect} opens a dialog box of effects applicable to the type of track of audio or video.
+ \item[Move up] allows for changing the order of the tracks up; the actual code refers
+to this as a swap. Disarmed tracks affect the results.
+ \item[Move down] allow for changing the order of the tracks down; the actual code refers
+to this as a swap. Disarmed tracks affect the results.
+ \item[Roll up] moves the tracks one step up in the stack with the top track going to the bottom. This is applicable to all armed and disarmed tracks.
+ \item[Roll down] moves the tracks one step down in the stack with the
bottom track going to the top. This is applicable to all armed and disarmed tracks.
\item[Delete track] removes the track from the timeline.
\item[Add Track] adds a track of the same media type as the one selected, audio or video, above the selected track.
- \item[Find in Resources] the media file on that track at the location of the insert pointer will be highlighted in the media folder in the Resources window. If the
+ \item[Find in Resources] \index{find in resources} the media file on that track at the location of the insert pointer will be highlighted in the media folder in the Resources window. If the
Resources window is closed, media is found and highlighted but the Resources window is not displayed.
- \item[Show edit] will point out the exact start and stop points along with the length of the current edit on
+ \item[Show edit] \index{show edit} will point out the exact start and stop points along with the length of the current edit on
that track as well as the media name, track name and number, and edit number.
- \item[User title] is used to change the title name. This is really handy for files that have very long and
+ \item[User title] \index{user title} is used to change the title name. This is really handy for files that have very long and
similar names that would get cut off during edits. You can use short names to better differentiate the
media. In Drag and Drop editing mode, if you select multiple edits all of those clips will have
their title name changed.
- \item[Bar color] allows the user to select a specific color for the title bar. This helps to more easily locate a piece of media.
- \item[Swap up] allows for changing the order of the tracks up. Disarmed tracks affect the results.
- \item[Swap down] allow for changing the order of the tracks down. Disarmed tracks affect the results.
- \item[Resize Track] resizes the track; this is only applicable to video tracks.
- \item[Match Output Size] resizes the track to match the current output size; this is only applicable to video tracks.
+ \item[Bar color] \index{bar color} allows the user to select a specific color for the title bar. This helps to more easily locate a piece of media.
+ \item[Resize Track] \index{resize track} resizes the track; this is only applicable to video tracks.
+ \item[Match Output Size] \index{match output size} resizes the track to match the current output size; this is only applicable to video tracks.
\end{description}
\subsection{Insertion Point}%
\label{sub:insertion_point}
+\index{insertion point}
The insertion point (figure~\ref{fig:insertion-points}) is the vertical hairline mark that spans the timeline in the program window - it can be a solid line but most of the time it will be flashing.
Like the cursor on a word processor, the insertion point marks the place on the timeline where the next
operation will begin. It is the starting point of all play operations and is the point where a paste operation will occur.
In some cases, when rendering it defines the beginning of the region of the timeline to be rendered.
-To move the insertion point, you move the mouse inside the timebar area and click with the left mouse button.
+To move the insertion point, you move the mouse inside the timebar \index{timebar} area and click with the left mouse button.
You can use any place on the timebar to reposition the insertion point as long as that spot is not blocked
-by In/Out point or a label.
+by In/Out point \index{in/out point} or a label \index{label}.
In cut and paste editing mode, you can also change the position of the insertion point with a simple
left mouse click in the timeline itself.
When moving the insertion point, the position is either aligned to frames or aligned to samples.
-For best results, \textit{Align cursor on frames} when editing a video track and \textit{Align to samples} when editing audio.
+For best results, \textit{Align cursor on frames} \index{Align cursor on frames} when editing a video track and \textit{Align to samples} \index{Align to samples} when editing audio.
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}
+\index{drag and drop}
+\index{cut and paste}
There are 2 different editing modes for operations which affect how the insertion point and editing
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}, or immediately to the right of the arrow,
-the \texttt{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 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}.
+
+\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,
a selected region or using the Copy/Paste Behavior as outlined in~\ref{sub:copy_paste_behavior}.
In this mode, clicking the LMB in the timeline does not reposition the \textit{Insertion Point}.
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.4\linewidth]{i-beam.png}
+ \caption{I-beam + in/out + labels}
+ \label{fig:i-beam}
+\end{figure}
+
When the I-beam is highlighted, you are in \emph{cut and paste mode}.
In cut and paste mode, clicking the LMB in the timeline does reposition the \textit{Insertion Point}.
Double clicking in the timeline selects the entire edit the cursor is over, i.e.\ that column.
and paste operations. It is also the playback range used for the subsequent playback operation.
Holding down the Shift key while clicking in the timeline extends the highlighted region.
-\begin{figure}[htpb]
- \centering
- \includegraphics[width=0.4\linewidth]{i-beam.png}
- \caption{I-beam + in/out + labels}
- \label{fig:i-beam}
-\end{figure}
-
\subsection{In/Out Points}%
\label{sub:in_out_points}
+\index{in/out point}
-The In/Out points, displayed on the timebar by [ and ] brackets, can be set in either of the editing modes to define the selection.
+The In/Out points, displayed on the timebar \index{timebar} by [ and ] brackets, can be set in either of the editing modes to define the selection.
In the timebar, a colored bar will show between these 2 brackets to better outline the area selected.
-In \emph{drag and drop mode}, they are an easy way to define a selected region.
+In \emph{drag and drop mode} \index{drag and drop}, they are an easy way to define a selected region.
It is important to remember that a highlighted area overrides the In/Out points. That is, if a highlighted area and In/Out points are both set, the highlighted area is changed by editing operations and the In/Out points are ignored.
But if no region is highlighted, the In/Out points are used.
To avoid confusion, use either highlighting or In/Out points but not both at the same time.
-To set In/Out points, in the timebar move to the position where you want the In point and click the In
+To set In/Out points, in the timebar move to the position where you want the Insertion point \index{insertion point} and click the In
point icon or one of the [ or < keys.
Then move the insertion point to a position after the In point and click the ] or > or the Out point icon.
You can use these same icons or keyboard characters to toggle In/Out points on or off.
\item[Ctrl-t] clears both In/Out points
\end{description}
+\subsection{Guide on timeline}%
+\label{sub:guide_timeline}
+\index{guide lines}
+
+It can be useful to have visual reference points on the timeline to help you position edits relative to other tracks. For example in manual synchronization of audio and video. You can set two points on the timeline with In/Out points or by selecting a range in Cut and Paste mode. Now we use \texttt{Settings $\rightarrow$ Loop Playback} (Shift - L) to make two vertical green lines appear at the edges of the selection. Originally this function is used to limit the playback within this range, but we can take advantage of the fact that the green lines remain even when we move the insertion point or delete the In/Out points or deselect the range. So they can be used as a visual reference when we want to move the edits precisely. To delete these guides press \textit{Shift-L} again.
+
\subsection{Labels}%
\label{sub:labels}
+\index{label}
Labels are used in order to set exact locations on the timeline that you want to be able to easily get to.
-To create a label, position the insertion point at a location and click on the label icon in the Transport
-and Buttons bar. The new label is displayed on the timebar as a down arrow at that location as shown in
+To create a label, position the insertion point \index{insertion point} at a location and click on the label icon in the Transport
+and Buttons bar. The new label is displayed on the timebar \index{timebar} as a down arrow at that location as shown in
figure~\ref{fig:i-beam}. Whenever the insertion point is at the same position as a label, it changes
color to emphasize that it is exactly at that spot.
Labels make it so you can jump back and forth to exact marked locations on the timeline.
\subsection{Color Title Bars and Assets}%
\label{sub:color_title_bars_and_assets}
-
+\index{bar color}
+\index{asset!color}
In order to visually aid in locating clips on the timeline that are from the same media file, you can have them auto-colored or self-colored. Auto-color is
an automatic system to always color the files on the timeline when loaded.
Self-color is a manual coloring requiring the user to take definitive action.
To change these individually or selectively, use the Edits popup \emph{Bar Color} option and click on \textit{Default} in the color picker window.
And that’s not all!
-There is an \emph{alpha fader slider bar} on the bottom of the main window on the right hand side of the Zoom Panel.
+There is an \emph{alpha fader slider bar} \index{alpha slider} on the bottom of the main window on the right hand side of the Zoom Panel.
With this alpha slider, you can colorize your video and audio tracks to either see only the color at 0.0 or see only the image at 1.0.
This slider bar affects all colored areas of the Autocolor assets and the self-colored ones.
In the case when a specifically changed edit alpha value is set in the color picker
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] options for loading, saving, and rendering as described in other sections (\ref{cha:load_save_and_the_EDL}).
- \item[Edit] edit functions; most of which have shortcuts that you will quickly learn (\ref{cha:editing}).
- \item[Keyframes] keyframe options which are described in the Keyframe section (\ref{cha:keyframes}).
- \item[Audio] audio functions such as \textit{Add track}, \textit{Attach effect}
+ \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}).
+ \item[Keyframes] keyframe options which are described in the Keyframe section (\ref{cha:keyframes}).
+ \item[Audio] \index{audio} audio functions such as \textit{Add track}, \textit{Attach effect}
and \textit{Attach transition}. The \textit{Attach effect} is especially useful when
you need the effect to be applied to all related audio tracks as a \textit{Shared effect}
and is described as an alternative method of application in section \ref{sec:shared_effect_tracks}.
- \item[Video] video functions such as \textit{Add track, Default/Attach transition, Render effect}.
- \item[Tracks] move or delete tracks are the most often used plus \textit{Align Timecodes}.
- \item[Settings] much of this is described elsewhere with the most frequently used to include
+ \item[Video] \index{video} video functions such as \textit{Add track, Default/Attach transition, Render effect}.
+ \item[Tracks] \index{track} move or delete tracks are the most often used plus \textit{Align Timecodes}.
+ \item[Settings] \index{settings} much of this is described elsewhere with the most frequently used to include
Preferences (\ref{cha:configuration_settings_preferences}), Format (\ref{cha:project_and_media_attributes}),
Proxy and Transcode (\ref{sec:proxy_settings}), as well as the others.
- \item[View] for display or modifying asset parameters and values to include Fade, Speed, and Cameras.
- \item[Window] window manipulation functions.
+ \item[View] \index{view} for display or modifying asset parameters and values to include Fade, Speed, and Cameras.
+ \item[Window] \index{window} window manipulation functions.
\end{description}
\subsection{Window Layouts}%
\label{sub:window_layouts}
+ \index{window!layout}
If you like to use different window layouts than the default for certain scenarios, you can setup, save, and load 4 variations.
First, position your \CGG{} windows where you want them to be and then use the \textit{Window} pulldown and choose \emph{Save layout}. Note the words \emph{Save layout} highlighted in Figure~\ref{fig:window_layouts}a with 4 names shown to the right and below of that highlight.
%TODO High res image replace
\end{minipage}
\begin{minipage}{.49\linewidth}
+%begin{latexonly}
\vspace{13ex}
+%end{latexonly}
\center{\includegraphics[width=1\linewidth]{window_layout2.png}}\\ b)
%TODO Alpha channel
\end{minipage}
\subsection{Multi-Pane Support}%
\label{sub:multipane_support}
+ \index{multi-pane}
The main \CGG{} edit window holds the Track Canvas which can be divided into 4 panes of track data: 1 or 2 vertical panes and/or 1 or 2 horizontal panes. To split the track, use the \textit{Window} pulldown, and then click on \textit{Split X} or \textit{Split Y} depending on how you wish to split the track. Alternatively, the canvas pane types can be changed using keys \textit{<Ctrl-1>} for toggle split horizontal or \textit{<Ctrl-2>} for toggle split vertical. Or the track can be split into panes by using the \textit{+ widget} in the lower right hand corner of the track canvas. Once the track has been divided, you can use the + widget shortcut or the drag bars to change the size of the panes.
\subsubsection*{Repeat Play / Looping Method}%
\label{ssub:repeat_play_looping_method}
+ \index{transport buttons}
There are 2 methods for repeat play or looping on the timeline and 1 method for both the Compositor and the Viewer. This works in conjunction with any of the transport buttons or shortcuts in either forward or reverse as usual. The 1 exception is that the Shift key can not be used to either add or subtract audio within the repeat area.
\subsubsection*{Playback Speed Automation Support}%
\label{ssub:playback_speed_automation_support}
-
+ \index{autos!speed}
The speed automation causes the playback sampling rate to increase or decrease to a period controlled by the speed automation curve.
This can make playback speed-up or slow-down according to the scaled sampling rate, as \textit{time is multiplied by speed} (Speed $\times$ Unit\_rate). For more information on changing
\subsubsection*{Alternative to using Numeric Keypad for Playing}%
\label{ssub:alternative_to_using_numeric_keypad_for_playing}
+ \index{keypad}
For the keyboards without a numeric keypad or if you prefer to use keys closer to where you normally type, there are alternative keys for the play/transport functions. These are listed below.
\section{Compositor Window}%
\label{sec:compositor_window}
+ \index{compositor!window}
\begin{figure}[htpb]
\centering
\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}
+\index{compositor!controls}
On the bottom of the window, there are many
-of the same transport buttons and controls that are available in the Program window.
+of the same transport buttons \index{transport buttons} and controls that are available in the Program window.
They work the same as in the Program window and also have tooltips that are visible
when you mouse over each of the icons so their use is fairly obvious. However,
-of particular note is the button \textit{Click to play} which is described in~\ref{sub:click_to_play_in_viewer_and_compositor}. Next is the \textit{Videoscope} button which is used to enable the scopes window
+of particular note is the button \textit{Click to play} \index{click to play} which is described in~\ref{sub:click_to_play_in_viewer_and_compositor}. Next is the \textit{Videoscope} \index{videoscope} button which is used to enable the scopes window
without having to apply the filter to the tracks/edits.
-Next to all of these controls all the way to the right side, there is a \textit{zoom menu} and a \textit{tally light}. The \textit{zoom menu} has a pulldown with different settings that you can choose from
+Next to all of these controls all the way to the right side, there is a \textit{zoom menu} \index{zoom!menu} and a \textit{tally light}. The \textit{zoom menu} has a pulldown with different settings that you can choose from
or you can just use the tumbler arrows to the right. Generally when just getting started, you
will be using the default \textit{Auto} option. The window size is not changed, but rather
the size of the video itself. In addition there are many shortcuts for zooming that you
will find in the Shortcuts chapter (\ref{cha:shortcuts}).
-To resize the entire window instead of just the video, use a RMB click in the compositor
-window which brings up a menu with all the zoom levels, zoom auto mode, and some other options.
+Using a RMB click in the compositor window brings up a menu with several options \index{compositor!RMB options}. One of these
+is \emph{Resize Window} which allows for resizing the entire window instead of just the video
+and if you highlight that, you can choose from several variations for the window size.
+Other available options include self-explanatory ones of \emph{Fullscreen} with "f" as a toggle
+to go to fullscreen and to revert to non-fullscreen and \emph{Zoom Auto}.
As you would expect, whenever the video is zoomed so that only part of the image is visible
in the window, scrollbars are automatically added as needed on the bottom, the right hand
side, or both.
Other options include \emph{Reset camera} and \emph{Reset projector} which obviously are used
-to reset the camera and the projector (reference~\ref{sub:camera_and_projector}).
+to reset the camera and the projector (reference~\ref{sub:camera_and_projector}). And
+\emph{Camera/Projector keyframe} will create a keyframe at that point on the timeline for
+X,Y, and Z without the requirement of being in \textit{Automatic Keyframe Mode}. More
+information is described in the section \nameref{sec:compositor_keyframes}.
The \emph{Hide controls/Show controls} option is great for hiding the left hand toolbar and
bottom set of controls for a cleaner look.
Next to the zoom tumbler arrows, is a \textit{tally light} that will be filled in with some color
(often red or blue) when a rendering operation
-is taking place. This is especially helpful when loading a very large video so you know
+is taking place \index{rendering!operation light}. This is especially helpful when loading a very large video so you know
when it is finished loading. You should pay attention to this \textit{tally light} when performing
a particularly time-consuming operation so that you do not keep executing more operations
that just have to wait until completion of that CPU intensive operation. Also, you should look
\subsection{Compositor Toolbar}%
\label{sub:compositor_toolbar}
+\index{compositor!toolbar}
On the left hand side of the Compositor window, there is a toolbar with several icons that
provide functions for viewing and compositing the video. Each of these operational features
to prevent an accidental click from making unwanted changes. When you enable this option, any
of the other enabled tools will automatically be disabled.
- \item[Zoom view / magnifying glass] when enabled, the \textit{Zoom view} immediately results
+ \item[Zoom view / magnifying glass] \index{zoom!slider} when enabled, the \textit{Zoom view} immediately results
in the addition of a zoom slider for fine viewing.
The vertically oriented \textit{zoom slider} will be displayed underneath the last icon of the toolbar and extends
to almost the end of the toolbar.
\label{fig:zoom_slider}
\end{figure}
\begin{description}
- \item[Edit mask] brings up a mask editing menu with many versatile options as
+ \item[Edit mask] \index{mask} brings up a mask editing menu with many versatile options as
described in great detail later in this section (\ref{sub:masks}). You may also have to click on
\textit{Show tool info} to popup the menu depending on whether or not you dismissed that window previously.
- \item[Ruler] this can be a handy tool to get the X,Y coordinates of an exact point or to
+ \item[Ruler] \index{ruler} this can be a handy tool to get the X,Y coordinates of an exact point or to
measure the distance between 2 points. To use the \textit{Ruler}, move the mouse on the video to
get to the desired spot - these X,Y coordinates will be displayed in the \textit{Current} text
box. Clicking the LMB creates Point 1 and then continue to hold down the LMB so that a ruler line is created between
so you will have to use Alt+Ctrl instead.
If you dismiss the Ruler menu, click on
\textit{Show tool info} to get the menu to popup again.
- \item[Adjust camera automation] the camera brings up the camera editing tool. Enable \textit{Show tool info} if the popup menu does not appear. More detail for usage is provided in the subsequent
+ \item[Adjust camera automation] \index{camera} the camera brings up the camera editing tool. Enable \textit{Show tool info} if the popup menu does not appear. More detail for usage is provided in the subsequent
section~\ref{sub:camera_and_projector}.
- \item[Adjust projector automation] the projector brings up the projector editing tool. Enable \textit{Show tool info} to get the menu to popup again. More detail for usage is provided in the
+ \item[Adjust projector automation] \index{projector} the projector brings up the projector editing tool. Enable \textit{Show tool info} to get the menu to popup again. More detail for usage is provided in the
subsequent section~\ref{sub:camera_and_projector}.
- \item[Crop a layer or output] this is a cropping tool used to reduce the visible picture area.
+ \item[Crop a layer or output] \index{crop} this is a cropping tool used to reduce the visible picture area.
More detail for usage is provided in a
subsequent paragraph (\ref{sub:cropping}). There is also a Crop \& Position plugin that provides
a different set of capabilities described in~\ref{sub:crop_position}.
Enable \textit{Show tool info} to get the menu to popup if it does not come
up automatically.
- \item[Get color / eyedropper] brings up the eyedropper used to detect the color at a
+ \item[Get color / eyedropper] \index{eyedropper} brings up the eyedropper used to detect the color at a
particular spot. Enable the \textit{Show tool info} if the Color popup menu does not come up
automatically or if that menu was accidentally dismissed. Click on a specific color in the video
output with the LMB to see the selected color. You can then use that color's
around the cross cursor and an average value of the color will be the result.
If you \textit{Use maximum}, instead of an average value of the color, the result
will be the maximum of all values within that square.
- \item[Show tool info] this tool button is used in conjunction with the other tools on the
+ \item[Show tool info] \index{tool info} this tool button is used in conjunction with the other tools on the
compositor's toolbar. You only need to click on this if one of these tools popup menu does not
come up or has been dismissed - Mask, Ruler, Camera, Projector, Crop, or Eyedropper tools.
You can also use it when highlighted to dismiss the highlighted tool's dialog box.
\label{fig:safe_regions}
\end{figure}
- \item[Show safe regions] draws 2 outlines to display the safe regions in the video as you
+ \item[Show safe regions] \index{safe region} draws 2 outlines to display the safe regions in the video as you
can see in Figure~\ref{fig:safe_regions}.
On some particular TVs/monitors/displays, the borders of the image are cut off and that
cut off section might not be as square as it appears in the compositor window.
\subsection{Compositing}%
\label{sub:compositing}
+\index{compositing}
-Much of the editing in \CGG{} involves "compositing" which is the combining of visual
+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.
\subsubsection*{The Temporary}%
\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}
+\index{track!size}
+\index{output size}
The \textit{Track size} is used to define the temporary size with each track having a different size (viewports). It also serves to conform the input media to a chosen format (aspect ratio). So each track can have a different format (viewport).
You can see or set the track size by RMB click on a track and then select \emph{Resize Track} to resize
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.
-\subsubsection*{Aspect Ratio (Theory)}%
-\label{ssub:aspect_ratio_theory}
+To clarify, let's take an example.
-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.
+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}
-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.
+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.
-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 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:
-\qquad $\frac{W}{H} =$ aspect ratio ($\frac{pixels}{pixels}$)
+\qquad $\frac{W}{H} =$ frame 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}$
-
-where:
-
-\textit{DAR}= Display Aspect Ratio
-
-\textit{PAR}= Pixel Aspect Ratio (1 or 1:1 is square)
+from which: $H = 816$ pixels
-\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}
+\index{camera}
+\index{projector}
In the compositor window, \textit{Adjust camera automation} and \textit{Adjust projector automation}
are editing tools to control operation of the camera and projector. In \CGG{}'s compositing
\subsubsection*{Projector Compositing}%
\label{ssub:projector_compositing}
+\index{projector}
The purpose of the \textit{projector} is to composite several sources from various tracks into one
output track. The projector alignment frame is the same as the camera's viewport, except that it
\subsubsection*{The Viewport}%
\label{ssub:viewport}
+\index{viewport}
-The \textit{viewport} is a window on the camera that frames the area of source video. The size of the current track is used for the initial size of the viewport. A smaller viewport, for example ($640\times480$), captures a smaller area; whereas a larger viewport of ($800\times600$) captures a larger area. If the captured area is larger than the source video, the empty spaces will be automatically filled with blanks. To change the size and aspect ratio of the viewport (Camera) of a single track, right-click on the track in the timeline and choose Resize Track. Here we can vary the height and base of the viewport in pixels or choose the multiplication coefficient for each side (Scale). With OK we will see the change in the Compositor window with the new dimensions reflected in the green box. We can have different size viewports for each video track on the timeline. To go back, reset the viewport to the original value. After the viewport is defined, the camera needs to be placed right above the area of interest in the source video. Operations to control the location of the camera are as follows:
+The \textit{viewport} is a window on the camera that frames the area of source video. The size of the current track is used for the initial size of the viewport. A smaller viewport, for example ($640\times480$), captures a smaller area; whereas a larger viewport of ($800\times600$) captures a larger area. If the captured area is larger than the source video, the empty spaces will be automatically filled with blanks. To change the size and aspect ratio of the viewport (Camera \index{camera}) of a single track, right-click on the track in the timeline and choose Resize Track. Here we can vary the height and base of the viewport in pixels or choose the multiplication coefficient for each side (Scale). With OK we will see the change in the Compositor window with the new dimensions reflected in the green box. We can have different size viewports for each video track on the timeline. To go back, reset the viewport to the original value. After the viewport is defined, the camera needs to be placed right above the area of interest in the source video. Operations to control the location of the camera are as follows:
\begin{enumerate}
\item In the compositor window you should see the selected track.
\subsubsection*{Camera Compositing}%
\label{ssub:camera_compositing}
+\index{camera}
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}
+\index{tool info}
+\index{camera}
+\index{projector}
The camera and projector have shortcut operations that do not appear in the popup menu and are not represented in video overlays.
These are accessed in the \emph{Show tool info} window.
Most operations in the Compositor window have a tool window which is enabled by activating the question mark icon (figure~\ref{fig:camera_tool}).
-\begin{wrapfigure}[10]{O}{0.45\linewidth}
- %\vspace{1ex}
- \includegraphics[width=1.0\linewidth]{camera_tool.png}
- \caption{Camera and Projector tool}
- \label{fig:camera_tool}
-\end{wrapfigure}
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.8\linewidth]{camera_tool.png}
+ \caption{Camera and Projector tool}
+ \label{fig:camera_tool}
+\end{figure}
-In the case of the camera and projector, the tool window shows $x$, $y$, and $z$ coordinates.
-By either tumbling or entering text directly, the camera and projector can be precisely positioned.
-Justification types are also defined for easy access.
-A popular justification operation is upper left projection after image reduction.
-This is used when reducing the size of video with aspect ratio adjustment.
-In the last figure you see the choices for justification as the location of the line in the 6 boxes in the order of left, center horizontal, right, top, center vertical, and bottom.
+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.
The translation effect allows simultaneous aspect ratio conversion and reduction but is easier to use if the reduced video is put in the upper left of the \textit{temporary} instead of in the center.
The track size is set to the original size of the video and the camera is centered.
Without any effects, this produces just the cropped center portion of the video in the output.
The translation effect is dropped onto the video track. The input dimensions of the translation effect are set to the original size and the output dimensions are set to the reduced size.
-To put the reduced video in the center subsection that the projector shows would require offsetting out $x$ and out $y$ by a complicated calculation.
-Instead, we leave out $x$ and out $y$ at 0 and use the projector's tool window.
+To put the reduced video in the center subsection that the projector shows would require offsetting out $X$ and out $Y$ by a complicated calculation.
+Instead, we leave out $X$ and out $Y$ at 0 and use the projector's tool window.
By selecting left justify and top justify, the projector displays the reduced image from the top left corner of the \textit{temporary} in the center of the output.
-Other buttons cover the 5 modes of curves interpolation: smooth, linear, tangent, free, bump.
+In the \textit{Curve type} section we can choose between various interpolation algorithms that determine the curve type \index{curve type}:
\begin{description}
\item[smooth:] bezier interpolation which are flat at the endpts
\item[linear:] piecewise linear curve.
\item[tangent:] bezier interpolation with collinear endpts in a specified line.
- \item[disjoint:] piecewise bezier, if there is such a thing.
+ \item[free:] piecewise bezier, if there is such a thing.
\item[bump:] has 2 values, one viewed from the left/right, discontinuous.
\end{description}
-Finally there are the 2 buttons for the bump curves: settings on Right/Left Edges and Span (see \nameref{sec:bump_autos}).
+In the \textit{Keyframe} section we can create new keyframes and set them as Bump autos (\textit{Right/Left edges} and \textit{Span} buttons). For further details see \nameref{sec:bump_autos}.
\subsubsection*{Reset to Default}%
\label{ssub:reset_default}
\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}
\begin{enumerate}
\item Start by shrinking the projector to $z=0.500$ ($\frac{1}{4}$ of the original frame).
\subsection{Masks}%
\label{sub:masks}
+\index{mask}
Masks can be used to accomplish various tasks but basically are used to select an area of the
video to be displayed or hidden.
\subsubsection*{Compositing pipeline with masks}%
\label{ssub:compositing_pipeline_with_masks}
+\index{compositing pipeline}
The Mask popup menu can be overwhelming upon first encounter. However, if you follow the next
few steps you can create a single simple mask without having to understand every possible parameter.
+Be sure you are working in a Format that includes the Alpha channel, YUVA or RGBA, because you need
+to have transparency for masking to show or will end up with only a black area.
\begin{enumerate}
\item To define a mask, in the Compositor window click on the \textit{Edit mask} icon to get the popup Mask menu. If the menu does not come up, click on the \textit{Show tool info}.
\item On the video, LMB click on the place where you want to start a mask.
\textit{smooth curve} $\rightarrow$ smooth all points on a mask edge curve.
-\textit{smooth all} $\rightarrow$ smooth all active masks.
+\textit{smooth all} $\rightarrow$ smooth all enabled masks on this track.
Linear buttons of \textit{linear point}, \textit{linear curve}, and \textit{linear all}, perform the inverse of the smooth functions.
The control point vectors on the bezier endpoints are set to zero magnitude.
-In addition there is a \textit{Markers} and a \textit{Boundary} checkbox which come in handy to turn off the display of the points and the outline of the mask. Turning off \textit{Markers} is very useful when you have a lot of control points that clutter the display and make it more difficult to see the actual mask. A helpful feature is available by disabling \textit{Markers} and enabling \textit{Boundary} which results in all masks being displayed in the viewer; for example you can then see mask 0, mask 1 \dots at the same time.
+In addition there is a \textit{Markers} and a \textit{Boundary} checkbox which come in handy to turn off the display of the points and the outline of the mask. Turning off \textit{Markers} is very useful when you have a lot of control points that clutter the display and make it more difficult to see the actual mask. A helpful feature is available by disabling \textit{Markers} and enabling \textit{Boundary} which results in all masks being displayed in the viewer
+even if they are not enabled; for example you can then see mask 0, mask 1 \dots at the same time.
A \textit{gang} symbol on the right hand side of this section, tooltip of \textit{Gang points}, is another useful feature that makes it easy to drag a mask to an exact coordinate using the \textit{X} or \textit{Y} textbox for numerical input or the associated tumblers. This works like the \texttt{Alt+LMB drag} translate but provides the ability to be precise.
\subsection{Cropping}%
\label{sub:cropping}
+\index{crop}
Cropping is used to reduce the visible picture area by changing the output dimensions, width and
height in pixels, and the $X, Y$ values. An example of cropping and the crop menu is seen in
There are 3 choices of crop methods to choose in the menu pulldown on the bottom right side.
\begin{enumerate}
\item Reformat - Reformat Session crops and changes the Format for the entire session.
-Because the Format is changed, this is applied to all tracks in the project.
+Because the Format is changed, this is applied to all tracks in the project.
The part of the image outside the rectangle will be cut off and the projector will make the video fit.
The \texttt{Settings $\rightarrow$ Format} window will show the new project Width and Height values and
the projector tool window will show the new $X, Y$ values. Track size remains unchanged.
\section{Viewer Window}%
\label{sec:viewer_window}
+\index{viewer!window}
The Viewer window (figure~\ref{fig:viewer_window}) is convenient for previewing your media and
clips. It can also be used for editing with cuts and then paste operations into the timeline or
-to create a clip. There are transport buttons to use in the same manner as in the Program
+to create a clip. There are transport buttons \index{transport buttons} to use in the same manner as in the Program
and Compositor windows or you can quickly move through the media by dragging with the LMB in
the timebar above the transport buttons.
Note that you can have multiple Viewer windows open with different or even the same media asset.
After the media is loaded you can use the transport buttons to play, rewind, stop, and so on, or
-for fast previewing drag with the LMB anywhere on the timebar slider. There is also the Videoscope
+for fast previewing drag with the LMB anywhere on the timebar slider. There is also the Videoscope \index{videoscope}
button which is to used to enable the scopes window without having to apply the filter to the tracks/edits.
-A few more options available in the Viewer window can be accessed with a RMB click on the display.
+A few more options available in the Viewer window can be accessed with a RMB click on the display \index{viewer!RMB options}.
These functions are listed next.
\begin{enumerate}
\item To remove the current media from being displayed, choose \textit{Close source}.
\end{enumerate}
-The Viewer uses the project's output size format settings to display the media instead of the
+The Viewer uses the project's output size output size{entry} format settings to display the media instead of the
original asset's format. Operations performed in the Viewer affect a temporary EDL or a clip rather
than the timeline. By default, the Viewer window is automatically available but if it gets
accidentally closed you can open it again by using the pulldown \texttt{Window $\rightarrow$ Show
to listen to the audio to see if it is what you would like to add to a timeline audio track for
your project. To do this, you simply drag the audio file from the Resources window in the same
manner as a video file. The viewer was designed to "view" images rather than play audio so in order
-to make it obvious that audio media is loaded to the viewer, a waveform is displayed that is the
+to make it obvious that audio media is loaded to the viewer, a waveform \index{waveform} is displayed that is the
same waveform as shown in the Resources window thumbnail when in the \textit{Display Icons} mode.
This waveform only represents the first 5 seconds of the media and will not change or move while
playing in the Viewer window. But you can play the entire piece of media in the window
In both the Viewer and Compositor windows, there is an arrow on the right hand side of the other
buttons in the edit panel as shown in figure~\ref{fig:viewer_window}. The "play" button can be
-toggled on/off via this arrow, which has a tooltip of \textit{Click to play}. When enabled
+toggled on/off via this arrow, which has a tooltip of \textit{Click to play} \index{click to play}. When enabled
the arrow is white surrounded by green and when disabled the arrow is red.\protect\footnote{the color and the look will be different for themes other than the default theme of Cakewalk}
The purpose of enabling this capability is to make it really easy to play the media in the window
by just using the left mouse button to start or stop the play. The entire main canvas surface
\subsection{Timebar + Preview Region Usage in the Compositor and Viewer}%
\label{sub:timebar_preview_region_usage_in_the_compositor_and_viewer}
+\index{preview region}
-The Viewer and Compositor each have a timebar control area with an indicator line below the video
-output. The \textit{timebar} shows the whole time covered by the program. When a video asset
-is loaded in the main window and you move in the compositor, the insertion pointer in the main
-window will reflect those movements. However, this is not the case with the viewer. In the viewer
-only that specific media is shown and there is no corresponding movement on the timeline.
-
-Both the Compositor and Viewer support labels and in/out pointer which are displayed in the timebar.
-And as with the movements, when you use the labels or in/out pointer in the compositor timebar,
-the result will also be reflected in the main window timebar. Along with that, of course, when
-you move to a label or in/out pointer in the compositor, the insertion point in the program window
-will go to that position.
-
-The timebar in the compositor and the viewer can be used to define a region known as the \textit{preview region}.
-This preview region is the region of the timeline which the slider affects.
-By using a preview region inside the entire program and using the slider inside the preview region you can very precisely and relatively quickly seek in the compositor and viewer.
-The preview region can be especially handy when you have large pieces of media by previewing one section, then move to the next section.
-
-The active preview region is the zone between the edge bars.
-The full range of the window slider pointer action is down-scaled to the active preview region.
-To use this, set the preview active region as a media time region of interest.
-Now addressing the timebar with the mouse only operates as if the timebar is zoomed to the scale of the active preview zone.
-This has the effect of magnifying the interesting media in terms of the mouse pointer addressing, for fine-tuning.
+The Viewer and Compositor each have a timebar \index{timebar} control area with a red indicator
+line below the video output. The timebar shows the whole time covered by the
+resource. When a video resource is loaded in the main window and you move in the
+compositor, the insertion pointer in the main window will reflect those movements.
+But in the viewer only that specific media is shown and there is no corresponding movement on the timeline.
\begin{figure}[htpb]
- \centering
- \includegraphics[width=1.0\linewidth]{timebar1.png}
- \caption{The arrow above the green colored “play forward” transport button is on the timebar.}
- \label{fig:timebar1}
+ \centering
+ \includegraphics[width=1.0\linewidth]{timebar1.png}
+ \caption{The mouse cursor, above the green colored “play forward” transport button, is on the timebar. Further to the right we see the red "indicator line".}
+ \label{fig:timebar1}
\end{figure}
+Both the Compositor and Viewer support labels and in/out pointer which are dis-
+played in the timebar. And as with the movements, when you use the labels or
+in/out pointer in the compositor timebar, the result will also be reflected in the
+main window timebar. Along with that, of course, when you move to a label or
+in/out pointer in the compositor, the insertion point in the program window will
+go to that position.
+
+The timebar in the compositor and the viewer covers the whole length of the resource
+loaded in there. Moving the mouse with the LMB pressed moves the position in the resources as indicated by the indicator line. A complete mouse movement between left and right edges of the window moves the indicator line by default along the whole timebar. With long resources it can be difficult to precisely locate sections in the resource. To make this easier, you can limit the effect of the same window-wide mouse movement to a smaller area of the timebar, this area is defined as the preview region. This region can also be moved along the timebar.
+
+For instance, if you need to get a few 10 second clips from an 60 minute video, you could define a one-minute preview region, move it approximately to a place where a clip needs to be taken, and easily select with the mouse in and out points within the region, because the whole window mouse movement now covers 1 minute instead of 60 minutes.
+
To create and use a preview region, hold down the right mouse button inside the timebar on either end of the timebar close to the edge until you see the resize pointer.
While continuously holding the right mouse button down, drag the arrow away from the end towards the middle of the timebar until you have the desired area outlined.
The slider will be a dark red color while the selected preview region will remain the same initial black color.
\begin{figure}[htpb]
\centering
\includegraphics[width=1.0\linewidth]{timebar3.png}
- \caption{Here you can see the right-facing arrow used to drag the other end of the slider bar.
- The black area between is the actual preview area.}
+ \caption{Here you can see the right-facing arrow used to drag the other end of the slider bar. The black area is the actual preview area.}
\label{fig:timebar3}
\end{figure}
The selected area will move left or right as you drag and still retains the same size.
\begin{figure}[htpb]
- \centering
- \includegraphics[width=1.0\linewidth]{timebar4.png}
- \caption{Note the double-headed fat arrow in the preview area used to move the selection over.}
- \label{fig:timebar4}
+ \centering
+ \includegraphics[width=1.0\linewidth]{timebar4.png}
+ \caption{Note the double-headed fat arrow in the black preview area used to move the selection over.}
+ \label{fig:timebar4}
\end{figure}
Settings:
\begin{enumerate}
- \item If no preview region is set, increasing the length of the media on the timeline by inserting media or
- appending, has no effect on the non-selected preview region. That is, you will not see the blue slider
- suddenly mysteriously appear.
- \item If the preview region is set, when you replace the current project or file, the preview region is
- automatically disabled.
- \item If the preview region is set, when you append data or change the size of the current project, the
- preview region may appear to either move, shrink, or grow depending on the new length of the
- media on the timeline.
- \item To disable the preview region, you will have to drag both the right and the left blue slider bars
- completely to their corresponding end so that there is no longer any visible red slider.
+ \item If no preview region is set, increasing the length of the media on the timeline by inserting media or appending, has no effect on the non-selected preview region. That is, you will not see the reddish slider bar suddenly mysteriously appear.
+ \item If the preview region is set, when you replace the current project or file, the preview region is automatically disabled.
+ \item If the preview region is set, when you append data or change the size of the current project, the preview region may appear to either move, shrink, or grow depending on the new length of the media on the timeline.
+ \item To disable the preview region, you will have to drag both the right and the left blue slider bars completely to their corresponding end so that there is no longer any visible red slider.
\end{enumerate}
A good method for taking advantage of the preview region is described here.
Back in the main track canvas, move to the location of the area you want to end looking and again you will see the red indicator line in the compositor.
Use the right mouse drag from the right to stop at that end point. Using this method is often easier than continuous usage of the single frame move which can be tedious.
-One last interesting item of note -- sometimes you may wish to see just a little more that is outside the preview region and you can do so! You can actually move outside the compositor or viewer window space and view more, at least until you hit the end of the monitor space.
+One last interesting item of note -- sometimes you may wish to see just a little more that is outside the preview region and you can do so! You can actually move outside the compositor or viewer window space and view more, at least until you hit the end of the screen space.
\section{Resources Window}%
\label{sec:resources_window}
+\index{resources window}
Effects, transitions, labels, clips, proxies, user bins, and media assets are accessed here.
Most of the resources are inserted into the project by dragging them out of the resource window.
\end{figure}
The resources window is divided into two areas (figure~\ref{fig:resource_window}.
-One area lists folders and another area lists the folder contents.
+One area lists folders \index{folders} and another area lists the folder contents \index{folder contents}.
Going into the folder list and clicking on a folder updates the contents area with the contents of that folder.
The folders can be displayed as icons or text.
There are several variations for displaying the contents; select \emph{Display text}, \emph{Display icons}, \emph{Display icons packed}, \emph{Display icons list} as types of display for the assets or plugins.
Use the letter “\texttt{V}” to easily scroll through the choices and see which you prefer.
You can also get to these options from the menu by a right mouse click in the window.
-A \emph{Search} option is available for any of the folders in the Resources window (and when using \textit{Attach effect} on the main track canvas for the Plugins).
+A \emph{Search} \index{search resources} option is available for any of the folders in the Resources window (and when using \textit{Attach effect} on the main track canvas for the Plugins).
As you type in characters a match is made with that substring.
Names that do not match are filtered out making it a lot easier to find the item you are looking for.
The characters can be any where within the phrase and it does not matter if upper or lower case.
-Other options you will see if you \textit{right mouse click in the folder} which brings up the menu are described next.
+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.
\item[Snapshot/Grabshot] use to take a quick snapshot or to grab a specific area on the screen. These functions are described in detail in section \ref{sub:snapshot_grabshot}).
\end{description}
-Using the right mouse click to bring up a menu in the folder area, you can also switch from Display text to Display icons, Sort items and create, delete and manipulate user defined folders/bins. Select Folder to create a user Folder or modify an existing folder.
+Using the right mouse click to bring up a menu in the folder area \index{folders!RMB options}, you can also switch from Display text to Display icons, Sort items and create, delete and manipulate user defined folders/bins. Select Folder to create a user Folder or modify an existing folder.
If you \textit{right mouse click on a highlighted/selected resource}, several options are available depending on whether the resource is an effect or transition or a piece of media.
You can highlight several for some options so that it is applicable to all of them, such as Info.
-Those listed immediately below are the available choices for media assets.
+Those listed immediately below are the available choices for media assets \index{asset!RMB options}.
\begin{description}
- \item[Info] provided basic Asset information; details are described later in this section.
+ \item[Info] provided basic Asset information; details are described later in this section.
\item[Display text/icons] same as mentioned previously.
\item[Sort] same as mentioned previously.
- \item[Rebuild index] if you switch from/to using ffmpeg/native for media loading, you should rebuild
+ \item[Rebuild index] \index{rebuild index} if you switch from/to using ffmpeg/native for media loading, you should rebuild
indexes. Or if you get hangs on media or strange looking tracks, you might want to rebuild indexes.
\item[View] use this option to bring up the media in the Viewer window.
\item[View in new window] in order to not overwrite your current viewer window, you can open any
\item[Open mixers] when you record with multiple cameras setup, you can work with them most easily
using the mixer mode. This is described in detail
\item[Paste]
- \item[Match] if you need to change your media parameters you can choose from the following: Match frame
+ \item[Match] \index{match format} if you need to change your media parameters you can choose from the following: Match frame
rate, Match project size, Match all
- \item[Remove] use to Remove the asset from the project or with caution, to Remove from disk permanently.
+ \item[Remove] \index{remove asset} use to Remove the asset from the project or with caution, to Remove from disk permanently.
\end{description}
-In the case of Effects or Transitions, a right mouse click on a highlighted selection leads to an \emph{Info} button which gives a short 1 line description of what the effect/transition can be used for.
-For Labels, choices are \emph{Edit}, \emph{Label}, and \emph{Go to}.
-For Clips, \emph{Nest} and \emph{UnNest} as described elsewhere are available.
+In the case of Effects or Transitions \index{effects/transitions info}, a right mouse click on a highlighted selection leads to an \emph{Info} button which gives a short 1 line description of what the effect/transition can be used for.
+For Labels \index{label!RMB options}, choices are \emph{Edit}, \emph{Label}, and \emph{Go to}.
+For Clips \index{clip!RMB options}, \emph{Nest} and \emph{UnNest} as described elsewhere are available.
\subsection{Info Asset Details}%
\label{sub:info_asset_details}
-
+\index{asset!info}
The asset \emph{Info} window also can be used to display detailed information about the selected/highlighted media file -- available for any loaded media of type mpeg or ffmpeg.
This is extremely helpful in determining what type of media it is, size, resolution, format, and type/number of audio streams. It is especially useful for multiple program streams. You can have the info window popped on several of your assets simultaneously.
\textit{Sample rate} and \textit{Frame rate} allows you to impose a different sampling or Fps of the audio and video assets.
-Another option is \textit{Resize} button, which allows you to change the sides (in pixels) of the frame of the asset.
+Another option is \textit{Resize} button, which allows you to change the size (in pixels) of the frame of the asset.
\textit{Asset's interlacing} is the type of interlacing the asset has: If the file is (H)DV type, recognition and configuration is done automatically. All other media types will be set unknown. So we have to manually set the interlacing \protect\footnote{From Igor ubuntu's mail}.
\subsection{User Folders/Bins}%
\label{sub:user_folders_bins}
+\index{user folders/bins}
+\index{user media bin}
+\index{user clip bin}
+\index{folder modify}
+\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
- \vspace{18ex}
-
- \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}
+
+\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}
-To delete the entire set of files listed on the filter rule, highlight the rule line and hit the \textit{Del} button.
+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.
+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}
+\index{vicon!video icons}
+\index{aicon!audio icons}
Vicons are video icons.
Aicons are audio icons.
\label{fig:vicons1}
\end{figure}
-The waveform in the figure~\ref{fig:vicons2} is displayed in the Resources window in the color green for the 3 audio tracks.
-There is a colored bar on the top of each a-icon where the color is based on the Color Spectrum -- the smaller the time duration, the redder the color; then as the time duration goes up, the color goes up so that you will go to green, then yellow, then blue, then really dark blue, then purple for the audio files 1 hour and over.
+The waveform \index{waveform} in the figure~\ref{fig:vicons2} is displayed in the Resources window in the color green for the 3 audio tracks.
+There is a colored bar \index{color bar aicons} on the top of each a-icon where the color is based on the Color Spectrum -- the smaller the time duration, the redder the color; then as the time duration goes up, the color goes up so that you will go to green, then yellow, then blue, then really dark blue, then purple for the audio files 1 hour and over.
There are various other colors between these colors same as that seen in the color spectrum in the screenshot below.
Colors are utilized from the hue wheel in the counter-clockwise direction.
Note that the horizontal line in the middle of the a-icon is yellow/red representing the 2 audio tracks and is only red for mono.
\subsection{Resources Window Preview Mode}%
\label{sub:resources_window_preview_mode}
+\index{resources preview}
Preview mode can be used to pop up a window which draws the vicons/aicons thumbnails in a larger size.
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.
\begin{enumerate}
- \item \emph{Full Play} is the default mode.
+ \item \emph{Full Play} \index{full play} is the default mode.
This means all of the media will automatically play when the mouse is in the Resources window and you can use the left mouse button to click on specific media to see it pop up in a larger view.
Audio only files do not play the audio until the icon is clicked on and the waveform aicon pops up into the 4x larger mode.
\emph{Full Play} includes the \emph{Mouse Over} capabilities as described below as well as the Inter-View \emph{Src Target} functions.
- \item \emph{No Play} mode is especially useful on smaller computers and for users who find the constant loop play to be somewhat distracting.
+ \item \emph{No Play} \index{no play} mode is especially useful on smaller computers and for users who find the constant loop play to be somewhat distracting.
- \item \emph{Mouse Over} mode is activated by a single click on one of the vicons/aicons and deactivated with another single click over any of the icons.
+ \item \emph{Mouse Over} \index{mouse over} mode is activated by a single click on one of the vicons/aicons and deactivated with another single click over any of the icons.
Once activated, whenever you just move the mouse over an icon, it automatically pops up the increased size preview.
The first time in your session that you enable this feature, it may take a few seconds to load all of the icon previews into memory so be patient and just wait.
\emph{Mouse Over} mode makes it quick and easy to preview without having to drag the media to the viewer.
You can still drag the media same as without preview enabled.
- \item \emph{Src Target} mode gives easy access to the Inter-View source target available by using the middle mouse button on media.
+ \item \emph{Src Target} \index{source target} mode gives easy access to the Inter-View source target available by using the middle mouse button on media.
There are 2 advantages to this mode -- there is no 5 second play loop taking up cpu time and the popup allows for the use of the letter “\texttt{f}” on that popup to have it go to fullscreen mode.
\emph{Src Target} mode in any scenario never plays sound as that is nonsensical usage.
After the initial click to pop media in this mode, you also have the \emph{Mouse over} feature.
\subsection{Moving clips/media from/to Resources window}%
\label{sub:moving_clips_media_from_to_resources_window}
+\index{copy/paste from/to resources window}
If you have several media files loaded into the Resources window of one instance of \CGG{} and want to load some of the same ones into another instance or just want a listing to save in a file for later use, you can do this with these set of steps:
\subsection{Snapshot / Grabshot}%
\label{sub:snapshot_grabshot}
+\index{snapshot}
+\index{grabshot}
\begin{figure}[htpb]
\centering
\subsection{Transport Controls}%
\label{sub:transport_controls}
+\index{transport buttons}
Transport controls are useful for navigation and for playing media.
Each of the Viewer, Compositor, and Program windows has its own transport panel.
-The controls generally all contain a yellow colored tooltip when you mouse over the control, providing a hint of their function and shortcuts for usage.
+The controls generally all contain a colored tooltip when you mouse over the control, providing a hint of their function and shortcuts for usage.
The transport panel is controlled by the keyboard as well as the graphical interface.
For each of the operations it performs, the starting position is the position of the insertion point in the Program window and the slider in the Compositor and Viewer windows.
\subsection{Zoombar}%
\label{sub:zoombar}
+\index{zoom}
The compositor has zoom capability.
The pull-down menu on the bottom of the compositor window has a number of zoom options.
\subsection{Show Overlays}%
\label{sub:show_overlays}
+\index{show ovelays window}
Color Coded Keyframe Curves are a big feature in the \textit{Show Overlays} window because by changing the colors to suit the user, it helps to remove confusion from multiple curves on the track canvas.
They can be viewed from the pulldown menu of \texttt{Window $\rightarrow$ Show overlays} but they will operate the same as when used from the \textit{View} pulldown menu.
\subsection{Sound Level Meters Window}%
\label{sub:sound_level_meters_window}
+\index{sound level meters window}
An additional window, the levels window, can be brought up from the \textit{Window} pulldown.
The levels window displays the output audio levels after all mixing is done.
--- /dev/null
+#!/bin/sh
+
+# First build PDF version, 3 times to be completely sure.
+# The various auxiliary files will be needed later.
+
+pdflatex CinelerraGG_Manual.tex
+makeindex CinelerraGG_Manual.idx
+makeindex CinelerraGG_Manual.nlo -s nomencl.ist -o CinelerraGG_Manual.nls
+pdflatex CinelerraGG_Manual.tex
+makeindex CinelerraGG_Manual.idx
+pdflatex CinelerraGG_Manual.tex
+
+# Now build HTML version, using auxiliary files created by pdflatex.
+
+# Clean the future HTML directory
+rm -rf CinelerraGG_Manual
+
+# Ensure creating the important settings file
+if [ ! -f .latex2html-init ]
+then
+ cp latex2html-init .latex2html-init
+fi
+
+# When translating manual for context help, don't use -show_section_numbers !
+# And do use -split +3 -link 3 -nofootnode and -local_icons.
+# -use_dvipng, -image_type and -bottom_navigation can be used
+# according to your preferences.
+
+# translate document (GIF images generated via gs, good for debugging)
+#latex2html -html_version 4.0,math -use_pdftex -nouse_dvipng -image_type gif -nofootnode -show_section_numbers -split +3 -link 3 -bottom_navigation -local_icons -t 'Cinelerra-GG Infinity' CinelerraGG_Manual.tex
+
+# another alternative options combination (PNG images, nicer look)
+#latex2html -html_version 4.0,math -use_pdftex -use_dvipng -image_type png -nofootnode -show_section_numbers -split +3 -link 3 -bottom_navigation -local_icons -t 'Cinelerra-GG Infinity' CinelerraGG_Manual.tex
+
+# Alternative currently used on the cinelerra-gg.org website / created on a Fedora system
+latex2html -html_version 4.0,math -use_pdftex -nouse_dvipng -long_titles 5 -image_type gif -nofootnode -split +3 -link 3 -bottom_navigation -local_icons -t 'CinelerraGG_Manual' CinelerraGG_Manual.tex
+
+# This single image has to be copied explicitly
+cp images/cin-big.png CinelerraGG_Manual
+
+# Clean temporary files in the HTML directory
+rm -f CinelerraGG_Manual/WARNINGS
+rm -f CinelerraGG_Manual/*.pl
+rm -f CinelerraGG_Manual/images*
projects / goodguy / cin-manual-latex.git / commitdiff
