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