mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-08 13:18:52 +00:00
Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * 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-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
323 lines
9.9 KiB
XML
323 lines
9.9 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 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 SCHEDULERS SYSTEM "advanced-schedulers.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 DEBUGGING SYSTEM "appendix-debugging.xml">
|
|
<!ENTITY PROGRAMS SYSTEM "appendix-programs.xml">
|
|
<!ENTITY GNOME SYSTEM "appendix-gnome.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;
|
|
&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;, such as threads,
|
|
scheduling, synchronization, metadata, interfaces and dynamic
|
|
parameters.
|
|
</para>
|
|
</partintro>
|
|
|
|
<!--
|
|
Idea:
|
|
* Querying and events
|
|
- seeking
|
|
- getting stream length
|
|
- prerolls and why
|
|
* Stream info
|
|
- pads info (see 2.4)
|
|
- tags
|
|
- inserting tags
|
|
* Interfaces
|
|
- each
|
|
* Clocks & Synchronization
|
|
- stress that it's automated
|
|
* Dynamic parameters
|
|
- ..
|
|
* Threading
|
|
- gstthread & queues
|
|
- buffering (network, live network/video/audio source)
|
|
- when 1-to-N, N-to-1 and N-to-N elements need threads
|
|
* Scheduling
|
|
- loop/chain/get etc. (internals)
|
|
- opt
|
|
* Autoplugging principles
|
|
- type detection
|
|
- dynamic element lookup (registry, factories and categories)
|
|
- reference part4!
|
|
- Hello world 2
|
|
* Pipeline manipulation
|
|
- data manipulation (identity, fakesrc, fakesink)
|
|
- probes (both events and data)
|
|
- length manipulation (managers, PWG)
|
|
- explain how to embed elements in applications
|
|
- explain why separate elements are to be preferred
|
|
-->
|
|
|
|
&QUERYEVENTS;
|
|
&METADATA;
|
|
&INTERFACES;
|
|
&CLOCKS;
|
|
&DPARAMS;
|
|
&THREADS;
|
|
&SCHEDULERS;
|
|
&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>
|
|
</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...
|
|
-->
|
|
|
|
&DEBUGGING;
|
|
&PROGRAMS;
|
|
&GNOME;
|
|
&WIN32;
|
|
"ES;
|
|
|
|
</part>
|
|
</book>
|