libvlc_media_player.h 33 KB
Newer Older
1
2
3
/*****************************************************************************
 * libvlc_media_player.h:  libvlc_media_player external API
 *****************************************************************************
4
 * Copyright (C) 1998-2010 the VideoLAN team
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 * $Id$
 *
 * Authors: Clément Stenac <zorglub@videolan.org>
 *          Jean-Paul Saman <jpsaman@videolan.org>
 *          Pierre d'Herbemont <pdherbemont@videolan.org>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
 *****************************************************************************/

/**
 * \file
 * This file defines libvlc_media_player external API
 */

#ifndef VLC_LIBVLC_MEDIA_PLAYER_H
#define VLC_LIBVLC_MEDIA_PLAYER_H 1

ivoire's avatar
ivoire committed
34
35
36
37
# ifdef __cplusplus
extern "C" {
# endif

38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
/*****************************************************************************
 * Media Player
 *****************************************************************************/
/** \defgroup libvlc_media_player libvlc_media_player
 * \ingroup libvlc
 * LibVLC Media Player, object that let you play a media
 * in a custom drawable
 * @{
 */

typedef struct libvlc_media_player_t libvlc_media_player_t;

/**
 * Description for video, audio tracks and subtitles. It contains
 * id, name (description string) and pointer to next record.
 */
typedef struct libvlc_track_description_t
{
    int   i_id;
    char *psz_name;
    struct libvlc_track_description_t *p_next;
59

60
61
62
63
64
65
66
67
68
69
70
} libvlc_track_description_t;

/**
 * Description for audio output. It contains
 * name, description and pointer to next record.
 */
typedef struct libvlc_audio_output_t
{
    char *psz_name;
    char *psz_description;
    struct libvlc_audio_output_t *p_next;
71

72
73
74
75
76
77
78
79
80
81
82
} libvlc_audio_output_t;

/**
 * Rectangle type for video geometry
 */
typedef struct libvlc_rectangle_t
{
    int top, left;
    int bottom, right;
} libvlc_rectangle_t;

83
/**
84
 * Marq options definition
85
 */
86
typedef enum libvlc_video_marquee_option_t {
87
    libvlc_marquee_Enable = 0,
88
    libvlc_marquee_Text,		/** string argument */
89
90
91
92
93
94
95
    libvlc_marquee_Color,
    libvlc_marquee_Opacity,
    libvlc_marquee_Position,
    libvlc_marquee_Refresh,
    libvlc_marquee_Size,
    libvlc_marquee_Timeout,
    libvlc_marquee_X,
96
    libvlc_marquee_Y
97
} libvlc_video_marquee_option_t;
98
99
100
101
102
103

/**
 * Create an empty Media Player object
 *
 * \param p_libvlc_instance the libvlc instance in which the Media Player
 *        should be created.
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
104
 * \return a new media player object, or NULL on error.
105
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
106
VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t * );
107
108
109
110
111
112

/**
 * Create a Media Player object from a Media
 *
 * \param p_md the media. Afterwards the p_md can be safely
 *        destroyed.
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
113
 * \return a new media player object, or NULL on error.
114
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
115
VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t * );
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

/**
 * Release a media_player after use
 * Decrement the reference count of a media player object. If the
 * reference count is 0, then libvlc_media_player_release() will
 * release the media player object. If the media player object
 * has been released, then it should not be used again.
 *
 * \param p_mi the Media Player to free
 */
VLC_PUBLIC_API void libvlc_media_player_release( libvlc_media_player_t * );

/**
 * Retain a reference to a media player object. Use
 * libvlc_media_player_release() to decrement reference count.
 *
 * \param p_mi media player object
 */
VLC_PUBLIC_API void libvlc_media_player_retain( libvlc_media_player_t * );

/**
 * Set the media that will be used by the media_player. If any,
 * previous md will be released.
 *
 * \param p_mi the Media Player
 * \param p_md the Media. Afterwards the p_md can be safely
 *        destroyed.
 */
144
VLC_PUBLIC_API void libvlc_media_player_set_media( libvlc_media_player_t *, libvlc_media_t * );
145
146
147
148
149
150
151
152

/**
 * Get the media used by the media_player.
 *
 * \param p_mi the Media Player
 * \return the media associated with p_mi, or NULL if no
 *         media is associated
 */
153
VLC_PUBLIC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t * );
154
155
156
157
158
159
160

/**
 * Get the Event Manager from which the media player send event.
 *
 * \param p_mi the Media Player
 * \return the event manager associated with p_mi
 */
161
VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t * );
162
163
164
165
166
167
168

/**
 * is_playing
 *
 * \param p_mi the Media Player
 * \return 1 if the media player is playing, 0 otherwise
 */
169
VLC_PUBLIC_API int libvlc_media_player_is_playing ( libvlc_media_player_t * );
170
171
172
173
174

/**
 * Play
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
175
 * \return 0 if playback started (and was already started), or -1 on error.
176
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
177
VLC_PUBLIC_API int libvlc_media_player_play ( libvlc_media_player_t * );
178
179

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
180
 * Toggle pause (no effect if there is no media)
181
182
183
 *
 * \param p_mi the Media Player
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
184
VLC_PUBLIC_API void libvlc_media_player_pause ( libvlc_media_player_t * );
185
186

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
187
 * Stop (no effect if there is no media)
188
189
190
 *
 * \param p_mi the Media Player
 */
191
VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t * );
192
193

/**
194
195
196
197
 * Set the NSView handler where the media player should render its video output.
 *
 * The object minimal_macosx expects is of kind NSObject and should
 * respect the protocol:
198
 *
199
 * @protocol VLCOpenGLVideoViewEmbedding <NSObject>
200
201
202
 * - (void)addVoutSubview:(NSView *)view;
 * - (void)removeVoutSubview:(NSView *)view;
 * @end
203
 *
204
 * You can find a live example in VLCVideoView in VLCKit.framework.
205
 *
206
 * \param p_mi the Media Player
207
 * \param drawable the NSView handler
208
 */
209
VLC_PUBLIC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable );
210
211

/**
212
 * Get the NSView handler previously set with libvlc_media_player_set_nsobject().
213
 *
214
 * \param p_mi the Media Player
215
 * \return the NSView handler or 0 if none where set
216
 */
Pierre's avatar
Pierre committed
217
VLC_PUBLIC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi );
218

219
220
221
222
223
224
/**
 * Set the agl handler where the media player should render its video output.
 *
 * \param p_mi the Media Player
 * \param drawable the agl handler
 */
225
VLC_PUBLIC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable );
226
227
228
229

/**
 * Get the agl handler previously set with libvlc_media_player_set_agl().
 *
230
 * \param p_mi the Media Player
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 * \return the agl handler or 0 if none where set
 */
VLC_PUBLIC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_mi );

/**
 * Set an X Window System drawable where the media player should render its
 * video output. If LibVLC was built without X11 output support, then this has
 * no effects.
 *
 * The specified identifier must correspond to an existing Input/Output class
 * X11 window. Pixmaps are <b>not</b> supported. The caller shall ensure that
 * the X11 server is the same as the one the VLC instance has been configured
 * with.
 * If XVideo is <b>not</b> used, it is assumed that the drawable has the
 * following properties in common with the default X11 screen: depth, scan line
 * pad, black pixel. This is a bug.
 *
 * \param p_mi the Media Player
 * \param drawable the ID of the X window
 */
251
VLC_PUBLIC_API void libvlc_media_player_set_xwindow ( libvlc_media_player_t *p_mi, uint32_t drawable );
252
253
254
255
256
257
258

/**
 * Get the X Window System window identifier previously set with
 * libvlc_media_player_set_xwindow(). Note that this will return the identifier
 * even if VLC is not currently using it (for instance if it is playing an
 * audio-only input).
 *
259
 * \param p_mi the Media Player
260
261
262
263
264
265
266
267
268
269
270
271
 * \return an X window ID, or 0 if none where set.
 */
VLC_PUBLIC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi );

/**
 * Set a Win32/Win64 API window handle (HWND) where the media player should
 * render its video output. If LibVLC was built without Win32/Win64 API output
 * support, then this has no effects.
 *
 * \param p_mi the Media Player
 * \param drawable windows handle of the drawable
 */
272
VLC_PUBLIC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable );
273
274
275
276
277
278

/**
 * Get the Windows API window handle (HWND) previously set with
 * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC
 * is not currently outputting any video to it.
 *
279
 * \param p_mi the Media Player
280
281
282
283
284
285
286
287
288
289
290
291
 * \return a window handle or NULL if there are none.
 */
VLC_PUBLIC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );



/** \bug This might go away ... to be replaced by a broader system */

/**
 * Get the current movie length (in ms).
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
292
 * \return the movie length (in ms), or -1 if there is no media.
293
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
294
VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t * );
295
296
297
298
299

/**
 * Get the current movie time (in ms).
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
300
 * \return the movie time (in ms), or -1 if there is no media.
301
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
302
VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t * );
303
304

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
305
306
 * Set the movie time (in ms). This has no effect if no media is being played.
 * Not all formats and protocols support this.
307
308
309
310
 *
 * \param p_mi the Media Player
 * \param the movie time (in ms).
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
311
VLC_PUBLIC_API void libvlc_media_player_set_time( libvlc_media_player_t *, libvlc_time_t );
312
313
314
315
316

/**
 * Get movie position.
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
317
 * \return movie position, or -1. in case of error
318
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
319
VLC_PUBLIC_API float libvlc_media_player_get_position( libvlc_media_player_t * );
320
321

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
322
323
 * Set movie position. This has no effect if playback is not enabled.
 * This might not work depending on the underlying input format and protocol.
324
325
 *
 * \param p_mi the Media Player
Olivier Aubert's avatar
Olivier Aubert committed
326
 * \param f_pos the position
327
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
328
VLC_PUBLIC_API void libvlc_media_player_set_position( libvlc_media_player_t *, float );
329
330

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
331
 * Set movie chapter (if applicable).
332
333
334
335
 *
 * \param p_mi the Media Player
 * \param i_chapter chapter number to play
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
336
VLC_PUBLIC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *, int );
337
338

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
339
 * Get movie chapter.
340
341
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
342
 * \return chapter number currently playing, or -1 if there is no media.
343
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
344
VLC_PUBLIC_API int libvlc_media_player_get_chapter( libvlc_media_player_t * );
345
346
347
348
349

/**
 * Get movie chapter count
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
350
 * \return number of chapters in movie, or -1.
351
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
352
VLC_PUBLIC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t * );
353
354

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
355
 * Is the player able to play
356
357
358
359
 *
 * \param p_mi the Media Player
 * \return boolean
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
360
VLC_PUBLIC_API int libvlc_media_player_will_play( libvlc_media_player_t * );
361
362
363
364
365
366

/**
 * Get title chapter count
 *
 * \param p_mi the Media Player
 * \param i_title title
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
367
 * \return number of chapters in title, or -1
368
369
 */
VLC_PUBLIC_API int libvlc_media_player_get_chapter_count_for_title(
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
370
                       libvlc_media_player_t *, int );
371
372
373
374
375
376
377

/**
 * Set movie title
 *
 * \param p_mi the Media Player
 * \param i_title title number to play
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
378
VLC_PUBLIC_API void libvlc_media_player_set_title( libvlc_media_player_t *, int );
379
380
381
382
383

/**
 * Get movie title
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
384
 * \return title number currently playing, or -1
385
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
386
VLC_PUBLIC_API int libvlc_media_player_get_title( libvlc_media_player_t * );
387
388
389
390
391

/**
 * Get movie title count
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
392
 * \return title number count, or -1
393
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
394
VLC_PUBLIC_API int libvlc_media_player_get_title_count( libvlc_media_player_t * );
395
396

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
397
 * Set previous chapter (if applicable)
398
399
400
 *
 * \param p_mi the Media Player
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
401
VLC_PUBLIC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t * );
402
403

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
404
 * Set next chapter (if applicable)
405
406
407
 *
 * \param p_mi the Media Player
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
408
VLC_PUBLIC_API void libvlc_media_player_next_chapter( libvlc_media_player_t * );
409
410
411
412
413

/**
 * Get movie play rate
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
414
 * \return movie play rate, or zero in case of error
415
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
416
VLC_PUBLIC_API float libvlc_media_player_get_rate( libvlc_media_player_t * );
417
418
419
420
421
422

/**
 * Set movie play rate
 *
 * \param p_mi the Media Player
 * \param movie play rate to set
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
423
424
 * \return -1 if an error was detected, 0 otherwise (but even then, it might
 * not actually work depending on the underlying media protocol)
425
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
426
VLC_PUBLIC_API int libvlc_media_player_set_rate( libvlc_media_player_t *, float );
427
428
429
430
431
432

/**
 * Get current movie state
 *
 * \param p_mi the Media Player
 */
433
VLC_PUBLIC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *);
434
435
436
437
438

/**
 * Get movie fps rate
 *
 * \param p_mi the Media Player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
439
 * \return frames per second (fps) for this playing movie, or 0 if unspecified
440
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
441
VLC_PUBLIC_API float libvlc_media_player_get_fps( libvlc_media_player_t * );
442
443
444
445

/** end bug */

/**
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
446
 * How many video outputs does this media player have?
447
448
 *
 * \param p_md the media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
449
 * \return the number of video outputs
450
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
451
VLC_PUBLIC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t * );
452
453
454
455
456
457

/**
 * Is this media player seekable?
 *
 * \param p_input the input
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
458
VLC_PUBLIC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi );
459
460
461
462
463
464

/**
 * Can this media player be paused?
 *
 * \param p_input the input
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
465
VLC_PUBLIC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi );
466

467
468

/**
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
469
 * Display the next frame (if supported)
470
471
472
 *
 * \param p_input the libvlc_media_player_t instance
 */
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
473
VLC_PUBLIC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_input );
474
475
476



477
478
479
480
481
482
483
484
485
486
487
488
489
490
/**
 * Release (free) libvlc_track_description_t
 *
 * \param p_track_description the structure to release
 */
VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description );

/** \defgroup libvlc_video libvlc_video
 * \ingroup libvlc_media_player
 * LibVLC Video handling
 * @{
 */

/**
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
491
 * Toggle fullscreen status on non-embedded video outputs.
492
493
494
 *
 * @warning The same limitations applies to this function
 * as to libvlc_set_fullscreen().
495
496
497
 *
 * \param p_mediaplayer the media player
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
498
VLC_PUBLIC_API void libvlc_toggle_fullscreen( libvlc_media_player_t * );
499
500

/**
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
501
 * Enable or disable fullscreen on non-embedded video outputs.
502
503
504
505
506
507
508
509
 *
 * @warning With most window managers, only a top-level windows can switch to
 * full-screen mode. Hence, this function will not operate properly if
 * libvlc_media_player_set_xid() or libvlc_media_player_set_hwnd() was
 * used to embed the video in a non-LibVLC widget. If you want to to render an
 * embedded LibVLC video full-screen, the parent embedding widget must expanded
 * to full screen (LibVLC cannot take care of that).
 * LibVLC will then automatically resize the video as appropriate.
510
511
512
513
 *
 * \param p_mediaplayer the media player
 * \param b_fullscreen boolean for fullscreen status
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
514
VLC_PUBLIC_API void libvlc_set_fullscreen( libvlc_media_player_t *, int );
515
516
517
518
519
520
521

/**
 * Get current fullscreen status.
 *
 * \param p_mediaplayer the media player
 * \return the fullscreen status (boolean)
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
522
VLC_PUBLIC_API int libvlc_get_fullscreen( libvlc_media_player_t * );
523

524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
/**
 * Enable or disable key press events handling, according to the LibVLC hotkeys
 * configuration. By default and for historical reasons, keyboard events are
 * handled by the LibVLC video widget.
 *
 * \note On X11, there can be only one subscriber for key press and mouse
 * click events per window. If your application has subscribed to those events
 * for the X window ID of the video widget, then LibVLC will not be able to
 * handle key presses and mouse clicks in any case.
 *
 * \warning This function is only implemented for X11 at the moment.
 *
 * \param mp the media player
 * \param on true to handle key press events, false to ignore them.
 */
VLC_PUBLIC_API
void libvlc_video_set_key_input( libvlc_media_player_t *mp, unsigned on );

/**
 * Enable or disable mouse click events handling. By default, those events are
 * handled. This is needed for DVD menus to work, as well as a few video
 * filters such as "puzzle".
 *
 * \note See also \func libvlc_video_set_key_input().
 *
 * \warning This function is only implemented for X11 at the moment.
 *
 * \param mp the media player
 * \param on true to handle mouse click events, false to ignore them.
 */
VLC_PUBLIC_API
void libvlc_video_set_mouse_input( libvlc_media_player_t *mp, unsigned on );

Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
557
558
559
560
561
562
563
564
565
566
567
568
569
/**
 * Get the pixel dimensions of a video.
 *
 * \param mp media player
 * \param num number of the video (starting from, and most commonly 0)
 * \param px pointer to get the pixel width [OUT]
 * \param py pointer to get the pixel height [OUT]
 * \return 0 on success, -1 if the specified video does not exist
 */
VLC_PUBLIC_API
int libvlc_video_get_size( libvlc_media_player_t *mp, unsigned num,
                           unsigned *px, unsigned *py );

570
571
/**
 * Get current video height.
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
572
 * You should use libvlc_video_get_size() instead.
573
574
 *
 * \param p_mediaplayer the media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
575
 * \return the video pixel height or 0 if not applicable
576
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
577
578
VLC_DEPRECATED_API
int libvlc_video_get_height( libvlc_media_player_t * );
579
580
581

/**
 * Get current video width.
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
582
 * You should use libvlc_video_get_size() instead.
583
584
 *
 * \param p_mediaplayer the media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
585
 * \return the video pixel width or 0 if not applicable
586
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
587
588
VLC_DEPRECATED_API
int libvlc_video_get_width( libvlc_media_player_t * );
589
590
591
592
593
594
595
596
597

/**
 * Get the current video scaling factor.
 * See also libvlc_video_set_scale().
 *
 * \param p_mediaplayer the media player
 * \return the currently configured zoom factor, or 0. if the video is set
 * to fit to the output window/drawable automatically.
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
598
VLC_PUBLIC_API float libvlc_video_get_scale( libvlc_media_player_t * );
599
600
601
602
603
604
605
606
607
608
609
610

/**
 * Set the video scaling factor. That is the ratio of the number of pixels on
 * screen to the number of pixels in the original decoded video in each
 * dimension. Zero is a special value; it will adjust the video to the output
 * window/drawable (in windowed mode) or the entire screen.
 *
 * Note that not all video outputs support scaling.
 *
 * \param p_mediaplayer the media player
 * \param i_factor the scaling factor, or zero
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
611
VLC_PUBLIC_API void libvlc_video_set_scale( libvlc_media_player_t *, float );
612
613
614
615
616

/**
 * Get current video aspect ratio.
 *
 * \param p_mediaplayer the media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
617
618
 * \return the video aspect ratio or NULL if unspecified
 * (the result must be released with free() or libvlc_free()).
619
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
620
VLC_PUBLIC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t * );
621
622
623
624
625

/**
 * Set new video aspect ratio.
 *
 * \param p_mediaplayer the media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
626
627
 * \param psz_aspect new video aspect-ratio or NULL to reset to default
 * \note Invalid aspect ratios are ignored.
628
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
629
VLC_PUBLIC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *, const char * );
630
631
632
633
634

/**
 * Get current video subtitle.
 *
 * \param p_mediaplayer the media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
635
 * \return the video subtitle selected, or -1 if none
636
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
637
VLC_PUBLIC_API int libvlc_video_get_spu( libvlc_media_player_t * );
638
639
640
641
642
643
644

/**
 * Get the number of available video subtitles.
 *
 * \param p_mediaplayer the media player
 * \return the number of available video subtitles
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
645
VLC_PUBLIC_API int libvlc_video_get_spu_count( libvlc_media_player_t * );
646
647
648
649
650
651
652
653

/**
 * Get the description of available video subtitles.
 *
 * \param p_mediaplayer the media player
 * \return list containing description of available video subtitles
 */
VLC_PUBLIC_API libvlc_track_description_t *
654
        libvlc_video_get_spu_description( libvlc_media_player_t * );
655
656
657
658
659
660

/**
 * Set new video subtitle.
 *
 * \param p_mediaplayer the media player
 * \param i_spu new video subtitle to select
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
661
 * \return 0 on success, -1 if out of range
662
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
663
VLC_PUBLIC_API int libvlc_video_set_spu( libvlc_media_player_t *, unsigned );
664
665
666
667
668
669
670
671

/**
 * Set new video subtitle file.
 *
 * \param p_mediaplayer the media player
 * \param psz_subtitle new video subtitle file
 * \return the success status (boolean)
 */
672
VLC_PUBLIC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *, const char * );
673
674
675
676
677
678
679
680

/**
 * Get the description of available titles.
 *
 * \param p_mediaplayer the media player
 * \return list containing description of available titles
 */
VLC_PUBLIC_API libvlc_track_description_t *
681
        libvlc_video_get_title_description( libvlc_media_player_t * );
682
683
684
685
686
687
688
689
690

/**
 * Get the description of available chapters for specific title.
 *
 * \param p_mediaplayer the media player
 * \param i_title selected title
 * \return list containing description of available chapter for title i_title
 */
VLC_PUBLIC_API libvlc_track_description_t *
691
        libvlc_video_get_chapter_description( libvlc_media_player_t *, int );
692
693
694
695
696

/**
 * Get current crop filter geometry.
 *
 * \param p_mediaplayer the media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
697
 * \return the crop filter geometry or NULL if unset
698
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
699
VLC_PUBLIC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t * );
700
701
702
703
704

/**
 * Set new crop filter geometry.
 *
 * \param p_mediaplayer the media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
705
 * \param psz_geometry new crop filter geometry (NULL to unset)
706
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
707
708
VLC_PUBLIC_API
void libvlc_video_set_crop_geometry( libvlc_media_player_t *, const char * );
709

710
711
712
713
714
715
716
717
718
719
720
721
722
723
/**
 * Get current teletext page requested.
 *
 * \param p_mediaplayer the media player
 * \return the current teletext page requested.
 */
