+++++++++++++++++++++++++                           +++++++++++++++++++++++++
                           XINE: A Free Video Player       
 +++++++++++++++++++++++++                           +++++++++++++++++++++++++


 INDEX
 -===-
   
   1   THE DOCUMENTATION
   1.1 Scope of this document
   
   2   ABOUT XINE
   2.1 Supported platforms and requirements
   2.2 Used software
   2.3 Developers of xine
   2.4 Usage
   2.4.1 Keyboard shortcuts
   2.4.2 Selecting audio channels
   2.4.3 Selecting subtitles
   2.4.4 LIRC
   2.4.5 Setting xine config-options on the commandline
   
   3   WHAT'S LEFT TO SAY
   3.1 Freedom, DVDs and stuff...
   
   4   Contacting the xine project







1   THE DOCUMENATION

1.1 Scope of this document

    This is the end-user documentation for xine-lib and xine-ui. You'll
    find more documentation in the doc/ directory of both packages.
    
    Please also take a closer look at the FAQ included with the xine-ui
    package which may already have the answers to your questions.


2   ABOUT XINE

    xine is a free GPL-licensed video player for unix-like systems. It
    supports mpeg-2 and mpeg-1 system (audio + video multiplexed) streams,
    mpeg elementary streams (audio/video only, e.g. mp3 files), AVI files
    with various video formats (some of them by using win32 dlls) and Vorbis
    OGG streams. There is some support for quicktime streams (but most
    quicktime video and audio codecs are highly proprietary and thus not
    supported).

    xine plays the video and audio data of the stream and synchronizes
    the playback of both. Depending on the properties of the stream,
    playback will need more or less processor power, full frame rate
    for mpeg-2 has been seen on a 400 MHz P II system.

    xine can play Video CDs, SVCDs and DVDs directly. Unfortunately the
    legal status of encrypted/locked DVD playback is uncertain in some
    countries so xine does not include any DVD unlock/decrypt code. To
    play back such DVDs you'll need external programs or something like a
    xine_dvd_plugin that can handle DVD authentification/descrambling.
    
    The xine project team denies all responsibility for such uses of xine.

    As of xine 0.5 xine's architecture allows for flexible plugins, so
    various other stream types and output devices might be supported in
    the future.

2.1 Supported platforms and requirements

    - xine needs a X11 server for video output
      (8, 15, 16, 24 or 32 bit color depth)
      
    - xine can detect and use the MIT X video and X shared memory extension
      for better playback performance
      
    - if you can't get Xv to run on your platform you should use 16bpp 
      colordepth for speed. Xv seems to work nicely for any color-depth.
      
    - if you have a Matrox G200/G400/G450 graphics adaptor you can optionally
      use the sybcfb/teletux video ouput driver. See README.syncfb for more
      details.
      
    - for audio playback OSS, ALSA, ESD and ARTSD are supported.
    - aaxine uses aalib for output and can run on nearly any terminal
    - to build xine fairly recent GNU make, gcc and binutils are required

    xine should run on any more recent i386-compatible machine (pentium
    and higher) using GNU/linux or FreeBSD. Depending on the type of video
    stream you want to play you will need more or less cpu-power for fluid
    playback. As a rule of thumb, DVDs will typically begin to run nicely
    on a Pentium II 400 system (or equivalent). There are many factors in
    this equation, so your mileage may vary.

    Successfully tested graphic cards (using Xv) for PCs include:
    nVidia Riva TNT (closed-sources nvidia drivers), nVidia Riva TNT 2,
    Matrox G400, ATI AIW Rage128-16MB, 3dfx voodoo3 2000 PCI 16Mb

    The following cards have been reported to work, but it's unclear
    whether they work with Xv or only with XShm (please report on
    xine-user mailing list):
     
     Trident 9660, ATI AIW M64-8Mb PCI, ATI RageII 8MB.

    xine should be able to show video on any type of working xserver with
    any graphics card, but with much worse performance than with Xv.

    Additionally, xine runs on i386-solaris, sparc machines running linux
    or solaris (Creator-3D framebuffer is known to work), see README.solaris
    for more information. Also supported: some powerpc based systems (running
    linux) and IRIX on MIPS.
    
    Last but not least, xine has also been reported to work on Alpha, IA-64
    and S/390 machines. 

2.2 Used software

    xine uses code from the following external free software projects:

     - liba52 by Aaron Holtzman and Michel Lespinasse
     - libmpeg2 by Aaron Holtzman and Michel Lespinasse
     - libmad by Robert Leslie
     - libffmpeg by Fabrice Bellard

    Without these great pieces of software xine would of course not be
    where it is now.

    Also many thanks to the Linux Video and DVD Project "LiViD", where the
    original ideas for the xine video player came from.
     
     => http://www.linuxvideo.org/

