diff options
Diffstat (limited to 'docs/gst-python.xml')
| -rw-r--r-- | docs/gst-python.xml | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/docs/gst-python.xml b/docs/gst-python.xml new file mode 100644 index 0000000..077a127 --- /dev/null +++ b/docs/gst-python.xml @@ -0,0 +1,435 @@ +<?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"> + +<article id="gst-python"> +<articleinfo> + <publisher><publishername>The GStreamer Development Team</publishername></publisher> + <pubdate>June ??, 2003</pubdate> + <copyright><year>2003</year><holder>David I. Lehn</holder></copyright> + <title><application>gst-python</application>: A Python Interface to GStreamer</title> + <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://www.gstreamer.net/bindings/python/"/></para> + </abstract> + <revhistory> + <revision> + <revnumber>0.1.0</revnumber> + <date>2003-06-??</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> + +<!--=====================================================================--> + +<section id="news"> +<title>News</title> +<para> +<informaltable frame="all"> +<tgroup cols="3"> +<colspec align="center"/> +<colspec align="center"/> +<colspec align="left"/> +<thead> + <row> + <entry>Date</entry> + <entry>Version</entry> + <entry>Notes</entry> + </row> +</thead> +<tbody> + <row> + <entry>2003-06-xx</entry> + <entry>0.1.0</entry> + <entry>first release</entry> + </row> +</tbody> +</tgroup> +</informaltable> +</para> +</section> + +<!--=====================================================================--> + +<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 && 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 <input file> <output file> + $ cmp <input file> <output file> + $ python vorbisplay.py <an Ogg Vorbis file> +</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://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. + +</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>) -> <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>() -> + <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> + +<!--=====================================================================--> + +<section id="todo"> +<title>TODO</title> +<itemizedlist> +<listitem><para>handle more of the functions that need manual wrapping code</para></listitem> +<listitem><para>add check that pygtk built with <parameter class="command">--enable-thread</parameter></para></listitem> +<listitem><para>improve Python gstreamer.Element creation</para> + <itemizedlist> + <listitem><para>perhaps drop <function>_set_foo_function</function>() calls in favor of object methods</para></listitem> + <listitem><para>sane buffer handling with buffer type or Numeric?</para></listitem> + </itemizedlist> +</listitem> +<listitem><para>docs</para> + <itemizedlist> + <listitem><para>API ref</para></listitem> + <listitem><para>manual</para></listitem> + <listitem><para>tutorial</para></listitem> + </itemizedlist> +</listitem> +<listitem><para>more examples</para></listitem> +<listitem><para>convert build system to distutils</para></listitem> +<listitem><para>wrap other GStreamer helper libs</para></listitem> +<listitem><para>add some standard widgets</para> + <itemizedlist> + <listitem><para>gtk video widget (similar to widget gst-player is using)</para></listitem> + </itemizedlist> +</listitem> +<listitem><para>testsuite</para></listitem> +</itemizedlist> +</section> + +<!--=====================================================================--> + +<section id="authors"> +<title>Authors</title> + +<para> +Please feel free to contact the developers. They hang out on IRC (<ulink url="http://gstreamer.net/dev/"/>) and the mailing lists (<ulink url="http://gstreamer.net/contact/lists.php"/>). +</para> + +<!--=================--> + +<section id="maintainer"> +<title>Maintainer</title> + +<itemizedlist> +<listitem><para>David I. Lehn <email>dlehn at users.sourceforge.net</email></para></listitem> +</itemizedlist> +</section> + +<!--=================--> + +<section id="contributions"> +<title>Contributions</title> +<para> +Patches, suggestions, and other help: +</para> + +<itemizedlist> +<listitem><para>Kenichi Sato <email>ksato at users.sourceforge.net</email></para></listitem> +</itemizedlist> + +<para> +Much of the framework for gst-python stolen from gtk and gconf bindings by: +</para> + +<itemizedlist> +<listitem><para>James Henstridge <email>james at daa.com.au</email></para></listitem> +<listitem><para>Johan Dahlin <email>jdahlin at telia.com</email></para></listitem> +<listitem><para>Matt Wilson <email>msw at redhat.com</email></para></listitem> +<listitem><para>and many more...</para></listitem> +</itemizedlist> + +</section> + +<!--=================--> + +<section id="gstreamer-team"> +<title>GStreamer Team</title> +<para> +And of course, none of this would be possible without the extreme hacker mojo +of the whole GStreamer crew! +</para> +</section> + +<!--=================--> + +</section> + +<!--=====================================================================--> + +</article> |