handling and for media type detection.
[pad-caps]: application-development/basics/pads.md#capabilities-of-a-pad
-[pwg-type-defs]: pwg/advanced/building-types.md
+[pwg-type-defs]: plugin-development/advanced/building-types.md
## Media stream type detection
## Embedding static elements in your application
-The [Plugin Writer's
-Guide](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html)
+The [Plugin Writer's Guide](plugin-development/index.md)
describes in great detail how to write elements for the GStreamer
framework. In this section, we will solely discuss how to embed such
elements statically in your application. This can be useful for
Custom bins can be created with a plugin or from the application. You
will find more information about creating custom bin in the [Plugin
-Writers
-Guide](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html).
+Writer's Guide](plugin-development/index.md)
Examples of such custom bins are the playbin and uridecodebin elements
from[gst-plugins-base](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/index.html).
Here, we will briefly describe what capabilities are and how to use
them, enough to get an understanding of the concept. For an in-depth
look into capabilities and a list of all capabilities defined in
-GStreamer, see the [Plugin Writers
-Guide](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html).
+GStreamer, see the [Plugin Writers Guide](plugin-development/index.md)
Capabilities are attached to pad templates and to pads. For pad
templates, it will describe the types of media that may stream over a
This book is about GStreamer from an application developer's point of
view; it describes how to write a GStreamer application using the
GStreamer libraries and tools. For an explanation about writing plugins,
-we suggest the [Plugin Writers Guide](pwg/index.md).
+we suggest the [Plugin Writer's Guide](plugin-development/index.md).
Also check out the other documentation available on the [GStreamer web
site](http://gstreamer.freedesktop.org/documentation/).
### Caps
The CAPS event contains the format description of the following buffers.
-See [Caps negotiation](pwg/advanced/negotiation.md) for more information
+See [Caps negotiation][caps-negotiation] for more information
about negotiation.
+[caps-negotiation]: plugin-development/advanced/negotiation.md
+
### Segment
A segment event is sent downstream to announce the range of valid
Tagging events are being sent downstream to indicate the tags as parsed
from the stream data. This is currently used to preserve tags during
stream transcoding from one format to the other. Tags are discussed
-extensively in [Tagging (Metadata and
-Streaminfo)](pwg/advanced/tagging.md). Most elements will simply
-forward the event by calling `gst_pad_event_default ()`.
+extensively in [Tagging (Metadata and Streaminfo)][metadata]. Most elements
+will simply forward the event by calling `gst_pad_event_default ()`.
The tag event is created using the function `gst_event_new_tag ()`, but
more often elements will send a tag event downstream that will be
functions require a filled-in taglist as argument, which they will take
ownership of.
-Elements parsing this event can use the function `gst_event_parse_tag
-()` to acquire the taglist that the event contains.
+Elements parsing this event can use the function `gst_event_parse_tag ()` to
+acquire the taglist that the event contains.
+
+[metadata]: plugin-development/advanced/tagging.md
### End of Stream (EOS)
### Quality Of Service (QOS)
The QOS event contains a report about the current real-time performance
-of the stream. See more info in [Quality Of Service
-(QoS)](pwg/advanced/qos.md).
+of the stream. See more info in [Quality Of Service (QoS)][qos].
+
+[qos]: plugin-development/advanced/qos.md
### Seek Request
# Interfaces
-Previously, in the chapter [Adding
-Properties](pwg/building/args.md), we have introduced the concept of
-GObject properties of controlling an element's behaviour. This is very
-powerful, but it has two big disadvantages: first of all, it is too
-generic, and second, it isn't dynamic.
+Previously, in the chapter [Adding Properties][plugin-properties], we have
+introduced the concept of GObject properties of controlling an element's
+behaviour. This is very powerful, but it has two big disadvantages: first of
+all, it is too generic, and second, it isn't dynamic.
The first disadvantage is related to the customizability of the end-user
interface that will be built to control the element. Some properties are
interfaces should be built *next to* properties. There are two important
reasons for this. First of all, properties can be more easily
introspected. Second, properties can be specified on the commandline
-(`gst-launch`).
+(`gst-launch-1.0`).
+
+[plugin-properties]: plugin-development/building/args.md
## How to Implement Interfaces
## Video Overlay Interface
-The \#GstVideoOverlay interface is used for 2 main purposes :
+The `GstVideoOverlay` interface is used for 2 main purposes :
- To get a grab on the Window where the video sink element is going to
render. This is achieved by either being informed about the Window
rendering.
- To force a redrawing of the latest video frame the video sink
- element displayed on the Window. Indeed if the \#GstPipeline is in
- \#GST\_STATE\_PAUSED state, moving the Window around will damage its
+ element displayed on the Window. Indeed if the `GstPipeline` is in
+ `GST\_STATE\_PAUSED` state, moving the Window around will damage its
content. Application developers will want to handle the Expose
events themselves and force the video sink element to refresh the
Window's content.
- In 0.10, buffers have caps attached to them. Elements should
allocate new buffers with `gst_pad_alloc_buffer ()`. See [Caps
- negotiation](pwg/advanced/negotiation.md) for more details.
+ negotiation](plugin-development/advanced/negotiation.md) for more details.
- Most functions returning an object or an object property have been
changed to return its own reference rather than a constant reference
some more work. Pads get assigned a scheduling mode, based on which
they can either operate in random access-mode, in pipeline driving
mode or in push-mode. all this is documented in detail in [Different
- scheduling modes](pwg/advanced/scheduling.md). As a result of this, the
+ scheduling modes](plugin-development/advanced/scheduling.md). As a result of this, the
bytestream object no longer exists. Elements requiring byte-level
access should now use random access on their sinkpads.
- Negotiation is asynchronous. This means that downstream negotiation
is done as data comes in and upstream negotiation is done whenever
renegotiation is required. All details are described in [Caps
- negotiation](pwg/advanced/negotiation.md).
+ negotiation](plugin-development/advanced/negotiation.md).
- For as far as possible, elements should try to use existing base
classes in 0.10. Sink and source elements, for example, could derive
from `GstBaseSrc` and `GstBaseSink`. Audio sinks or sources could
even derive from audio-specific base classes. All existing base
classes have been discussed in [Pre-made base
- classes](pwg/other/base.md) and the next few chapters.
+ classes](plugin-development/other/base.md) and the next few chapters.
- In 0.10, event handling and buffers are separated once again. This
means that in order to receive events, one no longer has to set the
need to be able to accept and process data already in the
`GST_STATE_PAUSED` state now (i.e. when prerolling the pipeline).
More details can be found in [What are
- states?](pwg/building/statemanage-states.md).
+ states?](plugin-development/building/statemanage-states.md).
- If your plugin's state change function hasn't been superseded by
virtual start() and stop() methods of one of the new base classes,
Pads are created from these static templates in the element's `_init ()`
function using `gst_pad_new_from_static_template ()`. In order to create
a new pad from this template using `gst_pad_new_from_static_template
-()`, you will need to declare the pad template as a global variable.
-More on this subject in [Specifying the pads](pwg/building/pads.md).
+()`, you will need to declare the pad template as a global variable. More on
+this subject in [Specifying the pads][pads].
static GstStaticPadTemplate sink_factory = [..],
src_factory = [..];
surrounded by square brackets (“\[” and “\]”) are ranges. Multiple sets
of types are supported too, and should be separated by a semicolon
(“;”). Later, in the chapter on pads, we will see how to use types
-to know the exact format of a stream: [Specifying the
-pads](pwg/building/pads.md).
+to know the exact format of a stream: [Specifying the pads][pads].
+
+[pads]: plugin-development/building/pads.md
## Constructor Functions
event data from its sink pad to its source pad without modification. But
by the end of this part of the guide, you will learn to add some more
interesting functionality, including properties and signal handlers. And
-after reading the next part of the guide, [Advanced Filter
-Concepts](pwg/advanced/index.md), you will be able to add even more
-functionality to your plugins.
+after reading the next part of the guide, [Advanced Filter Concepts][advanced],
+you will be able to add even more functionality to your plugins.
+
+[advanced]: plugin-development/advanced/index.md
## Managing filter state
If at all possible, your element should derive from one of the new base
-classes ([Pre-made base classes](pwg/other/base.md)). There are
+classes ([Pre-made base classes](plugin-development/other/base.md)). There are
ready-made general purpose base classes for different types of sources,
sinks and filter/transformation elements. In addition to those,
specialised base classes exist for audio and video elements and others.
- The other contents of the event depend on the specific event type.
Events will be discussed extensively in [Events: Seeking, Navigation and
-More](pwg/advanced/events.md). Until then, the only event that will
-be used is the *EOS* event, which is used to indicate the end-of-stream
+More](plugin-development/advanced/events.md). Until then, the only event that
+will be used is the *EOS* event, which is used to indicate the end-of-stream
(usually end-of-file).
See the *GStreamer Library Reference* for the current implementation
can ask a GstBufferPool or GstAllocator from the downstream peer
element. If downstream is able to provide these objects, upstream can
use them to allocate buffers. See more in [Memory
-allocation](pwg/advanced/allocation.md).
+allocation](plugin-development/advanced/allocation.md).
Many sink elements have accelerated methods for copying data to
hardware, or have direct access to hardware. It is common for these
match up correctly when linking pads between elements. Each link that is
made between elements has a specified type and optionally a set of
properties. See more about caps negotiation in [Caps
-negotiation](pwg/advanced/negotiation.md).
+negotiation](plugin-development/advanced/negotiation.md).
### The Basic Types
contains the name ("media type") and a description of the type, the
properties associated with the type, and the meaning of each property. A
full list of supported types is included in [List of Defined
-Types](pwg/advanced/building-types.md#list-of-defined-types).
+Types](plugin-development/advanced/building-types.md#list-of-defined-types).
<table>
<caption>Table of Example Types</caption>
GStreamer plugin development. The parts of this guide are laid out in
the following order:
- - [Building a Plugin](pwg/building/index.md) - Introduction to the
+ - [Building a Plugin][building] - Introduction to the
structure of a plugin, using an example audio filter for
illustration.
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
- [Constructing the Boilerplate](pwg/building/boiler.md). Then,
+ [Constructing the Boilerplate][boilerplate]. Then,
you will learn how to write the code to get a basic filter plugin
- working in [Specifying the pads](pwg/building/pads.md), [The
- chain function](pwg/building/chainfn.md) and [What are
- states?](pwg/building/statemanage-states.md).
+ working in [Specifying the pads][pads], [The chain function][chainfunc]
+ and [What are states?][states].
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 [Adding
- Properties](pwg/building/args.md) and
- [Signals](pwg/building/signals.md). Next, you will learn to
+ Properties][properties] and [Signals][signals]. Next, you will learn to
build a quick test application to test all that you've just learned
- in [Building a Test Application](pwg/building/testapp.md). We
+ in [Building a Test Application][testapp]. We
will just touch upon basics here. For full-blown application
development, you should look at [the Application Development
Manual](application-development/index.md).
- - [Advanced Filter Concepts](pwg/advanced/index.md) - Information on
+ - [Advanced Filter Concepts][advanced] - Information on
advanced features of GStreamer plugin development.
After learning about the basic steps, you should be able to create a
order, most of them don't require knowledge from other sections.
The first chapter, named [Different scheduling
- modes](pwg/advanced/scheduling.md), will explain some of the basics of
+ modes][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 [The chain
- function](pwg/building/chainfn.md): [Different scheduling
- modes](pwg/advanced/scheduling.md). Loop-based elements will give you
+ than what you learned in [The chain function][chainfunc]: [Different
+ scheduling modes][scheduling]. Loop-based elements will give you
more control over input rate. This is useful when writing, for
example, muxers or demuxers.
Next, we will discuss media identification in GStreamer in [Types
- and Properties](pwg/advanced/building-types.md). You will learn how to
+ and Properties][types]. You will learn how to
define new media types and get to know a list of standard media
types defined in GStreamer.
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 [Request and
- Sometimes pads](pwg/advanced/request.md).
+ Sometimes pads][request-pads].
- The next chapter, [Clocking](pwg/advanced/clock.md), will
+ The next chapter, [Clocking][clocks], will
explain the concept of clocks in GStreamer. You need this
information when you want to know how elements should achieve
audio/video synchronization.
The next few chapters will discuss advanced ways of doing
application-element interaction. Previously, we learned on the
- GObject-ways of doing this in [Adding
- Properties](pwg/building/args.md) and
- [Signals](pwg/building/signals.md). We will discuss dynamic
+ GObject-ways of doing this in [Adding Properties][properties] and
+ [Signals][signals]. We will discuss dynamic
parameters, which are a way of defining element behaviour over time
- in advance, in [Supporting Dynamic Parameters](pwg/advanced/dparams.md).
- Next, you will learn about interfaces in
- [Interfaces](pwg/advanced/interfaces.md). 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 [Tagging (Metadata and
- Streaminfo)](pwg/advanced/tagging.md).
-
- The last chapter, [Events: Seeking, Navigation and
- More](pwg/advanced/events.md), 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
+ in advance, in [Supporting Dynamic Parameters][dynamic-params].
+ Next, you will learn about interfaces in [Interfaces][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 [Tagging (Metadata and
+ Streaminfo)][tagging].
+
+ The last chapter, [Events: Seeking, Navigation and More][events], will
+ discuss the concept of events in GStreamer. Events are another way of
+ doing application-element interaction. They take care of seeking, for
+ example. They are also yet another 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.
- - [Creating special element types](pwg/other/index.md) - Explanation of
+ - [Creating special element types][element-types] - Explanation of
writing other plugin types.
Because the first two parts of the guide use an audio filter as an
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 ([Pre-made base
- classes](pwg/other/base.md)), and later also goes into writing
- special types of elements in [Writing a Demuxer or
- Parser](pwg/other/oneton.md), [Writing a N-to-1 Element or
- Muxer](pwg/other/ntoone.md) and [Writing a
- Manager](pwg/other/manager.md).
+ be written using a base-class ([Pre-made base classes][base-classes]),
+ and later also goes into writing special types of elements in [Writing a
+ Demuxer or Parser][one-to-n], [Writing a N-to-1 Element or Muxer][n-to-one]
+ and [Writing a Manager][manager].
- - [Appendices](pwg/appendix/index.md) - Further information for plugin
- developers.
+ - [Appendices][appendix] - Further information for plugin developers.
The appendices contain some information that stubbornly refuses to
fit cleanly in other sections of the guide. Most of this section is
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 [Elements and
-Plugins](pwg/introduction/basics.md#elements-and-plugins),
-[Pads](pwg/introduction/basics.md#pads), [GstMiniObject, Buffers and
-Events](pwg/introduction/basics.md#gstminiobject-buffers-and-events) and
-[Media types and
-Properties](pwg/introduction/basics.md#media-types-and-properties). If you
-are already familiar with this information, you can use this short
-overview to refresh your memory, or you can skip to [Building a
-Plugin](pwg/building/index.md).
+Topics covered include [Elements and Plugins][intro-elements],
+[Pads][intro-pads], [GstMiniObject, Buffers and Events][intro-miniobjects]
+and [Media types and Properties][intro-mediatypes]. If you are already
+familiar with this information, you can use this short overview to
+refresh your memory, or you can skip to [Building a Plugin][building].
As you can see, there a lot to learn, so let's get started\!
- Adding new media types to the registry along with typedetect
functions. This will allow your plugin to operate on a completely
new media type.
+
+[building]: plugin-development/building/index.md
+[boilerplate]: plugin-development/building/boiler.md
+[pads]: plugin-development/building/pads.md
+[chainfunc]: plugin-development/building/chainfn.md
+[states]: plugin-development/building/statemanage-states.md
+[properties]: plugin-development/building/args.md
+[signals]: plugin-development/building/signals.md
+[testapp]: plugin-development/building/testapp.md
+[advanced]: plugin-development/advanced/index.md
+[scheduling]: plugin-development/advanced/scheduling.md
+[types]: plugin-development/advanced/building-types.md
+[request-pads]: plugin-development/advanced/request.md
+[clocks]: plugin-development/advanced/clock.md
+[dynamic-params]: plugin-development/advanced/dparams.md
+[interfaces]: plugin-development/advanced/interfaces.md
+[tagging]: plugin-development/advanced/tagging.md
+[events]: plugin-development/advanced/events.md
+[element-types]: plugin-development/other/index.md
+[base-classes]: plugin-development/other/base.md
+[one-to-n]: plugin-development/other/oneton.md
+[n-to-one]: plugin-development/other/ntoone.md
+[manager]: plugin-development/other/manager.md
+[appendix]: plugin-development/appendix/index.md
+[intro-elements]: plugin-development/introduction/basics.md#elements-and-plugins
+[intro-pads]: plugin-development/introduction/basics.md#pads
+[intro-miniobjects]: plugin-development/introduction/basics.md#gstminiobject-buffers-and-events
+[intro-mediatypes]: plugin-development/introduction/basics.md#media-types-and-properties
## Writing a source
-In the previous part, particularly [Providing random
-access](pwg/advanced/scheduling.md#providing-random-access), we have learned
-that some types of elements can provide random access. This applies most
-definitely to source elements reading from a randomly seekable location,
-such as file sources. However, other source elements may be better
+In the previous part, particularly [Providing random access][random-access],
+we have learned that some types of elements can provide random access. This
+applies most definitely to source elements reading from a randomly seekable
+location, such as file sources. However, other source elements may be better
described as a live source element, such as a camera source, an audio
card source and such; those are not seekable and do not provide
byte-exact access. For all such use cases, GStreamer provides two base
or `mmap ()`'ed memory areas, as data pointers in buffers returned from
the `create()` virtual function.
+[random-access]: plugin-development/advanced/scheduling.md#providing-random-access
+
### Writing an audio source
An audio source is nothing more but a special case of a pushsource.
# Writing a N-to-1 Element or Muxer
N-to-1 elements have been previously mentioned and discussed in both
-[Request and Sometimes pads](pwg/advanced/request.md) and in
-[Different scheduling modes](pwg/advanced/scheduling.md). The main noteworthy
+[Request and Sometimes pads][request-pads] and in
+[Different scheduling modes][scheduling]. The main noteworthy
thing about N-to-1 elements is that each pad is push-based in its own
thread, and the N-to-1 element synchronizes those streams by
expected-timestamp-based logic. This means it lets all streams wait
If you need anything more difficult, such as "don't-grab-a-new-buffer
until a given timestamp" or something like that, you'll need to do this
yourself.
+
+[request-pads]: plugin-development/advanced/request.md
+[scheduling]: plugin-development/advanced/scheduling.md
they only cut the stream into buffers, they don't touch the data
otherwise.
-As mentioned previously in [Caps negotiation](pwg/advanced/negotiation.md),
+As mentioned previously in [Caps negotiation][negotiation],
demuxers should use fixed caps, since their data type will not change.
-As discussed in [Different scheduling modes](pwg/advanced/scheduling.md),
+As discussed in [Different scheduling modes][scheduling],
demuxer elements can be written in multiple ways:
- They can be the driving force of the pipeline, by running their own
if your element only accepts one mode, it may be required to implement
multiple modes to work in combination with all sorts of applications,
such as editing. Also, performance may become better if you implement
-multiple modes. See [Different scheduling modes](pwg/advanced/scheduling.md)
+multiple modes. See [Different scheduling modes][scheduling]
to see how an element can accept multiple scheduling modes.
+
+[negotiation]: plugin-development/advanced/negotiation.md
+[scheduling]: plugin-development/advanced/scheduling.md