2.3 Developers of xine

    main xine programming

      Guenter Bartsch <guenter@users.sourceforge.net>

    various suggestions, bug and build fixes, alsa plugin, gui 

      Daniel Caujolle-Bert <f1rmb@users.sourceforge.net>

    many bug and deadlock fixes, bitrate detection, soft deinterlacer, 
    massive libwin32 updates

      Miguel Freitas <miguel@cetuc.puc-rio.br>

    teletux/syncfb video output module, various bugfixes/reviews, alsa

      Joachim Koenig <Joachim.Koenig@gmx.net>

    liba52/libmpeg2 developement

      Michel Lespinasse <walken@zoy.org>

    Debian package, user support

      Siegfried Langauf <siggi@users.sourceforge.net>

    Plus various other contributors, see the xine-lib/AUTHORS file

2.4 Usage
    
    You can start xine without any command line parameters or you can
    specify one or more input streams directly. xine tries to detect
    whether it can use the Xv extension and will fall back to XShm, but
    that detection might fail. You can specify the video output plugin by
    using the "-V" option, e.g.

     xine -V XShm

    will force xine to use XShm or plain X11. 

    If you want to send the sound over a network with ESD, set the ESPEAKER
    environment variable before starting xine.

    The input stream can be a filename or something we call
    "MediaResourceLocator" (or MRL), which looks similar to a URL. First
    you specify an input source which is followed by "://" and an
    input-source specific identifier. What input sources you can use
    depends on the input plugins you have (for plain files you can omit
    the input-source identifier).

    Try:

     xine --help

    to get more complete information about usage.

    xine supports the xdnd protocol (Version 3) so if you have a file browser 
    application supporting that protocol (e.g. gmc) you can drop video files
    on xine for playback.

    Playing track 3 from a VCD:

     xine vcd://3

    Example for direct DVD access:

     xine dvd://VTS_01_1.VOB


2.4.1 Keyboard shortcuts

      Key             Action

      [RETURN]        play
      [SPACE]         pause
      [Up]/[Down]     fast forward / slow motion

      0-9             enter the corresponding digit
      /               Seek the % relative to the number previously entered
      [Left]/[Right]  seek -+ 15 sec (+CTRL: 60 sec)
      [PgUp]/[Prior]  jump to previous playlist entry
      [PgDown]/[Next] jump to next playlist entry

      f               toggle fullscreen mode
      a               toggle aspect ratio (AUTO/16:9/4:3/DVB)
      i               toggle interlaced mode

      z / Shift-Z     zoom into / out of video
                      add Ctrl to zoom horizontally or Meta to zoom vertically

      "<", ">"        modify output window size
      + -             change audio channel
      , .             change subtitle channel
      n m             adjust a/v sync
      [HOME]          reset a/v sync

      [INSERT]        toggle mouse cursor grabbing in the video output window

      q               quit

      h               hide video window (useful for mp3 playback)

      
      More to come. :-)

      Right click (or press 'g') on the video window to toggle panel
      visibility.

      Changing shortcuts:
        You can also change one/many/all of the shortcuts. For this, you
	should have a keymap in your $HOME/.xine/ directory. The key entry
	syntax is:

         WindowReduce {
            key = less
            modifier = none
         }

        The key should match with X11 key strings (see below). The modifier
	could be:
	         - 'none' for no modifier,
                 - 'control' (or 'ctrl') for the control key,
                 - 'meta' (or 'alt' on PC) for meta key,
                 - 'mod3' or 'mod4' or 'mod5' only available on some platforms.

        Modifiers can be mixed, separated with comma:
	
         WindowReduce {
           key = less
           modifier = control, alt
         }

        If you don't specify a modifier line that's equal to specifying 'none'.

        You can also add alias keystrokes, like:
	 
	 Alias {
           entry = Pause
           key = p
         }

        Meaning you add another key stroke to 'Pause' entry, by pressing 'p',
        you can also add a modifier section (see above). If you don't specify
        it, the modifier will be the same as in the original section ('Pause'
	in this case).

      Tracking X11 key names:
        To know a X11 key string, you could use 'xev', which it's provided 
        with your X11 package. Start 'xev' from a xterm, give focus to the
	small displayed window, and hit the key you want to specify.
      
        Then you will see something like:
	
         ...
         KeyRelease event, serial 27, synthetic NO, window 0x3200001,
         root 0x3c, subw 0x0, time 4144050914, (259,265), root:(272,319),
         state 0x0, keycode 81 (keysym 0xff9a, KP_Prior), same_screen YES,
                                               ^^^^^^^^
					       This is what you're looking for.


        About mouse button, to use your mouse wheel by example, you have
        to track which button will be assigned to a function, using xev:

         ButtonRelease event, serial 27, synthetic NO, window 0x1200001,
         root 0x3b, subw 0x0, time 2710360666, (107,87), root:(120,117),
         state 0x1000, button 5, same_screen YES
                       ^^^^^^^^
                       This is the button

         In this case, you have to set a "key = XButton_5". Modifier key
         is also supported with mouse button handling.
 

      Displaying current/remapped shortcuts:
        You could use 'xine --keymap' or 'xine --keymap=default' to display
        default shortcuts. You can redirect the result to a file, which can
        become a ~/.xine/keymap itself.
	
	To see the result of a remapping, just use 'xine --keymap=remapped'.

