<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
  <!ENTITY % local.common.attrib "xml:base CDATA #IMPLIED">
  <!ENTITY % ents SYSTEM "gst-python.ent">
  %ents;
]>

<article id="gst-python">
<articleinfo>
  <title>Gst-Python &version;: A Python Interface to GStreamer</title>
  <publisher><publishername>The GStreamer Development Team</publishername></publisher>
  <pubdate>&pubdate;</pubdate>
  <copyright><year>2003</year><holder>David I. Lehn</holder></copyright>
  <titleabbrev>gst-python</titleabbrev>
  <authorgroup>
    <author>
      <firstname>David</firstname>
      <othername role="mi">I.</othername>
      <surname>Lehn</surname>
      <email>dlehn@users.sourceforge.net</email>
    </author>
  </authorgroup>
  <abstract>
    <para>Introductory information for the GStreamer Python bindings.</para>
    <para><ulink url="http://gstreamer.freedesktop.org/bindings/python.html"/></para>
  </abstract>
  <revhistory>
     <revision>
        <revnumber>0.1.0</revnumber>
        <date>2003-07-10</date>
        <authorinitials>dil</authorinitials>
        <revremark>Initial version.</revremark>
     </revision>
  </revhistory>
</articleinfo>

<!--=====================================================================-->

<section id="about">
<title>About</title>
<para>

<application>gst-python</application>: the <ulink url="http://www.python.org/">Python</ulink> bindings for the <ulink url="http://www.gstreamer.net/">GStreamer</ulink> project.  These bindings provide access to almost all of the GStreamer C API through an object oriented Python API.

</para>
</section>

<!--=====================================================================-->

<xi:include href="NEWS.xml#news" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<!--=====================================================================-->

<section id="installation">
<title>Installation</title>

<!--=================-->

<section id="requirements">
<title>Requirements</title>
<itemizedlist>
<listitem><para>
Python 2.2 (<ulink url="http://www.python.org/"/>)
</para></listitem>
<listitem><para>
GStreamer 0.6.x (<emphasis>except</emphasis> 0.6.1) (<ulink url="http://www.gstreamer.net/"/>)
</para></listitem>
<listitem><para>
PyGTK 1.99.14 (<ulink url="http://www.daa.com.au/~james/pygtk/"/>)
</para></listitem>
</itemizedlist>
</section>

<!--=================-->

<section id="building">
<title>Building and Installation</title>

<para>
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:
</para>

<para>
<screen>
 $ ./configure &amp;&amp; make
</screen>
</para>

</section>

<!--=================-->

<section id="using">
<title>Using</title>
<para>
You either need to install the package or add the root directory to your
Python path:
</para>

<para>
<screen>
 $ export PYTHONPATH=$PYTHONPATH:`pwd`
</screen>
</para>

<para>
Try running examples:
</para>

<para>
<screen>
 $ cd examples/gstreamer/
 $ python cp.py &lt;input file&gt; &lt;output file&gt;
 $ cmp &lt;input file&gt; &lt;output file&gt;
 $ python vorbisplay.py &lt;an Ogg Vorbis file&gt;
</screen>
</para>

</section>

<!--=================-->

</section>

<!--=====================================================================-->

<section id="programming">
<title>Programming</title>

<!--=================-->

<section id="general-api">
<title>General API</title>
<para>

The gst-python bindings are directly generated from the GStreamer headers.  Look at the GStreamer documentation at <ulink url="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.

</para>
</section>

<!--=================-->

<section id="divergence-from-c-api">
<title>Divergence From C API</title>

<para>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 <xref linkend="python-elements" endterm="python-elements.title"/>.  A
few others remain that return GList* or return values in their parameters.
These have been wrapped as needed.  Please file a <link
linkend="bugs">bug</link> if you need one of the unwrapped functions.</para>

<para>API changes:</para>

