python: remove references to obsolete API
[vlc/bindings/python.git] / generator / templates / override.py
1
2 class Instance:
3     """Create a new Instance instance.
4
5     It may take as parameter either:
6       - a string
7       - a list of strings as first parameters
8       - the parameters given as the constructor parameters (must be strings)
9     """
10     def __new__(cls, *args):
11         if len(args) == 1:
12             # Only 1 arg. It is either a C pointer, or an arg string,
13             # or a tuple.
14             i = args[0]
15             if isinstance(i, _Ints):
16                 return _Constructor(cls, i)
17             elif isinstance(i, basestring):
18                 args = i.strip().split()
19             elif isinstance(i, _Seqs):
20                 args = list(i)
21             else:
22                 raise VLCException('Instance %r' % (args,))
23         else:
24             args = list(args)
25
26         if not args:  # no parameters passed
27             args = ['vlc']
28         elif args[0] != 'vlc':
29             args.insert(0, 'vlc')
30
31         if plugin_path is not None:
32             # set plugin_path if detected, win32 and MacOS,
33             # if the user did not specify it itself.
34             os.environ.setdefault('VLC_PLUGIN_PATH', plugin_path)
35
36         if PYTHON3:
37             args = [ str_to_bytes(a) for a in args ]
38         return libvlc_new(len(args), args)
39
40     def media_player_new(self, uri=None):
41         """Create a new MediaPlayer instance.
42
43         @param uri: an optional URI to play in the player.
44         """
45         p = libvlc_media_player_new(self)
46         if uri:
47             p.set_media(self.media_new(uri))
48         p._instance = self
49         return p
50
51     def media_list_player_new(self):
52         """Create a new MediaListPlayer instance.
53         """
54         p = libvlc_media_list_player_new(self)
55         p._instance = self
56         return p
57
58     def media_new(self, mrl, *options):
59         """Create a new Media instance.
60
61         If mrl contains a colon (:) preceded by more than 1 letter, it
62         will be treated as a URL. Else, it will be considered as a
63         local path. If you need more control, directly use
64         media_new_location/media_new_path methods.
65
66         Options can be specified as supplementary string parameters,
67         but note that many options cannot be set at the media level,
68         and rather at the Instance level. For instance, the marquee
69         filter must be specified when creating the vlc.Instance or
70         vlc.MediaPlayer.
71
72         Alternatively, options can be added to the media using the
73         Media.add_options method (with the same limitation).
74
75         @param options: optional media option=value strings
76         """
77         if ':' in mrl and mrl.index(':') > 1:
78             # Assume it is a URL
79             m = libvlc_media_new_location(self, str_to_bytes(mrl))
80         else:
81             # Else it should be a local path.
82             m = libvlc_media_new_path(self, str_to_bytes(os.path.normpath(mrl)))
83         for o in options:
84             libvlc_media_add_option(m, str_to_bytes(o))
85         m._instance = self
86         return m
87
88     def media_list_new(self, mrls=None):
89         """Create a new MediaList instance.
90         @param mrls: optional list of MRL strings
91         """
92         l = libvlc_media_list_new(self)
93         # We should take the lock, but since we did not leak the
94         # reference, nobody else can access it.
95         if mrls:
96             for m in mrls:
97                 l.add_media(m)
98         l._instance = self
99         return l
100
101     def audio_output_enumerate_devices(self):
102         """Enumerate the defined audio output devices.
103
104         @return: list of dicts {name:, description:, devices:}
105         """
106         r = []
107         head = libvlc_audio_output_list_get(self)
108         if head:
109             i = head
110             while i:
111                 i = i.contents
112                 r.append({'name': i.name, 'description': i.description})
113                 i = i.next
114             libvlc_audio_output_list_release(head)
115         return r
116
117     def audio_filter_list_get(self):
118         """Returns a list of available audio filters.
119
120         """
121         return module_description_list(libvlc_audio_filter_list_get(self))
122
123     def video_filter_list_get(self):
124         """Returns a list of available video filters.
125
126         """
127         return module_description_list(libvlc_video_filter_list_get(self))
128
129 class Media:
130     """Create a new Media instance.
131
132     Usage: Media(MRL, *options)
133
134     See vlc.Instance.media_new documentation for details.
135     """
136     def __new__(cls, *args):
137         if args:
138             i = args[0]
139             if isinstance(i, _Ints):
140                 return _Constructor(cls, i)
141             if isinstance(i, Instance):
142                 return i.media_new(*args[1:])
143
144         o = get_default_instance().media_new(*args)
145         return o
146
147     def get_instance(self):
148         return getattr(self, '_instance', None)
149
150     def add_options(self, *options):
151         """Add a list of options to the media.
152
153         Options must be written without the double-dash. Warning: most
154         audio and video options, such as text renderer, have no
155         effects on an individual media. These options must be set at
156         the vlc.Instance or vlc.MediaPlayer instanciation.
157
158         @param options: optional media option=value strings
159         """
160         for o in options:
161             self.add_option(o)
162
163     def tracks_get(self):
164         """Get media descriptor's elementary streams description
165         Note, you need to call L{parse}() or play the media at least once
166         before calling this function.
167         Not doing this will result in an empty array.
168         The result must be freed with L{tracks_release}.
169         @version: LibVLC 2.1.0 and later.
170         """
171         mediaTrack_pp = ctypes.POINTER(MediaTrack)()
172         n = libvlc_media_tracks_get(self, ctypes.byref(mediaTrack_pp))
173         info = ctypes.cast(mediaTrack_pp, ctypes.POINTER(ctypes.POINTER(MediaTrack) * n))
174         try:
175             contents = info.contents
176         except ValueError:
177             # Media not parsed, no info.
178             return None
179         tracks = ( contents[i].contents for i in range(len(contents)) )
180         # libvlc_media_tracks_release(mediaTrack_pp, n)
181         return tracks
182
183 class MediaList:
184     """Create a new MediaList instance.
185
186     Usage: MediaList(list_of_MRLs)
187
188     See vlc.Instance.media_list_new documentation for details.
189     """
190     def __new__(cls, *args):
191         if args:
192             i = args[0]
193             if isinstance(i, _Ints):
194                 return _Constructor(cls, i)
195             if isinstance(i, Instance):
196                 return i.media_list_new(*args[1:])
197
198         o = get_default_instance().media_list_new(*args)
199         return o
200
201     def get_instance(self):
202         return getattr(self, '_instance', None)
203
204     def add_media(self, mrl):
205         """Add media instance to media list.
206
207         The L{lock} should be held upon entering this function.
208         @param mrl: a media instance or a MRL.
209         @return: 0 on success, -1 if the media list is read-only.
210         """
211         if isinstance(mrl, basestring):
212             mrl = (self.get_instance() or get_default_instance()).media_new(mrl)
213         return libvlc_media_list_add_media(self, mrl)
214
215 class MediaPlayer:  #PYCHOK expected (comment is lost)
216     """Create a new MediaPlayer instance.
217
218     It may take as parameter either:
219       - a string (media URI), options... In this case, a vlc.Instance will be created.
220       - a vlc.Instance, a string (media URI), options...
221     """
222     def __new__(cls, *args):
223         if len(args) == 1 and isinstance(args[0], _Ints):
224             return _Constructor(cls, args[0])
225
226         if args and isinstance(args[0], Instance):
227             instance = args[0]
228             args = args[1:]
229         else:
230             instance = get_default_instance()
231
232         o = instance.media_player_new()
233         if args:
234             o.set_media(instance.media_new(*args))
235         return o
236
237     def get_instance(self):
238         """Return the associated Instance.
239         """
240         return self._instance  #PYCHOK expected
241
242     def set_mrl(self, mrl, *options):
243         """Set the MRL to play.
244
245         Warning: most audio and video options, such as text renderer,
246         have no effects on an individual media. These options must be
247         set at the vlc.Instance or vlc.MediaPlayer instanciation.
248
249         @param mrl: The MRL
250         @param options: optional media option=value strings
251         @return: the Media object
252         """
253         m = self.get_instance().media_new(mrl, *options)
254         self.set_media(m)
255         return m
256
257     def video_get_spu_description(self):
258         """Get the description of available video subtitles.
259         """
260         return track_description_list(libvlc_video_get_spu_description(self))
261
262     def video_get_track_description(self):
263         """Get the description of available video tracks.
264         """
265         return track_description_list(libvlc_video_get_track_description(self))
266
267     def audio_get_track_description(self):
268         """Get the description of available audio tracks.
269         """
270         return track_description_list(libvlc_audio_get_track_description(self))
271
272     def get_full_title_descriptions(self):
273         '''Get the full description of available titles.
274         @return: the titles list
275         @version: LibVLC 3.0.0 and later.
276         '''
277         titleDescription_pp = ctypes.POINTER(TitleDescription)()
278         n = libvlc_media_player_get_full_title_descriptions(self, ctypes.byref(titleDescription_pp))
279         info = ctypes.cast(titleDescription_pp, ctypes.POINTER(ctypes.POINTER(TitleDescription) * n))
280         try:
281             contents = info.contents
282         except ValueError:
283             # Media not parsed, no info.
284             return None
285         descr = ( contents[i].contents for i in range(len(contents)) )
286         return descr
287
288     def get_full_chapter_descriptions(self, i_chapters_of_title):
289         '''Get the full description of available chapters.
290         @param i_chapters_of_title: index of the title to query for chapters (uses current title if set to -1).
291         @return: the chapters list
292         @version: LibVLC 3.0.0 and later.
293         '''
294         chapterDescription_pp = ctypes.POINTER(ChapterDescription)()
295         n = libvlc_media_player_get_full_chapter_descriptions(self, ctypes.byref(chapterDescription_pp))
296         info = ctypes.cast(chapterDescription_pp, ctypes.POINTER(ctypes.POINTER(ChapterDescription) * n))
297         try:
298             contents = info.contents
299         except ValueError:
300             # Media not parsed, no info.
301             return None
302         descr = ( contents[i].contents for i in range(len(contents)) )
303         return descr
304
305     def video_get_size(self, num=0):
306         """Get the video size in pixels as 2-tuple (width, height).
307
308         @param num: video number (default 0).
309         """
310         r = libvlc_video_get_size(self, num)
311         if isinstance(r, tuple) and len(r) == 2:
312             return r
313         else:
314             raise VLCException('invalid video number (%s)' % (num,))
315
316     def set_hwnd(self, drawable):
317         """Set a Win32/Win64 API window handle (HWND).
318
319         Specify where the media player should render its video
320         output. If LibVLC was built without Win32/Win64 API output
321         support, then this has no effects.
322
323         @param drawable: windows handle of the drawable.
324         """
325         if not isinstance(drawable, ctypes.c_void_p):
326             drawable = ctypes.c_void_p(int(drawable))
327         libvlc_media_player_set_hwnd(self, drawable)
328
329     def video_get_width(self, num=0):
330         """Get the width of a video in pixels.
331
332         @param num: video number (default 0).
333         """
334         return self.video_get_size(num)[0]
335
336     def video_get_height(self, num=0):
337         """Get the height of a video in pixels.
338
339         @param num: video number (default 0).
340         """
341         return self.video_get_size(num)[1]
342
343     def video_get_cursor(self, num=0):
344         """Get the mouse pointer coordinates over a video as 2-tuple (x, y).
345
346         Coordinates are expressed in terms of the decoded video resolution,
347         B{not} in terms of pixels on the screen/viewport.  To get the
348         latter, you must query your windowing system directly.
349
350         Either coordinate may be negative or larger than the corresponding
351         size of the video, if the cursor is outside the rendering area.
352
353         @warning: The coordinates may be out-of-date if the pointer is not
354         located on the video rendering area.  LibVLC does not track the
355         mouse pointer if the latter is outside the video widget.
356
357         @note: LibVLC does not support multiple mouse pointers (but does
358         support multiple input devices sharing the same pointer).
359
360         @param num: video number (default 0).
361         """
362         r = libvlc_video_get_cursor(self, num)
363         if isinstance(r, tuple) and len(r) == 2:
364             return r
365         raise VLCException('invalid video number (%s)' % (num,))
366
367 class MediaListPlayer:
368     """Create a new MediaListPlayer instance.
369
370     It may take as parameter either:
371       - a vlc.Instance
372       - nothing
373     """
374     def __new__(cls, arg=None):
375         if arg is None:
376             i = get_default_instance()
377         elif isinstance(arg, Instance):
378             i = arg
379         elif isinstance(arg, _Ints):
380             return _Constructor(cls, arg)
381         else:
382             raise TypeError('MediaListPlayer %r' % (arg,))
383
384         return i.media_list_player_new()
385
386     def get_instance(self):
387         """Return the associated Instance.
388         """
389         return self._instance  #PYCHOK expected
390
391 class LogIterator:
392     """Create a new VLC log iterator.
393     """
394     def __iter__(self):
395         return self
396
397     def next(self):
398         if self.has_next():
399             b = LogMessage()
400             i = libvlc_log_iterator_next(self, b)
401             return i.contents
402         raise StopIteration
403
404     def __next__(self):
405         return self.next()
406
407 class Log:
408     """Create a new VLC log instance.
409     """
410     def __iter__(self):
411         return self.get_iterator()
412
413     def dump(self):
414         return [ str(m) for m in self ]
415
416 class EventManager:
417     """Create an event manager with callback handler.
418
419     This class interposes the registration and handling of
420     event notifications in order to (a) remove the need for
421     decorating each callback functions with the decorator
422     '@callbackmethod', (b) allow any number of positional
423     and/or keyword arguments to the callback (in addition
424     to the Event instance) and (c) to preserve the Python
425     objects such that the callback and argument objects
426     remain alive (i.e. are not garbage collected) until
427     B{after} the notification has been unregistered.
428
429     @note: Only a single notification can be registered
430     for each event type in an EventManager instance.
431     """
432     _callback_handler = None
433     _callbacks = {}
434
435     def __new__(cls, ptr=_internal_guard):
436         if ptr == _internal_guard:
437             raise VLCException("(INTERNAL) ctypes class.\nYou should get a reference to EventManager through the MediaPlayer.event_manager() method.")
438         return _Constructor(cls, ptr)
439
440     def event_attach(self, eventtype, callback, *args, **kwds):
441         """Register an event notification.
442
443         @param eventtype: the desired event type to be notified about.
444         @param callback: the function to call when the event occurs.
445         @param args: optional positional arguments for the callback.
446         @param kwds: optional keyword arguments for the callback.
447         @return: 0 on success, ENOMEM on error.
448
449         @note: The callback function must have at least one argument,
450         an Event instance.  Any other, optional positional and keyword
451         arguments are in B{addition} to the first one.
452         """
453         if not isinstance(eventtype, EventType):
454             raise VLCException("%s required: %r" % ('EventType', eventtype))
455         if not hasattr(callback, '__call__'):  # callable()
456             raise VLCException("%s required: %r" % ('callable', callback))
457          # check that the callback expects arguments
458         if not any(getargspec(callback)[:2]):  # list(...)
459             raise VLCException("%s required: %r" % ('argument', callback))
460
461         if self._callback_handler is None:
462             _called_from_ctypes = ctypes.CFUNCTYPE(None, ctypes.POINTER(Event), ctypes.c_void_p)
463             @_called_from_ctypes
464             def _callback_handler(event, k):
465                 """(INTERNAL) handle callback call from ctypes.
466
467                 @note: We cannot simply make this an EventManager
468                 method since ctypes does not prepend self as the
469                 first parameter, hence this closure.
470                 """
471                 try: # retrieve Python callback and arguments
472                     call, args, kwds = self._callbacks[k]
473                      # deref event.contents to simplify callback code
474                     call(event.contents, *args, **kwds)
475                 except KeyError:  # detached?
476                     pass
477             self._callback_handler = _callback_handler
478             self._callbacks = {}
479
480         k = eventtype.value
481         r = libvlc_event_attach(self, k, self._callback_handler, k)
482         if not r:
483             self._callbacks[k] = (callback, args, kwds)
484         return r
485
486     def event_detach(self, eventtype):
487         """Unregister an event notification.
488
489         @param eventtype: the event type notification to be removed.
490         """
491         if not isinstance(eventtype, EventType):
492             raise VLCException("%s required: %r" % ('EventType', eventtype))
493
494         k = eventtype.value
495         if k in self._callbacks:
496             del self._callbacks[k] # remove, regardless of libvlc return value
497             libvlc_event_detach(self, k, self._callback_handler, k)