VLC_PUBLIC_API int libvlc_video_get_teletext( libvlc_media_player_t * );

/**
 * Set new teletext page to retrieve.
 *
 * \param p_mediaplayer the media player
 * \param i_page teletex page number requested
 */
724
VLC_PUBLIC_API void libvlc_video_set_teletext( libvlc_media_player_t *, int );
725

726
727
728
729
730
/**
 * Toggle teletext transparent status on video output.
 *
 * \param p_mediaplayer the media player
 */
731
VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_player_t * );
732
733
734
735
736
737
738

/**
 * Get number of available video tracks.
 *
 * \param p_mi media player
 * \return the number of available video tracks (int)
 */
739
VLC_PUBLIC_API int libvlc_video_get_track_count( libvlc_media_player_t * );
740
741
742
743
744

/**
 * Get the description of available video tracks.
 *
 * \param p_mi media player
Rémi Denis-Courmont's avatar
good    
Rémi Denis-Courmont committed
745
 * \return list with description of available video tracks, or NULL on error
746
747
 */
VLC_PUBLIC_API libvlc_track_description_t *
748
        libvlc_video_get_track_description( libvlc_media_player_t * );
749
750
751
752
753

/**
 * Get current video track.
 *
 * \param p_mi media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
754
 * \return the video track (int) or -1 if none
755
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
756
VLC_PUBLIC_API int libvlc_video_get_track( libvlc_media_player_t * );
757
758
759
760
761
762

/**
 * Set video track.
 *
 * \param p_mi media player
 * \param i_track the track (int)
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
763
 * \return 0 on success, -1 if out of range
764
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
765
766
VLC_PUBLIC_API
int libvlc_video_set_track( libvlc_media_player_t *, int );
767
768
769
770
771
772
773
774

/**
 * Take a snapshot of the current video window.
 *
 * If i_width AND i_height is 0, original size is used.
 * If i_width XOR i_height is 0, original aspect-ratio is preserved.
 *
 * \param p_mi media player instance
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
775
 * \param num number of video output (typically 0 for the first/only one)
776
777
778
 * \param psz_filepath the path where to save the screenshot to
 * \param i_width the snapshot's width
 * \param i_height the snapshot's height
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
779
 * \return 0 on success, -1 if the video was not found
780
 */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
781
782
783
VLC_PUBLIC_API
int libvlc_video_take_snapshot( libvlc_media_player_t *, unsigned num,
                                const char *,unsigned int, unsigned int );
784

785
786
787
788
/**
 * Enable or disable deinterlace filter
 *
 * \param p_mi libvlc media player
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
789
 * \param psz_mode type of deinterlace filter, NULL to disable
790
791
 */
VLC_PUBLIC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *,
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
792
                                                  const char * );
793

794
/**
795
 * Get an integer marquee option value
796
797
 *
 * \param p_mi libvlc media player
798
 * \param option marq option to get \see libvlc_video_marquee_int_option_t
799
 */
800
VLC_PUBLIC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *,
801
                                                 unsigned );
802
803

/**
804
 * Get a string marquee option value
805
806
 *
 * \param p_mi libvlc media player
807
 * \param option marq option to get \see libvlc_video_marquee_string_option_t
808
 */
809
VLC_PUBLIC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *,
810
                                                      unsigned );
811
812

/**
813
 * Enable, disable or set an integer marquee option
814
815
816
 *
 * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
 * or disabling (arg 0) the marq filter.
817
818
 *
 * \param p_mi libvlc media player
819
 * \param option marq option to set \see libvlc_video_marquee_int_option_t
820
821
 * \param i_val marq option value
 */
822
VLC_PUBLIC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *,
823
                                                  unsigned, int );
824
825

/**
826
 * Set a marquee string option
827
828
 *
 * \param p_mi libvlc media player
829
 * \param option marq option to set \see libvlc_video_marquee_string_option_t
830
831
 * \param psz_text marq option value
 */
832
VLC_PUBLIC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *,
833
                                                     unsigned, const char * );
834

835
/** option values for libvlc_video_{get,set}_logo_{int,string} */
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
enum libvlc_video_logo_option_t {
    libvlc_logo_enable,
    libvlc_logo_file,           /**< string argument, "file,d,t;file,d,t;..." */
    libvlc_logo_x,
    libvlc_logo_y,
    libvlc_logo_delay,
    libvlc_logo_repeat,
    libvlc_logo_opacity,
    libvlc_logo_position,
};

/**
 * Get integer logo option.
 *
 * \param p_mi libvlc media player instance
 * \param option logo option to get, values of libvlc_video_logo_option_t
 */
