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