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