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