= Python bindings =

You can find two versions of python bindings: an old one (see [[Old Python bindings]]), hand-written C-module, and a new one, which is ctypes-based and automatically generated.
The old version of the bindings is now deprecated and will be removed in some future version.

== Features ==

The new module features :
* a complete cover of the libvlc API, since it is automatically generated from the include files.
* no compilation hassle: the generated module is pure python.
* no versioning hassle: the same module works with multiple VLC versions.
* a [http://www.advene.org/download/python-ctypes/doc/ complete documentation].

== Download ==

You can download the [http://git.videolan.org/?p=vlc/bindings/python.git;a=tree;f=generated;b=HEAD vlc.py] module from the Git repository. It only depends on ctypes (standard module in python >= 2.5). Put the module in some place accessible by python (either next to your application, or in a directory from sys.path).

Alternatively, you can generate it by yourself using the generate.py program and accompanying files in the vlc source tree (see [http://git.videolan.org/?p=vlc/bindings/python.git;a=summary]).

== Usage ==

The vlc.py module is also a runnable example player application (see code at the end of the module, starting from the line "if __name__ == '__main__'). A helper module [http://git.videolan.org/?p=vlc.git;a=blob;f=bindings/python-ctypes/vlcwidget.py;hb=HEAD vlcwidget.py] provides a pygtk VLCWidget() to ease integration.

== FAQ ==

=== Win32 initalization ===

If the vlc modules are not installed in their standard location (e.g. c:\\Program Files\\Videolan on Windows, or /usr/lib/vlc on linux), the VLC module cannot find them.

When instanciating vlc.Instance() with no parameter, it tries to guess the location of the modules. However, if you pass any argument to vlc.Instance(), you will need to supply the appropriate "--plugin-path=/path/to/the/modules" yourself.

2009-09-04T13:57:25Z

OlivierAubert: moved Python bindings to Old Python bindings: There are new python bindings (ctypes-based). Preserve this information for the moment, as the old bindings are still used.

= 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/bindings/python python binding] and a code sample can be found in the sources (file [http://trac.videolan.org/vlc/browser/bindings/python/vlcwidget.py vlcwidget.py]).

It has been compiled, and is being used, on Linux, Windows and Mac OS X.

= Compile HOWTO =

Only for < 0.9.0 versions: 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.

For >= 0.9.0 versions, python bindings cannot be compiled at the same time as the main VLC tree. They can (and event must) be compiled from a compiled VLC, provided that appropriate headers and libraries (libvlc.so/.dll) are available.

== Linux/Debian ==

On Debian:
* install the libvlc2-dev package
* Get the python bindings sources from the Git repository :
* in the python directory, launch
python setup.py build
The module will be built in
build/lib.linux-i686-2.5
* install the module through (as root)
python setup.py install
or simply copy the vlc.so file to some appropriate directory.

== Windows ==

* Get and install a nighty-built package from http://nightlies.videolan.org/build/windows/
* Get and extract the corresponding sources from http://nightlies.videolan.org/build/source/
* Create a .libs subdirectory in vlc/src
* Copy the libvlc.dll file from c:\Program Files\VideoLAN\VLC into src/.libs
* Go into the vlc/bindings/python directory and run
python setup.py build --compiler=mingw32
You should get a vlc.pyd (or vlc.dll) file in the build/ subdirectory.

= Basics =

The vlc python module provides 4 main classes : MediaControl, Instance, MediaPlayer and Media.

'''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.

'''vlc.Instance''', '''vlc.MediaPlayer''' and '''vlc.Media''' match the new [[ExternalAPI|LibVLC API]]. Refer (for now) to the docstrings provided by the python objects to get their usage.

= 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 --clone-vout-list default,snapshot --snapshot-width 320 --snapshot-height 200".split())

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.

== 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, since VLC will look for its plugins in the current directory. Another way is to pass the correct --plugin-path option.

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]]

2005-12-31T17:33:57Z

OlivierAubert: /* Python binding documentation */

= Python binding documentation =

For a while, there has been a basic python binding for 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 developped, based on the [[MediaControlAPI]]. It can be found in <code>vlc/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/].

It has been compiled, and is being used, on Linux and Windows. It compiles and run on Mac OS X, but embedded vout support is under development in VLC.

= Basics =

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

'''vlc.Object''' provides a binding to the vlc object architecture. It allows to manipulate variables and configuration options, and explore the object hierrarchy. The vlcdebug.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/]).

'''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.

= Tips and tricks =

== 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 order to get snapshot support, you have 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.

There is a snapshot functionality built in the vlc core, associated to a hotkey. The MediaControlAPI could (should ?) use it, but

* it did not exist at the time the extension was developped
* 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
* 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 select the more appropriate snapshot from the cache.

== 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()