theora-old/README

   1 -------------------------------------------------------------------------
   2           The Xiph.org Foundation's libtheora 1.0alpha7 release
   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; Currently the two are
  10 nearly identical, varying only in encapsulating decoder tables in the
  11 bitstream headers, but Theora will make use of this extra freedom
  12 in the future to improve over what is possible with VP3.
  13
  14 *** Where is Theora?
  15
  16 Theora's main site is www.theora.org.  Theora and related libraries
  17 can be gotten from www.theora.org or the main Xiph.Org site at
  18 www.xiph.org.  Development source is kept in an open subversion
  19 repository, see http://theora.org/svn.html for instructions.
  20
  21 *** What is the goal of this alpha release?
  22
  23 The Theora bitstream format was frozen after the alpha3 release. This
  24 means that files produced by the alpha3 encoder will always be playable
  25 according to the Theora I specification.
  26
  27 Traditionally alpha mean proof of concept, not a production-ready
  28 release. However the code is very robust, ready for and indeed
  29 in general use.
  30
  31 The purpose of this release is to provide an updated testing base for
  32 those interested in theora and to dissiminate more widely the changes
  33 we've made since the last alpha release. These include some helper
  34 utility functions, a draft format specification and api documentation
  35 located in the doc directory.
  36
  37 -------------------------------------------------------------------------
  38 Getting started with the code
  39 -------------------------------------------------------------------------
  40
  41 *** What do I need to build the source?
  42
  43 Requirements summary:
  44
  45   For libtheora:
  46
  47       libogg 1.1 or newer.
  48       (there is optional support for libogg2, unreleased at this time)
  49
  50   For example encoder:
  51
  52       as above
  53
  54       libvorbis and libvorbisenc 1.0.1 or newer.
  55
  56   For the player only:
  57
  58       as above,
  59
  60       SDL (Simple Direct media Layer) libraries and headers
  61
  62       OSS audio driver and development headers
  63
  64 The provided build system is the GNU automake/autoconf system, and
  65 the main library, libtheora, should already build smoothly on any
  66 system.  Failure of libtheora to build on a GNU-enabled system is
  67 considered a bug; please report problems to theora-dev@xiph.org.
  68
  69 Some windows build support is included in the win32 directory.
  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.  Snatch and MPlayer version
  75 0.90 and later can also export in YUV4MPEG format (more on this
  76 later).  The encoder take audio as WAV files.  encoder_example -h
  77 lists options accepted by the encoder.
  78
  79 An easy way to get raw video and audio files is to use MPlayer as an
  80 export utility.  The options " -ao pcm -vo yuv4mpeg " will export a
  81 wav file named audiodump.wav and a YUV video file in the correct
  82 format for encoder_example as stream.yuv.  Be careful when exporting
  83 video alone; MPlayer may drop frames to 'keep up' with the audio
  84 timer.  The example encoder can't properly synchronize input audio and
  85 video file that aren't in sync to begin with.
  86
  87 The encoder will also take video or audio on stdin if '-' is specified
  88 as the input file name.
  89
  90 *** How do I use the sample player?
  91
  92 The sample player takes an Ogg file on standard in; the file may be
  93 audio alone, video alone or video with audio.
  94
  95 *** What other tools are available?
  96
  97 If you're wanting to just use theora, consider the programs linked
  98 from http://www.theora.org/. There is playback support in a number
  99 of common free players, and Jan Gerber's ffmpeg2theora is an excellent
 100 encoding front end.
 101
 102 -------------------------------------------------------------------------
 103 Troubleshooting the build process
 104 -------------------------------------------------------------------------
 105
 106 *** Compile error, such as:
 107
 108 encoder_internal.h:664: parse error before `ogg_uint16_t'
 109
 110 This means you have version of libogg prior to 1.1. A *complete* new Ogg
 111 install, libs and headers, from a new release or CVS is needed.  Don't
 112 forget to re-reun autogen.sh so that autoconf sucks in the new type
 113 declarations.
 114
 115 Also be sure that there aren't multiple copies of Ogg installed in
 116 /usr and /usr/local; an older one might be first on the search path
 117 for libs and headers.
 118
 119 *** Link error, such as:
 120
 121 undefined reference to `oggpackB_stream'
 122
 123 See above; you need libogg 1.1 or later.
 124
 125 *** Link error, such as:
 126
 127 undefined reference to `vorbis_granule_time'
 128
 129 You need libvorbis and libvorbisenc from the 1.0.1 release or later.
 130
 131 *** Link error, such as:
 132
 133 /usr/lib/libSDL.a(SDL_esdaudio.lo): In function `ESD_OpenAudio':
 134 SDL_esdaudio.lo(.text+0x25d): undefined reference to `esd_play_stream'
 135
 136 Be sure to use an SDL that's built to work with OSS.  If you use an
 137 SDL that is also built with ESD and/or ALSA support, it will try to
 138 suck in all those extra libraries at link time too.  That will only
 139 work if the extra libraries are also installed.
 140
 141 *** Link warning, such as:
 142
 143 libtool: link: warning: library `/usr/lib/libogg.la' was moved.
 144 libtool: link: warning: library `/usr/lib/libogg.la' was moved.
 145
 146 Re-run theora/autogen.sh after an Ogg or Vorbis rebuild/reinstall
 147