1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libtheora/README Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,156 @@
1.4 +-------------------------------------------------------------------------
1.5 + The Xiph.org Foundation's libtheora 1.2
1.6 +-------------------------------------------------------------------------
1.7 +
1.8 +*** What is Theora?
1.9 +
1.10 +Theora is Xiph.Org's first publicly released video codec, intended
1.11 +for use within the Foundation's Ogg multimedia streaming system.
1.12 +Theora is derived directly from On2's VP3 codec, adds new features
1.13 +while allow it a longer useful lifetime as an competitive codec.
1.14 +
1.15 +The 1.0 release decoder supported all the new features, but the
1.16 +encoder is nearly identical to the VP3 code.
1.17 +
1.18 +The 1.1 release featured a completely rewritten encoder, offering
1.19 +better performance and compression, and making more complete use
1.20 +of the format's feature set.
1.21 +
1.22 +The 1.2 release features significant additional improvements in
1.23 +compression and performance. Files produced by newer encoders can
1.24 +be decoded by earlier releases.
1.25 +
1.26 +*** Where is Theora?
1.27 +
1.28 +Theora's main site is www.theora.org. Theora and related libraries
1.29 +can be gotten from www.theora.org or the main Xiph.Org site at
1.30 +www.xiph.org. Development source is kept in an open subversion
1.31 +repository, see http://theora.org/svn/ for instructions.
1.32 +
1.33 +-------------------------------------------------------------------------
1.34 +Getting started with the code
1.35 +-------------------------------------------------------------------------
1.36 +
1.37 +*** What do I need to build the source?
1.38 +
1.39 +Requirements summary:
1.40 +
1.41 + For libtheora:
1.42 +
1.43 + libogg 1.1 or newer.
1.44 +
1.45 + For example encoder:
1.46 +
1.47 + as above,
1.48 +
1.49 + libvorbis and libvorbisenc 1.0.1 or newer.
1.50 + (libvorbis 1.3.1 or newer for 5.1 audio)
1.51 +
1.52 + For creating a source distribution package:
1.53 +
1.54 + as above,
1.55 +
1.56 + Doxygen to build the API documentation,
1.57 + pdflatex and fig2dev to build the format specification
1.58 + (transfig package in Ubuntu).
1.59 +
1.60 + For the player only:
1.61 +
1.62 + as above,
1.63 +
1.64 + SDL (Simple Direct media Layer) libraries and headers,
1.65 + OSS audio driver and development headers.
1.66 +
1.67 +The provided build system is the GNU automake/autoconf system, and
1.68 +the main library, libtheora, should already build smoothly on any
1.69 +system. Failure of libtheora to build on a GNU-enabled system is
1.70 +considered a bug; please report problems to theora-dev@xiph.org.
1.71 +
1.72 +Windows build support is included in the win32 directory.
1.73 +
1.74 +Project files for Apple XCode are included in the macosx directory.
1.75 +
1.76 +There is also a more limited scons build.
1.77 +
1.78 +*** How do I use the sample encoder?
1.79 +
1.80 +The sample encoder takes raw video in YUV4MPEG2 format, as used by
1.81 +lavtools, mjpeg-tools and other packages. The encoder expects audio,
1.82 +if any, in a separate wave WAV file. Try 'encoder_example -h' for a
1.83 +complete list of options.
1.84 +
1.85 +An easy way to get raw video and audio files is to use MPlayer as an
1.86 +export utility. The options " -ao pcm -vo yuv4mpeg " will export a
1.87 +wav file named audiodump.wav and a YUV video file in the correct
1.88 +format for encoder_example as stream.yuv. Be careful when exporting
1.89 +video alone; MPlayer may drop frames to 'keep up' with the audio
1.90 +timer. The example encoder can't properly synchronize input audio and
1.91 +video file that aren't in sync to begin with.
1.92 +
1.93 +The encoder will also take video or audio on stdin if '-' is specified
1.94 +as the input file name.
1.95 +
1.96 +There is also a 'png2theora' example which accepts a set of image
1.97 +files in that format.
1.98 +
1.99 +*** How do I use the sample player?
1.100 +
1.101 +The sample player takes an Ogg file on standard in; the file may be
1.102 +audio alone, video alone or video with audio.
1.103 +
1.104 +*** What other tools are available?
1.105 +
1.106 +The programs in the examples directory are intended as tutorial source
1.107 +for developers using the library. As such they sacrifice features and
1.108 +robustness in the interests of comprehension and should not be
1.109 +considered serious applications.
1.110 +
1.111 +If you're wanting to just use theora, consider the programs linked
1.112 +from http://www.theora.org/. There is playback support in a number
1.113 +of common free players, and plugins for major media frameworks.
1.114 +Jan Gerber's ffmpeg2theora is an excellent encoding front end.
1.115 +
1.116 +-------------------------------------------------------------------------
1.117 +Troubleshooting the build process
1.118 +-------------------------------------------------------------------------
1.119 +
1.120 +*** Compile error, such as:
1.121 +
1.122 +encoder_internal.h:664: parse error before `ogg_uint16_t'
1.123 +
1.124 +This means you have version of libogg prior to 1.1. A *complete* new Ogg
1.125 +install, libs and headers is needed.
1.126 +
1.127 +Also be sure that there aren't multiple copies of Ogg installed in
1.128 +/usr and /usr/local; an older one might be first on the search path
1.129 +for libs and headers.
1.130 +
1.131 +*** Link error, such as:
1.132 +
1.133 +undefined reference to `oggpackB_stream'
1.134 +
1.135 +See above; you need libogg 1.1 or later.
1.136 +
1.137 +*** Link error, such as:
1.138 +
1.139 +undefined reference to `vorbis_granule_time'
1.140 +
1.141 +You need libvorbis and libvorbisenc from the 1.0.1 release or later.
1.142 +
1.143 +*** Link error, such as:
1.144 +
1.145 +/usr/lib/libSDL.a(SDL_esdaudio.lo): In function `ESD_OpenAudio':
1.146 +SDL_esdaudio.lo(.text+0x25d): undefined reference to `esd_play_stream'
1.147 +
1.148 +Be sure to use an SDL that's built to work with OSS. If you use an
1.149 +SDL that is also built with ESD and/or ALSA support, it will try to
1.150 +suck in all those extra libraries at link time too. That will only
1.151 +work if the extra libraries are also installed.
1.152 +
1.153 +*** Link warning, such as:
1.154 +
1.155 +libtool: link: warning: library `/usr/lib/libogg.la' was moved.
1.156 +libtool: link: warning: library `/usr/lib/libogg.la' was moved.
1.157 +
1.158 +Re-run theora/autogen.sh after an Ogg or Vorbis rebuild/reinstall
1.159 +