VLC_PUBLIC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi,
854
                                              unsigned option );
855
856
857

/**
 * Set logo option as integer. Options that take a different type value
858
 * are ignored.
859
860
861
862
863
864
865
866
 * Passing libvlc_logo_enable as option value has the side effect of
 * starting (arg !0) or stopping (arg 0) the logo filter.
 *
 * \param p_mi libvlc media player instance
 * \param option logo option to set, values of libvlc_video_logo_option_t
 * \param value logo option value
 */
VLC_PUBLIC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi,
867
                                               unsigned option, int value );
868
869
870

/**
 * Set logo option as string. Options that take a different type value
871
 * are ignored.
872
873
874
875
876
877
 *
 * \param p_mi libvlc media player instance
 * \param option logo option to set, values of libvlc_video_logo_option_t
 * \param psz_value logo option value
 */
VLC_PUBLIC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
878
                                      unsigned option, const char *psz_value );
879

880

881
882
883
884
885
886
887
888
889
890
891
/** @} video */

/** \defgroup libvlc_audio libvlc_audio
 * \ingroup libvlc_media_player
 * LibVLC Audio handling
 * @{
 */

/**
 * Audio device types
 */
892
typedef enum libvlc_audio_output_device_types_t {
893
894
895
896
897
898
899
900
    libvlc_AudioOutputDevice_Error  = -1,
    libvlc_AudioOutputDevice_Mono   =  1,
    libvlc_AudioOutputDevice_Stereo =  2,
    libvlc_AudioOutputDevice_2F2R   =  4,
    libvlc_AudioOutputDevice_3F2R   =  5,
    libvlc_AudioOutputDevice_5_1    =  6,
    libvlc_AudioOutputDevice_6_1    =  7,
    libvlc_AudioOutputDevice_7_1    =  8,
901
902
    libvlc_AudioOutputDevice_SPDIF  = 10
} libvlc_audio_output_device_types_t;
903
904
905
906

/**
 * Audio channels
 */
907
typedef enum libvlc_audio_output_channel_t {
908
909
910
911
912
    libvlc_AudioChannel_Error   = -1,
    libvlc_AudioChannel_Stereo  =  1,
    libvlc_AudioChannel_RStereo =  2,
    libvlc_AudioChannel_Left    =  3,
    libvlc_AudioChannel_Right   =  4,
913
914
    libvlc_AudioChannel_Dolbys  =  5
} libvlc_audio_output_channel_t;
915
916
917
918
919
920


/**
 * Get the list of available audio outputs
 *
 * \param p_instance libvlc instance
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
921
922
923
 * \return list of available audio outputs. It must be freed it with
*          \see libvlc_audio_output_list_release \see libvlc_audio_output_t .
 *         In case of error, NULL is returned.
924
925
 */
VLC_PUBLIC_API libvlc_audio_output_t *
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
926
        libvlc_audio_output_list_get( libvlc_instance_t * );
927
928
929
930
931
932
933
934
935
936
937
938

/**
 * Free the list of available audio outputs
 *
 * \param p_list list with audio outputs for release
 */
VLC_PUBLIC_API void libvlc_audio_output_list_release( libvlc_audio_output_t * );

/**
 * Set the audio output.
 * Change will be applied after stop and play.
 *
939
 * \param mp media player
940
941
942
943
 * \param psz_name name of audio output,
 *               use psz_name of \see libvlc_audio_output_t
 * \return true if function succeded
 */
944
VLC_PUBLIC_API int libvlc_audio_output_set( libvlc_media_player_t *,
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
                                            const char * );

/**
 * Get count of devices for audio output, these devices are hardware oriented
 * like analor or digital output of sound card
 *
 * \param p_instance libvlc instance
 * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
 * \return number of devices
 */
VLC_PUBLIC_API int libvlc_audio_output_device_count( libvlc_instance_t *,
                                                     const char * );

/**
 * Get long name of device, if not available short name given
 *
 * \param p_instance libvlc instance
 * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
 * \param i_device device index
 * \return long name of device
 */
VLC_PUBLIC_API char * libvlc_audio_output_device_longname( libvlc_instance_t *,
                                                           const char *,
                                                           int );

/**
 * Get id name of device
 *
 * \param p_instance libvlc instance
 * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
 * \param i_device device index
 * \return id name of device, use for setting device, need to be free after use
 */
VLC_PUBLIC_API char * libvlc_audio_output_device_id( libvlc_instance_t *,
                                                     const char *,
                                                     int );

