| |
| <!-- ############ chapter ############# --> |
| |
| <chapter id="chapter-intro-preface" xreflabel="Preface"> |
| <title>Preface</title> |
| |
| <!-- ############ sect1 ############# --> |
| |
| <sect1 id="section-intro-what"><!-- synchronize with AppDevMan --> |
| <title>What is &GStreamer;?</title> |
| <para> |
| &GStreamer; is a framework for creating streaming media applications. |
| The fundamental design comes from the video pipeline at Oregon Graduate |
| Institute, as well as some ideas from DirectShow. |
| </para> |
| |
| <para> |
| &GStreamer;'s development framework makes it possible to write any |
| type of streaming multimedia application. The &GStreamer; framework |
| is designed to make it easy to write applications that handle audio |
| or video or both. It isn't restricted to audio and video, and can |
| process any kind of data flow. |
| The pipeline design is made to have little overhead above what the |
| applied filters induce. This makes &GStreamer; a good framework for |
| designing even high-end audio applications which put high demands on |
| latency. |
| </para> |
| |
| <para> |
| One of the most obvious uses of &GStreamer; is using it to build |
| a media player. &GStreamer; already includes components for building a |
| media player that can support a very wide variety of formats, including |
| MP3, Ogg/Vorbis, MPEG-1/2, AVI, Quicktime, mod, and more. &GStreamer;, |
| however, is much more than just another media player. Its main advantages |
| are that the pluggable components can be mixed and matched into arbitrary |
| pipelines so that it's possible to write a full-fledged video or audio |
| editing application. |
| </para> |
| |
| <para> |
| The framework is based on plugins that will provide the various codec |
| and other functionality. The plugins can be linked and arranged in |
| a pipeline. This pipeline defines the flow of the data. Pipelines can |
| also be edited with a GUI editor and saved as XML so that pipeline |
| libraries can be made with a minimum of effort. |
| </para> |
| |
| <para> |
| The &GStreamer; core function is to provide a framework for plugins, |
| data flow and media type handling/negotiation. It also provides an |
| API to write applications using the various plugins. |
| </para> |
| </sect1> |
| |
| <!-- ############ sect1 ############# --> |
| |
| <sect1 id="section-preface-who" xreflabel="Who Should Read This Guide?"> |
| <title>Who Should Read This Guide?</title> |
| <para> |
| This guide explains how to write new modules for &GStreamer;. The guide is |
| relevant to several groups of people: |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| Anyone who wants to add support for new ways of processing data in |
| &GStreamer;. For example, a person in this group might want to create |
| a new data format converter, a new visualization tool, or a new |
| decoder or encoder. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Anyone who wants to add support for new input and output devices. For |
| example, people in this group might want to add the ability to write |
| to a new video output system or read data from a digital camera or |
| special microphone. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Anyone who wants to extend &GStreamer; in any way. You need to have an |
| understanding of how the plugin system works before you can understand |
| the constraints that the plugin system places on the rest of the code. |
| Also, you might be surprised after reading this at how much can be |
| done with plugins. |
| </para> |
| </listitem> |
| </itemizedlist> |
| <para> |
| This guide is not relevant to you if you only want to use the existing |
| functionality of &GStreamer;, or if you just want to use an application |
| that uses &GStreamer;. If you are only interested in using existing |
| plugins to write a new application - and there are quite a lot of |
| plugins already - you might want to check the &GstAppDevMan;. If you |
| are just trying to get help with a &GStreamer; application, then you |
| should check with the user manual for that particular application. |
| </para> |
| </sect1> |
| |
| <!-- ############ sect1 ############# --> |
| |
| <sect1 id="section-preface-reading" xreflabel="Preliminary Reading"> |
| <title>Preliminary Reading</title> |
| <para> |
| This guide assumes that you are somewhat familiar with the basic workings |
| of &GStreamer;. For a gentle introduction to programming concepts in |
| &GStreamer;, you may wish to read the &GstAppDevMan; first. |
| Also check out the other documentation available on the <ulink type="http" |
| url="http://gstreamer.freedesktop.org/documentation/">&GStreamer; web site</ulink>. |
| </para> |
| <para><!-- synchronize with AppDevMan --> |
| In order to understand this manual, you will need to have a basic |
| understanding of the C language. |
| Since &GStreamer; adheres to the GObject programming model, this guide |
| also assumes that you understand the basics of <ulink type="http" |
| url="http://developer.gnome.org/doc/API/2.0/gobject/index.html">GObject</ulink> |
| programming. |
| You may also want to have a look |
| at Eric Harlow's book <emphasis>Developing Linux Applications with |
| GTK+ and GDK</emphasis>. |
| </para> |
| </sect1> |
| |
| <!-- ############ sect1 ############# --> |
| |
| <sect1 id="section-preface-structure" xreflabel="Structure of This Guide"> |
| <title>Structure of This Guide</title> |
| <para> |
| To help you navigate through this guide, it is divided into several large |
| parts. Each part addresses a particular broad topic concerning &GStreamer; |
| plugin development. The parts of this guide are laid out in the following |
| order: |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| <xref linkend="part-building"/> - |
| Introduction to the structure of a plugin, using an example audio |
| filter for illustration. |
| </para> |
| <para> |
| This part covers all the basic steps you generally need to perform |
| to build a plugin, such as registering the element with &GStreamer; |
| and setting up the basics so it can receive data from and send data |
| to neighbour elements. The discussion begins by giving examples of |
| generating the basic structures and registering an element in |
| <xref linkend="chapter-building-boiler"/>. Then, you will learn how |
| to write the code to get a basic filter plugin working in <xref |
| linkend="chapter-building-pads"/>, <xref |
| linkend="chapter-building-chainfn"/> and <xref |
| linkend="chapter-statemanage-states"/>. |
| </para> |
| <para> |
| After that, we will show some of the GObject concepts on how to |
| make an element configurable for applications and how to do |
| application-element interaction in |
| <xref linkend="chapter-building-args"/> and <xref |
| linkend="chapter-building-signals"/>. Next, you will learn to build |
| a quick test application to test all that you've just learned in |
| <xref linkend="chapter-building-testapp"/>. We will just touch upon |
| basics here. For full-blown application development, you should |
| look at <ulink type="http" |
| url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/index.html">the |
| Application Development Manual</ulink>. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <xref linkend="part-advanced"/> - |
| Information on advanced features of &GStreamer; plugin development. |
| </para> |
| <para> |
| After learning about the basic steps, you should be able to create a |
| functional audio or video filter plugin with some nice features. |
| However, &GStreamer; offers more for plugin writers. This part of the |
| guide includes chapters on more advanced topics, such as scheduling, |
| media type definitions in &GStreamer;, clocks, interfaces and |
| tagging. Since these features are purpose-specific, you can read them |
| in any order, most of them don't require knowledge from other |
| sections. |
| </para> |
| <para> |
| The first chapter, named <xref linkend="chapter-scheduling"/>, |
| will explain some of the basics of element scheduling. It is not |
| very in-depth, but is mostly some sort of an introduction on why |
| other things work as they do. Read this chapter if you're interested |
| in &GStreamer; internals. Next, we will apply this knowledge and |
| discuss another type of data transmission than what you learned in |
| <xref linkend="chapter-building-chainfn"/>: <xref |
| linkend="chapter-scheduling"/>. Loop-based elements will give |
| you more control over input rate. This is useful when writing, for |
| example, muxers or demuxers. |
| </para> |
| <para> |
| Next, we will discuss media identification in &GStreamer; in <xref |
| linkend="chapter-building-types"/>. You will learn how to define |
| new media types and get to know a list of standard media types |
| defined in &GStreamer;. |
| </para> |
| <para> |
| In the next chapter, you will learn the concept of request- and |
| sometimes-pads, which are pads that are created dynamically, either |
| because the application asked for it (request) or because the media |
| stream requires it (sometimes). This will be in <xref |
| linkend="chapter-advanced-request"/>. |
| </para> |
| <para> |
| The next chapter, <xref linkend="chapter-advanced-clock"/>, will |
| explain the concept of clocks in &GStreamer;. You need this |
| information when you want to know how elements should achieve |
| audio/video synchronization. |
| </para> |
| <para> |
| The next few chapters will discuss advanced ways of doing |
| application-element interaction. Previously, we learned on the |
| GObject-ways of doing this in <xref linkend="chapter-building-args"/> |
| and <xref linkend="chapter-building-signals"/>. We will discuss |
| dynamic parameters, which are a way of defining element behaviour |
| over time in advance, in <xref linkend="chapter-dparams"/>. Next, |
| you will learn about interfaces in <xref |
| linkend="chapter-advanced-interfaces"/>. Interfaces are very target- |
| specific ways of application-element interaction, based on GObject's |
| GInterface. Lastly, you will learn about how metadata is handled in |
| &GStreamer; in <xref linkend="chapter-advanced-tagging"/>. |
| </para> |
| <para> |
| The last chapter, <xref linkend="chapter-advanced-events"/>, will |
| discuss the concept of events in &GStreamer;. Events are, on the |
| one hand, another way of doing application-element interaction. It |
| takes care of seeking, for example. On the other hand, it is also |
| a way in which elements interact with each other, such as letting |
| each other know about media stream discontinuities, forwarding tags |
| inside a pipeline and so on. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <xref linkend="part-other"/> - Explanation |
| of writing other plugin types. |
| </para> |
| <para> |
| Because the first two parts of the guide use an audio filter as an |
| example, the concepts introduced apply to filter plugins. But many of |
| the concepts apply equally to other plugin types, including sources, |
| sinks, and autopluggers. This part of the guide presents the issues |
| that arise when working on these more specialized plugin types. The |
| chapter starts with a special focus on elements that can be written |
| using a base-class (<xref linkend="chapter-other-base"/>), and |
| later also goes into writing special types of elements in |
| <xref linkend="chapter-other-oneton"/>, <xref |
| linkend="chapter-other-ntoone"/> and <xref |
| linkend="chapter-other-manager"/>. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <xref linkend="part-appendix"/> - Further |
| information for plugin developers. |
| </para> |
| <para> |
| The appendices contain some information that stubbornly refuses |
| to fit cleanly in other sections of the guide. Most of this section |
| is not yet finished. |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| <para> |
| The remainder of this introductory part of the guide presents a short |
| overview of the basic concepts involved in &GStreamer; plugin development. |
| Topics covered include <xref linkend="section-basics-elements"/>, <xref |
| linkend="section-basics-pads"/>, <xref linkend="section-basics-data"/> and |
| <xref linkend="section-basics-types"/>. If you are already familiar with |
| this information, you can use this short overview to refresh your memory, |
| or you can skip to <xref linkend="part-building"/>. |
| </para> |
| <para> |
| As you can see, there a lot to learn, so let's get started! |
| </para> |
| |
| <itemizedlist> |
| <listitem> |
| <para> |
| Creating compound and complex elements by extending from a GstBin. |
| This will allow you to create plugins that have other plugins embedded |
| in them. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Adding new mime-types to the registry along with typedetect functions. |
| This will allow your plugin to operate on a completely new media type. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </sect1> |
| </chapter> |
