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