diff --git a/openlp/core/ui/media/vendor/vlc.py b/openlp/core/ui/media/vendor/vlc.py index 36a2b206f..e7138b50a 100644 --- a/openlp/core/ui/media/vendor/vlc.py +++ b/openlp/core/ui/media/vendor/vlc.py @@ -2,7 +2,7 @@ # Python ctypes bindings for VLC # -# Copyright (C) 2009-2013 the VideoLAN team +# Copyright (C) 2009-2012 the VideoLAN team # $Id: $ # # Authors: Olivier Aubert @@ -48,7 +48,7 @@ import sys from inspect import getargspec __version__ = "N/A" -build_date = "Fri Oct 5 21:35:59 2012" +build_date = "Wed Feb 13 18:40:24 2013" if sys.version_info[0] > 2: str = str @@ -1000,6 +1000,50 @@ class MediaTrackInfo(_Cstruct): ('rate_or_width', ctypes.c_uint ), ] +class AudioTrack(_Cstruct): + _fields_ = [ + ('channels', ctypes.c_uint), + ('rate', ctypes.c_uint), + ] + +class VideoTrack(_Cstruct): + _fields_ = [ + ('height', ctypes.c_uint), + ('width', ctypes.c_uint), + ('sar_num', ctypes.c_uint), + ('sar_den', ctypes.c_uint), + ('frame_rate_num', ctypes.c_uint), + ('frame_rate_den', ctypes.c_uint), + ] + +class SubtitleTrack(_Cstruct): + _fields_ = [ + ('encoding', ctypes.c_char_p), + ] + +class MediaTrackTracks(ctypes.Union): + _fields_ = [ + ('audio', ctypes.POINTER(AudioTrack)), + ('video', ctypes.POINTER(VideoTrack)), + ('subtitle', ctypes.POINTER(SubtitleTrack)), + ] + +class MediaTrack(_Cstruct): + _anonymous_ = ("u",) + _fields_ = [ + ('codec', ctypes.c_uint32), + ('original_fourcc', ctypes.c_uint32), + ('id', ctypes.c_int ), + ('type', TrackType ), + ('profile', ctypes.c_int ), + ('level', ctypes.c_int ), + + ('u', MediaTrackTracks), + ('bitrate', ctypes.c_uint), + ('language', ctypes.c_char_p), + ('description', ctypes.c_char_p), + ] + class PlaylistItem(_Cstruct): _fields_ = [ ('id', ctypes.c_int ), @@ -1122,6 +1166,17 @@ def module_description_list(head): libvlc_module_description_list_release(head) return r +class AudioOutputDevice(_Cstruct): + + def __str__(self): + return '%s(%d:%s)' % (self.__class__.__name__, self.id, self.name) + +AudioOutputDevice._fields_ = [ # recursive struct + ('next', ctypes.POINTER(AudioOutputDevice)), + ('device', ctypes.c_char_p ), + ('description', ctypes.c_char_p), + ] + # End of header.py # class EventManager(_Ctype): @@ -1282,7 +1337,7 @@ class Instance(_Ctype): m = libvlc_media_new_location(self, str_to_bytes(mrl)) else: # Else it should be a local path. - m = libvlc_media_new_path(self, str_to_bytes(mrl)) + m = libvlc_media_new_path(self, str_to_bytes(os.path.normpath(mrl))) for o in options: libvlc_media_add_option(m, str_to_bytes(o)) m._instance = self @@ -1361,27 +1416,6 @@ class Instance(_Ctype): ''' return libvlc_set_user_agent(self, name, http) - def get_log_verbosity(self): - '''Always returns minus one. - This function is only provided for backward compatibility. - @return: always -1. - ''' - return libvlc_get_log_verbosity(self) - - def set_log_verbosity(self, level): - '''This function does nothing. - It is only provided for backward compatibility. - @param level: ignored. - ''' - return libvlc_set_log_verbosity(self, level) - - def log_open(self): - '''This function does nothing useful. - It is only provided for backward compatibility. - @return: an unique pointer or NULL on error. - ''' - return libvlc_log_open(self) - def media_new_location(self, psz_mrl): '''Create a media with a certain given media resource location, for instance a valid URL. @@ -1445,34 +1479,26 @@ class Instance(_Ctype): return libvlc_media_library_new(self) def audio_output_list_get(self): - '''Get the list of available audio outputs. + '''Gets the list of available audio outputs. @return: list of available audio outputs. It must be freed it with In case of error, NULL is returned. ''' return libvlc_audio_output_list_get(self) - def audio_output_device_count(self, psz_audio_output): - '''Get count of devices for audio output, these devices are hardware oriented - like analor or digital output of sound card. - @param psz_audio_output: - name of audio output, See L{AudioOutput}. - @return: number of devices. + def audio_output_device_list_get(self, aout): + '''Gets a list of audio output devices for a given audio output. + See L{audio_output_device_set}(). + @note: Not all audio outputs support this. In particular, an empty (NULL) + list of devices does B{not} imply that the specified audio output does + not work. + @note: The list might not be exhaustive. + @warning: Some audio output devices in the list might not actually work in + some circumstances. By default, it is recommended to not specify any + explicit audio device. + @param psz_aout: audio output name (as returned by L{audio_output_list_get}()). + @return: A NULL-terminated linked list of potential audio output devices. It must be freed it with L{audio_output_device_list_release}(). + @version: LibVLC 2.1.0 or later. ''' - return libvlc_audio_output_device_count(self, psz_audio_output) - - def audio_output_device_longname(self, psz_audio_output, i_device): - '''Get long name of device, if not available short name given. - @param psz_audio_output: - name of audio output, See L{AudioOutput}. - @param i_device: device index. - @return: long name of device. - ''' - return libvlc_audio_output_device_longname(self, psz_audio_output, i_device) - - def audio_output_device_id(self, psz_audio_output, i_device): - '''Get id name of device. - @param psz_audio_output: - name of audio output, See L{AudioOutput}. - @param i_device: device index. - @return: id name of device, use for setting device, need to be free after use. - ''' - return libvlc_audio_output_device_id(self, psz_audio_output, i_device) + return libvlc_audio_output_device_list_get(self, aout) def vlm_release(self): '''Release the vlm instance related to the given L{Instance}. @@ -1683,87 +1709,6 @@ class Instance(_Ctype): ''' return libvlc_vlm_get_event_manager(self) -class Log(_Ctype): - '''Create a new VLC log instance. - - ''' - - def __new__(cls, ptr=_internal_guard): - '''(INTERNAL) ctypes wrapper constructor. - ''' - return _Constructor(cls, ptr) - - def __iter__(self): - return self.get_iterator() - - def dump(self): - return [ str(m) for m in self ] - - - def close(self): - '''Frees memory allocated by L{open}(). - ''' - return libvlc_log_close(self) - - def count(self): - '''Always returns zero. - This function is only provided for backward compatibility. - @return: always zero. - ''' - return libvlc_log_count(self) - - def __len__(self): - return libvlc_log_count(self) - - def clear(self): - '''This function does nothing. - It is only provided for backward compatibility. - ''' - return libvlc_log_clear(self) - - def get_iterator(self): - '''This function does nothing useful. - It is only provided for backward compatibility. - @return: an unique pointer or NULL on error or if the parameter was NULL. - ''' - return libvlc_log_get_iterator(self) - -class LogIterator(_Ctype): - '''Create a new VLC log iterator. - - ''' - - def __new__(cls, ptr=_internal_guard): - '''(INTERNAL) ctypes wrapper constructor. - ''' - return _Constructor(cls, ptr) - - def __iter__(self): - return self - - def next(self): - if self.has_next(): - b = LogMessage() - i = libvlc_log_iterator_next(self, b) - return i.contents - raise StopIteration - - def __next__(self): - return self.next() - - - def free(self): - '''Frees memory allocated by L{log_get_iterator}(). - ''' - return libvlc_log_iterator_free(self) - - def has_next(self): - '''Always returns zero. - This function is only provided for backward compatibility. - @return: always zero. - ''' - return libvlc_log_iterator_has_next(self) - class Media(_Ctype): '''Create a new Media instance. @@ -1809,11 +1754,13 @@ class Media(_Ctype): This option will be used to determine how the media_player will read the media. This allows to use VLC's advanced reading/streaming options on a per-media basis. - The options are detailed in vlc --long-help, for instance - "--sout-all". Note that all options are not usable on medias: - specifically, due to architectural issues, video-related options - such as text renderer options cannot be set on a single media. They - must be set on the whole libvlc instance instead. + @note: The options are listed in 'vlc --long-help' from the command line, + e.g. "-sout-all". Keep in mind that available options and their semantics + vary across LibVLC versions and builds. + @warning: Not all options affects L{Media} objects: + Specifically, due to architectural issues most audio and video options, + such as text renderer options, have no effects on an individual media. + These options must be set through L{new}() instead. @param ppsz_options: the options (as a string). ''' return libvlc_media_add_option(self, ppsz_options) @@ -1906,6 +1853,14 @@ class Media(_Ctype): ''' return libvlc_media_get_stats(self, p_stats) + def subitems(self): + '''Get subitems of media descriptor object. This will increment + the reference count of supplied media descriptor object. Use + L{list_release}() to decrement the reference counting. + @return: list of media descriptor subitems or NULL. + ''' + return libvlc_media_subitems(self) + def event_manager(self): '''Get event manager from media descriptor object. NOTE: this function doesn't increment reference counting. @@ -1925,7 +1880,7 @@ class Media(_Ctype): The method is synchronous. See L{parse_async} See L{get_meta} - See L{get_tracks_info}. + See libvlc_media_get_tracks_info. ''' return libvlc_media_parse(self) @@ -1939,7 +1894,7 @@ class Media(_Ctype): See L{parse} See libvlc_MediaParsedChanged See L{get_meta} - See L{get_tracks_info}. + See libvlc_media_get_tracks_info. ''' return libvlc_media_parse_async(self) @@ -1965,15 +1920,16 @@ class Media(_Ctype): ''' return libvlc_media_get_user_data(self) - def get_tracks_info(self): + def tracks_get(self, tracks): '''Get media descriptor's elementary streams description Note, you need to call L{parse}() or play the media at least once before calling this function. Not doing this will result in an empty array. - @param tracks: address to store an allocated array of Elementary Streams descriptions (must be freed by the caller) [OUT]. - @return: the number of Elementary Streams. + @param tracks: address to store an allocated array of Elementary Streams descriptions (must be freed with L{tracks_release}. + @return: the number of Elementary Streams (zero on error). + @version: LibVLC 2.1.0 and later. ''' - return libvlc_media_get_tracks_info(self) + return libvlc_media_tracks_get(self, tracks) def player_new_from_media(self): '''Create a Media Player object from a Media. @@ -2255,7 +2211,7 @@ class MediaListPlayer(_Ctype): return libvlc_media_list_player_play(self) def pause(self): - '''Pause media list. + '''Toggle pause (or resume) media list. ''' return libvlc_media_list_player_pause(self) @@ -2681,13 +2637,14 @@ class MediaPlayer(_Ctype): return libvlc_media_player_set_time(self, i_time) def get_position(self): - '''Get movie position. + '''Get movie position as percentage between 0.0 and 1.0. @return: movie position, or -1. in case of error. ''' return libvlc_media_player_get_position(self) def set_position(self, f_pos): - '''Set movie position. This has no effect if playback is not enabled. + '''Set movie position as percentage between 0.0 and 1.0. + This has no effect if playback is not enabled. This might not work depending on the underlying input format and protocol. @param f_pos: the position. ''' @@ -2968,13 +2925,13 @@ class MediaPlayer(_Ctype): def video_get_track(self): '''Get current video track. - @return: the video track (int) or -1 if none. + @return: the video track ID (int) or -1 if no active input. ''' return libvlc_video_get_track(self) def video_set_track(self, i_track): '''Set video track. - @param i_track: the track (int). + @param i_track: the track ID (i_id field from track description). @return: 0 on success, -1 if out of range. ''' return libvlc_video_set_track(self, i_track) @@ -3084,33 +3041,30 @@ class MediaPlayer(_Ctype): return libvlc_video_set_adjust_float(self, option, value) def audio_output_set(self, psz_name): - '''Set the audio output. - Change will be applied after stop and play. + '''Sets the audio output. + @note: Any change will take be effect only after playback is stopped and + restarted. Audio output cannot be changed while playing. @param psz_name: name of audio output, use psz_name of See L{AudioOutput}. @return: 0 if function succeded, -1 on error. ''' return libvlc_audio_output_set(self, psz_name) def audio_output_device_set(self, psz_audio_output, psz_device_id): - '''Set audio output device. Changes are only effective after stop and play. + '''Configures an explicit audio output device for a given audio output plugin. + A list of possible devices can be obtained with + L{audio_output_device_list_get}(). + @note: This function does not select the specified audio output plugin. + L{audio_output_set}() is used for that purpose. + @warning: The syntax for the device parameter depends on the audio output. + This is not portable. Only use this function if you know what you are doing. + Some audio outputs do not support this function (e.g. PulseAudio, WASAPI). + Some audio outputs require further parameters (e.g. ALSA: channels map). @param psz_audio_output: - name of audio output, See L{AudioOutput}. @param psz_device_id: device. + @return: Nothing. Errors are ignored. ''' return libvlc_audio_output_device_set(self, psz_audio_output, psz_device_id) - def audio_output_get_device_type(self): - '''Get current audio device type. Device type describes something like - character of output sound - stereo sound, 2.1, 5.1 etc. - @return: the audio devices type See libvlc_audio_output_device_types_t. - ''' - return libvlc_audio_output_get_device_type(self) - - def audio_output_set_device_type(self, device_type): - '''Set current audio device type. - @param device_type: the audio device type, - ''' - return libvlc_audio_output_set_device_type(self, device_type) - def audio_toggle_mute(self): '''Toggle mute status. ''' @@ -3118,13 +3072,13 @@ class MediaPlayer(_Ctype): def audio_get_mute(self): '''Get current mute status. - @return: the mute status (boolean) \libvlc_return_bool. + @return: the mute status (boolean) if defined, -1 if undefined/unapplicable. ''' return libvlc_audio_get_mute(self) def audio_set_mute(self, status): '''Set mute status. - @param status: If status is true then mute, otherwise unmute. + @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. ''' return libvlc_audio_set_mute(self, status) @@ -3149,13 +3103,13 @@ class MediaPlayer(_Ctype): def audio_get_track(self): '''Get current audio track. - @return: the audio track (int), or -1 if none. + @return: the audio track ID or -1 if no active input. ''' return libvlc_audio_get_track(self) def audio_set_track(self, i_track): '''Set current audio track. - @param i_track: the track (int). + @param i_track: the track ID (i_id field from track description). @return: 0 on success, -1 on error. ''' return libvlc_audio_set_track(self, i_track) @@ -3397,112 +3351,6 @@ def libvlc_log_unsubscribe(sub): None, ctypes.c_void_p) return f(sub) -def libvlc_get_log_verbosity(p_instance): - '''Always returns minus one. - This function is only provided for backward compatibility. - @param p_instance: ignored. - @return: always -1. - ''' - f = _Cfunctions.get('libvlc_get_log_verbosity', None) or \ - _Cfunction('libvlc_get_log_verbosity', ((1,),), None, - ctypes.c_uint, Instance) - return f(p_instance) - -def libvlc_set_log_verbosity(p_instance, level): - '''This function does nothing. - It is only provided for backward compatibility. - @param p_instance: ignored. - @param level: ignored. - ''' - f = _Cfunctions.get('libvlc_set_log_verbosity', None) or \ - _Cfunction('libvlc_set_log_verbosity', ((1,), (1,),), None, - None, Instance, ctypes.c_uint) - return f(p_instance, level) - -def libvlc_log_open(p_instance): - '''This function does nothing useful. - It is only provided for backward compatibility. - @param p_instance: libvlc instance. - @return: an unique pointer or NULL on error. - ''' - f = _Cfunctions.get('libvlc_log_open', None) or \ - _Cfunction('libvlc_log_open', ((1,),), class_result(Log), - ctypes.c_void_p, Instance) - return f(p_instance) - -def libvlc_log_close(p_log): - '''Frees memory allocated by L{libvlc_log_open}(). - @param p_log: libvlc log instance or NULL. - ''' - f = _Cfunctions.get('libvlc_log_close', None) or \ - _Cfunction('libvlc_log_close', ((1,),), None, - None, Log) - return f(p_log) - -def libvlc_log_count(p_log): - '''Always returns zero. - This function is only provided for backward compatibility. - @param p_log: ignored. - @return: always zero. - ''' - f = _Cfunctions.get('libvlc_log_count', None) or \ - _Cfunction('libvlc_log_count', ((1,),), None, - ctypes.c_uint, Log) - return f(p_log) - -def libvlc_log_clear(p_log): - '''This function does nothing. - It is only provided for backward compatibility. - @param p_log: ignored. - ''' - f = _Cfunctions.get('libvlc_log_clear', None) or \ - _Cfunction('libvlc_log_clear', ((1,),), None, - None, Log) - return f(p_log) - -def libvlc_log_get_iterator(p_log): - '''This function does nothing useful. - It is only provided for backward compatibility. - @param p_log: ignored. - @return: an unique pointer or NULL on error or if the parameter was NULL. - ''' - f = _Cfunctions.get('libvlc_log_get_iterator', None) or \ - _Cfunction('libvlc_log_get_iterator', ((1,),), class_result(LogIterator), - ctypes.c_void_p, Log) - return f(p_log) - -def libvlc_log_iterator_free(p_iter): - '''Frees memory allocated by L{libvlc_log_get_iterator}(). - @param p_iter: libvlc log iterator or NULL. - ''' - f = _Cfunctions.get('libvlc_log_iterator_free', None) or \ - _Cfunction('libvlc_log_iterator_free', ((1,),), None, - None, LogIterator) - return f(p_iter) - -def libvlc_log_iterator_has_next(p_iter): - '''Always returns zero. - This function is only provided for backward compatibility. - @param p_iter: ignored. - @return: always zero. - ''' - f = _Cfunctions.get('libvlc_log_iterator_has_next', None) or \ - _Cfunction('libvlc_log_iterator_has_next', ((1,),), None, - ctypes.c_int, LogIterator) - return f(p_iter) - -def libvlc_log_iterator_next(p_iter, p_buffer): - '''Always returns NULL. - This function is only provided for backward compatibility. - @param p_iter: libvlc log iterator or NULL. - @param p_buffer: ignored. - @return: always NULL. - ''' - f = _Cfunctions.get('libvlc_log_iterator_next', None) or \ - _Cfunction('libvlc_log_iterator_next', ((1,), (1,),), None, - ctypes.POINTER(LogMessage), LogIterator, ctypes.POINTER(LogMessage)) - return f(p_iter, p_buffer) - def libvlc_module_description_list_release(p_list): '''Release a list of module descriptions. @param p_list: the list to be released. @@ -3615,11 +3463,13 @@ def libvlc_media_add_option(p_md, ppsz_options): This option will be used to determine how the media_player will read the media. This allows to use VLC's advanced reading/streaming options on a per-media basis. - The options are detailed in vlc --long-help, for instance - "--sout-all". Note that all options are not usable on medias: - specifically, due to architectural issues, video-related options - such as text renderer options cannot be set on a single media. They - must be set on the whole libvlc instance instead. + @note: The options are listed in 'vlc --long-help' from the command line, + e.g. "-sout-all". Keep in mind that available options and their semantics + vary across LibVLC versions and builds. + @warning: Not all options affects L{Media} objects: + Specifically, due to architectural issues most audio and video options, + such as text renderer options, have no effects on an individual media. + These options must be set through L{libvlc_new}() instead. @param p_md: the media descriptor. @param ppsz_options: the options (as a string). ''' @@ -3756,6 +3606,18 @@ def libvlc_media_get_stats(p_md, p_stats): ctypes.c_int, Media, ctypes.POINTER(MediaStats)) return f(p_md, p_stats) +def libvlc_media_subitems(p_md): + '''Get subitems of media descriptor object. This will increment + the reference count of supplied media descriptor object. Use + L{libvlc_media_list_release}() to decrement the reference counting. + @param p_md: media descriptor object. + @return: list of media descriptor subitems or NULL. + ''' + f = _Cfunctions.get('libvlc_media_subitems', None) or \ + _Cfunction('libvlc_media_subitems', ((1,),), class_result(MediaList), + ctypes.c_void_p, Media) + return f(p_md) + def libvlc_media_event_manager(p_md): '''Get event manager from media descriptor object. NOTE: this function doesn't increment reference counting. @@ -3783,7 +3645,7 @@ def libvlc_media_parse(p_md): The method is synchronous. See L{libvlc_media_parse_async} See L{libvlc_media_get_meta} - See L{libvlc_media_get_tracks_info}. + See libvlc_media_get_tracks_info. @param p_md: media descriptor object. ''' f = _Cfunctions.get('libvlc_media_parse', None) or \ @@ -3801,7 +3663,7 @@ def libvlc_media_parse_async(p_md): See L{libvlc_media_parse} See libvlc_MediaParsedChanged See L{libvlc_media_get_meta} - See L{libvlc_media_get_tracks_info}. + See libvlc_media_get_tracks_info. @param p_md: media descriptor object. ''' f = _Cfunctions.get('libvlc_media_parse_async', None) or \ @@ -3843,19 +3705,31 @@ def libvlc_media_get_user_data(p_md): ctypes.c_void_p, Media) return f(p_md) -def libvlc_media_get_tracks_info(p_md): +def libvlc_media_tracks_get(p_md, tracks): '''Get media descriptor's elementary streams description Note, you need to call L{libvlc_media_parse}() or play the media at least once before calling this function. Not doing this will result in an empty array. @param p_md: media descriptor object. - @param tracks: address to store an allocated array of Elementary Streams descriptions (must be freed by the caller) [OUT]. - @return: the number of Elementary Streams. + @param tracks: address to store an allocated array of Elementary Streams descriptions (must be freed with L{libvlc_media_tracks_release}. + @return: the number of Elementary Streams (zero on error). + @version: LibVLC 2.1.0 and later. ''' - f = _Cfunctions.get('libvlc_media_get_tracks_info', None) or \ - _Cfunction('libvlc_media_get_tracks_info', ((1,), (2,),), None, - ctypes.c_int, Media, ctypes.POINTER(ctypes.c_void_p)) - return f(p_md) + f = _Cfunctions.get('libvlc_media_tracks_get', None) or \ + _Cfunction('libvlc_media_tracks_get', ((1,), (1,),), None, + ctypes.c_uint, Media, ctypes.POINTER(ctypes.POINTER(MediaTrack))) + return f(p_md, tracks) + +def libvlc_media_tracks_release(p_tracks, i_count): + '''Release media descriptor's elementary streams description array. + @param p_tracks: tracks info array to release. + @param i_count: number of elements in the array. + @version: LibVLC 2.1.0 and later. + ''' + f = _Cfunctions.get('libvlc_media_tracks_release', None) or \ + _Cfunction('libvlc_media_tracks_release', ((1,), (1,),), None, + None, ctypes.POINTER(MediaTrack), ctypes.c_uint) + return f(p_tracks, i_count) def libvlc_media_discoverer_new_from_name(p_inst, psz_name): '''Discover media service by name. @@ -4208,7 +4082,7 @@ def libvlc_media_list_player_play(p_mlp): return f(p_mlp) def libvlc_media_list_player_pause(p_mlp): - '''Pause media list. + '''Toggle pause (or resume) media list. @param p_mlp: media list player instance. ''' f = _Cfunctions.get('libvlc_media_list_player_pause', None) or \ @@ -4673,7 +4547,7 @@ def libvlc_media_player_set_time(p_mi, i_time): return f(p_mi, i_time) def libvlc_media_player_get_position(p_mi): - '''Get movie position. + '''Get movie position as percentage between 0.0 and 1.0. @param p_mi: the Media Player. @return: movie position, or -1. in case of error. ''' @@ -4683,7 +4557,8 @@ def libvlc_media_player_get_position(p_mi): return f(p_mi) def libvlc_media_player_set_position(p_mi, f_pos): - '''Set movie position. This has no effect if playback is not enabled. + '''Set movie position as percentage between 0.0 and 1.0. + This has no effect if playback is not enabled. This might not work depending on the underlying input format and protocol. @param p_mi: the Media Player. @param f_pos: the position. @@ -4894,14 +4769,6 @@ def libvlc_track_description_list_release(p_track_description): None, ctypes.POINTER(TrackDescription)) return f(p_track_description) -def libvlc_track_description_release(p_track_description): - '''\deprecated Use L{libvlc_track_description_list_release} instead. - ''' - f = _Cfunctions.get('libvlc_track_description_release', None) or \ - _Cfunction('libvlc_track_description_release', ((1,),), None, - None, ctypes.POINTER(TrackDescription)) - return f(p_track_description) - def libvlc_toggle_fullscreen(p_mi): '''Toggle fullscreen status on non-embedded video outputs. @warning: The same limitations applies to this function @@ -5219,7 +5086,7 @@ def libvlc_video_get_track_description(p_mi): def libvlc_video_get_track(p_mi): '''Get current video track. @param p_mi: media player. - @return: the video track (int) or -1 if none. + @return: the video track ID (int) or -1 if no active input. ''' f = _Cfunctions.get('libvlc_video_get_track', None) or \ _Cfunction('libvlc_video_get_track', ((1,),), None, @@ -5229,7 +5096,7 @@ def libvlc_video_get_track(p_mi): def libvlc_video_set_track(p_mi, i_track): '''Set video track. @param p_mi: media player. - @param i_track: the track (int). + @param i_track: the track ID (i_id field from track description). @return: 0 on success, -1 if out of range. ''' f = _Cfunctions.get('libvlc_video_set_track', None) or \ @@ -5394,7 +5261,7 @@ def libvlc_video_set_adjust_float(p_mi, option, value): return f(p_mi, option, value) def libvlc_audio_output_list_get(p_instance): - '''Get the list of available audio outputs. + '''Gets the list of available audio outputs. @param p_instance: libvlc instance. @return: list of available audio outputs. It must be freed it with In case of error, NULL is returned. ''' @@ -5404,7 +5271,7 @@ def libvlc_audio_output_list_get(p_instance): return f(p_instance) def libvlc_audio_output_list_release(p_list): - '''Free the list of available audio outputs. + '''Frees the list of available audio outputs. @param p_list: list with audio outputs for release. ''' f = _Cfunctions.get('libvlc_audio_output_list_release', None) or \ @@ -5413,8 +5280,9 @@ def libvlc_audio_output_list_release(p_list): return f(p_list) def libvlc_audio_output_set(p_mi, psz_name): - '''Set the audio output. - Change will be applied after stop and play. + '''Sets the audio output. + @note: Any change will take be effect only after playback is stopped and + restarted. Audio output cannot be changed while playing. @param p_mi: media player. @param psz_name: name of audio output, use psz_name of See L{AudioOutput}. @return: 0 if function succeded, -1 on error. @@ -5424,77 +5292,59 @@ def libvlc_audio_output_set(p_mi, psz_name): ctypes.c_int, MediaPlayer, ctypes.c_char_p) return f(p_mi, psz_name) -def libvlc_audio_output_device_count(p_instance, psz_audio_output): - '''Get count of devices for audio output, these devices are hardware oriented - like analor or digital output of sound card. +def libvlc_audio_output_device_list_get(p_instance, aout): + '''Gets a list of audio output devices for a given audio output. + See L{libvlc_audio_output_device_set}(). + @note: Not all audio outputs support this. In particular, an empty (NULL) + list of devices does B{not} imply that the specified audio output does + not work. + @note: The list might not be exhaustive. + @warning: Some audio output devices in the list might not actually work in + some circumstances. By default, it is recommended to not specify any + explicit audio device. @param p_instance: libvlc instance. - @param psz_audio_output: - name of audio output, See L{AudioOutput}. - @return: number of devices. + @param psz_aout: audio output name (as returned by L{libvlc_audio_output_list_get}()). + @return: A NULL-terminated linked list of potential audio output devices. It must be freed it with L{libvlc_audio_output_device_list_release}(). + @version: LibVLC 2.1.0 or later. ''' - f = _Cfunctions.get('libvlc_audio_output_device_count', None) or \ - _Cfunction('libvlc_audio_output_device_count', ((1,), (1,),), None, - ctypes.c_int, Instance, ctypes.c_char_p) - return f(p_instance, psz_audio_output) + f = _Cfunctions.get('libvlc_audio_output_device_list_get', None) or \ + _Cfunction('libvlc_audio_output_device_list_get', ((1,), (1,),), None, + ctypes.POINTER(AudioOutputDevice), Instance, ctypes.c_char_p) + return f(p_instance, aout) -def libvlc_audio_output_device_longname(p_instance, psz_audio_output, i_device): - '''Get long name of device, if not available short name given. - @param p_instance: libvlc instance. - @param psz_audio_output: - name of audio output, See L{AudioOutput}. - @param i_device: device index. - @return: long name of device. +def libvlc_audio_output_device_list_release(p_list): + '''Frees a list of available audio output devices. + @param p_list: list with audio outputs for release. + @version: LibVLC 2.1.0 or later. ''' - f = _Cfunctions.get('libvlc_audio_output_device_longname', None) or \ - _Cfunction('libvlc_audio_output_device_longname', ((1,), (1,), (1,),), string_result, - ctypes.c_void_p, Instance, ctypes.c_char_p, ctypes.c_int) - return f(p_instance, psz_audio_output, i_device) - -def libvlc_audio_output_device_id(p_instance, psz_audio_output, i_device): - '''Get id name of device. - @param p_instance: libvlc instance. - @param psz_audio_output: - name of audio output, See L{AudioOutput}. - @param i_device: device index. - @return: id name of device, use for setting device, need to be free after use. - ''' - f = _Cfunctions.get('libvlc_audio_output_device_id', None) or \ - _Cfunction('libvlc_audio_output_device_id', ((1,), (1,), (1,),), string_result, - ctypes.c_void_p, Instance, ctypes.c_char_p, ctypes.c_int) - return f(p_instance, psz_audio_output, i_device) + f = _Cfunctions.get('libvlc_audio_output_device_list_release', None) or \ + _Cfunction('libvlc_audio_output_device_list_release', ((1,),), None, + None, ctypes.POINTER(AudioOutputDevice)) + return f(p_list) def libvlc_audio_output_device_set(p_mi, psz_audio_output, psz_device_id): - '''Set audio output device. Changes are only effective after stop and play. + '''Configures an explicit audio output device for a given audio output plugin. + A list of possible devices can be obtained with + L{libvlc_audio_output_device_list_get}(). + @note: This function does not select the specified audio output plugin. + L{libvlc_audio_output_set}() is used for that purpose. + @warning: The syntax for the device parameter depends on the audio output. + This is not portable. Only use this function if you know what you are doing. + Some audio outputs do not support this function (e.g. PulseAudio, WASAPI). + Some audio outputs require further parameters (e.g. ALSA: channels map). @param p_mi: media player. @param psz_audio_output: - name of audio output, See L{AudioOutput}. @param psz_device_id: device. + @return: Nothing. Errors are ignored. ''' f = _Cfunctions.get('libvlc_audio_output_device_set', None) or \ _Cfunction('libvlc_audio_output_device_set', ((1,), (1,), (1,),), None, None, MediaPlayer, ctypes.c_char_p, ctypes.c_char_p) return f(p_mi, psz_audio_output, psz_device_id) -def libvlc_audio_output_get_device_type(p_mi): - '''Get current audio device type. Device type describes something like - character of output sound - stereo sound, 2.1, 5.1 etc. - @param p_mi: media player. - @return: the audio devices type See libvlc_audio_output_device_types_t. - ''' - f = _Cfunctions.get('libvlc_audio_output_get_device_type', None) or \ - _Cfunction('libvlc_audio_output_get_device_type', ((1,),), None, - ctypes.c_int, MediaPlayer) - return f(p_mi) - -def libvlc_audio_output_set_device_type(p_mi, device_type): - '''Set current audio device type. - @param p_mi: vlc instance. - @param device_type: the audio device type, - ''' - f = _Cfunctions.get('libvlc_audio_output_set_device_type', None) or \ - _Cfunction('libvlc_audio_output_set_device_type', ((1,), (1,),), None, - None, MediaPlayer, ctypes.c_int) - return f(p_mi, device_type) - def libvlc_audio_toggle_mute(p_mi): '''Toggle mute status. - @param p_mi: media player. + @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}(). ''' f = _Cfunctions.get('libvlc_audio_toggle_mute', None) or \ _Cfunction('libvlc_audio_toggle_mute', ((1,),), None, @@ -5504,7 +5354,7 @@ def libvlc_audio_toggle_mute(p_mi): def libvlc_audio_get_mute(p_mi): '''Get current mute status. @param p_mi: media player. - @return: the mute status (boolean) \libvlc_return_bool. + @return: the mute status (boolean) if defined, -1 if undefined/unapplicable. ''' f = _Cfunctions.get('libvlc_audio_get_mute', None) or \ _Cfunction('libvlc_audio_get_mute', ((1,),), None, @@ -5514,7 +5364,7 @@ def libvlc_audio_get_mute(p_mi): def libvlc_audio_set_mute(p_mi, status): '''Set mute status. @param p_mi: media player. - @param status: If status is true then mute, otherwise unmute. + @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. ''' f = _Cfunctions.get('libvlc_audio_set_mute', None) or \ _Cfunction('libvlc_audio_set_mute', ((1,), (1,),), None, @@ -5565,7 +5415,7 @@ def libvlc_audio_get_track_description(p_mi): def libvlc_audio_get_track(p_mi): '''Get current audio track. @param p_mi: media player. - @return: the audio track (int), or -1 if none. + @return: the audio track ID or -1 if no active input. ''' f = _Cfunctions.get('libvlc_audio_get_track', None) or \ _Cfunction('libvlc_audio_get_track', ((1,),), None, @@ -5575,7 +5425,7 @@ def libvlc_audio_get_track(p_mi): def libvlc_audio_set_track(p_mi, i_track): '''Set current audio track. @param p_mi: media player. - @param i_track: the track (int). + @param i_track: the track ID (i_id field from track description). @return: 0 on success, -1 on error. ''' f = _Cfunctions.get('libvlc_audio_set_track', None) or \ @@ -5933,11 +5783,14 @@ def libvlc_vlm_get_event_manager(p_instance): return f(p_instance) -# 2 function(s) blacklisted: +# 4 function(s) blacklisted: +# libvlc_audio_output_get_device_type +# libvlc_audio_output_set_device_type # libvlc_printerr # libvlc_set_exit_handler -# 17 function(s) not wrapped as methods: +# 18 function(s) not wrapped as methods: +# libvlc_audio_output_device_list_release # libvlc_audio_output_list_release # libvlc_clearerr # libvlc_clock @@ -5950,10 +5803,10 @@ def libvlc_vlm_get_event_manager(p_instance): # libvlc_log_subscribe # libvlc_log_subscribe_file # libvlc_log_unsubscribe +# libvlc_media_tracks_release # libvlc_module_description_list_release # libvlc_new # libvlc_track_description_list_release -# libvlc_track_description_release # libvlc_vprinterr # Start of footer.py # @@ -6075,9 +5928,9 @@ if __name__ == '__main__': print('Error: %s file not readable' % movie) sys.exit(1) - instance = Instance() + instance = Instance("--sub-source marq") try: - media = instance.media_new(movie, 'sub-filter=marq') # load marqee option + media = instance.media_new(movie) except NameError: print('NameError: %s (%s vs LibVLC %s)' % (sys.exc_info()[1], __version__, @@ -6087,13 +5940,12 @@ if __name__ == '__main__': player.set_media(media) player.play() - # Some marquee examples. Marquee requires 'sub-filter=marq' in the - # media_new() call above. See also the Media.add_options method - # and + # Some marquee examples. Marquee requires '--sub-source marq' in the + # Instance() call above. See player.video_set_marquee_int(VideoMarqueeOption.Enable, 1) player.video_set_marquee_int(VideoMarqueeOption.Size, 24) # pixels player.video_set_marquee_int(VideoMarqueeOption.Position, Position.Bottom) - if True: # only one marquee can be specified + if False: # only one marquee can be specified player.video_set_marquee_int(VideoMarqueeOption.Timeout, 5000) # millisec, 0==forever t = media.get_mrl() # movie else: # update marquee text periodically