<itemizedlist>

 <listitem><para><function>gst_props_entry_get_type</function> is accessed
 through <function>PropsEntry.get_props_type</function>().  This is due to the
 <function>_get_type</function> function extention being normally used for
 <function>GType</function> access and is inaccessable
 otherwise.</para></listitem>

 <listitem><para>Special <link linkend="pipeline-iteration">pipeline
 iteration</link> support through the following functions:</para>

  <itemizedlist>

   <listitem><para><function>add_iterate_bin</function>(<parameter
   class="function">bin</parameter>) -&gt; <returnvalue>id</returnvalue>: used
   to iterate a bin with a C idle loop callback instead of a Python
   callback.</para></listitem>

   <listitem><para><function>remove_iterate_bin</function>(<parameter
   class="function">id</parameter>): used to remove the
   <function>add_iterate_bin</function> idle loop callback
   id.</para></listitem>

   <listitem><para><function>iterate_bin_all</function>(<parameter
   class="function">bin</parameter>): releases locks, calls
   <function>gst_bin_iterate</function> until it returns 0, reacquires locks
   and completes</para></listitem>

  </itemizedlist>
 </listitem>

 <listitem><para><link linkend="python-elements">Python Elements</link> support through the following currently horribly inefficient functions:</para>

  <itemizedlist>

   <listitem><para><function>Buffer.get_data</function>() -&gt;
   <returnvalue>string</returnvalue>: converts buffer data to a string and
   returns it.</para></listitem>

   <listitem><para><function>Buffer.set_data</function>(<parameter
   class="function">string</parameter>): sets the buffer data from a
   string.</para></listitem>

  </itemizedlist>
 </listitem>
</itemizedlist>

</section>

<!--=================-->

<section id="examples">
<title>Examples</title>

<para>The best documentation right now are the examples in <filename
class="directory">./examples/gstreamer/</filename>.  Read them.</para>

</section>

<!--=================-->

<section id="threads">
<title>Threads</title>

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

<section id="gil">
<title>GIL</title>

<para>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.</para>
  
<para>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:</para>

<orderedlist>
<listitem><para>Python calls wrapper function</para></listitem>
<listitem><para>wrapper function calls C GStreamer function</para></listitem>
<listitem><para>C GStreamer function calls side effect code</para></listitem>
<listitem><para>side effect code calls callback</para></listitem>
<listitem><para>callback tries to acquire Python GIL but it's already locked</para></listitem>
<listitem><para>deadlocked...</para></listitem>
</orderedlist>

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

<para>Please file a <link linkend="bugs">bug</link> if you have problems
related to this and need other functions to be specially handled.</para>

</section>

<section id="gdk-lock">
<title>Gdk Lock</title>

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

</section>

</section>

<!--=================-->

<section id="pipeline-iteration">
<title>Pipeline Iteration</title>

<para>There are a number of ways to iterate pipelines.
<filename>./examples/gstreamer/bps.py</filename> 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.</para>

<itemizedlist>
<listitem><para><function>Bin.iterate</function>() in Python from the gtk idle loop</para></listitem>
<listitem><para><function>gst_bin_iterate</function>() in C from gtk idle loop</para></listitem>
<listitem><para><function>Bin.iterate</function>() in a Python loop</para></listitem>
<listitem><para><function>gst_bin_iterate</function>() in a C loop</para></listitem>
</itemizedlist>

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

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

</section>

<!--=================-->

<section id="python-elements">
<title id="python-elements.title">Python Elements</title>

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

</section>

<!--=================-->

</section>

<!--=====================================================================-->

<section id="bugs">
<title>Bugs</title>
<para>
<emphasis>Please</emphasis> submit gst-python bugs, patches, or suggestions to GNOME Bugzilla (<ulink url="http://bugzilla.gnome.org/"/>). Product: GStreamer, Component: gst-python.  Or alternatively send a message to the gstreamer-devel list or the maintainer.  Thank you.
</para>
</section>

<!--=====================================================================-->

<xi:include href="TODO.xml#todo" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<!--=====================================================================-->

<xi:include href="AUTHORS.xml#authors" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<!--=====================================================================-->

</article>