source: multimedia/libdriv/gst-plugins.xml@ e77976f

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

<!ENTITY gst-plugins-download-http "http://gstreamer.freedesktop.org/src/gst-plugins/gst-plugins-&gst-plugins-version;.tar.bz2">
<!ENTITY gst-plugins-download-ftp  "&gnome-download-ftp;/gst-plugins/0.8/gst-plugins-&gst-plugins-version;.tar.bz2">
<!ENTITY gst-plugins-md5sum        "ea787eeed3761ff03cb60ecebebe1c30">
<!ENTITY gst-plugins-size          "2.4 MB">
<!ENTITY gst-plugins-buildsize     "up to 109 MB (depends on what dependencies are installed)">
<!ENTITY gst-plugins-time          "up to 3.6 SBU">
]>

<sect1 id="gst-plugins" xreflabel="GStreamer Plug-ins-&gst-plugins-version;">
  <?dbhtml filename="gst-plugins.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
    <keywordset>
      <keyword role="package">gst-plugins-&gst-plugins-version;.tar</keyword>
      <keyword role="ftpdir">gst-plugins</keyword>
    </keywordset>
  </sect1info>

  <title>GStreamer Plug-ins-&gst-plugins-version;</title>

  <indexterm zone="gst-plugins">
    <primary sortas="a-GStreamer-Plug-ins">GStreamer Plug-ins</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to GStreamer Plug-ins</title>

    <para>The <application>GStreamer Plug-ins</application> package builds
    graphics and multimedia CODEC interface modules for the
    <application>GStreamer</application> package. There are over 170 different
    modules that can be built, providing <application>GStreamer</application>
    the capability to create a pipeline for almost every known media
    stream. In recent versions of <application>GStreamer Plug-ins</application>,
    the <application>FFmpeg</application> plugin has been removed and is now
    released in a separate module. You can find out information about this
    module and how to download it from <ulink
    url="http://gstreamer.freedesktop.org/modules/gst-ffmpeg.html"/>.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&gst-plugins-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&gst-plugins-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &gst-plugins-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &gst-plugins-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &gst-plugins-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &gst-plugins-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">GStreamer Plug-ins Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="gstreamer"/></para>

    <bridgehead renderas="sect4">Optional Utilities (Graphics, Compression, Misc.)</bridgehead>
    <para role="optional"><xref linkend="aalib"/>,
    <xref linkend="cairo"/>,
    <xref linkend="cdparanoia"/>,
    <xref linkend="freetype2"/>,
    <xref linkend="GConf"/>,
    <xref linkend="gtk2"/>,
    <xref linkend="gnome-vfs"/>,
    <ulink url="http://talinux.fi.tal.org/pub/talinux/sources/Hermes-1.3.3.tar.gz">Hermes</ulink>,
    <ulink url="http://sam.zoy.org/projects/libcaca/">libcaca</ulink>,
    <ulink url="http://www.gnu.org/software/libcdio/">libcdio</ulink>,
    <ulink url="http://cvs.sourceforge.net/viewcvs.py/codecs/libcolorspace-pre/">libcolorspace</ulink>,
    <xref linkend="libjpeg"/> or
    <ulink url="http://sourceforge.net/projects/mjpeg/">MMX Jpeg</ulink>,
    <ulink url="http://eetpc20.bd.psu.edu/~rfisher/Research/Libmmx/libmmx.html">libmmx</ulink>,
    <xref linkend="libmng"/>,
    <ulink url="http://www.schleef.org/liboil/">liboil</ulink>,
    <xref linkend="libpng"/>,
    <xref linkend="NASM"/>,
    <xref linkend="pango"/>, and
    <xref linkend="x-window-system"/></para>

    <bridgehead renderas="sect4">Optional Audio Libraries/Drivers/CODECs</bridgehead>
    <para role="optional"><xref linkend="alsa"/>,
    <xref linkend="arts"/>,
    <xref linkend="audiofile"/>,
    <ulink url="http://www.comedi.org/cgi-bin/viewcvs.cgi/audioresample/">audioresample</ulink>,
    <xref linkend="esound"/>,
    <ulink url="http://sourceforge.net/projects/faac">FAAC</ulink>,
    <ulink url="http://sourceforge.net/projects/faac">FAAD2</ulink>,
    <xref linkend="flac"/>,
    <ulink url="http://kbs.cs.tu-berlin.de/~jutta/toast.html">GSM</ulink>,
    <ulink url="http://jackit.sourceforge.net/">JACK</ulink>,
    <xref linkend="lame"/>,
    <xref linkend="liba52"/>,
    <ulink url="http://ronald.bitfreak.net/priv/">libamrnb</ulink>,
    <ulink url="http://libcdaudio.sourceforge.net/">libcdaudio</ulink>,
    <ulink url="http://www.videolan.org/libdca.html">libdts</ulink>,
    <xref linkend="libmad"/> (and
    <ulink url="http://sourceforge.net/projects/mad/">libid3tag</ulink>),
    <xref linkend="libmikmod"/>,
    <ulink url="http://www.musepack.net/">libmpcdec</ulink>,
    <xref linkend="libmusicbrainz"/>,
    <xref linkend="libogg"/>,
    <ulink url="http://www.linux1394.org/">libraw1394</ulink> (and
    <ulink url="http://sourceforge.net/projects/libavc1394/">libavc1394</ulink>),
    <ulink url="http://www.icecast.org/">libshout</ulink>,
    <ulink url="http://www.geocities.com/SiliconValley/Lakes/5147/sidplay/">libsidplay</ulink>,
    <ulink url="http://www.mega-nerd.com/libsndfile/">libsndfile</ulink>,
    <xref linkend="libvorbis"/>,
    <ulink url="http://www.ladspa.org/">LADSPA</ulink>,
    <xref linkend="nas"/>,
    <ulink url="http://0pointer.de/lennart/projects/polypaudio/">polypaudio</ulink>,
    <xref linkend="speex"/>,
    <ulink url="http://www.theora.org/">Theora</ulink>,
    <ulink url="http://www.xiph.org/vorbis/">Tremor</ulink>,
    <ulink url="http://www.wavpack.com/">WavPack</ulink>, and
    <ulink url="http://developers.videolan.org/x264.html">x264</ulink></para>

    <bridgehead renderas="sect4">Optional Video Libraries/Drivers/CODECs</bridgehead>
    <para role="optional"><ulink url="http://sourceforge.net/projects/dirac/">Dirac</ulink>,
    <ulink url="http://directfb.org/">DirectFB</ulink>,
