Ogg Theora Cook Book


ffmpeg2theora is a very advanced Theora encoding application. The advanced functionality comes at the price of having to use a command line, as no graphical user interface is provided. For GNU/Linux, Mac OS X and Windows download ffmpeg2theora from http://v2v.cc/~j/ffmpeg2theora/download.html. If you are running a recent version of GNU/Linux, chances are good that your distribution already comes with software packages for ffmpeg2theora, that can be installed with the distribution's software packet manager.

Basic Usage

Open a command prompt and enter:

ffmpeg2theora my_source_video.mp4 -o my_theora_video.ogv

 This encodes the source video file "my_source_video.mp4", creating a new Theora video file named "my_theora_video.ogv".

Adding Parameters

When you are unhappy with the result of encoding, it's time to start tuning encoding parameters. We'll start with setting the video quality of the encoded video. Quality is given as a number in range 0 (lowest quality, smallest file) up to 10 (highest quality, largest file). Try this to encode at a high video quality of 9, and a very high audio quality of 6:

ffmpeg2theora my_source_video.mp4 -o my_theora_video.ogv \
    --videoquality 9 --audioquality 6

The following example exposes the basic encoding parameters. Just copy-paste and adjust it to your needs:

ffmpeg2theora my_source_video.mp4 -o my_theora_video.ogv \
    --videoquality 9 --audioquality 6 \
    --croptop 0 --cropbottom 0 --cropleft 0 --cropright 0 \
    --width 720 --height 576 \
    --title "Video Title" --artist "Artist Name" --date "1997-12-31"

If you do not wish to scale the video's frame size, drop the --width and --height options. There is no way to specify a scale factor, so check the input video's size and computing the target frame size as required. In most cases it is better to only specify one of the --width or --height options, the missing option is then automatically adjusted to a correct value.

Advanced Options

Ffmpeg2theora supports a multitude of other parameters for advanced use, which cannot all be described in detail here. To get an overview of all available options and short descriptions, type:

ffmpeg2theora --help

Depending on the operating system you are using, you might be able to open up the ffmpeg2theora manual by typing

man ffmpeg2theora

 The following options often prove useful:


Copy any audio-video synchronization of the source video file to the destination Theora video. Depending on the source video used, this may fix problems of audio-video delay drift introduced by the encoding process.

--keyint <N> 

Set the keyframe interval, i.e. the number of frames between keyframes, of the generated file. Large values of <N> lead to a reduced file size, however seeking and cutting does not work well with Theora files that have a large keyframe interval.

 --framerate <N>

Set the frame rate of the generated video file. In case you are attempting to create Theora videos with extremely small file size, try specifying half the input video's framerate.

 --starttime <N>  --endtime <M>

These two options allow you to copy only a part of the source video when encoding. Specify <N> and <M> as the number of seconds from the start of the video.

Two-Pass Encoding

The upcoming version 0.25 of ffmpeg2theora is going to support a two-pass encoding mode, which is described in this section. Once version 0.25 is released, just download it from http://v2v.cc/~j/ffmpeg2theora/download.html. The examples given below are not going to work with older versions.

Why Two-Pass Encoding

A lot of hype is surrounding two-pass encoding. Many people assume that you need to encode in two passes to achieve a constant subjective quality throughtout a video. This is how it used to be for many non-free video codecs such as DivX. However, as we have seen, ffmpeg2theora is well capable of encoding for a constant target quality in a single pass using option --videoquality.

The only real advantage of using two-pass mode over using --videoquality, is the ability to create a Theora video of a given file size. Imagine you want to encode a video, which must fit onto a single CD with 700 MB of available storage. You want a constant video quality, but in advance you can't possibly guess which --videoquality will exactly hit 700 MB. Using two-pass mode exactly achieves that.

Using Two-Pass Mode

So you want to encode "my_source_video.mp4" into a Theora video, with a file size of exactly 700 MB. ffmpeg2theora does not allow you to directly specify the size of the encoded file. Instead you specify the average video bitrate for the video. Note that the audio is also going to require some data, which has to be taken into account.

To decide on an average video bitrate for the file we first need to find out the duration of the source video "my_source_video.mp4". Ffmpeg2theora can help us with that. Type:

ffmpeg2theora --info "my_source_video.mp4"

Which prints, among other information:

  "duration": 2365.165100,
  "bitrate": 6437.331055,


 The duration shown is in seconds. If we divide the available 700 MB of space by the 2365 seconds to encode, we come to an average byte rate of 296 kByte/s. Multiplied by 8 we get the average bit rate of 2368 kBit/s.

We cannot use the full 2368 kBit/s for our video only. We also have an audio track, that is going to take 128 kBit/s. The average video bit rate we can use is thus 2240 kBit/s. Of this we subtract another 1% to account for any overhead in the encapsulation that is used to contain the video and audio tracks. This leaves us with 2218 kBit/s for the video and 128 kBit/s for the audio.

The following command is going to perform the two-passs encoding, creating the Theora video file "my_theora_video.ogv":

ffmpeg2theora my_source_video.mp4 -o my_theora_video.ogv \
    --two-pass --videobitrate 2218 --audiobitrate 128

Note that unlike other two-pass encoders, only one invocation of the ffmpeg2theora command is required. If you require more control, performing cropping, scaling etc., feel free to copy-paste other options from the examples given in previous sections.