* include/vlc_threads.h,include/main.h,src/misc/threads.c,src/misc/win32_specific.c:
[vlc.git] / src / libvlc.h
1 /*****************************************************************************
2  * libvlc.h: main libvlc header
3  *****************************************************************************
4  * Copyright (C) 1998-2002 VideoLAN
5  * $Id: libvlc.h,v 1.8 2002/07/29 19:05:47 gbazin Exp $
6  *
7  * Authors: Vincent Seguin <seguin@via.ecp.fr>
8  *          Samuel Hocevar <sam@zoy.org>
9  *          Gildas Bazin <gbazin@netcourrier.com>
10  *
11  * This program is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation; either version 2 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software
23  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
24  *****************************************************************************/
25
26 #define Nothing here, this is just to prevent update-po from being stupid
27
28 /*****************************************************************************
29  * Configuration options for the main program. Each module will also separatly
30  * define its own configuration options.
31  * Look into configuration.h if you need to know more about the following
32  * macros.
33  *****************************************************************************/
34 #define INTF_TEXT N_("interface module")
35 #define INTF_LONGTEXT N_( \
36     "This option allows you to select the interface used by vlc. " \
37     "The default behavior is to automatically select the best module " \
38     "available.")
39
40 #define VERBOSE_TEXT N_("be verbose")
41 #define VERBOSE_LONGTEXT N_( \
42     "This options activates the output of information messages.")
43
44 #define QUIET_TEXT N_("be quiet")
45 #define QUIET_LONGTEXT N_( \
46     "This options turns off all warning and information messages.")
47
48 #define COLOR_TEXT N_("color messages")
49 #define COLOR_LONGTEXT N_( \
50     "When this option is turned on, the messages sent to the console will " \
51     "be colorized. Your terminal needs Linux color support for this to work.")
52
53 #define INTF_PATH_TEXT N_("interface default search path")
54 #define INTF_PATH_LONGTEXT N_( \
55     "This option allows you to set the default path that the interface will " \
56     "open when looking for a file.")
57
58 #define PLUGIN_PATH_TEXT N_("plugin search path")
59 #define PLUGIN_PATH_LONGTEXT N_( \
60     "This option allows you to specify an additional path for vlc to look" \
61     "for its plugins.")
62
63 #define AOUT_TEXT N_("audio output module")
64 #define AOUT_LONGTEXT N_( \
65     "This option allows you to select the audio output method used by vlc. " \
66     "The default behavior is to automatically select the best method " \
67     "available.")
68
69 #define AUDIO_TEXT N_("enable audio")
70 #define AUDIO_LONGTEXT N_( \
71     "You can completely disable the audio output. In this case the audio " \
72     "decoding stage won't be done, and it will save some processing power.")
73
74 #define MONO_TEXT N_("force mono audio")
75 #define MONO_LONGTEXT N_("This will force a mono audio output")
76
77 #define VOLUME_TEXT N_("audio output volume")
78 #define VOLUME_LONGTEXT N_( \
79     "You can set the default audio output volume here, in a range from 0 to " \
80     "1024.")
81
82 #define FORMAT_TEXT N_("audio output format")
83 #define FORMAT_LONGTEXT N_( \
84     "You can force the audio output format here.\n" \
85     "0 -> 16 bits signed native endian (default)\n" \
86     "1 ->  8 bits unsigned\n"                       \
87     "2 -> 16 bits signed little endian\n"           \
88     "3 -> 16 bits signed big endian\n"              \
89     "4 ->  8 bits signed\n"                         \
90     "5 -> 16 bits unsigned little endian\n"         \
91     "6 -> 16 bits unsigned big endian\n"            \
92     "7 -> mpeg2 audio (unsupported)\n"              \
93     "8 -> ac3 pass-through")
94
95 #define RATE_TEXT N_("audio output frequency (Hz)")
96 #define RATE_LONGTEXT N_( \
97     "You can force the audio output frequency here. Common values are " \
98     "48000, 44100, 32000, 22050, 16000, 11025, 8000.")
99
100 #define DESYNC_TEXT N_("compensate desynchronization of audio (in ms)")
101 #define DESYNC_LONGTEXT N_( \
102     "This option allows you to delay the audio output. This can be handy if " \
103     "you notice a lag between the video and the audio.")
104
105 #define VOUT_TEXT N_("video output module")
106 #define VOUT_LONGTEXT N_( \
107     "This option allows you to select the video output method used by vlc. " \
108     "The default behavior is to automatically select the best " \
109     "method available.")
110
111 #define VIDEO_TEXT N_("enable video")
112 #define VIDEO_LONGTEXT N_( \
113     "You can completely disable the video output. In this case the video " \
114     "decoding stage won't be done, which will save some processing power.")
115
116 #define DISPLAY_TEXT N_("display identifier")
117 #define DISPLAY_LONGTEXT N_( \
118     "This is the local display port that will be used for X11 drawing. " \
119     "For instance :0.1.")
120
121 #define WIDTH_TEXT N_("video width")
122 #define WIDTH_LONGTEXT N_( \
123     "You can enforce the video width here. By default vlc will " \
124     "adapt to the video characteristics.")
125
126 #define HEIGHT_TEXT N_("video height")
127 #define HEIGHT_LONGTEXT N_( \
128     "You can enforce the video height here. By default vlc will " \
129     "adapt to the video characteristics.")
130
131 #define ZOOM_TEXT N_("zoom video")
132 #define ZOOM_LONGTEXT N_( \
133     "You can zoom the video by the specified factor.")
134
135 #define GRAYSCALE_TEXT N_("grayscale video output")
136 #define GRAYSCALE_LONGTEXT N_( \
137     "When enabled, the color information from the video won't be decoded " \
138     "(this can also allow you to save some processing power).")
139
140 #define FULLSCREEN_TEXT N_("fullscreen video output")
141 #define FULLSCREEN_LONGTEXT N_( \
142     "If this option is enabled, vlc will always start a video in fullscreen " \
143     "mode.")
144
145 #define OVERLAY_TEXT N_("overlay video output")
146 #define OVERLAY_LONGTEXT N_( \
147     "If enabled, vlc will try to take advantage of the overlay capabilities " \
148     "of you graphics card.")
149
150 #define SPUMARGIN_TEXT N_("force SPU position")
151 #define SPUMARGIN_LONGTEXT N_( \
152     "You can use this option to place the subtitles under the movie, " \
153     "instead of over the movie. Try several positions.")
154
155 #define FILTER_TEXT N_("video filter module")
156 #define FILTER_LONGTEXT N_( \
157     "This will allow you to add a post-processing filter to enhance the " \
158     "picture quality, for instance deinterlacing, or to clone or distort " \
159     "the video window.")
160
161 #define SERVER_PORT_TEXT N_("server port")
162 #define SERVER_PORT_LONGTEXT N_( \
163     "This is the port used for UDP streams. By default, we chose 1234.")
164
165 #define MTU_TEXT N_("MTU of the interface")
166 #define MTU_LONGTEXT N_( \
167     "This is the typical size of UDP packets that we expect. On Ethernet " \
168     "it is usually 1500.")
169
170 #define NETCHANNEL_TEXT N_("enable network channel mode")
171 #define NETCHANNEL_LONGTEXT N_( \
172     "Activate this option if you want to use the VideoLAN Channel Server.")
173
174 #define CHAN_SERV_TEXT N_("channel server address")
175 #define CHAN_SERV_LONGTEXT N_( \
176     "Indicate here the address of the VideoLAN Channel Server.")
177
178 #define CHAN_PORT_TEXT N_("channel server port")
179 #define CHAN_PORT_LONGTEXT N_( \
180     "Indicate here the port on which the VideoLAN Channel Server runs.")
181
182 #define IFACE_TEXT N_("network interface")
183 #define IFACE_LONGTEXT N_( \
184     "If you have several interfaces on your Linux machine and use the " \
185     "VLAN solution, you may indicate here which interface to use.")
186
187 #define INPUT_PROGRAM_TEXT N_("choose program (SID)")
188 #define INPUT_PROGRAM_LONGTEXT N_( \
189     "Choose the program to select by giving its Service ID.")
190
191 #define INPUT_AUDIO_TEXT N_("choose audio")
192 #define INPUT_AUDIO_LONGTEXT N_( \
193     "Give the default type of audio you want to use in a DVD.")
194
195 #define INPUT_CHAN_TEXT N_("choose channel")
196 #define INPUT_CHAN_LONGTEXT N_( \
197     "Give the stream number of the audio channel you want to use in a DVD " \
198     "(from 1 to n).")
199
200 #define INPUT_SUBT_TEXT N_("choose subtitles")
201 #define INPUT_SUBT_LONGTEXT N_( \
202     "Give the stream number of the subtitle channel you want to use in a " \
203     "DVD (from 1 to n).")
204
205 #define DVD_DEV_TEXT N_("DVD device")
206 #define DVD_DEV_LONGTEXT N_( \
207     "This is the default DVD device to use.")
208
209 #define VCD_DEV_TEXT N_("VCD device")
210 #define VCD_DEV_LONGTEXT N_( \
211     "This is the default VCD device to use.")
212
213 #define IPV6_TEXT N_("force IPv6")
214 #define IPV6_LONGTEXT N_( \
215     "If you check this box, IPv6 will be used by default for all UDP and " \
216     "HTTP connections.")
217
218 #define IPV4_TEXT N_("force IPv4")
219 #define IPV4_LONGTEXT N_( \
220     "If you check this box, IPv4 will be used by default for all UDP and " \
221     "HTTP connections.")
222
223 #define CODEC_TEXT N_("choose preferred codec list")
224 #define CODEC_LONGTEXT N_( \
225     "This allows you to select the order in which vlc will choose its " \
226     "codecs. For instance, 'a52,ac3,any' will try the a52 codec before " \
227     "the ac3 one. Please be aware that vlc does not make any difference " \
228     "between audio or video codecs, so you should always specify 'any' at " \
229     "the end of the list to make sure there is a fallback for all types.")
230
231 #define MMX_TEXT N_("enable CPU MMX support")
232 #define MMX_LONGTEXT N_( \
233     "If your processor supports the MMX instructions set, vlc can take " \
234     "advantage of them.")
235
236 #define THREE_DN_TEXT N_("enable CPU 3D Now! support")
237 #define THREE_DN_LONGTEXT N_( \
238     "If your processor supports the 3D Now! instructions set, vlc can take "\
239     "advantage of them.")
240
241 #define MMXEXT_TEXT N_("enable CPU MMX EXT support")
242 #define MMXEXT_LONGTEXT N_( \
243     "If your processor supports the MMX EXT instructions set, vlc can take "\
244     "advantage of them.")
245
246 #define SSE_TEXT N_("enable CPU SSE support")
247 #define SSE_LONGTEXT N_( \
248     "If your processor supports the SSE instructions set, vlc can take " \
249     "can take advantage of them.")
250
251 #define ALTIVEC_TEXT N_("enable CPU AltiVec support")
252 #define ALTIVEC_LONGTEXT N_( \
253     "If your processor supports the AltiVec instructions set, vlc can take "\
254     "advantage of them.")
255
256 #define PL_LAUNCH_TEXT N_("launch playlist on startup")
257 #define PL_LAUNCH_LONGTEXT N_( \
258     "If you want vlc to start playing on startup, then enable this option.")
259
260 #define PL_ENQUEUE_TEXT N_("enqueue items in playlist")
261 #define PL_ENQUEUE_LONGTEXT N_( \
262     "If you want vlc to add items to the playlist as you open them, then " \
263     "enable this option.")
264
265 #define PL_LOOP_TEXT N_("loop playlist on end")
266 #define PL_LOOP_LONGTEXT N_( \
267     "If you want vlc to keep playing the playlist indefinitely then enable " \
268     "this option.")
269
270 #define MEMCPY_TEXT N_("memory copy module")
271 #define MEMCPY_LONGTEXT N_( \
272     "You can select wich memory copy module you want to use. By default vlc " \
273     "will select the fastest one supported by your hardware.")
274
275 #define ACCESS_TEXT N_("access module")
276 #define ACCESS_LONGTEXT N_( \
277     "This is a legacy entry to let you configure access modules")
278
279 #define DEMUX_TEXT N_("demux module")
280 #define DEMUX_LONGTEXT N_( \
281     "This is a legacy entry to let you configure demux modules")
282
283 #define FAST_MUTEX_TEXT N_("fast mutex on NT/2K/XP (developpers only)")
284 #define FAST_MUTEX_LONGTEXT N_( \
285     "On Windows NT/2K/XP we use a slow mutex implementation but which " \
286     "allows us to correctely implement condition variables. " \
287     "You can also use the faster Win9x implementation but you might " \
288     "experience problems with it.")
289
290 #define WIN9X_CV_TEXT N_("Condition variables implementation for Win9x " \
291     "(developpers only)")
292 #define WIN9X_CV_LONGTEXT N_( \
293     "On Windows 9x/Me we use a fast but not correct condition variables " \
294     "implementation (more precisely there is a possibility for a race " \
295     "condition to happen). " \
296     "However it is possible to use slower alternatives which should be more " \
297     "robust. " \
298     "Currently you can choose between implementation 0 (which is the " \
299     "default and the fastest), 1 and 2.")
300
301 #define PLAYLIST_USAGE N_("\nPlaylist items:" \
302     "\n  *.mpg, *.vob                   plain MPEG-1/2 files" \
303     "\n  [dvd:][device][@raw_device][@[title][,[chapter][,angle]]]" \
304     "\n                                 DVD device" \
305     "\n  [vcd:][device][@[title][,[chapter]]" \
306     "\n                                 VCD device" \
307     "\n  udpstream:[@[<bind address>][:<bind port>]]" \
308     "\n                                 UDP stream sent by VLS" \
309     "\n  vlc:loop                       loop execution of the " \
310     "playlist" \
311     "\n  vlc:pause                      pause execution of " \
312     "playlist items" \
313     "\n  vlc:quit                       quit VLC" \
314     "\n")
315
316 /*
317  * Quick usage guide for the configuration options:
318  *
319  * MODULE_CONFIG_START
320  * MODULE_CONFIG_STOP
321  * ADD_CATEGORY_HINT( N_(text), N_(longtext) )
322  * ADD_SUBCATEGORY_HINT( N_(text), N_(longtext) )
323  * ADD_USAGE_HINT( N_(text) )
324  * ADD_STRING( option_name, value, p_callback, N_(text), N_(longtext) )
325  * ADD_FILE( option_name, psz_value, p_callback, N_(text), N_(longtext) )
326  * ADD_MODULE( option_name, psz_value, i_capability, p_callback,
327  *             N_(text), N_(longtext) )
328  * ADD_INTEGER( option_name, i_value, p_callback, N_(text), N_(longtext) )
329  * ADD_BOOL( option_name, b_value, p_callback, N_(text), N_(longtext) )
330  */
331
332 MODULE_CONFIG_START
333
334 /* Interface options */
335 ADD_CATEGORY_HINT( N_("Interface"), NULL)
336 ADD_MODULE_WITH_SHORT ( "intf", 'I', MODULE_CAPABILITY_INTF, NULL, NULL, INTF_TEXT, INTF_LONGTEXT )
337 ADD_BOOL_WITH_SHORT ( "verbose", 'v', 0, NULL, VERBOSE_TEXT, VERBOSE_LONGTEXT )
338 ADD_BOOL_WITH_SHORT ( "quiet", 'q', 0, NULL, QUIET_TEXT, QUIET_LONGTEXT )
339 ADD_BOOL            ( "color", 0, NULL, COLOR_TEXT, COLOR_LONGTEXT )
340 ADD_STRING  ( "search-path", NULL, NULL, INTF_PATH_TEXT, INTF_PATH_LONGTEXT )
341 ADD_STRING  ( "plugin-path", NULL, NULL, PLUGIN_PATH_TEXT, PLUGIN_PATH_LONGTEXT )
342
343 /* Audio options */
344 ADD_CATEGORY_HINT( N_("Audio"), NULL)
345 ADD_MODULE_WITH_SHORT ( "aout", 'A', MODULE_CAPABILITY_AOUT, NULL, NULL, AOUT_TEXT, AOUT_LONGTEXT )
346 ADD_BOOL    ( "audio", 1, NULL, AUDIO_TEXT, AUDIO_LONGTEXT )
347 ADD_BOOL    ( "mono", 0, NULL, MONO_TEXT, MONO_LONGTEXT )
348 ADD_INTEGER ( "volume", VOLUME_DEFAULT, NULL, VOLUME_TEXT, VOLUME_LONGTEXT )
349 ADD_INTEGER ( "rate", 44100, NULL, RATE_TEXT, RATE_LONGTEXT )
350 ADD_INTEGER ( "desync", 0, NULL, DESYNC_TEXT, DESYNC_LONGTEXT )
351 ADD_INTEGER ( "audio-format", 0, NULL, FORMAT_TEXT, FORMAT_LONGTEXT )
352
353 /* Video options */
354 ADD_CATEGORY_HINT( N_("Video"), NULL )
355 ADD_MODULE_WITH_SHORT ( "vout", 'V', MODULE_CAPABILITY_VOUT, NULL, NULL, VOUT_TEXT, VOUT_LONGTEXT )
356 ADD_BOOL    ( "video", 1, NULL, VIDEO_TEXT, VIDEO_LONGTEXT )
357 ADD_INTEGER ( "width", -1, NULL, WIDTH_TEXT, WIDTH_LONGTEXT )
358 ADD_INTEGER ( "height", -1, NULL, HEIGHT_TEXT, HEIGHT_LONGTEXT )
359 ADD_FLOAT   ( "zoom", 1, NULL, ZOOM_TEXT, ZOOM_LONGTEXT )
360 ADD_BOOL    ( "grayscale", 0, NULL, GRAYSCALE_TEXT, GRAYSCALE_LONGTEXT )
361 ADD_BOOL    ( "fullscreen", 0, NULL, FULLSCREEN_TEXT, FULLSCREEN_LONGTEXT )
362 ADD_BOOL    ( "overlay", 1, NULL, OVERLAY_TEXT, OVERLAY_LONGTEXT )
363 ADD_INTEGER ( "spumargin", -1, NULL, SPUMARGIN_TEXT, SPUMARGIN_LONGTEXT )
364 ADD_MODULE  ( "filter", MODULE_CAPABILITY_VOUT_FILTER, NULL, NULL, FILTER_TEXT, FILTER_LONGTEXT )
365
366 /* Input options */
367 ADD_CATEGORY_HINT( N_("Input"), NULL )
368 ADD_INTEGER ( "server-port", 1234, NULL, SERVER_PORT_TEXT, SERVER_PORT_LONGTEXT )
369 ADD_BOOL    ( "network-channel", 0, NULL, NETCHANNEL_TEXT, NETCHANNEL_LONGTEXT )
370 ADD_STRING  ( "channel-server", "localhost", NULL, CHAN_SERV_TEXT, CHAN_SERV_LONGTEXT )
371 ADD_INTEGER ( "channel-port", 6010, NULL, CHAN_PORT_TEXT, CHAN_PORT_LONGTEXT )
372 ADD_INTEGER ( "mtu", 1500, NULL, MTU_TEXT, MTU_LONGTEXT )
373 ADD_STRING  ( "iface", "eth0", NULL, IFACE_TEXT, IFACE_LONGTEXT )
374
375 ADD_INTEGER ( "program", 0, NULL, INPUT_PROGRAM_TEXT, INPUT_PROGRAM_LONGTEXT )
376 ADD_INTEGER ( "audio-type", -1, NULL, INPUT_AUDIO_TEXT, INPUT_AUDIO_LONGTEXT )
377 ADD_INTEGER ( "audio-channel", -1, NULL, INPUT_CHAN_TEXT, INPUT_CHAN_LONGTEXT )
378 ADD_INTEGER ( "spu-channel", -1, NULL, INPUT_SUBT_TEXT, INPUT_SUBT_LONGTEXT )
379
380 ADD_STRING  ( "dvd", DVD_DEVICE, NULL, DVD_DEV_TEXT, DVD_DEV_LONGTEXT )
381 ADD_STRING  ( "vcd", VCD_DEVICE, NULL, VCD_DEV_TEXT, VCD_DEV_LONGTEXT )
382
383 ADD_BOOL_WITH_SHORT ( "ipv6", '6', 0, NULL, IPV6_TEXT, IPV6_LONGTEXT )
384 ADD_BOOL_WITH_SHORT ( "ipv4", '4', 0, NULL, IPV4_TEXT, IPV4_LONGTEXT )
385
386 /* Decoder options */
387 ADD_CATEGORY_HINT( N_("Decoders"), NULL )
388 ADD_MODULE  ( "codec", MODULE_CAPABILITY_DECODER, NULL, NULL, CODEC_TEXT, CODEC_LONGTEXT )
389
390 /* CPU options */
391 ADD_CATEGORY_HINT( N_("CPU"), NULL )
392 ADD_BOOL ( "mmx", 1, NULL, MMX_TEXT, MMX_LONGTEXT )
393 ADD_BOOL ( "3dn", 1, NULL, THREE_DN_TEXT, THREE_DN_LONGTEXT )
394 ADD_BOOL ( "mmxext", 1, NULL, MMXEXT_TEXT, MMXEXT_LONGTEXT )
395 ADD_BOOL ( "sse", 1, NULL, SSE_TEXT, SSE_LONGTEXT )
396 ADD_BOOL ( "altivec", 1, NULL, ALTIVEC_TEXT, ALTIVEC_LONGTEXT )
397
398 /* Playlist options */
399 ADD_CATEGORY_HINT( N_("Playlist"), NULL )
400 ADD_BOOL ( "playlist", 0, NULL, PL_LAUNCH_TEXT, PL_LAUNCH_LONGTEXT )
401 ADD_BOOL ( "enqueue", 0, NULL, PL_ENQUEUE_TEXT, PL_ENQUEUE_LONGTEXT )
402 ADD_BOOL ( "loop", 0, NULL, PL_LOOP_TEXT, PL_LOOP_LONGTEXT )
403
404 /* Misc options */
405 ADD_CATEGORY_HINT( N_("Miscellaneous"), NULL )
406 ADD_MODULE  ( "memcpy", MODULE_CAPABILITY_MEMCPY, NULL, NULL, MEMCPY_TEXT, MEMCPY_LONGTEXT )
407 ADD_MODULE  ( "access", MODULE_CAPABILITY_ACCESS, NULL, NULL, ACCESS_TEXT, ACCESS_LONGTEXT )
408 ADD_MODULE  ( "demux", MODULE_CAPABILITY_DEMUX, NULL, NULL, DEMUX_TEXT, DEMUX_LONGTEXT )
409
410 #if defined(WIN32)
411 ADD_BOOL ( "fast-mutex", 0, NULL, FAST_MUTEX_TEXT, FAST_MUTEX_LONGTEXT )
412 ADD_INTEGER ( "win9x-cv-method", 0, NULL, WIN9X_CV_TEXT, WIN9X_CV_LONGTEXT )
413 #endif
414
415 /* Usage (mainly useful for cmd line stuff) */
416 ADD_USAGE_HINT( PLAYLIST_USAGE )
417
418 MODULE_CONFIG_STOP
419
420 MODULE_INIT_START
421     SET_DESCRIPTION( N_("main program") )
422     ADD_CAPABILITY( MAIN, 100/*whatever*/ )
423 MODULE_INIT_STOP
424
425 MODULE_ACTIVATE_START
426 MODULE_ACTIVATE_STOP
427
428 MODULE_DEACTIVATE_START
429 MODULE_DEACTIVATE_STOP
430
431 static module_config_t p_help_config[] =
432 {
433     { CONFIG_ITEM_BOOL, "help", 'h', N_("print help") },
434     { CONFIG_ITEM_BOOL, "longhelp", 'H', N_("print detailed help") },
435     { CONFIG_ITEM_BOOL, "list", 'l', N_("print a list of available modules") },
436     { CONFIG_ITEM_STRING, "module", 'p', N_("print help on module") },
437     { CONFIG_ITEM_BOOL, "version", '\0', N_("print version information") },
438     { CONFIG_ITEM_BOOL, "build", '\0', N_("print build information") },
439     { CONFIG_HINT_END, NULL, '\0' }
440 };
441
442 /*****************************************************************************
443  * End configuration.
444  *****************************************************************************/