mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-27 02:30:35 +00:00
2abdd0bfda
Original commit message from CVS: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-porting.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-bus.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-pads.xml: * docs/manual/highlevel-components.xml: * docs/manual/manual.xml: * docs/manual/thread.fig: Update (until threads/scheduling) Application Development Manual; remove GstThread, add GstBus, add simple porting checklist, add documentation for tag writing, clocks, make all examples until this part compile and run. * examples/manual/Makefile.am: Update from changes to Application Development Manual; add bus example, remove thread example.
302 lines
9.7 KiB
XML
302 lines
9.7 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
|
<!ENTITY % image-entities SYSTEM "image.entities">
|
|
%image-entities;
|
|
<!ENTITY % version-entities SYSTEM "version.entities">
|
|
%version-entities;
|
|
<!ENTITY % url-entities SYSTEM "url.entities">
|
|
%url-entities;
|
|
|
|
<!ENTITY EXAFOOT "
|
|
<footnote>
|
|
<para>
|
|
The code for this example is automatically extracted from
|
|
the documentation and built under <filename>examples/manual</filename>
|
|
in the GStreamer tarball.
|
|
</para>
|
|
</footnote>
|
|
">
|
|
|
|
<!-- Part 1: Overview -->
|
|
<!ENTITY INTRO SYSTEM "intro-preface.xml">
|
|
<!ENTITY MOTIVATION SYSTEM "intro-motivation.xml">
|
|
<!ENTITY CONCEPTS SYSTEM "intro-basics.xml">
|
|
|
|
<!-- Part 2: Basic Concepts -->
|
|
<!ENTITY INIT SYSTEM "basics-init.xml">
|
|
<!ENTITY ELEMENTS SYSTEM "basics-elements.xml">
|
|
<!ENTITY BINS SYSTEM "basics-bins.xml">
|
|
<!ENTITY BUS SYSTEM "basics-bus.xml">
|
|
<!ENTITY PADS SYSTEM "basics-pads.xml">
|
|
<!ENTITY DATA SYSTEM "basics-data.xml">
|
|
<!ENTITY HELLOWORLD SYSTEM "basics-helloworld.xml">
|
|
|
|
<!-- Part 3: Advanced Concepts -->
|
|
<!ENTITY QUERYEVENTS SYSTEM "advanced-position.xml">
|
|
<!ENTITY METADATA SYSTEM "advanced-metadata.xml">
|
|
<!ENTITY INTERFACES SYSTEM "advanced-interfaces.xml">
|
|
<!ENTITY CLOCKS SYSTEM "advanced-clocks.xml">
|
|
<!ENTITY DPARAMS SYSTEM "advanced-dparams.xml">
|
|
<!ENTITY THREADS SYSTEM "advanced-threads.xml">
|
|
<!ENTITY AUTOPLUGGING SYSTEM "advanced-autoplugging.xml">
|
|
<!ENTITY DATAACCESS SYSTEM "advanced-dataaccess.xml">
|
|
|
|
<!-- Part 4: Higher-level interfaces -->
|
|
<!ENTITY XML SYSTEM "highlevel-xml.xml">
|
|
<!ENTITY COMPONENTS SYSTEM "highlevel-components.xml">
|
|
|
|
<!-- Appendices -->
|
|
<!ENTITY CHECKLIST SYSTEM "appendix-checklist.xml">
|
|
<!ENTITY PORTING SYSTEM "appendix-porting.xml">
|
|
<!ENTITY INTEGRATION SYSTEM "appendix-integration.xml">
|
|
<!ENTITY LICENSING SYSTEM "appendix-licensing.xml">
|
|
<!ENTITY WIN32 SYSTEM "appendix-win32.xml">
|
|
<!ENTITY QUOTES SYSTEM "appendix-quotes.xml">
|
|
|
|
<!ENTITY GStreamer "<application>GStreamer</application>">
|
|
]>
|
|
|
|
<book id="index">
|
|
<bookinfo>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Wim</firstname>
|
|
<surname>Taymans</surname>
|
|
<authorblurb>
|
|
<para>
|
|
<email>wim.taymans@chello.be</email>
|
|
</para>
|
|
</authorblurb>
|
|
</author>
|
|
<author>
|
|
<firstname>Steve</firstname>
|
|
<surname>Baker</surname>
|
|
<authorblurb>
|
|
<para>
|
|
<email>stevebaker_org@yahoo.co.uk</email>
|
|
</para>
|
|
</authorblurb>
|
|
</author>
|
|
<author>
|
|
<firstname>Andy</firstname>
|
|
<surname>Wingo</surname>
|
|
<authorblurb>
|
|
<para>
|
|
<email>wingo@pobox.com</email>
|
|
</para>
|
|
</authorblurb>
|
|
</author>
|
|
<author>
|
|
<firstname>Ronald</firstname>
|
|
<othername>S.</othername>
|
|
<surname>Bultje</surname>
|
|
<authorblurb>
|
|
<para>
|
|
<email>rbultje@ronald.bitfreak.net</email>
|
|
</para>
|
|
</authorblurb>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<legalnotice id="misc-legalnotice">
|
|
<para>
|
|
This material may be distributed only subject to the terms and
|
|
conditions set forth in the Open Publication License, v1.0 or later (the
|
|
latest version is presently available at <ulink url="
|
|
http://www.opencontent.org/opl.shtml"
|
|
type="http">http://www.opencontent.org/opl.shtml</ulink>).
|
|
</para>
|
|
</legalnotice>
|
|
|
|
<title>&GStreamer; Application Development Manual (&GST_VERSION;)</title>
|
|
|
|
</bookinfo>
|
|
|
|
<!-- ############# Introduction & Overview - part ############### -->
|
|
|
|
<part id="part-overview">
|
|
<title>Overview</title>
|
|
<partintro>
|
|
<para>
|
|
&GStreamer; is an exremely powerful and versatile framework for
|
|
creating streaming media applications. Many of the virtues of the
|
|
&GStreamer; framework come from its modularity: &GStreamer; can
|
|
seamlessly incorporate new plugin modules. But because modularity
|
|
and power often come at a cost of greater complexity (consider,
|
|
for example, <ulink
|
|
type="http" url="http://www.omg.org/">CORBA</ulink>), writing new
|
|
applications is not always easy.
|
|
</para>
|
|
<para>
|
|
This guide is intended to help you understand the &GStreamer;
|
|
framework (version &GST_VERSION;) so you can develop applications
|
|
based on it. The first chapters will focus on development of a
|
|
simple audio player, with much effort going into helping you
|
|
understand &GStreamer; concepts. Later chapters will go into
|
|
more advanced topics related to media playback, but also at
|
|
other forms of media processing (capture, editing, etc.).
|
|
</para>
|
|
</partintro>
|
|
|
|
&INTRO;
|
|
&MOTIVATION;
|
|
&CONCEPTS;
|
|
|
|
</part>
|
|
|
|
<!-- ############ Basic concepts - part ############# -->
|
|
|
|
<part id="part-basics">
|
|
<title>Basic Concepts</title>
|
|
<partintro>
|
|
<para>
|
|
In these chapters, we will discuss the basic concepts of &GStreamer;
|
|
and the most-used objects, such as elements, pads and buffers. We
|
|
will use a visual representation of these objects so that we can
|
|
visualize the more complex pipelines you will learn to build later
|
|
on. You will get a first glance at the &GStreamer; API, which should
|
|
be enough for building elementary applications. Later on in this
|
|
part, you will also learn to build a basic command-line application.
|
|
</para>
|
|
<para>
|
|
Note that this part will give a look into the low-level API and
|
|
concepts of &GStreamer;. Once you're going to build applications,
|
|
you might want to use higher-level APIs. Those will be discussed
|
|
later on in this manual.
|
|
</para>
|
|
</partintro>
|
|
|
|
&INIT;
|
|
&ELEMENTS;
|
|
&BINS;
|
|
&BUS;
|
|
&PADS;
|
|
&DATA;
|
|
&HELLOWORLD;
|
|
|
|
</part>
|
|
|
|
<!-- ############ Advanced GStreamer - part ############# -->
|
|
|
|
<part id="part-advanced">
|
|
<title>Advanced &GStreamer; concepts</title>
|
|
<partintro>
|
|
<para>
|
|
In this part we will cover the more advanced features of &GStreamer;.
|
|
With the basics you learned in the previous part you should be
|
|
able to create a <emphasis>simple</emphasis> application. However,
|
|
&GStreamer; provides much more candy than just the basics of playing
|
|
back audio files. In this chapter, you will learn more of the
|
|
low-level features and internals of &GStreamer;.
|
|
</para>
|
|
<para>
|
|
Some parts of this part will serve mostly as an explanation of
|
|
how &GStreamer; works internally; they are not actually needed for
|
|
actual application development. This includes chapter such as the
|
|
ones covering scheduling, autoplugging and synchronization. Other
|
|
chapters, however, discuss more advanced ways of
|
|
pipeline-application interaction, and can turn out to be very useful
|
|
for certain applications. This includes the chapters on metadata,
|
|
querying and events, interfaces, dynamic parameters and pipeline
|
|
data manipulation.
|
|
</para>
|
|
</partintro>
|
|
|
|
&QUERYEVENTS;
|
|
&METADATA;
|
|
&INTERFACES;
|
|
&CLOCKS;
|
|
&DPARAMS;
|
|
&THREADS;
|
|
&AUTOPLUGGING;
|
|
&DATAACCESS;
|
|
|
|
</part>
|
|
|
|
<!-- ############ Higher-level APIs in GStreamer - part ############# -->
|
|
|
|
<part id="part-highlevel">
|
|
<title>Higher-level interfaces for &GStreamer; applications</title>
|
|
<partintro>
|
|
<para>
|
|
In the previous two parts, you have learned many of the internals
|
|
and their corresponding low-level interfaces into &GStreamer;
|
|
application programming. Many people will, however, not need so
|
|
much control (and as much code), but will prefer to use a standard
|
|
playback interface that does most of the difficult internals for
|
|
them. In this chapter, we will introduce you into the concept of
|
|
autopluggers, playback managing elements, XML-based pipelines and
|
|
other such things. Those higher-level interfaces are intended to
|
|
simplify &GStreamer;-based application programming. They do, however,
|
|
also reduce the flexibility. It is up to the application developer
|
|
to choose which interface he will want to use.
|
|
</para>
|
|
</partintro>
|
|
|
|
&COMPONENTS;
|
|
&XML;
|
|
|
|
</part>
|
|
|
|
<!-- ############ Appendices - part ############# -->
|
|
|
|
<part id="part-appendices">
|
|
<title>Appendices</title>
|
|
<partintro>
|
|
<para>
|
|
By now, you've learned all about the internals of &GStreamer; and
|
|
application programming using the &GStreamer; framework. This part
|
|
will go into some random bits that are useful to know if you're
|
|
going to use &GStreamer; for serious application programming. It
|
|
will touch upon things related to integration with popular desktop
|
|
environments that we run on (GNOME, KDE, OS X, Windows), it will
|
|
shortly explain how applications included with &GStreamer; can help
|
|
making your life easier, and some information on debugging.
|
|
</para>
|
|
<para>
|
|
In addition, we also provide a porting guide which will explain
|
|
easily how to port &GStreamer;-0.8 applications to &GStreamer;-0.9.
|
|
</para>
|
|
</partintro>
|
|
|
|
<!--
|
|
Idea:
|
|
* Debugging and error handling
|
|
- 'error' signal in pipelines
|
|
- checking return values and how to handle them
|
|
- using signals for pipeline states
|
|
- gst-debug
|
|
- programs
|
|
* Desktop integration
|
|
- Linux/UNIX
|
|
. {x,xv}imagesink
|
|
. {oss,alsa}sink
|
|
. {v4l,v4l2,oss,alsa}src
|
|
- GNOME
|
|
. GConf ({video,audio}{src,sink})
|
|
. gnomevfssrc, gnomevfssink
|
|
. popt
|
|
. app examples (RB, Totem, gnome-media, ...)
|
|
- KDE
|
|
. kiosrc
|
|
. app examples (JuK, AmaroK)
|
|
. ask Scott/Mark
|
|
- Mac OS X
|
|
. native video/audio sink
|
|
- Windows
|
|
. build etc.
|
|
* Quotes from devs
|
|
- table please...
|
|
-->
|
|
|
|
&CHECKLIST;
|
|
&PORTING;
|
|
&INTEGRATION;
|
|
&LICENSING;
|
|
&WIN32;
|
|
"ES;
|
|
|
|
</part>
|
|
</book>
|