8. Developing applications with GStreamer

A: GStreamer uses pkg-config to assist applications with compilation and linking flags. pkg-config is already used by GTK+, GNOME, SDL, and others; so if you are familiar with using it for any of those, you're set.

If you're not familiar with pkg-config to compile and link a small one-file program, pass the --cflags and --libs arguments to pkg-config. For example:

$ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-0.10` -o myprog myprog.c

$ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-0.10 gtk+-2.0` -o myprog myprog.c

For bigger projects, you should integrate pkg-config use in your Makefile, or integrate with autoconf using the pkg.m4 macro (providing PKG_CONFIG_CHECK).

A: It is possible to develop and compile against an uninstalled copy of gstreamer and gst-plugins-* (for example, against gits checkouts). The easiest way to do this is to use a bash script like this (also: lastest version of gst-uninstalled):

#!/bin/bash -i
#
# this script is in git as gstreamer/docs/faq/gst-uninstalled
#
# It will set up the environment to use and develop gstreamer and projects
# that use gstreamer with an uninstalled git checkout of gstreamer and the
# plugin modules.
#
# It will set up LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, PKG_CONFIG_PATH,
# GST_PLUGIN_PATH, GST_PLUGIN_SYSTEM_PATH, GST_REGISTRY, MANPATH, PYTHONPATH
# to prefer the uninstalled versions but also contain the installed ones.
# The only exception to this is, that no system installed plugins will be
# used but only the uninstalled ones.
#
# This script assumes that the relevant modules are checked out one by one
# under a given tree specified below in MYGST.
#
# Symlink this script in a directory in your path (for example $HOME/bin). You
# must name the symlink gst-something, where something is the subdirectory
# of MYGST that contains your gstreamer module checkouts.
#
# e.g.:
# - mkdir $HOME/gst/head
# - ln -sf gst-uninstalled $HOME/bin/gst-head
# - checkout copies of gstreamer modules in $HOME/gst/head
# - gst-head

# This script is run -i so that PS1 doesn't get cleared

# Change this variable to the location of your gstreamer git checkouts
MYGST=$HOME/gst

#
# Everything below this line shouldn't be edited!
#

# extract version from $0
# if this script is called "gst-head" then version will be "head"
VERSION=`echo $0 | sed s/.*gst-//g`

# base path under which dirs are installed
GST=$MYGST/$VERSION
if test ! -e $GST; then
  echo "$GST does not exist !"
  exit
fi

# set up a bunch of paths
PATH="\
$GST/gstreamer/tools:\
$GST/gst-plugins-base/tools:\
$GST/gst-player/src:\
$GST/gst-editor/src:\
$GST/prefix/bin:\
$PATH"

# /some/path: makes the dynamic linker look in . too, so avoid this
LD_LIBRARY_PATH=$GST/prefix/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
DYLD_LIBRARY_PATH=$GST/prefix/lib${DYLD_LIBRARY_PATH:+:$DYLD_LIBRARY_PATH}

# GStreamer rtsp server library
LD_LIBRARY_PATH=$GST/gst-rtsp-server/gst/rtsp-server/.libs:$LD_LIBRARY_PATH
DYLD_LIBRARY_PATH=$GST/gst-rtsp-server/gst/rtsp-server/.libs:$DYLD_LIBRARY_PATH

# GStreamer ffmpeg libraries
for path in libavformat libavutil libavcodec libpostproc libavdevice
do
   LD_LIBRARY_PATH=$GST/gst-ffmpeg/gst-libs/ext/ffmpeg/$path:$LD_LIBRARY_PATH
   DYLD_LIBRARY_PATH=$GST/gst-ffmpeg/gst-libs/ext/ffmpeg/$path:$DYLD_LIBRARY_PATH
done

# GStreamer plugins base libraries
for path in app audio cdda fft interfaces pbutils netbuffer riff rtp rtsp sdp tag utils video 
do
  LD_LIBRARY_PATH=$GST/gst-plugins-base/gst-libs/gst/$path/.libs:$LD_LIBRARY_PATH
  DYLD_LIBRARY_PATH=$GST/gst-plugins-base/gst-libs/gst/$path/.libs:$DYLD_LIBRARY_PATH
done

# GStreamer core libraries
for path in base net check controller dataprotocol
do
  LD_LIBRARY_PATH=$GST/gstreamer/libs/gst/$path/.libs:$LD_LIBRARY_PATH
  DYLD_LIBRARY_PATH=$GST/gstreamer/libs/gst/$path/.libs:$DYLD_LIBRARY_PATH
done
LD_LIBRARY_PATH=$GST/gstreamer/gst/.libs:$LD_LIBRARY_PATH
DYLD_LIBRARY_PATH=$GST/gstreamer/gst/.libs:$DYLD_LIBRARY_PATH
export LD_LIBRARY_PATH
export DYLD_LIBRARY_PATH
  
export PKG_CONFIG_PATH="\
$GST/prefix/lib/pkgconfig\
:$GST/gstreamer/pkgconfig\
:$GST/gst-plugins-base/pkgconfig\
:$GST/gst-plugins-good/pkgconfig\
:$GST/gst-python/pkgconfig\
:$GST/gst-rtsp-server/pkgconfig\
${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"

