· 6 years ago · Apr 17, 2019, 02:08 PM
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
28U{http://wiki.videolan.org/LibVLC}.
29
30You can find the documentation and a README file with some examples
31at U{http://www.olivieraubert.net/vlc/python-ctypes/}.
32
33Basically, the most important class is L{Instance}, which is used
34to create a libvlc instance. From this instance, you then create
35L{MediaPlayer} and L{MediaListPlayer} instances.
36
37Alternatively, you may create instances of the L{MediaPlayer} and
38L{MediaListPlayer} class directly and an instance of L{Instance}
39will be implicitly created. The latter can be obtained using the
40C{get_instance} method of L{MediaPlayer} and L{MediaListPlayer}.
41"""
42
43import ctypes
44from ctypes.util import find_library
45import os
46import sys
47import functools
48
49# Used by EventManager in override.py
50from inspect import getargspec
51
52import logging
53logger = logging.getLogger(__name__)
54
55__version__ = "2.2.6100"
56__libvlc_version__ = "2.2.6"
57__generator_version__ = "1.0"
58build_date = "Wed Oct 11 15:37:38 2017 2.2.6"
59
60# The libvlc doc states that filenames are expected to be in UTF8, do
61# not rely on sys.getfilesystemencoding() which will be confused,
62# esp. on windows.
63DEFAULT_ENCODING = 'utf-8'
64
65if 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
86else:
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
112def find_lib():
113 dll = None
114 plugin_path = os.environ.get('PYTHON_VLC_MODULE_PATH', None)
115 if 'PYTHON_VLC_LIB_PATH' in os.environ:
116 try:
117 dll = ctypes.CDLL(os.environ['PYTHON_VLC_LIB_PATH'])
118 except OSError:
119 logger.error("Cannot load lib specified by PYTHON_VLC_LIB_PATH env. variable")
120 sys.exit(1)
121 if plugin_path and not os.path.isdir(plugin_path):
122 logger.error("Invalid PYTHON_VLC_MODULE_PATH specified. Please fix.")
123 sys.exit(1)
124 if dll is not None:
125 return dll, plugin_path
126
127 if sys.platform.startswith('linux'):
128 p = find_library('vlc')
129 try:
130 dll = ctypes.CDLL(p)
131 except OSError: # may fail
132 dll = ctypes.CDLL('libvlc.so.5')
133 elif sys.platform.startswith('win'):
134 libname = 'libvlc.dll'
135 p = find_library(libname)
136 if p is None:
137 try: # some registry settings
138 # leaner than win32api, win32con
139 if PYTHON3:
140 import winreg as w
141 else:
142 import _winreg as w
143 for r in w.HKEY_LOCAL_MACHINE, w.HKEY_CURRENT_USER:
144 try:
145 r = w.OpenKey(r, 'Software\\VideoLAN\\VLC')
146 plugin_path, _ = w.QueryValueEx(r, 'InstallDir')
147 w.CloseKey(r)
148 break
149 except w.error:
150 pass
151 except ImportError: # no PyWin32
152 pass
153 if plugin_path is None:
154 # try some standard locations.
155 programfiles = os.environ["ProgramFiles"]
156 homedir = os.environ["HOMEDRIVE"]
157 for p in ('{programfiles}\\VideoLan{libname}', '{homedir}:\\VideoLan{libname}',
158 '{programfiles}{libname}', '{homedir}:{libname}'):
159 p = p.format(homedir = homedir,
160 programfiles = programfiles,
161 libname = '\\VLC\\' + libname)
162 if os.path.exists(p):
163 plugin_path = os.path.dirname(p)
164 break
165 if plugin_path is not None: # try loading
166 p = os.getcwd()
167 os.chdir(plugin_path)
168 # if chdir failed, this will raise an exception
169 dll = ctypes.CDLL(libname)
170 # restore cwd after dll has been loaded
171 os.chdir(p)
172 else: # may fail
173 dll = ctypes.CDLL(libname)
174 else:
175 plugin_path = os.path.dirname(p)
176 dll = ctypes.CDLL(p)
177
178 elif sys.platform.startswith('darwin'):
179 # FIXME: should find a means to configure path
180 d = '/Applications/VLC.app/Contents/MacOS/'
181 p = d + 'lib/libvlc.dylib'
182 if os.path.exists(p):
183 dll = ctypes.CDLL(p)
184 for p in ('modules', 'plugins'):
185 p = d + p
186 if os.path.isdir(p):
187 plugin_path = p
188 break
189 else: # hope, some PATH is set...
190 dll = ctypes.CDLL('libvlc.dylib')
191
192 else:
193 raise NotImplementedError('%s: %s not supported' % (sys.argv[0], sys.platform))
194
195 return (dll, plugin_path)
196
197# plugin_path used on win32 and MacOS in override.py
198dll, plugin_path = find_lib()
199
200class VLCException(Exception):
201 """Exception raised by libvlc methods.
202 """
203 pass
204
205try:
206 _Ints = (int, long)
207except NameError: # no long in Python 3+
208 _Ints = int
209_Seqs = (list, tuple)
210
211# Used for handling *event_manager() methods.
212class memoize_parameterless(object):
213 """Decorator. Caches a parameterless method's return value each time it is called.
214
215 If called later with the same arguments, the cached value is returned
216 (not reevaluated).
217 Adapted from https://wiki.python.org/moin/PythonDecoratorLibrary
218 """
219 def __init__(self, func):
220 self.func = func
221 self._cache = {}
222
223 def __call__(self, obj):
224 try:
225 return self._cache[obj]
226 except KeyError:
227 v = self._cache[obj] = self.func(obj)
228 return v
229
230 def __repr__(self):
231 """Return the function's docstring.
232 """
233 return self.func.__doc__
234
235 def __get__(self, obj, objtype):
236 """Support instance methods.
237 """
238 return functools.partial(self.__call__, obj)
239
240# Default instance. It is used to instanciate classes directly in the
241# OO-wrapper.
242_default_instance = None
243
244def get_default_instance():
245 """Return the default VLC.Instance.
246 """
247 global _default_instance
248 if _default_instance is None:
249 _default_instance = Instance()
250 return _default_instance
251
252_Cfunctions = {} # from LibVLC __version__
253_Globals = globals() # sys.modules[__name__].__dict__
254
255def _Cfunction(name, flags, errcheck, *types):
256 """(INTERNAL) New ctypes function binding.
257 """
258 if hasattr(dll, name) and name in _Globals:
259 p = ctypes.CFUNCTYPE(*types)
260 f = p((name, dll), flags)
261 if errcheck is not None:
262 f.errcheck = errcheck
263 # replace the Python function
264 # in this module, but only when
265 # running as python -O or -OO
266 if __debug__:
267 _Cfunctions[name] = f
268 else:
269 _Globals[name] = f
270 return f
271 raise NameError('no function %r' % (name,))
272
273def _Cobject(cls, ctype):
274 """(INTERNAL) New instance from ctypes.
275 """
276 o = object.__new__(cls)
277 o._as_parameter_ = ctype
278 return o
279
280def _Constructor(cls, ptr=_internal_guard):
281 """(INTERNAL) New wrapper from ctypes.
282 """
283 if ptr == _internal_guard:
284 raise VLCException("(INTERNAL) ctypes class. You should get references for this class through methods of the LibVLC API.")
285 if ptr is None or ptr == 0:
286 return None
287 return _Cobject(cls, ctypes.c_void_p(ptr))
288
289class _Cstruct(ctypes.Structure):
290 """(INTERNAL) Base class for ctypes structures.
291 """
292 _fields_ = [] # list of 2-tuples ('name', ctyptes.<type>)
293
294 def __str__(self):
295 l = [' %s:\t%s' % (n, getattr(self, n)) for n, _ in self._fields_]
296 return '\n'.join([self.__class__.__name__] + l)
297
298 def __repr__(self):
299 return '%s.%s' % (self.__class__.__module__, self)
300
301class _Ctype(object):
302 """(INTERNAL) Base class for ctypes.
303 """
304 @staticmethod
305 def from_param(this): # not self
306 """(INTERNAL) ctypes parameter conversion method.
307 """
308 if this is None:
309 return None
310 return this._as_parameter_
311
312class ListPOINTER(object):
313 """Just like a POINTER but accept a list of ctype as an argument.
314 """
315 def __init__(self, etype):
316 self.etype = etype
317
318 def from_param(self, param):
319 if isinstance(param, _Seqs):
320 return (self.etype * len(param))(*param)
321 else:
322 return ctypes.POINTER(param)
323
324# errcheck functions for some native functions.
325def string_result(result, func, arguments):
326 """Errcheck function. Returns a string and frees the original pointer.
327
328 It assumes the result is a char *.
329 """
330 if result:
331 # make a python string copy
332 s = bytes_to_str(ctypes.string_at(result))
333 # free original string ptr
334 libvlc_free(result)
335 return s
336 return None
337
338def class_result(classname):
339 """Errcheck function. Returns a function that creates the specified class.
340 """
341 def wrap_errcheck(result, func, arguments):
342 if result is None:
343 return None
344 return classname(result)
345 return wrap_errcheck
346
347# Wrapper for the opaque struct libvlc_log_t
348class Log(ctypes.Structure):
349 pass
350Log_ptr = ctypes.POINTER(Log)
351
352# FILE* ctypes wrapper, copied from
353# http://svn.python.org/projects/ctypes/trunk/ctypeslib/ctypeslib/contrib/pythonhdr.py
354class FILE(ctypes.Structure):
355 pass
356FILE_ptr = ctypes.POINTER(FILE)
357
358if PYTHON3:
359 PyFile_FromFd = ctypes.pythonapi.PyFile_FromFd
360 PyFile_FromFd.restype = ctypes.py_object
361 PyFile_FromFd.argtypes = [ctypes.c_int,
362 ctypes.c_char_p,
363 ctypes.c_char_p,
364 ctypes.c_int,
365 ctypes.c_char_p,
366 ctypes.c_char_p,
367 ctypes.c_char_p,
368 ctypes.c_int ]
369
370 PyFile_AsFd = ctypes.pythonapi.PyObject_AsFileDescriptor
371 PyFile_AsFd.restype = ctypes.c_int
372 PyFile_AsFd.argtypes = [ctypes.py_object]
373else:
374 PyFile_FromFile = ctypes.pythonapi.PyFile_FromFile
375 PyFile_FromFile.restype = ctypes.py_object
376 PyFile_FromFile.argtypes = [FILE_ptr,
377 ctypes.c_char_p,
378 ctypes.c_char_p,
379 ctypes.CFUNCTYPE(ctypes.c_int, FILE_ptr)]
380
381 PyFile_AsFile = ctypes.pythonapi.PyFile_AsFile
382 PyFile_AsFile.restype = FILE_ptr
383 PyFile_AsFile.argtypes = [ctypes.py_object]
384
385 # Generated enum types #
386
387class _Enum(ctypes.c_uint):
388 '''(INTERNAL) Base class
389 '''
390 _enum_names_ = {}
391
392 def __str__(self):
393 n = self._enum_names_.get(self.value, '') or ('FIXME_(%r)' % (self.value,))
394 return '.'.join((self.__class__.__name__, n))
395
396 def __hash__(self):
397 return self.value
398
399 def __repr__(self):
400 return '.'.join((self.__class__.__module__, self.__str__()))
401
402 def __eq__(self, other):
403 return ( (isinstance(other, _Enum) and self.value == other.value)
404 or (isinstance(other, _Ints) and self.value == other) )
405
406 def __ne__(self, other):
407 return not self.__eq__(other)
408
409class LogLevel(_Enum):
410 '''Logging messages level.
411\note future libvlc versions may define new levels.
412 '''
413 _enum_names_ = {
414 0: 'DEBUG',
415 2: 'NOTICE',
416 3: 'WARNING',
417 4: 'ERROR',
418 }
419LogLevel.DEBUG = LogLevel(0)
420LogLevel.ERROR = LogLevel(4)
421LogLevel.NOTICE = LogLevel(2)
422LogLevel.WARNING = LogLevel(3)
423
424class EventType(_Enum):
425 '''Event types.
426 '''
427 _enum_names_ = {
428 0: 'MediaMetaChanged',
429 1: 'MediaSubItemAdded',
430 2: 'MediaDurationChanged',
431 3: 'MediaParsedChanged',
432 4: 'MediaFreed',
433 5: 'MediaStateChanged',
434 6: 'MediaSubItemTreeAdded',
435 0x100: 'MediaPlayerMediaChanged',
436 257: 'MediaPlayerNothingSpecial',
437 258: 'MediaPlayerOpening',
438 259: 'MediaPlayerBuffering',
439 260: 'MediaPlayerPlaying',
440 261: 'MediaPlayerPaused',
441 262: 'MediaPlayerStopped',
442 263: 'MediaPlayerForward',
443 264: 'MediaPlayerBackward',
444 265: 'MediaPlayerEndReached',
445 266: 'MediaPlayerEncounteredError',
446 267: 'MediaPlayerTimeChanged',
447 268: 'MediaPlayerPositionChanged',
448 269: 'MediaPlayerSeekableChanged',
449 270: 'MediaPlayerPausableChanged',
450 271: 'MediaPlayerTitleChanged',
451 272: 'MediaPlayerSnapshotTaken',
452 273: 'MediaPlayerLengthChanged',
453 274: 'MediaPlayerVout',
454 275: 'MediaPlayerScrambledChanged',
455 279: 'MediaPlayerCorked',
456 280: 'MediaPlayerUncorked',
457 281: 'MediaPlayerMuted',
458 282: 'MediaPlayerUnmuted',
459 283: 'MediaPlayerAudioVolume',
460 0x200: 'MediaListItemAdded',
461 513: 'MediaListWillAddItem',
462 514: 'MediaListItemDeleted',
463 515: 'MediaListWillDeleteItem',
464 0x300: 'MediaListViewItemAdded',
465 769: 'MediaListViewWillAddItem',
466 770: 'MediaListViewItemDeleted',
467 771: 'MediaListViewWillDeleteItem',
468 0x400: 'MediaListPlayerPlayed',
469 1025: 'MediaListPlayerNextItemSet',
470 1026: 'MediaListPlayerStopped',
471 0x500: 'MediaDiscovererStarted',
472 1281: 'MediaDiscovererEnded',
473 0x600: 'VlmMediaAdded',
474 1537: 'VlmMediaRemoved',
475 1538: 'VlmMediaChanged',
476 1539: 'VlmMediaInstanceStarted',
477 1540: 'VlmMediaInstanceStopped',
478 1541: 'VlmMediaInstanceStatusInit',
479 1542: 'VlmMediaInstanceStatusOpening',
480 1543: 'VlmMediaInstanceStatusPlaying',
481 1544: 'VlmMediaInstanceStatusPause',
482 1545: 'VlmMediaInstanceStatusEnd',
483 1546: 'VlmMediaInstanceStatusError',
484 }
485EventType.MediaDiscovererEnded = EventType(1281)
486EventType.MediaDiscovererStarted = EventType(0x500)
487EventType.MediaDurationChanged = EventType(2)
488EventType.MediaFreed = EventType(4)
489EventType.MediaListItemAdded = EventType(0x200)
490EventType.MediaListItemDeleted = EventType(514)
491EventType.MediaListPlayerNextItemSet = EventType(1025)
492EventType.MediaListPlayerPlayed = EventType(0x400)
493EventType.MediaListPlayerStopped = EventType(1026)
494EventType.MediaListViewItemAdded = EventType(0x300)
495EventType.MediaListViewItemDeleted = EventType(770)
496EventType.MediaListViewWillAddItem = EventType(769)
497EventType.MediaListViewWillDeleteItem = EventType(771)
498EventType.MediaListWillAddItem = EventType(513)
499EventType.MediaListWillDeleteItem = EventType(515)
500EventType.MediaMetaChanged = EventType(0)
501EventType.MediaParsedChanged = EventType(3)
502EventType.MediaPlayerAudioVolume = EventType(283)
503EventType.MediaPlayerBackward = EventType(264)
504EventType.MediaPlayerBuffering = EventType(259)
505EventType.MediaPlayerCorked = EventType(279)
506EventType.MediaPlayerEncounteredError = EventType(266)
507EventType.MediaPlayerEndReached = EventType(265)
508EventType.MediaPlayerForward = EventType(263)
509EventType.MediaPlayerLengthChanged = EventType(273)
510EventType.MediaPlayerMediaChanged = EventType(0x100)
511EventType.MediaPlayerMuted = EventType(281)
512EventType.MediaPlayerNothingSpecial = EventType(257)
513EventType.MediaPlayerOpening = EventType(258)
514EventType.MediaPlayerPausableChanged = EventType(270)
515EventType.MediaPlayerPaused = EventType(261)
516EventType.MediaPlayerPlaying = EventType(260)
517EventType.MediaPlayerPositionChanged = EventType(268)
518EventType.MediaPlayerScrambledChanged = EventType(275)
519EventType.MediaPlayerSeekableChanged = EventType(269)
520EventType.MediaPlayerSnapshotTaken = EventType(272)
521EventType.MediaPlayerStopped = EventType(262)
522EventType.MediaPlayerTimeChanged = EventType(267)
523EventType.MediaPlayerTitleChanged = EventType(271)
524EventType.MediaPlayerUncorked = EventType(280)
525EventType.MediaPlayerUnmuted = EventType(282)
526EventType.MediaPlayerVout = EventType(274)
527EventType.MediaStateChanged = EventType(5)
528EventType.MediaSubItemAdded = EventType(1)
529EventType.MediaSubItemTreeAdded = EventType(6)
530EventType.VlmMediaAdded = EventType(0x600)
531EventType.VlmMediaChanged = EventType(1538)
532EventType.VlmMediaInstanceStarted = EventType(1539)
533EventType.VlmMediaInstanceStatusEnd = EventType(1545)
534EventType.VlmMediaInstanceStatusError = EventType(1546)
535EventType.VlmMediaInstanceStatusInit = EventType(1541)
536EventType.VlmMediaInstanceStatusOpening = EventType(1542)
537EventType.VlmMediaInstanceStatusPause = EventType(1544)
538EventType.VlmMediaInstanceStatusPlaying = EventType(1543)
539EventType.VlmMediaInstanceStopped = EventType(1540)
540EventType.VlmMediaRemoved = EventType(1537)
541
542class Meta(_Enum):
543 '''Meta data types.
544 '''
545 _enum_names_ = {
546 0: 'Title',
547 1: 'Artist',
548 2: 'Genre',
549 3: 'Copyright',
550 4: 'Album',
551 5: 'TrackNumber',
552 6: 'Description',
553 7: 'Rating',
554 8: 'Date',
555 9: 'Setting',
556 10: 'URL',
557 11: 'Language',
558 12: 'NowPlaying',
559 13: 'Publisher',
560 14: 'EncodedBy',
561 15: 'ArtworkURL',
562 16: 'TrackID',
563 17: 'TrackTotal',
564 18: 'Director',
565 19: 'Season',
566 20: 'Episode',
567 21: 'ShowName',
568 22: 'Actors',
569 }
570Meta.Actors = Meta(22)
571Meta.Album = Meta(4)
572Meta.Artist = Meta(1)
573Meta.ArtworkURL = Meta(15)
574Meta.Copyright = Meta(3)
575Meta.Date = Meta(8)
576Meta.Description = Meta(6)
577Meta.Director = Meta(18)
578Meta.EncodedBy = Meta(14)
579Meta.Episode = Meta(20)
580Meta.Genre = Meta(2)
581Meta.Language = Meta(11)
582Meta.NowPlaying = Meta(12)
583Meta.Publisher = Meta(13)
584Meta.Rating = Meta(7)
585Meta.Season = Meta(19)
586Meta.Setting = Meta(9)
587Meta.ShowName = Meta(21)
588Meta.Title = Meta(0)
589Meta.TrackID = Meta(16)
590Meta.TrackNumber = Meta(5)
591Meta.TrackTotal = Meta(17)
592Meta.URL = Meta(10)
593
594class State(_Enum):
595 '''Note the order of libvlc_state_t enum must match exactly the order of
596See mediacontrol_playerstatus, See input_state_e enums,
597and videolan.libvlc.state (at bindings/cil/src/media.cs).
598expected states by web plugins are:
599idle/close=0, opening=1, buffering=2, playing=3, paused=4,
600stopping=5, ended=6, error=7.
601 '''
602 _enum_names_ = {
603 0: 'NothingSpecial',
604 1: 'Opening',
605 2: 'Buffering',
606 3: 'Playing',
607 4: 'Paused',
608 5: 'Stopped',
609 6: 'Ended',
610 7: 'Error',
611 }
612State.Buffering = State(2)
613State.Ended = State(6)
614State.Error = State(7)
615State.NothingSpecial = State(0)
616State.Opening = State(1)
617State.Paused = State(4)
618State.Playing = State(3)
619State.Stopped = State(5)
620
621class TrackType(_Enum):
622 '''N/A
623 '''
624 _enum_names_ = {
625 -1: 'unknown',
626 0: 'audio',
627 1: 'video',
628 2: 'text',
629 }
630TrackType.audio = TrackType(0)
631TrackType.text = TrackType(2)
632TrackType.unknown = TrackType(-1)
633TrackType.video = TrackType(1)
634
635class VideoMarqueeOption(_Enum):
636 '''Marq options definition.
637 '''
638 _enum_names_ = {
639 0: 'Enable',
640 1: 'Text',
641 2: 'Color',
642 3: 'Opacity',
643 4: 'Position',
644 5: 'Refresh',
645 6: 'Size',
646 7: 'Timeout',
647 8: 'marquee_X',
648 9: 'marquee_Y',
649 }
650VideoMarqueeOption.Color = VideoMarqueeOption(2)
651VideoMarqueeOption.Enable = VideoMarqueeOption(0)
652VideoMarqueeOption.Opacity = VideoMarqueeOption(3)
653VideoMarqueeOption.Position = VideoMarqueeOption(4)
654VideoMarqueeOption.Refresh = VideoMarqueeOption(5)
655VideoMarqueeOption.Size = VideoMarqueeOption(6)
656VideoMarqueeOption.Text = VideoMarqueeOption(1)
657VideoMarqueeOption.Timeout = VideoMarqueeOption(7)
658VideoMarqueeOption.marquee_X = VideoMarqueeOption(8)
659VideoMarqueeOption.marquee_Y = VideoMarqueeOption(9)
660
661class NavigateMode(_Enum):
662 '''Navigation mode.
663 '''
664 _enum_names_ = {
665 0: 'activate',
666 1: 'up',
667 2: 'down',
668 3: 'left',
669 4: 'right',
670 }
671NavigateMode.activate = NavigateMode(0)
672NavigateMode.down = NavigateMode(2)
673NavigateMode.left = NavigateMode(3)
674NavigateMode.right = NavigateMode(4)
675NavigateMode.up = NavigateMode(1)
676
677class Position(_Enum):
678 '''Enumeration of values used to set position (e.g. of video title).
679 '''
680 _enum_names_ = {
681 -1: 'disable',
682 0: 'center',
683 1: 'left',
684 2: 'right',
685 3: 'top',
686 4: 'left',
687 5: 'right',
688 6: 'bottom',
689 7: 'left',
690 8: 'right',
691 }
692Position.bottom = Position(6)
693Position.center = Position(0)
694Position.disable = Position(-1)
695Position.left = Position(1)
696Position.left = Position(4)
697Position.left = Position(7)
698Position.right = Position(2)
699Position.right = Position(5)
700Position.right = Position(8)
701Position.top = Position(3)
702
703class VideoLogoOption(_Enum):
704 '''Option values for libvlc_video_{get,set}_logo_{int,string}.
705 '''
706 _enum_names_ = {
707 0: 'enable',
708 1: 'file',
709 2: 'logo_x',
710 3: 'logo_y',
711 4: 'delay',
712 5: 'repeat',
713 6: 'opacity',
714 7: 'position',
715 }
716VideoLogoOption.delay = VideoLogoOption(4)
717VideoLogoOption.enable = VideoLogoOption(0)
718VideoLogoOption.file = VideoLogoOption(1)
719VideoLogoOption.logo_x = VideoLogoOption(2)
720VideoLogoOption.logo_y = VideoLogoOption(3)
721VideoLogoOption.opacity = VideoLogoOption(6)
722VideoLogoOption.position = VideoLogoOption(7)
723VideoLogoOption.repeat = VideoLogoOption(5)
724
725class VideoAdjustOption(_Enum):
726 '''Option values for libvlc_video_{get,set}_adjust_{int,float,bool}.
727 '''
728 _enum_names_ = {
729 0: 'Enable',
730 1: 'Contrast',
731 2: 'Brightness',
732 3: 'Hue',
733 4: 'Saturation',
734 5: 'Gamma',
735 }
736VideoAdjustOption.Brightness = VideoAdjustOption(2)
737VideoAdjustOption.Contrast = VideoAdjustOption(1)
738VideoAdjustOption.Enable = VideoAdjustOption(0)
739VideoAdjustOption.Gamma = VideoAdjustOption(5)
740VideoAdjustOption.Hue = VideoAdjustOption(3)
741VideoAdjustOption.Saturation = VideoAdjustOption(4)
742
743class AudioOutputDeviceTypes(_Enum):
744 '''Audio device types.
745 '''
746 _enum_names_ = {
747 -1: 'Error',
748 1: 'Mono',
749 2: 'Stereo',
750 4: '_2F2R',
751 5: '_3F2R',
752 6: '_5_1',
753 7: '_6_1',
754 8: '_7_1',
755 10: 'SPDIF',
756 }
757AudioOutputDeviceTypes.Error = AudioOutputDeviceTypes(-1)
758AudioOutputDeviceTypes.Mono = AudioOutputDeviceTypes(1)
759AudioOutputDeviceTypes.SPDIF = AudioOutputDeviceTypes(10)
760AudioOutputDeviceTypes.Stereo = AudioOutputDeviceTypes(2)
761AudioOutputDeviceTypes._2F2R = AudioOutputDeviceTypes(4)
762AudioOutputDeviceTypes._3F2R = AudioOutputDeviceTypes(5)
763AudioOutputDeviceTypes._5_1 = AudioOutputDeviceTypes(6)
764AudioOutputDeviceTypes._6_1 = AudioOutputDeviceTypes(7)
765AudioOutputDeviceTypes._7_1 = AudioOutputDeviceTypes(8)
766
767class AudioOutputChannel(_Enum):
768 '''Audio channels.
769 '''
770 _enum_names_ = {
771 -1: 'Error',
772 1: 'Stereo',
773 2: 'RStereo',
774 3: 'Left',
775 4: 'Right',
776 5: 'Dolbys',
777 }
778AudioOutputChannel.Dolbys = AudioOutputChannel(5)
779AudioOutputChannel.Error = AudioOutputChannel(-1)
780AudioOutputChannel.Left = AudioOutputChannel(3)
781AudioOutputChannel.RStereo = AudioOutputChannel(2)
782AudioOutputChannel.Right = AudioOutputChannel(4)
783AudioOutputChannel.Stereo = AudioOutputChannel(1)
784
785class PlaybackMode(_Enum):
786 '''Defines playback modes for playlist.
787 '''
788 _enum_names_ = {
789 0: 'default',
790 1: 'loop',
791 2: 'repeat',
792 }
793PlaybackMode.default = PlaybackMode(0)
794PlaybackMode.loop = PlaybackMode(1)
795PlaybackMode.repeat = PlaybackMode(2)
796
797class Callback(ctypes.c_void_p):
798 """Callback function notification.
799 @param p_event: the event triggering the callback.
800 """
801 pass
802class LogCb(ctypes.c_void_p):
803 """Callback prototype for LibVLC log message handler.
804 @param data: data pointer as given to L{libvlc_log_set}().
805 @param level: message level (@ref enum libvlc_log_level).
806 @param ctx: message context (meta-information about the message).
807 @param fmt: printf() format string (as defined by ISO C11).
808 @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.
809 """
810 pass
811class VideoLockCb(ctypes.c_void_p):
812 """Callback prototype to allocate and lock a picture buffer.
813 Whenever a new video frame needs to be decoded, the lock callback is
814 invoked. Depending on the video chroma, one or three pixel planes of
815 adequate dimensions must be returned via the second parameter. Those
816 planes must be aligned on 32-bytes boundaries.
817 @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
818 @param planes: start address of the pixel planes (LibVLC allocates the array of void pointers, this callback must initialize the array) [OUT].
819 @return: a private pointer for the display and unlock callbacks to identify the picture buffers.
820 """
821 pass
822class VideoUnlockCb(ctypes.c_void_p):
823 """Callback prototype to unlock a picture buffer.
824 When the video frame decoding is complete, the unlock callback is invoked.
825 This callback might not be needed at all. It is only an indication that the
826 application can now read the pixel values if it needs to.
827 @warning: A picture buffer is unlocked after the picture is decoded,
828 but before the picture is displayed.
829 @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
830 @param picture: private pointer returned from the @ref libvlc_video_lock_cb callback [IN].
831 @param planes: pixel planes as defined by the @ref libvlc_video_lock_cb callback (this parameter is only for convenience) [IN].
832 """
833 pass
834class VideoDisplayCb(ctypes.c_void_p):
835 """Callback prototype to display a picture.
836 When the video frame needs to be shown, as determined by the media playback
837 clock, the display callback is invoked.
838 @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
839 @param picture: private pointer returned from the @ref libvlc_video_lock_cb callback [IN].
840 """
841 pass
842class VideoFormatCb(ctypes.c_void_p):
843 """Callback prototype to configure picture buffers format.
844 This callback gets the format of the video as output by the video decoder
845 and the chain of video filters (if any). It can opt to change any parameter
846 as it needs. In that case, LibVLC will attempt to convert the video format
847 (rescaling and chroma conversion) but these operations can be CPU intensive.
848 @param opaque: pointer to the private pointer passed to L{libvlc_video_set_callbacks}() [IN/OUT].
849 @param chroma: pointer to the 4 bytes video format identifier [IN/OUT].
850 @param width: pointer to the pixel width [IN/OUT].
851 @param height: pointer to the pixel height [IN/OUT].
852 @param pitches: table of scanline pitches in bytes for each pixel plane (the table is allocated by LibVLC) [OUT].
853 @return: lines table of scanlines count for each plane.
854 """
855 pass
856class VideoCleanupCb(ctypes.c_void_p):
857 """Callback prototype to configure picture buffers format.
858 @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() (and possibly modified by @ref libvlc_video_format_cb) [IN].
859 """
860 pass
861class AudioPlayCb(ctypes.c_void_p):
862 """Callback prototype for audio playback.
863 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
864 @param samples: pointer to the first audio sample to play back [IN].
865 @param count: number of audio samples to play back.
866 @param pts: expected play time stamp (see libvlc_delay()).
867 """
868 pass
869class AudioPauseCb(ctypes.c_void_p):
870 """Callback prototype for audio pause.
871 @note: The pause callback is never called if the audio is already paused.
872 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
873 @param pts: time stamp of the pause request (should be elapsed already).
874 """
875 pass
876class AudioResumeCb(ctypes.c_void_p):
877 """Callback prototype for audio resumption (i.e. restart from pause).
878 @note: The resume callback is never called if the audio is not paused.
879 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
880 @param pts: time stamp of the resumption request (should be elapsed already).
881 """
882 pass
883class AudioFlushCb(ctypes.c_void_p):
884 """Callback prototype for audio buffer flush
885 (i.e. discard all pending buffers and stop playback as soon as possible).
886 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
887 """
888 pass
889class AudioDrainCb(ctypes.c_void_p):
890 """Callback prototype for audio buffer drain
891 (i.e. wait for pending buffers to be played).
892 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
893 """
894 pass
895class AudioSetVolumeCb(ctypes.c_void_p):
896 """Callback prototype for audio volume change.
897 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
898 @param volume: software volume (1. = nominal, 0. = mute).
899 @param mute: muted flag.
900 """
901 pass
902class AudioSetupCb(ctypes.c_void_p):
903 """Callback prototype to setup the audio playback.
904 This is called when the media player needs to create a new audio output.
905 @param opaque: pointer to the data pointer passed to L{libvlc_audio_set_callbacks}() [IN/OUT].
906 @param format: 4 bytes sample format [IN/OUT].
907 @param rate: sample rate [IN/OUT].
908 @param channels: channels count [IN/OUT].
909 @return: 0 on success, anything else to skip audio playback.
910 """
911 pass
912class AudioCleanupCb(ctypes.c_void_p):
913 """Callback prototype for audio playback cleanup.
914 This is called when the media player no longer needs an audio output.
915 @param opaque: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
916 """
917 pass
918class CallbackDecorators(object):
919 "Class holding various method decorators for callback functions."
920 Callback = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p)
921 Callback.__doc__ = '''Callback function notification.
922 @param p_event: the event triggering the callback.
923 '''
924 LogCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int, Log_ptr, ctypes.c_char_p, ctypes.c_void_p)
925 LogCb.__doc__ = '''Callback prototype for LibVLC log message handler.
926 @param data: data pointer as given to L{libvlc_log_set}().
927 @param level: message level (@ref enum libvlc_log_level).
928 @param ctx: message context (meta-information about the message).
929 @param fmt: printf() format string (as defined by ISO C11).
930 @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.
931 '''
932 VideoLockCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.POINTER(ctypes.c_void_p))
933 VideoLockCb.__doc__ = '''Callback prototype to allocate and lock a picture buffer.
934 Whenever a new video frame needs to be decoded, the lock callback is
935 invoked. Depending on the video chroma, one or three pixel planes of
936 adequate dimensions must be returned via the second parameter. Those
937 planes must be aligned on 32-bytes boundaries.
938 @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
939 @param planes: start address of the pixel planes (LibVLC allocates the array of void pointers, this callback must initialize the array) [OUT].
940 @return: a private pointer for the display and unlock callbacks to identify the picture buffers.
941 '''
942 VideoUnlockCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.POINTER(ctypes.c_void_p))
943 VideoUnlockCb.__doc__ = '''Callback prototype to unlock a picture buffer.
944 When the video frame decoding is complete, the unlock callback is invoked.
945 This callback might not be needed at all. It is only an indication that the
946 application can now read the pixel values if it needs to.
947 @warning: A picture buffer is unlocked after the picture is decoded,
948 but before the picture is displayed.
949 @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
950 @param picture: private pointer returned from the @ref libvlc_video_lock_cb callback [IN].
951 @param planes: pixel planes as defined by the @ref libvlc_video_lock_cb callback (this parameter is only for convenience) [IN].
952 '''
953 VideoDisplayCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p)
954 VideoDisplayCb.__doc__ = '''Callback prototype to display a picture.
955 When the video frame needs to be shown, as determined by the media playback
956 clock, the display callback is invoked.
957 @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() [IN].
958 @param picture: private pointer returned from the @ref libvlc_video_lock_cb callback [IN].
959 '''
960 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))
961 VideoFormatCb.__doc__ = '''Callback prototype to configure picture buffers format.
962 This callback gets the format of the video as output by the video decoder
963 and the chain of video filters (if any). It can opt to change any parameter
964 as it needs. In that case, LibVLC will attempt to convert the video format
965 (rescaling and chroma conversion) but these operations can be CPU intensive.
966 @param opaque: pointer to the private pointer passed to L{libvlc_video_set_callbacks}() [IN/OUT].
967 @param chroma: pointer to the 4 bytes video format identifier [IN/OUT].
968 @param width: pointer to the pixel width [IN/OUT].
969 @param height: pointer to the pixel height [IN/OUT].
970 @param pitches: table of scanline pitches in bytes for each pixel plane (the table is allocated by LibVLC) [OUT].
971 @return: lines table of scanlines count for each plane.
972 '''
973 VideoCleanupCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)
974 VideoCleanupCb.__doc__ = '''Callback prototype to configure picture buffers format.
975 @param opaque: private pointer as passed to L{libvlc_video_set_callbacks}() (and possibly modified by @ref libvlc_video_format_cb) [IN].
976 '''
977 AudioPlayCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint, ctypes.c_int64)
978 AudioPlayCb.__doc__ = '''Callback prototype for audio playback.
979 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
980 @param samples: pointer to the first audio sample to play back [IN].
981 @param count: number of audio samples to play back.
982 @param pts: expected play time stamp (see libvlc_delay()).
983 '''
984 AudioPauseCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int64)
985 AudioPauseCb.__doc__ = '''Callback prototype for audio pause.
986 @note: The pause callback is never called if the audio is already paused.
987 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
988 @param pts: time stamp of the pause request (should be elapsed already).
989 '''
990 AudioResumeCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int64)
991 AudioResumeCb.__doc__ = '''Callback prototype for audio resumption (i.e. restart from pause).
992 @note: The resume callback is never called if the audio is not paused.
993 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
994 @param pts: time stamp of the resumption request (should be elapsed already).
995 '''
996 AudioFlushCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int64)
997 AudioFlushCb.__doc__ = '''Callback prototype for audio buffer flush
998 (i.e. discard all pending buffers and stop playback as soon as possible).
999 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1000 '''
1001 AudioDrainCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)
1002 AudioDrainCb.__doc__ = '''Callback prototype for audio buffer drain
1003 (i.e. wait for pending buffers to be played).
1004 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1005 '''
1006 AudioSetVolumeCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p, ctypes.c_float, ctypes.c_bool)
1007 AudioSetVolumeCb.__doc__ = '''Callback prototype for audio volume change.
1008 @param data: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1009 @param volume: software volume (1. = nominal, 0. = mute).
1010 @param mute: muted flag.
1011 '''
1012 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))
1013 AudioSetupCb.__doc__ = '''Callback prototype to setup the audio playback.
1014 This is called when the media player needs to create a new audio output.
1015 @param opaque: pointer to the data pointer passed to L{libvlc_audio_set_callbacks}() [IN/OUT].
1016 @param format: 4 bytes sample format [IN/OUT].
1017 @param rate: sample rate [IN/OUT].
1018 @param channels: channels count [IN/OUT].
1019 @return: 0 on success, anything else to skip audio playback.
1020 '''
1021 AudioCleanupCb = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)
1022 AudioCleanupCb.__doc__ = '''Callback prototype for audio playback cleanup.
1023 This is called when the media player no longer needs an audio output.
1024 @param opaque: data pointer as passed to L{libvlc_audio_set_callbacks}() [IN].
1025 '''
1026cb = CallbackDecorators
1027 # End of generated enum types #
1028
1029 # From libvlc_structures.h
1030
1031class AudioOutput(_Cstruct):
1032
1033 def __str__(self):
1034 return '%s(%s:%s)' % (self.__class__.__name__, self.name, self.description)
1035
1036AudioOutput._fields_ = [ # recursive struct
1037 ('name', ctypes.c_char_p),
1038 ('description', ctypes.c_char_p),
1039 ('next', ctypes.POINTER(AudioOutput)),
1040 ]
1041
1042class LogMessage(_Cstruct):
1043 _fields_ = [
1044 ('size', ctypes.c_uint ),
1045 ('severity', ctypes.c_int ),
1046 ('type', ctypes.c_char_p),
1047 ('name', ctypes.c_char_p),
1048 ('header', ctypes.c_char_p),
1049 ('message', ctypes.c_char_p),
1050 ]
1051
1052 def __init__(self):
1053 super(LogMessage, self).__init__()
1054 self.size = ctypes.sizeof(self)
1055
1056 def __str__(self):
1057 return '%s(%d:%s): %s' % (self.__class__.__name__, self.severity, self.type, self.message)
1058
1059class MediaEvent(_Cstruct):
1060 _fields_ = [
1061 ('media_name', ctypes.c_char_p),
1062 ('instance_name', ctypes.c_char_p),
1063 ]
1064
1065class MediaStats(_Cstruct):
1066 _fields_ = [
1067 ('read_bytes', ctypes.c_int ),
1068 ('input_bitrate', ctypes.c_float),
1069 ('demux_read_bytes', ctypes.c_int ),
1070 ('demux_bitrate', ctypes.c_float),
1071 ('demux_corrupted', ctypes.c_int ),
1072 ('demux_discontinuity', ctypes.c_int ),
1073 ('decoded_video', ctypes.c_int ),
1074 ('decoded_audio', ctypes.c_int ),
1075 ('displayed_pictures', ctypes.c_int ),
1076 ('lost_pictures', ctypes.c_int ),
1077 ('played_abuffers', ctypes.c_int ),
1078 ('lost_abuffers', ctypes.c_int ),
1079 ('sent_packets', ctypes.c_int ),
1080 ('sent_bytes', ctypes.c_int ),
1081 ('send_bitrate', ctypes.c_float),
1082 ]
1083
1084class MediaTrackInfo(_Cstruct):
1085 _fields_ = [
1086 ('codec', ctypes.c_uint32),
1087 ('id', ctypes.c_int ),
1088 ('type', TrackType ),
1089 ('profile', ctypes.c_int ),
1090 ('level', ctypes.c_int ),
1091 ('channels_or_height', ctypes.c_uint ),
1092 ('rate_or_width', ctypes.c_uint ),
1093 ]
1094
1095class AudioTrack(_Cstruct):
1096 _fields_ = [
1097 ('channels', ctypes.c_uint),
1098 ('rate', ctypes.c_uint),
1099 ]
1100
1101class VideoTrack(_Cstruct):
1102 _fields_ = [
1103 ('height', ctypes.c_uint),
1104 ('width', ctypes.c_uint),
1105 ('sar_num', ctypes.c_uint),
1106 ('sar_den', ctypes.c_uint),
1107 ('frame_rate_num', ctypes.c_uint),
1108 ('frame_rate_den', ctypes.c_uint),
1109 ]
1110
1111class SubtitleTrack(_Cstruct):
1112 _fields_ = [
1113 ('encoding', ctypes.c_char_p),
1114 ]
1115
1116class MediaTrackTracks(ctypes.Union):
1117 _fields_ = [
1118 ('audio', ctypes.POINTER(AudioTrack)),
1119 ('video', ctypes.POINTER(VideoTrack)),
1120 ('subtitle', ctypes.POINTER(SubtitleTrack)),
1121 ]
1122
1123class MediaTrack(_Cstruct):
1124 _anonymous_ = ("u",)
1125 _fields_ = [
1126 ('codec', ctypes.c_uint32),
1127 ('original_fourcc', ctypes.c_uint32),
1128 ('id', ctypes.c_int ),
1129 ('type', TrackType ),
1130 ('profile', ctypes.c_int ),
1131 ('level', ctypes.c_int ),
1132
1133 ('u', MediaTrackTracks),
1134 ('bitrate', ctypes.c_uint),
1135 ('language', ctypes.c_char_p),
1136 ('description', ctypes.c_char_p),
1137 ]
1138
1139class PlaylistItem(_Cstruct):
1140 _fields_ = [
1141 ('id', ctypes.c_int ),
1142 ('uri', ctypes.c_char_p),
1143 ('name', ctypes.c_char_p),
1144 ]
1145
1146 def __str__(self):
1147 return '%s #%d %s (uri %s)' % (self.__class__.__name__, self.id, self.name, self.uri)
1148
1149class Position(object):
1150 """Enum-like, immutable window position constants.
1151
1152 See e.g. VideoMarqueeOption.Position.
1153 """
1154 Center = 0
1155 Left = 1
1156 CenterLeft = 1
1157 Right = 2
1158 CenterRight = 2
1159 Top = 4
1160 TopCenter = 4
1161 TopLeft = 5
1162 TopRight = 6
1163 Bottom = 8
1164 BottomCenter = 8
1165 BottomLeft = 9
1166 BottomRight = 10
1167 def __init__(self, *unused):
1168 raise TypeError('constants only')
1169 def __setattr__(self, *unused): #PYCHOK expected
1170 raise TypeError('immutable constants')
1171
1172class Rectangle(_Cstruct):
1173 _fields_ = [
1174 ('top', ctypes.c_int),
1175 ('left', ctypes.c_int),
1176 ('bottom', ctypes.c_int),
1177 ('right', ctypes.c_int),
1178 ]
1179
1180class TrackDescription(_Cstruct):
1181
1182 def __str__(self):
1183 return '%s(%d:%s)' % (self.__class__.__name__, self.id, self.name)
1184
1185TrackDescription._fields_ = [ # recursive struct
1186 ('id', ctypes.c_int ),
1187 ('name', ctypes.c_char_p),
1188 ('next', ctypes.POINTER(TrackDescription)),
1189 ]
1190
1191def track_description_list(head):
1192 """Convert a TrackDescription linked list to a Python list (and release the former).
1193 """
1194 r = []
1195 if head:
1196 item = head
1197 while item:
1198 item = item.contents
1199 r.append((item.id, item.name))
1200 item = item.next
1201 try:
1202 libvlc_track_description_release(head)
1203 except NameError:
1204 libvlc_track_description_list_release(head)
1205
1206 return r
1207
1208class EventUnion(ctypes.Union):
1209 _fields_ = [
1210 ('meta_type', ctypes.c_uint ),
1211 ('new_child', ctypes.c_uint ),
1212 ('new_duration', ctypes.c_longlong),
1213 ('new_status', ctypes.c_int ),
1214 ('media', ctypes.c_void_p ),
1215 ('new_state', ctypes.c_uint ),
1216 # FIXME: Media instance
1217 ('new_cache', ctypes.c_float ),
1218 ('new_position', ctypes.c_float ),
1219 ('new_time', ctypes.c_longlong),
1220 ('new_title', ctypes.c_int ),
1221 ('new_seekable', ctypes.c_longlong),
1222 ('new_pausable', ctypes.c_longlong),
1223 ('new_scrambled', ctypes.c_longlong),
1224 ('new_count', ctypes.c_longlong),
1225 # FIXME: Skipped MediaList and MediaListView...
1226 ('filename', ctypes.c_char_p ),
1227 ('new_length', ctypes.c_longlong),
1228 ('media_event', MediaEvent ),
1229 ]
1230
1231class Event(_Cstruct):
1232 _fields_ = [
1233 ('type', EventType ),
1234 ('object', ctypes.c_void_p),
1235 ('u', EventUnion ),
1236 ]
1237
1238class ModuleDescription(_Cstruct):
1239
1240 def __str__(self):
1241 return '%s %s (%s)' % (self.__class__.__name__, self.shortname, self.name)
1242
1243ModuleDescription._fields_ = [ # recursive struct
1244 ('name', ctypes.c_char_p),
1245 ('shortname', ctypes.c_char_p),
1246 ('longname', ctypes.c_char_p),
1247 ('help', ctypes.c_char_p),
1248 ('next', ctypes.POINTER(ModuleDescription)),
1249 ]
1250
1251def module_description_list(head):
1252 """Convert a ModuleDescription linked list to a Python list (and release the former).
1253 """
1254 r = []
1255 if head:
1256 item = head
1257 while item:
1258 item = item.contents
1259 r.append((item.name, item.shortname, item.longname, item.help))
1260 item = item.next
1261 libvlc_module_description_list_release(head)
1262 return r
1263
1264class AudioOutputDevice(_Cstruct):
1265
1266 def __str__(self):
1267 return '%s(%d:%s)' % (self.__class__.__name__, self.id, self.name)
1268
1269AudioOutputDevice._fields_ = [ # recursive struct
1270 ('next', ctypes.POINTER(AudioOutputDevice)),
1271 ('device', ctypes.c_char_p ),
1272 ('description', ctypes.c_char_p),
1273 ]
1274
1275class TitleDescription(_Cstruct):
1276 _fields = [
1277 ('duration', ctypes.c_longlong),
1278 ('name', ctypes.c_char_p),
1279 ('menu', ctypes.c_bool),
1280 ]
1281
1282class ChapterDescription(_Cstruct):
1283 _fields = [
1284 ('time_offset', ctypes.c_longlong),
1285 ('duration', ctypes.c_longlong),
1286 ('name', ctypes.c_char_p),
1287 ]
1288
1289class VideoViewpoint(_Cstruct):
1290 _fields = [
1291 ('yaw', ctypes.c_float),
1292 ('pitch', ctypes.c_float),
1293 ('roll', ctypes.c_float),
1294 ('field_of_view', ctypes.c_float),
1295 ]
1296
1297# This struct depends on the MediaSlaveType enum that is defined only
1298# in > 2.2
1299if 'MediaSlaveType' in locals():
1300 class MediaSlave(_Cstruct):
1301 _fields = [
1302 ('psz_uri', ctypes.c_char_p),
1303 ('i_type', MediaSlaveType),
1304 ('i_priority', ctypes.c_uint)
1305 ]
1306
1307class RDDescription(_Cstruct):
1308 _fields = [
1309 ('name', ctypes.c_char_p),
1310 ('longname', ctypes.c_char_p)
1311 ]
1312
1313# End of header.py #
1314class EventManager(_Ctype):
1315 '''Create an event manager with callback handler.
1316
1317 This class interposes the registration and handling of
1318 event notifications in order to (a) remove the need for
1319 decorating each callback functions with the decorator
1320 '@callbackmethod', (b) allow any number of positional
1321 and/or keyword arguments to the callback (in addition
1322 to the Event instance) and (c) to preserve the Python
1323 objects such that the callback and argument objects
1324 remain alive (i.e. are not garbage collected) until
1325 B{after} the notification has been unregistered.
1326
1327 @note: Only a single notification can be registered
1328 for each event type in an EventManager instance.
1329
1330 '''
1331
1332 _callback_handler = None
1333 _callbacks = {}
1334
1335 def __new__(cls, ptr=_internal_guard):
1336 if ptr == _internal_guard:
1337 raise VLCException("(INTERNAL) ctypes class.\nYou should get a reference to EventManager through the MediaPlayer.event_manager() method.")
1338 return _Constructor(cls, ptr)
1339
1340 def event_attach(self, eventtype, callback, *args, **kwds):
1341 """Register an event notification.
1342
1343 @param eventtype: the desired event type to be notified about.
1344 @param callback: the function to call when the event occurs.
1345 @param args: optional positional arguments for the callback.
1346 @param kwds: optional keyword arguments for the callback.
1347 @return: 0 on success, ENOMEM on error.
1348
1349 @note: The callback function must have at least one argument,
1350 an Event instance. Any other, optional positional and keyword
1351 arguments are in B{addition} to the first one.
1352 """
1353 if not isinstance(eventtype, EventType):
1354 raise VLCException("%s required: %r" % ('EventType', eventtype))
1355 if not hasattr(callback, '__call__'): # callable()
1356 raise VLCException("%s required: %r" % ('callable', callback))
1357 # check that the callback expects arguments
1358 if not any(getargspec(callback)[:2]): # list(...)
1359 raise VLCException("%s required: %r" % ('argument', callback))
1360
1361 if self._callback_handler is None:
1362 _called_from_ctypes = ctypes.CFUNCTYPE(None, ctypes.POINTER(Event), ctypes.c_void_p)
1363 @_called_from_ctypes
1364 def _callback_handler(event, k):
1365 """(INTERNAL) handle callback call from ctypes.
1366
1367 @note: We cannot simply make this an EventManager
1368 method since ctypes does not prepend self as the
1369 first parameter, hence this closure.
1370 """
1371 try: # retrieve Python callback and arguments
1372 call, args, kwds = self._callbacks[k]
1373 # deref event.contents to simplify callback code
1374 call(event.contents, *args, **kwds)
1375 except KeyError: # detached?
1376 pass
1377 self._callback_handler = _callback_handler
1378 self._callbacks = {}
1379
1380 k = eventtype.value
1381 r = libvlc_event_attach(self, k, self._callback_handler, k)
1382 if not r:
1383 self._callbacks[k] = (callback, args, kwds)
1384 return r
1385
1386 def event_detach(self, eventtype):
1387 """Unregister an event notification.
1388
1389 @param eventtype: the event type notification to be removed.
1390 """
1391 if not isinstance(eventtype, EventType):
1392 raise VLCException("%s required: %r" % ('EventType', eventtype))
1393
1394 k = eventtype.value
1395 if k in self._callbacks:
1396 del self._callbacks[k] # remove, regardless of libvlc return value
1397 libvlc_event_detach(self, k, self._callback_handler, k)
1398
1399class Instance(_Ctype):
1400 '''Create a new Instance instance.
1401
1402 It may take as parameter either:
1403 - a string
1404 - a list of strings as first parameters
1405 - the parameters given as the constructor parameters (must be strings)
1406
1407 '''
1408
1409 def __new__(cls, *args):
1410 if len(args) == 1:
1411 # Only 1 arg. It is either a C pointer, or an arg string,
1412 # or a tuple.
1413 i = args[0]
1414 if isinstance(i, _Ints):
1415 return _Constructor(cls, i)
1416 elif isinstance(i, basestring):
1417 args = i.strip().split()
1418 elif isinstance(i, _Seqs):
1419 args = list(i)
1420 else:
1421 raise VLCException('Instance %r' % (args,))
1422 else:
1423 args = list(args)
1424
1425 if not args: # no parameters passed
1426 args = ['vlc']
1427 elif args[0] != 'vlc':
1428 args.insert(0, 'vlc')
1429
1430 if plugin_path is not None:
1431 # set plugin_path if detected, win32 and MacOS,
1432 # if the user did not specify it itself.
1433 os.environ.setdefault('VLC_PLUGIN_PATH', plugin_path)
1434
1435 if PYTHON3:
1436 args = [ str_to_bytes(a) for a in args ]
1437 return libvlc_new(len(args), args)
1438
1439 def media_player_new(self, uri=None):
1440 """Create a new MediaPlayer instance.
1441
1442 @param uri: an optional URI to play in the player.
1443 """
1444 p = libvlc_media_player_new(self)
1445 if uri:
1446 p.set_media(self.media_new(uri))
1447 p._instance = self
1448 return p
1449
1450 def media_list_player_new(self):
1451 """Create a new MediaListPlayer instance.
1452 """
1453 p = libvlc_media_list_player_new(self)
1454 p._instance = self
1455 return p
1456
1457 def media_new(self, mrl, *options):
1458 """Create a new Media instance.
1459
1460 If mrl contains a colon (:) preceded by more than 1 letter, it
1461 will be treated as a URL. Else, it will be considered as a
1462 local path. If you need more control, directly use
1463 media_new_location/media_new_path methods.
1464
1465 Options can be specified as supplementary string parameters,
1466 but note that many options cannot be set at the media level,
1467 and rather at the Instance level. For instance, the marquee
1468 filter must be specified when creating the vlc.Instance or
1469 vlc.MediaPlayer.
1470
1471 Alternatively, options can be added to the media using the
1472 Media.add_options method (with the same limitation).
1473
1474 @param options: optional media option=value strings
1475 """
1476 if ':' in mrl and mrl.index(':') > 1:
1477 # Assume it is a URL
1478 m = libvlc_media_new_location(self, str_to_bytes(mrl))
1479 else:
1480 # Else it should be a local path.
1481 m = libvlc_media_new_path(self, str_to_bytes(os.path.normpath(mrl)))
1482 for o in options:
1483 libvlc_media_add_option(m, str_to_bytes(o))
1484 m._instance = self
1485 return m
1486
1487 def media_list_new(self, mrls=None):
1488 """Create a new MediaList instance.
1489 @param mrls: optional list of MRL strings
1490 """
1491 l = libvlc_media_list_new(self)
1492 # We should take the lock, but since we did not leak the
1493 # reference, nobody else can access it.
1494 if mrls:
1495 for m in mrls:
1496 l.add_media(m)
1497 l._instance = self
1498 return l
1499
1500 def audio_output_enumerate_devices(self):
1501 """Enumerate the defined audio output devices.
1502
1503 @return: list of dicts {name:, description:, devices:}
1504 """
1505 r = []
1506 head = libvlc_audio_output_list_get(self)
1507 if head:
1508 i = head
1509 while i:
1510 i = i.contents
1511 d = [{'id': libvlc_audio_output_device_id (self, i.name, d),
1512 'longname': libvlc_audio_output_device_longname(self, i.name, d)}
1513 for d in range(libvlc_audio_output_device_count (self, i.name))]
1514 r.append({'name': i.name, 'description': i.description, 'devices': d})
1515 i = i.next
1516 libvlc_audio_output_list_release(head)
1517 return r
1518
1519 def audio_filter_list_get(self):
1520 """Returns a list of available audio filters.
1521
1522 """
1523 return module_description_list(libvlc_audio_filter_list_get(self))
1524
1525 def video_filter_list_get(self):
1526 """Returns a list of available video filters.
1527
1528 """
1529 return module_description_list(libvlc_video_filter_list_get(self))
1530
1531
1532
1533 def release(self):
1534 '''Decrement the reference count of a libvlc instance, and destroy it
1535 if it reaches zero.
1536 '''
1537 return libvlc_release(self)
1538
1539
1540 def retain(self):
1541 '''Increments the reference count of a libvlc instance.
1542 The initial reference count is 1 after L{new}() returns.
1543 '''
1544 return libvlc_retain(self)
1545
1546
1547 def add_intf(self, name):
1548 '''Try to start a user interface for the libvlc instance.
1549 @param name: interface name, or None for default.
1550 @return: 0 on success, -1 on error.
1551 '''
1552 return libvlc_add_intf(self, str_to_bytes(name))
1553
1554
1555 def wait(self):
1556 '''Waits until an interface causes the instance to exit.
1557 You should start at least one interface first, using L{add_intf}().
1558 '''
1559 return libvlc_wait(self)
1560
1561
1562 def set_user_agent(self, name, http):
1563 '''Sets the application name. LibVLC passes this as the user agent string
1564 when a protocol requires it.
1565 @param name: human-readable application name, e.g. "FooBar player 1.2.3".
1566 @param http: HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0".
1567 @version: LibVLC 1.1.1 or later.
1568 '''
1569 return libvlc_set_user_agent(self, str_to_bytes(name), str_to_bytes(http))
1570
1571
1572 def set_app_id(self, id, version, icon):
1573 '''Sets some meta-information about the application.
1574 See also L{set_user_agent}().
1575 @param id: Java-style application identifier, e.g. "com.acme.foobar".
1576 @param version: application version numbers, e.g. "1.2.3".
1577 @param icon: application icon name, e.g. "foobar".
1578 @version: LibVLC 2.1.0 or later.
1579 '''
1580 return libvlc_set_app_id(self, str_to_bytes(id), str_to_bytes(version), str_to_bytes(icon))
1581
1582
1583 def log_unset(self):
1584 '''Unsets the logging callback for a LibVLC instance. This is rarely needed:
1585 the callback is implicitly unset when the instance is destroyed.
1586 This function will wait for any pending callbacks invocation to complete
1587 (causing a deadlock if called from within the callback).
1588 @version: LibVLC 2.1.0 or later.
1589 '''
1590 return libvlc_log_unset(self)
1591
1592
1593 def log_set(self, data, p_instance):
1594 '''Sets the logging callback for a LibVLC instance.
1595 This function is thread-safe: it will wait for any pending callbacks
1596 invocation to complete.
1597 @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.
1598 @param p_instance: libvlc instance.
1599 @version: LibVLC 2.1.0 or later.
1600 '''
1601 return libvlc_log_set(self, data, p_instance)
1602
1603
1604 def log_set_file(self, stream):
1605 '''Sets up logging to a file.
1606 @param stream: FILE pointer opened for writing (the FILE pointer must remain valid until L{log_unset}()).
1607 @version: LibVLC 2.1.0 or later.
1608 '''
1609 return libvlc_log_set_file(self, stream)
1610
1611
1612 def get_log_verbosity(self):
1613 '''Always returns minus one.
1614 This function is only provided for backward compatibility.
1615 @return: always -1.
1616 '''
1617 return libvlc_get_log_verbosity(self)
1618
1619
1620 def set_log_verbosity(self, level):
1621 '''This function does nothing.
1622 It is only provided for backward compatibility.
1623 @param level: ignored.
1624 '''
1625 return libvlc_set_log_verbosity(self, level)
1626
1627
1628 def log_open(self):
1629 '''This function does nothing useful.
1630 It is only provided for backward compatibility.
1631 @return: an unique pointer or None on error.
1632 '''
1633 return libvlc_log_open(self)
1634
1635
1636 def media_discoverer_new_from_name(self, psz_name):
1637 '''Discover media service by name.
1638 @param psz_name: service name.
1639 @return: media discover object or None in case of error.
1640 '''
1641 return libvlc_media_discoverer_new_from_name(self, str_to_bytes(psz_name))
1642
1643
1644 def media_library_new(self):
1645 '''Create an new Media Library object.
1646 @return: a new object or None on error.
1647 '''
1648 return libvlc_media_library_new(self)
1649
1650
1651 def vlm_release(self):
1652 '''Release the vlm instance related to the given L{Instance}.
1653 '''
1654 return libvlc_vlm_release(self)
1655
1656
1657 def vlm_add_broadcast(self, psz_name, psz_input, psz_output, i_options, ppsz_options, b_enabled, b_loop):
1658 '''Add a broadcast, with one input.
1659 @param psz_name: the name of the new broadcast.
1660 @param psz_input: the input MRL.
1661 @param psz_output: the output MRL (the parameter to the "sout" variable).
1662 @param i_options: number of additional options.
1663 @param ppsz_options: additional options.
1664 @param b_enabled: boolean for enabling the new broadcast.
1665 @param b_loop: Should this broadcast be played in loop ?
1666 @return: 0 on success, -1 on error.
1667 '''
1668 return libvlc_vlm_add_broadcast(self, str_to_bytes(psz_name), str_to_bytes(psz_input), str_to_bytes(psz_output), i_options, ppsz_options, b_enabled, b_loop)
1669
1670
1671 def vlm_add_vod(self, psz_name, psz_input, i_options, ppsz_options, b_enabled, psz_mux):
1672 '''Add a vod, with one input.
1673 @param psz_name: the name of the new vod media.
1674 @param psz_input: the input MRL.
1675 @param i_options: number of additional options.
1676 @param ppsz_options: additional options.
1677 @param b_enabled: boolean for enabling the new vod.
1678 @param psz_mux: the muxer of the vod media.
1679 @return: 0 on success, -1 on error.
1680 '''
1681 return libvlc_vlm_add_vod(self, str_to_bytes(psz_name), str_to_bytes(psz_input), i_options, ppsz_options, b_enabled, str_to_bytes(psz_mux))
1682
1683
1684 def vlm_del_media(self, psz_name):
1685 '''Delete a media (VOD or broadcast).
1686 @param psz_name: the media to delete.
1687 @return: 0 on success, -1 on error.
1688 '''
1689 return libvlc_vlm_del_media(self, str_to_bytes(psz_name))
1690
1691
1692 def vlm_set_enabled(self, psz_name, b_enabled):
1693 '''Enable or disable a media (VOD or broadcast).
1694 @param psz_name: the media to work on.
1695 @param b_enabled: the new status.
1696 @return: 0 on success, -1 on error.
1697 '''
1698 return libvlc_vlm_set_enabled(self, str_to_bytes(psz_name), b_enabled)
1699
1700
1701 def vlm_set_output(self, psz_name, psz_output):
1702 '''Set the output for a media.
1703 @param psz_name: the media to work on.
1704 @param psz_output: the output MRL (the parameter to the "sout" variable).
1705 @return: 0 on success, -1 on error.
1706 '''
1707 return libvlc_vlm_set_output(self, str_to_bytes(psz_name), str_to_bytes(psz_output))
1708
1709
1710 def vlm_set_input(self, psz_name, psz_input):
1711 '''Set a media's input MRL. This will delete all existing inputs and
1712 add the specified one.
1713 @param psz_name: the media to work on.
1714 @param psz_input: the input MRL.
1715 @return: 0 on success, -1 on error.
1716 '''
1717 return libvlc_vlm_set_input(self, str_to_bytes(psz_name), str_to_bytes(psz_input))
1718
1719
1720 def vlm_add_input(self, psz_name, psz_input):
1721 '''Add a media's input MRL. This will add the specified one.
1722 @param psz_name: the media to work on.
1723 @param psz_input: the input MRL.
1724 @return: 0 on success, -1 on error.
1725 '''
1726 return libvlc_vlm_add_input(self, str_to_bytes(psz_name), str_to_bytes(psz_input))
1727
1728
1729 def vlm_set_loop(self, psz_name, b_loop):
1730 '''Set a media's loop status.
1731 @param psz_name: the media to work on.
1732 @param b_loop: the new status.
1733 @return: 0 on success, -1 on error.
1734 '''
1735 return libvlc_vlm_set_loop(self, str_to_bytes(psz_name), b_loop)
1736
1737
1738 def vlm_set_mux(self, psz_name, psz_mux):
1739 '''Set a media's vod muxer.
1740 @param psz_name: the media to work on.
1741 @param psz_mux: the new muxer.
1742 @return: 0 on success, -1 on error.
1743 '''
1744 return libvlc_vlm_set_mux(self, str_to_bytes(psz_name), str_to_bytes(psz_mux))
1745
1746
1747 def vlm_change_media(self, psz_name, psz_input, psz_output, i_options, ppsz_options, b_enabled, b_loop):
1748 '''Edit the parameters of a media. This will delete all existing inputs and
1749 add the specified one.
1750 @param psz_name: the name of the new broadcast.
1751 @param psz_input: the input MRL.
1752 @param psz_output: the output MRL (the parameter to the "sout" variable).
1753 @param i_options: number of additional options.
1754 @param ppsz_options: additional options.
1755 @param b_enabled: boolean for enabling the new broadcast.
1756 @param b_loop: Should this broadcast be played in loop ?
1757 @return: 0 on success, -1 on error.
1758 '''
1759 return libvlc_vlm_change_media(self, str_to_bytes(psz_name), str_to_bytes(psz_input), str_to_bytes(psz_output), i_options, ppsz_options, b_enabled, b_loop)
1760
1761
1762 def vlm_play_media(self, psz_name):
1763 '''Play the named broadcast.
1764 @param psz_name: the name of the broadcast.
1765 @return: 0 on success, -1 on error.
1766 '''
1767 return libvlc_vlm_play_media(self, str_to_bytes(psz_name))
1768
1769
1770 def vlm_stop_media(self, psz_name):
1771 '''Stop the named broadcast.
1772 @param psz_name: the name of the broadcast.
1773 @return: 0 on success, -1 on error.
1774 '''
1775 return libvlc_vlm_stop_media(self, str_to_bytes(psz_name))
1776
1777
1778 def vlm_pause_media(self, psz_name):
1779 '''Pause the named broadcast.
1780 @param psz_name: the name of the broadcast.
1781 @return: 0 on success, -1 on error.
1782 '''
1783 return libvlc_vlm_pause_media(self, str_to_bytes(psz_name))
1784
1785
1786 def vlm_seek_media(self, psz_name, f_percentage):
1787 '''Seek in the named broadcast.
1788 @param psz_name: the name of the broadcast.
1789 @param f_percentage: the percentage to seek to.
1790 @return: 0 on success, -1 on error.
1791 '''
1792 return libvlc_vlm_seek_media(self, str_to_bytes(psz_name), f_percentage)
1793
1794
1795 def vlm_show_media(self, psz_name):
1796 '''Return information about the named media as a JSON
1797 string representation.
1798 This function is mainly intended for debugging use,
1799 if you want programmatic access to the state of
1800 a vlm_media_instance_t, please use the corresponding
1801 libvlc_vlm_get_media_instance_xxx -functions.
1802 Currently there are no such functions available for
1803 vlm_media_t though.
1804 @param psz_name: the name of the media, if the name is an empty string, all media is described.
1805 @return: string with information about named media, or None on error.
1806 '''
1807 return libvlc_vlm_show_media(self, str_to_bytes(psz_name))
1808
1809
1810 def vlm_get_media_instance_position(self, psz_name, i_instance):
1811 '''Get vlm_media instance position by name or instance id.
1812 @param psz_name: name of vlm media instance.
1813 @param i_instance: instance id.
1814 @return: position as float or -1. on error.
1815 '''
1816 return libvlc_vlm_get_media_instance_position(self, str_to_bytes(psz_name), i_instance)
1817
1818
1819 def vlm_get_media_instance_time(self, psz_name, i_instance):
1820 '''Get vlm_media instance time by name or instance id.
1821 @param psz_name: name of vlm media instance.
1822 @param i_instance: instance id.
1823 @return: time as integer or -1 on error.
1824 '''
1825 return libvlc_vlm_get_media_instance_time(self, str_to_bytes(psz_name), i_instance)
1826
1827
1828 def vlm_get_media_instance_length(self, psz_name, i_instance):
1829 '''Get vlm_media instance length by name or instance id.
1830 @param psz_name: name of vlm media instance.
1831 @param i_instance: instance id.
1832 @return: length of media item or -1 on error.
1833 '''
1834 return libvlc_vlm_get_media_instance_length(self, str_to_bytes(psz_name), i_instance)
1835
1836
1837 def vlm_get_media_instance_rate(self, psz_name, i_instance):
1838 '''Get vlm_media instance playback rate by name or instance id.
1839 @param psz_name: name of vlm media instance.
1840 @param i_instance: instance id.
1841 @return: playback rate or -1 on error.
1842 '''
1843 return libvlc_vlm_get_media_instance_rate(self, str_to_bytes(psz_name), i_instance)
1844
1845
1846 def vlm_get_media_instance_title(self, psz_name, i_instance):
1847 '''Get vlm_media instance title number by name or instance id.
1848 @param psz_name: name of vlm media instance.
1849 @param i_instance: instance id.
1850 @return: title as number or -1 on error.
1851 @bug: will always return 0.
1852 '''
1853 return libvlc_vlm_get_media_instance_title(self, str_to_bytes(psz_name), i_instance)
1854
1855
1856 def vlm_get_media_instance_chapter(self, psz_name, i_instance):
1857 '''Get vlm_media instance chapter number by name or instance id.
1858 @param psz_name: name of vlm media instance.
1859 @param i_instance: instance id.
1860 @return: chapter as number or -1 on error.
1861 @bug: will always return 0.
1862 '''
1863 return libvlc_vlm_get_media_instance_chapter(self, str_to_bytes(psz_name), i_instance)
1864
1865
1866 def vlm_get_media_instance_seekable(self, psz_name, i_instance):
1867 '''Is libvlc instance seekable ?
1868 @param psz_name: name of vlm media instance.
1869 @param i_instance: instance id.
1870 @return: 1 if seekable, 0 if not, -1 if media does not exist.
1871 @bug: will always return 0.
1872 '''
1873 return libvlc_vlm_get_media_instance_seekable(self, str_to_bytes(psz_name), i_instance)
1874
1875 @memoize_parameterless
1876 def vlm_get_event_manager(self):
1877 '''Get libvlc_event_manager from a vlm media.
1878 The p_event_manager is immutable, so you don't have to hold the lock.
1879 @return: libvlc_event_manager.
1880 '''
1881 return libvlc_vlm_get_event_manager(self)
1882
1883
1884 def media_new_location(self, psz_mrl):
1885 '''Create a media with a certain given media resource location,
1886 for instance a valid URL.
1887 @note: To refer to a local file with this function,
1888 the file://... URI syntax B{must} be used (see IETF RFC3986).
1889 We recommend using L{media_new_path}() instead when dealing with
1890 local files.
1891 See L{media_release}.
1892 @param psz_mrl: the media location.
1893 @return: the newly created media or None on error.
1894 '''
1895 return libvlc_media_new_location(self, str_to_bytes(psz_mrl))
1896
1897
1898 def media_new_path(self, path):
1899 '''Create a media for a certain file path.
1900 See L{media_release}.
1901 @param path: local filesystem path.
1902 @return: the newly created media or None on error.
1903 '''
1904 return libvlc_media_new_path(self, str_to_bytes(path))
1905
1906
1907 def media_new_fd(self, fd):
1908 '''Create a media for an already open file descriptor.
1909 The file descriptor shall be open for reading (or reading and writing).
1910 Regular file descriptors, pipe read descriptors and character device
1911 descriptors (including TTYs) are supported on all platforms.
1912 Block device descriptors are supported where available.
1913 Directory descriptors are supported on systems that provide fdopendir().
1914 Sockets are supported on all platforms where they are file descriptors,
1915 i.e. all except Windows.
1916 @note: This library will B{not} automatically close the file descriptor
1917 under any circumstance. Nevertheless, a file descriptor can usually only be
1918 rendered once in a media player. To render it a second time, the file
1919 descriptor should probably be rewound to the beginning with lseek().
1920 See L{media_release}.
1921 @param fd: open file descriptor.
1922 @return: the newly created media or None on error.
1923 @version: LibVLC 1.1.5 and later.
1924 '''
1925 return libvlc_media_new_fd(self, fd)
1926
1927
1928 def media_new_as_node(self, psz_name):
1929 '''Create a media as an empty node with a given name.
1930 See L{media_release}.
1931 @param psz_name: the name of the node.
1932 @return: the new empty media or None on error.
1933 '''
1934 return libvlc_media_new_as_node(self, str_to_bytes(psz_name))
1935
1936
1937 def playlist_play(self, i_id, i_options, ppsz_options):
1938 '''Start playing (if there is any item in the playlist).
1939 Additionnal playlist item options can be specified for addition to the
1940 item before it is played.
1941 @param i_id: the item to play. If this is a negative number, the next item will be selected. Otherwise, the item with the given ID will be played.
1942 @param i_options: the number of options to add to the item.
1943 @param ppsz_options: the options to add to the item.
1944 '''
1945 return libvlc_playlist_play(self, i_id, i_options, ppsz_options)
1946
1947
1948 def audio_output_list_get(self):
1949 '''Gets the list of available audio output modules.
1950 @return: list of available audio outputs. It must be freed it with In case of error, None is returned.
1951 '''
1952 return libvlc_audio_output_list_get(self)
1953
1954
1955 def audio_output_device_count(self, psz_name):
1956 '''Backward compatibility stub. Do not use in new code.
1957 Use L{audio_output_device_list_get}() instead.
1958 @param psz_name: name.
1959 @return: always 0.
1960 '''
1961 return libvlc_audio_output_device_count(self, str_to_bytes(psz_name))
1962
1963
1964 def audio_output_device_longname(self, psz_name, int):
1965 '''Backward compatibility stub. Do not use in new code.
1966 Use L{audio_output_device_list_get}() instead.
1967 @param psz_name: name.
1968 @param int: index.
1969 @return: always None.
1970 '''
1971 return libvlc_audio_output_device_longname(self, str_to_bytes(psz_name), int)
1972
1973
1974 def audio_output_device_id(self, psz_name, int):
1975 '''Backward compatibility stub. Do not use in new code.
1976 Use L{audio_output_device_list_get}() instead.
1977 @param psz_name: name.
1978 @param int: index.
1979 @return: always None.
1980 '''
1981 return libvlc_audio_output_device_id(self, str_to_bytes(psz_name), int)
1982
1983
1984 def audio_output_device_list_get(self, aout):
1985 '''Gets a list of audio output devices for a given audio output module,
1986 See L{audio_output_device_set}().
1987 @note: Not all audio outputs support this. In particular, an empty (None)
1988 list of devices does B{not} imply that the specified audio output does
1989 not work.
1990 @note: The list might not be exhaustive.
1991 @warning: Some audio output devices in the list might not actually work in
1992 some circumstances. By default, it is recommended to not specify any
1993 explicit audio device.
1994 @param psz_aout: audio output name (as returned by L{audio_output_list_get}()).
1995 @return: A None-terminated linked list of potential audio output devices. It must be freed it with L{audio_output_device_list_release}().
1996 @version: LibVLC 2.1.0 or later.
1997 '''
1998 return libvlc_audio_output_device_list_get(self, str_to_bytes(aout))
1999
2000class LogIterator(_Ctype):
2001 '''Create a new VLC log iterator.
2002
2003 '''
2004
2005 def __new__(cls, ptr=_internal_guard):
2006 '''(INTERNAL) ctypes wrapper constructor.
2007 '''
2008 return _Constructor(cls, ptr)
2009
2010 def __iter__(self):
2011 return self
2012
2013 def next(self):
2014 if self.has_next():
2015 b = LogMessage()
2016 i = libvlc_log_iterator_next(self, b)
2017 return i.contents
2018 raise StopIteration
2019
2020 def __next__(self):
2021 return self.next()
2022
2023
2024
2025 def free(self):
2026 '''Frees memory allocated by L{log_get_iterator}().
2027 '''
2028 return libvlc_log_iterator_free(self)
2029
2030
2031 def has_next(self):
2032 '''Always returns zero.
2033 This function is only provided for backward compatibility.
2034 @return: always zero.
2035 '''
2036 return libvlc_log_iterator_has_next(self)
2037
2038class Media(_Ctype):
2039 '''Create a new Media instance.
2040
2041 Usage: Media(MRL, *options)
2042
2043 See vlc.Instance.media_new documentation for details.
2044
2045 '''
2046
2047 def __new__(cls, *args):
2048 if args:
2049 i = args[0]
2050 if isinstance(i, _Ints):
2051 return _Constructor(cls, i)
2052 if isinstance(i, Instance):
2053 return i.media_new(*args[1:])
2054
2055 o = get_default_instance().media_new(*args)
2056 return o
2057
2058 def get_instance(self):
2059 return getattr(self, '_instance', None)
2060
2061 def add_options(self, *options):
2062 """Add a list of options to the media.
2063
2064 Options must be written without the double-dash. Warning: most
2065 audio and video options, such as text renderer, have no
2066 effects on an individual media. These options must be set at
2067 the vlc.Instance or vlc.MediaPlayer instanciation.
2068
2069 @param options: optional media option=value strings
2070 """
2071 for o in options:
2072 self.add_option(o)
2073
2074 def tracks_get(self):
2075 """Get media descriptor's elementary streams description
2076 Note, you need to call L{parse}() or play the media at least once
2077 before calling this function.
2078 Not doing this will result in an empty array.
2079 The result must be freed with L{tracks_release}.
2080 @version: LibVLC 2.1.0 and later.
2081 """
2082 mediaTrack_pp = ctypes.POINTER(MediaTrack)()
2083 n = libvlc_media_tracks_get(self, ctypes.byref(mediaTrack_pp))
2084 info = ctypes.cast(mediaTrack_pp, ctypes.POINTER(ctypes.POINTER(MediaTrack) * n))
2085 try:
2086 contents = info.contents
2087 except ValueError:
2088 # Media not parsed, no info.
2089 return None
2090 tracks = ( contents[i].contents for i in range(len(contents)) )
2091 # libvlc_media_tracks_release(mediaTrack_pp, n)
2092 return tracks
2093
2094
2095
2096 def add_option(self, psz_options):
2097 '''Add an option to the media.
2098 This option will be used to determine how the media_player will
2099 read the media. This allows to use VLC's advanced
2100 reading/streaming options on a per-media basis.
2101 @note: The options are listed in 'vlc --long-help' from the command line,
2102 e.g. "-sout-all". Keep in mind that available options and their semantics
2103 vary across LibVLC versions and builds.
2104 @warning: Not all options affects L{Media} objects:
2105 Specifically, due to architectural issues most audio and video options,
2106 such as text renderer options, have no effects on an individual media.
2107 These options must be set through L{new}() instead.
2108 @param psz_options: the options (as a string).
2109 '''
2110 return libvlc_media_add_option(self, str_to_bytes(psz_options))
2111
2112
2113 def add_option_flag(self, psz_options, i_flags):
2114 '''Add an option to the media with configurable flags.
2115 This option will be used to determine how the media_player will
2116 read the media. This allows to use VLC's advanced
2117 reading/streaming options on a per-media basis.
2118 The options are detailed in vlc --long-help, for instance
2119 "--sout-all". Note that all options are not usable on medias:
2120 specifically, due to architectural issues, video-related options
2121 such as text renderer options cannot be set on a single media. They
2122 must be set on the whole libvlc instance instead.
2123 @param psz_options: the options (as a string).
2124 @param i_flags: the flags for this option.
2125 '''
2126 return libvlc_media_add_option_flag(self, str_to_bytes(psz_options), i_flags)
2127
2128
2129 def retain(self):
2130 '''Retain a reference to a media descriptor object (libvlc_media_t). Use
2131 L{release}() to decrement the reference count of a
2132 media descriptor object.
2133 '''
2134 return libvlc_media_retain(self)
2135
2136
2137 def release(self):
2138 '''Decrement the reference count of a media descriptor object. If the
2139 reference count is 0, then L{release}() will release the
2140 media descriptor object. It will send out an libvlc_MediaFreed event
2141 to all listeners. If the media descriptor object has been released it
2142 should not be used again.
2143 '''
2144 return libvlc_media_release(self)
2145
2146
2147 def get_mrl(self):
2148 '''Get the media resource locator (mrl) from a media descriptor object.
2149 @return: string with mrl of media descriptor object.
2150 '''
2151 return libvlc_media_get_mrl(self)
2152
2153
2154 def duplicate(self):
2155 '''Duplicate a media descriptor object.
2156 '''
2157 return libvlc_media_duplicate(self)
2158
2159
2160 def get_meta(self, e_meta):
2161 '''Read the meta of the media.
2162 If the media has not yet been parsed this will return None.
2163 This methods automatically calls L{parse_async}(), so after calling
2164 it you may receive a libvlc_MediaMetaChanged event. If you prefer a synchronous
2165 version ensure that you call L{parse}() before get_meta().
2166 See L{parse}
2167 See L{parse_async}
2168 See libvlc_MediaMetaChanged.
2169 @param e_meta: the meta to read.
2170 @return: the media's meta.
2171 '''
2172 return libvlc_media_get_meta(self, e_meta)
2173
2174
2175 def set_meta(self, e_meta, psz_value):
2176 '''Set the meta of the media (this function will not save the meta, call
2177 L{save_meta} in order to save the meta).
2178 @param e_meta: the meta to write.
2179 @param psz_value: the media's meta.
2180 '''
2181 return libvlc_media_set_meta(self, e_meta, str_to_bytes(psz_value))
2182
2183
2184 def save_meta(self):
2185 '''Save the meta previously set.
2186 @return: true if the write operation was successful.
2187 '''
2188 return libvlc_media_save_meta(self)
2189
2190
2191 def get_state(self):
2192 '''Get current state of media descriptor object. Possible media states
2193 are defined in libvlc_structures.c ( libvlc_NothingSpecial=0,
2194 libvlc_Opening, libvlc_Buffering, libvlc_Playing, libvlc_Paused,
2195 libvlc_Stopped, libvlc_Ended,
2196 libvlc_Error).
2197 See libvlc_state_t.
2198 @return: state of media descriptor object.
2199 '''
2200 return libvlc_media_get_state(self)
2201
2202
2203 def get_stats(self, p_stats):
2204 '''Get the current statistics about the media.
2205 @param p_stats:: structure that contain the statistics about the media (this structure must be allocated by the caller).
2206 @return: true if the statistics are available, false otherwise \libvlc_return_bool.
2207 '''
2208 return libvlc_media_get_stats(self, p_stats)
2209
2210
2211 def subitems(self):
2212 '''Get subitems of media descriptor object. This will increment
2213 the reference count of supplied media descriptor object. Use
2214 L{list_release}() to decrement the reference counting.
2215 @return: list of media descriptor subitems or None.
2216 '''
2217 return libvlc_media_subitems(self)
2218
2219 @memoize_parameterless
2220 def event_manager(self):
2221 '''Get event manager from media descriptor object.
2222 NOTE: this function doesn't increment reference counting.
2223 @return: event manager object.
2224 '''
2225 return libvlc_media_event_manager(self)
2226
2227
2228 def get_duration(self):
2229 '''Get duration (in ms) of media descriptor object item.
2230 @return: duration of media item or -1 on error.
2231 '''
2232 return libvlc_media_get_duration(self)
2233
2234
2235 def parse(self):
2236 '''Parse a media.
2237 This fetches (local) meta data and tracks information.
2238 The method is synchronous.
2239 See L{parse_async}
2240 See L{get_meta}
2241 See L{get_tracks_info}.
2242 '''
2243 return libvlc_media_parse(self)
2244
2245
2246 def parse_async(self):
2247 '''Parse a media.
2248 This fetches (local) meta data and tracks information.
2249 The method is the asynchronous of L{parse}().
2250 To track when this is over you can listen to libvlc_MediaParsedChanged
2251 event. However if the media was already parsed you will not receive this
2252 event.
2253 See L{parse}
2254 See libvlc_MediaParsedChanged
2255 See L{get_meta}
2256 See L{get_tracks_info}.
2257 '''
2258 return libvlc_media_parse_async(self)
2259
2260
2261 def is_parsed(self):
2262 '''Get Parsed status for media descriptor object.
2263 See libvlc_MediaParsedChanged.
2264 @return: true if media object has been parsed otherwise it returns false \libvlc_return_bool.
2265 '''
2266 return libvlc_media_is_parsed(self)
2267
2268
2269 def set_user_data(self, p_new_user_data):
2270 '''Sets media descriptor's user_data. user_data is specialized data
2271 accessed by the host application, VLC.framework uses it as a pointer to
2272 an native object that references a L{Media} pointer.
2273 @param p_new_user_data: pointer to user data.
2274 '''
2275 return libvlc_media_set_user_data(self, p_new_user_data)
2276
2277
2278 def get_user_data(self):
2279 '''Get media descriptor's user_data. user_data is specialized data
2280 accessed by the host application, VLC.framework uses it as a pointer to
2281 an native object that references a L{Media} pointer.
2282 '''
2283 return libvlc_media_get_user_data(self)
2284
2285
2286 def get_tracks_info(self):
2287 '''Get media descriptor's elementary streams description
2288 Note, you need to call L{parse}() or play the media at least once
2289 before calling this function.
2290 Not doing this will result in an empty array.
2291 \deprecated Use L{tracks_get} instead.
2292 @param tracks: address to store an allocated array of Elementary Streams descriptions (must be freed by the caller) [OUT].
2293 @return: the number of Elementary Streams.
2294 '''
2295 return libvlc_media_get_tracks_info(self)
2296
2297
2298 def player_new_from_media(self):
2299 '''Create a Media Player object from a Media.
2300 @return: a new media player object, or None on error.
2301 '''
2302 return libvlc_media_player_new_from_media(self)
2303
2304class MediaDiscoverer(_Ctype):
2305 '''N/A
2306 '''
2307
2308 def __new__(cls, ptr=_internal_guard):
2309 '''(INTERNAL) ctypes wrapper constructor.
2310 '''
2311 return _Constructor(cls, ptr)
2312
2313 def release(self):
2314 '''Release media discover object. If the reference count reaches 0, then
2315 the object will be released.
2316 '''
2317 return libvlc_media_discoverer_release(self)
2318
2319
2320 def localized_name(self):
2321 '''Get media service discover object its localized name.
2322 @return: localized name.
2323 '''
2324 return libvlc_media_discoverer_localized_name(self)
2325
2326
2327 def media_list(self):
2328 '''Get media service discover media list.
2329 @return: list of media items.
2330 '''
2331 return libvlc_media_discoverer_media_list(self)
2332
2333 @memoize_parameterless
2334 def event_manager(self):
2335 '''Get event manager from media service discover object.
2336 @return: event manager object.
2337 '''
2338 return libvlc_media_discoverer_event_manager(self)
2339
2340
2341 def is_running(self):
2342 '''Query if media service discover object is running.
2343 @return: true if running, false if not \libvlc_return_bool.
2344 '''
2345 return libvlc_media_discoverer_is_running(self)
2346
2347class MediaLibrary(_Ctype):
2348 '''N/A
2349 '''
2350
2351 def __new__(cls, ptr=_internal_guard):
2352 '''(INTERNAL) ctypes wrapper constructor.
2353 '''
2354 return _Constructor(cls, ptr)
2355
2356 def release(self):
2357 '''Release media library object. This functions decrements the
2358 reference count of the media library object. If it reaches 0,
2359 then the object will be released.
2360 '''
2361 return libvlc_media_library_release(self)
2362
2363
2364 def retain(self):
2365 '''Retain a reference to a media library object. This function will
2366 increment the reference counting for this object. Use
2367 L{release}() to decrement the reference count.
2368 '''
2369 return libvlc_media_library_retain(self)
2370
2371
2372 def load(self):
2373 '''Load media library.
2374 @return: 0 on success, -1 on error.
2375 '''
2376 return libvlc_media_library_load(self)
2377
2378
2379 def media_list(self):
2380 '''Get media library subitems.
2381 @return: media list subitems.
2382 '''
2383 return libvlc_media_library_media_list(self)
2384
2385class MediaList(_Ctype):
2386 '''Create a new MediaList instance.
2387
2388 Usage: MediaList(list_of_MRLs)
2389
2390 See vlc.Instance.media_list_new documentation for details.
2391
2392 '''
2393
2394 def __new__(cls, *args):
2395 if args:
2396 i = args[0]
2397 if isinstance(i, _Ints):
2398 return _Constructor(cls, i)
2399 if isinstance(i, Instance):
2400 return i.media_list_new(*args[1:])
2401
2402 o = get_default_instance().media_list_new(*args)
2403 return o
2404
2405 def get_instance(self):
2406 return getattr(self, '_instance', None)
2407
2408 def add_media(self, mrl):
2409 """Add media instance to media list.
2410
2411 The L{lock} should be held upon entering this function.
2412 @param mrl: a media instance or a MRL.
2413 @return: 0 on success, -1 if the media list is read-only.
2414 """
2415 if isinstance(mrl, basestring):
2416 mrl = (self.get_instance() or get_default_instance()).media_new(mrl)
2417 return libvlc_media_list_add_media(self, mrl)
2418
2419
2420
2421 def release(self):
2422 '''Release media list created with L{new}().
2423 '''
2424 return libvlc_media_list_release(self)
2425
2426
2427 def retain(self):
2428 '''Retain reference to a media list.
2429 '''
2430 return libvlc_media_list_retain(self)
2431
2432
2433 def set_media(self, p_md):
2434 '''Associate media instance with this media list instance.
2435 If another media instance was present it will be released.
2436 The L{lock} should NOT be held upon entering this function.
2437 @param p_md: media instance to add.
2438 '''
2439 return libvlc_media_list_set_media(self, p_md)
2440
2441
2442 def media(self):
2443 '''Get media instance from this media list instance. This action will increase
2444 the refcount on the media instance.
2445 The L{lock} should NOT be held upon entering this function.
2446 @return: media instance.
2447 '''
2448 return libvlc_media_list_media(self)
2449
2450
2451 def insert_media(self, p_md, i_pos):
2452 '''Insert media instance in media list on a position
2453 The L{lock} should be held upon entering this function.
2454 @param p_md: a media instance.
2455 @param i_pos: position in array where to insert.
2456 @return: 0 on success, -1 if the media list is read-only.
2457 '''
2458 return libvlc_media_list_insert_media(self, p_md, i_pos)
2459
2460
2461 def remove_index(self, i_pos):
2462 '''Remove media instance from media list on a position
2463 The L{lock} should be held upon entering this function.
2464 @param i_pos: position in array where to insert.
2465 @return: 0 on success, -1 if the list is read-only or the item was not found.
2466 '''
2467 return libvlc_media_list_remove_index(self, i_pos)
2468
2469
2470 def count(self):
2471 '''Get count on media list items
2472 The L{lock} should be held upon entering this function.
2473 @return: number of items in media list.
2474 '''
2475 return libvlc_media_list_count(self)
2476
2477 def __len__(self):
2478 return libvlc_media_list_count(self)
2479
2480
2481 def item_at_index(self, i_pos):
2482 '''List media instance in media list at a position
2483 The L{lock} should be held upon entering this function.
2484 @param i_pos: position in array where to insert.
2485 @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.
2486 '''
2487 return libvlc_media_list_item_at_index(self, i_pos)
2488
2489 def __getitem__(self, i):
2490 return libvlc_media_list_item_at_index(self, i)
2491
2492 def __iter__(self):
2493 for i in range(len(self)):
2494 yield self[i]
2495
2496
2497 def index_of_item(self, p_md):
2498 '''Find index position of List media instance in media list.
2499 Warning: the function will return the first matched position.
2500 The L{lock} should be held upon entering this function.
2501 @param p_md: media instance.
2502 @return: position of media instance or -1 if media not found.
2503 '''
2504 return libvlc_media_list_index_of_item(self, p_md)
2505
2506
2507 def is_readonly(self):
2508 '''This indicates if this media list is read-only from a user point of view.
2509 @return: 1 on readonly, 0 on readwrite \libvlc_return_bool.
2510 '''
2511 return libvlc_media_list_is_readonly(self)
2512
2513
2514 def lock(self):
2515 '''Get lock on media list items.
2516 '''
2517 return libvlc_media_list_lock(self)
2518
2519
2520 def unlock(self):
2521 '''Release lock on media list items
2522 The L{lock} should be held upon entering this function.
2523 '''
2524 return libvlc_media_list_unlock(self)
2525
2526 @memoize_parameterless
2527 def event_manager(self):
2528 '''Get libvlc_event_manager from this media list instance.
2529 The p_event_manager is immutable, so you don't have to hold the lock.
2530 @return: libvlc_event_manager.
2531 '''
2532 return libvlc_media_list_event_manager(self)
2533
2534class MediaListPlayer(_Ctype):
2535 '''Create a new MediaListPlayer instance.
2536
2537 It may take as parameter either:
2538 - a vlc.Instance
2539 - nothing
2540
2541 '''
2542
2543 def __new__(cls, arg=None):
2544 if arg is None:
2545 i = get_default_instance()
2546 elif isinstance(arg, Instance):
2547 i = arg
2548 elif isinstance(arg, _Ints):
2549 return _Constructor(cls, arg)
2550 else:
2551 raise TypeError('MediaListPlayer %r' % (arg,))
2552
2553 return i.media_list_player_new()
2554
2555 def get_instance(self):
2556 """Return the associated Instance.
2557 """
2558 return self._instance #PYCHOK expected
2559
2560
2561
2562 def release(self):
2563 '''Release a media_list_player after use
2564 Decrement the reference count of a media player object. If the
2565 reference count is 0, then L{release}() will
2566 release the media player object. If the media player object
2567 has been released, then it should not be used again.
2568 '''
2569 return libvlc_media_list_player_release(self)
2570
2571
2572 def retain(self):
2573 '''Retain a reference to a media player list object. Use
2574 L{release}() to decrement reference count.
2575 '''
2576 return libvlc_media_list_player_retain(self)
2577
2578 @memoize_parameterless
2579 def event_manager(self):
2580 '''Return the event manager of this media_list_player.
2581 @return: the event manager.
2582 '''
2583 return libvlc_media_list_player_event_manager(self)
2584
2585
2586 def set_media_player(self, p_mi):
2587 '''Replace media player in media_list_player with this instance.
2588 @param p_mi: media player instance.
2589 '''
2590 return libvlc_media_list_player_set_media_player(self, p_mi)
2591
2592
2593 def set_media_list(self, p_mlist):
2594 '''Set the media list associated with the player.
2595 @param p_mlist: list of media.
2596 '''
2597 return libvlc_media_list_player_set_media_list(self, p_mlist)
2598
2599
2600 def play(self):
2601 '''Play media list.
2602 '''
2603 return libvlc_media_list_player_play(self)
2604
2605
2606 def pause(self):
2607 '''Toggle pause (or resume) media list.
2608 '''
2609 return libvlc_media_list_player_pause(self)
2610
2611
2612 def is_playing(self):
2613 '''Is media list playing?
2614 @return: true for playing and false for not playing \libvlc_return_bool.
2615 '''
2616 return libvlc_media_list_player_is_playing(self)
2617
2618
2619 def get_state(self):
2620 '''Get current libvlc_state of media list player.
2621 @return: libvlc_state_t for media list player.
2622 '''
2623 return libvlc_media_list_player_get_state(self)
2624
2625
2626 def play_item_at_index(self, i_index):
2627 '''Play media list item at position index.
2628 @param i_index: index in media list to play.
2629 @return: 0 upon success -1 if the item wasn't found.
2630 '''
2631 return libvlc_media_list_player_play_item_at_index(self, i_index)
2632
2633 def __getitem__(self, i):
2634 return libvlc_media_list_player_play_item_at_index(self, i)
2635
2636 def __iter__(self):
2637 for i in range(len(self)):
2638 yield self[i]
2639
2640
2641 def play_item(self, p_md):
2642 '''Play the given media item.
2643 @param p_md: the media instance.
2644 @return: 0 upon success, -1 if the media is not part of the media list.
2645 '''
2646 return libvlc_media_list_player_play_item(self, p_md)
2647
2648
2649 def stop(self):
2650 '''Stop playing media list.
2651 '''
2652 return libvlc_media_list_player_stop(self)
2653
2654
2655 def next(self):
2656 '''Play next item from media list.
2657 @return: 0 upon success -1 if there is no next item.
2658 '''
2659 return libvlc_media_list_player_next(self)
2660
2661
2662 def previous(self):
2663 '''Play previous item from media list.
2664 @return: 0 upon success -1 if there is no previous item.
2665 '''
2666 return libvlc_media_list_player_previous(self)
2667
2668
2669 def set_playback_mode(self, e_mode):
2670 '''Sets the playback mode for the playlist.
2671 @param e_mode: playback mode specification.
2672 '''
2673 return libvlc_media_list_player_set_playback_mode(self, e_mode)
2674
2675class MediaPlayer(_Ctype):
2676 '''Create a new MediaPlayer instance.
2677
2678 It may take as parameter either:
2679 - a string (media URI), options... In this case, a vlc.Instance will be created.
2680 - a vlc.Instance, a string (media URI), options...
2681
2682 '''
2683
2684 def __new__(cls, *args):
2685 if len(args) == 1 and isinstance(args[0], _Ints):
2686 return _Constructor(cls, args[0])
2687
2688 if args and isinstance(args[0], Instance):
2689 instance = args[0]
2690 args = args[1:]
2691 else:
2692 instance = get_default_instance()
2693
2694 o = instance.media_player_new()
2695 if args:
2696 o.set_media(instance.media_new(*args))
2697 return o
2698
2699 def get_instance(self):
2700 """Return the associated Instance.
2701 """
2702 return self._instance #PYCHOK expected
2703
2704 def set_mrl(self, mrl, *options):
2705 """Set the MRL to play.
2706
2707 Warning: most audio and video options, such as text renderer,
2708 have no effects on an individual media. These options must be
2709 set at the vlc.Instance or vlc.MediaPlayer instanciation.
2710
2711 @param mrl: The MRL
2712 @param options: optional media option=value strings
2713 @return: the Media object
2714 """
2715 m = self.get_instance().media_new(mrl, *options)
2716 self.set_media(m)
2717 return m
2718
2719 def video_get_spu_description(self):
2720 """Get the description of available video subtitles.
2721 """
2722 return track_description_list(libvlc_video_get_spu_description(self))
2723
2724 def video_get_title_description(self):
2725 """Get the description of available titles.
2726 """
2727 return track_description_list(libvlc_video_get_title_description(self))
2728
2729 def video_get_chapter_description(self, title):
2730 """Get the description of available chapters for specific title.
2731
2732 @param title: selected title (int)
2733 """
2734 return track_description_list(libvlc_video_get_chapter_description(self, title))
2735
2736 def video_get_track_description(self):
2737 """Get the description of available video tracks.
2738 """
2739 return track_description_list(libvlc_video_get_track_description(self))
2740
2741 def audio_get_track_description(self):
2742 """Get the description of available audio tracks.
2743 """
2744 return track_description_list(libvlc_audio_get_track_description(self))
2745
2746 def get_full_title_descriptions(self):
2747 '''Get the full description of available titles.
2748 @return: the titles list
2749 @version: LibVLC 3.0.0 and later.
2750 '''
2751 titleDescription_pp = ctypes.POINTER(TitleDescription)()
2752 n = libvlc_media_player_get_full_title_descriptions(self, ctypes.byref(titleDescription_pp))
2753 info = ctypes.cast(ctypes.titleDescription_pp, ctypes.POINTER(ctypes.POINTER(TitleDescription) * n))
2754 return info
2755
2756 def get_full_chapter_descriptions(self, i_chapters_of_title):
2757 '''Get the full description of available chapters.
2758 @param i_chapters_of_title: index of the title to query for chapters (uses current title if set to -1).
2759 @return: the chapters list
2760 @version: LibVLC 3.0.0 and later.
2761 '''
2762 chapterDescription_pp = ctypes.POINTER(ChapterDescription)()
2763 n = libvlc_media_player_get_full_chapter_descriptions(self, ctypes.byref(chapterDescription_pp))
2764 info = ctypes.cast(ctypes.chapterDescription_pp, ctypes.POINTER(ctypes.POINTER(ChapterDescription) * n))
2765 return info
2766
2767 def video_get_size(self, num=0):
2768 """Get the video size in pixels as 2-tuple (width, height).
2769
2770 @param num: video number (default 0).
2771 """
2772 r = libvlc_video_get_size(self, num)
2773 if isinstance(r, tuple) and len(r) == 2:
2774 return r
2775 else:
2776 raise VLCException('invalid video number (%s)' % (num,))
2777
2778 def set_hwnd(self, drawable):
2779 """Set a Win32/Win64 API window handle (HWND).
2780
2781 Specify where the media player should render its video
2782 output. If LibVLC was built without Win32/Win64 API output
2783 support, then this has no effects.
2784
2785 @param drawable: windows handle of the drawable.
2786 """
2787 if not isinstance(drawable, ctypes.c_void_p):
2788 drawable = ctypes.c_void_p(int(drawable))
2789 libvlc_media_player_set_hwnd(self, drawable)
2790
2791 def video_get_width(self, num=0):
2792 """Get the width of a video in pixels.
2793
2794 @param num: video number (default 0).
2795 """
2796 return self.video_get_size(num)[0]
2797
2798 def video_get_height(self, num=0):
2799 """Get the height of a video in pixels.
2800
2801 @param num: video number (default 0).
2802 """
2803 return self.video_get_size(num)[1]
2804
2805 def video_get_cursor(self, num=0):
2806 """Get the mouse pointer coordinates over a video as 2-tuple (x, y).
2807
2808 Coordinates are expressed in terms of the decoded video resolution,
2809 B{not} in terms of pixels on the screen/viewport. To get the
2810 latter, you must query your windowing system directly.
2811
2812 Either coordinate may be negative or larger than the corresponding
2813 size of the video, if the cursor is outside the rendering area.
2814
2815 @warning: The coordinates may be out-of-date if the pointer is not
2816 located on the video rendering area. LibVLC does not track the
2817 mouse pointer if the latter is outside the video widget.
2818
2819 @note: LibVLC does not support multiple mouse pointers (but does
2820 support multiple input devices sharing the same pointer).
2821
2822 @param num: video number (default 0).
2823 """
2824 r = libvlc_video_get_cursor(self, num)
2825 if isinstance(r, tuple) and len(r) == 2:
2826 return r
2827 raise VLCException('invalid video number (%s)' % (num,))
2828
2829
2830
2831 def release(self):
2832 '''Release a media_player after use
2833 Decrement the reference count of a media player object. If the
2834 reference count is 0, then L{release}() will
2835 release the media player object. If the media player object
2836 has been released, then it should not be used again.
2837 '''
2838 return libvlc_media_player_release(self)
2839
2840
2841 def retain(self):
2842 '''Retain a reference to a media player object. Use
2843 L{release}() to decrement reference count.
2844 '''
2845 return libvlc_media_player_retain(self)
2846
2847
2848 def set_media(self, p_md):
2849 '''Set the media that will be used by the media_player. If any,
2850 previous md will be released.
2851 @param p_md: the Media. Afterwards the p_md can be safely destroyed.
2852 '''
2853 return libvlc_media_player_set_media(self, p_md)
2854
2855
2856 def get_media(self):
2857 '''Get the media used by the media_player.
2858 @return: the media associated with p_mi, or None if no media is associated.
2859 '''
2860 return libvlc_media_player_get_media(self)
2861
2862 @memoize_parameterless
2863 def event_manager(self):
2864 '''Get the Event Manager from which the media player send event.
2865 @return: the event manager associated with p_mi.
2866 '''
2867 return libvlc_media_player_event_manager(self)
2868
2869
2870 def is_playing(self):
2871 '''is_playing.
2872 @return: 1 if the media player is playing, 0 otherwise \libvlc_return_bool.
2873 '''
2874 return libvlc_media_player_is_playing(self)
2875
2876
2877 def play(self):
2878 '''Play.
2879 @return: 0 if playback started (and was already started), or -1 on error.
2880 '''
2881 return libvlc_media_player_play(self)
2882
2883
2884 def set_pause(self, do_pause):
2885 '''Pause or resume (no effect if there is no media).
2886 @param do_pause: play/resume if zero, pause if non-zero.
2887 @version: LibVLC 1.1.1 or later.
2888 '''
2889 return libvlc_media_player_set_pause(self, do_pause)
2890
2891
2892 def pause(self):
2893 '''Toggle pause (no effect if there is no media).
2894 '''
2895 return libvlc_media_player_pause(self)
2896
2897
2898 def stop(self):
2899 '''Stop (no effect if there is no media).
2900 '''
2901 return libvlc_media_player_stop(self)
2902
2903
2904 def video_set_callbacks(self, lock, unlock, display, opaque):
2905 '''Set callbacks and private data to render decoded video to a custom area
2906 in memory.
2907 Use L{video_set_format}() or L{video_set_format_callbacks}()
2908 to configure the decoded format.
2909 @param lock: callback to lock video memory (must not be None).
2910 @param unlock: callback to unlock video memory (or None if not needed).
2911 @param display: callback to display video (or None if not needed).
2912 @param opaque: private pointer for the three callbacks (as first parameter).
2913 @version: LibVLC 1.1.1 or later.
2914 '''
2915 return libvlc_video_set_callbacks(self, lock, unlock, display, opaque)
2916
2917
2918 def video_set_format(self, chroma, width, height, pitch):
2919 '''Set decoded video chroma and dimensions.
2920 This only works in combination with L{video_set_callbacks}(),
2921 and is mutually exclusive with L{video_set_format_callbacks}().
2922 @param chroma: a four-characters string identifying the chroma (e.g. "RV32" or "YUYV").
2923 @param width: pixel width.
2924 @param height: pixel height.
2925 @param pitch: line pitch (in bytes).
2926 @version: LibVLC 1.1.1 or later.
2927 @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.
2928 '''
2929 return libvlc_video_set_format(self, str_to_bytes(chroma), width, height, pitch)
2930
2931
2932 def video_set_format_callbacks(self, setup, cleanup):
2933 '''Set decoded video chroma and dimensions. This only works in combination with
2934 L{video_set_callbacks}().
2935 @param setup: callback to select the video format (cannot be None).
2936 @param cleanup: callback to release any allocated resources (or None).
2937 @version: LibVLC 2.0.0 or later.
2938 '''
2939 return libvlc_video_set_format_callbacks(self, setup, cleanup)
2940
2941
2942 def set_nsobject(self, drawable):
2943 '''Set the NSView handler where the media player should render its video output.
2944 Use the vout called "macosx".
2945 The drawable is an NSObject that follow the VLCOpenGLVideoViewEmbedding
2946 protocol:
2947 @begincode
2948 \@protocol VLCOpenGLVideoViewEmbedding <NSObject>
2949 - (void)addVoutSubview:(NSView *)view;
2950 - (void)removeVoutSubview:(NSView *)view;
2951 \@end
2952 @endcode
2953 Or it can be an NSView object.
2954 If you want to use it along with Qt4 see the QMacCocoaViewContainer. Then
2955 the following code should work:
2956 @begincode
2957
2958 NSView *video = [[NSView alloc] init];
2959 QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
2960 L{set_nsobject}(mp, video);
2961 [video release];
2962
2963 @endcode
2964 You can find a live example in VLCVideoView in VLCKit.framework.
2965 @param drawable: the drawable that is either an NSView or an object following the VLCOpenGLVideoViewEmbedding protocol.
2966 '''
2967 return libvlc_media_player_set_nsobject(self, drawable)
2968
2969
2970 def get_nsobject(self):
2971 '''Get the NSView handler previously set with L{set_nsobject}().
2972 @return: the NSView handler or 0 if none where set.
2973 '''
2974 return libvlc_media_player_get_nsobject(self)
2975
2976
2977 def set_agl(self, drawable):
2978 '''Set the agl handler where the media player should render its video output.
2979 @param drawable: the agl handler.
2980 '''
2981 return libvlc_media_player_set_agl(self, drawable)
2982
2983
2984 def get_agl(self):
2985 '''Get the agl handler previously set with L{set_agl}().
2986 @return: the agl handler or 0 if none where set.
2987 '''
2988 return libvlc_media_player_get_agl(self)
2989
2990
2991 def set_xwindow(self, drawable):
2992 '''Set an X Window System drawable where the media player should render its
2993 video output. If LibVLC was built without X11 output support, then this has
2994 no effects.
2995 The specified identifier must correspond to an existing Input/Output class
2996 X11 window. Pixmaps are B{not} supported. The caller shall ensure that
2997 the X11 server is the same as the one the VLC instance has been configured
2998 with. This function must be called before video playback is started;
2999 otherwise it will only take effect after playback stop and restart.
3000 @param drawable: the ID of the X window.
3001 '''
3002 return libvlc_media_player_set_xwindow(self, drawable)
3003
3004
3005 def get_xwindow(self):
3006 '''Get the X Window System window identifier previously set with
3007 L{set_xwindow}(). Note that this will return the identifier
3008 even if VLC is not currently using it (for instance if it is playing an
3009 audio-only input).
3010 @return: an X window ID, or 0 if none where set.
3011 '''
3012 return libvlc_media_player_get_xwindow(self)
3013
3014
3015 def get_hwnd(self):
3016 '''Get the Windows API window handle (HWND) previously set with
3017 L{set_hwnd}(). The handle will be returned even if LibVLC
3018 is not currently outputting any video to it.
3019 @return: a window handle or None if there are none.
3020 '''
3021 return libvlc_media_player_get_hwnd(self)
3022
3023
3024 def audio_set_callbacks(self, play, pause, resume, flush, drain, opaque):
3025 '''Set callbacks and private data for decoded audio.
3026 Use L{audio_set_format}() or L{audio_set_format_callbacks}()
3027 to configure the decoded audio format.
3028 @param play: callback to play audio samples (must not be None).
3029 @param pause: callback to pause playback (or None to ignore).
3030 @param resume: callback to resume playback (or None to ignore).
3031 @param flush: callback to flush audio buffers (or None to ignore).
3032 @param drain: callback to drain audio buffers (or None to ignore).
3033 @param opaque: private pointer for the audio callbacks (as first parameter).
3034 @version: LibVLC 2.0.0 or later.
3035 '''
3036 return libvlc_audio_set_callbacks(self, play, pause, resume, flush, drain, opaque)
3037
3038
3039 def audio_set_volume_callback(self, set_volume):
3040 '''Set callbacks and private data for decoded audio. This only works in
3041 combination with L{audio_set_callbacks}().
3042 Use L{audio_set_format}() or L{audio_set_format_callbacks}()
3043 to configure the decoded audio format.
3044 @param set_volume: callback to apply audio volume, or None to apply volume in software.
3045 @version: LibVLC 2.0.0 or later.
3046 '''
3047 return libvlc_audio_set_volume_callback(self, set_volume)
3048
3049
3050 def audio_set_format_callbacks(self, setup, cleanup):
3051 '''Set decoded audio format. This only works in combination with
3052 L{audio_set_callbacks}().
3053 @param setup: callback to select the audio format (cannot be None).
3054 @param cleanup: callback to release any allocated resources (or None).
3055 @version: LibVLC 2.0.0 or later.
3056 '''
3057 return libvlc_audio_set_format_callbacks(self, setup, cleanup)
3058
3059
3060 def audio_set_format(self, format, rate, channels):
3061 '''Set decoded audio format.
3062 This only works in combination with L{audio_set_callbacks}(),
3063 and is mutually exclusive with L{audio_set_format_callbacks}().
3064 @param format: a four-characters string identifying the sample format (e.g. "S16N" or "FL32").
3065 @param rate: sample rate (expressed in Hz).
3066 @param channels: channels count.
3067 @version: LibVLC 2.0.0 or later.
3068 '''
3069 return libvlc_audio_set_format(self, str_to_bytes(format), rate, channels)
3070
3071
3072 def get_length(self):
3073 '''Get the current movie length (in ms).
3074 @return: the movie length (in ms), or -1 if there is no media.
3075 '''
3076 return libvlc_media_player_get_length(self)
3077
3078
3079 def get_time(self):
3080 '''Get the current movie time (in ms).
3081 @return: the movie time (in ms), or -1 if there is no media.
3082 '''
3083 return libvlc_media_player_get_time(self)
3084
3085
3086 def set_time(self, i_time):
3087 '''Set the movie time (in ms). This has no effect if no media is being played.
3088 Not all formats and protocols support this.
3089 @param i_time: the movie time (in ms).
3090 '''
3091 return libvlc_media_player_set_time(self, i_time)
3092
3093
3094 def get_position(self):
3095 '''Get movie position as percentage between 0.0 and 1.0.
3096 @return: movie position, or -1. in case of error.
3097 '''
3098 return libvlc_media_player_get_position(self)
3099
3100
3101 def set_position(self, f_pos):
3102 '''Set movie position as percentage between 0.0 and 1.0.
3103 This has no effect if playback is not enabled.
3104 This might not work depending on the underlying input format and protocol.
3105 @param f_pos: the position.
3106 '''
3107 return libvlc_media_player_set_position(self, f_pos)
3108
3109
3110 def set_chapter(self, i_chapter):
3111 '''Set movie chapter (if applicable).
3112 @param i_chapter: chapter number to play.
3113 '''
3114 return libvlc_media_player_set_chapter(self, i_chapter)
3115
3116
3117 def get_chapter(self):
3118 '''Get movie chapter.
3119 @return: chapter number currently playing, or -1 if there is no media.
3120 '''
3121 return libvlc_media_player_get_chapter(self)
3122
3123
3124 def get_chapter_count(self):
3125 '''Get movie chapter count.
3126 @return: number of chapters in movie, or -1.
3127 '''
3128 return libvlc_media_player_get_chapter_count(self)
3129
3130
3131 def will_play(self):
3132 '''Is the player able to play.
3133 @return: boolean \libvlc_return_bool.
3134 '''
3135 return libvlc_media_player_will_play(self)
3136
3137
3138 def get_chapter_count_for_title(self, i_title):
3139 '''Get title chapter count.
3140 @param i_title: title.
3141 @return: number of chapters in title, or -1.
3142 '''
3143 return libvlc_media_player_get_chapter_count_for_title(self, i_title)
3144
3145
3146 def set_title(self, i_title):
3147 '''Set movie title.
3148 @param i_title: title number to play.
3149 '''
3150 return libvlc_media_player_set_title(self, i_title)
3151
3152
3153 def get_title(self):
3154 '''Get movie title.
3155 @return: title number currently playing, or -1.
3156 '''
3157 return libvlc_media_player_get_title(self)
3158
3159
3160 def get_title_count(self):
3161 '''Get movie title count.
3162 @return: title number count, or -1.
3163 '''
3164 return libvlc_media_player_get_title_count(self)
3165
3166
3167 def previous_chapter(self):
3168 '''Set previous chapter (if applicable).
3169 '''
3170 return libvlc_media_player_previous_chapter(self)
3171
3172
3173 def next_chapter(self):
3174 '''Set next chapter (if applicable).
3175 '''
3176 return libvlc_media_player_next_chapter(self)
3177
3178
3179 def get_rate(self):
3180 '''Get the requested movie play rate.
3181 @warning: Depending on the underlying media, the requested rate may be
3182 different from the real playback rate.
3183 @return: movie play rate.
3184 '''
3185 return libvlc_media_player_get_rate(self)
3186
3187
3188 def set_rate(self, rate):
3189 '''Set movie play rate.
3190 @param rate: movie play rate to set.
3191 @return: -1 if an error was detected, 0 otherwise (but even then, it might not actually work depending on the underlying media protocol).
3192 '''
3193 return libvlc_media_player_set_rate(self, rate)
3194
3195
3196 def get_state(self):
3197 '''Get current movie state.
3198 @return: the current state of the media player (playing, paused, ...) See libvlc_state_t.
3199 '''
3200 return libvlc_media_player_get_state(self)
3201
3202
3203 def get_fps(self):
3204 '''Get movie fps rate.
3205 @return: frames per second (fps) for this playing movie, or 0 if unspecified.
3206 '''
3207 return libvlc_media_player_get_fps(self)
3208
3209
3210 def has_vout(self):
3211 '''How many video outputs does this media player have?
3212 @return: the number of video outputs.
3213 '''
3214 return libvlc_media_player_has_vout(self)
3215
3216
3217 def is_seekable(self):
3218 '''Is this media player seekable?
3219 @return: true if the media player can seek \libvlc_return_bool.
3220 '''
3221 return libvlc_media_player_is_seekable(self)
3222
3223
3224 def can_pause(self):
3225 '''Can this media player be paused?
3226 @return: true if the media player can pause \libvlc_return_bool.
3227 '''
3228 return libvlc_media_player_can_pause(self)
3229
3230
3231 def program_scrambled(self):
3232 '''Check if the current program is scrambled.
3233 @return: true if the current program is scrambled \libvlc_return_bool.
3234 @version: LibVLC 2.2.0 or later.
3235 '''
3236 return libvlc_media_player_program_scrambled(self)
3237
3238
3239 def next_frame(self):
3240 '''Display the next frame (if supported).
3241 '''
3242 return libvlc_media_player_next_frame(self)
3243
3244
3245 def navigate(self, navigate):
3246 '''Navigate through DVD Menu.
3247 @param navigate: the Navigation mode.
3248 @version: libVLC 2.0.0 or later.
3249 '''
3250 return libvlc_media_player_navigate(self, navigate)
3251
3252
3253 def set_video_title_display(self, position, timeout):
3254 '''Set if, and how, the video title will be shown when media is played.
3255 @param position: position at which to display the title, or libvlc_position_disable to prevent the title from being displayed.
3256 @param timeout: title display timeout in milliseconds (ignored if libvlc_position_disable).
3257 @version: libVLC 2.1.0 or later.
3258 '''
3259 return libvlc_media_player_set_video_title_display(self, position, timeout)
3260
3261
3262 def toggle_fullscreen(self):
3263 '''Toggle fullscreen status on non-embedded video outputs.
3264 @warning: The same limitations applies to this function
3265 as to L{set_fullscreen}().
3266 '''
3267 return libvlc_toggle_fullscreen(self)
3268
3269
3270 def set_fullscreen(self, b_fullscreen):
3271 '''Enable or disable fullscreen.
3272 @warning: With most window managers, only a top-level windows can be in
3273 full-screen mode. Hence, this function will not operate properly if
3274 L{set_xwindow}() was used to embed the video in a
3275 non-top-level window. In that case, the embedding window must be reparented
3276 to the root window B{before} fullscreen mode is enabled. You will want
3277 to reparent it back to its normal parent when disabling fullscreen.
3278 @param b_fullscreen: boolean for fullscreen status.
3279 '''
3280 return libvlc_set_fullscreen(self, b_fullscreen)
3281
3282
3283 def get_fullscreen(self):
3284 '''Get current fullscreen status.
3285 @return: the fullscreen status (boolean) \libvlc_return_bool.
3286 '''
3287 return libvlc_get_fullscreen(self)
3288
3289
3290 def video_set_key_input(self, on):
3291 '''Enable or disable key press events handling, according to the LibVLC hotkeys
3292 configuration. By default and for historical reasons, keyboard events are
3293 handled by the LibVLC video widget.
3294 @note: On X11, there can be only one subscriber for key press and mouse
3295 click events per window. If your application has subscribed to those events
3296 for the X window ID of the video widget, then LibVLC will not be able to
3297 handle key presses and mouse clicks in any case.
3298 @warning: This function is only implemented for X11 and Win32 at the moment.
3299 @param on: true to handle key press events, false to ignore them.
3300 '''
3301 return libvlc_video_set_key_input(self, on)
3302
3303
3304 def video_set_mouse_input(self, on):
3305 '''Enable or disable mouse click events handling. By default, those events are
3306 handled. This is needed for DVD menus to work, as well as a few video
3307 filters such as "puzzle".
3308 See L{video_set_key_input}().
3309 @warning: This function is only implemented for X11 and Win32 at the moment.
3310 @param on: true to handle mouse click events, false to ignore them.
3311 '''
3312 return libvlc_video_set_mouse_input(self, on)
3313
3314
3315 def video_get_scale(self):
3316 '''Get the current video scaling factor.
3317 See also L{video_set_scale}().
3318 @return: the currently configured zoom factor, or 0. if the video is set to fit to the output window/drawable automatically.
3319 '''
3320 return libvlc_video_get_scale(self)
3321
3322
3323 def video_set_scale(self, f_factor):
3324 '''Set the video scaling factor. That is the ratio of the number of pixels on
3325 screen to the number of pixels in the original decoded video in each
3326 dimension. Zero is a special value; it will adjust the video to the output
3327 window/drawable (in windowed mode) or the entire screen.
3328 Note that not all video outputs support scaling.
3329 @param f_factor: the scaling factor, or zero.
3330 '''
3331 return libvlc_video_set_scale(self, f_factor)
3332
3333
3334 def video_get_aspect_ratio(self):
3335 '''Get current video aspect ratio.
3336 @return: the video aspect ratio or None if unspecified (the result must be released with free() or L{free}()).
3337 '''
3338 return libvlc_video_get_aspect_ratio(self)
3339
3340
3341 def video_set_aspect_ratio(self, psz_aspect):
3342 '''Set new video aspect ratio.
3343 @param psz_aspect: new video aspect-ratio or None to reset to default @note Invalid aspect ratios are ignored.
3344 '''
3345 return libvlc_video_set_aspect_ratio(self, str_to_bytes(psz_aspect))
3346
3347
3348 def video_get_spu(self):
3349 '''Get current video subtitle.
3350 @return: the video subtitle selected, or -1 if none.
3351 '''
3352 return libvlc_video_get_spu(self)
3353
3354
3355 def video_get_spu_count(self):
3356 '''Get the number of available video subtitles.
3357 @return: the number of available video subtitles.
3358 '''
3359 return libvlc_video_get_spu_count(self)
3360
3361
3362 def video_set_spu(self, i_spu):
3363 '''Set new video subtitle.
3364 @param i_spu: video subtitle track to select (i_id from track description).
3365 @return: 0 on success, -1 if out of range.
3366 '''
3367 return libvlc_video_set_spu(self, i_spu)
3368
3369
3370 def video_set_subtitle_file(self, psz_subtitle):
3371 '''Set new video subtitle file.
3372 @param psz_subtitle: new video subtitle file.
3373 @return: the success status (boolean).
3374 '''
3375 return libvlc_video_set_subtitle_file(self, str_to_bytes(psz_subtitle))
3376
3377
3378 def video_get_spu_delay(self):
3379 '''Get the current subtitle delay. Positive values means subtitles are being
3380 displayed later, negative values earlier.
3381 @return: time (in microseconds) the display of subtitles is being delayed.
3382 @version: LibVLC 2.0.0 or later.
3383 '''
3384 return libvlc_video_get_spu_delay(self)
3385
3386
3387 def video_set_spu_delay(self, i_delay):
3388 '''Set the subtitle delay. This affects the timing of when the subtitle will
3389 be displayed. Positive values result in subtitles being displayed later,
3390 while negative values will result in subtitles being displayed earlier.
3391 The subtitle delay will be reset to zero each time the media changes.
3392 @param i_delay: time (in microseconds) the display of subtitles should be delayed.
3393 @return: 0 on success, -1 on error.
3394 @version: LibVLC 2.0.0 or later.
3395 '''
3396 return libvlc_video_set_spu_delay(self, i_delay)
3397
3398
3399 def video_get_crop_geometry(self):
3400 '''Get current crop filter geometry.
3401 @return: the crop filter geometry or None if unset.
3402 '''
3403 return libvlc_video_get_crop_geometry(self)
3404
3405
3406 def video_set_crop_geometry(self, psz_geometry):
3407 '''Set new crop filter geometry.
3408 @param psz_geometry: new crop filter geometry (None to unset).
3409 '''
3410 return libvlc_video_set_crop_geometry(self, str_to_bytes(psz_geometry))
3411
3412
3413 def video_get_teletext(self):
3414 '''Get current teletext page requested.
3415 @return: the current teletext page requested.
3416 '''
3417 return libvlc_video_get_teletext(self)
3418
3419
3420 def video_set_teletext(self, i_page):
3421 '''Set new teletext page to retrieve.
3422 @param i_page: teletex page number requested.
3423 '''
3424 return libvlc_video_set_teletext(self, i_page)
3425
3426
3427 def toggle_teletext(self):
3428 '''Toggle teletext transparent status on video output.
3429 '''
3430 return libvlc_toggle_teletext(self)
3431
3432
3433 def video_get_track_count(self):
3434 '''Get number of available video tracks.
3435 @return: the number of available video tracks (int).
3436 '''
3437 return libvlc_video_get_track_count(self)
3438
3439
3440 def video_get_track(self):
3441 '''Get current video track.
3442 @return: the video track ID (int) or -1 if no active input.
3443 '''
3444 return libvlc_video_get_track(self)
3445
3446
3447 def video_set_track(self, i_track):
3448 '''Set video track.
3449 @param i_track: the track ID (i_id field from track description).
3450 @return: 0 on success, -1 if out of range.
3451 '''
3452 return libvlc_video_set_track(self, i_track)
3453
3454
3455 def video_take_snapshot(self, num, psz_filepath, i_width, i_height):
3456 '''Take a snapshot of the current video window.
3457 If i_width AND i_height is 0, original size is used.
3458 If i_width XOR i_height is 0, original aspect-ratio is preserved.
3459 @param num: number of video output (typically 0 for the first/only one).
3460 @param psz_filepath: the path where to save the screenshot to.
3461 @param i_width: the snapshot's width.
3462 @param i_height: the snapshot's height.
3463 @return: 0 on success, -1 if the video was not found.
3464 '''
3465 return libvlc_video_take_snapshot(self, num, str_to_bytes(psz_filepath), i_width, i_height)
3466
3467
3468 def video_set_deinterlace(self, psz_mode):
3469 '''Enable or disable deinterlace filter.
3470 @param psz_mode: type of deinterlace filter, None to disable.
3471 '''
3472 return libvlc_video_set_deinterlace(self, str_to_bytes(psz_mode))
3473
3474
3475 def video_get_marquee_int(self, option):
3476 '''Get an integer marquee option value.
3477 @param option: marq option to get See libvlc_video_marquee_int_option_t.
3478 '''
3479 return libvlc_video_get_marquee_int(self, option)
3480
3481
3482 def video_get_marquee_string(self, option):
3483 '''Get a string marquee option value.
3484 @param option: marq option to get See libvlc_video_marquee_string_option_t.
3485 '''
3486 return libvlc_video_get_marquee_string(self, option)
3487
3488
3489 def video_set_marquee_int(self, option, i_val):
3490 '''Enable, disable or set an integer marquee option
3491 Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
3492 or disabling (arg 0) the marq filter.
3493 @param option: marq option to set See libvlc_video_marquee_int_option_t.
3494 @param i_val: marq option value.
3495 '''
3496 return libvlc_video_set_marquee_int(self, option, i_val)
3497
3498
3499 def video_set_marquee_string(self, option, psz_text):
3500 '''Set a marquee string option.
3501 @param option: marq option to set See libvlc_video_marquee_string_option_t.
3502 @param psz_text: marq option value.
3503 '''
3504 return libvlc_video_set_marquee_string(self, option, str_to_bytes(psz_text))
3505
3506
3507 def video_get_logo_int(self, option):
3508 '''Get integer logo option.
3509 @param option: logo option to get, values of libvlc_video_logo_option_t.
3510 '''
3511 return libvlc_video_get_logo_int(self, option)
3512
3513
3514 def video_set_logo_int(self, option, value):
3515 '''Set logo option as integer. Options that take a different type value
3516 are ignored.
3517 Passing libvlc_logo_enable as option value has the side effect of
3518 starting (arg !0) or stopping (arg 0) the logo filter.
3519 @param option: logo option to set, values of libvlc_video_logo_option_t.
3520 @param value: logo option value.
3521 '''
3522 return libvlc_video_set_logo_int(self, option, value)
3523
3524
3525 def video_set_logo_string(self, option, psz_value):
3526 '''Set logo option as string. Options that take a different type value
3527 are ignored.
3528 @param option: logo option to set, values of libvlc_video_logo_option_t.
3529 @param psz_value: logo option value.
3530 '''
3531 return libvlc_video_set_logo_string(self, option, str_to_bytes(psz_value))
3532
3533
3534 def video_get_adjust_int(self, option):
3535 '''Get integer adjust option.
3536 @param option: adjust option to get, values of libvlc_video_adjust_option_t.
3537 @version: LibVLC 1.1.1 and later.
3538 '''
3539 return libvlc_video_get_adjust_int(self, option)
3540
3541
3542 def video_set_adjust_int(self, option, value):
3543 '''Set adjust option as integer. Options that take a different type value
3544 are ignored.
3545 Passing libvlc_adjust_enable as option value has the side effect of
3546 starting (arg !0) or stopping (arg 0) the adjust filter.
3547 @param option: adust option to set, values of libvlc_video_adjust_option_t.
3548 @param value: adjust option value.
3549 @version: LibVLC 1.1.1 and later.
3550 '''
3551 return libvlc_video_set_adjust_int(self, option, value)
3552
3553
3554 def video_get_adjust_float(self, option):
3555 '''Get float adjust option.
3556 @param option: adjust option to get, values of libvlc_video_adjust_option_t.
3557 @version: LibVLC 1.1.1 and later.
3558 '''
3559 return libvlc_video_get_adjust_float(self, option)
3560
3561
3562 def video_set_adjust_float(self, option, value):
3563 '''Set adjust option as float. Options that take a different type value
3564 are ignored.
3565 @param option: adust option to set, values of libvlc_video_adjust_option_t.
3566 @param value: adjust option value.
3567 @version: LibVLC 1.1.1 and later.
3568 '''
3569 return libvlc_video_set_adjust_float(self, option, value)
3570
3571
3572 def audio_output_set(self, psz_name):
3573 '''Selects an audio output module.
3574 @note: Any change will take be effect only after playback is stopped and
3575 restarted. Audio output cannot be changed while playing.
3576 @param psz_name: name of audio output, use psz_name of See L{AudioOutput}.
3577 @return: 0 if function succeded, -1 on error.
3578 '''
3579 return libvlc_audio_output_set(self, str_to_bytes(psz_name))
3580
3581
3582 def audio_output_device_enum(self):
3583 '''Gets a list of potential audio output devices,
3584 See L{audio_output_device_set}().
3585 @note: Not all audio outputs support enumerating devices.
3586 The audio output may be functional even if the list is empty (None).
3587 @note: The list may not be exhaustive.
3588 @warning: Some audio output devices in the list might not actually work in
3589 some circumstances. By default, it is recommended to not specify any
3590 explicit audio device.
3591 @return: A None-terminated linked list of potential audio output devices. It must be freed it with L{audio_output_device_list_release}().
3592 @version: LibVLC 2.2.0 or later.
3593 '''
3594 return libvlc_audio_output_device_enum(self)
3595
3596
3597 def audio_output_device_set(self, module, device_id):
3598 '''Configures an explicit audio output device.
3599 If the module paramater is None, audio output will be moved to the device
3600 specified by the device identifier string immediately. This is the
3601 recommended usage.
3602 A list of adequate potential device strings can be obtained with
3603 L{audio_output_device_enum}().
3604 However passing None is supported in LibVLC version 2.2.0 and later only;
3605 in earlier versions, this function would have no effects when the module
3606 parameter was None.
3607 If the module parameter is not None, the device parameter of the
3608 corresponding audio output, if it exists, will be set to the specified
3609 string. Note that some audio output modules do not have such a parameter
3610 (notably MMDevice and PulseAudio).
3611 A list of adequate potential device strings can be obtained with
3612 L{audio_output_device_list_get}().
3613 @note: This function does not select the specified audio output plugin.
3614 L{audio_output_set}() is used for that purpose.
3615 @warning: The syntax for the device parameter depends on the audio output.
3616 Some audio output modules require further parameters (e.g. a channels map
3617 in the case of ALSA).
3618 @param module: If None, current audio output module. if non-None, name of audio output module.
3619 @param device_id: device identifier string.
3620 @return: Nothing. Errors are ignored (this is a design bug).
3621 '''
3622 return libvlc_audio_output_device_set(self, str_to_bytes(module), str_to_bytes(device_id))
3623
3624
3625 def audio_toggle_mute(self):
3626 '''Toggle mute status.
3627 '''
3628 return libvlc_audio_toggle_mute(self)
3629
3630
3631 def audio_get_mute(self):
3632 '''Get current mute status.
3633 @return: the mute status (boolean) if defined, -1 if undefined/unapplicable.
3634 '''
3635 return libvlc_audio_get_mute(self)
3636
3637
3638 def audio_set_mute(self, status):
3639 '''Set mute status.
3640 @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.
3641 '''
3642 return libvlc_audio_set_mute(self, status)
3643
3644
3645 def audio_get_volume(self):
3646 '''Get current software audio volume.
3647 @return: the software volume in percents (0 = mute, 100 = nominal / 0dB).
3648 '''
3649 return libvlc_audio_get_volume(self)
3650
3651
3652 def audio_set_volume(self, i_volume):
3653 '''Set current software audio volume.
3654 @param i_volume: the volume in percents (0 = mute, 100 = 0dB).
3655 @return: 0 if the volume was set, -1 if it was out of range.
3656 '''
3657 return libvlc_audio_set_volume(self, i_volume)
3658
3659
3660 def audio_get_track_count(self):
3661 '''Get number of available audio tracks.
3662 @return: the number of available audio tracks (int), or -1 if unavailable.
3663 '''
3664 return libvlc_audio_get_track_count(self)
3665
3666
3667 def audio_get_track(self):
3668 '''Get current audio track.
3669 @return: the audio track ID or -1 if no active input.
3670 '''
3671 return libvlc_audio_get_track(self)
3672
3673
3674 def audio_set_track(self, i_track):
3675 '''Set current audio track.
3676 @param i_track: the track ID (i_id field from track description).
3677 @return: 0 on success, -1 on error.
3678 '''
3679 return libvlc_audio_set_track(self, i_track)
3680
3681
3682 def audio_get_channel(self):
3683 '''Get current audio channel.
3684 @return: the audio channel See libvlc_audio_output_channel_t.
3685 '''
3686 return libvlc_audio_get_channel(self)
3687
3688
3689 def audio_set_channel(self, channel):
3690 '''Set current audio channel.
3691 @param channel: the audio channel, See libvlc_audio_output_channel_t.
3692 @return: 0 on success, -1 on error.
3693 '''
3694 return libvlc_audio_set_channel(self, channel)
3695
3696
3697 def audio_get_delay(self):
3698 '''Get current audio delay.
3699 @return: the audio delay (microseconds).
3700 @version: LibVLC 1.1.1 or later.
3701 '''
3702 return libvlc_audio_get_delay(self)
3703
3704
3705 def audio_set_delay(self, i_delay):
3706 '''Set current audio delay. The audio delay will be reset to zero each time the media changes.
3707 @param i_delay: the audio delay (microseconds).
3708 @return: 0 on success, -1 on error.
3709 @version: LibVLC 1.1.1 or later.
3710 '''
3711 return libvlc_audio_set_delay(self, i_delay)
3712
3713
3714 def set_equalizer(self, p_equalizer):
3715 '''Apply new equalizer settings to a media player.
3716 The equalizer is first created by invoking L{audio_equalizer_new}() or
3717 L{audio_equalizer_new_from_preset}().
3718 It is possible to apply new equalizer settings to a media player whether the media
3719 player is currently playing media or not.
3720 Invoking this method will immediately apply the new equalizer settings to the audio
3721 output of the currently playing media if there is any.
3722 If there is no currently playing media, the new equalizer settings will be applied
3723 later if and when new media is played.
3724 Equalizer settings will automatically be applied to subsequently played media.
3725 To disable the equalizer for a media player invoke this method passing None for the
3726 p_equalizer parameter.
3727 The media player does not keep a reference to the supplied equalizer so it is safe
3728 for an application to release the equalizer reference any time after this method
3729 returns.
3730 @param p_equalizer: opaque equalizer handle, or None to disable the equalizer for this media player.
3731 @return: zero on success, -1 on error.
3732 @version: LibVLC 2.2.0 or later.
3733 '''
3734 return libvlc_media_player_set_equalizer(self, p_equalizer)
3735
3736
3737 # LibVLC __version__ functions #
3738
3739def libvlc_clearerr():
3740 '''Clears the LibVLC error status for the current thread. This is optional.
3741 By default, the error status is automatically overridden when a new error
3742 occurs, and destroyed when the thread exits.
3743 '''
3744 f = _Cfunctions.get('libvlc_clearerr', None) or \
3745 _Cfunction('libvlc_clearerr', (), None,
3746 None)
3747 return f()
3748
3749def libvlc_vprinterr(fmt, ap):
3750 '''Sets the LibVLC error status and message for the current thread.
3751 Any previous error is overridden.
3752 @param fmt: the format string.
3753 @param ap: the arguments.
3754 @return: a nul terminated string in any case.
3755 '''
3756 f = _Cfunctions.get('libvlc_vprinterr', None) or \
3757 _Cfunction('libvlc_vprinterr', ((1,), (1,),), None,
3758 ctypes.c_char_p, ctypes.c_char_p, ctypes.c_void_p)
3759 return f(fmt, ap)
3760
3761def libvlc_new(argc, argv):
3762 '''Create and initialize a libvlc instance.
3763 This functions accept a list of "command line" arguments similar to the
3764 main(). These arguments affect the LibVLC instance default configuration.
3765 @param argc: the number of arguments (should be 0).
3766 @param argv: list of arguments (should be None).
3767 @return: the libvlc instance or None in case of error.
3768 @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.
3769 '''
3770 f = _Cfunctions.get('libvlc_new', None) or \
3771 _Cfunction('libvlc_new', ((1,), (1,),), class_result(Instance),
3772 ctypes.c_void_p, ctypes.c_int, ListPOINTER(ctypes.c_char_p))
3773 return f(argc, argv)
3774
3775def libvlc_release(p_instance):
3776 '''Decrement the reference count of a libvlc instance, and destroy it
3777 if it reaches zero.
3778 @param p_instance: the instance to destroy.
3779 '''
3780 f = _Cfunctions.get('libvlc_release', None) or \
3781 _Cfunction('libvlc_release', ((1,),), None,
3782 None, Instance)
3783 return f(p_instance)
3784
3785def libvlc_retain(p_instance):
3786 '''Increments the reference count of a libvlc instance.
3787 The initial reference count is 1 after L{libvlc_new}() returns.
3788 @param p_instance: the instance to reference.
3789 '''
3790 f = _Cfunctions.get('libvlc_retain', None) or \
3791 _Cfunction('libvlc_retain', ((1,),), None,
3792 None, Instance)
3793 return f(p_instance)
3794
3795def libvlc_add_intf(p_instance, name):
3796 '''Try to start a user interface for the libvlc instance.
3797 @param p_instance: the instance.
3798 @param name: interface name, or None for default.
3799 @return: 0 on success, -1 on error.
3800 '''
3801 f = _Cfunctions.get('libvlc_add_intf', None) or \
3802 _Cfunction('libvlc_add_intf', ((1,), (1,),), None,
3803 ctypes.c_int, Instance, ctypes.c_char_p)
3804 return f(p_instance, name)
3805
3806def libvlc_wait(p_instance):
3807 '''Waits until an interface causes the instance to exit.
3808 You should start at least one interface first, using L{libvlc_add_intf}().
3809 @param p_instance: the instance @warning This function wastes one thread doing basically nothing. libvlc_set_exit_handler() should be used instead.
3810 '''
3811 f = _Cfunctions.get('libvlc_wait', None) or \
3812 _Cfunction('libvlc_wait', ((1,),), None,
3813 None, Instance)
3814 return f(p_instance)
3815
3816def libvlc_set_user_agent(p_instance, name, http):
3817 '''Sets the application name. LibVLC passes this as the user agent string
3818 when a protocol requires it.
3819 @param p_instance: LibVLC instance.
3820 @param name: human-readable application name, e.g. "FooBar player 1.2.3".
3821 @param http: HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0".
3822 @version: LibVLC 1.1.1 or later.
3823 '''
3824 f = _Cfunctions.get('libvlc_set_user_agent', None) or \
3825 _Cfunction('libvlc_set_user_agent', ((1,), (1,), (1,),), None,
3826 None, Instance, ctypes.c_char_p, ctypes.c_char_p)
3827 return f(p_instance, name, http)
3828
3829def libvlc_set_app_id(p_instance, id, version, icon):
3830 '''Sets some meta-information about the application.
3831 See also L{libvlc_set_user_agent}().
3832 @param p_instance: LibVLC instance.
3833 @param id: Java-style application identifier, e.g. "com.acme.foobar".
3834 @param version: application version numbers, e.g. "1.2.3".
3835 @param icon: application icon name, e.g. "foobar".
3836 @version: LibVLC 2.1.0 or later.
3837 '''
3838 f = _Cfunctions.get('libvlc_set_app_id', None) or \
3839 _Cfunction('libvlc_set_app_id', ((1,), (1,), (1,), (1,),), None,
3840 None, Instance, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p)
3841 return f(p_instance, id, version, icon)
3842
3843def libvlc_get_version():
3844 '''Retrieve libvlc version.
3845 Example: "1.1.0-git The Luggage".
3846 @return: a string containing the libvlc version.
3847 '''
3848 f = _Cfunctions.get('libvlc_get_version', None) or \
3849 _Cfunction('libvlc_get_version', (), None,
3850 ctypes.c_char_p)
3851 return f()
3852
3853def libvlc_get_compiler():
3854 '''Retrieve libvlc compiler version.
3855 Example: "gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu6)".
3856 @return: a string containing the libvlc compiler version.
3857 '''
3858 f = _Cfunctions.get('libvlc_get_compiler', None) or \
3859 _Cfunction('libvlc_get_compiler', (), None,
3860 ctypes.c_char_p)
3861 return f()
3862
3863def libvlc_get_changeset():
3864 '''Retrieve libvlc changeset.
3865 Example: "aa9bce0bc4".
3866 @return: a string containing the libvlc changeset.
3867 '''
3868 f = _Cfunctions.get('libvlc_get_changeset', None) or \
3869 _Cfunction('libvlc_get_changeset', (), None,
3870 ctypes.c_char_p)
3871 return f()
3872
3873def libvlc_free(ptr):
3874 '''Frees an heap allocation returned by a LibVLC function.
3875 If you know you're using the same underlying C run-time as the LibVLC
3876 implementation, then you can call ANSI C free() directly instead.
3877 @param ptr: the pointer.
3878 '''
3879 f = _Cfunctions.get('libvlc_free', None) or \
3880 _Cfunction('libvlc_free', ((1,),), None,
3881 None, ctypes.c_void_p)
3882 return f(ptr)
3883
3884def libvlc_event_attach(p_event_manager, i_event_type, f_callback, user_data):
3885 '''Register for an event notification.
3886 @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.
3887 @param i_event_type: the desired event to which we want to listen.
3888 @param f_callback: the function to call when i_event_type occurs.
3889 @param user_data: user provided data to carry with the event.
3890 @return: 0 on success, ENOMEM on error.
3891 '''
3892 f = _Cfunctions.get('libvlc_event_attach', None) or \
3893 _Cfunction('libvlc_event_attach', ((1,), (1,), (1,), (1,),), None,
3894 ctypes.c_int, EventManager, ctypes.c_uint, Callback, ctypes.c_void_p)
3895 return f(p_event_manager, i_event_type, f_callback, user_data)
3896
3897def libvlc_event_detach(p_event_manager, i_event_type, f_callback, p_user_data):
3898 '''Unregister an event notification.
3899 @param p_event_manager: the event manager.
3900 @param i_event_type: the desired event to which we want to unregister.
3901 @param f_callback: the function to call when i_event_type occurs.
3902 @param p_user_data: user provided data to carry with the event.
3903 '''
3904 f = _Cfunctions.get('libvlc_event_detach', None) or \
3905 _Cfunction('libvlc_event_detach', ((1,), (1,), (1,), (1,),), None,
3906 None, EventManager, ctypes.c_uint, Callback, ctypes.c_void_p)
3907 return f(p_event_manager, i_event_type, f_callback, p_user_data)
3908
3909def libvlc_event_type_name(event_type):
3910 '''Get an event's type name.
3911 @param event_type: the desired event.
3912 '''
3913 f = _Cfunctions.get('libvlc_event_type_name', None) or \
3914 _Cfunction('libvlc_event_type_name', ((1,),), None,
3915 ctypes.c_char_p, ctypes.c_uint)
3916 return f(event_type)
3917
3918def libvlc_log_get_context(ctx):
3919 '''Gets debugging information about a log message: the name of the VLC module
3920 emitting the message and the message location within the source code.
3921 The returned module name and file name will be None if unknown.
3922 The returned line number will similarly be zero if unknown.
3923 @param ctx: message context (as passed to the @ref libvlc_log_cb callback).
3924 @return: module module name storage (or None), file source code file name storage (or None), line source code file line number storage (or None).
3925 @version: LibVLC 2.1.0 or later.
3926 '''
3927 f = _Cfunctions.get('libvlc_log_get_context', None) or \
3928 _Cfunction('libvlc_log_get_context', ((1,), (2,), (2,), (2,),), None,
3929 None, Log_ptr, ListPOINTER(ctypes.c_char_p), ListPOINTER(ctypes.c_char_p), ctypes.POINTER(ctypes.c_uint))
3930 return f(ctx)
3931
3932def libvlc_log_get_object(ctx, id):
3933 '''Gets VLC object information about a log message: the type name of the VLC
3934 object emitting the message, the object header if any and a temporaly-unique
3935 object identifier. This information is mainly meant for B{manual}
3936 troubleshooting.
3937 The returned type name may be "generic" if unknown, but it cannot be None.
3938 The returned header will be None if unset; in current versions, the header
3939 is used to distinguish for VLM inputs.
3940 The returned object ID will be zero if the message is not associated with
3941 any VLC object.
3942 @param ctx: message context (as passed to the @ref libvlc_log_cb callback).
3943 @return: name object name storage (or None), header object header (or None), line source code file line number storage (or None).
3944 @version: LibVLC 2.1.0 or later.
3945 '''
3946 f = _Cfunctions.get('libvlc_log_get_object', None) or \
3947 _Cfunction('libvlc_log_get_object', ((1,), (2,), (2,), (1,),), None,
3948 None, Log_ptr, ListPOINTER(ctypes.c_char_p), ListPOINTER(ctypes.c_char_p), ctypes.POINTER(ctypes.c_uint))
3949 return f(ctx, id)
3950
3951def libvlc_log_unset(p_instance):
3952 '''Unsets the logging callback for a LibVLC instance. This is rarely needed:
3953 the callback is implicitly unset when the instance is destroyed.
3954 This function will wait for any pending callbacks invocation to complete
3955 (causing a deadlock if called from within the callback).
3956 @param p_instance: libvlc instance.
3957 @version: LibVLC 2.1.0 or later.
3958 '''
3959 f = _Cfunctions.get('libvlc_log_unset', None) or \
3960 _Cfunction('libvlc_log_unset', ((1,),), None,
3961 None, Instance)
3962 return f(p_instance)
3963
3964def libvlc_log_set(cb, data, p_instance):
3965 '''Sets the logging callback for a LibVLC instance.
3966 This function is thread-safe: it will wait for any pending callbacks
3967 invocation to complete.
3968 @param cb: callback function pointer.
3969 @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.
3970 @param p_instance: libvlc instance.
3971 @version: LibVLC 2.1.0 or later.
3972 '''
3973 f = _Cfunctions.get('libvlc_log_set', None) or \
3974 _Cfunction('libvlc_log_set', ((1,), (1,), (1,),), None,
3975 None, Instance, LogCb, ctypes.c_void_p)
3976 return f(cb, data, p_instance)
3977
3978def libvlc_log_set_file(p_instance, stream):
3979 '''Sets up logging to a file.
3980 @param p_instance: libvlc instance.
3981 @param stream: FILE pointer opened for writing (the FILE pointer must remain valid until L{libvlc_log_unset}()).
3982 @version: LibVLC 2.1.0 or later.
3983 '''
3984 f = _Cfunctions.get('libvlc_log_set_file', None) or \
3985 _Cfunction('libvlc_log_set_file', ((1,), (1,),), None,
3986 None, Instance, FILE_ptr)
3987 return f(p_instance, stream)
3988
3989def libvlc_get_log_verbosity(p_instance):
3990 '''Always returns minus one.
3991 This function is only provided for backward compatibility.
3992 @param p_instance: ignored.
3993 @return: always -1.
3994 '''
3995 f = _Cfunctions.get('libvlc_get_log_verbosity', None) or \
3996 _Cfunction('libvlc_get_log_verbosity', ((1,),), None,
3997 ctypes.c_uint, Instance)
3998 return f(p_instance)
3999
4000def libvlc_set_log_verbosity(p_instance, level):
4001 '''This function does nothing.
4002 It is only provided for backward compatibility.
4003 @param p_instance: ignored.
4004 @param level: ignored.
4005 '''
4006 f = _Cfunctions.get('libvlc_set_log_verbosity', None) or \
4007 _Cfunction('libvlc_set_log_verbosity', ((1,), (1,),), None,
4008 None, Instance, ctypes.c_uint)
4009 return f(p_instance, level)
4010
4011def libvlc_log_open(p_instance):
4012 '''This function does nothing useful.
4013 It is only provided for backward compatibility.
4014 @param p_instance: libvlc instance.
4015 @return: an unique pointer or None on error.
4016 '''
4017 f = _Cfunctions.get('libvlc_log_open', None) or \
4018 _Cfunction('libvlc_log_open', ((1,),), None,
4019 Log_ptr, Instance)
4020 return f(p_instance)
4021
4022def libvlc_log_close(p_log):
4023 '''Frees memory allocated by L{libvlc_log_open}().
4024 @param p_log: libvlc log instance or None.
4025 '''
4026 f = _Cfunctions.get('libvlc_log_close', None) or \
4027 _Cfunction('libvlc_log_close', ((1,),), None,
4028 None, Log_ptr)
4029 return f(p_log)
4030
4031def libvlc_log_count(p_log):
4032 '''Always returns zero.
4033 This function is only provided for backward compatibility.
4034 @param p_log: ignored.
4035 @return: always zero.
4036 '''
4037 f = _Cfunctions.get('libvlc_log_count', None) or \
4038 _Cfunction('libvlc_log_count', ((1,),), None,
4039 ctypes.c_uint, Log_ptr)
4040 return f(p_log)
4041
4042def libvlc_log_clear(p_log):
4043 '''This function does nothing.
4044 It is only provided for backward compatibility.
4045 @param p_log: ignored.
4046 '''
4047 f = _Cfunctions.get('libvlc_log_clear', None) or \
4048 _Cfunction('libvlc_log_clear', ((1,),), None,
4049 None, Log_ptr)
4050 return f(p_log)
4051
4052def libvlc_log_get_iterator(p_log):
4053 '''This function does nothing useful.
4054 It is only provided for backward compatibility.
4055 @param p_log: ignored.
4056 @return: an unique pointer or None on error or if the parameter was None.
4057 '''
4058 f = _Cfunctions.get('libvlc_log_get_iterator', None) or \
4059 _Cfunction('libvlc_log_get_iterator', ((1,),), class_result(LogIterator),
4060 ctypes.c_void_p, Log_ptr)
4061 return f(p_log)
4062
4063def libvlc_log_iterator_free(p_iter):
4064 '''Frees memory allocated by L{libvlc_log_get_iterator}().
4065 @param p_iter: libvlc log iterator or None.
4066 '''
4067 f = _Cfunctions.get('libvlc_log_iterator_free', None) or \
4068 _Cfunction('libvlc_log_iterator_free', ((1,),), None,
4069 None, LogIterator)
4070 return f(p_iter)
4071
4072def libvlc_log_iterator_has_next(p_iter):
4073 '''Always returns zero.
4074 This function is only provided for backward compatibility.
4075 @param p_iter: ignored.
4076 @return: always zero.
4077 '''
4078 f = _Cfunctions.get('libvlc_log_iterator_has_next', None) or \
4079 _Cfunction('libvlc_log_iterator_has_next', ((1,),), None,
4080 ctypes.c_int, LogIterator)
4081 return f(p_iter)
4082
4083def libvlc_log_iterator_next(p_iter, p_buf):
4084 '''Always returns None.
4085 This function is only provided for backward compatibility.
4086 @param p_iter: libvlc log iterator or None.
4087 @param p_buf: ignored.
4088 @return: always None.
4089 '''
4090 f = _Cfunctions.get('libvlc_log_iterator_next', None) or \
4091 _Cfunction('libvlc_log_iterator_next', ((1,), (1,),), None,
4092 ctypes.POINTER(LogMessage), LogIterator, ctypes.POINTER(LogMessage))
4093 return f(p_iter, p_buf)
4094
4095def libvlc_module_description_list_release(p_list):
4096 '''Release a list of module descriptions.
4097 @param p_list: the list to be released.
4098 '''
4099 f = _Cfunctions.get('libvlc_module_description_list_release', None) or \
4100 _Cfunction('libvlc_module_description_list_release', ((1,),), None,
4101 None, ctypes.POINTER(ModuleDescription))
4102 return f(p_list)
4103
4104def libvlc_audio_filter_list_get(p_instance):
4105 '''Returns a list of audio filters that are available.
4106 @param p_instance: libvlc instance.
4107 @return: a list of module descriptions. It should be freed with L{libvlc_module_description_list_release}(). In case of an error, None is returned. See L{ModuleDescription} See L{libvlc_module_description_list_release}.
4108 '''
4109 f = _Cfunctions.get('libvlc_audio_filter_list_get', None) or \
4110 _Cfunction('libvlc_audio_filter_list_get', ((1,),), None,
4111 ctypes.POINTER(ModuleDescription), Instance)
4112 return f(p_instance)
4113
4114def libvlc_video_filter_list_get(p_instance):
4115 '''Returns a list of video filters that are available.
4116 @param p_instance: libvlc instance.
4117 @return: a list of module descriptions. It should be freed with L{libvlc_module_description_list_release}(). In case of an error, None is returned. See L{ModuleDescription} See L{libvlc_module_description_list_release}.
4118 '''
4119 f = _Cfunctions.get('libvlc_video_filter_list_get', None) or \
4120 _Cfunction('libvlc_video_filter_list_get', ((1,),), None,
4121 ctypes.POINTER(ModuleDescription), Instance)
4122 return f(p_instance)
4123
4124def libvlc_clock():
4125 '''Return the current time as defined by LibVLC. The unit is the microsecond.
4126 Time increases monotonically (regardless of time zone changes and RTC
4127 adjustements).
4128 The origin is arbitrary but consistent across the whole system
4129 (e.g. the system uptim, the time since the system was booted).
4130 @note: On systems that support it, the POSIX monotonic clock is used.
4131 '''
4132 f = _Cfunctions.get('libvlc_clock', None) or \
4133 _Cfunction('libvlc_clock', (), None,
4134 ctypes.c_int64)
4135 return f()
4136
4137def libvlc_media_discoverer_new_from_name(p_inst, psz_name):
4138 '''Discover media service by name.
4139 @param p_inst: libvlc instance.
4140 @param psz_name: service name.
4141 @return: media discover object or None in case of error.
4142 '''
4143 f = _Cfunctions.get('libvlc_media_discoverer_new_from_name', None) or \
4144 _Cfunction('libvlc_media_discoverer_new_from_name', ((1,), (1,),), class_result(MediaDiscoverer),
4145 ctypes.c_void_p, Instance, ctypes.c_char_p)
4146 return f(p_inst, psz_name)
4147
4148def libvlc_media_discoverer_release(p_mdis):
4149 '''Release media discover object. If the reference count reaches 0, then
4150 the object will be released.
4151 @param p_mdis: media service discover object.
4152 '''
4153 f = _Cfunctions.get('libvlc_media_discoverer_release', None) or \
4154 _Cfunction('libvlc_media_discoverer_release', ((1,),), None,
4155 None, MediaDiscoverer)
4156 return f(p_mdis)
4157
4158def libvlc_media_discoverer_localized_name(p_mdis):
4159 '''Get media service discover object its localized name.
4160 @param p_mdis: media discover object.
4161 @return: localized name.
4162 '''
4163 f = _Cfunctions.get('libvlc_media_discoverer_localized_name', None) or \
4164 _Cfunction('libvlc_media_discoverer_localized_name', ((1,),), string_result,
4165 ctypes.c_void_p, MediaDiscoverer)
4166 return f(p_mdis)
4167
4168def libvlc_media_discoverer_media_list(p_mdis):
4169 '''Get media service discover media list.
4170 @param p_mdis: media service discover object.
4171 @return: list of media items.
4172 '''
4173 f = _Cfunctions.get('libvlc_media_discoverer_media_list', None) or \
4174 _Cfunction('libvlc_media_discoverer_media_list', ((1,),), class_result(MediaList),
4175 ctypes.c_void_p, MediaDiscoverer)
4176 return f(p_mdis)
4177
4178def libvlc_media_discoverer_event_manager(p_mdis):
4179 '''Get event manager from media service discover object.
4180 @param p_mdis: media service discover object.
4181 @return: event manager object.
4182 '''
4183 f = _Cfunctions.get('libvlc_media_discoverer_event_manager', None) or \
4184 _Cfunction('libvlc_media_discoverer_event_manager', ((1,),), class_result(EventManager),
4185 ctypes.c_void_p, MediaDiscoverer)
4186 return f(p_mdis)
4187
4188def libvlc_media_discoverer_is_running(p_mdis):
4189 '''Query if media service discover object is running.
4190 @param p_mdis: media service discover object.
4191 @return: true if running, false if not \libvlc_return_bool.
4192 '''
4193 f = _Cfunctions.get('libvlc_media_discoverer_is_running', None) or \
4194 _Cfunction('libvlc_media_discoverer_is_running', ((1,),), None,
4195 ctypes.c_int, MediaDiscoverer)
4196 return f(p_mdis)
4197
4198def libvlc_media_library_new(p_instance):
4199 '''Create an new Media Library object.
4200 @param p_instance: the libvlc instance.
4201 @return: a new object or None on error.
4202 '''
4203 f = _Cfunctions.get('libvlc_media_library_new', None) or \
4204 _Cfunction('libvlc_media_library_new', ((1,),), class_result(MediaLibrary),
4205 ctypes.c_void_p, Instance)
4206 return f(p_instance)
4207
4208def libvlc_media_library_release(p_mlib):
4209 '''Release media library object. This functions decrements the
4210 reference count of the media library object. If it reaches 0,
4211 then the object will be released.
4212 @param p_mlib: media library object.
4213 '''
4214 f = _Cfunctions.get('libvlc_media_library_release', None) or \
4215 _Cfunction('libvlc_media_library_release', ((1,),), None,
4216 None, MediaLibrary)
4217 return f(p_mlib)
4218
4219def libvlc_media_library_retain(p_mlib):
4220 '''Retain a reference to a media library object. This function will
4221 increment the reference counting for this object. Use
4222 L{libvlc_media_library_release}() to decrement the reference count.
4223 @param p_mlib: media library object.
4224 '''
4225 f = _Cfunctions.get('libvlc_media_library_retain', None) or \
4226 _Cfunction('libvlc_media_library_retain', ((1,),), None,
4227 None, MediaLibrary)
4228 return f(p_mlib)
4229
4230def libvlc_media_library_load(p_mlib):
4231 '''Load media library.
4232 @param p_mlib: media library object.
4233 @return: 0 on success, -1 on error.
4234 '''
4235 f = _Cfunctions.get('libvlc_media_library_load', None) or \
4236 _Cfunction('libvlc_media_library_load', ((1,),), None,
4237 ctypes.c_int, MediaLibrary)
4238 return f(p_mlib)
4239
4240def libvlc_media_library_media_list(p_mlib):
4241 '''Get media library subitems.
4242 @param p_mlib: media library object.
4243 @return: media list subitems.
4244 '''
4245 f = _Cfunctions.get('libvlc_media_library_media_list', None) or \
4246 _Cfunction('libvlc_media_library_media_list', ((1,),), class_result(MediaList),
4247 ctypes.c_void_p, MediaLibrary)
4248 return f(p_mlib)
4249
4250def libvlc_vlm_release(p_instance):
4251 '''Release the vlm instance related to the given L{Instance}.
4252 @param p_instance: the instance.
4253 '''
4254 f = _Cfunctions.get('libvlc_vlm_release', None) or \
4255 _Cfunction('libvlc_vlm_release', ((1,),), None,
4256 None, Instance)
4257 return f(p_instance)
4258
4259def libvlc_vlm_add_broadcast(p_instance, psz_name, psz_input, psz_output, i_options, ppsz_options, b_enabled, b_loop):
4260 '''Add a broadcast, with one input.
4261 @param p_instance: the instance.
4262 @param psz_name: the name of the new broadcast.
4263 @param psz_input: the input MRL.
4264 @param psz_output: the output MRL (the parameter to the "sout" variable).
4265 @param i_options: number of additional options.
4266 @param ppsz_options: additional options.
4267 @param b_enabled: boolean for enabling the new broadcast.
4268 @param b_loop: Should this broadcast be played in loop ?
4269 @return: 0 on success, -1 on error.
4270 '''
4271 f = _Cfunctions.get('libvlc_vlm_add_broadcast', None) or \
4272 _Cfunction('libvlc_vlm_add_broadcast', ((1,), (1,), (1,), (1,), (1,), (1,), (1,), (1,),), None,
4273 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int, ListPOINTER(ctypes.c_char_p), ctypes.c_int, ctypes.c_int)
4274 return f(p_instance, psz_name, psz_input, psz_output, i_options, ppsz_options, b_enabled, b_loop)
4275
4276def libvlc_vlm_add_vod(p_instance, psz_name, psz_input, i_options, ppsz_options, b_enabled, psz_mux):
4277 '''Add a vod, with one input.
4278 @param p_instance: the instance.
4279 @param psz_name: the name of the new vod media.
4280 @param psz_input: the input MRL.
4281 @param i_options: number of additional options.
4282 @param ppsz_options: additional options.
4283 @param b_enabled: boolean for enabling the new vod.
4284 @param psz_mux: the muxer of the vod media.
4285 @return: 0 on success, -1 on error.
4286 '''
4287 f = _Cfunctions.get('libvlc_vlm_add_vod', None) or \
4288 _Cfunction('libvlc_vlm_add_vod', ((1,), (1,), (1,), (1,), (1,), (1,), (1,),), None,
4289 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int, ListPOINTER(ctypes.c_char_p), ctypes.c_int, ctypes.c_char_p)
4290 return f(p_instance, psz_name, psz_input, i_options, ppsz_options, b_enabled, psz_mux)
4291
4292def libvlc_vlm_del_media(p_instance, psz_name):
4293 '''Delete a media (VOD or broadcast).
4294 @param p_instance: the instance.
4295 @param psz_name: the media to delete.
4296 @return: 0 on success, -1 on error.
4297 '''
4298 f = _Cfunctions.get('libvlc_vlm_del_media', None) or \
4299 _Cfunction('libvlc_vlm_del_media', ((1,), (1,),), None,
4300 ctypes.c_int, Instance, ctypes.c_char_p)
4301 return f(p_instance, psz_name)
4302
4303def libvlc_vlm_set_enabled(p_instance, psz_name, b_enabled):
4304 '''Enable or disable a media (VOD or broadcast).
4305 @param p_instance: the instance.
4306 @param psz_name: the media to work on.
4307 @param b_enabled: the new status.
4308 @return: 0 on success, -1 on error.
4309 '''
4310 f = _Cfunctions.get('libvlc_vlm_set_enabled', None) or \
4311 _Cfunction('libvlc_vlm_set_enabled', ((1,), (1,), (1,),), None,
4312 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_int)
4313 return f(p_instance, psz_name, b_enabled)
4314
4315def libvlc_vlm_set_output(p_instance, psz_name, psz_output):
4316 '''Set the output for a media.
4317 @param p_instance: the instance.
4318 @param psz_name: the media to work on.
4319 @param psz_output: the output MRL (the parameter to the "sout" variable).
4320 @return: 0 on success, -1 on error.
4321 '''
4322 f = _Cfunctions.get('libvlc_vlm_set_output', None) or \
4323 _Cfunction('libvlc_vlm_set_output', ((1,), (1,), (1,),), None,
4324 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_char_p)
4325 return f(p_instance, psz_name, psz_output)
4326
4327def libvlc_vlm_set_input(p_instance, psz_name, psz_input):
4328 '''Set a media's input MRL. This will delete all existing inputs and
4329 add the specified one.
4330 @param p_instance: the instance.
4331 @param psz_name: the media to work on.
4332 @param psz_input: the input MRL.
4333 @return: 0 on success, -1 on error.
4334 '''
4335 f = _Cfunctions.get('libvlc_vlm_set_input', None) or \
4336 _Cfunction('libvlc_vlm_set_input', ((1,), (1,), (1,),), None,
4337 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_char_p)
4338 return f(p_instance, psz_name, psz_input)
4339
4340def libvlc_vlm_add_input(p_instance, psz_name, psz_input):
4341 '''Add a media's input MRL. This will add the specified one.
4342 @param p_instance: the instance.
4343 @param psz_name: the media to work on.
4344 @param psz_input: the input MRL.
4345 @return: 0 on success, -1 on error.
4346 '''
4347 f = _Cfunctions.get('libvlc_vlm_add_input', None) or \
4348 _Cfunction('libvlc_vlm_add_input', ((1,), (1,), (1,),), None,
4349 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_char_p)
4350 return f(p_instance, psz_name, psz_input)
4351
4352def libvlc_vlm_set_loop(p_instance, psz_name, b_loop):
4353 '''Set a media's loop status.
4354 @param p_instance: the instance.
4355 @param psz_name: the media to work on.
4356 @param b_loop: the new status.
4357 @return: 0 on success, -1 on error.
4358 '''
4359 f = _Cfunctions.get('libvlc_vlm_set_loop', None) or \
4360 _Cfunction('libvlc_vlm_set_loop', ((1,), (1,), (1,),), None,
4361 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_int)
4362 return f(p_instance, psz_name, b_loop)
4363
4364def libvlc_vlm_set_mux(p_instance, psz_name, psz_mux):
4365 '''Set a media's vod muxer.
4366 @param p_instance: the instance.
4367 @param psz_name: the media to work on.
4368 @param psz_mux: the new muxer.
4369 @return: 0 on success, -1 on error.
4370 '''
4371 f = _Cfunctions.get('libvlc_vlm_set_mux', None) or \
4372 _Cfunction('libvlc_vlm_set_mux', ((1,), (1,), (1,),), None,
4373 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_char_p)
4374 return f(p_instance, psz_name, psz_mux)
4375
4376def libvlc_vlm_change_media(p_instance, psz_name, psz_input, psz_output, i_options, ppsz_options, b_enabled, b_loop):
4377 '''Edit the parameters of a media. This will delete all existing inputs and
4378 add the specified one.
4379 @param p_instance: the instance.
4380 @param psz_name: the name of the new broadcast.
4381 @param psz_input: the input MRL.
4382 @param psz_output: the output MRL (the parameter to the "sout" variable).
4383 @param i_options: number of additional options.
4384 @param ppsz_options: additional options.
4385 @param b_enabled: boolean for enabling the new broadcast.
4386 @param b_loop: Should this broadcast be played in loop ?
4387 @return: 0 on success, -1 on error.
4388 '''
4389 f = _Cfunctions.get('libvlc_vlm_change_media', None) or \
4390 _Cfunction('libvlc_vlm_change_media', ((1,), (1,), (1,), (1,), (1,), (1,), (1,), (1,),), None,
4391 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int, ListPOINTER(ctypes.c_char_p), ctypes.c_int, ctypes.c_int)
4392 return f(p_instance, psz_name, psz_input, psz_output, i_options, ppsz_options, b_enabled, b_loop)
4393
4394def libvlc_vlm_play_media(p_instance, psz_name):
4395 '''Play the named broadcast.
4396 @param p_instance: the instance.
4397 @param psz_name: the name of the broadcast.
4398 @return: 0 on success, -1 on error.
4399 '''
4400 f = _Cfunctions.get('libvlc_vlm_play_media', None) or \
4401 _Cfunction('libvlc_vlm_play_media', ((1,), (1,),), None,
4402 ctypes.c_int, Instance, ctypes.c_char_p)
4403 return f(p_instance, psz_name)
4404
4405def libvlc_vlm_stop_media(p_instance, psz_name):
4406 '''Stop the named broadcast.
4407 @param p_instance: the instance.
4408 @param psz_name: the name of the broadcast.
4409 @return: 0 on success, -1 on error.
4410 '''
4411 f = _Cfunctions.get('libvlc_vlm_stop_media', None) or \
4412 _Cfunction('libvlc_vlm_stop_media', ((1,), (1,),), None,
4413 ctypes.c_int, Instance, ctypes.c_char_p)
4414 return f(p_instance, psz_name)
4415
4416def libvlc_vlm_pause_media(p_instance, psz_name):
4417 '''Pause the named broadcast.
4418 @param p_instance: the instance.
4419 @param psz_name: the name of the broadcast.
4420 @return: 0 on success, -1 on error.
4421 '''
4422 f = _Cfunctions.get('libvlc_vlm_pause_media', None) or \
4423 _Cfunction('libvlc_vlm_pause_media', ((1,), (1,),), None,
4424 ctypes.c_int, Instance, ctypes.c_char_p)
4425 return f(p_instance, psz_name)
4426
4427def libvlc_vlm_seek_media(p_instance, psz_name, f_percentage):
4428 '''Seek in the named broadcast.
4429 @param p_instance: the instance.
4430 @param psz_name: the name of the broadcast.
4431 @param f_percentage: the percentage to seek to.
4432 @return: 0 on success, -1 on error.
4433 '''
4434 f = _Cfunctions.get('libvlc_vlm_seek_media', None) or \
4435 _Cfunction('libvlc_vlm_seek_media', ((1,), (1,), (1,),), None,
4436 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_float)
4437 return f(p_instance, psz_name, f_percentage)
4438
4439def libvlc_vlm_show_media(p_instance, psz_name):
4440 '''Return information about the named media as a JSON
4441 string representation.
4442 This function is mainly intended for debugging use,
4443 if you want programmatic access to the state of
4444 a vlm_media_instance_t, please use the corresponding
4445 libvlc_vlm_get_media_instance_xxx -functions.
4446 Currently there are no such functions available for
4447 vlm_media_t though.
4448 @param p_instance: the instance.
4449 @param psz_name: the name of the media, if the name is an empty string, all media is described.
4450 @return: string with information about named media, or None on error.
4451 '''
4452 f = _Cfunctions.get('libvlc_vlm_show_media', None) or \
4453 _Cfunction('libvlc_vlm_show_media', ((1,), (1,),), string_result,
4454 ctypes.c_void_p, Instance, ctypes.c_char_p)
4455 return f(p_instance, psz_name)
4456
4457def libvlc_vlm_get_media_instance_position(p_instance, psz_name, i_instance):
4458 '''Get vlm_media instance position by name or instance id.
4459 @param p_instance: a libvlc instance.
4460 @param psz_name: name of vlm media instance.
4461 @param i_instance: instance id.
4462 @return: position as float or -1. on error.
4463 '''
4464 f = _Cfunctions.get('libvlc_vlm_get_media_instance_position', None) or \
4465 _Cfunction('libvlc_vlm_get_media_instance_position', ((1,), (1,), (1,),), None,
4466 ctypes.c_float, Instance, ctypes.c_char_p, ctypes.c_int)
4467 return f(p_instance, psz_name, i_instance)
4468
4469def libvlc_vlm_get_media_instance_time(p_instance, psz_name, i_instance):
4470 '''Get vlm_media instance time by name or instance id.
4471 @param p_instance: a libvlc instance.
4472 @param psz_name: name of vlm media instance.
4473 @param i_instance: instance id.
4474 @return: time as integer or -1 on error.
4475 '''
4476 f = _Cfunctions.get('libvlc_vlm_get_media_instance_time', None) or \
4477 _Cfunction('libvlc_vlm_get_media_instance_time', ((1,), (1,), (1,),), None,
4478 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_int)
4479 return f(p_instance, psz_name, i_instance)
4480
4481def libvlc_vlm_get_media_instance_length(p_instance, psz_name, i_instance):
4482 '''Get vlm_media instance length by name or instance id.
4483 @param p_instance: a libvlc instance.
4484 @param psz_name: name of vlm media instance.
4485 @param i_instance: instance id.
4486 @return: length of media item or -1 on error.
4487 '''
4488 f = _Cfunctions.get('libvlc_vlm_get_media_instance_length', None) or \
4489 _Cfunction('libvlc_vlm_get_media_instance_length', ((1,), (1,), (1,),), None,
4490 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_int)
4491 return f(p_instance, psz_name, i_instance)
4492
4493def libvlc_vlm_get_media_instance_rate(p_instance, psz_name, i_instance):
4494 '''Get vlm_media instance playback rate by name or instance id.
4495 @param p_instance: a libvlc instance.
4496 @param psz_name: name of vlm media instance.
4497 @param i_instance: instance id.
4498 @return: playback rate or -1 on error.
4499 '''
4500 f = _Cfunctions.get('libvlc_vlm_get_media_instance_rate', None) or \
4501 _Cfunction('libvlc_vlm_get_media_instance_rate', ((1,), (1,), (1,),), None,
4502 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_int)
4503 return f(p_instance, psz_name, i_instance)
4504
4505def libvlc_vlm_get_media_instance_title(p_instance, psz_name, i_instance):
4506 '''Get vlm_media instance title number by name or instance id.
4507 @param p_instance: a libvlc instance.
4508 @param psz_name: name of vlm media instance.
4509 @param i_instance: instance id.
4510 @return: title as number or -1 on error.
4511 @bug: will always return 0.
4512 '''
4513 f = _Cfunctions.get('libvlc_vlm_get_media_instance_title', None) or \
4514 _Cfunction('libvlc_vlm_get_media_instance_title', ((1,), (1,), (1,),), None,
4515 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_int)
4516 return f(p_instance, psz_name, i_instance)
4517
4518def libvlc_vlm_get_media_instance_chapter(p_instance, psz_name, i_instance):
4519 '''Get vlm_media instance chapter number by name or instance id.
4520 @param p_instance: a libvlc instance.
4521 @param psz_name: name of vlm media instance.
4522 @param i_instance: instance id.
4523 @return: chapter as number or -1 on error.
4524 @bug: will always return 0.
4525 '''
4526 f = _Cfunctions.get('libvlc_vlm_get_media_instance_chapter', None) or \
4527 _Cfunction('libvlc_vlm_get_media_instance_chapter', ((1,), (1,), (1,),), None,
4528 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_int)
4529 return f(p_instance, psz_name, i_instance)
4530
4531def libvlc_vlm_get_media_instance_seekable(p_instance, psz_name, i_instance):
4532 '''Is libvlc instance seekable ?
4533 @param p_instance: a libvlc instance.
4534 @param psz_name: name of vlm media instance.
4535 @param i_instance: instance id.
4536 @return: 1 if seekable, 0 if not, -1 if media does not exist.
4537 @bug: will always return 0.
4538 '''
4539 f = _Cfunctions.get('libvlc_vlm_get_media_instance_seekable', None) or \
4540 _Cfunction('libvlc_vlm_get_media_instance_seekable', ((1,), (1,), (1,),), None,
4541 ctypes.c_int, Instance, ctypes.c_char_p, ctypes.c_int)
4542 return f(p_instance, psz_name, i_instance)
4543
4544def libvlc_vlm_get_event_manager(p_instance):
4545 '''Get libvlc_event_manager from a vlm media.
4546 The p_event_manager is immutable, so you don't have to hold the lock.
4547 @param p_instance: a libvlc instance.
4548 @return: libvlc_event_manager.
4549 '''
4550 f = _Cfunctions.get('libvlc_vlm_get_event_manager', None) or \
4551 _Cfunction('libvlc_vlm_get_event_manager', ((1,),), class_result(EventManager),
4552 ctypes.c_void_p, Instance)
4553 return f(p_instance)
4554
4555def libvlc_media_new_location(p_instance, psz_mrl):
4556 '''Create a media with a certain given media resource location,
4557 for instance a valid URL.
4558 @note: To refer to a local file with this function,
4559 the file://... URI syntax B{must} be used (see IETF RFC3986).
4560 We recommend using L{libvlc_media_new_path}() instead when dealing with
4561 local files.
4562 See L{libvlc_media_release}.
4563 @param p_instance: the instance.
4564 @param psz_mrl: the media location.
4565 @return: the newly created media or None on error.
4566 '''
4567 f = _Cfunctions.get('libvlc_media_new_location', None) or \
4568 _Cfunction('libvlc_media_new_location', ((1,), (1,),), class_result(Media),
4569 ctypes.c_void_p, Instance, ctypes.c_char_p)
4570 return f(p_instance, psz_mrl)
4571
4572def libvlc_media_new_path(p_instance, path):
4573 '''Create a media for a certain file path.
4574 See L{libvlc_media_release}.
4575 @param p_instance: the instance.
4576 @param path: local filesystem path.
4577 @return: the newly created media or None on error.
4578 '''
4579 f = _Cfunctions.get('libvlc_media_new_path', None) or \
4580 _Cfunction('libvlc_media_new_path', ((1,), (1,),), class_result(Media),
4581 ctypes.c_void_p, Instance, ctypes.c_char_p)
4582 return f(p_instance, path)
4583
4584def libvlc_media_new_fd(p_instance, fd):
4585 '''Create a media for an already open file descriptor.
4586 The file descriptor shall be open for reading (or reading and writing).
4587 Regular file descriptors, pipe read descriptors and character device
4588 descriptors (including TTYs) are supported on all platforms.
4589 Block device descriptors are supported where available.
4590 Directory descriptors are supported on systems that provide fdopendir().
4591 Sockets are supported on all platforms where they are file descriptors,
4592 i.e. all except Windows.
4593 @note: This library will B{not} automatically close the file descriptor
4594 under any circumstance. Nevertheless, a file descriptor can usually only be
4595 rendered once in a media player. To render it a second time, the file
4596 descriptor should probably be rewound to the beginning with lseek().
4597 See L{libvlc_media_release}.
4598 @param p_instance: the instance.
4599 @param fd: open file descriptor.
4600 @return: the newly created media or None on error.
4601 @version: LibVLC 1.1.5 and later.
4602 '''
4603 f = _Cfunctions.get('libvlc_media_new_fd', None) or \
4604 _Cfunction('libvlc_media_new_fd', ((1,), (1,),), class_result(Media),
4605 ctypes.c_void_p, Instance, ctypes.c_int)
4606 return f(p_instance, fd)
4607
4608def libvlc_media_new_as_node(p_instance, psz_name):
4609 '''Create a media as an empty node with a given name.
4610 See L{libvlc_media_release}.
4611 @param p_instance: the instance.
4612 @param psz_name: the name of the node.
4613 @return: the new empty media or None on error.
4614 '''
4615 f = _Cfunctions.get('libvlc_media_new_as_node', None) or \
4616 _Cfunction('libvlc_media_new_as_node', ((1,), (1,),), class_result(Media),
4617 ctypes.c_void_p, Instance, ctypes.c_char_p)
4618 return f(p_instance, psz_name)
4619
4620def libvlc_media_add_option(p_md, psz_options):
4621 '''Add an option to the media.
4622 This option will be used to determine how the media_player will
4623 read the media. This allows to use VLC's advanced
4624 reading/streaming options on a per-media basis.
4625 @note: The options are listed in 'vlc --long-help' from the command line,
4626 e.g. "-sout-all". Keep in mind that available options and their semantics
4627 vary across LibVLC versions and builds.
4628 @warning: Not all options affects L{Media} objects:
4629 Specifically, due to architectural issues most audio and video options,
4630 such as text renderer options, have no effects on an individual media.
4631 These options must be set through L{libvlc_new}() instead.
4632 @param p_md: the media descriptor.
4633 @param psz_options: the options (as a string).
4634 '''
4635 f = _Cfunctions.get('libvlc_media_add_option', None) or \
4636 _Cfunction('libvlc_media_add_option', ((1,), (1,),), None,
4637 None, Media, ctypes.c_char_p)
4638 return f(p_md, psz_options)
4639
4640def libvlc_media_add_option_flag(p_md, psz_options, i_flags):
4641 '''Add an option to the media with configurable flags.
4642 This option will be used to determine how the media_player will
4643 read the media. This allows to use VLC's advanced
4644 reading/streaming options on a per-media basis.
4645 The options are detailed in vlc --long-help, for instance
4646 "--sout-all". Note that all options are not usable on medias:
4647 specifically, due to architectural issues, video-related options
4648 such as text renderer options cannot be set on a single media. They
4649 must be set on the whole libvlc instance instead.
4650 @param p_md: the media descriptor.
4651 @param psz_options: the options (as a string).
4652 @param i_flags: the flags for this option.
4653 '''
4654 f = _Cfunctions.get('libvlc_media_add_option_flag', None) or \
4655 _Cfunction('libvlc_media_add_option_flag', ((1,), (1,), (1,),), None,
4656 None, Media, ctypes.c_char_p, ctypes.c_uint)
4657 return f(p_md, psz_options, i_flags)
4658
4659def libvlc_media_retain(p_md):
4660 '''Retain a reference to a media descriptor object (libvlc_media_t). Use
4661 L{libvlc_media_release}() to decrement the reference count of a
4662 media descriptor object.
4663 @param p_md: the media descriptor.
4664 '''
4665 f = _Cfunctions.get('libvlc_media_retain', None) or \
4666 _Cfunction('libvlc_media_retain', ((1,),), None,
4667 None, Media)
4668 return f(p_md)
4669
4670def libvlc_media_release(p_md):
4671 '''Decrement the reference count of a media descriptor object. If the
4672 reference count is 0, then L{libvlc_media_release}() will release the
4673 media descriptor object. It will send out an libvlc_MediaFreed event
4674 to all listeners. If the media descriptor object has been released it
4675 should not be used again.
4676 @param p_md: the media descriptor.
4677 '''
4678 f = _Cfunctions.get('libvlc_media_release', None) or \
4679 _Cfunction('libvlc_media_release', ((1,),), None,
4680 None, Media)
4681 return f(p_md)
4682
4683def libvlc_media_get_mrl(p_md):
4684 '''Get the media resource locator (mrl) from a media descriptor object.
4685 @param p_md: a media descriptor object.
4686 @return: string with mrl of media descriptor object.
4687 '''
4688 f = _Cfunctions.get('libvlc_media_get_mrl', None) or \
4689 _Cfunction('libvlc_media_get_mrl', ((1,),), string_result,
4690 ctypes.c_void_p, Media)
4691 return f(p_md)
4692
4693def libvlc_media_duplicate(p_md):
4694 '''Duplicate a media descriptor object.
4695 @param p_md: a media descriptor object.
4696 '''
4697 f = _Cfunctions.get('libvlc_media_duplicate', None) or \
4698 _Cfunction('libvlc_media_duplicate', ((1,),), class_result(Media),
4699 ctypes.c_void_p, Media)
4700 return f(p_md)
4701
4702def libvlc_media_get_meta(p_md, e_meta):
4703 '''Read the meta of the media.
4704 If the media has not yet been parsed this will return None.
4705 This methods automatically calls L{libvlc_media_parse_async}(), so after calling
4706 it you may receive a libvlc_MediaMetaChanged event. If you prefer a synchronous
4707 version ensure that you call L{libvlc_media_parse}() before get_meta().
4708 See L{libvlc_media_parse}
4709 See L{libvlc_media_parse_async}
4710 See libvlc_MediaMetaChanged.
4711 @param p_md: the media descriptor.
4712 @param e_meta: the meta to read.
4713 @return: the media's meta.
4714 '''
4715 f = _Cfunctions.get('libvlc_media_get_meta', None) or \
4716 _Cfunction('libvlc_media_get_meta', ((1,), (1,),), string_result,
4717 ctypes.c_void_p, Media, Meta)
4718 return f(p_md, e_meta)
4719
4720def libvlc_media_set_meta(p_md, e_meta, psz_value):
4721 '''Set the meta of the media (this function will not save the meta, call
4722 L{libvlc_media_save_meta} in order to save the meta).
4723 @param p_md: the media descriptor.
4724 @param e_meta: the meta to write.
4725 @param psz_value: the media's meta.
4726 '''
4727 f = _Cfunctions.get('libvlc_media_set_meta', None) or \
4728 _Cfunction('libvlc_media_set_meta', ((1,), (1,), (1,),), None,
4729 None, Media, Meta, ctypes.c_char_p)
4730 return f(p_md, e_meta, psz_value)
4731
4732def libvlc_media_save_meta(p_md):
4733 '''Save the meta previously set.
4734 @param p_md: the media desriptor.
4735 @return: true if the write operation was successful.
4736 '''
4737 f = _Cfunctions.get('libvlc_media_save_meta', None) or \
4738 _Cfunction('libvlc_media_save_meta', ((1,),), None,
4739 ctypes.c_int, Media)
4740 return f(p_md)
4741
4742def libvlc_media_get_state(p_md):
4743 '''Get current state of media descriptor object. Possible media states
4744 are defined in libvlc_structures.c ( libvlc_NothingSpecial=0,
4745 libvlc_Opening, libvlc_Buffering, libvlc_Playing, libvlc_Paused,
4746 libvlc_Stopped, libvlc_Ended,
4747 libvlc_Error).
4748 See libvlc_state_t.
4749 @param p_md: a media descriptor object.
4750 @return: state of media descriptor object.
4751 '''
4752 f = _Cfunctions.get('libvlc_media_get_state', None) or \
4753 _Cfunction('libvlc_media_get_state', ((1,),), None,
4754 State, Media)
4755 return f(p_md)
4756
4757def libvlc_media_get_stats(p_md, p_stats):
4758 '''Get the current statistics about the media.
4759 @param p_md:: media descriptor object.
4760 @param p_stats:: structure that contain the statistics about the media (this structure must be allocated by the caller).
4761 @return: true if the statistics are available, false otherwise \libvlc_return_bool.
4762 '''
4763 f = _Cfunctions.get('libvlc_media_get_stats', None) or \
4764 _Cfunction('libvlc_media_get_stats', ((1,), (1,),), None,
4765 ctypes.c_int, Media, ctypes.POINTER(MediaStats))
4766 return f(p_md, p_stats)
4767
4768def libvlc_media_subitems(p_md):
4769 '''Get subitems of media descriptor object. This will increment
4770 the reference count of supplied media descriptor object. Use
4771 L{libvlc_media_list_release}() to decrement the reference counting.
4772 @param p_md: media descriptor object.
4773 @return: list of media descriptor subitems or None.
4774 '''
4775 f = _Cfunctions.get('libvlc_media_subitems', None) or \
4776 _Cfunction('libvlc_media_subitems', ((1,),), class_result(MediaList),
4777 ctypes.c_void_p, Media)
4778 return f(p_md)
4779
4780def libvlc_media_event_manager(p_md):
4781 '''Get event manager from media descriptor object.
4782 NOTE: this function doesn't increment reference counting.
4783 @param p_md: a media descriptor object.
4784 @return: event manager object.
4785 '''
4786 f = _Cfunctions.get('libvlc_media_event_manager', None) or \
4787 _Cfunction('libvlc_media_event_manager', ((1,),), class_result(EventManager),
4788 ctypes.c_void_p, Media)
4789 return f(p_md)
4790
4791def libvlc_media_get_duration(p_md):
4792 '''Get duration (in ms) of media descriptor object item.
4793 @param p_md: media descriptor object.
4794 @return: duration of media item or -1 on error.
4795 '''
4796 f = _Cfunctions.get('libvlc_media_get_duration', None) or \
4797 _Cfunction('libvlc_media_get_duration', ((1,),), None,
4798 ctypes.c_longlong, Media)
4799 return f(p_md)
4800
4801def libvlc_media_parse(p_md):
4802 '''Parse a media.
4803 This fetches (local) meta data and tracks information.
4804 The method is synchronous.
4805 See L{libvlc_media_parse_async}
4806 See L{libvlc_media_get_meta}
4807 See L{libvlc_media_get_tracks_info}.
4808 @param p_md: media descriptor object.
4809 '''
4810 f = _Cfunctions.get('libvlc_media_parse', None) or \
4811 _Cfunction('libvlc_media_parse', ((1,),), None,
4812 None, Media)
4813 return f(p_md)
4814
4815def libvlc_media_parse_async(p_md):
4816 '''Parse a media.
4817 This fetches (local) meta data and tracks information.
4818 The method is the asynchronous of L{libvlc_media_parse}().
4819 To track when this is over you can listen to libvlc_MediaParsedChanged
4820 event. However if the media was already parsed you will not receive this
4821 event.
4822 See L{libvlc_media_parse}
4823 See libvlc_MediaParsedChanged
4824 See L{libvlc_media_get_meta}
4825 See L{libvlc_media_get_tracks_info}.
4826 @param p_md: media descriptor object.
4827 '''
4828 f = _Cfunctions.get('libvlc_media_parse_async', None) or \
4829 _Cfunction('libvlc_media_parse_async', ((1,),), None,
4830 None, Media)
4831 return f(p_md)
4832
4833def libvlc_media_is_parsed(p_md):
4834 '''Get Parsed status for media descriptor object.
4835 See libvlc_MediaParsedChanged.
4836 @param p_md: media descriptor object.
4837 @return: true if media object has been parsed otherwise it returns false \libvlc_return_bool.
4838 '''
4839 f = _Cfunctions.get('libvlc_media_is_parsed', None) or \
4840 _Cfunction('libvlc_media_is_parsed', ((1,),), None,
4841 ctypes.c_int, Media)
4842 return f(p_md)
4843
4844def libvlc_media_set_user_data(p_md, p_new_user_data):
4845 '''Sets media descriptor's user_data. user_data is specialized data
4846 accessed by the host application, VLC.framework uses it as a pointer to
4847 an native object that references a L{Media} pointer.
4848 @param p_md: media descriptor object.
4849 @param p_new_user_data: pointer to user data.
4850 '''
4851 f = _Cfunctions.get('libvlc_media_set_user_data', None) or \
4852 _Cfunction('libvlc_media_set_user_data', ((1,), (1,),), None,
4853 None, Media, ctypes.c_void_p)
4854 return f(p_md, p_new_user_data)
4855
4856def libvlc_media_get_user_data(p_md):
4857 '''Get media descriptor's user_data. user_data is specialized data
4858 accessed by the host application, VLC.framework uses it as a pointer to
4859 an native object that references a L{Media} pointer.
4860 @param p_md: media descriptor object.
4861 '''
4862 f = _Cfunctions.get('libvlc_media_get_user_data', None) or \
4863 _Cfunction('libvlc_media_get_user_data', ((1,),), None,
4864 ctypes.c_void_p, Media)
4865 return f(p_md)
4866
4867def libvlc_media_get_tracks_info(p_md):
4868 '''Get media descriptor's elementary streams description
4869 Note, you need to call L{libvlc_media_parse}() or play the media at least once
4870 before calling this function.
4871 Not doing this will result in an empty array.
4872 \deprecated Use L{libvlc_media_tracks_get} instead.
4873 @param p_md: media descriptor object.
4874 @param tracks: address to store an allocated array of Elementary Streams descriptions (must be freed by the caller) [OUT].
4875 @return: the number of Elementary Streams.
4876 '''
4877 f = _Cfunctions.get('libvlc_media_get_tracks_info', None) or \
4878 _Cfunction('libvlc_media_get_tracks_info', ((1,), (2,),), None,
4879 ctypes.c_int, Media, ctypes.POINTER(ctypes.c_void_p))
4880 return f(p_md)
4881
4882def libvlc_media_tracks_get(p_md, tracks):
4883 '''Get media descriptor's elementary streams description
4884 Note, you need to call L{libvlc_media_parse}() or play the media at least once
4885 before calling this function.
4886 Not doing this will result in an empty array.
4887 @param p_md: media descriptor object.
4888 @param tracks: address to store an allocated array of Elementary Streams descriptions (must be freed with L{libvlc_media_tracks_release}.
4889 @return: the number of Elementary Streams (zero on error).
4890 @version: LibVLC 2.1.0 and later.
4891 '''
4892 f = _Cfunctions.get('libvlc_media_tracks_get', None) or \
4893 _Cfunction('libvlc_media_tracks_get', ((1,), (1,),), None,
4894 ctypes.c_uint, Media, ctypes.POINTER(ctypes.POINTER(MediaTrack)))
4895 return f(p_md, tracks)
4896
4897def libvlc_media_tracks_release(p_tracks, i_count):
4898 '''Release media descriptor's elementary streams description array.
4899 @param p_tracks: tracks info array to release.
4900 @param i_count: number of elements in the array.
4901 @version: LibVLC 2.1.0 and later.
4902 '''
4903 f = _Cfunctions.get('libvlc_media_tracks_release', None) or \
4904 _Cfunction('libvlc_media_tracks_release', ((1,), (1,),), None,
4905 None, ctypes.POINTER(MediaTrack), ctypes.c_uint)
4906 return f(p_tracks, i_count)
4907
4908def libvlc_media_list_new(p_instance):
4909 '''Create an empty media list.
4910 @param p_instance: libvlc instance.
4911 @return: empty media list, or None on error.
4912 '''
4913 f = _Cfunctions.get('libvlc_media_list_new', None) or \
4914 _Cfunction('libvlc_media_list_new', ((1,),), class_result(MediaList),
4915 ctypes.c_void_p, Instance)
4916 return f(p_instance)
4917
4918def libvlc_media_list_release(p_ml):
4919 '''Release media list created with L{libvlc_media_list_new}().
4920 @param p_ml: a media list created with L{libvlc_media_list_new}().
4921 '''
4922 f = _Cfunctions.get('libvlc_media_list_release', None) or \
4923 _Cfunction('libvlc_media_list_release', ((1,),), None,
4924 None, MediaList)
4925 return f(p_ml)
4926
4927def libvlc_media_list_retain(p_ml):
4928 '''Retain reference to a media list.
4929 @param p_ml: a media list created with L{libvlc_media_list_new}().
4930 '''
4931 f = _Cfunctions.get('libvlc_media_list_retain', None) or \
4932 _Cfunction('libvlc_media_list_retain', ((1,),), None,
4933 None, MediaList)
4934 return f(p_ml)
4935
4936def libvlc_media_list_set_media(p_ml, p_md):
4937 '''Associate media instance with this media list instance.
4938 If another media instance was present it will be released.
4939 The L{libvlc_media_list_lock} should NOT be held upon entering this function.
4940 @param p_ml: a media list instance.
4941 @param p_md: media instance to add.
4942 '''
4943 f = _Cfunctions.get('libvlc_media_list_set_media', None) or \
4944 _Cfunction('libvlc_media_list_set_media', ((1,), (1,),), None,
4945 None, MediaList, Media)
4946 return f(p_ml, p_md)
4947
4948def libvlc_media_list_media(p_ml):
4949 '''Get media instance from this media list instance. This action will increase
4950 the refcount on the media instance.
4951 The L{libvlc_media_list_lock} should NOT be held upon entering this function.
4952 @param p_ml: a media list instance.
4953 @return: media instance.
4954 '''
4955 f = _Cfunctions.get('libvlc_media_list_media', None) or \
4956 _Cfunction('libvlc_media_list_media', ((1,),), class_result(Media),
4957 ctypes.c_void_p, MediaList)
4958 return f(p_ml)
4959
4960def libvlc_media_list_add_media(p_ml, p_md):
4961 '''Add media instance to media list
4962 The L{libvlc_media_list_lock} should be held upon entering this function.
4963 @param p_ml: a media list instance.
4964 @param p_md: a media instance.
4965 @return: 0 on success, -1 if the media list is read-only.
4966 '''
4967 f = _Cfunctions.get('libvlc_media_list_add_media', None) or \
4968 _Cfunction('libvlc_media_list_add_media', ((1,), (1,),), None,
4969 ctypes.c_int, MediaList, Media)
4970 return f(p_ml, p_md)
4971
4972def libvlc_media_list_insert_media(p_ml, p_md, i_pos):
4973 '''Insert media instance in media list on a position
4974 The L{libvlc_media_list_lock} should be held upon entering this function.
4975 @param p_ml: a media list instance.
4976 @param p_md: a media instance.
4977 @param i_pos: position in array where to insert.
4978 @return: 0 on success, -1 if the media list is read-only.
4979 '''
4980 f = _Cfunctions.get('libvlc_media_list_insert_media', None) or \
4981 _Cfunction('libvlc_media_list_insert_media', ((1,), (1,), (1,),), None,
4982 ctypes.c_int, MediaList, Media, ctypes.c_int)
4983 return f(p_ml, p_md, i_pos)
4984
4985def libvlc_media_list_remove_index(p_ml, i_pos):
4986 '''Remove media instance from media list on a position
4987 The L{libvlc_media_list_lock} should be held upon entering this function.
4988 @param p_ml: a media list instance.
4989 @param i_pos: position in array where to insert.
4990 @return: 0 on success, -1 if the list is read-only or the item was not found.
4991 '''
4992 f = _Cfunctions.get('libvlc_media_list_remove_index', None) or \
4993 _Cfunction('libvlc_media_list_remove_index', ((1,), (1,),), None,
4994 ctypes.c_int, MediaList, ctypes.c_int)
4995 return f(p_ml, i_pos)
4996
4997def libvlc_media_list_count(p_ml):
4998 '''Get count on media list items
4999 The L{libvlc_media_list_lock} should be held upon entering this function.
5000 @param p_ml: a media list instance.
5001 @return: number of items in media list.
5002 '''
5003 f = _Cfunctions.get('libvlc_media_list_count', None) or \
5004 _Cfunction('libvlc_media_list_count', ((1,),), None,
5005 ctypes.c_int, MediaList)
5006 return f(p_ml)
5007
5008def libvlc_media_list_item_at_index(p_ml, i_pos):
5009 '''List media instance in media list at a position
5010 The L{libvlc_media_list_lock} should be held upon entering this function.
5011 @param p_ml: a media list instance.
5012 @param i_pos: position in array where to insert.
5013 @return: media instance at position i_pos, or None if not found. In case of success, L{libvlc_media_retain}() is called to increase the refcount on the media.
5014 '''
5015 f = _Cfunctions.get('libvlc_media_list_item_at_index', None) or \
5016 _Cfunction('libvlc_media_list_item_at_index', ((1,), (1,),), class_result(Media),
5017 ctypes.c_void_p, MediaList, ctypes.c_int)
5018 return f(p_ml, i_pos)
5019
5020def libvlc_media_list_index_of_item(p_ml, p_md):
5021 '''Find index position of List media instance in media list.
5022 Warning: the function will return the first matched position.
5023 The L{libvlc_media_list_lock} should be held upon entering this function.
5024 @param p_ml: a media list instance.
5025 @param p_md: media instance.
5026 @return: position of media instance or -1 if media not found.
5027 '''
5028 f = _Cfunctions.get('libvlc_media_list_index_of_item', None) or \
5029 _Cfunction('libvlc_media_list_index_of_item', ((1,), (1,),), None,
5030 ctypes.c_int, MediaList, Media)
5031 return f(p_ml, p_md)
5032
5033def libvlc_media_list_is_readonly(p_ml):
5034 '''This indicates if this media list is read-only from a user point of view.
5035 @param p_ml: media list instance.
5036 @return: 1 on readonly, 0 on readwrite \libvlc_return_bool.
5037 '''
5038 f = _Cfunctions.get('libvlc_media_list_is_readonly', None) or \
5039 _Cfunction('libvlc_media_list_is_readonly', ((1,),), None,
5040 ctypes.c_int, MediaList)
5041 return f(p_ml)
5042
5043def libvlc_media_list_lock(p_ml):
5044 '''Get lock on media list items.
5045 @param p_ml: a media list instance.
5046 '''
5047 f = _Cfunctions.get('libvlc_media_list_lock', None) or \
5048 _Cfunction('libvlc_media_list_lock', ((1,),), None,
5049 None, MediaList)
5050 return f(p_ml)
5051
5052def libvlc_media_list_unlock(p_ml):
5053 '''Release lock on media list items
5054 The L{libvlc_media_list_lock} should be held upon entering this function.
5055 @param p_ml: a media list instance.
5056 '''
5057 f = _Cfunctions.get('libvlc_media_list_unlock', None) or \
5058 _Cfunction('libvlc_media_list_unlock', ((1,),), None,
5059 None, MediaList)
5060 return f(p_ml)
5061
5062def libvlc_media_list_event_manager(p_ml):
5063 '''Get libvlc_event_manager from this media list instance.
5064 The p_event_manager is immutable, so you don't have to hold the lock.
5065 @param p_ml: a media list instance.
5066 @return: libvlc_event_manager.
5067 '''
5068 f = _Cfunctions.get('libvlc_media_list_event_manager', None) or \
5069 _Cfunction('libvlc_media_list_event_manager', ((1,),), class_result(EventManager),
5070 ctypes.c_void_p, MediaList)
5071 return f(p_ml)
5072
5073def libvlc_playlist_play(p_instance, i_id, i_options, ppsz_options):
5074 '''Start playing (if there is any item in the playlist).
5075 Additionnal playlist item options can be specified for addition to the
5076 item before it is played.
5077 @param p_instance: the playlist instance.
5078 @param i_id: the item to play. If this is a negative number, the next item will be selected. Otherwise, the item with the given ID will be played.
5079 @param i_options: the number of options to add to the item.
5080 @param ppsz_options: the options to add to the item.
5081 '''
5082 f = _Cfunctions.get('libvlc_playlist_play', None) or \
5083 _Cfunction('libvlc_playlist_play', ((1,), (1,), (1,), (1,),), None,
5084 None, Instance, ctypes.c_int, ctypes.c_int, ListPOINTER(ctypes.c_char_p))
5085 return f(p_instance, i_id, i_options, ppsz_options)
5086
5087def libvlc_media_player_new(p_libvlc_instance):
5088 '''Create an empty Media Player object.
5089 @param p_libvlc_instance: the libvlc instance in which the Media Player should be created.
5090 @return: a new media player object, or None on error.
5091 '''
5092 f = _Cfunctions.get('libvlc_media_player_new', None) or \
5093 _Cfunction('libvlc_media_player_new', ((1,),), class_result(MediaPlayer),
5094 ctypes.c_void_p, Instance)
5095 return f(p_libvlc_instance)
5096
5097def libvlc_media_player_new_from_media(p_md):
5098 '''Create a Media Player object from a Media.
5099 @param p_md: the media. Afterwards the p_md can be safely destroyed.
5100 @return: a new media player object, or None on error.
5101 '''
5102 f = _Cfunctions.get('libvlc_media_player_new_from_media', None) or \
5103 _Cfunction('libvlc_media_player_new_from_media', ((1,),), class_result(MediaPlayer),
5104 ctypes.c_void_p, Media)
5105 return f(p_md)
5106
5107def libvlc_media_player_release(p_mi):
5108 '''Release a media_player after use
5109 Decrement the reference count of a media player object. If the
5110 reference count is 0, then L{libvlc_media_player_release}() will
5111 release the media player object. If the media player object
5112 has been released, then it should not be used again.
5113 @param p_mi: the Media Player to free.
5114 '''
5115 f = _Cfunctions.get('libvlc_media_player_release', None) or \
5116 _Cfunction('libvlc_media_player_release', ((1,),), None,
5117 None, MediaPlayer)
5118 return f(p_mi)
5119
5120def libvlc_media_player_retain(p_mi):
5121 '''Retain a reference to a media player object. Use
5122 L{libvlc_media_player_release}() to decrement reference count.
5123 @param p_mi: media player object.
5124 '''
5125 f = _Cfunctions.get('libvlc_media_player_retain', None) or \
5126 _Cfunction('libvlc_media_player_retain', ((1,),), None,
5127 None, MediaPlayer)
5128 return f(p_mi)
5129
5130def libvlc_media_player_set_media(p_mi, p_md):
5131 '''Set the media that will be used by the media_player. If any,
5132 previous md will be released.
5133 @param p_mi: the Media Player.
5134 @param p_md: the Media. Afterwards the p_md can be safely destroyed.
5135 '''
5136 f = _Cfunctions.get('libvlc_media_player_set_media', None) or \
5137 _Cfunction('libvlc_media_player_set_media', ((1,), (1,),), None,
5138 None, MediaPlayer, Media)
5139 return f(p_mi, p_md)
5140
5141def libvlc_media_player_get_media(p_mi):
5142 '''Get the media used by the media_player.
5143 @param p_mi: the Media Player.
5144 @return: the media associated with p_mi, or None if no media is associated.
5145 '''
5146 f = _Cfunctions.get('libvlc_media_player_get_media', None) or \
5147 _Cfunction('libvlc_media_player_get_media', ((1,),), class_result(Media),
5148 ctypes.c_void_p, MediaPlayer)
5149 return f(p_mi)
5150
5151def libvlc_media_player_event_manager(p_mi):
5152 '''Get the Event Manager from which the media player send event.
5153 @param p_mi: the Media Player.
5154 @return: the event manager associated with p_mi.
5155 '''
5156 f = _Cfunctions.get('libvlc_media_player_event_manager', None) or \
5157 _Cfunction('libvlc_media_player_event_manager', ((1,),), class_result(EventManager),
5158 ctypes.c_void_p, MediaPlayer)
5159 return f(p_mi)
5160
5161def libvlc_media_player_is_playing(p_mi):
5162 '''is_playing.
5163 @param p_mi: the Media Player.
5164 @return: 1 if the media player is playing, 0 otherwise \libvlc_return_bool.
5165 '''
5166 f = _Cfunctions.get('libvlc_media_player_is_playing', None) or \
5167 _Cfunction('libvlc_media_player_is_playing', ((1,),), None,
5168 ctypes.c_int, MediaPlayer)
5169 return f(p_mi)
5170
5171def libvlc_media_player_play(p_mi):
5172 '''Play.
5173 @param p_mi: the Media Player.
5174 @return: 0 if playback started (and was already started), or -1 on error.
5175 '''
5176 f = _Cfunctions.get('libvlc_media_player_play', None) or \
5177 _Cfunction('libvlc_media_player_play', ((1,),), None,
5178 ctypes.c_int, MediaPlayer)
5179 return f(p_mi)
5180
5181def libvlc_media_player_set_pause(mp, do_pause):
5182 '''Pause or resume (no effect if there is no media).
5183 @param mp: the Media Player.
5184 @param do_pause: play/resume if zero, pause if non-zero.
5185 @version: LibVLC 1.1.1 or later.
5186 '''
5187 f = _Cfunctions.get('libvlc_media_player_set_pause', None) or \
5188 _Cfunction('libvlc_media_player_set_pause', ((1,), (1,),), None,
5189 None, MediaPlayer, ctypes.c_int)
5190 return f(mp, do_pause)
5191
5192def libvlc_media_player_pause(p_mi):
5193 '''Toggle pause (no effect if there is no media).
5194 @param p_mi: the Media Player.
5195 '''
5196 f = _Cfunctions.get('libvlc_media_player_pause', None) or \
5197 _Cfunction('libvlc_media_player_pause', ((1,),), None,
5198 None, MediaPlayer)
5199 return f(p_mi)
5200
5201def libvlc_media_player_stop(p_mi):
5202 '''Stop (no effect if there is no media).
5203 @param p_mi: the Media Player.
5204 '''
5205 f = _Cfunctions.get('libvlc_media_player_stop', None) or \
5206 _Cfunction('libvlc_media_player_stop', ((1,),), None,
5207 None, MediaPlayer)
5208 return f(p_mi)
5209
5210def libvlc_video_set_callbacks(mp, lock, unlock, display, opaque):
5211 '''Set callbacks and private data to render decoded video to a custom area
5212 in memory.
5213 Use L{libvlc_video_set_format}() or L{libvlc_video_set_format_callbacks}()
5214 to configure the decoded format.
5215 @param mp: the media player.
5216 @param lock: callback to lock video memory (must not be None).
5217 @param unlock: callback to unlock video memory (or None if not needed).
5218 @param display: callback to display video (or None if not needed).
5219 @param opaque: private pointer for the three callbacks (as first parameter).
5220 @version: LibVLC 1.1.1 or later.
5221 '''
5222 f = _Cfunctions.get('libvlc_video_set_callbacks', None) or \
5223 _Cfunction('libvlc_video_set_callbacks', ((1,), (1,), (1,), (1,), (1,),), None,
5224 None, MediaPlayer, VideoLockCb, VideoUnlockCb, VideoDisplayCb, ctypes.c_void_p)
5225 return f(mp, lock, unlock, display, opaque)
5226
5227def libvlc_video_set_format(mp, chroma, width, height, pitch):
5228 '''Set decoded video chroma and dimensions.
5229 This only works in combination with L{libvlc_video_set_callbacks}(),
5230 and is mutually exclusive with L{libvlc_video_set_format_callbacks}().
5231 @param mp: the media player.
5232 @param chroma: a four-characters string identifying the chroma (e.g. "RV32" or "YUYV").
5233 @param width: pixel width.
5234 @param height: pixel height.
5235 @param pitch: line pitch (in bytes).
5236 @version: LibVLC 1.1.1 or later.
5237 @bug: All pixel planes are expected to have the same pitch. To use the YCbCr color space with chrominance subsampling, consider using L{libvlc_video_set_format_callbacks}() instead.
5238 '''
5239 f = _Cfunctions.get('libvlc_video_set_format', None) or \
5240 _Cfunction('libvlc_video_set_format', ((1,), (1,), (1,), (1,), (1,),), None,
5241 None, MediaPlayer, ctypes.c_char_p, ctypes.c_uint, ctypes.c_uint, ctypes.c_uint)
5242 return f(mp, chroma, width, height, pitch)
5243
5244def libvlc_video_set_format_callbacks(mp, setup, cleanup):
5245 '''Set decoded video chroma and dimensions. This only works in combination with
5246 L{libvlc_video_set_callbacks}().
5247 @param mp: the media player.
5248 @param setup: callback to select the video format (cannot be None).
5249 @param cleanup: callback to release any allocated resources (or None).
5250 @version: LibVLC 2.0.0 or later.
5251 '''
5252 f = _Cfunctions.get('libvlc_video_set_format_callbacks', None) or \
5253 _Cfunction('libvlc_video_set_format_callbacks', ((1,), (1,), (1,),), None,
5254 None, MediaPlayer, VideoFormatCb, VideoCleanupCb)
5255 return f(mp, setup, cleanup)
5256
5257def libvlc_media_player_set_nsobject(p_mi, drawable):
5258 '''Set the NSView handler where the media player should render its video output.
5259 Use the vout called "macosx".
5260 The drawable is an NSObject that follow the VLCOpenGLVideoViewEmbedding
5261 protocol:
5262 @begincode
5263 \@protocol VLCOpenGLVideoViewEmbedding <NSObject>
5264 - (void)addVoutSubview:(NSView *)view;
5265 - (void)removeVoutSubview:(NSView *)view;
5266 \@end
5267 @endcode
5268 Or it can be an NSView object.
5269 If you want to use it along with Qt4 see the QMacCocoaViewContainer. Then
5270 the following code should work:
5271 @begincode
5272
5273 NSView *video = [[NSView alloc] init];
5274 QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
5275 L{libvlc_media_player_set_nsobject}(mp, video);
5276 [video release];
5277
5278 @endcode
5279 You can find a live example in VLCVideoView in VLCKit.framework.
5280 @param p_mi: the Media Player.
5281 @param drawable: the drawable that is either an NSView or an object following the VLCOpenGLVideoViewEmbedding protocol.
5282 '''
5283 f = _Cfunctions.get('libvlc_media_player_set_nsobject', None) or \
5284 _Cfunction('libvlc_media_player_set_nsobject', ((1,), (1,),), None,
5285 None, MediaPlayer, ctypes.c_void_p)
5286 return f(p_mi, drawable)
5287
5288def libvlc_media_player_get_nsobject(p_mi):
5289 '''Get the NSView handler previously set with L{libvlc_media_player_set_nsobject}().
5290 @param p_mi: the Media Player.
5291 @return: the NSView handler or 0 if none where set.
5292 '''
5293 f = _Cfunctions.get('libvlc_media_player_get_nsobject', None) or \
5294 _Cfunction('libvlc_media_player_get_nsobject', ((1,),), None,
5295 ctypes.c_void_p, MediaPlayer)
5296 return f(p_mi)
5297
5298def libvlc_media_player_set_agl(p_mi, drawable):
5299 '''Set the agl handler where the media player should render its video output.
5300 @param p_mi: the Media Player.
5301 @param drawable: the agl handler.
5302 '''
5303 f = _Cfunctions.get('libvlc_media_player_set_agl', None) or \
5304 _Cfunction('libvlc_media_player_set_agl', ((1,), (1,),), None,
5305 None, MediaPlayer, ctypes.c_uint32)
5306 return f(p_mi, drawable)
5307
5308def libvlc_media_player_get_agl(p_mi):
5309 '''Get the agl handler previously set with L{libvlc_media_player_set_agl}().
5310 @param p_mi: the Media Player.
5311 @return: the agl handler or 0 if none where set.
5312 '''
5313 f = _Cfunctions.get('libvlc_media_player_get_agl', None) or \
5314 _Cfunction('libvlc_media_player_get_agl', ((1,),), None,
5315 ctypes.c_uint32, MediaPlayer)
5316 return f(p_mi)
5317
5318def libvlc_media_player_set_xwindow(p_mi, drawable):
5319 '''Set an X Window System drawable where the media player should render its
5320 video output. If LibVLC was built without X11 output support, then this has
5321 no effects.
5322 The specified identifier must correspond to an existing Input/Output class
5323 X11 window. Pixmaps are B{not} supported. The caller shall ensure that
5324 the X11 server is the same as the one the VLC instance has been configured
5325 with. This function must be called before video playback is started;
5326 otherwise it will only take effect after playback stop and restart.
5327 @param p_mi: the Media Player.
5328 @param drawable: the ID of the X window.
5329 '''
5330 f = _Cfunctions.get('libvlc_media_player_set_xwindow', None) or \
5331 _Cfunction('libvlc_media_player_set_xwindow', ((1,), (1,),), None,
5332 None, MediaPlayer, ctypes.c_uint32)
5333 return f(p_mi, drawable)
5334
5335def libvlc_media_player_get_xwindow(p_mi):
5336 '''Get the X Window System window identifier previously set with
5337 L{libvlc_media_player_set_xwindow}(). Note that this will return the identifier
5338 even if VLC is not currently using it (for instance if it is playing an
5339 audio-only input).
5340 @param p_mi: the Media Player.
5341 @return: an X window ID, or 0 if none where set.
5342 '''
5343 f = _Cfunctions.get('libvlc_media_player_get_xwindow', None) or \
5344 _Cfunction('libvlc_media_player_get_xwindow', ((1,),), None,
5345 ctypes.c_uint32, MediaPlayer)
5346 return f(p_mi)
5347
5348def libvlc_media_player_set_hwnd(p_mi, drawable):
5349 '''Set a Win32/Win64 API window handle (HWND) where the media player should
5350 render its video output. If LibVLC was built without Win32/Win64 API output
5351 support, then this has no effects.
5352 @param p_mi: the Media Player.
5353 @param drawable: windows handle of the drawable.
5354 '''
5355 f = _Cfunctions.get('libvlc_media_player_set_hwnd', None) or \
5356 _Cfunction('libvlc_media_player_set_hwnd', ((1,), (1,),), None,
5357 None, MediaPlayer, ctypes.c_void_p)
5358 return f(p_mi, drawable)
5359
5360def libvlc_media_player_get_hwnd(p_mi):
5361 '''Get the Windows API window handle (HWND) previously set with
5362 L{libvlc_media_player_set_hwnd}(). The handle will be returned even if LibVLC
5363 is not currently outputting any video to it.
5364 @param p_mi: the Media Player.
5365 @return: a window handle or None if there are none.
5366 '''
5367 f = _Cfunctions.get('libvlc_media_player_get_hwnd', None) or \
5368 _Cfunction('libvlc_media_player_get_hwnd', ((1,),), None,
5369 ctypes.c_void_p, MediaPlayer)
5370 return f(p_mi)
5371
5372def libvlc_audio_set_callbacks(mp, play, pause, resume, flush, drain, opaque):
5373 '''Set callbacks and private data for decoded audio.
5374 Use L{libvlc_audio_set_format}() or L{libvlc_audio_set_format_callbacks}()
5375 to configure the decoded audio format.
5376 @param mp: the media player.
5377 @param play: callback to play audio samples (must not be None).
5378 @param pause: callback to pause playback (or None to ignore).
5379 @param resume: callback to resume playback (or None to ignore).
5380 @param flush: callback to flush audio buffers (or None to ignore).
5381 @param drain: callback to drain audio buffers (or None to ignore).
5382 @param opaque: private pointer for the audio callbacks (as first parameter).
5383 @version: LibVLC 2.0.0 or later.
5384 '''
5385 f = _Cfunctions.get('libvlc_audio_set_callbacks', None) or \
5386 _Cfunction('libvlc_audio_set_callbacks', ((1,), (1,), (1,), (1,), (1,), (1,), (1,),), None,
5387 None, MediaPlayer, AudioPlayCb, AudioPauseCb, AudioResumeCb, AudioFlushCb, AudioDrainCb, ctypes.c_void_p)
5388 return f(mp, play, pause, resume, flush, drain, opaque)
5389
5390def libvlc_audio_set_volume_callback(mp, set_volume):
5391 '''Set callbacks and private data for decoded audio. This only works in
5392 combination with L{libvlc_audio_set_callbacks}().
5393 Use L{libvlc_audio_set_format}() or L{libvlc_audio_set_format_callbacks}()
5394 to configure the decoded audio format.
5395 @param mp: the media player.
5396 @param set_volume: callback to apply audio volume, or None to apply volume in software.
5397 @version: LibVLC 2.0.0 or later.
5398 '''
5399 f = _Cfunctions.get('libvlc_audio_set_volume_callback', None) or \
5400 _Cfunction('libvlc_audio_set_volume_callback', ((1,), (1,),), None,
5401 None, MediaPlayer, AudioSetVolumeCb)
5402 return f(mp, set_volume)
5403
5404def libvlc_audio_set_format_callbacks(mp, setup, cleanup):
5405 '''Set decoded audio format. This only works in combination with
5406 L{libvlc_audio_set_callbacks}().
5407 @param mp: the media player.
5408 @param setup: callback to select the audio format (cannot be None).
5409 @param cleanup: callback to release any allocated resources (or None).
5410 @version: LibVLC 2.0.0 or later.
5411 '''
5412 f = _Cfunctions.get('libvlc_audio_set_format_callbacks', None) or \
5413 _Cfunction('libvlc_audio_set_format_callbacks', ((1,), (1,), (1,),), None,
5414 None, MediaPlayer, AudioSetupCb, AudioCleanupCb)
5415 return f(mp, setup, cleanup)
5416
5417def libvlc_audio_set_format(mp, format, rate, channels):
5418 '''Set decoded audio format.
5419 This only works in combination with L{libvlc_audio_set_callbacks}(),
5420 and is mutually exclusive with L{libvlc_audio_set_format_callbacks}().
5421 @param mp: the media player.
5422 @param format: a four-characters string identifying the sample format (e.g. "S16N" or "FL32").
5423 @param rate: sample rate (expressed in Hz).
5424 @param channels: channels count.
5425 @version: LibVLC 2.0.0 or later.
5426 '''
5427 f = _Cfunctions.get('libvlc_audio_set_format', None) or \
5428 _Cfunction('libvlc_audio_set_format', ((1,), (1,), (1,), (1,),), None,
5429 None, MediaPlayer, ctypes.c_char_p, ctypes.c_uint, ctypes.c_uint)
5430 return f(mp, format, rate, channels)
5431
5432def libvlc_media_player_get_length(p_mi):
5433 '''Get the current movie length (in ms).
5434 @param p_mi: the Media Player.
5435 @return: the movie length (in ms), or -1 if there is no media.
5436 '''
5437 f = _Cfunctions.get('libvlc_media_player_get_length', None) or \
5438 _Cfunction('libvlc_media_player_get_length', ((1,),), None,
5439 ctypes.c_longlong, MediaPlayer)
5440 return f(p_mi)
5441
5442def libvlc_media_player_get_time(p_mi):
5443 '''Get the current movie time (in ms).
5444 @param p_mi: the Media Player.
5445 @return: the movie time (in ms), or -1 if there is no media.
5446 '''
5447 f = _Cfunctions.get('libvlc_media_player_get_time', None) or \
5448 _Cfunction('libvlc_media_player_get_time', ((1,),), None,
5449 ctypes.c_longlong, MediaPlayer)
5450 return f(p_mi)
5451
5452def libvlc_media_player_set_time(p_mi, i_time):
5453 '''Set the movie time (in ms). This has no effect if no media is being played.
5454 Not all formats and protocols support this.
5455 @param p_mi: the Media Player.
5456 @param i_time: the movie time (in ms).
5457 '''
5458 f = _Cfunctions.get('libvlc_media_player_set_time', None) or \
5459 _Cfunction('libvlc_media_player_set_time', ((1,), (1,),), None,
5460 None, MediaPlayer, ctypes.c_longlong)
5461 return f(p_mi, i_time)
5462
5463def libvlc_media_player_get_position(p_mi):
5464 '''Get movie position as percentage between 0.0 and 1.0.
5465 @param p_mi: the Media Player.
5466 @return: movie position, or -1. in case of error.
5467 '''
5468 f = _Cfunctions.get('libvlc_media_player_get_position', None) or \
5469 _Cfunction('libvlc_media_player_get_position', ((1,),), None,
5470 ctypes.c_float, MediaPlayer)
5471 return f(p_mi)
5472
5473def libvlc_media_player_set_position(p_mi, f_pos):
5474 '''Set movie position as percentage between 0.0 and 1.0.
5475 This has no effect if playback is not enabled.
5476 This might not work depending on the underlying input format and protocol.
5477 @param p_mi: the Media Player.
5478 @param f_pos: the position.
5479 '''
5480 f = _Cfunctions.get('libvlc_media_player_set_position', None) or \
5481 _Cfunction('libvlc_media_player_set_position', ((1,), (1,),), None,
5482 None, MediaPlayer, ctypes.c_float)
5483 return f(p_mi, f_pos)
5484
5485def libvlc_media_player_set_chapter(p_mi, i_chapter):
5486 '''Set movie chapter (if applicable).
5487 @param p_mi: the Media Player.
5488 @param i_chapter: chapter number to play.
5489 '''
5490 f = _Cfunctions.get('libvlc_media_player_set_chapter', None) or \
5491 _Cfunction('libvlc_media_player_set_chapter', ((1,), (1,),), None,
5492 None, MediaPlayer, ctypes.c_int)
5493 return f(p_mi, i_chapter)
5494
5495def libvlc_media_player_get_chapter(p_mi):
5496 '''Get movie chapter.
5497 @param p_mi: the Media Player.
5498 @return: chapter number currently playing, or -1 if there is no media.
5499 '''
5500 f = _Cfunctions.get('libvlc_media_player_get_chapter', None) or \
5501 _Cfunction('libvlc_media_player_get_chapter', ((1,),), None,
5502 ctypes.c_int, MediaPlayer)
5503 return f(p_mi)
5504
5505def libvlc_media_player_get_chapter_count(p_mi):
5506 '''Get movie chapter count.
5507 @param p_mi: the Media Player.
5508 @return: number of chapters in movie, or -1.
5509 '''
5510 f = _Cfunctions.get('libvlc_media_player_get_chapter_count', None) or \
5511 _Cfunction('libvlc_media_player_get_chapter_count', ((1,),), None,
5512 ctypes.c_int, MediaPlayer)
5513 return f(p_mi)
5514
5515def libvlc_media_player_will_play(p_mi):
5516 '''Is the player able to play.
5517 @param p_mi: the Media Player.
5518 @return: boolean \libvlc_return_bool.
5519 '''
5520 f = _Cfunctions.get('libvlc_media_player_will_play', None) or \
5521 _Cfunction('libvlc_media_player_will_play', ((1,),), None,
5522 ctypes.c_int, MediaPlayer)
5523 return f(p_mi)
5524
5525def libvlc_media_player_get_chapter_count_for_title(p_mi, i_title):
5526 '''Get title chapter count.
5527 @param p_mi: the Media Player.
5528 @param i_title: title.
5529 @return: number of chapters in title, or -1.
5530 '''
5531 f = _Cfunctions.get('libvlc_media_player_get_chapter_count_for_title', None) or \
5532 _Cfunction('libvlc_media_player_get_chapter_count_for_title', ((1,), (1,),), None,
5533 ctypes.c_int, MediaPlayer, ctypes.c_int)
5534 return f(p_mi, i_title)
5535
5536def libvlc_media_player_set_title(p_mi, i_title):
5537 '''Set movie title.
5538 @param p_mi: the Media Player.
5539 @param i_title: title number to play.
5540 '''
5541 f = _Cfunctions.get('libvlc_media_player_set_title', None) or \
5542 _Cfunction('libvlc_media_player_set_title', ((1,), (1,),), None,
5543 None, MediaPlayer, ctypes.c_int)
5544 return f(p_mi, i_title)
5545
5546def libvlc_media_player_get_title(p_mi):
5547 '''Get movie title.
5548 @param p_mi: the Media Player.
5549 @return: title number currently playing, or -1.
5550 '''
5551 f = _Cfunctions.get('libvlc_media_player_get_title', None) or \
5552 _Cfunction('libvlc_media_player_get_title', ((1,),), None,
5553 ctypes.c_int, MediaPlayer)
5554 return f(p_mi)
5555
5556def libvlc_media_player_get_title_count(p_mi):
5557 '''Get movie title count.
5558 @param p_mi: the Media Player.
5559 @return: title number count, or -1.
5560 '''
5561 f = _Cfunctions.get('libvlc_media_player_get_title_count', None) or \
5562 _Cfunction('libvlc_media_player_get_title_count', ((1,),), None,
5563 ctypes.c_int, MediaPlayer)
5564 return f(p_mi)
5565
5566def libvlc_media_player_previous_chapter(p_mi):
5567 '''Set previous chapter (if applicable).
5568 @param p_mi: the Media Player.
5569 '''
5570 f = _Cfunctions.get('libvlc_media_player_previous_chapter', None) or \
5571 _Cfunction('libvlc_media_player_previous_chapter', ((1,),), None,
5572 None, MediaPlayer)
5573 return f(p_mi)
5574
5575def libvlc_media_player_next_chapter(p_mi):
5576 '''Set next chapter (if applicable).
5577 @param p_mi: the Media Player.
5578 '''
5579 f = _Cfunctions.get('libvlc_media_player_next_chapter', None) or \
5580 _Cfunction('libvlc_media_player_next_chapter', ((1,),), None,
5581 None, MediaPlayer)
5582 return f(p_mi)
5583
5584def libvlc_media_player_get_rate(p_mi):
5585 '''Get the requested movie play rate.
5586 @warning: Depending on the underlying media, the requested rate may be
5587 different from the real playback rate.
5588 @param p_mi: the Media Player.
5589 @return: movie play rate.
5590 '''
5591 f = _Cfunctions.get('libvlc_media_player_get_rate', None) or \
5592 _Cfunction('libvlc_media_player_get_rate', ((1,),), None,
5593 ctypes.c_float, MediaPlayer)
5594 return f(p_mi)
5595
5596def libvlc_media_player_set_rate(p_mi, rate):
5597 '''Set movie play rate.
5598 @param p_mi: the Media Player.
5599 @param rate: movie play rate to set.
5600 @return: -1 if an error was detected, 0 otherwise (but even then, it might not actually work depending on the underlying media protocol).
5601 '''
5602 f = _Cfunctions.get('libvlc_media_player_set_rate', None) or \
5603 _Cfunction('libvlc_media_player_set_rate', ((1,), (1,),), None,
5604 ctypes.c_int, MediaPlayer, ctypes.c_float)
5605 return f(p_mi, rate)
5606
5607def libvlc_media_player_get_state(p_mi):
5608 '''Get current movie state.
5609 @param p_mi: the Media Player.
5610 @return: the current state of the media player (playing, paused, ...) See libvlc_state_t.
5611 '''
5612 f = _Cfunctions.get('libvlc_media_player_get_state', None) or \
5613 _Cfunction('libvlc_media_player_get_state', ((1,),), None,
5614 State, MediaPlayer)
5615 return f(p_mi)
5616
5617def libvlc_media_player_get_fps(p_mi):
5618 '''Get movie fps rate.
5619 @param p_mi: the Media Player.
5620 @return: frames per second (fps) for this playing movie, or 0 if unspecified.
5621 '''
5622 f = _Cfunctions.get('libvlc_media_player_get_fps', None) or \
5623 _Cfunction('libvlc_media_player_get_fps', ((1,),), None,
5624 ctypes.c_float, MediaPlayer)
5625 return f(p_mi)
5626
5627def libvlc_media_player_has_vout(p_mi):
5628 '''How many video outputs does this media player have?
5629 @param p_mi: the media player.
5630 @return: the number of video outputs.
5631 '''
5632 f = _Cfunctions.get('libvlc_media_player_has_vout', None) or \
5633 _Cfunction('libvlc_media_player_has_vout', ((1,),), None,
5634 ctypes.c_uint, MediaPlayer)
5635 return f(p_mi)
5636
5637def libvlc_media_player_is_seekable(p_mi):
5638 '''Is this media player seekable?
5639 @param p_mi: the media player.
5640 @return: true if the media player can seek \libvlc_return_bool.
5641 '''
5642 f = _Cfunctions.get('libvlc_media_player_is_seekable', None) or \
5643 _Cfunction('libvlc_media_player_is_seekable', ((1,),), None,
5644 ctypes.c_int, MediaPlayer)
5645 return f(p_mi)
5646
5647def libvlc_media_player_can_pause(p_mi):
5648 '''Can this media player be paused?
5649 @param p_mi: the media player.
5650 @return: true if the media player can pause \libvlc_return_bool.
5651 '''
5652 f = _Cfunctions.get('libvlc_media_player_can_pause', None) or \
5653 _Cfunction('libvlc_media_player_can_pause', ((1,),), None,
5654 ctypes.c_int, MediaPlayer)
5655 return f(p_mi)
5656
5657def libvlc_media_player_program_scrambled(p_mi):
5658 '''Check if the current program is scrambled.
5659 @param p_mi: the media player.
5660 @return: true if the current program is scrambled \libvlc_return_bool.
5661 @version: LibVLC 2.2.0 or later.
5662 '''
5663 f = _Cfunctions.get('libvlc_media_player_program_scrambled', None) or \
5664 _Cfunction('libvlc_media_player_program_scrambled', ((1,),), None,
5665 ctypes.c_int, MediaPlayer)
5666 return f(p_mi)
5667
5668def libvlc_media_player_next_frame(p_mi):
5669 '''Display the next frame (if supported).
5670 @param p_mi: the media player.
5671 '''
5672 f = _Cfunctions.get('libvlc_media_player_next_frame', None) or \
5673 _Cfunction('libvlc_media_player_next_frame', ((1,),), None,
5674 None, MediaPlayer)
5675 return f(p_mi)
5676
5677def libvlc_media_player_navigate(p_mi, navigate):
5678 '''Navigate through DVD Menu.
5679 @param p_mi: the Media Player.
5680 @param navigate: the Navigation mode.
5681 @version: libVLC 2.0.0 or later.
5682 '''
5683 f = _Cfunctions.get('libvlc_media_player_navigate', None) or \
5684 _Cfunction('libvlc_media_player_navigate', ((1,), (1,),), None,
5685 None, MediaPlayer, ctypes.c_uint)
5686 return f(p_mi, navigate)
5687
5688def libvlc_media_player_set_video_title_display(p_mi, position, timeout):
5689 '''Set if, and how, the video title will be shown when media is played.
5690 @param p_mi: the media player.
5691 @param position: position at which to display the title, or libvlc_position_disable to prevent the title from being displayed.
5692 @param timeout: title display timeout in milliseconds (ignored if libvlc_position_disable).
5693 @version: libVLC 2.1.0 or later.
5694 '''
5695 f = _Cfunctions.get('libvlc_media_player_set_video_title_display', None) or \
5696 _Cfunction('libvlc_media_player_set_video_title_display', ((1,), (1,), (1,),), None,
5697 None, MediaPlayer, Position, ctypes.c_int)
5698 return f(p_mi, position, timeout)
5699
5700def libvlc_track_description_list_release(p_track_description):
5701 '''Release (free) L{TrackDescription}.
5702 @param p_track_description: the structure to release.
5703 '''
5704 f = _Cfunctions.get('libvlc_track_description_list_release', None) or \
5705 _Cfunction('libvlc_track_description_list_release', ((1,),), None,
5706 None, ctypes.POINTER(TrackDescription))
5707 return f(p_track_description)
5708
5709def libvlc_track_description_release(p_track_description):
5710 '''\deprecated Use L{libvlc_track_description_list_release} instead.
5711 '''
5712 f = _Cfunctions.get('libvlc_track_description_release', None) or \
5713 _Cfunction('libvlc_track_description_release', ((1,),), None,
5714 None, ctypes.POINTER(TrackDescription))
5715 return f(p_track_description)
5716
5717def libvlc_toggle_fullscreen(p_mi):
5718 '''Toggle fullscreen status on non-embedded video outputs.
5719 @warning: The same limitations applies to this function
5720 as to L{libvlc_set_fullscreen}().
5721 @param p_mi: the media player.
5722 '''
5723 f = _Cfunctions.get('libvlc_toggle_fullscreen', None) or \
5724 _Cfunction('libvlc_toggle_fullscreen', ((1,),), None,
5725 None, MediaPlayer)
5726 return f(p_mi)
5727
5728def libvlc_set_fullscreen(p_mi, b_fullscreen):
5729 '''Enable or disable fullscreen.
5730 @warning: With most window managers, only a top-level windows can be in
5731 full-screen mode. Hence, this function will not operate properly if
5732 L{libvlc_media_player_set_xwindow}() was used to embed the video in a
5733 non-top-level window. In that case, the embedding window must be reparented
5734 to the root window B{before} fullscreen mode is enabled. You will want
5735 to reparent it back to its normal parent when disabling fullscreen.
5736 @param p_mi: the media player.
5737 @param b_fullscreen: boolean for fullscreen status.
5738 '''
5739 f = _Cfunctions.get('libvlc_set_fullscreen', None) or \
5740 _Cfunction('libvlc_set_fullscreen', ((1,), (1,),), None,
5741 None, MediaPlayer, ctypes.c_int)
5742 return f(p_mi, b_fullscreen)
5743
5744def libvlc_get_fullscreen(p_mi):
5745 '''Get current fullscreen status.
5746 @param p_mi: the media player.
5747 @return: the fullscreen status (boolean) \libvlc_return_bool.
5748 '''
5749 f = _Cfunctions.get('libvlc_get_fullscreen', None) or \
5750 _Cfunction('libvlc_get_fullscreen', ((1,),), None,
5751 ctypes.c_int, MediaPlayer)
5752 return f(p_mi)
5753
5754def libvlc_video_set_key_input(p_mi, on):
5755 '''Enable or disable key press events handling, according to the LibVLC hotkeys
5756 configuration. By default and for historical reasons, keyboard events are
5757 handled by the LibVLC video widget.
5758 @note: On X11, there can be only one subscriber for key press and mouse
5759 click events per window. If your application has subscribed to those events
5760 for the X window ID of the video widget, then LibVLC will not be able to
5761 handle key presses and mouse clicks in any case.
5762 @warning: This function is only implemented for X11 and Win32 at the moment.
5763 @param p_mi: the media player.
5764 @param on: true to handle key press events, false to ignore them.
5765 '''
5766 f = _Cfunctions.get('libvlc_video_set_key_input', None) or \
5767 _Cfunction('libvlc_video_set_key_input', ((1,), (1,),), None,
5768 None, MediaPlayer, ctypes.c_uint)
5769 return f(p_mi, on)
5770
5771def libvlc_video_set_mouse_input(p_mi, on):
5772 '''Enable or disable mouse click events handling. By default, those events are
5773 handled. This is needed for DVD menus to work, as well as a few video
5774 filters such as "puzzle".
5775 See L{libvlc_video_set_key_input}().
5776 @warning: This function is only implemented for X11 and Win32 at the moment.
5777 @param p_mi: the media player.
5778 @param on: true to handle mouse click events, false to ignore them.
5779 '''
5780 f = _Cfunctions.get('libvlc_video_set_mouse_input', None) or \
5781 _Cfunction('libvlc_video_set_mouse_input', ((1,), (1,),), None,
5782 None, MediaPlayer, ctypes.c_uint)
5783 return f(p_mi, on)
5784
5785def libvlc_video_get_size(p_mi, num):
5786 '''Get the pixel dimensions of a video.
5787 @param p_mi: media player.
5788 @param num: number of the video (starting from, and most commonly 0).
5789 @return: px pixel width, py pixel height.
5790 '''
5791 f = _Cfunctions.get('libvlc_video_get_size', None) or \
5792 _Cfunction('libvlc_video_get_size', ((1,), (1,), (2,), (2,),), None,
5793 ctypes.c_int, MediaPlayer, ctypes.c_uint, ctypes.POINTER(ctypes.c_uint), ctypes.POINTER(ctypes.c_uint))
5794 return f(p_mi, num)
5795
5796def libvlc_video_get_height(p_mi):
5797 '''Get current video height.
5798 \deprecated Use L{libvlc_video_get_size}() instead.
5799 @param p_mi: the media player.
5800 @return: the video pixel height or 0 if not applicable.
5801 '''
5802 f = _Cfunctions.get('libvlc_video_get_height', None) or \
5803 _Cfunction('libvlc_video_get_height', ((1,),), None,
5804 ctypes.c_int, MediaPlayer)
5805 return f(p_mi)
5806
5807def libvlc_video_get_width(p_mi):
5808 '''Get current video width.
5809 \deprecated Use L{libvlc_video_get_size}() instead.
5810 @param p_mi: the media player.
5811 @return: the video pixel width or 0 if not applicable.
5812 '''
5813 f = _Cfunctions.get('libvlc_video_get_width', None) or \
5814 _Cfunction('libvlc_video_get_width', ((1,),), None,
5815 ctypes.c_int, MediaPlayer)
5816 return f(p_mi)
5817
5818def libvlc_video_get_cursor(p_mi, num):
5819 '''Get the mouse pointer coordinates over a video.
5820 Coordinates are expressed in terms of the decoded video resolution,
5821 B{not} in terms of pixels on the screen/viewport (to get the latter,
5822 you can query your windowing system directly).
5823 Either of the coordinates may be negative or larger than the corresponding
5824 dimension of the video, if the cursor is outside the rendering area.
5825 @warning: The coordinates may be out-of-date if the pointer is not located
5826 on the video rendering area. LibVLC does not track the pointer if it is
5827 outside of the video widget.
5828 @note: LibVLC does not support multiple pointers (it does of course support
5829 multiple input devices sharing the same pointer) at the moment.
5830 @param p_mi: media player.
5831 @param num: number of the video (starting from, and most commonly 0).
5832 @return: px abscissa, py ordinate.
5833 '''
5834 f = _Cfunctions.get('libvlc_video_get_cursor', None) or \
5835 _Cfunction('libvlc_video_get_cursor', ((1,), (1,), (2,), (2,),), None,
5836 ctypes.c_int, MediaPlayer, ctypes.c_uint, ctypes.POINTER(ctypes.c_int), ctypes.POINTER(ctypes.c_int))
5837 return f(p_mi, num)
5838
5839def libvlc_video_get_scale(p_mi):
5840 '''Get the current video scaling factor.
5841 See also L{libvlc_video_set_scale}().
5842 @param p_mi: the media player.
5843 @return: the currently configured zoom factor, or 0. if the video is set to fit to the output window/drawable automatically.
5844 '''
5845 f = _Cfunctions.get('libvlc_video_get_scale', None) or \
5846 _Cfunction('libvlc_video_get_scale', ((1,),), None,
5847 ctypes.c_float, MediaPlayer)
5848 return f(p_mi)
5849
5850def libvlc_video_set_scale(p_mi, f_factor):
5851 '''Set the video scaling factor. That is the ratio of the number of pixels on
5852 screen to the number of pixels in the original decoded video in each
5853 dimension. Zero is a special value; it will adjust the video to the output
5854 window/drawable (in windowed mode) or the entire screen.
5855 Note that not all video outputs support scaling.
5856 @param p_mi: the media player.
5857 @param f_factor: the scaling factor, or zero.
5858 '''
5859 f = _Cfunctions.get('libvlc_video_set_scale', None) or \
5860 _Cfunction('libvlc_video_set_scale', ((1,), (1,),), None,
5861 None, MediaPlayer, ctypes.c_float)
5862 return f(p_mi, f_factor)
5863
5864def libvlc_video_get_aspect_ratio(p_mi):
5865 '''Get current video aspect ratio.
5866 @param p_mi: the media player.
5867 @return: the video aspect ratio or None if unspecified (the result must be released with free() or L{libvlc_free}()).
5868 '''
5869 f = _Cfunctions.get('libvlc_video_get_aspect_ratio', None) or \
5870 _Cfunction('libvlc_video_get_aspect_ratio', ((1,),), string_result,
5871 ctypes.c_void_p, MediaPlayer)
5872 return f(p_mi)
5873
5874def libvlc_video_set_aspect_ratio(p_mi, psz_aspect):
5875 '''Set new video aspect ratio.
5876 @param p_mi: the media player.
5877 @param psz_aspect: new video aspect-ratio or None to reset to default @note Invalid aspect ratios are ignored.
5878 '''
5879 f = _Cfunctions.get('libvlc_video_set_aspect_ratio', None) or \
5880 _Cfunction('libvlc_video_set_aspect_ratio', ((1,), (1,),), None,
5881 None, MediaPlayer, ctypes.c_char_p)
5882 return f(p_mi, psz_aspect)
5883
5884def libvlc_video_get_spu(p_mi):
5885 '''Get current video subtitle.
5886 @param p_mi: the media player.
5887 @return: the video subtitle selected, or -1 if none.
5888 '''
5889 f = _Cfunctions.get('libvlc_video_get_spu', None) or \
5890 _Cfunction('libvlc_video_get_spu', ((1,),), None,
5891 ctypes.c_int, MediaPlayer)
5892 return f(p_mi)
5893
5894def libvlc_video_get_spu_count(p_mi):
5895 '''Get the number of available video subtitles.
5896 @param p_mi: the media player.
5897 @return: the number of available video subtitles.
5898 '''
5899 f = _Cfunctions.get('libvlc_video_get_spu_count', None) or \
5900 _Cfunction('libvlc_video_get_spu_count', ((1,),), None,
5901 ctypes.c_int, MediaPlayer)
5902 return f(p_mi)
5903
5904def libvlc_video_get_spu_description(p_mi):
5905 '''Get the description of available video subtitles.
5906 @param p_mi: the media player.
5907 @return: list containing description of available video subtitles.
5908 '''
5909 f = _Cfunctions.get('libvlc_video_get_spu_description', None) or \
5910 _Cfunction('libvlc_video_get_spu_description', ((1,),), None,
5911 ctypes.POINTER(TrackDescription), MediaPlayer)
5912 return f(p_mi)
5913
5914def libvlc_video_set_spu(p_mi, i_spu):
5915 '''Set new video subtitle.
5916 @param p_mi: the media player.
5917 @param i_spu: video subtitle track to select (i_id from track description).
5918 @return: 0 on success, -1 if out of range.
5919 '''
5920 f = _Cfunctions.get('libvlc_video_set_spu', None) or \
5921 _Cfunction('libvlc_video_set_spu', ((1,), (1,),), None,
5922 ctypes.c_int, MediaPlayer, ctypes.c_int)
5923 return f(p_mi, i_spu)
5924
5925def libvlc_video_set_subtitle_file(p_mi, psz_subtitle):
5926 '''Set new video subtitle file.
5927 @param p_mi: the media player.
5928 @param psz_subtitle: new video subtitle file.
5929 @return: the success status (boolean).
5930 '''
5931 f = _Cfunctions.get('libvlc_video_set_subtitle_file', None) or \
5932 _Cfunction('libvlc_video_set_subtitle_file', ((1,), (1,),), None,
5933 ctypes.c_int, MediaPlayer, ctypes.c_char_p)
5934 return f(p_mi, psz_subtitle)
5935
5936def libvlc_video_get_spu_delay(p_mi):
5937 '''Get the current subtitle delay. Positive values means subtitles are being
5938 displayed later, negative values earlier.
5939 @param p_mi: media player.
5940 @return: time (in microseconds) the display of subtitles is being delayed.
5941 @version: LibVLC 2.0.0 or later.
5942 '''
5943 f = _Cfunctions.get('libvlc_video_get_spu_delay', None) or \
5944 _Cfunction('libvlc_video_get_spu_delay', ((1,),), None,
5945 ctypes.c_int64, MediaPlayer)
5946 return f(p_mi)
5947
5948def libvlc_video_set_spu_delay(p_mi, i_delay):
5949 '''Set the subtitle delay. This affects the timing of when the subtitle will
5950 be displayed. Positive values result in subtitles being displayed later,
5951 while negative values will result in subtitles being displayed earlier.
5952 The subtitle delay will be reset to zero each time the media changes.
5953 @param p_mi: media player.
5954 @param i_delay: time (in microseconds) the display of subtitles should be delayed.
5955 @return: 0 on success, -1 on error.
5956 @version: LibVLC 2.0.0 or later.
5957 '''
5958 f = _Cfunctions.get('libvlc_video_set_spu_delay', None) or \
5959 _Cfunction('libvlc_video_set_spu_delay', ((1,), (1,),), None,
5960 ctypes.c_int, MediaPlayer, ctypes.c_int64)
5961 return f(p_mi, i_delay)
5962
5963def libvlc_video_get_title_description(p_mi):
5964 '''Get the description of available titles.
5965 @param p_mi: the media player.
5966 @return: list containing description of available titles.
5967 '''
5968 f = _Cfunctions.get('libvlc_video_get_title_description', None) or \
5969 _Cfunction('libvlc_video_get_title_description', ((1,),), None,
5970 ctypes.POINTER(TrackDescription), MediaPlayer)
5971 return f(p_mi)
5972
5973def libvlc_video_get_chapter_description(p_mi, i_title):
5974 '''Get the description of available chapters for specific title.
5975 @param p_mi: the media player.
5976 @param i_title: selected title.
5977 @return: list containing description of available chapter for title i_title.
5978 '''
5979 f = _Cfunctions.get('libvlc_video_get_chapter_description', None) or \
5980 _Cfunction('libvlc_video_get_chapter_description', ((1,), (1,),), None,
5981 ctypes.POINTER(TrackDescription), MediaPlayer, ctypes.c_int)
5982 return f(p_mi, i_title)
5983
5984def libvlc_video_get_crop_geometry(p_mi):
5985 '''Get current crop filter geometry.
5986 @param p_mi: the media player.
5987 @return: the crop filter geometry or None if unset.
5988 '''
5989 f = _Cfunctions.get('libvlc_video_get_crop_geometry', None) or \
5990 _Cfunction('libvlc_video_get_crop_geometry', ((1,),), string_result,
5991 ctypes.c_void_p, MediaPlayer)
5992 return f(p_mi)
5993
5994def libvlc_video_set_crop_geometry(p_mi, psz_geometry):
5995 '''Set new crop filter geometry.
5996 @param p_mi: the media player.
5997 @param psz_geometry: new crop filter geometry (None to unset).
5998 '''
5999 f = _Cfunctions.get('libvlc_video_set_crop_geometry', None) or \
6000 _Cfunction('libvlc_video_set_crop_geometry', ((1,), (1,),), None,
6001 None, MediaPlayer, ctypes.c_char_p)
6002 return f(p_mi, psz_geometry)
6003
6004def libvlc_video_get_teletext(p_mi):
6005 '''Get current teletext page requested.
6006 @param p_mi: the media player.
6007 @return: the current teletext page requested.
6008 '''
6009 f = _Cfunctions.get('libvlc_video_get_teletext', None) or \
6010 _Cfunction('libvlc_video_get_teletext', ((1,),), None,
6011 ctypes.c_int, MediaPlayer)
6012 return f(p_mi)
6013
6014def libvlc_video_set_teletext(p_mi, i_page):
6015 '''Set new teletext page to retrieve.
6016 @param p_mi: the media player.
6017 @param i_page: teletex page number requested.
6018 '''
6019 f = _Cfunctions.get('libvlc_video_set_teletext', None) or \
6020 _Cfunction('libvlc_video_set_teletext', ((1,), (1,),), None,
6021 None, MediaPlayer, ctypes.c_int)
6022 return f(p_mi, i_page)
6023
6024def libvlc_toggle_teletext(p_mi):
6025 '''Toggle teletext transparent status on video output.
6026 @param p_mi: the media player.
6027 '''
6028 f = _Cfunctions.get('libvlc_toggle_teletext', None) or \
6029 _Cfunction('libvlc_toggle_teletext', ((1,),), None,
6030 None, MediaPlayer)
6031 return f(p_mi)
6032
6033def libvlc_video_get_track_count(p_mi):
6034 '''Get number of available video tracks.
6035 @param p_mi: media player.
6036 @return: the number of available video tracks (int).
6037 '''
6038 f = _Cfunctions.get('libvlc_video_get_track_count', None) or \
6039 _Cfunction('libvlc_video_get_track_count', ((1,),), None,
6040 ctypes.c_int, MediaPlayer)
6041 return f(p_mi)
6042
6043def libvlc_video_get_track_description(p_mi):
6044 '''Get the description of available video tracks.
6045 @param p_mi: media player.
6046 @return: list with description of available video tracks, or None on error.
6047 '''
6048 f = _Cfunctions.get('libvlc_video_get_track_description', None) or \
6049 _Cfunction('libvlc_video_get_track_description', ((1,),), None,
6050 ctypes.POINTER(TrackDescription), MediaPlayer)
6051 return f(p_mi)
6052
6053def libvlc_video_get_track(p_mi):
6054 '''Get current video track.
6055 @param p_mi: media player.
6056 @return: the video track ID (int) or -1 if no active input.
6057 '''
6058 f = _Cfunctions.get('libvlc_video_get_track', None) or \
6059 _Cfunction('libvlc_video_get_track', ((1,),), None,
6060 ctypes.c_int, MediaPlayer)
6061 return f(p_mi)
6062
6063def libvlc_video_set_track(p_mi, i_track):
6064 '''Set video track.
6065 @param p_mi: media player.
6066 @param i_track: the track ID (i_id field from track description).
6067 @return: 0 on success, -1 if out of range.
6068 '''
6069 f = _Cfunctions.get('libvlc_video_set_track', None) or \
6070 _Cfunction('libvlc_video_set_track', ((1,), (1,),), None,
6071 ctypes.c_int, MediaPlayer, ctypes.c_int)
6072 return f(p_mi, i_track)
6073
6074def libvlc_video_take_snapshot(p_mi, num, psz_filepath, i_width, i_height):
6075 '''Take a snapshot of the current video window.
6076 If i_width AND i_height is 0, original size is used.
6077 If i_width XOR i_height is 0, original aspect-ratio is preserved.
6078 @param p_mi: media player instance.
6079 @param num: number of video output (typically 0 for the first/only one).
6080 @param psz_filepath: the path where to save the screenshot to.
6081 @param i_width: the snapshot's width.
6082 @param i_height: the snapshot's height.
6083 @return: 0 on success, -1 if the video was not found.
6084 '''
6085 f = _Cfunctions.get('libvlc_video_take_snapshot', None) or \
6086 _Cfunction('libvlc_video_take_snapshot', ((1,), (1,), (1,), (1,), (1,),), None,
6087 ctypes.c_int, MediaPlayer, ctypes.c_uint, ctypes.c_char_p, ctypes.c_int, ctypes.c_int)
6088 return f(p_mi, num, psz_filepath, i_width, i_height)
6089
6090def libvlc_video_set_deinterlace(p_mi, psz_mode):
6091 '''Enable or disable deinterlace filter.
6092 @param p_mi: libvlc media player.
6093 @param psz_mode: type of deinterlace filter, None to disable.
6094 '''
6095 f = _Cfunctions.get('libvlc_video_set_deinterlace', None) or \
6096 _Cfunction('libvlc_video_set_deinterlace', ((1,), (1,),), None,
6097 None, MediaPlayer, ctypes.c_char_p)
6098 return f(p_mi, psz_mode)
6099
6100def libvlc_video_get_marquee_int(p_mi, option):
6101 '''Get an integer marquee option value.
6102 @param p_mi: libvlc media player.
6103 @param option: marq option to get See libvlc_video_marquee_int_option_t.
6104 '''
6105 f = _Cfunctions.get('libvlc_video_get_marquee_int', None) or \
6106 _Cfunction('libvlc_video_get_marquee_int', ((1,), (1,),), None,
6107 ctypes.c_int, MediaPlayer, ctypes.c_uint)
6108 return f(p_mi, option)
6109
6110def libvlc_video_get_marquee_string(p_mi, option):
6111 '''Get a string marquee option value.
6112 @param p_mi: libvlc media player.
6113 @param option: marq option to get See libvlc_video_marquee_string_option_t.
6114 '''
6115 f = _Cfunctions.get('libvlc_video_get_marquee_string', None) or \
6116 _Cfunction('libvlc_video_get_marquee_string', ((1,), (1,),), string_result,
6117 ctypes.c_void_p, MediaPlayer, ctypes.c_uint)
6118 return f(p_mi, option)
6119
6120def libvlc_video_set_marquee_int(p_mi, option, i_val):
6121 '''Enable, disable or set an integer marquee option
6122 Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
6123 or disabling (arg 0) the marq filter.
6124 @param p_mi: libvlc media player.
6125 @param option: marq option to set See libvlc_video_marquee_int_option_t.
6126 @param i_val: marq option value.
6127 '''
6128 f = _Cfunctions.get('libvlc_video_set_marquee_int', None) or \
6129 _Cfunction('libvlc_video_set_marquee_int', ((1,), (1,), (1,),), None,
6130 None, MediaPlayer, ctypes.c_uint, ctypes.c_int)
6131 return f(p_mi, option, i_val)
6132
6133def libvlc_video_set_marquee_string(p_mi, option, psz_text):
6134 '''Set a marquee string option.
6135 @param p_mi: libvlc media player.
6136 @param option: marq option to set See libvlc_video_marquee_string_option_t.
6137 @param psz_text: marq option value.
6138 '''
6139 f = _Cfunctions.get('libvlc_video_set_marquee_string', None) or \
6140 _Cfunction('libvlc_video_set_marquee_string', ((1,), (1,), (1,),), None,
6141 None, MediaPlayer, ctypes.c_uint, ctypes.c_char_p)
6142 return f(p_mi, option, psz_text)
6143
6144def libvlc_video_get_logo_int(p_mi, option):
6145 '''Get integer logo option.
6146 @param p_mi: libvlc media player instance.
6147 @param option: logo option to get, values of libvlc_video_logo_option_t.
6148 '''
6149 f = _Cfunctions.get('libvlc_video_get_logo_int', None) or \
6150 _Cfunction('libvlc_video_get_logo_int', ((1,), (1,),), None,
6151 ctypes.c_int, MediaPlayer, ctypes.c_uint)
6152 return f(p_mi, option)
6153
6154def libvlc_video_set_logo_int(p_mi, option, value):
6155 '''Set logo option as integer. Options that take a different type value
6156 are ignored.
6157 Passing libvlc_logo_enable as option value has the side effect of
6158 starting (arg !0) or stopping (arg 0) the logo filter.
6159 @param p_mi: libvlc media player instance.
6160 @param option: logo option to set, values of libvlc_video_logo_option_t.
6161 @param value: logo option value.
6162 '''
6163 f = _Cfunctions.get('libvlc_video_set_logo_int', None) or \
6164 _Cfunction('libvlc_video_set_logo_int', ((1,), (1,), (1,),), None,
6165 None, MediaPlayer, ctypes.c_uint, ctypes.c_int)
6166 return f(p_mi, option, value)
6167
6168def libvlc_video_set_logo_string(p_mi, option, psz_value):
6169 '''Set logo option as string. Options that take a different type value
6170 are ignored.
6171 @param p_mi: libvlc media player instance.
6172 @param option: logo option to set, values of libvlc_video_logo_option_t.
6173 @param psz_value: logo option value.
6174 '''
6175 f = _Cfunctions.get('libvlc_video_set_logo_string', None) or \
6176 _Cfunction('libvlc_video_set_logo_string', ((1,), (1,), (1,),), None,
6177 None, MediaPlayer, ctypes.c_uint, ctypes.c_char_p)
6178 return f(p_mi, option, psz_value)
6179
6180def libvlc_video_get_adjust_int(p_mi, option):
6181 '''Get integer adjust option.
6182 @param p_mi: libvlc media player instance.
6183 @param option: adjust option to get, values of libvlc_video_adjust_option_t.
6184 @version: LibVLC 1.1.1 and later.
6185 '''
6186 f = _Cfunctions.get('libvlc_video_get_adjust_int', None) or \
6187 _Cfunction('libvlc_video_get_adjust_int', ((1,), (1,),), None,
6188 ctypes.c_int, MediaPlayer, ctypes.c_uint)
6189 return f(p_mi, option)
6190
6191def libvlc_video_set_adjust_int(p_mi, option, value):
6192 '''Set adjust option as integer. Options that take a different type value
6193 are ignored.
6194 Passing libvlc_adjust_enable as option value has the side effect of
6195 starting (arg !0) or stopping (arg 0) the adjust filter.
6196 @param p_mi: libvlc media player instance.
6197 @param option: adust option to set, values of libvlc_video_adjust_option_t.
6198 @param value: adjust option value.
6199 @version: LibVLC 1.1.1 and later.
6200 '''
6201 f = _Cfunctions.get('libvlc_video_set_adjust_int', None) or \
6202 _Cfunction('libvlc_video_set_adjust_int', ((1,), (1,), (1,),), None,
6203 None, MediaPlayer, ctypes.c_uint, ctypes.c_int)
6204 return f(p_mi, option, value)
6205
6206def libvlc_video_get_adjust_float(p_mi, option):
6207 '''Get float adjust option.
6208 @param p_mi: libvlc media player instance.
6209 @param option: adjust option to get, values of libvlc_video_adjust_option_t.
6210 @version: LibVLC 1.1.1 and later.
6211 '''
6212 f = _Cfunctions.get('libvlc_video_get_adjust_float', None) or \
6213 _Cfunction('libvlc_video_get_adjust_float', ((1,), (1,),), None,
6214 ctypes.c_float, MediaPlayer, ctypes.c_uint)
6215 return f(p_mi, option)
6216
6217def libvlc_video_set_adjust_float(p_mi, option, value):
6218 '''Set adjust option as float. Options that take a different type value
6219 are ignored.
6220 @param p_mi: libvlc media player instance.
6221 @param option: adust option to set, values of libvlc_video_adjust_option_t.
6222 @param value: adjust option value.
6223 @version: LibVLC 1.1.1 and later.
6224 '''
6225 f = _Cfunctions.get('libvlc_video_set_adjust_float', None) or \
6226 _Cfunction('libvlc_video_set_adjust_float', ((1,), (1,), (1,),), None,
6227 None, MediaPlayer, ctypes.c_uint, ctypes.c_float)
6228 return f(p_mi, option, value)
6229
6230def libvlc_audio_output_list_get(p_instance):
6231 '''Gets the list of available audio output modules.
6232 @param p_instance: libvlc instance.
6233 @return: list of available audio outputs. It must be freed it with In case of error, None is returned.
6234 '''
6235 f = _Cfunctions.get('libvlc_audio_output_list_get', None) or \
6236 _Cfunction('libvlc_audio_output_list_get', ((1,),), None,
6237 ctypes.POINTER(AudioOutput), Instance)
6238 return f(p_instance)
6239
6240def libvlc_audio_output_list_release(p_list):
6241 '''Frees the list of available audio output modules.
6242 @param p_list: list with audio outputs for release.
6243 '''
6244 f = _Cfunctions.get('libvlc_audio_output_list_release', None) or \
6245 _Cfunction('libvlc_audio_output_list_release', ((1,),), None,
6246 None, ctypes.POINTER(AudioOutput))
6247 return f(p_list)
6248
6249def libvlc_audio_output_set(p_mi, psz_name):
6250 '''Selects an audio output module.
6251 @note: Any change will take be effect only after playback is stopped and
6252 restarted. Audio output cannot be changed while playing.
6253 @param p_mi: media player.
6254 @param psz_name: name of audio output, use psz_name of See L{AudioOutput}.
6255 @return: 0 if function succeded, -1 on error.
6256 '''
6257 f = _Cfunctions.get('libvlc_audio_output_set', None) or \
6258 _Cfunction('libvlc_audio_output_set', ((1,), (1,),), None,
6259 ctypes.c_int, MediaPlayer, ctypes.c_char_p)
6260 return f(p_mi, psz_name)
6261
6262def libvlc_audio_output_device_count(p_instance, psz_name):
6263 '''Backward compatibility stub. Do not use in new code.
6264 Use L{libvlc_audio_output_device_list_get}() instead.
6265 @param p_instance: vlc instance.
6266 @param psz_name: name.
6267 @return: always 0.
6268 '''
6269 f = _Cfunctions.get('libvlc_audio_output_device_count', None) or \
6270 _Cfunction('libvlc_audio_output_device_count', ((1,), (1,),), None,
6271 ctypes.c_int, Instance, ctypes.c_char_p)
6272 return f(p_instance, psz_name)
6273
6274def libvlc_audio_output_device_longname(p_instance, psz_name, int):
6275 '''Backward compatibility stub. Do not use in new code.
6276 Use L{libvlc_audio_output_device_list_get}() instead.
6277 @param p_instance: vlc instance.
6278 @param psz_name: name.
6279 @param int: index.
6280 @return: always None.
6281 '''
6282 f = _Cfunctions.get('libvlc_audio_output_device_longname', None) or \
6283 _Cfunction('libvlc_audio_output_device_longname', ((1,), (1,), (1,),), string_result,
6284 ctypes.c_void_p, Instance, ctypes.c_char_p, ctypes.c_int)
6285 return f(p_instance, psz_name, int)
6286
6287def libvlc_audio_output_device_id(p_instance, psz_name, int):
6288 '''Backward compatibility stub. Do not use in new code.
6289 Use L{libvlc_audio_output_device_list_get}() instead.
6290 @param p_instance: vlc instance.
6291 @param psz_name: name.
6292 @param int: index.
6293 @return: always None.
6294 '''
6295 f = _Cfunctions.get('libvlc_audio_output_device_id', None) or \
6296 _Cfunction('libvlc_audio_output_device_id', ((1,), (1,), (1,),), string_result,
6297 ctypes.c_void_p, Instance, ctypes.c_char_p, ctypes.c_int)
6298 return f(p_instance, psz_name, int)
6299
6300def libvlc_audio_output_device_enum(mp):
6301 '''Gets a list of potential audio output devices,
6302 See L{libvlc_audio_output_device_set}().
6303 @note: Not all audio outputs support enumerating devices.
6304 The audio output may be functional even if the list is empty (None).
6305 @note: The list may not be exhaustive.
6306 @warning: Some audio output devices in the list might not actually work in
6307 some circumstances. By default, it is recommended to not specify any
6308 explicit audio device.
6309 @param mp: media player.
6310 @return: A None-terminated linked list of potential audio output devices. It must be freed it with L{libvlc_audio_output_device_list_release}().
6311 @version: LibVLC 2.2.0 or later.
6312 '''
6313 f = _Cfunctions.get('libvlc_audio_output_device_enum', None) or \
6314 _Cfunction('libvlc_audio_output_device_enum', ((1,),), None,
6315 ctypes.POINTER(AudioOutputDevice), MediaPlayer)
6316 return f(mp)
6317
6318def libvlc_audio_output_device_list_get(p_instance, aout):
6319 '''Gets a list of audio output devices for a given audio output module,
6320 See L{libvlc_audio_output_device_set}().
6321 @note: Not all audio outputs support this. In particular, an empty (None)
6322 list of devices does B{not} imply that the specified audio output does
6323 not work.
6324 @note: The list might not be exhaustive.
6325 @warning: Some audio output devices in the list might not actually work in
6326 some circumstances. By default, it is recommended to not specify any
6327 explicit audio device.
6328 @param p_instance: libvlc instance.
6329 @param psz_aout: audio output name (as returned by L{libvlc_audio_output_list_get}()).
6330 @return: A None-terminated linked list of potential audio output devices. It must be freed it with L{libvlc_audio_output_device_list_release}().
6331 @version: LibVLC 2.1.0 or later.
6332 '''
6333 f = _Cfunctions.get('libvlc_audio_output_device_list_get', None) or \
6334 _Cfunction('libvlc_audio_output_device_list_get', ((1,), (1,),), None,
6335 ctypes.POINTER(AudioOutputDevice), Instance, ctypes.c_char_p)
6336 return f(p_instance, aout)
6337
6338def libvlc_audio_output_device_list_release(p_list):
6339 '''Frees a list of available audio output devices.
6340 @param p_list: list with audio outputs for release.
6341 @version: LibVLC 2.1.0 or later.
6342 '''
6343 f = _Cfunctions.get('libvlc_audio_output_device_list_release', None) or \
6344 _Cfunction('libvlc_audio_output_device_list_release', ((1,),), None,
6345 None, ctypes.POINTER(AudioOutputDevice))
6346 return f(p_list)
6347
6348def libvlc_audio_output_device_set(mp, module, device_id):
6349 '''Configures an explicit audio output device.
6350 If the module paramater is None, audio output will be moved to the device
6351 specified by the device identifier string immediately. This is the
6352 recommended usage.
6353 A list of adequate potential device strings can be obtained with
6354 L{libvlc_audio_output_device_enum}().
6355 However passing None is supported in LibVLC version 2.2.0 and later only;
6356 in earlier versions, this function would have no effects when the module
6357 parameter was None.
6358 If the module parameter is not None, the device parameter of the
6359 corresponding audio output, if it exists, will be set to the specified
6360 string. Note that some audio output modules do not have such a parameter
6361 (notably MMDevice and PulseAudio).
6362 A list of adequate potential device strings can be obtained with
6363 L{libvlc_audio_output_device_list_get}().
6364 @note: This function does not select the specified audio output plugin.
6365 L{libvlc_audio_output_set}() is used for that purpose.
6366 @warning: The syntax for the device parameter depends on the audio output.
6367 Some audio output modules require further parameters (e.g. a channels map
6368 in the case of ALSA).
6369 @param mp: media player.
6370 @param module: If None, current audio output module. if non-None, name of audio output module.
6371 @param device_id: device identifier string.
6372 @return: Nothing. Errors are ignored (this is a design bug).
6373 '''
6374 f = _Cfunctions.get('libvlc_audio_output_device_set', None) or \
6375 _Cfunction('libvlc_audio_output_device_set', ((1,), (1,), (1,),), None,
6376 None, MediaPlayer, ctypes.c_char_p, ctypes.c_char_p)
6377 return f(mp, module, device_id)
6378
6379def libvlc_audio_toggle_mute(p_mi):
6380 '''Toggle mute status.
6381 @param p_mi: media player @warning Toggling mute atomically is not always possible: On some platforms, other processes can mute the VLC audio playback stream asynchronously. Thus, there is a small race condition where toggling will not work. See also the limitations of L{libvlc_audio_set_mute}().
6382 '''
6383 f = _Cfunctions.get('libvlc_audio_toggle_mute', None) or \
6384 _Cfunction('libvlc_audio_toggle_mute', ((1,),), None,
6385 None, MediaPlayer)
6386 return f(p_mi)
6387
6388def libvlc_audio_get_mute(p_mi):
6389 '''Get current mute status.
6390 @param p_mi: media player.
6391 @return: the mute status (boolean) if defined, -1 if undefined/unapplicable.
6392 '''
6393 f = _Cfunctions.get('libvlc_audio_get_mute', None) or \
6394 _Cfunction('libvlc_audio_get_mute', ((1,),), None,
6395 ctypes.c_int, MediaPlayer)
6396 return f(p_mi)
6397
6398def libvlc_audio_set_mute(p_mi, status):
6399 '''Set mute status.
6400 @param p_mi: media player.
6401 @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.
6402 '''
6403 f = _Cfunctions.get('libvlc_audio_set_mute', None) or \
6404 _Cfunction('libvlc_audio_set_mute', ((1,), (1,),), None,
6405 None, MediaPlayer, ctypes.c_int)
6406 return f(p_mi, status)
6407
6408def libvlc_audio_get_volume(p_mi):
6409 '''Get current software audio volume.
6410 @param p_mi: media player.
6411 @return: the software volume in percents (0 = mute, 100 = nominal / 0dB).
6412 '''
6413 f = _Cfunctions.get('libvlc_audio_get_volume', None) or \
6414 _Cfunction('libvlc_audio_get_volume', ((1,),), None,
6415 ctypes.c_int, MediaPlayer)
6416 return f(p_mi)
6417
6418def libvlc_audio_set_volume(p_mi, i_volume):
6419 '''Set current software audio volume.
6420 @param p_mi: media player.
6421 @param i_volume: the volume in percents (0 = mute, 100 = 0dB).
6422 @return: 0 if the volume was set, -1 if it was out of range.
6423 '''
6424 f = _Cfunctions.get('libvlc_audio_set_volume', None) or \
6425 _Cfunction('libvlc_audio_set_volume', ((1,), (1,),), None,
6426 ctypes.c_int, MediaPlayer, ctypes.c_int)
6427 return f(p_mi, i_volume)
6428
6429def libvlc_audio_get_track_count(p_mi):
6430 '''Get number of available audio tracks.
6431 @param p_mi: media player.
6432 @return: the number of available audio tracks (int), or -1 if unavailable.
6433 '''
6434 f = _Cfunctions.get('libvlc_audio_get_track_count', None) or \
6435 _Cfunction('libvlc_audio_get_track_count', ((1,),), None,
6436 ctypes.c_int, MediaPlayer)
6437 return f(p_mi)
6438
6439def libvlc_audio_get_track_description(p_mi):
6440 '''Get the description of available audio tracks.
6441 @param p_mi: media player.
6442 @return: list with description of available audio tracks, or None.
6443 '''
6444 f = _Cfunctions.get('libvlc_audio_get_track_description', None) or \
6445 _Cfunction('libvlc_audio_get_track_description', ((1,),), None,
6446 ctypes.POINTER(TrackDescription), MediaPlayer)
6447 return f(p_mi)
6448
6449def libvlc_audio_get_track(p_mi):
6450 '''Get current audio track.
6451 @param p_mi: media player.
6452 @return: the audio track ID or -1 if no active input.
6453 '''
6454 f = _Cfunctions.get('libvlc_audio_get_track', None) or \
6455 _Cfunction('libvlc_audio_get_track', ((1,),), None,
6456 ctypes.c_int, MediaPlayer)
6457 return f(p_mi)
6458
6459def libvlc_audio_set_track(p_mi, i_track):
6460 '''Set current audio track.
6461 @param p_mi: media player.
6462 @param i_track: the track ID (i_id field from track description).
6463 @return: 0 on success, -1 on error.
6464 '''
6465 f = _Cfunctions.get('libvlc_audio_set_track', None) or \
6466 _Cfunction('libvlc_audio_set_track', ((1,), (1,),), None,
6467 ctypes.c_int, MediaPlayer, ctypes.c_int)
6468 return f(p_mi, i_track)
6469
6470def libvlc_audio_get_channel(p_mi):
6471 '''Get current audio channel.
6472 @param p_mi: media player.
6473 @return: the audio channel See libvlc_audio_output_channel_t.
6474 '''
6475 f = _Cfunctions.get('libvlc_audio_get_channel', None) or \
6476 _Cfunction('libvlc_audio_get_channel', ((1,),), None,
6477 ctypes.c_int, MediaPlayer)
6478 return f(p_mi)
6479
6480def libvlc_audio_set_channel(p_mi, channel):
6481 '''Set current audio channel.
6482 @param p_mi: media player.
6483 @param channel: the audio channel, See libvlc_audio_output_channel_t.
6484 @return: 0 on success, -1 on error.
6485 '''
6486 f = _Cfunctions.get('libvlc_audio_set_channel', None) or \
6487 _Cfunction('libvlc_audio_set_channel', ((1,), (1,),), None,
6488 ctypes.c_int, MediaPlayer, ctypes.c_int)
6489 return f(p_mi, channel)
6490
6491def libvlc_audio_get_delay(p_mi):
6492 '''Get current audio delay.
6493 @param p_mi: media player.
6494 @return: the audio delay (microseconds).
6495 @version: LibVLC 1.1.1 or later.
6496 '''
6497 f = _Cfunctions.get('libvlc_audio_get_delay', None) or \
6498 _Cfunction('libvlc_audio_get_delay', ((1,),), None,
6499 ctypes.c_int64, MediaPlayer)
6500 return f(p_mi)
6501
6502def libvlc_audio_set_delay(p_mi, i_delay):
6503 '''Set current audio delay. The audio delay will be reset to zero each time the media changes.
6504 @param p_mi: media player.
6505 @param i_delay: the audio delay (microseconds).
6506 @return: 0 on success, -1 on error.
6507 @version: LibVLC 1.1.1 or later.
6508 '''
6509 f = _Cfunctions.get('libvlc_audio_set_delay', None) or \
6510 _Cfunction('libvlc_audio_set_delay', ((1,), (1,),), None,
6511 ctypes.c_int, MediaPlayer, ctypes.c_int64)
6512 return f(p_mi, i_delay)
6513
6514def libvlc_audio_equalizer_get_preset_count():
6515 '''Get the number of equalizer presets.
6516 @return: number of presets.
6517 @version: LibVLC 2.2.0 or later.
6518 '''
6519 f = _Cfunctions.get('libvlc_audio_equalizer_get_preset_count', None) or \
6520 _Cfunction('libvlc_audio_equalizer_get_preset_count', (), None,
6521 ctypes.c_uint)
6522 return f()
6523
6524def libvlc_audio_equalizer_get_preset_name(u_index):
6525 '''Get the name of a particular equalizer preset.
6526 This name can be used, for example, to prepare a preset label or menu in a user
6527 interface.
6528 @param u_index: index of the preset, counting from zero.
6529 @return: preset name, or None if there is no such preset.
6530 @version: LibVLC 2.2.0 or later.
6531 '''
6532 f = _Cfunctions.get('libvlc_audio_equalizer_get_preset_name', None) or \
6533 _Cfunction('libvlc_audio_equalizer_get_preset_name', ((1,),), None,
6534 ctypes.c_char_p, ctypes.c_uint)
6535 return f(u_index)
6536
6537def libvlc_audio_equalizer_get_band_count():
6538 '''Get the number of distinct frequency bands for an equalizer.
6539 @return: number of frequency bands.
6540 @version: LibVLC 2.2.0 or later.
6541 '''
6542 f = _Cfunctions.get('libvlc_audio_equalizer_get_band_count', None) or \
6543 _Cfunction('libvlc_audio_equalizer_get_band_count', (), None,
6544 ctypes.c_uint)
6545 return f()
6546
6547def libvlc_audio_equalizer_get_band_frequency(u_index):
6548 '''Get a particular equalizer band frequency.
6549 This value can be used, for example, to create a label for an equalizer band control
6550 in a user interface.
6551 @param u_index: index of the band, counting from zero.
6552 @return: equalizer band frequency (Hz), or -1 if there is no such band.
6553 @version: LibVLC 2.2.0 or later.
6554 '''
6555 f = _Cfunctions.get('libvlc_audio_equalizer_get_band_frequency', None) or \
6556 _Cfunction('libvlc_audio_equalizer_get_band_frequency', ((1,),), None,
6557 ctypes.c_float, ctypes.c_uint)
6558 return f(u_index)
6559
6560def libvlc_audio_equalizer_new():
6561 '''Create a new default equalizer, with all frequency values zeroed.
6562 The new equalizer can subsequently be applied to a media player by invoking
6563 L{libvlc_media_player_set_equalizer}().
6564 The returned handle should be freed via L{libvlc_audio_equalizer_release}() when
6565 it is no longer needed.
6566 @return: opaque equalizer handle, or None on error.
6567 @version: LibVLC 2.2.0 or later.
6568 '''
6569 f = _Cfunctions.get('libvlc_audio_equalizer_new', None) or \
6570 _Cfunction('libvlc_audio_equalizer_new', (), None,
6571 ctypes.c_void_p)
6572 return f()
6573
6574def libvlc_audio_equalizer_new_from_preset(u_index):
6575 '''Create a new equalizer, with initial frequency values copied from an existing
6576 preset.
6577 The new equalizer can subsequently be applied to a media player by invoking
6578 L{libvlc_media_player_set_equalizer}().
6579 The returned handle should be freed via L{libvlc_audio_equalizer_release}() when
6580 it is no longer needed.
6581 @param u_index: index of the preset, counting from zero.
6582 @return: opaque equalizer handle, or None on error.
6583 @version: LibVLC 2.2.0 or later.
6584 '''
6585 f = _Cfunctions.get('libvlc_audio_equalizer_new_from_preset', None) or \
6586 _Cfunction('libvlc_audio_equalizer_new_from_preset', ((1,),), None,
6587 ctypes.c_void_p, ctypes.c_uint)
6588 return f(u_index)
6589
6590def libvlc_audio_equalizer_release(p_equalizer):
6591 '''Release a previously created equalizer instance.
6592 The equalizer was previously created by using L{libvlc_audio_equalizer_new}() or
6593 L{libvlc_audio_equalizer_new_from_preset}().
6594 It is safe to invoke this method with a None p_equalizer parameter for no effect.
6595 @param p_equalizer: opaque equalizer handle, or None.
6596 @version: LibVLC 2.2.0 or later.
6597 '''
6598 f = _Cfunctions.get('libvlc_audio_equalizer_release', None) or \
6599 _Cfunction('libvlc_audio_equalizer_release', ((1,),), None,
6600 None, ctypes.c_void_p)
6601 return f(p_equalizer)
6602
6603def libvlc_audio_equalizer_set_preamp(p_equalizer, f_preamp):
6604 '''Set a new pre-amplification value for an equalizer.
6605 The new equalizer settings are subsequently applied to a media player by invoking
6606 L{libvlc_media_player_set_equalizer}().
6607 The supplied amplification value will be clamped to the -20.0 to +20.0 range.
6608 @param p_equalizer: valid equalizer handle, must not be None.
6609 @param f_preamp: preamp value (-20.0 to 20.0 Hz).
6610 @return: zero on success, -1 on error.
6611 @version: LibVLC 2.2.0 or later.
6612 '''
6613 f = _Cfunctions.get('libvlc_audio_equalizer_set_preamp', None) or \
6614 _Cfunction('libvlc_audio_equalizer_set_preamp', ((1,), (1,),), None,
6615 ctypes.c_int, ctypes.c_void_p, ctypes.c_float)
6616 return f(p_equalizer, f_preamp)
6617
6618def libvlc_audio_equalizer_get_preamp(p_equalizer):
6619 '''Get the current pre-amplification value from an equalizer.
6620 @param p_equalizer: valid equalizer handle, must not be None.
6621 @return: preamp value (Hz).
6622 @version: LibVLC 2.2.0 or later.
6623 '''
6624 f = _Cfunctions.get('libvlc_audio_equalizer_get_preamp', None) or \
6625 _Cfunction('libvlc_audio_equalizer_get_preamp', ((1,),), None,
6626 ctypes.c_float, ctypes.c_void_p)
6627 return f(p_equalizer)
6628
6629def libvlc_audio_equalizer_set_amp_at_index(p_equalizer, f_amp, u_band):
6630 '''Set a new amplification value for a particular equalizer frequency band.
6631 The new equalizer settings are subsequently applied to a media player by invoking
6632 L{libvlc_media_player_set_equalizer}().
6633 The supplied amplification value will be clamped to the -20.0 to +20.0 range.
6634 @param p_equalizer: valid equalizer handle, must not be None.
6635 @param f_amp: amplification value (-20.0 to 20.0 Hz).
6636 @param u_band: index, counting from zero, of the frequency band to set.
6637 @return: zero on success, -1 on error.
6638 @version: LibVLC 2.2.0 or later.
6639 '''
6640 f = _Cfunctions.get('libvlc_audio_equalizer_set_amp_at_index', None) or \
6641 _Cfunction('libvlc_audio_equalizer_set_amp_at_index', ((1,), (1,), (1,),), None,
6642 ctypes.c_int, ctypes.c_void_p, ctypes.c_float, ctypes.c_uint)
6643 return f(p_equalizer, f_amp, u_band)
6644
6645def libvlc_audio_equalizer_get_amp_at_index(p_equalizer, u_band):
6646 '''Get the amplification value for a particular equalizer frequency band.
6647 @param p_equalizer: valid equalizer handle, must not be None.
6648 @param u_band: index, counting from zero, of the frequency band to get.
6649 @return: amplification value (Hz); NaN if there is no such frequency band.
6650 @version: LibVLC 2.2.0 or later.
6651 '''
6652 f = _Cfunctions.get('libvlc_audio_equalizer_get_amp_at_index', None) or \
6653 _Cfunction('libvlc_audio_equalizer_get_amp_at_index', ((1,), (1,),), None,
6654 ctypes.c_float, ctypes.c_void_p, ctypes.c_uint)
6655 return f(p_equalizer, u_band)
6656
6657def libvlc_media_player_set_equalizer(p_mi, p_equalizer):
6658 '''Apply new equalizer settings to a media player.
6659 The equalizer is first created by invoking L{libvlc_audio_equalizer_new}() or
6660 L{libvlc_audio_equalizer_new_from_preset}().
6661 It is possible to apply new equalizer settings to a media player whether the media
6662 player is currently playing media or not.
6663 Invoking this method will immediately apply the new equalizer settings to the audio
6664 output of the currently playing media if there is any.
6665 If there is no currently playing media, the new equalizer settings will be applied
6666 later if and when new media is played.
6667 Equalizer settings will automatically be applied to subsequently played media.
6668 To disable the equalizer for a media player invoke this method passing None for the
6669 p_equalizer parameter.
6670 The media player does not keep a reference to the supplied equalizer so it is safe
6671 for an application to release the equalizer reference any time after this method
6672 returns.
6673 @param p_mi: opaque media player handle.
6674 @param p_equalizer: opaque equalizer handle, or None to disable the equalizer for this media player.
6675 @return: zero on success, -1 on error.
6676 @version: LibVLC 2.2.0 or later.
6677 '''
6678 f = _Cfunctions.get('libvlc_media_player_set_equalizer', None) or \
6679 _Cfunction('libvlc_media_player_set_equalizer', ((1,), (1,),), None,
6680 ctypes.c_int, MediaPlayer, ctypes.c_void_p)
6681 return f(p_mi, p_equalizer)
6682
6683def libvlc_media_list_player_new(p_instance):
6684 '''Create new media_list_player.
6685 @param p_instance: libvlc instance.
6686 @return: media list player instance or None on error.
6687 '''
6688 f = _Cfunctions.get('libvlc_media_list_player_new', None) or \
6689 _Cfunction('libvlc_media_list_player_new', ((1,),), class_result(MediaListPlayer),
6690 ctypes.c_void_p, Instance)
6691 return f(p_instance)
6692
6693def libvlc_media_list_player_release(p_mlp):
6694 '''Release a media_list_player after use
6695 Decrement the reference count of a media player object. If the
6696 reference count is 0, then L{libvlc_media_list_player_release}() will
6697 release the media player object. If the media player object
6698 has been released, then it should not be used again.
6699 @param p_mlp: media list player instance.
6700 '''
6701 f = _Cfunctions.get('libvlc_media_list_player_release', None) or \
6702 _Cfunction('libvlc_media_list_player_release', ((1,),), None,
6703 None, MediaListPlayer)
6704 return f(p_mlp)
6705
6706def libvlc_media_list_player_retain(p_mlp):
6707 '''Retain a reference to a media player list object. Use
6708 L{libvlc_media_list_player_release}() to decrement reference count.
6709 @param p_mlp: media player list object.
6710 '''
6711 f = _Cfunctions.get('libvlc_media_list_player_retain', None) or \
6712 _Cfunction('libvlc_media_list_player_retain', ((1,),), None,
6713 None, MediaListPlayer)
6714 return f(p_mlp)
6715
6716def libvlc_media_list_player_event_manager(p_mlp):
6717 '''Return the event manager of this media_list_player.
6718 @param p_mlp: media list player instance.
6719 @return: the event manager.
6720 '''
6721 f = _Cfunctions.get('libvlc_media_list_player_event_manager', None) or \
6722 _Cfunction('libvlc_media_list_player_event_manager', ((1,),), class_result(EventManager),
6723 ctypes.c_void_p, MediaListPlayer)
6724 return f(p_mlp)
6725
6726def libvlc_media_list_player_set_media_player(p_mlp, p_mi):
6727 '''Replace media player in media_list_player with this instance.
6728 @param p_mlp: media list player instance.
6729 @param p_mi: media player instance.
6730 '''
6731 f = _Cfunctions.get('libvlc_media_list_player_set_media_player', None) or \
6732 _Cfunction('libvlc_media_list_player_set_media_player', ((1,), (1,),), None,
6733 None, MediaListPlayer, MediaPlayer)
6734 return f(p_mlp, p_mi)
6735
6736def libvlc_media_list_player_set_media_list(p_mlp, p_mlist):
6737 '''Set the media list associated with the player.
6738 @param p_mlp: media list player instance.
6739 @param p_mlist: list of media.
6740 '''
6741 f = _Cfunctions.get('libvlc_media_list_player_set_media_list', None) or \
6742 _Cfunction('libvlc_media_list_player_set_media_list', ((1,), (1,),), None,
6743 None, MediaListPlayer, MediaList)
6744 return f(p_mlp, p_mlist)
6745
6746def libvlc_media_list_player_play(p_mlp):
6747 '''Play media list.
6748 @param p_mlp: media list player instance.
6749 '''
6750 f = _Cfunctions.get('libvlc_media_list_player_play', None) or \
6751 _Cfunction('libvlc_media_list_player_play', ((1,),), None,
6752 None, MediaListPlayer)
6753 return f(p_mlp)
6754
6755def libvlc_media_list_player_pause(p_mlp):
6756 '''Toggle pause (or resume) media list.
6757 @param p_mlp: media list player instance.
6758 '''
6759 f = _Cfunctions.get('libvlc_media_list_player_pause', None) or \
6760 _Cfunction('libvlc_media_list_player_pause', ((1,),), None,
6761 None, MediaListPlayer)
6762 return f(p_mlp)
6763
6764def libvlc_media_list_player_is_playing(p_mlp):
6765 '''Is media list playing?
6766 @param p_mlp: media list player instance.
6767 @return: true for playing and false for not playing \libvlc_return_bool.
6768 '''
6769 f = _Cfunctions.get('libvlc_media_list_player_is_playing', None) or \
6770 _Cfunction('libvlc_media_list_player_is_playing', ((1,),), None,
6771 ctypes.c_int, MediaListPlayer)
6772 return f(p_mlp)
6773
6774def libvlc_media_list_player_get_state(p_mlp):
6775 '''Get current libvlc_state of media list player.
6776 @param p_mlp: media list player instance.
6777 @return: libvlc_state_t for media list player.
6778 '''
6779 f = _Cfunctions.get('libvlc_media_list_player_get_state', None) or \
6780 _Cfunction('libvlc_media_list_player_get_state', ((1,),), None,
6781 State, MediaListPlayer)
6782 return f(p_mlp)
6783
6784def libvlc_media_list_player_play_item_at_index(p_mlp, i_index):
6785 '''Play media list item at position index.
6786 @param p_mlp: media list player instance.
6787 @param i_index: index in media list to play.
6788 @return: 0 upon success -1 if the item wasn't found.
6789 '''
6790 f = _Cfunctions.get('libvlc_media_list_player_play_item_at_index', None) or \
6791 _Cfunction('libvlc_media_list_player_play_item_at_index', ((1,), (1,),), None,
6792 ctypes.c_int, MediaListPlayer, ctypes.c_int)
6793 return f(p_mlp, i_index)
6794
6795def libvlc_media_list_player_play_item(p_mlp, p_md):
6796 '''Play the given media item.
6797 @param p_mlp: media list player instance.
6798 @param p_md: the media instance.
6799 @return: 0 upon success, -1 if the media is not part of the media list.
6800 '''
6801 f = _Cfunctions.get('libvlc_media_list_player_play_item', None) or \
6802 _Cfunction('libvlc_media_list_player_play_item', ((1,), (1,),), None,
6803 ctypes.c_int, MediaListPlayer, Media)
6804 return f(p_mlp, p_md)
6805
6806def libvlc_media_list_player_stop(p_mlp):
6807 '''Stop playing media list.
6808 @param p_mlp: media list player instance.
6809 '''
6810 f = _Cfunctions.get('libvlc_media_list_player_stop', None) or \
6811 _Cfunction('libvlc_media_list_player_stop', ((1,),), None,
6812 None, MediaListPlayer)
6813 return f(p_mlp)
6814
6815def libvlc_media_list_player_next(p_mlp):
6816 '''Play next item from media list.
6817 @param p_mlp: media list player instance.
6818 @return: 0 upon success -1 if there is no next item.
6819 '''
6820 f = _Cfunctions.get('libvlc_media_list_player_next', None) or \
6821 _Cfunction('libvlc_media_list_player_next', ((1,),), None,
6822 ctypes.c_int, MediaListPlayer)
6823 return f(p_mlp)
6824
6825def libvlc_media_list_player_previous(p_mlp):
6826 '''Play previous item from media list.
6827 @param p_mlp: media list player instance.
6828 @return: 0 upon success -1 if there is no previous item.
6829 '''
6830 f = _Cfunctions.get('libvlc_media_list_player_previous', None) or \
6831 _Cfunction('libvlc_media_list_player_previous', ((1,),), None,
6832 ctypes.c_int, MediaListPlayer)
6833 return f(p_mlp)
6834
6835def libvlc_media_list_player_set_playback_mode(p_mlp, e_mode):
6836 '''Sets the playback mode for the playlist.
6837 @param p_mlp: media list player instance.
6838 @param e_mode: playback mode specification.
6839 '''
6840 f = _Cfunctions.get('libvlc_media_list_player_set_playback_mode', None) or \
6841 _Cfunction('libvlc_media_list_player_set_playback_mode', ((1,), (1,),), None,
6842 None, MediaListPlayer, PlaybackMode)
6843 return f(p_mlp, e_mode)
6844
6845
6846# 4 function(s) blacklisted:
6847# libvlc_audio_output_get_device_type
6848# libvlc_audio_output_set_device_type
6849# libvlc_printerr
6850# libvlc_set_exit_handler
6851
6852# 32 function(s) not wrapped as methods:
6853# libvlc_audio_equalizer_get_amp_at_index
6854# libvlc_audio_equalizer_get_band_count
6855# libvlc_audio_equalizer_get_band_frequency
6856# libvlc_audio_equalizer_get_preamp
6857# libvlc_audio_equalizer_get_preset_count
6858# libvlc_audio_equalizer_get_preset_name
6859# libvlc_audio_equalizer_new
6860# libvlc_audio_equalizer_new_from_preset
6861# libvlc_audio_equalizer_release
6862# libvlc_audio_equalizer_set_amp_at_index
6863# libvlc_audio_equalizer_set_preamp
6864# libvlc_audio_output_device_list_release
6865# libvlc_audio_output_list_release
6866# libvlc_clearerr
6867# libvlc_clock
6868# libvlc_event_type_name
6869# libvlc_free
6870# libvlc_get_changeset
6871# libvlc_get_compiler
6872# libvlc_get_version
6873# libvlc_log_clear
6874# libvlc_log_close
6875# libvlc_log_count
6876# libvlc_log_get_context
6877# libvlc_log_get_iterator
6878# libvlc_log_get_object
6879# libvlc_media_tracks_release
6880# libvlc_module_description_list_release
6881# libvlc_new
6882# libvlc_track_description_list_release
6883# libvlc_track_description_release
6884# libvlc_vprinterr
6885
6886# Start of footer.py #
6887
6888# Backward compatibility
6889def callbackmethod(callback):
6890 """Now obsolete @callbackmethod decorator."""
6891 return callback
6892
6893# libvlc_free is not present in some versions of libvlc. If it is not
6894# in the library, then emulate it by calling libc.free
6895if not hasattr(dll, 'libvlc_free'):
6896 # need to find the free function in the C runtime. This is
6897 # platform specific.
6898 # For Linux and MacOSX
6899 libc_path = find_library('c')
6900 if libc_path:
6901 libc = ctypes.CDLL(libc_path)
6902 libvlc_free = libc.free
6903 else:
6904 # On win32, it is impossible to guess the proper lib to call
6905 # (msvcrt, mingw...). Just ignore the call: it will memleak,
6906 # but not prevent to run the application.
6907 def libvlc_free(p):
6908 pass
6909
6910 # ensure argtypes is right, because default type of int won't
6911 # work on 64-bit systems
6912 libvlc_free.argtypes = [ ctypes.c_void_p ]
6913
6914# Version functions
6915def _dot2int(v):
6916 '''(INTERNAL) Convert 'i.i.i[.i]' str to int.
6917 '''
6918 t = [int(i) for i in v.split('.')]
6919 if len(t) == 3:
6920 t.append(0)
6921 elif len(t) != 4:
6922 raise ValueError('"i.i.i[.i]": %r' % (v,))
6923 if min(t) < 0 or max(t) > 255:
6924 raise ValueError('[0..255]: %r' % (v,))
6925 i = t.pop(0)
6926 while t:
6927 i = (i << 8) + t.pop(0)
6928 return i
6929
6930def hex_version():
6931 """Return the version of these bindings in hex or 0 if unavailable.
6932 """
6933 try:
6934 return _dot2int(__version__)
6935 except (NameError, ValueError):
6936 return 0
6937
6938def libvlc_hex_version():
6939 """Return the libvlc version in hex or 0 if unavailable.
6940 """
6941 try:
6942 return _dot2int(bytes_to_str(libvlc_get_version()).split()[0])
6943 except ValueError:
6944 return 0
6945
6946def debug_callback(event, *args, **kwds):
6947 '''Example callback, useful for debugging.
6948 '''
6949 l = ['event %s' % (event.type,)]
6950 if args:
6951 l.extend(map(str, args))
6952 if kwds:
6953 l.extend(sorted('%s=%s' % t for t in kwds.items()))
6954 print('Debug callback (%s)' % ', '.join(l))
6955
6956
6957if __name__ == '__main__':
6958 logging.basicConfig(level=logging.DEBUG)
6959 try:
6960 from msvcrt import getch
6961 except ImportError:
6962 import termios
6963 import tty
6964
6965 def getch(): # getchar(), getc(stdin) #PYCHOK flake
6966 fd = sys.stdin.fileno()
6967 old = termios.tcgetattr(fd)
6968 try:
6969 tty.setraw(fd)
6970 ch = sys.stdin.read(1)
6971 finally:
6972 termios.tcsetattr(fd, termios.TCSADRAIN, old)
6973 return ch
6974
6975 def end_callback(event):
6976 print('End of media stream (event %s)' % event.type)
6977 sys.exit(0)
6978
6979 echo_position = False
6980 def pos_callback(event, player):
6981 if echo_position:
6982 sys.stdout.write('\r%s to %.2f%% (%.2f%%)' % (event.type,
6983 event.u.new_position * 100,
6984 player.get_position() * 100))
6985 sys.stdout.flush()
6986
6987 def print_version():
6988 """Print version of this vlc.py and of the libvlc"""
6989 try:
6990 print('Build date: %s (%#x)' % (build_date, hex_version()))
6991 print('LibVLC version: %s (%#x)' % (bytes_to_str(libvlc_get_version()), libvlc_hex_version()))
6992 print('LibVLC compiler: %s' % bytes_to_str(libvlc_get_compiler()))
6993 if plugin_path:
6994 print('Plugin path: %s' % plugin_path)
6995 except:
6996 print('Error: %s' % sys.exc_info()[1])
6997
6998 if sys.argv[1:] and '-h' not in sys.argv[1:] and '--help' not in sys.argv[1:]:
6999
7000 movie = os.path.expanduser(sys.argv.pop())
7001 if not os.access(movie, os.R_OK):
7002 print('Error: %s file not readable' % movie)
7003 sys.exit(1)
7004
7005 # Need --sub-source=marq in order to use marquee below
7006 instance = Instance(["--sub-source=marq"] + sys.argv[1:])
7007 try:
7008 media = instance.media_new(movie)
7009 except (AttributeError, NameError) as e:
7010 print('%s: %s (%s %s vs LibVLC %s)' % (e.__class__.__name__, e,
7011 sys.argv[0], __version__,
7012 libvlc_get_version()))
7013 sys.exit(1)
7014 player = instance.media_player_new()
7015 player.set_media(media)
7016 player.play()
7017
7018 # Some marquee examples. Marquee requires '--sub-source marq' in the
7019 # Instance() call above, see <http://www.videolan.org/doc/play-howto/en/ch04.html>
7020 player.video_set_marquee_int(VideoMarqueeOption.Enable, 1)
7021 player.video_set_marquee_int(VideoMarqueeOption.Size, 24) # pixels
7022 player.video_set_marquee_int(VideoMarqueeOption.Position, Position.Bottom)
7023 if False: # only one marquee can be specified
7024 player.video_set_marquee_int(VideoMarqueeOption.Timeout, 5000) # millisec, 0==forever
7025 t = media.get_mrl() # movie
7026 else: # update marquee text periodically
7027 player.video_set_marquee_int(VideoMarqueeOption.Timeout, 0) # millisec, 0==forever
7028 player.video_set_marquee_int(VideoMarqueeOption.Refresh, 1000) # millisec (or sec?)
7029 ##t = '$L / $D or $P at $T'
7030 t = '%Y-%m-%d %H:%M:%S'
7031 player.video_set_marquee_string(VideoMarqueeOption.Text, str_to_bytes(t))
7032
7033 # Some event manager examples. Note, the callback can be any Python
7034 # callable and does not need to be decorated. Optionally, specify
7035 # any number of positional and/or keyword arguments to be passed
7036 # to the callback (in addition to the first one, an Event instance).
7037 event_manager = player.event_manager()
7038 event_manager.event_attach(EventType.MediaPlayerEndReached, end_callback)
7039 event_manager.event_attach(EventType.MediaPlayerPositionChanged, pos_callback, player)
7040
7041 def mspf():
7042 """Milliseconds per frame"""
7043 return int(1000 // (player.get_fps() or 25))
7044
7045 def print_info():
7046 """Print information about the media"""
7047 try:
7048 print_version()
7049 media = player.get_media()
7050 print('State: %s' % player.get_state())
7051 print('Media: %s' % bytes_to_str(media.get_mrl()))
7052 print('Track: %s/%s' % (player.video_get_track(), player.video_get_track_count()))
7053 print('Current time: %s/%s' % (player.get_time(), media.get_duration()))
7054 print('Position: %s' % player.get_position())
7055 print('FPS: %s (%d ms)' % (player.get_fps(), mspf()))
7056 print('Rate: %s' % player.get_rate())
7057 print('Video size: %s' % str(player.video_get_size(0))) # num=0
7058 print('Scale: %s' % player.video_get_scale())
7059 print('Aspect ratio: %s' % player.video_get_aspect_ratio())
7060 #print('Window:' % player.get_hwnd()
7061 except Exception:
7062 print('Error: %s' % sys.exc_info()[1])
7063
7064 def sec_forward():
7065 """Go forward one sec"""
7066 player.set_time(player.get_time() + 1000)
7067
7068 def sec_backward():
7069 """Go backward one sec"""
7070 player.set_time(player.get_time() - 1000)
7071
7072 def frame_forward():
7073 """Go forward one frame"""
7074 player.set_time(player.get_time() + mspf())
7075
7076 def frame_backward():
7077 """Go backward one frame"""
7078 player.set_time(player.get_time() - mspf())
7079
7080 def print_help():
7081 """Print help"""
7082 print('Single-character commands:')
7083 for k, m in sorted(keybindings.items()):
7084 m = (m.__doc__ or m.__name__).splitlines()[0]
7085 print(' %s: %s.' % (k, m.rstrip('.')))
7086 print('0-9: go to that fraction of the movie')
7087
7088 def quit_app():
7089 """Stop and exit"""
7090 sys.exit(0)
7091
7092 def toggle_echo_position():
7093 """Toggle echoing of media position"""
7094 global echo_position
7095 echo_position = not echo_position
7096
7097 keybindings = {
7098 ' ': player.pause,
7099 '+': sec_forward,
7100 '-': sec_backward,
7101 '.': frame_forward,
7102 ',': frame_backward,
7103 'f': player.toggle_fullscreen,
7104 'i': print_info,
7105 'p': toggle_echo_position,
7106 'q': quit_app,
7107 '?': print_help,
7108 }
7109
7110 print('Press q to quit, ? to get help.%s' % os.linesep)
7111 while True:
7112 k = getch()
7113 print('> %s' % k)
7114 if k in keybindings:
7115 keybindings[k]()
7116 elif k.isdigit():
7117 # jump to fraction of the movie.
7118 player.set_position(float('0.'+k))
7119
7120 else:
7121 print('Usage: %s [options] <movie_filename>' % sys.argv[0])
7122 print('Once launched, type ? for help.')
7123 print('')
7124 print_version()