diff --git a/docs/faq/Makefile.am b/docs/faq/Makefile.am new file mode 100644 index 0000000000..3170b28aeb --- /dev/null +++ b/docs/faq/Makefile.am @@ -0,0 +1,15 @@ +DOC=gstreamer-faq +MAIN=$(DOC).xml +XML=$(wildcard *.xml) +XSLFO=$(srcdir)/../xsl/fo.xsl +XSLFOMODS=$(srcdir)/../xsl/ulink.xsl $(srcdir)/../xsl/keycombo.xsl +XSLHTML=$(srcdir)/../xsl/html.xsl +XSLHTMLMODS=$(srcdir)/../xsl/fileext.xsl $(srcdir)/../xsl/admon.xsl \ + $(srcdir)/../xsl/keycombo.xsl $(srcdir)/../xsl/css.xsl +XSLS=$(XSLFO) $(XSLFOMODS) $(XSLHTML) $(XSLHTMLMODS) +SRC=$(XML) +CSS=base.css + +EXTRA_DIST = $(XML) $(CSS) + +include $(srcdir)/../manuals.mak diff --git a/docs/faq/base.css b/docs/faq/base.css new file mode 100644 index 0000000000..a24c078ad3 --- /dev/null +++ b/docs/faq/base.css @@ -0,0 +1,3 @@ +pre.programlisting { + background: #E8E8FF; +} diff --git a/docs/faq/dependencies.xml b/docs/faq/dependencies.xml new file mode 100644 index 0000000000..3e0fe49bb2 --- /dev/null +++ b/docs/faq/dependencies.xml @@ -0,0 +1,130 @@ + + Dependencies + + + + + Why are there so many dependencies ? + + + + +Making a full-featured media framework is a huge undertaking in itself. +By using the work done by others, we both reduce the amount of redundant work +being done and leave ourselves free to work on the architecture itself +instead of working on the low-level stuff. We would be stupid not to reuse +the code others have written. + + +However, do realize that in no way you are forced to have all dependencies +installed. Nono of the core developers has all of them installed. GStreamer +has only a few obligate dependencies : GLib 2.0, popt >= 1.6.0, and very +common stuff like glibc, a C compiler, and so on. All of the other +dependencies are optional. + + +So, in closing, let's rephrase the question to +Why are you giving me so many choices and such a rich environment ? + + + + + + + + +Does GStreamer use GTK+ 1.2/GLib 1.2 or GLib 2.0 ? + + + + + +Since the 0.3.3 release of GStreamer, we use GLib 2.0 as the core library +for GStreamer, which features a move of GObject from GTK+ 2.0 to GLib 2.0. +If you want to compile using GTK+ 1.2/GLib 1.2, you need to get the +0.3.1 or earlier release. It is of course not supported. + + + + + + + +Does GStreamer offer support for DVD decoder cards like dxr2/3 ? + + + + + +We do have support for the dxr3, although dxr2 support is unkown. +GStreamer can easily accomodate hardware acceleration by writing new +device-specific elements. + + + + + + + Is GStreamer X independent ? + + + + +Yes, we have no X dependency in any of our core modules. There are GStreamer +applications that run fine without any need for X. However, until our Linux +Framebuffer or libsvga plugin is ready, you will not be able to play videos +without X. In the future, there will probably be lots of different output +plugins for video available. + + + + + + + What is GStreamer's position on efforts such as LADSPA ? + + + + +GStreamer actively supports such efforts, and in the case of +LADPSA, +we already have a wrapper plugin. This wrapper plug-in detects the LADSPA +plugins present on your system at register time. + + + + + + + Does GStreamer support MIDI ? + + + + +Not yet. The GStreamer architecture should be able to support the needs of +MIDI applications very well however. If you are a developer interested in +adding MIDI support to GStreamer we are very interested in getting in touch +with you. + + + + + + + Does GStreamer depend on GNOME ? + + + + +No. But many of the applications developed for GStreamer do, including our +sample applications. There is nothing hindering people from developing +applications using other toolkits however and we would happily help promote +such efforts. A good example of an application using GStreamer, but which is +not using GNOME is the + +Mozstreamer which uses Mozilla XUL. + + + + + diff --git a/docs/faq/developing.xml b/docs/faq/developing.xml new file mode 100644 index 0000000000..e3b4c291f3 --- /dev/null +++ b/docs/faq/developing.xml @@ -0,0 +1,190 @@ + + Developing applications with GStreamer + + + + + + How do I compile programs that use GStreamer ? + + + + +GStreamer uses pkg-config to assist applications with compilationa 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: + +$ gcc `pkg-config --cflags --libs gstreamer` -o myprog myprog.c + +would be sufficient for a gstreamer-only program. +If (for example) your app also used GTK+ 2.0, you could use + +$ gcc `pkg-config --cflags --libs gstreamer gtk+-2.0` -o myprog myprog.c + +Those are back-ticks (on the same key with the tilde on US keyboards), +not single quotes. + + +For bigger projects, you should integrate pkg-config use in your Makefile, +or integrate with autoconf using the pkg.m4 macro. + + + + + + + How can I use GConf to get the system-wide defaults ? + + + + +It's a good idea to use GConf to use default ways of outputting audio and +video. Since GStreamer's GConf keys can be more than +just one element, but a whole pipeline, it would be a good idea +to use the gstgconf library. It provides functions to parse the GConf key +to a usable pipeline. + + +To link against gstgconf, use pkg-config to query the gstreamer-libs.pc file +for link flags, and add -lgstgconf to the link flags. +This fragment of configure.ac shows how to use pkg-config to get the LIBS: + + +dnl check for GStreamer helper libs +PKG_CHECK_MODULES(GST_HELPLIBS, gstreamer-libs >= $GSTREAMER_REQ,,exit) +AC_SUBST(GST_HELPLIBS_LIBS) +AC_SUBST(GST_HELPLIBS_CFLAGS) + + +This fragment of a Makefile.am file shows how to make your application link +to it: + + +bin_PROGRAMS = application + +application_LDADD = $(GST_LIBS) $(GST_HELPLIBS_LIBS) -lgstgconf +application_CFLAGS = $(GST_CFLAGS) $(GST_HELPLIBS_CFLAGS) + + + + + + + +How do I debug these funny shell scripts that libtool makes ? + + + + + +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 gdb /path/to/gstreamer-launch +. +If this does not work, you're probably using a broken version of libtool. + + + + + + + Why is mail traffic so low on gstreamer-devel ? + + + + +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. +However, we do archive our IRC discussions, which you may find in the +gstreamer-daily mailing list archives. + + + + + + + What kind of versioning scheme does GStreamer use ? + + + + +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 CVS version. +Any tarball or package that has a nano number of 1 is made from CVS 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. + + + + + + + What is the coding style for GStreamer core ? + + + + +The core is basically coded in K&R with 2-space indenting. +Just follow what's already there and you'll be fine. +The core could use a code cleanup though at this point. + + +Individual plugins in gst-plugins or plugins that you want considered for +addition to the gst-plugins module should be coded in the same style. +It's easier if everything is consistent. Consistency is, of course, the goal. + + +If you use emacs, try these lines: + +(defun gstreamer-c-mode () + "C mode with adjusted defaults for use with GStreamer." + (interactive) + (c-mode) + (c-set-style "K&R") + (setq c-basic-offset 2)) + +(setq auto-mode-alist (cons '("gst.*/.*\\.[ch]$" . gstreamer-c-mode) + auto-mode-alist)) + + + +Or, run your code through + +indent -br -bad -cbi0 -cli2 -bls -l100 -ut -ce + +before submitting a patch (FIXME: check if these are indeed the proper options). + + +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. + + + + + diff --git a/docs/faq/general.xml b/docs/faq/general.xml new file mode 100644 index 0000000000..4b832a3161 --- /dev/null +++ b/docs/faq/general.xml @@ -0,0 +1,189 @@ + + General + + + + + Is GStreamer a media player ? + + + + +No, GStreamer is a development framework for creating applications like +media players, video editors, streaming media broadcasters and so on. +That said, very good media players can easily be built on top +of GStreamer and we even include a simple yet functional media player +with GStreamer, called gst-player. + + + + + + + +Why is GStreamer written in C ? Why not C++/Objective-C/... ? + + + + + +We like C. Aside from "personal preference", there are a number of technical +reasons why C is nice in this project: + +C is extremely portable. +C is fast. +It is easy to make language bindings for libraries written in C. + +The GObject object system provided by GLib implements objects in C, +in a portable, powerful way. This library provides for introspection and +runtime dynamic typing. It is a full OO system, but without the syntactic +sugar. If you want sugar, take a look at +GOB. +Use of C integrates nicely with Gtk+ and GNOME. Some people like +this a lot, but neither Gtk+ nor GNOME are required by GStreamer. + + + +So, in closing, we like C. If you don't, that's fine; if you still want to +help out on GStreamer, we always need more language binding people. And if +not, don't bother us; we're working :-) + + + + + + + What applications are available for GStreamer ? + + + +GStreamer is still very early in its development, but already we see some +really nice applications being developed in parallel with GStreamer. +Both gst-player and gst-editor are very closely linked to GStreamer itself +for obvious reasons. +For a list of some of the more advanced projects, look at the list +in our Status table. + + + + + + + +What are the exact licensing terms for GStreamer and its plugins ? + + + + +All of GStreamer, including our own plugin code, is licensed under the +GNU LGPL license. +Some of the libraries we use for some of the plugins are however under the +GPL, which means that those plugins can not be used by a non-GPL-compatible +application. + + +As part of the GStreamer source download you find a file called +license_README. That file contains information in the exact licensing +terms of the libraries we use. As a general rule, GStreamer aims at using +only LGPL or BSD licensed libraries if available and only use GPL or +proprietary libraries where no good LGPL or BSD alternatives are available. + +From GStreamer 0.4.2 on, we implemented a license field for all of the plugins, +and in the future we might have the application enforce a stricter policy +(much like tainting in the kernel). + + + + + + + + Is GStreamer a sound server ? + + + +No, GStreamer is not a soundserver. GStreamer does however have plugins +supporting most of the major soundservers available today, including +ESD, aRTSd, and to some extent Jack. Support for MAS is also planned. + + + + + + + +Will GStreamer be available for platforms other than Unix ? + + + + +Depends. Our main target is the Unix platform. That said, interest has been +expressed in porting GStreamer to other platforms and the GStreamer core +team will gladly accept patches to accomplish this. +Please refer to the + +platform support status table + + + + + + + What is GStreamer's relationship with the GNOME community ? + + + +While GStreamer is operated as an independent project, we do have a close +relationship with the GNOME community. Many of our hackers consider +themselves also to be members of the GNOME community. There are plans to +make (some part of) GStreamer an official part of the development framework +of GNOME. This does not exclude use of GStreamer by other communities at +all, of course. + + + + + + + What is GStreamer's relationship with the KDE community ? + + + +The GStreamer community wants to have as good a relationship as possible +with KDE, and we hope that someday KDE decides to adopt GStreamer as their +multimedia API, just like the GNOME community plans on doing. +There have been contacts from time to time between the GStreamer community +and KDE and we do already have support for the aRTSd sound server used by KDE. +Also, some of the KDE hackers have created Qt bindings of GStreamer +and made a simple video player. + + + + + + + +I'm considering adding GStreamer output to my application... + + + + + +That doesn't really make sense. GStreamer is not a sound server, so you don't +output directly to GStreamer, and it's not an intermediate API between +audio data and different kinds of audio sinks. It is a fundamental design +decision to use GStreamer in your app; there are no easy ways of somehow +'transfering' data from your app to GStreamer. Instead, your app would have +to use or implement a number of GStreamer elements, string them together, and +tell them to run. In that manner the data would all be internal to the +GStreamer pipeline. + + +That said, it is possible to write a plugin specific to your app that can get +at the audio data. + + + + + + diff --git a/docs/faq/getting.xml b/docs/faq/getting.xml new file mode 100644 index 0000000000..d050ff5cd9 --- /dev/null +++ b/docs/faq/getting.xml @@ -0,0 +1,17 @@ + + Getting GStreamer + + + + + How do I get GStreamer ? + + + + +You either ask us nicely for it or pay us big bucks. + + + + + diff --git a/docs/faq/gstreamer-faq.xml b/docs/faq/gstreamer-faq.xml new file mode 100644 index 0000000000..f6f924b4ce --- /dev/null +++ b/docs/faq/gstreamer-faq.xml @@ -0,0 +1,44 @@ + + + + + + + + + +]> + +
+ + GStreamer FAQ + + + This is the FAQ for GStreamer, a multimedia framework. + Questions and answers range from general information to + deep-down-and-dirty compilation issues. + + + + + + 0.1 + 2002-10-01 + Initial conversion from FAQ database. + + + + + + &START; + &GENERAL; + &DEPENDENCIES; + &GETTING; + &USING; + &DEVELOPING; + &TROUBLESHOOTING; + +
diff --git a/docs/faq/magic-pdf b/docs/faq/magic-pdf new file mode 100644 index 0000000000..abc274e270 --- /dev/null +++ b/docs/faq/magic-pdf @@ -0,0 +1 @@ + diff --git a/docs/faq/magic-png b/docs/faq/magic-png new file mode 100644 index 0000000000..6941e28950 --- /dev/null +++ b/docs/faq/magic-png @@ -0,0 +1 @@ + diff --git a/docs/faq/start.xml b/docs/faq/start.xml new file mode 100644 index 0000000000..ee3aa72371 --- /dev/null +++ b/docs/faq/start.xml @@ -0,0 +1,16 @@ + + Getting Started + +So you're eager to get started learning about GStreamer. +There's a few ways you can get started. + +If you want to learn by reading about it, start with + + +If you'd rather learn by trying it out, start with + + + + + + diff --git a/docs/faq/troubleshooting.xml b/docs/faq/troubleshooting.xml new file mode 100644 index 0000000000..93bb97b416 --- /dev/null +++ b/docs/faq/troubleshooting.xml @@ -0,0 +1,23 @@ + + Troubleshooting GStreamer + + + + + +I'm having problems building or installing GStreamer. What should I do ? + + + + + +We've started a step-by-step + +troubleshooting guide. +Look there before asking, your problem might already have been solved by +someone else. + + + + + diff --git a/docs/faq/using.xml b/docs/faq/using.xml new file mode 100644 index 0000000000..5a1566a569 --- /dev/null +++ b/docs/faq/using.xml @@ -0,0 +1,105 @@ + + Using GStreamer + + + + + How do I tell what GStreamer plugins I have on my system ? + + + + +To do this you use the gst-inspect +command-line tool, which comes standard with GStreamer. +Invoked without any arguments, + +$ gst-inspect + +will print out a listing of installed plugins. +To learn more about a particular plugin, pass its name on the command line. +For example, + +$ gst-inspect volume + +will give you information about the volume plugin. + + +Also, if you install the gst-editor package, you will have a graphical +plugin browser available, gst-inspect-gui. + + + + + + + Where should I report bugs ? + + + + +Bug management is now hosted on GNOME's Bugzilla at +http://bugzilla.gnome.org, +under the product GStreamer. +Using bugzilla you can view past bug history, report new bugs, etc. +Bugzilla requires you to make an account here, which might seem cumbersome, +but allows us to at least have a chance at contacting you for further +information, as we will most likely have to. + + +When doing a bug report, you should at least describe + +your distribution + +how you installed GStreamer (from cvs, source, packages, which ?) +if you installed GStreamer before + + + +If you're new to GStreamer, it also is useful for us if you attach output of +the gst-feedback command to your bug report. +If you're having problem with a specific application (either one of ours, +somebody else's, or your own), please also provide a log of gst-mask by +running + +myapp --gst-mask=-1 > mask.log 2>&1 +gzip mask.log + +(interrupting the program if it doesn't stop by itself) +and attach mask.log.gz to your bug report + + + + + + + How do I use the GStreamer command line interface ? + + + +You access the GStreamer command line interface using the command gst-launch. +To decode an mp3 and play it through OSS, you could use + +gst-launch filesrc location=thesong.mp3 ! mad ! osssink +. +More examples can be found in the gst-launch man page. + + +To automatically detect the right codec in a pipeline, try + +gst-launch filesrc location=my-random-media-file.mpeg ! spider ! osssink +. +Try replacing osssink with sdlvideosink and see what happens. + + +We also have a simple tool called gst-launch-ext used for debugging, +which has predefined pipelines for you. This means you can just write + +gst-launch-ext (filename) + +and it will play the file if the extension is supported. Note that no effort +has been made for uninterrupted synchronized playback using this tool. + + + + +