media/libtheora/README.md

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