docs/manual/manual.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3           "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % image-entities SYSTEM "image.entities">
   5 %image-entities;
   6 <!ENTITY % version-entities SYSTEM "version.entities">
   7 %version-entities;
   8 <!ENTITY % url-entities SYSTEM "url.entities">
   9 %url-entities;
  10
  11 <!ENTITY EXAFOOT "
  12 <footnote>
  13   <para>
  14     The code for this example is automatically extracted from
  15     the documentation and built under <filename>tests/examples/manual</filename>
  16     in the GStreamer tarball.
  17   </para>
  18 </footnote>
  19 ">
  20
  21 <!ENTITY TITLEPAGE            SYSTEM "titlepage.xml">
  22
  23 <!-- Part 1: Overview -->
  24 <!ENTITY INTRO                SYSTEM "intro-preface.xml">
  25
  26 <!ENTITY GSTREAMER            SYSTEM "intro-gstreamer.xml">
  27 <!ENTITY MOTIVATION           SYSTEM "intro-motivation.xml">
  28 <!ENTITY CONCEPTS             SYSTEM "intro-basics.xml">
  29
  30 <!-- Part 2: Basic Concepts -->
  31 <!ENTITY INIT                 SYSTEM "basics-init.xml">
  32 <!ENTITY ELEMENTS             SYSTEM "basics-elements.xml">
  33 <!ENTITY BINS                 SYSTEM "basics-bins.xml">
  34 <!ENTITY BUS                  SYSTEM "basics-bus.xml">
  35 <!ENTITY PADS                 SYSTEM "basics-pads.xml">
  36 <!ENTITY DATA                 SYSTEM "basics-data.xml">
  37 <!ENTITY HELLOWORLD           SYSTEM "basics-helloworld.xml">
  38
  39 <!-- Part 3: Advanced Concepts -->
  40 <!ENTITY QUERYEVENTS          SYSTEM "advanced-position.xml">
  41 <!ENTITY METADATA             SYSTEM "advanced-metadata.xml">
  42 <!ENTITY INTERFACES           SYSTEM "advanced-interfaces.xml">
  43 <!ENTITY CLOCKS               SYSTEM "advanced-clocks.xml">
  44 <!ENTITY BUFFERING            SYSTEM "advanced-buffering.xml">
  45 <!ENTITY DPARAMS              SYSTEM "advanced-dparams.xml">
  46 <!ENTITY THREADS              SYSTEM "advanced-threads.xml">
  47 <!ENTITY AUTOPLUGGING         SYSTEM "advanced-autoplugging.xml">
  48 <!ENTITY DATAACCESS           SYSTEM "advanced-dataaccess.xml">
  49
  50 <!-- Part 4: Higher-level interfaces -->
  51 <!ENTITY PLAYBACK             SYSTEM "highlevel-playback.xml">
  52
  53 <!-- Appendices -->
  54 <!ENTITY PROGRAMS             SYSTEM "appendix-programs.xml">
  55 <!ENTITY COMPILING            SYSTEM "appendix-compiling.xml">
  56 <!ENTITY CHECKLIST            SYSTEM "appendix-checklist.xml">
  57 <!ENTITY PORTING              SYSTEM "appendix-porting.xml">
  58 <!ENTITY INTEGRATION          SYSTEM "appendix-integration.xml">
  59 <!ENTITY LICENSING            SYSTEM "appendix-licensing.xml">
  60 <!ENTITY QUOTES               SYSTEM "appendix-quotes.xml">
  61
  62 <!ENTITY GStreamer    "<application>GStreamer</application>">
  63 <!ENTITY GstPWG       "<emphasis>GStreamer Plugin Writer's Guide</emphasis>">
  64 ]>
  65
  66 <book id="index">
  67   &TITLEPAGE;
  68
  69 <!-- ############# Introduction ############### -->
  70
  71 <preface><title>Foreword</title>
  72       <para><!-- synchronize with PWG -->
  73         &GStreamer; is an extremely powerful and versatile framework for
  74         creating streaming media applications. Many of the virtues of the
  75         &GStreamer; framework come from its modularity: &GStreamer; can
  76         seamlessly incorporate new plugin modules. But because modularity
  77         and power often come at a cost of greater complexity, writing new
  78         applications is not always easy.
  79       </para>
  80       <para>
  81         This guide is intended to help you understand the &GStreamer;
  82         framework (version &GST_VERSION;) so you can develop applications
  83         based on it. The first chapters will focus on development of a
  84         simple audio player, with much effort going into helping you
  85         understand &GStreamer; concepts. Later chapters will go into
  86         more advanced topics related to media playback, but also at
  87         other forms of media processing (capture, editing, etc.).
  88       </para>
  89 </preface>
  90
  91
  92 <preface><title>Introduction</title>
  93
  94   &INTRO;
  95
  96 </preface>
  97
  98 <!-- ############# Overview - part ############### -->
  99
 100   <part id="part-introduction">
 101     <title>About GStreamer</title>
 102     <partintro>
 103       <para>
 104     This part gives you an overview of the technologies described in
 105     this book.
 106       </para>
 107     </partintro>
 108
 109     &GSTREAMER;
 110     &MOTIVATION;
 111     &CONCEPTS;
 112
 113   </part>
 114
 115 <!-- ############ Basic concepts - part ############# -->
 116
 117   <part id="part-building">
 118     <title>Building an Application</title>
 119     <partintro>
 120       <para>
 121         In these chapters, we will discuss the basic concepts of &GStreamer;
 122         and the most-used objects, such as elements, pads and buffers. We
 123         will use a visual representation of these objects so that we can
 124         visualize the more complex pipelines you will learn to build later
 125         on. You will get a first glance at the &GStreamer; API, which should
 126         be enough for building elementary applications. Later on in this
 127         part, you will also learn to build a basic command-line application.
 128       </para>
 129       <para>
 130         Note that this part will give a look into the low-level API and
 131         concepts of &GStreamer;. Once you're going to build applications,
 132         you might want to use higher-level APIs. Those will be discussed
 133         later on in this manual.
 134       </para>
 135     </partintro>
 136
 137     &INIT;
 138     &ELEMENTS;
 139     &BINS;
 140     &BUS;
 141     &PADS;
 142     &DATA;
 143     &HELLOWORLD;
 144
 145   </part>
 146
 147 <!-- ############ Advanced GStreamer - part ############# -->
 148
 149   <part id="part-advanced">
 150     <title>Advanced &GStreamer; concepts</title>
 151     <partintro>
 152       <para>
 153         In this part we will cover the more advanced features of &GStreamer;.
 154         With the basics you learned in the previous part you should be
 155         able to create a <emphasis>simple</emphasis> application. However,
 156         &GStreamer; provides much more candy than just the basics of playing
 157         back audio files. In this chapter, you will learn more of the
 158         low-level features and internals of &GStreamer;.
 159       </para>
 160       <para>
 161         Some parts of this part will serve mostly as an explanation of
 162         how &GStreamer; works internally; they are not actually needed for
 163         actual application development. This includes chapters such as the
 164         ones covering scheduling, autoplugging and synchronization. Other
 165         chapters, however, discuss more advanced ways of
 166         pipeline-application interaction, and can turn out to be very useful
 167         for certain applications. This includes the chapters on metadata,
 168         querying and events, interfaces, dynamic parameters and pipeline
 169         data manipulation.
 170       </para>
 171     </partintro>
 172
 173     &QUERYEVENTS;
 174     &METADATA;
 175     &INTERFACES;
 176     &CLOCKS;
 177     &BUFFERING;
 178     &DPARAMS;
 179     &THREADS;
 180     &AUTOPLUGGING;
 181     &DATAACCESS;
 182
 183   </part>
 184
 185 <!-- ############ Higher-level APIs in GStreamer - part ############# -->
 186
 187   <part id="part-highlevel">
 188     <title>Higher-level interfaces for &GStreamer; applications</title>
 189     <partintro>
 190       <para>
 191         In the previous two parts, you have learned many of the internals
 192         and their corresponding low-level interfaces into &GStreamer;
 193         application programming. Many people will, however, not need so
 194         much control (and as much code), but will prefer to use a standard
 195         playback interface that does most of the difficult internals for
 196         them. In this chapter, we will introduce you into the concept of
 197         autopluggers, playback managing elements and other such things.
 198         Those higher-level interfaces are intended to
 199         simplify &GStreamer;-based application programming. They do, however,
 200         also reduce the flexibility. It is up to the application developer
 201         to choose which interface he will want to use.
 202       </para>
 203     </partintro>
 204
 205     &PLAYBACK;
 206
 207   </part>
 208
 209 <!-- ############ Appendices - part ############# -->
 210
 211   <part id="part-appendices">
 212     <title>Appendices</title>
 213     <partintro>
 214       <para>
 215         By now, you've learned all about the internals of &GStreamer; and
 216         application programming using the &GStreamer; framework. This part
 217         will go into some random bits that are useful to know if you're
 218         going to use &GStreamer; for serious application programming. It
 219         will touch upon things related to integration with popular desktop
 220         environments that we run on (GNOME, KDE, OS X, Windows), it will
 221         shortly explain how applications included with &GStreamer; can help
 222         making your life easier, and some information on debugging.
 223       </para>
 224       <para>
 225         In addition, we also provide a porting guide which will explain
 226         easily how to port &GStreamer;-0.10 applications to &GStreamer;-1.0.
 227       </para>
 228     </partintro>
 229
 230     <!--
 231     Idea:
 232     * Debugging and error handling
 233      - 'error' signal in pipelines
 234      - checking return values and how to handle them
 235      - using signals for pipeline states
 236      - gst-debug
 237      - programs
 238     * Desktop integration
 239      - Linux/UNIX
 240         . {x,xv}imagesink
 241         . {oss,alsa}sink
 242         . {v4l,v4l2,oss,alsa}src
 243      - GNOME
 244         . GConf ({video,audio}{src,sink})
 245         . gnomevfssrc, gnomevfssink
 246         . popt
 247         . app examples (RB, Totem, gnome-media, ...)
 248      - KDE
 249         . kiosrc
 250         . app examples (JuK, AmaroK)
 251         . ask Scott/Mark
 252      - Mac OS X
 253         . native video/audio sink
 254      - Windows
 255         . build etc.
 256     * Quotes from devs
 257      - table please...
 258     -->
 259
 260     &PROGRAMS;
 261     &COMPILING;
 262     &CHECKLIST;
 263     &PORTING;
 264     &INTEGRATION;
 265     &LICENSING;
 266     &QUOTES;
 267
 268   </part>
 269 </book>