2.4.2 Selecting audio channels

      Supply the -a option to select the desired audio track:
       
       xine -a 3 test.mpg

      Plays the third available audio track (and the video, of course).

      Alternatively the gui can be used to select an audio channel.

2.4.3 Selecting subtitles

      Subtitles are embedded in different tracks like audio. In general,
      track 0 is the default language subtitle. Use the -u option to select
      the desired subtitle track:

       xine -u 0 test.vob

      Displays the subtitles from stream 0.

      Alternatively the gui can be used to select a subtitle channel.

2.4.4 LIRC

      xine can be remotely controlled with IR. For this, you should have
      LIRC installed (http://www.lirc.org).

      You should add some entries in your ~/.lircrc, like this:
      
       begin
               remote = SAMSUNG
               button = Button_Play
               prog   = xine
               repeat = 0
               config = Play
       end
       begin
               remote = SAMSUNG
               button = Button_1
               prog   = xine
               repeat = 0
               config = SetPosition10%
       end

      xine can self generate a lirc entries draft, using 'xine --keymap=lirc',
      then you can redirect the output to a file to polish the settings.
      
      Each entry will look like this:

       # Reduce the output window size.
       begin
               remote = xxxxx
               button = xxxxx
               prog   = xine
               repeat = 0
               config = WindowReduce
       end

      It's yours to specify the remote name, and assign the button.

      Playlist:
      ---------
      To Retrieve a playlist from a given input plugin, you can use the
      special 'PlaylistFrom:' keyword, followed by the plugin name (the same
      in the button in the panel window):

       # Retrieve playlist from NAV plugin.
       begin
               remote = xxxxx
               button = xxxxx
               prog   = xine
               repeat = 0
               config = PlaylistFrom:NAV
       end

2.4.5 Setting xine config-options on the commandline

      You can set any option (see README.config_en) from the commandline
      to override the default value in $HOME/.xine/config.

      For example you can do something like

         xine vcd://1 opt:media.vcd.device=/dev/cdrom2 vcd://1

      to change the vcd_device between playing two mrls.

      These opt: settings will not be saved in the configuration file, they
      are only temporary.


3   WHAT'S LEFT TO SAY

3.1 Freedom, DVDs and stuff...

    xine is free software. "free software" is somewhat related to being
    "open-source". However, the meaning of "free software" goes further
    than just that: it is about the freedom of users of software. If you
    have the time, please read what the free software foundation says
    about the topics of freedom and software:
     
     => http://www.gnu.org/philosophy/free-sw.html

    There is a very special threat to freedom when it comes to DVDs: the
    movie industry is making huge efforts to restrict playback of DVDs to
    controlled devices. Most DVDs that are currently sold are encrypted in
    a proprietary way - and in some countries (most notably the USA), it
    is possibly illegal to decrypt them - even for private viewing.
    Hopefully most people will agree that this is a very questionable way
    to treat customers. The xine project team condemns these efforts of
    the movie industry - trying to prevent loss of sales in such a way
    surely shows a lot of disrespect towards all their honest customers.
    On the other hand, the xine project team is against breaking existing
    law. No one knows exactly if it is actually illegal anywhere in the
    world to write, own and use software for viewing encrypted DVDs. But
    as this is an unclear topic (that seems potentially very dangerous),
    xine does not contain any specific code for decrypting DVDs. It seems,
    however, that third parties are working on such extensions. Possibly
    in some places it is legal to use these. Whichever way - you will not
    be able to play encrypted DVDs with xine out-of-the-box. Please note
    that this is not a bug or 'missing feature', but a genuine legal
    problem. It would be great to solve the problem (i.e. convincing
    america and/or the movie industry that they are really annoying and
    unnecessarily unfair to customers as well as users and developers of
    free software), but including code to decrypt DVDs in xine won't solve
    this problem.


4   Contacting the xine project

    the xine project website is

     => http://xine.sourceforge.net

    Feedback or offers for help are greatly appreciated, please contact:

     the xine user mailing list <xine-user@lists.sourceforge.net>