[xiph-cvs] cvs commit: theora README
Monty
xiphmont at xiph.org
Wed Sep 25 06:03:18 PDT 2002
xiphmont 02/09/25 09:03:18
Added: . README
Log:
Add the readme
Revision Changes Path
1.1 theora/README
Index: README
===================================================================
-------------------------------------------------------------------------
This README file is up to date with and covers Xiph.Org's first alpha
release of the Theora video codec on 25 09 2002.
-------------------------------------------------------------------------
*** What is Theora?
Theora is Xiph.Org's first publicly released video codec, intended
for use within the Ogg's project's Ogg multimedia streaming system.
Theora is derived directly from On2's VP3 codec; Currently the two are
nearly identical, varying only in framing headers, but Theora will
diverge and improve from the main VP3 development lineage as time
progresses.
*** Where is Theora?
Theora's main site is www.theora.org. Theora and related libraries
can be gotten from www.theora.org or the main Xiph.Org site at
www.xiph.org. In order to access CVS at xiph.org (the best way to get
to the source), see http://www.xiph.org/cvs.html
*** What is the goal of this alpha release?
This alpha is a proof of concept, not a production-ready release. Do
not expect the Theora packet or stream format from this release to
remain compatible with future releases. When the format for Theora is
officially frozen, we'll let you know.
This release serves several purposes:
1) An initial, thorough code review of the current VP3
implementation as we begin the transition to Theora. We sum the
results of the VP3 review below:
. Fixed [on the order of] fifty bugs capable of crashing
the codec during encode, playback or both.
. More thorough review of the codebase is warranted; however
most immediately indicated work has been covered in initial
review.
. Xiph.Org has substantially bootstrapped the imported
codebase and is ready to support Theora.
. Performance of unoptimized, pure-C version of VP3/Theora is
very good.
2) Proof of concept: The example programs included in
Theora/examples implement a mixed-stream (Theora/Vorbis) Ogg
encoder and player. These applications, though simple, show Ogg
functioning as intended as a full multimedia container,
illustrate the beginning of VP3/Theora integration into Ogg and
showcase the current level of performance of the portable,
unoptimized C implementation of Theora in terms of speed,
quality and bitrate.
3) Initial implementation testing; this release serves as both a
testbed and a public request for input.
Once more for the record: THIS RELEASE IS NOT PRODUCTION CODE. It is
not for ripping DVDs, writing a Xine/MPlayer plugin or anything beyond
tinkering. The Theora stream format WILL CHANGE in future
releases. The API WILL CHANGE. We will not yet support any Theora
files produced by this alpha. Not yet. Soon, Grasshopper, Soon.
-------------------------------------------------------------------------
Getting started with the code
-------------------------------------------------------------------------
*** What do I need to build the source?
Requirements summary:
For libtheora:
libogg dated 24092002 or newer, built and installed from
Xiph.Org CVS
GNU automake/autoconf/libtool build utilities
For example encoder:
as above
libvorbis and libvorbisenc dated 24092002 or
newer, built and installed from Xiph.Org CVS
For the player only:
as above,
SDL (Simple Direct media Layer) libraries and headers
OSS audio driver and development headers
This release is brand new and full portability is still in progress.
The provided build system is the GNU automake/autoconf system, and
the main library, libtheora, should already build smoothly on any
system. Failure of libtheora to build on a GNU-enabled system is
considered a bug; please report problems to theora-dev at xiph.org.
*** How do I use the sample encoder?
The sample encoder takes raw video in YUV4MPEG2 format, as used by
lavtools, mjpeg-tools and other packages. Snatch and MPlayer version
0.90 and later can also export in YUV4MPEG format (more on this
later). The encoder take audio as WAV files. encoder_example -h
lists options accepted by the encoder.
An easy way to get raw video and audio files is to use MPlayer as an
export utility. The options " -ao pcm -vo yuv4mpeg " will export a
wav vile named audiodump.wav and a YUV video file in the correct
format for encoder_example as stream.yuv. Be careful when exporting
video alone; MPlayer may drop frames to 'keep up' with the audio
timer. The example encoder can't properly synchronize input audio and
video file that aren't in sync to begin with.
The encoder will also take video or audio on stdin if '-' is specified
as the input file name.
*** How do I use the sample player?
The sample player takes an Ogg file on standard in; the file may be
audio alone, video alone or video with audio.
-------------------------------------------------------------------------
Troubleshooting the build process
-------------------------------------------------------------------------
*** Compile error, such as:
encoder_internal.h:664: parse error before `ogg_uint16_t'
A *complete* new Ogg install, libs and headers, from CVS really is
needed. Don't forget to re-reun autogen.sh so that autoconf sucks in
the new type declarations.
Also be sure that there aren't multiple copies of Ogg installed in
/usr and /usr/local; an older one might be first on the search path
for libs and headers.
*** Link error, such as:
undefined reference to `oggpackB_stream'
See above; you need libogg from CVS.
*** Link error, such as:
undefined reference to `vorbis_granule_time'
You need libvorbis and libvorbisenc from CVS.
*** Link error, such as:
/usr/lib/libSDL.a(SDL_esdaudio.lo): In function `ESD_OpenAudio':
SDL_esdaudio.lo(.text+0x25d): undefined reference to `esd_play_stream'
Be sure to use an SDL that's built to work with OSS. If you use an
SDL that is also built with ESD and/or ALSA support, it will try to
suck in all those extra libraries at link time too. That will only
work if the extra libraries are also installed.
*** Link warning, such as:
libtool: link: warning: library `/usr/lib/libogg.la' was moved.
libtool: link: warning: library `/usr/lib/libogg.la' was moved.
Re-run theora/autogen.sh after an Ogg or Vorbis rebuild/reinstall
<p><p><p>--- >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 'cvs-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.
More information about the commits
mailing list