README

   1 -------------------------------------------------------------------------
   2              The Xiph.org Foundation's libtheora 1.1
   3 -------------------------------------------------------------------------
   4
   5 *** What is Theora?
   6
   7 Theora is Xiph.Org's first publicly released video codec, intended
   8 for use within the Foundation's Ogg multimedia streaming system.
   9 Theora is derived directly from On2's VP3 codec, adds new features
  10 while allow it a longer useful lifetime as an competitive codec.
  11
  12 The 1.0 release decoder supported all the new features, but the
  13 encoder is nearly identical to the VP3 code.
  14
  15 The 1.1 release features a completely rewritten encoder, offering
  16 better performance and compression, and making more complete use
  17 of the format's feature set. Files produced by both encoders can
  18 be decoded by either release.
  19
  20 *** Where is Theora?
  21
  22 Theora's main site is www.theora.org.  Theora and related libraries
  23 can be gotten from www.theora.org or the main Xiph.Org site at
  24 www.xiph.org.  Development source is kept in an open subversion
  25 repository, see http://theora.org/svn/ for instructions.
  26
  27 -------------------------------------------------------------------------
  28 Getting started with the code
  29 -------------------------------------------------------------------------
  30
  31 *** What do I need to build the source?
  32
  33 Requirements summary:
  34
  35   For libtheora:
  36
  37       libogg 1.1 or newer.
  38
  39   For example encoder:
  40
  41       as above,
  42
  43       libvorbis and libvorbisenc 1.0.1 or newer.
  44
  45   For creating a source distribution package:
  46
  47       as above,
  48
  49       Doxygen to build the API documentation,
  50       pdflatex and fig2dev to build the format specification
  51         (transfig package in Ubuntu).
  52
  53   For the player only:
  54
  55       as above,
  56
  57       SDL (Simple Direct media Layer) libraries and headers,
  58       OSS audio driver and development headers.
  59
  60 The provided build system is the GNU automake/autoconf system, and
  61 the main library, libtheora, should already build smoothly on any
  62 system.  Failure of libtheora to build on a GNU-enabled system is
  63 considered a bug; please report problems to theora-dev@xiph.org.
  64
  65 Windows build support is included in the win32 directory.
  66
  67 Project files for Apple XCode are included in the macosx directory.
  68
  69 There is also an experimental scons build.
  70
  71 *** How do I use the sample encoder?
  72
  73 The sample encoder takes raw video in YUV4MPEG2 format, as used by
  74 lavtools, mjpeg-tools and other packages. The encoder expects audio,
  75 if any, in a separate wave WAV file. Try 'encoder_example -h' for a
  76 complete list of options.
  77
  78 An easy way to get raw video and audio files is to use MPlayer as an
  79 export utility.  The options " -ao pcm -vo yuv4mpeg " will export a
  80 wav file named audiodump.wav and a YUV video file in the correct
  81 format for encoder_example as stream.yuv.  Be careful when exporting
  82 video alone; MPlayer may drop frames to 'keep up' with the audio
  83 timer.  The example encoder can't properly synchronize input audio and
  84 video file that aren't in sync to begin with.
  85
  86 The encoder will also take video or audio on stdin if '-' is specified
  87 as the input file name.
  88
  89 There is also a 'png2theora' example which accepts a set of image
  90 files in that format.
  91
  92 *** How do I use the sample player?
  93
  94 The sample player takes an Ogg file on standard in; the file may be
  95 audio alone, video alone or video with audio.
  96
  97 *** What other tools are available?
  98
  99 The programs in the examples directory are intended as tutorial source
 100 for developers using the library. As such they sacrifice features and
 101 robustness in the interests of comprehension and should not be
 102 considered serious applications.
 103
 104 If you're wanting to just use theora, consider the programs linked
 105 from http://www.theora.org/. There is playback support in a number
 106 of common free players, and plugins for major media frameworks.
 107 Jan Gerber's ffmpeg2theora is an excellent encoding front end.
 108
 109 -------------------------------------------------------------------------
 110 Troubleshooting the build process
 111 -------------------------------------------------------------------------
 112
 113 *** Compile error, such as:
 114
 115 encoder_internal.h:664: parse error before `ogg_uint16_t'
 116
 117 This means you have version of libogg prior to 1.1. A *complete* new Ogg
 118 install, libs and headers is needed.
 119
 120 Also be sure that there aren't multiple copies of Ogg installed in
 121 /usr and /usr/local; an older one might be first on the search path
 122 for libs and headers.
 123
 124 *** Link error, such as:
 125
 126 undefined reference to `oggpackB_stream'
 127
 128 See above; you need libogg 1.1 or later.
 129
 130 *** Link error, such as:
 131
 132 undefined reference to `vorbis_granule_time'
 133
 134 You need libvorbis and libvorbisenc from the 1.0.1 release or later.
 135
 136 *** Link error, such as:
 137
 138 /usr/lib/libSDL.a(SDL_esdaudio.lo): In function `ESD_OpenAudio':
 139 SDL_esdaudio.lo(.text+0x25d): undefined reference to `esd_play_stream'
 140
 141 Be sure to use an SDL that's built to work with OSS.  If you use an
 142 SDL that is also built with ESD and/or ALSA support, it will try to
 143 suck in all those extra libraries at link time too.  That will only
 144 work if the extra libraries are also installed.
 145
 146 *** Link warning, such as:
 147
 148 libtool: link: warning: library `/usr/lib/libogg.la' was moved.
 149 libtool: link: warning: library `/usr/lib/libogg.la' was moved.
 150
 151 Re-run theora/autogen.sh after an Ogg or Vorbis rebuild/reinstall
 152