The xine engine FAQ

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 (Athlon™) 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 (Athlon™) 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

xine-lib >= 1.x.x
OSS driver
an external decoder
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. -

The xine hacker's guide

G�nter Bartsch

Heiko Sch�fer

Richard Wareham

Miguel Freitas

James Courtier-Dutton

Siggi Langauf

Marco Z�hlke

Mike Melanson

Michael Roitzsch

Table of Contents

1. Introduction

Where am I?
What does this text do?
New versions of this document
Feedback

2. Using the xine library

xine architecture as visible to libxine clients

Writing a new frontend to xine

Source code of a simple X11 frontend

3. xine code overview

Walking the source tree

Object oriented programming in C

Coding style and guidelines

The xine logging system

xine_log
xprintf
lprintf/llprintf

How to contribute

4. xine internals

Engine architecture and data flow

Plugin system

Plugin location and filesystem layout
Plugin Content: What's inside the .so?

What is this metronom thingy?

How does xine synchronize audio and video?

Overlays and OSD

Overlay Manager
OSD Renderer

MRLs

5. xine's stream layer

Input layer

Writing a xine input plugin

Demuxer layer

Introduction to demuxer theory
Input considerations
Seeking Policy
Writing a xine demuxer
Buffer types

Decoder layer

Audio and video decoders
Video output formats
Audio output formats
Writing a xine decoder
SPU decoder

6. xine's output layer

Video output

Writing a xine video out plugin

Chapter 1. Introduction

Where am I?

You are currently looking at a piece of documentation for xine. - xine is a free video player. It lives on - http://xinehq.de/. Specifically - this document goes under the moniker of the "xine Hackers' Guide". -

What does this text do?

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. -

New versions of this document

This document is being developed in the xine-lib cvs repository within - the directory doc/hackersguide/. If you are - unsure what to do with the stuff in that directory, please read the - README file located there. -

New versions of this document can also be obtained from the xine web site: - http://xinehq.de/. -

Feedback

All comments, error reports, additional information and criticism - concerning this document should be directed to the xine documentations - mailing list <xine-docs@lists.sourceforge.net>. - Questions about xine hacking in general should be sent to the - developer mailing list <xine-devel@lists.sourceforge.net>. -

Chapter 2. Using the xine library

xine architecture as visible to libxine clients

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. -

outside view on xine components

The function are named just to give you an overview of what is actually - there. It is all thoroughly documented in the plublic header - xine.h, which is the main and preferably the only xine - header, clients should include. (xine/xineutils.h and the XML parser might - make an exception.) -

Details on the OSD feature can be found in the OSD section. -

Writing a new frontend to xine

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. -

Source code of a simple X11 frontend

