\CGG{} uses ffmpeg for decoding and encoding media, thus there are many opportunities available to manipulate options.
\section{FFmpeg Early Probe Explanation}%
\label{sec:ffmpeg_early_probe_explanation}
\CGG{} uses ffmpeg for decoding and encoding media, thus there are many opportunities available to manipulate options.
\section{FFmpeg Early Probe Explanation}%
\label{sec:ffmpeg_early_probe_explanation}
-When you open media, a series of libraries and codec functions are used to \textit{probe} the data, to see if it can determine the type of file format and codec parameters needed to correctly decode the file. If ffmpeg probes early -- \textit{Try FFMpeg first} is in effect for the FF button -- it will usually find some way to try to decode just about any contemporary media file. But there are some times that the built in codecs are actually a better choice. A lot of this may fall into the category of personal preference. For example, some may prefer the mpeg library in the \CGG{} code over the ffmpeg code because it has more decoding capability and seems to be more robust when the media is damaged. In that case you will want the FF button to read \textit{Try FFMpeg last}.
+When you open media, a series of libraries and codec functions are used to \textit{probe} the data, to see if it can determine the type of file format and codec parameters needed to correctly decode the file. If ffmpeg probes early -- \textit{Try FFMpeg first} is in effect for the FF button (green icon) -- it will usually find some way to try to decode just about any contemporary media file. But there are some times that the built in codecs are actually a better choice. A lot of this may fall into the category of personal preference. For example, some may prefer the mpeg library in the \CGG{} code over the ffmpeg code because it has more decoding capability and seems to be more robust when the media is damaged. In that case you will want the FF button to read \textit{Try FFMpeg last}.
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.
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.
-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
+When the icon is green, ffmpeg probes early is enabled and you will see it reads
+ \textit{Currently: Try FFMpeg first} when moving over the icon button in the upper
+right hand corner of the screen. When the icon is capital "C", 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
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
-The ffmpeg early probe state is saved between sessions and is also affected by choices made in Probe Order (refer to section~\ref{sub:probe_order_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.
+The ffmpeg early probe state is saved between sessions and is also affected by choices made in Probe Order (refer to section~\nameref{sub:probe_order_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} 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 \CGG{} warns you accordingly.
+Figure~\ref{fig:ff} shows (1) greenish colored icon 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 icon is different because you highlighted the icon); and (3) "C" icon indicates ffmpeg will be used last and you are changing the behavior so that \CGG{} warns you accordingly.
This section describes how the FFmpeg options files work for decoding and encoding and goes into great detail. It will make more sense if you look at \CGG{}'s ffmpeg config directory and the \CGG{} menus at the same time.
It is meant to include everything necessary for complete understanding. You will be able to personalize your own options files without knowing all of the information included below if you know the basics. The word encoding is used interchangeably with the word rendering.
The possible combinations for ffmpeg options files are literally combinatorial -- that is a lot (factorial!). The allowed media file format / codec choices are much more flexible than you might realize. When the ffmpeg design was initially added, some parameter files which describe the choices which the program uses had to be created. There are way too many to enumerate in the deliverable \CGG{} package. Some quite detailed information for how ffmpeg options work is given here and hopefully, enough basics for simple understanding. It may all seem complicated at first, but will become obvious.
This section describes how the FFmpeg options files work for decoding and encoding and goes into great detail. It will make more sense if you look at \CGG{}'s ffmpeg config directory and the \CGG{} menus at the same time.
It is meant to include everything necessary for complete understanding. You will be able to personalize your own options files without knowing all of the information included below if you know the basics. The word encoding is used interchangeably with the word rendering.
The possible combinations for ffmpeg options files are literally combinatorial -- that is a lot (factorial!). The allowed media file format / codec choices are much more flexible than you might realize. When the ffmpeg design was initially added, some parameter files which describe the choices which the program uses had to be created. There are way too many to enumerate in the deliverable \CGG{} package. Some quite detailed information for how ffmpeg options work is given here and hopefully, enough basics for simple understanding. It may all seem complicated at first, but will become obvious.
\subsection{File naming convention}%
\label{sub:file_naming_convention}
In \CGG{}'s ffmpeg configuration directory you will see files as listed and described below. File type and extension names are the key for \CGG{}'s use of ffmpeg. Basically the \texttt{.opts} file extension represents options; \texttt{.dfl} represents defaults; and all the rest are media types. For example one media type is quicktime so that \texttt{*.qt} file names would be the \textit{quicktime} choices. In the file names below, \textit{ext} refers to a set of files with file names matching the \texttt{*.ext} file extension. And \textit{typ} refers to a type of format / codec combination used, that is, the media type.
\subsection{File naming convention}%
\label{sub:file_naming_convention}
In \CGG{}'s ffmpeg configuration directory you will see files as listed and described below. File type and extension names are the key for \CGG{}'s use of ffmpeg. Basically the \texttt{.opts} file extension represents options; \texttt{.dfl} represents defaults; and all the rest are media types. For example one media type is quicktime so that \texttt{*.qt} file names would be the \textit{quicktime} choices. In the file names below, \textit{ext} refers to a set of files with file names matching the \texttt{*.ext} file extension. And \textit{typ} refers to a type of format / codec combination used, that is, the media type.
ffmpeg/ffmpeg.opts & global ffmpeg options, always used \\
ffmpeg/decode.opts & global decoder options, used when opening existing files for decoding \\
ffmpeg/encode.opts & global encoder options, used when creating new files for encoding \\
ffmpeg/audio/audio.opts & audio encoder options, used when creating audio streams \\
ffmpeg/video/video.opts & video encoder options, used when creating video streams \\
ffmpeg/plugin.opts & parameters for ffmpeg filters as audio/video plugins \\
ffmpeg/ffmpeg.opts & global ffmpeg options, always used \\
ffmpeg/decode.opts & global decoder options, used when opening existing files for decoding \\
ffmpeg/encode.opts & global encoder options, used when creating new files for encoding \\
ffmpeg/audio/audio.opts & audio encoder options, used when creating audio streams \\
ffmpeg/video/video.opts & video encoder options, used when creating video streams \\
ffmpeg/plugin.opts & parameters for ffmpeg filters as audio/video plugins \\
-\paragraph{Decoder options:} Normally, only \texttt{ffmpeg.opts} and \texttt{decode.opts} are used when reading/decoding files, but may be specialized if a \texttt{<path>/media.opts} exists for a given \texttt{<path>/media.ext} file. For example, if you want to only fail on fatal errors and to always use the video filter, edgedetect, when working with your media file \texttt{dreaming.y4m}, then create a file \texttt{dreaming.opts} in the same directory with the contents of \textit{loglevel=fatal} on the first line and \textit{video\_filter=edgedetect} on the next. These specialized settings will override the defaults. The fatal loglevel is especially handy for lesser quality media.
+\paragraph{Decoder options:} \index{ffmpeg!decoder options} Normally, only \texttt{ffmpeg.opts} and \texttt{decode.opts} are used when reading/decoding files, but may be specialized if a \texttt{<path>/media.opts} exists for a given \texttt{<path>/media.ext} file. For example, if you want to only fail on fatal errors and to always use the video filter, edgedetect, when working with your media file \texttt{dreaming.y4m}, then create a file \texttt{dreaming.opts} in the same directory with the contents of \textit{loglevel=fatal} on the first line and \textit{video\_filter=edgedetect} on the next. These specialized settings will override the defaults. The fatal loglevel is especially handy for lesser quality media.
In \texttt{typ.ext} encoder parameter files, the first line is defined as:
\begin{lstlisting}[style=sh]
In \texttt{typ.ext} encoder parameter files, the first line is defined as:
\begin{lstlisting}[style=sh]
For illustrative purposes, here is an example of the options files that need to be added for using the ffmpeg \textit{ProRes 422} format. This makes it possible to transcode to \texttt{h264.mov} with FFmpeg retaining \textit{10-bit yuv422p} from the source to the target output video.
For illustrative purposes, here is an example of the options files that need to be added for using the ffmpeg \textit{ProRes 422} format. This makes it possible to transcode to \texttt{h264.mov} with FFmpeg retaining \textit{10-bit yuv422p} from the source to the target output video.
Add the file named \texttt{./ffmpeg/audio/pro.dfl} which contains the following lines:
\begin{lstlisting}[style=sh]
Add the file named \texttt{./ffmpeg/audio/pro.dfl} which contains the following lines:
\begin{lstlisting}[style=sh]
-\subsection{Viewing \& Modifying FFmpeg Format Options inside \CGG{}}%
-\label{sub:viewing_modifying_ffmpeg_cinelerra}
+\subsection{Modifying FFmpeg Format Options inside \CGG{}}%
+\label{sub:modifying_ffmpeg_cinelerra}
+\index{ffmpeg!option file format}
+\index{ffmpeg!wrench}
+\index{ffmpeg!private options}
There are thousands of options for using ffmpeg. Now it is possible to \textit{view} the available options for a particular video and audio choice by using the \textit{wrench icon} and then clicking on the \textit{view} box. FFmpeg has to be the selected file format for this feature to be visible. It makes it a lot easier since only the applicable options show up as opposed to everything that ffmpeg can do. These options are just \textit{Hints} and some may be missing due to the way that ffmpeg options are coded -- \CGG{} shows the option data ffmpeg has exposed.
There are thousands of options for using ffmpeg. Now it is possible to \textit{view} the available options for a particular video and audio choice by using the \textit{wrench icon} and then clicking on the \textit{view} box. FFmpeg has to be the selected file format for this feature to be visible. It makes it a lot easier since only the applicable options show up as opposed to everything that ffmpeg can do. These options are just \textit{Hints} and some may be missing due to the way that ffmpeg options are coded -- \CGG{} shows the option data ffmpeg has exposed.
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 \textit{profile=high422}, \textit{preset=medium}, or \textit{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.
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 \textit{profile=high422}, \textit{preset=medium}, or \textit{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} shows \textit{ffmpeg} video as the Kind. Note the x264opts (should actually be x264-params now) in the Video Preset window immediately below.
+With the \textit{format} button we can access further parameters, called \textit{Private Options}. A window opens that contains a new view button. More details in the section: \nameref{sub:extra_cin_option_ffmpeg}
+
+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. There is also the \textit{format} window with private options.
- \includegraphics[width=0.8\linewidth]{video-preset.png}
- \caption{FFmpeg wrench, video preset and view options}
+ \includegraphics[width=1.0\linewidth]{video-preset.png}
+ \caption{FFmpeg wrench, video preset, view and format options}
- \includegraphics[width=0.8\linewidth]{audio-preset02.png}
- \caption{FFmpeg wrench, audio preset and view options}
+ \includegraphics[width=1.0\linewidth]{audio-preset02.png}
+ \caption{FFmpeg wrench, audio preset, view and format options}
\label{fig:audio-preset02}
\end{figure}
\section{The FFmpeg Image2 Streams}%
\label{sec:ffmpeg_image2_streams}
\label{fig:audio-preset02}
\end{figure}
\section{The FFmpeg Image2 Streams}%
\label{sec:ffmpeg_image2_streams}
To encode a series of $48$\,bit tiff output image files, add a file to the \CGG{} data ffmpeg/video subdirectory as in:
\begin{lstlisting}[style=sh]
To encode a series of $48$\,bit tiff output image files, add a file to the \CGG{} data ffmpeg/video subdirectory as in:
\begin{lstlisting}[style=sh]
tiff48.tif
\end{lstlisting}
Then create an ffmpeg video encoder parameters file in the same directory:
\begin{lstlisting}[style=sh]
tiff48.tif
\end{lstlisting}
Then create an ffmpeg video encoder parameters file in the same directory:
\begin{lstlisting}[style=sh]
Raw video is not affected by decoding on read in. This makes it very attractive to provide raw image data for editing and rendering media. A wide variety of raw formats are available via the ffmpeg file interface. To load media in a raw format, select \textit{try ffmpeg first} and create an accompanying \textit{opts} file. The opts files must be in the same directory as your media, with the same base name, and the \texttt{.opts} extension. The opts file contents should reflect your video setup. An example follows:
Raw video is not affected by decoding on read in. This makes it very attractive to provide raw image data for editing and rendering media. A wide variety of raw formats are available via the ffmpeg file interface. To load media in a raw format, select \textit{try ffmpeg first} and create an accompanying \textit{opts} file. The opts files must be in the same directory as your media, with the same base name, and the \texttt{.opts} extension. The opts file contents should reflect your video setup. An example follows:
\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.
\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.