
Gst-Python 0.1.0: A Python Interface to GStreamer

David I. Lehn

   Copyright  2003 David I. Lehn

   July 10, 2003
   Revision History
   Revision 0.1.0 2003-07-10 dil
   Initial version.

   Abstract

   Introductory information for the GStreamer Python bindings.

   http://www.gstreamer.net/bindings/python/
     _________________________________________________________

   Table of Contents

   1. About
   2. News

   3. Installation

        3.1. Requirements
        3.2. Building and Installation
        3.3. Using

   4. Programming

        4.1. General API
        4.2. Divergence From C API
        4.3. Examples
        4.4. Threads
        4.5. Pipeline Iteration
        4.6. Python Elements

   5. Bugs
   6. ToDo
   7. Authors

        7.1. Maintainer
        7.2. Contributions
        7.3. GStreamer Team

1. About

   gst-python: the Python bindings for the GStreamer project.
   These bindings provide access to almost all of the GStreamer C
   API through an object oriented Python API.

2. News

2.1. 2003-07-10 - 0.1.0 - David I. Lehn
<dlehn@users.sourceforge.net>

     * First release
     * Supports only GStreamer 0.6.x (0.7.x support requires a
       few changes)

3. Installation

3.1. Requirements

     * Python 2.2 (http://www.python.org/)
     * GStreamer 0.6.x (except 0.6.1) (http://www.gstreamer.net/)
     * PyGTK 1.99.14 (http://www.daa.com.au/~james/pygtk/)

3.2. Building and Installation

   For build and install information please refer to the
   "INSTALL" file. Installation is optional, gst-python can be
   used from the build directory. The quick instructions: build
   and install PyGTK and GStreamer then build gst-python:

 $ ./configure && make

3.3. Using

   You either need to install the package or add the root
   directory to your Python path:

 $ export PYTHONPATH=$PYTHONPATH:`pwd`

   Try running examples:

 $ cd examples/gstreamer/
 $ python cp.py <input file> <output file>
 $ cmp <input file> <output file>
 $ python vorbisplay.py <an Ogg Vorbis file>

4. Programming

4.1. General API

   The gst-python bindings are directly generated from the
   GStreamer headers. Look at the GStreamer documentation at
   http://www.gstreamer.net/docs/ for general API and programming
   issues. In most cases the GStreamer classes and boxed types
   map directly to Python classes. The function-based GObject
   methods also map onto Python methods.

4.2. Divergence From C API

   Due to the nature of C and Python some of the GStreamer API is
   handled slightly different in Python than C. There are a few
   of the GStreamer C functions that are not yet provided in
   gst-python. These are mostly related to creating Python
   Elements. A few others remain that return GList* or return
   values in their parameters. These have been wrapped as needed.
   Please file a bug if you need one of the unwrapped functions.

   API changes:
     * gst_props_entry_get_type is accessed through
       PropsEntry.get_props_type(). This is due to the _get_type
       function extention being normally used for GType access
       and is inaccessable otherwise.
     * Special pipeline iteration support through the following
       functions:
          + add_iterate_bin(bin) -> id: used to iterate a bin
            with a C idle loop callback instead of a Python
            callback.
          + remove_iterate_bin(id): used to remove the
            add_iterate_bin idle loop callback id.
          + iterate_bin_all(bin): releases locks, calls
            gst_bin_iterate until it returns 0, reacquires locks
            and completes
     * Python Elements support through the following currently
       horribly inefficient functions:
          + Buffer.get_data() -> string: converts buffer data to
            a string and returns it.
          + Buffer.set_data(string): sets the buffer data from a
            string.

4.3. Examples

   The best documentation right now are the examples in
   ./examples/gstreamer/. Read them.

4.4. Threads

   Threading is a tricky subject for gst-python. There are a few
   lock you need to be aware of:

4.4.1. GIL

   The CPython interpreter is single threaded. Code execution in
   the interpreter is protected by a Global Interpreter Lock
   (GIL). This means that C code can run in other threads in
   parallel but only one thread will be running Python code at
   any one point. Most of this is handled internally by means of
   locking and unlocking the GIL at appropriate times. Callback
   code and other various code paths between Python and C
   *should* be setup to do proper GIL handling.

   However, it is possible that you may encounter a situation
   where proper locking is not done. This is most likely due to
   calling a wrapper function that follows a sequence like this:
    1. Python calls wrapper function
    2. wrapper function calls C GStreamer function
    3. C GStreamer function calls side effect code
    4. side effect code calls callback
    5. callback tries to acquire Python GIL but it's already
       locked
    6. deadlocked...

   This has been fixed for commonly called functions that have
   side effects which are likely to re-enter the interpreter. It
   just involves lock/unlock around the call to the C gst
   function. But doing it for every function could have
   performance issues and, more importantly, is not an automated
   process.

   Please file a bug if you have problems related to this and
   need other functions to be specially handled.

4.4.2. Gdk Lock

   If you are using PyGTK you will have to deal with Gdk locking.
   Make sure you're holding the Gdk lock while executing Gdk/Gtk
   calls. See PyGTK documentation and FAQ list for more
   information.

4.5. Pipeline Iteration

   There are a number of ways to iterate pipelines.
   ./examples/gstreamer/bps.py is a small test program to measure
   the performance in buffers per second of these various
   techniques. Please see the example for how to use these
   techniques.
     * Bin.iterate() in Python from the gtk idle loop
     * gst_bin_iterate() in C from gtk idle loop
     * Bin.iterate() in a Python loop
     * gst_bin_iterate() in a C loop

   The method you chose depends on your application. The idle
   loop methods are slightly slower yet more flexible. Probably
   useful for interactive GUI applications.

   The basic loop methods are faster but probably more use for
   non-interactive applications. A variation on these loops would
   be to also check for a stop condition which may provide
   performance increase and some level of control.

4.6. Python Elements

   It is possible to write Python subclasses of GstElement. This
   support is very primitive and likely to change. See
   ./examples/gstreamer/rot13.py for an example.

5. Bugs

   Please submit gst-python bugs, patches, or suggestions to
   GNOME Bugzilla (http://bugzilla.gnome.org/). Product:
   GStreamer, Component: gst-python. Or alternatively send a
   message to the gstreamer-devel list or the maintainer. Thank
   you.

6. ToDo

     * handle more of the functions that need manual wrapping
       code
     * add check that pygtk built with --enable-thread
     * improve Python gstreamer.Element creation
          + perhaps drop _set_foo_function() calls in favor of
            object methods
          + sane buffer handling with buffer type or Numeric?
     * docs
          + API ref
          + manual
          + tutorial
     * more examples
     * convert build system to distutils
     * wrap other GStreamer helper libs
     * add some standard widgets
          + gtk video widget (similar to widget gst-player is
            using)
     * testsuite

7. Authors

   Please feel free to contact the developers. They hang out on
   IRC (http://gstreamer.net/dev/) and the mailing lists
   (http://gstreamer.net/contact/lists.php).

7.1. Maintainer

     * David I. Lehn <dlehn@users.sourceforge.net>

7.2. Contributions

   Patches, suggestions, and other help:
     * Kenichi Sato <ksato at users.sourceforge.net>: misc
       patches
     * Thomas Vander Stichele <thomas at apestaart.org>: misc
       patches, build framework patches, Red Hat support

   Much of the framework for gst-python stolen from the excellent
   gtk and gconf bindings by:
     * James Henstridge <james at daa.com.au>
     * Johan Dahlin <jdahlin at telia.com>
     * Matt Wilson <msw at redhat.com>
     * and many more...

7.3. GStreamer Team

   And of course, none of this would be possible without the
   extreme hacker mojo of the whole GStreamer crew!
