 ++++++++++++++++++++++                                  ++++++++++++++++++++++
                        XINE: FREQUENTLY ASKED QUESTIONS
 ++++++++++++++++++++++                                  ++++++++++++++++++++++


  VERSION
   => $Id: FAQ_en,v 1.4 2002/01/03 21:06:42 matt2000 Exp $


 INDEX
 -===-
 
   1   THE FAQ
   1.1 What's the aim and scope of this text?
   1.2 My question is not yet covered here - where can I ask for help?

   2   GENERAL QUESTIONS
   2.1 What are those xine-lib, xine-ui and xine-plugin modules for?
   2.2 Where and how do I get the latest development version?
   
   3   THE BUILD PROCESS
   3.1 What do I need to compile everything properly?
   3.2 How do I compile xine?
   3.2.1 simple build instructions for beginners
   3.2.2 complete build instructions
   
   3.3 Can I provide additional CFLAGS for compilation?
   3.4 Are there binaries for my K7 available? Can I build them?
   3.5 Build problems: xine-lib.
   3.5.1 The package doesn't compile at all!
   3.5.2 The Xv video-out plugin fails to compile!
   3.6 Build problems: xine-ui.
   3.6.1 I have installed xine-lib but xine-ui complains about not finding it!

   4   INSTALLATION
   4.1 Where should I put the windows codec dlls for xine?

   5   THE PLEASURE OF RUNNING XINE :)   
   
   5.1 GENERAL QUESTIONS
   5.1.1 I have a lot of dropped frames - what can I do?   
   5.1.2 I have problems when using xine on FreeBSD, Solaris!   
   5.1.3 How do I play streams from STDIN?
   5.1.4 How do I change the skin of the xine gui?
   5.1.5 What is aalib? How do I use it in xine?
   5.1.6 What do all these ~/xine/config entries mean?
   5.1.7 How do I use the dvd plugin?
   5.1.8 I have problems setting up my RPC-2 drive for the right region!
   5.1.9 Can xine play (S)VCDs?
   
   5.2 AUDIO RELATED QUESTIONS
   5.2.1 When I play this stream, xine shows video but there's no audio!
   5.2.2 I have trouble with loading ALSA 0.9.x libs! (alsa09 audio plugin)
   5.2.3 What about ALSA 0.5.x?
   5.2.4 Can xine produce 4-/5-channel surround audio output?
   5.2.5 What about ac3 output via spdif to an external ac3 decoder?
   5.2.6 Changing the volume with the GUI control has not affect! What's up!?
   
   5.3 VIDEO RELATED QUESTIONS
   5.3.1 I can hear the audio - but I don't see the picture!
   5.3.2 How can I make xine use the Xv extension and what drivers do I need?
   5.3.3 The xine logo is being displayed but I don't see my video!
   5.3.4 Some parts of my X Desktop get transparent when xine plays the video!
   5.3.5 The aspect ratio of the video is wrong!
   5.3.6 How can I change color/brightness/contrast?

   5.4 ERROR MESSAGES: WHAT THEY MEAN AND WHAT YOU CAN DO.
   5.4.1 Starting xine fails with complains about audio drivers/devices!   
   5.4.2 "no video port found"
   5.4.3 "Unable to open dvd drive (/dev/dvd)"
   5.4.4 "demux error! 00 00 00 (should be 0x000001)"
   5.4.5 "input_dvd: Sorry, xine doesn't play encrypted DVDs. The legal status
          of CSS decryption is unclear and we will not provide such code."
   5.4.6 "audio driver 'oss' failed, using null driver instead"
   
   6   BUGS - GET THAT DAMN VERMIN EXTERMINATOR NOW! ;-)
   6.1 I did the impossible - I really found a bug! Who can I inform about it?











1   THE FAQ

1.1 What's the aim and scope of this text?
    
    The primary goal of this FAQ is to cover all recurring questions related
    to all of the xine modules.

1.2 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. ;-)
    
    That said - you are welcome to mail to our user mailing list.
     
     xine-user@lists.sourceforge.net    


2   GENERAL QUESTIONS

2.1 What are those xine-lib, xine-ui and xine-plugin modules 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 plugins
    and is necessary to run anything that relies on xine.
    
    xine-ui is basically the user interface which makes use of the xine-lib.
    
    xine-plugin will be a general browser plugin that will make it possible to
    watch your favorite Internet streams within your browser with xine.

