[theora-dev] Using Theora Micro-HOWTO

[emaillist at dogphilosophy.net]

Okay, thanks to some stubbornness on my part and helpfulness on the part
of people on this mailing list, I got the Ogg Theora alpha compiled up
and installed and running.

Yesterday, 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.

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 (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

the example encoder, as of this writing, does not yet also handle the audio
from a fifo, though this may be possible in the (near?) future.  In the
meantime, the simplest 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 stream.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 &

(and then - I do this in a separate terminal window, but as far as I know
it can be done in the same window, albeit messily as both programs output
status messages)

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

(if/when encoder_example supports 'piped' pcm data, you will be able to:

mkfifo -m 660 stream.wav 

and there will be only one mplayer command line to call before the
encoder_example:

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.

<p>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' (either that, or the player_example doesn't), 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':
-a 1, for 44.1khz stereo .wav file, equates to ~64-72kbps
-v 1, for 640x480 29.970fps video, equates to ~600kbps

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.
7
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:

Test encoding with some 'sharper' originals.

Compare encoding speed and quality with mpeg2 and xvid.

<p><p><p><p>Comments?  Questions?  Suggestions?
--- >8 ----
List archives:  http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'theora-dev-request at xiph.org'
containing only the word 'unsubscribe' in the body.  No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.