/*
-** 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;
-}

Chapter 3. xine code overview

Walking the source tree

The src/ directory in xine-lib contains several - modules, this should give you a quick overview on where - to find what sources. -

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. -

audio_out

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). -

demuxers

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. -

dxr3

Code to support the DXR3 / hollywood+ hardware mpeg decoder. -

input

Input plugins encapsulate the origin of the data. Data sources like - ordinary files, DVDs, CDA or streaming media are handled here. -

dvb

Some headers for Digital Video Broadcast. -

libdvdnav (imported)

The libdvdnav library for DVD navigation is used - by xine's DVD input plugin. -

libreal, librtsp

Support for RealMedia streaming as used by the RTSP input plugin. -

vcd

The enhanced VCD input plugin which also handles VCD navigation. -

libcdio, libvcd (imported)

Libraries used by the enhanced VCD plugin. -

liba52 (imported)

A52 (aka AC3, aka Dolby Digital) audio decoder library and xine plugin. -

We maintain some small integration improving differences between the - original liba52 and our copy in the file - diff_against_release.patch. -

libdivx4

Video decoder plugin using libdivx4linux if it is installed. - Currently unmaintained and soon to be discontinued if noone cares to take over. -

libdts

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? -

libfaad (imported)

The Free AAC Decoder library and xine plugin. -

libffmpeg

A xine decoder plugin using various audio and video decoders from the - ffmpeg decoder pack libavcodec. Their MPEG encoder is also for the DXR3. -

To optimize the integration of libavcodec and the xine engine, we maintain - some differences between the original ffmpeg and our copy in the file - diff_to_ffmpeg_cvs.txt. -

libavcodec (imported)

The libavcodec decoder pack as used by xine's ffmpeg plugin. -

libflac

A xine demuxer and decoder plugin for the Free Lossless Audio Codec library, - which has to be installed separately. -

liblpcm

Audio decoder plugin that "decodes" raw PCM data; most notably - endianess-conversions are done here. -

libmad (imported)

Mpeg audio decoder plugin (i.e. mp2 and mp3 decoding). - ISO/IEC compliant decoder using fixed point math. -

libmpeg2 (imported)

Most important MPEG video decoder plugin, provides fast and - high-precision MPEG-1/2 video decoding. -

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. -

libmpeg2new

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. -

include, libmpeg2 (imported)

The code of the imported new libmpeg2. -

libmpg123 (imported)

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. -

libreal

A thin wrapper around Real's binary codecs from the Linux RealPlayer to - use them as a xine plugin. -

libspeex

A xine decoder plugin for the speex library, - which has to be installed separately. -

libspucc

Closed caption subtitle decoder plugin. -

libspudec

DVD SPU subtitle decoder plugin. -

libsputext

Plain text subtitle decoder plugins. -

libtheora

A xine decoder plugin for the theora library, - which has to be installed separately. -

libvorbis

A xine decoder plugin for the ogg/vorbis library, - which has to be installed separately. -

libw32dll

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. -

DirectShow, dmo, - qtx, wine (imported)

Stripped down version of wine to support Video for Windows DLLs - and additional code to use DirectShow, DMO and QuickTime DLLs. -

libxineadec

xine's decoder pack of additional audio decoders. -

gsm610 (imported)

The gsm610 audio decoder library as used by the related xine plugin. -

nosefart (imported)

The nosefart audio decoder library as used by the related xine plugin. -

libxinevdec

xine's decoder pack of additional video decoders. -

libxvid

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. -

post

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. -

deinterlace (imported)

The tvtime deinterlacer as a xine video filter post. -

goom (imported)

The goom audio visualizer as a xine visualizer post. -

mosaico

Some post plugins merging multiple frames into one. For example - picture in picture can be done with this. -

planar

Some simple 2D video effects as xine video filter posts. -

visualizations

Audio visualization post plugins. -

video_out

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. -

libdha (imported)

A library for direct hardware access to the graphics card - as used by the vidix video out plugin. -

vidix (imported)

The vidix system for high performance video output - as used by the vidix video out plugin. -

xine-engine

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 internals section 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. -

xine-utils

Collection of utility functions and platform abstractions. - Also contains a simple XML parser for frontend playlist handling. -

Object oriented programming in C

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. -

Classes are structs containing function pointers and public member data. - Example: -
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);
-

To derive from such a class, private member variables can be added: -
typedef struct { - my_stack_t stack; /* public part */ - - /* private part follows here */ - int values[MAX_STACK_SIZE]; - int stack_size; - } intstack_t;
- 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. -

Implementation of the "push" method follows: -
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; - }
-

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: -
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; - }
-

Coding style and guidelines

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. -

Comment your interfaces directly in the header files. - No doxygen comments, ordinary C comments will do. -
Use C-style comments (/* */), not C++-style (//). -
When in doubt, use lower case. BTW: This thing is called xine, never Xine. -
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). -
Avoid macros unless they are really useful. Avoid gotos. -
use something like -
printf("module: ..."[,...]);
- for console output. All console output goes to stdout and - must be prefixed by the module name which generates the - output (see example above). -
Refer to emac's C-mode for all questions of proper indentiation. - That first of all means: indent with two spaces. -

The xine logging system

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. -

xine_log

Output which is done thru this function will be - displayed for the end user by the frontend. - If xine->verbosity 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. -
xine_log(xine_t *xine, int buf, const char *format, ...);
- buf is either XINE_LOG_MSG for general messages or - XINE_LOG_PLUGIN for messages about plugins. -

xprintf

This macro uses the xine->verbosity 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 --verbose=[1,2] options. - This function should be used for information which the - user should only read up on request. -
xprintf(xine_t *xine, int verbosity, const char *format, ...);
-