2.2 Where and how do I get the latest development version?

    Check it out of our CVS:

     cvs -d :pserver:anonymous@cvs.xine.sourceforge.net:/cvsroot/xine login

     <empty password>

     cvs -d :pserver:anonymous@cvs.xine.sourceforge.net:/cvsroot/xine co xine-lib
     cvs -d :pserver:anonymous@cvs.xine.sourceforge.net:/cvsroot/xine co xine-ui
     
     Or you alternatively get daily checkouts as tar archive on our web site.
    

3   THE BUILD PROCESS

3.1 What do I need to compile everything properly?

    First of all an official and stable release of gcc because there seem
    to be still problems with gcc-3.x. Also be aware that patched gcc versions
    may break parts of xine and are therefore not supported by us. (libmpeg2
    will be broken when compiled with pgcc)

    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.

3.2 How do I compile xine?

3.2.1 simple build instructions for beginners

    Download the latest xine-lib and 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
    for all users. You need root privileges to do this on most
    systems.

    first unpack xine-lib, then:
    # ./configure
    # make install

    make sure your /etc/ld.so.conf contains /usr/local/lib, then

    # ldconfig

    now unpack xine-ui, then:
    # ./configure
    # make install

3.2.2 complete build instructions

    The build process is the same for all of the xine modules (see 2.1 for
    an explanation about the modules).

    You have to start with xine-lib. If build and installed successfully, you
    can continue with xine-ui and/or xine-plugin.
    
    Please note that if you have installed xine-lib to a non-standard prefix,
    make sure you have $prefix/bin in your PATH and your linker will find libs
    in $prefix/lib - otherwise the compilation of every module that relies
    on xine-lib will fail with configure complaing 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 xine-ui/xine-plugin/....

    Last but not least. Here the compilation instructions. Like stated earlier,
    those are the same for every xine module.
    
     ./cvscompile.sh [-> only necessary if you checked your sources out of CVS]
     ./configure
     make
     make install

3.3 Can I provide additional CFLAGS for compilation?
    
    Yes, you can do so by setting the GLOBAL_CFLAGS variable and then run
    configure again.

    This can be useful to specify additional include paths or library paths
    to the compiler.
    
    Example: export GLOBAL_CFLAGS="-I/usr/include -L/home/guenter/xine_libs"

3.4 Are there binaries for my K7 available? Can I build them?

    At the moment we do not provide K7 binaries, since the latest stable gcc
    version (2.92.2 at the time of this writing) doesn't have K7 support. Use
    the 686 binaries instead. These binaries should run ok and will use 3DNow!

    If you have a newer 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 setting the xine_BUILD envvar
    explicitly to a valid description string for your configuration, e.g.

     export xine_BUILD=k7-pc-linux-gnu
     rm -f config.cache
     ./cvscompile.sh
     make
     make install

3.5 Build problems: xine-lib.

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

3.5.2 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. If not
      and you only got libXv.a 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.


3.6 Build problems: xine-ui.

3.6.1 I have installed xine-lib but xine-ui complains about not finding it!

      First of all take a closer look at 3.2 again. You will probably find your
      answer there right away.

      Like stated in 3.2 (there again that hint *grin*), make sure that you've
      $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 in earlier (yes, installing xine-lib with "make install"
      would be a great idea to be able to compile xine-ui *grin*).
    
      See question 3.2 for details about how to properly compile and install
      all of the xine modules. But I guess I already mentioned that just a few
      lines before. ;-)


4   INSTALLATION

4.1 Where should I put the windows codec dlls for xine?

    xine uses 
      
     /usr/lib/win32

    by default to search for dlls, but you can change this in your config
    file (located in ~/.xine) by editing:

     codec.win32_path:/usr/lib/win32


5   THE PLEASURE OF RUNNING XINE :)

5.1 GENERAL QUESTIONS

5.1.1 I have a lot of dropped frames - what can I do?

      Your hardware is too slow for xine. Make sure you turn on all
      speed optimizing options. A few things you should check:

       - use a recent kernel optimized for your hardware

       - use the latest gas/gcc

       - close other applications (use a tool like "top" to find out
         what applications are using up CPU power)

       - if you are not using Xv, make sure your display is set up
         to 16bpp, not 24 or higher (reduces memory bandwith)

       - make sure the hard drive which supplies the video data
         is in DMA mode (if supported) 
       
         Under linux, you can use hdparm to check this. 
         Example:

          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
	
         More information about this may be found here:
          => http://oreilly.linux.com/pub/a/linux/2000/06/29/hdparm.html

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

         Please contact Heiko if you have any problems or tips about via apollo
         pro chipset tweaking.

       - a nice performance tuning tool can be found here:

          => http://powertweak.sourceforge.net

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

         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.

       - set up and use raw devices for dvd access

         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/hdc

         then create a link named "rdvd" pointing to that raw device:

          ln -s /dev/raw1 /dev/rdvd

