diff options
| -rw-r--r-- | doc/faq/.cvsignore | 2 | ||||
| -rw-r--r-- | doc/faq/Makefile.am | 14 | ||||
| -rw-r--r-- | doc/faq/faq.html | 3800 | ||||
| -rw-r--r-- | doc/faq/faq.txt | 1364 | ||||
| -rw-r--r-- | doc/hackersguide/.cvsignore | 2 | ||||
| -rw-r--r-- | doc/hackersguide/Makefile.am | 15 | ||||
| -rw-r--r-- | doc/hackersguide/hackersguide.html | 5108 | ||||
| -rw-r--r-- | doc/hackersguide/overview.sgml | 5 |
8 files changed, 34 insertions, 10276 deletions
diff --git a/doc/faq/.cvsignore b/doc/faq/.cvsignore index 282522db0..647d53c1d 100644 --- a/doc/faq/.cvsignore +++ b/doc/faq/.cvsignore @@ -1,2 +1,4 @@ Makefile Makefile.in +faq.html +faq.txt diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am index ba3ebd15c..1e6fe0142 100644 --- a/doc/faq/Makefile.am +++ b/doc/faq/Makefile.am @@ -1,6 +1,6 @@ include $(top_srcdir)/misc/Makefile.common -EXTRA_DIST = $(docs_DOCS) README faq.sgml +EXTRA_DIST = README faq.sgml docs_DOCS = faq.html faq.txt docdir = $(prefix)/share/doc/xine/faq @@ -28,12 +28,24 @@ uninstall-local: docs: $(docs_DOCS) +dist-hook: + @make fail_if_missing=yes docs + cp $(docs_DOCS) $(distdir) + faq.html: faq.sgml @if test "$(SGMLTOOLS)" != "no"; then \ $(SGMLTOOLS) -b onehtml faq.sgml; \ + else if test "$(fail_if_missing)" = "yes"; then \ + echo "Please install sgmltools-lite."; \ + exit 1; \ + fi; \ fi faq.txt: faq.sgml @if test "$(SGMLTOOLS)" != "no"; then \ $(SGMLTOOLS) -b txt faq.sgml; \ + else if test "$(fail_if_missing)" = "yes"; then \ + echo "Please install sgmltools-lite."; \ + exit 1; \ + fi; \ fi diff --git a/doc/faq/faq.html b/doc/faq/faq.html deleted file mode 100644 index 91e33a987..000000000 --- a/doc/faq/faq.html +++ /dev/null @@ -1,3800 +0,0 @@ -<HTML -><HEAD -><TITLE ->The xine engine FAQ</TITLE -><META -NAME="GENERATOR" -CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD -><BODY -CLASS="BOOK" -><DIV -CLASS="BOOK" -><A -NAME="AEN1" -></A -><DIV -CLASS="TITLEPAGE" -><H1 -CLASS="TITLE" -><A -NAME="AEN2" -></A ->The xine engine FAQ</H1 -><P -CLASS="COPYRIGHT" ->Copyright © 2001-2003 the xine project team</P -><HR></DIV -><DIV -CLASS="TOC" -><DL -><DT -><B ->Table of Contents</B -></DT -><DT -><A -HREF="#AEN8" -></A -></DT -><DD -><DL -><DT -><A -HREF="#GENERAL" ->General questions about xine and this document</A -></DT -><DD -><DL -><DT -><A -HREF="#ABOUT" ->What is the xine engine?</A -></DT -><DT -><A -HREF="#SCOPE" ->What's the aim and scope of this text?</A -></DT -><DT -><A -HREF="#WHERETOGETHELP" ->My question is not yet covered here - where can I ask for help?</A -></DT -><DT -><A -HREF="#PRONOUNCE" ->How do I pronounce "xine"?</A -></DT -><DT -><A -HREF="#MODULES" ->What are those xine-lib, xine-ui, gxine, ... modules in cvs for?</A -></DT -><DT -><A -HREF="#CVS" ->Where and how do I get the latest development version?</A -></DT -><DT -><A -HREF="#BINARIES" ->Where can I find pre-compiled binaries, e.g. RPMs?</A -></DT -></DL -></DD -><DT -><A -HREF="#BUILDING" ->Building and installing xine from source</A -></DT -><DD -><DL -><DT -><A -HREF="#BUILDREQUIREMENTS" ->What do I need to compile everything properly?</A -></DT -><DT -><A -HREF="#AEN66" ->How do I compile xine?</A -></DT -><DT -><A -HREF="#RPMBUILD" ->Making your own RPM packages (xine-lib, xine-ui)</A -></DT -><DT -><A -HREF="#CFLAGS" ->Can I provide additional CFLAGS for compilation?</A -></DT -><DT -><A -HREF="#ATHLONFLAGS" ->Are there binaries for my AMD K7 (Athlon™) available? Can I build them?</A -></DT -><DT -><A -HREF="#AEN151" ->Build problems: xine engine (xine-lib)</A -></DT -><DT -><A -HREF="#AEN169" ->Build problems in frontends (gxine/xine-ui/...)</A -></DT -><DT -><A -HREF="#NONROOTBUILD" ->Can I install xine in my home directory (without being root)?</A -></DT -></DL -></DD -><DT -><A -HREF="#PLAYBACK" ->Playback of various stream types</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN199" ->DVD Playback with xine</A -></DT -><DT -><A -HREF="#VCDSUPPORT" ->Can I watch Video CDs (VCDs)? SVCDS ? CD-i?</A -></DT -><DT -><A -HREF="#QUICKTIME" ->Can I watch Quicktime (.mov, .mp4) files using xine?</A -></DT -><DT -><A -HREF="#AEN253" ->Real Network files/streams</A -></DT -><DT -><A -HREF="#WMV" ->Can I watch Windows Media (.asf/.wmv/.wma) files using xine?</A -></DT -><DT -><A -HREF="#DVB" ->Can I watch Digital TV (Digital Video Broadcast) using xine?</A -></DT -><DT -><A -HREF="#STDIN" ->How do I play streams from STDIN?</A -></DT -><DT -><A -HREF="#AVISUBTITLES" ->How can I watch files with external AVI subtitles?</A -></DT -></DL -></DD -><DT -><A -HREF="#RUNNING" ->Running xine</A -></DT -><DD -><DL -><DT -><A -HREF="#SPEEDUP" ->I have a lot of dropped frames - what can I do?</A -></DT -><DT -><A -HREF="#SMOOTHNESS" ->Oki, xine doesn't drop frames now but video output still is not really smooth!</A -></DT -><DT -><A -HREF="#PORTS" ->I have problems when using xine on FreeBSD, Solaris, ... !</A -></DT -><DT -><A -HREF="#AAXINE" ->What is aalib? How do I use it in xine?</A -></DT -><DT -><A -HREF="#CONFIGOPTIONS" ->What do all these <TT -CLASS="FILENAME" ->~/.xine/config</TT -> (<TT -CLASS="FILENAME" ->~/.gxine/config</TT ->) entries mean?</A -></DT -><DT -><A -HREF="#DXR3" ->Does xine support my dxr3 / hollywood+ card?</A -></DT -></DL -></DD -><DT -><A -HREF="#AUDIO" ->Audio related questions</A -></DT -><DD -><DL -><DT -><A -HREF="#AUDIODRIVERS" ->What audio drivers does xine support? OSS? Alsa? Arts? Esd?</A -></DT -><DT -><A -HREF="#COMPRESSOR" ->When I'm watching a movie, the sound effects are much higher in volume than the voices!</A -></DT -><DT -><A -HREF="#NOAUDIO" ->When I play this stream, xine shows video but there's no audio!</A -></DT -><DT -><A -HREF="#SURROUNDSOUND" ->Can xine produce 4-/5-channel surround audio output?</A -></DT -><DT -><A -HREF="#SPDIF" ->What about ac3 output via spdif to an external ac3 decoder?</A -></DT -><DT -><A -HREF="#SBLIVESPDIF" ->Getting SPDIF output from a SBLive 5.1 using OSS drivers</A -></DT -><DT -><A -HREF="#VOLUMECONTROL" ->Changing the volume with the GUI control has no effect! What's up!?</A -></DT -><DT -><A -HREF="#STUTTERING" ->Audio is stuttering and i see a lot of "metronom: fixing sound card drift by -2115 pts" on the console output</A -></DT -><DT -><A -HREF="#SOUNDLOSS" ->xine seems to lose sound arbitrarily during playback, especially with DVDs</A -></DT -></DL -></DD -><DT -><A -HREF="#VIDEO" ->Video related questions</A -></DT -><DD -><DL -><DT -><A -HREF="#NOVIDEO" ->I can hear the audio - but I don't see a picture!</A -></DT -><DT -><A -HREF="#XVEXTENSION" ->How can I make xine use the Xv extension and what drivers do I need?</A -></DT -><DT -><A -HREF="#COLORKEY" ->Some parts of my X Desktop get transparent when xine plays the video!</A -></DT -><DT -><A -HREF="#ASPECTRATIO" ->The aspect ratio of the video is wrong!</A -></DT -><DT -><A -HREF="#DISCARDEDSKIPPED" ->What is the difference between discarded and skipped frames?</A -></DT -><DT -><A -HREF="#CONTRASTBRIGHTNESSSATURATION" ->My xine is runing in black and white! / I only get a gray video output!</A -></DT -><DT -><A -HREF="#VIDEODRIVER" ->Which is the best video driver to use?</A -></DT -></DL -></DD -><DT -><A -HREF="#ERRORS" ->Error Messages: What they mean and what you can do</A -></DT -><DD -><DL -><DT -><A -HREF="#AUDIODRIVERERR" ->Starting xine fails with complains about audio drivers/devices!</A -></DT -><DT -><A -HREF="#NOVIDEOPORTFOUND" ->"no video port found"</A -></DT -><DT -><A -HREF="#UNABLETOOPENDVDDRIVE" ->"Unable to open dvd drive (/dev/dvd)"</A -></DT -><DT -><A -HREF="#STATUS0X51" ->My drive doesn't work and the kernel says "status=0x51 { DriveReady SeekComplete Error }"</A -></DT -><DT -><A -HREF="#DEMUXERROR0000" ->"demux error! 00 00 00 (should be 0x000001)"</A -></DT -><DT -><A -HREF="#OSSFAILED" ->"audio driver 'oss' failed, using null driver instead"</A -></DT -><DT -><A -HREF="#THROWINGAWAYIMAGE" ->"video_out: throwing away image with pts xxx because it's too old"</A -></DT -><DT -><A -HREF="#NOVIDEOPLUGINAVAILABLE" ->"No video plugin available to decode 'xxxxxx'."</A -></DT -><DT -><A -HREF="#DECODERFAILEDTOSTART" ->"w32codec: decoder failed to start. Is 'xxxxxx' installed?"</A -></DT -><DT -><A -HREF="#XINECRASHED" ->xine just crashed on me - i didn't get any error message</A -></DT -></DL -></DD -></DL -></DD -></DL -></DIV -><DIV -CLASS="ARTICLE" -><DIV -CLASS="SECT1" -><H2 -CLASS="SECT1" -><A -NAME="GENERAL" -></A ->General questions about xine and this document</H2 -><DIV -CLASS="SECT2" -><H3 -CLASS="SECT2" -><A -NAME="ABOUT" -></A ->What is the xine engine?</H3 -><P -> - The xine engine is a free media player engine. It comes in the form of - a shared libarary and is typically used by media player frontends - and other multimedia applications for playback of multimedia streams - such as movies, radio/tv network streams, DVDs, VCDs. - </P -><P -> Since there are several frontends for the xine library available, - this document has a problem when it comes to examples. - The two most common frontends xine-ui and gxine are mixed in command - line examples throughout this FAQ. When you use a different - frontend, some of these will not work for you. The filename of - the config file also varies amongst frontends. If you get confused, - I recommend you try with one of xine-ui or gxine. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="SCOPE" -></A ->What's the aim and scope of this text?</H3 -><P -> The primary goal of this FAQ is to cover all recurring questions related - to the xine engine. Frontend specific questions are usually not covered here. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="WHERETOGETHELP" -></A ->My question is not yet covered here - where can I ask for help?</H3 -><P -> First of all be sure that your question is really not covered here and - that you haven't just been a bit too lazy to read through all of this - text. ;-). Also check out the documentation specific to - the frontend (e.g. <B -CLASS="COMMAND" ->xine-ui</B -> or <B -CLASS="COMMAND" ->gxine</B -> or - <B -CLASS="COMMAND" ->totem</B ->). - </P -><P -> That said - you are welcome to mail to our user mailing list: - <TT -CLASS="EMAIL" -><<A -HREF="mailto:xine-user@lists.sourceforge.net" ->xine-user@lists.sourceforge.net</A ->></TT -> - Please provide some info about your setup so people have a chance to - help you, e.g. include information about your audio/video hardware - and drivers you use, operating system, cpu type and some console - output/any error messages. Also include command line parameters you - have specified and information about the type of stream you're - trying to play back. Also very important is the version of xine - you're using and information about any additional plugins you - may have installed on your system. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="PRONOUNCE" -></A ->How do I pronounce "xine"?</H3 -><P -> As long as people know what you are talking about, you are free to - pronounce it the way you like, but the official pronounciation is - [ksi:n], like the name "Maxine" with the "Ma" removed. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="MODULES" -></A ->What are those xine-lib, xine-ui, gxine, ... modules in cvs for?</H3 -><P -> Some time ago xine just became too complex to be just one big program. - Therefore it was split into two major parts. - </P -><P -> xine-lib is simply speaking the engine of xine. It contains all basic plugins - and is necessary to run anything that relies on xine. (This is the part that - is covered in this FAQ.) - </P -><P -> Then there are frontends - applications that use xine. The most - common frontend is that of a media player. There are currently - two frontends being developed in the xine project, xine-ui (skinned - dvd-player style frontend directly based on xlib) and gxine, - a desktop media-player style frontend using the standard gtk widget set - and comes with a mozilla browser plugin. - External projects like kaffeine, sinek and totem develop additional frontends. - In the future you will likely see more and different types of applications - being developed which will use the xine engine for video processing - and other multimedia purposes. - </P -><P -> If you simply want a media/dvd player, you'll need to install xine-lib - first and then choose and install a player frontend like xine-ui or gxine. - </P -><P -> Other modules in CVS are: <TT -CLASS="FILENAME" ->xine-plugin</TT -> a mozilla browser plugin - for streaming media playback using xine, - <TT -CLASS="FILENAME" ->xine-www</TT -> the - xine project website sources. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="CVS" -></A ->Where and how do I get the latest development version?</H3 -><P -> Be advised that end-users should stick to the official xine releases. - CVS is only intended for developers and for others who know why they use it. - </P -><P -> To check out xine-modules from CVS, first do this: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->cvs -d :pserver:anonymous@cvs.xine.sourceforge.net:/cvsroot/xine login</B -></PRE -></TD -></TR -></TABLE -> - The password is empty, just press Enter. - </P -><P -> Then, to check out individual modules (e.g. <TT -CLASS="FILENAME" ->xine-lib</TT ->, - <TT -CLASS="FILENAME" ->gxine</TT -> or <TT -CLASS="FILENAME" ->xine-ui</TT ->): - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->cvs -d :pserver:anonymous@cvs.xine.sourceforge.net:/cvsroot/xine co <modulename></B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="BINARIES" -></A ->Where can I find pre-compiled binaries, e.g. RPMs?</H3 -><P -> The xine project does not provide pre-compiled binaries for legal - reasons (some parts of xine may be covered by patents in some countries). - Some OS projects/vendors (e.g. debian, freebsd, ...) offer binaries - for their distributions - please contact them for further info. - You can also find links to third parties providing xine RPMs on - the xine homepage at - <A -HREF="http://xinehq.de/index.php/releases" -TARGET="_top" ->http://xinehq.de/index.php/releases</A ->. - </P -><P -> See the next section of this FAQ for instructions on how to build xine - from source. - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="BUILDING" -></A ->Building and installing xine from source</H2 -><DIV -CLASS="SECT2" -><H3 -CLASS="SECT2" -><A -NAME="BUILDREQUIREMENTS" -></A ->What do I need to compile everything properly?</H3 -><P -> First of all an official and stable release of gcc. Also be aware - that patched gcc versions may break parts of xine and are therefore - not supported by the xine project. - </P -><P -> Furthermore you'll have to use GNU make to compile xine. On most GNU/Linux - systems "make" is GNU make - on other platforms use "gmake" instead. - Also, zlib is required (including the appropriate header files, which are - often found in a package called zlib-devel or similar.) - </P -><P -> If you want to compile xine from CVS, you'll need to have the autobuild tools - installed (automake, autoconf and libtool - in recent versions). - </P -><P -> Frontends might need additional libraries, e.g. for gxine you'll need to have - GTK installed. Make sure you have not only the shared libraries themselves - but also the header files (often packaged seperately as so-called -dev packages) - on your system. - </P -><P -> Some plugins that come with the xine engine need additional libraries (otherwise - they will not be built). For example, libogg and libvorbis (plus their include files) - are needed for ogg/vorbis support. Most notably, if you want to see any video - on your X11 desktop (and that's what you're here for, isn't it?), you need the - XFree developer packages as well. - </P -><P -> Don't worry about this too much right now, xine's <B -CLASS="COMMAND" ->configure</B -> - (see below) will check for all the stuff needed and will tell you what's missing - (which means that you should check the output it produces carefully ;) ). - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN66" -></A ->How do I compile xine?</H3 -><DIV -CLASS="SECT3" -><H4 -CLASS="SECT3" -><A -NAME="SIMPLEBUILDINSTR" -></A ->Simple build instructions for beginners</H4 -><P -> Download the latest xine-lib and gxine/xine-ui tarballs, then follow - these instruction. To unpack a tarball, use: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->tar xfvz tarballname.tar.gz</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> The following instructions will install xine in <TT -CLASS="FILENAME" ->/usr/local</TT -> - where it will be visible for all users. You need root privileges to do this on most systems. - </P -><P -> After unpacking xine-lib, issue: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->./configure</B -> - <B -CLASS="COMMAND" ->make install</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> Make sure your <TT -CLASS="FILENAME" ->/etc/ld.so.conf</TT -> contains - <TT -CLASS="FILENAME" ->/usr/local/lib</TT -> and continue with: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->ldconfig</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> Now unpack your frontend (gxine or xine-ui or ...), then: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->./configure</B -> - <B -CLASS="COMMAND" ->make install</B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="COMPLETEBUILDINSTR" -></A ->Complete build instructions</H4 -><P -> The build process is the same for all of the xine modules. - </P -><P -> You have to start with xine-lib. If built and installed successfully, you - can continue with the frontend(s). - </P -><P -> If you have installed xine-lib to a non-standard prefix, make sure - that you have <TT -CLASS="FILENAME" ->$prefix/bin</TT -> in your PATH and that your linker finds - libs in <TT -CLASS="FILENAME" ->$prefix/lib</TT -> - otherwise trying to build modules that - rely on xine-lib will fail with configure complaining about not - finding certain parts of libxine. Using bash you can do something like: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->export PATH="$prefix/bin:$PATH"</B -> - <B -CLASS="COMMAND" ->export LD_LIBRARY_PATH="$prefix/lib:$LD_LIBRARY_PATH"</B -></PRE -></TD -></TR -></TABLE -> - to make sure libxine can be found by the frontend(s). - </P -><P -> Last but not least. Here the build instructions. As stated earlier, - those are the same for every xine module. - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->./autogen.sh</B -> [-> *only* if you checked your sources out of CVS] - <B -CLASS="COMMAND" ->./configure</B -> - <B -CLASS="COMMAND" ->make</B -> - <B -CLASS="COMMAND" ->make install</B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="RPMBUILD" -></A ->Making your own RPM packages (xine-lib, xine-ui)</H3 -><P -> Basically you will only have to issue one command, if you have just - downloaded a source tarball from our web site: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->rpm -ta <THE_NAME_OF_YOUR_SOURCE_TAR_BALL></B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> This will start the binary and source RPM building. After compiling is - finished, a binary rpm is placed in your rpm binary directory which is - something like <TT -CLASS="FILENAME" ->/usr/src/RPM/RPMS/<YOUR_ARCHITECTURE></TT -> - and a source RPM is written to your rpm source dir - (e.g. <TT -CLASS="FILENAME" ->/usr/src/RPM/SRPMS</TT ->). - </P -><P -> In case that you have a fresh CVS checkout, you will need to do the - following first in order to get a tarball release out of it which you - can later use with the <B -CLASS="COMMAND" ->rpm -ta</B -> command above: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->./autogen.sh && make clean && make dist</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> In any case, please keep in mind that you have to build and install - xine-lib first before you can proceed with xine-ui. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="CFLAGS" -></A ->Can I provide additional CFLAGS for compilation?</H3 -><P -> Yes, you can do so by setting the CFLAGS variable and then running - <B -CLASS="COMMAND" ->configure</B -> again. You can even pass them to - <B -CLASS="COMMAND" ->configure</B -> directly. Example: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->./configure CFLAGS="-march=i686"</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> Other user variables <B -CLASS="COMMAND" ->configure</B -> respects are: - <P -></P -><UL -><LI -><P -> <B -CLASS="COMMAND" ->CC</B -> to specify the compiler executable - </P -></LI -><LI -><P -> <B -CLASS="COMMAND" ->CPP</B -> to specify the C preprocessor executable - </P -></LI -><LI -><P -> <B -CLASS="COMMAND" ->LD</B -> to specify the linker executable - </P -></LI -><LI -><P -> <B -CLASS="COMMAND" ->CPPFLAGS</B -> to pass additional include paths or other - preprocessor options - </P -></LI -><LI -><P -> <B -CLASS="COMMAND" ->LDFLAGS</B -> to pass additional library paths or other - linker options - </P -></LI -></UL -> - </P -><P -> An example combining some of these would look like: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->./configure CC="/opt/intel/bin/icc" LD="/opt/intel/bin/xild" CPPFLAGS="-I/usr/local/include/dvdnav" LDFLAGS="-L/home/guenter/xine_libs"</B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="ATHLONFLAGS" -></A ->Are there binaries for my AMD K7 (Athlon™) available? Can I build them?</H3 -><P -> If you have a recent gcc you can try to compile "more" k7 support in (esp. - better instruction scheduling). If the configure script should fail to - detect your processor/gcc correctly, try passing the canonical system name for - your machine to configure with the <B -CLASS="COMMAND" ->--host</B -> option, e.g. - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->./configure --host=k7-pc-linux-gnu</B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN151" -></A ->Build problems: xine engine (xine-lib)</H3 -><DIV -CLASS="SECT3" -><H4 -CLASS="SECT3" -><A -NAME="DOESNTCOMPILE" -></A ->The package doesn't compile at all!</H4 -><P -> In order to be able to compile xine-lib, you need (amongst other things) - the zlib compression library plus the appropriate headers, which are - often found in a package called zlib-devel or similar. - </P -><P -> Read again carefully the output <B -CLASS="COMMAND" ->./configure</B -> - produced and/or compiler warnings and error reports, they often contain - helpful information to find out what's going on. If you're stuck here - and decide to post your problem on the xine-user mailing list, - make sure you include these outputs. - </P -></DIV -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="XVPLUGINFAILSTOBUILD" -></A ->The Xv video-out plugin fails to compile!</H4 -><P -> If you want to have Xv support compiled in, make sure you either have - a shared Xv library on your system, e.g. - <B -CLASS="COMMAND" ->ls /usr/X11R6/lib/libXv*</B -> - should give you some .so libs, like this: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> /usr/X11R6/lib/libXv.a - /usr/X11R6/lib/libXv.so - /usr/X11R6/lib/libXv.so.1</PRE -></TD -></TR -></TABLE -> - </P -><P -> Alternatively you need to have libtool 1.4 or newer installed, then - libXv.a is sufficient. Otherwise you can create the shared versions yourself: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->ld --whole-archive -shared -o libXv.so.1 libXv.a</B -> - <B -CLASS="COMMAND" ->ln -s libXv.so.1 libXv.so</B -> - <B -CLASS="COMMAND" ->ldconfig</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> Now you should be ready to build the Xv video-out plugin on your system. - </P -></DIV -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN169" -></A ->Build problems in frontends (gxine/xine-ui/...)</H3 -><DIV -CLASS="SECT3" -><H4 -CLASS="SECT3" -><A -NAME="XINELIBNOTFOUND" -></A ->I have installed xine-lib but the frontend complains about not finding it!</H4 -><P -> First of all take a closer look at the compilation instructions above again. - You will probably find your answer there right away. - </P -><P -> As stated there (there again that hint *grin*), make sure that you - have <TT -CLASS="FILENAME" ->$prefix/bin</TT -> in your path and that your - linker is able to find libraries installed in <TT -CLASS="FILENAME" ->$prefix/lib</TT -> - By the way, $prefix is where you installed your xine-lib to earlier - (yes, installing xine-lib with <B -CLASS="COMMAND" ->make install</B -> would be a good - idea before trying to compile the frontend ;) ). - </P -></DIV -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="NONROOTBUILD" -></A ->Can I install xine in my home directory (without being root)?</H3 -><P -> Sure. First set up a subdir where you install your private software, eg. - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->mkdir ~/xine</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> Then you have to set a few environment variables - it's probably a good - idea to add this to your <TT -CLASS="FILENAME" ->~/.bashrc</TT -> (or somewhere similar): - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->export PATH="$HOME/xine/bin:$PATH"</B -> - <B -CLASS="COMMAND" ->export LD_LIBRARY_PATH="$HOME/xine/lib:$LD_LIBRARY_PATH"</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> Now you can unpack tarballs e.g. in <TT -CLASS="FILENAME" ->~/xine/src</TT -> - (<B -CLASS="COMMAND" ->mkdir ~/xine/src</B -> if necessary) and do a - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->./configure --prefix=$HOME/xine</B -> - <B -CLASS="COMMAND" ->make install</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> You also need to tell frontends using xine-lib, where to find it: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->./configure --prefix=$HOME/xine --with-xine-prefix=$HOME/xine</B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="PLAYBACK" -></A ->Playback of various stream types</H2 -><DIV -CLASS="SECT2" -><H3 -CLASS="SECT2" -><A -NAME="AEN199" -></A ->DVD Playback with xine</H3 -><DIV -CLASS="SECT3" -><H4 -CLASS="SECT3" -><A -NAME="DVDPLAYBACK" -></A ->How do I play back DVDs with xine?</H4 -><P -> Newer xine (1.0.x) releases come with a full-featured - DVD plugin that should be able to handle any unencrypted, - non-locked DVD with full menu navigation support. No external - plugins are required anymore here. - </P -><P -> To get DVD playback working, first make sure you have - a symlink <TT -CLASS="FILENAME" ->/dev/dvd</TT -> pointing to your - DVD device on your system. For example, if your DVD drive - is the master ide drive on the second IDE channel, - <TT -CLASS="FILENAME" ->/dev/dvd</TT -> should point to - <TT -CLASS="FILENAME" ->/dev/hdc</TT ->. Please note that if you - are using the ide-scsi emulation on your system, it is - likely that your DVD drive got mapped to a scsi device - node even though it is an ide drive. In that case first - check out you boot/kernel logs (or run <B -CLASS="COMMAND" ->cdrecord -scanbus</B ->) - to find out which device it got mapped to and set the - symlink accordingly (should be something like <TT -CLASS="FILENAME" ->/dev/scd0</TT ->, - <TT -CLASS="FILENAME" ->/dev/scd1</TT ->, ... in that case). - Also make sure you (as a user) have sufficient (read and write) permissions - on your DVD drive. This could mean you either have to change the device - permissions or add your user to a special group - (e.g. <B -CLASS="COMMAND" ->addgroup cdrom username</B ->), - depending on your setup and/or distribution. - </P -><P -> It is highly recommended to switch DMA mode on for your DVD drive - (without it even very recent machines will have trouble producing - smooth video output). Use a command like - <B -CLASS="COMMAND" ->hdparm -d 1 <device></B -> - on your DVD device. Please note that even if you're using ide-scsi - you will have to set the dma flag on the ide device node (e.g. - <TT -CLASS="FILENAME" ->/dev/hdc</TT ->), not the mapped <TT -CLASS="FILENAME" ->/dev/scd</TT -> - scsi device. - </P -><P -> To be able to play back encrypted DVDs you need to have - libdvdcss installed on your system (please check if this is legal where - you live). If you do not understand what the term "encrypted DVD" means - here: As a rule of thumb, every DVD you have to pay money for is most - likely encrypted. - </P -><P -> To make matters worse, apart from encryption, there is another obstacle - to take: the region code. The DVD authorities decided to divide the world - into eight geographical regions. Have a look at - <A -HREF="http://www.dvdforum.gr.jp/RegionMap.pdf" -TARGET="_top" ->http://www.dvdforum.gr.jp/RegionMap.pdf</A -> - if you want to know which number has been assigned to your country. It is - now their idea, that you shall only play DVDs, which have been produced - for your region. If you take a DVD off the shelf in your local store, - you should find a little globe-like icon which shows the region code the - disc is for. - </P -><P -> Newer (post-2000) DVD drives (so-called RPC-2 drives) check the DVD - region, which means they'll prevent you from playing back DVDs that have - a different region code from what the drive is set up for. Some drives - come with a factory setting of region 0 so they can play back - any DVD until a region code is set. Others refuse to play any DVD at all - until they are told a region. The easiest way to handle this is to use - the regionset utility from - <A -HREF="http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415" -TARGET="_top" -> http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 - </A ->. - </P -><P -> Once you have everything set up, try something like - <B -CLASS="COMMAND" ->gxine dvd:/</B -> or <B -CLASS="COMMAND" ->xine -p dvd:/</B -> - to start dvd playback. Some frontend also offer so-called autoplay - buttons or menu entries that start dvd playback immediately. - </P -><P -> Important: do not try to mount the DVD. Just insert it and hit the DVD autoplay - button or start xine from the command line. - </P -><P -> If things do not work as expected, try running the <B -CLASS="COMMAND" ->xine-check</B -> - shellscript that comes with xine to see if this gives you further hints on - what could be wrong. - </P -></DIV -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="DVDLONGWAIT" -></A ->DVD playback works, but it takes a long time until playback starts</H4 -><P -> This points to a region code problem. Some versions of libdvdcss can play - back DVDs from other regions than the RPC-2 DVD drive is set up for, - but this usually means a cryptographic attack (which takes time) has - to be used to access the DVD. - </P -><P -> You can download a tool to set the region code of RPC-Drives here: - <A -HREF="http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415" -TARGET="_top" -> http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 - </A ->. - </P -><P -> Warning: Please be aware that the number of region code changes in RPC-2 - drives is limited (usually about 5 times), after that your drive will - stay locked to the region you last set it up for. - </P -></DIV -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="REGIONSET" -></A ->I have problems setting up my RPC-2 drive for the right region!</H4 -><P -> You can download a tool to set the region code of RPC-Drives here: - <A -HREF="http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415" -TARGET="_top" -> http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 - </A ->. - </P -><P -> Warning: Please be aware that the number of region code changes in RPC-2 - drives is limited (usually about 5 times), after that your drive will - stay locked to the region you last set it up for. - </P -></DIV -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="VCDSUPPORT" -></A ->Can I watch Video CDs (VCDs)? SVCDS ? CD-i?</H3 -><P -> xine supports VCD and SVCD playback out-of-the box. Similar to DVDs, - make sure you have a <TT -CLASS="FILENAME" ->/dev/cdrom</TT -> alias pointing - to your CDROM drive which you will use to play back the (S)VCD. - </P -><P -> At the moment, CD-i formats are not supported by xine. - </P -><P -> Do not try to mount the (S)VCD. Simply insert it into your CDROM drive - and hit the VCD autoplay button or start something like - <B -CLASS="COMMAND" ->gxine vcd:/</B -> or <B -CLASS="COMMAND" ->xine vcd:/</B -> - from the command line. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="QUICKTIME" -></A ->Can I watch Quicktime (.mov, .mp4) files using xine?</H3 -><P -> Quicktime is just a system layer (container format) which can contain various - different audio and video formats. The system layer itself is fully supported - in xine. However, some quicktime audio/video codecs are not natively supported yet. - Luckily, if you are using a x86 compatible machine (any recent PC hardware should do) - you can install and use the original Quicktime DLLs and watch most streams - (trailers) that can be downloaded from the net. - </P -><P -> Possibly the most convenient way to get the Quicktime DLLs is to download - them from the mplayer website - <A -HREF="http://www1.mplayerhq.hu/MPlayer/releases/codecs/" -TARGET="_top" -> http://www1.mplayerhq.hu/MPlayer/releases/codecs/ - </A ->. - The package is called "QuickTime6 DLLs". Unpack it and move everything you find - inside to <TT -CLASS="FILENAME" ->/usr/lib/win32</TT -> (actually you can place them - anywhere you want, e.g. someplace in your homedirectory, but then you'll - have to set <TT -CLASS="PARAMETER" -><I ->codec.win32_path</I -></TT -> in your - xine config file accordingly). Restart xine then and you should be - able to watch Quicktime trailers. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN253" -></A ->Real Network files/streams</H3 -><DIV -CLASS="SECT3" -><H4 -CLASS="SECT3" -><A -NAME="REALFILEPLAYBACK" -></A ->Can I watch Real (.rm, .ram) files using xine?</H4 -><P -> The situation with real files and streams is pretty similar to the situation - with Quicktime Streams (see above). The newer real audio and video formats - are only supported by using binary-only codecs which are available from - real networks but are not included in xine. - </P -><P -> One way to get these codecs is to download and install RealPlayer from - RealNetworks, for example in <TT -CLASS="FILENAME" ->/usr/local/RealPlayer8</TT -> or - <TT -CLASS="FILENAME" ->/opt/RealPlayer8</TT ->. If you installed it in one of these - places, xine should automatically find and use the real binary codecs. - If it doesn't work, try to find out the exact path to where the real codecs - are installed on your system (look for a file named <TT -CLASS="FILENAME" ->rv30.so.6.0</TT -> - which should reside in a directory called <TT -CLASS="FILENAME" ->Codecs</TT -> in the - directory where you have installed RealPlayer in) and set - <TT -CLASS="PARAMETER" -><I ->codec.real_codecs_path</I -></TT -> in your xine config file - accordingly. - </P -></DIV -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="REALNETWORKSTREAMS" -></A ->What about (live) network streams (pnm://, rtsp:// style urls)?</H4 -><P -> xine supports both pnm and rtsp streaming. However, digging out the actual - pnm/rtsp url can be tricky as they're often packed into heavy JavaScript and - HTML code on most websites. You can either use a combination of your - browser's "save source" function and wget or use a xine browser plugin - (currently the gxine frontend comes with a simple mozilla plugin, - for example). When you decided to dig out the url by hand don't get fooled - by the many redirectors that are often placed around the actual url. - Use wget to download any http://-style urls and use less to look inside - the downloaded .ra/.ram files where you will find the actual pnm/rtsp - url which can be opened using xine. - </P -></DIV -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="WMV" -></A ->Can I watch Windows Media (.asf/.wmv/.wma) files using xine?</H3 -><P -> While the container format (system layer) ASF (wmv is just an alias) - is fully supported in xine, for newer windows media 9 based streams - you'll need to install windows binary codecs (.DLLs). - </P -><P -> Possibly the most convenient way to get the windows DLLs is to download - them from the mplayer website - <A -HREF="http://www1.mplayerhq.hu/MPlayer/releases/codecs/" -TARGET="_top" -> http://www1.mplayerhq.hu/MPlayer/releases/codecs/ - </A ->. - The package is called "Win32 Codecpack". Unpack it and move everything you find - inside to <TT -CLASS="FILENAME" ->/usr/lib/win32</TT -> (actually you can place them - anywhere you want, e.g. someplace in your homedirectory, but then you'll - have to set <TT -CLASS="PARAMETER" -><I ->codec.win32_path</I -></TT -> in your - xine config file accordingly). Restart xine then and you should be - able to watch windows media streams. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="DVB" -></A ->Can I watch Digital TV (Digital Video Broadcast) using xine?</H3 -><P -> At the time of this writing DVB support is a very new and experimental - feature in xine. The number of supported cards is pretty limited at the moment. - See <TT -CLASS="FILENAME" ->doc/README.dvb</TT -> (in the xine-lib tarball) for details. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="STDIN" -></A ->How do I play streams from STDIN?</H3 -><P -> Use something like: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->cat stream.mpg | gxine stdin:/</B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AVISUBTITLES" -></A ->How can I watch files with external AVI subtitles?</H3 -><P -> In xine 0.9.13 this used to be: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine foo.avi%bar.sub</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> Latest xine-lib modules (1-beta3 or newer) support external subtitles - for any media file, not only AVI. In order to use it you can pass a - special MRL construction like: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine test.mpg#subtitle:file.sub</B -></PRE -></TD -></TR -></TABLE -> - The external subtitles support can also be used by any xine - frontend. Currently, just xine-ui implements this feature with a - subtitle selection dialog. - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="RUNNING" -></A ->Running xine</H2 -><DIV -CLASS="SECT2" -><H3 -CLASS="SECT2" -><A -NAME="SPEEDUP" -></A ->I have a lot of dropped frames - what can I do?</H3 -><P -> Your hardware might be too slow for xine. Make sure you turn on all - speed optimizing options. A few things you should check (in order of - importance): - <P -></P -><UL -><LI -><P -> First of all, run the <B -CLASS="COMMAND" ->xine-check</B -> script included in xine - package (probably already installed in your system). - <B -CLASS="COMMAND" ->xine-check</B -> will report several of the most common problems - listed here. Sample output from xine-check: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine-check</B -> - Please be patient, this script may take a while to run... - [ good ] you're using Linux, doing specific tests - [ good ] looks like you have a /proc filesystem mounted. - [ good ] You seem to have a reasonable kernel version (2.4.18) - [ good ] intel compatible processor, checking MTRR support - [ good ] you have MTRR support and there are some ranges set. - [ good ] found the player at /usr/local/bin/xine - [ good ] /usr/local/bin/xine is in your PATH - [ good ] found /usr/local/bin/xine-config in your PATH - [ good ] plugin directory /usr/local/lib/xine/plugins exists. - [ good ] found input plugins - [ good ] found demux plugins - [ good ] found decoder plugins - [ good ] found video_out plugins - [ good ] found audio_out plugins - [ good ] skin directory /usr/local/share/xine/skins exists. - [ good ] found logo in /usr/local/share/xine/skins - [ good ] I even found some skins. - [ good ] /dev/cdrom points to /dev/hdc - [ good ] /dev/dvd points to /dev/hdc - [ good ] DMA is enabled for your DVD drive - [ good ] found xvinfo: X-Video Extension version 2.2 - [ good ] your Xv extension supports YUV overlays (improves MPEG performance) - [ good ] your Xv extension supports packed YUV overlays - [ good ] Xv ports: YUY2 YV12 I420 UYVY</PRE -></TD -></TR -></TABLE -> - </P -></LI -><LI -><P -> Try to use the Xv driver, it greatly improves performance and quality - because your graphics card does image scaling and colorspace conversion. The - <A -HREF="#VIDEO" ->video section</A -> contains important information - about several Xv drivers. - </P -><P -> If Xv cannot be used for some reason, make sure your display is set up - to 16bpp, not 24 or higher (reduces memory bandwith). Some Xv drivers - may also have better performance with 16bpp. - </P -></LI -><LI -><P -> Make sure the hard drive (or cdrom/dvd drive) which supplies the - video data is in DMA mode (if supported). - </P -><P -> On most linux-based systems, you can use hdparm to check this: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->hdparm /dev/hda</B -> - [...] - using_dma = 1 (on) - [...]</PRE -></TD -></TR -></TABLE -> - </P -><P -> You can enable DMA mode with the following command: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->hdparm -d1 device_of_your_drive_that_supplies_video_data</B -></PRE -></TD -></TR -></TABLE -> - In some cases where this fails it helps to specify the dma mode - to use, for example: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->hdparm -d1 -X 66 device_of_your_drive_that_supplies_video_data</B -></PRE -></TD -></TR -></TABLE -> - In RedHat 8.0 an additional entry in /etc/modules.conf - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="SCREEN" -> options ide-cd dma=1</PRE -></TD -></TR -></TABLE -> - should help (reboot for this change to take effect). - </P -><P -> More information about this may be found here: - <A -HREF="http://oreilly.linux.com/pub/a/linux/2000/06/29/hdparm.html" -TARGET="_top" -> http://oreilly.linux.com/pub/a/linux/2000/06/29/hdparm.html - </A ->. - </P -></LI -><LI -><P -> Use a recent kernel which is optimized for your hardware. Old kernels - may lack support for accelerated instructions like SSE, for example. - </P -></LI -><LI -><P -> Close other applications (use a tool like "top" to find out - what applications are using up CPU power). Programs that update the - system clock like ntp should also be disabled. - </P -></LI -><LI -><P -> Enable MTRR support in your kernel. If you are still using XFree 3.x, - you'll have to tell the kernel yourself where the graphics memory is. - You'll find details about that in the linux dvd howto. - </P -><P -> If you're using XFree 4.x, enabling MTRR support in your kernel should - be enough (use a recent kernel!). - </P -><P -> Try a <B -CLASS="COMMAND" ->cat /proc/mtrr</B -> - if the file exists and you find an entry - corresponding to the amount of graphics memory you have, everything - should be fine. - </P -></LI -><LI -><P -> Have your X-server (usually XFree86) running with higher priority. - Most recent linux distributions (like RedHat 8.0 or Mandrake 9.0) should - do that for you, improving not only xine but desktop responsiveness - in general. - </P -><P -> Use the "top" utility and verify under the "NI" column if - the X process has a negative value, this indicates a higher priority. - See "The X Window User HOWTO - Performance considerations" for - further instructions - <A -HREF="http://www.tldp.org/HOWTO/XWindow-User-HOWTO/performance.html" -TARGET="_top" -> http://www.tldp.org/HOWTO/XWindow-User-HOWTO/performance.html - </A ->. - </P -></LI -><LI -><P -> Use the latest or a known-good gcc version and build an optimized xine-lib for - your architecture. - </P -></LI -><LI -><P -> Besides boosting X-server priority, sometimes it's possible to avoid - discarding frames by making xine itself higher priority. This is not - a recommended pratice since it will require to run xine as root, - but you may give it a try if you want: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->nice --5 xine</B -></PRE -></TD -></TR -></TABLE -> - </P -></LI -><LI -><P -> xine needs high speed memory access which depends on your chip set. - Make sure you enable all speed-improving options. - </P -><P -> Especially the via apollo pro chipset is known to be quite weird, - (most of all on my gigabyte board). If you can't configure the ram - access thoroughly using the bios you might want to try some really - nasty tricks, as explained on (for example): - <A -HREF="http://www.overclockers.com/tips105/index03.asp" -TARGET="_top" -> http://www.overclockers.com/tips105/index03.asp - </A -> - </P -><P -> This website centers around a windows-tool to tweak the chipset, you - can do the same on FreeBSD with <B -CLASS="COMMAND" ->pciconf</B ->. - On some linux distributions there are similar tools. - </P -></LI -><LI -><P -> a nice performance tuning tool can be found here: - <A -HREF="http://powertweak.sourceforge.net" -TARGET="_top" ->http://powertweak.sourceforge.net</A -> - </P -></LI -><LI -><P -> Set up and use raw devices for DVD access. Please note that the - actual performance gain during playback is very small if any, but - since raw devices are bypassing the kernel's buffer cache, Linux - will not try to cache the DVDs you play. This would not be useful, - because xine does its own caching and you usually play DVDs - sequentially, which means you won't reuse anything from the cache. - But the problem would be that Linux throws everything out of the - cache that might be in there. - </P -><P -> Raw devices should be available in linux kernel 2.4.x and there are - patches for older kernels available from: - <A -HREF="ftp://ftp.kernel.org/pub/linux/kernel/people/sct/raw-io/" -TARGET="_top" -> ftp://ftp.kernel.org/pub/linux/kernel/people/sct/raw-io/ - </A -> - </P -><P -> To use raw devices, first connect a free raw device to your dvd - device, use something like: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->raw /dev/raw1 /dev/dvd</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> Then create a link named "rdvd" pointing to that raw device: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->ln -s raw1 /dev/rdvd</B -></PRE -></TD -></TR -></TABLE -> - </P -></LI -><LI -><P -> For slow / high-latency dvd drives it might help to increase - the number of video buffers xine allocates. Try setting - <TT -CLASS="PARAMETER" -><I ->video.num_buffers:500</I -></TT -> - to a higher value (e.g. 1000 or 2500). - </P -></LI -></UL -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="SMOOTHNESS" -></A ->Oki, xine doesn't drop frames now but video output still is not really smooth!</H3 -><P -> Video output can be further improved by tuning your linux kernel: - <P -></P -><UL -><LI -><P -> Set HZ to 1000 in - <TT -CLASS="FILENAME" ->/usr/src/linux/include/asm-i386/param.h</TT -> - </P -></LI -><LI -><P -> Try applying scheduler patches, especially the O(1) and the preemptive - patches have proven useful at the time of this writing (spring 2003). - </P -></LI -></UL -> - Linux 2.5/2.6 will probably have these improvements out of the box. - </P -><P -> Miguel Freitas has written a nice - <A -HREF="http://cambuca.ldhs.cetuc.puc-rio.br/~miguel/multimedia_sim/" -TARGET="_top" -> article about his kernel multimedia experiments - </A ->. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="PORTS" -></A ->I have problems when using xine on FreeBSD, Solaris, ... !</H3 -><P -> Check out the the corresponding README files in the directory <TT -CLASS="FILENAME" ->xine-lib/doc</TT ->. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AAXINE" -></A ->What is aalib? How do I use it in xine?</H3 -><P -> aalib is an ascii art library. xine comes with an aalib video output - plugin so you can watch movies in your xterm, on the console or on your - old vt100 - very cool ;> ... another nice option is to preview movies - on a remote server in your shell over ssh. - </P -><P -> To use it make sure you have aalib installed correctly before you - configure/build xine-lib and xine-ui. In addition to the <B -CLASS="COMMAND" ->xine</B -> binary a - binary named <B -CLASS="COMMAND" ->aaxine</B -> should get built and installed. You can then use - something like: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->aaxine foo.mpg</B -></PRE -></TD -></TR -></TABLE -> - to use aalib video output. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="CONFIGOPTIONS" -></A ->What do all these <TT -CLASS="FILENAME" ->~/.xine/config</TT -> (<TT -CLASS="FILENAME" ->~/.gxine/config</TT ->) entries mean?</H3 -><P -> You can find information about them in - <TT -CLASS="FILENAME" ->xine-lib/doc/README.config_en</TT ->. - Frontends may register additional config entries, you may find out more about - them in their documentation. Also the comments in the config file might - help. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="DXR3" -></A ->Does xine support my dxr3 / hollywood+ card?</H3 -><P -> While xine's focus is clearly on software decoding, the dxr3 is supported. - </P -><P -> You can find more information about using xine with the dxr3 - <A -HREF="http://www.amalthea.de/xine/" -TARGET="_top" ->here</A -> - (also covers how to do tv output using the dxr3). - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AUDIO" -></A ->Audio related questions</H2 -><DIV -CLASS="SECT2" -><H3 -CLASS="SECT2" -><A -NAME="AUDIODRIVERS" -></A ->What audio drivers does xine support? OSS? Alsa? Arts? Esd?</H3 -><P -> Currently xine support audio output via OSS (kernel audio drivers), - ALSA 0.9.x (ALSA 0.5.x is no longer supported), arts (KDE's sound daemon) - and esound (esd, gnome's sound daemon - not recommended because it has - serious issues with a/v sync). - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="COMPRESSOR" -></A ->When I'm watching a movie, the sound effects are much higher in volume than the voices!</H3 -><P -> Congratulations, you seem to have an original movie audio track there. - </P -><P -> Uhm. So you don't like it. Well, there are two things you can do: - <P -></P -><UL -><LI -><P -> You can enable xine's audio compressor. Most frontends have - a settings window and in that you'll find a slider for the - compressor setting. The values are percent values, so a - slider setting of 200 means that xine will double the volume - of silent parts of the movie (loud parts stay the same). - </P -><P -> If your frontend does not have such a compression slider, - you can pass the value with the MRL: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine dvd:/#compression:150</B -></PRE -></TD -></TR -></TABLE -> - </P -></LI -><LI -><P -> If you have a dolby digital (AC3) soundtrack, you can try - to enable liba52's dynamic range compression setting - <TT -CLASS="PARAMETER" -><I ->codec.a52_dynrng:1</I -></TT -> - in your xine config file (or use some gui config dialog). - </P -></LI -></UL -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="NOAUDIO" -></A ->When I play this stream, xine shows video but there's no audio!</H3 -><P -> If this happens with any video, first try a different audio driver - (<B -CLASS="COMMAND" ->gxine -A oss</B ->, <B -CLASS="COMMAND" ->gxine -A arts</B ->, - <B -CLASS="COMMAND" ->xine -A alsa</B -> ...). - </P -><P -> If this problem only occurs with one specific stream, maybe switching to - a different audio channel (using the gui) helps. Some DVD streams have - audio on strange channels. - </P -><P -> If all this doesn't help, maybe you're missing an audio codec or you found - a bug. If you decide to post your problem on the xine-user mailing list, - make sure to include all console output xine produced and also clearly - state what type of stream you tried to play back or, even better, make - a test stream available somewhere for developers to download and try. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="SURROUNDSOUND" -></A ->Can xine produce 4-/5-channel surround audio output?</H3 -><P -> Yep, it can do that using OSS or ALSA drivers, provided that the driver - supports it. On startup xine tells you what modes are supported by your - audio driver, e.g: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> audio_alsa_out : supported modes are mono stereo (4-channel not enabled in xine config) (5-channel not enabled in xine config) (5.1-channel not enabled in xine config) (a/52 and DTS pass-through not enabled in xine config)</PRE -></TD -></TR -></TABLE -> - </P -><P -> On this machine 4-channel surround would be possible. However, since xine - cannot detect if there are actually speakers connected to the additional - channels, you'll have to activate that feature manually. - </P -><P -> You can do this either in the config dialog while xine is running (press - the config button on the xine panel and go to the AUDIO tab) or have it - the complicated way by editing the config file yourself which is located - in your home directory in <TT -CLASS="FILENAME" ->.gxine</TT -> or <TT -CLASS="FILENAME" ->.xine</TT ->: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> audio.four_channel:1 - audio.five_channel:1 - audio.five_lfe_channel:0</PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="SPDIF" -></A ->What about ac3 output via spdif to an external ac3 decoder?</H3 -><P -> xine can do that too. Pretty much the same story as for 4-/5-channel - surround (see above). You can either use the config dialog or edit - the config file (<TT -CLASS="FILENAME" ->~/.xine/config</TT -> or <TT -CLASS="FILENAME" ->~/.gxine/config</TT ->) - yourself: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> audio.a52_pass_through:1</PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="SBLIVESPDIF" -></A ->Getting SPDIF output from a SBLive 5.1 using OSS drivers</H3 -><P -> The following explains how to get the above configuration - going with xine. Some parts of it may applicable to other - configurations (cards that use the EMU10k1 chip) as well. - </P -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="AEN439" -></A ->Requirements</H4 -><P -></P -><OL -TYPE="1" -><LI -><P ->xine-lib >= 1.x.x</P -></LI -><LI -><P ->OSS driver</P -></LI -><LI -><P ->an external decoder</P -></LI -><LI -><P ->a cable to connect the SBLive to the external decoder</P -></LI -></OL -><P -> The configuration described was tested using a Soundblaster live 5.1 (rev 7) - with a Yamaha DSP-AX620 external decoder. - </P -></DIV -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="AEN451" -></A ->Retrieving the driver</H4 -><P -> The OSS driver is maintained by creative and can be downloaded at - <A -HREF="http://opensource.creative.com/" -TARGET="_top" ->http://opensource.creative.com/</A ->. - The driver package contains documentation on how to install it. - Besides that I'd like to add the following notes. - </P -><P -> In order to compile and install these drivers, you need a valid kernel - configuration file. For RedHat Linux's pre-compiled kernels these - configuration files can be found in - <TT -CLASS="FILENAME" ->/usr/src/linux/configs</TT ->. - After you've located the correct config file for your kernel, - you need to copy it to <TT -CLASS="FILENAME" ->/usr/src/linux/.config</TT -> - For example, when you run the 2.4.18-i686 kernel do : - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->cp /usr/src/linux/configs/kernel-2.4.18-i686.config /usr/src/linux/.config</B -></PRE -></TD -></TR -></TABLE -> - Make sure that the emu10k1 module that is currently installed is - not loaded. To unload the modules: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->/sbin/modprobe -rv emu10k1.o ac97_codec.o</B -></PRE -></TD -></TR -></TABLE -> - If this mentions that the device is busy, some program is - using the driver. Some example could be a mixer application - or sound daemon like artsd. You'll need to close down the - applications before continuing. - At success it should print something like: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> # delete emu10k1 - # delete ac97_codec - # delete soundcore</PRE -></TD -></TR -></TABLE -> - Run make in the directory where you unpacked the driver and follow the - instructions printed at the end of each step. - The last step should be: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->make install-tools</B -></PRE -></TD -></TR -></TABLE -> - As the README of the driver package mentions the SPDIF AC3 - output doesn't work by default. In the directory - <TT -CLASS="FILENAME" ->utils/scripts</TT -> an <TT -CLASS="FILENAME" ->emu10k1.conf</TT -> - file can be found which need to be placed in the default - installation directory (<TT -CLASS="FILENAME" ->/usr/local/etc</TT ->). - After this the <TT -CLASS="FILENAME" ->emu10k1.conf</TT -> needs to be modified. - The following settings worked fine for me (I don't use the analog - outputs of the card): - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> CARD_IS_5_1=yes - USE_DIGITAL_OUTPUT=yes - ENABLE_TONE_CONTROL=yes - AC3PASSTHROUGH=yes - ENABLE_LIVEDRIVE_IR=no - INVERT_REAR=no - MULTICHANNEL=yes - ROUTE_ALL_TO_SUB=no - ANALOG_FRONT_BOOST=no - SURROUND=no - PROLOGIC=no - ENABLE_CD_Spdif=yes - ENABLE_OPTICAL_SPDIF=no - ENABLE_LINE2_MIC2=no - ENABLE_RCA_SPDIF=no - ENABLE_RCA_AUX=no</PRE -></TD -></TR -></TABLE -> - After modifying the <TT -CLASS="FILENAME" ->emu10k1.conf</TT ->, - you need to modify your <TT -CLASS="FILENAME" ->/etc/modules.conf</TT -> and - make sure the following lines are in there. - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> alias sound-slot-0 emu10k1 - post-install emu10k1 /usr/local/etc/emu-script</PRE -></TD -></TR -></TABLE -> - After saving the changes to <TT -CLASS="FILENAME" ->modules.conf</TT ->, run - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->/sbin/depmod -a</B -></PRE -></TD -></TR -></TABLE -> - Now, you're ready to load the new modules and set the correct - options for it. To load the modules run: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->/sbin/modprobe emu10k1</B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="AEN478" -></A ->Setting up xine for SPDIF (AC3_passthrough) output</H4 -><P -> You can either use the config dialog of your frontend or edit - the config file (<TT -CLASS="FILENAME" ->~/.xine/config</TT ->) yourself: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> audio.a52_pass_through:1</PRE -></TD -></TR -></TABLE -> - In case the setting is not in the file you can add it. - </P -></DIV -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="AEN483" -></A ->The cable used for the SBLive can easily be self-made - or buy a stereo 3.5mm jack to dual RCA cable.</H4 -><P -> What you need to make the cable yourself: - <P -></P -><UL -><LI -><P ->stereo 3.5mm jack plug</P -></LI -><LI -><P ->RCA plug</P -></LI -><LI -><P ->shielded cable (video coax 75 Ohm will do)</P -></LI -></UL -> - Connect them as follows : - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> center pin jackplug ------|----- center pin RCA plug - GND __|__ GND</PRE -></TD -></TR -></TABLE -> - </P -><P -> In order to test it use a DVD with AC3 or DTS track - start xine and select the right audio track - from user interface or start xine as: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine dvd:/1 -a 0</B -></PRE -></TD -></TR -></TABLE -> - The external decoder should display something like - "Dolby Digital" in case the selected audio track contains - AC3 data or "DTS" in case the selected audio track - contains DTS data. Of course stereo audio also goes - through the SPDIF output, so the analog outputs of the - SBLive 5.1 are not needed anymore. - </P -></DIV -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="VOLUMECONTROL" -></A ->Changing the volume with the GUI control has no effect! What's up!?</H3 -><P -> Some xine drivers do not support volume changing although the GUI - will show the volume bar. Usually this is not xine's fault: aRts C - API, for example, doesn't offer any volume property to applications. - Similarly, with ac3 pass through it is not possible to set the volume. - </P -><P -> Note that recently we added support to "simulate" volume in aRts by - changing sample values on-the-fly before delivering them to the driver. - Not as good as having access to sound card's mixer but at least users - will not complain about lacking of volume bar anymore! :) - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="STUTTERING" -></A ->Audio is stuttering and i see a lot of "metronom: fixing sound card drift by -2115 pts" on the console output</H3 -><P -> Might be a soundcard problem, if it only comes in longer intervals. - Your soundcard does not keep it's sampling frequency accurately - enough, which results in audio and video - getting out of sync and xine has to compensate. If you see the message - only from time to time, you might remedy it by using the resampling sync - method. You can do this by setting the configuration entry - <TT -CLASS="PARAMETER" -><I ->audio.av_sync_method</I -></TT -> to <TT -CLASS="PARAMETER" -><I ->resample</I -></TT ->. - </P -><P -> If you receive the metronom message more often, - maybe switching to different drivers (alsa to oss or vise-versa) - can help here. It has also been reported that setting the configuration - entry <TT -CLASS="PARAMETER" -><I ->audio.force_rate</I -></TT -> to the native sampling - rate of your soundcard (try 44100 and 48000) helps sometimes. - </P -><P -> Another, whole different possibility is that you have some background - process running which is messing with the clock (like some ntp client - - chronny, ntpd, ...). - </P -><P -> Occasional messages of "fixing sound card drift" may happen on start and - when playing a long stream (like a movie). This is normal behaviour, - nothing to worry about. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="SOUNDLOSS" -></A ->xine seems to lose sound arbitrarily during playback, especially with DVDs</H3 -><P -> You are using the OSS audio output plugin, right? In order to keep video and audio - in sync, xine regularly queries the audio driver for the amount of delay induced by - the current length of the driver's audio buffer. Unfortunately some OSS drivers seem - to be broken because the can return strange values here. This confuses the xine audio - subsystem and makes it drop audio. - </P -><P -> You should try the various settings of the - configuration entry <TT -CLASS="PARAMETER" -><I ->audio.oss_sync_method</I -></TT ->. The options - <TT -CLASS="PARAMETER" -><I ->getodelay</I -></TT -> and <TT -CLASS="PARAMETER" -><I ->getoptr</I -></TT -> ask the driver and - might therefore show the problem. But chances are that only one is broken and the other - works, so you should try them both first, since they are the most accurate. - The option <TT -CLASS="PARAMETER" -><I ->probebuffer</I -></TT -> does not ask the driver directly but - tries to determine the buffer length from outside. This should work with any driver - and is the way to go, of the driver dependent methods fail. - <TT -CLASS="PARAMETER" -><I ->softsync</I -></TT -> is the least accurate and should be used only in - emergency situations. - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="VIDEO" -></A ->Video related questions</H2 -><DIV -CLASS="SECT2" -><H3 -CLASS="SECT2" -><A -NAME="NOVIDEO" -></A ->I can hear the audio - but I don't see a picture!</H3 -><P -> Probably your hardware is simply too slow - see above for some - hints on how to speed things up. - </P -><P -> Another possibility is that you using a buggy Xv driver, see the next - question. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="XVEXTENSION" -></A ->How can I make xine use the Xv extension and what drivers do I need?</H3 -><P -> xine will normally use Xv by default if it is available. In some cases - you might need to choose Xv playback manually (when the <TT -CLASS="FILENAME" ->~/.xine/config</TT -> - file for some reason says that you want to use XShm): - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine -V Xv foo.mpg</B -></PRE -></TD -></TR -></TABLE -> - </P -><P -> If this doesn't work for you, it may be possible that Xv is not present - on your system. - </P -><P -> First you need to install/use XFree 4.x. Once you got that you have to - make sure the XFree drivers you're using are supporting Xv on your - hardware. Here are some hints for individual gfx chips: - <P -></P -><UL -><LI -><P -> - 3Dfx: if all you get is a solid black window, upgrade at least to XFree 4.1.0 - </P -></LI -><LI -><P -> - ATI: if you only get "half a picture", try lowering your resolution - or bit depth, disable DRI (looks like you ran out of video RAM) - </P -></LI -><LI -><P -> - Trident card: If you see vertical bands jumbled, upgrade to the latest - xfree/experimental trident drivers (for the CyberBlade XP - a driver exists here: - <A -HREF="http://www.xfree86.org/~alanh/" -TARGET="_top" ->http://www.xfree86.org/~alanh/ </A ->) - </P -></LI -><LI -><P -> - nVidia: With newer GeForce cards, Xv should work with XFree 4.2.0 or - newer, for older RivaTNT cards use the binary drivers from nvidia - (of course the binary drivers work as well for GeForce cards) - </P -></LI -><LI -><P -> - Mach64/Rage3D (not Rage128/Radeon) cards/chips get no XVideo with - standard drivers, try - <A -HREF="http://gatos.sourceforge.net/" -TARGET="_top" ->GATOS drivers - </A -> instead - </P -></LI -><LI -><P -> - intel: i815 has Xv support in XFree 4.x, others unknown - </P -></LI -><LI -><P -> - Permedia 2/3 has Xv support in XFree 4.x - </P -></LI -><LI -><P -> - Savage: at least some older drivers tend to lock up the whole machine, - try the drivers available from - <A -HREF="http://www.probo.com/timr/savage40.html" -TARGET="_top" -> http://www.probo.com/timr/savage40.html - </A ->. - </P -></LI -><LI -><P -> - SIS: certain controllers (more info needed!) have Xv support in XFree 4.x - </P -></LI -><LI -><P -> - Chips and Tech 6555x, 68554, 69000, 69030 have Xv support in XFree 4.x - </P -></LI -><LI -><P -> - NeoMagic: certain controllers (more info needed!) have Xv support in Xfree 4.x - </P -></LI -><LI -><P -> - SiliconMotion: certain controllers (more info needed!) have Xv support in Xfree 4.x - </P -></LI -><LI -><P -> - Matrox: G200 or newer (but not Parhelia) have Xv support in XFree 4.x. - For Parhelia, use the binary only drivers available from matrox' website. - </P -></LI -></UL -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="COLORKEY" -></A ->Some parts of my X Desktop get transparent when xine plays the video!</H3 -><P -> Looks like some colors on your GUI match the colorkey Xv uses. You can - change the colorkey value to avoid this. There should be a line like: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> video.XV_COLORKEY:2110</PRE -></TD -></TR -></TABLE -> - in your <TT -CLASS="FILENAME" ->~/.xine/config</TT -> file where you can change the color that's used - by xine for the video overlay. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="ASPECTRATIO" -></A ->The aspect ratio of the video is wrong!</H3 -><P -> Try pressing "a" to change the aspect ratio. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="DISCARDEDSKIPPED" -></A ->What is the difference between discarded and skipped frames?</H3 -><P -> Sometimes xine will output a message like that: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> 200 frames delivered, XX frames skipped, YY frames discarded</PRE -></TD -></TR -></TABLE -> - </P -><P -> The difference between these counters is a little subtle for the non - developer. There are two threads running in order to display video: - the decoder thread will deliver frames to the video output thread. - The later is responsible for scheduling the frames to be displayed at - the right time. - </P -><P -> If your system can't keep up with decoding requirements, decoder will - deliver overdue frames. Imagine if it finished decoding the frame - tagged for displaying at 11:30 but xine clock marks 11:31. When this - situation is detected, xine will try to skip decoding a few frames - to recover. Not every decoder may support this feature. - </P -><P -> When the frame is decoded to be shown somewhere in future but the - output thread doesn't get scheduled in time by the operating system - to complete the operation, the frame is discarded. One cause might - be the disk access operation, which may halt the system for a few - miliseconds without DMA. See performance section tips above. - </P -><P -> Note that if a decoder can't skip frames for some reason, you would - never see frames skipped (they would be all discarded). - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="CONTRASTBRIGHTNESSSATURATION" -></A ->My xine is runing in black and white! / I only get a gray video output!</H3 -><P -> This frequently happens with new Xv drivers or when switching to a - different video card. Background is that different Xv drivers often - use different ranges for the contrast/brightness/saturation settings. - </P -><P -> To fix this, try opening the xine settings window and try adjusting - the sliders for contrast, brightness and saturation. - </P -><P -> Please note that some frontends save these settings in their config file - so when you have found a working combination, make sure you exit - xine cleanly so the values are saved. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="VIDEODRIVER" -></A ->Which is the best video driver to use?</H3 -><P -> xine support several video drivers for outputing the image. These will - differ on how the frames are copied to the video card memory, whether - colorspace conversion and scaling is done in software or hardware, among - other things. They may also differ on ease of use and stability. - </P -><P -> Most of the time, Xv should give the users a good trade-off between - quality, compatibility and ease of use. This is why xine tries to use - Xv by default. - </P -><P -> However some users may want to explore better the available hardware - capabilities (eg. syncing frame drawing with monitor refresh). - Also some Xv drivers contain slow copies and accessing the video card - directly may yield performance gains. - </P -><P -> Drivers that access hardware directly includes VIDIX (warning: requires - root priviledges or kernel helper) and SyncFB (requires kernel helper - Matrox only). - User may try one of those, but should be warned that with root access - they can cause the system to crash hard. The support is also limited to - a couple of graphics cards only. - </P -><P -> Graphic workstations like SGI have usually a good support for OpenGL. - In that case, using OpenGL may be a better choice than XShm. However for - most desktop systems the performance of OpenGL will be quite bad. - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="ERRORS" -></A ->Error Messages: What they mean and what you can do</H2 -><DIV -CLASS="SECT2" -><H3 -CLASS="SECT2" -><A -NAME="AUDIODRIVERERR" -></A ->Starting xine fails with complains about audio drivers/devices!</H3 -><P -> You can select the audio driver using the -A option. So try: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine -A null</B -></PRE -></TD -></TR -></TABLE -> - If you have ALSA drivers installed, try: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine -A alsa</B -></PRE -></TD -></TR -></TABLE -> - If you run ESD (not recommended), try: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine -A esd</B -></PRE -></TD -></TR -></TABLE -> - If you run artsd, try: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->xine -A arts</B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="NOVIDEOPORTFOUND" -></A ->"no video port found"</H3 -><P -> You got the Xv extension, but your video card driver doesn't support it. - First try to find a driver that does support Xv on your hardware (check - your graphics card vendor). If your driver has Xv support but you can't - get it working, try at a lower resolution (1024x768 is enough even for - anamorphic DVDs). - </P -><P -> If all that fails, you can still use plain X11/XShm: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->gxine -V XShm foo.vob</B -></PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="UNABLETOOPENDVDDRIVE" -></A ->"Unable to open dvd drive (/dev/dvd)"</H3 -><P -> You probably don't have /dev/dvd (check that). If so, simply create a - link /dev/dvd that points to your DVD device. Something like... - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->ln -s hdc /dev/dvd</B -></PRE -></TD -></TR -></TABLE -> - ...should do the job. Also make sure you have read and write access on - the device the symlink points to. - See the <A -HREF="#DVDPLAYBACK" ->dvd playback section</A -> - for more information. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="STATUS0X51" -></A ->My drive doesn't work and the kernel says "status=0x51 { DriveReady SeekComplete Error }"</H3 -><P -> This error can be fixed by recompiling your kernel with the option - "Use multi-mode by default" enabled in the IDE settings. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="DEMUXERROR0000" -></A ->"demux error! 00 00 00 (should be 0x000001)"</H3 -><P -> Probably xine can't access your input source. Most commonly this happens - when you're trying to play locked/encrypted DVDs. Remember that xine - can't play such DVDs out-of-the box for legal reasons (see above). - </P -><P -> If it is legal where you live, you can try to install libdvdcss. Once - you have done that and re-start xine, it should automatically detect - and use it to play back encrypted DVDs. - </P -><P -> Another reason could be that your (RPC-2) DVD drive isn't set up - for the right region (see above). - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="OSSFAILED" -></A ->"audio driver 'oss' failed, using null driver instead"</H3 -><P -> First of all, make sure that your OSS Audio drivers are working (i.e. - you can play music with other software). Maybe you're using alsa? - If so, try <B -CLASS="COMMAND" ->gxine -A alsa</B -> to see if this helps. - </P -><P -> The most common reason for oss not working is that some other program is accesing - your audio device. If you're using linux, the command <B -CLASS="COMMAND" ->fuser /dev/dsp</B -> - should give you the PID of the process. - </P -><P -> If you are using GNOME, chances are that this is caused by ESD. Now you - have two possibilities. Either deactivate ESD (temporarily) by right - clicking on the sound monitor applet and selecting "Place Esound in - standby" or just kill it. Then xine will use OSS audio output. The other - method is to make xine use ESD for audio output with: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->gxine -A esd</B -></PRE -></TD -></TR -></TABLE -> - This may result in worse playback - exact syncronization is not possible - with esd, so using oss should be preferred. - </P -><P -> If you are using KDE, there is the possibility that the aRts sound - daemon is currently running and thus blocking your sound device. You - can check that by starting the aRts control (in your KDE menu it should - be under Multimedia). If it is running, you can either use the aRts - audio output plugin: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> <B -CLASS="COMMAND" ->gxine -A arts</B -></PRE -></TD -></TR -></TABLE -> - Or you suspend the aRts daemon by checking the appropriate option in - your aRts control. (recommended) - </P -><P -> Newer versions of arts have an auto-suspend mode - this can lead to - some nondeterministic behaviour of xine if it is set up to use - the audio device directly. Using arts is recommended in that case, - however you will loose the ability to do four/five channel audio output. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="THROWINGAWAYIMAGE" -></A ->"video_out: throwing away image with pts xxx because it's too old"</H3 -><P -> This is a performance related problem. - If you have a fast computer and this message shows from time to - time playing dvd/cdrom, it's very likely that your drive is not - DMA enabled. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="NOVIDEOPLUGINAVAILABLE" -></A ->"No video plugin available to decode 'xxxxxx'."</H3 -><P -> You have tried to play a stream using a unknown or unhandled codec. - Possibly the file uses some obscure proprietary format and no - information is available on how to decode it. - </P -><P -> If you're on an x86 platform (e.g. PC hardware) you might want to - try installing binary-only windows medial, real networks and - quicktime codecs (see above). - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="DECODERFAILEDTOSTART" -></A ->"w32codec: decoder failed to start. Is 'xxxxxx' installed?"</H3 -><P -> You probably don't have the win32 dll needed to decode this file. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="XINECRASHED" -></A ->xine just crashed on me - i didn't get any error message</H3 -><P -> OK, yes, that shouldn't happen and you're upset. We can understand that. - But, to help you and of course to fix this, we need some information. - So, let's go through the checklist and maybe prepare a nice bug report - for the xine-user mailing list: - <P -></P -><UL -><LI -><P -> Did xine really crash (segfault) or did it hang (deadlock)? - </P -></LI -><LI -><P -> Can you reproduce the bug? (e.g. do you remember what you - did and when you do it again it crashes again?) - </P -></LI -><LI -><P -> Is that a specific media file or format which crashes xine? (Have you - tried other files types?) - </P -></LI -><LI -><P -> Check the console output (and include it in a bug report), maybe earlier - there is some output that points to the problem. - </P -></LI -><LI -><P -> Your X server just froze on you? unfortunately that's a known problem - with some chipsets and drivers (most commonly Savage chipsets) when - using Xv. You might want to try running <B -CLASS="COMMAND" ->gxine -V XShm</B -> - to see if the problem is related to the Xv driver. This will unfortunately - be much slower, as lots of things are now done in software instead of - hardware scaling/colour space conversion. - </P -><P -> Maybe at the time you read this, there's an XFree upgrade which fixes - this for the Savage driver. If that works for you, please notify the xine crew at - <TT -CLASS="EMAIL" -><<A -HREF="mailto:xine-user@lists.sourceforge.net" ->xine-user@lists.sourceforge.net</A ->></TT ->, so they can update this FAQ! - </P -></LI -><LI -><P -> Even though we try to make each release as bug free as possible, xine is - still under heavy development (nice excuse, isn't it? *grin*). - </P -><P -> If you write to the xine user mailing list - <TT -CLASS="EMAIL" -><<A -HREF="mailto:xine-user@lists.sourceforge.net" ->xine-user@lists.sourceforge.net</A ->></TT -> - make sure you include a the above information (when applicable) - and also some information about your machine (operating system, cpu type and - speed, gfx card, sound card, ...) and please use a meaningfull subject - line ("xine bug" is bad, "xine fails to play this quicktime trailer in fullscreen mode" - ist much better). - </P -><P -> Thanks for taking the time to help improve xine. - </P -></LI -></UL -> - </P -></DIV -></DIV -></DIV -></DIV -></BODY -></HTML ->
\ No newline at end of file diff --git a/doc/faq/faq.txt b/doc/faq/faq.txt deleted file mode 100644 index 6ac2d25d2..000000000 --- a/doc/faq/faq.txt +++ /dev/null @@ -1,1364 +0,0 @@ -The xine engine FAQ - -Copyright © 2001-2003 the xine project team - -------------------------------------------------------------------------------- - -Table of Contents - - - General questions about xine and this document - - What is the xine engine? - What's the aim and scope of this text? - My question is not yet covered here - where can I ask for help? - How do I pronounce "xine"? - What are those xine-lib, xine-ui, gxine, ... modules in cvs for? - Where and how do I get the latest development version? - Where can I find pre-compiled binaries, e.g. RPMs? - - Building and installing xine from source - - What do I need to compile everything properly? - How do I compile xine? - Making your own RPM packages (xine-lib, xine-ui) - Can I provide additional CFLAGS for compilation? - Are there binaries for my AMD K7 (AthlonTM) available? Can I build - them? - Build problems: xine engine (xine-lib) - Build problems in frontends (gxine/xine-ui/...) - Can I install xine in my home directory (without being root)? - - Playback of various stream types - - DVD Playback with xine - Can I watch Video CDs (VCDs)? SVCDS ? CD-i? - Can I watch Quicktime (.mov, .mp4) files using xine? - Real Network files/streams - Can I watch Windows Media (.asf/.wmv/.wma) files using xine? - Can I watch Digital TV (Digital Video Broadcast) using xine? - How do I play streams from STDIN? - How can I watch files with external AVI subtitles? - - Running xine - - I have a lot of dropped frames - what can I do? - Oki, xine doesn't drop frames now but video output still is not really - smooth! - I have problems when using xine on FreeBSD, Solaris, ... ! - What is aalib? How do I use it in xine? - What do all these ~/.xine/config (~/.gxine/config) entries mean? - Does xine support my dxr3 / hollywood+ card? - - Audio related questions - - What audio drivers does xine support? OSS? Alsa? Arts? Esd? - When I'm watching a movie, the sound effects are much higher in volume - than the voices! - When I play this stream, xine shows video but there's no audio! - Can xine produce 4-/5-channel surround audio output? - What about ac3 output via spdif to an external ac3 decoder? - Getting SPDIF output from a SBLive 5.1 using OSS drivers - Changing the volume with the GUI control has no effect! What's up!? - Audio is stuttering and i see a lot of "metronom: fixing sound card - drift by -2115 pts" on the console output - xine seems to lose sound arbitrarily during playback, especially with - DVDs - - Video related questions - - I can hear the audio - but I don't see a picture! - How can I make xine use the Xv extension and what drivers do I need? - Some parts of my X Desktop get transparent when xine plays the video! - The aspect ratio of the video is wrong! - What is the difference between discarded and skipped frames? - My xine is runing in black and white! / I only get a gray video output! - Which is the best video driver to use? - - Error Messages: What they mean and what you can do - - Starting xine fails with complains about audio drivers/devices! - "no video port found" - "Unable to open dvd drive (/dev/dvd)" - My drive doesn't work and the kernel says "status=0x51 { DriveReady - SeekComplete Error }" - "demux error! 00 00 00 (should be 0x000001)" - "audio driver 'oss' failed, using null driver instead" - "video_out: throwing away image with pts xxx because it's too old" - "No video plugin available to decode 'xxxxxx'." - "w32codec: decoder failed to start. Is 'xxxxxx' installed?" - xine just crashed on me - i didn't get any error message - -General questions about xine and this document - -What is the xine engine? - -The xine engine is a free media player engine. It comes in the form of a shared -libarary and is typically used by media player frontends and other multimedia -applications for playback of multimedia streams such as movies, radio/tv -network streams, DVDs, VCDs. - -Since there are several frontends for the xine library available, this document -has a problem when it comes to examples. The two most common frontends xine-ui -and gxine are mixed in command line examples throughout this FAQ. When you use -a different frontend, some of these will not work for you. The filename of the -config file also varies amongst frontends. If you get confused, I recommend you -try with one of xine-ui or gxine. - -------------------------------------------------------------------------------- - -What's the aim and scope of this text? - -The primary goal of this FAQ is to cover all recurring questions related to the -xine engine. Frontend specific questions are usually not covered here. - -------------------------------------------------------------------------------- - -My question is not yet covered here - where can I ask for help? - -First of all be sure that your question is really not covered here and that you -haven't just been a bit too lazy to read through all of this text. ;-). Also -check out the documentation specific to the frontend (e.g. xine-ui or gxine or -totem). - -That said - you are welcome to mail to our user mailing list: < -xine-user@lists.sourceforge.net> Please provide some info about your setup so -people have a chance to help you, e.g. include information about your audio/ -video hardware and drivers you use, operating system, cpu type and some console -output/any error messages. Also include command line parameters you have -specified and information about the type of stream you're trying to play back. -Also very important is the version of xine you're using and information about -any additional plugins you may have installed on your system. - -------------------------------------------------------------------------------- - -How do I pronounce "xine"? - -As long as people know what you are talking about, you are free to pronounce it -the way you like, but the official pronounciation is [ksi:n], like the name -"Maxine" with the "Ma" removed. - -------------------------------------------------------------------------------- - -What are those xine-lib, xine-ui, gxine, ... modules in cvs for? - -Some time ago xine just became too complex to be just one big program. -Therefore it was split into two major parts. - -xine-lib is simply speaking the engine of xine. It contains all basic plugins -and is necessary to run anything that relies on xine. (This is the part that is -covered in this FAQ.) - -Then there are frontends - applications that use xine. The most common frontend -is that of a media player. There are currently two frontends being developed in -the xine project, xine-ui (skinned dvd-player style frontend directly based on -xlib) and gxine, a desktop media-player style frontend using the standard gtk -widget set and comes with a mozilla browser plugin. External projects like -kaffeine, sinek and totem develop additional frontends. In the future you will -likely see more and different types of applications being developed which will -use the xine engine for video processing and other multimedia purposes. - -If you simply want a media/dvd player, you'll need to install xine-lib first -and then choose and install a player frontend like xine-ui or gxine. - -Other modules in CVS are: xine-plugin a mozilla browser plugin for streaming -media playback using xine, xine-www the xine project website sources. - -------------------------------------------------------------------------------- - -Where and how do I get the latest development version? - -Be advised that end-users should stick to the official xine releases. CVS is -only intended for developers and for others who know why they use it. - -To check out xine-modules from CVS, first do this: - cvs -d :pserver:anonymous@cvs.xine.sourceforge.net:/cvsroot/xine login -The password is empty, just press Enter. - -Then, to check out individual modules (e.g. xine-lib, gxine or xine-ui): - cvs -d :pserver:anonymous@cvs.xine.sourceforge.net:/cvsroot/xine co <modulename> - -------------------------------------------------------------------------------- - -Where can I find pre-compiled binaries, e.g. RPMs? - -The xine project does not provide pre-compiled binaries for legal reasons (some -parts of xine may be covered by patents in some countries). Some OS projects/ -vendors (e.g. debian, freebsd, ...) offer binaries for their distributions - -please contact them for further info. You can also find links to third parties -providing xine RPMs on the xine homepage at http://xinehq.de/index.php/releases -. - -See the next section of this FAQ for instructions on how to build xine from -source. - -------------------------------------------------------------------------------- - -Building and installing xine from source - -What do I need to compile everything properly? - -First of all an official and stable release of gcc. Also be aware that patched -gcc versions may break parts of xine and are therefore not supported by the -xine project. - -Furthermore you'll have to use GNU make to compile xine. On most GNU/Linux -systems "make" is GNU make - on other platforms use "gmake" instead. Also, zlib -is required (including the appropriate header files, which are often found in a -package called zlib-devel or similar.) - -If you want to compile xine from CVS, you'll need to have the autobuild tools -installed (automake, autoconf and libtool - in recent versions). - -Frontends might need additional libraries, e.g. for gxine you'll need to have -GTK installed. Make sure you have not only the shared libraries themselves but -also the header files (often packaged seperately as so-called -dev packages) on -your system. - -Some plugins that come with the xine engine need additional libraries -(otherwise they will not be built). For example, libogg and libvorbis (plus -their include files) are needed for ogg/vorbis support. Most notably, if you -want to see any video on your X11 desktop (and that's what you're here for, -isn't it?), you need the XFree developer packages as well. - -Don't worry about this too much right now, xine's configure (see below) will -check for all the stuff needed and will tell you what's missing (which means -that you should check the output it produces carefully ;) ). - -------------------------------------------------------------------------------- - -How do I compile xine? - -Simple build instructions for beginners - -Download the latest xine-lib and gxine/xine-ui tarballs, then follow these -instruction. To unpack a tarball, use: - tar xfvz tarballname.tar.gz - -The following instructions will install xine in /usr/local where it will be -visible for all users. You need root privileges to do this on most systems. - -After unpacking xine-lib, issue: - ./configure - make install - -Make sure your /etc/ld.so.conf contains /usr/local/lib and continue with: - ldconfig - -Now unpack your frontend (gxine or xine-ui or ...), then: - ./configure - make install - -------------------------------------------------------------------------------- - -Complete build instructions - -The build process is the same for all of the xine modules. - -You have to start with xine-lib. If built and installed successfully, you can -continue with the frontend(s). - -If you have installed xine-lib to a non-standard prefix, make sure that you -have $prefix/bin in your PATH and that your linker finds libs in $prefix/lib - -otherwise trying to build modules that rely on xine-lib will fail with -configure complaining about not finding certain parts of libxine. Using bash -you can do something like: - export PATH="$prefix/bin:$PATH" - export LD_LIBRARY_PATH="$prefix/lib:$LD_LIBRARY_PATH" -to make sure libxine can be found by the frontend(s). - -Last but not least. Here the build instructions. As stated earlier, those are -the same for every xine module. - ./autogen.sh [-> *only* if you checked your sources out of CVS] - ./configure - make - make install - -------------------------------------------------------------------------------- - -Making your own RPM packages (xine-lib, xine-ui) - -Basically you will only have to issue one command, if you have just downloaded -a source tarball from our web site: - rpm -ta <THE_NAME_OF_YOUR_SOURCE_TAR_BALL> - -This will start the binary and source RPM building. After compiling is -finished, a binary rpm is placed in your rpm binary directory which is -something like /usr/src/RPM/RPMS/<YOUR_ARCHITECTURE> and a source RPM is -written to your rpm source dir (e.g. /usr/src/RPM/SRPMS). - -In case that you have a fresh CVS checkout, you will need to do the following -first in order to get a tarball release out of it which you can later use with -the rpm -ta command above: - ./autogen.sh && make clean && make dist - -In any case, please keep in mind that you have to build and install xine-lib -first before you can proceed with xine-ui. - -------------------------------------------------------------------------------- - -Can I provide additional CFLAGS for compilation? - -Yes, you can do so by setting the CFLAGS variable and then running configure -again. You can even pass them to configure directly. Example: - ./configure CFLAGS="-march=i686" - -Other user variables configure respects are: - - * CC to specify the compiler executable - - * CPP to specify the C preprocessor executable - - * LD to specify the linker executable - - * CPPFLAGS to pass additional include paths or other preprocessor options - - * LDFLAGS to pass additional library paths or other linker options - -An example combining some of these would look like: - ./configure CC="/opt/intel/bin/icc" LD="/opt/intel/bin/xild" CPPFLAGS="-I/usr/local/include/dvdnav" LDFLAGS="-L/home/guenter/xine_libs" - -------------------------------------------------------------------------------- - -Are there binaries for my AMD K7 (AthlonTM) available? Can I build them? - -If you have a recent gcc you can try to compile "more" k7 support in (esp. -better instruction scheduling). If the configure script should fail to detect -your processor/gcc correctly, try passing the canonical system name for your -machine to configure with the --host option, e.g. - ./configure --host=k7-pc-linux-gnu - -------------------------------------------------------------------------------- - -Build problems: xine engine (xine-lib) - -The package doesn't compile at all! - -In order to be able to compile xine-lib, you need (amongst other things) the -zlib compression library plus the appropriate headers, which are often found in -a package called zlib-devel or similar. - -Read again carefully the output ./configure produced and/or compiler warnings -and error reports, they often contain helpful information to find out what's -going on. If you're stuck here and decide to post your problem on the xine-user -mailing list, make sure you include these outputs. - -------------------------------------------------------------------------------- - -The Xv video-out plugin fails to compile! - -If you want to have Xv support compiled in, make sure you either have a shared -Xv library on your system, e.g. ls /usr/X11R6/lib/libXv* should give you some -.so libs, like this: - /usr/X11R6/lib/libXv.a - /usr/X11R6/lib/libXv.so - /usr/X11R6/lib/libXv.so.1 - -Alternatively you need to have libtool 1.4 or newer installed, then libXv.a is -sufficient. Otherwise you can create the shared versions yourself: - ld --whole-archive -shared -o libXv.so.1 libXv.a - ln -s libXv.so.1 libXv.so - ldconfig - -Now you should be ready to build the Xv video-out plugin on your system. - -------------------------------------------------------------------------------- - -Build problems in frontends (gxine/xine-ui/...) - -I have installed xine-lib but the frontend complains about not finding it! - -First of all take a closer look at the compilation instructions above again. -You will probably find your answer there right away. - -As stated there (there again that hint *grin*), make sure that you have $prefix -/bin in your path and that your linker is able to find libraries installed in -$prefix/lib By the way, $prefix is where you installed your xine-lib to earlier -(yes, installing xine-lib with make install would be a good idea before trying -to compile the frontend ;) ). - -------------------------------------------------------------------------------- - -Can I install xine in my home directory (without being root)? - -Sure. First set up a subdir where you install your private software, eg. - mkdir ~/xine - -Then you have to set a few environment variables - it's probably a good idea to -add this to your ~/.bashrc (or somewhere similar): - export PATH="$HOME/xine/bin:$PATH" - export LD_LIBRARY_PATH="$HOME/xine/lib:$LD_LIBRARY_PATH" - -Now you can unpack tarballs e.g. in ~/xine/src (mkdir ~/xine/src if necessary) -and do a - ./configure --prefix=$HOME/xine - make install - -You also need to tell frontends using xine-lib, where to find it: - ./configure --prefix=$HOME/xine --with-xine-prefix=$HOME/xine - -------------------------------------------------------------------------------- - -Playback of various stream types - -DVD Playback with xine - -How do I play back DVDs with xine? - -Newer xine (1.0.x) releases come with a full-featured DVD plugin that should be -able to handle any unencrypted, non-locked DVD with full menu navigation -support. No external plugins are required anymore here. - -To get DVD playback working, first make sure you have a symlink /dev/dvd -pointing to your DVD device on your system. For example, if your DVD drive is -the master ide drive on the second IDE channel, /dev/dvd should point to /dev/ -hdc. Please note that if you are using the ide-scsi emulation on your system, -it is likely that your DVD drive got mapped to a scsi device node even though -it is an ide drive. In that case first check out you boot/kernel logs (or run -cdrecord -scanbus) to find out which device it got mapped to and set the -symlink accordingly (should be something like /dev/scd0, /dev/scd1, ... in that -case). Also make sure you (as a user) have sufficient (read and write) -permissions on your DVD drive. This could mean you either have to change the -device permissions or add your user to a special group (e.g. addgroup cdrom -username), depending on your setup and/or distribution. - -It is highly recommended to switch DMA mode on for your DVD drive (without it -even very recent machines will have trouble producing smooth video output). Use -a command like hdparm -d 1 <device> on your DVD device. Please note that even -if you're using ide-scsi you will have to set the dma flag on the ide device -node (e.g. /dev/hdc), not the mapped /dev/scd scsi device. - -To be able to play back encrypted DVDs you need to have libdvdcss installed on -your system (please check if this is legal where you live). If you do not -understand what the term "encrypted DVD" means here: As a rule of thumb, every -DVD you have to pay money for is most likely encrypted. - -To make matters worse, apart from encryption, there is another obstacle to -take: the region code. The DVD authorities decided to divide the world into -eight geographical regions. Have a look at http://www.dvdforum.gr.jp/ -RegionMap.pdf if you want to know which number has been assigned to your -country. It is now their idea, that you shall only play DVDs, which have been -produced for your region. If you take a DVD off the shelf in your local store, -you should find a little globe-like icon which shows the region code the disc -is for. - -Newer (post-2000) DVD drives (so-called RPC-2 drives) check the DVD region, -which means they'll prevent you from playing back DVDs that have a different -region code from what the drive is set up for. Some drives come with a factory -setting of region 0 so they can play back any DVD until a region code is set. -Others refuse to play any DVD at all until they are told a region. The easiest -way to handle this is to use the regionset utility from http://sourceforge.net/ -project/showfiles.php?group_id=31346&release_id=168415 . - -Once you have everything set up, try something like gxine dvd:/ or xine -p dvd: -/ to start dvd playback. Some frontend also offer so-called autoplay buttons or -menu entries that start dvd playback immediately. - -Important: do not try to mount the DVD. Just insert it and hit the DVD autoplay -button or start xine from the command line. - -If things do not work as expected, try running the xine-check shellscript that -comes with xine to see if this gives you further hints on what could be wrong. - -------------------------------------------------------------------------------- - -DVD playback works, but it takes a long time until playback starts - -This points to a region code problem. Some versions of libdvdcss can play back -DVDs from other regions than the RPC-2 DVD drive is set up for, but this -usually means a cryptographic attack (which takes time) has to be used to -access the DVD. - -You can download a tool to set the region code of RPC-Drives here: http:// -sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 . - -Warning: Please be aware that the number of region code changes in RPC-2 drives -is limited (usually about 5 times), after that your drive will stay locked to -the region you last set it up for. - -------------------------------------------------------------------------------- - -I have problems setting up my RPC-2 drive for the right region! - -You can download a tool to set the region code of RPC-Drives here: http:// -sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 . - -Warning: Please be aware that the number of region code changes in RPC-2 drives -is limited (usually about 5 times), after that your drive will stay locked to -the region you last set it up for. - -------------------------------------------------------------------------------- - -Can I watch Video CDs (VCDs)? SVCDS ? CD-i? - -xine supports VCD and SVCD playback out-of-the box. Similar to DVDs, make sure -you have a /dev/cdrom alias pointing to your CDROM drive which you will use to -play back the (S)VCD. - -At the moment, CD-i formats are not supported by xine. - -Do not try to mount the (S)VCD. Simply insert it into your CDROM drive and hit -the VCD autoplay button or start something like gxine vcd:/ or xine vcd:/ from -the command line. - -------------------------------------------------------------------------------- - -Can I watch Quicktime (.mov, .mp4) files using xine? - -Quicktime is just a system layer (container format) which can contain various -different audio and video formats. The system layer itself is fully supported -in xine. However, some quicktime audio/video codecs are not natively supported -yet. Luckily, if you are using a x86 compatible machine (any recent PC hardware -should do) you can install and use the original Quicktime DLLs and watch most -streams (trailers) that can be downloaded from the net. - -Possibly the most convenient way to get the Quicktime DLLs is to download them -from the mplayer website http://www1.mplayerhq.hu/MPlayer/releases/codecs/ . -The package is called "QuickTime6 DLLs". Unpack it and move everything you find -inside to /usr/lib/win32 (actually you can place them anywhere you want, e.g. -someplace in your homedirectory, but then you'll have to set codec.win32_path -in your xine config file accordingly). Restart xine then and you should be able -to watch Quicktime trailers. - -------------------------------------------------------------------------------- - -Real Network files/streams - -Can I watch Real (.rm, .ram) files using xine? - -The situation with real files and streams is pretty similar to the situation -with Quicktime Streams (see above). The newer real audio and video formats are -only supported by using binary-only codecs which are available from real -networks but are not included in xine. - -One way to get these codecs is to download and install RealPlayer from -RealNetworks, for example in /usr/local/RealPlayer8 or /opt/RealPlayer8. If you -installed it in one of these places, xine should automatically find and use the -real binary codecs. If it doesn't work, try to find out the exact path to where -the real codecs are installed on your system (look for a file named rv30.so.6.0 -which should reside in a directory called Codecs in the directory where you -have installed RealPlayer in) and set codec.real_codecs_path in your xine -config file accordingly. - -------------------------------------------------------------------------------- - -What about (live) network streams (pnm://, rtsp:// style urls)? - -xine supports both pnm and rtsp streaming. However, digging out the actual pnm/ -rtsp url can be tricky as they're often packed into heavy JavaScript and HTML -code on most websites. You can either use a combination of your browser's "save -source" function and wget or use a xine browser plugin (currently the gxine -frontend comes with a simple mozilla plugin, for example). When you decided to -dig out the url by hand don't get fooled by the many redirectors that are often -placed around the actual url. Use wget to download any http://-style urls and -use less to look inside the downloaded .ra/.ram files where you will find the -actual pnm/rtsp url which can be opened using xine. - -------------------------------------------------------------------------------- - -Can I watch Windows Media (.asf/.wmv/.wma) files using xine? - -While the container format (system layer) ASF (wmv is just an alias) is fully -supported in xine, for newer windows media 9 based streams you'll need to -install windows binary codecs (.DLLs). - -Possibly the most convenient way to get the windows DLLs is to download them -from the mplayer website http://www1.mplayerhq.hu/MPlayer/releases/codecs/ . -The package is called "Win32 Codecpack". Unpack it and move everything you find -inside to /usr/lib/win32 (actually you can place them anywhere you want, e.g. -someplace in your homedirectory, but then you'll have to set codec.win32_path -in your xine config file accordingly). Restart xine then and you should be able -to watch windows media streams. - -------------------------------------------------------------------------------- - -Can I watch Digital TV (Digital Video Broadcast) using xine? - -At the time of this writing DVB support is a very new and experimental feature -in xine. The number of supported cards is pretty limited at the moment. See doc -/README.dvb (in the xine-lib tarball) for details. - -------------------------------------------------------------------------------- - -How do I play streams from STDIN? - -Use something like: - cat stream.mpg | gxine stdin:/ - -------------------------------------------------------------------------------- - -How can I watch files with external AVI subtitles? - -In xine 0.9.13 this used to be: - xine foo.avi%bar.sub - -Latest xine-lib modules (1-beta3 or newer) support external subtitles for any -media file, not only AVI. In order to use it you can pass a special MRL -construction like: - xine test.mpg#subtitle:file.sub -The external subtitles support can also be used by any xine frontend. -Currently, just xine-ui implements this feature with a subtitle selection -dialog. - -------------------------------------------------------------------------------- - -Running xine - -I have a lot of dropped frames - what can I do? - -Your hardware might be too slow for xine. Make sure you turn on all speed -optimizing options. A few things you should check (in order of importance): - - * First of all, run the xine-check script included in xine package (probably - already installed in your system). xine-check will report several of the - most common problems listed here. Sample output from xine-check: - xine-check - Please be patient, this script may take a while to run... - [ good ] you're using Linux, doing specific tests - [ good ] looks like you have a /proc filesystem mounted. - [ good ] You seem to have a reasonable kernel version (2.4.18) - [ good ] intel compatible processor, checking MTRR support - [ good ] you have MTRR support and there are some ranges set. - [ good ] found the player at /usr/local/bin/xine - [ good ] /usr/local/bin/xine is in your PATH - [ good ] found /usr/local/bin/xine-config in your PATH - [ good ] plugin directory /usr/local/lib/xine/plugins exists. - [ good ] found input plugins - [ good ] found demux plugins - [ good ] found decoder plugins - [ good ] found video_out plugins - [ good ] found audio_out plugins - [ good ] skin directory /usr/local/share/xine/skins exists. - [ good ] found logo in /usr/local/share/xine/skins - [ good ] I even found some skins. - [ good ] /dev/cdrom points to /dev/hdc - [ good ] /dev/dvd points to /dev/hdc - [ good ] DMA is enabled for your DVD drive - [ good ] found xvinfo: X-Video Extension version 2.2 - [ good ] your Xv extension supports YUV overlays (improves MPEG performance) - [ good ] your Xv extension supports packed YUV overlays - [ good ] Xv ports: YUY2 YV12 I420 UYVY - - * Try to use the Xv driver, it greatly improves performance and quality - because your graphics card does image scaling and colorspace conversion. - The video section contains important information about several Xv drivers. - - If Xv cannot be used for some reason, make sure your display is set up to - 16bpp, not 24 or higher (reduces memory bandwith). Some Xv drivers may also - have better performance with 16bpp. - - * Make sure the hard drive (or cdrom/dvd drive) which supplies the video data - is in DMA mode (if supported). - - On most linux-based systems, you can use hdparm to check this: - hdparm /dev/hda - [...] - using_dma = 1 (on) - [...] - - You can enable DMA mode with the following command: - hdparm -d1 device_of_your_drive_that_supplies_video_data - In some cases where this fails it helps to specify the dma mode to use, for - example: - hdparm -d1 -X 66 device_of_your_drive_that_supplies_video_data - In RedHat 8.0 an additional entry in /etc/modules.conf - options ide-cd dma=1 - should help (reboot for this change to take effect). - - More information about this may be found here: http://oreilly.linux.com/pub - /a/linux/2000/06/29/hdparm.html . - - * Use a recent kernel which is optimized for your hardware. Old kernels may - lack support for accelerated instructions like SSE, for example. - - * Close other applications (use a tool like "top" to find out what - applications are using up CPU power). Programs that update the system clock - like ntp should also be disabled. - - * Enable MTRR support in your kernel. If you are still using XFree 3.x, - you'll have to tell the kernel yourself where the graphics memory is. - You'll find details about that in the linux dvd howto. - - If you're using XFree 4.x, enabling MTRR support in your kernel should be - enough (use a recent kernel!). - - Try a cat /proc/mtrr - if the file exists and you find an entry - corresponding to the amount of graphics memory you have, everything should - be fine. - - * Have your X-server (usually XFree86) running with higher priority. Most - recent linux distributions (like RedHat 8.0 or Mandrake 9.0) should do that - for you, improving not only xine but desktop responsiveness in general. - - Use the "top" utility and verify under the "NI" column if the X process has - a negative value, this indicates a higher priority. See "The X Window User - HOWTO - Performance considerations" for further instructions http:// - www.tldp.org/HOWTO/XWindow-User-HOWTO/performance.html . - - * Use the latest or a known-good gcc version and build an optimized xine-lib - for your architecture. - - * Besides boosting X-server priority, sometimes it's possible to avoid - discarding frames by making xine itself higher priority. This is not a - recommended pratice since it will require to run xine as root, but you may - give it a try if you want: - nice --5 xine - - * xine needs high speed memory access which depends on your chip set. Make - sure you enable all speed-improving options. - - Especially the via apollo pro chipset is known to be quite weird, (most of - all on my gigabyte board). If you can't configure the ram access thoroughly - using the bios you might want to try some really nasty tricks, as explained - on (for example): http://www.overclockers.com/tips105/index03.asp - - This website centers around a windows-tool to tweak the chipset, you can do - the same on FreeBSD with pciconf. On some linux distributions there are - similar tools. - - * a nice performance tuning tool can be found here: http:// - powertweak.sourceforge.net - - * Set up and use raw devices for DVD access. Please note that the actual - performance gain during playback is very small if any, but since raw - devices are bypassing the kernel's buffer cache, Linux will not try to - cache the DVDs you play. This would not be useful, because xine does its - own caching and you usually play DVDs sequentially, which means you won't - reuse anything from the cache. But the problem would be that Linux throws - everything out of the cache that might be in there. - - Raw devices should be available in linux kernel 2.4.x and there are patches - for older kernels available from: ftp://ftp.kernel.org/pub/linux/kernel/ - people/sct/raw-io/ - - To use raw devices, first connect a free raw device to your dvd device, use - something like: - raw /dev/raw1 /dev/dvd - - Then create a link named "rdvd" pointing to that raw device: - ln -s raw1 /dev/rdvd - - * For slow / high-latency dvd drives it might help to increase the number of - video buffers xine allocates. Try setting video.num_buffers:500 to a higher - value (e.g. 1000 or 2500). - -------------------------------------------------------------------------------- - -Oki, xine doesn't drop frames now but video output still is not really smooth! - -Video output can be further improved by tuning your linux kernel: - - * Set HZ to 1000 in /usr/src/linux/include/asm-i386/param.h - - * Try applying scheduler patches, especially the O(1) and the preemptive - patches have proven useful at the time of this writing (spring 2003). - -Linux 2.5/2.6 will probably have these improvements out of the box. - -Miguel Freitas has written a nice article about his kernel multimedia -experiments . - -------------------------------------------------------------------------------- - -I have problems when using xine on FreeBSD, Solaris, ... ! - -Check out the the corresponding README files in the directory xine-lib/doc. - -------------------------------------------------------------------------------- - -What is aalib? How do I use it in xine? - -aalib is an ascii art library. xine comes with an aalib video output plugin so -you can watch movies in your xterm, on the console or on your old vt100 - very -cool ;> ... another nice option is to preview movies on a remote server in your -shell over ssh. - -To use it make sure you have aalib installed correctly before you configure/ -build xine-lib and xine-ui. In addition to the xine binary a binary named -aaxine should get built and installed. You can then use something like: - aaxine foo.mpg -to use aalib video output. - -------------------------------------------------------------------------------- - -What do all these ~/.xine/config (~/.gxine/config) entries mean? - -You can find information about them in xine-lib/doc/README.config_en. Frontends -may register additional config entries, you may find out more about them in -their documentation. Also the comments in the config file might help. - -------------------------------------------------------------------------------- - -Does xine support my dxr3 / hollywood+ card? - -While xine's focus is clearly on software decoding, the dxr3 is supported. - -You can find more information about using xine with the dxr3 here (also covers -how to do tv output using the dxr3). - -------------------------------------------------------------------------------- - -Audio related questions - -What audio drivers does xine support? OSS? Alsa? Arts? Esd? - -Currently xine support audio output via OSS (kernel audio drivers), ALSA 0.9.x -(ALSA 0.5.x is no longer supported), arts (KDE's sound daemon) and esound (esd, -gnome's sound daemon - not recommended because it has serious issues with a/v -sync). - -------------------------------------------------------------------------------- - -When I'm watching a movie, the sound effects are much higher in volume than the -voices! - -Congratulations, you seem to have an original movie audio track there. - -Uhm. So you don't like it. Well, there are two things you can do: - - * You can enable xine's audio compressor. Most frontends have a settings - window and in that you'll find a slider for the compressor setting. The - values are percent values, so a slider setting of 200 means that xine will - double the volume of silent parts of the movie (loud parts stay the same). - - If your frontend does not have such a compression slider, you can pass the - value with the MRL: - xine dvd:/#compression:150 - - * If you have a dolby digital (AC3) soundtrack, you can try to enable - liba52's dynamic range compression setting codec.a52_dynrng:1 in your xine - config file (or use some gui config dialog). - -------------------------------------------------------------------------------- - -When I play this stream, xine shows video but there's no audio! - -If this happens with any video, first try a different audio driver (gxine -A -oss, gxine -A arts, xine -A alsa ...). - -If this problem only occurs with one specific stream, maybe switching to a -different audio channel (using the gui) helps. Some DVD streams have audio on -strange channels. - -If all this doesn't help, maybe you're missing an audio codec or you found a -bug. If you decide to post your problem on the xine-user mailing list, make -sure to include all console output xine produced and also clearly state what -type of stream you tried to play back or, even better, make a test stream -available somewhere for developers to download and try. - -------------------------------------------------------------------------------- - -Can xine produce 4-/5-channel surround audio output? - -Yep, it can do that using OSS or ALSA drivers, provided that the driver -supports it. On startup xine tells you what modes are supported by your audio -driver, e.g: - audio_alsa_out : supported modes are mono stereo (4-channel not enabled in xine config) (5-channel not enabled in xine config) (5.1-channel not enabled in xine config) (a/52 and DTS pass-through not enabled in xine config) - -On this machine 4-channel surround would be possible. However, since xine -cannot detect if there are actually speakers connected to the additional -channels, you'll have to activate that feature manually. - -You can do this either in the config dialog while xine is running (press the -config button on the xine panel and go to the AUDIO tab) or have it the -complicated way by editing the config file yourself which is located in your -home directory in .gxine or .xine: - audio.four_channel:1 - audio.five_channel:1 - audio.five_lfe_channel:0 - -------------------------------------------------------------------------------- - -What about ac3 output via spdif to an external ac3 decoder? - -xine can do that too. Pretty much the same story as for 4-/5-channel surround -(see above). You can either use the config dialog or edit the config file (~ -/.xine/config or ~/.gxine/config) yourself: - audio.a52_pass_through:1 - -------------------------------------------------------------------------------- - -Getting SPDIF output from a SBLive 5.1 using OSS drivers - -The following explains how to get the above configuration going with xine. Some -parts of it may applicable to other configurations (cards that use the EMU10k1 -chip) as well. - -------------------------------------------------------------------------------- - -Requirements - - 1. xine-lib >= 1.x.x - - 2. OSS driver - - 3. an external decoder - - 4. a cable to connect the SBLive to the external decoder - -The configuration described was tested using a Soundblaster live 5.1 (rev 7) -with a Yamaha DSP-AX620 external decoder. - -------------------------------------------------------------------------------- - -Retrieving the driver - -The OSS driver is maintained by creative and can be downloaded at http:// -opensource.creative.com/. The driver package contains documentation on how to -install it. Besides that I'd like to add the following notes. - -In order to compile and install these drivers, you need a valid kernel -configuration file. For RedHat Linux's pre-compiled kernels these configuration -files can be found in /usr/src/linux/configs. After you've located the correct -config file for your kernel, you need to copy it to /usr/src/linux/.config For -example, when you run the 2.4.18-i686 kernel do : - cp /usr/src/linux/configs/kernel-2.4.18-i686.config /usr/src/linux/.config -Make sure that the emu10k1 module that is currently installed is not loaded. To -unload the modules: - /sbin/modprobe -rv emu10k1.o ac97_codec.o -If this mentions that the device is busy, some program is using the driver. -Some example could be a mixer application or sound daemon like artsd. You'll -need to close down the applications before continuing. At success it should -print something like: - # delete emu10k1 - # delete ac97_codec - # delete soundcore -Run make in the directory where you unpacked the driver and follow the -instructions printed at the end of each step. The last step should be: - make install-tools -As the README of the driver package mentions the SPDIF AC3 output doesn't work -by default. In the directory utils/scripts an emu10k1.conf file can be found -which need to be placed in the default installation directory (/usr/local/etc). -After this the emu10k1.conf needs to be modified. The following settings worked -fine for me (I don't use the analog outputs of the card): - CARD_IS_5_1=yes - USE_DIGITAL_OUTPUT=yes - ENABLE_TONE_CONTROL=yes - AC3PASSTHROUGH=yes - ENABLE_LIVEDRIVE_IR=no - INVERT_REAR=no - MULTICHANNEL=yes - ROUTE_ALL_TO_SUB=no - ANALOG_FRONT_BOOST=no - SURROUND=no - PROLOGIC=no - ENABLE_CD_Spdif=yes - ENABLE_OPTICAL_SPDIF=no - ENABLE_LINE2_MIC2=no - ENABLE_RCA_SPDIF=no - ENABLE_RCA_AUX=no -After modifying the emu10k1.conf, you need to modify your /etc/modules.conf and -make sure the following lines are in there. - alias sound-slot-0 emu10k1 - post-install emu10k1 /usr/local/etc/emu-script -After saving the changes to modules.conf, run - /sbin/depmod -a -Now, you're ready to load the new modules and set the correct options for it. -To load the modules run: - /sbin/modprobe emu10k1 - -------------------------------------------------------------------------------- - -Setting up xine for SPDIF (AC3_passthrough) output - -You can either use the config dialog of your frontend or edit the config file -(~/.xine/config) yourself: - audio.a52_pass_through:1 -In case the setting is not in the file you can add it. - -------------------------------------------------------------------------------- - -The cable used for the SBLive can easily be self-made or buy a stereo 3.5mm -jack to dual RCA cable. - -What you need to make the cable yourself: - - * stereo 3.5mm jack plug - - * RCA plug - - * shielded cable (video coax 75 Ohm will do) - -Connect them as follows : - center pin jackplug ------|----- center pin RCA plug - GND __|__ GND - -In order to test it use a DVD with AC3 or DTS track start xine and select the -right audio track from user interface or start xine as: - xine dvd:/1 -a 0 -The external decoder should display something like "Dolby Digital" in case the -selected audio track contains AC3 data or "DTS" in case the selected audio -track contains DTS data. Of course stereo audio also goes through the SPDIF -output, so the analog outputs of the SBLive 5.1 are not needed anymore. - -------------------------------------------------------------------------------- - -Changing the volume with the GUI control has no effect! What's up!? - -Some xine drivers do not support volume changing although the GUI will show the -volume bar. Usually this is not xine's fault: aRts C API, for example, doesn't -offer any volume property to applications. Similarly, with ac3 pass through it -is not possible to set the volume. - -Note that recently we added support to "simulate" volume in aRts by changing -sample values on-the-fly before delivering them to the driver. Not as good as -having access to sound card's mixer but at least users will not complain about -lacking of volume bar anymore! :) - -------------------------------------------------------------------------------- - -Audio is stuttering and i see a lot of "metronom: fixing sound card drift by --2115 pts" on the console output - -Might be a soundcard problem, if it only comes in longer intervals. Your -soundcard does not keep it's sampling frequency accurately enough, which -results in audio and video getting out of sync and xine has to compensate. If -you see the message only from time to time, you might remedy it by using the -resampling sync method. You can do this by setting the configuration entry -audio.av_sync_method to resample. - -If you receive the metronom message more often, maybe switching to different -drivers (alsa to oss or vise-versa) can help here. It has also been reported -that setting the configuration entry audio.force_rate to the native sampling -rate of your soundcard (try 44100 and 48000) helps sometimes. - -Another, whole different possibility is that you have some background process -running which is messing with the clock (like some ntp client - chronny, ntpd, -...). - -Occasional messages of "fixing sound card drift" may happen on start and when -playing a long stream (like a movie). This is normal behaviour, nothing to -worry about. - -------------------------------------------------------------------------------- - -xine seems to lose sound arbitrarily during playback, especially with DVDs - -You are using the OSS audio output plugin, right? In order to keep video and -audio in sync, xine regularly queries the audio driver for the amount of delay -induced by the current length of the driver's audio buffer. Unfortunately some -OSS drivers seem to be broken because the can return strange values here. This -confuses the xine audio subsystem and makes it drop audio. - -You should try the various settings of the configuration entry -audio.oss_sync_method. The options getodelay and getoptr ask the driver and -might therefore show the problem. But chances are that only one is broken and -the other works, so you should try them both first, since they are the most -accurate. The option probebuffer does not ask the driver directly but tries to -determine the buffer length from outside. This should work with any driver and -is the way to go, of the driver dependent methods fail. softsync is the least -accurate and should be used only in emergency situations. - -------------------------------------------------------------------------------- - -Video related questions - -I can hear the audio - but I don't see a picture! - -Probably your hardware is simply too slow - see above for some hints on how to -speed things up. - -Another possibility is that you using a buggy Xv driver, see the next question. - -------------------------------------------------------------------------------- - -How can I make xine use the Xv extension and what drivers do I need? - -xine will normally use Xv by default if it is available. In some cases you -might need to choose Xv playback manually (when the ~/.xine/config file for -some reason says that you want to use XShm): - xine -V Xv foo.mpg - -If this doesn't work for you, it may be possible that Xv is not present on your -system. - -First you need to install/use XFree 4.x. Once you got that you have to make -sure the XFree drivers you're using are supporting Xv on your hardware. Here -are some hints for individual gfx chips: - - * 3Dfx: if all you get is a solid black window, upgrade at least to XFree - 4.1.0 - - * ATI: if you only get "half a picture", try lowering your resolution or bit - depth, disable DRI (looks like you ran out of video RAM) - - * Trident card: If you see vertical bands jumbled, upgrade to the latest - xfree/experimental trident drivers (for the CyberBlade XP a driver exists - here: http://www.xfree86.org/~alanh/ ) - - * nVidia: With newer GeForce cards, Xv should work with XFree 4.2.0 or newer, - for older RivaTNT cards use the binary drivers from nvidia (of course the - binary drivers work as well for GeForce cards) - - * Mach64/Rage3D (not Rage128/Radeon) cards/chips get no XVideo with standard - drivers, try GATOS drivers instead - - * intel: i815 has Xv support in XFree 4.x, others unknown - - * Permedia 2/3 has Xv support in XFree 4.x - - * Savage: at least some older drivers tend to lock up the whole machine, try - the drivers available from http://www.probo.com/timr/savage40.html . - - * SIS: certain controllers (more info needed!) have Xv support in XFree 4.x - - * Chips and Tech 6555x, 68554, 69000, 69030 have Xv support in XFree 4.x - - * NeoMagic: certain controllers (more info needed!) have Xv support in Xfree - 4.x - - * SiliconMotion: certain controllers (more info needed!) have Xv support in - Xfree 4.x - - * Matrox: G200 or newer (but not Parhelia) have Xv support in XFree 4.x. For - Parhelia, use the binary only drivers available from matrox' website. - -------------------------------------------------------------------------------- - -Some parts of my X Desktop get transparent when xine plays the video! - -Looks like some colors on your GUI match the colorkey Xv uses. You can change -the colorkey value to avoid this. There should be a line like: - video.XV_COLORKEY:2110 -in your ~/.xine/config file where you can change the color that's used by xine -for the video overlay. - -------------------------------------------------------------------------------- - -The aspect ratio of the video is wrong! - -Try pressing "a" to change the aspect ratio. - -------------------------------------------------------------------------------- - -What is the difference between discarded and skipped frames? - -Sometimes xine will output a message like that: - 200 frames delivered, XX frames skipped, YY frames discarded - -The difference between these counters is a little subtle for the non developer. -There are two threads running in order to display video: the decoder thread -will deliver frames to the video output thread. The later is responsible for -scheduling the frames to be displayed at the right time. - -If your system can't keep up with decoding requirements, decoder will deliver -overdue frames. Imagine if it finished decoding the frame tagged for displaying -at 11:30 but xine clock marks 11:31. When this situation is detected, xine will -try to skip decoding a few frames to recover. Not every decoder may support -this feature. - -When the frame is decoded to be shown somewhere in future but the output thread -doesn't get scheduled in time by the operating system to complete the -operation, the frame is discarded. One cause might be the disk access -operation, which may halt the system for a few miliseconds without DMA. See -performance section tips above. - -Note that if a decoder can't skip frames for some reason, you would never see -frames skipped (they would be all discarded). - -------------------------------------------------------------------------------- - -My xine is runing in black and white! / I only get a gray video output! - -This frequently happens with new Xv drivers or when switching to a different -video card. Background is that different Xv drivers often use different ranges -for the contrast/brightness/saturation settings. - -To fix this, try opening the xine settings window and try adjusting the sliders -for contrast, brightness and saturation. - -Please note that some frontends save these settings in their config file so -when you have found a working combination, make sure you exit xine cleanly so -the values are saved. - -------------------------------------------------------------------------------- - -Which is the best video driver to use? - -xine support several video drivers for outputing the image. These will differ -on how the frames are copied to the video card memory, whether colorspace -conversion and scaling is done in software or hardware, among other things. -They may also differ on ease of use and stability. - -Most of the time, Xv should give the users a good trade-off between quality, -compatibility and ease of use. This is why xine tries to use Xv by default. - -However some users may want to explore better the available hardware -capabilities (eg. syncing frame drawing with monitor refresh). Also some Xv -drivers contain slow copies and accessing the video card directly may yield -performance gains. - -Drivers that access hardware directly includes VIDIX (warning: requires root -priviledges or kernel helper) and SyncFB (requires kernel helper - Matrox -only). User may try one of those, but should be warned that with root access -they can cause the system to crash hard. The support is also limited to a -couple of graphics cards only. - -Graphic workstations like SGI have usually a good support for OpenGL. In that -case, using OpenGL may be a better choice than XShm. However for most desktop -systems the performance of OpenGL will be quite bad. - -------------------------------------------------------------------------------- - -Error Messages: What they mean and what you can do - -Starting xine fails with complains about audio drivers/devices! - -You can select the audio driver using the -A option. So try: - xine -A null -If you have ALSA drivers installed, try: - xine -A alsa -If you run ESD (not recommended), try: - xine -A esd -If you run artsd, try: - xine -A arts - -------------------------------------------------------------------------------- - -"no video port found" - -You got the Xv extension, but your video card driver doesn't support it. First -try to find a driver that does support Xv on your hardware (check your graphics -card vendor). If your driver has Xv support but you can't get it working, try -at a lower resolution (1024x768 is enough even for anamorphic DVDs). - -If all that fails, you can still use plain X11/XShm: - gxine -V XShm foo.vob - -------------------------------------------------------------------------------- - -"Unable to open dvd drive (/dev/dvd)" - -You probably don't have /dev/dvd (check that). If so, simply create a link /dev -/dvd that points to your DVD device. Something like... - ln -s hdc /dev/dvd -...should do the job. Also make sure you have read and write access on the -device the symlink points to. See the dvd playback section for more -information. - -------------------------------------------------------------------------------- - -My drive doesn't work and the kernel says "status=0x51 { DriveReady -SeekComplete Error }" - -This error can be fixed by recompiling your kernel with the option "Use -multi-mode by default" enabled in the IDE settings. - -------------------------------------------------------------------------------- - -"demux error! 00 00 00 (should be 0x000001)" - -Probably xine can't access your input source. Most commonly this happens when -you're trying to play locked/encrypted DVDs. Remember that xine can't play such -DVDs out-of-the box for legal reasons (see above). - -If it is legal where you live, you can try to install libdvdcss. Once you have -done that and re-start xine, it should automatically detect and use it to play -back encrypted DVDs. - -Another reason could be that your (RPC-2) DVD drive isn't set up for the right -region (see above). - -------------------------------------------------------------------------------- - -"audio driver 'oss' failed, using null driver instead" - -First of all, make sure that your OSS Audio drivers are working (i.e. you can -play music with other software). Maybe you're using alsa? If so, try gxine -A -alsa to see if this helps. - -The most common reason for oss not working is that some other program is -accesing your audio device. If you're using linux, the command fuser /dev/dsp -should give you the PID of the process. - -If you are using GNOME, chances are that this is caused by ESD. Now you have -two possibilities. Either deactivate ESD (temporarily) by right clicking on the -sound monitor applet and selecting "Place Esound in standby" or just kill it. -Then xine will use OSS audio output. The other method is to make xine use ESD -for audio output with: - gxine -A esd -This may result in worse playback - exact syncronization is not possible with -esd, so using oss should be preferred. - -If you are using KDE, there is the possibility that the aRts sound daemon is -currently running and thus blocking your sound device. You can check that by -starting the aRts control (in your KDE menu it should be under Multimedia). If -it is running, you can either use the aRts audio output plugin: - gxine -A arts -Or you suspend the aRts daemon by checking the appropriate option in your aRts -control. (recommended) - -Newer versions of arts have an auto-suspend mode - this can lead to some -nondeterministic behaviour of xine if it is set up to use the audio device -directly. Using arts is recommended in that case, however you will loose the -ability to do four/five channel audio output. - -------------------------------------------------------------------------------- - -"video_out: throwing away image with pts xxx because it's too old" - -This is a performance related problem. If you have a fast computer and this -message shows from time to time playing dvd/cdrom, it's very likely that your -drive is not DMA enabled. - -------------------------------------------------------------------------------- - -"No video plugin available to decode 'xxxxxx'." - -You have tried to play a stream using a unknown or unhandled codec. Possibly -the file uses some obscure proprietary format and no information is available -on how to decode it. - -If you're on an x86 platform (e.g. PC hardware) you might want to try -installing binary-only windows medial, real networks and quicktime codecs (see -above). - -------------------------------------------------------------------------------- - -"w32codec: decoder failed to start. Is 'xxxxxx' installed?" - -You probably don't have the win32 dll needed to decode this file. - -------------------------------------------------------------------------------- - -xine just crashed on me - i didn't get any error message - -OK, yes, that shouldn't happen and you're upset. We can understand that. But, -to help you and of course to fix this, we need some information. So, let's go -through the checklist and maybe prepare a nice bug report for the xine-user -mailing list: - - * Did xine really crash (segfault) or did it hang (deadlock)? - - * Can you reproduce the bug? (e.g. do you remember what you did and when you - do it again it crashes again?) - - * Is that a specific media file or format which crashes xine? (Have you tried - other files types?) - - * Check the console output (and include it in a bug report), maybe earlier - there is some output that points to the problem. - - * Your X server just froze on you? unfortunately that's a known problem with - some chipsets and drivers (most commonly Savage chipsets) when using Xv. - You might want to try running gxine -V XShm to see if the problem is - related to the Xv driver. This will unfortunately be much slower, as lots - of things are now done in software instead of hardware scaling/colour space - conversion. - - Maybe at the time you read this, there's an XFree upgrade which fixes this - for the Savage driver. If that works for you, please notify the xine crew - at <xine-user@lists.sourceforge.net>, so they can update this FAQ! - - * Even though we try to make each release as bug free as possible, xine is - still under heavy development (nice excuse, isn't it? *grin*). - - If you write to the xine user mailing list <xine-user@lists.sourceforge.net - > make sure you include a the above information (when applicable) and also - some information about your machine (operating system, cpu type and speed, - gfx card, sound card, ...) and please use a meaningfull subject line ("xine - bug" is bad, "xine fails to play this quicktime trailer in fullscreen mode" - ist much better). - - Thanks for taking the time to help improve xine. - diff --git a/doc/hackersguide/.cvsignore b/doc/hackersguide/.cvsignore index 282522db0..28b4cdaa4 100644 --- a/doc/hackersguide/.cvsignore +++ b/doc/hackersguide/.cvsignore @@ -1,2 +1,4 @@ Makefile Makefile.in +hackersguide.html +*.png diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index 205fccf44..b4cfa2228 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -10,8 +10,7 @@ hackersguide_sgml = hackersguide.sgml \ docs_DOCS = hackersguide.html architecture.png library.png overlays.png -EXTRA_DIST = README $(hackersguide_sgml) $(docs_DOCS) \ - architecture.fig library.fig overlays.fig +EXTRA_DIST = README $(hackersguide_sgml) architecture.fig library.fig overlays.fig docdir = $(prefix)/share/doc/xine/hackersguide @@ -38,12 +37,24 @@ uninstall-local: docs: $(docs_DOCS) +dist-hook: + @make fail_if_missing=yes docs + cp $(docs_DOCS) $(distdir) + hackersguide.html: $(hackersguide_sgml) @if test "$(SGMLTOOLS)" != "no"; then \ $(SGMLTOOLS) -b onehtml hackersguide.sgml; \ + else if test "$(fail_if_missing)" = "yes"; then \ + echo "Please install sgmltools-lite."; \ + exit 1; \ + fi; \ fi %.png: %.fig @if test "$(FIG2DEV)" != "no"; then \ $(FIG2DEV) -L png -S 4 $< $@; \ + else if test "$(fail_if_missing)" = "yes"; then \ + echo "Please install fig2dev."; \ + exit 1; \ + fi; \ fi diff --git a/doc/hackersguide/hackersguide.html b/doc/hackersguide/hackersguide.html deleted file mode 100644 index 9031002d4..000000000 --- a/doc/hackersguide/hackersguide.html +++ /dev/null @@ -1,5108 +0,0 @@ -<HTML -><HEAD -><TITLE ->The xine hacker's guide</TITLE -><META -NAME="GENERATOR" -CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD -><BODY -CLASS="BOOK" -><DIV -CLASS="BOOK" -><A -NAME="AEN1" -></A -><DIV -CLASS="TITLEPAGE" -><H1 -CLASS="TITLE" -><A -NAME="AEN2" -></A ->The xine hacker's guide</H1 -><H3 -CLASS="AUTHOR" -><A -NAME="AEN6" -></A ->Günter Bartsch</H3 -><H3 -CLASS="AUTHOR" -><A -NAME="AEN9" -></A ->Heiko Schäfer</H3 -><H3 -CLASS="AUTHOR" -><A -NAME="AEN12" -></A ->Richard Wareham</H3 -><H3 -CLASS="AUTHOR" -><A -NAME="AEN15" -></A ->Miguel Freitas</H3 -><H3 -CLASS="AUTHOR" -><A -NAME="AEN18" -></A ->James Courtier-Dutton</H3 -><H3 -CLASS="AUTHOR" -><A -NAME="AEN21" -></A ->Siggi Langauf</H3 -><H3 -CLASS="AUTHOR" -><A -NAME="AEN24" -></A ->Marco Zühlke</H3 -><H3 -CLASS="AUTHOR" -><A -NAME="AEN27" -></A ->Mike Melanson</H3 -><H3 -CLASS="AUTHOR" -><A -NAME="AEN30" -></A ->Michael Roitzsch</H3 -><P -CLASS="COPYRIGHT" ->Copyright © 2001-2003 the xine project team</P -><DIV -><DIV -CLASS="ABSTRACT" -><A -NAME="AEN36" -></A -><P -></P -><P -> This document should help xine hackers to find their way through - xine's architecture and source code. It's a pretty free-form document - containing a loose collection of articles describing various aspects - of xine's internals. - </P -><P -></P -></DIV -></DIV -><HR></DIV -><DIV -CLASS="TOC" -><DL -><DT -><B ->Table of Contents</B -></DT -><DT ->1. <A -HREF="#INTRO" ->Introduction</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN40" ->Where am I?</A -></DT -><DT -><A -HREF="#AEN44" ->What does this text do?</A -></DT -><DT -><A -HREF="#AEN47" ->New versions of this document</A -></DT -><DT -><A -HREF="#AEN54" ->Feedback</A -></DT -></DL -></DD -><DT ->2. <A -HREF="#XINE-LIBRARY" ->Using the xine library</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN61" ->xine architecture as visible to libxine clients</A -></DT -><DT -><A -HREF="#AEN75" ->Writing a new frontend to xine</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN78" ->Source code of a simple X11 frontend</A -></DT -></DL -></DD -></DL -></DD -><DT ->3. <A -HREF="#OVERVIEW" ->xine code overview</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN83" ->Walking the source tree</A -></DT -><DT -><A -HREF="#AEN400" ->Object oriented programming in C</A -></DT -><DT -><A -HREF="#AEN411" ->Coding style and guidelines</A -></DT -><DT -><A -HREF="#AEN430" ->The xine logging system</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN433" ->xine_log</A -></DT -><DT -><A -HREF="#AEN439" ->xprintf</A -></DT -><DT -><A -HREF="#AEN445" ->lprintf/llprintf</A -></DT -></DL -></DD -><DT -><A -HREF="#AEN458" ->How to contribute</A -></DT -></DL -></DD -><DT ->4. <A -HREF="#INTERNALS" ->xine internals</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN463" ->Engine architecture and data flow</A -></DT -><DT -><A -HREF="#AEN476" ->Plugin system</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN495" ->Plugin location and filesystem layout</A -></DT -><DT -><A -HREF="#AEN505" ->Plugin Content: What's inside the .so?</A -></DT -></DL -></DD -><DT -><A -HREF="#AEN544" ->What is this metronom thingy?</A -></DT -><DT -><A -HREF="#AEN557" ->How does xine synchronize audio and video?</A -></DT -><DT -><A -HREF="#OSD" ->Overlays and OSD</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN586" ->Overlay Manager</A -></DT -><DT -><A -HREF="#AEN590" ->OSD Renderer</A -></DT -></DL -></DD -><DT -><A -HREF="#AEN625" ->MRLs</A -></DT -></DL -></DD -><DT ->5. <A -HREF="#STREAM" ->xine's stream layer</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN635" ->Input layer</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN647" ->Writing a xine input plugin</A -></DT -></DL -></DD -><DT -><A -HREF="#AEN691" ->Demuxer layer</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN694" ->Introduction to demuxer theory</A -></DT -><DT -><A -HREF="#AEN698" ->Input considerations</A -></DT -><DT -><A -HREF="#AEN701" ->Seeking Policy</A -></DT -><DT -><A -HREF="#AEN708" ->Writing a xine demuxer</A -></DT -><DT -><A -HREF="#AEN748" ->Buffer types</A -></DT -></DL -></DD -><DT -><A -HREF="#AEN762" ->Decoder layer</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN765" ->Audio and video decoders</A -></DT -><DT -><A -HREF="#AEN769" ->Video output formats</A -></DT -><DT -><A -HREF="#AEN772" ->Audio output formats</A -></DT -><DT -><A -HREF="#AEN775" ->Writing a xine decoder</A -></DT -><DT -><A -HREF="#AEN836" ->SPU decoder</A -></DT -></DL -></DD -></DL -></DD -><DT ->6. <A -HREF="#OUTPUT" ->xine's output layer</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN851" ->Video output</A -></DT -><DD -><DL -><DT -><A -HREF="#AEN865" ->Writing a xine video out plugin</A -></DT -></DL -></DD -></DL -></DD -></DL -></DIV -><DIV -CLASS="CHAPTER" -><HR><H1 -><A -NAME="INTRO" -></A ->Chapter 1. Introduction</H1 -><DIV -CLASS="SECT1" -><H2 -CLASS="SECT1" -><A -NAME="AEN40" -></A ->Where am I?</H2 -><P -> You are currently looking at a piece of documentation for xine. - xine is a free video player. It lives on - <A -HREF="http://xinehq.de/" -TARGET="_top" ->http://xinehq.de/</A ->. Specifically - this document goes under the moniker of the "xine Hackers' Guide". - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN44" -></A ->What does this text do?</H2 -><P -> This document should help xine hackers to find their way through - xine's architecture and source code. It's a pretty free-form document - containing a loose collection of articles describing various aspects - of xine's internals. It has been written by a number of people who work - on xine themselves and is intended to provide the important concepts and - methods used within xine. Readers should not consider this document to be - an exhausative description of the internals of xine. As with all projects - which provide access, the source-code should be considered the definitive - source of information. - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN47" -></A ->New versions of this document</H2 -><P -> This document is being developed in the xine-lib cvs repository within - the directory <TT -CLASS="FILENAME" ->doc/hackersguide/</TT ->. If you are - unsure what to do with the stuff in that directory, please read the - <TT -CLASS="FILENAME" ->README</TT -> file located there. - </P -><P -> New versions of this document can also be obtained from the xine web site: - <A -HREF="http://xinehq.de/" -TARGET="_top" ->http://xinehq.de/</A ->. - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN54" -></A ->Feedback</H2 -><P -> All comments, error reports, additional information and criticism - concerning this document should be directed to the xine documentations - mailing list <TT -CLASS="EMAIL" -><<A -HREF="mailto:xine-docs@lists.sourceforge.net" ->xine-docs@lists.sourceforge.net</A ->></TT ->. - Questions about xine hacking in general should be sent to the - developer mailing list <TT -CLASS="EMAIL" -><<A -HREF="mailto:xine-devel@lists.sourceforge.net" ->xine-devel@lists.sourceforge.net</A ->></TT ->. - </P -></DIV -></DIV -><DIV -CLASS="CHAPTER" -><HR><H1 -><A -NAME="XINE-LIBRARY" -></A ->Chapter 2. Using the xine library</H1 -><DIV -CLASS="SECT1" -><H2 -CLASS="SECT1" -><A -NAME="AEN61" -></A ->xine architecture as visible to libxine clients</H2 -><P -> The following drawing shows the components of xine as outside applications - see them. For every component, the functions for creating and destroying it - are given. Every other function works in the context it is enclosed in. - Functions that facilitate the connection of the individual components are - also given. - </P -><DIV -CLASS="MEDIAOBJECT" -><P -><IMG -SRC="library.png"><DIV -CLASS="CAPTION" -><P ->outside view on xine components</P -></DIV -></P -></DIV -><P -> The function are named just to give you an overview of what is actually - there. It is all thoroughly documented in the plublic header - <TT -CLASS="FILENAME" ->xine.h</TT ->, which is the main and preferably the only xine - header, clients should include. (xine/xineutils.h and the XML parser might - make an exception.) - </P -><P -> Details on the OSD feature can be found in the <A -HREF="#OSD" ->OSD section</A ->. - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN75" -></A ->Writing a new frontend to xine</H2 -><P -> The best way to explain this seems to be actual code. Below you - will find a very easy and hopefully self-explaining xine frontend - to give you a start. - </P -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN78" -></A ->Source code of a simple X11 frontend</H3 -><TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" ->/* -** Copyright (C) 2003 Daniel Caujolle-Bert <segfault@club-internet.fr> -** -** This program is free software; you can redistribute it and/or modify -** it under the terms of the GNU General Public License as published by -** the Free Software Foundation; either version 2 of the License, or -** (at your option) any later version. -** -** This program is distributed in the hope that it will be useful, -** but WITHOUT ANY WARRANTY; without even the implied warranty of -** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -** GNU General Public License for more details. -** -** You should have received a copy of the GNU General Public License -** along with this program; if not, write to the Free Software -** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -** -*/ - -/* - * compile-command: "gcc -Wall -O2 `xine-config --cflags` `xine-config --libs` -lX11 -lm -o xinimin xinimin.c" - */ - -#include <stdio.h> -#include <string.h> -#include <math.h> - -#include <X11/X.h> -#include <X11/Xlib.h> -#include <X11/Xutil.h> -#include <X11/keysym.h> -#include <X11/Xatom.h> -#include <X11/Xutil.h> -#include <X11/extensions/XShm.h> - -#include <xine.h> -#include <xine/xineutils.h> - - -#define MWM_HINTS_DECORATIONS (1L << 1) -#define PROP_MWM_HINTS_ELEMENTS 5 -typedef struct { - uint32_t flags; - uint32_t functions; - uint32_t decorations; - int32_t input_mode; - uint32_t status; -} MWMHints; - -static xine_t *xine; -static xine_stream_t *stream; -static xine_video_port_t *vo_port; -static xine_audio_port_t *ao_port; -static xine_event_queue_t *event_queue; - -static Display *display; -static int screen; -static Window window[2]; -static int xpos, ypos, width, height, fullscreen; -static double pixel_aspect; - -static int running = 0; - - -/* this will be called by xine, if it wants to know the target size of a frame */ -static void dest_size_cb(void *data, int video_width, int video_height, double video_pixel_aspect, - int *dest_width, int *dest_height, double *dest_pixel_aspect) { - - if(!running) - return; - - *dest_width = width; - *dest_height = height; - *dest_pixel_aspect = pixel_aspect; -} - -/* this will be called by xine when it's about to draw the frame */ -static void frame_output_cb(void *data, int video_width, int video_height, - double video_pixel_aspect, int *dest_x, int *dest_y, - int *dest_width, int *dest_height, - double *dest_pixel_aspect, int *win_x, int *win_y) { - if(!running) - return; - - *dest_x = 0; - *dest_y = 0; - *win_x = xpos; - *win_y = ypos; - *dest_width = width; - *dest_height = height; - *dest_pixel_aspect = pixel_aspect; -} - -static void event_listener(void *user_data, const xine_event_t *event) { - switch(event->type) { - case XINE_EVENT_UI_PLAYBACK_FINISHED: - running = 0; - break; - - case XINE_EVENT_PROGRESS: - { - xine_progress_data_t *pevent = (xine_progress_data_t *) event->data; - - printf("%s [%d%%]\n", pevent->description, pevent->percent); - } - break; - - /* you can handle a lot of other interesting events here */ - } -} - -int main(int argc, char **argv) { - char configfile[2048]; - x11_visual_t vis; - double res_h, res_v; - char *vo_driver = "auto"; - char *ao_driver = "auto"; - char *mrl = NULL; - int i; - Atom XA_NO_BORDER; - MWMHints mwmhints; - - /* parsing command line */ - for (i = 1; i < argc; i++) { - if (strcmp(argv[i], "-vo") == 0) { - vo_driver = argv[++i]; - } - else if (strcmp(argv[i], "-ao") == 0) { - ao_driver = argv[++i]; - } - else - mrl = argv[i]; - } - - if (!mrl) { - printf("specify an mrl\n"); - return 1; - } - printf("mrl: '%s'\n", mrl); - - if (!XInitThreads()) { - printf("XInitThreads() failed\n"); - return 1; - } - - /* load xine config file and init xine */ - xine = xine_new(); - sprintf(configfile, "%s%s", xine_get_homedir(), "/.xine/config"); - xine_config_load(xine, configfile); - xine_init(xine); - - display = XOpenDisplay(NULL); - screen = XDefaultScreen(display); - xpos = 0; - ypos = 0; - width = 320; - height = 200; - - /* some initalization for the X11 Window we will be showing video in */ - XLockDisplay(display); - fullscreen = 0; - window[0] = XCreateSimpleWindow(display, XDefaultRootWindow(display), - xpos, ypos, width, height, 1, 0, 0); - - window[1] = XCreateSimpleWindow(display, XDefaultRootWindow(display), - 0, 0, (DisplayWidth(display, screen)), - (DisplayHeight(display, screen)), 0, 0, 0); - - XSelectInput(display, window[0], (ExposureMask | ButtonPressMask | KeyPressMask | - ButtonMotionMask | StructureNotifyMask | - PropertyChangeMask | PointerMotionMask)); - - XSelectInput(display, window[1], (ExposureMask | ButtonPressMask | KeyPressMask | - ButtonMotionMask | StructureNotifyMask | - PropertyChangeMask | PointerMotionMask)); - - XA_NO_BORDER = XInternAtom(display, "_MOTIF_WM_HINTS", False); - mwmhints.flags = MWM_HINTS_DECORATIONS; - mwmhints.decorations = 0; - XChangeProperty(display, window[1], - XA_NO_BORDER, XA_NO_BORDER, 32, PropModeReplace, (unsigned char *) &mwmhints, - PROP_MWM_HINTS_ELEMENTS); - - XMapRaised(display, window[fullscreen]); - - res_h = (DisplayWidth(display, screen) * 1000 / DisplayWidthMM(display, screen)); - res_v = (DisplayHeight(display, screen) * 1000 / DisplayHeightMM(display, screen)); - XSync(display, False); - XUnlockDisplay(display); - - /* filling in the xine visual struct */ - vis.display = display; - vis.screen = screen; - vis.d = window[fullscreen]; - vis.dest_size_cb = dest_size_cb; - vis.frame_output_cb = frame_output_cb; - vis.user_data = NULL; - pixel_aspect = res_v / res_h; - - /* opening xine output ports */ - vo_port = xine_open_video_driver(xine, vo_driver, XINE_VISUAL_TYPE_X11, (void *)&vis); - ao_port = xine_open_audio_driver(xine , ao_driver, NULL); - - /* open a xine stream connected to these ports */ - stream = xine_stream_new(xine, ao_port, vo_port); - /* hook our event handler into the streams events */ - event_queue = xine_event_new_queue(stream); - xine_event_create_listener_thread(event_queue, event_listener, NULL); - - /* make the video window visible to xine */ - xine_port_send_gui_data(vo_port, XINE_GUI_SEND_DRAWABLE_CHANGED, (void *) window[fullscreen]); - xine_port_send_gui_data(vo_port, XINE_GUI_SEND_VIDEOWIN_VISIBLE, (void *) 1); - - /* start playback */ - if (!xine_open(stream, mrl) || !xine_play(stream, 0, 0)) { - printf("Unable to open mrl '%s'\n", mrl); - return 1; - } - - running = 1; - - while (running) { - XEvent xevent; - - XNextEvent(display, &xevent); - - switch(xevent.type) { - - case KeyPress: - { - XKeyEvent kevent; - KeySym ksym; - char kbuf[256]; - int len; - - kevent = xevent.xkey; - - XLockDisplay(display); - len = XLookupString(&kevent, kbuf, sizeof(kbuf), &ksym, NULL); - XUnlockDisplay(display); - - switch (ksym) { - - case XK_q: - case XK_Q: - /* user pressed q => quit */ - running = 0; - break; - - case XK_f: - case XK_F: - { - /* user pressed f => toggle fullscreen */ - Window tmp_win; - - XLockDisplay(display); - XUnmapWindow(display, window[fullscreen]); - fullscreen = !fullscreen; - XMapRaised(display, window[fullscreen]); - XSync(display, False); - XTranslateCoordinates(display, window[fullscreen], - DefaultRootWindow(display), - 0, 0, &xpos, &ypos, &tmp_win); - XUnlockDisplay(display); - - xine_port_send_gui_data(vo_port, XINE_GUI_SEND_DRAWABLE_CHANGED, - (void*) window[fullscreen]); - } - break; - - case XK_Up: - /* cursor up => increase volume */ - xine_set_param(stream, XINE_PARAM_AUDIO_VOLUME, - (xine_get_param(stream, XINE_PARAM_AUDIO_VOLUME) + 1)); - break; - - case XK_Down: - /* cursor down => decrease volume */ - xine_set_param(stream, XINE_PARAM_AUDIO_VOLUME, - (xine_get_param(stream, XINE_PARAM_AUDIO_VOLUME) - 1)); - break; - - case XK_plus: - /* plus => next audio channel */ - xine_set_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL, - (xine_get_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL) + 1)); - break; - - case XK_minus: - /* minus => previous audio channel */ - xine_set_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL, - (xine_get_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL) - 1)); - break; - - case XK_space: - /* space => toggle pause mode */ - if (xine_get_param(stream, XINE_PARAM_SPEED) != XINE_SPEED_PAUSE) - xine_set_param(stream, XINE_PARAM_SPEED, XINE_SPEED_PAUSE); - else - xine_set_param(stream, XINE_PARAM_SPEED, XINE_SPEED_NORMAL); - break; - - } - } - break; - - case Expose: - /* this handles (partial) occlusion of our video window */ - if (xevent.xexpose.count != 0) - break; - xine_port_send_gui_data(vo_port, XINE_GUI_SEND_EXPOSE_EVENT, &xevent); - break; - - case ConfigureNotify: - { - XConfigureEvent *cev = (XConfigureEvent *) &xevent; - Window tmp_win; - - width = cev->width; - height = cev->height; - - if ((cev->x == 0) && (cev->y == 0)) { - XLockDisplay(display); - XTranslateCoordinates(display, cev->window, - DefaultRootWindow(cev->display), - 0, 0, &xpos, &ypos, &tmp_win); - XUnlockDisplay(display); - } else { - xpos = cev->x; - ypos = cev->y; - } - } - break; - - } - } - - /* cleanup */ - xine_close(stream); - xine_event_dispose_queue(event_queue); - xine_dispose(stream); - xine_close_audio_driver(xine, ao_port); - xine_close_video_driver(xine, vo_port); - xine_exit(xine); - - XLockDisplay(display); - XUnmapWindow(display, window[fullscreen]); - XDestroyWindow(display, window[0]); - XDestroyWindow(display, window[1]); - XUnlockDisplay(display); - - XCloseDisplay (display); - - return 0; -}</PRE -></TD -></TR -></TABLE -></DIV -></DIV -></DIV -><DIV -CLASS="CHAPTER" -><HR><H1 -><A -NAME="OVERVIEW" -></A ->Chapter 3. xine code overview</H1 -><DIV -CLASS="SECT1" -><H2 -CLASS="SECT1" -><A -NAME="AEN83" -></A ->Walking the source tree</H2 -><P -> The <TT -CLASS="FILENAME" ->src/</TT -> directory in xine-lib contains several - modules, this should give you a quick overview on where - to find what sources. - </P -><P -> Directories marked with "(imported)" contain - code that is copied from an external project into xine-lib. - Everything below such a directory is up to this project. When modifying - code there, be sure to send the patches on. - </P -><P -> <P -></P -><DIV -CLASS="VARIABLELIST" -><DL -><DT -><TT -CLASS="FILENAME" ->audio_out</TT -></DT -><DD -><P -> Audio output plugins. These provide a thin abstraction layer - around different types of audio output architectures or platforms. - Basically an audio output plugin provides functions to query and setup - the audio hardware and output audio data (e.g. PCM samples). - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->demuxers</TT -></DT -><DD -><P -> Demuxer plugins that handle various system layer file formats - like avi, asf or mpeg. The ideal demuxer know nothing about where the - data comes from and who decodes it. It should basically just unpack - it into chunks the rest of the engine can eat. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->dxr3</TT -></DT -><DD -><P -> Code to support the DXR3 / hollywood+ hardware mpeg decoder. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->input</TT -></DT -><DD -><P -> Input plugins encapsulate the origin of the data. Data sources like - ordinary files, DVDs, CDA or streaming media are handled here. - </P -><P -> <P -></P -><DIV -CLASS="VARIABLELIST" -><DL -><DT -><TT -CLASS="FILENAME" ->dvb</TT -></DT -><DD -><P -> Some headers for Digital Video Broadcast. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libdvdnav</TT -> (imported)</DT -><DD -><P -> The libdvdnav library for DVD navigation is used - by xine's DVD input plugin. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libreal</TT ->, <TT -CLASS="FILENAME" ->librtsp</TT -></DT -><DD -><P -> Support for RealMedia streaming as used by the RTSP input plugin. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->vcd</TT -></DT -><DD -><P -> The enhanced VCD input plugin which also handles VCD navigation. - </P -><P -> <P -></P -><DIV -CLASS="VARIABLELIST" -><DL -><DT -><TT -CLASS="FILENAME" ->libcdio</TT ->, <TT -CLASS="FILENAME" ->libvcd</TT -> (imported)</DT -><DD -><P -> Libraries used by the enhanced VCD plugin. - </P -><P -></P -></DD -></DL -></DIV -> - </P -><P -></P -></DD -></DL -></DIV -> - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->liba52</TT -> (imported)</DT -><DD -><P -> A52 (aka AC3, aka Dolby Digital) audio decoder library and xine plugin. - </P -><P -> We maintain some small integration improving differences between the - original liba52 and our copy in the file - <TT -CLASS="FILENAME" ->diff_against_release.patch</TT ->. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libdivx4</TT -></DT -><DD -><P -> Video decoder plugin using libdivx4linux if it is installed. - Currently unmaintained and soon to be discontinued if noone cares to take over. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libdts</TT -></DT -><DD -><P -> Audio decoder plugin that does currently nothing but passing through - DTS (AC5) data to the audio output plugin. This is only usefull - when using an external hardware DTS decoder. James has started to - work on software DTS decoding, but has not succeeded so far. Anyone - giving him a hand? - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libfaad</TT -> (imported)</DT -><DD -><P -> The Free AAC Decoder library and xine plugin. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libffmpeg</TT -></DT -><DD -><P -> A xine decoder plugin using various audio and video decoders from the - ffmpeg decoder pack libavcodec. Their MPEG encoder is also for the DXR3. - </P -><P -> To optimize the integration of libavcodec and the xine engine, we maintain - some differences between the original ffmpeg and our copy in the file - <TT -CLASS="FILENAME" ->diff_to_ffmpeg_cvs.txt</TT ->. - </P -><P -> <P -></P -><DIV -CLASS="VARIABLELIST" -><DL -><DT -><TT -CLASS="FILENAME" ->libavcodec</TT -> (imported)</DT -><DD -><P -> The libavcodec decoder pack as used by xine's ffmpeg plugin. - </P -><P -></P -></DD -></DL -></DIV -> - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libflac</TT -></DT -><DD -><P -> A xine demuxer and decoder plugin for the Free Lossless Audio Codec library, - which has to be installed separately. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->liblpcm</TT -></DT -><DD -><P -> Audio decoder plugin that "decodes" raw PCM data; most notably - endianess-conversions are done here. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libmad</TT -> (imported)</DT -><DD -><P -> Mpeg audio decoder plugin (i.e. mp2 and mp3 decoding). - ISO/IEC compliant decoder using fixed point math. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libmpeg2</TT -> (imported)</DT -><DD -><P -> Most important MPEG video decoder plugin, provides fast and - high-precision MPEG-1/2 video decoding. - </P -><P -> Although this is an imported library, we have heavily modified - our internal copy to blend it as seamlessly as possible into - the xine engine in order to get the maximum MPEG decoding - performance. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libmpeg2new</TT -></DT -><DD -><P -> James started an effort to bring a recent and unmodified version - of libmpeg2 into xine to one day replace our current internal - modified libmpeg2 with one closer to the original. But since - the full feature catalog has not yet been achieved with the new - one, it is still disabled. - </P -><P -> <P -></P -><DIV -CLASS="VARIABLELIST" -><DL -><DT -><TT -CLASS="FILENAME" ->include</TT ->, <TT -CLASS="FILENAME" ->libmpeg2</TT -> (imported)</DT -><DD -><P -> The code of the imported new libmpeg2. - </P -><P -></P -></DD -></DL -></DIV -> - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libmpg123</TT -> (imported)</DT -><DD -><P -> An MPEG audio decoder plugin baseg on mpg123 code. This plugin is disabled - because it is unmaintained. Some people said, it was faster than the libmad - decoder. But if noone starts to fix it, it will disappear soon. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libreal</TT -></DT -><DD -><P -> A thin wrapper around Real's binary codecs from the Linux RealPlayer to - use them as a xine plugin. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libspeex</TT -></DT -><DD -><P -> A xine decoder plugin for the speex library, - which has to be installed separately. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libspucc</TT -></DT -><DD -><P -> Closed caption subtitle decoder plugin. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libspudec</TT -></DT -><DD -><P -> DVD SPU subtitle decoder plugin. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libsputext</TT -></DT -><DD -><P -> Plain text subtitle decoder plugins. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libtheora</TT -></DT -><DD -><P -> A xine decoder plugin for the theora library, - which has to be installed separately. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libvorbis</TT -></DT -><DD -><P -> A xine decoder plugin for the ogg/vorbis library, - which has to be installed separately. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libw32dll</TT -></DT -><DD -><P -> Video and audio decoder plugins that exploit some wine code - to use win32 (media player and Quicktime) codecs in xine. - Works on x86 platforms only. - </P -><P -> <P -></P -><DIV -CLASS="VARIABLELIST" -><DL -><DT -><TT -CLASS="FILENAME" ->DirectShow</TT ->, <TT -CLASS="FILENAME" ->dmo</TT ->, - <TT -CLASS="FILENAME" ->qtx</TT ->, <TT -CLASS="FILENAME" ->wine</TT -> (imported)</DT -><DD -><P -> Stripped down version of wine to support Video for Windows DLLs - and additional code to use DirectShow, DMO and QuickTime DLLs. - </P -><P -></P -></DD -></DL -></DIV -> - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libxineadec</TT -></DT -><DD -><P -> xine's decoder pack of additional audio decoders. - </P -><P -> <P -></P -><DIV -CLASS="VARIABLELIST" -><DL -><DT -><TT -CLASS="FILENAME" ->gsm610</TT -> (imported)</DT -><DD -><P -> The gsm610 audio decoder library as used by the related xine plugin. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->nosefart</TT -> (imported)</DT -><DD -><P -> The nosefart audio decoder library as used by the related xine plugin. - </P -><P -></P -></DD -></DL -></DIV -> - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libxinevdec</TT -></DT -><DD -><P -> xine's decoder pack of additional video decoders. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->libxvid</TT -></DT -><DD -><P -> A xine decoder plugin for the xvid library, - which has to be installed separately. This plugin is - unmaintained and unless someone cares to update it, it will - be moved to the attic soon. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->post</TT -></DT -><DD -><P -> Video and audio post effect plugins live here. Post plugins - modify streams of video frames or audio buffers as they leave - the decoder to provide conversion or effects. - </P -><P -> <P -></P -><DIV -CLASS="VARIABLELIST" -><DL -><DT -><TT -CLASS="FILENAME" ->deinterlace</TT -> (imported)</DT -><DD -><P -> The tvtime deinterlacer as a xine video filter post. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->goom</TT -> (imported)</DT -><DD -><P -> The goom audio visualizer as a xine visualizer post. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->mosaico</TT -></DT -><DD -><P -> Some post plugins merging multiple frames into one. For example - picture in picture can be done with this. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->planar</TT -></DT -><DD -><P -> Some simple 2D video effects as xine video filter posts. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->visualizations</TT -></DT -><DD -><P -> Audio visualization post plugins. - </P -><P -></P -></DD -></DL -></DIV -> - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->video_out</TT -></DT -><DD -><P -> Contains various video output driver plugins. Video output drivers - are thin abstraction layers over various video output platforms - (e.g. X11, directfb, directX,...). Video output driver plugins - provide functions like frame allocation and drawing and handle - stuff like hardware acceleration, scaling and colorspace conversion - if necessary. They do not handle a/v sync since this is done - in the xine-engine already. - </P -><P -> <P -></P -><DIV -CLASS="VARIABLELIST" -><DL -><DT -><TT -CLASS="FILENAME" ->libdha</TT -> (imported)</DT -><DD -><P -> A library for direct hardware access to the graphics card - as used by the vidix video out plugin. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->vidix</TT -> (imported)</DT -><DD -><P -> The vidix system for high performance video output - as used by the vidix video out plugin. - </P -><P -></P -></DD -></DL -></DIV -> - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->xine-engine</TT -></DT -><DD -><P -> The heart of xine - it's engine. Contains code to - load and handle all the plugins, the configuration repository - as well as the generic decoding loops and code for synchronized output. - A lot of helper functions for plugins to use live here as well. - What's in the individual files should be guessable by the files' - names. This document is not going to explain the source, because - it simply changes too often. A look at the architectural drawing - in the <A -HREF="#INTERNALS" ->internals section</A -> should - give you a pretty good idea, what to expect in this directory. - Basically, everything in this picture that is not called "plugin" - lives here. - </P -><P -></P -></DD -><DT -><TT -CLASS="FILENAME" ->xine-utils</TT -></DT -><DD -><P -> Collection of utility functions and platform abstractions. - Also contains a simple XML parser for frontend playlist handling. - </P -><P -></P -></DD -></DL -></DIV -> - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN400" -></A ->Object oriented programming in C</H2 -><P -> xine uses a lot of design principles normally found in - object oriented designs. As xine is written in c, a few - basic principles shall be explained here on how xine - is object oriented anyway. - </P -><P -> Classes are structs containing function pointers and public member data. - Example: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> typedef struct my_stack_s my_class_t; - - struct my_stack_s { - /* method "push" with one parameter and no return value */ - void (*push)(my_stack_t *this, int i); - - /* method "add" with no parameters and no return value */ - void (*add)(my_stack_t *this); - - /* method "pop" with no parameters (except "this") and a return value */ - int (*pop) (my_stack_t *this); - }; - - /* constructor */ - my_class_t *new_my_stack(void);</PRE -></TD -></TR -></TABLE -> - </P -><P -> To derive from such a class, private member variables can be added: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> typedef struct { - my_stack_t stack; /* public part */ - - /* private part follows here */ - int values[MAX_STACK_SIZE]; - int stack_size; - } intstack_t;</PRE -></TD -></TR -></TABLE -> - Each method is implemented as a static method (static to prevent - namespace pollution). The "this" pointer needs to be cast to the - private pointer type to gain access to the private member variables. - </P -><P -> Implementation of the "push" method follows: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> static void push (my_stack_t *this_gen, int i) { - intstack_t *this = (intstack_t *)this_gen; - this->values[MAX_STACK_SIZE - ++this->stack_size] = i; - }</PRE -></TD -></TR -></TABLE -> - </P -><P -> Finally the contructor malloc()s the data struct (private variant) - and fills in function pointers and default values. Usually the - constructor is the only public (i.e. non-static) function in the module: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> my_stack_t *new_my_stack(void) { - intstack_t *this; - - /* alloc memory */ - this = malloc(sizeof(intstack_t)); - - /* fill in methods */ - this->push = push; - this->add = add; - this->pop = pop; - - /* init data fields */ - this->stack_size = 0; - - /* return public part */ - return &this->stack; - }</PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN411" -></A ->Coding style and guidelines</H2 -><P -> This section contains some guidelines for writing xine-code. - These are really just guidelines, no strict rules. - Contributions will not be rejected if they do not meet these - rules but they will be even more appreciated if they do. - <P -></P -><UL -><LI -><P -> Comment your interfaces directly in the header files. - No doxygen comments, ordinary C comments will do. - </P -></LI -><LI -><P -> Use C-style comments (/* */), not C++-style (//). - </P -></LI -><LI -><P -> When in doubt, use lower case. BTW: This thing is called xine, never Xine. - </P -></LI -><LI -><P -> Use expressive variable and function identifiers on all public interfaces. - Use underscores to seperate words in identifiers, not uppercase - letters (my_function_name is ok, myFunctionName is not ok). - </P -></LI -><LI -><P -> Avoid macros unless they are really useful. Avoid gotos. - </P -></LI -><LI -><P -> use something like - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> printf("module: ..."[,...]);</PRE -></TD -></TR -></TABLE -> - for console output. All console output goes to stdout and - must be prefixed by the module name which generates the - output (see example above). - </P -></LI -><LI -><P -> Refer to emac's C-mode for all questions of proper indentiation. - That first of all means: indent with two spaces. - </P -></LI -></UL -> - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN430" -></A ->The xine logging system</H2 -><P -> xine offers a wide range of possibilities to display - strings. This section should describe when to use - which way and how to do it right. - </P -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN433" -></A ->xine_log</H3 -><P -> Output which is done thru this function will be - displayed for the end user by the frontend. - If <TT -CLASS="VARNAME" ->xine->verbosity</TT -> is not 0 the messages will also - be displayed on the console. Ideally these strings - are translated. - This function is for information which the user should - read always. - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> xine_log(xine_t *xine, int buf, const char *format, ...);</PRE -></TD -></TR -></TABLE -> - <TT -CLASS="VARNAME" ->buf</TT -> is either XINE_LOG_MSG for general messages or - XINE_LOG_PLUGIN for messages about plugins. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN439" -></A ->xprintf</H3 -><P -> This macro uses the <TT -CLASS="VARNAME" ->xine->verbosity</TT -> value to decide - if the string should be printed to the console. Possible - values are XINE_VERBOSITY_NONE, XINE_VERBOSITY_LOG or - XINE_VERBOSITY_DEBUG. By default nothing is printed. - When you use xine-ui you can enable this output with - the <TT -CLASS="PARAMETER" -><I ->--verbose=[1,2]</I -></TT -> options. - This function should be used for information which the - user should only read up on request. - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> xprintf(xine_t *xine, int verbosity, const char *format, ...);</PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN445" -></A ->lprintf/llprintf</H3 -><P -> These macros are for debugging purpose only. Under normal - circumstances it is disabled. And can only be enabled by changing - a define statement and a recompilation. It has to be enabled for these - files that are of interest. - It should only be used for information which is intended for developers. - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> lprintf(const char *format, ...); - llprintf(bool, const char *format, ...);</PRE -></TD -></TR -></TABLE -> - <TT -CLASS="VARNAME" ->bool</TT -> is a flag which enables or disables this logging. - </P -><P -> <TT -CLASS="FUNCTION" ->lprintf</TT -> can be enabled by defining LOG at the top of the source file. - <TT -CLASS="FUNCTION" ->llprintf</TT -> can be used for more than one categorie - per file by using diffent lables: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> #define LOG_LOAD 1 - #define LOG_SAVE 0 - - llprintf(LOG_LOAD, "loading was successful\n"); - llprintf(LOG_SAVE, "could not save to file %s\n", filename);</PRE -></TD -></TR -></TABLE -> - </P -><P -> In this case only the first messages is printed. To enable/disable change the defines. - </P -><P -> LOG_MODULE should be used to set the modulename for xprintf/lprintf/llprintf. - Each output line will start with "modulename: ". - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> #define LOG_MODULE "modulename"</PRE -></TD -></TR -></TABLE -> - </P -><P -> LOG_VERBOSE can be defined to enable the logging of functionname and linenumbers. - Then the output will be: "modulename: (function_name:42) message". - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN458" -></A ->How to contribute</H2 -><P -> Make sure you send your patches in unified diff format to - the xine-devel mailing list. You'll have to subscribe first, - otherwise you're not allowed to post. Please do not send - patches to individual developers unless instructed otherwise - because your patch is more likely to get lost in an overfull - INBOX in that case. Please be patient, it may take 1-2 weeks - before you hear any comments on your work (developers may be - working on other parts of the code or are simply busy at - the moment). - </P -></DIV -></DIV -><DIV -CLASS="CHAPTER" -><HR><H1 -><A -NAME="INTERNALS" -></A ->Chapter 4. xine internals</H1 -><DIV -CLASS="SECT1" -><H2 -CLASS="SECT1" -><A -NAME="AEN463" -></A ->Engine architecture and data flow</H2 -><DIV -CLASS="MEDIAOBJECT" -><P -><IMG -SRC="architecture.png"><DIV -CLASS="CAPTION" -><P ->xine engine architecture</P -></DIV -></P -></DIV -><P -> Media streams usually consist of audio and video data multiplexed - into one bitstream in the so-called system-layer (e.g. AVI, Quicktime or MPEG). - A demuxer plugin is used to parse the system layer and extract audio and video - packages. The demuxer uses an input plugin to read the data and stores it - in pre-allocated buffers from the global buffer pool. - The buffers are then added to the audio or video stream fifo. - </P -><P -> From the other end of these fifos the audio and video decoder threads - consume the buffers and hand them over to the current audio or video - decoder plugin for decompression. These plugins then send the decoded - data to the output layer. The buffer holding the encoded - data is no longer needed and thus released to the global buffer pool. - </P -><P -> In the output layer, the video frames and audio samples pass through a - post plugin tree, which can apply effects or other operations to the data. - When reaching the output loops, frames and samples are enqueued to be - displayed, when the presentation time has arrived. - </P -><P -> A set of extra information travels with the data. Starting at the input and - demuxer level, where this information is generated, the data is attached to - the buffers as they wait in the fifo. The decoder loops copy the data to - a storage of their own. From there, every frame and audio buffer leaving - the stream layer is tagged with the data the decoder loop storage currently - holds. - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN476" -></A ->Plugin system</H2 -><P -> The plugin system enables some of xine's most valuable features: - <P -></P -><UL -><LI -><P -> drop-in extensiability - </P -></LI -><LI -><P -> support parallel installation of multiple (incompatible) libxine versions - </P -></LI -><LI -><P -> support for multiple plugin directories - (<TT -CLASS="FILENAME" ->$prefix/lib/xine/plugins</TT ->, - <TT -CLASS="FILENAME" ->$HOME/.xine/plugins</TT ->, ...) - </P -></LI -><LI -><P -> support for recursive plugin directories - (plugins are found even in subdirectories of the plugin directories) - </P -></LI -><LI -><P -> version management - (On start, xine finds all plugins in its plugin (sub)directories and - chooses an appropriate version (usually the newest) for each plugin.) - </P -></LI -><LI -><P -> simplification - (Plugins don't have to follow any special naming convention, - and any plugin may contain an arbitrary subset of input, demuxer, - decoder or output plugins.) - </P -></LI -></UL -> - </P -><P -> Essentally, plugins are just shared objects, ie dynamic libraries. In - contrast to normal dynamic libraries, they are stored outside of the - system's library PATHs and libxine does its own bookkeeping, which - enables most advanced features mentioned above. - </P -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN495" -></A ->Plugin location and filesystem layout</H3 -><P -> The primary goal for this new plugin mechanism was the need to support - simultaneous installation of several (most likely incompatible) - libxine versions without them overwriting each other's - plugins. Therefore, we have this simple layout: - </P -><P -> Plugins are installed below XINE_PLUGINDIR - (<TT -CLASS="FILENAME" ->/usr/local/lib/xine/plugins</TT -> by default). - Note that plugins are never directly installed into XINE_PLUGINDIR. - Instead, a separate subdirectory is created for each "plugin - provider". A plugin provider is equivalent with the exact version of - one source package. Typical examples include "xine-lib-0.9.11" or - "xine-vcdnav-1.0". Every source package is free to install an - arbitrary number of plugins in its own, private directory. If a - package installs several plugins, they may optionally be organized - further into subdirectories. - </P -><P -> So you will finally end up with something like this: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="SCREEN" -> /usr/local/lib/xine/plugins - xine-lib-0.9.11 - demux_mpeg_block.so - decode_mpeg.so - video_out_xv.so - ... - xine-vcdnav-0.9.11 - input_vcdnav.so - xine-lib-1.2 - input - file.so - stdin_fifo.so - vcd.so - demuxers - fli.so - avi.so - ... - decoders - ffmpeg.so - mpeg.so (may contain mpeg 1/2 audio and video decoders) - pcm.so - ... - output - video_xv.so - audio_oss.so - ... - xine-lib-3.0 - avi.so (avi demuxer) - mpeg.so (contains mpeg demuxers and audio/video decoders) - video_out_xv.so (Xv video out) - ...</PRE -></TD -></TR -></TABLE -> - </P -><P -> As you can see, every package is free to organize plugins at will - below its own plugin provider directory. - Additionally, administrators may choose to put plugins directly into - XINE_PLUGINDIR, or in a "local" subdirectory. - Users may wish to put additional plugins in ~/.xine/plugins/. - Again, there may be subdirectories to help organize the plugins. - </P -><P -> The default value for XINE_PLUGINDIR can be obtained using the - <B -CLASS="COMMAND" ->xine-config --plugindir</B -> command. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN505" -></A ->Plugin Content: What's inside the .so?</H3 -><P -> Each plugin library (.so file) contains an arbitrary number of (virtual) - plugins. Typically, it will contain exactly one plugin. However, it - may be useful to put a set of related plugins in one library, so they - can share common code. - </P -><P -> First of all, what is a virtual plugin? - A virtual plugin is essentially a structure that is defined by the - xine engine. This structure typically contains lots of function - pointers to the actual API functions. - For each plugin API, there are several API versions, and each API - version may specify a new, incompatible structure. Therefore, it is - essential that only those plugins are loaded that support current - libxine's API, so the .so file needs a plugin list that - provides libxine with the version information, even before it tries to - load any of the plugins. - </P -><P -> This plugin list is held in an array named <TT -CLASS="VARNAME" ->xine_plugin_info</TT ->": - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> plugin_info_t xine_plugin_info[] = { - /* type, API, "name", version, special_info, init_function */ - { PLUGIN_DEMUX, 20, "flac", XINE_VERSION_CODE, NULL, demux_flac_init_class }, - { PLUGIN_AUDIO_DECODER, 13, "flacdec", XINE_VERSION_CODE, &dec_info_audio, init_plugin }, - { PLUGIN_NONE, 0, "", 0, NULL, NULL } - };</PRE -></TD -></TR -></TABLE -> - </P -><P -> The structure of xine_plugin_info may <SPAN -CLASS="emphasis" -><I -CLASS="EMPHASIS" ->never</I -></SPAN -> be changed. - If it ever needs to be changed, it must be renamed to avoid - erraneous loading of incompatible plugins. - </P -><P -> <TT -CLASS="VARNAME" ->xine_plugin_info</TT -> can contain any number of plugins - and must be terminated with a <SPAN -CLASS="TYPE" ->PLUGIN_NONE</SPAN -> entry. Available plugin - types are: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> #define PLUGIN_NONE 0 - #define PLUGIN_INPUT 1 - #define PLUGIN_DEMUX 2 - #define PLUGIN_AUDIO_DECODER 3 - #define PLUGIN_VIDEO_DECODER 4 - #define PLUGIN_SPU_DECODER 5 - #define PLUGIN_AUDIO_OUT 6 - #define PLUGIN_VIDEO_OUT 7 - #define PLUGIN_POST 8</PRE -></TD -></TR -></TABLE -> - </P -><P -> The plugin version number is generated from xine-lib's version number - like this: MAJOR * 10000 + MINOR * 100 + SUBMINOR. - This is not required, but it's an easy way to ensure that the version - increases for every release. - </P -><P -> Every entry in <TT -CLASS="VARNAME" ->xine_plugin_info</TT -> has an initialization - function for the plugin class context. - This function returns a pointer to freshly allocated (typically - via <TT -CLASS="FUNCTION" ->malloc()</TT ->) structure containing mainly function - pointers; these are the "methods" of the plugin class. - </P -><P -> The "plugin class" is not what we call to do the job yet (like decoding - a video or something), it must be instantiated. One reason for having the - class is to hold any global settings that must be accessed by every - instance. Remember that xine library is multistream capable: multible - videos can be decoded at the same time, thus several instances of the - same plugin are possible. - </P -><P -> If you think this is pretty much an object-oriented aproach, - then you're right. - </P -><P -> A fictitious file input plugin that supports input plugin API 12 and - 13, found in xine-lib 2.13.7 would then define this plugin list: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> #include <xine/plugin.h> - ... - plugin_t *init_api12(void) { - input_plugin_t *this; - - this = malloc(sizeof(input_plugin_t)); - ... - return (plugin_t *)this; - } - /* same thing, with different initialization for API 13 */ - - const plugin_info_t xine_plugin_info[] = { - { PLUGIN_INPUT, 12, "file", 21307, init_api12 }, - { PLUGIN_INPUT, 13, "file", 21307, init_api13 }, - { PLUGIN_NONE, 0, "", 0, NULL } - }</PRE -></TD -></TR -></TABLE -> - This input plugin supports two APIs, other plugins might provide a - mixture of demuxer and decoder plugins that belong together somehow - (ie. share common code). - </P -><P -> You'll find exact definitions of public functions and plugin structs - in the appropriate header files for each plugin type: - <TT -CLASS="FILENAME" ->input/input_plugin.h</TT -> for input plugins, - <TT -CLASS="FILENAME" ->demuxers/demux.h</TT -> for demuxer plugins, - <TT -CLASS="FILENAME" ->xine-engine/video_decoder.h</TT -> for video decoder plugins, - <TT -CLASS="FILENAME" ->xine-engine/audio_decoder.h</TT -> for audio decoder plugins, - <TT -CLASS="FILENAME" ->xine-engine/post.h</TT -> for post plugins, - <TT -CLASS="FILENAME" ->xine-engine/video_out.h</TT -> for video out plugins, - <TT -CLASS="FILENAME" ->xine-engine/audio_out.h</TT -> for audio out plugins. - Additional information will also be given in the dedicated sections below. - </P -><P -> Many plugins will need some additional "private" data fields. - These should be simply added at the end of the plugin structure. - For example a demuxer plugin called "foo" with two private - fields "xine" and "count" may have a plugin structure declared in - the following way: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> typedef struct { - /* public fields "inherited" from demux.h */ - demux_plugin_t demux_plugin; - - xine_t *xine; - int count; - } demux_foo_t;</PRE -></TD -></TR -></TABLE -> - </P -><P -> The plugin would then access public members via the - <TT -CLASS="VARNAME" ->demux_plugin</TT -> field and private fields directly. - </P -><P -> Summary: Plugins consist of two C-style classes, each representing a different context. - <P -></P -><UL -><LI -><P -> The first is the so called "plugin class" context. This is a singleton context, - which means it will exist either not at all or at most once per xine context. - This plugin class context is a C-style class which is subclassing the related - class from the xine plugin headers. This contains functions, which are - independent of the actual instance of the plugin. Most prominently, it contains - a factory method to instantiate the next context. - </P -></LI -><LI -><P -> The second context is the instance context. This is another C-style class, which - is constructed and disposed withing the plugin class context. This one does - the actual work and subclasses the related plugin struct from the xine plugin - headers. It is instantiated for every separate running instance of the plugin - </P -></LI -></UL -> - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN544" -></A ->What is this metronom thingy?</H2 -><P -> Metronom serves two purposes: - <P -></P -><UL -><LI -><P -> Generate vpts (virtual presentation time stamps) from pts (presentation time stamps) - for a/v output and synchronization. - </P -></LI -><LI -><P -> Provide a master clock (system clock reference, scr), possibly provided - by external scr plugins (this can be used if some hardware decoder or network - server dictates the time). - </P -></LI -></UL -> - </P -><P -> pts/vpts values are given in 1/90000 sec units. pts values in mpeg streams - may wrap (that is, return to zero or any other value without further notice), - can be missing on some frames or (for broken streams) may "dance" around - the correct values. Metronom therefore has some heuristics built-in to generate - clean vpts values which can then be used in the output layers to schedule audio/video - output. - </P -><P -> The heuristics used in metronom have always been a field of research. Current metronom's - implementation <SPAN -CLASS="emphasis" -><I -CLASS="EMPHASIS" ->tries</I -></SPAN -> to stick to pts values as reported from demuxers, - that is, vpts may be obtained by a simple operation of vpts = pts + <TT -CLASS="VARNAME" ->vpts_offset</TT ->, - where <TT -CLASS="VARNAME" ->vpts_offset</TT -> takes into account any wraps. Whenever pts is zero, - metronom will estimate vpts based on previous values. If a difference is found between the - estimated and calculated vpts values by above formula, it will be smoothed by using a - "drift correction". - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN557" -></A ->How does xine synchronize audio and video?</H2 -><P -> Every image frame or audio buffer leaving decoder is tagged by metronom with - a vpts information. This will tell video_out and audio_out threads when that - data should be presented. Usually there isn't a significative delay associated - with video driver, so we expect it to get on screen at the time it's - delivered for drawing. Unfortunately the same isn't true for audio: all sound - systems implement some amount of buffering (or fifo), any data being send to it - <SPAN -CLASS="emphasis" -><I -CLASS="EMPHASIS" ->now</I -></SPAN -> will only get played some time in future. audio_out thread - must take this into account for making perfect A-V sync by asking the sound latency - to audio driver. - </P -><P -> Some audio drivers can't tell the current delay introduced in playback. This is - especially true for most sound servers like ESD or aRts and explain why in such - cases the sync is far from perfect. - </P -><P -> Another problem xine must handle is the sound card clock drift. vpts are - compared to the system clock (or even to a different clock provided by a scr plugin) - for presentation but sound card is sampling audio by it's own clocking - mechanism, so a small drift may occur. As the playback goes on this - error will accumulate possibly resulting in audio gaps or audio drops. To avoid that - annoying effect, two countermeasures are available (switchable with xine config - option <TT -CLASS="PARAMETER" -><I ->audio.av_sync_method</I -></TT ->): - <P -></P -><UL -><LI -><P -> The small sound card errors are feedbacked to metronom. The details - are given by <TT -CLASS="FILENAME" ->audio_out.c</TT -> comments: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> /* By adding gap errors (difference between reported and expected - * sound card clock) into metronom's vpts_offset we can use its - * smoothing algorithms to correct sound card clock drifts. - * obs: previously this error was added to xine scr. - * - * audio buf ---> metronom --> audio fifo --> (buf->vpts - hw_vpts) - * (vpts_offset + error) gap - * <---------- control --------------| - * - * Unfortunately audio fifo adds a large delay to our closed loop. - * - * These are designed to avoid updating the metronom too fast. - * - it will only be updated 1 time per second (so it has a chance of - * distributing the error for several frames). - * - it will only be updated 2 times for the whole audio fifo size - * length (so the control will wait to see the feedback effect) - * - each update will be of gap/SYNC_GAP_RATE. - * - * Sound card clock correction can only provide smooth playback for - * errors < 1% nominal rate. For bigger errors (bad streams) audio - * buffers may be dropped or gaps filled with silence. - */</PRE -></TD -></TR -></TABLE -> - </P -></LI -><LI -><P -> The audio is stretched or squeezed a slight bit by resampling, thus compensating - the drift: The next comment in <TT -CLASS="FILENAME" ->audio_out.c</TT -> explains: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="90%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> /* Alternative for metronom feedback: fix sound card clock drift - * by resampling all audio data, so that the sound card keeps in - * sync with the system clock. This may help, if one uses a DXR3/H+ - * decoder board. Those have their own clock (which serves as xine's - * master clock) and can only operate at fixed frame rates (if you - * want smooth playback). Resampling then avoids A/V sync problems, - * gaps filled with 0-frames and jerky video playback due to different - * clock speeds of the sound card and DXR3/H+. - */</PRE -></TD -></TR -></TABLE -> - </P -></LI -></UL -> - </P -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="OSD" -></A ->Overlays and OSD</H2 -><P -> The roots of xine overlay capabilities are DVD subpictures and subtitles support - (also known as 'spu'). The DVD subtitles are encoded in a RLE (Run Length Encoding - the - most simple compressing technique) format, with a palette of colors and transparency - levels. You probably thought that subtitles were just simple text saved into DVDs, right? - Wrong, they are bitmaps. - </P -><P -> In order to optimize to the most common case, xine's internal format for screen overlays - is a similar representation to the 'spu' data. This brings not only performance - benefit (since blending functions may skip large image areas due to RLE) but also - compatibility: it's possible to reencode any xine overlay to the original spu format - for displaying with mpeg hardware decoders like DXR3. - </P -><P -> Displaying subtitles requires the ability to sync them to the video stream. This - is done using the same kind of pts/vpts stuff of a-v sync code. DVD subtitles, - for example, may request: show this spu at pts1 and hide it at pts2. This brings the - concept of the 'video overlay manager', that is a event-driven module for managing - overlay's showing and hiding. - </P -><P -> The drawback of using internal RLE format is the difficulty in manipulating it - as graphic. To overcome that we created the 'OSD renderer', where OSD stands - for On Screen Display just like in TV sets. The osd renderer is a module - providing simple graphic primitives (lines, rectagles, draw text etc) over - a "virtual" bitmap area. Everytime we want to show that bitmap it will - be RLE encoded and sent to the overlay manager for displaying. - </P -><DIV -CLASS="MEDIAOBJECT" -><P -><IMG -SRC="overlays.png"><DIV -CLASS="CAPTION" -><P ->overlays architecture</P -></DIV -></P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN586" -></A ->Overlay Manager</H3 -><P -> The overlay manager interface is available to any xine plugin. It's a bit unlikely - to be used directly, anyway here's a code snippet for enqueueing an overlay for - displaying: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> video_overlay_event_t event; - - event.object.handle = this->video_overlay->get_handle(this->video_overlay,0); - - memset(this->event.object.overlay, 0, sizeof(*this->event.object.overlay)); - - /* set position and size for this overlay */ - event.object.overlay->x = 0; - event.object.overlay->y = 0; - event.object.overlay->width = 100; - event.object.overlay->height = 100; - - /* clipping region is mostly used by dvd menus for highlighting buttons */ - event.object.overlay->clip_top = 0; - event.object.overlay->clip_bottom = image_height; - event.object.overlay->clip_left = 0; - event.object.overlay->clip_right = image_width; - - /* the hard part: provide a RLE image */ - event.object.overlay->rle = your_rle; - event.object.overlay->data_size = your_size; - event.object.overlay->num_rle = your_rle_count; - - /* palette must contain YUV values for each color index */ - memcpy(event.object.overlay->clip_color, color, sizeof(color)); - - /* this table contains transparency levels for each color index. - 0 = completely transparent, 15 - completely opaque */ - memcpy(event.object.overlay->clip_trans, trans, sizeof(trans)); - - /* set the event type and time for displaying */ - event.event_type = EVENT_SHOW_SPU; - event.vpts = 0; /* zero is a special vpts value, it means 'now' */ - video_overlay->add_event(video_overlay, &event);</PRE -></TD -></TR -></TABLE -> - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN590" -></A ->OSD Renderer</H3 -><P -> OSD is a general API for rendering stuff over playing video. It's available both - to xine plugins and to frontends. - </P -><P -> The first thing you need is to allocate a OSD object for drawing from the - renderer. The code below allocates a 300x200 area. This size can't be changed - during the lifetime of a OSD object, but it's possible to place it anywhere - over the image. - </P -><TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> osd_object_t osd; - - osd = this->osd_renderer->new_object(osd_renderer, 300, 200);</PRE -></TD -></TR -></TABLE -><P -> Now we may want to set font and color for text rendering. Although we will - refer to fonts over this document, in fact the OSD can be any kind of bitmap. Font - files are searched and loaded during initialization from - <TT -CLASS="FILENAME" ->$prefix/share/xine/fonts/</TT -> and <TT -CLASS="FILENAME" ->~/.xine/fonts</TT ->. - There's a sample utility to convert truetype fonts at - <TT -CLASS="FILENAME" ->xine-lib/misc/xine-fontconv.c</TT ->. Palette may be manipulated directly, - however most of the time it's convenient to use pre-defined text palettes. - </P -><TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> /* set sans serif 24 font */ - osd_renderer->set_font(osd, "sans", 24); - - /* copy pre-defined colors for white, black border, transparent background to - starting at the index used by the first text palette */ - osd_renderer->set_text_palette(osd, TEXTPALETTE_WHITE_BLACK_TRANSPARENT, OSD_TEXT1); - - /* copy pre-defined colors for white, no border, translucid background to - starting at the index used by the second text palette */ - osd_renderer->set_text_palette(osd, TEXTPALETTE_WHITE_NONE_TRANSLUCID, OSD_TEXT2);</PRE -></TD -></TR -></TABLE -><P -> Now render the text and show it: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> osd_renderer->render_text(osd, 0, 0, "white text, black border", OSD_TEXT1); - osd_renderer->render_text(osd, 0, 30, "white text, no border", OSD_TEXT2); - - osd_renderer->show(osd, 0); /* 0 stands for 'now' */</PRE -></TD -></TR -></TABLE -> - </P -><P -> There's a 1:1 mapping between OSD objects and overlays, therefore the - second time you send an OSD object for displaying it will actually substitute - the first image. By using set_position() function we can move overlay - over the video. - </P -><TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> for( i=0; i < 100; i+=10 ) { - osd_renderer->set_position(osd, i, i ); - osd_renderer->show(osd, 0); - sleep(1); - } - osd_renderer->hide(osd, 0);</PRE -></TD -></TR -></TABLE -><P -> For additional functions please check osd.h or the public header. - </P -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="AEN605" -></A ->OSD palette notes</H4 -><P -> The palette functions demand some additional explanation, skip this if you - just want to write text fast without worring with details! :) - </P -><P -> We have a 256-entry palette, each one defining yuv and transparency levels. - Although xine fonts are bitmaps and may use any index they want, we have - defined a small convention: - </P -><TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> /* - Palette entries as used by osd fonts: - - 0: not used by font, always transparent - 1: font background, usually transparent, may be used to implement - translucid boxes where the font will be printed. - 2-5: transition between background and border (usually only alpha - value changes). - 6: font border. if the font is to be displayed without border this - will probably be adjusted to font background or near. - 7-9: transition between border and foreground - 10: font color (foreground) - */</PRE -></TD -></TR -></TABLE -><P -> The so called 'transitions' are used to implement font anti-aliasing. That - convention requires that any font file must use only the colors from 1 to 10. - When we use the set_text_palette() function we are just copying 11 palette - entries to the specified base index. - </P -><P -> That base index is the same we pass to render_text() function to use the - text palette. With this scheme is possible to have several diferent text - colors at the same time and also draw fonts over custom background. - </P -><TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> /* obtains size the text will occupy */ - renderer->get_text_size(osd, text, &width, &height); - - /* draws a box using font background color (translucid) */ - renderer->filled_rect(osd, x1, y1, x1+width, y1+height, OSD_TEXT2 + 1); - - /* render text */ - renderer->render_text(osd, x1, y1, text, OSD_TEXT2);</PRE -></TD -></TR -></TABLE -></DIV -><DIV -CLASS="SECT3" -><HR><H4 -CLASS="SECT3" -><A -NAME="AEN613" -></A ->OSD text and palette FAQ</H4 -><P -> Q: What is the format of the color palette entries? - </P -><P -> A: It's the same as used by overlay blending code (YUV). - </P -><P -> Q: What is the relation between a text palette and a palette - I set with xine_osd_set_palette? - </P -><P -> A: xine_osd_set_palette will set the entire 256 color palette - to be used when we blend the osd image. - "text palette" is a sequence of 11 colors from palette to be - used to render text. that is, by calling osd_render_text() - with color_base=100 will render text using colors 100-110. - </P -><P -> Q: Can I render text with colors in my own palette? - </P -><P -> A: Sure. Just pass the color_base to osd_render_text() - </P -><P -> Q: Has a text palette change effects on already drawed text? - </P -><P -> A: osd_set_text_palette() will overwrite some colors on palette - with pre-defined ones. So yes, it will change the color - on already drawed text (if you do it before calling osd_show, - of course). - If you don't want to change the colors of drawed text just - use different color_base values. - </P -><P -> Q: What about the shadows of osd-objects? Can I turn them off - or are they hardcoded? - </P -><P -> A: osd objects have no shadows by itself, but fonts use 11 - colors to produce an anti-aliased effect. - if you set a "text palette" with entries 0-9 being transparent - and 10 being foreground you will get rid of any borders or - anti-aliasing. - </P -></DIV -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN625" -></A ->MRLs</H2 -><P -> This section defines a draft for a syntactic specification of MRLs as - used by xine-lib. The language of MRLs is designed to be a true subset - of the language of URIs as given in RFC2396. A type 2 grammar for the - language of MRLs is given in EBNF below. - </P -><P -> Semantically, MRLs consist of two distinct parts that are evaluated by - different components of the xine architecture. The first part, - derivable from the symbol <input_source> in the given grammar, is - completely handed to the input plugins, with input plugins signaling - if they can handle the MRL. - </P -><P -> The second part, derivable from <stream_setup> and delimited from the - first by a crosshatch ('#') contains parameters that modify the - initialization and playback behaviour of the stream to which the MRL - is passed. The possible parameters are mentioned in the manpage to - xine-ui. - </P -><P -> The following definition should be regarded as a guideline only. - Of course any given input plugin only understands a subset of all - possible MRLs. On the other hand, invalid MRLs according to this - definition might be understood for convenience reasons. - Some user awareness is required at this point. - </P -><P -> EBNF grammar for MRLs: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> <mrl> ::= <input_source>[#<stream_setup>] - <input_source> ::= (<absolute_mrl>|<relative_mrl>) - <absolute_mrl> ::= <input>:(<net_path>|<abs_path>)[?<query>] - <relative_mrl> ::= (<abs_path>|<rel_path>) - <net_path> ::= //<authority>[<abs_path>] - <abs_path> ::= /<path_segments> - <rel_path> ::= <rel_segment>[<abs_path>] - <rel_segment> ::= <rel_char>{<rel_char>} - <rel_char> ::= (<unreserved>|<escaped>|;|@|&|=|+|$|,) - <input> ::= <alpha>{(<alpha>|<digit>|+|-|.)} - <authority> ::= (<server>|<reg_name>) - <server> ::= [[<userinfo>@]<host>[:<port>]] - <userinfo> ::= {(<unreserved>|<escaped>|;|:|&|=|+|$|,)} - <host> ::= (<hostname>|<ipv4_address>) - <hostname> ::= {<domainlabel>.}<toplabel>[.] - <domainlabel> ::= (<alphanum>|<alphanum>{(<alphanum>|-)}<alphanum>) - <toplabel> ::= (<alpha>|<alpha>{(<alphanum>|-)}<alphanum>) - <ipv4_address> ::= <digit>{<digit>}.<digit>{<digit>}.<digit>{<digit>}.<digit>{<digit>} - <port> ::= {<digit>} - <reg_name> ::= <reg_char>{<reg_char>} - <reg_char> ::= (<unreserved>|<escaped>|;|:|@|&|=|+|$|,) - <path_segments> ::= <segment>{/<segment>} - <segment> ::= {<path_char>}{;<param>} - <param> ::= {<path_char>} - <path_char> ::= (<unreserved>|<escaped>|:|@|&|=|+|$|,) - <query> ::= {<mrl_char>} - <stream_setup> ::= <stream_option>;{<stream_option>} - <stream_option> ::= (<configoption>|<engine_option>|novideo|noaudio|nospu) - <configoption> ::= <configentry>:<configvalue> - <configentry> ::= <unreserved>{<unreserved>} - <configvalue> ::= <conf_char>{<conf_char>} - <engine_option> ::= <unreserved>{<unreserved>}:<stream_char>{<stream_char>} - <stream_char> ::= (<unreserved>|<escaped>|:|@|&|=|+|$|,) - <mrl_char> ::= (<reserved>|<unreserved>|<escaped>) - <reserved> ::= (;|/|?|:|@|&|=|+|$|,) - <unreserved> ::= (<alphanum>|<mark>) - <mark> ::= (-|_|.|!|~|*|'|(|)) - <escaped> ::= %<hex><hex> - <hex> ::= (<digit>|A|B|C|D|E|F|a|b|c|d|e|f) - <alphanum> ::= (<alpha>|<digit>) - <alpha> ::= (<lowalpha>|<upalpha>) - <lowalpha> ::= (a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z) - <upalpha> ::= (A|B|C|D|E|F|G|H|I|J|K|L|M|N|O|P|Q|R|S|T|U|V|W|X|Y|Z) - <digit> ::= (0|1|2|3|4|5|6|7|8|9)</PRE -></TD -></TR -></TABLE -> - </P -></DIV -></DIV -><DIV -CLASS="CHAPTER" -><HR><H1 -><A -NAME="STREAM" -></A ->Chapter 5. xine's stream layer</H1 -><DIV -CLASS="SECT1" -><H2 -CLASS="SECT1" -><A -NAME="AEN635" -></A ->Input layer</H2 -><P -> Many media players expect streams to be stored within files on - some local medium. In actual fact, media may be streamed over a - network (e.g. via HTTP or RTP), encoded onto a specialized medium - (e.g. DVD), etc. To allow you to access all this media, xine supports - the concept of an "input plugin". The tasks performed by an - input plugin are: - <P -></P -><UL -><LI -><P -> Validation of Media Resource Locators (MRLs). - </P -></LI -><LI -><P -> MRL specific session management (e.g. opening and closing local files). - </P -></LI -><LI -><P -> Reading blocks/specific numbers of bytes from the input device. - </P -></LI -></UL -> - </P -><P -> In addition to these tasks, the input plugin may keep track of some - input device-specific state information (e.g. a DVD plugin may keep - track of navigational state data such as current title/chapter). - </P -><P -> There are two classes of input device which xine recognizes. - Byte-oriented devices can, upon request, return an arbitary - non-zero number of bytes from a stream. Examples of such devices - are files or network streams. Block-oriented devices, however, have - a prefered block or "frame"-size. An example of such a device is - a DVD where data is stored in logical blocks of 2048 bytes. One may - pass the hint to xine that the plugin is block-oriented by setting the - INPUT_CAP_BLOCK capability. Note that this is only a hint and - xine does not guarantee that all requests to the plugin will - be purely block based. - </P -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN647" -></A ->Writing a xine input plugin</H3 -><P -> An input plugin provides API functions which allow the engine to - access the data source the plugin encapsulates. The input plugin API - is declared in <TT -CLASS="FILENAME" ->input/input_plugin.h</TT ->. - </P -><P -> An input plugin exports a public function of the form: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void *input_init_plugin(xine_t *xine, void *data);</PRE -></TD -></TR -></TABLE -> - This function initializes an input plugin class object with the - following functions: - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_description(input_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns a plaintext, one-line string describing the plugin. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_identifier(input_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns a shorter identifier describing the plugin. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> xine_mrl_t **get_dir(input_class_t *this_gen, const char *filename, int *nFiles);</PRE -></TD -></TR -></TABLE -> - Retrieves a directory listing from the plugin. This function is optional. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char **get_autoplay_list(input_class_t *this_gen, int *num_files);</PRE -></TD -></TR -></TABLE -> - Retrieves the autoplay playlist from the plugin. This function is optional. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int eject_media(input_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - Ejects the medium. This function is optional. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void dispose(input_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function frees the memory used by the input plugin class object. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> input_plugin_t *get_instance(input_class_t *class_gen, xine_stream_t *stream, const char *mrl);</PRE -></TD -></TR -></TABLE -> - The plugin should try, if it can handle the specified MRL and return an - instance of itself if so. If not, NULL should be returned. - Note that input plugins are not guaranteed to be queried - in anay particular order and the first input plugin to claim an MRL - gets control so try not to duplicate MRLs already found within xine. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int open(input_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - You should do any device-specific initialisation within this function. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> uint32_t get_capabilities(input_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - Returns a bit mask describing the input device's capabilities. - You may logically OR the <TT -CLASS="VARNAME" ->INPUT_CAP_*</TT -> constants together to get - a suitable bit-mask (via the '|' operator). - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> off_t read(input_plugin_t *this_gen, char *buf, off_t nlen);</PRE -></TD -></TR -></TABLE -> - Reads a specified number of bytes into a buffer and returns the number of bytes actually copied. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> buf_element_t *read_block(input_plugin_t *this_gen, fifo_buffer_t *fifo, off_t len);</PRE -></TD -></TR -></TABLE -> - Should the input plugin set the block-oriented hint and if the - demuxer supports it, this function will be called to read a block directly - into a xine buffer from the buffer pool. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> off_t seek(input_plugin_t *this_gen, off_t offset, int origin);</PRE -></TD -></TR -></TABLE -> - This function is called by xine when it is required that subsequent - reads come from another part of the stream. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> off_t get_current_pos(input_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - Returns the current position within a finite length stream. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> off_t get_length(input_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - Similarly this function returns the length of the stream. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> uint32_t get_blocksize(input_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - Returns the device's prefered block-size if applicable. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_mrl(input_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - Returns the current MRL. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int get_optional_data(input_plugin_t *this_gen, void *data, int data_type);</PRE -></TD -></TR -></TABLE -> - This function allows the input to advertise extra information that is - not available through other API functions. See <TT -CLASS="VARNAME" ->INPUT_OPTIONAL_*</TT -> defines. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void dispose(input_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function closes all resources and frees the input_plugin_t object. - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN691" -></A ->Demuxer layer</H2 -><P -> This section is designed to familiarize a programmer with general demuxer - concepts and how they apply to the xine multimedia library. - </P -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN694" -></A ->Introduction to demuxer theory</H3 -><P -> xine's demuxer layer is responsible for taking apart multimedia files or - streams so that the engine can decode them and present them to the user. - "Demuxer" is short for demultiplexor, which is the opposite of - multiplexing. This refers to the process of combining 2 or more things - into one. Multimedia streams usually, at a minimum, multiplex an audio - stream and a video stream together into one stream. Sometimes, there are - multiple audio streams (e.g., for multiple language tracks). Sometimes, - there is a subtitle data stream multiplexed into the multimedia stream. - </P -><P -> There are many different multimedia formats in existence and there are - varying strategies for demuxing different types of multimedia files. - Formats in the MPEG family, for example, are designed to allow easy - playback from almost any place within the file. Many formats cannot deal - with this circumstance and at least need to be demuxed from the beginning - of the stream and played through to the end. Some formats, such as MPEG and - AVI, have marker information before every chunk in the stream. Other - formats, such as Apple Quicktime, are required to have a master index that - contains all information for taking apart a file. Many game-oriented - multimedia formats are designed strictly for playing from start to finish - without any regard to random seeking within the file. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN698" -></A ->Input considerations</H3 -><P -> A xine demuxer interacts with xine's input layer in order to receive - data. The underlying input plugin might be a file, a network stream, or - a block-oriented disc storage device like a DVD. A file input offers the - most flexibility in being able to read either blocks of data or individual - bytes, and being able to seek freely. Other input plugins may not allow the - demuxer to seek (such as stdin or certain network streams). Some input - plugins only allow the demuxer to read blocks of data and not individual - bytes (such as the CD-DA input plugin). The demuxer needs to check the - capabilities of the underlying input plugin before attempting to seek - around. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN701" -></A ->Seeking Policy</H3 -><P -> If possible, it is desirable that a demuxer can seek randomly through - the stream. This is easier for some file formats and essentially impossible - for other formats. xine's seeking API function allows a seek target to be - specified in terms of stream offset from 0, or time in milliseconds from 0. - Offset-based seeking is useful for seek bars in multimedia applications. - Time-based seeking is useful for specifying, e.g., a 1-minute jump forward - or backward in a stream. - </P -><P -> If a multimedia stream has video, there generally needs to be a way to - identify keyframes in the stream in order to facilitate seeking. Many - game-oriented formats fall over in this area as they carry no keyframe - information aside from the implicit assumption that the first frame is a - keyframe. - </P -><P -> In a stream with video, a seek operation should always jump to a keyframe. - xine Policy: When the seek target is between 2 keyframes, jump to the - earlier keyframe. E.g., if there are keyframes at stream offsets 10000 and - 20000, and the user requests a seek to offset 18000, choose the keyframe - at offset 10000. - </P -><P -> Note that there can be difficulties when the audio and video streams are - not tightly interleaved. In many formats, the audio frames are several - time units ahead of the video frames for the purpose of pre-buffering. - This is a typical scenario in the middle of a stream: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> audio frame @ time 10 - video frame @ time 8 - audio frame @ time 11 - video frame @ time 9 - audio frame @ time 12 - keyframe @ time 10 - audio frame @ time 13</PRE -></TD -></TR -></TABLE -> - If the demuxer seeks to the keyframe @ time 10, the next audio chunk will - have a timestamp of 13, which is well ahead of where the video is. While - the xine engine will eventually recover, it will make playback choppy for - a few seconds after the seek. One strategy for dealing with this situation - is to seek back to the nearest keyframe before the requested seek and then - seek back to find the audio frame with the nearest timestamp before the - keyframe. In this example, that would mean seeking back to [af@time 10]. - Then, demux the chunks in order, but skip the video frames until the next - keyframe is encountered. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN708" -></A ->Writing a xine demuxer</H3 -><P -> A demuxer plugin provides API functions which allow the engine to - initialize demuxing, dispatch data chunks to the engine, seek within the - stream, get the stream length, among other functions. The demuxer API - is declared in <TT -CLASS="FILENAME" ->demuxers/demux.h</TT ->. - </P -><P -> Writing a new xine demuxer is largely a process of using other demuxers as - references and understanding how they interact with the engine. This - section will give a brief overview of each API function. - </P -><P -> A demuxer plugin exports a public function of the form: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void *demux_wc3movie_init_plugin(xine_t *xine, void *data);</PRE -></TD -></TR -></TABLE -> - This function initializes a demuxer plugin class object with 6 - demuxer-specific functions. These functions mainly provide information - that a frontend can use to build user-friendly features. These functions - include: - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_description(demux_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns a plaintext, one-line string describing the plugin. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_identifier(demux_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns a shorter identifier describing the plugin. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_extensions(demux_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns a string with the file extensions that this demuxer - is known to use. For example, Microsoft .WAV files use "wav". If there are - multiple known extensions, separate each extension with a space. For - example, Apple Quicktime has the extensions "mov qt mp4". - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_mimetypes(demux_class_t *this_gen)</PRE -></TD -></TR -></TABLE -> - This function returns a string with the MIME types that this demuxer is - known to use. Multiple MIME type specifications should be separated with a - semicolon (;). For example, Apple Quicktime uses several MIME types: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> return "video/quicktime: mov,qt: Quicktime animation;" - "video/x-quicktime: mov,qt: Quicktime animation;" - "application/x-quicktimeplayer: qtl: Quicktime list;";</PRE -></TD -></TR -></TABLE -> - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void class_dispose(demux_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function frees the memory used by the demuxer plugin class object. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> demux_plugin_t *open_plugin(demux_class_t *class_gen, xine_stream_t *stream, input_plugin_t *input_gen);</PRE -></TD -></TR -></TABLE -> - This function is invoked by the xine engine to determine if the demuxer is - able to handle a particular multimedia stream. The engine can specify if - the demuxer is supposed to check the stream by content (validate the actual - stream data and see if it is of the expected type), by extension (check the - name of the MRL and see if the file extension is correct), or explicitly - (the engine is passing on a user request to force this demuxer to be used). - </P -><P -> NOTE: In the course of checking the stream by content, care must be taken - not to consume bytes out of a non-seekable stream. If the stream is - non-seekable, use the input plugin's preview buffer facility to get a cache - of the first few bytes. If the stream is seekable, reset the stream before - operating on the data (you do not know where some other demuxer left the - stream positioned). - </P -><P -> If the demuxer can handle the stream, it creates a new demux_plugin_t - structure and initializes the main demuxer functions which are called by - the engine to do the tough demuxing duty. These functions include: - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void demux_send_headers(demux_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function generally reads the headers of the stream, does whatever it - has to do to figure out what audio and video codecs are used in the file, - and asks the xine engine to initialize the correct decoders with the - proper parameters (like width and height for video, sample rate and - channels for audio). - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int demux_send_chunk(demux_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function reads data from the stream and sends it to the appropriate - decoder. This is where the bulk of the demuxing work is performed. Despite - the name, the function is actually free to send as much data as it wants - to, or as much as it can. A good policy is to send an entire chunk of - compressed audio or video data and then return. The chunk is likely large - enough that it will have to be broken up into multiple xine buffers. If - a chunk of audio is 20000 bytes large, and the engine is returning - 4096-byte buffers, send 4 full buffers and 1 partial buffer to the audio - decoder and then return. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int demux_seek(demux_plugin_t *this_gen, off_t start_pos, int start_time);</PRE -></TD -></TR -></TABLE -> - This function is called by the engine to request stream repositioning. - This function should be implemented if possible. See the section on - "Seeking Policy" for more information. A seek operation should reposition - the demuxer's internal accounting variables to be ready to start - dispatching chunks from the new position when the xine engine calls - demux_send_chunk() again. If seeking is not feasible, the function quietly - returns and the demuxer's position is unaffected. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void demux_dispose(demux_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function frees the demux_plugin_t object. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int demux_get_status(demux_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns the current internal status of the demuxer. There - are 2 states: DEMUX_OK, for when the demuxer is demuxing or ready to demux, - and DEMUX_FINISHED, for when the demuxer has reached the end of the stream - or has encountered some sort of error. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int demux_get_stream_length(demux_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns the length (time duration) of the stream in - milliseconds. If the length of the stream cannot be determined, return 0. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> uint32_t demux_get_capabilities(demux_plugin_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns an array of bit flags indicating special features of - the demuxer. See <TT -CLASS="VARNAME" ->DEMUX_CAP_*</TT -> defines. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int demux_get_optional_data(demux_plugin_t *this_gen, void *data, int data_type);</PRE -></TD -></TR -></TABLE -> - This function allows the demuxer to advertise extra information that is - not available through other API functions. See <TT -CLASS="VARNAME" ->DEMUX_OPTIONAL_*</TT -> defines. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN748" -></A ->Buffer types</H3 -><P -> Demuxer must send data to decoders using two fifos names <TT -CLASS="VARNAME" ->video_fifo</TT -> - and <TT -CLASS="VARNAME" ->audio_fifo</TT ->. Both are available at <TT -CLASS="VARNAME" ->stream</TT -> - level. The following code fragment shows how it's done. - </P -><TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> buf_element_t *buf; - - buf = stream->video_fifo->buffer_pool_alloc(stream->video_fifo); - buf->type = BUF_CONTROL_START; - stream->video_fifo->put(stream->video_fifo, buf);</PRE -></TD -></TR -></TABLE -><P -> Buffers must have set the <TT -CLASS="VARNAME" ->type</TT -> field as shown. All buffer types are - defined in <TT -CLASS="FILENAME" ->xine-engine/buffer.h</TT ->. - </P -><P -> The control buffer types are very important and must be sent by all kinds of demuxers. - They tell decoders to start/stop their operations and inform metronom about - discontinuities, either relative or absolute. There is also a reset buffer - type that must be sent when demuxers are seeking as a "warm restart" indication to - the decoders. - </P -><P -> To help finding out buffer types for known codecs, functions from <TT -CLASS="FILENAME" ->buffer_types.c</TT -> - may be used to convert "FOURCC" codes or audio format tags (as used in AVI files) to the xine - byffer type: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> buf->type = fourcc_to_buf_video((void*)this->avi->bih.biCompression);</PRE -></TD -></TR -></TABLE -> - </P -></DIV -></DIV -><DIV -CLASS="SECT1" -><HR><H2 -CLASS="SECT1" -><A -NAME="AEN762" -></A ->Decoder layer</H2 -><P -> This section is designed to familiarize a programmer with basic audio - and video decoding concepts and how they apply to the xine decoder API. - </P -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN765" -></A ->Audio and video decoders</H3 -><P -> Audio and video data requires an enormous amount of storage. Thus, the - raw data is encoded using a variety of compression techniques which - drastically reduces the amount of space required to transmit and store the - data. Before playback, the compressed data needs to be decoded. - </P -><P -> The process of decoding data is rather straightforward in a computer - science sense: An array of encoded data is fed into a decoder and the - decoder outputs an array of decoded data which is ready to be presented - to the user (either displayed on the screen or played through the - speakers). - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN769" -></A ->Video output formats</H3 -><P -> Raw video data comes in a variety of formats, most commonly in RGB and - YUV. xine's output layer currently only accepts data in YV12 format (a.k.a. - YUV 4:2:0 planar) or YUY2 format (a.k.a. YUV 4:2:2 packed). If the output - format is a RGB space, the data must be converted to an acceptable YUV - format before being dispatched to the video output unit. xine has a number - of support functions to facilitate converting RGB to YUV. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN772" -></A ->Audio output formats</H3 -><P -> Raw audio data equates to uncompressed PCM audio. xine's audio output - modules expect 8-bit PCM data to be unsigned and 16-bit PCM data to be - signed and in little endian format. When there is more than one channel, - the channel data is interleaved. For example, stereo data is interleaved - as left sample, right sample: LRLRLRLR. If there are 4 or 6 channels, the - same interleaving applies: 123456123456. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN775" -></A ->Writing a xine decoder</H3 -><P -> Writing a new xine decoder for an audio or video format entails - accumulating a buffer of encoded data, performing the necessary operations - for decoding and then passing it on the appropriate output module. The - best reference for understanding the decoder API is the various decoding - modules available. In particular, xine has example video and audio - decoders named <TT -CLASS="FILENAME" ->src/libxinevdec/foovideo.c</TT -> and - <TT -CLASS="FILENAME" ->src/libxineadec/fooaudio.c</TT ->, respectively. - </P -><P -> This section will give a brief overview of each API function. - The decoder API is declared in <TT -CLASS="FILENAME" ->src/xine-engine/video_decoder.h</TT -> - and <TT -CLASS="FILENAME" ->src/xine-engine/audio_decoder.h</TT ->. - </P -><P -> A decoder plugin must, like every plugin, export a public array of - plugin_info_t types. The array usually has 2 entries: The first contains - the plugin information regarding the decoder and the second entry is - a terminating NULL entry. However, there may be more entries. - Each entry contains 6 fields: - <P -></P -><UL -><LI -><P -> <TT -CLASS="VARNAME" ->plugin type</TT ->: Either PLUGIN_VIDEO_DECODER or PLUGIN_AUDIO_DECODER. - </P -></LI -><LI -><P -> <TT -CLASS="VARNAME" ->API</TT ->: The plugin API revision that this plugin adheres to. - </P -></LI -><LI -><P -> <TT -CLASS="VARNAME" ->name</TT ->: A character string that identifies the plugin. - </P -></LI -><LI -><P -> <TT -CLASS="VARNAME" ->version</TT ->: #define'd as XINE_VERSION_CODE. - </P -></LI -><LI -><P -> <TT -CLASS="VARNAME" ->supported types</TT ->: A structure that defines the buffer types that this plugin can handle. - </P -></LI -><LI -><P -> <TT -CLASS="VARNAME" ->init function</TT ->: The function that the xine engine calls in order to initialize this decoder plugin. - </P -></LI -></UL -> - The supported types field is a decoder_info_t structure. This struct - combines a list of buffer types that the plugin can handle, along with - a relative default priority. The priority allows xine to have multiple - plugins that can handle one data type and the plugin with the highest - priority takes precedence. The code defines the default priority, which - can be overriden by the user. - The list of buffer types is an array of uint32_t types from the list of - buffer types defined in <TT -CLASS="FILENAME" ->src/xine-engine/buffer.h</TT ->. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void *init_plugin(xine_t *xine, void *data);</PRE -></TD -></TR -></TABLE -> - This function allocates a plugin class and initializes a set of functions - for the xine engine to invoke. These functions include: - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_identifier(video_decoder_class_t *this);</PRE -></TD -></TR -></TABLE -> - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_identifier(audio_decoder_class_t *this);</PRE -></TD -></TR -></TABLE -> - This function returns a brief character string identifying the plugin. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_description(video_decoder_class_t *this);</PRE -></TD -></TR -></TABLE -> - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_description(audio_decoder_class_t *this);</PRE -></TD -></TR -></TABLE -> - This function returns a slightly longer description of the plugin. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void dispose_class(video_decoder_class_t *this);</PRE -></TD -></TR -></TABLE -> - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void dispose_class(audio_decoder_class_t *this);</PRE -></TD -></TR -></TABLE -> - This function frees the resources allocated by the plugin class. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> video_decoder_t *open_plugin(video_decoder_class_t *class_gen, xine_stream_t *stream);</PRE -></TD -></TR -></TABLE -> - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> audio_decoder_t *open_plugin(audio_decoder_class_t *class_gen, xine_stream_t *stream);</PRE -></TD -></TR -></TABLE -> - This function initializes the decoder plugin's private state. It also - initializes and returns either an audio_decoder_t or a video_decoder_t for - the engine. The decoder_t contains a number of functions that the plugin - invokes to handle data decoding. These functions include: - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void decode_data(video_decoder_t *this_gen, buf_element_t *buf);</PRE -></TD -></TR -></TABLE -> - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void decode_data(audio_decoder_t *this_gen, buf_element_t *buf);</PRE -></TD -></TR -></TABLE -> - This function performs the bulk of the decoding work. The xine engine - delivers buffers (xine_buffer_t data types) to this function and it is up - to this function to assemble the parts of the buffer, decode the data, and - send the decoded data to the proper output unit. - </P -><P -> A buffer has a <TT -CLASS="VARNAME" ->decoder_flags</TT -> field which can have - a number of flags set. The first buffer that a decoder receives ought - to have the BUF_FLAG_HEADER flag set. This indicates that the buffer - content contains the essential setup information for decoding - (width, height, etc. for video; sample rate, channels, etc. for audio). - </P -><P -> If the BUF_FLAG_HEADER flag is not set, the content of the buffer should - be accumulated in a private buffer until a buffer with a - BUF_FLAG_FRAME_END flag is set. This indicates that the entire chunk has - been transmitted to the decoder and is ready to be decoded. Fetch either - an empty video frame or audio buffer from the appropriate output unit. Perform - the appropriate decoding operations and set the pts for the output buffer - (and the duration, a.k.a. video_step, for video). Dispatch the decoded - data to the output and reset the internal buffer accumulation accounting. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void flush(video_decoder_t *this_gen);</PRE -></TD -></TR -></TABLE -> - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void flush(audio_decoder_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function is called when either the xine engine flushes the stream, e.g., - after a seek operation or when decoding runs too slow and frames arrive in - the output loops fast enough. Decoders should release everything they have - already decoded, drop the rest and wait for new input. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void reset(video_decoder_t *this_gen);</PRE -></TD -></TR -></TABLE -> - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void reset(audio_decoder_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function is called when the xine engine resets the stream. - Decoders should get ready to receive data that has nothing to do - with the one it worked on up to now. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void discontinuity(video_decoder_t *this_gen);</PRE -></TD -></TR -></TABLE -> - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void discontinuity(audio_decoder_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function is called when the xine engine encounters a pts - discontinuity. Decoders should forget all timestamping information - they might have accumulated from the stream to not confuse metronom. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void dispose(video_decoder_t *this_gen);</PRE -></TD -></TR -></TABLE -> - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void dispose(audio_decoder_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function frees the resources used by the decoder plugin. - </P -></DIV -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN836" -></A ->SPU decoder</H3 -><P -> A lot written above also applies for subpicture unit (SPU) decoders. The - SPU decoder API is declared in <TT -CLASS="FILENAME" ->src/xine-engine/spu_decoder.h</TT ->. - Details on the data, SPU decoders are expected to output, see the section on - <A -HREF="#OSD" ->overlays and OSD</A ->. - </P -><P -> However, there are some differences to consider. At first, unlike audio and - video, subtitles do not form a continuous stream. The decoder will therefore - only be called once in a while. The metronom call for timestamping, - which for audio and video is done by the engine, has to be done manually for SPU: - <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> vpts = metronom->got_spu_packet(metronom, buf->pts);</PRE -></TD -></TR -></TABLE -> - </P -><P -> There are also two functions in the SPU decoder API, which have not been discussed above: - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int get_interact_info(spu_decoder_t *this_gen, void *data);</PRE -></TD -></TR -></TABLE -> - Since SPUs are sometimes (on DVDs for example) used for user interaction like menu - highlights, this function can be called to get <TT -CLASS="VARNAME" ->data</TT -> filled with - the current interaction information. The caller and the decoder have to agree on - what this is exactly. With DVDs, you can get a copy of the current NAV packet here. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void set_button(spu_decoder_t *this_gen, int32_t button, int32_t mode);</PRE -></TD -></TR -></TABLE -> - Also for interaction, you can ask the decoder here to change the - current highlighting. - </P -></DIV -></DIV -></DIV -><DIV -CLASS="CHAPTER" -><HR><H1 -><A -NAME="OUTPUT" -></A ->Chapter 6. xine's output layer</H1 -><DIV -CLASS="SECT1" -><H2 -CLASS="SECT1" -><A -NAME="AEN851" -></A ->Video output</H2 -><P -> In order to allow for device-dependant acceleration features, xine - calls upon the video output plugin for more than just displaying - images. The tasks performed by the video plugins are: - <P -></P -><UL -><LI -><P -> Allocation of <SPAN -CLASS="TYPE" ->vo_frame_t</SPAN -> structures and their - subsequent destruction. - </P -></LI -><LI -><P -> Allocation of memory for use by one frame (this is to allow - for the ability of some video output plugins to map frames directly - into video-card memory hence removing the need for the frame to - be copied across the PCI/AGP bus at display time). - </P -></LI -><LI -><P -> Most important, the ability to render/copy a given - frame to the output device. - </P -></LI -><LI -><P -> Optionally the copying of the frame from a file dependant - colour-space and depth into the frame structure. This is to allow for - on-the fly colour-space conversion and scaling if required (e.g. the XShm - ouput plugin uses this mechanism). - </P -></LI -></UL -> - </P -><P -> Although these extra responsibilities add great complexity to your - plugin it should be noted that they allow plugins to take full advantage - of any special hardware-acceleration without sacrificing flexibility. - </P -><DIV -CLASS="SECT2" -><HR><H3 -CLASS="SECT2" -><A -NAME="AEN865" -></A ->Writing a xine video out plugin</H3 -><P -> The video out plugin API is declared in <TT -CLASS="FILENAME" ->src/xine-engine/video_out.h</TT -> - The plugin info of video out plugins contains the visual type, priority, - and the init_class function of the plugin. - </P -><P -> The <TT -CLASS="VARNAME" ->visual_type</TT -> field is used by xine to - determine if the GUI used by the client is supported by the plugin - (e.g. X11 output plugins require the GUI to be running under the - X Windowing system) and also to determine the type of information passed to the - <TT -CLASS="FUNCTION" ->open_plugin()</TT -> function as its <TT -CLASS="VARNAME" ->visual</TT -> parameter. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_description(video_driver_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns a plaintext, one-line string describing the plugin. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> char *get_identifier(video_driver_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function returns a shorter identifier describing the plugin. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void dispose(video_driver_class_t *this_gen);</PRE -></TD -></TR -></TABLE -> - This function frees the memory used by the video out plugin class object. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> vo_driver_t *get_instance(video_driver_class_t *class_gen, const void *visual);</PRE -></TD -></TR -></TABLE -> - Returns an instance of the plugin. - The <TT -CLASS="VARNAME" ->visual</TT -> is a pointer to a visual-dependant - structure/variable. For example, if you had previously claimed your - plugin was of the VISUAL_TYPE_X11 type, this would be a pointer - to a <SPAN -CLASS="TYPE" ->x11_visual_t</SPAN ->, which amongst other things hold the - <SPAN -CLASS="TYPE" ->Display</SPAN -> variable associated with the - X-server xine should display to. See plugin source-code for other - VISUAL_TYPE_* constants and associated structures. Note that this - field is provided by the client application and so if you wish to add another visual - type you will either need to extend an existing client or write a new - one. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> uint32_t get_capabilities(vo_driver_t *this_gen);</PRE -></TD -></TR -></TABLE -> - Returns a bit mask describing the output plugin's capabilities. - You may logically OR the <TT -CLASS="VARNAME" ->VO_CAP_*</TT -> constants together to get - a suitable bit-mask (via the '|' operator). - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int get_property(vo_driver_t *self, int property); - int set_property(vo_driver_t *self, int property, int value); - void get_property_min_max(vo_driver_t *self, int property, int *min, int *max);</PRE -></TD -></TR -></TABLE -> - Handle the getting, setting of properties and define their bounds. - Valid property IDs can be found in the <TT -CLASS="FILENAME" ->video_out.h</TT -> - header file. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int gui_data_exchange(vo_driver_t *self, int data_type, void *data);</PRE -></TD -></TR -></TABLE -> - Accepts various forms of data from the UI (e.g. the mouse has moved or the - window has been hidden). Look at existing plugins for examples of data - exchanges from various UIs. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> vo_frame_t *alloc_frame(vo_driver_t *self);</PRE -></TD -></TR -></TABLE -> - Returns a pointer to a xine video frame. - Typically the video plugin will add private fields to the end of the - <SPAN -CLASS="TYPE" ->vo_frame_t</SPAN -> structure which are used for internal purposes by the plugin. - </P -><P -> The function pointers within the frame structure provide a mechanism for the - driver to retain full control of how the frames are managed and rendered to. If - the VO_CAP_COPIES_IMAGE flag was set in the plugins capabilities then the - copy field is required and will be called sequentially for each 16-pixel high - strip in the image. The plugin may then decide, based on the frame's format, how - this is copied into the frame. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void update_frame_format(vo_driver_t *self, vo_frame_t *img, uint32_t width, uint32_t height, double ratio, int format, int flags);</PRE -></TD -></TR -></TABLE -> - This function will be called each time the colour-depth/space or size of a frame changes. - Typically this function would allocate sufficient memory for the frame, assign the pointers - to the individual planes of the frame to the <TT -CLASS="VARNAME" ->base</TT -> field of the - frame and perform any driver-specific changes. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void display_frame(vo_driver_t *self, vo_frame_t *vo_img);</PRE -></TD -></TR -></TABLE -> - Renders a given frame to the output device. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void overlay_begin(vo_driver_t *self, vo_frame_t *vo_img, int changed); - void overlay_blend(vo_driver_t *self, vo_frame_t *vo_img, vo_overlay_t *overlay); - void overlay_end(vo_driver_t *self, vo_frame_t *vo_img);</PRE -></TD -></TR -></TABLE -> - These are used to blend overlays on frames. <TT -CLASS="FUNCTION" ->overlay_begin()</TT -> is called, - when the overlay appears for the first time, <TT -CLASS="FUNCTION" ->overlay_blend()</TT -> is then - called for every subsequent frame and <TT -CLASS="FUNCTION" ->overlay_end()</TT -> is called, when - the overlay should disappear again. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> int redraw_needed(vo_driver_t *self);</PRE -></TD -></TR -></TABLE -> - Queries the driver, if the current frame needs to be drawn again. - </P -><P -> <TABLE -BORDER="0" -BGCOLOR="#E0E0E0" -WIDTH="100%" -><TR -><TD -><PRE -CLASS="PROGRAMLISTING" -> void dispose(vo_driver_t *self);</PRE -></TD -></TR -></TABLE -> - Releases all resources and frees the plugin. - </P -></DIV -></DIV -></DIV -></DIV -></BODY -></HTML ->
\ No newline at end of file diff --git a/doc/hackersguide/overview.sgml b/doc/hackersguide/overview.sgml index 833d966b4..acbac5f39 100644 --- a/doc/hackersguide/overview.sgml +++ b/doc/hackersguide/overview.sgml @@ -12,7 +12,10 @@ Directories marked with "(imported)" contain code that is copied from an external project into xine-lib. Everything below such a directory is up to this project. When modifying - code there, be sure to send the patches on. + code there, be sure to send the patches on. If some xine specific + adaptation of the code is absolutely necessary, a patch containing + the changes should be stored in CVS to not loose the changes the + next time we sync with the external project. </para> <para> <variablelist> |