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