+\begin{lstlisting}[language=bash]
+h264 libx265
+\end{lstlisting}
+
+The contents may be something like:
+
+\begin{lstlisting}[language=bash]
+# <path>/video/vid.mov
+mp4 libx265
+bitrate 4000000
+\end{lstlisting}
+
+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 example:
+
+\begin{lstlisting}[language=bash]
+# <path>/audio/aud.mov
+mp4 pcm_mulaw
+\end{lstlisting}
+
+This will create \textit{mp4} media using audio format \texttt{pcm\_mulaw} coding.
+
+Both the audio and the video are using \textit{mp4} mux format, and so there will be 2 streams:
+\begin{enumerate}
+ \item x265 video
+ \item pcm\_mulaw audio
+\end{enumerate}
+
+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:
+
+\texttt{audio/<class>.dfl} and \texttt{video/<class>.dfl}
+
+\begin{lstlisting}[language=bash]
+# audio/mov.dft
+aud.mov
+\end{lstlisting}
+
+\begin{lstlisting}[language=bash]
+# video/mov.dft =
+vid.mov
+\end{lstlisting}
+
+The above will be the default choice when the menu opens.
+
+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}:
+
+\begin{lstlisting}[language=bash]
+loglevel=verbose
+\end{lstlisting}
+
+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.
+
+\begin{lstlisting}[language=bash]
+# <path>/ffmpegvideo/test.mp4
+mp4 libx264
+preset=slow
+x264opts 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]
+# <path>/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 <build>directory substituting the location of <build> 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}.
+
+\begin{lstlisting}[language=bash]
+/<build>/cinelerra-5.1/thirdparty/ffmpeg-4.1.1/ffmpeg -formats > /tmp/ff-formats.txt
+/<build>/cinelerra-5.1/thirdparty/ffmpeg-4.1.1/ffmpeg -codecs > /tmp/ff-codecs.txt
+\end{lstlisting}
+
+\subsection{Complete Options File Example}%
+\label{sub:complete_options_file_example}
+
+For illustrative purposes, here is an example of the options files that need to be added for using the ffmpeg \textit{ProRes 422} format. This makes it possible to transcode to \texttt{h264.mov} with FFmpeg retaining \textit{10-bit yuv422p} from the source to the target output video.
+
+Add the file named \texttt{./ffmpeg/audio/acc256k.pro} which contains the following lines:
+
+\begin{lstlisting}[language=bash]
+mov aac
+strict -2
+b 256000
+\end{lstlisting}
+
+(Note that in the example above, even though the bitrate is set here to $256000$, it can be overridden by the render menu settings).
+
+Add the file named \texttt{./ffmpeg/audio/pro.dfl} which contains the following lines:
+
+\begin{lstlisting}[language=bash]
+acc256k.pro
+\end{lstlisting}
+
+Add the file named \texttt{./ffmpeg/video/med422p10.pro} which contains the following lines:
+
+\begin{lstlisting}[language=bash]
+mov prores
+preset medium
+pix_fmt yuv422p10le
+\end{lstlisting}
+
+Add the file named \texttt{./ffmpeg/video/pro.dfl} which contains the following lines:
+
+\begin{lstlisting}[language=bash]
+med422p10.pro
+\end{lstlisting}
+
+Then to use and to get 10 bit depth and preserve depth from decode to encode:
+
+\begin{enumerate}
+ \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 select target path
+ \item check \texttt{OK}, and watch for messages in the terminal window
+\end{enumerate}
+
+\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.
+
+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.
+
+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.
+
+Figure~\ref{fig:video-preset} show \textit{ffmpeg} video for as the Kind. Note the x264opts in the Video Preset window immediately below.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.8\linewidth]{images/video-preset.png}
+ \caption{FFmpeg wrench, video preset and view options}
+ \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.
+
+\begin{figure}[htpb]
+ \centering
+ \includegraphics[width=0.8\linewidth]{images/audio-preset02.png}
+ \caption{FFmpeg wrench, audio preset and view options}
+ \label{fig:audio-preset02}
+\end{figure}
+
+\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.
+
+To encode a series of $48$ bit tiff output image files, add a file to the cinelerra data ffmpeg/video subdirectory as in:
+
+\begin{lstlisting}[language=bash]
+# \dots/ffmpeg/video/tiff.dfl
+tiff48.tif
+\end{lstlisting}
+
+Then create an ffmpeg video encoder parameters file in the same directory:
+
+\begin{lstlisting}[language=bash]
+# \dots/ffmpeg/video/tiff48.tiff
+image2 tiff
+pixel_format=rgb48
+\end{lstlisting}
+
+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 \texttt{rgb48} (or a similar equivalent such as rgb48le). Next load up your project and set up for a Render using 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!
+
+The resulting directory of images can be opened for reading by simply opening the template path. As in: 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.
+
+\section{Raw Input Opts File for Video/Audio}%
+\label{sec:raw_input_opts_video_audio}
+
+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 \texttt{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{lstlisting}[language=bash]
+# Video file name: /tmp/buddy.mov
+# Opts file name: /tmp/buddy.opts
+# Contents of opts file:
+
+format=rawvideo
+codec=rawvideo
+video_size=352x240
+pixel_format=yuv420p
+duration=90.25
+\end{lstlisting}
+
+\section{FFmpeg Items of Note}%
+\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[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.
+ \item Make the filter config function project the new parameter data into the filter function at any point
+ during filter operation. This is so that continuous updates can be done as the plugin operates.
+ \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.
+ \end{itemize}
+\end{description}
projects / goodguy / cin-manual-latex.git / blobdiff