ZeroDream/gstreamer
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update

Browse Source
This commit is contained in:
Akkariin Meiko
2022-03-12 03:16:09 +08:00
Unverified
parent 12b76e0c7a
commit 27c4ec74a1
10075 changed files with 5122287 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
subprojects/gst-docs/markdown/application-development/appendix/checklist-element.md
+131
View File
@@ -0,0 +1,131 @@
---
title: Things to check when writing an application
...
# Things to check when writing an application
This chapter contains a fairly random selection of things that can be
useful to keep in mind when writing GStreamer-based applications. It's
up to you how much you're going to use the information provided here. We
will shortly discuss how to debug pipeline problems using GStreamer
applications. Also, we will touch upon how to acquire knowledge about
plugins and elements and how to test simple pipelines before building
applications around them.
## Good programming habits
- Always add a `GstBus` handler to your pipeline. Always report errors
in your application, and try to do something with warnings and
information messages, too.
- Always check return values of GStreamer functions. Especially, check
return values of `gst_element_link ()` and `gst_element_set_state
()`.
- Dereference return values of all functions returning a non-base
type, such as `gst_element_get_pad ()`. Also, always free non-const
string returns, such as `gst_object_get_name ()`.
- Always use your pipeline object to keep track of the current state
of your pipeline. Don't keep private variables in your application.
Also, don't update your user interface if a user presses the “play”
button. Instead, listen for the “state-changed” message on the
`GstBus` and only update the user interface whenever this message is
received.
- Report all bugs that you find to Gitlab at
[https://gitlab.freedesktop.org/gstreamer/](https://gitlab.freedesktop.org/gstreamer).
## Debugging
Applications can make use of the extensive GStreamer debugging system to
debug pipeline problems. Elements will write output to this system to
log what they're doing. It's not used for error reporting, but it is
very useful for tracking what an element is doing exactly, which can
come in handy when debugging application issues (such as failing seeks,
out-of-sync media, etc.).
Most GStreamer-based applications accept the commandline option
`--gst-debug=LIST` and related family members. The list consists of a
comma-separated list of category/level pairs, which can set the
debugging level for a specific debugging category. For example,
`--gst-debug=oggdemux:5` would turn on debugging for the Ogg demuxer
element. You can use wildcards as well. A debugging level of 0 will turn
off all debugging, and a level of 9 will turn on all debugging.
Intermediate values only turn on some debugging (based on message
severity; 2, for example, will only display errors and warnings). Here's
a list of all available options:
- `--gst-debug-help` will print available debug categories and exit.
- `--gst-debug-level=LEVEL` will set the default debug level (which
can range from 0 (no output) to 9 (everything)).
- `--gst-debug=LIST` takes a comma-separated list of
category\_name:level pairs to set specific levels for the individual
categories. Example: `GST_AUTOPLUG:5,avidemux:3`. Alternatively, you
can also set the `GST_DEBUG` environment variable, which has the
same effect.
- `--gst-debug-no-color` will disable color debugging. You can also
set the GST\_DEBUG\_NO\_COLOR environment variable to 1 if you want
to disable colored debug output permanently. Note that if you are
disabling color purely to avoid messing up your pager output, try
using `less -R`.
- `--gst-debug-color-mode=MODE` will change debug log coloring mode.
MODE can be one of the following: `on`, `off`, `auto`, `disable`,
`unix`. You can also set the GST\_DEBUG\_COLOR\_MODE environment
variable if you want to change colored debug output permanently.
Note that if you are disabling color purely to avoid messing up your
pager output, try using `less -R`.
- `--gst-debug-disable` disables debugging altogether.
- `--gst-plugin-spew` enables printout of errors while loading
GStreamer plugins.
## Conversion plugins
GStreamer contains a bunch of conversion plugins that most applications
will find useful. Specifically, those are videoscalers (videoscale),
colorspace convertors (videoconvert), audio format convertors and
channel resamplers (audioconvert) and audio samplerate convertors
(audioresample). Those convertors don't do anything when not required,
they will act in passthrough mode. They will activate when the hardware
doesn't support a specific request, though. All applications are
recommended to use those elements.
## Utility applications provided with GStreamer
GStreamer comes with a default set of command-line utilities that can
help in application development. We will discuss only `gst-launch` and
`gst-inspect` here.
### `gst-launch`
`gst-launch` is a simple script-like commandline application that can be
used to test pipelines. For example, the command `gst-launch
audiotestsrc ! audioconvert !
audio/x-raw,channels=2 ! alsasink` will run a pipeline which generates a
sine-wave audio stream and plays it to your ALSA audio card.
`gst-launch` also allows the use of threads (will be used automatically
as required or as queue elements are inserted in the pipeline) and bins
(using brackets, so “(” and “)”). You can use dots to imply padnames on
elements, or even omit the padname to automatically select a pad. Using
all this, the pipeline `gst-launch filesrc location=file.ogg ! oggdemux
name=d
d. ! queue ! theoradec ! videoconvert ! xvimagesink
d. ! queue ! vorbisdec ! audioconvert ! audioresample ! alsasink
` will play an Ogg file containing a Theora video-stream and a Vorbis
audio-stream. You can also use autopluggers such as decodebin on the
commandline. See the manual page of `gst-launch` for more information.
### `gst-inspect`
`gst-inspect` can be used to inspect all properties, signals, dynamic
parameters and the object hierarchy of an element. This can be very
useful to see which `GObject` properties or which signals (and using
what arguments) an element supports. Run `gst-inspect fakesrc` to get an
idea of what it does. See the manual page of `gst-inspect` for more
information.
subprojects/gst-docs/markdown/application-development/appendix/compiling.md
+67
View File
@@ -0,0 +1,67 @@
---
title: Compiling
...
# Compiling
This section talks about the different things you can do when building
and shipping your applications and plugins.
## Embedding static elements in your application
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
application-specific elements that have no use elsewhere in GStreamer.
Dynamically loaded plugins contain a structure that's defined using
`GST_PLUGIN_DEFINE ()`. This structure is loaded when the plugin is
loaded by the GStreamer core. The structure contains an initialization
function (usually called `plugin_init`) that will be called right after
that. It's purpose is to register the elements provided by the plugin
with the GStreamer framework. If you want to embed elements directly in
your application, the only thing you need to do is to replace
`GST_PLUGIN_DEFINE ()` with a call to `gst_plugin_register_static ()`.
As soon as you call `gst_plugin_register_static ()`, the elements will
from then on be available like any other element, without them having to
be dynamically loadable libraries. In the example below, you would be
able to call `gst_element_factory_make
("my-element-name", "some-name")` to create an instance of the element.
``` c
/*
* Here, you would write the actual plugin code.
*/
[..]
static gboolean
register_elements (GstPlugin *plugin)
{
return GST_ELEMENT_REGISTER (my_element_name, plugin);
}
static
my_code_init (void)
{
...
gst_plugin_register_static (
GST_VERSION_MAJOR,
GST_VERSION_MINOR,
"my-private-plugins",
"Private elements of my application",
register_elements,
VERSION,
"LGPL",
"my-application-source",
"my-application",
"http://www.my-application.net/")
...
}
```
subprojects/gst-docs/markdown/application-development/appendix/index.md
+17
View File
@@ -0,0 +1,17 @@
---
title: Appendices
...
# Appendices
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.
In addition, we also provide a porting guide which will explain easily
how to port GStreamer-0.10 applications to GStreamer-1.0.
subprojects/gst-docs/markdown/application-development/appendix/integration.md
+220
View File
@@ -0,0 +1,220 @@
---
title: Integration
...
# Integration
GStreamer tries to integrate closely with operating systems (such as
Linux and UNIX-like operating systems, OS X or Windows) and desktop
environments (such as GNOME or KDE). In this chapter, we'll mention some
specific techniques to integrate your application with your operating
system or desktop environment of choice.
## Linux and UNIX-like operating systems
GStreamer provides a basic set of elements that are useful when
integrating with Linux or a UNIX-like operating system.
- For audio input and output, GStreamer provides input and output
elements for several audio subsystems. Amongst others, GStreamer
includes elements for ALSA (alsasrc, alsasink), OSS (osssrc,
osssink) Pulesaudio (pulsesrc, pulsesink) and Sun audio
(sunaudiosrc, sunaudiomixer, sunaudiosink).
- For video input, GStreamer contains source elements for Video4linux2
(v4l2src, v4l2element, v4l2sink).
- For video output, GStreamer provides elements for output to
X-windows (ximagesink), Xv-windows (xvimagesink; for
hardware-accelerated video), direct-framebuffer (dfbimagesink) and
openGL image contexts (glsink).
## GNOME desktop
GStreamer has been the media backend of the
[GNOME](http://www.gnome.org/) desktop since GNOME-2.2 onwards.
Nowadays, a whole bunch of GNOME applications make use of GStreamer for
media-processing, including (but not limited to)
[Rhythmbox](http://www.rhythmbox.org/),
[Videos](https://wiki.gnome.org/Apps/Videos) and [Sound
Juicer](https://wiki.gnome.org/Apps/SoundJuicer).
Most of these GNOME applications make use of some specific techniques to
integrate as closely as possible with the GNOME desktop:
- GNOME applications usually call `gtk_init ()` to parse command-line
options and initialize GTK. GStreamer applications would normally
call `gst_init ()` to do the same for GStreamer. This would mean
that only one of the two can parse command-line options. To work
around this issue, GStreamer can provide a GLib `GOptionGroup` which
can be passed to `gnome_program_init ()`. The following example
requires GTK 2.6 or newer (previous GTK versions do not support
command line parsing via GOption yet)
``` c
#include <gtk/gtk.h>
#include <gst/gst.h>
static gchar **cmd_filenames = NULL;
static GOptionEntries cmd_options[] = {
/* here you can add command line options for your application. Check
* the GOption section in the GLib API reference for a more elaborate
* example of how to add your own command line options here */
/* at the end we have a special option that collects all remaining
* command line arguments (like filenames) for us. If you don't
* need this, you can safely remove it */
{ G_OPTION_REMAINING, 0, 0, G_OPTION_ARG_FILENAME_ARRAY, &cmd_filenames,
"Special option that collects any remaining arguments for us" },
/* mark the end of the options array with a NULL option */
{ NULL, }
};
/* this should usually be defined in your config.h */
#define VERSION "0.0.1"
gint
main (gint argc, gchar **argv)
{
GOptionContext *context;
GOptionGroup *gstreamer_group, *gtk_group;
GError *err = NULL;
context = g_option_context_new ("gtk-demo-app");
/* get command line options from GStreamer and add them to the group */
gstreamer_group = gst_init_get_option_group ();
g_option_context_add_group (context, gstreamer_group);
gtk_group = gtk_get_option_group (TRUE);
g_option_context_add_group (context, gtk_group);
/* add our own options. If you are using gettext for translation of your
* strings, use GETTEXT_PACKAGE here instead of NULL */
g_option_context_add_main_entries (context, cmd_options, NULL);
/* now parse the commandline options, note that this already
* calls gtk_init() and gst_init() */
if (!g_option_context_parse (ctx, &argc, &argv, &err)) {
g_print ("Error initializing: %s\n", err->message);
g_clear_error (&err);
g_option_context_free (ctx);
exit (1);
}
g_option_context_free (ctx);
/* any filenames we got passed on the command line? parse them! */
if (cmd_filenames != NULL) {
guint i, num;
num = g_strv_length (cmd_filenames);
for (i = 0; i < num; ++i) {
/* do something with the filename ... */
g_print ("Adding to play queue: %s\n", cmd_filenames[i]);
}
g_strfreev (cmd_filenames);
cmd_filenames = NULL;
}
[..]
}
```
- GNOME uses Pulseaudio for audio, use the pulsesrc and pulsesink
elements to have access to all the features.
- GStreamer provides data input/output elements for use with the GIO
VFS system. These elements are called “giosrc” and “giosink”. The
deprecated GNOME-VFS system is supported too but shouldn't be used
for any new applications.
## KDE desktop
GStreamer has been proposed for inclusion in KDE-4.0. Currently,
GStreamer is included as an optional component, and it's used by several
KDE applications, including [AmaroK](http://amarok.kde.org/),
[KMPlayer](http://www.xs4all.nl/~jjvrieze/kmplayer.html) and
[Kaffeine](http://kaffeine.sourceforge.net/).
Although not yet as complete as the GNOME integration bits, there are
already some KDE integration specifics available. This list will
probably grow as GStreamer starts to be used in KDE-4.0:
- AmaroK contains a kiosrc element, which is a source element that
integrates with the KDE VFS subsystem KIO.
## OS X
GStreamer provides native video and audio output elements for OS X. It
builds using the standard development tools for OS X.
## Windows
> **Warning**
>
> Note: this section is out of date. GStreamer-1.0 has much better
> support for win32 than previous versions though and should usually
> compile and work out-of-the-box both using MSYS/MinGW or Microsoft
> compilers. The [GStreamer web site](http://gstreamer.freedesktop.org)
> and the [mailing list
> archives](http://news.gmane.org/gmane.comp.video.gstreamer.devel) are
> a good place to check the latest win32-related news.
GStreamer builds using Microsoft Visual C .NET 2003 and using Cygwin.
### Building GStreamer under Win32
There are different makefiles that can be used to build GStreamer with
the usual Microsoft compiling tools.
The Makefile is meant to be used with the GNU make program and the free
version of the Microsoft compiler
(<http://msdn.microsoft.com/visualc/vctoolkit2003/>). You also have to
modify your system environment variables to use it from the
command-line. You will also need a working Platform SDK for Windows that
is available for free from Microsoft.
The projects/makefiles will generate automatically some source files
needed to compile GStreamer. That requires that you have installed on
your system some GNU tools and that they are available in your system
PATH.
The GStreamer project depends on other libraries, namely :
- GLib
- libxml2
- libintl
- libiconv
Work is being done to provide pre-compiled GStreamer-1.0 libraries as a
packages for win32. Check the [GStreamer web
site](http://gstreamer.freedesktop.org) and check our [mailing
list](http://news.gmane.org/gmane.comp.video.gstreamer.devel) for the
latest developments in this respect.
> **Note**
>
> GNU tools needed that you can find on
> <http://gnuwin32.sourceforge.net/>
>
> - GNU flex (tested with 2.5.4)
>
> - GNU bison (tested with 1.35)
>
> and <http://www.mingw.org/>
>
> - GNU make (tested with 3.80)
>
> the generated files from the -auto makefiles will be available soon
> separately on the net for convenience (people who don't want to
> install GNU tools).
### Installation on the system
FIXME: This section needs be updated for GStreamer-1.0.
subprojects/gst-docs/markdown/application-development/appendix/licensing.md
+92
View File
@@ -0,0 +1,92 @@
---
title: Licensing advisory
...
# Licensing advisory
## How to license the applications you build with GStreamer
The licensing of GStreamer is no different from a lot of other libraries
out there like GTK+ or glibc: we use the LGPL. What complicates things
with regards to GStreamer is its plugin-based design and the heavily
patented and proprietary nature of many multimedia codecs. While patents
on software are currently only allowed in a small minority of world
countries (the US and Australia being the most important of those), the
problem is that due to the central place the US hold in the world
economy and the computing industry, software patents are hard to ignore
wherever you are. Due to this situation, many companies, including major
GNU/Linux distributions, get trapped in a situation where they either
get bad reviews due to lacking out-of-the-box media playback
capabilities (and attempts to educate the reviewers have met with little
success so far), or go against their own - and the free software
movement's - wish to avoid proprietary software. Due to competitive
pressure, most choose to add some support. Doing that through pure free
software solutions would have them risk heavy litigation and punishment
from patent owners. So when the decision is made to include support for
patented codecs, it leaves them the choice of either using special
proprietary applications, or try to integrate the support for these
codecs through proprietary plugins into the multimedia infrastructure
provided by GStreamer. Faced with one of these two evils the GStreamer
community of course prefer the second option.
The problem which arises is that most free software and open source
applications developed use the GPL as their license. While this is
generally a good thing, it creates a dilemma for people who want to put
together a distribution. The dilemma they face is that if they include
proprietary plugins in GStreamer to support patented formats in a way
that is legal for them, they do risk running afoul of the GPL license of
the applications. We have gotten some conflicting reports from lawyers
on whether this is actually a problem, but the official stance of the
FSF is that it is a problem. We view the FSF as an authority on this
matter, so we are inclined to follow their interpretation of the GPL
license.
So what does this mean for you as an application developer? Well, it
means you have to make an active decision on whether you want your
application to be used together with proprietary plugins or not. What
you decide here will also influence the chances of commercial
distributions and Unix vendors shipping your application. The GStreamer
community suggest you license your software using a license that will
allow proprietary plugins to be bundled with GStreamer and your
applications, in order to make sure that as many vendors as possible go
with GStreamer instead of less free solutions. This in turn we hope and
think will let GStreamer be a vehicle for wider use of free formats like
the Xiph.org formats.
If you do decide that you want to allow for non-free plugins to be used
with your application you have a variety of choices. One of the simplest
is using licenses like LGPL, MPL or BSD for your application instead of
the GPL. Or you can add an exception clause to your GPL license stating
that you except GStreamer plugins from the obligations of the GPL.
A good example of such a GPL exception clause would be, using the Totem
video player project as an example: The authors of the Totem video
player project hereby grants permission for non-GPL-compatible GStreamer
plugins to be used and distributed together with GStreamer and Totem.
This permission goes above and beyond the permissions granted by the GPL
license Totem is covered by.
Our suggestion among these choices is to use the LGPL license, as it is
what resembles the GPL most and it makes it a good licensing fit with
the major GNU/Linux desktop projects like GNOME and KDE. It also allows
you to share code more openly with projects that have compatible
licenses. Obviously, pure GPL code without the above-mentioned clause is
not usable in your application as such. By choosing the LGPL, there is
no need for an exception clause and thus code can be shared more freely.
I have above outlined the practical reasons for why the GStreamer
community suggests you allow non-free plugins to be used with your
applications. We feel that in the multimedia arena, the free software
community is still not strong enough to set the agenda and that blocking
non-free plugins to be used in our infrastructure hurts us more than it
hurts the patent owners and their ilk.
This view is not shared by everyone. The Free Software Foundation urges
you to use an unmodified GPL for your applications, so as to push back
against the temptation to use non-free plug-ins. They say that since not
everyone else has the strength to reject them because they are
unethical, they ask your help to give them a legal reason to do so.
This advisory is part of a bigger advisory with a FAQ which you can find
on the [GStreamer
website](http://gstreamer.freedesktop.org/documentation/licensing.html)
subprojects/gst-docs/markdown/application-development/appendix/porting-1.0.md
+125
View File
@@ -0,0 +1,125 @@
---
title: Porting 0.10 applications to 1.0
...
# Porting 0.10 applications to 1.0
This section outlines some of the changes necessary to port applications
from GStreamer-0.10 to GStreamer-1.0. For a comprehensive and up-to-date
list, see the separate [Porting
to 1.0](https://gitlab.freedesktop.org/gstreamer/gstreamer/tree/master/docs/random/porting-to-1.0.txt)
document.
It should be possible to port simple applications to GStreamer-1.0 in
less than a day.
## List of changes
- All deprecated methods were removed. Recompile against 0.10 with
GST\_DISABLE\_DEPRECATED defined (such as by adding
-DGST\_DISABLE\_DEPRECATED to the compiler flags) and fix issues
before attempting to port to 1.0.
- "playbin2" has been renamed to "playbin", with similar API
- "decodebin2" has been renamed to "decodebin", with similar API. Note
that there is no longer a "new-decoded-pad" signal, just use
GstElement's "pad-added" signal instead (but don't forget to remove
the 'gboolean last' argument from your old signal callback functino
signature).
- the names of some "formatted" pad templates has been changed from
e.g. "src%d" to "src%u" or "src\_%u" or similar, since we don't want
to see negative numbers in pad names. This mostly affects
applications that create request pads from elements.
- some elements that used to have a single dynamic source pad have a
source pad now. Example: wavparse, id3demux, iceydemux, apedemux.
(This does not affect applications using decodebin or playbin).
- playbin now proxies the GstVideoOverlay (former GstXOverlay)
interface, so most applications can just remove the sync bus handler
where they would set the window ID, and instead just set the window
ID on playbin from the application thread before starting playback.
playbin also proxies the GstColorBalance and GstNavigation
interfaces, so applications that use this don't need to go fishing
for elements that may implement those any more, but can just use on
playbin unconditionally.
- multifdsink, tcpclientsink, tcpclientsrc, tcpserversrc the protocol
property is removed, use gdppay and gdpdepay.
- XML serialization was removed.
- Probes and pad blocking was merged into new pad probes.
- Position, duration and convert functions no longer use an inout
parameter for the destination format.
- Video and audio caps were simplified. audio/x-raw-int and
audio/x-raw-float are now all under the audio/x-raw media type.
Similarly, video/x-raw-rgb and video/x-raw-yuv are now video/x-raw.
- ffmpegcolorspace was removed and replaced with videoconvert.
- GstMixerInterface / GstTunerInterface were removed without
replacement.
- The GstXOverlay interface was renamed to GstVideoOverlay, and now
part of the video library in gst-plugins-base, as the interfaces
library no longer exists.
The name of the GstXOverlay "prepare-xwindow-id" message has changed
to "prepare-window-handle" (and GstXOverlay has been renamed to
GstVideoOverlay). Code that checks for the string directly should be
changed to use
gst\_is\_video\_overlay\_prepare\_window\_handle\_message(message)
instead.
- The GstPropertyProbe interface was removed. There is no replacement
for it in GStreamer 1.0.x and 1.2.x, but since version 1.4 there is
a more featureful replacement for device discovery and feature
querying provided by GstDeviceMonitor, GstDevice, and friends. See
the ["GStreamer Device Discovery and Device Probing"
documentation](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-device-probing.html).
- gst\_uri\_handler\_get\_uri() and the get\_uri vfunc now return a
copy of the URI string
gst\_uri\_handler\_set\_uri() and the set\_uri vfunc now take an
additional GError argument so the handler can notify the caller why
it didn't accept a particular URI.
gst\_uri\_handler\_set\_uri() now checks if the protocol of the URI
passed is one of the protocols advertised by the uri handler, so
set\_uri vfunc implementations no longer need to check that as well.
- GstTagList is now an opaque mini object instead of being typedefed
to a GstStructure. While it was previously okay (and in some cases
required because of missing taglist API) to cast a GstTagList to a
GstStructure or use gst\_structure\_\* API on taglists, you can no
longer do that. Doing so will cause crashes.
Also, tag lists are refcounted now, and can therefore not be freely
modified any longer. Make sure to call
gst\_tag\_list\_make\_writable (taglist) before adding, removing or
changing tags in the taglist.
GST\_TAG\_IMAGE, GST\_TAG\_PREVIEW\_IMAGE, GST\_TAG\_ATTACHMENT:
many tags that used to be of type GstBuffer are now of type
GstSample (which is basically a struct containing a buffer alongside
caps and some other info).
- GstController has now been merged into GstObject. It does not exists
as an individual object anymore. In addition core contains a
GstControlSource base class and the GstControlBinding. The actual
control sources are in the controller library as before. The 2nd big
change is that control sources generate a sequence of gdouble values
and those are mapped to the property type and value range by
GstControlBindings.
The whole gst\_controller\_\* API is gone and now available in
simplified form under gst\_object\_\*. ControlSources are now
attached via GstControlBinding to properties. There are no GValue
arguments used anymore when programming control sources.
subprojects/gst-docs/markdown/application-development/appendix/porting.md
+91
View File
@@ -0,0 +1,91 @@
---
title: Porting 0.8 applications to 0.10
...
# Porting 0.8 applications to 0.10
This section of the appendix will discuss shortly what changes to
applications will be needed to quickly and conveniently port most
applications from GStreamer-0.8 to GStreamer-0.10, with references to
the relevant sections in this Application Development Manual where
needed. With this list, it should be possible to port simple
applications to GStreamer-0.10 in less than a day.
## List of changes
- Most functions returning an object or an object property have been
changed to return its own reference rather than a constant reference
of the one owned by the object itself. The reason for this change is
primarily thread safety. This means, effectively, that return values
of functions such as `gst_element_get_pad ()`, `gst_pad_get_name ()`
and many more like these have to be free'ed or unreferenced after
use. Check the API references of each function to know for sure
whether return values should be free'ed or not. It is important that
all objects derived from GstObject are ref'ed/unref'ed using
gst\_object\_ref() and gst\_object\_unref() respectively (instead of
g\_object\_ref/unref).
- Applications should no longer use signal handlers to be notified of
errors, end-of-stream and other similar pipeline events. Instead,
they should use the `GstBus`, which has been discussed in
[Bus][bus]. The bus will take care that the messages will
be delivered in the context of a main loop, which is almost
certainly the application's main thread. The big advantage of this
is that applications no longer need to be thread-aware; they don't
need to use `g_idle_add ()` in the signal handler and do the actual
real work in the idle-callback. GStreamer now does all that internally.
- Related to this, `gst_bin_iterate ()` has been removed. Pipelines
will iterate in their own thread, and applications can simply run a
`GMainLoop` (or call the mainloop of their UI toolkit, such as
`gtk_main ()`).
- State changes can be delayed (ASYNC). Due to the new fully threaded
nature of GStreamer-0.10, state changes are not always immediate, in
particular changes including the transition from READY to PAUSED
state. This means two things in the context of porting applications:
first of all, it is no longer always possible to do
`gst_element_set_state ()` and check for a return value of
GST\_STATE\_CHANGE\_SUCCESS, as the state change might be delayed
(ASYNC) and the result will not be known until later. You should
still check for GST\_STATE\_CHANGE\_FAILURE right away, it is just
no longer possible to assume that everything that is not SUCCESS
means failure. Secondly, state changes might not be immediate, so
your code needs to take that into account. You can wait for a state
change to complete if you use GST\_CLOCK\_TIME\_NONE as timeout
interval with `gst_element_get_state ()`.
- In 0.8, events and queries had to manually be sent to sinks in
pipelines (unless you were using playbin). This is no longer the
case in 0.10. In 0.10, queries and events can be sent to toplevel
pipelines, and the pipeline will do the dispatching internally for
you. This means less bookkeeping in your application. For a short
code example, see [Position tracking and seeking][queries-and-events].
Related, seeking is now threadsafe, and your video output will show the new
video position's frame while seeking, providing a better user experience.
- The `GstThread` object has been removed. Applications can now simply
put elements in a pipeline with optionally some “queue” elements in
between for buffering, and GStreamer will take care of creating
threads internally. It is still possible to have parts of a pipeline
run in different threads than others, by using the “queue” element.
See [Threads][threads] for details.
- Filtered caps -\> capsfilter element (the pipeline syntax for
gst-launch has not changed though).
- libgstgconf-0.10.la does not exist. Use the “gconfvideosink” and
“gconfaudiosink” elements instead, which will do live-updates and
require no library linking.
- The “new-pad” and “state-change” signals on `GstElement` were
renamed to “pad-added” and “state-changed”.
- `gst_init_get_popt_table ()` has been removed in favour of the new
GOption command line option API that was added to GLib 2.6.
`gst_init_get_option_group ()` is the new GOption-based equivalent
to `gst_init_get_ptop_table ()`.
[bus]: application-development/basics/bus.md
[threads]: application-development/advanced/threads.md
[queries-and-sevents]: application-development/advanced/queryevents.md
subprojects/gst-docs/markdown/application-development/appendix/programs.md
+334
View File
@@ -0,0 +1,334 @@
---
title: Programs
...
# Programs
## `gst-launch`
This is a tool that will construct pipelines based on a command-line
syntax.
A simple commandline looks like:
```
gst-launch filesrc location=hello.mp3 ! mad ! audioresample ! osssink
```
A more complex pipeline looks like:
```
gst-launch filesrc location=redpill.vob ! dvddemux name=demux \
demux.audio_00 ! queue ! a52dec ! audioconvert ! audioresample ! osssink \
demux.video_00 ! queue ! mpeg2dec ! videoconvert ! xvimagesink
```
You can also use the parser in you own code. GStreamer provides a
function gst\_parse\_launch () that you can use to construct a pipeline.
The following program lets you create an MP3 pipeline using the
gst\_parse\_launch () function:
``` c
#include <gst/gst.h>
int
main (int argc, char *argv[])
{
GstElement *pipeline;
GstElement *filesrc;
GstMessage *msg;
GstBus *bus;
GError *error = NULL;
gst_init (&argc, &argv);
if (argc != 2) {
g_print ("usage: %s <filename>\n", argv[0]);
return -1;
}
pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &error);
if (!pipeline) {
g_print ("Parse error: %s\n", error->message);
exit (1);
}
filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc");
g_object_set (filesrc, "location", argv[1], NULL);
g_object_unref (filesrc);
gst_element_set_state (pipeline, GST_STATE_PLAYING);
bus = gst_element_get_bus (pipeline);
/* wait until we either get an EOS or an ERROR message. Note that in a real
* program you would probably not use gst_bus_poll(), but rather set up an
* async signal watch on the bus and run a main loop and connect to the
* bus's signals to catch certain messages or all messages */
msg = gst_bus_poll (bus, GST_MESSAGE_EOS | GST_MESSAGE_ERROR, -1);
switch (GST_MESSAGE_TYPE (msg)) {
case GST_MESSAGE_EOS: {
g_print ("EOS\n");
break;
}
case GST_MESSAGE_ERROR: {
GError *err = NULL; /* error to show to users */
gchar *dbg = NULL; /* additional debug string for developers */
gst_message_parse_error (msg, &err, &dbg);
if (err) {
g_printerr ("ERROR: %s\n", err->message);
g_error_free (err);
}
if (dbg) {
g_printerr ("[Debug details: %s]\n", dbg);
g_free (dbg);
}
}
default:
g_printerr ("Unexpected message of type %d", GST_MESSAGE_TYPE (msg));
break;
}
gst_message_unref (msg);
gst_element_set_state (pipeline, GST_STATE_NULL);
gst_object_unref (pipeline);
gst_object_unref (bus);
return 0;
}
```
Note how we can retrieve the filesrc element from the constructed bin
using the element name.
### Grammar Reference
The `gst-launch` syntax is processed by a flex/bison parser. This
section is intended to provide a full specification of the grammar; any
deviations from this specification is considered a bug.
#### Elements
```
... mad ...
```
A bare identifier (a string beginning with a letter and containing only
letters, numbers, dashes, underscores, percent signs, or colons) will
create an element from a given element factory. In this example, an
instance of the "mad" MP3 decoding plugin will be created.
#### Links
```
... !sink ...
```
An exclamation point, optionally having a qualified pad name (an the
name of the pad, optionally preceded by the name of the element) on both
sides, will link two pads. If the source pad is not specified, a source
pad from the immediately preceding element will be automatically chosen.
If the sink pad is not specified, a sink pad from the next element to be
constructed will be chosen. An attempt will be made to find compatible
pads. Pad names may be preceded by an element name, as in
`my_element_name.sink_pad`.
#### Properties
```
... location="http://gstreamer.net" ...
```
The name of a property, optionally qualified with an element name, and a
value, separated by an equals sign, will set a property on an element.
If the element is not specified, the previous element is assumed.
Strings can optionally be enclosed in quotation marks. Characters in
strings may be escaped with the backtick (`\`). If the right-hand side
is all digits, it is considered to be an integer. If it is all digits
and a decimal point, it is a double. If it is "true", "false", "TRUE",
or "FALSE" it is considered to be boolean. Otherwise, it is parsed as a
string. The type of the property is determined later on in the parsing,
and the value is converted to the target type. This conversion is not
guaranteed to work, it relies on the g\_value\_convert routines. No
error message will be displayed on an invalid conversion, due to
limitations in the value convert API.
#### Bins, Threads, and Pipelines
```
( ... )
```
A pipeline description between parentheses is placed into a bin. The
open paren may be preceded by a type name, as in `jackbin.( ... )` to
make a bin of a specified type. Square brackets make pipelines, and
curly braces make threads. The default toplevel bin type is a pipeline,
although putting the whole description within parentheses or braces can
override this default.
## `gst-inspect`
This is a tool to query a plugin or an element about its properties.
To query the information about the element mad, you would specify:
```
gst-inspect mad
```
Below is the output of a query for the osssink element:
```
Factory Details:
Rank: secondary (128)
Long-name: Audio Sink (OSS)
Klass: Sink/Audio
Description: Output to a sound card via OSS
Author: Erik Walthinsen <omega@cse.ogi.edu>, Wim Taymans <wim.taymans@chello.be>
Plugin Details:
Name: ossaudio
Description: OSS (Open Sound System) support for GStreamer
Filename: /home/wim/gst/head/gst-plugins-good/sys/oss/.libs/libgstossaudio.so
Version: 1.0.0.1
License: LGPL
Source module: gst-plugins-good
Source release date: 2012-09-25 12:52 (UTC)
Binary package: GStreamer Good Plug-ins git
Origin URL: Unknown package origin
GObject
+----GInitiallyUnowned
+----GstObject
+----GstElement
+----GstBaseSink
+----GstAudioBaseSink
+----GstAudioSink
+----GstOssSink
Pad Templates:
SINK template: 'sink'
Availability: Always
Capabilities:
audio/x-raw
format: { S16LE, U16LE, S8, U8 }
layout: interleaved
rate: [ 1, 2147483647 ]
channels: 1
audio/x-raw
format: { S16LE, U16LE, S8, U8 }
layout: interleaved
rate: [ 1, 2147483647 ]
channels: 2
channel-mask: 0x0000000000000003
Element Flags:
no flags set
Element Implementation:
Has change_state() function: gst_audio_base_sink_change_state
Clocking Interaction:
element is supposed to provide a clock but returned NULL
Element has no indexing capabilities.
Element has no URI handling capabilities.
Pads:
SINK: 'sink'
Implementation:
Has chainfunc(): gst_base_sink_chain
Has custom eventfunc(): gst_base_sink_event
Has custom queryfunc(): gst_base_sink_sink_query
Has custom iterintlinkfunc(): gst_pad_iterate_internal_links_default
Pad Template: 'sink'
Element Properties:
name : The name of the object
flags: readable, writable
String. Default: "osssink0"
parent : The parent of the object
flags: readable, writable
Object of type "GstObject"
sync : Sync on the clock
flags: readable, writable
Boolean. Default: true
max-lateness : Maximum number of nanoseconds that a buffer can be late before it is dropped (-1 unlimited)
flags: readable, writable
Integer64. Range: -1 - 9223372036854775807 Default: -1
qos : Generate Quality-of-Service events upstream
flags: readable, writable
Boolean. Default: false
async : Go asynchronously to PAUSED
flags: readable, writable
Boolean. Default: true
ts-offset : Timestamp offset in nanoseconds
flags: readable, writable
Integer64. Range: -9223372036854775808 - 9223372036854775807 Default: 0
enable-last-sample : Enable the last-sample property
flags: readable, writable
Boolean. Default: false
last-sample : The last sample received in the sink
flags: readable
Boxed pointer of type "GstSample"
blocksize : Size in bytes to pull per buffer (0 = default)
flags: readable, writable
Unsigned Integer. Range: 0 - 4294967295 Default: 4096
render-delay : Additional render delay of the sink in nanoseconds
flags: readable, writable
Unsigned Integer64. Range: 0 - 18446744073709551615 Default: 0
throttle-time : The time to keep between rendered buffers
flags: readable, writable
Unsigned Integer64. Range: 0 - 18446744073709551615 Default: 0
buffer-time : Size of audio buffer in microseconds, this is the minimum latency that the sink reports
flags: readable, writable
Integer64. Range: 1 - 9223372036854775807 Default: 200000
latency-time : The minimum amount of data to write in each iteration in microseconds
flags: readable, writable
Integer64. Range: 1 - 9223372036854775807 Default: 10000
provide-clock : Provide a clock to be used as the global pipeline clock
flags: readable, writable
Boolean. Default: true
slave-method : Algorithm to use to match the rate of the masterclock
flags: readable, writable
Enum "GstAudioBaseSinkSlaveMethod" Default: 1, "skew"
(0): resample - GST_AUDIO_BASE_SINK_SLAVE_RESAMPLE
(1): skew - GST_AUDIO_BASE_SINK_SLAVE_SKEW
(2): none - GST_AUDIO_BASE_SINK_SLAVE_NONE
can-activate-pull : Allow pull-based scheduling
flags: readable, writable
Boolean. Default: false
alignment-threshold : Timestamp alignment threshold in nanoseconds
flags: readable, writable
Unsigned Integer64. Range: 1 - 18446744073709551614 Default: 40000000
drift-tolerance : Tolerance for clock drift in microseconds
flags: readable, writable
Integer64. Range: 1 - 9223372036854775807 Default: 40000
discont-wait : Window of time in nanoseconds to wait before creating a discontinuity
flags: readable, writable
Unsigned Integer64. Range: 0 - 18446744073709551614 Default: 1000000000
device : OSS device (usually /dev/dspN)
flags: readable, writable
String. Default: "/dev/dsp"
```
To query the information about a plugin, you would do:
```
gst-inspect gstelements
```
subprojects/gst-docs/markdown/application-development/appendix/quotes.md
+200
View File
@@ -0,0 +1,200 @@
---
title: Quotes from the Developers
...
# Quotes from the Developers
As well as being a cool piece of software, GStreamer is a lively
project, with developers from around the globe very actively
contributing. We often hang out on the \#gstreamer IRC channel on
irc.oftc.net: the following are a selection of amusing\[1\] quotes
from our conversations.
- 6 Mar 2006
When I opened my eyes I was in a court room. There were masters
McIlroy and Thompson sitting in the jury and master Kernighan too.
There were the GStreamer developers standing in the defendant's
place, accused of violating several laws of Unix philosophy and
customer lock-down via running on a proprietary pipeline, different
from that of the Unix systems. I heard Eric Raymond whispering "got
to add this case to my book.
*behdad's blog*
- 22 May 2007
*\<\_\_tim\>* Uraeus: amusing, isn't it?
*\<Uraeus\>* \_\_tim: I wrote that :)
*\<\_\_tim\>* Uraeus: of course you did; your refusal to surrender
to the oppressive regime of the third-person-singular-rule is so
unique in its persistence that it's hard to miss :)
- 12 Sep 2005
*\<wingo\>* we just need to get rid of that mmap stuff
*\<wingo\>* i think gnomevfssrc is faster for files even
*\<BBB\>* wingo, no
*\<BBB\>* and no
*\<wingo\>* good points ronald
- 23 Jun 2005
*\* wingo* back
*\* thomasvs* back
\--- You are now known as everybody
*\* everybody* back back
*\<everybody\>* now break it down
\--- You are now known as thomasvs
*\* bilboed* back
\--- bilboed is now known as john-sebastian
*\* john-sebastian* bach
\--- john-sebastian is now known as bilboed
\--- You are now known as scratch\_my
*\* scratch\_my* back
\--- bilboed is now known as Illbe
\--- You are now known as thomasvs
*\* Illbe* back
\--- Illbe is now known as bilboed
- 20 Apr 2005
*thomas*: jrb, somehow his screenshotsrc grabs whatever X is showing
and makes it available as a stream of frames
*jrb*: thomas: so, is the point that the screenshooter takes a
video? but won't the dialog be in the video? oh, nevermind. I'll
just send mail...
*thomas*: jrb, well, it would shoot first and ask questions later
- 2 Nov 2004
*zaheerm*: wtay: unfair u fixed the bug i was using as a feature\!
- 14 Oct 2004
*\* zaheerm* wonders how he can break gstreamer today :)
*ensonic*: zaheerm, spider is always a good starting point
- 14 Jun 2004
*teuf*: ok, things work much better when I don't write incredibly
stupid and buggy code
*thaytan*: I find that too
- 23 Nov 2003
*Uraeus*: ah yes, the sleeping part, my mind is not multitasking so
I was still thinking about exercise
*dolphy*: Uraeus: your mind is multitasking
*dolphy*: Uraeus: you just miss low latency patches
- 14 Sep 2002
\--- *wingo-party* is now known as *wingo*
\* *wingo* holds head
- 4 Jun 2001
*taaz:* you witchdoctors and your voodoo mpeg2 black magic...
*omega\_:* um. I count three, no four different cults there \<g\>
*ajmitch:* hehe
*omega\_:* witchdoctors, voodoo, black magic,
*omega\_:* and mpeg
- 16 Feb 2001
*wtay:* I shipped a few commerical products to \>40000 people now
but GStreamer is way more exciting...
- 16 Feb 2001
\* *tool-man* is a gstreamer groupie
- 14 Jan 2001
*Omega:* did you run ldconfig? maybe it talks to init?
*wtay:* not sure, don't think so... I did run gstreamer-register
though :-)
*Omega:* ah, that did it then ;-)
*wtay:* right
*Omega:* probably not, but in case GStreamer starts turning into an
OS, someone please let me know?
- 9 Jan 2001
*wtay:* me tar, you rpm?
*wtay:* hehe, forgot "zan"
*Omega:* ?
*wtay:* me tar"zan", you ...
- 7 Jan 2001
*Omega:* that means probably building an agreggating,
cache-massaging queue to shove N buffers across all at once, forcing
cache transfer.
*wtay:* never done that before...
*Omega:* nope, but it's easy to do in gstreamer \<g\>
*wtay:* sure, I need to rewrite cp with gstreamer too, someday :-)
- 7 Jan 2001
*wtay:* GStreamer; always at least one developer is awake...
- 5/6 Jan 2001
*wtay:* we need to cut down the time to create an mp3 player down to
seconds...
*richardb:* :)
*Omega:* I'm wanting to something more interesting soon, I did the
"draw an mp3 player in 15sec" back in October '99.
*wtay:* by the time Omega gets his hands on the editor, you'll see a
complete audio mixer in the editor :-)
*richardb:* Well, it clearly has the potential...
*Omega:* Working on it... ;-)
- 28 Dec 2000
*MPAA:* We will sue you now, you have violated our IP rights\!
*wtay:* hehehe
*MPAA:* How dare you laugh at us? We have lawyers\! We have
Congressmen\! We have *LARS*\!
*wtay:* I'm so sorry your honor
*MPAA:* Hrumph.
\* *wtay* bows before thy
<!-- end list -->
1. No guarantee of sense of humour compatibility is given.