               Gst-Python 0.8.0: A Python Interface to GStreamer

  David I. Lehn

   <[1]dlehn@users.sourceforge.net>

   Copyright (c) 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.

   [2]http://gstreamer.freedesktop.org/bindings/python.html

   ---------------------------------------------------------------------------

   Table of Contents

   [3]1. About

   [4]2. News

   [5]3. Installation

                [6]3.1. Requirements

                [7]3.2. Building and Installation

                [8]3.3. Using

   [9]4. Programming

                [10]4.1. General API

                [11]4.2. Divergence From C API

                [12]4.3. Examples

                [13]4.4. Threads

                [14]4.5. Pipeline Iteration

                [15]4.6. Python Elements

   [16]5. Bugs

   [17]6. ToDo

   [18]7. Authors

                [19]7.1. Maintainer

                [20]7.2. Contributions

                [21]7.3. GStreamer Team

1. About

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

2. News

  2.1. 2004-03-17 - 0.7.90 - Johan Dahlin <[24]johan@gnome.org>

     o Updated for 0.8.0

  2.2. 2003-07-10 - 0.1.0 - David I. Lehn <[25]dlehn@users.sourceforge.net>

     o First release

     o Supports only GStreamer 0.6.x (0.7.x support requires a few changes)

3. Installation

  3.1. Requirements

     o Python 2.2 ([26]http://www.python.org/)

     o GStreamer 0.6.x (except 0.6.1) ([27]http://www.gstreamer.net/)

     o PyGTK 1.99.14 ([28]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
   [29]http://gstreamer.freedesktop.org/documentation/ 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 [30]Python Elements. A few others remain that return
   GList* or return values in their parameters. These have been wrapped as
   needed. Please file a [31]bug if you need one of the unwrapped functions.

   API changes:

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

     o Special [32]pipeline iteration support through the following
       functions:

          o add_iterate_bin(bin) -> id: used to iterate a bin with a C idle
            loop callback instead of a Python callback.

          o remove_iterate_bin(id): used to remove the add_iterate_bin idle
            loop callback id.

          o iterate_bin_all(bin): releases locks, calls gst_bin_iterate until
            it returns 0, reacquires locks and completes

     o [33]Python Elements support through the following currently horribly
       inefficient functions:

          o Buffer.get_data() -> string: converts buffer data to a string and
            returns it.

          o 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 [34]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.

     o Bin.iterate() in Python from the gtk idle loop

     o gst_bin_iterate() in C from gtk idle loop

     o Bin.iterate() in a Python loop

     o 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
   ([35]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

     o handle more of the functions that need manual wrapping code

     o add check that pygtk built with --enable-thread

     o improve Python gstreamer.Element creation

          o perhaps drop _set_foo_function() calls in favor of object methods

          o sane buffer handling with buffer type or Numeric?

     o docs

          o API ref

          o manual

          o tutorial

     o more examples

     o convert build system to distutils

     o wrap other GStreamer helper libs

     o add some standard widgets

          o gtk video widget (similar to widget gst-player is using)

     o testsuite

7. Authors

   Please feel free to contact the developers. They hang out on IRC
   ([36]http://gstreamer.freedesktop.org/dev/) and the mailing lists
   ([37]http://gstreamer.freedesktop.org/lists/).

  7.1. Maintainer

     o David I. Lehn <[38]dlehn@users.sourceforge.net>

  7.2. Contributions

   Patches, suggestions, and other help:

     o Kenichi Sato <[39]ksato at users.sourceforge.net>: misc patches

     o Thomas Vander Stichele <[40]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:

     o James Henstridge <[41]james at daa.com.au>

     o Johan Dahlin <[42]jdahlin at telia.com>

     o Matt Wilson <[43]msw at redhat.com>

     o 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!

References

   Visible links
   1. mailto:dlehn@users.sourceforge.net
   2. http://gstreamer.freedesktop.org/bindings/python.html
   3. file:///tmp/xmlto.uc2141/README.proc#about
   4. file:///tmp/xmlto.uc2141/README.proc#news
   5. file:///tmp/xmlto.uc2141/README.proc#installation
   6. file:///tmp/xmlto.uc2141/README.proc#requirements
   7. file:///tmp/xmlto.uc2141/README.proc#building
   8. file:///tmp/xmlto.uc2141/README.proc#using
   9. file:///tmp/xmlto.uc2141/README.proc#programming
  10. file:///tmp/xmlto.uc2141/README.proc#general-api
  11. file:///tmp/xmlto.uc2141/README.proc#divergence-from-c-api
  12. file:///tmp/xmlto.uc2141/README.proc#examples
  13. file:///tmp/xmlto.uc2141/README.proc#threads
  14. file:///tmp/xmlto.uc2141/README.proc#pipeline-iteration
  15. file:///tmp/xmlto.uc2141/README.proc#python-elements
  16. file:///tmp/xmlto.uc2141/README.proc#bugs
  17. file:///tmp/xmlto.uc2141/README.proc#todo
  18. file:///tmp/xmlto.uc2141/README.proc#authors
  19. file:///tmp/xmlto.uc2141/README.proc#maintainer
  20. file:///tmp/xmlto.uc2141/README.proc#contributions
  21. file:///tmp/xmlto.uc2141/README.proc#gstreamer-team
  22. http://www.python.org/
  23. http://www.gstreamer.net/
  24. mailto:johan@gnome.org
  25. mailto:dlehn@users.sourceforge.net
  26. http://www.python.org/
  27. http://www.gstreamer.net/
  28. http://www.daa.com.au/~james/pygtk/
  29. http://gstreamer.freedesktop.org/documentation/
  30. file:///tmp/xmlto.uc2141/README.proc#python-elements
  31. 5.Bugs
	file:///tmp/xmlto.uc2141/README.proc#bugs
  32. 4.5.Pipeline Iteration
	file:///tmp/xmlto.uc2141/README.proc#pipeline-iteration
  33. 4.6.Python Elements
	file:///tmp/xmlto.uc2141/README.proc#python-elements
  34. 5.Bugs
	file:///tmp/xmlto.uc2141/README.proc#bugs
  35. http://bugzilla.gnome.org/
  36. http://gstreamer.freedesktop.org/dev/
  37. http://gstreamer.freedesktop.org/lists/
  38. mailto:dlehn@users.sourceforge.net
  39. mailto:ksato%20at%20users.sourceforge.net
  40. mailto:thomas%20at%20apestaart.org
  41. mailto:james%20at%20daa.com.au
  42. mailto:jdahlin%20at%20telia.com
  43. mailto:msw%20at%20redhat.com