lprintf/llprintf

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. -
lprintf(const char *format, ...); - llprintf(bool, const char *format, ...);
- bool is a flag which enables or disables this logging. -

lprintf can be enabled by defining LOG at the top of the source file. - llprintf can be used for more than one categorie - per file by using diffent lables: -
#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);
-

In this case only the first messages is printed. To enable/disable change the defines. -

LOG_MODULE should be used to set the modulename for xprintf/lprintf/llprintf. - Each output line will start with "modulename: ". -
#define LOG_MODULE "modulename"
-

LOG_VERBOSE can be defined to enable the logging of functionname and linenumbers. - Then the output will be: "modulename: (function_name:42) message". -

How to contribute

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). -

Chapter 4. xine internals

Engine architecture and data flow

xine engine architecture

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. -

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. -

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. -

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. -

Plugin system

The plugin system enables some of xine's most valuable features: -

drop-in extensiability -
support parallel installation of multiple (incompatible) libxine versions -
support for multiple plugin directories - ($prefix/lib/xine/plugins, - $HOME/.xine/plugins, ...) -
support for recursive plugin directories - (plugins are found even in subdirectories of the plugin directories) -
version management - (On start, xine finds all plugins in its plugin (sub)directories and - chooses an appropriate version (usually the newest) for each plugin.) -
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.) -

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. -

Plugin location and filesystem layout

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: -

Plugins are installed below XINE_PLUGINDIR - (/usr/local/lib/xine/plugins 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. -

So you will finally end up with something like this: -
/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) - ...
-

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. -

The default value for XINE_PLUGINDIR can be obtained using the - xine-config --plugindir command. -

Plugin Content: What's inside the .so?

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. -

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. -

This plugin list is held in an array named xine_plugin_info": -
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 } - };
-

The structure of xine_plugin_info may never be changed. - If it ever needs to be changed, it must be renamed to avoid - erraneous loading of incompatible plugins. -

xine_plugin_info can contain any number of plugins - and must be terminated with a PLUGIN_NONE entry. Available plugin - types are: -
#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
-

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. -

Every entry in xine_plugin_info has an initialization - function for the plugin class context. - This function returns a pointer to freshly allocated (typically - via malloc()) structure containing mainly function - pointers; these are the "methods" of the plugin class. -

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. -

If you think this is pretty much an object-oriented aproach, - then you're right. -

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: -
#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 } - }
- 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). -

You'll find exact definitions of public functions and plugin structs - in the appropriate header files for each plugin type: - input/input_plugin.h for input plugins, - demuxers/demux.h for demuxer plugins, - xine-engine/video_decoder.h for video decoder plugins, - xine-engine/audio_decoder.h for audio decoder plugins, - xine-engine/post.h for post plugins, - xine-engine/video_out.h for video out plugins, - xine-engine/audio_out.h for audio out plugins. - Additional information will also be given in the dedicated sections below. -

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: -
typedef struct { - /* public fields "inherited" from demux.h */ - demux_plugin_t demux_plugin; - - xine_t *xine; - int count; - } demux_foo_t;
-

The plugin would then access public members via the - demux_plugin field and private fields directly. -

Summary: Plugins consist of two C-style classes, each representing a different context. -

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. -
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 -

What is this metronom thingy?

Metronom serves two purposes: -

Generate vpts (virtual presentation time stamps) from pts (presentation time stamps) - for a/v output and synchronization. -
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). -

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. -

The heuristics used in metronom have always been a field of research. Current metronom's - implementation tries to stick to pts values as reported from demuxers, - that is, vpts may be obtained by a simple operation of vpts = pts + vpts_offset, - where vpts_offset 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". -

How does xine synchronize audio and video?

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 - now 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. -

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. -

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 audio.av_sync_method): -

The small sound card errors are feedbacked to metronom. The details - are given by audio_out.c comments: -
/* 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. - */
-

The audio is stretched or squeezed a slight bit by resampling, thus compensating - the drift: The next comment in audio_out.c explains: -
/* 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+. - */
-

Overlays and OSD

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. -

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. -

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. -

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. -

overlays architecture

Overlay Manager

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: -
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);
-

OSD Renderer

