Index: books/porters-handbook/book.xml
===================================================================
--- books/porters-handbook/book.xml (revision 42940)
+++ books/porters-handbook/book.xml (working copy)
@@ -3889,7 +3889,8 @@
.
Perl related variables are
described in . X11 variables
- are listed in .
+ are listed in . Gstreamer variable
+ options are listed in .
deals with GNOME and
with KDE related variables.
documents Java variables, while
@@ -6516,6 +6517,160 @@
+
+ Using GStreamer
+
+ The maintainer of the port need to consider which set of
+ GStreamer plugin they will include.
+ Due to the nature of Gstreamer
+ being plugin based. Defining a minimal set so basic
+ functinality works is ok. As a side note including all
+ possible plugins is going overboard. If the user wants
+ support for a specific format he just has to install the
+ appropiat plugin.
+
+ The following two variables are for selecting which version
+ of GStreamer the port needs. Please note that while Gstreamer
+ 0.10 and 1.x can be installable next to each other. They can't
+ be depended on by the same port.
+
+
+ Variables for enabling GStreamer
+
+
+
+ USE_GSTREAMER
+ Use this variable if your port is using the
+ 0.10 version of the GStreamer
+ framework. Programs installed by this version of
+ GStreamer have the -0.10 suffix.
+
+
+ USE_GSTREAMER1
+ Use this variable if your port is using the
+ 1.x version of the GStreamer
+ framework. Programs installed by this version of
+ GStreamer have the -1.0 suffix.
+
+
+
+
+
+
+ Selecting GStreamer Components
+
+ In this example, the application uses the
+ Gstreamer
+ pulse, ogg and
+ vorbis plugin. The framework will make
+ sure that all needed dependancies are included for these plugins.
+ USE_GSTREAMER= pulse ogg vorbis
+
+
+ scovererNot sure where to put this yet. mention gst-discoverer. also us the following for nice example. The part below could also be in the normal handbook for users for how to handle gstreamer ports.
+ Also talk about where USE_GSTREAMER should be placed and how optional gstreamer support should be done. bsd.port.options.mk.
+
+
+In the following example GStreamer tells the users which plug is missing. This is done with the "Missing element:" line. To see this the application needs to be started from a terminal (xterm/gnome-terminal). Gstreamer based applications will emit a simular line to console if they miss a plugin for playback.
+
+
+Detemening missing plugin
+
+
+&prompt.user;
+gst-launch-0.10 playbin uri=http://momori.animenfo.com:8000
+Setting pipeline to PAUSED ...
+Pipeline is PREROLLING ...
+Missing element: MPEG-1 Layer 3 (MP3) decoder
+WARNING: from element /GstPlayBin:playbin0/GstURIDecodeBin:uridecodebin0: No decoder available for type 'audio/mpeg, mpegversion=(int)1, mpegaudioversion=(int)1, layer=(int)3, rate=(int)44100, channels=(int)2, parsed=(boolean)true'.
+Additional debug info:
+gsturidecodebin.c(880): unknown_type_cb (): /GstPlayBin:playbin0/GstURIDecodeBin:uridecodebin0
+ERROR: from element /GstPlayBin:playbin0/GstURIDecodeBin:uridecodebin0/GstDecodeBin:decodebin0: Your GStreamer installation is missing a plug-in.
+Additional debug info:
+gstdecodebin2.c(3705): gst_decode_bin_expose (): /GstPlayBin:playbin0/GstURIDecodeBin:uridecodebin0/GstDecodeBin:decodebin0:
+no suitable plugins found
+ERROR: pipeline doesn't want to preroll.
+Setting pipeline to NULL ...
+Freeing pipeline ...
+
+
+
+
+
+ Where normaly one would use the plugin name these are exceptions or are special plugins.
+
+ Special cases
+
+
+
+ Plugin name
+ Available in
+ Auto dependancy added on
+ Description
+
+
+ good
+ both
+ yes
+ Set of gstreamer-plugins-good plugins without extra external dependancies.
+
+
+ mp3
+ 0.10
+ yes
+ This is a meta port that prompts the user to choice between the mad (default) or fluendo mp3 plugin.
+
+
+ yes
+ both
+ -
+ This is the minimal needed for GStreamer, it adds a dependacy on gstreamer-plugins. This port is known as gstreamer-plugins-base.
+
+
+
+
+
+ The next table shows which plugins are available on FreeBSD. For a complete list see Upstream GStreamer Plugins List
+
+ Gstreamer plugins
+
+
+
+
+ Plugin name
+ Available in
+ Auto dependancy added on
+ Description
+
+
+ ffmpeg
+ 0.10
+ base
+ ffmpeg based codec pack
+
+
+ libav
+ 1.0
+ base
+ libav based codec pack
+
+
+ mad
+ both
+ bad
+ Mp3 decoder
+
+
+ ogg
+ both
+ base
+ Ogg audio codec plugin
+
+
+
+
+
+
Using GNOME