------------------------------------------------------------------------- The Xiph.org Foundation's libtheora 1.0alpha4 release ------------------------------------------------------------------------- *** What is Theora? Theora is Xiph.Org's first publicly released video codec, intended for use within the Foundation's Ogg multimedia streaming system. Theora is derived directly from On2's VP3 codec; Currently the two are nearly identical, varying only in encapsulating decoder tables in the bitstream headers, but Theora will make use of this extra freedom in the future to improve over what is possible with VP3. *** 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. Development source is kept in an open subversion repository, see http://theora.org/svn.html for instructions. *** What is the goal of this alpha release? The Theora bitstream format was frozen after the alpha3 release. This means that files produced by the alpha3 encoder will always be playable according to the Theora I specification. Traditionally alpha mean proof of concept, not a production-ready release. However the code is very robust, ready for and indeed in general use. But WE DO INTEND TO MAKE INCOMPATIBLE API changes before stable beta release however, particularly on the encoding side. The purpose of this release is to provide an updated testing base for those interested in theora and to dissiminate more widely the changes we've made since the last alpha release. These include some helper utility functions, a draft format specification and rough api documentation located in the doc directory. ------------------------------------------------------------------------- Getting started with the code ------------------------------------------------------------------------- *** What do I need to build the source? Requirements summary: For libtheora: libogg 1.1 or newer. (there is optional support for libogg2, unreleased at this time) For example encoder: as above libvorbis and libvorbisenc 1.0.1 or newer. For the player only: as above, SDL (Simple Direct media Layer) libraries and headers OSS audio driver and development headers 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@xiph.org. Some windows build support is included in the win32 directory. *** 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 file 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. *** What other tools are available? If you're wanting to just use theora, consider the programs linked from http://www.theora.org/. There is playback support in a number of common free players, and Jan Gerber's ffmpeg2theora is an excellent encoding front end. ------------------------------------------------------------------------- Troubleshooting the build process ------------------------------------------------------------------------- *** Compile error, such as: encoder_internal.h:664: parse error before `ogg_uint16_t' This means you have version of libogg prior to 1.1. A *complete* new Ogg install, libs and headers, from a new release or CVS 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 1.1 or later. *** Link error, such as: undefined reference to `vorbis_granule_time' You need libvorbis and libvorbisenc from the 1.0.1 release or later. *** 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