libvlc_audio_*: remove useless exception parameters
[vlc.git] / include / vlc / libvlc_media_player.h
1 /*****************************************************************************
2  * libvlc_media_player.h:  libvlc_media_player external API
3  *****************************************************************************
4  * Copyright (C) 1998-2009 the VideoLAN team
5  * $Id$
6  *
7  * Authors: ClĂ©ment Stenac <zorglub@videolan.org>
8  *          Jean-Paul Saman <jpsaman@videolan.org>
9  *          Pierre d'Herbemont <pdherbemont@videolan.org>
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., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24  *****************************************************************************/
25
26 /**
27  * \file
28  * This file defines libvlc_media_player external API
29  */
30
31 #ifndef VLC_LIBVLC_MEDIA_PLAYER_H
32 #define VLC_LIBVLC_MEDIA_PLAYER_H 1
33
34 /*****************************************************************************
35  * Media Player
36  *****************************************************************************/
37 /** \defgroup libvlc_media_player libvlc_media_player
38  * \ingroup libvlc
39  * LibVLC Media Player, object that let you play a media
40  * in a custom drawable
41  * @{
42  */
43
44 typedef struct libvlc_media_player_t libvlc_media_player_t;
45
46 /**
47  * Description for video, audio tracks and subtitles. It contains
48  * id, name (description string) and pointer to next record.
49  */
50 typedef struct libvlc_track_description_t
51 {
52     int   i_id;
53     char *psz_name;
54     struct libvlc_track_description_t *p_next;
55     
56 } libvlc_track_description_t;
57
58 /**
59  * Description for audio output. It contains
60  * name, description and pointer to next record.
61  */
62 typedef struct libvlc_audio_output_t
63 {
64     char *psz_name;
65     char *psz_description;
66     struct libvlc_audio_output_t *p_next;
67     
68 } libvlc_audio_output_t;
69
70 /**
71  * Rectangle type for video geometry
72  */
73 typedef struct libvlc_rectangle_t
74 {
75     int top, left;
76     int bottom, right;
77 } libvlc_rectangle_t;
78
79 /**
80  * Marq int options definition
81  */
82 typedef enum libvlc_video_marquee_int_option_t {
83     libvlc_marquee_Enabled = 0,
84     libvlc_marquee_Color,
85     libvlc_marquee_Opacity,
86     libvlc_marquee_Position,
87     libvlc_marquee_Refresh,
88     libvlc_marquee_Size,
89     libvlc_marquee_Timeout,
90     libvlc_marquee_X,
91     libvlc_marquee_Y
92 } libvlc_video_marquee_int_option_t;
93
94 /**
95  * Marq string options definition
96  */
97 typedef enum libvlc_video_marquee_string_option_t {
98     libvlc_marquee_Text = 0
99 } libvlc_video_marquee_string_option_t;
100
101
102 /**
103  * Create an empty Media Player object
104  *
105  * \param p_libvlc_instance the libvlc instance in which the Media Player
106  *        should be created.
107  * \param p_e an initialized exception pointer
108  */
109 VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *, libvlc_exception_t * );
110
111 /**
112  * Create a Media Player object from a Media
113  *
114  * \param p_md the media. Afterwards the p_md can be safely
115  *        destroyed.
116  * \param p_e an initialized exception pointer
117  */
118 VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *, libvlc_exception_t * );
119
120 /**
121  * Release a media_player after use
122  * Decrement the reference count of a media player object. If the
123  * reference count is 0, then libvlc_media_player_release() will
124  * release the media player object. If the media player object
125  * has been released, then it should not be used again.
126  *
127  * \param p_mi the Media Player to free
128  */
129 VLC_PUBLIC_API void libvlc_media_player_release( libvlc_media_player_t * );
130
131 /**
132  * Retain a reference to a media player object. Use
133  * libvlc_media_player_release() to decrement reference count.
134  *
135  * \param p_mi media player object
136  */
137 VLC_PUBLIC_API void libvlc_media_player_retain( libvlc_media_player_t * );
138
139 /**
140  * Set the media that will be used by the media_player. If any,
141  * previous md will be released.
142  *
143  * \param p_mi the Media Player
144  * \param p_md the Media. Afterwards the p_md can be safely
145  *        destroyed.
146  * \param p_e an initialized exception pointer
147  */
148 VLC_PUBLIC_API void libvlc_media_player_set_media( libvlc_media_player_t *, libvlc_media_t *, libvlc_exception_t * );
149
150 /**
151  * Get the media used by the media_player.
152  *
153  * \param p_mi the Media Player
154  * \param p_e an initialized exception pointer
155  * \return the media associated with p_mi, or NULL if no
156  *         media is associated
157  */
158 VLC_PUBLIC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t *, libvlc_exception_t * );
159
160 /**
161  * Get the Event Manager from which the media player send event.
162  *
163  * \param p_mi the Media Player
164  * \param p_e an initialized exception pointer
165  * \return the event manager associated with p_mi
166  */
167 VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *, libvlc_exception_t * );
168
169 /**
170  * is_playing
171  *
172  * \param p_mi the Media Player
173  * \param p_e an initialized exception pointer
174  * \return 1 if the media player is playing, 0 otherwise
175  */
176 VLC_PUBLIC_API int libvlc_media_player_is_playing ( libvlc_media_player_t *, libvlc_exception_t * );
177
178 /**
179  * Play
180  *
181  * \param p_mi the Media Player
182  * \param p_e an initialized exception pointer
183  */
184 VLC_PUBLIC_API void libvlc_media_player_play ( libvlc_media_player_t *, libvlc_exception_t * );
185
186 /**
187  * Pause
188  *
189  * \param p_mi the Media Player
190  * \param p_e an initialized exception pointer
191  */
192 VLC_PUBLIC_API void libvlc_media_player_pause ( libvlc_media_player_t *, libvlc_exception_t * );
193
194 /**
195  * Stop
196  *
197  * \param p_mi the Media Player
198  * \param p_e an initialized exception pointer
199  */
200 VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t *, libvlc_exception_t * );
201
202 /**
203  * Set the agl handler where the media player should render its video output.
204  *
205  * \param p_mi the Media Player
206  * \param drawable the agl handler
207  * \param p_e an initialized exception pointer
208  */
209 VLC_PUBLIC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable, libvlc_exception_t *p_e );
210
211 /**
212  * Get the agl handler previously set with libvlc_media_player_set_agl().
213  *
214  * \param p_mi the Media Player
215  * \return the agl handler or 0 if none where set
216  */
217 VLC_PUBLIC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi );
218         
219 /**
220  * Set the agl handler where the media player should render its video output.
221  *
222  * \param p_mi the Media Player
223  * \param drawable the agl handler
224  * \param p_e an initialized exception pointer
225  */
226 VLC_PUBLIC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable, libvlc_exception_t *p_e );
227
228 /**
229  * Get the agl handler previously set with libvlc_media_player_set_agl().
230  *
231  * \param p_mi the Media Player
232  * \return the agl handler or 0 if none where set
233  */
234 VLC_PUBLIC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_mi );
235
236 /**
237  * Set an X Window System drawable where the media player should render its
238  * video output. If LibVLC was built without X11 output support, then this has
239  * no effects.
240  *
241  * The specified identifier must correspond to an existing Input/Output class
242  * X11 window. Pixmaps are <b>not</b> supported. The caller shall ensure that
243  * the X11 server is the same as the one the VLC instance has been configured
244  * with.
245  * If XVideo is <b>not</b> used, it is assumed that the drawable has the
246  * following properties in common with the default X11 screen: depth, scan line
247  * pad, black pixel. This is a bug.
248  *
249  * \param p_mi the Media Player
250  * \param drawable the ID of the X window
251  * \param p_e an initialized exception pointer
252  */
253 VLC_PUBLIC_API void libvlc_media_player_set_xwindow ( libvlc_media_player_t *p_mi, uint32_t drawable, libvlc_exception_t *p_e );
254
255 /**
256  * Get the X Window System window identifier previously set with
257  * libvlc_media_player_set_xwindow(). Note that this will return the identifier
258  * even if VLC is not currently using it (for instance if it is playing an
259  * audio-only input).
260  *
261  * \param p_mi the Media Player
262  * \return an X window ID, or 0 if none where set.
263  */
264 VLC_PUBLIC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi );
265
266 /**
267  * Set a Win32/Win64 API window handle (HWND) where the media player should
268  * render its video output. If LibVLC was built without Win32/Win64 API output
269  * support, then this has no effects.
270  *
271  * \param p_mi the Media Player
272  * \param drawable windows handle of the drawable
273  * \param p_e an initialized exception pointer
274  */
275 VLC_PUBLIC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable, libvlc_exception_t *p_e );
276
277 /**
278  * Get the Windows API window handle (HWND) previously set with
279  * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC
280  * is not currently outputting any video to it.
281  *
282  * \param p_mi the Media Player
283  * \return a window handle or NULL if there are none.
284  */
285 VLC_PUBLIC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );
286
287
288
289 /** \bug This might go away ... to be replaced by a broader system */
290
291 /**
292  * Get the current movie length (in ms).
293  *
294  * \param p_mi the Media Player
295  * \param p_e an initialized exception pointer
296  * \return the movie length (in ms).
297  */
298 VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *, libvlc_exception_t *);
299
300 /**
301  * Get the current movie time (in ms).
302  *
303  * \param p_mi the Media Player
304  * \param p_e an initialized exception pointer
305  * \return the movie time (in ms).
306  */
307 VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *, libvlc_exception_t *);
308
309 /**
310  * Set the movie time (in ms).
311  *
312  * \param p_mi the Media Player
313  * \param the movie time (in ms).
314  * \param p_e an initialized exception pointer
315  */
316 VLC_PUBLIC_API void libvlc_media_player_set_time( libvlc_media_player_t *, libvlc_time_t, libvlc_exception_t *);
317
318 /**
319  * Get movie position.
320  *
321  * \param p_mi the Media Player
322  * \param p_e an initialized exception pointer
323  * \return movie position
324  */
325 VLC_PUBLIC_API float libvlc_media_player_get_position( libvlc_media_player_t *, libvlc_exception_t *);
326
327 /**
328  * Set movie position.
329  *
330  * \param p_mi the Media Player
331  * \param f_pos the position
332  * \param p_e an initialized exception pointer
333  */
334 VLC_PUBLIC_API void libvlc_media_player_set_position( libvlc_media_player_t *, float, libvlc_exception_t *);
335
336 /**
337  * Set movie chapter
338  *
339  * \param p_mi the Media Player
340  * \param i_chapter chapter number to play
341  * \param p_e an initialized exception pointer
342  */
343 VLC_PUBLIC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *, int, libvlc_exception_t *);
344
345 /**
346  * Get movie chapter
347  *
348  * \param p_mi the Media Player
349  * \param p_e an initialized exception pointer
350  * \return chapter number currently playing
351  */
352 VLC_PUBLIC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *, libvlc_exception_t * );
353
354 /**
355  * Get movie chapter count
356  *
357  * \param p_mi the Media Player
358  * \param p_e an initialized exception pointer
359  * \return number of chapters in movie
360  */
361 VLC_PUBLIC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *, libvlc_exception_t *);
362
363 /**
364  * Will the player play
365  *
366  * \param p_mi the Media Player
367  * \param p_e an initialized exception pointer
368  * \return boolean
369  */
370 VLC_PUBLIC_API int libvlc_media_player_will_play        ( libvlc_media_player_t *, libvlc_exception_t *);
371
372 /**
373  * Get title chapter count
374  *
375  * \param p_mi the Media Player
376  * \param i_title title
377  * \param p_e an initialized exception pointer
378  * \return number of chapters in title
379  */
380 VLC_PUBLIC_API int libvlc_media_player_get_chapter_count_for_title(
381                        libvlc_media_player_t *, int, libvlc_exception_t *);
382
383 /**
384  * Set movie title
385  *
386  * \param p_mi the Media Player
387  * \param i_title title number to play
388  * \param p_e an initialized exception pointer
389  */
390 VLC_PUBLIC_API void libvlc_media_player_set_title( libvlc_media_player_t *, int, libvlc_exception_t *);
391
392 /**
393  * Get movie title
394  *
395  * \param p_mi the Media Player
396  * \param p_e an initialized exception pointer
397  * \return title number currently playing
398  */
399 VLC_PUBLIC_API int libvlc_media_player_get_title( libvlc_media_player_t *, libvlc_exception_t *);
400
401 /**
402  * Get movie title count
403  *
404  * \param p_mi the Media Player
405  * \param p_e an initialized exception pointer
406  * \return title number count
407  */
408 VLC_PUBLIC_API int libvlc_media_player_get_title_count( libvlc_media_player_t *, libvlc_exception_t *);
409
410 /**
411  * Set previous chapter
412  *
413  * \param p_mi the Media Player
414  * \param p_e an initialized exception pointer
415  */
416 VLC_PUBLIC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t *, libvlc_exception_t *);
417
418 /**
419  * Set next chapter
420  *
421  * \param p_mi the Media Player
422  * \param p_e an initialized exception pointer
423  */
424 VLC_PUBLIC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *, libvlc_exception_t *);
425
426 /**
427  * Get movie play rate
428  *
429  * \param p_mi the Media Player
430  * \param p_e an initialized exception pointer
431  * \return movie play rate
432  */
433 VLC_PUBLIC_API float libvlc_media_player_get_rate( libvlc_media_player_t *, libvlc_exception_t *);
434
435 /**
436  * Set movie play rate
437  *
438  * \param p_mi the Media Player
439  * \param movie play rate to set
440  * \param p_e an initialized exception pointer
441  */
442 VLC_PUBLIC_API void libvlc_media_player_set_rate( libvlc_media_player_t *, float, libvlc_exception_t *);
443
444 /**
445  * Get current movie state
446  *
447  * \param p_mi the Media Player
448  * \param p_e an initialized exception pointer
449  * \return current movie state as libvlc_state_t
450  */
451 VLC_PUBLIC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *, libvlc_exception_t *);
452
453 /**
454  * Get movie fps rate
455  *
456  * \param p_mi the Media Player
457  * \param p_e an initialized exception pointer
458  * \return frames per second (fps) for this playing movie
459  */
460 VLC_PUBLIC_API float libvlc_media_player_get_fps( libvlc_media_player_t *, libvlc_exception_t *);
461
462 /** end bug */
463
464 /**
465  * Does this media player have a video output?
466  *
467  * \param p_md the media player
468  * \param p_e an initialized exception pointer
469  */
470 VLC_PUBLIC_API int  libvlc_media_player_has_vout( libvlc_media_player_t *, libvlc_exception_t *);
471
472 /**
473  * Is this media player seekable?
474  *
475  * \param p_input the input
476  * \param p_e an initialized exception pointer
477  */
478 VLC_PUBLIC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi, libvlc_exception_t *p_e );
479
480 /**
481  * Can this media player be paused?
482  *
483  * \param p_input the input
484  * \param p_e an initialized exception pointer
485  */
486 VLC_PUBLIC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi, libvlc_exception_t *p_e );
487
488
489 /**
490  * Display the next frame
491  *
492  * \param p_input the libvlc_media_player_t instance
493  * \param p_e an initialized exception pointer
494  */
495 VLC_PUBLIC_API void    libvlc_media_player_next_frame( libvlc_media_player_t *p_input,
496                                                        libvlc_exception_t *p_e );
497
498
499
500 /**
501  * Release (free) libvlc_track_description_t
502  *
503  * \param p_track_description the structure to release
504  */
505 VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
506
507 /** \defgroup libvlc_video libvlc_video
508  * \ingroup libvlc_media_player
509  * LibVLC Video handling
510  * @{
511  */
512
513 /**
514  * Toggle fullscreen status on video output.
515  *
516  * \param p_mediaplayer the media player
517  * \param p_e an initialized exception pointer
518  */
519 VLC_PUBLIC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *, libvlc_exception_t * );
520
521 /**
522  * Enable or disable fullscreen on a video output.
523  *
524  * \param p_mediaplayer the media player
525  * \param b_fullscreen boolean for fullscreen status
526  * \param p_e an initialized exception pointer
527  */
528 VLC_PUBLIC_API void libvlc_set_fullscreen( libvlc_media_player_t *, int, libvlc_exception_t * );
529
530 /**
531  * Get current fullscreen status.
532  *
533  * \param p_mediaplayer the media player
534  * \param p_e an initialized exception pointer
535  * \return the fullscreen status (boolean)
536  */
537 VLC_PUBLIC_API int libvlc_get_fullscreen( libvlc_media_player_t *, libvlc_exception_t * );
538
539 /**
540  * Get current video height.
541  *
542  * \param p_mediaplayer the media player
543  * \param p_e an initialized exception pointer
544  * \return the video height
545  */
546 VLC_PUBLIC_API int libvlc_video_get_height( libvlc_media_player_t *, libvlc_exception_t * );
547
548 /**
549  * Get current video width.
550  *
551  * \param p_mediaplayer the media player
552  * \param p_e an initialized exception pointer
553  * \return the video width
554  */
555 VLC_PUBLIC_API int libvlc_video_get_width( libvlc_media_player_t *, libvlc_exception_t * );
556
557 /**
558  * Get the current video scaling factor.
559  * See also libvlc_video_set_scale().
560  *
561  * \param p_mediaplayer the media player
562  * \param p_e an initialized exception pointer
563  * \return the currently configured zoom factor, or 0. if the video is set
564  * to fit to the output window/drawable automatically.
565  */
566 VLC_PUBLIC_API float libvlc_video_get_scale( libvlc_media_player_t *,
567                                              libvlc_exception_t *p_e );
568
569 /**
570  * Set the video scaling factor. That is the ratio of the number of pixels on
571  * screen to the number of pixels in the original decoded video in each
572  * dimension. Zero is a special value; it will adjust the video to the output
573  * window/drawable (in windowed mode) or the entire screen.
574  *
575  * Note that not all video outputs support scaling.
576  *
577  * \param p_mediaplayer the media player
578  * \param i_factor the scaling factor, or zero
579  * \param p_e an initialized exception pointer
580  */
581 VLC_PUBLIC_API void libvlc_video_set_scale( libvlc_media_player_t *, float,
582                                             libvlc_exception_t *p_e );
583
584 /**
585  * Get current video aspect ratio.
586  *
587  * \param p_mediaplayer the media player
588  * \param p_e an initialized exception pointer
589  * \return the video aspect ratio
590  */
591 VLC_PUBLIC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *, libvlc_exception_t * );
592
593 /**
594  * Set new video aspect ratio.
595  *
596  * \param p_mediaplayer the media player
597  * \param psz_aspect new video aspect-ratio
598  * \param p_e an initialized exception pointer
599  */
600 VLC_PUBLIC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *, const char *, libvlc_exception_t * );
601
602 /**
603  * Get current video subtitle.
604  *
605  * \param p_mediaplayer the media player
606  * \param p_e an initialized exception pointer
607  * \return the video subtitle selected
608  */
609 VLC_PUBLIC_API int libvlc_video_get_spu( libvlc_media_player_t *, libvlc_exception_t * );
610
611 /**
612  * Get the number of available video subtitles.
613  *
614  * \param p_mediaplayer the media player
615  * \param p_e an initialized exception pointer
616  * \return the number of available video subtitles
617  */
618 VLC_PUBLIC_API int libvlc_video_get_spu_count( libvlc_media_player_t *, libvlc_exception_t * );
619
620 /**
621  * Get the description of available video subtitles.
622  *
623  * \param p_mediaplayer the media player
624  * \param p_e an initialized exception pointer
625  * \return list containing description of available video subtitles
626  */
627 VLC_PUBLIC_API libvlc_track_description_t *
628         libvlc_video_get_spu_description( libvlc_media_player_t *, libvlc_exception_t * );
629
630 /**
631  * Set new video subtitle.
632  *
633  * \param p_mediaplayer the media player
634  * \param i_spu new video subtitle to select
635  * \param p_e an initialized exception pointer
636  */
637 VLC_PUBLIC_API void libvlc_video_set_spu( libvlc_media_player_t *, int , libvlc_exception_t * );
638
639 /**
640  * Set new video subtitle file.
641  *
642  * \param p_mediaplayer the media player
643  * \param psz_subtitle new video subtitle file
644  * \param p_e an initialized exception pointer
645  * \return the success status (boolean)
646  */
647 VLC_PUBLIC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *, const char *, libvlc_exception_t * );
648
649 /**
650  * Get the description of available titles.
651  *
652  * \param p_mediaplayer the media player
653  * \param p_e an initialized exception pointer
654  * \return list containing description of available titles
655  */
656 VLC_PUBLIC_API libvlc_track_description_t *
657         libvlc_video_get_title_description( libvlc_media_player_t *, libvlc_exception_t * );
658
659 /**
660  * Get the description of available chapters for specific title.
661  *
662  * \param p_mediaplayer the media player
663  * \param i_title selected title
664  * \param p_e an initialized exception pointer
665  * \return list containing description of available chapter for title i_title
666  */
667 VLC_PUBLIC_API libvlc_track_description_t *
668         libvlc_video_get_chapter_description( libvlc_media_player_t *, int, libvlc_exception_t * );
669
670 /**
671  * Get current crop filter geometry.
672  *
673  * \param p_mediaplayer the media player
674  * \param p_e an initialized exception pointer
675  * \return the crop filter geometry
676  */
677 VLC_PUBLIC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *, libvlc_exception_t * );
678
679 /**
680  * Set new crop filter geometry.
681  *
682  * \param p_mediaplayer the media player
683  * \param psz_geometry new crop filter geometry
684  * \param p_e an initialized exception pointer
685  */
686 VLC_PUBLIC_API void libvlc_video_set_crop_geometry( libvlc_media_player_t *, const char *, libvlc_exception_t * );
687
688 /**
689  * Toggle teletext transparent status on video output.
690  *
691  * \param p_mediaplayer the media player
692  * \param p_e an initialized exception pointer
693  */
694 VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_player_t *, libvlc_exception_t * );
695
696 /**
697  * Get current teletext page requested.
698  *
699  * \param p_mediaplayer the media player
700  * \param p_e an initialized exception pointer
701  * \return the current teletext page requested.
702  */
703 VLC_PUBLIC_API int libvlc_video_get_teletext( libvlc_media_player_t *, libvlc_exception_t * );
704
705 /**
706  * Set new teletext page to retrieve.
707  *
708  * \param p_mediaplayer the media player
709  * \param i_page teletex page number requested
710  * \param p_e an initialized exception pointer
711  */
712 VLC_PUBLIC_API void libvlc_video_set_teletext( libvlc_media_player_t *, int, libvlc_exception_t * );
713
714 /**
715  * Get number of available video tracks.
716  *
717  * \param p_mi media player
718  * \param p_e an initialized exception
719  * \return the number of available video tracks (int)
720  */
721 VLC_PUBLIC_API int libvlc_video_get_track_count( libvlc_media_player_t *,  libvlc_exception_t * );
722
723 /**
724  * Get the description of available video tracks.
725  *
726  * \param p_mi media player
727  * \param p_e an initialized exception
728  * \return list with description of available video tracks
729  */
730 VLC_PUBLIC_API libvlc_track_description_t *
731         libvlc_video_get_track_description( libvlc_media_player_t *,  libvlc_exception_t * );
732
733 /**
734  * Get current video track.
735  *
736  * \param p_mi media player
737  * \param p_e an initialized exception pointer
738  * \return the video track (int)
739  */
740 VLC_PUBLIC_API int libvlc_video_get_track( libvlc_media_player_t *, libvlc_exception_t * );
741
742 /**
743  * Set video track.
744  *
745  * \param p_mi media player
746  * \param i_track the track (int)
747  * \param p_e an initialized exception pointer
748  */
749 VLC_PUBLIC_API void libvlc_video_set_track( libvlc_media_player_t *, int, libvlc_exception_t * );
750
751 /**
752  * Take a snapshot of the current video window.
753  *
754  * If i_width AND i_height is 0, original size is used.
755  * If i_width XOR i_height is 0, original aspect-ratio is preserved.
756  *
757  * \param p_mi media player instance
758  * \param psz_filepath the path where to save the screenshot to
759  * \param i_width the snapshot's width
760  * \param i_height the snapshot's height
761  * \param p_e an initialized exception pointer
762  */
763 VLC_PUBLIC_API void libvlc_video_take_snapshot( libvlc_media_player_t *, const char *,unsigned int, unsigned int, libvlc_exception_t * );
764
765 /**
766  * Enable or disable deinterlace filter
767  *
768  * \param p_mi libvlc media player
769  * \param b_enable boolean to enable or disable deinterlace filter
770  * \param psz_mode type of deinterlace filter to use
771  * \param p_e an initialized exception pointer
772  */
773 VLC_PUBLIC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *,
774                                                   int , const char *,
775                                                   libvlc_exception_t *);
776
777 /**
778  * Get an option value (option which return an int)
779  *
780  * \param p_mi libvlc media player
781  * \param option marq option to get
782  * \param p_e an initialized exception pointer
783  */
784 VLC_PUBLIC_API int libvlc_video_get_marquee_option_as_int( libvlc_media_player_t *,
785                                                         libvlc_video_marquee_int_option_t,
786                                                         libvlc_exception_t * );
787
788 /**
789  * Get an option value (option which return a string)
790  *
791  * \param p_mi libvlc media player
792  * \param option marq option to get
793  * \param p_e an initialized exception pointer
794  */
795 VLC_PUBLIC_API char *libvlc_video_get_marquee_option_as_string( libvlc_media_player_t *,
796                                                              libvlc_video_marquee_string_option_t,
797                                                              libvlc_exception_t * );
798
799 /**
800  * Enable, disable or set a marq option (only int)
801  *
802  * \param p_mi libvlc media player
803  * \param option marq option to set
804  * \param i_val marq option value
805  * \param p_e an initialized exception pointer
806  */
807 VLC_PUBLIC_API void libvlc_video_set_marquee_option_as_int( libvlc_media_player_t *,
808                                                          libvlc_video_marquee_int_option_t,
809                                                          int, libvlc_exception_t * );
810
811 /**
812  * Set a marq option (only string)
813  *
814  * \param p_mi libvlc media player
815  * \param option marq option to set
816  * \param psz_text marq option value
817  * \param p_e an initialized exception pointer
818  */
819 VLC_PUBLIC_API void libvlc_video_set_marquee_option_as_string( libvlc_media_player_t *,
820                                                             libvlc_video_marquee_string_option_t,
821                                                             const char *,
822                                                             libvlc_exception_t * );
823
824 /** @} video */
825
826 /** \defgroup libvlc_audio libvlc_audio
827  * \ingroup libvlc_media_player
828  * LibVLC Audio handling
829  * @{
830  */
831
832 /**
833  * Audio device types
834  */
835 typedef enum libvlc_audio_output_device_types_t {
836     libvlc_AudioOutputDevice_Error  = -1,
837     libvlc_AudioOutputDevice_Mono   =  1,
838     libvlc_AudioOutputDevice_Stereo =  2,
839     libvlc_AudioOutputDevice_2F2R   =  4,
840     libvlc_AudioOutputDevice_3F2R   =  5,
841     libvlc_AudioOutputDevice_5_1    =  6,
842     libvlc_AudioOutputDevice_6_1    =  7,
843     libvlc_AudioOutputDevice_7_1    =  8,
844     libvlc_AudioOutputDevice_SPDIF  = 10
845 } libvlc_audio_output_device_types_t;
846
847 /**
848  * Audio channels
849  */
850 typedef enum libvlc_audio_output_channel_t {
851     libvlc_AudioChannel_Error   = -1,
852     libvlc_AudioChannel_Stereo  =  1,
853     libvlc_AudioChannel_RStereo =  2,
854     libvlc_AudioChannel_Left    =  3,
855     libvlc_AudioChannel_Right   =  4,
856     libvlc_AudioChannel_Dolbys  =  5
857 } libvlc_audio_output_channel_t;
858
859
860 /**
861  * Get the list of available audio outputs
862  *
863  * \param p_instance libvlc instance
864  * \param p_e an initialized exception pointer
865  * \return list of available audio outputs, at the end free it with
866 *          \see libvlc_audio_output_list_release \see libvlc_audio_output_t
867  */
868 VLC_PUBLIC_API libvlc_audio_output_t *
869         libvlc_audio_output_list_get( libvlc_instance_t *,
870                                       libvlc_exception_t * );
871
872 /**
873  * Free the list of available audio outputs
874  *
875  * \param p_list list with audio outputs for release
876  */
877 VLC_PUBLIC_API void libvlc_audio_output_list_release( libvlc_audio_output_t * );
878
879 /**
880  * Set the audio output.
881  * Change will be applied after stop and play.
882  *
883  * \param p_instance libvlc instance
884  * \param psz_name name of audio output,
885  *               use psz_name of \see libvlc_audio_output_t
886  * \return true if function succeded
887  */
888 VLC_PUBLIC_API int libvlc_audio_output_set( libvlc_instance_t *,
889                                             const char * );
890
891 /**
892  * Get count of devices for audio output, these devices are hardware oriented
893  * like analor or digital output of sound card
894  *
895  * \param p_instance libvlc instance
896  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
897  * \return number of devices
898  */
899 VLC_PUBLIC_API int libvlc_audio_output_device_count( libvlc_instance_t *,
900                                                      const char * );
901
902 /**
903  * Get long name of device, if not available short name given
904  *
905  * \param p_instance libvlc instance
906  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
907  * \param i_device device index
908  * \return long name of device
909  */
910 VLC_PUBLIC_API char * libvlc_audio_output_device_longname( libvlc_instance_t *,
911                                                            const char *,
912                                                            int );
913
914 /**
915  * Get id name of device
916  *
917  * \param p_instance libvlc instance
918  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
919  * \param i_device device index
920  * \return id name of device, use for setting device, need to be free after use
921  */
922 VLC_PUBLIC_API char * libvlc_audio_output_device_id( libvlc_instance_t *,
923                                                      const char *,
924                                                      int );
925
926 /**
927  * Set device for using
928  *
929  * \param p_instance libvlc instance
930  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
931  * \param psz_device_id device
932  */
933 VLC_PUBLIC_API void libvlc_audio_output_device_set( libvlc_instance_t *,
934                                                     const char *,
935                                                     const char * );
936
937 /**
938  * Get current audio device type. Device type describes something like
939  * character of output sound - stereo sound, 2.1, 5.1 etc
940  *
941  * \param p_instance vlc instance
942  * \param p_e an initialized exception pointer
943  * \return the audio devices type \see libvlc_audio_output_device_types_t
944  */
945 VLC_PUBLIC_API int libvlc_audio_output_get_device_type(
946         libvlc_instance_t *, libvlc_exception_t * );
947
948 /**
949  * Set current audio device type.
950  *
951  * \param p_instance vlc instance
952  * \param device_type the audio device type,
953           according to \see libvlc_audio_output_device_types_t
954  * \param p_e an initialized exception pointer
955  */
956 VLC_PUBLIC_API void libvlc_audio_output_set_device_type( libvlc_instance_t *,
957                                                          int,
958                                                          libvlc_exception_t * );
959
960
961 /**
962  * Toggle mute status.
963  *
964  * \param p_instance libvlc instance
965  */
966 VLC_PUBLIC_API void libvlc_audio_toggle_mute( libvlc_instance_t * );
967
968 /**
969  * Get current mute status.
970  *
971  * \param p_instance libvlc instance
972  * \return the mute status (boolean)
973  */
974 VLC_PUBLIC_API int libvlc_audio_get_mute( libvlc_instance_t * );
975
976 /**
977  * Set mute status.
978  *
979  * \param p_instance libvlc instance
980  * \param status If status is true then mute, otherwise unmute
981  */
982 VLC_PUBLIC_API void libvlc_audio_set_mute( libvlc_instance_t *, int );
983
984 /**
985  * Get current audio level.
986  *
987  * \param p_instance libvlc instance
988  * \param p_e an initialized exception pointer
989  * \return the audio level (int)
990  */
991 VLC_PUBLIC_API int libvlc_audio_get_volume( libvlc_instance_t * );
992
993 /**
994  * Set current audio level.
995  *
996  * \param p_instance libvlc instance
997  * \param i_volume the volume (int)
998  * \param p_e an initialized exception pointer
999  */
1000 VLC_PUBLIC_API void libvlc_audio_set_volume( libvlc_instance_t *, int, libvlc_exception_t *);
1001
1002 /**
1003  * Get number of available audio tracks.
1004  *
1005  * \param p_mi media player
1006  * \param p_e an initialized exception
1007  * \return the number of available audio tracks (int)
1008  */
1009 VLC_PUBLIC_API int libvlc_audio_get_track_count( libvlc_media_player_t *,  libvlc_exception_t * );
1010
1011 /**
1012  * Get the description of available audio tracks.
1013  *
1014  * \param p_mi media player
1015  * \param p_e an initialized exception
1016  * \return list with description of available audio tracks
1017  */
1018 VLC_PUBLIC_API libvlc_track_description_t *
1019         libvlc_audio_get_track_description( libvlc_media_player_t *,  libvlc_exception_t * );
1020
1021 /**
1022  * Get current audio track.
1023  *
1024  * \param p_mi media player
1025  * \param p_e an initialized exception pointer
1026  * \return the audio track (int)
1027  */
1028 VLC_PUBLIC_API int libvlc_audio_get_track( libvlc_media_player_t *, libvlc_exception_t * );
1029
1030 /**
1031  * Set current audio track.
1032  *
1033  * \param p_mi media player
1034  * \param i_track the track (int)
1035  * \param p_e an initialized exception pointer
1036  */
1037 VLC_PUBLIC_API void libvlc_audio_set_track( libvlc_media_player_t *, int, libvlc_exception_t * );
1038
1039 /**
1040  * Get current audio channel.
1041  *
1042  * \param p_instance vlc instance
1043  * \param p_e an initialized exception pointer
1044  * \return the audio channel \see libvlc_audio_output_channel_t
1045  */
1046 VLC_PUBLIC_API int
1047     libvlc_audio_get_channel( libvlc_instance_t *, libvlc_exception_t * );
1048
1049 /**
1050  * Set current audio channel.
1051  *
1052  * \param p_instance vlc instance
1053  * \param channel the audio channel, \see libvlc_audio_output_channel_t
1054  * \param p_e an initialized exception pointer
1055  */
1056 VLC_PUBLIC_API void libvlc_audio_set_channel( libvlc_instance_t *,
1057                                               int,
1058                                               libvlc_exception_t * );
1059
1060 /** @} audio */
1061
1062 /** @} media_player */
1063
1064 #endif /* VLC_LIBVLC_MEDIA_PLAYER_H */