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