##
Option File Format / Content

For the option files a specific format must be followed in creating the file content. AppImage does not provide this capability unless you use the workaround as described in the Appendix FAQ, Known Problems and Workarounds. In typ.ext encoder parameter files, the first line is defined as:

          muxer codec
    (or) 	muxer codec | bitstream filter [ bitstream filter options ]

where the | represents piping the codec data through the bitstream filter. The rest of the lines in the file should look as follows:

          # in column one is a comment
          id1   value1
    (or)	id2 = value2

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:

          bitrate 4000000
    (or)	bitrate = 5000000

There are 4 special id's recognized by CINELERRA-GG which cause special processing. They are:

duration
  overrides the probe duration when opening media for decoding
video_filter
  adds a video stream filter, eg. edgedetect,...at the stream level
audio_filter
  adds an audio stream filter, eg. echo,...at the stream level
loglevel
  sets the library logging level, as quiet, panic, ...verbose, debug

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:

    aspect 4:3

Below shows an example: decode.opts which is used when the ffmpeg decoder is initialized.

    # apply at init decode
    loglevel=fatal
    formatprobesize=5000000
    scan_all_pmts=1
    threads=auto

The encoder options you see in the CINELERRA-GG menus depend on the files in these directories, NOT THE CODE. If you add files, you will get to use more variety.

In the CINELERRA-GG 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.

These extensions create audio / video media classes:

dvd m2ts mkv mp3 mp4 mpeg qt pro

which become the choices in the render pulldown menu.

So if you want to create a mov codec class, add two new files to the ffmpeg configuration directory:

audio/aud.mov and video/vid.mov

Now you will see this as what you can choose in the rendering choices for ffmpeg. Inside the file you will see that the first line is special. It is the muxer and codec. For example:

    h264     libx265

The contents may be something like:

    # <path>/video/vid.mov
    mp4 libx265
    bitrate 4000000

This will code an mp4 formatted file using the 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 all the streams in the file being written. For example:

    # <path>/audio/aud.mov
    mp4 pcm_mulaw

This will create mp4 media using audio format pcm_mulaw coding.

Both the audio and the video are using mp4 mux format, and so there will be 2 streams:

1. x265 video
2. pcm_mulaw audio

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:

audio/<class>.dfl and video/<class>.dfl

    # audio/mov.dft
    aud.mov

    # video/mov.dft =
    vid.mov

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 ffmpeg/encoder.opts:

    loglevel=verbose

sometimes that will be enough to see what has caused a failure, or even catch unexpected results.

There is an 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 x264-params line tweaking values to throw off the detection/error termination code.

    # <path>/ffmpegvideo/test.mp4
    mp4 libx264
    preset=slow
    x264-params keyint=25:min-keyint=4:qpmin=3:qpmax=33:qp_step=4:merange=8
    crf 20

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 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-GG, 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-GG on your system and the ffmpeg may be a different version than 4.2 as used below. Then look at the output created in /tmp/ff-formats.txt and codecs.txt.

    /<build>/cinelerra-5.1/thirdparty/ffmpeg-4.2/ffmpeg -formats > /tmp/ff-formats.txt
    /<build>/cinelerra-5.1/thirdparty/ffmpeg-4.2/ffmpeg -codecs > /tmp/ff-codecs.txt