5.1.2 I have problems when using xine on FreeBSD, Solaris!

      Check out the the corresponding README files in the directory:
       
       xine-ui/doc

5.1.3 How do I play streams from STDIN?

      Use something like:
      
       cat stream.mpg | xine stdin://mpeg1

      Or, if you've got an mpeg-2 stream use:
      
       cat stream.vob | xine stdin://mpeg2  

5.1.4 How do I change the skin of the xine gui?

      The easiest way to do this is by selecting your favorite theme with
      the gui itself. In order to do this, start xine and push the control
      button on the panel which opens a menu window (that also contains the
      contrast controller for example). There you will find xine's skin
      chooser. Click your desired skin and your new theme will come into
      affect immediately.
      
      And if you wanna do it the complicated way :), you can also edit the
      appropriate entry in your ~/.xine/config file (gui.skin).

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

      To use it simply make sure you have aalib installed correctly before you
      configure/build xine-lib and xine-ui. Besides the "xine" binary a
      "aaxine" binary should get built and installed, so you can use something
      like:

       aaxine foo.mpg

      to use aalib video output.

5.1.6 What do all these ~/.xine/config entries mean?
     
      You'll find more info about them in xine-ui/doc/README.config_en.

5.1.7 How do I use the dvd plugin?

      First of all:
    
      The dvd plugin delivered with xine currently does not support playback
      of locked and/or encrypted dvds. You will need external programs or
      something like an "improved" xine_dvd_plugin to view these DVDs with xine
      directly. Of course you could play back the decrypted mpeg2 stream
      (technically speaking) that is the movie on the dvd with xine with the
      help of additional programs.
    
      Due to the uncertain legal situation regarding css encryption we do not
      include anything of that nature in the xine distribution, nor do we
      generally endorse the use of such software (you should check if the use
      of such software is legal where you live).
    
      We hope that this situation will change soon.
      
      The easiest way to play an unlocked/unencrypted dvd is, press the DVD
      button on the xine panel and then play. Now everything should work
      out-of-the-box. Please note that for this to work you will not have to
      mount your dvd. You can lean back and enjoy the movie... :-)
      
      Alternatively you can also do all the work by yourself (even though
      unnecessary but if you want to: the user is the king *grin*):

      Please note, if you go this way, you will *not* have seamless branching
      of the dvd movie. You have to play each part of the movie manually. So
      once again: why don't just press the dvd button anyway!? ;-)

      Mount your dvd and check what files are on the disc. There should be
      some files like:
     
       ../VIDEO_TS/VTS_xx_x.VOB, where x are numbers.
     
      If you look for the big .VOB files on a dvd, those are probably the
      ones where the movie is in. To play one of those big files, start xine
      like that:

       xine dvd://VTS_xx_x.VOB

      Make sure you do not supply any path name (no VIDEO_TS/) and use capital
      letters for the file name.

      xine tries to open the dvd using /dev/cdrom. On FreeBSD this will only
      work if you create a symlink to your dvd-devicenode for the time being.

5.1.8 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://linuxtv.org/download/dvd/dvd_disc_20000215_css.tar.gz

      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.

5.1.9 Can xine play (S)VCDs?
     
      Yes, use a MRL like:

       xine VCD://<track number>


5.2 AUDIO RELATED QUESTIONS

5.2.1 When I play this stream, xine shows video but there's no audio!

      This can happen with mpeg-2 material such as DVDs.
      Try another audio channel:

       xine -a channel stream.vob

      (or select the channel by using the gui-buttons)

      Some .vob files have audio on strange channels (e.g. 3, 7, 10).

5.2.2 I have trouble with loading ALSA 0.9.x libs! (alsa09 audio plugin)

      Joel Atyas <smilin@seedling.com> wrote:

       I had a similar problem which turned out to be caused by a feature in
       .xinerc which is still undocumented. So this proposed solution is bound
       to be a wild guess:  Put the lines

        alsa_pcm_device:plughw:0,0
        alsa_ac3_device:plughw:0,2

       somewhere into your ~/.xinerc and try again.

5.2.3 What about ALSA 0.5.x?

      Don't use it. :-)

5.2.4 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 manually activate that feature.
      
      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 .xine:

      # 4-channel:
        audio.four_channel:1
 
      # 5-channel:
        audio.five_channel:1

      # 5.1-channel
        audio.five_lfe_channel:0

5.2.5 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 5.2.4). You can either use the config dialog or edit
      the config file (~/.xine/config) yourself:

        audio.a52_pass_through:1
       
