parts/FFmpeg.tex

   1 \chapter{FFmpeg Interactions}%
   2 \label{cha:ffmpeg_interactions}
   3
   4 Cinelerra-GG uses ffmpeg for decoding and encoding media, thus there are many opportunities available to manipulate options.
   5
   6 \section{FFmpeg Early Probe Explanation}%
   7 \label{sec:ffmpeg_early_probe_explanation}
   8
   9 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.
  10
  11 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.
  12
  13 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.
  14 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.
  15
  16 Figure~\ref{fig:ff} show (1) reddish colored FF in upper right hand corner of main window indicating
  17 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.
  18
  19 \begin{figure}[htpb]
  20     \centering
  21     \includegraphics[width=0.7\linewidth]{images/ff.png}
  22     \caption{The three colors of \textit{Probe}}
  23     \label{fig:ff}
  24 \end{figure}
  25
  26 \section{How to Create FFmpeg Options Files}%
  27 \label{sec:create_ffmpeg_options_files}
  28
  29 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.
  30 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.
  31
  32 \subsection{File naming convention}%
  33 \label{sub:file_naming_convention}
  34
  35 In Cinelerra's ffmpeg configuration directory you will see files as listed and described below.  File type and extension names are the key for Cinelerra'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, \texttt{ext} refers to a set of files with file names matching the \texttt{*.ext} file extension.  And \texttt{typ} refers to a type of format / codec combination used, that is, the media type.
  36
  37 In the ffmpeg configuration directory there are a series of options files used when encoding or decoding audio or video.  They are read in the order from top to bottom and only the files needed for the current operation are added to the active configuration.
  38
  39 \begin{center}
  40     \begin{tabular}{l l}
  41         \toprule
  42         ffmpeg/ffmpeg.opts & global ffmpeg options, always used \\
  43         ffmpeg/decode.opts & global decoder options, used when opening existing files for decoding \\
  44         ffmpeg/encode.opts & global encoder options, used when creating new files for encoding \\
  45         ffmpeg/audio/audio.opts & audio encoder options, used when creating audio streams \\
  46         ffmpeg/video/video.opts & video encoder options, used when creating video streams \\
  47         ffmpeg/plugin.opts & parameters for ffmpeg filters as audio/video plugins \\
  48         \bottomrule
  49     \end{tabular}
  50 \end{center}
  51
  52 \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 \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.
  53
  54 \paragraph{Encoder Options:} Within the audio /video subdirectories of the first level ffmpeg directory, the \texttt{typ.ext} files are for encoder (rendering) setups.
  55
  56 \begin{center}
  57     \begin{longtable}{l l}
  58         \toprule
  59         ffmpeg/audio & directory of audio encoder settings \\
  60         \midrule
  61         audio.opts & options used by all audio encoders \\
  62         typ1.ext, typ2.ext, … & are all *.ext type choices for encoding audio \\
  63         ext.dfl & contains the default selection used when ext is first selected \\
  64         \midrule
  65         ffmpeg/video & directory of video encoder settings \\
  66         \midrule
  67         video.opts & options used by all video encoders \\
  68         typ1.ext, typ2.ext, … & are all *.ext type choices for encoding video \\
  69         ext.dfl & contains the default selection used when ext is first selected \\
  70         \midrule
  71         ffmpeg/format & presets needed to initialize audio / video formats \\
  72         \bottomrule
  73     \end{longtable}
  74 \end{center}
  75
  76 \subsection{Option File Format / Content}%
  77 \label{sub:option_file_format_content}
  78
  79 For the option files a specific format must be followed in creating the file content.
  80 In \texttt{typ.ext} encoder parameter files, the first line is defined as:
  81
  82 \begin{lstlisting}[language=bash]
  83       muxer codec
  84 (or)    muxer codec | bitstream filter [ bitstream filter options ]
  85 \end{lstlisting}
  86
  87 where the | represents piping the codec data through the bitstream filter. The rest of the lines in the file should look as follows:
  88
  89 \begin{lstlisting}[language=bash]
  90       # in column one is a comment
  91       id1   value1
  92 (or)    id2 = value2
  93 \end{lstlisting}
  94
  95 Only one equals sign is allowed and it is just for readability.  There may be any number of id / value pair lines in a media definition, including zero. A typical line might be:
  96
  97 \begin{lstlisting}[language=bash]
  98       bitrate 4000000
  99 (or)    bitrate = 5000000
 100 \end{lstlisting}
 101
 102 There are 4 special id's recognized by cinelerra which cause special processing.  They are:
 103
 104 \begin{description}
 105     \item[duration] overrides the probe duration when opening media for decoding
 106     \item[video\_filter] adds an video stream filter, eg. edgedetect,\dots at the stream level
 107     \item[audio\_filter] adds an audio stream filter, eg. echo,\dots at the stream level
 108     \item[loglevel] sets the library logging level, as quiet, panic, \dots verbose, debug
 109 \end{description}
 110
 111 All other id's should be in the ffmpeg documentation, and correspond to the global, muxer, and codec option names and values used by ffmpeg.  For example to set the aspect ratio to 4:3, use:
 112
 113 \begin{lstlisting}[language=bash]
 114 aspect 4:3
 115 \end{lstlisting}
 116
 117 Below shows an example:  \texttt{decode.opts} which is used when the ffmpeg decoder is initialized.
 118
 119 \begin{lstlisting}[language=bash]
 120 # apply at init decode
 121 loglevel=fatal
 122 formatprobesize=5000000
 123 scan_all_pmts=1
 124 threads=auto
 125 \end{lstlisting}
 126
 127 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.
 128
 129 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.
 130
 131 These extensions create audio / video media classes:
 132
 133 \texttt{dvd \quad  m2ts \quad  mkv \quad  mp3 \quad  mp4 \quad  mpeg  \quad qt \quad  pro}
 134
 135 which become the choices in the render pulldown menu
 136
 137 So if you want to create a \textit{mov} codec class, add two new files to the ffmpeg configuration directory:
 138
 139 \texttt{audio/aud.mov}  and  \texttt{video/vid.mov}
 140
 141 Now you will see this as what you can choose in the rendering choices for ffmpeg.
 142 Inside the file you will see that the first line is special.  It is the muxer and codec.  For example:
 143