docs/faq/using.xml

   1 <sect1 id="chapter-using">
   2   <title id="title-using">Using GStreamer</title>
   3   <qandaset>
   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 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 connect the sinesrc plug-in to an output plug-in that matches your hardware.
  57 A (non-complete) list of output plug-ins for audio is
  58 <itemizedlist>
  59 <listitem>osssink for OSS output</listitem>
  60 <listitem>esdsink for ESound output</listitem>
  61 <listitem>artssink for aRTs output</listitem>
  62 <listitem>alsasink for ALSA output</listitem>
  63 <listitem>jacksink for JACK output</listitem>
  64 </itemizedlist>
  65 First of all, run gst-inspect on the output plug-in you want to use to
  66 make sure you have it installed.  For example, if you use OSS, run
  67 <programlisting>
  68 $ gst-inspect osssink
  69 </programlisting>
  70 and see if that prints out a bunch of properties for the plug-in.
  71         </para>
  72         <para>
  73 Then try to play the sine tone by running
  74 <programlisting>
  75 $ gst-launch sinesrc ! osssink
  76 </programlisting>
  77 and see if you hear something.  Make sure your volume is turned up,
  78 but also make sure it is not too loud and you are not wearing your headphones.
  79         </para>
  80       </answer>
  81     </qandaentry>
  82
  83     <qandaentry>
  84       <question id="using-gst-inspect">
  85         <para>How can I see what GStreamer plugins I have on my system ?</para>
  86       </question>
  87
  88       <answer>
  89         <para>
  90 To do this you use the gst-inspect
  91 command-line tool, which comes standard with GStreamer.
  92 Invoked without any arguments,
  93 <programlisting>
  94 $ gst-inspect
  95 </programlisting>
  96 will print out a listing of installed plugins.
  97 To learn more about a particular plugin, pass its name on the command line.
  98 For example,
  99 <programlisting>
 100 $ gst-inspect volume
 101 </programlisting>
 102 will give you information about the volume plugin.
 103         </para>
 104         <para>
 105 Also, if you install the gst-editor package, you will have a graphical
 106 plugin browser available, gst-inspect-gui.
 107         </para>
 108       </answer>
 109     </qandaentry>
 110
 111     <qandaentry>
 112       <question id="using-bugs-where">
 113         <para>Where should I report bugs ?</para>
 114       </question>
 115
 116       <answer>
 117         <para>
 118 Bug management is now hosted on GNOME's Bugzilla at
 119 <ulink url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>,
 120 under the product GStreamer.
 121 Using bugzilla you can view past bug history, report new bugs, etc.
 122 Bugzilla requires you to make an account here, which might seem cumbersome,
 123 but allows us to at least have a chance at contacting you for further
 124 information, as we will most likely have to.
 125         </para>
 126       </answer>
 127     </qandaentry>
 128
 129
 130     <qandaentry>
 131       <question id="using-bugs-how">
 132         <para>How should I report bugs ?</para>
 133       </question>
 134
 135       <answer>
 136         <para>
 137 When doing a bug report, you should at least describe
 138 <itemizedlist>
 139 <listitem>your distribution</listitem>
 140 <listitem>
 141 how you installed GStreamer (from cvs, source, packages, which ?)</listitem>
 142 <listitem>if you installed GStreamer before</listitem>
 143 </itemizedlist>
 144         </para>
 145         <para>
 146 It also is useful for us if you attach output of
 147 the gst-feedback command to your bug report.
 148 If you're having problem with a specific application (either one of ours,
 149 somebody else's, or your own), please also provide a log of gst-mask by
 150 running
 151 <programlisting>
 152 myapp --gst-mask=-1 > mask.log 2>&amp;1
 153 gzip mask.log
 154 </programlisting>
 155 (interrupting the program if it doesn't stop by itself)
 156 and attach mask.log.gz to your bug report.
 157         </para>
 158         <para>
 159 If the application you are having problems with is segfaulting, then
 160 provide us with the necessary gdb output.  See
 161 <xref linkend="troubleshooting-segfault" endterm="troubleshooting-segfault"/>
 162         </para>
 163       </answer>
 164     </qandaentry>
 165
 166     <qandaentry>
 167       <question id="using-gst-launch">
 168         <para>How do I use the GStreamer command line interface ?</para>
 169       </question>
 170       <answer>
 171         <para>
 172 You access the GStreamer command line interface using the command gst-launch.
 173 To decode an mp3 and play it through OSS, you could use
 174 <programlisting>
 175 gst-launch filesrc location=thesong.mp3 ! mad ! osssink
 176 </programlisting>.
 177 More examples can be found in the gst-launch man page.
 178         </para>
 179         <para>
 180 To automatically detect the right codec in a pipeline, try
 181 <programlisting>
 182 gst-launch filesrc location=my-random-media-file.mpeg ! spider ! osssink
 183 </programlisting>.
 184 Try replacing osssink with sdlvideosink and see what happens.
 185         </para>
 186         <para>
 187 We also have a simple tool called gst-launch-ext used for debugging,
 188 which has predefined pipelines for you. This means you can just write
 189 <programlisting>
 190 gst-launch-ext (filename)
 191 </programlisting>
 192 and it will play the file if the extension is supported.  Note that no effort
 193 has been made for uninterrupted synchronized playback using this tool.
 194         </para>
 195       </answer>
 196     </qandaentry>
 197   </qandaset>
 198 </sect1>