pwg-intro-preface.md

   1 ---
   2 title: Preface
   3 ...
   4
   5 # Preface
   6
   7 ## What is GStreamer?
   8
   9 GStreamer is a framework for creating streaming media applications. The
  10 fundamental design comes from the video pipeline at Oregon Graduate
  11 Institute, as well as some ideas from DirectShow.
  12
  13 GStreamer's development framework makes it possible to write any type of
  14 streaming multimedia application. The GStreamer framework is designed to
  15 make it easy to write applications that handle audio or video or both.
  16 It isn't restricted to audio and video, and can process any kind of data
  17 flow. The pipeline design is made to have little overhead above what the
  18 applied filters induce. This makes GStreamer a good framework for
  19 designing even high-end audio applications which put high demands on
  20 latency or performance.
  21
  22 One of the most obvious uses of GStreamer is using it to build a media
  23 player. GStreamer already includes components for building a media
  24 player that can support a very wide variety of formats, including MP3,
  25 Ogg/Vorbis, MPEG-1/2, AVI, Quicktime, mod, and more. GStreamer, however,
  26 is much more than just another media player. Its main advantages are
  27 that the pluggable components can be mixed and matched into arbitrary
  28 pipelines so that it's possible to write a full-fledged video or audio
  29 editing application.
  30
  31 The framework is based on plugins that will provide the various codec
  32 and other functionality. The plugins can be linked and arranged in a
  33 pipeline. This pipeline defines the flow of the data.
  34
  35 The GStreamer core function is to provide a framework for plugins, data
  36 flow, synchronization and media type handling/negotiation. It also
  37 provides an API to write applications using the various plugins.
  38
  39 ## Who Should Read This Guide?
  40
  41 This guide explains how to write new modules for GStreamer. The guide is
  42 relevant to several groups of people:
  43
  44   - Anyone who wants to add support for new ways of processing data in
  45     GStreamer. For example, a person in this group might want to create
  46     a new data format converter, a new visualization tool, or a new
  47     decoder or encoder.
  48
  49   - Anyone who wants to add support for new input and output devices.
  50     For example, people in this group might want to add the ability to
  51     write to a new video output system or read data from a digital
  52     camera or special microphone.
  53
  54   - Anyone who wants to extend GStreamer in any way. You need to have an
  55     understanding of how the plugin system works before you can
  56     understand the constraints that the plugin system places on the rest
  57     of the code. Also, you might be surprised after reading this at how
  58     much can be done with plugins.
  59
  60 This guide is not relevant to you if you only want to use the existing
  61 functionality of GStreamer, or if you just want to use an application
  62 that uses GStreamer. If you are only interested in using existing
  63 plugins to write a new application - and there are quite a lot of
  64 plugins already - you might want to check the *GStreamer Application
  65 Development Manual*. If you are just trying to get help with a GStreamer
  66 application, then you should check with the user manual for that
  67 particular application.
  68
  69 ## Preliminary Reading
  70
  71 This guide assumes that you are somewhat familiar with the basic
  72 workings of GStreamer. For a gentle introduction to programming concepts
  73 in GStreamer, you may wish to read the *GStreamer Application
  74 Development Manual* first. Also check out the other documentation
  75 available on the [GStreamer web
  76 site](http://gstreamer.freedesktop.org/documentation/).
  77
  78 In order to understand this manual, you will need to have a basic
  79 understanding of the C language. Since GStreamer adheres to the GObject
  80 programming model, this guide also assumes that you understand the
  81 basics of [GObject](http://developer.gnome.org/gobject/stable/pt01.html)
  82 programming. You may also want to have a look at Eric Harlow's book
  83 *Developing Linux Applications with GTK+ and GDK*.
  84
  85 ## Structure of This Guide
  86
  87 To help you navigate through this guide, it is divided into several
  88 large parts. Each part addresses a particular broad topic concerning
  89 GStreamer plugin development. The parts of this guide are laid out in
  90 the following order:
  91
  92   - [Building a Plugin](pwg-building.md) - Introduction to the
  93     structure of a plugin, using an example audio filter for
  94     illustration.
  95
  96     This part covers all the basic steps you generally need to perform
  97     to build a plugin, such as registering the element with GStreamer
  98     and setting up the basics so it can receive data from and send data
  99     to neighbour elements. The discussion begins by giving examples of
 100     generating the basic structures and registering an element in
 101     [Constructing the Boilerplate](pwg-building-boiler.md). Then,
 102     you will learn how to write the code to get a basic filter plugin
 103     working in [Specifying the pads](pwg-building-pads.md), [The
 104     chain function](pwg-building-chainfn.md) and [What are
 105     states?](pwg-statemanage-states.md).
 106
 107     After that, we will show some of the GObject concepts on how to make
 108     an element configurable for applications and how to do
 109     application-element interaction in [Adding
 110     Properties](pwg-building-args.md) and
 111     [Signals](pwg-building-signals.md). Next, you will learn to
 112     build a quick test application to test all that you've just learned
 113     in [Building a Test Application](pwg-building-testapp.md). We
 114     will just touch upon basics here. For full-blown application
 115     development, you should look at [the Application Development
 116     Manual](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/index.html).
 117
 118   - [Advanced Filter Concepts](pwg-advanced.md) - Information on
 119     advanced features of GStreamer plugin development.
 120
 121     After learning about the basic steps, you should be able to create a
 122     functional audio or video filter plugin with some nice features.
 123     However, GStreamer offers more for plugin writers. This part of the
 124     guide includes chapters on more advanced topics, such as scheduling,
 125     media type definitions in GStreamer, clocks, interfaces and tagging.
 126     Since these features are purpose-specific, you can read them in any
 127     order, most of them don't require knowledge from other sections.
 128
 129     The first chapter, named [Different scheduling
 130     modes](pwg-scheduling.md), will explain some of the basics of
 131     element scheduling. It is not very in-depth, but is mostly some sort
 132     of an introduction on why other things work as they do. Read this
 133     chapter if you're interested in GStreamer internals. Next, we will
 134     apply this knowledge and discuss another type of data transmission
 135     than what you learned in [The chain
 136     function](pwg-building-chainfn.md): [Different scheduling
 137     modes](pwg-scheduling.md). Loop-based elements will give you
 138     more control over input rate. This is useful when writing, for
 139     example, muxers or demuxers.
 140
 141     Next, we will discuss media identification in GStreamer in [Types
 142     and Properties](pwg-building-types.md). You will learn how to
 143     define new media types and get to know a list of standard media
 144     types defined in GStreamer.
 145
 146     In the next chapter, you will learn the concept of request- and
 147     sometimes-pads, which are pads that are created dynamically, either
 148     because the application asked for it (request) or because the media
 149     stream requires it (sometimes). This will be in [Request and
 150     Sometimes pads](pwg-advanced-request.md).
 151
 152     The next chapter, [Clocking](pwg-advanced-clock.md), will
 153     explain the concept of clocks in GStreamer. You need this
 154     information when you want to know how elements should achieve
 155     audio/video synchronization.
 156
 157     The next few chapters will discuss advanced ways of doing
 158     application-element interaction. Previously, we learned on the
 159     GObject-ways of doing this in [Adding
 160     Properties](pwg-building-args.md) and
 161     [Signals](pwg-building-signals.md). We will discuss dynamic
 162     parameters, which are a way of defining element behaviour over time
 163     in advance, in [Supporting Dynamic Parameters](pwg-dparams.md).
 164     Next, you will learn about interfaces in
 165     [Interfaces](pwg-advanced-interfaces.md). Interfaces are very
 166     target- specific ways of application-element interaction, based on
 167     GObject's GInterface. Lastly, you will learn about how metadata is
 168     handled in GStreamer in [Tagging (Metadata and
 169     Streaminfo)](pwg-advanced-tagging.md).
 170
 171     The last chapter, [Events: Seeking, Navigation and
 172     More](pwg-advanced-events.md), will discuss the concept of
 173     events in GStreamer. Events are, on the one hand, another way of
 174     doing application-element interaction. It takes care of seeking, for
 175     example. On the other hand, it is also a way in which elements
 176     interact with each other, such as letting each other know about
 177     media stream discontinuities, forwarding tags inside a pipeline and
 178     so on.
 179
 180   - [Creating special element types](pwg-other.md) - Explanation of
 181     writing other plugin types.
 182
 183     Because the first two parts of the guide use an audio filter as an
 184     example, the concepts introduced apply to filter plugins. But many
 185     of the concepts apply equally to other plugin types, including
 186     sources, sinks, and autopluggers. This part of the guide presents
 187     the issues that arise when working on these more specialized plugin
 188     types. The chapter starts with a special focus on elements that can
 189     be written using a base-class ([Pre-made base
 190     classes](pwg-other-base.md)), and later also goes into writing
 191     special types of elements in [Writing a Demuxer or
 192     Parser](pwg-other-oneton.md), [Writing a N-to-1 Element or
 193     Muxer](pwg-other-ntoone.md) and [Writing a
 194     Manager](pwg-other-manager.md).
 195
 196   - [Appendices](pwg-appendix.md) - Further information for plugin
 197     developers.
 198
 199     The appendices contain some information that stubbornly refuses to
 200     fit cleanly in other sections of the guide. Most of this section is
 201     not yet finished.
 202
 203 The remainder of this introductory part of the guide presents a short
 204 overview of the basic concepts involved in GStreamer plugin development.
 205 Topics covered include [Elements and
 206 Plugins](pwg-intro-basics.md#elements-and-plugins),
 207 [Pads](pwg-intro-basics.md#pads), [GstMiniObject, Buffers and
 208 Events](pwg-intro-basics.md#gstminiobject-buffers-and-events) and
 209 [Media types and
 210 Properties](pwg-intro-basics.md#media-types-and-properties). If you
 211 are already familiar with this information, you can use this short
 212 overview to refresh your memory, or you can skip to [Building a
 213 Plugin](pwg-building.md).
 214
 215 As you can see, there a lot to learn, so let's get started\!
 216
 217   - Creating compound and complex elements by extending from a GstBin.
 218     This will allow you to create plugins that have other plugins
 219     embedded in them.
 220
 221   - Adding new media types to the registry along with typedetect
 222     functions. This will allow your plugin to operate on a completely
 223     new media type.
 224