Initial revision

CVS patchset: 1
CVS date: 2001/04/18 22:33:39

1 files changed, 335 insertions, 0 deletions

diff --git a/doc/README b/doc/README
new file mode 100644
index 000000000..ff41e9421
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,335 @@
+
+   ----------------------
+            xine
+   ----------------------
+
+     a unix video player
+
+
+
+about xine:
+-----------
+
+xine is a free gpl-licensed video player for unix-like systems.
+We support mpeg-2 and mpeg-1 system (audio + video multiplexed) streams,
+mpg audio files and AVI files (using win32 codec dlls).
+
+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 we cannot include any DVD unlock/decrypt code with xine. To play back
+such DVDs you'll need external programs or something like a
+xine_dvd_plugin that can handle DVD authentification/descrambling.
+
+xine tries to be straightforward and effective. ...no bells and
+whistles are being developed at this time ;-) first we want to achieve
+good playback of video.
+
+
+supported platforms / requirements:
+----------------------------------
+
+- xine needs a locally attached graphics device and monitor (playback over
+  x is not supported at the moment and will probably never be really useful
+  because of the enormous bandwidth of decoded video streams).
+- xine needs either MIT-SHM (The MIT Shared Memory Extension), which is
+  supported in XFree86 for quite some time (3.3.x will be fine),
+  or X-Video Extension (Xv) which is faster and supports fullscreen
+  operation but is only provided by some XFree86 4.x drivers.
+  nVidia chips and Matrox G200 and G400 are known to work.
+- if you can't get Xv to run on your platform you should use 16bpp 
+  colordepth for speed. Xv seems to work nicely for 16 and 24bpp.
+- if you have a mga 200 / 400 graphics adaptor you can optionally
+  use the sybcfb/teletux video ouput driver. See README.syncfb for 
+  details.
+- you need a sound driver that is realtime capable (not all
+  OSS/ALSA drivers support that feature) or ESD
+
+xine has so far been sucessfully used on the following systems:
+
+- Linux on a Pentium III 667
+  using XFree86 4.01 on a nVidia Riva TNT 2
+- Linux on a Pentium II 400
+  using XFree86 3.3.6, 4.0, 4.01 and 4.02 on a nVidia Riva TNT
+- FreeBSD 4.1-Release on a Celeron 400
+  using XFree86 3.3.6 and 4.0.1 on a Matrox G400
+- Linux on a Pentium 120 (no MMX)
+  using XFree86 3.3.5 on a Trident 9660
+- Linux on an AMD K6-266
+  using XFree86 3.3.5 on a ATI AIW M64-8Mb PCI
+- Linux on an AMD K6-III 450
+  using XFree86 3.3.6 on a ATI RageII 8MB
+- Linux on a Celeron 633
+  using XFree86 4.0.1 on a ATI AIW Rage128-16MB
+- Linux on a Amd K7@550
+  using Xfree 4.0.1 on a Ati Rage 128 16 Mb 
+  (Xv is working on this configuration with drivers from GATOS project)
+- Linux on a Celeron 667
+  using XFree86 4.0.2 on a Riva TNT 16Mb 
+  (Xv is working on this configuration with closed-sources drivers
+  version 0.9.5 from NVidia).
+
+Work for non-Intel platforms has started but has not yet reached a 
+working state. 
+
+usage:
+------
+
+You can start xine without any command line parameters or you can 
+specify one or more input streams directly. Xine tries to detect wheter 
+it can use the Xv extension and will fall back to XShm, but that 
+detection might fail.
+If you don't see any video, first check your X11 drivers (for example
+only the binary drivers from nVidia have Xv support for their chips).
+If you can't get Xv to work, use the "-s" option and xine will be
+forced to use Xshm.
+If you get very sloppy video ouput your sound driver may not be
+realtime capable. Try to use ALSA instead or, if you're already using
+ALSA you might want to give OSS a try.
+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" 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 the complete usage.
+
+Unfortunately the gui does not yet support the MRL concept to any
+great extend, so to use any other input source than plain files you'll
+have to use the command line at the moment. That will change soon :-)
+
+Example usage:
+
+$ xine
+
+$ xine /path/foo.vob
+
+$ xine -s /foo/test.mpg
+
+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
+
+Keyboard shortcuts:
+-------------------
+
+Key           action
+
+RETURN        play
+F             toggle fullscreen mode
+Q             quit
+0             jump start of current stream
+1-9           jump to 10-90% of current stream
+SPACE         pause
+PgUp/Prior    jump to previous playlist entry
+PgDown/Next   jump to next playlist entry
+A             toggle aspect ratio (AUTO/16:9/4:3/DVB)
+Ctrl          show/hide mouse cursor
+
+more to come.
+
+Click right on the video window to toggle panel visibility.
+
+selecting audio channels:
+-------------------------
+
+Supply the -a option to select the desired audio track:
+
+xine -a 3 test.mpg
+
+plays the third mpg audio track (and the video, of course).
+
+For mpeg-1, only mpeg audio (layer 1, 2 and 3) is supported.
+
+Mpeg-2 streams can have different types of audio streams, though.
+Xine supports ac3 (dolby digital), mpeg and LPCM sound. These
+are mapped to the following tracks:
+
+Track    selected audio stream
+
+ 0- 7    ac3 stream 0-7
+ 8-15    mpg audio stream 0-7
+16-23    pcm audio stram 0-7
+
+example: to play pcm stream 0 use
+
+xine -a 16 file.vob
+
+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.
+
+controlling xine via CORBA:
+---------------------------
+
+Xine implements a CORBA server interface to enable remote control and
+scripting. For this, you need ORBit which should already be installed if
+you are using GNOME. Otherwise you can get it from
+
+  http://orbit-resource.sourceforge.net/
+
+Any version of ORBit >= 0.4.0 should work fine.
+
+To enable the CORBA interface, you need to supply the "--enable-corba"
+argument to the ./configure script and recompile xine.
+
+The xine server interface definition can be found in "corba/xine.idl" which
+gets installed to "/usr/share/idl/xine.idl" by default.
+
+To communicate with xine via CORBA, you need to get its IOR (Interoperable
+Object Reference). Upon startup, xine writes it to the file ~/.xine.ior
+where you can read it from. If the ORBit name service is running, xine
+also registers itself there under the name "Xine". Unfortunately, the
+ORBit name server is usually not activated by default. You have to run
+it manually like this:
+
+  orbit-name-server >/tmp/name-service-ior &
+
+See the ORBit docs for more information.
+
+Two example client programs are provided:
+  1. "xine-remote" is an example client written in C which can be used to
+     send play/stop/pause commands to a running instance of xine
+  2. "example.py" is a small Python script that demonstrates how to easily
+     control xine from a scripting language
+
+using LIRC with xine:
+---------------------
+
+Xine can be remotly controlled with by IR. For this, you should have
+LIRC installed (http://www.lirc.org), you should get latest CVS snapshot
+if you're running latest Linux kernels (2.2 or 2.4 series). 
+
+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_Src
+	prog   = xine
+	repeat = 0
+	config = DVD
+end
+begin
+	remote = SAMSUNG
+	button = Button_1
+	prog   = xine
+	repeat = 0
+	config = 10%
+end
+...
+
+All valids strings orders are:
+
+ - for quiting:
+      quit
+ - for set the current position in current stream playback:
+      0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90% 
+ - for play or stop:
+      play
+ - for pausing:
+      pause
+ - for eject:
+      eject
+ - for next/previous MRL in the playlist:
+      next, prev
+ - for next/previous audio track selection:
+      audio+, audio-
+ - for next/previous sub-title selection:
+      spu+, spu-
+ - to get the playlist from a DVD/VCD:
+      dvd, vcd
+ - to hide/show the GUI, the output video window:
+      hidegui, hideoutput
+ - to toggle the output video window<->fullscreen
+      fullscr
+
+All of orders are not case sensitive.
+
+used software:
+--------------
+
+xine uses software from the following free software projects:
+
+- libac3 by Aaron Holtzman
+- libmpeg2 by Aaron Holtzman
+- libmpg123 of the mpg123 project by Michael Hipp
+  (see http://www.mpg123.de/)
+
+...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"
+(http://www.linuxvideo.org/), where the original ideas for the xine
+video player came from.
+
+developers of xine:
+-------------------
+
+  main xine developer:
+    Guenter Bartsch
+
+  various suggestions, bug and build fixes, alsa plugin, gui
+    Daniel Caujolle-Bert <f1rmb@users.sourceforge.net>
+
+  audio programming
+    Siegfried Langauf <siggi@users.sourceforge.net>
+
+  contributes great libmpeg2 hacks:
+    Michael Lespinasse
+  
+  ...plus various other contributors, see the AUTHORS file
+
+
+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>
+                                 =================================
+
+
+  If, for some reason, you can't post to the list, you may contact the authors
+  directly:
+
+  Guenter Bartsch <guenter@users.sourceforge.net>
+  Daniel Caujolle-Bert <f1rmb@users.sourceforge.net>
+  Siegfried Langauf <siggi@users.sourceforge.net>
+
+  $Id: README,v 1.1 2001/04/18 22:36:13 f1rmb Exp $