1 /*****************************************************************************
2 * libvlc.h: libvlc_* new external API
3 *****************************************************************************
4 * Copyright (C) 1998-2005 the VideoLAN team
5 * $Id: vlc.h 13701 2005-12-12 17:58:56Z zorglub $
7 * Authors: Clément Stenac <zorglub@videolan.org>
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22 *****************************************************************************/
25 * \defgroup libvlc Libvlc
26 * This is libvlc, the base library of the VLC program.
45 /*****************************************************************************
47 *****************************************************************************/
48 /** defgroup libvlc_exception Exceptions
50 * LibVLC Exceptions handling
54 struct libvlc_exception_t
59 typedef struct libvlc_exception_t libvlc_exception_t;
62 * Initialize an exception structure. This can be called several times to reuse
63 * an exception structure.
64 * \param p_exception the exception to initialize
66 void libvlc_exception_init( libvlc_exception_t *p_exception );
69 * Has an exception been raised ?
70 * \param p_exception the exception to query
71 * \return 0 if no exception raised, 1 else
73 int libvlc_exception_raised( libvlc_exception_t *p_exception );
77 * \param p_exception the exception to raise
78 * \param psz_message the exception message
80 void libvlc_exception_raise( libvlc_exception_t *p_exception, char *psz_format, ... );
83 * Clear an exception object so it can be reused.
84 * The exception object must be initialized
85 * \param p_exception the exception to clear
87 void libvlc_exception_clear( libvlc_exception_t * );
90 * Get exception message
91 * \param p_exception the exception to query
92 * \return the exception message or NULL if not applicable (exception not raised
95 char* libvlc_exception_get_message( libvlc_exception_t *p_exception );
99 /*****************************************************************************
101 *****************************************************************************/
103 /** defgroup libvlc_core Core
109 /** This structure is opaque. It represents a libvlc instance */
110 typedef struct libvlc_instance_t libvlc_instance_t;
113 * Create an initialized libvlc instance
114 * \param argc the number of arguments
115 * \param argv command-line-type arguments
116 * \param exception an initialized exception pointer
118 libvlc_instance_t * libvlc_new( int , char **, libvlc_exception_t *);
121 * Destroy a libvlc instance
122 * \param p_instance the instance to destroy
124 void libvlc_destroy( libvlc_instance_t *);
128 /*****************************************************************************
130 *****************************************************************************/
131 /** defgroup libvlc_playlist Playlist
133 * LibVLC Playlist handling
138 * Start playing. You can give some additionnal playlist item options
139 * that will be added to the item before playing it.
140 * \param p_instance the instance
141 * \param i_id the item to play. If this is a negative number, the next
142 * item will be selected. Else, the item with the given ID will be played
143 * \param i_options the number of options to add to the item
144 * \param ppsz_options the options to add to the item
145 * \param p_exception an initialized exception
147 void libvlc_playlist_play( libvlc_instance_t*, int, int, char **,
148 libvlc_exception_t * );
151 * Pause a running playlist, resume if it was stopped
152 * \param p_instance the instance to pause
153 * \param p_exception an initialized exception
155 void libvlc_playlist_pause( libvlc_instance_t *, libvlc_exception_t * );
158 * Checks if the playlist is running
159 * \param p_instance the instance
160 * \param p_exception an initialized exception
161 * \return 0 if the playlist is stopped or paused, 1 if it is running
163 int libvlc_playlist_isplaying( libvlc_instance_t *, libvlc_exception_t * );
166 * Get the number of items in the playlist
167 * \param p_instance the instance
168 * \param p_exception an initialized exception
169 * \return the number of items
171 int libvlc_playlist_items_count( libvlc_instance_t *, libvlc_exception_t * );
175 * \param p_instance the instance to stop
176 * \param p_exception an initialized exception
178 void libvlc_playlist_stop( libvlc_instance_t *, libvlc_exception_t * );
181 * Go to next playlist item (starts playback if it was stopped)
182 * \param p_instance the instance to use
183 * \param p_exception an initialized exception
185 void libvlc_playlist_next( libvlc_instance_t *, libvlc_exception_t * );
188 * Go to previous playlist item (starts playback if it was stopped)
189 * \param p_instance the instance to use
190 * \param p_exception an initialized exception
192 void libvlc_playlist_prev( libvlc_instance_t *, libvlc_exception_t * );
195 * Remove all playlist items
196 * \param p_instance the instance
197 * \param p_exception an initialized exception
199 void libvlc_playlist_clear( libvlc_instance_t *, libvlc_exception_t * );
202 * Go to next playlist item
203 * \param p_instance the instance
204 * \param p_exception an initialized exception
206 void libvlc_playlist_next( libvlc_instance_t *, libvlc_exception_t * );
209 * Go to Previous playlist item
210 * \param p_instance the instance
211 * \param p_exception an initialized exception
213 void libvlc_playlist_prev( libvlc_instance_t *, libvlc_exception_t * );
216 * Add an item at the end of the playlist
217 * If you need more advanced options, \see libvlc_playlist_add_extended
218 * \param p_instance the instance
219 * \param psz_uri the URI to open, using VLC format
220 * \param psz_name a name that you might want to give or NULL
221 * \return the identifier of the new item
223 int libvlc_playlist_add( libvlc_instance_t *, const char *, const char *,
224 libvlc_exception_t * );
227 * Add an item at the end of the playlist, with additional input options
228 * \param p_instance the instance
229 * \param psz_uri the URI to open, using VLC format
230 * \param psz_name a name that you might want to give or NULL
231 * \param i_options the number of options to add
232 * \param ppsz_options strings representing the options to add
233 * \return the identifier of the new item
235 int libvlc_playlist_add_extended( libvlc_instance_t *, const char *,
236 const char *, int, const char **,
237 libvlc_exception_t * );
240 int libvlc_playlist_delete_item( libvlc_instance_t *, int,
241 libvlc_exception_t * );
243 typedef struct libvlc_input_t libvlc_input_t;
245 /* Get the input that is currently being played by the playlist
246 * \param p_instance the instance to use
247 * \param p_exception an initialized excecption
248 * \return an input object
250 libvlc_input_t *libvlc_playlist_get_input( libvlc_instance_t *,
251 libvlc_exception_t * );
257 /*****************************************************************************
259 *****************************************************************************/
260 /** defgroup libvlc_input Input
262 * LibVLC Input handling
266 /** Free an input object
267 * \param p_input the input to free
269 void libvlc_input_free( libvlc_input_t * );
271 /// \bug This might go away ... to be replaced by a broader system
272 vlc_int64_t libvlc_input_get_length ( libvlc_input_t *, libvlc_exception_t *);
273 vlc_int64_t libvlc_input_get_time ( libvlc_input_t *, libvlc_exception_t *);
274 float libvlc_input_get_position ( libvlc_input_t *, libvlc_exception_t *);
275 vlc_bool_t libvlc_input_will_play ( libvlc_input_t *, libvlc_exception_t *);
276 vlc_bool_t libvlc_input_has_vout ( libvlc_input_t *, libvlc_exception_t *);
277 float libvlc_input_get_fps ( libvlc_input_t *, libvlc_exception_t *);
281 /** defgroup libvlc_video Video
283 * LibVLC Video handling
288 * Toggle fullscreen status on video output
289 * \param p_input the input
290 * \param p_exception an initialized exception
292 void libvlc_toggle_fullscreen( libvlc_input_t *, libvlc_exception_t * );
295 * Enable or disable fullscreen on a video output
296 * \param p_input the input
297 * \param b_fullscreen boolean for fullscreen status
298 * \param p_exception an initialized exception
300 void libvlc_set_fullscreen( libvlc_input_t *, int, libvlc_exception_t * );
303 * Get current fullscreen status
304 * \param p_input the input
305 * \param p_exception an initialized exception
306 * \return the fullscreen status (boolean)
308 int libvlc_get_fullscreen( libvlc_input_t *, libvlc_exception_t * );
311 * Get current video height
312 * \param p_input the input
313 * \param p_exception an initialized exception
314 * \return the video height
316 int libvlc_video_get_height( libvlc_input_t *, libvlc_exception_t * );
319 * Get current video width
320 * \param p_input the input
321 * \param p_exception an initialized exception
322 * \return the video width
324 int libvlc_video_get_width( libvlc_input_t *, libvlc_exception_t * );
327 * Take a snapshot of the current video window
328 * \param p_input the input
329 * \param psz_filepath the path where to save the screenshot to
330 * \param p_exception an initialized exception
332 void libvlc_video_take_snapshot( libvlc_input_t *, char *, libvlc_exception_t * );
334 int libvlc_video_destroy( libvlc_input_t *, libvlc_exception_t *);
337 int libvlc_video_reparent( libvlc_input_t *, Drawable, libvlc_exception_t * );
344 * defgroup libvlc_vlm VLM
346 * LibVLC VLM handling
350 /** defgroup libvlc_audio Audio
352 * LibVLC Audio handling
357 * Get current mute status
358 * \param p_instance libvlc instance
359 * \param p_exception an initialized exception
360 * \return the mute status (boolean)
362 vlc_bool_t libvlc_audio_get_mute( libvlc_instance_t *, libvlc_exception_t * );
366 * \param p_instance libvlc instance
367 * \param status If status is VLC_TRUE then mute, otherwise unmute
368 * \param p_exception an initialized exception
371 void libvlc_audio_set_mute( libvlc_instance_t *, vlc_bool_t , libvlc_exception_t * );
375 * Get current audio level
376 * \param p_instance libvlc instance
377 * \param p_exception an initialized exception
378 * \return the audio level (int)
380 int libvlc_audio_get_volume( libvlc_instance_t *, libvlc_exception_t * );
384 * Set current audio level
385 * \param p_instance libvlc instance
386 * \param i_volume the volume (int)
387 * \param p_exception an initialized exception
390 void libvlc_audio_set_volume( libvlc_instance_t *, int , libvlc_exception_t *);
396 * Add a broadcast, with one input
397 * \param p_instance the instance
398 * \param psz_name the name of the new broadcast
399 * \param psz_input the input MRL
400 * \param psz_output the output MRL (the parameter to the "sout" variable)
401 * \param i_options number of additional options
402 * \param ppsz_options additional options
403 * \param b_enabled boolean for enabling the new broadcast
404 * \param b_loop Should this broadcast be played in loop ?
405 * \param p_exception an initialized exception
407 void libvlc_vlm_add_broadcast( libvlc_instance_t *, char *, char *, char* ,
408 int, char **, int, int, libvlc_exception_t * );
411 * Delete a media (vod or broadcast)
412 * \param p_instance the instance
413 * \param psz_name the media to delete
414 * \param p_exception an initialized exception
416 void libvlc_vlm_del_media( libvlc_instance_t *, char *, libvlc_exception_t * );
419 * Enable or disable a media (vod or broadcast)
420 * \param p_instance the instance
421 * \param psz_name the media to work on
422 * \param b_enabled the new status
423 * \param p_exception an initialized exception
425 void libvlc_vlm_set_enabled( libvlc_instance_t *, char *, int,
426 libvlc_exception_t *);
429 * Set the output for a media
430 * \param p_instance the instance
431 * \param psz_name the media to work on
432 * \param psz_output the output MRL (the parameter to the "sout" variable)
433 * \param p_exception an initialized exception
435 void libvlc_vlm_set_output( libvlc_instance_t *, char *, char*,
436 libvlc_exception_t *);
439 * Set a media's input MRL. This will delete all existing inputs and
440 * add the specified one.
441 * \param p_instance the instance
442 * \param psz_name the media to work on
443 * \param psz_input the input MRL
444 * \param p_exception an initialized exception
446 void libvlc_vlm_set_input( libvlc_instance_t *, char *, char*,
447 libvlc_exception_t *);
452 * Set output for a media
453 * \param p_instance the instance
454 * \param psz_name the media to work on
455 * \param b_loop the new status
456 * \param p_exception an initialized exception
458 void libvlc_vlm_set_loop( libvlc_instance_t *, char *, int,
459 libvlc_exception_t *);
465 * Edit the parameters of a media. This will delete all existing inputs and
466 * add the specified one.
467 * \param p_instance the instance
468 * \param psz_name the name of the new broadcast
469 * \param psz_input the input MRL
470 * \param psz_output the output MRL (the parameter to the "sout" variable)
471 * \param i_options number of additional options
472 * \param ppsz_options additional options
473 * \param b_enabled boolean for enabling the new broadcast
474 * \param b_loop Should this broadcast be played in loop ?
475 * \param p_exception an initialized exception
477 void libvlc_vlm_change_media( libvlc_instance_t *, char *, char *, char* ,
478 int, char **, int, int, libvlc_exception_t * );
481 * Plays the named broadcast.
482 * \param p_instance the instance
483 * \param psz_name the name of the broadcast
484 * \param p_exception an initialized exception
486 void libvlc_vlm_play_media ( libvlc_instance_t *, char *, libvlc_exception_t * );
489 * Stops the named broadcast.
490 * \param p_instance the instance
491 * \param psz_name the name of the broadcast
492 * \param p_exception an initialized exception
494 void libvlc_vlm_stop_media ( libvlc_instance_t *, char *, libvlc_exception_t * );
498 * Pauses the named broadcast.
499 * \param p_instance the instance
500 * \param psz_name the name of the broadcast
501 * \param p_exception an initialized exception
503 void libvlc_vlm_pause_media( libvlc_instance_t *, char *, libvlc_exception_t * );
514 #endif /* <vlc/libvlc.h> */