/**
983
 * Set audio output device. Changes are only effective after stop and play.
984
 *
985
 * \param mp media player
986
987
988
 * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
 * \param psz_device_id device
 */
989
VLC_PUBLIC_API void libvlc_audio_output_device_set( libvlc_media_player_t *,
990
991
992
993
994
995
996
                                                    const char *,
                                                    const char * );

/**
 * Get current audio device type. Device type describes something like
 * character of output sound - stereo sound, 2.1, 5.1 etc
 *
997
 * \param mp media player
998
999
1000
 * \return the audio devices type \see libvlc_audio_output_device_types_t
 */
VLC_PUBLIC_API int libvlc_audio_output_get_device_type(
1001
        libvlc_media_player_t * );
1002
1003
1004
1005

/**
 * Set current audio device type.
 *
1006
 * \param mp vlc instance
1007
1008
1009
 * \param device_type the audio device type,
          according to \see libvlc_audio_output_device_types_t
 */
1010
1011
VLC_PUBLIC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *,
                                                         int );
1012
1013
1014
1015
1016


/**
 * Toggle mute status.
 *
1017
 * \param mp media player
1018
 */
1019
VLC_PUBLIC_API void libvlc_audio_toggle_mute( libvlc_media_player_t * );
1020
1021
1022
1023

/**
 * Get current mute status.
 *
1024
 * \param mp media player
1025
1026
 * \return the mute status (boolean)
 */
1027
VLC_PUBLIC_API int libvlc_audio_get_mute( libvlc_media_player_t * );
1028
1029
1030
1031

/**
 * Set mute status.
 *
1032
 * \param mp media player
1033
1034
 * \param status If status is true then mute, otherwise unmute
 */
1035
VLC_PUBLIC_API void libvlc_audio_set_mute( libvlc_media_player_t *, int );
1036
1037
1038
1039

/**
 * Get current audio level.
 *
1040
 * \param mp media player
1041
1042
 * \return the audio level (int)
 */
1043
VLC_PUBLIC_API int libvlc_audio_get_volume( libvlc_media_player_t * );
1044
1045
1046
1047

/**
 * Set current audio level.
 *
1048
 * \param mp media player
1049
 * \param i_volume the volume (int)
1050
 * \return 0 if the volume was set, -1 if it was out of range
1051
 */
1052
VLC_PUBLIC_API int libvlc_audio_set_volume( libvlc_media_player_t *, int );
1053
1054
1055
1056
1057

/**
 * Get number of available audio tracks.
 *
 * \param p_mi media player
1058
 * \return the number of available audio tracks (int), or -1 if unavailable
1059
 */
1060
VLC_PUBLIC_API int libvlc_audio_get_track_count( libvlc_media_player_t * );
1061

Olivier Aubert's avatar
Olivier Aubert committed
1062
/**
1063
1064
1065
 * Get the description of available audio tracks.
 *
 * \param p_mi media player
1066
 * \return list with description of available audio tracks, or NULL
1067
1068
 */
VLC_PUBLIC_API libvlc_track_description_t *
1069
        libvlc_audio_get_track_description( libvlc_media_player_t * );
1070
1071
1072
1073
1074

/**
 * Get current audio track.
 *
 * \param p_mi media player
1075
 * \return the audio track (int), or -1 if none.
1076
 */
1077
VLC_PUBLIC_API int libvlc_audio_get_track( libvlc_media_player_t * );
1078
1079
1080
1081
1082
1083

/**
 * Set current audio track.
 *
 * \param p_mi media player
 * \param i_track the track (int)
1084
 * \return 0 on success, -1 on error
1085
 */
1086
VLC_PUBLIC_API int libvlc_audio_set_track( libvlc_media_player_t *, int );
1087
1088
1089
1090

/**
 * Get current audio channel.
 *
1091
 * \param mp media player
1092
1093
 * \return the audio channel \see libvlc_audio_output_channel_t
 */
1094
VLC_PUBLIC_API int libvlc_audio_get_channel( libvlc_media_player_t * );
1095
1096
1097
1098

/**
 * Set current audio channel.
 *
1099
 * \param p_mi media player
1100
 * \param channel the audio channel, \see libvlc_audio_output_channel_t
1101
 * \return 0 on success, -1 on error
1102
 */
1103
VLC_PUBLIC_API int libvlc_audio_set_channel( libvlc_media_player_t *, int );
1104
1105
1106
1107
1108

/** @} audio */

/** @} media_player */

ivoire's avatar
ivoire committed
1109
1110
1111
1112
# ifdef __cplusplus
}
# endif

1113
#endif /* VLC_LIBVLC_MEDIA_PLAYER_H */