docs/faq/using.xml

   1 <sect1 id="chapter-using">
   2   <title id="title-using">Using GStreamer</title>
   3   <qandaset defaultlabel="qanda">
   4
   5     <qandaentry>
   6       <question id="using-getting-started">
   7         <para>Ok, I've installed GStreamer.  What can I do next ?</para>
   8       </question>
   9
  10       <answer>
  11         <para>
  12 First of all, verify that you have a working registry and that you can
  13 inspect them by typing
  14 <programlisting>
  15 $ gst-inspect fakesrc
  16 </programlisting>
  17 This should print out a bunch of information about this particular element.
  18 If this tells you that there is "no such element or plugin", you haven't
  19 installed GStreamer correctly.  Please check
  20 <link linkend="chapter-getting">how to get GStreamer</link>
  21 If this fails with any other message, we would appreciate a
  22 <link linkend="using-bugs-where">bug report</link>.
  23         </para>
  24         <para>
  25 It's time to try out a few things.  Start with gst-launch and two plug-ins
  26 that you really should have : fakesrc and fakesink.  They do nothing except
  27 pass empty buffers. Type this at the command-line :
  28 <programlisting>
  29 $ gst-launch -v fakesrc num-buffers=3 ! fakesink
  30 </programlisting>
  31 This will print out output that looks similar to this :
  32 <programlisting>
  33 RUNNING pipeline ...
  34 fakesrc0: last-message = "get      ******* (fakesrc0:src)gt; (0 bytes, 0) 0x8057510"
  35 fakesink0: last-message = "chain   ******* (fakesink0:sink)lt; (0 bytes, 0) 0x8057510"
  36 fakesrc0: last-message = "get      ******* (fakesrc0:src)gt; (0 bytes, 1) 0x8057510"
  37 fakesink0: last-message = "chain   ******* (fakesink0:sink)lt; (0 bytes, 1) 0x8057510"
  38 fakesrc0: last-message = "get      ******* (fakesrc0:src)gt; (0 bytes, 2) 0x8057510"
  39 fakesink0: last-message = "chain   ******* (fakesink0:sink)lt; (0 bytes, 2) 0x8057510"
  40 execution ended after 5 iterations (sum 301479000 ns, average 60295800 ns, min 3000 ns, max 105482000 ns)
  41 </programlisting>
  42 (Some parts of output have been removed for clarity)  If it looks similar, then
  43 GStreamer itself is running correctly.
  44         </para>
  45       </answer>
  46     </qandaentry>
  47
  48     <qandaentry>
  49       <question id="using-sound">
  50         <para>Can my system play sound through GStreamer ?</para>
  51       </question>
  52
  53       <answer>
  54         <para>
  55 You can test this by trying to play a sine tone.  For this, you need to
  56 link the audiotestsrc element to an output element that matches your hardware.
  57 A (non-complete) list of output plug-ins for audio is
  58 <itemizedlist>
  59 <listitem><para>osssink for OSS output</para></listitem>
  60 <listitem><para>esdsink for ESound output</para></listitem>
  61 <listitem><para>artsdsink for aRTs output (not ported to 0.10 yet)</para></listitem>
  62 <listitem><para>alsasink for ALSA output</para></listitem>
  63 <listitem><para>alsaspdifsink for ALSA S/PDIF output</para></listitem>
  64 <listitem><para>jackaudiosink for JACK output</para></listitem>
  65 </itemizedlist>
  66 First of all, run gst-inspect on the output plug-in you want to use to
  67 make sure you have it installed.  For example, if you use OSS, run
  68 <programlisting>
  69 $ gst-inspect osssink
  70 </programlisting>
  71 and see if that prints out a bunch of properties for the plug-in.
  72         </para>
  73         <para>
  74 Then try to play the sine tone by running
  75 <programlisting>
  76 $ gst-launch audiotestsrc ! audioconvert ! audioresample ! osssink
  77 </programlisting>
  78 and see if you hear something.  Make sure your volume is turned up,
  79 but also make sure it is not too loud and you are not wearing your headphones.
  80         </para>
  81         <para>
  82 In GNOME, you can configure audio output for most applications by running
  83 <programlisting>
  84 $ gstreamer-properties
  85 </programlisting>
  86 which can also be found in the start menu (Applications -> Preferences ->
  87 Multimedia Systems Selector). In KDE, there is not yet a shared way of
  88 setting audio output for all applications; however, applications such
  89 as Amarok allow you to specify an audio output in their preferences dialog.
  90         </para>
  91       </answer>
  92     </qandaentry>
  93
  94     <qandaentry>
  95       <question id="using-gst-inspect">
  96         <para>How can I see what GStreamer plugins I have on my system ?</para>
  97       </question>
  98
  99       <answer>
 100         <para>
 101 To do this you use the gst-inspect
 102 command-line tool, which comes standard with GStreamer.
 103 Invoked without any arguments,
 104 <programlisting>
 105 $ gst-inspect
 106 </programlisting>
 107 will print out a listing of installed plugins.
 108 To learn more about a particular plugin, pass its name on the command line.
 109 For example,
 110 <programlisting>
 111 $ gst-inspect volume
 112 </programlisting>
 113 will give you information about the volume plugin.
 114         </para>
 115         <para>
 116 Also, if you install the gst-editor package, you will have a graphical
 117 plugin browser available, gst-inspect-gui.
 118         </para>
 119       </answer>
 120     </qandaentry>
 121
 122     <qandaentry>
 123       <question id="using-bugs-where">
 124         <para>Where should I report bugs ?</para>
 125       </question>
 126
 127       <answer>
 128         <para>
 129 Bug management is now hosted on GNOME's Bugzilla at
 130 <ulink url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>,
 131 under the product GStreamer.
 132 Using bugzilla you can view past bug history, report new bugs, etc.
 133 Bugzilla requires you to make an account here, which might seem cumbersome,
 134 but allows us to at least have a chance at contacting you for further
 135 information, as we will most likely have to.
 136         </para>
 137       </answer>
 138     </qandaentry>
 139
 140
 141     <qandaentry>
 142       <question id="using-bugs-how">
 143         <para>How should I report bugs ?</para>
 144       </question>
 145
 146       <answer>
 147         <para>
 148 When doing a bug report, you should at least describe
 149 <itemizedlist>
 150 <listitem><para>your distribution</para></listitem>
 151 <listitem><para>
 152 how you installed GStreamer (from git, source, packages, which ?)</para></listitem>
 153 <listitem><para>if you installed GStreamer before</para></listitem>
 154 </itemizedlist>
 155         </para>
 156         <para>
 157 If the application you are having problems with is segfaulting, then
 158 provide us with the necessary gdb output.  See
 159 <xref linkend="troubleshooting-segfault" endterm="troubleshooting-segfault"/>
 160         </para>
 161       </answer>
 162     </qandaentry>
 163
 164     <qandaentry>
 165       <question id="using-gst-launch">
 166         <para>How do I use the GStreamer command line interface ?</para>
 167       </question>
 168       <answer>
 169         <para>
 170 You access the GStreamer command line interface using the command gst-launch.
 171 To decode an mp3 and play it through OSS, you could use
 172 <programlisting>
 173 gst-launch filesrc location=thesong.mp3 ! mad ! audioconvert !
 174 audioresample ! osssink
 175 </programlisting>.
 176 More examples can be found in the gst-launch man page.
 177         </para>
 178         <para>
 179 To automatically detect the right codec in a pipeline, try
 180 <programlisting>
 181 gst-launch filesrc location=my-random-media-file.mpeg ! decodebin !
 182  audioconvert ! audioresample ! osssink
 183 </programlisting>.
 184 or
 185 <programlisting>
 186 gst-launch filesrc location=my-random-media-file.mpeg ! decodebin !
 187  ffmpegcolorspace ! xvimagesink
 188 </programlisting>
 189 Something more complicated:
 190 <programlisting>
 191 gst-launch filesrc location=my-random-media-file.mpeg ! decodebin name=decoder
 192    decoder. ! ffmpegcolorspace ! xvimagesink
 193    decoder. ! audioconvert ! audioresample ! osssink
 194 </programlisting>
 195         </para>
 196         <para>
 197 We also have a basic media playing plugin that will take care of most things
 198 for you. This plugin is called playbin. Try this:
 199 <programlisting>
 200 gst-launch playbin uri=file:///home/joe/my-random-media-file.mpeg
 201 </programlisting>
 202 This should play the file if the format is supported, ie. you have all the
 203 necessary demuxing and decoding and some output plugins installed.
 204         </para>
 205       </answer>
 206     </qandaentry>
 207   </qandaset>
 208 </sect1>