+++++++++++++++++++++++++ +++++++++++++++++++++++++
XINE: A Free Video Player
+++++++++++++++++++++++++ +++++++++++++++++++++++++
VERSION
=> $Id: README_en,v 1.10 2004/12/12 21:57:10 mroi Exp $
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>
