michael@0: ------------------------------------------------------------------------- michael@0: The Xiph.org Foundation's libtheora 1.2 michael@0: ------------------------------------------------------------------------- michael@0: michael@0: *** What is Theora? michael@0: michael@0: Theora is Xiph.Org's first publicly released video codec, intended michael@0: for use within the Foundation's Ogg multimedia streaming system. michael@0: Theora is derived directly from On2's VP3 codec, adds new features michael@0: while allow it a longer useful lifetime as an competitive codec. michael@0: michael@0: The 1.0 release decoder supported all the new features, but the michael@0: encoder is nearly identical to the VP3 code. michael@0: michael@0: The 1.1 release featured a completely rewritten encoder, offering michael@0: better performance and compression, and making more complete use michael@0: of the format's feature set. michael@0: michael@0: The 1.2 release features significant additional improvements in michael@0: compression and performance. Files produced by newer encoders can michael@0: be decoded by earlier releases. michael@0: michael@0: *** Where is Theora? michael@0: michael@0: Theora's main site is www.theora.org. Theora and related libraries michael@0: can be gotten from www.theora.org or the main Xiph.Org site at michael@0: www.xiph.org. Development source is kept in an open subversion michael@0: repository, see http://theora.org/svn/ for instructions. michael@0: michael@0: ------------------------------------------------------------------------- michael@0: Getting started with the code michael@0: ------------------------------------------------------------------------- michael@0: michael@0: *** What do I need to build the source? michael@0: michael@0: Requirements summary: michael@0: michael@0: For libtheora: michael@0: michael@0: libogg 1.1 or newer. michael@0: michael@0: For example encoder: michael@0: michael@0: as above, michael@0: michael@0: libvorbis and libvorbisenc 1.0.1 or newer. michael@0: (libvorbis 1.3.1 or newer for 5.1 audio) michael@0: michael@0: For creating a source distribution package: michael@0: michael@0: as above, michael@0: michael@0: Doxygen to build the API documentation, michael@0: pdflatex and fig2dev to build the format specification michael@0: (transfig package in Ubuntu). michael@0: michael@0: For the player only: michael@0: michael@0: as above, michael@0: michael@0: SDL (Simple Direct media Layer) libraries and headers, michael@0: OSS audio driver and development headers. michael@0: michael@0: The provided build system is the GNU automake/autoconf system, and michael@0: the main library, libtheora, should already build smoothly on any michael@0: system. Failure of libtheora to build on a GNU-enabled system is michael@0: considered a bug; please report problems to theora-dev@xiph.org. michael@0: michael@0: Windows build support is included in the win32 directory. michael@0: michael@0: Project files for Apple XCode are included in the macosx directory. michael@0: michael@0: There is also a more limited scons build. michael@0: michael@0: *** How do I use the sample encoder? michael@0: michael@0: The sample encoder takes raw video in YUV4MPEG2 format, as used by michael@0: lavtools, mjpeg-tools and other packages. The encoder expects audio, michael@0: if any, in a separate wave WAV file. Try 'encoder_example -h' for a michael@0: complete list of options. michael@0: michael@0: An easy way to get raw video and audio files is to use MPlayer as an michael@0: export utility. The options " -ao pcm -vo yuv4mpeg " will export a michael@0: wav file named audiodump.wav and a YUV video file in the correct michael@0: format for encoder_example as stream.yuv. Be careful when exporting michael@0: video alone; MPlayer may drop frames to 'keep up' with the audio michael@0: timer. The example encoder can't properly synchronize input audio and michael@0: video file that aren't in sync to begin with. michael@0: michael@0: The encoder will also take video or audio on stdin if '-' is specified michael@0: as the input file name. michael@0: michael@0: There is also a 'png2theora' example which accepts a set of image michael@0: files in that format. michael@0: michael@0: *** How do I use the sample player? michael@0: michael@0: The sample player takes an Ogg file on standard in; the file may be michael@0: audio alone, video alone or video with audio. michael@0: michael@0: *** What other tools are available? michael@0: michael@0: The programs in the examples directory are intended as tutorial source michael@0: for developers using the library. As such they sacrifice features and michael@0: robustness in the interests of comprehension and should not be michael@0: considered serious applications. michael@0: michael@0: If you're wanting to just use theora, consider the programs linked michael@0: from http://www.theora.org/. There is playback support in a number michael@0: of common free players, and plugins for major media frameworks. michael@0: Jan Gerber's ffmpeg2theora is an excellent encoding front end. michael@0: michael@0: ------------------------------------------------------------------------- michael@0: Troubleshooting the build process michael@0: ------------------------------------------------------------------------- michael@0: michael@0: *** Compile error, such as: michael@0: michael@0: encoder_internal.h:664: parse error before `ogg_uint16_t' michael@0: michael@0: This means you have version of libogg prior to 1.1. A *complete* new Ogg michael@0: install, libs and headers is needed. michael@0: michael@0: Also be sure that there aren't multiple copies of Ogg installed in michael@0: /usr and /usr/local; an older one might be first on the search path michael@0: for libs and headers. michael@0: michael@0: *** Link error, such as: michael@0: michael@0: undefined reference to `oggpackB_stream' michael@0: michael@0: See above; you need libogg 1.1 or later. michael@0: michael@0: *** Link error, such as: michael@0: michael@0: undefined reference to `vorbis_granule_time' michael@0: michael@0: You need libvorbis and libvorbisenc from the 1.0.1 release or later. michael@0: michael@0: *** Link error, such as: michael@0: michael@0: /usr/lib/libSDL.a(SDL_esdaudio.lo): In function `ESD_OpenAudio': michael@0: SDL_esdaudio.lo(.text+0x25d): undefined reference to `esd_play_stream' michael@0: michael@0: Be sure to use an SDL that's built to work with OSS. If you use an michael@0: SDL that is also built with ESD and/or ALSA support, it will try to michael@0: suck in all those extra libraries at link time too. That will only michael@0: work if the extra libraries are also installed. michael@0: michael@0: *** Link warning, such as: michael@0: michael@0: libtool: link: warning: library `/usr/lib/libogg.la' was moved. michael@0: libtool: link: warning: library `/usr/lib/libogg.la' was moved. michael@0: michael@0: Re-run theora/autogen.sh after an Ogg or Vorbis rebuild/reinstall michael@0: