2003-02-11 - 0.1.0 released

• first release

General/API

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

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

Examples

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

Threads

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

• 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:

  • Python -> wrapper function
  • wrapper function -> C GStreamer function
  • C GStreamer function -> side effect code
  • side effect code -> callback
  • callback -> tries to acquire Python GIL but it's already locked
  • 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.

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

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.

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.

Maintainer

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

Contributions

Patches, suggestions, and other help:

• Kenichi Sato <ksato@users.sourceforge.net>)

Much of the framework for gst-python stolen from gtk and gconf bindings by:

• James Henstridge <james@daa.com.au>
• Johan Dahlin <jdahlin@telia.com>
• Matt Wilson <msw@redhat.com>
• and many more...

GStreamer

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