export GST_PLUGIN_PATH="\
$GST/gstreamer\
:$GST/gst-plugins-base\
:$GST/gst-plugins-good\
:$GST/gst-plugins-ugly\
:$GST/gst-plugins-bad\
:$GST/gst-ffmpeg\
:$GST/gnonlin\
:$GST/gst-openmax\
:$GST/gst-plugins-gl\
:$GST/plugins\
${GST_PLUGIN_PATH:+:$GST_PLUGIN_PATH}"

# don't use any system-installed plug-ins at all
export GST_PLUGIN_SYSTEM_PATH=
# set our registry somewhere else so we don't mess up the registry generated
# by an installed copy
export GST_REGISTRY=$GST/gstreamer/registry.xml
# once MANPATH is set, it needs at least an "empty"component to keep pulling
# in the system-configured man paths from man.config
# this still doesn't make it work for the uninstalled case, since man goes
# look for a man directory "nearby" instead of the directory I'm telling it to
export MANPATH=$GST/gstreamer/tools:$GST/prefix/share/man:$MANPATH
pythonver=`python -c "import sys; print sys.version[:3]"`
export PYTHONPATH=$GST/gst-python:$GST/prefix/lib/python$pythonver/site-packages${PYTHONPATH:+:$PYTHONPATH}

# totem-pl-parser
export PKG_CONFIG_PATH=$GST/totem-pl-parser:$PKG_CONFIG_PATH
export LD_LIBRARY_PATH=$GST/totem-pl-parser/plparse/.libs:$LD_LIBRARY_PATH
export DYLD_LIBRARY_PATH=$GST/totem-pl-parser/plparse/.libs:$DYLD_LIBRARY_PATH

# totem
export PATH=$GST/totem/src:$PATH

# if we got a command, run it, else start a shell
if test ! -z "$1";
then
  $@
  exit $?
fi

# set up prompt to help us remember we're in a subshell, cd to
# the gstreamer base dir and start $SHELL
cd $GST
shell=$SHELL
if test "x$SHELL" == "x/bin/bash"
then
  # debian/ubuntu resets our PS1.  bastards.
  shell="$SHELL --noprofile"
fi
PS1="[gst-$VERSION] $PS1" $shell

This requires you to have put your checkouts of gstreamer and gst-plugins under ~/gst/git (for the master version). The program is easily modifiable if this isn't the case.

After running this script, you'll be in an environment where the uninstalled tools and plugins will be used by default. Also, pkg-config will detect the uninstalled copies before (and prefer them to) any installed copies.

A: For GNOME applications it's a good idea to use GConf to find the default ways of outputting audio and video. You can do this by using the 'gconfaudiosink' and 'gconfvideosink' elements for audio and video output. They will take care of everything GConf-related for you and automatically use the outputs that the user configured. If you are using gconfaudiosink, your application should set the 'profile' property.

A: When you link a program against uninstalled GStreamer using libtool, funny shell scripts are made to modify your shared object search path and then run your program. For instance, to debug gst-launch, try

libtool --mode=execute gdb /path/to/gst-launch

A: Our main arena for coordination and discussion is IRC, not email. Join us in #gstreamer on irc.freenode.net For larger picture questions or getting more input from more persons, a mail to gstreamer-devel is never a bad idea.

A: For public releases, GStreamer uses a standard MAJOR.MINOR.MICRO version scheme. If the release consists of mostly bug fixes or incremental changes, the MICRO version is incremented. If the release contains big changes, the MINOR version is incremented. If we're particularly giddy, we might even increase the MAJOR number. Don't hold your breath for that though.

During the development cycle, GStreamer also uses a fourth or NANO number. If this number is 1, then it's a git development version. Any tarball or package that has a nano number of 1 is made from git and thus not supported. Additionally, if you didn't get this package or tarball from the GStreamer team, don't have high hopes on it doing whatever you want it to do.

If the number is 2 or higher, it's an official pre-release in preparation of an actual complete release. Your help in testing these tarballs and packages is very much appreciated.

A: The core and almost all plugin modules are basically coded in K&R with 2-space indenting. Just follow what's already there and you'll be fine.

Individual plugins in gst-plugins-* or plugins that you want considered for addition to one of the gst-plugins-* modules should be coded in the same style. It's easier if everything is consistent. Consistency is, of course, the goal.

Simply run your code (only the *.c files, not the header files) through

indent \
  --braces-on-if-line \
  --case-brace-indentation0 \
  --case-indentation2 \
  --braces-after-struct-decl-line \
  --line-length80 \
  --no-tabs \
  --cuddle-else \
  --dont-line-up-parentheses \
  --continuation-indentation4 \
  --honour-newlines \
  --tab-size8 \
  --indent-level2

As for the code itself, the GNOME coding guidelines is a good read. Where possible, we try to adhere to the spirit of GObject and use similar coding idioms.

Patches should be made against git master or the latest release and should be in 'unified context' format (use diff -u -p). They should be attached to a bug report (or feature request) in bugzilla rather than sent to the mailing list. Also see SubmittingPatches in the GStreamer wiki.

A: GStreamer translations are uniformly managed through the Translation Project (http://translationproject.org). There are some instructions on how to join the Translation Project team and submit new translations at http://translationproject.org/html/translators.html.

New translations submitted via the Translation Project are merged periodically into git by the maintainers by running 'make download-po' in the various modules.