theora/README

   1 -------------------------------------------------------------------------
   2           The Xiph.org Foundation's libtheora 1.0beta1 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
  10 encoders are nearly identical, but Theora will make use of new
  11 features supported by the decoder to improve over what is
  12 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/ for instructions.
  20
  21 *** What is the goal of this release?
  22
  23 This is the first beta release of the 1.0 reference implementation.
  24 It is intended to completely support the decoder specification, and
  25 gather feedback on the implementation before declaring it stable.
  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 the player only:
  46
  47       as above,
  48
  49       SDL (Simple Direct media Layer) libraries and headers
  50
  51       OSS audio driver and development headers
  52
  53 The provided build system is the GNU automake/autoconf system, and
  54 the main library, libtheora, should already build smoothly on any
  55 system.  Failure of libtheora to build on a GNU-enabled system is
  56 considered a bug; please report problems to theora-dev@xiph.org.
  57
  58 Some windows build support is included in the win32 directory.
  59
  60 There is also an experimental scons build.
  61
  62 *** How do I use the sample encoder?
  63
  64 The sample encoder takes raw video in YUV4MPEG2 format, as used by
  65 lavtools, mjpeg-tools and other packages. The encoder expects audio,
  66 if any, in a separate wave WAV file. Try 'encoder_example -h' for a
  67 complete list of options.
  68
  69 An easy way to get raw video and audio files is to use MPlayer as an
  70 export utility.  The options " -ao pcm -vo yuv4mpeg " will export a
  71 wav file named audiodump.wav and a YUV video file in the correct
  72 format for encoder_example as stream.yuv.  Be careful when exporting
  73 video alone; MPlayer may drop frames to 'keep up' with the audio
  74 timer.  The example encoder can't properly synchronize input audio and
  75 video file that aren't in sync to begin with.
  76
  77 The encoder will also take video or audio on stdin if '-' is specified
  78 as the input file name.
  79
  80 There is also a 'png2theora' example which accepts a set of image
  81 files in that format.
  82
  83 *** How do I use the sample player?
  84
  85 The sample player takes an Ogg file on standard in; the file may be
  86 audio alone, video alone or video with audio.
  87
  88 *** What other tools are available?
  89
  90 The programs in the examples directory are intended as tutorial source
  91 for developers using the library. As such they sacrifice features and
  92 robustness in the interests of comprehension and should not be
  93 considered serious applications.
  94
  95 If you're wanting to just use theora, consider the programs linked
  96 from http://www.theora.org/. There is playback support in a number
  97 of common free players, and plugins for major media frameworks.
  98 Jan Gerber's ffmpeg2theora is an excellent encoding front end.
  99
 100 -------------------------------------------------------------------------
 101 Troubleshooting the build process
 102 -------------------------------------------------------------------------
 103
 104 *** Compile error, such as:
 105
 106 encoder_internal.h:664: parse error before `ogg_uint16_t'
 107
 108 This means you have version of libogg prior to 1.1. A *complete* new Ogg
 109 install, libs and headers is needed.
 110
 111 Also be sure that there aren't multiple copies of Ogg installed in
 112 /usr and /usr/local; an older one might be first on the search path
 113 for libs and headers.
 114
 115 *** Link error, such as:
 116
 117 undefined reference to `oggpackB_stream'
 118
 119 See above; you need libogg 1.1 or later.
 120
 121 *** Link error, such as:
 122
 123 undefined reference to `vorbis_granule_time'
 124
 125 You need libvorbis and libvorbisenc from the 1.0.1 release or later.
 126
 127 *** Link error, such as:
 128
 129 /usr/lib/libSDL.a(SDL_esdaudio.lo): In function `ESD_OpenAudio':
 130 SDL_esdaudio.lo(.text+0x25d): undefined reference to `esd_play_stream'
 131
 132 Be sure to use an SDL that's built to work with OSS.  If you use an
 133 SDL that is also built with ESD and/or ALSA support, it will try to
 134 suck in all those extra libraries at link time too.  That will only
 135 work if the extra libraries are also installed.
 136
 137 *** Link warning, such as:
 138
 139 libtool: link: warning: library `/usr/lib/libogg.la' was moved.
 140 libtool: link: warning: library `/usr/lib/libogg.la' was moved.
 141
 142 Re-run theora/autogen.sh after an Ogg or Vorbis rebuild/reinstall
 143