<!-- Dead link
    <ulink url="http://www.divx.com/divx/linux/">DivX4Linux</ulink>,
-->
    <ulink url="http://dxr3.sourceforge.net/">DXR3</ulink>,
    <xref linkend="libdv"/>,
    <ulink url="http://sourceforge.net/projects/dvd/">libdvdnav</ulink>,
    <xref linkend="libdvdread"/>,
    <xref linkend="libfame"/>,
    <xref linkend="libmpeg2"/>,
    <!-- <ulink url="https://cvs.comedi.org/cgi-bin/viewcvs.cgi/librfb/">librfb</ulink>, -->
    <ulink url="http://mjpeg.sourceforge.net/">MJPEG Tools</ulink>,
    <ulink url="http://www.thedirks.org/v4l2/">V4L2</ulink>, and
    <xref linkend="xvid"/></para>

    <bridgehead renderas="sect4">Optional Multimedia Utilities</bridgehead>
    <para role="optional"><ulink url="http://sourceforge.net/projects/libmms">libmms</ulink>,
    <ulink url="http://sourceforge.net/projects/libvisual/">libvisual</ulink>,
    <xref linkend="sdl"/>,
    <ulink url="http://swfdec.sourceforge.net/">swfdec</ulink>, and
    <xref linkend="xine-lib"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of GStreamer Plug-ins</title>

    <para>Install <application>GStreamer Plug-ins</application> by running the
    following commands:</para>

<screen><userinput>sed -i -e 's|LIBS="-lGLU|LIBS="-L/usr/X11R6/lib -lGLU|' \
       -e '/GST_DOC/d' \
       -e 's/lx264 -lm/&amp; -lpthread/' \
    configure &amp;&amp;
sed -i 's/X264_LIBS@/&amp; -lpthread/' ext{,/x264}/Makefile.in &amp;&amp;

./configure --prefix=/usr --sysconfdir=/etc &amp;&amp;
make</userinput></screen>

    <para>To check the results, issue:</para>

<screen><userinput>sed -i 's|:\$(GST_LIB_DIR)/..||' gst/audioconvert/Makefile &amp;&amp;
make -C gst/audioconvert check</userinput></screen>

    <para> On some platforms in certain situations the tests may fail because
    one or more of the plugins will fail to register. This will be displayed in
    the output from the command. If this happens, you are urged to rename the
    offending plugin and repeat the
    <command>make -C gst/audioconvert check</command> command. Both tests
    should pass before you continue. Simply renaming the offending plugin by
    adding <filename class='extension'>.BAD</filename> to the end of the
    filename is sufficient. Here is an example:</para>

<screen><userinput>mv gst/audioconvert/../../ext/xine/.libs/libgstxine.so \
   gst/audioconvert/../../ext/xine/.libs/libgstxine.so.BAD</userinput></screen>

    <para>After the tests have completed successfully, if you had to rename any
    of the plugins, ensure you rename it back to the original, or the
    installation step will fail.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;
