mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-10 19:31:12 +00:00
296 lines
14 KiB
XML
296 lines
14 KiB
XML
|
|
<!-- ############ 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 or performance.
|
|
</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.
|
|
</para>
|
|
|
|
<para>
|
|
The &GStreamer; core function is to provide a framework for plugins,
|
|
data flow, synchronization 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/gobject/stable/pt01.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 media 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>
|