Updated to correctly reflect Georgy's code fixes and enhancements for ContextHelp
[goodguy/cin-manual-latex.git] / parts / FFmpeg.tex
1 \chapter{FFmpeg Interactions}%
2 \label{cha:ffmpeg_interactions}
3 \index{ffmpeg}
4
5 \CGG{} uses ffmpeg for decoding and encoding media, thus there are many opportunities available to manipulate options.
6
7 \section{FFmpeg Early Probe Explanation}%
8 \label{sec:ffmpeg_early_probe_explanation}
9 \index{ffmpeg!early probe}
10 \index{ffmpeg!try first}
11 \index{ffmpeg!try last}
12
13 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}.
14
15 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.
16 The green icon is located in the upper right hand corner of the main window.
17
18 When the icon is green, ffmpeg probes early is enabled and you will see it reads
19  \textit{Currently: Try FFMpeg first} when moving over the icon button in the upper 
20 right hand corner of the screen.  When the icon is capital "C", ffmpeg probes early is disabled so that 
21 ffmpeg probes late and it reads \textit{Currently: Try FFMpeg last}.  The initial default state of 
22 the icon is on, that is, ffmpeg probes first. Suggestion is to leave it on except in a few special 
23 cases where it may be better to have early probes disabled.  When you mouse over the main menu icon 
24 toggle button, the text displays ffmpeg's \textit{Currently} set position.  Just left mouse click to change to the other setting.
25 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.
26
27 Figure~\ref{fig:ff} shows (1) greenish colored icon in upper right hand corner of main window indicating
28 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.
29
30 \begin{figure}[htpb]
31     \centering
32     \includegraphics[width=0.9\linewidth]{ff.png}
33     \caption{The three icons of \textit{FF Probe}}
34     \label{fig:ff}
35 \end{figure}
36
37 \section{How to Create FFmpeg Options Files}%
38 \label{sec:create_ffmpeg_options_files}
39 \index{ffmpeg!options files}
40
41 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.  
42 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.
43 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.
44 AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}. 
45
46 \subsection{File naming convention}%
47 \label{sub:file_naming_convention}
48
49 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.
50 AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}. 
51
52 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.
53
54 \begin{center}
55     \small
56     \begin{tabular}{l m{25em}}
57         \toprule
58         ffmpeg/ffmpeg.opts & global ffmpeg options, always used \\
59         ffmpeg/decode.opts & global decoder options, used when opening existing files for decoding \\
60         ffmpeg/encode.opts & global encoder options, used when creating new files for encoding \\
61         ffmpeg/audio/audio.opts & audio encoder options, used when creating audio streams \\
62         ffmpeg/video/video.opts & video encoder options, used when creating video streams \\
63         ffmpeg/plugin.opts & parameters for ffmpeg filters as audio/video plugins \\
64         \bottomrule
65     \end{tabular}
66 \end{center}
67
68 \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.
69
70 \paragraph{Encoder Options:} \index{ffmpeg!encoder options} Within the audio/video subdirectories of the first level ffmpeg directory, the \texttt{typ.ext} files are for encoder (rendering) setups.
71
72 \begin{center}
73     \begin{longtable}{l p{23em}}
74         \toprule
75         ffmpeg/audio & directory of audio encoder settings \\
76         \midrule
77         audio.opts & options used by all audio encoders \\
78         typ1.ext, typ2.ext, … & are all *.ext type choices for encoding audio \\
79         ext.dfl & contains the default selection used when ext is first selected \\
80         \midrule
81         ffmpeg/video & directory of video encoder settings \\
82         \midrule
83         video.opts & options used by all video encoders \\
84         typ1.ext, typ2.ext, … & are all *.ext type choices for encoding video \\
85         ext.dfl & contains the default selection used when ext is first selected \\
86         \midrule
87         ffmpeg/format & presets needed to initialize audio / video formats \\
88         \bottomrule
89     \end{longtable}
90 \end{center}
91
92 \subsection{Option File Format / Content}%
93 \label{sub:option_file_format_content}
94 \index{ffmpeg!option file format}
95
96 For the option files a specific format must be followed in creating the file content.
97 AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}. 
98 In \texttt{typ.ext} encoder parameter files, the first line is defined as:
99
100 \begin{lstlisting}[style=sh]
101       muxer codec
102 (or)    muxer codec | bitstream filter [ bitstream filter options ]
103 \end{lstlisting}
104
105 where the | represents piping the codec data through the bitstream filter. The rest of the lines in the file should look as follows:
106
107 \begin{lstlisting}[style=sh]
108       # in column one is a comment
109       id1   value1
110 (or)    id2 = value2
111 \end{lstlisting}
112
113 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:
114
115 \begin{lstlisting}[style=sh]
116       bitrate 4000000
117 (or)    bitrate = 5000000
118 \end{lstlisting}
119
120 There are 4 special id's recognized by \CGG{} which cause special processing.  They are:
121
122 \begin{description}
123     \item[duration] overrides the probe duration when opening media for decoding
124     \item[video\_filter] adds a video stream filter, eg.\ edgedetect,\dots at the stream level
125     \item[audio\_filter] adds an audio stream filter, eg.\ echo,\dots at the stream level
126     \item[loglevel] sets the library logging level, as quiet, panic, \dots verbose, debug
127 \end{description}
128
129 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:
130
131 \begin{lstlisting}[style=sh]
132 aspect 4:3
133 \end{lstlisting}
134
135 Below shows an example:  \texttt{decode.opts} which is used when the ffmpeg decoder is initialized.
136
137 \begin{lstlisting}[style=sh]
138 # apply at init decode
139 loglevel=fatal
140 formatprobesize=5000000
141 scan_all_pmts=1
142 threads=auto
143 \end{lstlisting}
144
145 The encoder options you see in the \CGG{} menus depend on the files in these directories, \textsc{NOT THE CODE}.  If you add files, you will get to use more variety.
146
147 In the \textit{\CGG{}} 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 \texttt{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.
148
149 These extensions create audio / video media classes:
150
151 \texttt{dvd \quad  m2ts \quad  mkv \quad  mp3 \quad  mp4 \quad  mpeg  \quad qt \quad  pro}
152
153 which become the choices in the render pulldown menu.
154
155 So if you want to create a \textit{mov} codec class, add two new files to the ffmpeg configuration directory:
156
157 \texttt{audio/aud.mov}  and  \texttt{video/vid.mov}
158
159 Now you will see this as what you can choose in the rendering choices for ffmpeg.
160 Inside the file you will see that the first line is special.  It is the muxer and codec.  For example:
161
162 \begin{lstlisting}[style=sh]
163 h264     libx265
164 \end{lstlisting}
165
166 The contents may be something like:
167
168 \begin{lstlisting}[style=sh]
169 # <path>/video/vid.mov 
170 mp4 libx265
171 bitrate 4000000
172 \end{lstlisting}
173
174 This will code an mp4 formatted file using the \textit{lib264} codec encoder.
175
176 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.
177 For example:
178
179 \begin{lstlisting}[style=sh]
180 # <path>/audio/aud.mov
181 mp4 pcm_mulaw
182 \end{lstlisting}
183
184 This will create mp4 media using audio format \textit{pcm\_mulaw} coding.
185
186 Both the audio and the video are using mp4 mux format, and so there will be 2 streams:
187 \begin{enumerate}
188     \item x265 video
189     \item pcm\_mulaw audio
190 \end{enumerate}
191
192 When the menu popup is created, there may be many choices for that class type, so you may want defaults.  That can be specified as:
193
194 \texttt{audio/<class>.dfl}  and  \texttt{video/<class>.dfl}
195
196 \begin{lstlisting}[style=sh]
197 # audio/mov.dft
198 aud.mov
199 \end{lstlisting}
200
201 \begin{lstlisting}[style=sh]
202 # video/mov.dft =
203 vid.mov
204 \end{lstlisting}
205
206 The above will be the default choice when the menu opens.  
207
208 When you see problems in using the new options files you have created and put into place, add the following line to \texttt{ffmpeg/encoder.opts}:
209
210 \begin{lstlisting}[style=sh]
211 loglevel=verbose
212 \end{lstlisting}
213
214 sometimes that will be enough to see what has caused a failure, or even catch unexpected results.
215
216 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 \textit{x264-params} line tweaking values to throw off the detection/error termination code.
217
218 \begin{lstlisting}[style=sh]
219 # <path>/ffmpegvideo/test.mp4
220 mp4 libx264
221 preset=slow
222 x264-params keyint=25:min-keyint=4:qpmin=3:qpmax=33:qp_step=4:merange=8
223 crf 20
224 \end{lstlisting}
225
226 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. 
227
228 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.  
229 If you send any new options files to \href{mailto:cin@lists.cinelerra-gg.org}{cin@lists.cinelerra-gg.org}, it will be given consideration to being added to the baseline for future deliverables.
230
231 To get a listing of the current ffmpeg supported formats and codecs that can be made to work with \CGG{}, provided there are option files added, run the following commands.  This should be done from the \texttt{<build>} directory substituting the location of \texttt{<build>} where you have installed \CGG{} 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}.
232
233 \begin{lstlisting}[style=sh]
234 /<build>/cinelerra-5.1/thirdparty/ffmpeg-4.2/ffmpeg -formats > /tmp/ff-formats.txt
235 /<build>/cinelerra-5.1/thirdparty/ffmpeg-4.2/ffmpeg -codecs > /tmp/ff-codecs.txt
236 \end{lstlisting}
237
238 \subsection{Complete Options File Example}%
239 \label{sub:complete_options_file_example}
240
241 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.
242
243 Add the file named  \texttt{./ffmpeg/audio/aac256k.pro} which contains the following lines:
244
245 \begin{lstlisting}[style=sh]
246 mov aac
247 strict -2
248 b 256000
249 \end{lstlisting}
250
251 (Note that in the example above, even though the bitrate is set here to $256000$, it can be     overridden by the render menu settings).
252
253 Add the file named \texttt{./ffmpeg/audio/pro.dfl} which contains the following lines:
254
255 \begin{lstlisting}[style=sh]
256 aac256k.pro
257 \end{lstlisting}
258
259 Add the file named \texttt{./ffmpeg/video/prores.pro} which contains the following lines:
260
261 \begin{lstlisting}[style=sh]
262 mov prores
263 profile=2
264 # lines of comments
265 \end{lstlisting}
266
267 Add the file named \texttt{./ffmpeg/video/pro.dfl} which contains the following lines:
268
269 \begin{lstlisting}[style=sh]
270 prores.pro
271 \end{lstlisting}
272
273 Then to use and to get 10 bit depth and preserve depth from decode to encode:
274
275 \begin{enumerate}
276     \item load media
277     \item use \texttt{settings $\rightarrow$ format} to set the frame rate, sample rate/channels, aspect ratio, 
278     color model = rgb\_float or rgba\_float if blending
279     \item press Shift-R and select FFmpeg format type \textit{pro}
280     \item select target path
281     \item check OK, and watch for messages in the terminal window
282 \end{enumerate}
283
284 \subsection{Modifying FFmpeg Format Options inside \CGG{}}%
285 \label{sub:modifying_ffmpeg_cinelerra}
286 \index{ffmpeg!option file format}
287 \index{ffmpeg!wrench}
288 \index{ffmpeg!private options}
289
290 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.
291
292 As an example, instead of reading the entire 264 library
293 information, you only have to look at the shown available options.
294 Both the video and the audio are browsable. The options visible in
295 the \textit{Audio/Video Preset} textbox are the final values which
296 are used when rendering once you have checked OK\@.  For assistance
297 in choosing the options you want, use the view popup to see the
298 objects that go with the selected format tool, highlight the option,
299 modify the parameter value in the box at the top of the
300 \textit{Options} window based on what you want, and then click
301 apply.  Updated parameter values or new parameters will be appended
302 at the bottom.  Note that when you highlight an option, a tooltip
303 will show up when available in the lower right hand corner which
304 describes the option.  Also note that the Format and Codec types are
305 shown on the top line of the Options window.
306
307 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.
308
309 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}
310
311 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.
312
313 \begin{figure}[htpb]
314     \centering
315     \includegraphics[width=1.0\linewidth]{video-preset.png}
316     \caption{FFmpeg wrench, video preset, view and format options}
317     \label{fig:video-preset}
318 \end{figure}
319
320 Figure~\ref{fig:audio-preset02} shows \textit{ffmpeg} video for the Kind. Note the colored tooltip in the lower right hand corner describing the highlighted option.  Also note the allowed \textit{Range} values above the box provided for keyins. There is also the \textit{format} window with private options.
321
322 \begin{figure}[htpb]
323     \centering
324     \includegraphics[width=1.0\linewidth]{audio-preset02.png}
325     \caption{FFmpeg wrench, audio preset, view and format options}
326     \label{fig:audio-preset02}
327 \end{figure}
328
329 \section{The FFmpeg Image2 Streams}%
330 \label{sec:ffmpeg_image2_streams}
331 \index{ffmpeg!image2 streams}
332
333 Another feature gained from using ffmpeg in \CGG{} takes advantage of what is being referred to as the \textit{\%d trick}.  This trick uses the ffmpeg muxer image2 and a filename template to create a series of image files of a given type.  A specific example is described below.
334 AppImage does not provide this capability unless you use the workaround as described in the Appendix \nameref{cha:faq_problems_workarounds}. 
335
336 To encode a series of $48$\,bit tiff output image files, add a file to the \CGG{} data ffmpeg/video subdirectory as in:
337
338 \begin{lstlisting}[style=sh]
339 # {path_to_cinelerra}/bin/ffmpeg/video/tiff.dfl
340 tiff48.tif
341 \end{lstlisting}
342
343 Then create an ffmpeg video encoder parameters file in the same directory:
344
345 \begin{lstlisting}[style=sh]
346 # {path_to_cinelerra}/bin/ffmpeg/video/tiff48.tiff
347 image2 tiff
348 pixel_format=rgb48
349 \end{lstlisting}
350
351 This will define a new ffmpeg encoder format which is a video image file format that uses the tiff codec for encoding, and a pixel\_format of \textit{rgb48} (or a similar equivalent such as rgb48le).  Next load up your project and set up for a Render using \texttt{File $\rightarrow$ Render} in the usual way.  Now the tricky part; the output file name should contain a \texttt{\%d} which will be the frame number used in the image output filename as in:  Select a file to render to  \texttt{/tmp/tiff\_images/img\%03d.tiff}.  You will get multiple files as output -- one for each frame!
352
353 The resulting directory of images can be opened for reading by simply opening the template path.  As in: \texttt{File $\rightarrow$ Load Files} \texttt{/tmp/tiff\_images/img\%03d.tiff}.  You will notice a file named the same as the template, which has been automatically created, is empty, is needed, and has to remain with the set.
354
355 \section{Raw Input Opts File for Video/Audio}%
356 \label{sec:raw_input_opts_video_audio}
357 \index{ffmpeg!raw input options}
358
359 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:
360
361 \begin{lstlisting}[style=sh]
362 # Video file name:    /tmp/buddy.mov
363 # Opts file name:     /tmp/buddy.opts
364 # Contents of opts file:
365
366 format=rawvideo
367 codec=rawvideo
368 video_size=352x240
369 pixel_format=yuv420p
370 duration=90.25
371 \end{lstlisting}
372
373 \section{FFmpeg Items of Note}%
374 \label{sec:ffmpeg_items_note}
375 \index{ffmpeg!notes}
376
377 \begin{description}
378     \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.
379     \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.
380     \item[Outstanding Issues with ffmpeg:] There are some problems that need to be addressed by the ffmpeg developer group that adversely affect \CGG{}.  These are stated below with the hopes that that group will fix them as time permits.
381     \begin{itemize}
382         \item Make all the default parameters operational.  When they are not, the \CGG{} 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.
383         \item Make the filter config function project the new parameter data into the filter function at any point
384         during filter operation.  This is so that continuous updates can be done as the plugin operates.
385         \item Improve seek codec restarts.  The past predictor must be reset or reconstructed after a seek.  The  only documented way to seek is open/seek/play.  Reopening the format layer is very expensive.
386     \end{itemize}
387 \end{description}