this is a mirror of http://www.dogphilosophy.net/SECTION-Technical_Stuff/ogg-theora-microhowto.html

Unofficial Ogg Theora Micro-HOWTO

Okay, thanks to some stubbornness on my part and helpfulness on the part of people on the theora-dev mailing list, I got Ogg Theora Alpha 1 compiled up, installed, and running within a day or so of its release around 25 September 2002.

I went to the Prelinger archives (the public-domain video archive at www.archive.com) to find a high-quality original to re-encode as a test. The encoder worked just fine, and playback as well, and I thought I'd share what I found with the thought that it might help others and hopefully help keep development and interest active.

COMPILING:
Both the encoder and the player rely on STATIC versions of their respective libraries. I believe both the ogg and vorbis libraries build static versions as well as shared when compiled, but some (e.g. libartsc) don't. (Most pre-compiled packages probably include static versions, however.)

Otherwise, simply running the supplied ./autogen.sh script followed by 'make' should build the code just fine. 'make install' places the theora library (by default) in /usr/local/lib, but does not copy the example player or encoder. If you want them moved out of the examples directory in the source tree, you'll have to do it by hand (you may or may not want to bother, considering that both are A)merely examples and B)still in early 'alpha' testing, though in my limited experience thus far they both seem to perform reasonably well.)

ENCODING:
The encoder, as the README states, expects raw, uncompressed 'yuv4mpeg' data for video, and '.wav' files or data (pcm) for sound. As the readme also explains, mplayer ( http://www.mplayerhq.hu ) is an easy way to export from an existing video file to this format.

It's not explicitly stated in the README, but the example encoder's output is to stdin, so the output needs to be redirected in the command line to the appropriate filename (or, if desired, piped directly to another program for output.)

For those who don't have a 300GB hard drive to a raw, uncompressed file on, you can actually pipe yuv4mpeg data 'on-the-fly' from mplayer to the example encoder by creating a fifo "pipe" file:

mkfifo -m 660 stream.yuv
mkfifo -m 660 stream.wav

The example encoder, as of this writing, seems to have some trouble handling both audio and video from fifo at the same time. Some experimentation and more advice from the theora-dev mailing list leads to the conclusion that the problem involves the order that the audio and video packets are coming out of mplayer in. Until Theora Alpha 2 (due out in another month or so) is released (possibly with a fix for this in the example encoder?) this can be worked around by using TWO mplayer processes to do the export - one for just the video (and -ao null) and the other for just the audio (-vo null). Encoding, then, goes something like this (note, I run each of the following in separate terminals/Konsole sessions for 'cleanliness' in the display, but as far as I know, you could theoretically run the whole thing in one terminal...):

mplayer -ao pcm -aofile stream.wav -vo null file_to_be_encoded.avi &
mplayer -vo yuv4mpeg -ao null -nosound file_to_be_encoded.avi &
encoder_example -v 1 -a 1 stream.wav stream.yuv > theora_file.ogg

An alternative workaround is to dump the audio, separately, to a standard .wav file (which can be rather large, but still MUCH smaller than the video dump file would be...):

mplayer -ao pcm -aofile dump.wav -vo null file_to_be_encoded.avi

Finally, to encode the Ogg Theora file from the original:

mplayer -ao null -nosound -vo yuv4mpeg file_to_be_encoded.avi &

(again, I do this in separate terminals, but I don't believe you HAVE to...)

encoder_example -v 1 -a 1 dump.wav stream.yuv > theora_file.ogg

Once the example encoder is set up to handle the order that the audio and video packets come out of mplayer's export, this whole process will be much simpler:

mplayer -ao pcm -aofile stream.wav -vo yuv4mpeg file_to_be_encoded.avi &

The encoder_example line above can remain unchanged, unless you want to modify the quality settings or supply target bitrates instead.

On final encoding note: The encoder takes the size and frame rate of the output video directly from the yuv4mpeg stream, and does not yet handle 'aspect ratio', so if you want to, for example, create an Ogg Theora file from an NTSC SVCD mpeg file (480x480) that displays the "correct" size (640x480), you will need to explicitly scale it. Fortunately, mplayer handles this just fine:

mplayer -ao null -nosound -vo yuv4mpeg -vop scale=640:480 SVCD_File.mpg

Some 'data points':

I've tested 'transcoding' a 13-minute-long, 368x480, 29.970 fps, 3750.0 kbps color mpeg2 video, 112kbps (?) audio file (Total file size ~315MB)from the Prelinger archives as described above, scaling to 640x480, with no problems. Synchronization seems fine throughout, and even at -v 1, the resulting video did not seem noticeably degraded from the original, though in fairness, the original in this case is a faded and grainy 1950's film, so what degradation there was is likely to be less noticeable.
The resulting Theora file was ~68MB.

PLAYBACK:
Playback by the player_example, as also explicitly stated in the README, takes its input from stdin. However, since *I* read that and STILL tried to supply a filename the first time or two that I ran it, I'll reiterate it here to cover up my stupidity:

player_example expects data on stdin, that is, piped. To play back an Ogg Theora file with it, use a command line such as:

cat Ogg_Theora_File.ogg | player_example

or simply:
player_example < Ogg_Theora_File.ogg

The example player has no options or playing controls, but plays back just fine in my experience so far.

TODO (for this document):

Comments? Questions? Suggestions?