python: release 3.0.6109
[vlc/bindings/python.git] / generated / dev / vlc.py
1 #! /usr/bin/python
2 # -*- coding: utf-8 -*-
3
4 # Python ctypes bindings for VLC
5 #
6 # Copyright (C) 2009-2017 the VideoLAN team
7 # $Id: $
8 #
9 # Authors: Olivier Aubert <contact at olivieraubert.net>
10 #          Jean Brouwers <MrJean1 at gmail.com>
11 #          Geoff Salmon <geoff.salmon at gmail.com>
12 #
13 # This library is free software; you can redistribute it and/or modify
14 # it under the terms of the GNU Lesser General Public License as
15 # published by the Free Software Foundation; either version 2.1 of the
16 # License, or (at your option) any later version.
17 #
18 # This library is distributed in the hope that it will be useful, but
19 # WITHOUT ANY WARRANTY; without even the implied warranty of
20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
21 # Lesser General Public License for more details.
22 #
23 # You should have received a copy of the GNU Lesser General Public
24 # License along with this library; if not, write to the Free Software
25 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA
26
27 """This module provides bindings for the LibVLC public API, see
28 U{http://wiki.videolan.org/LibVLC}.
29
30 You can find the documentation and a README file with some examples
31 at U{http://www.olivieraubert.net/vlc/python-ctypes/}.
32
33 Basically, the most important class is L{Instance}, which is used
34 to create a libvlc instance.  From this instance, you then create
35 L{MediaPlayer} and L{MediaListPlayer} instances.
36
37 Alternatively, you may create instances of the L{MediaPlayer} and
38 L{MediaListPlayer} class directly and an instance of L{Instance}
39 will be implicitly created.  The latter can be obtained using the
40 C{get_instance} method of L{MediaPlayer} and L{MediaListPlayer}.
41 """
42
43 import ctypes
44 from ctypes.util import find_library
45 import os
46 import sys
47 import functools
48
49 # Used by EventManager in override.py
50 from inspect import getargspec
51
52 import logging
53 logger = logging.getLogger(__name__)
54
55 __version__ = "4.0.0-dev-6311-gd5ccdffa65108"
56 __libvlc_version__ = "4.0.0-dev-6311-gd5ccdffa65"
57 __generator_version__ = "1.8"
58 build_date  = "Sun Feb 24 16:20:24 2019 4.0.0-dev-6311-gd5ccdffa65"
59
60 # The libvlc doc states that filenames are expected to be in UTF8, do
61 # not rely on sys.getfilesystemencoding() which will be confused,
62 # esp. on windows.
63 DEFAULT_ENCODING = 'utf-8'
64
65 if sys.version_info[0] > 2:
66     str = str
67     unicode = str
68     bytes = bytes
69     basestring = (str, bytes)
70     PYTHON3 = True
71     def str_to_bytes(s):
72         """Translate string or bytes to bytes.
73         """
74         if isinstance(s, str):
75             return bytes(s, DEFAULT_ENCODING)
76         else:
77             return s
78
79     def bytes_to_str(b):
80         """Translate bytes to string.
81         """
82         if isinstance(b, bytes):
83             return b.decode(DEFAULT_ENCODING)
84         else:
85             return b
86 else:
87     str = str
88     unicode = unicode
89     bytes = str
90     basestring = basestring
91     PYTHON3 = False
92     def str_to_bytes(s):
93         """Translate string or bytes to bytes.
94         """
95         if isinstance(s, unicode):
96             return s.encode(DEFAULT_ENCODING)
97         else:
98             return s
99
100     def bytes_to_str(b):
101         """Translate bytes to unicode string.
102         """
103         if isinstance(b, str):
104             return unicode(b, DEFAULT_ENCODING)
105         else:
106             return b
107
108 # Internal guard to prevent internal classes to be directly
109 # instanciated.
110 _internal_guard = object()
111
112 def find_lib():
113     dll = None
114     plugin_path = os.environ.get('PYTHON_VLC_MODULE_PATH', None)
115     if 'PYTHON_VLC_LIB_PATH' in os.environ:
116         try:
117             dll = ctypes.CDLL(os.environ['PYTHON_VLC_LIB_PATH'])
118         except OSError:
119             logger.error("Cannot load lib specified by PYTHON_VLC_LIB_PATH env. variable")
120             sys.exit(1)
121     if plugin_path and not os.path.isdir(plugin_path):
122         logger.error("Invalid PYTHON_VLC_MODULE_PATH specified. Please fix.")
123         sys.exit(1)
124     if dll is not None:
125         return dll, plugin_path
126
127     if sys.platform.startswith('win'):
128         libname = 'libvlc.dll'
129         p = find_library(libname)
130         if p is None:
131             try:  # some registry settings
132                 # leaner than win32api, win32con
133                 if PYTHON3:
134                     import winreg as w
135                 else:
136                     import _winreg as w
137                 for r in w.HKEY_LOCAL_MACHINE, w.HKEY_CURRENT_USER:
138                     try:
139                         r = w.OpenKey(r, 'Software\\VideoLAN\\VLC')
140                         plugin_path, _ = w.QueryValueEx(r, 'InstallDir')
141                         w.CloseKey(r)
142                         break
143                     except w.error:
144                         pass
145             except ImportError:  # no PyWin32
146                 pass
147             if plugin_path is None:
148                 # try some standard locations.
149                 programfiles = os.environ["ProgramFiles"]
150                 homedir = os.environ["HOMEDRIVE"]
151                 for p in ('{programfiles}\\VideoLan{libname}', '{homedir}:\\VideoLan{libname}',
152                           '{programfiles}{libname}',           '{homedir}:{libname}'):
153                     p = p.format(homedir = homedir,
154                                  programfiles = programfiles,
155                                  libname = '\\VLC\\' + libname)
156                     if os.path.exists(p):
157                         plugin_path = os.path.dirname(p)
158                         break
159             if plugin_path is not None:  # try loading
160                 p = os.getcwd()
161                 os.chdir(plugin_path)
162                  # if chdir failed, this will raise an exception
163                 dll = ctypes.CDLL(libname)
164                  # restore cwd after dll has been loaded
165                 os.chdir(p)
166             else:  # may fail
167                 dll = ctypes.CDLL(libname)
168         else:
169             plugin_path = os.path.dirname(p)
170             dll = ctypes.CDLL(p)
171
172     elif sys.platform.startswith('darwin'):
173         # FIXME: should find a means to configure path
174         d = '/Applications/VLC.app/Contents/MacOS/'
175         c = d + 'lib/libvlccore.dylib'
176         p = d + 'lib/libvlc.dylib'
177         if os.path.exists(p) and os.path.exists(c):
178             # pre-load libvlccore VLC 2.2.8+
179             ctypes.CDLL(c)
180             dll = ctypes.CDLL(p)
181             for p in ('modules', 'plugins'):
182                 p = d + p
183                 if os.path.isdir(p):
184                     plugin_path = p
185                     break
186         else:  # hope, some [DY]LD_LIBRARY_PATH is set...
187             # pre-load libvlccore VLC 2.2.8+
188             ctypes.CDLL('libvlccore.dylib')
189             dll = ctypes.CDLL('libvlc.dylib')
190
191     else:
192         # All other OSes (linux, freebsd...)
193         p = find_library('vlc')
194         try:
195             dll = ctypes.CDLL(p)
196         except OSError:  # may fail
197             dll = None
198         if dll is None:
199             try:
200                 dll = ctypes.CDLL('libvlc.so.5')
201             except:
202                 raise NotImplementedError('Cannot find libvlc lib')
203
204     return (dll, plugin_path)
205
206 # plugin_path used on win32 and MacOS in override.py
207 dll, plugin_path  = find_lib()
208
209 class VLCException(Exception):
210     """Exception raised by libvlc methods.
211     """
212     pass
213
214 try:
215     _Ints = (int, long)
216 except NameError:  # no long in Python 3+
217     _Ints =  int
218 _Seqs = (list, tuple)
219
220 # Used for handling *event_manager() methods.
221 class memoize_parameterless(object):
222     """Decorator. Caches a parameterless method's return value each time it is called.
223
224     If called later with the same arguments, the cached value is returned
225     (not reevaluated).
226     Adapted from https://wiki.python.org/moin/PythonDecoratorLibrary
227     """
228     def __init__(self, func):
229         self.func = func
230         self._cache = {}
231
232     def __call__(self, obj):
233         try:
234             return self._cache[obj]
235         except KeyError:
236             v = self._cache[obj] = self.func(obj)
237             return v
238
239     def __repr__(self):
240         """Return the function's docstring.
241         """
242         return self.func.__doc__
243
244     def __get__(self, obj, objtype):
245       """Support instance methods.
246       """
247       return functools.partial(self.__call__, obj)
248
249 # Default instance. It is used to instanciate classes directly in the
250 # OO-wrapper.
251 _default_instance = None
252
253 def get_default_instance():
254     """Return the default VLC.Instance.
255     """
256     global _default_instance
257     if _default_instance is None:
258         _default_instance = Instance()
259     return _default_instance
260
261 _Cfunctions = {}  # from LibVLC __version__
262 _Globals = globals()  # sys.modules[__name__].__dict__
263
264 def _Cfunction(name, flags, errcheck, *types):
265     """(INTERNAL) New ctypes function binding.
266     """
267     if hasattr(dll, name) and name in _Globals:
268         p = ctypes.CFUNCTYPE(*types)
269         f = p((name, dll), flags)
270         if errcheck is not None:
271             f.errcheck = errcheck
272         # replace the Python function
273         # in this module, but only when
274         # running as python -O or -OO
275         if __debug__:
276             _Cfunctions[name] = f
277         else:
278             _Globals[name] = f
279         return f
280     raise NameError('no function %r' % (name,))
281
282 def _Cobject(cls, ctype):
283     """(INTERNAL) New instance from ctypes.
284     """
285     o = object.__new__(cls)
286     o._as_parameter_ = ctype
287     return o
288
289 def _Constructor(cls, ptr=_internal_guard):
290     """(INTERNAL) New wrapper from ctypes.
291     """
292     if ptr == _internal_guard:
293         raise VLCException("(INTERNAL) ctypes class. You should get references for this class through methods of the LibVLC API.")
294     if ptr is None or ptr == 0:
295         return None
296     return _Cobject(cls, ctypes.c_void_p(ptr))
297
298 class _Cstruct(ctypes.Structure):
299     """(INTERNAL) Base class for ctypes structures.
300     """
301     _fields_ = []  # list of 2-tuples ('name', ctyptes.<type>)
302
303     def __str__(self):
304         l = [' %s:\t%s' % (n, getattr(self, n)) for n, _ in self._fields_]
305         return '\n'.join([self.__class__.__name__] + l)
306
307     def __repr__(self):
308         return '%s.%s' % (self.__class__.__module__, self)
309
310 class _Ctype(object):
311     """(INTERNAL) Base class for ctypes.
312     """
313     @staticmethod
314     def from_param(this):  # not self
315         """(INTERNAL) ctypes parameter conversion method.
316         """
317         if this is None:
318             return None
319         return this._as_parameter_
320
321 class ListPOINTER(object):
322     """Just like a POINTER but accept a list of ctype as an argument.
323     """
324     def __init__(self, etype):
325         self.etype = etype
326
327     def from_param(self, param):
328         if isinstance(param, _Seqs):
329             return (self.etype * len(param))(*param)
330         else:
331             return ctypes.POINTER(param)
332
333 # errcheck functions for some native functions.
334 def string_result(result, func, arguments):
335     """Errcheck function. Returns a string and frees the original pointer.
336
337     It assumes the result is a char *.
338     """
339     if result:
340         # make a python string copy
341         s = bytes_to_str(ctypes.string_at(result))
342         # free original string ptr
343         libvlc_free(result)
344         return s
345     return None
346
347 def class_result(classname):
348     """Errcheck function. Returns a function that creates the specified class.
349     """
350     def wrap_errcheck(result, func, arguments):
351         if result is None:
352             return None
353         return classname(result)
354     return wrap_errcheck
355
356 # Wrapper for the opaque struct libvlc_log_t
357 class Log(ctypes.Structure):
358     pass
359 Log_ptr = ctypes.POINTER(Log)
360
361 # FILE* ctypes wrapper, copied from
362 # http://svn.python.org/projects/ctypes/trunk/ctypeslib/ctypeslib/contrib/pythonhdr.py
363 class FILE(ctypes.Structure):
364     pass
365 FILE_ptr = ctypes.POINTER(FILE)
366
367 if PYTHON3:
368     PyFile_FromFd = ctypes.pythonapi.PyFile_FromFd
369     PyFile_FromFd.restype = ctypes.py_object
370     PyFile_FromFd.argtypes = [ctypes.c_int,
371                               ctypes.c_char_p,
372                               ctypes.c_char_p,
373                               ctypes.c_int,
374                               ctypes.c_char_p,
375                               ctypes.c_char_p,
376                               ctypes.c_char_p,
377                               ctypes.c_int ]
378
379     PyFile_AsFd = ctypes.pythonapi.PyObject_AsFileDescriptor
380     PyFile_AsFd.restype = ctypes.c_int
381     PyFile_AsFd.argtypes = [ctypes.py_object]
382 else:
383     PyFile_FromFile = ctypes.pythonapi.PyFile_FromFile
384     PyFile_FromFile.restype = ctypes.py_object
385     PyFile_FromFile.argtypes = [FILE_ptr,
386                                 ctypes.c_char_p,
387                                 ctypes.c_char_p,
388                                 ctypes.CFUNCTYPE(ctypes.c_int, FILE_ptr)]
389
390     PyFile_AsFile = ctypes.pythonapi.PyFile_AsFile
391     PyFile_AsFile.restype = FILE_ptr
392     PyFile_AsFile.argtypes = [ctypes.py_object]
393
394  # Generated enum types #
395
396 class _Enum(ctypes.c_uint):
397     '''(INTERNAL) Base class
398     '''
399     _enum_names_ = {}
400
401     def __str__(self):
402         n = self._enum_names_.get(self.value, '') or ('FIXME_(%r)' % (self.value,))
403         return '.'.join((self.__class__.__name__, n))
404
405     def __hash__(self):
406         return self.value
407
408     def __repr__(self):
409         return '.'.join((self.__class__.__module__, self.__str__()))
410
411     def __eq__(self, other):
412         return ( (isinstance(other, _Enum) and self.value == other.value)
413               or (isinstance(other, _Ints) and self.value == other) )
414
415     def __ne__(self, other):
416         return not self.__eq__(other)
417
418 class LogLevel(_Enum):
419     '''Logging messages level.
420 \note future libvlc versions may define new levels.
421     '''
422     _enum_names_ = {
423         0: 'DEBUG',
424         2: 'NOTICE',
425         3: 'WARNING',
426         4: 'ERROR',
427     }
428 LogLevel.DEBUG   = LogLevel(0)
429 LogLevel.ERROR   = LogLevel(4)
430 LogLevel.NOTICE  = LogLevel(2)
431 LogLevel.WARNING = LogLevel(3)
432
433 class MediaDiscovererCategory(_Enum):
434     '''Category of a media discoverer
435 See libvlc_media_discoverer_list_get().
436     '''
437     _enum_names_ = {
438         0: 'devices',
439         1: 'lan',
440         2: 'podcasts',
441         3: 'localdirs',
442     }
443 MediaDiscovererCategory.devices   = MediaDiscovererCategory(0)
444 MediaDiscovererCategory.lan       = MediaDiscovererCategory(1)
445 MediaDiscovererCategory.localdirs = MediaDiscovererCategory(3)
446 MediaDiscovererCategory.podcasts  = MediaDiscovererCategory(2)
447
448 class DialogQuestionType(_Enum):
449     '''@defgroup libvlc_dialog libvlc dialog
450 @ingroup libvlc
451 @{
452 @file
453 libvlc dialog external api.
454     '''
455     _enum_names_ = {
456         0: 'NORMAL',
457         1: 'WARNING',
458         2: 'CRITICAL',
459     }
460 DialogQuestionType.CRITICAL = DialogQuestionType(2)
461 DialogQuestionType.NORMAL   = DialogQuestionType(0)
462 DialogQuestionType.WARNING  = DialogQuestionType(1)
463
464 class PictureType(_Enum):
465     '''N/A
466     '''
467     _enum_names_ = {
468         0: 'Argb',
469         1: 'Png',
470         2: 'Jpg',
471     }
472 PictureType.Argb = PictureType(0)
473 PictureType.Jpg  = PictureType(2)
474 PictureType.Png  = PictureType(1)
475
476 class EventType(_Enum):
477     '''Event types.
478     '''
479     _enum_names_ = {
480         0: 'MediaMetaChanged',
481         1: 'MediaSubItemAdded',
482         2: 'MediaDurationChanged',
483         3: 'MediaParsedChanged',
484         4: 'MediaFreed',
485         5: 'MediaStateChanged',
486         6: 'MediaSubItemTreeAdded',
487         7: 'MediaThumbnailGenerated',
488         0x100: 'MediaPlayerMediaChanged',
489         257: 'MediaPlayerNothingSpecial',
490         258: 'MediaPlayerOpening',
491         259: 'MediaPlayerBuffering',
492         260: 'MediaPlayerPlaying',
493         261: 'MediaPlayerPaused',
494         262: 'MediaPlayerStopped',
495         263: 'MediaPlayerForward',
496         264: 'MediaPlayerBackward',
497         265: 'MediaPlayerEndReached',
498         266: 'MediaPlayerEncounteredError',
499         267: 'MediaPlayerTimeChanged',
500         268: 'MediaPlayerPositionChanged',
501         269: 'MediaPlayerSeekableChanged',
502         270: 'MediaPlayerPausableChanged',
503         271: 'MediaPlayerTitleChanged',
504         272: 'MediaPlayerSnapshotTaken',
505         273: 'MediaPlayerLengthChanged',
506         274: 'MediaPlayerVout',
507         275: 'MediaPlayerScrambledChanged',
508         276: 'MediaPlayerESAdded',
509         277: 'MediaPlayerESDeleted',
510         278: 'MediaPlayerESSelected',
511         279: 'MediaPlayerCorked',
512         280: 'MediaPlayerUncorked',
513         281: 'MediaPlayerMuted',
514         282: 'MediaPlayerUnmuted',
515         283: 'MediaPlayerAudioVolume',
516         284: 'MediaPlayerAudioDevice',
517         285: 'MediaPlayerChapterChanged',
518         0x200: 'MediaListItemAdded',
519         513: 'MediaListWillAddItem',
520         514: 'MediaListItemDeleted',
521         515: 'MediaListWillDeleteItem',
522         516: 'MediaListEndReached',
523         0x300: 'MediaListViewItemAdded',
524         769: 'MediaListViewWillAddItem',
525         770: 'MediaListViewItemDeleted',
526         771: 'MediaListViewWillDeleteItem',
527         0x400: 'MediaListPlayerPlayed',
528         1025: 'MediaListPlayerNextItemSet',
529         1026: 'MediaListPlayerStopped',
530         0x502: 'RendererDiscovererItemAdded',
531         1283: 'RendererDiscovererItemDeleted',
532     }
533 EventType.MediaDurationChanged          = EventType(2)
534 EventType.MediaFreed                    = EventType(4)
535 EventType.MediaListEndReached           = EventType(516)
536 EventType.MediaListItemAdded            = EventType(0x200)
537 EventType.MediaListItemDeleted          = EventType(514)
538 EventType.MediaListPlayerNextItemSet    = EventType(1025)
539 EventType.MediaListPlayerPlayed         = EventType(0x400)
540 EventType.MediaListPlayerStopped        = EventType(1026)
541 EventType.MediaListViewItemAdded        = EventType(0x300)
542 EventType.MediaListViewItemDeleted      = EventType(770)
543 EventType.MediaListViewWillAddItem      = EventType(769)
544 EventType.MediaListViewWillDeleteItem   = EventType(771)
545 EventType.MediaListWillAddItem          = EventType(513)
546 EventType.MediaListWillDeleteItem       = EventType(515)
547 EventType.MediaMetaChanged              = EventType(0)
548 EventType.MediaParsedChanged            = EventType(3)
549 EventType.MediaPlayerAudioDevice        = EventType(284)
550 EventType.MediaPlayerAudioVolume        = EventType(283)
551 EventType.MediaPlayerBackward           = EventType(264)
552 EventType.MediaPlayerBuffering          = EventType(259)
553 EventType.MediaPlayerChapterChanged     = EventType(285)
554 EventType.MediaPlayerCorked             = EventType(279)
555 EventType.MediaPlayerESAdded            = EventType(276)
556 EventType.MediaPlayerESDeleted          = EventType(277)
557 EventType.MediaPlayerESSelected         = EventType(278)
558 EventType.MediaPlayerEncounteredError   = EventType(266)
559 EventType.MediaPlayerEndReached         = EventType(265)
560 EventType.MediaPlayerForward            = EventType(263)
561 EventType.MediaPlayerLengthChanged      = EventType(273)
562 EventType.MediaPlayerMediaChanged       = EventType(0x100)
563 EventType.MediaPlayerMuted              = EventType(281)
564 EventType.MediaPlayerNothingSpecial     = EventType(257)
565 EventType.MediaPlayerOpening            = EventType(258)
566 EventType.MediaPlayerPausableChanged    = EventType(270)
567 EventType.MediaPlayerPaused             = EventType(261)
568 EventType.MediaPlayerPlaying            = EventType(260)
569 EventType.MediaPlayerPositionChanged    = EventType(268)
570 EventType.MediaPlayerScrambledChanged   = EventType(275)
571 EventType.MediaPlayerSeekableChanged    = EventType(269)
572 EventType.MediaPlayerSnapshotTaken      = EventType(272)
573 EventType.MediaPlayerStopped            = EventType(262)
574 EventType.MediaPlayerTimeChanged        = EventType(267)
575 EventType.MediaPlayerTitleChanged       = EventType(271)
576 EventType.MediaPlayerUncorked           = EventType(280)
577 EventType.MediaPlayerUnmuted            = EventType(282)
578 EventType.MediaPlayerVout               = EventType(274)
579 EventType.MediaStateChanged             = EventType(5)
580 EventType.MediaSubItemAdded             = EventType(1)
581 EventType.MediaSubItemTreeAdded         = EventType(6)
582 EventType.MediaThumbnailGenerated       = EventType(7)
583 EventType.RendererDiscovererItemAdded   = EventType(0x502)
584 EventType.RendererDiscovererItemDeleted = EventType(1283)
585
586 class Meta(_Enum):
587     '''Meta data types.
588     '''
589     _enum_names_ = {
590         0: 'Title',
591         1: 'Artist',
592         2: 'Genre',
593         3: 'Copyright',
594         4: 'Album',
595         5: 'TrackNumber',
596         6: 'Description',
597         7: 'Rating',
598         8: 'Date',
599         9: 'Setting',
600         10: 'URL',
601         11: 'Language',
602         12: 'NowPlaying',
603         13: 'Publisher',
604         14: 'EncodedBy',
605         15: 'ArtworkURL',
606         16: 'TrackID',
607         17: 'TrackTotal',
608         18: 'Director',
609         19: 'Season',
610         20: 'Episode',
611         21: 'ShowName',
612         22: 'Actors',
613         23: 'AlbumArtist',
614         24: 'DiscNumber',
615         25: 'DiscTotal',
616     }
617 Meta.Actors      = Meta(22)
618 Meta.Album       = Meta(4)
619 Meta.AlbumArtist = Meta(23)
620 Meta.Artist      = Meta(1)
621 Meta.ArtworkURL  = Meta(15)
622 Meta.Copyright   = Meta(3)
623 Meta.Date        = Meta(8)
624 Meta.Description = Meta(6)
625 Meta.Director    = Meta(18)
626 Meta.DiscNumber  = Meta(24)
627 Meta.DiscTotal   = Meta(25)
628 Meta.EncodedBy   = Meta(14)
629 Meta.Episode     = Meta(20)
630 Meta.Genre       = Meta(2)
631 Meta.Language    = Meta(11)
632 Meta.NowPlaying  = Meta(12)
633 Meta.Publisher   = Meta(13)
634 Meta.Rating      = Meta(7)
635 Meta.Season      = Meta(19)
636 Meta.Setting     = Meta(9)
637 Meta.ShowName    = Meta(21)
638 Meta.Title       = Meta(0)
639 Meta.TrackID     = Meta(16)
640 Meta.TrackNumber = Meta(5)
641 Meta.TrackTotal  = Meta(17)
642 Meta.URL         = Meta(10)
643
644 class State(_Enum):
645     '''Note the order of libvlc_state_t enum must match exactly the order of
646 See mediacontrol_playerstatus, See input_state_e enums,
647 and videolan.libvlc.state (at bindings/cil/src/media.cs).
648 expected states by web plugins are:
649 idle/close=0, opening=1, playing=3, paused=4,
650 stopping=5, ended=6, error=7.
651     '''
652     _enum_names_ = {
653         0: 'NothingSpecial',
654         1: 'Opening',
655         2: 'Buffering',
656         3: 'Playing',
657         4: 'Paused',
658         5: 'Stopped',
659         6: 'Ended',
660         7: 'Error',
661     }
662 State.Buffering      = State(2)
663 State.Ended          = State(6)
664 State.Error          = State(7)
665 State.NothingSpecial = State(0)
666 State.Opening        = State(1)
667 State.Paused         = State(4)
668 State.Playing        = State(3)
669 State.Stopped        = State(5)
670
671 class TrackType(_Enum):
672     '''N/A
673     '''
674     _enum_names_ = {
675         -1: 'unknown',
676         0: 'audio',
677         1: 'video',
678         2: 'text',
679     }
680 TrackType.audio   = TrackType(0)
681 TrackType.text    = TrackType(2)
682 TrackType.unknown = TrackType(-1)
683 TrackType.video   = TrackType(1)
684
685 class VideoOrient(_Enum):
686     '''N/A
687     '''
688     _enum_names_ = {
689         0: 'left',
690         1: 'right',
691         2: 'left',
692         3: 'right',
693         4: 'top',
694         5: 'bottom',
695         6: 'top',
696         7: 'bottom',
697     }
698 VideoOrient.bottom = VideoOrient(5)
699 VideoOrient.bottom = VideoOrient(7)
700 VideoOrient.left   = VideoOrient(0)
701 VideoOrient.left   = VideoOrient(2)
702 VideoOrient.right  = VideoOrient(1)
703 VideoOrient.right  = VideoOrient(3)
704 VideoOrient.top    = VideoOrient(4)
705 VideoOrient.top    = VideoOrient(6)
706
707 class VideoProjection(_Enum):
708     '''N/A
709     '''
710     _enum_names_ = {
711         0: 'rectangular',
712         1: 'equirectangular',
713         0x100: 'standard',
714     }
715 VideoProjection.equirectangular = VideoProjection(1)
716 VideoProjection.rectangular     = VideoProjection(0)
717 VideoProjection.standard        = VideoProjection(0x100)
718
719 class VideoMultiview(_Enum):
720     '''Viewpoint
721 \warning allocate using libvlc_video_new_viewpoint().
722     '''
723     _enum_names_ = {
724         0: '_2d',
725         1: 'sbs',
726         2: 'tb',
727         3: 'row',
728         4: 'col',
729         5: 'frame',
730         6: 'checkerboard',
731     }
732 VideoMultiview._2d          = VideoMultiview(0)
733 VideoMultiview.checkerboard = VideoMultiview(6)
734 VideoMultiview.col          = VideoMultiview(4)
735 VideoMultiview.frame        = VideoMultiview(5)
736 VideoMultiview.row          = VideoMultiview(3)
737 VideoMultiview.sbs          = VideoMultiview(1)
738 VideoMultiview.tb           = VideoMultiview(2)
739
740 class MediaType(_Enum):
741     '''Media type
742 See libvlc_media_get_type.
743     '''
744     _enum_names_ = {
745         0: 'unknown',
746         1: 'file',
747         2: 'directory',
748         3: 'disc',
749         4: 'stream',
750         5: 'playlist',
751     }
752 MediaType.directory = MediaType(2)
753 MediaType.disc      = MediaType(3)
754 MediaType.file      = MediaType(1)
755 MediaType.playlist  = MediaType(5)
756 MediaType.stream    = MediaType(4)
757 MediaType.unknown   = MediaType(0)
758
759 class MediaParseFlag(_Enum):
760     '''Parse flags used by libvlc_media_parse_with_options()
761 See libvlc_media_parse_with_options.
762     '''
763     _enum_names_ = {
764         0x0: 'local',
765         0x1: 'network',
766         0x2: 'local',
767         0x4: 'network',
768         0x8: 'interact',
769     }
770 MediaParseFlag.interact = MediaParseFlag(0x8)
771 MediaParseFlag.local    = MediaParseFlag(0x0)
772 MediaParseFlag.local    = MediaParseFlag(0x2)
773 MediaParseFlag.network  = MediaParseFlag(0x1)
774 MediaParseFlag.network  = MediaParseFlag(0x4)
775
776 class MediaParsedStatus(_Enum):
777     '''Parse status used sent by libvlc_media_parse_with_options() or returned by
778 libvlc_media_get_parsed_status()
779 See libvlc_media_parse_with_options
780 See libvlc_media_get_parsed_status.
781     '''
782     _enum_names_ = {
783         1: 'skipped',
784         2: 'failed',
785         3: 'timeout',
786         4: 'done',
787     }
788 MediaParsedStatus.done    = MediaParsedStatus(4)
789 MediaParsedStatus.failed  = MediaParsedStatus(2)
790 MediaParsedStatus.skipped = MediaParsedStatus(1)
791 MediaParsedStatus.timeout = MediaParsedStatus(3)
792
793 class MediaSlaveType(_Enum):
794     '''Type of a media slave: subtitle or audio.
795     '''
796     _enum_names_ = {
797         0: 'subtitle',
798         1: 'audio',
799     }
800 MediaSlaveType.audio    = MediaSlaveType(1)
801 MediaSlaveType.subtitle = MediaSlaveType(0)
802
803 class ThumbnailerSeekSpeed(_Enum):
804     '''N/A
805     '''
806     _enum_names_ = {
807         0: 'precise',
808         1: 'fast',
809     }
810 ThumbnailerSeekSpeed.fast    = ThumbnailerSeekSpeed(1)
811 ThumbnailerSeekSpeed.precise = ThumbnailerSeekSpeed(0)
812
813 class VideoMarqueeOption(_Enum):
814     '''Marq options definition.
815     '''
816     _enum_names_ = {
817         0: 'Enable',
818         1: 'Text',
819         2: 'Color',
820         3: 'Opacity',
821         4: 'Position',
822         5: 'Refresh',
823         6: 'Size',
824         7: 'Timeout',
825         8: 'marquee_X',
826         9: 'marquee_Y',
827     }
828 VideoMarqueeOption.Color     = VideoMarqueeOption(2)
829 VideoMarqueeOption.Enable    = VideoMarqueeOption(0)
830 VideoMarqueeOption.Opacity   = VideoMarqueeOption(3)
831 VideoMarqueeOption.Position  = VideoMarqueeOption(4)
832 VideoMarqueeOption.Refresh   = VideoMarqueeOption(5)
833 VideoMarqueeOption.Size      = VideoMarqueeOption(6)
834 VideoMarqueeOption.Text      = VideoMarqueeOption(1)
835 VideoMarqueeOption.Timeout   = VideoMarqueeOption(7)
836 VideoMarqueeOption.marquee_X = VideoMarqueeOption(8)
837 VideoMarqueeOption.marquee_Y = VideoMarqueeOption(9)
838
839 class NavigateMode(_Enum):
840     '''Navigation mode.
841     '''
842     _enum_names_ = {
843         0: 'activate',
844         1: 'up',
845         2: 'down',
846         3: 'left',
847         4: 'right',
848         5: 'popup',
849     }
850 NavigateMode.activate = NavigateMode(0)
851 NavigateMode.down     = NavigateMode(2)
852 NavigateMode.left     = NavigateMode(3)
853 NavigateMode.popup    = NavigateMode(5)
854 NavigateMode.right    = NavigateMode(4)
855 NavigateMode.up       = NavigateMode(1)
856
857 class Position(_Enum):
858     '''Enumeration of values used to set position (e.g. of video title).
859     '''
860     _enum_names_ = {
861         -1: 'disable',
862         0: 'center',
863         1: 'left',
864         2: 'right',
865         3: 'top',
866         4: 'left',
867         5: 'right',
868         6: 'bottom',
869         7: 'left',
870         8: 'right',
871     }
872 Position.bottom  = Position(6)
873 Position.center  = Position(0)
874 Position.disable = Position(-1)
875 Position.left    = Position(1)
876 Position.left    = Position(4)
877 Position.left    = Position(7)
878 Position.right   = Position(2)
879 Position.right   = Position(5)
880 Position.right   = Position(8)
881 Position.top     = Position(3)
882
883 class TeletextKey(_Enum):
884     '''Enumeration of teletext keys than can be passed via
885 libvlc_video_set_teletext().
886     '''
887     _enum_names_ = {
888         7471104: 'red',
889         6750208: 'green',
890         7929856: 'yellow',
891         6422528: 'blue',
892         6881280: 'index',
893     }
894 TeletextKey.blue   = TeletextKey(6422528)
895 TeletextKey.green  = TeletextKey(6750208)
896 TeletextKey.index  = TeletextKey(6881280)
897 TeletextKey.red    = TeletextKey(7471104)
898 TeletextKey.yellow = TeletextKey(7929856)
899
900 class VideoEngine(_Enum):
901     '''Enumeration of the video engine to be used on output.
902 can be passed to @a libvlc_video_set_output_callbacks.
903     '''
904     _enum_names_ = {
905         0: 'opengl',
906         1: 'gles2',
907     }
908 VideoEngine.gles2  = VideoEngine(1)
909 VideoEngine.opengl = VideoEngine(0)
910
911 class VideoLogoOption(_Enum):
912     '''Option values for libvlc_video_{get,set}_logo_{int,string}.
913     '''
914     _enum_names_ = {
915         0: 'enable',
916         1: 'file',
917         2: 'logo_x',
918         3: 'logo_y',
919         4: 'delay',
920         5: 'repeat',
921         6: 'opacity',
922         7: 'position',
923     }
924 VideoLogoOption.delay    = VideoLogoOption(4)
925 VideoLogoOption.enable   = VideoLogoOption(0)
926 VideoLogoOption.file     = VideoLogoOption(1)
927 VideoLogoOption.logo_x   = VideoLogoOption(2)
928 VideoLogoOption.logo_y   = VideoLogoOption(3)
929 VideoLogoOption.opacity  = VideoLogoOption(6)
930 VideoLogoOption.position = VideoLogoOption(7)
931 VideoLogoOption.repeat   = VideoLogoOption(5)
932
933 class VideoAdjustOption(_Enum):
934     '''Option values for libvlc_video_{get,set}_adjust_{int,float,bool}.
935     '''
936     _enum_names_ = {
937         0: 'Enable',
938         1: 'Contrast',
939         2: 'Brightness',
940         3: 'Hue',
941         4: 'Saturation',
942         5: 'Gamma',
943     }
944 VideoAdjustOption.Brightness = VideoAdjustOption(2)
945 VideoAdjustOption.Contrast   = VideoAdjustOption(1)
946 VideoAdjustOption.Enable     = VideoAdjustOption(0)
947 VideoAdjustOption.Gamma      = VideoAdjustOption(5)
948 VideoAdjustOption.Hue        = VideoAdjustOption(3)
949 VideoAdjustOption.Saturation = VideoAdjustOption(4)
950
951 class AudioOutputDeviceTypes(_Enum):
952     '''Audio device types.
953     '''
954     _enum_names_ = {
955         -1: 'Error',
956         1: 'Mono',
957         2: 'Stereo',
958         4: '_2F2R',
959         5: '_3F2R',
960         6: '_5_1',
961         7: '_6_1',
962         8: '_7_1',
963         10: 'SPDIF',
964     }
965 AudioOutputDeviceTypes.Error  = AudioOutputDeviceTypes(-1)
966 AudioOutputDeviceTypes.Mono   = AudioOutputDeviceTypes(1)
967 AudioOutputDeviceTypes.SPDIF  = AudioOutputDeviceTypes(10)
968 AudioOutputDeviceTypes.Stereo = AudioOutputDeviceTypes(2)
969 AudioOutputDeviceTypes._2F2R  = AudioOutputDeviceTypes(4)
970 AudioOutputDeviceTypes._3F2R  = AudioOutputDeviceTypes(5)
971 AudioOutputDeviceTypes._5_1   = AudioOutputDeviceTypes(6)
972 AudioOutputDeviceTypes._6_1   = AudioOutputDeviceTypes(7)
973 AudioOutputDeviceTypes._7_1   = AudioOutputDeviceTypes(8)
974
975 class AudioOutputChannel(_Enum):
976     '''Audio channels.
977     '''
978     _enum_names_ = {
979         -1: 'Error',
980         1: 'Stereo',
981         2: 'RStereo',
982         3: 'Left',
983         4: 'Right',
984         5: 'Dolbys',
985     }
986 AudioOutputChannel.Dolbys  = AudioOutputChannel(5)
987 AudioOutputChannel.Error   = AudioOutputChannel(-1)
988 AudioOutputChannel.Left    = AudioOutputChannel(3)
989 AudioOutputChannel.RStereo = AudioOutputChannel(2)
990 AudioOutputChannel.Right   = AudioOutputChannel(4)
991 AudioOutputChannel.Stereo  = AudioOutputChannel(1)
992
993 class MediaPlayerRole(_Enum):
994     '''Media player roles.
995 \version libvlc 3.0.0 and later.
996 see \ref libvlc_media_player_set_role().
997     '''
998     _enum_names_ = {
999         0: '_None',
1000         1: 'Music',
1001         2: 'Video',
1002         3: 'Communication',
1003         4: 'Game',
1004         5: 'Notification',
1005         6: 'Animation',
1006         7: 'Production',
1007         8: 'Accessibility',
1008         9: 'Test',
1009     }
1010 MediaPlayerRole.Accessibility = MediaPlayerRole(8)
1011 MediaPlayerRole.Animation     = MediaPlayerRole(6)
1012 MediaPlayerRole.Communication = MediaPlayerRole(3)
1013 MediaPlayerRole.Game          = MediaPlayerRole(4)
1014 MediaPlayerRole.Music         = MediaPlayerRole(1)
1015 MediaPlayerRole.Notification  = MediaPlayerRole(5)
1016 MediaPlayerRole.Production    = MediaPlayerRole(7)
1017 MediaPlayerRole.Test          = MediaPlayerRole(9)
1018 MediaPlayerRole.Video         = MediaPlayerRole(2)
1019 MediaPlayerRole._None         = MediaPlayerRole(0)
1020
1021 class PlaybackMode(_Enum):
1022     '''Defines playback modes for playlist.
1023     '''
1024     _enum_names_ = {
1025         0: 'default',
1026         1: 'loop',
1027         2: 'repeat',
1028     }
1029 PlaybackMode.default = PlaybackMode(0)
1030 PlaybackMode.loop    = PlaybackMode(1)
1031 PlaybackMode.repeat  = PlaybackMode(2)
1032
1033 class Callback(ctypes.c_void_p):
1034     """Callback function notification.
1035     @param p_event: the event triggering the callback.
1036     """
1037     pass
1038 class LogCb(ctypes.c_void_p):
1039     """Callback prototype for LibVLC log message handler.
1040     @param data: data pointer as given to L{libvlc_log_set}().
1041     @param level: message level (@ref L{LogLevel}).
1042     @param ctx: message context (meta-information about the message).
1043     @param fmt: printf() format string (as defined by ISO C11).
1044     @param args: variable argument list for the format @note Log message handlers B{must} be thread-safe. @warning The message context pointer, the format string parameters and the variable arguments are only valid until the callback returns.
1045     """
1046     pass
1047 class MediaOpenCb(ctypes.c_void_p):
1048     """Callback prototype to open a custom bitstream input media.
1049     The same media item can be opened multiple times. Each time, this callback
1050     is invoked. It should allocate and initialize any instance-specific
1051     resources, then store them in *datap. The instance resources can be freed
1052     in the @ref libvlc_media_close_cb callback.
1053     @param opaque: private pointer as passed to L{libvlc_media_new_callbacks}().
1054     @return: datap storage space for a private data pointer, sizep byte length of the bitstream or UINT64_MAX if unknown.
1055     """
1056     pass
1057 class MediaReadCb(ctypes.c_void_p):
1058     """Callback prototype to read data from a custom bitstream input media.
1059     @param opaque: private pointer as set by the @ref libvlc_media_open_cb callback.
1060     @param buf: start address of the buffer to read data into.
1061     @param len: bytes length of the buffer.
1062     @return: strictly positive number of bytes read, 0 on end-of-stream, or -1 on non-recoverable error @note If no data is immediately available, then the callback should sleep. @warning The application is responsible for avoiding deadlock situations. In particular, the callback should return an error if playback is stopped; if it does not return, then L{libvlc_media_player_stop}() will never return.
1063     """
1064     pass
1065 class MediaSeekCb(ctypes.c_void_p):
1066     """Callback prototype to seek a custom bitstream input media.
1067     @param opaque: private pointer as set by the @ref libvlc_media_open_cb callback.
1068     @param offset: absolute byte offset to seek to.
1069     @return: 0 on success, -1 on error.
1070     """
1071     pass
1072 class MediaCloseCb(ctypes.c_void_p):
1073     """Callback prototype to close a custom bitstream input media.
1074     @param opaque: private pointer as set by the @ref libvlc_media_open_cb callback.
1075     """
1076     pass
1077 class VideoLockCb(ctypes.c_void_p):
1078     """Callback prototype to allocate and lock a picture buffer.
1079     Whenever a new video frame needs to be decoded, the lock callback is
1080     invoked. Depending on the video chroma, one or three pixel planes of
1081     adequate dimensions must be returned via the second parameter. Those
1082     planes must be aligned on 32-bytes boundaries.
1083     @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
1084     @param planes: start address of the pixel planes (LibVLC allocates the array of void pointers, this callback must initialize the array) [OUT].
1085     @return: a private pointer for the display and unlock callbacks to identify the picture buffers.
1086     """
1087     pass
1088 class VideoUnlockCb(ctypes.c_void_p):
1089     """Callback prototype to unlock a picture buffer.
1090     When the video frame decoding is complete, the unlock callback is invoked.
1091     This callback might not be needed at all. It is only an indication that the
1092     application can now read the pixel values if it needs to.
1093     @note: A picture buffer is unlocked after the picture is decoded,
1094     but before the picture is displayed.
1095     @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
1096     @param picture: private pointer returned from the @ref libvlc_video_lock_cb callback [IN].
1097     @param planes: pixel planes as defined by the @ref libvlc_video_lock_cb callback (this parameter is only for convenience) [IN].
1098     """
1099     pass
1100 class VideoDisplayCb(ctypes.c_void_p):
1101     """Callback prototype to display a picture.
1102     When the video frame needs to be shown, as determined by the media playback
1103     clock, the display callback is invoked.
1104     @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
1105     @param picture: private pointer returned from the @ref libvlc_video_lock_cb callback [IN].
1106     """
1107     pass
1108 class VideoFormatCb(ctypes.c_void_p):
1109     """Callback prototype to configure picture buffers format.
1110     This callback gets the format of the video as output by the video decoder
1111     and the chain of video filters (if any). It can opt to change any parameter
1112     as it needs. In that case, LibVLC will attempt to convert the video format
1113     (rescaling and chroma conversion) but these operations can be CPU intensive.
1114     @param opaque: pointer to the private pointer passed to L{libvlc_video_set_callbacks}() [IN/OUT].
1115     @param chroma: pointer to the 4 bytes video format identifier [IN/OUT].
1116     @param width: pointer to the pixel width [IN/OUT].
1117     @param height: pointer to the pixel height [IN/OUT].
1118     @param pitches: table of scanline pitches in bytes for each pixel plane (the table is allocated by LibVLC) [OUT].
1119     @return: lines table of scanlines count for each plane.
1120     """
1121     pass
1122 class VideoCleanupCb(ctypes.c_void_p):
1123     """Callback prototype to configure picture buffers format.
1124     @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() (and possibly modified by @ref libvlc_video_format_cb) [IN].
1125     """
1126     pass
1127 class VideoSetupCb(ctypes.c_void_p):
1128     """Callback prototype called to initialize user data.
1129     @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1130     @return: true on success.
1131     @version: LibVLC 4.0.0 or later.
1132     """
1133     pass
1134 class VideoCleanupCb(ctypes.c_void_p):
1135     """Callback prototype called to release user data.
1136     @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1137     @version: LibVLC 4.0.0 or later.
1138     """
1139     pass
1140 class VideoUpdateOutputCb(ctypes.c_void_p):
1141     """Callback prototype called on video size changes.
1142     @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1143     @param width: video width in pixel [IN].
1144     @param height: video height in pixel [IN].
1145     @version: LibVLC 4.0.0 or later.
1146     """
1147     pass
1148 class VideoSwapCb(ctypes.c_void_p):
1149     """Callback prototype called after performing drawing calls.
1150     @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1151     @version: LibVLC 4.0.0 or later.
1152     """
1153     pass
1154 class VideoMakecurrentCb(ctypes.c_void_p):
1155     """Callback prototype to set up the OpenGL context for rendering.
1156     @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1157     @param enter: true to set the context as current, false to unset it [IN].
1158     @return: true on success.
1159     @version: LibVLC 4.0.0 or later.
1160     """
1161     pass
1162 class VideoGetprocaddressCb(ctypes.c_void_p):
1163     """Callback prototype to load opengl functions.
1164     @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1165     @param fct_name: name of the opengl function to load.
1166     @return: a pointer to the named OpenGL function the None otherwise.
1167     @version: LibVLC 4.0.0 or later.
1168     """
1169     pass
1170 class AudioPlayCb(ctypes.c_void_p):
1171     """Callback prototype for audio playback.
1172     The LibVLC media player decodes and post-processes the audio signal
1173     asynchronously (in an internal thread). Whenever audio samples are ready
1174     to be queued to the output, this callback is invoked.
1175     The number of samples provided per invocation may depend on the file format,
1176     the audio coding algorithm, the decoder plug-in, the post-processing
1177     filters and timing. Application must not assume a certain number of samples.
1178     The exact format of audio samples is determined by L{libvlc_audio_set_format}()
1179     or L{libvlc_audio_set_format_callbacks}() as is the channels layout.
1180     Note that the number of samples is per channel. For instance, if the audio
1181     track sampling rate is 48000 Hz, then 1200 samples represent 25 milliseconds
1182     of audio signal - regardless of the number of audio channels.
1183     @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1184     @param samples: pointer to a table of audio samples to play back [IN].
1185     @param count: number of audio samples to play back.
1186     @param pts: expected play time stamp (see libvlc_delay()).
1187     """
1188     pass
1189 class AudioPauseCb(ctypes.c_void_p):
1190     """Callback prototype for audio pause.
1191     LibVLC invokes this callback to pause audio playback.
1192     @note: The pause callback is never called if the audio is already paused.
1193     @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1194     @param pts: time stamp of the pause request (should be elapsed already).
1195     """
1196     pass
1197 class AudioResumeCb(ctypes.c_void_p):
1198     """Callback prototype for audio resumption.
1199     LibVLC invokes this callback to resume audio playback after it was
1200     previously paused.
1201     @note: The resume callback is never called if the audio is not paused.
1202     @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1203     @param pts: time stamp of the resumption request (should be elapsed already).
1204     """
1205     pass
1206 class AudioFlushCb(ctypes.c_void_p):
1207     """Callback prototype for audio buffer flush.
1208     LibVLC invokes this callback if it needs to discard all pending buffers and
1209     stop playback as soon as possible. This typically occurs when the media is
1210     stopped.
1211     @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1212     """
1213     pass
1214 class AudioDrainCb(ctypes.c_void_p):
1215     """Callback prototype for audio buffer drain.
1216     LibVLC may invoke this callback when the decoded audio track is ending.
1217     There will be no further decoded samples for the track, but playback should
1218     nevertheless continue until all already pending buffers are rendered.
1219     @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1220     """
1221     pass
1222 class AudioSetVolumeCb(ctypes.c_void_p):
1223     """Callback prototype for audio volume change.
1224     @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1225     @param volume: software volume (1. = nominal, 0. = mute).
1226     @param mute: muted flag.
1227     """
1228     pass
1229 class AudioSetupCb(ctypes.c_void_p):
1230     """Callback prototype to setup the audio playback.
1231     This is called when the media player needs to create a new audio output.
1232     @param opaque: pointer to the data pointer passed to L{libvlc_audio_set_callbacks}() [IN/OUT].
1233     @param format: 4 bytes sample format [IN/OUT].
1234     @param rate: sample rate [IN/OUT].
1235     @param channels: channels count [IN/OUT].
1236     @return: 0 on success, anything else to skip audio playback.
1237     """
1238     pass
1239 class AudioCleanupCb(ctypes.c_void_p):
1240     """Callback prototype for audio playback cleanup.
1241     This is called when the media player no longer needs an audio output.
1242     @param opaque: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1243     """
1244     pass
1245 class CallbackDecorators(object):
1246     "Class holding various method decorators for callback functions."
1247     Callback = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p)
1248     Callback.__doc__ = '''Callback function notification.
1249         @param p_event: the event triggering the callback.
1250     '''
1251     LogCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int, Log_ptr, ctypes.c_char_p, ctypes.c_void_p)
1252     LogCb.__doc__ = '''Callback prototype for LibVLC log message handler.
1253         @param data: data pointer as given to L{libvlc_log_set}().
1254         @param level: message level (@ref L{LogLevel}).
1255         @param ctx: message context (meta-information about the message).
1256         @param fmt: printf() format string (as defined by ISO C11).
1257         @param args: variable argument list for the format @note Log message handlers B{must} be thread-safe. @warning The message context pointer, the format string parameters and the variable arguments are only valid until the callback returns.
1258     '''
1259     MediaOpenCb = ctypes.CFUNCTYPE(ctypes.POINTER(ctypes.c_int), ctypes.c_void_p, ctypes.POINTER(ctypes.c_void_p), ctypes.POINTER(ctypes.c_uint64))
1260     MediaOpenCb.__doc__ = '''Callback prototype to open a custom bitstream input media.
1261         The same media item can be opened multiple times. Each time, this callback
1262         is invoked. It should allocate and initialize any instance-specific
1263         resources, then store them in *datap. The instance resources can be freed
1264         in the @ref libvlc_media_close_cb callback.
1265         @param opaque: private pointer as passed to L{libvlc_media_new_callbacks}().
1266         @return: datap storage space for a private data pointer, sizep byte length of the bitstream or UINT64_MAX if unknown.
1267     '''
1268     MediaReadCb = ctypes.CFUNCTYPE(ctypes.POINTER(ctypes.c_ssize_t), ctypes.c_void_p, ctypes.c_char_p, ctypes.c_size_t)
1269     MediaReadCb.__doc__ = '''Callback prototype to read data from a custom bitstream input media.
1270         @param opaque: private pointer as set by the @ref libvlc_media_open_cb callback.
1271         @param buf: start address of the buffer to read data into.
1272         @param len: bytes length of the buffer.
1273         @return: strictly positive number of bytes read, 0 on end-of-stream, or -1 on non-recoverable error @note If no data is immediately available, then the callback should sleep. @warning The application is responsible for avoiding deadlock situations. In particular, the callback should return an error if playback is stopped; if it does not return, then L{libvlc_media_player_stop}() will never return.
1274     '''
1275     MediaSeekCb = ctypes.CFUNCTYPE(ctypes.POINTER(ctypes.c_int), ctypes.c_void_p, ctypes.c_uint64)
1276     MediaSeekCb.__doc__ = '''Callback prototype to seek a custom bitstream input media.
1277         @param opaque: private pointer as set by the @ref libvlc_media_open_cb callback.
1278         @param offset: absolute byte offset to seek to.
1279         @return: 0 on success, -1 on error.
1280     '''
1281     MediaCloseCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)
1282     MediaCloseCb.__doc__ = '''Callback prototype to close a custom bitstream input media.
1283         @param opaque: private pointer as set by the @ref libvlc_media_open_cb callback.
1284     '''
1285     VideoLockCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.POINTER(ctypes.c_void_p))
1286     VideoLockCb.__doc__ = '''Callback prototype to allocate and lock a picture buffer.
1287         Whenever a new video frame needs to be decoded, the lock callback is
1288         invoked. Depending on the video chroma, one or three pixel planes of
1289         adequate dimensions must be returned via the second parameter. Those
1290         planes must be aligned on 32-bytes boundaries.
1291         @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
1292         @param planes: start address of the pixel planes (LibVLC allocates the array of void pointers, this callback must initialize the array) [OUT].
1293         @return: a private pointer for the display and unlock callbacks to identify the picture buffers.
1294     '''
1295     VideoUnlockCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.POINTER(ctypes.c_void_p))
1296     VideoUnlockCb.__doc__ = '''Callback prototype to unlock a picture buffer.
1297         When the video frame decoding is complete, the unlock callback is invoked.
1298         This callback might not be needed at all. It is only an indication that the
1299         application can now read the pixel values if it needs to.
1300         @note: A picture buffer is unlocked after the picture is decoded,
1301         but before the picture is displayed.
1302         @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
1303         @param picture: private pointer returned from the @ref libvlc_video_lock_cb callback [IN].
1304         @param planes: pixel planes as defined by the @ref libvlc_video_lock_cb callback (this parameter is only for convenience) [IN].
1305     '''
1306     VideoDisplayCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p)
1307     VideoDisplayCb.__doc__ = '''Callback prototype to display a picture.
1308         When the video frame needs to be shown, as determined by the media playback
1309         clock, the display callback is invoked.
1310         @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
1311         @param picture: private pointer returned from the @ref libvlc_video_lock_cb callback [IN].
1312     '''
1313     VideoFormatCb = ctypes.CFUNCTYPE(ctypes.POINTER(ctypes.c_uint), ctypes.POINTER(ctypes.c_void_p), ctypes.c_char_p, ctypes.POINTER(ctypes.c_uint), ctypes.POINTER(ctypes.c_uint), ctypes.POINTER(ctypes.c_uint), ctypes.POINTER(ctypes.c_uint))
1314     VideoFormatCb.__doc__ = '''Callback prototype to configure picture buffers format.
1315         This callback gets the format of the video as output by the video decoder
1316         and the chain of video filters (if any). It can opt to change any parameter
1317         as it needs. In that case, LibVLC will attempt to convert the video format
1318         (rescaling and chroma conversion) but these operations can be CPU intensive.
1319         @param opaque: pointer to the private pointer passed to L{libvlc_video_set_callbacks}() [IN/OUT].
1320         @param chroma: pointer to the 4 bytes video format identifier [IN/OUT].
1321         @param width: pointer to the pixel width [IN/OUT].
1322         @param height: pointer to the pixel height [IN/OUT].
1323         @param pitches: table of scanline pitches in bytes for each pixel plane (the table is allocated by LibVLC) [OUT].
1324         @return: lines table of scanlines count for each plane.
1325     '''
1326     VideoCleanupCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)
1327     VideoCleanupCb.__doc__ = '''Callback prototype to configure picture buffers format.
1328         @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() (and possibly modified by @ref libvlc_video_format_cb) [IN].
1329     '''
1330     VideoSetupCb = ctypes.CFUNCTYPE(ctypes.POINTER(ctypes.c_bool), ctypes.c_void_p)
1331     VideoSetupCb.__doc__ = '''Callback prototype called to initialize user data.
1332         @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1333         @return: true on success.
1334         @version: LibVLC 4.0.0 or later.
1335     '''
1336     VideoCleanupCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)
1337     VideoCleanupCb.__doc__ = '''Callback prototype called to release user data.
1338         @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1339         @version: LibVLC 4.0.0 or later.
1340     '''
1341     VideoUpdateOutputCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint, ctypes.c_uint)
1342     VideoUpdateOutputCb.__doc__ = '''Callback prototype called on video size changes.
1343         @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1344         @param width: video width in pixel [IN].
1345         @param height: video height in pixel [IN].
1346         @version: LibVLC 4.0.0 or later.
1347     '''
1348     VideoSwapCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)
1349     VideoSwapCb.__doc__ = '''Callback prototype called after performing drawing calls.
1350         @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1351         @version: LibVLC 4.0.0 or later.
1352     '''
1353     VideoMakecurrentCb = ctypes.CFUNCTYPE(ctypes.POINTER(ctypes.c_bool), ctypes.c_void_p, ctypes.c_bool)
1354     VideoMakecurrentCb.__doc__ = '''Callback prototype to set up the OpenGL context for rendering.
1355         @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1356         @param enter: true to set the context as current, false to unset it [IN].
1357         @return: true on success.
1358         @version: LibVLC 4.0.0 or later.
1359     '''
1360     VideoGetprocaddressCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_char_p)
1361     VideoGetprocaddressCb.__doc__ = '''Callback prototype to load opengl functions.
1362         @param opaque: private pointer passed to the @a L{libvlc_video_set_output_callbacks}() [IN].
1363         @param fct_name: name of the opengl function to load.
1364         @return: a pointer to the named OpenGL function the None otherwise.
1365         @version: LibVLC 4.0.0 or later.
1366     '''
1367     AudioPlayCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint, ctypes.c_int64)
1368     AudioPlayCb.__doc__ = '''Callback prototype for audio playback.
1369         The LibVLC media player decodes and post-processes the audio signal
1370         asynchronously (in an internal thread). Whenever audio samples are ready
1371         to be queued to the output, this callback is invoked.
1372         The number of samples provided per invocation may depend on the file format,
1373         the audio coding algorithm, the decoder plug-in, the post-processing
1374         filters and timing. Application must not assume a certain number of samples.
1375         The exact format of audio samples is determined by L{libvlc_audio_set_format}()
1376         or L{libvlc_audio_set_format_callbacks}() as is the channels layout.
1377         Note that the number of samples is per channel. For instance, if the audio
1378         track sampling rate is 48000 Hz, then 1200 samples represent 25 milliseconds
1379         of audio signal - regardless of the number of audio channels.
1380         @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1381         @param samples: pointer to a table of audio samples to play back [IN].
1382         @param count: number of audio samples to play back.
1383         @param pts: expected play time stamp (see libvlc_delay()).
1384     '''
1385     AudioPauseCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int64)
1386     AudioPauseCb.__doc__ = '''Callback prototype for audio pause.
1387         LibVLC invokes this callback to pause audio playback.
1388         @note: The pause callback is never called if the audio is already paused.
1389         @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1390         @param pts: time stamp of the pause request (should be elapsed already).
1391     '''
1392     AudioResumeCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int64)
1393     AudioResumeCb.__doc__ = '''Callback prototype for audio resumption.
1394         LibVLC invokes this callback to resume audio playback after it was
1395         previously paused.
1396         @note: The resume callback is never called if the audio is not paused.
1397         @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1398         @param pts: time stamp of the resumption request (should be elapsed already).
1399     '''
1400     AudioFlushCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int64)
1401     AudioFlushCb.__doc__ = '''Callback prototype for audio buffer flush.
1402         LibVLC invokes this callback if it needs to discard all pending buffers and
1403         stop playback as soon as possible. This typically occurs when the media is
1404         stopped.
1405         @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1406     '''
1407     AudioDrainCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)
1408     AudioDrainCb.__doc__ = '''Callback prototype for audio buffer drain.
1409         LibVLC may invoke this callback when the decoded audio track is ending.
1410         There will be no further decoded samples for the track, but playback should
1411         nevertheless continue until all already pending buffers are rendered.
1412         @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1413     '''
1414     AudioSetVolumeCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_float, ctypes.c_bool)
1415     AudioSetVolumeCb.__doc__ = '''Callback prototype for audio volume change.
1416         @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1417         @param volume: software volume (1. = nominal, 0. = mute).
1418         @param mute: muted flag.
1419     '''
1420     AudioSetupCb = ctypes.CFUNCTYPE(ctypes.POINTER(ctypes.c_int), ctypes.POINTER(ctypes.c_void_p), ctypes.c_char_p, ctypes.POINTER(ctypes.c_uint), ctypes.POINTER(ctypes.c_uint))
1421     AudioSetupCb.__doc__ = '''Callback prototype to setup the audio playback.
1422         This is called when the media player needs to create a new audio output.
1423         @param opaque: pointer to the data pointer passed to L{libvlc_audio_set_callbacks}() [IN/OUT].
1424         @param format: 4 bytes sample format [IN/OUT].
1425         @param rate: sample rate [IN/OUT].
1426         @param channels: channels count [IN/OUT].
1427         @return: 0 on success, anything else to skip audio playback.
1428     '''
1429     AudioCleanupCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)
1430     AudioCleanupCb.__doc__ = '''Callback prototype for audio playback cleanup.
1431         This is called when the media player no longer needs an audio output.
1432         @param opaque: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1433     '''
1434 cb = CallbackDecorators
1435  # End of generated enum types #
1436
1437  # From libvlc_structures.h
1438
1439 class AudioOutput(_Cstruct):
1440
1441     def __str__(self):
1442         return '%s(%s:%s)' % (self.__class__.__name__, self.name, self.description)
1443
1444 AudioOutput._fields_ = [  # recursive struct
1445     ('name',        ctypes.c_char_p),
1446     ('description', ctypes.c_char_p),
1447     ('next',        ctypes.POINTER(AudioOutput)),
1448     ]
1449
1450 class LogMessage(_Cstruct):
1451     _fields_ = [
1452         ('size',     ctypes.c_uint  ),
1453         ('severity', ctypes.c_int   ),
1454         ('type',     ctypes.c_char_p),
1455         ('name',     ctypes.c_char_p),
1456         ('header',   ctypes.c_char_p),
1457         ('message',  ctypes.c_char_p),
1458     ]
1459
1460     def __init__(self):
1461         super(LogMessage, self).__init__()
1462         self.size = ctypes.sizeof(self)
1463
1464     def __str__(self):
1465         return '%s(%d:%s): %s' % (self.__class__.__name__, self.severity, self.type, self.message)
1466
1467 class MediaEvent(_Cstruct):
1468     _fields_ = [
1469         ('media_name',    ctypes.c_char_p),
1470         ('instance_name', ctypes.c_char_p),
1471     ]
1472
1473 class MediaStats(_Cstruct):
1474     _fields_ = [
1475         ('read_bytes',          ctypes.c_int  ),
1476         ('input_bitrate',       ctypes.c_float),
1477         ('demux_read_bytes',    ctypes.c_int  ),
1478         ('demux_bitrate',       ctypes.c_float),
1479         ('demux_corrupted',     ctypes.c_int  ),
1480         ('demux_discontinuity', ctypes.c_int  ),
1481         ('decoded_video',       ctypes.c_int  ),
1482         ('decoded_audio',       ctypes.c_int  ),
1483         ('displayed_pictures',  ctypes.c_int  ),
1484         ('lost_pictures',       ctypes.c_int  ),
1485         ('played_abuffers',     ctypes.c_int  ),
1486         ('lost_abuffers',       ctypes.c_int  ),
1487         ('sent_packets',        ctypes.c_int  ),
1488         ('sent_bytes',          ctypes.c_int  ),
1489         ('send_bitrate',        ctypes.c_float),
1490     ]
1491
1492 class MediaTrackInfo(_Cstruct):
1493     _fields_ = [
1494         ('codec',              ctypes.c_uint32),
1495         ('id',                 ctypes.c_int   ),
1496         ('type',               TrackType      ),
1497         ('profile',            ctypes.c_int   ),
1498         ('level',              ctypes.c_int   ),
1499         ('channels_or_height', ctypes.c_uint  ),
1500         ('rate_or_width',      ctypes.c_uint  ),
1501     ]
1502
1503 class AudioTrack(_Cstruct):
1504     _fields_ = [
1505         ('channels', ctypes.c_uint),
1506         ('rate', ctypes.c_uint),
1507         ]
1508
1509 class VideoTrack(_Cstruct):
1510     _fields_ = [
1511         ('height', ctypes.c_uint),
1512         ('width', ctypes.c_uint),
1513         ('sar_num', ctypes.c_uint),
1514         ('sar_den', ctypes.c_uint),
1515         ('frame_rate_num', ctypes.c_uint),
1516         ('frame_rate_den', ctypes.c_uint),
1517         ]
1518
1519 class SubtitleTrack(_Cstruct):
1520     _fields_ = [
1521         ('encoding', ctypes.c_char_p),
1522         ]
1523
1524 class MediaTrackTracks(ctypes.Union):
1525     _fields_ = [
1526         ('audio', ctypes.POINTER(AudioTrack)),
1527         ('video', ctypes.POINTER(VideoTrack)),
1528         ('subtitle', ctypes.POINTER(SubtitleTrack)),
1529         ]
1530
1531 class MediaTrack(_Cstruct):
1532     _anonymous_ = ("u",)
1533     _fields_ = [
1534         ('codec',              ctypes.c_uint32),
1535         ('original_fourcc',    ctypes.c_uint32),
1536         ('id',                 ctypes.c_int   ),
1537         ('type',               TrackType      ),
1538         ('profile',            ctypes.c_int   ),
1539         ('level',              ctypes.c_int   ),
1540
1541         ('u',                  MediaTrackTracks),
1542         ('bitrate',            ctypes.c_uint),
1543         ('language',           ctypes.c_char_p),
1544         ('description',        ctypes.c_char_p),
1545         ]
1546
1547 class PlaylistItem(_Cstruct):
1548     _fields_ = [
1549         ('id',   ctypes.c_int   ),
1550         ('uri',  ctypes.c_char_p),
1551         ('name', ctypes.c_char_p),
1552     ]
1553
1554     def __str__(self):
1555         return '%s #%d %s (uri %s)' % (self.__class__.__name__, self.id, self.name, self.uri)
1556
1557 class Position(object):
1558     """Enum-like, immutable window position constants.
1559
1560        See e.g. VideoMarqueeOption.Position.
1561     """
1562     Center       = 0
1563     Left         = 1
1564     CenterLeft   = 1
1565     Right        = 2
1566     CenterRight  = 2
1567     Top          = 4
1568     TopCenter    = 4
1569     TopLeft      = 5
1570     TopRight     = 6
1571     Bottom       = 8
1572     BottomCenter = 8
1573     BottomLeft   = 9
1574     BottomRight  = 10
1575     def __init__(self, *unused):
1576         raise TypeError('constants only')
1577     def __setattr__(self, *unused):  #PYCHOK expected
1578         raise TypeError('immutable constants')
1579
1580 class Rectangle(_Cstruct):
1581     _fields_ = [
1582         ('top',    ctypes.c_int),
1583         ('left',   ctypes.c_int),
1584         ('bottom', ctypes.c_int),
1585         ('right',  ctypes.c_int),
1586     ]
1587
1588 class TrackDescription(_Cstruct):
1589
1590     def __str__(self):
1591         return '%s(%d:%s)' % (self.__class__.__name__, self.id, self.name)
1592
1593 TrackDescription._fields_ = [  # recursive struct
1594     ('id',   ctypes.c_int   ),
1595     ('name', ctypes.c_char_p),
1596     ('next', ctypes.POINTER(TrackDescription)),
1597     ]
1598
1599 def track_description_list(head):
1600     """Convert a TrackDescription linked list to a Python list (and release the former).
1601     """
1602     r = []
1603     if head:
1604         item = head
1605         while item:
1606             item = item.contents
1607             r.append((item.id, item.name))
1608             item = item.next
1609         try:
1610             libvlc_track_description_release(head)
1611         except NameError:
1612             libvlc_track_description_list_release(head)
1613
1614     return r
1615
1616 class EventUnion(ctypes.Union):
1617     _fields_ = [
1618         ('meta_type',    ctypes.c_uint    ),
1619         ('new_child',    ctypes.c_uint    ),
1620         ('new_duration', ctypes.c_longlong),
1621         ('new_status',   ctypes.c_int     ),
1622         ('media',        ctypes.c_void_p  ),
1623         ('new_state',    ctypes.c_uint    ),
1624         # FIXME: Media instance
1625         ('new_cache', ctypes.c_float   ),
1626         ('new_position', ctypes.c_float   ),
1627         ('new_time',     ctypes.c_longlong),
1628         ('new_title',    ctypes.c_int     ),
1629         ('new_seekable', ctypes.c_longlong),
1630         ('new_pausable', ctypes.c_longlong),
1631         ('new_scrambled', ctypes.c_longlong),
1632         ('new_count', ctypes.c_longlong),
1633         # FIXME: Skipped MediaList and MediaListView...
1634         ('filename',     ctypes.c_char_p  ),
1635         ('new_length',   ctypes.c_longlong),
1636         ('media_event',  MediaEvent       ),
1637     ]
1638
1639 class Event(_Cstruct):
1640     _fields_ = [
1641         ('type',   EventType      ),
1642         ('object', ctypes.c_void_p),
1643         ('u',      EventUnion     ),
1644     ]
1645
1646 class ModuleDescription(_Cstruct):
1647
1648     def __str__(self):
1649         return '%s %s (%s)' % (self.__class__.__name__, self.shortname, self.name)
1650
1651 ModuleDescription._fields_ = [  # recursive struct
1652     ('name',      ctypes.c_char_p),
1653     ('shortname', ctypes.c_char_p),
1654     ('longname',  ctypes.c_char_p),
1655     ('help',      ctypes.c_char_p),
1656     ('next',      ctypes.POINTER(ModuleDescription)),
1657     ]
1658
1659 def module_description_list(head):
1660     """Convert a ModuleDescription linked list to a Python list (and release the former).
1661     """
1662     r = []
1663     if head:
1664         item = head
1665         while item:
1666             item = item.contents
1667             r.append((item.name, item.shortname, item.longname, item.help))
1668             item = item.next
1669         libvlc_module_description_list_release(head)
1670     return r
1671
1672 class AudioOutputDevice(_Cstruct):
1673
1674     def __str__(self):
1675         return '%s(%d:%s)' % (self.__class__.__name__, self.id, self.name)
1676
1677 AudioOutputDevice._fields_ = [  # recursive struct
1678     ('next', ctypes.POINTER(AudioOutputDevice)),
1679     ('device',   ctypes.c_char_p   ),
1680     ('description', ctypes.c_char_p),
1681     ]
1682
1683 class TitleDescription(_Cstruct):
1684     _fields_ = [
1685         ('duration', ctypes.c_longlong),
1686         ('name', ctypes.c_char_p),
1687         ('menu', ctypes.c_bool),
1688     ]
1689
1690 class ChapterDescription(_Cstruct):
1691     _fields_ = [
1692         ('time_offset', ctypes.c_longlong),
1693         ('duration', ctypes.c_longlong),
1694         ('name', ctypes.c_char_p),
1695     ]
1696
1697 class VideoViewpoint(_Cstruct):
1698     _fields_ = [
1699         ('yaw', ctypes.c_float),
1700         ('pitch', ctypes.c_float),
1701         ('roll', ctypes.c_float),
1702         ('field_of_view', ctypes.c_float),
1703     ]
1704
1705 class MediaDiscovererDescription(_Cstruct):
1706     _fields_ = [
1707         ('name', ctypes.c_char_p),
1708         ('longname', ctypes.c_char_p),
1709         ('cat', MediaDiscovererCategory),
1710     ]
1711
1712     def __str__(self):
1713         return '%s %s (%d) - %s' % (self.__class__.__name__, self.name, self.cat, self.longname)
1714
1715 # This struct depends on the MediaSlaveType enum that is defined only
1716 # in > 2.2
1717 if 'MediaSlaveType' in locals():
1718     class MediaSlave(_Cstruct):
1719         _fields_ = [
1720             ('psz_uri', ctypes.c_char_p),
1721             ('i_type', MediaSlaveType),
1722             ('i_priority', ctypes.c_uint)
1723         ]
1724
1725 class RDDescription(_Cstruct):
1726     _fields_ = [
1727         ('name', ctypes.c_char_p),
1728         ('longname', ctypes.c_char_p)
1729     ]
1730
1731
1732 class MediaThumbnailRequest:
1733     def __new__(cls, *args):
1734         if len(args) == 1 and isinstance(args[0], _Ints):
1735             return _Constructor(cls, args[0])
1736
1737 # End of header.py #
1738 class AudioEqualizer(_Ctype):
1739     '''Create a new default equalizer, with all frequency values zeroed.
1740
1741     The new equalizer can subsequently be applied to a media player by invoking
1742     L{MediaPlayer.set_equalizer}.
1743     The returned handle should be freed via libvlc_audio_equalizer_release() when
1744     it is no longer needed.
1745     '''
1746
1747     def __new__(cls, *args):
1748         if len(args) == 1 and isinstance(args[0], _Ints):
1749             return _Constructor(cls, args[0])
1750         return libvlc_audio_equalizer_new()
1751
1752
1753     def release(self):
1754         '''Release a previously created equalizer instance.
1755         The equalizer was previously created by using L{new}() or
1756         L{new_from_preset}().
1757         It is safe to invoke this method with a None p_equalizer parameter for no effect.
1758         @version: LibVLC 2.2.0 or later.
1759         '''
1760         return libvlc_audio_equalizer_release(self)
1761
1762
1763     def set_preamp(self, f_preamp):
1764         '''Set a new pre-amplification value for an equalizer.
1765         The new equalizer settings are subsequently applied to a media player by invoking
1766         L{media_player_set_equalizer}().
1767         The supplied amplification value will be clamped to the -20.0 to +20.0 range.
1768         @param f_preamp: preamp value (-20.0 to 20.0 Hz).
1769         @return: zero on success, -1 on error.
1770         @version: LibVLC 2.2.0 or later.
1771         '''
1772         return libvlc_audio_equalizer_set_preamp(self, f_preamp)
1773
1774
1775     def get_preamp(self):
1776         '''Get the current pre-amplification value from an equalizer.
1777         @return: preamp value (Hz).
1778         @version: LibVLC 2.2.0 or later.
1779         '''
1780         return libvlc_audio_equalizer_get_preamp(self)
1781
1782
1783     def set_amp_at_index(self, f_amp, u_band):
1784         '''Set a new amplification value for a particular equalizer frequency band.
1785         The new equalizer settings are subsequently applied to a media player by invoking
1786         L{media_player_set_equalizer}().
1787         The supplied amplification value will be clamped to the -20.0 to +20.0 range.
1788         @param f_amp: amplification value (-20.0 to 20.0 Hz).
1789         @param u_band: index, counting from zero, of the frequency band to set.
1790         @return: zero on success, -1 on error.
1791         @version: LibVLC 2.2.0 or later.
1792         '''
1793         return libvlc_audio_equalizer_set_amp_at_index(self, f_amp, u_band)
1794
1795
1796     def get_amp_at_index(self, u_band):
1797         '''Get the amplification value for a particular equalizer frequency band.
1798         @param u_band: index, counting from zero, of the frequency band to get.
1799         @return: amplification value (Hz); NaN if there is no such frequency band.
1800         @version: LibVLC 2.2.0 or later.
1801         '''
1802         return libvlc_audio_equalizer_get_amp_at_index(self, u_band)
1803
1804 class EventManager(_Ctype):
1805     '''Create an event manager with callback handler.
1806
1807     This class interposes the registration and handling of
1808     event notifications in order to (a) remove the need for
1809     decorating each callback functions with the decorator
1810     '@callbackmethod', (b) allow any number of positional
1811     and/or keyword arguments to the callback (in addition
1812     to the Event instance) and (c) to preserve the Python
1813     objects such that the callback and argument objects
1814     remain alive (i.e. are not garbage collected) until
1815     B{after} the notification has been unregistered.
1816
1817     @note: Only a single notification can be registered
1818     for each event type in an EventManager instance.
1819     
1820     '''
1821
1822     _callback_handler = None
1823     _callbacks = {}
1824
1825     def __new__(cls, ptr=_internal_guard):
1826         if ptr == _internal_guard:
1827             raise VLCException("(INTERNAL) ctypes class.\nYou should get a reference to EventManager through the MediaPlayer.event_manager() method.")
1828         return _Constructor(cls, ptr)
1829
1830     def event_attach(self, eventtype, callback, *args, **kwds):
1831         """Register an event notification.
1832
1833         @param eventtype: the desired event type to be notified about.
1834         @param callback: the function to call when the event occurs.
1835         @param args: optional positional arguments for the callback.
1836         @param kwds: optional keyword arguments for the callback.
1837         @return: 0 on success, ENOMEM on error.
1838
1839         @note: The callback function must have at least one argument,
1840         an Event instance.  Any other, optional positional and keyword
1841         arguments are in B{addition} to the first one.
1842         """
1843         if not isinstance(eventtype, EventType):
1844             raise VLCException("%s required: %r" % ('EventType', eventtype))
1845         if not hasattr(callback, '__call__'):  # callable()
1846             raise VLCException("%s required: %r" % ('callable', callback))
1847          # check that the callback expects arguments
1848         if not any(getargspec(callback)[:2]):  # list(...)
1849             raise VLCException("%s required: %r" % ('argument', callback))
1850
1851         if self._callback_handler is None:
1852             _called_from_ctypes = ctypes.CFUNCTYPE(None, ctypes.POINTER(Event), ctypes.c_void_p)
1853             @_called_from_ctypes
1854             def _callback_handler(event, k):
1855                 """(INTERNAL) handle callback call from ctypes.
1856
1857                 @note: We cannot simply make this an EventManager
1858                 method since ctypes does not prepend self as the
1859                 first parameter, hence this closure.
1860                 """
1861                 try: # retrieve Python callback and arguments
1862                     call, args, kwds = self._callbacks[k]
1863                      # deref event.contents to simplify callback code
1864                     call(event.contents, *args, **kwds)
1865                 except KeyError:  # detached?
1866                     pass
1867             self._callback_handler = _callback_handler
1868             self._callbacks = {}
1869
1870         k = eventtype.value
1871         r = libvlc_event_attach(self, k, self._callback_handler, k)
1872         if not r:
1873             self._callbacks[k] = (callback, args, kwds)
1874         return r
1875
1876     def event_detach(self, eventtype):
1877         """Unregister an event notification.
1878
1879         @param eventtype: the event type notification to be removed.
1880         """
1881         if not isinstance(eventtype, EventType):
1882             raise VLCException("%s required: %r" % ('EventType', eventtype))
1883
1884         k = eventtype.value
1885         if k in self._callbacks:
1886             del self._callbacks[k] # remove, regardless of libvlc return value
1887             libvlc_event_detach(self, k, self._callback_handler, k)
1888
1889
1890 class Instance(_Ctype):
1891     '''Create a new Instance instance.
1892
1893     It may take as parameter either:
1894       - a string
1895       - a list of strings as first parameters
1896       - the parameters given as the constructor parameters (must be strings)
1897     
1898     '''
1899
1900     def __new__(cls, *args):
1901         if len(args) == 1:
1902             # Only 1 arg. It is either a C pointer, or an arg string,
1903             # or a tuple.
1904             i = args[0]
1905             if isinstance(i, _Ints):
1906                 return _Constructor(cls, i)
1907             elif isinstance(i, basestring):
1908                 args = i.strip().split()
1909             elif isinstance(i, _Seqs):
1910                 args = list(i)
1911             else:
1912                 raise VLCException('Instance %r' % (args,))
1913         else:
1914             args = list(args)
1915
1916         if not args:  # no parameters passed
1917             args = ['vlc']
1918         elif args[0] != 'vlc':
1919             args.insert(0, 'vlc')
1920
1921         if plugin_path is not None:
1922             # set plugin_path if detected, win32 and MacOS,
1923             # if the user did not specify it itself.
1924             os.environ.setdefault('VLC_PLUGIN_PATH', plugin_path)
1925
1926         if PYTHON3:
1927             args = [ str_to_bytes(a) for a in args ]
1928         return libvlc_new(len(args), args)
1929
1930     def media_player_new(self, uri=None):
1931         """Create a new MediaPlayer instance.
1932
1933         @param uri: an optional URI to play in the player.
1934         """
1935         p = libvlc_media_player_new(self)
1936         if uri:
1937             p.set_media(self.media_new(uri))
1938         p._instance = self
1939         return p
1940
1941     def media_list_player_new(self):
1942         """Create a new MediaListPlayer instance.
1943         """
1944         p = libvlc_media_list_player_new(self)
1945         p._instance = self
1946         return p
1947
1948     def media_new(self, mrl, *options):
1949         """Create a new Media instance.
1950
1951         If mrl contains a colon (:) preceded by more than 1 letter, it
1952         will be treated as a URL. Else, it will be considered as a
1953         local path. If you need more control, directly use
1954         media_new_location/media_new_path methods.
1955
1956         Options can be specified as supplementary string parameters,
1957         but note that many options cannot be set at the media level,
1958         and rather at the Instance level. For instance, the marquee
1959         filter must be specified when creating the vlc.Instance or
1960         vlc.MediaPlayer.
1961
1962         Alternatively, options can be added to the media using the
1963         Media.add_options method (with the same limitation).
1964
1965         @param options: optional media option=value strings
1966         """
1967         if ':' in mrl and mrl.index(':') > 1:
1968             # Assume it is a URL
1969             m = libvlc_media_new_location(self, str_to_bytes(mrl))
1970         else:
1971             # Else it should be a local path.
1972             m = libvlc_media_new_path(self, str_to_bytes(os.path.normpath(mrl)))
1973         for o in options:
1974             libvlc_media_add_option(m, str_to_bytes(o))
1975         m._instance = self
1976         return m
1977
1978     def media_list_new(self, mrls=None):
1979         """Create a new MediaList instance.
1980         @param mrls: optional list of MRL strings
1981         """
1982         l = libvlc_media_list_new(self)
1983         # We should take the lock, but since we did not leak the
1984         # reference, nobody else can access it.
1985         if mrls:
1986             for m in mrls:
1987                 l.add_media(m)
1988         l._instance = self
1989         return l
1990
1991     def audio_output_enumerate_devices(self):
1992         """Enumerate the defined audio output devices.
1993
1994         @return: list of dicts {name:, description:, devices:}
1995         """
1996         r = []
1997         head = libvlc_audio_output_list_get(self)
1998         if head:
1999             i = head
2000             while i:
2001                 i = i.contents
2002                 r.append({'name': i.name, 'description': i.description})
2003                 i = i.next
2004             libvlc_audio_output_list_release(head)
2005         return r
2006
2007     def audio_filter_list_get(self):
2008         """Returns a list of available audio filters.
2009
2010         """
2011         return module_description_list(libvlc_audio_filter_list_get(self))
2012
2013     def video_filter_list_get(self):
2014         """Returns a list of available video filters.
2015
2016         """
2017         return module_description_list(libvlc_video_filter_list_get(self))
2018
2019
2020
2021     def release(self):
2022         '''Decrement the reference count of a libvlc instance, and destroy it
2023         if it reaches zero.
2024         '''
2025         return libvlc_release(self)
2026
2027
2028     def retain(self):
2029         '''Increments the reference count of a libvlc instance.
2030         The initial reference count is 1 after L{new}() returns.
2031         '''
2032         return libvlc_retain(self)
2033
2034
2035     def add_intf(self, name):
2036         '''Try to start a user interface for the libvlc instance.
2037         @param name: interface name, or None for default.
2038         @return: 0 on success, -1 on error.
2039         '''
2040         return libvlc_add_intf(self, str_to_bytes(name))
2041
2042
2043     def set_user_agent(self, name, http):
2044         '''Sets the application name. LibVLC passes this as the user agent string
2045         when a protocol requires it.
2046         @param name: human-readable application name, e.g. "FooBar player 1.2.3".
2047         @param http: HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0".
2048         @version: LibVLC 1.1.1 or later.
2049         '''
2050         return libvlc_set_user_agent(self, str_to_bytes(name), str_to_bytes(http))
2051
2052
2053     def set_app_id(self, id, version, icon):
2054         '''Sets some meta-information about the application.
2055         See also L{set_user_agent}().
2056         @param id: Java-style application identifier, e.g. "com.acme.foobar".
2057         @param version: application version numbers, e.g. "1.2.3".
2058         @param icon: application icon name, e.g. "foobar".
2059         @version: LibVLC 2.1.0 or later.
2060         '''
2061         return libvlc_set_app_id(self, str_to_bytes(id), str_to_bytes(version), str_to_bytes(icon))
2062
2063
2064     def log_unset(self):
2065         '''Unsets the logging callback.
2066         This function deregisters the logging callback for a LibVLC instance.
2067         This is rarely needed as the callback is implicitly unset when the instance
2068         is destroyed.
2069         @note: This function will wait for any pending callbacks invocation to
2070         complete (causing a deadlock if called from within the callback).
2071         @version: LibVLC 2.1.0 or later.
2072         '''
2073         return libvlc_log_unset(self)
2074
2075
2076     def log_set(self, cb, data):
2077         '''Sets the logging callback for a LibVLC instance.
2078         This function is thread-safe: it will wait for any pending callbacks
2079         invocation to complete.
2080         @param data: opaque data pointer for the callback function @note Some log messages (especially debug) are emitted by LibVLC while is being initialized. These messages cannot be captured with this interface. @warning A deadlock may occur if this function is called from the callback.
2081         @param p_instance: libvlc instance.
2082         @version: LibVLC 2.1.0 or later.
2083         '''
2084         return libvlc_log_set(self, cb, data)
2085
2086
2087     def log_set_file(self, stream):
2088         '''Sets up logging to a file.
2089         @param stream: FILE pointer opened for writing (the FILE pointer must remain valid until L{log_unset}()).
2090         @version: LibVLC 2.1.0 or later.
2091         '''
2092         return libvlc_log_set_file(self, stream)
2093
2094
2095     def media_discoverer_new(self, psz_name):
2096         '''Create a media discoverer object by name.
2097         After this object is created, you should attach to media_list events in
2098         order to be notified of new items discovered.
2099         You need to call L{media_discoverer_start}() in order to start the
2100         discovery.
2101         See L{media_discoverer_media_list}
2102         See libvlc_media_discoverer_event_manager
2103         See L{media_discoverer_start}.
2104         @param psz_name: service name; use L{media_discoverer_list_get}() to get a list of the discoverer names available in this libVLC instance.
2105         @return: media discover object or None in case of error.
2106         @version: LibVLC 3.0.0 or later.
2107         '''
2108         return libvlc_media_discoverer_new(self, str_to_bytes(psz_name))
2109
2110
2111     def media_discoverer_list_get(self, i_cat, ppp_services):
2112         '''Get media discoverer services by category.
2113         @param i_cat: category of services to fetch.
2114         @param ppp_services: address to store an allocated array of media discoverer services (must be freed with L{media_discoverer_list_release}() by the caller) [OUT].
2115         @return: the number of media discoverer services (0 on error).
2116         @version: LibVLC 3.0.0 and later.
2117         '''
2118         return libvlc_media_discoverer_list_get(self, i_cat, ppp_services)
2119
2120
2121     def media_library_new(self):
2122         '''Create an new Media Library object.
2123         @return: a new object or None on error.
2124         '''
2125         return libvlc_media_library_new(self)
2126
2127
2128     def media_new_location(self, psz_mrl):
2129         '''Create a media with a certain given media resource location,
2130         for instance a valid URL.
2131         @note: To refer to a local file with this function,
2132         the file://... URI syntax B{must} be used (see IETF RFC3986).
2133         We recommend using L{media_new_path}() instead when dealing with
2134         local files.
2135         See L{media_release}.
2136         @param psz_mrl: the media location.
2137         @return: the newly created media or None on error.
2138         '''
2139         return libvlc_media_new_location(self, str_to_bytes(psz_mrl))
2140
2141
2142     def media_new_path(self, path):
2143         '''Create a media for a certain file path.
2144         See L{media_release}.
2145         @param path: local filesystem path.
2146         @return: the newly created media or None on error.
2147         '''
2148         return libvlc_media_new_path(self, str_to_bytes(path))
2149
2150
2151     def media_new_fd(self, fd):
2152         '''Create a media for an already open file descriptor.
2153         The file descriptor shall be open for reading (or reading and writing).
2154         Regular file descriptors, pipe read descriptors and character device
2155         descriptors (including TTYs) are supported on all platforms.
2156         Block device descriptors are supported where available.
2157         Directory descriptors are supported on systems that provide fdopendir().
2158         Sockets are supported on all platforms where they are file descriptors,
2159         i.e. all except Windows.
2160         @note: This library will B{not} automatically close the file descriptor
2161         under any circumstance. Nevertheless, a file descriptor can usually only be
2162         rendered once in a media player. To render it a second time, the file
2163         descriptor should probably be rewound to the beginning with lseek().
2164         See L{media_release}.
2165         @param fd: open file descriptor.
2166         @return: the newly created media or None on error.
2167         @version: LibVLC 1.1.5 and later.
2168         '''
2169         return libvlc_media_new_fd(self, fd)
2170
2171
2172     def media_new_callbacks(self, open_cb, read_cb, seek_cb, close_cb, opaque):
2173         '''Create a media with custom callbacks to read the data from.
2174         @param open_cb: callback to open the custom bitstream input media.
2175         @param read_cb: callback to read data (must not be None).
2176         @param seek_cb: callback to seek, or None if seeking is not supported.
2177         @param close_cb: callback to close the media, or None if unnecessary.
2178         @param opaque: data pointer for the open callback.
2179         @return: the newly created media or None on error @note If open_cb is None, the opaque pointer will be passed to read_cb, seek_cb and close_cb, and the stream size will be treated as unknown. @note The callbacks may be called asynchronously (from another thread). A single stream instance need not be reentrant. However the open_cb needs to be reentrant if the media is used by multiple player instances. @warning The callbacks may be used until all or any player instances that were supplied the media item are stopped. See L{media_release}.
2180         @version: LibVLC 3.0.0 and later.
2181         '''
2182         return libvlc_media_new_callbacks(self, open_cb, read_cb, seek_cb, close_cb, opaque)
2183
2184
2185     def media_new_as_node(self, psz_name):
2186         '''Create a media as an empty node with a given name.
2187         See L{media_release}.
2188         @param psz_name: the name of the node.
2189         @return: the new empty media or None on error.
2190         '''
2191         return libvlc_media_new_as_node(self, str_to_bytes(psz_name))
2192
2193
2194     def renderer_discoverer_new(self, psz_name):
2195         '''Create a renderer discoverer object by name
2196         After this object is created, you should attach to events in order to be
2197         notified of the discoverer events.
2198         You need to call L{renderer_discoverer_start}() in order to start the
2199         discovery.
2200         See L{renderer_discoverer_event_manager}()
2201         See L{renderer_discoverer_start}().
2202         @param psz_name: service name; use L{renderer_discoverer_list_get}() to get a list of the discoverer names available in this libVLC instance.
2203         @return: media discover object or None in case of error.
2204         @version: LibVLC 3.0.0 or later.
2205         '''
2206         return libvlc_renderer_discoverer_new(self, str_to_bytes(psz_name))
2207
2208
2209     def renderer_discoverer_list_get(self, ppp_services):
2210         '''Get media discoverer services
2211         See libvlc_renderer_list_release().
2212         @param ppp_services: address to store an allocated array of renderer discoverer services (must be freed with libvlc_renderer_list_release() by the caller) [OUT].
2213         @return: the number of media discoverer services (0 on error).
2214         @version: LibVLC 3.0.0 and later.
2215         '''
2216         return libvlc_renderer_discoverer_list_get(self, ppp_services)
2217
2218
2219     def playlist_play(self):
2220         '''Start playing (if there is any item in the playlist).
2221         Additionnal playlist item options can be specified for addition to the
2222         item before it is played.
2223         '''
2224         return libvlc_playlist_play(self)
2225
2226
2227     def audio_output_list_get(self):
2228         '''Gets the list of available audio output modules.
2229         @return: list of available audio outputs. It must be freed with In case of error, None is returned.
2230         '''
2231         return libvlc_audio_output_list_get(self)
2232
2233
2234     def audio_output_device_list_get(self, aout):
2235         '''Gets a list of audio output devices for a given audio output module,
2236         See L{audio_output_device_set}().
2237         @note: Not all audio outputs support this. In particular, an empty (None)
2238         list of devices does B{not} imply that the specified audio output does
2239         not work.
2240         @note: The list might not be exhaustive.
2241         @warning: Some audio output devices in the list might not actually work in
2242         some circumstances. By default, it is recommended to not specify any
2243         explicit audio device.
2244         @param aout: audio output name (as returned by L{audio_output_list_get}()).
2245         @return: A None-terminated linked list of potential audio output devices. It must be freed with L{audio_output_device_list_release}().
2246         @version: LibVLC 2.1.0 or later.
2247         '''
2248         return libvlc_audio_output_device_list_get(self, str_to_bytes(aout))
2249
2250 class Media(_Ctype):
2251     '''Create a new Media instance.
2252
2253     Usage: Media(MRL, *options)
2254
2255     See vlc.Instance.media_new documentation for details.
2256     
2257     '''
2258
2259     def __new__(cls, *args):
2260         if args:
2261             i = args[0]
2262             if isinstance(i, _Ints):
2263                 return _Constructor(cls, i)
2264             if isinstance(i, Instance):
2265                 return i.media_new(*args[1:])
2266
2267         o = get_default_instance().media_new(*args)
2268         return o
2269
2270     def get_instance(self):
2271         return getattr(self, '_instance', None)
2272
2273     def add_options(self, *options):
2274         """Add a list of options to the media.
2275
2276         Options must be written without the double-dash. Warning: most
2277         audio and video options, such as text renderer, have no
2278         effects on an individual media. These options must be set at
2279         the vlc.Instance or vlc.MediaPlayer instanciation.
2280
2281         @param options: optional media option=value strings
2282         """
2283         for o in options:
2284             self.add_option(o)
2285
2286     def tracks_get(self):
2287         """Get media descriptor's elementary streams description
2288         Note, you need to call L{parse}() or play the media at least once
2289         before calling this function.
2290         Not doing this will result in an empty array.
2291         The result must be freed with L{tracks_release}.
2292         @version: LibVLC 2.1.0 and later.
2293         """
2294         mediaTrack_pp = ctypes.POINTER(MediaTrack)()
2295         n = libvlc_media_tracks_get(self, ctypes.byref(mediaTrack_pp))
2296         info = ctypes.cast(mediaTrack_pp, ctypes.POINTER(ctypes.POINTER(MediaTrack) * n))
2297         try:
2298             contents = info.contents
2299         except ValueError:
2300             # Media not parsed, no info.
2301             return None
2302         tracks = ( contents[i].contents for i in range(len(contents)) )
2303         # libvlc_media_tracks_release(mediaTrack_pp, n)
2304         return tracks
2305
2306
2307
2308     def add_option(self, psz_options):
2309         '''Add an option to the media.
2310         This option will be used to determine how the media_player will
2311         read the media. This allows to use VLC's advanced
2312         reading/streaming options on a per-media basis.
2313         @note: The options are listed in 'vlc --long-help' from the command line,
2314         e.g. "-sout-all". Keep in mind that available options and their semantics
2315         vary across LibVLC versions and builds.
2316         @warning: Not all options affects L{Media} objects:
2317         Specifically, due to architectural issues most audio and video options,
2318         such as text renderer options, have no effects on an individual media.
2319         These options must be set through L{new}() instead.
2320         @param psz_options: the options (as a string).
2321         '''
2322         return libvlc_media_add_option(self, str_to_bytes(psz_options))
2323
2324
2325     def add_option_flag(self, psz_options, i_flags):
2326         '''Add an option to the media with configurable flags.
2327         This option will be used to determine how the media_player will
2328         read the media. This allows to use VLC's advanced
2329         reading/streaming options on a per-media basis.
2330         The options are detailed in vlc --long-help, for instance
2331         "--sout-all". Note that all options are not usable on medias:
2332         specifically, due to architectural issues, video-related options
2333         such as text renderer options cannot be set on a single media. They
2334         must be set on the whole libvlc instance instead.
2335         @param psz_options: the options (as a string).
2336         @param i_flags: the flags for this option.
2337         '''
2338         return libvlc_media_add_option_flag(self, str_to_bytes(psz_options), i_flags)
2339
2340
2341     def retain(self):
2342         '''Retain a reference to a media descriptor object (L{Media}). Use
2343         L{release}() to decrement the reference count of a
2344         media descriptor object.
2345         '''
2346         return libvlc_media_retain(self)
2347
2348
2349     def release(self):
2350         '''Decrement the reference count of a media descriptor object. If the
2351         reference count is 0, then L{release}() will release the
2352         media descriptor object. It will send out an libvlc_MediaFreed event
2353         to all listeners. If the media descriptor object has been released it
2354         should not be used again.
2355         '''
2356         return libvlc_media_release(self)
2357
2358
2359     def get_mrl(self):
2360         '''Get the media resource locator (mrl) from a media descriptor object.
2361         @return: string with mrl of media descriptor object.
2362         '''
2363         return libvlc_media_get_mrl(self)
2364
2365
2366     def duplicate(self):
2367         '''Duplicate a media descriptor object.
2368         '''
2369         return libvlc_media_duplicate(self)
2370
2371
2372     def get_meta(self, e_meta):
2373         '''Read the meta of the media.
2374         If the media has not yet been parsed this will return None.
2375         See L{parse}
2376         See L{parse_with_options}
2377         See libvlc_MediaMetaChanged.
2378         @param e_meta: the meta to read.
2379         @return: the media's meta.
2380         '''
2381         return libvlc_media_get_meta(self, e_meta)
2382
2383
2384     def set_meta(self, e_meta, psz_value):
2385         '''Set the meta of the media (this function will not save the meta, call
2386         L{save_meta} in order to save the meta).
2387         @param e_meta: the meta to write.
2388         @param psz_value: the media's meta.
2389         '''
2390         return libvlc_media_set_meta(self, e_meta, str_to_bytes(psz_value))
2391
2392
2393     def save_meta(self):
2394         '''Save the meta previously set.
2395         @return: true if the write operation was successful.
2396         '''
2397         return libvlc_media_save_meta(self)
2398
2399
2400     def get_state(self):
2401         '''Get current state of media descriptor object. Possible media states are
2402         libvlc_NothingSpecial=0, libvlc_Opening, libvlc_Playing, libvlc_Paused,
2403         libvlc_Stopped, libvlc_Ended, libvlc_Error.
2404         See L{State}.
2405         @return: state of media descriptor object.
2406         '''
2407         return libvlc_media_get_state(self)
2408
2409
2410     def get_stats(self, p_stats):
2411         '''Get the current statistics about the media.
2412         @param p_stats:: structure that contain the statistics about the media (this structure must be allocated by the caller).
2413         @return: true if the statistics are available, false otherwise \libvlc_return_bool.
2414         '''
2415         return libvlc_media_get_stats(self, p_stats)
2416
2417
2418     def subitems(self):
2419         '''Get subitems of media descriptor object. This will increment
2420         the reference count of supplied media descriptor object. Use
2421         L{list_release}() to decrement the reference counting.
2422         @return: list of media descriptor subitems or None.
2423         '''
2424         return libvlc_media_subitems(self)
2425
2426     @memoize_parameterless
2427     def event_manager(self):
2428         '''Get event manager from media descriptor object.
2429         NOTE: this function doesn't increment reference counting.
2430         @return: event manager object.
2431         '''
2432         return libvlc_media_event_manager(self)
2433
2434
2435     def get_duration(self):
2436         '''Get duration (in ms) of media descriptor object item.
2437         @return: duration of media item or -1 on error.
2438         '''
2439         return libvlc_media_get_duration(self)
2440
2441
2442     def parse_with_options(self, parse_flag, timeout):
2443         '''Parse the media asynchronously with options.
2444         This fetches (local or network) art, meta data and/or tracks information.
2445         This method is the extended version of L{parse_with_options}().
2446         To track when this is over you can listen to libvlc_MediaParsedChanged
2447         event. However if this functions returns an error, you will not receive any
2448         events.
2449         It uses a flag to specify parse options (see L{MediaParseFlag}). All
2450         these flags can be combined. By default, media is parsed if it's a local
2451         file.
2452         @note: Parsing can be aborted with L{parse_stop}().
2453         See libvlc_MediaParsedChanged
2454         See L{get_meta}
2455         See L{tracks_get}
2456         See L{get_parsed_status}
2457         See L{MediaParseFlag}.
2458         @param parse_flag: parse options:
2459         @param timeout: maximum time allowed to preparse the media. If -1, the default "preparse-timeout" option will be used as a timeout. If 0, it will wait indefinitely. If > 0, the timeout will be used (in milliseconds).
2460         @return: -1 in case of error, 0 otherwise.
2461         @version: LibVLC 3.0.0 or later.
2462         '''
2463         return libvlc_media_parse_with_options(self, parse_flag, timeout)
2464
2465
2466     def parse_stop(self):
2467         '''Stop the parsing of the media
2468         When the media parsing is stopped, the libvlc_MediaParsedChanged event will
2469         be sent with the libvlc_media_parsed_status_timeout status.
2470         See L{parse_with_options}.
2471         @version: LibVLC 3.0.0 or later.
2472         '''
2473         return libvlc_media_parse_stop(self)
2474
2475
2476     def get_parsed_status(self):
2477         '''Get Parsed status for media descriptor object.
2478         See libvlc_MediaParsedChanged
2479         See L{MediaParsedStatus}.
2480         @return: a value of the L{MediaParsedStatus} enum.
2481         @version: LibVLC 3.0.0 or later.
2482         '''
2483         return libvlc_media_get_parsed_status(self)
2484
2485
2486     def set_user_data(self, p_new_user_data):
2487         '''Sets media descriptor's user_data. user_data is specialized data
2488         accessed by the host application, VLC.framework uses it as a pointer to
2489         an native object that references a L{Media} pointer.
2490         @param p_new_user_data: pointer to user data.
2491         '''
2492         return libvlc_media_set_user_data(self, p_new_user_data)
2493
2494
2495     def get_user_data(self):
2496         '''Get media descriptor's user_data. user_data is specialized data
2497         accessed by the host application, VLC.framework uses it as a pointer to
2498         an native object that references a L{Media} pointer.
2499         '''
2500         return libvlc_media_get_user_data(self)
2501
2502
2503     def get_type(self):
2504         '''Get the media type of the media descriptor object.
2505         @return: media type.
2506         @version: LibVLC 3.0.0 and later. See L{MediaType}.
2507         '''
2508         return libvlc_media_get_type(self)
2509
2510
2511     def thumbnail_request_by_time(self, time, speed, width, height, picture_type, timeout):
2512         '''\brief libvlc_media_get_thumbnail_by_time Start an asynchronous thumbnail generation
2513         If the request is successfuly queued, the libvlc_MediaThumbnailGenerated
2514         is guaranteed to be emited.
2515         @param time: The time at which the thumbnail should be generated.
2516         @param speed: The seeking speed \saL{ThumbnailerSeekSpeed}.
2517         @param width: The thumbnail width.
2518         @param height: the thumbnail height.
2519         @param picture_type: The thumbnail picture type \saL{PictureType}.
2520         @param timeout: A timeout value in ms, or 0 to disable timeout.
2521         @return: A valid opaque request object, or None in case of failure.
2522         @version: libvlc 4.0 or later See L{Picture} See L{PictureType}.
2523         '''
2524         return libvlc_media_thumbnail_request_by_time(self, time, speed, width, height, picture_type, timeout)
2525
2526
2527     def thumbnail_request_by_pos(self, pos, speed, width, height, picture_type, timeout):
2528         '''\brief libvlc_media_get_thumbnail_by_pos Start an asynchronous thumbnail generation
2529         If the request is successfuly queued, the libvlc_MediaThumbnailGenerated
2530         is guaranteed to be emited.
2531         @param pos: The position at which the thumbnail should be generated.
2532         @param speed: The seeking speed \saL{ThumbnailerSeekSpeed}.
2533         @param width: The thumbnail width.
2534         @param height: the thumbnail height.
2535         @param picture_type: The thumbnail picture type \saL{PictureType}.
2536         @param timeout: A timeout value in ms, or 0 to disable timeout.
2537         @return: A valid opaque request object, or None in case of failure.
2538         @version: libvlc 4.0 or later See L{Picture} See L{PictureType}.
2539         '''
2540         return libvlc_media_thumbnail_request_by_pos(self, pos, speed, width, height, picture_type, timeout)
2541
2542
2543     def slaves_add(self, i_type, i_priority, psz_uri):
2544         '''Add a slave to the current media.
2545         A slave is an external input source that may contains an additional subtitle
2546         track (like a .srt) or an additional audio track (like a .ac3).
2547         @note: This function must be called before the media is parsed (via
2548         L{parse_with_options}()) or before the media is played (via
2549         L{player_play}()).
2550         @param i_type: subtitle or audio.
2551         @param i_priority: from 0 (low priority) to 4 (high priority).
2552         @param psz_uri: Uri of the slave (should contain a valid scheme).
2553         @return: 0 on success, -1 on error.
2554         @version: LibVLC 3.0.0 and later.
2555         '''
2556         return libvlc_media_slaves_add(self, i_type, i_priority, str_to_bytes(psz_uri))
2557
2558
2559     def slaves_clear(self):
2560         '''Clear all slaves previously added by L{slaves_add}() or
2561         internally.
2562         @version: LibVLC 3.0.0 and later.
2563         '''
2564         return libvlc_media_slaves_clear(self)
2565
2566
2567     def slaves_get(self, ppp_slaves):
2568         '''Get a media descriptor's slave list
2569         The list will contain slaves parsed by VLC or previously added by
2570         L{slaves_add}(). The typical use case of this function is to save
2571         a list of slave in a database for a later use.
2572         @param ppp_slaves: address to store an allocated array of slaves (must be freed with L{slaves_release}()) [OUT].
2573         @return: the number of slaves (zero on error).
2574         @version: LibVLC 3.0.0 and later. See L{slaves_add}.
2575         '''
2576         return libvlc_media_slaves_get(self, ppp_slaves)
2577
2578
2579     def parse(self):
2580         '''Parse a media.
2581         This fetches (local) art, meta data and tracks information.
2582         The method is synchronous.
2583         \deprecated This function could block indefinitely.
2584                     Use L{parse_with_options}() instead
2585         See L{parse_with_options}
2586         See L{get_meta}.
2587         '''
2588         return libvlc_media_parse(self)
2589
2590
2591     def parse_async(self):
2592         '''Parse a media.
2593         This fetches (local) art, meta data and tracks information.
2594         The method is the asynchronous of L{parse}().
2595         To track when this is over you can listen to libvlc_MediaParsedChanged
2596         event. However if the media was already parsed you will not receive this
2597         event.
2598         \deprecated You can't be sure to receive the libvlc_MediaParsedChanged
2599                     event (you can wait indefinitely for this event).
2600                     Use L{parse_with_options}() instead
2601         See L{parse}
2602         See libvlc_MediaParsedChanged
2603         See L{get_meta}.
2604         '''
2605         return libvlc_media_parse_async(self)
2606
2607
2608     def is_parsed(self):
2609         '''Return true is the media descriptor object is parsed
2610         \deprecated This can return true in case of failure.
2611                     Use L{get_parsed_status}() instead
2612         See libvlc_MediaParsedChanged.
2613         @return: true if media object has been parsed otherwise it returns false \libvlc_return_bool.
2614         '''
2615         return libvlc_media_is_parsed(self)
2616
2617
2618     def player_new_from_media(self):
2619         '''Create a Media Player object from a Media.
2620         @return: a new media player object, or None on error.
2621         '''
2622         return libvlc_media_player_new_from_media(self)
2623
2624 class MediaDiscoverer(_Ctype):
2625     '''N/A
2626     '''
2627
2628     def __new__(cls, ptr=_internal_guard):
2629         '''(INTERNAL) ctypes wrapper constructor.
2630         '''
2631         return _Constructor(cls, ptr)
2632
2633     def start(self):
2634         '''Start media discovery.
2635         To stop it, call L{stop}() or
2636         L{list_release}() directly.
2637         See L{stop}.
2638         @return: -1 in case of error, 0 otherwise.
2639         @version: LibVLC 3.0.0 or later.
2640         '''
2641         return libvlc_media_discoverer_start(self)
2642
2643
2644     def stop(self):
2645         '''Stop media discovery.
2646         See L{start}.
2647         @version: LibVLC 3.0.0 or later.
2648         '''
2649         return libvlc_media_discoverer_stop(self)
2650
2651
2652     def release(self):
2653         '''Release media discover object. If the reference count reaches 0, then
2654         the object will be released.
2655         '''
2656         return libvlc_media_discoverer_release(self)
2657
2658
2659     def media_list(self):
2660         '''Get media service discover media list.
2661         @return: list of media items.
2662         '''
2663         return libvlc_media_discoverer_media_list(self)
2664
2665
2666     def is_running(self):
2667         '''Query if media service discover object is running.
2668         @return: true if running, false if not \libvlc_return_bool.
2669         '''
2670         return libvlc_media_discoverer_is_running(self)
2671
2672 class MediaLibrary(_Ctype):
2673     '''N/A
2674     '''
2675
2676     def __new__(cls, ptr=_internal_guard):
2677         '''(INTERNAL) ctypes wrapper constructor.
2678         '''
2679         return _Constructor(cls, ptr)
2680
2681     def release(self):
2682         '''Release media library object. This functions decrements the
2683         reference count of the media library object. If it reaches 0,
2684         then the object will be released.
2685         '''
2686         return libvlc_media_library_release(self)
2687
2688
2689     def retain(self):
2690         '''Retain a reference to a media library object. This function will
2691         increment the reference counting for this object. Use
2692         L{release}() to decrement the reference count.
2693         '''
2694         return libvlc_media_library_retain(self)
2695
2696
2697     def load(self):
2698         '''Load media library.
2699         @return: 0 on success, -1 on error.
2700         '''
2701         return libvlc_media_library_load(self)
2702
2703
2704     def media_list(self):
2705         '''Get media library subitems.
2706         @return: media list subitems.
2707         '''
2708         return libvlc_media_library_media_list(self)
2709
2710 class MediaList(_Ctype):
2711     '''Create a new MediaList instance.
2712
2713     Usage: MediaList(list_of_MRLs)
2714
2715     See vlc.Instance.media_list_new documentation for details.
2716     
2717     '''
2718
2719     def __new__(cls, *args):
2720         if args:
2721             i = args[0]
2722             if isinstance(i, _Ints):
2723                 return _Constructor(cls, i)
2724             if isinstance(i, Instance):
2725                 return i.media_list_new(*args[1:])
2726
2727         o = get_default_instance().media_list_new(*args)
2728         return o
2729
2730     def get_instance(self):
2731         return getattr(self, '_instance', None)
2732
2733     def add_media(self, mrl):
2734         """Add media instance to media list.
2735
2736         The L{lock} should be held upon entering this function.
2737         @param mrl: a media instance or a MRL.
2738         @return: 0 on success, -1 if the media list is read-only.
2739         """
2740         if isinstance(mrl, basestring):
2741             mrl = (self.get_instance() or get_default_instance()).media_new(mrl)
2742         return libvlc_media_list_add_media(self, mrl)
2743
2744
2745
2746     def release(self):
2747         '''Release media list created with L{new}().
2748         '''
2749         return libvlc_media_list_release(self)
2750
2751
2752     def retain(self):
2753         '''Retain reference to a media list.
2754         '''
2755         return libvlc_media_list_retain(self)
2756
2757
2758     def set_media(self, p_md):
2759         '''Associate media instance with this media list instance.
2760         If another media instance was present it will be released.
2761         The L{lock} should NOT be held upon entering this function.
2762         @param p_md: media instance to add.
2763         '''
2764         return libvlc_media_list_set_media(self, p_md)
2765
2766
2767     def media(self):
2768         '''Get media instance from this media list instance. This action will increase
2769         the refcount on the media instance.
2770         The L{lock} should NOT be held upon entering this function.
2771         @return: media instance.
2772         '''
2773         return libvlc_media_list_media(self)
2774
2775
2776     def insert_media(self, p_md, i_pos):
2777         '''Insert media instance in media list on a position
2778         The L{lock} should be held upon entering this function.
2779         @param p_md: a media instance.
2780         @param i_pos: position in array where to insert.
2781         @return: 0 on success, -1 if the media list is read-only.
2782         '''
2783         return libvlc_media_list_insert_media(self, p_md, i_pos)
2784
2785
2786     def remove_index(self, i_pos):
2787         '''Remove media instance from media list on a position
2788         The L{lock} should be held upon entering this function.
2789         @param i_pos: position in array where to insert.
2790         @return: 0 on success, -1 if the list is read-only or the item was not found.
2791         '''
2792         return libvlc_media_list_remove_index(self, i_pos)
2793
2794
2795     def count(self):
2796         '''Get count on media list items
2797         The L{lock} should be held upon entering this function.
2798         @return: number of items in media list.
2799         '''
2800         return libvlc_media_list_count(self)
2801
2802     def __len__(self):
2803         return libvlc_media_list_count(self)
2804
2805
2806     def item_at_index(self, i_pos):
2807         '''List media instance in media list at a position
2808         The L{lock} should be held upon entering this function.
2809         @param i_pos: position in array where to insert.
2810         @return: media instance at position i_pos, or None if not found. In case of success, L{media_retain}() is called to increase the refcount on the media.
2811         '''
2812         return libvlc_media_list_item_at_index(self, i_pos)
2813
2814     def __getitem__(self, i):
2815         return libvlc_media_list_item_at_index(self, i)
2816
2817     def __iter__(self):
2818         for i in range(len(self)):
2819             yield self[i]
2820
2821
2822     def index_of_item(self, p_md):
2823         '''Find index position of List media instance in media list.
2824         Warning: the function will return the first matched position.
2825         The L{lock} should be held upon entering this function.
2826         @param p_md: media instance.
2827         @return: position of media instance or -1 if media not found.
2828         '''
2829         return libvlc_media_list_index_of_item(self, p_md)
2830
2831
2832     def is_readonly(self):
2833         '''This indicates if this media list is read-only from a user point of view.
2834         @return: 1 on readonly, 0 on readwrite \libvlc_return_bool.
2835         '''
2836         return libvlc_media_list_is_readonly(self)
2837
2838
2839     def lock(self):
2840         '''Get lock on media list items.
2841         '''
2842         return libvlc_media_list_lock(self)
2843
2844
2845     def unlock(self):
2846         '''Release lock on media list items
2847         The L{lock} should be held upon entering this function.
2848         '''
2849         return libvlc_media_list_unlock(self)
2850
2851     @memoize_parameterless
2852     def event_manager(self):
2853         '''Get libvlc_event_manager from this media list instance.
2854         The p_event_manager is immutable, so you don't have to hold the lock.
2855         @return: libvlc_event_manager.
2856         '''
2857         return libvlc_media_list_event_manager(self)
2858
2859 class MediaListPlayer(_Ctype):
2860     '''Create a new MediaListPlayer instance.
2861
2862     It may take as parameter either:
2863       - a vlc.Instance
2864       - nothing
2865     
2866     '''
2867
2868     def __new__(cls, arg=None):
2869         if arg is None:
2870             i = get_default_instance()
2871         elif isinstance(arg, Instance):
2872             i = arg
2873         elif isinstance(arg, _Ints):
2874             return _Constructor(cls, arg)
2875         else:
2876             raise TypeError('MediaListPlayer %r' % (arg,))
2877
2878         return i.media_list_player_new()
2879
2880     def get_instance(self):
2881         """Return the associated Instance.
2882         """
2883         return self._instance  #PYCHOK expected
2884
2885
2886
2887     def release(self):
2888         '''Release a media_list_player after use
2889         Decrement the reference count of a media player object. If the
2890         reference count is 0, then L{release}() will
2891         release the media player object. If the media player object
2892         has been released, then it should not be used again.
2893         '''
2894         return libvlc_media_list_player_release(self)
2895
2896
2897     def retain(self):
2898         '''Retain a reference to a media player list object. Use
2899         L{release}() to decrement reference count.
2900         '''
2901         return libvlc_media_list_player_retain(self)
2902
2903     @memoize_parameterless
2904     def event_manager(self):
2905         '''Return the event manager of this media_list_player.
2906         @return: the event manager.
2907         '''
2908         return libvlc_media_list_player_event_manager(self)
2909
2910
2911     def set_media_player(self, p_mi):
2912         '''Replace media player in media_list_player with this instance.
2913         @param p_mi: media player instance.
2914         '''
2915         return libvlc_media_list_player_set_media_player(self, p_mi)
2916
2917
2918     def get_media_player(self):
2919         '''Get media player of the media_list_player instance.
2920         @return: media player instance @note the caller is responsible for releasing the returned instance.
2921         '''
2922         return libvlc_media_list_player_get_media_player(self)
2923
2924
2925     def set_media_list(self, p_mlist):
2926         '''Set the media list associated with the player.
2927         @param p_mlist: list of media.
2928         '''
2929         return libvlc_media_list_player_set_media_list(self, p_mlist)
2930
2931
2932     def play(self):
2933         '''Play media list.
2934         '''
2935         return libvlc_media_list_player_play(self)
2936
2937
2938     def pause(self):
2939         '''Toggle pause (or resume) media list.
2940         '''
2941         return libvlc_media_list_player_pause(self)
2942
2943
2944     def set_pause(self, do_pause):
2945         '''Pause or resume media list.
2946         @param do_pause: play/resume if zero, pause if non-zero.
2947         @version: LibVLC 3.0.0 or later.
2948         '''
2949         return libvlc_media_list_player_set_pause(self, do_pause)
2950
2951
2952     def is_playing(self):
2953         '''Is media list playing?
2954         @return: true for playing and false for not playing \libvlc_return_bool.
2955         '''
2956         return libvlc_media_list_player_is_playing(self)
2957
2958
2959     def get_state(self):
2960         '''Get current libvlc_state of media list player.
2961         @return: L{State} for media list player.
2962         '''
2963         return libvlc_media_list_player_get_state(self)
2964
2965
2966     def play_item_at_index(self, i_index):
2967         '''Play media list item at position index.
2968         @param i_index: index in media list to play.
2969         @return: 0 upon success -1 if the item wasn't found.
2970         '''
2971         return libvlc_media_list_player_play_item_at_index(self, i_index)
2972
2973     def __getitem__(self, i):
2974         return libvlc_media_list_player_play_item_at_index(self, i)
2975
2976     def __iter__(self):
2977         for i in range(len(self)):
2978             yield self[i]
2979
2980
2981     def play_item(self, p_md):
2982         '''Play the given media item.
2983         @param p_md: the media instance.
2984         @return: 0 upon success, -1 if the media is not part of the media list.
2985         '''
2986         return libvlc_media_list_player_play_item(self, p_md)
2987
2988
2989     def stop(self):
2990         '''Stop playing media list.
2991         '''
2992         return libvlc_media_list_player_stop(self)
2993
2994
2995     def next(self):
2996         '''Play next item from media list.
2997         @return: 0 upon success -1 if there is no next item.
2998         '''
2999         return libvlc_media_list_player_next(self)
3000
3001
3002     def previous(self):
3003         '''Play previous item from media list.
3004         @return: 0 upon success -1 if there is no previous item.
3005         '''
3006         return libvlc_media_list_player_previous(self)
3007
3008
3009     def set_playback_mode(self, e_mode):
3010         '''Sets the playback mode for the playlist.
3011         @param e_mode: playback mode specification.
3012         '''
3013         return libvlc_media_list_player_set_playback_mode(self, e_mode)
3014
3015 class MediaPlayer(_Ctype):
3016     '''Create a new MediaPlayer instance.
3017
3018     It may take as parameter either:
3019       - a string (media URI), options... In this case, a vlc.Instance will be created.
3020       - a vlc.Instance, a string (media URI), options...
3021     
3022     '''
3023
3024     def __new__(cls, *args):
3025         if len(args) == 1 and isinstance(args[0], _Ints):
3026             return _Constructor(cls, args[0])
3027
3028         if args and isinstance(args[0], Instance):
3029             instance = args[0]
3030             args = args[1:]
3031         else:
3032             instance = get_default_instance()
3033
3034         o = instance.media_player_new()
3035         if args:
3036             o.set_media(instance.media_new(*args))
3037         return o
3038
3039     def get_instance(self):
3040         """Return the associated Instance.
3041         """
3042         return self._instance  #PYCHOK expected
3043
3044     def set_mrl(self, mrl, *options):
3045         """Set the MRL to play.
3046
3047         Warning: most audio and video options, such as text renderer,
3048         have no effects on an individual media. These options must be
3049         set at the vlc.Instance or vlc.MediaPlayer instanciation.
3050
3051         @param mrl: The MRL
3052         @param options: optional media option=value strings
3053         @return: the Media object
3054         """
3055         m = self.get_instance().media_new(mrl, *options)
3056         self.set_media(m)
3057         return m
3058
3059     def video_get_spu_description(self):
3060         """Get the description of available video subtitles.
3061         """
3062         return track_description_list(libvlc_video_get_spu_description(self))
3063
3064     def video_get_track_description(self):
3065         """Get the description of available video tracks.
3066         """
3067         return track_description_list(libvlc_video_get_track_description(self))
3068
3069     def audio_get_track_description(self):
3070         """Get the description of available audio tracks.
3071         """
3072         return track_description_list(libvlc_audio_get_track_description(self))
3073
3074     def get_full_title_descriptions(self):
3075         '''Get the full description of available titles.
3076         @return: the titles list
3077         @version: LibVLC 3.0.0 and later.
3078         '''
3079         titleDescription_pp = ctypes.POINTER(TitleDescription)()
3080         n = libvlc_media_player_get_full_title_descriptions(self, ctypes.byref(titleDescription_pp))
3081         info = ctypes.cast(titleDescription_pp, ctypes.POINTER(ctypes.POINTER(TitleDescription) * n))
3082         try:
3083             contents = info.contents
3084         except ValueError:
3085             # Media not parsed, no info.
3086             return None
3087         descr = ( contents[i].contents for i in range(len(contents)) )
3088         return descr
3089
3090     def get_full_chapter_descriptions(self, i_chapters_of_title):
3091         '''Get the full description of available chapters.
3092         @param i_chapters_of_title: index of the title to query for chapters (uses current title if set to -1).
3093         @return: the chapters list
3094         @version: LibVLC 3.0.0 and later.
3095         '''
3096         chapterDescription_pp = ctypes.POINTER(ChapterDescription)()
3097         n = libvlc_media_player_get_full_chapter_descriptions(self, ctypes.byref(chapterDescription_pp))
3098         info = ctypes.cast(chapterDescription_pp, ctypes.POINTER(ctypes.POINTER(ChapterDescription) * n))
3099         try:
3100             contents = info.contents
3101         except ValueError:
3102             # Media not parsed, no info.
3103             return None
3104         descr = ( contents[i].contents for i in range(len(contents)) )
3105         return descr
3106
3107     def video_get_size(self, num=0):
3108         """Get the video size in pixels as 2-tuple (width, height).
3109
3110         @param num: video number (default 0).
3111         """
3112         r = libvlc_video_get_size(self, num)
3113         if isinstance(r, tuple) and len(r) == 2:
3114             return r
3115         else:
3116             raise VLCException('invalid video number (%s)' % (num,))
3117
3118     def set_hwnd(self, drawable):
3119         """Set a Win32/Win64 API window handle (HWND).
3120
3121         Specify where the media player should render its video
3122         output. If LibVLC was built without Win32/Win64 API output
3123         support, then this has no effects.
3124
3125         @param drawable: windows handle of the drawable.
3126         """
3127         if not isinstance(drawable, ctypes.c_void_p):
3128             drawable = ctypes.c_void_p(int(drawable))
3129         libvlc_media_player_set_hwnd(self, drawable)
3130
3131     def video_get_width(self, num=0):
3132         """Get the width of a video in pixels.
3133
3134         @param num: video number (default 0).
3135         """
3136         return self.video_get_size(num)[0]
3137
3138     def video_get_height(self, num=0):
3139         """Get the height of a video in pixels.
3140
3141         @param num: video number (default 0).
3142         """
3143         return self.video_get_size(num)[1]
3144
3145     def video_get_cursor(self, num=0):
3146         """Get the mouse pointer coordinates over a video as 2-tuple (x, y).
3147
3148         Coordinates are expressed in terms of the decoded video resolution,
3149         B{not} in terms of pixels on the screen/viewport.  To get the
3150         latter, you must query your windowing system directly.
3151
3152         Either coordinate may be negative or larger than the corresponding
3153         size of the video, if the cursor is outside the rendering area.
3154
3155         @warning: The coordinates may be out-of-date if the pointer is not
3156         located on the video rendering area.  LibVLC does not track the
3157         mouse pointer if the latter is outside the video widget.
3158
3159         @note: LibVLC does not support multiple mouse pointers (but does
3160         support multiple input devices sharing the same pointer).
3161
3162         @param num: video number (default 0).
3163         """
3164         r = libvlc_video_get_cursor(self, num)
3165         if isinstance(r, tuple) and len(r) == 2:
3166             return r
3167         raise VLCException('invalid video number (%s)' % (num,))
3168
3169
3170
3171     def release(self):
3172         '''Release a media_player after use
3173         Decrement the reference count of a media player object. If the
3174         reference count is 0, then L{release}() will
3175         release the media player object. If the media player object
3176         has been released, then it should not be used again.
3177         '''
3178         return libvlc_media_player_release(self)
3179
3180
3181     def retain(self):
3182         '''Retain a reference to a media player object. Use
3183         L{release}() to decrement reference count.
3184         '''
3185         return libvlc_media_player_retain(self)
3186
3187
3188     def set_media(self, p_md):
3189         '''Set the media that will be used by the media_player. If any,
3190         previous md will be released.
3191         @param p_md: the Media. Afterwards the p_md can be safely destroyed.
3192         '''
3193         return libvlc_media_player_set_media(self, p_md)
3194
3195
3196     def get_media(self):
3197         '''Get the media used by the media_player.
3198         @return: the media associated with p_mi, or None if no media is associated.
3199         '''
3200         return libvlc_media_player_get_media(self)
3201
3202     @memoize_parameterless
3203     def event_manager(self):
3204         '''Get the Event Manager from which the media player send event.
3205         @return: the event manager associated with p_mi.
3206         '''
3207         return libvlc_media_player_event_manager(self)
3208
3209
3210     def is_playing(self):
3211         '''is_playing.
3212         @return: 1 if the media player is playing, 0 otherwise \libvlc_return_bool.
3213         '''
3214         return libvlc_media_player_is_playing(self)
3215
3216
3217     def play(self):
3218         '''Play.
3219         @return: 0 if playback started (and was already started), or -1 on error.
3220         '''
3221         return libvlc_media_player_play(self)
3222
3223
3224     def set_pause(self, do_pause):
3225         '''Pause or resume (no effect if there is no media).
3226         @param do_pause: play/resume if zero, pause if non-zero.
3227         @version: LibVLC 1.1.1 or later.
3228         '''
3229         return libvlc_media_player_set_pause(self, do_pause)
3230
3231
3232     def pause(self):
3233         '''Toggle pause (no effect if there is no media).
3234         '''
3235         return libvlc_media_player_pause(self)
3236
3237
3238     def stop(self):
3239         '''Stop (no effect if there is no media).
3240         '''
3241         return libvlc_media_player_stop(self)
3242
3243
3244     def set_renderer(self, p_item):
3245         '''Set a renderer to the media player
3246         @note: must be called before the first call of L{play}() to
3247         take effect.
3248         See L{renderer_discoverer_new}.
3249         @param p_item: an item discovered by L{renderer_discoverer_start}().
3250         @return: 0 on success, -1 on error.
3251         @version: LibVLC 3.0.0 or later.
3252         '''
3253         return libvlc_media_player_set_renderer(self, p_item)
3254
3255
3256     def video_set_callbacks(self, lock, unlock, display, opaque):
3257         '''Set callbacks and private data to render decoded video to a custom area
3258         in memory.
3259         Use L{video_set_format}() or L{video_set_format_callbacks}()
3260         to configure the decoded format.
3261         @warning: Rendering video into custom memory buffers is considerably less
3262         efficient than rendering in a custom window as normal.
3263         For optimal perfomances, VLC media player renders into a custom window, and
3264         does not use this function and associated callbacks. It is B{highly
3265         recommended} that other LibVLC-based application do likewise.
3266         To embed video in a window, use libvlc_media_player_set_xid() or equivalent
3267         depending on the operating system.
3268         If window embedding does not fit the application use case, then a custom
3269         LibVLC video output display plugin is required to maintain optimal video
3270         rendering performances.
3271         The following limitations affect performance:
3272         - Hardware video decoding acceleration will either be disabled completely,
3273           or require (relatively slow) copy from video/DSP memory to main memory.
3274         - Sub-pictures (subtitles, on-screen display, etc.) must be blent into the
3275           main picture by the CPU instead of the GPU.
3276         - Depending on the video format, pixel format conversion, picture scaling,
3277           cropping and/or picture re-orientation, must be performed by the CPU
3278           instead of the GPU.
3279         - Memory copying is required between LibVLC reference picture buffers and
3280           application buffers (between lock and unlock callbacks).
3281         @param lock: callback to lock video memory (must not be None).
3282         @param unlock: callback to unlock video memory (or None if not needed).
3283         @param display: callback to display video (or None if not needed).
3284         @param opaque: private pointer for the three callbacks (as first parameter).
3285         @version: LibVLC 1.1.1 or later.
3286         '''
3287         return libvlc_video_set_callbacks(self, lock, unlock, display, opaque)
3288
3289
3290     def video_set_format(self, chroma, width, height, pitch):
3291         '''Set decoded video chroma and dimensions.
3292         This only works in combination with L{video_set_callbacks}(),
3293         and is mutually exclusive with L{video_set_format_callbacks}().
3294         @param chroma: a four-characters string identifying the chroma (e.g. "RV32" or "YUYV").
3295         @param width: pixel width.
3296         @param height: pixel height.
3297         @param pitch: line pitch (in bytes).
3298         @version: LibVLC 1.1.1 or later.
3299         @bug: All pixel planes are expected to have the same pitch. To use the YCbCr color space with chrominance subsampling, consider using L{video_set_format_callbacks}() instead.
3300         '''
3301         return libvlc_video_set_format(self, str_to_bytes(chroma), width, height, pitch)
3302
3303
3304     def video_set_format_callbacks(self, setup, cleanup):
3305         '''Set decoded video chroma and dimensions. This only works in combination with
3306         L{video_set_callbacks}().
3307         @param setup: callback to select the video format (cannot be None).
3308         @param cleanup: callback to release any allocated resources (or None).
3309         @version: LibVLC 2.0.0 or later.
3310         '''
3311         return libvlc_video_set_format_callbacks(self, setup, cleanup)
3312
3313
3314     def video_set_output_callbacks(self, engine, setup_cb, cleanup_cb, update_output_cb, swap_cb, makeCurrent_cb, getProcAddress_cb, opaque):
3315         '''Set callbacks and data to render decoded video to a custom texture
3316         @warning: VLC will perform video rendering in its own thread and at its own rate,
3317         You need to provide your own synchronisation mechanism.
3318         OpenGL context need to be created before playing a media.
3319         @param engine: the GPU engine to use.
3320         @param setup_cb: callback called to initialize user data.
3321         @param cleanup_cb: callback called to clean up user data.
3322         @param update_output_cb: callback called to get the size of the video.
3323         @param swap_cb: callback called after rendering a video frame (cannot be None).
3324         @param makeCurrent_cb: callback called to enter/leave the opengl context (cannot be None for \ref libvlc_video_engine_opengl and for \ref libvlc_video_engine_gles2).
3325         @param getProcAddress_cb: opengl function loading callback (cannot be None for \ref libvlc_video_engine_opengl and for \ref libvlc_video_engine_gles2).
3326         @param opaque: private pointer passed to callbacks \libvlc_return_bool.
3327         @version: LibVLC 4.0.0 or later.
3328         '''
3329         return libvlc_video_set_output_callbacks(self, engine, setup_cb, cleanup_cb, update_output_cb, swap_cb, makeCurrent_cb, getProcAddress_cb, opaque)
3330
3331
3332     def set_nsobject(self, drawable):
3333         '''Set the NSView handler where the media player should render its video output.
3334         Use the vout called "macosx".
3335         The drawable is an NSObject that follow the VLCOpenGLVideoViewEmbedding
3336         protocol:
3337         @code.m
3338         \@protocol VLCOpenGLVideoViewEmbedding <NSObject>
3339         - (void)addVoutSubview:(NSView *)view;
3340         - (void)removeVoutSubview:(NSView *)view;
3341         \@end
3342         @endcode
3343         Or it can be an NSView object.
3344         If you want to use it along with Qt see the QMacCocoaViewContainer. Then
3345         the following code should work:
3346         @code.mm
3347         
3348             NSView *video = [[NSView alloc] init];
3349             QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
3350             L{set_nsobject}(mp, video);
3351             [video release];
3352         
3353         @endcode
3354         You can find a live example in VLCVideoView in VLCKit.framework.
3355         @param drawable: the drawable that is either an NSView or an object following the VLCOpenGLVideoViewEmbedding protocol.
3356         '''
3357         return libvlc_media_player_set_nsobject(self, drawable)
3358
3359
3360     def get_nsobject(self):
3361         '''Get the NSView handler previously set with L{set_nsobject}().
3362         @return: the NSView handler or 0 if none where set.
3363         '''
3364         return libvlc_media_player_get_nsobject(self)
3365
3366
3367     def set_xwindow(self, drawable):
3368         '''Set an X Window System drawable where the media player should render its
3369         video output. The call takes effect when the playback starts. If it is
3370         already started, it might need to be stopped before changes apply.
3371         If LibVLC was built without X11 output support, then this function has no
3372         effects.
3373         By default, LibVLC will capture input events on the video rendering area.
3374         Use L{video_set_mouse_input}() and L{video_set_key_input}() to
3375         disable that and deliver events to the parent window / to the application
3376         instead. By design, the X11 protocol delivers input events to only one
3377         recipient.
3378         @warning
3379         The application must call the XInitThreads() function from Xlib before
3380         L{new}(), and before any call to XOpenDisplay() directly or via any
3381         other library. Failure to call XInitThreads() will seriously impede LibVLC
3382         performance. Calling XOpenDisplay() before XInitThreads() will eventually
3383         crash the process. That is a limitation of Xlib.
3384         @param drawable: X11 window ID @note The specified identifier must correspond to an existing Input/Output class X11 window. Pixmaps are B{not} currently supported. The default X11 server is assumed, i.e. that specified in the DISPLAY environment variable. @warning LibVLC can deal with invalid X11 handle errors, however some display drivers (EGL, GLX, VA and/or VDPAU) can unfortunately not. Thus the window handle must remain valid until playback is stopped, otherwise the process may abort or crash.
3385         @bug No more than one window handle per media player instance can be specified. If the media has multiple simultaneously active video tracks, extra tracks will be rendered into external windows beyond the control of the application.
3386         '''
3387         return libvlc_media_player_set_xwindow(self, drawable)
3388
3389
3390     def get_xwindow(self):
3391         '''Get the X Window System window identifier previously set with
3392         L{set_xwindow}(). Note that this will return the identifier
3393         even if VLC is not currently using it (for instance if it is playing an
3394         audio-only input).
3395         @return: an X window ID, or 0 if none where set.
3396         '''
3397         return libvlc_media_player_get_xwindow(self)
3398
3399
3400     def get_hwnd(self):
3401         '''Get the Windows API window handle (HWND) previously set with
3402         L{set_hwnd}(). The handle will be returned even if LibVLC
3403         is not currently outputting any video to it.
3404         @return: a window handle or None if there are none.
3405         '''
3406         return libvlc_media_player_get_hwnd(self)
3407
3408
3409     def set_android_context(self, p_awindow_handler):
3410         '''Set the android context.
3411         @param p_awindow_handler: org.videolan.libvlc.AWindow jobject owned by the org.videolan.libvlc.MediaPlayer class from the libvlc-android project.
3412         @version: LibVLC 3.0.0 and later.
3413         '''
3414         return libvlc_media_player_set_android_context(self, p_awindow_handler)
3415
3416
3417     def audio_set_callbacks(self, play, pause, resume, flush, drain, opaque):
3418         '''Sets callbacks and private data for decoded audio.
3419         Use L{audio_set_format}() or L{audio_set_format_callbacks}()
3420         to configure the decoded audio format.
3421         @note: The audio callbacks override any other audio output mechanism.
3422         If the callbacks are set, LibVLC will B{not} output audio in any way.
3423         @param play: callback to play audio samples (must not be None).
3424         @param pause: callback to pause playback (or None to ignore).
3425         @param resume: callback to resume playback (or None to ignore).
3426         @param flush: callback to flush audio buffers (or None to ignore).
3427         @param drain: callback to drain audio buffers (or None to ignore).
3428         @param opaque: private pointer for the audio callbacks (as first parameter).
3429         @version: LibVLC 2.0.0 or later.
3430         '''
3431         return libvlc_audio_set_callbacks(self, play, pause, resume, flush, drain, opaque)
3432
3433
3434     def audio_set_volume_callback(self, set_volume):
3435         '''Set callbacks and private data for decoded audio. This only works in
3436         combination with L{audio_set_callbacks}().
3437         Use L{audio_set_format}() or L{audio_set_format_callbacks}()
3438         to configure the decoded audio format.
3439         @param set_volume: callback to apply audio volume, or None to apply volume in software.
3440         @version: LibVLC 2.0.0 or later.
3441         '''
3442         return libvlc_audio_set_volume_callback(self, set_volume)
3443
3444
3445     def audio_set_format_callbacks(self, setup, cleanup):
3446         '''Sets decoded audio format via callbacks.
3447         This only works in combination with L{audio_set_callbacks}().
3448         @param setup: callback to select the audio format (cannot be None).
3449         @param cleanup: callback to release any allocated resources (or None).
3450         @version: LibVLC 2.0.0 or later.
3451         '''
3452         return libvlc_audio_set_format_callbacks(self, setup, cleanup)
3453
3454
3455     def audio_set_format(self, format, rate, channels):
3456         '''Sets a fixed decoded audio format.
3457         This only works in combination with L{audio_set_callbacks}(),
3458         and is mutually exclusive with L{audio_set_format_callbacks}().
3459         @param format: a four-characters string identifying the sample format (e.g. "S16N" or "f32l").
3460         @param rate: sample rate (expressed in Hz).
3461         @param channels: channels count.
3462         @version: LibVLC 2.0.0 or later.
3463         '''
3464         return libvlc_audio_set_format(self, str_to_bytes(format), rate, channels)
3465
3466
3467     def get_length(self):
3468         '''Get the current movie length (in ms).
3469         @return: the movie length (in ms), or -1 if there is no media.
3470         '''
3471         return libvlc_media_player_get_length(self)
3472
3473
3474     def get_time(self):
3475         '''Get the current movie time (in ms).
3476         @return: the movie time (in ms), or -1 if there is no media.
3477         '''
3478         return libvlc_media_player_get_time(self)
3479
3480
3481     def set_time(self, i_time, b_fast):
3482         '''Set the movie time (in ms). This has no effect if no media is being played.
3483         Not all formats and protocols support this.
3484         @param b_fast: prefer fast seeking or precise seeking.
3485         @param i_time: the movie time (in ms).
3486         @return: 0 on success, -1 on error.
3487         '''
3488         return libvlc_media_player_set_time(self, i_time, b_fast)
3489
3490
3491     def get_position(self):
3492         '''Get movie position as percentage between 0.0 and 1.0.
3493         @return: movie position, or -1. in case of error.
3494         '''
3495         return libvlc_media_player_get_position(self)
3496
3497
3498     def set_position(self, f_pos, b_fast):
3499         '''Set movie position as percentage between 0.0 and 1.0.
3500         This has no effect if playback is not enabled.
3501         This might not work depending on the underlying input format and protocol.
3502         @param b_fast: prefer fast seeking or precise seeking.
3503         @param f_pos: the position.
3504         @return: 0 on success, -1 on error.
3505         '''
3506         return libvlc_media_player_set_position(self, f_pos, b_fast)
3507
3508
3509     def set_chapter(self, i_chapter):
3510         '''Set movie chapter (if applicable).
3511         @param i_chapter: chapter number to play.
3512         '''
3513         return libvlc_media_player_set_chapter(self, i_chapter)
3514
3515
3516     def get_chapter(self):
3517         '''Get movie chapter.
3518         @return: chapter number currently playing, or -1 if there is no media.
3519         '''
3520         return libvlc_media_player_get_chapter(self)
3521
3522
3523     def get_chapter_count(self):
3524         '''Get movie chapter count.
3525         @return: number of chapters in movie, or -1.
3526         '''
3527         return libvlc_media_player_get_chapter_count(self)
3528
3529
3530     def will_play(self):
3531         '''Is the player able to play.
3532         @return: boolean \libvlc_return_bool.
3533         '''
3534         return libvlc_media_player_will_play(self)
3535
3536
3537     def get_chapter_count_for_title(self, i_title):
3538         '''Get title chapter count.
3539         @param i_title: title.
3540         @return: number of chapters in title, or -1.
3541         '''
3542         return libvlc_media_player_get_chapter_count_for_title(self, i_title)
3543
3544
3545     def set_title(self, i_title):
3546         '''Set movie title.
3547         @param i_title: title number to play.
3548         '''
3549         return libvlc_media_player_set_title(self, i_title)
3550
3551
3552     def get_title(self):
3553         '''Get movie title.
3554         @return: title number currently playing, or -1.
3555         '''
3556         return libvlc_media_player_get_title(self)
3557
3558
3559     def get_title_count(self):
3560         '''Get movie title count.
3561         @return: title number count, or -1.
3562         '''
3563         return libvlc_media_player_get_title_count(self)
3564
3565
3566     def previous_chapter(self):
3567         '''Set previous chapter (if applicable).
3568         '''
3569         return libvlc_media_player_previous_chapter(self)
3570
3571
3572     def next_chapter(self):
3573         '''Set next chapter (if applicable).
3574         '''
3575         return libvlc_media_player_next_chapter(self)
3576
3577
3578     def get_rate(self):
3579         '''Get the requested movie play rate.
3580         @warning: Depending on the underlying media, the requested rate may be
3581         different from the real playback rate.
3582         @return: movie play rate.
3583         '''
3584         return libvlc_media_player_get_rate(self)
3585
3586
3587     def set_rate(self, rate):
3588         '''Set movie play rate.
3589         @param rate: movie play rate to set.
3590         @return: -1 if an error was detected, 0 otherwise (but even then, it might not actually work depending on the underlying media protocol).
3591         '''
3592         return libvlc_media_player_set_rate(self, rate)
3593
3594
3595     def get_state(self):
3596         '''Get current movie state.
3597         @return: the current state of the media player (playing, paused, ...) See L{State}.
3598         '''
3599         return libvlc_media_player_get_state(self)
3600
3601
3602     def has_vout(self):
3603         '''How many video outputs does this media player have?
3604         @return: the number of video outputs.
3605         '''
3606         return libvlc_media_player_has_vout(self)
3607
3608
3609     def is_seekable(self):
3610         '''Is this media player seekable?
3611         @return: true if the media player can seek \libvlc_return_bool.
3612         '''
3613         return libvlc_media_player_is_seekable(self)
3614
3615
3616     def can_pause(self):
3617         '''Can this media player be paused?
3618         @return: true if the media player can pause \libvlc_return_bool.
3619         '''
3620         return libvlc_media_player_can_pause(self)
3621
3622
3623     def program_scrambled(self):
3624         '''Check if the current program is scrambled.
3625         @return: true if the current program is scrambled \libvlc_return_bool.
3626         @version: LibVLC 2.2.0 or later.
3627         '''
3628         return libvlc_media_player_program_scrambled(self)
3629
3630
3631     def next_frame(self):
3632         '''Display the next frame (if supported).
3633         '''
3634         return libvlc_media_player_next_frame(self)
3635
3636
3637     def navigate(self, navigate):
3638         '''Navigate through DVD Menu.
3639         @param navigate: the Navigation mode.
3640         @version: libVLC 2.0.0 or later.
3641         '''
3642         return libvlc_media_player_navigate(self, navigate)
3643
3644
3645     def set_video_title_display(self, position, timeout):
3646         '''Set if, and how, the video title will be shown when media is played.
3647         @param position: position at which to display the title, or libvlc_position_disable to prevent the title from being displayed.
3648         @param timeout: title display timeout in milliseconds (ignored if libvlc_position_disable).
3649         @version: libVLC 2.1.0 or later.
3650         '''
3651         return libvlc_media_player_set_video_title_display(self, position, timeout)
3652
3653
3654     def add_slave(self, i_type, psz_uri, b_select):
3655         '''Add a slave to the current media player.
3656         @note: If the player is playing, the slave will be added directly. This call
3657         will also update the slave list of the attached L{Media}.
3658         @param i_type: subtitle or audio.
3659         @param psz_uri: Uri of the slave (should contain a valid scheme).
3660         @param b_select: True if this slave should be selected when it's loaded.
3661         @return: 0 on success, -1 on error.
3662         @version: LibVLC 3.0.0 and later. See L{media_slaves_add}.
3663         '''
3664         return libvlc_media_player_add_slave(self, i_type, str_to_bytes(psz_uri), b_select)
3665
3666
3667     def toggle_fullscreen(self):
3668         '''Toggle fullscreen status on non-embedded video outputs.
3669         @warning: The same limitations applies to this function
3670         as to L{set_fullscreen}().
3671         '''
3672         return libvlc_toggle_fullscreen(self)
3673
3674
3675     def set_fullscreen(self, b_fullscreen):
3676         '''Enable or disable fullscreen.
3677         @warning: With most window managers, only a top-level windows can be in
3678         full-screen mode. Hence, this function will not operate properly if
3679         L{set_xwindow}() was used to embed the video in a
3680         non-top-level window. In that case, the embedding window must be reparented
3681         to the root window B{before} fullscreen mode is enabled. You will want
3682         to reparent it back to its normal parent when disabling fullscreen.
3683         @param b_fullscreen: boolean for fullscreen status.
3684         '''
3685         return libvlc_set_fullscreen(self, b_fullscreen)
3686
3687
3688     def get_fullscreen(self):
3689         '''Get current fullscreen status.
3690         @return: the fullscreen status (boolean) \libvlc_return_bool.
3691         '''
3692         return libvlc_get_fullscreen(self)
3693
3694
3695     def video_set_key_input(self, on):
3696         '''Enable or disable key press events handling, according to the LibVLC hotkeys
3697         configuration. By default and for historical reasons, keyboard events are
3698         handled by the LibVLC video widget.
3699         @note: On X11, there can be only one subscriber for key press and mouse
3700         click events per window. If your application has subscribed to those events
3701         for the X window ID of the video widget, then LibVLC will not be able to
3702         handle key presses and mouse clicks in any case.
3703         @warning: This function is only implemented for X11 and Win32 at the moment.
3704         @param on: true to handle key press events, false to ignore them.
3705         '''
3706         return libvlc_video_set_key_input(self, on)
3707
3708
3709     def video_set_mouse_input(self, on):
3710         '''Enable or disable mouse click events handling. By default, those events are
3711         handled. This is needed for DVD menus to work, as well as a few video
3712         filters such as "puzzle".
3713         See L{video_set_key_input}().
3714         @warning: This function is only implemented for X11 and Win32 at the moment.
3715         @param on: true to handle mouse click events, false to ignore them.
3716         '''
3717         return libvlc_video_set_mouse_input(self, on)
3718
3719
3720     def video_get_scale(self):
3721         '''Get the current video scaling factor.
3722         See also L{video_set_scale}().
3723         @return: the currently configured zoom factor, or 0. if the video is set to fit to the output window/drawable automatically.
3724         '''
3725         return libvlc_video_get_scale(self)
3726
3727
3728     def video_set_scale(self, f_factor):
3729         '''Set the video scaling factor. That is the ratio of the number of pixels on
3730         screen to the number of pixels in the original decoded video in each
3731         dimension. Zero is a special value; it will adjust the video to the output
3732         window/drawable (in windowed mode) or the entire screen.
3733         Note that not all video outputs support scaling.
3734         @param f_factor: the scaling factor, or zero.
3735         '''
3736         return libvlc_video_set_scale(self, f_factor)
3737
3738
3739     def video_get_aspect_ratio(self):
3740         '''Get current video aspect ratio.
3741         @return: the video aspect ratio or None if unspecified (the result must be released with free() or L{free}()).
3742         '''
3743         return libvlc_video_get_aspect_ratio(self)
3744
3745
3746     def video_set_aspect_ratio(self, psz_aspect):
3747         '''Set new video aspect ratio.
3748         @param psz_aspect: new video aspect-ratio or None to reset to default @note Invalid aspect ratios are ignored.
3749         '''
3750         return libvlc_video_set_aspect_ratio(self, str_to_bytes(psz_aspect))
3751
3752
3753     def video_update_viewpoint(self, p_viewpoint, b_absolute):
3754         '''Update the video viewpoint information.
3755         @note: It is safe to call this function before the media player is started.
3756         @param p_viewpoint: video viewpoint allocated via L{video_new_viewpoint}().
3757         @param b_absolute: if true replace the old viewpoint with the new one. If false, increase/decrease it.
3758         @return: -1 in case of error, 0 otherwise @note the values are set asynchronously, it will be used by the next frame displayed.
3759         @version: LibVLC 3.0.0 and later.
3760         '''
3761         return libvlc_video_update_viewpoint(self, p_viewpoint, b_absolute)
3762
3763
3764     def video_get_spu(self):
3765         '''Get current video subtitle.
3766         @return: the video subtitle selected, or -1 if none.
3767         '''
3768         return libvlc_video_get_spu(self)
3769
3770
3771     def video_get_spu_count(self):
3772         '''Get the number of available video subtitles.
3773         @return: the number of available video subtitles.
3774         '''
3775         return libvlc_video_get_spu_count(self)
3776
3777
3778     def video_set_spu(self, i_spu):
3779         '''Set new video subtitle.
3780         @param i_spu: video subtitle track to select (i_id from track description).
3781         @return: 0 on success, -1 if out of range.
3782         '''
3783         return libvlc_video_set_spu(self, i_spu)
3784
3785
3786     def video_get_spu_delay(self):
3787         '''Get the current subtitle delay. Positive values means subtitles are being
3788         displayed later, negative values earlier.
3789         @return: time (in microseconds) the display of subtitles is being delayed.
3790         @version: LibVLC 2.0.0 or later.
3791         '''
3792         return libvlc_video_get_spu_delay(self)
3793
3794
3795     def video_set_spu_delay(self, i_delay):
3796         '''Set the subtitle delay. This affects the timing of when the subtitle will
3797         be displayed. Positive values result in subtitles being displayed later,
3798         while negative values will result in subtitles being displayed earlier.
3799         The subtitle delay will be reset to zero each time the media changes.
3800         @param i_delay: time (in microseconds) the display of subtitles should be delayed.
3801         @return: 0 on success, -1 on error.
3802         @version: LibVLC 2.0.0 or later.
3803         '''
3804         return libvlc_video_set_spu_delay(self, i_delay)
3805
3806
3807     def video_get_crop_geometry(self):
3808         '''Get current crop filter geometry.
3809         @return: the crop filter geometry or None if unset.
3810         '''
3811         return libvlc_video_get_crop_geometry(self)
3812
3813
3814     def video_set_crop_geometry(self, psz_geometry):
3815         '''Set new crop filter geometry.
3816         @param psz_geometry: new crop filter geometry (None to unset).
3817         '''
3818         return libvlc_video_set_crop_geometry(self, str_to_bytes(psz_geometry))
3819
3820
3821     def video_get_teletext(self):
3822         '''Get current teletext page requested or 0 if it's disabled.
3823         Teletext is disabled by default, call L{video_set_teletext}() to enable
3824         it.
3825         @return: the current teletext page requested.
3826         '''
3827         return libvlc_video_get_teletext(self)
3828
3829
3830     def video_set_teletext(self, i_page):
3831         '''Set new teletext page to retrieve.
3832         This function can also be used to send a teletext key.
3833         @param i_page: teletex page number requested. This value can be 0 to disable teletext, a number in the range ]0;1000[ to show the requested page, or a \ref L{TeletextKey}. 100 is the default teletext page.
3834         '''
3835         return libvlc_video_set_teletext(self, i_page)
3836
3837
3838     def video_get_track_count(self):
3839         '''Get number of available video tracks.
3840         @return: the number of available video tracks (int).
3841         '''
3842         return libvlc_video_get_track_count(self)
3843
3844
3845     def video_get_track(self):
3846         '''Get current video track.
3847         @return: the video track ID (int) or -1 if no active input.
3848         '''
3849         return libvlc_video_get_track(self)
3850
3851
3852     def video_set_track(self, i_track):
3853         '''Set video track.
3854         @param i_track: the track ID (i_id field from track description).
3855         @return: 0 on success, -1 if out of range.
3856         '''
3857         return libvlc_video_set_track(self, i_track)
3858
3859
3860     def video_take_snapshot(self, num, psz_filepath, i_width, i_height):
3861         '''Take a snapshot of the current video window.
3862         If i_width AND i_height is 0, original size is used.
3863         If i_width XOR i_height is 0, original aspect-ratio is preserved.
3864         @param num: number of video output (typically 0 for the first/only one).
3865         @param psz_filepath: the path of a file or a folder to save the screenshot into.
3866         @param i_width: the snapshot's width.
3867         @param i_height: the snapshot's height.
3868         @return: 0 on success, -1 if the video was not found.
3869         '''
3870         return libvlc_video_take_snapshot(self, num, str_to_bytes(psz_filepath), i_width, i_height)
3871
3872
3873