11213111f740ac2e07c7f0867779db4ad631546d
[cortado.git] / README
1 WHAT IT IS
2 ----------
3
4 This is Cortado, a multimedia framework for Java written by Fluendo.
5
6 It contains:
7 - JST, a port of the GStreamer 0.10 design to Java
8 - jcraft, a copy of the JCraft JOgg/Jorbis code
9 - jheora, an implementation of Theora in Java
10 - jkate, an implementation of a basic Kate decoder in Java
11 - jtiger, a basic Kate renderer (simple text/images only for now)
12 - codecs (currently only containing the Smoke codec, a variant on Jpeg)
13 - JST plugins for:
14   - HTTP source element
15   - Ogg and Multipart demuxers
16   - Theora, JPEG and Smoke video decoders
17   - Vorbis and MuLaw audio decoders
18    - Java 1.1 sun.audio API audio sink
19    - Java 1.4 javax.sound.sampled API audio sink
20   - Overlay element
21   - Kate text decoder and overlay
22   - Selector element
23 - examples
24 - applets
25
26 This release has support for
27 - seeking in on-demand files
28 - the above-mentioned plugins
29 - basic HTTP authentication
30 - buffering
31
32 FAQ
33 ---
34
35 For frequently asked questions check our website at http://theora.org/cortado/
36
37 If any questions should be added, let us know.
38
39 BUGS
40 ----
41
42 You can file bugs at Xiph's issue tracker:
43 https://trac.xiph.org/newticket?component=Cortado
44
45 Make sure to choose the "Cortado" component.
46
47 BUILDING
48 --------
49
50 The build uses ant exclusively now.
51
52 Normally, running
53
54   ant
55
56 Should build everything, if your system is setup correctly.
57
58 You can copy build.config.sample to build.config and tweak it to choose
59 certain settings.
60
61 Run
62
63   ant -p
64
65 to see all the possible targets.
66
67 EXAMPLES
68 --------
69
70 You need a Java Virtual Machine to run the example code.
71 You also need to set the classpath to your build tree when running
72 (output/build/debug or output/build/stripped)
73
74 - Jikes does not have a VM
75 - gij (the GNU Java VM) does not have a javax.sound.sampled implementation, so
76   fails when playing audio, but can still play video-only files
77 - Sun Java VM works for me:
78
79   /usr/java/jre1.5.0_04/bin/java -cp output/build/debug com.fluendo.examples.Player http://stream.fluendo.com:8850
80
81   (with a JPackage java-1.5.0-sun package)
82   /usr/lib/jvm/java-1.5.0-sun-1.5.0.05/jre/bin/java -cp output/build/debug com.fluendo.examples.Player http://stream.fluendo.com:8850
83
84
85 USAGE
86 -----
87
88 Embed the applet in a web page with code like this:
89
90 ----
91 <html>
92  <head>
93  </head>
94  <body>
95    <applet code="com.fluendo.player.Cortado.class" 
96            archive="cortado.jar" 
97            width="352" height="288">
98      <param name="url" value="http://localhost/test6.ogg"/>
99      <param name="local" value="false"/>
100      <param name="duration" value="232"/>
101      <param name="keepAspect" value="true"/>
102      <param name="video" value="true"/>
103      <param name="audio" value="true"/>
104      <param name="bufferSize" value="200"/>
105      <param name="userId" value="user"/>
106      <param name="password" value="test"/>
107    </applet>
108  </body>
109 </html>
110 ----
111
112 parameters:
113 -----------
114
115   url:        string
116               the URL to load, must be a fully qualified URL.
117               IMPORTANT: if the applet is not signed, the hostname of the
118               url *is required* to be the same as the hostname of the link
119               to the page with the applet tag.  This is a Java security limitation.
120
121   seekable:   enum (auto|true|false)
122               Whether or not you can seek in the file.  For live streams,
123               this should be false; for on-demand files, this can be true.
124               In automatic mode, the stream becomes seekable when the content
125               length is discovered.
126               Defaults to auto
127
128   live        enum (auto|true|false)
129               Whether or not this file is a live stream.  For live streams,
130               this should be true, which will disable the PAUSE button.
131               For on-demand files, this can be false.
132               In automatic mode, the stream becomes non-live when the content
133               length is discovered.
134               Defaults to auto
135
136   duration:   int
137               Length of clip in seconds.  Needed when seekable is false,
138               to allow the seek bar to work.
139
140   startTime:  int
141               Start time of clip in seconds.  Needed when seekable is false,
142               to allow the seek bar to work.
143
144   keepAspect: boolean
145               Try to keep the natural aspect of the video when resizing the
146               applet window. true or false.
147               Defaults to true
148
149   ignoreAspect: boolean
150               Ignore the aspect ratio as signalled by the video, always assume
151               square pixels. true or false.
152               Defaults to false
153
154   ignoreBasetime: boolean
155               Ignore the ogg file's basetime (initial granule or granpos) when
156               displaying times in the seek bar.  Instead, for display purposes,
157               always treat the first sample as occurring at time zero.
158               true or false.
159               Defaults to false
160
161   video:      boolean
162               Use video. When not using video, this property will not create
163               resources to play a video stream. true or false.
164               Defaults to true
165               
166   audio:      boolean
167               Use audio. When not using audio, this property will not create
168               resources to play an audio stream. true or false.
169               Defaults to true
170
171   kateIndex:  int
172               Use text from the given Kate stream (indexed from zero).
173               The first Kate stream found will have index 0, the second will
174               have index 1, etc.
175               Selecting a Kate stream by index takes priority over selecting
176               by language and/or category.
177               At most one Kate stream may be enabled at a time.
178               Defaults to -1 (none)
179
180   kateLanguage: string
181               Use text from the Kate stream with the given language (ISO 639-1 tag).
182               Selecting a Kate stream by index takes priority over selecting
183               by language and/or category.
184               At most one Kate stream may be enabled at a time.
185               Defaults to null (none)
186
187   kateCategory: string
188               Use text from the Kate stream with the given category.
189               Selecting a Kate stream by index takes priority over selecting
190               by language and/or category.
191               At most one Kate stream may be enabled at a time.
192               Defaults to null (none)
193
194   statusHeight: int
195               The height of the status area (default 12)
196
197   autoPlay:   boolean
198               Automatically start playback (default true)
199
200   showStatus: enum (auto|show|hide)
201               Controls how to make the status area visible. 
202               auto will show the status area when hovered over with the mouse.
203               hide will only show the status area on error.
204               show will always show the status area.
205               (default auto)
206
207   showSpeaker: boolean
208               Show a speaker icon when audio is available (default true)
209
210   showSubtitles: boolean
211               Show a subtitles icon when subtitles are available (default true)
212
213   hideTimeout: int 
214               Timeout in seconds to hide the status area when showStatus is
215               auto. This timeout is to make sure that the status area is visible
216               for the first timeout seconds of playback so that the user can see
217               that there is a clickable status area too.
218               (default 0)
219
220   bufferSize: int
221               The size of the network buffer, in KB.
222               A good value is max Kbps of the stream * 33
223               Defaults to 200
224
225   bufferLow:  int
226               Percentage of low watermark for buffer.  Below this, the applet
227               will stop playing and rebuffer until the high watermark is
228               reached.
229               Defaults to 10
230
231   bufferHigh: int
232               Percentage of high watermark for buffer.  At startup or when
233               rebuffering, the applet will not play until this percentage of
234               buffer fill status is reached.
235               Defaults to 70
236
237   userId:     string
238               user id for basic authentication.
239
240   password:   string
241               password for basic authentication.
242
243   debug:      int
244               debug level, 0 - 4.  Defaults to 3.  Output goes to the Java
245               console.
246
247 Using javascript
248 ----------------
249
250 The applet parameters can be changed from javascript by calling the
251 setParam(key, value) on the applet. After setting the new parameters in the
252 applet it needs to be restarted with the restart() method for the changes to
253 take effect.
254 Likewise, applet parameters may be queried using getParam(key, default).
255
256 The following piece of HTML demonstrates switching URLs with an without sound
257 using javascript:
258
259 ----
260 <html>
261  <head>
262  </head>
263  <body>
264    <script language="javascript">
265      function restart() {
266        document.applets[0].restart(); 
267      }
268      function loadUrl(uri, audio) {
269        document.applets[0].setParam("audio", audio); 
270        document.applets[0].setParam("url", uri); 
271        restart();
272      }
273    </script>
274    <applet archive="cortado.jar" code="com.fluendo.player.Cortado.class" width="320" height="240"> 
275      <param name="url" value="http://localhost:8800"/>
276      <param name="local" value="false"/>
277      <param name="framerate" value="5.0"/>
278      <param name="keepaspect" value="true"/>
279      <param name="video" value="true"/>
280      <param name="audio" value="true"/>
281    </applet>
282
283    <br/>
284    <br/>
285
286    <button onClick="restart()">
287     Restart
288    </button>
289    <button onClick="loadUrl('http://localhost:8800', 'true')">
290     With Audio
291    </button>
292    <button onClick="loadUrl('http://localhost:8802', 'false')">
293     Without Audio
294    </button>
295    
296  </body>
297 </html>
298 ----
299
300 The applet can be controlled with the following javascript methods:
301
302   doPlay(): Start playback
303   doPause(): Pause playback
304   doStop(): Stop playback
305   doSeek(double pos); seek to a new position, must be between 0.0 and 1.0.
306   getPlayPosition(): returns current position in seconds
307