From: Спицын Андрей Date: Sun, 22 Dec 2019 12:21:09 +0000 (+0300) Subject: Merge branch 'master' of github.com:Andrea-Paz/cin-manual-latex into Andrea-Paz X-Git-Tag: 2021-05~157 X-Git-Url: https://git.cinelerra-gg.org/git/?p=goodguy%2Fcin-manual-latex.git;a=commitdiff_plain;h=ea23fa5f714b9dafe1491b1aeb2a5b04b4893065;hp=37cb1b963584bd39ecd6c60dd02def19ad72788c Merge branch 'master' of github.com:Andrea-Paz/cin-manual-latex into Andrea-Paz --- diff --git a/CinelerraGG_Manual.tex b/CinelerraGG_Manual.tex index 7331a67..94a7966 100644 --- a/CinelerraGG_Manual.tex +++ b/CinelerraGG_Manual.tex @@ -42,6 +42,8 @@ svgnames \include{parts/DVD} \include{parts/Multi5s} \include{parts/Shortcuts} +\include{parts/Configuration} +\include{parts/Stuff} \include{parts/Glossary} diff --git a/common/packages.tex b/common/packages.tex index fea6665..866b786 100644 --- a/common/packages.tex +++ b/common/packages.tex @@ -27,6 +27,7 @@ \usepackage{array} % additional cell aligh \usepackage{indentfirst} % first line indent \usepackage{gensymb} % symbols +\usepackage{caption} %\usepackage[nottoc]{tocbibind} % do we need bibliography in toc %---------------------------------------------- diff --git a/images/Fenstergrundposition-en.png b/images/Fenstergrundposition-en.png new file mode 100644 index 0000000..d009b92 Binary files /dev/null and b/images/Fenstergrundposition-en.png differ diff --git a/images/Rastergrafik.png b/images/Rastergrafik.png new file mode 100644 index 0000000..6f5e141 Binary files /dev/null and b/images/Rastergrafik.png differ diff --git a/images/color.png b/images/color.png new file mode 100644 index 0000000..3532db4 Binary files /dev/null and b/images/color.png differ diff --git a/images/cursor01.png b/images/cursor01.png new file mode 100644 index 0000000..c3368b2 Binary files /dev/null and b/images/cursor01.png differ diff --git a/images/cursor02.png b/images/cursor02.png new file mode 100644 index 0000000..b889a79 Binary files /dev/null and b/images/cursor02.png differ diff --git a/images/ff_probe.png b/images/ff_probe.png new file mode 100644 index 0000000..a3d2781 Binary files /dev/null and b/images/ff_probe.png differ diff --git a/images/settings.png b/images/settings.png new file mode 100644 index 0000000..292ed13 Binary files /dev/null and b/images/settings.png differ diff --git a/images/theme.png b/images/theme.png new file mode 100644 index 0000000..2c358ca Binary files /dev/null and b/images/theme.png differ diff --git a/parts/Configuration.tex b/parts/Configuration.tex new file mode 100644 index 0000000..3440a34 --- /dev/null +++ b/parts/Configuration.tex @@ -0,0 +1,367 @@ + +\chapter{Configuration, Settings and Preferences}% +\label{cha:configuration_settings_preferences} + +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 cinelerra 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 Cinelerra. 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 cinelerra, 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. + +Several ways exist to change Cinelerra’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} (figure~\ref{fig:settings}). + +\begin{figure}[htpb] + \centering \includegraphics[width=0.9\linewidth]{images/settings.png} + \caption{Settings$\rightarrow$Preferences window with Interface tab displayed} + \label{fig:settings} +\end{figure} + +\section{Playback A / Playback B}% +\label{sec:playback_a_b} + +\subsection{Audio Out section}% +\label{sub:audio_out_section} + +The audio drivers are used for both recording and playback. The Audio Out settings affect the outcome when you play sound on the timeline. + +\begin{description} + \item[Playback buffer samples] for playing audio, small fragments of sound are read from disk and processed sequentially. A larger value here causes more latency when you change mixing parameters but yields more reliable playback. Some sound drivers do not allow changing of the fragment, so latency is unchanged no matter what the value. Since different stages of the rendering pipeline can change the rate of the incoming data, it would be difficult to disconnect the size of the console fragments from the size of the fragments read from disk. + \item[Audio offset (sec)] the ability to tell the exact playback position on Linux sound drivers is poor. The audio offset allows users to adjust the position returned by the sound driver in order to reflect reality. The audio offset does not affect the audio playback or rendering at all. It merely changes the synchronization of video playback. The easiest way to set the audio offset is to create a timeline with one video track and one audio track. Expand the audio track and center the audio pan. The frame rate should be larger than $24 fps$ and the sampling rate should be greater than $32000$. The frame size should be small enough for your computer to render it at the full framerate. Highlight a region of the timeline starting at 10 seconds and ending at 20 seconds. Drop a gradient effect on the video track and configure it to be clearly visible. Drop a synthesizer effect on the audio and configure it to be clearly audible. Play the timeline from 0 and watch to see if the gradient effect starts exactly when the audio starts. If it does not, expand the audio track and adjust the nudge. If the audio starts ahead of the video, decrease the nudge value. If the audio starts after the video, increase the nudge value. Once the tracks play back synchronized, copy the nudge value to the audio offset value in preferences. Note: if you change sound drivers or Disable hardware synchronization, you will need to change the audio offset because different sound drivers are unequally inaccurate. + \item[View follows playback] this causes the timeline window to scroll when the playback cursor moves. This can slow down the X Server or cause the timeline window to lock up for long periods of time while drawing the assets. + \item[Disable hardware synchronization] most sound cards and sound drivers do not give reliable information on the number of samples the card has played. You need this information for synchronization when playing back video. This option causes the sound driver to be ignored and a software timer to be used for synchronization. + \item[Audio playback in realtime priority (root only)] for really old computers, this setting allows uninterrupted playback during periods of heavy load. It forces the audio playback to the highest priority in the kernel. Today, it is most useful for achieving very low latency between console tweaks and sound card output. You must be root to get real-time priority. Only experts might want to use this because it interferes with ordinary time-share scheduling and can lock up the system. When this is enabled, audio gets the first shot and burns audio until audio lets go. To explain, there are 2 kinds of scheduling, \textit{time-sharing} which is the default, and \textit{real time} where the scheduled task must explicitly request scheduling to allow other tasks to execute. Time-share interrupts when you use up your allocated time slice. Realtime priority audio will execute audio decode until it finishes, which may slow down other types of processing like video decoding. Most decoders use a policy that video may be downsampled to accommodate scheduling, but will never skip audio because it creates a much more obvious defect. This feature helps to make sure audio gets priority over video during decode. Be sure to check apply in order for this feature to take effect. + \item[Map 5.1$\rightarrow$2] playback 5.1 $\rightarrow$ 2 driver downmix maps 6 tracks to 2 channels when checked, that is mixes $5.1$ down to stereo on the output device side. This is different from the patchbay and menubar functions which reset the pan/mix levels of the input channels. In this way, you can render $5.1$ media, and use stereo speakers to listen in the same session setup. This downmix only occurs if the playback is $5.1$ (6 channels) and the device config is stereo (2 channels). + \item[Gain] set audio gain to a different value than the default of $1.0$ This feature, device level gain, corrects for hardware conditions which some devices may need to be useful. For example, you may need to increase the gain for a weak microphone or a noisy speaker, since it affects rendering when you crank up or down the audio via use of the patchbay. With the audio H/W gain support, you have the ability to fine tune the audio volume by some numerical value for the scale. You are adjusting the scaling of data into the audio driver -- H/W scaling is done before it goes into or out of the driver. This is a one time linear multiplication of the sample values, and may offer better control than the logarithmic DB gain controls of the application. + \item[Audio driver] there are many sound drivers for Linux. This allows selecting one sound driver and setting parameters specific to it. The currently available possibilities are listed next. + \begin{description} + \item[\textit{ALSA}] is the most common sound driver these days and supports almost all sound cards. ALSA + is frequently updated but is very stable. + \item[\textit{OSS}] was one of the first Linux sound drivers and has an open source implementation with many sound cards supported. + \item[\textit{OSS Envy24}] is the commercial version of OSS with a variant for $24 bit 96 KHz$ sound cards. This variant required changes to the way the sound drivers were used and so needed a different driver. + \item[\textit{Raw 1394, DV 1394, IEC 61883}] are older audio drivers used by camcorders and not much else. + \end{description} + \item[Device] with the down arrow, you can see the device choices on your computer. + \item[Bits] 8, 16 or 24 Bit Linear are the current choices for the number of bits of precision Cinelerra should set the device for. The meaning of the number of bits can be misleading. Some sound drivers need to be set to 32 bits to perform 24 bit playback and will not play anything when set to 24 bits. Other sound drivers need to be set to 24 bits for 24 bit playback. + \item[Stop playback locks up] this ALSA only checkbox is needed if stopping playback causes the software to lock up. This has worked some time ago, but may no longer work as expected +\end{description} + +\subsection{Video Out section}% +\label{sub:video_out_section} + +The video drivers are used for video playback in the compositor and the viewer. These determine how you will see video on the timeline. + +\begin{description} + \item[Play every frame] this causes every frame of video to be displayed even if it means that the playback of the video tracks fall behind. Most likely you will want this enabled because, after all, in order to edit you want to see each frame. However, if you are just watching a big video, you can switch to not play every frame so that you can at least not be distracted by slowness. + \item[Framerate achieved] the number of frames per second being displayed during playback. This is updated during playback only. The goal is to get as close to the frame rate as possible, even if Play every frame is not enabled. + \item[Scaling equation] Enlarge / Reduce -- this algorithm is used when video playback involves scaling or translation. This does not affect $1:1$ playback. Choices available are: + \begin{description} + \item[\textit{Nearest Neighbor / Nearest Neighbor}] low quality output with fast playback. Often produces jagged edges and uneven motion. + \item[\textit{Bicubic / Bicubic}] Bicubic interpolation is used for both enlarging and reducing, enlarging blurs slightly but does not show stair step artifacts. + \item[\textit{Bicubic / Bilinear}] High quality output with slow playback. Bicubic interpolation is used for enlarging, which blurs slightly but does not show stair step artifacts. A bilinear interpolation is used for reduction, which produces very sharp images and reduces noise. Bilinear reduced images can be sharpened with a sharpen effect with less noise side effects than a normal sized image. + \item[\textit{Bilinear / Bilinear}] when slight enlargement is needed, a bilinear enlargement looks better than a bicubic enlargement. Bilinear uses less CPU than either Bicubic or Lanczos. + \item[\textit{Lanczos / Lanczos}] is not necessarily a general purpose upscaler, but is intended for low resolution sources. However many people like the sharpening effects. More quality from Lanczos does take more CPU. + \end{description} + \item[DVD subtitle to display] DVD IFO files usually contain subtitle tracks. These must be decoded with the MPEG decoder. Select Enable subtitles to enable subtitle decoding. There are usually multiple subtitle tracks indexed by number and starting from 0. Enter the index number of the subtitle track to be decoded in the \textit{DVD Subtitle to display} text box or use the tumbler to increase the index value. Go to the asset corresponding to the MPEG file in the \texttt{Resources} window and right click. Click on \texttt{Info}. The number of subtitle tracks is shown at the bottom. + \item[Enable subtitles/captioning] for broadcast TV ?? + \item[Label cells] ?? + \item[TOC Program No] Table of Contents program number used in DVB ?? + \item[Interpolate CR2 images] enables interpolation of CR2 images. Interpolation is required since the raw image in a CR2 file is a Bayer pattern. The interpolation uses dcraw's built-in interpolation and is very slow. This operation can be disabled and the Interpolate Pixels effect used instead for faster previewing + \item[White balance CR2 images] this enables white balancing for CR2 images if interpolation is also enabled. This is because proper white balancing needs a blending of all 3 primary colors. White balance uses the camera's matrix which is contained in the CR2 file. Disabling white balancing is useful for operations involving dark frame subtraction. The dark frame and the long exposure need to have the same color matrix. If you disable Interpolate CR2 Images and use the Interpolate Pixels effect, be aware the Interpolate Pixels effect always does both interpolation and white balancing using the camera's matrix, regardless of the settings in Preferences. Dark frame subtraction needs to be performed before Interpolate Pixels. + \item[Video driver] normally video on the timeline goes to the compositor window during both continuous playback and when the insertion point is repositioned. Instead of sending video to the Compositor window, the video driver can be set to send video to another output device during continuous playback. However, this does not affect where video is routed when the insertion point is repositioned. Options are listed next. + \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-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. + \item[\textit{Raw 1394, DV 1394, and IEC 61883}] are for old camcorders. + \end{description} + \item[Default A/B Display] the interface is intended for dual monitor displays. Depending on the value of Display, the Compositor window will appear on a different monitor from the rest of the windows. +\end{description} + +\section{Recording}% +\label{sec:recording} + +The parameters here expedite the \texttt{File $\rightarrow$ Record\dots} function by allowing the user to pre-configure the file format and the hardware used for recording, since the hardware generally determines the supported file format. Once set, the file format is applied to all recordings. + +\subsection{File Format section}% +\label{sub:file_format_section} + +\begin{description} + \item[File Format] this determines the output file format for recordings. It depends heavily on the type of driver used. The menu selections are the same as those of the rendering interface. + \item[Record audio tracks] toggle must be enabled to record audio. + \item[Record video tracks] toggle must be enabled to record video. The wrench button left of both the audio and video tracks toggle, opens a configuration dialog in order to set the compression scheme (codec) for each audio and video output stream. The audio and video is wrapped in a container format defined by the \texttt{File Format} menu. Different wrappers may record audio only, video only, or both. Some video drivers can only record to a certain container. If the video driver is changed, the file format may be updated to give the supported output. If you change the file format to an unsupported format, it may not work with the video driver. + \item[Realtime TOC] setup for DVB recording to automatically generate a Table of Contents. This will scan the stream data \textit{on the fly} on its way to being written while the asset is being captured. ?? +\end{description} + +\subsection{Audio In section}% +\label{sub:audio_in_section} + +\begin{description} + \item[Record Driver] is used for recording audio in the Record window. It may be configured the same as the Record Driver for video if the audio and video are wrapped in the same stream. Available parameters vary depending on the driver. The drivers are the same as described in Playback A/B with the addition of DVB and V4L2 MPEG but no Raw 1394. + \item[DVB Adapter] name of a suitable DVB adapter for linux that is usb connected to your computer and has a connected broadcast TV antenna.?? + \item[dev] your DVB adapter device number, which is usually 0. + \item[Bits] same as described in Playback A/B audio section. + \item[Follow audio config] ?? + \item[Samples read from device] a good value is $2048$ or approximate dev buffer size ($2k-16k$ probably). + Samples to write to disk -- at a time. First, audio is read in small fragments from the device. Then, many small fragments are combined into a large fragment before writing to disk. The disk writing process is done in a different thread. The value here determines how large the combination of fragments is for each disk write. A good starting value is $48000$ but this will will most likely automatically change, probably to $44100$ if necessary. + \item[Sample rate for recording] regardless of what the project settings are, the value set here will be the sample rate used for recording. The sample rate should be set to the highest value the audio device supports. + \item[Channels to record] usually set to 2. + \item[Map 5.1$\rightarrow$2] eave unchecked to record all possible channels. + \item[Gain] usually leave at default of $1.0$, but this device level gain corrects for hardware conditions on some devices which need help. This gives you the ability to fine tune the audio volume by some numerical value for the scale. It is useful as better explained for the Gain in the Playback A/B Audio section discussed previously. + \item[Record in realtime priority] (root only) -- only experts might want to use this because it interferes with ordinary time-share scheduling and can lock up the system. When this is enabled, audio gets the first shot and burns audio until audio lets go. +\end{description} + +\subsection{Video In section}% +\label{sub:video_in_section} + +\begin{description} + \item[Record driver] used for recording video in the Record window. It may be configured the same as the Record Driver for video if the audio and video are wrapped in the same container. Available parameters vary depending on the driver. The drivers available are as follows. + \begin{itemize} + \item Video4Linux2 + \item JPEG webcam + \item YUYV webcam + \item Video4Linux2 JPEG + \item Video4Linux2 MPEG + \item Screencapture + \item DV1394 + \item IEC61883 + \item DVB + \end{itemize} + \item[DVB Adapter] name of a suitable DVB adapter for linux that is usb connected to your computer and has a connected broadcast TV antenna.?? + \item[dev] your DVB adapter device number, which is usually 0. + \item[Follow video config] ?? + \item[Frames to record to disk at a time] frames are recorded in a pipeline. First, frames are buffered in the device. Then, they are read into a larger buffer for writing to disk. The disk writing is done in a separate thread from the device reading. For certain codecs the disk writing uses multiple processors. The value set here determines how many frames are written to disk at a time. + \item[Frames to buffer in device ] the number of frames to store in the device before reading and this determines how much latency there can be in the system before frames are dropped. + \item[Positioning] if set to \textit{Software timing}, use software for positioning information. Video uses audio for synchronization, but most sound cards do not give accurate position information so selecting this option makes Cinelerra calculate an estimation of audio position in software instead of hardware for synchronization. You can also choose \textit{Presentation Timestamps}, \textit{Device Position}, or \textit{Sample Position}. + \item[Sync drives automatically] for high bitrate recording, the disk drives you use may be fast enough to store the data but your operating system may wait several minutes and stall as it writes several minutes of data at a time. This forces the operating system to flush its buffers every second instead of every few minutes to produce slightly better real-time behavior. + \item[Size of captured frame] is the size of the recorded frames in pixels. It is independent of the project frame size because most video devices only record a fixed frame size. + \item[Frame rate for recording ] the frame rate recorded is different from the project settings. This sets the recorded frame rate. +\end{description} + +\section{Performance}% +\label{sec:performance} + +\subsection{Performance section}% +\label{sub:performance_section} + +The main focus of the performance section is rendering parameters not available in the rendering dialog with the obvious gain of perhaps better performance. + +\begin{description} + \item[Cache size] to speed up rendering, several assets are kept open simultaneously. This determines how many are kept open. A number too large may exhaust your memory rapidly. A number too small may result in slow playback as assets need to be reopened more frequently. + \item[Seconds to preroll renders] some effects need a certain amount of time to settle in. Checking this option sets a number of seconds to render without writing to disk before the selected region is rendered. When using the render farm, you will sometimes need to preroll to get seamless transitions between the jobs. Every job in a render farm is prerolled by this value. This does not affect background rendering because background rendering uses a different preroll value. + \item[Force single processor use] Cinelerra tries to use all processors on the system by default, but sometimes you will only want to use one processor, like in a render farm client. This forces only one processor to be used. The operating system usually uses the second processor for disk access. The value of this parameter is used in render farm clients. + \item[Project SMP cpus ] to restrict the number of processors utilized, change the count number. This number will be used for the plugin per load balance operation cpu limit, which uses smp-cpus to stripe your data. It does not affect the number of cpus used in any other cinelerra 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. +\end{description} + +\subsection{Background Rendering section}% +\label{sub:background_rendering_section} + +\begin{description} + \item[Use background rendering] checking this box, enables automatic background rendering. This works in conjunction with the interactive function \texttt{Settings menu $\rightarrow$ Toggle background rendering} which sets the point where background rendering starts up to the position of the insertion point. + \item[Frames per background rendering job] his only works if a render farm is being used; otherwise, background rendering creates a single job for the entire timeline. The number of frames specified here is scaled to the relative CPU speed of rendering nodes and used in a single render farm job. + \item[Frames to preroll background] the number of frames to render ahead of each background rendering job. Background rendering is degraded when preroll is used since the jobs are small. When using background rendering, this number is ideally 0. Some effects may require 3 frames of preroll. + \item[Output for background rendering] background rendering generates a sequence of image files in a certain directory. This parameter determines the filename prefix of the image files. It should be on a disk, accessible to every node in the render farm by the same path. + \item[File format] the file format for background rendering has to be a sequence of images. The format of the image sequences determines the quality and speed of playback. JPEG is a good choice usually. + \item[Video wrench] this has the single option of \textit{use alpha}. It is by default unchecked. +\end{description} + +\subsection{Render Farm section}% +\label{sub:render_farm_section} + +In the Render Farm Section are many options that are explained in detail in the \hyperref[sec:render_farm_usage]{Rendering} chapter of this manual. Just make sure if you do not intend to use a render farm, that \texttt{Use render farm} is not checked. + +\section{Interface}% +\label{sec:interface} + +\subsection{Editing section}% +\label{sub:editing_section} + +\begin{description} + \item[Clicking on edit boundaries] (trimming) Cinelerra not only allows you to perform editing by dragging edit boundaries, but also defines five separate operations that occur when you drag an edit boundary. Here you can select the behavior of each mouse button. The usage of each editing mode is described in great detail in the \hyperref[sub:drag_handle_management_trimming]{Editing} chapter. + \item[Keyframe reticle] the options are \textit{Newer}, \textit{Dragging}, or \textit{Always}. This is used to help in checking edit alignment across tracks. Always renders a line over all plugins, and dragging only over the drag icon. Never draws nothing. + \item[Snapshot path] designates the default directory path for snapshot and grabshot generated output. +\end{description} + +\subsection{Operation section}% +\label{sub:operation_section} + +\begin{description} + \item[Probe Order] clicking on this box brings up a popup allowing you to change the probe order usually for media that is raw camera output but it is also helpful if you want to ensure that a specific driver is used for certain media; for example you may want \texttt{tiff} files to be read natively instead of by ffmpeg. + \item[trap sigSEGV] always enable this so that if cinelerra crashes, a dump will be generated for analysis. + \item[trap sigINT] always enable this so that you can use \texttt{Ctrl-c} to interrupt the program if it appears to be hanging. This will often generate some useful information for analysis. + \item[Use yuv420p dvd interlace format] for DVD media this option maintains the interlacing in Chroma sample addressing, which ordinarily would be deleted because the upsampling of interlaced chroma fields is normally done using a progressive algorithm. With this mode enabled, the MPEG decoder uses a different algorithm for interlaced frames so that the $4:2:0$ format chroma interlacing is preserved. + \item[Min / Max DB for meter] \textit{Min DB} is useful because some sound sources have a lower noise threshold than others. Everything below the noise threshold is meaningless. This option sets the meters to clip below a certain level. \textit{Max DB} sets the maximum sound level represented by the sound meters. This value is presented merely to show how far over the limit a sound wave is. No matter what this value is, no sound card can play sound over 0 dB. + \item[Import images with a duration of \# seconds] when you load single images, like \texttt{png} or \texttt{jpeg}, automatically load for \# number of seconds. This makes it easier to see an image on the timeline. If you just want the single frames, uncheck this option. + \item[Auto start lv2 gui] some lv2 plugins display a \textit{glitzy} UI (User Interface); for example the Calf plugins. For these LV2 plugins, if you want that to automatically come up without having to click on the UI button on the simplified ui interface, this is the flag to enable that. + \item[Android Remote Control] check this to enable using an android device as a remote control for broradcast TV. + \item[Port] default port 23432 is used for the android remote control. + \item[Pin] default PIN cinelerra is used for the android remote control. + \item[Shell Commands] this button brings up the controls for setting up your own shell commands or editing previously set up commands. See the section on Menu Bar Shell Commands for information. + \item[Reload plugin index] execute this reload command when you have modified plugins and want to make sure your changes take effect. + \item[Default LV2\_Path] when there is no system \texttt{LV2\_PATH} set, if you want lv2 plugins loaded, you must set the correct directory path name here. When you change this field, cin will automatically restart and load the newly specified lv2 plugins. +\end{description} + +\subsection{Index Files section}% +\label{sub:index_file_section} + +\begin{description} + \item[Index files go here] index files exist in order to speed up drawing the audio/video tracks. This option determines where index files are placed on the disk. + \item[Size of index file] determines the size of an index file. Larger index sizes allow smaller files to be drawn faster, while slowing down the drawing of large files. Smaller index sizes allow large files to be drawn faster, while slowing down small files. The default is currently 4kB for average size files. + \item[Number of index files to keep] to keep the index directory from becoming very large, old index files are deleted. This determines the maximum number of index files to keep in the directory. + \item[build ffmpeg marker indexes] improves ffmpeg seeks in certain cases although not clear which ones. + \item[Scan for commercial during toc build] used for working with broadcast TV commercial removal. + \item[Delete existing indexes] when you change the index size or you want to clean out excess index files, this deletes all the index files. + \item[Delete clip thumbnails] as clip thumbnails accumulate over time, you may want to delete them to get the disk space back. +\end{description} + +\section{Appearance}% +\label{sec:appearance} + +\subsection{Layout section}% +\label{sub:layout_section} + +\paragraph{Theme} Cinelerra supports 11 different themes to suit the preferences of different users (figure~\ref{fig:theme}). When you change the theme, Cinelerra automatically saves your session and restarts exactly where you were. The \textit{Themes User Interface} are described in more detail next. \textit{Akirad} themes are all available in Cin-GG with major thanks to the \textit{Cinecutie} project for all of their hard work. These modifications provide alternative User Interface environments and allows you to choose your favorite look. Be aware that when you change your theme, Cinelerra will automatically shutdown and restart for it to take effect. The theme you choose is preserved across sessions. + +\underline{Theme choices available:} + +\begin{itemize}[noitemsep] + \item Blond + \item Blond-cv + \item Blue + \item Blue Dot + \item Bright + \item Cakewalk (default) + \item Hulk + \item Neophyte + \item Pink Lady + \item S.U.V. + \item UnFlat +\end{itemize} + + +\begin{figure}[htpb] + \centering \includegraphics[width=0.9\linewidth]{images/theme.png} + \caption{Shows the Cakewalk theme (courtesy Olaf )on Preferences window with list of themes} + \label{fig:theme} +\end{figure} + + +\underline{How To Change your Theme:} + +To change a \textit{Theme} in the main window pulldown, select: + +\texttt{Settings $\rightarrow$ Preferences}; + +then in Preferences window, click on the \texttt{Appearance} tab. In the Editing section in the lower left hand corner, click on the \texttt{down arrow} next to Theme to see your choices. Click on your desired choice from the list given. Check \texttt{OK}, cinelerra will automatically shutdown and restart. + +\begin{description} + \item[Plugin Icons] here are currently 4 choices for different plugin icons to include the old original. + \item[View thumbnail size] you can increase or decrease the thumbnail size -- larger size uses more cpu. + \item[Vicon quality] increase the quality used for thumbnails to get more clarity of pixels -- this will use + more memory. + \item[Vicon color mode] modify the color mode to Low, Medium, or High for the thumbnails -- High will + look the best but takes more memory. +\end{description} + +\subsection{Time Format section}% +\label{sub:time_format_section} + +Various representations of time are given so that you can select the most convenient one for you. The time representation can also be changed by \texttt{Ctrl-clicking} on the timebar in the main window. + +\begin{itemize}[noitemsep] + \item Hours : Minutes : Seconds : xxx + \item Hours : Minutes : Seconds : frames + \item Frames + \item Feet-frames [frames per foot \dots] + \item Seconds +\end{itemize} + +\subsection{Color section}% +\label{sub:color_section} + +\begin{description} + \item[Highlighting Inversion color] modify the selection area color; default is \texttt{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 \texttt{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 \texttt{f} is not readily visible and leads to confusion). A leading 0 or blank is not allowed and will be automatically changed to \texttt{ffffff}. + \item[YUV color space] default is \textit{BT601}; others \textit{BT709} (high definition), \textit{BT2020} (ultra high definition). + \item[YUV color range] JPEG [$0-255$] and MPEG [$16-235$] +\end{description} + +\subsection{Flags section}% +\label{sub:flags_section} + +This section contains many useful options to cater to the various preferences of individual users. + +\begin{description} + \item[Show tip of the day] if checked, a tip will be displayed in a popup box when start up cinelerra. + \item[Autocolor assets] to make it visually easier to see your clips on the timeline that are from the same media file, you can have them automatically colored. Use of this feature requires additional memory and cpu on every timeline redraw, therefore smaller computers may not want this checked on. + \item[ffmpeg probe warns rebuild indexes] this warning is very important for switching from using ffmpeg to using native formats, such as in the case of MPEG, so that you are reminded to \textit{rebuild indexes}. If you do not rebuild the indexes, seeking on the timeline back and forth could very well be problematic, meaning it might not go to the right place. Notification about rebuilding the indexes will appear by default as shown in the figure~\ref{fig:ff_probe} when you click on the FF icon in the main timeline in the upper right hand corner. Once you click on \texttt{Don’t show this warning again} you will no longer be warned and this flag will no longer be enabled. + \begin{figure}[htpb] + \centering \includegraphics[width=0.7\linewidth]{images/ff_probe.png} + \caption{Default warning when you click on FF icon in main window} + \label{fig:ff_probe} + \end{figure} + \item[EDL version warns if mismatched] in the case of a Batch Render, it is often helpful to be warned if the EDL has been changed so that you are aware that what is going to be rendered is different than your current EDL session. + \item[Create Bluray warns if not root] if checked and you are not logged in as root, you will get an error message in order to avoid doing a lot of work and then failing out because root is required for automount and to write on DVD hardware. + \item[Popups activate on button up] this is the default but if unchecked, popups activate on button down. + \item[Set Input Focus when window entered] this is checked on by default because on some operating system distros, when you move your mouse to a different window, nothing happens and you are left wondering why you can not enter information. When checked this causes the input focus to shift to any cinelerra window when the cursor enters an exposed region of the window which eliminates the need to switch input focus by tabbing. + \item[Click to activate text focus] Click to activate text focus + \item [Click to deactivate text focus] if checked, you will have to click to deactivate text focus. + \item[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 (\hyperref[sub:playing_seeking]{17.2.1}). + \item[Use thumbnails in resource window] the Resource Window displays thumbnails of assets by default, but drawing asset thumbnails can take more time and CPU so you may want to uncheck this. + \item[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 Cinelerra you will be right back where you left off. You + will retain all of your undo's and redo's. + \item[Clears before toggle] when using copy/paste in drag and drop mode some users prefer to resort to the addition of the \texttt{Ctrl} key for adding multiple selections. By checking this flag, the user retains usage as is commonly done for listbox operations. + \item[Timeline Rectify Audio] for displaying rectified audio on the timeline instead of a standard audio waveform, check this flag. The waveform is cut on the zero line, thus making the silent areas more visible and the waveform is stretched more over the entire height of the audio track, which improves the visibility of certain areas. This only affects the timeline and not any other audio waveform displays. +\end{description} + +\section{About}% +\label{sec:about} + +This section gives you information about the Cinelerra program and version you are running. The original author’s copyright and name are first and foremost. Next is a textbox with additional information and a summary of the monthly new features of note. Below that is a summary of the GPL License and the fact that it is provided without any warranty. Then the licensing verbage is the item that you may need to refer to most often -- the \textit{built} date and time in case you need to know which version you are currently running. + +\section{Environment Variables for Customization}% +\label{sec:environment_variables_customization} + +Environment variables are global variables in the shell which all applications can read. They are set with a command like \texttt{set VARIABLE=value} or \texttt{export VARIABLE=value}. Environment variables can be viewed with a command like \texttt{env}. The values set can be removed with \texttt{unset VARIABLE}. + +The following exported variables can be set to customize your environment. The \texttt{CIN\_CONFIG} variable could be extremely useful for testing purposes or for multiple users sharing the same home directory who would like different default preference settings. + +\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\_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 + \item[{\small CIN\_LOCALE}] locale text domain path to use for translating text + \item[{\small CIN\_PLUGIN}] plugin directory path + \item[{\small CIN\_RENDER}] complete filename with path, that was used for \textit{select file to render} to in the current session’s last successful Render job; this is used in the \texttt{RenderMux} defined \textit{Shell Cmds} and is available for any user-defined script inside Cinelerra + \item[{\small CIN\_PKG}] used to set your text domain, that is the locale path pointing to mo language file + \item[{\small CIN\_XSYNCH}] (for Developers only) set to 1 helps debugging for windows primitives to execute immediately and not be buffered up so you can see what is happening +\end{description} + +One example: + +\begin{lstlisting}[language=bash] +export CIN_BROWSER=chrome #would override default firefox for Shell Cmds. +\end{lstlisting} + +Another example: + +\begin{lstlisting}[language=bash] +export CIN_CONFIG=/tmp/.bcast5 #use a temporary setup for testing purposes. +\end{lstlisting} + +\begin{description} + \item[{\small BC\_USE\_COMMERCIALS=1}] to activate the commercial database (db) methods. + \item[{\small BC\_TRAP\_LV2\_SEGV}] to get a dump of the failure of an LV2 plugin for help in debugging. + \item[{\small BC\_FONT\_SCALE=1.2}] for changing the default size of the characters to be twice as big. + \item[{\small BC\_ICON\_SCALE=1.1}] for changing the default size of the icons to be bigger; can change \# to any. You can increase the size of the characters in the fonts and icons on your Cinelerra system. This will make it easier to read the characters if you have trouble seeing the default small letters, which have been auto-scaled based on the window geometry. The user-friendly font/icon scaling default is 1 but you can set it to any decimal value. To defeat default auto scaling and get any size characters/fonts, override the setting via the previous 2 listed shell environment variables. This is very sensitive, meaning that even a small increase in the numeric value can vary the size quite dramatically. + \item[{\small BC\_FONT\_PATH=}] to add additional font sets for the \textit{Title} + plugin or to remove all fonts set to : \texttt{(colon)}. An example: \texttt{export BC\_FONT\_PATH=/usr/share/fonts}. + \item[{\small BC\_FONT\_DEBUG=1}] debug for determining which font is causing problems. 0 for no debug. + \item[{\small LADSPA\_PATH}] specify an alternate set of ladspa plugins or include the default with the use of a colon separated list of directories to search for LADSPA plugins. This is always used first and if it does not + exist, then the value for \texttt{CIN\_LADSPA} becomes \texttt{LADSPA\_PATH}. + \item[{\small LV2\_PATH}] specify a certain set of LV2 plugins to use. Separate multiple paths with colons. + \item[{\small LANG and LANGUAGE}] Cinelerra can be localized to display menus and messages in many languages. Language settings are normally read from your linux O/S language settings. To run on a language different than the one selected on your system just change the \texttt{LANG} and \texttt{LANGUAGE} environment variables. For example, open a shell and type: \texttt{export LANG=es\_ES} or + \texttt{LANGUAGE=es\_ES}, then run Cin from the same shell and you will have translations in Spanish. + \item[{\small SHUTTLE\_CONFIG\_FILE}] alternate shuttle configuration file. +\end{description} + diff --git a/parts/DVD.tex b/parts/DVD.tex index c7f29ac..805db10 100644 --- a/parts/DVD.tex +++ b/parts/DVD.tex @@ -430,7 +430,7 @@ Note that there will be no files in the actual AUDIO\_TS directory. \label{ssub:checklist_troubleshooting} \begin{itemize} - \item Are you logged in as root? This is required in order to loopback mount files for bluray and to write media on \texttt{/dev/hardware}. See section 13.7 \todo{internal reference}for a workaround for normal user mode. + \item Are you logged in as root? This is required in order to loopback mount files for bluray and to write media on \texttt{/dev/hardware}. See section \hyperref[sec:bluray_workaround_mount_umount]{13.7} for a workaround for normal user mode. \item Did you startup cinelerra from a terminal window so you can see informative messages? \item Is udftools installed for BD and dvdauthor installed for SD? \item Do you have loopback not enabled for bluray? At least temporarily, disable automount via: @@ -627,7 +627,7 @@ The basic idea is to use playlist-0 as a menu or directions to use the bluray pl Total size = File0 size in bytes / 2048 + 4094 "+" File1 size in bytes / 2048 + 4094 "+" ... \end{lstlisting} Now create the image file via: \texttt{mkudffs image } where image or udfs is the image name. - \item Loop mount the disk image (refer to Section 13.7\todo{idem as above}). + \item Loop mount the disk image (refer to Section \hyperref[sec:bluray_workaround_mount_umount]{13.7}). \item Then actually write your multiple bd.m2ts type files onto the \textit{image} where \texttt{} is the location of the cinelerra binary \textit{bdwrite} file and \texttt{} is your directory path. Below is a single line that wrapped around with 4 Titles. \begin{lstlisting}[language=bash] /bin/bdwrite image /menu_titles.m2ts --- //bd1.m2ts -- //bd2.m2ts -- //bd3.m2ts -- /bd4.m2ts diff --git a/parts/FFmpeg.tex b/parts/FFmpeg.tex index d0aa21e..75996e8 100644 --- a/parts/FFmpeg.tex +++ b/parts/FFmpeg.tex @@ -6,14 +6,21 @@ Cinelerra-GG uses ffmpeg for decoding and encoding media, thus there are many op \section{FFmpeg Early Probe Explanation}% \label{sec:ffmpeg_early_probe_explanation} -When you open media, a series of libraries and codec functions are used to \textit{probe} the data, to see if it can determine the type of file format and codec parameters needed to correctly decode the file. If ffmpeg probes early --- \texttt{Try FFMpeg first} is in effect for the button --- it will usually find some way to try to decode just about any contemporary media file. But there are some times that the built in codecs are actually a better choice. A lot of this may fall into the category of personal preference. For example, some may prefer the mpeg library in the cinelerra code over the ffmpeg code because it has more decoding capability and seems to be more robust when the media is damaged. In that case you will want the FF button to read \texttt{Try FFMpeg last} in the upper right hand corner of the main window. +When you open media, a series of libraries and codec functions are used to \textit{probe} the data, to see if it can determine the type of file format and codec parameters needed to correctly decode the file. If ffmpeg probes early --- \texttt{Try FFMpeg first} is in effect for the FF button --- it will usually find some way to try to decode just about any contemporary media file. But there are some times that the built in codecs are actually a better choice. A lot of this may fall into the category of personal preference. For example, some may prefer the mpeg library in the Cinelerra code over the ffmpeg code because it has more decoding capability and seems to be more robust when the media is damaged. In that case you will want the FF button to read \texttt{Try FFMpeg last}. -So, if ffmpeg probes early, you will never get to use the built in libraries, and if you want to skip over buggy old libraries, use ffmpeg early probe enabled so that the newest code will be tried first. +To summarize, if ffmpeg probes early, you will never get to use the built in libraries, and if you want to skip over buggy old libraries, use ffmpeg early probe enabled so that the newest code will be tried first. +The FF button is located in the upper right hand corner of the main window. -When the icon is red, ffmpeg probes early is enabled and you will see it reads \textit{Currently: Try FFMpeg first} when moving over the FF button in the upper right hand corner of the screen. When the icon is black, ffmpeg probes early is disabled so that ffmpeg probes late and it reads \textit{Currently: Try FFMpeg last}. The initial default state of the icon is on, that is, ffmpeg probes first. This is the original code behavior before ffmpeg code was added. Suggestion is to leave it on except in a few special cases where it may be better to have early probes disabled. When you mouse over the main menu ff toggle button, the text displays ffmpeg's \textit{Currently} set position and \textit{Click to} change it. -The ffmpeg early probe state is saved between sessions and is also affected by choices made in Probe Order (in another section). It is important to note that the various file indexes may need to be rebuilt if you change which codec is being used to decode the file. There is a warning popup to remind you when you change the default ffmpeg early probe state (unless you have checked the box to no longer show you the warning). You can easily rebuild the index for a specific media file by going to the Resources window, right mouse click on that media, and choose \texttt{Rebuild Index} from the popup choices. +When the icon is red, ffmpeg probes early is enabled and you will see it reads + \textit{Currently: Try FFMpeg first} when moving over the FF button in the upper +right hand corner of the screen. When the icon is black, ffmpeg probes early is disabled so that +ffmpeg probes late and it reads \textit{Currently: Try FFMpeg last}. The initial default state of +the icon is on, that is, ffmpeg probes first. Suggestion is to leave it on except in a few special +cases where it may be better to have early probes disabled. When you mouse over the main menu FF +toggle button, the text displays ffmpeg's \textit{Currently} set position. Just left mouse click to change to the other setting. +The ffmpeg early probe state is saved between sessions and is also affected by choices made in Probe Order (refer to section 4 - Probe Order when Loading Media). It is important to note that the various file indexes may need to be rebuilt if you change which codec is being used to decode the file. There is a warning popup to remind you when you change the default ffmpeg early probe state (unless you have checked the box to no longer show the warning). You can easily rebuild the index for a specific media file by going to the Resources window, right mouse click on that media, and choose \texttt{Rebuild Index} from the popup choices. -Figure~\ref{fig:ff} show (1) reddish colored FF in upper right hand corner of main window indicating +Figure~\ref{fig:ff} shows (1) reddish colored FF in upper right hand corner of main window indicating that ffmpeg early probes is enabled; (2) \textit{Try FFMpeg last} indicator message for ffmpeg early probes enabled (note that the color is different because you highlighted the icon); and (3) black colored FF indicates ffmpeg will be used last and you are changing the behavior so that Cinelerra warns you accordingly. \begin{figure}[htpb] @@ -26,7 +33,8 @@ that ffmpeg early probes is enabled; (2) \textit{Try FFMpeg last} indicator mes \section{How to Create FFmpeg Options Files}% \label{sec:create_ffmpeg_options_files} -This section describes how the FFMpeg options files work for decoding and encoding and goes into great detail. It will make more sense if you look at cinelerra's ffmpeg config directory and the cinelerra 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. +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 Cinelerra's ffmpeg config directory and the Cinelerra 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 Cinelerra 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. \subsection{File naming convention}% @@ -52,7 +60,7 @@ In the ffmpeg configuration directory there are a series of options files used w \paragraph{Decoder options:} Normally, only \texttt{ffmpeg.opts} and \texttt{decode.opts} are used when reading/decoding files, but may be specialized if a \texttt{/media.opts} exists for a given \texttt{/media.ext} file. For example, if you want to only fail on fatal errors and to always use the video filter, edgedetect, when working with your media file \texttt{dreaming.y4m}, then create a file \texttt{dreaming.opts} in the same directory with the contents of \texttt{loglevel=fatal} on the first line and \texttt{video\_filter=edgedetect} on the next. These specialized settings will override the defaults. The fatal loglevel is especially handy for lesser quality media. -\paragraph{Encoder Options:} Within the audio /video subdirectories of the first level ffmpeg directory, the \texttt{typ.ext} files are for encoder (rendering) setups. +\paragraph{Encoder Options:} Within the audio/video subdirectories of the first level ffmpeg directory, the \texttt{typ.ext} files are for encoder (rendering) setups. \begin{center} \begin{longtable}{l p{23em}} @@ -100,11 +108,11 @@ Only one equals sign is allowed and it is just for readability. There may be an (or) bitrate = 5000000 \end{lstlisting} -There are 4 special id's recognized by cinelerra which cause special processing. They are: +There are 4 special id's recognized by Cinelerra which cause special processing. They are: \begin{description} \item[duration] overrides the probe duration when opening media for decoding - \item[video\_filter] adds an video stream filter, eg. edgedetect,\dots at the stream level + \item[video\_filter] adds a video stream filter, eg. edgedetect,\dots at the stream level \item[audio\_filter] adds an audio stream filter, eg. echo,\dots at the stream level \item[loglevel] sets the library logging level, as quiet, panic, \dots verbose, debug \end{description} @@ -125,7 +133,7 @@ scan_all_pmts=1 threads=auto \end{lstlisting} -The encoder options you see in the cinelerra menus depend on the files in these directories, \textsc{NOT THE CODE}. If you add files, you will get to use more variety. +The encoder options you see in the Cinelerra menus depend on the files in these directories, \textsc{NOT THE CODE}. If you add files, you will get to use more variety. In the \textit{cinelerra} directory, which contains the ffmpeg configuration folder, there are the choices the program uses. When you open an ffmpeg format popup dialog, the listbox contains all of the codec types which are identified by the file.ext extensions. Decoding has only a few options, since the ffmpeg file probes determine most of the options by looking at the media being opened, but encoding media requires a lot of setup. Below are some of the folders and files used to determine the configurations used by ffmpeg to decode and encode files. @@ -133,7 +141,7 @@ These extensions create audio / video media classes: \texttt{dvd \quad m2ts \quad mkv \quad mp3 \quad mp4 \quad mpeg \quad qt \quad pro} -which become the choices in the render pulldown menu +which become the choices in the render pulldown menu. So if you want to create a \textit{mov} codec class, add two new files to the ffmpeg configuration directory: @@ -156,7 +164,7 @@ bitrate 4000000 This will code an \texttt{mp4} formatted file using the \texttt{lib264} codec encoder. -For audio and video together, the mux format must agree between the aud.mov and vid.mov files when they are to be used together. The stream muxer must be the same for the all the streams in the file being written. +For audio and video together, the mux format must agree between the aud.mov and vid.mov files when they are to be used together. The stream muxer must be the same for all the streams in the file being written. for example: \begin{lstlisting}[language=bash] @@ -196,33 +204,25 @@ loglevel=verbose sometimes that will be enough to see what has caused a failure, or even catch unexpected results. -Now there is an \textsc{EXCEPTION} to all of the above because of a conflict between ffmpeg and the x264 person making the detection of default ffmpeg settings terminate with an error. If you get this error, you must workaround this termination by including parameters that don't match $5$ or more of the normal expected values. So you just have to change a few parameters to avoid the probe detection. Here is an example where you will notice the \texttt{x264opts} line tweaking values to throw off the detection/error termination code. +There is an \textsc{EXCEPTION} to all of the above because of a conflict between ffmpeg and the x264 person making the detection of default ffmpeg settings terminate with an error. If you get this error, you must workaround this termination by including parameters that don't match $5$ or more of the normal expected values. So you just have to change a few parameters to avoid the probe detection. Here is an example where you will notice the \texttt{x264-params} line tweaking values to throw off the detection/error termination code. \begin{lstlisting}[language=bash] # /ffmpegvideo/test.mp4 mp4 libx264 preset=slow -x264opts keyint=25:min-keyint=4:qpmin=3:qpmax=33:qp_step=4:merange=8 +x264-params keyint=25:min-keyint=4:qpmin=3:qpmax=33:qp_step=4:merange=8 crf 20 \end{lstlisting} -Another \textsc{EXCEPTION} is for some forms of aac, which is the reason bitstream filters were added. -If you think that you are in this situation, use: - -\begin{lstlisting}[language=bash] -# /ffmpeg/audio/test.mp4 -mp4 libfdk_aac -\end{lstlisting} - For more examples, look around the ffmpeg directory for examples which may be close to what you are trying to use, and see if the parameters look usable. This is quite complicated, but that is because ffmpeg has a lot of parameters and history. Good results are not that hard to create. Initially you should mostly use the defaults. If you send any new options files to \url{cin@lists.cinelerra-gg.org }, it will be given consideration to being added to the baseline for future deliverables. -To get a listing of the current ffmpeg supported formats and codecs that can be made to work with cinelerra, provided there are option files added, run the following commands. This should be done from the directory substituting the location of where you have installed cinelerra on your system and the ffmpeg may be a different version than $4.1.1$ as used below. Then look at the output created in \texttt{/tmp/ff-formats.txt} and \texttt{codecs.txt}. +To get a listing of the current ffmpeg supported formats and codecs that can be made to work with Cinelerra, provided there are option files added, run the following commands. This should be done from the directory substituting the location of where you have installed Cinelerra on your system and the ffmpeg may be a different version than $4.2$ as used below. Then look at the output created in \texttt{/tmp/ff-formats.txt} and \texttt{codecs.txt}. \begin{lstlisting}[language=bash] -//cinelerra-5.1/thirdparty/ffmpeg-4.1.1/ffmpeg -formats > /tmp/ff-formats.txt -//cinelerra-5.1/thirdparty/ffmpeg-4.1.1/ffmpeg -codecs > /tmp/ff-codecs.txt +//cinelerra-5.1/thirdparty/ffmpeg-4.2/ffmpeg -formats > /tmp/ff-formats.txt +//cinelerra-5.1/thirdparty/ffmpeg-4.2/ffmpeg -codecs > /tmp/ff-codecs.txt \end{lstlisting} \subsection{Complete Options File Example}% @@ -246,18 +246,18 @@ Add the file named \texttt{./ffmpeg/audio/pro.dfl} which contains the following acc256k.pro \end{lstlisting} -Add the file named \texttt{./ffmpeg/video/med422p10.pro} which contains the following lines: +Add the file named \texttt{./ffmpeg/video/prores.pro} which contains the following lines: \begin{lstlisting}[language=bash] mov prores -preset medium -cin_pix_fmt yuv422p10le +profile=2 +# lines of comments \end{lstlisting} Add the file named \texttt{./ffmpeg/video/pro.dfl} which contains the following lines: \begin{lstlisting}[language=bash] -med422p10.pro +prores.pro \end{lstlisting} Then to use and to get 10 bit depth and preserve depth from decode to encode: @@ -266,7 +266,7 @@ Then to use and to get 10 bit depth and preserve depth from decode to encode: \item load media \item use settings$\rightarrow$format to set the frame rate, sample rate/channels, aspect ratio, color model = rgb\_float or rgba\_float if blending - \item press \texttt{Shift-R} and select FFMpeg format type \texttt{pro} + \item press \texttt{Shift-R} and select FFmpeg format type \texttt{pro} \item select target path \item check \texttt{OK}, and watch for messages in the terminal window \end{enumerate} @@ -274,13 +274,13 @@ Then to use and to get 10 bit depth and preserve depth from decode to encode: \subsection{Viewing \& Modifying FFmpeg Format Options inside Cinelerra}% \label{sub:viewing_modifying_ffmpeg_cinelerra} -There are thousands of options for using ffmpeg. Now it is possible to \textit{view} the available options for a particular video and audio choice by using the \textit{wrench icon} and then clicking on the \textit{view} box. Ffmpeg has to be the selected file format for this feature to be visible. It makes it a lot easier since only the applicable options show up as opposed to everything that ffmpeg can do. These options are just \textit{Hints} and some may be missing due to the way that ffmpeg options are coded --- Cinelerra shows the option data ffmpeg has exposed. +There are thousands of options for using ffmpeg. Now it is possible to \textit{view} the available options for a particular video and audio choice by using the \textit{wrench icon} and then clicking on the \textit{view} box. FFmpeg has to be the selected file format for this feature to be visible. It makes it a lot easier since only the applicable options show up as opposed to everything that ffmpeg can do. These options are just \textit{Hints} and some may be missing due to the way that ffmpeg options are coded --- Cinelerra shows the option data ffmpeg has exposed. -As an example, instead of reading the entire 264 library information, you only have to look at the shown available options. Both the video and the audio are browsable. The options visible in the \textit{Audio/Video Preset} textbox are the final values which are used when rendering once you have checked \texttt{OK}. For assistance in choosing the options you want, use the view popup to see the objects that go with the selected format tool, highlight the option, modify the parameter value in the box at the top of the \textit{Options} window based on what you want, and then click apply. Updates modify parameter values or new parameters will be appended at the bottom. Note that when you highlight an option, a tooltip will show up when available in the lower right hand corner which describes the option. Also note that the Format and Codec types are shown on the top line of the Options window. +As an example, instead of reading the entire 264 library information, you only have to look at the shown available options. Both the video and the audio are browsable. The options visible in the \textit{Audio/Video Preset} textbox are the final values which are used when rendering once you have checked \texttt{OK}. For assistance in choosing the options you want, use the view popup to see the objects that go with the selected format tool, highlight the option, modify the parameter value in the box at the top of the \textit{Options} window based on what you want, and then click apply. Updated parameter values or new parameters will be appended at the bottom. Note that when you highlight an option, a tooltip will show up when available in the lower right hand corner which describes the option. Also note that the Format and Codec types are shown on the top line of the Options window. -Parameters exist in 3 layers: ffmpeg, codec, and an interface layer. You can apply parameters to each layer. The top 2 layers are accessed with the Kind popup menu. The ffmpeg layer is topmost, and is selected as Kind: ffmpeg. It can specify many of the more common parameters, such as the bitrate, quality, and so on. The middle layer is selected as Kind: codec. These options can specialize your choices, and frequently includes presets and profiles useful for coding well known parameter sets, like \texttt{profile=high422}, \texttt{preset=medium}, or \texttt{tune=film}, etc. The interface layer may or may not be available. It is usually accessible only by an \textit{opts} parameter, like \texttt{x264opts=key=value:key=value:\dots} These options are passed directly to the low level codec library. +Parameters exist in 3 layers: ffmpeg, codec, and an interface layer. You can apply parameters to each layer. The top 2 layers are accessed with the Kind popup menu. The ffmpeg layer is topmost, and is selected as Kind: ffmpeg. It can specify many of the more common parameters, such as the bitrate, quality, and so on. The middle layer is selected as Kind: codec. These options can specialize your choices, and frequently includes presets and profiles useful for coding well known parameter sets, like \texttt{profile=high422}, \texttt{preset=medium}, or \texttt{tune=film}, etc. The interface layer may or may not be available. It is usually accessible only by an \textit{opts} parameter, like \texttt{x264-params key=value:key=value:\dots} These options are passed directly to the low level codec library. -Figure~\ref{fig:video-preset} show \textit{ffmpeg} video for as the Kind. Note the x264opts in the Video Preset window immediately below. +Figure~\ref{fig:video-preset} shows \textit{ffmpeg} video as the Kind. Note the x264opts (should actually be x264-params now) in the Video Preset window immediately below. \begin{figure}[htpb] \centering @@ -289,7 +289,7 @@ Figure~\ref{fig:video-preset} show \textit{ffmpeg} video for as the Kind. Note t \label{fig:video-preset} \end{figure} -Figure~\ref{fig:audio-preset02} show \textit{ffmpeg} video for as 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. +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. \begin{figure}[htpb] \centering @@ -301,7 +301,7 @@ Figure~\ref{fig:audio-preset02} show \textit{ffmpeg} video for as the Kind. Note \section{The FFmpeg Image2 Streams}% \label{sec:ffmpeg_image2_streams} -Another feature gained from using ffmpeg in cinelerra 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 kind. A specific example is described below. +Another feature gained from using ffmpeg in Cinelerra 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. To encode a series of $48$ bit tiff output image files, add a file to the cinelerra data ffmpeg/video subdirectory as in: @@ -343,8 +343,8 @@ duration=90.25 \label{sec:ffmpeg_items_note} \begin{description} - \item[Quality Option when rendering:] Ffmpeg responds variably to the quality option in the render option but seems to respond well to bitrate. The subranges used by quality even seem to vary somewhat depending on how old the codec is. Some use $0$ to $35$, some use $0$ to $500$ or so. The quality is supposed to cause the codec to output data until the noise level is below a limit determined by the quality setting. Your specific results may vary. - \item[Previous Changes when rendering:] With ffmpeg there are 2 cases that the defaults will be used. The first time when you have nothing set up and any other time when you reset the render File Format in the Render Menu. Otherwise with ffmpeg if you change a video compression type for the render (for example \texttt{h264.mp4} to \texttt{h265.mp4}), the settings will be from the previous session settings. + \item[Quality Option when rendering:] FFmpeg responds variably to the quality option in the render option but seems to respond well to bitrate. The subranges used by quality even seem to vary somewhat depending on how old the codec is. Some use $0$ to $35$, some use $0$ to $500$ or so. The quality is supposed to cause the codec to output data until the noise level is below a limit determined by the quality setting. Your specific results may vary. + \item[Previous Changes when rendering:] With ffmpeg there are 2 cases that the defaults will be used. The first time when you have nothing set up and any other time when you reset the render File Format in the Render Menu. Otherwise with ffmpeg, if you change a video compression type for the render (for example \texttt{h264.mp4} to \texttt{h265.mp4}), the settings will be from the previous session settings. \item[Outstanding Issues with ffmpeg:] There are some problems that need to be addressed by the ffmpeg developer group that adversely affect Cinelerra. These are stated below with the hopes that that group will fix them as time permits. \begin{itemize} \item Make all the default parameters operational. When they are not, the Cinelerra plugins can't be initialized since the initial state of the filter is not operational. If that is not possible, then provide a set of nominal parameters for each plugin, so that they can be used as the plugins initial default state. diff --git a/parts/Instalation.tex b/parts/Instalation.tex index 0059bc7..c90a40a 100644 --- a/parts/Instalation.tex +++ b/parts/Instalation.tex @@ -4,7 +4,7 @@ \label{sec:How_to_build} These are generic build instructions for building Cinelerra-GG Infinity. -Known to work on ubuntu, mint, suse/leap, fedora, debian, centos, arch, and slackware. +Known to work on Ubuntu, Mint, Suse/Leap, Fedora, Debian, Centos, Arch, and Slackware. It has not been tested on every single possible distro yet so you might expect to have to make some minor changes. Patches have been created to build on FreeBSD through the work of another programmer and a Gentoo version is being maintained elsewhere by another programmer. @@ -51,13 +51,13 @@ These differences make it possible to have several different versions installed \begin{enumerate} \item - You need at least 2.5\,GB of disk storage to operate a build + you need to have “\texttt{git}” installed. + You need about 6.0 \,GB of disk storage to operate a build + you need to have “\texttt{git}” installed. \item Obviously in order to install into the system, you must run as \textbf{root}. - \item The "\texttt{git}" step has to download many files (approx 100\,MB) so allow time. + \item The "\texttt{git}" step has to download many files (approx 130\,MB) so allow time. When decompressed this will expand to about 530 MB. \item Run the following commands (this takes awhile): \begin{lstlisting}[language=bash] -$ cd // # this is where you need the 2.5GB of disk space +$ cd // # this is where you need the 6.0GB of disk space $ git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5 $ cd cinelerra5/cinelerra-5.1 # toplevel directory \end{lstlisting} @@ -66,7 +66,7 @@ $ cd cinelerra5/cinelerra-5.1 # toplevel directory So on the very first build you should run: \begin{lstlisting}[language=bash] -$ ./blds/bld_prepare.sh # where represents the Operating System of centos, fedora, suse, leap, ubuntu, debian. +$ ./blds/bld_prepare.sh # where represents the Operating System of Centos, Fedora, Suse, Leap, Ubuntu, Debian. $ ./autogen.sh $ ./configure --prefix=/usr # optional parameters can be added here $ make 2>&1 | tee log # make and log the build @@ -84,17 +84,17 @@ $ //cinelerra5/cinelerra-5.1/log \begin{lstlisting}[language=bash] $ make install \end{lstlisting} - \item If it all worked, you are all setup. Just click on the cinelerra desktop icon. + \item If it all worked, you are all setup. Just click on the Cinelerra desktop icon. \end{enumerate} \paragraph{To do a single-user build,} read the \texttt{README} that is at the top level after you get the source. \begin{enumerate} - \item You need at least 2.5\,GB of disk storage to operate a build + you need to have “\texttt{git}” installed. + \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 The "\texttt{git}" step has to download many files (approx 100\,MB) so allow time. + \item The "\texttt{git}" step has to download many files (approx 130\,MB) so allow time. \item Run the following commands (this takes awhile): \begin{lstlisting}[language=bash] -$ cd // # this is where you need the 2.5GB of disk space +$ cd // # this is where you need the 6GB of disk space $ git clone --depth 1 "git://git.cinelerra-gg.org/goodguy/cinelerra.git" cinelerra5 $ cd cinelerra5/cinelerra-5.1 # toplevel directory \end{lstlisting} @@ -189,7 +189,7 @@ $ export FFMPEG_EXTRA_CFG=" --disable-vdpau" \subsection{Notes about Building from Git in your Customized Environment}% \label{sub:notes_about_building_from_git_in_your_customized_environment} -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 "devel" version so the header files which match the library interfaces exist. Below is the list of thirdparty builds, but this list may have changed over time: +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 "devel" version so the header files which match the library interfaces exist. Below is the list of thirdparty builds, but this list may have changed over time. % It's list of Table? \begin{table}[htpb] @@ -264,7 +264,7 @@ If you want to avoid downloading the software every time an update is available The repo is a directory where you first do a “\texttt{git clone}”. For the initial git clone, setup a local area for the repository storage, referred to as \texttt{}. The “\texttt{git clone}” creates a repo named "\texttt{cin5}" in the \texttt{//} directory. -This accesses over 300\,MB of repo data, so the device has to have at least that available. +This accesses about 530\,MB of repo data, so the device has to have at least that available. The repo path is always a perfect clone of the main repo. \paragraph{Setting up the initial clone}% @@ -363,7 +363,7 @@ $ git checkout master \label{sub:debuggable_single_user_build} -To build from source with full debugging symbols, first build a full static (non\_debug) build as follows but instead /tmp substituted with a permanent disk path if you want to keep it. +To build from source with full debugging symbols, first build a full static (non\_debug) build as follows but instead /tmp should be substituted with a permanent disk path if you want to keep it. \begin{lstlisting} $ git clone ... @@ -402,14 +402,14 @@ For example, unless special options were set up by you, the LV2 audio plugins wi Nor will the codec libzmpeg, the file codec ac3, or DVD creation. The old school file classes will all work, but some of the formats that come with ffmpeg may not because of the way that ffmpeg was installed on your operating system. That is because the Cinelerra ffmpeg is a known static build and is usually the latest stable/released version. -In the current case of Leap 15, libx264 and libx265 are not built in and this can be debilitating; You can always run “ffmpeg -formats” and “ffmpeg -codecs” to see what is available on your system. +In the current case of Leap 15, libx264 and libx265 are not built in and this can be debilitating; you can always run “ffmpeg -formats” and “ffmpeg -codecs” to see what is available on your system. \section{Download Already Built Cinelerra-GG}% \label{sec:download_already_built_cinelerra_gg} -If you prefer to not have to take the time to build Cinelerra-GG Infinity yourself, there are pre-built dynamic or static binaries for various versions of ubuntu, mint, suse, fedora, debian, centos, arch, and slackware linux as well as Gentoo and FreeBSD. -There are also 32-bit i686 ubuntu, debian, and slackware versions available. +If you prefer to not have to take the time to build Cinelerra-GG Infinity yourself, there are pre-built dynamic or static binaries for various versions of Ubuntu, Mint, Suse, Fedora, Debian, Centos, Arch, and Slackware linux as well as Gentoo and FreeBSD. +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. They are in subdirectories of: @@ -513,11 +513,13 @@ apt upgrade cin apt install software-properties-common apt-transport-https apt-add-repository https://cinelerra-gg.org/download/pkgs/debian8 OR apt-add-repository https://cinelerra-gg.org/download/pkgs/debian9 +OR apt-add-repository https://cinelerra-gg.org/download/pkgs/debian10 # VIP - for the first install, the above line adds cinelerra to /etc/apt/sources.list but... -# Debian stretch and jessie are more strict for licensing so you will have to edit +# Debian stretch/jessie/buster are more strict for licensing so you will have to edit # the file /etc/apt/sources.list to add [trusted=yes] after deb and before https...cin... # For example for debian8: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/debian8 jessie main # For example for debian9: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/debian9 stretch main +# For example for debian10: deb [trusted=yes] https://cinelerra-gg.org/download/pkgs/debian10 buster main apt update apt install cin #to update a previous install diff --git a/parts/Introduction.tex b/parts/Introduction.tex index 9173f1a..e003a49 100644 --- a/parts/Introduction.tex +++ b/parts/Introduction.tex @@ -3,19 +3,29 @@ \addcontentsline{toc}{chapter}{Introduction} Cinelerra is a software program NLE, Non-Linear Editor, that provides a way to edit, record, and play audio or video media. -It can also be used to retouch photos. - -This manual covers Cinelerra-GG Infinity version. -The author of the original Cinelerra, Adam Williams, as well as many different people worked on Cinelerra over the years. -The software and this manual were merged in from various sources and each person is to be thanked and commended for their efforts. -Numerous software modifications were made by William Morrow. -These are all under GPLv2+ license. +It can also be used to transcode media from one format to another or to correct and retouch photos. Cinelerra +currently runs on many Linux operating system distributions. + +This manual covers the Cinelerra-GG Infinity version. +Information contained in this manual is a description of the Cinelerra-GG program usage and was obtained from +various sources to include different communication channels, emails, common knowledge, and write-ups as new features were added. +The author of the original Cinelerra program, Adam Williams, as well as many different people have modified + the Cinelerra source code over the years. +William Morrow merged all of the known changes, whenever possible, into this Cinelerra-GG version and for several years has been adding numerous features, updates, and fixes. +All of these software contributions are appreciated and each individual is thanked and commended for their efforts. +The Cinelerra software is under GPLv2+ license. Refer to: {\small\url{https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html}} +As for this manual, the GNU Free Documentation License (GNU FDL or simply GFDL) is a copyleft +license for free documentation, designed by the Free Software Foundation (FSF) for the GNU +Project. It is similar to the GNU General Public License, giving readers the rights to copy, +redistribute, and modify (except for "invariant sections") a work and requires all copies and derivatives to be available under the same license. +The GFDL was designed for manuals, textbooks, other reference and instructional materials, and documentation which often accompanies GNU software. +Refer to: {\small\url{https://en.wikipedia.org/wiki/GNU_Free_Documentation_License}} \textbf{This is a copy of the header from the original source code.} \begin{lstlisting}[numbers=none,basicstyle=\footnotesize] -/* +* * CINELERRA * Copyright (C) 1997-2012 Adam Williams * @@ -34,21 +44,6 @@ Refer to: {\small\url{https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalo * Foundation, Inc., 59 Temple Place, Suite 330, Boston \end{lstlisting} -\textbf{This is a copy of the information in the Cinelerra-CV manual.} - -Copyright c 2003, 2004, 2005, 2006 Adam Williams - Heroine Virtual Ltd. -Copyright c 2003, 2004, 2005, 2006, 2007 Cinelerra CV Team. - -This manual is free; you can redistribute it and/or modify it under the terms of the GNU General -Public License as published by the Free Software Foundation; either version 2 of the License, or -(at your option) any later version. - -This document is distributed in the hope that it will be useful, but WITHOUT ANY WAR- -RANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A -PARTICULAR PURPOSE. See the GNU General Public License for more details. - -You should have received a copy of the GNU General Public License along with this program; -if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, U \section*{Cinelerra Overview}% \label{sec:cinelerra_overview} @@ -69,14 +64,14 @@ The GG version of Cinelerra has been improved for \emph{stability}, \emph{modern \item[Modernization] ~\\ Artistic creativity has been applied to modernize the Cinelerra-GG plugin icons for video and audio to even include the ffmpeg plugins. The Cinfinity set of plugin icons come in square or roundish versions --- your choice. - In keeping up with the current expectation of users for a certain “look and feel”, a very modern Neophyte theme recent addition provides an alternative to the already existing 9 themes. - These 10 themes give the user the choice to get the look they like best for their own eyes. - \item[Cerrent and up-to-date] ~\\ + In keeping up with the current expectation of users for a certain “look and feel”, 2 very modern recent theme additions, Cakewalk and Neophyte, provide alternatives to the already existing 9 themes. + These 11 themes give the user the choice to get the look they like best for their own eyes. + \item[Current and up-to-date] ~\\ For today’s software, included thirdparty libraries are kept up to date in a timely manner and effort is made to always used a relatively recent version of FFmpeg, if not the latest. This is a big deal because there is a whole set of separate programmers continuously working diligently to cover all of the old and newly created formats. Thus Cinelerra programmers can be dedicated to working solely on Cinelerra rather than just trying to keep up with many formats. \item[FFmpeg usage integration]~\\ - By using FFmpegwith Cinelerra there is the advantage that users can directly convert videos via pre- and post-processing, without the need for command lines to be executed manually before or afterwards. + By using FFmpeg with Cinelerra, there is the advantage that users can directly convert videos via pre- and post-processing, without the need for command lines to be executed manually before or afterwards. \item[Import and Export formats] ~\\ Listed here are only a few of the supported Import and Export formats: \begin{itemize} @@ -85,7 +80,7 @@ The GG version of Cinelerra has been improved for \emph{stability}, \emph{modern mp4, mkv, mpeg, mov, m2ts, mp3, dvd, ogg, theora, prores, tiff, webm, flac, opus, vorbis, quicktime (div, dnxhd, jpeg, mjpeg, mp4, rle, v308, v410), h264 \& h265 usage, avc, hevc, and recently released AV1 and WebP - \item raw image format for over 700 supported cameras, courtesy Dave Coffin DCraw + \item raw image format for over 700 supported cameras, courtesy Dave Coffin's DCraw \end{itemize} \item[Standard Features] ~\\ \begin{itemize} @@ -95,7 +90,7 @@ The GG version of Cinelerra has been improved for \emph{stability}, \emph{modern \item Undo and Redo capability for many editing functions. \item Drag handle functionality for Ripple, Roll, Slip, Slide, Edge, and No Effect. \item Dynamic Keyframe support with curve, toggle, automatic, compositor, and editing capabilities. - \item Proxy editing support to speed up editing for large formatted files or slower computers. + \item Proxy editing support to speed up editing for large formatted files on slower computers. \item Compositor window with masking, zooming, cropping, projector and camera capabilities. \item Viewing window for quickly viewing/playing audio, video, clips, or proxies. \item Resources window with Media, Proxy, Clips, Video and Audio Effects/Transitions. @@ -120,6 +115,7 @@ The GG version of Cinelerra has been improved for \emph{stability}, \emph{modern \item OpenGL support as well as Direct X11 speedup. \item Advanced Trim Features and Grouping. \item Asset and Title colors selection including Alpha slider adjustment. + \item Scaling preference for any monitor size and HiDPI to support 4K monitors. \end{itemize} \item[Innovative New Features] ~\\ \begin{itemize} diff --git a/parts/Plugins.tex b/parts/Plugins.tex index 8e6cf25..a6ce6b2 100644 --- a/parts/Plugins.tex +++ b/parts/Plugins.tex @@ -188,11 +188,13 @@ For most User installs, the \texttt{.png} file will be located at: For some System installs, the files might be located at: -\texttt{/usr/lib/cin/plugins/picon/cinfinity} (or cinfinity2, original or -\todo{raphrase to avoid boarder break} -smoo\-ther) (ubuntu distros) +\texttt{/usr/lib/cin/plugins/picon/cinfinity} -\texttt{/usr/lib64/cin/plugins/picon/cinfinity} (or cinfinity2, original or smoother) (Leap distro) +(or cinfinity2, original or smoother --- ubuntu distros) + +\texttt{/usr/lib64/cin/plugins/picon/cinfinity} + +(or cinfinity2, original or smoother --- Leap distro) \subsection{Details on where to put your own Plugin Icons}% \label{sub:details_put_plugin_icons} @@ -2419,9 +2421,7 @@ Figure~\ref{fig:title03}. \begin{description} \item[Background] in this box you can keyin the name of a file of the type that cinelerra accepts and use that file as a background for your Title characters. This will be seen in the compositor window on top of the video that is loaded in the main track canvas. Besides typing in the filename, you must also check the checkbox. This makes it easy to turn it \texttt{on} and \texttt{off} to see what it looks like. Next to the background box is a \texttt{Loop} checkbox. If the background file takes less time than the main track canvas video to run, you can turn on the loop checkbox so that it runs over and over again to match the time size of your video. \item[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 \texttt{Drop shadow}. - \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 \texttt{Ctrl-Shift-U} followed by $2022$ and a carriage return is an example of the bullet. Refer to section 40.11 - \todo{lost link} - for details. + \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 \texttt{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} diff --git a/parts/Recording.tex b/parts/Recording.tex index 73d2325..f4e73e0 100644 --- a/parts/Recording.tex +++ b/parts/Recording.tex @@ -21,7 +21,7 @@ Access the Record function via \texttt{File} $\rightarrow$ \texttt{Record}\dots \end{tabular} \vspace{2ex} -The media file will be written using the format and codec specified in the \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Recording tab}, which you will need to set up first. See the Settings/Preferences \todo{reference to section} section for parameters. Only ffmpeg can record both audio and video simultaneously, and some ffmpeg formats require too much cpu to do a realtime compression. A setting which is more likely to be usable (requires less cpu/memory for realtime encoding) is \texttt{ffmpeg /qt/mp4.qt} with bitrates like $audio/256000$ \& $video/6000000$. +The media file will be written using the format and codec specified in the \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Recording tab}, which you will need to set up first. See the \hyperref[sec:recording]{Settings/Preferences} section for parameters. Only ffmpeg can record both audio and video simultaneously, and some ffmpeg formats require too much cpu to do a realtime compression. A setting which is more likely to be usable (requires less cpu/memory for realtime encoding) is \texttt{ffmpeg /qt/mp4.qt} with bitrates like $audio/256000$ \& $video/6000000$. \section{Record Web Media in real-time}% \label{sec:record_web_media_rt} @@ -648,7 +648,7 @@ command line from a window of \\ \item Next press \texttt{play} on your media hardware device. If on the \textit{Video In} side window you see only noise, then S-Video or something else was an incorrect choice and you will have to perform some tests to find correct choices. \end{itemize} -There are many more parameters that you may want to vary in the Recording menu or for more details on various items, please refer to the section \textit{Record Web Media in real-time} \todo{reference to previous section}. The \textit{Transport} buttons are well defined there also. +There are many more parameters that you may want to vary in the Recording menu or for more details on various items, please refer to the section \hyperref[sec:record_web_media_rt]{Record Web Media in real-time}. The \textit{Transport} buttons are well defined there also. \textit{Step 4}: When the media has finished playing, use the \texttt{Stop} icon on the Recording menu – the fourth icon next to the \textit{Transport} label - to stop the recording (figure~\ref{fig:vhs02}). diff --git a/parts/Stuff.tex b/parts/Stuff.tex new file mode 100644 index 0000000..4cfe501 --- /dev/null +++ b/parts/Stuff.tex @@ -0,0 +1,184 @@ +\chapter{How some stuff works}% +\label{cha:how_stuff_works} + +This section describes in detail some areas of Cinelerra to help explain how things work. + +\section{Copy/Paste and Highlight Usage}% +\label{sec:copy_paste_highlight_usage} + +There are 3 types of copy/cut and paste methods which exist in X windows, and most modern programs use 2 of them. The 3 cases are: + +\begin{description} + \item[cut\_buffers 0-7] these are obsolete but they still work and are the simplest to use. + \item[highlighting] called primary selection; almost all clipboard programs only use this. + \item[copy and paste] called secondary (or clipboard) selection. Some more modern programs use \texttt{ctrl-C/ctrl-X} and \texttt{ctrl-V} for this (some use other keys or qualifiers, like \texttt{shift}). +\end{description} + +\subsection*{How it works:}% +\label{sub:how_it_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. + +When a paste is used in a target window, the target program requests the advertised selection data. This may access one of two buffers depending on which type of load/paste action is used. The user loads a \textit{cut buffer} via \texttt{drag} select or \texttt{ctrl-C/ctrl-X}, and pastes a \textit{cut buffer} via \texttt{middle mouse} press or \texttt{ctrl-V}. + +\subsection*{Cinelerra cut and paste:}% +\label{sub:cinelerra_cut_paste} + +\subsubsection*{1. Text cut and paste operations}% +\label{ssub:text_cut_paste_operations} + +To use a text selection, create a drag selection in textboxes by pressing and holding left mouse button with the pointer over the beginning of the text selection, then move the pointer over the desired selection to the selection end, then release the mouse button. This continuously reloads the \textit{primary} clipboard buffer and highlights the text selection. It can then be pasted to most programs by pressing the middle mouse button with the pointer over the text insertion point. Some examples of these programs are \textit{xterm}, \textit{gnome-terminal}, \textit{cinelerra}, and \textit{browser} input text boxes. After you create a text selection, if you then press \texttt{ctrl-C} the selection will also be copied to the \textit{secondary} (or \textit{clipboard}) selection buffer. This second paste buffer can be used for a more lasting save effect, since it will not be lost until you again press \texttt{ctrl-C} (copy). Using \texttt{ctrl-X} (cut) will also copy the selection to the secondary clipboard buffer, and then delete the selection from the textbox. If you press \texttt{ctrl-V} (or paste) in a target window, the secondary selection will be inserted at the target window cursor. If a text selection exists in the target window, it is replaced by the pasted text. + +\subsubsection*{2. Media cut and paste operations}% +\label{ssub:media_cut_paste_operations} + +To create a media selection, highlight a region on the cinelerra media timeline, then use the main menubar or compositor/viewer edit panel to operate the clip cut, copy, or copy-keyframe menu buttons. This selection can then be pasted to a target selection on the timeline using the main menubar or compositor/viewer edit panel to operate the clip paste or paste-keyframe operation. Also, by using the resource window you can select the \textit{Clips} folder and right mouse the resources list box, then use the \texttt{Paste Clip} menu item to paste the selection to a named clip. Additionally, these methods work between running instances of cinelerra, which means you can move media clips between the cinelerra program instances. The clip data is also copied to the secondary clipboard buffer. This makes it possible to examine the clip content directly if so desired. + +\subsubsection*{3. The older cut\_buffer method}% +\label{ssub:older_cut_buffer_method} + +\begin{itemize} + \item For text, if there is an active selection when a window closes, it uses \texttt{cut\_buffer0}. Normally when a paste is performed, the target window \textit{notifies} the selection owner to \textit{send it now} when you do a paste, but if the window has closed there is no source window, so no pasting. Some programs, like cinelerra, use \texttt{cut\_buffer0} as a fallback. This makes it possible to paste data from a closed window. + \item To move media clip, data \texttt{cut\_buffer2} is used because it does not require the selection owner interface, and works simply and reliably. This buffer is not normally in use by other programs. +\end{itemize} + +\subsection*{Final note}% +\label{sub:final_note} + +When a text selection is set, the selected text is redrawn using selected-highlight color when the textbox loses focus. This convenience feature shows the active text selection as you move the pointer to the new target window. When a new selection is set anywhere else on your screen, the current text selection will be redrawn using the inactive-highlight color as the textbox loses selection ownership. In most cinelerra themes, the drag selection text-highlight color is BLUE ($\#0000FF$), the selected-highlight color is SLBLUE ($\#6040C0$) -- really sort of purple, and the inactive-highlight color is MEGREY ($\#AFAFAF$). + +\section{Playing is Different than Seeking/Positioning!}% +\label{sec:playing_seeking_positioning} + +\subsection{Playing/Seeking}% +\label{sub:playing_seeking} + +\textit{Seeking} targets and displays the next frame. The next frame is targeted because frame zero has no previous. When you seek, you reposition to just before the target frame, and since the play direction has not been established (there is no direction when seeking) it shows you the next frame. This produces the expected behavior when you seek to frame zero; you see the first frame. Seeking displays in the compositor what you are getting ready to work with/edit/etc; always showing the next frame in relation to the cursor. Technically, since seeking just resets the position, it would be correct not to update the compositor, but it is best to seek and show the next frame to confirm that it is the frame you expected to see. + +\textit{Playing} shows you what has just been played in the compositor window. It is not the same as seeking. When you use \texttt{keypad 1} to play frame forward, then the 1st frame that is played and shown in the compositor window is frame zero (which was already displayed). The position is incremented to 1. Press \texttt{keypad 1} yet again, and the next frame displayed is 1, and the new position is 2, and so on. According to the implemented strategy, the insertion point moves to track playback. When playback stops, the insertion point stays where playback stopped. Thus, with playback you change the position of the insertion point. + +Simple explanation of what you will be seeing in the compositor when playing: + +\begin{description} + \item[Play forward] the frame to the right of the cursor in the timeline gets displayed. + \item[Play backward] the frame to the left of the cursor in the timeline gets displayed. +\end{description} + +The reason behind this \textit{play} methodology is that you want to know what you just played so that you know what matches what you just saw/heard in case that is the desired stuff. You don't want the compositor to show you what you have not yet played -- you need to see this frame to analyze/check to see if it is what you want. This behavior applies to any playing operation, such as the \texttt{keypad} or \texttt{Frame forward / Frame reverse} buttons. You can still easily see the actual insertion point in the zoombar at the bottom of the timeline -- sixth button over or 3rd button from the right side. Also note the following: + +\begin{description} + \item[Blinking insertion point on the timeline] seeking/positioning was the last operation. + \item[Solid non-blinking insertion point on timeline] playing was the last operation. +\end{description} + +\subsubsection*{Example and explanation}% +\label{ssub:example_explanation} + +\begin{enumerate} + \item open a small example of 10 numbered frames (or use the \texttt{Title} plugin to add a timestamp) + \item press \texttt{f} to \textit{fit} the timeline + \item make sure \texttt{settings $\rightarrow$ align\_cursor\_on\_frames} is set + \item seek to frame 4 by clicking on the timeline at position 4, compositor shows the 5th frame, since the + media counts from 1 and the timeline counts from 0. This is correct behavior. + \item press \texttt{KP1} to play next frame. According to playback strategy: \textit{When play is forwards, the next unit is displayed, and the position is advanced one unit}. So the next frame is 4, (shows the $5^{th}$ frame) it is displayed. The position is advanced from 4 to 5. This is correct behavior. + \item press \texttt{KP4} to play the previous frame. According to playback strategy: \textit{When play is in reverse, the previous unit is displayed, and the position is reduced one unit}. So the previous frame is 4, (shows the $5^{th}$ frame) it is displayed. The position is reduced from 5 to 4. This is correct behavior. +\end{enumerate} + +If you watch the zoombar (bottom of main window) position, it shows the current position is just before the next frame to be displayed when going forwards, and just after the frame to be displayed when going backward. + +To recap, position is usually set in the program as a location that is between a previous and next frame/sample unit such that the next unit equals the seek target. After position is reset using a \textit{seek} operation, the next unit is displayed, which is the seek target. When \textit{play is forward}, the next unit is shown, and the position is advanced one unit. When \textit{play is in reverse}, the previous unit is shown, and the position is reduced one unit. At the beginning, there is no previous, and at the end, there is no next, but silence is rendered at the end. + +\subsection{Always Show Next Frame}% +\label{sub:always_show_next_frame} + +Since some users prefer the insertion pointer to reflect the same as the Compositor a choice is available. For playing forward, there is a preference option which results in what looks like 1 was added to the frame displayed in the Compositor window. To enable this mode, check the box \texttt{Always show next frame}, and this will be saved to \texttt{.bcast5}. The option checkbox is in the \texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab and when checked, any forward \textit{plays} in the Compositor window show the same frame as you would with a seek. Reverse plays and plays using a selection or In/Out pointers (with \texttt{Ctrl}) work the same as without this preference set. But you will no longer see the odd behavior where if you frame advance forward and then frame advance backward, the displayed frame does not change -- instead it will change and look more natural. +A color indicator that shows in the main track canvas timeline and the compositor timeline reminds the user which mode is currently active. The cursor in the compositor turns \textit{red} for default mode and \textit{white} for \textit{Always show next frame} mode. The top portion of the insertion cursor in the track canvas mirrors this, with red for default and white otherwise. + +Figure~\ref{fig:cursor01} using the default \textit{playing} method where the frame in the compositor is the one that was just played; in this case play was in the forward direction. Note that the insertion pointer in the main track canvas shows 01:20 but the compositor show 01:19 so you know what you last saw. Also, the cursor/cursor tops in both windows is red.\todo{I make copy/paste from your examples; but no arrow is displayed} + +\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]{images/cursor01.png}}; + \node [yshift=-20mm, xshift=-1cm,anchor=east] at (img1.north west) (Compositor) {Red cursor in Compositor}; + \node [yshift=-26mm, xshift=-1cm,anchor=east] at (img1.north west) (Timeline) {red cursor in Timeline}; + \end{tikzpicture} + \caption{"Default" mode with red cursors} + \label{fig:cursor01} +\end{figure} + +Figure~\ref{fig:cursor02} using the \textit{Always show next frame} method where the frame in the compositor is the same one that would have shown with a seek; in this case play was in the forward direction. Note that the insertion pointer in the main track canvas shows 01:20 and the compositor shows 01:20. Also, the cursor/cursor tops in both windows is white. + +\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]{images/cursor02.png}}; + \node [yshift=-21mm, xshift=-1cm,anchor=east] at (img1.north west) (Compositor) {White cursor in Compositor}; + \node [yshift=-27mm, xshift=-1cm,anchor=east] at (img1.north west) (Timeline) {White cursor in Timeline}; + \end{tikzpicture} + \caption{"Always show next frame" mode with white cursors} + \label{fig:cursor02} +\end{figure} + +\subsection{Seeking Issues}% +\label{sub:seeking_issue} + +If you have an issue playing a video and not seeing it in the Compositor (just see a black screen), it is most likely due to the media not being designed to be \textit{editable}. It is most likely not damaged. Generally it just does not have keyframes which are needed for seeking which is what is done when you move around the media and start playing in the middle. The media plays just fine in the compositor if you always play from the beginning because then you don’t need keyframes to seek. You can get around this problem if you proxy the media. A good choice to use for the proxy would be \texttt{use scalar}, \texttt{ffmpeg/mp4} and size of $\frac{1}{2}$. The proxied media can then seek and you will see it play in the compositor because keyframes exist. + +\section{Color Space and Color Range Affecting Playback}% +\label{sec:color_space_range_playback} + +Playback \textit{single step} and \textit{plugins} cause the render to be in the session color model, while continuous playback with no plugins tries to use the file’s best color model for the display (for speed). +This can create a visible effect of a switch in color in the Compositor, usually shown as grayish versus over-bright. + +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{gray} offset. The \textit{YUV mpeg} color range is $[16..235]$ for Y, $[16..240]$ for UV, and the color range used by \textit{YUV jpeg} is $[0..255]$ for YUV. + +The mpeg YUV color range $[16..235]$ looks sort of like an old TV if it is viewed on a display with jpeg range $[0..255]$. A common expression for the short \textit{mpeg} color range is \textit{compressed} color range. If you are using color compressed data with no display decompression, or using uncompressed data and the display is configured to use compression, the color range will appear \textit{squished} or \textit{stretched}, as too gray or too much contrast. + +The \texttt{use X11 direct when possible} preference with X11 as your video driver, generally means that you value speed over color range. When you use this feature and the color range preference is mismatched, the color switch offsets will still appear. This is a personal choice solely for improved speed. + +There is now program code to look for RGB versus YUV color model mismatches. You can override the default setup, which mirrors the original code, via the following. + +\texttt{Settings $\rightarrow$ Preferences $\rightarrow$ Appearance} tab in the lower left hand corner (Figure~\ref{fig:color}): + +\begin{description} + \item[YUV color space] default choice is BT601, alternate is BT709 (High Definition), BT2020 (UHD) + \item[YUV color range] default choice is JPEG, alternate is MPEG +\end{description} + + +\begin{figure}[htpb] + \centering + \includegraphics[width=0.6\linewidth,keepaspectratio]{images/color.png} + \captionsetup{labelformat=empty, textformat=empty} + \caption[Color space and Color range]{No text} + \label{fig:color} +\end{figure} + +\section{Simple Animation (Festival)}% +\label{sec:simple_animation_festival} + +This functionality was added to cinelerra by the original author to create simple animation. The file type for this animation is \textit{Scene}. + +To get started making a simple animated movie copy from the directory: \texttt{/cinelerra/tests} the \texttt{text2movie} and \texttt{text2movie.xml}. You can see what this does via \texttt{File $\rightarrow$ Load\dots $\rightarrow$ text2movie.xml}. The file text2movie acts like a normal asset, except changes to it are immediately reflected on the timeline without reloading and the length is infinite. You can just edit the text2movie file to change the script. If the length of the movie increases, drag the right edit handle to extend the edit or use the pulldown \texttt{Edit $\rightarrow$ edit length}. There is one audio channel created for every character. The frame rate, sample rate, frame size, and camera angles are fixed. To see these values, right click on the asset and look at the \textit{Asset info}. + +Currently the functionality that is implemented focuses on dialog between two people. The models are defined in model files saved in Cinelerra's executable directory (for example, \texttt{/opt/cinelerra/models}). The character model and voice is selected separately in the script. The model files have the same name that appears in the script and are usually saved in the directory the script is in, but there is a defined search path, if not. You can create new models for the script without affecting the entire system. These models define the total size of the model along with the images used -- the model images are 2D png images because all the animations are baked. Since there is no 3D renderer, no custom movement is supported. + +There are currently 2 actions implemented: + +\begin{enumerate} + \item Character2 can cut off character1 if character1's dialog ends in “\dots” + \item Inserting “[pause]” anywhere causes the character to pause. This is useful for adjusting the timing of dialog. +\end{enumerate} + +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. + +\section{Textbox Non-std Character / Unicode Insertion}% +\label{sec:textbox_non_std_character_unicode} + +If you want to enter a special character -- like a bullet, an accent grave character, or a mathematical summation symbol -- you can use the unicode equivalent in a textbox to do so. In the textbox, keyin \texttt{Ctrl-Shift-U} which puts you into single character unicode mode, then keyin the numerical value for the intended single character followed by the carriage return. For a voluminous list of possible special characters, you can go to \url{https://unicode-table.com/en/} on the internet to choose by highlighting a character to get its numerical equivalence. For example, $U+2022$ is a bullet. If you make a mistake, you can use the \texttt{backspace} key or if you want to exit unicode-insert-mode, use the \texttt{ESC} key. This feature is especially useful with the \textit{Title} plugin and for naming Tracks in the main window. + +However, it is worth mentioning that some special characters are available via the \textit{compose} key in the current distribution. \url{https://en.wikipedia.org/wiki/Compose_key} . + diff --git a/parts/Transition.tex b/parts/Transition.tex index da113d1..3e244c1 100644 --- a/parts/Transition.tex +++ b/parts/Transition.tex @@ -1,7 +1,8 @@ \chapter{Transition Plugins}% \label{cha:transition_plugin} -When one edit ends and another edit begins, the default behavior is to have the first edit's output immediately become the output of the second edit when played back. Transitions are a way for the first edit’s output to become the second edit’s output with different variations. The audio and video transitions are listed in the Resources window as figure~\ref{fig:transition}. +When playing a section of media where one edit ends and another edit begins on the timeline, +the usual result is that the first edit's output immediately is followed by the second edit. Transitions provide a better method whereby the first edit’s output becomes the second edit’s output. There are several different audio and video transitions listed in the Resources window as figure~\ref{fig:transition}. \begin{figure}[htpb] \centering @@ -11,23 +12,45 @@ When one edit ends and another edit begins, the default behavior is to have the \end{figure} Note the colored bar above the \textit{Shape Wipe} transition. +This bar near the transition symbol shows the position and the length of the transition. -Transitions may only apply to the matching track type. Transitions under audio transitions can only apply to audio tracks. Transitions under video transitions can only apply to video tracks. +Transitions only apply to the matching track type; that is audio transitions only apply to audio tracks +and video transitions only apply to video tracks. An example usage of a transition follows: \begin{enumerate} - \item Load a single video file and cut away a section from the center or make a blade cut so that you make two edits out of a single file. Make sure the edit boundary between the two edits is visible on the timeline. - \item Go to the \textit{Resources window} and click on the \texttt{Video transitions} folder. Drag a transition from the transition list onto the second video edit on the timeline. A colored box highlights over where the transition will appear. Releasing over the $2^{nd}$ edit applies the transition between the $1^{st}$ and $2^{nd}$ edit. + \item Load a single video file and delete a sizable section from within the video which will result in two edits of that file. Now you should see the edit boundary between the two edits on the timeline. + \item Move to the \textit{Resources window} and click on the \texttt{Video transitions} folder. Choose a transition by highlighting it and then drag and drop it on the second video edit on the timeline. A colored box shows where the transition will appear and when you release the mouse the $2^{nd}$ edit applies the transition between the $1^{st}$ and $2^{nd}$ edit. +The beginning of the edit will be covered by the transition, if the insertion point or the In point is over an edit. \end{enumerate} -Once the transition is in place, it can be edited similarly to a plugin. Move the \textit{pointer} over the transition and \texttt{right click} to bring up the transition menu. The show option brings up specific parameters for the transition in question if any. The \texttt{length} option adjusts the length of the transition in seconds. The \texttt{detach} option removes the transition from the timeline. If the insertion point or the In point is over an edit, the beginning of the edit is covered by the transition. +Some Transitions have parameters that can be modified. To see these, move the \textit{pointer} over the transition and \texttt{right click} which brings up a menu. A \texttt{Show} option will pop up a window if there are parameters that you can change to different values. +An \texttt{On} option makes it possible to turn off the transition so that it will not be in effect in case you want to only enable it under certain conditions. The default value for this will be checked On. +A \texttt{Length} option lets you adjust the length in seconds of the time that the transition will be in play. Values modified in the Show or Length will be saved for use the next time that transition is used until changed again. +The \texttt{Detach} option deletes the transition from the timeline. When you drag and drop a different transition on top of an existing transition on the timeline, it replaces the previous one. -Dragging and dropping transitions from the Resource window to the Program window can be tedious so there are shortcuts to solve this issue. Once you drag a transition from the Resources window, the \texttt{U} and \texttt{u} keys will paste the same transition. The U key pastes the last video transition and the u key pastes the last audio transition on all the recordable tracks. Another easy way to add the same transition to multiple edits is to get into \texttt{Arrow mode} (Drag and Drop editing), select the edits you would like to add the transition to and use the Video or Audio pulldown to \texttt{Attach transition}. Choose which transition you would like and click the checkmark \texttt{OK}. You can also set your default transition at any time by doing so in the Attach transition popup box – highlight your choice, and then at the bottom, click on the button \texttt{Set Default Transition}. You will see that name appear. +There are some shortcuts to alleviate the dragging and dropping of transitions when you want to do a lot of them in various places on the timeline. After you have established the parameter values for a transition that you have dragged from the Resources window, you can use \texttt{U} and \texttt{u} keys to paste the same transition; +the \texttt{U} key pastes the last video transition while the \texttt{u} key pastes the last audio transition on all recordable tracks. +Alternatively, you can add the same transition to multiple edits when in \texttt{Arrow mode} (Drag and Drop editing), by selecting edits to add the transition to and use the Video/Audio pulldown to \texttt{Attach transition}. Select the desired transition and then click the checkmark \texttt{OK}. You can set a default transition in the Attach transition popup box – by highlighting your choice, then click on the button \texttt{Set Default Transition}, and you will see that transition become the new default. -Transitions make two edits overlap for a certain amount of time. Cinelerra does not move edits during transitions. Instead it uses spare frames from the source file to lengthen the first edit enough to make it overlap the second edit for the duration of the transition. The exact point in time when the transition takes effect is the beginning of the second edit. The transition lasts a set amount of time into the second edit. For example, if you set a duration of 1 second for a dissolve transition, it will not start at the last 0.5 second of the first edit and continue 0.5 second into the second edit. In fact, it will start exactly at the beginning of the second edit and last for 1 second into that second edit. On the timeline a colored bar over the transition symbol visually represents the position and the duration of the transition. -The most important consequence of this behavior is that the first asset needs to have enough spare data after the end boundary to fill the transition into the second edit. Spare data duration should be equal or greater than the length of the transition effect set in the Length parameter of the transition popup menu. -If the last frame shown on the timeline is the last frame of the source file, Cinelerra will lengthen the first edit using the last frame only, with the unpleasant result of having the first edit freezing into the transition. +The way that transitions work is that two edits overlap for some length of time and no edits are actually moved during the transitions. +Instead extra frames from the source file will be used to lengthen the first edit enough to make it overlap the second edit for the length of the transition. The transition takes effect exactly at the beginning of the second edit and lasts for the specific length of time you set into the second edit. +What this means is that if you set a duration of 2 seconds for a flash transition, it will not start at the last 1 second of the first edit and continue 1 second into the second edit. Instead the transition will start exactly at the beginning of the second edit and last for 2 seconds into that second edit. +This is why it is necessary that the first edit needs to have extra data after the end boundary to provide enough fill for the transition length into the second edit. +In the case where the last frame on the timeline is the last frame of the source, Cinelerra will lengthen the first edit using only that last frame. The result will not be what you want because the first edit will freeze into the transition. -It should be noted that when playing transitions from the timeline to a hardware accelerated video device, the hardware acceleration will usually be turned \textit{off} momentarily during the transition and \textit{on} after the transition, in order to render the transition. Using an un-accelerated video device for the entire timeline normally removes the disturbance. +When playing transitions, software rendering is used. This means that if you are using hardware, as with the video driver set to OpenGL, hardware acceleration will usually be turned \textit{off} during the transition and \textit{on} after the transition. Consequently, you may notice small anomalies while playing this section but you can avoid this by switching to using X11 video driver instead or just ignore it because when you create your final render that is always done in software only. + +When “Info on” is enabled via the right mouse button over an empty space in the Resources window (or the shortcut of the letter “i” is used), a short description will be provided in the lower right hand corner of that window for the current transition that the mouse is on. + +Once you have dragged and dropped a transition to the timeline, right mouse click on the transition and a pop-up menu will appear which provides an opportunity to make some changes. These are described next for all video and audio transitions. + +\begin{description} + \item[Show] If available, clicking on this will pop up a transition specific menu. + \item[On] Toggle on/off the transition effect so that you can see what it looks like when played. Ordinarily this will be checked to indicate it is On. + \item[Transition length] When you click on Length, a pop-up menu will come up. Set the length in seconds, frames, samples, \textit{H:M:S:frm} or \textit{H:M:S.xxx} for the transition to complete either by typing a value into the text box or using the tumbler arrows. In addition you can use the mouse wheel to change the length in real time. You will see the colored bar get longer or shorter as you change the length. +There is a down arrow next to the Seconds box allowing for changing to the other dimensions of frames, samples, etc. The mathematics is automatically done for you to convert it to seconds if not already in that dimension. + \item[Detach] Remove the transition from the timeline. +\end{description} \section{Audio Transitions}% \label{sec:audio_transition} @@ -40,15 +63,6 @@ Creates a smooth transition from one audio source edit to another. The crossfade \section{Video Transitions}% \label{sec:video_transition} -In order to use a transition that you have dragged to the timeline, first right mouse click on the transition icon in the timeline. A menu will pop-up with the following controls: - -\begin{description} - \item[Show] Pops up the transition specific menu if available (not available on the dissolve transition). - \item[On] Toggle on/off the transition effect. - \item[Transition length] Set the length in seconds, frames, samples, \textit{H:M:S:frm} or \textit{H:M:S.xxx} for the transition to complete. In addition you can use the mouse wheel to change the length in real time. - \item[Detach] Remove the transition from the timeline. -\end{description} - \subsection*{BandSlide}% \label{sub:bandslide} @@ -59,7 +73,12 @@ Bands slide across video and you see the image slide. Bands wipe across the video and you see the mask slides. -\subsection{Flash}% +\subsection*{Dissolve}% +\label{sub:dissolve} + +A soft dissolve where the In segment becomes more transparent while the Out segment begins to gradually show in its place until fully there. + +\subsection*{Flash}% \label{sub:flash} The video flashes when transitioning between segments. @@ -72,11 +91,22 @@ Video switches segments via a small rectangular view that gradually grows to ful \subsection*{Shape Wipe}% \label{sub:shape_wipe} -Wipe a specific shape across the video. Currently available shapes are: \textit{burst}, \textit{circle}, \textit{clock}, \textit{heart}, \textit{specks}, \textit{spiral}, \textit{tile2x2h}, and \textit{tile2x2v}. +Wipe a specific shape across the video. Currently available shapes are: \textit{burst}, \textit{Butterfly}, + \textit{circle}, \textit{Circle-h\_01}, \textit{Circle-h\_02}, \textit{Circle-v\_01}, \textit{Circle-v\_02}, + \textit{clock}, \textit{Clouds\_01}, \textit{Clouds\_02}, \textit{Cross-Iris\_01}, \textit{Cross\_01}, +\textit{Diagonal-Curve}, \textit{Diagonal-Linear}, \textit{Diamond-Iris\_01}, \textit{Diamond\_01}, + \textit{Diamond\_02}, \textit{Diamond\_03}, \textit{Double-Door-h}, \textit{Double-Door-v}, \textit{Gravity}, +\textit{heart}, \textit{Linear-h}, \textit{Linear-v}, \textit{Plasma\_01}, + \textit{specks}, \textit{spiral}, \textit{tile2x2h}, \textit{tile2x2v}, \textit{Venetian-Blinds-h-x05}, + \textit{Venetian-Blinds-h-x10}, \textit{Venetian-Blinds-v-x05}, and \textit{Venetian-Blinds-v-x10}. + +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}. -You can add your own images to the Shape Wipe transition and there are some free ones available to download such as at \url{assistcg.com}. +You can add your own images to the Shape Wipe transition and there are some free ones available to download such as under the Video$\rightarrow$Transitions pulldown at \url{assistcg.com}. -To include new images in the Shape Wipe Transition, simply copy the file \texttt{{shape}.png} to your location of cinelerra in the subdirectory \texttt{plugins/shapes}. +To include new images in the Shape Wipe Transition, simply copy the file \texttt{{shape}.png} to the + subdirectory \texttt{plugins/shapes} in your cinelerra directory path. \subsection*{Slide}% \label{sub:slide} diff --git a/parts/Windows.tex b/parts/Windows.tex index 328032b..414dbd2 100644 --- a/parts/Windows.tex +++ b/parts/Windows.tex @@ -1,11 +1,19 @@ \chapter{The 4+ Windows}% \label{cha:the_4_windows} +\begin{figure}[htpb] + \centering + \includegraphics[width=\linewidth,keepaspectratio]{images/Fenstergrundposition-en.png} + \captionsetup{labelformat=empty, textformat=empty} + \caption[The four windows (cc-by-sa Olaf)]{No text} + \label{fig:Fenstergrundposition-en} +\end{figure} + \section{Program Window}% \label{sec:program_window} The main window is called the Program window and contains the timeline as well as the entry point for all menu driven operations. -It is often just called the “timeline”. +It is often just called the \textit{timeline}. The timeline consists of a vertical stack of tracks with a horizontal representation of time. This defines the output of rendering operations and what is saved when you save files. To the left of the timeline is the patchbay which contains options affecting each track.