From: Good Guy Date: Wed, 17 Apr 2024 19:09:51 +0000 (-0600) Subject: Credit Andrea with Windows.tex changes based on reading updates in CV manual X-Git-Url: https://git.cinelerra-gg.org/git/?p=goodguy%2Fcin-manual-latex.git;a=commitdiff_plain;h=HEAD;hp=5f7eb23c66c85a2566498a073568bbad95004c31 Credit Andrea with Windows.tex changes based on reading updates in CV manual --- diff --git a/Anamorphic.tex b/Anamorphic.tex new file mode 100644 index 0000000..752b331 --- /dev/null +++ b/Anamorphic.tex @@ -0,0 +1,41 @@ +\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: diff --git a/CinelerraGG_Manual.tex b/CinelerraGG_Manual.tex index 6849500..025c5dd 100644 --- a/CinelerraGG_Manual.tex +++ b/CinelerraGG_Manual.tex @@ -48,6 +48,7 @@ svgnames, \include{parts/Tips} \include{parts/Translations} \include{parts/Licenses} +\include{parts/AUTHORS} \chapter*{Appendices} \addappheadtotoc @@ -56,6 +57,7 @@ svgnames, \include{parts/Developer} \include{parts/AuxilaryPrograms} \include{parts/Real-World} +\include{parts/Faq} \end{appendices} \pagestyle{plain} diff --git a/Preserving.tex b/Preserving.tex new file mode 100644 index 0000000..c093ad4 --- /dev/null +++ b/Preserving.tex @@ -0,0 +1,41 @@ +\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: diff --git a/common/packages.tex b/common/packages.tex index 4b9312f..15f93c1 100644 --- a/common/packages.tex +++ b/common/packages.tex @@ -6,7 +6,7 @@ % 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} % Подключение русифицированных diff --git a/common/settings.tex b/common/settings.tex index 63baf04..4e662d4 100644 --- a/common/settings.tex +++ b/common/settings.tex @@ -11,9 +11,7 @@ % Set up the page layout % memman.pdf capter 2: Laying out the page (READ IT!) % example: memsty.sty -%begin{latexonly} \settypeblocksize{8.75in}{34pc}{*} -%end{latexonly} % In loose reference to the theme CW. \definecolor{CinBlueText}{RGB}{23,85,142}% "Dark blue" @@ -31,7 +29,6 @@ % \definecolor{subsectioncolour}{RGB}{23,85,142} % \definecolor{subsubsectioncolour}{RGB}{23,85,142} -%begin{latexonly} \makechapterstyle{morrow}{% requires graphicx package \chapterstyle{default} \renewcommand*{\chapnamefont}{% @@ -45,7 +42,6 @@ \renewcommand*{\chaptitlefont}{% Overwrites toc \normalfont\Huge\bfseries\sffamily\raggedleft\color{CinBlueText}} } -%end{latexonly} \addtodef{\printpartname}{\color{CinBlueText}}{}% Part \addtodef{\printchaptername}{\color{CinBlueText}}{}% Chapter @@ -129,12 +125,10 @@ \parindent=0.0cm % first indent in section \righthyphenmin=2 % hyphen last charecter -%begin{latexonly} \setsecnumdepth{subsubsection} % section numeration depth % We use the chapter header style: \chapterstyle{morrow} -%end{latexonly} % \renewcommand{\printchaptername}{\normalfont\large\scshape Chapter} \renewcommand{\chapterheadstart}{} @@ -143,7 +137,7 @@ %\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 diff --git a/common/title.tex b/common/title.tex index a4d48e6..ef44c18 100644 --- a/common/title.tex +++ b/common/title.tex @@ -97,8 +97,8 @@ % 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 diff --git a/extra/help_br_de.odt b/extra/help_br_de.odt new file mode 100644 index 0000000..a9aa5e4 Binary files /dev/null and b/extra/help_br_de.odt differ diff --git a/extra/help_br_el.odt b/extra/help_br_el.odt new file mode 100644 index 0000000..73d4fb5 Binary files /dev/null and b/extra/help_br_el.odt differ diff --git a/extra/help_br_en.odt b/extra/help_br_en.odt new file mode 100644 index 0000000..f122294 Binary files /dev/null and b/extra/help_br_en.odt differ diff --git a/extra/help_br_es.odt b/extra/help_br_es.odt new file mode 100644 index 0000000..a292649 Binary files /dev/null and b/extra/help_br_es.odt differ diff --git a/extra/help_br_eu.odt b/extra/help_br_eu.odt new file mode 100644 index 0000000..c0155a9 Binary files /dev/null and b/extra/help_br_eu.odt differ diff --git a/extra/help_br_fr.odt b/extra/help_br_fr.odt new file mode 100644 index 0000000..9032656 Binary files /dev/null and b/extra/help_br_fr.odt differ diff --git a/extra/help_br_hi.odt b/extra/help_br_hi.odt new file mode 100644 index 0000000..d8643a7 Binary files /dev/null and b/extra/help_br_hi.odt differ diff --git a/extra/help_br_it.odt b/extra/help_br_it.odt new file mode 100644 index 0000000..e051c63 Binary files /dev/null and b/extra/help_br_it.odt differ diff --git a/extra/help_br_ja.odt b/extra/help_br_ja.odt new file mode 100644 index 0000000..0f3609f Binary files /dev/null and b/extra/help_br_ja.odt differ diff --git a/extra/help_br_ko.odt b/extra/help_br_ko.odt new file mode 100644 index 0000000..bf3d6aa Binary files /dev/null and b/extra/help_br_ko.odt differ diff --git a/extra/help_br_nb.odt b/extra/help_br_nb.odt new file mode 100644 index 0000000..b0e4013 Binary files /dev/null and b/extra/help_br_nb.odt differ diff --git a/extra/help_br_nl.odt b/extra/help_br_nl.odt new file mode 100644 index 0000000..533584d Binary files /dev/null and b/extra/help_br_nl.odt differ diff --git a/extra/help_br_no.odt b/extra/help_br_no.odt new file mode 100644 index 0000000..432c08f Binary files /dev/null and b/extra/help_br_no.odt differ diff --git a/extra/help_br_pt.odt b/extra/help_br_pt.odt new file mode 100644 index 0000000..38328e4 Binary files /dev/null and b/extra/help_br_pt.odt differ diff --git a/extra/help_br_ru.odt b/extra/help_br_ru.odt new file mode 100644 index 0000000..8acdf2d Binary files /dev/null and b/extra/help_br_ru.odt differ diff --git a/extra/help_br_sl.odt b/extra/help_br_sl.odt new file mode 100644 index 0000000..b1f86c9 Binary files /dev/null and b/extra/help_br_sl.odt differ diff --git a/extra/help_br_uk.odt b/extra/help_br_uk.odt new file mode 100644 index 0000000..0718b53 Binary files /dev/null and b/extra/help_br_uk.odt differ diff --git a/extra/help_br_vi.odt b/extra/help_br_vi.odt new file mode 100644 index 0000000..8dbfb1d Binary files /dev/null and b/extra/help_br_vi.odt differ diff --git a/extra/help_br_zh.odt b/extra/help_br_zh.odt new file mode 100644 index 0000000..794f59e Binary files /dev/null and b/extra/help_br_zh.odt differ diff --git a/images/DAR.png b/images/DAR.png new file mode 100644 index 0000000..fb2ba7e Binary files /dev/null and b/images/DAR.png differ diff --git a/images/Frame_on_PiP.png b/images/Frame_on_PiP.png new file mode 100644 index 0000000..536d4f3 Binary files /dev/null and b/images/Frame_on_PiP.png differ diff --git a/images/Preserving.png b/images/Preserving.png new file mode 100644 index 0000000..f72b0ca Binary files /dev/null and b/images/Preserving.png differ diff --git a/images/android.png b/images/android.png new file mode 100644 index 0000000..6c65c81 Binary files /dev/null and b/images/android.png differ diff --git a/images/bluray01.png b/images/bluray01.png index 7e0e717..0de0ed4 100644 Binary files a/images/bluray01.png and b/images/bluray01.png differ diff --git a/images/color_01.png b/images/color_01.png new file mode 100644 index 0000000..ba9140b Binary files /dev/null and b/images/color_01.png differ diff --git a/images/gamma01.png b/images/gamma01.png index 6eb695f..8e674e4 100644 Binary files a/images/gamma01.png and b/images/gamma01.png differ diff --git a/images/gamma02.png b/images/gamma02.png index adac1d9..a155a94 100644 Binary files a/images/gamma02.png and b/images/gamma02.png differ diff --git a/images/graphic-art2.png b/images/graphic-art2.png new file mode 100644 index 0000000..49820a4 Binary files /dev/null and b/images/graphic-art2.png differ diff --git a/images/histogram.png b/images/histogram.png index 2a29f71..58810b9 100644 Binary files a/images/histogram.png and b/images/histogram.png differ diff --git a/images/info_asset_details.png b/images/info_asset_details.png index d316b9c..be9c84a 100644 Binary files a/images/info_asset_details.png and b/images/info_asset_details.png differ diff --git a/images/logical2.png b/images/logical2.png new file mode 100644 index 0000000..bddea30 Binary files /dev/null and b/images/logical2.png differ diff --git a/images/magnifier.png b/images/magnifier.png index 489b614..74d9e1a 100644 Binary files a/images/magnifier.png and b/images/magnifier.png differ diff --git a/images/mirror.png b/images/mirror.png new file mode 100644 index 0000000..9d37768 Binary files /dev/null and b/images/mirror.png differ diff --git a/images/normal.png b/images/normal.png index 8b21dcb..36d1f3d 100644 Binary files a/images/normal.png and b/images/normal.png differ diff --git a/images/normal2.png b/images/normal2.png new file mode 100644 index 0000000..e0b6967 Binary files /dev/null and b/images/normal2.png differ diff --git a/images/porter-duff2.png b/images/porter-duff2.png new file mode 100644 index 0000000..d1c4e0f Binary files /dev/null and b/images/porter-duff2.png differ diff --git a/images/porter-duff3.png b/images/porter-duff3.png new file mode 100644 index 0000000..359c37a Binary files /dev/null and b/images/porter-duff3.png differ diff --git a/images/proxy-02.png b/images/proxy-02.png index da00bd1..e3e4aae 100644 Binary files a/images/proxy-02.png and b/images/proxy-02.png differ diff --git a/images/pulldown_button.png b/images/pulldown_button.png index 7856a45..b1d4987 100644 Binary files a/images/pulldown_button.png and b/images/pulldown_button.png differ diff --git a/images/rgbshift.png b/images/rgbshift.png index 122c4f2..5f2f58c 100644 Binary files a/images/rgbshift.png and b/images/rgbshift.png differ diff --git a/images/set-format.png b/images/set-format.png index ce43ff6..696125e 100644 Binary files a/images/set-format.png and b/images/set-format.png differ diff --git a/images/settings.png b/images/settings.png index 85135b2..2de23b3 100644 Binary files a/images/settings.png and b/images/settings.png differ diff --git a/images/some_editing.png b/images/some_editing.png index 1902e0a..62bdd4f 100644 Binary files a/images/some_editing.png and b/images/some_editing.png differ diff --git a/images/sum.png b/images/sum.png new file mode 100644 index 0000000..ecb4b9e Binary files /dev/null and b/images/sum.png differ diff --git a/images/title_color.png b/images/title_color.png index f14f68f..e1fda56 100644 Binary files a/images/title_color.png and b/images/title_color.png differ diff --git a/images/trim.png b/images/trim.png index 2d3ec28..7778d8b 100644 Binary files a/images/trim.png and b/images/trim.png differ diff --git a/images/yuvshift.png b/images/yuvshift.png index 3c5c022..81ae410 100644 Binary files a/images/yuvshift.png and b/images/yuvshift.png differ diff --git a/latex2html-init b/latex2html-init index 6300ef9..4646aaa 100644 --- a/latex2html-init +++ b/latex2html-init @@ -76,10 +76,18 @@ $WORDS_IN_PAGE = 300; $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) +# 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" @@ -213,7 +221,6 @@ sub bot_navigation_panel { &ignore_commands( <<_IGNORED_CMDS_); captionsetup # {} -settocdepth # {} fboxsep # &ignore_numeric_argument drop # &ignore_numeric_argument AddToShipoutPicture # {} diff --git a/parts/AUTHORS.tex b/parts/AUTHORS.tex new file mode 100644 index 0000000..cc76918 --- /dev/null +++ b/parts/AUTHORS.tex @@ -0,0 +1,99 @@ +\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 . + +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} diff --git a/parts/Advanced.tex b/parts/Advanced.tex index 87eecea..1fcb545 100644 --- a/parts/Advanced.tex +++ b/parts/Advanced.tex @@ -5,39 +5,104 @@ \label{sec:proxy} \index{proxy} -Proxies was introduced to allow for a smoother timeline experience. Full HD and everything from 4K size up are usually very large in file size. In addition, some commonly used codecs (e.g. h264/5) are very compressed and interframe type, so they are more stressful for timeline playback. These files cause performance problems on weaker PCs. As a solution the developers have introduced proxies to reduce the file size. Reduced means to minimize the resolution/dimension, as usually not the full resolution is needed, because the compositor usually takes only a fraction of the computer screen. Therefore the scaling factor, which indicates how much the original resolution should be reduced. -There is also the \textit{proxy 1:1} \index{proxy!1:1} that maintains the original resolution but still allows you to act on the codec (lowering the bit rate, for example). See also next section: \ref{sec:transcode}. -When rendering, the original setting will be used to avoid loss of image quality. +Proxies were introduced to allow for a smoother timeline experience. Full HD and everything from 4K size up are usually very large in file size. In addition, some commonly used codecs (for example h264/5) are very compressed and interframe type, so they are more CPU intensive for timeline playback. These files cause performance problems on smaller computers. As a solution, proxies were introduced to reduce the file size. Reduced means to minimize the resolution/dimension, as usually not the full resolution is needed because the compositor generally occupies only a fraction of the computer screen. The proxy provides a scaling factor which indicates how much the original resolution should be reduced. +There is also the \textit{proxy 1:1} \index{proxy!1:1} option that maintains the original resolution but still allows you to modify codec parameters (lowering the bit rate, for example). This is explained in the next section, \ref{sec:transcode}. +Always remember when getting ready to render the project, disable Proxy to return to the original settings with the highest quality. -To use the proxy in a classic way, i.e. as a scaling, select \texttt{Settings $\rightarrow$ Proxy settings} and change the Scale factor from Original size to your downsized choice. You can choose ffmpeg as the File Format \index{file format} and a choice of various codecs associated with that. A good choice is the default of mpeg which can usually be quite fast. In addition, to modify values for that codec, click on the wrench icon. +To use proxy select \texttt{Settings $\rightarrow$ Proxy settings} on the main window. You can choose ffmpeg as the \textit{File Format} \index{file format} and for the \textit{File Type} a choice of various codecs associated with that. A good choice for \textit{File Type} is the default of mpeg or mov which can usually be quite fast. In addition you can modify values for that codec by clicking on the wrench icon. Once you have created a +proxy file, it will be reused and does not have to be created again as long as you +do not change certain parameters. This saves a lot of CPU time. -We can use the \textit{Proxy 1:1} in two ways: setting "1" as \textit{Scale factor}, or check the \textit{Rescaled to project size (FFMPEG only)} button. In this mode we don't have scaling, i.e. downsize, but only variations of the codec parameters that allow to maintain the original resolution. The advantage is that you can use filters that require the original size to work well. NB: if we set any scaling, by activating the \textit{Rescaled to project size (FFMPEG only)} button we automatically lose scaling and enter Proxy 1:1 mode. +There are two main ways to use Proxy, with or without \textit{Rescaled to project size} option checked. The options of the \textit{Scale factor} may be different if \textit{Rescaled to project size} is checked versus unchecked. It is a special case when the \textit{Scale facto}r is set to "1" and it does not matter if \textit{Rescaled to project size} is checked or unchecked. -When you have completed your choices, just click OK, and then the video tracks will be rendered. This may take some time, but previous proxy renders will be reused. +The usual steps to use Proxy are: +\begin{enumerate} + \item Check that \textit{File Format} is set to \texttt{FFMPEG}. + \item Check or uncheck the \textit{Rescaled to project size} (FFMPEG only). The difference with this option will be explained here \ref{sub:rescaled_project_size_works}. But for old computers checking \textit{Rescaled to project size} is not recommended; again due to requiring more CPU. You need to know that when \textit{Rescaled to project size} is unchecked some Effects/Plugins do not work as expected because they use pixel values instead of percentage values as is used in the Project Format. For example \textit{Title}, \textit{Blur}, \textit{Sketcher} plugins do not work right if unchecked, while \textit{Perspective} and \textit{Crop\&Position} plugins work correctly for both checked and unchecked. + \item Choose the \textit{Scale factor}. The options may be different if \textit{Rescaled to project size} is checked or unchecked. The smaller the \textit{Scale factor} is, the smoother playing on the Timeline will be ($\frac{1}{8}$ is smaller than $\frac{1}{4}$), but on the Viewer/Compositor the image will be degraded/pixelated more. + \item Set the \textit{File Type} in the \textit{File Format} for FFMPEG, such as mp4, mpeg, or mov. Still images like jpg, tiff, and png will be converted to PNG files with alpha channel if it had an alpha channel. + \item Click on the wrench icon to configure video compression; just use the default values if you are unsure and prefer not to experiment. + \begin{enumerate} + \item Select the Compressor type (codec). + \item Change Bitrate, or Quality, and Pixels. Because not all codecs use the alpha channel for transparency, check that the letter "\textbf{a}" is in the Pixels name (such as yuv\textbf{a}420p or rgb\textbf{a}) to retain the alpha channel. + \item Click on the OK button to close the Compressor window. + \end{enumerate} + \item Now click on the \texttt{OK} button to start the rendering for the proxy. + \item Look in the lower right corner of the main window where there is a progress bar and a percentage value showing the progress of the creation of proxies, and in the lower left corner there is the \textit{Creating proxy files... ETA: hh:mm:ss} text with the "Estimated Time of Arrival (completion)" in hours, minutes, seconds. Depending on how many files your project uses, the file size, which codec is used, the scale factor, and cpu performance, creating proxies may take some time. +\end{enumerate} + +You will know that Proxy mode is enabled because: +\begin{itemize} + \item A white colored \textbf{P} meaning \textit{\textbf{P}roxy}, or a white colored \textbf{S} meaning \textit{Proxy \textbf{S}caled} icon is shown in the upper right corner of the main window to the left of the FF icon. If using the Cakewalk or Neophyte theme it will be a \textbf{Ps} icon. + \item The Proxy folder in the Resources window has been populated with the names and/or icons of the proxy media. + \item The edit title bar in the timeline will have the name of the proxy file instead of the original name. So if the video filename is \texttt{VID\_20221012.mp4}, the Proxy Scale Factor is $\frac{1}{4}$, and the Proxy container is mov, then the proxy name will be \texttt{VID\_20221012.proxy4-mp4.mov}. +\end{itemize} + +The Proxy icon is a toggle button so that you just click on the icon to change modes. Or it can be toggled using the \texttt{Ctrl+R} shortcut. + +\begin{table}[ht] + \centering + \begin{tabular}{|p{2.5cm}|p{3.2cm}|p{3.2cm}|p{3.2cm}|} + \hline + {\footnotesize\textbf{Proxy State}} & {\footnotesize\textbf{Rescaled to project size (FFMPEG only)}} & {\footnotesize\textbf{Proxy icon for themes: + Cakewalk/ Neophyte}} & {\footnotesize\textbf{Proxy icon for themes: the Others}}\\ + \hline + {\footnotesize{Off}} & {\footnotesize{checked/ unchecked}} & {\footnotesize{no icon}} + & {\footnotesize{no icon}}\\ + \hline + {\footnotesize{Active (Enable)}} & {\footnotesize{checked}} & {\footnotesize{Ps: P(green) s(white)}} + & {\footnotesize{S (white)}}\\ + \hline + {\footnotesize{Disable}} & {\footnotesize{checked}} & {\footnotesize{Ps: P(red) s(white)}} & {\footnotesize{S (gray)}}\\ + \hline + {\footnotesize{Active (Enable)}} & {\footnotesize{unchecked}} & {\footnotesize{Ps: P(green) s(red)}} & {\footnotesize{P (white)}}\\ + \hline + {\footnotesize{Disable}} & {\footnotesize{unchecked}} & {\footnotesize{Ps: P(red) s(red)}} & {\footnotesize{P (gray)}}\\ + \hline + \end{tabular} + \caption{list States of the Proxy icon} +\end{table} + +When you disable Proxy using the toggle button for Proxy, or its shortcut (\texttt{Ctrl+R}), in the Proxy Settings window you will see the \textit{Scale Factor = 1}, but if you look at the Active Scale and the State, you can understand what your setting is. +Proxy can have three possible States: Off, Active, Disabled. The difference between Off and Disabled is that Disabled means you have set the Proxy and it is temporarily switched off (and you can see the icon in the upper right corner of the main window); you can enable proxy by just clicking on the icon, so the State will then be changed from Disabled to Active. + +\subsection{How Rescaled to project size (FFMPEG only) works}% +\label{sub:rescaled_project_size_works} + +\begin{itemize} + \item When \textit{Rescaled to project size (FFMPEG only)} is checked, the size of the video data to be computed will always be the same as the Project Format. The size of your video is scaled down to the \textit{Scale factor} BUT then it is rescaled up to the Project Format. For example, your Project Format is 1920x1080 and Proxy's Scale factor is $\frac{1}{4}$, then your videos ($1920x1080$) will be scaled down to 480x270 and then up-scaled to $1920x1080$. All the Effects/Plugins work correctly because the original resolution/geometry/size is not changed. For an old computer, this option is not recommended. + \item When \textit{Rescaled to project size (FFMPEG only)} is UNchecked, the size of the video data to be computed will be reduced to the \textit{Scale factor}. The size of your video is scaled down to the \textit{Scale factor}. For example, your Project Format is 1920x1080 and Proxy's Scale factor is $\frac{1}{4}$, then your videos ($1920x1080$) will be scaled down to $480x270$. It works as if the Project Format were $480x270$ (and really it works). If you take a look at \texttt{Settings $\rightarrow$ Format...} when Proxy is enabled (Active), you can see that the Width and Height are changed according to the \textit{Scale factor}; you absolutely must NOT change these values! The good thing is that your computer will be faster. The bad thing is that some Effects/Plugins do not work as expected because they use pixel units. Examples are \textit{Title} and \textit{Blur} plugins. A workaround is needed for that, such as using Inkscape to create a title and export it to PNG that you load instead of using the \textit{Title} plugin. + +\end{itemize} + +Note: the dimensions of the frame/image are downscaled to the Scale factor; so if the Scale factor is $\frac{1}{4}$ and the dimension of the image is $4288x2848$ pixels, that image will be downscaled to $1072x712$. It doesn't matter what the Project Format is. + +\subsection{Using proxy}% +\label{sub:using_proxy} + +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. -The proxy videos will be added to your assets in a separate Proxy folder \index{proxy!folder}, and the video track edits will use the proxies. -The assets in both the Media folder and Proxy folder will look proxied when dragged to the Viewer although the scale may be different. -Proxy downsizing renders all loaded tracks, but only work on the $1^{st}$ video layer of any multi-layer media. Rendered proxy media is saved in the same directory as the original media. -However, if you proxy your session, the clips do not get proxied to the Proxy folder, but if you Drag and Drop the clip from the Clip folder to the Viewer or the Timeline, you will see that it too is proxied. -As usual, you can delete proxy files from the project or disk in the Resources window if you no longer want to retain them. -And you can save your project either as proxied or not. +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. -Because Proxy works on the original media in all circumstances, when you resize the -media in the Resources window, it does not actually resize the media but puts it in -a \textit{buffer} in that format. This might lead to some confusion for the user who -expects this resizing to be maintained when disabling Proxy for that media. However, -that does not happen because the resize is only in a buffer and not in the original -media. This result is different than in the case of media \textit{edits}, like cuts or adding plugins because this information is not in a buffer but rather part of the -copy \textit{Editing Decision List} (EDL). +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. -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}. +\subsection{Scale factor set to 1, a special case}% +\label{sub:scale_factor_special_case} -Let's examine in detail how Proxy and Proxy 1:1 modes work: when the proxy is done with downsize, the Mask, Camera and Projector automations are scaled accordingly. In this situation, the entire project will be re-sized so that the session is in the resized geometry. Not all plugins are useful when the project is scaled, because the keyframe data must be in the original geometry. In this case, you can use the il Proxy 1:1, by enabling \textit{Scale factor}=1. This has the added advantage that the project size does not change. The main reason for using \textit{Proxy 1:1} is that it does not change the image coordinate data, so that automation and plugin parameters will be in the original project geometry (e.g. Title plugin). +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 “Ps” as the icon for Proxy. \quad \includegraphics[height=\baselineskip]{proxy-01.png} \quad This quick switch is especially useful when editing and you need to see a better image temporarily. -The "P" is green when the proxy is active and red when it is disabled. The "s" is white when in \textit{Proxy 1:1} mode and red when downsize. +\subsection{Setting the proxy}% +\label{sub:setting_proxy} \begin{figure}[htpb] \centering @@ -46,13 +111,12 @@ The "P" is green when the proxy is active and red when it is disabled. The "s" i \label{fig:proxy-02} \end{figure} -Screencast in figure~\ref{fig:proxy-02} shows the use scaled checked so you can still use plugins and the original project size is kept. The Scale factor pull-down gives you available size options. Note the new media dimensions shown (partially covered). If the size is an odd number, 1 is added to make the dimensions both even numbers. +Screencast in figure~\ref{fig:proxy-02} shows the \textit{Rescaled to project size} checked so you can still use plugins correctly and the original project size is kept. The \textit{Scale factor} pull-down gives you available size options. Note the new media dimensions shown (partially covered). If the size is an odd number, 1 is added to make the dimensions both even numbers. -To go back to the original media for good, simply take the Scale factor to Off. However, if we decide to reuse the proxies, these, which have not been deleted from the Hard Disk but only from the project, will still be used without making new rendering. To completely cancel the created proxies we will have to delete them manually from the Hard Disk. +To go back to the original media permanently, simply set the \textit{Scale factor} to Off or disable the Proxy by clicking on its toggle button. However, if you decide to reuse the proxies, those which have not been deleted from the Hard Disk (but have been removed from the project) will be used without re-rendering - this saves a lot of time. To completely remove the created proxies you will have to delete them manually from the Hard Disk. +There is also a convenient \textit{Beep on done volume} slider included so that you can work on other tasks until there is an audible notify of completion. The default volume is set to 0 for no audible notify. -There is also a convenient \textit{Beep on done volume} bar included so that you can work on other tasks until there is an audible notify of completion. The default volume is set to 0 for no audible notify. - -A good choice for classic proxy settings with 1080p source video is: +A good choice for classic proxy settings with a 1080p source video is: \begin{lstlisting}[numbers=none] Scale Factor: 1/4 @@ -64,7 +128,7 @@ Quality: -1 Pixels: yuv420p \end{lstlisting} -If you get errors for some videos, such as those with strange variable bit rate or some types of files made on a smartphone, an usually reliable alternative is to change the following parameters: +If you get errors for some videos, such as those with strange variable bit rate or some types of files made on a smartphone, a usually reliable alternative is to change the following parameters: \begin{lstlisting}[numbers=none] File Format: FFMPEG - mov @@ -72,13 +136,98 @@ Video Preset: Compression: mov.mov \end{lstlisting} -Or if you want small files with high image quality, a File Format of \texttt{m2ts} is optimal. For example a 1 GB file can be reduced to 50 MB with scale $\frac{1}{2}$. +Or if you want small files with high image quality, a \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. + +\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} -Checking the \textit{Creation of proxy on media loading} results in any additional media loads to be automatically proxy scaled. However, single frame media such as PNG or JPEG \textit{stills}, can not be scaled to \textit{stream} media. If this type of media exists, you should \textit{Proxy 1:1}. +\subsection{Proxies with Alpha channel}% +\label{sub:proxies_alpha_channel} -If you get error messages \index{proxy!error} when creating proxies, check the Video wrench settings. These usually default to values that are expected to work correctly for the \textit{File Format} and codec you selected but they can be changed and may result in errors. If you get an error message of \textit{check\_frame\_rate failed} followed by \textit{Error making proxy} in the popup Errors window, do just that and check the Frame rate value by going to the Resources window, Media folder, and use the right mouse button for the Info option for that specific media in question. You can change the frame rate in this window to a more codec acceptable value. Different codecs may have different legal values. +Next are some examples of tested and working configurations that maintain the alpha channel: -More specific information on which plugins need to use \textit{Proxy 1:1}. is provided here next. If the keyframe data uses coordinate data that is absolute, then the Factor scale = 1 should be used. If the data is normalized (like always $0-100\%$) then the proxy can be done with downsize (i.e. classic \textit{Proxy}). The session geometry format, shown in \texttt{Settings $\rightarrow$ Format} as $width \times height$, is changed if scale factor $\neq$ 1 is used to cause all of the data to be in the reduced format. If this affects the plugin operation, then \textit{Proxy 1:1} should be used. Examples of plugins that need the \textit{Proxy 1:1} are: Title, AutoScale, Scale, ScaleRatio, and Translate. Most others are safe to use with downsize. +\begin{lstlisting}[numbers=none] +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} @@ -89,17 +238,22 @@ The process of transcoding works directly from the resource; it is independent o All of the loaded asset media will be converted, that is, rendered in the selected format and loaded onto the timeline. Menu choices besides the usual File Format \index{file format} and File Type include: \textit{Tag suffix} (to add to media filename), \textit{Remove originals from project}, \textit{Into Nested Proxy directory} (an option to have the file saved here instead of the location of the original media), and \textit{Beep on done} volume. -The settings of the project have an effect, for example the dimensions are taken into account. The resulting files are also larger than if they were created directly with ffmpeg. +The settings of the project have an effect on the outcome, for example the dimensions are taken into account. The resulting files are also larger than if they were created directly with ffmpeg. Transcode works for videos with or without audio and even single frame files, like png's. If you have a video file that also contains audio, and you convert only the video, the original audio will stay on the timeline if do not check \textit{Remove originals from project}. Or vice versa if audio converted and not video. Multiple stream media will only transcode the first stream (this would be like the TV channel recordings in the United States). You will get an error message if you already have a transcoded file in the selected format with the same suffix name and try to transcode it again with a different selection made -- you will have to delete that file first. An example would be an already converted file that has both video and audio and now you request video only. -The BIGGEST gain from using this is if you have media that is not \textit{seekable} \index{seek}, that is, you can play it from the beginning but can not move to another spot and have the audio or video play correctly. A video file with no keyframes makes seeking next to impossible, but then a Transcode generally adds these keyframes. This is particularly useful for the \texttt{mkv} container, which often has seek problems. +The BIGGEST gain from using this is if you have media that is not \textit{seekable} \index{seek}, that is, you can play it from the beginning but can not move to another spot and have the audio or video play correctly. A video file with no keyframes makes seeking next to impossible, but then a Transcode generally adds these keyframes. This is particularly useful for the \texttt{mkv} container, which often has seek problems. For more details on mkv container see \ref{ssub:note_mkv_container} Another important function of Transcode is being able to convert the project's media into a high-quality \textit{mezzanine} codec \index{mezzanine codec} (sometimes also called \textit{intermediate} codec \index{digital intermediate}), which makes timeline work lighter and more efficient. In fact such codecs (ffv1, ProRes, DNxHD, OpenEXR, huffyuv, etc) are generally little or not at all compressed; the type of compression is intraframe --more suitable for editing, and the image quality (4:2:2 up; 10-bit color up; floating point; etc) is suitable for \textit{Color Correction}, \textit{Chroma Key} and \textit{Rotoscoping}. The use of mezzanine codecs leads to very large files, so you need to make sure you have enough storage space. +\paragraph{NOTE:} \CGG{} cannot do \textit{remuxing} without transcoding. For remuxing only, use \textit{ffmpeg} as shown in the following script. First move to the folder containing the files to be remuxed; the script takes all video files of a certain extension (in the following example \texttt{avi}) from the folder and its subfolders and makes a remux in a new container (in this example \texttt{mkv}) inside the new folder \texttt{remux}. The internal codec will remain the original one. Here is an example script: + +\begin{lstlisting}[numbers=none] + for f in $(find . -name '*.avi'); do ffmpeg -i "$f" -c:v copy -c:a copy "remux/{f%.*}.mkv "; done +\end{lstlisting} \section{OpenEDL}% \label{sec:openedl} @@ -114,7 +268,8 @@ plugins added to it before it was nested, you can edit those plugin parameter values. Previously to make any changes to these types of EDL you had to remake the whole clip from scratch. The program is actually "opening" the file as it currently exists for that particular -media so that it can be edited separately from the project EDL. In other NLEs the term \textit{sub-timeline} is used. +media so that it can be edited separately from the project EDL. In other NLEs the term \textit{sub-timeline} or \textit{sub-project} is used. +It is important to know that all media used with Open EDL must be loaded on the timeline Main Program window and created from there in that project. Here is how this works. In the Clip \index{clip !older} or Media folder \index{media folder} or on a timeline EDL edit, the option \textit{Open EDL} for the highlighted clip or @@ -153,6 +308,8 @@ An example of a typical set of steps to follow is: 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 @@ -196,7 +353,7 @@ shown. In summary: 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} @@ -244,7 +401,7 @@ See a real-world workflow at appendix \nameref{sec:workflow_openedl_nested_clips 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 @@ -349,8 +506,8 @@ on the timeline. \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} @@ -391,6 +548,8 @@ follows. 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. @@ -404,46 +563,42 @@ rest == p+=c: for rest of clips \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 @@ -493,8 +648,7 @@ beginning or the end. 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} @@ -663,7 +817,7 @@ capability of nesting. \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. @@ -712,7 +866,7 @@ Figure~\ref{fig:multicam01} shows 9 media sources in the left corner, the compos \subsubsection*{But, I want to use only the first set of audio tracks\dots}% \label{ssub:but_use_only_first_audio} -There are many cases where you may want to compose using media from several different tracks while using the the same audio tracks as associated from a specific viewer. Since mixer source tracks can be updated any time by using a mixer toggle \index{mixers!toggle}, this makes it possible to do this. +There are many cases where you may want to compose using media from several different tracks while using the the same audio tracks as associated from a specific viewer. Since mixer source tracks can be updated any time by using a mixer toggle\index{mixers!toggle}, this makes it possible to do this. Procedure to update the mixer audio source track list: @@ -1061,7 +1215,7 @@ Operation of Align Timecodes includes the following options to help in your setu 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} diff --git a/parts/Anamorphic.tex b/parts/Anamorphic.tex new file mode 100644 index 0000000..2369b0c --- /dev/null +++ b/parts/Anamorphic.tex @@ -0,0 +1,132 @@ +\chapter{Overview}% +\label{cha:anamorphic} + +\section{\textbf{HDV, anamorphic and non-square pixels}}% +\label{sec:hdv} + +A guide on how to handle anamorphic formats in \CGG{}. +For a detailed discussion see: {\small \url{https://lurkertech.com/lg/pixelaspect/}} + +\subsection{\textbf{Theory}}% +\label{sub:theory} + +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}}): + +\begin{figure}[htpb] + \centering + \includegraphics[width=0.85\linewidth]{DAR.png} + \caption{DAR and SAR compared} + \label{fig:DAR} +\end{figure} + +Unfortunately, there are two opposing schools of thought in describing various aspect ratios: + +\begin{enumerate} + \item PAR = Pixel (\textit{pixel}) aspect ratio and SAR = Storage (\textit{frame}) aspect ratio. + \item PAR = Picture (\textit{frame}) aspect ratio and SAR = Sample (\textit{pixel}) aspect ratio. +\end{enumerate} + +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. + +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: + +\qquad $DAR = SAR \times PAR(=W/H)$ + +with: + +\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. + +\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. + +\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. + +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. +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}}. + +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): + +\begin{center} +\renewcommand\arraystretch{1.3} +\begin{tabular}{|c||c|c||c|c||c|} + \hline + \multirow{2}{*}{\textbf{DV; HDV}} & \textbf{Display} & \textbf{DAR} & \textbf{Picture} & \textbf{PAR} & \textbf{SAR =} \\ + & \textbf{(Output)} & \textbf{(W/H)} & \textbf{(Input)} & \textbf{(W/H)} & \textbf{DAR $\times$ W/H} \\ + \hline + 16:9-2160 & 3840 x 2160 & 16:9 & 3840 x 2160 & 16:9 & 1:1 \\ + 4:3-2160 & 2880 x 2160 & 4:3 & 2880 x 2160 & 4:3 & 1:1 \\ + 16:9-1080 & 1920 x 1080 & 16:9 & 1920 x 1080 & 16:9 & 1:1 \\ + 16:9-1080 & 1920 X 1080 & 16:9 & 1440 x 1080 & 4:3 & 1:1 \\ + 16:9-720 & 1280 x 720 & 16:9 & 1280 x 720 & 16:9 & 1:1 \\ + 16:9-1080 & 1920 X 1080 & 16:9 & 1440 x 1080 & 4:3 & 4:3 \\ + 16:9-576 & 1024 x 576 & 16:9 & 720 x 576 & 5:4& 64:45 \\ + 4:3-576 & 768 x 576 & 4:3 & 720 x 576 & 5:4& 16:15 \\ + 16:9-480 & 853 x 480 & 16:9 & 720 x 480 & 3:2& 32:27 \\ + 4:3-480 & 640 x 480 & 4:3 & 720 x 480 & 3:2 & 8:9 \\ +\hline +\end{tabular} +\end{center} + +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. + +\subsection{\textbf{How \CGG{} works}}% +\label{sub:how_cgg_works} + +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. + +So: + +\begin{itemize} + \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). + \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. + \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: + + WxH\textit{source} = WxH\textit{project} $\rightarrowtail$ Correct display. + + WxH\textit{source} < WxH\textit{project} $\rightarrowtail$ pad (letterbox, pillarbox). + + WxH\textit{source} > WxH\textit{project} $\rightarrowtail$ crop. + + 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. +\end{itemize} + +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. + +To see some useful examples, see Raffaella Traniello: {\small \url{http://www.g-raffa.eu/Cinelerra/HOWTO/anamorphic.html}} + +\subsection{\textbf{Use Case}}% +\label{sub:use_case} + +For a video tutorial, see \href{https://youtu.be/JyIkdX3q_Ho}{HDV, anamorphic and non-square pixels}. + +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). + +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: + +$DAR (16:9) = 1440/1080 \times SAR (4:3) = 1.3333 \times 1.3333 = 1.777$ + +\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}. + +\paragraph{Step 2:} We change the project from the initial one (of the source) to the preset \textit{PAL 576i (16:9) -DV(D)}. + +Now we have: + +720$\times$576; W Ratio=0.5000; H Ratio=0.5333; DAR 16:9 + +from which: + +SAR = DAR / (720/576) = 1.7778 / 1.25 = 1.4222 = 64:45 + +Note that the video is cropped if we did not downscale in \textit{step1}. + +\paragraph{Step3:} Render with \textit{dv\_pal.avi} or \textit{dv\_pal.qt} preset. Now we have: + +720$\times$576; SAR = 64:45 (=1.4222); DAR = 16:9 + +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: + +SAR=(576$\times$16/9)/720=64/45=1.4222 \\ +PAR = W/H = 720/576 = 1.25 \\ +DAR = 16:9 (unchanged) \\ + +\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). + diff --git a/parts/Anamorphic_title.tex b/parts/Anamorphic_title.tex new file mode 100644 index 0000000..2f439b1 --- /dev/null +++ b/parts/Anamorphic_title.tex @@ -0,0 +1,55 @@ +% ================================================================ +% 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: diff --git a/parts/Attributes.tex b/parts/Attributes.tex index 56a24d6..0c1c703 100644 --- a/parts/Attributes.tex +++ b/parts/Attributes.tex @@ -29,9 +29,9 @@ from this point 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 (SAR). +refers to the display aspect ratio (DAR). Edit decision lists , the EDL \index{EDL} stored in XML, save the project settings. Formats which contain media but no edit decisions just @@ -121,21 +121,20 @@ 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:] \index{canvas size} sets the size of the video output \index{output size}. In addition, -each track also has its own frame size. Initially, the New Project -dialog creates video tracks whose size match the video output. The -video track sizes can be changed later without changing the video -output. - -\item[Aspect ratio:] \index{aspect ratio} sets the aspect ratio; this aspect ratio refers -to the screen aspect ratio. The aspect ratio is applied to the -video output. The aspect ratio can be different than the ratio that -results from the formula: $\dfrac{h}{v}$ (the number of horizontal -pixels divided into the number of vertical pixels). If the aspect -ratio differs from the results of the formula above, your output -will be in non-square pixels. - -\item[Auto aspect ratio:] if this option is checked, the Set Format +\item[Canvas size:] \index{canvas size} sets the size of the video output \index{output size}. In addition, +each track also has its own frame size. Initially, the New Project dialog creates video tracks whose size matches the video output. The video track sizes can be changed later without changing the video output. We have: Project size = $Width \times Height$, pixels = canvas size = output size . + +\item[W/H Ratio] Sets the ratio of the new canvas size (Width, Height) from the old (previous) canvas size (Width, Height). + +\qquad W Ratio = $\frac{W_f}{W_i}$ \qquad H Ratio = $\frac{H_f}{H_i}$ + +with $W_f$/$H_f$: final Width and Height; $W_i$/$H_i$: initial Width and Height. + +The new canvas size is recalculated based upon a certain factor in the \texttt{W Ratio}, \texttt{H Ratio} fields. A practical use-case: the current resolution is $640 \times 480$, and for some reason you want Width to be 1.33 times bigger. You don't have to calculate what $640 \times1.33$ is; you type 1.33 into the \texttt{Width} input instead, and \CGG{} calculates it for you. W/H Ratio works as a local calculator. Warning: if you vary W/H Ratio without adjusting Display aspect ratio, we may get non-square pixels resulting in anamorphic frame distortion. + +\item[Display aspect ratio:] \index{aspect ratio} sets the aspect ratio; this aspect ratio refers to the display aspect ratio (DAR). The aspect ratio is applied to the video output (canvas). It can be convenient to vary the size of the canvas in percentage terms, instead of having to calculate the number of Width x Height pixels. The aspect ratio can be different than the ratio that results from the formula: $\dfrac{h}{v}$ (the number of horizontal pixels divided into the number of vertical pixels). If the aspect ratio differs from the results of the formula above, your output will be in non-square pixels. + +\item[Auto aspect ratio:] if this option is checked, the \texttt{Set Format} dialog always recalculates the Aspect ratio setting based upon the given Canvas size. This ensures pixels are always square. @@ -167,7 +166,7 @@ processing with no transparency. 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 @@ -198,7 +197,7 @@ range. 16 bit integers were used in the past and were too lossy and 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:] \index{interlacing} this is mostly obsolete in the modern digital age, but may be needed for older media such as that from broadcast @@ -208,6 +207,54 @@ even-numbered lines. Interlaced fields are stored in alternating 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 diff --git a/parts/AuxilaryPrograms.tex b/parts/AuxilaryPrograms.tex index bf0a545..a090c7c 100644 --- a/parts/AuxilaryPrograms.tex +++ b/parts/AuxilaryPrograms.tex @@ -60,18 +60,21 @@ Now render yourfile using different quality levels and run ydiff to compare the \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:" @@ -80,20 +83,23 @@ echo "# Height:" 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} + +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} @@ -109,13 +115,34 @@ The following extensions of files in \CGG{}'s \texttt{.bcast5} directory are exp \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" diff --git a/parts/Configuration.tex b/parts/Configuration.tex index 3c746e3..6a51db5 100644 --- a/parts/Configuration.tex +++ b/parts/Configuration.tex @@ -11,10 +11,19 @@ \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} @@ -29,7 +38,7 @@ The \texttt{Settings $\rightarrow$ Preferences} menu has \textit{Playback A and \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} @@ -87,7 +96,7 @@ The video drivers are used for video playback in the compositor and the viewer. \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] \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. @@ -164,14 +173,15 @@ The parameters here expedite the \texttt{File $\rightarrow$ Record}\dots functio \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] \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 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{entry}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[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}% @@ -236,7 +246,7 @@ Screencast below shows part of the Preferences menu where you can change the ind \end{figure} \begin{description} - \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[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. @@ -345,7 +355,7 @@ Various representations of time are given so that you can select the most conven \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). +\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$] @@ -365,6 +375,14 @@ Various representations of time are given so that you can select the most conven 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} @@ -376,10 +394,12 @@ This section contains many useful options to cater to the various preferences of shutting down and the next time you start up \CGG{} you will be right back where you left off. You will retain all of your undo's and redo's. \item[Timeline Rectify Audio] \index{timeline rectify audio} for displaying rectified audio on the timeline instead of a standard audio waveform, check this flag. The waveform is cut on the zero line, thus making the silent areas more visible and the waveform is stretched more over the entire height of the audio track, which improves the visibility of certain areas. This only affects the timeline and not any other audio waveform displays. +Once you check or uncheck this flag, you must reload any media on the timeline +in order to see the changed waveform. \item[Clears before toggle] \index{clears before toggle} when using copy/paste in drag and drop mode some users prefer to resort to the addition of the Ctrl key for adding multiple selections. By checking this flag, the user retains usage as is commonly done for listbox operations. \item[Always show next frame] \index{always show next frame} in this mode the insertion pointer reflects the same as the Compositor so that for playing forward, the result is what looks like 1 was added to the frame displayed in the Compositor window. This is fully explained in another section (\nameref{sub:playing_seeking}). \item[Show tip of the day] if checked, a tip will be displayed in a popup box when start up \CGG{}. - \item[Use thumbnails in resource window] \index{use thumbnails in resources window} the Resource Window displays thumbnails of assets by default, but drawing asset thumbnails can take more time and CPU so you may want to uncheck this. + \item[Use thumbnails in resource window] \index{use thumbnails in resources window} the Resource Window displays thumbnails of assets by default, but drawing asset thumbnails can take more time and CPU as well as other system resources so you may want to uncheck this. \item[Popups activate on button up] \index{popups activate on button up} this is the default but if unchecked, popups activate on button down. \item[Set Input Focus when window entered] \index{set input focus} this is checked on by default because on some operating system distros, when you move your mouse to a different window, nothing happens and you are left wondering why you can not enter information. When checked this causes the input focus to shift to any \CGG{} window when the cursor enters an exposed region of the window which eliminates the need to switch input focus by tabbing. \item[Click to activate text focus] \index{click to activate text focus} Click to activate text focus @@ -403,7 +423,7 @@ The following exported variables can be set to customize your environment. \\ Th \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 diff --git a/parts/DVD.tex b/parts/DVD.tex index 07abb14..08c59c5 100644 --- a/parts/DVD.tex +++ b/parts/DVD.tex @@ -3,18 +3,21 @@ \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{.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. @@ -27,12 +30,13 @@ Figure~\ref{fig:preset01} shows pulldown \textit{Presets} in \textit{Set Format} \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. @@ -42,7 +46,9 @@ A quick set of basic steps to create DVDs is immediately below and usually just \item Load your media, format if needed, note device name to substitute for \textit{} or \textit{} \begin{itemize} \item If rewritable blu-ray, use \\ - \texttt{dd if=./bd.udfs of=/dev/ bs=2048000} + \texttt{dd if=./bd.udfs of=/dev/ 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.udfs} \item If any DVD media, use \\ @@ -56,7 +62,9 @@ Any problems encountered will require that you read more information in this sec 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{/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{/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{/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: @@ -123,14 +131,23 @@ Explanation of the choice boxes as seen in figure~\ref{fig:bluray_dvd} for both \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] @@ -167,9 +184,9 @@ Horizontal and Vertical are duplicates or restatement of same functionality as C \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 @@ -190,13 +207,13 @@ When you click on \textit{start}, it fires off those jobs and you will see the r This will produce a new directory in your target path which contains a filesystem image file. For example: \\ -\texttt{/TargetDirectory/bd\_20150820-093747} \\ +\texttt{//bd\_(or dvd\_)/} \\ 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 //bd_(or dvd_)/ mount -o loop,ro ./bd.udfs ./udfs #check the media using a compatible media rendering tool like ffplay umount ./udfs... @@ -210,7 +227,7 @@ To burn blu-ray media you will need to run from the command line interface. In 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 @@ -219,14 +236,14 @@ 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 //bd_(or dvd_)/ 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 //bd_(or dvd_)/ growisofs -dvd-compat -Z /dev/bd=./bd.udfs \end{lstlisting} @@ -236,7 +253,7 @@ growisofs -dvd-compat -Z /dev/bd=./bd.udfs 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 @@ -245,7 +262,7 @@ 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 //bd_(or dvd_)/ growisofs -dvd-compat -Z /dev/dvd -dvd-video ./iso \end{lstlisting} @@ -480,13 +497,56 @@ With this option enabled, improved chroma results will be obtained from your DV 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} @@ -533,21 +593,59 @@ zmpeg3cc2txt -o - /dvb_data/channel5.ts For some time, DVD manufacturers have been employing a variety of measures to make reading a DVD difficult on a computer. One technique which is widely deployed is to add a bunch of extra program data, so that correct playback is only likely if you can read the DVD virtual machine data and decode a maze of program data to find the undamaged stream definitions. Only a few streams are created which are machine usable, and dozens are created as decoy streams. The decoy streams fail or introduce errors. This program scans the IFO (info file) playlists and verifies the contents of the stream that does not contain obvious damage. The result is a list of program ids which can be entered into the playback preferences to select a program which qualifies. -\section{HDV on a Blu-ray Disc Without Re-encoding}% -\label{sec:hdv_bd_without_reencoding} -\index{BluRay!HDV without re-encoding} +\section{Creating Blu-ray Without Re-encoding}% +\label{sec:bluray_without_reencoding} +\index{BluRay!without re-encoding} +\index{BluRay!camcorders} +\index{BluRay!AVCHD} + +If you have video that is already in Blu-ray format AND you do not want to use \CGG{} to do +any editing, you can create blu-ray video media using Cinelerra's \textit{bdwrite} program. This +could be the case if you are working with media from a modern Digital Camcorder. Camcorders +usually record in a legacy tape-based format or the current file-based format. The most common +digital camcorder formats and whether or not they need to be re-encoded are: -An MTS file is a video file saved in the high-definition (HD) MPEG Transport Stream video format, commonly called \textit{AVCHD}. It contains HD video compatible with Blu-ray disc format and is based on the MPEG-2 transport stream. MTS files are often used by Sony, Panasonic, Canon and other HD camcorders. Legal input for Video -- MPEG1VIDEO, MPEG2VIDEO, H264; Audio -- MP1, MP2, AC3, AC3PLUS, DTS, TRUHD. +\begin{itemize} + \item DV (1995) to SD-blu-ray video - process in \CGG{} using the File pulldown of +BD Render as previously described or use programs documented in their manuals to re-encode +video to mpeg2 and then re-encode DV LPCM audio to Blu-ray LPCM. + \item HDV (2004) to blu-ray video - process in \CGG{} using the File pulldown of +BD Render as previously described or use programs documented in their manuals to + copy mpeg2 +video and then re-encode MP2 audio to Blu-ray LPCM or AC3. + \item AVCHD (2006-current) to blu-ray video; these are the types of videos that do +not have to be re-encoded if you do not want to edit anything. +\end{itemize} +For an explanation of the differences between HDV vs AVCHD see: + {\small \url{http://www.differencebetween.net/technology/difference-between-hdv-and-avchd}} -For creating a blu-ray disc, if you have HDV MPEG-2 media that is in blu-ray format, you can save the original quality of your work, rather than rendering it to another format. Follow the steps below directly instead of going through \CGG{}. It has been tested on 10 different MTS files. +Besides digital camcorder file-based format of AVCHD, there are video files in MTS format +that are also candidates for burning to blu-ray video media without re-encoding. +An MTS file is a video file saved in the high-definition (HD) MPEG Transport Stream video format/H264, commonly called \textit{AVCHD}. It contains HD video compatible with Blu-ray video disc format and is based on the MPEG-2 transport stream. MTS files are often used by Sony, Panasonic, Canon and other HD camcorders. Legal input for Video -- MPEG1VIDEO, MPEG2VIDEO, H264; Audio -- MP1, MP2, AC3, AC3PLUS, DTS, TRUHD. +For creating a blu-ray video disc, if you have these HD MPEG-2 media types that are in blu-ray video format, you can save the original quality of your work, rather than rendering it to another format. +Note that for older media or media which used MP1 or MP2 audio codecs which will not work on +blu-ray video discs, it may be necessary to first transcode the audio while leaving video intact. +An example of the transcode line to use if using ffmpeg version 5.1 or higher is shown next. +If using a lower ffmpeg version substitute ac3 for pcm\_bluray: + +\begin{lstlisting}[numbers=none] +ffmpeg -i hdv -c:v copy -c:a pcm_bluray -mpegts_m2ts_mode 1 new_hdv.mts +\end{lstlisting} + +Follow the next 2 sets of steps to create the blu-ray video disc. \begin{lstlisting}[style=sh] -du -sb /yourHDVfile.MTS # Determine the size of your file in bytes. -blocks=((size-in-bytes/2048 + 4096)) # Convert bytes into blocks + a little more. -mkudffs /tmp/newfilename.udfs blocks # Create a file with that \# of blocks + some extra. +du -sb /yourHDVfile.MTS # Determine the size of your file in bytes. +blocks=((size-in-bytes/2048 + 4096)) # Convert bytes into blocks + a little more. +mkudffs -b 2048 /tmp/newfilename.udfs blocks # Create a file with that \# of blocks + some extra. mount -o loop /tmp/newfilename.udfs /mntX # Use a mount point like mntX that is not in use. +\end{lstlisting} +In order to create the udfs file, you will need access to Cinelerra's \textit{bdwrite} program. +If you do not do your own build and compile, but use the AppImage instead, you will have to first +extract \textit{bdwrite} from the AppImage as described in the NOTE at \ref{sub:managing_appimage}. +\begin{lstlisting}[style=sh] //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} @@ -569,7 +667,8 @@ Also, be sure to do a \texttt{mkdir bluray} in your \texttt{/home/name} director \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: diff --git a/parts/Developer.tex b/parts/Developer.tex index 5532ce8..34d355f 100644 --- a/parts/Developer.tex +++ b/parts/Developer.tex @@ -20,7 +20,7 @@ So, an example of what happens in 4 steps for a single-user build would be as fo \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} @@ -98,18 +98,35 @@ FFmpeg is a \textit{strongly connected} component in the build linkage and widel \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} @@ -210,6 +227,7 @@ Optional Features: --enable-openjpeg build openjpeg (auto) --enable-libogg build libogg (auto) --enable-libsndfile build libsndfile (auto) + --enable-libsvtav1 build libsvtav1 (no) --enable-libtheora build libtheora (auto) --enable-libuuid build libuuid (yes) --enable-libvorbis build libvorbis (auto) @@ -317,12 +335,13 @@ Individual package libraries can be rebuilt, via: 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} @@ -351,7 +370,7 @@ developer's feedback and experimentation. \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 @@ -388,20 +407,12 @@ compile; and use binaries that you do not know what they contain since no source 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} @@ -470,7 +481,10 @@ It comes back with the routine as: \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: @@ -483,6 +497,10 @@ The best way to compile and run valgrind is to run the developer static build. T \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} @@ -492,7 +510,14 @@ Now your \CGG{} obj has all of the debug stuff. Next run valgrind as root for th 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} @@ -650,6 +675,134 @@ The summary line above in Bold represents the User time, System time, Real time So why use a Profiler? Because it is the ``ls'' for executable functions!! +\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} @@ -724,3 +877,180 @@ example, the SUV theme has over 800 lines in the initialize function, and has ov 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. diff --git a/parts/Editing.tex b/parts/Editing.tex index 47af184..95bcb10 100644 --- a/parts/Editing.tex +++ b/parts/Editing.tex @@ -11,6 +11,8 @@ but not often considered editing method is called \textit{two-screen editing} \index{two-screen} (or 3 point editing) where the Viewer is used to view media and then the desired clip from the media is transferred to the timeline. +In the timeline, Audio tracks are different from Video tracks so a media including both audio and video will be split into 2 or more independent tracks. There is no \textit{Link/Unlink}-like function present in other programs, although there are workarounds. + The timeline \index{timeline} is where all editing decisions are made (figure~\ref{fig:timeline}). This is a stack of tracks in the center of the main window. It can be scrolled up, down, left and @@ -54,6 +56,8 @@ represents the editing decisions, you need to render it. Saving and loading your edit decisions is explained in the Load, Save and the EDL \index{EDL} section and rendering is explained in the section on Rendering. +\textbf{Nomenclature:} media loaded in the timeline, in whole or in part, are called \textit{edits}, unlike other programs that call them \textit{clips}. Clips in \CGG{} are those that are created in the Viewer window or in the timeline via the \texttt{to clip} command and brought into the Resources window, inside the \texttt{Clips folder}, where they can be renamed and a description added. These, once brought into the timeline, are renamed edits. In \CGG{} the difference edits/clips is not important and you can use them as synonyms; however, the difference of clips as it is intended in other NLEs is important. These are media (or parts of it) complete in themselves and indipendent from other clips and the timeline. Edits in \CGG{} on the other hand, can be a media (or part of it) but can also be any region of the timeline between In/Out Points or from a highlighted, on which we can do editing operations. This leads to some advantages (e.g. putting an effect only in a part of the active region) but one must always keep in mind that the edit remains dependent on the track and the entire timeline. + In the following editing sections, references to common operations are scattered within any of the modes where they seem pertinent. However, many of the editing operations work in different modes. @@ -129,7 +133,9 @@ The 7 \textit{attributes} are described here next followed by the other availabl 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} @@ -317,11 +323,10 @@ on top of old tracks. 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} \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. 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: +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 @@ -329,15 +334,7 @@ To get this capability, there is a \textit{Gang Tracks} \index{gang tracks toggl \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, 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} -\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 @@ -346,7 +343,6 @@ Stereo tracks, or 5:1 channels/any number of audio tracks, are drawn as 1 audio \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} @@ -359,7 +355,7 @@ Stereo tracks, or 5:1 channels/any number of audio tracks, are drawn as 1 audio 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. @@ -367,11 +363,12 @@ There are no restrictions on how you use this feature and there may be variation 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 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}% @@ -556,7 +553,7 @@ 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. @@ -676,6 +673,7 @@ you can see an arrow pointing to the corner. Use Shift-left mouse 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} @@ -694,7 +692,7 @@ on the timeline. To simply get started, perform the following operations which are useful for working in a drag and drop editing session. First load your media by using the main menu \textit{File} pulldown \index{file pulldown} and choose -\textit{Load files} \index{load media files}; make sure the insertion mode is set to +\textit{Load files}\index{load media files}; make sure the insertion mode is set to \textit{Create new resources only} \index{insertion strategy}. This loads the files into the Resources window \index{resources window}. @@ -816,7 +814,6 @@ you click on the middle mouse button. An expanded explanation is 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}\\ @@ -829,22 +826,21 @@ provided below. off if it is on.\\ \bottomrule \end{longtable} -\end{center} -\begin{center} \begin{longtable}{p{0.2\textwidth-2\tabcolsep} - p{0.2\textwidth-2\tabcolsep} p{0.6\textwidth-2\tabcolsep} - } + p{0.2\textwidth-2\tabcolsep} p{0.6\textwidth-2\tabcolsep}} \toprule \textbf{Popup Label} & \textbf{Key} & \textbf{Operation}\\ \midrule + %begin{latexonly} \endhead + %end{latexonly} Clear Select & Ctrl-Shift-A & Deselect all selected edits -- ones that have the red lines around them.\\ - Select Edits & Ctrl-Alt-' & Select all edits within a highlighted area of the timeline \\ + Select Edits & Ctrl-Alt-' & Select all edits within a highlighted area of the timeline * (see note below) \\ - Deselect Edits & & Deselect all edits within a highlighted area of the timeline \\ + Deselect Edits & & Deselect all edits within a highlighted area of the timeline * (see note below) \\ Copy & Ctrl-c & Copy the selected edits into the copy buffer.\\ @@ -884,14 +880,15 @@ provided below. 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 @@ -930,12 +927,12 @@ following keyboard shortcuts to perform the same functions: \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} @@ -1138,7 +1135,9 @@ There is also a faster way: \item Choose the \textit{Select or Deselect edits} option and the clips inside the highlight area will be selected or deselected. \end{enumerate} -And there is a Drag mouse way (this requires that the cursor be on the first +NOTE: \textit{Select Edits/Deselect Edits} option toggle between select and deselect edits. If you have selected an edit and you want to deselect it but select the edits near to it, you can highlight the area and using \textit{Deselect Edits} (or \textit{Select Edits}) the edits near to it will be selected while the edit selected before will be deselected. Of course it works for more edits selected before too. In practice, edits that were selected are deselected, while unselected edits (included in the selection area we created) are selected. If you want to deselect all the selected edits you must use \textit{Clear Select} option by MMB. + +There is a Drag mouse way (this requires that the cursor be on the first clip and from there you start the drag): \begin{enumerate} \item To Drag Select edits, hold down Alt+Left Mouse Button (LMB) and drag over the selection area. Releasing the mouse results in selecting. @@ -1177,12 +1176,18 @@ another 2 minutes. This feature provides the following capabilities: \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. @@ -1430,11 +1435,14 @@ $4\times4$\,inches. \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 @@ -1811,7 +1819,8 @@ cat "/sys/kernel/debug/hid/0003:0B33.0030.0006/events" # press keys to see the 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] diff --git a/parts/FFmpeg.tex b/parts/FFmpeg.tex index 4424804..12c867c 100644 --- a/parts/FFmpeg.tex +++ b/parts/FFmpeg.tex @@ -41,25 +41,27 @@ that ffmpeg early probes is enabled; (2) \textit{Try FFMpeg last} indicator mes 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} @@ -92,6 +94,7 @@ In the ffmpeg configuration directory there are a series of options files used w \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] @@ -237,7 +240,7 @@ To get a listing of the current ffmpeg supported formats and codecs that can be 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 @@ -250,7 +253,7 @@ b 256000 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: @@ -314,7 +317,7 @@ Figure~\ref{fig:video-preset} shows \textit{ffmpeg} video as the Kind. Note the \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 @@ -328,18 +331,19 @@ Figure~\ref{fig:audio-preset02} shows \textit{ffmpeg} video for the Kind. Note t \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} diff --git a/parts/Faq.tex b/parts/Faq.tex new file mode 100644 index 0000000..d29b42d --- /dev/null +++ b/parts/Faq.tex @@ -0,0 +1,75 @@ +\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} + diff --git a/parts/Glossary.tex b/parts/Glossary.tex index db842ef..1e42136 100644 --- a/parts/Glossary.tex +++ b/parts/Glossary.tex @@ -16,7 +16,7 @@ \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{\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.} +\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{\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.} diff --git a/parts/Installation.tex b/parts/Installation.tex index 2258db4..a938d23 100644 --- a/parts/Installation.tex +++ b/parts/Installation.tex @@ -2,6 +2,86 @@ \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} @@ -12,6 +92,10 @@ \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 @@ -20,8 +104,7 @@ you get the added benefit of the latest checked in changes, please reference ~\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}{}{} @@ -78,11 +161,24 @@ caption={README.pkgs} 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 @@ -137,8 +233,7 @@ To do a system build \index{build} , you should read the file \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 @@ -160,20 +255,19 @@ cd cinelerra5/cinelerra-5.1 \begin{lstlisting}[style=sh] ./blds/bld_prepare.sh # where 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] @@ -192,7 +286,7 @@ grep "\*\*\*.*error" -ai log make install \end{lstlisting} Where 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. @@ -215,8 +309,7 @@ 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. @@ -232,8 +325,7 @@ cd cinelerra5/cinelerra-5.1 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] @@ -244,7 +336,7 @@ make 2>&1 | tee log make install \end{lstlisting} Where 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. @@ -252,14 +344,13 @@ 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] @@ -272,20 +363,18 @@ After you have followed the above, in the cin.desktop file, change the \texttt{Exec=cin} line to be \texttt{Exec=/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} @@ -297,6 +386,16 @@ handling errors, other problems and potential crashes with the most success. Included in this section are some of the build variations easily available for normal builds. +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] @@ -371,6 +470,23 @@ export ac_cv_header_xmmintrin_h=no 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} @@ -382,58 +498,62 @@ 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 @@ -540,6 +660,8 @@ git clean -i # interactive clean, use answer 1 to "clean" 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] @@ -624,6 +746,10 @@ cd cinelerra 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} @@ -677,10 +803,57 @@ this can be debilitating; you can always run \texttt{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: libxcb. This setup has been tested with @@ -883,20 +1056,117 @@ Running gdb from inside a desktop resident console (not a cygwin64 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{Distro with \CGG{} 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/file.jpg //DSC*.jpg +./jpeglist.sh //outputfile.jpgs //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 @@ -110,6 +111,10 @@ JPEGLIST ./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} @@ -185,7 +190,9 @@ All data that you work with in \CGG{} is acquired either by loading from disk or \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] \index{insertion strategy} @@ -361,28 +368,37 @@ Originally, the easiest way to maintain a project for moving to another computer \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. +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 perpetual.dat file is updated so that when you Quit \CGG{} in the normal manner, +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. -\vspace{1ex} Some notes to keep in mind about Perpetual session are: @@ -390,12 +406,39 @@ 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 + \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: /your\_cinelerra\_path\texttt{/bin/cin -S} + \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} diff --git a/parts/Overlays.tex b/parts/Overlays.tex index 34b202f..dc948f3 100644 --- a/parts/Overlays.tex +++ b/parts/Overlays.tex @@ -27,6 +27,7 @@ Conceptually, when the foreground color is completely opaque, the resulting blen 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 @@ -136,7 +137,15 @@ Each line describes a pair with the left one for alpha and the right one for chr The previous math forms are the only truly accurate description of each blending operation, but short descriptions are below where \textit{Source} is the output from the next track and \textit{Destination} is the output from the lower track stacking. Blending starts with new Source and combines it with the previous render stack output, which is referred to as Destination. The new output becomes the next Destination and the next up stack level becomes the new Source. Source is above; Destination is below. -Note: the Graphic Art group operates principally on color, and the others operate principally on alpha. +Some notable items that affect the results are listed here. +\begin{enumerate} + \item So as not to be surprised by the results, set your Video Driver to X11, not X11-OpenGL, because when rendering your video no graphics library is used. Rendering is handled in software and there is sometimes anomaly differences when using the OpenGL driver. + \item The Graphic Art group operates principally on color, and the others operate principally on alpha. + \item When using the Title plugin with text, blending or changes in the text will only take affect in Subtract, Divide, and Difference. This matches the implmentation of the original Cinelerra version. + \item If comparing results with the original Cinelerra version for Subtract and Divide, you may have to switch the order of the source and destination tracks to see the same output. If you do not want to switch tracks, you can use the \textit{overlay} plugin as shared and change the Layer order and/or Output layer. The reason for having to switch tracks to get equivalent output is because of differences in the math formulas used. Subtract exactly matches the original Cinelerra version if you switch the 2 tracks; Divide matches in one order only. + \item Instead of using the patchbay overlays, you may prefer to use the \textit{overlay} plugin instead. + \item If you see undesirable results, always check under Settings->Format and check your Color Model as that will vary or interfere with the look. +\end{enumerate} % Leave the word Group in due to latex2html dual name conflict \subsection*{Normal Group}% @@ -154,11 +163,11 @@ Note: the Graphic Art group operates principally on color, and the others operat 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}% @@ -210,6 +219,45 @@ 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 diff --git a/parts/Plugins.tex b/parts/Plugins.tex index dfa2d97..0dc5384 100644 --- a/parts/Plugins.tex +++ b/parts/Plugins.tex @@ -4,6 +4,9 @@ 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] @@ -44,11 +47,13 @@ Note that when you change the plugin icons, your session will automatically save \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 \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 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} \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. +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 \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. @@ -95,6 +100,21 @@ Figure~\ref{fig:drag-effect} showing 3 plugins, two still plugin, two have alrea \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} @@ -177,10 +197,22 @@ To get a short one or a few lines description of a plugin, mouse over that plugi \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 @@ -222,6 +254,8 @@ For some System installs, the files might be located at: (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} @@ -266,6 +300,7 @@ Keep in mind these points for newly created plugin icons: \label{sub:example_plugin_icon_testing} For a simple test just copy an existing \texttt{.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{/plugins/picon/original}. This icon will show up in \CGG{} if original is selected and execute the \textit{F\_loop} function. @@ -319,7 +354,7 @@ To accentuate a set of common plugins, there are \textit{expander} arrows on the \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 @@ -332,6 +367,10 @@ The \texttt{expanders.txt} file has very specific requirements. The most specifi \begin{lstlisting}[style=sh] Video Effects + -Favorites + Brightness/Contrast + Title + VideoScope - Color_Correction Blue Banana Color 3 Way @@ -344,6 +383,14 @@ Audio Effects 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} @@ -480,6 +527,7 @@ Use this to remove \textit{DC Offset}, which is usually an undesirable character \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} @@ -491,18 +539,18 @@ Reduce audio background noise. There is only 1 parameter which is used to regula \label{sub:denoisefft} \index{denoisefft} -Audio sampling (time data) is converted to a frequency spectrum using FFT (\textit{Fast Fourier Transform}). Since the \textit{Signal} 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. +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. For example, if you record a voice with a microphone\protect\footnote{credit fary54}: \begin{enumerate} - \item You record 15 seconds of background noise (without talking). This is the \textit{Signal audio clip}. - \item After 15 seconds, start the voice. This is the whole \textit{Noise Audio clip} + \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 signal noise). + \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 which, in our example, ends at 65536 samples later. +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. @@ -583,7 +631,7 @@ EchoCancel is the process of removing echos from audio in order to improve the q \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. @@ -676,7 +724,7 @@ Remove silent gap (below $DB$ threshold) which persist for more than the time li 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 \\ @@ -788,7 +836,7 @@ export LADSPA_PATH=/usr/lib/ladspa 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. @@ -895,7 +943,7 @@ This effect is the one to use if you want to achieve an old movie or TV show loo \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} @@ -907,12 +955,12 @@ Automatically scale to a specified size. \label{sub:blue_banana} \index{blue banana} -Blue Banana\protect\footnote{credit to Monty Montgomery programmer} is an \textit{HSL Qualifier} \index{HSL Qualifier} (HSL= hue, saturation, lightness), one of the basic tools of any grading software that are based on circumscribing a zone of the frame by extracting a chromatic key and producing a \textit{matte} in the alpha channel (Secondary Color Correction). Blue Banana differs not by creating a real matte, but by creating a \textit{selection mask} exclusively for use within the plugin. The BlueBanana plugin has a couple of useful purposes. It can be used for color transformation or remapping -- by isolating a specific color and then performing color change/correction on only that color (or color ranges). Another useful purpose is for chroma-key filtering, using multiple BlueBanana plugins on the same track. Also, it can be used in conjunction with the mask operation of the Compositor. Usage of BlueBanana may seem complicated at first, but it is necessarily so in order to get enough control to produce the desired effect simply and quickly. Just changing a single color is actually quite easy. BlueBanana is keyframable (figure~\ref{fig:bluebanana}). +Blue Banana\protect\footnote{credit to Monty Montgomery programmer} is an \textit{HSL Qualifier} \index{HSL Qualifier} (HSL= Hue, Saturation, Luminance; HSV in our plugin, with V = Value), one of the basic tools of any grading software that are based on circumscribing a zone of the frame by extracting a chromatic key and producing a \textit{matte} in the alpha channel (Secondary Color Correction). Blue Banana differs not by creating a real matte, but by creating a \textit{selection mask} exclusively for use within the plugin. The three H, S and V sliders are called \textit{qualifiers}. The BlueBanana plugin has a couple of useful purposes. It can be used for color transformation or remapping -- by isolating a specific color and then performing color change/correction on only that color (or color ranges). Another useful purpose is for chroma-key filtering, using multiple BlueBanana plugins on the same track. Also, it can be used in conjunction with the mask operation of the Compositor. Usage of BlueBanana may seem complicated at first, but it is necessarily so in order to get enough control to produce the desired effect simply and quickly. Just changing a single color is actually quite easy. BlueBanana is keyframable (figure~\ref{fig:bluebanana}). The basic strategy for BlueBanana is to: \begin{itemize} - \item Select a specific target color. + \item Select a specific target color with the eyedropper tool. \item Create a selection region by expanding color ranges around that color. \item Optionally reduce or expand the alpha plane as a regional selection mask. \item Optionally apply a color remapping or transformation to the selection. @@ -948,25 +996,26 @@ If you just want to try this, follow these steps. \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} @@ -988,9 +1037,10 @@ This section is used to select the target color domain. First, a short explanati 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}: @@ -1024,10 +1074,12 @@ 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} @@ -1056,8 +1108,18 @@ This section is used to modify the color of your selection. Descriptive commenta \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} @@ -1106,6 +1168,27 @@ This is a Gaussian type blur. Other blur plugins -- \textit{Linear}, \textit{Mot \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} @@ -1152,7 +1235,7 @@ is a clear button on the right to set the value to 1. 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}% @@ -1234,7 +1317,7 @@ This effect erases pixels which match the selected color. They are replaced with \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. @@ -1259,7 +1342,7 @@ Chroma Key (HSV)\protect\footnote{Credit for Plugin by Jerome Cornet \url{http:/ \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} @@ -1309,7 +1392,7 @@ Together with \textit{Histogram Bezier / Curves} Color 3 Way is the main tool of \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} @@ -1326,6 +1409,8 @@ The most common use cases (but can be adapted to virtually any situation) of the \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} @@ -1680,7 +1765,7 @@ In its simplest form, highlight a region of the track to freeze, drop the \textt 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 @@ -1688,7 +1773,7 @@ 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 @@ -1699,7 +1784,7 @@ incorrect linearization, etc. \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} @@ -1710,13 +1795,13 @@ The best use of the gamma is manually monitoring the waveform as shown in 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} @@ -1761,7 +1846,8 @@ Remap colors using blended histogram weights. Figure~\ref{fig:histeq} shows the \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. @@ -1774,7 +1860,7 @@ Histeq equalizes the colorspace through use of a \textit{histogram equalization \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 @@ -1783,19 +1869,30 @@ The histogram allows an immediate view of the contrast amplitude of an image wit \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} @@ -1803,78 +1900,90 @@ color to determine the color you want the rest of the video to be. When there is a large light or color variation within a range of a few frames, you spend a lot of time correcting each frame when it would be better to just get an average value to use. If you want, then you can make a LUT for -that set of frames instead of each frame. - +that set of frames instead of each frame.\\ It works by selecting the area on the timeline for which you would like to see the Histogram averaged and then click on the -\textit{Frames} button in the Histogram plugin. -The parameters are: -\textit{Linear to Log} slider: frequency in Linear range to Log range; default is 50\%, but if you want it to be the same as the Videoscope or Histogram Bezier, set the slider all the way to Log. The variation is by 10\% steps. Linear generally represents what the eye sees in the real world. Log is an exponential look where the small numbers are represented more - that is, the leading digit. -\textit{Frames} button: if a Selection is set on the timeline, the number of frames -will be calculated and shown in the box next to it. -\textit{Frame Count box}: type in the number of frames you want to be looked at -starting at the insert marker or use the up/down counter. -\textit{Clear Frames} icon: reset the frame count to the default value of 0. +\textbf{sum frames} button in the Histogram plugin. If a Selection is set on the timeline, the number of frames will be calculated and equalized to the mean value. A side note: by using a number of frames, you can get a \textit{dissolve-like transition effect}. \paragraph{Theory:} -A histogram is a bunch of \textit{bins} (accumulators) that count the number of times a particular pixel channel intensity occurs in an image. Dim are on the left, bright on the right. +For more on the mathematical aspect see here: + +{\small \url{https://thirdspacelearning.com/gcse-maths/statistics/histogram/}} + +For our discussion, it is enough to understand a few concepts. Each vertical line we see in the histogram is not a simple line, but a rectangle having a certain base. This base is given by the values of $x_i$ present at the edges of the rectangle \textit{i} (pixel range, $x_{max_i} - x_{min_i}$). Rectangles are called \textit{Bins} or Accumulators. The bin's number is of fixed and known size because it depends on the color depth. The bin height is our output $y$ and the bin area ($A_i = f(x_i)$) is known because it represents the \textit{number of occurrences} that are read in bin, also called \textit{frequency ($f_x$)}. The plugin scans the entire range of $x_i$, from 0 to 1.0, and records all the occurrences within each bin. The value of $f_x$ for each bin is the \textit{max} value. At this point knowing base and area, we can obtain the value of $y$ axis that is reported in the histogram. + +$width = b_i = x_{max_i} - x_{min_i}$ -The number of bins used depends on the color model bit depth: +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[Histogram:] 256 for rgb8 and 65536 for all others + \item[Bezier:] 256 for rgb8/yuv8 and 65536 for all others \item[Scopes:] always uses 65536 \end{description} -All of the bins are scanned when the graph is plotted. What is shown -depends on which plugin is used: +All of the bins are scanned when the graph is plotted. What is shown on the graph, in the Compositor window, and finally on the scopes, depends on which plugin is used: \begin{description} - \item[Histogram:] was max of the bins in the pixel range, now is the sum + \item[Histogram:] was max of the bins in the pixel range, now is the sum (to make it congruent with Bezier and the Scopes) \item[Bezier:] is the max of the bins in the pixel range \item[Scopes:] is the max of the bins in the pixel range \end{description} -When the color space and the bin size are the same, all of the values -increment the indexed bins. When the color is the result of yuv $\rightarrow$ rgb conversion, the results \textit{spread} if there are more bins than colors. This is the same effect you see when you turn on \textit{smoothing} in the vectorscope histogram. +Another difference in behavior is regarding the type of curve, whether Linear or Log: + +\begin{description} + \item[Histogram:] the curve is Linear, but it is editable with the Linear/Log slider + \item[Bezier:] the curve is Log + \item[Scopes:] the curve is Log +\end{description} + +This diversity also leads to different visual results from Histogram Bezier or Videoscope. -The \textit{total} pixels for each value is approximately the same, but the \textit{max} value depends on the color quantization. More colors increment more bins. Fewer colors increment fewer bins. In both cases, the image size has the same -number of pixels. The fewer color case increments the used bins, and skips the -unused bins. This sums all of the pixels into fewer bins, and the bins have -higher values. That is the \textit{rgb} vs \textit{yuv} case, fewer vs more bins are used. +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. -To report something more consistent, has been changed the reported value to -the \textit{sum} of the accumulated counts for the bins reporting a pixel bar on the -graph. The effect of this is to do this: +The \textit{total} pixels for each value is approximately the same, but the \textit{max} value depends on the color quantization. More colors increment more bins. Fewer colors increment fewer bins. In both cases, the image size has the same number of pixels. So the pixels will distribute into more bins if you go to a higher depth color; those bins will have a lower count. The fewer color case increments the used bins, and skips the unused bins. This sums all of the pixels into fewer bins, and the bins have higher values. That is the \textit{rgb} vs \textit{yuv} case, fewer vs more bins are used. To get more consistent visual feedback (and on scopes), the concept of \textit{sum} was used instead of the maximum number of occurrences (max). + +To report something more consistent, the reported value has been changed from the original code to be the \textit{sum} of the accumulated counts for the bins reporting a pixel bar on the \begin{center} - \begin{tabular}{ l l c r r } + \begin{tabular}{clccr} \hline 1 & & & & \\ 1 & & & 1 & \\ - 000100 & 3 pixels & vs & 001000& 3 pixels \\ + 000100 & 3 pixels & vs & 0011000& 3 pixels \\ \hline \end{tabular} \end{center} -On the left, the course color model piles all 3 pixels into one bin. max -value 3 - -On the right, the fine color model puts the counts into 2 bins, max 2, sum 3 - -So, by reporting the sum the shape of the results are more similar. +On the left, the course color model piles all 3 pixels into one bin, max +value 3. +On the right, the fine color model puts the counts into 2 bins, max 2, sum 3. +So, by reporting the sum the shape of the results are more similar to Bezier. \subsection{Histogram Bezier / Curves}% \label{sub:histogram_bezier_curves} \index{histogram Bezier} -Histogram Bézier allows an immediate view of the contrast amplitude of an image with its distribution of luma and colors values using a piecewise linear method. In addition it uses a Bézier curve (parametric) on the histogram plot. When mapping color spaces, it has a variety of presentations to get smoother transitions and more pleasing output. It uses more general remapping, not just straight lines but more contour lines. Curves are perhaps the most powerful and sophisticated tool for color correction. For some repetitive details, see the previous description of the Histogram plugin. Histogram Bézier is keyframable. +Histogram Bézier allows an immediate view of the contrast amplitude of an image with its distribution of luma and colors values using a piecewise linear method (bins). In addition it uses a Bézier curve (parametric) on the histogram plot. When mapping color spaces, it has a variety of presentations to get smoother transitions and more pleasing output. It uses more general remapping, not just straight lines but more contour lines. Curves are perhaps the most powerful and sophisticated tool for color correction. For some repetitive details, see the previous description of the Histogram plugin. Histogram Bézier is keyframable. The scale is given in percent ($0 - 100\% \pm 10\%$). The default curve is Log type and can use either RGB or YUV sources without implementing conversions. + +NOTE: Histogram Bezier may give results that are not congruent with Histogram plugin. To understand the difference in behavior see the Theory section in Histogram plugin. The input graph is edited by adding and removing any number of points. Click and drag anywhere in the input graph to create a point and move it. Click on an existing point to make it active and move it. The active point is always indicated by being filled in. The active point's input X and output Y values are given in textboxes on top of the window. The input and output color of the point can be changed through these textboxes. Points can be deleted by first selecting a point and then dragging it to the other side of an adjacent point. They can also be deleted by selecting them and hitting delete (figure~\ref{fig:bezier}). @@ -1915,7 +2024,7 @@ Curves are generally adjusted by introducing several control points, some to be 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}): @@ -1938,22 +2047,23 @@ Some examples of the use of curves to demonstrate the variety of possible interv \label{sub:holographictv} \index{holographicTV} -Incoming objects are projected like holovision seen in the movie Stars Wars as in R2-D2's video message projector of the Princess Leia. You need a movie or background image and above it a track containing the figure on which to apply the effect. This must have a transparent background. There are no configuration parameters; it only has to be applied to the upper track (figure~\ref{fig:holographictv}). +\begin{figure}[htpb] + \centering + \includegraphics[width=0.55\linewidth]{holographictv.png} + \caption{Holographic messages in CinGG!} + \label{fig:holographictv} +\end{figure} + +Incoming objects are projected like holovision seen in the movie Stars Wars as in R2-D2's video message projector of the Princess Leia (figure~\ref{fig:holographictv}). You need a movie or background image and above it a track containing the figure on which to apply the effect. This must have a transparent background. There are no configuration parameters; it only has to be applied to the upper track. This effect originated from {\small \url{https://effectv.com}}. -\begin{figure}[htpb] - \centering - \includegraphics[width=0.8\linewidth]{holographictv.png} - \caption{Holographic messages in CinGG!} - \label{fig:holographictv} -\end{figure} \subsection{Hue saturation}% \label{sub:hue_saturation} \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} @@ -2039,6 +2149,7 @@ This effect acts only in one direction which can vary up to an angle of $180\deg \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}% @@ -2063,10 +2174,33 @@ The loop effects have one option: the \textit{number of frames} or \textit{sampl 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. @@ -2115,6 +2249,8 @@ The Samples box at the top is most often the only parameter that you may want to \label{sub:motion} \index{Motion} +Note: Motion and Motion51 plugins are complex and slow to use for video stabilization. If you are stabilizing an entire video, you may want to preprocess by using ffmpeg's \textit{vidstabdetect} and \textit{vidstabtransform} plugins before importing the video into \CGG{}. + The \textit{motion tracker} is almost a complete application in itself. The motion tracker tracks two types of motion: \textit{translation} and \textit{rotation}. It can track both simultaneously or one only. It can do $\frac{1}{4}$ pixel tracking or single pixel tracking. It can stabilize motion or cause one track to follow the motion of another track. Although the motion tracker is applied as a realtime effect, it usually must be rendered to see useful results. The effect takes a long time to precisely detect motion so it is very slow. Motion tracker works by using one region of the frame as the region to track (Match Box). It compares this region between $2$ frames to calculate the motion. This region can be defined anywhere on the screen. Once the motion between $2$ frames has been calculated, a number of things can be done with that \textit{motion vector}. It can be scaled by a user value and clamped to a maximum range. It can be thrown away or accumulated with all the motion vectors leading up to the current position. @@ -2123,12 +2259,12 @@ To save time the motion result can be saved in a file for later reuse, recalled \begin{figure}[ht] \centering - \includegraphics[width=0.9\linewidth]{motion.png} + \includegraphics[width=0.99\linewidth]{motion.png} \caption{Motion plugin GUI} \label{fig:motion} \end{figure} -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. @@ -2444,7 +2580,14 @@ C - has only object2 visible \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} @@ -2475,7 +2618,8 @@ This effect makes video tracks appears as a painting. It can be controlled by \t \label{sub:overlay} \index{overlay video} -This effect can combine several tracks by using the so called Overlayer. This is a basic internal device normally used by \CGGI{} to create the dissolve transitions and for compositing the final output of every track onto the output bitmap. The Overlayer has the ability to combine one or several image layers on top of a bottom layer. It can do this combining of images in several different (and switchable) output modes such as \textit{Normal}, \textit{Additive}, \textit{Subtractive}, \textit{Multiply} (Filter), \textit{Divide}, \textit{Max} and \textit{Replace}. For a detailed list refer to the on \hyperref[cha:overlays]{Overlays} chapter -- PorterDuff. +This effect can combine several tracks by using the Overlayer. This is a basic internal device normally used by \CGGI{} to create the dissolve transitions and for compositing the final output of every track onto the output bitmap. The Overlayer has the ability to combine one or several image layers on top of a "bottom layer". It can do this combining of images in several different (and switchable) output modes such as \textit{Normal}, \textit{Addition}, \textit{Subtract}, \textit{Multiply} (Filter), \textit{Divide}, \textit{Max} and \textit{Replace}. For a detailed list and some differences in output expectations, refer to the \hyperref[cha:overlays]{Overlays} chapter -- PorterDuff. + The \textit{overlay} plugin enables the use of this Overlayer device in the middle of any plugin stack, opening endless filtering and processing possibilities. It is only useful as a \textit{shared plugin} (i.e.\ a multitrack plugin). To use the overlay plugin: @@ -2486,6 +2630,16 @@ The \textit{overlay} plugin enables the use of this Overlayer device in the midd \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} @@ -2511,13 +2665,13 @@ In (figure~\ref{fig:perspective}) you can see that there are four options for th 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. @@ -2548,7 +2702,13 @@ position a little so that the answers are not exactly zero. \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. With the 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. 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{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} @@ -2562,15 +2722,18 @@ To render to MPEG, add the \textit{RGB-601} effect to all video tracks where mat \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} @@ -2591,6 +2754,7 @@ Radial blur is a \textit{Bokeh} effect that creates a whirlpool which simulates \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$. @@ -2610,7 +2774,7 @@ the sequence, and therefore its length, but not the framerate. The 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} @@ -2635,7 +2799,7 @@ in stretch mode with a value less than $1$. \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} @@ -2651,7 +2815,7 @@ Downsample mode changes the frame rate of the input as well as the number of the \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} @@ -2660,7 +2824,14 @@ Downsample mode changes the frame rate of the input as well as the number of the \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} @@ -2793,7 +2964,7 @@ An example of common usage is to select the number of frames you wish to average \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} @@ -2847,8 +3018,6 @@ LMB click almost anywhere on the compositor screen will automatically show, in t 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 @@ -2897,7 +3066,6 @@ There is no \textit{undo} recorded between gui updates. It is recommended that y Del button in Curve section \\ \bottomrule \end{longtable} -\end{center} \subsubsection*{Other Button and Label Descriptions}% \label{ssub:other_button_label_description} @@ -2929,6 +3097,12 @@ Points and curves are identified by numeric ids, and not the table position. Thi 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} @@ -3011,6 +3185,12 @@ With \textit{Time Range} we decide the size (and therefore the number) of the ba \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} @@ -3043,23 +3223,6 @@ For improving playback performances of titles with effects, you can reduce the s 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. It is -important to note that because there are checkboxes for both Bold and Italic, the pulldown will not include these specific fonts -as an addition to a Regular font. They will be used via the checkboxes but not viewed in the pulldown. - -If the video is displayed on a consumer TV, the outer border is going to be cropped by $5\%$ on each side. To avoid text which is too close to the edge looking bad, you may want to enable the \textit{title-safe} tool in the compositor window. The text should not cross the inner rectangle. - \subsubsection*{Some recently added options}% \label{ssub:some_recently_added_options} @@ -3082,8 +3245,6 @@ If the video is displayed on a consumer TV, the outer border is going to be crop \item[Attributes] in the Text box where you type your Title information, you can now change several attributes to give you plenty of flexibility (figure~\ref{fig:title02}). Each of these special attributes begin with an open angle bracket < and ends with a closing angle bracket >. Until the closing angle bracket is keyed in, the actual characters you type, will be seen in the compositor window. In addition, if you do not use the exact syntax or you keyin a filename that is not available, all of the characters will continue to show up. This helps to see what needs to be fixed or is missing. The attributes usage is described in the table below. \end{description} -\begin{center} - \small \begin{longtable}{{m{6em}m{14em}m{14em}}} \caption{Titler attributes} \label{tabular:titler_attributes} \\ % note that double backslash is mandatory here @@ -3094,7 +3255,7 @@ If the video is displayed on a consumer TV, the outer border is going to be crop color name such as RED from \textit{/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& @@ -3134,7 +3295,6 @@ If the video is displayed on a consumer TV, the outer border is going to be crop 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. @@ -3159,6 +3319,7 @@ Figure~\ref{fig:title03}. \begin{description} \item[Background] in this box you can keyin the name of a file of the type that \CGG{} accepts and use that file as a background for your Title characters (media video or image). This will be seen in the compositor window on top of the video that is loaded in the main track canvas. Besides typing in the filename, you must also check the checkbox. This makes it easy to turn it \textit{On} and \textit{Off} to see what it looks like. Next to the background box is a \textit{Loop} checkbox. If the background file takes less time than the main track canvas video to run, you can turn on the loop checkbox so that it runs over and over again to match the time size of your video. By default the background image will occupy the whole frame, but if we activate \textit{drag} mode and create a box of the desired size, the image will occupy only the box leaving the rest of the frame visible. \item[Stroker] to add \textit{pen strokes} to the text letters, adjust the stroke width numerically. This looks particularly nice on certain fonts and with a negative adjustment of the \textit{Drop shadow}. + \item[Text: chars:] to output and update the number of characters already used. The only limit to the number of characters based on a count of single $8\, bit$ characters is the available resources on the user computer available for \CGG{} use. Keep in mind that unicode or other special characters may consist of $2$ to $4$ $8\,bit$ bytes. Also, newlines are a character and any of the attributes you use count in the total. There is now a horizontal scroll bar as well as the vertical one in the textbox and they only appear when there are more lines or characters than can fit in the original sized textbox. \item[Unicode Insertion] if you want to enter a special character like the mathematical \textit{summation} symbol, you can use the unicode equivalent to do so. Press Ctrl-Shift-U followed by $2022$ and a carriage return is an example of the bullet. Refer to section \hyperref[sec:textbox_non_std_character_unicode]{17.5} for details. \item[Popup Helper] put your cursor where you want to add an attribute, then right mouse will bring up a list of the available attributes for you to choose, along with a submenu to choose from. The program will insert that attribute for you and all you have to add is a value when required! (see figure~\ref{fig:title02}). \end{description} @@ -3186,6 +3347,8 @@ The Text Color window has several enhanced features as listed here and seen in f \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{/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: @@ -3194,11 +3357,32 @@ In order to choose a font faster, you can keyin the first few characters of the \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{/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] @@ -3208,7 +3392,7 @@ export BC_FONT_PATH=/usr/share/fonts 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{ /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{/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: @@ -3230,9 +3414,6 @@ export BC_FONT_PATH=: #(the : "colon" removes all automatic system and Cineler 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} @@ -3258,13 +3439,6 @@ Tracer creates an outline around an object after a few points are designated, so \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. @@ -3280,6 +3454,13 @@ Tracer creates an outline around an object after a few points are designated, so \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. @@ -3305,7 +3486,7 @@ This effect supports keyframes so these parameters can change smoothly over time \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. @@ -3320,6 +3501,15 @@ This effect applies a traditional \textit{darkroom} technique, the so called \te 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: @@ -3340,17 +3530,10 @@ and two vectorscopes: \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). @@ -3402,15 +3585,15 @@ On the left is shown waveform RGB: instead of the color shadows as in figure~\re 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} @@ -3486,25 +3669,26 @@ You can also display the 4 histograms (master or RGB) on the left of the window. \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} @@ -3517,10 +3701,10 @@ Modify the 411 yuv to look like 420 color space instead. If the edit to which th \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} @@ -3528,22 +3712,24 @@ A corrected video image is shown in the bottom. Now the red and blue colors are 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} @@ -3622,7 +3808,7 @@ plugins included for consistency and to avoid problems. 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 @@ -3655,13 +3841,13 @@ cin/plugins/opencv/stylizeobj.plugin The location for most User installs is: -\hspace{4em}\texttt{/plugins/} +\hspace{4em}\texttt{/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} @@ -3704,7 +3890,7 @@ cp Makefile.devel Makefile 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: @@ -3990,31 +4176,44 @@ The following is a list of the integrated audio plug-ins\protect\footnote{credit 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 @@ -4054,7 +4253,7 @@ The following is a list of the integrated audio plug-ins\protect\footnote{credit 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 @@ -4086,9 +4285,11 @@ The following is a list of the integrated audio plug-ins\protect\footnote{credit 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} @@ -4112,23 +4313,32 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi \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. @@ -4180,9 +4390,12 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi \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 @@ -4202,6 +4415,7 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi \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\@. @@ -4210,10 +4424,11 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi 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. @@ -4221,8 +4436,9 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi 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. @@ -4244,6 +4460,7 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi 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. @@ -4264,8 +4481,8 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi \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. @@ -4283,11 +4500,12 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi 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. @@ -4295,13 +4513,15 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi 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. This plugin can be used to correct @@ -4331,6 +4551,7 @@ The following is a list of the integrated video plug-ins \protect\footnote{credi \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. @@ -4396,6 +4617,10 @@ If the scale factor is $2$, every $2$ input samples will be reduced to $1$ outpu \subsubsection*{Time Stretch}% \label{ssub:time_stretch} +\subsubsection*{CD Ripper}% +\label{ssub:cd_ripper} + + \subsection{Rendered Video Effects}% \label{sub:renederd_video_effets} @@ -4416,9 +4641,6 @@ To create a slow-motion of fast moving video: \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} diff --git a/parts/Preserving.tex b/parts/Preserving.tex new file mode 100644 index 0000000..f7ffea2 --- /dev/null +++ b/parts/Preserving.tex @@ -0,0 +1,627 @@ +\chapter{Overview}% +\label{cha:camcorders} + +This document describes the methods used to achieve a "backup type" or intermediate codec +for non-edited source video camcorder formats, compatible with and viewable on Bluray hardware players. After you have +moved your camcorder media onto a computer disk, you can with some extra effort, transfer them for safekeeping and +longer term storage on simple viewable Blu-ray video discs. + +Transferring camcorder media to digital files on a computer, and next to optical Blu-ray video media is especially +important for legacy tape-based camcorders, because tape will degrade over time. You can do this using a combination of +free tools on Linux, generic and independent of any NLE. + +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 +formats. As confirmed by the ffmpeg output below, DV uses 25 Mbps data rate (DV25), is Standard Definition (SD), +resolution 720{\texttimes}576, 8 bits color depth 4:2:0, display aspect ratio (DAR) 4:3 while HDV is High Definition HD video, +resolution 1440{\texttimes}1080, DAR 16:9, 8 bits color depth 4:2:0. + +We utilize or keep relative low MPEG-2 video compression at the same bit-rate 25 Mbps as the original video recorded +onto the source tapes. That is about 13 GB per hour video and audio in total, and about 3 hours playtime with 40 GB +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 +with BD-video. + +In this how-to we combine \textbf{ffmpeg}, \textbf{tsMuxeR} and \textbf{xorriso} to create the MTS-video stream, to +create the Blu-ray ISO image, and to burn the image to Blu-ray video disc. The benefit of using tsMuxer here, is its +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. + +\begin{itemize} +\item \textbf{DV} (1995) transfer to SD-blu-ray video (re-encoding video to mpeg2, re-encoding DV LPCM audio to Blu-ray LPCM) +\item \textbf{HDV} (2004) transfer to blu-ray video (copying mpeg2 video, re-encoding MP2 audio to Blu-ray LPCM or AC3) +\item \textbf{AVCHD} (2006-current) transfer to Blu-ray video (copying H.264 video and AC3 audio) +\end{itemize} + +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}. \\ +{\small \url{https://cinelerra-gg.org/download/CinelerraGG\_Manual/Creating\_Blu\_ray\_Without\_Re.html}} + +There are other methods described on the internet and there are alternatives to the software programs used here that work as well. + +\chapter{Video recording formats}% +\label{cha:recording} + +A description of the most common video recording formats for consumer and prosumer equipment; camcorders, analog video +cassette recorders (VCR decks), digital video hard disc recorders, and optical disc recorders (DVD, Blu-ray). + +\section{\textbf{Analog video} (legacy) onto magnetic tape cassettes}% +\label{sec:analog} +\settocdepth{subsection} + +\subsection{\textbf{VHS (1976), VHS-C (1982), and Video8 (1984)}}% +\label{sub:vhs1976} + +% +% WARNING - the next line will change it for every list for rest of document +% +%\setlist{noitemsep} +\begin{itemize}[noitemsep] +\item Composite Audio/Video is encoded on one channel with maximum horizontal resolution 240 (250) dots (or visually +resolvable vertical picture lines) for VHS/VHS-C and 280 dots for Video8 (2.7MHz video bandwidth). +\item In comparision, horizontal resolution bandwidth for PAL broadcast: 5.0-5.5 MHz, NTSC: 4.2 MHz. +\item It is the horizontal resolution that makes the big difference in picture quality since all video formats have the +same number of vertical resolution (or visible horizontal scan lines); always 576 for PAL/SECAM and 486 for NTSC. +\item RCA (phono) connectors: yellow for composite video, red and white for left and right audio signals. +\item 21-pin SCART Euro connector with optional RCA adapter. +\item Magnetic tape media in full size VHS (1/2") cassettes, VHS-C (1/4") compact and 8\ mm cassettes. +\item Cassette adapters to playback compact VHS-C cassettes on full size VHS decks/players. +\end{itemize} + +\subsection{SVHS (Super VHS, 1987), SVHS-C (-Compact, 1987) and Hi8 (1989)}% +\label{sub:svhs1987} + +\begin{itemize}[noitemsep] +\item S-Video (separate video, Y/C) encodes video \href{https://en.wikipedia.org/wiki/Luma\_(video)}{luma} +(brightness/contrast/black\&white) and +\href{https://en.wikipedia.org/wiki/Chrominance}{chrom}\href{https://en.wikipedia.org/wiki/Chrominance}{a} (color) on +two separate channels, achieving higher image quality and amount of picture details over composite video. +\item Max visible horizontal resolution is 400 dots for SVHS/SVHS-C and 440 dots for Hi8 systems on high-end VCR +machines (4.5 MHz decks). In practice consumer/prosumer camcorder recordings quality vary from about 330-350 dots +horizontal resolution (3.5MHz), which is equivalent to analog TV set quality. +\item 4-pin mini-DIN S-video connector for Y/C video, red and white RCA line connectors for left and right audio; +optional SCART Euro adapter with 4-pin video and RCA audio connectors. +\item In comparision, analog Component video (three component YPbPr) has the highest color resolution and is encoded +over three channels with green, blue and red RCA connectors (consumer) or with BNC connectors (prosumer), additional red +and white phono line connectors for audio. +\end{itemize} + +\section{\textbf{Digital video}}% +\label{sec:digital} + +\subsection{\textbf{DV (1995), Digital8 (1999)}}% +\label{sub:dv1995} + +\begin{itemize}[noitemsep] +\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. +\item DV codecs are still sometimes used when dealing with legacy standard definition SD video: + \newline\hspace*{.5cm}PAL: 625i50, 720 {\texttimes} 576 frame size, 25 fps, 8 bit 4:2:0 subsampling + \newline\hspace*{.5cm}NTSC: 525i60, 720 {\texttimes} 480 frame size, 30 fps, 8-bit 4:1:1 subsampling +\item The same frame size is used for 4:3 and 16:9 frame aspect ratios, resulting in different pixel aspect ratios for +fullscreen and anamorphic widescreen video. +\item DV uses lossy, DCT algorithm intraframe video compression 5:1 on a frame-by-frame basis. +\item Audio almost exclusively is stored as 16-bit LPCM at 48 kHz sampling rate, 1.5 Mbit/s stereo. +\item Data rate is about 25 Mbit/s for video, thus DV25, and an additional 1.5 Mbit/s for PCM audio. +\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 +per hour playtime. +\item DV camcorders and decks have IEEE 1394 (FireWire, i.LINK) ports for digital video transfer. +\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. +\item DV was strongly associated with the transition from analog to digital desktop video production. +\item Digital8 equipment recorded in DV format only, but usually could playback Video8 and Hi8 tapes as well, and were +also capable to do analog to digital video conversion during playback. +\item Most (but not all) modern digital camcorders provided an analog-to-digital +"passthrough" capability. This feature fed an analog input signal (usually via S-Video, +sometimes RCA) into the camcorder and output a standard DV signal. The camcorder converts the analog signal on-the-fly +using a hardware encoder. The input device could be your old analog camcorder (playing 8\ mm or Hi8 tapes), a VHS/VHS-C +video player, to convert analog to digital output via Firewire \textbf{dv} file extension. +\end{itemize} + +\subsection{\textbf{DVD-Video} (1996)}% +\label{sub:DVD-Video} + +DVD-Video discs are intended for full-length movies and offer a range of features including the following: +\begin{itemize}[noitemsep] +\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. +\item Video encoding: MPEG-2 (\href{mailto:MP@ML}{MP@ML}) or MPEG-1. +\item Audio Quality and Languages: Dolby Digital, DTS, MPEG-2 or Linear PCM audio for up to 5.1 channel surround sound. +\end{itemize} + +\begin{itemize} +\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 +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 +video with a \href{https://en.wikipedia.org/wiki/Color\_depth}{bit depth} of 8 bits per color, encoded as +\href{https://en.wikipedia.org/wiki/YCbCr}{YCbCr} with 4:2:0 +\href{https://en.wikipedia.org/wiki/Chroma\_subsampling}{chroma subsampling}. The H.262/MPEG-2 Part 2 format supports +both interlaced and progressive scan content. +\item As for lines of horizontal resolution, DVD has about 500. In analog output signal terms, typical luma frequency +response maintains 53/145 full amplitude to between 5.0 - 5.5 MHz. This is below the 6.75 MHz native frequency of the +MPEG-2 digital signal. Chroma frequency response is one-half that of luma. +\end{itemize} + +The following formats are allowed for H.262/MPEG-2 Part 2 video: +\begin{itemize} +\item At a display rate of 25 frames per second, interlaced or progressive scan (commonly used in regions with 50 Hz +image scanning frequency, compatible with analog 625-line PAL/SECAM): + \begin{adjustwidth}{.5cm}{0cm} + 720 {\texttimes} 576 pixels (D-1 resolution, 4:3 fullscreen or 16:9 anamorphic widescreen aspect ratio) + \end{adjustwidth} +\item At a display rate of 29.97 frames per second, interlaced or progressive scan (commonly used in regions with 60 Hz +image scanning frequency, compatible with analog 525-line NTSC): + \begin{adjustwidth}{.5cm}{0cm} + 720 {\texttimes} 480 pixels (D-1 resolution, 4:3 or 16:9) + \end{adjustwidth} +\end{itemize} + +The official allowed formats for the audio tracks on a DVD-Video are: + \begin{itemize} + \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. +16-bit 48 kHz 8 channel PCM is allowed by the DVD-Video specification but is not well supported by authoring +applications or players. + \item AC-3: 48 kHz sampling rate, 1 to 5.1 (6) channels, up to 448 kbit/s. + \item MP2: 48 kHz sampling rate, 1 to 7.1 channels, up to 912 kbit/s. + \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 = +377.25 and 503.25 kbit/s, bitrates for 5.x and 6.1 = 754.5 and 1509.75 kbit/s. +\item File system: +\begin{itemize}[noitemsep] +\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. +\item The UDF bridge format provides backwards compatibility for operating systems that +support only ISO 9660. +\item Most DVD players read the UDF filesystem from a DVD-Video disc and ignore the ISO9660 filesystem. +\end{itemize} +\end{itemize} + +\subsection{\textbf{HDV (2003)}}% +\label{sub:HDV2003} + +\begin{itemize}[noitemsep] +\item HDV was a successor format to DV with an updated video codec, and used the same MiniDV cassette format, optional +specifically for HDV recording on tape with reduced drop-out rate. +\item Some manufacturers offered on (larger) camera hard disk recording units capable of recording HDV both onto tape +and/or onto file-based media via FireWire connection. +\item HDV camcorders can typically switch between HDV/MP2 and SD-DV/PCM recording modes. +\item HDV 1080i with horizontal resolution 1440 is twice the 720 resolution of DV and DVD, and the perceived +sharpness with HDV is much higher when scaled up to full HD (TV) resolution. +\end{itemize} + +\begin{tabular}{ll} +------------------- \\ +{\textbullet}\textbf{HDV 1080i} specification (HD2): & \textbf{HDV 720p} specification (HD1): \\ +{\textbullet} 1080/ 50i (PAL), 1080/ 60i (NTSC) & 720/25p, 720/50p,720/30p, and 720/60p \\ +{\textbullet} 1440 {\texttimes} 1080, anamorphic pixels 4:3=1.33 & 1280 x 720, Pixel aspect ratio 1.0 \\ +{\textbullet} 16:9 Display aspect ratio & 16:9 Display aspect ratio \\ +\hspace*{.5cm} - 720{\texttimes}480/ 60i (SD-DV 4:3 og 16:9) \\ +\hspace*{.5cm} - 720{\texttimes}576/ 50i (SD-DV 4:3 og 16:9) \\ +{\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}) \\ +{\textbullet} 8 bit color depth 4:2:0 subsampling & 8 bit color depth 4:2:0 subsampling \\ +{\textbullet} 25 Mbps data rate after compression (20:1) & 19.4 Mbps data rate after compression \\ +{\textbullet} MP2/MPEG-1 Audio Layer II & MP2/MPEG-1 Audio Layer II \\ +{\textbullet} Stereo (2-ch), 384 kbps & Stereo (2-ch), 384 kbps \\ +{\textbullet} A/V out: HDMI, Component, S-video/RCA\ & A/V out: HDMI, Component, S-video/RCA \\ +{\textbullet} IEEE 1394 (MPEG-2-TS) stream interface & IEEE 1394 (MPEG-2-TS) stream interface \\ +{\textbullet} M2T file extension & M2T file extension +\end{tabular} + +\subsection{\textbf{AVCHD (2006-current)}}% +\label{sub:AVCHD} + +\begin{itemize} +\item AVCHD stands for \textit{Advanced Video Coding High Definition}, in particular, \textit{MPEG-4 Part 10: +AVC/H.264}. The intent of the H.264/AVC project was to create a standard capable of providing good video quality at +substantially lower bit rates than previous standards (i.e., half or less the bit rate of MPEG-2, H.263, or MPEG-4 Part +2). \\ +\item AVCHD is a file based format for digital camcorders to record and playback 1080i and 720p HD-video onto certain +random access media. Memory cards, thumb drives, and HDDs use the FAT file system. This highly compressed video allows for +recording long videos in high definition.\\ +\item AVCHD was originally a simplified version of the Blu-ray standard to enable DVD and BD-based camcorders. +Recordable optical discs use UDF or ISO9660 derived from the Blu-ray disc specification. For example, it utilizes a +legacy 8.3 file naming system while Blu-ray disc uses long filenames. \\ +\item MTS file extension changes to M2TS when MTS recorded data is transferred to the computer for storing the video in +a Blu-ray disc. \\ +\item Playback is possible on an AVCHD-compatible Blu-ray Disc player/recorder, DVD player/recorder, or PlayStation 3, +the 8 cm DVDs (discs recorded in AVCHD) you have recorded or DVDs (discs recorded in AVCHD) and Blu-ray Discs created +by importing videos to a PC or Blu-ray Disc player. \\ +\item Today AVCHD is the most popular camcorder format for consumers and prosumers, and is also available as AVCHD +Progressive/PCM models for professional use.\\ +\item AVCHD supports both \textit{AVCHD-SD Standard Definition} and \textit{AVCHD 1080i High Definition} interlaced +video, while AVCHD 1080i is available with most AVCHD camcorders. AVCHD supports 720-line progressive recording mode at +frame rates of 24 and 60 frames/s for 60 Hz models and 50 frames/s for 50 Hz models.\\ +\item Also, 3D (MVC format) and 1080/60p(1080/50p) video formats were added as an extension to the AVCHD format to +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.\\ +\end{itemize} +-------------------------------------- + +\begin{tabular}{ll} + \textbf{8\ cm DVD/Built-in/SD Memory/M-Stick: } & \textbf{Built-in media/SD Memory/Memory Stick:} \\ + + {\textbullet} 1920{\texttimes}1080/ 60i, 50i, 24p & 1920{\texttimes}1080/ 60p, 50p \\ + {\textbullet} 1440{\texttimes}1080/ 60i, 50i, 24p & 1440{\texttimes}1080/ 60p, 50p \\ + {\textbullet} 1280{\texttimes}720/ 60i, 50i, 24p & 1280{\texttimes}720/ 60p, 50p \\ + {\textbullet} 720{\texttimes}480/ 60i (SD 4:3 og 16:9) \\ + {\textbullet} 720{\texttimes}576/ 50i (SD 4:3 og 16:9) \\ + {\textbullet} 16:9 Display aspect ratio & 16:9 Display aspect ratio \\ + {\textbullet} MPEG-4 Part 10: AVC / H.264 & MPEG-4 Part 10: AVC / H.264 \\ + {\textbullet} 8 bit color depth 4:2:0 subsampling & 8 bit color depth 4:2:0 subsampling \\ + {\textbullet} {\textless}= 24 Mbps data rate & {\textless}= 28 Mbps data rate \\ + {\textbullet} {\textless}= 18 Mbps data rate for DVD \\ + {\textbullet} Dolby Digital AC-3\ \ , 64-640 kbps & Dolby Digital AC-3, 64-640 kbps \\ + \hspace*{.3cm} 2 ch stereo and 5.1 (5-ch + subw.) surround & \hspace*{.3cm} 1$\sim$ 5.1 channels \\ + {\textbullet} Linear PCM, 1.5 Mbps (2 ch) & Linear PCM, 1.5 Mbps (2 ch) \\ + \hspace*{.3cm}1$\sim$ 7.1 channels & \hspace*{.3cm} 1$\sim$ 7.1 channels \\ + {\textbullet} A/V out: HDMI, Component, S-video/RCA & A/V out: HDMI, Component, S-video/RCA \\ + {\textbullet} MPEG-2 Transport Stream & MPEG-2 Transport Stream \\ + {\textbullet} MTS file extension\ \ (recorded) & MTS file extension (recorded) \\ +\end{tabular} + +\subsection{\textbf{Blu-ray BD-Video (2006), UHD-video (2016)}}% +\label{sub:Blu-ray} + +All standard DVDs will play on existing Blu-ray players, making the switch to Blu-ray much easier than the switch +from VHS to DVD. Ultra HD Blu-ray is the latest version available, supporting 4K resolution content. Historically, +Blu-ray Disc allows video with a color (bit) depth of 8-bits per color YCbCr with 4:2:0 chroma subsampling (colors +compressed to 25\% of uncompressed), which means 256 possible values for red, green and blue; 16.7 million colors in +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 +total, or 64x more than 8-bit. + +BDMV Video encoding: +\begin{itemize}[noitemsep] +\item UDF2.5 as file system (BD-R/RE, 2005) +\item M2TS file extension +\item H.262/MPEG-2 Part 2 (\href{mailto:MP@HL}{MP@HL}, \href{mailto:MP@ML}{MP@ML}) +\item H.264/MPEG-4 AVC (\href{mailto:HP@L4.1}{HP@4.1}, \href{mailto:MP@L4.1}{MP@4.1}) +\item SMPTE VC-1 (\href{mailto:AP@L3}{AP@L3}) +\item H.265/H.265/MPEG-H Part 2 (HEVC) (only Ultra HD Blu-ray on High-density optical disc) +\end{itemize} + +BD Video movies have a maximum data transfer rate of 54 Mbit/s, a maximum AV bitrate of 48 Mbit/s (for both audio +and video data), and a maximum video bit rate of 40 Mbit/s., BD disc capacities, each with its own data rate: +\begin{itemize}[noitemsep] +\item 25 GB (BD-R SL) +\item 50, 66 GB (BD-R DL) at 72 or 92 Mbit/s (50 GB BD-R DL 4x read speed supports UHD-video) +\item 100 GB (TL), 128 GB (QL) at 92, 123, or 144 Mbit/s (BD-R XL) +\end{itemize} + +Supported video formats (shortened): + +\begin{tabular}{ l c c} +\textbf{Format} & \textbf{Resolution and frame rate} & \textbf{Display aspect ratio }\\ + +4K UHD & 3840x2160 60p, 50p & 16:9 \\ + & 3840x2160 25p, 24p & 16:9 \\ +\\ +HD & 1920x1080 60p, 50p & 16:9 \\ + & 1920x1080 25p, 24p & 16:9 \\ + & 1920x1080 29.97i, 25i & 16:9 \\ + & 1440x1080 29.97i, 25i & 16:9\\ +\\ +HD & 1440x1080 24p & 16:9\\ + & 1280x720 59.94p, 50p 1 & 16:9 \\ + & 1280x720 24p & 16:9 \\ +\\ +SD & 720x480 29.97i, 25i & 4:3 or 16:9\\ +\end{tabular} + +\chapter{How to digitize and capture analog video to digital SD video format with A/D video conversion}% +\label{cha:how_to} + +\section{Methods and workflow}% +\label{sec:methods} + +There are a number of ways to get analog source recorded video digitized and captured into the computer. +\begin{itemize} +\item One way is to use the passthrough feature of an available miniDV camcorder or the digital output of a Sony Digital 8 +camcorder to convert the Hi8 source to DV, which is then sent via firewire to the computer. +\item Another alternative might be a Linux supported external capture card to USB3 (often MPEG-4), or find a higher-end +internal PCIe analog video capture card to store uncompressed, 422 or DV video. +\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 +or optional to a high-end analog/SDI and a SSD 422 codec (i.e ProRes) recorder. +\end{itemize} +\hspace*{.9cm} An example workflow and setup for this third way: + +\small{Analog Hi8 \hspace*{.15cm} S-Video \hspace*{.8cm} S-Video} \\ + tape player ----------> TBC --------------> A/D-conv. \\ +\hspace*{8cm} $\backslash$ \_ DV/HDV HDD \hspace*{.5cm} Firewire \hspace*{.5cm} PC \\ +\hspace*{8.3cm} \_ rec/player ------------------------> DV/M2T \\ +\hspace*{6.4cm} Firewire \hspace*{.1cm}/ \\ +\hspace*{3.5cm} HDV tape player -----------> + +\begin{itemize} +\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: \\ +{\small \url{https://lists.cinelerra-gg.org/pipermail/cin/2021-October/003960.html}} \\ +{\small \url{https://lists.cinelerra-gg.org/pipermail/cin/2021-October/003970.html}} + +\end{itemize} + +{\small \texttt{S-Video Out -> A/D video converter -> HDMI/USB3 capture card}} + +\section{Equipment and setup}% +\label{sec:equipment} + +\begin{itemize} +\item The first required is a tape player device (VCR deck or camcorder) to playback the analog video tape cassette formats, +either VHS/ SVHS, VHS-C/ SVHS-C or Video8/ Hi8. Use a video head cleaning tape before use. Wind and rewind the tape +cassette before playback in Edit mode "ON" to minimize picture deterioration. \\ +\item A second recommended device for all capture methods is a Time Base Corrector (TBC). Connected to the analog output of +a VCR, a good TBC can make wonder and remove most or all of the flagging, shaky pictures, wavy lines, and other time +base problems from a videotape, to get a clearer and more steady picture. The best is a standalone, fullframe +high-resolution TBC of broadcast quality; minimum is a line-based TBC built in high-end VCR decks. \\ +\item A third, optional feature before digitizing is a noise filter to reduce/soften noise and grain (snow) from bad VHS tape +recordings, or also when video that is over-processed using sharpness controls and enhancers. Noise filter adjustment +may be part of the TBC setup and preview, or fixed built in the playback VCR. Optional a standalone Video +corrector/processor if available can be used, where also optional brightness, contrast and color saturation/correction +can be adjusted. +\end{itemize} + +\section{Example articles and references}% +\label{sec:example} + +\begin{itemize} +\item Digitizing Analog Video through a Digital Camcorder (Michael Steil, 2022) \\ +{\small \url{https://www.pagetable.com/?p=1697}} \\ +\item How to Get the Best Images Digitizing SD Video (TBC/ProRes, Larry Jordan, 2021) \\ +{\small \url{https://larryjordan.com/articles/how-to-get-the-best-images-digitizing-sd-video/}} \\ +\item Digitize analog cassettes (VHS or 8\ mm) with Linux (USB/H.264, Corinne HENIN, 2021) \\ +{\small \url{https://www.arsouyes.org/en/blog/2021/2021-05-17\_Numerisation\_VHS}} \\ +\item The Digitization of VHS Videotapes -- Technical Bulletin 31 -- Canada.ca (Joe Iraci, 2020) \\ +{\small \url{https://www.canada.ca/en/conservation-institute/services/conservation-preservation-publications/technical-bulletins/digitization-vhs-video-tapes.html}} \\ +\item Hi8 to DVD Workflow in Linux (Eric Olson, Renomath (2012) \\ +{\small \url{https://renomath.org/video/linux/hi8/}} \\ +\item Transfer VHS/DVD Media or Video8/Hi8 Tapes into CINELERRA-GG (chpt. 13.4 manual) \\ +{\small \url{https://cinelerra-gg.org/download/CinelerraGG\_Manual/Transfer\_VHS\_DVD\_Media\_or\_V.html}} +\end{itemize} + +\chapter{\textbf{DV files converted to Blu-ray compliant MPEG-2/LPCM and authored to SD BD-Video}}% +\label{cha:dv_files} + +\textbf{Step 1} + +\begin{itemize} +\item Prepare a 40 GB continuously DV input file by joining and concatenating the actual dv clips in order. Each +digitized Hi8 video tape was automatically split and recorded as a numbered series of 2.0 GB dv files each. \\ +\item Naming convention used, for example, for Tape \#1 with clips in order: \texttt{dv01, dv01-01, dv01\_02, dv01\_03}, +etc. For the full example at the end of this article, the concatenated \texttt{DV41\_02+DV42+DV43\_02} contains the clips from on + \texttt{dv41\_02+all dv42} up to and including \texttt{dv43\_02}. +\end{itemize} + +\textbf{Step 2} + +\begin{itemize} +\item Encode DV to MPEG-2 video and "re-encode" uncompressed PCM to Blu-ray PCM audio and +remux to interlaced SD-BD-video.mts: +\begin{lstlisting}[style=sh] +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 +\end{lstlisting} +\end{itemize} + +\textbf{Step 3} + +\begin{itemize} +\item Run \textbf{tsMuxer} (screenshot of tsMuxer usage is displayed at the end of this article). The following +parameters are shown for tsMuxer\_SD\_M2TS: \\ +\newline\hspace*{.5cm} Input file: \texttt{SD-BD\_DV41\_02+DV42+DV43\_02.mts} +\newline\hspace*{.5cm} Tracs:\hspace*{.63cm}\ MPEG-2 video stream and LPCM audio stream +\newline\hspace*{.5cm} Output:\hspace*{.37cm} \texttt{SD-BD\_DV41\_02+DV42+DV43\_02.iso} +\end{itemize} + +\textbf{Step 4} +\begin{itemize} +\item Burn the iso SD-BD-Video image with \textbf{xorriso} on a BD-R DL 50 GB disc: +\begin{lstlisting}[style=sh] +xorriso -as cdrecord -v -sao dev=/dev/sr1 SD-BD_DV41_02+DV42+DV43_02.iso +\end{lstlisting} +\end{itemize} + +\chapter{\textbf{HDV.m2t files converted and authored to HD BD-Video}}% +\label{cha:hdvm2t} + +\textbf{Step 1} +\begin{itemize} +\item Prepare the source HDV.m2t file using hdv clips as for DV above. +\end{itemize} + +\textbf{Step 2} +\begin{itemize} +\item Copying the mpeg2 video, re-encoding MP2 audio to Blu-ray LPCM. If using an ffmpeg version lower than 5.1, +substitute ac3 for pcm\_bluray and add -b:a 384 to override lower default. + +\begin{lstlisting}[style=sh] +ffmpeg -i HDV.m2t -c:v copy -c:a pcm_bluray -mpegts_m2ts_mode 1 HDV.mts +\end{lstlisting} +\end{itemize} + +\textbf{Step 3} +\begin{itemize} +\item Run \textbf{tsMuxer} (screenshot of tsMuxer usage is displayed at the end of this article). +\newline\hspace*{.5cm} Input file: \texttt{HD-BD\_HDV.mts} +\newline\hspace*{.5cm} Tracs: \hspace*{.5cm} MPEG-2 video stream and LPCM audio stream +\newline\hspace*{.5cm} Output: \hspace*{.25cm} \texttt{HD-BD\_HDV.iso} +\end{itemize} + +\textbf{Step 4} +\begin{itemize} +\item Burn the iso HD-BD-Video image with \textbf{xorriso} on a BD-R DL 50 GB disc: +\begin{lstlisting}[style=sh] + xorriso -as cdrecord -v -sao dev=/dev/sr1 HD-BD_HDV.iso +\end{lstlisting} +\end{itemize} + +\chapter{\textbf{Full example output}}% +\label{cha:full} + +\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 +DL}% +\label{sec:DVFILES} + +17/01-2023 \\ +SD-BD\_DV41\_02+DV42+DV43\_02 \\ +----------------------------------------------- + +\textbf{Step 1} +\begin{lstlisting}[style=sh] +cd /run/media/terje/Seagate_8TB_back/video/DV + +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 +\end{lstlisting} + +-------------------------------------- +\begin{lstlisting}[style=sh] +cd /home/terje/Videoklipp/SD-BD-DV-iso + +du -sh DV* +40G DV41_02+DV42+DV43_02.dv +\end{lstlisting} +------------------------------------------------ + +\textbf{Step 2} +\begin{lstlisting}[style=sh] +cd /home_lp154/terje/Videoklipp/SD-BD-DV-iso + +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 + +ffmpeg version 5.1.2 Copyright (c) 2000-2022 the FFmpeg developers + built with gcc 12 (SUSE Linux) +............................. + +(NOTE: the @ sign represents the pound sign in the next 21 lines) + +Input @0, dv, from 'DV41_02+DV42+DV43_02.dv': + Metadata: + timecode : 00:19:52:24 + Duration: 03:15:53.28, start: 0.000000, bitrate: 28800 kb/s + Stream @0:0: Video: dvvideo, yuv420p, 720x576 [SAR 16:15 DAR 4:3], 25000 kb/s, 25 fps, 25 tbr, 25 tbn + Stream @0:1: Audio: pcm_s16le, 48000 Hz, stereo, s16, 1536 kb/s +Stream mapping: + Stream @0:0 -> @0:0 (dvvideo (native) -> mpeg2video (native)) + Stream @0:1 -> @0:1 (pcm_s16le (native) -> pcm_bluray (native)) +Press [q] to stop, [?] for help +[mpeg2video @ 0x558bb9453ac0] Warning vbv_delay will be set to 0xFFFF (=VBR) as the specified vbv buffer is too large for the given bitrate! +Output @0, mpegts, to 'SD-BD_DV41_02+DV42+DV43_02.mts': + Metadata: + timecode : 00:19:52:24 + encoder : Lavf59.27.100 + 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 + Metadata: + encoder : Lavc59.37.100 mpeg2video + Side data: + cpb: bitrate max/min/avg: 25000000/25000000/25000000 buffer size: 28000000 vbv_delay: N/A + Stream @0:1: Audio: pcm_bluray, 48000 Hz, stereo, s16, 128 kb/s + Metadata: + encoder : Lavc59.37.100 pcm_bluray +frame=293832 fps=373 q=2.5 Lsize=41027202kB time=03:15:53.28 bitrate=28595.8kbits/s speed=14.9x +video:35867310kB audio:2212922kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 7.738845% + +-------------------------------------- +du -sh *.mts +40G SD-BD_DV41_02+DV42+DV43_02.mts +\end{lstlisting} +-------------------------------------- + +\textbf{Step 3} +\begin{itemize} +\item Run \textbf{tsMuxer} (screenshots of tsMuxer usage are displayed at the end of this article). +\newline\hspace*{.5cm} Input file: \texttt{HD-BD\_HDV.mts} +\newline\hspace*{.5cm} Tracs: \hspace*{.5cm} MPEG-2 video stream and LPCM audio stream +\newline\hspace*{.5cm} Output: \hspace*{.2cm} \texttt{HD-BD\_HDV.iso} +\end{itemize} + +-------------------------------- +\begin{lstlisting}[style=sh] +du -sh *.iso +39G SD-BD_DV41_02+DV42+DV43_02.iso +\end{lstlisting} +-------------------------------------- + +\textbf{Step 4} +\begin{lstlisting}[style=sh,escapechar=\^] +MediaRange BD-R DL + +eject /dev/sr1 +eject -t /dev/sr1 + +umount /dev/sr1 +umount: /dev/sr1: not mounted. +-------------------------------------- + +xorriso -devices +xorriso 1.5.4 : RockRidge filesystem manipulator, libburnia project. + +Beginning to scan for devices ... +Full drive scan done +-------------------------------------- +0 -dev '/dev/sr0' rwrw-- : 'HL-DT-ST' 'BD-RE BH10LS30' +1 -dev '/dev/sr1' rwrw-- : 'ASUS ' 'BW-16D1X-U' +-------------------------------------- + +Device og media info for a new BD-R DL (MediaRange): +-------------------------------------- +xorrecord -dev=/dev/sr1 -atip +xorriso 1.5.4 : RockRidge filesystem manipulator, libburnia project. + +Drive current: -outdev '/dev/sr1' +Media current: BD-R sequential recording +Media status : is blank +Media summary: 0 sessions, 0 data blocks, 0 data, 46.6g free +Device type : Removable CD-ROM +Vendor_info : 'ASUS' +Identifikation : 'BW-16D1X-U' +Revision : 'A105' +Driver flags : BURNFREE +Supported modes: SAO TAO +Current: BD-R sequential recording +Profile: 0x0043 (BD-RE) +Profile: 0x0042 (BD-R random recording) +Profile: 0x0041 (BD-R sequential recording) (current) +Profile: 0x0040 (BD-ROM) +Profile: 0x002B (DVD+R/DL) +Profile: 0x001B (DVD+R) +Profile: 0x001A (DVD+RW) +Profile: 0x0016 (DVD-R/DL layer jump recording) +Profile: 0x0015 (DVD-R/DL sequential recording) +Profile: 0x0014 (DVD-RW sequential recording) +Profile: 0x0013 (DVD-RW restricted overwrite) +Profile: 0x0012 (DVD-RAM) +Profile: 0x0011 (DVD-R sequential recording) +Profile: 0x0010 (DVD-ROM) +Profile: 0x000A (CD-RW) +Profile: 0x0009 (CD-R) +Profile: 0x0008 (CD-ROM) +Profile: 0x0002 (Removable disk) +Mounted Media: 41h, BD-R sequential recording +Product Id: CMCMAG/DI6/0 +Producer: CMC Magnetics Corporation +Manufacturer: 'CMCMAG' +Media type: 'DI6' +-------------------------------------- +\end{lstlisting} + +\underline{Burning the 40 GB SD-BD-Video iso image to a BD-R DL disc:} + +\begin{lstlisting}[style=sh] +27 min + +xorriso -as cdrecord -v -sao dev=/dev/sr1 SD-BD_DV41_02+DV42+DV43_02.iso + +xorriso 1.5.4 : RockRidge filesystem manipulator, libburnia project. +Drive current: -outdev '/dev/sr1' +Media current: BD-R sequential recording +Media status : is blank +Media summary: 0 sessions, 0 data blocks, 0 data, 46.6g free +Beginning to write data track. +........... +xorriso : UPDATE : 39219 of 39251 MB written (fifo 71%) [buf 100%] 6.1x. +xorriso : UPDATE : 39245 of 39251 MB written (fifo 80%) [buf 100%] 6.1x. +xorriso : UPDATE : 39251 of 39251 MB written (fifo 0%) [buf 100%] 1.5x. +xorriso : UPDATE : 39251 of 39251 MB written (fifo 0%) [buf 100%] 0.0x. +xorriso : UPDATE : Closing track/session. Working since 1587 seconds +xorriso : UPDATE : Closing track/session. Working since 1588 seconds +.......... +xorriso : UPDATE : Closing track/session. Working since 1627 seconds +Writing to '/dev/sr1' completed successfully. + +xorriso : NOTE : Re-assessing -outdev '/dev/sr1' +xorriso : NOTE : Disc status unsuitable for writing +Drive current: -outdev '/dev/sr1' +Media current: BD-ROM +Media status : is written , is closed +Media summary: 1 session, 20096864 data blocks, 38.3g data, 0 free +\end{lstlisting} + +\begin{figure}[htpb] +\centering +\includegraphics[width=15.132cm,height=9.823cm]{Preserving.png} +\end{figure} diff --git a/parts/Preserving_title.tex b/parts/Preserving_title.tex new file mode 100644 index 0000000..38e2bee --- /dev/null +++ b/parts/Preserving_title.tex @@ -0,0 +1,55 @@ +% ================================================================ +% 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: diff --git a/parts/Quickstart.tex b/parts/Quickstart.tex index 5e74fee..aec2992 100644 --- a/parts/Quickstart.tex +++ b/parts/Quickstart.tex @@ -41,18 +41,23 @@ Depending on how you installed the software, you can log in as root or as a user \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} @@ -60,7 +65,7 @@ On the main timeline program window are many pulldowns, the first of which is \t \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} @@ -106,7 +111,7 @@ You can skip this step if you want the format of your output to be the same as y \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} @@ -126,8 +131,8 @@ You can skip this step if you want the format of your output to be the same as y \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}% @@ -136,13 +141,13 @@ You can skip this step if you want the format of your output to be the same as y \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 @@ -152,6 +157,11 @@ You can skip this step if you want the format of your output to be the same as y 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} @@ -160,7 +170,7 @@ There may be sections of your media that you want to delete, or audio that is ha \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} @@ -193,7 +203,7 @@ There may be sections of your media that you want to delete, or audio that is ha 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. @@ -266,3 +276,319 @@ At this time, or even earlier if you think you might make a mistake or if you ar \label{sub:play_your_new_media} 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{Overview on Formats and Codecs}% +\label{sec:overview_formats} +\index{format} +\index{codec} + +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. + +\subsection{Video FFmpeg Formats}% +\label{sec:FFmpeg_video} + +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. + +\subsubsection{High Quality} +\label{ssub:ffmpeg_video_high_quality} + +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{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} + +Not having \CGG{} a CMS, it becomes essential to have a monitor calibrated and set in sRGB that is just the output displayed on the timeline of the program. You have these cases: + +\begin{center} + \begin{tabular}{|l|l|p{8cm}|} + \hline + \textbf{Timeline} & \textbf{Display} & \textbf{Description} \\ + \hline + sRGB & sRGB & we get a correct color reproduction \\ + sRGB & Rec.709 & we get slightly dark colors, because gamma \\ + sRGB & DCI-P3 & we get over-saturated dark colors, because gamma and bigger gamut \\ + \hline + \end{tabular} +\end{center} + +\subsection{Pipeline CMS}% +\label{sub:pipeline_cms} + +INPUT $\rightarrow$ DECODING/PROCESSING $\rightarrow$ OUTPUT/PLAYBACK $\rightarrow$ DISPLAY $\rightarrow$ ENCODING + +\begin{description} + \item[Input] color space and color depth of the source file; better if combined with an ICC profile. + \item[Decoding] how \CGG{} transforms and uses the input file (it is a temporary transformation, for usage of the internal/ffmpeg engine and plugins). + \item[Output] our setting of the project for the output. In \CGG{} such a signal is \texttt{8-bit sRGB}, but it can also be 8-bit YUV in \textit{continuous playback}. + \item[Display] as the monitor equipped with its color space (and profiled with ICC or LUT) displays the signal that reaches the user and what we see. The signal reaching the display is also mediated by the graphics card and the operating system CMS, if any. + \item[Encoding] the final rendering stage where we set not only formats and codecs but also color space, color depth, and color range. +\end{description} + +\subsection{How \CGG{} works}% +\label{sub:how_cingg_works} + +\begin{description} + \item[Decoding/playback:] Video is decoded to internal representation (look at \texttt{Settings /Format/Color model}). Internal format is unpacked as 3 color values + one alpha value every pixel. \CGG{} has 6 internal pixel formats (RGB(A) 8-bit; YUV(A) 8-bit and RGB(A)\_FLOAT 32-bit (see Color Model in \nameref{sec:video_attributes}). The program will configure the frame buffer for your resulting video to be able to hold data in that color model. Then, for each plugin, it will pick the variant of the algorithm coded for that model. + \CGG{} automatically converts the source file to the set color model (in a buffer, the original is not touched!). Even if the input color model matches what we set in \texttt{Settings/Format/Color model}, there will always be a first conversion because \CGG{} works internally (in the buffer) at 32-bit in RGB. For playback \CGG{} has to convert each frame to the format acceptable by the output device, i.e. sRGB 8-bit. In practice, the decoded file follows two separate paths: conversion to FLOAT for all internal calculations in the temporary (including other conversions for plugins, etc.) and simultaneously the result in the temporary is converted to 8-bit sRGB for on-screen display. See also \nameref{sec:conform_the_project}. To review, a \textit{temporary} is a single frame of +video in memory where graphics processing takes place. +\CGG{} use X11 and X11 is RGB only and it is used to draw the \textit{refresh frame}. So single step is always drawn in RGB. Continuous playback on the other hand can also be YUV for efficiency reasons. + \item[Color range:] One problem with the YUV color model is the \texttt{YUV color range}. This can create a visible effect of a switch in color in the Compositor, usually shown as grayish versus over-bright. The cause of the issue is that X11 is RGB only and it is used to draw the \textit{refresh frame}. So single step is always drawn in RGB. To make a YUV frame into RGB, a color model transfer function is used. The math equations are based on Color\_space and Color\_range. In this case, color\_range is the cause of the \textit{grayish} offset. The \textit{YUV MPEG color range} (limited or TV) is 16..235 for \textbf{Y}, 16..240 for \textbf{UV}, and the color range used by \textit{YUV JPEG color range} (full or HDTV) is 0 to 255. The cause is that 16-16-16 is seen as pure black in MPEG, but as gray in JPEG and all playback will come out brighter and more grayish. This can be fixed by forcing appropriate conversions via the ColorSpace plugin. See \nameref{sec:color_space_range_playback} + \item[Plugins:] On the timeline all plugins see the frames only in internal pixel format and modify this as needed (\textit{temporary}). Some effects work differently depending on colorspace: sometimes pixel values are converted to float, sometimes to 8-bit for an effect. In addition \textit{playback single step} and \textit{plugins} cause the render to be in the session color model, while \textit{continuous playback} with no plugins tries to use the file’s best color model for the display (for speed). As mentioned, each plugin we add converts and uses the color information in its own way. Some limit the gamut and depth of color by clipping (i.e. \texttt{Histogram}); others convert and reconvert color spaces for their convenience; others introduce artifacts and posterization; etc. For example, the \texttt{Chroma Key (HSV)} plugin converts any signal to HSV for its operation. + If we want to better control and target this color management in \CGG{}, we can take advantage of its internal ffmpeg engine: there is an optional feature that can be used via \texttt{.opts} lines from the ffmpeg decoded files. This is via the \texttt{video\_filter=colormatrix=...}ffmpeg plugin. There may be other good plugins (lut3d...) that can also accomplish a desired color transform. This \texttt{.opts} feature affects the file colorspace on a file by file basis, although in principle it should be possible to setup a \texttt{histogram} plugin or any of the \texttt{F\_lut*} plugins to remap the colortable, either by table or interpolation. + \item[Conversion:] Any conversion is done with approximate mathematical calculations and always involves a loss of data, more or less visible, because you always have to interpolate an exact value when mapping it into the other color space. Obviously, when we use floating point numbers to represent values, these losses become small and close to negligible. So the choice comes down to either keeping the source color model even while processing or else converting to FLOAT, which in addition to leading to fewer errors should also minimize the number of conversions, being congruous with the program's internal one. The use of FLOAT, however, takes more system resources than the streamlined YUV. Color conversions are mathematical operations; for example to make a YUV frame into RGB, a color model matrix function is used. The math equations are based on color\_space and color\_range. Since the majority of sources are YUV, this conversion is very common and it is important to set these parameters to optimize playback speed and correct color representation. + \item[Encoding:] Finally, the encoding converts to colorspace required by the codec. +\end{description} + +\subsection{Workflow}% +\label{sub:workflow} + +Let us give an example of color workflow in \CGG{}. We start with a source of type YUV (probably: YCbCr); this is decoded and converted to the chosen color model for the project, resulting in a \textit{temporary}. Various jobs and conversions are done in FLOAT math and the result remains in the chosen color model until further action. In addition, the temporary is always converted to sRGB 8-bit for monitor display only. If we apply the \texttt{ChromaKey (HSV)} plugin, the temporary is converted to HSV (in FLOAT math) and the result in the temporary becomes HSV. If we do other jobs the temporary is again converted to the set color model (or others if there is demand) to perform the other actions. At the end of all jobs, the obtained temporary will be the basis of the rendering that will be implemented according to the choice of codecs in the render window (\textit{Wrench}), regardless of the color model set in the project. If we have worked well the final temporary will retain as much of the source color data as possible and will be a good basis for encoding of whatever type it is. + +For practical guidelines, one can imagine starting with a quality file, for example, \textit{10-bit YUV 4.2.2}. You set the project to \texttt{RGBA-FLOAT}; the \texttt{YUV color space} to your choice of Rec709 (for a FullHD) or BT 2020NCL (for UHD) and finally the \texttt{YUV color range} to JPEG. If the original file has the MPEG type color range then you convert to JPEG with the \texttt{ColorSpace} plugin. If you want to transcode to a quality intermediate you can use \textit{DNxHR 422}, or even \textit{444}, and maybe do the editing step with a \textit{proxy}. For rendering you choose the codec appropriate for the file destination, but you can still generate a high-quality master, for example \textit{ffv1 .mov} with lossless compression. + +\begin{figure}[htpb] + \centering + \includegraphics[width=1.0\linewidth]{color_01.png} + \caption{Color settings (Settings $\rightarrow$ Format / Settings $\rightarrow$ Preferences)} + \label{fig:color_01} +\end{figure} diff --git a/parts/Real-World.tex b/parts/Real-World.tex index c89d219..9183bc1 100644 --- a/parts/Real-World.tex +++ b/parts/Real-World.tex @@ -178,7 +178,7 @@ Let's take the case of a professional magician filmed in multicam while performi You can find the files to test the workflow that is described next at the following address: %begin{latexonly} -\small{\url{https://cinelerra-gg.org/download/testing/cinelerra-forum.zip}} +\url{https://cinelerra-gg.org/download/testing/cinelerra-Manual-reference.zip} %end{latexonly} \begin{htmlonly} \url{https://cinelerra-gg.org/download/testing/cinelerra-forum.zip} @@ -205,7 +205,7 @@ Start \CGG{} to create an empty video track and two audio tracks (default). If y \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. @@ -224,3 +224,107 @@ To render, do not forget to uncheck the P (proxy) button in the main program win \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} diff --git a/parts/Recording.tex b/parts/Recording.tex index 9d31516..8a67cc8 100644 --- a/parts/Recording.tex +++ b/parts/Recording.tex @@ -17,6 +17,7 @@ Access the Record function via \texttt{File} $\rightarrow$ \texttt{Record}\dots \vspace{2ex} \begin{tabular}{lll} + \hline Path: & output media file path & \\ Start time: & weekday/time of day & to begin capture\\ @@ -27,7 +28,8 @@ Access the Record function via \texttt{File} $\rightarrow$ \texttt{Record}\dots \multirow{2}*{Mode:} & timed & use start time/duration \\ - & untimed & use transport controls\\ + & untimed & use transport controls\\ + \hline \end{tabular} \vspace{2ex} @@ -37,7 +39,7 @@ The media file will be written using the format and codec specified in the \text \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}. @@ -127,10 +129,10 @@ The algorithm for determining how many frames to drop is as follows: \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. @@ -141,10 +143,10 @@ You can select synchronization time source \textit{Positioning} in: \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}. @@ -177,6 +179,9 @@ One other noted new feature is a new choice for recording - \texttt{V4L2 MPEG}. \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} @@ -448,8 +453,8 @@ Figure~\ref{fig:two-monitors04} shows 2 monitors with Compositor window on the 2 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\\ @@ -489,13 +494,13 @@ Remote Control Keys (Application/Menu key toggle for ati-x10 remote) 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\\ @@ -511,7 +516,7 @@ Remote Control Keys (Application/Menu key toggle for ati-x10 remote) square&=&stop\\ 2 lines&=&fast reverse\\ - \bottomrule + \hline \end{tabular} The Application/Menu key \quad @@ -745,8 +750,6 @@ Output from "dmesg" for EasyCap - Model \# DC60: [ 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} diff --git a/parts/Rendering.tex b/parts/Rendering.tex index 3de25a9..e221c57 100644 --- a/parts/Rendering.tex +++ b/parts/Rendering.tex @@ -2,7 +2,7 @@ \label{cha:rendering} \index{rendering} -Rendering takes a section of the timeline \index{active region}, 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 @@ -13,7 +13,8 @@ in/out points are set, the affected region is rendered. When no 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} @@ -110,7 +111,9 @@ Use the \textit{File} pulldown and select Render to start the render dialog 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:] \index{insertion strategy} select an insertion mode from the @@ -172,7 +175,9 @@ all parameter configurations. 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. + 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 @@ -183,7 +188,7 @@ errors when the other provided parameters conflict with the 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} +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} @@ -213,6 +218,8 @@ 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} @@ -506,10 +513,12 @@ There are currently 6 specific variations within the ffmpeg (file format) / yout The first 3 below, plus any of the VP9 files under the file type of \textit{webm} are the recommended options to use because they are freely usable in any circumstance. \begin{center} - \begin{tabular}{l p{8cm}} + \begin{tabular}{lp{8cm}} + \hline sd.youtube & Standard Definition use with default audio/Opus stereo.youtube \\ hd.youtube & High Definition “ “ \\ uhd.youtube & Ultra High Definition “ “ \\ + \hline \end{tabular} \end{center} @@ -518,10 +527,12 @@ For more details and options on VP9, see: {\small\url{https://developers.google. Alternatives based on h264 and for non-commercial use are listed below. For Dailymotion, these must be renamed to have a different extension of .mp4 instead of .youtube before uploading. \begin{center} - \begin{tabular}{l p{8cm}} + \begin{tabular}{lp{8cm}} + \hline sd\_h264.youtube & Standard Definition – must change to audio stereo\_with\_h264.youtube \\ hd\_h264.youtube & High Definition - “ “ \\ uhd\_u264.youtube & Ultra High Definition - “ “ \\ + \hline \end{tabular} \end{center} @@ -559,11 +570,13 @@ Bitrate (bit rate) \textit{mode:} -\begin{tabular}{p{6cm} p{10cm}} +\begin{tabular}{p{6cm}p{10cm}} + \hline Constant Quantizer (Q) & Allows you to specify a fixed quantizer value; bitrate will vary \\ Constrained Quality (CQ) & Allows you to set a maximum quality level. Quality may vary within bitrate parameters\\ Variable Bitrate (VBR) & Balances quality and bitrate over time within constraints on bitrate\\ Constant Bitrate (CBR) & Attempts to keep the bitrate fairly constant while quality varies\\ + \hline \end{tabular} CQ mode is recommended for file-based video (as opposed to streaming). The following FFMpeg command-line parameters are used for CQ mode: @@ -571,11 +584,13 @@ CQ mode is recommended for file-based video (as opposed to streaming). The follo \textit{FFMpeg}: \begin{center} - \begin{tabular}{{p{4cm} p{10cm}}} + \begin{tabular}{p{4cm}p{10cm}} + \hline -b:v & Sets target bitrate (e.g. 500k)\\ -minrate & Sets minimum bitrate.\\ -maxrate & Sets maximum bitrate.\\ -crf & sets maximum quality level. Valid values are 0-63, lower numbers are higher quality.\\ + \hline \end{tabular} \end{center} @@ -671,15 +686,50 @@ video/audio wrenches and choose \textit{faststart\_h264}. With the 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}). +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} @@ -783,7 +833,8 @@ mistakes. These are described next. \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. + 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 @@ -805,23 +856,37 @@ render dialog whether or not anything is being rendered, by hitting 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 \textit{Save Jobs} and choose a file -to save your batch render list to. Once you have created this 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. +\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} \subsection{Advanced features}% \label{sub:advanced_features} \index{batch rendering!more options} -\textbf{Warning}: one of these advanced functions overwrites the original EDL, which will then be lost! +\textbf{Warning}: \textit{Save to EDL path} overwrites the current EDL thus destroying the original contents. 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. @@ -908,14 +973,16 @@ 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 +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\@. +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: @@ -941,7 +1008,9 @@ the \texttt{Preferences} window. It has one interactive function 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} @@ -979,12 +1048,28 @@ rates (figure~\ref{fig:back-ren}). 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} @@ -994,14 +1079,13 @@ 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 @@ -1016,6 +1100,7 @@ script. 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$ @@ -1026,35 +1111,40 @@ communication, shared filesystem, permissions and usernames synched. \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. @@ -1068,7 +1158,7 @@ cin -d 407 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}% @@ -1105,7 +1195,7 @@ Below we describe the Performance tab for configuring a render 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. @@ -1319,12 +1409,6 @@ RenderFarmClient::main_loop: Session started from 127.0.0.1 \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 @@ -1353,13 +1437,26 @@ done \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 @@ -1386,7 +1483,7 @@ want to bother setting up NFS for a shared disk. 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} @@ -1404,13 +1501,13 @@ want to bother setting up NFS for a shared disk. /{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} @@ -1421,10 +1518,10 @@ want to bother setting up NFS for a shared disk. 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 @@ -1459,7 +1556,7 @@ 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\#}. @@ -1489,7 +1586,7 @@ list of items to check. 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 diff --git a/parts/Shortcuts.tex b/parts/Shortcuts.tex index 617495d..9d1e264 100644 --- a/parts/Shortcuts.tex +++ b/parts/Shortcuts.tex @@ -20,7 +20,13 @@ 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. +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}). + + \section{Main window }% \label{sec:main_window} @@ -53,7 +59,7 @@ The Main window (also called the program window) consists of pulldown menus, but & 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. \\ @@ -335,6 +341,7 @@ The Main window (also called the program window) consists of pulldown menus, but & 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. \\ @@ -353,7 +360,7 @@ The Main window (also called the program window) consists of pulldown menus, but \end{longtable} -\section{Compositor window}% +\section{Compositor window shortcuts}% \label{sec:compositor_window_shortcuts} \index{shortcuts!compositor window} @@ -450,7 +457,7 @@ The Main window (also called the program window) consists of pulldown menus, but \end{longtable} -\section{Viewer window }% +\section{Viewer window shortcuts }% \label{sec:viewer_window_shortcuts} \index{shortcuts!viewer window} @@ -668,3 +675,148 @@ The Main window (also called the program window) consists of pulldown menus, but \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} diff --git a/parts/Stuff.tex b/parts/Stuff.tex index da8b241..bef47f4 100644 --- a/parts/Stuff.tex +++ b/parts/Stuff.tex @@ -15,8 +15,8 @@ There are 3 types of copy/cut and paste methods which exist in X windows, and mo \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. @@ -166,6 +166,25 @@ There is now program code to look for RGB versus YUV color model mismatches. Yo \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} @@ -210,6 +229,8 @@ There are currently 2 actions implemented: 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} diff --git a/parts/Tips.tex b/parts/Tips.tex index 7d4ecce..5b95186 100644 --- a/parts/Tips.tex +++ b/parts/Tips.tex @@ -9,11 +9,11 @@ in \texttt{Settings $\rightarrow$ Preferences, Playback A} tab, the frames/secon 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. @@ -32,6 +32,15 @@ VDPAU, Video Decode and Presentation API for Unix, is an open source library to 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. @@ -61,6 +70,13 @@ or 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 @@ -76,7 +92,7 @@ Precedence of the decode hardware acceleration settings are: \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} @@ -94,7 +110,16 @@ There are 4 phases during \CGG{}’s handling of hardware acceleration. These fi 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}% @@ -165,7 +190,7 @@ or HEVC with NVIDIA, VDPAU driver is buggy, skipping \end{lstlisting} -If you would like to see more information on what is occurring, you can modify in the \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 @@ -417,7 +442,7 @@ An error you may see on your \CGG{} startup window when you have Cuda installed \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: @@ -437,19 +462,19 @@ With the X11 video driver choice, large format files such as 4K, will playback f \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} @@ -460,7 +485,7 @@ A list of items to check for smaller computers that will help to use less cpu/me \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. @@ -562,13 +587,13 @@ A LUT, acronym for Look-Up Table, is a mathematically precise way of taking spec \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} @@ -628,9 +653,9 @@ Interlacing often exists on older video sources, such as camcorders, and was pre \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} @@ -736,3 +761,58 @@ Another way to change duration slightly is to go to the Resources window, highli 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). + diff --git a/parts/Transition.tex b/parts/Transition.tex index 67ba7b5..7efb1b1 100644 --- a/parts/Transition.tex +++ b/parts/Transition.tex @@ -109,9 +109,9 @@ Video switches segments via a small rectangular view that gradually grows to ful 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} \\ @@ -128,16 +128,15 @@ Wipe a specific shape across the video. Currently available 63 shapes are: \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}). @@ -149,14 +148,16 @@ Next, there is a \textit{Feather} textbox with tumbler arrows or a slider bar to \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/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} diff --git a/parts/Translations.tex b/parts/Translations.tex index 3354581..4f2b921 100644 --- a/parts/Translations.tex +++ b/parts/Translations.tex @@ -11,7 +11,7 @@ of updates, and date of last update as of this writing. 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 October\\ + 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\\ @@ -21,7 +21,8 @@ of updates, and date of last update as of this writing. \\ 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 \\ diff --git a/parts/Trouble.tex b/parts/Trouble.tex index 2ff131a..810ab73 100644 --- a/parts/Trouble.tex +++ b/parts/Trouble.tex @@ -1,6 +1,93 @@ \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} @@ -8,22 +95,28 @@ You can report potential problems, bugs, and crashes to the \CGG{} website at: \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{/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 @@ -38,7 +131,7 @@ Basically we\textbf{ need to see what you see }with the input, output, and sessi \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. @@ -103,7 +196,7 @@ 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 @@ -118,7 +211,7 @@ is all that is needed to repair a media problem. \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. @@ -129,7 +222,54 @@ Set them to more reasonable values until you see the lines appear. Just as a rem 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} @@ -138,7 +278,7 @@ On the \textit{File} pulldown, there is a \textit{Dumps} option with a submenu o the text results will be shown in that window. \begin{itemize}[nosep] -\item \textit{Dump EDL} \index{EDL dump} 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 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. @@ -161,6 +301,16 @@ This is not a problem. Basically, when you open a file if a stream has a known d 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: @@ -168,7 +318,7 @@ This indicates that there is something wrong with the audio. Some reasons for th \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 @@ -183,8 +333,8 @@ There can be various reasons that \CGG{} does not come up. Some of the recent re \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} @@ -193,7 +343,7 @@ There can be various reasons that \CGG{} does not come up. Some of the recent re 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] @@ -208,6 +358,35 @@ You can usually install the required library to fix the problem. A temporary fix 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:} @@ -227,12 +406,12 @@ main000(); 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} @@ -310,6 +489,7 @@ There are some Help features currently included in the Shell Cmds menu. Those av \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}% diff --git a/parts/Windows.tex b/parts/Windows.tex index 8ae755d..5c8c0ae 100644 --- a/parts/Windows.tex +++ b/parts/Windows.tex @@ -10,18 +10,22 @@ \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} \index{timeline}. Here is where you enter the main menu operations. +The main window is called the \textit{Program} window and is often just referred to as the \textit{timeline}\index{timeline}. Here is where you enter the main menu operations. This timeline consists of a vertical stack of tracks with time represented horizontally on the track. It is the output of the rendering operations and this is what is saved when you run the \textit{File} pulldown, Save command. -Immediately to the left of the timeline is the patchbay \index{patchbay}. The patchbay contains options that affect each track. +Immediately to the left of the timeline is the patchbay\index{patchbay}. The patchbay contains options that affect each track. These options are described in great detail in \nameref{sec:patchbay}. The \textit{Window} pulldown on the main window contains options @@ -80,7 +84,7 @@ Each of the symbols has an associated tooltip as an easy reminder of its functio several is described in a little more detail in other areas of this manual. \vspace{2ex} -\begin{tabular}{ll} +\begin{longtable}{ll} \hline First set of 3 symbols & Move in the reverse direction on the timeline \\ 4th symbol & Stop play \\ @@ -101,7 +105,7 @@ several is described in a little more detail in other areas of this manual. Set Timecode & Explained in \ref{sub:align_timecodes} \\ Gang Modes & Explained in \ref{sub:displaying_tracks_ganged} \\ \hline -\end{tabular} +\end{longtable} The \textit{Manual Go To} \index{goto} menu is quite versatile as you can see in figure~\ref{fig:goto_menu}. The options of \textit{=} represents goto the position indicated in the textbox; \textit{+} indicates @@ -248,30 +252,6 @@ For best results, \textit{Align cursor on frames} \index{Align cursor on frames} 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} @@ -282,9 +262,31 @@ There are 2 different editing modes for operations which affect how the insertio on the timeline operate. There is: \emph{drag and drop mode} and \emph{cut and paste mode}. The editing mode is determined by selecting the \texttt{arrow} \index{arrow}, or immediately to the right of the arrow, -the \texttt{I-beam} \index{i-beam} in the Transport and Buttons bar. In figure~\ref{fig:insertion-points} you can see -the green colored highlight \protect\footnote{green is used in the default Cakewalk theme, but the highlight color will be different in other themes} on the arrow icon indicating that you are currently in -\emph{drag and drop mode}. +the \texttt{I-beam} \index{i-beam} in the Transport and Buttons bar. In figure~\ref{fig:insertion-points} you can see the green colored highlight \protect\footnote{green is used in the default Cakewalk theme, but the highlight color will be different in other themes} on the arrow icon indicating that you are currently in \emph{drag and drop mode}. + +\begin{figure}[htpb] + \centering + %\includegraphics[width=0.8\linewidth]{name.ext} + \begin{tikzpicture}[scale=1, transform shape] + \node (img1) [yshift=0cm, xshift=0cm, rotate=0] + {\includegraphics[width=0.6\linewidth]{insertion-point.png}}; + \node [yshift=-5mm, xshift=-1cm,anchor=east] at (img1.north west) (Pulldowns) {Pulldowns}; + \node [yshift=-10mm, xshift=-1cm,anchor=east] at (img1.north west) (Transport) {Transport \& Buttons Bar}; + \node [yshift=-15mm, xshift=-1cm,anchor=east] at (img1.north west) (Timebar) {Timebar}; + \node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Title) {Media Title }; + \node [yshift=-28mm, xshift=-1cm,anchor=east] at (img1.north west) (Video) {Video Track}; + \node [yshift=-46mm, xshift=-1cm,anchor=east] at (img1.north west) (Audio) {Audio Track}; + \draw [->, line width=1mm] (Pulldowns) edge ([yshift=-5mm] img1.north west); + \draw [->, line width=1mm] (Transport) edge ([yshift=-10mm] img1.north west); + \draw [->, line width=1mm] (Timebar) edge ([yshift=-15mm] img1.north west); + \draw [->, line width=1mm] (Title) edge ([yshift=-20mm] img1.north west); + \draw [->, line width=1mm] (Video) edge ([yshift=-28mm] img1.north west); + \draw [->, line width=1mm] (Audio) edge ([yshift=-46mm] img1.north west); + \end{tikzpicture} + + \caption{Insertion point is at 0:00:25:10 in Hr:Mn:Sec:Frames} + \label{fig:insertion-points} +\end{figure} With the arrow highlighted for \emph{drag and drop mode}, a double click with the left mouse button in the timeline selects the edit the mouse pointer is over. Then dragging in the timeline repositions that edit and this can be used for moving effects, @@ -483,9 +485,6 @@ and waveforms with transluent colors. The pink media file has been self-colored The main window pulldowns as pointed out in figure~\ref{fig:insertion-points} are quite obvious in their meaning and usage, so here is only a summary. -%TODO Figure 3 shows an example of the pulldowns as displayed in the main window.Appearance - - \begin{description} \item[File] \index{file} options for loading, saving, and rendering as described in other sections (\ref{cha:load_save_and_the_EDL}). \item[Edit] \index{edit} edit functions; most of which have shortcuts that you will quickly learn (\ref{cha:editing}). @@ -671,16 +670,9 @@ will not include audio. \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} @@ -847,7 +839,7 @@ titles are inside the inner outline and actions are inside the outer outline. 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. @@ -862,14 +854,7 @@ to the camera, effects, and the projector. \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} @@ -888,42 +873,34 @@ or by using \texttt{Settings $\rightarrow$ Format}, or in the Resources window w a video asset and choosing \texttt{Match $\rightarrow$ Match project size}. When you \emph{Match project size}, you are conforming the output to the asset. To change the size and aspect ratio of the output (Projector) we have to change the whole project, which will alter all the tracks in the timeline. Once you have set the output size in 1 of these 3 ways, any newly created tracks will conform to the specified output size. When rendering, the project's -output size is the final video track size where the temporary pipeline is rendered into. +output size is the final video track size where the temporary pipeline is rendered into. + +To clarify, let's take an example. + +If we load a media (M) into Resources and adjust the size of the project to the size of M, we will get the canvas size of the media $W_{M} \times H_{M}$). We can see in the Set Format window that the project's default values ($W \times H$) have changed to those of M ($W_{M} \times H_{M}$). The tracks on the timeline can have different sizes, but what we will see on the canvas, that is, in the Compositor window, is always the output size i.e. the size of the project. Tracks with smaller sizes will be seen with black bands; tracks with larger sizes will be cropped. Each track has its own size but we will see it inserted in the output size. If we change the output size the tracks will not change, remaining in their original size. We can only change the size of the tracks by manually acting on each one in the ways seen before. Finally, if we create a new track in a project of size $W \times H$, it will assume the size of the project automatically. \subsubsection*{Aspect Ratio (Theory)}% \label{ssub:aspect_ratio_theory} \index{aspect ratio} \index{PAR, DAR, SAR} -The aspect ratio is the ratio of the sides of the frame (\textit{Width} and \textit{Height}). For example, classically broadcast TV was 4:3 (= 1.33), whereas today it has changed to 16:9 (= 1.85); in cinema we use the 35 mm aspect ratio of 1.37 (Academic aperture), but even more so the super 35 mm (2.35). There are also anamorphic formats, i.e. that have no square pixels, like Cinemascope (2.35). The projection must be \textit{normalized} to have an undistorted view. - - -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} @@ -997,7 +974,7 @@ with the mouse. The viewport moves in the same manner. 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} @@ -1016,7 +993,7 @@ Most operations in the Compositor window have a tool window which is enabled by \label{fig:camera_tool} \end{figure} -In the \textit{Position} section you can act on the $X$, $Y$ and $Z$ coordinates. By either tumbling or entering text directly or by using the slider, the camera and projector can be precisely positioned. There is also a reference to the color of the curve as we see it on the timeline. You can also define the \textit{range} of action which by default is [-100 to 100]. By pressing the Reset button for each coordinate, or the global Reset button, the range is automatically brought to the project size value (HD; 4k; etc), which are usually the most useful limits. Note that the range can also be changed in the \textit{Program} window, in the \textit{zoom bar}, where there are similar input fields to enter the chosen limits. +In the \textit{Position} section you can change the $X$, $Y$ and $Z$ coordinates. By either tumbling or entering text directly or by using the slider, the camera and projector can be precisely positioned. There is also a reference to the color of the curve as we see it on the timeline. You can also define the \textit{range} of action which by default is [-100 to 100]. By pressing the Reset button for each coordinate, or the global Reset button, the range is automatically brought to the project size value (HD; 4k; etc), which are usually the most useful limits. Note that the range can also be changed in the \textit{Program} window, in the \textit{zoom bar}, where there are similar input fields to enter the chosen limits. In the \textit{Justify} section we can use automatic positioning in the 6 standard coordinates: Left, Horizontal, Right, Top, Center and Bottom. @@ -1051,7 +1028,7 @@ In the compositing window, there is a popup menu of options for the camera and p \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} @@ -1096,6 +1073,8 @@ The compositing pipeline graph has a masking stage (figure~\ref{fig:temporary-02 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. @@ -1550,7 +1529,7 @@ The characters can be any where within the phrase and it does not matter if uppe 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. @@ -1620,110 +1599,107 @@ Figure~\ref{fig:info_asset_details} shows the \textit{Detail} box to click on th \index{folder add filter/search} Creating folders that are more specific to a particular project is helpful in better organizing your work. -This can be done by utilizing the files already loaded to the \textit{master} Media or Clips folders in the Resources window. The general rule is you can only drag clips to a ClipUserBin and you can only drag media to a MediaUserBin. +This can be done by utilizing the files already loaded to the \textit{master} Media or Clips folders in the Resources window. The general rule is you can only drag clips to a ClipUserBin and you can only drag media to a MediaUserBin. No subfolders can be created within the new folders. Further below, after we populate the new folder, we will see how to use logical operators or other filters to automatically sort the media. -Below are steps illustrating an easy way to set up a folder. +Below are steps illustrating an easy way to set up a new folder. -%TODO Below part need to be rewriten \begin{enumerate} - \item In the Resources window (figure~\ref{fig:folder_resources}), in the location of the Video/Audio effects and Media folders, bring up the \textit{Folder}$\dots$ popup by clicking the right mouse button. - Highlight, then click \textit{New Media or Clips}. - \begin{figure}[htpb] - \begin{minipage}{.6\linewidth} - \centering - \includegraphics[width=0.9\linewidth]{folder_resources.png} - \caption{Highlight, then click “New Media or Clips”. - “Modify folder” can be used to change the name of a folder. - “Delete folder” in the popup can be used to delete a folder. - } - \label{fig:folder_resources} - \end{minipage} - \hfill - \begin{minipage}{.37\linewidth} - \centering -%begin{latexonly} - \vspace{18ex} -%end{latexonly} - - \includegraphics[width=0.9\linewidth]{folder_new.png} - \caption{Type in your folder name in the textbox. Click OK.} - \label{fig:folder_new} - \end{minipage} - \end{figure} + \item In the Resources window (figure~\ref{fig:folder_resources}), in the location of the Video/Audio effects and Media folders, bring up the \textit{Folder...} popup by clicking the right mouse button. Highlight, then click \textit{New Media} or \textit{New Clips}. \textit{Modify folder} can be used to change the name of a folder. \textit{Delete folder} can be used to delete a folder. \item In the \textit{New folder} popup as shown below (figure~\ref{fig:folder_new}), type in your folder name in the textbox. Click OK. - \begin{figure}[htbp] - \centering - \includegraphics[width=0.9\linewidth]{folder_master.png} - \caption{The “master” Media folder} - \label{fig:folder_master} - \end{figure} - \item Select the \textit{master} Media folder to see which files are currently loaded, figure~\ref{fig:folder_master}. - Highlight the files there that you want to copy to your new folder (named Photos of Garden). - Drag the files to the left and when you see the Photos of Garden folder become highlighted, then drop there. - You can drag and drop any of the media from the \textit{master} Media at any time. - It flashes when the drop is successful. + \item Select the \textit{master} Media folder to see which files are currently loaded, figure~\ref{fig:folder_master}. Highlight the files there that you want to copy to your new folder (named \textit{Photos of Garden}). Drag the files to the left and when you see the \textit{Photos of Garden} folder become highlighted, then drop there. You can drag and drop any of the media from the \textit{master} Media at any time. It flashes when the drop is successful. \end{enumerate} -Adding the Shift key before the actual drop, will allow for relative path filenames instead of full path. -But you might want to include or eliminate some of the media that exists in one of the folders that you have set up already. -In this case you will want to click on the \textit{Modify folder} in the popup. -When you bring up the Modify folder window, if you already have files in that folder, you will see filters that were generated automatically when you did a Drag and Drop. +\begin{figure}[htpb] + \centering + \includegraphics[width=0.5\linewidth]{folder_resources.png} + \caption{New folder menu} + \label{fig:folder_resources} +\end{figure} + +\begin{figure}[htpb] + \centering + \includegraphics[width=0.4\linewidth]{folder_new.png} + \caption{Folder name} + \label{fig:folder_new} +\end{figure} + + \begin{figure}[htbp] + \centering + \includegraphics[width=0.8\linewidth]{folder_master.png} + \caption{The “master” Media folder} + \label{fig:folder_master} +\end{figure} +\subsection{Modify Folder: sorting the media}% +\label{sub:sorting_media} +\index{folder modify} + +In \CGG{} all the virtual mediafiles loaded in the \textit{Resources} window are collected in the \texttt{Media} folder without any kind of organization and sorting other than alphabetical. The Media folder is considered a \textit{master} folder because it is the basis for every other new folder we create. Another \textit{master} folder is \texttt{Clips}, and in fact we can create new clips folders as well. If we do editing of large projects containing numerous mediafiles, a rational and selective organization of the source material becomes necessary. In fact, having the sources organized in folders, where they can be found and used easily, makes subsequent editing much faster, as well as minimizing confusion and the possibility of errors. This step, which is fundamental in the pro environment, is called \textit{Logging} and also includes \textit{screening} individual mediafiles in the Viewer window; \textit{renaming} them rationally; and adding labels and descriptions in the \textit{metadata}. + +We start by creating one or more new folders (MediaUserBin). These will be empty and we should populate them with the mediafiles contained in the master Media folder. There are two options: manual \textit{Drag and Drop} or automatic populating by setting \textit{filters} (Smart Bins). + +\paragraph{Drag and Drop:} you drag mediafiles into the new folder one by one or in selected groups. The starting master folder can only be \texttt{Media} (or \texttt{Clips}, if we have created a new clip folder). Dragging is done by preserving the absolute path of the sources. If you open Modify Folder window you will notice that each imported mediafile occupies a different row characterized by its own path and name. See figure~\ref{fig:modify-target}. The \texttt{Value} field containing paths can contain only 63 characters, and it may happen to find the names cut off. The full path and name can be found by right-clicking on the row, but this is inconvenient and time-consuming. The best solution is to drag the mediafiles while holding down the \texttt{Shift} key; this will return the relative path instead of the absolute path, with space gain. \begin{figure}[htpb] - \centering - %\includegraphics[width=0.8\linewidth]{name.ext} - \begin{tikzpicture}[scale=1, transform shape] - \node (img1) [yshift=0cm, xshift=0cm, rotate=0] {\includegraphics[width=0.7\linewidth]{folder_modify.png}}; - \node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Arrow1) {\parbox{8em}{Here is the filter that was generated with the original drop }}; - \node [yshift=-65mm, xshift=0cm,anchor=east] at (img1.north west) (Arrow2) {\parbox{10em}{When you click on the Value portion of that filter, the entire set of files that are covered by the filter rules pops up. Now you can highlight a target filename that you would like to remove, and just erase that line and check the green checkmark for OK.}}; - \draw [->, line width=1mm] (Arrow1) edge ([yshift=-20mm] img1.north west); - \end{tikzpicture} - - \caption{Modify target} - \label{fig:modify-target} + \centering + %\includegraphics[width=0.8\linewidth]{name.ext} + \begin{tikzpicture}[scale=1, transform shape] + \node (img1) [yshift=0cm, xshift=0cm, rotate=0] {\includegraphics[width=0.7\linewidth]{folder_modify.png}}; + \node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Arrow1) {\parbox{8em}{Here is the filter that was generated with the original drop }}; + \draw [->, line width=1mm] (Arrow1) edge ([yshift=-20mm] img1.north west); + \end{tikzpicture} + + \caption{Modify Folder} + \label{fig:modify-target} +\end{figure} + +\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 \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) @@ -1734,7 +1710,7 @@ Column headers: \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 @@ -1747,14 +1723,14 @@ Column headers: \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\\ @@ -1804,7 +1780,6 @@ Column headers: Table showing the allowed usage: -%TODO create table for below code \begin{lstlisting}[numbers=none] target: | eq ge gt ne le lt matches around ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -1841,24 +1816,25 @@ Examples with some caveats first: \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} @@ -1918,7 +1894,7 @@ The reason for playing 5 seconds of a video for a vicon is that until the first 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. @@ -2078,7 +2054,7 @@ A red circle reticle can be moved to the area to grab; use left mouse drag to su 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. diff --git a/translate_manual b/translate_manual index 3fbd6a6..cd2494d 100755 --- a/translate_manual +++ b/translate_manual @@ -12,30 +12,33 @@ pdflatex CinelerraGG_Manual.tex # Now build HTML version, using auxiliary files created by pdflatex. -# clean the future HTML directory +# Clean the future HTML directory rm -rf CinelerraGG_Manual -# latex2html does not know documentclass memoir. It does work nevertheless -# but may produce slightly better results if we temporarily switch to book. -#mv -f CinelerraGG_Manual.tex CinelerraGG_tmp.tex -#sed -e 's/{memoir}/{book}/' CinelerraGG_Manual.tex +# Ensure creating the important settings file +if [ ! -f .latex2html-init ] +then + cp latex2html-init .latex2html-init +fi -# translate document -#latex2html -html_version 4.0,math -use_pdftex -nouse_dvipng -image_type gif -nofootnode -numbered_footnotes -split +3 -link 3 -bottom_navigation -local_icons -t 'Cinelerra-GG Infinity' CinelerraGG_Manual.tex +# 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. -# another alternative options combination -#latex2html -html_version 4.0,math -use_pdftex -use_dvipng -image_type png -nofootnode -numbered_footnotes -cut_ref_name -split +3 -link 3 -bottom_navigation -local_icons -t 'Cinelerra-GG Infinity' CinelerraGG_Manual.tex +# 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 -# 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 -numbered_footnotes -split +3 -link 3 -cut_ref_name -bottom_navigation -local_icons -t 'CinelerraGG_Manual' 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 -# revert back to the original documentclass -#mv -f CinelerraGG_tmp.tex 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 +# This single image has to be copied explicitly cp images/cin-big.png CinelerraGG_Manual -# clean temporary files in the HTML directory +# Clean temporary files in the HTML directory rm -f CinelerraGG_Manual/WARNINGS rm -f CinelerraGG_Manual/*.pl rm -f CinelerraGG_Manual/images*