ldconfig</userinput></screen>

    <para>If you had to rename any of the plugins for the tests to complete
    successfully, you will have to also rename (or remove) them so that the
    <command>gst-register</command> command will complete successfully. The
    plugins were installed into the
    <filename class='directory'>/usr/lib/gstreamer-0.8</filename>
    directory. Finish the installation by running the following command as the
    <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>gst-register</userinput></screen>

    <caution>
      <para>If you <command>touch</command>, <command>strip</command> or do
      anything else that can update the time stamp (modification time) of the
      plugin files, ensure you rerun the <command>gst-register</command>
      command as the <systemitem class="username">root</systemitem> user again
      so that the time stamp of the global registry file
      (<filename>/var/cache/gstreamer-0.8/registry.xml</filename>) is dated
      later than the time stamp of any of the plugin files.</para>
    </caution>

    <sect3>
      <title>Testing the Installation</title>

      <para>To test the functionality of the completed
      <application>GStreamer</application> installation, you can run a couple
      of tests. Perform the tests as an unprivileged user.</para>

      <para>The first test should complete without any errors displayed to
      the screen:</para>

<screen><userinput>gst-launch --iterations=10000 sinesrc ! fakesink</userinput></screen>

      <para>For the next test you'll need to choose an output method valid for
      your system such as osssink/esdsink/artsdsink/alsasink/jacksink. Replace
      the <replaceable>[output_sink]</replaceable> in the command below with
      a valid output method. Running the command should produce a C tone for a
      short duration.</para>

<screen><userinput>gst-launch --iterations=50 sinesrc ! <replaceable>[output_sink]</replaceable></userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>sed -i ... configure</command>: The check for the OpenGL
    (Mesa) libraries will fail if <application>X</application> is installed in
    any directory other than <filename class='directory'>/usr</filename>. This
    commands adds an additional search path. Additionally, the command removes
    a misplaced line and fixes the checks for the
    <application>x264</application> library.</para>

    <para><command>sed -i ... ext{,/x264}/Makefile.in</command>: This command
    adds the <filename class='libraryfile'>libpthread.so</filename> library to
    the list of libraries required to properly compile the
    <application>x264</application> library.</para>

    <para><option>--with-gconf-schema-file-dir=&gnome-etc-dir;/gconf/schemas</option>:
    Use this option if you have the <application>GNOME-2</application>
    <application>GConf</application> package installed.</para>

    <para><option>--enable-gdk-pixbuf-loader</option>: Use this option to build
    the GDK pixbuf loader module if you have <application>GTK+-2</application>
    installed.</para>

    <para><option>-enable-xine</option>: Use this option to build the
    <application>Xine</application> wrapper module if you have the
    <application>Xine Libraries</application> package installed. On some
    platforms, the module will have some corruption and cause the test suite
    and <command>gst-register</command> command to fail.</para>

    <!--
    <para><option>-enable-xine</option>: Using this option to build the
    <application>Xine</application> wrapper module will break the build if you
    have <application>xine-libs</application>-&xine-lib-version;
    installed.</para>
    -->

    <para>Note: all other modules are built if the <command>configure</command>
    script discovers the required dependency package. To prevent a module from
    being built, pass
    <option>--disable-<replaceable>[module]</replaceable></option> to
    <command>configure</command>. Run <command>configure --help</command>
    for all the available module names.</para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>gst-launch-ext-0.8 and gst-visualise-0.8</seg>
        <seg>libgst*.[so,a], numerous <application>GStreamer</application> plugins,
        and a <application>Gstreamer</application> GDK pixbuf loader module</seg>
        <seg>&gnome-etc-dir;/gconf/gconf.xml.defaults/schemas/system/gstreamer,
        &gnome-etc-dir;/gconf/gconf.xml.defaults/system/gstreamer,
        and many subdirs of /usr/include/gstreamer-0.8/gst</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="gst-launch-ext">
        <term><command>gst-launch-ext-0.8</command></term>
        <listitem>
          <para>is used to run a basic predefined
          <application>GStreamer</application> pipeline as a quick test to ensure
          proper working of codecs and <application>GStreamer</application>.</para>
          <indexterm zone="gst-plugins gst-launch-ext">
            <primary sortas="b-gst-launch-ext">gst-launch-ext-0.8</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gst-visualise">
        <term><command>gst-visualise-0.8</command></term>
        <listitem>
          <para>is used to run a basic <application>GStreamer</application>
          pipeline to display a graphical visualisation of an audio stream.</para>
          <indexterm zone="gst-plugins gst-visualise">
            <primary sortas="b-gst-visualise">gst-visualise-0.8</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>