OSD is a general API for rendering stuff over playing video. It's available both - to xine plugins and to frontends. -

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. -

   osd_object_t osd;
-   
-   osd = this->osd_renderer->new_object(osd_renderer, 300, 200);

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 - $prefix/share/xine/fonts/ and ~/.xine/fonts. - There's a sample utility to convert truetype fonts at - xine-lib/misc/xine-fontconv.c. Palette may be manipulated directly, - however most of the time it's convenient to use pre-defined text palettes. -

   /* 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);

Now render the text and show it: -
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' */
-

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. -

   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);

For additional functions please check osd.h or the public header. -

OSD palette notes

The palette functions demand some additional explanation, skip this if you - just want to write text fast without worring with details! :) -

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: -

   /* 
-    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)   
-   */

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. -

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. -

   /* 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);

OSD text and palette FAQ

Q: What is the format of the color palette entries? -

A: It's the same as used by overlay blending code (YUV). -

Q: What is the relation between a text palette and a palette - I set with xine_osd_set_palette? -

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. -

Q: Can I render text with colors in my own palette? -

A: Sure. Just pass the color_base to osd_render_text() -

Q: Has a text palette change effects on already drawed text? -

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. -

Q: What about the shadows of osd-objects? Can I turn them off - or are they hardcoded? -

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. -

MRLs

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. -

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. -

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. -

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. -

EBNF grammar for MRLs: -
<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)
-

Chapter 5. xine's stream layer

Input layer

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: -

Validation of Media Resource Locators (MRLs). -
MRL specific session management (e.g. opening and closing local files). -
Reading blocks/specific numbers of bytes from the input device. -

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). -

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. -

Writing a xine input plugin

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 input/input_plugin.h. -

An input plugin exports a public function of the form: -
void *input_init_plugin(xine_t *xine, void *data);
- This function initializes an input plugin class object with the - following functions: -

char *get_description(input_class_t *this_gen);
- This function returns a plaintext, one-line string describing the plugin. -

char *get_identifier(input_class_t *this_gen);
- This function returns a shorter identifier describing the plugin. -

xine_mrl_t **get_dir(input_class_t *this_gen, const char *filename, int *nFiles);
- Retrieves a directory listing from the plugin. This function is optional. -

char **get_autoplay_list(input_class_t *this_gen, int *num_files);
- Retrieves the autoplay playlist from the plugin. This function is optional. -

int eject_media(input_class_t *this_gen);
- Ejects the medium. This function is optional. -

void dispose(input_class_t *this_gen);
- This function frees the memory used by the input plugin class object. -

input_plugin_t *get_instance(input_class_t *class_gen, xine_stream_t *stream, const char *mrl);
- 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. -

int open(input_plugin_t *this_gen);
- You should do any device-specific initialisation within this function. -

uint32_t get_capabilities(input_plugin_t *this_gen);
- Returns a bit mask describing the input device's capabilities. - You may logically OR the INPUT_CAP_* constants together to get - a suitable bit-mask (via the '|' operator). -

off_t read(input_plugin_t *this_gen, char *buf, off_t nlen);
- Reads a specified number of bytes into a buffer and returns the number of bytes actually copied. -

buf_element_t *read_block(input_plugin_t *this_gen, fifo_buffer_t *fifo, off_t len);
- 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. -

off_t seek(input_plugin_t *this_gen, off_t offset, int origin);
- This function is called by xine when it is required that subsequent - reads come from another part of the stream. -

off_t get_current_pos(input_plugin_t *this_gen);
- Returns the current position within a finite length stream. -

off_t get_length(input_plugin_t *this_gen);
- Similarly this function returns the length of the stream. -

uint32_t get_blocksize(input_plugin_t *this_gen);
- Returns the device's prefered block-size if applicable. -

char *get_mrl(input_plugin_t *this_gen);
- Returns the current MRL. -

int get_optional_data(input_plugin_t *this_gen, void *data, int data_type);
- This function allows the input to advertise extra information that is - not available through other API functions. See INPUT_OPTIONAL_* defines. -

void dispose(input_plugin_t *this_gen);
- This function closes all resources and frees the input_plugin_t object. -

Demuxer layer

This section is designed to familiarize a programmer with general demuxer - concepts and how they apply to the xine multimedia library. -

Introduction to demuxer theory

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. -

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. -

Input considerations

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. -

Seeking Policy

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. -

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. -

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. -

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: -
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
- 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. -

Writing a xine demuxer

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 demuxers/demux.h. -

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. -

A demuxer plugin exports a public function of the form: -
void *demux_wc3movie_init_plugin(xine_t *xine, void *data);
- 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: -

char *get_description(demux_class_t *this_gen);
- This function returns a plaintext, one-line string describing the plugin. -

char *get_identifier(demux_class_t *this_gen);
- This function returns a shorter identifier describing the plugin. -

char *get_extensions(demux_class_t *this_gen);
- 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". -

char *get_mimetypes(demux_class_t *this_gen)
- 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: -
return "video/quicktime: mov,qt: Quicktime animation;" - "video/x-quicktime: mov,qt: Quicktime animation;" - "application/x-quicktimeplayer: qtl: Quicktime list;";
-

void class_dispose(demux_class_t *this_gen);
- This function frees the memory used by the demuxer plugin class object. -

demux_plugin_t *open_plugin(demux_class_t *class_gen, xine_stream_t *stream, input_plugin_t *input_gen);
- 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). -

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). -

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: -

void demux_send_headers(demux_plugin_t *this_gen);
- 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). -

int demux_send_chunk(demux_plugin_t *this_gen);
- 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. -

int demux_seek(demux_plugin_t *this_gen, off_t start_pos, int start_time);
- 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. -

void demux_dispose(demux_plugin_t *this_gen);
- This function frees the demux_plugin_t object. -

int demux_get_status(demux_plugin_t *this_gen);
- 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. -

int demux_get_stream_length(demux_plugin_t *this_gen);
- This function returns the length (time duration) of the stream in - milliseconds. If the length of the stream cannot be determined, return 0. -

uint32_t demux_get_capabilities(demux_plugin_t *this_gen);
- This function returns an array of bit flags indicating special features of - the demuxer. See DEMUX_CAP_* defines. -

int demux_get_optional_data(demux_plugin_t *this_gen, void *data, int data_type);
- This function allows the demuxer to advertise extra information that is - not available through other API functions. See DEMUX_OPTIONAL_* defines. -

Buffer types

Demuxer must send data to decoders using two fifos names video_fifo - and audio_fifo. Both are available at stream - level. The following code fragment shows how it's done. -

   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);

Buffers must have set the type field as shown. All buffer types are - defined in xine-engine/buffer.h. -

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. -

To help finding out buffer types for known codecs, functions from buffer_types.c - may be used to convert "FOURCC" codes or audio format tags (as used in AVI files) to the xine - byffer type: -
buf->type = fourcc_to_buf_video((void*)this->avi->bih.biCompression);
-

Decoder layer

This section is designed to familiarize a programmer with basic audio - and video decoding concepts and how they apply to the xine decoder API. -

Audio and video decoders

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. -

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). -

Video output formats

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. -

Audio output formats

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. -

Writing a xine decoder

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 src/libxinevdec/foovideo.c and - src/libxineadec/fooaudio.c, respectively. -

This section will give a brief overview of each API function. - The decoder API is declared in src/xine-engine/video_decoder.h - and src/xine-engine/audio_decoder.h. -

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: -

plugin type: Either PLUGIN_VIDEO_DECODER or PLUGIN_AUDIO_DECODER. -
API: The plugin API revision that this plugin adheres to. -
name: A character string that identifies the plugin. -
version: #define'd as XINE_VERSION_CODE. -
supported types: A structure that defines the buffer types that this plugin can handle. -
init function: The function that the xine engine calls in order to initialize this decoder plugin. -

- 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 src/xine-engine/buffer.h. -

void *init_plugin(xine_t *xine, void *data);
- This function allocates a plugin class and initializes a set of functions - for the xine engine to invoke. These functions include: -

char *get_identifier(video_decoder_class_t *this);
-
char *get_identifier(audio_decoder_class_t *this);
- This function returns a brief character string identifying the plugin. -

char *get_description(video_decoder_class_t *this);
-
char *get_description(audio_decoder_class_t *this);
- This function returns a slightly longer description of the plugin. -

void dispose_class(video_decoder_class_t *this);
-
void dispose_class(audio_decoder_class_t *this);
- This function frees the resources allocated by the plugin class. -

video_decoder_t *open_plugin(video_decoder_class_t *class_gen, xine_stream_t *stream);
-
audio_decoder_t *open_plugin(audio_decoder_class_t *class_gen, xine_stream_t *stream);
- 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: -

void decode_data(video_decoder_t *this_gen, buf_element_t *buf);
-
void decode_data(audio_decoder_t *this_gen, buf_element_t *buf);
- 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. -

A buffer has a decoder_flags 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). -

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. -

void flush(video_decoder_t *this_gen);
-
void flush(audio_decoder_t *this_gen);
- 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. -

void reset(video_decoder_t *this_gen);
-
void reset(audio_decoder_t *this_gen);
- 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. -

void discontinuity(video_decoder_t *this_gen);
-
void discontinuity(audio_decoder_t *this_gen);
- 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. -

void dispose(video_decoder_t *this_gen);
-
void dispose(audio_decoder_t *this_gen);
- This function frees the resources used by the decoder plugin. -

SPU decoder

A lot written above also applies for subpicture unit (SPU) decoders. The - SPU decoder API is declared in src/xine-engine/spu_decoder.h. - Details on the data, SPU decoders are expected to output, see the section on - overlays and OSD. -

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: -
vpts = metronom->got_spu_packet(metronom, buf->pts);
-

There are also two functions in the SPU decoder API, which have not been discussed above: -

int get_interact_info(spu_decoder_t *this_gen, void *data);
- Since SPUs are sometimes (on DVDs for example) used for user interaction like menu - highlights, this function can be called to get data 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. -

void set_button(spu_decoder_t *this_gen, int32_t button, int32_t mode);
- Also for interaction, you can ask the decoder here to change the - current highlighting. -

Chapter 6. xine's output layer

Video output

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: -

Allocation of vo_frame_t structures and their - subsequent destruction. -
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). -
Most important, the ability to render/copy a given - frame to the output device. -
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). -

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. -

Writing a xine video out plugin

The video out plugin API is declared in src/xine-engine/video_out.h - The plugin info of video out plugins contains the visual type, priority, - and the init_class function of the plugin. -

The visual_type 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 - open_plugin() function as its visual parameter. -

char *get_description(video_driver_class_t *this_gen);
- This function returns a plaintext, one-line string describing the plugin. -

char *get_identifier(video_driver_class_t *this_gen);
- This function returns a shorter identifier describing the plugin. -

void dispose(video_driver_class_t *this_gen);
- This function frees the memory used by the video out plugin class object. -

vo_driver_t *get_instance(video_driver_class_t *class_gen, const void *visual);
- Returns an instance of the plugin. - The visual 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 x11_visual_t, which amongst other things hold the - Display 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. -

uint32_t get_capabilities(vo_driver_t *this_gen);
- Returns a bit mask describing the output plugin's capabilities. - You may logically OR the VO_CAP_* constants together to get - a suitable bit-mask (via the '|' operator). -

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);
- Handle the getting, setting of properties and define their bounds. - Valid property IDs can be found in the video_out.h - header file. -

int gui_data_exchange(vo_driver_t *self, int data_type, void *data);
- 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. -

vo_frame_t *alloc_frame(vo_driver_t *self);
- Returns a pointer to a xine video frame. - Typically the video plugin will add private fields to the end of the - vo_frame_t structure which are used for internal purposes by the plugin. -

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. -

void update_frame_format(vo_driver_t *self, vo_frame_t *img, uint32_t width, uint32_t height, double ratio, int format, int flags);
- 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 base field of the - frame and perform any driver-specific changes. -

void display_frame(vo_driver_t *self, vo_frame_t *vo_img);
- Renders a given frame to the output device. -

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);
- These are used to blend overlays on frames. overlay_begin() is called, - when the overlay appears for the first time, overlay_blend() is then - called for every subsequent frame and overlay_end() is called, when - the overlay should disappear again. -

int redraw_needed(vo_driver_t *self);
- Queries the driver, if the current frame needs to be drawn again. -

void dispose(vo_driver_t *self);
- Releases all resources and frees the plugin. -