View source for Old Python bindings

= Python binding documentation =

For a while, there has been a basic python binding for [[Wikipedia:libvlc|libvlc]] (located in <code>vlc/pyvlc</code>), that was used for streaming. A more complete (with a hopefully generic API that can be reused by other players) has been developed, based on the [[MediaControlAPI]]. It can be found in <code>bindings/python</code>.

Sources are browsable from [http://trac.videolan.org/vlc/browser/trunk/bindings/python python binding] and a code sample can be found in [http://liris.cnrs.fr/advene/download.html].

It has been compiled, and is being used, on Linux, Windows and Mac OS X.  If you want to include the python bindings in your build, you must pass --enable-python-bindings (svn version) or --enable-mediacontrol-python-bindings (0.8.6* versions) to ./configure as it is disabled by default.

= Basics =

The vlc python module provides 2 main classes : Object and MediaControl.

'''vlc.Object''' provides a binding to the vlc object architecture. It allows to manipulate variables and configuration options, and explore the object hierarchy. The vlcwrapper.py script, located in the python bindings directory, wraps around the vlc.Object to provide an easier access to variables and objects (as illustrated in the code sample in [http://liris.cnrs.fr/advene/download/]), and combined with a interactive python environment such as [http://ipython.scipy.org/ IPython] offers an interaction framework with VLC (with object navigation, completion...).

'''vlc.MediaControl''' implements the [[MediaControlAPI]].

Methods taking positions as parameters expect a '''vlc.Position''' object, that provides a very flexible way to address absolute or relative positions, in a number of units (milliseconds, frames or bytes). For convenience, the python binding automatically converts integer positions into milliseconds '''vlc.Position''' objects.

Note: as of 0.9.0pre (still in svn), the vlc.Object binding has been moved to its own module called vlcinternal, and it '''must''' be built from a vlc tree, since it provides access to internal features of vlc. The vlc module holds the vlc.MediaControl object as well as bindings to the new libvlc API (vlc.Instance, vlc.Input), and can be built outside of the vlc tree, provided that the appropriate headers and libraries are present.

= Tips and tricks =

== Building notes ==

* on 0.8.6(a), the --enable-mediacontrol-python-bindings option is not compatible with --enable-libtool. If you need libtool support, please use the svn version.

== Python specificities ==

The python bindings provide a binding for the [[MediaControlAPI]], with some variations :

* the methods taking a ''vlc.Position'' parameter also accept an integer, which will then be converted to a relative position in milliseconds (vlc.MediaTime)
* the start, stop, pause and resume method position parameter is optional. If omitted, it will default to a 0-relative position.
* RGBPicture (returned by snapshot) and StreamInformation (returned by get_stream_information) are not objects with attributes, but instead dictionaries.

== Snapshot support ==

In the current svn revision, we use the core snapshot functionality of vlc, which is simpler to setup (no additional module, see below) and directly returns PNG, but less precise.

Prior to revision 13881, in order to get snapshot support, you had to activate the snapshot vout module through a clone video filter.  The following code gives a way to achieve this :

  mc=vlc.MediaControl([ "--vout-filter", "clone" ])
  o=VLC.Object(0)
  o.config_set("clone-vout-list", "default,snapshot")
  o.config_set("snapshot-width", 320)
  o.config_set("snapshot-height", 200)

Note that all config options could have been given on the command line, but this illustrates the use of the vlc.Object API.

Advantages of the old (filter-based) approach:
* the snapshot vout module holds a cache of reduced-size snapshots, that allow to take into account the reaction time of the user (around 200ms) and also to precisely select the more appropriate snapshot from the cache.
* the builtin snapshot functionality is oriented towards interactive use (hotkey activation, saving into a file) and should be revamped to take into accound a more programmatic use [Note: this is now implemented, cf src/video_output/vout_intf.c, and look for "object-id"]

== Win32 initialization ==

If the vlc module was not compiled with the exact same prefix as the VLC installation (e.g. c:\\Program Files\\Videolan), then it cannot find itself the installation directory (stored in the registry Software\VideoLAN\VLC\InstallDir), and the MediaControl instanciation will fail with a message like "Cannot find interface plugins". 

The workaround consists in changing directory to the VLC installation directory before instanciating the MediaControl object. 

    def get_registry_value (self, subkey, name):
        import _winreg
        value = None
        for hkey in _winreg.HKEY_LOCAL_MACHINE, _winreg.HKEY_CURRENT_USER:
            try:
                reg = _winreg.OpenKey(hkey, subkey)
                value, type_id = _winreg.QueryValueEx(reg, name)
                _winreg.CloseKey(reg)
            except _winreg.error:
                pass
        return value
    
    vlcpath=get_registry_value('Software\\VideoLAN\\VLC','InstallDir')
    if vlcpath is None:
        print "Cannot locate VLC installation directory"
    else:
        os.chdir(vlcpath)
        mc=vlc.MediaControl()

= Source code =
{{file|bindings/python|bindings}}
[[Category:Bindings]]