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