5.2.6 Changing the volume with the GUI control has not affect! What's up!?

      Some xine drivers do not support volume changing although the GUI
      will show the volume bar. Usually this is not a xine fault: aRts C
      API, for example, doesn't offer any volume property to applications.


5.3 VIDEO RELATED QUESTIONS

5.3.1 I can hear the audio - but I don't see a picture!

      Probably your hardware is simply too slow - see question 5.1.1 for some
      tips on how to speed things up.

5.3.2 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 locations to look for suitable drivers:

       CARDS WITH OUT-OF-THE-BOX XV SUPPORT IN XFREE86 4.x:
       
	 3dfx (voodoo)     (URL: ?)
         i815              (URL: ?)
         Matrox G200/G400  (URL: www.matrox.com)
	 NVidia            (URL: www.nvidia.com)
	 Permedia 2/3      (URL: ?)
       
       CARDS WITH YET UNKNOWN STATUS:
       
         ATI cards         (take a look at GATOS: www.linuxvideo.org/gatos/)
         Savage            (URL: www.probo.com/timr/savage40.html)

5.3.3 The xine logo is being displayed but I don't see my video!

      Use the play button of the gui or press RETURN for PLAY. Make sure that
      you really told xine what it should play - for example as a commandline
      argument, such as:

       xine foo-movie.mpg

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

5.3.5 The aspect ratio of the video is wrong!

      Try pressing "a" to toggle the aspect ratio

5.3.6 How can I change color/brightness/contrast?

      At the moment this is only supported on some Xv drivers and with XShm.
      You'll find three entries like these in our ~/.xine/config file for Xv:
       
       video.XV_BRIGHTNESS:0
       video.XV_SATURATION:0
       video.XV_CONTRAST:128

      The values and possible ranges depend on your Xv driver so you'll have
      to experiment a bit to get a good picture.
      
      For XShm, you can change the brightness (gamma correction) by editing
      the following xine config element:

       video.xshm_gamma:0
       
      It has has a range from -100 to +100. Just experiment a bit with it
      until you have your desired brightness.

      Naturally you can also use the specific gui button for this to change
      these video settings interactively. Yet please keep in mind that the gui
      element will only work, if the video-out plugin you are using is also
      supporting brightness, saturation and/or contrast - otherwise you won't
      be able to change the specific setting. (logical, isn't it? *grin*)
      
      (Please also refer to README.config_en for more details about xine's
       config file or use the config dialog accessible through the xine panel)


5.4 ERROR MESSAGES: WHAT THEY MEAN AND WHAT YOU CAN DO.

5.4.1 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 alsa09

      If you run ESD, try:

       xine -A esd

      If you run artsd, try:

       xine -A arts

5.4.2 "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 mpeg-2).

      If all that fails, you can still use plain X11/XShm:

       xine -V XShm foo.vob

      (see also 5.3.2 for more information)

5.4.3 "Unable to open dvd drive (/dev/dvd)"

      You probalby don't have /dev/dvd (check that). If so, simply create a
      link /dev/dvd that points to your DVD device. Something like...

       cd /dev
       ln -s hdc dvd

      ...should do the job.

5.4.4 "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 5.1.7)

      You could use a css-enabled DVD input plugin to avoid this.

      Another reason could be that your (RPC-2) DVD drive isn't set up
      for the right region. (see also 5.1.8)
      
      Recent xine versions will properly check if the DVD you are trying to
      play is encrypted and warn you about it. (see 5.4.5)

5.4.5 "input_dvd: Sorry, xine doesn't play encrypted DVDs. The legal status
       of CSS decryption is unclear and we will not provide such code."
       
      Your DVD is encrypted and thus cannot be played back with xine. Please
      refer to question 5.1.7 and to the general README included with xine for
      more information about this matter.
      
      We are sorry for the inconvenience, yet this is out of our hands. :-(

5.4.6 "audio driver 'oss' failed, using null driver instead"

      First of all, make sure that your OSS Audio drivers are working (ie you
      can play music with other software).

      The most common reason for this 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:

       xine -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:
       
       xine -A arts
      
      Or you suspend the aRts daemon by checking the appropriate option in
      your aRts control. (recommended)


6   BUGS - GET THAT DAMN VERMIN EXTERMINATOR NOW! ;-)

6.1 I did the impossible - I really found a bug! Who can I inform about it?
    
    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*)

    Please take a look at our bug report form which is located in the xine-ui
    package (doc/bug_report_form). Fill it out accordingly and sent it to our
    user mailing list: xine-user@lists.sourceforge.net

    Thanks for taking the time to help improve xine even more!
